Doc tweaks (#112)
* Fix a link and some typos * Fix some crappy formatting introduced by the pandoc conversion. * Use more subheadings rather than points.
This commit is contained in:
Rudi Grinberg
Jérémie Dimino
parent
827aac0e43
commit
f98072deb7
624
doc/jbuild.rst
624
doc/jbuild.rst
|
|
@ -62,120 +62,115 @@ modules you want.
|
|||
``<optional-fields>`` are:
|
||||
|
||||
- ``(public_name <name>)`` this is the name under which the library can be
|
||||
referred to as a dependency when it is not part of the current workspace,
|
||||
i.e. when it is installed. Without a ``(public_name ...)`` field, the library
|
||||
will not be installed by Jbuilder. The public name must start by the package
|
||||
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`
|
||||
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`
|
||||
|
||||
- ``(synopsis <string>)`` should give a one-line description of the library.
|
||||
This is used by tools that list installed libraries
|
||||
This is used by tools that list installed libraries
|
||||
|
||||
- ``(modules <modules>)`` specifies what modules are part of the library. By
|
||||
default Jbuilder will use all the .ml/.re files in the same directory as the
|
||||
``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))``
|
||||
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))``
|
||||
|
||||
- ``(libraries (<library-dependencies>))`` is used to specify the dependencies
|
||||
of the library. See the section about `Library dependencies`_ for more
|
||||
details
|
||||
of the library. See the section about `Library dependencies`_ for more details
|
||||
|
||||
- ``(wrapped <boolean>)`` specifies whether the modules of the library should be
|
||||
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
|
||||
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
|
||||
|
||||
- ``(preprocess <preprocess-spec>)`` specifies how to preprocess files if
|
||||
needed. The default is ``no_processing``. Other options are described in the
|
||||
`Preprocessing specification`_ section
|
||||
needed. The default is ``no_processing``. Other options are described in the
|
||||
`Preprocessing specification`_ section
|
||||
|
||||
- ``(preprocessor_deps (<deps-conf list>))`` specifies extra dependencies of the
|
||||
preprocessor, for instance if the preprocessor reads a generated file. The
|
||||
specification of dependencies is described in the `Dependency specification`_
|
||||
section
|
||||
preprocessor, for instance if the preprocessor reads a generated file. The
|
||||
specification of dependencies is described in the `Dependency specification`_
|
||||
section
|
||||
|
||||
- ``(optional)``, if present it indicates that the library should only be built
|
||||
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
|
||||
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
|
||||
|
||||
- ``(c_names (<names>))``, if your library has stubs, you must list the C files
|
||||
in this field, without the ``.c`` extension
|
||||
in this field, without the ``.c`` extension
|
||||
|
||||
- ``(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
|
||||
that must be installed, you must list them in this field, with the ``.h``
|
||||
extension
|
||||
that must be installed, you must list them in this field, with the ``.h``
|
||||
extension
|
||||
|
||||
- ``(modes (<modes>))`` modes (``byte`` and ``native``) which should be built by
|
||||
default. This is only useful when writing libraries for the OCaml toplevel
|
||||
default. This is only useful when writing libraries for the OCaml toplevel
|
||||
|
||||
- ``(no_dynlink)`` is to disable dynamic linking of the library. This is for
|
||||
advanced use only, by default you shouldn't set this option
|
||||
advanced use only, by default you shouldn't set this option
|
||||
|
||||
- ``(kind <kind>)`` is the kind of the library. The default is ``normal``, other
|
||||
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
|
||||
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
|
||||
|
||||
- ``(ppx_runtime_libraries (<library-names>))`` is for when the library is a ppx
|
||||
rewriter or a ``[@@deriving ...]`` plugin and has runtime dependencies. You
|
||||
need to specify these runtime dependencies here
|
||||
rewriter or a ``[@@deriving ...]`` plugin and has runtime dependencies. You
|
||||
need to specify these runtime dependencies here
|
||||
|
||||
- ``(virtual_deps (<opam-packages>)``. Sometimes opam packages enable a specific
|
||||
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
|
||||
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
|
||||
|
||||
- ``js_of_ocaml``. See the section about :ref:`jbuild-jsoo`
|
||||
- ``js_of_ocaml``. See the section about :ref:`jbuild-jsoo`
|
||||
|
||||
- ``flags``, ``ocamlc_flags`` and ``ocamlopt_flags``. See the section about
|
||||
`OCaml flags`_
|
||||
`OCaml flags`_
|
||||
|
||||
- ``(library_flags (<flags>))`` is a list of flags that are passed as it to
|
||||
``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`_
|
||||
``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`_
|
||||
|
||||
- ``(c_flags <flags>)`` specifies the compilation flags for C stubs,
|
||||
using the `Ordered set language`_. This field supports
|
||||
``(:include ...)`` forms
|
||||
- ``(c_flags <flags>)`` specifies the compilation flags for C stubs, using the
|
||||
`Ordered set language`_. This field supports ``(:include ...)`` forms
|
||||
|
||||
- ``(cxx_flags <flags>)`` is the same as ``c_flags`` but for C++
|
||||
stubs
|
||||
- ``(cxx_flags <flags>)`` is the same as ``c_flags`` but for C++ stubs
|
||||
|
||||
- ``(c_library_flags <flags>)`` specifies the flags to pass to the C compiler
|
||||
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
|
||||
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
|
||||
|
||||
- ``(self_build_stubs_archive <c-libname>)`` indicates to Jbuilder that the
|
||||
library has stubs, but that the stubs are built manually. The aim of the
|
||||
field is to embed a library written in foreign language and/or building with
|
||||
another build system. It is not for casual uses, see the `re2 library
|
||||
<https://github.com/janestreet/re2>`__ for an example of use
|
||||
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 ...))``.
|
||||
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 ...))``.
|
||||
|
||||
executable
|
||||
----------
|
||||
|
|
@ -198,21 +193,21 @@ need to specify the entry point. Given an ``executable`` stanza with ``(name
|
|||
bytecode executable which requires ``ocamlrun`` to run and ``<name>.bc.js`` is a
|
||||
JavaScript generated using js_of_ocaml.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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``.
|
||||
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``.
|
||||
|
||||
``<optional-fields>`` are:
|
||||
0
|
||||
- ``(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:
|
||||
|
||||
- ``(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:
|
||||
|
||||
.. code:: scheme
|
||||
|
||||
|
|
@ -220,30 +215,29 @@ or when there is a ``(modes (...))`` field not listing ``native``.
|
|||
((section bin)
|
||||
(files ((<name>.exe as <public-name>)))))
|
||||
|
||||
- ``(package <package>)`` if there is a ``(public_name ...)`` field,
|
||||
this specifies the package the executables are part of
|
||||
- ``(package <package>)`` if there is a ``(public_name ...)`` field, this
|
||||
specifies the package the executables are part of
|
||||
|
||||
- ``(libraries (<library-dependencies>))`` specifies the library dependencies.
|
||||
See the section about `Library dependencies`_ for more details
|
||||
See the section about `Library dependencies`_ for more details
|
||||
|
||||
- ``(modules <modules>)`` specifies which modules in the current directory
|
||||
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`_
|
||||
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`_
|
||||
|
||||
- ``(modes (<modes>))`` modes (``byte`` and ``native``) which should be built by
|
||||
default. If the stanza has a ``(public_name ...)`` field and
|
||||
``native`` is not listed here, the byte-code version will be
|
||||
installed instead.
|
||||
default. If the stanza has a ``(public_name ...)`` field and ``native`` is not
|
||||
listed here, the byte-code version will be installed instead.
|
||||
|
||||
- ``(preprocess <preprocess-spec>)`` is the same as the ``(preprocess ...)``
|
||||
field of `library`_
|
||||
field of `library`_
|
||||
|
||||
- ``(preprocessor_deps (<deps-conf list>))`` is the same as the
|
||||
``(preprocessor_deps ...)`` field of `library`_
|
||||
``(preprocessor_deps ...)`` field of `library`_
|
||||
|
||||
- ``js_of_ocaml``. See the section about `js_of_ocaml`_
|
||||
- ``js_of_ocaml``. See the section about `js_of_ocaml`_
|
||||
|
||||
- ``flags``, ``ocamlc_flags`` and ``ocamlopt_flags``. See the section about
|
||||
specifying `OCaml flags`_
|
||||
|
|
@ -251,28 +245,26 @@ or when there is a ``(modes (...))`` field not listing ``native``.
|
|||
executables
|
||||
-----------
|
||||
|
||||
The ``executables`` stanza is the same as the ``executable`` stanza,
|
||||
except that it is used to describe several executables sharing the
|
||||
same configuration.
|
||||
The ``executables`` stanza is the same as the ``executable`` stanza, except that
|
||||
it is used to describe several executables sharing the same configuration.
|
||||
|
||||
It shares the same fields as the ``executable`` stanza, except that
|
||||
instead of ``(name ...)`` and ``(public_name ...)`` you must use:
|
||||
It shares the same fields as the ``executable`` stanza, except that instead of
|
||||
``(name ...)`` and ``(public_name ...)`` you must use:
|
||||
|
||||
- ``(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
|
||||
- ``(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
|
||||
|
||||
- ``(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
|
||||
- ``(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
|
||||
|
||||
rule
|
||||
----
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
The syntax is as follows:
|
||||
|
||||
|
|
@ -283,8 +275,8 @@ The syntax is as follows:
|
|||
(deps (<deps-conf list>))
|
||||
(action <action>)))
|
||||
|
||||
``<filenames>`` is a list of file names. Note that currently Jbuilder
|
||||
only support user rules with targets in the current directory.
|
||||
``<filenames>`` is a list of file names. Note that currently Jbuilder only
|
||||
support user rules with targets in the current directory.
|
||||
|
||||
``<deps-conf list>`` specifies the dependencies of the rule. See the `Dependency
|
||||
specification`_ section for more details.
|
||||
|
|
@ -292,10 +284,9 @@ specification`_ section for more details.
|
|||
``<action>`` is the action to run to produce the targets from the dependencies.
|
||||
See the `User actions`_ section for more details.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
do (inferred rules)
|
||||
-------------------
|
||||
|
|
@ -405,18 +396,16 @@ More precisely, given a stanza ``(ml_of_mli (foo))`` the following
|
|||
(* contents of foo.mli *)
|
||||
end = Foo
|
||||
|
||||
If you have a ``.mli`` file containing only type declarations, this
|
||||
allows you to automatically produce the corresponding
|
||||
implementation.
|
||||
If you have a ``.mli`` file containing only type declarations, this allows you
|
||||
to automatically produce the corresponding implementation.
|
||||
|
||||
Note that if the ``.mli`` file does contain a value declaration, the
|
||||
compilation of the generated ``.ml`` file will fail with an error
|
||||
about recursive module. In particular declaring an exception or
|
||||
extension constructor implicitely declares a value. The error won't be
|
||||
precide because the compiler doesn't support checking that a mli file
|
||||
doesn't contain value declaration. See ``this ticket
|
||||
<https://github.com/janestreet/jbuilder/issues/9>``__ for a discussion
|
||||
about these issues.
|
||||
Note that if the ``.mli`` file does contain a value declaration, the compilation
|
||||
of the generated ``.ml`` file will fail with an error about recursive module. In
|
||||
particular declaring an exception or extension constructor implicitely declares
|
||||
a value. The error won't be precide because the compiler doesn't support
|
||||
checking that a mli file doesn't contain value declaration. See `this ticket
|
||||
<https://github.com/janestreet/jbuilder/issues/9>`__ for a discussion about
|
||||
these issues.
|
||||
|
||||
alias
|
||||
-----
|
||||
|
|
@ -441,13 +430,12 @@ The syntax is as follows:
|
|||
|
||||
``<optional-fields>`` are:
|
||||
|
||||
- ``<action>``, an action to run when constructing the alias. See
|
||||
the `User actions`_ section for more details.
|
||||
- ``<action>``, an action to run when constructing the alias. See the `User
|
||||
actions`_ section for more details.
|
||||
|
||||
- ``(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>``
|
||||
- ``(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>``
|
||||
|
||||
The typical use of the ``alias`` stanza is to define tests:
|
||||
|
||||
|
|
@ -517,11 +505,10 @@ instance, to install a file ``mylib.el`` as
|
|||
|
||||
``<optional-fields>`` are:
|
||||
|
||||
- ``(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
|
||||
- ``(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
|
||||
|
||||
Common items
|
||||
============
|
||||
|
|
@ -539,7 +526,7 @@ following rules:
|
|||
- 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
|
||||
not appear in ``<sets2>``
|
||||
not appear in ``<sets2>``
|
||||
|
||||
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
|
||||
|
|
@ -577,38 +564,39 @@ In addition, ``(action ...)`` fields support the following special variables:
|
|||
|
||||
- ``@`` expands to the list of target
|
||||
- ``<`` expands to the first dependency, or the empty string if there are no
|
||||
dependencies
|
||||
- ``^`` expands to the list of dependencies
|
||||
dependencies
|
||||
- ``^`` expands to the list of dependencies, separated by spaces
|
||||
- ``path:<path>`` expands to ``<path>``
|
||||
- ``exe:<path>`` is the same as ``<path>``, except when cross-compiling, in
|
||||
which case it will expand to ``<path>`` from the host build context
|
||||
which case it will expand to ``<path>`` from the host build context
|
||||
- ``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
|
||||
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
|
||||
- ``lib:<public-library-name>:<file>`` expands to a path to file ``<file>`` of
|
||||
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
|
||||
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
|
||||
- ``libexec:<public-library-name>:<file>`` is the same as ``lib:...`` except
|
||||
when cross-compiling, in which case it will expand to the file from the host
|
||||
build context
|
||||
when cross-compiling, in which case it will expand to the file from the host
|
||||
build context
|
||||
- ``lib-available:<library-name>`` expands to ``true`` or ``false`` depending on
|
||||
wether the library is available or not. A library is available iff at least
|
||||
one of the following condition holds:
|
||||
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
|
||||
- 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
|
||||
|
||||
The ``${<kind>:...}`` forms are what allows you to write custom rules that work
|
||||
transparently whether things are installed or not.
|
||||
|
|
@ -674,89 +662,87 @@ are part of the installed world, you need to use the public name. For instance:
|
|||
When resolving libraries, libraries that are part of the workspace are always
|
||||
prefered to ones that are part of the installed world.
|
||||
|
||||
#. Scope of internal library names
|
||||
Scope of internal library names
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The scope of internal library names is not the whole workspace. It is
|
||||
restricted to the subtree starting from the closest parent containing a
|
||||
``<package>.opam`` file, or the whole workspace if no such directory exist.
|
||||
Moreover, a subtree containing ``<package>.opam`` doesn' t inherit the
|
||||
internal names available in its parent scope.
|
||||
The scope of internal library names is not the whole workspace. It is restricted
|
||||
to the subtree starting from the closest parent containing a ``<package>.opam``
|
||||
file, or the whole workspace if no such directory exist. Moreover, a subtree
|
||||
containing ``<package>.opam`` doesn' t inherit the internal names available in
|
||||
its parent scope.
|
||||
|
||||
The idea behing this rule is that public library names must be universally
|
||||
unique, but internal ones don't need to. In particular you might have private
|
||||
libraries that are only used for tests or building an executable.
|
||||
The idea behing this rule is that public library names must be universally
|
||||
unique, but internal ones don't need to. In particular you might have private
|
||||
libraries that are only used for tests or building an executable.
|
||||
|
||||
As a result, when you create a workspace including several projects there
|
||||
might be a name clash between internal library names.
|
||||
As a result, when you create a workspace including several projects there might
|
||||
be a name clash between internal library names.
|
||||
|
||||
This scoping rule ensure that this won't be a problem.
|
||||
This scoping rule ensure that this won't be a problem.
|
||||
|
||||
.. _alternative-deps:
|
||||
|
||||
#. Alternative dependencies
|
||||
Alternative dependencies
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In addition to direct dependencies you can specify alternative dependencies.
|
||||
This is described in the :ref:`Alternative dependencies <alternative-deps>`
|
||||
section
|
||||
In addition to direct dependencies you can specify alternative dependencies.
|
||||
This is described in the :ref:`Alternative dependencies <alternative-deps>`
|
||||
section
|
||||
|
||||
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.
|
||||
It is sometimes the case that one wants to not depend on a specific library, but
|
||||
instead on whatever is already installed. For instance to use a different
|
||||
backend depending on the target.
|
||||
|
||||
Jbuilder allows this by using a ``(select ... from ...)`` form inside the
|
||||
list of library dependencies.
|
||||
Jbuilder allows this by using a ``(select ... from ...)`` form inside the list
|
||||
of library dependencies.
|
||||
|
||||
Select forms are specified as follows:
|
||||
Select forms are specified as follows:
|
||||
|
||||
.. code:: scheme
|
||||
.. code:: scheme
|
||||
|
||||
(select <target-filename> from
|
||||
((<literals> -> <filename>)
|
||||
(<literals> -> <filename>)
|
||||
...))
|
||||
(select <target-filename> from
|
||||
((<literals> -> <filename>)
|
||||
(<literals> -> <filename>)
|
||||
...))
|
||||
|
||||
``<literals>`` are lists of literals, where each literal is one
|
||||
of:
|
||||
``<literals>`` are lists of literals, where each literal is one of:
|
||||
|
||||
- ``<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
|
||||
- ``<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
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Preprocessing specification
|
||||
---------------------------
|
||||
|
||||
Jbuilder accepts three kinds of preprocessing:
|
||||
|
||||
- ``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
|
||||
- ``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
|
||||
|
||||
Note that in any cases, files are preprocessed only once. Jbuilder
|
||||
doesn't use the ``-pp`` or ``-ppx`` of the various OCaml tools.
|
||||
Note that in any cases, files are preprocessed only once. Jbuilder doesn't use
|
||||
the ``-pp`` or ``-ppx`` of the various OCaml tools.
|
||||
|
||||
#. Preprocessing with actions
|
||||
Preprocessing with actions
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
``<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.
|
||||
``<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.
|
||||
|
||||
More precisely, ``(preprocess (action <action>))`` acts as if
|
||||
you had setup a rule for every file of the form:
|
||||
More precisely, ``(preprocess (action <action>))`` acts as if
|
||||
you had setup a rule for every file of the form:
|
||||
|
||||
.. code:: scheme
|
||||
|
||||
|
|
@ -765,135 +751,127 @@ doesn't use the ``-pp`` or ``-ppx`` of the various OCaml tools.
|
|||
(deps (file.ml))
|
||||
(action (with-stdout-to ${@} (chdir ${ROOT} <action>)))))
|
||||
|
||||
The equivalent of a ``-pp <command>`` option passed to the
|
||||
OCaml compiler is ``(system "<command> ${<}")``.
|
||||
The equivalent of a ``-pp <command>`` option passed to the OCaml compiler is
|
||||
``(system "<command> ${<}")``.
|
||||
|
||||
#. Preprocessing with ppx rewriters
|
||||
Preprocessing with ppx rewriters
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
``<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:
|
||||
``<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:
|
||||
|
||||
.. code:: scheme
|
||||
|
||||
(preprocess (pps (ppx1 -foo ppx2 (-bar 42))))
|
||||
|
||||
The list of libraries will be ``ppx1`` and ``ppx2`` and the
|
||||
command line arguments will be: ``-foo -bar 42``.
|
||||
The list of libraries will be ``ppx1`` and ``ppx2`` and the command line
|
||||
arguments will be: ``-foo -bar 42``.
|
||||
|
||||
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>`__.
|
||||
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>`__.
|
||||
|
||||
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``.
|
||||
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``.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
#. Per module preprocessing specification
|
||||
Per module preprocessing specification
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
.. code:: scheme
|
||||
.. code:: scheme
|
||||
|
||||
(preprocess (per_file
|
||||
(<spec1> (<module-list1>))
|
||||
(<spec2> (<module-list2>))
|
||||
...))
|
||||
(preprocess (per_file
|
||||
(<spec1> (<module-list1>))
|
||||
(<spec2> (<module-list2>))
|
||||
...))
|
||||
|
||||
Where ``<spec1>``, ``<spec2>``, ... are preprocessing
|
||||
specifications and ``<module-list1>``, ``<module-list2>``, ...
|
||||
are list of module names. It is currently not possible to
|
||||
distinguish between .ml/.mli files, however it wouldn't be hard
|
||||
to support if needed.
|
||||
Where ``<spec1>``, ``<spec2>``, ... are preprocessing specifications and
|
||||
``<module-list1>``, ``<module-list2>``, ... are list of module names. It is
|
||||
currently not possible to distinguish between .ml/.mli files, however it
|
||||
wouldn't be hard to support if needed.
|
||||
|
||||
For instance:
|
||||
For instance:
|
||||
|
||||
.. code:: scheme
|
||||
.. code:: scheme
|
||||
|
||||
(preprocess (per_file
|
||||
(((action (run ./pp.sh X=1 ${<})) (foo bar)))
|
||||
(((action (run ./pp.sh X=2 ${<})) (baz)))))
|
||||
(preprocess (per_file
|
||||
(((action (run ./pp.sh X=1 ${<})) (foo bar)))
|
||||
(((action (run ./pp.sh X=2 ${<})) (baz)))))
|
||||
|
||||
Dependency specification
|
||||
------------------------
|
||||
|
||||
Dependencies in ``jbuild`` files can be specified using one of the
|
||||
following syntax:
|
||||
Dependencies in ``jbuild`` files can be specified using one of the following
|
||||
syntax:
|
||||
|
||||
- ``(file <filename>)`` or simply ``<filename>``: depend on this file
|
||||
- ``(alias <alias-name>)``: depend on the construction of this alias, for
|
||||
instance: ``(alias src/runtest)``
|
||||
instance: ``(alias src/runtest)``
|
||||
- ``(glob_files <glob>)``: depend on all files matched by ``<glob>``, see the
|
||||
:ref:`glob <glob>` for details
|
||||
:ref:`glob <glob>` for details
|
||||
- ``(files_recursively_in <dir>)``: depend on all files in the subtree with root
|
||||
``<dir>``
|
||||
``<dir>``
|
||||
|
||||
In all these cases, the argument supports `Variables expansion`_.
|
||||
|
||||
.. _glob:
|
||||
|
||||
#. Glob
|
||||
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``.
|
||||
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:
|
||||
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
|
||||
- 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:
|
||||
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>``, ...
|
||||
- ``\<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>``, ...
|
||||
|
||||
OCaml flags
|
||||
-----------
|
||||
|
||||
In ``library`` and ``executables`` stanzas, you can specify OCaml
|
||||
compilation flags using the following fields:
|
||||
In ``library`` and ``executables`` stanzas, you can specify OCaml compilation
|
||||
flags using the following fields:
|
||||
|
||||
- ``(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
|
||||
- ``(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
|
||||
|
||||
For all these fields, ``<flags>`` is specified in the `Ordered set language`_.
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -909,10 +887,10 @@ using ``(js_of_ocaml (<js_of_ocaml-options>))``.
|
|||
|
||||
``<js_of_ocaml-options>`` are all optional:
|
||||
|
||||
- ``(flags <flags>)`` to specify flags passed to ``js_of_ocaml``
|
||||
- ``(flags <flags>)`` to specify flags passed to ``js_of_ocaml``
|
||||
|
||||
- ``(javascript_files (<files-list>))`` to specify ``js_of_ocaml`` JavaScript
|
||||
runtime files.
|
||||
runtime files.
|
||||
|
||||
=<flags>= is specified in the `Ordered set language`_.
|
||||
|
||||
|
|
@ -942,24 +920,24 @@ configuration related tasks.
|
|||
|
||||
The following constructions are available:
|
||||
|
||||
- ``(run <prog> <args>)`` to execute a program
|
||||
- ``(chdir <dir> <DSL>)`` to change the current directory
|
||||
- ``(setenv <var> <value> <DSL>)`` to set an environment variable
|
||||
- ``(run <prog> <args>)`` to execute a program
|
||||
- ``(chdir <dir> <DSL>)`` to change the current directory
|
||||
- ``(setenv <var> <value> <DSL>)`` to set an environment variable
|
||||
- ``(with-<outputs>-to <file> <DSL>)`` to redirect the output to a file, where
|
||||
``<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
|
||||
``<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
|
||||
- ``(copy-and-add-line-directive <src> <dst>)`` to copy a file and add a line
|
||||
directive at the beginning
|
||||
directive at the beginning
|
||||
- ``(system <cmd>)`` to execute a command using the system shell: ``sh`` on Unix
|
||||
and ``cmd`` on Windows
|
||||
and ``cmd`` on Windows
|
||||
- ``(bash <cmd>)`` to execute a command using ``/bin/bash``. This is obviously
|
||||
not very portable
|
||||
not very portable
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -15,8 +15,8 @@ jbuild-workspace
|
|||
----------------
|
||||
|
||||
The root of the current workspace is determined by looking up a
|
||||
``jbuild-workspace`` file in the current directory and parent
|
||||
directories. ``jbuilder`` prints out the root when starting:
|
||||
``jbuild-workspace`` file in the current directory and parent directories.
|
||||
``jbuilder`` prints out the root when starting:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
|
|
@ -24,10 +24,10 @@ directories. ``jbuilder`` prints out the root when starting:
|
|||
Workspace root: /usr/local/home/jdimino/workspaces/public-jane/+share+
|
||||
...
|
||||
|
||||
More precisely, it will choose the outermost ancestor directory
|
||||
containing a ``jbuild-workspace`` file as root. For instance if you are
|
||||
in ``/home/me/code/myproject/src``, then jbuilder will look for all
|
||||
these files in order:
|
||||
More precisely, it will choose the outermost ancestor directory containing a
|
||||
``jbuild-workspace`` file as root. For instance if you are in
|
||||
``/home/me/code/myproject/src``, then jbuilder will look for all these files in
|
||||
order:
|
||||
|
||||
- ``/jbuild-workspace``
|
||||
- ``/home/jbuild-workspace``
|
||||
|
|
@ -48,11 +48,11 @@ this file.
|
|||
jbuild-workspace\*
|
||||
------------------
|
||||
|
||||
In addition to the previous rule, if no ``jbuild-workspace`` file is
|
||||
found, ``jbuilder`` will look for any file whose name starts with
|
||||
``jbuild-workspace`` in ancestor directories. For instance
|
||||
``jbuild-workspace.dev``. If such a file is found, it will mark the root
|
||||
of the workspace. ``jbuilder`` will however not read its contents.
|
||||
In addition to the previous rule, if no ``jbuild-workspace`` file is found,
|
||||
``jbuilder`` will look for any file whose name starts with ``jbuild-workspace``
|
||||
in ancestor directories. For instance ``jbuild-workspace.dev``. If such a file
|
||||
is found, it will mark the root of the workspace. ``jbuilder`` will however not
|
||||
read its contents.
|
||||
|
||||
The rationale for this rule is that it is good practice to have a
|
||||
``jbuild-workspace.dev`` file at the root of your project.
|
||||
|
|
@ -74,12 +74,11 @@ Forcing the root (for scripts)
|
|||
------------------------------
|
||||
|
||||
You can pass the ``--root`` option to ``jbuilder`` to select the root
|
||||
explicitly. This option is intended for scripts to disable the automatic
|
||||
lookup.
|
||||
explicitly. This option is intended for scripts to disable the automatic lookup.
|
||||
|
||||
Notet that when using the ``--root`` option, targets given on the
|
||||
command line will be interpreted relative to the given root, not
|
||||
relative to the current directory as this is normally the case.
|
||||
Note that when using the ``--root`` option, targets given on the command line
|
||||
will be interpreted relative to the given root, not relative to the current
|
||||
directory as this is normally the case.
|
||||
|
||||
Interpretation of targets
|
||||
=========================
|
||||
|
|
@ -90,27 +89,26 @@ the command line.
|
|||
Resolution
|
||||
----------
|
||||
|
||||
Most targets that Jbuilder knows how to build lives in the ``_build``
|
||||
directory, except for a few:
|
||||
Most targets that Jbuilder knows how to build lives in the ``_build`` directory,
|
||||
except for a few:
|
||||
|
||||
= ``.merlin`` files
|
||||
|
||||
- ``<package>.install`` files; for the ``default`` context Jbuilder
|
||||
knows how generate the install file both in ``_build/default`` and in
|
||||
the source tree so that ``opam`` can find it
|
||||
- ``<package>.install`` files; for the ``default`` context Jbuilder knows how
|
||||
generate the install file both in ``_build/default`` and in the source tree
|
||||
so that ``opam`` can find it
|
||||
|
||||
As a result, if you want to ask ``jbuilder`` to produce a particular
|
||||
``.exe`` file you would have to type:
|
||||
As a result, if you want to ask ``jbuilder`` to produce a particular ``.exe``
|
||||
file you would have to type:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ jbuilder build _build/default/bin/prog.exe
|
||||
|
||||
However, for convenience when a target on the command line doesn't start
|
||||
with ``_build``, ``jbuilder`` will expand it to the corresponding target
|
||||
in all the build contexts where it knows how to build it. It prints out
|
||||
the actual set of targets when starting so that you know what is
|
||||
happening:
|
||||
However, for convenience when a target on the command line doesn't start with
|
||||
``_build``, ``jbuilder`` will expand it to the corresponding target in all the
|
||||
build contexts where it knows how to build it. It prints out the actual set of
|
||||
targets when starting so that you know what is happening:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
|
|
@ -147,14 +145,13 @@ It looks up external libraries using a specific list of search pathes. A
|
|||
list of search pathes is specific to a given build context and is
|
||||
determined as follow:
|
||||
|
||||
#. if the ``ocamlfind`` is present in the ``PATH`` of the context, use
|
||||
each line in the output of ``ocamlfind printconf path`` as a search
|
||||
path
|
||||
#. otherwise, if ``opam`` is present in the ``PATH``, use the outout of
|
||||
``opam config var lib``
|
||||
#. if the ``ocamlfind`` is present in the ``PATH`` of the context, use each line
|
||||
in the output of ``ocamlfind printconf path`` as a search path
|
||||
#. otherwise, if ``opam`` is present in the ``PATH``, use the outout of ``opam
|
||||
config var lib``
|
||||
#. otherwise, take the directory where ``ocamlc`` was found, and append
|
||||
``../lib`` to it. For instance if ``ocamlc`` is found in
|
||||
``/usr/bin``, use ``/usr/lib``
|
||||
``../lib`` to it. For instance if ``ocamlc`` is found in ``/usr/bin``, use
|
||||
``/usr/lib``
|
||||
|
||||
.. _running-tests:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue