From: Stefano Zacchiroli Date: Fri, 2 Jun 2006 16:42:18 +0000 (+0000) Subject: my 0.02 EUR X-Git-Tag: archive/raspbian/4.08.1-4+rpi1~3^2~641^2~2 X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=2159c3d7c4888d72b02ae9f89bf2176d435a8242;p=ocaml.git my 0.02 EUR --- diff --git a/appendix-resources.xml b/appendix-resources.xml index ff4ccfc0..aea329b3 100644 --- a/appendix-resources.xml +++ b/appendix-resources.xml @@ -1,6 +1,6 @@ - The &ocaml-force;'s website: http://pkg-ocaml-maint.alioth.debian.org/ (it's an Alioth project) - The &ocaml-force;'s mailing list: debian-ocaml-maint@lists.debian.org (archives) + &ocaml-force;'s website: http://pkg-ocaml-maint.alioth.debian.org/ (it's an Alioth project) + &ocaml-force;'s mailing list: debian-ocaml-maint@lists.debian.org (archives) diff --git a/chapter-generalities.xml b/chapter-generalities.xml index 47e788a3..2119131e 100644 --- a/chapter-generalities.xml +++ b/chapter-generalities.xml @@ -1,12 +1,12 @@
- OCaml in Debian - - At the time of this writing, the latest version of OCaml in Debian is &ocaml-version;. - + OCaml in Debian + + At the time of this writing, the latest version of OCaml in Debian is &ocaml-version;. + - The ocaml package depends on all the basic packages needed to develop programs with OCaml. More specifically, the packaging of OCaml is split into smaller packages. The -nox packages contain libraries which don't need X (i.e., for the programs which don't use the Graphics or LablTk modules) in order to avoid dependencies on big packages for users who do not need to run graphical applications. - + The ocaml package depends on all the basic packages needed to develop programs with OCaml. More specifically, the packaging of OCaml is split into smaller packages. The packages with suffix -nox contain libraries which don't need X (i.e., for the programs which don't use the Graphics or LablTk modules) in order to avoid dependencies on big packages for users who do not need to run graphical applications. Here is the list of binary packages in which OCaml is split: + The ocaml and ocaml-nox packages contain the compiler and its libraries. @@ -14,22 +14,25 @@ - The ocaml-native-compilers package contains the OCaml compiler built in native mode (ocamlc.opt and ocamlopt.opt). - + The ocaml-native-compilers package contains the OCaml compilers built in native mode (ocamlc.opt and ocamlopt.opt). + + + The compilers themselves are built in native mode, nonetheless, both compilers for compiling toward bytecode and native code are contained in this package. + - The ocaml-base and ocaml-base-nox packages contain the runtime libraries needed by bytecode programs compiled with OCaml (in particular, the package ocaml-base-nox contains the ocamlrun program). + The ocaml-base and ocaml-base-nox packages contain the interpreter and runtime libraries needed by bytecode programs compiled with OCaml (in particular, the package ocaml-base-nox contains the ocamlrun program). - The ocaml-interp package contains the interactive command-line interpreter (ocaml). + The ocaml-interp package contains the toplevel system for OCaml (ocaml), that enables interactive use of the language. - The ocaml-mode package contains the OCaml emacs mode (the one provided with OCaml, not the tuareg mode which is in the package tuareg-mode). + The ocaml-mode package contains the OCaml Emacs mode (the one provided with OCaml, not the tuareg mode which is in the package tuareg-mode). @@ -39,22 +42,35 @@ - The ocaml-compiler-libs package contains some internal libraries of the OCaml compiler (it is needed only in very rare cases). + 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 the libraries produced by OCaml are binary incompatible when compiled with two different releases of OCaml, versionned virtual packages are also provided: ocaml-&ocaml-version;, ocaml-nox-&ocaml-version;, ocaml-base-&ocaml-version;, ocaml-base-nox-&ocaml-version;. + 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) and (2): ocaml-&ocaml-version;, ocaml-nox-&ocaml-version;, ocaml-base-&ocaml-version;, ocaml-base-nox-&ocaml-version;. + +
+ OCaml location + + The root of all installed OCaml libraries is the OCaml + standard library directory, which is + /usr/lib/ocaml/VERSION/, at the time of writing + /usr/lib/ocaml/&ocaml-version;. It can be output + by the OCaml compiler invoking it as ocamlc -where. + + +
+
Bytecode and native programs - The OCaml compiler can produce two kinds of executables: bytecode and native. The native executables (compiled with ocamlopt) are generally faster since they are compiled specifically for an achitecture. The bytecode executables (compiled with ocamlc) have the advantage of being portable, which means that a bytecode program can be run on any achitecture without needing to be rebuilt. It should be noted that native OCaml compilers are not provided for every achitecture. Only the following are suported: alpha, amd64, arm, i386, ia64, kfreebsd-i386, powerpc and sparc. + The OCaml compiler can produce two kinds of executables: bytecode and native. The native executables (compiled with ocamlopt) are generally faster since they are compiled specifically for an achitecture. The bytecode executables (compiled with ocamlc) have the advantage of being portable, which means that a bytecode program can be run on any achitecture without needing to be rebuilt. It should be noted that native OCaml compilers are not provided for every achitecture. Only the following are suported: &supported-archs;. @@ -62,7 +78,7 @@ - The ocaml-native-compilers package contains the OCaml compiler built in native mode (ocamlc.opt and ocamlopt.opt). Compiling with this version of the compiler is generally faster but, as explained before, 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 (yet) be a versioned dependency. The version dependency should thus be carried by the ocaml dependency. + The ocaml-native-compilers package contains the OCaml compiler built in native mode (ocamlc.opt, which outputs bytecode, and ocamlopt.opt, which output native code). Compiling with those versions of the compilers is generally faster. 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 (yet) be a versioned dependency. The version dependency should thus be carried by the ocaml dependency.
@@ -72,16 +88,22 @@ The &ocaml-name; compiler can produce or use the following kind of files: - bytecode executables (they can be recognised since they start with #!/usr/bin/ocamlrun) - bytecode libraries (*.cma) + bytecode executables (they can be recognised since they start with the shebang line #!/usr/bin/ocamlrun) + + bytecode executables linked in custom mode. They are generated by ocamlc (or ocamlc.opt), 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. strip should never be invoked on them, since it will remove the bytecode part. + + native executables (in ELF format) + bytecode libraries (*.cma) native libraries (*.cmxa) - shared libraries (for C bindings) (dll*.so) + shared libraries (for C bindings) (dll*.so, lib*.so) static libraries (for C bindings) (lib*.a) bytecode object files (*.cmo) native object files (*.cmx) configuration files for handling libraries with ocamlfind (META) - &camlp4; related files (*.cm[ao]) + + @@ -111,10 +133,17 @@ - The OCaml compiler first looks for a local installation of libraries and then for libraries installed by Debian packages. This section describe the standard paths for files contained in Debian packages. + 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. - - Warning: the + preceding any library in the of ocamlc or ocamlopt won't be expanded to the local standard library path. You need to specify the path entirely. - + + + The + preceding any library in the of ocamlc or ocamlopt won't be expanded to the local standard library path. You need to specify the path entirely. + + + diff --git a/chapter-libpack.xml b/chapter-libpack.xml index f11f4f39..df5d691d 100644 --- a/chapter-libpack.xml +++ b/chapter-libpack.xml @@ -2,18 +2,24 @@ Creating a package for a library - A package which provides an OCaml library xxx should be split as follows: + 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; (or ocaml-base-nox-&ocaml-version;) as well as any other library needed. The versionned dependency on ocaml-base is important since libraries are binary incompatible between releases of OCaml: basically, a library compiled with OCaml 3.08 cannot be used with OCaml &ocaml-version;. + 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; (or ocaml-base-nox-&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: libs + 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, this package should depend on them. + + libxxx-ocaml-dev packages should be in Section: libdevel + @@ -35,7 +41,14 @@ - It is recommended that libraries use the option to pack all the modules provided by the library into one module. We are not sure this really works right now for libraries, and 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 libraries use the 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 for more information on this. @@ -47,52 +60,52 @@ - If upstream developpers 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 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 developpers 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. + 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.
Handling dependencies on OCaml - Some parts of the package need to know the current version of OCaml. For example, libraries should be installed /usr/lib/ocaml/&ocaml-version;/. However, the version of OCaml should never be hardcoded in the package (&ocaml-version; here). This would make a binNMU impossible if the version of OCaml has changed. Instead .in files should be used where @OCamlABI@ is replaced at build-time by the current OCaml version. + Some parts of the package need to know the current version of OCaml. For example, libraries should be installed /usr/lib/ocaml/&ocaml-version;/. However, the current version of OCaml should never be hardcoded in the package (&ocaml-version; 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/&ocaml-version;/mad/META -usr/lib/ocaml/&ocaml-version;/mad/*.a -usr/lib/ocaml/&ocaml-version;/mad/*.cm* -usr/lib/ocaml/&ocaml-version;/mad/*.ml* + usr/lib/ocaml/&ocaml-version;/mad/META + usr/lib/ocaml/&ocaml-version;/mad/*.a + usr/lib/ocaml/&ocaml-version;/mad/*.cm* + usr/lib/ocaml/&ocaml-version;/mad/*.ml* In order to avoid the explicit mention of the version of OCaml (&ocaml-version;), 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* + 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 := $(patsubst %.in,%,$(wildcard debian/*.in)) + 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 + ocamlinit: + for f in $(OFILES); do sed -e 's/@OCamlABI@/$(OCAMLABI)/g' $$f.in > $$f; done -config.status: ocamlinit configure - [...] + config.status: ocamlinit configure + [...] -.PHONY: build clean binary-indep binary-arch binary install ocamlinit + .PHONY: build clean binary-indep binary-arch binary install ocamlinit - The only exception to this rule is the debian/control file, which should never be generated at build-time. As explained before, 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 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 , 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.
@@ -106,8 +119,8 @@ config.status: ocamlinit configure By default, &ocamlfind; will look for META in this order: - /usr/lib/ocaml/&ocaml-version;/META/ - /usr/lib/ocaml/&ocaml-version;/package/ + &ocaml-metas-dir;/ + &ocaml-sys-dir;/package/ @@ -122,7 +135,7 @@ config.status: ocamlinit configure - If the META file is placed in /usr/lib/ocaml/&ocaml-version;/META/, it should be called META.packagename, where packagename is the name of the subdirectory where the library is stored. + If the META file is placed in &ocaml-metas-dir;/, it should be called META.packagename, where packagename is the name of the subdirectory where the library is stored. @@ -133,7 +146,7 @@ config.status: ocamlinit configure - 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 ML for help. + 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. diff --git a/chapter-progpack.xml b/chapter-progpack.xml index 8e69607b..353bbe30 100644 --- a/chapter-progpack.xml +++ b/chapter-progpack.xml @@ -1,26 +1,40 @@
Creating a package for an OCaml program - Any package providing executables built from OCaml source should conform the following guidelines. + Any package providing executables built from OCaml source should conform to the following guidelines. - The package should use the name of the upstream package, without modification. + The source package should, if possible, use the name of the upstream + package without modifications. - Native versions of programs should be provided where a native compiler is available, bytecode versions should be provided elsewhere (cf. next section). + Programs which are not particularly CPU angry should be compiled in + 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. Other programs + should be compiled in native form on architectures where the native + compiler is available, and in bytecode on other architectures. + See 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, so as to not bloat the archive. However, there may be special cases, were using statically linked bytecode is necessary, in these cases, it is naturally ok to link statically. 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 will never be a valid reason to use statically linked bytecode in a Debian package. If statically linked bytecode is provided, a justification of this use should be provided in the README.Debian file. + 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. + +
Bytecode and native versions of programs - As explained before, native OCaml compilers are not available everywhere. For architecture having no native compiler, a bytecode version of the program should be provided. + As explained in , native OCaml compilers are not available everywhere. For architectures missing native compiler, a bytecode version of the program should be provided. @@ -28,7 +42,17 @@ - The avilability of a native compiler can be tested in the debian/rules file by [ -e /usr/bin/ocamlopt ], and build the bytecode version or the native version of the program according to the result of the test. + 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 + @@ -36,6 +60,26 @@ - Bytecode versions of the programs should depend on ocaml-base-nox-&ocaml-version; (or ocaml-base-&ocaml-version; 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 -s -- -VF:OCamlABI="$(OCAMLABI)" in the debian/rules file. + Bytecode versions of the programs should depend on ocaml-base-nox-&ocaml-version; (or ocaml-base-&ocaml-version; 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)" + + +
diff --git a/ocaml_packaging_policy.xml b/ocaml_packaging_policy.xml index e22c6f8e..41363ede 100644 --- a/ocaml_packaging_policy.xml +++ b/ocaml_packaging_policy.xml @@ -2,6 +2,10 @@ + + + + ocaml"> ocaml-&ocaml-version;"> @@ -14,7 +18,7 @@ ocamlopt"> ocamldoc"> ocamlfind"> -camlp4"> +CamlP4">