From: Samuel Mimram Date: Fri, 26 May 2006 13:47:33 +0000 (+0000) Subject: Some more doc. X-Git-Tag: archive/raspbian/4.08.1-4+rpi1~3^2~641^2~8 X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=4dde4b3153aa429c71e9b9e8c1ed53f55dde0aa2;p=ocaml.git Some more doc. --- diff --git a/chapter-libpack.xml b/chapter-libpack.xml index 81457daf..54b33c3e 100644 --- a/chapter-libpack.xml +++ b/chapter-libpack.xml @@ -1,3 +1,50 @@ +
+ Creating a package for a library + + + A package which provides an OCaml library 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. + + + + + 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. + + + + + + + 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 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. + +
+ +
+ Handling dependencies on OCaml + + +
+
Paths for libraries @@ -59,6 +106,7 @@
+
&camlp4; Actually, &camlp4; extensions are stored in /usr/lib/ocaml/&ocaml-version;/camlp4/. In order to do something - cleaner, &ocaml-force; propose to put this files in their own directory, even in their - own package. It is not mandatory, but it could ease a lot, the user of camlp4, by avoiding - name clash. + cleaner, &ocaml-force; proposes to put this files in their own directory, even in their + own package. It is not mandatory, but it could ease a lot by avoiding + name clashes. - You just have to consider &camlp4; file just as standard library, except that you + You just have to consider a &camlp4; file just as a standard library, except that you prefix them with -syntax. For example: the syntax extension coming with libokey-ocaml-dev should be stored in /usr/lib/ocaml/&ocaml-version;/okey-syntax/, the package @@ -141,35 +190,34 @@ Documentation The documentation is a joint effort of &ocaml-force; and usptream. - There is many way to have documentation : + There are many ways to have documentation: - Header files (*.mli) - Source files (*.ml) - Specific documentation provided by the upstream - OCamldoc generated documentation + header files (*.mli), + source files (*.ml), + specific documentation provided by the upstream, + OCamldoc generated documentation. - This documentation should be browse by different mean, from the - most simple to the most complex. At least, they could all be browsed with - simple text editor. Specific and &ocamldoc; generated documentation should - be browse by using different viewer ( like advi, - HTML browser...). There is also at least two + This documentation should be browsable by different mean, from the + most simple to the most complex. At least, they should all be readable with + simple text editor. Specific and &ocamldoc; generated documentations should be provided in HTML format. + There are also at least two specific &ocaml-name; browser : docbrowse shipped with cameleon and ocamlbrowser - shipped with &ocaml-name; itself. The first one, need specific + shipped with &ocaml-name; itself. The first one, needs specific &ocamldoc; generated documentation. The second one enables - the user to browse directly the prototype of each function shipped in the cmi gives + the user to browse directly the prototype of each function shipped in the cmi gives to the application. - You can generate &ocamldoc; specific documentation by using + You can generate &ocamldoc;-specific documentation by using the of this application. By using this, you dump the intermediary 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 ). + file (using ). diff --git a/chapter-progpack.xml b/chapter-progpack.xml index 2a671e27..44447ab5 100644 --- a/chapter-progpack.xml +++ b/chapter-progpack.xml @@ -1,6 +1,25 @@
- Packaging OCaml prgrams + Creating a package for an OCaml program - blah + 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. + + +