guix.texi

@command{guix} commands that can perform builds, as in the example
below:

@example
$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
@end example

These options are parsed independently, and the result is appended to
the parsed command-line options.
@end defvr


@node Package Transformation Options
@subsection Package Transformation Options

@cindex package variants
Another set of command-line options supported by @command{guix build}
and also @command{guix package} are @dfn{package transformation
options}.  These are options that make it possible to define @dfn{package
variants}---for instance, packages built from different source code.
This is a convenient way to create customized packages on the fly
without having to type in the definitions of package variants
(@pxref{Defining Packages}).

@table @code

@item --with-source=@var{source}
Use @var{source} as the source of the corresponding package.
@var{source} must be a file name or a URL, as for @command{guix
download} (@pxref{Invoking guix download}).

The ``corresponding package'' is taken to be the one specified on the
command line the name of which matches the base of @var{source}---e.g.,
if @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
package is @code{guile}.  Likewise, the version string is inferred from
@var{source}; in the previous example, it is @code{2.0.10}.

This option allows users to try out versions of packages other than the
one provided by the distribution.  The example below downloads
@file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
the @code{ed} package:

@example
guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
@end example

As a developer, @code{--with-source} makes it easy to test release
candidates:

@example
guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
@end example

@dots{} or to build from a checkout in a pristine environment:

@example
$ git clone git://git.sv.gnu.org/guix.git
$ guix build guix --with-source=./guix
@end example

@item --with-input=@var{package}=@var{replacement}
Replace dependency on @var{package} by a dependency on
@var{replacement}.  @var{package} must be a package name, and
@var{replacement} must be a package specification such as @code{guile}
or @code{guile@@1.8}.

For instance, the following command builds Guix, but replaces its
dependency on the current stable version of Guile with a dependency on
the legacy version of Guile, @code{guile@@2.0}:

@example
guix build --with-input=guile=guile@@2.0 guix
@end example

This is a recursive, deep replacement.  So in this example, both
@code{guix} and its dependency @code{guile-json} (which also depends on
@code{guile}) get rebuilt against @code{guile@@2.0}.

This is implemented using the @code{package-input-rewriting} Scheme
procedure (@pxref{Defining Packages, @code{package-input-rewriting}}).

@item --with-graft=@var{package}=@var{replacement}
This is similar to @code{--with-input} but with an important difference:
instead of rebuilding the whole dependency chain, @var{replacement} is
built and then @dfn{grafted} onto the binaries that were initially
referring to @var{package}.  @xref{Security Updates}, for more
information on grafts.

For example, the command below grafts version 3.5.4 of GnuTLS onto Wget
and all its dependencies, replacing references to the version of GnuTLS
they currently refer to:

@example
guix build --with-graft=gnutls=gnutls@@3.5.4 wget
@end example

This has the advantage of being much faster than rebuilding everything.
But there is a caveat: it works if and only if @var{package} and
@var{replacement} are strictly compatible---for example, if they provide
a library, the application binary interface (ABI) of those libraries
must be compatible.  If @var{replacement} is somehow incompatible with
@var{package}, then the resulting package may be unusable.  Use with
care!

@end table

@node Additional Build Options
@subsection Additional Build Options

The command-line options presented below are specific to @command{guix
build}.

@table @code

@item --quiet
@itemx -q
Build quietly, without displaying the build log.  Upon completion, the
build log is kept in @file{/var} (or similar) and can always be
retrieved using the @option{--log-file} option.

@item --file=@var{file}
@itemx -f @var{file}

Build the package or derivation that the code within @var{file}
evaluates to.

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

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

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

For example, @var{expr} may be @code{(@@ (gnu packages guile)
guile-1.8)}, which unambiguously designates this specific variant of
version 1.8 of Guile.

Alternatively, @var{expr} may be a G-expression, in which case it is used
as a build program passed to @code{gexp->derivation}
(@pxref{G-Expressions}).

Lastly, @var{expr} may refer to a zero-argument monadic procedure
(@pxref{The Store Monad}).  The procedure must return a derivation as a
monadic value, which is then passed through @code{run-with-store}.

@item --source
@itemx -S
Build the source derivations of the packages, rather than the packages
themselves.

For instance, @code{guix build -S gcc} returns something like
@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is the GCC
source tarball.

The returned source tarball is the result of applying any patches and
code snippets specified in the package @code{origin} (@pxref{Defining
Packages}).

@item --sources
Fetch and return the source of @var{package-or-derivation} and all their
dependencies, recursively.  This is a handy way to obtain a local copy
of all the source code needed to build @var{packages}, allowing you to
eventually build them even without network access.  It is an extension
of the @code{--source} option and can accept one of the following
optional argument values:

@table @code
@item package
This value causes the @code{--sources} option to behave in the same way
as the @code{--source} option.

@item all
Build the source derivations of all packages, including any source that
might be listed as @code{inputs}.  This is the default value.

@example
$ guix build --sources tzdata
The following derivations will be built:
   /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
   /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
@end example

@item transitive
Build the source derivations of all packages, as well of all transitive
inputs to the packages.  This can be used e.g. to
prefetch package source for later offline building.

@example
$ guix build --sources=transitive tzdata
The following derivations will be built:
   /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
   /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
   /gnu/store/@dots{}-grep-2.21.tar.xz.drv
   /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
   /gnu/store/@dots{}-make-4.1.tar.xz.drv
   /gnu/store/@dots{}-bash-4.3.tar.xz.drv
@dots{}
@end example

@end table

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

An example use of this is on Linux-based systems, which can emulate
different personalities.  For instance, passing
@code{--system=i686-linux} on an @code{x86_64-linux} system allows users
to build packages in a complete 32-bit environment.

@item --target=@var{triplet}
@cindex cross-compilation
Cross-build for @var{triplet}, which must be a valid GNU triplet, such
as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU
configuration triplets,, autoconf, Autoconf}).

@anchor{build-check}
@item --check
@cindex determinism, checking
@cindex reproducibility, checking
Rebuild @var{package-or-derivation}, which are already available in the
store, and raise an error if the build results are not bit-for-bit
identical.

This mechanism allows you to check whether previously installed
substitutes are genuine (@pxref{Substitutes}), or whether the build result
of a package is deterministic.  @xref{Invoking guix challenge}, for more
background information and tools.

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

@item --repair
@cindex repairing store items
@cindex corruption, recovering from
Attempt to repair the specified store items, if they are corrupt, by
re-downloading or rebuilding them.

This operation is not atomic and thus restricted to @code{root}.

@item --derivations
@itemx -d
Return the derivation paths, not the output paths, of the given
packages.

@item --root=@var{file}
@itemx -r @var{file}
Make @var{file} a symlink to the result, and register it as a garbage
collector root.

@item --log-file
Return the build log file names or URLs for the given
@var{package-or-derivation}, or raise an error if build logs are
missing.

This works regardless of how packages or derivations are specified.  For
instance, the following invocations are equivalent:

@example
guix build --log-file `guix build -d guile`
guix build --log-file `guix build guile`
guix build --log-file guile
guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
@end example

If a log is unavailable locally, and unless @code{--no-substitutes} is
passed, the command looks for a corresponding log on one of the
substitute servers (as specified with @code{--substitute-urls}.)

So for instance, imagine you want to see the build log of GDB on MIPS,
but you are actually on an @code{x86_64} machine:

@example
$ guix build --log-file gdb -s mips64el-linux
https://hydra.gnu.org/log/@dots{}-gdb-7.10
@end example

You can freely access a huge library of build logs!
@end table

@node Debugging Build Failures
@subsection Debugging Build Failures

@cindex build failures, debugging
When defining a new package (@pxref{Defining Packages}), you will
probably find yourself spending some time debugging and tweaking the
build until it succeeds.  To do that, you need to operate the build
commands yourself in an environment as close as possible to the one the
build daemon uses.

To that end, the first thing to do is to use the @option{--keep-failed}
or @option{-K} option of @command{guix build}, which will keep the
failed build tree in @file{/tmp} or whatever directory you specified as
@code{TMPDIR} (@pxref{Invoking guix build, @code{--keep-failed}}).

From there on, you can @command{cd} to the failed build tree and source
the @file{environment-variables} file, which contains all the
environment variable definitions that were in place when the build
failed.  So let's say you're debugging a build failure in package
@code{foo}; a typical session would look like this:

@example
$ guix build foo -K
@dots{} @i{build fails}
$ cd /tmp/guix-build-foo.drv-0
$ source ./environment-variables
$ cd foo-1.2
@end example

Now, you can invoke commands as if you were the daemon (almost) and
troubleshoot your build process.

Sometimes it happens that, for example, a package's tests pass when you
run them manually but they fail when the daemon runs them.  This can
happen because the daemon runs builds in containers where, unlike in our
environment above, network access is missing, @file{/bin/sh} does not
exist, etc. (@pxref{Build Environment Setup}).

In such cases, you may need to run inspect the build process from within
a container similar to the one the build daemon creates:

@example
$ guix build -K foo
@dots{}
$ cd /tmp/guix-build-foo.drv-0
$ guix environment --no-grafts -C foo --ad-hoc strace gdb
[env]# source ./environment-variables
[env]# cd foo-1.2
@end example

Here, @command{guix environment -C} creates a container and spawns a new
shell in it (@pxref{Invoking guix environment}).  The @command{--ad-hoc
strace gdb} part adds the @command{strace} and @command{gdb} commands to
the container, which would may find handy while debugging.  The
@option{--no-grafts} option makes sure we get the exact same
environment, with ungrafted packages (@pxref{Security Updates}, for more
info on grafts).

To get closer to a container like that used by the build daemon, we can
remove @file{/bin/sh}:

@example
[env]# rm /bin/sh
@end example

(Don't worry, this is harmless: this is all happening in the throw-away
container created by @command{guix environment}.)

The @command{strace} command is probably not in the search path, but we
can run:

@example
[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check
@end example

In this way, not only you will have reproduced the environment variables
the daemon uses, you will also be running the build process in a container
similar to the one the daemon uses.


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

@cindex @command{guix edit}
@cindex package definition, editing
So many packages, so many source files!  The @command{guix edit} command
facilitates the life of users and packagers by pointing their editor at
the source file containing the definition of the specified packages.
For instance:

@example
guix edit gcc@@4.9 vim
@end example

@noindent
launches the program specified in the @code{VISUAL} or in the
@code{EDITOR} environment variable to view the recipe of GCC@tie{}4.9.3
and that of Vim.

If you are using a Guix Git checkout (@pxref{Building from Git}), or
have created your own packages on @code{GUIX_PACKAGE_PATH}
(@pxref{Defining Packages}), you will be able to edit the package
recipes. Otherwise, you will be able to examine the read-only recipes
for packages currently in the store.


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

@cindex @command{guix download}
@cindex downloading package sources
When writing a package definition, developers typically need to download
a source tarball, compute its SHA256 hash, and write that
hash in the package definition (@pxref{Defining Packages}).  The
@command{guix download} tool helps with this task: it downloads a file
from the given URI, adds it to the store, and prints both its file name
in the store and its SHA256 hash.

The fact that the downloaded file is added to the store saves bandwidth:
when the developer eventually tries to build the newly defined package
with @command{guix build}, the source tarball will not have to be
downloaded again because it is already in the store.  It is also a
convenient way to temporarily stash files, which may be deleted
eventually (@pxref{Invoking guix gc}).

The @command{guix download} command supports the same URIs as used in
package definitions.  In particular, it supports @code{mirror://} URIs.
@code{https} URIs (HTTP over TLS) are supported @emph{provided} the
Guile bindings for GnuTLS are available in the user's environment; when
they are not available, an error is raised.  @xref{Guile Preparations,
how to install the GnuTLS bindings for Guile,, gnutls-guile,
GnuTLS-Guile}, for more information.

@command{guix download} verifies HTTPS server certificates by loading
the certificates of X.509 authorities from the directory pointed to by
the @code{SSL_CERT_DIR} environment variable (@pxref{X.509
Certificates}), unless @option{--no-check-certificate} is used.

The following options are available:

@table @code
@item --format=@var{fmt}
@itemx -f @var{fmt}
Write the hash in the format specified by @var{fmt}.  For more
information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.

@item --no-check-certificate
Do not validate the X.509 certificates of HTTPS servers.

When using this option, you have @emph{absolutely no guarantee} that you
are communicating with the authentic server responsible for the given
URL, which makes you vulnerable to ``man-in-the-middle'' attacks.

@item --output=@var{file}
@itemx -o @var{file}
Save the downloaded file to @var{file} instead of adding it to the
store.
@end table

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

@cindex @command{guix hash}
The @command{guix hash} command computes the SHA256 hash of a file.
It is primarily a convenience tool for anyone contributing to the
distribution: it computes the cryptographic hash of a file, which can be
used in the definition of a package (@pxref{Defining Packages}).

The general syntax is:

@example
guix hash @var{option} @var{file}
@end example

When @var{file} is @code{-} (a hyphen), @command{guix hash} computes the
hash of data read from standard input.  @command{guix hash} has the
following options:

@table @code

@item --format=@var{fmt}
@itemx -f @var{fmt}
Write the hash in the format specified by @var{fmt}.

Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
(@code{hex} and @code{hexadecimal} can be used as well).

If the @option{--format} option is not specified, @command{guix hash}
will output the hash in @code{nix-base32}.  This representation is used
in the definitions of packages.

@item --recursive
@itemx -r
Compute the hash on @var{file} recursively.

In this case, the hash is computed on an archive containing @var{file},
including its children if it is a directory.  Some of the metadata of
@var{file} is part of the archive; for instance, when @var{file} is a
regular file, the hash is different depending on whether @var{file} is
executable or not.  Metadata such as time stamps has no impact on the
hash (@pxref{Invoking guix archive}).
@c FIXME: Replace xref above with xref to an ``Archive'' section when
@c it exists.

@item --exclude-vcs
@itemx -x
When combined with @option{--recursive}, exclude version control system
directories (@file{.bzr}, @file{.git}, @file{.hg}, etc.)

@vindex git-fetch
As an example, here is how you would compute the hash of a Git checkout,
which is useful when using the @code{git-fetch} method (@pxref{origin
Reference}):

@example
$ git clone http://example.org/foo.git
$ cd foo
$ guix hash -rx .
@end example
@end table

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

@cindex importing packages
@cindex package import
@cindex package conversion
@cindex Invoking @command{guix import}
The @command{guix import} command is useful for people who would like to
add a package to the distribution with as little work as
possible---a legitimate demand.  The command knows of a few
repositories from which it can ``import'' package metadata.  The result
is a package definition, or a template thereof, in the format we know
(@pxref{Defining Packages}).

The general syntax is:

@example
guix import @var{importer} @var{options}@dots{}
@end example

@var{importer} specifies the source from which to import package
metadata, and @var{options} specifies a package identifier and other
options specific to @var{importer}.  Currently, the available
``importers'' are:

@table @code
@item gnu
Import metadata for the given GNU package.  This provides a template
for the latest version of that GNU package, including the hash of its
source tarball, and its canonical synopsis and description.

Additional information such as the package dependencies and its
license needs to be figured out manually.

For example, the following command returns a package definition for
GNU@tie{}Hello:

@example
guix import gnu hello
@end example

Specific command-line options are:

@table @code
@item --key-download=@var{policy}
As for @code{guix refresh}, specify the policy to handle missing OpenPGP
keys when verifying the package signature.  @xref{Invoking guix
refresh, @code{--key-download}}.
@end table

@item pypi
@cindex pypi
Import metadata from the @uref{https://pypi.python.org/, Python Package
Index}@footnote{This functionality requires Guile-JSON to be installed.
@xref{Requirements}.}.  Information is taken from the JSON-formatted
description available at @code{pypi.python.org} and usually includes all
the relevant information, including package dependencies.  For maximum
efficiency, it is recommended to install the @command{unzip} utility, so
that the importer can unzip Python wheels and gather data from them.

The command below imports metadata for the @code{itsdangerous} Python
package:

@example
guix import pypi itsdangerous
@end example

@item gem
@cindex gem
Import metadata from @uref{https://rubygems.org/,
RubyGems}@footnote{This functionality requires Guile-JSON to be
installed.  @xref{Requirements}.}.  Information is taken from the
JSON-formatted description available at @code{rubygems.org} and includes
most relevant information, including runtime dependencies.  There are
some caveats, however.  The metadata doesn't distinguish between
synopses and descriptions, so the same string is used for both fields.
Additionally, the details of non-Ruby dependencies required to build
native extensions is unavailable and left as an exercise to the
packager.

The command below imports metadata for the @code{rails} Ruby package:

@example
guix import gem rails
@end example

@item cpan
@cindex CPAN
Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}@footnote{This
functionality requires Guile-JSON to be installed.
@xref{Requirements}.}.
Information is taken from the JSON-formatted metadata provided through
@uref{https://api.metacpan.org/, MetaCPAN's API} and includes most
relevant information, such as module dependencies.  License information
should be checked closely.  If Perl is available in the store, then the
@code{corelist} utility will be used to filter core modules out of the
list of dependencies.

The command command below imports metadata for the @code{Acme::Boolean}
Perl module:

@example
guix import cpan Acme::Boolean
@end example

@item cran
@cindex CRAN
@cindex Bioconductor
Import metadata from @uref{http://cran.r-project.org/, CRAN}, the
central repository for the @uref{http://r-project.org, GNU@tie{}R
statistical and graphical environment}.

Information is extracted from the @code{DESCRIPTION} file of the package.

The command command below imports metadata for the @code{Cairo}
R package:

@example
guix import cran Cairo
@end example

When @code{--recursive} is added, the importer will traverse the
dependency graph of the given upstream package recursively and generate
package expressions for all those packages that are not yet in Guix.

When @code{--archive=bioconductor} is added, metadata is imported from
@uref{http://www.bioconductor.org/, Bioconductor}, a repository of R
packages for for the analysis and comprehension of high-throughput
genomic data in bioinformatics.

Information is extracted from the @code{DESCRIPTION} file of a package
published on the web interface of the Bioconductor SVN repository.

The command below imports metadata for the @code{GenomicRanges}
R package:

@example
guix import cran --archive=bioconductor GenomicRanges
@end example

@item nix
Import metadata from a local copy of the source of the
@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
relies on the @command{nix-instantiate} command of
@uref{http://nixos.org/nix/, Nix}.}.  Package definitions in Nixpkgs are
typically written in a mixture of Nix-language and Bash code.  This
command only imports the high-level package structure that is written in
the Nix language.  It normally includes all the basic fields of a
package definition.

When importing a GNU package, the synopsis and descriptions are replaced
by their canonical upstream variant.

Usually, you will first need to do:

@example
export NIX_REMOTE=daemon
@end example

@noindent
so that @command{nix-instantiate} does not try to open the Nix database.

As an example, the command below imports the package definition of
LibreOffice (more precisely, it imports the definition of the package
bound to the @code{libreoffice} top-level attribute):

@example
guix import nix ~/path/to/nixpkgs libreoffice
@end example

@item hackage
@cindex hackage
Import metadata from the Haskell community's central package archive
@uref{https://hackage.haskell.org/, Hackage}.  Information is taken from
Cabal files and includes all the relevant information, including package
dependencies.

Specific command-line options are:

@table @code
@item --stdin
@itemx -s
Read a Cabal file from standard input.
@item --no-test-dependencies
@itemx -t
Do not include dependencies required only by the test suites.
@item --cabal-environment=@var{alist}
@itemx -e @var{alist}
@var{alist} is a Scheme alist defining the environment in which the
Cabal conditionals are evaluated.  The accepted keys are: @code{os},
@code{arch}, @code{impl} and a string representing the name of a flag.
The value associated with a flag has to be either the symbol
@code{true} or @code{false}.  The value associated with other keys
has to conform to the Cabal file format definition.  The default value
associated with the keys @code{os}, @code{arch} and @code{impl} is
@samp{linux}, @samp{x86_64} and @samp{ghc}, respectively.
@end table

The command below imports metadata for the latest version of the
@code{HTTP} Haskell package without including test dependencies and
specifying the value of the flag @samp{network-uri} as @code{false}:

@example
guix import hackage -t -e "'((\"network-uri\" . false))" HTTP
@end example

A specific package version may optionally be specified by following the
package name by an at-sign and a version number as in the following example:

@example
guix import hackage mtl@@2.1.3.1
@end example

@item stackage
@cindex stackage
The @code{stackage} importer is a wrapper around the @code{hackage} one.
It takes a package name, looks up the package version included in a
long-term support (LTS) @uref{https://www.stackage.org, Stackage}
release and uses the @code{hackage} importer to retrieve its metadata.
Note that it is up to you to select an LTS release compatible with the
GHC compiler used by Guix.

Specific command-line options are:

@table @code
@item --no-test-dependencies
@itemx -t
Do not include dependencies required only by the test suites.
@item --lts-version=@var{version}
@itemx -r @var{version}
@var{version} is the desired LTS release version.  If omitted the latest
release is used.
@end table

The command below imports metadata for the @code{HTTP} Haskell package
included in the LTS Stackage release version 7.18:

@example
guix import stackage --lts-version=7.18 HTTP
@end example

@item elpa
@cindex elpa
Import metadata from an Emacs Lisp Package Archive (ELPA) package
repository (@pxref{Packages,,, emacs, The GNU Emacs Manual}).

Specific command-line options are:

@table @code
@item --archive=@var{repo}
@itemx -a @var{repo}
@var{repo} identifies the archive repository from which to retrieve the
information.  Currently the supported repositories and their identifiers
are:
@itemize -
@item
@uref{http://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
identifier.  This is the default.

Packages from @code{elpa.gnu.org} are signed with one of the keys
contained in the GnuPG keyring at
@file{share/emacs/25.1/etc/package-keyring.gpg} (or similar) in the
@code{emacs} package (@pxref{Package Installation, ELPA package
signatures,, emacs, The GNU Emacs Manual}).

@item
@uref{http://stable.melpa.org/packages, MELPA-Stable}, selected by the
@code{melpa-stable} identifier.

@item
@uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa}
identifier.
@end itemize
@end table

@item crate
@cindex crate
Import metadata from the crates.io Rust package repository
@uref{https://crates.io, crates.io}.
@end table

The structure of the @command{guix import} code is modular.  It would be
useful to have more importers for other package formats, and your help
is welcome here (@pxref{Contributing}).

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

@cindex @command {guix refresh}
The primary audience of the @command{guix refresh} command is developers
of the GNU software distribution.  By default, it reports any packages
provided by the distribution that are outdated compared to the latest
upstream version, like this:

@example
$ guix refresh
gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
@end example

Alternately, one can specify packages to consider, in which case a
warning is emitted for packages that lack an updater:

@example
$ guix refresh coreutils guile guile-ssh
gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh
gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13
@end example

@command{guix refresh} browses the upstream repository of each package and determines
the highest version number of the releases therein.  The command
knows how to update specific types of packages: GNU packages, ELPA
packages, etc.---see the documentation for @option{--type} below.  There
are many packages, though, for which it lacks a method to determine
whether a new upstream release is available.  However, the mechanism is
extensible, so feel free to get in touch with us to add a new method!

When passed @code{--update}, it modifies distribution source files to
update the version numbers and source tarball hashes of those package
recipes (@pxref{Defining Packages}).  This is achieved by downloading
each package's latest source tarball and its associated OpenPGP
signature, authenticating the downloaded tarball against its signature
using @command{gpg}, and finally computing its hash.  When the public
key used to sign the tarball is missing from the user's keyring, an
attempt is made to automatically retrieve it from a public key server;
when this is successful, the key is added to the user's keyring; otherwise,
@command{guix refresh} reports an error.

The following options are supported:

@table @code

@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 refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)'
@end example

This command lists the dependents of the ``final'' libc (essentially all
the packages.)

@item --update
@itemx -u
Update distribution source files (package recipes) in place.  This is
usually run from a checkout of the Guix source tree (@pxref{Running
Guix Before It Is Installed}):

@example
$ ./pre-inst-env guix refresh -s non-core -u
@end example

@xref{Defining Packages}, for more information on package definitions.

@item --select=[@var{subset}]
@itemx -s @var{subset}
Select all the packages in @var{subset}, one of @code{core} or
@code{non-core}.

The @code{core} subset refers to all the packages at the core of the
distribution---i.e., packages that are used to build ``everything
else''.  This includes GCC, libc, Binutils, Bash, etc.  Usually,
changing one of these packages in the distribution entails a rebuild of
all the others.  Thus, such updates are an inconvenience to users in
terms of build time or bandwidth used to achieve the upgrade.

The @code{non-core} subset refers to the remaining packages.  It is
typically useful in cases where an update of the core packages would be
inconvenient.

@item --manifest=@var{file}
@itemx -m @var{file}
Select all the packages from the manifest in @var{file}. This is useful to
check if any packages of the user manifest can be updated.

@item --type=@var{updater}
@itemx -t @var{updater}
Select only packages handled by @var{updater} (may be a comma-separated
list of updaters).  Currently, @var{updater} may be one of:

@table @code
@item gnu
the updater for GNU packages;
@item gnome
the updater for GNOME packages;
@item kde
the updater for KDE packages;
@item xorg
the updater for X.org packages;
@item kernel.org
the updater for packages hosted on kernel.org;
@item elpa
the updater for @uref{http://elpa.gnu.org/, ELPA} packages;
@item cran
the updater for @uref{http://cran.r-project.org/, CRAN} packages;
@item bioconductor
the updater for @uref{http://www.bioconductor.org/, Bioconductor} R packages;
@item cpan
the updater for @uref{http://www.cpan.org/, CPAN} packages;
@item pypi
the updater for @uref{https://pypi.python.org, PyPI} packages.
@item gem
the updater for @uref{https://rubygems.org, RubyGems} packages.
@item github
the updater for @uref{https://github.com, GitHub} packages.
@item hackage
the updater for @uref{https://hackage.haskell.org, Hackage} packages.
@item stackage
the updater for @uref{https://www.stackage.org, Stackage} packages.
@item crate
the updater for @uref{https://crates.io, Crates} packages.
@end table

For instance, the following command only checks for updates of Emacs
packages hosted at @code{elpa.gnu.org} and for updates of CRAN packages:

@example
$ guix refresh --type=elpa,cran
gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0
gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9
@end example

@end table

In addition, @command{guix refresh} can be passed one or more package
names, as in this example:

@example
$ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8
@end example

@noindent
The command above specifically updates the @code{emacs} and
@code{idutils} packages.  The @code{--select} option would have no
effect in this case.

When considering whether to upgrade a package, it is sometimes
convenient to know which packages would be affected by the upgrade and
should be checked for compatibility.  For this the following option may
be used when passing @command{guix refresh} one or more package names:

@table @code

@item --list-updaters
@itemx -L
List available updaters and exit (see @option{--type} above.)

For each updater, display the fraction of packages it covers; at the
end, display the fraction of packages covered by all these updaters.

@item --list-dependent
@itemx -l
List top-level dependent packages that would need to be rebuilt as a
result of upgrading one or more packages.

@xref{Invoking guix graph, the @code{reverse-package} type of
@command{guix graph}}, for information on how to visualize the list of
dependents of a package.

@end table

Be aware that the @code{--list-dependent} option only
@emph{approximates} the rebuilds that would be required as a result of
an upgrade.  More rebuilds might be required under some circumstances.

@example
$ guix refresh --list-dependent flex
Building the following 120 packages would ensure 213 dependent packages are rebuilt:
hop@@2.4.0 geiser@@0.4 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{}
@end example

The command above lists a set of packages that could be built to check
for compatibility with an upgraded @code{flex} package.

The following options can be used to customize GnuPG operation:

@table @code

@item --gpg=@var{command}
Use @var{command} as the GnuPG 2.x command.  @var{command} is searched
for in @code{$PATH}.

@item --key-download=@var{policy}
Handle missing OpenPGP keys according to @var{policy}, which may be one
of:

@table @code
@item always
Always download missing OpenPGP keys from the key server, and add them
to the user's GnuPG keyring.