From 9a61673c33ecc1b9110696cde7733dba75484d3d Mon Sep 17 00:00:00 2001 From: Sylvain Le Gall Date: Thu, 16 Oct 2003 22:13:38 +0000 Subject: [PATCH] Added some tools to create package. A lot to come tommorow ;-> Sylvain LE GALL --- ocaml_packaging_policy | 249 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 ocaml_packaging_policy diff --git a/ocaml_packaging_policy b/ocaml_packaging_policy new file mode 100644 index 00000000..37f1c988 --- /dev/null +++ b/ocaml_packaging_policy @@ -0,0 +1,249 @@ + +Policy for the packaging of ocaml libraries and programs (version 0.4) +---------------------------------------------------------------------- + + 1) User installed libraries. + + Debian package installed ocaml related stuff install per default under + /usr/lib/ocaml/ (that is /usr/lib/ocaml/3.06 for + ocaml 3.06). + + 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.06 for ocaml 3.06). + + 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 aroung until all + libraries are ported. ocaml-ldconf is now declared deprecated, and will + be removed in the near future, probably at the time of the ocaml 3.07 + release, and outputs a warning in this sense when a package still using + it get installed. + + Notice that user installed dll.so files should go into + /usr/local/lib/ocaml//stublibs which is searched before + /usr/lib/ocaml//stublibs. + + Ocaml-ldconf handled the ld.conf file in a different way than what ocaml + does. There are three involved files, /var/lib/ocaml/ld.conf which is + handled by dpkg and its dh_ocamlld generated postinst/prerm script, + /etc/ocaml/ld.conf which the sysadmin can adapt to its needs, and finally + /usr/lib/ocaml/ld.conf which is generated from the previous two by + ocaml-ldconf. Since many libraries don't know about this, + /usr/lib/ocaml/ld.conf will be made read only (except for the + ocaml-ldconf tool). + + Ocaml library packager should install the stub libraries (dll.so) into + /usr/lib/ocaml/stublibs, so no further meddling with the ld.conf file is + needed. If (for whatever unrecommended reasons) a separate stub library + is wanted, then a call to dh_ocamlld should be added in the debian/rules + file as follows : + + dh_ocamlld -p ... + + 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.06/lablgtk/META, where "/usr/lib/ocaml/3.06" 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, nestring, + 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 as well as any other library needed. + + - libxxx-ocaml-dev will provide the rest of the library package, in + fact anything needed to developp 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 recomendation 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 exeption 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 practic 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 encoutnered 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 usefull 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.06-1 and + ocaml-base-3.06-1 respectively. + + Ocaml libraries should build depend on ocaml-3.06-1 : + + Build-Depends: ocaml-3.06-1 + + Ocaml library runtime packages (the libxxx-ocaml) + should depend on ocaml-base-3.06-1 : + + Depends: ocaml-base-3.06-1 + + And Ocaml library developpment packages (the libxxx-ocaml-dev) + should depend on ocaml-3.06-1 : + + Depends: ocaml-3.06-1 + + The old way of doing this (epends: ocaml (>= 3.06), ocaml (<< 3.07)) 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, altough 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 + + -- 2.30.2