There's a handful of mix commands you learn when you get started and it's such a great experience. You can crack open erlang application structure and learn more if you want, but if you just want to `mix compile` `mix deps.get` `mix test` that's also fine.
When I first learned ocaml I watched this really wonderful series https://www.youtube.com/watch?v=MUcka_SvhLw&list=PLre5AT9JnK... (highly recommend if you are at all interested) and it's great for learning the language and tooling but it's all opam up until the end when some of it switches to dune.
I think wanting to provide more details about what's going on is nice too, but I think there's a place for "here's the commands you will actually need in your day to day"
[1] https://github.com/ocaml/ocamlbuild/blob/master/manual/manua...
Date: 2025-07-29
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.
We are back with another practical walkthrough for the newcomers of the OCaml ecosystem. We understand from the feedback we have gathered over the years that getting started with the OCaml Distribution can sometimes be perceived as challenging at first. That's why we keep it in mind when planning each post - to make your onboarding smoother and more approachable.
Case in point: today's topic, which came to us during the making of our latest opam deep-dive: Opam 103: Bootstrapping a New OCaml Project with opam.
It occured to us that we were assuming a level of familiarity with the toolchain that we had never explicitly explained or clarified. We decided to put together a short, practical guide for the newer developers, looking for quick, on-the-fly tutorials for OCaml. π οΈ
If you're new to OCaml, or any other programming language for that matter, the first necessities you'll encounter are building, running, and testing your code. Fortunately, there is a powerful build system called dune that we can use. It is widespread and makes project setup and compilation straightforward. Understanding how dune works is a key step towards becoming productive in the OCaml ecosystem.
In this article, weβll walk you through the essentials of using dune to build libraries, executables, and tests, and to manage your project structure. Whether you're writing your first OCaml program or stepping into a new dune-based codebase, this guide will help you get up and running quickly.
We strongly believe that starting from scratch is key when approaching a brand new technical topic β and today's topic is no exception. Anyone who has ever felt lost exploring a new codebase knows that minimal, toy examples are often the best way to build intuition.
Table of contents
As said previously, this article was written in the context of the latest Opam 103: Bootstrapping a New OCaml Project with opam. That article explained how an OCaml developer should go about structuring an 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 structure of an OCaml project: your build system. The goal is to show how the workflows of opam and dune fit together, while giving you a solid introduction to the fundamentals of dune.
We're using the same toy project helloer as basis for this rundown. It's a simple, well-scoped example with a structure that's idiomatic to both opam and dune, making it a great fit for illustrating the fundamentals without unnecessary complexity.
Note that helloer was not created using dune init that we will introduce at the end of this article. First, it's important to understand how Dune works under the hood - so you know what it's generating for you, how to modify it confidently, and how it fits into your overall build workflow.
Consider checking Dune's official reference manual or visiting the official OCaml Discuss forum to reach out to the OCaml Community.
Let's first start with the dune-project file since every Dune-driven project should have one at its root.
This file is the entry point for your project and its contents are its metadata β which Dune uses to understand how your project is structured.
Said metadata includes things like:
dune you're using;This information not only guides Dune, but also helps tools like opam understand how to build, distribute, and document your project.
$ cat dune-project
(lang dune 3.15)
(package (name helloer))
(cram enable)
Note: The first line must be (lang dune X.Y) - with no comments or extra whitespace. This line determines which features and syntax dune will recognize.
NB: You will find all complementary information in the official docs π.
A dune file is a build specification file that tells Dune how to compile the OCaml code within a specific directory.
Usually there's one dune file per subdirectory, with the description of what's there - library, executable, or some tests. Since our toy helloer project is flat in structure, weβll place this file at the root of the project.
$ cat dune
(library
(name helloer_lib)
(modules helloer_lib)
)
(executable
(public_name helloer)
(name helloer)
(libraries cmdliner helloer_lib)
(modules helloer)
)
(test
(name test)
(libraries alcotest helloer_lib)
(modules test)
)
In effect, this tells dune:
In the context of Dune, a stanza is just a fancy word for a block of configuration. It tells the build system what kind of artifact you want to define β be it a library, an executable, a test, a documentation alias, or even an installable binary. Each stanza lives inside a dune file and follows a structured, declarative syntax.
Theyβre usually grouped by purpose, and each type comes with its own expected fields. Each of these stanzas deserves a deeper dive, but here's a quick overview to get you started.
library stanza(library
(name helloer_lib)
(modules helloer_lib)
)
A
librarystanza tells Dune how to compile a set of modules into a reusable package.
Purpose of this stanza:
helloer_lib;helloer_lib.ml (by default, each .ml file defines a module with the same name);OCaml module names should match the filename, so helloer_lib.ml is expected to exist in this directory.
executable stanza(executable
(public_name helloer)
(name helloer)
(libraries cmdliner helloer_lib)
(modules helloer)
)
An
executablestanza explains how to bundle up some code into a runnable binary.
Purposes:
name: builds an executable named helloer;cmdliner (for CLI parsing) and internal helloer_lib (our own library);public_name helloer: this makes the executable available publicly. It is used for dune install helloer in the opam file for instance.You can learn about how to find and install
cmdlinerinopamin the latest Opam 103 blogpost, you'll find a simple breakdown ofopamfiles there too .
test stanza(test
(name test)
(libraries alcotest helloer_lib)
(modules test)
)
What it does:
test, defined in the file test.ml. A test stanza registers the executable as part of the runtest rule alias, meaning it will be compiled and run automatically when you invoke dune runtest (or its alias dune test);alcotest testing library;helloer_lib to test its functionality.Now your project is setup and structured. Next, letβs see how to build it.
dune buildAs you can see below, the dune build @all command will build all targets defined in your dune files, it's the default behaviour of the dune build command.
$ tree
.
βββ dune
βββ dune-project
βββ helloer_lib.ml
βββ helloer.ml
βββ helloer.opam
βββ test.ml
$ dune build @all
$ tree -L 2
.
βββ _build
β βββ default
β β βββ helloer.exe // executable in its build dir
β β βββ helloer_lib.cmxs // built library
β β βββ test.exe // test executable
β β βββ [...]
β βββ install
β βββ log
βββ dune
βββ dune-project
βββ helloer_lib.ml
βββ helloer.ml
βββ helloer.opam
βββ test.ml
Explanation:
@all is an alias that includes all buildable targets defined in your dune files: executables, libraries, tests, docs, etc;You can also use custom aliases (like @doc, @runtest, etc.), or define your own in your dune files.
dune build @docOnce your code builds and your project has a proper dune-project file, you can generate documentation using:
$ dune build @doc
What it does:
odoc behind the scenes to build API docs from your OCaml code. This implies that installing odoc is mandatory to benefit from this feature, a simple opam install odoc will do just fine;_build/default/_doc/_html/.Make sure your dune-project file includes a (package ...) stanza, and that your libraries are properly documented using OCaml comments (** your comment *).
You can see generate the doc for the toy project here
NB: You will find all complementary information in the official docs π.
After building, you can view the generated docs:
$ open _build/default/_doc/_html/index.html
This is great for checking your module interfaces or publishing documentation online.
dune exec --This command is used to run executables defined in your project.
So, something like:
$ dune exec -- ./helloer.exe
Hello OCamlers!!
$ dune exec -- ./helloer.exe --gentle
Welcome my dear OCamlers.
This tells dune to build the executable if necessary, then run it. The -- separates the dune options from the executable and its arguments. The first item after -- is the executable to run
This can be:
dune exec -- ./path/to/executabledune exec -- ./helloer.All additional arguments after the executable name (like --gentle) are passed to the executable itself.
Essentially, dune exec -- COMMAND behaves the same way as calling dune install first and then COMMAND sequentially.
NB: If you'd like to copy the executable to your project root (outside
_build/), you can add(promote (until-clean))to your executable stanza.
Great, our little project builds and runs smoothly, now onto testing it.
In our helloer project, we use the alcotest library on our internal helloer_lib. This is quite standard. However testing the executable itself can be done without depending on an external tool with the help of cram tests.
Dune supports a special kind of test called a cram test, inspired by the original Cram, which checks that command-line examples produce the expected output.
The "expected output" is the shell-session itself and whatever your executable prints, during its test run for that specific call, is checked against it.
To create a cram test, you just write a .t file that contains a succession of shell-like sessions separated by empty newlines like so:
$ helloer
Hello OCamlers!!
$ helloer --gentle
Welcome my dear OCamlers.
How it works:
.t files;stdout by our binary to the expected output written in the cram file;dune promote whenever you wish to replace all the failed tests with the new output, which will most often happen when you make changes to your binary's printing to stdout.You can test it here.
dune runtestYou can run all your tests using:
$ dune runtest
test targets defined in your project;.t or .ml files marked as tests;ppx_expect or alcotest).It's quite straightforward: if you have an inline_tests stanza or an expect test, it will run them and tell you if anything failed.
For example, a valid cram test will output something like:
$ dune runtest
Testing `Tests'.
This run has ID `N39NJ5ZE'.
[OK] messages 0 normal.
[OK] messages 1 gentle.
Full test results in `~/ocamler/dev/helloer/_build/default/_build/_tests/Tests'.
Test Successful in 0.000s. 2 tests run.
However, if one of these tests were to fail, you would see something like:
$ dune runtest
File "test.t", line 1, characters 0-0:
diff --git a/_build/.sandbox/e6d6dcfb864b62e42104889af2a44f23/default/test.t b/_build/.sandbox/e6d6dcfb864b62e42104889af2a44f23/default/test.t.corrected
index f79b63c..70c7a17 100644
--- a/_build/.sandbox/e6d6dcfb864b62e42104889af2a44f23/default/test.t
+++ b/_build/.sandbox/e6d6dcfb864b62e42104889af2a44f23/default/test.t.corrected
@@ -3,7 +3,7 @@ Default behaviour
Hello OCamlers!!
Gentle behaviour
$ helloer --gentle
- Welcome my deer OCamlers.
+ Welcome my dear OCamlers.
Unknown behaviour
$ helloer --unknown
helloer: unknown option '--unknown'.
File "dune", line 16, characters 7-11:
16 | (name test)
^^^^
Testing `Tests'.
This run has ID `1OS0H3WP'.
[OK] messages 0 normal.
> [FAIL] messages 1 gentle.
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β [FAIL] messages 1 gentle. β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ASSERT same string
FAIL same string
Expected: `"Welcome my deer OCamlers."'
Received: `"Welcome my dear OCamlers."'
Raised at Alcotest_engine__Test.check in file "src/alcotest-engine/test.ml", lines 216-226, characters 4-19
Called from Alcotest_engine__Core.Make.protect_test.(fun) in file "src/alcotest-engine/core.ml", line 186, characters 17-23
Called from Alcotest_engine__Monad.Identity.catch in file "src/alcotest-engine/monad.ml", line 24, characters 31-35
Logs saved to `~/ocamler/dev/helloer/_build/default/_build/_tests/Tests/messages.001.output'.
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Full test results in `~/ocamler/dev/helloer/_build/default/_build/_tests/Tests'.
1 failure! in 0.000s. 2 tests run.
At this point in the development process, we can assume that you know how to use the most basic dune command-lines to make your OCaml projects a reality!
Now that weβve explored how Dune works at a foundational level β writing stanzas by hand, managing libraries and executables, building, running, testing β youβre probably starting to see patterns. These project ingredients donβt change much from one small OCaml project to the next. Thatβs exactly where dune init comes in.
dune init is the starting point for creating a new OCaml project using Dune. It scaffolds a working directory structure and sets up the essential files youβll need.
Rather than writing every file from scratch, Dune offers a command-line scaffolding tool that sets up a complete, minimal project for you β so you can jump straight to writing code with a solid structure already in place.
This means the following command is all you need to scaffold a basic project:
$ dune init project helloer
What it does:
helloer with a working OCaml project inside;The structure you'll get looks like this:
$ tree
helloer/
βββ bin/
β βββ dune
β βββ main.ml
βββ dune-project
βββ lib
β βββ dune
βββ test
β βββ dune
β βββ test_helloer.ml
βββ [...]
From here, you can build on this template by adding libraries, tests, and more.
If your project is only a library or binary, you can use the other project template with
dune init lib helloerordune init exec helloer.
Sharp-eyed readers may notice differences between our toy project and the layout generated by dune init.
You can see the end result in this branch.
Indeed, you should be comfortable with the basic building blocks of a dune-based OCaml project: from initializing it, defining libraries and executables, to running it and writing tests, and even generating documentation. dune takes care of a lot of the heavy lifting, letting you focus on writing code rather than fiddling with build scripts. As you grow more confident with OCaml and Dune, youβll discover even more powerful featuresβbut for now, youβre well-equipped to start building real-world OCaml applications.
About OCamlPro:
OCamlPro is a R&D lab founded in 2011, with the mission to help industrial users benefit from experts with a state-of-the-art knowledge of programming languages theory and practice.
- We provide audit, support, custom developer tools and training for both the most modern languages, such as Rust, Wasm and OCaml, and for legacy languages, such as COBOL or even home-made domain-specific languages;
- We design, create and implement software with great added-value for our clients. High complexity is not a problem for our PhD-level experts. For example, we helped the French Income Tax Administration re-adapt and improve their internally kept M language, we designed a DSL to model and express revenue streams in the Cinema Industry, codename Niagara, and we also developed the prototype of the Tezos proof-of-stake blockchain from 2014 to 2018.
- We have a long history of creating open-source projects, such as the Opam package manager, the LearnOCaml web platform, and contributing to other ones, such as the Flambda optimizing compiler, or the GnuCOBOL compiler.
- We are also experts of Formal Methods, developing tools such as our SMT Solver Alt-Ergo (check our Alt-Ergo Users' Club) and using them to prove safety or security properties of programs.
Please reach out, we'll be delighted to discuss your challenges: contact@ocamlpro.com or book a quick discussion.