Re: OSR: META files for packages containing syntax extensions

[Sylvain Le Gall <sylvain@le-gall.net>]

Hello,

On 13-03-2008, Dario Teixeira <darioteixeira@yahoo.com> wrote:
>================================================================
>    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.
>
>

Very good initiative: simple, efficient and first good step for a
standardization process ;-)


[...]

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

4.3 and 4.2 should be merged. 

All syntax extension should be contained in a package "statements" (or
whatever other name is chosen). If there is only 1 syntax extension, the
package "statements" is directly the syntax extension. If there is
several extension, each one get its own package with a name related to
its function.

For p4ck, here is the META is propose:
name = "p4ck"
version="0.0.0"
description="Various syntax extension"

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

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

  requires = "p4ck.statements.openin,p4ck.statements.memoization"
)

Which gives "ocamlfind -list":
p4ck                (version: 0.0.0)
p4ck.statements     (version: n/a)
p4ck.statements.memoization (version: 1.0)
p4ck.statements.openin (version: 1.0)

The "statements" package should represent all the extension contained in
it.

In this case:
$ ocamlfind -query -a-format p4ck.statements -r -predicates "syntax,toploop"
pa_openin.cmo
pa_memoization.cmo

$ ocamlfind -query -a-format p4ck.statements.openin -r -predicates "syntax,toploop"
pa_openin.cmo

This also simplifies migration from 1 to many syntax extension in the same
package, because "statements" package will still contains all the former
syntax extension. However, this is not a good solution for many to 1
syntax extension (you will still have to define all sub packages just
requiring the "statements" package).

Regards,
Sylvain Le Gall