guix.texi

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

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}/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 a hyphen 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 independently.

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.

@c XXX: keep me up-to-date
Finally, when installing a GNU package, the tool reports the
availability of a newer upstream version.  In the future, it may provide
the option of installing directly from the upstream version, even if
that version is not yet in the distribution.

@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 --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{}]
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

@item --roll-back
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 meta-data.

Installing, removing, or upgrading packages from a generation that has
been rolled back to overwrites previous future generations.  Thus, the
history of a profile's generations is always linear.

@item --switch-generation=@var{pattern}
@itemx -S @var{pattern}
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}.

@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 environment's build log
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}
List the available packages whose name, synopsis, or description matches
@var{regexp}.  Print all the meta-data 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
name: glibc
version: 2.17

name: libgc
version: 7.2alpha6
@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

@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:
@example
$ guix package --show=python-3.3.5 | recsel -p name,version
name: python
version: 3.3.5
@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
installed 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}]
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 lesser 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 roll-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 that @command{guix
build} supports (@pxref{Invoking guix build, common build options}).

@include emacs.texi

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

The @code{hydra.gnu.org} server is a front-end to a build farm that
builds packages from the GNU distribution continuously for some
architectures, and makes them available as substitutes.  This is the
default source of substitutes; it can be overridden by passing
@command{guix-daemon} the @code{--substitute-urls} option
(@pxref{Invoking guix-daemon}).

@cindex security
@cindex digital signatures
To allow Guix to download substitutes from @code{hydra.gnu.org}, 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{hydra.gnu.org} to not
be compromised and to serve genuine substitutes.

This public key is installed along with Guix, in
@code{@var{prefix}/share/guix/hydra.gnu.org.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 < hydra.gnu.org.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
The following files 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{hydra.gnu.org} are usable and
will be downloaded, when possible, for future builds.

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

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.


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{hydra.gnu.org} substitutes can be
convenient, we encourage users to also build on their own, or even run
their own build farm, such that @code{hydra.gnu.org} 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.

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

Often, packages defined in Guix have a single @dfn{output}---i.e., the
source package leads 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

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 install 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.

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
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!

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 includes default user
profiles, and may be augmented with @command{guix build --root}, for
example (@pxref{Invoking guix build}).

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

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 --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-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
List the references (respectively, the referrers) of store files given
as arguments.

@item --requisites
@itemx -R
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.

@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
daemon's database actually exist in @file{/gnu/store}.

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

When passing @option{--verify=contents}, the daemon will compute the
content hash of each store item and compare 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
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.

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

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.

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.

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

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

@item --url=@var{url}
Download the source tarball of Guix from @var{url}.

By default, the tarball is taken from its canonical address at
@code{gnu.org}, for the stable branch of Guix.

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


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

The @command{guix archive} command allows users to @dfn{export} files
from the store into a single archive, and to later @dfn{import} them.
In particular, it allows store files to be transferred from one machine
to another machine's store.  For example, to transfer the @code{emacs}
package to a machine connected over SSH, one would run:

@example
guix archive --export -r emacs | ssh the-machine guix archive --import
@end example

@noindent
Similarly, a complete user profile may be transferred from one machine
to another like this:

@example
guix archive --export -r $(readlink -f ~/.guix-profile) | \
  ssh the-machine guix-archive --import
@end example

@noindent
However, note that, in both examples, all of @code{emacs} and the
profile as well as all of their dependencies are transferred (due to
@code{-r}), regardless of what is already available in the target
machine's store.  The @code{--missing} option can help figure out which
items are missing from the target's store.

Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
comparable in spirit to `tar', but with a few noteworthy differences
that make it more appropriate for our purposes.  First, rather than
recording all Unix meta-data for each file, the Nar format only mentions
the file type (regular, directory, or symbolic link); Unix permissions
and owner/group are dismissed.  Second, the order in which directory
entries are stored always follows the order of file names according to
the C locale collation order.  This makes archive production fully
deterministic.

When exporting, the daemon digitally signs the contents of the archive,
and that digital signature is appended.  When importing, the daemon
verifies the signature and rejects the import in case of an invalid
signature or if the signing key is not authorized.
@c FIXME: Add xref to daemon doc about signatures.

The main options are:

@table @code
@item --export
Export the specified store files or packages (see below.)  Write the
resulting archive to the standard output.

Dependencies are @emph{not} included in the output, unless
@code{--recursive} is passed.

@item -r
@itemx --recursive
When combined with @code{--export}, this instructs @command{guix
archive} to include dependencies of the given items in the archive.
Thus, the resulting archive is self-contained: it contains the closure
of the exported store items.

@item --import
Read an archive from the standard input, and import the files listed
therein into the store.  Abort if the archive has an invalid digital
signature, or if it is signed by a public key not among the authorized
keys (see @code{--authorize} below.)

@item --missing
Read a list of store file names from the standard input, one per line,
and write on the standard output the subset of these files missing from
the store.

@item --generate-key[=@var{parameters}]
@cindex signing, archives
Generate a new key pair for the daemons.  This is a prerequisite before
archives can be exported with @code{--export}.  Note that this operation
usually takes time, because it needs to gather enough entropy to
generate the key pair.

The generated key pair is typically stored under @file{/etc/guix}, in
@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
key, which must be kept secret.)  When @var{parameters} is omitted,
an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
versions before 1.6.0, it is a 4096-bit RSA key.
Alternately, @var{parameters} can specify
@code{genkey} parameters suitable for Libgcrypt (@pxref{General
public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
Libgcrypt Reference Manual}).

@item --authorize
@cindex authorizing, archives
Authorize imports signed by the public key passed on standard input.
The public key must be in ``s-expression advanced format''---i.e., the
same format as the @file{signing-key.pub} file.

The list of authorized keys is kept in the human-editable file
@file{/etc/guix/acl}.  The file contains
@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
s-expressions''} and is structured as an access-control list in the
@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
(SPKI)}.
@end table

To export store files as an archive to the standard output, run:

@example
guix archive --export @var{options} @var{specifications}...
@end example

@var{specifications} may be either store file names or package
specifications, as for @command{guix package} (@pxref{Invoking guix
package}).  For instance, the following command creates an archive
containing the @code{gui} output of the @code{git} package and the main
output of @code{emacs}:

@example
guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
@end example

If the specified packages are not built yet, @command{guix archive}
automatically builds them.  The build process may be controlled with the
same options that can be passed to the @command{guix build} command
(@pxref{Invoking guix build, common build options}).


@c *********************************************************************
@node Programming Interface
@chapter Programming Interface

GNU Guix provides several Scheme programming interfaces (APIs) to
define, build, and query packages.  The first interface allows users to
write high-level package definitions.  These definitions refer to
familiar packaging concepts, such as the name and version of a package,
its build system, and its dependencies.  These definitions can then be
turned into concrete build actions.

Build actions are performed by the Guix daemon, on behalf of users.  In a
standard setup, the daemon has write access to the store---the
@file{/gnu/store} directory---whereas users do not.  The recommended
setup also has the daemon perform builds in chroots, under a specific
build users, to minimize interference with the rest of the system.

@cindex derivation
Lower-level APIs are available to interact with the daemon and the
store.  To instruct the daemon to perform a build action, users actually
provide it with a @dfn{derivation}.  A derivation is a low-level
representation of the build actions to be taken, and the environment in
which they should occur---derivations are to package definitions what
assembly is to C programs.  The term ``derivation'' comes from the fact
that build results @emph{derive} from them.

This chapter describes all these APIs in turn, starting from high-level
package definitions.

@menu
* Defining Packages::           Defining new packages.
* Build Systems::               Specifying how packages are built.
* The Store::                   Manipulating the package store.
* Derivations::                 Low-level interface to package derivations.
* The Store Monad::             Purely functional interface to the store.
* G-Expressions::               Manipulating build expressions.
@end menu

@node Defining Packages
@section Defining Packages

The high-level interface to package definitions is implemented in the
@code{(guix packages)} and @code{(guix build-system)} modules.  As an
example, the package definition, or @dfn{recipe}, for the GNU Hello
package looks like this:

@example
(define-module (gnu packages hello)
  #:use-module (guix packages)
  #:use-module (guix download)
  #:use-module (guix build-system gnu)
  #:use-module (guix licenses))

(define-public hello
  (package
    (name "hello")
    (version "2.8")
    (source (origin
             (method url-fetch)
             (uri (string-append "mirror://gnu/hello/hello-" version
                                 ".tar.gz"))
             (sha256
              (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
    (build-system gnu-build-system)
    (arguments `(#:configure-flags '("--enable-silent-rules")))
    (inputs `(("gawk" ,gawk)))
    (synopsis "Hello, GNU world: An example GNU package")
    (description "Guess what GNU Hello prints!")
    (home-page "http://www.gnu.org/software/hello/")
    (license gpl3+)))
@end example

@noindent
Without being a Scheme expert, the reader may have guessed the meaning
of the various fields here.  This expression binds variable @code{hello}
to a @code{<package>} object, which is essentially a record
(@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
This package object can be inspected using procedures found in the
@code{(guix packages)} module; for instance, @code{(package-name hello)}
returns---surprise!---@code{"hello"}.

With luck, you may be able to import part or all of the definition of
the package you are interested in from another repository, using the
@code{guix import} command (@pxref{Invoking guix import}).

In the example above, @var{hello} is defined into a module of its own,
@code{(gnu packages hello)}.  Technically, this is not strictly
necessary, but it is convenient to do so: all the packages defined in
modules under @code{(gnu packages @dots{})} are automatically known to
the command-line tools (@pxref{Package Modules}).

There are a few points worth noting in the above package definition:

@itemize
@item
The @code{source} field of the package is an @code{<origin>} object
(@pxref{origin Reference}, for the complete reference).
Here, the @code{url-fetch} method from @code{(guix download)} is used,
meaning that the source is a file to be downloaded over FTP or HTTP.

The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
the GNU mirrors defined in @code{(guix download)}.

The @code{sha256} field specifies the expected SHA256 hash of the file
being downloaded.  It is mandatory, and allows Guix to check the
integrity of the file.  The @code{(base32 @dots{})} form introduces the
base32 representation of the hash.  You can obtain this information with
@code{guix download} (@pxref{Invoking guix download}) and @code{guix
hash} (@pxref{Invoking guix hash}).

@cindex patches
When needed, the @code{origin} form can also have a @code{patches} field
listing patches to be applied, and a @code{snippet} field giving a
Scheme expression to modify the source code.

@item
@cindex GNU Build System
The @code{build-system} field specifies the procedure to build the
package (@pxref{Build Systems}).  Here, @var{gnu-build-system}
represents the familiar GNU Build System, where packages may be
configured, built, and installed with the usual @code{./configure &&
make && make check && make install} command sequence.

@item
The @code{arguments} field specifies options for the build system
(@pxref{Build Systems}).  Here it is interpreted by
@var{gnu-build-system} as a request run @file{configure} with the
@code{--enable-silent-rules} flag.

@item
The @code{inputs} field specifies inputs to the build process---i.e.,
build-time or run-time dependencies of the package.  Here, we define an
input called @code{"gawk"} whose value is that of the @var{gawk}
variable; @var{gawk} is itself bound to a @code{<package>} object.

Note that GCC, Coreutils, Bash, and other essential tools do not need to
be specified as inputs here.  Instead, @var{gnu-build-system} takes care
of ensuring that they are present (@pxref{Build Systems}).

However, any other dependencies need to be specified in the
@code{inputs} field.  Any dependency not specified here will simply be
unavailable to the build process, possibly leading to a build failure.
@end itemize

@xref{package Reference}, for a full description of possible fields.

Once a package definition is in place, the
package may actually be built using the @code{guix build} command-line
tool (@pxref{Invoking guix build}).  @xref{Packaging Guidelines}, for
more information on how to test package definitions, and
@ref{Invoking guix lint}, for information on how to check a definition
for style conformance.

Eventually, updating the package definition to a new upstream version
can be partly automated by the @command{guix refresh} command
(@pxref{Invoking guix refresh}).

Behind the scenes, a derivation corresponding to the @code{<package>}
object is first computed by the @code{package-derivation} procedure.
That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
The build actions it prescribes may then be realized by using the
@code{build-derivations} procedure (@pxref{The Store}).

@deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
Return the @code{<derivation>} object of @var{package} for @var{system}
(@pxref{Derivations}).

@var{package} must be a valid @code{<package>} object, and @var{system}
must be a string denoting the target system type---e.g.,
@code{"x86_64-linux"} for an x86_64 Linux-based GNU system.  @var{store}
must be a connection to the daemon, which operates on the store
(@pxref{The Store}).
@end deffn

@noindent
@cindex cross-compilation
Similarly, it is possible to compute a derivation that cross-builds a
package for some other system:

@deffn {Scheme Procedure} package-cross-derivation @var{store} @
            @var{package} @var{target} [@var{system}]
Return the @code{<derivation>} object of @var{package} cross-built from
@var{system} to @var{target}.

@var{target} must be a valid GNU triplet denoting the target hardware
and operating system, such as @code{"mips64el-linux-gnu"}
(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
Configure and Build System}).
@end deffn

@menu
* package Reference ::          The package data type.