mte/unikernel/duniverse/dune_/doc/usage.rst

**********************
Command-Line Interface
**********************

.. TODO(diataxis)

   There are mixed types of contents in this document, including:

   - an how-to about ``dune init``
   - reference info about finding the root and libraries
   - reference info about the CLI
   - how-to info about overriding what ``dune build`` does

This section describes using ``dune`` from the shell.

.. _initializing_components:

Initializing Components
=======================

NOTE: The ``dune init`` command is still under development and subject to
change.

Dune's ``init`` subcommand provides limited support for generating Dune file
stanzas and folder structures to define components. The ``dune init`` command can be used to
quickly add new projects, libraries, tests, and executables without having to
manually create Dune files in a text editor, or it can be composed to programmatically generate
parts of a multi-component project.

Initializing a Project
----------------------

You can run the following command to initialize a new Dune project that uses the ``base`` and ``cmdliner``
libraries and supports inline tests:

.. code:: console

   $ dune init proj myproj --libs base,cmdliner --inline-tests --ppx ppx_inline_test

This creates a new directory called ``myproj``, including subdirectories and
``dune`` files for library, executable, and test components. Each component's
``dune`` file will also include the declarations required for the given
dependencies.

This is the quickest way to get a basic ``dune`` project up and building.

Initializing an Executable
-----------------------------

To add a new executable to a ``dune`` file in the current directory
(creating the file if necessary), run

.. code:: console

    $ dune init exe myexe --libs base,containers,notty --ppx ppx_deriving

This will add the following stanza to the ``dune`` file:

.. code:: dune

    (executable
     (name main)
     (libraries base containers notty)
     (preprocess
      (pps ppx_deriving)))

Initializing a Library
----------------------

Run the following command to create a new directory ``src``, initialized as a library:

.. code:: console

    $ dune init lib mylib src --libs core --inline-tests --public

This will ensure the file ``./src/dune`` contains the below stanza (creating
the file and directory, if necessary):

.. code:: dune

    (library
     (public_name mylib)
     (inline_tests)
     (name mylib)
     (libraries core)
     (preprocess
      (pps ppx_inline_tests)))

Initializing Components in a Specified Directory
------------------------------------------------

All ``init`` subcommands take an optional ``PATH`` argument, which should be a
path to a directory. When supplied, the component will be created in the
specified directory. E.g., to initialize a project in the current working
directory, run

.. code:: console

    $ dune init proj my_proj .

To initialize a project in a directory in some nested path, run

.. code:: console

    $ dune init proj my_proj path/to/my/project

If the specified directory does not already exist, it will be created.

Learning More About the ``init`` Commands
-----------------------------------------

Consult the manual page using the ```dune init --help`` command for more
details.

.. _finding-root:

Finding the Root
================

The root of the current workspace is determined by looking up a
``dune-workspace`` or ``dune-project`` file in the current directory and its
parent directories. Dune requires at least one of these two files to operate.

If it isn't in the current directory, Dune prints out the root when starting:

.. code:: console

    $ dune runtest
    Entering directory '/home/jdimino/code/dune'
    ...

This message can be suppressed with the ``--no-print-directory``
command line option (as in GNU make).

More precisely, Dune will choose the outermost ancestor directory containing a
``dune-workspace`` file, which is used to mark the root of the current workspace.
If no ``dune-workspace`` file is present, the same strategy applies with
``dune-project`` files.

In case of a mix of `dune-workspace` and `dune-project` files, workspace files
take precedence over project files in the sense that if a ``dune-workspace``
file is found, only parent ``dune-workspace`` files will be considered when
looking for the root; however, if a `dune-project` file is found both parent
``dune-workspace`` and ``dune-project`` files will be considered.

A ``dune-workspace`` file is also a configuration file. Dune will read it
unless the ``--workspace`` command line option is used. See
:doc:`/reference/dune-workspace/index` for the syntax of this file. The
scope of ``dune-project`` files is wider than the scope ``dune-workspace``
files. For instance, a ``dune-project`` file may specify the name of the
project which is a universal property of the project, while a
``dune-workspace`` file may specify an opam switch name which is valid only on
a given machine. For this reason, it is common and recommended to commit
``dune-project`` files in repositories, while it is less common to commit
``dune-workspace`` files.


Current Directory
-----------------

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.

.. _forcing-root:

Forcing the Root (for Scripts)
------------------------------

You can pass the ``--root`` option to ``dune`` to select the root
explicitly. This option is intended for scripts to disable the automatic lookup.

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.

Interpretation of Targets
=========================

This section describes how Dune interprets the targets provided on
the command line. When no targets are specified, Dune builds the
:doc:`default alias </reference/aliases/default>`.

Resolution
----------

All targets that Dune knows how to build live in the ``_build`` directory.
Although, some are sometimes copied to the source tree for the need of external
tools. These includes ``<package>.install`` files when either ``-p`` or
``--promote-install-files`` is passed on the command line.

As a result, if you want to ask Dune to produce a particular ``.exe``
file you would have to type:

.. code:: console

    $ dune build _build/default/bin/prog.exe

However, for convenience, when a target on the command line doesn't
start with ``_build``, Dune expands it to the
corresponding target in all the build contexts that Dune knows how to
build. When using ``--verbose``, it prints out the actual set of
targets upon starting:

.. code:: console

    $ dune build bin/prog.exe --verbose
    ...
    Actual targets:
    - _build/default/bin/prog.exe
    - _build/4.03.0/bin/prog.exe
    - _build/4.04.0/bin/prog.exe

If a target starts with the ``@`` sign, it is interpreted as an :term:`alias`.
See :doc:`reference/aliases`.

Variables for Artifacts
-----------------------

It's possible to build specific artifacts by using the corresponding variable
on the command line. For example:

.. code::

    dune build '%{cmi:foo}'

See :ref:`variables-for-artifacts` for more information.


Finding External Libraries
==========================

When a library isn't available in the workspace, Dune will search for it
in the installed world and expect it to be already compiled.

It looks up external libraries using a specific list of search paths,
and each build context has a specific list of search paths.

When running inside an opam environment, Dune will look for installed
libraries in ``$OPAM_SWITCH_PREFIX/lib``. This includes both opam
build context configured via the ``dune-workspace`` file and the
default build context when the variable ``$OPAM_SWITCH_PREFIX`` is
set.

Otherwise, Dune takes the directory where ``ocamlc`` was found and
appends `../lib`` to it. For instance, if ``ocamlc`` is found in
``/usr/bin``, Dune looks for installed libraries in ``/usr/lib``.

In addition to the two above rules, Dune always inspects the
``OCAMLPATH`` environment variable and uses the paths defined in this
variable. ``OCAMLPATH`` always has precedence and can have different
values in different build contexts. For instance, you can set it
manually in a specific build context via the ``dune-workspace`` file.

.. _running-tests:

Running Tests
=============

There are two ways to run tests:

-  ``dune build @runtest``
-  ``dune test`` (or its alias ``dune runtest``)

The two commands are equivalent, and they will run all the tests defined in the
current directory and its children directories recursively. You can also run the tests in a
specific sub-directory and its children by using:

-  ``dune build @foo/bar/runtest``
-  ``dune test foo/bar`` (or ``dune runtest foo/bar``)

Watch Mode
==========

The ``dune build`` and ``dune runtest`` commands support a ``-w`` (or
``--watch``) flag. When it's 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.

Launching the Toplevel (REPL)
=============================

Dune supports launching a `utop <https://github.com/diml/utop>`__ instance
with locally defined libraries loaded.

.. code:: console

   $ dune utop <dir> -- <args>

Where ``<dir>`` is a directory under which Dune searches (recursively) for
all libraries that will be loaded. ``<args>`` will be 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.

Dune also supports loading individual modules unsealed by their signatures into
the toplevel. This is accomplished by launching a toplevel and then asking dune
to return the toplevel directives needed to evaluate the module:

.. code:: console

   $ utop
   # use_output "dune ocaml top-module path/to/module.ml";;

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.

Restricting the Set of Packages
===============================

Restrict the set of packages from your workspace that Dune can see with
the ``--only-packages`` option:

.. code:: console

    $ dune build --only-packages pkg1,pkg2,... @install

This option acts as if you went through all the Dune files and
commented out the stanzas referring to a package that isn't in the list
given to ``dune``.

Distributing Projects
=====================

Dune provides support for building and installing your project; however, it
doesn't provide helpers for distributing it. It's recommended to use
`dune-release <https://github.com/samoht/dune-release>`__ for this purpose.

The common defaults are that your projects include the following files:

- ``README.md``
- ``CHANGES.md``
- ``LICENSE.md``

If your project contains several packages, all the package names
must be prefixed by the shortest one.

.. _dune-subst:

``dune subst``
==============

One of the features ``dune-release`` provides is watermarking; it replaces
various strings of the form ``%%ID%%`` in all your project files
before creating a release tarball or when the opam user pins the package.

This is especially interesting for the ``VERSION`` watermark, which gets
replaced by the version obtained from the Version-Control System (VCS). For instance, if you're using
Git, ``dune-release`` invokes this command to find out the version:

.. code:: console

    $ git describe --always --dirty --abbrev=7
    1.0+beta9-79-g29e9b37

If no VCS is detected, ``dune subst`` will do nothing.

Projects using Dune usually only need ``dune-release`` for creating and
publishing releases. However, they may still substitute the
watermarks when the user pins the package. To help with this,
Dune provides the ``subst`` sub-command.

``dune subst`` performs the same substitution that ``dune-release`` does
with the default configuration, i.e., calling ``dune subst`` at the
root of your project will rewrite all your project files.

More precisely, it replaces the following watermarks in the source files:

- ``NAME``, the name of the project
- ``VERSION``, output of ``git describe --always --dirty --abbrev=7``
- ``VERSION_NUM``, same as ``VERSION`` but with a potential leading
  ``v`` or ``V`` dropped
- ``VCS_COMMIT_ID``, commit hash from the vcs
- ``PKG_MAINTAINER``, contents of the ``maintainer`` field from the
  opam file
- ``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

The project name 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.

Note that ``dune subst`` is meant to be called from the opam file and
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.

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:: console

   $ 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

Installing a Package
====================

Via opam
--------

When releasing a package using Dune in opam, there's nothing special
to do.  Dune generates a file called ``<package-name>.install`` at the
root of the project.  This contains a list of files to install, and
opam reads it in order to perform the installation.

Manually
--------

When not using opam, or when you want to manually install a package,
you can ask Dune to perform the installation via the ``install``
command:

.. code:: console

    $ dune install [PACKAGE]...

This command takes a list of package names to install.  If no packages
are specified, Dune will install all available packages in the
workspace.  When several build contexts are specified via a
:doc:`/reference/dune-workspace/index` file, Dune performs the
installation in all the build contexts.

Destination Directory
---------------------

For a given build context, the installation directories are determined with a
single scheme for all installation sections. Taking the ``lib`` installation
section as an example, the priorities of this scheme are as follows:

#. if an explicit ``--lib <path>`` argument is passed, use this path
#. if an explicit ``--prefix <path>`` argument is passed, use ``<path>/lib``
#. if ``--lib <path>`` argument is passed before during dune compilation to
   ``./configure``, use this paths
#. if ``OPAM_SWITCH_PREFIX`` is present in the environment use ``$OPAM_SWITCH_PREFIX/lib``
#. otherwise, fail

Relocation Mode
---------------

The installation can be done in specific mode (``--relocation``) for creating a
directory that can be moved. In that case, the installed executables will
look up the package sites (cf :ref:`sites`) relative to its location.
The `--prefix` directory should be used to specify the destination.


If you're using plugins that depend on installed libraries and aren't
executable dependencies, like libraries that need to be loaded at
runtime, you must copy the libraries manually to the destination directory.

Querying Merlin Configuration
=============================

Since Version 2.8, Dune no longer promotes ``.merlin`` files to the source
directories. Instead, Dune stores these configurations in the `_build`
folder, and Merlin communicates directly with Dune to obtain its configuration
via the `ocaml-merlin` subcommand. The Merlin configuration is now stanza-specific,
allowing finer control. The following commands aren't needed for
normal Dune and Merlin use, but they can provide insightful information when
debugging or configuring non-standard projects.

Printing the Configuration
--------------------------

It's possible to manually query the generated configuration for debugging
purposes:

.. code:: console

    $ dune ocaml merlin dump-config

This command prints the distinct configuration of each module present in the
current directory. This directory must be in a Dune workspace and the project
must be already built. The configuration will be encoded as s-expressions, which
are used to communicate with Merlin.

Printing an Approximated ``.merlin``
------------------------------------

It's also possible to print the current folder's configuration in the
Merlin configuration syntax by running the following command:

.. code:: console

    $ dune ocaml dump-dot-merlin > .merlin

In that case, Dune prints only one configuration: the result of the configuration's
coarse merge in the current folder's various modules.
This folder must be in a Dune workspace, and the project must be already
built. Preprocessing directives and other flags will be commented out and must
be un-commented afterward. This feature doesn't aim at writing exact or correct
``.merlin`` files. Its sole purpose is to lessen the burden of writing the
configuration from scratch.

.. _merlin-filenames:

Non-Standard Filenames
----------------------

Merlin configuration loading is based on filenames, so if you have
files that are preprocessed by custom rules before they are built, they should
respect the following naming convention: the unprocessed file should start with
the name of the resulting processed file followed by a dot. The rest
does not matter. Dune uses only the name before the first dot to
match with available configurations.

For example, if you use the ``cppo`` preprocessor to generate the file
``real_module_name.ml``, then the source file could be named
``real_module_name.cppo.ml``.

Running a Coq Toplevel
======================

See :ref:`running-coq-top`.