# Chapter 18 The ocamlbuild compilation manager

- Features of `ocamlbuild`
- Limitations
- Using `ocamlbuild`
- Appendix: Motivations
- Appendix: Summary of default rules

(Chapter written by Berke Durak and Nicolas Pouillard)

`ocamlbuild` 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.

## 18.1 Features of `ocamlbuild`

This section is intended to read like a sales brochure or a datasheet.

- Built-in compilation rules for OCaml projects handle all the nasty cases: native and byte-code, missing `.mli` files, preprocessor rules, libraries, package (-pack) debugging and profiling flags, C stubs.
- Plugin mechanism for writing compilation rules and actions in a real programming language, OCaml itself.
- Automatic inference of dependencies.
- Correct handling of dynamically discovered dependencies.
- Object files and other temporary files are created in a specific directory, leaving your main directory uncluttered.
- Sanity checks ensure that object files are where they are supposed to be: in the build directory.
- Regular projects are built using a single command with no extra files.
- Parallel compilation to speed up things on multi-core systems.
- 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.
- Tags and flags provide a concise and convenient mechanism for automatic selection of compilation, preprocessing and other options.
- 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.
- Mechanisms for defining the mutual visibility of subdirectories.
- Cache mechanism avoiding unnecessary compilations where reasonably computable.

## 18.2 Limitations

Not perfect nor complete yet, but already pretty damn useful.

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 `ocamlbuild`, and we hope that the OCaml community will find our first try at `ocamlbuild` useful and hopefully help it grow into a tool that satisfies most needs of most users by providing feedback, bug reports and patches.

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 `Ocamlbuild_plugin` 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 `ocamlbuild` 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 `ocamlbuild` library from the rest of your plugin to be able to keep the later when incompatible changes arise.

The way that `ocamlbuild` handles the command-line options, the `_tags` 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.

## 18.3 Using `ocamlbuild`

Learn how to use `ocamlbuild` with short, specific, straight-to-the-point examples.

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.

`ocamlbuild` is intended to be very easy to use for projects, large or small, with a simple compilation process: typing `ocamlbuild foo.native` should be enough to compile the native version of a program whose top module is `foo.ml` 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.

### 18.3.1 Hygiene & where is my code ?

Your code is in the `_build` directory, but `ocamlbuild` automatically creates a symbolic link to the executables it produces in the current directory. `ocamlbuild` copies the source files and compiles them in a separate directory which is `_build` by default.

For `ocamlbuild`, 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. `ocamlbuild` has so-called “hygiene” rules that state that object files (`.cmo`, `.cmi`, or `.o` files, for instance) must not appear outside of the build directory. These rules are enforced at startup; any violations will be reported and `ocamlbuild` will exit. You must then remove these files by hand or run, with caution, the script `sanitize.sh`, which is generated in your source directory. This script will contain commands to remove them for you.

To disable these checks, you can use the `-no-hygiene` flag. If you have files that must elude the hygiene squad, just tag them with `precious` or `not_hygienic`.

### 18.3.2 Hello, world !

Assuming we are in a directory named `example1` containing one file `hello.ml` whose contents are

    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)
    ;;

we can compile and link it into a native executable by invoking `ocamlbuild hello.native`. Here, `hello` is the basename of the top-level module and `native` is an extension used by `ocamlbuild` to denote native code executables.

    % 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*

What’s this funny `_build` directory ? Well that’s where `ocamlbuild` does its dirty work of compiling. You usually won’t have to look very often into this directory. Source files are copied into `_build` and this is where the compilers will be run. Various cache files are also stored there. Its contents may look like this:

    % 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

### 18.3.3 Executing my code

You can execute your code the old-fashioned way (`./hello.native`). You may also type

    ocamlbuild hello.native – Caesar

and it will compile and then run `hello.native` with the arguments following `--`, which should display:

    % ocamlbuild hello.native – Caesar
    Finished, 4 targets (0 cached) in 00:00:00.
    Hello, Caesar ! My name is _build/hello.native

### 18.3.4 The log file, verbosity and debugging

By default, if you run `ocamlbuild` on a terminal, it will use some ANSI escape sequences to display a nice, one-line progress indicator. To see what commands `ocamlbuild` has actually run, you can check the contents of the `_build/_log` file. To change the name of the log file or to disable logging, use the `-log <file>` or `-no-log` options. Note that the log file is truncated at each execution of `ocamlbuild`.

The log file contains all the external commands that `ocamlbuild` ran or intended to run along with the target name and the computed tags. With the `-verbose <level>` option, `ocamlbuild` will also write more or less useful debugging information; a verbosity level of 1 (which can also be specified using the `-verbose` switch) prints generally useful information; higher levels produce much more output.

### 18.3.5 Cleaning

`ocamlbuild` may leave a `_build` 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 `ocamlbuild` with the `-clean` flag.

### 18.3.6 Where and how to run `ocamlbuild`?

An important point is that `ocamlbuild` must be invoked from the root of the project, even if this project has multiple, nested subdirectories. This is because `ocamlbuild` likes to store the object files in a single `_build` directory. You can change the name of that directory with the `-build-dir` option.

`ocamlbuild` can be either invoked manually from the UNIX or Windows shell, or automatically from a build script or a Makefile. Unless run with the `-no-hygiene` option, there is the possibility that `ocamlbuild` will prompt the user for a response. By default, on UNIX systems, if `ocamlbuild` 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 `-classic-display` option.

### 18.3.7 Dependencies

Dependencies are automatically discovered.

Most of the value of `ocamlbuild` lies in the fact that it often needs no extra information to compile a project besides the name of the top-level module. `ocamlbuild` calls `ocamldep` to automatically find the dependencies of any modules it wants to compile. These dependencies are dynamically incorporated in the dependency graph, something `make` cannot do. For instance, let’s add a module `Greet` that implements various ways of greeting people.

    % 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)
    ;;

Then the module `Hello` depends on the module `Greet` and `ocamlbuild` can figure this out for himself – we still only have to invoke `ocamlbuild hello.native`. Needless to say, this works for any number of modules.

### 18.3.8 Native and byte-code

If we want to compile byte-code instead of native, we just a target name of `hello.byte` instead of `hello.native`, i.e., we type `ocamlbuild hello.byte`.

### 18.3.9 Compile flags

To pass a flag to the compiler, such as the `-rectypes` option, use the `-cflag` option as in:

    ocamlbuild -cflag -rectypes hello.native

You can put multiple `-cflag` options, they will be passed to the compiler in the same order. You can also give them in a comma-separated list with the `-cflags` option (notice the plural):

    ocamlbuild -cflags -I,+lablgtk,-rectypes hello.native

These flags apply when compiling, that is, when producing `.cmi`, `.cmo`,`.cmx` and `.o` files from `.ml` or `.mli` files.

### 18.3.10 Link flags

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 `-lflag` and `-lflags` options, which work in the same way as the `-cflag` and `-cflags` options.

### 18.3.11 Linking with external libraries

In our third example, we use one Unix system call and functions from the `num` library:

    % 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)
    ;;

This requires linking with the `unix` and `num` modules, which is accomplished by using the `-lib unix` and `-lib num` flags, or, alternatively, `-libs unix,num`:

    % ocamlbuild -libs nums,unix epoch.native –
    Finished, 4 targets (4 cached) in 00:00:00.
    1169051647000000000000 picoseconds have passed since January 1st, 1970.

You may need to add options such as `-cflags -I,/usr/local/lib/ocaml/` and `-lflags -I,/usr/local/lib/ocaml/` if the libraries you wish to link with are not in OCaml’s default search path.

### 18.3.12 The `_tags` files

Finer control over the compiler flags applied to each source file, such as preprocessing, debugging, profiling and linking options, can be gained using `ocamlbuild`’s tagging mechanism.

Every source file has a set of tags which tells `ocamlbuild` what kind of file it is and what to do with it. A tag is simply a string, usually lowercase, for example `ocaml` or `native`. The set of tags attached to a file is computed by applying the tagging rules to the filename. Tagging rules are defined in `_tags` files in any parent directory of a file, up to the main project directory.

Each line in the `_tags` file is made of a glob pattern (see subsection 18.3.13) 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.

#### Example: the built-in `_tags` file

         <**/*.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

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 `foo/bar.ml` those tags will be `file:foo/bar.ml`, and `extension:ml`.

If you do not have subdirectories, you can put `*.ml` instead of `**/*.ml`.

### 18.3.13 Glob patterns and expressions

Glob patterns have a syntax similar to those used by UNIX shells to select path names (like `foo_*.ba?`). They are used in `ocamlbuild` to define the files and directories to which tags apply. Glob expressions are glob patterns enclosed in brackets `<` and `>` combined using the standard boolean operators `and`, `or`, `not`. This allows one to describe sets of path names in more concise and more readable ways.

Please note that file and directory names are supposed to be made of the following characters: `a`, …, `z`, `A`, …, `Z`, `0`, …, `9`, `_`, `-` and `.`. This is called the pathname alphabet P.

> Formal syntax | Example | Matches | Does not match | Meaning (formal meaning)
> u A string of pathname characters | `foo.ml` | `foo.ml` | `fo.ml`, `bar/foo.ml` | The exact string u ({ u }, where u ∈ P*)
> `*` The wild-card star | `*` | ε, `foo`, `bar` | `foo/bar`, `/bar` | Any string not containing a slash (P*)
> `?` The joker | `?` | `a`, `b`, `z` | `/`, `bar` | Any one-letter string, excluding the slash
> `**/` The prefix inter-directory star | `**/foo.ml` | `foo.ml`, `bar/foo.ml`, `bar/baz/foo.ml` | `foo/bar`, `/bar` | The empty string, or any string ending with a slash (ε ∪ P*`/`)
> `/**` The suffix inter-directory star | `foo/**` | `foo`, `foo/bar` | `bar/foo` | Any string starting with a slash, or the empty string (ε ∪ `/`P*)
> `/**/` The infix inter-directory star | `bar/**/foo.ml` | `bar/foo.ml`, `bar/baz/foo.ml` | `foo.ml` | Any string starting and ending with a slash (ε ∪ `/`P*`/`)
> `[` r1 r2 ⋯ rk `]` where ri is either c or c1−c2 (1 ≤ i ≤ k) The positive character class | `[a-fA-F0-9_.]` | `3`, `F`, `.` | `z`, `bar` | Any one-letter string made of characters from one of the ranges ri (1 ≤ i ≤ n). (L(r1) ∪ ⋯ ∪ L(rn))
> `[^`r1 r2 ⋯ rk `]` where ri is either c or c1−c2 (1 ≤ i ≤ k) The negative character class | `[^a-fA-F0-9_.]` | `z`, `bar` | `3`, `F`, `.` | Any one-letter string NOT made of characters from one of the ranges ri (1 ≤ i ≤ n). (Σ* ∖ (L(r1) ∪ ⋯ ∪ L(rn)))
> p1 p2 A concatenation of patterns | `foo*` | `foo`, `foob`, `foobar` | `fo`, `bar` | Any string with a prefix matching p1 and the corresponding suffix matching p2, ({ uv ∣ u ∈ L(p1), v ∈ L(p2) })
> `{` p1 `,` p2 `,` ⋯ `,` pk `}` A union of patterns | `toto.{ml,mli}` | `toto.ml`, `toto.mli` | `toto.` | Any string matching one of the patterns pi for 1 ≤ i ≤ k. (L(p1) ∪ ⋯ ∪ L(pk))

> Table 18.1: Syntax and semantics of glob patterns.

> Formal syntax | Example | Meaning (formal meaning)
> `<`p`>` | `<foo.ml>` | Pathnames matching the pattern p
> e1 `or` e2 | `<*.ml> or <foo/bar.ml>` | Pathnames matching at least one of the expressions e1 and e2
> e1 `and` e2 | `<*.ml> and <foo_*>` | Pathnames matching both expressions e1 and e2
> `not` e | `not <*.mli>` | Pathnames not matching the expression e
> `true` | `true` | All pathnames
> `false` | `false` | No pathnames

> Table 18.2: Syntax and semantics of glob expressions.

### 18.3.14 Subdirectories

If the files of your project are held in one or more subdirectories, `ocamlbuild` must be made aware of that fact using the `-I` or `-Is` options or by adding an `include` tag. For instance, assume your project is made of three subdirectories, `foo`, `bar` and `baz` containing various `.ml` files, the main file being `foo/main.ml`. Then you can either type:

    % ocamlbuild -Is foo,bar,baz foo/main.native

or add the following line in the `_tags` file

    <foo> or <bar> or <baz>: include

and call

    % ocamlbuild foo/main.native

There are then two cases. If no other modules named `Bar` or `Baz` exist elsewhere in the project, then you are done. Just use `Foo`, `Foo.Bar` and `Foo.Baz` in your code. Otherwise, you will need to use the plugin mechanism and define the mutual visibility of the subdirectories using the `Pathname.define_context` function.

#### Note on subdirectory traversal

`ocamlbuild` 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 `_tags` file and the `traverse` tag.

There is no longer the `true: traverse` tag declaration by default. To make `ocamlbuild` recursive use one of these:

1. Give the `-r` flag to ocamlbuild.
2. Have a `_tags` or myocamlbuild.ml file in your top directory.

### 18.3.15 Grouping targets with `.itarget`

You can create a file named `foo.itarget` containing a list of targets, one per line, such as

    main.native
    main.byte
    stuff.docdir/index.html

Requesting the target `foo.otarget` will then build every target listed in the file `foo.itarget`. Blank lines and lines starting with a sharp (`#`) are ignored.

### 18.3.16 Packing subdirectories into modules

OCaml’s `-pack` option allows you to structure the contents of a module in a subdirectory. For instance, assume you have a directory `foo` containing two modules `bar.ml` and `baz.ml`. You want from these to build a module `Foo` containing `Bar` and `Baz` as submodules. In the case where no modules named `Bar` or `Baz` exist outside of `Foo`, to do this you must write a file `foo.mlpack`, preferably sitting in the same directory as the directory `Foo` and containing the list of modules (one per line) it must contain:

    Bar
    Baz

Then when you will request for building `foo.cmo` the package will be made from `bar.cmo` and `baz.cmo`.

### 18.3.17 Making an OCaml library

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 `bar.ml` and `baz.ml`. You want from these to build a library `foo.cmx?a` containing `Bar` and `Baz` modules. To do this you must write a file `foo.mllib` containing the list of modules (one per line) it must contain:

    Bar
    Baz

Then when you will request for building `foo.cma` the library will be made from `bar.cmo` and `baz.cmo`.

### 18.3.18 Making an OCaml toplevel

Making a toplevel is almost the same thing than making a packaged module or a library. Just write a file with the `mltop` extension (like `foo.mltop`) and request for building the toplevel using the `top` extension (`foo.top` in this example).

### 18.3.19 Preprocessor options and tags

You can specify preprocessor options with `-pp` followed by the preprocessor string, for instance `ocamlbuild -pp camlp4o.opt -unsafe` would run your sources through CamlP4 with the `-unsafe` option. Another way is to use the tags file.

Tag | Preprocessor command | Remark
`pp(cmd...)` | `cmd...` | Arbitrary preprocessor command1
`camlp4o` | `camlp4o` | Original OCaml syntax
`camlp4r` | `camlp4r` | Revised OCaml syntax
`camlp4of` | `camlp4of` | Original OCaml syntax with extensions
`camlp4rf` | `camlp4rf` | Revised OCaml syntax with extensions

### 18.3.20 Debugging byte code and profiling native code

The preferred way of compiling code suitable for debugging with `ocamldebug` or profiling native code with `ocamlprof` is to use the appropriate target extensions, `.d.byte` for debugging or `.p.native`.

Another way is to add use the `debug` or `profile` tags. Note that these tags must be applied at the compilation and linking stages. Hence you must either use `-tag debug` or `-tag profile` on the command line, or add a

    true: debug

line to your `_tags` file. Please note that the byte-code profiler works in a wholly different way and is not supported by `ocamlbuild`.

### 18.3.21 Generating documentation using `ocamldoc`

Write the names of the modules whose interfaces will be documented in a file whose extension is `.odocl`, for example `foo.odocl`, then invoke `ocamlbuild` on the target `foo.docdir/index.html`. This will collect all the documentation from the interfaces (which will be build, if necessary) using `ocamldoc` and generate a set of HTML files under the directory `foo.docdir/`, which is actually a link to `_build/foo.docdir/`. 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.

### 18.3.22 The display line

Provided `ocamlbuild` 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:

    00:00:02 210  (180 ) main.cmx                             ONbp–il /

Here, 00:00:02 is the elapsed time in hour:minute:second format since `ocamlbuild` 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; `main.cmx` is the name of the last target built; `ONbp--il` 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:

    HH:MM:SS JOBS (CACHED) PATHNAME                           TAGS TICKER

The tag string is made of 8 indicators which each monitor a tag. These tags are `ocaml`, `native`, `byte`, `program`, `pp`, `debug`, `interf` and `link`. Initially, each indicator displays a dash `-`. If the current target has the monitored tag, then the indicator displays the corresponding character (see table 18.3) 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 `ocamlbuild`.

Hence the tag string `ONbp--il` means that the current target `main.cmx` has the tags `ocaml` and `native`, and that the tags `ocaml`, `native`, `byte`, `program`, `interf` and `link` have already been seen.

> Tag | Display character
> ocaml | O
> native | N
> byte | B
> program | P
> pp | R
> debug | D
> interf | I
> link | L

> Table 18.3: Relation between the characters displayed in the tag string and the tags.

### 18.3.23 `ocamllex`, `ocamlyacc` and `menhir`

`ocamlbuild` knows how to run the standard lexer and parser generator tools `ocamllex` and `ocamlyacc` when your files have the standard `.mll` and `.mly` extensions. If you want to use `menhir` instead of `ocamlyacc`, you can either launch `ocamlbuild` with the `-use-menhir` option or add a

    true: use_menhir

line to your `_tags` file. Note that there is currently no way of using `menhir` and `ocamlyacc` in the same execution of `ocamlbuild`.

### 18.3.24 Changing the compilers or tools

As `ocamlbuild` is part of your OCaml distribution, it knows if it can call the native compilers and tools (`ocamlc.opt`, `ocamlopt.opt`...) or not. However you may want `ocamlbuild` to use another `ocaml` compiler for different reasons (such as cross-compiling or using a wrapper such as `ocamlfind`). Here is the list of relevant options:

- `-ocamlc <command>`
- `-ocamlopt <command>`
- `-ocamldep <command>`
- `-ocamlyacc <command>`
- `-menhir <command>`
- `-ocamllex <command>`
- `-ocamlmktop <command>`
- `-ocamlrun <command>`

### 18.3.25 Interaction with version control systems

Here are tips for configuring your version control system to ignore the files and directories generated by `ocamlbuild`.

The directory `_build` and any symbolic links pointing into `_build` should be ignored. To do this, you must add the following ignore patterns to your version control system’s ignore set:

    _build
    *.native
    *.byte
    *.d.native
    *.p.byte

For CVS, add the above lines to the `.cvsignore` file. For Subversion (SVN), type `svn propedit svn:ignore .` and add the above lines.

### 18.3.26 A shell script for driving it all?

To shell or to make ? 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 `/bin/sh` 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:

- Typing `make` to compile is now an automatism,
- We need to share variable definitions between rules and actions,
- Escaping already way too special-character-sensitive shell code with invisible tabs and backslashes is a dangerously fun game.

We also have bad reasons for not using an OCaml script to drive everything:

- `Sys.command` calls the `/bin/sh` anyway,
- Shell scripts can execute partial commands or commands with badly formed arguments.
- Shell scripts are more concise for expressing... shell scripts.

Anyway you are of course free to use a makefile or an OCaml script to call ocamlbuild. Here is an example shell driver script:

    #!/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

## 18.4 Appendix: Motivations

This inflammatory appendix describes the frustration that led us to write `ocamlbuild`.

Many people have painfully found that the utilities of the `make` 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: `make` was designed with the idea of a static dependency graph. Dependency extracting tools, however, are typically run by a rule in `make` itself; this means that make has to reload the dependency information. This is the origin of the `make clean; make depend; make` 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 `make`. 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 `make` 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 (`depend1, depend2...`) 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.

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:

    Files foo.cmo and bar.cmo
    make inconsistent assumptions over interface Bar

The typical reaction is then to issue the mantra `make clean; make depend; make` 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 `make` could correctly guess the small number of files that really had to be recompiled.

It is not surprising that hacking a build tool such as `make` 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 `.ml`s that you want to convert into a list including both `.cmo`s and `.cmi`s, that is you want to transform `a.ml b.ml c.ml` into `a.cmi a.cmo b.cmi b.cmo c.cmi c.cmo` while preserving the dependency order which must be hand specified for linking 2. Unfortunately `$patsubst %.ml, %.cmi %.cmo, a.ml b.ml c.ml` won’t work since the %-sign in the right-hand of a `patsubst` gets substituted only once. You then have to delve into something that is hardly lambda calculus: an intricate network of `foreach`, `eval`, `call` and `define`s may get you the job done, unless you chicken out and opt for an external `awk`, `sed` or `perl` 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 `autotools`.

Note that it is also difficult to write `Makefiles` to build object files in a separate directory. It is not impossible since the language of `make` 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 `foo.mli` is generated by `ocamlyacc` using `foo.mly` and can thus be removed.

## 18.5 Appendix: Summary of default rules

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 `ocamlbuild` with the `-documentation` option.

Tags | Dependencies | Targets
| %.itarget | %.otarget
ocaml | %.mli %.mli.depends | %.cmi
byte, debug, ocaml | %.mlpack %.cmi | %.d.cmo
byte, ocaml | %.mlpack | %.cmo %.cmi
byte, ocaml | %.mli %.ml %.ml.depends %.cmi | %.d.cmo
byte, ocaml | %.mli %.ml %.ml.depends %.cmi | %.cmo
native, ocaml, profile | %.mlpack %.cmi | %.p.cmx %.p.o
native, ocaml | %.mlpack %.cmi | %.cmx %.o
native, ocaml, profile | %.ml %.ml.depends %.cmi | %.p.cmx %.p.o
native, ocaml | %.ml %.ml.depends %.cmi | %.cmx %.o
debug, ocaml | %.ml %.ml.depends %.cmi | %.d.cmo
ocaml | %.ml %.ml.depends | %.cmo %.cmi
byte, debug, ocaml, program | %.d.cmo | %.d.byte
byte, ocaml, program | %.cmo | %.byte
native, ocaml, profile, program | %.p.cmx %.p.o | %.p.native
native, ocaml, program | %.cmx %.o | %.native
byte, debug, library, ocaml | %.mllib | %.d.cma
byte, library, ocaml | %.mllib | %.cma
byte, debug, library, ocaml | %.d.cmo | %.d.cma
byte, library, ocaml | %.cmo | %.cma
| lib%(libname).clib | lib%(libname).a dll%(libname).so
| %(path)/lib%(libname).clib | %(path)/lib%(libname).a %(path)/dll%(libname).so
library, native, ocaml, profile | %.mllib | %.p.cmxa %.p.a
library, native, ocaml | %.mllib | %.cmxa %.a
library, native, ocaml, profile | %.p.cmx %.p.o | %.p.cmxa %.p.a
library, native, ocaml | %.cmx %.o | %.cmxa %.a
| %.ml | %.ml.depends
| %.mli | %.mli.depends
ocaml | %.mll | %.ml
doc, ocaml | %.mli %.mli.depends | %.odoc
| %.odocl | %.docdir/index.html
ocaml | %.mly | %.ml %.mli
| %.c | %.o
| %.ml %.ml.depends | %.inferred.mli

1
  The command must not contain newlines or parentheses.
2
  By the way, what’s the point of having a declarative language if `make` can’t sort the dependencies in topological order for giving them to `gcc` or whatever ?