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

Improve wording and fix typos in documentation

This commit is contained in:
Adrien Guatto 2017-03-27 20:05:59 -04:00 committed by Jérémie Dimino
parent 6ce4d54274
commit c05f410b75
2 changed files with 64 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
README.org
View File

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

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