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

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

[Kenneth Knowles]

OCamlConf : A simple OCaml build tool
-------------------------------------

   OCamlConf is an O'Caml build tool that resembles GNU autoconf to the user. It
provides many useful functions for building your O'Caml project from a minimal
amount of specification.

See the homepage at http://kenn.frap.net/ocamlconf/ for more details

--------------------
New in this version:

*  No longer generates two files, "configure_out.ml" and "configure." The
   configure script is a hybrid shell script / ml program that contains
   everything it needs to run, provided they have a bourne shell, sed, and ocaml
   installed

*  Renamed "MakeMake" to "AutoMake" to indicate that it is a super-high-level
   wrapper.

*  Factored out MakeMake into several modules, allowed finer control of the build

*  Bugfixes in mixed C/O'Caml libraries, which are certainly the toughest to
   build right.

*  Dramatically improved documentation (if I do say so myself!)

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

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

[Kenneth Knowles]

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

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

[Kenneth Knowles]

On Wed, May 12, 2004 at 02:20:20PM -0600, William D. Neumann wrote:
> This is really, I suppose, the heart of my complaint.  It seems that a
> number of OCaml developers are relying on ocamldoc as their primary
> documentation method.  While this may work more-or-less well for a library
> like mlgmp or similar, it is woefully inadequate for documenting anything
> more substantial (e.g. applications).

I basically think of OCamlConf as a library, but agree that ocamldoc output is
not appropriate for applications.  Every time I sit down to write a user's
manual for ocamlconf (It is on the gameplan!) I end up re-hashing the inline
comments almost word-for-word.  I'm not sure the best way to write a tutorial
that is heavily hyperlinked into the code, so it just gives a friendly front-end
to the API.  I'll take a look at ocamlweb; I'm curious about literate programming
but usually find that the ordering necessary in prose is inconvenient for code.

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