Ocaml library packaging policy
From Mandriva Community Wiki
Contents |
Rules
Naming
OCaml modules, libraries and syntax extensions should be named ocaml-foo. Examples include: ocaml-extlib, ocaml-ssl.
Files splitting
Main package
In order to allow OCaml scripts and the toplevel to use a library, the main package should contain only files matching:
- *.cma (contains the bytecode)
- *.cmi (contains the compiled signature)
- *.so (if present, contains OCaml <-> C stubs)
- META (the findlib description)
- *.so.owner (if present, used by findlib)
- *.cmxs (dynamically loadable native code modules)
- a license file (if present) marked %doc
- .cmo files are not normally included. There are two exceptions where *.cmo files may be included:
- if file is needed for link (like gtkInit.cmo in lablgtk or std_exit.cmo in OCaml itself), then it must be included to allow the library to be linked properly.
- if the cmo file is a camlp4 preprocessor (like Camlp4OCamlPrinter.cmo in OCaml), then it must be included because otherwise the syntax extension would not be available.
If the package contains *.so files, then they should have rpaths removed, as per standard Mandriva packaging policy..
The packager should check the META file [1]. If there is no META file, then the packager should create one, include it in the package, and pass it to the upstream maintainer.
Rationale: OCaml does not support dynamic linking of binaries, and even if it did with the current module hash system for expressing strict typing requirements almost any conceivable change to a library would require the binary to be recompiled. OCaml scripts are the closest we come to dynamic linking, in as much as they do not usually depend on a specific version of a library (albeit this only works because the scripts are recompiled each time they run).
-devel subpackage
The -devel subpackage of a library should contain all other files required to allow development with the library. Normally these would be:
- *.a (contains the compiled machine code)
- *.cmxa (describes the compiled machine code)
- *.cmx (if present, allows cross-module optimizations)
- *.mli (contains the signature of the library)
- .o files are not normally included. There is however one exception -- if file is needed for link (like gtkInit.cmx and gtkInit.o in lablgtk or std_exit.cmx and std_exit.o in OCaml itself), then it should be included.
- .ml files are not normally included. The exception is if the file describes a module signature and there is no corresponding .mli file, then the .ml file should be included. (Note that Debian is more permissive and they often distribute *.ml files, allowing the programmer to peek at the implementation of a module).
Documentation, examples and other articles which are useful to the developer may be included in the -devel sub-package. The license file (which is in the main package) does not need to be included again in the -devel subpackage.
If the -devel subpackage would only contain documentation files, then the packager may at their discretion place the documentation files in the main package and not have a -devel subpackage at all.
It should also require any C libraries required for development, and sometimes this means an explicit 'Requires' is needed. For example, ocaml-pcre-devel needs an explicit 'Requires: pcre-devel' to make it usable for development.
Rationale for inclusion of all cmx files: [*.cmx files] are needed even for module included in .cmxa libraries in order to enable cross-module optimizations (inlining, constant propagation and direct function calls). The .o files are not needed. [From a private email from Alain Frisch]
-doc subpackage
If the documentation files are very large they may be placed in a separate -doc subpackage.
-data subpackage
If the package contains excessively large data files, they may be placed in a separate -data subpackage.
Dependencies
No explicit dependency on ocaml itself should be needed, rpm automatically adds a versioned dependency for it.
Automatic dependencies for modules is desirable, especially considering Fedora already did the work for it: see http://fedoraproject.org/wiki/Packaging/OCaml#Requires_and_provides
