OCaml Onboarding: Introduction to the Dune build system | OCamlPro
Nos activités commerciales ont déménagé : retrouvez-nous désormais sur titagone.com.
×
Table of contents
A Camleer's basics: Dune
Ressources
Project metadata and build specification files
dune-project
dune file
Key stanzas
Build and run your project
dune build
dune build @doc
dune exec --
Test your project with Dune
Cram tests
dune runtest
Scaffolding with dune init
OCaml Onboarding: Introduction to the Dune build system
Authors: Raja Boujbel, Dario Pinto
Date: 2025-07-29
Category: Trainings
Tags: tutorial, on-boarding, build system, dune, beginner, dev, new project
A camel sitting atop a dune in the middle of the desert. He wears his hard hat as he takes a break from all the building and running of OCaml code. Want to start building your own? Follow the tracks below.
Welcome to all Camleers
We are back with another practical walkthrough for the newcomers of the OCaml<br>ecosystem. We understand from the feedback we have gathered over the years that<br>getting started with the OCaml Distribution can sometimes be perceived as<br>challenging at first. That's why we keep it in mind when planning each post -<br>to make your onboarding smoother and more approachable.
Case in point: today's topic, which came to us during the making of our latest<br>opam deep-dive: Opam 103: Bootstrapping a New OCaml Project with<br>opam.
It occured to us that we were assuming a level of familiarity with the<br>toolchain that we had never explicitly explained or clarified. We decided to<br>put together a short, practical guide for the newer developers, looking for<br>quick, on-the-fly tutorials for OCaml. 🛠️
A Camleer's basics: Dune
If you're new to OCaml, or any other programming language for that matter, the<br>first necessities you'll encounter are building , running , and<br>testing your code. Fortunately, there is a powerful build system called<br>dune that we can use. It is widespread and makes project setup and<br>compilation straightforward. Understanding how dune works is a key step<br>towards becoming productive in the OCaml ecosystem.
In this article, we’ll walk you through the essentials of using dune to<br>build libraries , executables , and tests , and to manage your<br>project structure . Whether you're writing your first OCaml program or<br>stepping into a new dune-based codebase, this guide will help you get up and<br>running quickly.
We strongly believe that starting from scratch is key when approaching a<br>brand new technical topic — and today's topic is no exception. Anyone who<br>has ever felt lost exploring a new codebase knows that minimal, toy examples<br>are often the best way to build intuition.
Table of contents
A Camleer's basics: Dune
Ressources
Project metadata and build specification files
dune-project
dune file
Key stanzas
Build and run your project
dune build
dune build @doc
dune exec --
Test your project with Dune
Cram tests
dune runtest
Scaffolding with dune init
Ressources
As said previously, this article was written in the context of the latest<br>Opam 103: Bootstrapping a New OCaml Project with<br>opam.<br>That article explained how an OCaml developer should go about structuring an<br>OCaml project when they intend to use it with opam.
The point of today's topic is to focus on the other defining parameter of the<br>structure of an OCaml project: your build system. The goal is to show how<br>the workflows of opam and dune fit together, while giving you a solid<br>introduction to the fundamentals of dune.
We're using the same toy<br>project<br>helloer as basis for this rundown. It's a simple, well-scoped example with a<br>structure that's idiomatic to both opam and dune, making it a great fit for<br>illustrating the fundamentals without unnecessary complexity.
Note that helloer was not created using dune init that we will introduce at<br>the end of this article. First, it's important to understand how Dune works<br>under the hood - so you know what it's generating for you, how to modify it<br>confidently, and how it fits into your overall build workflow.
Consider checking Dune's official reference<br>manual or<br>visiting the official OCaml Discuss forum<br>to reach out to the OCaml Community.
Project metadata and build specification files
dune-project
Let's first start with the dune-project file since every Dune-driven<br>project should have one at its root.
This file is the entry point for your project and its contents are its<br>metadata — which Dune uses to understand how your project is structured.
Said metadata includes things like:
the version of dune you're using;
important URLs for your projects lifecycles;
optional settings like dependencies licensing, documentation;
and even configuration for automatic opam file generation.<br>More on that in Opam<br>103 .
This information not only guides Dune, but also helps tools like opam<br>understand how to build, distribute, and document your project.
$ cat dune-project<br>(lang dune 3.15)<br>(package (name helloer))
(cram enable)
Note:...