[Pkg-ocaml-maint-commits] [SCM] dh-ocaml packaging branch, policy-update, updated. debian/0.9.5-10-ga2392f0
Ralf Treinen (none)
treinen at debian.
Sat Aug 7 22:05:15 UTC 2010
The following commit has been merged in the policy-update branch:
commit a2392f00c72f86a0790ff548ec46c1c91c66774c
Author: Ralf Treinen <treinen at debian.(none)>
Date: Sat Aug 7 23:03:39 2010 +0100
start to streamline the sectoin on bytecode and native code
diff --git a/policy/chapter-generalities.xml b/policy/chapter-generalities.xml
index a29efb5..02b667a 100644
--- a/policy/chapter-generalities.xml
+++ b/policy/chapter-generalities.xml
@@ -11,14 +11,15 @@
<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.
+ 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>
- </section>
+
+ </section>
<section id="bytecode-native">
<title>Bytecode and Native Code</title>
@@ -27,38 +28,72 @@
<title>Bytecode and Native Code Executables</title>
<para>
- The OCaml compiler can produce two kinds of executables: bytecode and
- native. Native executables, produced by the compiler &ocamlopt;, are
- generally faster than bytecode executables since they are compiled
- specifically for an architecture. Bytecode executables, produced by the
- compiler &ocamlc;, have the advantage of being portable, which means that
- a bytecode executable can be run on any architecture without having to be
- recompiled. 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. It
- should be noted that OCaml compilers to native code are not provided for
- every architecture. Only the following ones are supported:
- &supported-archs;.
+ 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
+ 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
+ provides compilation to native code can be found in the file
+ <filename>/usr/lib/ocaml/native-archs</filename>.
</para>
-
+
<para>
- 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. If the program is known to require a lot of CPU power, only
- the native version should be provided where possible and bytecode version
- otherwise. For small utilities that doesn't require to be fast, only
- bytecode version should be provided.
+ 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
+ Architecure=all, which reduces archive space and autobuilder load.
+ It also reduces download and installation size for users in
+ case they install several byecode 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:
+
+ <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 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>
<title>Bytecode and Native Code Compilers</title>
@@ -133,11 +168,6 @@
<section>
<title>OCaml in Debian</title>
- <para>
- At the time of this writing, the latest version of OCaml in
- Debian is &ocaml-version;.
- </para>
-
<section>
<title>findlib and ocamlfind</title>
diff --git a/policy/chapter-progpack.xml b/policy/chapter-progpack.xml
index e437870..e395725 100644
--- a/policy/chapter-progpack.xml
+++ b/policy/chapter-progpack.xml
@@ -128,5 +128,18 @@
availability of &ocamlopt; or <command>ocamlopt.opt</command> when
building.
</para>
+
+ <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>
+
</section>
</chapter>
diff --git a/policy/included.ent b/policy/included.ent
index 5c4c7f9..32ab4f2 100644
--- a/policy/included.ent
+++ b/policy/included.ent
@@ -1,5 +1,5 @@
<!ENTITY doc-version "0.8.0">
-<!ENTITY ocaml-version "3.11.2">
+<!ENTITY ocaml-version "<nonterminal>ocaml-version</nonterminal>">
<!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/scratch.xml b/policy/scratch.xml
index 8a79c32..78fc6ff 100644
--- a/policy/scratch.xml
+++ b/policy/scratch.xml
@@ -1,3 +1,11 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"/usr/share/sgml/docbook/dtd/xml/4.4/docbookx.dtd" [
+<!ENTITY % included SYSTEM "included.ent">
+%included;
+]>
+<chapter id="scratch">
+ <title>Scratch</title>
<!-- Parts that have been removed from the doc, maybe we can add it back -->
@@ -54,3 +62,4 @@
</programlisting>
</para>
+</chapter>
--
dh-ocaml packaging
More information about the Pkg-ocaml-maint-commits
mailing list