guix.texi

@example
guix package -r lua -i guile guile-cairo
@end example

@cindex aliases, for @command{guix package}
For your convenience, we also provide the following aliases:

@itemize
@item
@command{guix search} is an alias for @command{guix package -s},
@item
@command{guix install} is an alias for @command{guix package -i},
@item
@command{guix remove} is an alias for @command{guix package -r},
@item
@command{guix upgrade} is an alias for @command{guix package -u},
@item
and @command{guix show} is an alias for @command{guix package --show=}.
@end itemize

These aliases are less expressive than @command{guix package} and provide
fewer options, so in some cases you'll probably want to use @command{guix
package} directly.

@command{guix package} also supports a @dfn{declarative approach}
whereby the user specifies the exact set of packages to be available and
passes it @i{via} the @option{--manifest} option
(@pxref{profile-manifest, @option{--manifest}}).

@cindex profile
For each user, a symlink to the user's default profile is automatically
created in @file{$HOME/.guix-profile}.  This symlink always points to the
current generation of the user's default profile.  Thus, users can add
@file{$HOME/.guix-profile/bin} to their @env{PATH} environment
variable, and so on.
@cindex search paths
If you are not using Guix System, consider adding the
following lines to your @file{~/.bash_profile} (@pxref{Bash Startup
Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned
shells get all the right environment variable definitions:

@example
GUIX_PROFILE="$HOME/.guix-profile" ; \
source "$HOME/.guix-profile/etc/profile"
@end example

In a multi-user setup, user profiles are stored in a place registered as
a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
to (@pxref{Invoking guix gc}).  That directory is normally
@code{@var{localstatedir}/guix/profiles/per-user/@var{user}}, where
@var{localstatedir} is the value passed to @code{configure} as
@option{--localstatedir}, and @var{user} is the user name.  The
@file{per-user} directory is created when @command{guix-daemon} is
started, and the @var{user} sub-directory is created by @command{guix
package}.

The @var{options} can be among the following:

@table @code

@item --install=@var{package} @dots{}
@itemx -i @var{package} @dots{}
Install the specified @var{package}s.

Each @var{package} may specify either a simple package name, such as
@code{guile}, or a package name followed by an at-sign and version number,
such as @code{guile@@1.8.8} or simply @code{guile@@1.8} (in the latter
case, the newest version prefixed by @code{1.8} is selected).

If no version number is specified, the
newest available version will be selected.  In addition, @var{package}
may contain a colon, followed by the name of one of the outputs of the
package, as in @code{gcc:doc} or @code{binutils@@2.22:lib}
(@pxref{Packages with Multiple Outputs}).  Packages with a corresponding
name (and optionally version) are searched for among the GNU
distribution modules (@pxref{Package Modules}).

@cindex propagated inputs
Sometimes packages have @dfn{propagated inputs}: these are dependencies
that automatically get installed along with the required package
(@pxref{package-propagated-inputs, @code{propagated-inputs} in
@code{package} objects}, for information about propagated inputs in
package definitions).

@anchor{package-cmd-propagated-inputs}
An example is the GNU MPC library: its C header files refer to those of
the GNU MPFR library, which in turn refer to those of the GMP library.
Thus, when installing MPC, the MPFR and GMP libraries also get installed
in the profile; removing MPC also removes MPFR and GMP---unless they had
also been explicitly installed by the user.

Besides, packages sometimes rely on the definition of environment
variables for their search paths (see explanation of
@option{--search-paths} below).  Any missing or possibly incorrect
environment variable definitions are reported here.

@item --install-from-expression=@var{exp}
@itemx -e @var{exp}
Install the package @var{exp} evaluates to.

@var{exp} must be a Scheme expression that evaluates to a
@code{<package>} object.  This option is notably useful to disambiguate
between same-named variants of a package, with expressions such as
@code{(@@ (gnu packages base) guile-final)}.

Note that this option installs the first output of the specified
package, which may be insufficient when needing a specific output of a
multiple-output package.

@item --install-from-file=@var{file}
@itemx -f @var{file}
Install the package that the code within @var{file} evaluates to.

As an example, @var{file} might contain a definition like this
(@pxref{Defining Packages}):

@lisp
@include package-hello.scm
@end lisp

Developers may find it useful to include such a @file{guix.scm} file
in the root of their project source tree that can be used to test
development snapshots and create reproducible development environments
(@pxref{Invoking guix environment}).

The @var{file} may also contain a JSON representation of one or more
package definitions.  Running @code{guix package -f} on
@file{hello.json} with the following contents would result in installing
the package @code{greeter} after building @code{myhello}:

@example
@verbatiminclude package-hello.json
@end example

@item --remove=@var{package} @dots{}
@itemx -r @var{package} @dots{}
Remove the specified @var{package}s.

As for @option{--install}, each @var{package} may specify a version number
and/or output name in addition to the package name.  For instance,
@samp{-r glibc:debug} would remove the @code{debug} output of
@code{glibc}.

@item --upgrade[=@var{regexp} @dots{}]
@itemx -u [@var{regexp} @dots{}]
@cindex upgrading packages
Upgrade all the installed packages.  If one or more @var{regexp}s are
specified, upgrade only installed packages whose name matches a
@var{regexp}.  Also see the @option{--do-not-upgrade} option below.

Note that this upgrades package to the latest version of packages found
in the distribution currently installed.  To update your distribution,
you should regularly run @command{guix pull} (@pxref{Invoking guix
pull}).

@cindex package transformations, upgrades
When upgrading, package transformations that were originally applied
when creating the profile are automatically re-applied (@pxref{Package
Transformation Options}).  For example, assume you first installed Emacs
from the tip of its development branch with:

@example
guix install emacs-next --with-branch=emacs-next=master
@end example

Next time you run @command{guix upgrade}, Guix will again pull the tip
of the Emacs development branch and build @code{emacs-next} from that
checkout.

Note that transformation options such as @option{--with-branch} and
@option{--with-source} depend on external state; it is up to you to
ensure that they work as expected.  You can also discard a
transformations that apply to a package by running:

@example
guix install @var{package}
@end example

@item --do-not-upgrade[=@var{regexp} @dots{}]
When used together with the @option{--upgrade} option, do @emph{not}
upgrade any packages whose name matches a @var{regexp}.  For example, to
upgrade all packages in the current profile except those containing the
substring ``emacs'':

@example
$ guix package --upgrade . --do-not-upgrade emacs
@end example

@item @anchor{profile-manifest}--manifest=@var{file}
@itemx -m @var{file}
@cindex profile declaration
@cindex profile manifest
Create a new generation of the profile from the manifest object
returned by the Scheme code in @var{file}.  This option can be repeated
several times, in which case the manifests are concatenated.

This allows you to @emph{declare} the profile's contents rather than
constructing it through a sequence of @option{--install} and similar
commands.  The advantage is that @var{file} can be put under version
control, copied to different machines to reproduce the same profile, and
so on.

@c FIXME: Add reference to (guix profile) documentation when available.
@var{file} must return a @dfn{manifest} object, which is roughly a list
of packages:

@findex packages->manifest
@lisp
(use-package-modules guile emacs)

(packages->manifest
 (list emacs
       guile-2.0
       ;; Use a specific package output.
       (list guile-2.0 "debug")))
@end lisp

@findex specifications->manifest
In this example we have to know which modules define the @code{emacs}
and @code{guile-2.0} variables to provide the right
@code{use-package-modules} line, which can be cumbersome.  We can
instead provide regular package specifications and let
@code{specifications->manifest} look up the corresponding package
objects, like this:

@lisp
(specifications->manifest
 '("emacs" "guile@@2.2" "guile@@2.2:debug"))
@end lisp

@item --roll-back
@cindex rolling back
@cindex undoing transactions
@cindex transactions, undoing
Roll back to the previous @dfn{generation} of the profile---i.e., undo
the last transaction.

When combined with options such as @option{--install}, roll back occurs
before any other actions.

When rolling back from the first generation that actually contains
installed packages, the profile is made to point to the @dfn{zeroth
generation}, which contains no files apart from its own metadata.

After having rolled back, installing, removing, or upgrading packages
overwrites previous future generations.  Thus, the history of the
generations in a profile is always linear.

@item --switch-generation=@var{pattern}
@itemx -S @var{pattern}
@cindex generations
Switch to a particular generation defined by @var{pattern}.

@var{pattern} may be either a generation number or a number prefixed
with ``+'' or ``-''.  The latter means: move forward/backward by a
specified number of generations.  For example, if you want to return to
the latest generation after @option{--roll-back}, use
@option{--switch-generation=+1}.

The difference between @option{--roll-back} and
@option{--switch-generation=-1} is that @option{--switch-generation} will
not make a zeroth generation, so if a specified generation does not
exist, the current generation will not be changed.

@item --search-paths[=@var{kind}]
@cindex search paths
Report environment variable definitions, in Bash syntax, that may be
needed in order to use the set of installed packages.  These environment
variables are used to specify @dfn{search paths} for files used by some
of the installed packages.

For example, GCC needs the @env{CPATH} and @env{LIBRARY_PATH}
environment variables to be defined so it can look for headers and
libraries in the user's profile (@pxref{Environment Variables,,, gcc,
Using the GNU Compiler Collection (GCC)}).  If GCC and, say, the C
library are installed in the profile, then @option{--search-paths} will
suggest setting these variables to @file{@var{profile}/include} and
@file{@var{profile}/lib}, respectively.

The typical use case is to define these environment variables in the
shell:

@example
$ eval `guix package --search-paths`
@end example

@var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix},
meaning that the returned environment variable definitions will either
be exact settings, or prefixes or suffixes of the current value of these
variables.  When omitted, @var{kind} defaults to @code{exact}.

This option can also be used to compute the @emph{combined} search paths
of several profiles.  Consider this example:

@example
$ guix package -p foo -i guile
$ guix package -p bar -i guile-json
$ guix package -p foo -p bar --search-paths
@end example

The last command above reports about the @env{GUILE_LOAD_PATH}
variable, even though, taken individually, neither @file{foo} nor
@file{bar} would lead to that recommendation.


@item --profile=@var{profile}
@itemx -p @var{profile}
Use @var{profile} instead of the user's default profile.

@var{profile} must be the name of a file that will be created upon
completion.  Concretely, @var{profile} will be a mere symbolic link
(``symlink'') pointing to the actual profile where packages are
installed:

@example
$ guix install hello -p ~/code/my-profile
@dots{}
$ ~/code/my-profile/bin/hello
Hello, world!
@end example

All it takes to get rid of the profile is to remove this symlink and its
siblings that point to specific generations:

@example
$ rm ~/code/my-profile ~/code/my-profile-*-link
@end example

@item --list-profiles
List all the user's profiles:

@example
$ guix package --list-profiles
/home/charlie/.guix-profile
/home/charlie/code/my-profile
/home/charlie/code/devel-profile
/home/charlie/tmp/test
@end example

When running as root, list all the profiles of all the users.

@cindex collisions, in a profile
@cindex colliding packages in profiles
@cindex profile collisions
@item --allow-collisions
Allow colliding packages in the new profile.  Use at your own risk!

By default, @command{guix package} reports as an error @dfn{collisions}
in the profile.  Collisions happen when two or more different versions
or variants of a given package end up in the profile.

@item --bootstrap
Use the bootstrap Guile to build the profile.  This option is only
useful to distribution developers.

@end table

In addition to these actions, @command{guix package} supports the
following options to query the current state of a profile, or the
availability of packages:

@table @option

@item --search=@var{regexp}
@itemx -s @var{regexp}
@anchor{guix-search}
@cindex searching for packages
List the available packages whose name, synopsis, or description matches
@var{regexp} (in a case-insensitive fashion), sorted by relevance.
Print all the metadata of matching packages in
@code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
GNU recutils manual}).

This allows specific fields to be extracted using the @command{recsel}
command, for instance:

@example
$ guix package -s malloc | recsel -p name,version,relevance
name: jemalloc
version: 4.5.0
relevance: 6

name: glibc
version: 2.25
relevance: 1

name: libgc
version: 7.6.0
relevance: 1
@end example

Similarly, to show the name of all the packages available under the
terms of the GNU@tie{}LGPL version 3:

@example
$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
name: elfutils

name: gmp
@dots{}
@end example

It is also possible to refine search results using several @code{-s} flags to
@command{guix package}, or several arguments to @command{guix search}.  For
example, the following command returns a list of board games (this time using
the @command{guix search} alias):

@example
$ guix search '\<board\>' game | recsel -p name
name: gnubg
@dots{}
@end example

If we were to omit @code{-s game}, we would also get software packages
that deal with printed circuit boards; removing the angle brackets
around @code{board} would further add packages that have to do with
keyboards.

And now for a more elaborate example.  The following command searches
for cryptographic libraries, filters out Haskell, Perl, Python, and Ruby
libraries, and prints the name and synopsis of the matching packages:

@example
$ guix search crypto library | \
    recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
@end example

@noindent
@xref{Selection Expressions,,, recutils, GNU recutils manual}, for more
information on @dfn{selection expressions} for @code{recsel -e}.

@item --show=@var{package}
Show details about @var{package}, taken from the list of available packages, in
@code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
recutils manual}).

@example
$ guix package --show=python | recsel -p name,version
name: python
version: 2.7.6

name: python
version: 3.3.5
@end example

You may also specify the full name of a package to only get details about a
specific version of it (this time using the @command{guix show} alias):
@example
$ guix show python@@3.4 | recsel -p name,version
name: python
version: 3.4.3
@end example



@item --list-installed[=@var{regexp}]
@itemx -I [@var{regexp}]
List the currently installed packages in the specified profile, with the
most recently installed packages shown last.  When @var{regexp} is
specified, list only installed packages whose name matches @var{regexp}.

For each installed package, print the following items, separated by
tabs: the package name, its version string, the part of the package that
is installed (for instance, @code{out} for the default output,
@code{include} for its headers, etc.), and the path of this package in
the store.

@item --list-available[=@var{regexp}]
@itemx -A [@var{regexp}]
List packages currently available in the distribution for this system
(@pxref{GNU Distribution}).  When @var{regexp} is specified, list only
available packages whose name matches @var{regexp}.

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, @option{--list-generations=1} returns
the first one.

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

@item @emph{Ranges}.  @option{--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,
@option{--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, @option{--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, @option{--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 @env{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.
* Getting Substitutes from Other Servers::  Substitute diversity.
* 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 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 Guix System (@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.

@quotation Note
If you are using Guix System, you can skip this section: Guix System
authorizes substitutes from @code{@value{SUBSTITUTE-SERVER}} by default.
@end quotation

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

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
The text changed from ``The following derivations would be built'' to
``112.3 MB would be downloaded''.  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 @option{--no-substitutes} (@pxref{Invoking
guix-daemon}).  It can also be disabled temporarily by passing the
@option{--no-substitutes} option to @command{guix package},
@command{guix build}, and other command-line tools.

@node Getting Substitutes from Other Servers
@subsection Getting Substitutes from Other Servers

@cindex substitute servers, adding more
Guix can look up and fetch substitutes from several servers.  This is
useful when you are using packages from additional channels for which
the official server does not have substitutes but another server
provides them.  Another situation where this is useful is when you would
prefer to download from your organization's substitute server, resorting
to the official server only as a fallback or dismissing it altogether.

You can give Guix a list of substitute server URLs and it will check
them in the specified order.  You also need to explicitly authorize the
public keys of substitute servers to instruct Guix to accept the
substitutes they sign.

On Guix System, this is achieved by modifying the configuration of the
@code{guix} service.  Since the @code{guix} service is part of the
default lists of services, @code{%base-services} and
@code{%desktop-services}, you can use @code{modify-services} to change
its configuration and add the URLs and substitute keys that you want
(@pxref{Service Reference, @code{modify-services}}).

As an example, suppose you want to fetch substitutes from
@code{guix.example.org} and to authorize the signing key of that server,
in addition to the default @code{@value{SUBSTITUTE-SERVER}}.  The
resulting operating system configuration will look something like:

@lisp
(operating-system
  ;; @dots{}
  (services
    ;; Assume we're starting from '%desktop-services'.  Replace it
    ;; with the list of services you're actually using.
    (modify-services %desktop-services
      (guix-service-type config =>
                        (guix-configuration
                          (inherit config)
                          (substitute-urls
                            (append (list "https://guix.example.org")
                                    %default-substitute-urls))
                          (authorized-keys
                            (append (list (local-file "./key.pub"))
                                    %default-authorized-guix-keys)))))))
@end lisp

This assumes that the file @file{key.pub} contains the signing key of
@code{guix.example.org}.  With this change in place in your operating
system configuration file (say @file{/etc/config.scm}), you can
reconfigure and restart the @code{guix-daemon} service or reboot so the
changes take effect:

@example
$ sudo guix system reconfigure /etc/config.scm
$ sudo herd restart guix-daemon
@end example

If you're running Guix on a ``foreign distro'', you would instead take
the following steps to get substitutes from additional servers:

@enumerate
@item
Edit the service configuration file for @code{guix-daemon}; when using
systemd, this is normally
@file{/etc/systemd/system/guix-daemon.service}.  Add the
@option{--substitute-urls} option on the @command{guix-daemon} command
line and list the URLs of interest (@pxref{daemon-substitute-urls,
@code{guix-daemon --substitute-urls}}):

@example
@dots{} --substitute-urls='https://guix.example.org https://@value{SUBSTITUTE-SERVER}'
@end example

@item
Restart the daemon.  For systemd, it goes like this:

@example
systemctl daemon-reload
systemctl restart guix-daemon.service
@end example

@item
Authorize the key of the new server (@pxref{Invoking guix archive}):

@example
guix archive --authorize < key.pub
@end example

Again this assumes @file{key.pub} contains the public key that
@code{guix.example.org} uses to sign substitutes.
@end enumerate

Now you're all set!  Substitutes will be preferably taken from
@code{https://guix.example.org}, using @code{@value{SUBSTITUTE-SERVER}}
as a fallback.  Of course you can list as many substitute servers as you
like, with the caveat that substitute lookup can be slowed down if too
many servers need to be contacted.

Note that there are also situations where one may want to add the URL of
a substitute server @emph{without} authorizing its key.
@xref{Substitute Authentication}, to understand this fine point.

@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 @samp{b.example.org}, and if
@samp{a.example.org} happens to serve the @emph{exact same} substitutes,
then Guix will download substitutes from @samp{a.example.org} because it
comes first in the list and can be considered a mirror of
@samp{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
@vindex https_proxy
Substitutes are downloaded over HTTP or HTTPS.  The @env{http_proxy} and
@env{https_proxy} environment variables can be set in the environment of
@command{guix-daemon} and are honored for downloads of substitutes.
Note that the value of those environment variables 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
@option{--fallback} was given (@pxref{fallback-option,, common build
option @option{--fallback}}).  Specifically, if @option{--fallback} was
omitted, then no local build will be performed, and the derivation is
considered to have failed.  However, if @option{--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
@option{--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 install 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 install glib
@end example

@cindex documentation
The command to install its documentation is:

@example
guix install 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 @option{--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