Aliases <alias>
are build targets that do not correspond to specific files. For example, the runtest
alias corresponds to running tests.
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 buildx
insub/dir
and its subdirectories.@@x
will buildx
in the current directory only.@@sub/dir/x
will buildx
insub/dir
only.
If dir
is the directory of a build context
, it restricts the alias to this context.
To summarize, the syntax is:
@
(recursive) or@@
(non-recursive): determine if subdirectories are included- optional
build context root
: restrict to a particularbuild context
- optional directory: only consider this subdirectory
- alias name
Examples:
dune build @_build/foo/runtest
only runs the tests for thefoo
build contextdune build @runtest
will run the tests for all build contexts
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.
(rule
(alias deploy)
(action ./run-deployer.exe))
Some aliases are defined and managed by Dune itself.
This alias corresponds to every known file target in a directory.
This alias corresponds to the set of targets necessary for development tools to work correctly. For example, it will build *.cmi
, *.cmt
, and *.cmti
files so that Merlin and ocaml-lsp-server
can be used in the project. It is also useful in the development loop because it will catch compilation errors without executing expensive operations such as linking executables.
This alias corresponds to the default argument for dune build
: dune build
is equivalent to dune build @@default
. Similarly, dune build dir
is equivalent to dune build @@dir/default
.
When a directory doesn't explicitly define what the default
alias means via an dune/alias
stanza, the following implicit definition is assumed:
(alias
(name default)
(deps (alias_rec all)))
But if such a stanza is present in the dune
file in a directory, it will be used instead. For example, if the following is present in tests/dune
, dune build tests
will run tests there:
(alias
(name default)
(deps (alias_rec runtest)))
This alias builds documentation for public libraries as HTML pages.
This alias builds documentation for public libraries as JSON files. These are produced by odoc
's option --as-json
and can be consumed by external tools.
This alias builds documentation for all libraries, both public & private.
This alias is used by formatting rules: when it is built, code formatters will be executed (using promotion <../concepts/promotion>
).
dune fmt
is a shortcut for dune build @fmt --auto-promote
.
It is possible to build on top of this convention. If some actions are manually attached to the fmt
alias, they will be executed by dune fmt
.
Example:
(rule
(with-stdout-to
data.json.formatted
(run jq . %{dep:data.json})))
(rule
(alias fmt)
(action
(diff data.json data.json.formatted)))
This alias depends on the *.install
files used by the opam
integration <../explanation/opam-integration>
. In turn, these depend on installable files.
This alias runs linting tools.
Actions that run tests are attached to this alias. For example this convention is used by the (test)
stanza.
dune runtest
is a shortcut for dune build @runtest
.