Merge branch 'master' into dune-gen-meta

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
+To clarify this with an example, let's assume that you have the following
-following ``src/jbuild`` file:
+``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
 =============

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.

doc/documentation.rst

@@ -79,10 +79,10 @@ Where ``<optional-fields>`` 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
+specially by dune. This will be the file used to generate the entry page for the
-the package. This is the page that will be linked from the main package listing.
+package. This is the page that will be linked from the main package listing. If
-If you omit writing an ``index.mld``, dune will generate one with the entry
+you omit writing an ``index.mld``, dune will generate one with the entry modules
-modules for your package. But this generated will not be installed.
+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.

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

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.

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
+A typical dune project will have a ```dune-project`` and one or more
-more ``<package>.opam`` file at toplevel as well as ``jbuild`` files
+``<package>.opam`` file at toplevel as well as ``dune`` files wherever
-wherever interesting things are: libraries, executables, tests,
+interesting things are: libraries, executables, tests, documents to install,
-documents to install, etc...
+etc...
 
-It is recommended to organize your project so that you have exactly one
+It is recommended to organize your project so that you have exactly one library
-library per directory. You can have several executables in the same
+per directory. You can have several executables in the same directory, as long
-directory, as long as they share the same build configuration. If you'd
+as they share the same build configuration. If you'd like to have multiple
-like to have multiple executables with different configurations in the
+executables with different configurations in the same directory, you will have
-same directory, you will have to make an explicit module list for every
+to make an explicit module list for every executable using ``modules``.
-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
+Note that the dune metadata format is versioned in order to ensure forward
-forward compatibility. There is currently only one version available,
+compatibility. There is currently only one version available, but to be future
-but to be future proof, you should still specify it in your ``jbuild``
+proof, you should still specify it in your ``dune`` files. If no version is
-files. If no version is specified, the latest one will be used.
+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
+These files are used to mark the root of projects as well as define project-wide
-project-wide parameters. These files are required to have a ``lang``
+parameters. These files are required to have a ``lang`` which controls the names
-which controls the names and contents of all configuration files read
+and contents of all configuration files read by Dune. The ``lang`` stanza looks
-by Dune. The ``lang`` stanza looks like:
+like:
 
 .. code:: scheme
 
           (lang dune 0.1)
 
-The 0.1 version of the language is exactly the same as the Jbuilder
+The 0.1 version of the language is exactly the same as the Jbuilder language. So
-language. So to convert a Jbuilder project to Dune, simply write this
+to convert a Jbuilder project to Dune, simply write this file at the root of
-file at the root of your project.
+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
+Declaring a package this way will allow you to add elements such as libraries,
-libraries, executables, documentation, ... to your package by declaring
+executables, documentation, ... to your package by declaring them in ``dune``
-them in ``jbuild`` files.
+files.
 
 Such elements can only be declared in the scope defined by the
 corresponding ``<package>.opam`` file. Typically, your

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 two commands are equivalent. They will run all the tests defined in the
-the current directory and its children recursively. You can also run the
+current directory and its children recursively. You can also run the tests in a
-tests in a specific sub-directory and its children by using:
+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 <dir> -- <args>
 
-Where ``<dir>`` is a directory containing a ``jbuild`` file defining all the
+Where ``<dir>`` is a directory containing a ``dune`` file defining all the
 libraries that will be loaded (using the ``library`` stanza). ``<args>`` will be
-passed as arguments to the utop command itself. For example, ``dune 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
+-implicit-bindings`` will start ``utop`` with the libraries defined in ``lib``
-``lib`` and implicit bindings for toplevel expressions.
+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
+You can restrict the set of packages from your workspace that dune can see with
-can see with the ``--only-packages`` option:
+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``
+Note that ``name`` and ``jobs`` are variables expanded by opam. ``name`` expands
-expands to the package name and ``jobs`` to the number of jobs available
+to the package name and ``jobs`` to the number of jobs available to build the
-to build the package.
+package.
 
 Tests
 =====
 
-To setup the building and running of tests in opam, add this line to
+To setup the building and running of tests in opam, add this line to your
-your ``<package>.opam`` file:
+``<package>.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
+Installing a package means copying the build artifacts from the build directory
-directory to the installed word.
+to the installed word.
 
-When installing via opam, you don't need to worry about this step:
+When installing via opam, you don't need to worry about this step: dune
-dune generates a ``<package>.install`` file that opam will
+generates a ``<package>.install`` file that opam will automatically read to
-automatically read to handle installation.
+handle installation.
 
-However, when not using opam or doing local development, you can use
+However, when not using opam or doing local development, you can use dune to
-dune to install the artifacts by hands. To do that, use the
+install the artifacts by hands. To do that, use the ``install`` command:
-``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
+packages. If several build contexts are configured, the installation will be
-will be performed for all of them.
+performed for all of them.
 
-Note that ``dune install`` is a thin wrapper around the
+Note that ``dune install`` is a thin wrapper around the ``opam-installer`` tool,
-``opam-installer`` tool, so you will need to install this tool in order
+so you will need to install this tool in order to be able to use ``dune
-to be able to use ``dune install``.
+install``.
 
 Destination
 -----------
 
-The place where the build artifacts are copied, usually referred as
+The place where the build artifacts are copied, usually referred as **prefix**,
-**prefix**, is determined as follow for a given build context:
+is determined as follow for a given build context:
 
 #. if an explicit ``--prefix <path>`` 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
+As an exception to this rule, library files might be copied to a different
-different location. The reason for this is that they often need to be
+location. The reason for this is that they often need to be copied to a
-copied to a particular location for the various build system used in
+particular location for the various build system used in OCaml projects to find
-OCaml projects to find them and this location might be different from
+them and this location might be different from ``<prefix>/lib`` on some systems.
-``<prefix>/lib`` on some systems.
 
-Historically, the location where to store OCaml library files was
+Historically, the location where to store OCaml library files was configured
-configured through `findlib
+through `findlib <http://projects.camlcity.org/projects/findlib.html>`__ and the
-<http://projects.camlcity.org/projects/findlib.html>`__ and the
+``ocamlfind`` command line tool was used to both install these files and locate
-``ocamlfind`` command line tool was used to both install these files
+them. Many Linux distributions or other packaging systems are using this
-and locate them. Many Linux distributions or other packaging systems
+mechanism to setup where OCaml library files should be copied.
-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
+As a result, if none of ``--libdir`` and ``--prefix`` is passed to ``dune
-``dune install`` and ``ocamlfind`` is present in the ``PATH``,
+install`` and ``ocamlfind`` is present in the ``PATH``, then library files will
-then library files will be copied to the directory reported by
+be copied to the directory reported by ``ocamlfind printconf destdir``. This
-``ocamlfind printconf destdir``. This ensures that ``dune
+ensures that ``dune install`` can be used without opam. When using opam,
-install`` can be used without opam. When using opam, ``ocamlfind`` is
+``ocamlfind`` is configured to point to the opam directory, so this rule makes
-configured to point to the opam directory, so this rule makes no
+no difference.
-difference.
 
-Note that ``--prefix`` and ``--libdir`` are only supported if a single
+Note that ``--prefix`` and ``--libdir`` are only supported if a single build
-build context is in use.
+context is in use.
 
 Workspace configuration
 =======================
 
-By default, a workspace has only one build context named ``default``
+By default, a workspace has only one build context named ``default`` which
-which correspond to the environment in which ``dune`` is run. You can
+correspond to the environment in which ``dune`` is run. You can define more
-define more contexts by writing a ``dune-workspace`` file.
+contexts by writing a ``dune-workspace`` file.
 
-You can point ``dune`` to an explicit ``dune-workspace`` file with
+You can point ``dune`` to an explicit ``dune-workspace`` file with the
-the ``--workspace`` option. For instance it is good practice to write a
+``--workspace`` option. For instance it is good practice to write a
-``dune-workspace.dev`` in your project with all the version of OCaml
+``dune-workspace.dev`` in your project with all the version of OCaml your
-your projects support. This way developers can tests that the code
+projects support. This way developers can tests that the code builds with all
-builds with all version of OCaml by simply running:
+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
+Note that an empty ``dune-workspace`` file is interpreted the same as one
-as one containing exactly:
+containing exactly:
 
 .. code:: scheme
 
     (lang dune 1.0)
     (context default)
 
-This allows you to use an empty ``dune-workspace`` file to mark
+This allows you to use an empty ``dune-workspace`` file to mark the root of your
-the root of your project.
+project.
 
 profile
 ~~~~~~~
 
-The build profile can be selected in the ``dune-workspace`` file by
+The build profile can be selected in the ``dune-workspace`` file by write a
-write a ``(profile ...)`` stanza. For instance:
+``(profile ...)`` stanza. For instance:
 
 .. code:: scheme
 
     (profile release)
 
-Note that the command line option ``--profile`` has precedence over
+Note that the command line option ``--profile`` has precedence over this stanza.
-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
+Both ``(default ...)`` and ``(opam ...)`` accept a ``targets`` field in order to
-in order to setup cross compilation. See :ref:`advanced-cross-compilation`
+setup cross compilation. See :ref:`advanced-cross-compilation` for more
-for more information.
+information.
 
-Merlin reads compilation artifacts and it can only read the
+Merlin reads compilation artifacts and it can only read the compilation
-compilation artifacts of a single context.  Usually, you should use
+artifacts of a single context. Usually, you should use the artifacts from the
-the artifacts from the ``default`` context, and if you have the
+``default`` context, and if you have the ``(context default)`` stanza in your
-``(context default)`` stanza in your ``dune-workspace`` file, that
+``dune-workspace`` file, that is the one dune will use.
-is the one Jbuilder will use.
 
-For rare cases where this is not what you want, you can force dune
+For rare cases where this is not what you want, you can force dune to use a
-to use a different build contexts for merlin by adding the field
+different build contexts for merlin by adding the field ``(merlin)`` to this
-``(merlin)`` to this context.
+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
+The separate compilation mode will be selected when the build profile is
-is ``dev``, which is the default. There is currently no other way to
+``dev``, which is the default. There is currently no other way to control this
-control this behaviour.
+behaviour.
 
 See the section about :ref:`dune-jsoo` for passing custom flags to the
 js_of_ocaml compiler
 
-.. _using-topkg:
+Distributing Projects
-
-Using topkg with dune
 =====================
 
-Dune provides support for building and installing your project.
+Dune provides support for building and installing your project. However it
-However it doesn't provides helpers for distributing it. It is
+doesn't provide helpers for distributing it. It is recommended to use
-recommemded to use `Topkg <https://github.com/dbuenzli/topkg>`__ for
+`dune-release <https://github.com/samoht/dune-release>`__ for this purpose.
-this purpose.
 
-The `topkg-jbuilder <https://github.com/diml/topkg-jbuilder>`__
+The common defaults are that your projects include the following files:
-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:
 
 - ``README.md``
 - ``CHANGES.md``
 - ``LICENSE.md``
 
-And that if your project contains several packages, then all the
+And that if your project contains several packages, then all the package names
-package names must be prefixed by the shortest one.
+must be prefixed by the shortest one.
 
 Watermarking
 ============
 
-One of the feature topkg provides is watermarking; it replaces various
+One of the feature topkg provides is watermarking; it replaces various strings
-strings of the form ``%%ID%%`` in all files of your project before
+of the form ``%%ID%%`` in all files of your project before creating a release
-creating a release tarball or when the package is pinned by the user
+tarball or when the package is pinned by the user using opam.
-using opam.
 
-This is especially interesting for the ``VERSION`` watermark, which
+This is especially interesting for the ``VERSION`` watermark, which gets
-gets replaced by the version obtained from the vcs. For instance if
+replaced by the version obtained from the vcs. For instance if you are using
-you are using git, topkg invokes this command to find out the version:
+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
+Projects using dune usually only need topkg for creating and publishing
-publishing releases. However they might still want to substitute the
+releases. However they might still want to substitute the watermarks when the
-watermarks when the package is pinned by the user. To help with this,
+package is pinned by the user. To help with this, dune provides the ``subst``
-dune provides the ``subst`` sub-command.
+sub-command.
 
 dune subst
 ==========
 
-``dune subst`` performs the same substitution ``topkg`` does with
+``dune subst`` performs the same substitution ``topkg`` does with the default
-the default configuration. i.e. calling ``dune subst`` at the root
+configuration. i.e. calling ``dune subst`` at the root of your project will
-of your project will rewrite in place all the files in your project.
+rewrite in place all the files in your project.
 
-More precisely, it replaces all the following watermarks in source
+More precisely, it replaces all the following watermarks in source files:
-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
+Note that if your project contains several packages, ``NAME`` will be replaced
-be replaced by the shorted package name as long as it is a prefix of
+by the shorted package name as long as it is a prefix of all the package names.
-all the package names. If your package names don't follow this rule,
+If your package names don't follow this rule, you need to specify the name
-you need to specify the name explicitly via the ``-n`` flag:
+explicitly via the ``-n`` flag:
 
 .. code:: bash
 
     $ dune subst -n myproject
 
-Finally, note that dune doesn't allow you to customize the list of
+Finally, note that dune doesn't allow you to customize the list of substituted
-substituted watermarks. If you which to do so, you need to configure
+watermarks. If you which to do so, you need to configure topkg and use it
-topkg and use it instead of ``dune subst``.
+instead of ``dune subst``.
 
 Custom Build Directory
 ======================