ocamlbuild documentation

ocamlbuild documentation

[Sam Steingold]

Hi,

What documentation for ocamlbuild is available in in addition to
http://brion.inria.fr/gallium/index.php/Ocamlbuild &
http://nicolaspouillard.fr/ocamlbuild/ocamlbuild-user-guide.html?

Thanks
Sam

Re: [Caml-list] ocamlbuild documentation

[Romain Bardou]

Sam Steingold a écrit :
> Hi,
> 
> What documentation for ocamlbuild is available in in addition to
> http://brion.inria.fr/gallium/index.php/Ocamlbuild &
> http://nicolaspouillard.fr/ocamlbuild/ocamlbuild-user-guide.html?

Hello,

As far as I know there is none.

-- 
Romain Bardou

Re: [Caml-list] ocamlbuild documentation

[Erick Matsen]

Hi--


This is such a common theme on this list, I wonder if it would be
worth setting up a repository of well-commented Ocamlbuild examples.
That would go a long way towards helping beginners (like myself) out.

Would people be interested in contributing such examples? Any ideas
about where to host them?


Thanks,

Erick

On Wed, Oct 21, 2009 at 1:47 AM, Romain Bardou <Romain.Bardou@lri.fr> wrote:
> Sam Steingold a écrit :
>> Hi,
>>
>> What documentation for ocamlbuild is available in in addition to
>> http://brion.inria.fr/gallium/index.php/Ocamlbuild &
>> http://nicolaspouillard.fr/ocamlbuild/ocamlbuild-user-guide.html?
>
> Hello,
>
> As far as I know there is none.
>
> --
> Romain Bardou
>
> _______________________________________________
> 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
>

Re: [Caml-list] ocamlbuild documentation

[Ashish Agarwal]

[-- Attachment #1: Type: text/plain, Size: 1781 bytes --]

> Any ideas about where to host them?

Why not at the first link given? It is a wiki.
http://brion.inria.fr/gallium/index.php/Ocamlbuild

Personally I think what's most needed is a description of the concepts,
although examples of course would help too.


On Wed, Oct 21, 2009 at 9:36 AM, Erick Matsen <ematsen@gmail.com> wrote:

> Hi--
>
>
> This is such a common theme on this list, I wonder if it would be
> worth setting up a repository of well-commented Ocamlbuild examples.
> That would go a long way towards helping beginners (like myself) out.
>
> Would people be interested in contributing such examples? Any ideas
> about where to host them?
>
>
> Thanks,
>
> Erick
>
> On Wed, Oct 21, 2009 at 1:47 AM, Romain Bardou <Romain.Bardou@lri.fr>
> wrote:
> > Sam Steingold a écrit :
> >> Hi,
> >>
> >> What documentation for ocamlbuild is available in in addition to
> >> http://brion.inria.fr/gallium/index.php/Ocamlbuild &
> >> http://nicolaspouillard.fr/ocamlbuild/ocamlbuild-user-guide.html?
> >
> > Hello,
> >
> > As far as I know there is none.
> >
> > --
> > Romain Bardou
> >
> > _______________________________________________
> > 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
> >
>
> _______________________________________________
> 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
>

[-- Attachment #2: Type: text/html, Size: 3175 bytes --]

Re: [Caml-list] ocamlbuild documentation

[Rakotomandimby Mihamina]

10/21/2009 04:36 PM, Erick Matsen:
> This is such a common theme on this list, I wonder if it would be
> worth setting up a repository of well-commented Ocamlbuild examples.
> That would go a long way towards helping beginners (like myself) out.

somthing a bit like that: http://pleac.sourceforge.net/pleac_ocaml/ ?

> Would people be interested in contributing such examples? Any ideas
> about where to host them?

ocamlforge?
sourceforge? google code? freshmeat?

-- 
       Architecte Informatique chez Blueline/Gulfsat:
    Administration Systeme, Recherche & Developpement
                                    +261 33 11 207 36

Re: [Caml-list] ocamlbuild documentation

[Gabriel Kerneis]

On Wed, Oct 21, 2009 at 06:36:52AM -0700, Erick Matsen wrote:
> This is such a common theme on this list, I wonder if it would be
> worth setting up a repository of well-commented Ocamlbuild examples.
> That would go a long way towards helping beginners (like myself) out.

Since ocamlbuild is (unofficially) unmaintained, I wonder if this is
such a good idea.  You might prefer to swich to a more perennial system
(like make).

Regards,
-- 
Gabriel, only half-kidding

Re: [Caml-list] ocamlbuild documentation

[Rakotomandimby Mihamina]

10/21/2009 05:02 PM, Gabriel Kerneis:
>> worth setting up a repository of well-commented Ocamlbuild examples.
> You might prefer to swich to a more perennial system

Not wrong...

-- 
       Architecte Informatique chez Blueline/Gulfsat:
    Administration Systeme, Recherche & Developpement
                                    +261 33 11 207 36

Re: ocamlbuild documentation

[Sylvain Le Gall]

On 21-10-2009, Erick Matsen <ematsen@gmail.com> wrote:
> Hi--
>
>
> This is such a common theme on this list, I wonder if it would be
> worth setting up a repository of well-commented Ocamlbuild examples.
> That would go a long way towards helping beginners (like myself) out.
>
> Would people be interested in contributing such examples? Any ideas
> about where to host them?
>

OCaml Forge is probably the best place to host this kind of project:
http://forge.ocamlcore.org

Probably a lot of potential contributors are already subscribed and you
will get a good visibility among other OCaml projects.

Regards
Sylvain Le Gall

>
> Thanks,
>
> Erick
>
> On Wed, Oct 21, 2009 at 1:47 AM, Romain Bardou <Romain.Bardou@lri.fr> wrote:
>> Sam Steingold a écrit :
>>> Hi,
>>>
>>> What documentation for ocamlbuild is available in in addition to
>>> http://brion.inria.fr/gallium/index.php/Ocamlbuild &
>>> http://nicolaspouillard.fr/ocamlbuild/ocamlbuild-user-guide.html?
>>
>> Hello,
>>
>> As far as I know there is none.
>>
>> --
>> Romain Bardou
>>
>> _______________________________________________
>> 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
>>
>

Regards,
Sylvain Le Gall

[ANN] OCaml Batteries Included, alpha 3

[David Rajchenbach-Teller]

     Dear list,

 We're happy to inform you  that OCaml Batteries Included alpha 3 is now
available for download [1] and/or GODI installation. You may find the
new documentation on-line [2], as well as release notes [3], extended
release notes [4] and the slides for the OCaml Meeting talk [5]. The
list of changes is a tad too long to present here, but the important
part is that we're progressing towards maturity.

Enjoy!

The OCaml Batteries Included team

[1] http://forge.ocamlcore.org/frs/?group_id=17&release_id=73
[2]
http://forge.ocamlcore.org/docman/index.php?group_id=17&selected_doc_group_id=59&language_id=1 
[3]  https://forge.ocamlcore.org/frs/shownotes.php?release_id=73 
[4]
http://dutherenverseauborddelatable.wordpress.com/2009/02/06/ocaml-batteries-included-alpha-3/ 
[5]
http://forge.ocamlcore.org/docman/index.php?group_id=77&selected_doc_group_id=84&language_id=1 

-- 
David Teller-Rajchenbach
 Security of Distributed Systems
  http://www.univ-orleans.fr/lifo/Members/David.Teller
   « Ce matin Un crétin A tué un chercheur. » (air connu)
   Latest News of French Research: System being liquidated. Researchers angry.

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

[Daniel Bünzli]

Le 9 févr. 09 à 14:22, Romain Bardou a écrit :

> Well I would disagree and say that the bare minimum is here. This is  
> why I stopped contributing to the wiki: I had nothing else  
> interesting to add. So now I ask: what exactly is missing from this  
> bare minimum?

A text with paragraph, words and explanations, not scattered phrases  
and paragraphs without coherence. You know a structured document.

> In my opinion, questions such as "can I use the flag function inside  
> the rule function" are definitely not part of the bare minimum.

Not but maybe _when_ I'm supposed to call Plugin.flag is.

> (btw, the answer is: the use of the flag function inside the rule  
> function is not specified, thus not documented)

What do you mean by "not specified", your beautiful "manual" doesn't  
even tell me where/when I should call Plugin.flag.

Best,

Daniel

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

[Romain Bardou]

>> Well I would disagree and say that the bare minimum is here. This is 
>> why I stopped contributing to the wiki: I had nothing else interesting 
>> to add. So now I ask: what exactly is missing from this bare minimum?
> 
> 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. To me everything contains structure, paragraph, 
explanations, coherence, and is not scattered. Is, for instance, the 
"Solver mechanism" page really that badly written?

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

>> In my opinion, questions such as "can I use the flag function inside 
>> the rule function" are definitely not part of the bare minimum.
> 
> Not but maybe _when_ I'm supposed to call Plugin.flag is.
> 
>> (btw, the answer is: the use of the flag function inside the rule 
>> function is not specified, thus not documented)
> 
> What do you mean by "not specified", your beautiful "manual" doesn't 
> even tell me where/when I should call Plugin.flag.

Indeed, it is not exactly said and should be added in the API 
documentation, but because the API documentation is not a wiki, I cannot 
do that, and neither can you. However, the "Making plugins" page of the 
wiki does contain this sentence: "This is usually done After_rules." in 
the "Manage tags" part. It is true that it does not mention explicitely 
the "flag" function, but along with the examples it should be clear 
enough. Isn't it?

-- 
Romain Bardou

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

[Jon Harrop]

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

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

[DooMeeR]

I'll skip over the documentation questions because people are beginning 
to say that I troll too much :p

> 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

This is, indeed, and in my opinion, one of the BIGGEST problem with 
Ocamlbuild right now. In fact you didn't chose the easiest solution, 
which is:

ocamlbuild -cflags -I,+lablGL -lflags -I,+lablGL -lib lablgl -lib 
lablglut foo.native

However, this is of course very hackish, not documented (took me a while 
to figure that this was the simplest way of using a library), and still 
not satisfying at all. The extension of Ocamlbuild I am working on 
should allow you to replace this by:

ocamlbuild -pkg lablGL.glut foo.native

(the package lablGL.glut depends on the package lablGL, which will thus 
be included automatically)

I will work on an extension to allow tags such as use_pkg(lablGL.glut) 
to put this in a _tag file if you get tired of using the command line 
option.

This will require findlib though. If you do not have findlib, another 
solution I may implement someday would be:

ocamlbuild -libs +lablGL/lablgl,+lablGL/lablglut foo.native

Which is still better than the solution using ocamlopt directly IMO 
(because here, ocamlbuild can at least guess whether it should include 
the .cmxa or the .cma).

Now, I don't think it will happen someday that Ocamlbuild will be able 
to guess that lablGL should be included. It raises too many questions :(

-- 
Romain Bardou

Re: ocamlbuild documentation

[Jan Kybic]

>> 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:

I agree with the previous posters that ocamlbuild is a great project
but the documentation is not yet sufficient for a beginner. Let me
recall my recent experience:

Yesterday, out of curiosity, I have tried to use Ocaml for my current
project. It is not complicated, just a few Ocaml source files with a
few libraries. In Ocamlmake, I only had to list the SOURCES and set

PACKS = lacaml unix extlib str gsl

In ocamlbuild, I spent a long time finding out how to tell Ocaml to
use the required libraries.  I took the ocamlfind plugin from
the Ocamlbuild wiki
(http://brion.inria.fr/gallium/index.php/Using_ocamlfind_with_ocamlbuild)
and created the following _tags file:

<*.ml> or <*.mli>: pkg_extlib, pkg_gsl, pkg_str, pkg_unix
<dList.ml>: ocaml, pp(ocaml+twt), debug
<utils.ml>: ocaml, pp(camlp4o), debug

Now, all files compiled correctly. However, the linking failed with
message "No implementations provided for the following modules". I could
eliminate some of the messages by invoking ocamlbuild as

  ocamlbuild -libs str,unix,bigarray,gsl matvflss.native

but this did not help with gsl and extlib libraries.  Finally, after
many frustrating attempts I could link everything using:

ocamlbuild -lflags -I,/usr/lib/ocaml/site-packages/gsl -lflags -I,/usr/lib/ocaml/site-packages/extlib -libs str,unix,bigarray,gsl,extLib   matvflss.native

So finally yes, ocamlbuild works. But for a beginner, it is currently more
complicated to use than Ocamlmake. Instead of a few lines in a
Makefile, you need to write myocamlbuild.ml, _tags, and a script
automating the command line.  I found the command line more or less by
trial and error and by looking at the examples. It is admittedly my
fault since there is one relevant sentence in the manual ("You may
need to add options such as...") but it is easy to miss.

Why do I have to manually set all the paths and library names
if I have already said "pkg_..." in _tags? Why does not ocamlbuild
uses ocamlfind to find out automatically? I thought the plugin was
supposed to do exactly this.

By the way, how am I supposed to use the caml-types-show-type feature
in Emacs Tuareg mode, if ocamlbuild forces all the annot files into
the _build subdirectory?


I am sure Ocamlbuild will mature with time and become a very useful
tool. Keep up the good work.

Jan


-- 
-------------------------------------------------------------------------
Jan Kybic <kybic@fel.cvut.cz>                       tel. +420 2 2435 5721
http://cmp.felk.cvut.cz/~kybic                      ICQ 200569450