more doc

doc/manual.org

@@ -896,7 +896,14 @@ This section describe usage of Jbuilder from the shell.
 ** Finding the root
 
 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
 ancestors. For instance if you are in =/home/me/code/myproject/src=,
@@ -909,12 +916,135 @@ then this is this set:
 - =/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=
 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
 
 This section describes some details of Jbuilder for advanced users.