diff --git a/doc/dune-files.rst b/doc/dune-files.rst index 7464ff35..0cf4d3a3 100644 --- a/doc/dune-files.rst +++ b/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 -``jbuild`` looks like: +``dune`` files are composed of stanzas. For instance a typical +``dune`` looks like: .. code:: scheme (library - ((name mylib) - (libraries (base lwt)))) + (name mylib) + (libraries base lwt)) (rule - ((targets (foo.ml)) - (deps (generator/gen.exe)) - (action (run ${<} -o ${@})))) + (targets foo.ml) + (deps generator/gen.exe) + (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 - ((name ) + 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 )`` 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 )`` field. ```` 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 ())`` is used to specify the dependencies +- ``(libraries )`` is used to specify the dependencies of the library. See the section about `Library dependencies`_ for more details - ``(wrapped )`` 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 which should be built by default. The +- ``(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 )`` 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) - (files ((.exe as ))))) + (section bin) + (files (.exe as ))) - ``(package )`` if there is a ``(public_name ...)`` field, this specifies the package the executables are part of -- ``(libraries ())`` specifies the library dependencies. +- ``(libraries )`` specifies the library dependencies. See the section about `Library dependencies`_ for more details - ``(link_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 ())`` where ```` is a list of entry point names. As for +- ``(names )`` where ```` 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 ())`` describes under what name each executable should +- ``(public_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 ()) - (action ) - )) + (targets ) + (action ) + ) ```` 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. ```` are: -- ``(deps ())`` to specify the dependencies of the +- ``(deps )`` to specify the dependencies of the rule. See the `Dependency specification`_ section for more details. - ``(mode )`` to specify how to handle the targets, see `modes`_ @@ -455,9 +455,9 @@ For instance: .. code:: scheme (rule - ((targets (b) - (deps (a) - (action (copy ${<} ${@})))))) + (targets b + (deps a + (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 (.ml)) - (deps (.mll)) - (action (chdir ${ROOT} (run ${bin:ocamllex} -q -o ${<}))))) + (targets .ml) + (deps .mll) + (action (chdir ${ROOT} (run ${bin:ocamllex} -q -o ${<})))) To use a different rule mode, use the long form: .. code:: scheme (ocamllex - ((modules ()) - (mode ))) + (modules ()) + (mode )) ocamlyacc --------- @@ -511,17 +511,17 @@ ocamlyacc .. code:: scheme (rule - ((targets (.ml .mli)) - (deps (.mly)) - (action (chdir ${ROOT} (run ${bin:ocamlyacc} ${<}))))) + (targets .ml .mli) + (deps .mly) + (action (chdir ${ROOT} (run ${bin:ocamlyacc} ${<})))) To use a different rule mode, use the long form: .. code:: scheme (ocamlyacc - ((modules ()) - (mode ))) + (modules ()) + (mode )) menhir ------ @@ -542,10 +542,9 @@ The syntax is as follows: .. code:: scheme (alias - ((name ) - (deps ()) - - )) + (name ) + (deps ) + ) ```` 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) - (action (run ${exe:my-test-program.exe} blah)))) + (name runtest) + (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
) - (files ()) - - )) + (section
) + (files ) + ) ``
`` 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) - (files ((mylib.el as emacs/site-lisp/mylib.el))))) + (section share_root) + (files (mylib.el as emacs/site-lisp/mylib.el))) ```` 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 -into the current jbuild file. Currently, the included file cannot be -generated and must be present in the source tree. This feature is -intended to be used in conjunction with promotion, when parts of a -jbuild file are to be generated. +The ``include`` stanza allows to include the contents of another file into the +current dune file. Currently, the included file cannot be generated and must be +present in the source tree. This feature is intended to be used in conjunction +with promotion, when parts of a dune 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) - (action (diff jbuild.inc jbuild.inc.gen)))) + (name runtest) + (action (diff dune.inc dune.inc.gen))) -With this jbuild file, running dune as follow will replace the -``jbuild.inc`` file in the source tree by the generated one: +With this dune file, running dune as follow will replace the +``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 ```` 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)) - (deps (foo.exe (glob_files *.txt))) - (action (run ${^})))) + (targets result.txt) + (deps foo.exe (glob_files *.txt)) + (action (run ${^}))) Here is another example: .. code:: scheme (rule - ((targets (foo.exe)) - (deps (foo.c)) - (action (run ${CC} -o ${@} ${<} -lfoolib)))) + (targets foo.exe) + (deps foo.c) + (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 -real name or the public name. For libraries that are part of the -installed world, or for libraries that are part of the current -workspace but in another scope, you need to use the public name. For -instance: ``(libraries (base re))``. +For libraries defined in the current scope, you can use either the real name or +the public name. For libraries that are part of the installed world, or for +libraries that are part of the current workspace but in another scope, you need +to use the public name. For 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)) - (deps (file.ml)) - (action (with-stdout-to ${@} (chdir ${ROOT} ))))) + (targets file.pp.ml) + (deps file.ml) + (action (with-stdout-to ${@} (chdir ${ROOT} )))) The equivalent of a ``-pp `` option passed to the OCaml compiler is ``(system " ${<}")``. @@ -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 )`` or simply ````: depend on this file @@ -1156,7 +1152,7 @@ follows: (flags (:standard )) -.. _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 -``src/foo/jbuild`` will be run from ``_build//src/foo``. +context as the dune file they are defined in. So for instance an action defined +in ``src/foo/dune`` will be run from ``_build//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 ``${:...}`` 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)) - (deps (blah.mll)) - (action (run ocamllex -o ${@} ${<})))) + (targets blah.ml) + (deps blah.mll) + (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)) - (deps (blah.mll)) - (action (chdir ${ROOT} (run ocamllex -o ${@} ${<}))))) + (targets blah.ml) + (deps blah.mll) + (action (chdir ${ROOT} (run ocamllex -o ${@} ${<})))) Locks ----- @@ -1315,37 +1311,36 @@ same lock: .. code:: scheme (alias - ((name runtest) - (deps (foo)) - (locks (m)) - (action (run test.exe ${<})))) + (name runtest) + (deps foo) + (locks m) + (action (run test.exe ${<}))) (alias - ((name runtest) - (deps (bar)) - (locks (m)) - (action (run test.exe ${<})))) + (name runtest) + (deps bar) + (locks m) + (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 -as file names. So for instance ``(with-lock m ...)`` in ``src/jbuild`` -and ``(with-lock ../src/m)`` in ``test/jbuild`` refer to the same -lock. +Although they don't live in the filesystem, lock names are interpreted as file +names. So for instance ``(with-lock m ...)`` in ``src/dune`` and ``(with-lock +../src/m)`` in ``test/dune`` refer to the same lock. -Note also that locks are per build context. So if your workspace has -two build contexts setup, the same rule might still be executed -concurrently between the two build contexts. If you want a lock that -is global to all build contexts, simply use an absolute filename: +Note also that locks are per build context. So if your workspace has two build +contexts setup, the same rule might still be executed concurrently between the +two build contexts. If you want a lock that is global to all build contexts, +simply use an absolute filename: .. code:: scheme (alias - ((name runtest) - (deps (foo)) - (locks (/tcp-port/1042)) - (action (run test.exe ${<})))) + (name runtest) + (deps foo) + (locks /tcp-port/1042) + (action (run test.exe ${<}))) .. _ocaml-syntax: @@ -1396,7 +1391,7 @@ Whenever an action ``(diff )`` or ``(diff? you to promote ```` as ```` if ```` is a source file and ```` 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) - (action (diff data.expected data.out)))) + (name runtest) + (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 -interpreted as an OCaml script that generates the ``jbuild`` file as described +If a ``dune`` file starts with ``(* -*- tuareg -*- *)``, then it is +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 `__ diff --git a/doc/project-layout-specification.rst b/doc/project-layout-specification.rst index 7f1cc73f..4704ed6c 100644 --- a/doc/project-layout-specification.rst +++ b/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. diff --git a/doc/terminology.rst b/doc/terminology.rst index 0022c50b..4becfa75 100644 --- a/doc/terminology.rst +++ b/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 diff --git a/doc/usage.rst b/doc/usage.rst index 2f73bb12..ca439652 100644 --- a/doc/usage.rst +++ b/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: