Advanced topics¶
This section describes some details of dune for advanced users.
META file generation¶
Dune uses 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
one.
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 META.<package>
file from the META.<package>.template
file by replacing lines of
the form # JBUILDER_GEN
by the contents of the META
it would
normally generate.
For instance if you want to extend the META
file generated by
dune you can write the folliwing META.foo.template
file:
# JBUILDER_GEN
blah = "..."
Findlib integration and limitations¶
Dune uses 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 versionmt_posix
: forces the use of posix threads rather than VM threads. VM threads are deprecated and are likely to go away soonppx_driver
: when a library acts differently depending on whether it is linked as part of a driver or meant to add a-ppx
argument 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 Fl_dynload.load_packages l
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
Cross Compilation¶
Dune allows for cross compilation by defining build contexts with
multiple targets. Targets are specified by adding a targets
field
to the definition of a build context.
targets
takes a list of target name. It can be either:
native
which means using the native tools that can build binaries that run on the machine doing the build- the name of an alternative toolchain
Note that at the moment, there is no official support for cross-compilation in OCaml. Dune supports the opam-cross-x repositories from the ocaml-cross organization on github, such as:
In particular:
- to build Windows binaries using opam-cross-windows, write
windows
in the list of targets - to build Android binaries using opam-cross-android, write
android
in the list of targets - to build IOS binaries using opam-cross-ios, write
ios
in the list of targets
For example, the following workspace file defines three different
targets for the default
build context:
(context (default (targets (native windows android))))
This configuration defines three build contexts:
default
default.windows
default.android
Note that the native
target is always implicitly added when not
present. However, when implicitly added dune build @install
will skip this context, i.e. default
will only be used for
building executables needed by the other contexts.
With such a setup, calling dune build @install
will build all
the packages three times.
Note that instead of writing a dune-workspace
file, you can also
use the -x
command line option. Passing -x foo
to dune
without having a dune-workspace
file is the same as writing the
following dune-workspace
file:
(context (default (targets (foo))))
If you have a dune-workspace
and pass a -x foo
option,
foo
will be added as target of all context stanzas.
How does it work?¶
In such a setup, binaries that need to be built and executed in the
default.windows
or default.android
contexts as part of the
build, will no longer be executed. Instead, all the binaries that will
be executed will come from the default
context. One consequence of
this is that all preprocessing (ppx or otherwise) will be done using
binaries built in the default
context.
To clarify this with an example, let’s assume that you have the following
src/dune
file:
(executable (name foo))
(rule (with-stdout-to blah (run ./foo.exe)))
When building _build/default/src/blah
, dune will resolve ./foo.exe
to
_build/default/src/foo.exe
as expected. However, for
_build/default.windows/src/blah
dune will resolve ./foo.exe
to
_build/default/src/foo.exe
Assuming that the right packages are installed or that your workspace has no external dependencies, dune will be able to cross-compile a given package without doing anything special.
Some packages might still have to be updated to support cross-compilation. For
instance if the foo.exe
program in the previous example was using
Sys.os_type
, it should instead take it as a command line argument:
(rule (with-stdout-to blah (run ./foo.exe -os-type %{os_type})))
Classical ppx¶
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.