2017-05-14 00:10:00 +00:00
|
|
|
********************
|
|
|
|
jbuild specification
|
|
|
|
********************
|
|
|
|
|
|
|
|
``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.
|
|
|
|
|
2017-05-29 09:05:04 +00:00
|
|
|
The syntax of ``jbuild`` files is described in
|
|
|
|
:ref:``metadata-format`` section.
|
2017-05-27 09:52:39 +00:00
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
Stanzas
|
|
|
|
=======
|
|
|
|
|
|
|
|
``jbuild`` files are composed of stanzas. For instance a typical
|
|
|
|
``jbuild`` looks like:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(library
|
|
|
|
((name mylib)
|
|
|
|
(libraries (base lwt))))
|
|
|
|
|
|
|
|
(rule
|
|
|
|
((targets (foo.ml))
|
|
|
|
(deps (generator/gen.exe))
|
|
|
|
(action (run ${<} -o ${@}))))
|
|
|
|
|
|
|
|
The following sections describe the available stanzas and their meaning.
|
|
|
|
|
|
|
|
jbuild_version
|
|
|
|
--------------
|
|
|
|
|
|
|
|
``(jbuild_version 1)`` specifies that we are using the version 1 of
|
|
|
|
the Jbuilder metadata format in this ``jbuild`` file.
|
|
|
|
|
|
|
|
library
|
|
|
|
-------
|
|
|
|
|
|
|
|
The ``library`` stanza must be used to describe OCaml libraries. The
|
|
|
|
format of library stanzas is as follows:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(library
|
|
|
|
((name <library-name>)
|
|
|
|
<optional-fields>
|
|
|
|
))
|
|
|
|
|
|
|
|
``<library-name>`` is the real name of the library. It determines the
|
|
|
|
names of the archive files generated for the library as well as the
|
|
|
|
module name under which the library will be available, unless
|
|
|
|
``(wrapped false)`` is used (see below). It must be a valid OCaml
|
|
|
|
module name but doesn't need to start with a uppercase letter.
|
|
|
|
|
|
|
|
For instance, the modules of a library named ``foo`` will be
|
|
|
|
available as ``Foo.XXX`` outside of ``foo`` itself. It is however
|
|
|
|
allowed to write an explicit ``Foo`` module, in which case this will
|
|
|
|
be the interface of the library and you are free to expose only the
|
|
|
|
modules you want.
|
|
|
|
|
|
|
|
``<optional-fields>`` are:
|
|
|
|
|
|
|
|
- ``(public_name <name>)`` this is the name under which the library can be
|
2017-06-01 15:02:29 +00:00
|
|
|
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
|
|
|
|
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,
|
|
|
|
as determined by the :ref:`opam-files`
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(synopsis <string>)`` should give a one-line description of the library.
|
2017-06-01 15:02:29 +00:00
|
|
|
This is used by tools that list installed libraries
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(modules <modules>)`` specifies what modules are part of the library. By
|
2017-06-01 15:02:29 +00:00
|
|
|
default Jbuilder 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 <modules>)`` field. ``<modules>`` uses the `Ordered set language`_
|
|
|
|
where elements are module names and don't need to start with a uppercase
|
|
|
|
letter. For instance to exclude module ``Foo``: ``(modules (:standard \
|
|
|
|
foo))``
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(libraries (<library-dependencies>))`` is used to specify the dependencies
|
2017-06-01 15:02:29 +00:00
|
|
|
of the library. See the section about `Library dependencies`_ for more details
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(wrapped <boolean>)`` specifies whether the modules of the library should be
|
2017-06-01 15:02:29 +00:00
|
|
|
available only through the top-level library module, or should all be exposed
|
|
|
|
at the top level. The default is ``true`` and it is highly recommended to keep
|
|
|
|
it this way. Because OCaml top-level modules must all be unique when linking
|
|
|
|
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
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(preprocess <preprocess-spec>)`` specifies how to preprocess files if
|
2017-06-01 15:02:29 +00:00
|
|
|
needed. The default is ``no_processing``. Other options are described in the
|
|
|
|
`Preprocessing specification`_ section
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(preprocessor_deps (<deps-conf list>))`` specifies extra dependencies of the
|
2017-06-01 15:02:29 +00:00
|
|
|
preprocessor, for instance if the preprocessor reads a generated file. The
|
|
|
|
specification of dependencies is described in the `Dependency specification`_
|
|
|
|
section
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(optional)``, if present it indicates that the library should only be built
|
2017-06-01 15:02:29 +00:00
|
|
|
and installed if all the dependencies are available, either in the workspace
|
|
|
|
or in the installed world. You can use this to provide extra features without
|
|
|
|
adding hard dependencies to your project
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(c_names (<names>))``, if your library has stubs, you must list the C files
|
2017-06-01 15:02:29 +00:00
|
|
|
in this field, without the ``.c`` extension
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(cxx_names (<names>))`` is the same as ``c_names`` but for C++ stubs
|
|
|
|
|
|
|
|
- ``(install_c_headers (<names>))``, if your library has public C header files
|
2017-06-01 15:02:29 +00:00
|
|
|
that must be installed, you must list them in this field, with the ``.h``
|
|
|
|
extension
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(modes (<modes>))`` modes (``byte`` and ``native``) which should be built by
|
2017-06-01 15:02:29 +00:00
|
|
|
default. This is only useful when writing libraries for the OCaml toplevel
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(no_dynlink)`` is to disable dynamic linking of the library. This is for
|
2017-06-01 15:02:29 +00:00
|
|
|
advanced use only, by default you shouldn't set this option
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(kind <kind>)`` is the kind of the library. The default is ``normal``, other
|
2017-06-01 15:02:29 +00:00
|
|
|
available choices are ``ppx_rewriter`` and ``ppx_deriver`` and must be set
|
|
|
|
when the library is intended to be used as a ppx rewriter or a ``[@@deriving
|
|
|
|
...]`` plugin. The reason why ``ppx_rewriter`` and ``ppx_deriver`` are split
|
|
|
|
is historical and hopefully we won't need two options soon
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(ppx_runtime_libraries (<library-names>))`` is for when the library is a ppx
|
2017-06-01 15:02:29 +00:00
|
|
|
rewriter or a ``[@@deriving ...]`` plugin and has runtime dependencies. You
|
|
|
|
need to specify these runtime dependencies here
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(virtual_deps (<opam-packages>)``. Sometimes opam packages enable a specific
|
2017-06-01 15:02:29 +00:00
|
|
|
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
|
|
|
|
synthesize the ``depends`` and ``depopts`` sections of your opam file
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
- ``js_of_ocaml``. See the section about :ref:`jbuild-jsoo`
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
- ``flags``, ``ocamlc_flags`` and ``ocamlopt_flags``. See the section about
|
2017-06-01 15:02:29 +00:00
|
|
|
`OCaml flags`_
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(library_flags (<flags>))`` is a list of flags that are passed as it to
|
2017-06-01 15:02:29 +00:00
|
|
|
``ocamlc`` and ``ocamlopt`` when building the library archive files. You can
|
|
|
|
use this to specify ``-linkall`` for instance. ``<flags>`` is a list of
|
|
|
|
strings supporting `Variables expansion`_
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
- ``(c_flags <flags>)`` specifies the compilation flags for C stubs, using the
|
|
|
|
`Ordered set language`_. This field supports ``(:include ...)`` forms
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
- ``(cxx_flags <flags>)`` is the same as ``c_flags`` but for C++ stubs
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(c_library_flags <flags>)`` specifies the flags to pass to the C compiler
|
2017-06-01 15:02:29 +00:00
|
|
|
when constructing the library archive file for the C stubs. ``<flags>`` uses
|
|
|
|
the `Ordered set language`_ and supports ``(:include ...)`` forms. When you
|
|
|
|
are writing bindings for a C library named ``bar``, you should typically write
|
|
|
|
``-lbar`` here, or whatever flags are necessary to to link against this
|
|
|
|
library
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(self_build_stubs_archive <c-libname>)`` indicates to Jbuilder that the
|
2017-06-01 15:02:29 +00:00
|
|
|
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
|
|
|
|
<https://github.com/janestreet/re2>`__ for an example of use
|
|
|
|
|
|
|
|
Note that when binding C libraries, Jbuilder doesn't provide special support for
|
|
|
|
tools such as ``pkg-config``, however it integrates easily with `configurator
|
|
|
|
<https://github.com/janestreet/configurator>`__ by using ``(c_flags (:include
|
|
|
|
...))`` and ``(c_library_flags (:include ...))``.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
executable
|
|
|
|
----------
|
|
|
|
|
|
|
|
The ``executable`` stanza must be used to describe an executable. The
|
|
|
|
format of executable stanzas is as follows:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(executable
|
|
|
|
((name <name>)
|
|
|
|
<optional-fields>
|
|
|
|
))
|
|
|
|
|
|
|
|
``<name>`` 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
|
|
|
|
<name>)``, Jbuilder will know how to build ``<name>.exe``, ``<name>.bc`` and
|
|
|
|
``<name>.bc.js``. ``<name>.exe`` is a native code executable, ``<name>.bc`` is a
|
|
|
|
bytecode executable which requires ``ocamlrun`` to run and ``<name>.bc.js`` is a
|
|
|
|
JavaScript generated using js_of_ocaml.
|
|
|
|
|
2017-06-02 17:54:45 +00:00
|
|
|
Note that in case native compilation is not available, ``<name>.exe``
|
|
|
|
will in fact be a custom byte-code executable. Custom in the sense of
|
|
|
|
``ocamlc -custom``, meaning that it is a native executable that embeds
|
|
|
|
the ``ocamlrun`` virtual machine as well as the byte code. As such you
|
|
|
|
can always rely on ``<name>.exe`` being available. Moreover, it is
|
|
|
|
usually preferable to use ``<name>.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.
|
2017-05-29 12:18:55 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
Native compilation is considered not available when there is no ``ocamlopt``
|
|
|
|
binary at the same place as where ``ocamlc`` was found, or when there is a
|
|
|
|
``(modes (...))`` field not listing ``native``.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
``<optional-fields>`` are:
|
2017-06-01 15:02:29 +00:00
|
|
|
|
|
|
|
- ``(public_name <public-name>)`` specifies that the executable should be
|
|
|
|
installed under that name. It is the same as adding the following stanza to
|
|
|
|
your ``jbuild`` file:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(install
|
|
|
|
((section bin)
|
|
|
|
(files ((<name>.exe as <public-name>)))))
|
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
- ``(package <package>)`` if there is a ``(public_name ...)`` field, this
|
|
|
|
specifies the package the executables are part of
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
- ``(libraries (<library-dependencies>))`` specifies the library dependencies.
|
2017-06-01 15:02:29 +00:00
|
|
|
See the section about `Library dependencies`_ for more details
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
- ``(modules <modules>)`` specifies which modules in the current directory
|
2017-06-01 15:02:29 +00:00
|
|
|
Jbuilder 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`_
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-29 13:06:52 +00:00
|
|
|
- ``(modes (<modes>))`` modes (``byte`` and ``native``) which should be built by
|
2017-06-01 15:02:29 +00:00
|
|
|
default. If the stanza has a ``(public_name ...)`` field and ``native`` is not
|
|
|
|
listed here, the byte-code version will be installed instead.
|
2017-05-29 13:06:52 +00:00
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
- ``(preprocess <preprocess-spec>)`` is the same as the ``(preprocess ...)``
|
2017-06-01 15:02:29 +00:00
|
|
|
field of `library`_
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
- ``(preprocessor_deps (<deps-conf list>))`` is the same as the
|
2017-06-01 15:02:29 +00:00
|
|
|
``(preprocessor_deps ...)`` field of `library`_
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
- ``js_of_ocaml``. See the section about `js_of_ocaml`_
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
- ``flags``, ``ocamlc_flags`` and ``ocamlopt_flags``. See the section about
|
|
|
|
specifying `OCaml flags`_
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
executables
|
|
|
|
-----------
|
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
The ``executables`` stanza is the same as the ``executable`` stanza, except that
|
|
|
|
it is used to describe several executables sharing the same configuration.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
It shares the same fields as the ``executable`` stanza, except that instead of
|
|
|
|
``(name ...)`` and ``(public_name ...)`` you must use:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
- ``(names (<names>))`` where ``<names>`` is a list of entry point names. As for
|
|
|
|
``executable`` you only need to specify the modules containing the entry point
|
|
|
|
of each executable
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
- ``(public_names (<names>))`` describes under what name each executable should
|
|
|
|
be installed. The list of names must be of the same length as the list in the
|
|
|
|
``(names ...)`` field. Moreover you can use ``-`` for executables that
|
|
|
|
shouldn't be installed
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
rule
|
|
|
|
----
|
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
The ``rule`` stanza is used to create custom user rules. It tells Jbuilder how
|
|
|
|
to generate a specific set of files from a specific set of dependencies.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
The syntax is as follows:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(rule
|
|
|
|
((targets (<filenames>))
|
|
|
|
(deps (<deps-conf list>))
|
|
|
|
(action <action>)))
|
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
``<filenames>`` is a list of file names. Note that currently Jbuilder only
|
|
|
|
support user rules with targets in the current directory.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
``<deps-conf list>`` specifies the dependencies of the rule. See the `Dependency
|
|
|
|
specification`_ section for more details.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
``<action>`` is the action to run to produce the targets from the dependencies.
|
|
|
|
See the `User actions`_ section for more details.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
Note that contrary to makefiles or other build systems, user rules currently
|
|
|
|
don't support patterns, such as a rule to produce ``%.y`` from ``%.x`` for any
|
|
|
|
given ``%``. This might be supported in the future.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:53:55 +00:00
|
|
|
inferred rules
|
|
|
|
~~~~~~~~~~~~~~
|
2017-05-31 09:34:17 +00:00
|
|
|
|
|
|
|
When using the action DSL (see `User actions`_), it is most of the
|
|
|
|
time obvious what are the dependencies and targets.
|
|
|
|
|
|
|
|
For instance:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(rule
|
|
|
|
((targets (b)
|
|
|
|
(deps (a)
|
|
|
|
(action (copy ${<} ${@}))))))
|
|
|
|
|
|
|
|
In this example it is obvious by inspecting the action what the
|
2017-06-01 15:53:55 +00:00
|
|
|
dependencies and targets are. When this is the case you can use the
|
|
|
|
following shorter syntax, where Jbuilder infers dependencies and
|
|
|
|
targets for you:
|
2017-05-31 09:34:17 +00:00
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
2017-06-01 15:53:55 +00:00
|
|
|
(rule <action>)
|
2017-05-31 09:34:17 +00:00
|
|
|
|
|
|
|
For instance:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
2017-06-01 15:53:55 +00:00
|
|
|
(rule (copy a b))
|
2017-05-31 09:34:17 +00:00
|
|
|
|
|
|
|
Note that in Jbuilder, targets must always be known
|
|
|
|
statically. Especially, this mean that Jbuilder must be able to
|
2017-06-01 15:53:55 +00:00
|
|
|
statically determine all targets. For instance, this ``(rule ...)``
|
2017-05-31 09:34:17 +00:00
|
|
|
stanza is rejected by Jbuilder:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
2017-06-01 15:53:55 +00:00
|
|
|
(rule (copy a b.${read:file}))
|
2017-05-31 09:34:17 +00:00
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
ocamllex
|
|
|
|
--------
|
|
|
|
|
|
|
|
``(ocamllex (<names>))`` is essentially a shorthand for:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(rule
|
|
|
|
((targets (<name>.ml))
|
|
|
|
(deps (<name>.mll))
|
|
|
|
(action (chdir ${ROOT} (run ${bin:ocamllex} -q -o ${<})))))
|
|
|
|
|
|
|
|
ocamlyacc
|
|
|
|
---------
|
|
|
|
|
|
|
|
``(ocamlyacc (<names>))`` is essentially a shorthand for:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(rule
|
|
|
|
((targets (<name>.ml <name>.mli))
|
|
|
|
(deps (<name>.mly))
|
|
|
|
(action (chdir ${ROOT} (run ${bin:ocamlyacc} ${<})))))
|
|
|
|
|
|
|
|
menhir
|
|
|
|
------
|
|
|
|
|
|
|
|
The basic form for defining menhir parsers (analogous to ocamlyacc) is:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(menhir
|
|
|
|
((modules (<parser1> <parser2> ...))))
|
|
|
|
|
|
|
|
Modular parsers can be defined by adding a ``merge_into`` field. This correspond
|
|
|
|
to the ``--base`` command line option of ``menhir``. With this option, a single
|
|
|
|
parser named ``base_name`` is generated.
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(menhir
|
|
|
|
((merge_into <base_name>)
|
|
|
|
(modules (<parser1> <parser2> ...))))
|
|
|
|
|
|
|
|
Extra flags can be passed to menhir using the ``flags`` flag:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(menhir
|
|
|
|
((flags (<option1> <option2> ...))
|
|
|
|
(modules (<parser1> <parser2> ...))))
|
2017-05-28 03:25:02 +00:00
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
alias
|
|
|
|
-----
|
|
|
|
|
|
|
|
The ``alias`` stanza lets you add dependencies to an alias, or specify an action
|
|
|
|
to run to construct the alias.
|
|
|
|
|
|
|
|
The syntax is as follows:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(alias
|
|
|
|
((name <alias-name>)
|
|
|
|
(deps (<deps-conf list>))
|
|
|
|
<optional-fields>
|
|
|
|
))
|
|
|
|
|
|
|
|
``<name>`` is an alias name such as ``runtest``.
|
|
|
|
|
|
|
|
``<deps-conf list>`` specifies the dependencies of the alias. See the
|
2017-05-18 20:15:49 +00:00
|
|
|
`Dependency specification`_ section for more details.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
``<optional-fields>`` are:
|
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
- ``<action>``, an action to run when constructing the alias. See the `User
|
|
|
|
actions`_ section for more details.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
- ``(package <name>)`` indicates that this alias stanza is part of package
|
|
|
|
``<name>`` and should be filtered out if ``<name>`` is filtered out from the
|
|
|
|
command line, either with ``--only-packages <pkgs>`` or ``-p <pkgs>``
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
The typical use of the ``alias`` stanza is to define tests:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(alias
|
|
|
|
((name runtest)
|
|
|
|
(action (run ${exe:my-test-program.exe} blah))))
|
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
See the section about :ref:`running-tests` for details.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
Note that if your project contains several packages and you run test the tests
|
|
|
|
from the opam file using a ``build-test`` field, then all your ``runtest`` alias
|
|
|
|
stanzas should have a ``(package ...)`` field in order to partition the set of
|
|
|
|
tests.
|
|
|
|
|
|
|
|
install
|
|
|
|
-------
|
|
|
|
|
|
|
|
The ``install`` stanza is what lets you describe what Jbuilder should install,
|
|
|
|
either when running ``jbuilder install`` or through opam.
|
|
|
|
|
2017-05-30 11:27:20 +00:00
|
|
|
Libraries and executables don't need an ``install`` stanza to be
|
|
|
|
installed, just a ``public_name`` field. Everything else needs an
|
|
|
|
``install`` stanza.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
The syntax is as follows:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(install
|
|
|
|
((section <section>)
|
|
|
|
(files (<filenames>))
|
|
|
|
<optional-fields>
|
|
|
|
))
|
|
|
|
|
|
|
|
``<section>`` is the installation section, as described in the opam
|
|
|
|
manual. The following sections are available:
|
|
|
|
|
|
|
|
- ``lib``
|
|
|
|
- ``libexec``
|
|
|
|
- ``bin``
|
|
|
|
- ``sbin``
|
|
|
|
- ``toplevel``
|
|
|
|
- ``share``
|
|
|
|
- ``share_root``
|
|
|
|
- ``etc``
|
|
|
|
- ``doc``
|
|
|
|
- ``stublibs``
|
|
|
|
- ``man``
|
|
|
|
- ``misc``
|
|
|
|
|
2017-05-30 11:27:20 +00:00
|
|
|
``<files>`` is the list of files to install. Each element in the list
|
|
|
|
must be either a literal filename or a S-expression of the form:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(<filename> as <destination>)
|
|
|
|
|
|
|
|
where ``<destination>`` describe how the file will be installed. For
|
|
|
|
instance, to install a file ``mylib.el`` as
|
|
|
|
``emacs/site-lisp/mylib.el`` in the ``share_root`` section:
|
|
|
|
|
|
|
|
(install
|
|
|
|
((section share_root)
|
|
|
|
(files ((mylib.el as emacs/site-lisp/mylib.el)))))
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
``<optional-fields>`` are:
|
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
- ``(package <name>)``. If there are no ambiguities, you can omit this field.
|
|
|
|
Otherwise you need it to specify which package these files are part of. The
|
|
|
|
package is not ambiguous when the first parent directory to contain a
|
|
|
|
``<package>.opam`` file contains exactly one ``<package>.opam`` file
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-08 08:59:43 +00:00
|
|
|
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
|
|
|
|
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
|
|
|
|
not already present.
|
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
Common items
|
|
|
|
============
|
|
|
|
|
|
|
|
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
|
|
|
|
following rules:
|
|
|
|
|
|
|
|
- ``:standard`` denotes the standard value of the field when it is absent
|
|
|
|
- an atom not starting with a ``:`` is a singleton containing only this atom
|
|
|
|
- a list of sets is the concatenation of its inner sets
|
|
|
|
- ``(<sets1> \ <sets2>)`` is the set composed of elements of ``<sets1>`` that do
|
2017-06-01 15:02:29 +00:00
|
|
|
not appear in ``<sets2>``
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
In addition, some fields support the inclusion of an external file using the
|
|
|
|
syntax ``(:include <filename>)``. This is useful for instance when you need to
|
|
|
|
run a script to figure out some compilation flags. ``<filename>`` is expected to
|
|
|
|
contain a single S-expression and cannot contain ``(:include ...)`` forms.
|
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
Most fields using the ordered set language also support `Variables expansion`_.
|
2017-05-14 00:10:00 +00:00
|
|
|
Variables are expanded after the set language is interpreted.
|
|
|
|
|
|
|
|
Variables expansion
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
Some fields can contains variables of the form ``$(var)`` or ``${var}`` that are
|
|
|
|
expanded by Jbuilder.
|
|
|
|
|
|
|
|
Jbuilder supports the following variables:
|
|
|
|
|
2017-06-09 11:42:33 +00:00
|
|
|
- ``ROOT`` is the relative path to the root of the build
|
|
|
|
context. Note that ``ROOT`` depends on the worksace
|
|
|
|
configuration. As such you shouldn't use ``ROOT`` to denote the
|
|
|
|
root of your project. Use ``SCOPE_ROOT`` instead for this purpose
|
|
|
|
- ``SCOPE_ROOT`` is the root of the current scope. It is typically
|
|
|
|
the toplevel directory of your project and as long as you have at
|
|
|
|
least one ``<package>.opam`` file there, ``SCOPE_ROOT`` is
|
|
|
|
independant of the workspace configuration
|
2017-05-14 00:10:00 +00:00
|
|
|
- ``CC`` is the C compiler command line being used in the current
|
|
|
|
build context
|
|
|
|
- ``CXX`` is the C++ compiler command line being used in the
|
|
|
|
current build context
|
|
|
|
- ``ocaml_bin`` is the path where ``ocamlc`` lives
|
|
|
|
- ``OCAML`` is the ``ocaml`` binary
|
|
|
|
- ``OCAMLC`` is the ``ocamlc`` binary
|
|
|
|
- ``OCAMLOPT`` is the ``ocamlopt`` binary
|
|
|
|
- ``ocaml_version`` is the version of the compiler used in the
|
|
|
|
current build context
|
|
|
|
- ``ocaml_where`` is the output of ``ocamlc -where``
|
|
|
|
- ``ARCH_SIXTYFOUR`` is ``true`` if using a compiler targeting a
|
|
|
|
64 bit architecture and ``false`` otherwise
|
|
|
|
- ``null`` is ``/dev/null`` on Unix or ``nul`` on Windows
|
|
|
|
|
|
|
|
In addition, ``(action ...)`` fields support the following special variables:
|
|
|
|
|
2017-05-30 16:10:50 +00:00
|
|
|
- ``@`` expands to the list of target
|
2017-05-18 20:15:49 +00:00
|
|
|
- ``<`` expands to the first dependency, or the empty string if there are no
|
2017-06-01 15:02:29 +00:00
|
|
|
dependencies
|
|
|
|
- ``^`` expands to the list of dependencies, separated by spaces
|
2017-05-14 00:10:00 +00:00
|
|
|
- ``path:<path>`` expands to ``<path>``
|
2017-05-18 20:15:49 +00:00
|
|
|
- ``exe:<path>`` is the same as ``<path>``, except when cross-compiling, in
|
2017-06-01 15:02:29 +00:00
|
|
|
which case it will expand to ``<path>`` from the host build context
|
2017-06-08 09:37:25 +00:00
|
|
|
- ``bin:<program>`` expands to a path to ``program``. If ``program``
|
|
|
|
is installed by a package in the workspace (see `install`_ stanzas),
|
|
|
|
the locally built binary will be used, otherwise it will be searched
|
|
|
|
in the ``PATH`` of the current build context. Note that ``(run
|
|
|
|
${bin:program} ...)`` and ``(run program ...)`` behave in the same
|
|
|
|
way. ``${bin:...}`` is only necessary when you are using ``(bash
|
|
|
|
...)`` or ``(system ...)``
|
2017-05-18 20:15:49 +00:00
|
|
|
- ``lib:<public-library-name>:<file>`` expands to a path to file ``<file>`` of
|
2017-06-01 15:02:29 +00:00
|
|
|
library ``<public-library-name>``. If ``<public-library-name>`` is available
|
|
|
|
in the current workspace, the local file will be used, otherwise the one from
|
|
|
|
the installed world will be used
|
2017-05-18 20:15:49 +00:00
|
|
|
- ``libexec:<public-library-name>:<file>`` is the same as ``lib:...`` except
|
2017-06-01 15:02:29 +00:00
|
|
|
when cross-compiling, in which case it will expand to the file from the host
|
|
|
|
build context
|
2017-05-18 20:15:49 +00:00
|
|
|
- ``lib-available:<library-name>`` expands to ``true`` or ``false`` depending on
|
2017-06-01 15:02:29 +00:00
|
|
|
wether the library is available or not. A library is available iff at least
|
|
|
|
one of the following condition holds:
|
|
|
|
|
|
|
|
- it is part the installed worlds
|
|
|
|
- it is available locally and is not optional
|
|
|
|
- it is available locally and all its library dependencies are
|
|
|
|
available
|
|
|
|
|
|
|
|
- ``version:<package>`` expands to the version of the given
|
|
|
|
package. Note that this is only supported for packages that are
|
|
|
|
being defined in the current scope
|
|
|
|
- ``read:<path>`` expands to the contents of the given file
|
|
|
|
- ``read-lines:<path>`` expands to the list of lines in the given
|
|
|
|
file
|
|
|
|
- ``read-strings:<path>`` expands to the list of lines in the given
|
|
|
|
file, unescaped using OCaml lexical convention
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
The ``${<kind>:...}`` forms are what allows you to write custom rules that work
|
|
|
|
transparently whether things are installed or not.
|
|
|
|
|
2017-05-29 17:55:39 +00:00
|
|
|
Note that aliases are ignored by both ``${<}`` and ``${^}``.
|
|
|
|
|
2017-05-30 16:10:50 +00:00
|
|
|
The intent of this last form is to reliably read a list of strings
|
|
|
|
generated by an OCaml program via:
|
|
|
|
|
|
|
|
.. code:: ocaml
|
|
|
|
|
|
|
|
List.iter (fun s -> print_string (String.escaped s)) l
|
|
|
|
|
|
|
|
#. Expansion of lists
|
|
|
|
|
|
|
|
Forms that expands to list of items, such as ``${^}``, ``${@}`` or
|
|
|
|
``${read-lines:...}`` will always expand to a single string where
|
|
|
|
elements are separated by spaces. Inside ``(run <prog> <arguments>)``
|
|
|
|
forms you can however split the items as several arguments by
|
|
|
|
prefixing the variable with ``!``. Such forms can only be used as a
|
|
|
|
whole atom, i.e. they can't be used inside a quoted atom.
|
|
|
|
|
|
|
|
For instance in:
|
2017-05-29 18:12:37 +00:00
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(run foo ${^})
|
|
|
|
|
|
|
|
even if there are two dependencies ``a`` and ``b``, the produced
|
|
|
|
command will be equivalent to the shell command:
|
|
|
|
|
|
|
|
.. code:: shell
|
|
|
|
|
|
|
|
$ foo "a b"
|
|
|
|
|
2017-05-30 16:10:50 +00:00
|
|
|
However, if you replace ``${^}`` by ``${!^}`` in the previous example
|
|
|
|
the command produced would be equivalent to this shell command:
|
2017-05-29 18:12:37 +00:00
|
|
|
|
|
|
|
.. code:: shell
|
|
|
|
|
|
|
|
$ foo "a" "b"
|
|
|
|
|
|
|
|
You can also use ``${!^}`` as program name, for instance:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(rule
|
|
|
|
((targets (result.txt))
|
|
|
|
(deps (foo.exe (glob_files *.txt)))
|
|
|
|
(action (run ${!^}))))
|
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
Library dependencies
|
|
|
|
--------------------
|
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
Dependencies on libraries are specified using ``(libraries ...)`` fields in
|
|
|
|
``library`` and ``executables`` stanzas.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
For libraries that are present in the workspace, you can use either the real
|
|
|
|
name (with some restrictions, see below) or the public name. For libraries that
|
|
|
|
are part of the installed world, you need to use the public name. For instance:
|
2017-05-14 00:10:00 +00:00
|
|
|
``(libraries (base re))``.
|
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
When resolving libraries, libraries that are part of the workspace are always
|
|
|
|
prefered to ones that are part of the installed world.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
.. _alternative-deps:
|
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
Alternative dependencies
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
In addition to direct dependencies you can specify alternative dependencies.
|
|
|
|
This is described in the :ref:`Alternative dependencies <alternative-deps>`
|
|
|
|
section
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
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.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
Jbuilder allows this by using a ``(select ... from ...)`` form inside the list
|
|
|
|
of library dependencies.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
Select forms are specified as follows:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
.. code:: scheme
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
(select <target-filename> from
|
2017-06-05 15:16:49 +00:00
|
|
|
(<literals> -> <filename>)
|
|
|
|
(<literals> -> <filename>)
|
|
|
|
...)
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
``<literals>`` are lists of literals, where each literal is one of:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
- ``<library-name>``, which will evaluate to true if ``<library-name>`` is
|
|
|
|
available, either in the workspace or in the installed world
|
|
|
|
- ``!<library-name>``, which will evaluate to true if ``<library-name>`` is not
|
|
|
|
available in the workspace or in the installed world
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
When evaluating a select form, Jbuilder will create ``<target-filename>`` by
|
|
|
|
copying the file given by the first ``(<literals> -> <filename>)`` 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 ``(->
|
|
|
|
<file>)`` at the end of the list.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
Preprocessing specification
|
|
|
|
---------------------------
|
|
|
|
|
|
|
|
Jbuilder accepts three kinds of preprocessing:
|
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
- ``no_preprocessing``, meaning that files are given as it to the compiler, this
|
|
|
|
is the default
|
|
|
|
- ``(action <action>)`` to preprocess files using the given action
|
|
|
|
- ``(pps (<ppx-rewriters-and-flags>))`` to preprocess files using the given list
|
|
|
|
of ppx rewriters
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
Note that in any cases, files are preprocessed only once. Jbuilder doesn't use
|
|
|
|
the ``-pp`` or ``-ppx`` of the various OCaml tools.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
Preprocessing with actions
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
``<action>`` uses the same DSL as described in the `User actions`_ section, and
|
|
|
|
for the same reason given in that section, it will be executed from the root of
|
|
|
|
the current build context. It is expected to be an action that reads the file
|
|
|
|
given as only dependency and outputs the preprocessed file on its standard
|
|
|
|
output.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
More precisely, ``(preprocess (action <action>))`` acts as if
|
|
|
|
you had setup a rule for every file of the form:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(rule
|
|
|
|
((targets (file.pp.ml))
|
|
|
|
(deps (file.ml))
|
|
|
|
(action (with-stdout-to ${@} (chdir ${ROOT} <action>)))))
|
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
The equivalent of a ``-pp <command>`` option passed to the OCaml compiler is
|
|
|
|
``(system "<command> ${<}")``.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
Preprocessing with ppx rewriters
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
``<ppx-rewriters-and-flags>`` is expected to be a list where each element is
|
|
|
|
either a command line flag if starting with a ``-`` or the name of a library.
|
|
|
|
Additionnally, any sub-list will be treated as a list of command line arguments.
|
|
|
|
So for instance from the following ``preprocess`` field:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(preprocess (pps (ppx1 -foo ppx2 (-bar 42))))
|
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
The list of libraries will be ``ppx1`` and ``ppx2`` and the command line
|
|
|
|
arguments will be: ``-foo -bar 42``.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
Libraries listed here should be libraries implementing an OCaml AST rewriter and
|
|
|
|
registering themselves using the `ocaml-migrate-parsetree.driver API
|
|
|
|
<https://github.com/let-def/ocaml-migrate-parsetree>`__.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
Jbuilder 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 ...)``
|
|
|
|
field is set to ``ppx_rewriter`` or ``ppx_deriver``.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
It is guaranteed that the last library in the list will be linked last. You can
|
|
|
|
use this feature to use a custom ppx driver. By default Jbuilder will use
|
|
|
|
``ocaml-migrate-parsetree.driver-main``. See the section about
|
|
|
|
:ref:`custom-driver` for more details.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
Per module preprocessing specification
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
By default a preprocessing specification will apply to all modules in the
|
|
|
|
library/set of executables. It is possible to select the preprocessing on a
|
|
|
|
module-by-module basis by using the following syntax:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
.. code:: scheme
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-02 16:58:20 +00:00
|
|
|
(preprocess (per_module
|
2017-06-01 15:02:29 +00:00
|
|
|
(<spec1> (<module-list1>))
|
|
|
|
(<spec2> (<module-list2>))
|
|
|
|
...))
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-02 16:58:20 +00:00
|
|
|
Where ``<spec1>``, ``<spec2>``, ... are preprocessing specifications
|
|
|
|
and ``<module-list1>``, ``<module-list2>``, ... are list of module
|
|
|
|
names.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
For instance:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
.. code:: scheme
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-02 16:58:20 +00:00
|
|
|
(preprocess (per_module
|
2017-06-01 15:02:29 +00:00
|
|
|
(((action (run ./pp.sh X=1 ${<})) (foo bar)))
|
|
|
|
(((action (run ./pp.sh X=2 ${<})) (baz)))))
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-02 16:58:20 +00:00
|
|
|
Note the beta versions of Jbuilder used ``per_file`` instead of
|
|
|
|
``per_module``, which was obviously the wrong name. ``per_file`` is
|
|
|
|
still accepted for backward compatibility but deprecated. It will be
|
|
|
|
re-purposed in the future to allow to distinguish between .ml and .mli
|
|
|
|
files.
|
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
Dependency specification
|
|
|
|
------------------------
|
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
Dependencies in ``jbuild`` files can be specified using one of the following
|
|
|
|
syntax:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
- ``(file <filename>)`` or simply ``<filename>``: depend on this file
|
|
|
|
- ``(alias <alias-name>)``: depend on the construction of this alias, for
|
2017-06-01 15:02:29 +00:00
|
|
|
instance: ``(alias src/runtest)``
|
2017-05-18 20:15:49 +00:00
|
|
|
- ``(glob_files <glob>)``: depend on all files matched by ``<glob>``, see the
|
2017-06-01 15:02:29 +00:00
|
|
|
:ref:`glob <glob>` for details
|
2017-05-18 20:15:49 +00:00
|
|
|
- ``(files_recursively_in <dir>)``: depend on all files in the subtree with root
|
2017-06-01 15:02:29 +00:00
|
|
|
``<dir>``
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
In all these cases, the argument supports `Variables expansion`_.
|
|
|
|
|
|
|
|
.. _glob:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
Glob
|
|
|
|
~~~~
|
|
|
|
|
|
|
|
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
|
|
|
|
particular the glob is interpreted as follows:
|
|
|
|
|
|
|
|
- anything before the last ``/`` is taken as a literal path
|
|
|
|
- anything after the last ``/``, or everything if the glob contains no ``/``, is
|
|
|
|
interpreted using the glob syntax
|
|
|
|
|
|
|
|
The glob syntax is interpreted as follows:
|
|
|
|
|
|
|
|
- ``\<char>`` matches exactly ``<char>``, even if it is a special character
|
|
|
|
(``*``, ``?``, ...)
|
|
|
|
- ``*`` matches any sequence of characters, except if it comes first in which
|
|
|
|
case it matches any character that is not ``.`` followed by anything
|
|
|
|
- ``**`` matches any character that is not ``.`` followed by anything, except if
|
|
|
|
it comes first in which case it matches anything
|
|
|
|
- ``?`` matches any single character
|
|
|
|
- ``[<set>]`` matches any character that is part of ``<set>``
|
|
|
|
- ``[!<set>]`` matches any character that is not part of ``<set>``
|
|
|
|
- ``{<glob1>,<glob2>,...,<globn>}`` matches any string that is matched by one of
|
|
|
|
``<glob1>``, ``<glob2>``, ...
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
OCaml flags
|
|
|
|
-----------
|
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
In ``library`` and ``executables`` stanzas, you can specify OCaml compilation
|
|
|
|
flags using the following fields:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
- ``(flags <flags>)`` to specify flags passed to both ``ocamlc`` and
|
|
|
|
``ocamlopt``
|
|
|
|
- ``(ocamlc_flags <flags>)`` to specify flags passed to ``ocamlc`` only
|
|
|
|
- ``(ocamlopt_flags <flags>)`` to specify flags passed to ``ocamlopt`` only
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
For all these fields, ``<flags>`` is specified in the `Ordered set language`_.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
The default value for ``(flags ...)`` includes some ``-w`` options to set
|
|
|
|
warnings. The exact set depends on whether ``--dev`` is passed to Jbuilder. As a
|
|
|
|
result it is recommended to write ``(flags ...)`` fields as follows:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
(flags (:standard <my options>))
|
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
.. _jbuild-jsoo:
|
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
js_of_ocaml
|
|
|
|
-----------
|
|
|
|
|
|
|
|
In ``library`` and ``executables`` stanzas, you can specify js_of_ocaml options
|
|
|
|
using ``(js_of_ocaml (<js_of_ocaml-options>))``.
|
|
|
|
|
|
|
|
``<js_of_ocaml-options>`` are all optional:
|
|
|
|
|
2017-06-01 15:02:29 +00:00
|
|
|
- ``(flags <flags>)`` to specify flags passed to ``js_of_ocaml``
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
- ``(javascript_files (<files-list>))`` to specify ``js_of_ocaml`` JavaScript
|
2017-06-01 15:02:29 +00:00
|
|
|
runtime files.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
=<flags>= is specified in the `Ordered set language`_.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
The default value for ``(flags ...)`` depends on whether ``--dev`` is passed to
|
|
|
|
Jbuilder. ``--dev`` will enable sourcemap and the pretty JavaScript output.
|
|
|
|
|
|
|
|
User actions
|
|
|
|
------------
|
|
|
|
|
|
|
|
``(action ...)`` fields describe user actions.
|
|
|
|
|
|
|
|
User actions are always run from the same subdirectory of the current build
|
|
|
|
context as the jbuild they are defined in. So for instance an action defined in
|
|
|
|
``src/foo/jbuild`` will be run from ``_build/<context>/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
|
2017-05-18 20:15:49 +00:00
|
|
|
support `Variables expansion`_. Moreover, you don't need to specify dependencies
|
2017-05-14 00:10:00 +00:00
|
|
|
explicitly for the special ``${<kind>:...}`` forms, these are recognized and
|
|
|
|
automatically handled by Jbuilder.
|
|
|
|
|
|
|
|
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.
|
|
|
|
You can use `shexp <https://github.com/janestreet/shexp>`__ to write portable
|
|
|
|
scripts or `configurator <https://github.com/janestreet/configurator>`__ for
|
|
|
|
configuration related tasks.
|
|
|
|
|
|
|
|
The following constructions are available:
|
|
|
|
|
2017-06-08 09:37:25 +00:00
|
|
|
- ``(run <prog> <args>)`` to execute a program. ``<prog>`` is resolved
|
|
|
|
locally if it is available in the current workspace, otherwise it is
|
|
|
|
resolved using the ``PATH``
|
2017-06-01 15:02:29 +00:00
|
|
|
- ``(chdir <dir> <DSL>)`` to change the current directory
|
|
|
|
- ``(setenv <var> <value> <DSL>)`` to set an environment variable
|
2017-05-14 00:10:00 +00:00
|
|
|
- ``(with-<outputs>-to <file> <DSL>)`` to redirect the output to a file, where
|
2017-06-01 15:02:29 +00:00
|
|
|
``<outputs>`` is one of: ``stdout``, ``stderr`` or ``outputs`` (for both
|
|
|
|
``stdout`` and ``stderr``)
|
|
|
|
- ``(ignore-<outputs> <DSL)`` to ignore the output, where
|
|
|
|
``<outputs>`` is one of: ``stdout``, ``stderr`` or ``outputs``
|
|
|
|
- ``(progn <DSL>...)`` to execute several commands in sequence
|
|
|
|
- ``(echo <string>)`` to output a string on stdout
|
|
|
|
- ``(cat <file>)`` to print the contents of a file to stdout
|
|
|
|
- ``(copy <src> <dst>)`` to copy a file
|
2017-06-05 11:10:39 +00:00
|
|
|
- ``(copy# <src> <dst>)`` to copy a file and add a line directive at
|
|
|
|
the beginning
|
2017-05-14 00:10:00 +00:00
|
|
|
- ``(system <cmd>)`` to execute a command using the system shell: ``sh`` on Unix
|
2017-06-01 15:02:29 +00:00
|
|
|
and ``cmd`` on Windows
|
2017-05-14 00:10:00 +00:00
|
|
|
- ``(bash <cmd>)`` to execute a command using ``/bin/bash``. This is obviously
|
2017-06-01 15:02:29 +00:00
|
|
|
not very portable
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-06-05 11:10:39 +00:00
|
|
|
As mentioned ``copy#`` inserts a line directive at the beginning of
|
|
|
|
the destination file. More precisely, it inserts the following line:
|
|
|
|
|
|
|
|
.. code:: ocaml
|
|
|
|
|
|
|
|
# 1 "<source file name>"
|
|
|
|
|
|
|
|
Most languages recognize such lines and update their current location,
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
Note: expansion of the special ``${<kind>:...}`` is done relative to the current
|
|
|
|
working directory of the part of the DSL being executed. So for instance if you
|
|
|
|
have this action in a ``src/foo/jbuild``:
|
|
|
|
|
|
|
|
.. code:: scheme
|
|
|
|
|
|
|
|
(action (chdir ../../.. (echo ${path:jbuild})))
|
|
|
|
|
|
|
|
Then ``${path:jbuild}`` will expand to ``src/foo/jbuild``. When you run various
|
|
|
|
tools, they often use the filename given on the command line in error messages.
|
|
|
|
As a result, if you execute the command from the original directory, it will
|
|
|
|
only see the basename.
|
|
|
|
|
|
|
|
To understand why this is important, let's consider this jbuild living in
|
|
|
|
``src/foo``:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
(rule
|
|
|
|
((targets (blah.ml))
|
|
|
|
(deps (blah.mll))
|
|
|
|
(action (run ocamllex -o ${@} ${<}))))
|
|
|
|
|
|
|
|
Here the command that will be executed is:
|
|
|
|
|
|
|
|
.. code:: bash
|
|
|
|
|
|
|
|
ocamllex -o blah.ml blah.mll
|
|
|
|
|
|
|
|
And it will be executed in ``_build/<context>/src/foo``. As a result, if there
|
|
|
|
is an error in the generated ``blah.ml`` file it will be reported as:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
File "blah.ml", line 42, characters 5-10:
|
|
|
|
Error: ...
|
|
|
|
|
|
|
|
Which can be a problem as you editor might think that ``blah.ml`` is at the root
|
|
|
|
of your project. What you should write instead is:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
(rule
|
|
|
|
((targets (blah.ml))
|
|
|
|
(deps (blah.mll))
|
|
|
|
(action (chdir ${ROOT} (run ocamllex -o ${@} ${<})))))
|
|
|
|
|
2017-05-18 20:15:49 +00:00
|
|
|
.. _ocaml-syntax:
|
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
OCaml syntax
|
|
|
|
============
|
|
|
|
|
|
|
|
If a ``jbuild`` file starts with ``(* -*- tuareg -*- *)``, then it is
|
|
|
|
interpreted as an OCaml script that generates the ``jbuild`` file as described
|
|
|
|
in the rest of this section. The code in the script will have access to a
|
|
|
|
`Jbuild_plugin
|
|
|
|
<https://github.com/janestreet/jbuilder/blob/master/plugin/jbuild_plugin.mli>`__
|
|
|
|
module containing details about the build context it is executed in.
|
|
|
|
|
2017-06-06 09:23:22 +00:00
|
|
|
The OCaml syntax gives you an escape hatch for when the S-expression
|
|
|
|
syntax is not enough. It is not clear whether the OCaml syntax will be
|
|
|
|
supported in the long term as it doesn't work well with incremental
|
|
|
|
builds. It is possible that it will be replaced by just an ``include``
|
|
|
|
stanza where one can include a generated file.
|
2017-06-08 10:33:59 +00:00
|
|
|
|
|
|
|
Consequently **you must not** build complex systems based on it.
|