aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorDavid Thompson <dthompson2@worcester.edu>2014-09-21 13:40:05 -0400
committerDavid Thompson <dthompson2@worcester.edu>2014-10-10 18:14:40 -0400
commit372c4bbcbb279450043e6e55e419808467df228a (patch)
tree2f3460f5a2c7189c58d1078b4b13631bd2c6ec84 /doc
parente25234e34b0d2709e8ff06609cedce2b24b50ee8 (diff)
downloadguix-372c4bbcbb279450043e6e55e419808467df228a.tar
guix-372c4bbcbb279450043e6e55e419808467df228a.tar.gz
scripts: Add 'environment' command.
* guix/scripts/environment.scm: New file. * Makefile.am (MODULES): Add it. * doc/guix.texi ("Invoking guix environment"): New node.
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi82
1 files changed, 82 insertions, 0 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index 52b9d607ee..13bcd103ca 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -33,6 +33,12 @@ Documentation License''.
Managing the operating system configuration.
@end direntry
+@dircategory Software development
+@direntry
+* guix environment: (guix)Invoking guix environment
+ Building development environments with Guix.
+@end direntry
+
@titlepage
@title GNU Guix Reference Manual
@subtitle Using the GNU Guix Functional Package Manager
@@ -2431,6 +2437,7 @@ programming interface of Guix in a convenient way.
* Invoking guix hash:: Computing the cryptographic hash of a file.
* Invoking guix refresh:: Updating package definitions.
* Invoking guix lint:: Finding errors in package definitions.
+* Invoking guix environment:: Setting up development environments.
@end menu
@node Invoking guix build
@@ -2840,6 +2847,81 @@ and exit.
@end table
+@node Invoking guix environment
+@section Invoking @command{guix 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 the necessary 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 examples spawns a new shell that is capable of building
+the GNU Guile source code:
+
+@example
+guix environment guile
+@end example
+
+If the specified packages are not built yet, @command{guix environment}
+automatically builds them. The new shell's environment 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.
+
+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. The
+@code{--exec} option can be used to specify the command to run instead.
+
+@example
+guix environment guile --exec=make
+@end example
+
+The following options are available:
+
+@table @code
+@item --expression=@var{expr}
+@itemx -e @var{expr}
+Create an environment for the package that @var{expr} evaluates to.
+
+@item --load=@var{file}
+@itemx -l @var{file}
+Create an environment for the package that the code within @var{file}
+evaluates to.
+
+@item --exec=@var{command}
+@item -E @var{command}
+Execute @var{command} in the new environment.
+
+@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.
+@end table
+
+It also supports all of the common build options that @command{guix
+build} supports (@pxref{Invoking guix build, common build options}).
+
@c *********************************************************************
@node GNU Distribution
@chapter GNU Distribution