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
***************
This section describes some details of Jbuilder for advanced users.
This section describes some details of dune for advanced users.
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
to interoperate with the rest of the world when installing libraries. It
is able to generate them automatically. However, for the rare cases
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.
In order to do that, write or setup a rule to generate a
``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
the form ``# JBUILDER_GEN`` by the contents of the ``META`` it would
normally generate.
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::
@ -33,7 +33,7 @@ Jbuilder you can write the folliwing ``META.foo.template`` file:
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
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
a lot. In particular, complex ``META`` files are often hand-written and
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:
- ``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
- ``mt_posix``: forces the use of posix threads rather than VM
@ -62,7 +62,7 @@ set of predicates:
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
to the definition of a build context.
@ -74,7 +74,7 @@ to the definition of a build context.
- the name of an alternative toolchain
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
<https://github.com/ocaml-cross/>`_, such as:
@ -105,11 +105,11 @@ This configuration defines three build contexts:
- ``default.android``
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
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.
Note that instead of writing a ``dune-workspace`` file, you can also
@ -142,13 +142,13 @@ following ``src/jbuild`` file:
(executable ((name foo)))
(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.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``
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.
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
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
<https://github.com/diml/ppxfind>`_ tool.

12
doc/documentation.rst
View File

@ -7,8 +7,8 @@ Generating Documentation
Prerequisites
=============
Documentation in jbuilder is done courtesy of the odoc_ tool. Therefore, to
generate documentation in jbuilder, you will need to install this tool. This
Documentation in dune is done courtesy of the odoc_ tool. Therefore, to
generate documentation in dune, you will need to install this tool. This
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
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
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:
- ``(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.
- ``(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
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.
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.
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
its name. They are used to describe libraries, executables, tests, and
everything Jbuilder needs to know about.
``dune`` files are the main part of dune. They are used to describe libraries,
executables, tests, and everything dune needs to know about.
The syntax of ``jbuild`` files is described in
:ref:``metadata-format`` section.
The syntax of ``dune`` files is described in :ref:`metadata-format` section.
Stanzas
=======
@ -64,16 +62,16 @@ modules you want.
- ``(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,
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
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`
- ``(synopsis <string>)`` should give a one-line description of the library.
This is used by tools that list installed libraries
- ``(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
as ones generated by user rules. You can restrict this list by using a
``(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
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
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
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
``ctypes`` which will only install ``ctypes.foreign`` if the dummy
``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
- ``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
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
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
@ -175,8 +173,8 @@ modules you want.
``.re`` file. Such modules are usually referred as *mli only
modules*. They are not officially supported by the OCaml compiler,
however they are commonly used. Such modules must only define
types. Since it is not reasonably possible for Jbuilder to check
that this is the case, Jbuilder requires the user to explicitly list
types. Since it is not reasonably possible for dune to check
that this is the case, dune requires the user to explicitly list
such modules to avoid surprises. ``<modules>`` must be a subset of
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
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
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
executable. There can be additional modules in the current directory, you only
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
bytecode executable which requires ``ocamlrun`` to run and ``<name>.bc.js`` is a
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
executable often requires loading shared libraries that are locally
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``
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.
- ``(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
the current stanza. It is interpreted in the same way as the ``(modules
...)`` field of `library`_
@ -376,7 +374,7 @@ It shares the same fields as the ``executable`` stanza, except that instead of
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.
The syntax is as follows:
@ -388,7 +386,7 @@ The syntax is as follows:
(action <action>)
<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.
``<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
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``
field. The following modes are available:
@ -423,7 +421,7 @@ field. The following modes are available:
- ``standard``, this is the standard mode
- ``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
of fallback rules is to generate default configuration files that
may be generated by a configure script.
@ -433,7 +431,7 @@ field. The following modes are available:
back to the source tree
- ``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
@ -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
to commit the generated code and review it. The second is to cut down
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
``-p/--for-release-of-packages`` flag implies
``--ignore-promote-rules``.
@ -463,7 +461,7 @@ For instance:
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
following shorter syntax, where Jbuilder infers dependencies and
following shorter syntax, where dune infers dependencies and
targets for you:
.. code:: scheme
@ -476,10 +474,10 @@ For instance:
(rule (copy a b))
Note that in Jbuilder, targets must always be known
statically. Especially, this mean that Jbuilder must be able to
Note that in dune, targets must always be known
statically. Especially, this mean that dune must be able to
statically determine all targets. For instance, this ``(rule ...)``
stanza is rejected by Jbuilder:
stanza is rejected by dune:
.. code:: scheme
@ -584,8 +582,8 @@ tests.
install
-------
The ``install`` stanza is what lets you describe what Jbuilder should install,
either when running ``jbuilder install`` or through opam.
The ``install`` stanza is what lets you describe what dune should install,
either when running ``dune install`` or through opam.
Libraries and executables don't need an ``install`` stanza to be
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
``.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.
More precisely, when installing a file via an ``(install ...)``
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.
copy_files
@ -694,12 +692,12 @@ For instance:
((name runtest)
(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:
.. code:: shell
$ jbuilder build @runtest --auto-promote
$ dune build @runtest --auto-promote
.. _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
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:
- ``: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
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
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``
are the file extension used for various artifacts
- ``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
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
``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``
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
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.
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
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
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 ``(->
@ -989,7 +987,7 @@ selectable. You can add a fallback by adding a clause of the form ``(->
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
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
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.
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
<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
``-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``.
Per module preprocessing specification
@ -1097,7 +1095,7 @@ syntax:
``<dir>``
- ``(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
universe. In any case, this is only for dependencies in the
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
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:
- 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``.
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
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
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``
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
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
wants this behavior rather than a bare copy, so it was renamed to
something shorter.
@ -1304,7 +1302,7 @@ of your project. What you should write instead is:
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
independent if none of them depend on the other, either directly or
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
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
same lock:
@ -1330,7 +1328,7 @@ same lock:
(locks (m))
(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.
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
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
explicitly as dependencies
@ -1396,7 +1394,7 @@ Promotion
~~~~~~~~~
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
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:
- 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
- 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
You can also use ``jbuilder runtest --auto-promote`` which will
You can also use ``dune runtest --auto-promote`` which will
automatically do the promotion.
OCaml syntax

22
doc/faq.rst
View File

@ -2,10 +2,10 @@
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:
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
`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
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
Can I use topkg with jbuilder?
==============================
Can I use topkg with dune?
==========================
Yes, have a look at the topkg-jbuilder_ project for more details.
.. _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
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.
.. _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
contain the root `toctree` directive.
Welcome to jbuilder's documentation!
====================================
Welcome to dune's documentation!
================================
.. toctree::
:maxdepth: 3
@ -13,7 +13,7 @@ Welcome to jbuilder's documentation!
overview
terminology
project-layout-specification
jbuild
dune-files
tests
documentation
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
non-jbuilder 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
Jbuilder:
non-dune users to use your library. We tried to use them for some internal
module generated by dune and it broke the build of projects not using
dune:
https://github.com/ocaml/dune/issues/567

24
doc/overview.rst
View File

@ -2,7 +2,7 @@
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
in any language. On the contrary, it makes lots of choices in order to
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
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
details, from the compilation of your libraries, executables and
documentation, to the installation, setting up of tests, setting up of
the development tools such as merlin, etc.
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:
- you never need to tell Jbuilder where things such as libraries are.
Jbuilder will always discover them automatically. In particular, this
- you never need to tell dune where things such as libraries are.
Dune will always discover them automatically. In particular, this
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
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
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
- cross-platform: as long as your code is portable, Jbuilder will be
able to cross-compile it (note that Jbuilder is designed internally
- cross-platform: as long as your code is portable, dune will be
able to cross-compile it (note that dune is designed internally
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
of course add some release steps if you want to, but it is not
necessary
The first section of this document defines some terms used in the rest
of this manual. The second section specifies the Jbuilder metadata
format and the third one describes how to use the ``jbuilder`` command.
of this manual. The second section specifies the dune metadata
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
*****************************************
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
wherever interesting things are: libraries, executables, tests,
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
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,
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.
@ -205,17 +205,17 @@ Sets the version of the project:
<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>.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
``<package>.install`` files in the workspace. So for instance to build
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
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
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
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.
Package version
---------------
Note that Jbuilder will try to determine the version number of packages
defined in the workspace. While Jbuilder itself makes no use of version
Note that dune will try to determine the version number of packages
defined in the workspace. While dune itself makes no use of version
numbers, it can be use by external tools such as
`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:
- 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
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
----------------
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\*
and LICENSE\* files in the same directory as the ``<package>.opam`` file
to a location where odig will find them.

12
doc/quick-start.rst
View File

@ -2,9 +2,9 @@
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
complete examples of projects using Jbuilder.
complete examples of projects using dune.
Building a hello world program
==============================
@ -29,7 +29,7 @@ And build it with:
.. 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
native code executables will have the ``.exe`` extension on all platforms
@ -58,7 +58,7 @@ And build it with:
.. code:: bash
jbuilder build hello_world.exe
dune build hello_world.exe
The executable will be built as ``_build/default/hello_world.exe``
@ -91,7 +91,7 @@ And build it with:
.. code:: bash
jbuilder build hello_world.exe
dune build 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
jbuilder runtest
dune runtest
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
packages
- **root**: the root is the directory from where Jbuilder can build
things. Jbuilder knows how to build targets that are descendents of
- **root**: the root is the directory from where dune can build
things. Dune knows how to build targets that are descendents of
the root. Anything outside of the tree starting from the root is
considered part of the **installed world**. How the root is
determined is explained in :ref:`finding-root`.
- **workspace**: the workspace is the subtree starting from the root.
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
- **installation**: this is the action of copying build artifacts or
@ -27,7 +27,7 @@ Terminology
- **scope**: a scope determines where private items are
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
exclusive. Typically, every project defines a single scope. See
:ref:`scopes` for more details
@ -36,7 +36,7 @@ Terminology
``<root>/_build`` directory. It contains all the build artifacts of
the workspace built against a specific configuration. Without
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
:ref:`dune-workspace` file
@ -47,7 +47,7 @@ Terminology
and has configurable dependencies. Aliases are
per-directory. However, on the command line, asking for an alias to
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:
- ``default`` which is the alias build by default when no targets
@ -58,7 +58,7 @@ Terminology
- ``doc`` which depends on the generated HTML
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
various parameters, such as the compilation flags. Inside a scope,
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
*************************
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
up with various test frameworks.
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
project, how to describe your tests to Jbuilder and how to promote
dune. In particular we will see how to run the testsuite of a
project, how to describe your tests to dune and how to promote
tests result as expectation.
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
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
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
``test`` recursively.
Note that in any case, ``jbuilder runtest`` is simply a short-hand for
building the ``runtest`` alias, so you can always ask Jbuilder to run
Note that in any case, ``dune runtest`` is simply a short-hand for
building the ``runtest`` alias, so you can always ask dune to run
the tests in conjunction with other targets by passing ``@runtest`` to
``jbuilder build``. For instance:
``dune build``. For instance:
.. code:: bash
$ jbuilder build @install @runtest
$ jbuilder build @install @test/runtest
$ dune build @install @runtest
$ dune build @install @test/runtest
Inline tests
============
@ -45,7 +45,7 @@ Inline tests
There are several inline tests framework available for OCaml, such as
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
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
follow:
@ -65,7 +65,7 @@ so for instance the ``jbuild`` file might look like this:
((name foo)
(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:
.. code:: scheme
@ -75,13 +75,12 @@ all we have to do is add an ``inline_tests`` field:
(inline_tests)
(preprocess (pps (ppx_inline_test)))))
We can now build and execute this test by running ``jbuilder
runtest``. For instance, if we make the test fail by replacing ``120``
by ``0`` we get:
We can now build and execute this test by running ``dune runtest``. For
instance, if we make the test fail by replacing ``120`` by ``0`` we get:
.. code:: bash
$ jbuilder runtest
$ dune runtest
[...]
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
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
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``
field:
@ -129,15 +128,15 @@ following test elements are clearly identified:
You can have a look at `this blog post
<https://blog.janestreet.com/testing-with-expectations/>`_ to find out
more about expectation tests. But Back to Jbuilder, the workflow for
expectation tests is always as follow:
more about expectation tests. To dune, the workflow for
expectation tests is always as follows:
- write the test with some empty expect nodes in it
- run the tests
- check the suggested correction and promote it as the original source
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:
.. code:: scheme
@ -147,13 +146,13 @@ your list of ppx rewriters as follow:
(inline_tests)
(preprocess (pps (ppx_expect)))))
Then calling ``jbuilder runtest`` will run these tests and in case of
mismatch Jbuilder will print a diff of the original source file and
Then calling ``dune runtest`` will run these tests and in case of
mismatch dune will print a diff of the original source file and
the suggested correction. For instance:
.. code:: bash
$ jbuilder runtest
$ dune runtest
[...]
-src/fact.ml
+src/fact.ml.corrected
@ -169,14 +168,14 @@ In order to accept the correction, simply run:
.. 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:
.. code:: bash
$ jbuilder runtest --auto-promote
$ dune runtest --auto-promote
Finally, some editor integration is possible to make the editor do the
promotion and make the workflow even smoother.
@ -184,7 +183,7 @@ promotion and make the workflow even smoother.
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
``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
--------------------------------------------
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
arguments. You can specify such flags by using a ``flags`` field, such
as:
@ -319,7 +318,7 @@ build as this would cause portability problems.
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
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
@ -335,9 +334,9 @@ Diffing the result
------------------
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
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:
.. code:: scheme
@ -350,29 +349,29 @@ command. For instance let's consider this test:
(action (diff tests.expected test.output))))
After having run ``tests.exe`` and dumping its output to
``tests.output``, Jbuilder will compare the latter to
``tests.expected``. In case of mismatch, Jbuilder will print a diff
and then the ``jbuilder promote`` command can be used to copy over the
``tests.output``, dune will compare the latter to
``tests.expected``. In case of mismatch, dune will print a diff
and then the ``dune promote`` command can be used to copy over the
generated ``test.output`` file to ``tests.expected`` in the source
tree. This provides a nice way of dealing with the usual *write code*,
*run*, *promote* cycle of testing. For instance:
.. code:: bash
$ jbuilder runtest
$ dune runtest
[...]
-tests.expected
+tests.output
File "tests.expected", line 1, characters 0-1:
-Hello, world!
+Good bye!
$ jbuilder promote
$ dune promote
Promoting _build/default/tests.output to tests.expected.
Note that if available, the diffing is done using the patdiff_ tool,
which displays nicer looking diffs that the standard ``diff``
tool. You can change that by passing ``--diff-command CMD`` to
Jbuilder.
dune.
.. _ppx_inline_test: https://github.com/janestreet/ppx_inline_test

96
doc/usage.rst
View File

@ -2,7 +2,7 @@
Usage
*****
This section describe usage of Jbuilder from the shell.
This section describe usage of dune from the shell.
.. _finding-root:
@ -40,7 +40,7 @@ order:
- ``/home/me/code/myproject/src/dune-workspace``
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.
In addition to determining the root, ``dune`` will read this file as
@ -58,7 +58,7 @@ as root.
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.
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
----------
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
the need of external tools. These includes:
@ -83,22 +83,22 @@ the need of external tools. These includes:
- ``<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:
.. 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
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
build it. When using ``--verbose``, It prints out the actual set of
targets when starting:
.. code:: bash
$ jbuilder build bin/prog.exe --verbose
$ dune build bin/prog.exe --verbose
...
Actual targets:
- _build/default/bin/prog.exe
@ -118,9 +118,9 @@ To build and run the tests for a particular build context, use
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
- ``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
``@``. For instance to run tests only from the current directory:
@ -157,7 +157,7 @@ is installable.
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.
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:
- ``jbuilder build @runtest``
- ``jbuilder runtest``
- ``dune build @runtest``
- ``dune runtest``
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
tests in a specific sub-directory and its children by using:
- ``jbuilder build @foo/bar/runtest``
- ``jbuilder runtest foo/bar``
- ``dune build @foo/bar/runtest``
- ``dune runtest foo/bar``
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.
.. code:: bash
$ jbuilder utop <dir> -- <args>
$ dune utop <dir> -- <args>
Where ``<dir>`` is a directory containing a ``jbuild`` file defining all the
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
``lib`` and implicit bindings for toplevel expressions.
@ -218,16 +218,16 @@ Requirements & Limitations
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:
.. 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
commented out the stanzas refering to a package that is not in the list
given to ``jbuilder``.
given to ``dune``.
Invocation from opam
====================
@ -245,9 +245,9 @@ release --default-target @install``. ``-p`` is the short version of
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
- 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 uses whatever concurrency option opam provides
- 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.
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.
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:
::
$ jbuilder install [PACKAGE]...
$ dune install [PACKAGE]...
without an argument, it will install all the packages available in the
workspace. With a specific list of packages, it will only install these
packages. If several build contexts are configured, the installation
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
to be able to use ``jbuilder install``.
to be able to use ``dune install``.
Destination
-----------
@ -319,9 +319,9 @@ are using this mechanism to setup where OCaml library files should be
copied.
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
``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
configured to point to the opam directory, so this rule makes no
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
- ``(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``
- ``(merlin)`` instructs Jbuilder to use this build context for
- ``(merlin)`` instructs dune to use this build context for
merlin
- ``(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
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
``(merlin)`` to this context.
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``
opam package must be installed).
@ -452,16 +452,16 @@ js_of_ocaml compiler
.. _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
recommemded to use `Topkg <https://github.com/dbuenzli/topkg>`__ for
this purpose.
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
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"
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
files:
@ -500,16 +500,16 @@ you are using git, topkg invokes this command to find out the version:
$ git describe --always --dirty
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
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
the default configuration. i.e. calling ``jbuilder subst`` at the root
``dune subst`` performs the same substitution ``topkg`` does with
the default configuration. i.e. calling ``dune subst`` at the root
of your project will rewrite in place all the files in your project.
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
$ 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
topkg and use it instead of ``jbuilder subst``.
topkg and use it instead of ``dune subst``.
Custom Build Directory
======================