guix.texi

For each package, print the following items separated by tabs: its name,
its version string, the parts of the package (@pxref{Packages with
Multiple Outputs}), and the source location of its definition.

@item --list-generations[=@var{pattern}]
@itemx -l [@var{pattern}]
@cindex generations
Return a list of generations along with their creation dates; for each
generation, show the installed packages, with the most recently
installed packages shown last.  Note that the zeroth generation is never
shown.

For each installed package, print the following items, separated by
tabs: the name of a package, its version string, the part of the package
that is installed (@pxref{Packages with Multiple Outputs}), and the
location of this package in the store.

When @var{pattern} is used, the command returns only matching
generations.  Valid patterns include:

@itemize
@item @emph{Integers and comma-separated integers}.  Both patterns denote
generation numbers.  For instance, @code{--list-generations=1} returns
the first one.

And @code{--list-generations=1,8,2} outputs three generations in the
specified order.  Neither spaces nor trailing commas are allowed.

@item @emph{Ranges}.  @code{--list-generations=2..9} prints the
specified generations and everything in between.  Note that the start of
a range must be smaller than its end.

It is also possible to omit the endpoint.  For example,
@code{--list-generations=2..}, returns all generations starting from the
second one.

@item @emph{Durations}.  You can also get the last @emph{N}@tie{}days, weeks,
or months by passing an integer along with the first letter of the
duration.  For example, @code{--list-generations=20d} lists generations
that are up to 20 days old.
@end itemize

@item --delete-generations[=@var{pattern}]
@itemx -d [@var{pattern}]
When @var{pattern} is omitted, delete all generations except the current
one.

This command accepts the same patterns as @option{--list-generations}.
When @var{pattern} is specified, delete the matching generations.  When
@var{pattern} specifies a duration, generations @emph{older} than the
specified duration match.  For instance, @code{--delete-generations=1m}
deletes generations that are more than one month old.

If the current generation matches, it is @emph{not} deleted.  Also, the
zeroth generation is never deleted.

Note that deleting generations prevents rolling back to them.
Consequently, this command must be used with care.

@end table

Finally, since @command{guix package} may actually start build
processes, it supports all the common build options (@pxref{Common Build
Options}).  It also supports package transformation options, such as
@option{--with-source} (@pxref{Package Transformation Options}).
However, note that package transformations are lost when upgrading; to
preserve transformations across upgrades, you should define your own
package variant in a Guile module and add it to @code{GUIX_PACKAGE_PATH}
(@pxref{Defining Packages}).

@node Substitutes
@section Substitutes

@cindex substitutes
@cindex pre-built binaries
Guix supports transparent source/binary deployment, which means that it
can either build things locally, or download pre-built items from a
server, or both.  We call these pre-built items @dfn{substitutes}---they
are substitutes for local build results.  In many cases, downloading a
substitute is much faster than building things locally.

Substitutes can be anything resulting from a derivation build
(@pxref{Derivations}).  Of course, in the common case, they are
pre-built package binaries, but source tarballs, for instance, which
also result from derivation builds, can be available as substitutes.

@menu
* Official Substitute Server::  One particular source of substitutes.
* Substitute Server Authorization::  How to enable or disable substitutes.
* Substitute Authentication::   How Guix verifies substitutes.
* Proxy Settings::              How to get substitutes via proxy.
* Substitution Failure::        What happens when substitution fails.
* On Trusting Binaries::        How can you trust that binary blob?
@end menu

@node Official Substitute Server
@subsection Official Substitute Server

@cindex hydra
@cindex build farm
The @code{@value{SUBSTITUTE-SERVER}} server is a front-end to an official build farm
that builds packages from Guix continuously for some
architectures, and makes them available as substitutes.  This is the
default source of substitutes; it can be overridden by passing the
@option{--substitute-urls} option either to @command{guix-daemon}
(@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
or to client tools such as @command{guix package}
(@pxref{client-substitute-urls,, client @option{--substitute-urls}
option}).

Substitute URLs can be either HTTP or HTTPS.
HTTPS is recommended because communications are encrypted; conversely,
using HTTP makes all communications visible to an eavesdropper, who
could use the information gathered to determine, for instance, whether
your system has unpatched security vulnerabilities.

Substitutes from the official build farm are enabled by default when
using the Guix System Distribution (@pxref{GNU Distribution}).  However,
they are disabled by default when using Guix on a foreign distribution,
unless you have explicitly enabled them via one of the recommended
installation steps (@pxref{Installation}).  The following paragraphs
describe how to enable or disable substitutes for the official build
farm; the same procedure can also be used to enable substitutes for any
other substitute server.

@node Substitute Server Authorization
@subsection Substitute Server Authorization

@cindex security
@cindex substitutes, authorization thereof
@cindex access control list (ACL), for substitutes
@cindex ACL (access control list), for substitutes
To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER}} or a
mirror thereof, you
must add its public key to the access control list (ACL) of archive
imports, using the @command{guix archive} command (@pxref{Invoking guix
archive}).  Doing so implies that you trust @code{@value{SUBSTITUTE-SERVER}} to not
be compromised and to serve genuine substitutes.

The public key for @code{@value{SUBSTITUTE-SERVER}} is installed along with Guix, in
@code{@var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub}, where @var{prefix} is
the installation prefix of Guix.  If you installed Guix from source,
make sure you checked the GPG signature of
@file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
Then, you can run something like this:

@example
# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub
@end example

@quotation Note
Similarly, the @file{hydra.gnu.org.pub} file contains the public key
of an independent build farm also run by the project, reachable at
@indicateurl{https://mirror.hydra.gnu.org}.
@end quotation

Once this is in place, the output of a command like @code{guix build}
should change from something like:

@example
$ guix build emacs --dry-run
The following derivations would be built:
   /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
   /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
   /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
   /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
@dots{}
@end example

@noindent
to something like:

@example
$ guix build emacs --dry-run
112.3 MB would be downloaded:
   /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
   /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
   /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
   /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
@dots{}
@end example

@noindent
This indicates that substitutes from @code{@value{SUBSTITUTE-SERVER}} are usable and
will be downloaded, when possible, for future builds.

@cindex substitutes, how to disable
The substitute mechanism can be disabled globally by running
@code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
guix-daemon}).  It can also be disabled temporarily by passing the
@code{--no-substitutes} option to @command{guix package}, @command{guix
build}, and other command-line tools.

@node Substitute Authentication
@subsection Substitute Authentication

@cindex digital signatures
Guix detects and raises an error when attempting to use a substitute
that has been tampered with.  Likewise, it ignores substitutes that are
not signed, or that are not signed by one of the keys listed in the ACL.

There is one exception though: if an unauthorized server provides
substitutes that are @emph{bit-for-bit identical} to those provided by
an authorized server, then the unauthorized server becomes eligible for
downloads.  For example, assume we have chosen two substitute servers
with this option:

@example
--substitute-urls="https://a.example.org https://b.example.org"
@end example

@noindent
@cindex reproducible builds
If the ACL contains only the key for @code{b.example.org}, and if
@code{a.example.org} happens to serve the @emph{exact same} substitutes,
then Guix will download substitutes from @code{a.example.org} because it
comes first in the list and can be considered a mirror of
@code{b.example.org}.  In practice, independent build machines usually
produce the same binaries, thanks to bit-reproducible builds (see
below).

When using HTTPS, the server's X.509 certificate is @emph{not} validated
(in other words, the server is not authenticated), contrary to what
HTTPS clients such as Web browsers usually do.  This is because Guix
authenticates substitute information itself, as explained above, which
is what we care about (whereas X.509 certificates are about
authenticating bindings between domain names and public keys.)

@node Proxy Settings
@subsection Proxy Settings

@vindex http_proxy
Substitutes are downloaded over HTTP or HTTPS.
The @code{http_proxy} environment
variable can be set in the environment of @command{guix-daemon} and is
honored for downloads of substitutes.  Note that the value of
@code{http_proxy} in the environment where @command{guix build},
@command{guix package}, and other client commands are run has
@emph{absolutely no effect}.

@node Substitution Failure
@subsection Substitution Failure

Even when a substitute for a derivation is available, sometimes the
substitution attempt will fail.  This can happen for a variety of
reasons: the substitute server might be offline, the substitute may
recently have been deleted, the connection might have been interrupted,
etc.

When substitutes are enabled and a substitute for a derivation is
available, but the substitution attempt fails, Guix will attempt to
build the derivation locally depending on whether or not
@code{--fallback} was given (@pxref{fallback-option,, common build
option @code{--fallback}}).  Specifically, if @code{--fallback} was
omitted, then no local build will be performed, and the derivation is
considered to have failed.  However, if @code{--fallback} was given,
then Guix will attempt to build the derivation locally, and the success
or failure of the derivation depends on the success or failure of the
local build.  Note that when substitutes are disabled or no substitute
is available for the derivation in question, a local build will
@emph{always} be performed, regardless of whether or not
@code{--fallback} was given.

To get an idea of how many substitutes are available right now, you can
try running the @command{guix weather} command (@pxref{Invoking guix
weather}).  This command provides statistics on the substitutes provided
by a server.

@node On Trusting Binaries
@subsection On Trusting Binaries

@cindex trust, of pre-built binaries
Today, each individual's control over their own computing is at the
mercy of institutions, corporations, and groups with enough power and
determination to subvert the computing infrastructure and exploit its
weaknesses.  While using @code{@value{SUBSTITUTE-SERVER}} substitutes can be
convenient, we encourage users to also build on their own, or even run
their own build farm, such that @code{@value{SUBSTITUTE-SERVER}} is less of an
interesting target.  One way to help is by publishing the software you
build using @command{guix publish} so that others have one more choice
of server to download substitutes from (@pxref{Invoking guix publish}).

Guix has the foundations to maximize build reproducibility
(@pxref{Features}).  In most cases, independent builds of a given
package or derivation should yield bit-identical results.  Thus, through
a diverse set of independent package builds, we can strengthen the
integrity of our systems.  The @command{guix challenge} command aims to
help users assess substitute servers, and to assist developers in
finding out about non-deterministic package builds (@pxref{Invoking guix
challenge}).  Similarly, the @option{--check} option of @command{guix
build} allows users to check whether previously-installed substitutes
are genuine by rebuilding them locally (@pxref{build-check,
@command{guix build --check}}).

In the future, we want Guix to have support to publish and retrieve
binaries to/from other users, in a peer-to-peer fashion.  If you would
like to discuss this project, join us on @email{guix-devel@@gnu.org}.

@node Packages with Multiple Outputs
@section Packages with Multiple Outputs

@cindex multiple-output packages
@cindex package outputs
@cindex outputs

Often, packages defined in Guix have a single @dfn{output}---i.e., the
source package leads to exactly one directory in the store.  When running
@command{guix package -i glibc}, one installs the default output of the
GNU libc package; the default output is called @code{out}, but its name
can be omitted as shown in this command.  In this particular case, the
default output of @code{glibc} contains all the C header files, shared
libraries, static libraries, Info documentation, and other supporting
files.

Sometimes it is more appropriate to separate the various types of files
produced from a single source package into separate outputs.  For
instance, the GLib C library (used by GTK+ and related packages)
installs more than 20 MiB of reference documentation as HTML pages.
To save space for users who do not need it, the documentation goes to a
separate output, called @code{doc}.  To install the main GLib output,
which contains everything but the documentation, one would run:

@example
guix package -i glib
@end example

@cindex documentation
The command to install its documentation is:

@example
guix package -i glib:doc
@end example

Some packages install programs with different ``dependency footprints''.
For instance, the WordNet package installs both command-line tools and
graphical user interfaces (GUIs).  The former depend solely on the C
library, whereas the latter depend on Tcl/Tk and the underlying X
libraries.  In this case, we leave the command-line tools in the default
output, whereas the GUIs are in a separate output.  This allows users
who do not need the GUIs to save space.  The @command{guix size} command
can help find out about such situations (@pxref{Invoking guix size}).
@command{guix graph} can also be helpful (@pxref{Invoking guix graph}).

There are several such multiple-output packages in the GNU distribution.
Other conventional output names include @code{lib} for libraries and
possibly header files, @code{bin} for stand-alone programs, and
@code{debug} for debugging information (@pxref{Installing Debugging
Files}).  The outputs of a packages are listed in the third column of
the output of @command{guix package --list-available} (@pxref{Invoking
guix package}).


@node Invoking guix gc
@section Invoking @command{guix gc}

@cindex garbage collector
@cindex disk space
Packages that are installed, but not used, may be @dfn{garbage-collected}.
The @command{guix gc} command allows users to explicitly run the garbage
collector to reclaim space from the @file{/gnu/store} directory.  It is
the @emph{only} way to remove files from @file{/gnu/store}---removing
files or directories manually may break it beyond repair!

@cindex GC roots
@cindex garbage collector roots
The garbage collector has a set of known @dfn{roots}: any file under
@file{/gnu/store} reachable from a root is considered @dfn{live} and
cannot be deleted; any other file is considered @dfn{dead} and may be
deleted.  The set of garbage collector roots (``GC roots'' for short)
includes default user profiles; by default, the symlinks under
@file{/var/guix/gcroots} represent these GC roots.  New GC roots can be
added with @command{guix build --root}, for example (@pxref{Invoking
guix build}).  The @command{guix gc --list-roots} command lists them.

Prior to running @code{guix gc --collect-garbage} to make space, it is
often useful to remove old generations from user profiles; that way, old
package builds referenced by those generations can be reclaimed.  This
is achieved by running @code{guix package --delete-generations}
(@pxref{Invoking guix package}).

Our recommendation is to run a garbage collection periodically, or when
you are short on disk space.  For instance, to guarantee that at least
5@tie{}GB are available on your disk, simply run:

@example
guix gc -F 5G
@end example

It is perfectly safe to run as a non-interactive periodic job
(@pxref{Scheduled Job Execution}, for how to set up such a job).
Running @command{guix gc} with no arguments will collect as
much garbage as it can, but that is often inconvenient: you may find
yourself having to rebuild or re-download software that is ``dead'' from
the GC viewpoint but that is necessary to build other pieces of
software---e.g., the compiler tool chain.

The @command{guix gc} command has three modes of operation: it can be
used to garbage-collect any dead files (the default), to delete specific
files (the @code{--delete} option), to print garbage-collector
information, or for more advanced queries.  The garbage collection
options are as follows:

@table @code
@item --collect-garbage[=@var{min}]
@itemx -C [@var{min}]
Collect garbage---i.e., unreachable @file{/gnu/store} files and
sub-directories.  This is the default operation when no option is
specified.

When @var{min} is given, stop once @var{min} bytes have been collected.
@var{min} may be a number of bytes, or it may include a unit as a
suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
(@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).

When @var{min} is omitted, collect all the garbage.

@item --free-space=@var{free}
@itemx -F @var{free}
Collect garbage until @var{free} space is available under
@file{/gnu/store}, if possible; @var{free} denotes storage space, such
as @code{500MiB}, as described above.

When @var{free} or more is already available in @file{/gnu/store}, do
nothing and exit immediately.

@item --delete-generations[=@var{duration}]
@itemx -d [@var{duration}]
Before starting the garbage collection process, delete all the generations
older than @var{duration}, for all the user profiles; when run as root, this
applies to all the profiles @emph{of all the users}.

For example, this command deletes all the generations of all your profiles
that are older than 2 months (except generations that are current), and then
proceeds to free space until at least 10 GiB are available:

@example
guix gc -d 2m -F 10G
@end example

@item --delete
@itemx -D
Attempt to delete all the store files and directories specified as
arguments.  This fails if some of the files are not in the store, or if
they are still live.

@item --list-failures
List store items corresponding to cached build failures.

This prints nothing unless the daemon was started with
@option{--cache-failures} (@pxref{Invoking guix-daemon,
@option{--cache-failures}}).

@item --list-roots
List the GC roots owned by the user; when run as root, list @emph{all} the GC
roots.

@item --clear-failures
Remove the specified store items from the failed-build cache.

Again, this option only makes sense when the daemon is started with
@option{--cache-failures}.  Otherwise, it does nothing.

@item --list-dead
Show the list of dead files and directories still present in the
store---i.e., files and directories no longer reachable from any root.

@item --list-live
Show the list of live store files and directories.

@end table

In addition, the references among existing store files can be queried:

@table @code

@item --references
@itemx --referrers
@cindex package dependencies
List the references (respectively, the referrers) of store files given
as arguments.

@item --requisites
@itemx -R
@cindex closure
List the requisites of the store files passed as arguments.  Requisites
include the store files themselves, their references, and the references
of these, recursively.  In other words, the returned list is the
@dfn{transitive closure} of the store files.

@xref{Invoking guix size}, for a tool to profile the size of the closure
of an element.  @xref{Invoking guix graph}, for a tool to visualize
the graph of references.

@item --derivers
@cindex derivation
Return the derivation(s) leading to the given store items
(@pxref{Derivations}).

For example, this command:

@example
guix gc --derivers `guix package -I ^emacs$ | cut -f4`
@end example

@noindent
returns the @file{.drv} file(s) leading to the @code{emacs} package
installed in your profile.

Note that there may be zero matching @file{.drv} files, for instance
because these files have been garbage-collected.  There can also be more
than one matching @file{.drv} due to fixed-output derivations.
@end table

Lastly, the following options allow you to check the integrity of the
store and to control disk usage.

@table @option

@item --verify[=@var{options}]
@cindex integrity, of the store
@cindex integrity checking
Verify the integrity of the store.

By default, make sure that all the store items marked as valid in the
database of the daemon actually exist in @file{/gnu/store}.

When provided, @var{options} must be a comma-separated list containing one
or more of @code{contents} and @code{repair}.

When passing @option{--verify=contents}, the daemon computes the
content hash of each store item and compares it against its hash in the
database.  Hash mismatches are reported as data corruptions.  Because it
traverses @emph{all the files in the store}, this command can take a
long time, especially on systems with a slow disk drive.

@cindex repairing the store
@cindex corruption, recovering from
Using @option{--verify=repair} or @option{--verify=contents,repair}
causes the daemon to try to repair corrupt store items by fetching
substitutes for them (@pxref{Substitutes}).  Because repairing is not
atomic, and thus potentially dangerous, it is available only to the
system administrator.  A lightweight alternative, when you know exactly
which items in the store are corrupt, is @command{guix build --repair}
(@pxref{Invoking guix build}).

@item --optimize
@cindex deduplication
Optimize the store by hard-linking identical files---this is
@dfn{deduplication}.

The daemon performs deduplication after each successful build or archive
import, unless it was started with @code{--disable-deduplication}
(@pxref{Invoking guix-daemon, @code{--disable-deduplication}}).  Thus,
this option is primarily useful when the daemon was running with
@code{--disable-deduplication}.

@end table

@node Invoking guix pull
@section Invoking @command{guix pull}

@cindex upgrading Guix
@cindex updating Guix
@cindex @command{guix pull}
@cindex pull
Packages are installed or upgraded to the latest version available in
the distribution currently available on your local machine.  To update
that distribution, along with the Guix tools, you must run @command{guix
pull}: the command downloads the latest Guix source code and package
descriptions, and deploys it.  Source code is downloaded from a
@uref{https://git-scm.com, Git} repository, by default the official
GNU@tie{}Guix repository, though this can be customized.

On completion, @command{guix package} will use packages and package
versions from this just-retrieved copy of Guix.  Not only that, but all
the Guix commands and Scheme modules will also be taken from that latest
version.  New @command{guix} sub-commands added by the update also
become available.

Any user can update their Guix copy using @command{guix pull}, and the
effect is limited to the user who run @command{guix pull}.  For
instance, when user @code{root} runs @command{guix pull}, this has no
effect on the version of Guix that user @code{alice} sees, and vice
versa.

The result of running @command{guix pull} is a @dfn{profile} available
under @file{~/.config/guix/current} containing the latest Guix.  Thus,
make sure to add it to the beginning of your search path so that you use
the latest version, and similarly for the Info manual
(@pxref{Documentation}):

@example
export PATH="$HOME/.config/guix/current/bin:$PATH"
export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
@end example

The @code{--list-generations} or @code{-l} option lists past generations
produced by @command{guix pull}, along with details about their provenance:

@example
$ guix pull -l
Generation 1	Jun 10 2018 00:18:18
  guix 65956ad
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: origin/master
    commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe

Generation 2	Jun 11 2018 11:02:49
  guix e0cc7f6
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: origin/master
    commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d
  2 new packages: keepalived, libnfnetlink
  6 packages upgraded: emacs-nix-mode@@2.0.4,
    guile2.0-guix@@0.14.0-12.77a1aac, guix@@0.14.0-12.77a1aac,
    heimdal@@7.5.0, milkytracker@@1.02.00, nix@@2.0.4

Generation 3	Jun 13 2018 23:31:07	(current)
  guix 844cc1c
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: origin/master
    commit: 844cc1c8f394f03b404c5bb3aee086922373490c
  28 new packages: emacs-helm-ls-git, emacs-helm-mu, @dots{}
  69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{}
@end example

@xref{Invoking guix describe, @command{guix describe}}, for other ways to
describe the current status of Guix.

This @code{~/.config/guix/current} profile works like any other profile
created by @command{guix package} (@pxref{Invoking guix package}).  That
is, you can list generations, roll back to the previous
generation---i.e., the previous Guix---and so on:

@example
$ guix package -p ~/.config/guix/current --roll-back
switched from generation 3 to 2
$ guix package -p ~/.config/guix/current --delete-generations=1
deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
@end example

The @command{guix pull} command is usually invoked with no arguments,
but it supports the following options:

@table @code
@item --url=@var{url}
@itemx --commit=@var{commit}
@itemx --branch=@var{branch}
Download code for the @code{guix} channel from the specified @var{url}, at the
given @var{commit} (a valid Git commit ID represented as a hexadecimal
string), or @var{branch}.

@cindex @file{channels.scm}, configuration file
@cindex configuration file for channels
These options are provided for convenience, but you can also specify your
configuration in the @file{~/.config/guix/channels.scm} file or using the
@option{--channels} option (see below).

@item --channels=@var{file}
@itemx -C @var{file}
Read the list of channels from @var{file} instead of
@file{~/.config/guix/channels.scm}.  @var{file} must contain Scheme code that
evaluates to a list of channel objects.  @xref{Channels}, for more
information.

@item --list-generations[=@var{pattern}]
@itemx -l [@var{pattern}]
List all the generations of @file{~/.config/guix/current} or, if @var{pattern}
is provided, the subset of generations that match @var{pattern}.
The syntax of @var{pattern} is the same as with @code{guix package
--list-generations} (@pxref{Invoking guix package}).

@xref{Invoking guix describe}, for a way to display information about the
current generation only.

@item --profile=@var{profile}
@itemx -p @var{profile}
Use @var{profile} instead of @file{~/.config/guix/current}.

@item --dry-run
@itemx -n
Show which channel commit(s) would be used and what would be built or
substituted but do not actually do it.

@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
the system type of the build host.

@item --verbose
Produce verbose output, writing build logs to the standard error output.

@item --bootstrap
Use the bootstrap Guile to build the latest Guix.  This option is only
useful to Guix developers.
@end table

The @dfn{channel} mechanism allows you to instruct @command{guix pull} which
repository and branch to pull from, as well as @emph{additional} repositories
containing package modules that should be deployed.  @xref{Channels}, for more
information.

In addition, @command{guix pull} supports all the common build options
(@pxref{Common Build Options}).

@node Channels
@section Channels

@cindex channels
@cindex @file{channels.scm}, configuration file
@cindex configuration file for channels
@cindex @command{guix pull}, configuration file
@cindex configuration of @command{guix pull}
Guix and its package collection are updated by running @command{guix pull}
(@pxref{Invoking guix pull}).  By default @command{guix pull} downloads and
deploys Guix itself from the official GNU@tie{}Guix repository.  This can be
customized by defining @dfn{channels} in the
@file{~/.config/guix/channels.scm} file.  A channel specifies a URL and branch
of a Git repository to be deployed, and @command{guix pull} can be instructed
to pull from one or more channels.  In other words, channels can be used to
@emph{customize} and to @emph{extend} Guix, as we will see below.

@subsection Using a Custom Guix Channel

The channel called @code{guix} specifies where Guix itself---its command-line
tools as well as its package collection---should be downloaded.  For instance,
suppose you want to update from your own copy of the Guix repository at
@code{example.org}, and specifically the @code{super-hacks} branch, you can
write in @code{~/.config/guix/channels.scm} this specification:

@lisp
;; Tell 'guix pull' to use my own repo.
(list (channel
        (name 'guix)
        (url "https://example.org/my-guix.git")
        (branch "super-hacks")))
@end lisp

@noindent
From there on, @command{guix pull} will fetch code from the @code{super-hacks}
branch of the repository at @code{example.org}.

@subsection Specifying Additional Channels

@cindex extending the package collection (channels)
@cindex personal packages (channels)
@cindex channels, for personal packages
You can also specify @emph{additional channels} to pull from.  Let's say you
have a bunch of custom package variants or personal packages that you think
would make little sense to contribute to the Guix project, but would like to
have these packages transparently available to you at the command line.  You
would first write modules containing those package definitions (@pxref{Package
Modules}), maintain them in a Git repository, and then you and anyone else can
use it as an additional channel to get packages from.  Neat, no?

@c What follows stems from discussions at
@c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
@c earlier discussions on guix-devel@gnu.org.
@quotation Warning
Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
publish your personal channel to the world, we would like to share a few words
of caution:

@itemize
@item
Before publishing a channel, please consider contributing your package
definitions to Guix proper (@pxref{Contributing}).  Guix as a project is open
to free software of all sorts, and packages in Guix proper are readily
available to all Guix users and benefit from the project's quality assurance
process.

@item
When you maintain package definitions outside Guix, we, Guix developers,
consider that @emph{the compatibility burden is on you}.  Remember that
package modules and package definitions are just Scheme code that uses various
programming interfaces (APIs).  We want to remain free to change these APIs to
keep improving Guix, possibly in ways that break your channel.  We never
change APIs gratuitously, but we will @emph{not} commit to freezing APIs
either.

@item
Corollary: if you're using an external channel and that channel breaks, please
@emph{report the issue to the channel authors}, not to the Guix project.
@end itemize

You've been warned!  Having said this, we believe external channels are a
practical way to exert your freedom to augment Guix' package collection and to
share your improvements, which are basic tenets of
@uref{https://www.gnu.org/philosophy/free-sw.html, free software}.  Please
email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
@end quotation

To use a channel, write @code{~/.config/guix/channels.scm} to instruct
@command{guix pull} to pull from it @emph{in addition} to the default Guix
channel(s):

@vindex %default-channels
@lisp
;; Add my personal packages to those Guix provides.
(cons (channel
        (name 'my-personal-packages)
        (url "https://example.org/personal-packages.git"))
      %default-channels)
@end lisp

@noindent
Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to
add a channel the list of channels that the variable @code{%default-channels}
is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference
Manual}).  With this file in place, @command{guix pull} builds not only Guix
but also the package modules from your own repository.  The result in
@file{~/.config/guix/current} is the union of Guix with your own package
modules:

@example
$ guix pull --list-generations
@dots{}
Generation 19	Aug 27 2018 16:20:48
  guix d894ab8
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: master
    commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
  my-personal-packages dd3df5e
    repository URL: https://example.org/personal-packages.git
    branch: master
    commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
  11 new packages: my-gimp, my-emacs-with-cool-features, @dots{}
  4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
@end example

@noindent
The output of @command{guix pull} above shows that Generation@tie{}19 includes
both Guix and packages from the @code{my-personal-packages} channel.  Among
the new and upgraded packages that are listed, some like @code{my-gimp} and
@code{my-emacs-with-cool-features} might come from
@code{my-personal-packages}, while others come from the Guix default channel.

To create a channel, create a Git repository containing your own package
modules and make it available.  The repository can contain anything, but a
useful channel will contain Guile modules that export packages.  Once you
start using a channel, Guix will behave as if the root directory of that
channel's Git repository has been added to the Guile load path (@pxref{Load
Paths,,, guile, GNU Guile Reference Manual}).  For example, if your channel
contains a file at @file{my-packages/my-tools.scm} that defines a Guile
module, then the module will be available under the name @code{(my-packages
my-tools)}, and you will be able to use it like any other module
(@pxref{Modules,,, guile, GNU Guile Reference Manual}).

@cindex dependencies, channels
@cindex meta-data, channels
@subsection Declaring Channel Dependencies

Channel authors may decide to augment a package collection provided by other
channels.  They can declare their channel to be dependent on other channels in
a meta-data file @file{.guix-channel}, which is to be placed in the root of
the channel repository.

The meta-data file should contain a simple S-expression like this:

@lisp
(channel
 (version 0)
 (dependencies
  (channel
   (name some-collection)
   (url "https://example.org/first-collection.git"))
  (channel
   (name some-other-collection)
   (url "https://example.org/second-collection.git")
   (branch "testing"))))
@end lisp

In the above example this channel is declared to depend on two other channels,
which will both be fetched automatically.  The modules provided by the channel
will be compiled in an environment where the modules of all these declared
channels are available.

For the sake of reliability and maintainability, you should avoid dependencies
on channels that you don't control, and you should aim to keep the number of
dependencies to a minimum.

@subsection Replicating Guix

@cindex pinning, channels
@cindex replicating Guix
@cindex reproducibility, of Guix
The @command{guix pull --list-generations} output above shows precisely which
commits were used to build this instance of Guix.  We can thus replicate it,
say, on another machine, by providing a channel specification in
@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits:

@lisp
;; Deploy specific commits of my channels of interest.
(list (channel
       (name 'guix)
       (url "https://git.savannah.gnu.org/git/guix.git")
       (commit "d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300"))
      (channel
       (name 'my-personal-packages)
       (url "https://example.org/personal-packages.git")
       (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
@end lisp

The @command{guix describe --format=channels} command can even generate this
list of channels directly (@pxref{Invoking guix describe}).

At this point the two machines run the @emph{exact same Guix}, with access to
the @emph{exact same packages}.  The output of @command{guix build gimp} on
one machine will be exactly the same, bit for bit, as the output of the same
command on the other machine.  It also means both machines have access to all
the source code of Guix and, transitively, to all the source code of every
package it defines.

This gives you super powers, allowing you to track the provenance of binary
artifacts with very fine grain, and to reproduce software environments at
will---some sort of ``meta reproducibility'' capabilities, if you will.
@xref{Inferiors}, for another way to take advantage of these super powers.

@node Inferiors
@section Inferiors

@c TODO: Remove this once we're more confident about API stability.
@quotation Note
The functionality described here is a ``technology preview'' as of version
@value{VERSION}.  As such, the interface is subject to change.
@end quotation

@cindex inferiors
@cindex composition of Guix revisions
Sometimes you might need to mix packages from the revision of Guix you're
currently running with packages available in a different revision of Guix.
Guix @dfn{inferiors} allow you to achieve that by composing different Guix
revisions in arbitrary ways.

@cindex inferior packages
Technically, an ``inferior'' is essentially a separate Guix process connected
to your main Guix process through a REPL (@pxref{Invoking guix repl}).  The
@code{(guix inferior)} module allows you to create inferiors and to
communicate with them.  It also provides a high-level interface to browse and
manipulate the packages that an inferior provides---@dfn{inferior packages}.

When combined with channels (@pxref{Channels}), inferiors provide a simple way
to interact with a separate revision of Guix.  For example, let's assume you
want to install in your profile the current @code{guile} package, along with
the @code{guile-json} as it existed in an older revision of Guix---perhaps
because the newer @code{guile-json} has an incompatible API and you want to
run your code against the old API@.  To do that, you could write a manifest for
use by @code{guix package --manifest} (@pxref{Invoking guix package}); in that
manifest, you would create an inferior for that old Guix revision you care
about, and you would look up the @code{guile-json} package in the inferior:

@lisp
(use-modules (guix inferior) (guix channels)
             (srfi srfi-1))   ;for 'first'

(define channels
  ;; This is the old revision from which we want to
  ;; extract guile-json.
  (list (channel
         (name 'guix)
         (url "https://git.savannah.gnu.org/git/guix.git")
         (commit
          "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))

(define inferior
  ;; An inferior representing the above revision.
  (inferior-for-channels channels))

;; Now create a manifest with the current "guile" package
;; and the old "guile-json" package.
(packages->manifest
 (list (first (lookup-inferior-packages inferior "guile-json"))
       (specification->package "guile")))
@end lisp

On its first run, @command{guix package --manifest} might have to build the
channel you specified before it can create the inferior; subsequent runs will
be much faster because the Guix revision will be cached.

The @code{(guix inferior)} module provides the following procedures to open an
inferior:

@deffn {Scheme Procedure} inferior-for-channels @var{channels} @
   [#:cache-directory] [#:ttl]
Return an inferior for @var{channels}, a list of channels.  Use the cache at
@var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds.
This procedure opens a new connection to the build daemon.

As a side effect, this procedure may build or substitute binaries for
@var{channels}, which can take time.
@end deffn

@deffn {Scheme Procedure} open-inferior @var{directory} @
  [#:command "bin/guix"]
Open the inferior Guix in @var{directory}, running
@code{@var{directory}/@var{command} repl} or equivalent.  Return @code{#f} if
the inferior could not be launched.
@end deffn

@cindex inferior packages