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 <package-name>.opam file is found, it signals the existence of the <package-name> package to Dune. The contents of the opam file are not interpreted by Dune, unless package management is enabled.

  • In dune-project, a (package) stanza with (name <package-name>) defines the <package-name> 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 <package-name>.opam using the metadata in found in (package) stanzas and global fields such as (source).

See also

How to Generate Opam Files from dune-project

If a <package-name>.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.

See also

package for fields supported by dune-project

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 <package-name>) and (public_name <package-name>.sub) will look for a package named <package-name> 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 conventions of odig, files named README*, CHANGE*, HISTORY* and LICENSE* 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.