From: Samuel Mimram Date: Sat, 27 May 2006 13:37:00 +0000 (+0000) Subject: More or less completed porting the policy to docbook. X-Git-Tag: archive/raspbian/4.08.1-4+rpi1~3^2~641^2~5 X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=26ccb5fe202ea6d9ac9f330e96c5b68826dca306;p=ocaml.git More or less completed porting the policy to docbook. --- diff --git a/appendix-svn.xml b/appendix-svn.xml index 7c3223cc..f9b6c8ed 100644 --- a/appendix-svn.xml +++ b/appendix-svn.xml @@ -1,27 +1,27 @@
- How to obtain a copy of the pkg-ocaml-maint SVN archive + How to obtain a copy of the SVN archive FIXME: to be filled in
- Structure of the pkg-ocaml-maint SVN archive + Structure of the SVN archive 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. - - - -The structure of the pkg-ocaml-maint svn archive is as follows, where -generic names are indicated in angular brackets [ .. ], and where the -contents of subdirectories not directly relevant for package management -are not detailed: - + 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. + + + + The structure of the pkg-ocaml-maint svn archive is as follows, where + generic names are indicated in square brackets [ .. ], and where the + contents of subdirectories not directly relevant for package management + are not detailed: + tags packages [package1] @@ -48,18 +48,18 @@ are not detailed: policy projects tools - +
How to add a new package to the SVN archive - Place yourself in the directory trunk/packages of your working copy of + 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 + 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: trunk/packages/my_package @@ -75,11 +75,146 @@ are not detailed: 01_patch1.dpatch ... ... - + - 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 svn add my_package from the trunk/packages directory, and eventually svn commit. + +
+ +
+ How to set up your package for use with <application>svn-buildpackage</application> + + + Please see the svn-buildpackage documentation for complete + information. The important issues here are: + + + + Since we keep upstream as a tarball we have to use svn-buildpackage 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. + + + + + The structure of our svn repository is not among the default structures + of svn-buildpackage. Hence, we have to override the default location of some + directories. + + + + + + + Place yourself in trunk/packages/my_packages/trunk, and do the following: + svn propset mergeWithUpstream 1 debian. + This registers the property "mergeWithUpstream" with the current + directory, such that svn-buildpackage knows that it has to use merge + mode as explained above. + + + + Create a file debian/svn-deblayout with the following contents: + +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 + + + + + Remember that "my_package" has to be replaced by the name of your + actual package. svn-buildpackage will not include this file in the + source package when actually building the package. + + + + If you tried svn-buildpackage before writing your debian/svn-deblayout remember + to delete .svn/deb-layout, since svn-buildpackages caches here the content + of svn-deblayout (that would be empty in this case) and will ignore + your debian/svn-deblayout. + +
+ +
+ How to build a package with <application>svn-buildpackage</application> + + + Please refer to the svn-builpackage documentation for more complete + information. Here is just a quick guide. + + + + All options, except those starting on , are passed to + dpkg-buildpackage. Hence, basic usage should be something like this + (from the trunk/packages/my_package/trunk directory): svn-buildpackage -rfakeroot -uc -us. + + + + svn-buildpackage will complain when your copy of the debian directory + is not in sync with the repository. You may use the option + to override this behaviour. The package will be + build in the directory ../build-area. + + + + If your package is ready for upload you may use the 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: svn-buildpackage --svn-tag. + 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 tags/packages/my_package. The tagging is done directly in the + svn repository. + + + + + Some useful aliases took from the svn-buildpackage HOWTO: + +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' + + + + + The former (svn-b) is to be used for test builds, while you are + working on your package; while the latter (svn-bt) 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. + + + + Adding -k<your gpg id> to the svn-bt alias may also be useful when working on + collaboratively maintained packages: + +alias svn-bt='svn-buildpackage -rfakeroot -k<gpgid> --svn-lintian --svn-dont-clean --svn-tag' + + + +
+ +
+ dpatch + + + 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 debian/rules with the "clean" target in the trunk/ + directory will fail since dpatch is unable to deapply patches, passing + to svn-buildpackage fixes this misbehaviour (aliases suggested + above alredy include this flag). + + + + If you want to use dpatch-edit-patch to handle patches, you will need to invoke + it in "debian only mode" ( flag, see man dpatch-edit-patch) and to tell him + where to find the upstream tarball. Adding the following line to your + ~/.dpatch.conf will be enough: + +conf_origtargzpath=../upstream +
diff --git a/ocaml_packaging_policy b/ocaml_packaging_policy deleted file mode 100644 index 153ec8ea..00000000 --- a/ocaml_packaging_policy +++ /dev/null @@ -1,240 +0,0 @@ -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/ (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/ (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//stublibs and then at - /usr/lib/ocaml//stublibs, as can be seen in the - /usr/lib/ocaml//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//stublibs which is searched before - /usr/lib/ocaml//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//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, , - 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 , Sat, 14 Dec 2002 22:18:44 +0100 - findlib && META: - -- Stefano Zacchiroli , Thu, 13 Jun 2002 21:21:52 +0200