unikernel/duniverse/dune_/doc/reference/aliases.rst

@@ -0,0 +1,93 @@
+Aliases
+=======
+
+:term:`Aliases <alias>` are build targets that do not correspond to specific
+files. For example, the ``runtest`` alias corresponds to running tests.
+
+Model and Syntax
+----------------
+
+Dependencies and actions can be attached to an alias. When this alias is
+requested to be built, these dependencies are built and these actions are
+executed. Aliases are attached to specific directories.
+
+In commands such as ``dune build``, the syntax to refer to the ``x`` alias is
+``@x``, for example ``dune build @x``. This is why it is common to refer to it
+as "the ``@x`` alias", or "attaching a rule to ``@x``".
+
+Building ``@x`` will build ``x`` in all subdirectories of the current
+directory. This is the most common case, but it is possible to restrict this
+using different syntaxes:
+
+- ``@sub/dir/x`` will build ``x`` in ``sub/dir`` and its subdirectories.
+- ``@@x`` will build ``x`` in the current directory only.
+- ``@@sub/dir/x`` will build ``x`` in ``sub/dir`` only.
+
+If ``dir`` is the directory of a :term:`build context`, it restricts the alias
+to this context.
+
+To summarize, the syntax is:
+
+- ``@`` (recursive) or ``@@`` (non-recursive): determine if subdirectories are
+  included
+- optional :term:`build context root`: restrict to a particular :term:`build
+  context`
+- optional directory: only consider this subdirectory
+- alias name
+
+Examples:
+
+- ``dune build @_build/foo/runtest`` only runs the tests for
+  the ``foo`` build context
+- ``dune build @runtest`` will run the tests for all build contexts
+
+User-Defined Aliases
+--------------------
+
+It is possible to use any name for alias names; it will then be available on
+the command line. For example, if a Dune file contains the following, then
+``dune build @deploy`` will execute that command.
+
+.. code:: dune
+
+   (rule
+    (alias deploy)
+    (action ./run-deployer.exe))
+
+Built-In Aliases
+----------------
+
+Some aliases are defined and managed by Dune itself:
+
+.. grid:: 1 3 2 3
+
+  .. grid-item::
+
+    .. toctree::
+       :caption: Builds
+
+       aliases/all
+       aliases/default
+       aliases/install
+       aliases/pkg-install
+       aliases/empty
+
+  .. grid-item::
+
+    .. toctree::
+       :caption: Checks
+
+       aliases/check
+       aliases/ocaml-index
+       aliases/runtest
+       aliases/fmt
+       aliases/lint
+
+  .. grid-item::
+
+    .. toctree::
+       :caption: Docs
+
+       aliases/doc
+       aliases/doc-private
+       aliases/doc-json