Port over the dune file description page to dune (#953)

doc/dune-files.rst

@@ -10,19 +10,19 @@ The syntax of ``dune`` files is described in :ref:`metadata-format` section.
 Stanzas
 =======
 
-``jbuild`` files are composed of stanzas. For instance a typical
+``dune`` files are composed of stanzas. For instance a typical
-``jbuild`` looks like:
+``dune`` looks like:
 
 .. code:: scheme
 
     (library
-     ((name mylib)
+     (name mylib)
-      (libraries (base lwt))))
+     (libraries base lwt))
 
     (rule
-     ((targets (foo.ml))
+     (targets foo.ml)
-      (deps    (generator/gen.exe))
+     (deps    generator/gen.exe)
-      (action  (run ${<} -o ${@}))))
+     (action  (run ${<} -o ${@})))
 
 The following sections describe the available stanzas and their meaning.
 
@@ -40,10 +40,10 @@ format of library stanzas is as follows:
 
 .. code:: scheme
 
-    (library
+    library
-      ((name <library-name>)
+      (name <library-name>
        <optional-fields>
-      ))
+      )
 
 ``<library-name>`` is the real name of the library. It determines the
 names of the archive files generated for the library as well as the
@@ -72,14 +72,14 @@ modules you want.
 
 - ``(modules <modules>)`` specifies what modules are part of the library. By
   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
+  ``dune`` 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`_
   where elements are module names and don't need to start with a uppercase
   letter. For instance to exclude module ``Foo``: ``(modules (:standard \
   foo))``
 
-- ``(libraries (<library-dependencies>))`` is used to specify the dependencies
+- ``(libraries <library-dependencies>)`` is used to specify the dependencies
   of the library. See the section about `Library dependencies`_ for more details
 
 - ``(wrapped <boolean>)`` specifies whether the modules of the library should be
@@ -114,7 +114,7 @@ modules you want.
   that must be installed, you must list them in this field, with the ``.h``
   extension
 
-- ``(modes (<modes>))`` modes which should be built by default. The
+- ``(modes <modes>)`` modes which should be built by default. The
   most common use for this feature is to disable native compilation
   when writing libraries for the OCaml toplevel. The following modes
   are available: ``byte``, ``native`` and ``best``. ``best`` is
@@ -140,7 +140,7 @@ modules you want.
   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`
+- ``js_of_ocaml``. See the section about :ref:`dune-jsoo`
 
 - ``flags``, ``ocamlc_flags`` and ``ocamlopt_flags``. See the section about
   `OCaml flags`_
@@ -232,18 +232,18 @@ Executables can also be linked as object or shared object files. See
 
 - ``(public_name <public-name>)`` specifies that the executable should be
   installed under that name. It is the same as adding the following stanza to
-  your ``jbuild`` file:
+  your ``dune`` file:
 
    .. code:: scheme
 
        (install
-        ((section bin)
+        (section bin)
-         (files ((<name>.exe as <public-name>)))))
+        (files (<name>.exe as <public-name>)))
 
 - ``(package <package>)`` if there is a ``(public_name ...)`` field, this
   specifies the package the executables are part of
 
-- ``(libraries (<library-dependencies>))`` specifies the library dependencies.
+- ``(libraries <library-dependencies>)`` specifies the library dependencies.
   See the section about `Library dependencies`_ for more details
 
 - ``(link_flags <flags>)`` specifies additional flags to pass to the linker.
@@ -362,11 +362,11 @@ it is used to describe several executables sharing the same configuration.
 It shares the same fields as the ``executable`` stanza, except that instead of
 ``(name ...)`` and ``(public_name ...)`` you must use:
 
-- ``(names (<names>))`` where ``<names>`` is a list of entry point names. As for
+- ``(names <names>)`` where ``<names>`` is a list of entry point names. As for
   ``executable`` you only need to specify the modules containing the entry point
   of each executable
 
-- ``(public_names (<names>))`` describes under what name each executable should
+- ``(public_names <names>)`` describes under what name each executable should
   be installed. The list of names must be of the same length as the list in the
   ``(names ...)`` field. Moreover you can use ``-`` for executables that
   shouldn't be installed
@@ -382,9 +382,9 @@ The syntax is as follows:
 .. code:: scheme
 
     (rule
-      ((targets (<filenames>))
+      (targets <filenames>)
-       (action  <action>)
+      (action  <action>)
-       <optional-fields>))
+      <optional-fields>)
 
 ``<filenames>`` is a list of file names. Note that currently dune only
 support user rules with targets in the current directory.
@@ -394,7 +394,7 @@ See the `User actions`_ section for more details.
 
 ``<optional-fields>`` are:
 
-- ``(deps (<deps-conf list>))`` to specify the dependencies of the
+- ``(deps <deps-conf list>)`` to specify the dependencies of the
   rule. See the `Dependency specification`_ section for more details.
 
 - ``(mode <mode>)`` to specify how to handle the targets, see `modes`_
@@ -455,9 +455,9 @@ For instance:
 .. code:: scheme
 
     (rule
-      ((targets (b)
+      (targets b
-       (deps    (a)
+      (deps    a
-       (action  (copy ${<} ${@}))))))
+      (action  (copy ${<} ${@})))))
 
 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
@@ -491,17 +491,17 @@ ocamllex
 .. code:: scheme
 
     (rule
-      ((targets (<name>.ml))
+      (targets <name>.ml)
-       (deps    (<name>.mll))
+      (deps    <name>.mll)
-       (action  (chdir ${ROOT} (run ${bin:ocamllex} -q -o ${<})))))
+      (action  (chdir ${ROOT} (run ${bin:ocamllex} -q -o ${<}))))
 
 To use a different rule mode, use the long form:
 
 .. code:: scheme
 
     (ocamllex
-      ((modules (<names>))
+      (modules (<names>))
-       (mode    <mode>)))
+      (mode    <mode>))
 
 ocamlyacc
 ---------
@@ -511,17 +511,17 @@ ocamlyacc
 .. code:: scheme
 
     (rule
-      ((targets (<name>.ml <name>.mli))
+      (targets <name>.ml <name>.mli)
-       (deps    (<name>.mly))
+      (deps    <name>.mly)
-       (action  (chdir ${ROOT} (run ${bin:ocamlyacc} ${<})))))
+      (action  (chdir ${ROOT} (run ${bin:ocamlyacc} ${<}))))
 
 To use a different rule mode, use the long form:
 
 .. code:: scheme
 
     (ocamlyacc
-      ((modules (<names>))
+      (modules (<names>))
-       (mode    <mode>)))
+      (mode    <mode>))
 
 menhir
 ------
@@ -542,10 +542,9 @@ The syntax is as follows:
 .. code:: scheme
 
     (alias
-      ((name    <alias-name>)
+     (name    <alias-name>)
-       (deps    (<deps-conf list>))
+     (deps    <deps-conf list>)
-       <optional-fields>
+      <optional-fields>)
-       ))
 
 ``<name>`` is an alias name such as ``runtest``.
 
@@ -569,8 +568,8 @@ The typical use of the ``alias`` stanza is to define tests:
 .. code:: scheme
 
     (alias
-      ((name   runtest)
+     (name   runtest)
-       (action (run ${exe:my-test-program.exe} blah))))
+     (action (run ${exe:my-test-program.exe} blah)))
 
 See the section about :ref:`running-tests` for details.
 
@@ -594,10 +593,9 @@ The syntax is as follows:
 .. code:: scheme
 
     (install
-      ((section <section>)
+      (section <section>)
-       (files   (<filenames>))
+       (files   <filenames>)
-       <optional-fields>
+       <optional-fields>)
-      ))
 
 ``<section>`` is the installation section, as described in the opam
 manual. The following sections are available:
@@ -631,8 +629,8 @@ instance, to install a file ``mylib.el`` as
 .. code:: scheme
 
     (install
-      ((section share_root)
+     (section share_root)
-       (files   ((mylib.el as emacs/site-lisp/mylib.el)))))
+     (files   (mylib.el as emacs/site-lisp/mylib.el)))
 
 ``<optional-fields>`` are:
 
@@ -676,32 +674,31 @@ as the difference between the ``copy`` and ``copy#`` action. See the
 include
 -------
 
-The ``include`` stanza allows to include the contents of another file
+The ``include`` stanza allows to include the contents of another file into the
-into the current jbuild file. Currently, the included file cannot be
+current dune file. Currently, the included file cannot be generated and must be
-generated and must be present in the source tree. This feature is
+present in the source tree. This feature is intended to be used in conjunction
-intended to be used in conjunction with promotion, when parts of a
+with promotion, when parts of a dune file are to be generated.
-jbuild file are to be generated.
 
 For instance:
 
 .. code:: scheme
 
-    (include jbuild.inc)
+    (include dune.inc)
 
-    (rule (with-stdout-to jbuild.inc.gen (run ./gen-jbuild.exe)))
+    (rule (with-stdout-to dune.inc.gen (run ./gen-dune.exe)))
 
     (alias
-     ((name   runtest)
+     (name   runtest)
-      (action (diff jbuild.inc jbuild.inc.gen))))
+     (action (diff dune.inc dune.inc.gen)))
 
-With this jbuild file, running dune as follow will replace the
+With this dune file, running dune as follow will replace the
-``jbuild.inc`` file in the source tree by the generated one:
+``dune.inc`` file in the source tree by the generated one:
 
 .. code:: shell
 
     $ dune build @runtest --auto-promote
 
-.. _jbuild-env:
+.. _dune-env:
 
 env
 ---
@@ -724,7 +721,7 @@ directory. You can use ``_`` to match any build profile.
 Currently ``<settings>`` can be any OCaml flags field, see `OCaml
 flags`_ for more details.
 
-.. _jbuild-ignored_subdirs:
+.. _dune-ignored_subdirs:
 
 ignored_subdirs
 ---------------
@@ -915,18 +912,18 @@ used as a program name, for instance:
 .. code:: scheme
 
     (rule
-     ((targets (result.txt))
+     (targets result.txt)
-      (deps    (foo.exe (glob_files *.txt)))
+     (deps    foo.exe (glob_files *.txt))
-      (action  (run ${^}))))
+     (action  (run ${^})))
 
 Here is another example:
 
 .. code:: scheme
 
     (rule
-     ((targets (foo.exe))
+     (targets foo.exe)
-      (deps    (foo.c))
+     (deps    foo.c)
-      (action  (run ${CC} -o ${@} ${<} -lfoolib))))
+     (action  (run ${CC} -o ${@} ${<} -lfoolib)))
 
 
 Library dependencies
@@ -935,11 +932,10 @@ Library dependencies
 Dependencies on libraries are specified using ``(libraries ...)`` fields in
 ``library`` and ``executables`` stanzas.
 
-For libraries defined in the current scope, you can use either the
+For libraries defined in the current scope, you can use either the real name or
-real name or the public name. For libraries that are part of the
+the public name. For libraries that are part of the installed world, or for
-installed world, or for libraries that are part of the current
+libraries that are part of the current workspace but in another scope, you need
-workspace but in another scope, you need to use the public name. For
+to use the public name. For instance: ``(libraries base re)``.
-instance: ``(libraries (base re))``.
 
 When resolving libraries, libraries that are part of the workspace are always
 preferred to ones that are part of the installed world.
@@ -1011,9 +1007,9 @@ you had setup a rule for every file of the form:
    .. code:: scheme
 
        (rule
-        ((targets (file.pp.ml))
+        (targets file.pp.ml)
-         (deps    (file.ml))
+        (deps    file.ml)
-         (action  (with-stdout-to ${@} (chdir ${ROOT} <action>)))))
+        (action  (with-stdout-to ${@} (chdir ${ROOT} <action>))))
 
 The equivalent of a ``-pp <command>`` option passed to the OCaml compiler is
 ``(system "<command> ${<}")``.
@@ -1074,7 +1070,7 @@ For instance:
 Dependency specification
 ------------------------
 
-Dependencies in ``jbuild`` files can be specified using one of the following
+Dependencies in ``dune`` files can be specified using one of the following
 syntax:
 
 - ``(file <filename>)`` or simply ``<filename>``: depend on this file
@@ -1156,7 +1152,7 @@ follows:
 
     (flags (:standard <my options>))
 
-.. _jbuild-jsoo:
+.. _dune-jsoo:
 
 js_of_ocaml
 -----------
@@ -1186,8 +1182,8 @@ User actions
 ``(action ...)`` fields describe user actions.
 
 User actions are always run from the same subdirectory of the current build
-context as the jbuild they are defined in. So for instance an action defined in
+context as the dune file they are defined in. So for instance an action defined
-``src/foo/jbuild`` will be run from ``_build/<context>/src/foo``.
+in ``src/foo/dune`` will be run from ``_build/<context>/src/foo``.
 
 The argument of ``(action ...)`` fields is a small DSL that is interpreted by
 dune directly and doesn't require an external shell. All atoms in the DSL
@@ -1252,26 +1248,26 @@ something shorter.
 
 Note: expansion of the special ``${<kind>:...}`` is done relative to the current
 working directory of the part of the DSL being executed. So for instance if you
-have this action in a ``src/foo/jbuild``:
+have this action in a ``src/foo/dune``:
 
 .. code:: scheme
 
-    (action (chdir ../../.. (echo ${path:jbuild})))
+    (action (chdir ../../.. (echo ${path:dune})))
 
-Then ``${path:jbuild}`` will expand to ``src/foo/jbuild``. When you run various
+Then ``${path:dune}`` will expand to ``src/foo/dune``. When you run various
 tools, they often use the filename given on the command line in error messages.
 As a result, if you execute the command from the original directory, it will
 only see the basename.
 
-To understand why this is important, let's consider this jbuild living in
+To understand why this is important, let's consider this dune file living in
 ``src/foo``:
 
 ::
 
     (rule
-     ((targets (blah.ml))
+     (targets blah.ml)
-      (deps    (blah.mll))
+     (deps    blah.mll)
-      (action  (run ocamllex -o ${@} ${<}))))
+     (action  (run ocamllex -o ${@} ${<})))
 
 Here the command that will be executed is:
 
@@ -1293,9 +1289,9 @@ of your project. What you should write instead is:
 ::
 
     (rule
-     ((targets (blah.ml))
+     (targets blah.ml)
-      (deps    (blah.mll))
+     (deps    blah.mll)
-      (action  (chdir ${ROOT} (run ocamllex -o ${@} ${<})))))
+     (action  (chdir ${ROOT} (run ocamllex -o ${@} ${<}))))
 
 Locks
 -----
@@ -1315,37 +1311,36 @@ same lock:
 .. code:: scheme
 
     (alias
-     ((name   runtest)
+     (name   runtest)
-      (deps   (foo))
+     (deps   foo)
-      (locks  (m))
+     (locks  m)
-      (action (run test.exe ${<}))))
+     (action (run test.exe ${<})))
 
     (alias
-     ((name   runtest)
+     (name   runtest)
-      (deps   (bar))
+     (deps   bar)
-      (locks  (m))
+     (locks  m)
-      (action (run test.exe ${<}))))
+     (action (run test.exe ${<})))
 
 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
+Although they don't live in the filesystem, lock names are interpreted as file
-as file names. So for instance ``(with-lock m ...)`` in ``src/jbuild``
+names. So for instance ``(with-lock m ...)`` in ``src/dune`` and ``(with-lock
-and ``(with-lock ../src/m)`` in ``test/jbuild`` refer to the same
+../src/m)`` in ``test/dune`` refer to the same lock.
-lock.
 
-Note also that locks are per build context. So if your workspace has
+Note also that locks are per build context. So if your workspace has two build
-two build contexts setup, the same rule might still be executed
+contexts setup, the same rule might still be executed concurrently between the
-concurrently between the two build contexts. If you want a lock that
+two build contexts. If you want a lock that is global to all build contexts,
-is global to all build contexts, simply use an absolute filename:
+simply use an absolute filename:
 
 .. code:: scheme
 
     (alias
-     ((name   runtest)
+     (name   runtest)
-      (deps   (foo))
+     (deps   foo)
-      (locks  (/tcp-port/1042))
+     (locks  /tcp-port/1042)
-      (action (run test.exe ${<}))))
+     (action (run test.exe ${<})))
 
 .. _ocaml-syntax:
 
@@ -1396,7 +1391,7 @@ Whenever an action ``(diff <file1> <file2>)`` or ``(diff?  <file1>
 you to promote ``<file2>`` as ``<file1>`` if ``<file1>`` is a source
 file and ``<file2>`` is a generated file.
 
-More precisely, let's consider the following jbuild file:
+More precisely, let's consider the following dune file:
 
 .. code:: scheme
 
@@ -1404,8 +1399,8 @@ More precisely, let's consider the following jbuild file:
     (with-stdout-to data.out (run ./test.exe)))
 
    (alias
-    ((name   runtest)
+    (name   runtest)
-     (action (diff data.expected data.out))))
+    (action (diff data.expected data.out)))
 
 Where ``data.expected`` is a file committed in the source
 repository. You can use the following workflow to update your test:
@@ -1423,8 +1418,8 @@ automatically do the promotion.
 OCaml syntax
 ============
 
-If a ``jbuild`` file starts with ``(* -*- tuareg -*- *)``, then it is
+If a ``dune`` file starts with ``(* -*- tuareg -*- *)``, then it is
-interpreted as an OCaml script that generates the ``jbuild`` file as described
+interpreted as an OCaml script that generates the ``dune`` file as described
 in the rest of this section. The code in the script will have access to a
 `Jbuild_plugin
 <https://github.com/ocaml/dune/blob/master/plugin/jbuild_plugin.mli>`__

doc/project-layout-specification.rst

@@ -287,4 +287,4 @@ jbuild-ignore (deprecated)
 ==========================
 
 ``jbuild-ignore`` files are deprecated and replaced by
-:ref:`jbuild-ignored_subdirs` stanzas in ``dune`` files.
+:ref:`dune-ignored_subdirs` stanzas in ``dune`` files.

doc/terminology.rst

@@ -63,7 +63,7 @@ Terminology
   various parameters, such as the compilation flags. Inside a scope,
   each directory inherit the environment from its parent. At the root
   of every scope, a default environment is used. At any point, the
-  environment can be altered using an :ref:`jbuild-env` stanza.
+  environment can be altered using an :ref:`dune-env` stanza.
 
 - **build profile**: a global setting that influence various
   defaults. It can be set from the command line using ``--profile

doc/usage.rst

@@ -447,7 +447,7 @@ The separate compilation mode will be selected when the build profile
 is ``dev``, which is the default. There is currently no other way to
 control this behaviour.
 
-See the section about :ref:`jbuild-jsoo` for passing custom flags to the
+See the section about :ref:`dune-jsoo` for passing custom flags to the
 js_of_ocaml compiler
 
 .. _using-topkg: