summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorDavid Thompson <davet@gnu.org>2015-06-19 08:57:44 -0400
committerDavid Thompson <dthompson2@worcester.edu>2015-10-25 20:27:19 -0400
commitf535dcbe198e7f88f3b0cd8aa4d7585191b31080 (patch)
treeecc716aed8764e046fd3ff4b0ccf297686d3df0e /doc
parent581176c00b424ea6ddbeec38ba5dfaea43b53bcc (diff)
scripts: environment: Add --container option.
* guix/scripts/system.scm (specification->file-system-mapping): Move from here... * guix/ui.scm (specification->file-system-mapping): ... to here. * guix/scripts/enviroment.scm (show-help): Show help for new options. (%options): Add --container --network, --expose, and --share options. (%network-configuration-files): New variable. (launch-environment, launch-environment/container, requisites*, inputs->requisites): New procedures. (guix-environment): Spawn new process in a container when requested. * doc/guix.texi (Invoking guix environment): Document it. * tests/guix-environment-container.sh: New file. * Makefile.am (SH_TESTS): Add it.
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi56
1 files changed, 56 insertions, 0 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index 99c10d8dc7..7715b72818 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4681,6 +4681,18 @@ NumPy:
guix environment --ad-hoc python2-numpy python-2.7 -- python
@end example
+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 @file{/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:
+
+@example
+guix environment --ad-hoc --container guile -- guile
+@end example
+
The available options are summarized below.
@table @code
@@ -4741,6 +4753,49 @@ environment.
@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system}---e.g., @code{i686-linux}.
+
+@item --container
+@itemx -C
+@cindex container
+Run @var{command} within an isolated container. The current working
+directory outside the container is mapped to @file{/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.
+
+@item --network
+@itemx -N
+For containers, share the network namespace with the host system.
+Containers created without this flag only have access to the loopback
+device.
+
+@item --expose=@var{source}[=@var{target}]
+For containers, expose the file system @var{source} from the host system
+as the read-only file system @var{target} within the container. If
+@var{target} is not specified, @var{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 @file{/exchange}
+directory:
+
+@example
+guix environment --container --expose=$HOME=/exchange guile -- guile
+@end example
+
+@item --share
+For containers, share the file system @var{source} from the host system
+as the writable file system @var{target} within the container. If
+@var{target} is not specified, @var{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
+@file{/exchange} directory:
+
+@example
+guix environment --container --share=$HOME=/exchange guile -- guile
+@end example
@end table
It also supports all of the common build options that @command{guix
@@ -7064,6 +7119,7 @@ This command also installs GRUB on the device specified in
@item vm
@cindex virtual machine
@cindex VM
+@anchor{guix system vm}
Build a virtual machine that contain the operating system declared in
@var{file}, and return a script to run that virtual machine (VM).
Arguments given to the script are passed as is to QEMU.