
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


