Daniel Bünzli
2016-09-11 00:43:48 UTC
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.
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.