OSR » META files for packages containing syntax extensions

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