Re: ocamlbuild (was Re: [Caml-list] Re: GODI is shutting down)

[Dario Teixeira <darioteixeira@yahoo.com>]

Hi,

> As I said above, I plan to keep using ocamlbuild and incrementally fix

> some of its shortcomings (parallelization, documentation, plugin
> composability...). I hope that some other users will also make a
> contribution and help to solve some of the issues that have been
> reported on the bugtracker (most of them are not very hard to tackle).
> Wojciech and I eager to welcome patches and review them.

Please consider starting with the documentation, which is IMHO OCamlbuild's
Achilles's heel.  I will go as far as saying that what stopped OCamlbuild from
becoming the ultimate OCaml build tool and thus preempting the constant
popping up of new but often ephemeral build tools was precisely the lack
of good documentation.  Moreover, I reckon that even the other OCamlbuild
shortcomings (namely parallelisation) would have been patched long ago
if the tool had gained the community mind share that it missed due to its
poor documentation.

Daniel has already mentioned some of the things wrong with OCamlbuild's docs.
For me, the most egregious aspect of the manual is the lack of a good narrative
and a bird's eye view of the tool.  One can go through the whole document and
remain wondering how does it actually work and what does it do!  The reader
is thus left without a good mental model of the tool.  Moreover, bear in mind that
the wiki documentation is a good resource only *after* one already understands
how the tool works and what the various entities mean and how they fit together.

Anyway, I'm sure you (Gabriel and Wojciech) are well aware of the points I've just
raised, and time availability is the only limiting factor for improving the situation.
But since you've bravely "inherited" the maintenance of OCamlbuild, my 2 cents
is that your short term move that is likely to wield greater long term benefits is
to write a short introduction that allows the reader to really grok OCamlbuild.

Best regards,
Dario Teixeira