
Policy for the packaging of ocaml libraries and programs (version 0.2)
----------------------------------------------------------------------

  1) Ocaml-ldconf and ld.conf handling

    Contrary to the standard ocaml distribution, the path to directories
    containing shared stub libraries is handled in two different files, the
    user editable /etc/ocaml/ld.conf and the dpkg handled
    /var/lib/ocaml/ld.conf.

    The ocaml-ldconf tool is used to generate the ld.conf file used by the
    ocamlrun program.

    Additionnaly, the ocaml-ldconf program is also used in the postinst/postrm
    of packages which provide such shared stub libraries. These
    postinst/postrm parts are automatically added by the debhelper script
    dh_ocamlld, which can be called in debian/rules as follows :

      dh_ocamlld -p<package> <dir1> <dir2> ...
     
    finally, the ocaml-ldconf program can also be used with the -l argument
    to show a list of all current files in the ld.conf file. It doesn't yet
    show the paths provided by other means (environment variable and other
    such)

  2) 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.

  3) 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.

  4) 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.

  5) 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.

  6) Ocaml dependencies.

     The ocaml libraries should always depend on the exact version of ocaml
     they were build with. This can be achieved for the 3.04 version of ocaml 
     with the following dependency:

     Depends: ocaml (>= 3.04), ocaml (<< 3.05)

     and 

     Build-Depends: ocaml (>= 3.04), ocaml (<< 3.05)

     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
list.

 -- Sven Luther <luther@lambda.u-strasbg.fr>, Tue, 19 Feb 2002 22:08:07 +0100
