Documentation and guides

Building and packaging with jbuilder and topkg

Packaging with jbuilder and topkg

This post describes the current state-of-the-art in building and releasing Mirage libraries with jbuilder (to build) and topkg (to release).


We wish to

The tools

We make heavy use of the following tools:

Internally we make heavy use of ocamlfind but this is wrapped by jbuilder and opam.


We adopt the following conventions:

Package structure

A Mirage library should have

Developing changes

It should be sufficient to

and then

Releasing changes

Mirage releases are published via github. First log into your account and create a github API token if you haven't already. Store it in a file (e.g. ~/.github/token). If on a multi-user machine, ensure the privileges are set to prevent other users from reading it.

Before releasing anything it's a good idea to review the outstanding issues. Perhaps some can be closed already? Maybe a entry is missing?

When ready to go, create a branch from master and edit the file to list the interesting changes made since the last release. Make a PR for this update. The CI will run which is a useful final check that the code still builds and the tests still pass. (It's ok to skip this if the CI was working fine a few moments ago when you merged another PR).

When the PR is merged, pull it into your local master branch.

Read topkg help release to have an overview of the full release workflow. You need to install odoc, topkg-jbuilder and opam-publish to be installed. Run opam-publish once to generate a release token.


topkg tag

-- topkg will extract the latest version from the file, perform version substitutions and create a local tag.


topkg distrib

-- topkg will create a release tarball.

Install odoc, topkg-jbuilder Type:

topkg publish

-- topkg will push the tag, create a release and upload the release tarball. It will also build the docs and push them online.

If you have the multi-package release rules in your Makefile, and assumning that you have a clone on ocaml/opam-repository in ../opam-repository, you can then type:

make opam-pkg

-- this will add new files in your opam-repository clone. git commit and push them to your fork on GitHub and open a new pull-request.

If you only have one package in your repository, you can simply write:

topkg tag && topk bistro