guix.texi

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
nothing and exit immediately.

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

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

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

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

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

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

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

@item --list-busy
List store items in use by currently running processes.  These store
items are effectively considered GC roots: they cannot be deleted.

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

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

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

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

@end table

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

@table @code

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

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

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

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

For example, this command:

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

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

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

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

@table @option

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

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

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

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

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

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

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

@end table

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

@cindex upgrading Guix
@cindex updating Guix
@cindex @command{guix pull}
@cindex pull
@cindex security, @command{guix pull}
@cindex authenticity, of code obtained with @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.  Source code is downloaded from a
@uref{https://git-scm.com, Git} repository, by default the official
GNU@tie{}Guix repository, though this can be customized.  @command{guix
pull} ensures that the code it downloads is @emph{authentic} by
verifying that commits are signed by Guix developers.

Specifically, @command{guix pull} downloads code from the @dfn{channels}
(@pxref{Channels}) specified by one of the followings, in this order:

@enumerate
@item
the @option{--channels} option;
@item
the user's @file{~/.config/guix/channels.scm} file;
@item
the system-wide @file{/etc/guix/channels.scm} file;
@item
the built-in default channels specified in the @code{%default-channels}
variable.
@end enumerate

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

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

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

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

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

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

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

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

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

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

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

You can also use @command{guix package} (@pxref{Invoking guix package})
to manage the profile by naming it explicitly:
@example
$ guix package -p ~/.config/guix/current --roll-back
switched from generation 3 to 2
$ guix package -p ~/.config/guix/current --delete-generations=1
deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
@end example

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

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

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

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

@cindex channel news
@item --news
@itemx -N
Display the list of packages added or upgraded since the previous
generation, as well as, occasionally, news written by channel authors
for their users (@pxref{Channels, Writing Channel News}).

The package information is the same as displayed upon @command{guix
pull} completion, but without ellipses; it is also similar to the output
of @command{guix pull -l} for the last generation (see below).

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

@item --roll-back
@cindex rolling back
@cindex undoing transactions
@cindex transactions, undoing
Roll back to the previous @dfn{generation} of @file{~/.config/guix/current}---i.e.,
undo the last transaction.

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

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

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

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

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

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

@item --allow-downgrades
Allow pulling older or unrelated revisions of channels than those
currently in use.

@cindex downgrade attacks, protection against
By default, @command{guix pull} protects against so-called ``downgrade
attacks'' whereby the Git repository of a channel would be reset to an
earlier or unrelated revision of itself, potentially leading you to
install older, known-vulnerable versions of software packages.

@quotation Note
Make sure you understand its security implications before using
@option{--allow-downgrades}.
@end quotation

@item --disable-authentication
Allow pulling channel code without authenticating it.

@cindex authentication, of channel code
By default, @command{guix pull} authenticates code downloaded from
channels by verifying that its commits are signed by authorized
developers, and raises an error if this is not the case.  This option
instructs it to not perform any such verification.

@quotation Note
Make sure you understand its security implications before using
@option{--disable-authentication}.
@end quotation

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

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

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

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

@node Invoking guix time-machine
@section Invoking @command{guix time-machine}

@cindex @command{guix time-machine}
@cindex pinning, channels
@cindex replicating Guix
@cindex reproducibility, of Guix

The @command{guix time-machine} command provides access to other
revisions of Guix, for example to install older versions of packages,
or to reproduce a computation in an identical environment.  The revision
of Guix to be used is defined by a commit or by a channel
description file created by @command{guix describe}
(@pxref{Invoking guix describe}).

The general syntax is:

@example
guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{}
@end example

where @var{command} and @var{arg}@dots{} are passed unmodified to the
@command{guix} command of the specified revision.  The @var{options} that define
this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}):

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

@item --channels=@var{file}
@itemx -C @var{file}
Read the list of channels from @var{file}.  @var{file} must contain
Scheme code that evaluates to a list of channel objects.
@xref{Channels} for more information.
@end table

As for @command{guix pull}, the absence of any options means that the
latest commit on the master branch will be used.  The command

@example
guix time-machine -- build hello
@end example

will thus build the package @code{hello} as defined in the master branch,
which is in general a newer revision of Guix than you have installed.
Time travel works in both directions!

Note that @command{guix time-machine} can trigger builds of channels and
their dependencies, and these are controlled by the standard build
options (@pxref{Common Build Options}).

@node Inferiors
@section Inferiors

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

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

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

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

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

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

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

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

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

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

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

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

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

@cindex inferior packages
The procedures listed below allow you to obtain and manipulate inferior
packages.

@deffn {Scheme Procedure} inferior-packages @var{inferior}
Return the list of packages known to @var{inferior}.
@end deffn

@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @
   [@var{version}]
Return the sorted list of inferior packages matching @var{name} in
@var{inferior}, with highest version numbers first.  If @var{version} is true,
return only packages with a version number prefixed by @var{version}.
@end deffn

@deffn {Scheme Procedure} inferior-package? @var{obj}
Return true if @var{obj} is an inferior package.
@end deffn

@deffn {Scheme Procedure} inferior-package-name @var{package}
@deffnx {Scheme Procedure} inferior-package-version @var{package}
@deffnx {Scheme Procedure} inferior-package-synopsis @var{package}
@deffnx {Scheme Procedure} inferior-package-description @var{package}
@deffnx {Scheme Procedure} inferior-package-home-page @var{package}
@deffnx {Scheme Procedure} inferior-package-location @var{package}
@deffnx {Scheme Procedure} inferior-package-inputs @var{package}
@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package}
@deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package}
@deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package}
@deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package}
@deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package}
@deffnx {Scheme Procedure} inferior-package-search-paths @var{package}
These procedures are the counterpart of package record accessors
(@pxref{package Reference}).  Most of them work by querying the inferior
@var{package} comes from, so the inferior must still be live when you call
these procedures.
@end deffn

Inferior packages can be used transparently like any other package or
file-like object in G-expressions (@pxref{G-Expressions}).  They are also
transparently handled by the @code{packages->manifest} procedure, which is
commonly use in manifests (@pxref{Invoking guix package, the
@option{--manifest} option of @command{guix package}}).  Thus you can insert
an inferior package pretty much anywhere you would insert a regular package:
in manifests, in the @code{packages} field of your @code{operating-system}
declaration, and so on.

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

@cindex reproducibility
@cindex replicating Guix
Often you may want to answer questions like: ``Which revision of Guix am I
using?'' or ``Which channels am I using?''  This is useful information in many
situations: if you want to @emph{replicate} an environment on a different
machine or user account, if you want to report a bug or to determine what
change in the channels you are using caused it, or if you want to record your
system state for reproducibility purposes.  The @command{guix describe}
command answers these questions.

When run from a @command{guix pull}ed @command{guix}, @command{guix describe}
displays the channel(s) that it was built from, including their repository URL
and commit IDs (@pxref{Channels}):

@example
$ guix describe
Generation 10	Sep 03 2018 17:32:44	(current)
  guix e0fa68c
    repository URL: https://git.savannah.gnu.org/git/guix.git
    branch: master
    commit: e0fa68c7718fffd33d81af415279d6ddb518f727
@end example

If you're familiar with the Git version control system, this is similar in
spirit to @command{git describe}; the output is also similar to that of
@command{guix pull --list-generations}, but limited to the current generation
(@pxref{Invoking guix pull, the @option{--list-generations} option}).  Because
the Git commit ID shown above unambiguously refers to a snapshot of Guix, this
information is all it takes to describe the revision of Guix you're using, and
also to replicate it.

To make it easier to replicate Guix, @command{guix describe} can also be asked
to return a list of channels instead of the human-readable description above:

@example
$ guix describe -f channels
(list (channel
        (name 'guix)
        (url "https://git.savannah.gnu.org/git/guix.git")
        (commit
          "e0fa68c7718fffd33d81af415279d6ddb518f727")
        (introduction
          (make-channel-introduction
            "9edb3f66fd807b096b48283debdcddccfea34bad"
            (openpgp-fingerprint
              "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA")))))
@end example

@noindent
You can save this to a file and feed it to @command{guix pull -C} on some
other machine or at a later point in time, which will instantiate @emph{this
exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}).
From there on, since you're able to deploy the same revision of Guix, you can
just as well @emph{replicate a complete software environment}.  We humbly
think that this is @emph{awesome}, and we hope you'll like it too!

The details of the options supported by @command{guix describe} are as
follows:

@table @code
@item --format=@var{format}
@itemx -f @var{format}
Produce output in the specified @var{format}, one of:

@table @code
@item human
produce human-readable output;
@item channels
produce a list of channel specifications that can be passed to @command{guix
pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking
guix pull});
@item channels-sans-intro
like @code{channels}, but omit the @code{introduction} field; use it to
produce a channel specification suitable for Guix version 1.1.0 or
earlier---the @code{introduction} field has to do with channel
authentication (@pxref{Channels, Channel Authentication}) and is not
supported by these older versions;
@item json
@cindex JSON
produce a list of channel specifications in JSON format;
@item recutils
produce a list of channel specifications in Recutils format.
@end table

@item --list-formats
Display available formats for @option{--format} option.

@item --profile=@var{profile}
@itemx -p @var{profile}
Display information about @var{profile}.
@end table

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

@cindex @command{guix archive}
@cindex 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 on
a machine that runs Guix.
In particular, it allows store files to be transferred from one machine
to the store on another machine.

@quotation Note
If you're looking for a way to produce archives in a format suitable for
tools other than Guix, @pxref{Invoking guix pack}.
@end quotation

@cindex exporting store items
To export store files as an archive to 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
common build options (@pxref{Common Build Options}).

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
@option{-r}), regardless of what is already available in the store on
the target machine.  The @option{--missing} option can help figure out
which items are missing from the target store.  The @command{guix copy}
command simplifies and optimizes this whole process, so this is probably
what you should use in this case (@pxref{Invoking guix copy}).

@cindex nar, archive format
@cindex normalized archive (nar)
@cindex nar bundle, archive format
Each store item is written in the @dfn{normalized archive} or @dfn{nar}
format (described below), and the output of @command{guix archive
--export} (and input of @command{guix archive --import}) is a @dfn{nar
bundle}.

The nar format is
comparable in spirit to `tar', but with differences
that make it more appropriate for our purposes.  First, rather than
recording all Unix metadata 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.

That nar bundle format is essentially the concatenation of zero or more
nars along with metadata for each store item it contains: its file name,
references, corresponding derivation, and a digital signature.

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
@option{--recursive} is passed.

@item -r
@itemx --recursive
When combined with @option{--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 @option{--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 daemon.  This is a prerequisite before
archives can be exported with @option{--export}.  This
operation is usually instantaneous but it can take time if the system's
entropy pool needs to be refilled.  On Guix System,
@code{guix-service-type} takes care of generating this key pair the
first boot.

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.
Alternatively, @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{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
s-expressions''} and is structured as an access-control list in the
@url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
(SPKI)}.

@item --extract=@var{directory}
@itemx -x @var{directory}
Read a single-item archive as served by substitute servers
(@pxref{Substitutes}) and extract it to @var{directory}.  This is a
low-level operation needed in only very narrow use cases; see below.

For example, the following command extracts the substitute for Emacs
served by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}:

@example
$ wget -O - \
  https://@value{SUBSTITUTE-SERVER}/nar/gzip/@dots{}-emacs-24.5 \
  | gunzip | guix archive -x /tmp/emacs
@end example

Single-item archives are different from multiple-item archives produced
by @command{guix archive --export}; they contain a single store item,
and they do @emph{not} embed a signature.  Thus this operation does
@emph{no} signature verification and its output should be considered
unsafe.

The primary purpose of this operation is to facilitate inspection of
archive contents coming from possibly untrusted substitute servers
(@pxref{Invoking guix challenge}).

@item --list
@itemx -t
Read a single-item archive as served by substitute servers
(@pxref{Substitutes}) and print the list of files it contains, as in
this example:

@example
$ wget -O - \
  https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-emacs-26.3 \
  | lzip -d | guix archive -t
@end example

@end table

@c *********************************************************************
@node Channels
@chapter Channels

@cindex channels