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
_______________________________________________
Caml-list mailing list. Subscription management:
http://yquem.inria.fr/cgi-bin/mailman/listinfo/caml-list
Archives: http://caml.inria.fr
Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
Bug reports: http://caml.inria.fr/bin/caml-bugs
