opam-monorepo

opam-monorepo is an opam plugin designed to assemble standalone Dune workspaces with your projects and all of their dependencies, letting you build it all from scratch using only dune and ocaml.

Documentation on opam-monorepo is available in the repository as well as available online.

Installation

You can simply install it via opam in your current switch by running:

opam install opam-monorepo

Note that once it's installed you can invoke it as an opam command:

opam monorepo <subcommand> ...

Note that opam knows about available plugins and will offer to install opam-monorepo if you try to invoke it without having installed it beforehand.

Usage

The basic usage for opam-monorepo is to start by running the following command from the root of your project:

opam monorepo lock

This will generate a project-wide lock file under <project-name>.opam.locked that contains:

• The full list of your direct and transitive opam dependencies, according to the specifications in the .opam files at your project's root, with hard version constraints ({= <version>) in the depends field.
• A pin-depends field filled with reproducible pins, either to tarballs or to Git repos with an explicit commit hash for all the above dependencies, except for ocaml, dune, and any virtual opam package.
• A few extra fields meant to be interprated by opam monorepo

This lock file can then be consumed by the following command:

opam monorepo pull

which will fetch the sources of all the locked dependencies into a duniverse/ folder at the root of your project, marking them as vendored_dirs (see Dune's documentation) so that Dune will only build the artifacts you need from that folder.

From that point you should be able to run dune build and dune runtest as you normally would and build your entire project from scratch!

The lock Command

It's important to note that opam monorepo lock will only succeed if all of your non-virtual and non "base" dependencies (e.g., ocaml or dune) build with Dune (i.e., directly depend on the dune or jbuilder packages). If that's not the case, the solver will report which packages don't build with dune.

We maintain a separate opam repository with Dune ports of commonly used opam packages. If you have non-Dune dependencies, we advise adding this repository before running opam monorepo lock. You can do so by running the following command:

opam repository add dune-universe git+https://github.com/dune-universe/opam-overlays.git

Note that if it's not setup, the plugin will warn you.

The lock command takes your global and switch's opam configurations into account, meaning any opam repository or pins you set up will be picked up by the solver when resolving the full set of your project's dependencies.

The generated lock file is meant to be compatible with opam in such a way that running

opam install . --locked

should give you the same versions you would using opam monorepo pull in a reproducible way (i.e., independently of any change that might have happened on the upstream opam-repository) thanks to the pin-depends. You can use that property to your advantage by allowing one to choose between a "monorepo" or a regular opam workflow depending on the situation.

You can also exclude packages from the set of packages to be vendored by opam-monorepo. To do so, specify an additional field in your opam file:

x-opam-monorepo-opam-provided: ["ocamlformat" "patdiff"]

This will exclude the packages from the list of packages opam-monorepo will pull, so they can be installed via opam manually.

opam monorepo pull

The pull command fetches the sources using the URLs in the lock file. It benefits from the opam cache but its outcome does not depend on your opam configuration.

Monorepo Projects

If you wish to use opam-monorepo to manage your dependencies, we suggest that you Git version the lock file but not the content of the duniverse/.

If you use ocaml-ci and have an opam-monorepo lock file at the root of your project, it will detect it is an opam-monorepo project and start a specific pipeline. It will use the plugin to assemble a Dune workspace with your dependencies rather than installing them through opam.