Browse Source

doc: Add 'guix environment' examples.

* doc/environment-gdb.scm: New file.
* (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'.
Ludovic Courtès 6 years ago
3 changed files with 45 additions and 4 deletions
  1. +2
  2. +13
  3. +30

+ 2
- 1 View File

@ -24,7 +24,8 @@ EXTRA_DIST += \
doc/fdl-1.3.texi \
doc/images/ \
doc/images/bootstrap-graph.eps \
doc/images/bootstrap-graph.pdf \
doc/os-config-bare-bones.texi \

+ 13
- 0
doc/environment-gdb.scm View File

@ -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))))

+ 30
- 3
doc/guix.texi View File

@ -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
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
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:
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}):
@verbatiminclude environment-gdb.scm
@end example
@item --exec=@var{command}
@item -E @var{command}
Execute @var{command} in the new environment.