diff --git a/doc/advanced-topics.rst b/doc/advanced-topics.rst index 30a595fd..3099c5ad 100644 --- a/doc/advanced-topics.rst +++ b/doc/advanced-topics.rst @@ -134,12 +134,12 @@ be executed will come from the ``default`` context. One consequence of this is that all preprocessing (ppx or otherwise) will be done using binaries built in the ``default`` context. -To clarify this with an example, let's assume that you have the -following ``src/jbuild`` file: +To clarify this with an example, let's assume that you have the following +``src/dune`` file: .. code:: scheme - (executable ((name foo))) + (executable (name foo)) (rule (with-stdout-to blah (run ./foo.exe))) When building ``_build/default/src/blah``, dune will resolve ``./foo.exe`` to @@ -157,7 +157,7 @@ instance if the ``foo.exe`` program in the previous example was using .. code:: scheme - (rule (with-stdout-to blah (run ./foo.exe -os-type ${os_type}))) + (rule (with-stdout-to blah (run ./foo.exe -os-type %{os_type}))) Classical ppx ============= diff --git a/doc/configurator.rst b/doc/configurator.rst index 77d57277..44a7bb5e 100644 --- a/doc/configurator.rst +++ b/doc/configurator.rst @@ -64,7 +64,7 @@ invoke it as an executable and tell dune about the targets that it produces: (executable ((name discover) - (libraries (jbuilder.configurator)))) + (libraries (dune.configurator)))) (rule ((targets (config.h)) @@ -103,7 +103,7 @@ The following steps must be taken to transition from the old configurator: * Mentions of the ``configurator`` opam package should be removed. -* The library name ``configurator`` should be changed ``jbuilder.configurator``. +* The library name ``configurator`` should be changed ``dune.configurator``. * The ``-ocamlc`` flag in rules that run configurator scripts should be removed. This information is now passed automatically by dune. diff --git a/doc/documentation.rst b/doc/documentation.rst index 35c40d95..0c99a957 100644 --- a/doc/documentation.rst +++ b/doc/documentation.rst @@ -79,10 +79,10 @@ Where ```` are: ``.mld`` files in the stanza's directory. 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``, dune will generate one with the entry -modules for your package. But this generated will not be installed. +specially by dune. 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``, 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 ``.install`` file for that package, and hence will be installed by opam. diff --git a/doc/faq.rst b/doc/faq.rst index 6134dabf..4e0b1e51 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -29,9 +29,16 @@ script when working on multiple projects at the same time. Can I use topkg with dune? ========================== -Yes, have a look at the topkg-jbuilder_ project for more details. +It's possible using the topkg-jbuilder_ but it's not recommended. dune-release_ +subsumes topkg-jbuilder and is specifically tailored to dune projects. -.. _topkg-jbuilder: https://github.com/samoht/topkg-jbuilder + +How do I publish my packages with dune? +======================================= + +Dune is just a build system and considers publishing outside of its scope. +However, the dune-release_ project is specifically designed for releasing dune +projects to opam. We recommend using tool for publishing dune packages. here can I find some examples of projects using dune? ===================================================== @@ -41,3 +48,5 @@ 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 +.. _topkg-jbuilder: https://github.com/samoht/topkg-jbuilder +.. _dune-release: https://github.com/samoht/dune-release diff --git a/doc/index.rst b/doc/index.rst index 6ad15f4a..4e512049 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,4 +1,4 @@ -.. jbuilder documentation master file, created by +.. dune documentation master file, created by sphinx-quickstart on Tue Apr 11 21:24:42 2017. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. diff --git a/doc/project-layout-specification.rst b/doc/project-layout-specification.rst index 4704ed6c..1d9ff956 100644 --- a/doc/project-layout-specification.rst +++ b/doc/project-layout-specification.rst @@ -2,24 +2,23 @@ Project Layout and Metadata Specification ***************************************** -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... +A typical dune project will have a ```dune-project`` and one or more +``.opam`` file at toplevel as well as ``dune`` files wherever +interesting things are: libraries, executables, tests, documents to install, +etc... -It is recommended to organize your project so that you have exactly one -library per directory. You can have several executables in the same -directory, as long as they share the same build configuration. If you'd -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``. +It is recommended to organize your project so that you have exactly one library +per directory. You can have several executables in the same directory, as long +as they share the same build configuration. If you'd 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 dune metadata files. -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. +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 ``dune`` files. If no version is +specified, the latest one will be used. .. _metadata-format: @@ -169,18 +168,18 @@ string. dune-project files ================== -These files are used to mark the root of projects as well as define -project-wide parameters. These files are required to have a ``lang`` -which controls the names and contents of all configuration files read -by Dune. The ``lang`` stanza looks like: +These files are used to mark the root of projects as well as define project-wide +parameters. These files are required to have a ``lang`` which controls the names +and contents of all configuration files read by Dune. The ``lang`` stanza looks +like: .. code:: scheme (lang dune 0.1) -The 0.1 version of the language is exactly the same as the Jbuilder -language. So to convert a Jbuilder project to Dune, simply write this -file at the root of your project. +The 0.1 version of the language is exactly the same as the Jbuilder language. So +to convert a Jbuilder project to Dune, simply write this file at the root of +your project. Additionally, they can contains the following stanzas. @@ -217,9 +216,9 @@ everything that is installable in a workspace, run at the root: $ dune build @install -Declaring a package this way will allow you to add elements such as -libraries, executables, documentation, ... to your package by declaring -them in ``jbuild`` files. +Declaring a package this way will allow you to add elements such as libraries, +executables, documentation, ... to your package by declaring them in ``dune`` +files. Such elements can only be declared in the scope defined by the corresponding ``.opam`` file. Typically, your diff --git a/doc/usage.rst b/doc/usage.rst index ca439652..164f0d7a 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -29,7 +29,7 @@ directory: More precisely, it will choose the outermost ancestor directory containing a ``dune-workspace`` file as root. For instance if you are in -``/home/me/code/myproject/src``, then jbuilder will look for all these files in +``/home/me/code/myproject/src``, then dune will look for all these files in order: - ``/dune-workspace`` @@ -182,9 +182,9 @@ There are two ways to run tests: - ``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: +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: - ``dune build @foo/bar/runtest`` - ``dune runtest foo/bar`` @@ -199,11 +199,11 @@ with locally defined libraries loaded. $ dune utop -- -Where ```` is a directory containing a ``jbuild`` file defining all the +Where ```` is a directory containing a ``dune`` 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, ``dune utop lib --- -implicit-bindings`` will start ``utop`` with the libraries defined in -``lib`` and implicit bindings for toplevel expressions. +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. Requirements & Limitations -------------------------- @@ -218,14 +218,14 @@ Requirements & Limitations Restricting the set of packages =============================== -You can restrict the set of packages from your workspace that dune -can see with the ``--only-packages`` option: +You can restrict the set of packages from your workspace that dune can see with +the ``--only-packages`` option: .. code:: bash $ dune build --only-packages pkg1,pkg2,... @install -This option acts as if you went through all the jbuild files and +This option acts as if you went through all the dune files and commented out the stanzas refering to a package that is not in the list given to ``dune``. @@ -252,33 +252,32 @@ This has the following effects: - it uses whatever concurrency option opam provides - it sets the default target to ``@install`` rather than ``@@default`` -Note that ``name`` and ``jobs`` are variables expanded by opam. ``name`` -expands to the package name and ``jobs`` to the number of jobs available -to build the package. +Note that ``name`` and ``jobs`` are variables expanded by opam. ``name`` expands +to the package name and ``jobs`` to the number of jobs available to build the +package. Tests ===== -To setup the building and running of tests in opam, add this line to -your ``.opam`` file: +To setup the building and running of tests in opam, add this line to your +``.opam`` file: :: - build-test: [["jbuilder" "runtest" "-p" name "-j" jobs]] + build-test: [["dune" "runtest" "-p" name "-j" jobs]] Installation ============ -Installing a package means copying the build artifacts from the build -directory to the installed word. +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: -dune generates a ``.install`` file that opam will -automatically read to handle installation. +When installing via opam, you don't need to worry about this step: 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 -dune to install the artifacts by hands. To do that, use the -``install`` command: +However, when not using opam or doing local development, you can use dune to +install the artifacts by hands. To do that, use the ``install`` command: :: @@ -286,61 +285,57 @@ dune to install the artifacts by hands. To do that, use the 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. +packages. If several build contexts are configured, the installation will be +performed for all of them. -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 ``dune install``. +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 ``dune +install``. Destination ----------- -The place where the build artifacts are copied, usually referred as -**prefix**, is determined as follow for a given build context: +The place where the build artifacts are copied, usually referred as **prefix**, +is determined as follow for a given build context: #. if an explicit ``--prefix `` argument is passed, use this path #. if ``opam`` is present in the ``PATH`` and is configured, use the output of ``opam config var prefix`` #. otherwise, take the parent of the directory where ``ocamlc`` was found. -As an exception to this rule, library files might be copied to a -different location. The reason for this is that they often need to be -copied to a particular location for the various build system used in -OCaml projects to find them and this location might be different from -``/lib`` on some systems. +As an exception to this rule, library files might be copied to a different +location. The reason for this is that they often need to be copied to a +particular location for the various build system used in OCaml projects to find +them and this location might be different from ``/lib`` on some systems. -Historically, the location where to store OCaml library files was -configured through `findlib -`__ and the -``ocamlfind`` command line tool was used to both install these files -and locate them. Many Linux distributions or other packaging systems -are using this mechanism to setup where OCaml library files should be -copied. +Historically, the location where to store OCaml library files was configured +through `findlib `__ and the +``ocamlfind`` command line tool was used to both install these files and locate +them. Many Linux distributions or other packaging systems 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 -``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 ``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. +As a result, if none of ``--libdir`` and ``--prefix`` is passed to ``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 ``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. -Note that ``--prefix`` and ``--libdir`` are only supported if a single -build context is in use. +Note that ``--prefix`` and ``--libdir`` are only supported if a single build +context is in use. Workspace configuration ======================= -By default, a workspace has only one build context named ``default`` -which correspond to the environment in which ``dune`` is run. You can -define more contexts by writing a ``dune-workspace`` file. +By default, a workspace has only one build context named ``default`` which +correspond to the environment in which ``dune`` is run. You can define more +contexts by writing a ``dune-workspace`` file. -You can point ``dune`` to an explicit ``dune-workspace`` file with -the ``--workspace`` option. For instance it is good practice to write a -``dune-workspace.dev`` in your project with all the version of OCaml -your projects support. This way developers can tests that the code -builds with all version of OCaml by simply running: +You can point ``dune`` to an explicit ``dune-workspace`` file with the +``--workspace`` option. For instance it is good practice to write a +``dune-workspace.dev`` in your project with all the version of OCaml your +projects support. This way developers can tests that the code builds with all +version of OCaml by simply running: .. code:: bash @@ -361,29 +356,28 @@ a typical ``dune-workspace`` file looks like: The rest of this section describe the stanzas available. -Note that an empty ``dune-workspace`` file is interpreted the same -as one containing exactly: +Note that an empty ``dune-workspace`` file is interpreted the same as one +containing exactly: .. code:: scheme (lang dune 1.0) (context default) -This allows you to use an empty ``dune-workspace`` file to mark -the root of your project. +This allows you to use an empty ``dune-workspace`` file to mark the root of your +project. profile ~~~~~~~ -The build profile can be selected in the ``dune-workspace`` file by -write a ``(profile ...)`` stanza. For instance: +The build profile can be selected in the ``dune-workspace`` file by write a +``(profile ...)`` stanza. For instance: .. code:: scheme (profile release) -Note that the command line option ``--profile`` has precedence over -this stanza. +Note that the command line option ``--profile`` has precedence over this stanza. context ~~~~~~~ @@ -413,19 +407,18 @@ context or can be the description of an opam switch, as follows: context. This has precedence over the command line option ``--profile`` -Both ``(default ...)`` and ``(opam ...)`` accept a ``targets`` field -in order to setup cross compilation. See :ref:`advanced-cross-compilation` -for more information. +Both ``(default ...)`` and ``(opam ...)`` accept a ``targets`` field in order to +setup cross compilation. See :ref:`advanced-cross-compilation` for more +information. -Merlin reads compilation artifacts and it can only read the -compilation artifacts of a single context. Usually, you should use -the artifacts from the ``default`` context, and if you have the -``(context default)`` stanza in your ``dune-workspace`` file, that -is the one Jbuilder will use. +Merlin reads compilation artifacts and it can only read the compilation +artifacts of a single context. Usually, you should use the artifacts from the +``default`` context, and if you have the ``(context default)`` stanza in your +``dune-workspace`` file, that is the one dune will use. -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. +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 ==================================== @@ -443,77 +436,58 @@ It supports two modes of compilation: separately and then linked together. This mode is useful during development as it builds more quickly. -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. +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:`dune-jsoo` for passing custom flags to the js_of_ocaml compiler -.. _using-topkg: - -Using topkg with dune +Distributing Projects ===================== -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. +Dune provides support for building and installing your project. However it +doesn't provide helpers for distributing it. It is recommended to use +`dune-release `__ for this purpose. -The `topkg-jbuilder `__ -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: - -.. code:: ocaml - - #use "topfind" - #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 dune projects. - -The common defaults are that your projects include the following -files: +The common defaults are that your projects include the following files: - ``README.md`` - ``CHANGES.md`` - ``LICENSE.md`` -And that if your project contains several packages, then all the -package names must be prefixed by the shortest one. +And that if your project contains several packages, then all the package names +must be prefixed by the shortest one. Watermarking ============ -One of the feature topkg provides is watermarking; it replaces various -strings of the form ``%%ID%%`` in all files of your project before -creating a release tarball or when the package is pinned by the user -using opam. +One of the feature topkg provides is watermarking; it replaces various strings +of the form ``%%ID%%`` in all files of your project before creating a release +tarball or when the package is pinned by the user using opam. -This is especially interesting for the ``VERSION`` watermark, which -gets replaced by the version obtained from the vcs. For instance if -you are using git, topkg invokes this command to find out the version: +This is especially interesting for the ``VERSION`` watermark, which gets +replaced by the version obtained from the vcs. For instance if you are using +git, topkg invokes this command to find out the version: .. code:: bash $ git describe --always --dirty 1.0+beta9-79-g29e9b37 -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, -dune provides the ``subst`` sub-command. +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, dune provides the ``subst`` +sub-command. dune subst ========== -``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. +``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 -files: +More precisely, it replaces all the following watermarks in source files: - ``NAME``, the name of the project - ``VERSION``, output of ``git describe --always --dirty`` @@ -529,18 +503,18 @@ files: - ``PKG_LICENSE``, contents of the ``license`` field from the opam file - ``PKG_REPO``, contents of the ``repo`` field from the opam file -Note that if your project contains several packages, ``NAME`` will -be replaced by the shorted package name as long as it is a prefix of -all the package names. If your package names don't follow this rule, -you need to specify the name explicitly via the ``-n`` flag: +Note that if your project contains several packages, ``NAME`` will be replaced +by the shorted package name as long as it is a prefix of all the package names. +If your package names don't follow this rule, you need to specify the name +explicitly via the ``-n`` flag: .. code:: bash $ dune subst -n myproject -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 ``dune subst``. +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 ``dune subst``. Custom Build Directory ======================