matthieu
/
dune
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge pull request #931 from emillon/docs-rename-jbuilder-command 

Rename jbuilder to dune in docs
This commit is contained in:
Etienne Millon 2018-07-02 10:23:37 +02:00 committed by GitHub
parent 438fef915f 2f5ac86c71
commit 9254f30cc0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 220 additions and 223 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
doc/advanced-topics.rst
View File

@ -2,28 +2,28 @@
Advanced topics Advanced topics
*************** ***************
This section describes some details of Jbuilder for advanced users. This section describes some details of dune for advanced users.
META file generation META file generation
==================== ====================
Jbuilder uses ``META`` files from the `findlib library Dune uses ``META`` files from the `findlib library
manager <http://projects.camlcity.org/projects/findlib.html>`__ in order manager <http://projects.camlcity.org/projects/findlib.html>`__ in order
to interoperate with the rest of the world when installing libraries. It to interoperate with the rest of the world when installing libraries. It
is able to generate them automatically. However, for the rare cases is able to generate them automatically. However, for the rare cases
where you would need a specific ``META`` file, or to ease the transition where you would need a specific ``META`` file, or to ease the transition
of a project to Jbuilder, it is allowed to write/generate a specific of a project to dune, it is allowed to write/generate a specific
one. one.
In order to do that, write or setup a rule to generate a In order to do that, write or setup a rule to generate a
``META.<package>.template`` file in the same directory as the ``META.<package>.template`` file in the same directory as the
``<package>.opam`` file. Jbuilder will generate a ``META.<package>`` ``<package>.opam`` file. Dune will generate a ``META.<package>``
file from the ``META.<package>.template`` file by replacing lines of file from the ``META.<package>.template`` file by replacing lines of
the form ``# JBUILDER_GEN`` by the contents of the ``META`` it would the form ``# JBUILDER_GEN`` by the contents of the ``META`` it would
normally generate. normally generate.
For instance if you want to extend the ``META`` file generated by For instance if you want to extend the ``META`` file generated by
Jbuilder you can write the folliwing ``META.foo.template`` file: dune you can write the folliwing ``META.foo.template`` file:
.. code:: .. code::
@ -33,7 +33,7 @@ Jbuilder you can write the folliwing ``META.foo.template`` file:
Findlib integration and limitations Findlib integration and limitations
=================================== ===================================
Jbuilder uses ``META`` files to support external libraries. However, it Dune uses ``META`` files to support external libraries. However, it
doesn't export the full power of findlib to the user, and especially doesn't export the full power of findlib to the user, and especially
it doesn't let the user specify *predicates*. it doesn't let the user specify *predicates*.
@ -41,13 +41,13 @@ The reason for this limitation is that so far they haven't been
needed, and adding full support for them would complicate things quite needed, and adding full support for them would complicate things quite
a lot. In particular, complex ``META`` files are often hand-written and a lot. In particular, complex ``META`` files are often hand-written and
the various features they offer are only available once the package is the various features they offer are only available once the package is
installed, which goes against the root ideas jbuilder is built on. installed, which goes against the root ideas dune is built on.
In practice, jbuilder interpret ``META`` files assuming the following In practice, dune interprets ``META`` files assuming the following
set of predicates: set of predicates:
- ``mt``: what this means is that using a library that can be used - ``mt``: what this means is that using a library that can be used
with or without threads with jbuilder will force the threaded with or without threads with dune will force the threaded
version version
- ``mt_posix``: forces the use of posix threads rather than VM - ``mt_posix``: forces the use of posix threads rather than VM
@ -62,7 +62,7 @@ set of predicates:
Cross Compilation Cross Compilation
================= =================
Jbuilder allows for cross compilation by defining build contexts with Dune allows for cross compilation by defining build contexts with
multiple targets. Targets are specified by adding a ``targets`` field multiple targets. Targets are specified by adding a ``targets`` field
to the definition of a build context. to the definition of a build context.
@ -74,7 +74,7 @@ to the definition of a build context.
- the name of an alternative toolchain - the name of an alternative toolchain
Note that at the moment, there is no official support for Note that at the moment, there is no official support for
cross-compilation in OCaml. Jbuilder supports the opam-cross-x cross-compilation in OCaml. Dune supports the opam-cross-x
repositories from the `ocaml-cross organization on github repositories from the `ocaml-cross organization on github
<https://github.com/ocaml-cross/>`_, such as: <https://github.com/ocaml-cross/>`_, such as:
@ -105,11 +105,11 @@ This configuration defines three build contexts:
- ``default.android`` - ``default.android``
Note that the ``native`` target is always implicitly added when not Note that the ``native`` target is always implicitly added when not
present. However, when implicitly added ``jbuilder build @install`` present. However, when implicitly added ``dune build @install``
will skip this context, i.e. ``default`` will only be used for will skip this context, i.e. ``default`` will only be used for
building executables needed by the other contexts. building executables needed by the other contexts.
With such a setup, calling ``jbuilder build @install`` will build all With such a setup, calling ``dune build @install`` will build all
the packages three times. the packages three times.
Note that instead of writing a ``dune-workspace`` file, you can also Note that instead of writing a ``dune-workspace`` file, you can also
@ -142,13 +142,13 @@ following ``src/jbuild`` file:
(executable ((name foo))) (executable ((name foo)))
(rule (with-stdout-to blah (run ./foo.exe))) (rule (with-stdout-to blah (run ./foo.exe)))
When building ``_build/default/src/blah``, jbuilder will resolve ``./foo.exe`` to When building ``_build/default/src/blah``, dune will resolve ``./foo.exe`` to
``_build/default/src/foo.exe`` as expected. However, for ``_build/default/src/foo.exe`` as expected. However, for
``_build/default.windows/src/blah`` jbuilder will resolve ``./foo.exe`` to ``_build/default.windows/src/blah`` dune will resolve ``./foo.exe`` to
``_build/default/src/foo.exe`` ``_build/default/src/foo.exe``
Assuming that the right packages are installed or that your workspace Assuming that the right packages are installed or that your workspace
has no external dependencies, jbuilder will be able to cross-compile a has no external dependencies, dune will be able to cross-compile a
given package without doing anything special. given package without doing anything special.
Some packages might still have to be updated to support cross-compilation. For Some packages might still have to be updated to support cross-compilation. For
@ -164,6 +164,6 @@ Classical ppx
*classical ppx* refers to running ppx using the -ppx compiler option, which is *classical ppx* refers to running ppx using the -ppx compiler option, which is
composed using Findlib. Even though this is useful to run some (usually old) composed using Findlib. Even though this is useful to run some (usually old)
ppx's which don't support drivers, Jbuilder does not support preprocessing with ppx's which don't support drivers, dune does not support preprocessing with
ppx this way. but a workaround exists using the `ppxfind ppx this way. but a workaround exists using the `ppxfind
<https://github.com/diml/ppxfind>`_ tool. <https://github.com/diml/ppxfind>`_ tool.

12
doc/documentation.rst
View File

@ -7,8 +7,8 @@ Generating Documentation
Prerequisites Prerequisites
============= =============
Documentation in jbuilder is done courtesy of the odoc_ tool. Therefore, to Documentation in dune is done courtesy of the odoc_ tool. Therefore, to
generate documentation in jbuilder, you will need to install this tool. This generate documentation in dune, you will need to install this tool. This
should likely be done with opam: should likely be done with opam:
:: ::
@ -33,7 +33,7 @@ to generate documentation for your project is building this alias:
:: ::
$ jbuilder build @doc $ dune build @doc
An index page containing links to all the opam packages in your project can be An index page containing links to all the opam packages in your project can be
found in: found in:
@ -46,7 +46,7 @@ Documentation for private libraries may also be built with:
:: ::
$ jbuilder build @doc-private $ dune build @doc-private
But this libraries will not be in the main html listing above, since they do not But this libraries will not be in the main html listing above, since they do not
belong to any particular package. But the generated html will still be found in belong to any particular package. But the generated html will still be found in
@ -70,7 +70,7 @@ in the same syntax as ocamldoc comments.
Where ``<optional-fields>`` are: Where ``<optional-fields>`` are:
- ``(package <name>)`` the package this documentation should be attached to. If - ``(package <name>)`` the package this documentation should be attached to. If
this absent, jbuilder will try to infer it based on the location of the this absent, dune will try to infer it based on the location of the
stanza. stanza.
- ``(mld_files <arg>)`` where ``<arg>`` field follows the - ``(mld_files <arg>)`` where ``<arg>`` field follows the
@ -81,7 +81,7 @@ Where ``<optional-fields>`` are:
The ``index.mld`` file (specified as ``index`` in ``mld_files``) is treated The ``index.mld`` file (specified as ``index`` in ``mld_files``) is treated
specially by jbulder. This will be the file used to generate the entry page for specially by jbulder. This will be the file used to generate the entry page for
the package. This is the page that will be linked from the main package listing. the package. This is the page that will be linked from the main package listing.
If you omit writing an ``index.mld``, jbuilder will generate one with the entry If you omit writing an ``index.mld``, dune will generate one with the entry
modules for your package. But this generated will not be installed. modules for your package. But this generated will not be installed.
All mld files attached to a package will be included in the generated All mld files attached to a package will be included in the generated

118
doc/jbuild.rst → doc/dune-files.rst
View File

@ -1,13 +1,11 @@
******************** **********
jbuild specification dune files
******************** **********
``jbuild`` files are the main part of Jbuilder, and are the origin of ``dune`` files are the main part of dune. They are used to describe libraries,
its name. They are used to describe libraries, executables, tests, and executables, tests, and everything dune needs to know about.
everything Jbuilder needs to know about.
The syntax of ``jbuild`` files is described in The syntax of ``dune`` files is described in :ref:`metadata-format` section.
:ref:``metadata-format`` section.
Stanzas Stanzas
======= =======
@ -64,16 +62,16 @@ modules you want.
- ``(public_name <name>)`` this is the name under which the library can be - ``(public_name <name>)`` this is the name under which the library can be
referred to as a dependency when it is not part of the current workspace, referred to as a dependency when it is not part of the current workspace,
i.e. when it is installed. Without a ``(public_name ...)`` field, the library i.e. when it is installed. Without a ``(public_name ...)`` field, the library
will not be installed by Jbuilder. The public name must start by the package will not be installed by dune. The public name must start by the package
name it is part of and optionally followed by a dot and anything else you name it is part of and optionally followed by a dot and anything else you
want. The package name must be one of the packages that Jbuilder knows about, want. The package name must be one of the packages that dune knows about,
as determined by the :ref:`opam-files` as determined by the :ref:`opam-files`
- ``(synopsis <string>)`` should give a one-line description of the library. - ``(synopsis <string>)`` should give a one-line description of the library.
This is used by tools that list installed libraries This is used by tools that list installed libraries
- ``(modules <modules>)`` specifies what modules are part of the library. By - ``(modules <modules>)`` specifies what modules are part of the library. By
default Jbuilder will use all the .ml/.re files in the same directory as the 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 ``jbuild`` 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 as ones generated by user rules. You can restrict this list by using a
``(modules <modules>)`` field. ``<modules>`` uses the `Ordered set language`_ ``(modules <modules>)`` field. ``<modules>`` uses the `Ordered set language`_
@ -91,7 +89,7 @@ modules you want.
an executables, polluting the top-level namespace will make your library an executables, polluting the top-level namespace will make your library
unusable with other libraries if there is a module name clash. This option is unusable with other libraries if there is a module name clash. This option is
only intended for libraries that manually prefix all their modules by the only intended for libraries that manually prefix all their modules by the
library name and to ease porting of existing projects to Jbuilder library name and to ease porting of existing projects to dune
- ``(preprocess <preprocess-spec>)`` specifies how to preprocess files if - ``(preprocess <preprocess-spec>)`` specifies how to preprocess files if
needed. The default is ``no_processing``. Other options are described in the needed. The default is ``no_processing``. Other options are described in the
@ -139,7 +137,7 @@ modules you want.
feature only if another package is installed. This is for instance the case of feature only if another package is installed. This is for instance the case of
``ctypes`` which will only install ``ctypes.foreign`` if the dummy ``ctypes`` which will only install ``ctypes.foreign`` if the dummy
``ctypes-foreign`` package is installed. You can specify such virtual ``ctypes-foreign`` package is installed. You can specify such virtual
dependencies here. You don't need to do so unless you use Jbuilder to dependencies here. You don't need to do so unless you use dune to
synthesize the ``depends`` and ``depopts`` sections of your opam file 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:`jbuild-jsoo`
@ -164,7 +162,7 @@ modules you want.
``-lbar`` here, or whatever flags are necessary to to link against this ``-lbar`` here, or whatever flags are necessary to to link against this
library library
- ``(self_build_stubs_archive <c-libname>)`` indicates to Jbuilder that the - ``(self_build_stubs_archive <c-libname>)`` indicates to dune that the
library has stubs, but that the stubs are built manually. The aim of the field library has stubs, but that the stubs are built manually. The aim of the field
is to embed a library written in foreign language and/or building with another is to embed a library written in foreign language and/or building with another
build system. It is not for casual uses, see the `re2 library build system. It is not for casual uses, see the `re2 library
@ -175,8 +173,8 @@ modules you want.
``.re`` file. Such modules are usually referred as *mli only ``.re`` file. Such modules are usually referred as *mli only
modules*. They are not officially supported by the OCaml compiler, modules*. They are not officially supported by the OCaml compiler,
however they are commonly used. Such modules must only define however they are commonly used. Such modules must only define
types. Since it is not reasonably possible for Jbuilder to check types. Since it is not reasonably possible for dune to check
that this is the case, Jbuilder requires the user to explicitly list that this is the case, dune requires the user to explicitly list
such modules to avoid surprises. ``<modules>`` must be a subset of such modules to avoid surprises. ``<modules>`` must be a subset of
the modules listed in the ``(modules ...)`` field. the modules listed in the ``(modules ...)`` field.
@ -186,7 +184,7 @@ modules you want.
- ``(no_keep_locs)`` undocumented, it is a necessary hack until this - ``(no_keep_locs)`` undocumented, it is a necessary hack until this
is implemented: https://github.com/ocaml/dune/issues/921 is implemented: https://github.com/ocaml/dune/issues/921
Note that when binding C libraries, Jbuilder doesn't provide special support for Note that when binding C libraries, dune doesn't provide special support for
tools such as ``pkg-config``, however it integrates easily with configurator_ by tools such as ``pkg-config``, however it integrates easily with configurator_ by
using ``(c_flags (:include ...))`` and ``(c_library_flags (:include ...))``. using ``(c_flags (:include ...))`` and ``(c_library_flags (:include ...))``.
@ -208,7 +206,7 @@ format of executable stanzas is as follows:
``<name>`` is a module name that contains the main entry point of the ``<name>`` is a module name that contains the main entry point of the
executable. There can be additional modules in the current directory, you only executable. There can be additional modules in the current directory, you only
need to specify the entry point. Given an ``executable`` stanza with ``(name need to specify the entry point. Given an ``executable`` stanza with ``(name
<name>)``, Jbuilder will know how to build ``<name>.exe``, ``<name>.bc`` and <name>)``, dune will know how to build ``<name>.exe``, ``<name>.bc`` and
``<name>.bc.js``. ``<name>.exe`` is a native code executable, ``<name>.bc`` is a ``<name>.bc.js``. ``<name>.exe`` is a native code executable, ``<name>.bc`` is a
bytecode executable which requires ``ocamlrun`` to run and ``<name>.bc.js`` is a bytecode executable which requires ``ocamlrun`` to run and ``<name>.bc.js`` is a
JavaScript generated using js_of_ocaml. JavaScript generated using js_of_ocaml.
@ -222,7 +220,7 @@ usually preferable to use ``<name>.exe`` in custom rules or when
calling the executable by hand. This is because running a byte-code calling the executable by hand. This is because running a byte-code
executable often requires loading shared libraries that are locally executable often requires loading shared libraries that are locally
built, and so requires additional setup such as setting specific built, and so requires additional setup such as setting specific
environment variables and jbuilder doesn't do at the moment. environment variables and dune doesn't do at the moment.
Native compilation is considered not available when there is no ``ocamlopt`` Native compilation is considered not available when there is no ``ocamlopt``
binary at the same place as where ``ocamlc`` was found. binary at the same place as where ``ocamlc`` was found.
@ -256,7 +254,7 @@ Executables can also be linked as object or shared object files. See
specification`_ section for more details. specification`_ section for more details.
- ``(modules <modules>)`` specifies which modules in the current directory - ``(modules <modules>)`` specifies which modules in the current directory
Jbuilder should consider when building this executable. Modules not listed dune should consider when building this executable. Modules not listed
here will be ignored and cannot be used inside the executable described by here will be ignored and cannot be used inside the executable described by
the current stanza. It is interpreted in the same way as the ``(modules the current stanza. It is interpreted in the same way as the ``(modules
...)`` field of `library`_ ...)`` field of `library`_
@ -376,7 +374,7 @@ It shares the same fields as the ``executable`` stanza, except that instead of
rule rule
---- ----
The ``rule`` stanza is used to create custom user rules. It tells Jbuilder how The ``rule`` stanza is used to create custom user rules. It tells dune how
to generate a specific set of files from a specific set of dependencies. to generate a specific set of files from a specific set of dependencies.
The syntax is as follows: The syntax is as follows:
@ -388,7 +386,7 @@ The syntax is as follows:
(action <action>) (action <action>)
<optional-fields>)) <optional-fields>))
``<filenames>`` is a list of file names. Note that currently Jbuilder only ``<filenames>`` is a list of file names. Note that currently dune only
support user rules with targets in the current directory. support user rules with targets in the current directory.
``<action>`` is the action to run to produce the targets from the dependencies. ``<action>`` is the action to run to produce the targets from the dependencies.
@ -415,7 +413,7 @@ modes
~~~~~ ~~~~~
By default, the target of a rule must not exist in the source tree and By default, the target of a rule must not exist in the source tree and
Jbuilder will error out when this is the case. dune will error out when this is the case.
However, it is possible to change this behavior using the ``mode`` However, it is possible to change this behavior using the ``mode``
field. The following modes are available: field. The following modes are available:
@ -423,7 +421,7 @@ field. The following modes are available:
- ``standard``, this is the standard mode - ``standard``, this is the standard mode
- ``fallback``, in this mode, when the targets are already present in - ``fallback``, in this mode, when the targets are already present in
the source tree, jbuilder will ignore the rule. It is an error if the source tree, dune will ignore the rule. It is an error if
only a subset of the targets are present in the tree. The common use only a subset of the targets are present in the tree. The common use
of fallback rules is to generate default configuration files that of fallback rules is to generate default configuration files that
may be generated by a configure script. may be generated by a configure script.
@ -433,7 +431,7 @@ field. The following modes are available:
back to the source tree back to the source tree
- ``promote-until-clean`` is the same as ``promote`` except than - ``promote-until-clean`` is the same as ``promote`` except than
``jbuilder clean`` will remove the promoted files from the source ``dune clean`` will remove the promoted files from the source
tree tree
@ -441,7 +439,7 @@ There are two use cases for promote rules. The first one is when the
generated code is easier to review than the generator, so it's easier generated code is easier to review than the generator, so it's easier
to commit the generated code and review it. The second is to cut down to commit the generated code and review it. The second is to cut down
dependencies during releases: by passing ``--ignore-promoted-rules`` dependencies during releases: by passing ``--ignore-promoted-rules``
to jbuilder, rules will ``(mode promote)`` will be ignored and the to dune, rules will ``(mode promote)`` will be ignored and the
source files will be used instead. The source files will be used instead. The
``-p/--for-release-of-packages`` flag implies ``-p/--for-release-of-packages`` flag implies
``--ignore-promote-rules``. ``--ignore-promote-rules``.
@ -463,7 +461,7 @@ For instance:
In this example it is obvious by inspecting the action what the 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 dependencies and targets are. When this is the case you can use the
following shorter syntax, where Jbuilder infers dependencies and following shorter syntax, where dune infers dependencies and
targets for you: targets for you:
.. code:: scheme .. code:: scheme
@ -476,10 +474,10 @@ For instance:
(rule (copy a b)) (rule (copy a b))
Note that in Jbuilder, targets must always be known Note that in dune, targets must always be known
statically. Especially, this mean that Jbuilder must be able to statically. Especially, this mean that dune must be able to
statically determine all targets. For instance, this ``(rule ...)`` statically determine all targets. For instance, this ``(rule ...)``
stanza is rejected by Jbuilder: stanza is rejected by dune:
.. code:: scheme .. code:: scheme
@ -584,8 +582,8 @@ tests.
install install
------- -------
The ``install`` stanza is what lets you describe what Jbuilder should install, The ``install`` stanza is what lets you describe what dune should install,
either when running ``jbuilder install`` or through opam. either when running ``dune install`` or through opam.
Libraries and executables don't need an ``install`` stanza to be Libraries and executables don't need an ``install`` stanza to be
installed, just a ``public_name`` field. Everything else needs an installed, just a ``public_name`` field. Everything else needs an
@ -645,12 +643,12 @@ Handling of the .exe extension on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Under Microsoft Windows, executables must be suffixed with Under Microsoft Windows, executables must be suffixed with
``.exe``. Jbuilder tries to make sure that executables are always ``.exe``. Dune tries to make sure that executables are always
installed with this extension on Windows. installed with this extension on Windows.
More precisely, when installing a file via an ``(install ...)`` More precisely, when installing a file via an ``(install ...)``
stanza, if the source file has extension ``.exe`` or ``.bc``, then stanza, if the source file has extension ``.exe`` or ``.bc``, then
Jbuilder implicitly adds the ``.exe`` extension to the destination, if dune implicitly adds the ``.exe`` extension to the destination, if
not already present. not already present.
copy_files copy_files
@ -694,12 +692,12 @@ For instance:
((name runtest) ((name runtest)
(action (diff jbuild.inc jbuild.inc.gen)))) (action (diff jbuild.inc jbuild.inc.gen))))
With this jbuild file, running jbuilder as follow will replace the With this jbuild file, running dune as follow will replace the
``jbuild.inc`` file in the source tree by the generated one: ``jbuild.inc`` file in the source tree by the generated one:
.. code:: shell .. code:: shell
$ jbuilder build @runtest --auto-promote $ dune build @runtest --auto-promote
.. _jbuild-env: .. _jbuild-env:
@ -752,7 +750,7 @@ Ordered set language
A few fields takes as argument an ordered set and can be specified using a small A few fields takes as argument an ordered set and can be specified using a small
DSL. DSL.
This DSL is interpreted by jbuilder into an ordered set of strings using the This DSL is interpreted by dune into an ordered set of strings using the
following rules: following rules:
- ``:standard`` denotes the standard value of the field when it is absent - ``:standard`` denotes the standard value of the field when it is absent
@ -786,9 +784,9 @@ Variables expansion
------------------- -------------------
Some fields can contains variables of the form ``$(var)`` or ``${var}`` that are Some fields can contains variables of the form ``$(var)`` or ``${var}`` that are
expanded by Jbuilder. expanded by dune.
Jbuilder supports the following variables: Dune supports the following variables:
- ``ROOT`` is the relative path to the root of the build - ``ROOT`` is the relative path to the root of the build
context. Note that ``ROOT`` depends on the worksace context. Note that ``ROOT`` depends on the worksace
@ -816,12 +814,12 @@ Jbuilder supports the following variables:
- ``ext_obj``, ``ext_asm``, ``ext_lib``, ``ext_dll`` and ``ext_exe`` - ``ext_obj``, ``ext_asm``, ``ext_lib``, ``ext_dll`` and ``ext_exe``
are the file extension used for various artifacts are the file extension used for various artifacts
- ``ocaml-config:v`` for every variable ``v`` in the output of - ``ocaml-config:v`` for every variable ``v`` in the output of
``ocamlc -config``. Note that output Jbuilder processes the output ``ocamlc -config``. Note that dune processes the output
of ``ocamlc -config`` in order to make it a bit more stable across of ``ocamlc -config`` in order to make it a bit more stable across
versions, so the exact set of variables accessible this way might versions, so the exact set of variables accessible this way might
not be exactly the same as what you can see in the output of not be exactly the same as what you can see in the output of
``ocamlc -config``. In particular, variables added in new versions ``ocamlc -config``. In particular, variables added in new versions
of OCaml needs to be registered in Jbuilder before they can be used of OCaml needs to be registered in dune before they can be used
- ``profile`` the profile selected via ``--profile`` - ``profile`` the profile selected via ``--profile``
In addition, ``(action ...)`` fields support the following special variables: In addition, ``(action ...)`` fields support the following special variables:
@ -961,7 +959,7 @@ It is sometimes the case that one wants to not depend on a specific library, but
instead on whatever is already installed. For instance to use a different instead on whatever is already installed. For instance to use a different
backend depending on the target. backend depending on the target.
Jbuilder allows this by using a ``(select ... from ...)`` form inside the list Dune allows this by using a ``(select ... from ...)`` form inside the list
of library dependencies. of library dependencies.
Select forms are specified as follows: Select forms are specified as follows:
@ -980,7 +978,7 @@ Select forms are specified as follows:
- ``!<library-name>``, which will evaluate to true if ``<library-name>`` is not - ``!<library-name>``, which will evaluate to true if ``<library-name>`` is not
available in the workspace or in the installed world available in the workspace or in the installed world
When evaluating a select form, Jbuilder will create ``<target-filename>`` by When evaluating a select form, dune will create ``<target-filename>`` by
copying the file given by the first ``(<literals> -> <filename>)`` case where copying the file given by the first ``(<literals> -> <filename>)`` case where
all the literals evaluate to true. It is an error if none of the clauses are all the literals evaluate to true. It is an error if none of the clauses are
selectable. You can add a fallback by adding a clause of the form ``(-> selectable. You can add a fallback by adding a clause of the form ``(->
@ -989,7 +987,7 @@ selectable. You can add a fallback by adding a clause of the form ``(->
Preprocessing specification Preprocessing specification
--------------------------- ---------------------------
Jbuilder accepts three kinds of preprocessing: Dune accepts three kinds of preprocessing:
- ``no_preprocessing``, meaning that files are given as it to the compiler, this - ``no_preprocessing``, meaning that files are given as it to the compiler, this
is the default is the default
@ -997,7 +995,7 @@ Jbuilder accepts three kinds of preprocessing:
- ``(pps <ppx-rewriters-and-flags>)`` to preprocess files using the given list - ``(pps <ppx-rewriters-and-flags>)`` to preprocess files using the given list
of ppx rewriters of ppx rewriters
Note that in any cases, files are preprocessed only once. Jbuilder doesn't use Note that in any cases, files are preprocessed only once. Dune doesn't use
the ``-pp`` or ``-ppx`` of the various OCaml tools. the ``-pp`` or ``-ppx`` of the various OCaml tools.
Preprocessing with actions Preprocessing with actions
@ -1042,9 +1040,9 @@ Libraries listed here should be libraries implementing an OCaml AST rewriter and
registering themselves using the `ocaml-migrate-parsetree.driver API registering themselves using the `ocaml-migrate-parsetree.driver API
<https://github.com/let-def/ocaml-migrate-parsetree>`__. <https://github.com/let-def/ocaml-migrate-parsetree>`__.
Jbuilder will build a single executable by linking all these libraries and their Dune will build a single executable by linking all these libraries and their
dependencies. Note that it is important that all these libraries are linked with dependencies. Note that it is important that all these libraries are linked with
``-linkall``. Jbuilder automatically uses ``-linkall`` when the ``(kind ...)`` ``-linkall``. Dune automatically uses ``-linkall`` when the ``(kind ...)``
field is set to ``ppx_rewriter`` or ``ppx_deriver``. field is set to ``ppx_rewriter`` or ``ppx_deriver``.
Per module preprocessing specification Per module preprocessing specification
@ -1097,7 +1095,7 @@ syntax:
``<dir>`` ``<dir>``
- ``(universe)``: depend on everything in the universe. This is for - ``(universe)``: depend on everything in the universe. This is for
cases where dependencies are too hard to specify. Note that Jbuilder cases where dependencies are too hard to specify. Note that dune
will not be able to cache the result of actions that depend on the will not be able to cache the result of actions that depend on the
universe. In any case, this is only for dependencies in the universe. In any case, this is only for dependencies in the
installed world, you must still specify all dependencies that come installed world, you must still specify all dependencies that come
@ -1117,7 +1115,7 @@ You can use globs to declare dependencies on a set of files. Note that globs
will match files that exist in the source tree as well as buildable targets, so will match files that exist in the source tree as well as buildable targets, so
for instance you can depend on ``*.cmi``. for instance you can depend on ``*.cmi``.
Currently jbuilder only support globbing files in a single directory. And in Currently dune only support globbing files in a single directory. And in
particular the glob is interpreted as follows: particular the glob is interpreted as follows:
- anything before the last ``/`` is taken as a literal path - anything before the last ``/`` is taken as a literal path
@ -1194,10 +1192,10 @@ 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``. ``src/foo/jbuild`` will be run from ``_build/<context>/src/foo``.
The argument of ``(action ...)`` fields is a small DSL that is interpreted by The argument of ``(action ...)`` fields is a small DSL that is interpreted by
jbuilder directly and doesn't require an external shell. All atoms in the DSL dune directly and doesn't require an external shell. All atoms in the DSL
support `Variables expansion`_. Moreover, you don't need to specify dependencies support `Variables expansion`_. Moreover, you don't need to specify dependencies
explicitly for the special ``${<kind>:...}`` forms, these are recognized and explicitly for the special ``${<kind>:...}`` forms, these are recognized and
automatically handled by Jbuilder. automatically handled by dune.
The DSL is currently quite limited, so if you want to do something complicated The DSL is currently quite limited, so if you want to do something complicated
it is recommended to write a small OCaml program and use the DSL to invoke it. it is recommended to write a small OCaml program and use the DSL to invoke it.
@ -1249,7 +1247,7 @@ in order to report errors in the original file rather than the
copy. This is important as the copy exists only under the ``_build`` copy. This is important as the copy exists only under the ``_build``
directory and in order for editors to jump to errors when parsing the directory and in order for editors to jump to errors when parsing the
output of the build system, errors must point to files that exist in output of the build system, errors must point to files that exist in
the source tree. In the beta versions of jbuilder, ``copy#`` was the source tree. In the beta versions of dune, ``copy#`` was
called ``copy-and-add-line-directive``. However, most of time one called ``copy-and-add-line-directive``. However, most of time one
wants this behavior rather than a bare copy, so it was renamed to wants this behavior rather than a bare copy, so it was renamed to
something shorter. something shorter.
@ -1304,7 +1302,7 @@ of your project. What you should write instead is:
Locks Locks
----- -----
Given two rules that are independent, Jbuilder will assume that there Given two rules that are independent, dune will assume that there
associated action can be run concurrently. Two rules are considered associated action can be run concurrently. Two rules are considered
independent if none of them depend on the other, either directly or independent if none of them depend on the other, either directly or
through a chain of dependencies. This basic assumption allows to through a chain of dependencies. This basic assumption allows to
@ -1312,7 +1310,7 @@ parallelize the build.
However, it is sometimes the case that two independent rules cannot be However, it is sometimes the case that two independent rules cannot be
executed concurrently. For instance this can happen for more executed concurrently. For instance this can happen for more
complicated tests. In order to prevent jbuilder from running the complicated tests. In order to prevent dune from running the
actions at the same time, you can specify that both actions take the actions at the same time, you can specify that both actions take the
same lock: same lock:
@ -1330,7 +1328,7 @@ same lock:
(locks (m)) (locks (m))
(action (run test.exe ${<})))) (action (run test.exe ${<}))))
Jbuilder will make sure that the executions of ``test.exe foo`` and Dune will make sure that the executions of ``test.exe foo`` and
``test.exe bar`` are serialized. ``test.exe bar`` are serialized.
Although they don't live in the filesystem, lock names are interpreted Although they don't live in the filesystem, lock names are interpreted
@ -1378,7 +1376,7 @@ However, it is different for the following reason:
- on Windows, both ``(diff a b)`` and ``(diff? a b)`` normalize the end of - on Windows, both ``(diff a b)`` and ``(diff? a b)`` normalize the end of
lines before comparing the files lines before comparing the files
- since ``(diff a b)`` is a builtin action, Jbuilder knowns that ``a`` - since ``(diff a b)`` is a builtin action, dune knowns that ``a``
and ``b`` are needed and so you don't need to specify them and ``b`` are needed and so you don't need to specify them
explicitly as dependencies explicitly as dependencies
@ -1396,7 +1394,7 @@ Promotion
~~~~~~~~~ ~~~~~~~~~
Whenever an action ``(diff <file1> <file2>)`` or ``(diff? <file1> Whenever an action ``(diff <file1> <file2>)`` or ``(diff? <file1>
<file2>)`` fails because the two files are different, jbuilder allows <file2>)`` fails because the two files are different, dune allows
you to promote ``<file2>`` as ``<file1>`` if ``<file1>`` is a source you to promote ``<file2>`` as ``<file1>`` if ``<file1>`` is a source
file and ``<file2>`` is a generated file. file and ``<file2>`` is a generated file.
@ -1415,13 +1413,13 @@ Where ``data.expected`` is a file committed in the source
repository. You can use the following workflow to update your test: repository. You can use the following workflow to update your test:
- update the code of your test - update the code of your test
- run ``jbuilder runtest``. The diff action will fail and a diff will - run ``dune runtest``. The diff action will fail and a diff will
be printed be printed
- check the diff to make sure it is what you expect - check the diff to make sure it is what you expect
- run ``jbuilder promote``. This will copy the generated ``data.out`` - run ``dune promote``. This will copy the generated ``data.out``
file to ``data.expected`` directly in the source tree file to ``data.expected`` directly in the source tree
You can also use ``jbuilder runtest --auto-promote`` which will You can also use ``dune runtest --auto-promote`` which will
automatically do the promotion. automatically do the promotion.
OCaml syntax OCaml syntax

22
doc/faq.rst
View File

@ -2,10 +2,10 @@
FAQ FAQ
*** ***
Why do many Jbuilder projects contain a Makefile? Why do many dune projects contain a Makefile?
================================================= =============================================
Many Jbuilder project contain a toplevel `Makefile`. It is often only there for Many dune projects contain a toplevel `Makefile`. It is often only there for
convenience, for the following reasons: convenience, for the following reasons:
1. there are many different build systems out there, all with a different CLI. 1. there are many different build systems out there, all with a different CLI.
@ -15,10 +15,10 @@ convenience, for the following reasons:
2. you often have a few common operations that are not part of the build and 2. you often have a few common operations that are not part of the build and
`make <blah>` is a good way to provide them `make <blah>` is a good way to provide them
3. `make` is shorter to type than `jbuilder build @install` 3. `make` is shorter to type than `dune build @install`
How to add a configure step to a jbuilder project? How to add a configure step to a dune project?
================================================== ==============================================
The with-configure-step_ example shows one way to do it which The with-configure-step_ example shows one way to do it which
preserves composability; i.e. it doesn't require manually running `./configure` preserves composability; i.e. it doesn't require manually running `./configure`
@ -26,18 +26,18 @@ script when working on multiple projects at the same time.
.. _with-configure-step: https://github.com/ocaml/dune/tree/master/example/sample-projects/with-configure-step .. _with-configure-step: https://github.com/ocaml/dune/tree/master/example/sample-projects/with-configure-step
Can I use topkg with jbuilder? Can I use topkg with dune?
============================== ==========================
Yes, have a look at the topkg-jbuilder_ project for more details. Yes, have a look at the topkg-jbuilder_ project for more details.
.. _topkg-jbuilder: https://github.com/samoht/topkg-jbuilder .. _topkg-jbuilder: https://github.com/samoht/topkg-jbuilder
here can I find some examples of projects using Jbuilder? here can I find some examples of projects using dune?
========================================================= =====================================================
The dune-universe_ repository contains a snapshot of the latest versions of all The dune-universe_ repository contains a snapshot of the latest versions of all
opam packages depending on jbuilder. It is therefore a useful reference to opam packages depending on dune. It is therefore a useful reference to
search through to find different approaches to constructing build rules. search through to find different approaches to constructing build rules.
.. _dune-universe: https://github.com/dune-universe/dune-universe .. _dune-universe: https://github.com/dune-universe/dune-universe

6
doc/index.rst
View File

@ -3,8 +3,8 @@
You can adapt this file completely to your liking, but it should at least You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive. contain the root `toctree` directive.
Welcome to jbuilder's documentation! Welcome to dune's documentation!
==================================== ================================
.. toctree:: .. toctree::
:maxdepth: 3 :maxdepth: 3
@ -13,7 +13,7 @@ Welcome to jbuilder's documentation!
overview overview
terminology terminology
project-layout-specification project-layout-specification
jbuild dune-files
tests tests
documentation documentation
usage usage

6
doc/known-issues.rst
View File

@ -6,9 +6,9 @@ mli only modules
================ ================
These are supported, however using them might cause make it impossible for These are supported, however using them might cause make it impossible for
non-jbuilder users to use your library. We tried to use them for some internal non-dune users to use your library. We tried to use them for some internal
module generated by Jbuilder and it broke the build of projects not using module generated by dune and it broke the build of projects not using
Jbuilder: dune:
https://github.com/ocaml/dune/issues/567 https://github.com/ocaml/dune/issues/567

24
doc/overview.rst
View File

@ -2,7 +2,7 @@
Overview Overview
******** ********
Jbuilder is a build system for OCaml and Reason. It is not intended as a Dune is a build system for OCaml and Reason. It is not intended as a
completely generic build system that is able to build any given project completely generic build system that is able to build any given project
in any language. On the contrary, it makes lots of choices in order to in any language. On the contrary, it makes lots of choices in order to
encourage a consistent development style. encourage a consistent development style.
@ -12,36 +12,36 @@ to the opam world. It has matured over a long time and is used daily by
hundred of developers, which means that it is highly tested and hundred of developers, which means that it is highly tested and
productive. productive.
When using Jbuilder, you give very little and high-level information to When using dune, you give very little and high-level information to
the build system, which in turn takes care of all the low-level the build system, which in turn takes care of all the low-level
details, from the compilation of your libraries, executables and details, from the compilation of your libraries, executables and
documentation, to the installation, setting up of tests, setting up of documentation, to the installation, setting up of tests, setting up of
the development tools such as merlin, etc. the development tools such as merlin, etc.
In addition to the normal features one would expect from a build system In addition to the normal features one would expect from a build system
for OCaml, Jbuilder provides a few additional ones that detach it from for OCaml, dune provides a few additional ones that detach it from
the crowd: the crowd:
- you never need to tell Jbuilder where things such as libraries are. - you never need to tell dune where things such as libraries are.
Jbuilder will always discover them automatically. In particular, this Dune will always discover them automatically. In particular, this
means that when you want to re-organize your project you need to do no means that when you want to re-organize your project you need to do no
more than rename your directories, Jbuilder will do the rest more than rename your directories, dune will do the rest
- things always work the same whether your dependencies are local or - things always work the same whether your dependencies are local or
installed on the system. In particular, this means that you can always installed on the system. In particular, this means that you can always
drop in the source for a dependency of your project in your working drop in the source for a dependency of your project in your working
copy and Jbuilder will start using it immediately. This makes Jbuilder a copy and dune will start using it immediately. This makes dune a
great choice for multi-project development great choice for multi-project development
- cross-platform: as long as your code is portable, Jbuilder will be - cross-platform: as long as your code is portable, dune will be
able to cross-compile it (note that Jbuilder is designed internally able to cross-compile it (note that dune is designed internally
to make this easy but the actual support is not implemented yet) to make this easy but the actual support is not implemented yet)
- release directly from any revision: Jbuilder needs no setup stage. To - release directly from any revision: dune needs no setup stage. To
release your project, you can simply point to a specific tag. You can release your project, you can simply point to a specific tag. You can
of course add some release steps if you want to, but it is not of course add some release steps if you want to, but it is not
necessary necessary
The first section of this document defines some terms used in the rest The first section of this document defines some terms used in the rest
of this manual. The second section specifies the Jbuilder metadata of this manual. The second section specifies the dune metadata
format and the third one describes how to use the ``jbuilder`` command. format and the third one describes how to use the ``dune`` command.

24
doc/project-layout-specification.rst
View File

@ -2,7 +2,7 @@
Project Layout and Metadata Specification Project Layout and Metadata Specification
***************************************** *****************************************
A typical jbuilder project will have a ```dune-project`` and one or A typical dune project will have a ```dune-project`` and one or
more ``<package>.opam`` file at toplevel as well as ``jbuild`` files more ``<package>.opam`` file at toplevel as well as ``jbuild`` files
wherever interesting things are: libraries, executables, tests, wherever interesting things are: libraries, executables, tests,
documents to install, etc... documents to install, etc...
@ -14,9 +14,9 @@ like to have multiple executables with different configurations in the
same directory, you will have to make an explicit module list for every same directory, you will have to make an explicit module list for every
executable using ``modules``. executable using ``modules``.
The next sections describe the format of Jbuilder metadata files. The next sections describe the format of dune metadata files.
Note that the Jbuilder metadata format is versioned in order to ensure Note that the dune metadata format is versioned in order to ensure
forward compatibility. There is currently only one version available, forward compatibility. There is currently only one version available,
but to be future proof, you should still specify it in your ``jbuild`` but to be future proof, you should still specify it in your ``jbuild``
files. If no version is specified, the latest one will be used. files. If no version is specified, the latest one will be used.
@ -205,17 +205,17 @@ Sets the version of the project:
<package>.opam files <package>.opam files
==================== ====================
When a ``<package>.opam`` file is present, Jbuilder will know that the When a ``<package>.opam`` file is present, dune will know that the
package named ``<package>`` exists. It will know how to construct a package named ``<package>`` exists. It will know how to construct a
``<package>.install`` file in the same directory to handle installation ``<package>.install`` file in the same directory to handle installation
via `opam <https://opam.ocaml.org/>`__. Jbuilder also defines the via `opam <https://opam.ocaml.org/>`__. Dune also defines the
recursive ``install`` alias, which depends on all the buildable recursive ``install`` alias, which depends on all the buildable
``<package>.install`` files in the workspace. So for instance to build ``<package>.install`` files in the workspace. So for instance to build
everything that is installable in a workspace, run at the root: everything that is installable in a workspace, run at the root:
:: ::
$ jbuilder build @install $ dune build @install
Declaring a package this way will allow you to add elements such as Declaring a package this way will allow you to add elements such as
libraries, executables, documentation, ... to your package by declaring libraries, executables, documentation, ... to your package by declaring
@ -245,18 +245,18 @@ this scope only.
Because scopes are exclusive, if you wish to include the dependencies Because scopes are exclusive, if you wish to include the dependencies
of the project you are currently working on into your workspace, you of the project you are currently working on into your workspace, you
may copy them in a ``vendor`` directory, or any other name of your may copy them in a ``vendor`` directory, or any other name of your
choice. Jbuilder will look for them there rather than in the installed choice. Dune will look for them there rather than in the installed
world and there will be no overlap between the various scopes. world and there will be no overlap between the various scopes.
Package version Package version
--------------- ---------------
Note that Jbuilder will try to determine the version number of packages Note that dune will try to determine the version number of packages
defined in the workspace. While Jbuilder itself makes no use of version defined in the workspace. While dune itself makes no use of version
numbers, it can be use by external tools such as numbers, it can be use by external tools such as
`ocamlfind <http://projects.camlcity.org/projects/findlib.html>`__. `ocamlfind <http://projects.camlcity.org/projects/findlib.html>`__.
Jbuilder determines the version of a package by trying the following Dune determines the version of a package by trying the following
methods in order: methods in order:
- it looks in the ``<package>.opam`` file for a ``version`` variable - it looks in the ``<package>.opam`` file for a ``version`` variable
@ -269,12 +269,12 @@ methods in order:
``<package>.version``, ``version`` and ``VERSION`` files may be ``<package>.version``, ``version`` and ``VERSION`` files may be
generated. generated.
If the version can't be determined, Jbuilder just won't assign one. If the version can't be determined, dune just won't assign one.
Odig conventions Odig conventions
---------------- ----------------
Jbuilder follows the `odig <http://erratique.ch/software/odig>`__ Dune follows the `odig <http://erratique.ch/software/odig>`__
conventions and automatically installs any README\*, CHANGE\*, HISTORY\* conventions and automatically installs any README\*, CHANGE\*, HISTORY\*
and LICENSE\* files in the same directory as the ``<package>.opam`` file and LICENSE\* files in the same directory as the ``<package>.opam`` file
to a location where odig will find them. to a location where odig will find them.

12
doc/quick-start.rst
View File

@ -2,9 +2,9 @@
Quickstart Quickstart
********** **********
This document gives simple usage examples of Jbuilder. You can also look at This document gives simple usage examples of dune. You can also look at
`examples <https://github.com/ocaml/dune/tree/master/example>`__ for `examples <https://github.com/ocaml/dune/tree/master/example>`__ for
complete examples of projects using Jbuilder. complete examples of projects using dune.
Building a hello world program Building a hello world program
============================== ==============================
@ -29,7 +29,7 @@ And build it with:
.. code:: bash .. code:: bash
jbuilder build hello_world.exe dune build hello_world.exe
The executable will be built as ``_build/default/hello_world.exe``. Note that The executable will be built as ``_build/default/hello_world.exe``. Note that
native code executables will have the ``.exe`` extension on all platforms native code executables will have the ``.exe`` extension on all platforms
@ -58,7 +58,7 @@ And build it with:
.. code:: bash .. code:: bash
jbuilder build hello_world.exe dune build hello_world.exe
The executable will be built as ``_build/default/hello_world.exe`` The executable will be built as ``_build/default/hello_world.exe``
@ -91,7 +91,7 @@ And build it with:
.. code:: bash .. code:: bash
jbuilder build hello_world.exe dune build hello_world.exe
The executable will be built as ``_build/default/hello_world.exe`` The executable will be built as ``_build/default/hello_world.exe``
@ -278,7 +278,7 @@ And run the tests with:
.. code:: bash .. code:: bash
jbuilder runtest dune runtest
Building a custom toplevel Building a custom toplevel
========================== ==========================

16
doc/terminology.rst
View File

@ -8,17 +8,17 @@ Terminology
- **project**: a project is a source tree, maybe containing one or more - **project**: a project is a source tree, maybe containing one or more
packages packages
- **root**: the root is the directory from where Jbuilder can build - **root**: the root is the directory from where dune can build
things. Jbuilder knows how to build targets that are descendents of things. Dune knows how to build targets that are descendents of
the root. Anything outside of the tree starting from the root is the root. Anything outside of the tree starting from the root is
considered part of the **installed world**. How the root is considered part of the **installed world**. How the root is
determined is explained in :ref:`finding-root`. determined is explained in :ref:`finding-root`.
- **workspace**: the workspace is the subtree starting from the root. - **workspace**: the workspace is the subtree starting from the root.
It can contain any number of projects that will be built It can contain any number of projects that will be built
simultaneously by jbuilder simultaneously by dune
- **installed world**: anything outside of the workspace, that Jbuilder - **installed world**: anything outside of the workspace, that dune
takes for granted and doesn't know how to build takes for granted and doesn't know how to build
- **installation**: this is the action of copying build artifacts or - **installation**: this is the action of copying build artifacts or
@ -27,7 +27,7 @@ Terminology
- **scope**: a scope determines where private items are - **scope**: a scope determines where private items are
visible. Private items include libraries or binaries that will not visible. Private items include libraries or binaries that will not
be installed. In Jbuilder, scopes are sub-trees rooted where at be installed. In dune, scopes are sub-trees rooted where at
least one ``<package>.opam`` file is present. Moreover, scopes are least one ``<package>.opam`` file is present. Moreover, scopes are
exclusive. Typically, every project defines a single scope. See exclusive. Typically, every project defines a single scope. See
:ref:`scopes` for more details :ref:`scopes` for more details
@ -36,7 +36,7 @@ Terminology
``<root>/_build`` directory. It contains all the build artifacts of ``<root>/_build`` directory. It contains all the build artifacts of
the workspace built against a specific configuration. Without the workspace built against a specific configuration. Without
specific configuration from the user, there is always a ``default`` specific configuration from the user, there is always a ``default``
build context, which corresponds to the environment in which Jbuilder build context, which corresponds to the environment in which dune
is executed. Build contexts can be specified by writing a is executed. Build contexts can be specified by writing a
:ref:`dune-workspace` file :ref:`dune-workspace` file
@ -47,7 +47,7 @@ Terminology
and has configurable dependencies. Aliases are and has configurable dependencies. Aliases are
per-directory. However, on the command line, asking for an alias to per-directory. However, on the command line, asking for an alias to
be built in a given directory will trigger the construction of the be built in a given directory will trigger the construction of the
alias in all children directories recursively. Jbuilder defines the alias in all children directories recursively. Dune defines the
following standard aliases: following standard aliases:
- ``default`` which is the alias build by default when no targets - ``default`` which is the alias build by default when no targets
@ -58,7 +58,7 @@ Terminology
- ``doc`` which depends on the generated HTML - ``doc`` which depends on the generated HTML
documentation. See :ref:`documentation` for details. documentation. See :ref:`documentation` for details.
- **environment**: in Jbuilder, each directory has an environment - **environment**: in dune, each directory has an environment
attached to it. The environment determines the default values of attached to it. The environment determines the default values of
various parameters, such as the compilation flags. Inside a scope, various parameters, such as the compilation flags. Inside a scope,
each directory inherit the environment from its parent. At the root each directory inherit the environment from its parent. At the root

73
doc/tests.rst
View File

@ -2,13 +2,13 @@
Writing and running tests Writing and running tests
************************* *************************
Jbuilder tries to streamline the testing story as much as possible, so Dune tries to streamline the testing story as much as possible, so
that you can focus on the tests themselves and not bother with setting that you can focus on the tests themselves and not bother with setting
up with various test frameworks. up with various test frameworks.
In this section, we will explain the workflow to deal with tests in In this section, we will explain the workflow to deal with tests in
Jbuilder. In particular we will see how to run the testsuite of a dune. In particular we will see how to run the testsuite of a
project, how to describe your tests to Jbuilder and how to promote project, how to describe your tests to dune and how to promote
tests result as expectation. tests result as expectation.
We distinguish two kinds of tests: inline tests and custom We distinguish two kinds of tests: inline tests and custom
@ -22,22 +22,22 @@ Running tests
============= =============
Whatever the tests of a project are, the usual way to run tests with Whatever the tests of a project are, the usual way to run tests with
Jbuilder is to call ``jbuilder runtest`` from the shell. This will run dune is to call ``dune runtest`` from the shell. This will run
all the tests defined in the current directory and any sub-directory all the tests defined in the current directory and any sub-directory
recursively. You can also pass a directory argument to run the tests recursively. You can also pass a directory argument to run the tests
from a sub-tree. For instance ``jbuilder runtest test`` will only run from a sub-tree. For instance ``dune runtest test`` will only run
the tests from the ``test`` directory and any sub-directory of the tests from the ``test`` directory and any sub-directory of
``test`` recursively. ``test`` recursively.
Note that in any case, ``jbuilder runtest`` is simply a short-hand for Note that in any case, ``dune runtest`` is simply a short-hand for
building the ``runtest`` alias, so you can always ask Jbuilder to run building the ``runtest`` alias, so you can always ask dune to run
the tests in conjunction with other targets by passing ``@runtest`` to the tests in conjunction with other targets by passing ``@runtest`` to
``jbuilder build``. For instance: ``dune build``. For instance:
.. code:: bash .. code:: bash
$ jbuilder build @install @runtest $ dune build @install @runtest
$ jbuilder build @install @test/runtest $ dune build @install @test/runtest
Inline tests Inline tests
============ ============
@ -45,7 +45,7 @@ Inline tests
There are several inline tests framework available for OCaml, such as There are several inline tests framework available for OCaml, such as
ppx_inline_test_ and qtest_. We will use ppx_inline_test_ as an ppx_inline_test_ and qtest_. We will use ppx_inline_test_ as an
example as at the time of writing this document it has the necessary example as at the time of writing this document it has the necessary
setup to be used with Jbuilder out of the box. setup to be used with dune out of the box.
ppx_inline_test_ allows to write tests directly inside ml files as ppx_inline_test_ allows to write tests directly inside ml files as
follow: follow:
@ -65,7 +65,7 @@ so for instance the ``jbuild`` file might look like this:
((name foo) ((name foo)
(preprocess (pps (ppx_inline_test))))) (preprocess (pps (ppx_inline_test)))))
In order to instruct Jbuilder that our library contains inline tests, In order to instruct dune that our library contains inline tests,
all we have to do is add an ``inline_tests`` field: all we have to do is add an ``inline_tests`` field:
.. code:: scheme .. code:: scheme
@ -75,13 +75,12 @@ all we have to do is add an ``inline_tests`` field:
(inline_tests) (inline_tests)
(preprocess (pps (ppx_inline_test))))) (preprocess (pps (ppx_inline_test)))))
We can now build and execute this test by running ``jbuilder We can now build and execute this test by running ``dune runtest``. For
runtest``. For instance, if we make the test fail by replacing ``120`` instance, if we make the test fail by replacing ``120`` by ``0`` we get:
by ``0`` we get:
.. code:: bash .. code:: bash
$ jbuilder runtest $ dune runtest
[...] [...]
File "src/fact.ml", line 3, characters 0-25: <<(fact 5) = 0>> is false. File "src/fact.ml", line 3, characters 0-25: <<(fact 5) = 0>> is false.
@ -91,7 +90,7 @@ Note that in this case Jbuild knew how to build and run the tests
without any special configuration. This is because ppx_inline_test without any special configuration. This is because ppx_inline_test
defines an inline tests backend and it is used by the library. Some defines an inline tests backend and it is used by the library. Some
other frameworks, such as qtest_ don't have any special library or ppx other frameworks, such as qtest_ don't have any special library or ppx
rewriter. To use such a framework, you must tell Jbuilder about it rewriter. To use such a framework, you must tell dune about it
since it cannot guess it. You can do that by adding a ``backend`` since it cannot guess it. You can do that by adding a ``backend``
field: field:
@ -129,15 +128,15 @@ following test elements are clearly identified:
You can have a look at `this blog post You can have a look at `this blog post
<https://blog.janestreet.com/testing-with-expectations/>`_ to find out <https://blog.janestreet.com/testing-with-expectations/>`_ to find out
more about expectation tests. But Back to Jbuilder, the workflow for more about expectation tests. To dune, the workflow for
expectation tests is always as follow: expectation tests is always as follows:
- write the test with some empty expect nodes in it - write the test with some empty expect nodes in it
- run the tests - run the tests
- check the suggested correction and promote it as the original source - check the suggested correction and promote it as the original source
file if you are happy with it file if you are happy with it
Jbuilder makes this workflow very easy, simply add ``ppx_expect`` to Dune makes this workflow very easy, simply add ``ppx_expect`` to
your list of ppx rewriters as follow: your list of ppx rewriters as follow:
.. code:: scheme .. code:: scheme
@ -147,13 +146,13 @@ your list of ppx rewriters as follow:
(inline_tests) (inline_tests)
(preprocess (pps (ppx_expect))))) (preprocess (pps (ppx_expect)))))
Then calling ``jbuilder runtest`` will run these tests and in case of Then calling ``dune runtest`` will run these tests and in case of
mismatch Jbuilder will print a diff of the original source file and mismatch dune will print a diff of the original source file and
the suggested correction. For instance: the suggested correction. For instance:
.. code:: bash .. code:: bash
$ jbuilder runtest $ dune runtest
[...] [...]
-src/fact.ml -src/fact.ml
+src/fact.ml.corrected +src/fact.ml.corrected
@ -169,14 +168,14 @@ In order to accept the correction, simply run:
.. code:: bash .. code:: bash
$ jbuilder promote $ dune promote
You can also make Jbuilder automatically accept the correction after You can also make dune automatically accept the correction after
running the tests by typing: running the tests by typing:
.. code:: bash .. code:: bash
$ jbuilder runtest --auto-promote $ dune runtest --auto-promote
Finally, some editor integration is possible to make the editor do the Finally, some editor integration is possible to make the editor do the
promotion and make the workflow even smoother. promotion and make the workflow even smoother.
@ -184,7 +183,7 @@ promotion and make the workflow even smoother.
Specifying inline test dependencies Specifying inline test dependencies
----------------------------------- -----------------------------------
If your tests are reading files, you must say it to Jbuilder by adding If your tests are reading files, you must say it to dune by adding
a ``deps`` field the the ``inline_tests`` field. The argument of this a ``deps`` field the the ``inline_tests`` field. The argument of this
``deps`` field follows the usual :ref:`deps-field`. For instance: ``deps`` field follows the usual :ref:`deps-field`. For instance:
@ -198,7 +197,7 @@ a ``deps`` field the the ``inline_tests`` field. The argument of this
Passing special arguments to the test runner Passing special arguments to the test runner
-------------------------------------------- --------------------------------------------
Under the hood, a test executable is built by Jbuilder. Depending on Under the hood, a test executable is built by dune. Depending on
the backend used this runner might take useful command line the backend used this runner might take useful command line
arguments. You can specify such flags by using a ``flags`` field, such arguments. You can specify such flags by using a ``flags`` field, such
as: as:
@ -319,7 +318,7 @@ build as this would cause portability problems.
Custom tests Custom tests
============ ============
We said in `Running tests`_ that to run tests Jbuilder simply builds We said in `Running tests`_ that to run tests dune simply builds
the ``runtest`` alias. As a result, to define cutsom tests, you simply the ``runtest`` alias. As a result, to define cutsom tests, you simply
need to add an action to this alias in any directory. For instance if need to add an action to this alias in any directory. For instance if
you have a binary ``tests.exe`` that you want to run as part of you have a binary ``tests.exe`` that you want to run as part of
@ -335,9 +334,9 @@ Diffing the result
------------------ ------------------
It is often the case that we want to compare the output of a test to It is often the case that we want to compare the output of a test to
some expected one. For that, Jbuilder offers the ``diff`` command, some expected one. For that, dune offers the ``diff`` command,
which in essence is the same as running the ``diff`` tool, except that which in essence is the same as running the ``diff`` tool, except that
it is more integrated in Jbuilder and especially with the ``promote`` it is more integrated in dune and especially with the ``promote``
command. For instance let's consider this test: command. For instance let's consider this test:
.. code:: scheme .. code:: scheme
@ -350,29 +349,29 @@ command. For instance let's consider this test:
(action (diff tests.expected test.output)))) (action (diff tests.expected test.output))))
After having run ``tests.exe`` and dumping its output to After having run ``tests.exe`` and dumping its output to
``tests.output``, Jbuilder will compare the latter to ``tests.output``, dune will compare the latter to
``tests.expected``. In case of mismatch, Jbuilder will print a diff ``tests.expected``. In case of mismatch, dune will print a diff
and then the ``jbuilder promote`` command can be used to copy over the and then the ``dune promote`` command can be used to copy over the
generated ``test.output`` file to ``tests.expected`` in the source generated ``test.output`` file to ``tests.expected`` in the source
tree. This provides a nice way of dealing with the usual *write code*, tree. This provides a nice way of dealing with the usual *write code*,
*run*, *promote* cycle of testing. For instance: *run*, *promote* cycle of testing. For instance:
.. code:: bash .. code:: bash
$ jbuilder runtest $ dune runtest
[...] [...]
-tests.expected -tests.expected
+tests.output +tests.output
File "tests.expected", line 1, characters 0-1: File "tests.expected", line 1, characters 0-1:
-Hello, world! -Hello, world!
+Good bye! +Good bye!
$ jbuilder promote $ dune promote
Promoting _build/default/tests.output to tests.expected. Promoting _build/default/tests.output to tests.expected.
Note that if available, the diffing is done using the patdiff_ tool, Note that if available, the diffing is done using the patdiff_ tool,
which displays nicer looking diffs that the standard ``diff`` which displays nicer looking diffs that the standard ``diff``
tool. You can change that by passing ``--diff-command CMD`` to tool. You can change that by passing ``--diff-command CMD`` to
Jbuilder. dune.
.. _ppx_inline_test: https://github.com/janestreet/ppx_inline_test .. _ppx_inline_test: https://github.com/janestreet/ppx_inline_test

96
doc/usage.rst
View File

@ -2,7 +2,7 @@
Usage Usage
***** *****
This section describe usage of Jbuilder from the shell. This section describe usage of dune from the shell.
.. _finding-root: .. _finding-root:
@ -40,7 +40,7 @@ order:
- ``/home/me/code/myproject/src/dune-workspace`` - ``/home/me/code/myproject/src/dune-workspace``
The first entry to match in this list will determine the root. In The first entry to match in this list will determine the root. In
practice this means that if you nest your workspaces, Jbuilder will practice this means that if you nest your workspaces, dune will
always use the outermost one. always use the outermost one.
In addition to determining the root, ``dune`` will read this file as In addition to determining the root, ``dune`` will read this file as
@ -58,7 +58,7 @@ as root.
Forcing the root (for scripts) Forcing the root (for scripts)
------------------------------ ------------------------------
You can pass the ``--root`` option to ``jbuilder`` to select the root You can pass the ``--root`` option to ``dune`` to select the root
explicitly. This option is intended for scripts to disable the automatic lookup. explicitly. This option is intended for scripts to disable the automatic lookup.
Note that when using the ``--root`` option, targets given on the command line Note that when using the ``--root`` option, targets given on the command line
@ -75,7 +75,7 @@ the command line. When no targets are specified, ``dune`` builds the
Resolution Resolution
---------- ----------
All targets that Jbuilder knows how to build live in the ``_build`` All targets that dune knows how to build live in the ``_build``
directory. Although, some are sometimes copied to the source tree for directory. Although, some are sometimes copied to the source tree for
the need of external tools. These includes: the need of external tools. These includes:
@ -83,22 +83,22 @@ the need of external tools. These includes:
- ``<package>.install`` files - ``<package>.install`` files
As a result, if you want to ask ``jbuilder`` to produce a particular ``.exe`` As a result, if you want to ask ``dune`` to produce a particular ``.exe``
file you would have to type: file you would have to type:
.. code:: bash .. code:: bash
$ jbuilder build _build/default/bin/prog.exe $ dune build _build/default/bin/prog.exe
However, for convenience when a target on the command line doesn't However, for convenience when a target on the command line doesn't
start with ``_build``, ``jbuilder`` will expand it to the start with ``_build``, ``dune`` will expand it to the
corresponding target in all the build contexts where it knows how to corresponding target in all the build contexts where it knows how to
build it. When using ``--verbose``, It prints out the actual set of build it. When using ``--verbose``, It prints out the actual set of
targets when starting: targets when starting:
.. code:: bash .. code:: bash
$ jbuilder build bin/prog.exe --verbose $ dune build bin/prog.exe --verbose
... ...
Actual targets: Actual targets:
- _build/default/bin/prog.exe - _build/default/bin/prog.exe
@ -118,9 +118,9 @@ To build and run the tests for a particular build context, use
So for instance: So for instance:
- ``jbuilder build @_build/foo/runtest`` will run the tests only for - ``dune build @_build/foo/runtest`` will run the tests only for
the ``foo`` build context the ``foo`` build context
- ``jbuilder build @runtest`` will run the tests for all build contexts - ``dune build @runtest`` will run the tests for all build contexts
You can also build an alias non-recursively by using ``@@`` instead of You can also build an alias non-recursively by using ``@@`` instead of
``@``. For instance to run tests only from the current directory: ``@``. For instance to run tests only from the current directory:
@ -157,7 +157,7 @@ is installable.
Finding external libraries Finding external libraries
========================== ==========================
When a library is not available in the workspace, jbuilder will look it When a library is not available in the workspace, dune will look it
up in the installed world, and expect it to be already compiled. up in the installed world, and expect it to be already compiled.
It looks up external libraries using a specific list of search pathes. A It looks up external libraries using a specific list of search pathes. A
@ -179,29 +179,29 @@ Running tests
There are two ways to run tests: There are two ways to run tests:
- ``jbuilder build @runtest`` - ``dune build @runtest``
- ``jbuilder runtest`` - ``dune runtest``
The two commands are equivalent. They will run all the tests defined in The two commands are equivalent. They will run all the tests defined in
the current directory and its children recursively. You can also run the the current directory and its children recursively. You can also run the
tests in a specific sub-directory and its children by using: tests in a specific sub-directory and its children by using:
- ``jbuilder build @foo/bar/runtest`` - ``dune build @foo/bar/runtest``
- ``jbuilder runtest foo/bar`` - ``dune runtest foo/bar``
Launching the Toplevel (REPL) Launching the Toplevel (REPL)
============================= =============================
jbuilder supports launching a `utop <https://github.com/diml/utop>`__ instance Dune supports launching a `utop <https://github.com/diml/utop>`__ instance
with locally defined libraries loaded. with locally defined libraries loaded.
.. code:: bash .. code:: bash
$ jbuilder utop <dir> -- <args> $ dune utop <dir> -- <args>
Where ``<dir>`` is a directory containing a ``jbuild`` file defining all the Where ``<dir>`` is a directory containing a ``jbuild`` file defining all the
libraries that will be loaded (using the ``library`` stanza). ``<args>`` will be libraries that will be loaded (using the ``library`` stanza). ``<args>`` will be
passed as arguments to the utop command itself. For example, ``jbuilder utop lib passed as arguments to the utop command itself. For example, ``dune utop lib
-- -implicit-bindings`` will start ``utop`` with the libraries defined in -- -implicit-bindings`` will start ``utop`` with the libraries defined in
``lib`` and implicit bindings for toplevel expressions. ``lib`` and implicit bindings for toplevel expressions.
@ -218,16 +218,16 @@ Requirements & Limitations
Restricting the set of packages Restricting the set of packages
=============================== ===============================
You can restrict the set of packages from your workspace that Jbuilder You can restrict the set of packages from your workspace that dune
can see with the ``--only-packages`` option: can see with the ``--only-packages`` option:
.. code:: bash .. code:: bash
$ jbuilder build --only-packages pkg1,pkg2,... @install $ dune build --only-packages pkg1,pkg2,... @install
This option acts as if you went through all the jbuild files and This option acts as if you went through all the jbuild files and
commented out the stanzas refering to a package that is not in the list commented out the stanzas refering to a package that is not in the list
given to ``jbuilder``. given to ``dune``.
Invocation from opam Invocation from opam
==================== ====================
@ -245,9 +245,9 @@ release --default-target @install``. ``-p`` is the short version of
This has the following effects: This has the following effects:
- it tells jbuilder to build everything that is installable and to - it tells dune to build everything that is installable and to
ignore packages other than ``name`` defined in your project ignore packages other than ``name`` defined in your project
- it sets the root to prevent jbuilder from looking it up - it sets the root to prevent dune from looking it up
- it sets the build profile to ``release`` - it sets the build profile to ``release``
- it uses whatever concurrency option opam provides - it uses whatever concurrency option opam provides
- it sets the default target to ``@install`` rather than ``@@default`` - it sets the default target to ``@install`` rather than ``@@default``
@ -273,25 +273,25 @@ Installing a package means copying the build artifacts from the build
directory to the installed word. directory to the installed word.
When installing via opam, you don't need to worry about this step: When installing via opam, you don't need to worry about this step:
jbuilder generates a ``<package>.install`` file that opam will dune generates a ``<package>.install`` file that opam will
automatically read to handle installation. automatically read to handle installation.
However, when not using opam or doing local development, you can use However, when not using opam or doing local development, you can use
jbuilder to install the artifacts by hands. To do that, use the dune to install the artifacts by hands. To do that, use the
``install`` command: ``install`` command:
:: ::
$ jbuilder install [PACKAGE]... $ dune install [PACKAGE]...
without an argument, it will install all the packages available in the without an argument, it will install all the packages available in the
workspace. With a specific list of packages, it will only install these workspace. With a specific list of packages, it will only install these
packages. If several build contexts are configured, the installation packages. If several build contexts are configured, the installation
will be performed for all of them. will be performed for all of them.
Note that ``jbuilder install`` is a thin wrapper around the Note that ``dune install`` is a thin wrapper around the
``opam-installer`` tool, so you will need to install this tool in order ``opam-installer`` tool, so you will need to install this tool in order
to be able to use ``jbuilder install``. to be able to use ``dune install``.
Destination Destination
----------- -----------
@ -319,9 +319,9 @@ are using this mechanism to setup where OCaml library files should be
copied. copied.
As a result, if none of ``--libdir`` and ``--prefix`` is passed to As a result, if none of ``--libdir`` and ``--prefix`` is passed to
``jbuilder install`` and ``ocamlfind`` is present in the ``PATH``, ``dune install`` and ``ocamlfind`` is present in the ``PATH``,
then library files will be copied to the directory reported by then library files will be copied to the directory reported by
``ocamlfind printconf destdir``. This ensures that ``jbuilder ``ocamlfind printconf destdir``. This ensures that ``dune
install`` can be used without opam. When using opam, ``ocamlfind`` is install`` can be used without opam. When using opam, ``ocamlfind`` is
configured to point to the opam directory, so this rule makes no configured to point to the opam directory, so this rule makes no
difference. difference.
@ -403,10 +403,10 @@ context or can be the description of an opam switch, as follows:
where the artifacts for this build context will be stored where the artifacts for this build context will be stored
- ``(root <opam-root>)`` is the opam root. By default it will take - ``(root <opam-root>)`` is the opam root. By default it will take
the opam root defined by the environment in which ``jbuilder`` is the opam root defined by the environment in which ``dune`` is
run which is usually ``~/.opam`` run which is usually ``~/.opam``
- ``(merlin)`` instructs Jbuilder to use this build context for - ``(merlin)`` instructs dune to use this build context for
merlin merlin
- ``(profile <profile>)`` to set a different profile for a build - ``(profile <profile>)`` to set a different profile for a build
@ -423,14 +423,14 @@ the artifacts from the ``default`` context, and if you have the
``(context default)`` stanza in your ``dune-workspace`` file, that ``(context default)`` stanza in your ``dune-workspace`` file, that
is the one Jbuilder will use. is the one Jbuilder will use.
For rare cases where this is not what you want, you can force Jbuilder For rare cases where this is not what you want, you can force dune
to use a different build contexts for merlin by adding the field to use a different build contexts for merlin by adding the field
``(merlin)`` to this context. ``(merlin)`` to this context.
Building JavaScript with js_of_ocaml Building JavaScript with js_of_ocaml
==================================== ====================================
Jbuilder knows how to generate a JavaScript version of an executable Dune knows how to generate a JavaScript version of an executable
(``<name>.bc.js``) using the js_of_ocaml compiler (the ``js_of_ocaml-compiler`` (``<name>.bc.js``) using the js_of_ocaml compiler (the ``js_of_ocaml-compiler``
opam package must be installed). opam package must be installed).
@ -452,16 +452,16 @@ js_of_ocaml compiler
.. _using-topkg: .. _using-topkg:
Using topkg with jbuilder Using topkg with dune
========================= =====================
Jbuilder provides suport for building and installing your project. Dune provides support for building and installing your project.
However it doesn't provides helpers for distributing it. It is However it doesn't provides helpers for distributing it. It is
recommemded to use `Topkg <https://github.com/dbuenzli/topkg>`__ for recommemded to use `Topkg <https://github.com/dbuenzli/topkg>`__ for
this purpose. this purpose.
The `topkg-jbuilder <https://github.com/diml/topkg-jbuilder>`__ The `topkg-jbuilder <https://github.com/diml/topkg-jbuilder>`__
project provides helpers for using Topkg in a Jbuilder project. In project provides helpers for using Topkg in a dune project. In
particular, as long as your project uses the common defaults, just particular, as long as your project uses the common defaults, just
write this ``pkg/pkg.ml`` file and you are all set: write this ``pkg/pkg.ml`` file and you are all set:
@ -471,7 +471,7 @@ write this ``pkg/pkg.ml`` file and you are all set:
#require "topkg-jbuilder.auto" #require "topkg-jbuilder.auto"
It is planned that this file won't be necessary at all soon and topkg It is planned that this file won't be necessary at all soon and topkg
will work out of the box on jbuilder projects. will work out of the box on dune projects.
The common defaults are that your projects include the following The common defaults are that your projects include the following
files: files:
@ -500,16 +500,16 @@ you are using git, topkg invokes this command to find out the version:
$ git describe --always --dirty $ git describe --always --dirty
1.0+beta9-79-g29e9b37 1.0+beta9-79-g29e9b37
Projects using jbuilder usually only need topkg for creating and Projects using dune usually only need topkg for creating and
publishing releases. However they might still want to substitute the publishing releases. However they might still want to substitute the
watermarks when the package is pinned by the user. To help with this, watermarks when the package is pinned by the user. To help with this,
jbuilder provides the ``subst`` sub-command. dune provides the ``subst`` sub-command.
jbuilder subst dune subst
============== ==========
``jbuilder subst`` performs the same substitution ``topkg`` does with ``dune subst`` performs the same substitution ``topkg`` does with
the default configuration. i.e. calling ``jbuilder subst`` at the root the default configuration. i.e. calling ``dune subst`` at the root
of your project will rewrite in place all the files in your project. of your project will rewrite in place all the files in your project.
More precisely, it replaces all the following watermarks in source More precisely, it replaces all the following watermarks in source
@ -536,11 +536,11 @@ you need to specify the name explicitly via the ``-n`` flag:
.. code:: bash .. code:: bash
$ jbuilder subst -n myproject $ dune subst -n myproject
Finally, note that jbuilder doesn't allow you to customize the list of Finally, note that dune doesn't allow you to customize the list of
substituted watermarks. If you which to do so, you need to configure substituted watermarks. If you which to do so, you need to configure
topkg and use it instead of ``jbuilder subst``. topkg and use it instead of ``dune subst``.
Custom Build Directory Custom Build Directory
====================== ======================