On this page

OCaml Dune in Depth: Libraries vs. Executables vs. Tests, Dependencies

Published on August 3, 2026

Enrico Hochkoeppler Profile

By Enrico Hochkoeppler

Web Developer & TutoriaLibre Founder

Dune organizes a project around three core kinds of buildable components — libraries, executables, and tests — each declared through its own stanza in a dune file. Understanding exactly what separates them, and how each declares its dependencies, is what makes it possible to structure a project that goes beyond a single file with a single purpose.

The library Stanza​

A library is a collection of modules meant to be depended on by other components — other libraries, executables, or tests — rather than run directly on its own.


(library

 (name calculator)

 (libraries str))

name gives the library an identifier usable by other components in the same project; libraries lists that library's own dependencies, using the same field shared across every stanza that can declare dependencies. A library produces no runnable output by itself — its entire purpose is to be consumed by something else that does.

By default, Dune wraps every module inside a library under a single top-level module matching the library's name. A library named calculator containing parser.ml and evaluator.ml exposes them externally as Calculator.Parser and Calculator.Evaluator, even though those files can refer to each other directly, without that extra prefix, from inside the library itself. This wrapping exists specifically to prevent naming collisions: since every top-level module linked into a single executable must have a globally unique name, wrapping each library's modules under one name keeps two different libraries from clashing just because they both happened to define a file called, say, types.ml. Turning this default off is possible but strongly discouraged outside of very specific circumstances, precisely because it reopens the door to exactly the collisions the wrapping is designed to prevent.

The executable Stanza​

An executable produces a runnable binary rather than something meant to be consumed by other components:


(executable

 (name main)

 (libraries calculator))

main.ml, in the same directory as this dune file, becomes the entry point, and (libraries calculator) makes everything the calculator library exposes available to it. Running dune exec ./main.exe, or the more common dune exec <project_name> shorthand, builds and runs the resulting binary in one step.

The essential distinction from a library is directional: an executable can depend on a library, but nothing can depend on an executable — it's a terminal node in a project's dependency graph, not something built to be reused as a building block elsewhere. This is precisely why real projects tend to keep executables deliberately thin, pushing the actual logic into a library instead: logic that lives in a library can be reused by a test suite, by a second executable, or by another project entirely, while logic that lives only inside an executable is permanently stuck there.

The test Stanza​

A test stanza is a convenience wrapper: it builds an executable exactly like the executable stanza does, and additionally wires that executable into Dune's built-in @runtest alias, so it runs automatically as part of dune test (equivalently, dune runtest), rather than needing to be invoked by its own explicit path.


(test

 (name test_calculator)

 (libraries calculator alcotest))

For a project with several separate test executables, the plural tests stanza declares them all at once, sharing common configuration like their library dependencies:


(tests

 (names test_parser test_evaluator)

 (libraries calculator alcotest))

This expands into a separate test executable per name listed, each wired into @runtest the same way a single test stanza would be, without repeating the shared libraries field for every one of them individually.

Declaring Dependencies: The libraries Field​

Every stanza capable of depending on something else — library, executable, and test alike — uses the same (libraries ...) field to declare it. What goes inside that field depends on where the dependency comes from: a library defined elsewhere in the same project is referenced by its plain name, while a library that's part of the installed world — installed through opam, or part of a different, unrelated scope — needs to be referenced by its public_name instead. Dune always prefers a library defined within the current project over an installed one of the same name, if both happen to exist.


(executable

 (name main)

 (libraries calculator str yojson))

Here, calculator is a project-local library referenced by its plain name, while str and yojson are being pulled in as installed dependencies, referenced the same way inside the same field. Version constraints on installed dependencies don't live in the dune file itself — they belong in the dune-project file's package metadata, in a depends field, which is where Dune's package-management tooling checks that a compatible version is actually available before building.

A Small Multi-Component Project, Assembled​

Putting all three stanzas together in one project makes the relationship between them concrete. A calculator project might be laid out with a library holding the actual logic, an executable exposing it as a command-line tool, and a test suite exercising it directly:


(* lib/dune *)

(library

 (name calculator)

 (libraries str))



(* bin/dune *)

(executable

 (name main)

 (libraries calculator))



(* test/dune *)

(test

 (name test_calculator)

 (libraries calculator alcotest))

bin/main.ml depends on calculator purely to expose its functionality as a runnable program; test/test_calculator.ml depends on the exact same calculator library to exercise its functions directly, entirely independent of whether bin/main.ml even exists. Neither the executable nor the test needs to know anything about the other — both simply depend on the one shared library, which is exactly the arrangement that lets the actual logic be tested thoroughly without ever needing to shell out to, or parse the output of, the command-line program built around it.

Key Takeaways​

Found this helpful? Share the knowledge...

... or support this project to keep it alive!

Buy Me a Coffee

Previous

Module Aliasing

Next

OPAM Package Discovery & Installation