[ocaml-platform] Toying with package installs and documentation

[Daniel Bünzli]

Hello,  

I took the excuse of providing a story for odoc at the OPAM level to toy and move a bit on the idea of simplifying package management by using the information OCaml stores in build artefacts and using OPAM files as the pivotal package metadata format. 

In order to have a good comparison point for odoc generation I implemented a best-effort ocamldoc path which does per-package ocamldoc set generation (details [1]). It works pretty well in practice on quite a few packages, including the ocaml one. It also doesn't work at all on others. You can try it on your own opam switch by invoking: 

 opam pin add -kgit opkg https://github.com/dbuenzli/opkg.git
 opkg ocamldoc 
 opkg doc 

Do this in a 4.03 switch as the 4.02.* line was sadly systematically broken from a doc generation point of view. API docs can be found here http://erratique.ch/software/opkg/doc/ (or in `opkg doc opkg` of course).

Here's a sample rendering done on a random selection of packages:

http://erratique.ch/tmp/opkg-ocamldoc/var/cache/opkg/ocamldoc/
For ex. http://erratique.ch/tmp/opkg-ocamldoc/var/cache/opkg/ocamldoc/bos/index.html
 

Other, simple but handy, commands you may want to try are:

 opgk guess-deps _build # Good hint that a brighter build future exists
 opkg changes bos 
 opkg readme bos
 opkg homepage bos
 opkg issues bos
 opkg online-doc bos 
 opkg doc bos

If you want to know more about current packaging conventions, they are described in `opkg help packaging`. Note that they do not depend on the packages being OPAM managed (the OPAM file format is however reused). Using a software packager with a minimally decent release process like `topkg` implements them by default without the developer having anything special to do.

Comments on this list welcome -- please do not file issues for now as the whole thing is very wip and moving, a lot of design details are not yet determined some of which will need time to mature.

Daniel

[1] 
Restricting generation to packages allows to avoid cross package name overwrites and outrageous generation times for the final link step. Given a package we just fish for the mlis installed in its (sub)libdir. We then look for a corresponding cmi at the same place and find out the digests of the cmis it imports. By looking up opkg's global index of compilation object digests their install location can be found and is used to generate the list of `-I` ocamldoc needs to compile the mli to an odoc file. Sometimes it works, sometimes it fails, for various different reasons.