From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.1.3 (2006-06-01) on yquem.inria.fr X-Spam-Level: X-Spam-Status: No, score=0.3 required=5.0 tests=AWL autolearn=disabled version=3.1.3 X-Original-To: caml-list@yquem.inria.fr Delivered-To: caml-list@yquem.inria.fr Received: from mail4-relais-sop.national.inria.fr (mail4-relais-sop.national.inria.fr [192.134.164.105]) by yquem.inria.fr (Postfix) with ESMTP id 34869BBC1 for ; Thu, 13 Mar 2008 13:40:55 +0100 (CET) X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AnQAADO+2EfOvjGroWdsb2JhbACQcwEBAQEBAQUEBgkIAReWdA X-IronPort-AV: E=Sophos;i="4.25,493,1199660400"; d="scan'208";a="23719965" Received: from web54601.mail.re2.yahoo.com ([206.190.49.171]) by mail4-smtp-sop.national.inria.fr with SMTP; 13 Mar 2008 13:40:30 +0100 Received: (qmail 76188 invoked by uid 60001); 13 Mar 2008 12:40:30 -0000 DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws; s=s1024; d=yahoo.com; h=X-YMail-OSG:Received:Date:From:Subject:To:MIME-Version:Content-Type:Content-Transfer-Encoding:Message-ID; b=t5+Yx7J9DyGMHWLunQzHyqiv0ZjIooOHi8wxsp1WOzBf6dpRY/pyOoFvhU7TZ8bnHgS8Asfo+EMauwpTP014hFB3aQDJ367azamw2Q4FWvdv4pmyzcFH3d4x6IVLbGKM330TTkxu6/8Mic6VQCdNsLG0x2qsbS1sNPbZJqDrA1Y=; X-YMail-OSG: rTllp90VM1nacM0mHzNFKqigiPsjGj2Wstoh2Z7iuuOfieiZO8XMNV9BmQKibwF20GJ9Us9JXxN08mRn2CksExK3axiXZMyigLk0h02eOuo8gkqPQrWTQCOEdLts4A-- Received: from [82.155.118.30] by web54601.mail.re2.yahoo.com via HTTP; Thu, 13 Mar 2008 12:40:30 GMT Date: Thu, 13 Mar 2008 12:40:30 +0000 (GMT) From: Dario Teixeira Subject: OSR: META files for packages containing syntax extensions To: caml-list@yquem.inria.fr MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 8bit Message-ID: <98095.73991.qm@web54601.mail.re2.yahoo.com> X-Spam: no; 0.00; syntax:01 syntax:01 ocaml:01 camlp:01 ocamlfind:01 ocaml:01 findlib:01 camlp:01 findlib:01 makefiles:01 cmo:01 toploop:01 cmo:01 runtime:01 runtime:01 ================================================================ 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/