From: Samuel Mimram Date: Sat, 27 May 2006 11:25:09 +0000 (+0000) Subject: Some more doc. X-Git-Tag: archive/raspbian/4.08.1-4+rpi1~3^2~641^2~7 X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=a0458c0be2664a37a4b51c957b61b6850311b3b8;p=ocaml.git Some more doc. --- diff --git a/appendix-resources.xml b/appendix-resources.xml index c5b1e4ef..a7e130a9 100644 --- a/appendix-resources.xml +++ b/appendix-resources.xml @@ -1,6 +1,22 @@ + + + + The &ocaml-force;'s website: http://pkg-ocaml-maint.alioth.debian.org/ + The &ocaml-force;'s mailing list: debian-ocaml-maint@lists.debian.org + + + + + + + + + + diff --git a/chapter-generalities.xml b/chapter-generalities.xml index a49a478b..68b6ef35 100644 --- a/chapter-generalities.xml +++ b/chapter-generalities.xml @@ -5,64 +5,64 @@ - 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 too big dependencies for users who don't have and X server installed. + 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 too big dependencies for users who don't have an X server installed. - The ocaml and ocaml-nox package contain the compiler and its libraries. + The ocaml and ocaml-nox packages contain the compiler and its libraries. - The ocaml-native-compilers contains the OCaml compiler built in native mode. + The ocaml-native-compilers package contains the OCaml compiler built in native mode (ocamlc.opt and ocamlopt.opt). - The ocaml-base and ocaml-base-nox packages contain the runtime libraries needed by bytecode programs compiled with OCaml (in particular it contains the ocamlrun program). + 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-interp contains the interactive command-line interpreter. + The ocaml-interp package contains the interactive command-line interpreter (ocaml). - The ocaml-mode contains the OCaml emacs mode (the one provided with OCaml, not the 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). - The ocaml-source contains the sources of the OCaml compiler. + The ocaml-source package contains the sources of the OCaml compiler. - The ocaml-compiler-libs 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 (it is needed only in very rare cases). - Since the libraries produced by OCaml are binary incompatible when compiled with two different releases of OCaml, versionned virtual packages are provided: ocaml-&ocaml-version;, ocaml-nox-&ocaml-version;, ocaml-base-&ocaml-version;, ocaml-base-nox-&ocaml-version;. + 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;. -
- Native and bytecode programs +
+ 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. - Package 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). + 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). - 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. In order to build big programs and benefit from this natively built compiler, packages should depend on ocaml-best-compilers which depends on ocaml-native-compilers where available and on ocaml elsewhere. + 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.
diff --git a/chapter-libpack.xml b/chapter-libpack.xml index 54b33c3e..b42111f8 100644 --- a/chapter-libpack.xml +++ b/chapter-libpack.xml @@ -195,7 +195,7 @@ header files (*.mli), source files (*.ml), specific documentation provided by the upstream, - OCamldoc generated documentation. + OCamldoc generated documentation. diff --git a/chapter-progpack.xml b/chapter-progpack.xml index 44447ab5..07dcee58 100644 --- a/chapter-progpack.xml +++ b/chapter-progpack.xml @@ -1,25 +1,41 @@
Creating a package for an OCaml program - Any package providing executables built from OCaml source should conform - the following regulations. - - - - - The package should use the name of the upstream package, without modification. - - - - - The package's debian/rules 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. The availability of a native compiler can be tested by [ -e /usr/bin/ocamlopt ]. Exceptions to this are the executables who are small or not time critical, which may be built only as bytecode. It is the decision of the individual maintainers to choose this, maybe guided by the practice of the upstream author. - - - - - All bytecode executables should be link 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. - - - + Any package providing executables built from OCaml source should conform the following guidelines. + + + + The package should use the name of the upstream package, without modification. + + + + Native versions of programs should be provided where a native compiler is available, bytecode versions should be provided elsewhere (cf. next section). + + + + 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. + +
+ +
+ 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. + + + + The package's debian/rules 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. Exceptions to this are the executables who are small or not time critical, which may be built only as bytecode. It is the decision of the individual maintainers to choose this, maybe guided by the practice of the upstream author. + + + + 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 bytecode versions are portable. In order to spare the buildds and the Debian archive, bytecode versions should be compiled once for all for big packages (which either take a lot of place on disks or take a lot of time to build). For example, the spamoracle package provides the spamoracle-byte package which is Architecture: all and contains the bytecode version of spamoracle, and the spamoracle package which contains the native version of spamoracle and is available only where a native OCaml compiler is available (Architecture: alpha amd64 arm i386 ia64 kfreebsd-i386 powerpc sparc). + + + + 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 really hardocoded 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.