2017-05-14 00:10:00 +00:00
|
|
|
*****************************************
|
|
|
|
Project Layout and Metadata Specification
|
|
|
|
*****************************************
|
|
|
|
|
|
|
|
A typical jbuilder project will have one or more ``<package>.opam`` file
|
|
|
|
at toplevel as well as ``jbuild`` files wherever interesting things are:
|
|
|
|
libraries, executables, tests, documents to install, etc...
|
|
|
|
|
|
|
|
It is recommended to organize your project so that you have exactly one
|
|
|
|
library per directory. You can have several executables in the same
|
|
|
|
directory, as long as they share the same build configuration. If you'd
|
|
|
|
like to have multiple executables with different configurations in the
|
|
|
|
same directory, you will have to make an explicit module list for every
|
|
|
|
executable using ``modules``.
|
|
|
|
|
|
|
|
The next sections describe the format of Jbuilder metadata files.
|
|
|
|
|
|
|
|
Note that the Jbuilder metadata format is versioned in order to ensure
|
2017-05-29 08:54:56 +00:00
|
|
|
forward compatibility. There is currently only one version available,
|
|
|
|
but to be future proof, you should still specify it in your ``jbuild``
|
|
|
|
files. If no version is specified, the latest one will be used.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
2017-05-29 09:05:04 +00:00
|
|
|
.. _metadata-format:
|
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
Metadata format
|
|
|
|
===============
|
|
|
|
|
|
|
|
Most configuration files read by Jbuilder are using the S-expression
|
|
|
|
syntax, which is very simple. Everything is either an atom or a list.
|
|
|
|
The exact specification of S-expressions is described in the
|
|
|
|
documentation of the `parsexp <https://github.com/janestreet/parsexp>`__
|
|
|
|
library.
|
|
|
|
|
2017-06-17 16:06:58 +00:00
|
|
|
In a nutshell, the syntax is as follows:
|
2017-05-29 09:05:04 +00:00
|
|
|
|
|
|
|
- atoms that do no contain special characters are simply written as
|
2017-06-17 16:06:58 +00:00
|
|
|
is. For instance: ``foo``, ``bar`` are valid atomic S-expressions
|
2017-05-29 09:05:04 +00:00
|
|
|
|
|
|
|
- atoms containing special characters or spaces must be quoted using
|
|
|
|
the syntax ``"..."``: ``"foo bar\n"``
|
|
|
|
|
|
|
|
- lists are formed by surrounding a sequence of S-expressions separated
|
|
|
|
by spaces with parentheses: ``(a b (c d))``
|
|
|
|
|
|
|
|
- single-line comments are introduced with the ``;`` character and may
|
|
|
|
appear anywhere except in the middle of a quoted atom
|
|
|
|
|
|
|
|
- block comment are enclosed by ``#|`` and ``|#`` and can be nested
|
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
Note that the format is completely static. However you can do
|
2017-05-18 20:15:49 +00:00
|
|
|
meta-programming on jbuilds files by writing them in :ref:`ocaml-syntax`.
|
|
|
|
|
|
|
|
.. _opam-files:
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
<package>.opam files
|
|
|
|
====================
|
|
|
|
|
|
|
|
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 `opam <https://opam.ocaml.org/>`__. Jbuilder also defines the
|
|
|
|
recursive ``install`` alias, which depends on all the buildable
|
|
|
|
``<package>.install`` files in the workspace. So for instance to build
|
|
|
|
everything that is installable in a workspace, run at the root:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
$ jbuilder build @install
|
|
|
|
|
|
|
|
Declaring a package this way will allow you to add elements such as
|
2017-06-17 16:06:58 +00:00
|
|
|
libraries, executables, documentation, ... to your package by declaring
|
2017-05-14 00:10:00 +00:00
|
|
|
them in ``jbuild`` files.
|
|
|
|
|
2017-06-05 11:33:45 +00:00
|
|
|
Such elements can only be declared in the scope defined by the
|
2017-06-17 16:06:58 +00:00
|
|
|
corresponding ``<package>.opam`` file. Typically, your
|
2017-05-14 00:10:00 +00:00
|
|
|
``<package>.opam`` files should be at the root of your project, since
|
|
|
|
this is where ``opam pin ...`` will look for them.
|
|
|
|
|
2017-06-17 16:06:58 +00:00
|
|
|
Note that ``<package>`` must be non-empty, so in particular ``.opam``
|
2017-05-14 00:10:00 +00:00
|
|
|
files are ignored.
|
|
|
|
|
2017-06-05 11:33:45 +00:00
|
|
|
.. _scopes:
|
|
|
|
|
|
|
|
Scopes
|
|
|
|
------
|
|
|
|
|
|
|
|
Any directory containing at least one ``<package>.opam`` file defines
|
|
|
|
a scope. This scope is the sub-tree starting from this directory,
|
|
|
|
excluding any other scopes rooted in sub-direcotries.
|
|
|
|
|
|
|
|
Typically, any given project will define a single scope. Libraries and
|
|
|
|
executables that are not meant to be installed will be visible inside
|
|
|
|
this scope only.
|
|
|
|
|
|
|
|
Because scopes are exclusive, if you whish to include the dependencies
|
|
|
|
of the project you are currently working on into your workspace, you
|
|
|
|
may copy them in a ``vendor`` directory, or any other name of your
|
|
|
|
choice. Jbuilder will look for them there rather than in the installed
|
|
|
|
world and there will be no overlap between the various scopes.
|
|
|
|
|
2017-05-14 00:10:00 +00:00
|
|
|
Package version
|
|
|
|
---------------
|
|
|
|
|
|
|
|
Note that Jbuilder will try to determine the version number of packages
|
|
|
|
defined in the workspace. While Jbuilder itself makes no use of version
|
|
|
|
numbers, it can be use by external tools such as
|
|
|
|
`ocamlfind <http://projects.camlcity.org/projects/findlib.html>`__.
|
|
|
|
|
|
|
|
Jbuilder determines the version of a package by first looking in the
|
|
|
|
``<package>.opam`` for a ``version`` variable. If not found, it will try
|
|
|
|
to read the first line of a version file in the same directory as the
|
|
|
|
``<package>.opam`` file. The version file is any file whose name is, in
|
|
|
|
order in which they are looked for:
|
|
|
|
|
|
|
|
- ``<package>.version``
|
|
|
|
- ``version``
|
|
|
|
- ``VERSION``
|
|
|
|
|
|
|
|
The version file can be generated by a user rule.
|
|
|
|
|
|
|
|
If the version can't be determined, Jbuilder just won't assign one.
|
|
|
|
|
|
|
|
Note that if you are using `Topkg <https://github.com/dbuenzli/topkg>`__
|
|
|
|
as well in your project, you shouldn't manually set a version in your
|
|
|
|
``<package>.opam`` file or write/generate on of the file listed above.
|
2017-05-18 20:15:49 +00:00
|
|
|
See the section about :ref:`using-topkg` for more details.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
Odig conventions
|
|
|
|
----------------
|
|
|
|
|
|
|
|
Jbuilder follows the `odig <http://erratique.ch/software/odig>`__
|
|
|
|
conventions and automatically installs any README\*, CHANGE\*, HISTORY\*
|
|
|
|
and LICENSE\* files in the same directory as the ``<package>.opam`` file
|
|
|
|
to a location where odig will find them.
|
|
|
|
|
2017-06-17 16:06:58 +00:00
|
|
|
Note that this includes files present in the source tree as well as
|
2017-05-14 00:10:00 +00:00
|
|
|
generated files. So for instance a changelog generated by a user rule
|
|
|
|
will be automatically installed as well.
|
|
|
|
|
|
|
|
jbuild-ignore
|
|
|
|
=============
|
|
|
|
|
2017-05-19 11:36:06 +00:00
|
|
|
By default Jbuilder traverses the whole source tree, ignoring the
|
|
|
|
following files and directories:
|
|
|
|
|
|
|
|
- any file that start with ``.#``
|
|
|
|
- any directory that start with either ``.`` or ``_``
|
|
|
|
|
|
|
|
To ignore a subtree, simply write a ``jbuild-ignore`` file in the
|
|
|
|
parent directory containing the name of the sub-directories to ignore.
|
2017-05-14 00:10:00 +00:00
|
|
|
|
|
|
|
So for instance, if you write ``foo`` in ``src/jbuild-ignore``, then
|
|
|
|
``src/foo`` won't be traversed and any ``jbuild`` file it contains will
|
|
|
|
be ignored.
|
|
|
|
|
|
|
|
``jbuild-ignore`` files contain a list of directory names, one per line.
|