unikernel/duniverse/dune_/doc/reference/dune/install.rst

@@ -0,0 +1,286 @@
+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 or directories 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:: dune
+
+    (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.
+
+Also note that as of dune-lang 3.11 (i.e., ``(lang dune 3.11)`` in
+``dune-project``) it is deprecated to use the ``as`` keyword to specify a
+destination beginning with ``..``. Dune intends for files associated with a
+package to only be installed under specific directories in the file system
+implied by the installation section (e.g., ``share``, ``bin``, ``doc``, etc.)
+and the package name. Starting destination paths with ``..`` allows packages to
+install files to arbitrary locations on the file system. In 3.11, this behaviour
+is still supported (as some projects may depend on it) but will generate a
+warning and will be removed in a future version of Dune.
+
+.. _including-files-install-stanza:
+
+Including Files in the Install Stanza
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can include external files from the ``files`` and ``dirs`` fields of the
+install stanza:
+
+.. code:: dune
+
+    (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:: dune
+
+    (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:: dune
+
+    (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 where ``<package>`` is the name of the package (ie.
+``dune-project`` would contain ``(package (name <package>))``).
+
+The ``with_prefix`` keyword can be used to change the destination path of files
+matched by a glob, similar to the ``as`` keyword in the ``(files ...)`` field.
+``with_prefix`` changes the prefix of a path before the component matched by the
+``*`` to some new value. For example:
+
+.. code:: dune
+
+    (install
+     (files
+      (glob_files (style/*.css with_prefix web/stylesheets))
+      (glob_files_rec (content/*.html with_prefix web/documents)))
+     (section share))
+
+Continuing the example above, this would result in the source file at
+``style/foo.css`` being installed to ``share/<package>/web/stylesheets/foo.css``
+and ``content/bar/baz.html`` being installed to
+``share/<package>/web/documents/bar/baz.html``. Note in the latter case
+``with_prefix`` only replaced the ``content`` component of the path and not the
+``bar`` component since it replaces the prefix of the glob - not the prefix
+of paths matching the glob.
+
+Installing Globs from Parent Directories
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The default treatment of paths in globs creates a complication where referring
+to globs in a parent directory such as ``(glob_files ../*.txt)`` would attempt
+to install the matched files outside the designated install directory. For
+example writing:
+
+.. code:: dune
+
+    (install
+     (files (glob_files ../*.txt))
+     (section share))
+
+...would cause Dune to attempt to install the matching files to
+``share/<package>/../``, ie. ``share`` where ``<package>`` is the name of the
+package (i.e., ``dune-project`` would contain ``(package (name <package>))``).
+This is probably not what the user intends, and installing files to relative
+paths beginning with ``..`` is deprecated from version 3.11 of Dune and will
+become an error in a future version.
+
+The solution is to use ``with_prefix`` to replace the ``..`` with some other
+path. For example:
+
+.. code:: dune
+
+    (install
+     (files (glob_files (../*.txt with_prefix .)))
+     (section share))
+
+...would install the matched files to ``share/<package>/`` instead.
+
+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
+
+Installing Source Directories
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To install entire source directories, the ``source_tree`` field can be used:
+
+.. code:: dune
+
+   (install
+    (section doc)
+    (source_trees manual))
+
+This example results in the contents of the ``manual`` directory being installed
+under ``<prefix>/doc/<package>/manual/``.
+
+As with ``(files ...)`` the destination can be changed with the ``as`` keyword.
+For example if you want to install all the files in the ``manual`` directory
+directly into ``<prefix>/doc/<package>/`` you can write:
+
+.. code:: dune
+
+   (install
+    (section doc)
+    (source_trees (manual as .)))
+
+It's also possible to specify multiple directories:
+
+.. code:: dune
+
+   (install
+    (section doc)
+    (source_trees manual examples))
+
+This would result in the local directories ``manual`` and ``examples`` being
+installed to ``<prefix>/doc/<package>/manual/`` and
+``<prefix>/doc/<package>/examples/`` respectively.
+
+Unlike with ``(files ...)`` it is an error to begin the destination (the
+right-hand side of ``as``) with ``..``. (This is because support for installing
+source directories was added to Dune after destinations beginning with ``..``
+were deprecated.)