From 744430b6847e215549f8c34e489f5b7779c37117 Mon Sep 17 00:00:00 2001 From: Jeremie Dimino Date: Fri, 29 Jun 2018 23:30:27 +0100 Subject: [PATCH] Update doc Signed-off-by: Jeremie Dimino --- bin/main.ml | 7 ++- doc/advanced-topics.rst | 10 ++-- doc/terminology.rst | 2 +- doc/usage.rst | 101 +++++++++++++++------------------------- 4 files changed, 48 insertions(+), 72 deletions(-) diff --git a/bin/main.ml b/bin/main.ml index 0469daea..8b6c3ca9 100644 --- a/bin/main.ml +++ b/bin/main.ml @@ -1426,8 +1426,11 @@ module Help = struct Unix systems and $(b,Local Settings/dune/config) in the User home directory on Windows. However, it is possible to specify an alternative configuration file with the $(b,--config-file) option.|} - ; `P {|This file must be written in S-expression syntax and be composed of - a list of stanzas. The following sections describe the stanzas available.|} + ; `P {|The first line of the file must be of the form (lang dune X.Y) \ + 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" ; `P {|Syntax: $(b,\(display MODE\))|} ; `P {|This stanza controls how Dune reports what it is doing to the user. diff --git a/doc/advanced-topics.rst b/doc/advanced-topics.rst index d29d975f..0094deb5 100644 --- a/doc/advanced-topics.rst +++ b/doc/advanced-topics.rst @@ -112,16 +112,16 @@ building executables needed by the other contexts. With such a setup, calling ``jbuilder build @install`` will build all the packages three times. -Note that instead of writing a ``jbuild-workspace`` file, you can also -use the ``-x`` command line option. Passing ``-x foo`` to ``jbuilder`` -without having a ``jbuild-workspace`` file is the same as writing the -following ``jbuild-workspace`` file: +Note that instead of writing a ``dune-workspace`` file, you can also +use the ``-x`` command line option. Passing ``-x foo`` to ``dune`` +without having a ``dune-workspace`` file is the same as writing the +following ``dune-workspace`` file: .. code:: scheme (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. How does it work? diff --git a/doc/terminology.rst b/doc/terminology.rst index 0afb5801..7cac56d7 100644 --- a/doc/terminology.rst +++ b/doc/terminology.rst @@ -38,7 +38,7 @@ Terminology specific configuration from the user, there is always a ``default`` build context, which corresponds to the environment in which Jbuilder 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/`` diff --git a/doc/usage.rst b/doc/usage.rst index 4a5a9a9e..c12ba0ac 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -9,71 +9,51 @@ This section describe usage of Jbuilder from the shell. Finding the root ================ -.. _jbuild-workspace: +.. _dune-workspace: -jbuild-workspace ----------------- +dune-workspace +-------------- 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. -``jbuilder`` prints out the root when starting if it is not the -current directory: +``dune`` prints out the root when starting if it is not the current +directory: .. code:: bash - $ jbuilder runtest - Entering directory '/home/jdimino/code/jbuilder' + $ dune runtest + Entering directory '/home/jdimino/code/dune' ... 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 order: -- ``/jbuild-workspace`` -- ``/home/jbuild-workspace`` -- ``/home/me/jbuild-workspace`` -- ``/home/me/code/jbuild-workspace`` -- ``/home/me/code/myproject/jbuild-workspace`` -- ``/home/me/code/myproject/src/jbuild-workspace`` +- ``/dune-workspace`` +- ``/home/dune-workspace`` +- ``/home/me/dune-workspace`` +- ``/home/me/code/dune-workspace`` +- ``/home/me/code/myproject/dune-workspace`` +- ``/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 always use the outermost one. -In addition to determining the root, ``jbuilder`` will read this file as to -setup the configuration of the workspace unless the ``--workspace`` command line -option is used. See the section `Workspace 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 +In addition to determining the root, ``dune`` will read this file as +to setup the configuration of the workspace unless the ``--workspace`` +command line option is used. See the section `Workspace +configuration`_ for the syntax of this file. Current directory ----------------- -If none of the two previous rules appies, i.e. no ancestor directories -have a file whose name starts with ``jbuild-workspace``, then the -current directory will be used as root. +If the previous rule doesn't apply, i.e. no ancestor directory has a +file named ``dune-workspace``, then the current directory will be used +as root. Forcing the root (for scripts) ------------------------------ @@ -319,47 +299,49 @@ Workspace configuration ======================= By default, a workspace has only one build context named ``default`` -which correspond to the environment in which ``jbuilder`` is run. You -can define more contexts by writing a ``jbuild-workspace`` file. +which correspond to the environment in which ``dune`` is run. You can +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 -``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 builds with all version of OCaml by simply running: .. 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 -a typical ``jbuild-workspace`` file looks like: +The ``dune-workspace`` file uses the S-expression syntax. This is what +a typical ``dune-workspace`` file looks like: .. code:: scheme + (lang dune 1.0) (context (opam (switch 4.02.3))) (context (opam (switch 4.03.0))) (context (opam (switch 4.04.0))) 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: .. code:: scheme + (lang dune 1.0) (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. 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: .. code:: scheme @@ -404,22 +386,13 @@ for more information. Merlin reads compilation artifacts and it can only read the compilation artifacts of a single context. Usually, you should use 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. 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 ``(merlin)`` to this context. -Note that the following syntax is still accepted but is deprecated: - -.. code:: scheme - - (context ((switch ) - )) - -it is interpreted the same as ``(context (opam (switch ...) ...))``. - Building JavaScript with js_of_ocaml ====================================