[ANN] OCaml Batteries Included, alpha 3

[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: [Caml-list] [ANN] OCaml Batteries Included, alpha 3

[Mikkel Fahnøe Jørgensen]

Great work.

I just quickly scanned the Batteries slideshow.
Regarding the analysis of popular languages, I agree.
But I think one very important aspect is being overlooked:

I think the build system is extremely important, just after library support.

I believe the success of "scripting" and especially dynamic typing is
that you can just write some code and run it. Rarely do have to
consider make files etc. Of course, the problem sometimes just
multiplies so all end users have to deal with installing the proper
libraries, but this is partially offset by having good standard
libraries.

I also believe the success of dynamic typing is mostly due to the fact
that you can just get starting doing whatever you like. Fortunately
for OCaml this is also true for type inference, and I think this is
why so many Ruby programmers also look a little into OCaml.

I think the build environment is one of OCamls great weaknesses and
that we need to improve here before the language well ever go
mainstream. Most of these problems relate to a comparatively complex
ocaml tool chain, but another problem is the tendency of library
writers to delibarately use non-portable tools where they are not
really needed - simply because others do the same and eventually it
just becomes to difficult to support cross platform builds.

So in conclusion, Batteries is a very important contribution but we
must also improve on the tool chains and build environment.
ocamlbuild, flexdll, cross platform findlib and ocamlmklib are all
steps in the right direction.

Mikkel

2009/2/6 David Rajchenbach-Teller <David.Teller@ens-lyon.org>:
>     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.
>
> _______________________________________________
> 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: [ANN] OCaml Batteries Included, alpha 3

[Sylvain Le Gall]

Hello,

On 07-02-2009, Mikkel Fahnøe Jørgensen <mikkel@dvide.com> wrote:
> So in conclusion, Batteries is a very important contribution but we
> must also improve on the tool chains and build environment.
> ocamlbuild, flexdll, cross platform findlib and ocamlmklib are all
> steps in the right direction.
>

- ocamlbuild works on windows and linux
- findlib works on windows and linux

(however you need some tools from cygwin in some case like for building
findlib)

flexdll is not required directly (i think you don't need to invoke it
directly) and ocamlmklib can be replaced by ocamlbuild.

Building ocaml itself is still complicated on Windows (but not that much
once you know how to do it), but I don't think you can easily address
this problem in any way.

So: what need to be improved?

Regards
Sylvain Le Gall

ps: I have no data concerning MacOS, FreeBSD and other

Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3

[Jon Harrop]

On Saturday 07 February 2009 14:43:49 Sylvain Le Gall wrote:
> Hello,
>
> On 07-02-2009, Mikkel Fahnøe Jørgensen <mikkel@dvide.com> wrote:
> > So in conclusion, Batteries is a very important contribution but we
> > must also improve on the tool chains and build environment.
> > ocamlbuild, flexdll, cross platform findlib and ocamlmklib are all
> > steps in the right direction.
>
> - ocamlbuild works on windows and linux
> - findlib works on windows and linux
>
> (however you need some tools from cygwin in some case like for building
> findlib)
>
> flexdll is not required directly (i think you don't need to invoke it
> directly) and ocamlmklib can be replaced by ocamlbuild.
>
> Building ocaml itself is still complicated on Windows (but not that much
> once you know how to do it), but I don't think you can easily address
> this problem in any way.
>
> So: what need to be improved?

Documentation! I tried to use ocamlbuild several times and gave up because I 
could not figure out how to do simple things.

I used Makefiles for a bit but make/ocamldep is so fragile that it broke so 
often I ended up doing "make clean; make" to rebuild at every edit. So now my 
method of choice is either writing the compile line out by hand every time or 
using a bash script that always recompiles everything.

Fortunately OCaml is ridiculously fast at compiling so there is almost no need 
for incremental compilation anyway. Although I would appreciate parallel 
builds...

> ps: I have no data concerning MacOS, FreeBSD and other

I managed to get Smoke compiled and running on Mac OS, which is LablGL as well 
as OCaml itself. I thought Mac OS X sucked but I can hardly blame OCaml for 
that. ;-)

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

Re: [ANN] OCaml Batteries Included, alpha 3

[Sylvain Le Gall]

On 07-02-2009, Jon Harrop <jon@ffconsultancy.com> wrote:
> On Saturday 07 February 2009 14:43:49 Sylvain Le Gall wrote:
>> Hello,
>>
>> On 07-02-2009, Mikkel Fahnøe Jørgensen <mikkel@dvide.com> wrote:
>> > So in conclusion, Batteries is a very important contribution but we
>> > must also improve on the tool chains and build environment.
>> > ocamlbuild, flexdll, cross platform findlib and ocamlmklib are all
>> > steps in the right direction.
>>
>> - ocamlbuild works on windows and linux
>> - findlib works on windows and linux
>>
>> (however you need some tools from cygwin in some case like for building
>> findlib)
>>
>> flexdll is not required directly (i think you don't need to invoke it
>> directly) and ocamlmklib can be replaced by ocamlbuild.
>>
>> Building ocaml itself is still complicated on Windows (but not that much
>> once you know how to do it), but I don't think you can easily address
>> this problem in any way.
>>
>> So: what need to be improved?
>
> Documentation! I tried to use ocamlbuild several times and gave up because I 
> could not figure out how to do simple things.
>

Good point indeed. 

> I used Makefiles for a bit but make/ocamldep is so fragile that it broke so 
> often I ended up doing "make clean; make" to rebuild at every edit. So now my 
> method of choice is either writing the compile line out by hand every time or 
> using a bash script that always recompiles everything.
>

Same with OCamlMakefile which doesn't detect library update (even in the
same source tree). This problem disappear with ocamlbuild which is a
good tool for this. More documentation would allow more people to
use it and to improve it.

Regards,
Sylvain Le Gall

Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3

[Paolo Donadeo]

> Fortunately OCaml is ridiculously fast at compiling so there is almost no need
> for incremental compilation anyway. Although I would appreciate parallel
> builds...

The first approach with ocamlbuild is quite difficult because
documentation is very incomplete and fragmentary, but give it a try:
my life changed since when I gave up with makefiles and started using
ocamlbuild. And, of course, ocamlbuild supports parallel and
incremental build (-j option).


-- 
Paolo
~
~
:wq

Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3

[Matthieu Dubuget]

Sylvain Le Gall a écrit :
> On 07-02-2009, Jon Harrop <jon@ffconsultancy.com> wrote:
>> On Saturday 07 February 2009 14:43:49 Sylvain Le Gall wrote:
>>> So: what need to be improved?
>> Documentation! I tried to use ocamlbuild several times and gave up because I 
>> could not figure out how to do simple things.
> 
> Good point indeed. 
> 

An other points that could be improved, concerning ocamlbuild are:
- modules (planned, but I don't know how many time the owners of
ocamlbuild have?)
- better integration with findlib (modules would help, and also the
possibility to use directly findlib modules from ocamlbuild modules)

Salutations

Matt

Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3

[David Rajchenbach-Teller]

On Sat, 2009-02-07 at 17:13 +0100, Matthieu Dubuget wrote:
> An other points that could be improved, concerning ocamlbuild are:
> - modules (planned, but I don't know how many time the owners of
> ocamlbuild have?)

I don't quite understand this.

> - better integration with findlib (modules would help, and also the
> possibility to use directly findlib modules from ocamlbuild modules)

The myocamlbuild.ml provided with Batteries Included manages findlib
(that's actually based on an extract provided in the documentation of
OCamlBuild).

Cheers,
 David


-- 
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: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3

[Daniel Bünzli]

Le 7 févr. 09 à 15:43, Sylvain Le Gall a écrit :

> So: what need to be improved?

Cross platform package instructions and a package system.

Haskellers got it the right way [1], design the package system first  
then select a few stable packages to become batteries included. OCaml  
got it the wrong way by first trying to build a huge monolithic  
library. Everything that's not in the monolothic batteries is still  
harder to install than it should be.

Best,

Daniel

[1] http://www.cse.unsw.edu.au/~dons/papers/haskell31-coutts.pdf

Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3

[Matthieu Dubuget]

David Rajchenbach-Teller a écrit :
> On Sat, 2009-02-07 at 17:13 +0100, Matthieu Dubuget wrote:
>> An other points that could be improved, concerning ocamlbuild are:
>> - modules (planned, but I don't know how many time the owners of
>> ocamlbuild have?)
> 
> I don't quite understand this.

>From the very beginning, I had the feeling that ocamlbuild's author
had planned to make the monolithic myocamlbuild system more modular.
I may be wrong.

My idea is that it would be very useful if one could specify other
modules to compile and use (and the associated command line if
necessary) instead of copy-paste everything needed into myocamlbuild.

> 
>> - better integration with findlib (modules would help, and also the
>> possibility to use directly findlib modules from ocamlbuild modules)
> 
> The myocamlbuild.ml provided with Batteries Included manages findlib
> (that's actually based on an extract provided in the documentation of
> OCamlBuild).

Yes. I'm aware of that. But the tags associated to each package are
constructed by calling ocamlfind as an external process, and parsing the
output of ocamlfind. It would be cleaner and certainly more powerful if
myocamlbuild module could use directly the findlib library provided with
findlib?

My development tree is composed of a lot of libraries. They have
inter-dependencies. I would like to use ocamlfind more consistently,
because this is very a nice tool. When properly configured, if I want to
use Toto, i just have to add the toto package, and all dependencies and
link options are sorted automatically.

If I modify one library which is known by ocamlfind, I would like to be
able to have all other packages that depends on it to be compiled again,
and finally the target I'm working on. This not easy to achieve.

And when I extract a fresh tree from my repository, I would like to have
everything compiled and installed with an ocamlbuild all.otarget command.

But I may be wrong by mixing the two levels: building with ocamlbuild
and library use with ocamlfind.

Sorry if all this is not clear, but it is not (yet) very clear for me…

Salutations

Matt

P.S. When writing this post, I had a new idea that may simplify my
problem: adding my development tree to findlib.conf path seems enough to
let findlib find and use my own packages, without having to install them.

Re: [Caml-list] [ANN] OCaml Batteries Included, alpha 3

[Richard Jones]

On Sat, Feb 07, 2009 at 03:21:17PM +0100, Mikkel Fahnøe Jørgensen wrote:
> I think the build system is extremely important, just after library support.
> 
> I believe the success of "scripting" and especially dynamic typing is
> that you can just write some code and run it. Rarely do have to
> consider make files etc. Of course, the problem sometimes just
> multiplies so all end users have to deal with installing the proper
> libraries, but this is partially offset by having good standard
> libraries.

Please don't write yet another build system to fix perceived problems
with current ones.  You'll just end up with N+1 build systems, making
the choice even more confusing than now.  And I guarantee that your
new build system won't work for some combination of {cross-
compilation, Windows, AIX, PowerPC-64} user, which means it'll be
strictly less useful than autotools which has nearly 20 years of
development and experience behind it.

Instead: write better documentation for existing build systems.

For example, everyone loves to hate autoconf (me included), but in
actual fact you only have to write two files containing under 10 lines
of code in each, to make a complete build environment for an OCaml
program under autotools.  This fact probably isn't obvious, because
nowhere is it documented.

So a good task would be to document this[1].

Similarly, plain Makefiles are easy to do, including working
dependencies.  Just needs to be documented.

Rich.

[1] A good place to start would be
http://www.annexia.org/tmp/ocaml-mingw-gtk

-- 
Richard Jones
Red Hat

RE: [Caml-list] [ANN] OCaml Batteries Included, alpha 3

[David Allsopp]

On Sun, Feb 08, 2009 Richard Jones wrote:
> For example, everyone loves to hate autoconf (me included), but in
> actual fact you only have to write two files containing under 10 lines
> of code in each, to make a complete build environment for an OCaml
> program under autotools.  This fact probably isn't obvious, because
> nowhere is it documented.

+1! And projects like GnuWin32[1] mean that it doesn't take too much extra
work to support Windows builds within the same build framework.

> Similarly, plain Makefiles are easy to do, including working
> dependencies.  Just needs to be documented.

Would a line-by-line analysis of something comprehensive like OCamlMakefile
be a good example for anyone wishing to see how OCaml building is expressed
in make (I'm afraid I don't use it so can't really volunteer to do that - I
get everything I need for writing Makefiles from the GNU info pages and
O'Reilly's excellent "Managing projects with make" book)


David



[1] http://gnuwin32.sourceforge.net

Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3

[Romain Bardou]

>> So: what need to be improved?
> 
> Documentation! I tried to use ocamlbuild several times and gave up because I 
> could not figure out how to do simple things.

Is the problem really the lack of documentation or a problem to find it 
because it is not on the caml.inria.fr website?

The wiki:
http://brion.inria.fr/gallium/index.php/Ocamlbuild
should answer all questions you have to compile simple projects. In 
fact, the user manual (first link on the wiki) should answer these 
questions.

It would really help to improve the documentation if you could explain 
what were the problems you encountered and where did you look for the 
documentation.

Please note that since the first OCaml meeting (last year), the wiki has 
changed quite a bit, so if you tried Ocamlbuild before, you might want 
to try it again.

-- 
Romain Bardou

Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3

[Romain Bardou]

> - better integration with findlib (modules would help, and also the
> possibility to use directly findlib modules from ocamlbuild modules)

I have a few patches ready for Ocamlbuild which:
- add some support for Findlib in the plugin API
- add a -pkg option (to be used instead of -lib)

I will work on what we call parameterized tags to be able to write tags 
such as use_pkg(unix). Right now I miss time but I hope that the whole 
system will be ready before 3.12.

All these should greatly improve the integration of findlib into 
Ocamlbuild. My goal is that the findlib plugin on the wiki becomes obsolete.

-- 
Romain Bardou

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

[Daniel Bünzli]

Le 9 févr. 09 à 10:32, Romain Bardou a écrit :

> It would really help to improve the documentation if you could  
> explain what were the problems you encountered and where did you  
> look for the documentation.

Simple projects are not the problem. The plugin interface lacks  
documentation.

> Please note that since the first OCaml meeting (last year), the wiki  
> has changed quite a bit, so if you tried Ocamlbuild before, you  
> might want to try it again.

Wikis are nice but not are no substitute for real documentation. The  
designers of ocamlbuild should once take the time to thoroughly  
explain and document the philosophy and workings of ocamlbuild; how  
does it work, what is the right way to do thing, what is the wrong way  
to do things, how do I achieve this etc.

So far every program of the caml toolchain had sufficiently clear  
documentation in ocaml's manual. With respect to that ocamlbuild is an  
unwelcomed precedent.

It's sad because this seems to hinder the adoption of this very  
powerful tool that IMHO drifts away from make nightmares in the right  
way. For example being able to do this kind of tricks [1] without any  
hassle is just a blessing for your modularity and productivity.

Best,

Daniel

[1] http://brion.inria.fr/gallium/index.php/Working_on_dependent_projects_with_ocamlbuild

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

[Romain Bardou]

> Simple projects are not the problem. The plugin interface lacks 
> documentation.

Well I would like to know what "simple things" Jon could not do then.

> Wikis are nice but not are no substitute for real documentation. The 
> designers of ocamlbuild should once take the time to thoroughly explain 
> and document the philosophy and workings of ocamlbuild; how does it 
> work, what is the right way to do thing, what is the wrong way to do 
> things, how do I achieve this etc.
> 
> So far every program of the caml toolchain had sufficiently clear 
> documentation in ocaml's manual. With respect to that ocamlbuild is an 
> unwelcomed precedent.

Is it just a matter of copy/pasting the contents of the wiki into the 
OCaml manual? Or does the wiki really lacks important information? As 
far as I can tell it does answer a lot of the questions you highlighted.

-- 
Romain Bardou

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

[Daniel Bünzli]

Le 9 févr. 09 à 12:51, Romain Bardou a écrit :

> Is it just a matter of copy/pasting the contents of the wiki into  
> the OCaml manual?

Are you serious ?

> Or does the wiki really lacks important information?

Yes, the way the plugin api works is still lagely undocumented (a  
random example is it possible to use Plugin.flag inside a rule and  
what would the effects be ? another is why is the tags argument of  
Plugin.rule deprectated and thus how can I make a rule apply only if a  
file has a given tag or maybe I shouldn't do that, etc.).

There are a lot of things the authors of ocambuild know that are not  
in the wiki and that I don't want to discover by trial/error/ 
understand the ocamlbuild source/consult mailling list/try to look at  
the wiki and I'd be very grateful to them if they'd share this  
knowledge in a well-written manual.

> As far as I can tell it does answer a lot of the questions you  
> highlighted.

Many people don't understand that very often the barrier to adoption  
is just a single, extensive source of documentation called a manual.  
Let me repeat that again, a wiki (or its content) is not a substitute  
for a manual. The whole carefully edited "big picture" documentation  
is missing and you won't get that by copy and pasting random samples  
from the wiki. We need this well-written thing called a manual that  
any respectful tool should provide, they had a good start here [1] but  
it is not sufficient as it covers only the simplest cases.

Daniel

[1] http://nicolaspouillard.fr/ocamlbuild/ocamlbuild-user-guide.html

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

[Romain Bardou]

>> Is it just a matter of copy/pasting the contents of the wiki into the 
>> OCaml manual?
> 
> Are you serious ?

You don't have to be so mean :(

> Yes, the way the plugin api works is still lagely undocumented (a random 
> example is it possible to use Plugin.flag inside a rule and what would 
> the effects be ? another is why is the tags argument of Plugin.rule 
> deprectated and thus how can I make a rule apply only if a file has a 
> given tag or maybe I shouldn't do that, etc.).

Unfortunately, while authors might be the best persons to answer these 
questions, they are also the ones who do not have any question ;) 
Finding the right questions is not easy and a Wiki is a nice way to find 
out.

> There are a lot of things the authors of ocambuild know that are not in 
> the wiki and that I don't want to discover by trial/error/understand the 
> ocamlbuild source/consult mailling list/try to look at the wiki and I'd 
> be very grateful to them if they'd share this knowledge in a 
> well-written manual.
> 
>> As far as I can tell it does answer a lot of the questions you 
>> highlighted.
> 
> Many people don't understand that very often the barrier to adoption is 
> just a single, extensive source of documentation called a manual. Let me 
> repeat that again, a wiki (or its content) is not a substitute for a 
> manual. The whole carefully edited "big picture" documentation is 
> missing and you won't get that by copy and pasting random samples from 
> the wiki. We need this well-written thing called a manual that any 
> respectful tool should provide, they had a good start here [1] but it is 
> not sufficient as it covers only the simplest cases.

While I agree that the documentation should answer most questions, I 
fail to see how "try to look at the wiki" is different from "try to look 
at the manual". The only problem I have with the wiki is that it is not 
in the same place as the OCaml manual. Do we have to rename "wiki" into 
"manual in which you can write your own notes" ? :)

-- 
Romain Bardou

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

[Daniel Bünzli]

Le 9 févr. 09 à 13:52, Romain Bardou a écrit :

> You don't have to be so mean :(

Sorry.

> Unfortunately, while authors might be the best persons to answer  
> these questions, they are also the ones who do not have any  
> question ;) Finding the right questions is not easy and a Wiki is a  
> nice way to find out.

You need a reasonable base documentation first if you want people to  
try your system. The bare minimum (i.e. the one that doesn't make your  
loose your time with the system) is not here yet. And if you want to  
build things for others to use you better have some empathy, so you  
should be able to imagine some of these questions.

> While I agree that the documentation should answer most questions, I  
> fail to see how "try to look at the wiki" is different from "try to  
> look at the manual".

What I see in the wiki doesn't qualify as a manual to me.

> Do we have to rename "wiki" into "manual in which you can write your  
> own notes" ? :)

The problem is that "wiki" here seems to stand for "write the manual  
for me please".

Daniel

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

[Romain Bardou]

> You need a reasonable base documentation first if you want people to try 
> your system. The bare minimum (i.e. the one that doesn't make your loose 
> your time with the system) is not here yet. And if you want to build 
> things for others to use you better have some empathy, so you should be 
> able to imagine some of these questions.
 >
 > What I see in the wiki doesn't qualify as a manual to me.

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? In my 
opinion, questions such as "can I use the flag function inside the rule 
function" are definitely not part of the bare minimum.

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

-- 
Romain Bardou

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)

[Romain Bardou]

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

Sorry, I answered too fast: "flag" is really different than "tag", so my 
answer is kind of silly here ;) However, there ARE some examples in the 
part which talks about "flag", where we clearly see an usage (After_rules).

-- 
Romain Bardou

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

[Daniel Bünzli]

Le 9 févr. 09 à 15:04, Romain Bardou a écrit :

>  However, there ARE some examples in the part which talks about  
> "flag", where we clearly see an usage (After_rules).

Which doesn't mean it cannot be used differently.

Anyway it seems useless arguing further: we just don't have the same  
standards.

The only thing I see is that there are still a lot of mentions to  
makefiles on this list and a lot of new projects don't use ocamlbuild  
while ocamlbuild is clearly a superior alternative. The only way I can  
explain this is by lack of good documentation. If you get the standard  
distribution you don't get documentation for ocamlbuild (except a  
brief manpage), there's no chapter on ocambuild in the manual, caml's  
site documentation page doesn't even have a link to the small manual  
or the wiki (you'll have to google to find it), the plugin api  
documentation is not installed etc. etc.

It's a pitty, given its caml only implementation, ocamlbuild could  
become a key part of a solid cross platform infrastructure for ocaml.  
Alas it doesn't seem to be used much (and the reason is IMHO the sad  
state of its documentation/advertising).

Best,

Daniel

Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3

[David Teller]

That would be great.
On the Batteries side, we now have (on the git) a drop-in replacement
for ocamlbuild which doesn't require any myocamlbuild.ml or _tags to use
Batteries. (it's actually a one-liner shell script, which invokes
ocamlbuild).

Cheers,
 David

On Mon, 2009-02-09 at 10:36 +0100, Romain Bardou wrote:
> All these should greatly improve the integration of findlib into 
> Ocamlbuild. My goal is that the findlib plugin on the wiki becomes obsolete.
> 
-- 
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)

[Kuba Ober]

> Le 9 févr. 09 à 15:04, Romain Bardou a écrit :
>
>> However, there ARE some examples in the part which talks about  
>> "flag", where we clearly see an usage (After_rules).
>
> Which doesn't mean it cannot be used differently.
>
> Anyway it seems useless arguing further: we just don't have the same  
> standards.
>
> The only thing I see is that there are still a lot of mentions to  
> makefiles on this list and a lot of new projects don't use  
> ocamlbuild while ocamlbuild is clearly a superior alternative. The  
> only way I can explain this is by lack of good documentation.

I'd argue that make's documentation is no better. The TeXinfo pages  
distributed with GNU make are useful as a reference, but if you don't  
use make much it's a big pain. A good manual IMHO should essentially  
have two parts: first is a narrative introduction of all features,  
with good examples. Second is a reference section where each command/ 
setting/UI element is documented in detail.

I have to use make and similarly documented tools (say gnuplot) about  
40% of any given 12 month period. I waste lots of time looking for  
same information over and over... simply because it's *documented* but  
in some hard-to-get-to corner of the hypertext tree. Even Octave's  
manual, though more conventional in style, is still written in such a  
way that there are no pointers to most common features if all you do  
is look at the contents table...

OCaml's manual is, unfortunately, in the same class. For someone who  
is not a devoted, full-time user, it's virtually useless. Unless you  
know the term/keyword you're looking for, there's no way to find it  
short of going through the whole thing page-by-page.

Such manuals are designed to adhere to some 'higher deity' "standards"  
of organization, which make them useful to robots perhaps, but nut to  
humans. There's utter lack of locality of reference. The authors also  
somehow abhor saying things out like they are. Instead of "just saying  
it", the sprinkle the information all over the place,  in places you'd  
least expect to find it.

Suppose I haven't used lists in OCaml much and would like to refresh  
my memory. There's a sparse "introduction" to them in section 1.2.  
List.map is "introduced" in 1.3; List.assoc in 1.6. The syntax of list  
constants (ekhm, sorry, they are called list expressions) is basically  
assumed. The list type syntax is given in 19.1. The list concatenation  
operator is given in Module Pervasives documentation, in the "List  
operations" section. Why the plural? -- beats me. And then there's the  
List Module which gives the rest of it. There's no single place that  
actually gives list syntax and explicitly says: dude, a list is  
written as [ foo; bar; baz ]. Section 6.7 gives expression syntax,  
which includes list expressions, but the *narrative* of list syntax is  
given in -- of all places -- section 6.7.2 "operations on data  
structures", under the heading "Variants". All in all, this is a good  
WTF of a manual.

Lisp's hyperspec is, after some getting used to, a better "manual"  
than OCaml's "manual" is. Even though a specification is typically  
unfit for daily consumption, at least it's reasonably self-consistent,  
so once you figure out how it's structured, you'll find things where  
you expect to find them. This doesn't address the locality of  
reference (there's hardly any) and similar maladies, but at least it  
doesn't suffer from lack of self-consistency. It's a bad manual, but  
at least everywhere it's bad just the same. OCaml's manual is bad in  
many different ways, but not always, and not at the same time. This  
actually make's it even worse...

Jon's "OCaml for Scientists" is written more in the way a manual would  
be written, but Jon didn't intend to write a manual in the first  
place, so I cannot blame him that the book isn't really useable as a  
full-blown manual. It does its prescribed job just fine, though.

If there's a good manual I had first-hand experience with, it must be  
the one that came with Borland's Turbo Pascal. It was entirely clear  
and understandable back when I was in elementary school. This is in  
spite of my English being pretty elementary too, back then. Not only  
was all the information I ever needed in the manual, but it included  
all the nitty-gritty details you needed to interface to Pascal code  
from assembly, and the other way around. Down to the layout of  
compiler-generated stuff (vtables, packing, etc). It was also included  
in the on-line help system, and there the hypertext navigation  
actually made it more accessible/navigable. Must be one of the very  
few manuals which were originally written on paper, and then meshed  
with hypertext while improving usability. I can only give Borland's  
doc team from back then highest praise.

Writing good documentation takes skills which don't necessarily mesh  
with skills of an accomplished software engineer. It's an added bonus  
if a software engineer/scientist is a good documentation writer, but  
that's very, very rare. There are many either excellent or pretty  
decent open source tools that desperately need a manual written by  
someone who knows how to do it. The authors are good at making the  
tools, but their technical writing skills leave a lot to be desired.  
I'm referencing stuff that I use: OCaml, make, autotools, Octave,  
gnuplot, Maxima, ...

Cheers, Kuba

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)

[David Teller]

(Here's hoping that this thread doesn't degenerate into a slugfest)

I have used OCamlBuild a lot. I can confirm that this is great software.
Unfortunately, I can also confirm that, to do anything besides compiling
trivial projects, the Wiki proved extremely elusive at best. My best
source of information (besides bugging ertai on IRC :)) was to dig in
the mostly uncommented source code of OCamlBuild, without being certain
of what was supposed to be public, what was supposed to be known by
users, etc.

Now, what needs to be written? That's hard to summarize in one sentence,
and that's probably why people tend not to contribute to the Wiki once
they have found what they need. My personal take would be the following:

* take the current official OCamlBuild manual and turn it into chapter 1
of "the OCamlBuild handbook"

* write a complete and detailed step-by-step tutorial on writing a _tags
file for a simple project, with an appendix detailing all the existing
available tags (including the commonly used tags which I believe are
automatically generated, such as [pack(...)] ) -- and please write that
tutorial for a newbie, not for me

* progressively complete that tutorial to add all sorts of
not-that-trivial cases such as using OCamlFind, then  building a library
which is going to be used by the rest of the build process, then
building a syntax extension which is going to be used by the rest of the
build process, ... (all sorts of things which are already on the Wiki,
just with more structure and more details)

* progressively complete further that tutorial to add quite complex
cases such as integrating things which are not OCaml at all, including C
code, LaTeX documentation compiled to both pdf and html, generation
of .ml/.mli files during compilation (we have an example of this kind of
thing in  Batteries, where we have to generate .mli from .mlpack to
allow ocamldoc to work on .mlpack files), etc. (some of this is on the
Wiki already, but needs more structure and more details)

* write a complete and detailed step-by-step tutorial on converting an
existing project based on a relatively complex Makefile to _tags and
myocamlbuild.ml

* add at least the first chapter (preferably everything) to the OCaml
manual

* ask a user who has used OCamlBuild for trivial projects (preferably
one who sits in an office close to that of either Romain Bardou or
Nicolas Pouillard) to comment the source code (first the .mli and
the .ml)

* be available to answer the questions of that user  :)

Just my two cents.

Cheers,
 David

P.S.: And if there's no room for this kind of tutorial in the OCaml
documentation, we'll be glad to have it into OCaml Batteries Included :)

On Mon, 2009-02-09 at 14:22 +0100, Romain Bardou wrote:
> 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? In my 
> opinion, questions such as "can I use the flag function inside the rule 
> function" are definitely not part of the bare minimum.
> 
> (btw, the answer is: the use of the flag function inside the rule 
> function is not specified, thus not documented)
> 
-- 
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)

[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: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3

[Peter Hawkins]

Hi...

On Mon, Feb 9, 2009 at 1:32 AM, Romain Bardou <Romain.Bardou@lri.fr> wrote:
> The wiki:
> http://brion.inria.fr/gallium/index.php/Ocamlbuild
> should answer all questions you have to compile simple projects. In fact,
> the user manual (first link on the wiki) should answer these questions.
>
> It would really help to improve the documentation if you could explain what
> were the problems you encountered and where did you look for the
> documentation.

The documentation on linking Ocaml programs to external C libraries or
Ocaml libraries with C library dependencies is minimal at best. There
are some examples in the wiki, but they come with little explanation
and aren't adequate documentation by themselves.

Another thing that caused me frustration is that ocamlbuild doesn't
understand how to build C++ files. My ocaml programs use external C++
libraries (bindings to MiniSAT, STP, and MONA), and the build system
needs to understand how to build the C++ stub files. I hacked up a
rule for building .cc files, but I think this is a common use case so
one needs to be built in.

Cheers,
Peter

Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3

[Mikkel Fahnøe Jørgensen]

2009/2/9 Peter Hawkins <hawkinsp@cs.stanford.edu>:
> Hi...
>
> On Mon, Feb 9, 2009 at 1:32 AM, Romain Bardou <Romain.Bardou@lri.fr> wrote:
>> The wiki:

> The documentation on linking Ocaml programs to external C libraries or
> Ocaml libraries with C library dependencies is minimal at best. There
> are some examples in the wiki, but they come with little explanation
> and aren't adequate documentation by themselves.
>

Documention issues aside, external C linking is not at all well
supported in ocamlbuild, for one thing there is no dependency support
and C header files do not automatically get added to the build dir,
and there isn't any good support for different C tool chains - that is
why I wrote ocamlbuild-ctools. More generally ocamlbuild does no very
well support building C code without ocaml either. I hope some of this
could eventually be integrated with ocamlbuild itself or that
ocamlbuild adds module support so it becomes easier to include in ones
own build.

Regarding what is missing in ocaml build environment ... yes
documentation. But there are other issues. Usually these get answered
with - but you just have do ... like install unix tools, or use
ocamlfind with this argument, or something. Yes, it is possible. But
it is much more involved that in scripting languages. I don't have all
the answers. But for example: why is there a need for ocamlfind in the
first place. Couldn't the ocaml compiler tools do the same thing with
a lib path argument, a default location and an environment varible? Or
since it is more or less needed, why isn't it part of the default
installation of ocaml? Why is the path information mixed ocaml/C
libaries so hardcoded that I must copy C libraries to a new path
before creating an ocaml library so it doesn't hardcode some strange
path that makes the library uninstallable. Why is it so difficult to
create libraries with pack arguments - granted ocamlbuild solves many
of these issues. Why can't the compiler figure out the proper link
order of arguments - again ocamlbuild helps. Why can't a name a camlp4
syntax at the top of a file so other users have a chance to figure out
how to read the reminder of the file. Why do I have to link with a
library in the first place when I already referenced the library in
the source code. Again ocamlbuild solves  some of these issues.

There are probably many good reasons and priorities behind this, but
the end result is a more difficult build environment than your typical
scripting language, or even C/C++.

Mikkel

Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3

[Mikkel Fahnøe Jørgensen]

2009/2/9 Mikkel Fahnøe Jørgensen <mikkel@dvide.com>:
> Regarding what is missing in ocaml build environment ...

I should add that one reason I chose to work with ocaml is also
because of its build environment. I links very efficiently with C code
and do link with object files. So it is not a self-contained
environment that would be difficult to use for systems programming.
This is very powerful. But it does have implications as I mentioned
before.

I'd also like to mention that I find ocamlbuild a very good tool - not
only for ocaml, but for building anything. That fact that you can
dynamically include dependency generators in the build based on
generated build products is outstanding. I hope it will get to used
more because many of the platform dependent unix tools used in
makefiles could be done in ocaml code instead in a portable way.

So I am just mentioning where I see areas for improvement, it is not
like I think everything is just bad.

Mikkel

Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3

[Stefano Zacchiroli]

On Mon, Feb 09, 2009 at 11:45:48PM +0100, Mikkel Fahnøe Jørgensen wrote:
> Documention issues aside, external C linking is not at all well
> supported in ocamlbuild, for one thing there is no dependency
> support and C header files do not automatically get added to the
> build dir, and there isn't any good support for different C tool
> chains - that is why I wrote ocamlbuild-ctools. More generally
> ocamlbuild does no very well support building C code without ocaml
> either.

Have you reported all this in the Caml bug tracking system? The only
bug ocamlbuild-related which mentions C compiling [1] is way more
specific than this.  Please do the effort, seems you seem to have
incurred in the problem, of filing the problems you find, maybe with
workarounds :-)

Cheers.

[1] http://caml.inria.fr/mantis/view.php?id=4421

-- 
Stefano Zacchiroli -o- PhD in Computer Science \ PostDoc @ Univ. Paris 7
zack@{upsilon.cc,pps.jussieu.fr,debian.org} -<>- http://upsilon.cc/zack/
Dietro un grande uomo c'è ..|  .  |. Et ne m'en veux pas si je te tutoie
sempre uno zaino ...........| ..: |.... Je dis tu à tous ceux que j'aime

Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3

[Mikkel Fahnøe Jørgensen]

2009/2/10 Stefano Zacchiroli <zack@upsilon.cc>:
> Have you reported all this in the Caml bug tracking system? The only
> bug ocamlbuild-related which mentions C compiling [1] is way more
> specific than this.  Please do the effort, seems you seem to have
> incurred in the problem, of filing the problems you find, maybe with
> workarounds :-)

I don't think this is a bug reporting issue. I was concerned with new
functionality not incorrect behaviour. There is, for example, no C
dependency scanner in ocamlbuild (last I looked). I could of course
request features in a bug report, but I thought I'd rather write the
code.

There has been a few workarounds because ocamlbuild does not have all
the hooks (such as supporting exclusive tags (like don't add
optimization to debug builds)), but ocamlbuild is surprisingly
extensible via the plugin interface.

I have been in contact with one of the ocamlbuild developers and got a
lot of great help and suggestions, otherwise I could not have written
the plugin.

Mikkel

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

Re: [Caml-list] Re: ocamlbuild documentation

[Matthieu Dubuget]

Jan Kybic a écrit :
> 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.
>   

Not sure about the first answer. Anyway, I will be corrected if I'm
wrong ;-)

your _tags file is too restrictive. Your pkg_… are taken into account
only for
.ml and .mli files.
At link stage, there are not used
What if you add "<matvflss.nativ> or" on the first line?
I think the findlib packages are simply not used during the final step?
> 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?
>   
caml-type.el which is used by emacs, is aware of this.

Re: [Caml-list] Re: ocamlbuild documentation

[Matthieu Dubuget]

Jan Kybic a écrit :
>> your _tags file is too restrictive. Your pkg_… are taken into account
>> only for
>> .ml and .mli files.
>> At link stage, there are not used
>> What if you add "<matvflss.nativ> or" on the first line?
>>     
>
> Yes, it works! 
>   
Nice.
>   
>> I think the findlib packages are simply not used during the final step?
>>     
>>> 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?
>>>   
>>>       
>> caml-type.el which is used by emacs, is aware of this.
>>     
>
> Not the tuareg mode version 1.45.6 which I am using. But it is
> probably just a matter of upgrading, I will try that later.
>   

caml-type.el comes from ocaml distrib. And tuareg uses it.
I have the same version, and it works.

when I give -cflag -dtypes to ocamlbuild, of course.

Salutations

Matt

Re: [Caml-list] Re: ocamlbuild documentation

[Daniel Bünzli]

Le 10 févr. 09 à 16:50, Matthieu Dubuget a écrit :

> when I give -cflag -dtypes to ocamlbuild, of course.

If you are using 3.11 -dtypes is deprectated, use -annot instead.

Instead of passing it to ocamlbuild on invocation you can write the  
following in _tags

<**/*.ml> : annot

Best,

Daniel

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

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