opam packages, documentation and CI

On your laptop the ledger library builds, tests pass and the ledger total prints 162500. A teammate clones the same commit on their machine, runs dune build and gets Error: Library "alcotest" not found; the documentation page is missing too. Nothing is wrong with the code: the project only lives in your switch.

Packaging turns the project into something another machine can install the same way every time. A dune-generated opam fileopam file: The text file that defines an opam package, usually <name>.opam. Dune can generate it from a (package ...) stanza in dune-project when (generate_opam_files true) is set. names the dependencies, a project-local switchopam switch: One OCaml compiler together with its own set of installed packages, kept apart from every other switch; global switches live in the opam root and local ones in a project's _opam folder. More in “Install OCaml 5.5.1 with opam and use the REPL” holds its own copies of them, odocodoc: OCaml's documentation generator. It reads doc comments written with (** ... *) above declarations and renders HTML, LaTeX or man pages, usually driven by dune build @doc. renders the (** ... *) comments, and a continuous-integrationcontinuous integration: The practice of running the build and tests on a shared server on every push, so a change that works only on its author's machine is caught before it reaches the main branch. job runs the same build on every push.

A dune-project becomes an opam file other machines read

An opam packageopam package: A unit that opam installs. Each is defined by one .opam file, which names the package, its version, its dependencies and the commands opam runs to build and install it. is defined by an opam-version: "2.0" text file. All opam packages, dune and the compiler included, are described by such a file in the opam repository. You could write it by hand, as the opam manual shows, but a dune project already lists its name, source, licence and dependencies, so dune can write the file for you. Add a (package ...) stanza to dune-project and set (generate_opam_files true), then dune build @install writes a pkg.opam.generated and dune promote moves it over the checked-in file. The generated file begins with # This file is generated by dune, edit dune-project instead, which tells teammates (and you, next week) where to make changes:

from session import files, run

# A dune-project with (package ...) and (generate_opam_files true) is enough: dune build writes ledger.opam. The
# session copies in the lesson's four files, builds once, then shows the generated opam file.
files(
    "ledger/dune-project=dune-project",
    "ledger/lib/dune=lib/dune",
    "ledger/lib/ledger.ml=lib/ledger.ml",
    "ledger/lib/ledger.mli=lib/ledger.mli",
    "ledger/bin/dune=bin/dune",
    "ledger/bin/main.ml=bin/main.ml",
    "ledger/test/dune=test/dune",
    "ledger/test/test_ledger.ml=test/test_ledger.ml",
)
run(
    """
ls dune-project lib bin test
cat dune-project
! dune build @install
dune promote
ls *.opam
cat ledger.opam
""",
)

$ ls dune-project lib bin test
dune-project

bin:
dune
main.ml

lib:
dune
ledger.ml
ledger.mli

test:
dune
test_ledger.ml
$ cat dune-project
(lang dune 3.24)

(name ledger)

(generate_opam_files true)

(source
 (github example/ledger))

(authors "Asha Rao")

(maintainers "asha@example.com")

(license MIT)

(package
 (name ledger)
 (synopsis "A tiny ledger for teaching package publishing")
 (description
  "A one-library package that adds up amounts in the smallest unit of a currency and prints a total.")
 (depends
  (ocaml
   (>= 4.14))
  (alcotest
   (and
    (>= 1.6.0)
    :with-test))))
$  dune build @install
File "ledger.opam", line 1, characters 0-0:
diff --git a/_build/default/ledger.opam.generated b/_build/default/ledger.opam.generated
new file mode 100644
index 0000000..7c4292e
--- /dev/null
+++ b/_build/default/ledger.opam.generated
@@ -0,0 +1,32 @@
+# This file is generated by dune, edit dune-project instead
+opam-version: "2.0"
+synopsis: "A tiny ledger for teaching package publishing"
+description:
+  "A one-library package that adds up amounts in the smallest unit of a currency and prints a total."
+maintainer: ["asha@example.com"]
+authors: ["Asha Rao"]
+license: "MIT"
+homepage: "https://github.com/example/ledger"
+bug-reports: "https://github.com/example/ledger/issues"
+depends: [
+  "dune" {>= "3.24"}
+  "ocaml" {>= "4.14"}
+  "alcotest" {>= "1.6.0" & with-test}
+  "odoc" {with-doc}
+]
+build: [
+  ["dune" "subst"] {dev}
+  [
+    "dune"
+    "build"
+    "-p"
+    name
+    "-j"
+    jobs
+    "@install"
+    "@runtest" {with-test}
+    "@doc" {with-doc}
+  ]
+]
+dev-repo: "git+https://github.com/example/ledger.git"
+x-maintenance-intent: ["(latest)"]
[exit status 1]
$ dune promote
Promoting _build/default/ledger.opam.generated to ledger.opam.
$ ls *.opam
ledger.opam
$ cat ledger.opam
# This file is generated by dune, edit dune-project instead
opam-version: "2.0"
synopsis: "A tiny ledger for teaching package publishing"
description:
  "A one-library package that adds up amounts in the smallest unit of a currency and prints a total."
maintainer: ["asha@example.com"]
authors: ["Asha Rao"]
license: "MIT"
homepage: "https://github.com/example/ledger"
bug-reports: "https://github.com/example/ledger/issues"
depends: [
  "dune" {>= "3.24"}
  "ocaml" {>= "4.14"}
  "alcotest" {>= "1.6.0" & with-test}
  "odoc" {with-doc}
]
build: [
  ["dune" "subst"] {dev}
  [
    "dune"
    "build"
    "-p"
    name
    "-j"
    jobs
    "@install"
    "@runtest" {with-test}
    "@doc" {with-doc}
  ]
]
dev-repo: "git+https://github.com/example/ledger.git"
x-maintenance-intent: ["(latest)"]

The 32-line ledger.opam lists every dependency with its constraint ("dune" {>= "3.24"}, "ocaml" {>= "4.14"}, "alcotest" {>= "1.6.0" & with-test}), the build command that opam will run and the version-controlled source URL. Every opam install anywhere reads one of these files, so writing it from one place removes the drift that hand-maintained metadata always grows.

A project-local switch holds its own dependencies, and opam installs them from the file

A new project runs opam switch create . 5.5.1 --no-install, which makes a project-local switch inside _opam/ with its own OCaml 5.5.1 and no other packages. Then opam install . --deps-only --with-test reads ledger.opam and installs exactly what the project declares, into _opam/ only. Delete _opam/ and the same two commands rebuild it from the file, with whatever versions opam picks that day.

A lockfilelockfile: A file that records the exact version of every direct and transitive dependency a project installs, so another machine installs the same set. opam writes it with opam lock . narrows that further: opam lock . writes ledger.opam.locked with every transitive package pinned to the exact version in your switch, and opam install . --locked installs from it. The dune package manager has an experimental dune pkg lock command for the same idea, but its tutorial warns that it “is not final yet and details are still subject to change”, so this track uses opam.

Documentation and continuous integration finish the package

odoc 3.2.1 reads the (** ... *) doc comments in your .ml and .mli files and renders them as HTML documentation. dune build @doc writes the pages under _build/default/_doc/_html/, and the doc build of this project is recorded further down. Documentation that builds without odoc warnings lets a teammate read the API without opening every file.

A continuous-integration workflow in .github/workflows/ci.yml uses ocaml/setup-ocaml@v3, the official OCaml action, to install opam and the compiler, then runs the same opam install . --deps-only --with-test, dune build, dune runtest and dune build @doc on every push. CI catches a change that works in your switch but not in a fresh one; the workflow file itself appears further down. Publishing a release is one more step: tag a version, then opam-publish or dune-release bistro opens a pull request against the ocaml/opam-repository, where the opam packages that everyone installs are kept, with your new version’s opam file.

Practise: write the opam file and read it back

The questions use the ledger project from the lesson above. The weakest idea comes first, and every wrong choice names the misunderstanding behind it.

odoc documentation and a GitHub Actions build that stays green Pro: opens with a Pro, Premium or Ultimate pass

Reproducible dependencies, and why a PPX can block a release Pro: opens with a Pro, Premium or Ultimate pass

Interview questions

Warm-up (fresher to 2–5 years): what does (generate_opam_files true) in dune-project do, and why is editing the generated file a mistake?

With (generate_opam_files true) and a (package ...) stanza, dune build @install writes <pkg>.opam.generated into _build; dune promote applies the diff, so the checked-in <pkg>.opam matches your dune metadata. The generated file carries a comment on its first line, # This file is generated by dune, edit dune-project instead, which is the reminder that the opam file is a derived artefact. If you edit it, the next build overwrites your change. The source of truth is dune-project: dependencies belong in the (depends ...) field of the package stanza, synopsis and description in their own fields, authors and licence at the top level. Keeping the two in step is a single-source-of-truth property: there is only one place to change.

Three deeper questions follow: reproducing a build on a new machine, a dependency that will not install on your compiler, and what a workflow should run for an OCaml library. Say your first move for each before you open its follow-ups:

Key takeaways

• A (package ...) stanza with (generate_opam_files true) makes dune write the opam file; the first line reminds you to edit dune-project, not the generated copy.
• A project-local switch and opam install . --deps-only reproduce a build; opam lock . pins every transitive version in a committed ledger.opam.locked.
• dune build @doc renders every (** ... *) comment to HTML under _build/default/_doc/_html/, offline, so docs are not a separate build step.
• A GitHub Actions workflow using ocaml/setup-ocaml@v3 runs the same install, build, test and doc commands on every push, so a change that only works in your own switch fails where everyone can see it.