Improve wording and fix typos in documentation
This commit is contained in:
parent
6ce4d54274
commit
c05f410b75
14
README.org
14
README.org
|
@ -25,11 +25,11 @@ static files in a simple S-expression syntax or OCaml scripts. It uses
|
||||||
this information to setup build rules, generate configuration files
|
this information to setup build rules, generate configuration files
|
||||||
for development tools such as [[https://github.com/ocaml/merlin][merlin]], handle installation, etc...
|
for development tools such as [[https://github.com/ocaml/merlin][merlin]], handle installation, etc...
|
||||||
|
|
||||||
Jbuilder itself is fast, has very low-overhead and supports parallel
|
Jbuilder itself is fast, has very low overhead and supports parallel
|
||||||
builds on all platforms. It has no system dependencies: all you need
|
builds on all platforms. It has no system dependencies: all you need
|
||||||
to build jbuilder and packages using jbuilder is OCaml. You don't need
|
to build jbuilder and packages using jbuilder is OCaml. You don't need
|
||||||
=make= or =bash= as long as the packages themselves don't use =bash=
|
=make= or =bash= as long as the packages themselves don't use =bash=
|
||||||
explicitely.
|
explicitly.
|
||||||
|
|
||||||
Especially, one should be able to install OCaml on Windows with a
|
Especially, one should be able to install OCaml on Windows with a
|
||||||
binary installer and then use only the Windows Console to build
|
binary installer and then use only the Windows Console to build
|
||||||
|
@ -98,7 +98,7 @@ there only for convenience, for the following reasons:
|
||||||
|
|
||||||
1. there are many different build systems out there, all with a
|
1. there are many different build systems out there, all with a
|
||||||
different CLI. If you have been hacking for a long time, the one
|
different CLI. If you have been hacking for a long time, the one
|
||||||
true invokation you know is =make && make install=, possibly
|
true invocation you know is =make && make install=, possibly
|
||||||
preceded by =./configure=
|
preceded by =./configure=
|
||||||
|
|
||||||
2. you often have a few common operations that are not part of the
|
2. you often have a few common operations that are not part of the
|
||||||
|
@ -109,7 +109,7 @@ there only for convenience, for the following reasons:
|
||||||
*** How to add a configure step to a jbuilder project?
|
*** How to add a configure step to a jbuilder project?
|
||||||
|
|
||||||
[[example/sample-projects/with-configure-step]] shows one way to do it
|
[[example/sample-projects/with-configure-step]] shows one way to do it
|
||||||
that preserve composability; i.e. it doesn't require to manually run
|
that preserves composability; i.e. it doesn't require to manually run
|
||||||
all =./configure= script when working on multiple projects at the same
|
all =./configure= script when working on multiple projects at the same
|
||||||
time.
|
time.
|
||||||
|
|
||||||
|
@ -150,7 +150,7 @@ Street packages which became incredibly complicated over time. It is
|
||||||
still successfully used for this purpose.
|
still successfully used for this purpose.
|
||||||
|
|
||||||
One necessary feature to achieve this is the ability to precisely
|
One necessary feature to achieve this is the ability to precisely
|
||||||
report the external dependencies necesseray to build a given set of
|
report the external dependencies necessary to build a given set of
|
||||||
targets without running any command, just by looking at the source
|
targets without running any command, just by looking at the source
|
||||||
tree. This is used to automatically generate the =<package>.opam=
|
tree. This is used to automatically generate the =<package>.opam=
|
||||||
files for all Jane Street packages.
|
files for all Jane Street packages.
|
||||||
|
@ -159,8 +159,8 @@ To implement this, the build rules are described using a build arrow,
|
||||||
which is defined in [[src/build.mli][src/build]]. In the end it makes the development
|
which is defined in [[src/build.mli][src/build]]. In the end it makes the development
|
||||||
of the internal rules of Jbuilder very composable and quite pleasant.
|
of the internal rules of Jbuilder very composable and quite pleasant.
|
||||||
|
|
||||||
To deal with process multi-plexing, Jbuilder uses a simplified
|
To deal with process multiplexing, Jbuilder uses a simplified
|
||||||
Lwt/Async like monad, implemented in [[src/future.mli][src/future]].
|
Lwt/Async-like monad, implemented in [[src/future.mli][src/future]].
|
||||||
|
|
||||||
**** Code flow
|
**** Code flow
|
||||||
|
|
||||||
|
|
115
doc/manual.org
115
doc/manual.org
|
@ -1,4 +1,4 @@
|
||||||
This document describe the usage of Jbuilder and specifies its
|
This document describes the usage of Jbuilder and specifies its
|
||||||
metadata format. It is written using the =org= syntax and the best way
|
metadata format. It is written using the =org= syntax and the best way
|
||||||
to read it is either using the Emacs =org-mode= or on github.
|
to read it is either using the Emacs =org-mode= or on github.
|
||||||
|
|
||||||
|
@ -21,7 +21,7 @@ When using Jbuilder, you give very little and high-level information
|
||||||
to the build system, which in turns takes care of all the low-level
|
to the build system, which in turns takes care of all the low-level
|
||||||
details, from the compilation of your libraries, executables and
|
details, from the compilation of your libraries, executables and
|
||||||
documentation to the installation, setting up of tests, setting up of
|
documentation to the installation, setting up of tests, setting up of
|
||||||
the development tools such as merlin, etc...
|
the development tools such as merlin, etc.
|
||||||
|
|
||||||
In addition to the normal features one would expect from a build
|
In addition to the normal features one would expect from a build
|
||||||
system for OCaml, Jbuilder provides a few additional ones that detach
|
system for OCaml, Jbuilder provides a few additional ones that detach
|
||||||
|
@ -60,12 +60,12 @@ format and the third one describes how to use the =jbuilder= command.
|
||||||
packages
|
packages
|
||||||
|
|
||||||
- *root*: the root is the directory from where Jbuilder can build
|
- *root*: the root is the directory from where Jbuilder can build
|
||||||
things. Jbuilder knows how to build target that are descendant of
|
things. Jbuilder knows how to build targets that are descendents of
|
||||||
the root. Anything outside of the tree starting from the root is
|
the root. Anything outside of the tree starting from the root is
|
||||||
considered part of the *installed world*. How the root is determined
|
considered part of the *installed world*. How the root is determined
|
||||||
is explained in [[Finding the root][this section]].
|
is explained in [[Finding the root][this section]].
|
||||||
|
|
||||||
- *workspace*: a workspace is the sub-tree starting from the root. It
|
- *workspace*: the workspace is the subtree starting from the root. It
|
||||||
can contain any number of projects that will be built simultaneously
|
can contain any number of projects that will be built simultaneously
|
||||||
by jbuilder
|
by jbuilder
|
||||||
|
|
||||||
|
@ -76,7 +76,7 @@ format and the third one describes how to use the =jbuilder= command.
|
||||||
=<root>/_build= directory. It contains all the build artifacts of
|
=<root>/_build= directory. It contains all the build artifacts of
|
||||||
the workspace built against a specific configuration. Without
|
the workspace built against a specific configuration. Without
|
||||||
specific configuration from the user, there is always a =default=
|
specific configuration from the user, there is always a =default=
|
||||||
build context, which correspond to the environment in which Jbuilder
|
build context, which corresponds to the environment in which Jbuilder
|
||||||
is executed. Build contexts can be specified by writing a
|
is executed. Build contexts can be specified by writing a
|
||||||
[[jbuild-workspace]] file
|
[[jbuild-workspace]] file
|
||||||
|
|
||||||
|
@ -130,7 +130,7 @@ meta-programming on jbuilds files by writing them in [[OCaml syntax]].
|
||||||
|
|
||||||
** <package>.opam files
|
** <package>.opam files
|
||||||
|
|
||||||
When a =<package>.opam= file is present, Jbuilder will knows that the
|
When a =<package>.opam= file is present, Jbuilder will know that the
|
||||||
package named =<package>= exists. It will know how to construct a
|
package named =<package>= exists. It will know how to construct a
|
||||||
=<package>.install= file in the same directory to handle installation
|
=<package>.install= file in the same directory to handle installation
|
||||||
via [[https://opam.ocaml.org/][opam]]. Jbuilder also defines the recursive =install= alias, which
|
via [[https://opam.ocaml.org/][opam]]. Jbuilder also defines the recursive =install= alias, which
|
||||||
|
@ -252,7 +252,7 @@ Jbuilder metadata format in this =jbuild= file.
|
||||||
**** library
|
**** library
|
||||||
|
|
||||||
The =library= stanza must be used to describe OCaml libraries. The
|
The =library= stanza must be used to describe OCaml libraries. The
|
||||||
format of library stanzas is as follow:
|
format of library stanzas is as follows:
|
||||||
|
|
||||||
#+begin_src scheme
|
#+begin_src scheme
|
||||||
(library
|
(library
|
||||||
|
@ -275,7 +275,7 @@ the library and you are free to expose only the modules you want.
|
||||||
=<optional-fields>= are:
|
=<optional-fields>= are:
|
||||||
|
|
||||||
- =(public_name <name>)= this is the name under which the library can
|
- =(public_name <name>)= this is the name under which the library can
|
||||||
be referred as a dependency when it is not part of the current
|
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 ...)=
|
workspace, i.e. when it is installed. Without a =(public_name ...)=
|
||||||
field, the library will not be installed by Jbuilder. The public
|
field, the library will not be installed by Jbuilder. The public
|
||||||
name must start by the package name it is part of and optionally
|
name must start by the package name it is part of and optionally
|
||||||
|
@ -300,16 +300,16 @@ the library and you are free to expose only the modules you want.
|
||||||
dependencies]] for more details
|
dependencies]] for more details
|
||||||
|
|
||||||
- =(wrapped <boolean>)= specifies whether the modules of the library
|
- =(wrapped <boolean>)= specifies whether the modules of the library
|
||||||
should be available only through of the toplevel library module, or
|
should be available only through the top-level library module, or
|
||||||
should all be exposed at toplevel. The default is =true= and it is
|
should all be exposed at the top level. The default is =true= and it is
|
||||||
highly recommended to keep it this way. Because OCaml toplevel modules
|
highly recommended to keep it this way. Because OCaml top-level modules
|
||||||
must all be unique when linking an executables, polluting the
|
must all be unique when linking an executables, polluting the
|
||||||
toplevel namespace will make your library unusable with other
|
top-level namespace will make your library unusable with other
|
||||||
libraries if there is a module name clash. This option is only
|
libraries if there is a module name clash. This option is only
|
||||||
intended for libraries that manually prefix all their modules by the
|
intended for libraries that manually prefix all their modules by the
|
||||||
library name and to ease porting of existing projects to Jbuilder
|
library name and to ease porting of existing projects to Jbuilder
|
||||||
|
|
||||||
- =(preprocess <preprocess-spec>)= specifies how to pre-process files
|
- =(preprocess <preprocess-spec>)= specifies how to preprocess files
|
||||||
if needed. The default is =no_processing=. Other options are
|
if needed. The default is =no_processing=. Other options are
|
||||||
described in the [[Preprocessing specification][preprocessing specification section]]
|
described in the [[Preprocessing specification][preprocessing specification section]]
|
||||||
|
|
||||||
|
@ -329,7 +329,7 @@ the library and you are free to expose only the modules you want.
|
||||||
|
|
||||||
- =(cxx_names (<names>))= is the same as =c_names= but for C++ stubs
|
- =(cxx_names (<names>))= is the same as =c_names= but for C++ stubs
|
||||||
|
|
||||||
- =(install_c_headers (<names>))=, if your libraries has public C
|
- =(install_c_headers (<names>))=, if your library has public C
|
||||||
header files that must be installed, you must list them in this
|
header files that must be installed, you must list them in this
|
||||||
field, with the =.h= extension
|
field, with the =.h= extension
|
||||||
|
|
||||||
|
@ -346,12 +346,12 @@ the library and you are free to expose only the modules you want.
|
||||||
|
|
||||||
- =(ppx_runtime_libraries (<library-names>))= is for when the library
|
- =(ppx_runtime_libraries (<library-names>))= is for when the library
|
||||||
is a ppx rewriter or a =[@@deriving ...]= plugin and has runtime
|
is a ppx rewriter or a =[@@deriving ...]= plugin and has runtime
|
||||||
dependencies. You need to specify these runtime dependencies them here
|
dependencies. You need to specify these runtime dependencies here
|
||||||
|
|
||||||
- =(virtual_deps (<opam-packages>)=. Sometimes opam packages enable a
|
- =(virtual_deps (<opam-packages>)=. Sometimes opam packages enable a
|
||||||
specific feature only if another package is installed. This is for
|
specific feature only if another package is installed. This is for
|
||||||
instance the case of =ctypes= which will only install
|
instance the case of =ctypes= which will only install
|
||||||
=ctypes.foreign= if the dummy =ctypes-forein= package is
|
=ctypes.foreign= if the dummy =ctypes-foreign= package is
|
||||||
installed. You can specify such virtual dependencies here. You don't
|
installed. You can specify such virtual dependencies here. You don't
|
||||||
need to do so unless you use Jbuilder to synthesize the =depends=
|
need to do so unless you use Jbuilder to synthesize the =depends=
|
||||||
and =depopts= sections of your opam file
|
and =depopts= sections of your opam file
|
||||||
|
@ -376,7 +376,7 @@ the library and you are free to expose only the modules you want.
|
||||||
=<flags>= uses the [[Ordered set language][ordered set language]] and supports =(:include
|
=<flags>= uses the [[Ordered set language][ordered set language]] and supports =(:include
|
||||||
...)= forms. When you are writing bindings for a C library named
|
...)= forms. When you are writing bindings for a C library named
|
||||||
=bar=, you should typically write =-lbar= here, or whatever flags
|
=bar=, you should typically write =-lbar= here, or whatever flags
|
||||||
are necessary to to link against this library.
|
are necessary to to link against this library
|
||||||
|
|
||||||
- =(self_build_stubs_archive <c-libname>)= indicates to Jbuilder that
|
- =(self_build_stubs_archive <c-libname>)= indicates to Jbuilder that
|
||||||
the library has stubs, but that the stubs are built manually. The
|
the library has stubs, but that the stubs are built manually. The
|
||||||
|
@ -392,7 +392,7 @@ with [[https://github.com/janestreet/configurator][configurator]] by using =(c_f
|
||||||
**** executable
|
**** executable
|
||||||
|
|
||||||
The =executable= stanza must be used to describe an executable. The
|
The =executable= stanza must be used to describe an executable. The
|
||||||
format of executables stanzas is as follows:
|
format of executable stanzas is as follows:
|
||||||
|
|
||||||
#+begin_src scheme
|
#+begin_src scheme
|
||||||
(executable
|
(executable
|
||||||
|
@ -401,13 +401,12 @@ format of executables stanzas is as follows:
|
||||||
))
|
))
|
||||||
#+end_src
|
#+end_src
|
||||||
|
|
||||||
=<entry point name>= is a module name that contain the main entry
|
=<name>= is a module name that contains the main entry point of the
|
||||||
point of the executable. There can be additional modules in the
|
executable. There can be additional modules in the current directory,
|
||||||
current directory, you only need to specify the entry point. Given an
|
you only need to specify the entry point. Given an =executable= stanza
|
||||||
=executable= stanza with =(name <name>)=, Jbuilder will know how to
|
with =(name <name>)=, Jbuilder will know how to build =<name>.exe= and
|
||||||
build =<name>.exe= and =<name>.bc=. =<name>.exe= is a native code
|
=<name>.bc=. =<name>.exe= is a native code executable and =<name>.bc=
|
||||||
executable and =<name>.bc= is a bytecode executable which requires
|
is a bytecode executable which requires =ocamlrun= to run.
|
||||||
=ocamlrun= to run.
|
|
||||||
|
|
||||||
Note that in case native compilation is not available, =<name>.exe=
|
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
|
will in fact be a custom byte-code executable. Custom in the sense of
|
||||||
|
@ -417,7 +416,7 @@ can always rely on =<name>.exe= being available.
|
||||||
|
|
||||||
=<optional-fields>= are:
|
=<optional-fields>= are:
|
||||||
|
|
||||||
- =(public_name <public-name>)= specify that the executable should be
|
- =(public_name <public-name>)= specifies that the executable should be
|
||||||
installed under that name. It is the same as adding the following
|
installed under that name. It is the same as adding the following
|
||||||
stanza to your =jbuild= file:
|
stanza to your =jbuild= file:
|
||||||
#+begin_src scheme
|
#+begin_src scheme
|
||||||
|
@ -463,7 +462,7 @@ instead of =(name ...)= and =(public_name ...)= you must use:
|
||||||
containing the entry point of each executable
|
containing the entry point of each executable
|
||||||
|
|
||||||
- =(public_names (<names>))= describes under what name 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
|
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
|
the list in the =(names ...)= field. Moreover you can use =-= for
|
||||||
executables that shouldn't be installed
|
executables that shouldn't be installed
|
||||||
|
|
||||||
|
@ -473,7 +472,7 @@ 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
|
Jbuilder how to generate a specific set of files from a specific set
|
||||||
of dependencies.
|
of dependencies.
|
||||||
|
|
||||||
The syntax is as follow:
|
The syntax is as follows:
|
||||||
|
|
||||||
#+begin_src scheme
|
#+begin_src scheme
|
||||||
(rule
|
(rule
|
||||||
|
@ -494,7 +493,7 @@ dependencies. See the [[User actions][actions section]] for more details.
|
||||||
|
|
||||||
**** ocamllex
|
**** ocamllex
|
||||||
|
|
||||||
=(ocamllex (<names>))= is essentially a short-hand for:
|
=(ocamllex (<names>))= is essentially a shorthand for:
|
||||||
|
|
||||||
#+begin_src scheme
|
#+begin_src scheme
|
||||||
(rule
|
(rule
|
||||||
|
@ -505,7 +504,7 @@ dependencies. See the [[User actions][actions section]] for more details.
|
||||||
|
|
||||||
**** ocamlyacc
|
**** ocamlyacc
|
||||||
|
|
||||||
=(ocamlyacc (<names>))= is essentially a short-hand for:
|
=(ocamlyacc (<names>))= is essentially a shorthand for:
|
||||||
|
|
||||||
#+begin_src scheme
|
#+begin_src scheme
|
||||||
(rule
|
(rule
|
||||||
|
@ -519,7 +518,7 @@ dependencies. See the [[User actions][actions section]] for more details.
|
||||||
The =alias= stanza lets you add dependencies to an alias, or specify
|
The =alias= stanza lets you add dependencies to an alias, or specify
|
||||||
an action to run to construct the alias.
|
an action to run to construct the alias.
|
||||||
|
|
||||||
The syntax is as follow:
|
The syntax is as follows:
|
||||||
|
|
||||||
#+begin_src scheme
|
#+begin_src scheme
|
||||||
(alias
|
(alias
|
||||||
|
@ -558,7 +557,7 @@ install, either when running =jbuilder install= or through opam.
|
||||||
Libraries don't need an =install= stanza to be installed, just a
|
Libraries don't need an =install= stanza to be installed, just a
|
||||||
=public_name= field. Everything else needs an =install= stanza.
|
=public_name= field. Everything else needs an =install= stanza.
|
||||||
|
|
||||||
The syntax is as follow:
|
The syntax is as follows:
|
||||||
|
|
||||||
#+begin_src scheme
|
#+begin_src scheme
|
||||||
(install
|
(install
|
||||||
|
@ -598,13 +597,13 @@ manual. The following sections are available:
|
||||||
|
|
||||||
***** Ordered set language
|
***** Ordered set language
|
||||||
|
|
||||||
A few fields takes as argument am ordered set and can be specified
|
A few fields takes as argument an ordered set and can be specified
|
||||||
using a small DSL.
|
using a small DSL.
|
||||||
|
|
||||||
This DSL is interpreted by jbuilder into an ordered set of strings
|
This DSL is interpreted by jbuilder into an ordered set of strings
|
||||||
using the following rules:
|
using the following rules:
|
||||||
|
|
||||||
- =:standard= denotes to the standard value of the field when it is
|
- =:standard= denotes the standard value of the field when it is
|
||||||
absent
|
absent
|
||||||
- an atom not starting with a =:= is a singleton containing only this
|
- an atom not starting with a =:= is a singleton containing only this
|
||||||
atom
|
atom
|
||||||
|
@ -674,7 +673,7 @@ that work transparently whether things are installed or not.
|
||||||
Dependencies on libraries are specified using =(libraries ...)= fields
|
Dependencies on libraries are specified using =(libraries ...)= fields
|
||||||
in =library= and =executables= stanzas.
|
in =library= and =executables= stanzas.
|
||||||
|
|
||||||
For library that are present in the workspace, you can use either the
|
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
|
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
|
libraries that are part of the installed world, you need to use the
|
||||||
public name. For instance: =(libraries (base re))=.
|
public name. For instance: =(libraries (base re))=.
|
||||||
|
@ -685,9 +684,9 @@ 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
|
The scope of internal library names is not the whole workspace. It is
|
||||||
restricted to the sub-tree starting from the closest parent containing
|
restricted to the subtree starting from the closest parent containing
|
||||||
a =<package>.opam= file, or the whole workspace if no such directory
|
a =<package>.opam= file, or the whole workspace if no such directory
|
||||||
exist. Moreover, a sub-tree containing =<package>.opam= doesn' t
|
exist. Moreover, a subtree containing =<package>.opam= doesn' t
|
||||||
inherit the internal names available in its parent scope.
|
inherit the internal names available in its parent scope.
|
||||||
|
|
||||||
The idea behing this rule is that public library names must be
|
The idea behing this rule is that public library names must be
|
||||||
|
@ -713,7 +712,7 @@ use a different backend depending on the target.
|
||||||
Jbuilder allows this by using a =(select ... from ...)= form inside
|
Jbuilder allows this by using a =(select ... from ...)= form inside
|
||||||
the list of library dependencies.
|
the list of library dependencies.
|
||||||
|
|
||||||
Select forms are specified as follow:
|
Select forms are specified as follows:
|
||||||
|
|
||||||
#+begin_src scheme
|
#+begin_src scheme
|
||||||
(select <target-filename> from
|
(select <target-filename> from
|
||||||
|
@ -722,9 +721,9 @@ Select forms are specified as follow:
|
||||||
...))
|
...))
|
||||||
#+end_src
|
#+end_src
|
||||||
|
|
||||||
=<literals>= are list 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
|
- =<library-name>=, which will evaluate to true if =<library-name>= is
|
||||||
available, either in the worksapce either in the installed world
|
available, either in the workspace or in the installed world
|
||||||
- =!<library-name>=, which will evaluate to true if =<library-name>=
|
- =!<library-name>=, which will evaluate to true if =<library-name>=
|
||||||
is not available in the workspace or in the installed world
|
is not available in the workspace or in the installed world
|
||||||
|
|
||||||
|
@ -737,15 +736,15 @@ of the list.
|
||||||
|
|
||||||
***** Preprocessing specification
|
***** Preprocessing specification
|
||||||
|
|
||||||
Jbuilder accept three kinds of pre-processing:
|
Jbuilder accepts three kinds of preprocessing:
|
||||||
|
|
||||||
- =no_preprocessing=, meaning that files are given as it to the
|
- =no_preprocessing=, meaning that files are given as it to the
|
||||||
compiler, this is the default
|
compiler, this is the default
|
||||||
- =(action <action>)= to pre-process files using the given action
|
- =(action <action>)= to preprocess files using the given action
|
||||||
- =(pps (<ppx-rewriters-and-flags>))= to pre-process files using the
|
- =(pps (<ppx-rewriters-and-flags>))= to preprocess files using the
|
||||||
given list of ppx rewriters
|
given list of ppx rewriters
|
||||||
|
|
||||||
Note that in any cases, files are pre-processed only once. Jbuilder
|
Note that in any cases, files are preprocessed only once. Jbuilder
|
||||||
doesn't use the =-pp= or =-ppx= of the various OCaml tools.
|
doesn't use the =-pp= or =-ppx= of the various OCaml tools.
|
||||||
|
|
||||||
****** Preprocessing with actions
|
****** Preprocessing with actions
|
||||||
|
@ -753,7 +752,7 @@ doesn't use the =-pp= or =-ppx= of the various OCaml tools.
|
||||||
=<action>= uses the same DSL as described in the [[User actions][user actions section]],
|
=<action>= uses the same DSL as described in the [[User actions][user actions section]],
|
||||||
and for the same reason given in that section, it will be executed
|
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
|
from the root of the current build context. It is expected to be an
|
||||||
action that read the file given as only dependency and outputs the
|
action that reads the file given as only dependency and outputs the
|
||||||
preprocessed file on its standard output.
|
preprocessed file on its standard output.
|
||||||
|
|
||||||
More precisely, =(preprocess (action <action>))= acts as if you had
|
More precisely, =(preprocess (action <action>))= acts as if you had
|
||||||
|
@ -788,7 +787,7 @@ Libraries listed here should be libraries implementing an OCaml AST
|
||||||
rewriter and registering themselves using the
|
rewriter and registering themselves using the
|
||||||
[[https://github.com/let-def/ocaml-migrate-parsetree][ocaml-migrate-parsetree.driver API]].
|
[[https://github.com/let-def/ocaml-migrate-parsetree][ocaml-migrate-parsetree.driver API]].
|
||||||
|
|
||||||
Jbuilder will build a single executable by linking all these lbraries
|
Jbuilder will build a single executable by linking all these libraries
|
||||||
and their dependencies. Note that it is important that all these
|
and their dependencies. Note that it is important that all these
|
||||||
libraries are linked with =-linkall=. Jbuilder automatically uses
|
libraries are linked with =-linkall=. Jbuilder automatically uses
|
||||||
=-linkall= when the =(kind ...)= field is set to =ppx_rewriter= or
|
=-linkall= when the =(kind ...)= field is set to =ppx_rewriter= or
|
||||||
|
@ -799,7 +798,7 @@ last. You can use this feature to use a custom ppx driver. By default
|
||||||
Jbuilder will use =ocaml-migrate-parsetree.driver-main=. See the
|
Jbuilder will use =ocaml-migrate-parsetree.driver-main=. See the
|
||||||
[[Using a custom ppx driver][section about using a custom ppx driver]] for more details.
|
[[Using a custom ppx driver][section about using a custom ppx driver]] for more details.
|
||||||
|
|
||||||
****** Per module pre-processing specification
|
****** Per module preprocessing specification
|
||||||
|
|
||||||
By default a preprocessing specification will apply to all modules in
|
By default a preprocessing specification will apply to all modules in
|
||||||
the library/set of executables. It is possible to select the
|
the library/set of executables. It is possible to select the
|
||||||
|
@ -836,7 +835,7 @@ following syntax:
|
||||||
for instance: =(alias src/runtest)=
|
for instance: =(alias src/runtest)=
|
||||||
- =(glob_files <glob>)=: depend on all files matched by =<glob>=, see
|
- =(glob_files <glob>)=: depend on all files matched by =<glob>=, see
|
||||||
the [[Glob][glob section]] for details
|
the [[Glob][glob section]] for details
|
||||||
- =(files_recursively_in <dir>)=: depend on all files in the sub-tree
|
- =(files_recursively_in <dir>)=: depend on all files in the subtree
|
||||||
with root =<dir>=
|
with root =<dir>=
|
||||||
|
|
||||||
In all these cases, the argument supports [[Variables expansion][variables expansion]].
|
In all these cases, the argument supports [[Variables expansion][variables expansion]].
|
||||||
|
@ -848,13 +847,13 @@ globs will match files that exist in the source tree as well as
|
||||||
buildable targets, so for instance you can depend on =*.cmi=.
|
buildable targets, so for instance you can depend on =*.cmi=.
|
||||||
|
|
||||||
Currently jbuilder only support globbing files in a single
|
Currently jbuilder only support globbing files in a single
|
||||||
directory. And in particular the glob is interpreted as follow:
|
directory. And in particular the glob is interpreted as follows:
|
||||||
|
|
||||||
- anything before the last =/= is taken as a literal path
|
- anything before the last =/= is taken as a literal path
|
||||||
- anything after the last =/=, or everything if the glob contains no
|
- anything after the last =/=, or everything if the glob contains no
|
||||||
=/=, is interpreted using the glob syntax
|
=/=, is interpreted using the glob syntax
|
||||||
|
|
||||||
The glob syntax is interpreted as follow:
|
The glob syntax is interpreted as follows:
|
||||||
|
|
||||||
- =\<char>= matches exactly =<char>=, even if it is a special
|
- =\<char>= matches exactly =<char>=, even if it is a special
|
||||||
character (=*=, =?=, ...)
|
character (=*=, =?=, ...)
|
||||||
|
@ -885,7 +884,7 @@ For all these fields, =<flags>= is specified in the [[Ordered set language][orde
|
||||||
The default value for =(flags ...)= includes some =-w= options to set
|
The default value for =(flags ...)= includes some =-w= options to set
|
||||||
warnings. The exact set depends on whether =--dev= is passed to
|
warnings. The exact set depends on whether =--dev= is passed to
|
||||||
Jbuilder. As a result it is recommended to write =(flags ...)= fields
|
Jbuilder. As a result it is recommended to write =(flags ...)= fields
|
||||||
as follow:
|
as follows:
|
||||||
|
|
||||||
#+begin_src
|
#+begin_src
|
||||||
(flags (:standard <my options>))
|
(flags (:standard <my options>))
|
||||||
|
@ -895,7 +894,7 @@ as follow:
|
||||||
|
|
||||||
=(action ...)= fields describe user actions.
|
=(action ...)= fields describe user actions.
|
||||||
|
|
||||||
User actions are always run from the same sub-directory of the current
|
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
|
build context as the jbuild they are defined in. So for instance an
|
||||||
action defined in =src/foo/jbuild= will be run from
|
action defined in =src/foo/jbuild= will be run from
|
||||||
=_build/<context>/src/foo=.
|
=_build/<context>/src/foo=.
|
||||||
|
@ -983,7 +982,7 @@ the root of your project. What you should write instead is:
|
||||||
** jbuild-ignore
|
** jbuild-ignore
|
||||||
|
|
||||||
By default Jbuilder traverses the whole source tree. To ignore a
|
By default Jbuilder traverses the whole source tree. To ignore a
|
||||||
sub-tree, simply write a =jbuild-ignore= file in the parent directory
|
subtree, simply write a =jbuild-ignore= file in the parent directory
|
||||||
containing the name of the sub-directories to ignore.
|
containing the name of the sub-directories to ignore.
|
||||||
|
|
||||||
So for instance, if you write =foo= in =src/jbuild-ignore=, then
|
So for instance, if you write =foo= in =src/jbuild-ignore=, then
|
||||||
|
@ -1133,7 +1132,7 @@ list given to =jbuilder=.
|
||||||
** Invocation from opam
|
** Invocation from opam
|
||||||
|
|
||||||
You should set the =build:= field of your =<package>.opam= file as
|
You should set the =build:= field of your =<package>.opam= file as
|
||||||
follow:
|
follows:
|
||||||
|
|
||||||
#+begin_src
|
#+begin_src
|
||||||
build: [["jbuilder" "build" "--only-packages" "<package>" "--root" "." "-j" jobs "@install"]]
|
build: [["jbuilder" "build" "--only-packages" "<package>" "--root" "." "-j" jobs "@install"]]
|
||||||
|
@ -1178,7 +1177,7 @@ The rest of this section describe the stanzas available.
|
||||||
|
|
||||||
The =(context ...)= stanza declares a build context. The argument can
|
The =(context ...)= stanza declares a build context. The argument can
|
||||||
be either =default= for the default build context or can be the
|
be either =default= for the default build context or can be the
|
||||||
description of an opam switch, as follow:
|
description of an opam switch, as follows:
|
||||||
|
|
||||||
#+begin_src scheme
|
#+begin_src scheme
|
||||||
(context ((switch <opam-switch-name>)
|
(context ((switch <opam-switch-name>)
|
||||||
|
@ -1187,7 +1186,7 @@ description of an opam switch, as follow:
|
||||||
|
|
||||||
=<optional-fields>= are:
|
=<optional-fields>= are:
|
||||||
|
|
||||||
- =(name <name>)= is the name of the sub-directory of =_build= where
|
- =(name <name>)= is the name of the subdirectory of =_build= where
|
||||||
the artifacts for this build context will be stored
|
the artifacts for this build context will be stored
|
||||||
|
|
||||||
- =(root <opam-root>)= is the opam root. By default it will take the
|
- =(root <opam-root>)= is the opam root. By default it will take the
|
||||||
|
@ -1207,7 +1206,7 @@ This section describes some details of Jbuilder for advanced users.
|
||||||
** META file generation
|
** META file generation
|
||||||
|
|
||||||
Jbuilder uses =META= files from the [[http://projects.camlcity.org/projects/findlib.html][findlib library manager]] in order
|
Jbuilder uses =META= files from the [[http://projects.camlcity.org/projects/findlib.html][findlib library manager]] in order
|
||||||
to inter-operate with the rest of the world when installing
|
to interoperate with the rest of the world when installing
|
||||||
libraries. It is able to generate them automatically. However, for the
|
libraries. It is able to generate them automatically. However, for the
|
||||||
rare cases where you would need a specific =META= file, or to ease the
|
rare cases where you would need a specific =META= file, or to ease the
|
||||||
transition of a project to Jbuilder, it is allowed to write/generate a
|
transition of a project to Jbuilder, it is allowed to write/generate a
|
||||||
|
@ -1249,7 +1248,7 @@ use it instead of =ocaml-migrate-parsetree.driver-main=, simply write
|
||||||
****** Driver expectation
|
****** Driver expectation
|
||||||
|
|
||||||
Jbuilder will invoke the executable resulting from linking the
|
Jbuilder will invoke the executable resulting from linking the
|
||||||
libraries given in the =(pps ...)= form as follow:
|
libraries given in the =(pps ...)= form as follows:
|
||||||
|
|
||||||
#+begin_src sh
|
#+begin_src sh
|
||||||
ppx.exe <flags-written-by-user> --dump-ast -o <output-file> [--impl|--intf] <source-file>
|
ppx.exe <flags-written-by-user> --dump-ast -o <output-file> [--impl|--intf] <source-file>
|
||||||
|
|
Loading…
Reference in New Issue