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.1 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 mail2-relais-roc.national.inria.fr (mail2-relais-roc.national.inria.fr [192.134.164.83]) by yquem.inria.fr (Postfix) with ESMTP id 3290EBB84 for ; Mon, 9 Feb 2009 19:37:59 +0100 (CET) X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AsQCANcGkEnCpx6wi2dsb2JhbACUOQEBAQoLChi8DIQaBg X-IronPort-AV: E=Sophos;i="4.37,406,1231110000"; d="scan'208";a="20859505" Received: from smtpmin.univ-orleans.fr (HELO min.univ-orleans.fr) ([194.167.30.176]) by mail2-smtp-roc.national.inria.fr with ESMTP; 09 Feb 2009 19:37:59 +0100 Received: from smtps.univ-orleans.fr (localhost [127.0.0.1]) by min.univ-orleans.fr (Postfix) with ESMTP id EEDA812B4F8; Mon, 9 Feb 2009 19:37:58 +0100 (CET) Received: from [192.168.0.1] (lau18-1-82-246-197-195.fbx.proxad.net [82.246.197.195]) by smtps.univ-orleans.fr (Postfix) with ESMTP id 094D436E60; Mon, 9 Feb 2009 19:38:01 +0100 (CET) Subject: Re: ocamlbuild documentation (was Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3) From: David Teller To: Romain Bardou Cc: OCaml List In-Reply-To: <49902E11.2010101@lri.fr> References: <1233936696.6216.65.camel@Blefuscu> <200902071458.45000.jon@ffconsultancy.com> <498FF839.6090901@lri.fr> <499018C2.9080007@lri.fr> <499026F9.3030708@lri.fr> <997E6911-3D37-4FAA-A958-757AD21A9F4D@erratique.ch> <49902E11.2010101@lri.fr> Content-Type: text/plain; charset=utf-8 Date: Mon, 09 Feb 2009 19:38:09 +0100 Message-Id: <1234204689.6659.29.camel@Blefuscu> Mime-Version: 1.0 X-Mailer: Evolution 2.12.1 Content-Transfer-Encoding: 8bit X-Spam: no; 0.00; ocaml:01 univ-orleans:01 trivial:01 wiki:01 uncommented:01 summarize:01 wiki:01 ocamlfind:01 syntax:01 ocaml:01 mli:01 compilation:01 mli:01 ocamldoc:01 makefile:01 (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.