doc: Add a "Development" chapter.

* doc/guix.texi (Managing Software the Guix Way): Add reference to the
"Development" section.
(Invoking guix environment, Invoking guix pack): Move to...
(Development): ... here.  New node.

1 files changed, 526 insertions, 492 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 6980672094..1ac077d98a 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -119,6 +119,7 @@ Project}.
 * Installation::                Installing Guix.
 * System Installation::         Installing the whole operating system.
 * Package Management::          Package installation, upgrade, etc.
+* Development::                 Guix-aided software development.
 * Programming Interface::       Using Guix in Scheme.
 * Utilities::                   Package management commands.
 * System Configuration::        Configuring the operating system.
@@ -137,6 +138,11 @@ Project}.
 @detailmenu
  --- The Detailed Node Listing ---
 
+Introduction
+
+* Managing Software the Guix Way::      What's special.
+* GNU Distribution::                    The packages and tools.
+
 Installation
 
 * Binary Installation::         Getting Guix running in no time!
@@ -159,7 +165,7 @@ System Installation
 * USB Stick and DVD Installation::  Preparing the installation medium.
 * Preparing for Installation::  Networking, partitioning, etc.
 * Proceeding with the Installation::  The real thing.
-* Installing Guix in a VM::   Guix System playground.
+* Installing Guix in a VM::     Guix System playground.
 * Building the Installation Image::  How this comes to be.
 
 Package Management
@@ -173,7 +179,6 @@ Package Management
 * Channels::                    Customizing the package collection.
 * Inferiors::                   Interacting with another revision of Guix.
 * Invoking guix describe::      Display information about your Guix revision.
-* Invoking guix pack::          Creating software bundles.
 * Invoking guix archive::       Exporting and importing store files.
 
 Substitutes
@@ -185,6 +190,11 @@ Substitutes
 * Substitution Failure::        What happens when substitution fails.
 * On Trusting Binaries::        How can you trust that binary blob?
 
+Development
+
+* Invoking guix environment::   Setting up development environments.
+* Invoking guix pack::          Creating software bundles.
+
 Programming Interface
 
 * Package Modules::             Packages from the programmer's viewpoint.
@@ -212,7 +222,6 @@ Utilities
 * Invoking guix lint::          Finding errors in package definitions.
 * Invoking guix size::          Profiling disk usage.
 * Invoking guix graph::         Visualizing the graph of packages.
-* Invoking guix environment::   Setting up development environments.
 * Invoking guix publish::       Sharing substitutes.
 * Invoking guix challenge::     Challenging substitute servers.
 * Invoking guix copy::          Copying to and from a remote store.
@@ -242,7 +251,7 @@ System Configuration
 * Initial RAM Disk::            Linux-Libre bootstrapping.
 * Bootloader Configuration::    Configuring the boot loader.
 * Invoking guix system::        Instantiating a system configuration.
-* Running Guix in a VM::      How to run Guix System in a virtual machine.
+* Running Guix in a VM::        How to run Guix System in a virtual machine.
 * Defining Services::           Adding new service definitions.
 
 Services
@@ -309,12 +318,18 @@ group everything under the ``Guix'' banner since, after all, Guix System is
 readily available through the @command{guix system} command, even if you're
 using a different distro underneath!}.  @xref{GNU Distribution}.
 
+@menu
+* Managing Software the Guix Way::      What's special.
+* GNU Distribution::                    The packages and tools.
+@end menu
+
 @node Managing Software the Guix Way
 @section Managing Software the Guix Way
 
 @cindex user interfaces
 Guix provides a command-line package management interface
-(@pxref{Invoking guix package}), a set of command-line utilities
+(@pxref{Package Management}), tools to help with software development
+(@pxref{Development}), command-line utilities for more advanced usage,
 (@pxref{Utilities}), as well as Scheme programming interfaces
 (@pxref{Programming Interface}).
 @cindex build daemon
@@ -1762,7 +1777,7 @@ available.
 * USB Stick and DVD Installation::  Preparing the installation medium.
 * Preparing for Installation::  Networking, partitioning, etc.
 * Proceeding with the Installation::  The real thing.
-* Installing Guix in a VM::   Guix System playground.
+* Installing Guix in a VM::     Guix System playground.
 * Building the Installation Image::  How this comes to be.
 @end menu
 
@@ -2431,7 +2446,6 @@ guix package -i emacs-guix
 * Channels::                    Customizing the package collection.
 * Inferiors::                   Interacting with another revision of Guix.
 * Invoking guix describe::      Display information about your Guix revision.
-* Invoking guix pack::          Creating software bundles.
 * Invoking guix archive::       Exporting and importing store files.
 @end menu
 
@@ -4040,6 +4054,510 @@ produce a list of channel specifications in Recutils format.
 Display information about @var{profile}.
 @end table
 
+@node Invoking guix archive
+@section Invoking @command{guix archive}
+
+@cindex @command{guix archive}
+@cindex archive
+The @command{guix archive} command allows users to @dfn{export} files
+from the store into a single archive, and to later @dfn{import} them on
+a machine that runs Guix.
+In particular, it allows store files to be transferred from one machine
+to the store on another machine.
+
+@quotation Note
+If you're looking for a way to produce archives in a format suitable for
+tools other than Guix, @pxref{Invoking guix pack}.
+@end quotation
+
+@cindex exporting store items
+To export store files as an archive to standard output, run:
+
+@example
+guix archive --export @var{options} @var{specifications}...
+@end example
+
+@var{specifications} may be either store file names or package
+specifications, as for @command{guix package} (@pxref{Invoking guix
+package}).  For instance, the following command creates an archive
+containing the @code{gui} output of the @code{git} package and the main
+output of @code{emacs}:
+
+@example
+guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
+@end example
+
+If the specified packages are not built yet, @command{guix archive}
+automatically builds them.  The build process may be controlled with the
+common build options (@pxref{Common Build Options}).
+
+To transfer the @code{emacs} package to a machine connected over SSH,
+one would run:
+
+@example
+guix archive --export -r emacs | ssh the-machine guix archive --import
+@end example
+
+@noindent
+Similarly, a complete user profile may be transferred from one machine
+to another like this:
+
+@example
+guix archive --export -r $(readlink -f ~/.guix-profile) | \
+  ssh the-machine guix-archive --import
+@end example
+
+@noindent
+However, note that, in both examples, all of @code{emacs} and the
+profile as well as all of their dependencies are transferred (due to
+@code{-r}), regardless of what is already available in the store on the
+target machine.  The @code{--missing} option can help figure out which
+items are missing from the target store.  The @command{guix copy}
+command simplifies and optimizes this whole process, so this is probably
+what you should use in this case (@pxref{Invoking guix copy}).
+
+@cindex nar, archive format
+@cindex normalized archive (nar)
+Archives are stored in the ``normalized archive'' or ``nar'' format, which is
+comparable in spirit to `tar', but with differences
+that make it more appropriate for our purposes.  First, rather than
+recording all Unix metadata for each file, the nar format only mentions
+the file type (regular, directory, or symbolic link); Unix permissions
+and owner/group are dismissed.  Second, the order in which directory
+entries are stored always follows the order of file names according to
+the C locale collation order.  This makes archive production fully
+deterministic.
+
+When exporting, the daemon digitally signs the contents of the archive,
+and that digital signature is appended.  When importing, the daemon
+verifies the signature and rejects the import in case of an invalid
+signature or if the signing key is not authorized.
+@c FIXME: Add xref to daemon doc about signatures.
+
+The main options are:
+
+@table @code
+@item --export
+Export the specified store files or packages (see below.)  Write the
+resulting archive to the standard output.
+
+Dependencies are @emph{not} included in the output, unless
+@code{--recursive} is passed.
+
+@item -r
+@itemx --recursive
+When combined with @code{--export}, this instructs @command{guix
+archive} to include dependencies of the given items in the archive.
+Thus, the resulting archive is self-contained: it contains the closure
+of the exported store items.
+
+@item --import
+Read an archive from the standard input, and import the files listed
+therein into the store.  Abort if the archive has an invalid digital
+signature, or if it is signed by a public key not among the authorized
+keys (see @code{--authorize} below.)
+
+@item --missing
+Read a list of store file names from the standard input, one per line,
+and write on the standard output the subset of these files missing from
+the store.
+
+@item --generate-key[=@var{parameters}]
+@cindex signing, archives
+Generate a new key pair for the daemon.  This is a prerequisite before
+archives can be exported with @code{--export}.  Note that this operation
+usually takes time, because it needs to gather enough entropy to
+generate the key pair.
+
+The generated key pair is typically stored under @file{/etc/guix}, in
+@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
+key, which must be kept secret.)  When @var{parameters} is omitted,
+an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
+versions before 1.6.0, it is a 4096-bit RSA key.
+Alternatively, @var{parameters} can specify
+@code{genkey} parameters suitable for Libgcrypt (@pxref{General
+public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
+Libgcrypt Reference Manual}).
+
+@item --authorize
+@cindex authorizing, archives
+Authorize imports signed by the public key passed on standard input.
+The public key must be in ``s-expression advanced format''---i.e., the
+same format as the @file{signing-key.pub} file.
+
+The list of authorized keys is kept in the human-editable file
+@file{/etc/guix/acl}.  The file contains
+@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
+s-expressions''} and is structured as an access-control list in the
+@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
+(SPKI)}.
+
+@item --extract=@var{directory}
+@itemx -x @var{directory}
+Read a single-item archive as served by substitute servers
+(@pxref{Substitutes}) and extract it to @var{directory}.  This is a
+low-level operation needed in only very narrow use cases; see below.
+
+For example, the following command extracts the substitute for Emacs
+served by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}:
+
+@example
+$ wget -O - \
+  https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-emacs-24.5 \
+  | bunzip2 | guix archive -x /tmp/emacs
+@end example
+
+Single-item archives are different from multiple-item archives produced
+by @command{guix archive --export}; they contain a single store item,
+and they do @emph{not} embed a signature.  Thus this operation does
+@emph{no} signature verification and its output should be considered
+unsafe.
+
+The primary purpose of this operation is to facilitate inspection of
+archive contents coming from possibly untrusted substitute servers.
+
+@end table
+
+
+@c *********************************************************************
+@node Development
+@chapter Development
+
+@cindex software development
+If you are a software developer, Guix provides tools that you should find
+helpful---independently of the language you're developing in.  This is what
+this chapter is about.
+
+The @command{guix environment} command provides a convenient way to set up
+@dfn{development environments} containing all the dependencies and tools
+necessary to work on the software package of your choice.  The @command{guix
+pack} command allows you to create @dfn{application bundles} that can be
+easily distributed to users who do not run Guix.
+
+@menu
+* Invoking guix environment::   Setting up development environments.
+* Invoking guix pack::          Creating software bundles.
+@end menu
+
+@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 Guix System, 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.  @xref{Invoking guix
+gc}, for more on GC roots.
+
+@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 base system 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 --manifest=@var{file}
+@itemx -m @var{file}
+Create an environment for the packages contained in the manifest object
+returned by the Scheme code in @var{file}.
+
+This is similar to the same-named option in @command{guix package}
+(@pxref{profile-manifest, @option{--manifest}}) and uses the same
+manifest files.
+
+@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, unless overridden with @code{--user}, 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 --link-profile
+@itemx -P
+For containers, link the environment profile to
+@file{~/.guix-profile} within the container.  This is equivalent to
+running the command @command{ln -s $GUIX_ENVIRONMENT ~/.guix-profile}
+within the container.  Linking will fail and abort the environment if
+the directory already exists, which will certainly be the case if
+@command{guix environment} was invoked in the user's home directory.
+
+Certain packages are configured to look in
+@code{~/.guix-profile} for configuration files and data;@footnote{For
+example, the @code{fontconfig} package inspects
+@file{~/.guix-profile/share/fonts} for additional fonts.}
+@code{--link-profile} allows these programs to behave as expected within
+the environment.
+
+@item --user=@var{user}
+@itemx -u @var{user}
+For containers, use the username @var{user} in place of the current
+user.  The generated @file{/etc/passwd} entry within the container will
+contain the name @var{user}; the home directory will be
+@file{/home/USER}; and no user GECOS data will be copied.  @var{user}
+need not exist on the system.
+
+Additionally, any shared or exposed path (see @code{--share} and
+@code{--expose} respectively) whose target is within the current user's
+home directory will be remapped relative to @file{/home/USER}; this
+includes the automatic mapping of the current working directory.
+
+@example
+# will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
+cd $HOME/wd
+guix environment --container --user=foo \
+     --expose=$HOME/test \
+     --expose=/tmp/target=$HOME/target
+@end example
+
+While this will limit the leaking of user identity through home paths
+and each of the user fields, this is only one useful component of a
+broader privacy/anonymity solution---not one in and of itself.
+
+@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}) as well as package
+transformation options (@pxref{Package Transformation Options}).
+
 @node Invoking guix pack
 @section Invoking @command{guix pack}
 
@@ -4267,170 +4785,6 @@ In addition, @command{guix pack} supports all the common build options
 options (@pxref{Package Transformation Options}).
 
 
-@node Invoking guix archive
-@section Invoking @command{guix archive}
-
-@cindex @command{guix archive}
-@cindex archive
-The @command{guix archive} command allows users to @dfn{export} files
-from the store into a single archive, and to later @dfn{import} them on
-a machine that runs Guix.
-In particular, it allows store files to be transferred from one machine
-to the store on another machine.
-
-@quotation Note
-If you're looking for a way to produce archives in a format suitable for
-tools other than Guix, @pxref{Invoking guix pack}.
-@end quotation
-
-@cindex exporting store items
-To export store files as an archive to standard output, run:
-
-@example
-guix archive --export @var{options} @var{specifications}...
-@end example
-
-@var{specifications} may be either store file names or package
-specifications, as for @command{guix package} (@pxref{Invoking guix
-package}).  For instance, the following command creates an archive
-containing the @code{gui} output of the @code{git} package and the main
-output of @code{emacs}:
-
-@example
-guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
-@end example
-
-If the specified packages are not built yet, @command{guix archive}
-automatically builds them.  The build process may be controlled with the
-common build options (@pxref{Common Build Options}).
-
-To transfer the @code{emacs} package to a machine connected over SSH,
-one would run:
-
-@example
-guix archive --export -r emacs | ssh the-machine guix archive --import
-@end example
-
-@noindent
-Similarly, a complete user profile may be transferred from one machine
-to another like this:
-
-@example
-guix archive --export -r $(readlink -f ~/.guix-profile) | \
-  ssh the-machine guix-archive --import
-@end example
-
-@noindent
-However, note that, in both examples, all of @code{emacs} and the
-profile as well as all of their dependencies are transferred (due to
-@code{-r}), regardless of what is already available in the store on the
-target machine.  The @code{--missing} option can help figure out which
-items are missing from the target store.  The @command{guix copy}
-command simplifies and optimizes this whole process, so this is probably
-what you should use in this case (@pxref{Invoking guix copy}).
-
-@cindex nar, archive format
-@cindex normalized archive (nar)
-Archives are stored in the ``normalized archive'' or ``nar'' format, which is
-comparable in spirit to `tar', but with differences
-that make it more appropriate for our purposes.  First, rather than
-recording all Unix metadata for each file, the nar format only mentions
-the file type (regular, directory, or symbolic link); Unix permissions
-and owner/group are dismissed.  Second, the order in which directory
-entries are stored always follows the order of file names according to
-the C locale collation order.  This makes archive production fully
-deterministic.
-
-When exporting, the daemon digitally signs the contents of the archive,
-and that digital signature is appended.  When importing, the daemon
-verifies the signature and rejects the import in case of an invalid
-signature or if the signing key is not authorized.
-@c FIXME: Add xref to daemon doc about signatures.
-
-The main options are:
-
-@table @code
-@item --export
-Export the specified store files or packages (see below.)  Write the
-resulting archive to the standard output.
-
-Dependencies are @emph{not} included in the output, unless
-@code{--recursive} is passed.
-
-@item -r
-@itemx --recursive
-When combined with @code{--export}, this instructs @command{guix
-archive} to include dependencies of the given items in the archive.
-Thus, the resulting archive is self-contained: it contains the closure
-of the exported store items.
-
-@item --import
-Read an archive from the standard input, and import the files listed
-therein into the store.  Abort if the archive has an invalid digital
-signature, or if it is signed by a public key not among the authorized
-keys (see @code{--authorize} below.)
-
-@item --missing
-Read a list of store file names from the standard input, one per line,
-and write on the standard output the subset of these files missing from
-the store.
-
-@item --generate-key[=@var{parameters}]
-@cindex signing, archives
-Generate a new key pair for the daemon.  This is a prerequisite before
-archives can be exported with @code{--export}.  Note that this operation
-usually takes time, because it needs to gather enough entropy to
-generate the key pair.
-
-The generated key pair is typically stored under @file{/etc/guix}, in
-@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
-key, which must be kept secret.)  When @var{parameters} is omitted,
-an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
-versions before 1.6.0, it is a 4096-bit RSA key.
-Alternatively, @var{parameters} can specify
-@code{genkey} parameters suitable for Libgcrypt (@pxref{General
-public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
-Libgcrypt Reference Manual}).
-
-@item --authorize
-@cindex authorizing, archives
-Authorize imports signed by the public key passed on standard input.
-The public key must be in ``s-expression advanced format''---i.e., the
-same format as the @file{signing-key.pub} file.
-
-The list of authorized keys is kept in the human-editable file
-@file{/etc/guix/acl}.  The file contains
-@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
-s-expressions''} and is structured as an access-control list in the
-@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
-(SPKI)}.
-
-@item --extract=@var{directory}
-@itemx -x @var{directory}
-Read a single-item archive as served by substitute servers
-(@pxref{Substitutes}) and extract it to @var{directory}.  This is a
-low-level operation needed in only very narrow use cases; see below.
-
-For example, the following command extracts the substitute for Emacs
-served by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}:
-
-@example
-$ wget -O - \
-  https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-emacs-24.5 \
-  | bunzip2 | guix archive -x /tmp/emacs
-@end example
-
-Single-item archives are different from multiple-item archives produced
-by @command{guix archive --export}; they contain a single store item,
-and they do @emph{not} embed a signature.  Thus this operation does
-@emph{no} signature verification and its output should be considered
-unsafe.
-
-The primary purpose of this operation is to facilitate inspection of
-archive contents coming from possibly untrusted substitute servers.
-
-@end table
-
 @c *********************************************************************
 @node Programming Interface
 @chapter Programming Interface
@@ -6976,7 +7330,6 @@ the Scheme programming interface of Guix in a convenient way.
 * Invoking guix lint::          Finding errors in package definitions.
 * Invoking guix size::          Profiling disk usage.
 * Invoking guix graph::         Visualizing the graph of packages.
-* Invoking guix environment::   Setting up development environments.
 * Invoking guix publish::       Sharing substitutes.
 * Invoking guix challenge::     Challenging substitute servers.
 * Invoking guix copy::          Copying to and from a remote store.
@@ -8892,325 +9245,6 @@ are some architecture-dependent bits that this option allows you to visualize.
 @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 Guix System, 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.  @xref{Invoking guix
-gc}, for more on GC roots.
-
-@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 base system 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 --manifest=@var{file}
-@itemx -m @var{file}
-Create an environment for the packages contained in the manifest object
-returned by the Scheme code in @var{file}.
-
-This is similar to the same-named option in @command{guix package}
-(@pxref{profile-manifest, @option{--manifest}}) and uses the same
-manifest files.
-
-@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, unless overridden with @code{--user}, 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 --link-profile
-@itemx -P
-For containers, link the environment profile to
-@file{~/.guix-profile} within the container.  This is equivalent to
-running the command @command{ln -s $GUIX_ENVIRONMENT ~/.guix-profile}
-within the container.  Linking will fail and abort the environment if
-the directory already exists, which will certainly be the case if
-@command{guix environment} was invoked in the user's home directory.
-
-Certain packages are configured to look in
-@code{~/.guix-profile} for configuration files and data;@footnote{For
-example, the @code{fontconfig} package inspects
-@file{~/.guix-profile/share/fonts} for additional fonts.}
-@code{--link-profile} allows these programs to behave as expected within
-the environment.
-
-@item --user=@var{user}
-@itemx -u @var{user}
-For containers, use the username @var{user} in place of the current
-user.  The generated @file{/etc/passwd} entry within the container will
-contain the name @var{user}; the home directory will be
-@file{/home/USER}; and no user GECOS data will be copied.  @var{user}
-need not exist on the system.
-
-Additionally, any shared or exposed path (see @code{--share} and
-@code{--expose} respectively) whose target is within the current user's
-home directory will be remapped relative to @file{/home/USER}; this
-includes the automatic mapping of the current working directory.
-
-@example
-# will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
-cd $HOME/wd
-guix environment --container --user=foo \
-     --expose=$HOME/test \
-     --expose=/tmp/target=$HOME/target
-@end example
-
-While this will limit the leaking of user identity through home paths
-and each of the user fields, this is only one useful component of a
-broader privacy/anonymity solution---not one in and of itself.
-
-@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}) as well as package
-transformation options (@pxref{Package Transformation Options}).
-
 
 @node Invoking guix publish
 @section Invoking @command{guix publish}
@@ -9892,7 +9926,7 @@ instance to support new system services.
 * Initial RAM Disk::            Linux-Libre bootstrapping.
 * Bootloader Configuration::    Configuring the boot loader.
 * Invoking guix system::        Instantiating a system configuration.
-* Running Guix in a VM::      How to run Guix System in a virtual machine.
+* Running Guix in a VM::        How to run Guix System in a virtual machine.
 * Defining Services::           Adding new service definitions.
 @end menu