4.1.4 The benefits of manifests

Manifests are a convenient way to keep your package lists around and, say, to synchronize them across multiple machines using a version control system.

A common complaint about manifests is that they can be slow to install when they contain large number of packages. This is especially cumbersome when you just want get an upgrade for one package within a big manifest.

This is one more reason to use multiple profiles, which happen to be just perfect to break down manifests into multiple sets of semantically connected packages. Using multiple, small profiles provides more flexibility and usability.

Manifests come with multiple benefits. In particular, they ease maintenance:

• When a profile is set up from a manifest, the manifest itself is self-sufficient to keep a “package listing” around and reinstall the profile later or on a different system. For ad-hoc profiles, we would need to generate a manifest specification manually and maintain the package versions for the packages that don’t use the default version.
• guix package --upgrade always tries to update the packages that have propagated inputs, even if there is nothing to do. Guix manifests remove this problem.
• When partially upgrading a profile, conflicts may arise (due to diverging dependencies between the updated and the non-updated packages) and they can be annoying to resolve manually. Manifests remove this problem altogether since all packages are always upgraded at once.
• As mentioned above, manifests allow for reproducible profiles, while the imperative guix install, guix upgrade, etc. do not, since they produce different profiles every time even when they hold the same packages. See the related discussion on the matter.
• Manifest specifications are usable by other ‘guix’ commands. For example, you can run guix weather -m manifest.scm to see how many substitutes are available, which can help you decide whether you want to try upgrading today or wait a while. Another example: you can run guix pack -m manifest.scm to create a pack containing all the packages in the manifest (and their transitive references).
• Finally, manifests have a Scheme representation, the ‘<manifest>’ record type. They can be manipulated in Scheme and passed to the various Guix APIs.

It’s important to understand that while manifests can be used to declare profiles, they are not strictly equivalent: profiles have the side effect that they “pin” packages in the store, which prevents them from being garbage-collected (see Invoking guix gc in GNU Guix Reference Manual) and ensures that they will still be available at any point in the future.

Let’s take an example:

1. We have an environment for hacking on a project for which there isn’t a Guix package yet. We build the environment using a manifest, and then run guix environment -m manifest.scm. So far so good.
2. Many weeks pass and we have run a couple of guix pull in the mean time. Maybe a dependency from our manifest has been updated; or we may have run guix gc and some packages needed by our manifest have been garbage-collected.
3. Eventually, we set to work on that project again, so we run guix shell -m manifest.scm. But now we have to wait for Guix to build and install stuff!

Ideally, we could spare the rebuild time. And indeed we can, all we need is to install the manifest to a profile and use GUIX_PROFILE=/the/profile; . "$GUIX_PROFILE"/etc/profile as explained above: this guarantees that our hacking environment will be available at all times.

Security warning: While keeping old profiles around can be convenient, keep in mind that outdated packages may not have received the latest security fixes.