[opam-devel] [RFC] OPAM files as *the* OCaml package metadata format

[Louis Gesbert]

Let me gather some answers in a single response (including lots of spoilers on 
opam 2.0~alpha)...

> Daniel:
> (Louis, I really need these x- fields for playing with ideas…)

Yup, 2.0~alpha is getting rolled out. I'll be grateful if you are ready to 
take the risk, as you have been most helpful with your reports on previous 
releases.

> Since OCaml packages may also get used outside OPAM itself (e.g. in an os
> package manager), this means that I need to install opam files so that they
> can be made available to hypothetical tools that consume them,
> independently from an OPAM install. The upcoming topkg packager overhaul
> will do this automatically, unless prevented.

The granularity of opam libs for manipulating these files has been much 
improved, but it could probably still be improved. Feel free to suggest such 
changes (OpamFile should probably be split; it would be better to do these 
_before_ everyone migrates to the new APIs). Also, the data handling is done 
through the new lens-like OpamFormat module (in lib opam-format).

The work-in-progress APIs are now online here:
    http://opam.ocaml.org/doc/2.0/api/

> 1. Where should those be installed in `lib:` (like METAs) or `etc:` (seems
> more logical) or … ?

Two things:
- opam now puts all its metadata into a .opam-switch/ subdir below the switch 
prefix. This is cleaner.
- it now keeps a synchronised cache of the opam files of all installed 
packages, in each switch. It's at `<prefix>/.opam-
switch/packages/<name>.<version>/opam`, but could be moved somewhere else (a 
directory structure is used to allow for a `files/` subdir, and for 
consistence with the repository format)

> 2. Has this any chance to confuse OPAM itself  ? My
> guess is no, it treats its install directories elements as sequence of
> bytes.

No, unless you write directly to the above-mentionned cache.

> Anil:
> - I think it would be good to encourage the use of an `opam/` directory so
> that `descr` files can also be tracked with the development version.  We
> could even assemble useful information in there such as example code
> fragments that would appear in the OPAM homepage for that package when
> published.

Unless you use overlay files (`files/xxx` that get added to the archive), 
which should really only be used for hot-patching in the repo and not on 
development packages, you can now put everything within a single opam file:

- For the description, use a `descr:` field, and a simple string. The new 
`"""`-delimited syntax for strings makes this more convenient.
- For the url, use the "section" format (implemented since opam 1.0 or before, 
but never used):
    url {
      <same format as the url file>
    }

> Daniel:
> 1) There's no support at the moment for such directories in OPAM install
> file

This can easily be added if we get a consensus

> Build tool link helpers, documentation indexer, finder and viewers, etc.

The repository maintainers will probably have to put some guidelines on what 
should or should not be within these files, when they are part of the official 
repository ?

Hope this helps!
Louis