Previous: , Up: Development   [Contents][Index]


5.2 Invoking guix pack

Occasionally you want to pass software to people who are not (yet!) lucky enough to be using Guix. You’d tell them to run guix package -i something, but that’s not possible in this case. This is where guix pack comes in.

Note: If you are looking for ways to exchange binaries among machines that already run Guix, see Invoking guix copy, Invoking guix publish, and Invoking guix archive.

The guix pack command creates a shrink-wrapped pack or software bundle: it creates a tarball or some other archive containing the binaries of the software you’re interested in, and all its dependencies. The resulting archive can be used on any machine that does not have Guix, and people can run the exact same binaries as those you have with Guix. The pack itself is created in a bit-reproducible fashion, so anyone can verify that it really contains the build results that you pretend to be shipping.

For example, to create a bundle containing Guile, Emacs, Geiser, and all their dependencies, you can run:

$ guix pack guile emacs geiser
…
/gnu/store/…-pack.tar.gz

The result here is a tarball containing a /gnu/store directory with all the relevant packages. The resulting tarball contains a profile with the three packages of interest; the profile is the same as would be created by guix package -i. It is this mechanism that is used to create Guix’s own standalone binary tarball (see Binary Installation).

Users of this pack would have to run /gnu/store/…-profile/bin/guile to run Guile, which you may find inconvenient. To work around it, you can create, say, a /opt/gnu/bin symlink to the profile:

guix pack -S /opt/gnu/bin=bin guile emacs geiser

That way, users can happily type /opt/gnu/bin/guile and enjoy.

What if the recipient of your pack does not have root privileges on their machine, and thus cannot unpack it in the root file system? In that case, you will want to use the --relocatable option (see below). This option produces relocatable binaries, meaning they they can be placed anywhere in the file system hierarchy: in the example above, users can unpack your tarball in their home directory and directly run ./opt/gnu/bin/guile.

Alternatively, you can produce a pack in the Docker image format using the following command:

guix pack -f docker guile emacs geiser

The result is a tarball that can be passed to the docker load command. See the Docker documentation for more information.

Yet another option is to produce a SquashFS image with the following command:

guix pack -f squashfs guile emacs geiser

The result is a SquashFS file system image that can either be mounted or directly be used as a file system container image with the Singularity container execution environment, using commands like singularity shell or singularity exec.

Several command-line options allow you to customize your pack:

--format=format
-f format

Produce a pack in the given format.

The available formats are:

tarball

This is the default format. It produces a tarball containing all the specified binaries and symlinks.

docker

This produces a tarball that follows the Docker Image Specification.

squashfs

This produces a SquashFS image containing all the specified binaries and symlinks, as well as empty mount points for virtual file systems like procfs.

--relocatable
-R

Produce relocatable binaries—i.e., binaries that can be placed anywhere in the file system hierarchy and run from there.

When this option is passed once, the resulting binaries require support for user namespaces in the kernel Linux; when passed twice12, relocatable binaries fall to back to PRoot if user namespaces are unavailable, and essentially work anywhere—see below for the implications.

For example, if you create a pack containing Bash with:

guix pack -RR -S /mybin=bin bash

... you can copy that pack to a machine that lacks Guix, and from your home directory as a normal user, run:

tar xf pack.tar.gz
./mybin/sh

In that shell, if you type ls /gnu/store, you’ll notice that /gnu/store shows up and contains all the dependencies of bash, even though the machine actually lacks /gnu/store altogether! That is probably the simplest way to deploy Guix-built software on a non-Guix machine.

Note: By default, relocatable binaries rely on the user namespace feature of the kernel Linux, which allows unprivileged users to mount or change root. Old versions of Linux did not support it, and some GNU/Linux distributions turn it off.

To produce relocatable binaries that work even in the absence of user namespaces, pass --relocatable or -R twice. In that case, binaries will try user namespace support and fall back to PRoot if user namespaces are not supported.

The PRoot program provides the necessary support for file system virtualization. It achieves that by using the ptrace system call on the running program. This approach has the advantage to work without requiring special kernel support, but it incurs run-time overhead every time a system call is made.

--expression=expr
-e expr

Consider the package expr evaluates to.

This has the same purpose as the same-named option in guix build (see --expression in guix build).

--manifest=file
-m file

Use the packages contained in the manifest object returned by the Scheme code in file.

This has a similar purpose as the same-named option in guix package (see --manifest) and uses the same manifest files. It allows you to define a collection of packages once and use it both for creating profiles and for creating archives for use on machines that do not have Guix installed. Note that you can specify either a manifest file or a list of packages, but not both.

--system=system
-s system

Attempt to build for system—e.g., i686-linux—instead of the system type of the build host.

--target=triplet

Cross-build for triplet, which must be a valid GNU triplet, such as "mips64el-linux-gnu" (see GNU configuration triplets in Autoconf).

--compression=tool
-C tool

Compress the resulting tarball using tool—one of gzip, bzip2, xz, lzip, or none for no compression.

--symlink=spec
-S spec

Add the symlinks specified by spec to the pack. This option can appear several times.

spec has the form source=target, where source is the symlink that will be created and target is the symlink target.

For instance, -S /opt/gnu/bin=bin creates a /opt/gnu/bin symlink pointing to the bin sub-directory of the profile.

--save-provenance

Save provenance information for the packages passed on the command line. Provenance information includes the URL and commit of the channels in use (see Channels).

Provenance information is saved in the /gnu/store/…-profile/manifest file in the pack, along with the usual package metadata—the name and version of each package, their propagated inputs, and so on. It is useful information to the recipient of the pack, who then knows how the pack was (supposedly) obtained.

This option is not enabled by default because, like timestamps, provenance information contributes nothing to the build process. In other words, there is an infinity of channel URLs and commit IDs that can lead to the same pack. Recording such “silent” metadata in the output thus potentially breaks the source-to-binary bitwise reproducibility property.

--localstatedir
--profile-name=name

Include the “local state directory”, /var/guix, in the resulting pack, and notably the /var/guix/profiles/per-user/root/name profile—by default name is guix-profile, which corresponds to ~root/.guix-profile.

/var/guix contains the store database (see The Store) as well as garbage-collector roots (see Invoking guix gc). Providing it in the pack means that the store is “complete” and manageable by Guix; not providing it pack means that the store is “dead”: items cannot be added to it or removed from it after extraction of the pack.

One use case for this is the Guix self-contained binary tarball (see Binary Installation).

--bootstrap

Use the bootstrap binaries to build the pack. This option is only useful to Guix developers.

In addition, guix pack supports all the common build options (see Common Build Options) and all the package transformation options (see Package Transformation Options).


Footnotes

(12)

Here’s a trick to memorize it: -RR, which adds PRoot support, can be thought of as the abbreviation of “Really Relocatable”. Neat, isn’t it?


Previous: , Up: Development   [Contents][Index]