57 lines
2.3 KiB
ReStructuredText
57 lines
2.3 KiB
ReStructuredText
Packages
|
|
========
|
|
|
|
:term:`Packages <package>` 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 the ``pkg``
|
|
package to Dune. The contents of the opam file are not interpreted by Dune.
|
|
- In ``dune-project``, a ``(package)`` stanza with ``(name pkg)`` defines the
|
|
``pkg`` 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)``.
|
|
|
|
.. seealso:: :doc:`../howto/opam-file-generation`
|
|
|
|
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.
|
|
|
|
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 named ``pkg`` 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.
|
|
|
|
.. _odig: https://erratique.ch/software/odig
|