01/01: doc: Add 'guix environment' examples.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit fe36d84eae08c485f4991f0e2ee0e53d55833f26
Author: Ludovic Courtès <address@hidden>
Date:   Mon Jun 29 22:25:43 2015 +0200

    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'.
---
 doc.am                  |    3 ++-
 doc/environment-gdb.scm |   13 +++++++++++++
 doc/guix.texi           |   33 ++++++++++++++++++++++++++++++---
 3 files changed, 45 insertions(+), 4 deletions(-)

diff --git a/doc.am b/doc.am
index 9d72b11..8a65b8d 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 0000000..040a863
--- /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 6164e08..ccccf7b 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
address@hidden 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} @address@hidden
 @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
address@hidden:
 
 @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 address@hidden and
+NumPy:
+
address@hidden
+guix environment --ad-hoc python2-numpy python-2.7 -E python
address@hidden example
+
+The available options are summarized below.
 
 @table @code
 @item address@hidden
 @itemx -e @var{expr}
 Create an environment for the package that @var{expr} evaluates to.
 
+For example, running:
+
address@hidden
+guix environment -e '(@@ (gnu packages maths) petsc-openmpi)'
address@hidden example
+
+starts a shell with the environment for this specific variant of the
+PETSc package.
+
 @item address@hidden
 @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}):
+
address@hidden
address@hidden environment-gdb.scm
address@hidden example
+
+
 @item address@hidden
 @item -E @var{command}
 Execute @var{command} in the new environment.