[Pkg-ocaml-maint-commits] [SCM] dh-ocaml packaging branch, policy-update, updated. debian/0.9.5-13-gf9cc191
Ralf Treinen
treinen at free.fr
Sun Aug 15 16:15:58 UTC 2010
The following commit has been merged in the policy-update branch:
commit f9cc191483361bc5279aafaeaac37cfa56721bc1
Author: Ralf Treinen <treinen at free.fr>
Date: Sun Aug 15 18:15:24 2010 +0200
finnish first pass through the policy
diff --git a/policy/chapter-generalities.xml b/policy/chapter-generalities.xml
index bb690ee..d6fcfce 100644
--- a/policy/chapter-generalities.xml
+++ b/policy/chapter-generalities.xml
@@ -29,12 +29,12 @@
bytecode and native. Native executables are usual ELF executables
produced for a particular CPU architecture, while bytecode
executables are written in a language which can only be run on a
- ocaml bytecode interpreter. A bytecode executable starts with a
+ OCaml bytecode interpreter. A bytecode executable starts with a
magic string invoking the interpreter, so that bytecode
executables can just be invoked like native executables. OCaml
compilers to native code are not provided for every
architecture. On a Debian system, the list of architectures for
- which the currently installed version of the ocaml system
+ which the currently installed version of the OCaml system
provides compilation to native code can be found in the file
<filename>/usr/lib/ocaml/native-archs</filename>.
</para>
@@ -53,38 +53,44 @@
<para>
Bytecode executables have the advantage of being portable, which
means that a bytecode executable can be run without having to be
- recompiled on any architecture for which an ocaml bytecode
+ recompiled on any architecture for which an OCaml bytecode
interpreter is available. For Debian, this has the advantage
that packages containing only bytecode executables have
- Architecture=all, which reduces archive space and auto-builder load.
- It also reduces download and installation size for users in
- case they install several bytecode packages.
+ <code>Architecture=all</code>, which reduces archive space and
+ auto-builder load. It also reduces download and installation
+ size for users in case they install several bytecode packages.
</para>
<para>
- An important decision to take when building a Debian package
- is whether to support bytecode, native code, or both. We aim
- to support development both of bytecode and native code
+ An important decision to take when building a Debian package is
+ whether to support bytecode, native code, or both. We aim to
+ support development both of bytecode and native code
applications, hence libraries should be distributed both in
- bytecode and native code. For
- packages containing executables, the rule is:
+ bytecode and native code (see the <ulink url="#libpack">section on
+ library packaging</ulink>). For packages containing executables,
+ the rule is:
<itemizedlist>
<listitem><para> If the execution of the program requires a
- lot of CPU power then the executables in the package should
- be compiled to native code on architectures where this is
+ lot of CPU power then the executables in the package should be
+ compiled to native code on architectures where this is
possible, and to bytecode elsewhere. Typical examples are
- coq, or edos-distcheck. </para></listitem>
+ coq, or edos-distcheck. See the <ulink
+ url="#native-prog">section on native code
+ packages</ulink>.</para></listitem>
- <listitem><para> If the execution of the program is very
- fast on typical application cases then the program contained
- in the package should be compiled to bytecode. Typical
- examples are hevea, or headache. </para></listitem>
+ <listitem><para> If the execution of the program is very fast
+ on typical application cases then the program contained in the
+ package should be compiled to bytecode. Typical examples are
+ hevea, or headache. See the <ulink
+ url="#bytecode-prog">section on bytecode
+ packages</ulink>.</para></listitem>
- <listitem><para> Only in justified cases, for instance when
- both versions provide different features, should a package
- contain programs both compiled to bytecode and native
- code. </para></listitem>
+ <listitem><para> Only in special cases, for instance when both
+ versions provide different features, should a package contain
+ programs both compiled to bytecode and native code. See the
+ <ulink url="#bytecode-native-prog">section on combined
+ bytecode and native code packages</ulink>. </para></listitem>
</itemizedlist>
</para>
</section>
@@ -165,14 +171,14 @@
<para>
bytecode executables linked in <emphasis>custom
mode</emphasis>. They are generated by
- <command>ocamlc</command>, when the
+ <command>ocamlc</command> when the
<option>-custom</option> flag is given at link
time. Those executables are in ELF format and include
both the final bytecode and the bytecode
interpreter. The <command>strip</command> command should never
be invoked on them since it will remove the bytecode
part. Bytecode executables linked in custom mode are
- depreciated an should be avoided.
+ depreciated and should be avoided.
</para>
</listitem>
<listitem>
@@ -222,16 +228,16 @@
<title>Findlib and ocamlfind</title>
<para>&ocaml-force; has chosen to fully support
- <application>findlib</application> library. This is a suite of tools
- that help to manage OCaml library. This tool is not Debian specific and
- works on all platform where OCaml is available. Through years, this has
- become the standard de facto when relying on external library. The main
- frontend is called &ocamlfind; and provided by
- <package>ocaml-findlib</package>.
+ <application>findlib</application> library. This is a suite of
+ tools that help to manage OCaml libraries. This tool is not
+ specific to Debian and works on all platforms where OCaml is
+ available. Through the years, this has become the de facto standard
+ when relying on external libraries. The main frontend is called
+ &ocamlfind; and provided by the package <package>ocaml-findlib</package>.
</para>
- <para>Even though compiling OCaml project in Debian is still possible
- without &ocamlfind;, it is highly recommended to use it.
+ <para>Even though compiling OCaml projects in Debian is still possible
+ without &ocamlfind; it is highly recommended to use it.
</para>
</section>
@@ -239,22 +245,26 @@
<title>The OCaml system in Debian</title>
<para id="package-type">
- OCaml packages can be splitted in three categories in Debian:
+ There are three categories of OCaml packages in Debian:
<itemizedlist>
<listitem>
- <para>devel package, containing OCaml objects require to compile
+ <para>Development packages contain OCaml objects required
+ for the development or compilation of OCaml programs, or
+ specifically for the creation of Debian packages
+ containing OCaml programs.
</para>
</listitem>
<listitem>
- <para>runtime package, containing OCaml objects require to run
- compiled program. A runtime package is always associated with
- a devel package.
+ <para>Runtime package contain OCaml objects necessary to run
+ compiled programs. A runtime package is always associated
+ with a development package.
</para>
</listitem>
<listitem>
- <para>simple binary package, containing everything that don't fall
- into the two former categories. E.g. bytecode and native executable
- share data, documentation.
+ <para>Simple binary package contain everything that does
+ not fall into the two former categories. This includes
+ bytecode and native executable of application programs,
+ documentation, etc.
</para>
</listitem>
</itemizedlist>
@@ -262,21 +272,20 @@
<para>
The <package>ocaml</package> 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 <package>-nox</package> contain libraries
- that do not need X (i.e., for programs that 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 into
- which the OCaml system is organized:
+ packages needed to develop programs with OCaml. More
+ specifically, the packaging of OCaml is split into smaller
+ packages. The packages with suffix <package>-nox</package>
+ contain libraries that do not need the X Window system (i.e.,
+ for programs that don't use the <code>Graphics</code> or
+ <code>LablTk</code> modules). Here is the list of binary
+ packages into which the OCaml system is organized:
<orderedlist>
<listitem>
<para>
The <package>ocaml</package> and <package>ocaml-nox</package>
- packages contain the compiler and its libraries. The can be
- both considered as devel package.
+ packages contain the compiler and its libraries. They can be
+ both considered as development packages.
</para>
</listitem>
<listitem>
@@ -301,17 +310,17 @@
interpreter and runtime libraries needed by bytecode
programs compiled with OCaml (in particular, the package
<package>ocaml-base-nox</package> contains the
- <package>ocamlrun</package> program). They can be both
- considered as runtime package associated to
- <package>ocaml</package> and
+ <package>ocamlrun</package> program). They can both be
+ considered as runtime packages associated to
+ <package>ocaml</package>, resp.
<package>ocaml-nox</package>.
</para>
<note>
<para>
<package>ocaml-base-nox</package> contains also OCaml
interface objects <filename>*.cmi</filename>, which are
- normally only in devel package because they are needed to
- run <command>ocaml</command> toplevel from the package
+ normally only in development packages because they are needed to
+ run the <command>ocaml</command> toplevel from the package
<package>ocaml-interp</package>.
</para>
</note>
@@ -320,16 +329,16 @@
<para>
The <package>ocaml-interp</package> package contains the
toplevel system for OCaml (<package>ocaml</package>) which
- provides for an interactive interpreter of the language. This
- package is built so that simple script in OCaml can be run
- with the minimal dependencies.
+ provides for an interactive interpreter of the language.
</para>
</listitem>
<listitem>
<para>
- The <package>ocaml-mode</package> package contains the OCaml
- Emacs mode (the one provided with OCaml, not the tuareg mode
- which is in the package <package>tuareg-mode</package>).
+ The <package>ocaml-mode</package> package contains the
+ OCaml Emacs mode. This is the original Emacs mode provided
+ with the OCaml upstream distribution, not to be confused
+ with the tuareg Emacs mode which is in the package
+ <package>tuareg-mode</package>.
</para>
</listitem>
<listitem>
@@ -349,7 +358,14 @@
<listitem>
<para>
The packages <package>camlp4</package> and
- <package>camlp4-extra</package> contains the &camlp4;
+ <package>camlp4-extra</package> contain the &camlp4;
+ preprocessor.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The packages <package>camlp5</package> and
+ <package>camlp5-extra</package> contain the &camlp5;
preprocessor.
</para>
</listitem>
@@ -359,11 +375,9 @@
<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):
- <package>ocaml-&ocaml-version;</package>,
- <package>ocaml-nox-&ocaml-version;</package>,
- <package>ocaml-base-&ocaml-version;</package>,
- <package>ocaml-base-nox-&ocaml-version;</package>.
+ packages are also provided by packages at items (1), (2), (6)
+ and (7): <package>ocaml-&ocaml-version;</package>,
+ <package>ocaml-nox-&ocaml-version;</package>, etc.
</para>
</section>
@@ -443,7 +457,7 @@
OCaml development or execution support but just happen to be
implemented in OCaml should have their section set according
to their application domain (<code>games</code>,
- <code>science</code>, etc.). General develoment tools that are
+ <code>science</code>, etc.). General development tools that are
not specific to OCaml development go into section
<code>devel</code> (example: headache).
</para>
@@ -455,7 +469,9 @@
Documentation relevant to programming in OCaml should be
registered with doc-base in Section
<code>Programming/OCaml</code>. This is the case for API
- documentation generated using &ocamldoc;.
+ documentation generated using &ocamldoc;. See the <ulink
+ url="#documentation">section on generating
+ documentation</ulink>.
</para>
</section>
</section>
diff --git a/policy/chapter-libpack.xml b/policy/chapter-libpack.xml
index 082a3fc..7972c99 100644
--- a/policy/chapter-libpack.xml
+++ b/policy/chapter-libpack.xml
@@ -33,7 +33,7 @@
<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>
+ libraries then this package should depend on them. </para>
<para>
<filename>libxxx-ocaml-dev</filename> should depend on its
@@ -139,78 +139,23 @@
<para>
If upstream developers already use a subdirectory of the OCaml standard
- library path, this path should be preserved in the Debian package but
+ library path then this path should be preserved in the Debian package but
made relative to the standard library path of OCaml. Before using the
provided subdirectory, packagers should obviously check if there is no
subdirectory name clash with another OCaml library. </para>
<para>
- If upstream developers 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>
+ If upstream developers do not use this scheme then packagers are
+ encouraged not to install this library in the standard library
+ directory. They should create at least a subdirectory per source
+ package (in order to avoid name clashes). Packagers should also
+ consider to do a larger separation by creating a subdirectory
+ per binary package (in order to avoid META name clash). A
+ suggested rule to choose the name for this subdirectory is to use
+ either the package name provided by the META of the upstream, or
+ the name of the library itself. </para>
</section>
- <section>
- <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, this path should not be
- hardcoded. Previous version of the packaging scheme install libraries into
- versionned standard library directory. So path should not be hardcoded,
- instead <filename>.in</filename> files should be used where
- <varname>@OCamlStdlibDir@</varname> and
- <varname>@OCamlDllDir@</varname> are 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 <ulink
- url='#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>
@@ -241,13 +186,13 @@
<listitem>
<para>
If the <filename>META</filename> file is placed in the subdirectory
- of the package, it should be called <filename>META</filename>.
+ of the package then it should be called <filename>META</filename>.
</para>
</listitem>
<listitem>
<para>
If the <filename>META</filename> file is placed in
- <filename>&ocaml-metas-dir;/</filename>, it should be called
+ <filename>&ocaml-metas-dir;/</filename> then it should be called
<filename>META.packagename</filename>, where
<filename>packagename</filename> is the name of the subdirectory
where the library is stored. </para>
@@ -264,7 +209,7 @@
directory. </para>
<para>
- If upstream doesn't provide a <filename>META</filename>, packagers are
+ If upstream doesn't provide a <filename>META</filename> then 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
@@ -330,8 +275,8 @@
<section id="camlp4-path">
<title>&camlp4;/&camlp5;</title>
- <para> Actually, &camlp4; extensions should be processed just as standard
- OCaml library. The META file distributed with this syntax extension
+ <para> Actually, &camlp4; extensions should be processed just like standard
+ OCaml libraries. The META file distributed with this syntax extension
should follow the
<ulink url="http://cocan.org/osr/meta_files_for_packages_containing_syntax_extensions">
OSR: META files for packages containing syntax extensions</ulink>. In
@@ -346,7 +291,7 @@
</para>
<para>
- If a package contains at the same time syntax extension and library, it
+ If a package contains at the same time syntax extension and library then it
is up to the maintainer to choose the most relevant name for the package.
Whatever the name chosen for the package, the other name should be a
<varname>Provide</varname> of the package.
@@ -374,7 +319,7 @@
<section id="documentation">
<title>Documentation</title>
<para>
- The documentation is a joint effort of &ocaml-force; and usptream.
+ The documentation is a joint effort of &ocaml-force; and upstream.
There are many ways to have documentation:
<itemizedlist>
<listitem><para>header files (<filename>*.mli</filename>),</para></listitem>
@@ -385,23 +330,22 @@
</para>
<para>
- This documentation should be browsable by different mean, from the most
+ This documentation should be browsable by different means, from the most
simple to the most complex. At least, they should all be readable with
- simple text editor. Specific and &ocamldoc; generated documentations
+ a 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
+ &ocaml-name; browsers: <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
+ 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.
+ function shipped in the <filename>cmi</filename>.
</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.
+ intermediate representation of the document that will be generated by ocamldoc.
This can be used to generate HTML documentation and manpages, by reloading this
file (using <option>-load</option>).
</para>
diff --git a/policy/chapter-progpack.xml b/policy/chapter-progpack.xml
index 50b9f69..b83c424 100644
--- a/policy/chapter-progpack.xml
+++ b/policy/chapter-progpack.xml
@@ -9,10 +9,6 @@
<section>
<title>Creating Packages for OCaml Programs</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
@@ -20,32 +16,12 @@
</para>
<para>
- Programs which are not particularly CPU hungry should be
- compiled into 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. See <xref linkend="bytecode-prog" /> for details on
- this kind of packages.
+ Packages containing executables (as opposed to libraries) may be
+ produced by compiling to bytecode, native code, or both. See
+ <ulink url="#bytecode-native">this discussion of which mode to
+ choose</ulink>.
</para>
- <para>
- Other programs should be compiled into native form on architectures
- where the native compiler is available, and into 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. That
- said, the upstream authors often favor statically linked bytecode
- executables (&ocamlc; option <option>-custom</option>), because in this
- case 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 where package dependencies can fix this problem.
- </para>
<para>
Package containing only bytecode executable, native executable or data
@@ -59,21 +35,33 @@
<para>
A bytecode package has all its binaries compiled into
bytecode. It depends on a package containing the OCaml runtime
- system. By consequence, such a package has its architecture
+ system. As a consequence, such a package has its architecture
field set to <code>all</code>.
</para>
+
+ <para>
+ All bytecode executables should be linked dynamically against the
+ shared libraries for C bindings, so as to not bloat the archive. That
+ said, the upstream authors often favor statically linked bytecode
+ executables (&ocamlc; option <option>-custom</option>), because in this
+ case 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 where package dependencies can fix this problem.
+ </para>
<para>
- A bytecode package must depend on the provided runtime packages that is
- required to run. Typically, it should depends on &ocaml-base-nox-vpkg; or
- &ocaml-base-vpkg;, if if the program either uses the <code>Graphics</code>
- or the <code>LablTk</code> module). It can also depends on the virtual
- <package>libXXX-ocaml-byte-ABCD</package> provided by the runtime package
- <package>libXXX-ocaml</package>. In order for the package to be able to be
- rebuilt or even binNMUed without a change in the packaging,
- <emphasis>these virtual packages should not be hardcoded in the
- <filename>debian/control</filename> file.</emphasis>. Instead, the
- package should use some tools provided by &dh-ocaml; package to do the job.
+ A bytecode package must depend on the provided runtime packages
+ that is required to run it. Typically, it should depends on
+ &ocaml-base-nox-vpkg; (or &ocaml-base-vpkg;, if if the program
+ either uses the <code>Graphics</code> or the <code>LablTk</code>
+ module). It can also depends on the virtual
+ <package>libXXX-ocaml-byte-ABCD</package> provided by the
+ runtime package <package>libXXX-ocaml</package>. In order for
+ the package to be able to be rebuilt or even binNMUed without a
+ change in the packaging, <emphasis>these virtual packages should
+ not be hard-coded in the <filename>debian/control</filename>
+ file</emphasis>. Instead, the package should use some tools
+ (for instance those provided by the &dh-ocaml; package) to do the job.
</para>
<para>
@@ -107,21 +95,15 @@
As explained in <ulink url='#bytecode-native'/>, native OCaml compilers
are not available everywhere. For architectures missing native
compiler, a bytecode version of the program should be provided.
+ Native code packages are specific to an architecture, that is they
+ have <code>Architecture=any</code> in the source package.
</para>
<para>
- The <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. It is not recommended to provide
- both executable if they ship the same feature, it is also not recommended
- to build at the same time an architecture independent package
- (<code>Architecture: all</code>) providing the bytecode and an
- architecture dependent package providing the native code only for native
- architecture supporting it.
+ The <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.
</para>
<para>
@@ -134,15 +116,15 @@
<section id="bytecode-native-prog">
<title>Bytecode and native versions of programs</title>
<para>
- WHERE TO PUT THIS?
- Packages providing both native and bytecode versions of a program
- <command>prog</command> usually name them respectively
- <command>prog.opt</command> and
- <command>prog.byte</command> and provide a symbolic link
- <command>prog</command> to the best available version (generally
- <command>prog.opt</command>). Providing both version should be
- really useful, there must be a difference in term of features between the
- two version.
- </para>
+ This should be done only under exceptional circumstances.
+ Packages providing both native and bytecode versions of a
+ program <command>prog</command> usually name them respectively
+ <command>prog.opt</command> and <command>prog.byte</command> and
+ provide a symbolic link <command>prog</command> to the best
+ available version (generally <command>prog.opt</command>).
+ Please consult the rules for <ulink url="#bytecode-prog">bytecode
+ packages</ulink> and for <ulink url="#native-prog">native code
+ packages</ulink>.
+ </para>
</section>
</chapter>
diff --git a/policy/included.ent b/policy/included.ent
index 32ab4f2..6d7ad32 100644
--- a/policy/included.ent
+++ b/policy/included.ent
@@ -1,5 +1,5 @@
<!ENTITY doc-version "0.8.0">
-<!ENTITY ocaml-version "<nonterminal>ocaml-version</nonterminal>">
+<!ENTITY ocaml-version "[ocaml-version]">
<!ENTITY ocaml-sys-dir-base "/usr/lib/ocaml">
<!ENTITY ocaml-sys-dir "<filename>&ocaml-sys-dir-base;</filename>">
<!ENTITY ocaml-metas-dir "<filename>&ocaml-sys-dir-base;/METAS</filename>">
diff --git a/policy/ocaml_packaging_policy.xml b/policy/ocaml_packaging_policy.xml
index a3ac419..971486d 100644
--- a/policy/ocaml_packaging_policy.xml
+++ b/policy/ocaml_packaging_policy.xml
@@ -19,6 +19,15 @@
xmlns:xi="http://www.w3.org/2003/XInclude"/>
</bookinfo>
+
+ <preface>
+ <title>Conventions used in this document</title>
+ <para>
+ &ocaml-version; stands for the current upstream version of the
+ OCaml system (for instance, 3.11.2).
+ </para>
+ </preface>
+
<xi:include
href="chapter-generalities.xml"
xmlns:xi="http://www.w3.org/2003/XInclude"/>
diff --git a/policy/scratch.xml b/policy/scratch.xml
index 78fc6ff..d45d9cb 100644
--- a/policy/scratch.xml
+++ b/policy/scratch.xml
@@ -62,4 +62,66 @@
</programlisting>
</para>
+
+
+ <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, this path should not be
+ hardcoded. Previous version of the packaging scheme install libraries into
+ versionned standard library directory. So path should not be hardcoded,
+ instead <filename>.in</filename> files should be used where
+ <varname>@OCamlStdlibDir@</varname> and
+ <varname>@OCamlDllDir@</varname> are 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 <ulink
+ url='#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>
+
</chapter>
+
+
+
--
dh-ocaml packaging
More information about the Pkg-ocaml-maint-commits
mailing list