********
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, and
        which has warnings-as-errors turned on.

   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.23.1`` 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.
