<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.00">
<link rel="stylesheet" type="text/css" href="manual.css">
<title>The ocamlbuild compilation manager</title>
</head>
<body>
<a href="profil.html"><img src="previous_motif.gif" alt="Previous"></a>
<a href="index.html"><img src="contents_motif.gif" alt="Up"></a>
<a href="intfc.html"><img src="next_motif.gif" alt="Next"></a>
<hr>
<h1 class="chapter" id="sec370">Chapter 18  The ocamlbuild compilation manager</h1>
<ul>
<li><a href="ocamlbuild.html#sec371">Features of <span class="c007">ocamlbuild</span></a>
</li><li><a href="ocamlbuild.html#sec372">Limitations</a>
</li><li><a href="ocamlbuild.html#sec373">Using <span class="c007">ocamlbuild</span></a>
</li><li><a href="ocamlbuild.html#sec402">Appendix: Motivations</a>
</li><li><a href="ocamlbuild.html#sec403">Appendix: Summary of default rules</a>
</li></ul>
<p> <a id="c:ocamlbuild"></a>
</p><p><span class="c013">(Chapter written by Berke Durak and Nicolas Pouillard)</span></p><p><br>
<br>
</p><p><span class="c007">ocamlbuild</span> is a tool automating the compilation of most OCaml projects with minimal
user input. Its use is not restricted to projects having a simple structure –
the extra effort needed to make it work with the more complex projects is in
reasonable proportion with their added complexity. In practice, one will use a
set of small text files, and, if needed, an OCaml compilation module that can
fine-tune the behaviour and define custom rules.</p>
<h2 class="section" id="sec371">18.1  Features of <span class="c007">ocamlbuild</span></h2>
<p>
<em>This section is intended to read like a sales brochure or a datasheet.</em></p><ul class="itemize"><li class="li-itemize">
Built-in compilation rules for OCaml projects handle all the nasty cases:
native and byte-code, missing <span class="c007">.mli</span> files, preprocessor rules,
libraries, package (-pack) debugging and profiling flags, C stubs.
</li><li class="li-itemize">Plugin mechanism for writing compilation rules and actions in a real programming language,
OCaml itself.
</li><li class="li-itemize">Automatic inference of dependencies.
</li><li class="li-itemize">Correct handling of dynamically discovered dependencies.
</li><li class="li-itemize">Object files and other temporary files are created in a specific directory, leaving your main directory uncluttered.
</li><li class="li-itemize">Sanity checks ensure that object files are where they are supposed to be: in the build directory.
</li><li class="li-itemize">Regular projects are built using a single command with no extra files.
</li><li class="li-itemize">Parallel compilation to speed up things on multi-core systems.
</li><li class="li-itemize">Sophisticated display mode to keep your screen free of boring and repetitive compilation message
while giving you important progress information in a glimpse, and correctly multiplexing the error messages.
</li><li class="li-itemize">Tags and flags provide a concise and convenient mechanism for automatic selection of compilation, preprocessing and
other options.
</li><li class="li-itemize">Extended shell-like glob patterns, that can be combined using boolean operators,
allow you to concisely define the tags that apply to a given file.
</li><li class="li-itemize">Mechanisms for defining the mutual visibility of subdirectories.
</li><li class="li-itemize">Cache mechanism avoiding unnecessary compilations where reasonably computable.
</li></ul>
<h2 class="section" id="sec372">18.2  Limitations</h2>
<p>
<em>Not perfect nor complete yet, but already pretty damn useful.</em></p><p>We were not expecting to write the ultimate compilation tool in a few man-months, however we believe we have
a tool that solves many compilation problems, especially our own, in a satisfactory way. Hence there are a
lot of missing features, incomplete options and hideous bugs lurking in <span class="c007">ocamlbuild</span>, and we hope that the OCaml community
will find our first try at <span class="c007">ocamlbuild</span> useful and hopefully help it grow into a tool that satisfies most needs of most users
by providing feedback, bug reports and patches.</p><p>The plugin API maybe somewhat lacking in maturity, as it has only been tested
by a few people. We believe a good API can only evolve under pressure from
many peers and the courage to rewrite things cleanly when time is ripe by the
developers. Most of the important functions a user will need are encapsulated
in the plugin API, which is the <span class="c007">Ocamlbuild_plugin</span> module pack. We
intend to keep that API backwards compatible. It may happen that intricate
projects need features not available in that module – you may then use
functions or values directly from the core <span class="c007">ocamlbuild</span> modules. We ask you to report
such usage to the authors so that we may make the necessary changes to the API;
you may also want to isolate calls to the non-API parts of the <span class="c007">ocamlbuild</span> library
from the rest of your plugin to be able to keep the later when incompatible
changes arise.</p><p>The way that <span class="c007">ocamlbuild</span> handles the command-line options, the <span class="c007">_tags</span> file,
the target names, names of the tags, and so on, are not expected to change in
incompatible ways. We intend to keep a project that compiles without a plugin
compilable without modifications in the future.
</p>
<h2 class="section" id="sec373">18.3  Using <span class="c007">ocamlbuild</span></h2>
<p>
<em>Learn how to use <span class="c007">ocamlbuild</span> with short, specific, straight-to-the-point examples.</em></p><p>The amount of time and effort spent on the compilation process of a project
should be proportionate to that spent on the project itself. It should be easy
to set up a small project, maybe a little harder for a medium-sized project,
and it may take some more time, but not too much, for a big project. Ideally
setting up a big project would be as easy as setting up a small project. However,
as projects grow, modularization techniques start to be used, and the probability
of using meta programming or multiple programming languages increases, thus making
the compilation process more delicate.</p><p><span class="c007">ocamlbuild</span> is intended to be very easy to use for projects, large or small, with a simple
compilation process: typing
<span class="c007">ocamlbuild foo.native</span> should be enough to compile the native version
of a program whose top module is <span class="c007">foo.ml</span> and whose dependencies are in
the same directory. As your project gets more complex, you will gradually
start to use command-line options to specify libraries to link with, then
configuration files, ultimately culminating in a custom OCaml plugin for
complex projects with arbitrary dependencies and actions.</p>
<h3 class="subsection" id="sec374">18.3.1  Hygiene & where is my code ?</h3>
<p>
Your code is in the <span class="c007">_build</span> directory, but <span class="c007">ocamlbuild</span> automatically creates
a symbolic link to the executables it produces in the current directory.
<span class="c007">ocamlbuild</span> copies the source files and compiles them in a separate directory
which is <span class="c007">_build</span> by default.</p><p>For <span class="c007">ocamlbuild</span>, any file that is not in the build directory is a source file.
It is not unreasonable to think that some users may have bought binary object files
they keep in their project directory. Usually binary files cluttering the project
directory are due to previous builds using other systems. <span class="c007">ocamlbuild</span> has so-called
“hygiene” rules that state that object files (<span class="c007">.cmo</span>, <span class="c007">.cmi</span>,
or <span class="c007">.o</span> files, for instance) must not appear outside of the build
directory. These rules are enforced at startup; any violations will be reported
and <span class="c007">ocamlbuild</span> will exit. You must then remove these files by hand or run, with caution,
the script <span class="c007">sanitize.sh</span>, which is generated in your source directory.
This script will contain commands to remove them for you.</p><p>To disable these checks, you can use the <span class="c007">-no-hygiene</span> flag. If you have
files that must elude the hygiene squad, just tag them with <span class="c007">precious</span>
or <span class="c007">not_hygienic</span>.
</p>
<h3 class="subsection" id="sec375">18.3.2  Hello, world !</h3>
<p>
Assuming we are in a directory named <span class="c007">example1</span> containing one file <span class="c007">hello.ml</span>
whose contents are
</p><pre>let _ =
Printf.printf "Hello, %s ! My name is %s\n"
(if Array.length Sys.argv > 1 then Sys.argv.(1) else "stranger")
Sys.argv.(0)
;;
</pre><p>we can compile and link it into a native executable by invoking <span class="c007">ocamlbuild hello.native</span>.
Here, <span class="c007">hello</span> is the basename of the top-level module and <span class="c007">native</span> is an extension used
by <span class="c007">ocamlbuild</span> to denote native code executables.
</p><pre>% ls
hello.ml
% ocamlbuild hello.native
Finished, 4 targets (0 cached) in 00:00:00.
% ls -l
total 12
drwxrwx--- 2 linus gallium 4096 2007-01-17 16:24 _build/
-rw-rw---- 1 linus gallium 43 2007-01-17 16:23 hello.ml
lrwxrwxrwx 1 linus gallium 19 2007-01-17 16:24 hello.native -> _build/hello.native*
</pre><p>What’s this funny <span class="c007">_build</span> directory ? Well that’s where <span class="c007">ocamlbuild</span> does its dirty work
of compiling. You usually won’t have to look very often into this directory. Source files are copied
into <span class="c007">_build</span> and this is where the compilers will be run. Various cache files are also stored
there. Its contents may look like this:
</p><pre>% ls -l _build
total 208
-rw-rw---- 1 linus gallium 337 2007-01-17 16:24 _digests
-rw-rw---- 1 linus gallium 191 2007-01-17 16:24 hello.cmi
-rw-rw---- 1 linus gallium 262 2007-01-17 16:24 hello.cmo
-rw-rw---- 1 linus gallium 225 2007-01-17 16:24 hello.cmx
-rw-rw---- 1 linus gallium 43 2007-01-17 16:23 hello.ml
-rw-rw---- 1 linus gallium 17 2007-01-17 16:24 hello.ml.depends
-rwxrwx--- 1 linus gallium 173528 2007-01-17 16:24 hello.native*
-rw-rw---- 1 linus gallium 936 2007-01-17 16:24 hello.o
-rw-rw---- 1 linus gallium 22 2007-01-17 16:24 ocamlc.where
</pre>
<h3 class="subsection" id="sec376">18.3.3  Executing my code</h3>
<p>
You can execute your code the old-fashioned way (<span class="c007">./hello.native</span>).
You may also type
</p><pre>ocamlbuild hello.native -- Caesar
</pre><p>and it will compile and then run <span class="c007">hello.native</span> with the arguments following <span class="c007">--</span>,
which should display:
</p><pre>% ocamlbuild hello.native -- Caesar
Finished, 4 targets (0 cached) in 00:00:00.
Hello, Caesar ! My name is _build/hello.native
</pre>
<h3 class="subsection" id="sec377">18.3.4  The log file, verbosity and debugging</h3>
<p>
By default, if you run <span class="c007">ocamlbuild</span> on a terminal, it will use some ANSI escape sequences
to display a nice, one-line progress indicator. To see what commands <span class="c007">ocamlbuild</span> has actually run,
you can check the contents of the <span class="c007">_build/_log</span> file. To change the name of the
log file or to disable logging, use the <span class="c007">-log <file></span> or <span class="c007">-no-log</span> options.
Note that the log file is truncated at each execution of <span class="c007">ocamlbuild</span>.</p><p>The log file contains all the external commands that <span class="c007">ocamlbuild</span> ran or intended to
run along with the target name and the computed tags. With the
<span class="c007">-verbose <level></span> option, <span class="c007">ocamlbuild</span> will also write more or less useful
debugging information; a verbosity level of 1 (which can also be specified
using the <span class="c007">-verbose</span> switch) prints generally useful information; higher
levels produce much more output.
</p>
<h3 class="subsection" id="sec378">18.3.5  Cleaning</h3>
<p>
<span class="c007">ocamlbuild</span> may leave a <span class="c007">_build</span> directory and symbolic links to executables in
that directory (unless when using -no-links). All of these can be removed safely
by hand, or by invoking <span class="c007">ocamlbuild</span> with the <span class="c007">-clean</span> flag.
</p>
<h3 class="subsection" id="sec379">18.3.6  Where and how to run <span class="c007">ocamlbuild</span>?</h3>
<p>
An important point is that <span class="c007">ocamlbuild</span> must be invoked from the root of the project,
even if this project has multiple, nested subdirectories. This is because <span class="c007">ocamlbuild</span> likes to store the object files in a single <span class="c007">_build</span> directory. You
can change the name of that directory with the <span class="c007">-build-dir</span> option.</p><p><span class="c007">ocamlbuild</span> can be either invoked manually from the UNIX or Windows shell, or
automatically from a build script or a Makefile. Unless run with the
<span class="c007">-no-hygiene</span> option, there is the possibility that <span class="c007">ocamlbuild</span> will prompt the
user for a response. By default, on UNIX systems, if <span class="c007">ocamlbuild</span> senses that the
standard output is a terminal, it will use a nice progress indicator using ANSI
codes, instrumenting the output of the processes it spawns to have a consistent
display. Under non-UNIX systems, or if the standard output is not a terminal,
it will run in classic mode where it will echo the executed commands on its
standard output. This selection can be overridden with the <span class="c007">-classic-display</span> option.
</p>
<h3 class="subsection" id="sec380">18.3.7  Dependencies</h3>
<p>
<em>Dependencies are automatically discovered.</em></p><p>Most of the value of <span class="c007">ocamlbuild</span> lies in the fact that it often needs no extra
information to compile a project besides the name of the top-level module.
<span class="c007">ocamlbuild</span> calls <span class="c007">ocamldep</span> to automatically find the dependencies of any
modules it wants to compile. These dependencies are dynamically incorporated
in the dependency graph, something <span class="c007">make</span> cannot do.
For instance, let’s add a module <span class="c007">Greet</span> that implements various ways of
greeting people.
</p><pre>% cat greet.ml
type how = Nicely | Badly;;
let greet how who =
match how with Nicely -> Printf.printf "Hello, %s !\n" who
| Badly -> Printf.printf "Oh, here is that %s again.\n" who
;;
% cat hello.ml
open Greet
let _ =
let name =
if Array.length Sys.argv > 1 then
Sys.argv.(1)
else
"stranger"
in
greet
(if name = "Caesar" then Nicely else Badly)
name;
Printf.printf "My name is %s\n" Sys.argv.(0)
;;
</pre><p>Then the module <span class="c007">Hello</span> depends on the module <span class="c007">Greet</span> and <span class="c007">ocamlbuild</span> can
figure this out for himself – we still only have to invoke <span class="c007">ocamlbuild hello.native</span>. Needless to say, this works for any number of modules.
</p>
<h3 class="subsection" id="sec381">18.3.8  Native and byte-code</h3>
<p>
If we want to compile byte-code instead of native, we just a target name of
<span class="c007">hello.byte</span> instead of <span class="c007">hello.native</span>, i.e., we type
<span class="c007">ocamlbuild hello.byte</span>.
</p>
<h3 class="subsection" id="sec382">18.3.9  Compile flags</h3>
<p>
To pass a flag to the compiler, such as the <span class="c007">-rectypes</span> option,
use the <span class="c007">-cflag</span> option as in:
</p><pre>ocamlbuild -cflag -rectypes hello.native
</pre><p>You can put multiple <span class="c007">-cflag</span> options, they will be passed to the compiler
in the same order. You can also give them in a comma-separated list with the
<span class="c007">-cflags</span> option (notice the plural):
</p><pre>ocamlbuild -cflags -I,+lablgtk,-rectypes hello.native
</pre><p>These flags apply when compiling, that is, when producing <span class="c007">.cmi</span>,
<span class="c007">.cmo</span>,<span class="c007">.cmx</span> and <span class="c007">.o</span> files from <span class="c007">.ml</span> or
<span class="c007">.mli</span> files.
</p>
<h3 class="subsection" id="sec383">18.3.10  Link flags</h3>
<p>
Link flags apply when the various object files are collected and linked into
one executable. These will typically be include directories for libraries.
They are given using the <span class="c007">-lflag</span> and <span class="c007">-lflags</span> options, which
work in the same way as the <span class="c007">-cflag</span> and <span class="c007">-cflags</span> options.
</p>
<h3 class="subsection" id="sec384">18.3.11  Linking with external libraries</h3>
<p>
In our third example, we use one Unix system call and functions from the <span class="c007">num</span>
library:
</p><pre>% cat epoch.ml
let _ =
let s = Num.num_of_string (Printf.sprintf "%.0f" (Unix.gettimeofday ())) in
let ps = Num.mult_num (Num.num_of_string "1000000000000") s in
Printf.printf "%s picoseconds have passed since January 1st, 1970.\n"
(Num.string_of_num ps)
;;
</pre><p>This requires linking with the <span class="c007">unix</span> and <span class="c007">num</span> modules, which is accomplished
by using the <span class="c007">-lib unix</span> and <span class="c007">-lib num</span> flags, or, alternatively, <span class="c007">-libs unix,num</span>:
</p><pre>% ocamlbuild -libs nums,unix epoch.native --
Finished, 4 targets (4 cached) in 00:00:00.
1169051647000000000000 picoseconds have passed since January 1st, 1970.
</pre><p>You may need to add options such as <span class="c007">-cflags -I,/usr/local/lib/ocaml/</span>
and <span class="c007">-lflags -I,/usr/local/lib/ocaml/</span> if the libraries you wish to
link with are not in OCaml’s default search path.
</p>
<h3 class="subsection" id="sec385">18.3.12  The <span class="c007">_tags</span> files</h3>
<p>
Finer control over the compiler flags applied to each source file, such as
preprocessing, debugging, profiling and linking options, can be gained using
<span class="c007">ocamlbuild</span>’s tagging mechanism.</p><p>Every source file has a set of tags which tells <span class="c007">ocamlbuild</span> what kind of file it is
and what to do with it. A tag is simply a string, usually lowercase, for
example <span class="c007">ocaml</span> or <span class="c007">native</span>. The set of tags attached to a file
is computed by applying the tagging rules to the filename. Tagging rules are
defined in <span class="c007">_tags</span> files in any parent directory of a file, up to the main
project directory.</p><p>Each line in the <span class="c007">_tags</span> file is made of a glob pattern (see subsection
<a href="#subsec%3Aglob">18.3.13</a>) and a list of tags. More than one rule can apply to a file
and rules are applied in the order in which they appear in a file.
By preceding a tag with a minus sign, one may remove tags from one or more files.</p>
<h4 class="subsubsection" id="sec386">Example: the built-in <span class="c007">_tags</span> file</h4>
<pre> <**/*.ml> or <**/*.mli> or <**/*.mlpack> or <**/*.ml.depends>: ocaml
<**/*.byte>: ocaml, byte, program
<**/*.odoc>: ocaml, doc
<**/*.native>: ocaml, native, program
<**/*.cma>: ocaml, byte, library
<**/*.cmxa>: ocaml, native, library
<**/*.cmo>: ocaml, byte
<**/*.cmi>: ocaml, byte, native
<**/*.cmx>: ocaml, native
</pre><p>
Two special tags made from the path name of the file relative to the toplevel
of the project are automatically defined for each file. For a file
<span class="c007">foo/bar.ml</span> those tags will be <span class="c007">file:foo/bar.ml</span>, and
<span class="c007">extension:ml</span>.</p><p>If you do not have subdirectories, you can put <span class="c007">*.ml</span> instead of
<span class="c007">**/*.ml</span>.
</p>
<h3 class="subsection" id="sec387">18.3.13  Glob patterns and expressions</h3>
<p>
<a id="subsec:glob"></a>
Glob patterns have a syntax similar to those used by UNIX shells to select path
names (like <span class="c007">foo_*.ba?</span>). They are used in <span class="c007">ocamlbuild</span> to define the files
and directories to which tags apply. Glob expressions are glob patterns
enclosed in brackets <span class="c007"><</span> and <span class="c007">></span> combined using the standard
boolean operators <span class="c007">and</span>, <span class="c007">or</span>, <span class="c007">not</span>. This allows one to
describe sets of path names in more concise and more readable ways.</p><p>Please note that file and directory names are supposed to be made of the
following characters: <span class="c007">a</span>, …, <span class="c007">z</span>, <span class="c007">A</span>,
…, <span class="c007">Z</span>, <span class="c007">0</span>, …, <span class="c007">9</span>, <span class="c007">_</span>,
<span class="c007">-</span> and <span class="c007">.</span>. This is called the pathname alphabet <span class="c013">P</span>.</p><blockquote class="table"><div class="center"><hr class="c032"></div>
<div class="center">
<table class="c000 cellpadding1" border=1><tr><td class="c028"><span class="c012"><em> Formal syntax</em></span></td><td class="c029"><span class="c012"><em> Example</em></span></td><td class="c028"><span class="c012"><em>Matches</em></span></td><td class="c028"><span class="c012"><em>Does not match</em></span></td><td class="c028"><span class="c012"><em> Meaning (formal meaning) </em></span></td></tr>
<tr><td class="c028"><span class="c012"><span class="c013">u</span> <br>
A string of pathname characters</span></td><td class="c029"><span class="c012"> <span class="c007">foo.ml</span></span></td><td class="c028"><span class="c012"> <span class="c007">foo.ml</span></span></td><td class="c028"><span class="c012"> <span class="c007">fo.ml</span>, <span class="c007">bar/foo.ml</span></span></td><td class="c028"><span class="c012"> The exact string <span class="c013">u</span>
({ <span class="c013">u</span> }, where <span class="c013">u</span> ∈ <span class="c013">P</span></span><sup><span class="c012">*</span></sup><span class="c012">) </span></td></tr>
<tr><td class="c028"><span class="c012"><span class="c007">*</span> <br>
The wild-card star</span></td><td class="c029"><span class="c012"> <span class="c007">*</span></span></td><td class="c028"><span class="c012"> ε, <span class="c007">foo</span>, <span class="c007">bar</span></span></td><td class="c028"><span class="c012"> <span class="c007">foo/bar</span>, <span class="c007">/bar</span></span></td><td class="c028"><span class="c012"> Any string not containing a slash
(<span class="c013">P</span></span><sup><span class="c012">*</span></sup><span class="c012">) </span></td></tr>
<tr><td class="c028"><span class="c012"><span class="c007">?</span> <br>
The joker</span></td><td class="c029"><span class="c012"> <span class="c007">?</span></span></td><td class="c028"><span class="c012"> <span class="c007">a</span>, <span class="c007">b</span>, <span class="c007">z</span></span></td><td class="c028"><span class="c012"> <span class="c007">/</span>, <span class="c007">bar</span></span></td><td class="c028"><span class="c012"> Any one-letter string, excluding the slash </span></td></tr>
<tr><td class="c028"><span class="c012"><span class="c007">**/</span> <br>
The prefix inter-directory star</span></td><td class="c029"><span class="c012"> <span class="c007">**/foo.ml</span></span></td><td class="c028"><span class="c012"> <span class="c007">foo.ml</span>, <span class="c007">bar/foo.ml</span>, <span class="c007">bar/baz/foo.ml</span></span></td><td class="c028"><span class="c012"> <span class="c007">foo/bar</span>, <span class="c007">/bar</span></span></td><td class="c028"><span class="c012"> The empty string, or any string ending with a slash
(ε ∪ <span class="c013">P</span></span><sup><span class="c012">*</span></sup><span class="c012"><span class="c007">/</span>) </span></td></tr>
<tr><td class="c028"><span class="c012"><span class="c007">/**</span> <br>
The suffix inter-directory star</span></td><td class="c029"><span class="c012"> <span class="c007">foo/**</span></span></td><td class="c028"><span class="c012"> <span class="c007">foo</span>, <span class="c007">foo/bar</span></span></td><td class="c028"><span class="c012"> <span class="c007">bar/foo</span></span></td><td class="c028"><span class="c012"> Any string starting with a slash, or the empty string
(ε ∪ <span class="c007">/</span><span class="c013">P</span></span><sup><span class="c012">*</span></sup><span class="c012">) </span></td></tr>
<tr><td class="c028"><span class="c012"><span class="c007">/**/</span> <br>
The infix inter-directory star</span></td><td class="c029"><span class="c012"> <span class="c007">bar/**/foo.ml</span></span></td><td class="c028"><span class="c012"> <span class="c007">bar/foo.ml</span>, <span class="c007">bar/baz/foo.ml</span></span></td><td class="c028"><span class="c012"> <span class="c007">foo.ml</span></span></td><td class="c028"><span class="c012"> Any string starting and ending with a slash
(ε ∪ <span class="c007">/</span><span class="c013">P</span></span><sup><span class="c012">*</span></sup><span class="c012"><span class="c007">/</span>) </span></td></tr>
<tr><td class="c028"><span class="c012"><span class="c007">[</span> <span class="c013">r</span></span><sub><span class="c012">1</span></sub><span class="c016"> r</span><sub><span class="c012">2</span></sub><span class="c012"> ⋯ <span class="c013">r</span></span><sub><span class="c016">k</span></sub><span class="c012"> <span class="c007">]</span>
where <span class="c013">r</span></span><sub><span class="c016">i</span></sub><span class="c012"> is either <span class="c013">c</span> or <span class="c013">c</span></span><sub><span class="c012">1</span></sub><span class="c012">−<span class="c013">c</span></span><sub><span class="c012">2</span></sub><span class="c012"> (1 ≤ <span class="c013">i</span> ≤ <span class="c013">k</span>)
<br>
The positive character class</span></td><td class="c029"><span class="c012"> <span class="c007">[a-fA-F0-9_.]</span></span></td><td class="c028"><span class="c012"> <span class="c007">3</span>, <span class="c007">F</span>, <span class="c007">.</span></span></td><td class="c028"><span class="c012"> <span class="c007">z</span>, <span class="c007">bar</span></span></td><td class="c028"><span class="c012"> Any one-letter string made of characters from one of the ranges
<span class="c013">r</span></span><sub><span class="c016">i</span></sub><span class="c012"> (1 ≤ <span class="c013">i</span> ≤ <span class="c013">n</span>).
(<span class="c015">L</span>(<span class="c013">r</span></span><sub><span class="c012">1</span></sub><span class="c012">) ∪ ⋯ ∪ <span class="c015">L</span>(<span class="c013">r</span></span><sub><span class="c016">n</span></sub><span class="c012">)) </span></td></tr>
<tr><td class="c028"><span class="c012"><span class="c007">[^</span><span class="c013">r</span></span><sub><span class="c012">1</span></sub><span class="c016"> r</span><sub><span class="c012">2</span></sub><span class="c012"> ⋯ <span class="c013">r</span></span><sub><span class="c016">k</span></sub><span class="c012"> <span class="c007">]</span>
where <span class="c013">r</span></span><sub><span class="c016">i</span></sub><span class="c012"> is either <span class="c013">c</span> or <span class="c013">c</span></span><sub><span class="c012">1</span></sub><span class="c012">−<span class="c013">c</span></span><sub><span class="c012">2</span></sub><span class="c012"> (1 ≤ <span class="c013">i</span> ≤ <span class="c013">k</span>)
<br>
The negative character class</span></td><td class="c029"><span class="c012"> <span class="c007">[^a-fA-F0-9_.]</span></span></td><td class="c028"><span class="c012"> <span class="c007">z</span>, <span class="c007">bar</span></span></td><td class="c028"><span class="c012"> <span class="c007">3</span>, <span class="c007">F</span>, <span class="c007">.</span></span></td><td class="c028"><span class="c012"> Any one-letter string NOT made of characters from one of the ranges
<span class="c013">r</span></span><sub><span class="c016">i</span></sub><span class="c012"> (1 ≤ <span class="c013">i</span> ≤ <span class="c013">n</span>).
(Σ</span><sup><span class="c012">*</span></sup><span class="c012"> ∖ (<span class="c015">L</span>(<span class="c013">r</span></span><sub><span class="c012">1</span></sub><span class="c012">) ∪ ⋯ ∪ <span class="c015">L</span>(<span class="c013">r</span></span><sub><span class="c016">n</span></sub><span class="c012">))) </span></td></tr>
<tr><td class="c028"><span class="c016">p</span><sub><span class="c012">1</span></sub><span class="c016"> p</span><sub><span class="c012">2</span></sub><span class="c012"> <br>
A concatenation of patterns</span></td><td class="c029"><span class="c012"> <span class="c007">foo*</span></span></td><td class="c028"><span class="c012"> <span class="c007">foo</span>, <span class="c007">foob</span>, <span class="c007">foobar</span></span></td><td class="c028"><span class="c012"> <span class="c007">fo</span>, <span class="c007">bar</span></span></td><td class="c028"><span class="c012"> Any string with a prefix matching <span class="c013">p</span></span><sub><span class="c012">1</span></sub><span class="c012"> and the corresponding suffix
matching <span class="c013">p</span></span><sub><span class="c012">2</span></sub><span class="c012">,
({ <span class="c013">uv</span> ∣ <span class="c013">u</span> ∈ <span class="c015">L</span>(<span class="c013">p</span></span><sub><span class="c012">1</span></sub><span class="c012">), <span class="c013">v</span> ∈ <span class="c015">L</span>(<span class="c013">p</span></span><sub><span class="c012">2</span></sub><span class="c012">) }) </span></td></tr>
<tr><td class="c028"><span class="c012"><span class="c007">{</span> <span class="c013">p</span></span><sub><span class="c012">1</span></sub><span class="c012"> <span class="c007">,</span> <span class="c013">p</span></span><sub><span class="c012">2</span></sub><span class="c012"> <span class="c007">,</span> ⋯ <span class="c007">,</span> <span class="c013">p</span></span><sub><span class="c016">k</span></sub><span class="c012"> <span class="c007">}</span> <br>
A union of patterns</span></td><td class="c029"><span class="c012"> <span class="c007">toto.{ml,mli}</span></span></td><td class="c028"><span class="c012"> <span class="c007">toto.ml</span>, <span class="c007">toto.mli</span></span></td><td class="c028"><span class="c012"> <span class="c007">toto.</span></span></td><td class="c028"><span class="c012"> Any string matching one of the patterns <span class="c013">p</span></span><sub><span class="c016">i</span></sub><span class="c012"> for 1 ≤ <span class="c013">i</span> ≤ <span class="c013">k</span>.
(<span class="c015">L</span>(<span class="c013">p</span></span><sub><span class="c012">1</span></sub><span class="c012">) ∪ ⋯ ∪ <span class="c015">L</span>(<span class="c013">p</span></span><sub><span class="c016">k</span></sub><span class="c012">)) </span></td></tr>
</table><span class="c012">
</span></div>
<div class="caption"><table class="c002 cellpading0"><tr><td class="c027">Table 18.1:
Syntax and semantics of glob patterns.
</td></tr>
</table></div>
<div class="center"><hr class="c032"></div></blockquote><blockquote class="table"><div class="center"><hr class="c032"></div>
<div class="center">
<table class="c000 cellpadding1" border=1><tr><td class="c028"><span class="c012"><em> Formal syntax</em></span></td><td class="c029"><span class="c012"><em> Example</em></span></td><td class="c028"><span class="c012"><em> Meaning (formal meaning) </em></span></td></tr>
<tr><td class="c028"><span class="c012"> <span class="c007"><</span><span class="c013">p</span><span class="c007">></span></span></td><td class="c029"><span class="c012"> <span class="c007"><foo.ml></span></span></td><td class="c028"><span class="c012"> Pathnames matching the pattern <span class="c013">p</span> </span></td></tr>
<tr><td class="c028"><span class="c016"> e</span><sub><span class="c012">1</span></sub><span class="c012">   <span class="c009">or</span>   <span class="c013">e</span></span><sub><span class="c012">2</span></sub></td><td class="c029"><span class="c012"> <span class="c007"><*.ml> or <foo/bar.ml></span></span></td><td class="c028"><span class="c012"> Pathnames matching at least one of the expressions <span class="c013">e</span></span><sub><span class="c012">1</span></sub><span class="c012"> and <span class="c013">e</span></span><sub><span class="c012">2</span></sub><span class="c012"> </span></td></tr>
<tr><td class="c028"><span class="c016"> e</span><sub><span class="c012">1</span></sub><span class="c012">   <span class="c009">and</span>   <span class="c013">e</span></span><sub><span class="c012">2</span></sub></td><td class="c029"><span class="c012"> <span class="c007"><*.ml> and <foo_*></span></span></td><td class="c028"><span class="c012"> Pathnames matching both expressions <span class="c013">e</span></span><sub><span class="c012">1</span></sub><span class="c012"> and <span class="c013">e</span></span><sub><span class="c012">2</span></sub><span class="c012"> </span></td></tr>
<tr><td class="c028"><span class="c012"> <span class="c009">not</span>   <span class="c013">e</span></span></td><td class="c029"><span class="c012"> <span class="c007">not <*.mli></span></span></td><td class="c028"><span class="c012"> Pathnames not matching the expression <span class="c013">e</span> </span></td></tr>
<tr><td class="c028"><span class="c016"> <span class="c007">true</span></span></td><td class="c029"><span class="c012"> <span class="c007">true</span></span></td><td class="c028"><span class="c012"> All pathnames </span></td></tr>
<tr><td class="c028"><span class="c016"> <span class="c007">false</span></span></td><td class="c029"><span class="c012"> <span class="c007">false</span></span></td><td class="c028"><span class="c012"> No pathnames </span></td></tr>
</table><span class="c012">
</span></div>
<div class="caption"><table class="c002 cellpading0"><tr><td class="c027">Table 18.2:
Syntax and semantics of glob expressions.
</td></tr>
</table></div>
<div class="center"><hr class="c032"></div></blockquote>
<h3 class="subsection" id="sec388">18.3.14  Subdirectories</h3>
<p>
If the files of your project are held in one or more subdirectories,
<span class="c007">ocamlbuild</span> must be made aware of that fact using the <span class="c007">-I</span> or <span class="c007">-Is</span> options
or by adding an <span class="c007">include</span> tag. For instance, assume your project is made
of three subdirectories, <span class="c007">foo</span>, <span class="c007">bar</span> and <span class="c007">baz</span> containing
various <span class="c007">.ml</span> files, the main file being <span class="c007">foo/main.ml</span>. Then you can
either type:
</p><pre>% ocamlbuild -Is foo,bar,baz foo/main.native
</pre><p>or add the following line in the <span class="c007">_tags</span> file
</p><pre><foo> or <bar> or <baz>: include
</pre><p>and call
</p><pre>% ocamlbuild foo/main.native
</pre><p>
There are then two cases. If no other modules named <span class="c007">Bar</span> or
<span class="c007">Baz</span> exist elsewhere in the project, then you are done. Just use
<span class="c007">Foo</span>, <span class="c007">Foo.Bar</span> and <span class="c007">Foo.Baz</span> in your code.
Otherwise, you will need to use the plugin mechanism and define the mutual
visibility of the subdirectories using the <span class="c007">Pathname.define_context</span>
function.</p>
<h4 class="subsubsection" id="sec389">Note on subdirectory traversal</h4>
<p>
<span class="c007">ocamlbuild</span> used to traverse by default any subdirectory not explicitly excluded.
This is no longer the case. Note that you can still have a fine grained
control using your <span class="c007">_tags</span> file and the <span class="c007">traverse</span> tag.</p><p>There is no longer the <span class="c007">true: traverse</span> tag declaration by default. To
make <span class="c007">ocamlbuild</span> recursive use one of these:
</p><ol class="enumerate" type=1><li class="li-enumerate">
Give the <span class="c007">-r</span> flag to ocamlbuild.
</li><li class="li-enumerate">Have a <span class="c007">_tags</span> or myocamlbuild.ml file in your top directory.
</li></ol>
<h3 class="subsection" id="sec390">18.3.15  Grouping targets with <span class="c007">.itarget</span></h3>
<p>
You can create a file named <span class="c007">foo.itarget</span> containing
a list of targets, one per line, such as
</p><pre>main.native
main.byte
stuff.docdir/index.html
</pre><p>Requesting the target <span class="c007">foo.otarget</span> will then build every target
listed in the file <span class="c007">foo.itarget</span>. Blank lines and lines starting
with a sharp (<span class="c007">#</span>) are ignored.
</p>
<h3 class="subsection" id="sec391">18.3.16  Packing subdirectories into modules</h3>
<p>
OCaml’s <span class="c007">-pack</span> option allows you to structure the contents of a
module in a subdirectory. For instance, assume you have a directory
<span class="c007">foo</span> containing two modules <span class="c007">bar.ml</span> and <span class="c007">baz.ml</span>.
You want from these to build a module <span class="c007">Foo</span> containing <span class="c007">Bar</span>
and <span class="c007">Baz</span> as submodules. In the case where no modules named
<span class="c007">Bar</span> or <span class="c007">Baz</span> exist outside of <span class="c007">Foo</span>, to do this you
must write a file <span class="c007">foo.mlpack</span>, preferably sitting in the same
directory as the directory <span class="c007">Foo</span> and containing the list of modules
(one per line) it must contain:
</p><pre>Bar
Baz
</pre><p>Then when you will request for building <span class="c007">foo.cmo</span> the package will be
made from <span class="c007">bar.cmo</span> and <span class="c007">baz.cmo</span>.
</p>
<h3 class="subsection" id="sec392">18.3.17  Making an OCaml library</h3>
<p>
In a similar way than for packaged modules you can make a library by putting
it’s contents in a file (with the mllib extension). For instance, assume you
have a two modules <span class="c007">bar.ml</span> and <span class="c007">baz.ml</span>. You want from these to
build a library <span class="c007">foo.cmx?a</span> containing <span class="c007">Bar</span> and <span class="c007">Baz</span>
modules. To do this you must write a file <span class="c007">foo.mllib</span> containing the
list of modules (one per line) it must contain:
</p><pre>Bar
Baz
</pre><p>Then when you will request for building <span class="c007">foo.cma</span> the library will be
made from <span class="c007">bar.cmo</span> and <span class="c007">baz.cmo</span>.
</p>
<h3 class="subsection" id="sec393">18.3.18  Making an OCaml toplevel</h3>
<p>
Making a toplevel is almost the same thing than making a packaged module or a
library. Just write a file with the <span class="c007">mltop</span> extension (like
<span class="c007">foo.mltop</span>) and request for building the toplevel using the
<span class="c007">top</span> extension (<span class="c007">foo.top</span> in this example).
</p>
<h3 class="subsection" id="sec394">18.3.19  Preprocessor options and tags</h3>
<p>
You can specify preprocessor options with <span class="c007">-pp</span> followed by the
preprocessor string, for instance <span class="c007">ocamlbuild -pp camlp4o.opt -unsafe</span>
would run your sources through CamlP4 with the <span class="c007">-unsafe</span> option.
Another way is to use the tags file.
</p><div class="center">
<table class="c000 cellpadding1" border=1><tr><td class="c023"> <span class="c019">Tag</span></td><td class="c023"><span class="c019">Preprocessor command</span></td><td class="c023"><span class="c019">Remark</span> </td></tr>
<tr><td class="c023"> <span class="c007">pp(cmd...)</span></td><td class="c023"><span class="c007">cmd...</span></td><td class="c023">Arbitrary
preprocessor command<sup><a id="text3" href="#note3">1</a></sup> </td></tr>
<tr><td class="c023"> <span class="c007">camlp4o</span></td><td class="c023"><span class="c007">camlp4o</span></td><td class="c023">Original OCaml syntax </td></tr>
<tr><td class="c023"> <span class="c007">camlp4r</span></td><td class="c023"><span class="c007">camlp4r</span></td><td class="c023">Revised OCaml syntax </td></tr>
<tr><td class="c023"> <span class="c007">camlp4of</span></td><td class="c023"><span class="c007">camlp4of</span></td><td class="c023">Original OCaml syntax with extensions </td></tr>
<tr><td class="c023"> <span class="c007">camlp4rf</span></td><td class="c023"><span class="c007">camlp4rf</span></td><td class="c023">Revised OCaml syntax with extensions </td></tr>
</table>
</div>
<h3 class="subsection" id="sec395">18.3.20  Debugging byte code and profiling native code</h3>
<p>
The preferred way of compiling code suitable for debugging with <span class="c007">ocamldebug</span> or
profiling native code with <span class="c007">ocamlprof</span> is to use the appropriate target
extensions, <span class="c007">.d.byte</span> for debugging or <span class="c007">.p.native</span>.</p><p>Another way is to add use the <span class="c007">debug</span> or <span class="c007">profile</span> tags.
Note that these tags must be applied at the compilation and linking stages.
Hence you must either use <span class="c007">-tag debug</span> or <span class="c007">-tag profile</span>
on the command line, or add a
</p><pre>true: debug
</pre><p>line to your <span class="c007">_tags</span> file.
Please note that the byte-code profiler works in a wholly different way
and is not supported by <span class="c007">ocamlbuild</span>.
</p>
<h3 class="subsection" id="sec396">18.3.21  Generating documentation using <span class="c007">ocamldoc</span></h3>
<p>
Write the names of the modules whose interfaces will be documented in a file
whose extension is <span class="c007">.odocl</span>, for example <span class="c007">foo.odocl</span>, then invoke
<span class="c007">ocamlbuild</span> on the target <span class="c007">foo.docdir/index.html</span>. This will collect all the
documentation from the interfaces (which will be build, if necessary) using
<span class="c007">ocamldoc</span> and generate a set of HTML files under the directory
<span class="c007">foo.docdir/</span>, which is actually a link to <span class="c007">_build/foo.docdir/</span>.
As for packing subdirectories into modules, the module names must be written
one per line, without extensions and correctly capitalized. Note that
generating documentation in formats other than HTML or from implementations is
not supported.
</p>
<h3 class="subsection" id="sec397">18.3.22  The display line</h3>
<p>
Provided <span class="c007">ocamlbuild</span> runs in a terminal under a POSIX environment, it will
display a sophisticated progress-indicator line that graciously interacts
with the output of subcommands. This line looks like this:
</p><pre>00:00:02 210 (180 ) main.cmx ONbp--il /
</pre><p>Here, 00:00:02 is the elapsed time in hour:minute:second format since <span class="c007">ocamlbuild</span> has
been invoked; 210 is the number of external commands, typically calls to the
compiler or the like, that may or may not have been invoked; 180 is the number
of external commands that have not been invoked since their result is already
in the build directory; <span class="c007">main.cmx</span> is the name of the last target built;
<span class="c007">ONbp--il</span> is a short string that describes the tags that have been
encountered and the slash at the end is a frame from a rotating ticker. Hence,
the display line has the following structure:
</p><pre>HH:MM:SS JOBS (CACHED) PATHNAME TAGS TICKER
</pre><p>
The tag string is made of 8 indicators which each monitor a tag. These tags
are <span class="c007">ocaml</span>, <span class="c007">native</span>, <span class="c007">byte</span>, <span class="c007">program</span>,
<span class="c007">pp</span>, <span class="c007">debug</span>, <span class="c007">interf</span> and <span class="c007">link</span>. Initially,
each indicator displays a dash <span class="c007">-</span>. If the current target has the
monitored tag, then the indicator displays the corresponding character
(see table <a href="#tab%3Atag-chars">18.3</a>) in uppercase. Otherwise, it displays that
character in lowercase. This allows you to see the set of tags that have
been applied to files in your project during the current invocation of <span class="c007">ocamlbuild</span>.</p><p>Hence the tag string <span class="c007">ONbp--il</span> means that the current target
<span class="c007">main.cmx</span> has the tags <span class="c007">ocaml</span> and <span class="c007">native</span>, and that
the tags <span class="c007">ocaml</span>, <span class="c007">native</span>, <span class="c007">byte</span>, <span class="c007">program</span>,
<span class="c007">interf</span> and <span class="c007">link</span> have already been seen.</p><blockquote class="table"><div class="center"><hr class="c032"></div>
<div class="center">
<table class="c000 cellpadding1" border=1><tr><td class="c023"> <span class="c019">Tag</span></td><td class="c021"><span class="c019">Display character</span> </td></tr>
<tr><td class="c023"> ocaml</td><td class="c021">O </td></tr>
<tr><td class="c023"> native</td><td class="c021">N </td></tr>
<tr><td class="c023"> byte</td><td class="c021">B </td></tr>
<tr><td class="c023"> program</td><td class="c021">P </td></tr>
<tr><td class="c023"> pp</td><td class="c021">R </td></tr>
<tr><td class="c023"> debug</td><td class="c021">D </td></tr>
<tr><td class="c023"> interf</td><td class="c021">I </td></tr>
<tr><td class="c023"> link</td><td class="c021">L </td></tr>
</table>
</div>
<div class="caption"><table class="c002 cellpading0"><tr><td class="c027">Table 18.3: <a id="tab:tag-chars"></a> Relation between the characters displayed in
the tag string and the tags.</td></tr>
</table></div>
<div class="center"><hr class="c032"></div></blockquote>
<h3 class="subsection" id="sec398">18.3.23  <span class="c007">ocamllex</span>, <span class="c007">ocamlyacc</span> and <span class="c007">menhir</span></h3>
<p>
<span class="c007">ocamlbuild</span> knows how to run the standard lexer and parser generator tools
<span class="c007">ocamllex</span> and <span class="c007">ocamlyacc</span> when your files have the
standard <span class="c007">.mll</span> and <span class="c007">.mly</span> extensions. If you want to
use <span class="c007">menhir</span> instead of <span class="c007">ocamlyacc</span>, you can either
launch <span class="c007">ocamlbuild</span> with the <span class="c007">-use-menhir</span> option or add a
</p><pre>true: use_menhir
</pre><p>line to your <span class="c007">_tags</span> file. Note that there is currently no way
of using <span class="c007">menhir</span> and <span class="c007">ocamlyacc</span> in the same execution
of <span class="c007">ocamlbuild</span>.
</p>
<h3 class="subsection" id="sec399">18.3.24  Changing the compilers or tools</h3>
<p>
As <span class="c007">ocamlbuild</span> is part of your OCaml distribution, it knows if it can call the
native compilers and tools (<span class="c007">ocamlc.opt</span>, <span class="c007">ocamlopt.opt</span>...)
or not. However you may want <span class="c007">ocamlbuild</span> to use another <span class="c007">ocaml</span> compiler
for different reasons (such as cross-compiling or using a wrapper such as
<span class="c007">ocamlfind</span>). Here is the list of relevant options:
</p><ul class="itemize"><li class="li-itemize">
<span class="c007">-ocamlc <command></span>
</li><li class="li-itemize"><span class="c007">-ocamlopt <command></span>
</li><li class="li-itemize"><span class="c007">-ocamldep <command></span>
</li><li class="li-itemize"><span class="c007">-ocamlyacc <command></span>
</li><li class="li-itemize"><span class="c007">-menhir <command></span>
</li><li class="li-itemize"><span class="c007">-ocamllex <command></span>
</li><li class="li-itemize"><span class="c007">-ocamlmktop <command></span>
</li><li class="li-itemize"><span class="c007">-ocamlrun <command></span>
</li></ul>
<h3 class="subsection" id="sec400">18.3.25  Interaction with version control systems</h3>
<p>
Here are tips for configuring your version control system to ignore the files
and directories generated by <span class="c007">ocamlbuild</span>.</p><p>The directory <span class="c007">_build</span> and any symbolic links
pointing into <span class="c007">_build</span> should be ignored.
To do this, you must add the following ignore patterns to your version
control system’s ignore set:
</p><pre>_build
*.native
*.byte
*.d.native
*.p.byte
</pre><p>
For CVS, add the above lines to the <span class="c007">.cvsignore</span> file.
For Subversion (SVN), type <span class="c007">svn propedit svn:ignore .</span> and add the
above lines.
</p>
<h3 class="subsection" id="sec401">18.3.26  A shell script for driving it all?</h3>
<p>
<em>To shell or to make ?</em>
Traditionally, makefiles have two major functions. The first one
is the dependency-ordering, rule-matching logic used for compiling.
The second one is as a dispatcher for various actions defined using
phony targets with shell script actions. These actions include cleaning,
cleaning really well, archiving, uploading and so on. Their characteristic
is that they rely little or not on the building process – they either need
the building to have been completed, or they don’t need anything.
As <span class="c007">/bin/sh</span> scripts have been here for three to four decades and are
not going anywhere, why not replace that functionality of makefiles with a
shell script ? We have thought of three bad reasons:
</p><ul class="itemize"><li class="li-itemize">
Typing <span class="c007">make</span> to compile is now an automatism,
</li><li class="li-itemize">We need to share variable definitions between rules and actions,
</li><li class="li-itemize">Escaping already way too special-character-sensitive shell code with
invisible tabs and backslashes is a dangerously fun game.
</li></ul><p>
We also have bad reasons for not using an OCaml script to drive everything:
</p><ul class="itemize"><li class="li-itemize">
<span class="c007">Sys.command</span> calls the <span class="c007">/bin/sh</span> anyway,
</li><li class="li-itemize">Shell scripts can execute partial commands or commands with badly formed arguments.
</li><li class="li-itemize">Shell scripts are more concise for expressing... shell scripts.
</li></ul><p>
Anyway you are of course free to use a makefile or an OCaml script to call ocamlbuild.
Here is an example shell driver script:
</p><pre>#!/bin/sh
set -e
TARGET=epoch
FLAGS="-libs unix,nums"
OCAMLBUILD=ocamlbuild
ocb()
{
$OCAMLBUILD $FLAGS $*
}
rule() {
case $1 in
clean) ocb -clean;;
native) ocb $TARGET.native;;
byte) ocb $TARGET.byte;;
all) ocb $TARGET.native $TARGET.byte;;
depend) echo "Not needed.";;
*) echo "Unknown action $1";;
esac;
}
if [ $# -eq 0 ]; then
rule all
else
while [ $# -gt 0 ]; do
rule $1;
shift
done
fi
</pre>
<h2 class="section" id="sec402">18.4  Appendix: Motivations</h2>
<p>
<em>This inflammatory appendix describes the frustration that led us to write <span class="c007">ocamlbuild</span>.</em></p><p>Many people have painfully found that the utilities of the <span class="c007">make</span>
family, namely GNU Make, BSD Make, and their derivatives, fail to scale to
large projects, especially when using multi-stage compilation rules, such as
custom pre-processors, unless dependencies are hand-defined. But as your
project gets larger, more modular, and uses more diverse pre-processing tools,
it becomes increasingly difficult to correctly define dependencies by hand.
Hence people tend to use language-specific tools that attempt to extract
dependencies. However another problem then appears: <span class="c007">make</span> was designed
with the idea of a static dependency graph. Dependency extracting tools,
however, are typically run by a rule in <span class="c007">make</span> itself; this means that
make has to reload the dependency information. This is the origin of the
<span class="c007">make clean; make depend; make</span> mantra. This approach tends to work
quite well as long as all the files sit in a single directory and there is only
one stage of pre-processing. If there are two or more stages, then dependency
extracting tools must be run two or more times - and this means multiple
invocations of <span class="c007">make</span>. Also, if one distributes the modules of a large
project into multiple subdirectories, it becomes difficult to distribute the
makefiles themselves, because the language of <span class="c007">make</span> was not conceived
to be modular; the only two mechanisms permitted, inclusion of makefile
fragments, and invocation of other make instances, must be skillfully
coordinated with phony target names (<span class="c007">depend1, depend2...</span>) to insure
inclusion of generated dependencies with multi-stage programming; changes in
the structure of the project must be reflected by hand and the order of
variable definitions must be well-thought ahead to avoid long afternoons spent
combinatorially fiddling makefiles until it works but no one understands why.</p><p>These problems become especially apparent with OCaml: to ensure type safety and
to allow a small amount of cross-unit optimization when compiling native code,
interface and object files include cryptographical digests of interfaces they
are to be linked with. This means that linking is safer, but that makefile sloppiness
leads to messages such as:
</p><pre>Files foo.cmo and bar.cmo
make inconsistent assumptions over interface Bar
</pre><p>
The typical reaction is then to issue the mantra <span class="c007">make clean; make
depend; make</span> and everything compiles just fine... from the beginning. Hence
on medium projects, the programmer often has to wait for minutes instead of the
few seconds that would be taken if <span class="c007">make</span> could correctly guess the
small number of files that really had to be recompiled.</p><p>It is not surprising that hacking a build tool such as <span class="c007">make</span> to include
a programming language while retaining the original syntax and semantics gives
an improvised and cumbersome macro language of dubious expressive power. For
example, using GNU make, suppose you have a list of <span class="c007">.ml</span>s that you want
to convert into a list including both <span class="c007">.cmo</span>s and <span class="c007">.cmi</span>s, that
is you want to transform <span class="c007">a.ml b.ml c.ml</span> into <span class="c007">a.cmi a.cmo b.cmi
b.cmo c.cmi c.cmo</span> while preserving the dependency order which must be hand
specified for linking <sup><a id="text4" href="#note4">2</a></sup>.
Unfortunately <span class="c007">$patsubst %.ml, %.cmi %.cmo, a.ml b.ml c.ml</span> won’t
work since the %-sign in the right-hand of a <span class="c007">patsubst</span> gets
substituted only once. You then have to delve into something that is hardly
lambda calculus: an intricate network of <span class="c007">foreach</span>, <span class="c007">eval</span>,
<span class="c007">call</span> and <span class="c007">define</span>s may get you the job done, unless you chicken
out and opt for an external <span class="c007">awk</span>, <span class="c007">sed</span> or <span class="c007">perl</span> call.
People who at this point have not lost their temper or sanity usually resort to
metaprogramming by writing Makefile generators using a mixture of shell and m4.
One such an attempt gave something that is the nightmare of wannabe package
maintainers: it’s called <span class="c007">autotools</span>.</p><p>Note that it is also difficult to write <span class="c007">Makefiles</span> to build object
files in a separate directory. It is not impossible since the language of
<span class="c007">make</span> is Turing-complete, a proof of which is left as an exercise.
Note that building things in a separate directory is not necessarily a young
enthusiast’s way of giving a different look and feel to his projects – it may
be a good way of telling the computer that <span class="c007">foo.mli</span> is generated by
<span class="c007">ocamlyacc</span> using <span class="c007">foo.mly</span> and can thus be removed.
</p>
<h2 class="section" id="sec403">18.5  Appendix: Summary of default rules</h2>
<p>
The contents of this table give a summary of the most important default rules.
To get the most accurate and up-to-date information, launch <span class="c007">ocamlbuild</span> with the
<span class="c007">-documentation</span> option.
</p><div class="center">
<table class="c000 cellpadding1" border=1><tr><td class="c029"><span class="c020"> Tags</span></td><td class="c029"><span class="c020">Dependencies</span></td><td class="c028"><span class="c020">Targets </span></td></tr>
<tr><td class="c029"><span class="c012"> </span></td><td class="c029"><span class="c012">%.itarget</span></td><td class="c028"><span class="c012">%.otarget </span></td></tr>
<tr><td class="c029"><span class="c012"> ocaml</span></td><td class="c029"><span class="c012">%.mli %.mli.depends</span></td><td class="c028"><span class="c012">%.cmi </span></td></tr>
<tr><td class="c029"><span class="c012"> byte, debug, ocaml</span></td><td class="c029"><span class="c012">%.mlpack %.cmi</span></td><td class="c028"><span class="c012">%.d.cmo </span></td></tr>
<tr><td class="c029"><span class="c012"> byte, ocaml</span></td><td class="c029"><span class="c012">%.mlpack</span></td><td class="c028"><span class="c012">%.cmo %.cmi </span></td></tr>
<tr><td class="c029"><span class="c012"> byte, ocaml</span></td><td class="c029"><span class="c012">%.mli %.ml %.ml.depends %.cmi</span></td><td class="c028"><span class="c012">%.d.cmo </span></td></tr>
<tr><td class="c029"><span class="c012"> byte, ocaml</span></td><td class="c029"><span class="c012">%.mli %.ml %.ml.depends %.cmi</span></td><td class="c028"><span class="c012">%.cmo </span></td></tr>
<tr><td class="c029"><span class="c012"> native, ocaml, profile</span></td><td class="c029"><span class="c012">%.mlpack %.cmi</span></td><td class="c028"><span class="c012">%.p.cmx %.p.o </span></td></tr>
<tr><td class="c029"><span class="c012"> native, ocaml</span></td><td class="c029"><span class="c012">%.mlpack %.cmi</span></td><td class="c028"><span class="c012">%.cmx %.o </span></td></tr>
<tr><td class="c029"><span class="c012"> native, ocaml, profile</span></td><td class="c029"><span class="c012">%.ml %.ml.depends %.cmi</span></td><td class="c028"><span class="c012">%.p.cmx %.p.o </span></td></tr>
<tr><td class="c029"><span class="c012"> native, ocaml</span></td><td class="c029"><span class="c012">%.ml %.ml.depends %.cmi</span></td><td class="c028"><span class="c012">%.cmx %.o </span></td></tr>
<tr><td class="c029"><span class="c012"> debug, ocaml</span></td><td class="c029"><span class="c012">%.ml %.ml.depends %.cmi</span></td><td class="c028"><span class="c012">%.d.cmo </span></td></tr>
<tr><td class="c029"><span class="c012"> ocaml</span></td><td class="c029"><span class="c012">%.ml %.ml.depends</span></td><td class="c028"><span class="c012">%.cmo %.cmi </span></td></tr>
<tr><td class="c029"><span class="c012"> byte, debug, ocaml, program</span></td><td class="c029"><span class="c012">%.d.cmo</span></td><td class="c028"><span class="c012">%.d.byte </span></td></tr>
<tr><td class="c029"><span class="c012"> byte, ocaml, program</span></td><td class="c029"><span class="c012">%.cmo</span></td><td class="c028"><span class="c012">%.byte </span></td></tr>
<tr><td class="c029"><span class="c012"> native, ocaml, profile, program</span></td><td class="c029"><span class="c012">%.p.cmx %.p.o</span></td><td class="c028"><span class="c012">%.p.native </span></td></tr>
<tr><td class="c029"><span class="c012"> native, ocaml, program</span></td><td class="c029"><span class="c012">%.cmx %.o</span></td><td class="c028"><span class="c012">%.native </span></td></tr>
<tr><td class="c029"><span class="c012"> byte, debug, library, ocaml</span></td><td class="c029"><span class="c012">%.mllib</span></td><td class="c028"><span class="c012">%.d.cma </span></td></tr>
<tr><td class="c029"><span class="c012"> byte, library, ocaml</span></td><td class="c029"><span class="c012">%.mllib</span></td><td class="c028"><span class="c012">%.cma </span></td></tr>
<tr><td class="c029"><span class="c012"> byte, debug, library, ocaml</span></td><td class="c029"><span class="c012">%.d.cmo</span></td><td class="c028"><span class="c012">%.d.cma </span></td></tr>
<tr><td class="c029"><span class="c012"> byte, library, ocaml</span></td><td class="c029"><span class="c012">%.cmo</span></td><td class="c028"><span class="c012">%.cma </span></td></tr>
<tr><td class="c029"><span class="c012"> </span></td><td class="c029"><span class="c012">lib%(libname).clib</span></td><td class="c028"><span class="c012">lib%(libname).a dll%(libname).so </span></td></tr>
<tr><td class="c029"><span class="c012"> </span></td><td class="c029"><span class="c012">%(path)/lib%(libname).clib</span></td><td class="c028"><span class="c012">%(path)/lib%(libname).a %(path)/dll%(libname).so </span></td></tr>
<tr><td class="c029"><span class="c012"> library, native, ocaml, profile</span></td><td class="c029"><span class="c012">%.mllib</span></td><td class="c028"><span class="c012">%.p.cmxa %.p.a </span></td></tr>
<tr><td class="c029"><span class="c012"> library, native, ocaml</span></td><td class="c029"><span class="c012">%.mllib</span></td><td class="c028"><span class="c012">%.cmxa %.a </span></td></tr>
<tr><td class="c029"><span class="c012"> library, native, ocaml, profile</span></td><td class="c029"><span class="c012">%.p.cmx %.p.o</span></td><td class="c028"><span class="c012">%.p.cmxa %.p.a </span></td></tr>
<tr><td class="c029"><span class="c012"> library, native, ocaml</span></td><td class="c029"><span class="c012">%.cmx %.o</span></td><td class="c028"><span class="c012">%.cmxa %.a </span></td></tr>
<tr><td class="c029"><span class="c012"> </span></td><td class="c029"><span class="c012">%.ml</span></td><td class="c028"><span class="c012">%.ml.depends </span></td></tr>
<tr><td class="c029"><span class="c012"> </span></td><td class="c029"><span class="c012">%.mli</span></td><td class="c028"><span class="c012">%.mli.depends </span></td></tr>
<tr><td class="c029"><span class="c012"> ocaml</span></td><td class="c029"><span class="c012">%.mll</span></td><td class="c028"><span class="c012">%.ml </span></td></tr>
<tr><td class="c029"><span class="c012"> doc, ocaml</span></td><td class="c029"><span class="c012">%.mli %.mli.depends</span></td><td class="c028"><span class="c012">%.odoc </span></td></tr>
<tr><td class="c029"><span class="c012"> </span></td><td class="c029"><span class="c012">%.odocl</span></td><td class="c028"><span class="c012">%.docdir/index.html </span></td></tr>
<tr><td class="c029"><span class="c012"> ocaml</span></td><td class="c029"><span class="c012">%.mly</span></td><td class="c028"><span class="c012">%.ml %.mli </span></td></tr>
<tr><td class="c029"><span class="c012"> </span></td><td class="c029"><span class="c012">%.c</span></td><td class="c028"><span class="c012">%.o </span></td></tr>
<tr><td class="c029"><span class="c012"> </span></td><td class="c029"><span class="c012">%.ml %.ml.depends</span></td><td class="c028"><span class="c012">%.inferred.mli </span></td></tr>
</table><span class="c012">
</span></div>
<hr class="ffootnoterule"><dl class="thefootnotes"><dt class="dt-thefootnotes">
<a id="note3" href="#text3">1</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">The command must not contain newlines or parentheses.</div>
</dd><dt class="dt-thefootnotes"><a id="note4" href="#text4">2</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">By the way, what’s the point of having a
declarative language if <span class="c007">make</span> can’t sort the dependencies in
topological order for giving them to <span class="c007">gcc</span> or whatever ?</div>
</dd></dl>
<hr>
<a href="profil.html"><img src="previous_motif.gif" alt="Previous"></a>
<a href="index.html"><img src="contents_motif.gif" alt="Up"></a>
<a href="intfc.html"><img src="next_motif.gif" alt="Next"></a>
</body>
</html>
