[Pkg-ocaml-maint-commits] r2803 - in /trunk/policy/trunk:
appendix-resources.xml
chapter-generalities.xml chapter-libpack.xml chapter-progpack.xml
ocaml_packaging_policy.xml
zack at users.alioth.debian.org
zack at users.alioth.debian.org
Fri Jun 2 16:42:19 UTC 2006
Author: zack
Date: Fri Jun 2 16:42:18 2006
New Revision: 2803
URL: http://svn.debian.org/wsvn/?sc=1&rev=2803
Log:
my 0.02 EUR
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
trunk/policy/trunk/ocaml_packaging_policy.xml
Modified: trunk/policy/trunk/appendix-resources.xml
URL: http://svn.debian.org/wsvn/trunk/policy/trunk/appendix-resources.xml?rev=2803&op=diff
==============================================================================
--- trunk/policy/trunk/appendix-resources.xml (original)
+++ trunk/policy/trunk/appendix-resources.xml Fri Jun 2 16:42:18 2006
@@ -1,6 +1,6 @@
<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> (it's an <ulink url="http://alioth.debian.org/projects/pkg-ocaml-maint/">Alioth project</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> (<ulink url="http://lists.debian.org/debian-ocaml-maint/">archives</ulink>)</para></listitem>
+ <listitem><para>&ocaml-force;'s website: <ulink url="http://pkg-ocaml-maint.alioth.debian.org/">http://pkg-ocaml-maint.alioth.debian.org/</ulink> (it's an <ulink url="http://alioth.debian.org/projects/pkg-ocaml-maint/">Alioth project</ulink>)</para></listitem>
+ <listitem><para>&ocaml-force;'s mailing list: <ulink url="mailto:debian-ocaml-maint at lists.debian.org">debian-ocaml-maint at lists.debian.org</ulink> (<ulink url="http://lists.debian.org/debian-ocaml-maint/">archives</ulink>)</para></listitem>
</itemizedlist>
</para>
Modified: trunk/policy/trunk/chapter-generalities.xml
URL: http://svn.debian.org/wsvn/trunk/policy/trunk/chapter-generalities.xml?rev=2803&op=diff
==============================================================================
--- trunk/policy/trunk/chapter-generalities.xml (original)
+++ trunk/policy/trunk/chapter-generalities.xml Fri Jun 2 16:42:18 2006
@@ -1,12 +1,12 @@
<section>
- <title>OCaml in Debian</title>
- <para>
- At the time of this writing, the latest version of OCaml in Debian is &ocaml-version;.
- </para>
+ <title>OCaml in Debian</title>
+ <para>
+ At the time of this writing, the latest version of OCaml in Debian is &ocaml-version;.
+ </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 dependencies on big packages for users who do not need to run graphical applications.
- <itemizedlist>
+ 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 packages with suffix <filename>-nox</filename> 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 dependencies on big packages for users who do not need to run graphical applications. Here is the list of binary packages in which OCaml is split:
+ <orderedlist>
<listitem>
<para>
The <filename>ocaml</filename> and <filename>ocaml-nox</filename> packages contain the compiler and its libraries.
@@ -14,22 +14,25 @@
</listitem>
<listitem>
<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>).
+ The <filename>ocaml-native-compilers</filename> package contains the OCaml compilers built in native mode (<filename>ocamlc.opt</filename> and <filename>ocamlopt.opt</filename>).
+ </para>
+ <note>
+ <para>The compilers themselves are built in native mode, nonetheless, both compilers for compiling toward bytecode and native code are contained in this package.</para>
+ </note>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>ocaml-base</filename> and <filename>ocaml-base-nox</filename> packages contain the interpreter and 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-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).
+ The <filename>ocaml-interp</filename> package contains the toplevel system for OCaml (<filename>ocaml</filename>), that enables interactive use of the language.
</para>
</listitem>
<listitem>
<para>
- The <filename>ocaml-interp</filename> package contains the interactive command-line interpreter (<filename>ocaml</filename>).
- </para>
- </listitem>
- <listitem>
- <para>
- 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>).
+ 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>
@@ -39,22 +42,35 @@
</listitem>
<listitem>
<para>
- The <filename>ocaml-compiler-libs</filename> package 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 (needed only in very rare cases, e.g. for developing languages which reuse OCaml internals).
</para>
</listitem>
- </itemizedlist>
+ </orderedlist>
</para>
<para>
- 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>.
+ Since libraries produced by OCaml are binary incompatible when compiled with different releases of OCaml, versioned virtual packages are also provided by packages at items (1) and (2): <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>
+ <title>OCaml location</title>
+ <para>
+ The root of all installed OCaml libraries is the <emphasis>OCaml
+ standard library directory</emphasis>, which is
+ <filename>/usr/lib/ocaml/VERSION/</filename>, at the time of writing
+ <filename>/usr/lib/ocaml/&ocaml-version;</filename>. It can be output
+ by the OCaml compiler invoking it as <code>ocamlc -where</code>.
+ </para>
+
+ </section>
+
</section>
<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.
+ 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: &supported-archs;.
</para>
<para>
@@ -62,7 +78,7 @@
</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. <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 <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.
+ The <filename>ocaml-native-compilers</filename> package contains the OCaml compiler built in native mode (<filename>ocamlc.opt</filename>, which outputs bytecode, and <filename>ocamlopt.opt</filename>, which output native code). Compiling with those versions of the compilers is generally faster. Unfortunately the <filename>ocaml-native-compilers</filename> 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 <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>
@@ -72,16 +88,22 @@
<para>
The &ocaml-name; compiler can produce or use the following kind of files:
<itemizedlist>
- <listitem><para>bytecode executables (they can be recognised since they start with <code>#!/usr/bin/ocamlrun</code>)</para></listitem>
+ <listitem><para>bytecode executables (they can be recognised 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 <filename>ocamlc</filename> (or <filename>ocamlc.opt</filename>), when the <code>-custom</code> flag is given at link time. Those executables are in ELF format and include both the final bytecode and the bytecode interpreter. <filename>strip</filename> 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 executables (in ELF format)</para></listitem>
<listitem><para>native libraries (<filename>*.cmxa</filename>)</para></listitem>
- <listitem><para>shared libraries (for C bindings) (<filename>dll*.so</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>configuration files for handling libraries with <filename>ocamlfind</filename> (<filename>META</filename>)</para></listitem>
- <listitem><para>&camlp4; related files (<filename>*.cm[ao]</filename>)</para></listitem>
+ <!-- ZACK: do we really need to differentiate them? They are plain
+ objects or library after all ... -->
+ <!--<listitem><para>&camlp4; related files (<filename>*.cm[ao]</filename>)</para></listitem>-->
</itemizedlist>
</para>
</section>
@@ -111,10 +133,17 @@
</para>
<para>
- The OCaml compiler first looks for a local installation of libraries and then for libraries installed by Debian packages. This section describe the standard paths for files contained in Debian packages.
+ 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.
</para>
- <para>
- Warning: the <varname>+</varname> preceding any library in the <option>-I</option> of ocamlc or ocamlopt won't be expanded to the local standard library path. You need to specify the path entirely.
- </para>
+ <warning>
+ <para>
+ The <varname>+</varname> preceding any library in the <option>-I</option> of ocamlc or ocamlopt won't be expanded to the local standard library path. You need to specify the path entirely.
+ </para>
+ </warning>
+
</section>
Modified: trunk/policy/trunk/chapter-libpack.xml
URL: http://svn.debian.org/wsvn/trunk/policy/trunk/chapter-libpack.xml?rev=2803&op=diff
==============================================================================
--- trunk/policy/trunk/chapter-libpack.xml (original)
+++ trunk/policy/trunk/chapter-libpack.xml Fri Jun 2 16:42:18 2006
@@ -2,18 +2,24 @@
<title>Creating a package for a library</title>
<para>
- A package which provides an OCaml library <filename>xxx</filename> should be split as follows:
-
- <itemizedlist>
- <listitem>
- <para>
- For libraries which are not purely programmed in OCaml (e.g. C bindings), <filename>libxxx-ocaml</filename> should provide the shared library stubs (<filename>dll*.so</filename>), and all other stuff needed to run a bytecode executable that links into this library. It should depend on <filename>ocaml-base-&ocaml-version;</filename> (or <filename>ocaml-base-nox-&ocaml-version;</filename>) as well as any other library needed. The <emphasis>versionned</emphasis> dependency on <filename>ocaml-base</filename> is important since libraries are binary incompatible between releases of OCaml: basically, a library compiled with OCaml 3.08 cannot be used with OCaml &ocaml-version;.
- </para>
+ A package which provides an OCaml library called <filename>xxx</filename> should be split as follows:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ For libraries which are not purely programmed in OCaml (e.g. C bindings), <filename>libxxx-ocaml</filename> should provide the shared library stubs (<filename>dll*.so</filename>), and all other stuff needed to run a bytecode executable that links into this library. It should depend on <filename>ocaml-base-&ocaml-version;</filename> (or <filename>ocaml-base-nox-&ocaml-version;</filename>) as well as any other library needed. The <emphasis>versioned</emphasis> dependency on <filename>ocaml-base</filename> is important since libraries are binary incompatible between releases of OCaml.
+ </para>
+ <para>
+ <filename>libxxx-ocaml</filename> packages should be in <code>Section: libs</code>
+ </para>
</listitem>
<listitem>
<para>
<filename>libxxx-ocaml-dev</filename> should provide the rest of the library package, in fact anything needed to develop programs using the library. If the library uses other libraries or C libraries, this package should depend on them.
</para>
+ <para>
+ <filename>libxxx-ocaml-dev</filename> packages should be in <code>Section: libdevel</code>
+ </para>
</listitem>
</itemizedlist>
</para>
@@ -35,7 +41,14 @@
</para>
<para>
- It is recommended that libraries use the <option>-pack</option> option to pack all the modules provided by the library into one module. We are not sure this really works right now for libraries, and we don't think upstream libraries will be moving to this scheme anytime soon (unless we actively lobby for it) so this is just a recommendation for now.
+ It is recommended that libraries use the <option>-pack</option> option to pack all the modules provided by the library into one module.
+ <!-- ZACK: yes, it works, it has been fixed in ocaml 3.09.1 IIRC -->
+ <!--We are not sure this really works right now for libraries, and-->
+ We don't think upstream libraries will be moving to this scheme anytime soon (unless we actively lobby for it) so this is just a recommendation for now.
+ </para>
+
+ <para>
+ It is recommended that each library package ships a <filename>META</filename> file in order to make the library usable via <filename>ocamlfind</filename> (see the Debian package <filename>ocaml-findlib</filename>). See <xref linkend="META" /> for more information on this.
</para>
</section>
@@ -47,52 +60,52 @@
</para>
<para>
- If upstream developpers already use a subdirectory of the OCaml standard library path, this path should be preserved in the Debian package but made relative to the standard library path of OCaml. Before using the provided subdirectory, packagers should obviously check if there is no subdirectory name clash with another OCaml library.
- </para>
-
- <para>
- If upstream developpers don't use this scheme, packagers are encouraged not to install this library in the standard library directory. They should create at least a subdirectory per source package (in order to avoid name clashes). Packagers should also consider to do a larger separation by creating a subdirectory per binary package (in order to avoid META name clash). A suggested rule to choose name for this subdirectory is to use either the package name provided by the META of the upstream, or the name of the library itself.
+ If upstream developers already use a subdirectory of the OCaml standard library path, this path should be preserved in the Debian package but made relative to the standard library path of OCaml. Before using the provided subdirectory, packagers should obviously check if there is no subdirectory name clash with another OCaml library.
+ </para>
+
+ <para>
+ If upstream developers don't use this scheme, packagers are encouraged not to install this library in the standard library directory. They should create at least a subdirectory per source package (in order to avoid name clashes). Packagers should also consider to do a larger separation by creating a subdirectory per binary package (in order to avoid META name clash). A suggested rule to choose name for this subdirectory is to use either the package name provided by the META of the upstream, or the name of the library itself.
</para>
</section>
<section>
<title>Handling dependencies on OCaml</title>
<para>
- Some parts of the package need to know the current version of OCaml. For example, libraries should be installed <filename>/usr/lib/ocaml/&ocaml-version;/</filename>. However, <emphasis>the version of OCaml should never be hardcoded in the package</emphasis> (&ocaml-version; here). This would make a binNMU impossible if the version of OCaml has changed. Instead <filename>.in</filename> files should be used where <varname>@OCamlABI@</varname> is replaced at <emphasis>build-time</emphasis> by the current OCaml version.
+ Some parts of the package need to know the current version of OCaml. For example, libraries should be installed <filename>/usr/lib/ocaml/&ocaml-version;/</filename>. However, <emphasis>the current version of OCaml should never be hardcoded in the package</emphasis> (&ocaml-version; here). This would make a binNMU impossible when the version of OCaml changes. Instead <filename>.in</filename> files should be used where <varname>@OCamlABI@</varname> is replaced at <emphasis>build-time</emphasis> by the current OCaml version.
</para>
<para>
For example, the package <filename>ocaml-mad</filename> would normally contain a file <filename>libmad-ocaml-dev.install</filename> for installing files with <filename>dh_install</filename>, containing:
<programlisting>
-usr/lib/ocaml/&ocaml-version;/mad/META
-usr/lib/ocaml/&ocaml-version;/mad/*.a
-usr/lib/ocaml/&ocaml-version;/mad/*.cm*
-usr/lib/ocaml/&ocaml-version;/mad/*.ml*
+ usr/lib/ocaml/&ocaml-version;/mad/META
+ usr/lib/ocaml/&ocaml-version;/mad/*.a
+ usr/lib/ocaml/&ocaml-version;/mad/*.cm*
+ usr/lib/ocaml/&ocaml-version;/mad/*.ml*
</programlisting>
In order to avoid the explicit mention of the version of OCaml (&ocaml-version;), the package actually contains instead a file <filename>libmad-ocaml-dev.install.in</filename> which contains:
<programlisting>
-usr/lib/ocaml/@OCamlABI@/mad/META
-usr/lib/ocaml/@OCamlABI@/mad/*.a
-usr/lib/ocaml/@OCamlABI@/mad/*.cm*
-usr/lib/ocaml/@OCamlABI@/mad/*.ml*
+ usr/lib/ocaml/@OCamlABI@/mad/META
+ usr/lib/ocaml/@OCamlABI@/mad/*.a
+ usr/lib/ocaml/@OCamlABI@/mad/*.cm*
+ usr/lib/ocaml/@OCamlABI@/mad/*.ml*
</programlisting>
The string <varname>@OCamlABI@</varname> is substituted at build-time by the version of OCaml. Here are the relevant parts of the <filename>debian/rules</filename> file:
<programlisting>
-OCAMLABI := $(shell ocamlc -version)
-OFILES := $(patsubst %.in,%,$(wildcard debian/*.in))
-
-ocamlinit:
- for f in $(OFILES); do sed -e 's/@OCamlABI@/$(OCAMLABI)/g' $$f.in > $$f; done
-
-config.status: ocamlinit configure
- [...]
-
-.PHONY: build clean binary-indep binary-arch binary install ocamlinit
+ OCAMLABI := $(shell ocamlc -version)
+ OFILES := $(filter-out debian/control,(patsubst %.in,%,$(wildcard debian/*.in)))
+
+ ocamlinit:
+ for f in $(OFILES); do sed -e 's/@OCamlABI@/$(OCAMLABI)/g' $$f.in > $$f; done
+
+ config.status: ocamlinit configure
+ [...]
+
+ .PHONY: build clean binary-indep binary-arch binary install ocamlinit
</programlisting>
</para>
<para>
- The only exception to this rule is the <filename>debian/control</filename> file, which should never be generated at build-time. As <link linkend='bytecode-native-prog'>explained before</link>, the dependency should nevertheless not hardcode the version of OCaml: the <filename>debian/control</filename> file should have a <varname>Depends: ocaml-base-nox-${F:OCamlABI}</varname> which is filled by a <code>dh_gencontrol -s -- -VF:OCamlABI="$(OCAMLABI)"</code> in the <filename>debian/rules</filename> file.
+ The only exception to this rule (properly handled by the example above) is the <filename>debian/control</filename> file, which should never be generated at build-time. As explained in <xref linkend='bytecode-native-prog'/>, the dependency should nevertheless not hardcode the version of OCaml: the <filename>debian/control</filename> file should have a <varname>Depends: ocaml-base-nox-${F:OCamlABI}</varname> which is filled by a <code>dh_gencontrol -s -- -VF:OCamlABI="$(OCAMLABI)"</code> in the <filename>debian/rules</filename> file.
</para>
</section>
@@ -106,8 +119,8 @@
<para>
By default, &ocamlfind; will look for <filename>META</filename> in this order:
<itemizedlist>
- <listitem><para><filename>/usr/lib/ocaml/&ocaml-version;/META/</filename></para></listitem>
- <listitem><para><filename>/usr/lib/ocaml/&ocaml-version;/package/</filename></para></listitem>
+ <listitem><para><filename>&ocaml-metas-dir;/</filename></para></listitem>
+ <listitem><para><filename>&ocaml-sys-dir;/package/</filename></para></listitem>
</itemizedlist>
</para>
@@ -122,7 +135,7 @@
</listitem>
<listitem>
<para>
- If the <filename>META</filename> file is placed in <filename>/usr/lib/ocaml/&ocaml-version;/META/</filename>, it should be called <filename>META.packagename</filename>, where <filename>packagename</filename> is the name of the subdirectory where the library is stored.
+ If the <filename>META</filename> file is placed in <filename>&ocaml-metas-dir;/</filename>, it should be called <filename>META.packagename</filename>, where <filename>packagename</filename> is the name of the subdirectory where the library is stored.
</para>
</listitem>
</itemizedlist>
@@ -133,7 +146,7 @@
</para>
<para>
- If upstream doesn't provide a <filename>META</filename>, 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 ML for help.
+ If upstream doesn't provide a <filename>META</filename>, 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>
</section>
Modified: trunk/policy/trunk/chapter-progpack.xml
URL: http://svn.debian.org/wsvn/trunk/policy/trunk/chapter-progpack.xml?rev=2803&op=diff
==============================================================================
--- trunk/policy/trunk/chapter-progpack.xml (original)
+++ trunk/policy/trunk/chapter-progpack.xml Fri Jun 2 16:42:18 2006
@@ -1,26 +1,40 @@
<section>
<title>Creating a package for an OCaml program</title>
<para>
- Any package providing executables built from OCaml source should conform the following guidelines.
+ Any package providing executables built from OCaml source should conform to the following guidelines.
</para>
<para>
- The package should use the name of the upstream package, without modification.
+ The source package should, if possible, use the name of the upstream
+ package without modifications.
</para>
<para>
- Native versions of programs should be provided where a native compiler is available, bytecode versions should be provided elsewhere (cf. next section).
+ Programs which are not particularly CPU angry should be compiled in
+ 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. Other programs
+ should be compiled in native form on architectures where the native
+ compiler is available, and in 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, 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.
+ All bytecode executables should be linked dynamically against the shared libraries for C bindings, so as to not bloat the archive.
+ <!-- ZACK: which cases? -->
+ <!--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 is not a valid reason to use statically linked bytecode in a Debian package.
+ <!-- ZACK: related to the commented stuff above -->
+ <!--If statically linked bytecode is provided, a justification of this use should be provided in the <filename>README.Debian</filename> file.-->
</para>
</section>
<section id="bytecode-native-prog">
<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.
+ As explained in <xref linkend='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>
@@ -28,7 +42,17 @@
</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.
+ 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>
@@ -36,6 +60,26 @@
</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, <emphasis>this version should not be hardcoded in the <filename>debian/control</filename> file.</emphasis> 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.
+ 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, <emphasis>this version should not be hardcoded in the <filename>debian/control</filename> file.</emphasis> 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 -- -VF:OCamlABI="$(OCAMLABI)"</code> in the <filename>debian/rules</filename> file.
</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>
+
</section>
Modified: trunk/policy/trunk/ocaml_packaging_policy.xml
URL: http://svn.debian.org/wsvn/trunk/policy/trunk/ocaml_packaging_policy.xml?rev=2803&op=diff
==============================================================================
--- trunk/policy/trunk/ocaml_packaging_policy.xml (original)
+++ trunk/policy/trunk/ocaml_packaging_policy.xml Fri Jun 2 16:42:18 2006
@@ -2,6 +2,10 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"/usr/share/sgml/docbook/dtd/xml/4.3/docbookx.dtd" [
<!ENTITY ocaml-version "3.09.2">
+<!ENTITY ocaml-sys-dir-base "/usr/lib/ocaml">
+<!ENTITY ocaml-sys-dir "&ocaml-sys-dir-base;/&ocaml-version;">
+<!ENTITY ocaml-metas-dir "&ocaml-sys-dir;/METAS">
+<!ENTITY supported-archs "alpha, amd64, arm, i386, ia64, kfreebsd-i386, powerpc, sparc">
<!ENTITY ocaml-compat "1">
<!ENTITY ocaml-pkg "<application>ocaml</application>">
<!ENTITY ocaml-vpkg "<application>ocaml-&ocaml-version;</application>">
@@ -14,7 +18,7 @@
<!ENTITY ocamlopt "<application>ocamlopt</application>">
<!ENTITY ocamldoc "<application>ocamldoc</application>">
<!ENTITY ocamlfind "<application>ocamlfind</application>">
-<!ENTITY camlp4 "<application>camlp4</application>">
+<!ENTITY camlp4 "<application>CamlP4</application>">
<!ENTITY debian-name "Debian">
<!ENTITY authors SYSTEM "authors.xml">
<!ENTITY legal SYSTEM "legal.xml">
More information about the Pkg-ocaml-maint-commits
mailing list