OSR: META files for packages containing syntax extensions

[Dario Teixeira <darioteixeira@yahoo.com>]

================================================================
   OSR: META files for packages containing syntax extensions
================================================================

1. OBJECTIVE:
=============

This recommendation aims to ensure that the META files accompanying
Ocaml packages implementing some Camlp4-based syntax extension are
Findlib-compliant.


2. RATIONALE:
=============

Whether by invoking ocamlfind directly or by using the generic Ocamlbuild
plugin [1], the use of syntax extensions in Ocaml can be significantly
simplified if the package defining the extension includes a META file
that is Findlib+Camlp4 aware.  Though the Findlib manual describes
the Camlp4 support as being experimental [2], it works well enough in
practice to warrant a more widespread use.  Despite this fact, not all
packages available via GODI are presently compliant.


3. WHOM IT CONCERNS:
====================

On the one hand, package maintainers, who should make sure the packages
under their wing follow the guidelines in this OSR.  On the other hand,
the users themselves: either by using the Ocamlbuild plugin [1], or
by manually using the findlib facilities for syntax extensions in their
makefiles, they can make life easier for others who wish to compile/modify
their code.


4. DESCRIPTION:
===============

The Findlib manual already contains a comprehensive description [2].
The material contained here merely illustrates how the META file
should be written for a number of common scenarios.


4.1. Package that IS A syntax extension:
========================================

Suppose we have a syntax extension "pa_listcomp" for list comprehensions.
This extension does not rely on any other libraries, and is meant to be
packaged individually.  Here's how its META file should look like:

-----------------------------------------------
name "pa_listcomp"
requires = "camlp4"
version = "1.0"
description = "Syntax extension for list comprehensions"
archive(syntax,preprocessor) = "pa_listcomp.cmo"
archive(syntax,toploop) = "pa_listcomp.cmo"
-----------------------------------------------

Another common occurrence is for the syntax extension to rely on a runtime
module or library included with the package.  Suppose pa_listcomp relied
on a "runtime_listcomp" module; here's how its META file should look
like instead:

-----------------------------------------------
name "pa_listcomp"
requires = "camlp4"
version = "1.0"
description = "Syntax extension for list comprehensions"
archive(syntax,preprocessor) = "pa_listcomp.cmo"
archive(syntax,toploop) = "pa_listcomp.cmo runtime_listcomp.cmo"
archive(syntax,byte) = "runtime_listcomp.cmo"
archive(syntax,native) = "runtime_listcomp.cmx"
-----------------------------------------------

Topic for discussion: for the sake of standardisation, it would be
nice if all packages of this type were to share a common prefix.
The most obvious candidate is "pa_".


4.2. Package with optional syntax extension:
============================================

A good example is PG'OCaml.  Users of this library can link against the
"pgocaml" package if they only intend to use the low-level functions.
However, there is also an optional syntax extension that enables the
embedding of SQL statements.  This syntax extension is enabled by using
the "pgocaml.statements" package (note that "statements" is defined as
a subpackage of "pgocaml").  Here's the current META file:

-----------------------------------------------
name="pgocaml"
version="1.1"
description="PG'OCaml is a set of OCaml bindings for the PostgreSQL database."
requires="unix,extlib,csv,pcre,calendar"
archive(byte)="pgocaml.cma"
archive(native)="pgocaml.cmxa"

package "statements" (
  requires = "pgocaml,camlp4"
  version = "1.1"
  description = "Syntax extension: PostgreSQL statements checked at
compile-time"
  archive(syntax,preprocessor) = "pa_pgsql.cmo"
  archive(syntax,toploop) = "pa_pgsql.cmo"
  )
-----------------------------------------------

Topic for discussion: without prejudice for those cases where an alternative
name may be far more suitable, it would be nice if packages of this type
containing a single syntax extension were to agree on a common name for the
subpackage defining that extension.  Some possibilities are "extension",
"pa", "pp", etc.


4.3. Package that is a container for several syntax extensions:
===============================================================

I would place P4ck in this category, though it is presently not available
via GODI, and I don't know if its author would like to see it added as
a single godi-p4ck package or if split into individual packages.

Suppose we have a dummy package "foobar", which is simply a container for two
independent syntax extensions, "pa_openin" and "pa_memoization".  Users can
refer to each extension as "foobar.pa_openin" and "foobar.pa_memoization".
Here's how the META file for foobar should look like:

-----------------------------------------------
package "pa_openin" (
  requires = "camlp4"
  version = "1.0"
  description = "Open_in syntax extension"
  archive(syntax,preprocessor) = "pa_openin.cmo"
  archive(syntax,toploop) = "pa_openin.cmo"
  )

package "pa_memoization" (
  requires = "camlp4"
  version = "1.0"
  description = "Memoization syntax extension"
  archive(syntax,preprocessor) = "pa_memoization.cmo"
  archive(syntax,toploop) = "pa_memoization.cmo"
  )
-----------------------------------------------

Topic for discussion: since each syntax extension is fairly autonomous
and has the potential to become an independent package,  I reckon its
name should follow the same conventions that are eventually agreed upon
for section 4.1.


REFERENCES:
===========

[1] Ocamlbuild Wiki - "Using ocamlfind with ocamlbuild":
http://brion.inria.fr/gallium/index.php/Using_ocamlfind_with_ocamlbuild

[2] The findlib User's Guide - "Does Findlib support camlp4?":
http://www.ocaml-programming.de/packages/documentation/findlib/guide-html/x412.html






      ___________________________________________________________ 
Rise to the challenge for Sport Relief with Yahoo! For Good  

http://uk.promotions.yahoo.com/forgood/