guix.texi

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

It does so by browsing the FTP directory of each package and determining
the highest version number of the source tarballs therein.  The command
knows how to update specific types of packages: GNU packages, ELPA
packages, etc.---see the documentation for @option{--type} below.  The
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
@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 --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 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 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.
@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.4
@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.)

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

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

@item never
Never try to download missing OpenPGP keys.  Instead just bail out.

@item interactive
When a package signed with an unknown OpenPGP key is encountered, ask
the user whether to download it or not.  This is the default behavior.
@end table

@item --key-server=@var{host}
Use @var{host} as the OpenPGP key server when importing a public key.

@end table

The @code{github} updater uses the
@uref{https://developer.github.com/v3/, GitHub API} to query for new
releases.  When used repeatedly e.g. when refreshing all packages,
GitHub will eventually refuse to answer any further API requests.  By
default 60 API requests per hour are allowed, and a full refresh on all
GitHub packages in Guix requires more than this.  Authentication with
GitHub through the use of an API token alleviates these limits.  To use
an API token, set the environment variable @code{GUIX_GITHUB_TOKEN} to a
token procured from @uref{https://github.com/settings/tokens} or
otherwise.


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

@cindex @command{guix lint}
@cindex package, checking for errors
The @command{guix lint} command is meant to help package developers avoid
common errors and use a consistent style.  It runs a number of checks on
a given set of packages in order to find common mistakes in their
definitions.  Available @dfn{checkers} include (see
@code{--list-checkers} for a complete list):

@table @code
@item synopsis
@itemx description
Validate certain typographical and stylistic rules about package
descriptions and synopses.

@item inputs-should-be-native
Identify inputs that should most likely be native inputs.

@item source
@itemx home-page
@itemx mirror-url
@itemx source-file-name
Probe @code{home-page} and @code{source} URLs and report those that are
invalid.  Suggest a @code{mirror://} URL when applicable.  Check that
the source file name is meaningful, e.g. is not
just a version number or ``git-checkout'', without a declared
@code{file-name} (@pxref{origin Reference}).

@item cve
@cindex security vulnerabilities
@cindex CVE, Common Vulnerabilities and Exposures
Report known vulnerabilities found in the Common Vulnerabilities and
Exposures (CVE) databases of the current and past year
@uref{https://nvd.nist.gov/download.cfm#CVE_FEED, published by the US
NIST}.

To view information about a particular vulnerability, visit pages such as:

@itemize
@item
@indicateurl{https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD}
@item
@indicateurl{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD}
@end itemize

@noindent
where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g.,
@code{CVE-2015-7554}.

Package developers can specify in package recipes the
@uref{https://nvd.nist.gov/cpe.cfm,Common Platform Enumeration (CPE)}
name and version of the package when they differ from the name that Guix
uses, as in this example:

@example
(package
  (name "grub")
  ;; @dots{}
  ;; CPE calls this package "grub2".
  (properties '((cpe-name . "grub2"))))
@end example

@item formatting
Warn about obvious source code formatting issues: trailing white space,
use of tabulations, etc.
@end table

The general syntax is:

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

If no package is given on the command line, then all packages are checked.
The @var{options} may be zero or more of the following:

@table @code
@item --list-checkers
@itemx -l
List and describe all the available checkers that will be run on packages
and exit.

@item --checkers
@itemx -c
Only enable the checkers specified in a comma-separated list using the
names returned by @code{--list-checkers}.

@end table

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

@cindex size
@cindex package size
@cindex closure
@cindex @command{guix size}
The @command{guix size} command helps package developers profile the
disk usage of packages.  It is easy to overlook the impact of an
additional dependency added to a package, or the impact of using a
single output for a package that could easily be split (@pxref{Packages
with Multiple Outputs}).  Such are the typical issues that
@command{guix size} can highlight.

The command can be passed a package specification such as @code{gcc-4.8}
or @code{guile:debug}, or a file name in the store.  Consider this
example:

@example
$ guix size coreutils
store item                               total    self
/gnu/store/@dots{}-coreutils-8.23          70.0    13.9  19.8%
/gnu/store/@dots{}-gmp-6.0.0a              55.3     2.5   3.6%
/gnu/store/@dots{}-acl-2.2.52              53.7     0.5   0.7%
/gnu/store/@dots{}-attr-2.4.46             53.2     0.3   0.5%
/gnu/store/@dots{}-gcc-4.8.4-lib           52.9    15.7  22.4%
/gnu/store/@dots{}-glibc-2.21              37.2    37.2  53.1%
@end example

@cindex closure
The store items listed here constitute the @dfn{transitive closure} of
Coreutils---i.e., Coreutils and all its dependencies, recursively---as
would be returned by:

@example
$ guix gc -R /gnu/store/@dots{}-coreutils-8.23
@end example

Here the output shows three columns next to store items.  The first column,
labeled ``total'', shows the size in mebibytes (MiB) of the closure of
the store item---that is, its own size plus the size of all its
dependencies.  The next column, labeled ``self'', shows the size of the
item itself.  The last column shows the ratio of the size of the item
itself to the space occupied by all the items listed here.

In this example, we see that the closure of Coreutils weighs in at
70@tie{}MiB, half of which is taken by libc.  (That libc represents a
large fraction of the closure is not a problem @i{per se} because it is
always available on the system anyway.)

When the package passed to @command{guix size} is available in the
store, @command{guix size} queries the daemon to determine its
dependencies, and measures its size in the store, similar to @command{du
-ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU
Coreutils}).

When the given package is @emph{not} in the store, @command{guix size}
reports information based on the available substitutes
(@pxref{Substitutes}).  This makes it possible it to profile disk usage of
store items that are not even on disk, only available remotely.

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.  @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.  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 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 --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 --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 the use 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 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 guile -- guile
@end example
@end table

It 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