Bump version

manual: add XML IDs to all builtin list entries
(cherry picked from commit 05cfc71cab)
2018-10-02 17:04:33 +02:00 · 2018-10-02 17:04:06 +02:00 · 2018-10-01 22:51:23 +02:00 · 2018-10-01 22:49:46 +02:00 · 2018-10-01 22:49:06 +02:00 · 2018-10-01 22:48:53 +02:00
43 changed files with 1096 additions and 418 deletions
--- a/configure.ac
+++ b/configure.ac
@@ -152,9 +152,9 @@ PKG_CHECK_MODULES([OPENSSL], [libcrypto], [CXXFLAGS="$OPENSSL_CFLAGS $CXXFLAGS"]

 # Look for libbz2, a required dependency.
 AC_CHECK_LIB([bz2], [BZ2_bzWriteOpen], [true],
-  [AC_MSG_ERROR([Nix requires libbz2, which is part of bzip2.  See http://www.bzip.org/.])])
+  [AC_MSG_ERROR([Nix requires libbz2, which is part of bzip2.  See https://web.archive.org/web/20180624184756/http://www.bzip.org/.])])
 AC_CHECK_HEADERS([bzlib.h], [true],
-  [AC_MSG_ERROR([Nix requires libbz2, which is part of bzip2.  See http://www.bzip.org/.])])
+  [AC_MSG_ERROR([Nix requires libbz2, which is part of bzip2.  See https://web.archive.org/web/20180624184756/http://www.bzip.org/.])])


 # Look for SQLite, a required dependency.
@@ -229,12 +229,6 @@ if test "$gc" = yes; then
 fi


-AC_ARG_ENABLE(init-state, AC_HELP_STRING([--disable-init-state],
-  [do not initialise DB etc. in `make install']),
-  init_state=$enableval, init_state=yes)
-#AM_CONDITIONAL(INIT_STATE, test "$init_state" = "yes")
-
-
 # documentation generation switch
 AC_ARG_ENABLE(doc-gen, AC_HELP_STRING([--disable-doc-gen],
  [disable documentation generation]),
--- a/doc/manual/advanced-topics/advanced-topics.xml
+++ b/doc/manual/advanced-topics/advanced-topics.xml
@@ -1,6 +1,7 @@
 <part xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
+      xml:id="part-advanced-topics"
      version="5.0">

 <title>Advanced Topics</title>
--- a/doc/manual/advanced-topics/distributed-builds.xml
+++ b/doc/manual/advanced-topics/distributed-builds.xml
@@ -81,6 +81,7 @@ or a newline, e.g.

 <para>Each machine specification consists of the following elements,
 separated by spaces. Only the first element is required.
+To leave a field at its default, set it to <literal>-</literal>.

 <orderedlist>

--- a/doc/manual/command-ref/conf-file.xml
+++ b/doc/manual/command-ref/conf-file.xml
@@ -135,7 +135,6 @@ false</literal>.</para>

  </varlistentry>

-
  <varlistentry xml:id="conf-builders">
    <term><literal>builders</literal></term>
    <listitem>
@@ -159,7 +158,6 @@ false</literal>.</para>

  </varlistentry>

-
  <varlistentry xml:id="conf-build-users-group"><term><literal>build-users-group</literal></term>

    <listitem><para>This options specifies the Unix group containing
@@ -210,7 +208,6 @@ false</literal>.</para>

  </varlistentry>

-
  <varlistentry xml:id="conf-connect-timeout"><term><literal>connect-timeout</literal></term>

    <listitem>
@@ -243,7 +240,6 @@ false</literal>.</para>

  </varlistentry>

-
  <varlistentry xml:id="conf-extra-sandbox-paths">
    <term><literal>extra-sandbox-paths</literal></term>

@@ -283,7 +279,6 @@ false</literal>.</para>

  </varlistentry>

-
  <varlistentry xml:id="conf-fallback"><term><literal>fallback</literal></term>

    <listitem><para>If set to <literal>true</literal>, Nix will fall
@@ -293,7 +288,6 @@ false</literal>.</para>

  </varlistentry>

-
  <varlistentry xml:id="conf-fsync-metadata"><term><literal>fsync-metadata</literal></term>

    <listitem><para>If set to <literal>true</literal>, changes to the
@@ -304,7 +298,6 @@ false</literal>.</para>

  </varlistentry>

-
  <varlistentry xml:id="conf-hashed-mirrors"><term><literal>hashed-mirrors</literal></term>

    <listitem><para>A list of web servers used by
@@ -367,10 +360,8 @@ builtins.fetchurl {
    options a store path was built), so by default this option is on.
    Turn it off to save a bit of disk space (or a lot if
    <literal>keep-outputs</literal> is also turned on).</para></listitem>
-
  </varlistentry>

-
  <varlistentry xml:id="conf-keep-env-derivations"><term><literal>keep-env-derivations</literal></term>

    <listitem><para>If <literal>false</literal> (default), derivations
@@ -394,7 +385,6 @@ builtins.fetchurl {

  </varlistentry>

-
  <varlistentry xml:id="conf-keep-outputs"><term><literal>keep-outputs</literal></term>

    <listitem><para>If <literal>true</literal>, the garbage collector
@@ -408,10 +398,8 @@ builtins.fetchurl {
    only at build time (e.g., the C compiler, or source tarballs
    downloaded from the network).  To prevent it from doing so, set
    this option to <literal>true</literal>.</para></listitem>
-
  </varlistentry>

-
  <varlistentry xml:id="conf-max-build-log-size"><term><literal>max-build-log-size</literal></term>

    <listitem>
@@ -441,10 +429,8 @@ builtins.fetchurl {
    overridden using the <option
    linkend='opt-max-jobs'>--max-jobs</option> (<option>-j</option>)
    command line switch.</para></listitem>
-
  </varlistentry>

-
  <varlistentry xml:id="conf-max-silent-time"><term><literal>max-silent-time</literal></term>

    <listitem>
@@ -524,7 +510,12 @@ password <replaceable>my-password</replaceable>

    For the exact syntax, see <link
    xlink:href="https://ec.haxx.se/usingcurl-netrc.html">the
-    <literal>curl</literal> documentation.</link></para></listitem>
+    <literal>curl</literal> documentation.</link></para>
+
+    <note><para>This must be an absolute path, and <literal>~</literal>
+    is not resolved. For example, <filename>~/.netrc</filename> won't
+    resolve to your home directory's <filename>.netrc</filename>.</para></note>
+    </listitem>

  </varlistentry>

@@ -595,7 +586,6 @@ password <replaceable>my-password</replaceable>

  </varlistentry>

-
  <varlistentry xml:id="conf-repeat"><term><literal>repeat</literal></term>

    <listitem><para>How many times to repeat builds to check whether
@@ -607,7 +597,6 @@ password <replaceable>my-password</replaceable>

  </varlistentry>

-
  <varlistentry xml:id="conf-require-sigs"><term><literal>require-sigs</literal></term>

    <listitem><para>If set to <literal>true</literal> (the default),
@@ -671,7 +660,6 @@ password <replaceable>my-password</replaceable>

  </varlistentry>

-
  <varlistentry xml:id="conf-sandbox-dev-shm-size"><term><literal>sandbox-dev-shm-size</literal></term>

    <listitem><para>This option determines the maximum size of the
@@ -737,7 +725,6 @@ password <replaceable>my-password</replaceable>

  </varlistentry>

-
  <varlistentry xml:id="conf-substituters"><term><literal>substituters</literal></term>

    <listitem><para>A list of URLs of substituters, separated by
@@ -746,7 +733,6 @@ password <replaceable>my-password</replaceable>

  </varlistentry>

-
  <varlistentry xml:id="conf-system"><term><literal>system</literal></term>

    <listitem><para>This option specifies the canonical Nix system
@@ -787,7 +773,6 @@ password <replaceable>my-password</replaceable>

  </varlistentry>

-
  <varlistentry xml:id="conf-trusted-public-keys"><term><literal>trusted-public-keys</literal></term>

    <listitem><para>A whitespace-separated list of public keys. When
@@ -798,7 +783,6 @@ password <replaceable>my-password</replaceable>

  </varlistentry>

-
  <varlistentry xml:id="conf-trusted-substituters"><term><literal>trusted-substituters</literal></term>

    <listitem><para>A list of URLs of substituters, separated by
@@ -811,7 +795,6 @@ password <replaceable>my-password</replaceable>

  </varlistentry>

-
  <varlistentry xml:id="conf-trusted-users"><term><literal>trusted-users</literal></term>

    <listitem>
@@ -837,9 +820,178 @@ password <replaceable>my-password</replaceable>
  </varlistentry>

 </variablelist>
-
 </para>

+<refsection>
+  <title>Deprecated Settings</title>
+
+<para>
+
+<variablelist>
+
+  <varlistentry xml:id="conf-binary-caches">
+    <term><literal>binary-caches</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>binary-caches</literal> is now an alias to
+    <xref linkend="conf-substituters" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-binary-cache-public-keys">
+    <term><literal>binary-cache-public-keys</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>binary-cache-public-keys</literal> is now an alias to
+    <xref linkend="conf-trusted-public-keys" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-build-compress-log">
+    <term><literal>build-compress-log</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>build-compress-log</literal> is now an alias to
+    <xref linkend="conf-compress-build-log" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-build-cores">
+    <term><literal>build-cores</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>build-cores</literal> is now an alias to
+    <xref linkend="conf-cores" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-build-extra-chroot-dirs">
+    <term><literal>build-extra-chroot-dirs</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>build-extra-chroot-dirs</literal> is now an alias to
+    <xref linkend="conf-extra-sandbox-paths" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-build-extra-sandbox-paths">
+    <term><literal>build-extra-sandbox-paths</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>build-extra-sandbox-paths</literal> is now an alias to
+    <xref linkend="conf-extra-sandbox-paths" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-build-fallback">
+    <term><literal>build-fallback</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>build-fallback</literal> is now an alias to
+    <xref linkend="conf-fallback" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-build-max-jobs">
+    <term><literal>build-max-jobs</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>build-max-jobs</literal> is now an alias to
+    <xref linkend="conf-max-jobs" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-build-max-log-size">
+    <term><literal>build-max-log-size</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>build-max-log-size</literal> is now an alias to
+    <xref linkend="conf-max-build-log-size" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-build-max-silent-time">
+    <term><literal>build-max-silent-time</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>build-max-silent-time</literal> is now an alias to
+    <xref linkend="conf-max-silent-time" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-build-repeat">
+    <term><literal>build-repeat</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>build-repeat</literal> is now an alias to
+    <xref linkend="conf-repeat" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-build-timeout">
+    <term><literal>build-timeout</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>build-timeout</literal> is now an alias to
+    <xref linkend="conf-timeout" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-build-use-chroot">
+    <term><literal>build-use-chroot</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>build-use-chroot</literal> is now an alias to
+    <xref linkend="conf-sandbox" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-build-use-sandbox">
+    <term><literal>build-use-sandbox</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>build-use-sandbox</literal> is now an alias to
+    <xref linkend="conf-sandbox" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-build-use-substitutes">
+    <term><literal>build-use-substitutes</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>build-use-substitutes</literal> is now an alias to
+    <xref linkend="conf-substitute" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-gc-keep-derivations">
+    <term><literal>gc-keep-derivations</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>gc-keep-derivations</literal> is now an alias to
+    <xref linkend="conf-keep-derivations" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-gc-keep-outputs">
+    <term><literal>gc-keep-outputs</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>gc-keep-outputs</literal> is now an alias to
+    <xref linkend="conf-keep-outputs" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-env-keep-derivations">
+    <term><literal>env-keep-derivations</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>env-keep-derivations</literal> is now an alias to
+    <xref linkend="conf-keep-env-derivations" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-extra-binary-caches">
+    <term><literal>extra-binary-caches</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>extra-binary-caches</literal> is now an alias to
+    <xref linkend="conf-extra-substituters" />.</para></listitem>
+  </varlistentry>
+
+  <varlistentry xml:id="conf-trusted-binary-caches">
+    <term><literal>trusted-binary-caches</literal></term>
+
+    <listitem><para><emphasis>Deprecated:</emphasis>
+    <literal>trusted-binary-caches</literal> is now an alias to
+    <xref linkend="conf-trusted-substituters" />.</para></listitem>
+  </varlistentry>
+</variablelist>
+</para>
+</refsection>
+
 </refsection>

 </refentry>
--- a/doc/manual/command-ref/nix-shell.xml
+++ b/doc/manual/command-ref/nix-shell.xml
@@ -317,13 +317,28 @@ while (my $token = $p->get_tag("a")) {

 </para>

-<para>Finally, the following Haskell script uses a specific branch of
-Nixpkgs/NixOS (the 14.12 stable branch):
+<para>Sometimes you need to pass a simple Nix expression to customize
+a package like Terraform:
+
+<programlisting><![CDATA[
+#! /usr/bin/env nix-shell
+#! nix-shell -i bash -p "terraform.withPlugins (plugins: [ plugins.openstack ])"
+
+terraform apply
+]]></programlisting>
+
+<note><para>You must use double quotes (<literal>"</literal>) when
+passing a simple Nix expression in a nix-shell shebang.</para></note>
+</para>
+
+<para>Finally, using the merging of multiple nix-shell shebangs the
+following Haskell script uses a specific branch of Nixpkgs/NixOS (the
+18.03 stable branch):

 <programlisting><![CDATA[
 #! /usr/bin/env nix-shell
 #! nix-shell -i runghc -p haskellPackages.ghc haskellPackages.HTTP haskellPackages.tagsoup
-#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz
+#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-18.03.tar.gz

 import Network.HTTP
 import Text.HTML.TagSoup
--- a/doc/manual/expressions/advanced-attributes.xml
+++ b/doc/manual/expressions/advanced-attributes.xml
@@ -50,6 +50,40 @@ allowedRequisites = [ foobar ];

  </varlistentry>

+  <varlistentry><term><varname>disallowedReferences</varname></term>
+
+    <listitem><para>The optional attribute
+    <varname>disallowedReferences</varname> specifies a list of illegal
+    references (dependencies) of the output of the builder.  For
+    example,
+
+<programlisting>
+disallowedReferences = [ foo ];
+</programlisting>
+
+    enforces that the output of a derivation cannot have a direct runtime
+    dependencies on the derivation <varname>foo</varname>.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><varname>disallowedRequisites</varname></term>
+
+    <listitem><para>This attribute is similar to
+    <varname>disallowedReferences</varname>, but it specifies illegal
+    requisites for the whole closure, so all the dependencies
+    recursively.  For example,
+
+<programlisting>
+disallowedRequisites = [ foobar ];
+</programlisting>
+
+    enforces that the output of a derivation cannot have any
+    runtime dependency on <varname>foobar</varname> or any other derivation
+    depending recursively on <varname>foobar</varname>.</para></listitem>
+
+  </varlistentry>
+

  <varlistentry><term><varname>exportReferencesGraph</varname></term>

--- a/doc/manual/expressions/builtins.xml
+++ b/doc/manual/expressions/builtins.xml
@@ -21,7 +21,8 @@ available as <function>builtins.derivation</function>.</para>
 <variablelist>


-  <varlistentry><term><function>abort</function> <replaceable>s</replaceable></term>
+  <varlistentry xml:id='builtin-abort'>
+    <term><function>abort</function> <replaceable>s</replaceable></term>

    <listitem><para>Abort Nix expression evaluation, print error
    message <replaceable>s</replaceable>.</para></listitem>
@@ -29,8 +30,10 @@ available as <function>builtins.derivation</function>.</para>
  </varlistentry>


-  <varlistentry><term><function>builtins.add</function>
-  <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
+  <varlistentry xml:id='builtin-add'>
+    <term><function>builtins.add</function>
+    <replaceable>e1</replaceable> <replaceable>e2</replaceable>
+    </term>

    <listitem><para>Return the sum of the numbers
    <replaceable>e1</replaceable> and
@@ -39,8 +42,9 @@ available as <function>builtins.derivation</function>.</para>
  </varlistentry>


-  <varlistentry><term><function>builtins.all</function>
-  <replaceable>pred</replaceable> <replaceable>list</replaceable></term>
+  <varlistentry xml:id='builtin-all'>
+    <term><function>builtins.all</function>
+    <replaceable>pred</replaceable> <replaceable>list</replaceable></term>

    <listitem><para>Return <literal>true</literal> if the function
    <replaceable>pred</replaceable> returns <literal>true</literal>
@@ -50,8 +54,9 @@ available as <function>builtins.derivation</function>.</para>
  </varlistentry>


-  <varlistentry><term><function>builtins.any</function>
-  <replaceable>pred</replaceable> <replaceable>list</replaceable></term>
+  <varlistentry xml:id='builtin-any'>
+    <term><function>builtins.any</function>
+    <replaceable>pred</replaceable> <replaceable>list</replaceable></term>

    <listitem><para>Return <literal>true</literal> if the function
    <replaceable>pred</replaceable> returns <literal>true</literal>
@@ -61,8 +66,9 @@ available as <function>builtins.derivation</function>.</para>
  </varlistentry>


-  <varlistentry><term><function>builtins.attrNames</function>
-  <replaceable>set</replaceable></term>
+  <varlistentry xml:id='builtin-attrNames'>
+    <term><function>builtins.attrNames</function>
+    <replaceable>set</replaceable></term>

    <listitem><para>Return the names of the attributes in the set
    <replaceable>set</replaceable> in an alphabetically sorted list.  For instance,
@@ -72,8 +78,9 @@ available as <function>builtins.derivation</function>.</para>
  </varlistentry>


-  <varlistentry><term><function>builtins.attrValues</function>
-  <replaceable>set</replaceable></term>
+  <varlistentry xml:id='builtin-attrValues'>
+    <term><function>builtins.attrValues</function>
+    <replaceable>set</replaceable></term>

    <listitem><para>Return the values of the attributes in the set
    <replaceable>set</replaceable> in the order corresponding to the
@@ -82,7 +89,8 @@ available as <function>builtins.derivation</function>.</para>
  </varlistentry>


-  <varlistentry><term><function>baseNameOf</function> <replaceable>s</replaceable></term>
+  <varlistentry xml:id='builtin-baseNameOf'>
+    <term><function>baseNameOf</function> <replaceable>s</replaceable></term>

    <listitem><para>Return the <emphasis>base name</emphasis> of the
    string <replaceable>s</replaceable>, that is, everything following
@@ -92,8 +100,9 @@ available as <function>builtins.derivation</function>.</para>
  </varlistentry>


-  <varlistentry><term><function>builtins.bitAnd</function>
-  <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
+  <varlistentry xml:id='builtin-bitAnd'>
+    <term><function>builtins.bitAnd</function>
+    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>Return the bitwise AND of the integers
    <replaceable>e1</replaceable> and
@@ -102,8 +111,9 @@ available as <function>builtins.derivation</function>.</para>
  </varlistentry>


-  <varlistentry><term><function>builtins.bitOr</function>
-  <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
+  <varlistentry xml:id='builtin-bitOr'>
+    <term><function>builtins.bitOr</function>
+    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>Return the bitwise OR of the integers
    <replaceable>e1</replaceable> and
@@ -112,8 +122,9 @@ available as <function>builtins.derivation</function>.</para>
  </varlistentry>


-  <varlistentry><term><function>builtins.bitXor</function>
-  <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
+  <varlistentry xml:id='builtin-bitXor'>
+    <term><function>builtins.bitXor</function>
+    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>Return the bitwise XOR of the integers
    <replaceable>e1</replaceable> and
@@ -122,7 +133,8 @@ available as <function>builtins.derivation</function>.</para>
  </varlistentry>


-  <varlistentry><term><varname>builtins</varname></term>
+  <varlistentry xml:id='builtin-builtins'>
+    <term><varname>builtins</varname></term>

    <listitem><para>The set <varname>builtins</varname> contains all
    the built-in functions and values.  You can use
@@ -139,8 +151,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.compareVersions</function>
-  <replaceable>s1</replaceable> <replaceable>s2</replaceable></term>
+  <varlistentry xml:id='builtin-compareVersions'>
+    <term><function>builtins.compareVersions</function>
+    <replaceable>s1</replaceable> <replaceable>s2</replaceable></term>

    <listitem><para>Compare two strings representing versions and
    return <literal>-1</literal> if version
@@ -156,8 +169,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.splitVersion</function>
-  <replaceable>s</replaceable></term>
+  <varlistentry xml:id='builtin-splitVersion'>
+    <term><function>builtins.splitVersion</function>
+    <replaceable>s</replaceable></term>

    <listitem><para>Split a string representing a version into its
    components, by the same version splitting logic underlying the
@@ -167,16 +181,18 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.concatLists</function>
-  <replaceable>lists</replaceable></term>
+  <varlistentry xml:id='builtin-concatLists'>
+    <term><function>builtins.concatLists</function>
+    <replaceable>lists</replaceable></term>

    <listitem><para>Concatenate a list of lists into a single
    list.</para></listitem>

  </varlistentry>

-  <varlistentry><term><function>builtins.concatStringsSep</function>
-  <replaceable>separator</replaceable> <replaceable>list</replaceable></term>
+  <varlistentry xml:id='builtin-concatStringsSep'>
+    <term><function>builtins.concatStringsSep</function>
+    <replaceable>separator</replaceable> <replaceable>list</replaceable></term>

    <listitem><para>Concatenate a list of strings with a separator
    between each element, e.g. <literal>concatStringsSep "/"
@@ -184,8 +200,8 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>

  </varlistentry>

-  <varlistentry
-  xml:id='builtin-currentSystem'><term><varname>builtins.currentSystem</varname></term>
+  <varlistentry xml:id='builtin-currentSystem'>
+    <term><varname>builtins.currentSystem</varname></term>

    <listitem><para>The built-in value <varname>currentSystem</varname>
    evaluates to the Nix platform identifier for the Nix installation
@@ -218,8 +234,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
  -->


-  <varlistentry><term><function>builtins.deepSeq</function>
-  <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
+  <varlistentry xml:id='builtin-deepSeq'>
+    <term><function>builtins.deepSeq</function>
+    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>This is like <literal>seq
    <replaceable>e1</replaceable>
@@ -231,8 +248,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
  </varlistentry>


-  <varlistentry><term><function>derivation</function>
-  <replaceable>attrs</replaceable></term>
+  <varlistentry xml:id='builtin-derivation'>
+    <term><function>derivation</function>
+    <replaceable>attrs</replaceable></term>

    <listitem><para><function>derivation</function> is described in
    <xref linkend='ssec-derivation' />.</para></listitem>
@@ -240,7 +258,8 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
  </varlistentry>


-  <varlistentry><term><function>dirOf</function> <replaceable>s</replaceable></term>
+  <varlistentry xml:id='builtin-dirOf'>
+    <term><function>dirOf</function> <replaceable>s</replaceable></term>

    <listitem><para>Return the directory part of the string
    <replaceable>s</replaceable>, that is, everything before the final
@@ -250,8 +269,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.div</function>
-  <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
+  <varlistentry xml:id='builtin-div'>
+    <term><function>builtins.div</function>
+    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>Return the quotient of the numbers
    <replaceable>e1</replaceable> and
@@ -259,8 +279,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>

  </varlistentry>

-  <varlistentry><term><function>builtins.elem</function>
-  <replaceable>x</replaceable> <replaceable>xs</replaceable></term>
+  <varlistentry xml:id='builtin-elem'>
+    <term><function>builtins.elem</function>
+    <replaceable>x</replaceable> <replaceable>xs</replaceable></term>

    <listitem><para>Return <literal>true</literal> if a value equal to
    <replaceable>x</replaceable> occurs in the list
@@ -270,8 +291,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.elemAt</function>
-  <replaceable>xs</replaceable> <replaceable>n</replaceable></term>
+  <varlistentry xml:id='builtin-elemAt'>
+    <term><function>builtins.elemAt</function>
+    <replaceable>xs</replaceable> <replaceable>n</replaceable></term>

    <listitem><para>Return element <replaceable>n</replaceable> from
    the list <replaceable>xs</replaceable>.  Elements are counted
@@ -281,8 +303,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.fetchurl</function>
-  <replaceable>url</replaceable></term>
+  <varlistentry xml:id='builtin-fetchurl'>
+    <term><function>builtins.fetchurl</function>
+    <replaceable>url</replaceable></term>

    <listitem><para>Download the specified URL and return the path of
    the downloaded file. This function is not available if <link
@@ -292,8 +315,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
  </varlistentry>


-  <varlistentry><term><function>fetchTarball</function>
-  <replaceable>url</replaceable></term>
+  <varlistentry xml:id='builtin-fetchTarball'>
+    <term><function>fetchTarball</function>
+    <replaceable>url</replaceable></term>

    <listitem><para>Download the specified URL, unpack it and return
    the path of the unpacked tree. The file must be a tape archive
@@ -346,7 +370,7 @@ stdenv.mkDerivation { … }

  </varlistentry>

-  <varlistentry>
+  <varlistentry xml:id='builtin-fetchGit'>
    <term>
      <function>builtins.fetchGit</function>
      <replaceable>args</replaceable>
@@ -398,6 +422,84 @@ stdenv.mkDerivation { … }
          </listitem>
        </varlistentry>
      </variablelist>
+
+      <example>
+        <title>Fetching a private repository over SSH</title>
+        <programlisting>builtins.fetchGit {
+  url = "git@github.com:my-secret/repository.git";
+  ref = "master";
+  rev = "adab8b916a45068c044658c4158d81878f9ed1c3";
+}</programlisting>
+      </example>
+
+      <example>
+        <title>Fetching a repository's specific commit on an arbitrary branch</title>
+        <para>
+          If the revision you're looking for is in the default branch
+          of the gift repository you don't strictly need to specify
+          the branch name in the <varname>ref</varname> attribute.
+        </para>
+        <para>
+          However, if the revision you're looking for is in a future
+          branch for the non-default branch you will need to specify
+          the the <varname>ref</varname> attribute as well.
+        </para>
+        <programlisting>builtins.fetchGit {
+  url = "https://github.com/nixos/nix.git";
+  rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
+  ref = "1.11-maintenance";
+}</programlisting>
+        <note>
+          <para>
+            It is nice to always specify the branch which a revision
+            belongs to. Without the branch being specified, the
+            fetcher might fail if the default branch changes.
+            Additionally, it can be confusing to try a commit from a
+            non-default branch and see the fetch fail. If the branch
+            is specified the fault is much more obvious.
+          </para>
+        </note>
+      </example>
+
+      <example>
+        <title>Fetching a repository's specific commit on the default branch</title>
+        <para>
+          If the revision you're looking for is in the default branch
+          of the gift repository you may omit the
+          <varname>ref</varname> attribute.
+        </para>
+        <programlisting>builtins.fetchGit {
+  url = "https://github.com/nixos/nix.git";
+  rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
+}</programlisting>
+      </example>
+
+      <example>
+        <title>Fetching a tag</title>
+        <programlisting>builtins.fetchGit {
+  url = "https://github.com/nixos/nix.git";
+  ref = "tags/1.9";
+}</programlisting>
+        <note><para>Due to a bug (<link
+        xlink:href="https://github.com/NixOS/nix/issues/2385">#2385</link>),
+        only non-annotated tags can be fetched.</para></note>
+      </example>
+
+      <example>
+        <title>Fetching the latest version of a remote branch</title>
+        <para>
+          <function>builtins.fetchGit</function> can behave impurely
+           fetch the latest version of a remote branch.
+        </para>
+        <note><para>Nix will refetch the branch in accordance to
+        <option>tarball-ttl</option>.</para></note>
+        <note><para>This behavior is disabled in
+        <emphasis>Pure evaluation mode</emphasis>.</para></note>
+        <programlisting>builtins.fetchGit {
+  url = "ssh://git@github.com/nixos/nix.git";
+  ref = "master";
+}</programlisting>
+      </example>
    </listitem>
  </varlistentry>

@@ -468,7 +570,8 @@ stdenv.mkDerivation {
  </varlistentry>


-  <varlistentry><term><function>builtins.foldl’</function>
+  <varlistentry xml:id='builtin-foldl-prime'>
+    <term><function>builtins.foldl’</function>
    <replaceable>op</replaceable> <replaceable>nul</replaceable> <replaceable>list</replaceable></term>

    <listitem><para>Reduce a list by applying a binary operator, from
@@ -481,7 +584,8 @@ stdenv.mkDerivation {
  </varlistentry>


-  <varlistentry><term><function>builtins.functionArgs</function>
+  <varlistentry xml:id='builtin-functionArgs'>
+    <term><function>builtins.functionArgs</function>
    <replaceable>f</replaceable></term>

    <listitem><para>
@@ -499,7 +603,8 @@ stdenv.mkDerivation {
  </varlistentry>


-  <varlistentry><term><function>builtins.fromJSON</function> <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-fromJSON'>
+    <term><function>builtins.fromJSON</function> <replaceable>e</replaceable></term>

    <listitem><para>Convert a JSON string to a Nix
    value. For example,
@@ -514,8 +619,9 @@ builtins.fromJSON ''{"x": [1, 2, 3], "y": null}''
  </varlistentry>


-  <varlistentry><term><function>builtins.genList</function>
-  <replaceable>generator</replaceable> <replaceable>length</replaceable></term>
+  <varlistentry xml:id='builtin-genList'>
+    <term><function>builtins.genList</function>
+    <replaceable>generator</replaceable> <replaceable>length</replaceable></term>

    <listitem><para>Generate list of size
    <replaceable>length</replaceable>, with each element
@@ -532,8 +638,9 @@ builtins.genList (x: x * x) 5
  </varlistentry>


-  <varlistentry><term><function>builtins.getAttr</function>
-  <replaceable>s</replaceable> <replaceable>set</replaceable></term>
+  <varlistentry xml:id='builtin-getAttr'>
+    <term><function>builtins.getAttr</function>
+    <replaceable>s</replaceable> <replaceable>set</replaceable></term>

    <listitem><para><function>getAttr</function> returns the attribute
    named <replaceable>s</replaceable> from
@@ -545,8 +652,9 @@ builtins.genList (x: x * x) 5
  </varlistentry>


-  <varlistentry><term><function>builtins.getEnv</function>
-  <replaceable>s</replaceable></term>
+  <varlistentry xml:id='builtin-getEnv'>
+    <term><function>builtins.getEnv</function>
+    <replaceable>s</replaceable></term>

    <listitem><para><function>getEnv</function> returns the value of
    the environment variable <replaceable>s</replaceable>, or an empty
@@ -563,8 +671,9 @@ builtins.genList (x: x * x) 5
  </varlistentry>


-  <varlistentry><term><function>builtins.hasAttr</function>
-  <replaceable>s</replaceable> <replaceable>set</replaceable></term>
+  <varlistentry xml:id='builtin-hasAttr'>
+    <term><function>builtins.hasAttr</function>
+    <replaceable>s</replaceable> <replaceable>set</replaceable></term>

    <listitem><para><function>hasAttr</function> returns
    <literal>true</literal> if <replaceable>set</replaceable> has an
@@ -577,8 +686,9 @@ builtins.genList (x: x * x) 5
  </varlistentry>


-  <varlistentry><term><function>builtins.hashString</function>
-  <replaceable>type</replaceable> <replaceable>s</replaceable></term>
+  <varlistentry xml:id='builtin-hashString'>
+    <term><function>builtins.hashString</function>
+    <replaceable>type</replaceable> <replaceable>s</replaceable></term>

    <listitem><para>Return a base-16 representation of the
    cryptographic hash of string <replaceable>s</replaceable>.  The
@@ -589,8 +699,9 @@ builtins.genList (x: x * x) 5
  </varlistentry>


-  <varlistentry><term><function>builtins.head</function>
-  <replaceable>list</replaceable></term>
+  <varlistentry xml:id='builtin-head'>
+    <term><function>builtins.head</function>
+    <replaceable>list</replaceable></term>

    <listitem><para>Return the first element of a list; abort
    evaluation if the argument isn’t a list or is an empty list.  You
@@ -600,8 +711,9 @@ builtins.genList (x: x * x) 5
  </varlistentry>


-  <varlistentry><term><function>import</function>
-  <replaceable>path</replaceable></term>
+  <varlistentry xml:id='builtin-import'>
+    <term><function>import</function>
+    <replaceable>path</replaceable></term>

    <listitem><para>Load, parse and return the Nix expression in the
    file <replaceable>path</replaceable>.  If <replaceable>path
@@ -655,8 +767,9 @@ x: x + 456</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.intersectAttrs</function>
-  <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
+  <varlistentry xml:id='builtin-intersectAttrs'>
+    <term><function>builtins.intersectAttrs</function>
+    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>Return a set consisting of the attributes in the
    set <replaceable>e2</replaceable> that also exist in the set
@@ -665,8 +778,9 @@ x: x + 456</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.isAttrs</function>
-  <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-isAttrs'>
+    <term><function>builtins.isAttrs</function>
+    <replaceable>e</replaceable></term>

    <listitem><para>Return <literal>true</literal> if
    <replaceable>e</replaceable> evaluates to a set, and
@@ -675,8 +789,9 @@ x: x + 456</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.isList</function>
-  <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-isList'>
+    <term><function>builtins.isList</function>
+    <replaceable>e</replaceable></term>

    <listitem><para>Return <literal>true</literal> if
    <replaceable>e</replaceable> evaluates to a list, and
@@ -685,7 +800,7 @@ x: x + 456</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.isFunction</function>
+  <varlistentry xml:id='builtin-isFunction'><term><function>builtins.isFunction</function>
  <replaceable>e</replaceable></term>

    <listitem><para>Return <literal>true</literal> if
@@ -695,8 +810,9 @@ x: x + 456</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.isString</function>
-  <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-isString'>
+    <term><function>builtins.isString</function>
+    <replaceable>e</replaceable></term>

    <listitem><para>Return <literal>true</literal> if
    <replaceable>e</replaceable> evaluates to a string, and
@@ -705,8 +821,9 @@ x: x + 456</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.isInt</function>
-  <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-isInt'>
+    <term><function>builtins.isInt</function>
+    <replaceable>e</replaceable></term>

    <listitem><para>Return <literal>true</literal> if
    <replaceable>e</replaceable> evaluates to an int, and
@@ -715,8 +832,9 @@ x: x + 456</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.isFloat</function>
-  <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-isFloat'>
+    <term><function>builtins.isFloat</function>
+    <replaceable>e</replaceable></term>

    <listitem><para>Return <literal>true</literal> if
    <replaceable>e</replaceable> evaluates to a float, and
@@ -725,8 +843,9 @@ x: x + 456</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.isBool</function>
-  <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-isBool'>
+    <term><function>builtins.isBool</function>
+    <replaceable>e</replaceable></term>

    <listitem><para>Return <literal>true</literal> if
    <replaceable>e</replaceable> evaluates to a bool, and
@@ -735,8 +854,9 @@ x: x + 456</programlisting>
  </varlistentry>


-  <varlistentry><term><function>isNull</function>
-  <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-isNull'>
+    <term><function>isNull</function>
+    <replaceable>e</replaceable></term>

    <listitem><para>Return <literal>true</literal> if
    <replaceable>e</replaceable> evaluates to <literal>null</literal>,
@@ -750,8 +870,9 @@ x: x + 456</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.length</function>
-  <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-length'>
+    <term><function>builtins.length</function>
+    <replaceable>e</replaceable></term>

    <listitem><para>Return the length of the list
    <replaceable>e</replaceable>.</para></listitem>
@@ -759,8 +880,9 @@ x: x + 456</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.lessThan</function>
-  <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
+  <varlistentry xml:id='builtin-lessThan'>
+    <term><function>builtins.lessThan</function>
+    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>Return <literal>true</literal> if the number
    <replaceable>e1</replaceable> is less than the number
@@ -772,8 +894,9 @@ x: x + 456</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.listToAttrs</function>
-  <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-listToAttrs'>
+    <term><function>builtins.listToAttrs</function>
+    <replaceable>e</replaceable></term>

    <listitem><para>Construct a set from a list specifying the names
    and values of each attribute.  Each element of the list should be
@@ -799,8 +922,9 @@ builtins.listToAttrs

  </varlistentry>

-  <varlistentry><term><function>map</function>
-  <replaceable>f</replaceable> <replaceable>list</replaceable></term>
+  <varlistentry xml:id='builtin-map'>
+    <term><function>map</function>
+    <replaceable>f</replaceable> <replaceable>list</replaceable></term>

    <listitem><para>Apply the function <replaceable>f</replaceable> to
    each element in the list <replaceable>list</replaceable>.  For
@@ -815,14 +939,15 @@ map (x: "foo" + x) [ "bar" "bla" "abc" ]</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.match</function>
-  <replaceable>regex</replaceable> <replaceable>str</replaceable></term>
+  <varlistentry xml:id='builtin-match'>
+    <term><function>builtins.match</function>
+    <replaceable>regex</replaceable> <replaceable>str</replaceable></term>

-  <listitem><para>Returns a list if the <link
-  xlink:href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04">extended
-  POSIX regular expression</link> <replaceable>regex</replaceable>
-  matches <replaceable>str</replaceable> precisely, otherwise returns
-  <literal>null</literal>.  Each item in the list is a regex group.
+    <listitem><para>Returns a list if the <link
+    xlink:href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04">extended
+    POSIX regular expression</link> <replaceable>regex</replaceable>
+    matches <replaceable>str</replaceable> precisely, otherwise returns
+    <literal>null</literal>.  Each item in the list is a regex group.

 <programlisting>
 builtins.match "ab" "abc"
@@ -848,11 +973,12 @@ builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" "  FOO   "

 Evaluates to <literal>[ "foo" ]</literal>.

-  </para></listitem>
+    </para></listitem>
  </varlistentry>

-  <varlistentry><term><function>builtins.mul</function>
-  <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
+  <varlistentry xml:id='builtin-mul'>
+    <term><function>builtins.mul</function>
+    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>Return the product of the numbers
    <replaceable>e1</replaceable> and
@@ -861,8 +987,9 @@ Evaluates to <literal>[ "foo" ]</literal>.
  </varlistentry>


-  <varlistentry><term><function>builtins.parseDrvName</function>
-  <replaceable>s</replaceable></term>
+  <varlistentry xml:id='builtin-parseDrvName'>
+    <term><function>builtins.parseDrvName</function>
+    <replaceable>s</replaceable></term>

    <listitem><para>Split the string <replaceable>s</replaceable> into
    a package name and version.  The package name is everything up to
@@ -875,7 +1002,7 @@ Evaluates to <literal>[ "foo" ]</literal>.

  </varlistentry>

-  <varlistentry>
+  <varlistentry xml:id='builtin-path'>
    <term>
      <function>builtins.path</function>
      <replaceable>args</replaceable>
@@ -945,8 +1072,9 @@ Evaluates to <literal>[ "foo" ]</literal>.
    </listitem>
  </varlistentry>

-  <varlistentry><term><function>builtins.pathExists</function>
-  <replaceable>path</replaceable></term>
+  <varlistentry xml:id='builtin-pathExists'>
+    <term><function>builtins.pathExists</function>
+    <replaceable>path</replaceable></term>

    <listitem><para>Return <literal>true</literal> if the path
    <replaceable>path</replaceable> exists, and
@@ -969,8 +1097,9 @@ in config.someSetting</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.readDir</function>
-  <replaceable>path</replaceable></term>
+  <varlistentry xml:id='builtin-readDir'>
+    <term><function>builtins.readDir</function>
+    <replaceable>path</replaceable></term>

    <listitem><para>Return the contents of the directory
    <replaceable>path</replaceable> as a set mapping directory entries
@@ -991,8 +1120,9 @@ in config.someSetting</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.readFile</function>
-  <replaceable>path</replaceable></term>
+  <varlistentry xml:id='builtin-readFile'>
+    <term><function>builtins.readFile</function>
+    <replaceable>path</replaceable></term>

    <listitem><para>Return the contents of the file
    <replaceable>path</replaceable> as a string.</para></listitem>
@@ -1000,8 +1130,9 @@ in config.someSetting</programlisting>
  </varlistentry>


-  <varlistentry><term><function>removeAttrs</function>
-  <replaceable>set</replaceable> <replaceable>list</replaceable></term>
+  <varlistentry xml:id='builtin-removeAttrs'>
+    <term><function>removeAttrs</function>
+    <replaceable>set</replaceable> <replaceable>list</replaceable></term>

    <listitem><para>Remove the attributes listed in
    <replaceable>list</replaceable> from
@@ -1016,8 +1147,9 @@ removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.replaceStrings</function>
-  <replaceable>from</replaceable> <replaceable>to</replaceable> <replaceable>s</replaceable></term>
+  <varlistentry xml:id='builtin-replaceStrings'>
+    <term><function>builtins.replaceStrings</function>
+    <replaceable>from</replaceable> <replaceable>to</replaceable> <replaceable>s</replaceable></term>

    <listitem><para>Given string <replaceable>s</replaceable>, replace
    every occurrence of the strings in <replaceable>from</replaceable>
@@ -1033,8 +1165,9 @@ builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar"
  </varlistentry>


-  <varlistentry><term><function>builtins.seq</function>
-  <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
+  <varlistentry xml:id='builtin-seq'>
+    <term><function>builtins.seq</function>
+    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>Evaluate <replaceable>e1</replaceable>, then
    evaluate and return <replaceable>e2</replaceable>. This ensures
@@ -1044,8 +1177,9 @@ builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar"
  </varlistentry>


-  <varlistentry><term><function>builtins.sort</function>
-  <replaceable>comparator</replaceable> <replaceable>list</replaceable></term>
+  <varlistentry xml:id='builtin-sort'>
+    <term><function>builtins.sort</function>
+    <replaceable>comparator</replaceable> <replaceable>list</replaceable></term>

    <listitem><para>Return <replaceable>list</replaceable> in sorted
    order. It repeatedly calls the function
@@ -1067,15 +1201,16 @@ builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ]
  </varlistentry>


-  <varlistentry><term><function>builtins.split</function>
-  <replaceable>regex</replaceable> <replaceable>str</replaceable></term>
+  <varlistentry xml:id='builtin-split'>
+    <term><function>builtins.split</function>
+    <replaceable>regex</replaceable> <replaceable>str</replaceable></term>

-  <listitem><para>Returns a list composed of non matched strings interleaved
-  with the lists of the <link
-  xlink:href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04">extended
-  POSIX regular expression</link> <replaceable>regex</replaceable> matches
-  of <replaceable>str</replaceable>. Each item in the lists of matched
-  sequences is a regex group.
+    <listitem><para>Returns a list composed of non matched strings interleaved
+    with the lists of the <link
+    xlink:href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04">extended
+    POSIX regular expression</link> <replaceable>regex</replaceable> matches
+    of <replaceable>str</replaceable>. Each item in the lists of matched
+    sequences is a regex group.

 <programlisting>
 builtins.split "(a)b" "abc"
@@ -1101,11 +1236,12 @@ builtins.split "([[:upper:]]+)" "  FOO   "

 Evaluates to <literal>[ "  " [ "FOO" ] "   " ]</literal>.

-  </para></listitem>
+    </para></listitem>
  </varlistentry>

-  <varlistentry><term><function>builtins.stringLength</function>
-  <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-stringLength'>
+    <term><function>builtins.stringLength</function>
+    <replaceable>e</replaceable></term>

    <listitem><para>Return the length of the string
    <replaceable>e</replaceable>.  If <replaceable>e</replaceable> is
@@ -1114,8 +1250,9 @@ Evaluates to <literal>[ "  " [ "FOO" ] "   " ]</literal>.
  </varlistentry>


-  <varlistentry><term><function>builtins.sub</function>
-  <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
+  <varlistentry xml:id='builtin-sub'>
+    <term><function>builtins.sub</function>
+    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>Return the difference between the numbers
    <replaceable>e1</replaceable> and
@@ -1124,9 +1261,10 @@ Evaluates to <literal>[ "  " [ "FOO" ] "   " ]</literal>.
  </varlistentry>


-  <varlistentry><term><function>builtins.substring</function>
-  <replaceable>start</replaceable> <replaceable>len</replaceable>
-  <replaceable>s</replaceable></term>
+  <varlistentry xml:id='builtin-substring'>
+    <term><function>builtins.substring</function>
+    <replaceable>start</replaceable> <replaceable>len</replaceable>
+    <replaceable>s</replaceable></term>

    <listitem><para>Return the substring of
    <replaceable>s</replaceable> from character position
@@ -1149,8 +1287,9 @@ builtins.substring 0 3 "nixos"
  </varlistentry>


-  <varlistentry><term><function>builtins.tail</function>
-  <replaceable>list</replaceable></term>
+  <varlistentry xml:id='builtin-tail'>
+    <term><function>builtins.tail</function>
+    <replaceable>list</replaceable></term>

    <listitem><para>Return the second to last elements of a list;
    abort evaluation if the argument isn’t a list or is an empty
@@ -1159,8 +1298,9 @@ builtins.substring 0 3 "nixos"
  </varlistentry>


-  <varlistentry><term><function>throw</function>
-  <replaceable>s</replaceable></term>
+  <varlistentry xml:id='builtin-throw'>
+    <term><function>throw</function>
+    <replaceable>s</replaceable></term>

    <listitem><para>Throw an error message
    <replaceable>s</replaceable>.  This usually aborts Nix expression
@@ -1173,9 +1313,10 @@ builtins.substring 0 3 "nixos"
  </varlistentry>


-  <varlistentry
-  xml:id='builtin-toFile'><term><function>builtins.toFile</function>
-  <replaceable>name</replaceable> <replaceable>s</replaceable></term>
+  <varlistentry xml:id='builtin-toFile'>
+    <term><function>builtins.toFile</function>
+    <replaceable>name</replaceable>
+    <replaceable>s</replaceable></term>

    <listitem><para>Store the string <replaceable>s</replaceable> in a
    file in the Nix store and return its path.  The file has suffix
@@ -1244,14 +1385,15 @@ in foo</programlisting>
    This is not allowed because it would cause a cyclic dependency in
    the computation of the cryptographic hashes for
    <varname>foo</varname> and <varname>bar</varname>.</para>
-    <para>It is also not possible to reference the result of a derivation. 
-    If you are using Nixpkgs, the <literal>writeTextFile</literal> function is able to 
+    <para>It is also not possible to reference the result of a derivation.
+    If you are using Nixpkgs, the <literal>writeTextFile</literal> function is able to
    do that.</para></listitem>

  </varlistentry>


-  <varlistentry><term><function>builtins.toJSON</function> <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-toJSON'>
+    <term><function>builtins.toJSON</function> <replaceable>e</replaceable></term>

    <listitem><para>Return a string containing a JSON representation
    of <replaceable>e</replaceable>.  Strings, integers, floats, booleans,
@@ -1264,7 +1406,8 @@ in foo</programlisting>
  </varlistentry>


-  <varlistentry><term><function>builtins.toPath</function> <replaceable>s</replaceable></term>
+  <varlistentry xml:id='builtin-toPath'>
+    <term><function>builtins.toPath</function> <replaceable>s</replaceable></term>

    <listitem><para>Convert the string value
    <replaceable>s</replaceable> into a path value.  The string
@@ -1277,7 +1420,8 @@ in foo</programlisting>
  </varlistentry>


-  <varlistentry><term><function>toString</function> <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-toString'>
+    <term><function>toString</function> <replaceable>e</replaceable></term>

    <listitem><para>Convert the expression
    <replaceable>e</replaceable> to a string.
@@ -1296,7 +1440,8 @@ in foo</programlisting>
  </varlistentry>


-  <varlistentry xml:id='builtin-toXML'><term><function>builtins.toXML</function> <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-toXML'>
+    <term><function>builtins.toXML</function> <replaceable>e</replaceable></term>

    <listitem><para>Return a string containing an XML representation
    of <replaceable>e</replaceable>.  The main application for
@@ -1411,8 +1556,9 @@ stdenv.mkDerivation (rec {
  </varlistentry>


-  <varlistentry><term><function>builtins.trace</function>
-  <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
+  <varlistentry xml:id='builtin-trace'>
+    <term><function>builtins.trace</function>
+    <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>

    <listitem><para>Evaluate <replaceable>e1</replaceable> and print its
    abstract syntax representation on standard error.  Then return
@@ -1421,8 +1567,9 @@ stdenv.mkDerivation (rec {

  </varlistentry>

-  <varlistentry><term><function>builtins.tryEval</function>
-  <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-tryEval'>
+    <term><function>builtins.tryEval</function>
+    <replaceable>e</replaceable></term>

    <listitem><para>Try to evaluate <replaceable>e</replaceable>.
    Return a set containing the attributes <literal>success</literal>
@@ -1435,8 +1582,9 @@ stdenv.mkDerivation (rec {
  </varlistentry>


-  <varlistentry><term><function>builtins.typeOf</function>
-  <replaceable>e</replaceable></term>
+  <varlistentry xml:id='builtin-typeOf'>
+    <term><function>builtins.typeOf</function>
+    <replaceable>e</replaceable></term>

    <listitem><para>Return a string representing the type of the value
    <replaceable>e</replaceable>, namely <literal>"int"</literal>,
--- a/doc/manual/expressions/language-constructs.xml
+++ b/doc/manual/expressions/language-constructs.xml
@@ -41,7 +41,7 @@ encountered</quote>).</para></footnote>.</para>
 </simplesect>


-<simplesect><title>Let-expressions</title>
+<simplesect xml:id="sect-let-expressions"><title>Let-expressions</title>

 <para>A let-expression allows you define local variables for an
 expression.  For instance,
--- a/doc/manual/glossary/glossary.xml
+++ b/doc/manual/glossary/glossary.xml
@@ -1,5 +1,6 @@
 <appendix xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink">
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xml:id="part-glossary">

 <title>Glossary</title>

--- a/doc/manual/hacking.xml
+++ b/doc/manual/hacking.xml
@@ -30,7 +30,7 @@ To build Nix itself in this shell:
 [nix-shell]$ configurePhase
 [nix-shell]$ make
 </screen>
-To install it in <literal>$(pwd)/nix</literal> and test it:
+To install it in <literal>$(pwd)/inst</literal> and test it:
 <screen>
 [nix-shell]$ make install
 [nix-shell]$ make installcheck
--- a/doc/manual/installation/env-variables.xml
+++ b/doc/manual/installation/env-variables.xml
@@ -39,7 +39,7 @@ bundle.</para>
  <step><para>Set the environment variable and install Nix</para>
    <screen>
 $ export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt
-$ curl https://nixos.org/nix/install | sh
+$ sh &lt;(curl https://nixos.org/nix/install)
 </screen></step>

  <step><para>In the shell profile and rc files (for example,
@@ -55,7 +55,7 @@ export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt
 the Nix installer will detect the presense of Nix configuration, and
 abort.</para></note>

-<section>
+<section xml:id="sec-nix-ssl-cert-file-with-nix-daemon-and-macos">
 <title><envar>NIX_SSL_CERT_FILE</envar> with macOS and the Nix daemon</title>

 <para>On macOS you must specify the environment variable for the Nix
--- a/doc/manual/installation/installing-binary.xml
+++ b/doc/manual/installation/installing-binary.xml
@@ -6,13 +6,30 @@

 <title>Installing a Binary Distribution</title>

-<para>If you are using Linux or macOS, the easiest way to install
-Nix is to run the following command:
+<para>If you are using Linux or macOS, the easiest way to install Nix
+is to run the following command:

 <screen>
-$ bash &lt;(curl https://nixos.org/nix/install)
+  $ sh &lt;(curl https://nixos.org/nix/install)
 </screen>

+As of Nix 2.1.0, the Nix installer will always default to creating a
+single-user installation, however opting in to the multi-user
+installation is highly recommended.
+</para>
+
+<section xml:id="sect-single-user-installation">
+  <title>Single User Installation</title>
+
+  <para>
+    To explicitly select a single-user installation on your system:
+
+    <screen>
+  sh &lt;(curl https://nixos.org/nix/install) --no-daemon
+</screen>
+  </para>
+
+<para>
 This will perform a single-user installation of Nix, meaning that
 <filename>/nix</filename> is owned by the invoking user.  You should
 run this under your usual user account, <emphasis>not</emphasis> as
@@ -33,51 +50,8 @@ and <filename>.profile</filename> to source
 the <command>NIX_INSTALLER_NO_MODIFY_PROFILE</command> environment
 variable before executing the install script to disable this
 behaviour.
-
 </para>

-<!--
-<para>You can also manually download and install a binary package.
-Binary packages of the latest stable release are available for Fedora,
-Debian, Ubuntu, macOS and various other systems from the <link
-xlink:href="http://nixos.org/nix/download.html">Nix homepage</link>.
-You can also get builds of the latest development release from our
-<link
-xlink:href="http://hydra.nixos.org/job/nix/master/release/latest-finished#tabs-constituents">continuous
-build system</link>.</para>
-
-<para>For Fedora, RPM packages are available.  These can be installed
-or upgraded using <command>rpm -U</command>.  For example,
-
-<screen>
-$ rpm -U nix-1.8-1.i386.rpm</screen>
-
-</para>
-
-<para>For Debian and Ubuntu, you can download a Deb package and
-install it like this:
-
-<screen>
-$ dpkg -i nix_1.8-1_amd64.deb</screen>
-
-</para>
-->
-
-<para>You can also download a binary tarball that contains Nix and all
-its dependencies.  (This is what the install script at
-<uri>https://nixos.org/nix/install</uri> does automatically.)  You
-should unpack it somewhere (e.g. in <filename>/tmp</filename>), and
-then run the script named <command>install</command> inside the binary
-tarball:
-
-<screen>
-alice$ cd /tmp
-alice$ tar xfj nix-1.8-x86_64-darwin.tar.bz2
-alice$ cd nix-1.8-x86_64-darwin
-alice$ ./install
-</screen>
-
-</para>

 <para>You can uninstall Nix simply by running:

@@ -86,5 +60,131 @@ $ rm -rf /nix
 </screen>

 </para>
+</section>

+<section xml:id="sect-multi-user-installation">
+  <title>Multi User Installation</title>
+  <para>
+    The multi-user Nix installation creates system users, and a system
+    service for the Nix daemon.
+  </para>
+
+  <itemizedlist>
+    <title>Supported Systems</title>
+
+    <listitem>
+      <para>Linux running systemd, with SELinux disabled</para>
+    </listitem>
+    <listitem><para>macOS</para></listitem>
+  </itemizedlist>
+
+  <para>
+    You can instruct the installer to perform a multi-user
+    installation on your system:
+
+    <screen>
+  sh &lt;(curl https://nixos.org/nix/install) --daemon
+</screen>
+  </para>
+
+  <para>
+    The multi-user installation of Nix will create build users between
+    the user IDs 30001 and 30032, and a group with the group ID 30000.
+
+    You should run this under your usual user account,
+    <emphasis>not</emphasis> as root. The script will invoke
+    <command>sudo</command> as needed.
+  </para>
+
+  <note><para>
+    If you need Nix to use a different group ID or user ID set, you
+    will have to download the tarball manually and <link
+    linkend="sect-nix-install-binary-tarball">edit the install
+    script</link>.
+  </para></note>
+
+  <para>
+    The installer will modify <filename>/etc/bashrc</filename>, and
+    <filename>/etc/zshrc</filename> if they exist. The installer will
+    first back up these files with a
+    <literal>.backup-before-nix</literal> extension. The installer
+    will also create <filename>/etc/profile.d/nix.sh</filename>.
+  </para>
+
+  <para>You can uninstall Nix with the following commands:
+
+<screen>
+sudo rm -rf /etc/profile/nix.sh /etc/nix /nix ~root/.nix-profile ~root/.nix-defexpr ~root/.nix-channels ~/.nix-profile ~/.nix-defexpr ~/.nix-channels
+
+# If you are on Linux with systemd, you will need to run:
+sudo systemctl stop nix-daemon.socket
+sudo systemctl stop nix-daemon.service
+sudo systemctl disable nix-daemon.socket
+sudo systemctl disable nix-daemon.service
+sudo systemctl daemon-reload
+
+# If you are on macOS, you will need to run:
+sudo launchctl unload /Library/LaunchDaemons/org.nixos.nix-daemon.plist
+sudo rm /Library/LaunchDaemons/org.nixos.nix-daemon.plist
+</screen>
+
+    There may also be references to Nix in
+    <filename>/etc/profile</filename>,
+    <filename>/etc/bashrc</filename>, and
+    <filename>/etc/zshrc</filename> which you may remove.
+  </para>
+
+</section>
+
+<section xml:id="sect-nix-install-pinned-version-url">
+  <title>Installing a pinned Nix version from a URL</title>
+
+  <para>
+    NixOS.org hosts version-specific installation URLs for all Nix
+    versions since 1.11.16, at
+    <literal>https://nixos.org/releases/nix/nix-VERSION/install</literal>.
+  </para>
+
+  <para>
+    These install scripts can be used the same as the main
+  NixOS.org installation script:
+
+  <screen>
+  sh &lt;(curl https://nixos.org/nix/install)
+</screen>
+  </para>
+
+  <para>
+    In the same directory of the install script are sha256 sums, and
+    gpg signature files.
+  </para>
+</section>
+
+<section xml:id="sect-nix-install-binary-tarball">
+  <title>Installing from a binary tarball</title>
+
+  <para>
+    You can also download a binary tarball that contains Nix and all
+    its dependencies.  (This is what the install script at
+    <uri>https://nixos.org/nix/install</uri> does automatically.)  You
+    should unpack it somewhere (e.g. in <filename>/tmp</filename>),
+    and then run the script named <command>install</command> inside
+    the binary tarball:
+
+
+<screen>
+alice$ cd /tmp
+alice$ tar xfj nix-1.8-x86_64-darwin.tar.bz2
+alice$ cd nix-1.8-x86_64-darwin
+alice$ ./install
+</screen>
+  </para>
+
+  <para>
+    If you need to edit the multi-user installation script to use
+    different group ID or a different user ID range, modify the
+    variables set in the file named
+    <filename>install-multi-user</filename>.
+  </para>
+</section>
 </chapter>
--- a/doc/manual/installation/prerequisites-source.xml
+++ b/doc/manual/installation/prerequisites-source.xml
@@ -29,7 +29,8 @@
  <literal>libbz2</literal> library.  Thus you must have bzip2
  installed, including development headers and libraries.  If your
  distribution does not provide these, you can obtain bzip2 from <link
-  xlink:href="http://www.bzip.org/"/>.</para></listitem>
+  xlink:href="https://web.archive.org/web/20180624184756/http://www.bzip.org/"
+  />.</para></listitem>

  <listitem><para><literal>liblzma</literal>, which is provided by
  XZ Utils. If your distribution does not provide this, you can
--- a/doc/manual/installation/supported-platforms.xml
+++ b/doc/manual/installation/supported-platforms.xml
@@ -10,7 +10,7 @@

 <itemizedlist>

-  <listitem><para>Linux (i686, x86_64).</para></listitem>
+  <listitem><para>Linux (i686, x86_64, aarch64).</para></listitem>

  <listitem><para>macOS (x86_64).</para></listitem>

--- a/doc/manual/installation/upgrading.xml
+++ b/doc/manual/installation/upgrading.xml
@@ -0,0 +1,22 @@
+<chapter 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="ch-upgrading-nix">
+
+  <title>Upgrading Nix</title>
+
+  <para>
+    Multi-user Nix users on macOS can upgrade Nix by running:
+    <command>sudo -i sh -c 'nix-channel --update &amp;&amp;
+    nix-env -iA nixpkgs.nix &amp;&amp;
+    launchctl remove org.nixos.nix-daemon &amp;&amp;
+    launchctl load /Library/LaunchDaemons/org.nixos.nix-daemon.plist'</command>
+  </para>
+
+
+  <para>
+    Single-user installations of Nix should run this:
+    <command>nix-channel --update; nix-env -iA nixpkgs.nix</command>
+  </para>
+</chapter>
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -32,6 +32,7 @@

  <xi:include href="introduction/introduction.xml" />
  <xi:include href="installation/installation.xml" />
+  <xi:include href="installation/upgrading.xml" />
  <xi:include href="packages/package-management.xml" />
  <xi:include href="expressions/writing-nix-expressions.xml" />
  <xi:include href="advanced-topics/advanced-topics.xml" />
--- a/doc/manual/packages/s3-substituter.xml
+++ b/doc/manual/packages/s3-substituter.xml
@@ -12,8 +12,49 @@ from Amazon S3 and S3 compatible services. This uses the same
 <emphasis>binary</emphasis> cache mechanism that Nix usually uses to
 fetch prebuilt binaries from <uri>cache.nixos.org</uri>.</para>

+<para>The following options can be specified as URL parameters to
+the S3 URL:</para>
+
+<variablelist>
+  <varlistentry><term><literal>profile</literal></term>
+  <listitem>
+    <para>
+      The name of the AWS configuration profile to use. By default
+      Nix will use the <literal>default</literal> profile.
+    </para>
+  </listitem>
+  </varlistentry>
+
+  <varlistentry><term><literal>region</literal></term>
+  <listitem>
+    <para>
+      The region of the S3 bucket. <literal>us–east-1</literal> by
+      default.
+    </para>
+
+    <para>
+      If your bucket is not in <literal>us–east-1</literal>, you
+      should always explicitly specify the region parameter.
+    </para>
+  </listitem>
+  </varlistentry>
+
+  <varlistentry><term><literal>endpoint</literal></term>
+  <listitem>
+    <para>
+      The URL to your S3-compatible service, for when not using
+      Amazon S3. Do not specify this value if you're using Amazon
+      S3.
+    </para>
+    <note><para>This endpoint must support HTTPS and will use
+    path-based addressing instead of virtual host based
+    addressing.</para></note>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
 <para>In this example we will use the bucket named
-<literal>example-bucket</literal>.</para>
+<literal>example-nix-cache</literal>.</para>

 <section xml:id="ssec-s3-substituter-anonymous-reads">
  <title>Anonymous Reads to your S3-compatible binary cache</title>
@@ -24,65 +65,56 @@ fetch prebuilt binaries from <uri>cache.nixos.org</uri>.</para>
  cache.</para>

  <para>For AWS S3 the binary cache URL for example bucket will be
-  exactly <uri>https://example-bucket.s3.amazonaws.com</uri>. For S3
-  compatible binary caches ago have to consult your software's
-  documentation.</para>
+  exactly <uri>https://example-nix-cache.s3.amazonaws.com</uri> or
+  <uri>s3://example-nix-cache</uri>. For S3 compatible binary caches,
+  consult that cache's documentation.</para>

  <para>Your bucket will need the following bucket policy:</para>

-  <programlisting>
-<![CDATA[
+  <programlisting><![CDATA[
 {
-  "Id": "DirectReads",
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Sid": "AlowDirectReads",
-      "Action": [
-        "s3:GetObject"
-      ],
-      "Effect": "Allow",
-      "Resource": "arn:aws:s3:::example-bucket/*",
-      "Principal": "*"
-    }
-  ]
+    "Id": "DirectReads",
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "AlowDirectReads",
+            "Action": [
+                "s3:GetObject",
+                "s3:GetBucketLocation"
+            ],
+            "Effect": "Allow",
+            "Resource": [
+                "arn:aws:s3:::example-nix-cache",
+                "arn:aws:s3:::example-nix-cache/*"
+            ],
+            "Principal": "*"
+        }
+    ]
 }
-]]>
-</programlisting>
+]]></programlisting>
 </section>

 <section xml:id="ssec-s3-substituter-authenticated-reads">
  <title>Authenticated Reads to your S3 binary cache</title>

  <para>For AWS S3 the binary cache URL for example bucket will be
-  exactly <uri>s3://example-bucket</uri>.</para>
+  exactly <uri>s3://example-nix-cache</uri>.</para>

  <para>Nix will use the <link
  xlink:href="https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default.">default
  credential provider chain</link> for authenticating requests to
  Amazon S3.</para>

-  <para>Nix supports authenticated writes to S3 compatible binary
-  caches but only supports Authenticated reads from Amazon S3.
-  Additionally, the following limitations are in place for
-  authenticated reads:</para>
-
-  <itemizedlist>
-    <listitem><para>The bucket must actually be hosted by Amazon S3 and
-    <emphasis>not</emphasis> an S3 compatible
-    service.</para></listitem>
-
-    <listitem><para>The bucket must be within the
-    <literal>us-east-1</literal> region.</para></listitem>
-
-    <listitem><para>The Amazon credentials, if stored in a credential
-    profile, must be stored in the <literal>default</literal>
-    profile.</para></listitem>
-  </itemizedlist>
+  <para>Nix supports authenticated reads from Amazon S3 and S3
+  compatible binary caches.</para>

  <para>Your bucket will need a bucket policy allowing the desired
-  users to perform the <literal>s3:GetObject</literal> action on all
-  objects in the bucket.</para>
+  users to perform the <literal>s3:GetObject</literal> and
+  <literal>s3:GetBucketLocation</literal> action on all objects in the
+  bucket. The anonymous policy in <xref
+  linkend="ssec-s3-substituter-anonymous-reads" /> can be updated to
+  have a restricted <literal>Principal</literal> to support
+  this.</para>
 </section>


@@ -91,69 +123,49 @@ fetch prebuilt binaries from <uri>cache.nixos.org</uri>.</para>

  <para>Nix support fully supports writing to Amazon S3 and S3
  compatible buckets. The binary cache URL for our example bucket will
-  be <uri>s3://example-bucket</uri>.</para>
+  be <uri>s3://example-nix-cache</uri>.</para>

  <para>Nix will use the <link
  xlink:href="https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default.">default
  credential provider chain</link> for authenticating requests to
  Amazon S3.</para>

-  <para>The following options can be specified as URL parameters to
-  the S3 URL:</para>
-  <variablelist>
-    <varlistentry><term><literal>profile</literal></term>
-    <listitem>
-      <para>
-        The name of the AWS configuration profile to use. By default
-        Nix will use the <literal>default</literal> profile.
-      </para>
-    </listitem>
-    </varlistentry>
+  <para>Your account will need the following IAM policy to
+  upload to the cache:</para>

-    <varlistentry><term><literal>region</literal></term>
-    <listitem>
-      <para>
-        The region of the S3 bucket. <literal>us–east-1</literal> by
-        default.
-      </para>
-    </listitem>
-    </varlistentry>
+  <programlisting><![CDATA[
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "UploadToCache",
+      "Effect": "Allow",
+      "Action": [
+        "s3:AbortMultipartUpload",
+        "s3:GetBucketLocation",
+        "s3:GetObject",
+        "s3:ListBucket",
+        "s3:ListBucketMultipartUploads",
+        "s3:ListMultipartUploadParts",
+        "s3:ListObjects",
+        "s3:PutObject"
+      ],
+      "Resource": [
+        "arn:aws:s3:::example-nix-cache",
+        "arn:aws:s3:::example-nix-cache/*"
+      ]
+    }
+  ]
+}
+]]></programlisting>

-    <varlistentry><term><literal>endpoint</literal></term>
-    <listitem>
-      <para>
-        The URL to your S3-compatible service, for when not using
-        Amazon S3. Do not specify this value if you're using Amazon
-        S3.
-      </para>
-      <note><para>This endpoint must support HTTPS and will use
-      path-based addressing instead of virtual host based
-      addressing.</para></note>
-    </listitem>
-    </varlistentry>
-  </variablelist>

-  <example><title>Uploading with non-default credential profile for Amazon S3</title>
-    <para><command>nix copy --to ssh://machine nixpkgs.hello s3://example-bucket?profile=cache-upload</command></para>
+  <example><title>Uploading with a specific credential profile for Amazon S3</title>
+    <para><command>nix copy --to 's3://example-nix-cache?profile=cache-upload&amp;region=eu-west-2' nixpkgs.hello</command></para>
  </example>

  <example><title>Uploading to an S3-Compatible Binary Cache</title>
-    <para><command>nix copy --to ssh://machine nixpkgs.hello s3://example-bucket?profile=cache-upload&amp;endpoint=minio.example.com</command></para>
+    <para><command>nix copy --to 's3://example-nix-cache?profile=cache-upload&amp;endpoint=minio.example.com' nixpkgs.hello</command></para>
  </example>
-
-  <para>The user writing to the bucket will need to perform the
-  following actions against the bucket:</para>
-
-  <itemizedlist>
-    <listitem><para><literal>s3:ListBucket</literal></para></listitem>
-    <listitem><para><literal>s3:GetBucketLocation</literal></para></listitem>
-    <listitem><para><literal>s3:ListObjects</literal></para></listitem>
-    <listitem><para><literal>s3:GetObject</literal></para></listitem>
-    <listitem><para><literal>s3:PutObject</literal></para></listitem>
-    <listitem><para><literal>s3:ListBucketMultipartUploads</literal></para></listitem>
-    <listitem><para><literal>s3:CreateMultipartUpload</literal></para></listitem>
-    <listitem><para><literal>s3:ListMultipartUploadParts</literal></para></listitem>
-    <listitem><para><literal>s3:AbortMultipartUpload</literal></para></listitem>
-  </itemizedlist>
 </section>
 </section>
--- a/doc/manual/release-notes/rl-2.1.xml
+++ b/doc/manual/release-notes/rl-2.1.xml
@@ -4,7 +4,7 @@
      version="5.0"
      xml:id="ssec-relnotes-2.1">

-<title>Release 2.1 (2018-08-??)</title>
+<title>Release 2.1 (2018-09-02)</title>

 <para>This is primarily a bug fix release. It also reduces memory
 consumption in certain situations. In addition, it has the following
@@ -12,6 +12,29 @@ new features:</para>

 <itemizedlist>

+  <listitem>
+    <para>The Nix installer will no longer default to the Multi-User
+    installation for macOS. You can still <link
+    linkend="sect-multi-user-installation">instruct the installer to
+    run in multi-user mode</link>.
+    </para>
+  </listitem>
+
+  <listitem>
+    <para>The Nix installer now supports performing a Multi-User
+    installation for Linux computers which are running systemd. You
+    can <link
+    linkend="sect-multi-user-installation">select a Multi-User installation</link> by passing the
+    <option>--daemon</option> flag to the installer: <command>sh &lt;(curl
+    https://nixos.org/nix/install) --daemon</command>.
+    </para>
+
+    <para>The multi-user installer cannot handle systems with SELinux.
+    If your system has SELinux enabled, you can <link
+    linkend="sect-single-user-installation">force the installer to run
+    in single-user mode</link>.</para>
+  </listitem>
+
  <listitem>
    <para>New builtin functions:
    <literal>builtins.bitAnd</literal>,
@@ -41,13 +64,70 @@ new features:</para>

  <listitem>
    <para><command>nix-daemon</command> now respects
-    <option>--store</option>, so it can be run as a non-root
-    user.</para>
+    <option>--store</option>.</para>
+  </listitem>
+
+  <listitem>
+    <para><command>nix run</command> now respects
+    <varname>nix-support/propagated-user-env-packages</varname>.</para>
  </listitem>

 </itemizedlist>

-<para>This release has contributions from TODO.
+<para>This release has contributions from
+
+Adrien Devresse,
+Aleksandr Pashkov,
+Alexandre Esteves,
+Amine Chikhaoui,
+Andrew Dunham,
+Asad Saeeduddin,
+aszlig,
+Ben Challenor,
+Ben Gamari,
+Benjamin Hipple,
+Bogdan Seniuc,
+Corey O'Connor,
+Daiderd Jordan,
+Daniel Peebles,
+Daniel Poelzleithner,
+Danylo Hlynskyi,
+Dmitry Kalinkin,
+Domen Kožar,
+Doug Beardsley,
+Eelco Dolstra,
+Erik Arvstedt,
+Félix Baylac-Jacqué,
+Gleb Peregud,
+Graham Christensen,
+Guillaume Maudoux,
+Ivan Kozik,
+John Arnold,
+Justin Humm,
+Linus Heckemann,
+Lorenzo Manacorda,
+Matthew Justin Bauer,
+Matthew O'Gorman,
+Maximilian Bosch,
+Michael Bishop,
+Michael Fiano,
+Michael Mercier,
+Michael Raskin,
+Michael Weiss,
+Nicolas Dudebout,
+Peter Simons,
+Ryan Trinkle,
+Samuel Dionne-Riel,
+Sean Seefried,
+Shea Levy,
+Symphorien Gibol,
+Tim Engler,
+Tim Sears,
+Tuomas Tynkkynen,
+volth,
+Will Dietz,
+Yorick van Pelt and
+zimbatm.
 </para>

 </section>
--- a/release-common.nix
+++ b/release-common.nix
@@ -30,7 +30,7 @@ rec {
  });

  configureFlags =
-    [ "--disable-init-state"
+    [
      "--enable-gc"
    ] ++ lib.optionals stdenv.isLinux [
      "--with-sandbox-shell=${sh}/bin/busybox"
--- a/release.nix
+++ b/release.nix
@@ -67,6 +67,14 @@ let

        buildInputs = buildDeps;

+        preConfigure =
+          # Copy libboost_context so we don't get all of Boost in our closure.
+          # https://github.com/NixOS/nixpkgs/issues/45462
+          ''
+            mkdir -p $out/lib
+            cp ${boost}/lib/libboost_context* $out/lib
+          '';
+
        configureFlags = configureFlags ++
          [ "--sysconfdir=/etc" ];

@@ -74,8 +82,6 @@ let

        makeFlags = "profiledir=$(out)/etc/profile.d";

-        preBuild = "unset NIX_INDENT_MAKE";
-
        installFlags = "sysconfdir=$(out)/etc";

        doInstallCheck = true;
@@ -103,8 +109,6 @@ let
        enableParallelBuilding = true;

        postUnpack = "sourceRoot=$sourceRoot/perl";
-
-        preBuild = "unset NIX_INDENT_MAKE";
      });


@@ -189,10 +193,6 @@ let

        buildInputs = buildDeps;

-        configureFlags = ''
-          --disable-init-state
-        '';
-
        dontInstall = false;

        doInstallCheck = true;
@@ -241,6 +241,7 @@ let
        { diskImage = vmTools.diskImages.ubuntu1204x86_64;
        }
        ''
+          set -x
          useradd -m alice
          su - alice -c 'tar xf ${binaryTarball.x86_64-linux}/*.tar.*'
          mkdir /dest-nix
@@ -249,6 +250,17 @@ let
          su - alice -c '_NIX_INSTALLER_TEST=1 ./nix-*/install'
          su - alice -c 'nix-store --verify'
          su - alice -c 'PAGER= nix-store -qR ${build.x86_64-linux}'
+
+          # Check whether 'nix upgrade-nix' works.
+          cat > /tmp/paths.nix <<EOF
+          {
+            x86_64-linux = "${build.x86_64-linux}";
+          }
+          EOF
+          su - alice -c 'nix upgrade-nix -vvv --nix-store-paths-url file:///tmp/paths.nix'
+          (! [ -L /home/alice/.profile-1-link ])
+          su - alice -c 'PAGER= nix-store -qR ${build.x86_64-linux}'
+
          mkdir -p $out/nix-support
          touch $out/nix-support/hydra-build-products
          umount /nix
--- a/scripts/install-nix-from-closure.sh
+++ b/scripts/install-nix-from-closure.sh
@@ -30,15 +30,14 @@ if [ "$(uname -s)" = "Darwin" ]; then
    fi
 fi

-# Determine if we should punt to the single-user installer or not
+# Determine if we could use the multi-user installer or not
 if [ "$(uname -s)" = "Darwin" ]; then
-    INSTALL_MODE=daemon
+    echo "Note: a multi-user installation is possible. See https://nixos.org/nix/manual/#sect-multi-user-installation" >&2
 elif [ "$(uname -s)" = "Linux" ] && [ -e /run/systemd/system ]; then
-    INSTALL_MODE=daemon
-else
-    INSTALL_MODE=no-daemon
+    echo "Note: a multi-user installation is possible. See https://nixos.org/nix/manual/#sect-multi-user-installation" >&2
 fi

+INSTALL_MODE=no-daemon
 # Trivially handle the --daemon / --no-daemon options
 if [ "x${1:-}" = "x--no-daemon" ]; then
    INSTALL_MODE=no-daemon
@@ -47,14 +46,18 @@ elif [ "x${1:-}" = "x--daemon" ]; then
 elif [ "x${1:-}" != "x" ]; then
    (
        echo "Nix Installer [--daemon|--no-daemon]"
+
+        echo "Choose installation method."
        echo ""
-        echo " --daemon:    Force the installer to use the Daemon"
-        echo "              based installer, even though it may not"
-        echo "              work."
+        echo " --daemon:    Installs and configures a background daemon that manages the store,"
+        echo "              providing multi-user support and better isolation for local builds."
+        echo "              Both for security and reproducibility, this method is recommended if"
+        echo "              supported on your platform."
+        echo "              See https://nixos.org/nix/manual/#sect-multi-user-installation"
        echo ""
-        echo " --no-daemon: Force a no-daemon, single-user"
-        echo "              installation even when the preferred"
-        echo "              method is with the daemon."
+        echo " --no-daemon: Simple, single-user installation that does not require root and is"
+        echo "              trivial to uninstall."
+        echo "              (default)"
        echo ""
    ) >&2
    exit
--- a/scripts/nix-profile-daemon.sh.in
+++ b/scripts/nix-profile-daemon.sh.in
@@ -68,4 +68,4 @@ elif [ -e "/nix/var/nix/profiles/default/etc/ssl/certs/ca-bundle.crt" ]; then #
 fi

 export NIX_PATH="nixpkgs=@localstatedir@/nix/profiles/per-user/root/channels/nixpkgs:@localstatedir@/nix/profiles/per-user/root/channels"
-export PATH="$HOME/.nix-profile/bin:$HOME/.nix-profile/lib/kde4/libexec:@localstatedir@/nix/profiles/default/bin:@localstatedir@/nix/profiles/default:@localstatedir@/nix/profiles/default/lib/kde4/libexec:$PATH"
+export PATH="$HOME/.nix-profile/bin:@localstatedir@/nix/profiles/default/bin:$PATH"
--- a/src/libexpr/local.mk
+++ b/src/libexpr/local.mk
@@ -20,14 +20,10 @@ libexpr_LDFLAGS_PROPAGATED = $(BDW_GC_LIBS)

 libexpr_ORDER_AFTER := $(d)/parser-tab.cc $(d)/parser-tab.hh $(d)/lexer-tab.cc $(d)/lexer-tab.hh

-$(d)/parser-tab.hh: $(d)/parser-tab.cc
-
-$(d)/parser-tab.cc: $(d)/parser.y
+$(d)/parser-tab.cc $(d)/parser-tab.hh: $(d)/parser.y
 	$(trace-gen) bison -v -o $(libexpr_DIR)/parser-tab.cc $< -d

-$(d)/lexer-tab.hh: $(d)/lexer-tab.cc
-
-$(d)/lexer-tab.cc: $(d)/lexer.l
+$(d)/lexer-tab.cc $(d)/lexer-tab.hh: $(d)/lexer.l
 	$(trace-gen) flex --outfile $(libexpr_DIR)/lexer-tab.cc --header-file=$(libexpr_DIR)/lexer-tab.hh $<

 clean-files += $(d)/parser-tab.cc $(d)/parser-tab.hh $(d)/lexer-tab.cc $(d)/lexer-tab.hh
--- a/src/libexpr/primops/fetchGit.cc
+++ b/src/libexpr/primops/fetchGit.cc
@@ -219,8 +219,6 @@ static void prim_fetchGit(EvalState & state, const Pos & pos, Value * * args, Va
    } else
        url = state.coerceToString(pos, *args[0], context, false, false);

-    if (!isUri(url)) url = absPath(url);
-
    // FIXME: git externals probably can be used to bypass the URI
    // whitelist. Ah well.
    state.checkURI(url);
--- a/src/libexpr/primops/fetchMercurial.cc
+++ b/src/libexpr/primops/fetchMercurial.cc
@@ -184,8 +184,6 @@ static void prim_fetchMercurial(EvalState & state, const Pos & pos, Value * * ar
    } else
        url = state.coerceToString(pos, *args[0], context, false, false);

-    if (!isUri(url)) url = absPath(url);
-
    // FIXME: git externals probably can be used to bypass the URI
    // whitelist. Ah well.
    state.checkURI(url);
--- a/src/libstore/build.cc
+++ b/src/libstore/build.cc
@@ -3682,6 +3682,19 @@ void SubstitutionGoal::tryNext()
    } catch (InvalidPath &) {
        tryNext();
        return;
+    } catch (SubstituterDisabled &) {
+        if (settings.tryFallback) {
+            tryNext();
+            return;
+        }
+        throw;
+    } catch (Error & e) {
+        if (settings.tryFallback) {
+            printError(e.what());
+            tryNext();
+            return;
+        }
+        throw;
    }

    /* Update the total expected download size. */
--- a/src/libstore/builtins/fetchurl.cc
+++ b/src/libstore/builtins/fetchurl.cc
@@ -24,6 +24,7 @@ void builtinFetchurl(const BasicDerivation & drv, const std::string & netrcData)

    Path storePath = getAttr("out");
    auto mainUrl = getAttr("url");
+    bool unpack = get(drv.env, "unpack", "") == "1";

    /* Note: have to use a fresh downloader here because we're in
       a forked process. */
@@ -40,12 +41,12 @@ void builtinFetchurl(const BasicDerivation & drv, const std::string & netrcData)
            request.decompress = false;

            auto decompressor = makeDecompressionSink(
-                hasSuffix(mainUrl, ".xz") ? "xz" : "none", sink);
+                unpack && hasSuffix(mainUrl, ".xz") ? "xz" : "none", sink);
            downloader->download(std::move(request), *decompressor);
            decompressor->finish();
        });

-        if (get(drv.env, "unpack", "") == "1")
+        if (unpack)
            restorePath(storePath, *source);
        else
            writeFile(storePath, *source);
--- a/src/libstore/download.cc
+++ b/src/libstore/download.cc
@@ -345,7 +345,7 @@ struct CurlDownloader : public Downloader
                done = true;

                try {
-                    act.progress(result.data->size(), result.data->size());
+                    act.progress(result.bodySize, result.bodySize);
                    callback(std::move(result));
                } catch (...) {
                    done = true;
@@ -710,11 +710,12 @@ void Downloader::download(DownloadRequest && request, Sink & sink)

        /* If the buffer is full, then go to sleep until the calling
           thread wakes us up (i.e. when it has removed data from the
-           buffer). Note: this does stall the download thread. */
-        while (state->data.size() > 1024 * 1024) {
-            if (state->quit) return;
+           buffer). We don't wait forever to prevent stalling the
+           download thread. (Hopefully sleeping will throttle the
+           sender.) */
+        if (state->data.size() > 1024 * 1024) {
            debug("download buffer is full; going to sleep");
-            state.wait(state->request);
+            state.wait_for(state->request, std::chrono::seconds(10));
        }

        /* Append data to the buffer and wake up the calling
@@ -736,30 +737,36 @@ void Downloader::download(DownloadRequest && request, Sink & sink)
            state->request.notify_one();
        }});

-    auto state(_state->lock());
-
    while (true) {
        checkInterrupt();

-        /* If no data is available, then wait for the download thread
-           to wake us up. */
-        if (state->data.empty()) {
+        std::string chunk;

-            if (state->quit) {
-                if (state->exc) std::rethrow_exception(state->exc);
-                break;
+        /* Grab data if available, otherwise wait for the download
+           thread to wake us up. */
+        {
+            auto state(_state->lock());
+
+            while (state->data.empty()) {
+
+                if (state->quit) {
+                    if (state->exc) std::rethrow_exception(state->exc);
+                    return;
+                }
+
+                state.wait(state->avail);
            }

-            state.wait(state->avail);
-        }
+            chunk = std::move(state->data);

-        /* If data is available, then flush it to the sink and wake up
-           the download thread if it's blocked on a full buffer. */
-        if (!state->data.empty()) {
-            sink((unsigned char *) state->data.data(), state->data.size());
-            state->data.clear();
            state->request.notify_one();
        }
+
+        /* Flush the data to the sink and wake up the download thread
+           if it's blocked on a full buffer. We don't hold the state
+           lock while doing this to prevent blocking the download
+           thread if sink() takes a long time. */
+        sink((unsigned char *) chunk.data(), chunk.size());
    }
 }

--- a/src/libstore/http-binary-cache-store.cc
+++ b/src/libstore/http-binary-cache-store.cc
@@ -13,6 +13,14 @@ private:

    Path cacheUri;

+    struct State
+    {
+        bool enabled = true;
+        std::chrono::steady_clock::time_point disabledUntil;
+    };
+
+    Sync<State> _state;
+
 public:

    HttpBinaryCacheStore(
@@ -46,8 +54,33 @@ public:

 protected:

+    void maybeDisable()
+    {
+        auto state(_state.lock());
+        if (state->enabled && settings.tryFallback) {
+            int t = 60;
+            printError("disabling binary cache '%s' for %s seconds", getUri(), t);
+            state->enabled = false;
+            state->disabledUntil = std::chrono::steady_clock::now() + std::chrono::seconds(t);
+        }
+    }
+
+    void checkEnabled()
+    {
+        auto state(_state.lock());
+        if (state->enabled) return;
+        if (std::chrono::steady_clock::now() > state->disabledUntil) {
+            state->enabled = true;
+            debug("re-enabling binary cache '%s'", getUri());
+            return;
+        }
+        throw SubstituterDisabled("substituter '%s' is disabled", getUri());
+    }
+
    bool fileExists(const std::string & path) override
    {
+        checkEnabled();
+
        try {
            DownloadRequest request(cacheUri + "/" + path);
            request.head = true;
@@ -59,6 +92,7 @@ protected:
               bucket is unlistable, so treat 403 as 404. */
            if (e.error == Downloader::NotFound || e.error == Downloader::Forbidden)
                return false;
+            maybeDisable();
            throw;
        }
    }
@@ -86,12 +120,14 @@ protected:

    void getFile(const std::string & path, Sink & sink) override
    {
+        checkEnabled();
        auto request(makeRequest(path));
        try {
            getDownloader()->download(std::move(request), sink);
        } catch (DownloadError & e) {
            if (e.error == Downloader::NotFound || e.error == Downloader::Forbidden)
                throw NoSuchBinaryCacheFile("file '%s' does not exist in binary cache '%s'", path, getUri());
+            maybeDisable();
            throw;
        }
    }
@@ -99,15 +135,18 @@ protected:
    void getFile(const std::string & path,
        Callback<std::shared_ptr<std::string>> callback) override
    {
+        checkEnabled();
+
        auto request(makeRequest(path));

        getDownloader()->enqueueDownload(request,
-            {[callback](std::future<DownloadResult> result) {
+            {[callback, this](std::future<DownloadResult> result) {
                try {
                    callback(result.get().data);
                } catch (DownloadError & e) {
                    if (e.error == Downloader::NotFound || e.error == Downloader::Forbidden)
                        return callback(std::shared_ptr<std::string>());
+                    maybeDisable();
                    callback.rethrow();
                } catch (...) {
                    callback.rethrow();
--- a/src/libstore/legacy-ssh-store.cc
+++ b/src/libstore/legacy-ssh-store.cc
@@ -131,7 +131,7 @@ struct LegacySSHStore : public Store

        auto conn(connections->get());

-        if (GET_PROTOCOL_MINOR(conn->remoteVersion) >= 4) {
+        if (GET_PROTOCOL_MINOR(conn->remoteVersion) >= 5) {

            conn->to
                << cmdAddToStoreNar
--- a/src/libstore/local-store.cc
+++ b/src/libstore/local-store.cc
@@ -880,6 +880,12 @@ void LocalStore::querySubstitutablePathInfos(const PathSet & paths,
                    narInfo ? narInfo->fileSize : 0,
                    info->narSize};
            } catch (InvalidPath) {
+            } catch (SubstituterDisabled) {
+            } catch (Error & e) {
+                if (settings.tryFallback)
+                    printError(e.what());
+                else
+                    throw;
            }
        }
    }
--- a/src/libstore/store-api.hh
+++ b/src/libstore/store-api.hh
@@ -23,6 +23,7 @@ MakeError(BuildError, Error) /* denotes a permanent build failure */
 MakeError(InvalidPath, Error)
 MakeError(Unsupported, Error)
 MakeError(SubstituteGone, Error)
+MakeError(SubstituterDisabled, Error)


 struct BasicDerivation;
--- a/src/libutil/archive.cc
+++ b/src/libutil/archive.cc
@@ -283,7 +283,7 @@ void parseDump(ParseSink & sink, Source & source)
 {
    string version;
    try {
-        version = readString(source);
+        version = readString(source, narVersionMagic1.size());
    } catch (SerialisationError & e) {
        /* This generally means the integer at the start couldn't be
           decoded.  Ignore and throw the exception below. */
--- a/src/libutil/compression.cc
+++ b/src/libutil/compression.cc
@@ -250,7 +250,7 @@ struct XzCompressionSink : CompressionSink
            ret = lzma_stream_encoder_mt(&strm, &mt_options);
            done = true;
 #else
-            printMsg(lvlError, "warning: parallel compression requested but not supported for metho  d '%1%', falling back to single-threaded compression", method);
+            printMsg(lvlError, "warning: parallel XZ compression requested but not supported, falling back to single-threaded compression");
 #endif
        }

--- a/src/libutil/serialise.cc
+++ b/src/libutil/serialise.cc
@@ -169,17 +169,13 @@ std::unique_ptr<Source> sinkToSource(
    {
        typedef boost::coroutines2::coroutine<std::string> coro_t;

+        std::function<void(Sink &)> fun;
        std::function<void()> eof;
-        coro_t::pull_type coro;
+        std::experimental::optional<coro_t::pull_type> coro;
+        bool started = false;

        SinkToSource(std::function<void(Sink &)> fun, std::function<void()> eof)
-            : eof(eof)
-            , coro([&](coro_t::push_type & yield) {
-                LambdaSink sink([&](const unsigned char * data, size_t len) {
-                    if (len) yield(std::string((const char *) data, len));
-                });
-                fun(sink);
-            })
+            : fun(fun), eof(eof)
        {
        }

@@ -188,11 +184,19 @@ std::unique_ptr<Source> sinkToSource(

        size_t read(unsigned char * data, size_t len) override
        {
-            if (!coro) { eof(); abort(); }
+            if (!coro)
+                coro = coro_t::pull_type([&](coro_t::push_type & yield) {
+                    LambdaSink sink([&](const unsigned char * data, size_t len) {
+                            if (len) yield(std::string((const char *) data, len));
+                        });
+                    fun(sink);
+                });
+
+            if (!*coro) { eof(); abort(); }

            if (pos == cur.size()) {
-                if (!cur.empty()) coro();
-                cur = coro.get();
+                if (!cur.empty()) (*coro)();
+                cur = coro->get();
                pos = 0;
            }

@@ -268,16 +272,17 @@ void readPadding(size_t len, Source & source)
 size_t readString(unsigned char * buf, size_t max, Source & source)
 {
    auto len = readNum<size_t>(source);
-    if (len > max) throw Error("string is too long");
+    if (len > max) throw SerialisationError("string is too long");
    source(buf, len);
    readPadding(len, source);
    return len;
 }


-string readString(Source & source)
+string readString(Source & source, size_t max)
 {
    auto len = readNum<size_t>(source);
+    if (len > max) throw SerialisationError("string is too long");
    std::string res(len, 0);
    source((unsigned char*) res.data(), len);
    readPadding(len, source);
--- a/src/libutil/serialise.hh
+++ b/src/libutil/serialise.hh
@@ -284,7 +284,7 @@ inline uint64_t readLongLong(Source & source)

 void readPadding(size_t len, Source & source);
 size_t readString(unsigned char * buf, size_t max, Source & source);
-string readString(Source & source);
+string readString(Source & source, size_t max = std::numeric_limits<size_t>::max());
 template<class T> T readStrings(Source & source);

 Source & operator >> (Source & in, string & s);
--- a/src/nix-build/nix-build.cc
+++ b/src/nix-build/nix-build.cc
@@ -305,6 +305,8 @@ void mainWrapped(int argc, char * * argv)
        }
    }

+    state->printStats();
+
    auto buildPaths = [&](const PathSet & paths) {
        /* Note: we do this even when !printMissing to efficiently
           fetch binary cache data. */
@@ -419,7 +421,6 @@ void mainWrapped(int argc, char * * argv)
                R"s([ -n "$PS1" ] && PS1='\n\[\033[1;32m\][nix-shell:\w]\$\[\033[0m\] '; )s"
                "if [ \"$(type -t runHook)\" = function ]; then runHook shellHook; fi; "
                "unset NIX_ENFORCE_PURITY; "
-                "unset NIX_INDENT_MAKE; "
                "shopt -u nullglob; "
                "unset TZ; %4%"
                "%5%",
--- a/src/nix-env/nix-env.cc
+++ b/src/nix-env/nix-env.cc
@@ -150,10 +150,8 @@ static void loadSourceExpr(EvalState & state, const Path & path, Value & v)
    if (stat(path.c_str(), &st) == -1)
        throw SysError(format("getting information about '%1%'") % path);

-    if (isNixExpr(path, st)) {
+    if (isNixExpr(path, st))
        state.evalFile(path, v);
-        return;
-    }

    /* The path is a directory.  Put the Nix expressions in the
       directory in a set, with the file name of each expression as
@@ -161,13 +159,15 @@ static void loadSourceExpr(EvalState & state, const Path & path, Value & v)
       set flat, not nested, to make it easier for a user to have a
       ~/.nix-defexpr directory that includes some system-wide
       directory). */
-    if (S_ISDIR(st.st_mode)) {
+    else if (S_ISDIR(st.st_mode)) {
        state.mkAttrs(v, 1024);
        state.mkList(*state.allocAttr(v, state.symbols.create("_combineChannels")), 0);
        StringSet attrs;
        getAllExprs(state, path, attrs, v);
        v.attrs->sort();
    }
+
+    else throw Error("path '%s' is not a directory or a Nix expression", path);
 }


--- a/src/nix/main.cc
+++ b/src/nix/main.cc
@@ -24,7 +24,6 @@ struct NixArgs : virtual MultiCommand, virtual MixCommonArgs
    {
        mkFlag()
            .longName("help")
-            .shortName('h')
            .description("show usage information")
            .handler([&]() { showHelpAndExit(); });

--- a/src/nix/path-info.cc
+++ b/src/nix/path-info.cc
@@ -78,7 +78,10 @@ struct CmdPathInfo : StorePathsCommand, MixJSON
                auto info = store->queryPathInfo(storePath);
                storePath = info->path; // FIXME: screws up padding

-                std::cout << storePath << std::string(std::max(0, (int) pathLen - (int) storePath.size()), ' ');
+                std::cout << storePath;
+
+                if (showSize || showClosureSize || showSigs)
+                    std::cout << std::string(std::max(0, (int) pathLen - (int) storePath.size()), ' ');

                if (showSize)
                    std::cout << '\t' << std::setw(11) << info->narSize;
--- a/src/nix/repl.cc
+++ b/src/nix/repl.cc
@@ -173,9 +173,14 @@ void NixRepl::mainLoop(const std::vector<std::string> & files)
            printMsg(lvlError, format(error + "%1%%2%") % (settings.showTrace ? e.prefix() : "") % e.msg());
        }

+        if (input.size() > 0) {
+            // Remove trailing newline before adding to history
+            input.erase(input.size() - 1);
+            linenoiseHistoryAdd(input.c_str());
+        }
+
        // We handled the current input fully, so we should clear it
        // and read brand new input.
-        linenoiseHistoryAdd(input.c_str());
        input.clear();
        std::cout << std::endl;
    }
--- a/src/nix/upgrade-nix.cc
+++ b/src/nix/upgrade-nix.cc
@@ -1,14 +1,18 @@
 #include "command.hh"
+#include "common-args.hh"
 #include "store-api.hh"
 #include "download.hh"
 #include "eval.hh"
 #include "attr-path.hh"
+#include "names.hh"
+#include "progress-bar.hh"

 using namespace nix;

-struct CmdUpgradeNix : StoreCommand
+struct CmdUpgradeNix : MixDryRun, StoreCommand
 {
    Path profileDir;
+    std::string storePathsUrl = "https://github.com/NixOS/nixpkgs/raw/master/nixos/modules/installer/tools/nix-fallback-paths.nix";

    CmdUpgradeNix()
    {
@@ -18,6 +22,12 @@ struct CmdUpgradeNix : StoreCommand
            .labels({"profile-dir"})
            .description("the Nix profile to upgrade")
            .dest(&profileDir);
+
+        mkFlag()
+            .longName("nix-store-paths-url")
+            .labels({"url"})
+            .description("URL of the file that contains the store paths of the latest Nix release")
+            .dest(&storePathsUrl);
    }

    std::string name() override
@@ -59,6 +69,14 @@ struct CmdUpgradeNix : StoreCommand
            storePath = getLatestNix(store);
        }

+        auto version = DrvName(storePathToName(storePath)).version;
+
+        if (dryRun) {
+            stopProgressBar();
+            printError("would upgrade to version %s", version);
+            return;
+        }
+
        {
            Activity act(*logger, lvlInfo, actUnknown, fmt("downloading '%s'...", storePath));
            store->ensurePath(storePath);
@@ -72,11 +90,15 @@ struct CmdUpgradeNix : StoreCommand
                throw Error("could not verify that '%s' works", program);
        }

+        stopProgressBar();
+
        {
            Activity act(*logger, lvlInfo, actUnknown, fmt("installing '%s' into profile '%s'...", storePath, profileDir));
            runProgram(settings.nixBinDir + "/nix-env", false,
                {"--profile", profileDir, "-i", storePath, "--no-sandbox"});
        }
+
+        printError(ANSI_GREEN "upgrade to version %s done" ANSI_NORMAL, version);
    }

    /* Return the profile in which Nix is installed. */
@@ -98,11 +120,18 @@ struct CmdUpgradeNix : StoreCommand
        if (hasPrefix(where, "/run/current-system"))
            throw Error("Nix on NixOS must be upgraded via 'nixos-rebuild'");

-        Path profileDir;
-        Path userEnv;
+        Path profileDir = dirOf(where);
+
+        // Resolve profile to /nix/var/nix/profiles/<name> link.
+        while (canonPath(profileDir).find("/profiles/") == std::string::npos && isLink(profileDir))
+            profileDir = readLink(profileDir);
+
+        printInfo("found profile '%s'", profileDir);
+
+        Path userEnv = canonPath(profileDir, true);

        if (baseNameOf(where) != "bin" ||
-            !hasSuffix(userEnv = canonPath(profileDir = dirOf(where), true), "user-environment"))
+            !hasSuffix(userEnv, "user-environment"))
            throw Error("directory '%s' does not appear to be part of a Nix profile", where);

        if (!store->isValidPath(userEnv))
@@ -115,7 +144,7 @@ struct CmdUpgradeNix : StoreCommand
    Path getLatestNix(ref<Store> store)
    {
        // FIXME: use nixos.org?
-        auto req = DownloadRequest("https://github.com/NixOS/nixpkgs/raw/master/nixos/modules/installer/tools/nix-fallback-paths.nix");
+        auto req = DownloadRequest(storePathsUrl);
        auto res = getDownloader()->download(req);

        auto state = std::make_unique<EvalState>(Strings(), store);
--- a/2
+++ b/2
@@ -1 +1 @@
-2.1
+2.1.4
Author	SHA1	Message	Date
Eelco Dolstra	b0e20cbabf	Bump version	2018-10-02 17:04:33 +02:00
Profpatsch	5438e889be	manual: add XML IDs to all builtin list entries (cherry picked from commit `05cfc71cab`)	2018-10-02 17:04:06 +02:00
Matthew Bauer	9011a85ef6	nix-profile-daemon: remove cruft This removes part of the PATH that were being added automatically in multi-user installs: - $HOME/.nix-profile/lib/kde4/libexec - shouldn't be needed anymore, we are now using kde5 - @localstatedir@/nix/profiles/default/lib/kde4/libexec - same as above - @localstatedir@/nix/profiles/default - shouldn't ever contain binaries (cherry picked from commit `9cc876fb11`)	2018-10-01 22:51:23 +02:00
Graham Christensen	1c99c1ba43	Update docs to describe how s3:// URLS does in fact support endpoint, region, and profile for upload (cherry picked from commit `51cbeec49a`)	2018-10-01 22:49:46 +02:00
Eelco Dolstra	96e03a39ec	Ensure download thread liveness * Don't wait forever for the client to remove data from the buffer. This does mean that the buffer can grow without bounds (e.g. when downloading is faster than writing to disk), but meh. * Don't hold the state lock while calling the sink. The sink could take any amount of time to process the data (in particular when it's actually a coroutine), so we don't want to block the download thread. (cherry picked from commit `9750430003`)	2018-10-01 22:49:06 +02:00
Eelco Dolstra	51d11e9e0d	sinkToSource(): Start the coroutine lazily In particular this causes copyStorePath() from HttpBinaryCacheStore to only start a download if needed. E.g. if the destination LocalStore goes to sleep waiting for the path lock and another process creates the path, then LocalStore::addToStore() will never read from the source so we don't have to do the download. (cherry picked from commit `ed78582847`)	2018-10-01 22:48:53 +02:00
Eelco Dolstra	87ad88f28d	Make NAR header check more robust Changes std::bad_alloc into bad archive: input doesn't look like a Nix archive (cherry picked from commit `44e86304b6`)	2018-10-01 22:48:53 +02:00
Eelco Dolstra	373cc12d63	Bump version	2018-10-01 22:47:47 +02:00
Eelco Dolstra	fa37d03b3c	Fix build failure if parallel xz is not available (cherry picked from commit `901dfc7978`)	2018-09-19 22:25:44 +02:00
Eelco Dolstra	099951945e	If fallback is enabled, temporarily disable substituters after a failure Otherwise, we just keep asking the substituter for other .narinfo files, which can take a very long time due to retries/timeouts. (cherry picked from commit `bba3f0a308`)	2018-09-19 22:25:32 +02:00
Will Dietz	3f20275fa0	download: fix size reported to progress bar (cherry picked from commit `28418af920`)	2018-09-19 22:25:16 +02:00
Eelco Dolstra	c0c0c6b7cd	Handle queryPathInfo() failure from substituters when fallback is enabled Fixes #1990. (cherry picked from commit `33c3f91885`)	2018-09-19 22:25:01 +02:00
Vladimír Čunát	4d0929a096	docs: change expired bzip2.org to archive.org Fixes #2396. (cherry picked from commit `5f3b72cfc2`)	2018-09-19 22:24:08 +02:00
Eelco Dolstra	30b8ecf8f9	nix-env: Fix segfault if -f argument is not a directory or a Nix expression Fixes #2425. (cherry picked from commit `52f6d541b9`)	2018-09-19 22:23:52 +02:00
Graham Christensen	74b612e70a	nix-shell: document double quotes being necessary for a simple Nix expression in the shebang (cherry picked from commit `be9e356e61`)	2018-09-19 22:23:26 +02:00
Graham Christensen	cae9262a6c	nix-shell: explain the merging property close to the example (cherry picked from commit `10a7f19937`)	2018-09-19 22:23:26 +02:00
Graham Christensen	e811aa8d65	docs: document deprecated aliases (cherry picked from commit `0cd863197b`)	2018-09-19 22:23:05 +02:00
Anders Riutta	57ddc6c0e7	Upgrade docs: improve the upgrade command and make it more copy-pastable. (cherry picked from commit `1915862767`)	2018-09-19 22:21:40 +02:00
Eelco Dolstra	f364c91572	Bump version	2018-09-19 22:21:10 +02:00
Eelco Dolstra	f573ea7464	Bump version	2018-09-05 21:24:04 +02:00
Eelco Dolstra	46c8fcca97	fetchurl: Respect unpack Fixes #2393. (cherry picked from commit `2d91012754`)	2018-09-05 21:23:45 +02:00
Eelco Dolstra	b4441c9690	Release notes tweaks (cherry picked from commit `4dd09210d7`)	2018-09-02 21:47:53 +02:00
Graham Christensen	eb40c23dfd	Create upgrade notes (cherry picked from commit `c42eaaf684`)	2018-09-01 23:30:16 +02:00
Graham Christensen	7fe614b5c9	release notes: note that the multi-user installer is available but not selected for Linux with systemd, and the bug about selinux (cherry picked from commit `4be7652dd3`)	2018-09-01 23:30:16 +02:00
Graham Christensen	95ed61c990	Default to single-user install (cherry picked from commit `51f9682a8b`)	2018-09-01 23:30:16 +02:00
Graham Christensen	93cae69725	Document the multi-user installer some Use sh <(...) syntax for installation to preserve stdin and prompting also update installation docs to account for changes in multi-user selection (cherry picked from commit `c3e508d924`)	2018-09-01 23:30:16 +02:00
Graham Christensen	a4a72c0152	We support aarch64 now (cherry picked from commit `f66fa7cd20`)	2018-09-01 23:30:15 +02:00
Graham Christensen	348a2eb84a	nix-build: Print stats even in failing builds (cherry picked from commit `87702532d2`)	2018-09-01 23:30:15 +02:00
Graham Christensen	958e037a08	nix-build: print stats on sucessful builds (cherry picked from commit `b7bb627f67`)	2018-09-01 23:30:15 +02:00
Graham Christensen	75a041c36c	Drop ssh://... as a required formatting for builtins.fetchGit (cherry picked from commit `0b7568fb73`)	2018-09-01 23:29:51 +02:00
Eelco Dolstra	6202ffdce9	fetchGit/fetchMercurial: Don't absolutize paths This is already done by coerceToString(), provided that the argument is a path (e.g. 'fetchGit ./bla'). It fixes the handling of URLs like git@github.com:owner/repo.git. It breaks 'fetchGit "./bla"', but that was never intended to work anyway and is inconsistent with other builtin functions (e.g. 'readFile "./bla"' fails). (cherry picked from commit `475a0a54a9`)	2018-09-01 23:29:51 +02:00
Eelco Dolstra	d2339af44c	nix path-info: Remove trailing spaces Fixes #2390. (cherry picked from commit `b7409c5754`)	2018-09-01 23:29:37 +02:00
Eelco Dolstra	b71789885a	Add contributors (cherry picked from commit `4095cd6438`)	2018-09-01 23:29:37 +02:00
Graham Christensen	165743b8bf	docs: Add IDs to important sections (cherry picked from commit `149d10c308`)	2018-09-01 23:29:37 +02:00
Graham Christensen	81028d5b87	docs: Add some examples to fetchGit (cherry picked from commit `2df21b78b9`)	2018-09-01 23:29:37 +02:00
Graham Christensen	d3088a64db	manual: document why ~/.netrc doesn't work Maybe there is a better place to document this, which is more generic? (cherry picked from commit `33712fed38`)	2018-09-01 23:29:01 +02:00
Niklas Hambüchen	d853b57991	manual: distributed-builds: Mention - as default (cherry picked from commit `10ebcf8670`)	2018-09-01 23:29:01 +02:00
Symphorien Gibol	1d619967ef	add manual entries for disallowedRequisites and disallowedReferences (cherry picked from commit `81d1385437`)	2018-09-01 23:29:01 +02:00
Erik Arvstedt	8115c10e59	Docs: Fix install prefix shell.nix defines the install prefix as $(pwd)/inst (cherry picked from commit `8ad2defdf0`)	2018-08-31 16:12:27 +02:00
Eelco Dolstra	b7a37ab5f2	nix upgrade-nix: Handle .nix-profile being a link to .../profiles/per-user/... Also some cosmetic improvements. (cherry picked from commit `39f1722f36`)	2018-08-31 16:12:11 +02:00
Eelco Dolstra	f8fbab43f2	nix upgrade-nix: Improve error message if 'nix' is not in a profile E.g. $ nix upgrade-nix error: directory '/home/eelco/Dev/nix/inst/bin' does not appear to be part of a Nix profile instead of $ nix upgrade-nix error: '/home/eelco/Dev/nix/inst' is not a symlink (cherry picked from commit `f08b14c9d0`)	2018-08-31 16:12:11 +02:00
Eelco Dolstra	d7b2c6c92f	Add simple test for nix upgrade-nix (cherry picked from commit `264e66f696`)	2018-08-31 16:12:11 +02:00
Michael Bishop	8b0761b172	fix `error: unknown serve command 9` (cherry picked from commit `0767e402f1`)	2018-08-31 16:12:11 +02:00
Daiderd Jordan	2b25ffbd49	upgrade-nix: resolve profile symlinks The profile present in PATH is not necessarily the actual profile location. User profiles are generally added as $HOME/.nix-profile in which case the indirect profile link needs to be resolved first. /home/user/.nix-profile -> /nix/var/nix/profiles/per-user/user/profile /nix/var/nix/profiles/per-user/user/profile -> profile-15-link /nix/var/nix/profiles/per-user/user/profile-14-link -> /nix/store/hyi4kkjh3bwi2z3wfljrkfymz9904h62-user-environment /nix/var/nix/profiles/per-user/user/profile-15-link -> /nix/store/6njpl3qvihz46vj911pwx7hfcvwhifl9-user-environment To upgrade nix here we want /nix/var/nix/profiles/per-user/user/profile-16-link instead of /home/user/.nix-profile-1-link. The latter is not a gcroot and would be garbage collected, resulting in a broken profile. Fixes #2175 (cherry picked from commit `d85bb4814f`)	2018-08-31 16:12:11 +02:00
Daiderd Jordan	88d2e298f5	upgrade-nix: add --dry-run (cherry picked from commit `414397759a`)	2018-08-31 16:12:11 +02:00
Eelco Dolstra	1fceed528d	nix: Remove the -h flag (cherry picked from commit `5e83b0227f`)	2018-08-31 16:11:09 +02:00
Eelco Dolstra	b542267d18	Remove boost from the closure This reduces the size of the closure by 45 MiB. (cherry picked from commit `145db703e5`)	2018-08-31 16:11:09 +02:00
Eelco Dolstra	e76eec86bd	Update release notes (cherry picked from commit `64d7d1a884`)	2018-08-31 16:11:06 +02:00
Eelco Dolstra	25af916eb4	Revert "Fix parser/lexer generation with parallel make" This reverts commit `d277442df5`. Make sucks. (cherry picked from commit `c651b7bdc9`)	2018-08-30 12:48:48 +02:00
Tuomas Tynkkynen	0107a8f6d4	Drop all references to NIX_INDENT_MAKE Dead code since `6669a3b477` (cherry picked from commit `2894197de7`)	2018-08-30 12:48:32 +02:00
Tuomas Tynkkynen	c2dcc102e4	Drop all references to --disable-init-state It's all dead code since 2014 (commit `0c6d62cf27`). (cherry picked from commit `458282be59`)	2018-08-30 12:48:32 +02:00
Ivan Kozik	9280d11e54	repl: don't add trailing spaces to history lines (cherry picked from commit `ec49ea28dc`)	2018-08-30 12:48:28 +02:00
@@ -1 +1 @@
 .1
 .1.4