[Pkg-ocaml-maint-commits] [SCM] dh-ocaml packaging branch, policy-update, updated. debian/0.9.5-12-g74e4532
Ralf Treinen (none)
treinen at debian.
Fri Aug 13 13:46:52 UTC 2010
The following commit has been merged in the policy-update branch:
commit 74e45320063430fea98001102902ec4e7b6a4ad1
Author: Ralf Treinen <treinen at debian.(none)>
Date: Fri Aug 13 14:45:59 2010 +0100
reorganiwe sections in chapter generalities, put info on local installatoins into appendix
diff --git a/policy/appendix-local.xml b/policy/appendix-local.xml
new file mode 100644
index 0000000..98fbb47
--- /dev/null
+++ b/policy/appendix-local.xml
@@ -0,0 +1,70 @@
+<?xml version="1.0"?>
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"/usr/share/sgml/docbook/dtd/xml/4.4/docbookx.dtd" [
+<!ENTITY % included SYSTEM "included.ent">
+%included;
+]>
+
+<appendix id="appendix">
+ <title>Appendix</title>
+
+ <section id="liblocal-path">
+ <title>Locally Installing OCaml Programs and Libraries</title>
+
+ <para>
+ Locally installed files are files that are installed directly by
+ the system administrator, in contrast to files installed through Debian
+ packages. 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, a local system
+ administrator should follow these 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/stublibs/</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Basically, every other file should be installed
+ in <filename>/usr/local/lib/ocaml/</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>), native plugin object files
+ (<filename>*.cmxs</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.
+ </para>
+
+ <warning>
+ <para>
+ The <varname>+</varname> preceding any library in the
+ <option>-I</option> of <command>ocamlc</command> or
+ <command>ocamlopt</command> won't be expanded to the local standard
+ library path. You need to specify the path entirely.
+ </para>
+ </warning>
+
+ </section>
+
+</appendix>
+
\ No newline at end of file
diff --git a/policy/chapter-generalities.xml b/policy/chapter-generalities.xml
index abf2f14..bb690ee 100644
--- a/policy/chapter-generalities.xml
+++ b/policy/chapter-generalities.xml
@@ -6,116 +6,119 @@
]>
<chapter id="generalities">
<title>Generalities about &ocaml-name; packages in Debian</title>
-
+
<section id="name-ocaml">
- <title>The Name of the Game</title>
-
- <para>
+ <title>The Name of the Game</title>
+
+ <para>
The correct short name of Objective Caml is
<emphasis>&ocaml-name;</emphasis>. Other
spellings/capitalizations like <quote>ocaml</quote>,
<quote>OCAML</quote>, <quote>O'Caml</quote> should be avoided
when talking about the Objective Caml project, the system, or
the programing language.
- </para>
-
+ </para>
+
</section>
-
+
<section id="bytecode-native">
- <title>Bytecode and Native Code</title>
-
- <section id="bytecode-native-executables">
- <title>Bytecode and Native Code Executables</title>
-
- <para>
- The OCaml compiler can produce two kinds of executables:
- 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
- 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
- provides compilation to native code can be found in the file
- <filename>/usr/lib/ocaml/native-archs</filename>.
- </para>
-
- <para>
- Native executables are in general faster to execute than
- bytecode executables since they are compiled specifically for an
- architecture. Bytecode executables are smaller than native code
- executables. If considering only one process the advantage in
- size is annihilated by the need for the OCaml run time system
- for executing bytecode, however there is an advantage when
- running several bytecode processes in parallel since the runtime
- system can then be shared.
- </para>
-
- <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
- 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.
- </para>
+ <title>Bytecode and Native Code</title>
+
+ <para>
+ The OCaml compilers can produce two kinds of executables:
+ 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
+ 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
+ provides compilation to native code can be found in the file
+ <filename>/usr/lib/ocaml/native-archs</filename>.
+ </para>
+
+ <para>
+ Native executables are in general faster to execute than
+ bytecode executables since they are compiled specifically for an
+ architecture. Bytecode executables are smaller than native code
+ executables. If considering only one process the advantage in
+ size is annihilated by the need for the OCaml run time system
+ for executing bytecode, however there is an advantage when
+ running several bytecode processes in parallel since the runtime
+ system can then be shared.
+ </para>
+
+ <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
+ 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.
+ </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
+ applications, hence libraries should be distributed both in
+ bytecode and native code. For
+ packages containing executables, the rule is:
- <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
- applications, hence libraries should be distributed both in
- bytecode and native code. 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
+ possible, and to bytecode elsewhere. Typical examples are
+ coq, or edos-distcheck. </para></listitem>
- <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
- possible, and to bytecode elsewhere. Typical examples are
- coq, or edos-distcheck. </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> 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>
- </itemizedlist>
- </para>
- </section>
-
- <section>
+ <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> 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>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id="compiler-overview">
+ <title>Overview of the OCaml compilers</title>
+
+ <section id="byte-native-compilers">
<title>Bytecode and Native Code Compilers</title>
<para>
- The <package>ocaml-native-compilers</package> package contains the OCaml
- compiler executables built in native mode: <command>ocamlc.opt</command>,
- which produces bytecode, and <command>ocamlopt.opt</command>, which
- produces native code. Since the OCaml compilers are themselves written in
- OCaml this package exists only on architectures where compilation to
- native code is supported.
+ The <package>ocaml-native-compilers</package> package contains
+ the OCaml compiler executables built in native mode:
+ <command>ocamlc.opt</command>, which produces bytecode, and
+ <command>ocamlopt.opt</command>, which produces native
+ code. Since the OCaml compilers are themselves written in
+ OCaml this package exists only on architectures where
+ compilation to native code is supported.
</para>
<para>
- The <package>ocaml-nox</package> package contains the OCaml compiler
- executables built in bytecode mode: <command>ocamlc</command>, which
- produces bytecode, and on architectures where compilation to native code
- is supported the compiler <command>ocamlopt</command>, which produces
- native code. It is important to understand that on architectures where
- compilation to native code is supported <emphasis>both</emphasis>
- packages contain compilers from OCaml to both bytecode and native code,
- the difference lies in the nature (installation size and execution speed)
- of the compiler executables.
+ The <package>ocaml-nox</package> package contains the OCaml
+ compiler executables built in bytecode mode:
+ <command>ocamlc</command>, which produces bytecode, and on
+ architectures where compilation to native code is supported
+ the compiler <command>ocamlopt</command>, which produces
+ native code. It is important to understand that on
+ architectures where compilation to native code is supported
+ <emphasis>both</emphasis> packages contain compilers from
+ OCaml to both bytecode and native code, the difference lies in
+ the nature (installation size and execution speed) of the
+ compiler executables.
</para>
-
+
<table>
<title>OCaml Compilers</title>
<tgroup cols="3">
@@ -139,35 +142,84 @@
</row>
</tbody>
</tgroup>
- </table>
-
-
+ </table>
<para>
- Compiling with native code versions of the compilers is generally faster
- than with compilers in bytecode. Unfortunately, the
- <package>ocaml-native-compilers</package> 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
- <package>ocaml-best-compilers</package> which itself depends on
- <package>ocaml-native-compilers</package> where available and on
- <package>ocaml</package> elsewhere. Since it is a virtual package, it
- cannot be a versioned dependency. The version dependency should thus be
- carried by the <package>ocaml</package> dependency. Note that dependency
- on <package>ocaml-best-compilers</package> is only necessary for real big
- programs for which compilation takes a lot of resources. For most small
- programs the compilers from the <package>ocaml-nox</package> package are
- perfectly sufficient, and faster to install in a build environment than
- compiler executables in native code.
+ See <xref linkend="bytecode-native"/> on a discussion whether
+ to produce native code or bytecode.
</para>
- </section>
+ </section>
+
+ <section id="files">
+ <title>Files Used and Produced by the OCaml Compilers</title>
+
+ <para>
+ The &ocaml-name; compiler can produce or use the following kind of files:
+ <itemizedlist>
+ <listitem>
+ <para>
+ bytecode executables (they can be recognized 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
+ <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.
+ </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>native plugin object files (<filename>*.cmxs</filename>)</para>
+ </listitem>
+ <listitem>
+ <para>
+ configuration files for handling libraries with &ocamlfind;
+ (<filename>META</filename>)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
</section>
<section>
- <title>OCaml in Debian</title>
+ <title>Building packages using OCaml</title>
<section>
- <title>findlib and ocamlfind</title>
+ <title>Findlib and ocamlfind</title>
<para>&ocaml-force; has chosen to fully support
<application>findlib</application> library. This is a suite of tools
@@ -184,7 +236,7 @@
</section>
<section>
- <title>Packages for OCaml</title>
+ <title>The OCaml system in Debian</title>
<para id="package-type">
OCaml packages can be splitted in three categories in Debian:
@@ -213,11 +265,11 @@
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 don't need X (i.e., for programs that don't use the
+ 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 OCaml is split:
+ which the OCaml system is organized:
<orderedlist>
<listitem>
@@ -314,180 +366,97 @@
<package>ocaml-base-nox-&ocaml-version;</package>.
</para>
</section>
-
+
<section>
- <title>OCaml Location</title>
- <para>
- The root of all installed OCaml libraries is the <emphasis>OCaml standard
- library directory</emphasis>, which is &ocaml-sys-dir;. This location can
- be obtained from the OCaml compiler by invoking it as <userinput>ocamlc
- -where</userinput>.
- </para>
- </section>
-
- <section id="doc-base">
- <title>Documentation</title>
- <para>
- 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;.
- </para>
- </section>
-
- <section id="archive-section">
- <title>Archive Section</title>
- <para>
- Devel and runtime packages should have their section set to <code>ocaml</code>.
- </para>
-
+ <title>Choosing the right build dependencies</title>
+
<para>
- Binary packages that are intended for OCaml
- <emphasis>development</emphasis>, as opposed to more general
- tools that just happen to be implemented in OCaml, could have
- their Section set to <code>ocaml</code>.
+ Compiling with native code versions of the compilers is generally faster
+ than with compilers in bytecode. Unfortunately, the
+ <package>ocaml-native-compilers</package> 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
+ <package>ocaml-best-compilers</package> which itself depends on
+ <package>ocaml-native-compilers</package> where available and on
+ <package>ocaml</package> elsewhere. Since it is a virtual package, it
+ cannot be a versioned dependency. The version dependency should thus be
+ carried by the <package>ocaml</package> dependency. Note that dependency
+ on <package>ocaml-best-compilers</package> is only necessary for real big
+ programs for which compilation takes a lot of resources. For most small
+ programs the compilers from the <package>ocaml-nox</package> package are
+ perfectly sufficient, and faster to install in a build environment than
+ compiler executables in native code.
</para>
</section>
-
+
<section id="dh-ocaml">
- <title>dh_ocaml</title>
- <para>&ocaml-force; has designed a system to compute dependencies between &ocaml-name;
- packages and ensure type-safe linking using it. Details of this work can be found
- <ulink url="http://upsilon.cc/~zack/stuff/ocaml-debian-deps.pdf">here</ulink>. It
- imposes to use new substitution variables in <filename>debian/control</filename>:
+ <title>Dh_ocaml</title>
+ <para>&ocaml-force; has created a system to compute dependencies
+ between &ocaml-name; packages and to ensure type-safe linking. It
+ requires to use new substitution variables in
+ <filename>debian/control</filename>:
</para>
-
+
<itemizedlist>
<listitem>
- <para>You must use <code>${ocaml:Depends}</code> substitution variables
- in field <code>Depends</code>.</para>
+ <para>Use the <code>${ocaml:Depends}</code> substitution variable
+ in the field <code>Depends</code>.</para>
</listitem>
<listitem>
- <para>You must add a field <code>Provides: ${ocaml:Provides}</code> on
- devel and runtime packages.</para>
+ <para>Add a field <code>Provides: ${ocaml:Provides}</code> in
+ development and runtime packages.</para>
</listitem>
</itemizedlist>
+ <para>
+ More detailed information about this work can be found <ulink
+ url="http://upsilon.cc/~zack/stuff/ocaml-debian-deps.pdf">here</ulink>.
+ </para>
</section>
+</section>
- </section>
-
- <section id="files">
- <title>Files Used and Produced by the OCaml Compiler</title>
-
+<section>
+ <title>Integrating OCaml packages in Debian</title>
+
+ <section>
+ <title>Location of OCaml directories</title>
+ <para>
+ The root of all installed OCaml libraries is the
+ <emphasis>OCaml standard library directory</emphasis>, which
+ is &ocaml-sys-dir;. This location can be obtained from the
+ OCaml compiler by invoking it as <userinput>ocamlc
+ -where</userinput>.
+ </para>
+ </section>
+
+ <section id="archive-section">
+ <title>Archive Section</title>
<para>
- The &ocaml-name; compiler can produce or use the following kind of files:
- <itemizedlist>
- <listitem>
- <para>
- bytecode executables (they can be recognized 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 <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. <command>strip</command> 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>native plugin object files (<filename>*.cmxs</filename>)</para>
- </listitem>
- <listitem>
- <para>
- configuration files for handling libraries with &ocamlfind;
- (<filename>META</filename>)
- </para>
- </listitem>
- </itemizedlist>
+ Packages intended for the development of OCaml programs or
+ packages, as well as packages necessary for the execution of
+ OCaml code (like runtime systems or libraries) should have
+ their section set to <code>ocaml</code>.
</para>
- </section>
-
- <section id="liblocal-path">
- <title>Locally Installing OCaml Programs and Libraries</title>
-
+
<para>
- Locally installed files are files that are installed directly by
- the system administrator, in contrast to files installed through Debian
- packages. 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, a local system
- administrator should follow these 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>), native plugin object files
- (<filename>*.cmxs</filename>), static libraries
- (<filename>*.a</filename>) and <filename>META</filename>
- files.
- </para>
- </listitem>
- </itemizedlist>
+ End user applications that are not specifically aiming at
+ 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
+ not specific to OCaml development go into section
+ <code>devel</code> (example: headache).
</para>
+ </section>
+ <section id="doc-base">
+ <title>Documentation</title>
<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.
+ 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;.
</para>
-
- <warning>
- <para>
- The <varname>+</varname> preceding any library in the
- <option>-I</option> of <command>ocamlc</command> or
- <command>ocamlopt</command> won't be expanded to the local standard
- library path. You need to specify the path entirely.
- </para>
- </warning>
-
+ </section>
</section>
-
</chapter>
diff --git a/policy/ocaml_packaging_policy.xml b/policy/ocaml_packaging_policy.xml
index 962b477..a3ac419 100644
--- a/policy/ocaml_packaging_policy.xml
+++ b/policy/ocaml_packaging_policy.xml
@@ -31,4 +31,8 @@
href="chapter-libpack.xml"
xmlns:xi="http://www.w3.org/2003/XInclude"/>
+ <xi:include
+ href="appendix-local.xml"
+ xmlns:xi="http://www.w3.org/2003/XInclude"/>
+
</book>
--
dh-ocaml packaging
More information about the Pkg-ocaml-maint-commits
mailing list