From fe36d84eae08c485f4991f0e2ee0e53d55833f26 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= Date: Mon, 29 Jun 2015 22:25:43 +0200 Subject: [PATCH] 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(-) create mode 100644 doc/environment-gdb.scm 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.