about summary refs log tree commit diff
path: root/doc/manual
diff options
context:
space:
mode:
authorVladimír Čunát <vcunat@gmail.com>2015-09-29T16·21+0200
committerVladimír Čunát <vcunat@gmail.com>2015-11-10T21·32+0100
commitb39622a487e2978bd32c9faf2f651aec1f9815c1 (patch)
tree9f7c754848efabd7bd7dc0c230d369bfd0af0606 /doc/manual
parentaaf8a1c16bb8de4045d8aae4fea8ac8a1bef2c34 (diff)
rename `chroot` to `sandbox` (fixes #656, close #682)
- rename options but leav old names as lower-priority aliases,
  also "-dirs" -> "-paths" to get closer to the meaning
- update docs to reflect the new names (old aliases are not documented),
  including a new file with release notes
- tests need an update after corresponding changes to nixpkgs
- __noChroot is left as it is (after discussion on the PR)
Diffstat (limited to 'doc/manual')
-rw-r--r--doc/manual/command-ref/conf-file.xml44
-rw-r--r--doc/manual/release-notes/release-notes.xml1
-rw-r--r--doc/manual/release-notes/rl-1.11.xml23
3 files changed, 47 insertions, 21 deletions
diff --git a/doc/manual/command-ref/conf-file.xml b/doc/manual/command-ref/conf-file.xml
index c947d19fa0e1..a23223818ea5 100644
--- a/doc/manual/command-ref/conf-file.xml
+++ b/doc/manual/command-ref/conf-file.xml
@@ -224,16 +224,16 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
   </varlistentry>
 
 
-  <varlistentry><term><literal>build-use-chroot</literal></term>
+  <varlistentry><term><literal>build-use-sandbox</literal></term>
 
     <listitem><para>If set to <literal>true</literal>, builds will be
-    performed in a <emphasis>chroot environment</emphasis>, i.e.,
+    performed in a <emphasis>sandboxed environment</emphasis>, i.e.,
     they’re isolated from the normal file system hierarchy and will
     only see their dependencies in the Nix store, the temporary build
     directory, private versions of <filename>/proc</filename>,
     <filename>/dev</filename>, <filename>/dev/shm</filename> and
-    <filename>/dev/pts</filename>, and the paths configured with the
-    <link linkend='conf-build-chroot-dirs'><literal>build-chroot-dirs</literal>
+    <filename>/dev/pts</filename> (on Linux), and the paths configured with the
+    <link linkend='conf-build-sandbox-paths'><literal>build-sandbox-paths</literal>
     option</link>. This is useful to prevent undeclared dependencies
     on files in directories such as <filename>/usr/bin</filename>. In
     addition, on Linux, builds run in private PID, mount, network, IPC
@@ -241,8 +241,8 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
     system (except that fixed-output derivations do not run in private
     network namespace to ensure they can access the network).</para>
 
-    <para>Currently, chroots only work on Linux and Mac OS X. The use
-    of a chroot requires that Nix is run as root (so you should use
+    <para>Currently, sandboxing only work on Linux and Mac OS X. The use
+    of a sandbox requires that Nix is run as root (so you should use
     the <link linkend='conf-build-users-group'>“build users”
     feature</link> to perform the actual builds under different users
     than root).</para>
@@ -250,7 +250,7 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
     <para>If this option is set to <literal>relaxed</literal>, then
     fixed-output derivations and derivations that have the
     <varname>__noChroot</varname> attribute set to
-    <literal>true</literal> do not run in chroots.</para>
+    <literal>true</literal> do not run in sandboxes.</para>
 
     <para>The default is <literal>false</literal>.</para>
 
@@ -259,17 +259,16 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
   </varlistentry>
 
 
-  <varlistentry xml:id="conf-build-chroot-dirs"><term><literal>build-chroot-dirs</literal></term>
+  <varlistentry xml:id="conf-build-sandbox-paths">
+    <term><literal>build-sandbox-paths</literal></term>
 
-    <listitem><para>A list of paths bind-mounted into Nix chroot
-    environments.  Contrary to what the name suggests, the specified
-    paths do not have to be directories; you can bind-mount other
-    types of files as well.  You can use the syntax
+    <listitem><para>A list of paths bind-mounted into Nix sandbox
+    environments. You can use the syntax
     <literal><replaceable>target</replaceable>=<replaceable>source</replaceable></literal>
-    to mount a path in a different location in the chroot; for
+    to mount a path in a different location in the sandbox; for
     instance, <literal>/bin=/nix-bin</literal> will mount the path
     <literal>/nix-bin</literal> as <literal>/bin</literal> inside the
-    chroot.</para>
+    sandbox.</para>
 
     <para>Depending on how Nix was built, the default value for this option
     may be empty or provide <filename>/bin/sh</filename> as a
@@ -278,10 +277,11 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
   </varlistentry>
 
 
-  <varlistentry xml:id="conf-build-extra-chroot-dirs"><term><literal>build-extra-chroot-dirs</literal></term>
+  <varlistentry xml:id="conf-build-extra-sandbox-paths">
+    <term><literal>build-extra-sandbox-paths</literal></term>
 
     <listitem><para>A list of additional paths appended to
-    <option>build-chroot-dirs</option>. Useful if you want to extend
+    <option>build-sandbox-paths</option>. Useful if you want to extend
     its default value.</para></listitem>
 
   </varlistentry>
@@ -593,19 +593,21 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
       between different versions of the same system to be hard-coded into nix.
       </para>
 
-      <para>The hook is passed the derivation path and, if chroots are enabled,
-      the chroot directory. It can then modify the chroot and send a series of
+      <para>The hook is passed the derivation path and, if sandboxes are enabled,
+      the sandbox directory. It can then modify the sandbox and send a series of
       commands to modify various settings to stdout. The currently recognized
       commands are:</para>
 
       <variablelist>
-        <varlistentry xml:id="extra-chroot-dirs"><term><literal>extra-chroot-dirs</literal></term>
+        <varlistentry xml:id="extra-sandbox-paths">
+          <term><literal>extra-sandbox-paths</literal></term>
 
           <listitem>
 
             <para>Pass a list of files and directories to be included in the
-            chroot for this build. One entry per line, terminated by an empty
-            line. Entries have the same format as build-chroot-dirs.</para>
+            sandbox for this build. One entry per line, terminated by an empty
+            line. Entries have the same format as
+            <literal>build-sandbox-paths</literal>.</para>
 
           </listitem>
 
diff --git a/doc/manual/release-notes/release-notes.xml b/doc/manual/release-notes/release-notes.xml
index 4ea57c99c3a4..0aa3e8717aa1 100644
--- a/doc/manual/release-notes/release-notes.xml
+++ b/doc/manual/release-notes/release-notes.xml
@@ -12,6 +12,7 @@
 </partintro>
 -->
 
+<xi:include href="rl-1.11.xml" />
 <xi:include href="rl-1.10.xml" />
 <xi:include href="rl-1.9.xml" />
 <xi:include href="rl-1.8.xml" />
diff --git a/doc/manual/release-notes/rl-1.11.xml b/doc/manual/release-notes/rl-1.11.xml
new file mode 100644
index 000000000000..aa9a3e101835
--- /dev/null
+++ b/doc/manual/release-notes/rl-1.11.xml
@@ -0,0 +1,23 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="ssec-relnotes-1.11">
+
+<title>Release 1.11 (TODO: date, 2015)</title>
+
+<para>TODO: This is primarily a bug fix release. It also has a number of new
+features:</para>
+
+<itemizedlist>
+  <listitem>
+    <para>All "chroot"-containing strings got renamed to "sandbox".
+      In particular, some nix options got renamed, but the old names
+      are still accepted as lower-priority aliases.
+    </para>
+  </listitem>
+</itemizedlist>
+
+<para>This release has contributions from TODO.</para>
+
+</section>