--- /dev/null
+
+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/<ocaml_version> (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/<ocaml_version> (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/<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 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/<ocaml_version>/stublibs which is searched before
+ /usr/lib/ocaml/<ocaml_version>/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<package> <dir1> <dir2> ...
+
+ 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/<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 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, <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