-<!--
-<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@lists.debian.org">debian-ocaml-maint@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@lists.debian.org">debian-ocaml-maint@lists.debian.org</ulink> (<ulink url="http://lists.debian.org/debian-ocaml-maint/">archives</ulink>)</para></listitem>
</itemizedlist>
</para>
--- /dev/null
+<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>
+++ /dev/null
-<section>
- <title>Packages which can be binNMUed</title>
- <para>
- blah
- </para>
-</section>
</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>
<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>
</para>
</section>
-<section>
- <title>Handling dependencies on OCaml</title>
- <para>
- </para>
-</section>
-
<section id="library-path">
<title>Paths for libraries</title>
</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 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>
+ 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>
</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.
</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>
<!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>
&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>
projects / ocaml.git / commitdiff