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
|
||||
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
|
||||
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=
|
||||
explicitely.
|
||||
explicitly.
|
||||
|
||||
Especially, one should be able to install OCaml on Windows with a
|
||||
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
|
||||
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=
|
||||
|
||||
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?
|
||||
|
||||
[[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
|
||||
time.
|
||||
|
||||
|
@ -150,7 +150,7 @@ Street packages which became incredibly complicated over time. It is
|
|||
still successfully used for this purpose.
|
||||
|
||||
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
|
||||
tree. This is used to automatically generate the =<package>.opam=
|
||||
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
|
||||
of the internal rules of Jbuilder very composable and quite pleasant.
|
||||
|
||||
To deal with process multi-plexing, Jbuilder uses a simplified
|
||||
Lwt/Async like monad, implemented in [[src/future.mli][src/future]].
|
||||
To deal with process multiplexing, Jbuilder uses a simplified
|
||||
Lwt/Async-like monad, implemented in [[src/future.mli][src/future]].
|
||||
|
||||
**** 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
|
||||
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
|
||||
details, from the compilation of your libraries, executables and
|
||||
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
|
||||
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
|
||||
|
||||
- *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
|
||||
considered part of the *installed world*. How the root is determined
|
||||
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
|
||||
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
|
||||
the workspace built against a specific configuration. Without
|
||||
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
|
||||
[[jbuild-workspace]] file
|
||||
|
||||
|
@ -130,7 +130,7 @@ meta-programming on jbuilds files by writing them in [[OCaml syntax]].
|
|||
|
||||
** <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>.install= file in the same directory to handle installation
|
||||
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
|
||||
|
||||
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
|
||||
(library
|
||||
|
@ -275,7 +275,7 @@ 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 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 ...)=
|
||||
field, the library will not be installed by Jbuilder. The public
|
||||
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
|
||||
|
||||
- =(wrapped <boolean>)= specifies whether the modules of the library
|
||||
should be available only through of the toplevel library module, or
|
||||
should all be exposed at toplevel. The default is =true= and it is
|
||||
highly recommended to keep it this way. Because OCaml toplevel modules
|
||||
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
|
||||
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
|
||||
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 pre-process files
|
||||
- =(preprocess <preprocess-spec>)= specifies how to preprocess files
|
||||
if needed. The default is =no_processing=. Other options are
|
||||
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
|
||||
|
||||
- =(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
|
||||
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
|
||||
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
|
||||
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-forein= package is
|
||||
=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
|
||||
|
@ -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
|
||||
...)= 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.
|
||||
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
|
||||
|
@ -392,7 +392,7 @@ with [[https://github.com/janestreet/configurator][configurator]] by using =(c_f
|
|||
**** executable
|
||||
|
||||
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
|
||||
(executable
|
||||
|
@ -401,13 +401,12 @@ format of executables stanzas is as follows:
|
|||
))
|
||||
#+end_src
|
||||
|
||||
=<entry point name>= is a module name that contain 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= and =<name>.bc=. =<name>.exe= is a native code
|
||||
executable and =<name>.bc= is a bytecode executable which requires
|
||||
=ocamlrun= to run.
|
||||
=<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= and
|
||||
=<name>.bc=. =<name>.exe= is a native code executable and =<name>.bc=
|
||||
is a bytecode executable which requires =ocamlrun= to run.
|
||||
|
||||
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
|
||||
|
@ -417,7 +416,7 @@ can always rely on =<name>.exe= being available.
|
|||
|
||||
=<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
|
||||
stanza to your =jbuild= file:
|
||||
#+begin_src scheme
|
||||
|
@ -463,7 +462,7 @@ instead of =(name ...)= and =(public_name ...)= you must use:
|
|||
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
|
||||
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
|
||||
|
||||
|
@ -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
|
||||
of dependencies.
|
||||
|
||||
The syntax is as follow:
|
||||
The syntax is as follows:
|
||||
|
||||
#+begin_src scheme
|
||||
(rule
|
||||
|
@ -494,7 +493,7 @@ dependencies. See the [[User actions][actions section]] for more details.
|
|||
|
||||
**** ocamllex
|
||||
|
||||
=(ocamllex (<names>))= is essentially a short-hand for:
|
||||
=(ocamllex (<names>))= is essentially a shorthand for:
|
||||
|
||||
#+begin_src scheme
|
||||
(rule
|
||||
|
@ -505,7 +504,7 @@ dependencies. See the [[User actions][actions section]] for more details.
|
|||
|
||||
**** ocamlyacc
|
||||
|
||||
=(ocamlyacc (<names>))= is essentially a short-hand for:
|
||||
=(ocamlyacc (<names>))= is essentially a shorthand for:
|
||||
|
||||
#+begin_src scheme
|
||||
(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
|
||||
an action to run to construct the alias.
|
||||
|
||||
The syntax is as follow:
|
||||
The syntax is as follows:
|
||||
|
||||
#+begin_src scheme
|
||||
(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
|
||||
=public_name= field. Everything else needs an =install= stanza.
|
||||
|
||||
The syntax is as follow:
|
||||
The syntax is as follows:
|
||||
|
||||
#+begin_src scheme
|
||||
(install
|
||||
|
@ -598,13 +597,13 @@ manual. The following sections are available:
|
|||
|
||||
***** 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.
|
||||
|
||||
This DSL is interpreted by jbuilder into an ordered set of strings
|
||||
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
|
||||
- an atom not starting with a =:= is a singleton containing only this
|
||||
atom
|
||||
|
@ -674,7 +673,7 @@ that work transparently whether things are installed or not.
|
|||
Dependencies on libraries are specified using =(libraries ...)= fields
|
||||
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
|
||||
libraries that are part of the installed world, you need to use the
|
||||
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
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
the list of library dependencies.
|
||||
|
||||
Select forms are specified as follow:
|
||||
Select forms are specified as follows:
|
||||
|
||||
#+begin_src scheme
|
||||
(select <target-filename> from
|
||||
|
@ -722,9 +721,9 @@ Select forms are specified as follow:
|
|||
...))
|
||||
#+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
|
||||
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>=
|
||||
is not available in the workspace or in the installed world
|
||||
|
||||
|
@ -737,15 +736,15 @@ of the list.
|
|||
|
||||
***** 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
|
||||
compiler, this is the default
|
||||
- =(action <action>)= to pre-process files using the given action
|
||||
- =(pps (<ppx-rewriters-and-flags>))= to pre-process files using the
|
||||
- =(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 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.
|
||||
|
||||
****** 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]],
|
||||
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 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.
|
||||
|
||||
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
|
||||
[[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
|
||||
libraries are linked with =-linkall=. Jbuilder automatically uses
|
||||
=-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
|
||||
[[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
|
||||
the library/set of executables. It is possible to select the
|
||||
|
@ -836,7 +835,7 @@ following syntax:
|
|||
for instance: =(alias src/runtest)=
|
||||
- =(glob_files <glob>)=: depend on all files matched by =<glob>=, see
|
||||
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>=
|
||||
|
||||
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=.
|
||||
|
||||
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 after the last =/=, or everything if the glob contains no
|
||||
=/=, 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
|
||||
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
|
||||
warnings. The exact set depends on whether =--dev= is passed to
|
||||
Jbuilder. As a result it is recommended to write =(flags ...)= fields
|
||||
as follow:
|
||||
as follows:
|
||||
|
||||
#+begin_src
|
||||
(flags (:standard <my options>))
|
||||
|
@ -895,7 +894,7 @@ as follow:
|
|||
|
||||
=(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
|
||||
action defined in =src/foo/jbuild= will be run from
|
||||
=_build/<context>/src/foo=.
|
||||
|
@ -983,7 +982,7 @@ the root of your project. What you should write instead is:
|
|||
** jbuild-ignore
|
||||
|
||||
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.
|
||||
|
||||
So for instance, if you write =foo= in =src/jbuild-ignore=, then
|
||||
|
@ -1133,7 +1132,7 @@ list given to =jbuilder=.
|
|||
** Invocation from opam
|
||||
|
||||
You should set the =build:= field of your =<package>.opam= file as
|
||||
follow:
|
||||
follows:
|
||||
|
||||
#+begin_src
|
||||
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
|
||||
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
|
||||
(context ((switch <opam-switch-name>)
|
||||
|
@ -1187,7 +1186,7 @@ description of an opam switch, as follow:
|
|||
|
||||
=<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
|
||||
|
||||
- =(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
|
||||
|
||||
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
|
||||
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
|
||||
|
@ -1249,7 +1248,7 @@ use it instead of =ocaml-migrate-parsetree.driver-main=, simply write
|
|||
****** Driver expectation
|
||||
|
||||
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
|
||||
ppx.exe <flags-written-by-user> --dump-ast -o <output-file> [--impl|--intf] <source-file>
|
||||
|
|
Loading…
Reference in New Issue