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

The OCaml compilers can produce two kinds of executables: bytecode and native. Native executables are usual ELF executables produced for a particular CPU architecture, while pure bytecode executables are written in a language which can only be run on a OCaml bytecode interpreter. A pure bytecode executable starts with a magic string invoking the interpreter, so that bytecode executables can just be invoked like native executables. There are also “custom” bytecode executables, which embed a bytecode program along with a bytecode interpreter; these files are ELF executables. OCaml compilers to native code are not provided for every architecture. On a Debian system, the list of architectures for which the currently installed version of the OCaml system provides compilation to native code can be found in the file /usr/lib/ocaml/native-archs.

Native executables are in general faster to execute than bytecode executables since they are compiled specifically for an architecture. Bytecode executables are smaller than native code executables. If considering only one process the advantage in size is annihilated by the need for the OCaml runtime system for executing bytecode, however there is an advantage when running several bytecode processes in parallel since the runtime system can then be shared.

Pure bytecode executables have the advantage of being portable, which means that a pure bytecode executable can usually be run without having to be recompiled on any architecture for which an OCaml bytecode interpreter is available. For Debian, this has the advantage that packages containing only bytecode executables have Architecture=all, which reduces archive space and auto-builder load. It also reduces download and installation size for users in case they install several bytecode packages.

An important decision to take when building a Debian package is whether to support bytecode, native code, or both. We aim to support development both of bytecode and native code applications, hence libraries should be distributed both in bytecode and native code (see the section on library packaging). For packages containing executables, the rule is:

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

Packages containing executables (as opposed to libraries) may be produced by compiling to bytecode, native code, or both. See this discussion of which mode to choose.

Package containing only bytecode executable, native executable or data are simple binary package, as explained previously.

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

All bytecode executables should be linked dynamically against the shared libraries for C bindings, to not bloat the archive. That said, upstream authors often favor statically linked bytecode executables (ocamlc option -custom), because in this case they don't need to worry about the presence of the dll stub libraries. This is not a valid reason to use statically linked bytecode in a Debian package where package dependencies can fix this problem.

A bytecode package must depend on the runtime package that is required to run it. Typically, it should depend on ocaml-base-nox-[ocaml-version] (or ocaml-base-[ocaml-version], if if the program uses the Graphics module). It can also depends on the virtual libXXX-ocaml-byte-ABCD provided by the runtime package libXXX-ocaml (see the section on binary dependencies).

A bytecode package must build-depend-indep on ocaml-nox (or ocaml if the program uses the Graphics module).

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. Custom bytecode executable is a deprecated feature of OCaml -- for now they still exist but should be avoided.

Bytecode programs should not be compiled for debugging, i.e. they should not be compiled using the -g option to ocamlc.

Native OCaml compilers are not available on all architecures. For architectures missing native compiler, a bytecode version of the program should be provided. Native code packages are specific to an architecture, that is they have Architecture=any in the source package.

The debian/rules file 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. As a consequence, the rules of the section called “Bytecode packages” also apply here.

It is safe to consider that detection of native architecture means availability of ocamlopt or ocamlopt.opt when building.

This should be done only under exceptional circumstances. Packages providing both native and bytecode versions of a program prog usually name them respectively prog.opt and prog.byte and provide a symbolic link prog to the best available version (generally prog.opt). Please consult the rules of the section called “Bytecode packages” and the section called “Native versions of programs”.

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/ or in a subdirectory of this directory. This includes in particular bytecode libraries (*.cma), native libraries (*.cmxa, *.a), native plugins (*.cmxs), bytecode object files (*.cmo), native object files (*.cmx, *.o), 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/stublibs, as can it be seen in the /usr/lib/ocaml/ld.conf file.

If upstream developers already use a subdirectory of the OCaml standard library path then 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 do not use this scheme then 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 the 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.

The ocaml-findlib provides a tool (called 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 organization 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:

If a library package creates its own subdirectory /usr/lib/ocaml/package/ then the META file should be stored in that directory.

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/lablgtk/META, where /usr/lib/ocaml is the main OCaml installation directory and lablgtk is the lablgtk library directory.

If upstream doesn't provide a META then packagers are encouraged to create one. In this case, the META file should contain a comment like this, so that developers will know that they shouldn't count on the availability of a META file on non-Debian machines:

	# This META file is delivered by the Debian distribution.
      

Furthermore, the META file should be sent to the upstream authors in order to have it included in future versions of the upstream source. For more information about META files see 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 like standard OCaml libraries. In particular, they should provide a META file. The syntax extension should be contained in a syntax sub package.

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 libraries then 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 upstream. There are many ways to have documentation:

This documentation should be browsable by different means, from the most simple to the most complex one. At least, they should all be readable with a simple text editor. Specific and ocamldoc generated documentations should be provided in HTML format.

You can generate ocamldoc-specific documentation by using the -dump option of this command. By using this, you dump the intermediate 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).