+++ /dev/null
-all: html text
-
-html:
- docbook2html ocaml_packaging_policy.xml -o packaging-policy-html
-
-text:
- docbook2txt ocaml_packaging_policy.xml
-
-clean:
- $(RM) -rf packaging-policy-html ocaml_packaging_policy.txt
-
-.PHONY: html text
+++ /dev/null
------------------------
-* *
-* HOWTO-XML *
-* DOCBOOK *
-* *
-* *
------------------------
-
-
-If you are interested in writing in the policy, you should
-take a look at
-
-http://docbook.sourceforge.net/
-http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html
-
-When you finish write your part, just do a make clean && make all. It will result
-in having ocaml_packaging_policy.html...
-
-Sylvain LE GALL
-Sat, 18 October 2003
+++ /dev/null
-<para>
- <itemizedlist>
- <listitem><para>&ocaml-force;'s website: <ulink url="http://pkg-ocaml-maint.alioth.debian.org/">http://pkg-ocaml-maint.alioth.debian.org/</ulink> (it's an <ulink url="http://alioth.debian.org/projects/pkg-ocaml-maint/">Alioth project</ulink>)</para></listitem>
- <listitem><para>&ocaml-force;'s mailing list: <ulink url="mailto:debian-ocaml-maint@lists.debian.org">debian-ocaml-maint@lists.debian.org</ulink> (<ulink url="http://lists.debian.org/debian-ocaml-maint/">archives</ulink>)</para></listitem>
- </itemizedlist>
-</para>
+++ /dev/null
-<section>
- <title>How to obtain a copy of the SVN archive</title>
- <para>
- You can obtain a copy of debian-ocaml-maint SVN archive by
- <programlisting>
-svn co svn+ssh://svn.debian.org/svn/pkg-ocaml-maint
- </programlisting>
- You must be member of the
- <ulink url="http://pkg-ocaml-maint.alioth.debian.org/">Debian
- OCaml Task Force</ulink> in order to have write access to this archive.
- </para>
-</section>
-
-<section>
- <title>Structure of the SVN archive</title>
- <para>
- We keep all files of the debian subdirectory under svn control, and
- upstream only as a compressed tarball. The rationale behind this is
- that changes to upstream files should be managed by the <application>dpatch</application> patch
- manager. Hence, all the diffs to upstream files are kept in a
- subdirectory of <filename>debian/</filename>, and it is not necessary to manage upstream on
- file-by-file basis.
- </para>
-
- <para>
- The structure of the pkg-ocaml-maint svn archive is as follows, where
- generic names are indicated in square brackets <varname>[ .. ]</varname>, and where the
- contents of subdirectories not directly relevant for package management
- are not detailed:
- <programlisting>
- tags
- packages
- [package1]
- [version1]
- [version2]
- ...
- [package2]
- [version1]
- ...
- ...
- projects
- test
- trunk
- packages
- [package1]
- trunk
- debian
- upstream
- [upstream-tarball-version1]
- [upstream-tarball-version2]
- ...
- [package2]
- ...
- policy
- projects
- tools
- </programlisting>
- </para>
-</section>
-
-<section>
- <title>How to add a new package to the SVN archive</title>
- <para>
- Place yourself in the directory <filename>trunk/packages</filename> of your working copy of
- the svn repository. Create a directory with the same name as your
- source package (let's say, my-package), and subdirectories <filename>upstream</filename>
- and <filename>trunk</filename>. Put the current upstream tarball in <filename>upstream</filename>, and the
- current debian directory with all its relevant files in <filename>trunk</filename>. This
- should now look like this:
- <programlisting>
- trunk/packages/my_package
- upstream
- my_package_1.2.3.orig.tar.gz
- trunk
- debian
- changelog
- control
- copyright
- patches
- 00_list
- 01_patch1.dpatch
- ...
- ...
- </programlisting>
- </para>
-
- <para>
- If everything is in order you can do a <command>svn add my_package</command> from the <filename>trunk/packages</filename> directory, and eventually <command>svn commit</command>.
- </para>
-</section>
-
-<section>
- <title>How to set up your package for use with <application>svn-buildpackage</application></title>
-
- <para>
- Please see the <application>svn-buildpackage</application> documentation for complete
- information. The important issues here are:
- <itemizedlist>
- <listitem>
- <para>
- Since we keep upstream as a tarball we have to use <application>svn-buildpackage</application> in
- so-called merge mode. This means that, before compiling the package,
- the debianized source tree is constructed by untarring the orig tarball, and then merging the contents of the trunk subdirectory in it.
- </para>
- </listitem>
- <listitem>
- <para>
- The structure of our svn repository is not among the default structures
- of <application>svn-buildpackage</application>. Hence, we have to override the default location of some
- directories.
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- Place yourself in <filename>trunk/packages/my_packages/trunk</filename>, and do the following:
- <command>svn propset mergeWithUpstream 1 debian</command>.
- This registers the property "mergeWithUpstream" with the current
- directory, such that svn-buildpackage knows that it has to use merge
- mode as explained above.
- </para>
-
- <para>
- Create a file <filename>debian/svn-deblayout</filename> with the following contents:
- <programlisting>
-origDir=../upstream
-origUrl=svn+ssh://svn.debian.org/svn/pkg-ocaml-maint/trunk/packages/my_package/upstream
-tagsUrl=svn+ssh://svn.debian.org/svn/pkg-ocaml-maint/tags/packages/my_package
- </programlisting>
- </para>
-
- <para>
- Remember that "my_package" has to be replaced by the name of your
- actual package. <application>svn-buildpackage</application> will not include this file in the
- source package when actually building the package.
- </para>
-
- <para>
- If you tried <application>svn-buildpackage</application> before writing your <filename>debian/svn-deblayout</filename> remember
- to delete <filename>.svn/deb-layout</filename>, since <application>svn-buildpackages</application> caches here the content
- of <filename>svn-deblayout</filename> (that would be empty in this case) and will ignore
- your <filename>debian/svn-deblayout</filename>.
- </para>
-</section>
-
-<section>
- <title>How to build a package with <application>svn-buildpackage</application></title>
-
- <para>
- Please refer to the <application>svn-builpackage</application> documentation for more complete
- information. Here is just a quick guide.
- </para>
-
- <para>
- All options, except those starting on <option>--svn</option>, are passed to
- <application>dpkg-buildpackage</application>. Hence, basic usage should be something like this
- (from the <filename>trunk/packages/my_package/trunk</filename> directory): <command>svn-buildpackage -rfakeroot -uc -us</command>.
- </para>
-
- <para>
- svn-buildpackage will complain when your copy of the debian directory
- is not in sync with the repository. You may use the option
- <option>--svn-ignore-new</option> to override this behaviour. The package will be
- build in the directory <filename>../build-area</filename>.
- </para>
-
- <para>
- If your package is ready for upload you may use the <option>--svn-tag</option> option
- for the final build. This will put a tag in the svn-repository on the
- current version, and add a new entry in the changlog to start working
- on the upcomming next version: <command>svn-buildpackage --svn-tag</command>.
- Provided you have commited all your changes to the svn repository, this
- will after a successful build of the package create a tag for the current
- version in <filename>tags/packages/my_package</filename>. The tagging is done directly in the
- svn repository.
- </para>
-
- <tip>
- <para>
- Some useful aliases took from the svn-buildpackage HOWTO:
- <programlisting>
-alias svn-b='svn-buildpackage -rfakeroot --svn-dont-clean -us -uc --svn-ignore'
-alias svn-bt='svn-buildpackage -rfakeroot --svn-lintian --svn-dont-clean --svn-tag'
- </programlisting>
- </para>
-
- <para>
- The former (<command>svn-b</command>) is to be used for test builds, while you are
- working on your package; while the latter (<command>svn-bt</command>) is to be used at
- the end, after you commit your changes and just before uploading a new
- version of the package to the debian archive.
- </para>
-
- <para>
- Adding -k<your gpg id> to the svn-bt alias may also be useful when working on
- collaboratively maintained packages:
- <programlisting>
-alias svn-bt='svn-buildpackage -rfakeroot -k<gpgid> --svn-lintian --svn-dont-clean --svn-tag'
- </programlisting>
- </para>
- </tip>
-</section>
-
-<section>
- <title>dpatch</title>
-
- <para>
- dpatch will work properly at package build time with the svn
- structure described above since all of the build process will be
- carried out in a fresh directory. However, invoking
- <filename>debian/rules</filename> with the "clean" target in
- the <filename>trunk/</filename> directory will fail since
- dpatch is unable to de-apply patches. Passing
- <option>--svn-dont-clean</option> to
- <application>svn-buildpackage</application> fixes this
- misbehaviour (aliases suggested above already include this
- flag). </para>
-
- <para>
- If you want to use dpatch-edit-patch to handle patches, you will need to invoke
- it in "debian only mode" (<option>-b</option> flag, see man dpatch-edit-patch) and to tell him
- where to find the upstream tarball. Adding the following line to your
- <filename>~/.dpatch.conf</filename> will be enough:
- <programlisting>
-conf_origtargzpath=../upstream
- </programlisting>
- </para>
-</section>
+++ /dev/null
- <!--author>
- <firstname>Sven</firstname>
- <surname>Luther</surname>
- <affiliation>
- <orgname>The Debian Project</orgname>
- <address><email>luther@debian.org</email></address>
- </affiliation>
- </author>
- <author>
- <firstname>Stefano</firstname>
- <surname>Zacchiroli</surname>
- <affiliation>
- <orgname>The Debian Project</orgname>
- <address><email>zack@debian.orgcs.unibo.it</email></address>
- </affiliation>
- </author>
- <author>
- <firstname>Sylvain</firstname>
- <surname>Le Gall</surname>
- <affiliation>
- <orgname>The NM Debian Project</orgname>
- <address><email>sylvain.le-gall@polytechnique.org</email></address>
- </affiliation>
- </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 packages with suffix <filename>-nox</filename> 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 dependencies on big packages for users who do not need to run graphical applications. Here is the list of binary packages in which OCaml is split:
- <orderedlist>
- <listitem>
- <para>
- The <filename>ocaml</filename> and <filename>ocaml-nox</filename> packages contain the compiler and its libraries.
- </para>
- </listitem>
- <listitem>
- <para>
- The <filename>ocaml-native-compilers</filename> package contains the OCaml compilers built in native mode (<filename>ocamlc.opt</filename> and <filename>ocamlopt.opt</filename>).
- </para>
- <note>
- <para>The compilers themselves are built in native mode, nonetheless, both compilers for compiling toward bytecode and native code are contained in this package.</para>
- </note>
- </listitem>
- <listitem>
- <para>
- The <filename>ocaml-base</filename> and <filename>ocaml-base-nox</filename> packages contain the interpreter and runtime libraries needed by bytecode programs compiled with OCaml (in particular, the package <filename>ocaml-base-nox</filename> contains the <filename>ocamlrun</filename> program).
- </para>
- </listitem>
- <listitem>
- <para>
- The <filename>ocaml-interp</filename> package contains the toplevel system for OCaml (<filename>ocaml</filename>), that enables interactive use of the language.
- </para>
- </listitem>
- <listitem>
- <para>
- The <filename>ocaml-mode</filename> package contains the OCaml Emacs mode (the one provided with OCaml, not the tuareg mode which is in the package <filename>tuareg-mode</filename>).
- </para>
- </listitem>
- <listitem>
- <para>
- The <filename>ocaml-source</filename> package contains the sources of the OCaml compiler.
- </para>
- </listitem>
- <listitem>
- <para>
- The <filename>ocaml-compiler-libs</filename> package contains some internal libraries of the OCaml compiler (needed only in very rare cases, e.g. for developing languages which reuse OCaml internals).
- </para>
- </listitem>
- </orderedlist>
- </para>
-
- <para>
- Since libraries produced by OCaml are binary incompatible when compiled with different releases of OCaml, versioned virtual packages are also provided by packages at items (1) and (2): <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>
- <title>OCaml location</title>
- <para>
- The root of all installed OCaml libraries is the <emphasis>OCaml
- standard library directory</emphasis>, which is
- <filename>/usr/lib/ocaml/VERSION/</filename>, at the time of writing
- <filename>&ocaml-sys-dir;</filename>. It can be output
- by the OCaml compiler invoking it as <code>ocamlc -where</code>.
- </para>
-
- </section>
-
-</section>
-
-<section id="bytecode-native">
- <title>Bytecode and native 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: &supported-archs;.
- </para>
-
- <para>
- Packages 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>, which outputs bytecode, and <filename>ocamlopt.opt</filename>, which output native code). Compiling with those versions of the compilers is generally faster. Unfortunately the <filename>ocaml-native-compilers</filename> package is not available on every architecture. <emphasis>Packages should therefore never depend directly on this package.</emphasis> In order to build big programs and benefit from this natively built compiler, packages should depend on <filename>ocaml-best-compilers</filename> which itself depends on <filename>ocaml-native-compilers</filename> where available and on <filename>ocaml</filename> elsewhere. Since it is a virtual package, it cannot (yet) be a versioned dependency. The version dependency should thus be carried by the <filename>ocaml</filename> dependency.
- </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 the shebang line <code>#!/usr/bin/ocamlrun</code>)</para></listitem>
- <listitem>
- <para>bytecode executables linked in <emphasis>custom mode</emphasis>. They are generated by <filename>ocamlc</filename> (or <filename>ocamlc.opt</filename>), when the <code>-custom</code> flag is given at link time. Those executables are in ELF format and include both the final bytecode and the bytecode interpreter. <filename>strip</filename> should never be invoked on them, since it will remove the bytecode part.
- </para>
- </listitem>
- <listitem><para>native executables (in ELF format)</para></listitem>
- <listitem><para>bytecode libraries (<filename>*.cma</filename>)</para></listitem>
- <listitem><para>native libraries (<filename>*.cmxa</filename>)</para></listitem>
- <listitem><para>shared libraries (for C bindings) (<filename>dll*.so</filename>, <filename>lib*.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>
- <!-- ZACK: do we really need to differentiate them? They are plain
- objects or library after all ... -->
- <!--<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 default configuration of <filename>ocamlfind</filename> (the OCaml
- library manager recommended in Debian) first looks for a local
- installation of libraries and then for libraries installed by Debian
- packages. The next section describes the standard paths for files
- contained in Debian packages.
- </para>
-
- <warning>
- <para>
- 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>
- </warning>
-
-</section>
+++ /dev/null
-<section>
- <title>Creating a package for a library</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 <filename>ocaml-base-&ocaml-version;</filename> (or <filename>ocaml-base-nox-&ocaml-version;</filename>) as well as any other library needed. The <emphasis>versioned</emphasis> dependency on <filename>ocaml-base</filename> is important since libraries are binary incompatible between releases of OCaml.
- </para>
- <para>
- <filename>libxxx-ocaml</filename> packages should be in <code>Section: libs</code>
- </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, this package should depend on them.
- </para>
- <para>
- <filename>libxxx-ocaml-dev</filename> packages should be in <code>Section: libdevel</code>
- </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.
- <!-- ZACK: yes, it works, it has been fixed in ocaml 3.09.1 IIRC -->
- <!--We are not sure this really works right now for libraries, and-->
- 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</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>&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, 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 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>
- <title>Handling dependencies on OCaml</title>
- <para>
- Some parts of the package need to know the current version of OCaml. For example, libraries should be installed <filename>&ocaml-sys-dir;/</filename>. However, <emphasis>the current version of OCaml should never be hardcoded in the package</emphasis> (&ocaml-version; here). This would make a binNMU impossible when the version of OCaml changes. Instead <filename>.in</filename> files should be used where <varname>@OCamlABI@</varname> is replaced at <emphasis>build-time</emphasis> by the current OCaml version.
- </para>
-
- <para>
- For example, the package <filename>ocaml-mad</filename> would normally contain a file <filename>libmad-ocaml-dev.install</filename> for installing files with <filename>dh_install</filename>, containing:
- <programlisting>
- usr/lib/ocaml/&ocaml-version;/mad/META
- usr/lib/ocaml/&ocaml-version;/mad/*.a
- usr/lib/ocaml/&ocaml-version;/mad/*.cm*
- usr/lib/ocaml/&ocaml-version;/mad/*.ml*
- </programlisting>
- In order to avoid the explicit mention of the version of OCaml (&ocaml-version;), the package actually contains instead a file <filename>libmad-ocaml-dev.install.in</filename> which contains:
- <programlisting>
- usr/lib/ocaml/@OCamlABI@/mad/META
- usr/lib/ocaml/@OCamlABI@/mad/*.a
- usr/lib/ocaml/@OCamlABI@/mad/*.cm*
- usr/lib/ocaml/@OCamlABI@/mad/*.ml*
- </programlisting>
- The string <varname>@OCamlABI@</varname> is substituted at build-time by the version of OCaml. Here are the relevant parts of the <filename>debian/rules</filename> file:
- <programlisting>
- OCAMLABI := $(shell ocamlc -version)
- OFILES := $(filter-out debian/control,(patsubst %.in,%,$(wildcard debian/*.in)))
-
- ocamlinit:
- for f in $(OFILES); do sed -e 's/@OCamlABI@/$(OCAMLABI)/g' $$f.in > $$f; done
-
- config.status: ocamlinit configure
- [...]
-
- .PHONY: build clean binary-indep binary-arch binary install ocamlinit
- </programlisting>
- </para>
-
- <para>
- The only exception to this rule (properly handled by the example above) is the <filename>debian/control</filename> file, which should never be generated at build-time. As explained in <xref linkend='bytecode-native-prog'/>, the dependency should nevertheless not hardcode the version of OCaml: the <filename>debian/control</filename> file should have a <varname>Depends: ocaml-base-nox-${F:OCamlABI}</varname> which is filled by a <code>dh_gencontrol -s -- -VF:OCamlABI="$(OCAMLABI)"</code> in the <filename>debian/rules</filename> file.
- </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>&ocaml-metas-dir;/</filename></para></listitem>
- <listitem><para><filename>&ocaml-sys-dir;/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>&ocaml-metas-dir;/</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>&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>, 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 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;</title>
- <para>
- Actually, &camlp4; extensions are stored in
- <filename>&ocaml-sys-dir;/camlp4/</filename>. In order to do something
- cleaner, &ocaml-force; proposes to put this files in their own directory, even in their
- own package. It is not mandatory, but it could ease a lot by avoiding
- name clashes.
- </para>
-
- <para>
- You just have to consider a &camlp4; file just as a 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>&ocaml-sys-dir;/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 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 mean, from the
- most simple to the most complex. At least, they should all be readable with
- simple text editor. Specific and &ocamldoc; generated documentations should be provided in HTML format.
- There are 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, needs specific
- &ocamldoc; generated documentation. The second one enables
- the user to browse directly the prototype of each function shipped in the <filename>cmi</filename> 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>
- <title>Creating a package for an OCaml program</title>
- <para>
- Any package providing executables built from OCaml source should conform to the following guidelines.
- </para>
-
- <para>
- The source package should, if possible, use the name of the upstream
- package without modifications.
- </para>
-
- <para>
- Programs which are not particularly CPU angry should be compiled in
- bytecode form and the corresponding binary packages should be
- <code>Architecture: all</code> in order to minimize archive usage and
- avoid the need of rebuilding them on all architectures. Other programs
- should be compiled in native form on architectures where the native
- compiler is available, and in bytecode on other architectures.
- See <xref linkend="bytecode-native-prog" /> for details on how to achieve
- this. The corresponding binary packages should be <code>Architecture:
- any</code> and will need to be built on any architecture.
- </para>
-
- <para>
- All bytecode executables should be linked dynamically against the shared libraries for C bindings, so as to not bloat the archive.
- <!-- ZACK: which cases? -->
- <!--However, there may be special cases, were using statically linked bytecode is necessary, in these cases, it is naturally ok to link statically.-->
- That said, often the upstream authors will favor statically linked bytecode executables, because so they don't need to worry about the presence of the dll stub libraries and such. This is not a valid reason to use statically linked bytecode in a Debian package.
- <!-- ZACK: related to the commented stuff above -->
- <!--If statically linked bytecode is provided, a justification of this use should be provided in the <filename>README.Debian</filename> file.-->
- </para>
-</section>
-
-<section id="bytecode-native-prog">
- <title>Bytecode and native versions of programs</title>
- <para>
- As explained in <xref linkend='bytecode-native' />, native OCaml compilers are not available everywhere. For architectures missing native compiler, a bytecode version of the program should be provided.
- </para>
-
- <para>
- The package's <filename>debian/rules</filename> should build the native code executable if supported on the architecture it is built on, and fall back to building the bytecode version if no working native code compiler is available. Exceptions to this are the executables who are small or not time critical, which may be built only as bytecode. It is the decision of the individual maintainers to choose this, maybe guided by the practice of the upstream author.
- </para>
-
- <para>
- The availability of the native compiler can be tested in the <filename>debian/rules</filename> file by testing the possibility of executing <filename>/usr/bin/ocamlopt</filename>, and build the bytecode version or the native version of the program according to the result of the test. This is a sample snippet of <filename>debian/rules</filename> doing so:
- <programlisting>
- build-stamp:
- dh_testdir
-
- if [ -x /usr/bin/ocamlopt ]; then \
- $(MAKE) opt; \
- else; \
- $(MAKE) all; \
- fi
- </programlisting>
- </para>
-
- <para>
- The bytecode versions are portable. In order to spare the buildds and the Debian archive, bytecode versions should be compiled once for all for big packages (which either take a lot of place on disks or take a lot of time to build). For example, the <filename>spamoracle</filename> package provides the <filename>spamoracle-byte</filename> package which is <varname>Architecture: all</varname> and contains the bytecode version of spamoracle, and the <filename>spamoracle</filename> package which contains the native version of spamoracle and is available only where a native OCaml compiler is available (<varname>Architecture: alpha amd64 arm i386 ia64 kfreebsd-i386 powerpc sparc</varname>).
- </para>
-
- <para>
- Bytecode versions of the programs should depend on <filename>ocaml-base-nox-&ocaml-version;</filename> (or <filename>ocaml-base-&ocaml-version;</filename> the program either uses the <code>Graphics</code> or the <code>LablTk</code> module). In order for the package to be able to be rebuilt or even binNMUed without a change in the packaging, <emphasis>this version should not be hardcoded in the <filename>debian/control</filename> file.</emphasis> Instead, the package should depend on <varname>ocaml-base-nox-${F:OCamlABI}</varname> and use <code>OCAMLABI := $(shell ocamlc -version)</code> and <code>dh_gencontrol -- -VF:OCamlABI="$(OCAMLABI)"</code> in the <filename>debian/rules</filename> file.
- </para>
-
- <para>The following is a snippet of a sample <filename>debian/control</filename>:
- <programlisting>
- Package: spamoracle-byte
- Architecture: all
- Depends: ocaml-base-nox-${F:OCamlABI}
- Provides: spamoracle
- Conflicts: spamoracle
- Replaces: spamoracle
- </programlisting>
- </para>
- <para>The following its pairing <filename>debian/rules</filename> snippet:
- <programlisting>
- OCAMLABI := $(shell ocamlc -version)
- ...
- binary-indep: build install
- dh_gencontrol -i -- -VF:OCamlABI="$(OCAMLABI)"
- </programlisting>
- </para>
-
-</section>
--- /dev/null
+all: html text
+
+html:
+ docbook2html ocaml_packaging_policy.xml -o packaging-policy-html
+
+text:
+ docbook2txt ocaml_packaging_policy.xml
+
+clean:
+ $(RM) -rf packaging-policy-html ocaml_packaging_policy.txt
+
+.PHONY: html text
--- /dev/null
+-----------------------
+* *
+* HOWTO-XML *
+* DOCBOOK *
+* *
+* *
+-----------------------
+
+
+If you are interested in writing in the policy, you should
+take a look at
+
+http://docbook.sourceforge.net/
+http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html
+
+When you finish write your part, just do a make clean && make all. It will result
+in having ocaml_packaging_policy.html...
+
+Sylvain LE GALL
+Sat, 18 October 2003
--- /dev/null
+<para>
+ <itemizedlist>
+ <listitem><para>&ocaml-force;'s website: <ulink url="http://pkg-ocaml-maint.alioth.debian.org/">http://pkg-ocaml-maint.alioth.debian.org/</ulink> (it's an <ulink url="http://alioth.debian.org/projects/pkg-ocaml-maint/">Alioth project</ulink>)</para></listitem>
+ <listitem><para>&ocaml-force;'s mailing list: <ulink url="mailto:debian-ocaml-maint@lists.debian.org">debian-ocaml-maint@lists.debian.org</ulink> (<ulink url="http://lists.debian.org/debian-ocaml-maint/">archives</ulink>)</para></listitem>
+ </itemizedlist>
+</para>
--- /dev/null
+<section>
+ <title>How to obtain a copy of the SVN archive</title>
+ <para>
+ You can obtain a copy of debian-ocaml-maint SVN archive by
+ <programlisting>
+svn co svn+ssh://svn.debian.org/svn/pkg-ocaml-maint
+ </programlisting>
+ You must be member of the
+ <ulink url="http://pkg-ocaml-maint.alioth.debian.org/">Debian
+ OCaml Task Force</ulink> in order to have write access to this archive.
+ </para>
+</section>
+
+<section>
+ <title>Structure of the SVN archive</title>
+ <para>
+ We keep all files of the debian subdirectory under svn control, and
+ upstream only as a compressed tarball. The rationale behind this is
+ that changes to upstream files should be managed by the <application>dpatch</application> patch
+ manager. Hence, all the diffs to upstream files are kept in a
+ subdirectory of <filename>debian/</filename>, and it is not necessary to manage upstream on
+ file-by-file basis.
+ </para>
+
+ <para>
+ The structure of the pkg-ocaml-maint svn archive is as follows, where
+ generic names are indicated in square brackets <varname>[ .. ]</varname>, and where the
+ contents of subdirectories not directly relevant for package management
+ are not detailed:
+ <programlisting>
+ tags
+ packages
+ [package1]
+ [version1]
+ [version2]
+ ...
+ [package2]
+ [version1]
+ ...
+ ...
+ projects
+ test
+ trunk
+ packages
+ [package1]
+ trunk
+ debian
+ upstream
+ [upstream-tarball-version1]
+ [upstream-tarball-version2]
+ ...
+ [package2]
+ ...
+ policy
+ projects
+ tools
+ </programlisting>
+ </para>
+</section>
+
+<section>
+ <title>How to add a new package to the SVN archive</title>
+ <para>
+ Place yourself in the directory <filename>trunk/packages</filename> of your working copy of
+ the svn repository. Create a directory with the same name as your
+ source package (let's say, my-package), and subdirectories <filename>upstream</filename>
+ and <filename>trunk</filename>. Put the current upstream tarball in <filename>upstream</filename>, and the
+ current debian directory with all its relevant files in <filename>trunk</filename>. This
+ should now look like this:
+ <programlisting>
+ trunk/packages/my_package
+ upstream
+ my_package_1.2.3.orig.tar.gz
+ trunk
+ debian
+ changelog
+ control
+ copyright
+ patches
+ 00_list
+ 01_patch1.dpatch
+ ...
+ ...
+ </programlisting>
+ </para>
+
+ <para>
+ If everything is in order you can do a <command>svn add my_package</command> from the <filename>trunk/packages</filename> directory, and eventually <command>svn commit</command>.
+ </para>
+</section>
+
+<section>
+ <title>How to set up your package for use with <application>svn-buildpackage</application></title>
+
+ <para>
+ Please see the <application>svn-buildpackage</application> documentation for complete
+ information. The important issues here are:
+ <itemizedlist>
+ <listitem>
+ <para>
+ Since we keep upstream as a tarball we have to use <application>svn-buildpackage</application> in
+ so-called merge mode. This means that, before compiling the package,
+ the debianized source tree is constructed by untarring the orig tarball, and then merging the contents of the trunk subdirectory in it.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The structure of our svn repository is not among the default structures
+ of <application>svn-buildpackage</application>. Hence, we have to override the default location of some
+ directories.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Place yourself in <filename>trunk/packages/my_packages/trunk</filename>, and do the following:
+ <command>svn propset mergeWithUpstream 1 debian</command>.
+ This registers the property "mergeWithUpstream" with the current
+ directory, such that svn-buildpackage knows that it has to use merge
+ mode as explained above.
+ </para>
+
+ <para>
+ Create a file <filename>debian/svn-deblayout</filename> with the following contents:
+ <programlisting>
+origDir=../upstream
+origUrl=svn+ssh://svn.debian.org/svn/pkg-ocaml-maint/trunk/packages/my_package/upstream
+tagsUrl=svn+ssh://svn.debian.org/svn/pkg-ocaml-maint/tags/packages/my_package
+ </programlisting>
+ </para>
+
+ <para>
+ Remember that "my_package" has to be replaced by the name of your
+ actual package. <application>svn-buildpackage</application> will not include this file in the
+ source package when actually building the package.
+ </para>
+
+ <para>
+ If you tried <application>svn-buildpackage</application> before writing your <filename>debian/svn-deblayout</filename> remember
+ to delete <filename>.svn/deb-layout</filename>, since <application>svn-buildpackages</application> caches here the content
+ of <filename>svn-deblayout</filename> (that would be empty in this case) and will ignore
+ your <filename>debian/svn-deblayout</filename>.
+ </para>
+</section>
+
+<section>
+ <title>How to build a package with <application>svn-buildpackage</application></title>
+
+ <para>
+ Please refer to the <application>svn-builpackage</application> documentation for more complete
+ information. Here is just a quick guide.
+ </para>
+
+ <para>
+ All options, except those starting on <option>--svn</option>, are passed to
+ <application>dpkg-buildpackage</application>. Hence, basic usage should be something like this
+ (from the <filename>trunk/packages/my_package/trunk</filename> directory): <command>svn-buildpackage -rfakeroot -uc -us</command>.
+ </para>
+
+ <para>
+ svn-buildpackage will complain when your copy of the debian directory
+ is not in sync with the repository. You may use the option
+ <option>--svn-ignore-new</option> to override this behaviour. The package will be
+ build in the directory <filename>../build-area</filename>.
+ </para>
+
+ <para>
+ If your package is ready for upload you may use the <option>--svn-tag</option> option
+ for the final build. This will put a tag in the svn-repository on the
+ current version, and add a new entry in the changlog to start working
+ on the upcomming next version: <command>svn-buildpackage --svn-tag</command>.
+ Provided you have commited all your changes to the svn repository, this
+ will after a successful build of the package create a tag for the current
+ version in <filename>tags/packages/my_package</filename>. The tagging is done directly in the
+ svn repository.
+ </para>
+
+ <tip>
+ <para>
+ Some useful aliases took from the svn-buildpackage HOWTO:
+ <programlisting>
+alias svn-b='svn-buildpackage -rfakeroot --svn-dont-clean -us -uc --svn-ignore'
+alias svn-bt='svn-buildpackage -rfakeroot --svn-lintian --svn-dont-clean --svn-tag'
+ </programlisting>
+ </para>
+
+ <para>
+ The former (<command>svn-b</command>) is to be used for test builds, while you are
+ working on your package; while the latter (<command>svn-bt</command>) is to be used at
+ the end, after you commit your changes and just before uploading a new
+ version of the package to the debian archive.
+ </para>
+
+ <para>
+ Adding -k<your gpg id> to the svn-bt alias may also be useful when working on
+ collaboratively maintained packages:
+ <programlisting>
+alias svn-bt='svn-buildpackage -rfakeroot -k<gpgid> --svn-lintian --svn-dont-clean --svn-tag'
+ </programlisting>
+ </para>
+ </tip>
+</section>
+
+<section>
+ <title>dpatch</title>
+
+ <para>
+ dpatch will work properly at package build time with the svn
+ structure described above since all of the build process will be
+ carried out in a fresh directory. However, invoking
+ <filename>debian/rules</filename> with the "clean" target in
+ the <filename>trunk/</filename> directory will fail since
+ dpatch is unable to de-apply patches. Passing
+ <option>--svn-dont-clean</option> to
+ <application>svn-buildpackage</application> fixes this
+ misbehaviour (aliases suggested above already include this
+ flag). </para>
+
+ <para>
+ If you want to use dpatch-edit-patch to handle patches, you will need to invoke
+ it in "debian only mode" (<option>-b</option> flag, see man dpatch-edit-patch) and to tell him
+ where to find the upstream tarball. Adding the following line to your
+ <filename>~/.dpatch.conf</filename> will be enough:
+ <programlisting>
+conf_origtargzpath=../upstream
+ </programlisting>
+ </para>
+</section>
--- /dev/null
+ <!--author>
+ <firstname>Sven</firstname>
+ <surname>Luther</surname>
+ <affiliation>
+ <orgname>The Debian Project</orgname>
+ <address><email>luther@debian.org</email></address>
+ </affiliation>
+ </author>
+ <author>
+ <firstname>Stefano</firstname>
+ <surname>Zacchiroli</surname>
+ <affiliation>
+ <orgname>The Debian Project</orgname>
+ <address><email>zack@debian.orgcs.unibo.it</email></address>
+ </affiliation>
+ </author>
+ <author>
+ <firstname>Sylvain</firstname>
+ <surname>Le Gall</surname>
+ <affiliation>
+ <orgname>The NM Debian Project</orgname>
+ <address><email>sylvain.le-gall@polytechnique.org</email></address>
+ </affiliation>
+ </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 packages with suffix <filename>-nox</filename> 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 dependencies on big packages for users who do not need to run graphical applications. Here is the list of binary packages in which OCaml is split:
+ <orderedlist>
+ <listitem>
+ <para>
+ The <filename>ocaml</filename> and <filename>ocaml-nox</filename> packages contain the compiler and its libraries.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>ocaml-native-compilers</filename> package contains the OCaml compilers built in native mode (<filename>ocamlc.opt</filename> and <filename>ocamlopt.opt</filename>).
+ </para>
+ <note>
+ <para>The compilers themselves are built in native mode, nonetheless, both compilers for compiling toward bytecode and native code are contained in this package.</para>
+ </note>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>ocaml-base</filename> and <filename>ocaml-base-nox</filename> packages contain the interpreter and runtime libraries needed by bytecode programs compiled with OCaml (in particular, the package <filename>ocaml-base-nox</filename> contains the <filename>ocamlrun</filename> program).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>ocaml-interp</filename> package contains the toplevel system for OCaml (<filename>ocaml</filename>), that enables interactive use of the language.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>ocaml-mode</filename> package contains the OCaml Emacs mode (the one provided with OCaml, not the tuareg mode which is in the package <filename>tuareg-mode</filename>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>ocaml-source</filename> package contains the sources of the OCaml compiler.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>ocaml-compiler-libs</filename> package contains some internal libraries of the OCaml compiler (needed only in very rare cases, e.g. for developing languages which reuse OCaml internals).
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ Since libraries produced by OCaml are binary incompatible when compiled with different releases of OCaml, versioned virtual packages are also provided by packages at items (1) and (2): <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>
+ <title>OCaml location</title>
+ <para>
+ The root of all installed OCaml libraries is the <emphasis>OCaml
+ standard library directory</emphasis>, which is
+ <filename>/usr/lib/ocaml/VERSION/</filename>, at the time of writing
+ <filename>&ocaml-sys-dir;</filename>. It can be output
+ by the OCaml compiler invoking it as <code>ocamlc -where</code>.
+ </para>
+
+ </section>
+
+</section>
+
+<section id="bytecode-native">
+ <title>Bytecode and native 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: &supported-archs;.
+ </para>
+
+ <para>
+ Packages 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>, which outputs bytecode, and <filename>ocamlopt.opt</filename>, which output native code). Compiling with those versions of the compilers is generally faster. Unfortunately the <filename>ocaml-native-compilers</filename> package is not available on every architecture. <emphasis>Packages should therefore never depend directly on this package.</emphasis> In order to build big programs and benefit from this natively built compiler, packages should depend on <filename>ocaml-best-compilers</filename> which itself depends on <filename>ocaml-native-compilers</filename> where available and on <filename>ocaml</filename> elsewhere. Since it is a virtual package, it cannot (yet) be a versioned dependency. The version dependency should thus be carried by the <filename>ocaml</filename> dependency.
+ </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 the shebang line <code>#!/usr/bin/ocamlrun</code>)</para></listitem>
+ <listitem>
+ <para>bytecode executables linked in <emphasis>custom mode</emphasis>. They are generated by <filename>ocamlc</filename> (or <filename>ocamlc.opt</filename>), when the <code>-custom</code> flag is given at link time. Those executables are in ELF format and include both the final bytecode and the bytecode interpreter. <filename>strip</filename> should never be invoked on them, since it will remove the bytecode part.
+ </para>
+ </listitem>
+ <listitem><para>native executables (in ELF format)</para></listitem>
+ <listitem><para>bytecode libraries (<filename>*.cma</filename>)</para></listitem>
+ <listitem><para>native libraries (<filename>*.cmxa</filename>)</para></listitem>
+ <listitem><para>shared libraries (for C bindings) (<filename>dll*.so</filename>, <filename>lib*.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>
+ <!-- ZACK: do we really need to differentiate them? They are plain
+ objects or library after all ... -->
+ <!--<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 default configuration of <filename>ocamlfind</filename> (the OCaml
+ library manager recommended in Debian) first looks for a local
+ installation of libraries and then for libraries installed by Debian
+ packages. The next section describes the standard paths for files
+ contained in Debian packages.
+ </para>
+
+ <warning>
+ <para>
+ 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>
+ </warning>
+
+</section>
--- /dev/null
+<section>
+ <title>Creating a package for a library</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 <filename>ocaml-base-&ocaml-version;</filename> (or <filename>ocaml-base-nox-&ocaml-version;</filename>) as well as any other library needed. The <emphasis>versioned</emphasis> dependency on <filename>ocaml-base</filename> is important since libraries are binary incompatible between releases of OCaml.
+ </para>
+ <para>
+ <filename>libxxx-ocaml</filename> packages should be in <code>Section: libs</code>
+ </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, this package should depend on them.
+ </para>
+ <para>
+ <filename>libxxx-ocaml-dev</filename> packages should be in <code>Section: libdevel</code>
+ </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.
+ <!-- ZACK: yes, it works, it has been fixed in ocaml 3.09.1 IIRC -->
+ <!--We are not sure this really works right now for libraries, and-->
+ 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</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>&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, 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 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>
+ <title>Handling dependencies on OCaml</title>
+ <para>
+ Some parts of the package need to know the current version of OCaml. For example, libraries should be installed <filename>&ocaml-sys-dir;/</filename>. However, <emphasis>the current version of OCaml should never be hardcoded in the package</emphasis> (&ocaml-version; here). This would make a binNMU impossible when the version of OCaml changes. Instead <filename>.in</filename> files should be used where <varname>@OCamlABI@</varname> is replaced at <emphasis>build-time</emphasis> by the current OCaml version.
+ </para>
+
+ <para>
+ For example, the package <filename>ocaml-mad</filename> would normally contain a file <filename>libmad-ocaml-dev.install</filename> for installing files with <filename>dh_install</filename>, containing:
+ <programlisting>
+ usr/lib/ocaml/&ocaml-version;/mad/META
+ usr/lib/ocaml/&ocaml-version;/mad/*.a
+ usr/lib/ocaml/&ocaml-version;/mad/*.cm*
+ usr/lib/ocaml/&ocaml-version;/mad/*.ml*
+ </programlisting>
+ In order to avoid the explicit mention of the version of OCaml (&ocaml-version;), the package actually contains instead a file <filename>libmad-ocaml-dev.install.in</filename> which contains:
+ <programlisting>
+ usr/lib/ocaml/@OCamlABI@/mad/META
+ usr/lib/ocaml/@OCamlABI@/mad/*.a
+ usr/lib/ocaml/@OCamlABI@/mad/*.cm*
+ usr/lib/ocaml/@OCamlABI@/mad/*.ml*
+ </programlisting>
+ The string <varname>@OCamlABI@</varname> is substituted at build-time by the version of OCaml. Here are the relevant parts of the <filename>debian/rules</filename> file:
+ <programlisting>
+ OCAMLABI := $(shell ocamlc -version)
+ OFILES := $(filter-out debian/control,(patsubst %.in,%,$(wildcard debian/*.in)))
+
+ ocamlinit:
+ for f in $(OFILES); do sed -e 's/@OCamlABI@/$(OCAMLABI)/g' $$f.in > $$f; done
+
+ config.status: ocamlinit configure
+ [...]
+
+ .PHONY: build clean binary-indep binary-arch binary install ocamlinit
+ </programlisting>
+ </para>
+
+ <para>
+ The only exception to this rule (properly handled by the example above) is the <filename>debian/control</filename> file, which should never be generated at build-time. As explained in <xref linkend='bytecode-native-prog'/>, the dependency should nevertheless not hardcode the version of OCaml: the <filename>debian/control</filename> file should have a <varname>Depends: ocaml-base-nox-${F:OCamlABI}</varname> which is filled by a <code>dh_gencontrol -s -- -VF:OCamlABI="$(OCAMLABI)"</code> in the <filename>debian/rules</filename> file.
+ </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>&ocaml-metas-dir;/</filename></para></listitem>
+ <listitem><para><filename>&ocaml-sys-dir;/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>&ocaml-metas-dir;/</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>&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>, 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 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;</title>
+ <para>
+ Actually, &camlp4; extensions are stored in
+ <filename>&ocaml-sys-dir;/camlp4/</filename>. In order to do something
+ cleaner, &ocaml-force; proposes to put this files in their own directory, even in their
+ own package. It is not mandatory, but it could ease a lot by avoiding
+ name clashes.
+ </para>
+
+ <para>
+ You just have to consider a &camlp4; file just as a 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>&ocaml-sys-dir;/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 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 mean, from the
+ most simple to the most complex. At least, they should all be readable with
+ simple text editor. Specific and &ocamldoc; generated documentations should be provided in HTML format.
+ There are 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, needs specific
+ &ocamldoc; generated documentation. The second one enables
+ the user to browse directly the prototype of each function shipped in the <filename>cmi</filename> 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>
+ <title>Creating a package for an OCaml program</title>
+ <para>
+ Any package providing executables built from OCaml source should conform to the following guidelines.
+ </para>
+
+ <para>
+ The source package should, if possible, use the name of the upstream
+ package without modifications.
+ </para>
+
+ <para>
+ Programs which are not particularly CPU angry should be compiled in
+ bytecode form and the corresponding binary packages should be
+ <code>Architecture: all</code> in order to minimize archive usage and
+ avoid the need of rebuilding them on all architectures. Other programs
+ should be compiled in native form on architectures where the native
+ compiler is available, and in bytecode on other architectures.
+ See <xref linkend="bytecode-native-prog" /> for details on how to achieve
+ this. The corresponding binary packages should be <code>Architecture:
+ any</code> and will need to be built on any architecture.
+ </para>
+
+ <para>
+ All bytecode executables should be linked dynamically against the shared libraries for C bindings, so as to not bloat the archive.
+ <!-- ZACK: which cases? -->
+ <!--However, there may be special cases, were using statically linked bytecode is necessary, in these cases, it is naturally ok to link statically.-->
+ That said, often the upstream authors will favor statically linked bytecode executables, because so they don't need to worry about the presence of the dll stub libraries and such. This is not a valid reason to use statically linked bytecode in a Debian package.
+ <!-- ZACK: related to the commented stuff above -->
+ <!--If statically linked bytecode is provided, a justification of this use should be provided in the <filename>README.Debian</filename> file.-->
+ </para>
+</section>
+
+<section id="bytecode-native-prog">
+ <title>Bytecode and native versions of programs</title>
+ <para>
+ As explained in <xref linkend='bytecode-native' />, native OCaml compilers are not available everywhere. For architectures missing native compiler, a bytecode version of the program should be provided.
+ </para>
+
+ <para>
+ The package's <filename>debian/rules</filename> should build the native code executable if supported on the architecture it is built on, and fall back to building the bytecode version if no working native code compiler is available. Exceptions to this are the executables who are small or not time critical, which may be built only as bytecode. It is the decision of the individual maintainers to choose this, maybe guided by the practice of the upstream author.
+ </para>
+
+ <para>
+ The availability of the native compiler can be tested in the <filename>debian/rules</filename> file by testing the possibility of executing <filename>/usr/bin/ocamlopt</filename>, and build the bytecode version or the native version of the program according to the result of the test. This is a sample snippet of <filename>debian/rules</filename> doing so:
+ <programlisting>
+ build-stamp:
+ dh_testdir
+
+ if [ -x /usr/bin/ocamlopt ]; then \
+ $(MAKE) opt; \
+ else; \
+ $(MAKE) all; \
+ fi
+ </programlisting>
+ </para>
+
+ <para>
+ The bytecode versions are portable. In order to spare the buildds and the Debian archive, bytecode versions should be compiled once for all for big packages (which either take a lot of place on disks or take a lot of time to build). For example, the <filename>spamoracle</filename> package provides the <filename>spamoracle-byte</filename> package which is <varname>Architecture: all</varname> and contains the bytecode version of spamoracle, and the <filename>spamoracle</filename> package which contains the native version of spamoracle and is available only where a native OCaml compiler is available (<varname>Architecture: alpha amd64 arm i386 ia64 kfreebsd-i386 powerpc sparc</varname>).
+ </para>
+
+ <para>
+ Bytecode versions of the programs should depend on <filename>ocaml-base-nox-&ocaml-version;</filename> (or <filename>ocaml-base-&ocaml-version;</filename> the program either uses the <code>Graphics</code> or the <code>LablTk</code> module). In order for the package to be able to be rebuilt or even binNMUed without a change in the packaging, <emphasis>this version should not be hardcoded in the <filename>debian/control</filename> file.</emphasis> Instead, the package should depend on <varname>ocaml-base-nox-${F:OCamlABI}</varname> and use <code>OCAMLABI := $(shell ocamlc -version)</code> and <code>dh_gencontrol -- -VF:OCamlABI="$(OCAMLABI)"</code> in the <filename>debian/rules</filename> file.
+ </para>
+
+ <para>The following is a snippet of a sample <filename>debian/control</filename>:
+ <programlisting>
+ Package: spamoracle-byte
+ Architecture: all
+ Depends: ocaml-base-nox-${F:OCamlABI}
+ Provides: spamoracle
+ Conflicts: spamoracle
+ Replaces: spamoracle
+ </programlisting>
+ </para>
+ <para>The following its pairing <filename>debian/rules</filename> snippet:
+ <programlisting>
+ OCAMLABI := $(shell ocamlc -version)
+ ...
+ binary-indep: build install
+ dh_gencontrol -i -- -VF:OCamlABI="$(OCAMLABI)"
+ </programlisting>
+ </para>
+
+</section>
--- /dev/null
+<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.
+ </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.
+ </para>
+ <para>
+ 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.
+ </para>
+</legalnotice>
--- /dev/null
+<?xml version="1.0"?>
+<!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-sys-dir-base "/usr/lib/ocaml">
+<!ENTITY ocaml-sys-dir "&ocaml-sys-dir-base;/&ocaml-version;">
+<!ENTITY ocaml-metas-dir "&ocaml-sys-dir;/METAS">
+<!ENTITY supported-archs "alpha, amd64, arm, i386, ia64, kfreebsd-i386, powerpc, sparc">
+<!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-resources SYSTEM "appendix-resources.xml">
+<!ENTITY appendix-svn SYSTEM "appendix-svn.xml">
+]>
+<book>
+ <bookinfo>
+ <title>&debian-name; &ocaml-name; Packaging Policy for OCaml &ocaml-version;</title>
+ <releaseinfo>Revision 0.7</releaseinfo>
+ &authors;
+ &legal;
+ </bookinfo>
+
+ <chapter id="generalities">
+ <title>Generalities about &ocaml-name; packages in Debian</title>
+ &chapter-generalities;
+ </chapter>
+
+ <chapter id="progpack">
+ <title>Packaging OCaml Programs</title>
+ &chapter-progpack;
+ </chapter>
+
+ <chapter id="libpack">
+ <title>Packaging OCaml libraries</title>
+ &chapter-libpack;
+ </chapter>
+
+ <appendix id="resources">
+ <title>&ocaml-force; resources</title>
+ &appendix-resources;
+ </appendix>
+
+ <appendix>
+ <title>Using the SVN repository</title>
+ &appendix-svn;
+ </appendix>
+</book>
+++ /dev/null
-<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.
- </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.
- </para>
- <para>
- 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.
- </para>
-</legalnotice>
+++ /dev/null
-<?xml version="1.0"?>
-<!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-sys-dir-base "/usr/lib/ocaml">
-<!ENTITY ocaml-sys-dir "&ocaml-sys-dir-base;/&ocaml-version;">
-<!ENTITY ocaml-metas-dir "&ocaml-sys-dir;/METAS">
-<!ENTITY supported-archs "alpha, amd64, arm, i386, ia64, kfreebsd-i386, powerpc, sparc">
-<!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-resources SYSTEM "appendix-resources.xml">
-<!ENTITY appendix-svn SYSTEM "appendix-svn.xml">
-]>
-<book>
- <bookinfo>
- <title>&debian-name; &ocaml-name; Packaging Policy for OCaml &ocaml-version;</title>
- <releaseinfo>Revision 0.7</releaseinfo>
- &authors;
- &legal;
- </bookinfo>
-
- <chapter id="generalities">
- <title>Generalities about &ocaml-name; packages in Debian</title>
- &chapter-generalities;
- </chapter>
-
- <chapter id="progpack">
- <title>Packaging OCaml Programs</title>
- &chapter-progpack;
- </chapter>
-
- <chapter id="libpack">
- <title>Packaging OCaml libraries</title>
- &chapter-libpack;
- </chapter>
-
- <appendix id="resources">
- <title>&ocaml-force; resources</title>
- &appendix-resources;
- </appendix>
-
- <appendix>
- <title>Using the SVN repository</title>
- &appendix-svn;
- </appendix>
-</book>
projects / ocaml.git / commitdiff