From: Sylvain Le Gall Date: Thu, 23 Oct 2003 21:53:18 +0000 (+0000) Subject: More definition... X-Git-Tag: archive/raspbian/4.08.1-4+rpi1~3^2~641^2~17 X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=e4d14d6f7c13d10510627c65ce255ec7fec2294f;p=ocaml.git More definition... Sylvain LE GALL --- diff --git a/chapter-ocaml.xml b/chapter-ocaml.xml index 6c3fd349..ceb4180a 100644 --- a/chapter-ocaml.xml +++ b/chapter-ocaml.xml @@ -1,13 +1,13 @@
Version - At any given time, the package ocaml - should represent the current stable upstream version of &ocaml-name; + At any given time, the package &ocaml-pkg; should represent + the current stable upstream version of &ocaml-name; revision &ocaml-version;. - This package provides a virtual package called &ocaml-pkg;. + This package provides a virtual package called &ocaml-vpkg;. This will help to track incompatible changes made within the same version of &ocaml-name;. @@ -18,13 +18,13 @@ Base Package In order to have a minimal installation, a virtual package - ocaml-base exists. It enable to have + &ocaml-base-vpkg; exists. It enable to have a bare minimum install of &ocaml-name; library. - As for ocaml this package provides - a virtual package &ocaml-base-pkg;. This will help to track + As for &ocaml-pkg; this package provides + a virtual package &ocaml-base-vpkg;. This will help to track incompatible changes made within the same version of &ocaml-name;. @@ -37,31 +37,31 @@ &ocaml-name; is a complete language allowing to create : bytecoded executable - bytecoded library ( *.cma ) + bytecoded library ( *.cma ) native executable - native library ( *.cmxa ) - shared library ( for C-binding ) ( dll*.so ) - static library ( for C-binding ) ( lib*.a ) - bytecoded object ( *.cmo ) - native object ( *.cmx ) - configuration file for handling library ( META ) - ocamldoc generated documentation ( *.odoc ) + native library ( *.cmxa ) + shared library ( for C-binding ) ( dll*.so ) + static library ( for C-binding ) ( lib*.a ) + bytecoded object ( *.cmo ) + native object ( *.cmx ) + configuration file for handling library ( META ) + &ocamldoc; generated documentation ( *.odoc ) There is a convention considering that native executable should be - called progname.opt and bytecoded one - progname.byte. When packaging, only + called progname.opt and bytecoded one + progname.byte. When packaging, only progname is taken in account. For easying library management, &ocaml-force; used the - ocamlfind library management scheme. - This scheme includes a file named META which holds + &ocamlfind; library management scheme. This scheme includes + a file named META which holds all the library possibility. This is the configuration file for - handling library ( see XXX ). + handling library path and compile option.
@@ -78,56 +78,114 @@ - This documentation should be browse by different mean, from the + + 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 shoudl be browse by using different viewer ( like - advi, HTML browser ...). There is also at least two + 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 specific &ocaml-name; browser : docbrowse shipped with cameleon and ocamlbrowser - shipped with ocaml itself. The first one, need specific - ocamldoc generated documentation : this is in fact the - output of the intermediary stage of ocamldoc when - generating any kind of output, this is file with ".odoco - - which is installed in - /usr/lib/ocaml/&ocaml-version;/ and his subdirectory. - You can also browse documentation with ocamlbrowser. - At last, for some package, a special scheme is used to handle documentation - file : ocamldoc generated documentation. By this mean you can have different access - to library documentation : using docbrowser which is - shipped with cameleon, HTML pages registered under - the doc-base Debian package, - or manpages. + shipped with &ocaml-name; itself. The first one, need specific + &ocamldoc; generated documentation. The second one enables + 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 + 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 - As of this date, there is no automatic way to generate manpages and HTML - documentation with a debian package. For now, *.odoc files - will be stored in /usr/share/ocamldoc-base. A tools, to - auto-generate manpages and HTML documentation is under construction. + + As of today, there is no way to post-process &ocamldoc; + specific documentation. A &debian-name; package is under construction to do this + task. It will be referred as &ocamldoc-base;. + +
- Library paths + Path for all &ocaml-name; component</para> + <para> Ocaml will search library in two different location, referred to as <varname>local</varname> which hold user installed library and as <varname>core</varname> in which packaged modules stood. </para> + + <subsection id="library-path"> + <title>Library paths + + + By default, &ocaml-name; will look for modules in this order : + + + local + /usr/local/lib/ocaml/&ocaml-version;/ + + + core + /usr/lib/ocaml/&ocaml-version;/ + + + + + + When installing a library, packagers should use a subdirectory of the preceding + set of path. Subdirectory name is not mandatory. + + + + If upstream developpers use already a subdirectory of the &ocaml-name; + standard library path, this path should be preserved in the &debian-name; + package, but made relative to the standard library path of the &ocaml-pkg;. + Before using the provided subdirectory, packagers should check if there is + no subdirectory name clash with other &ocaml-name; 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 library + name clash ). 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. + + + + + + &ocamldoc; specific generated documentation - By default, &ocaml-name; will look for modules in this order : - - - local - /usr/local/lib/ocaml/&ocaml-version;/ - - - core - /usr/lib/ocaml/&ocaml-version;/ - - + Even if this way of producing documentation is not mandatory, packagers are + encouraged to use it, in order to ship lighter documentation, which could + be processed by &ocaml-name; tools. + + + By default, &ocamldoc-base; will look for *.odoc in this order : + + + local + /usr/local/share/ocamldoc/&ocaml-version;/ + + + core + /usr/share/ocamldoc/&ocaml-version;/ + + + +
diff --git a/ocaml_packaging_policy.xml b/ocaml_packaging_policy.xml index 090d98ac..a777348d 100644 --- a/ocaml_packaging_policy.xml +++ b/ocaml_packaging_policy.xml @@ -7,6 +7,10 @@ ocaml-base-&ocaml-version;-&ocaml-compat;"> OCaml"> + ocamlc"> + ocamlopt"> + ocamldoc"> + ocamlfind">