From Mageia wiki
Jump to: navigation, search

This page describes Mageia's OCaml policy. It mainly concerns the OCaml libraries.

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 Mageia packaging policy..

The packager should check the META file (ref: Findlib users guide - writing META files.). 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 (or contains ocamldoc documentation) 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. [Private email from Alain Frisch to Richard Jones]

-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

Dependency on ocaml-compiler is not necessary. Dependencies between modules should however be explicitely enforced.

There are some tools for generating automatic dependencies for modules, used (and developed) by Fedora: see http://fedoraproject.org/wiki/Packaging/OCaml#Requires_and_provides It however introduces dozens of provides and requires that make error messages extremely long and painful to debug. For now, dependencies are handled by hand.

And how it is handled in Debian is explained in this document:

Other ressources


NB: This page is initially coming from Mandriva's OCaml policy, itself inspired by Fedora's.