[Pkg-ocaml-maint-commits] r2792 - in /trunk/policy/trunk:
appendix-resources.xml appendix-svn.xml
appendix-transition.xml chapter-generalities.xml chapter-libpack.xml
chapter-progpack.xml ocaml_packaging_policy.xml
smimram at users.alioth.debian.org
smimram at users.alioth.debian.org
Sat May 27 12:09:34 UTC 2006
Author: smimram
Date: Sat May 27 12:09:33 2006
New Revision: 2792
URL: http://svn.debian.org/wsvn/?sc=1&rev=2792
Log:
Some more doc.
Added:
trunk/policy/trunk/appendix-svn.xml
Removed:
trunk/policy/trunk/appendix-transition.xml
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=2792&op=diff
==============================================================================
--- trunk/policy/trunk/appendix-resources.xml (original)
+++ trunk/policy/trunk/appendix-resources.xml Sat May 27 12:09:33 2006
@@ -1,22 +1,6 @@
-<!--
-<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>
+ <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>
</itemizedlist>
</para>
Added: trunk/policy/trunk/appendix-svn.xml
URL: http://svn.debian.org/wsvn/trunk/policy/trunk/appendix-svn.xml?rev=2792&op=file
==============================================================================
--- trunk/policy/trunk/appendix-svn.xml (added)
+++ trunk/policy/trunk/appendix-svn.xml Sat May 27 12:09:33 2006
@@ -1,0 +1,85 @@
+<section>
+ <title>How to obtain a copy of the pkg-ocaml-maint SVN archive</title>
+ <para>
+ FIXME: to be filled in
+ </para>
+</section>
+
+<section>
+ <title>Structure of the pkg-ocaml-maint SVN archive</title>
+ <para>
+ We keep all files of the debian subdirectory under svn control, and
+upstream only as a compressed tarball. The rationale behind this is
+that changes to upstream files should be managed by the dpatch patch
+manager. Hence, all the diffs to upstream files are kept in a
+subdirectory of debian/, and it is not necessary to manage upstream on
+file-by-file basis.
+</para>
+
+<para>
+The structure of the pkg-ocaml-maint svn archive is as follows, where
+generic names are indicated in angular brackets <varname>[ .. ]</varname>, and where the
+contents of subdirectories not directly relevant for package management
+are not detailed:
+<programlisting>
+ tags
+ packages
+ [package1]
+ [version1]
+ [version2]
+ ...
+ [package2]
+ [version1]
+ ...
+ ...
+ projects
+ test
+ trunk
+ packages
+ [package1]
+ trunk
+ debian
+ upstream
+ [upstream-tarball-version1]
+ [upstream-tarball-version2]
+ ...
+ [package2]
+ ...
+ policy
+ projects
+ tools
+</programlisting>
+ </para>
+</section>
+
+<section>
+ <title>How to add a new package to the SVN archive</title>
+ <para>
+ Place yourself in the directory trunk/packages of your working copy of
+ the svn repository. Create a directory with the same name as your
+ source package (let's say, my-package), and subdirectories "upstream"
+ and "trunk". Put the current upstream tarball in "upstream", and the
+ current debian directory with all its relevant files in "trunk". This
+ should now look like this:
+ <programlisting>
+ trunk/packages/my_package
+ upstream
+ my_package_1.2.3.orig.tar.gz
+ trunk
+ debian
+ changelog
+ control
+ copyright
+ patches
+ 00_list
+ 01_patch1.dpatch
+ ...
+ ...
+ </programlisting>
+ </para>
+
+ <para>
+ If everything is in order you can do a "svn add my_package" from the
+"trunk/packages" directory, and eventually "svn commit".
+ </para>
+</section>
Modified: trunk/policy/trunk/chapter-generalities.xml
URL: http://svn.debian.org/wsvn/trunk/policy/trunk/chapter-generalities.xml?rev=2792&op=diff
==============================================================================
--- trunk/policy/trunk/chapter-generalities.xml (original)
+++ trunk/policy/trunk/chapter-generalities.xml Sat May 27 12:09:33 2006
@@ -62,7 +62,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. 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.
+ 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.
</para>
</section>
Modified: trunk/policy/trunk/chapter-libpack.xml
URL: http://svn.debian.org/wsvn/trunk/policy/trunk/chapter-libpack.xml?rev=2792&op=diff
==============================================================================
--- trunk/policy/trunk/chapter-libpack.xml (original)
+++ trunk/policy/trunk/chapter-libpack.xml Sat May 27 12:09:33 2006
@@ -7,7 +7,7 @@
<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.
+ 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>
</listitem>
<listitem>
@@ -36,32 +36,63 @@
<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.
+ </para>
+</section>
+
+<section id="library-path">
+ <title>Paths for libraries</title>
+
+ <para>
+ Libraries should be installed in <filename>/usr/local/lib/ocaml/&ocaml-version;/</filename> or in a subdirectory of this directory. This includes in particular bytecode libraries (<filename>*.cma</filename>), native libraries (<filename>*.cmxa</filename>), bytecode object files (<filename>*.cmo</filename>), native object files (<filename>*.cmx</filename>), static libraries (<filename>*.a</filename>) and <filename>META</filename> files. The only exception to this rule is for shared libraries (<filename>dll*.so</filename>) which should be installed in <filename>/usr/local/lib/ocaml/&ocaml-version;/stublibs</filename>, as can it be seen in the <filename>/usr/lib/ocaml/&ocaml-version;/ld.conf</filename> file.
+ </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.
</para>
</section>
<section>
<title>Handling dependencies on OCaml</title>
<para>
- </para>
-</section>
-
-<section id="library-path">
- <title>Paths for libraries</title>
-
- <para>
- Libraries should be installed in <filename>/usr/local/lib/ocaml/&ocaml-version;/</filename> or in a subdirectory of this directory. This includes in particular bytecode libraries (<filename>*.cma</filename>), native libraries (<filename>*.cmxa</filename>), bytecode object files (<filename>*.cmo</filename>), native object files (<filename>*.cmx</filename>), static libraries (<filename>*.a</filename>) and <filename>META</filename> files. The only exception to this rule is for shared libraries (<filename>dll*.so</filename>) which should be installed in <filename>/usr/local/lib/ocaml/&ocaml-version;/stublibs</filename>, as can it be seen in the <filename>/usr/lib/ocaml/&ocaml-version;/ld.conf</filename> file.
- </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.
+ Some parts of the package need to know the current version of OCaml. For example, libraries should be installed <filename>/usr/local/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.
+ </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*
+ </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*
+ </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
+ </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.
</para>
</section>
Modified: trunk/policy/trunk/chapter-progpack.xml
URL: http://svn.debian.org/wsvn/trunk/policy/trunk/chapter-progpack.xml?rev=2792&op=diff
==============================================================================
--- trunk/policy/trunk/chapter-progpack.xml (original)
+++ trunk/policy/trunk/chapter-progpack.xml Sat May 27 12:09:33 2006
@@ -17,7 +17,7 @@
</para>
</section>
-<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.
@@ -36,6 +36,6 @@
</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.
+ 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.
</para>
</section>
Modified: trunk/policy/trunk/ocaml_packaging_policy.xml
URL: http://svn.debian.org/wsvn/trunk/policy/trunk/ocaml_packaging_policy.xml?rev=2792&op=diff
==============================================================================
--- trunk/policy/trunk/ocaml_packaging_policy.xml (original)
+++ trunk/policy/trunk/ocaml_packaging_policy.xml Sat May 27 12:09:33 2006
@@ -23,8 +23,8 @@
<!ENTITY chapter-libpack SYSTEM "chapter-libpack.xml">
<!ENTITY chapter-progpack SYSTEM "chapter-progpack.xml">
<!ENTITY chapter-liblocal SYSTEM "chapter-liblocal.xml">
-<!ENTITY appendix-transition SYSTEM "appendix-transition.xml">
<!ENTITY appendix-resources SYSTEM "appendix-resources.xml">
+<!ENTITY appendix-svn SYSTEM "appendix-svn.xml">
]>
<book>
<bookinfo>
@@ -49,13 +49,13 @@
&chapter-libpack;
</chapter>
- <appendix id="transition">
- <title>Managing version transition</title>
- &appendix-transition;
- </appendix>
-
<appendix id="resources">
<title>&ocaml-force; resources</title>
&appendix-resources;
</appendix>
+
+ <appendix>
+ <title>Using the SVN repository</title>
+ &appendix-svn;
+ </appendix>
</book>
More information about the Pkg-ocaml-maint-commits
mailing list