<section>
- <title>How to obtain a copy of the pkg-ocaml-maint SVN archive</title>
+ <title>How to obtain a copy of the SVN archive</title>
<para>
FIXME: to be filled in
</para>
</section>
<section>
- <title>Structure of the pkg-ocaml-maint SVN archive</title>
+ <title>Structure of the 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>
+ upstream only as a compressed tarball. The rationale behind this is
+ that changes to upstream files should be managed by the <application>dpatch</application> patch
+ manager. Hence, all the diffs to upstream files are kept in a
+ subdirectory of <filename>debian/</filename>, and it is not necessary to manage upstream on
+ file-by-file basis.
+ </para>
+
+ The structure of the pkg-ocaml-maint svn archive is as follows, where
+ generic names are indicated in square brackets <varname>[ .. ]</varname>, and where the
+ contents of subdirectories not directly relevant for package management
+ are not detailed:
tags
packages
[package1]
policy
projects
tools
-</programlisting>
+ </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
+ Place yourself in the directory <filename>trunk/packages</filename> 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
+ source package (let's say, my-package), and subdirectories <filename>upstream</filename>
+ and <filename>trunk</filename>. Put the current upstream tarball in <filename>upstream</filename>, and the
+ current debian directory with all its relevant files in <filename>trunk</filename>. This
should now look like this:
<programlisting>
trunk/packages/my_package
01_patch1.dpatch
...
...
- </programlisting>
+ </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".
+ If everything is in order you can do a <command>svn add my_package</command> from the <filename>trunk/packages</filename> directory, and eventually <command>svn commit</command>.
+ </para>
+</section>
+
+<section>
+ <title>How to set up your package for use with <application>svn-buildpackage</application></title>
+
+ <para>
+ Please see the <application>svn-buildpackage</application> documentation for complete
+ information. The important issues here are:
+ <itemizedlist>
+ <listitem>
+ <para>
+ Since we keep upstream as a tarball we have to use <application>svn-buildpackage</application> in
+ so-called merge mode. This means that, before compiling the package,
+ the debianized source tree is constructed by untarring the orig tarball, and then merging the contents of the trunk subdirectory in it.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The structure of our svn repository is not among the default structures
+ of <application>svn-buildpackage</application>. Hence, we have to override the default location of some
+ directories.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Place yourself in <filename>trunk/packages/my_packages/trunk</filename>, and do the following:
+ <command>svn propset mergeWithUpstream 1 debian</command>.
+ This registers the property "mergeWithUpstream" with the current
+ directory, such that svn-buildpackage knows that it has to use merge
+ mode as explained above.
+ </para>
+
+ <para>
+ Create a file <filename>debian/svn-deblayout</filename> with the following contents:
+ <programlisting>
+origDir=../upstream
+origUrl=svn+ssh://svn.debian.org/svn/pkg-ocaml-maint/trunk/packages/my_package/upstream
+tagsUrl=svn+ssh://svn.debian.org/svn/pkg-ocaml-maint/tags/packages/my_package
+ </programlisting>
+ </para>
+
+ <para>
+ Remember that "my_package" has to be replaced by the name of your
+ actual package. <application>svn-buildpackage</application> will not include this file in the
+ source package when actually building the package.
+ </para>
+
+ <para>
+ If you tried <application>svn-buildpackage</application> before writing your <filename>debian/svn-deblayout</filename> remember
+ to delete <filename>.svn/deb-layout</filename>, since <application>svn-buildpackages</application> caches here the content
+ of <filename>svn-deblayout</filename> (that would be empty in this case) and will ignore
+ your <filename>debian/svn-deblayout</filename>.
+ </para>
+</section>
+
+<section>
+ <title>How to build a package with <application>svn-buildpackage</application></title>
+
+ <para>
+ Please refer to the <application>svn-builpackage</application> documentation for more complete
+ information. Here is just a quick guide.
+ </para>
+
+ <para>
+ All options, except those starting on <option>--svn</option>, are passed to
+ <application>dpkg-buildpackage</application>. Hence, basic usage should be something like this
+ (from the <filename>trunk/packages/my_package/trunk</filename> directory): <command>svn-buildpackage -rfakeroot -uc -us</command>.
+ </para>
+
+ <para>
+ svn-buildpackage will complain when your copy of the debian directory
+ is not in sync with the repository. You may use the option
+ <option>--svn-ignore-new</option> to override this behaviour. The package will be
+ build in the directory <filename>../build-area</filename>.
+ </para>
+
+ <para>
+ If your package is ready for upload you may use the <option>--svn-tag</option> option
+ for the final build. This will put a tag in the svn-repository on the
+ current version, and add a new entry in the changlog to start working
+ on the upcomming next version: <command>svn-buildpackage --svn-tag</command>.
+ Provided you have commited all your changes to the svn repository, this
+ will after a successful build of the package create a tag for the current
+ version in <filename>tags/packages/my_package</filename>. The tagging is done directly in the
+ svn repository.
+ </para>
+
+ <tip>
+ <para>
+ Some useful aliases took from the svn-buildpackage HOWTO:
+ <programlisting>
+alias svn-b='svn-buildpackage -rfakeroot --svn-dont-clean -us -uc --svn-ignore'
+alias svn-bt='svn-buildpackage -rfakeroot --svn-lintian --svn-dont-clean --svn-tag'
+ </programlisting>
+ </para>
+
+ <para>
+ The former (<command>svn-b</command>) is to be used for test builds, while you are
+ working on your package; while the latter (<command>svn-bt</command>) is to be used at
+ the end, after you commit your changes and just before uploading a new
+ version of the package to the debian archive.
+ </para>
+
+ <para>
+ Adding -k<your gpg id> to the svn-bt alias may also be useful when working on
+ collaboratively maintained packages:
+ <programlisting>
+alias svn-bt='svn-buildpackage -rfakeroot -k<gpgid> --svn-lintian --svn-dont-clean --svn-tag'
+ </programlisting>
+ </para>
+ </tip>
+</section>
+
+<section>
+ <title>dpatch</title>
+
+ <para>
+ dpatch will work properly ad package build time with the svn structure
+ described above since all the build process will be carried on in a fresh
+ directory. However, invoking <filename>debian/rules</filename> with the "clean" target in the <filename>trunk/</filename>
+ directory will fail since dpatch is unable to deapply patches, passing
+ <option>--svn-dont-clean</option> to <application>svn-buildpackage</application> fixes this misbehaviour (aliases suggested
+ above alredy include this flag).
+ </para>
+
+ <para>
+ If you want to use dpatch-edit-patch to handle patches, you will need to invoke
+ it in "debian only mode" (<option>-b</option> flag, see man dpatch-edit-patch) and to tell him
+ where to find the upstream tarball. Adding the following line to your
+ <filename>~/.dpatch.conf</filename> will be enough:
+ <programlisting>
+conf_origtargzpath=../upstream
+ </programlisting>
</para>
</section>
+++ /dev/null
-Policy for the packaging of ocaml libraries and programs (version 0.6)
-----------------------------------------------------------------------
-
- 1) User installed libraries
-
- Debian package installed ocaml related stuff install per default under
- /usr/lib/ocaml/<ocaml_version> (that is /usr/lib/ocaml/3.08 for
- ocaml 3.08).
-
- User installed stuff cannot by policy go under this directory, since the
- /usr tree is for dpkg handled packages alone. As thus, user installed
- stuff should go into /usr/local/lib/ocaml/<ocaml_version> (that is
- /usr/local/lib/ocaml/3.08 for ocaml 3.08).
-
- Findlib knows about this, and will install user installed stuff into the
- right place. But this does not resolve the problem of user stuff which
- does not use findlib.
-
- Another problem is that the actual version of ocaml will not search more
- than one path by default nor can the -I +dir option be used for locally
- installed stuff, and as thus the full path needs to be handled for these
- cases. A solution to this needs to be coordinated with upstream.
-
- Finally, the runtime system will look for dll.so files first at
- /usr/local/lib/ocaml/<ocaml_version>/stublibs and then at
- /usr/lib/ocaml/<ocaml_version>/stublibs, as can be seen in the
- /usr/lib/ocaml/<ocaml_version>/ld.conf file.
-
- 2) Dynamically loaded stub libraries and ld.conf handling
-
- Starting from ocaml 3.05, ocaml now puts all dll.so files into a common
- stublibs directory, so the ocaml-ldconf tool for handling the ld.conf
- file is not needed anymore, but we will still keep it around until all
- libraries are ported. Since ocaml 3.08, ocaml-ldconf is now deprecated
- and removed.
-
- Notice that user installed dll.so files should go into
- /usr/local/lib/ocaml/<ocaml_version>/stublibs which is searched before
- /usr/lib/ocaml/<ocaml_version>/stublibs.
-
- 3) Findlib and META files
-
- Findlib [2] provides a tool (namely "ocamlfind") to handle OCaml libraries
- and store information about libraries dependencies, compiler flags, linking
- options, etc ...
- Meta information regarding a library are contained in files (usually one
- for each library), named "META" files, contained in the library directory.
- For example: the META file for the lablgtk [3] library is named "META" and
- has path /usr/lib/ocaml/3.08/lablgtk/META, where "/usr/lib/ocaml/3.08" is
- the main OCaml installation directory and "lablgtk" is the lablgtk library
- directory.
-
- A package which provides OCaml libraries should provides one META file for
- each library it provides and should have it installed so that findlib can
- find it (easily checkable doing "ocamlfind list"), installing it in the
- library directory is usually a good solution, but others are possible.
- If the META file isn't available upstream, the maintainer should
- write one, include it in the Debian package and suggest the upstream to
- include it in next release.
-
- Writing a META file is easy and usually takes a 5-minute-work, for more
- information have a look at the Findlib manual [4], at the several META
- files provided by other packages (e.g. lablgtk, pxp, pcre, netstring,
- lablgl, ...) or ask on the debian-ocaml-maint ML [1] for help.
-
- 4) Ocaml library packages
-
- A package, named xxx, which provides ocaml libraries should be split as
- follows :
-
- - libxxx-ocaml will provide the shared library stubs, and all other
- stuff needed to run a dynamic loading ocaml bytecode executable that
- links into this library.
- It should depend on ocaml-base (or ocaml-base-nox, see section 8)
- as well as any other library needed.
-
- - libxxx-ocaml-dev will provide the rest of the library package, in
- fact anything needed to develop programs using the library.
-
- Optionally, two other packages can be split :
-
- - libxxx-ocaml-bin may include binaries provided by the library source
- package if they are numerous. This package should conform with the
- same regulations as other packages providing ocaml programs. It is
- only needed to split off this package if there is a significant
- number of programs included in the library, if not, the programs
- should go into libxxx-ocaml-dev.
-
- - libxxx-ocaml-doc may include any kind of documentation provided by
- the library source package or as separate documentation. Again, if
- there is only little documentation, they should go with the -dev
- package.
-
- It is also recommended that libraries use the -pack option to pack all
- the modules provided by the library into one module. I am not sure this
- really works right now for libraries, and i 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.
-
- 5) Ocaml program packages
-
- Any package providing executables issued from ocaml source should conform
- the following regulations.
-
- - the package will go by the name of the upstream package, without
- modifications.
-
- - the package debian/rules 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.
- And exception to this are the executables who are small or not time
- critical, which may be built only as bytecode executable. It is the
- decision of the individual maintainers to choose this, maybe guided by
- the practice of the upstream author.
-
- - all bytecode executables should be dynamic loading, 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 README.Debian file.
-
- Notice, that for now, we will not split the packages into a native code
- version and a dynamic loading bytecode version. This may be a change we
- will go in post woody, and which will allow to distribute the bytecode
- executables as binary: all.
-
- 6) Caml C headers
-
- On debian systems, the caml C headers are encountered under
- /usr/include/caml, as it should be. A /usr/lib/ocaml/<ocaml_version>/caml
- symlink is provided for backward compatibility of non debian maintained
- packages, but using them is considered broken for debian packages.
-
- 7) Ocaml-best-compilers
-
- Packages for which it is recommended to use the optimized nativecode
- compilers to build them should depend on the ocaml package and the
- ocaml-best-compilers package. The ocaml-best-compilers will provide the
- best compilers available for that architecture, but as it is a virtual
- package, it cannot (yet) be a versioned dependency. The version
- dependency should thus be carried by the ocaml dependency.
-
- Notice that it is only useful to use the nativecode compilers when the
- package contains especially large source files or is very large. Mostly
- when this is the case, the upstream authors will recommend the use of
- nativecode compilers in these cases.
-
- If native code compilers are recommended, it would be a good idea to
- split the package between the native code version and a binary: all
- bytecode version, in order to not overload the slower not nativecode
- architectures.
-
- 8) Ocaml dependencies.
-
- The ocaml libraries should always depend on the exact version of ocaml
- they were build with. Since ocaml 3.06-13, the ocaml and ocaml-base
- package now provide virtual packages called ocaml-3.08 and
- ocaml-base-3.08 respectively.
-
- Since ocaml 3.07.2a-3, ocaml is split in ocaml-nox and ocaml and
- ocaml-base is split in ocaml-base-nox and ocaml-base. The -nox packages
- contain all the files the packages used to contain except the files
- related to the Graphics module and labltk. This has been done in order to
- avoid unnecessary dependencies to X libraries. The -nox packages should
- be used in the dependencies when neither Graphics nor labltk is used in the
- program.
-
- Ocaml libraries should build depend on ocaml-3.08 :
-
- Build-Depends: ocaml-3.08
-
- (or ocaml-nox-3.08 if the library does not require X stuff)
-
- Ocaml library runtime packages (the libxxx-ocaml)
- should depend on ocaml-base-3.08 :
-
- Depends: ocaml-base-3.08
-
- (or ocaml-base-nox-3.08 if the library does not require X stuff)
-
- And Ocaml library development packages (the libxxx-ocaml-dev)
- should depend on ocaml-3.08 :
-
- Depends: ocaml-3.08
-
- (or ocaml-nox-3.08 if the library does not require X stuff)
-
- The old way of doing this (Depends: ocaml (>= 3.08), ocaml (<< 3.09)) is
- deprecated
-
- It is necessary to do this to future proof library packages, so they will
- not remain installed when a new, maybe incompatible, version of ocaml is
- installed, and thus provide library parts built with different versions
- of the compiler, which may not work, and is not recommended by the ocaml
- team.
-
- In the future, this restriction may be lifted if ocaml gains a finer
- control of the incompatible changes in the .cm* files.
-
- Also i may add some stuff to be able to determine this version
- dynamically from the ocaml package, in order to simplify the work of my
- fellow maintainers, but this will probably be a post woody stuff.
-
- Finally, i strongly recommend that all packages containing ocaml
- executables follow these same dependency rules, although it may not be
- always necessary, but again this is something recommended by the upstream
- authors. As an exception, it is mandatory to add these dependencies for
- executables which do dynamic loading of bytecode files, for the same
- reason as the library case.
-
- Notice that a critic to this is that it may hinder the ocaml compiler to
- enter testing, if there are still packages in testing that depend on an
- older version of ocaml. This is ok, in fact it is even the expected
- behavior of testings and the new pool stuff. The idea is that all the
- packages which depend on the exact same version of the ocaml package will
- need to be available as testing candidates before the ocaml package can
- enter testing simultaneously with these other packages. This is were the
- pool name comes from, and we have here the ocaml pool.
-
-Ok, thats all for now, feel free to comment on it on the debian-ocaml-maint [1]
-list.
-
-References:
-
-[1] Debian Ocaml Maintainer Mailing List, <debian-ocaml-maint@lists.debian.org>,
- archives available at http://lists.debian.org/debian-ocaml-maint/
-[2] http://www.ocaml-programming.de/packages/, debian package "ocaml-findlib"
-[3] http://wwwfun.kurims.kyoto-u.ac.jp/soft/olabl/
-[4] http://www.ocaml-programming.de/packages/documentation/findlib/,
- /usr/share/doc/ocaml-findlib/html/index.html
-
-Authors:
- First version:
- -- Sven Luther <luther@lambda.u-strasbg.fr>, Sat, 14 Dec 2002 22:18:44 +0100
- findlib && META:
- -- Stefano Zacchiroli <zack@cs.unibo.it>, Thu, 13 Jun 2002 21:21:52 +0200
projects / ocaml.git / commitdiff