-%.html: %.xml
- xsltproc --nonet --output $@ \
- /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/docbook.xsl \
- $^
+all: html text
-all: ocaml_packaging_policy.html
+html:
+ docbook2html ocaml_packaging_policy.xml -o packaging-policy-html
+
+text:
+ docbook2txt ocaml_packaging_policy.xml
clean:
- $(RM) ocaml_packaging_policy.html
+ $(RM) -rf packaging-policy-html ocaml_packaging_policy.txt
+
+.PHONY: html text
+<section>
+ <title>Where to find the &ocaml-force;</title>
+ <para>
+ blah
+ </para>
+</section>
-
+<section>
+ <title>Packages which can be binNMUed</title>
+ <para>
+ blah
+ </para>
+</section>
<address><email>sylvain.le-gall@polytechnique.org</email></address>
</affiliation>
</author-->
- <author>
- <organization>The Debian OCaml Task Force</organization>
- <address><email>debian-ocaml-maint@lists.debian.org</email></address>
- </author>
-
+<author>
+ <affiliation>
+ <orgname>The Debian OCaml Task Force</orgname>
+ <address><email>debian-ocaml-maint@lists.debian.org</email></address>
+ </affiliation>
+</author>
--- /dev/null
+<section>
+ <title>OCaml in Debian</title>
+ <para>
+ At the time of this writing, the latest version of OCaml in Debian is &ocaml-version;.
+ </para>
+
+ <para>
+ The <filename>ocaml</filename> package depends on all the basic packages needed to develop programs with OCaml. More specifically, the packaging of OCaml is split into smaller packages. The <filename>-nox</filename> packages contain libraries which don't need X (i.e. for the programs which don't use the <code>Graphics</code> or <code>LablTk</code> modules) in order to avoid too big dependencies for users who don't have and X server installed.
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <filename>ocaml</filename> and <filename>ocaml-nox</filename> package contain the compiler and its libraries.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>ocaml-native-compilers</filename> contains the OCaml compiler built in native mode.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>ocaml-base</filename> and <filename>ocaml-base-nox</filename> packages contain the runtime libraries needed by bytecode programs compiled with OCaml (in particular it contains the <filename>ocamlrun</filename> program).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>ocaml-interp</filename> contains the interactive command-line interpreter.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>ocaml-mode</filename> contains the OCaml emacs mode (the one provided with OCaml, not the tuareg mode).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>ocaml-source</filename> contains the sources of the OCaml compiler.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>ocaml-compiler-libs</filename> contains some internal libraries of the OCaml compiler (it is needed only in very rare cases).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Since the libraries produced by OCaml are binary incompatible when compiled with two different releases of OCaml, versionned virtual packages are provided: <filename>ocaml-&ocaml-version;</filename>, <filename>ocaml-nox-&ocaml-version;</filename>, <filename>ocaml-base-&ocaml-version;</filename>, <filename>ocaml-base-nox-&ocaml-version;</filename>.
+ </para>
+</section>
+
+<section>
+ <title>Native and bytecode programs</title>
+
+ <para>
+ The OCaml compiler can produce two kinds of executables: bytecode and native. The native executables (compiled with <filename>ocamlopt</filename>) are generally faster since they are compiled specifically for an achitecture. The bytecode executables (compiled with <filename>ocamlc</filename>) have the advantage of being portable, which means that a bytecode program can be run on any achitecture without needing to be rebuilt. It should be noted that native OCaml compilers are not provided for every achitecture. Only the following are suported: alpha, amd64, arm, i386, ia64, kfreebsd-i386, powerpc and sparc.
+ </para>
+
+ <para>
+ Package providing both native and bytecode versions of a program <filename>prog</filename> usually name them respectively <filename>prog.opt</filename> and <filename>prog.byte</filename> and provide a symbolic link <filename>prog</filename> to the best available version (generally <filename>prog.opt</filename>).
+ </para>
+
+ <para>
+ The <filename>ocaml-native-compilers</filename> package contains the OCaml compiler built in native mode (<filename>ocamlc.opt</filename> and <filename>ocamlopt.opt</filename>). Compiling with this version of the compiler is generally faster but, as explained before, the <filename>ocaml-native-compilers</filename> package is not available on every architecture. In order to build big programs and benefit from this natively built compiler, packages should depend on <filename>ocaml-best-compilers</filename> which depends on <filename>ocaml-native-compilers</filename> where available and on <filename>ocaml</filename> elsewhere.
+ </para>
+</section>
+
+<section id="files">
+ <title>Files used by the OCaml compiler</title>
+
+ <para>
+ The &ocaml-name; compiler can produce or use the following kind of files:
+ <itemizedlist>
+ <listitem><para>bytecode executables (they can be recognised since they start with <code>#!/usr/bin/ocamlrun</code>)</para></listitem>
+ <listitem><para>bytecode libraries (<filename>*.cma</filename>)</para></listitem>
+ <listitem><para>native executables (in ELF format)</para></listitem>
+ <listitem><para>native libraries (<filename>*.cmxa</filename>)</para></listitem>
+ <listitem><para>shared libraries (for C bindings) (<filename>dll*.so</filename>)</para></listitem>
+ <listitem><para>static libraries (for C bindings) (<filename>lib*.a</filename>)</para></listitem>
+ <listitem><para>bytecode object files (<filename>*.cmo</filename>)</para></listitem>
+ <listitem><para>native object files (<filename>*.cmx</filename>)</para></listitem>
+ <listitem><para>configuration files for handling libraries with <filename>ocamlfind</filename> (<filename>META</filename>)</para></listitem>
+ <listitem><para>&camlp4; related files (<filename>*.cm[ao]</filename>)</para></listitem>
+ </itemizedlist>
+ </para>
+</section>
+
+<section id="liblocal-path">
+ <title>Locally installing OCaml programs and libraries</title>
+
+ <para>
+ Installation and use of locally installed OCaml related programs is out of the scope of this document. However, in order to have it work with a standard Debian installation, you should follow some guidelines.
+ <itemizedlist>
+ <listitem>
+ <para>
+ Executable files should be installed in <filename>/usr/local/bin</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Shared libraries (for C bindings) should be installed in <filename>/usr/local/lib/ocaml/&ocaml-version;/stublibs/</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Basically, every other file should be installed in <filename>/usr/local/lib/ocaml/&ocaml-version;/</filename>. This includes in particular bytecode libraries (<filename>*.cma</filename>), native libraries (<filename>*.cmxa</filename>), bytecode object files (<filename>*.cmo</filename>), native object files (<filename>*.cmx</filename>), static libraries (<filename>*.a</filename>) and <filename>META</filename> files.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The OCaml compiler first looks for a local installation of libraries and then for libraries installed by Debian packages. This section describe the standard paths for files contained in Debian packages.
+ </para>
+
+ <para>
+ Warning: the <varname>+</varname> preceding any library in the <option>-I</option> of ocamlc or ocamlopt won't be expanded to the local standard library path. You need to specify the path entirely.
+ </para>
+</section>
- <para>
- Installation and use of locally installed &ocaml-name; is out of the
- scope of this document. However, in order to have it work with a standard
- &ocaml-name; &debian-name; install, you should follow some guideline.
- </para>
-
- <section id="liblocal-path">
- <title>Path of localy installed component</title>
-
- <para>Warning : the <varname>+</varname> preceding any library
- in <option>-I</option> of &ocamlc;, &ocamlopt; wont be expanded
- to the local standard library path. You need to specify this
- path entirely.
- </para>
-
- <para>You user this path to install local library and executable :
- <variablelist>
- <varlistentry>
- <term>bytecoded executable</term>
- <listitem><filename>/usr/local/bin/</filename></listitem>
- <listitem><filename>/usr/local/sbin/</filename></listitem>
- </varlistentry>
- <varlistentry>
- <term>bytecoded library ( <filename>*.cma</filename> )</term>
- <listitem><filename>/usr/local/lib/ocaml/&ocaml-version;/</filename></listitem>
- </varlistentry>
- <varlistentry>
- <term>native executable</term>
- <listitem><filename>/usr/local/bin/</filename></listitem>
- <listitem><filename>/usr/local/sbin/</filename></listitem>
- </varlistentry>
- <varlistentry>
- <term>native library ( <filename>*.cmxa</filename> )</term>
- </varlistentry>
- <varlistentry>
- <term>shared library ( for C-binding ) ( <filename>dll*.so</filename> )</term>
- <listitem>/usr/local/lib/ocaml/&ocaml-version;/stublibs/</listitem>
- </varlistentry>
- <varlistentry>
- <term>static library ( for C-binding ) ( <filename>lib*.a</filename> )</term>
- <listitem><filename>/usr/local/lib/ocaml/&ocaml-version;/</filename></listitem>
- </varlistentry>
- <varlistentry>
- <term>bytecoded object ( <filename>*.cmo</filename> )</term>
- <listitem><filename>/usr/local/lib/ocaml/&ocaml-version;/</filename></listitem>
- </varlistentry>
- <varlistentry>
- <term>native object ( <filename>*.cmx</filename> )</term>
- <listitem><filename>/usr/local/lib/ocaml/&ocaml-version;/</filename></listitem>
- </varlistentry>
- <varlistentry>
- <term>configuration file for handling library ( <filename>META</filename> )</term>
- <listitem><filename>/usr/local/lib/ocaml/&ocaml-version;/ and subdirectory</filename>
- </listitem>
- <listitem><filename>/usr/local/lib/ocaml/&ocaml-version;/META</filename></listitem>
- </varlistentry>
- <varlistentry>
- <term>&ocamldoc; generated documentation ( <filename>*.odoc</filename> )</term>
- <listitem><filename>/usr/local/share/ocamldoc-base</filename></listitem>
- </varlistentry>
- <varlistentry>
- <term>&camlp4; related files ( <filename>*.cm[ao]</filename> )</term>
- <listitem><filename>/usr/local/lib/ocaml/&ocaml-version;/</filename> and
- <filename>subdirectory</filename></listitem>
- </varlistentry>
- </variablelist>
- </para>
-
-
- </section>
- <section id="libpack-camlp4">
- <title>Camlp4 files</title>
- </section>
+<section id="library-path">
+ <title>Paths for libraries</title>
+
+ <para>
+ Libraries should be installed in <filename>/usr/local/lib/ocaml/&ocaml-version;/</filename> or in a subdirectory of this directory. This includes in particular bytecode libraries (<filename>*.cma</filename>), native libraries (<filename>*.cmxa</filename>), bytecode object files (<filename>*.cmo</filename>), native object files (<filename>*.cmx</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>/usr/local/lib/ocaml/&ocaml-version;/stublibs</filename>, as can it be seen in the <filename>/usr/lib/ocaml/&ocaml-version;/ld.conf</filename> file.
+ </para>
+
+ <para>
+ If upstream developpers already use a subdirectory of the OCaml standard library path, 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 developpers don't use this scheme, 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 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 (named <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 oragnization 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>/usr/lib/ocaml/&ocaml-version;/META/</filename></para></listitem>
+ <listitem><para><filename>/usr/lib/ocaml/&ocaml-version;/package/</filename></para></listitem>
+ </itemizedlist>
+ </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, it should be called <filename>META</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the <filename>META</filename> file is placed in <filename>/usr/lib/ocaml/&ocaml-version;/META/</filename>, 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>/usr/lib/ocaml/&ocaml-version;/lablgtk/META</filename>, where <filename>/usr/lib/ocaml/&ocaml-version;</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>, packagers are encouraged to create one. In this case, the <filename>META</filename> should be sent to upstream authors, in order to have it included in the next version of the upstream source. For more information about <filename>META</filename> files, have a look at 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 ML 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;</title>
+ <para>
+ Actually, &camlp4; extensions are stored in
+ <filename>/usr/lib/ocaml/&ocaml-version;/camlp4/</filename>. In order to do something
+ cleaner, &ocaml-force; propose to put this files in their own directory, even in their
+ own package. It is not mandatory, but it could ease a lot, the user of camlp4, by avoiding
+ name clash.
+ </para>
+
+ <para>
+ You just have to consider &camlp4; file just as standard library, except that you
+ prefix them with <varname>-syntax</varname>. For example: the syntax
+ extension coming with <application>libokey-ocaml-dev</application> should be stored
+ in <filename>/usr/lib/ocaml/&ocaml-version;/okey-syntax/</filename>, the package
+ containing it should be called <application>libokey-syntax-ocaml-dev</application>.
+ </para>
+
+ <para>
+ It is recommended to use <filename>META</filename> to specify how to handle this
+ extension.
+ </para>
+
+ <para>
+ All definition is taken from previous text considering syntax extension as a standalone
+ library.
+ </para>
+
+</section>
+
+<section id="documentation">
+ <title>Documentation</title>
+ <para>
+ The documentation is a joint effort of &ocaml-force; and usptream.
+ There is many way 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 browse by different mean, from the
+ most simple to the most complex. At least, they could all be browsed with
+ simple text editor. Specific and &ocamldoc; generated documentation should
+ be browse by using different viewer ( like <application>advi</application>,
+ HTML browser...). There is also at least two
+ specific &ocaml-name; browser : <application>docbrowse</application> shipped
+ with <application>cameleon</application> and <application>ocamlbrowser</application>
+ shipped with &ocaml-name; itself. The first one, need specific
+ &ocamldoc; generated documentation. The second one enables
+ the user to browse directly the prototype of each function shipped in the cmi gives
+ to the application.
+ </para>
+
+ <para>
+ You can generate &ocamldoc; specific documentation by using
+ the <option>-dump</option> of this application. By using this, you dump the
+ intermediary 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>
+
+ <para>
+ As of today, there is no way to post-process &ocamldoc;
+ specific documentation. A &debian-name; package is under construction to do this
+ task. It will be referred as &ocamldoc-base;.
+ </para>
+</section>
+++ /dev/null
- <section id="versions">
- <title>Version</title>
- <para>
- At any given time, the package &ocaml-pkg; should represent
- the current stable upstream version of &ocaml-name;
- revision &ocaml-version;.
- </para>
-
- <para>
- This package provides a virtual package called &ocaml-vpkg;.
- This will help to track incompatible changes made within the
- same version of &ocaml-name;.
- </para>
-
- </section>
-
- <section id="base">
- <title>Base Package</title>
- <para>
- In order to have a minimal installation, a virtual package
- &ocaml-base-vpkg; exists. It enable to have
- a bare minimum install of &ocaml-name; library.
- </para>
-
- <para>
- As for &ocaml-pkg; this package provides
- a virtual package &ocaml-base-vpkg;. This will help to track
- incompatible changes made within the same version of &ocaml-name;.
- </para>
-
- </section>
-
- <section id="files">
- <title>File terminology for Ocaml packaging</title>
-
- <para>
- &ocaml-name; is a complete language allowing to create :
- <simplelist>
- <listitem>bytecoded executable</listitem>
- <listitem>bytecoded library ( <filename>*.cma</filename> )</listitem>
- <listitem>native executable</listitem>
- <listitem>native library ( <filename>*.cmxa</filename> )</listitem>
- <listitem>shared library ( for C-binding ) ( <filename>dll*.so</filename> )</listitem>
- <listitem>static library ( for C-binding ) ( <filename>lib*.a</filename> )</listitem>
- <listitem>bytecoded object ( <filename>*.cmo</filename> )</listitem>
- <listitem>native object ( <filename>*.cmx</filename> )</listitem>
- <listitem>configuration file for handling library ( <filename>META</filename> )</listitem>
- <listitem>&ocamldoc; generated documentation ( <filename>*.odoc</filename> )</listitem>
- <listitem>&camlp4; related files ( <filename>*.cm[ao]</filename> )</listitem>
- </simplelist>
- </para>
-
- <para>
- There is a convention considering that native executable should be
- called <application>progname.opt</application> and bytecoded one
- <application>progname.byte</application>. When packaging, only
- <application>progname</application> is taken in account.
- </para>
-
- <para>
- For easying library management, &ocaml-force; used the
- &ocamlfind; library management scheme. This scheme includes
- a file named <filename>META</filename> which holds
- all the library possibility. This is the configuration file for
- handling library path and compile option.
- </para>
- </section>
-
- <section id="documentation">
- <title>Documentation</title>
- <para>
- The documentation is a joint effort of &ocaml-force; and usptream.
- There is many way to have documentation :
- <simplelist>
- <listitem>Header files ( <filename>*.mli</filename> )</listitem>
- <listitem>Source files ( <filename>*.ml</filename> )</listitem>
- <listitem>Specific documentation provided by the upstream</listitem>
- <listitem>OCamldoc generated documentation</listitem>
- </simplelist>
- </para>
-
- <para>
- This documentation should be browse by different mean, from the
- most simple to the most complex. At least, they could all be browsed with
- simple text editor. Specific and &ocamldoc; generated documentation should
- be browse by using different viewer ( like <application>advi</application>,
- HTML browser ...). There is also at least two
- specific &ocaml-name; browser : <application>docbrowse</application> shipped
- with <application>cameleon</application> and <application>ocamlbrowser</application>
- shipped with &ocaml-name; itself. The first one, need specific
- &ocamldoc; generated documentation. The second one enables
- the user to browse directly the prototype of each function shipped in the cmi gives
- to the application.
- </para>
-
- <para>
- You can generate &ocamldoc; specific documentation by using
- the <option>-dump</option> of this application. By using this, you dump the
- intermediary 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>
-
- <para>
- As of today, there is no way to post-process &ocamldoc;
- specific documentation. A &debian-name; package is under construction to do this
- task. It will be referred as &ocamldoc-base;.
- </para>
-
- </section>
-
- <section id="path">
- <title>Path for all &ocaml-name; component</title>
-
- <para>
- Ocaml will search library in two different location, referred to
- as <varname>local</varname> which hold user installed library and as
- <varname>core</varname> in which packaged modules stood.
- </para>
-
- <section id="library-path">
- <title>Library paths</title>
-
- <para>
- By default, &ocaml-name; will look for modules in this order :
- <variablelist>
- <varlistentry>
- <term><varname>local</varname></term>
- <listitem><filename>/usr/local/lib/ocaml/&ocaml-version;/</filename></listitem>
- </varlistentry>
- <varlistentry>
- <term><varname>core</varname></term>
- <listitem><filename>/usr/lib/ocaml/&ocaml-version;/</filename></listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <para>
- When installing a library, packagers should use a subdirectory of the preceding
- set of path. Subdirectory name is not mandatory.
- </para>
-
- <para>
- If upstream developpers use already a subdirectory of the &ocaml-name;
- standard library path, this path should be preserved in the &debian-name;
- package, but made relative to the standard library path of the &ocaml-pkg;.
- Before using the provided subdirectory, packagers should check if there is
- no subdirectory name clash with other &ocaml-name; library.
- </para>
-
- <para>
- If upstream developpers don't use this scheme, 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 library
- name clash ). Packagers should also consider to do a larger separation by
- creating a subdirectory per binary package ( in order to avoid META name
- clash ).
- </para>
-
- <para>
- A suggested rule to choose 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-path">
- <title><filename>META</filename></title>
-
- <para>
- <filename>META</filename> distribution is the best way to make more
- easy specific library subdirectory oragnization. Even, if user building
- a simple executable should only need one library, and don't want to
- bother himself by using &ocamlfind;, this same user will find one day
- that using &ocamlfind; permit him to compile from anywhere.
- </para>
-
- <para>
- Since we distribute <filename>META</filename>, all devel library
- should suggest the use of &ocamlfind;. So a <varname>Suggest:</varname>
- should be set to &ocamlfind-pkg;.
- </para>
-
- <para>
- By default, &ocamlfind; will look for <filename>META</filename> in this order :
- <variablelist>
- <varlistentry>
- <term><varname>local</varname></term>
- <listitem><filename>/usr/local/lib/ocaml/&ocaml-version;/META/</filename></listitem>
- <listitem><filename>/usr/local/lib/ocaml/&ocaml-version;/package/</filename></listitem>
- </varlistentry>
- <varlistentry>
- <term><varname>core</varname></term>
- <listitem><filename>/usr/lib/ocaml/&ocaml-version;/META/</filename></listitem>
- <listitem><filename>/usr/lib/ocaml/&ocaml-version;/package/</filename></listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <para>
- The naming scheme of <filename>META</filename> is pretty simple :
- <simplelist>
- <listitem>If <filename>META</filename> is placed in the subdirectory
- of the package, it should be called <filename>META</filename>. If
- you don't call it this way, it won't be recognized by &ocamlfind;.
- </listitem>
- <listitem>If <filename>META</filename> is placed in
- <filename>/usr/lib/ocaml/&ocaml-version;/META/</filename>, it should
- be called <filename>META.package</filename>. In order to avoid
- name clash, it should be specialized to the binary package it is shipped
- from, otherwise package should be the package source.
- </listitem>
- </simplelist>
- </para>
-
- <para>
- If upstream doesn't provide a <filename>META</filename>, packager are encouraged
- to create one. It should be placed in the
- <filename>/usr/lib/ocaml/&ocaml-version;/META/</filename>. <filename>META</filename>
- should be sent to upstream authors, in order to have it in the next version of
- the upstream source.
- </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><filename>/usr/local/share/ocamldoc/&ocaml-version;/</filename></listitem>
- </varlistentry>
- <varlistentry>
- <term><varname>core</varname></term>
- <listitem><filename>/usr/share/ocamldoc/&ocaml-version;/</filename></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">
- <para>
- Actually, &camlp4; extensions are stored in
- <filename>/usr/lib/ocaml/&ocaml-version;/camlp4/</filename>. In order to do something
- cleaner, &ocaml-force; propose to put this files in their own directory, even in their
- own package. It is not mandatory, but it could ease a lot, the user of camlp4, by avoiding
- name clash.
- </para>
-
- <para>
- You just have to consider &camlp4; file just as standard library, except that you
- prefix them with <varname>-syntax</varname>. <example>For example : the syntax
- extension coming with <application>libokey-ocaml-dev</application> should be stored
- in <filename>/usr/lib/ocaml/&ocaml-version;/okey-syntax/</filename>, the package
- containing it should be called <application>libokey-syntax-ocaml-dev</application>.
- </example>
- </para>
-
- <para>
- It is recommended to use <filename>META</filename> to specify how to handle this
- extension.
- </para>
-
- <para>
- All definition is taken from previous text considering syntax extension as a standalone
- library.
- </para>
-
- </section>
- </section>
-
-
+<section>
+ <title>Packaging OCaml prgrams</title>
+ <para>
+ blah
+ </para>
+</section>
- <copyright>
- <year>2002</year><year>2003</year>
- <holder>Sven LUTHER, Stefano ZACCHIROLI and Sylvain LE GALL</holder>
- <legalnotice>
+<copyright>
+ <year>2002</year><year>2003</year><year>2004</year><year>2005</year><year>2006</year>
+ <holder>Sylvain LE GALL, Sven LUTHER, Samuel MIMRAM and Stefano ZACCHIROLI</holder>
+</copyright>
+<legalnotice>
<para>
- This manual is free software; you can redistribute it and/or
- modify it under the terms of the GNU General Public License
- as published by the Free Software Foundation; either version
- 2 of the License, or (at your option) any later version.
+ This manual is free software; you can redistribute it and/or
+ modify it under the terms of the GNU General Public License
+ as published by the Free Software Foundation; either version
+ 2 of the License, or (at your option) any later version.
</para>
<para>
- This is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
- the GNU General Public License for more details.
+ This is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
+ the GNU General Public License for more details.
</para>
<para>
- A copy of the GNU General Public License is available as
- <tt>/usr/share/common-licenses/GPL</tt> in the Debian GNU/Linux
- distribution or on the World Wide Web at
-
<ulink url="http://www.gnu.org/copyleft/gpl.html">The GNU Public Licence</ulink>.
+ A copy of the GNU General Public License is available as
+ <filename>/usr/share/common-licenses/GPL</filename> in the Debian GNU/Linux
+ distribution or on the World Wide Web at
+ <ulink url="http://www.gnu.org/copyleft/gpl.html">The GNU Public Licence</ulink>.
</para>
<para>
- You can also obtain it by writing to the
- Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- Boston, MA 02111-1307, USA.
+ You can also obtain it by writing to the
+ Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA.
</para>
- </legalnotice>
- </copyright>
+</legalnotice>
<?xml version="1.0"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "/usr/share/sgml/docbook/dtd/xml/4.2/docbookx.dtd" [
- <!ENTITY ocaml-version "3.07">
- <!ENTITY ocaml-compat "1">
- <!ENTITY ocaml-pkg "<application>ocaml</application>">
- <!ENTITY ocaml-vpkg "<application>ocaml-&ocaml-version;-&ocaml-compat;</application>">
- <!ENTITY ocaml-base-vpkg "<application>ocaml-base-&ocaml-version;-&ocaml-compat;</application>">
- <!ENTITY ocamlfind-pkg "<application>ocaml-findlib</application>">
- <!ENTITY ocamldoc-base "<application>ocamldoc-base</application>">
- <!ENTITY ocaml-name "<application>OCaml</application>">
- <!ENTITY ocaml-force "The Debian OCaml Task Force">
- <!ENTITY ocamlc "<application>ocamlc</application>">
- <!ENTITY ocamlopt "<application>ocamlopt</application>">
- <!ENTITY ocamldoc "<application>ocamldoc</application>">
- <!ENTITY ocamlfind "<application>ocamlfind</application>">
- <!ENTITY camlp4 "<application>camlp4</application>">
- <!ENTITY debian-name "Debian">
- <!ENTITY authors SYSTEM "authors.xml">
- <!ENTITY legal SYSTEM "legal.xml">
- <!ENTITY chapter-ocaml SYSTEM "chapter-ocaml.xml">
- <!ENTITY chapter-liblocal SYSTEM "chapter-liblocal.xml">
- <!ENTITY chapter-libpack SYSTEM "chapter-libpack.xml">
- <!ENTITY chapter-progpack SYSTEM "chapter-progpack.xml">
- <!ENTITY appendix-transition SYSTEM "appendix-transition.xml">
- <!ENTITY appendix-resources SYSTEM "appendix-resources.xml">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"/usr/share/sgml/docbook/dtd/xml/4.3/docbookx.dtd" [
+<!ENTITY ocaml-version "3.09.2">
+<!ENTITY ocaml-compat "1">
+<!ENTITY ocaml-pkg "<application>ocaml</application>">
+<!ENTITY ocaml-vpkg "<application>ocaml-&ocaml-version;</application>">
+<!ENTITY ocaml-base-vpkg "<application>ocaml-base-&ocaml-version;</application>">
+<!ENTITY ocamlfind-pkg "<application>ocaml-findlib</application>">
+<!ENTITY ocamldoc-base "<application>ocamldoc-base</application>">
+<!ENTITY ocaml-name "<application>OCaml</application>">
+<!ENTITY ocaml-force "The Debian OCaml Task Force">
+<!ENTITY ocamlc "<application>ocamlc</application>">
+<!ENTITY ocamlopt "<application>ocamlopt</application>">
+<!ENTITY ocamldoc "<application>ocamldoc</application>">
+<!ENTITY ocamlfind "<application>ocamlfind</application>">
+<!ENTITY camlp4 "<application>camlp4</application>">
+<!ENTITY debian-name "Debian">
+<!ENTITY authors SYSTEM "authors.xml">
+<!ENTITY legal SYSTEM "legal.xml">
+<!ENTITY chapter-generalities SYSTEM "chapter-generalities.xml">
+<!ENTITY chapter-packaging SYSTEM "chapter-packaging.xml">
+<!ENTITY chapter-libpack SYSTEM "chapter-libpack.xml">
+<!ENTITY chapter-progpack SYSTEM "chapter-progpack.xml">
+<!ENTITY chapter-liblocal SYSTEM "chapter-liblocal.xml">
+<!ENTITY appendix-transition SYSTEM "appendix-transition.xml">
+<!ENTITY appendix-resources SYSTEM "appendix-resources.xml">
]>
-<article>
- <articleinfo>
- <title>&debian-name; &ocaml-name; Packaging Policy</title>
- <subtitle>For Objective Caml version &ocaml-version;</subtitle>
- <releaseinfo>Revision 0.1</releaseinfo>
- <!-- Bug ici -->
- &authors;
- &legal;
- </articleinfo>
+<book>
+ <bookinfo>
+ <title>&debian-name; &ocaml-name; Packaging Policy for OCaml &ocaml-version;</title>
+ <releaseinfo>Revision 0.7</releaseinfo>
+ &authors;
+ &legal;
+ </bookinfo>
- <chapter id="ocaml">
- <title>&ocaml-name; Packaging</title>
- &chapter-ocaml;
- </chapter>
+ <chapter id="generalities">
+ <title>Generalities about &ocaml-name; packages in Debian</title>
+ &chapter-generalities;
+ </chapter>
- <chapter id="liblocal">
- <title>Locally installed library</title>
- &chapter-liblocal;
- </chapter>
+ <chapter id="progpack">
+ <title>Packaging OCaml Programs</title>
+ &chapter-progpack;
+ </chapter>
- <chapter id="libpack">
- <title>Packaged library</title>
- &chapter-libpack;
- </chapter>
+ <chapter id="libpack">
+ <title>Packaging OCaml libraries</title>
+ &chapter-libpack;
+ </chapter>
- <chapter id="progpack">
- <title>Packaged program</title>
- &chapter-progpack;
- </chapter>
+ <appendix id="transition">
+ <title>Managing version transition</title>
+ &appendix-transition;
+ </appendix>
- <appendix id="transition">
- <title>Managing version transition</title>
- &appendix-transition;
- </appendix>
-
- <appendix id="resources">
- <title>&ocaml-force; resources</title>
- &appendix-resources;
- </appendix>
-</article>
+ <appendix id="resources">
+ <title>&ocaml-force; resources</title>
+ &appendix-resources;
+ </appendix>
+</book>
projects / ocaml.git / commitdiff