Port over the dune file description page to dune (#953)
This commit is contained in:
Rudi Grinberg
GitHub
parent
6694dd2714
commit
4c0594caff
|
|
@ -10,19 +10,19 @@ The syntax of ``dune`` files is described in :ref:`metadata-format` section.
|
|||
Stanzas
|
||||
=======
|
||||
|
||||
``jbuild`` files are composed of stanzas. For instance a typical
|
||||
``jbuild`` looks like:
|
||||
``dune`` files are composed of stanzas. For instance a typical
|
||||
``dune`` looks like:
|
||||
|
||||
.. code:: scheme
|
||||
|
||||
(library
|
||||
((name mylib)
|
||||
(libraries (base lwt))))
|
||||
(name mylib)
|
||||
(libraries base lwt))
|
||||
|
||||
(rule
|
||||
((targets (foo.ml))
|
||||
(deps (generator/gen.exe))
|
||||
(action (run ${<} -o ${@}))))
|
||||
(targets foo.ml)
|
||||
(deps generator/gen.exe)
|
||||
(action (run ${<} -o ${@})))
|
||||
|
||||
The following sections describe the available stanzas and their meaning.
|
||||
|
||||
|
|
@ -40,10 +40,10 @@ format of library stanzas is as follows:
|
|||
|
||||
.. code:: scheme
|
||||
|
||||
(library
|
||||
((name <library-name>)
|
||||
library
|
||||
(name <library-name>
|
||||
<optional-fields>
|
||||
))
|
||||
)
|
||||
|
||||
``<library-name>`` is the real name of the library. It determines the
|
||||
names of the archive files generated for the library as well as the
|
||||
|
|
@ -72,14 +72,14 @@ modules you want.
|
|||
|
||||
- ``(modules <modules>)`` specifies what modules are part of the library. By
|
||||
default dune will use all the .ml/.re files in the same directory as the
|
||||
``jbuild`` file. This include ones that are present in the file system as well
|
||||
``dune`` file. This include ones that are present in the file system as well
|
||||
as ones generated by user rules. You can restrict this list by using a
|
||||
``(modules <modules>)`` field. ``<modules>`` uses the `Ordered set language`_
|
||||
where elements are module names and don't need to start with a uppercase
|
||||
letter. For instance to exclude module ``Foo``: ``(modules (:standard \
|
||||
foo))``
|
||||
|
||||
- ``(libraries (<library-dependencies>))`` is used to specify the dependencies
|
||||
- ``(libraries <library-dependencies>)`` is used to specify the dependencies
|
||||
of the library. See the section about `Library dependencies`_ for more details
|
||||
|
||||
- ``(wrapped <boolean>)`` specifies whether the modules of the library should be
|
||||
|
|
@ -114,7 +114,7 @@ modules you want.
|
|||
that must be installed, you must list them in this field, with the ``.h``
|
||||
extension
|
||||
|
||||
- ``(modes (<modes>))`` modes which should be built by default. The
|
||||
- ``(modes <modes>)`` modes which should be built by default. The
|
||||
most common use for this feature is to disable native compilation
|
||||
when writing libraries for the OCaml toplevel. The following modes
|
||||
are available: ``byte``, ``native`` and ``best``. ``best`` is
|
||||
|
|
@ -140,7 +140,7 @@ modules you want.
|
|||
dependencies here. You don't need to do so unless you use dune to
|
||||
synthesize the ``depends`` and ``depopts`` sections of your opam file
|
||||
|
||||
- ``js_of_ocaml``. See the section about :ref:`jbuild-jsoo`
|
||||
- ``js_of_ocaml``. See the section about :ref:`dune-jsoo`
|
||||
|
||||
- ``flags``, ``ocamlc_flags`` and ``ocamlopt_flags``. See the section about
|
||||
`OCaml flags`_
|
||||
|
|
@ -232,18 +232,18 @@ Executables can also be linked as object or shared object files. See
|
|||
|
||||
- ``(public_name <public-name>)`` specifies that the executable should be
|
||||
installed under that name. It is the same as adding the following stanza to
|
||||
your ``jbuild`` file:
|
||||
your ``dune`` file:
|
||||
|
||||
.. code:: scheme
|
||||
|
||||
(install
|
||||
((section bin)
|
||||
(files ((<name>.exe as <public-name>)))))
|
||||
(section bin)
|
||||
(files (<name>.exe as <public-name>)))
|
||||
|
||||
- ``(package <package>)`` if there is a ``(public_name ...)`` field, this
|
||||
specifies the package the executables are part of
|
||||
|
||||
- ``(libraries (<library-dependencies>))`` specifies the library dependencies.
|
||||
- ``(libraries <library-dependencies>)`` specifies the library dependencies.
|
||||
See the section about `Library dependencies`_ for more details
|
||||
|
||||
- ``(link_flags <flags>)`` specifies additional flags to pass to the linker.
|
||||
|
|
@ -362,11 +362,11 @@ it is used to describe several executables sharing the same configuration.
|
|||
It shares the same fields as the ``executable`` stanza, except that instead of
|
||||
``(name ...)`` and ``(public_name ...)`` you must use:
|
||||
|
||||
- ``(names (<names>))`` where ``<names>`` is a list of entry point names. As for
|
||||
- ``(names <names>)`` where ``<names>`` is a list of entry point names. As for
|
||||
``executable`` you only need to specify the modules containing the entry point
|
||||
of each executable
|
||||
|
||||
- ``(public_names (<names>))`` describes under what name each executable should
|
||||
- ``(public_names <names>)`` describes under what name each executable should
|
||||
be installed. The list of names must be of the same length as the list in the
|
||||
``(names ...)`` field. Moreover you can use ``-`` for executables that
|
||||
shouldn't be installed
|
||||
|
|
@ -382,9 +382,9 @@ The syntax is as follows:
|
|||
.. code:: scheme
|
||||
|
||||
(rule
|
||||
((targets (<filenames>))
|
||||
(action <action>)
|
||||
<optional-fields>))
|
||||
(targets <filenames>)
|
||||
(action <action>)
|
||||
<optional-fields>)
|
||||
|
||||
``<filenames>`` is a list of file names. Note that currently dune only
|
||||
support user rules with targets in the current directory.
|
||||
|
|
@ -394,7 +394,7 @@ See the `User actions`_ section for more details.
|
|||
|
||||
``<optional-fields>`` are:
|
||||
|
||||
- ``(deps (<deps-conf list>))`` to specify the dependencies of the
|
||||
- ``(deps <deps-conf list>)`` to specify the dependencies of the
|
||||
rule. See the `Dependency specification`_ section for more details.
|
||||
|
||||
- ``(mode <mode>)`` to specify how to handle the targets, see `modes`_
|
||||
|
|
@ -455,9 +455,9 @@ For instance:
|
|||
.. code:: scheme
|
||||
|
||||
(rule
|
||||
((targets (b)
|
||||
(deps (a)
|
||||
(action (copy ${<} ${@}))))))
|
||||
(targets b
|
||||
(deps a
|
||||
(action (copy ${<} ${@})))))
|
||||
|
||||
In this example it is obvious by inspecting the action what the
|
||||
dependencies and targets are. When this is the case you can use the
|
||||
|
|
@ -491,17 +491,17 @@ ocamllex
|
|||
.. code:: scheme
|
||||
|
||||
(rule
|
||||
((targets (<name>.ml))
|
||||
(deps (<name>.mll))
|
||||
(action (chdir ${ROOT} (run ${bin:ocamllex} -q -o ${<})))))
|
||||
(targets <name>.ml)
|
||||
(deps <name>.mll)
|
||||
(action (chdir ${ROOT} (run ${bin:ocamllex} -q -o ${<}))))
|
||||
|
||||
To use a different rule mode, use the long form:
|
||||
|
||||
.. code:: scheme
|
||||
|
||||
(ocamllex
|
||||
((modules (<names>))
|
||||
(mode <mode>)))
|
||||
(modules (<names>))
|
||||
(mode <mode>))
|
||||
|
||||
ocamlyacc
|
||||
---------
|
||||
|
|
@ -511,17 +511,17 @@ ocamlyacc
|
|||
.. code:: scheme
|
||||
|
||||
(rule
|
||||
((targets (<name>.ml <name>.mli))
|
||||
(deps (<name>.mly))
|
||||
(action (chdir ${ROOT} (run ${bin:ocamlyacc} ${<})))))
|
||||
(targets <name>.ml <name>.mli)
|
||||
(deps <name>.mly)
|
||||
(action (chdir ${ROOT} (run ${bin:ocamlyacc} ${<}))))
|
||||
|
||||
To use a different rule mode, use the long form:
|
||||
|
||||
.. code:: scheme
|
||||
|
||||
(ocamlyacc
|
||||
((modules (<names>))
|
||||
(mode <mode>)))
|
||||
(modules (<names>))
|
||||
(mode <mode>))
|
||||
|
||||
menhir
|
||||
------
|
||||
|
|
@ -542,10 +542,9 @@ The syntax is as follows:
|
|||
.. code:: scheme
|
||||
|
||||
(alias
|
||||
((name <alias-name>)
|
||||
(deps (<deps-conf list>))
|
||||
<optional-fields>
|
||||
))
|
||||
(name <alias-name>)
|
||||
(deps <deps-conf list>)
|
||||
<optional-fields>)
|
||||
|
||||
``<name>`` is an alias name such as ``runtest``.
|
||||
|
||||
|
|
@ -569,8 +568,8 @@ The typical use of the ``alias`` stanza is to define tests:
|
|||
.. code:: scheme
|
||||
|
||||
(alias
|
||||
((name runtest)
|
||||
(action (run ${exe:my-test-program.exe} blah))))
|
||||
(name runtest)
|
||||
(action (run ${exe:my-test-program.exe} blah)))
|
||||
|
||||
See the section about :ref:`running-tests` for details.
|
||||
|
||||
|
|
@ -594,10 +593,9 @@ The syntax is as follows:
|
|||
.. code:: scheme
|
||||
|
||||
(install
|
||||
((section <section>)
|
||||
(files (<filenames>))
|
||||
<optional-fields>
|
||||
))
|
||||
(section <section>)
|
||||
(files <filenames>)
|
||||
<optional-fields>)
|
||||
|
||||
``<section>`` is the installation section, as described in the opam
|
||||
manual. The following sections are available:
|
||||
|
|
@ -631,8 +629,8 @@ instance, to install a file ``mylib.el`` as
|
|||
.. code:: scheme
|
||||
|
||||
(install
|
||||
((section share_root)
|
||||
(files ((mylib.el as emacs/site-lisp/mylib.el)))))
|
||||
(section share_root)
|
||||
(files (mylib.el as emacs/site-lisp/mylib.el)))
|
||||
|
||||
``<optional-fields>`` are:
|
||||
|
||||
|
|
@ -676,32 +674,31 @@ as the difference between the ``copy`` and ``copy#`` action. See the
|
|||
include
|
||||
-------
|
||||
|
||||
The ``include`` stanza allows to include the contents of another file
|
||||
into the current jbuild file. Currently, the included file cannot be
|
||||
generated and must be present in the source tree. This feature is
|
||||
intended to be used in conjunction with promotion, when parts of a
|
||||
jbuild file are to be generated.
|
||||
The ``include`` stanza allows to include the contents of another file into the
|
||||
current dune file. Currently, the included file cannot be generated and must be
|
||||
present in the source tree. This feature is intended to be used in conjunction
|
||||
with promotion, when parts of a dune file are to be generated.
|
||||
|
||||
For instance:
|
||||
|
||||
.. code:: scheme
|
||||
|
||||
(include jbuild.inc)
|
||||
(include dune.inc)
|
||||
|
||||
(rule (with-stdout-to jbuild.inc.gen (run ./gen-jbuild.exe)))
|
||||
(rule (with-stdout-to dune.inc.gen (run ./gen-dune.exe)))
|
||||
|
||||
(alias
|
||||
((name runtest)
|
||||
(action (diff jbuild.inc jbuild.inc.gen))))
|
||||
(name runtest)
|
||||
(action (diff dune.inc dune.inc.gen)))
|
||||
|
||||
With this jbuild file, running dune as follow will replace the
|
||||
``jbuild.inc`` file in the source tree by the generated one:
|
||||
With this dune file, running dune as follow will replace the
|
||||
``dune.inc`` file in the source tree by the generated one:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
$ dune build @runtest --auto-promote
|
||||
|
||||
.. _jbuild-env:
|
||||
.. _dune-env:
|
||||
|
||||
env
|
||||
---
|
||||
|
|
@ -724,7 +721,7 @@ directory. You can use ``_`` to match any build profile.
|
|||
Currently ``<settings>`` can be any OCaml flags field, see `OCaml
|
||||
flags`_ for more details.
|
||||
|
||||
.. _jbuild-ignored_subdirs:
|
||||
.. _dune-ignored_subdirs:
|
||||
|
||||
ignored_subdirs
|
||||
---------------
|
||||
|
|
@ -915,18 +912,18 @@ used as a program name, for instance:
|
|||
.. code:: scheme
|
||||
|
||||
(rule
|
||||
((targets (result.txt))
|
||||
(deps (foo.exe (glob_files *.txt)))
|
||||
(action (run ${^}))))
|
||||
(targets result.txt)
|
||||
(deps foo.exe (glob_files *.txt))
|
||||
(action (run ${^})))
|
||||
|
||||
Here is another example:
|
||||
|
||||
.. code:: scheme
|
||||
|
||||
(rule
|
||||
((targets (foo.exe))
|
||||
(deps (foo.c))
|
||||
(action (run ${CC} -o ${@} ${<} -lfoolib))))
|
||||
(targets foo.exe)
|
||||
(deps foo.c)
|
||||
(action (run ${CC} -o ${@} ${<} -lfoolib)))
|
||||
|
||||
|
||||
Library dependencies
|
||||
|
|
@ -935,11 +932,10 @@ Library dependencies
|
|||
Dependencies on libraries are specified using ``(libraries ...)`` fields in
|
||||
``library`` and ``executables`` stanzas.
|
||||
|
||||
For libraries defined in the current scope, you can use either the
|
||||
real name or the public name. For libraries that are part of the
|
||||
installed world, or for libraries that are part of the current
|
||||
workspace but in another scope, you need to use the public name. For
|
||||
instance: ``(libraries (base re))``.
|
||||
For libraries defined in the current scope, you can use either the real name or
|
||||
the public name. For libraries that are part of the installed world, or for
|
||||
libraries that are part of the current workspace but in another scope, you need
|
||||
to use the public name. For instance: ``(libraries base re)``.
|
||||
|
||||
When resolving libraries, libraries that are part of the workspace are always
|
||||
preferred to ones that are part of the installed world.
|
||||
|
|
@ -1011,9 +1007,9 @@ you had setup a rule for every file of the form:
|
|||
.. code:: scheme
|
||||
|
||||
(rule
|
||||
((targets (file.pp.ml))
|
||||
(deps (file.ml))
|
||||
(action (with-stdout-to ${@} (chdir ${ROOT} <action>)))))
|
||||
(targets file.pp.ml)
|
||||
(deps file.ml)
|
||||
(action (with-stdout-to ${@} (chdir ${ROOT} <action>))))
|
||||
|
||||
The equivalent of a ``-pp <command>`` option passed to the OCaml compiler is
|
||||
``(system "<command> ${<}")``.
|
||||
|
|
@ -1074,7 +1070,7 @@ For instance:
|
|||
Dependency specification
|
||||
------------------------
|
||||
|
||||
Dependencies in ``jbuild`` files can be specified using one of the following
|
||||
Dependencies in ``dune`` files can be specified using one of the following
|
||||
syntax:
|
||||
|
||||
- ``(file <filename>)`` or simply ``<filename>``: depend on this file
|
||||
|
|
@ -1156,7 +1152,7 @@ follows:
|
|||
|
||||
(flags (:standard <my options>))
|
||||
|
||||
.. _jbuild-jsoo:
|
||||
.. _dune-jsoo:
|
||||
|
||||
js_of_ocaml
|
||||
-----------
|
||||
|
|
@ -1186,8 +1182,8 @@ User actions
|
|||
``(action ...)`` fields describe user actions.
|
||||
|
||||
User actions are always run from the same subdirectory of the current build
|
||||
context as the jbuild they are defined in. So for instance an action defined in
|
||||
``src/foo/jbuild`` will be run from ``_build/<context>/src/foo``.
|
||||
context as the dune file they are defined in. So for instance an action defined
|
||||
in ``src/foo/dune`` will be run from ``_build/<context>/src/foo``.
|
||||
|
||||
The argument of ``(action ...)`` fields is a small DSL that is interpreted by
|
||||
dune directly and doesn't require an external shell. All atoms in the DSL
|
||||
|
|
@ -1252,26 +1248,26 @@ something shorter.
|
|||
|
||||
Note: expansion of the special ``${<kind>:...}`` is done relative to the current
|
||||
working directory of the part of the DSL being executed. So for instance if you
|
||||
have this action in a ``src/foo/jbuild``:
|
||||
have this action in a ``src/foo/dune``:
|
||||
|
||||
.. code:: scheme
|
||||
|
||||
(action (chdir ../../.. (echo ${path:jbuild})))
|
||||
(action (chdir ../../.. (echo ${path:dune})))
|
||||
|
||||
Then ``${path:jbuild}`` will expand to ``src/foo/jbuild``. When you run various
|
||||
Then ``${path:dune}`` will expand to ``src/foo/dune``. When you run various
|
||||
tools, they often use the filename given on the command line in error messages.
|
||||
As a result, if you execute the command from the original directory, it will
|
||||
only see the basename.
|
||||
|
||||
To understand why this is important, let's consider this jbuild living in
|
||||
To understand why this is important, let's consider this dune file living in
|
||||
``src/foo``:
|
||||
|
||||
::
|
||||
|
||||
(rule
|
||||
((targets (blah.ml))
|
||||
(deps (blah.mll))
|
||||
(action (run ocamllex -o ${@} ${<}))))
|
||||
(targets blah.ml)
|
||||
(deps blah.mll)
|
||||
(action (run ocamllex -o ${@} ${<})))
|
||||
|
||||
Here the command that will be executed is:
|
||||
|
||||
|
|
@ -1293,9 +1289,9 @@ of your project. What you should write instead is:
|
|||
::
|
||||
|
||||
(rule
|
||||
((targets (blah.ml))
|
||||
(deps (blah.mll))
|
||||
(action (chdir ${ROOT} (run ocamllex -o ${@} ${<})))))
|
||||
(targets blah.ml)
|
||||
(deps blah.mll)
|
||||
(action (chdir ${ROOT} (run ocamllex -o ${@} ${<}))))
|
||||
|
||||
Locks
|
||||
-----
|
||||
|
|
@ -1315,37 +1311,36 @@ same lock:
|
|||
.. code:: scheme
|
||||
|
||||
(alias
|
||||
((name runtest)
|
||||
(deps (foo))
|
||||
(locks (m))
|
||||
(action (run test.exe ${<}))))
|
||||
(name runtest)
|
||||
(deps foo)
|
||||
(locks m)
|
||||
(action (run test.exe ${<})))
|
||||
|
||||
(alias
|
||||
((name runtest)
|
||||
(deps (bar))
|
||||
(locks (m))
|
||||
(action (run test.exe ${<}))))
|
||||
(name runtest)
|
||||
(deps bar)
|
||||
(locks m)
|
||||
(action (run test.exe ${<})))
|
||||
|
||||
Dune will make sure that the executions of ``test.exe foo`` and
|
||||
``test.exe bar`` are serialized.
|
||||
|
||||
Although they don't live in the filesystem, lock names are interpreted
|
||||
as file names. So for instance ``(with-lock m ...)`` in ``src/jbuild``
|
||||
and ``(with-lock ../src/m)`` in ``test/jbuild`` refer to the same
|
||||
lock.
|
||||
Although they don't live in the filesystem, lock names are interpreted as file
|
||||
names. So for instance ``(with-lock m ...)`` in ``src/dune`` and ``(with-lock
|
||||
../src/m)`` in ``test/dune`` refer to the same lock.
|
||||
|
||||
Note also that locks are per build context. So if your workspace has
|
||||
two build contexts setup, the same rule might still be executed
|
||||
concurrently between the two build contexts. If you want a lock that
|
||||
is global to all build contexts, simply use an absolute filename:
|
||||
Note also that locks are per build context. So if your workspace has two build
|
||||
contexts setup, the same rule might still be executed concurrently between the
|
||||
two build contexts. If you want a lock that is global to all build contexts,
|
||||
simply use an absolute filename:
|
||||
|
||||
.. code:: scheme
|
||||
|
||||
(alias
|
||||
((name runtest)
|
||||
(deps (foo))
|
||||
(locks (/tcp-port/1042))
|
||||
(action (run test.exe ${<}))))
|
||||
(name runtest)
|
||||
(deps foo)
|
||||
(locks /tcp-port/1042)
|
||||
(action (run test.exe ${<})))
|
||||
|
||||
.. _ocaml-syntax:
|
||||
|
||||
|
|
@ -1396,7 +1391,7 @@ Whenever an action ``(diff <file1> <file2>)`` or ``(diff? <file1>
|
|||
you to promote ``<file2>`` as ``<file1>`` if ``<file1>`` is a source
|
||||
file and ``<file2>`` is a generated file.
|
||||
|
||||
More precisely, let's consider the following jbuild file:
|
||||
More precisely, let's consider the following dune file:
|
||||
|
||||
.. code:: scheme
|
||||
|
||||
|
|
@ -1404,8 +1399,8 @@ More precisely, let's consider the following jbuild file:
|
|||
(with-stdout-to data.out (run ./test.exe)))
|
||||
|
||||
(alias
|
||||
((name runtest)
|
||||
(action (diff data.expected data.out))))
|
||||
(name runtest)
|
||||
(action (diff data.expected data.out)))
|
||||
|
||||
Where ``data.expected`` is a file committed in the source
|
||||
repository. You can use the following workflow to update your test:
|
||||
|
|
@ -1423,8 +1418,8 @@ automatically do the promotion.
|
|||
OCaml syntax
|
||||
============
|
||||
|
||||
If a ``jbuild`` file starts with ``(* -*- tuareg -*- *)``, then it is
|
||||
interpreted as an OCaml script that generates the ``jbuild`` file as described
|
||||
If a ``dune`` file starts with ``(* -*- tuareg -*- *)``, then it is
|
||||
interpreted as an OCaml script that generates the ``dune`` file as described
|
||||
in the rest of this section. The code in the script will have access to a
|
||||
`Jbuild_plugin
|
||||
<https://github.com/ocaml/dune/blob/master/plugin/jbuild_plugin.mli>`__
|
||||
|
|
|
|||
|
|
@ -287,4 +287,4 @@ jbuild-ignore (deprecated)
|
|||
==========================
|
||||
|
||||
``jbuild-ignore`` files are deprecated and replaced by
|
||||
:ref:`jbuild-ignored_subdirs` stanzas in ``dune`` files.
|
||||
:ref:`dune-ignored_subdirs` stanzas in ``dune`` files.
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ Terminology
|
|||
various parameters, such as the compilation flags. Inside a scope,
|
||||
each directory inherit 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 :ref:`jbuild-env` stanza.
|
||||
environment can be altered using an :ref:`dune-env` stanza.
|
||||
|
||||
- **build profile**: a global setting that influence various
|
||||
defaults. It can be set from the command line using ``--profile
|
||||
|
|
|
|||
|
|
@ -447,7 +447,7 @@ The separate compilation mode will be selected when the build profile
|
|||
is ``dev``, which is the default. There is currently no other way to
|
||||
control this behaviour.
|
||||
|
||||
See the section about :ref:`jbuild-jsoo` for passing custom flags to the
|
||||
See the section about :ref:`dune-jsoo` for passing custom flags to the
|
||||
js_of_ocaml compiler
|
||||
|
||||
.. _using-topkg:
|
||||
|
|
|
|||
Loading…
Reference in New Issue