This section describes some details of dune for advanced users.
META file generation¶
META files from the findlib library
manager in order
to interoperate with the rest of the world when installing libraries. It
is able to generate them automatically. However, for the rare cases
where you would need a specific
META file, or to ease the transition
of a project to dune, it is allowed to write/generate a specific
In order to do that, write or setup a rule to generate a
META.<package>.template file in the same directory as the
<package>.opam file. Dune will generate a
file from the
META.<package>.template file by replacing lines of
# DUNE_GEN by the contents of the
META it would
For instance if you want to extend the
META file generated by
dune you can write the following
# DUNE_GEN blah = "..."
META files to support external libraries. However, it
doesn’t export the full power of findlib to the user, and especially
it doesn’t let the user specify predicates.
The reason for this limitation is that so far they haven’t been
needed, and adding full support for them would complicate things quite
a lot. In particular, complex
META files are often hand-written and
the various features they offer are only available once the package is
installed, which goes against the root ideas dune is built on.
In practice, dune interprets
META files assuming the following
set of predicates:
mt: what this means is that using a library that can be used with or without threads with dune will force the threaded version
mt_posix: forces the use of posix threads rather than VM threads. VM threads are deprecated and are likely to go away soon
ppx_driver: when a library acts differently depending on whether it is linked as part of a driver or meant to add a
-ppxargument to the compiler, choose the former behavior
Dynamic loading of packages¶
Dune supports the
findlib.dynload package from findlib that allows to
dynamically load packages and their dependencies (using OCaml Dynlink module).
So adding the ability for an application to have plugins just requires to add
findlib.dynload to the set of library dependencies:
(library (name mytool) (public_name mytool) (modules ...) ) (executable (name main) (public_name mytool) (libraries mytool findlib.dynload) (modules ...) )
Then you could use in your application
that will load the list
l of packages. The packages are loaded
only once. So trying to load a package statically linked does nothing.
A plugin creator just need to link to your library:
(library (name mytool_plugin_a) (public_name mytool-plugin-a) (libraries mytool) )
By choosing some naming convention, for example all the plugins of
mytool should start with
mytool-plugin-. You can automatically
load all the plugins installed for your tool by listing the existing packages:
let () = Findlib.init () let () = let pkgs = Fl_package_base.list_packages () in let pkgs = List.filter (fun pkg -> 14 <= String.length pkg && String.sub pkg 0 14 = "mytool-plugin-") pkgs in Fl_dynload.load_packages pkgs
classical ppx refers to running ppx using the -ppx compiler option, which is composed using Findlib. Even though this is useful to run some (usually old) ppx’s which don’t support drivers, dune does not support preprocessing with ppx this way. but a workaround exists using the ppxfind tool.
--trace-file FILE is passed, dune will write detailed data about internal
operations, such as the timing of commands that are run by dune.
The format is compatible with Catapult trace-viewer. In particular, these
files can be loaded into Chromium’s
chrome://tracing. Note that the exact
format is subject to change between versions.
Dune determine the version of a package by looking at the
field in the package stanza. If the version field is
not set, it looks at the toplevel
version field in the
dune-project field. If neither are set, dune assume that we are in
development mode and reads the version from the VCS if any. The way it
obtains the version from the VCS in described in the build-info
When installing the files of a package on the system, dune
automatically inserts the package version into various metadata files
dune file starts with
(* -*- tuareg -*- *), then it is
interpreted as an OCaml script that generates the
dune file as described
in the rest of this section. The code in the script will have access to a
module containing details about the build context it is executed in.
The OCaml syntax gives you an escape hatch for when the S-expression
syntax is not enough. It is not clear whether the OCaml syntax will be
supported in the long term as it doesn’t work well with incremental
builds. It is possible that it will be replaced by just an
stanza where one can include a generated file.
Consequently you must not build complex systems based on it.