diff --git a/doc/advanced-topics.rst b/doc/advanced-topics.rst index 0094deb5..30a595fd 100644 --- a/doc/advanced-topics.rst +++ b/doc/advanced-topics.rst @@ -2,28 +2,28 @@ Advanced topics *************** -This section describes some details of Jbuilder for advanced users. +This section describes some details of dune for advanced users. META file generation ==================== -Jbuilder uses ``META`` files from the `findlib library +Dune uses ``META`` files from the `findlib library manager `__ in order to interoperate with the rest of the world when installing libraries. It is able to generate them automatically. However, for the rare cases where you would need a specific ``META`` file, or to ease the transition -of a project to Jbuilder, it is allowed to write/generate a specific +of a project to dune, it is allowed to write/generate a specific one. In order to do that, write or setup a rule to generate a ``META..template`` file in the same directory as the -``.opam`` file. Jbuilder will generate a ``META.`` +``.opam`` file. Dune will generate a ``META.`` file from the ``META..template`` file by replacing lines of the form ``# JBUILDER_GEN`` by the contents of the ``META`` it would normally generate. For instance if you want to extend the ``META`` file generated by -Jbuilder you can write the folliwing ``META.foo.template`` file: +dune you can write the folliwing ``META.foo.template`` file: .. code:: @@ -33,7 +33,7 @@ Jbuilder you can write the folliwing ``META.foo.template`` file: Findlib integration and limitations =================================== -Jbuilder uses ``META`` files to support external libraries. However, it +Dune uses ``META`` files to support external libraries. However, it doesn't export the full power of findlib to the user, and especially it doesn't let the user specify *predicates*. @@ -41,13 +41,13 @@ The reason for this limitation is that so far they haven't been needed, and adding full support for them would complicate things quite a lot. In particular, complex ``META`` files are often hand-written and the various features they offer are only available once the package is -installed, which goes against the root ideas jbuilder is built on. +installed, which goes against the root ideas dune is built on. -In practice, jbuilder interpret ``META`` files assuming the following +In practice, dune interprets ``META`` files assuming the following set of predicates: - ``mt``: what this means is that using a library that can be used - with or without threads with jbuilder will force the threaded + with or without threads with dune will force the threaded version - ``mt_posix``: forces the use of posix threads rather than VM @@ -62,7 +62,7 @@ set of predicates: Cross Compilation ================= -Jbuilder allows for cross compilation by defining build contexts with +Dune allows for cross compilation by defining build contexts with multiple targets. Targets are specified by adding a ``targets`` field to the definition of a build context. @@ -74,7 +74,7 @@ to the definition of a build context. - the name of an alternative toolchain Note that at the moment, there is no official support for -cross-compilation in OCaml. Jbuilder supports the opam-cross-x +cross-compilation in OCaml. Dune supports the opam-cross-x repositories from the `ocaml-cross organization on github `_, such as: @@ -105,11 +105,11 @@ This configuration defines three build contexts: - ``default.android`` Note that the ``native`` target is always implicitly added when not -present. However, when implicitly added ``jbuilder build @install`` +present. However, when implicitly added ``dune build @install`` will skip this context, i.e. ``default`` will only be used for building executables needed by the other contexts. -With such a setup, calling ``jbuilder build @install`` will build all +With such a setup, calling ``dune build @install`` will build all the packages three times. Note that instead of writing a ``dune-workspace`` file, you can also @@ -142,13 +142,13 @@ following ``src/jbuild`` file: (executable ((name foo))) (rule (with-stdout-to blah (run ./foo.exe))) -When building ``_build/default/src/blah``, jbuilder will resolve ``./foo.exe`` to +When building ``_build/default/src/blah``, dune will resolve ``./foo.exe`` to ``_build/default/src/foo.exe`` as expected. However, for -``_build/default.windows/src/blah`` jbuilder will resolve ``./foo.exe`` to +``_build/default.windows/src/blah`` dune will resolve ``./foo.exe`` to ``_build/default/src/foo.exe`` Assuming that the right packages are installed or that your workspace -has no external dependencies, jbuilder will be able to cross-compile a +has no external dependencies, dune will be able to cross-compile a given package without doing anything special. Some packages might still have to be updated to support cross-compilation. For @@ -164,6 +164,6 @@ Classical ppx *classical ppx* refers to running ppx using the -ppx compiler option, which is composed using Findlib. Even though this is useful to run some (usually old) -ppx's which don't support drivers, Jbuilder does not support preprocessing with +ppx's which don't support drivers, dune does not support preprocessing with ppx this way. but a workaround exists using the `ppxfind `_ tool. diff --git a/doc/documentation.rst b/doc/documentation.rst index 7061124b..35c40d95 100644 --- a/doc/documentation.rst +++ b/doc/documentation.rst @@ -7,8 +7,8 @@ Generating Documentation Prerequisites ============= -Documentation in jbuilder is done courtesy of the odoc_ tool. Therefore, to -generate documentation in jbuilder, you will need to install this tool. This +Documentation in dune is done courtesy of the odoc_ tool. Therefore, to +generate documentation in dune, you will need to install this tool. This should likely be done with opam: :: @@ -33,7 +33,7 @@ to generate documentation for your project is building this alias: :: - $ jbuilder build @doc + $ dune build @doc An index page containing links to all the opam packages in your project can be found in: @@ -46,7 +46,7 @@ Documentation for private libraries may also be built with: :: - $ jbuilder build @doc-private + $ dune build @doc-private But this libraries will not be in the main html listing above, since they do not belong to any particular package. But the generated html will still be found in @@ -70,7 +70,7 @@ in the same syntax as ocamldoc comments. Where ```` are: - ``(package )`` the package this documentation should be attached to. If - this absent, jbuilder will try to infer it based on the location of the + this absent, dune will try to infer it based on the location of the stanza. - ``(mld_files )`` where ```` field follows the @@ -81,7 +81,7 @@ Where ```` are: The ``index.mld`` file (specified as ``index`` in ``mld_files``) is treated specially by jbulder. This will be the file used to generate the entry page for the package. This is the page that will be linked from the main package listing. -If you omit writing an ``index.mld``, jbuilder will generate one with the entry +If you omit writing an ``index.mld``, dune will generate one with the entry modules for your package. But this generated will not be installed. All mld files attached to a package will be included in the generated diff --git a/doc/jbuild.rst b/doc/dune-files.rst similarity index 92% rename from doc/jbuild.rst rename to doc/dune-files.rst index 6a515ac1..23daa2db 100644 --- a/doc/jbuild.rst +++ b/doc/dune-files.rst @@ -1,13 +1,11 @@ -******************** -jbuild specification -******************** +********** +dune files +********** -``jbuild`` files are the main part of Jbuilder, and are the origin of -its name. They are used to describe libraries, executables, tests, and -everything Jbuilder needs to know about. +``dune`` files are the main part of dune. They are used to describe libraries, +executables, tests, and everything dune needs to know about. -The syntax of ``jbuild`` files is described in -:ref:``metadata-format`` section. +The syntax of ``dune`` files is described in :ref:`metadata-format` section. Stanzas ======= @@ -64,16 +62,16 @@ modules you want. - ``(public_name )`` this is the name under which the library can be referred to as a dependency when it is not part of the current workspace, i.e. when it is installed. Without a ``(public_name ...)`` field, the library - will not be installed by Jbuilder. The public name must start by the package + will not be installed by dune. The public name must start by the package name it is part of and optionally followed by a dot and anything else you - want. The package name must be one of the packages that Jbuilder knows about, + want. The package name must be one of the packages that dune knows about, as determined by the :ref:`opam-files` - ``(synopsis )`` should give a one-line description of the library. This is used by tools that list installed libraries - ``(modules )`` specifies what modules are part of the library. By - default Jbuilder will use all the .ml/.re files in the same directory as the + 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 as ones generated by user rules. You can restrict this list by using a ``(modules )`` field. ```` uses the `Ordered set language`_ @@ -91,7 +89,7 @@ modules you want. an executables, polluting the top-level namespace will make your library unusable with other libraries if there is a module name clash. This option is only intended for libraries that manually prefix all their modules by the - library name and to ease porting of existing projects to Jbuilder + library name and to ease porting of existing projects to dune - ``(preprocess )`` specifies how to preprocess files if needed. The default is ``no_processing``. Other options are described in the @@ -139,7 +137,7 @@ modules you want. feature only if another package is installed. This is for instance the case of ``ctypes`` which will only install ``ctypes.foreign`` if the dummy ``ctypes-foreign`` package is installed. You can specify such virtual - dependencies here. You don't need to do so unless you use Jbuilder to + 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` @@ -164,7 +162,7 @@ modules you want. ``-lbar`` here, or whatever flags are necessary to to link against this library -- ``(self_build_stubs_archive )`` indicates to Jbuilder that the +- ``(self_build_stubs_archive )`` indicates to dune that the library has stubs, but that the stubs are built manually. The aim of the field is to embed a library written in foreign language and/or building with another build system. It is not for casual uses, see the `re2 library @@ -175,8 +173,8 @@ modules you want. ``.re`` file. Such modules are usually referred as *mli only modules*. They are not officially supported by the OCaml compiler, however they are commonly used. Such modules must only define - types. Since it is not reasonably possible for Jbuilder to check - that this is the case, Jbuilder requires the user to explicitly list + types. Since it is not reasonably possible for dune to check + that this is the case, dune requires the user to explicitly list such modules to avoid surprises. ```` must be a subset of the modules listed in the ``(modules ...)`` field. @@ -186,7 +184,7 @@ modules you want. - ``(no_keep_locs)`` undocumented, it is a necessary hack until this is implemented: https://github.com/ocaml/dune/issues/921 -Note that when binding C libraries, Jbuilder doesn't provide special support for +Note that when binding C libraries, dune doesn't provide special support for tools such as ``pkg-config``, however it integrates easily with configurator_ by using ``(c_flags (:include ...))`` and ``(c_library_flags (:include ...))``. @@ -208,7 +206,7 @@ format of executable stanzas is as follows: ```` is a module name that contains the main entry point of the executable. There can be additional modules in the current directory, you only need to specify the entry point. Given an ``executable`` stanza with ``(name -)``, Jbuilder will know how to build ``.exe``, ``.bc`` and +)``, dune will know how to build ``.exe``, ``.bc`` and ``.bc.js``. ``.exe`` is a native code executable, ``.bc`` is a bytecode executable which requires ``ocamlrun`` to run and ``.bc.js`` is a JavaScript generated using js_of_ocaml. @@ -222,7 +220,7 @@ usually preferable to use ``.exe`` in custom rules or when calling the executable by hand. This is because running a byte-code executable often requires loading shared libraries that are locally built, and so requires additional setup such as setting specific -environment variables and jbuilder doesn't do at the moment. +environment variables and dune doesn't do at the moment. Native compilation is considered not available when there is no ``ocamlopt`` binary at the same place as where ``ocamlc`` was found. @@ -256,7 +254,7 @@ Executables can also be linked as object or shared object files. See specification`_ section for more details. - ``(modules )`` specifies which modules in the current directory - Jbuilder should consider when building this executable. Modules not listed + dune should consider when building this executable. Modules not listed here will be ignored and cannot be used inside the executable described by the current stanza. It is interpreted in the same way as the ``(modules ...)`` field of `library`_ @@ -376,7 +374,7 @@ It shares the same fields as the ``executable`` stanza, except that instead of rule ---- -The ``rule`` stanza is used to create custom user rules. It tells Jbuilder how +The ``rule`` stanza is used to create custom user rules. It tells dune how to generate a specific set of files from a specific set of dependencies. The syntax is as follows: @@ -388,7 +386,7 @@ The syntax is as follows: (action ) )) -```` is a list of file names. Note that currently Jbuilder only +```` is a list of file names. Note that currently dune only support user rules with targets in the current directory. ```` is the action to run to produce the targets from the dependencies. @@ -415,7 +413,7 @@ modes ~~~~~ By default, the target of a rule must not exist in the source tree and -Jbuilder will error out when this is the case. +dune will error out when this is the case. However, it is possible to change this behavior using the ``mode`` field. The following modes are available: @@ -423,7 +421,7 @@ field. The following modes are available: - ``standard``, this is the standard mode - ``fallback``, in this mode, when the targets are already present in - the source tree, jbuilder will ignore the rule. It is an error if + the source tree, dune will ignore the rule. It is an error if only a subset of the targets are present in the tree. The common use of fallback rules is to generate default configuration files that may be generated by a configure script. @@ -433,7 +431,7 @@ field. The following modes are available: back to the source tree - ``promote-until-clean`` is the same as ``promote`` except than - ``jbuilder clean`` will remove the promoted files from the source + ``dune clean`` will remove the promoted files from the source tree @@ -441,7 +439,7 @@ There are two use cases for promote rules. The first one is when the generated code is easier to review than the generator, so it's easier to commit the generated code and review it. The second is to cut down dependencies during releases: by passing ``--ignore-promoted-rules`` -to jbuilder, rules will ``(mode promote)`` will be ignored and the +to dune, rules will ``(mode promote)`` will be ignored and the source files will be used instead. The ``-p/--for-release-of-packages`` flag implies ``--ignore-promote-rules``. @@ -463,7 +461,7 @@ For instance: 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 -following shorter syntax, where Jbuilder infers dependencies and +following shorter syntax, where dune infers dependencies and targets for you: .. code:: scheme @@ -476,10 +474,10 @@ For instance: (rule (copy a b)) -Note that in Jbuilder, targets must always be known -statically. Especially, this mean that Jbuilder must be able to +Note that in dune, targets must always be known +statically. Especially, this mean that dune must be able to statically determine all targets. For instance, this ``(rule ...)`` -stanza is rejected by Jbuilder: +stanza is rejected by dune: .. code:: scheme @@ -584,8 +582,8 @@ tests. install ------- -The ``install`` stanza is what lets you describe what Jbuilder should install, -either when running ``jbuilder install`` or through opam. +The ``install`` stanza is what lets you describe what dune should install, +either when running ``dune install`` or through opam. Libraries and executables don't need an ``install`` stanza to be installed, just a ``public_name`` field. Everything else needs an @@ -645,12 +643,12 @@ Handling of the .exe extension on Windows ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Under Microsoft Windows, executables must be suffixed with -``.exe``. Jbuilder tries to make sure that executables are always +``.exe``. Dune tries to make sure that executables are always installed with this extension on Windows. More precisely, when installing a file via an ``(install ...)`` stanza, if the source file has extension ``.exe`` or ``.bc``, then -Jbuilder implicitly adds the ``.exe`` extension to the destination, if +dune implicitly adds the ``.exe`` extension to the destination, if not already present. copy_files @@ -694,12 +692,12 @@ For instance: ((name runtest) (action (diff jbuild.inc jbuild.inc.gen)))) -With this jbuild file, running jbuilder as follow will replace the +With this jbuild file, running dune as follow will replace the ``jbuild.inc`` file in the source tree by the generated one: .. code:: shell - $ jbuilder build @runtest --auto-promote + $ dune build @runtest --auto-promote .. _jbuild-env: @@ -752,7 +750,7 @@ Ordered set language A few fields takes as argument an ordered set and can be specified using a small DSL. -This DSL is interpreted by jbuilder into an ordered set of strings using the +This DSL is interpreted by dune into an ordered set of strings using the following rules: - ``:standard`` denotes the standard value of the field when it is absent @@ -786,9 +784,9 @@ Variables expansion ------------------- Some fields can contains variables of the form ``$(var)`` or ``${var}`` that are -expanded by Jbuilder. +expanded by dune. -Jbuilder supports the following variables: +Dune supports the following variables: - ``ROOT`` is the relative path to the root of the build context. Note that ``ROOT`` depends on the worksace @@ -816,12 +814,12 @@ Jbuilder supports the following variables: - ``ext_obj``, ``ext_asm``, ``ext_lib``, ``ext_dll`` and ``ext_exe`` are the file extension used for various artifacts - ``ocaml-config:v`` for every variable ``v`` in the output of - ``ocamlc -config``. Note that output Jbuilder processes the output + ``ocamlc -config``. Note that dune processes the output of ``ocamlc -config`` in order to make it a bit more stable across versions, so the exact set of variables accessible this way might not be exactly the same as what you can see in the output of ``ocamlc -config``. In particular, variables added in new versions - of OCaml needs to be registered in Jbuilder before they can be used + of OCaml needs to be registered in dune before they can be used - ``profile`` the profile selected via ``--profile`` In addition, ``(action ...)`` fields support the following special variables: @@ -961,7 +959,7 @@ It is sometimes the case that one wants to not depend on a specific library, but instead on whatever is already installed. For instance to use a different backend depending on the target. -Jbuilder allows this by using a ``(select ... from ...)`` form inside the list +Dune allows this by using a ``(select ... from ...)`` form inside the list of library dependencies. Select forms are specified as follows: @@ -980,7 +978,7 @@ Select forms are specified as follows: - ``!``, which will evaluate to true if ```` is not available in the workspace or in the installed world -When evaluating a select form, Jbuilder will create ```` by +When evaluating a select form, dune will create ```` by copying the file given by the first ``( -> )`` case where all the literals evaluate to true. It is an error if none of the clauses are selectable. You can add a fallback by adding a clause of the form ``(-> @@ -989,7 +987,7 @@ selectable. You can add a fallback by adding a clause of the form ``(-> Preprocessing specification --------------------------- -Jbuilder accepts three kinds of preprocessing: +Dune accepts three kinds of preprocessing: - ``no_preprocessing``, meaning that files are given as it to the compiler, this is the default @@ -997,7 +995,7 @@ Jbuilder accepts three kinds of preprocessing: - ``(pps )`` to preprocess files using the given list of ppx rewriters -Note that in any cases, files are preprocessed only once. Jbuilder doesn't use +Note that in any cases, files are preprocessed only once. Dune doesn't use the ``-pp`` or ``-ppx`` of the various OCaml tools. Preprocessing with actions @@ -1042,9 +1040,9 @@ Libraries listed here should be libraries implementing an OCaml AST rewriter and registering themselves using the `ocaml-migrate-parsetree.driver API `__. -Jbuilder will build a single executable by linking all these libraries and their +Dune will build a single executable by linking all these libraries and their dependencies. Note that it is important that all these libraries are linked with -``-linkall``. Jbuilder automatically uses ``-linkall`` when the ``(kind ...)`` +``-linkall``. Dune automatically uses ``-linkall`` when the ``(kind ...)`` field is set to ``ppx_rewriter`` or ``ppx_deriver``. Per module preprocessing specification @@ -1097,7 +1095,7 @@ syntax: ```` - ``(universe)``: depend on everything in the universe. This is for - cases where dependencies are too hard to specify. Note that Jbuilder + cases where dependencies are too hard to specify. Note that dune will not be able to cache the result of actions that depend on the universe. In any case, this is only for dependencies in the installed world, you must still specify all dependencies that come @@ -1117,7 +1115,7 @@ You can use globs to declare dependencies on a set of files. Note that globs will match files that exist in the source tree as well as buildable targets, so for instance you can depend on ``*.cmi``. -Currently jbuilder only support globbing files in a single directory. And in +Currently dune only support globbing files in a single directory. And in particular the glob is interpreted as follows: - anything before the last ``/`` is taken as a literal path @@ -1194,10 +1192,10 @@ 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``. The argument of ``(action ...)`` fields is a small DSL that is interpreted by -jbuilder directly and doesn't require an external shell. All atoms in the DSL +dune directly and doesn't require an external shell. All atoms in the DSL support `Variables expansion`_. Moreover, you don't need to specify dependencies explicitly for the special ``${:...}`` forms, these are recognized and -automatically handled by Jbuilder. +automatically handled by dune. The DSL is currently quite limited, so if you want to do something complicated it is recommended to write a small OCaml program and use the DSL to invoke it. @@ -1249,7 +1247,7 @@ in order to report errors in the original file rather than the copy. This is important as the copy exists only under the ``_build`` directory and in order for editors to jump to errors when parsing the output of the build system, errors must point to files that exist in -the source tree. In the beta versions of jbuilder, ``copy#`` was +the source tree. In the beta versions of dune, ``copy#`` was called ``copy-and-add-line-directive``. However, most of time one wants this behavior rather than a bare copy, so it was renamed to something shorter. @@ -1304,7 +1302,7 @@ of your project. What you should write instead is: Locks ----- -Given two rules that are independent, Jbuilder will assume that there +Given two rules that are independent, dune will assume that there associated action can be run concurrently. Two rules are considered independent if none of them depend on the other, either directly or through a chain of dependencies. This basic assumption allows to @@ -1312,7 +1310,7 @@ parallelize the build. However, it is sometimes the case that two independent rules cannot be executed concurrently. For instance this can happen for more -complicated tests. In order to prevent jbuilder from running the +complicated tests. In order to prevent dune from running the actions at the same time, you can specify that both actions take the same lock: @@ -1330,7 +1328,7 @@ same lock: (locks (m)) (action (run test.exe ${<})))) -Jbuilder will make sure that the executions of ``test.exe foo`` and +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 @@ -1378,7 +1376,7 @@ However, it is different for the following reason: - on Windows, both ``(diff a b)`` and ``(diff? a b)`` normalize the end of lines before comparing the files -- since ``(diff a b)`` is a builtin action, Jbuilder knowns that ``a`` +- since ``(diff a b)`` is a builtin action, dune knowns that ``a`` and ``b`` are needed and so you don't need to specify them explicitly as dependencies @@ -1396,7 +1394,7 @@ Promotion ~~~~~~~~~ Whenever an action ``(diff )`` or ``(diff? -)`` fails because the two files are different, jbuilder allows +)`` fails because the two files are different, dune allows you to promote ```` as ```` if ```` is a source file and ```` is a generated file. @@ -1415,13 +1413,13 @@ Where ``data.expected`` is a file committed in the source repository. You can use the following workflow to update your test: - update the code of your test -- run ``jbuilder runtest``. The diff action will fail and a diff will +- run ``dune runtest``. The diff action will fail and a diff will be printed - check the diff to make sure it is what you expect -- run ``jbuilder promote``. This will copy the generated ``data.out`` +- run ``dune promote``. This will copy the generated ``data.out`` file to ``data.expected`` directly in the source tree -You can also use ``jbuilder runtest --auto-promote`` which will +You can also use ``dune runtest --auto-promote`` which will automatically do the promotion. OCaml syntax diff --git a/doc/faq.rst b/doc/faq.rst index 93f85c24..6134dabf 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -2,10 +2,10 @@ FAQ *** -Why do many Jbuilder projects contain a Makefile? -================================================= +Why do many dune projects contain a Makefile? +============================================= -Many Jbuilder project contain a toplevel `Makefile`. It is often only there for +Many dune projects contain a toplevel `Makefile`. It is often only there for convenience, for the following reasons: 1. there are many different build systems out there, all with a different CLI. @@ -15,10 +15,10 @@ convenience, for the following reasons: 2. you often have a few common operations that are not part of the build and `make ` is a good way to provide them -3. `make` is shorter to type than `jbuilder build @install` +3. `make` is shorter to type than `dune build @install` -How to add a configure step to a jbuilder project? -================================================== +How to add a configure step to a dune project? +============================================== The with-configure-step_ example shows one way to do it which preserves composability; i.e. it doesn't require manually running `./configure` @@ -26,18 +26,18 @@ script when working on multiple projects at the same time. .. _with-configure-step: https://github.com/ocaml/dune/tree/master/example/sample-projects/with-configure-step -Can I use topkg with jbuilder? -============================== +Can I use topkg with dune? +========================== Yes, have a look at the topkg-jbuilder_ project for more details. .. _topkg-jbuilder: https://github.com/samoht/topkg-jbuilder -here can I find some examples of projects using Jbuilder? -========================================================= +here can I find some examples of projects using dune? +===================================================== The dune-universe_ repository contains a snapshot of the latest versions of all -opam packages depending on jbuilder. It is therefore a useful reference to +opam packages depending on dune. It is therefore a useful reference to search through to find different approaches to constructing build rules. .. _dune-universe: https://github.com/dune-universe/dune-universe diff --git a/doc/index.rst b/doc/index.rst index ebf6add4..6ad15f4a 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -3,8 +3,8 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to jbuilder's documentation! -==================================== +Welcome to dune's documentation! +================================ .. toctree:: :maxdepth: 3 @@ -13,7 +13,7 @@ Welcome to jbuilder's documentation! overview terminology project-layout-specification - jbuild + dune-files tests documentation usage diff --git a/doc/known-issues.rst b/doc/known-issues.rst index d02a9655..bf0e9f9e 100644 --- a/doc/known-issues.rst +++ b/doc/known-issues.rst @@ -6,9 +6,9 @@ mli only modules ================ These are supported, however using them might cause make it impossible for -non-jbuilder users to use your library. We tried to use them for some internal -module generated by Jbuilder and it broke the build of projects not using -Jbuilder: +non-dune users to use your library. We tried to use them for some internal +module generated by dune and it broke the build of projects not using +dune: https://github.com/ocaml/dune/issues/567 diff --git a/doc/overview.rst b/doc/overview.rst index bf3a0a80..16f64f0e 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -2,7 +2,7 @@ Overview ******** -Jbuilder is a build system for OCaml and Reason. It is not intended as a +Dune is a build system for OCaml and Reason. It is not intended as a completely generic build system that is able to build any given project in any language. On the contrary, it makes lots of choices in order to encourage a consistent development style. @@ -12,36 +12,36 @@ to the opam world. It has matured over a long time and is used daily by hundred of developers, which means that it is highly tested and productive. -When using Jbuilder, you give very little and high-level information to +When using dune, you give very little and high-level information to the build system, which in turn takes care of all the low-level details, from the compilation of your libraries, executables and documentation, to the installation, setting up of tests, setting up of the development tools such as merlin, etc. In addition to the normal features one would expect from a build system -for OCaml, Jbuilder provides a few additional ones that detach it from +for OCaml, dune provides a few additional ones that detach it from the crowd: -- you never need to tell Jbuilder where things such as libraries are. - Jbuilder will always discover them automatically. In particular, this +- you never need to tell dune where things such as libraries are. + Dune will always discover them automatically. In particular, this means that when you want to re-organize your project you need to do no - more than rename your directories, Jbuilder will do the rest + more than rename your directories, dune will do the rest - things always work the same whether your dependencies are local or installed on the system. In particular, this means that you can always drop in the source for a dependency of your project in your working - copy and Jbuilder will start using it immediately. This makes Jbuilder a + copy and dune will start using it immediately. This makes dune a great choice for multi-project development -- cross-platform: as long as your code is portable, Jbuilder will be - able to cross-compile it (note that Jbuilder is designed internally +- cross-platform: as long as your code is portable, dune will be + able to cross-compile it (note that dune is designed internally to make this easy but the actual support is not implemented yet) -- release directly from any revision: Jbuilder needs no setup stage. To +- release directly from any revision: dune needs no setup stage. To release your project, you can simply point to a specific tag. You can of course add some release steps if you want to, but it is not necessary The first section of this document defines some terms used in the rest -of this manual. The second section specifies the Jbuilder metadata -format and the third one describes how to use the ``jbuilder`` command. +of this manual. The second section specifies the dune metadata +format and the third one describes how to use the ``dune`` command. diff --git a/doc/project-layout-specification.rst b/doc/project-layout-specification.rst index 9a0a72c9..7f1cc73f 100644 --- a/doc/project-layout-specification.rst +++ b/doc/project-layout-specification.rst @@ -2,7 +2,7 @@ Project Layout and Metadata Specification ***************************************** -A typical jbuilder project will have a ```dune-project`` and one or +A typical dune project will have a ```dune-project`` and one or more ``.opam`` file at toplevel as well as ``jbuild`` files wherever interesting things are: libraries, executables, tests, documents to install, etc... @@ -14,9 +14,9 @@ like to have multiple executables with different configurations in the same directory, you will have to make an explicit module list for every executable using ``modules``. -The next sections describe the format of Jbuilder metadata files. +The next sections describe the format of dune metadata files. -Note that the Jbuilder metadata format is versioned in order to ensure +Note that the dune metadata format is versioned in order to ensure forward compatibility. There is currently only one version available, but to be future proof, you should still specify it in your ``jbuild`` files. If no version is specified, the latest one will be used. @@ -205,17 +205,17 @@ Sets the version of the project: .opam files ==================== -When a ``.opam`` file is present, Jbuilder will know that the +When a ``.opam`` file is present, dune will know that the package named ```` exists. It will know how to construct a ``.install`` file in the same directory to handle installation -via `opam `__. Jbuilder also defines the +via `opam `__. Dune also defines the recursive ``install`` alias, which depends on all the buildable ``.install`` files in the workspace. So for instance to build everything that is installable in a workspace, run at the root: :: - $ jbuilder build @install + $ dune build @install Declaring a package this way will allow you to add elements such as libraries, executables, documentation, ... to your package by declaring @@ -245,18 +245,18 @@ this scope only. Because scopes are exclusive, if you wish to include the dependencies of the project you are currently working on into your workspace, you may copy them in a ``vendor`` directory, or any other name of your -choice. Jbuilder will look for them there rather than in the installed +choice. Dune will look for them there rather than in the installed world and there will be no overlap between the various scopes. Package version --------------- -Note that Jbuilder will try to determine the version number of packages -defined in the workspace. While Jbuilder itself makes no use of version +Note that dune will try to determine the version number of packages +defined in the workspace. While dune itself makes no use of version numbers, it can be use by external tools such as `ocamlfind `__. -Jbuilder determines the version of a package by trying the following +Dune determines the version of a package by trying the following methods in order: - it looks in the ``.opam`` file for a ``version`` variable @@ -269,12 +269,12 @@ methods in order: ``.version``, ``version`` and ``VERSION`` files may be generated. -If the version can't be determined, Jbuilder just won't assign one. +If the version can't be determined, dune just won't assign one. Odig conventions ---------------- -Jbuilder follows the `odig `__ +Dune follows the `odig `__ conventions and automatically installs any README\*, CHANGE\*, HISTORY\* and LICENSE\* files in the same directory as the ``.opam`` file to a location where odig will find them. diff --git a/doc/quick-start.rst b/doc/quick-start.rst index 071ead03..fa53ba14 100644 --- a/doc/quick-start.rst +++ b/doc/quick-start.rst @@ -2,9 +2,9 @@ Quickstart ********** -This document gives simple usage examples of Jbuilder. You can also look at +This document gives simple usage examples of dune. You can also look at `examples `__ for -complete examples of projects using Jbuilder. +complete examples of projects using dune. Building a hello world program ============================== @@ -29,7 +29,7 @@ And build it with: .. code:: bash - jbuilder build hello_world.exe + dune build hello_world.exe The executable will be built as ``_build/default/hello_world.exe``. Note that native code executables will have the ``.exe`` extension on all platforms @@ -58,7 +58,7 @@ And build it with: .. code:: bash - jbuilder build hello_world.exe + dune build hello_world.exe The executable will be built as ``_build/default/hello_world.exe`` @@ -91,7 +91,7 @@ And build it with: .. code:: bash - jbuilder build hello_world.exe + dune build hello_world.exe The executable will be built as ``_build/default/hello_world.exe`` @@ -278,7 +278,7 @@ And run the tests with: .. code:: bash - jbuilder runtest + dune runtest Building a custom toplevel ========================== diff --git a/doc/terminology.rst b/doc/terminology.rst index aed21bd3..0022c50b 100644 --- a/doc/terminology.rst +++ b/doc/terminology.rst @@ -8,17 +8,17 @@ Terminology - **project**: a project is a source tree, maybe containing one or more packages -- **root**: the root is the directory from where Jbuilder can build - things. Jbuilder knows how to build targets that are descendents of +- **root**: the root is the directory from where dune can build + things. Dune knows how to build targets that are descendents of the root. Anything outside of the tree starting from the root is considered part of the **installed world**. How the root is determined is explained in :ref:`finding-root`. - **workspace**: the workspace is the subtree starting from the root. It can contain any number of projects that will be built - simultaneously by jbuilder + simultaneously by dune -- **installed world**: anything outside of the workspace, that Jbuilder +- **installed world**: anything outside of the workspace, that dune takes for granted and doesn't know how to build - **installation**: this is the action of copying build artifacts or @@ -27,7 +27,7 @@ Terminology - **scope**: a scope determines where private items are visible. Private items include libraries or binaries that will not - be installed. In Jbuilder, scopes are sub-trees rooted where at + be installed. In dune, scopes are sub-trees rooted where at least one ``.opam`` file is present. Moreover, scopes are exclusive. Typically, every project defines a single scope. See :ref:`scopes` for more details @@ -36,7 +36,7 @@ Terminology ``/_build`` directory. It contains all the build artifacts of the workspace built against a specific configuration. Without 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 dune is executed. Build contexts can be specified by writing a :ref:`dune-workspace` file @@ -47,7 +47,7 @@ Terminology and has configurable dependencies. Aliases are per-directory. However, on the command line, asking for an alias to be built in a given directory will trigger the construction of the - alias in all children directories recursively. Jbuilder defines the + alias in all children directories recursively. Dune defines the following standard aliases: - ``default`` which is the alias build by default when no targets @@ -58,7 +58,7 @@ Terminology - ``doc`` which depends on the generated HTML documentation. See :ref:`documentation` for details. -- **environment**: in Jbuilder, each directory has an environment +- **environment**: in dune, each directory has an environment attached to it. The environment determines the default values of various parameters, such as the compilation flags. Inside a scope, each directory inherit the environment from its parent. At the root diff --git a/doc/tests.rst b/doc/tests.rst index bb7df7ab..77d37f90 100644 --- a/doc/tests.rst +++ b/doc/tests.rst @@ -2,13 +2,13 @@ Writing and running tests ************************* -Jbuilder tries to streamline the testing story as much as possible, so +Dune tries to streamline the testing story as much as possible, so that you can focus on the tests themselves and not bother with setting up with various test frameworks. In this section, we will explain the workflow to deal with tests in -Jbuilder. In particular we will see how to run the testsuite of a -project, how to describe your tests to Jbuilder and how to promote +dune. In particular we will see how to run the testsuite of a +project, how to describe your tests to dune and how to promote tests result as expectation. We distinguish two kinds of tests: inline tests and custom @@ -22,22 +22,22 @@ Running tests ============= Whatever the tests of a project are, the usual way to run tests with -Jbuilder is to call ``jbuilder runtest`` from the shell. This will run +dune is to call ``dune runtest`` from the shell. This will run all the tests defined in the current directory and any sub-directory recursively. You can also pass a directory argument to run the tests -from a sub-tree. For instance ``jbuilder runtest test`` will only run +from a sub-tree. For instance ``dune runtest test`` will only run the tests from the ``test`` directory and any sub-directory of ``test`` recursively. -Note that in any case, ``jbuilder runtest`` is simply a short-hand for -building the ``runtest`` alias, so you can always ask Jbuilder to run +Note that in any case, ``dune runtest`` is simply a short-hand for +building the ``runtest`` alias, so you can always ask dune to run the tests in conjunction with other targets by passing ``@runtest`` to -``jbuilder build``. For instance: +``dune build``. For instance: .. code:: bash - $ jbuilder build @install @runtest - $ jbuilder build @install @test/runtest + $ dune build @install @runtest + $ dune build @install @test/runtest Inline tests ============ @@ -45,7 +45,7 @@ Inline tests There are several inline tests framework available for OCaml, such as ppx_inline_test_ and qtest_. We will use ppx_inline_test_ as an example as at the time of writing this document it has the necessary -setup to be used with Jbuilder out of the box. +setup to be used with dune out of the box. ppx_inline_test_ allows to write tests directly inside ml files as follow: @@ -65,7 +65,7 @@ so for instance the ``jbuild`` file might look like this: ((name foo) (preprocess (pps (ppx_inline_test))))) -In order to instruct Jbuilder that our library contains inline tests, +In order to instruct dune that our library contains inline tests, all we have to do is add an ``inline_tests`` field: .. code:: scheme @@ -75,13 +75,12 @@ all we have to do is add an ``inline_tests`` field: (inline_tests) (preprocess (pps (ppx_inline_test))))) -We can now build and execute this test by running ``jbuilder -runtest``. For instance, if we make the test fail by replacing ``120`` -by ``0`` we get: +We can now build and execute this test by running ``dune runtest``. For +instance, if we make the test fail by replacing ``120`` by ``0`` we get: .. code:: bash - $ jbuilder runtest + $ dune runtest [...] File "src/fact.ml", line 3, characters 0-25: <<(fact 5) = 0>> is false. @@ -91,7 +90,7 @@ Note that in this case Jbuild knew how to build and run the tests without any special configuration. This is because ppx_inline_test defines an inline tests backend and it is used by the library. Some other frameworks, such as qtest_ don't have any special library or ppx -rewriter. To use such a framework, you must tell Jbuilder about it +rewriter. To use such a framework, you must tell dune about it since it cannot guess it. You can do that by adding a ``backend`` field: @@ -129,15 +128,15 @@ following test elements are clearly identified: You can have a look at `this blog post `_ to find out -more about expectation tests. But Back to Jbuilder, the workflow for -expectation tests is always as follow: +more about expectation tests. To dune, the workflow for +expectation tests is always as follows: - write the test with some empty expect nodes in it - run the tests - check the suggested correction and promote it as the original source file if you are happy with it -Jbuilder makes this workflow very easy, simply add ``ppx_expect`` to +Dune makes this workflow very easy, simply add ``ppx_expect`` to your list of ppx rewriters as follow: .. code:: scheme @@ -147,13 +146,13 @@ your list of ppx rewriters as follow: (inline_tests) (preprocess (pps (ppx_expect))))) -Then calling ``jbuilder runtest`` will run these tests and in case of -mismatch Jbuilder will print a diff of the original source file and +Then calling ``dune runtest`` will run these tests and in case of +mismatch dune will print a diff of the original source file and the suggested correction. For instance: .. code:: bash - $ jbuilder runtest + $ dune runtest [...] -src/fact.ml +src/fact.ml.corrected @@ -169,14 +168,14 @@ In order to accept the correction, simply run: .. code:: bash - $ jbuilder promote + $ dune promote -You can also make Jbuilder automatically accept the correction after +You can also make dune automatically accept the correction after running the tests by typing: .. code:: bash - $ jbuilder runtest --auto-promote + $ dune runtest --auto-promote Finally, some editor integration is possible to make the editor do the promotion and make the workflow even smoother. @@ -184,7 +183,7 @@ promotion and make the workflow even smoother. Specifying inline test dependencies ----------------------------------- -If your tests are reading files, you must say it to Jbuilder by adding +If your tests are reading files, you must say it to dune by adding a ``deps`` field the the ``inline_tests`` field. The argument of this ``deps`` field follows the usual :ref:`deps-field`. For instance: @@ -198,7 +197,7 @@ a ``deps`` field the the ``inline_tests`` field. The argument of this Passing special arguments to the test runner -------------------------------------------- -Under the hood, a test executable is built by Jbuilder. Depending on +Under the hood, a test executable is built by dune. Depending on the backend used this runner might take useful command line arguments. You can specify such flags by using a ``flags`` field, such as: @@ -319,7 +318,7 @@ build as this would cause portability problems. Custom tests ============ -We said in `Running tests`_ that to run tests Jbuilder simply builds +We said in `Running tests`_ that to run tests dune simply builds the ``runtest`` alias. As a result, to define cutsom tests, you simply need to add an action to this alias in any directory. For instance if you have a binary ``tests.exe`` that you want to run as part of @@ -335,9 +334,9 @@ Diffing the result ------------------ It is often the case that we want to compare the output of a test to -some expected one. For that, Jbuilder offers the ``diff`` command, +some expected one. For that, dune offers the ``diff`` command, which in essence is the same as running the ``diff`` tool, except that -it is more integrated in Jbuilder and especially with the ``promote`` +it is more integrated in dune and especially with the ``promote`` command. For instance let's consider this test: .. code:: scheme @@ -350,29 +349,29 @@ command. For instance let's consider this test: (action (diff tests.expected test.output)))) After having run ``tests.exe`` and dumping its output to -``tests.output``, Jbuilder will compare the latter to -``tests.expected``. In case of mismatch, Jbuilder will print a diff -and then the ``jbuilder promote`` command can be used to copy over the +``tests.output``, dune will compare the latter to +``tests.expected``. In case of mismatch, dune will print a diff +and then the ``dune promote`` command can be used to copy over the generated ``test.output`` file to ``tests.expected`` in the source tree. This provides a nice way of dealing with the usual *write code*, *run*, *promote* cycle of testing. For instance: .. code:: bash - $ jbuilder runtest + $ dune runtest [...] -tests.expected +tests.output File "tests.expected", line 1, characters 0-1: -Hello, world! +Good bye! - $ jbuilder promote + $ dune promote Promoting _build/default/tests.output to tests.expected. Note that if available, the diffing is done using the patdiff_ tool, which displays nicer looking diffs that the standard ``diff`` tool. You can change that by passing ``--diff-command CMD`` to -Jbuilder. +dune. .. _ppx_inline_test: https://github.com/janestreet/ppx_inline_test diff --git a/doc/usage.rst b/doc/usage.rst index b3ceea8b..2f73bb12 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -2,7 +2,7 @@ Usage ***** -This section describe usage of Jbuilder from the shell. +This section describe usage of dune from the shell. .. _finding-root: @@ -40,7 +40,7 @@ order: - ``/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 +practice this means that if you nest your workspaces, dune will always use the outermost one. In addition to determining the root, ``dune`` will read this file as @@ -58,7 +58,7 @@ as root. Forcing the root (for scripts) ------------------------------ -You can pass the ``--root`` option to ``jbuilder`` to select the root +You can pass the ``--root`` option to ``dune`` to select the root explicitly. This option is intended for scripts to disable the automatic lookup. Note that when using the ``--root`` option, targets given on the command line @@ -75,7 +75,7 @@ the command line. When no targets are specified, ``dune`` builds the Resolution ---------- -All targets that Jbuilder knows how to build live in the ``_build`` +All targets that dune knows how to build live in the ``_build`` directory. Although, some are sometimes copied to the source tree for the need of external tools. These includes: @@ -83,22 +83,22 @@ the need of external tools. These includes: - ``.install`` files -As a result, if you want to ask ``jbuilder`` to produce a particular ``.exe`` +As a result, if you want to ask ``dune`` to produce a particular ``.exe`` file you would have to type: .. code:: bash - $ jbuilder build _build/default/bin/prog.exe + $ dune build _build/default/bin/prog.exe However, for convenience when a target on the command line doesn't -start with ``_build``, ``jbuilder`` will expand it to the +start with ``_build``, ``dune`` will expand it to the corresponding target in all the build contexts where it knows how to build it. When using ``--verbose``, It prints out the actual set of targets when starting: .. code:: bash - $ jbuilder build bin/prog.exe --verbose + $ dune build bin/prog.exe --verbose ... Actual targets: - _build/default/bin/prog.exe @@ -118,9 +118,9 @@ To build and run the tests for a particular build context, use So for instance: -- ``jbuilder build @_build/foo/runtest`` will run the tests only for +- ``dune build @_build/foo/runtest`` will run the tests only for the ``foo`` build context -- ``jbuilder build @runtest`` will run the tests for all build contexts +- ``dune build @runtest`` will run the tests for all build contexts You can also build an alias non-recursively by using ``@@`` instead of ``@``. For instance to run tests only from the current directory: @@ -157,7 +157,7 @@ is installable. Finding external libraries ========================== -When a library is not available in the workspace, jbuilder will look it +When a library is not available in the workspace, dune will look it up in the installed world, and expect it to be already compiled. It looks up external libraries using a specific list of search pathes. A @@ -179,29 +179,29 @@ Running tests There are two ways to run tests: -- ``jbuilder build @runtest`` -- ``jbuilder runtest`` +- ``dune build @runtest`` +- ``dune runtest`` The two commands are equivalent. They will run all the tests defined in the current directory and its children recursively. You can also run the tests in a specific sub-directory and its children by using: -- ``jbuilder build @foo/bar/runtest`` -- ``jbuilder runtest foo/bar`` +- ``dune build @foo/bar/runtest`` +- ``dune runtest foo/bar`` Launching the Toplevel (REPL) ============================= -jbuilder supports launching a `utop `__ instance +Dune supports launching a `utop `__ instance with locally defined libraries loaded. .. code:: bash - $ jbuilder utop -- + $ dune utop -- Where ```` is a directory containing a ``jbuild`` file defining all the libraries that will be loaded (using the ``library`` stanza). ```` will be -passed as arguments to the utop command itself. For example, ``jbuilder utop lib +passed as arguments to the utop command itself. For example, ``dune utop lib -- -implicit-bindings`` will start ``utop`` with the libraries defined in ``lib`` and implicit bindings for toplevel expressions. @@ -218,16 +218,16 @@ Requirements & Limitations Restricting the set of packages =============================== -You can restrict the set of packages from your workspace that Jbuilder +You can restrict the set of packages from your workspace that dune can see with the ``--only-packages`` option: .. code:: bash - $ jbuilder build --only-packages pkg1,pkg2,... @install + $ dune build --only-packages pkg1,pkg2,... @install This option acts as if you went through all the jbuild files and commented out the stanzas refering to a package that is not in the list -given to ``jbuilder``. +given to ``dune``. Invocation from opam ==================== @@ -245,9 +245,9 @@ release --default-target @install``. ``-p`` is the short version of This has the following effects: -- it tells jbuilder to build everything that is installable and to +- it tells dune to build everything that is installable and to ignore packages other than ``name`` defined in your project -- it sets the root to prevent jbuilder from looking it up +- it sets the root to prevent dune from looking it up - it sets the build profile to ``release`` - it uses whatever concurrency option opam provides - it sets the default target to ``@install`` rather than ``@@default`` @@ -273,25 +273,25 @@ Installing a package means copying the build artifacts from the build directory to the installed word. When installing via opam, you don't need to worry about this step: -jbuilder generates a ``.install`` file that opam will +dune generates a ``.install`` file that opam will automatically read to handle installation. However, when not using opam or doing local development, you can use -jbuilder to install the artifacts by hands. To do that, use the +dune to install the artifacts by hands. To do that, use the ``install`` command: :: - $ jbuilder install [PACKAGE]... + $ dune install [PACKAGE]... without an argument, it will install all the packages available in the workspace. With a specific list of packages, it will only install these packages. If several build contexts are configured, the installation will be performed for all of them. -Note that ``jbuilder install`` is a thin wrapper around the +Note that ``dune install`` is a thin wrapper around the ``opam-installer`` tool, so you will need to install this tool in order -to be able to use ``jbuilder install``. +to be able to use ``dune install``. Destination ----------- @@ -319,9 +319,9 @@ are using this mechanism to setup where OCaml library files should be copied. As a result, if none of ``--libdir`` and ``--prefix`` is passed to -``jbuilder install`` and ``ocamlfind`` is present in the ``PATH``, +``dune install`` and ``ocamlfind`` is present in the ``PATH``, then library files will be copied to the directory reported by -``ocamlfind printconf destdir``. This ensures that ``jbuilder +``ocamlfind printconf destdir``. This ensures that ``dune install`` can be used without opam. When using opam, ``ocamlfind`` is configured to point to the opam directory, so this rule makes no difference. @@ -403,10 +403,10 @@ context or can be the description of an opam switch, as follows: where the artifacts for this build context will be stored - ``(root )`` is the opam root. By default it will take - the opam root defined by the environment in which ``jbuilder`` is + the opam root defined by the environment in which ``dune`` is run which is usually ``~/.opam`` -- ``(merlin)`` instructs Jbuilder to use this build context for +- ``(merlin)`` instructs dune to use this build context for merlin - ``(profile )`` to set a different profile for a build @@ -423,14 +423,14 @@ the artifacts from the ``default`` context, and if you have the ``(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 +For rare cases where this is not what you want, you can force dune to use a different build contexts for merlin by adding the field ``(merlin)`` to this context. Building JavaScript with js_of_ocaml ==================================== -Jbuilder knows how to generate a JavaScript version of an executable +Dune knows how to generate a JavaScript version of an executable (``.bc.js``) using the js_of_ocaml compiler (the ``js_of_ocaml-compiler`` opam package must be installed). @@ -452,16 +452,16 @@ js_of_ocaml compiler .. _using-topkg: -Using topkg with jbuilder -========================= +Using topkg with dune +===================== -Jbuilder provides suport for building and installing your project. +Dune provides support for building and installing your project. However it doesn't provides helpers for distributing it. It is recommemded to use `Topkg `__ for this purpose. The `topkg-jbuilder `__ -project provides helpers for using Topkg in a Jbuilder project. In +project provides helpers for using Topkg in a dune project. In particular, as long as your project uses the common defaults, just write this ``pkg/pkg.ml`` file and you are all set: @@ -471,7 +471,7 @@ write this ``pkg/pkg.ml`` file and you are all set: #require "topkg-jbuilder.auto" It is planned that this file won't be necessary at all soon and topkg -will work out of the box on jbuilder projects. +will work out of the box on dune projects. The common defaults are that your projects include the following files: @@ -500,16 +500,16 @@ you are using git, topkg invokes this command to find out the version: $ git describe --always --dirty 1.0+beta9-79-g29e9b37 -Projects using jbuilder usually only need topkg for creating and +Projects using dune usually only need topkg for creating and publishing releases. However they might still want to substitute the watermarks when the package is pinned by the user. To help with this, -jbuilder provides the ``subst`` sub-command. +dune provides the ``subst`` sub-command. -jbuilder subst -============== +dune subst +========== -``jbuilder subst`` performs the same substitution ``topkg`` does with -the default configuration. i.e. calling ``jbuilder subst`` at the root +``dune subst`` performs the same substitution ``topkg`` does with +the default configuration. i.e. calling ``dune subst`` at the root of your project will rewrite in place all the files in your project. More precisely, it replaces all the following watermarks in source @@ -536,11 +536,11 @@ you need to specify the name explicitly via the ``-n`` flag: .. code:: bash - $ jbuilder subst -n myproject + $ dune subst -n myproject -Finally, note that jbuilder doesn't allow you to customize the list of +Finally, note that dune doesn't allow you to customize the list of substituted watermarks. If you which to do so, you need to configure -topkg and use it instead of ``jbuilder subst``. +topkg and use it instead of ``dune subst``. Custom Build Directory ======================