Ocamlbuild has rules which say how to build targets. These rules are similar to those of a Makefile: they contain a list of dependencies, a list of productions, and the command that build the productions.
When trying to build a target, Ocamlbuild looks for all rules that are valid for this target. A rule is valid for a given target if, and only if:
- its dependencies can be built (i.e. there is a valid rule for each dependency),
- the target name matches one of the rule's productions.
The tags of the target or the dependencies have no effect on whether a rule is valid or not.
Then, Ocamlbuild tries the first valid rule. Because rules can discover new dependencies, they can fail if there is no valid rule to make the new dependencies. In this case, Ocamlbuild continues with the next valid rule, until a rule succeeds. If all valid rules fail, then the solver fails to build the target.
A rule can generate new dependencies at run-time. For example, imagine
you use the following
When executing the following command: ocamlbuild example.otarget
- Ocamlbuild looks for rules which match
example.otargetas a target.
- There is one such rule, which has one single dependency:
- The file
example.itargetalready exists, so there is no need to build it: the rule is valid, and it is executed.
- The file
example.itargetis read, and the rule adds two dependencies:
Ocamlbuildtries to build these new dependencies before finishing to build
To understand how the solver works, you can simply run Ocamlbuild
using a command such as:
ocamlbuild -classic-display -verbose 10 target.
You'll get both the backtrace in case of a failure, and the actual names
and order of the rules that are triggered.
This is especially useful if you are developing a plugin and are adding new rules.
All files have tags associated to them. This is the easiest way to
change the behaviour of the rules. To add or delete tags from a file,
When a rule is triggered, the tags of the files may modify the command of the rule. Commands come with holes in them; these holes are lists of tags that are replaced by the corresponding options.
For instance, the
ocamlc command used to compile an
.ml file to a
.cmo file contains a hole. This hole contains the tags of the
file, along with some other tags such as
When a hole contains the tags
-thread option is added to the command, in place of the hole.
So if you try to compile an
.ml file which is tagged with the
tag, then the file will be compiled using the
Some tags, such as
precious, are not used in holes.
In fact, if you program your own plugin, you may use tags in any way
that suits your needs. But remember that fancy stuff makes it difficult
to understand the semantics of your tag!