Packages¶
Packages are the units that are made installable. Executables
and libraries that have a (public_name)
are installable, and need to be
attached to a package.
How Dune Knows About Packages¶
Packages can be defined in two ways:
If a
pkg.opam
file is found, it signals the existence of thepkg
package to Dune. The contents of the opam file are not interpreted by Dune.In
dune-project
, a(package)
stanza with(name pkg)
defines thepkg
package.
Note
If you want to define public elements but are not interested in publishing
to opam, it is not necessary to write empty *.opam
files. Instead,
prefer declaring it in dune-project
as a (package)
with just a
(name)
.
Generating Opam Files¶
In the latter case, if (generate_opam_files)
is present in
(dune-project)
, Dune will generate pkg.opam
using the metadata in found in (package)
stanzas and global fields such as (source)
.
If a pkg.opam.template
file is found, the fields found in this opam file
are added to the generated file, overriding the generated ones in case of
collision. This can be used as an escape hatch to add arbitrary opam fields.
Note
The template file should be a valid opam file and cannot be generated by a rule (it must be available in the source tree).
What Dune Installs¶
Dune will install the following files:
(library)
stanzas which have a(public_name)
. The package name is the first component of the dot-separated public name:(public_name pkg)
and(public_name pkg.sub)
will look for a package namedpkg
to install their contents.(executable)
and(test)
stanzas with a(public_name)
. The package to install the files in is determined by the(package)
field, which can be omitted if there is only one package.(install)
stanzas provide a low-level mechanism to install arbitrary files.Following the convetions of odig, files named
README*
,CHANGE*
,HISTORY*
andLICENSE*
are installed in the packages defined by opam files in the same directory. These files can be generated by user rules, So for instance, a changelog generated by a user rule will be automatically installed as well.