Debian OCaml Packaging Policy

The correct short name of Objective Caml is OCaml. Other spellings/capitalizations like “ocaml”, “OCAML”, “O'Caml” should be avoided when talking about the Objective Caml project, the system, or the programing language.

At the time of this writing, the latest version of OCaml in Debian is 3.10.2.

The OCaml compiler can produce or use the following kind of files:

Locally installed files are files that are installed directly by the system administrator, in contrast to files installed through Debian packages. Installation and use of locally installed OCaml related programs is out of the scope of this document. However, in order to have it work with a standard Debian installation, a local system administrator should follow these guidelines:

The default configuration of ocamlfind (the OCaml library manager recommended in Debian) first looks for a local installation of libraries and then for libraries installed by Debian packages. The next section describes the standard paths for files contained in Debian packages.

Documentation relevant to programming in OCaml (language, tools, libraries, ...) should be registered with doc-base in Section Programming/OCaml.

Packages that are intended for OCaml development, as opposed to more general tools that just happen to be implemented in OCaml, should have their Section set to ocaml.

Any package providing executables built from OCaml source should conform to the following guidelines.

The source package should, if possible, use the name of the upstream package without modifications.

Programs which are not particularly CPU hungry should be compiled into bytecode form, and the corresponding binary packages should be Architecture: all in order to minimize archive usage and avoid the need of rebuilding them on all architectures. See the section called “Bytecode Packages” for details on this kind of packages.

Other programs should be compiled into native form on architectures where the native compiler is available, and into bytecode on other architectures. See the section called “Bytecode and native versions of programs” for details on how to achieve this. The corresponding binary packages should be Architecture: any and will need to be built on any architecture.

All bytecode executables should be linked dynamically against the shared libraries for C bindings, so as to not bloat the archive. 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 is not a valid reason to use statically linked bytecode in a Debian package.

A bytecode package has all its binaries compiled into bytecode. It depends on a package containing the OCaml runtime system. By consequence, such a package has its architecture field set to all.

A bytecode package must depend on ocaml-base-nox-3.10.2 (or ocaml-base-3.10.2 if the program either uses the Graphics or the LablTk module). In order for the package to be able to be rebuilt or even binNMUed without a change in the packaging, this version should not be hardcoded in the debian/control file. Instead, the package should depend on ocaml-base-nox-${F:OCamlABI} and use OCAMLABI := $(shell ocamlc -version) and dh_gencontrol -- -VF:OCamlABI="$(OCAMLABI)" in the debian/rules file.

A bytecode package must build-depend-indep on ocaml-nox-3.10.2 (or ocaml-3.10.2 if the program either uses the Graphics or the LablTk module). The current version number of OCaml should not be hardcoded into the build-dependency (this is a deviation from a practice which used be recommended but is depreciated now). Of course, if it is necessary to ensure that the version of OCaml has a certain value then version constraints can be used. However, this should be justified by the requirements of the compilation of the program.

Bytecode programs which are compiled by ocamlc -custom must not be stripped. In particular, their package should be excluded from the dh_strip script. When compiled this way, an elf executable is generated containing the ocaml interpreter, and the bytecode of the program in a section which is removed when the program is stripped. For more information, see the bug 256900. An override for the lintian warning is considered as acceptable in this situation.

Bytecode programs should not be compiled for debugging, i.e. they should not be compiled passing the -g option to ocamlc (or ocamlc.opt).

As explained in #bytecode-native, native OCaml compilers are not available everywhere. For architectures missing native compiler, a bytecode version of the program should be provided.

The package's 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. Exceptions to this are the executables who are small or not time critical, which may be built only as bytecode. It is the decision of the individual maintainers to choose this, maybe guided by the practice of the upstream author.

The availability of the native compiler can be tested in the debian/rules file by testing the possibility of executing /usr/bin/ocamlopt, and build the bytecode version or the native version of the program according to the result of the test. This is a sample snippet of debian/rules doing so:

          build-stamp:
                  dh_testdir

                  if [ -x /usr/bin/ocamlopt ]; then \
                          $(MAKE) opt; \
                  else \
                          $(MAKE) all; \
                  fi
        

The bytecode versions are portable. In order to spare the buildds and the Debian archive, bytecode versions should be compiled once for all for big packages (which either take a lot of place on disks or take a lot of time to build). For example, the spamoracle package provides the spamoracle-byte package which is Architecture: all and contains the bytecode version of spamoracle, and the spamoracle package which contains the native version of spamoracle and is available only where a native OCaml compiler is available (Architecture: amd64 i386 kfreebsd-i386 powerpc sparc).

Bytecode versions of the programs should depend on ocaml-base-nox-3.10.2 (or ocaml-base-3.10.2 the program either uses the Graphics or the LablTk module). In order for the package to be able to be rebuilt or even binNMUed without a change in the packaging, this version should not be hardcoded in the debian/control file. Instead, the package should depend on ocaml-base-nox-${F:OCamlABI} and use OCAMLABI := $(shell ocamlc -version) and dh_gencontrol -- -VF:OCamlABI="$(OCAMLABI)" in the debian/rules file.

The following is a snippet of a sample debian/control:

          Package: spamoracle-byte
          Architecture: all
          Depends: ocaml-base-nox-${F:OCamlABI}
          Provides: spamoracle
          Conflicts: spamoracle
          Replaces: spamoracle
        

The following its pairing debian/rules snippet:

          OCAMLABI := $(shell ocamlc -version)
          ...
          binary-indep: build install
          dh_gencontrol -i -- -VF:OCamlABI="$(OCAMLABI)"
        

In the case where there is only one package, which provides either a native version where available or a bytecode version otherwise, the dependency on ocaml-base-nox-3.10.2 should be added only when the package is built in native mode. For example, the debian/control of approx contains:

          Package: approx
          Architecture: any
          Depends: ${shlibs:Depends}, ${F:OCamlRun}, adduser, bzip2, curl
        

and the corresponding debian/rules contains:

          OCAMLABI = $(shell ocamlc -version)
          BYTECODE = $(shell [ -x /usr/bin/ocamlopt ] || echo yes)
          OCAMLRUN = $(if $(BYTECODE),ocaml-base-nox-$(OCAMLABI))
          ...
          binary-arch:
                  ...
                  dh_gencontrol -- -VF:OCamlRun="$(OCAMLRUN)"
        

A package which provides an OCaml library called xxx should be split as follows:

Optionally, two other packages may be created:

It is recommended that libraries use the -pack option to pack all the modules provided by the library into one module. We 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.

It is recommended that each library package ships a META file in order to make the library usable via ocamlfind (see the Debian package ocaml-findlib). See the section called “Providing META files” for more information on this.

Libraries should be installed in /usr/lib/ocaml/3.10.2/ or in a subdirectory of this directory. This includes in particular bytecode libraries (*.cma), native libraries (*.cmxa), bytecode object files (*.cmo), native object files (*.cmx), static libraries (*.a) and META files. The only exception to this rule is for shared libraries (dll*.so) which should be installed in /usr/lib/ocaml/3.10.2/stublibs, as can it be seen in the /usr/lib/ocaml/3.10.2/ld.conf file.

If upstream developers already use a subdirectory of the OCaml standard library path, this path should be preserved in the Debian package but made relative to the standard library path of OCaml. Before using the provided subdirectory, packagers should obviously check if there is no subdirectory name clash with another OCaml library.

If upstream developers don't use this scheme, packagers are encouraged not to install this library in the standard library directory. They should create at least a subdirectory per source package (in order to avoid name clashes). Packagers should also consider to do a larger separation by creating a subdirectory per binary package (in order to avoid META name clash). A suggested rule to choose name for this subdirectory is to use either the package name provided by the META of the upstream, or the name of the library itself.

Some parts of the package need to know the current version of OCaml. For example, libraries should be installed /usr/lib/ocaml/3.10.2/. However, the current version of OCaml should never be hardcoded in the package (3.10.2 here). This would make a binNMU impossible when the version of OCaml changes. Instead .in files should be used where @OCamlABI@ is replaced at build-time by the current OCaml version.

For example, the package ocaml-mad would normally contain a file libmad-ocaml-dev.install for installing files with dh_install, containing:

          usr/lib/ocaml/3.10.2/mad/META
          usr/lib/ocaml/3.10.2/mad/*.a
          usr/lib/ocaml/3.10.2/mad/*.cm*
          usr/lib/ocaml/3.10.2/mad/*.ml*
          

In order to avoid the explicit mention of the version of OCaml (3.10.2), the package actually contains instead a file libmad-ocaml-dev.install.in which contains:

          usr/lib/ocaml/@OCamlABI@/mad/META
          usr/lib/ocaml/@OCamlABI@/mad/*.a
          usr/lib/ocaml/@OCamlABI@/mad/*.cm*
          usr/lib/ocaml/@OCamlABI@/mad/*.ml*
          

The string @OCamlABI@ is substituted at build-time by the version of OCaml. Here are the relevant parts of the debian/rules file:

          OCAMLABI := $(shell ocamlc -version)
          OFILES := $(filter-out debian/control,$(patsubst %.in,%,$(wildcard debian/*.in)))

          ocamlinit:
                  for f in $(OFILES); do sed -e 's/@OCamlABI@/$(OCAMLABI)/g' $$f.in > $$f; done

          config.status: ocamlinit configure
                  [...]

          .PHONY: build clean binary-indep binary-arch binary install ocamlinit
          

The only exception to this rule (properly handled by the example above) is the debian/control file, which should never be generated at build-time. As explained in #bytecode-native-prog, the dependency should nevertheless not hardcode the version of OCaml: the debian/control file should have a Depends: ocaml-base-nox-${F:OCamlABI} which is filled by a dh_gencontrol -s -- -VF:OCamlABI="$(OCAMLABI)" in the debian/rules file.

The ocaml-findlib provides a tool (named ocamlfind) to handle OCaml libraries and store information about libraries dependencies, compiler flags, linking options, etc. Meta informations regarding a library are contained in files (usually one for each library), named META files, contained in the library directory. The distribution of META files is the best way to make more easy to use the Debian-specific oragnization of libraries. Packages distributing META files should suggest the use of ocamlfind, that is have a Suggest: ocaml-findlib.

By default, ocamlfind will look for META in this order:

The naming scheme of META is pretty simple.

For example, the META file for the lablgtk library is named META and has path /usr/lib/ocaml/3.10.2/lablgtk/META, where /usr/lib/ocaml/3.10.2 is the main OCaml installation directory and lablgtk is the lablgtk library directory.

If upstream doesn't provide a META, packagers are encouraged to create one. In this case, the META should be sent to upstream authors, in order to have it included in the next version of the upstream source. For more information about META files, have a look at the Findlib manual, at the several META files provided by other packages (e.g. lablgtk, pxp, pcre, netstring, lablgl, ...) or ask on the debian-ocaml-maint mailing list for help.

Actually, Camlp4 extensions should be processed just as standard OCaml library. The META file distributed with this syntax extension should follow the OSR: META files for packages containing syntax extensions. In particular, the syntax extension should be contained in a syntax sub packages.

The naming convention of the package is to use the same naming as with standard package, replacing -ocaml- by the syntax extension name, -camlp4-.

If a package contains at the same time syntax extension and library, it is up to the maintainer to choose the most relevant name for the package. Whatever the name chosen for the package, the other name should be a Provide of the package.

For example, consider the package sexplib310. It provides a syntax extension and a library, which is the runtime support of the additional function generated by the syntax extension. Since the most common use of sexplib310 is through its syntax extension, the package is name libsexplib-camlp4-dev and it also provide libsexplib-ocaml-dev.

Camlp5 is an alternate pretty-printer and preprocessor for OCaml (which is compatible with pre-3.10.0 version). Syntax extension are handled through exactly the same scheme as for Camlp4 except that package name use -camlp5- rather than -camlp4-.

The documentation is a joint effort of The Debian OCaml Task Force and usptream. There are many ways to have documentation:

This documentation should be browsable by different mean, from the most simple to the most complex. At least, they should all be readable with simple text editor. Specific and ocamldoc generated documentations should be provided in HTML format. There are also at least two specific OCaml browser : docbrowse shipped with cameleon and ocamlbrowser shipped with OCaml itself. The first one, needs specific ocamldoc generated documentation. The second one enables the user to browse directly the prototype of each function shipped in the cmi gives to the application.

You can generate ocamldoc-specific documentation by using the -dump of this application. By using this, you dump the intermediary representation of the document that will be generated by ocamldoc. This can be used to generate HTML documentation and manpages, by reloading this file (using -load).

As of today, there is no way to post-process ocamldoc specific documentation. A Debian package is under construction to do this task. It will be referred as ocamldoc-base.