287 lines
9.3 KiB
ReStructuredText
287 lines
9.3 KiB
ReStructuredText
|
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.)
|