2017-05-14 00:10:00 +00:00
|
|
|
*****
|
|
|
|
Usage
|
|
|
|
*****
|
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
This section describe usage of dune from the shell.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
.. _finding-root:
|
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
Finding the root
|
|
|
|
================
|
|
|
|
|
2018-06-29 22:30:27 +00:00
|
|
|
.. _dune-workspace:
|
2017-05-18 20:15:49 +00:00
|
|
|
|
2018-06-29 22:30:27 +00:00
|
|
|
dune-workspace
|
|
|
|
--------------
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
The root of the current workspace is determined by looking up a
|
2018-06-29 22:30:27 +00:00
|
|
|
``dune-workspace`` or ``dune-project`` file in the current directory
|
2018-05-02 11:56:12 +00:00
|
|
|
and parent directories.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-06-29 22:30:27 +00:00
|
|
|
``dune`` prints out the root when starting if it is not the current
|
|
|
|
directory:
|
2017-09-22 00:40:14 +00:00
|
|
|
|
|
|
|
.. code:: bash
|
|
|
|
|
2018-06-29 22:30:27 +00:00
|
|
|
$ dune runtest
|
|
|
|
Entering directory '/home/jdimino/code/dune'
|
2017-09-22 00:40:14 +00:00
|
|
|
...
|
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
More precisely, it will choose the outermost ancestor directory containing a
|
2018-06-29 22:30:27 +00:00
|
|
|
``dune-workspace`` file as root. For instance if you are in
|
2018-07-06 08:10:59 +00:00
|
|
|
``/home/me/code/myproject/src``, then dune will look for all these files in
|
2017-06-01 15:02:29 +00:00
|
|
|
order:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-06-29 22:30:27 +00:00
|
|
|
- ``/dune-workspace``
|
|
|
|
- ``/home/dune-workspace``
|
|
|
|
- ``/home/me/dune-workspace``
|
|
|
|
- ``/home/me/code/dune-workspace``
|
|
|
|
- ``/home/me/code/myproject/dune-workspace``
|
|
|
|
- ``/home/me/code/myproject/src/dune-workspace``
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
The first entry to match in this list will determine the root. In
|
2018-06-29 13:27:35 +00:00
|
|
|
practice this means that if you nest your workspaces, dune will
|
2017-05-14 00:10:00 +00:00
|
|
|
always use the outermost one.
|
|
|
|
|
2018-06-29 22:30:27 +00:00
|
|
|
In addition to determining the root, ``dune`` will read this file as
|
|
|
|
to setup the configuration of the workspace unless the ``--workspace``
|
|
|
|
command line option is used. See the section `Workspace
|
|
|
|
configuration`_ for the syntax of this file.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
Current directory
|
|
|
|
-----------------
|
|
|
|
|
2018-06-29 22:30:27 +00:00
|
|
|
If the previous rule doesn't apply, i.e. no ancestor directory has a
|
|
|
|
file named ``dune-workspace``, then the current directory will be used
|
|
|
|
as root.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
Forcing the root (for scripts)
|
|
|
|
------------------------------
|
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
You can pass the ``--root`` option to ``dune`` to select the root
|
2017-06-01 15:02:29 +00:00
|
|
|
explicitly. This option is intended for scripts to disable the automatic lookup.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
Note that when using the ``--root`` option, targets given on the command line
|
|
|
|
will be interpreted relative to the given root, not relative to the current
|
|
|
|
directory as this is normally the case.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
Interpretation of targets
|
|
|
|
=========================
|
|
|
|
|
2018-06-28 11:21:13 +00:00
|
|
|
This section describes how ``dune`` interprets the targets given on
|
|
|
|
the command line. When no targets are specified, ``dune`` builds the
|
|
|
|
``default`` alias, see :ref:`default-alias` for more details.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
Resolution
|
|
|
|
----------
|
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
All targets that dune knows how to build live in the ``_build``
|
2018-01-19 08:50:06 +00:00
|
|
|
directory. Although, some are sometimes copied to the source tree for
|
|
|
|
the need of external tools. These includes:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-01-19 08:50:06 +00:00
|
|
|
- ``.merlin`` files
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-01-19 08:50:06 +00:00
|
|
|
- ``<package>.install`` files
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
As a result, if you want to ask ``dune`` to produce a particular ``.exe``
|
2017-06-01 15:02:29 +00:00
|
|
|
file you would have to type:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
.. code:: bash
|
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
$ dune build _build/default/bin/prog.exe
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-01-19 08:50:06 +00:00
|
|
|
However, for convenience when a target on the command line doesn't
|
2018-06-29 13:27:35 +00:00
|
|
|
start with ``_build``, ``dune`` will expand it to the
|
2018-01-19 08:50:06 +00:00
|
|
|
corresponding target in all the build contexts where it knows how to
|
|
|
|
build it. When using ``--verbose``, It prints out the actual set of
|
|
|
|
targets when starting:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
.. code:: bash
|
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
$ dune build bin/prog.exe --verbose
|
2017-05-14 00:10:00 +00:00
|
|
|
...
|
|
|
|
Actual targets:
|
|
|
|
- _build/default/bin/prog.exe
|
|
|
|
- _build/4.03.0/bin/prog.exe
|
|
|
|
- _build/4.04.0/bin/prog.exe
|
|
|
|
|
|
|
|
Aliases
|
|
|
|
-------
|
|
|
|
|
|
|
|
Targets starting with a ``@`` are interpreted as aliases. For instance
|
2017-09-29 15:49:05 +00:00
|
|
|
``@src/runtest`` means the alias ``runtest`` in all descendant of
|
2018-01-19 08:50:06 +00:00
|
|
|
``src`` in all build contexts where it is defined. If you want to
|
|
|
|
refer to a target starting with a ``@``, simply write: ``./@foo``.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-01-19 08:50:06 +00:00
|
|
|
To build and run the tests for a particular build context, use
|
|
|
|
``@_build/default/runtest`` instead.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
So for instance:
|
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
- ``dune build @_build/foo/runtest`` will run the tests only for
|
2017-05-14 00:10:00 +00:00
|
|
|
the ``foo`` build context
|
2018-06-29 13:27:35 +00:00
|
|
|
- ``dune build @runtest`` will run the tests for all build contexts
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-06-28 11:39:00 +00:00
|
|
|
You can also build an alias non-recursively by using ``@@`` instead of
|
|
|
|
``@``. For instance to run tests only from the current directory:
|
|
|
|
|
|
|
|
.. code::
|
|
|
|
|
|
|
|
dune build @@runtest
|
|
|
|
|
2018-06-28 11:21:13 +00:00
|
|
|
.. _default-alias:
|
|
|
|
|
|
|
|
Default alias
|
|
|
|
-------------
|
|
|
|
|
|
|
|
When no targets are given to ``dune build``, it builds the special
|
|
|
|
``default`` alias. Effectively ``dune build`` is equivalent to:
|
|
|
|
|
|
|
|
.. code::
|
|
|
|
|
|
|
|
dune build @@default
|
|
|
|
|
|
|
|
When a directory doesn't explicitly define what the ``default`` alias
|
|
|
|
means via an :ref:`alias-stanza` stanza, the following implicit
|
|
|
|
definition is assumed:
|
|
|
|
|
|
|
|
.. code::
|
|
|
|
|
|
|
|
(alias
|
|
|
|
(name default)
|
|
|
|
(deps (alias_rec install)))
|
|
|
|
|
|
|
|
Which means that by default ``dune build`` will build everything that
|
|
|
|
is installable.
|
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
Finding external libraries
|
|
|
|
==========================
|
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
When a library is not available in the workspace, dune will look it
|
2017-05-14 00:10:00 +00:00
|
|
|
up in the installed world, and expect it to be already compiled.
|
|
|
|
|
2018-07-10 11:46:27 +00:00
|
|
|
It looks up external libraries using a specific list of search paths. A
|
|
|
|
list of search paths is specific to a given build context and is
|
2017-05-14 00:10:00 +00:00
|
|
|
determined as follow:
|
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
#. if the ``ocamlfind`` is present in the ``PATH`` of the context, use each line
|
|
|
|
in the output of ``ocamlfind printconf path`` as a search path
|
|
|
|
#. otherwise, if ``opam`` is present in the ``PATH``, use the outout of ``opam
|
|
|
|
config var lib``
|
2017-05-14 00:10:00 +00:00
|
|
|
#. otherwise, take the directory where ``ocamlc`` was found, and append
|
2017-06-01 15:02:29 +00:00
|
|
|
``../lib`` to it. For instance if ``ocamlc`` is found in ``/usr/bin``, use
|
|
|
|
``/usr/lib``
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
.. _running-tests:
|
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
Running tests
|
2017-10-10 20:15:50 +00:00
|
|
|
=============
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
There are two ways to run tests:
|
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
- ``dune build @runtest``
|
|
|
|
- ``dune runtest``
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
The two commands are equivalent. They will run all the tests defined in the
|
|
|
|
current directory and its children recursively. You can also run the tests in a
|
|
|
|
specific sub-directory and its children by using:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
- ``dune build @foo/bar/runtest``
|
|
|
|
- ``dune runtest foo/bar``
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-09-06 15:56:02 +00:00
|
|
|
Watch mode
|
|
|
|
==========
|
|
|
|
|
|
|
|
The ``dune build`` and ``dune runtest`` commands support a ``-w`` (or
|
|
|
|
``--watch``) flag. When it is passed, dune will perform the action as usual, and
|
|
|
|
then wait for file changes and rebuild (or rerun the tests). This feature
|
|
|
|
requires ``inotifywait`` or ``fswatch`` to be installed.
|
|
|
|
|
2017-10-10 20:35:47 +00:00
|
|
|
Launching the Toplevel (REPL)
|
|
|
|
=============================
|
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
Dune supports launching a `utop <https://github.com/diml/utop>`__ instance
|
2017-10-10 20:35:47 +00:00
|
|
|
with locally defined libraries loaded.
|
|
|
|
|
|
|
|
.. code:: bash
|
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
$ dune utop <dir> -- <args>
|
2017-10-10 20:35:47 +00:00
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
Where ``<dir>`` is a directory containing a ``dune`` file defining all the
|
2017-10-10 20:35:47 +00:00
|
|
|
libraries that will be loaded (using the ``library`` stanza). ``<args>`` will be
|
2018-07-06 08:10:59 +00:00
|
|
|
passed as arguments to the utop command itself. For example, ``dune utop lib --
|
|
|
|
-implicit-bindings`` will start ``utop`` with the libraries defined in ``lib``
|
|
|
|
and implicit bindings for toplevel expressions.
|
2017-10-10 20:35:47 +00:00
|
|
|
|
|
|
|
Requirements & Limitations
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
* utop version >= 2.0 is required for this to work.
|
|
|
|
* This subcommand only supports loading libraries. Executables aren't supported.
|
|
|
|
* Libraries that are dependencies of utop itself cannot be loaded. For example
|
|
|
|
`Camomile <https://github.com/yoriyuki/Camomile>`__.
|
|
|
|
* Loading libraries that are defined in different directories into one utop
|
|
|
|
instance isn't possible.
|
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
Restricting the set of packages
|
|
|
|
===============================
|
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
You can restrict the set of packages from your workspace that dune can see with
|
|
|
|
the ``--only-packages`` option:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
.. code:: bash
|
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
$ dune build --only-packages pkg1,pkg2,... @install
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
This option acts as if you went through all the dune files and
|
2017-05-14 00:10:00 +00:00
|
|
|
commented out the stanzas refering to a package that is not in the list
|
2018-06-29 13:27:35 +00:00
|
|
|
given to ``dune``.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
Invocation from opam
|
|
|
|
====================
|
|
|
|
|
|
|
|
You should set the ``build:`` field of your ``<package>.opam`` file as
|
|
|
|
follows:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2018-07-31 19:00:08 +00:00
|
|
|
build: [
|
|
|
|
["dune" "subst"] {pinned}
|
|
|
|
["dune" "build" "-p" name "-j" jobs]
|
|
|
|
]
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-05-04 15:49:25 +00:00
|
|
|
``-p pkg`` is a shorthand for ``--root . --only-packages pkg --profile
|
2018-06-28 11:21:13 +00:00
|
|
|
release --default-target @install``. ``-p`` is the short version of
|
2018-01-15 13:24:25 +00:00
|
|
|
``--for-release-of-packages``.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
This has the following effects:
|
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
- it tells dune to build everything that is installable and to
|
2017-05-14 00:10:00 +00:00
|
|
|
ignore packages other than ``name`` defined in your project
|
2018-06-29 13:27:35 +00:00
|
|
|
- it sets the root to prevent dune from looking it up
|
2018-05-04 15:49:25 +00:00
|
|
|
- it sets the build profile to ``release``
|
2017-05-14 00:10:00 +00:00
|
|
|
- it uses whatever concurrency option opam provides
|
2018-06-28 11:21:13 +00:00
|
|
|
- it sets the default target to ``@install`` rather than ``@@default``
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
Note that ``name`` and ``jobs`` are variables expanded by opam. ``name`` expands
|
|
|
|
to the package name and ``jobs`` to the number of jobs available to build the
|
|
|
|
package.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
Tests
|
|
|
|
=====
|
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
To setup the building and running of tests in opam, add this line to your
|
|
|
|
``<package>.opam`` file:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
::
|
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
build-test: [["dune" "runtest" "-p" name "-j" jobs]]
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
Installation
|
|
|
|
============
|
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
Installing a package means copying the build artifacts from the build directory
|
|
|
|
to the installed word.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
When installing via opam, you don't need to worry about this step: dune
|
|
|
|
generates a ``<package>.install`` file that opam will automatically read to
|
|
|
|
handle installation.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
However, when not using opam or doing local development, you can use dune to
|
|
|
|
install the artifacts by hands. To do that, use the ``install`` command:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
::
|
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
$ dune install [PACKAGE]...
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
without an argument, it will install all the packages available in the
|
|
|
|
workspace. With a specific list of packages, it will only install these
|
2018-07-06 08:10:59 +00:00
|
|
|
packages. If several build contexts are configured, the installation will be
|
|
|
|
performed for all of them.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
Note that ``dune install`` is a thin wrapper around the ``opam-installer`` tool,
|
|
|
|
so you will need to install this tool in order to be able to use ``dune
|
|
|
|
install``.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
Destination
|
|
|
|
-----------
|
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
The place where the build artifacts are copied, usually referred as **prefix**,
|
|
|
|
is determined as follow for a given build context:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
#. if an explicit ``--prefix <path>`` argument is passed, use this path
|
2017-07-25 16:07:24 +00:00
|
|
|
#. if ``opam`` is present in the ``PATH`` and is configured, use the
|
|
|
|
output of ``opam config var prefix``
|
2017-07-05 13:10:41 +00:00
|
|
|
#. otherwise, take the parent of the directory where ``ocamlc`` was found.
|
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
As an exception to this rule, library files might be copied to a different
|
|
|
|
location. The reason for this is that they often need to be copied to a
|
|
|
|
particular location for the various build system used in OCaml projects to find
|
|
|
|
them and this location might be different from ``<prefix>/lib`` on some systems.
|
|
|
|
|
|
|
|
Historically, the location where to store OCaml library files was configured
|
|
|
|
through `findlib <http://projects.camlcity.org/projects/findlib.html>`__ and the
|
|
|
|
``ocamlfind`` command line tool was used to both install these files and locate
|
|
|
|
them. Many Linux distributions or other packaging systems are using this
|
|
|
|
mechanism to setup where OCaml library files should be copied.
|
|
|
|
|
|
|
|
As a result, if none of ``--libdir`` and ``--prefix`` is passed to ``dune
|
|
|
|
install`` and ``ocamlfind`` is present in the ``PATH``, then library files will
|
|
|
|
be copied to the directory reported by ``ocamlfind printconf destdir``. This
|
|
|
|
ensures that ``dune install`` can be used without opam. When using opam,
|
|
|
|
``ocamlfind`` is configured to point to the opam directory, so this rule makes
|
|
|
|
no difference.
|
|
|
|
|
|
|
|
Note that ``--prefix`` and ``--libdir`` are only supported if a single build
|
|
|
|
context is in use.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
Workspace configuration
|
|
|
|
=======================
|
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
By default, a workspace has only one build context named ``default`` which
|
|
|
|
correspond to the environment in which ``dune`` is run. You can define more
|
|
|
|
contexts by writing a ``dune-workspace`` file.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
You can point ``dune`` to an explicit ``dune-workspace`` file with the
|
|
|
|
``--workspace`` option. For instance it is good practice to write a
|
|
|
|
``dune-workspace.dev`` in your project with all the version of OCaml your
|
|
|
|
projects support. This way developers can tests that the code builds with all
|
|
|
|
version of OCaml by simply running:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
.. code:: bash
|
|
|
|
|
2018-06-29 22:30:27 +00:00
|
|
|
$ dune build --workspace dune-workspace.dev @install @runtest
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-06-29 22:30:27 +00:00
|
|
|
dune-workspace
|
|
|
|
--------------
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-06-29 22:30:27 +00:00
|
|
|
The ``dune-workspace`` file uses the S-expression syntax. This is what
|
|
|
|
a typical ``dune-workspace`` file looks like:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
2018-06-29 22:30:27 +00:00
|
|
|
(lang dune 1.0)
|
2017-12-21 11:59:09 +00:00
|
|
|
(context (opam (switch 4.02.3)))
|
|
|
|
(context (opam (switch 4.03.0)))
|
|
|
|
(context (opam (switch 4.04.0)))
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
The rest of this section describe the stanzas available.
|
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
Note that an empty ``dune-workspace`` file is interpreted the same as one
|
|
|
|
containing exactly:
|
2017-08-30 00:29:54 +00:00
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
2018-06-29 22:30:27 +00:00
|
|
|
(lang dune 1.0)
|
2017-08-30 00:29:54 +00:00
|
|
|
(context default)
|
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
This allows you to use an empty ``dune-workspace`` file to mark the root of your
|
|
|
|
project.
|
2017-08-30 00:29:54 +00:00
|
|
|
|
2018-05-04 15:49:25 +00:00
|
|
|
profile
|
|
|
|
~~~~~~~
|
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
The build profile can be selected in the ``dune-workspace`` file by write a
|
|
|
|
``(profile ...)`` stanza. For instance:
|
2018-05-04 15:49:25 +00:00
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
2018-06-27 18:06:38 +00:00
|
|
|
(profile release)
|
2018-05-04 15:49:25 +00:00
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
Note that the command line option ``--profile`` has precedence over this stanza.
|
2018-05-04 15:49:25 +00:00
|
|
|
|
2018-07-20 14:03:44 +00:00
|
|
|
env
|
|
|
|
~~~
|
|
|
|
|
|
|
|
The ``env`` stanza can be used to set the base environment for all contexts in
|
|
|
|
this workspace. This environment has the lowest precedence of all other ``env``
|
|
|
|
stanzas. The syntax for this stanza is the same dune's :ref:`dune-env` stanza.
|
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
context
|
|
|
|
~~~~~~~
|
|
|
|
|
|
|
|
The ``(context ...)`` stanza declares a build context. The argument
|
2017-12-21 11:59:09 +00:00
|
|
|
can be either ``default`` or ``(default)`` for the default build
|
|
|
|
context or can be the description of an opam switch, as follows:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
2017-12-21 11:59:09 +00:00
|
|
|
(context (opam (switch <opam-switch-name>)
|
|
|
|
<optional-fields>))
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
``<optional-fields>`` are:
|
|
|
|
|
|
|
|
- ``(name <name>)`` is the name of the subdirectory of ``_build``
|
|
|
|
where the artifacts for this build context will be stored
|
|
|
|
|
|
|
|
- ``(root <opam-root>)`` is the opam root. By default it will take
|
2018-06-29 13:27:35 +00:00
|
|
|
the opam root defined by the environment in which ``dune`` is
|
2017-05-14 00:10:00 +00:00
|
|
|
run which is usually ``~/.opam``
|
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
- ``(merlin)`` instructs dune to use this build context for
|
2018-06-01 13:24:35 +00:00
|
|
|
merlin
|
2017-09-22 11:20:22 +00:00
|
|
|
|
2018-05-04 15:49:25 +00:00
|
|
|
- ``(profile <profile>)`` to set a different profile for a build
|
|
|
|
context. This has precedence over the command line option
|
|
|
|
``--profile``
|
|
|
|
|
2018-07-20 14:03:44 +00:00
|
|
|
- ``(env <env>)`` to set the environment for a particular context. This is of
|
|
|
|
higher precedence than the toplevel ``env`` stanza in the workspace file. This
|
|
|
|
field the same options as the :ref:`dune-env` stanza.
|
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
Both ``(default ...)`` and ``(opam ...)`` accept a ``targets`` field in order to
|
|
|
|
setup cross compilation. See :ref:`advanced-cross-compilation` for more
|
|
|
|
information.
|
2017-12-21 11:59:09 +00:00
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
Merlin reads compilation artifacts and it can only read the compilation
|
|
|
|
artifacts of a single context. Usually, you should use the artifacts from the
|
|
|
|
``default`` context, and if you have the ``(context default)`` stanza in your
|
|
|
|
``dune-workspace`` file, that is the one dune will use.
|
2017-09-22 11:20:22 +00:00
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
For rare cases where this is not what you want, you can force dune to use a
|
|
|
|
different build contexts for merlin by adding the field ``(merlin)`` to this
|
|
|
|
context.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
Distributing Projects
|
2018-06-29 13:27:35 +00:00
|
|
|
=====================
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
Dune provides support for building and installing your project. However it
|
|
|
|
doesn't provide helpers for distributing it. It is recommended to use
|
|
|
|
`dune-release <https://github.com/samoht/dune-release>`__ for this purpose.
|
2017-06-02 10:41:10 +00:00
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
The common defaults are that your projects include the following files:
|
2017-06-02 10:41:10 +00:00
|
|
|
|
|
|
|
- ``README.md``
|
|
|
|
- ``CHANGES.md``
|
|
|
|
- ``LICENSE.md``
|
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
And that if your project contains several packages, then all the package names
|
|
|
|
must be prefixed by the shortest one.
|
2017-06-02 10:41:10 +00:00
|
|
|
|
|
|
|
Watermarking
|
2018-06-01 13:24:35 +00:00
|
|
|
============
|
2017-06-02 10:41:10 +00:00
|
|
|
|
2018-07-08 08:51:16 +00:00
|
|
|
One of the feature dune-release provides is watermarking; it replaces
|
|
|
|
various strings of the form ``%%ID%%`` in all files of your project
|
|
|
|
before creating a release tarball or when the package is pinned by the
|
|
|
|
user using opam.
|
2017-06-02 10:41:10 +00:00
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
This is especially interesting for the ``VERSION`` watermark, which gets
|
|
|
|
replaced by the version obtained from the vcs. For instance if you are using
|
2018-07-08 08:51:16 +00:00
|
|
|
git, dune-release invokes this command to find out the version:
|
2017-06-02 10:41:10 +00:00
|
|
|
|
|
|
|
.. code:: bash
|
|
|
|
|
|
|
|
$ git describe --always --dirty
|
|
|
|
1.0+beta9-79-g29e9b37
|
|
|
|
|
2018-07-08 08:51:16 +00:00
|
|
|
Projects using dune usually only need dune-release for creating and
|
|
|
|
publishing releases. However they might still want to substitute the
|
|
|
|
watermarks when the package is pinned by the user. To help with this,
|
|
|
|
dune provides the ``subst`` sub-command.
|
2017-06-02 10:41:10 +00:00
|
|
|
|
2018-06-29 13:27:35 +00:00
|
|
|
dune subst
|
|
|
|
==========
|
2017-06-02 10:41:10 +00:00
|
|
|
|
2018-07-08 08:51:16 +00:00
|
|
|
``dune subst`` performs the same substitution ``dune-release`` does
|
|
|
|
with the default configuration. i.e. calling ``dune subst`` at the
|
|
|
|
root of your project will rewrite in place all the files in your
|
|
|
|
project.
|
2017-06-02 10:41:10 +00:00
|
|
|
|
2018-07-06 08:10:59 +00:00
|
|
|
More precisely, it replaces all the following watermarks in source files:
|
2017-06-02 10:41:10 +00:00
|
|
|
|
2017-06-06 13:59:21 +00:00
|
|
|
- ``NAME``, the name of the project
|
|
|
|
- ``VERSION``, output of ``git describe --always --dirty``
|
|
|
|
- ``VERSION_NUM``, same as ``VERSION`` but with a potential leading
|
2017-06-02 10:41:10 +00:00
|
|
|
``v`` or ``V`` dropped
|
2017-06-06 13:59:21 +00:00
|
|
|
- ``VCS_COMMIT_ID``, commit hash from the vcs
|
|
|
|
- ``PKG_MAINTAINER``, contents of the ``maintainer`` field from the
|
2017-06-02 10:41:10 +00:00
|
|
|
opam file
|
2017-06-06 13:59:21 +00:00
|
|
|
- ``PKG_AUTHORS``, contents of the ``authors`` field from the opam file
|
|
|
|
- ``PKG_HOMEPAGE``, contents of the ``homepage`` field from the opam file
|
|
|
|
- ``PKG_ISSUES``, contents of the ``issues`` field from the opam file
|
|
|
|
- ``PKG_DOC``, contents of the ``doc`` field from the opam file
|
|
|
|
- ``PKG_LICENSE``, contents of the ``license`` field from the opam file
|
|
|
|
- ``PKG_REPO``, contents of the ``repo`` field from the opam file
|
|
|
|
|
2018-07-08 08:51:16 +00:00
|
|
|
The name of the project is obtained by reading the ``dune-project``
|
|
|
|
file in the directory where ``dune subst`` is called. The
|
|
|
|
``dune-project`` file must exist and contain a valid ``(name ...)``
|
|
|
|
field.
|
2017-06-02 10:41:10 +00:00
|
|
|
|
2018-07-08 08:51:16 +00:00
|
|
|
Note that ``dune subst`` is meant to be called from the opam file and
|
|
|
|
in particular behaves a bit different to other ``dune`` commands. In
|
|
|
|
particular it doesn't try to detect the root of the workspace and must
|
|
|
|
be called from the root of the project.
|
2018-06-02 11:30:06 +00:00
|
|
|
|
|
|
|
Custom Build Directory
|
|
|
|
======================
|
|
|
|
|
|
|
|
By default dune places all build artifacts in the ``_build`` directory relative
|
|
|
|
to the user's workspace. However, one can customize this directory by using the
|
|
|
|
``--build-dir`` flag or the ``DUNE_BUILD_DIR`` environment variable.
|
|
|
|
|
|
|
|
.. code:: bash
|
|
|
|
|
|
|
|
$ dune build --build-dir _build-foo
|
|
|
|
|
|
|
|
# this is equivalent to:
|
|
|
|
$ DUNE_BUILD_DIR=_build-foo dune build
|
|
|
|
|
|
|
|
# Absolute paths are also allowed
|
|
|
|
$ dune build --build-dir /tmp/build foo.exe
|