[Pkg-ocaml-maint-commits] [SCM] dh-ocaml packaging branch, policy-update, updated. debian/0.9.5-14-g51fef4e
Ralf Treinen
treinen at free.fr
Sun Aug 15 20:25:43 UTC 2010
The following commit has been merged in the policy-update branch:
commit 51fef4ed98b508fea4d1083d7e559017710d1d16
Author: Ralf Treinen <treinen at free.fr>
Date: Sun Aug 15 22:23:20 2010 +0200
small corrections, typos in the policy
start to fill in stuff in reference about dh and DIY rules
diff --git a/policy/appendix-local.xml b/policy/appendix-local.xml
index 98fbb47..ca3ca99 100644
--- a/policy/appendix-local.xml
+++ b/policy/appendix-local.xml
@@ -9,7 +9,7 @@
<title>Appendix</title>
<section id="liblocal-path">
- <title>Locally Installing OCaml Programs and Libraries</title>
+ <title>Locally installing OCaml programs and libraries</title>
<para>
Locally installed files are files that are installed directly by
diff --git a/policy/chapter-generalities.xml b/policy/chapter-generalities.xml
index d6fcfce..7a5edc2 100644
--- a/policy/chapter-generalities.xml
+++ b/policy/chapter-generalities.xml
@@ -8,7 +8,7 @@
<title>Generalities about &ocaml-name; packages in Debian</title>
<section id="name-ocaml">
- <title>The Name of the Game</title>
+ <title>The name of the game</title>
<para>
The correct short name of Objective Caml is
@@ -22,7 +22,7 @@
</section>
<section id="bytecode-native">
- <title>Bytecode and Native Code</title>
+ <title>Bytecode and native code</title>
<para>
The OCaml compilers can produce two kinds of executables:
@@ -99,7 +99,7 @@
<title>Overview of the OCaml compilers</title>
<section id="byte-native-compilers">
- <title>Bytecode and Native Code Compilers</title>
+ <title>Bytecode and native code compilers</title>
<para>
The <package>ocaml-native-compilers</package> package contains
@@ -126,7 +126,7 @@
</para>
<table>
- <title>OCaml Compilers</title>
+ <title>OCaml compilers</title>
<tgroup cols="3">
<thead>
<row>
@@ -156,7 +156,7 @@
</section>
<section id="files">
- <title>Files Used and Produced by the OCaml Compilers</title>
+ <title>Files used and produced by the OCaml compilers</title>
<para>
The &ocaml-name; compiler can produce or use the following kind of files:
@@ -255,13 +255,13 @@
</para>
</listitem>
<listitem>
- <para>Runtime package contain OCaml objects necessary to run
+ <para>Runtime packages 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 contain everything that does
+ <para>Simple binary packages contain everything that does
not fall into the two former categories. This includes
bytecode and native executable of application programs,
documentation, etc.
@@ -381,7 +381,7 @@
</para>
</section>
- <section>
+ <section id="general:build-dependencies">
<title>Choosing the right build dependencies</title>
<para>
@@ -403,6 +403,39 @@
compiler executables in native code.
</para>
</section>
+
+ <section id="general:dependencies">
+ <title>Putting the right binary dependencies</title>
+
+ <para>
+ Bytecode is specific to an upstream version of the OCaml
+ system. Therefore, any package containing bytecode has to depend
+ directly or indirectly on the packages providing the OCaml
+ runtime system in precisely the version for which it was
+ compiled (for instance,
+ <package>ocaml-base-&ocaml-version;</package>.) This is in
+ particular the case for bytecode programs, but it is also the
+ case for native code programs on the architectures on which
+ there is no native code OCaml compiler, and on which the program
+ will be actually compiled to bytecode (see the <ulink
+ url="#native-prog">section on packaging native code
+ programs</ulink>). The exact dependencies of libraries packages
+ are discussed in the <ulink url="#libpack">chapter on library
+ packaging</ulink>.
+ </para>
+
+ <para>
+ In order for a package to be easily rebuild, or even binNMUed,
+ in case of a transition from one OCaml version to another, these
+ dependencies must not be hardcoded in
+ <filename>debian/control</filename>. Instead, substitution
+ variables must be used which are instantiated from the
+ <filename>debian/rules</filename> file. See the discussion on
+ build systems in the Debian OCaml Developers Reference for a
+ discussion how this can be achieved.
+ </para>
+
+ </section>
<section id="dh-ocaml">
<title>Dh_ocaml</title>
@@ -444,7 +477,7 @@
</section>
<section id="archive-section">
- <title>Archive Section</title>
+ <title>Debian archive section</title>
<para>
Packages intended for the development of OCaml programs or
packages, as well as packages necessary for the execution of
diff --git a/policy/chapter-libpack.xml b/policy/chapter-libpack.xml
index 7972c99..3a69ced 100644
--- a/policy/chapter-libpack.xml
+++ b/policy/chapter-libpack.xml
@@ -8,7 +8,7 @@
<title>Packaging OCaml libraries</title>
<section>
- <title>Creating Packages for OCaml Libraries</title>
+ <title>Creating packages for OCaml libraries</title>
<para>
A package which provides an OCaml library called <filename>xxx</filename> should be split as follows:
@@ -50,7 +50,7 @@
<code>${binary:Version}</code> substitution variable.
<example>
- <title>Dependency from a -dev package to its companion share
+ <title>Dependency from a -dev package to its companion shared
library stub package (if any), from the
<application>pcre-ocaml</application> package</title>
<programlisting>
@@ -209,17 +209,19 @@
directory. </para>
<para>
- 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
- <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>
+ 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 the upstream
+ authors in order to have it included in future versions of the
+ upstream source. For more information about
+ <filename>META</filename> files see the <ulink
+ url="http://www.ocaml-programming.de/packages/documentation/findlib/">Findlib
+ manual</ulink>, at the several META files provided by other
+ packages (e.g. <filename>lablgtk</filename>,
+ <filename>pxp</filename>, <filename>pcre</filename>,
+ <filename>netstring</filename>, <filename>lablgl</filename>,
+ ...) or ask on the debian-ocaml-maint mailing list for help.
+ </para>
</section>
<!--
@@ -291,7 +293,7 @@
</para>
<para>
- If a package contains at the same time syntax extension and library then it
+ If a package contains at the same time syntax extension and libraries then it
is up to the maintainer to choose the most relevant name for the package.
Whatever the name chosen for the package, the other name should be a
<varname>Provide</varname> of the package.
@@ -331,7 +333,7 @@
<para>
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 to the most complex one. At least, they should all be readable with
a simple text editor. Specific and &ocamldoc; generated documentations
should be provided in HTML format. There are also at least two specific
&ocaml-name; browsers: <application>docbrowse</application> shipped with
diff --git a/policy/chapter-progpack.xml b/policy/chapter-progpack.xml
index b83c424..19e29af 100644
--- a/policy/chapter-progpack.xml
+++ b/policy/chapter-progpack.xml
@@ -5,10 +5,10 @@
%included;
]>
<chapter id="progpack">
- <title>Packaging OCaml Programs</title>
+ <title>Packaging OCaml programs</title>
<section>
- <title>Creating Packages for OCaml Programs</title>
+ <title>Creating packages for OCaml programs</title>
<para>
The source package should, if possible, use the name of the upstream
@@ -31,7 +31,7 @@
</section>
<section id="bytecode-prog">
- <title>Bytecode Packages</title>
+ <title>Bytecode packages</title>
<para>
A bytecode package has all its binaries compiled into
bytecode. It depends on a package containing the OCaml runtime
@@ -40,28 +40,26 @@
</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.
+ All bytecode executables should be linked dynamically against
+ the shared libraries for C bindings, to not bloat the
+ archive. That said, 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. 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 it. Typically, it should depends on
+ A bytecode package must depend on the runtime package
+ that is required to run it. Typically, it should depend 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.
+ runtime package <package>libXXX-ocaml</package> (see <ulink
+ url="#general:dependencies">the section on binary
+ dependencies</ulink>).
</para>
<para>
@@ -71,20 +69,21 @@
</para>
<para>
- Bytecode programs which are compiled by <userinput>ocamlc -custom</userinput>
- must not be stripped. In particular, their package should be excluded from
- the <command>dh_strip</command> script. When compiled this way, an ELF
- executable is generated containing the ocaml interpreter, and the bytecode
- of the program in a section which is removed when the program is stripped.
- For more information, see the bug
- <ulink url="http://bugs.debian.org/256900">256900</ulink>. <emphasis>Custom
- bytecode executable is a deprecated feature of OCaml -- for now they still
- exist but should be avoided</emphasis>.
+ Bytecode programs which are compiled by <userinput>ocamlc
+ -custom</userinput> must not be stripped. In particular, their
+ package should be excluded from the <command>dh_strip</command>
+ script. When compiled this way, an ELF executable is generated
+ containing the ocaml interpreter, and the bytecode of the
+ program in a section which is removed when the program is
+ stripped. For more information, see the bug <ulink
+ url="http://bugs.debian.org/256900">256900</ulink>. <emphasis>Custom
+ bytecode executable is a deprecated feature of OCaml -- for now
+ they still exist but should be avoided</emphasis>.
</para>
<para>
Bytecode programs should not be compiled for debugging,
- i.e. they should not be compiled passing the <option>-g</option>
+ i.e. they should not be compiled using the <option>-g</option>
option to &ocamlc;.
</para>
</section>
@@ -92,18 +91,19 @@
<section id="native-prog">
<title>Native versions of programs</title>
<para>
- 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.
+ Native OCaml compilers are not available on all
+ architecures. 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
+ The <filename>debian/rules</filename> file 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.
+ native code compiler is available. As a consequence, the rules of
+ <xref linkend="bytecode-prog"/> also apply here.
</para>
<para>
@@ -122,9 +122,8 @@
<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>.
+ Please consult the rules of <xref linkend="bytecode-prog"/>
+ and <xref linkend="native-prog"/>.
</para>
</section>
</chapter>
diff --git a/policy/copyright.xml b/policy/copyright.xml
index 1d30c5d..3ad7403 100644
--- a/policy/copyright.xml
+++ b/policy/copyright.xml
@@ -6,11 +6,11 @@
]>
<copyright>
<year>2002-2010</year>
+ <holder>Mehdi Dogguy</holder>
+ <holder>Stephane Glondu</holder>
<holder>Sylvain Le Gall</holder>
<holder>Sven Luther</holder>
<holder>Samuel Mimram</holder>
<holder>Ralf Treinen</holder>
<holder>Stefano Zacchiroli</holder>
- <holder>Mehdi Dogguy</holder>
- <holder>Stephane Glondu</holder>
</copyright>
diff --git a/policy/legal.xml b/policy/legal.xml
index 30e6f6a..6388c24 100644
--- a/policy/legal.xml
+++ b/policy/legal.xml
@@ -19,7 +19,7 @@
</para>
<para>
A copy of the GNU General Public License is available as <ulink
- url="file:///usr/share/common-licenses/GPL"><filename>/usr/share/common-licenses/GPL</filename></ulink>
+ url="file:///usr/share/common-licenses/GPL-3"><filename>/usr/share/common-licenses/GPL-3</filename></ulink>
on Debian GNU/Linux systems or on the World Wide Web at <ulink
url="http://www.gnu.org/copyleft/gpl.html">The GNU Public
Licence</ulink>.
diff --git a/policy/ocaml_packaging_reference.xml b/policy/ocaml_packaging_reference.xml
index ff2ebd9..78fe188 100644
--- a/policy/ocaml_packaging_reference.xml
+++ b/policy/ocaml_packaging_reference.xml
@@ -24,7 +24,7 @@
xmlns:xi="http://www.w3.org/2003/XInclude"/>
<chapter>
- <title>Build system</title>
+ <title>Build systems</title>
<xi:include
href="reference-diy.xml"
xmlns:xi="http://www.w3.org/2003/XInclude"/>
@@ -40,7 +40,7 @@
<chapter>
- <title>VCS</title>
+ <title>Using a Version Control System</title>
<xi:include
href="reference-git.xml"
xmlns:xi="http://www.w3.org/2003/XInclude"/>
@@ -51,6 +51,10 @@
</chapter>
<xi:include
+ href="reference-transitions.xml"
+ xmlns:xi="http://www.w3.org/2003/XInclude"/>
+
+ <xi:include
href="reference-resources.xml"
xmlns:xi="http://www.w3.org/2003/XInclude"/>
diff --git a/policy/reference-cdbs.xml b/policy/reference-cdbs.xml
index d88f143..97a3236 100644
--- a/policy/reference-cdbs.xml
+++ b/policy/reference-cdbs.xml
@@ -5,7 +5,7 @@
%included;
]>
<section>
- <title>The OCaml CDBS class</title>
+ <title>Building packages with CDBS and the OCaml class</title>
<para>
To help maintainers of OCaml-related packages in adhering to this policy, a
class for the <ulink url="http://build-common.alioth.debian.org/">CDBS
diff --git a/policy/reference-dh.xml b/policy/reference-dh.xml
index 40682dc..1dd93ba 100644
--- a/policy/reference-dh.xml
+++ b/policy/reference-dh.xml
@@ -5,9 +5,28 @@
%included;
]>
<section>
- <title>Building a package with dh (debhelper > 7)</title>
+ <title>Building packages with dh (debhelper > 7)</title>
- <para>TODO</para>
+ <para>Debhelper provides since version 7 the <command>dh</command>
+ tool which automatizes in simply and standard cases completely the
+ tasks to be done by <filename>debian/rules</filename>, and which
+ provides for various means to adapt to complex or non-standard cases
+ (see <command>dh(1)</command>). The
+ <package>dh-ocaml</package> package provides since version
+ 0.9.0 a <command>ocaml</command> addon to <command>dh</command>.</para>
+
+ <example>
+ <title>A <filename>debian/rules</filename> file using <command>dh</command>
+ </title>
+ <programlisting>
+#!/usr/bin/make -f
+%:
+ dh $@ --with ocaml
+ </programlisting>
+ <para>
+ This package must build-depend on <code>dh-ocaml (>= 0.9.0)</code>.
+ </para>
+ </example>
</section>
diff --git a/policy/reference-diy.xml b/policy/reference-diy.xml
index f11ba9d..7ad6d7e 100644
--- a/policy/reference-diy.xml
+++ b/policy/reference-diy.xml
@@ -5,9 +5,73 @@
%included;
]>
<section>
- <title>Do-it-yourself or building a package with just debhelper</title>
+ <title>Building packages with debhelper tools and dh-ocaml</title>
- <para>TODO</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 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>
+
+ <para>
+ In the case where there is only one package, which provides
+ either a native version where available or a bytecode version
+ otherwise, the dependency on
+ <varname>ocaml-base-nox-&ocaml-version;</varname> should be
+ added only when the package is built in native mode. For
+ example, the <filename>debian/control</filename> of
+ <filename>approx</filename> contains:
+ <programlisting>
+ Package: approx
+ Architecture: any
+ Depends: ${shlibs:Depends}, ${F:OCamlRun}, adduser, bzip2, curl
+ </programlisting>
+ and the corresponding <filename>debian/rules</filename> contains:
+ <programlisting>
+ OCAMLABI = $(shell ocamlc -version)
+ BYTECODE = $(shell [ -x /usr/bin/ocamlopt ] || echo yes)
+ OCAMLRUN = $(if $(BYTECODE),ocaml-base-nox-$(OCAMLABI))
+ ...
+ binary-arch:
+ ...
+ dh_gencontrol -- -VF:OCamlRun="$(OCAMLRUN)"
+ </programlisting>
+ </para>
+
+ <para>TODO: section should be simlified by using dh-ocaml</para>
</section>
--
dh-ocaml packaging
More information about the Pkg-ocaml-maint-commits
mailing list