matthieu
/
dune
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge branch 'master' into dune-gen-meta

This commit is contained in:
Rudi Grinberg 2018-07-06 15:39:43 +07:00 committed by GitHub
parent a8bd8ffa44 0f607c39fb
commit 35f111981f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 149 additions and 167 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc/advanced-topics.rst
View File

@ -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
=============

4
doc/configurator.rst
View File

@ -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.

8
doc/documentation.rst
View File

@ -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
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.

13
doc/faq.rst
View File

@ -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

2
doc/index.rst
View File

@ -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.

47
doc/project-layout-specification.rst
View File

@ -2,24 +2,23 @@
Project Layout and Metadata Specification
*****************************************
A typical dune project will have a ```dune-project`` and one or
more ``<package>.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
``<package>.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 ``<package>.opam`` file. Typically, your

234
doc/usage.rst
View File

@ -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 <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
-- -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 ``<package>.opam`` file:
To setup the building and running of tests in opam, add this line to your
``<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
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 ``<package>.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 ``<package>.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 <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
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
``<prefix>/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 ``<prefix>/lib`` on some systems.
Historically, the location where to store OCaml library files was
configured through `findlib
<http://projects.camlcity.org/projects/findlib.html>`__ 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 <http://projects.camlcity.org/projects/findlib.html>`__ 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 <https://github.com/dbuenzli/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 <https://github.com/samoht/dune-release>`__ for this purpose.
The `topkg-jbuilder <https://github.com/diml/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
======================