unikernel/duniverse/dune_/doc/reference/packages.rst

@@ -0,0 +1,57 @@
+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