By Dave Scott - 2017-05-22
This post describes the current state-of-the-art in building and releasing MirageOS packages with dune (to build) and dune-release (to release).
Please note that some packages are still using ocamlbuild
and topkg
, install
topkg-care
and replace dune-release
with topkg
below.
We wish to
We make heavy use of the following tools:
make
) which knows how to build OCaml code
incrementally and really quickly.We adopt the following conventions:
v
to easily distinguish concreate releases (v1.2.3
) from release branches (1.2
)depopts
to specify sub-libraries. Instead we create
multiple opam
packages via multiple <name>.opam
files in the same repo.
See rgrinberg's
post for a rationaleocamlfind
package and the opam
package. This is to avoid misunderstandings over whether you need to type mirage-types.lwt
or mirage-types-lwt
in the current context.CHANGES.md
entries in the same style, to ensure they are parseable
by dune-release
A MirageOS library should have
CHANGES.md
: containing a log of user-visible changes in each release.
For example consider mirage-tcpip CHANGES.md:
it has a markdown ###
prefix before each release version and the date in
(YYYY-MM-DD)
form.LICENSE.md
: describing the conditions under which the code can be used
(the MirageOS standard license is ISC).
For example mirage-tcpip LICENSE.md.README.md
: describing what the code is for and linking to examples, docs,
continuous integration (CI) status. For example mirage-tcpip.3.7.1.<name>.opam
file per opam package defined in the repo.
For example mirage-block.1.2.0
and mirage-block-lwt.1.2.0.
These should have a github pages doc:
link in order that dune-release
can detect
the upstream repo.Makefile
: contains dune
invocations.
For example mirage-block.1.2.0dune
files: these describe how to build the libraries, executables
and tests of your project.
For example mirage-block-unix.2.11.0/lib/dune
links the main library against OCaml and C,
while mirage-block-unix.2.11.0/lib_test/dune
defines 2 executables and associates one with an alias runtest
, triggered by
make test
in the root.It should be sufficient to
git clone
the repoopam install --deps-only <name>
: to install any required dependenciesand then
make
: to perform an incremental buildmake test
: to compile and execute testsdune utop
: to launch an interactive top-levelMirageOS 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. ~/.config/dune/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 CHANGES.md
entry is missing?
When ready to go, create a branch from master
and edit the CHANGES.md
file
to list the interesting changes made since the last release. Make a pull request (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). If you include [ci skip]
in your commit message, the CI will not be run.
When the CHANGES.md
PR is merged, pull it into your local master
branch.
Read dune-release help release
to have an overview of the full release workflow.
You need to have odoc
installed to generate the documentation.
Type:
dune-release tag
-- dune-release will extract the latest version from the CHANGES.md
file, perform
version substitutions and create a local tag.
Type:
dune-release distrib
-- dune-release will create a release tarball.
Install odoc
and type:
dune-release publish --dry-run
-- dune-release will build the documentation (fix all the warnings).
Type:
dune-release publish
-- dune-release will push the tag, create a release and upload the release tarball. It will also build the docs and push them online.
Type
dune-release opam pkg
dune-release opam submit
-- 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.
You can simply write:
dune-release tag && dune-release
-- this will do the above steps (distrib, publish, opam pkg, opam submit).