c-cube/manual-ocamlbuild

A new reference manual for the ocamlbuild tool

Temporary OCamlbuild manual repository

This repository for the present OCamlbuild manual is an effort to replace the old manual with something that satisfies users better.

The present documentation is currently only a draft, with parts missing. Contributions are warmly welcome to evolve into a more polished and complete document.

Angles of improvement

The not-good-enough documentation is a subject that often comes up in ocamlbuild discussions. It’s surprisingly hard to get feedback on what should be improved, but here is what I heard:

1. There are not enough short examples to reuse/tweak and forget about.

2. A clear presentation of the basic mental model of the tool is missing.

3. Writing a myocamlbuild.ml is frightening and little help is provided (though the former Wiki, whose content is now on ocaml.org, does answer questions).

I would add two points:

1. There is too much blatter about design philosophies that aren’t terribly helpful in the end

2. The manual doesn’t emphasize enough the combination of ocamlbuild and ocamlfind, as the latter tool was not a given when ocamlbuild was designed. Choosing ocamlbuild + ocamlfind as the default tool combination allows a simpler presentation that does more by default and skips over some less-useful features (use_foo and + non-ocamlfind camlp4 stuff).