Re: [Caml-list] [ANNOUNCE] ocamlconf-0.5 release

[Kenneth Knowles <kknowles@berkeley.edu>]

On Wed, May 12, 2004 at 11:38:22AM -0600, William D. Neumann wrote:
> > *  Dramatically improved documentation (if I do say so myself!)
> 
> I really don't want this to sound rude, but... You're kidding, right?

> For example, I've looked at the included configure.ml, and both examples
> in the README

I am not kidding.  There is a lot of documentation you don't appear to have
consulted.  It resides here: http://kenn.frap.net/ocamlconf/docs.html/

It is not amazing, but much better than before.

I'm quite sold on Skaller's idea of the whole build process being a
general-purpose program, and I'm trying to supply an API that make that easier,
plus the trivial service of making a portable script out of your O'Caml
program.  Since ocamlconf is *mostly* an API, the ocamldoc output is the most
valuable reference.
 
> But figuring out exactly what would be a chore.  Hell, I'm not even sure
> why you have false after the findlib keys, and true after the path_search
> and param keys... 

Excerpt from http://kenn.frap.net/ocamlconf/docs.html/Conf.html

    val configure : (configuration_item * bool) list -> t

    Takes a configuration_item list, supplemented with a bool to say whether to show
    each item to the user, and returns the configuration that results from all the
    tests.

To further clarify, when a user types './configure --help' the boolean
determines whether they see the item so you can have behind-the-scenes work.

> And I have no clue how to tell the tool to search for a
> needed set of header files.

There are no C-oriented tests, because that is a tough problem with better
solutions than I have time for.  If your project is C-heavy, I'd recommend
either:
(1) using autoconf all the way
(2) gluing autoconf to ocamlconf - much easier than reimplementing autoconf
(3) contribute code :-)
 
I hope eventually to make it easy to glue ocamlconf and autoconf together, but I
do not intend to touch the C library/header issue.  I'm always open to concrete
suggestions and/or code.

> Do you plan on writing any documentation for this (potentially quite
> useful) tool that will allow someone who a) didn't write it, and b) isn't
> even familiar with autoconf to begin using it?

I haven't found the time to write a narrative tutorial, so until I do I have to
limit my target audience to people who are familiar with autoconf's concepts,
and/or are willing to read reference documentation.

> I realize that no one likes to write documentation,

I do like to write documentation :-) but it takes a lot of time, and so mostly I
annotate my sources so ocamldoc can do the work for me.  In addition, the API
for ocamlconf is very unstable (note the small number of releases, and low
version number), so it would be a waste of time to put together a tutorial just
to rewrite the API.

> Again, I do want to stress that I appreciate the time that you put into
> creating what I think can be a useful tool for me and the OCaml community
> in general.  But until I can actually *use* that tool, from my viewpoint,
> it may as well have never been written.

In summary:
(1) The "documentation" does not mean "the README and examples", it means the
API docs
(2) I want to write a tutorial eventually, but
(3) I don't have time
(4) The API is not stable enough to merit it
(5) OCamlConf knows how to build mixed C/O'Caml programs, but not how to search
for C libraries.

I understand your frustration, and my answer is that eventually it may be what
you want.

Kenn

-------------------
To unsubscribe, mail caml-list-request@inria.fr Archives: http://caml.inria.fr
Bug reports: http://caml.inria.fr/bin/caml-bugs FAQ: http://caml.inria.fr/FAQ/
Beginner's list: http://groups.yahoo.com/group/ocaml_beginners