documentation clarification plus feature request for testing local opam-repository changes

[gasche]

In the process of making ocaml/opam-repository#6862 I used my first "patch" in opam metadata. This is a bit scary so I wanted to test the change locally before sending an opam-repository PR. I found this more difficult than it should be.

My first try was to go to my modified ~/Prog/opam-repository/packages/coqide/coqide.8.5.1 and run opam pin add coqide .. That does not work (opam does not fetch the archive, it expects the current directory to contain the unpacked sources), why does it not work? Could we make it work? Could we have a --kind=repo option to ask opam to expect the path to be to a "repo-like" directory and follow the build instructions at is would from an opam repository? (Suggested heuristics: the current directory contains all three of opam, descr, url).

Then I tried to find documentation on what was the right way to test that change. I found no documentation on this. In particular, the Packaging page assumes that we are working from a checkout/clone of the project, and uses the regular pin workflow.

There is however a remark about this at the end of the Packaging document:

You can set OPAM to use your local clone of the repository with

$ opam repository add my-dev-repo path/to/opam-repository

Don't forget to opam pin remove , and test your changes to the repo directly. You'll also need to opam update my-dev-repo each time to keep OPAM in sync (opam update synches all repos, this will be faster).

I think that this would need to be substantially fleshed out to explain to users how to test their package description. I find this workflow rather unpleasant, though, as it is mutating my whole opam environment (I don't want this one test to affect future opam usage, so I have to opam repo add ..., test, then opam remove ...) while I only want to test one package description. Supporting the pin workflow would be much better I think.

[AltGr]

I see, interesting point.
This would almost work, except that pinning normally forces the remote URL to the specified pinning target, ignoring any url file or section.

Internally, what you want is just pinning then cp -r ~/Prog/opam-repository/packages/coqide/coqide.8.5.1/* $(opam config var prefix)/.opam-switch/overlay/coqide/ (or dirname of opam show coqide --where). I can't recommend it though :)

An option opam pin add --meta-dir or --definition may be suitable for doing this directly; the only way currently is opam pin edit, or opam pin add URL to just change the source. Be careful, though, that pinnings are expected to pick up metadata changes from the package source -- although you will be prompted if there are any conflicts with the local metadata, and that is different from the upstream.

[AltGr]

Summarising:

• currently, you will need to opam repo add to test your repo's packages. That can now be specific to the current switch, but you will still need to opam repo remove afterwards. If you modified more than one package, you need to do it this way in any case (possibly, using a one-shot test switch)
• an option to opam pin add to pick up metadata (including url) instead of a package source could be added (the implementation would make this easy, since it is in fact already possible by manually copying the metadata to the internal overlay dir)

Keeping open for the latter feature request.