Documentation of format of sources tarballs and paths missing.

[mattam82]

Prompted by this log https://gitlab.inria.fr/coq/opam/-/jobs/5542475/raw I tried to find documentation on what is the format expected for tarballs in opam. Typically, I put in src: a URL to a filename.tar.gz file that contains a directory build-dir/* contents. So when one untars it, the path to the sources is in build-dir, and opam should implicitly cd into it before running the build script. As far as I can tell, there is not necessarily any link between filename and build-dir, and opam actually doesn't untar build-dir but puts the sources under build-dir directly in ~/.opam-switch/sources/package-name/. Can we just think of opam cd'int into the untarred source tree if there is a single directory there? What's the logic here? And does sandboxing change anything to that picture?

[kit-ty-kate]

Can we just think of opam cd'int into the untarred source tree if there is a single directory there? What's the logic here? And does sandboxing change anything to that picture?

The logic, as encoded in OpamSystem.extract_job currently is:

• if the root of the tarball contains a single directory, opam makes it the main directory
• if it contains more than one directory, it errors out
• otherwise opam chooses the root as main directory

And no, sandboxing doesn't change that behaviour.

In general, we're missing documentation on archives as a whole. For example we're missing the documentation on which formats are supported (currently zip, tar.gz, tar.bz2, tar.xz), we'll do it when we have some time. Contributions are welcome in the meantime.