[Pkg-ocaml-maint-commits] r2791 - in /trunk/policy/trunk:
appendix-resources.xml
chapter-generalities.xml chapter-libpack.xml chapter-progpack.xml
smimram at users.alioth.debian.org
smimram at users.alioth.debian.org
Sat May 27 11:25:10 UTC 2006
Author: smimram
Date: Sat May 27 11:25:09 2006
New Revision: 2791
URL: http://svn.debian.org/wsvn/?sc=1&rev=2791
Log:
Some more doc.
Modified:
trunk/policy/trunk/appendix-resources.xml
trunk/policy/trunk/chapter-generalities.xml
trunk/policy/trunk/chapter-libpack.xml
trunk/policy/trunk/chapter-progpack.xml
Modified: trunk/policy/trunk/appendix-resources.xml
URL: http://svn.debian.org/wsvn/trunk/policy/trunk/appendix-resources.xml?rev=2791&op=diff
==============================================================================
--- trunk/policy/trunk/appendix-resources.xml (original)
+++ trunk/policy/trunk/appendix-resources.xml Sat May 27 11:25:09 2006
@@ -1,6 +1,22 @@
+<!--
<section>
<title>Where to find the &ocaml-force;</title>
<para>
blah
</para>
</section>
+-->
+<para>
+ <itemizedlist>
+ <listitem><para>The &ocaml-force;'s website: <ulink url="http://pkg-ocaml-maint.alioth.debian.org/">http://pkg-ocaml-maint.alioth.debian.org/</ulink></para></listitem>
+ <listitem><para>The &ocaml-force;'s mailing list: <ulink url="mailto:debian-ocaml-maint at lists.debian.org">debian-ocaml-maint at lists.debian.org</ulink></para></listitem>
+ <listitem><para></para></listitem>
+ <listitem><para></para></listitem>
+ <listitem><para></para></listitem>
+ <listitem><para></para></listitem>
+ <listitem><para></para></listitem>
+ <listitem><para></para></listitem>
+ <listitem><para></para></listitem>
+ <listitem><para></para></listitem>
+ </itemizedlist>
+</para>
Modified: trunk/policy/trunk/chapter-generalities.xml
URL: http://svn.debian.org/wsvn/trunk/policy/trunk/chapter-generalities.xml?rev=2791&op=diff
==============================================================================
--- trunk/policy/trunk/chapter-generalities.xml (original)
+++ trunk/policy/trunk/chapter-generalities.xml Sat May 27 11:25:09 2006
@@ -5,64 +5,64 @@
</para>
<para>
- The <filename>ocaml</filename> 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 <filename>-nox</filename> packages contain libraries which don't need X (i.e. for the programs which don't use the <code>Graphics</code> or <code>LablTk</code> modules) in order to avoid too big dependencies for users who don't have and X server installed.
+ The <filename>ocaml</filename> 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 <filename>-nox</filename> packages contain libraries which don't need X (i.e. for the programs which don't use the <code>Graphics</code> or <code>LablTk</code> modules) in order to avoid too big dependencies for users who don't have an X server installed.
<itemizedlist>
<listitem>
<para>
- The <filename>ocaml</filename> and <filename>ocaml-nox</filename> package contain the compiler and its libraries.
+ The <filename>ocaml</filename> and <filename>ocaml-nox</filename> packages contain the compiler and its libraries.
</para>
</listitem>
<listitem>
<para>
- The <filename>ocaml-native-compilers</filename> contains the OCaml compiler built in native mode.
+ The <filename>ocaml-native-compilers</filename> package contains the OCaml compiler built in native mode (<filename>ocamlc.opt</filename> and <filename>ocamlopt.opt</filename>).
</para>
</listitem>
<listitem>
<para>
- The <filename>ocaml-base</filename> and <filename>ocaml-base-nox</filename> packages contain the runtime libraries needed by bytecode programs compiled with OCaml (in particular it contains the <filename>ocamlrun</filename> program).
+ The <filename>ocaml-base</filename> and <filename>ocaml-base-nox</filename> packages contain the runtime libraries needed by bytecode programs compiled with OCaml (in particular, the package <filename>ocaml-base-nox</filename> contains the <filename>ocamlrun</filename> program).
</para>
</listitem>
<listitem>
<para>
- The <filename>ocaml-interp</filename> contains the interactive command-line interpreter.
+ The <filename>ocaml-interp</filename> package contains the interactive command-line interpreter (<filename>ocaml</filename>).
</para>
</listitem>
<listitem>
<para>
- The <filename>ocaml-mode</filename> contains the OCaml emacs mode (the one provided with OCaml, not the tuareg mode).
+ The <filename>ocaml-mode</filename> package contains the OCaml emacs mode (the one provided with OCaml, not the tuareg mode which is in the package <filename>tuareg-mode</filename>).
</para>
</listitem>
<listitem>
<para>
- The <filename>ocaml-source</filename> contains the sources of the OCaml compiler.
+ The <filename>ocaml-source</filename> package contains the sources of the OCaml compiler.
</para>
</listitem>
<listitem>
<para>
- The <filename>ocaml-compiler-libs</filename> contains some internal libraries of the OCaml compiler (it is needed only in very rare cases).
+ The <filename>ocaml-compiler-libs</filename> package contains some internal libraries of the OCaml compiler (it is needed only in very rare cases).
</para>
</listitem>
</itemizedlist>
</para>
<para>
- Since the libraries produced by OCaml are binary incompatible when compiled with two different releases of OCaml, versionned virtual packages are provided: <filename>ocaml-&ocaml-version;</filename>, <filename>ocaml-nox-&ocaml-version;</filename>, <filename>ocaml-base-&ocaml-version;</filename>, <filename>ocaml-base-nox-&ocaml-version;</filename>.
+ Since the libraries produced by OCaml are binary incompatible when compiled with two different releases of OCaml, versionned virtual packages are also provided: <filename>ocaml-&ocaml-version;</filename>, <filename>ocaml-nox-&ocaml-version;</filename>, <filename>ocaml-base-&ocaml-version;</filename>, <filename>ocaml-base-nox-&ocaml-version;</filename>.
</para>
</section>
-<section>
- <title>Native and bytecode programs</title>
+<section id="bytecode-native">
+ <title>Bytecode and native programs</title>
<para>
The OCaml compiler can produce two kinds of executables: bytecode and native. The native executables (compiled with <filename>ocamlopt</filename>) are generally faster since they are compiled specifically for an achitecture. The bytecode executables (compiled with <filename>ocamlc</filename>) have the advantage of being portable, which means that a bytecode program can be run on any achitecture without needing to be rebuilt. It should be noted that native OCaml compilers are not provided for every achitecture. Only the following are suported: alpha, amd64, arm, i386, ia64, kfreebsd-i386, powerpc and sparc.
</para>
<para>
- Package providing both native and bytecode versions of a program <filename>prog</filename> usually name them respectively <filename>prog.opt</filename> and <filename>prog.byte</filename> and provide a symbolic link <filename>prog</filename> to the best available version (generally <filename>prog.opt</filename>).
+ Packages providing both native and bytecode versions of a program <filename>prog</filename> usually name them respectively <filename>prog.opt</filename> and <filename>prog.byte</filename> and provide a symbolic link <filename>prog</filename> to the best available version (generally <filename>prog.opt</filename>).
</para>
<para>
- The <filename>ocaml-native-compilers</filename> package contains the OCaml compiler built in native mode (<filename>ocamlc.opt</filename> and <filename>ocamlopt.opt</filename>). Compiling with this version of the compiler is generally faster but, as explained before, the <filename>ocaml-native-compilers</filename> package is not available on every architecture. In order to build big programs and benefit from this natively built compiler, packages should depend on <filename>ocaml-best-compilers</filename> which depends on <filename>ocaml-native-compilers</filename> where available and on <filename>ocaml</filename> elsewhere.
+ The <filename>ocaml-native-compilers</filename> package contains the OCaml compiler built in native mode (<filename>ocamlc.opt</filename> and <filename>ocamlopt.opt</filename>). Compiling with this version of the compiler is generally faster but, as explained before, the <filename>ocaml-native-compilers</filename> package is not available on every architecture. Packages should therefore never depend directly on this package. In order to build big programs and benefit from this natively built compiler, packages should depend on <filename>ocaml-best-compilers</filename> which itself depends on <filename>ocaml-native-compilers</filename> where available and on <filename>ocaml</filename> elsewhere. Since it is a virtual package, it cannot (yet) be a versioned dependency. The version dependency should thus be carried by the <filename>ocaml</filename> dependency.
</para>
</section>
Modified: trunk/policy/trunk/chapter-libpack.xml
URL: http://svn.debian.org/wsvn/trunk/policy/trunk/chapter-libpack.xml?rev=2791&op=diff
==============================================================================
--- trunk/policy/trunk/chapter-libpack.xml (original)
+++ trunk/policy/trunk/chapter-libpack.xml Sat May 27 11:25:09 2006
@@ -195,7 +195,7 @@
<listitem><para>header files (<filename>*.mli</filename>),</para></listitem>
<listitem><para>source files (<filename>*.ml</filename>),</para></listitem>
<listitem><para>specific documentation provided by the upstream,</para></listitem>
- <listitem><para>OCamldoc generated documentation</para>.</listitem>
+ <listitem><para>OCamldoc generated documentation.</para></listitem>
</itemizedlist>
</para>
Modified: trunk/policy/trunk/chapter-progpack.xml
URL: http://svn.debian.org/wsvn/trunk/policy/trunk/chapter-progpack.xml?rev=2791&op=diff
==============================================================================
--- trunk/policy/trunk/chapter-progpack.xml (original)
+++ trunk/policy/trunk/chapter-progpack.xml Sat May 27 11:25:09 2006
@@ -1,25 +1,41 @@
<section>
<title>Creating a package for an OCaml program</title>
<para>
- Any package providing executables built from OCaml source should conform
- the following regulations.
+ Any package providing executables built from OCaml source should conform the following guidelines.
+ </para>
- <itemizedlist>
- <listitem>
- <para>
- The package should use the name of the upstream package, without modification.
- </para>
- </listitem>
- <listitem>
- <para>
- The package's <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. The availability of a native compiler can be tested by <code>[ -e /usr/bin/ocamlopt ]</code>. 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.
- </para>
- </listitem>
- <listitem>
- <para>
- All bytecode executables should be link dynamically, so as to not bloat the archive. However, there may be special cases, were using statically linked bytecode is necessary, in these cases, it is naturally ok to link statically. That said, often the upstream authors will favor statically linked bytecode executables, because so they don't need to worry about the presence of the dll stub libraries and such. This will never be a valid reason to use statically linked bytecode in a Debian package. If statically linked bytecode is provided, a justification of this use should be provided in the <filename>README.Debian</filename> file.
- </para>
- </listitem>
- </itemizedlist>
+ <para>
+ The package should use the name of the upstream package, without modification.
+ </para>
+
+ <para>
+ Native versions of programs should be provided where a native compiler is available, bytecode versions should be provided elsewhere (cf. next section).
+ </para>
+
+ <para>
+ All bytecode executables should be linked dynamically, so as to not bloat the archive. However, there may be special cases, were using statically linked bytecode is necessary, in these cases, it is naturally ok to link statically. That said, often the upstream authors will favor statically linked bytecode executables, because so they don't need to worry about the presence of the dll stub libraries and such. This will never be a valid reason to use statically linked bytecode in a Debian package. If statically linked bytecode is provided, a justification of this use should be provided in the <filename>README.Debian</filename> file.
</para>
</section>
+
+<section>
+ <title>Bytecode and native versions of programs</title>
+ <para>
+ As <link linkend='bytecode-native'>explained before</link>, native OCaml compilers are not available everywhere. For architecture having no native compiler, a bytecode version of the program should be provided.
+ </para>
+
+ <para>
+ The package's <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.
+ </para>
+
+ <para>
+ The avilability of a native compiler can be tested in the <filename>debian/rules</filename> file by <code>[ -e /usr/bin/ocamlopt ]</code>, and build the bytecode version or the native version of the program according to the result of the test.
+ </para>
+
+ <para>
+ The bytecode versions are portable. In order to spare the buildds and the Debian archive, bytecode versions should be compiled once for all for big packages (which either take a lot of place on disks or take a lot of time to build). For example, the <filename>spamoracle</filename> package provides the <filename>spamoracle-byte</filename> package which is <varname>Architecture: all</varname> and contains the bytecode version of spamoracle, and the <filename>spamoracle</filename> package which contains the native version of spamoracle and is available only where a native OCaml compiler is available (<varname>Architecture: alpha amd64 arm i386 ia64 kfreebsd-i386 powerpc sparc</varname>).
+ </para>
+
+ <para>
+ Bytecode versions of the programs should depend on <filename>ocaml-base-nox-&ocaml-version;</filename> (or <filename>ocaml-base-&ocaml-version;</filename> the program either uses the <code>Graphics</code> or the <code>LablTk</code> module). In order for the package to be able to be rebuilt or even binNMUed without a change in the packaging, this version should not be really hardocoded in the <filename>debian/control</filename> file. Instead, the package should depend on <varname>ocaml-base-nox-${F:OCamlABI}</varname> and use <code>OCAMLABI := $(shell ocamlc -version)</code> and <code>dh_gencontrol -s -- -VF:OCamlABI="$(OCAMLABI)"</code> in the <filename>debian/rules</filename> file.
+ </para>
+</section>
More information about the Pkg-ocaml-maint-commits
mailing list