guix.texi

machines with a higher speed factor.

@item @code{features} (default: @code{'()})
A list of strings denoting specific features supported by the machine.
An example is @code{"kvm"} for machines that have the KVM Linux modules
and corresponding hardware support.  Derivations can request features by
name, and they will be scheduled on matching build machines.

@end table
@end deftp

The @code{guile} command must be in the search path on the build
machines.  In addition, the Guix modules must be in
@code{$GUILE_LOAD_PATH} on the build machine---you can check whether
this is the case by running:

@example
ssh build-machine guile -c "'(use-modules (guix config))'"
@end example

There is one last thing to do once @file{machines.scm} is in place.  As
explained above, when offloading, files are transferred back and forth
between the machine stores.  For this to work, you first need to
generate a key pair on each machine to allow the daemon to export signed
archives of files from the store (@pxref{Invoking guix archive}):

@example
# guix archive --generate-key
@end example

@noindent
Each build machine must authorize the key of the master machine so that
it accepts store items it receives from the master:

@example
# guix archive --authorize < master-public-key.txt
@end example

@noindent
Likewise, the master machine must authorize the key of each build machine.

All the fuss with keys is here to express pairwise mutual trust
relations between the master and the build machines.  Concretely, when
the master receives files from a build machine (and @i{vice versa}), its
build daemon can make sure they are genuine, have not been tampered
with, and that they are signed by an authorized key.

@cindex offload test
To test whether your setup is operational, run this command on the
master node:

@example
# guix offload test
@end example

This will attempt to connect to each of the build machines specified in
@file{/etc/guix/machines.scm}, make sure Guile and the Guix modules are
available on each machine, attempt to export to the machine and import
from it, and report any error in the process.

If you want to test a different machine file, just specify it on the
command line:

@example
# guix offload test machines-qualif.scm
@end example

Last, you can test the subset of the machines whose name matches a
regular expression like this:

@example
# guix offload test machines.scm '\.gnu\.org$'
@end example

@cindex offload status
To display the current load of all build hosts, run this command on the
main node:

@example
# guix offload status
@end example


@node Invoking guix-daemon
@section Invoking @command{guix-daemon}

The @command{guix-daemon} program implements all the functionality to
access the store.  This includes launching build processes, running the
garbage collector, querying the availability of a build result, etc.  It
is normally run as @code{root} like this:

@example
# guix-daemon --build-users-group=guixbuild
@end example

@noindent
For details on how to set it up, @pxref{Setting Up the Daemon}.

@cindex chroot
@cindex container, build environment
@cindex build environment
@cindex reproducible builds
By default, @command{guix-daemon} launches build processes under
different UIDs, taken from the build group specified with
@code{--build-users-group}.  In addition, each build process is run in a
chroot environment that only contains the subset of the store that the
build process depends on, as specified by its derivation
(@pxref{Programming Interface, derivation}), plus a set of specific
system directories.  By default, the latter contains @file{/dev} and
@file{/dev/pts}.  Furthermore, on GNU/Linux, the build environment is a
@dfn{container}: in addition to having its own file system tree, it has
a separate mount name space, its own PID name space, network name space,
etc.  This helps achieve reproducible builds (@pxref{Features}).

When the daemon performs a build on behalf of the user, it creates a
build directory under @file{/tmp} or under the directory specified by
its @code{TMPDIR} environment variable; this directory is shared with
the container for the duration of the build.  Be aware that using a
directory other than @file{/tmp} can affect build results---for example,
with a longer directory name, a build process that uses Unix-domain
sockets might hit the name length limitation for @code{sun_path}, which
it would otherwise not hit.

The build directory is automatically deleted upon completion, unless the
build failed and the client specified @option{--keep-failed}
(@pxref{Invoking guix build, @option{--keep-failed}}).

The following command-line options are supported:

@table @code
@item --build-users-group=@var{group}
Take users from @var{group} to run build processes (@pxref{Setting Up
the Daemon, build users}).

@item --no-substitutes
@cindex substitutes
Do not use substitutes for build products.  That is, always build things
locally instead of allowing downloads of pre-built binaries
(@pxref{Substitutes}).

When the daemon runs with @code{--no-substitutes}, clients can still
explicitly enable substitution @i{via} the @code{set-build-options}
remote procedure call (@pxref{The Store}).

@item --substitute-urls=@var{urls}
@anchor{daemon-substitute-urls}
Consider @var{urls} the default whitespace-separated list of substitute
source URLs.  When this option is omitted,
@indicateurl{https://mirror.hydra.gnu.org https://hydra.gnu.org} is used
(@code{mirror.hydra.gnu.org} is a mirror of @code{hydra.gnu.org}).

This means that substitutes may be downloaded from @var{urls}, as long
as they are signed by a trusted signature (@pxref{Substitutes}).

@cindex build hook
@item --no-build-hook
Do not use the @dfn{build hook}.

The build hook is a helper program that the daemon can start and to
which it submits build requests.  This mechanism is used to offload
builds to other machines (@pxref{Daemon Offload Setup}).

@item --cache-failures
Cache build failures.  By default, only successful builds are cached.

When this option is used, @command{guix gc --list-failures} can be used
to query the set of store items marked as failed; @command{guix gc
--clear-failures} removes store items from the set of cached failures.
@xref{Invoking guix gc}.

@item --cores=@var{n}
@itemx -c @var{n}
Use @var{n} CPU cores to build each derivation; @code{0} means as many
as available.

The default value is @code{0}, but it may be overridden by clients, such
as the @code{--cores} option of @command{guix build} (@pxref{Invoking
guix build}).

The effect is to define the @code{NIX_BUILD_CORES} environment variable
in the build process, which can then use it to exploit internal
parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.

@item --max-jobs=@var{n}
@itemx -M @var{n}
Allow at most @var{n} build jobs in parallel.  The default value is
@code{1}.  Setting it to @code{0} means that no builds will be performed
locally; instead, the daemon will offload builds (@pxref{Daemon Offload
Setup}), or simply fail.

@item --max-silent-time=@var{seconds}
When the build or substitution process remains silent for more than
@var{seconds}, terminate it and report a build failure.

The default value is @code{0}, which disables the timeout.

The value specified here can be overridden by clients (@pxref{Common
Build Options, @code{--max-silent-time}}).

@item --timeout=@var{seconds}
Likewise, when the build or substitution process lasts for more than
@var{seconds}, terminate it and report a build failure.

The default value is @code{0}, which disables the timeout.

The value specified here can be overridden by clients (@pxref{Common
Build Options, @code{--timeout}}).

@item --rounds=@var{N}
Build each derivation @var{n} times in a row, and raise an error if
consecutive build results are not bit-for-bit identical.  Note that this
setting can be overridden by clients such as @command{guix build}
(@pxref{Invoking guix build}).

When used in conjunction with @option{--keep-failed}, the differing
output is kept in the store, under @file{/gnu/store/@dots{}-check}.
This makes it easy to look for differences between the two results.

@item --debug
Produce debugging output.

This is useful to debug daemon start-up issues, but then it may be
overridden by clients, for example the @code{--verbosity} option of
@command{guix build} (@pxref{Invoking guix build}).

@item --chroot-directory=@var{dir}
Add @var{dir} to the build chroot.

Doing this may change the result of build processes---for instance if
they use optional dependencies found in @var{dir} when it is available,
and not otherwise.  For that reason, it is not recommended to do so.
Instead, make sure that each derivation declares all the inputs that it
needs.

@item --disable-chroot
Disable chroot builds.

Using this option is not recommended since, again, it would allow build
processes to gain access to undeclared dependencies.  It is necessary,
though, when @command{guix-daemon} is running under an unprivileged user
account.

@item --log-compression=@var{type}
Compress build logs according to @var{type}, one of @code{gzip},
@code{bzip2}, or @code{none}.

Unless @code{--lose-logs} is used, all the build logs are kept in the
@var{localstatedir}.  To save space, the daemon automatically compresses
them with bzip2 by default.

@item --disable-deduplication
@cindex deduplication
Disable automatic file ``deduplication'' in the store.

By default, files added to the store are automatically ``deduplicated'':
if a newly added file is identical to another one found in the store,
the daemon makes the new file a hard link to the other file.  This can
noticeably reduce disk usage, at the expense of slightly increased
input/output load at the end of a build process.  This option disables
this optimization.

@item --gc-keep-outputs[=yes|no]
Tell whether the garbage collector (GC) must keep outputs of live
derivations.

@cindex GC roots
@cindex garbage collector roots
When set to ``yes'', the GC will keep the outputs of any live derivation
available in the store---the @code{.drv} files.  The default is ``no'',
meaning that derivation outputs are kept only if they are GC roots.
@xref{Invoking guix gc}, for more on GC roots.

@item --gc-keep-derivations[=yes|no]
Tell whether the garbage collector (GC) must keep derivations
corresponding to live outputs.

When set to ``yes'', as is the case by default, the GC keeps
derivations---i.e., @code{.drv} files---as long as at least one of their
outputs is live.  This allows users to keep track of the origins of
items in their store.  Setting it to ``no'' saves a bit of disk space.

Note that when both @code{--gc-keep-derivations} and
@code{--gc-keep-outputs} are used, the effect is to keep all the build
prerequisites (the sources, compiler, libraries, and other build-time
tools) of live objects in the store, regardless of whether these
prerequisites are live.  This is convenient for developers since it
saves rebuilds or downloads.

@item --impersonate-linux-2.6
On Linux-based systems, impersonate Linux 2.6.  This means that the
kernel's @code{uname} system call will report 2.6 as the release number.

This might be helpful to build programs that (usually wrongfully) depend
on the kernel version number.

@item --lose-logs
Do not keep build logs.  By default they are kept under
@code{@var{localstatedir}/guix/log}.

@item --system=@var{system}
Assume @var{system} as the current system type.  By default it is the
architecture/kernel pair found at configure time, such as
@code{x86_64-linux}.

@item --listen=@var{endpoint}
Listen for connections on @var{endpoint}.  @var{endpoint} is interpreted
as the file name of a Unix-domain socket if it starts with
@code{/} (slash sign).  Otherwise, @var{endpoint} is interpreted as a
host name or host name and port to listen to.  Here are a few examples:

@table @code
@item --listen=/gnu/var/daemon
Listen for connections on the @file{/gnu/var/daemon} Unix-domain socket,
creating it if needed.

@item --listen=localhost
@cindex daemon, remote access
@cindex remote access to the daemon
@cindex daemon, cluster setup
@cindex clusters, daemon setup
Listen for TCP connections on the network interface corresponding to
@code{localhost}, on port 44146.

@item --listen=128.0.0.42:1234
Listen for TCP connections on the network interface corresponding to
@code{128.0.0.42}, on port 1234.
@end table

This option can be repeated multiple times, in which case
@command{guix-daemon} accepts connections on all the specified
endpoints.  Users can tell client commands what endpoint to connect to
by setting the @code{GUIX_DAEMON_SOCKET} environment variable
(@pxref{The Store, @code{GUIX_DAEMON_SOCKET}}).

@quotation Note
The daemon protocol is @emph{unauthenticated and unencrypted}.  Using
@code{--listen=@var{host}} is suitable on local networks, such as
clusters, where only trusted nodes may connect to the build daemon.  In
other cases where remote access to the daemon is needed, we recommend
using Unix-domain sockets along with SSH.
@end quotation

When @code{--listen} is omitted, @command{guix-daemon} listens for
connections on the Unix-domain socket located at
@file{@var{localstatedir}/guix/daemon-socket/socket}.
@end table


@node Application Setup
@section Application Setup

@cindex foreign distro
When using Guix on top of GNU/Linux distribution other than GuixSD---a
so-called @dfn{foreign distro}---a few additional steps are needed to
get everything in place.  Here are some of them.

@subsection Locales

@anchor{locales-and-locpath}
@cindex locales, when not on GuixSD
@vindex LOCPATH
@vindex GUIX_LOCPATH
Packages installed @i{via} Guix will not use the locale data of the
host system.  Instead, you must first install one of the locale packages
available with Guix and then define the @code{GUIX_LOCPATH} environment
variable:

@example
$ guix package -i glibc-locales
$ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale
@end example

Note that the @code{glibc-locales} package contains data for all the
locales supported by the GNU@tie{}libc and weighs in at around
110@tie{}MiB.  Alternatively, the @code{glibc-utf8-locales} is smaller but
limited to a few UTF-8 locales.

The @code{GUIX_LOCPATH} variable plays a role similar to @code{LOCPATH}
(@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library Reference
Manual}).  There are two important differences though:

@enumerate
@item
@code{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc
provided by foreign distros.  Thus, using @code{GUIX_LOCPATH} allows you
to make sure the programs of the foreign distro will not end up loading
incompatible locale data.

@item
libc suffixes each entry of @code{GUIX_LOCPATH} with @code{/X.Y}, where
@code{X.Y} is the libc version---e.g., @code{2.22}.  This means that,
should your Guix profile contain a mixture of programs linked against
different libc version, each libc version will only try to load locale
data in the right format.
@end enumerate

This is important because the locale data format used by different libc
versions may be incompatible.

@subsection Name Service Switch

@cindex name service switch, glibc
@cindex NSS (name service switch), glibc
@cindex nscd (name service caching daemon)
@cindex name service caching daemon (nscd)
When using Guix on a foreign distro, we @emph{strongly recommend} that
the system run the GNU C library's @dfn{name service cache daemon},
@command{nscd}, which should be listening on the
@file{/var/run/nscd/socket} socket.  Failing to do that, applications
installed with Guix may fail to look up host names or user accounts, or
may even crash.  The next paragraphs explain why.

@cindex @file{nsswitch.conf}
The GNU C library implements a @dfn{name service switch} (NSS), which is
an extensible mechanism for ``name lookups'' in general: host name
resolution, user accounts, and more (@pxref{Name Service Switch,,, libc,
The GNU C Library Reference Manual}).

@cindex Network information service (NIS)
@cindex NIS (Network information service)
Being extensible, the NSS supports @dfn{plugins}, which provide new name
lookup implementations: for example, the @code{nss-mdns} plugin allow
resolution of @code{.local} host names, the @code{nis} plugin allows
user account lookup using the Network information service (NIS), and so
on.  These extra ``lookup services'' are configured system-wide in
@file{/etc/nsswitch.conf}, and all the programs running on the system
honor those settings (@pxref{NSS Configuration File,,, libc, The GNU C
Reference Manual}).

When they perform a name lookup---for instance by calling the
@code{getaddrinfo} function in C---applications first try to connect to
the nscd; on success, nscd performs name lookups on their behalf.  If
the nscd is not running, then they perform the name lookup by
themselves, by loading the name lookup services into their own address
space and running it.  These name lookup services---the
@file{libnss_*.so} files---are @code{dlopen}'d, but they may come from
the host system's C library, rather than from the C library the
application is linked against (the C library coming from Guix).

And this is where the problem is: if your application is linked against
Guix's C library (say, glibc 2.24) and tries to load NSS plugins from
another C library (say, @code{libnss_mdns.so} for glibc 2.22), it will
likely crash or have its name lookups fail unexpectedly.

Running @command{nscd} on the system, among other advantages, eliminates
this binary incompatibility problem because those @code{libnss_*.so}
files are loaded in the @command{nscd} process, not in applications
themselves.

@subsection X11 Fonts

@cindex fonts
The majority of graphical applications use Fontconfig to locate and
load fonts and perform X11-client-side rendering.  The @code{fontconfig}
package in Guix looks for fonts in @file{$HOME/.guix-profile}
by default.  Thus, to allow graphical applications installed with Guix
to display fonts, you have to install fonts with Guix as well.
Essential font packages include @code{gs-fonts}, @code{font-dejavu}, and
@code{font-gnu-freefont-ttf}.

To display text written in Chinese languages, Japanese, or Korean in
graphical applications, consider installing
@code{font-adobe-source-han-sans} or @code{font-wqy-zenhei}.  The former
has multiple outputs, one per language family (@pxref{Packages with
Multiple Outputs}).  For instance, the following command installs fonts
for Chinese languages:

@example
guix package -i font-adobe-source-han-sans:cn
@end example

@cindex @code{xterm}
Older programs such as @command{xterm} do not use Fontconfig and instead
rely on server-side font rendering.  Such programs require to specify a
full name of a font using XLFD (X Logical Font Description), like this:

@example
-*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1
@end example

To be able to use such full names for the TrueType fonts installed in
your Guix profile, you need to extend the font path of the X server:

@example
xset +fp ~/.guix-profile/share/fonts/truetype
@end example

@cindex @code{xlsfonts}
After that, you can run @code{xlsfonts} (from @code{xlsfonts} package)
to make sure your TrueType fonts are listed there.

@cindex @code{fc-cache}
@cindex font cache
After installing fonts you may have to refresh the font cache to use
them in applications.  The same applies when applications installed via
Guix do not seem to find fonts.  To force rebuilding of the font cache
run @code{fc-cache -f}.  The @code{fc-cache} command is provided by the
@code{fontconfig} package.

@subsection X.509 Certificates

@cindex @code{nss-certs}
The @code{nss-certs} package provides X.509 certificates, which allow
programs to authenticate Web servers accessed over HTTPS.

When using Guix on a foreign distro, you can install this package and
define the relevant environment variables so that packages know where to
look for certificates.  @xref{X.509 Certificates}, for detailed
information.

@subsection Emacs Packages

@cindex @code{emacs}
When you install Emacs packages with Guix, the elisp files may be placed
either in @file{$HOME/.guix-profile/share/emacs/site-lisp/} or in
sub-directories of
@file{$HOME/.guix-profile/share/emacs/site-lisp/guix.d/}.  The latter
directory exists because potentially there may exist thousands of Emacs
packages and storing all their files in a single directory may not be
reliable (because of name conflicts).  So we think using a separate
directory for each package is a good idea.  It is very similar to how
the Emacs package system organizes the file structure (@pxref{Package
Files,,, emacs, The GNU Emacs Manual}).

By default, Emacs (installed with Guix) ``knows'' where these packages
are placed, so you do not need to perform any configuration.  If, for
some reason, you want to avoid auto-loading Emacs packages installed
with Guix, you can do so by running Emacs with @code{--no-site-file}
option (@pxref{Init File,,, emacs, The GNU Emacs Manual}).

@subsection The GCC toolchain

@cindex GCC
@cindex ld-wrapper

Guix offers individual compiler packages such as @code{gcc} but if you
are in need of a complete toolchain for compiling and linking source
code what you really want is the @code{gcc-toolchain} package.  This
package provides a complete GCC toolchain for C/C++ development,
including GCC itself, the GNU C Library (headers and binaries, plus
debugging symbols in the @code{debug} output), Binutils, and a linker
wrapper.

@cindex attempt to use impure library, error message

The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches
passed to the linker, add corresponding @code{-rpath} arguments, and
invoke the actual linker with this new set of arguments.  By default,
the linker wrapper refuses to link to libraries outside the store to
ensure ``purity''.  This can be annoying when using the toolchain to
link with local libraries.  To allow references to libraries outside the
store you need to define the environment variable
@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES}.

@c TODO What else?

@c *********************************************************************
@node Package Management
@chapter Package Management

@cindex packages
The purpose of GNU Guix is to allow users to easily install, upgrade, and
remove software packages, without having to know about their build
procedures or dependencies.  Guix also goes beyond this obvious set of
features.

This chapter describes the main features of Guix, as well as the
package management tools it provides.  Along with the command-line
interface described below (@pxref{Invoking guix package, @code{guix
package}}), you may also use the Emacs-Guix interface (@pxref{Top,,,
emacs-guix, The Emacs-Guix Reference Manual}), after installing
@code{emacs-guix} package (run @kbd{M-x guix-help} command to start
with it):

@example
guix package -i emacs-guix
@end example

@menu
* Features::                    How Guix will make your life brighter.
* Invoking guix package::       Package installation, removal, etc.
* Substitutes::                 Downloading pre-built binaries.
* Packages with Multiple Outputs::  Single source package, multiple outputs.
* Invoking guix gc::            Running the garbage collector.
* Invoking guix pull::          Fetching the latest Guix and distribution.
* Invoking guix pack::          Creating software bundles.
* Invoking guix archive::       Exporting and importing store files.
@end menu

@node Features
@section Features

When using Guix, each package ends up in the @dfn{package store}, in its
own directory---something that resembles
@file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string.

Instead of referring to these directories, users have their own
@dfn{profile}, which points to the packages that they actually want to
use.  These profiles are stored within each user's home directory, at
@code{$HOME/.guix-profile}.

For example, @code{alice} installs GCC 4.7.2.  As a result,
@file{/home/alice/.guix-profile/bin/gcc} points to
@file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}.  Now, on the same machine,
@code{bob} had already installed GCC 4.8.0.  The profile of @code{bob}
simply continues to point to
@file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
coexist on the same system without any interference.

The @command{guix package} command is the central tool to manage
packages (@pxref{Invoking guix package}).  It operates on the per-user
profiles, and can be used @emph{with normal user privileges}.

@cindex transactions
The command provides the obvious install, remove, and upgrade
operations.  Each invocation is actually a @emph{transaction}: either
the specified operation succeeds, or nothing happens.  Thus, if the
@command{guix package} process is terminated during the transaction,
or if a power outage occurs during the transaction, then the user's
profile remains in its previous state, and remains usable.

In addition, any package transaction may be @emph{rolled back}.  So, if,
for example, an upgrade installs a new version of a package that turns
out to have a serious bug, users may roll back to the previous instance
of their profile, which was known to work well.  Similarly, the global
system configuration on GuixSD is subject to
transactional upgrades and roll-back
(@pxref{Using the Configuration System}).

All packages in the package store may be @emph{garbage-collected}.
Guix can determine which packages are still referenced by user
profiles, and remove those that are provably no longer referenced
(@pxref{Invoking guix gc}).  Users may also explicitly remove old
generations of their profile so that the packages they refer to can be
collected.

@cindex reproducibility
@cindex reproducible builds
Finally, Guix takes a @dfn{purely functional} approach to package
management, as described in the introduction (@pxref{Introduction}).
Each @file{/gnu/store} package directory name contains a hash of all the
inputs that were used to build that package---compiler, libraries, build
scripts, etc.  This direct correspondence allows users to make sure a
given package installation matches the current state of their
distribution.  It also helps maximize @dfn{build reproducibility}:
thanks to the isolated build environments that are used, a given build
is likely to yield bit-identical files when performed on different
machines (@pxref{Invoking guix-daemon, container}).

@cindex substitutes
This foundation allows Guix to support @dfn{transparent binary/source
deployment}.  When a pre-built binary for a @file{/gnu/store} item is
available from an external source---a @dfn{substitute}, Guix just
downloads it and unpacks it;
otherwise, it builds the package from source, locally
(@pxref{Substitutes}).  Because build results are usually bit-for-bit
reproducible, users do not have to trust servers that provide
substitutes: they can force a local build and @emph{challenge} providers
(@pxref{Invoking guix challenge}).

Control over the build environment is a feature that is also useful for
developers.  The @command{guix environment} command allows developers of
a package to quickly set up the right development environment for their
package, without having to manually install the dependencies of the
package into their profile (@pxref{Invoking guix environment}).

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

@cindex installing packages
@cindex removing packages
@cindex package installation
@cindex package removal
The @command{guix package} command is the tool that allows users to
install, upgrade, and remove packages, as well as rolling back to
previous configurations.  It operates only on the user's own profile,
and works with normal user privileges (@pxref{Features}).  Its syntax
is:

@example
guix package @var{options}
@end example
@cindex transactions
Primarily, @var{options} specifies the operations to be performed during
the transaction.  Upon completion, a new profile is created, but
previous @dfn{generations} of the profile remain available, should the user
want to roll back.

For example, to remove @code{lua} and install @code{guile} and
@code{guile-cairo} in a single transaction:

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

@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 @code{PATH} environment
variable, and so on.
@cindex search paths
If you are not using the Guix System Distribution, 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
@code{--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
@code{--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}):

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

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}).

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

As for @code{--install}, each @var{package} may specify a version number
and/or output name in addition to the package name.  For instance,
@code{-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 @code{--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}).

@item --do-not-upgrade[=@var{regexp} @dots{}]
When used together with the @code{--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 allows you to @emph{declare} the profile's contents rather than
constructing it through a sequence of @code{--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
@example
(use-package-modules guile emacs)

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

@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:

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

@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 @code{--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 @code{--roll-back}, use
@code{--switch-generation=+1}.

The difference between @code{--roll-back} and
@code{--switch-generation=-1} is that @code{--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 @code{CPATH} and @code{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 @code{--search-paths} will
suggest setting these variables to @code{@var{profile}/include} and
@code{@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 @code{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.

@item --verbose
Produce verbose output.  In particular, emit the build log of the
environment on the standard error port.

@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}
@cindex searching for packages
List the available packages whose name, synopsis, or description matches
@var{regexp}, 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