Next: Invoking guix publish, Previous: Invoking guix graph, Up: Utilities [Contents][Index]
guix environment
The purpose of guix environment
is to assist hackers in
creating reproducible development environments without polluting their
package profile. The 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:
guix environment options package…
The following example spawns a new shell set up for the development of GNU Guile:
guix environment guile
If the specified packages are not built yet, guix environment
automatically builds them. The new shell’s environment is an augmented
version of the environment that 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 --pure
option12.
guix environment
defines the GUIX_ENVIRONMENT
variable in the shell it spaws. This allows users to, say, define a
specific prompt for development environments in their .bashrc
(see Bash Startup Files in The GNU Bash Reference Manual):
if [ -n "$GUIX_ENVIRONMENT" ] then export PS1="\u@\h \w [dev]\$ " fi
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:
guix environment guile emacs
Sometimes an interactive shell session is not desired. An arbitrary
command may be invoked by placing the --
token to separate the
command from the rest of the arguments:
guix environment guile -- make -j4
In other situations, it is more convenient to specify the list of
packages needed in the environment. For example, the following command
runs python
from an environment containing Python 2.7 and
NumPy:
guix environment --ad-hoc python2-numpy python-2.7 -- python
Furthermore, one might want the dependencies of a package and also some
additional packages that are not build-time or runtime dependencies, but
are useful when developing nonetheless. Because of this, the
--ad-hoc
flag is positional. Packages appearing before
--ad-hoc
are interpreted as packages whose dependencies will be
added to the environment. Packages appearing after are interpreted as
packages that will be added to the environment directly. For example,
the following command creates a Guix development environment that
additionally includes Git and strace:
guix environment guix --ad-hoc git strace
Sometimes it is desirable to isolate the environment as much as possible, for maximal purity and reproducibility. In particular, when using Guix on a host distro that is not GuixSD, it is desirable to prevent access to /usr/bin and other system-wide resources from the development environment. For example, the following command spawns a Guile REPL in a “container” where only the store and the current working directory are mounted:
guix environment --ad-hoc --container guile -- guile
Note: The
--container
option requires Linux-libre 3.19 or newer.
The available options are summarized below.
--expression=expr
-e expr
Create an environment for the package or list of packages that expr evaluates to.
For example, running:
guix environment -e '(@ (gnu packages maths) petsc-openmpi)'
starts a shell with the environment for this specific variant of the PETSc package.
Running:
guix environment --ad-hoc -e '(@ (gnu) %base-packages)'
starts a shell with all the GuixSD base packages available.
--load=file
-l file
Create an environment for the package or list of packages that the code within file evaluates to.
As an example, file might contain a definition like this (see Defining Packages):
(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))))
--ad-hoc
Include all specified packages in the resulting environment, as if an ad hoc package were defined with them as inputs. This option is useful for quickly creating an environment without having to write a package expression to contain the desired inputs.
For instance, the command:
guix environment --ad-hoc guile guile-sdl -- guile
runs guile
in an environment where Guile and Guile-SDL are
available.
Note that this example implicitly asks for the default output of
guile
and guile-sdl
but it is possible to ask for a
specific output—e.g., glib:bin
asks for the bin
output
of glib
(see Packages with Multiple Outputs).
This option may be composed with the default behavior of guix
environment
. Packages appearing before --ad-hoc
are interpreted
as packages whose dependencies will be added to the environment, the
default behavior. Packages appearing after are interpreted as packages
that will be added to the environment directly.
--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.
--search-paths
Display the environment variable definitions that make up the environment.
--system=system
-s system
Attempt to build for system—e.g., i686-linux
.
--container
-C
Run command within an isolated container. The current working directory outside the container is mapped to /env inside the container. Additionally, the spawned process runs as the current user outside the container, but has root privileges in the context of the container.
--network
-N
For containers, share the network namespace with the host system. Containers created without this flag only have access to the loopback device.
--expose=source[=target]
For containers, expose the file system source from the host system as the read-only file system target within the container. If target is not specified, source is used as the target mount point in the container.
The example below spawns a Guile REPL in a container in which the user’s home directory is accessible read-only via the /exchange directory:
guix environment --container --expose=$HOME=/exchange guile -- guile
--share=source[=target]
For containers, share the file system source from the host system as the writable file system target within the container. If target is not specified, source is used as the target mount point in the container.
The example below spawns a Guile REPL in a container in which the user’s home directory is accessible for both reading and writing via the /exchange directory:
guix environment --container --share=$HOME=/exchange guile -- guile
It also supports all of the common build options that guix
build
supports (see common build options).
Users sometimes wrongfully augment
environment variables such as PATH
in their ~/.bashrc
file. As a consequence, when guix environment
launches it, Bash
may read ~/.bashrc, thereby introducing “impurities” in these
environment variables. It is an error to define such environment
variables in .bashrc; instead, they should be defined in
.bash_profile, which is sourced only by log-in shells.
See Bash Startup Files in The GNU Bash Reference Manual, for
details on Bash start-up files.
Next: Invoking guix publish, Previous: Invoking guix graph, Up: Utilities [Contents][Index]