.. _install:

install
-------

Dune supports installing packages on the system, i.e., copying freshly built
artifacts from the workspace to the system. The ``install`` stanza takes three
pieces of information:

- The list of files to install.
- The package to attach these files. This field is optional if your project
  contains a single package.
- The section in which the files will be installed.

For instance:

.. code::

   (install
    (files hello.txt)
    (section share)
    (package mypackage))

Indicate that the file ``hello.txt`` in the current directory is to be installed
in ``<prefix>/share/mypackage``.

The following sections are available:

.. list-table::
   :header-rows: 1

   * - Section
     - Target
     - Remarks
   * - ``lib``
     - ``<prefix>/lib/<pkgname>/``
     -
   * - ``lib_root``
     - ``<prefix>/lib/``
     -
   * - ``libexec``
     - ``<prefix>/lib/<pkgname>/``
     - executable bit is set
   * - ``libexec_root``
     - ``<prefix>/lib/``
     - executable bit is set
   * - ``bin``
     - ``<prefix>/bin/``
     - executable bit is set
   * - ``sbin``
     - ``<prefix>/sbin/``
     - executable bit is set
   * - ``toplevel``
     - ``<prefix>/lib/toplevel/``
     -
   * - ``share``
     - ``<prefix>/share/<pkgname>/``
     -
   * - ``share_root``
     - ``<prefix>/share/``
     -
   * - ``etc``
     - ``<prefix>/etc/<pkgname>/``
     -
   * - ``stublibs``
     - ``<prefix>/lib/stublibs/``
     - executable bit is set
   * - ``doc``
     - ``<prefix>/doc/<pkgname>/``
     -
   * - ``man``
     - ``<prefix>/man/manX/``
     - (see below)
   * - ``misc``
     - absolute destination
     - (see below)
   * - ``(site (<package> <site>))``
     - ``<site>`` directory of ``<package>``
     - (see below)

Additional remarks:

- For ``man``, the exact destination is inferred from the file extension. For
  example, ``foo.1`` is installed as ``<prefix>/man/man1/foo.1``.
- ``misc`` only works when using opam. In that case, the user will be prompted
  before installation. This mechanism is deprecated.
- In the case of ``(site)``, if the prefix isn't the same as the one used when installing ``<package>``, ``<package>`` won't find the files.

Normally, Dune uses the file's basename to determine the file's name once
installed; however, you can change that by using the form ``(<filename> as
<destination>)`` in the ``files`` field. For instance, to install a file
``mylib.el`` as ``<prefix>/emacs/site-lisp/mylib.el``, you must write the
following:

.. code:: scheme

    (install
     (section share_root)
     (files   (mylib.el as emacs/site-lisp/mylib.el)))

The mode of installed files is fully determined by the section they are
installed in. If the section above is documented as with the executable bit
set, they are installed with mode ``0o755`` (``rwxr-xr-x``); otherwise they are
installed with mode ``0o644`` (``rw-r--r--``).

Note that all files in the install stanza must be specified by relative paths
only. It is an error to specify files by absolute paths.

Including Files in the Install Stanza
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can include external files from the ``files`` and ``dirs`` fields of the
install stanza:

.. code:: scheme

    (install
     (files (include foo.sexp))
     (section share))

Here the file ``foo.sexp`` must contain a single S-expression list, whose
elements will be included in the list of files or directories to install. That
is, elements may be of the form:

- ``<filename>``
- ``(<filename> as <destination>)``
- ``(include <filename>)``

Included files may be generated by rules. Here is an example of a rule which
generates a file by listing all the files in a subdirectory ``resources``:

.. code:: scheme

    (rule
     (deps (source_tree resources))
     (action
      (with-stdout-to foo.sexp
      (system "echo '(' resources/* ')'"))))

Globs in the Install Stanza
~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can use globs to specify files to install by using the terms ``(glob_files
<glob>)`` and ``(glob_files_rec <glob>)`` inside the ``files`` field of the
install stanza (but not inside the ``dirs`` field). See the :ref:`glob <glob>`
for details of the glob syntax. The ``(glob_files <glob>)`` term will expand its
argument within a single directory, whereas the ``(glob_files_rec <glob>)`` term
will recursively expand its argument within all subdirectories.

For example:

.. code:: scheme

    (install
     (files (glob_files style/*.css) (glob_files_rec content/*.html))
     (section share))

This example will install:

- All files matching ``*.css`` in the ``style`` directory.

- All files matching ``*.html`` in the ``content`` directory, or any of its
  descendant subdirectories.

Note that the paths to files are preserved after installation. Suppose the
source directory contained the files ``style/foo.css`` and
``content/bar/baz.html``. The example above will place these files in
``share/<package>/style/foo.css`` and ``share/<package>/content/bar/baz.html``
respectively.

Handling of the .exe Extension on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Under Microsoft Windows, executables must be suffixed with ``.exe``. Dune tries
to ensure that executables are always installed with this extension on Windows.

More precisely, when installing a file via an ``(install ...)`` stanza, Dune
implicitly adds the ``.exe`` extension to the destination, if the source file
has extension ``.exe`` or ``.bc`` and if it's not already present
