Re: [Caml-list] OSR: META files for packages containing syntax extensions (take 2)

[Dario Teixeira <darioteixeira@yahoo.com>]

Hi,

As promised, here's version 2.0 of the OSR.  Please make your voice
be heard concerning bugs/suggestions/criticisms/etc.  If everybody
is happy with it, it will be placed in the Wiki.

Best regards,
Dario Teixeira


================================================================
   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.  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 reference concerning
Findlib's support for Camlp4 syntax extensions [2].  The material
contained here merely illustrates how the META file should be written for
a number of common scenarios.  The reader will note that the goal has been
to unify as much as possible the conventions used, even if at the expense
of always requiring the use of subpackages.  In particular, we always
mandate a subpackage called "syntax" to hold the syntax extension itself.


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

Suppose we have a syntax extension "listcomp" for list comprehensions.
This extension does not rely on any other libraries, and is meant to be
packaged individually.  However, due to the requirement that all syntax
extension packages are named "syntax", it must be defined in a subpackage
and placed inside a container package.  Here's how its META file should
look like:

-----------------------------------------------
name "listcomp"
version = "1.0"
description = "Container for list comprehensions"

package "syntax"
   (
   version = "1.0"
   description = "Syntax extension for list comprehensions"
   requires = "camlp4"
   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 listcomp
relied on a "runtime_listcomp" module; here's how its META file should
look like instead:

-----------------------------------------------
name "listcomp"
version = "1.0"
description = "Runtime support for list comprehensions"
archive(byte)="runtime_listcomp.cma"
archive(native)="runtime_listcomp.cmxa"

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


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 within Ocaml code.  This syntax extension
is enabled by using the "pgocaml.syntax" subpackage.  Note that this
case is essentially identical to the previously shown syntax extension
relying on a runtime library.  Here's the proposed 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 "syntax"
   (
   version = "1.1"
   description = "Syntax extension: PostgreSQL statements checked at
compile-time"
   requires = "pgocaml,camlp4"
   archive(syntax,preprocessor) = "pa_pgsql.cmo"
   archive(syntax,toploop) = "pa_pgsql.cmo"
   )
-----------------------------------------------


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, "openin" and "memoization".
Users can refer to each extension as "foobar.openin.syntax" and
"foobar.memoization.syntax".  Moreover, and if applicable, the user may
wish to use all syntax extensions defined in package foobar.  In this
case, "foobar.syntax" should load them all.  Here's how the META file
for foobar should look like:

-----------------------------------------------
name "foobar"
version = "1.0"
description = "Collection of useful syntax extensions"

package "openin"
   (
   version = "1.0"
   description = "Container for openin syntax extension"
   package "syntax"
      (
      version = "1.0"
      requires = "camlp4"
      description = "Syntax extension for openin"
      archive(syntax,preprocessor) = "pa_openin.cmo"
      archive(syntax,toploop) = "pa_openin.cmo"
      )
   )

package "memoization"
   (
   version = "1.0"
   description = "Container for memoization syntax extension"
   package "syntax"
      (
      version = "1.0"
      requires = "camlp4"
      description = "Syntax extension for memoization"
      archive(syntax,preprocessor) = "pa_memoization.cmo"
      archive(syntax,toploop) = "pa_memoization.cmo"
      )
   )

package "syntax"
   (
   version = "1.0"
   requires = "foobar.openin.syntax,foobar.memoization.syntax"
   description = "All syntax extensions contained by foobar"
   )
-----------------------------------------------


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/