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 ``<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 :doc:`package management
  <../explanation/package-management>` is :doc:`enabled <config/pkg>`.

- In ``dune-project``, a :doc:`(package) <dune-project/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 :doc:`(package)
   <dune-project/package>` with just a ``(name)``.

Generating Opam Files
---------------------

In the latter case, if :doc:`(generate_opam_files)
<dune-project/generate_opam_files>` is present in ``(dune-project)``, Dune will
generate ``<package-name>.opam`` using the metadata in found in :doc:`(package)
<dune-project/package>` stanzas and global fields such as ``(source)``.

.. seealso:: :doc:`../howto/opam-file-generation`

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.

.. seealso:: :doc:`dune-project/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.

.. _odig: https://erratique.ch/software/odig
