Managing development/deployment bundles

opam-bundle.md

Bundles

OPAM can manage development and deployment bundles

Commands

Now that we have compiler-as-packages, switches can come empty by default. OPAM 2.0 adds a new mechanism to handle set of packages, called bundles.

Switch bundle

For development purposes, it is often useful to share the content of the current switch with coworkers: To create a new bundle from the current switch:

$ opam bundle switch [--precise]
$ cat [SWITCH-NAME].bundle
[...]
```

A bundle file contains:
- The list of active repositories if `--precise` is not set.
- The list of installed packaged in the current switch. If `--precise` is set, also include their metadata: opam, descr, url, files, etc...
- The list of pinned packages as well as their metadata
  > NOTE: what happens with local pins? 

A `--precise` bundle file is self-contained, it contains everything needed to recreate the switch on a different switch/machine with similar compiler/OS/architecture. This is pretty useful when you want to deploy the things that you built on the current switch.

> NOTE: need to better define how much portability we want for these bundle. 

#### Package bundles

Sometimes you want to create bundles without installing the packages that you want to deploy (because you target a different architecture/OS).

```
$ opam bundle package PKG1 [... PKGn] --set-vars "os=windows,compiler-version=4.02.3" [--pins PKG:URL,..] [--repos URL,..]
PKG1[-...-PKGn].bundle
```

These bundle files are similar to precise bundle switches: they don't contain repository metadata, just the full set of package metadata needed to install the given packages. The goal is to have fully reproducible builds.

#### Applying bundles

A bundle can be imported in the current switch:

```
$ opam bundle apply <file>.bundle
```

> NOTE: we need to define what happens when some package constraints cannot be resolved

Most of this is also available with switch import/export, and opam switch create --import.

A bundle file contains:

1. The list of active repositories if --precise is not set.
2. The list of installed packaged in the current switch. If --precise is set, also include their metadata: opam, descr, url, files, etc...
3. The list of pinned packages as well as their metadata > NOTE: what happens with local pins?

export files already include 2. and 3. ; 1. would be a list of URLs, but that adds concerns at import time since repositories are handled globally (although now configured per-switch): opam switch create --import then opam switch remove could leave artifacts unless we have some repository GC (which would be easy -- assuming we have the complete list of existing switches).
About 3., local pins are just pins which specify a local path as URL, and the export doesn't affect that.

Another approach would be to create a repository from the current switch, which could include the actual package archives. This is related, but a bit different from the opam-admin stuff to create a limited repository. Pins could be either kept as pins, or included in the repo.

A currently possible trick is also to generate a virtual package with the proper depends; that could be included in a generated repository and avoid the need for an export file altogether.

We should also decide if bundles are only used from empty switches or can be applied to existing switches: changing the repositories is dubious in the latter case.