guix.texi

You can also specify several package names:

@example
$ guix size coreutils grep sed bash
store item                               total    self
/gnu/store/@dots{}-coreutils-8.24          77.8    13.8  13.4%
/gnu/store/@dots{}-grep-2.22               73.1     0.8   0.8%
/gnu/store/@dots{}-bash-4.3.42             72.3     4.7   4.6%
/gnu/store/@dots{}-readline-6.3            67.6     1.2   1.2%
@dots{}
total: 102.3 MiB
@end example

@noindent
In this example we see that the combination of the four packages takes
102.3@tie{}MiB in total, which is much less than the sum of each closure
since they have a lot of dependencies in common.

The available options are:

@table @option

@item --substitute-urls=@var{urls}
Use substitute information from @var{urls}.
@xref{client-substitute-urls, the same option for @code{guix build}}.

@item --map-file=@var{file}
Write a graphical map of disk usage in PNG format to @var{file}.

For the example above, the map looks like this:

@image{images/coreutils-size-map,5in,, map of Coreutils disk usage
produced by @command{guix size}}

This option requires that
@uref{http://wingolog.org/software/guile-charting/, Guile-Charting} be
installed and visible in Guile's module search path.  When that is not
the case, @command{guix size} fails as it tries to load it.

@item --system=@var{system}
@itemx -s @var{system}
Consider packages for @var{system}---e.g., @code{x86_64-linux}.

@end table

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

@cindex DAG
@cindex @command{guix graph}
@cindex package dependencies
Packages and their dependencies form a @dfn{graph}, specifically a
directed acyclic graph (DAG).  It can quickly become difficult to have a
mental model of the package DAG, so the @command{guix graph} command
provides a visual representation of the DAG.  By default,
@command{guix graph} emits a DAG representation in the input format of
@uref{http://www.graphviz.org/, Graphviz}, so its output can be passed
directly to the @command{dot} command of Graphviz.  It can also emit an
HTML page with embedded JavaScript code to display a ``chord diagram''
in a Web browser, using the @uref{https://d3js.org/, d3.js} library.
The general syntax is:

@example
guix graph @var{options} @var{package}@dots{}
@end example

For example, the following command generates a PDF file representing the
package DAG for the GNU@tie{}Core Utilities, showing its build-time
dependencies:

@example
guix graph coreutils | dot -Tpdf > dag.pdf
@end example

The output looks like this:

@image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils}

Nice little graph, no?

But there is more than one graph!  The one above is concise: it is the
graph of package objects, omitting implicit inputs such as GCC, libc,
grep, etc.  It is often useful to have such a concise graph, but
sometimes one may want to see more details.  @command{guix graph} supports
several types of graphs, allowing you to choose the level of detail:

@table @code
@item package
This is the default type used in the example above.  It shows the DAG of
package objects, excluding implicit dependencies.  It is concise, but
filters out many details.

@item reverse-package
This shows the @emph{reverse} DAG of packages.  For example:

@example
guix graph --type=reverse-package ocaml
@end example

... yields the graph of packages that depend on OCaml.

Note that for core packages this can yield huge graphs.  If all you want
is to know the number of packages that depend on a given package, use
@command{guix refresh --list-dependent} (@pxref{Invoking guix refresh,
@option{--list-dependent}}).

@item bag-emerged
This is the package DAG, @emph{including} implicit inputs.

For instance, the following command:

@example
guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf
@end example

... yields this bigger graph:

@image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU Coreutils}

At the bottom of the graph, we see all the implicit inputs of
@var{gnu-build-system} (@pxref{Build Systems, @code{gnu-build-system}}).

Now, note that the dependencies of these implicit inputs---that is, the
@dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown
here, for conciseness.

@item bag
Similar to @code{bag-emerged}, but this time including all the bootstrap
dependencies.

@item bag-with-origins
Similar to @code{bag}, but also showing origins and their dependencies.

@item derivations
This is the most detailed representation: It shows the DAG of
derivations (@pxref{Derivations}) and plain store items.  Compared to
the above representation, many additional nodes are visible, including
build scripts, patches, Guile modules, etc.

For this type of graph, it is also possible to pass a @file{.drv} file
name instead of a package name, as in:

@example
guix graph -t derivation `guix system build -d my-config.scm`
@end example
@end table

All the types above correspond to @emph{build-time dependencies}.  The
following graph type represents the @emph{run-time dependencies}:

@table @code
@item references
This is the graph of @dfn{references} of a package output, as returned
by @command{guix gc --references} (@pxref{Invoking guix gc}).

If the given package output is not available in the store, @command{guix
graph} attempts to obtain dependency information from substitutes.

Here you can also pass a store file name instead of a package name.  For
example, the command below produces the reference graph of your profile
(which can be big!):

@example
guix graph -t references `readlink -f ~/.guix-profile`
@end example

@item referrers
This is the graph of the @dfn{referrers} of a store item, as returned by
@command{guix gc --referrers} (@pxref{Invoking guix gc}).

This relies exclusively on local information from your store.  For
instance, let us suppose that the current Inkscape is available in 10
profiles on your machine; @command{guix graph -t referrers inkscape}
will show a graph rooted at Inkscape and with those 10 profiles linked
to it.

It can help determine what is preventing a store item from being garbage
collected.

@end table

The available options are the following:

@table @option
@item --type=@var{type}
@itemx -t @var{type}
Produce a graph output of @var{type}, where @var{type} must be one of
the values listed above.

@item --list-types
List the supported graph types.

@item --backend=@var{backend}
@itemx -b @var{backend}
Produce a graph using the selected @var{backend}.

@item --list-backends
List the supported graph backends.

Currently, the available backends are Graphviz and d3.js.

@item --expression=@var{expr}
@itemx -e @var{expr}
Consider the package @var{expr} evaluates to.

This is useful to precisely refer to a package, as in this example:

@example
guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
@end example
@end table


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

@cindex reproducible build environments
@cindex development environments
@cindex @command{guix environment}
@cindex environment, package build environment
The purpose of @command{guix environment} is to assist hackers in
creating reproducible development environments without polluting their
package profile.  The @command{guix environment} tool takes one or more
packages, builds all of their inputs, and creates a shell
environment to use them.

The general syntax is:

@example
guix environment @var{options} @var{package}@dots{}
@end example

The following example spawns a new shell set up for the development of
GNU@tie{}Guile:

@example
guix environment guile
@end example

If the needed dependencies are not built yet, @command{guix environment}
automatically builds them.  The environment of the new shell is an augmented
version of the environment that @command{guix environment} was run in.
It contains the necessary search paths for building the given package
added to the existing environment variables.  To create a ``pure''
environment, in which the original environment variables have been unset,
use the @code{--pure} option@footnote{Users sometimes wrongfully augment
environment variables such as @code{PATH} in their @file{~/.bashrc}
file.  As a consequence, when @code{guix environment} launches it, Bash
may read @file{~/.bashrc}, thereby introducing ``impurities'' in these
environment variables.  It is an error to define such environment
variables in @file{.bashrc}; instead, they should be defined in
@file{.bash_profile}, which is sourced only by log-in shells.
@xref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}, for
details on Bash start-up files.}.

@vindex GUIX_ENVIRONMENT
@command{guix environment} defines the @code{GUIX_ENVIRONMENT}
variable in the shell it spawns; its value is the file name of the
profile of this environment.  This allows users to, say, define a
specific prompt for development environments in their @file{.bashrc}
(@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):

@example
if [ -n "$GUIX_ENVIRONMENT" ]
then
    export PS1="\u@@\h \w [dev]\$ "
fi
@end example

@noindent
... or to browse the profile:

@example
$ ls "$GUIX_ENVIRONMENT/bin"
@end example

Additionally, more than one package may be specified, in which case the
union of the inputs for the given packages are used.  For example, the
command below spawns a shell where all of the dependencies of both Guile
and Emacs are available:

@example
guix environment guile emacs
@end example

Sometimes an interactive shell session is not desired.  An arbitrary
command may be invoked by placing the @code{--} token to separate the
command from the rest of the arguments:

@example
guix environment guile -- make -j4
@end example

In other situations, it is more convenient to specify the list of
packages needed in the environment.  For example, the following command
runs @command{python} from an environment containing Python@tie{}2.7 and
NumPy:

@example
guix environment --ad-hoc python2-numpy python-2.7 -- python
@end example

Furthermore, one might want the dependencies of a package and also some
additional packages that are not build-time or runtime dependencies, but
are useful when developing nonetheless.  Because of this, the
@code{--ad-hoc} flag is positional.  Packages appearing before
@code{--ad-hoc} are interpreted as packages whose dependencies will be
added to the environment.  Packages appearing after are interpreted as
packages that will be added to the environment directly.  For example,
the following command creates a Guix development environment that
additionally includes Git and strace:

@example
guix environment guix --ad-hoc git strace
@end example

Sometimes it is desirable to isolate the environment as much as
possible, for maximal purity and reproducibility.  In particular, when
using Guix on a host distro that is not GuixSD, it is desirable to
prevent access to @file{/usr/bin} and other system-wide resources from
the development environment.  For example, the following command spawns
a Guile REPL in a ``container'' where only the store and the current
working directory are mounted:

@example
guix environment --ad-hoc --container guile -- guile
@end example

@quotation Note
The @code{--container} option requires Linux-libre 3.19 or newer.
@end quotation

The available options are summarized below.

@table @code
@item --root=@var{file}
@itemx -r @var{file}
@cindex persistent environment
@cindex garbage collector root, for environments
Make @var{file} a symlink to the profile for this environment, and
register it as a garbage collector root.

This is useful if you want to protect your environment from garbage
collection, to make it ``persistent''.

When this option is omitted, the environment is protected from garbage
collection only for the duration of the @command{guix environment}
session.  This means that next time you recreate the same environment,
you could have to rebuild or re-download packages.

@item --expression=@var{expr}
@itemx -e @var{expr}
Create an environment for the package or list of packages that
@var{expr} evaluates to.

For example, running:

@example
guix environment -e '(@@ (gnu packages maths) petsc-openmpi)'
@end example

starts a shell with the environment for this specific variant of the
PETSc package.

Running:

@example
guix environment --ad-hoc -e '(@@ (gnu) %base-packages)'
@end example

starts a shell with all the GuixSD base packages available.

The above commands only use the default output of the given packages.
To select other outputs, two element tuples can be specified:

@example
guix environment --ad-hoc -e '(list (@ (gnu packages bash) bash) "include")'
@end example

@item --load=@var{file}
@itemx -l @var{file}
Create an environment for the package or list of packages that the code
within @var{file} evaluates to.

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

@example
@verbatiminclude environment-gdb.scm
@end example

@item --ad-hoc
Include all specified packages in the resulting environment, as if an
@i{ad hoc} package were defined with them as inputs.  This option is
useful for quickly creating an environment without having to write a
package expression to contain the desired inputs.

For instance, the command:

@example
guix environment --ad-hoc guile guile-sdl -- guile
@end example

runs @command{guile} in an environment where Guile and Guile-SDL are
available.

Note that this example implicitly asks for the default output of
@code{guile} and @code{guile-sdl}, but it is possible to ask for a
specific output---e.g., @code{glib:bin} asks for the @code{bin} output
of @code{glib} (@pxref{Packages with Multiple Outputs}).

This option may be composed with the default behavior of @command{guix
environment}.  Packages appearing before @code{--ad-hoc} are interpreted
as packages whose dependencies will be added to the environment, the
default behavior.  Packages appearing after are interpreted as packages
that will be added to the environment directly.

@item --pure
Unset existing environment variables when building the new environment.
This has the effect of creating an environment in which search paths
only contain package inputs.

@item --search-paths
Display the environment variable definitions that make up the
environment.

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

@item --container
@itemx -C
@cindex container
Run @var{command} within an isolated container.  The current working
directory outside the container is mapped inside the container.
Additionally, a dummy home directory is created that matches the current
user's home directory, and @file{/etc/passwd} is configured accordingly.
The spawned process runs as the current user outside the container, but
has root privileges in the context of the container.

@item --network
@itemx -N
For containers, share the network namespace with the host system.
Containers created without this flag only have access to the loopback
device.

@item --expose=@var{source}[=@var{target}]
For containers, expose the file system @var{source} from the host system
as the read-only file system @var{target} within the container.  If
@var{target} is not specified, @var{source} is used as the target mount
point in the container.

The example below spawns a Guile REPL in a container in which the user's
home directory is accessible read-only via the @file{/exchange}
directory:

@example
guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
@end example

@item --share=@var{source}[=@var{target}]
For containers, share the file system @var{source} from the host system
as the writable file system @var{target} within the container.  If
@var{target} is not specified, @var{source} is used as the target mount
point in the container.

The example below spawns a Guile REPL in a container in which the user's
home directory is accessible for both reading and writing via the
@file{/exchange} directory:

@example
guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile
@end example
@end table

@command{guix environment}
also supports all of the common build options that @command{guix
build} supports (@pxref{Common Build Options}).


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

@cindex @command{guix publish}
The purpose of @command{guix publish} is to enable users to easily share
their store with others, who can then use it as a substitute server
(@pxref{Substitutes}).

When @command{guix publish} runs, it spawns an HTTP server which allows
anyone with network access to obtain substitutes from it.  This means
that any machine running Guix can also act as if it were a build farm,
since the HTTP interface is compatible with Hydra, the software behind
the @code{hydra.gnu.org} build farm.

For security, each substitute is signed, allowing recipients to check
their authenticity and integrity (@pxref{Substitutes}).  Because
@command{guix publish} uses the signing key of the system, which is only
readable by the system administrator, it must be started as root; the
@code{--user} option makes it drop root privileges early on.

The signing key pair must be generated before @command{guix publish} is
launched, using @command{guix archive --generate-key} (@pxref{Invoking
guix archive}).

The general syntax is:

@example
guix publish @var{options}@dots{}
@end example

Running @command{guix publish} without any additional arguments will
spawn an HTTP server on port 8080:

@example
guix publish
@end example

Once a publishing server has been authorized (@pxref{Invoking guix
archive}), the daemon may download substitutes from it:

@example
guix-daemon --substitute-urls=http://example.org:8080
@end example

By default, @command{guix publish} compresses archives on the fly as it
serves them.  This ``on-the-fly'' mode is convenient in that it requires
no setup and is immediately available.  However, when serving lots of
clients, we recommend using the @option{--cache} option, which enables
caching of the archives before they are sent to clients---see below for
details.

As a bonus, @command{guix publish} also serves as a content-addressed
mirror for source files referenced in @code{origin} records
(@pxref{origin Reference}).  For instance, assuming @command{guix
publish} is running on @code{example.org}, the following URL returns the
raw @file{hello-2.10.tar.gz} file with the given SHA256 hash
(represented in @code{nix-base32} format, @pxref{Invoking guix hash}):

@example
http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i
@end example

Obviously, these URLs only work for files that are in the store; in
other cases, they return 404 (``Not Found'').

The following options are available:

@table @code
@item --port=@var{port}
@itemx -p @var{port}
Listen for HTTP requests on @var{port}.

@item --listen=@var{host}
Listen on the network interface for @var{host}.  The default is to
accept connections from any interface.

@item --user=@var{user}
@itemx -u @var{user}
Change privileges to @var{user} as soon as possible---i.e., once the
server socket is open and the signing key has been read.

@item --compression[=@var{level}]
@itemx -C [@var{level}]
Compress data using the given @var{level}.  When @var{level} is zero,
disable compression.  The range 1 to 9 corresponds to different gzip
compression levels: 1 is the fastest, and 9 is the best (CPU-intensive).
The default is 3.

Unless @option{--cache} is used, compression occurs on the fly and
the compressed streams are not
cached.  Thus, to reduce load on the machine that runs @command{guix
publish}, it may be a good idea to choose a low compression level, to
run @command{guix publish} behind a caching proxy, or to use
@option{--cache}.  Using @option{--cache} has the advantage that it
allows @command{guix publish} to add @code{Content-Length} HTTP header
to its responses.

@item --cache=@var{directory}
@itemx -c @var{directory}
Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory}
and only serve archives that are in cache.

When this option is omitted, archives and meta-data are created
on-the-fly.  This can reduce the available bandwidth, especially when
compression is enabled, since this may become CPU-bound.  Another
drawback of the default mode is that the length of archives is not known
in advance, so @command{guix publish} does not add a
@code{Content-Length} HTTP header to its responses, which in turn
prevents clients from knowing the amount of data being downloaded.

Conversely, when @option{--cache} is used, the first request for a store
item (@i{via} a @code{.narinfo} URL) returns 404 and triggers a
background process to @dfn{bake} the archive---computing its
@code{.narinfo} and compressing the archive, if needed.  Once the
archive is cached in @var{directory}, subsequent requests succeed and
are served directly from the cache, which guarantees that clients get
the best possible bandwidth.

The ``baking'' process is performed by worker threads.  By default, one
thread per CPU core is created, but this can be customized.  See
@option{--workers} below.

@item --workers=@var{N}
When @option{--cache} is used, request the allocation of @var{N} worker
threads to ``bake'' archives.

@item --ttl=@var{ttl}
Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
(TTL) of @var{ttl}.  @var{ttl} must denote a duration: @code{5d} means 5
days, @code{1m} means 1 month, and so on.

This allows the user's Guix to keep substitute information in cache for
@var{ttl}.  However, note that @code{guix publish} does not itself
guarantee that the store items it provides will indeed remain available
for as long as @var{ttl}.

@item --nar-path=@var{path}
Use @var{path} as the prefix for the URLs of ``nar'' files
(@pxref{Invoking guix archive, normalized archives}).

By default, nars are served at a URL such as
@code{/nar/gzip/@dots{}-coreutils-8.25}.  This option allows you to
change the @code{/nar} part to @var{path}.

@item --public-key=@var{file}
@itemx --private-key=@var{file}
Use the specific @var{file}s as the public/private key pair used to sign
the store items being published.

The files must correspond to the same key pair (the private key is used
for signing and the public key is merely advertised in the signature
metadata).  They must contain keys in the canonical s-expression format
as produced by @command{guix archive --generate-key} (@pxref{Invoking
guix archive}).  By default, @file{/etc/guix/signing-key.pub} and
@file{/etc/guix/signing-key.sec} are used.

@item --repl[=@var{port}]
@itemx -r [@var{port}]
Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
Reference Manual}) on @var{port} (37146 by default).  This is used
primarily for debugging a running @command{guix publish} server.
@end table

Enabling @command{guix publish} on a GuixSD system is a one-liner: just
instantiate a @code{guix-publish-service-type} service in the @code{services} field
of the @code{operating-system} declaration (@pxref{guix-publish-service-type,
@code{guix-publish-service-type}}).

If you are instead running Guix on a ``foreign distro'', follow these
instructions:”

@itemize
@item
If your host distro uses the systemd init system:

@example
# ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \
        /etc/systemd/system/
# systemctl start guix-publish && systemctl enable guix-publish
@end example

@item
If your host distro uses the Upstart init system:

@example
# ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/
# start guix-publish
@end example

@item
Otherwise, proceed similarly with your distro's init system.
@end itemize

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

@cindex reproducible builds
@cindex verifiable builds
@cindex @command{guix challenge}
@cindex challenge
Do the binaries provided by this server really correspond to the source
code it claims to build?  Is a package build process deterministic?
These are the questions the @command{guix challenge} command attempts to
answer.

The former is obviously an important question: Before using a substitute
server (@pxref{Substitutes}), one had better @emph{verify} that it
provides the right binaries, and thus @emph{challenge} it.  The latter
is what enables the former: If package builds are deterministic, then
independent builds of the package should yield the exact same result,
bit for bit; if a server provides a binary different from the one
obtained locally, it may be either corrupt or malicious.

We know that the hash that shows up in @file{/gnu/store} file names is
the hash of all the inputs of the process that built the file or
directory---compilers, libraries, build scripts,
etc. (@pxref{Introduction}).  Assuming deterministic build processes,
one store file name should map to exactly one build output.
@command{guix challenge} checks whether there is, indeed, a single
mapping by comparing the build outputs of several independent builds of
any given store item.

The command output looks like this:

@smallexample
$ guix challenge --substitute-urls="https://hydra.gnu.org https://guix.example.org"
updating list of substitutes from 'https://hydra.gnu.org'... 100.0%
updating list of substitutes from 'https://guix.example.org'... 100.0%
/gnu/store/@dots{}-openssl-1.0.2d contents differ:
  local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
  https://hydra.gnu.org/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
  https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
/gnu/store/@dots{}-git-2.5.0 contents differ:
  local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
  https://hydra.gnu.org/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
  https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
/gnu/store/@dots{}-pius-2.1.1 contents differ:
  local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
  https://hydra.gnu.org/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
  https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
@end smallexample

@noindent
In this example, @command{guix challenge} first scans the store to
determine the set of locally-built derivations---as opposed to store
items that were downloaded from a substitute server---and then queries
all the substitute servers.  It then reports those store items for which
the servers obtained a result different from the local build.

@cindex non-determinism, in package builds
As an example, @code{guix.example.org} always gets a different answer.
Conversely, @code{hydra.gnu.org} agrees with local builds, except in the
case of Git.  This might indicate that the build process of Git is
non-deterministic, meaning that its output varies as a function of
various things that Guix does not fully control, in spite of building
packages in isolated environments (@pxref{Features}).  Most common
sources of non-determinism include the addition of timestamps in build
results, the inclusion of random numbers, and directory listings sorted
by inode number.  See @uref{https://reproducible-builds.org/docs/}, for
more information.

To find out what is wrong with this Git binary, we can do something along
these lines (@pxref{Invoking guix archive}):

@example
$ wget -q -O - https://hydra.gnu.org/nar/@dots{}-git-2.5.0 \
   | guix archive -x /tmp/git
$ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
@end example

This command shows the difference between the files resulting from the
local build, and the files resulting from the build on
@code{hydra.gnu.org} (@pxref{Overview, Comparing and Merging Files,,
diffutils, Comparing and Merging Files}).  The @command{diff} command
works great for text files.  When binary files differ, a better option
is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps
visualize differences for all kinds of files.

Once you have done that work, you can tell whether the differences are due
to a non-deterministic build process or to a malicious server.  We try
hard to remove sources of non-determinism in packages to make it easier
to verify substitutes, but of course, this is a process that
involves not just Guix, but a large part of the free software community.
In the meantime, @command{guix challenge} is one tool to help address
the problem.

If you are writing packages for Guix, you are encouraged to check
whether @code{hydra.gnu.org} and other substitute servers obtain the
same build result as you did with:

@example
$ guix challenge @var{package}
@end example

@noindent
where @var{package} is a package specification such as
@code{guile@@2.0} or @code{glibc:debug}.

The general syntax is:

@example
guix challenge @var{options} [@var{packages}@dots{}]
@end example

When a difference is found between the hash of a locally-built item and
that of a server-provided substitute, or among substitutes provided by
different servers, the command displays it as in the example above and
its exit code is 2 (other non-zero exit codes denote other kinds of
errors.)

The one option that matters is:

@table @code

@item --substitute-urls=@var{urls}
Consider @var{urls} the whitespace-separated list of substitute source
URLs to compare to.

@item --verbose
@itemx -v
Show details about matches (identical contents) in addition to
information about mismatches.

@end table

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

@cindex copy, of store items, over SSH
@cindex SSH, copy of store items
@cindex sharing store items across machines
@cindex transferring store items across machines
The @command{guix copy} command copies items from the store of one
machine to that of another machine over a secure shell (SSH)
connection@footnote{This command is available only when Guile-SSH was
found.  @xref{Requirements}, for details.}.  For example, the following
command copies the @code{coreutils} package, the user's profile, and all
their dependencies over to @var{host}, logged in as @var{user}:

@example
guix copy --to=@var{user}@@@var{host} \
          coreutils `readlink -f ~/.guix-profile`
@end example

If some of the items to be copied are already present on @var{host},
they are not actually sent.

The command below retrieves @code{libreoffice} and @code{gimp} from
@var{host}, assuming they are available there:

@example
guix copy --from=@var{host} libreoffice gimp
@end example

The SSH connection is established using the Guile-SSH client, which is
compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and
@file{~/.ssh/config}, and uses the SSH agent for authentication.

The key used to sign items that are sent must be accepted by the remote
machine.  Likewise, the key used by the remote machine to sign items you
are retrieving must be in @file{/etc/guix/acl} so it is accepted by your
own daemon.  @xref{Invoking guix archive}, for more information about
store item authentication.

The general syntax is:

@example
guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{}
@end example

You must always specify one of the following options:

@table @code
@item --to=@var{spec}
@itemx --from=@var{spec}
Specify the host to send to or receive from.  @var{spec} must be an SSH
spec such as @code{example.org}, @code{charlie@@example.org}, or
@code{charlie@@example.org:2222}.
@end table

The @var{items} can be either package names, such as @code{gimp}, or
store items, such as @file{/gnu/store/@dots{}-idutils-4.6}.

When specifying the name of a package to send, it is first built if
needed, unless @option{--dry-run} was specified.  Common build options
are supported (@pxref{Common Build Options}).


@node Invoking guix container
@section Invoking @command{guix container}
@cindex container
@cindex @command{guix container}
@quotation Note
As of version @value{VERSION}, this tool is experimental.  The interface
is subject to radical change in the future.
@end quotation

The purpose of @command{guix container} is to manipulate processes
running within an isolated environment, commonly known as a
``container'', typically created by the @command{guix environment}
(@pxref{Invoking guix environment}) and @command{guix system container}
(@pxref{Invoking guix system}) commands.

The general syntax is:

@example
guix container @var{action} @var{options}@dots{}
@end example

@var{action} specifies the operation to perform with a container, and
@var{options} specifies the context-specific arguments for the action.

The following actions are available:

@table @code
@item exec
Execute a command within the context of a running container.

The syntax is:

@example
guix container exec @var{pid} @var{program} @var{arguments}@dots{}
@end example

@var{pid} specifies the process ID of the running container.
@var{program} specifies an executable file name within the root file
system of the container.  @var{arguments} are the additional options that
will be passed to @var{program}.

The following command launches an interactive login shell inside a
GuixSD container, started by @command{guix system container}, and whose
process ID is 9001:

@example
guix container exec 9001 /run/current-system/profile/bin/bash --login
@end example

Note that the @var{pid} cannot be the parent process of a container.  It
must be PID 1 of the container or one of its child processes.

@end table

@c *********************************************************************
@node GNU Distribution
@chapter GNU Distribution

@cindex Guix System Distribution
@cindex GuixSD
Guix comes with a distribution of the GNU system consisting entirely of
free software@footnote{The term ``free'' here refers to the
@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
users of that software}.}.  The
distribution can be installed on its own (@pxref{System Installation}),
but it is also possible to install Guix as a package manager on top of
an installed GNU/Linux system (@pxref{Installation}).  To distinguish
between the two, we refer to the standalone distribution as the Guix
System Distribution, or GuixSD.

The distribution provides core GNU packages such as GNU libc, GCC, and
Binutils, as well as many GNU and non-GNU applications.  The complete
list of available packages can be browsed
@url{http://www.gnu.org/software/guix/packages,on-line} or by
running @command{guix package} (@pxref{Invoking guix package}):

@example
guix package --list-available
@end example

Our goal is to provide a practical 100% free software distribution of
Linux-based and other variants of GNU, with a focus on the promotion and
tight integration of GNU components, and an emphasis on programs and
tools that help users exert that freedom.

Packages are currently available on the following platforms:

@table @code

@item x86_64-linux
Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;

@item i686-linux
Intel 32-bit architecture (IA32), Linux-Libre kernel;

@item armhf-linux
ARMv7-A architecture with hard float, Thumb-2 and NEON,
using the EABI hard-float application binary interface (ABI),
and Linux-Libre kernel.

@item aarch64-linux
little-endian 64-bit ARMv8-A processors, Linux-Libre kernel.  This is
currently in an experimental stage, with limited support.
@xref{Contributing}, for how to help!

@item mips64el-linux
little-endian 64-bit MIPS processors, specifically the Loongson series,
n32 ABI, and Linux-Libre kernel.

@end table

GuixSD itself is currently only available on @code{i686} and @code{x86_64}.

@noindent
For information on porting to other architectures or kernels,
@pxref{Porting}.

@menu
* System Installation::         Installing the whole operating system.
* System Configuration::        Configuring the operating system.
* Documentation::                Browsing software user manuals.
* Installing Debugging Files::  Feeding the debugger.
* Security Updates::            Deploying security fixes quickly.
* Package Modules::             Packages from the programmer's viewpoint.
* Packaging Guidelines::        Growing the distribution.
* Bootstrapping::               GNU/Linux built from scratch.
* Porting::                     Targeting another platform or kernel.
@end menu

Building this distribution is a cooperative effort, and you are invited
to join!  @xref{Contributing}, for information about how you can help.