[Pkg-ocaml-maint-commits] [SCM] dh-ocaml packaging branch, policy-update, updated. debian/0.9.5-11-g7805bab
Ralf Treinen (none)
treinen at debian.
Wed Aug 11 14:15:53 UTC 2010
The following commit has been merged in the policy-update branch:
commit 7805bab51277c36d0a2350b07563d50920d17127
Author: Ralf Treinen <treinen at debian.(none)>
Date: Wed Aug 11 15:14:56 2010 +0100
proofreading so far
diff --git a/policy/chapter-generalities.xml b/policy/chapter-generalities.xml
index 02b667a..abf2f14 100644
--- a/policy/chapter-generalities.xml
+++ b/policy/chapter-generalities.xml
@@ -24,20 +24,20 @@
<section id="bytecode-native">
<title>Bytecode and Native Code</title>
- <section>
+ <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 excutables
- produced for a particular cpu architecture, while bytecode
- excutables are written in a language which can only be run on a
+ 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
- whcich the currently installed version of the ocaml system
+ 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>
@@ -57,39 +57,37 @@
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
+ interpreter is available. For Debian, this has the advantage
that packages containing only bytecode executables have
- Architecure=all, which reduces archive space and autobuilder load.
+ Architecture=all, which reduces archive space and auto-builder load.
It also reduces download and installation size for users in
- case they install several byecode packages.
+ 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 (see ....). For packages containing executables,
- the rule is:
+ 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 excutables in the package should be compiled to native code.
- Typical examples are coq, or edos-distcheck.
- </para></listitem>
+ <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> 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>
+ <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>
diff --git a/policy/chapter-progpack.xml b/policy/chapter-progpack.xml
index e395725..50b9f69 100644
--- a/policy/chapter-progpack.xml
+++ b/policy/chapter-progpack.xml
@@ -6,108 +6,109 @@
]>
<chapter id="progpack">
<title>Packaging OCaml Programs</title>
-
+
<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
- package without modifications.
- </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.
- </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
- are simple binary package, as explained <ulink url="#package-type">
- previously</ulink>.
- </para>
+ <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
+ package without modifications.
+ </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.
+ </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
+ are simple binary package, as explained <ulink url="#package-type">
+ previously</ulink>.
+ </para>
</section>
-
+
<section id="bytecode-prog">
- <title>Bytecode Packages</title>
- <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 field set to <code>all</code>.
- </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.
- </para>
-
- <para>
- A bytecode package must build-depend-indep on &ocaml-nox-pkg; (or
- &ocaml-pkg; if the program either uses the <code>Graphics</code> or the
- <code>LablTk</code> module).
- </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>.
- </para>
-
- <para>
- Bytecode programs should not be compiled for debugging, i.e. they should not
- be compiled passing the <option>-g</option> option to &ocamlc;.
- </para>
-
+ <title>Bytecode Packages</title>
+ <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
+ field set to <code>all</code>.
+ </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.
+ </para>
+
+ <para>
+ A bytecode package must build-depend-indep on &ocaml-nox-pkg; (or
+ &ocaml-pkg; if the program either uses the <code>Graphics</code> or the
+ <code>LablTk</code> module).
+ </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>.
+ </para>
+
+ <para>
+ Bytecode programs should not be compiled for debugging,
+ i.e. they should not be compiled passing the <option>-g</option>
+ option to &ocamlc;.
+ </para>
</section>
- <section id="bytecode-native-prog">
- <title>Bytecode and native versions of programs</title>
+ <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.
</para>
-
+
<para>
The <filename>debian/rules</filename> should build the native code
executable if supported on the architecture it is built on, and fall
@@ -122,13 +123,16 @@
architecture dependent package providing the native code only for native
architecture supporting it.
</para>
-
+
<para>
It is safe to consider that detection of native architecture means
availability of &ocamlopt; or <command>ocamlopt.opt</command> when
building.
</para>
-
+ </section>
+
+ <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
@@ -140,6 +144,5 @@
really useful, there must be a difference in term of features between the
two version.
</para>
-
</section>
</chapter>
--
dh-ocaml packaging
More information about the Pkg-ocaml-maint-commits
mailing list