179 lines
7.9 KiB
ReStructuredText
179 lines
7.9 KiB
ReStructuredText
********
|
|
Overview
|
|
********
|
|
|
|
.. TODO(diataxis)
|
|
|
|
Split into:
|
|
|
|
- info on the index page
|
|
- :doc:`glossary`
|
|
- a history page that could also explain the various actors
|
|
|
|
Introduction
|
|
============
|
|
|
|
Dune is a build system for OCaml (with support for Reason and Coq). It is not
|
|
intended as a completely generic build system that's able to build any project
|
|
in any language. On the contrary, it makes lots of choices in order to encourage
|
|
a consistent development style.
|
|
|
|
This scheme is inspired from the one used inside Jane Street and adapted to the
|
|
opam world. It has matured over a long time and is used daily by hundreds of
|
|
developers, which means that it is highly tested and productive.
|
|
|
|
When using Dune, you give very little, high-level information to the build
|
|
system, which in turn takes care of all the low-level details from the
|
|
compilation of your libraries, executables, and documentation to the
|
|
installation, setting up of tests, and setting up development tools such as
|
|
Merlin, etc.
|
|
|
|
In addition to the normal features expected from an OCaml build system, Dune
|
|
provides a few additional ones that separate it from the crowd:
|
|
|
|
- You never need to tell Dune the location of things such as libraries. Dune
|
|
will discover them automatically. In particular, this means that when you
|
|
want to reorganise your project, you need nothing other than to rename your
|
|
directories, Dune will do the rest.
|
|
|
|
- Things always work the same whether your dependencies are local or installed
|
|
on the system. In particular, this means that you can insert the source for a
|
|
project dependency in your working copy, and Dune will start using it
|
|
immediately. This makes Dune a great choice for multi-project development.
|
|
|
|
- Cross-platform: as long as your code is portable, Dune will be able to
|
|
cross-compile it. Read more in the :ref:`cross-compilation` section.
|
|
|
|
- Release directly from any revision: Dune needs no setup stage. To release
|
|
your project, simply point to a specific Git tag (named revision). Of course,
|
|
you can add some release steps if you'd like, but it isn't necessary. For
|
|
more information, please refer to dune-release_.
|
|
|
|
.. _dune-release: https://github.com/tarides/dune-release
|
|
|
|
The first section below defines some terms used in this manual. The second
|
|
section specifies the Dune metadata format, and the third one describes how to
|
|
use the ``dune`` command.
|
|
|
|
Terminology
|
|
===========
|
|
|
|
.. glossary::
|
|
root
|
|
The top-most directory in a GitHub repo, workspace, and project,
|
|
differentiated by variables such as ``%{workspace_root}`` and
|
|
``%{project_root}``. Dune builds things from this directory. It knows how to
|
|
build targets that are descendants of the root. Anything outside of the tree
|
|
starting from the root is considered part of the :term:`installed world`.
|
|
Refer to :ref:`finding-root` to learn how the workspace root is determined.
|
|
|
|
workspace
|
|
The subtree starting from each root. It can contain any number of projects
|
|
that will be built simultaneously by Dune, and it must contain a
|
|
``dune-workspace`` file.
|
|
|
|
project
|
|
A collection of source files that must include a ``dune-project`` file. It
|
|
may also contain one or more packages. A project consists in a hierarchy
|
|
of directories. Every directory (at the root, or a subdirectory) can
|
|
contain a ``dune`` file that contains instructions to build files in that
|
|
directory. Projects can be shared between different applications.
|
|
|
|
package
|
|
A set of libraries and executables that opam builds and installs as one.
|
|
|
|
installed world
|
|
Anything outside of the workspace. Dune doesn't know how to build things
|
|
in the installed world.
|
|
|
|
installation
|
|
The action of copying build artifacts or other files from the
|
|
``<root>/_build`` directory to the :term:`installed world`.
|
|
|
|
scope
|
|
Defined by any directory that contains at least one `<package>.opam` file.
|
|
Typically, every project defines a single scope that is a subtree starting
|
|
from this directory. Moreover, scopes are separate from your project's
|
|
dependencies. The scope also determines where private items are visible.
|
|
Private items include libraries or binaries that will not be installed.
|
|
See :doc:`/explanation/scopes` for more details.
|
|
|
|
build context
|
|
A specific configuration written in a
|
|
:doc:`/reference/dune-workspace/index` file, which has a
|
|
corresponding subdirectory in the ``<root>/_build`` directory. It contains
|
|
all the workspace's build artifacts. Without this specific configuration
|
|
from the user, there is always a ``default`` build context that
|
|
corresponds to the executed Dune environment.
|
|
|
|
build context root
|
|
The root of a build context named ``foo`` is ``<root>/_build/<foo>``.
|
|
|
|
build target
|
|
Specified on the command line, e.g., ``dune build <target_path.exe>``. All
|
|
targets that Dune knows how to build live in the ``_build`` directory.
|
|
|
|
alias
|
|
A build target that doesn't produce any file and has configurable
|
|
dependencies. Targets starting with ``@`` on the command line are
|
|
interpreted as aliases (e.g., ``dune build @src/runtest``). Aliases are
|
|
per-directory. See :doc:`reference/aliases`.
|
|
|
|
environment
|
|
Determines the default values of various parameters, such as the
|
|
compilation flags. In Dune, each directory has an environment attached to
|
|
it. Inside a scope, each directory inherits the environment from its
|
|
parent. At the root of every scope, a default environment is used. At any
|
|
point, the environment can be altered using an
|
|
:doc:`/reference/dune/env` stanza.
|
|
|
|
build profile
|
|
A global setting that influences various defaults. It can be set from the
|
|
command line using ``--profile <profile>`` or from ``dune-workspace``
|
|
files. The following profiles are standard:
|
|
|
|
- ``release`` which is the profile used for opam releases
|
|
- ``dev`` which is the default profile when none is set explicitly, it has
|
|
stricter warnings than the ``release`` one
|
|
|
|
dialect
|
|
An alternative frontend to OCaml (such as ReasonML). It is described
|
|
by a pair of file extensions, one corresponding to interfaces and one to
|
|
implementations. It can use the standard OCaml syntax, or it can specify an
|
|
action to convert from a custom syntax to a binary OCaml abstract syntax
|
|
tree. It can also specify a custom formatter.
|
|
|
|
placeholder substitution
|
|
A build step in which placeholders such as ``3.20.2`` in source files
|
|
are replaced by concrete values such as ``1.2.3``. It is performed by
|
|
:ref:`dune-subst` for development versions and dune-release_ for
|
|
releases.
|
|
|
|
stanza
|
|
A fragment of a file interpreted by Dune, that will appear as a
|
|
s-expression at the top-level of a file. For example, the
|
|
:doc:`/reference/dune/library` stanza describes a library. This can be
|
|
either a generic term ("the library stanza") or it can refer to a
|
|
particular instance in a file ("the executable stanza in ``bin/dune``").
|
|
|
|
Project Layout
|
|
==============
|
|
|
|
A typical Dune project will have a ``dune-project`` and one or more
|
|
``<package>.opam`` files at the root as well as ``dune`` files wherever
|
|
interesting things are: libraries, executables, tests, documents to install,
|
|
etc.
|
|
|
|
We recommend organising your project to have exactly one library per
|
|
directory. You can have several executables in the same directory, as long as
|
|
they share the same build configuration. If you'd like to have multiple
|
|
executables with different configurations in the same directory, you will have
|
|
to make an explicit module list for every executable using ``modules``.
|
|
|
|
History
|
|
=======
|
|
|
|
Dune started as ``jbuilder`` in late 2016. When its 1.0.0 version was released
|
|
in 2018, the name has been changed to ``dune``. It used to be configured with
|
|
``jbuild`` and ``jbuild-workspace`` files with a slightly different syntax.
|
|
After a transition period, this syntax is not supported anymore.
|