summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2015-06-29 22:25:43 +0200
committerLudovic Courtès <ludo@gnu.org>2015-06-29 23:08:36 +0200
commitfe36d84eae08c485f4991f0e2ee0e53d55833f26 (patch)
treeac632b01cb9f74b091b6424e93890f5bcd8645eb
parent257341086549ed8a02ea35d50593696127f1eed5 (diff)
doc: Add 'guix environment' examples.
* doc/environment-gdb.scm: New file. * doc.am (EXTRA_DIST): Add it. * doc/guix.texi (Invoking guix environment): Clarify wording of the first example. Add a --ad-hoc example upfront. Add an example for '-e', and one for '-l'.
-rw-r--r--doc.am3
-rw-r--r--doc/environment-gdb.scm13
-rw-r--r--doc/guix.texi33
3 files changed, 45 insertions, 4 deletions
diff --git a/doc.am b/doc.am
index 9d72b11caa..8a65b8d90d 100644
--- a/doc.am
+++ b/doc.am
@@ -24,7 +24,8 @@ EXTRA_DIST += \
doc/fdl-1.3.texi \
doc/images/bootstrap-graph.dot \
doc/images/bootstrap-graph.eps \
- doc/images/bootstrap-graph.pdf
+ doc/images/bootstrap-graph.pdf \
+ doc/environment-gdb.scm
OS_CONFIG_EXAMPLES_TEXI = \
doc/os-config-bare-bones.texi \
diff --git a/doc/environment-gdb.scm b/doc/environment-gdb.scm
new file mode 100644
index 0000000000..040a8637f8
--- /dev/null
+++ b/doc/environment-gdb.scm
@@ -0,0 +1,13 @@
+(use-modules (guix)
+ (gnu packages gdb)
+ (gnu packages autotools)
+ (gnu packages texinfo))
+
+;; Augment the package definition of GDB with the build tools
+;; needed when developing GDB (and which are not needed when
+;; simply installing it.)
+(package (inherit gdb)
+ (native-inputs `(("autoconf" ,autoconf-2.64)
+ ("automake" ,automake)
+ ("texinfo" ,texinfo)
+ ,@(package-native-inputs gdb))))
diff --git a/doc/guix.texi b/doc/guix.texi
index 6164e086a3..ccccf7b347 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4110,6 +4110,7 @@ Consider packages for @var{system}---e.g., @code{x86_64-linux}.
@section Invoking @command{guix environment}
@cindex reproducible build environments
+@cindex development environments
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
@@ -4122,8 +4123,8 @@ The general syntax is:
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:
+The following example spawns a new shell set up for the development of
+GNU@tie{}Guile:
@example
guix environment guile
@@ -4153,18 +4154,44 @@ Sometimes an interactive shell session is not desired. The
guix environment guile --exec=make
@end example
-The following options are available:
+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 -E python
+@end example
+
+The available options are summarized below.
@table @code
@item --expression=@var{expr}
@itemx -e @var{expr}
Create an environment for the package 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.
+
@item --load=@var{file}
@itemx -l @var{file}
Create an environment for the package 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 --exec=@var{command}
@item -E @var{command}
Execute @var{command} in the new environment.