Re: ocamlbuild documentation (was Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3)

[Jon Harrop <jon@ffconsultancy.com>]

On Monday 09 February 2009 13:59:34 Romain Bardou wrote:
> On Monday 09 February 2009 13:36:02 Daniel Bünzli wrote:
> > A text with paragraph, words and explanations, not scattered phrases and
> > paragraphs without coherence. You know a structured document.
>
> I'm actually very surprised here. If you look at the "Documentation"
> part of the index:
>
> http://brion.inria.fr/gallium/index.php/Ocamlbuild
>
> Except from the lists, which are, well, lists, like in an appendix, all
> pages meet what you ask.

Daniel asked for a "structured document". That means a document that is broken 
down hierarchically into a roughly-balanced tree combined with a table of 
contents (and possibly even an index).

Look at the section headings of the ocamlbuild user guide:

1.
2.
3. 1
3. 2
3. 3
3. 4
3. 5
3. 6
3. 7
3. 8
3. 9
3.10
3.11
3.12
3.13
3.14
3.15
3.16
3.17
3.18
3.19
3.20
3.21
3.22
3.23
3.24
3.25

That is obviously not a structured document!

Moreover, as I understand it the main thing any user will need to do in order 
to get ocamlbuild working on any real project is write a plugin. There is no 
table of contents or index for the user guide so you start scrolling down 
past over two dozen completely random subheadings... finally you reach the 
compellingly-titled subheading "3.23 Writing a myocamlbuild.ml plugin" only 
to discover that the section is completely empty and is immediately followed 
by "3.24 Interaction with version control systems".

As plugins are really the core of ocamlbuild you may be tempted to learn about 
them from the "plugin API documentation". This turns out to be ocamldoc 
generated documentation that was created automatically from the source code. 
Unfortunately, it appears that the source code was not documented and, 
therefore, this "documentation" is little more than a list of colored 
definitions. The first page on my screen has 13 definitions, 11 of which are 
completely undocumented. Clicking on the first ("Pathname") brings you to a 
module containing dozens of definitions, none of which have any 
documentation.

> The "FAQ" part is not structured, but you should not need it (for "bare
> minimum" standards) except to find more plugin examples.

You said that ocamlbuild's documentation has changed considerably since I last 
tried to use it, which was over a year ago (I think). I have not done it 
justice by studying the current documentation in detail but the only example 
listed on "Using an external library" is actually the example I asked for the 
last time I tried to use ocamlbuild and was actually something that really 
put me off it.

Like any OCaml programmer, I have favorite libraries that I use a lot. In my 
case, I love OpenGL and use LablGL all the time. For me, LablGL is more of a 
core library than half of the stuff that comes in the OCaml distro. LablGTK 
is even more popular and, in fact, is OCaml's most popular library according 
to the popcon results. Consequently, I would expect an ocaml program foo.ml 
that used LablGL (and certainly if it used LablGTK) to be handled completely 
automatically by any build tool if there was any hope of it making the 
programmer's life easier.

Instead, I found that ocamlbuild replaces my current build option of choice:

  ocamlopt foo.ml -I +lablGL lablgl.cmxa lablglut.cmxa foo.ml -o foo

with lots of incidental complexity:

$ cat myocamlbuild.ml
open Ocamlbuild_plugin;;
open Command;;

dispatch begin function
| After_rules ->
    ocaml_lib ~extern:true ~dir:"+lablGL" "lablgl";
    ocaml_lib ~extern:true ~dir:"+lablGL" "lablglut";
| _ -> ()
end;;

$ cat _tags
<main.{byte,native}>: use_lablgl, use_lablglut
<**/*.ml>: use_lablgl

$ ocamlbuild foo.native

Why does ocamlbuild not recognise common OCaml libraries out of the box? Is it 
possible to factor this boiler plate from one project to the next? If so, I 
assume that is done by using myocamlbuild.ml as a full-blown OCaml project in 
its own right, in which case how do you build your build project and what 
builds that? Why is ocamlbuild still disabled by default in the OCaml distro?

-- 
Dr Jon Harrop, Flying Frog Consultancy Ltd.
http://www.ffconsultancy.com/?e