Re: [Caml-list] Re: oasis packaging questions

[Sylvain Le Gall <sylvain@le-gall.net>]

Hi,

2012/3/8 Daniel Bünzli <daniel.buenzli@erratique.ch>:
>> OK, so first of all you are talking about the odb/GODI/oasis-db level.
>> OASIS itself is not meant to handle that directly. There will be a
>> plugin "oasis-db" that will allow you to do "oasis install xmlm" and
>> "oasis uninstalll xmlm" and fetch the source from
>> http://oasis.ocamlcore.org but this is the future and this won't be
>> the core oasis system. You can have a look at odb that allow you to
>> already do that after having uploaded your package to
>> http://oasis.ocamlcore.org.
>>
>> Concerning the ocamlfind install + documentation. I understand you but
>> it is technically not feasible right now (AFAIK). Simple fact:
>> ocamlfind cannot install files in subdirectories.
>
>
> Ok interesting fact. This raises a few comments/questions.
>
> 1) You tell me that's none of oasis business. But setup.ml sports a -install option so you actually deal with installing things (even if its via ocamlfind). More than that the examples I saw for Document sections are along the lines of copying things to a specific $htmldir so oasis seems to deal with that... At least that's the place where *something* should happen so that the right info gets to the right place.

OK, you got me on this. Technically, it is possible to do it using
oasis. We just have to define a dynamic variable that will contain the
directory ocamlfind choose to install the library. It is not trivial
to do and you can set it without enforcing $htmldir.

You have to use "ocaml setup.ml --docdir '$pkg_XYZ_installdir'".

Let say that if you just use $htmldir, it will help whatever packaging
system that cooperate with oasis to enforce it in the future.

To be honest, if it was the only problem I have to solve, I'll be
happy to spend hours on that.

>
> 2) How does godi et al. handle documentation ? I know for sure that odb doesn't do anything about it.

It does it the right way ;-)

$ ls /opt/godi/doc/
apps-oasis      godi-lablgl               godi-ocaml-fileutils  godi-react
apps-ocamlify   godi-lablgtk2             godi-ocamlgraph       godi-sexplib
GODI            godi-lwt                  godi-ocamlmakefile    godi-sqlite3
godi-cryptgps   godi-menhir               godi-ocamlnet         godi-tools
godi-cryptokit  godi-ocaml                godi-ocaml-text       godi-type-conv
godi-extlib     godi-ocaml-data-notation  godi-ounit            godi-zip
godi-findlib    godi-ocaml-expect         godi-pcre             ocsigen

$ ls /opt/godi/doc/apps-oasis/
AUTHORS.txt  CHANGES.txt  COPYING.txt  MANUAL.mkd  oasis  README.txt

(oasis contains the html documentation of the API).

> 3) Would ocamlfind consider extending its approach to be able to install files in subdirectories ?
>
> I really think that easy access to README, CHANGES and other bits like ocamldoc generated doc is paramount in a good package system since you don't get to see the tarballs anymore. I try to do my best and spend long hours on the documentation of the things I distribute (doesn't mean it's perfect, I sometimes don't understand what I wrote myself...), I want them to be somehow easily accessible (and easily destroyable).
>
> Can't we agree on something at that level ?

I would probably object to have html documentation in the $SITELIB of
findlib. However, if there is something to distribute and that should
go in $SITELIB/pkg, it should be a .odoc (compiled ocamldoc generated
using -dump). Among all the possible format, I think this is the
easiest one to use if you want to cooperate with TypeRex (or
Cameleon). Moreover, starting with this .odoc you can generate html
documentation or whatever ocamldoc generator you have at hand.

I think a CHANGES/README is light enough to be in $SITELIB as well.

But all this need to be more widely discuss (with OCamlPro for
TypeRex, Maxence for .odoc/Cameleon, Gerd for ocamlfind and the rest
of  the community to have a real agreement on this point).


> P.S. Btw. setup.ml -install should maybe also install the _oasis files.

Well _oasis can also go there, even though it will be a little bit a
duplicate with META...

Cheers
Sylvain