Usage¶

This section describe usage of Jbuilder from the shell.

Finding the root¶

jbuild-workspace¶

The root of the current workspace is determined by looking up a jbuild-workspace file in the current directory and parent directories. jbuilder prints out the root when starting:

$ jbuilder runtest
Workspace root: /usr/local/home/jdimino/workspaces/public-jane/+share+
...

More precisely, it will choose the outermost ancestor directory containing a jbuild-workspace file as root. For instance if you are in /home/me/code/myproject/src, then jbuilder will look for all these files in order:

/jbuild-workspace
/home/jbuild-workspace
/home/me/jbuild-workspace
/home/me/code/jbuild-workspace
/home/me/code/myproject/jbuild-workspace
/home/me/code/myproject/src/jbuild-workspace

The first entry to match in this list will determine the root. In practice this means that if you nest your workspaces, Jbuilder will always use the outermost one.

In addition to determining the root, jbuilder will read this file as to setup the configuration of the workspace unless the --workspace command line option is used. See the section about workspace configuration for the syntax of this file.

jbuild-workspace*¶

In addition to the previous rule, if no jbuild-workspace file is found, jbuilder will look for any file whose name starts with jbuild-workspace in ancestor directories. For instance jbuild-workspace.dev. If such a file is found, it will mark the root of the workspace. jbuilder will however not read its contents.

The rationale for this rule is that it is good practice to have a jbuild-workspace.dev file at the root of your project.

For quick experiments, simply do this to mark the root:

$ touch jbuild-workspace.here

Current directory¶

If none of the two previous rules appies, i.e. no ancestor directories have a file whose name starts with jbuild-workspace, then the current directory will be used as root.

Forcing the root (for scripts)¶

You can pass the --root option to jbuilder to select the root explicitly. 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:

$ jbuilder build _build/default/bin/prog.exe

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:

$ 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

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

Finding external libraries¶

When a library is not available in the workspace, jbuilder will look it up in the installed world, and expect it to be already compiled.

It looks up external libraries using a specific list of search pathes. A list of search pathes is specific to a given build context and is determined as follow:

if the ocamlfind is present in the PATH of the context, use each line in the output of ocamlfind printconf path as a search path
otherwise, if opam is present in the PATH, use the outout of opam config var lib
otherwise, take the directory where ocamlc was found, and append ../lib to it. For instance if ocamlc is found in /usr/bin, use /usr/lib

Running tests¶

There are two ways to run tests:

jbuilder build @runtest
jbuilder runtest

The two commands are equivalent. They will run all the tests defined in the current directory and its children recursively. You can also run the tests in a specific sub-directory and its children by using:

jbuilder build @foo/bar/runtest
jbuidler runtest foo/bar

Restricting the set of packages¶

You can restrict the set of packages from your workspace that Jbuilder can see with the --only-packages option:

$ jbuilder build --only-packages pkg1,pkg2,... @install

This option acts as if you went through all the jbuild files and commented out the stanzas refering to a package that is not in the list given to jbuilder.

Invocation from opam¶

You should set the build: field of your <package>.opam file as follows:

build: [["jbuilder" "build" "-p" name "-j" jobs]]

-p pkg is a shorthand for --root . --only-packages pkg. -p is the short version of --for-release-of-packages.

This has the following effects:

it tells jbuilder to build everything that is installable and to ignore packages other than name defined in your project
it sets the root to prevent jbuilder from looking it up
it uses whatever concurrency option opam provides

Note that name and jobs are variables expanded by opam. name expands to the package name and jobs to the number of jobs available to build the package.

Tests¶

To setup the building and running of tests in opam, add this line to your <package>.opam file:

build-test: [["jbuilder" "runtest" "-p" name "-j" jobs]]

Installation¶

Installing a package means copying the build artifacts from the build directory to the installed word.

When installing via opam, you don’t need to worry about this step: jbuilder generates a <package>.install file that opam will automatically read to handle installation.

However, when not using opam or doing local development, you can use jbuilder to install the artifacts by hands. To do that, use the install command:

$ jbuilder install [PACKAGE]...

without an argument, it will install all the packages available in the workspace. With a specific list of packages, it will only install these packages. If several build contexts are configured, the installation will be performed for all of them.

Note that jbuilder install is a thin wrapper around the opam-installer tool, so you will need to install this tool in order to be able to use jbuilder install.

Destination¶

The place where the build artifacts are copied, usually referred as prefix, is determined as follow for a given build context:

if an explicit --prefix <path> argument is passed, use this path
if opam is present in the PATH, use the output of opam config var prefix
otherwise, take the directory where ocamlc was found, and append ../lib to it. For instance if ocamlc is found in /usr/bin, use /usr

Note that --prefix is only supported if a single build context is in use.

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:

$ jbuilder build --workspace jbuild-workspace.dev @install @runtest

jbuild-workspace¶

The jbuild-workspace file uses the S-expression syntax. This is what a typical jbuild-workspace file looks like:

(context ((switch 4.02.3)))
(context ((switch 4.03.0)))
(context ((switch 4.04.0)))

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 follows:

(context ((switch <opam-switch-name>)
          <optional-fields>))

<optional-fields> are:

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

Building JavaScript with js_of_ocaml¶

Jbuilder knows how to generate a JavaScript version of an executable (<name>.bc.js) using the js_of_ocaml compiler (the js_of_ocaml-compiler opam package must be installed).

It supports two modes of compilation:

Direct compilation of a bytecode program to JavaScript. This mode allows js_of_ocaml to perform whole program deadcode elimination and whole program inlining.
Separate compilation, where compilation units are compiled to JavaScript separately and then linked together. This mode is useful during development as it builds more quickly.

The separate compilation mode will be selected when passing --dev to jbuilder. There is currently no other way to control this behaviour.

See the section about js_of_ocalm for passing custom flags to the js_of_ocaml compiler

Using topkg with jbuilder¶

Jbuilder provides suport for building and installing your project. However it doesn’t provides helpers for distributing it. It is recommemded to use Topkg for this purpose.

The topkg-jbuilder project provides helpers for using Topkg in a Jbuilder project.