Update doc

Signed-off-by: Jeremie Dimino <jeremie@dimino.org>
This commit is contained in:
Jeremie Dimino 2018-06-29 23:30:27 +01:00 committed by Rudi Grinberg
parent 757400a6a6
commit 744430b684
4 changed files with 48 additions and 72 deletions

View File

@ -1426,8 +1426,11 @@ module Help = struct
Unix systems and $(b,Local Settings/dune/config) in the User home Unix systems and $(b,Local Settings/dune/config) in the User home
directory on Windows. However, it is possible to specify an directory on Windows. However, it is possible to specify an
alternative configuration file with the $(b,--config-file) option.|} alternative configuration file with the $(b,--config-file) option.|}
; `P {|This file must be written in S-expression syntax and be composed of ; `P {|The first line of the file must be of the form (lang dune X.Y) \
a list of stanzas. The following sections describe the stanzas available.|} where X.Y is the version of the dune language used in the file.|}
; `P {|The rest of the file must be written in S-expression syntax and be \
composed of a list of stanzas. The following sections describe \
the stanzas available.|}
; `S "DISPLAY MODES" ; `S "DISPLAY MODES"
; `P {|Syntax: $(b,\(display MODE\))|} ; `P {|Syntax: $(b,\(display MODE\))|}
; `P {|This stanza controls how Dune reports what it is doing to the user. ; `P {|This stanza controls how Dune reports what it is doing to the user.

View File

@ -112,16 +112,16 @@ building executables needed by the other contexts.
With such a setup, calling ``jbuilder build @install`` will build all With such a setup, calling ``jbuilder build @install`` will build all
the packages three times. the packages three times.
Note that instead of writing a ``jbuild-workspace`` file, you can also Note that instead of writing a ``dune-workspace`` file, you can also
use the ``-x`` command line option. Passing ``-x foo`` to ``jbuilder`` use the ``-x`` command line option. Passing ``-x foo`` to ``dune``
without having a ``jbuild-workspace`` file is the same as writing the without having a ``dune-workspace`` file is the same as writing the
following ``jbuild-workspace`` file: following ``dune-workspace`` file:
.. code:: scheme .. code:: scheme
(context (default (targets (foo)))) (context (default (targets (foo))))
If you have a ``jbuild-workspace`` and pass a ``-x foo`` option, If you have a ``dune-workspace`` and pass a ``-x foo`` option,
``foo`` will be added as target of all context stanzas. ``foo`` will be added as target of all context stanzas.
How does it work? How does it work?

View File

@ -38,7 +38,7 @@ Terminology
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 Jbuilder
is executed. Build contexts can be specified by writing a is executed. Build contexts can be specified by writing a
:ref:`jbuild-workspace` file :ref:`dune-workspace` file
- **build context root**: the root of a build context named ``foo`` is - **build context root**: the root of a build context named ``foo`` is
``<root>/_build/<foo>`` ``<root>/_build/<foo>``

View File

@ -9,71 +9,51 @@ This section describe usage of Jbuilder from the shell.
Finding the root Finding the root
================ ================
.. _jbuild-workspace: .. _dune-workspace:
jbuild-workspace dune-workspace
---------------- --------------
The root of the current workspace is determined by looking up a The root of the current workspace is determined by looking up a
``jbuild-workspace`` or ``dune-project`` file in the current directory ``dune-workspace`` or ``dune-project`` file in the current directory
and parent directories. and parent directories.
``jbuilder`` prints out the root when starting if it is not the ``dune`` prints out the root when starting if it is not the current
current directory: directory:
.. code:: bash .. code:: bash
$ jbuilder runtest $ dune runtest
Entering directory '/home/jdimino/code/jbuilder' Entering directory '/home/jdimino/code/dune'
... ...
More precisely, it will choose the outermost ancestor directory containing a More precisely, it will choose the outermost ancestor directory containing a
``jbuild-workspace`` file as root. For instance if you are in ``dune-workspace`` file as root. For instance if you are in
``/home/me/code/myproject/src``, then jbuilder will look for all these files in ``/home/me/code/myproject/src``, then jbuilder will look for all these files in
order: order:
- ``/jbuild-workspace`` - ``/dune-workspace``
- ``/home/jbuild-workspace`` - ``/home/dune-workspace``
- ``/home/me/jbuild-workspace`` - ``/home/me/dune-workspace``
- ``/home/me/code/jbuild-workspace`` - ``/home/me/code/dune-workspace``
- ``/home/me/code/myproject/jbuild-workspace`` - ``/home/me/code/myproject/dune-workspace``
- ``/home/me/code/myproject/src/jbuild-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, Jbuilder will
always use the outermost one. always use the outermost one.
In addition to determining the root, ``jbuilder`` will read this file as to In addition to determining the root, ``dune`` will read this file as
setup the configuration of the workspace unless the ``--workspace`` command line to setup the configuration of the workspace unless the ``--workspace``
option is used. See the section `Workspace configuration`_ for the syntax of command line option is used. See the section `Workspace
this file. configuration`_ for the syntax of this file.
jbuild-workspace\*
------------------
The following is deprecated and no longer works with ``dune``.
In addition to the previous rule, if no ``jbuild-workspace`` file is found,
``jbuilder`` will look for any file whose name starts with ``jbuild-workspace``
in ancestor directories. For instance ``jbuild-workspace.dev``. If such a file
is found, it will mark the root of the workspace. ``jbuilder`` will however not
read its contents.
The rationale for this rule is that it is good practice to have a
``jbuild-workspace.dev`` file at the root of your project.
For quick experiments, simply do this to mark the root:
.. code:: bash
$ touch jbuild-workspace.here
Current directory Current directory
----------------- -----------------
If none of the two previous rules appies, i.e. no ancestor directories If the previous rule doesn't apply, i.e. no ancestor directory has a
have a file whose name starts with ``jbuild-workspace``, then the file named ``dune-workspace``, then the current directory will be used
current directory will be used as root. as root.
Forcing the root (for scripts) Forcing the root (for scripts)
------------------------------ ------------------------------
@ -319,47 +299,49 @@ Workspace configuration
======================= =======================
By default, a workspace has only one build context named ``default`` By default, a workspace has only one build context named ``default``
which correspond to the environment in which ``jbuilder`` is run. You which correspond to the environment in which ``dune`` is run. You can
can define more contexts by writing a ``jbuild-workspace`` file. define more contexts by writing a ``dune-workspace`` file.
You can point ``jbuilder`` to an explicit ``jbuild-workspace`` file with You can point ``dune`` to an explicit ``dune-workspace`` file with
the ``--workspace`` option. For instance it is good practice to write a the ``--workspace`` option. For instance it is good practice to write a
``jbuild-workspace.dev`` in your project with all the version of OCaml ``dune-workspace.dev`` in your project with all the version of OCaml
your projects support. This way developers can tests that the code your projects support. This way developers can tests that the code
builds with all version of OCaml by simply running: builds with all version of OCaml by simply running:
.. code:: bash .. code:: bash
$ jbuilder build --workspace jbuild-workspace.dev @install @runtest $ dune build --workspace dune-workspace.dev @install @runtest
jbuild-workspace dune-workspace
---------------- --------------
The ``jbuild-workspace`` file uses the S-expression syntax. This is what The ``dune-workspace`` file uses the S-expression syntax. This is what
a typical ``jbuild-workspace`` file looks like: a typical ``dune-workspace`` file looks like:
.. code:: scheme .. code:: scheme
(lang dune 1.0)
(context (opam (switch 4.02.3))) (context (opam (switch 4.02.3)))
(context (opam (switch 4.03.0))) (context (opam (switch 4.03.0)))
(context (opam (switch 4.04.0))) (context (opam (switch 4.04.0)))
The rest of this section describe the stanzas available. The rest of this section describe the stanzas available.
Note that an empty ``jbuild-workspace`` file is interpreted the same Note that an empty ``dune-workspace`` file is interpreted the same
as one containing exactly: as one containing exactly:
.. code:: scheme .. code:: scheme
(lang dune 1.0)
(context default) (context default)
This allows you to use an empty ``jbuild-workspace`` file to mark This allows you to use an empty ``dune-workspace`` file to mark
the root of your project. the root of your project.
profile profile
~~~~~~~ ~~~~~~~
The build profile can be selected in the ``jbuild-workspace`` file by The build profile can be selected in the ``dune-workspace`` file by
write a ``(profile ...)`` stanza. For instance: write a ``(profile ...)`` stanza. For instance:
.. code:: scheme .. code:: scheme
@ -404,22 +386,13 @@ for more information.
Merlin reads compilation artifacts and it can only read the Merlin reads compilation artifacts and it can only read the
compilation artifacts of a single context. Usually, you should use compilation artifacts of a single context. Usually, you should use
the artifacts from the ``default`` context, and if you have the the artifacts from the ``default`` context, and if you have the
``(context default)`` stanza in your ``jbuild-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 Jbuilder
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.
Note that the following syntax is still accepted but is deprecated:
.. code:: scheme
(context ((switch <opam-switch-name>)
<optional-fields>))
it is interpreted the same as ``(context (opam (switch ...) ...))``.
Building JavaScript with js_of_ocaml Building JavaScript with js_of_ocaml
==================================== ====================================