more doc
This commit is contained in:
parent
16bd433e4e
commit
d338bdd134
136
doc/manual.org
136
doc/manual.org
|
@ -896,7 +896,14 @@ This section describe usage of Jbuilder from the shell.
|
||||||
** Finding the root
|
** Finding the root
|
||||||
|
|
||||||
The root of the current workspace is determined by looking up specific
|
The root of the current workspace is determined by looking up specific
|
||||||
files/directories in the current directory and parent directories.
|
files/directories in the current directory and parent
|
||||||
|
directories. =jbuilder= prints out the root when starting:
|
||||||
|
|
||||||
|
#+begin_src sh
|
||||||
|
$ jbuilder runtest
|
||||||
|
Workspace root: /usr/local/home/jdimino/workspaces/public-jane/+share+
|
||||||
|
...
|
||||||
|
#+end_src
|
||||||
|
|
||||||
More precisely, consider the current directory and all its
|
More precisely, consider the current directory and all its
|
||||||
ancestors. For instance if you are in =/home/me/code/myproject/src=,
|
ancestors. For instance if you are in =/home/me/code/myproject/src=,
|
||||||
|
@ -909,12 +916,135 @@ then this is this set:
|
||||||
- =/home=
|
- =/home=
|
||||||
- =/=
|
- =/=
|
||||||
|
|
||||||
Jbuilder looks for the following entries in all these directories:
|
Jbuilder looks for the following entries in all these directories, in
|
||||||
|
order of precedences:
|
||||||
|
|
||||||
1. jbuild-workspace
|
1. =jbuild-workspace=
|
||||||
2. any file ending with =.install=
|
2. any file ending with =.install=
|
||||||
3. =.git= or =.hg=
|
3. =.git= or =.hg=
|
||||||
|
|
||||||
|
The first entry to match in this list will determine the root. If this
|
||||||
|
entry is present in several of the looked up directories, the one with
|
||||||
|
the smallest name will be used. In practice this means that if you
|
||||||
|
nest your workspaces, Jbuilder will always use the toplevel one.
|
||||||
|
|
||||||
|
*** Forcing the root (for scripts)
|
||||||
|
|
||||||
|
You can pass the =--root= option to =jbuilder= to select the root
|
||||||
|
explicitely. 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.
|
||||||
|
|
||||||
|
** Interpretation of targets
|
||||||
|
|
||||||
|
This section describes how =jbuilder= interprets the targets given on
|
||||||
|
the command line.
|
||||||
|
|
||||||
|
*** Resolution
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
As a result, if you want to ask =jbuilder= to produce a particular
|
||||||
|
=.exe= file you would have to type:
|
||||||
|
|
||||||
|
#+begin_src sh
|
||||||
|
$ jbuilder build _build/default/bin/prog.exe
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
#+begin_src sh
|
||||||
|
$ jbuilder build bin/prog.exe
|
||||||
|
...
|
||||||
|
Actual targets:
|
||||||
|
- _build/default/bin/prog.exe
|
||||||
|
- _build/4.03.0/bin/prog.exe
|
||||||
|
- _build/4.04.0/bin/prog.exe
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
*** Aliases
|
||||||
|
|
||||||
|
Targets starting with a =@= are interpreted as aliases. For instance
|
||||||
|
=@src/runtest= means the alias =src/runtest=. If you want to refer to
|
||||||
|
a target starting with a =@=, simply write: =./@foo=.
|
||||||
|
|
||||||
|
Note that an alias not pointing to the =_build= directory always
|
||||||
|
depends on all the corresponding aliases in build contexts.
|
||||||
|
|
||||||
|
So for instance:
|
||||||
|
|
||||||
|
- =jbuilder build @_build/foo/runtest= will run the tests only for the
|
||||||
|
=foo= build context
|
||||||
|
- =jbuilder build @runtest= will run the tests for all build contexts
|
||||||
|
|
||||||
|
** Workspace configuration
|
||||||
|
|
||||||
|
By default, a workspace has only one build context named =default=
|
||||||
|
which correspond to the environment in which =jbuilder= is run. You
|
||||||
|
can define more contexts by writing a =jbuild-workspace= file.
|
||||||
|
|
||||||
|
You can point =jbuilder= to an explicit =jbuild-workspace= file with
|
||||||
|
the =--workspace= option. For instance it is good practice to write a
|
||||||
|
=jbuild-workspace.dev= in your project with all the version of OCaml
|
||||||
|
your projects support. This way developpers can tests that the code
|
||||||
|
builds with all version of OCaml by simply running:
|
||||||
|
|
||||||
|
#+begin_src sh
|
||||||
|
$ jbuilder build --workspace jbuild-workspace.dev @install @runtest
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
*** jbuild-workspace
|
||||||
|
|
||||||
|
The =jbuild-workspace= file uses the S-expression syntax. This is what
|
||||||
|
a typical =jbuild-workspace= file looks like:
|
||||||
|
|
||||||
|
#+begin_src scheme
|
||||||
|
(context ((switch 4.02.3)))
|
||||||
|
(context ((switch 4.03.0)))
|
||||||
|
(context ((switch 4.04.0)))
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
The rest of this section describe the stanzas available.
|
||||||
|
|
||||||
|
**** context
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
#+begin_src scheme
|
||||||
|
(context ((switch <opam-switch-name>)
|
||||||
|
<optional-fields>))
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
=<optional-fields>= are:
|
||||||
|
|
||||||
|
- =(name <name>)= is the name of the sub-directory 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
|
||||||
|
opam root defined by the environment in which =jbuilder= is run
|
||||||
|
which is usually =~/.opam=
|
||||||
|
|
||||||
|
- =(merlin)= instructs Jbuilder to generate the =.merlin= files from
|
||||||
|
this context. There can be at most one build context with a
|
||||||
|
=(merlin)= field. If no build context has a =(merlin)= field, the
|
||||||
|
selected context for =merlin= will be =(context default)= if
|
||||||
|
present. Otherwise Jbuilder won't generate =.merlin= files
|
||||||
|
|
||||||
* Advanced topics
|
* Advanced topics
|
||||||
|
|
||||||
This section describes some details of Jbuilder for advanced users.
|
This section describes some details of Jbuilder for advanced users.
|
||||||
|
|
Loading…
Reference in New Issue