From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.1.3 (2006-06-01) on yquem.inria.fr X-Spam-Level: X-Spam-Status: No, score=0.4 required=5.0 tests=AWL autolearn=disabled version=3.1.3 X-Original-To: caml-list@yquem.inria.fr Delivered-To: caml-list@yquem.inria.fr Received: from mail4-relais-sop.national.inria.fr (mail4-relais-sop.national.inria.fr [192.134.164.105]) by yquem.inria.fr (Postfix) with ESMTP id 42EEDBB84 for ; Mon, 9 Feb 2009 19:23:53 +0100 (CET) X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: ArkBAMsDkEnUnwdjlGdsb2JhbACCPZF8AQEBAQkLCAkRBLwGhBoG X-IronPort-AV: E=Sophos;i="4.37,406,1231110000"; d="scan'208";a="34959079" Received: from relay.pcl-ipout01.plus.net ([212.159.7.99]) by mail4-smtp-sop.national.inria.fr with ESMTP/TLS/RC4-SHA; 09 Feb 2009 19:23:52 +0100 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: ApsEAMsDkEnUnw4U/2dsb2JhbACCPc5AhBoG Received: from pih-relay08.plus.net ([212.159.14.20]) by relay.pcl-ipout01.plus.net with ESMTP; 09 Feb 2009 18:23:51 +0000 Received: from [87.114.148.153] (helo=leper.local) by pih-relay08.plus.net with esmtp (Exim) id 1LWanO-0002DZ-R2 for caml-list@yquem.inria.fr; Mon, 09 Feb 2009 18:23:51 +0000 From: Jon Harrop Organization: Flying Frog Consultancy Ltd. To: caml-list@yquem.inria.fr Subject: Re: ocamlbuild documentation (was Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3) Date: Mon, 9 Feb 2009 18:28:29 +0000 User-Agent: KMail/1.9.9 References: <1233936696.6216.65.camel@Blefuscu> <0520EBEC-B30C-4D83-9153-A72BC3C986BF@erratique.ch> <499036C6.5070504@lri.fr> In-Reply-To: <499036C6.5070504@lri.fr> MIME-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable Content-Disposition: inline Message-Id: <200902091828.30057.jon@ffconsultancy.com> X-Plusnet-Relay: 12e5c0ee28084a17b5067cb83d033069 X-Spam: no; 0.00; ocaml:01 bunzli:01 coherence:01 headings:01 ocamldoc:01 pathname:01 ocaml:01 lablgl:01 lablgl:01 distro:01 lablgtk:01 ocaml's:01 foo:01 lablgtk:01 programmer's:01 On Monday 09 February 2009 13:59:34 Romain Bardou wrote: > On Monday 09 February 2009 13:36:02 Daniel B=FCnzli 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 bro= ken=20 down hierarchically into a roughly-balanced tree combined with a table of=20 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 ord= er=20 to get ocamlbuild working on any real project is write a plugin. There is n= o=20 table of contents or index for the user guide so you start scrolling down=20 past over two dozen completely random subheadings... finally you reach the= =20 compellingly-titled subheading "3.23 Writing a myocamlbuild.ml plugin" only= =20 to discover that the section is completely empty and is immediately followe= d=20 by "3.24 Interaction with version control systems". As plugins are really the core of ocamlbuild you may be tempted to learn ab= out=20 them from the "plugin API documentation". This turns out to be ocamldoc=20 generated documentation that was created automatically from the source code= =2E=20 Unfortunately, it appears that the source code was not documented and,=20 therefore, this "documentation" is little more than a list of colored=20 definitions. The first page on my screen has 13 definitions, 11 of which ar= e=20 completely undocumented. Clicking on the first ("Pathname") brings you to a= =20 module containing dozens of definitions, none of which have any=20 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 l= ast=20 tried to use it, which was over a year ago (I think). I have not done it=20 justice by studying the current documentation in detail but the only exampl= e=20 listed on "Using an external library" is actually the example I asked for t= he=20 last time I tried to use ocamlbuild and was actually something that really= =20 put me off it. Like any OCaml programmer, I have favorite libraries that I use a lot. In m= y=20 case, I love OpenGL and use LablGL all the time. For me, LablGL is more of = a=20 core library than half of the stuff that comes in the OCaml distro. LablGTK= =20 is even more popular and, in fact, is OCaml's most popular library accordin= g=20 to the popcon results. Consequently, I would expect an ocaml program foo.ml= =20 that used LablGL (and certainly if it used LablGTK) to be handled completel= y=20 automatically by any build tool if there was any hope of it making the=20 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 : use_lablgl, use_lablglut <**/*.ml>: use_lablgl $ ocamlbuild foo.native Why does ocamlbuild not recognise common OCaml libraries out of the box? Is= it=20 possible to factor this boiler plate from one project to the next? If so, I= =20 assume that is done by using myocamlbuild.ml as a full-blown OCaml project = in=20 its own right, in which case how do you build your build project and what=20 builds that? Why is ocamlbuild still disabled by default in the OCaml distr= o? =2D-=20 Dr Jon Harrop, Flying Frog Consultancy Ltd. http://www.ffconsultancy.com/?e