Update doc
Signed-off-by: Jeremie Dimino <jeremie@dimino.org>
This commit is contained in:
parent
757400a6a6
commit
744430b684
|
@ -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.
|
||||||
|
|
|
@ -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?
|
||||||
|
|
|
@ -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>``
|
||||||
|
|
101
doc/usage.rst
101
doc/usage.rst
|
@ -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
|
||||||
====================================
|
====================================
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue