<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"/usr/share/sgml/docbook/dtd/xml/4.4/docbookx.dtd" [
<!ENTITY % included SYSTEM "included.ent">
%included;
]>
<chapter id="libpack">
  <title>Packaging OCaml libraries</title>

  <section>
    <title>Creating packages for OCaml libraries</title>

    <para>
      A package which provides an OCaml library called <filename>xxx</filename> should be split as follows:

      <itemizedlist>
        <listitem>
          <para>
            For libraries which are not purely programmed in OCaml (e.g. C
            bindings), <filename>libxxx-ocaml</filename> should provide the
            shared library stubs (<filename>dll*.so</filename>), and all other
            stuff needed to run a bytecode executable that links into this
            library. It should depend on &ocaml-base-vpkg; as well as any other library needed. The
            <emphasis>versioned</emphasis> dependency on &ocaml-base-pkg; is
            important since libraries are binary incompatible between releases
            of OCaml.  </para> <para> <filename>libxxx-ocaml</filename>
            packages should be in <code>Section: ocaml</code>.
          </para>
          <para>
            If the library provides native plugins (<filename>*.cmxs</filename>)
            or is meant to be dynamically loaded using the <code>Dynlink</code>
            library, those plugins, relevant <filename>*.cmo</filename> or
            <filename>*.cma</filename> files, and the <filename>META</filename>
            file referencing them should also be provided by this runtime package.
          </para>
        </listitem>
        <listitem>
          <para>
            <filename>libxxx-ocaml-dev</filename> should provide the rest of
            the library package, in fact anything needed to develop programs
            using the library. If the library uses other libraries or C
            libraries then this package should depend on them.  </para>
          <para>

          <filename>libxxx-ocaml-dev</filename> should depend on its
          companion <filename>libxxx-ocaml</filename> package (if any).
          The reason is that at compile time the &ocaml-name; compiler
          will try to load the shared library stubs, aborting the
          compilation in case of failure. Hence the development package
          is useless if the corresponding stub package is missing. To
          ensure compatibility the dependency among the two packages
          should be strictly versioned. In order for the resulting
          packages to be <ulink
            url="http://wiki.debian.org/binNMU">binNMU safe</ulink> this
          requirement states that the dependency should make use of a
          <code>${binary:Version}</code> substitution variable.

          <example>
            <title>Dependency from a -dev package to its companion shared
            library stub package (if any), from the
            <application>pcre-ocaml</application> package</title>
            <programlisting>
  Package: libpcre-ocaml
  Architecture: any
  Section: ocaml
  Depends: &ocaml-base-vpkg;, ${shlibs:Depends}, ${misc:Depends}
  ...

  Package: libpcre-ocaml-dev
  Architecture: any
  Section: ocaml
  Depends: &ocaml-vpkg;, libpcre3-dev (>= 4.5), <emphasis>libpcre-ocaml (= ${binary:Version})</emphasis>, ${misc:Depends}
  Suggests: ocaml-findlib (>= 1.1)
  ...
            </programlisting>
          </example>

          </para>
          <para>
          <filename>libxxx-ocaml-dev</filename> packages should be in <code>Section: ocaml</code>
          </para>
          <para>
          All &ocaml-name; bytecode libraries
          (<filename>*.cma</filename>) and bytecode object files
          (<filename>*.cmo</filename>) should be compiled for
          debugging, i.e. they should be compiled passing the
          <option>-g</option> option to <command>ocamlc</command> (or
          <command>ocamlc.opt</command>).
          </para>
        </listitem>
      </itemizedlist>
    </para>

    <para>
      Optionally, two other packages may be created:
      <itemizedlist>
        <listitem>
          <para>
            <filename>libxxx-ocaml-bin</filename> may include binaries provided
            by the library source package if they are numerous. This package
            should conform with the same regulations as other packages
            providing ocaml programs. It is only needed to split off this
            package if there is a significant number of programs included in
            the library, if not, the programs should go into
            <filename>libxxx-ocaml-dev</filename>.  </para>
        </listitem>
        <listitem>
          <para>
            <filename>libxxx-ocaml-doc</filename> may include any kind of
            documentation provided by the library source package or as separate
            documentation. Again, if there is only little documentation, they
            should go with the <filename>-dev</filename> package.  </para>
        </listitem>
      </itemizedlist>
    </para>

    <para>
    It is recommended that libraries use the <option>-pack</option> option to
    pack all the modules provided by the library into one module.  We don't
    think upstream libraries will be moving to this scheme anytime soon (unless
    we actively lobby for it) so this is just a recommendation for now.
    </para>

    <para>
    It is recommended that each library package ships a
    <filename>META</filename> file in order to make the library usable via
    <filename>ocamlfind</filename> (see the Debian package
    <filename>ocaml-findlib</filename>). See <xref linkend="META" /> for more
    information on this.</para>
  </section>

  <section id="library-path">
    <title>Paths for libraries</title>

    <para>
      Libraries should be installed in <filename>&ocaml-sys-dir;/</filename> or
      in a subdirectory of this directory. This includes in particular bytecode
      libraries (<filename>*.cma</filename>), native libraries
      (<filename>*.cmxa, *.a</filename>), native plugins (<filename>*.cmxs</filename>), bytecode object files
      (<filename>*.cmo</filename>), native object files
      (<filename>*.cmx, *.o</filename>), static libraries (<filename>*.a</filename>)
      and <filename>META</filename> files. The only exception to this rule is
      for shared libraries (<filename>dll*.so</filename>) which should be
      installed in <filename>&ocaml-sys-dir;/stublibs</filename>, as can it be
      seen in the <filename>&ocaml-sys-dir;/ld.conf</filename> file.  </para>

    <para>
      If upstream developers already use a subdirectory of the OCaml standard
      library path then this path should be preserved in the Debian package but
      made relative to the standard library path of OCaml. Before using the
      provided subdirectory, packagers should obviously check if there is no
      subdirectory name clash with another OCaml library.  </para>

    <para>
      If upstream developers do not use this scheme then packagers are
      encouraged not to install this library in the standard library
      directory. They should create at least a subdirectory per source
      package (in order to avoid name clashes). Packagers should also
      consider to do a larger separation by creating a subdirectory
      per binary package (in order to avoid META name clash). A
      suggested rule to choose the name for this subdirectory is to use
      either the package name provided by the META of the upstream, or
      the name of the library itself.  </para>
  </section>


  <section id="META">
    <title>Providing <filename>META</filename> files</title>

    <para>
      The <filename>ocaml-findlib</filename> provides a tool (called
      <filename>ocamlfind</filename>) to handle OCaml libraries and store
      information about libraries dependencies, compiler flags, linking
      options, etc. Meta informations regarding a library are contained in
      files (usually one for each library), named <filename>META</filename>
      files, contained in the library directory. The distribution of
      <filename>META</filename> files is the best way to make more easy to use
      the Debian-specific organization of libraries. Packages distributing
      <filename>META</filename> files should suggest the use of &ocamlfind;,
      that is have a <varname>Suggest: ocaml-findlib</varname>.
    </para>

    <para>
      By default, &ocamlfind; will look for <filename>META</filename> in this order:
      <itemizedlist>
        <listitem><para><filename>&ocaml-metas-dir;/</filename></para></listitem>
        <listitem><para><filename>&ocaml-sys-dir;/package/</filename></para></listitem>
      </itemizedlist>
    </para>

    <para>
      If a library package creates its own subdirectory
      <filename>&ocaml-sys-dir;/package/</filename> then the META file
      should be stored in that directory.
    </para>

    <para>
      The naming scheme of <filename>META</filename> is pretty simple.
      <itemizedlist>
        <listitem>
          <para>
            If the <filename>META</filename> file is placed in the subdirectory
            of the package then it should be called <filename>META</filename>.
          </para>
        </listitem>
        <listitem>
          <para>
          If the <filename>META</filename> file is placed in
          <filename>&ocaml-metas-dir;/</filename> then it should be called
          <filename>META.packagename</filename>, where
          <filename>packagename</filename> is the name of the subdirectory
          where the library is stored.  </para>
        </listitem>
      </itemizedlist>
    </para>

    <para>
      For example, the <filename>META</filename> file for the lablgtk library
      is named <filename>META</filename> and has path
      <filename>&ocaml-sys-dir;/lablgtk/META</filename>, where
      <filename>&ocaml-sys-dir;</filename> is the main OCaml installation
      directory and <filename>lablgtk</filename> is the lablgtk library
      directory.  </para>

    <para>
      If upstream doesn't provide a <filename>META</filename> then
      packagers are encouraged to create one. In this case, the META
      file should contain a comment like this, so that developers will
      know that they shouldn't count on the availability of a META file
      on non-Debian machines:
      <programlisting>
	# This META file is delivered by the Debian distribution.
      </programlisting>
      Furthermore, the <filename>META</filename> file should be sent to the
      upstream authors in order to have it included in future versions
      of the upstream source. For more information about
      <filename>META</filename> files see the <ulink
      url="http://www.ocaml-programming.de/packages/documentation/findlib/">Findlib
      manual</ulink>, at the several META files provided by other
      packages (e.g. <filename>lablgtk</filename>,
      <filename>pxp</filename>, <filename>pcre</filename>,
      <filename>netstring</filename>, <filename>lablgl</filename>,
      ...) or ask on the debian-ocaml-maint mailing list for help.
      </para>
  </section>

  <!--
  <section id="ocamldoc-base-path">
    <title>&ocamldoc; specific generated documentation</title>

    <para>
      Even if this way of producing documentation is not mandatory, packagers are
      encouraged to use it, in order to ship lighter documentation, which could
      be processed by &ocaml-name; tools.
    </para>

    <para>
      By default, &ocamldoc-base; will look for <filename>*.odoc</filename> in this order :
      <variablelist>
        <varlistentry>
          <term><varname>local</varname></term>
          <listitem><para><filename>/usr/local/share/ocamldoc/&ocaml-version;/</filename></para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>core</varname></term>
          <listitem><para><filename>/usr/share/ocamldoc/&ocaml-version;/</filename></para></listitem>
        </varlistentry>
      </variablelist>
    </para>

    <para>
      As for library, the naming scheme of the <filename>*.odoc</filename> should be 
      at least the name of the source package from which the documentation was
      generated. If a source package is split in many binary package and the
      documentation comes only in one <filename>*.odoc</filename>, packagers are 
      encouraged to create a separate package and to <varname>Suggest:</varname> it
      in each binary package which he described. If this could not be met, it is at 
      least a good practice to <varname>Suggest:</varname> the package containing
      the documentation.
      The packager should consider to ship one <filename>*.odoc</filename> per 
      library package.
    </para>

    <para>
      By doing this, &ocaml-force; is trying to build a clear way of distributing
      documentation. It should help user to find and exploit the documentation 
      coming from the source. Generating &ocamldoc; documentation is not so hard,
      and should take a one line call. Commenting the code in order to generate
      fully functional documentation is however an upstream task. Packager are encouraged
      to patch <filename>Makefile</filename> in order to have a target 
      <varname>odoc</varname>, generating this documentation and to contact upstream
      author to have a well commented source.
    </para>
  </section>
  -->

  <section id="camlp4-path">
  <title>&camlp4;/&camlp5;</title>

    <para> Actually, &camlp4; extensions should be processed just like standard
    OCaml libraries. In particular, they should provide a META file.
    The syntax extension should be contained in a <varname>syntax</varname> sub
    package.
    </para>

    <para>
    The naming convention of the package is to use the same naming as with
    standard package, replacing <varname>-ocaml-</varname> by the syntax
    extension name, <varname>-camlp4-</varname>. 
    </para>

    <para>
    If a package contains at the same time syntax extension and libraries then it
    is up to the maintainer to choose the most relevant name for the package.
    Whatever the name chosen for the package, the other name should be a
    <varname>Provide</varname> of the package.
    </para>

    <para>
    For example, consider the package <application>sexplib310</application>.
    It provides a syntax extension and a library, which is the runtime support  
    of the additional function generated by the syntax extension. Since the most
    common use of <application>sexplib310</application> is through its syntax 
    extension, the package is name
    <application>libsexplib-camlp4-dev</application> and it also provide
    <application>libsexplib-ocaml-dev</application>.  
    </para>

    <para>
    &camlp5; is an alternate pretty-printer and preprocessor for OCaml
    (which is compatible with pre-3.10.0 version). Syntax extension are
    handled through exactly the same scheme as for &camlp4; except that
    package name use <varname>-camlp5-</varname> rather than
    <varname>-camlp4-</varname>.
  </para>
  </section>

  <section id="documentation">
    <title>Documentation</title>
    <para>
      The documentation is a joint effort of  &ocaml-force; and upstream. 
      There are many ways to have documentation:
      <itemizedlist>
        <listitem><para>header files (<filename>*.mli</filename>),</para></listitem>
        <listitem><para>source files (<filename>*.ml</filename>),</para></listitem>
        <listitem><para>specific documentation provided by the upstream,</para></listitem>
        <listitem><para>OCamldoc generated documentation.</para></listitem>
      </itemizedlist>
    </para>

    <para>
      This documentation should be browsable by different means, from the most
      simple to the most complex one. At least, they should all be readable with
      a simple text editor. Specific and &ocamldoc; generated documentations
      should be provided in HTML format.
    </para>

    <para>
      You can generate &ocamldoc;-specific documentation by using
      the <option>-dump</option> option of this command. By using this, you dump the
      intermediate representation of the document that will be generated by ocamldoc.
      This can be used to generate HTML documentation and manpages, by reloading this
      file (using <option>-load</option>).
    </para>
  </section>
</chapter>