--- /srv/reproducible-results/rbuild-debian/r-b-build.BkyJpxj9/b1/dh-ocaml_2.4_amd64.changes +++ /srv/reproducible-results/rbuild-debian/r-b-build.BkyJpxj9/b2/dh-ocaml_2.4_amd64.changes ├── Files │ @@ -1,2 +1,2 @@ │ │ - fd217c39ca350e6f532982f9afdb59a7 55816 ocaml optional dh-ocaml_2.4_all.deb │ + 6f58894cd4e9e546b4bfe06f5d105285 62920 ocaml optional dh-ocaml_2.4_all.deb ├── dh-ocaml_2.4_all.deb │ ├── file list │ │ @@ -1,3 +1,3 @@ │ │ -rw-r--r-- 0 0 0 4 2024-09-26 07:25:54.000000 debian-binary │ │ -rw-r--r-- 0 0 0 1744 2024-09-26 07:25:54.000000 control.tar.xz │ │ --rw-r--r-- 0 0 0 53880 2024-09-26 07:25:54.000000 data.tar.xz │ │ +-rw-r--r-- 0 0 0 60984 2024-09-26 07:25:54.000000 data.tar.xz │ ├── control.tar.xz │ │ ├── control.tar │ │ │ ├── ./control │ │ │ │ @@ -1,12 +1,12 @@ │ │ │ │ Package: dh-ocaml │ │ │ │ Version: 2.4 │ │ │ │ Architecture: all │ │ │ │ Maintainer: Debian OCaml Maintainers │ │ │ │ -Installed-Size: 205 │ │ │ │ +Installed-Size: 212 │ │ │ │ Depends: libconfig-tiny-perl │ │ │ │ Recommends: debhelper, ocaml │ │ │ │ Suggests: git │ │ │ │ Provides: dh-sequence-ocaml │ │ │ │ Section: ocaml │ │ │ │ Priority: optional │ │ │ │ Multi-Arch: foreign │ │ │ ├── ./md5sums │ │ │ │ ├── ./md5sums │ │ │ │ │┄ Files differ │ ├── data.tar.xz │ │ ├── data.tar │ │ │ ├── file list │ │ │ │ @@ -13,15 +13,15 @@ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2024-09-26 07:25:54.000000 ./usr/share/doc/ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2024-09-26 07:25:54.000000 ./usr/share/doc/dh-ocaml/ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 1338 2024-09-26 07:25:54.000000 ./usr/share/doc/dh-ocaml/README.Debian │ │ │ │ -rw-r--r-- 0 root (0) root (0) 1 2024-09-26 07:25:54.000000 ./usr/share/doc/dh-ocaml/TODO │ │ │ │ -rw-r--r-- 0 root (0) root (0) 1318 2024-09-26 07:25:54.000000 ./usr/share/doc/dh-ocaml/changelog.gz │ │ │ │ -rw-r--r-- 0 root (0) root (0) 896 2024-09-26 07:25:54.000000 ./usr/share/doc/dh-ocaml/copyright │ │ │ │ -rw-r--r-- 0 root (0) root (0) 54781 2024-09-26 07:25:54.000000 ./usr/share/doc/dh-ocaml/ocaml_packaging_policy.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 2329 2024-09-26 07:25:54.000000 ./usr/share/doc/dh-ocaml/ocaml_packaging_policy.txt.gz │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 9330 2024-09-26 07:25:54.000000 ./usr/share/doc/dh-ocaml/ocaml_packaging_policy.txt.gz │ │ │ │ -rw-r--r-- 0 root (0) root (0) 25674 2024-09-26 07:25:54.000000 ./usr/share/doc/dh-ocaml/ocaml_packaging_reference.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 4851 2024-09-26 07:25:54.000000 ./usr/share/doc/dh-ocaml/ocaml_packaging_reference.txt.gz │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2024-09-26 07:25:54.000000 ./usr/share/doc/ocaml/ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2024-09-26 07:25:54.000000 ./usr/share/doc/ocaml-base/ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2024-09-26 07:25:54.000000 ./usr/share/doc-base/ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 590 2024-09-26 07:25:54.000000 ./usr/share/doc-base/dh-ocaml.ocaml-packaging-policy │ │ │ │ -rw-r--r-- 0 root (0) root (0) 663 2024-09-26 07:25:54.000000 ./usr/share/doc-base/dh-ocaml.ocaml-packaging-reference │ │ │ ├── ./usr/share/doc/dh-ocaml/ocaml_packaging_policy.txt.gz │ │ │ │ ├── ocaml_packaging_policy.txt │ │ │ │ │ @@ -162,8 +162,513 @@ │ │ │ │ │ * If the execution of the program is very fast on typical application │ │ │ │ │ cases then the program contained in the package should be compiled │ │ │ │ │ to bytecode. Typical examples are hevea, or headache. See the │ │ │ │ │ section on bytecode packages. │ │ │ │ │ * Only in special cases, for instance when both versions provide │ │ │ │ │ different features, should a package contain programs both compiled │ │ │ │ │ to bytecode and native code. See the section on combined bytecode │ │ │ │ │ - and native code p │ │ │ │ │ + and native code packages. │ │ │ │ │ + │ │ │ │ │ +Overview of the OCaml compilers │ │ │ │ │ + │ │ │ │ │ +Bytecode and native code compilers │ │ │ │ │ + │ │ │ │ │ + The ocaml-native-compilers package contains the OCaml compiler │ │ │ │ │ + executables built in native mode: ocamlc.opt, which produces bytecode, │ │ │ │ │ + and ocamlopt.opt, which produces native code. Since the OCaml compilers │ │ │ │ │ + are themselves written in OCaml this package exists only on │ │ │ │ │ + architectures where compilation to native code is supported. │ │ │ │ │ + │ │ │ │ │ + The ocaml package contains the OCaml compiler executables built in │ │ │ │ │ + bytecode mode: ocamlc, which produces bytecode, and on architectures │ │ │ │ │ + where compilation to native code is supported the compiler ocamlopt, │ │ │ │ │ + which produces native code. It is important to understand that on │ │ │ │ │ + architectures where compilation to native code is supported both │ │ │ │ │ + packages contain compilers from OCaml to both bytecode and native code, │ │ │ │ │ + the difference lies in the nature (installation size and execution │ │ │ │ │ + speed) of the compiler executables. │ │ │ │ │ + │ │ │ │ │ + Table 1.1. OCaml compilers │ │ │ │ │ + Compiles to bytecode Compiles to native code │ │ │ │ │ + Compiler executable in bytecode ocamlc ocamlopt │ │ │ │ │ + Compiler executable in native code ocamlc.opt ocamlopt.opt │ │ │ │ │ + │ │ │ │ │ + See the section called “Bytecode and native code” on a discussion │ │ │ │ │ + whether to produce native code or bytecode. │ │ │ │ │ + │ │ │ │ │ +Files used and produced by the OCaml compilers │ │ │ │ │ + │ │ │ │ │ + The OCaml toolchain can produce or use the following kind of files: │ │ │ │ │ + * pure bytecode executables (they can be recognized since they start │ │ │ │ │ + with the shebang line #!/usr/bin/ocamlrun) │ │ │ │ │ + * bytecode executables linked in custom mode. They are generated by │ │ │ │ │ + ocamlc when the -custom flag is given at link time. Those │ │ │ │ │ + executables are in ELF format and include both the final bytecode │ │ │ │ │ + and the bytecode interpreter. The strip command should never be │ │ │ │ │ + invoked on them since it will remove the bytecode part. Bytecode │ │ │ │ │ + executables linked in custom mode are depreciated and should be │ │ │ │ │ + avoided. │ │ │ │ │ + * native executables (in ELF format) │ │ │ │ │ + * bytecode libraries (*.cma, *.a) │ │ │ │ │ + * native libraries (*.cmxa) │ │ │ │ │ + * shared libraries (for C bindings) (dll*.so, lib*.so) │ │ │ │ │ + * static libraries (for C bindings) (lib*.a) │ │ │ │ │ + * bytecode object files (*.cmo) │ │ │ │ │ + * native object files (*.cmx, *.o) │ │ │ │ │ + * native plugin object files (*.cmxs) │ │ │ │ │ + * configuration files for handling libraries with ocamlfind (META) │ │ │ │ │ + │ │ │ │ │ +Building packages using OCaml │ │ │ │ │ + │ │ │ │ │ +Findlib and ocamlfind │ │ │ │ │ + │ │ │ │ │ + The Debian OCaml Task Force has chosen to fully support the findlib │ │ │ │ │ + library. This is a suite of tools and libraries that help to manage │ │ │ │ │ + OCaml libraries. This software is not specific to Debian and works on │ │ │ │ │ + all platforms where OCaml is available. Through the years, this has │ │ │ │ │ + become the de facto standard when relying on external libraries. The │ │ │ │ │ + main frontend is called ocamlfind and provided by the package │ │ │ │ │ + ocaml-findlib. │ │ │ │ │ + │ │ │ │ │ + Even though compiling OCaml projects in Debian is still possible │ │ │ │ │ + without ocamlfind it is highly recommended to use it. │ │ │ │ │ + │ │ │ │ │ +The OCaml system in Debian │ │ │ │ │ + │ │ │ │ │ + There are three categories of OCaml packages in Debian: │ │ │ │ │ + * Development packages contain OCaml objects required for the │ │ │ │ │ + development or compilation of OCaml programs, or specifically for │ │ │ │ │ + the creation of Debian packages containing OCaml programs. │ │ │ │ │ + * Runtime packages contain OCaml objects necessary to run compiled │ │ │ │ │ + programs. A runtime package is always associated with a development │ │ │ │ │ + package. │ │ │ │ │ + * Simple binary packages contain everything that does not fall into │ │ │ │ │ + the two former categories. This includes bytecode and native │ │ │ │ │ + executable of application programs, documentation, etc. │ │ │ │ │ + │ │ │ │ │ + The ocaml package depends on all the basic packages needed to develop │ │ │ │ │ + programs with OCaml. Here is the list of binary packages into which the │ │ │ │ │ + OCaml system is organized: │ │ │ │ │ + 1. The ocaml package contain the compiler and its libraries. It can be │ │ │ │ │ + considered as a development package. │ │ │ │ │ + 2. The ocaml-native-compilers package contains the OCaml compilers │ │ │ │ │ + built in native mode (ocamlc.opt and ocamlopt.opt). │ │ │ │ │ + │ │ │ │ │ +Note │ │ │ │ │ + The compilers themselves are built in native mode, nonetheless, │ │ │ │ │ + both compilers for compiling toward bytecode and native code are │ │ │ │ │ + contained in this package. │ │ │ │ │ + 3. The ocaml-base package contains the interpreter and runtime │ │ │ │ │ + libraries needed by bytecode programs compiled with OCaml (in │ │ │ │ │ + particular, it contains the ocamlrun program). It can be considered │ │ │ │ │ + as the runtime package associated to ocaml. │ │ │ │ │ + │ │ │ │ │ +Note │ │ │ │ │ + ocaml-base contains also OCaml interface objects *.cmi, which are │ │ │ │ │ + normally only in development packages because they are needed to │ │ │ │ │ + run the ocaml toplevel from the package ocaml-interp. │ │ │ │ │ + 4. The ocaml-interp package contains the toplevel system for OCaml │ │ │ │ │ + (ocaml) which provides for an interactive interpreter of the │ │ │ │ │ + language. │ │ │ │ │ + 5. The ocaml-mode package contains the OCaml Emacs mode. This is the │ │ │ │ │ + original Emacs mode provided with the OCaml upstream distribution, │ │ │ │ │ + not to be confused with the tuareg Emacs mode which is in the │ │ │ │ │ + package tuareg-mode. │ │ │ │ │ + 6. The ocaml-source package contains the sources of the OCaml │ │ │ │ │ + compiler. │ │ │ │ │ + 7. The ocaml-compiler-libs package contains some internal libraries of │ │ │ │ │ + the OCaml compiler (needed only in very rare cases, e.g. for │ │ │ │ │ + developing languages which reuse OCaml internals). │ │ │ │ │ + │ │ │ │ │ + Since libraries produced by OCaml are binary incompatible when compiled │ │ │ │ │ + with different releases of OCaml, versioned virtual packages are also │ │ │ │ │ + provided by packages at items (1), (2), (6) and (7): │ │ │ │ │ + ocaml-[ocaml-version], etc. │ │ │ │ │ + │ │ │ │ │ +Choosing the right build dependencies │ │ │ │ │ + │ │ │ │ │ + Compiling with native code versions of the compilers is generally │ │ │ │ │ + faster than with compilers in bytecode. Unfortunately, the │ │ │ │ │ + ocaml-native-compilers package is not available on every architecture. │ │ │ │ │ + Packages should therefore never depend directly on this package. In │ │ │ │ │ + order to build big programs and benefit from this natively built │ │ │ │ │ + compiler, packages should depend on ocaml-best-compilers which itself │ │ │ │ │ + depends on ocaml-native-compilers where available and on ocaml │ │ │ │ │ + elsewhere. Since it is a virtual package, it cannot be a versioned │ │ │ │ │ + dependency. The version dependency should thus be carried by the ocaml │ │ │ │ │ + dependency. Note that dependency on ocaml-best-compilers is only │ │ │ │ │ + necessary for really big programs for which compilation takes a lot of │ │ │ │ │ + resources. For most small programs the compilers from the ocaml package │ │ │ │ │ + are perfectly sufficient, and faster to install in a build environment │ │ │ │ │ + than compiler executables in native code. │ │ │ │ │ + │ │ │ │ │ +Putting the right binary dependencies │ │ │ │ │ + │ │ │ │ │ + Bytecode is specific to an upstream version of the OCaml system. │ │ │ │ │ + Therefore, any package containing bytecode has to depend directly or │ │ │ │ │ + indirectly on the packages providing the OCaml runtime system in │ │ │ │ │ + precisely the version for which it was compiled (for instance, │ │ │ │ │ + ocaml-base-[ocaml-version].) This is in particular the case for │ │ │ │ │ + bytecode programs, but it is also the case for native code programs on │ │ │ │ │ + the architectures on which there is no native code OCaml compiler, and │ │ │ │ │ + on which the program will be actually compiled to bytecode (see the │ │ │ │ │ + section on packaging native code programs). The exact dependencies of │ │ │ │ │ + libraries packages are discussed in the chapter on library packaging. │ │ │ │ │ + │ │ │ │ │ + In order for a package to be easily rebuild, or even binNMUed, in case │ │ │ │ │ + of a transition from one OCaml version to another, these dependencies │ │ │ │ │ + must not be hardcoded in debian/control. Instead, substitution │ │ │ │ │ + variables must be used which are instantiated from the debian/rules │ │ │ │ │ + file. See the discussion on build systems in the Debian OCaml │ │ │ │ │ + Developers Reference for a discussion how this can be achieved. │ │ │ │ │ + │ │ │ │ │ +Dh_ocaml │ │ │ │ │ + │ │ │ │ │ + The Debian OCaml Task Force has created a system to compute │ │ │ │ │ + dependencies between OCaml packages and to ensure type-safe linking. It │ │ │ │ │ + requires to use new substitution variables in debian/control: │ │ │ │ │ + * Use the ${ocaml:Depends} substitution variable in the field │ │ │ │ │ + Depends. │ │ │ │ │ + * Add a field Provides: ${ocaml:Provides} in development and runtime │ │ │ │ │ + packages. │ │ │ │ │ + │ │ │ │ │ + More detailed information about this work can be found here. │ │ │ │ │ + │ │ │ │ │ +Integrating OCaml packages in Debian │ │ │ │ │ + │ │ │ │ │ +Location of OCaml directories │ │ │ │ │ + │ │ │ │ │ + The root of all installed OCaml libraries is the OCaml standard library │ │ │ │ │ + directory, which is /usr/lib/ocaml. This location can be obtained from │ │ │ │ │ + the OCaml compiler by invoking it as ocamlc -where. │ │ │ │ │ + │ │ │ │ │ +Debian archive section │ │ │ │ │ + │ │ │ │ │ + Packages intended for the development of OCaml programs or packages, as │ │ │ │ │ + well as packages necessary for the execution of OCaml code (like │ │ │ │ │ + runtime systems or libraries) should have their section set to ocaml. │ │ │ │ │ + │ │ │ │ │ + End user applications that are not specifically aiming at OCaml │ │ │ │ │ + development or execution support but just happen to be implemented in │ │ │ │ │ + OCaml should have their section set according to their application │ │ │ │ │ + domain (games, science, etc.). General development tools that are not │ │ │ │ │ + specific to OCaml development go into section devel (example: │ │ │ │ │ + headache). │ │ │ │ │ + │ │ │ │ │ +Documentation │ │ │ │ │ + │ │ │ │ │ + Documentation relevant to programming in OCaml should be registered │ │ │ │ │ + with doc-base in Section Programming/OCaml. This is the case for API │ │ │ │ │ + documentation generated using ocamldoc. See the section on generating │ │ │ │ │ + documentation. │ │ │ │ │ + │ │ │ │ │ +Chapter 2. Packaging OCaml programs │ │ │ │ │ + │ │ │ │ │ + Table of Contents │ │ │ │ │ + │ │ │ │ │ + Creating packages for OCaml programs │ │ │ │ │ + Bytecode packages │ │ │ │ │ + Native versions of programs │ │ │ │ │ + Bytecode and native versions of programs │ │ │ │ │ + │ │ │ │ │ +Creating packages for OCaml programs │ │ │ │ │ + │ │ │ │ │ + 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. │ │ │ │ │ + │ │ │ │ │ +Bytecode packages │ │ │ │ │ + │ │ │ │ │ + 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-[ocaml-version]. │ │ │ │ │ + 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. │ │ │ │ │ + │ │ │ │ │ + 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 versions of programs │ │ │ │ │ + │ │ │ │ │ + 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. │ │ │ │ │ + │ │ │ │ │ +Bytecode and native versions of programs │ │ │ │ │ + │ │ │ │ │ + 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”. │ │ │ │ │ + │ │ │ │ │ +Chapter 3. Packaging OCaml libraries │ │ │ │ │ + │ │ │ │ │ + Table of Contents │ │ │ │ │ + │ │ │ │ │ + Creating packages for OCaml libraries │ │ │ │ │ + Paths for libraries │ │ │ │ │ + Providing META files │ │ │ │ │ + Camlp4/Camlp5 │ │ │ │ │ + Documentation │ │ │ │ │ + │ │ │ │ │ +Creating packages for OCaml libraries │ │ │ │ │ + │ │ │ │ │ + A package which provides an OCaml library called xxx should be split as │ │ │ │ │ + follows: │ │ │ │ │ + * For libraries which are not purely programmed in OCaml (e.g. C │ │ │ │ │ + bindings), libxxx-ocaml should provide the shared library stubs │ │ │ │ │ + (dll*.so), and all other stuff needed to run a bytecode executable │ │ │ │ │ + that links into this library. It should depend on │ │ │ │ │ + ocaml-base-[ocaml-version] as well as any other library needed. The │ │ │ │ │ + versioned dependency on ocaml-base is important since libraries are │ │ │ │ │ + binary incompatible between releases of OCaml. │ │ │ │ │ + libxxx-ocaml packages should be in Section: ocaml. │ │ │ │ │ + If the library provides native plugins (*.cmxs) or is meant to be │ │ │ │ │ + dynamically loaded using the Dynlink library, those plugins, │ │ │ │ │ + relevant *.cmo or *.cma files, and the META file referencing them │ │ │ │ │ + should also be provided by this runtime package. │ │ │ │ │ + * libxxx-ocaml-dev should provide the rest of the library package, in │ │ │ │ │ + fact anything needed to develop programs using the library. If the │ │ │ │ │ + library uses other libraries or C libraries then this package │ │ │ │ │ + should depend on them. │ │ │ │ │ + libxxx-ocaml-dev should depend on its companion libxxx-ocaml │ │ │ │ │ + package (if any). The reason is that at compile time the OCaml │ │ │ │ │ + compiler will try to load the shared library stubs, aborting the │ │ │ │ │ + compilation in case of failure. Hence the development package is │ │ │ │ │ + useless if the corresponding stub package is missing. To ensure │ │ │ │ │ + compatibility the dependency among the two packages should be │ │ │ │ │ + strictly versioned. In order for the resulting packages to be │ │ │ │ │ + binNMU safe this requirement states that the dependency should make │ │ │ │ │ + use of a ${binary:Version} substitution variable. │ │ │ │ │ + Example 3.1. Dependency from a -dev package to its companion shared │ │ │ │ │ + library stub package (if any), from the pcre-ocaml package │ │ │ │ │ + Package: libpcre-ocaml │ │ │ │ │ + Architecture: any │ │ │ │ │ + Section: ocaml │ │ │ │ │ + Depends: ocaml-base-[ocaml-version], ${shlibs:Depends}, ${misc:Depends} │ │ │ │ │ + ... │ │ │ │ │ + │ │ │ │ │ + Package: libpcre-ocaml-dev │ │ │ │ │ + Architecture: any │ │ │ │ │ + Section: ocaml │ │ │ │ │ + Depends: ocaml-[ocaml-version], libpcre3-dev (>= 4.5), libpcre-ocaml (= ${bina │ │ │ │ │ +ry:Version}), ${misc:Depends} │ │ │ │ │ + Suggests: ocaml-findlib (>= 1.1) │ │ │ │ │ + ... │ │ │ │ │ + │ │ │ │ │ + libxxx-ocaml-dev packages should be in Section: ocaml │ │ │ │ │ + All OCaml bytecode libraries (*.cma) and bytecode object files │ │ │ │ │ + (*.cmo) should be compiled for debugging, i.e. they should be │ │ │ │ │ + compiled passing the -g option to ocamlc (or ocamlc.opt). │ │ │ │ │ + │ │ │ │ │ + Optionally, two other packages may be created: │ │ │ │ │ + * 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. │ │ │ │ │ + │ │ │ │ │ + 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. │ │ │ │ │ + │ │ │ │ │ +Paths for libraries │ │ │ │ │ + │ │ │ │ │ + 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. │ │ │ │ │ + │ │ │ │ │ +Providing META files │ │ │ │ │ + │ │ │ │ │ + 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: │ │ │ │ │ + * /usr/lib/ocaml/METAS/ │ │ │ │ │ + * /usr/lib/ocaml/package/ │ │ │ │ │ + │ │ │ │ │ + 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. │ │ │ │ │ + * If the META file is placed in the subdirectory of the package then │ │ │ │ │ + it should be called META. │ │ │ │ │ + * If the META file is placed in /usr/lib/ocaml/METAS/ then it should │ │ │ │ │ + be called META.packagename, where packagename is the name of the │ │ │ │ │ + subdirectory where the library is stored. │ │ │ │ │ + │ │ │ │ │ + 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. │ │ │ │ │ + │ │ │ │ │ +Camlp4/Camlp5 │ │ │ │ │ + │ │ │ │ │ + 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-. │ │ │ │ │ + │ │ │ │ │ +Documentation │ │ │ │ │ + │ │ │ │ │ + The documentation is a joint effort of The Debian OCaml Task Force and │ │ │ │ │ + upstream. There are many ways to have documentation: │ │ │ │ │ + * header files (*.mli), │ │ │ │ │ + * source files (*.ml), │ │ │ │ │ + * specific documentation provided by the upstream, │ │ │ │ │ + * OCamldoc generated 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). │ │ │ │ │ + │ │ │ │ │ +Appendix A. Appendix │ │ │ │ │ + │ │ │ │ │ + Table of Contents │ │ │ │ │ + │ │ │ │ │ + Locally installing OCaml programs and libraries │ │ │ │ │ + │ │ │ │ │ +Locally installing OCaml programs and libraries │ │ │ │ │ + │ │ │ │ │ + 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: │ │ │ │ │ + * Executable files should be installed in /usr/local/bin. │ │ │ │ │ + * Shared libraries (for C bindings) should be installed in │ │ │ │ │ + /usr/local/lib/ocaml/stublibs/ │ │ │ │ │ + * Basically, every other file should be installed in │ │ │ │ │ + /usr/local/lib/ocaml/. This includes in particular bytecode │ │ │ │ │ + libraries (*.cma), native libraries (*.cmxa), bytecode object files │ │ │ │ │ + (*.cmo), native object files (*.cmx), native plugin object files │ │ │ │ │ + (*.cmxs), static libraries (*.a) and META files. │ │ │ │ │ + │ │ │ │ │ + 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. │ │ │ │ │ + │ │ │ │ │ +Warning │ │ │ │ │ + │ │ │ │ │ + The + preceding any library in the -I of ocamlc or ocamlopt won't be │ │ │ │ │ + expanded to the local standard library path. You need to specify the │ │ │ │ │ + path entirely.