Restructuring the Nix manual

doc/manual/builds/build-farm.xml

@@ -0,0 +1,22 @@
+<part 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='chap-distributed-builds'>
+
+<title>Distributed Builds</title>
+
+<partintro>
+<para>Nix supports distributed builds, where a local Nix installation can
+forward Nix builds to other machines over the network.  This allows
+multiple builds to be performed in parallel (thus improving
+performance) and allows Nix to perform multi-platform builds in a
+semi-transparent way.  For instance, if you perform a build for a
+<literal>powerpc-darwin</literal> on an <literal>i686-linux</literal>
+machine, Nix can automatically forward the build to a
+<literal>powerpc-darwin</literal> machine, if available.</para>
+</partintro>
+
+<xi:include href="enabling-builds.xml" />
+
+</part>

doc/manual/builds/enabling-builds.xml

@@ -1,17 +1,10 @@
 <chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id='chap-distributed-builds'>
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="ch-enabling-builds">
 
-<title>Setting Up Distributed Builds</title>
+<title>Enabling Distributed Builds</title>
-
-<para>Nix supports distributed builds: a local Nix installation can
-forward Nix builds to other machines over the network.  This allows
-multiple builds to be performed in parallel (thus improving
-performance) and allows Nix to perform multi-platform builds in a
-semi-transparent way.  For instance, if you perform a build for a
-<literal>powerpc-darwin</literal> on an <literal>i686-linux</literal>
-machine, Nix can automatically forward the build to a
-<literal>powerpc-darwin</literal> machine, if available.</para>
 
 <para>You can enable distributed builds by setting the environment
 variable <envar>NIX_BUILD_HOOK</envar> to point to a program that Nix
@@ -109,5 +102,5 @@ load on the remote machine, so if you have multiple instances of Nix
 running, they should use the same <envar>NIX_CURRENT_LOAD</envar>
 file.  Maybe in the future <filename>build-remote.pl</filename> will
 look at the actual remote load.</para>
-  
+
-</chapter>
+</chapter>

doc/manual/command-ref/command-ref.xml

@@ -0,0 +1,20 @@
+<part 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='part-command-ref'>
+
+<title>Command Reference</title>
+
+<partintro>
+<para>This section lists commands and options that you can use when you
+work with Nix.</para>
+</partintro>
+
+<xi:include href="opt-common.xml" />
+<xi:include href="env-common.xml" />
+<xi:include href="main-commands.xml" />
+<xi:include href="utilities.xml" />
+<xi:include href="files.xml" />
+
+</part>

doc/manual/command-ref/env-common.xml

@@ -1,8 +1,10 @@
-<section xmlns="http://docbook.org/ns/docbook"
+<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="sec-common-env">
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-common-env">
 
-<title>Common environment variables</title>
+<title>Common Environment Variables</title>
 
 
 <para>Most Nix commands interpret the following environment variables:</para>
@@ -335,4 +337,4 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
 </variablelist>
 
 
-</section>
+</chapter>

doc/manual/command-ref/files.xml

@@ -0,0 +1,14 @@
+<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-files'>
+
+<title>Files</title>
+
+<para>This section lists configuration files that you can use when you
+work with Nix.</para>
+
+<xi:include href="conf-file.xml" />
+
+</chapter>

doc/manual/command-ref/main-commands.xml

@@ -0,0 +1,17 @@
+<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-main-commands'>
+
+<title>Main Commands</title>
+
+<para>This section lists commands and options that you can use when you
+work with Nix.</para>
+
+<xi:include href="nix-env.xml" />
+<xi:include href="nix-build.xml" />
+<xi:include href="nix-shell.xml" />
+<xi:include href="nix-store.xml" />
+
+</chapter>

doc/manual/command-ref/nix-build.xml

@@ -1,7 +1,8 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-build">
+      version="5.0"
+      xml:id="sec-nix-build">
 
 <refmeta>
   <refentrytitle>nix-build</refentrytitle>

doc/manual/command-ref/nix-channel.xml

@@ -1,7 +1,8 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-channel">
+      version="5.0"
+      xml:id="sec-nix-channel">
   
 <refmeta>
   <refentrytitle>nix-channel</refentrytitle>

doc/manual/command-ref/nix-collect-garbage.xml

@@ -1,7 +1,8 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-collect-garbage">
+      version="5.0"
+      xml:id="sec-nix-collect-garbage">
   
 <refmeta>
   <refentrytitle>nix-collect-garbage</refentrytitle>

doc/manual/command-ref/nix-daemon.xml

@@ -1,7 +1,8 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-daemon">
+      version="5.0"
+      xml:id="sec-nix-daemon">
 
 <refmeta>
   <refentrytitle>nix-daemon</refentrytitle>

doc/manual/command-ref/nix-env.xml

@@ -1,7 +1,8 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-env">
+      version="5.0"
+      xml:id="sec-nix-env">
 
 <refmeta>
   <refentrytitle>nix-env</refentrytitle>

doc/manual/command-ref/nix-hash.xml

@@ -1,7 +1,8 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-hash">
+      version="5.0"
+      xml:id="sec-nix-hash">
   
 <refmeta>
   <refentrytitle>nix-hash</refentrytitle>

doc/manual/command-ref/nix-install-package.xml

@@ -1,7 +1,8 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-install-package">
+      version="5.0"
+      xml:id="sec-nix-install-package">
   
 <refmeta>
   <refentrytitle>nix-install-package</refentrytitle>

doc/manual/command-ref/nix-instantiate.xml

@@ -1,7 +1,8 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-instantiate">
+      version="5.0"
+      xml:id="sec-nix-instantiate">
 
 <refmeta>
   <refentrytitle>nix-instantiate</refentrytitle>

doc/manual/command-ref/nix-prefetch-url.xml

@@ -1,7 +1,8 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-prefetch-url">
+      version="5.0"
+      xml:id="sec-nix-prefetch-url">
   
 <refmeta>
   <refentrytitle>nix-prefetch-url</refentrytitle>

doc/manual/command-ref/nix-pull.xml

@@ -1,7 +1,8 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-pull">
+      version="5.0"
+      xml:id="sec-nix-pull">
 
 <refmeta>
   <refentrytitle>nix-pull</refentrytitle>

doc/manual/command-ref/nix-push.xml

@@ -1,7 +1,8 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-push">
+      version="5.0"
+      xml:id="sec-nix-push">
 
 <refmeta>
   <refentrytitle>nix-push</refentrytitle>

doc/manual/command-ref/nix-shell.xml

@@ -1,7 +1,8 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-shell">
+      version="5.0"
+      xml:id="sec-nix-shell">
 
 <refmeta>
   <refentrytitle>nix-shell</refentrytitle>

doc/manual/command-ref/nix-store.xml

@@ -1,7 +1,8 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-store">
+      version="5.0"
+      xml:id="sec-nix-store">
 
 <refmeta>
   <refentrytitle>nix-store</refentrytitle>

doc/manual/command-ref/opt-common.xml

@@ -1,6 +1,6 @@
-<section xmlns="http://docbook.org/ns/docbook" xml:id="sec-common-options">
+<chapter xmlns="http://docbook.org/ns/docbook" xml:id="sec-common-options">
 
-<title>Common options</title>
+<title>Common Options</title>
 
 
 <para>Most Nix commands accept the following command-line options:</para>
@@ -386,4 +386,4 @@
 </variablelist>
 
 
-</section>
+</chapter>

doc/manual/command-ref/utilities.xml

@@ -0,0 +1,23 @@
+<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-utilities'>
+
+<title>Utilities</title>
+
+<para>This section lists utilities that you can use when you
+work with Nix.</para>
+
+<xi:include href="nix-channel.xml" />
+<xi:include href="nix-collect-garbage.xml" />
+<xi:include href="nix-copy-closure.xml" />
+<xi:include href="nix-daemon.xml" />
+<xi:include href="nix-hash.xml" />
+<xi:include href="nix-install-package.xml" />
+<xi:include href="nix-instantiate.xml" />
+<xi:include href="nix-prefetch-url.xml" />
+<xi:include href="nix-pull.xml" />
+<xi:include href="nix-push.xml" />
+
+</chapter>

doc/manual/expressions/advanced-attributes.xml

@@ -0,0 +1,243 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-advanced-attributes">
+
+<title>Advanced Attributes</title>
+
+<para>Derivations can declare some infrequently used optional
+attributes.</para>
+
+<variablelist>
+
+  <varlistentry><term><varname>allowedReferences</varname></term>
+
+    <listitem><para>The optional attribute
+    <varname>allowedReferences</varname> specifies a list of legal
+    references (dependencies) of the output of the builder.  For
+    example,
+
+<programlisting>
+allowedReferences = [];
+</programlisting>
+
+    enforces that the output of a derivation cannot have any runtime
+    dependencies on its inputs.  To allow an output to have a runtime
+    dependency on itself, use <literal>"out"</literal> as a list item.
+    This is used in NixOS to check that generated files such as
+    initial ramdisks for booting Linux don’t have accidental
+    dependencies on other paths in the Nix store.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><varname>exportReferencesGraph</varname></term>
+
+    <listitem><para>This attribute allows builders access to the
+    references graph of their inputs.  The attribute is a list of
+    inputs in the Nix store whose references graph the builder needs
+    to know.  The value of this attribute should be a list of pairs
+    <literal>[ <replaceable>name1</replaceable>
+    <replaceable>path1</replaceable> <replaceable>name2</replaceable>
+    <replaceable>path2</replaceable> <replaceable>...</replaceable>
+    ]</literal>.  The references graph of each
+    <replaceable>pathN</replaceable> will be stored in a text file
+    <replaceable>nameN</replaceable> in the temporary build directory.
+    The text files have the format used by <command>nix-store
+    --register-validity</command> (with the deriver fields left
+    empty).  For example, when the following derivation is built:
+
+<programlisting>
+derivation {
+  ...
+  exportReferencesGraph = [ "libfoo-graph" libfoo ];
+};
+</programlisting>
+
+    the references graph of <literal>libfoo</literal> is placed in the
+    file <filename>libfoo-graph</filename> in the temporary build
+    directory.</para>
+
+    <para><varname>exportReferencesGraph</varname> is useful for
+    builders that want to do something with the closure of a store
+    path.  Examples include the builders in NixOS that generate the
+    initial ramdisk for booting Linux (a <command>cpio</command>
+    archive containing the closure of the boot script) and the
+    ISO-9660 image for the installation CD (which is populated with a
+    Nix store containing the closure of a bootable NixOS
+    configuration).</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="fixed-output-drvs">
+    <term><varname>outputHash</varname></term>
+    <term><varname>outputHashAlgo</varname></term>
+    <term><varname>outputHashMode</varname></term>
+
+    <listitem><para>These attributes declare that the derivation is a
+    so-called <emphasis>fixed-output derivation</emphasis>, which
+    means that a cryptographic hash of the output is already known in
+    advance.  When the build of a fixed-output derivation finishes,
+    Nix computes the cryptographic hash of the output and compares it
+    to the hash declared with these attributes.  If there is a
+    mismatch, the build fails.</para>
+
+    <para>The rationale for fixed-output derivations is derivations
+    such as those produced by the <function>fetchurl</function>
+    function.  This function downloads a file from a given URL.  To
+    ensure that the downloaded file has not been modified, the caller
+    must also specify a cryptographic hash of the file.  For example,
+
+<programlisting>
+fetchurl {
+  url = http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz;
+  md5 = "70c9ccf9fac07f762c24f2df2290784d";
+}
+</programlisting>
+
+    It sometimes happens that the URL of the file changes, e.g.,
+    because servers are reorganised or no longer available.  We then
+    must update the call to <function>fetchurl</function>, e.g.,
+
+<programlisting>
+fetchurl {
+  url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
+  md5 = "70c9ccf9fac07f762c24f2df2290784d";
+}
+</programlisting>
+
+    If a <function>fetchurl</function> derivation was treated like a
+    normal derivation, the output paths of the derivation and
+    <emphasis>all derivations depending on it</emphasis> would change.
+    For instance, if we were to change the URL of the Glibc source
+    distribution in Nixpkgs (a package on which almost all other
+    packages depend) massive rebuilds would be needed.  This is
+    unfortunate for a change which we know cannot have a real effect
+    as it propagates upwards through the dependency graph.</para>
+
+    <para>For fixed-output derivations, on the other hand, the name of
+    the output path only depends on the <varname>outputHash*</varname>
+    and <varname>name</varname> attributes, while all other attributes
+    are ignored for the purpose of computing the output path.  (The
+    <varname>name</varname> attribute is included because it is part
+    of the path.)</para>
+
+    <para>As an example, here is the (simplified) Nix expression for
+    <varname>fetchurl</varname>:
+
+<programlisting>
+{ stdenv, curl }: # The <command>curl</command> program is used for downloading.
+
+{ url, md5 }:
+
+stdenv.mkDerivation {
+  name = baseNameOf (toString url);
+  builder = ./builder.sh;
+  buildInputs = [ curl ];
+
+  # This is a fixed-output derivation; the output must be a regular
+  # file with MD5 hash <varname>md5</varname>.
+  outputHashMode = "flat";
+  outputHashAlgo = "md5";
+  outputHash = md5;
+
+  inherit url;
+}
+</programlisting>
+
+    </para>
+
+    <para>The <varname>outputHashAlgo</varname> attribute specifies
+    the hash algorithm used to compute the hash.  It can currently be
+    <literal>"md5"</literal>, <literal>"sha1"</literal> or
+    <literal>"sha256"</literal>.</para>
+
+    <para>The <varname>outputHashMode</varname> attribute determines
+    how the hash is computed.  It must be one of the following two
+    values:
+
+    <variablelist>
+
+      <varlistentry><term><literal>"flat"</literal></term>
+
+        <listitem><para>The output must be a non-executable regular
+        file.  If it isn’t, the build fails.  The hash is simply
+        computed over the contents of that file (so it’s equal to what
+        Unix commands like <command>md5sum</command> or
+        <command>sha1sum</command> produce).</para>
+
+        <para>This is the default.</para></listitem>
+
+      </varlistentry>
+
+      <varlistentry><term><literal>"recursive"</literal></term>
+
+        <listitem><para>The hash is computed over the NAR archive dump
+        of the output (i.e., the result of <link
+        linkend="refsec-nix-store-dump"><command>nix-store
+        --dump</command></link>).  In this case, the output can be
+        anything, including a directory tree.</para></listitem>
+
+      </varlistentry>
+
+    </variablelist>
+
+    </para>
+
+    <para>The <varname>outputHash</varname> attribute, finally, must
+    be a string containing the hash in either hexadecimal or base-32
+    notation.  (See the <link
+    linkend="sec-nix-hash"><command>nix-hash</command> command</link>
+    for information about converting to and from base-32
+    notation.)</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><varname>impureEnvVars</varname></term>
+
+    <listitem><para>This attribute allows you to specify a list of
+    environment variables that should be passed from the environment
+    of the calling user to the builder.  Usually, the environment is
+    cleared completely when the builder is executed, but with this
+    attribute you can allow specific environment variables to be
+    passed unmodified.  For example, <function>fetchurl</function> in
+    Nixpkgs has the line
+
+<programlisting>
+impureEnvVars = [ "http_proxy" "https_proxy" <replaceable>...</replaceable> ];
+</programlisting>
+
+    to make it use the proxy server configuration specified by the
+    user in the environment variables <envar>http_proxy</envar> and
+    friends.</para>
+
+    <para>This attribute is only allowed in <link
+    linkend="fixed-output-drvs">fixed-output derivations</link>, where
+    impurities such as these are okay since (the hash of) the output
+    is known in advance.  It is ignored for all other
+    derivations.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><varname>preferLocalBuild</varname></term>
+
+    <listitem><para>If this attribute is set to
+    <literal>true</literal>, it has two effects.  First, the
+    derivation will always be built, not substituted, even if a
+    substitute is available.  Second, if <link
+    linkend="chap-distributed-builds">distributed building is
+    enabled</link>, then, if possible, the derivaton will be built
+    locally instead of forwarded to a remote machine.  This is
+    appropriate for trivial builders where the cost of doing a
+    download or remote build would exceed the cost of building
+    locally.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</section>

doc/manual/expressions/arguments-variables.xml

@@ -0,0 +1,121 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id='sec-arguments'>
+
+<title>Arguments and Variables</title>
+
+<example xml:id='ex-hello-composition'>
+
+<title>Composing GNU Hello
+(<filename>all-packages.nix</filename>)</title>
+<programlisting>
+...
+
+rec { <co xml:id='ex-hello-composition-co-1' />
+
+  hello = import ../applications/misc/hello/ex-1 <co xml:id='ex-hello-composition-co-2' /> { <co xml:id='ex-hello-composition-co-3' />
+    inherit fetchurl stdenv perl;
+  };
+
+  perl = import ../development/interpreters/perl { <co xml:id='ex-hello-composition-co-4' />
+    inherit fetchurl stdenv;
+  };
+
+  fetchurl = import ../build-support/fetchurl {
+    inherit stdenv; ...
+  };
+
+  stdenv = ...;
+
+}
+</programlisting>
+</example>
+
+<para>The Nix expression in <xref linkend='ex-hello-nix' /> is a
+function; it is missing some arguments that have to be filled in
+somewhere.  In the Nix Packages collection this is done in the file
+<filename>pkgs/top-level/all-packages.nix</filename>, where all
+Nix expressions for packages are imported and called with the
+appropriate arguments.  <xref linkend='ex-hello-composition' /> shows
+some fragments of
+<filename>all-packages.nix</filename>.</para>
+
+<calloutlist>
+
+  <callout arearefs='ex-hello-composition-co-1'>
+
+    <para>This file defines a set of attributes, all of which are
+    concrete derivations (i.e., not functions).  In fact, we define a
+    <emphasis>mutually recursive</emphasis> set of attributes.  That
+    is, the attributes can refer to each other.  This is precisely
+    what we want since we want to <quote>plug</quote> the
+    various packages into each other.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-composition-co-2'>
+
+    <para>Here we <emphasis>import</emphasis> the Nix expression for
+    GNU Hello.  The import operation just loads and returns the
+    specified Nix expression. In fact, we could just have put the
+    contents of <xref linkend='ex-hello-nix' /> in
+    <filename>all-packages.nix</filename> at this point.  That
+    would be completely equivalent, but it would make the file rather
+    bulky.</para>
+
+    <para>Note that we refer to
+    <filename>../applications/misc/hello/ex-1</filename>, not
+    <filename>../applications/misc/hello/ex-1/default.nix</filename>.
+    When you try to import a directory, Nix automatically appends
+    <filename>/default.nix</filename> to the file name.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-composition-co-3'>
+
+    <para>This is where the actual composition takes place.  Here we
+    <emphasis>call</emphasis> the function imported from
+    <filename>../applications/misc/hello/ex-1</filename> with a set
+    containing the things that the function expects, namely
+    <varname>fetchurl</varname>, <varname>stdenv</varname>, and
+    <varname>perl</varname>.  We use inherit again to use the
+    attributes defined in the surrounding scope (we could also have
+    written <literal>fetchurl = fetchurl;</literal>, etc.).</para>
+
+    <para>The result of this function call is an actual derivation
+    that can be built by Nix (since when we fill in the arguments of
+    the function, what we get is its body, which is the call to
+    <varname>stdenv.mkDerivation</varname> in <xref
+    linkend='ex-hello-nix' />).</para>
+
+    <note><para>Nixpkgs has a convenience function
+    <function>callPackage</function> that imports and calls a
+    function, filling in any missing arguments by passing the
+    corresponding attribute from the Nixpkgs set, like this:
+
+<programlisting>
+hello = callPackage ../applications/misc/hello/ex-1 { };
+</programlisting>
+
+    If necessary, you can set or override arguments:
+
+<programlisting>
+hello = callPackage ../applications/misc/hello/ex-1 { stdenv = myStdenv; };
+</programlisting>
+
+    </para></note>
+
+  </callout>
+
+  <callout arearefs='ex-hello-composition-co-4'>
+
+    <para>Likewise, we have to instantiate Perl,
+    <varname>fetchurl</varname>, and the standard environment.</para>
+
+  </callout>
+
+</calloutlist>
+
+</section>

doc/manual/expressions/build-script.xml

@@ -0,0 +1,119 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id='sec-build-script'>
+
+<title>Build Script</title>
+
+<example xml:id='ex-hello-builder'><title>Build script for GNU Hello
+(<filename>builder.sh</filename>)</title>
+<programlisting>
+source $stdenv/setup <co xml:id='ex-hello-builder-co-1' />
+
+PATH=$perl/bin:$PATH <co xml:id='ex-hello-builder-co-2' />
+
+tar xvfz $src <co xml:id='ex-hello-builder-co-3' />
+cd hello-*
+./configure --prefix=$out <co xml:id='ex-hello-builder-co-4' />
+make <co xml:id='ex-hello-builder-co-5' />
+make install</programlisting>
+</example>
+
+<para><xref linkend='ex-hello-builder' /> shows the builder referenced
+from Hello's Nix expression (stored in
+<filename>pkgs/applications/misc/hello/ex-1/builder.sh</filename>).
+The builder can actually be made a lot shorter by using the
+<emphasis>generic builder</emphasis> functions provided by
+<varname>stdenv</varname>, but here we write out the build steps to
+elucidate what a builder does.  It performs the following
+steps:</para>
+
+<calloutlist>
+
+  <callout arearefs='ex-hello-builder-co-1'>
+
+    <para>When Nix runs a builder, it initially completely clears the
+    environment (except for the attributes declared in the
+    derivation).  For instance, the <envar>PATH</envar> variable is
+    empty<footnote><para>Actually, it's initialised to
+    <filename>/path-not-set</filename> to prevent Bash from setting it
+    to a default value.</para></footnote>.  This is done to prevent
+    undeclared inputs from being used in the build process.  If for
+    example the <envar>PATH</envar> contained
+    <filename>/usr/bin</filename>, then you might accidentally use
+    <filename>/usr/bin/gcc</filename>.</para>
+
+    <para>So the first step is to set up the environment.  This is
+    done by calling the <filename>setup</filename> script of the
+    standard environment.  The environment variable
+    <envar>stdenv</envar> points to the location of the standard
+    environment being used.  (It wasn't specified explicitly as an
+    attribute in <xref linkend='ex-hello-nix' />, but
+    <varname>mkDerivation</varname> adds it automatically.)</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-builder-co-2'>
+
+    <para>Since Hello needs Perl, we have to make sure that Perl is in
+    the <envar>PATH</envar>.  The <envar>perl</envar> environment
+    variable points to the location of the Perl package (since it
+    was passed in as an attribute to the derivation), so
+    <filename><replaceable>$perl</replaceable>/bin</filename> is the
+    directory containing the Perl interpreter.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-builder-co-3'>
+
+    <para>Now we have to unpack the sources.  The
+    <varname>src</varname> attribute was bound to the result of
+    fetching the Hello source tarball from the network, so the
+    <envar>src</envar> environment variable points to the location in
+    the Nix store to which the tarball was downloaded.  After
+    unpacking, we <command>cd</command> to the resulting source
+    directory.</para>
+
+    <para>The whole build is performed in a temporary directory
+    created in <varname>/tmp</varname>, by the way.  This directory is
+    removed after the builder finishes, so there is no need to clean
+    up the sources afterwards.  Also, the temporary directory is
+    always newly created, so you don't have to worry about files from
+    previous builds interfering with the current build.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-builder-co-4'>
+
+    <para>GNU Hello is a typical Autoconf-based package, so we first
+    have to run its <filename>configure</filename> script.  In Nix
+    every package is stored in a separate location in the Nix store,
+    for instance
+    <filename>/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1</filename>.
+    Nix computes this path by cryptographically hashing all attributes
+    of the derivation.  The path is passed to the builder through the
+    <envar>out</envar> environment variable.  So here we give
+    <filename>configure</filename> the parameter
+    <literal>--prefix=$out</literal> to cause Hello to be installed in
+    the expected location.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-builder-co-5'>
+
+    <para>Finally we build Hello (<literal>make</literal>) and install
+    it into the location specified by <envar>out</envar>
+    (<literal>make install</literal>).</para>
+
+  </callout>
+
+</calloutlist>
+
+<para>If you are wondering about the absence of error checking on the
+result of various commands called in the builder: this is because the
+shell script is evaluated with Bash's <option>-e</option> option,
+which causes the script to be aborted if any command fails without an
+error check.</para>
+
+</section>

doc/manual/expressions/builder-syntax.xml

@@ -0,0 +1,119 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id='sec-builder-syntax'>
+
+<title>Builder Syntax</title>
+
+<example xml:id='ex-hello-builder'><title>Build script for GNU Hello
+(<filename>builder.sh</filename>)</title>
+<programlisting>
+source $stdenv/setup <co xml:id='ex-hello-builder-co-1' />
+
+PATH=$perl/bin:$PATH <co xml:id='ex-hello-builder-co-2' />
+
+tar xvfz $src <co xml:id='ex-hello-builder-co-3' />
+cd hello-*
+./configure --prefix=$out <co xml:id='ex-hello-builder-co-4' />
+make <co xml:id='ex-hello-builder-co-5' />
+make install</programlisting>
+</example>
+
+<para><xref linkend='ex-hello-builder' /> shows the builder referenced
+from Hello's Nix expression (stored in
+<filename>pkgs/applications/misc/hello/ex-1/builder.sh</filename>).
+The builder can actually be made a lot shorter by using the
+<emphasis>generic builder</emphasis> functions provided by
+<varname>stdenv</varname>, but here we write out the build steps to
+elucidate what a builder does.  It performs the following
+steps:</para>
+
+<calloutlist>
+
+  <callout arearefs='ex-hello-builder-co-1'>
+
+    <para>When Nix runs a builder, it initially completely clears the
+    environment (except for the attributes declared in the
+    derivation).  For instance, the <envar>PATH</envar> variable is
+    empty<footnote><para>Actually, it's initialised to
+    <filename>/path-not-set</filename> to prevent Bash from setting it
+    to a default value.</para></footnote>.  This is done to prevent
+    undeclared inputs from being used in the build process.  If for
+    example the <envar>PATH</envar> contained
+    <filename>/usr/bin</filename>, then you might accidentally use
+    <filename>/usr/bin/gcc</filename>.</para>
+
+    <para>So the first step is to set up the environment.  This is
+    done by calling the <filename>setup</filename> script of the
+    standard environment.  The environment variable
+    <envar>stdenv</envar> points to the location of the standard
+    environment being used.  (It wasn't specified explicitly as an
+    attribute in <xref linkend='ex-hello-nix' />, but
+    <varname>mkDerivation</varname> adds it automatically.)</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-builder-co-2'>
+
+    <para>Since Hello needs Perl, we have to make sure that Perl is in
+    the <envar>PATH</envar>.  The <envar>perl</envar> environment
+    variable points to the location of the Perl package (since it
+    was passed in as an attribute to the derivation), so
+    <filename><replaceable>$perl</replaceable>/bin</filename> is the
+    directory containing the Perl interpreter.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-builder-co-3'>
+
+    <para>Now we have to unpack the sources.  The
+    <varname>src</varname> attribute was bound to the result of
+    fetching the Hello source tarball from the network, so the
+    <envar>src</envar> environment variable points to the location in
+    the Nix store to which the tarball was downloaded.  After
+    unpacking, we <command>cd</command> to the resulting source
+    directory.</para>
+
+    <para>The whole build is performed in a temporary directory
+    created in <varname>/tmp</varname>, by the way.  This directory is
+    removed after the builder finishes, so there is no need to clean
+    up the sources afterwards.  Also, the temporary directory is
+    always newly created, so you don't have to worry about files from
+    previous builds interfering with the current build.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-builder-co-4'>
+
+    <para>GNU Hello is a typical Autoconf-based package, so we first
+    have to run its <filename>configure</filename> script.  In Nix
+    every package is stored in a separate location in the Nix store,
+    for instance
+    <filename>/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1</filename>.
+    Nix computes this path by cryptographically hashing all attributes
+    of the derivation.  The path is passed to the builder through the
+    <envar>out</envar> environment variable.  So here we give
+    <filename>configure</filename> the parameter
+    <literal>--prefix=$out</literal> to cause Hello to be installed in
+    the expected location.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-builder-co-5'>
+
+    <para>Finally we build Hello (<literal>make</literal>) and install
+    it into the location specified by <envar>out</envar>
+    (<literal>make install</literal>).</para>
+
+  </callout>
+
+</calloutlist>
+
+<para>If you are wondering about the absence of error checking on the
+result of various commands called in the builder: this is because the
+shell script is evaluated with Bash's <option>-e</option> option,
+which causes the script to be aborted if any command fails without an
+error check.</para>
+
+</section>

doc/manual/expressions/builtins.xml

@@ -1,9 +1,10 @@
 <section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id='ssec-builtins'>
+      xmlns:xi="http://www.w3.org/2001/XInclude"
-
+      version="5.0"
-<title>Built-in functions</title>
+      xml:id='ssec-builtins'>
 
+<title>Built-in Functions</title>
 
 <para>This section lists the functions and constants built into the
 Nix expression evaluator.  (The built-in function

doc/manual/expressions/custom-builder.xml

@@ -0,0 +1,26 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-custom-builder">
+
+<title>Customizing the Generic Builder</title>
+
+<para>The operation of the generic builder can be modified in many
+places by setting certain variables.  These <emphasis>hook
+variables</emphasis> are typically set to the name of some shell
+function defined by you.  For instance, to perform some additional
+steps after <command>make install</command> you would set the
+<varname>postInstall</varname> variable:
+
+<programlisting>
+postInstall=myPostInstall
+
+myPostInstall() {
+    mkdir $out/share/extra
+    cp extrafiles/* $out/share/extra
+}</programlisting>
+
+</para>
+
+</section>

doc/manual/expressions/debug-build.xml

@@ -0,0 +1,33 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-debug-build">
+
+<title>Debugging Build Failures</title>
+
+<para>At the beginning of each phase, the set of all shell variables
+is written to the file <filename>env-vars</filename> at the top-level
+build directory.  This is useful for debugging: it allows you to
+recreate the environment in which a build was performed.  For
+instance, if a build fails, then assuming you used the
+<option>-K</option> flag, you can go to the output directory and
+<quote>switch</quote> to the environment of the builder:
+
+<screen>
+$ nix-build -K ./foo.nix
+... fails, keeping build directory `/tmp/nix-1234-0'
+
+$ cd /tmp/nix-1234-0
+
+$ source env-vars
+
+<lineannotation>(edit some files...)</lineannotation>
+
+$ make
+
+<lineannotation>(execution continues with the same GCC, make, etc.)</lineannotation></screen>
+
+</para>
+
+</section>

doc/manual/expressions/derivations.xml

@@ -0,0 +1,211 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="ssec-derivation">
+
+<title>Derivations</title>
+
+<para>The most important built-in function is
+<function>derivation</function>, which is used to describe a single
+derivation (a build action).  It takes as input a set, the attributes
+of which specify the inputs of the build.</para>
+
+<itemizedlist>
+
+  <listitem xml:id="attr-system"><para>There must be an attribute named
+  <varname>system</varname> whose value must be a string specifying a
+  Nix platform identifier, such as <literal>"i686-linux"</literal> or
+  <literal>"powerpc-darwin"</literal><footnote><para>To figure out
+  your platform identifier, look at the line <quote>Checking for the
+  canonical Nix system name</quote> in the output of Nix's
+  <filename>configure</filename> script.</para></footnote> The build
+  can only be performed on a machine and operating system matching the
+  platform identifier.  (Nix can automatically forward builds for
+  other platforms by forwarding them to other machines; see <xref
+  linkend='chap-distributed-builds' />.)</para></listitem>
+
+  <listitem><para>There must be an attribute named
+  <varname>name</varname> whose value must be a string.  This is used
+  as a symbolic name for the package by <command>nix-env</command>,
+  and it is appended to the output paths of the
+  derivation.</para></listitem>
+
+  <listitem><para>There must be an attribute named
+  <varname>builder</varname> that identifies the program that is
+  executed to perform the build.  It can be either a derivation or a
+  source (a local file reference, e.g.,
+  <filename>./builder.sh</filename>).</para></listitem>
+
+  <listitem><para>Every attribute is passed as an environment variable
+  to the builder.  Attribute values are translated to environment
+  variables as follows:
+
+    <itemizedlist>
+
+      <listitem><para>Strings and integers are just passed
+      verbatim.</para></listitem>
+
+      <listitem><para>A <emphasis>path</emphasis> (e.g.,
+      <filename>../foo/sources.tar</filename>) causes the referenced
+      file to be copied to the store; its location in the store is put
+      in the environment variable.  The idea is that all sources
+      should reside in the Nix store, since all inputs to a derivation
+      should reside in the Nix store.</para></listitem>
+
+      <listitem><para>A <emphasis>derivation</emphasis> causes that
+      derivation to be built prior to the present derivation; its
+      default output path is put in the environment
+      variable.</para></listitem>
+
+      <listitem><para>Lists of the previous types are also allowed.
+      They are simply concatenated, separated by
+      spaces.</para></listitem>
+
+      <listitem><para><literal>true</literal> is passed as the string
+      <literal>1</literal>, <literal>false</literal> and
+      <literal>null</literal> are passed as an empty string.
+      </para></listitem>
+    </itemizedlist>
+
+  </para></listitem>
+
+  <listitem><para>The optional attribute <varname>args</varname>
+  specifies command-line arguments to be passed to the builder.  It
+  should be a list.</para></listitem>
+
+  <listitem><para>The optional attribute <varname>outputs</varname>
+  specifies a list of symbolic outputs of the derivation.  By default,
+  a derivation produces a single output path, denoted as
+  <literal>out</literal>.  However, derivations can produce multiple
+  output paths.  This is useful because it allows outputs to be
+  downloaded or garbage-collected separately.  For instance, imagine a
+  library package that provides a dynamic library, header files, and
+  documentation.  A program that links against the library doesn’t
+  need the header files and documentation at runtime, and it doesn’t
+  need the documentation at build time.  Thus, the library package
+  could specify:
+<programlisting>
+outputs = [ "lib" "headers" "doc" ];
+</programlisting>
+  This will cause Nix to pass environment variables
+  <literal>lib</literal>, <literal>headers</literal> and
+  <literal>doc</literal> to the builder containing the intended store
+  paths of each output.  The builder would typically do something like
+<programlisting>
+./configure --libdir=$lib/lib --includedir=$headers/include --docdir=$doc/share/doc
+</programlisting>
+  for an Autoconf-style package.  You can refer to each output of a
+  derivation by selecting it as an attribute, e.g.
+<programlisting>
+buildInputs = [ pkg.lib pkg.headers ];
+</programlisting>
+  The first element of <varname>output</varname> determines the
+  <emphasis>default output</emphasis>.  Thus, you could also write
+<programlisting>
+buildInputs = [ pkg pkg.headers ];
+</programlisting>
+  since <literal>pkg</literal> is equivalent to
+  <literal>pkg.lib</literal>.</para></listitem>
+
+</itemizedlist>
+
+<para>The function <function>mkDerivation</function> in the standard
+environment is a wrapper around <function>derivation</function> that
+adds a default value for <varname>system</varname> and always uses
+Bash as the builder, to which the supplied builder is passed as a
+command-line argument.  See <xref linkend='sec-standard-environment'
+/>.</para>
+
+<para>The builder is executed as follows:
+
+<itemizedlist>
+
+  <listitem><para>A temporary directory is created under the directory
+  specified by <envar>TMPDIR</envar> (default
+  <filename>/tmp</filename>) where the build will take place.  The
+  current directory is changed to this directory.</para></listitem>
+
+  <listitem><para>The environment is cleared and set to the derivation
+  attributes, as specified above.</para></listitem>
+
+  <listitem><para>In addition, the following variables are set:
+
+  <itemizedlist>
+
+    <listitem><para><envar>NIX_BUILD_TOP</envar> contains the path of
+    the temporary directory for this build.</para></listitem>
+
+    <listitem><para>Also, <envar>TMPDIR</envar>,
+    <envar>TEMPDIR</envar>, <envar>TMP</envar>, <envar>TEMP</envar>
+    are set to point to the temporary directory.  This is to prevent
+    the builder from accidentally writing temporary files anywhere
+    else.  Doing so might cause interference by other
+    processes.</para></listitem>
+
+    <listitem><para><envar>PATH</envar> is set to
+    <filename>/path-not-set</filename> to prevent shells from
+    initialising it to their built-in default value.</para></listitem>
+
+    <listitem><para><envar>HOME</envar> is set to
+    <filename>/homeless-shelter</filename> to prevent programs from
+    using <filename>/etc/passwd</filename> or the like to find the
+    user's home directory, which could cause impurity.  Usually, when
+    <envar>HOME</envar> is set, it is used as the location of the home
+    directory, even if it points to a non-existent
+    path.</para></listitem>
+
+    <listitem><para><envar>NIX_STORE</envar> is set to the path of the
+    top-level Nix store directory (typically,
+    <filename>/nix/store</filename>).</para></listitem>
+
+    <listitem><para>For each output declared in
+    <varname>outputs</varname>, the corresponding environment variable
+    is set to point to the intended path in the Nix store for that
+    output.  Each output path is a concatenation of the cryptographic
+    hash of all build inputs, the <varname>name</varname> attribute
+    and the output name.  (The output name is omitted if it’s
+    <literal>out</literal>.)</para></listitem>
+
+  </itemizedlist>
+
+  </para></listitem>
+
+  <listitem><para>If an output path already exists, it is removed.
+  Also, locks are acquired to prevent multiple Nix instances from
+  performing the same build at the same time.</para></listitem>
+
+  <listitem><para>A log of the combined standard output and error is
+  written to <filename>/nix/var/log/nix</filename>.</para></listitem>
+
+  <listitem><para>The builder is executed with the arguments specified
+  by the attribute <varname>args</varname>.  If it exits with exit
+  code 0, it is considered to have succeeded.</para></listitem>
+
+  <listitem><para>The temporary directory is removed (unless the
+  <option>-K</option> option was specified).</para></listitem>
+
+  <listitem><para>If the build was successful, Nix scans each output
+  path for references to input paths by looking for the hash parts of
+  the input paths.  Since these are potential runtime dependencies,
+  Nix registers them as dependencies of the output
+  paths.</para></listitem>
+
+  <listitem><para>After the build, Nix sets the last-modified
+  timestamp on all files in the build result to 1 (00:00:01 1/1/1970
+  UTC), sets the group to the default group, and sets the mode of the
+  file to 0444 or 0555 (i.e., read-only, with execute permission
+  enabled if the file was originally executable).  Note that possible
+  <literal>setuid</literal> and <literal>setgid</literal> bits are
+  cleared.  Setuid and setgid programs are not currently supported by
+  Nix.  This is because the Nix archives used in deployment have no
+  concept of ownership information, and because it makes the build
+  result dependent on the user performing the build.</para></listitem>
+
+</itemizedlist>
+
+</para>
+
+<xi:include href="advanced-attributes.xml" />
+
+</section>

doc/manual/expressions/expression-language.xml

@@ -0,0 +1,30 @@
+<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-expression-language">
+
+<title>Nix Expression Language</title>
+
+<para>The Nix expression language is a pure, lazy, functional
+language.  Purity means that operations in the language don't have
+side-effects (for instance, there is no variable assignment).
+Laziness means that arguments to functions are evaluated only when
+they are needed.  Functional means that functions are
+<quote>normal</quote> values that can be passed around and manipulated
+in interesting ways.  The language is not a full-featured, general
+purpose language.  Its main job is to describe packages,
+compositions of packages, and the variability within
+packages.</para>
+
+<para>This section presents the various features of the
+language.</para>
+
+<xi:include href="language-values.xml" />
+<xi:include href="language-constructs.xml" />
+<xi:include href="language-operators.xml" />
+<xi:include href="derivations.xml" />
+<xi:include href="builtins.xml" />
+
+
+</chapter>

doc/manual/expressions/expression-syntax.xml

@@ -0,0 +1,148 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id='sec-expression-syntax'>
+
+<title>Expression Syntax</title>
+
+<example xml:id='ex-hello-nix'><title>Nix expression for GNU Hello
+(<filename>default.nix</filename>)</title>
+<programlisting>
+{ stdenv, fetchurl, perl }: <co xml:id='ex-hello-nix-co-1' />
+
+stdenv.mkDerivation { <co xml:id='ex-hello-nix-co-2' />
+  name = "hello-2.1.1"; <co xml:id='ex-hello-nix-co-3' />
+  builder = ./builder.sh; <co xml:id='ex-hello-nix-co-4' />
+  src = fetchurl { <co xml:id='ex-hello-nix-co-5' />
+    url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
+    md5 = "70c9ccf9fac07f762c24f2df2290784d";
+  };
+  inherit perl; <co xml:id='ex-hello-nix-co-6' />
+}</programlisting>
+</example>
+
+<para><xref linkend='ex-hello-nix' /> shows a Nix expression for GNU
+Hello.  It's actually already in the Nix Packages collection in
+<filename>pkgs/applications/misc/hello/ex-1/default.nix</filename>.
+It is customary to place each package in a separate directory and call
+the single Nix expression in that directory
+<filename>default.nix</filename>.  The file has the following elements
+(referenced from the figure by number):
+
+<calloutlist>
+
+  <callout arearefs='ex-hello-nix-co-1'>
+
+    <para>This states that the expression is a
+    <emphasis>function</emphasis> that expects to be called with three
+    arguments: <varname>stdenv</varname>, <varname>fetchurl</varname>,
+    and <varname>perl</varname>.  They are needed to build Hello, but
+    we don't know how to build them here; that's why they are function
+    arguments.  <varname>stdenv</varname> is a package that is used
+    by almost all Nix Packages packages; it provides a
+    <quote>standard</quote> environment consisting of the things you
+    would expect in a basic Unix environment: a C/C++ compiler (GCC,
+    to be precise), the Bash shell, fundamental Unix tools such as
+    <command>cp</command>, <command>grep</command>,
+    <command>tar</command>, etc.  <varname>fetchurl</varname> is a
+    function that downloads files.  <varname>perl</varname> is the
+    Perl interpreter.</para>
+
+    <para>Nix functions generally have the form <literal>{ x, y, ...,
+    z }: e</literal> where <varname>x</varname>, <varname>y</varname>,
+    etc. are the names of the expected arguments, and where
+    <replaceable>e</replaceable> is the body of the function.  So
+    here, the entire remainder of the file is the body of the
+    function; when given the required arguments, the body should
+    describe how to build an instance of the Hello package.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-nix-co-2'>
+
+    <para>So we have to build a package.  Building something from
+    other stuff is called a <emphasis>derivation</emphasis> in Nix (as
+    opposed to sources, which are built by humans instead of
+    computers).  We perform a derivation by calling
+    <varname>stdenv.mkDerivation</varname>.
+    <varname>mkDerivation</varname> is a function provided by
+    <varname>stdenv</varname> that builds a package from a set of
+    <emphasis>attributes</emphasis>.  A set is just a list of
+    key/value pairs where each key is a string and each value is an
+    arbitrary Nix expression.  They take the general form <literal>{
+    <replaceable>name1</replaceable> =
+    <replaceable>expr1</replaceable>; <replaceable>...</replaceable>
+    <replaceable>nameN</replaceable> =
+    <replaceable>exprN</replaceable>; }</literal>.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-nix-co-3'>
+
+    <para>The attribute <varname>name</varname> specifies the symbolic
+    name and version of the package.  Nix doesn't really care about
+    these things, but they are used by for instance <command>nix-env
+    -q</command> to show a <quote>human-readable</quote> name for
+    packages.  This attribute is required by
+    <varname>mkDerivation</varname>.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-nix-co-4'>
+
+    <para>The attribute <varname>builder</varname> specifies the
+    builder.  This attribute can sometimes be omitted, in which case
+    <varname>mkDerivation</varname> will fill in a default builder
+    (which does a <literal>configure; make; make install</literal>, in
+    essence).  Hello is sufficiently simple that the default builder
+    would suffice, but in this case, we will show an actual builder
+    for educational purposes.  The value
+    <command>./builder.sh</command> refers to the shell script shown
+    in <xref linkend='ex-hello-builder' />, discussed below.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-nix-co-5'>
+
+    <para>The builder has to know what the sources of the package
+    are.  Here, the attribute <varname>src</varname> is bound to the
+    result of a call to the <command>fetchurl</command> function.
+    Given a URL and an MD5 hash of the expected contents of the file
+    at that URL, this function builds a derivation that downloads the
+    file and checks its hash.  So the sources are a dependency that
+    like all other dependencies is built before Hello itself is
+    built.</para>
+
+    <para>Instead of <varname>src</varname> any other name could have
+    been used, and in fact there can be any number of sources (bound
+    to different attributes).  However, <varname>src</varname> is
+    customary, and it's also expected by the default builder (which we
+    don't use in this example).</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-nix-co-6'>
+
+    <para>Since the derivation requires Perl, we have to pass the
+    value of the <varname>perl</varname> function argument to the
+    builder.  All attributes in the set are actually passed as
+    environment variables to the builder, so declaring an attribute
+
+    <programlisting>
+perl = perl;</programlisting>
+
+    will do the trick: it binds an attribute <varname>perl</varname>
+    to the function argument which also happens to be called
+    <varname>perl</varname>.  However, it looks a bit silly, so there
+    is a shorter syntax.  The <literal>inherit</literal> keyword
+    causes the specified attributes to be bound to whatever variables
+    with the same name happen to be in scope.</para>
+
+  </callout>
+
+</calloutlist>
+
+</para>
+
+</section>

doc/manual/expressions/generic-builder.xml

@@ -0,0 +1,98 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id='sec-generic-builder'>
+
+<title>Generic Builder Syntax</title>
+
+<para>Recall from <xref linkend='ex-hello-builder' /> that the builder
+looked something like this:
+
+<programlisting>
+PATH=$perl/bin:$PATH
+tar xvfz $src
+cd hello-*
+./configure --prefix=$out
+make
+make install</programlisting>
+
+The builders for almost all Unix packages look like this — set up some
+environment variables, unpack the sources, configure, build, and
+install.  For this reason the standard environment provides some Bash
+functions that automate the build process.  A builder using the
+generic build facilities in shown in <xref linkend='ex-hello-builder2'
+/>.</para>
+
+<example xml:id='ex-hello-builder2'><title>Build script using the generic
+build functions</title>
+<programlisting>
+buildInputs="$perl" <co xml:id='ex-hello-builder2-co-1' />
+
+source $stdenv/setup <co xml:id='ex-hello-builder2-co-2' />
+
+genericBuild <co xml:id='ex-hello-builder2-co-3' /></programlisting>
+</example>
+
+<calloutlist>
+
+  <callout arearefs='ex-hello-builder2-co-1'>
+
+    <para>The <envar>buildInputs</envar> variable tells
+    <filename>setup</filename> to use the indicated packages as
+    <quote>inputs</quote>.  This means that if a package provides a
+    <filename>bin</filename> subdirectory, it's added to
+    <envar>PATH</envar>; if it has a <filename>include</filename>
+    subdirectory, it's added to GCC's header search path; and so
+    on.<footnote><para>How does it work? <filename>setup</filename>
+    tries to source the file
+    <filename><replaceable>pkg</replaceable>/nix-support/setup-hook</filename>
+    of all dependencies.  These “setup hooks” can then set up whatever
+    environment variables they want; for instance, the setup hook for
+    Perl sets the <envar>PERL5LIB</envar> environment variable to
+    contain the <filename>lib/site_perl</filename> directories of all
+    inputs.</para></footnote>
+    </para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-builder2-co-2'>
+
+    <para>The function <function>genericBuild</function> is defined in
+    the file <literal>$stdenv/setup</literal>.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-builder2-co-3'>
+
+    <para>The final step calls the shell function
+    <function>genericBuild</function>, which performs the steps that
+    were done explicitly in <xref linkend='ex-hello-builder' />.  The
+    generic builder is smart enough to figure out whether to unpack
+    the sources using <command>gzip</command>,
+    <command>bzip2</command>, etc.  It can be customised in many ways;
+    see <xref linkend='sec-standard-environment' />.</para>
+
+  </callout>
+
+</calloutlist>
+
+<para>Discerning readers will note that the
+<envar>buildInputs</envar> could just as well have been set in the Nix
+expression, like this:
+
+<programlisting>
+  buildInputs = [ perl ];</programlisting>
+
+The <varname>perl</varname> attribute can then be removed, and the
+builder becomes even shorter:
+
+<programlisting>
+source $stdenv/setup
+genericBuild</programlisting>
+
+In fact, <varname>mkDerivation</varname> provides a default builder
+that looks exactly like that, so it is actually possible to omit the
+builder for Hello entirely.</para>
+
+</section>

doc/manual/expressions/language-constructs.xml

@@ -0,0 +1,344 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-constructs">
+
+<title>Language Constructs</title>
+
+<simplesect><title>Recursive sets</title>
+
+<para>Recursive sets are just normal sets, but the attributes can
+refer to each other.  For example,
+
+<programlisting>
+rec {
+  x = y;
+  y = 123;
+}.x
+</programlisting>
+
+evaluates to <literal>123</literal>.  Note that without
+<literal>rec</literal> the binding <literal>x = y;</literal> would
+refer to the variable <varname>y</varname> in the surrounding scope,
+if one exists, and would be invalid if no such variable exists.  That
+is, in a normal (non-recursive) set, attributes are not added to the
+lexical scope; in a recursive set, they are.</para>
+
+<para>Recursive sets of course introduce the danger of infinite
+recursion.  For example,
+
+<programlisting>
+rec {
+  x = y;
+  y = x;
+}.x</programlisting>
+
+does not terminate<footnote><para>Actually, Nix detects infinite
+recursion in this case and aborts (<quote>infinite recursion
+encountered</quote>).</para></footnote>.</para>
+
+</simplesect>
+
+
+<simplesect><title>Let-expressions</title>
+
+<para>A let-expression allows you define local variables for an
+expression.  For instance,
+
+<programlisting>
+let
+  x = "foo";
+  y = "bar";
+in x + y</programlisting>
+
+evaluates to <literal>"foobar"</literal>.
+
+</para>
+
+</simplesect>
+
+
+<simplesect><title>Inheriting attributes</title>
+
+<para>When defining a set it is often convenient to copy variables
+from the surrounding lexical scope (e.g., when you want to propagate
+attributes).  This can be shortened using the
+<literal>inherit</literal> keyword.  For instance,
+
+<programlisting>
+let x = 123; in
+{ inherit x;
+  y = 456;
+}</programlisting>
+
+evaluates to <literal>{ x = 123; y = 456; }</literal>.  (Note that
+this works because <varname>x</varname> is added to the lexical scope
+by the <literal>let</literal> construct.)  It is also possible to
+inherit attributes from another set.  For instance, in this fragment
+from <filename>all-packages.nix</filename>,
+
+<programlisting>
+  graphviz = (import ../tools/graphics/graphviz) {
+    inherit fetchurl stdenv libpng libjpeg expat x11 yacc;
+    inherit (xlibs) libXaw;
+  };
+
+  xlibs = {
+    libX11 = ...;
+    libXaw = ...;
+    ...
+  }
+
+  libpng = ...;
+  libjpg = ...;
+  ...</programlisting>
+
+the set used in the function call to the function defined in
+<filename>../tools/graphics/graphviz</filename> inherits a number of
+variables from the surrounding scope (<varname>fetchurl</varname>
+... <varname>yacc</varname>), but also inherits
+<varname>libXaw</varname> (the X Athena Widgets) from the
+<varname>xlibs</varname> (X11 client-side libraries) set.</para>
+
+</simplesect>
+
+
+<simplesect xml:id="ss-functions"><title>Functions</title>
+
+<para>Functions have the following form:
+
+<programlisting>
+<replaceable>pattern</replaceable>: <replaceable>body</replaceable></programlisting>
+
+The pattern specifies what the argument of the function must look
+like, and binds variables in the body to (parts of) the
+argument.  There are three kinds of patterns:</para>
+
+<itemizedlist>
+
+
+  <listitem><para>If a pattern is a single identifier, then the
+  function matches any argument.  Example:
+
+  <programlisting>
+let negate = x: !x;
+    concat = x: y: x + y;
+in if negate true then concat "foo" "bar" else ""</programlisting>
+
+  Note that <function>concat</function> is a function that takes one
+  argument and returns a function that takes another argument.  This
+  allows partial parameterisation (i.e., only filling some of the
+  arguments of a function); e.g.,
+
+  <programlisting>
+map (concat "foo") [ "bar" "bla" "abc" ]</programlisting>
+
+  evaluates to <literal>[ "foobar" "foobla"
+  "fooabc" ]</literal>.</para></listitem>
+
+
+  <listitem><para>A <emphasis>set pattern</emphasis> of the form
+  <literal>{ name1, name2, …, nameN }</literal> matches a set
+  containing the listed attributes, and binds the values of those
+  attributes to variables in the function body.  For example, the
+  function
+
+<programlisting>
+{ x, y, z }: z + y + x</programlisting>
+
+  can only be called with a set containing exactly the attributes
+  <varname>x</varname>, <varname>y</varname> and
+  <varname>z</varname>.  No other attributes are allowed.  If you want
+  to allow additional arguments, you can use an ellipsis
+  (<literal>...</literal>):
+
+<programlisting>
+{ x, y, z, ... }: z + y + x</programlisting>
+
+  This works on any set that contains at least the three named
+  attributes.</para>
+
+  <para>It is possible to provide <emphasis>default values</emphasis>
+  for attributes, in which case they are allowed to be missing.  A
+  default value is specified by writing
+  <literal><replaceable>name</replaceable> ?
+  <replaceable>e</replaceable></literal>, where
+  <replaceable>e</replaceable> is an arbitrary expression.  For example,
+
+<programlisting>
+{ x, y ? "foo", z ? "bar" }: z + y + x</programlisting>
+
+  specifies a function that only requires an attribute named
+  <varname>x</varname>, but optionally accepts <varname>y</varname>
+  and <varname>z</varname>.</para></listitem>
+
+
+  <listitem><para>An <literal>@</literal>-pattern provides a means of referring
+  to the whole value being matched:
+
+<programlisting>
+args@{ x, y, z, ... }: z + y + x + args.a</programlisting>
+
+  Here <varname>args</varname> is bound to the entire argument, which
+  is further matched against the pattern <literal>{ x, y, z,
+  ... }</literal>.</para></listitem>
+
+
+</itemizedlist>
+
+<para>Note that functions do not have names.  If you want to give them
+a name, you can bind them to an attribute, e.g.,
+
+<programlisting>
+let concat = { x, y }: x + y;
+in concat { x = "foo"; y = "bar"; }</programlisting>
+
+</para>
+
+</simplesect>
+
+
+<simplesect><title>Conditionals</title>
+
+<para>Conditionals look like this:
+
+<programlisting>
+if <replaceable>e1</replaceable> then <replaceable>e2</replaceable> else <replaceable>e3</replaceable></programlisting>
+
+where <replaceable>e1</replaceable> is an expression that should
+evaluate to a Boolean value (<literal>true</literal> or
+<literal>false</literal>).</para>
+
+</simplesect>
+
+
+<simplesect><title>Assertions</title>
+
+<para>Assertions are generally used to check that certain requirements
+on or between features and dependencies hold.  They look like this:
+
+<programlisting>
+assert <replaceable>e1</replaceable>; <replaceable>e2</replaceable></programlisting>
+
+where <replaceable>e1</replaceable> is an expression that should
+evaluate to a Boolean value.  If it evaluates to
+<literal>true</literal>, <replaceable>e2</replaceable> is returned;
+otherwise expression evaluation is aborted and a backtrace is printed.</para>
+
+<example xml:id='ex-subversion-nix'><title>Nix expression for Subversion</title>
+<programlisting>
+{ localServer ? false
+, httpServer ? false
+, sslSupport ? false
+, pythonBindings ? false
+, javaSwigBindings ? false
+, javahlBindings ? false
+, stdenv, fetchurl
+, openssl ? null, httpd ? null, db4 ? null, expat, swig ? null, j2sdk ? null
+}:
+
+assert localServer -> db4 != null; <co xml:id='ex-subversion-nix-co-1' />
+assert httpServer -> httpd != null &amp;&amp; httpd.expat == expat; <co xml:id='ex-subversion-nix-co-2' />
+assert sslSupport -> openssl != null &amp;&amp; (httpServer -> httpd.openssl == openssl); <co xml:id='ex-subversion-nix-co-3' />
+assert pythonBindings -> swig != null &amp;&amp; swig.pythonSupport;
+assert javaSwigBindings -> swig != null &amp;&amp; swig.javaSupport;
+assert javahlBindings -> j2sdk != null;
+
+stdenv.mkDerivation {
+  name = "subversion-1.1.1";
+  ...
+  openssl = if sslSupport then openssl else null; <co xml:id='ex-subversion-nix-co-4' />
+  ...
+}</programlisting>
+</example>
+
+<para><xref linkend='ex-subversion-nix' /> show how assertions are
+used in the Nix expression for Subversion.</para>
+
+<calloutlist>
+
+  <callout arearefs='ex-subversion-nix-co-1'>
+    <para>This assertion states that if Subversion is to have support
+    for local repositories, then Berkeley DB is needed.  So if the
+    Subversion function is called with the
+    <varname>localServer</varname> argument set to
+    <literal>true</literal> but the <varname>db4</varname> argument
+    set to <literal>null</literal>, then the evaluation fails.</para>
+  </callout>
+
+  <callout arearefs='ex-subversion-nix-co-2'>
+    <para>This is a more subtle condition: if Subversion is built with
+    Apache (<literal>httpServer</literal>) support, then the Expat
+    library (an XML library) used by Subversion should be same as the
+    one used by Apache.  This is because in this configuration
+    Subversion code ends up being linked with Apache code, and if the
+    Expat libraries do not match, a build- or runtime link error or
+    incompatibility might occur.</para>
+  </callout>
+
+  <callout arearefs='ex-subversion-nix-co-3'>
+    <para>This assertion says that in order for Subversion to have SSL
+    support (so that it can access <literal>https</literal> URLs), an
+    OpenSSL library must be passed.  Additionally, it says that
+    <emphasis>if</emphasis> Apache support is enabled, then Apache's
+    OpenSSL should match Subversion's.  (Note that if Apache support
+    is not enabled, we don't care about Apache's OpenSSL.)</para>
+  </callout>
+
+  <callout arearefs='ex-subversion-nix-co-4'>
+    <para>The conditional here is not really related to assertions,
+    but is worth pointing out: it ensures that if SSL support is
+    disabled, then the Subversion derivation is not dependent on
+    OpenSSL, even if a non-<literal>null</literal> value was passed.
+    This prevents an unnecessary rebuild of Subversion if OpenSSL
+    changes.</para>
+  </callout>
+
+</calloutlist>
+
+</simplesect>
+
+
+
+<simplesect><title>With-expressions</title>
+
+<para>A <emphasis>with-expression</emphasis>,
+
+<programlisting>
+with <replaceable>e1</replaceable>; <replaceable>e2</replaceable></programlisting>
+
+introduces the set <replaceable>e1</replaceable> into the lexical
+scope of the expression <replaceable>e2</replaceable>.  For instance,
+
+<programlisting>
+let as = { x = "foo"; y = "bar"; };
+in with as; x + y</programlisting>
+
+evaluates to <literal>"foobar"</literal> since the
+<literal>with</literal> adds the <varname>x</varname> and
+<varname>y</varname> attributes of <varname>as</varname> to the
+lexical scope in the expression <literal>x + y</literal>.  The most
+common use of <literal>with</literal> is in conjunction with the
+<function>import</function> function.  E.g.,
+
+<programlisting>
+with (import ./definitions.nix); ...</programlisting>
+
+makes all attributes defined in the file
+<filename>definitions.nix</filename> available as if they were defined
+locally in a <literal>rec</literal>-expression.</para>
+
+</simplesect>
+
+
+<simplesect><title>Comments</title>
+
+<para>Comments can be single-line, started with a <literal>#</literal>
+character, or inline/multi-line, enclosed within <literal>/*
+... */</literal>.</para>
+
+</simplesect>
+
+
+</section>

doc/manual/expressions/language-operators.xml

@@ -0,0 +1,113 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-language-operators">
+
+<title>Operators</title>
+
+<para><xref linkend='table-operators' /> lists the operators in the
+Nix expression language, in order of precedence (from strongest to
+weakest binding).</para>
+
+<table xml:id='table-operators'>
+  <title>Operators</title>
+  <tgroup cols='3'>
+    <thead>
+      <row>
+        <entry>Syntax</entry>
+        <entry>Associativity</entry>
+        <entry>Description</entry>
+      </row>
+    </thead>
+    <tbody>
+      <row>
+        <entry><replaceable>e</replaceable> <literal>.</literal>
+        <replaceable>attrpath</replaceable>
+        [ <literal>or</literal> <replaceable>def</replaceable> ]
+        </entry>
+        <entry>none</entry>
+        <entry>Select attribute denoted by the attribute path
+        <replaceable>attrpath</replaceable> from set
+        <replaceable>e</replaceable>.  (An attribute path is a
+        dot-separated list of attribute names.)  If the attribute
+        doesn’t exist, return <replaceable>def</replaceable> if
+        provided, otherwise abort evaluation.</entry>
+      </row>
+      <row>
+        <entry><replaceable>e1</replaceable> <replaceable>e2</replaceable></entry>
+        <entry>left</entry>
+        <entry>Call function <replaceable>e1</replaceable> with
+        argument <replaceable>e2</replaceable>.</entry>
+      </row>
+      <row>
+        <entry><replaceable>e</replaceable> <literal>?</literal>
+        <replaceable>attrpath</replaceable></entry>
+        <entry>none</entry>
+        <entry>Test whether set <replaceable>e</replaceable> contains
+        the attribute denoted by <replaceable>attrpath</replaceable>;
+        return <literal>true</literal> or
+        <literal>false</literal>.</entry>
+      </row>
+      <row>
+        <entry><replaceable>e1</replaceable> <literal>++</literal> <replaceable>e2</replaceable></entry>
+        <entry>right</entry>
+        <entry>List concatenation.</entry>
+      </row>
+      <row>
+        <entry><replaceable>e1</replaceable> <literal>+</literal> <replaceable>e2</replaceable></entry>
+        <entry>left</entry>
+        <entry>String or path concatenation.</entry>
+      </row>
+      <row>
+        <entry><literal>!</literal> <replaceable>e</replaceable></entry>
+        <entry>left</entry>
+        <entry>Boolean negation.</entry>
+      </row>
+      <row>
+        <entry><replaceable>e1</replaceable> <literal>//</literal>
+        <replaceable>e2</replaceable></entry>
+        <entry>right</entry>
+        <entry>Return a set consisting of the attributes in
+        <replaceable>e1</replaceable> and
+        <replaceable>e2</replaceable> (with the latter taking
+        precedence over the former in case of equally named
+        attributes).</entry>
+      </row>
+      <row>
+        <entry><replaceable>e1</replaceable> <literal>==</literal>
+        <replaceable>e2</replaceable></entry>
+        <entry>none</entry>
+        <entry>Equality.</entry>
+      </row>
+      <row>
+        <entry><replaceable>e1</replaceable> <literal>!=</literal>
+        <replaceable>e2</replaceable></entry>
+        <entry>none</entry>
+        <entry>Inequality.</entry>
+      </row>
+      <row>
+        <entry><replaceable>e1</replaceable> <literal>&amp;&amp;</literal>
+        <replaceable>e2</replaceable></entry>
+        <entry>left</entry>
+        <entry>Logical AND.</entry>
+      </row>
+      <row>
+        <entry><replaceable>e1</replaceable> <literal>||</literal>
+        <replaceable>e2</replaceable></entry>
+        <entry>left</entry>
+        <entry>Logical OR.</entry>
+      </row>
+      <row>
+        <entry><replaceable>e1</replaceable> <literal>-></literal>
+        <replaceable>e2</replaceable></entry>
+        <entry>none</entry>
+        <entry>Logical implication (equivalent to
+        <literal>!<replaceable>e1</replaceable> ||
+        <replaceable>e2</replaceable></literal>).</entry>
+      </row>
+    </tbody>
+  </tgroup>
+</table>
+
+</section>

doc/manual/expressions/language-values.xml

@@ -0,0 +1,268 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id='ssec-values'>
+
+<title>Values</title>
+
+
+<simplesect><title>Simple Values</title>
+
+<para>Nix has the following basic data types:
+
+<itemizedlist>
+
+  <listitem>
+
+    <para><emphasis>Strings</emphasis> can be written in three
+    ways.</para>
+
+    <para>The most common way is to enclose the string between double
+    quotes, e.g., <literal>"foo bar"</literal>.  Strings can span
+    multiple lines.  The special characters <literal>"</literal> and
+    <literal>\</literal> and the character sequence
+    <literal>${</literal> must be escaped by prefixing them with a
+    backslash (<literal>\</literal>).  Newlines, carriage returns and
+    tabs can be written as <literal>\n</literal>,
+    <literal>\r</literal> and <literal>\t</literal>,
+    respectively.</para>
+
+    <para>You can include the result of an expression into a string by
+    enclosing it in
+    <literal>${<replaceable>...</replaceable>}</literal>, a feature
+    known as <emphasis>antiquotation</emphasis>.  The enclosed
+    expression must evaluate to something that can be coerced into a
+    string (meaning that it must be a string, a path, or a
+    derivation).  For instance, rather than writing
+
+<programlisting>
+"--with-freetype2-library=" + freetype + "/lib"</programlisting>
+
+    (where <varname>freetype</varname> is a derivation), you can
+    instead write the more natural
+
+<programlisting>
+"--with-freetype2-library=${freetype}/lib"</programlisting>
+
+    The latter is automatically translated to the former.  A more
+    complicated example (from the Nix expression for <link
+    xlink:href='http://www.trolltech.com/products/qt'>Qt</link>):
+
+<programlisting>
+configureFlags = "
+  -system-zlib -system-libpng -system-libjpeg
+  ${if openglSupport then "-dlopen-opengl
+    -L${mesa}/lib -I${mesa}/include
+    -L${libXmu}/lib -I${libXmu}/include" else ""}
+  ${if threadSupport then "-thread" else "-no-thread"}
+";</programlisting>
+
+    Note that Nix expressions and strings can be arbitrarily nested;
+    in this case the outer string contains various antiquotations that
+    themselves contain strings (e.g., <literal>"-thread"</literal>),
+    some of which in turn contain expressions (e.g.,
+    <literal>${mesa}</literal>).</para>
+
+    <para>The second way to write string literals is as an
+    <emphasis>indented string</emphasis>, which is enclosed between
+    pairs of <emphasis>double single-quotes</emphasis>, like so:
+
+<programlisting>
+''
+  This is the first line.
+  This is the second line.
+    This is the third line.
+''</programlisting>
+
+    This kind of string literal intelligently strips indentation from
+    the start of each line.  To be precise, it strips from each line a
+    number of spaces equal to the minimal indentation of the string as
+    a whole (disregarding the indentation of empty lines).  For
+    instance, the first and second line are indented two space, while
+    the third line is indented four spaces.  Thus, two spaces are
+    stripped from each line, so the resulting string is
+
+<programlisting>
+"This is the first line.\nThis is the second line.\n  This is the third line.\n"</programlisting>
+
+    </para>
+
+    <para>Note that the whitespace and newline following the opening
+    <literal>''</literal> is ignored if there is no non-whitespace
+    text on the initial line.</para>
+
+    <para>Antiquotation
+    (<literal>${<replaceable>expr</replaceable>}</literal>) is
+    supported in indented strings.</para>
+
+    <para>Since <literal>${</literal> and <literal>''</literal> have
+    special meaning in indented strings, you need a way to quote them.
+    <literal>${</literal> can be escaped by prefixing it with
+    <literal>''</literal> (that is, two single quotes), i.e.,
+    <literal>''${</literal>.  <literal>''</literal> can be escaped by
+    prefixing it with <literal>'</literal>, i.e.,
+    <literal>'''</literal>.  Finally, linefeed, carriage-return and
+    tab characters can be written as <literal>''\n</literal>,
+    <literal>''\r</literal>, <literal>''\t</literal>.</para>
+
+    <para>Indented strings are primarily useful in that they allow
+    multi-line string literals to follow the indentation of the
+    enclosing Nix expression, and that less escaping is typically
+    necessary for strings representing languages such as shell scripts
+    and configuration files because <literal>''</literal> is much less
+    common than <literal>"</literal>.  Example:
+
+<programlisting>
+stdenv.mkDerivation {
+  <replaceable>...</replaceable>
+  postInstall =
+    ''
+      mkdir $out/bin $out/etc
+      cp foo $out/bin
+      echo "Hello World" > $out/etc/foo.conf
+      ${if enableBar then "cp bar $out/bin" else ""}
+    '';
+  <replaceable>...</replaceable>
+}
+</programlisting>
+
+    </para>
+
+    <para>Finally, as a convenience, <emphasis>URIs</emphasis> as
+    defined in appendix B of <link
+    xlink:href='http://www.ietf.org/rfc/rfc2396.txt'>RFC 2396</link>
+    can be written <emphasis>as is</emphasis>, without quotes.  For
+    instance, the string
+    <literal>"http://example.org/foo.tar.bz2"</literal>
+    can also be written as
+    <literal>http://example.org/foo.tar.bz2</literal>.</para>
+
+  </listitem>
+
+  <listitem><para><emphasis>Integers</emphasis>, e.g.,
+  <literal>123</literal>.</para></listitem>
+
+  <listitem><para><emphasis>Paths</emphasis>, e.g.,
+  <filename>/bin/sh</filename> or <filename>./builder.sh</filename>.
+  A path must contain at least one slash to be recognised as such; for
+  instance, <filename>builder.sh</filename> is not a
+  path<footnote><para>It's parsed as an expression that selects the
+  attribute <varname>sh</varname> from the variable
+  <varname>builder</varname>.</para></footnote>.  If the file name is
+  relative, i.e., if it does not begin with a slash, it is made
+  absolute at parse time relative to the directory of the Nix
+  expression that contained it.  For instance, if a Nix expression in
+  <filename>/foo/bar/bla.nix</filename> refers to
+  <filename>../xyzzy/fnord.nix</filename>, the absolute path is
+  <filename>/foo/xyzzy/fnord.nix</filename>.</para></listitem>
+
+  <listitem><para><emphasis>Booleans</emphasis> with values
+  <literal>true</literal> and
+  <literal>false</literal>.</para></listitem>
+
+  <listitem><para>The null value, denoted as
+  <literal>null</literal>.</para></listitem>
+
+</itemizedlist>
+
+</para>
+
+</simplesect>
+
+
+<simplesect><title>Lists</title>
+
+<para>Lists are formed by enclosing a whitespace-separated list of
+values between square brackets.  For example,
+
+<programlisting>
+[ 123 ./foo.nix "abc" (f { x = y; }) ]</programlisting>
+
+defines a list of four elements, the last being the result of a call
+to the function <varname>f</varname>.  Note that function calls have
+to be enclosed in parentheses.  If they had been omitted, e.g.,
+
+<programlisting>
+[ 123 ./foo.nix "abc" f { x = y; } ]</programlisting>
+
+the result would be a list of five elements, the fourth one being a
+function and the fifth being a set.</para>
+
+</simplesect>
+
+
+<simplesect><title>Sets</title>
+
+<para>Sets are really the core of the language, since ultimately the
+Nix language is all about creating derivations, which are really just
+sets of attributes to be passed to build scripts.</para>
+
+<para>Sets are just a list of name/value pairs (called
+<emphasis>attributes</emphasis>) enclosed in curly brackets, where
+each value is an arbitrary expression terminated by a semicolon.  For
+example:
+
+<programlisting>
+{ x = 123;
+  text = "Hello";
+  y = f { bla = 456; };
+}</programlisting>
+
+This defines a set with attributes named <varname>x</varname>,
+<varname>text</varname>, <varname>y</varname>.  The order of the
+attributes is irrelevant.  An attribute name may only occur
+once.</para>
+
+<para>Attributes can be selected from a set using the
+<literal>.</literal> operator.  For instance,
+
+<programlisting>
+{ a = "Foo"; b = "Bar"; }.a</programlisting>
+
+evaluates to <literal>"Foo"</literal>.  It is possible to provide a
+default value in an attribute selection using the
+<literal>or</literal> keyword.  For example,
+
+<programlisting>
+{ a = "Foo"; b = "Bar"; }.c or "Xyzzy"</programlisting>
+
+will evaluate to <literal>"Xyzzy"</literal> because there is no
+<varname>c</varname> attribute in the set.</para>
+
+<para>You can use arbitrary double-quoted strings as attribute
+names:
+
+<programlisting>
+{ "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}"
+</programlisting>
+
+This will evaluate to <literal>123</literal> (Assuming
+<literal>bar</literal> is antiquotable). In the case where an
+attribute name is just a single antiquotation, the quotes can be
+dropped:
+
+<programlisting>
+{ foo = 123; }.${bar} or 456 </programlisting>
+
+This will evaluate to <literal>123</literal> if
+<literal>bar</literal> evaluates to <literal>"foo"</literal> when
+coerced to a string and <literal>456</literal> otherwise (again
+assuming <literal>bar</literal> is antiquotable).</para>
+
+<para>In the special case where an attribute name inside of a set declaration
+evaluates to <literal>null</literal> (which is normally an error, as
+<literal>null</literal> is not antiquotable), that attribute is simply not
+added to the set:
+
+<programlisting>
+{ ${if foo then "bar" else null} = true; }</programlisting>
+
+This will evaluate to <literal>{}</literal> if <literal>foo</literal>
+evaluates to <literal>false</literal>.</para>
+
+
+</simplesect>
+
+
+</section>

doc/manual/expressions/simple-building-testing.xml

@@ -0,0 +1,86 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id='sec-building-simple'>
+
+<title>Building and Testing</title>
+
+<para>You can now try to build Hello.  Of course, you could do
+<literal>nix-env -f pkgs/top-level/all-packages.nix -i hello</literal>,
+but you may not want to install a possibly broken package just yet.
+The best way to test the package is by using the command <command
+linkend="sec-nix-build">nix-build</command>, which builds a Nix
+expression and creates a symlink named <filename>result</filename> in
+the current directory:
+
+<screen>
+$ nix-build pkgs/top-level/all-packages.nix -A hello
+building path `/nix/store/632d2b22514d...-hello-2.1.1'
+hello-2.1.1/
+hello-2.1.1/intl/
+hello-2.1.1/intl/ChangeLog
+<replaceable>...</replaceable>
+
+$ ls -l result
+lrwxrwxrwx ... 2006-09-29 10:43 result -> /nix/store/632d2b22514d...-hello-2.1.1
+
+$ ./result/bin/hello
+Hello, world!</screen>
+
+The <link linkend='opt-attr'><option>-A</option></link> option selects
+the <literal>hello</literal> attribute from
+<filename>all-packages.nix</filename>.  This is faster than using the
+symbolic package name specified by the <literal>name</literal>
+attribute (which also happens to be <literal>hello</literal>) and is
+unambiguous (there can be multiple packages with the symbolic name
+<literal>hello</literal>, but there can be only one attribute in a set
+named <literal>hello</literal>).</para>
+
+<para><command>nix-build</command> registers the
+<filename>./result</filename> symlink as a garbage collection root, so
+unless and until you delete the <filename>./result</filename> symlink,
+the output of the build will be safely kept on your system.  You can
+use <command>nix-build</command>’s <option
+linkend='opt-out-link'>-o</option> switch to give the symlink another
+name.</para>
+
+<para>Nix has a transactional semantics.  Once a build finishes
+successfully, Nix makes a note of this in its database: it registers
+that the path denoted by <envar>out</envar> is now
+<quote>valid</quote>.  If you try to build the derivation again, Nix
+will see that the path is already valid and finish immediately.  If a
+build fails, either because it returns a non-zero exit code, because
+Nix or the builder are killed, or because the machine crashes, then
+the output paths will not be registered as valid.  If you try to build
+the derivation again, Nix will remove the output paths if they exist
+(e.g., because the builder died half-way through <literal>make
+install</literal>) and try again.  Note that there is no
+<quote>negative caching</quote>: Nix doesn't remember that a build
+failed, and so a failed build can always be repeated.  This is because
+Nix cannot distinguish between permanent failures (e.g., a compiler
+error due to a syntax error in the source) and transient failures
+(e.g., a disk full condition).</para>
+
+<para>Nix also performs locking.  If you run multiple Nix builds
+simultaneously, and they try to build the same derivation, the first
+Nix instance that gets there will perform the build, while the others
+block (or perform other derivations if available) until the build
+finishes:
+
+<screen>
+$ nix-build pkgs/top-level/all-packages.nix -A hello
+waiting for lock on `/nix/store/0h5b7hp8d4hqfrw8igvx97x1xawrjnac-hello-2.1.1x'</screen>
+
+So it is always safe to run multiple instances of Nix in parallel
+(which isn’t the case with, say, <command>make</command>).</para>
+
+<para>If you have a system with multiple CPUs, you may want to have
+Nix build different derivations in parallel (insofar as possible).
+Just pass the option <link linkend='opt-max-jobs'><option>-j
+<replaceable>N</replaceable></option></link>, where
+<replaceable>N</replaceable> is the maximum number of jobs to be run
+in parallel, or set.  Typically this should be the number of
+CPUs.</para>
+
+</section>

doc/manual/expressions/simple-expression.xml

@@ -0,0 +1,47 @@
+<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-simple-expression">
+
+<title>Simple Nix Expression Use-Case</title>
+
+<para>This section shows how to add and test the <link
+xlink:href='http://www.gnu.org/software/hello/hello.html'>GNU Hello
+package</link> to the Nix Packages collection.  Hello is a program
+that prints out the text <quote>Hello, world!</quote>.</para>
+
+<para>To add a package to the Nix Packages collection, you generally
+need to do three things:
+
+<orderedlist>
+
+  <listitem><para>Write a Nix expression for the package.  This is a
+  file that describes all the inputs involved in building the package,
+  such as dependencies, sources, and so on.</para></listitem>
+
+  <listitem><para>Write a <emphasis>builder</emphasis>.  This is a
+  shell script<footnote><para>In fact, it can be written in any
+  language, but typically it's a <command>bash</command> shell
+  script.</para></footnote> that actually builds the package from
+  the inputs.</para></listitem>
+
+  <listitem><para>Add the package to the file
+  <filename>pkgs/top-level/all-packages.nix</filename>.  The Nix
+  expression written in the first step is a
+  <emphasis>function</emphasis>; it requires other packages in order
+  to build it.  In this step you put it all together, i.e., you call
+  the function with the right arguments to build the actual
+  package.</para></listitem>
+
+</orderedlist>
+
+</para>
+
+<xi:include href="expression-syntax.xml" />
+<xi:include href="build-script.xml" />
+<xi:include href="arguments-variables.xml" />
+<xi:include href="simple-building-testing.xml" />
+<xi:include href="generic-builder.xml" />
+
+</chapter>

doc/manual/expressions/standard-env.xml

@@ -0,0 +1,60 @@
+<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='sec-standard-environment'>
+
+<title>The Standard Environment</title>
+
+
+<para>The standard environment is used by passing it as an input
+called <envar>stdenv</envar> to the derivation, and then doing
+
+<programlisting>
+source $stdenv/setup</programlisting>
+
+at the top of the builder.</para>
+
+<para>Apart from adding the aforementioned commands to the
+<envar>PATH</envar>, <filename>setup</filename> also does the
+following:
+
+<itemizedlist>
+
+  <listitem><para>All input packages specified in the
+  <envar>buildInputs</envar> environment variable have their
+  <filename>/bin</filename> subdirectory added to <envar>PATH</envar>,
+  their <filename>/include</filename> subdirectory added to the C/C++
+  header file search path, and their <filename>/lib</filename>
+  subdirectory added to the linker search path.  This can be extended.
+  For instance, when the <command>pkgconfig</command> package is
+  used, the subdirectory <filename>/lib/pkgconfig</filename> of each
+  input is added to the <envar>PKG_CONFIG_PATH</envar> environment
+  variable.</para></listitem>
+
+  <listitem><para>The environment variable
+  <envar>NIX_CFLAGS_STRIP</envar> is set so that the compiler strips
+  debug information from object files.  This can be disabled by
+  setting <envar>NIX_STRIP_DEBUG</envar> to
+  <literal>0</literal>.</para></listitem>
+
+</itemizedlist>
+
+</para>
+
+<para>The <filename>setup</filename> script also exports a function
+called <function>genericBuild</function> that knows how to build
+typical Autoconf-style packages.  It can be customised to perform
+builds for any type of package.  It is advisable to use
+<function>genericBuild</function> since it provides facilities that
+are almost always useful such as unpacking of sources, patching of
+sources, nested logging, etc.</para>
+
+<para>The definitive, up-to-date documentation of the generic builder
+is the source itself, which resides in
+<filename>pkgs/stdenv/generic/setup.sh</filename>.</para>
+
+<xi:include href="custom-builder.xml" />
+<xi:include href="debug-build.xml" />
+
+</chapter>

doc/manual/expressions/writing-nix-expressions.xml

@@ -0,0 +1,27 @@
+<part 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='chap-writing-nix-expressions'>
+
+<title>Nix Expressions</title>
+
+<partintro>
+<para>This chapter shows you how to write Nix expressions, which 
+instruct Nix how to build packages.  It starts with a
+simple example (a Nix expression for GNU Hello), and then moves
+on to a more in-depth look at the Nix expression language.</para>
+
+<note><para>This chapter is mostly about the Nix expression language.
+For more extensive information on adding packages to the Nix Packages
+collection (such as functions in the standard environment and coding
+conventions), please consult <link
+xlink:href="http://nixos.org/nixpkgs/manual/">its
+manual</link>.</para></note>
+</partintro>
+
+<xi:include href="simple-expression.xml" />
+<xi:include href="expression-language.xml" />
+<xi:include href="standard-env.xml" />
+
+</part>

doc/manual/installation.xml

@@ -1,447 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="chap-installation">
-
-<title>Installation</title>
-
-
-<section><title>Supported platforms</title>
-
-<para>Nix is currently supported on the following platforms:
-
-<itemizedlist>
-
-  <listitem><para>Linux (particularly on x86, x86_64, and
-  PowerPC).</para></listitem>
-
-  <listitem><para>Mac OS X.</para></listitem>
-
-  <listitem><para>FreeBSD (only tested on Intel).</para></listitem>
-
-  <!--
-  <listitem><para>Windows through <link
-  xlink:href="http://www.cygwin.com/">Cygwin</link>.</para>
-
-  <warning><para>On Cygwin, Nix <emphasis>must</emphasis> be installed
-  on an NTFS partition.  It will not work correctly on a FAT
-  partition.</para></warning>
-
-  </listitem>
-  -->
-
-</itemizedlist>
-
-</para>
-
-<para>Nix is pretty portable, so it should work on most other Unix
-platforms as well.</para>
-
-</section>
-
-
-<section><title>Installing a binary distribution</title>
-
-<para>The easiest way to install Nix is to run the following:
-
-<screen>
-$ bash &lt;(curl https://nixos.org/nix/install)
-</screen>
-
-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
-root.  The script will invoke <command>sudo</command> to create
-<filename>/nix</filename> if it doesn’t already exist.  If you don’t
-have <command>sudo</command>, you should manually create
-<command>/nix</command> first as root:
-
-<screen>
-$ mkdir /nix
-$ chown alice /nix
-</screen>
-
-</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, Mac OS X 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.7-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.7-1_amd64.deb</screen>
-
-</para>
-
-<para>For other platforms, including Mac OS X (Darwin), FreeBSD and
-other Linux distributions, you can 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> uses.)  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.7-x86_64-darwin.tar.bz2
-alice$ cd nix-1.7-x86_64-darwin
-alice$ ./install
-</screen>
-
-</para>
-
-<para>Nix can be uninstalled using <command>rpm -e nix</command> or
-<command>dpkg -r nix</command> on RPM- and Dpkg-based systems,
-respectively.  After this you should manually remove the Nix store and
-other auxiliary data, if desired:
-
-<screen>
-$ rm -rf /nix</screen>
-
-</para>
-
-</section>
-
-
-<section><title>Installing Nix from source</title>
-
-<para>If no binary package is available, you can download and compile
-a source distribution.</para>
-
-<section><title>Prerequisites</title>
-
-<itemizedlist>
-
-  <listitem><para>GNU Make.</para></listitem>
-
-  <listitem><para>A version of GCC or Clang that supports C++11.</para></listitem>
-
-  <listitem><para>Perl 5.8 or higher.</para></listitem>
-
-  <listitem><para><command>pkg-config</command> to locate
-  dependencies.  If your distribution does not provide it, you can get
-  it from <link
-  xlink:href="http://www.freedesktop.org/wiki/Software/pkg-config"
-  />.</para></listitem>
-
-  <listitem><para>The bzip2 compressor program and the
-  <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>
-
-  <listitem><para>The SQLite embedded database library, version 3.6.19
-  or higher.  If your distribution does not provide it, please install
-  it from <link xlink:href="http://www.sqlite.org/" />.</para></listitem>
-
-  <listitem><para>The Perl DBI and DBD::SQLite libraries, which are
-  available from <link
-  xlink:href="http://search.cpan.org/">CPAN</link> if your
-  distribution does not provide them.</para></listitem>
-
-  <listitem><para>The <link
-  xlink:href="http://www.hpl.hp.com/personal/Hans_Boehm/gc/">Boehm
-  garbage collector</link> to reduce the evaluator’s memory
-  consumption (optional).  To enable it, install
-  <literal>pkgconfig</literal> and the Boehm garbage collector, and
-  pass the flag <option>--enable-gc</option> to
-  <command>configure</command>.</para></listitem>
-
-  <listitem><para>The <command>xmllint</command> and
-  <command>xsltproc</command> programs to build this manual and the
-  man-pages.  These are part of the <literal>libxml2</literal> and
-  <literal>libxslt</literal> packages, respectively.  You also need
-  the <link
-  xlink:href="http://docbook.sourceforge.net/projects/xsl/">DocBook
-  XSL stylesheets</link> and optionally the <link
-  xlink:href="http://www.docbook.org/schemas/5x"> DocBook 5.0 RELAX NG
-  schemas</link>.  Note that these are only required if you modify the
-  manual sources or when you are building from the Git
-  repository.</para></listitem>
-
-  <listitem><para>Recent versions of Bison and Flex to build the
-  parser.  (This is because Nix needs GLR support in Bison and
-  reentrancy support in Flex.)  For Bison, you need version 2.6, which
-  can be obtained from the <link
-  xlink:href="ftp://alpha.gnu.org/pub/gnu/bison">GNU FTP
-  server</link>.  For Flex, you need version 2.5.35, which is
-  available on <link
-  xlink:href="http://lex.sourceforge.net/">SourceForge</link>.
-  Slightly older versions may also work, but ancient versions like the
-  ubiquitous 2.5.4a won't.  Note that these are only required if you
-  modify the parser or when you are building from the Git
-  repository.</para></listitem>
-
-</itemizedlist>
-
-</section>
-
-
-<section><title>Obtaining a source distribution</title>
-
-<para>The source tarball of the most recent stable release can be
-downloaded from the <link
-xlink:href="http://nixos.org/nix/download.html">Nix homepage</link>.
-You can also grab the <link
-xlink:href="http://hydra.nixos.org/job/nix/master/release/latest-finished#tabs-constituents">most
-recent development release</link>.</para>
-
-<para>Alternatively, the most recent sources of Nix can be obtained
-from its <link
-xlink:href="https://github.com/NixOS/nix">Git
-repository</link>.  For example, the following command will check out
-the latest revision into a directory called
-<filename>nix</filename>:</para>
-
-<screen>
-$ git clone https://github.com/NixOS/nix</screen>
-
-<para>Likewise, specific releases can be obtained from the <link
-xlink:href="https://github.com/NixOS/nix/tags">tags</link> of the
-repository.</para>
-
-</section>
-
-
-<section><title>Building Nix from source</title>
-
-<para>After unpacking or checking out the Nix sources, issue the
-following commands:
-
-<screen>
-$ ./configure <replaceable>options...</replaceable>
-$ make
-$ make install</screen>
-
-Nix requires GNU Make so you may need to invoke
-<command>gmake</command> instead.</para>
-
-<para>When building from the Git repository, these should be preceded
-by the command:
-
-<screen>
-$ ./bootstrap.sh</screen>
-
-</para>
-
-<para>The installation path can be specified by passing the
-<option>--prefix=<replaceable>prefix</replaceable></option> to
-<command>configure</command>.  The default installation directory is
-<filename>/usr/local</filename>.  You can change this to any location
-you like.  You must have write permission to the
-<replaceable>prefix</replaceable> path.</para>
-
-<para>Nix keeps its <emphasis>store</emphasis> (the place where
-packages are stored) in <filename>/nix/store</filename> by default.
-This can be changed using
-<option>--with-store-dir=<replaceable>path</replaceable></option>.</para>
-
-<warning><para>It is best <emphasis>not</emphasis> to change the Nix
-store from its default, since doing so makes it impossible to use
-pre-built binaries from the standard Nixpkgs channels — that is, all
-packages will need to be built from source.</para></warning>
-
-<para>Nix keeps state (such as its database and log files) in
-<filename>/nix/var</filename> by default.  This can be changed using
-<option>--localstatedir=<replaceable>path</replaceable></option>.</para>
-
-<para>If you want to rebuild the documentation, pass the full path to
-the DocBook RELAX NG schemas and to the DocBook XSL stylesheets using
-the
-<option>--with-docbook-rng=<replaceable>path</replaceable></option>
-and
-<option>--with-docbook-xsl=<replaceable>path</replaceable></option>
-options.</para>
-
-</section>
-
-
-</section>
-
-
-<!-- TODO: should be updated
-<section><title>Upgrading Nix through Nix</title>
-
-<para>You can install the latest stable version of Nix through Nix
-itself by subscribing to the channel <link
-xlink:href="http://nixos.org/releases/nix/channels/nix-stable" />,
-or the latest unstable version by subscribing to the channel <link
-xlink:href="http://nixos.org/releases/nix/channels/nix-unstable" />.
-You can also do a <link linkend="sec-one-click">one-click
-installation</link> by clicking on the package links at <link
-xlink:href="http://nixos.org/releases/full-index-nix.html" />.</para>
-
-</section>
--->
-
-
-<section><title>Security</title>
-
-<para>Nix has two basic security models.  First, it can be used in
-“single-user mode”, which is similar to what most other package
-management tools do: there is a single user (typically <systemitem
-class="username">root</systemitem>) who performs all package
-management operations.  All other users can then use the installed
-packages, but they cannot perform package management operations
-themselves.</para>
-
-<para>Alternatively, you can configure Nix in “multi-user mode”.  In
-this model, all users can perform package management operations — for
-instance, every user can install software without requiring root
-privileges.  Nix ensures that this is secure.  For instance, it’s not
-possible for one user to overwrite a package used by another user with
-a Trojan horse.</para>
-
-
-<section><title>Single-user mode</title>
-
-<para>In single-user mode, all Nix operations that access the database
-in <filename><replaceable>prefix</replaceable>/var/nix/db</filename>
-or modify the Nix store in
-<filename><replaceable>prefix</replaceable>/store</filename> must be
-performed under the user ID that owns those directories.  This is
-typically <systemitem class="username">root</systemitem>.  (If you
-install from RPM packages, that’s in fact the default ownership.)
-However, on single-user machines, it is often convenient to
-<command>chown</command> those directories to your normal user account
-so that you don’t have to <command>su</command> to <systemitem
-class="username">root</systemitem> all the time.</para>
-
-</section>
-
-
-<section xml:id="ssec-multi-user"><title>Multi-user mode</title>
-
-<para>To allow a Nix store to be shared safely among multiple users,
-it is important that users are not able to run builders that modify
-the Nix store or database in arbitrary ways, or that interfere with
-builds started by other users.  If they could do so, they could
-install a Trojan horse in some package and compromise the accounts of
-other users.</para>
-
-<para>To prevent this, the Nix store and database are owned by some
-privileged user (usually <literal>root</literal>) and builders are
-executed under special user accounts (usually named
-<literal>nixbld1</literal>, <literal>nixbld2</literal>, etc.).  When a
-unprivileged user runs a Nix command, actions that operate on the Nix
-store (such as builds) are forwarded to a <emphasis>Nix
-daemon</emphasis> running under the owner of the Nix store/database
-that performs the operation.</para>
-
-<note><para>Multi-user mode has one important limitation: only
-<systemitem class="username">root</systemitem> can run <command
-linkend="sec-nix-pull">nix-pull</command> to register the availability
-of pre-built binaries.  However, those registrations are shared by all
-users, so they still get the benefit from <command>nix-pull</command>s
-done by <systemitem class="username">root</systemitem>.</para></note>
-
-
-<section><title>Setting up the build users</title>
-
-<para>The <emphasis>build users</emphasis> are the special UIDs under
-which builds are performed.  They should all be members of the
-<emphasis>build users group</emphasis> <literal>nixbld</literal>.
-This group should have no other members.  The build users should not
-be members of any other group. On Linux, you can create the group and
-users as follows:
-
-<screen>
-$ groupadd -r nixbld
-$ for n in $(seq 1 10); do useradd -c "Nix build user $n" \
-    -d /var/empty -g nixbld -G nixbld -M -N -r -s "$(which nologin)" \
-    nixbld$n; done
-</screen>
-
-This creates 10 build users. There can never be more concurrent builds
-than the number of build users, so you may want to increase this if
-you expect to do many builds at the same time.</para>
-
-</section>
-
-
-<section><title>Running the daemon</title>
-
-<para>The <link linkend="sec-nix-daemon">Nix daemon</link> should be
-started as follows (as <literal>root</literal>):
-
-<screen>
-$ nix-daemon</screen>
-
-You’ll want to put that line somewhere in your system’s boot
-scripts.</para>
-
-<para>To let unprivileged users use the daemon, they should set the
-<link linkend="envar-remote"><envar>NIX_REMOTE</envar> environment
-variable</link> to <literal>daemon</literal>.  So you should put a
-line like
-
-<programlisting>
-export NIX_REMOTE=daemon</programlisting>
-
-into the users’ login scripts.</para>
-
-</section>
-
-
-<section><title>Restricting access</title>
-
-<para>To limit which users can perform Nix operations, you can use the
-permissions on the directory
-<filename>/nix/var/nix/daemon-socket</filename>.  For instance, if you
-want to restrict the use of Nix to the members of a group called
-<literal>nix-users</literal>, do
-
-<screen>
-$ chgrp nix-users /nix/var/nix/daemon-socket
-$ chmod ug=rwx,o= /nix/var/nix/daemon-socket
-</screen>
-
-This way, users who are not in the <literal>nix-users</literal> group
-cannot connect to the Unix domain socket
-<filename>/nix/var/nix/daemon-socket/socket</filename>, so they cannot
-perform Nix operations.</para>
-
-</section>
-
-
-</section> <!-- end of multi-user -->
-
-
-</section> <!-- end of security -->
-
-
-<section><title>Using Nix</title>
-
-<para>To use Nix, some environment variables should be set.  In
-particular, <envar>PATH</envar> should contain the directories
-<filename><replaceable>prefix</replaceable>/bin</filename> and
-<filename>~/.nix-profile/bin</filename>.  The first directory contains
-the Nix tools themselves, while <filename>~/.nix-profile</filename> is
-a symbolic link to the current <emphasis>user environment</emphasis>
-(an automatically generated package consisting of symlinks to
-installed packages).  The simplest way to set the required environment
-variables is to include the file
-<filename><replaceable>prefix</replaceable>/etc/profile.d/nix.sh</filename>
-in your <filename>~/.profile</filename> (or similar), like this:</para>
-
-<screen>
-source <replaceable>prefix</replaceable>/etc/profile.d/nix.sh</screen>
-
-</section>
-
-
-</chapter>

doc/manual/installation/building-source.xml

@@ -0,0 +1,57 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-building-source">
+
+<title>Building Nix from Source</title>
+
+<para>After unpacking or checking out the Nix sources, issue the
+following commands:
+
+<screen>
+$ ./configure <replaceable>options...</replaceable>
+$ make
+$ make install</screen>
+
+Nix requires GNU Make so you may need to invoke
+<command>gmake</command> instead.</para>
+
+<para>When building from the Git repository, these should be preceded
+by the command:
+
+<screen>
+$ ./bootstrap.sh</screen>
+
+</para>
+
+<para>The installation path can be specified by passing the
+<option>--prefix=<replaceable>prefix</replaceable></option> to
+<command>configure</command>.  The default installation directory is
+<filename>/usr/local</filename>.  You can change this to any location
+you like.  You must have write permission to the
+<replaceable>prefix</replaceable> path.</para>
+
+<para>Nix keeps its <emphasis>store</emphasis> (the place where
+packages are stored) in <filename>/nix/store</filename> by default.
+This can be changed using
+<option>--with-store-dir=<replaceable>path</replaceable></option>.</para>
+
+<warning><para>It is best <emphasis>not</emphasis> to change the Nix
+store from its default, since doing so makes it impossible to use
+pre-built binaries from the standard Nixpkgs channels — that is, all
+packages will need to be built from source.</para></warning>
+
+<para>Nix keeps state (such as its database and log files) in
+<filename>/nix/var</filename> by default.  This can be changed using
+<option>--localstatedir=<replaceable>path</replaceable></option>.</para>
+
+<para>If you want to rebuild the documentation, pass the full path to
+the DocBook RELAX NG schemas and to the DocBook XSL stylesheets using
+the
+<option>--with-docbook-rng=<replaceable>path</replaceable></option>
+and
+<option>--with-docbook-xsl=<replaceable>path</replaceable></option>
+options.</para>
+
+</section>

doc/manual/installation/env-variables.xml

@@ -0,0 +1,24 @@
+<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-env-variables">
+
+<title>Environment Variables</title>
+
+<para>To use Nix, some environment variables should be set.  In
+particular, <envar>PATH</envar> should contain the directories
+<filename><replaceable>prefix</replaceable>/bin</filename> and
+<filename>~/.nix-profile/bin</filename>.  The first directory contains
+the Nix tools themselves, while <filename>~/.nix-profile</filename> is
+a symbolic link to the current <emphasis>user environment</emphasis>
+(an automatically generated package consisting of symlinks to
+installed packages).  The simplest way to set the required environment
+variables is to include the file
+<filename><replaceable>prefix</replaceable>/etc/profile.d/nix.sh</filename>
+in your <filename>~/.profile</filename> (or similar), like this:</para>
+
+<screen>
+source <replaceable>prefix</replaceable>/etc/profile.d/nix.sh</screen>
+
+</chapter>

doc/manual/installation/installation.xml

@@ -0,0 +1,34 @@
+<part 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="chap-installation">
+
+<title>Installation</title>
+
+<partintro>
+<para>This section describes how to install and configure Nix for first-time use.</para>
+</partintro>
+
+<xi:include href="supported-platforms.xml" />
+<xi:include href="installing-binary.xml" />
+<xi:include href="installing-source.xml" />
+<xi:include href="nix-security.xml" />
+<xi:include href="env-variables.xml" />
+
+<!-- TODO: should be updated
+<section><title>Upgrading Nix through Nix</title>
+
+<para>You can install the latest stable version of Nix through Nix
+itself by subscribing to the channel <link
+xlink:href="http://nixos.org/releases/nix/channels/nix-stable" />,
+or the latest unstable version by subscribing to the channel <link
+xlink:href="http://nixos.org/releases/nix/channels/nix-unstable" />.
+You can also do a <link linkend="sec-one-click">one-click
+installation</link> by clicking on the package links at <link
+xlink:href="http://nixos.org/releases/full-index-nix.html" />.</para>
+
+</section>
+-->
+
+</part>

doc/manual/installation/installing-binary.xml

@@ -0,0 +1,81 @@
+<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-installing-binary">
+
+<title>Installing a Binary Distribution</title>
+
+<para>The easiest way to install Nix is to run the following command:
+
+<screen>
+$ bash &lt;(curl https://nixos.org/nix/install)
+</screen>
+
+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
+root.  The script will invoke <command>sudo</command> to create
+<filename>/nix</filename> if it doesn’t already exist.  If you don’t
+have <command>sudo</command>, you should manually create
+<command>/nix</command> first as root:
+
+<screen>
+$ mkdir /nix
+$ chown alice /nix
+</screen>
+
+</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, Mac OS X 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.7-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.7-1_amd64.deb</screen>
+
+</para>
+
+<para>For other platforms, including Mac OS X (Darwin), FreeBSD and
+other Linux distributions, you can 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> uses.)  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.7-x86_64-darwin.tar.bz2
+alice$ cd nix-1.7-x86_64-darwin
+alice$ ./install
+</screen>
+
+</para>
+
+<para>Nix can be uninstalled using <command>rpm -e nix</command> or
+<command>dpkg -r nix</command> on RPM- and Dpkg-based systems,
+respectively.  After this you should manually remove the Nix store and
+other auxiliary data, if desired:
+
+<screen>
+$ rm -rf /nix</screen>
+
+</para>
+
+</chapter>

doc/manual/installation/installing-source.xml

@@ -0,0 +1,17 @@
+<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-installing-source">
+
+<title>Installing Nix from Source</title>
+
+<para>If no binary package is available, you can download and compile
+a source distribution.</para>
+
+<xi:include href="prerequisites-source.xml" />
+<xi:include href="obtaining-source.xml" />
+<xi:include href="installing-source.xml" />
+<xi:include href="building-source.xml" />
+
+</chapter>

doc/manual/installation/multi-user.xml

@@ -0,0 +1,106 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="ssec-multi-user">
+
+<title>Multi-User Mode</title>
+
+<para>To allow a Nix store to be shared safely among multiple users,
+it is important that users are not able to run builders that modify
+the Nix store or database in arbitrary ways, or that interfere with
+builds started by other users.  If they could do so, they could
+install a Trojan horse in some package and compromise the accounts of
+other users.</para>
+
+<para>To prevent this, the Nix store and database are owned by some
+privileged user (usually <literal>root</literal>) and builders are
+executed under special user accounts (usually named
+<literal>nixbld1</literal>, <literal>nixbld2</literal>, etc.).  When a
+unprivileged user runs a Nix command, actions that operate on the Nix
+store (such as builds) are forwarded to a <emphasis>Nix
+daemon</emphasis> running under the owner of the Nix store/database
+that performs the operation.</para>
+
+<note>Multi-user mode has one important limitation: only
+<systemitem class="username">root</systemitem> can run <command
+linkend="sec-nix-pull">nix-pull</command> to register the availability
+of pre-built binaries.  However, those registrations are shared by all
+users, so they still get the benefit from <command>nix-pull</command>s
+done by <systemitem class="username">root</systemitem>.</note>
+
+
+<simplesect>
+
+<title>Setting up the build users</title>
+
+<para>The <emphasis>build users</emphasis> are the special UIDs under
+which builds are performed.  They should all be members of the
+<emphasis>build users group</emphasis> <literal>nixbld</literal>.
+This group should have no other members.  The build users should not
+be members of any other group. On Linux, you can create the group and
+users as follows:
+
+<screen>
+$ groupadd -r nixbld
+$ for n in $(seq 1 10); do useradd -c "Nix build user $n" \
+    -d /var/empty -g nixbld -G nixbld -M -N -r -s "$(which nologin)" \
+    nixbld$n; done
+</screen>
+
+This creates 10 build users. There can never be more concurrent builds
+than the number of build users, so you may want to increase this if
+you expect to do many builds at the same time.</para>
+
+</simplesect>
+
+
+<simplesect>
+
+<title>Running the daemon</title>
+
+<para>The <link linkend="sec-nix-daemon">Nix daemon</link> should be
+started as follows (as <literal>root</literal>):
+
+<screen>
+$ nix-daemon</screen>
+
+You’ll want to put that line somewhere in your system’s boot
+scripts.</para>
+
+<para>To let unprivileged users use the daemon, they should set the
+<link linkend="envar-remote"><envar>NIX_REMOTE</envar> environment
+variable</link> to <literal>daemon</literal>.  So you should put a
+line like
+
+<programlisting>
+export NIX_REMOTE=daemon</programlisting>
+
+into the users’ login scripts.</para>
+
+</simplesect>
+
+<simplesect>
+
+<title>Restricting access</title>
+
+<para>To limit which users can perform Nix operations, you can use the
+permissions on the directory
+<filename>/nix/var/nix/daemon-socket</filename>.  For instance, if you
+want to restrict the use of Nix to the members of a group called
+<literal>nix-users</literal>, do
+
+<screen>
+$ chgrp nix-users /nix/var/nix/daemon-socket
+$ chmod ug=rwx,o= /nix/var/nix/daemon-socket
+</screen>
+
+This way, users who are not in the <literal>nix-users</literal> group
+cannot connect to the Unix domain socket
+<filename>/nix/var/nix/daemon-socket/socket</filename>, so they cannot
+perform Nix operations.</para>
+
+</simplesect>
+
+
+</section>

doc/manual/installation/nix-security.xml

@@ -0,0 +1,27 @@
+<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-nix-security">
+
+<title>Security</title>
+
+<para>Nix has two basic security models.  First, it can be used in
+“single-user mode”, which is similar to what most other package
+management tools do: there is a single user (typically <systemitem
+class="username">root</systemitem>) who performs all package
+management operations.  All other users can then use the installed
+packages, but they cannot perform package management operations
+themselves.</para>
+
+<para>Alternatively, you can configure Nix in “multi-user mode”.  In
+this model, all users can perform package management operations — for
+instance, every user can install software without requiring root
+privileges.  Nix ensures that this is secure.  For instance, it’s not
+possible for one user to overwrite a package used by another user with
+a Trojan horse.</para>
+
+<xi:include href="single-user.xml" />
+<xi:include href="multi-user.xml" />
+
+</chapter>

doc/manual/installation/obtaining-source.xml

@@ -0,0 +1,30 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-obtaining-source">
+
+<title>Obtaining a Source Distribution</title>
+
+<para>The source tarball of the most recent stable release can be
+downloaded from the <link
+xlink:href="http://nixos.org/nix/download.html">Nix homepage</link>.
+You can also grab the <link
+xlink:href="http://hydra.nixos.org/job/nix/master/release/latest-finished#tabs-constituents">most
+recent development release</link>.</para>
+
+<para>Alternatively, the most recent sources of Nix can be obtained
+from its <link
+xlink:href="https://github.com/NixOS/nix">Git
+repository</link>.  For example, the following command will check out
+the latest revision into a directory called
+<filename>nix</filename>:</para>
+
+<screen>
+$ git clone https://github.com/NixOS/nix</screen>
+
+<para>Likewise, specific releases can be obtained from the <link
+xlink:href="https://github.com/NixOS/nix/tags">tags</link> of the
+repository.</para>
+
+</section>

doc/manual/installation/prerequisites-source.xml

@@ -0,0 +1,73 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-prerequisites-source">
+
+<title>Prerequisites</title>
+
+<itemizedlist>
+
+  <listitem><para>GNU Make.</para></listitem>
+
+  <listitem><para>A version of GCC or Clang that supports C++11.</para></listitem>
+
+  <listitem><para>Perl 5.8 or higher.</para></listitem>
+
+  <listitem><para><command>pkg-config</command> to locate
+  dependencies.  If your distribution does not provide it, you can get
+  it from <link
+  xlink:href="http://www.freedesktop.org/wiki/Software/pkg-config"
+  />.</para></listitem>
+
+  <listitem><para>The bzip2 compressor program and the
+  <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>
+
+  <listitem><para>The SQLite embedded database library, version 3.6.19
+  or higher.  If your distribution does not provide it, please install
+  it from <link xlink:href="http://www.sqlite.org/" />.</para></listitem>
+
+  <listitem><para>The Perl DBI and DBD::SQLite libraries, which are
+  available from <link
+  xlink:href="http://search.cpan.org/">CPAN</link> if your
+  distribution does not provide them.</para></listitem>
+
+  <listitem><para>The <link
+  xlink:href="http://www.hpl.hp.com/personal/Hans_Boehm/gc/">Boehm
+  garbage collector</link> to reduce the evaluator’s memory
+  consumption (optional).  To enable it, install
+  <literal>pkgconfig</literal> and the Boehm garbage collector, and
+  pass the flag <option>--enable-gc</option> to
+  <command>configure</command>.</para></listitem>
+
+  <listitem><para>The <command>xmllint</command> and
+  <command>xsltproc</command> programs to build this manual and the
+  man-pages.  These are part of the <literal>libxml2</literal> and
+  <literal>libxslt</literal> packages, respectively.  You also need
+  the <link
+  xlink:href="http://docbook.sourceforge.net/projects/xsl/">DocBook
+  XSL stylesheets</link> and optionally the <link
+  xlink:href="http://www.docbook.org/schemas/5x"> DocBook 5.0 RELAX NG
+  schemas</link>.  Note that these are only required if you modify the
+  manual sources or when you are building from the Git
+  repository.</para></listitem>
+
+  <listitem><para>Recent versions of Bison and Flex to build the
+  parser.  (This is because Nix needs GLR support in Bison and
+  reentrancy support in Flex.)  For Bison, you need version 2.6, which
+  can be obtained from the <link
+  xlink:href="ftp://alpha.gnu.org/pub/gnu/bison">GNU FTP
+  server</link>.  For Flex, you need version 2.5.35, which is
+  available on <link
+  xlink:href="http://lex.sourceforge.net/">SourceForge</link>.
+  Slightly older versions may also work, but ancient versions like the
+  ubiquitous 2.5.4a won't.  Note that these are only required if you
+  modify the parser or when you are building from the Git
+  repository.</para></listitem>
+
+</itemizedlist>
+
+</section>

doc/manual/installation/single-user.xml

@@ -0,0 +1,21 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-single-user">
+
+<title>Single-User Mode</title>
+
+<para>In single-user mode, all Nix operations that access the database
+in <filename><replaceable>prefix</replaceable>/var/nix/db</filename>
+or modify the Nix store in
+<filename><replaceable>prefix</replaceable>/store</filename> must be
+performed under the user ID that owns those directories.  This is
+typically <systemitem class="username">root</systemitem>.  (If you
+install from RPM packages, that’s in fact the default ownership.)
+However, on single-user machines, it is often convenient to
+<command>chown</command> those directories to your normal user account
+so that you don’t have to <command>su</command> to <systemitem
+class="username">root</systemitem> all the time.</para>
+
+</section>

doc/manual/installation/supported-platforms.xml

@@ -0,0 +1,38 @@
+<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-supported-platforms">
+
+<title>Supported Platforms</title>
+
+<para>Nix is currently supported on the following platforms:
+
+<itemizedlist>
+
+  <listitem><para>Linux (particularly on x86, x86_64, and
+  PowerPC).</para></listitem>
+
+  <listitem><para>Mac OS X.</para></listitem>
+
+  <listitem><para>FreeBSD (only tested on Intel).</para></listitem>
+
+  <!--
+  <listitem><para>Windows through <link
+  xlink:href="http://www.cygwin.com/">Cygwin</link>.</para>
+
+  <warning><para>On Cygwin, Nix <emphasis>must</emphasis> be installed
+  on an NTFS partition.  It will not work correctly on a FAT
+  partition.</para></warning>
+
+  </listitem>
+  -->
+
+</itemizedlist>
+
+</para>
+
+<para>Nix is pretty portable, so it should work on most other Unix
+platforms as well.</para>
+
+</chapter>

doc/manual/introduction/about-nix.xml

@@ -1,11 +1,10 @@
 <chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="chap-introduction">
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="ch-about-nix">
 
-<title>Introduction</title>
+<title>About Nix</title>
-
-
-<section><title>About Nix</title>
 
 <para>Nix is a <emphasis>purely functional package manager</emphasis>.
 This means that it treats packages like values in purely functional
@@ -251,23 +250,4 @@ xlink:href="http://nixos.org/">NixOS homepage</link>.</para>
 
 -->
 
-</section>
+</chapter>
-
-
-<section><title>License</title>
-
-<para>Nix is free software; you can redistribute it and/or modify it
-under the terms of the <link
-xlink:href="http://www.gnu.org/licenses/lgpl.html">GNU Lesser General
-Public License</link> as published by the <link
-xlink:href="http://www.fsf.org/">Free Software Foundation</link>;
-either version 2.1 of the License, or (at your option) any later
-version.  Nix is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-Lesser General Public License for more details.</para>
-
-</section>
-
-
-</chapter>

doc/manual/introduction/introduction.xml

@@ -0,0 +1,16 @@
+<part 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="chap-introduction">
+
+<title>Introduction</title>
+
+<partintro>
+<para>This section describes the main features of Nix and the license under which you can use Nix.</para>
+</partintro>
+
+<xi:include href="about-nix.xml" />
+<xi:include href="nix-license.xml" />
+
+</part>

doc/manual/introduction/nix-license.xml

@@ -0,0 +1,20 @@
+<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-nix-license">
+
+<title>License</title>
+
+<para>Nix is free software; you can redistribute it and/or modify it
+under the terms of the <link
+xlink:href="http://www.gnu.org/licenses/lgpl.html">GNU Lesser General
+Public License</link> as published by the <link
+xlink:href="http://www.fsf.org/">Free Software Foundation</link>;
+either version 2.1 of the License, or (at your option) any later
+version.  Nix is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.</para>
+
+</chapter>

doc/manual/manual.xml

@@ -1,9 +1,12 @@
 <book xmlns="http://docbook.org/ns/docbook"
-      xmlns:xi="http://www.w3.org/2001/XInclude">
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="NixManual">
 
   <info>
 
-    <title>Nix User's Guide</title>
+    <title>Nix Package Manager Guide</title>
 
     <edition>Version <xi:include href="version.txt" parse="text" /></edition>
 
@@ -27,58 +30,30 @@
 
   </info>
 
+<preface>
+<title>Preface</title>
+<para>This manual describes how to set up and use Nix package manager and Nix expressions.</para>
+</preface>
 
-  <xi:include href="introduction.xml" />
+  <xi:include href="introduction/introduction.xml" />
-  <xi:include href="quick-start.xml" />
+  <xi:include href="quicks-start/quick-start.xml" />
-  <xi:include href="installation.xml" />
+  <xi:include href="installation/installation.xml" />
-  <xi:include href="package-management.xml" />
+  <xi:include href="packages/package-management.xml" />
-  <xi:include href="writing-nix-expressions.xml" />
+  <xi:include href="expressions/writing-nix-expressions.xml" />
-  <xi:include href="build-farm.xml" />
+  <xi:include href="builds/build-farm.xml" />
-
+  <xi:include href="command-ref/command-ref.xml" />
-
+  <xi:include href="troubleshooting/troubleshooting.xml" />
-  <appendix>
-    <title>Command Reference</title>
-    <xi:include href="opt-common.xml" />
-    <xi:include href="env-common.xml" />
-
-    <section>
-      <title>Main commands</title>
-      <xi:include href="nix-env.xml" />
-      <xi:include href="nix-build.xml" />
-      <xi:include href="nix-shell.xml" />
-      <xi:include href="nix-store.xml" />
-    </section>
-
-    <section>
-      <title>Utilities</title>
-      <xi:include href="nix-channel.xml" />
-      <xi:include href="nix-collect-garbage.xml" />
-      <xi:include href="nix-copy-closure.xml" />
-      <xi:include href="nix-daemon.xml" />
-      <xi:include href="nix-hash.xml" />
-      <xi:include href="nix-install-package.xml" />
-      <xi:include href="nix-instantiate.xml" />
-      <xi:include href="nix-prefetch-url.xml" />
-      <xi:include href="nix-pull.xml" />
-      <xi:include href="nix-push.xml" />
-    </section>
-
-    <section>
-      <title>Files</title>
-      <xi:include href="conf-file.xml" />
-    </section>
-
-  </appendix>
-
-  <xi:include href="troubleshooting.xml" />
   <!-- <xi:include href="bugs.xml" /> -->
-  <xi:include href="glossary.xml" />
+  <xi:include href="glossary/glossary.xml" />
   <xi:include href="hacking.xml" />
-
+  <xi:include href="release-notes/release-notes.xml" />
-  <appendix>
+  
+<!-- 
+<appendix>
     <title>Nix Release Notes</title>
-    <xi:include href="release-notes.xml"
+    <xi:include href="release-notes/release-notes.xml"
                 xpointer="xmlns(x=http://docbook.org/ns/docbook)xpointer(x:article/x:section)" />
   </appendix>
+-->
 
 </book>

doc/manual/package-management.xml

@@ -1,591 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id='chap-package-management'>
-
-<title>Package Management</title>
-
-
-<para>This chapter discusses how to do package management with Nix,
-i.e., how to obtain, install, upgrade, and erase packages.  This is
-the “user’s” perspective of the Nix system — people
-who want to <emphasis>create</emphasis> packages should consult
-<xref linkend='chap-writing-nix-expressions' />.</para>
-
-
-<section><title>Basic package management</title>
-
-<para>The main command for package management is <link
-linkend="sec-nix-env"><command>nix-env</command></link>.  You can use
-it to install, upgrade, and erase packages, and to query what
-packages are installed or are available for installation.</para>
-
-<para>In Nix, different users can have different “views”
-on the set of installed applications.  That is, there might be lots of
-applications present on the system (possibly in many different
-versions), but users can have a specific selection of those active —
-where “active” just means that it appears in a directory
-in the user’s <envar>PATH</envar>.  Such a view on the set of
-installed applications is called a <emphasis>user
-environment</emphasis>, which is just a directory tree consisting of
-symlinks to the files of the active applications.  </para>
-
-<para>Components are installed from a set of <emphasis>Nix
-expressions</emphasis> that tell Nix how to build those packages,
-including, if necessary, their dependencies.  There is a collection of
-Nix expressions called the Nix Package collection that contains
-packages ranging from basic development stuff such as GCC and Glibc,
-to end-user applications like Mozilla Firefox.  (Nix is however not
-tied to the Nix Package collection; you could write your own Nix
-expressions based on it, or completely new ones.)  You can download
-the latest version from <link
-xlink:href='http://nixos.org/nixpkgs/download.html' />.</para>
-
-<para>Assuming that you have downloaded and unpacked a release of Nix
-Packages, you can view the set of available packages in the release:
-
-<screen>
-$ nix-env -qaf nixpkgs-<replaceable>version</replaceable> '*'
-ant-blackdown-1.4.2
-aterm-2.2
-bash-3.0
-binutils-2.15
-bison-1.875d
-blackdown-1.4.2
-bzip2-1.0.2
-...</screen>
-
-where <literal>nixpkgs-<replaceable>version</replaceable></literal> is
-where you’ve unpacked the release.  The flag <option>-q</option>
-specifies a query operation; <option>-a</option> means that you want
-to show the “available” (i.e., installable) packages, as opposed to
-the installed packages; and <option>-f</option>
-<filename>nixpkgs-<replaceable>version</replaceable></filename>
-specifies the source of the packages.  The argument
-<literal>'*'</literal> shows all installable packages. (The quotes are
-necessary to prevent shell expansion.)  You can also select specific
-packages by name:
-
-<screen>
-$ nix-env -qaf nixpkgs-<replaceable>version</replaceable> gcc
-gcc-3.4.6
-gcc-4.0.3
-gcc-4.1.1</screen>
-
-</para>
-
-<para>It is also possible to see the <emphasis>status</emphasis> of
-available packages, i.e., whether they are installed into the user
-environment and/or present in the system:
-
-<screen>
-$ nix-env -qasf nixpkgs-<replaceable>version</replaceable> '*'
-...
--PS bash-3.0
---S binutils-2.15
-IPS bison-1.875d
-...</screen>
-
-The first character (<literal>I</literal>) indicates whether the
-package is installed in your current user environment.  The second
-(<literal>P</literal>) indicates whether it is present on your system
-(in which case installing it into your user environment would be a
-very quick operation).  The last one (<literal>S</literal>) indicates
-whether there is a so-called <emphasis>substitute</emphasis> for the
-package, which is Nix’s mechanism for doing binary deployment.  It
-just means that Nix knows that it can fetch a pre-built package from
-somewhere (typically a network server) instead of building it
-locally.</para>
-
-<para>So now that we have a set of Nix expressions we can build the
-packages contained in them.  This is done using <literal>nix-env
--i</literal>.  For instance,
-
-<screen>
-$ nix-env -f nixpkgs-<replaceable>version</replaceable> -i subversion</screen>
-
-will install the package called <literal>subversion</literal> (which
-is, of course, the <link
-xlink:href='http://subversion.tigris.org/'>Subversion version
-management system</link>).</para>
-
-<para>When you do this for the first time, Nix will start building
-Subversion and all its dependencies.  This will take quite a while —
-typically an hour or two on modern machines.  Fortunately, there is a
-faster way (so do a Ctrl-C on that install operation!): you just need
-to tell Nix that pre-built binaries of all those packages are
-available somewhere.  This is done using the
-<command>nix-pull</command> command, which must be supplied with a URL
-containing a <emphasis>manifest</emphasis> describing what binaries
-are available.  This URL should correspond to the Nix Packages release
-that you’re using.  For instance, if you obtained a release from <link
-xlink:href='http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x'
-/>, then you should do:
-
-<screen>
-$ nix-pull http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x/MANIFEST</screen>
-
-If you then issue the installation command, it should start
-downloading binaries from <systemitem
-class='fqdomainname'>nixos.org</systemitem>, instead of building
-them from source.  This might still take a while since all
-dependencies must be downloaded, but on a reasonably fast connection
-such as a DSL line it’s on the order of a few minutes.</para>
-
-<para>Naturally, packages can also be uninstalled:
-
-<screen>
-$ nix-env -e subversion</screen>
-
-</para>
-
-<para>Upgrading to a new version is just as easy.  If you have a new
-release of Nix Packages, you can do:
-
-<screen>
-$ nix-env -f nixpkgs-<replaceable>version</replaceable> -u subversion</screen>
-
-This will <emphasis>only</emphasis> upgrade Subversion if there is a
-“newer” version in the new set of Nix expressions, as
-defined by some pretty arbitrary rules regarding ordering of version
-numbers (which generally do what you’d expect of them).  To just
-unconditionally replace Subversion with whatever version is in the Nix
-expressions, use <parameter>-i</parameter> instead of
-<parameter>-u</parameter>; <parameter>-i</parameter> will remove
-whatever version is already installed.</para>
-
-<para>You can also upgrade all packages for which there are newer
-versions:
-
-<screen>
-$ nix-env -f nixpkgs-<replaceable>version</replaceable> -u '*'</screen>
-
-</para>
-
-<para>Sometimes it’s useful to be able to ask what
-<command>nix-env</command> would do, without actually doing it.  For
-instance, to find out what packages would be upgraded by
-<literal>nix-env -u '*'</literal>, you can do
-
-<screen>
-$ nix-env ... -u '*' --dry-run
-(dry run; not doing anything)
-upgrading `libxslt-1.1.0' to `libxslt-1.1.10'
-upgrading `graphviz-1.10' to `graphviz-1.12'
-upgrading `coreutils-5.0' to `coreutils-5.2.1'</screen>
-
-</para>
-
-</section>
-
-
-<section xml:id="sec-profiles"><title>Profiles</title>
-
-<para>Profiles and user environments are Nix’s mechanism for
-implementing the ability to allow different users to have different
-configurations, and to do atomic upgrades and rollbacks.  To
-understand how they work, it’s useful to know a bit about how Nix
-works.  In Nix, packages are stored in unique locations in the
-<emphasis>Nix store</emphasis> (typically,
-<filename>/nix/store</filename>).  For instance, a particular version
-of the Subversion package might be stored in a directory
-<filename>/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3/</filename>,
-while another version might be stored in
-<filename>/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2</filename>.
-The long strings prefixed to the directory names are cryptographic
-hashes<footnote><para>160-bit truncations of SHA-256 hashes encoded in
-a base-32 notation, to be precise.</para></footnote> of
-<emphasis>all</emphasis> inputs involved in building the package —
-sources, dependencies, compiler flags, and so on.  So if two
-packages differ in any way, they end up in different locations in
-the file system, so they don’t interfere with each other.  <xref
-linkend='fig-user-environments' /> shows a part of a typical Nix
-store.</para>
-
-<figure xml:id='fig-user-environments'><title>User environments</title>
-  <mediaobject>
-    <imageobject>
-      <imagedata fileref='figures/user-environments.png' format='PNG' />
-    </imageobject>
-  </mediaobject>
-</figure>
-
-<para>Of course, you wouldn’t want to type
-
-<screen>
-$ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn</screen>
-
-every time you want to run Subversion.  Of course we could set up the
-<envar>PATH</envar> environment variable to include the
-<filename>bin</filename> directory of every package we want to use,
-but this is not very convenient since changing <envar>PATH</envar>
-doesn’t take effect for already existing processes.  The solution Nix
-uses is to create directory trees of symlinks to
-<emphasis>activated</emphasis> packages.  These are called
-<emphasis>user environments</emphasis> and they are packages
-themselves (though automatically generated by
-<command>nix-env</command>), so they too reside in the Nix store.  For
-instance, in <xref linkend='fig-user-environments' /> the user
-environment <filename>/nix/store/0c1p5z4kda11...-user-env</filename>
-contains a symlink to just Subversion 1.1.2 (arrows in the figure
-indicate symlinks).  This would be what we would obtain if we had done
-
-<screen>
-$ nix-env -i subversion</screen>
-
-on a set of Nix expressions that contained Subversion 1.1.2.</para>
-
-<para>This doesn’t in itself solve the problem, of course; you
-wouldn’t want to type
-<filename>/nix/store/0c1p5z4kda11...-user-env/bin/svn</filename>
-either.  That’s why there are symlinks outside of the store that point
-to the user environments in the store; for instance, the symlinks
-<filename>default-42-link</filename> and
-<filename>default-43-link</filename> in the example.  These are called
-<emphasis>generations</emphasis> since every time you perform a
-<command>nix-env</command> operation, a new user environment is
-generated based on the current one.  For instance, generation 43 was
-created from generation 42 when we did
-
-<screen>
-$ nix-env -i subversion mozilla</screen>
-
-on a set of Nix expressions that contained Mozilla and a new version
-of Subversion.</para>
-
-<para>Generations are grouped together into
-<emphasis>profiles</emphasis> so that different users don’t interfere
-with each other if they don’t want to.  For example:
-
-<screen>
-$ ls -l /nix/var/nix/profiles/
-...
-lrwxrwxrwx  1 eelco ... default-42-link -> /nix/store/0c1p5z4kda11...-user-env
-lrwxrwxrwx  1 eelco ... default-43-link -> /nix/store/3aw2pdyx2jfc...-user-env
-lrwxrwxrwx  1 eelco ... default -> default-43-link</screen>
-
-This shows a profile called <filename>default</filename>.  The file
-<filename>default</filename> itself is actually a symlink that points
-to the current generation.  When we do a <command>nix-env</command>
-operation, a new user environment and generation link are created
-based on the current one, and finally the <filename>default</filename>
-symlink is made to point at the new generation.  This last step is
-atomic on Unix, which explains how we can do atomic upgrades.  (Note
-that the building/installing of new packages doesn’t interfere in
-any way with old packages, since they are stored in different
-locations in the Nix store.)</para>
-
-<para>If you find that you want to undo a <command>nix-env</command>
-operation, you can just do
-
-<screen>
-$ nix-env --rollback</screen>
-
-which will just make the current generation link point at the previous
-link.  E.g., <filename>default</filename> would be made to point at
-<filename>default-42-link</filename>.  You can also switch to a
-specific generation:
-
-<screen>
-$ nix-env --switch-generation 43</screen>
-
-which in this example would roll forward to generation 43 again.  You
-can also see all available generations:
-
-<screen>
-$ nix-env --list-generations</screen></para>
-
-<para>Actually, there is another level of indirection not shown in the
-figure above.  You generally wouldn’t have
-<filename>/nix/var/nix/profiles/<replaceable>some-profile</replaceable>/bin</filename>
-in your <envar>PATH</envar>.  Rather, there is a symlink
-<filename>~/.nix-profile</filename> that points to your current
-profile.  This means that you should put
-<filename>~/.nix-profile/bin</filename> in your <envar>PATH</envar>
-(and indeed, that’s what the initialisation script
-<filename>/nix/etc/profile.d/nix.sh</filename> does).  This makes it
-easier to switch to a different profile.  You can do that using the
-command <command>nix-env --switch-profile</command>:
-
-<screen>
-$ nix-env --switch-profile /nix/var/nix/profiles/my-profile
-
-$ nix-env --switch-profile /nix/var/nix/profiles/default</screen>
-
-These commands switch to the <filename>my-profile</filename> and
-default profile, respectively.  If the profile doesn’t exist, it will
-be created automatically.  You should be careful about storing a
-profile in another location than the <filename>profiles</filename>
-directory, since otherwise it might not be used as a root of the
-garbage collector (see <xref linkend='sec-garbage-collection'
-/>).</para>
-
-<para>All <command>nix-env</command> operations work on the profile
-pointed to by <command>~/.nix-profile</command>, but you can override
-this using the <option>--profile</option> option (abbreviation
-<option>-p</option>):
-
-<screen>
-$ nix-env -p /nix/var/nix/profiles/other-profile -i subversion</screen>
-
-This will <emphasis>not</emphasis> change the
-<command>~/.nix-profile</command> symlink.</para>
-
-</section>
-
-
-<section xml:id='sec-garbage-collection'><title>Garbage collection</title>
-
-<para><command>nix-env</command> operations such as upgrades
-(<option>-u</option>) and uninstall (<option>-e</option>) never
-actually delete packages from the system.  All they do (as shown
-above) is to create a new user environment that no longer contains
-symlinks to the “deleted” packages.</para>
-
-<para>Of course, since disk space is not infinite, unused packages
-should be removed at some point.  You can do this by running the Nix
-garbage collector.  It will remove from the Nix store any package
-not used (directly or indirectly) by any generation of any
-profile.</para>
-
-<para>Note however that as long as old generations reference a
-package, it will not be deleted.  After all, we wouldn’t be able to
-do a rollback otherwise.  So in order for garbage collection to be
-effective, you should also delete (some) old generations.  Of course,
-this should only be done if you are certain that you will not need to
-roll back.</para>
-
-<para>To delete all old (non-current) generations of your current
-profile:
-
-<screen>
-$ nix-env --delete-generations old</screen>
-
-Instead of <literal>old</literal> you can also specify a list of
-generations, e.g.,
-
-<screen>
-$ nix-env --delete-generations 10 11 14</screen>
-
-</para>
-
-<para>After removing appropriate old generations you can run the
-garbage collector as follows:
-
-<screen>
-$ nix-store --gc</screen>
-
-If you are feeling uncertain, you can also first view what files would
-be deleted:
-
-<screen>
-$ nix-store --gc --print-dead</screen>
-
-Likewise, the option <option>--print-live</option> will show the paths
-that <emphasis>won’t</emphasis> be deleted.</para>
-
-<para>There is also a convenient little utility
-<command>nix-collect-garbage</command>, which when invoked with the
-<option>-d</option> (<option>--delete-old</option>) switch deletes all
-old generations of all profiles in
-<filename>/nix/var/nix/profiles</filename>.  So
-
-<screen>
-$ nix-collect-garbage -d</screen>
-
-is a quick and easy way to clean up your system.</para>
-
-
-
-
-<section xml:id="ssec-gc-roots"><title>Garbage collector roots</title>
-
-<para>The roots of the garbage collector are all store paths to which
-there are symlinks in the directory
-<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>.
-For instance, the following command makes the path
-<filename>/nix/store/d718ef...-foo</filename> a root of the collector:
-
-<screen>
-$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar</screen>
-	
-That is, after this command, the garbage collector will not remove
-<filename>/nix/store/d718ef...-foo</filename> or any of its
-dependencies.</para>
-
-<para>Subdirectories of
-<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>
-are also searched for symlinks.  Symlinks to non-store paths are
-followed and searched for roots, but symlinks to non-store paths
-<emphasis>inside</emphasis> the paths reached in that way are not
-followed to prevent infinite recursion.</para>
-
-</section>
-
-</section>
-
-
-<section xml:id="sec-channels"><title>Channels</title>
-
-<para>If you want to stay up to date with a set of packages, it’s not
-very convenient to manually download the latest set of Nix expressions
-for those packages, use <command>nix-pull</command> to register
-pre-built binaries (if available), and upgrade using
-<command>nix-env</command>.  Fortunately, there’s a better way:
-<emphasis>Nix channels</emphasis>.</para>
-
-<para>A Nix channel is just a URL that points to a place that contains
-a set of Nix expressions and a manifest.  Using the command <link
-linkend="sec-nix-channel"><command>nix-channel</command></link> you
-can automatically stay up to date with whatever is available at that
-URL.</para>
-
-<para>You can “subscribe” to a channel using
-<command>nix-channel --add</command>, e.g.,
-
-<screen>
-$ nix-channel --add http://nixos.org/channels/nixpkgs-unstable</screen>
-
-subscribes you to a channel that always contains that latest version
-of the Nix Packages collection.  (Instead of
-<literal>nixpkgs-unstable</literal> you could also subscribe to
-<literal>nixpkgs-stable</literal>, which should have a higher level of
-stability, but right now is just outdated.)  Subscribing really just
-means that the URL is added to the file
-<filename>~/.nix-channels</filename>.  Right now there is no command
-to “unsubscribe”; you should just edit that file manually
-and delete the offending URL.</para>
-
-<para>To obtain the latest Nix expressions available in a channel, do
-
-<screen>
-$ nix-channel --update</screen>
-
-This downloads the Nix expressions in every channel (downloaded from
-<literal><replaceable>url</replaceable>/nixexprs.tar.bz2</literal>)
-and registers any available pre-built binaries in every channel
-(by <command>nix-pull</command>ing
-<literal><replaceable>url</replaceable>/MANIFEST</literal>).  It also
-makes the union of each channel’s Nix expressions the default for
-<command>nix-env</command> operations.  Consequently, you can then say
-
-<screen>
-$ nix-env -u '*'</screen>
-
-to upgrade all packages in your profile to the latest versions
-available in the subscribed channels.</para>
-
-</section>
-
-
-<section xml:id="sec-one-click"><title>One-click installs</title>
-
-<para>Often, when you want to install a specific package (e.g., from
-the <link
-xlink:href="http://nixos.org/nixpkgs/">Nix
-Packages collection</link>), subscribing to a channel is a bit
-cumbersome.  And channels don’t help you at all if you want to install
-an older version of a package than the one provided by the current
-contents of the channel, or a package that has been removed from the
-channel.  That’s when <emphasis>one-click installs</emphasis> come in
-handy: you can just go to the web page that contains the package,
-click on it, and it will be installed with all the necessary
-dependencies.</para>
-
-<para>For instance, you can go to <link
-xlink:href="http://hydra.nixos.org/jobset/nixpkgs/trunk/channel/latest"
-/> and click on any link for the individual packages for your
-platform.  The first time you do this, your browser will ask what to
-do with <literal>application/nix-package</literal> files.  You should
-open them with <filename>/nix/bin/nix-install-package</filename>.
-This will open a window that asks you to confirm that you want to
-install the package.  When you answer <literal>Y</literal>, the
-package and all its dependencies will be installed.  This is a binary
-deployment mechanism — you get packages pre-compiled for the selected
-platform type.</para>
-
-<para>You can also install <literal>application/nix-package</literal>
-files from the command line directly.  See <xref
-linkend='sec-nix-install-package' /> for details.</para>
-
-</section>
-
-
-<section xml:id="sec-sharing-packages"><title>Sharing packages between machines</title>
-
-<para>Sometimes you want to copy a package from one machine to
-another.  Or, you want to install some packages and you know that
-another machine already has some or all of those packages or their
-dependencies.  In that case there are mechanisms to quickly copy
-packages between machines.</para>
-
-<para>The command <command
-linkend="sec-nix-copy-closure">nix-copy-closure</command> copies a Nix
-store path along with all its dependencies to or from another machine
-via the SSH protocol.  It doesn’t copy store paths that are already
-present on the target machine.  For example, the following command
-copies Firefox with all its dependencies:
-
-<screen>
-$ nix-copy-closure --to alice@itchy.example.org $(type -p firefox)</screen>
-
-See <xref linkend='sec-nix-copy-closure' /> for details.</para>
-
-<para>With <command linkend='refsec-nix-store-export'>nix-store
---export</command> and <command
-linkend='refsec-nix-store-import'>nix-store --import</command> you can
-write the closure of a store path (that is, the path and all its
-dependencies) to a file, and then unpack that file into another Nix
-store.  For example,
-
-<screen>
-$ nix-store --export $(nix-store -qR $(type -p firefox)) > firefox.closure</screen>
-
-writes the closure of Firefox to a file.  You can then copy this file
-to another machine and install the closure:
-
-<screen>
-$ nix-store --import &lt; firefox.closure</screen>
-
-Any store paths in the closure that are already present in the target
-store are ignored.  It is also possible to pipe the export into
-another command, e.g. to copy and install a closure directly to/on
-another machine:
-
-<screen>
-$ nix-store --export $(nix-store -qR $(type -p firefox)) | bzip2 | \
-    ssh alice@itchy.example.org "bunzip2 | nix-store --import"</screen>
-
-But note that <command>nix-copy-closure</command> is generally more
-efficient in this example because it only copies paths that are not
-already present in the target Nix store.</para>
-
-<para>Finally, if you can mount the Nix store of a remote machine in
-your local filesystem, Nix can copy paths from the remote Nix store to
-the local Nix store <emphasis>on demand</emphasis>.  For instance,
-suppose that you mount a remote machine containing a Nix store via
-<command
-xlink:href="http://fuse.sourceforge.net/sshfs.html">sshfs</command>:
-
-<screen>
-$ sshfs alice@itchy.example.org:/ /mnt</screen>
-
-You should then set the <envar>NIX_OTHER_STORES</envar> environment
-variable to tell Nix about this remote Nix store:
-
-<screen>
-$ export NIX_OTHER_STORES=/mnt/nix</screen>
-
-Then if you do any Nix operation, e.g.
-
-<screen>
-$ nix-env -i firefox</screen>
-
-and Nix has to build a path that it sees is already present in
-<filename>/mnt/nix</filename>, then it will just copy from there
-instead of building it from source.</para>
-
-
-</section>
-
-
-</chapter>

doc/manual/packages/basic-package-mgmt.xml

@@ -0,0 +1,170 @@
+<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-basic-package-mgmt">
+
+<title>Basic Package Management</title>
+
+<para>The main command for package management is <link
+linkend="sec-nix-env"><command>nix-env</command></link>.  You can use
+it to install, upgrade, and erase packages, and to query what
+packages are installed or are available for installation.</para>
+
+<para>In Nix, different users can have different “views”
+on the set of installed applications.  That is, there might be lots of
+applications present on the system (possibly in many different
+versions), but users can have a specific selection of those active —
+where “active” just means that it appears in a directory
+in the user’s <envar>PATH</envar>.  Such a view on the set of
+installed applications is called a <emphasis>user
+environment</emphasis>, which is just a directory tree consisting of
+symlinks to the files of the active applications.  </para>
+
+<para>Components are installed from a set of <emphasis>Nix
+expressions</emphasis> that tell Nix how to build those packages,
+including, if necessary, their dependencies.  There is a collection of
+Nix expressions called the Nix Package collection that contains
+packages ranging from basic development stuff such as GCC and Glibc,
+to end-user applications like Mozilla Firefox.  (Nix is however not
+tied to the Nix Package collection; you could write your own Nix
+expressions based on it, or completely new ones.)  You can download
+the latest version from <link
+xlink:href='http://nixos.org/nixpkgs/download.html' />.</para>
+
+<para>Assuming that you have downloaded and unpacked a release of Nix
+Packages, you can view the set of available packages in the release:
+
+<screen>
+$ nix-env -qaf nixpkgs-<replaceable>version</replaceable> '*'
+ant-blackdown-1.4.2
+aterm-2.2
+bash-3.0
+binutils-2.15
+bison-1.875d
+blackdown-1.4.2
+bzip2-1.0.2
+...</screen>
+
+where <literal>nixpkgs-<replaceable>version</replaceable></literal> is
+where you’ve unpacked the release.  The flag <option>-q</option>
+specifies a query operation; <option>-a</option> means that you want
+to show the “available” (i.e., installable) packages, as opposed to
+the installed packages; and <option>-f</option>
+<filename>nixpkgs-<replaceable>version</replaceable></filename>
+specifies the source of the packages.  The argument
+<literal>'*'</literal> shows all installable packages. (The quotes are
+necessary to prevent shell expansion.)  You can also select specific
+packages by name:
+
+<screen>
+$ nix-env -qaf nixpkgs-<replaceable>version</replaceable> gcc
+gcc-3.4.6
+gcc-4.0.3
+gcc-4.1.1</screen>
+
+</para>
+
+<para>It is also possible to see the <emphasis>status</emphasis> of
+available packages, i.e., whether they are installed into the user
+environment and/or present in the system:
+
+<screen>
+$ nix-env -qasf nixpkgs-<replaceable>version</replaceable> '*'
+...
+-PS bash-3.0
+--S binutils-2.15
+IPS bison-1.875d
+...</screen>
+
+The first character (<literal>I</literal>) indicates whether the
+package is installed in your current user environment.  The second
+(<literal>P</literal>) indicates whether it is present on your system
+(in which case installing it into your user environment would be a
+very quick operation).  The last one (<literal>S</literal>) indicates
+whether there is a so-called <emphasis>substitute</emphasis> for the
+package, which is Nix’s mechanism for doing binary deployment.  It
+just means that Nix knows that it can fetch a pre-built package from
+somewhere (typically a network server) instead of building it
+locally.</para>
+
+<para>So now that we have a set of Nix expressions we can build the
+packages contained in them.  This is done using <literal>nix-env
+-i</literal>.  For instance,
+
+<screen>
+$ nix-env -f nixpkgs-<replaceable>version</replaceable> -i subversion</screen>
+
+will install the package called <literal>subversion</literal> (which
+is, of course, the <link
+xlink:href='http://subversion.tigris.org/'>Subversion version
+management system</link>).</para>
+
+<para>When you do this for the first time, Nix will start building
+Subversion and all its dependencies.  This will take quite a while —
+typically an hour or two on modern machines.  Fortunately, there is a
+faster way (so do a Ctrl-C on that install operation!): you just need
+to tell Nix that pre-built binaries of all those packages are
+available somewhere.  This is done using the
+<command>nix-pull</command> command, which must be supplied with a URL
+containing a <emphasis>manifest</emphasis> describing what binaries
+are available.  This URL should correspond to the Nix Packages release
+that you’re using.  For instance, if you obtained a release from <link
+xlink:href='http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x'
+/>, then you should do:
+
+<screen>
+$ nix-pull http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x/MANIFEST</screen>
+
+If you then issue the installation command, it should start
+downloading binaries from <systemitem
+class='fqdomainname'>nixos.org</systemitem>, instead of building
+them from source.  This might still take a while since all
+dependencies must be downloaded, but on a reasonably fast connection
+such as a DSL line it’s on the order of a few minutes.</para>
+
+<para>Naturally, packages can also be uninstalled:
+
+<screen>
+$ nix-env -e subversion</screen>
+
+</para>
+
+<para>Upgrading to a new version is just as easy.  If you have a new
+release of Nix Packages, you can do:
+
+<screen>
+$ nix-env -f nixpkgs-<replaceable>version</replaceable> -u subversion</screen>
+
+This will <emphasis>only</emphasis> upgrade Subversion if there is a
+“newer” version in the new set of Nix expressions, as
+defined by some pretty arbitrary rules regarding ordering of version
+numbers (which generally do what you’d expect of them).  To just
+unconditionally replace Subversion with whatever version is in the Nix
+expressions, use <parameter>-i</parameter> instead of
+<parameter>-u</parameter>; <parameter>-i</parameter> will remove
+whatever version is already installed.</para>
+
+<para>You can also upgrade all packages for which there are newer
+versions:
+
+<screen>
+$ nix-env -f nixpkgs-<replaceable>version</replaceable> -u '*'</screen>
+
+</para>
+
+<para>Sometimes it’s useful to be able to ask what
+<command>nix-env</command> would do, without actually doing it.  For
+instance, to find out what packages would be upgraded by
+<literal>nix-env -u '*'</literal>, you can do
+
+<screen>
+$ nix-env ... -u '*' --dry-run
+(dry run; not doing anything)
+upgrading `libxslt-1.1.0' to `libxslt-1.1.10'
+upgrading `graphviz-1.10' to `graphviz-1.12'
+upgrading `coreutils-5.0' to `coreutils-5.2.1'</screen>
+
+</para>
+
+</chapter>

doc/manual/packages/channels.xml

@@ -0,0 +1,57 @@
+<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="sec-channels">
+
+<title>Channels</title>
+
+<para>If you want to stay up to date with a set of packages, it’s not
+very convenient to manually download the latest set of Nix expressions
+for those packages, use <command>nix-pull</command> to register
+pre-built binaries (if available), and upgrade using
+<command>nix-env</command>.  Fortunately, there’s a better way:
+<emphasis>Nix channels</emphasis>.</para>
+
+<para>A Nix channel is just a URL that points to a place that contains
+a set of Nix expressions and a manifest.  Using the command <link
+linkend="sec-nix-channel"><command>nix-channel</command></link> you
+can automatically stay up to date with whatever is available at that
+URL.</para>
+
+<para>You can “subscribe” to a channel using
+<command>nix-channel --add</command>, e.g.,
+
+<screen>
+$ nix-channel --add http://nixos.org/channels/nixpkgs-unstable</screen>
+
+subscribes you to a channel that always contains that latest version
+of the Nix Packages collection.  (Instead of
+<literal>nixpkgs-unstable</literal> you could also subscribe to
+<literal>nixpkgs-stable</literal>, which should have a higher level of
+stability, but right now is just outdated.)  Subscribing really just
+means that the URL is added to the file
+<filename>~/.nix-channels</filename>.  Right now there is no command
+to “unsubscribe”; you should just edit that file manually
+and delete the offending URL.</para>
+
+<para>To obtain the latest Nix expressions available in a channel, do
+
+<screen>
+$ nix-channel --update</screen>
+
+This downloads the Nix expressions in every channel (downloaded from
+<literal><replaceable>url</replaceable>/nixexprs.tar.bz2</literal>)
+and registers any available pre-built binaries in every channel
+(by <command>nix-pull</command>ing
+<literal><replaceable>url</replaceable>/MANIFEST</literal>).  It also
+makes the union of each channel’s Nix expressions the default for
+<command>nix-env</command> operations.  Consequently, you can then say
+
+<screen>
+$ nix-env -u '*'</screen>
+
+to upgrade all packages in your profile to the latest versions
+available in the subscribed channels.</para>
+
+</chapter>

doc/manual/packages/garbage-collection.xml

@@ -0,0 +1,70 @@
+<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='sec-garbage-collection'>
+
+<title>Garbage Collection</title>
+
+<para><command>nix-env</command> operations such as upgrades
+(<option>-u</option>) and uninstall (<option>-e</option>) never
+actually delete packages from the system.  All they do (as shown
+above) is to create a new user environment that no longer contains
+symlinks to the “deleted” packages.</para>
+
+<para>Of course, since disk space is not infinite, unused packages
+should be removed at some point.  You can do this by running the Nix
+garbage collector.  It will remove from the Nix store any package
+not used (directly or indirectly) by any generation of any
+profile.</para>
+
+<para>Note however that as long as old generations reference a
+package, it will not be deleted.  After all, we wouldn’t be able to
+do a rollback otherwise.  So in order for garbage collection to be
+effective, you should also delete (some) old generations.  Of course,
+this should only be done if you are certain that you will not need to
+roll back.</para>
+
+<para>To delete all old (non-current) generations of your current
+profile:
+
+<screen>
+$ nix-env --delete-generations old</screen>
+
+Instead of <literal>old</literal> you can also specify a list of
+generations, e.g.,
+
+<screen>
+$ nix-env --delete-generations 10 11 14</screen>
+
+</para>
+
+<para>After removing appropriate old generations you can run the
+garbage collector as follows:
+
+<screen>
+$ nix-store --gc</screen>
+
+If you are feeling uncertain, you can also first view what files would
+be deleted:
+
+<screen>
+$ nix-store --gc --print-dead</screen>
+
+Likewise, the option <option>--print-live</option> will show the paths
+that <emphasis>won’t</emphasis> be deleted.</para>
+
+<para>There is also a convenient little utility
+<command>nix-collect-garbage</command>, which when invoked with the
+<option>-d</option> (<option>--delete-old</option>) switch deletes all
+old generations of all profiles in
+<filename>/nix/var/nix/profiles</filename>.  So
+
+<screen>
+$ nix-collect-garbage -d</screen>
+
+is a quick and easy way to clean up your system.</para>
+
+<xi:include href="garbage-collector-roots.xml" />
+
+</chapter>

doc/manual/packages/garbage-collector-roots.xml

@@ -0,0 +1,29 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="ssec-gc-roots">
+
+<title>Garbage Collector Roots</title>
+
+<para>The roots of the garbage collector are all store paths to which
+there are symlinks in the directory
+<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>.
+For instance, the following command makes the path
+<filename>/nix/store/d718ef...-foo</filename> a root of the collector:
+
+<screen>
+$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar</screen>
+	
+That is, after this command, the garbage collector will not remove
+<filename>/nix/store/d718ef...-foo</filename> or any of its
+dependencies.</para>
+
+<para>Subdirectories of
+<filename><replaceable>prefix</replaceable>/nix/var/nix/gcroots</filename>
+are also searched for symlinks.  Symlinks to non-store paths are
+followed and searched for roots, but symlinks to non-store paths
+<emphasis>inside</emphasis> the paths reached in that way are not
+followed to prevent infinite recursion.</para>
+
+</section>

doc/manual/packages/one-click.xml

@@ -0,0 +1,37 @@
+<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="sec-one-click">
+
+<title>One-Click Installation</title>
+
+<para>Often, when you want to install a specific package (e.g., from
+the <link
+xlink:href="http://nixos.org/nixpkgs/">Nix
+Packages collection</link>), subscribing to a channel is a bit
+cumbersome.  And channels don’t help you at all if you want to install
+an older version of a package than the one provided by the current
+contents of the channel, or a package that has been removed from the
+channel.  That’s when <emphasis>one-click installs</emphasis> come in
+handy: you can just go to the web page that contains the package,
+click on it, and it will be installed with all the necessary
+dependencies.</para>
+
+<para>For instance, you can go to <link
+xlink:href="http://hydra.nixos.org/jobset/nixpkgs/trunk/channel/latest"
+/> and click on any link for the individual packages for your
+platform.  The first time you do this, your browser will ask what to
+do with <literal>application/nix-package</literal> files.  You should
+open them with <filename>/nix/bin/nix-install-package</filename>.
+This will open a window that asks you to confirm that you want to
+install the package.  When you answer <literal>Y</literal>, the
+package and all its dependencies will be installed.  This is a binary
+deployment mechanism — you get packages pre-compiled for the selected
+platform type.</para>
+
+<para>You can also install <literal>application/nix-package</literal>
+files from the command line directly.  See <xref
+linkend='sec-nix-install-package' /> for details.</para>
+
+</chapter>

doc/manual/packages/package-management.xml

@@ -0,0 +1,24 @@
+<part 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='chap-package-management'>
+
+<title>Package Management</title>
+
+<partintro>
+<para>This chapter discusses how to do package management with Nix,
+i.e., how to obtain, install, upgrade, and erase packages.  This is
+the “user’s” perspective of the Nix system — people
+who want to <emphasis>create</emphasis> packages should consult
+<xref linkend='chap-writing-nix-expressions' />.</para>
+</partintro>
+
+<xi:include href="basic-package-mgmt.xml" />
+<xi:include href="profiles.xml" />
+<xi:include href="garbage-collection.xml" />
+<xi:include href="channels.xml" />
+<xi:include href="one-click.xml" />
+<xi:include href="sharing-packages.xml" />
+
+</part>

doc/manual/packages/profiles.xml

@@ -0,0 +1,159 @@
+<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="sec-profiles">
+
+<title>Profiles</title>
+
+<para>Profiles and user environments are Nix’s mechanism for
+implementing the ability to allow different users to have different
+configurations, and to do atomic upgrades and rollbacks.  To
+understand how they work, it’s useful to know a bit about how Nix
+works.  In Nix, packages are stored in unique locations in the
+<emphasis>Nix store</emphasis> (typically,
+<filename>/nix/store</filename>).  For instance, a particular version
+of the Subversion package might be stored in a directory
+<filename>/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3/</filename>,
+while another version might be stored in
+<filename>/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2</filename>.
+The long strings prefixed to the directory names are cryptographic
+hashes<footnote><para>160-bit truncations of SHA-256 hashes encoded in
+a base-32 notation, to be precise.</para></footnote> of
+<emphasis>all</emphasis> inputs involved in building the package —
+sources, dependencies, compiler flags, and so on.  So if two
+packages differ in any way, they end up in different locations in
+the file system, so they don’t interfere with each other.  <xref
+linkend='fig-user-environments' /> shows a part of a typical Nix
+store.</para>
+
+<figure xml:id='fig-user-environments'><title>User environments</title>
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref='figures/user-environments.png' format='PNG' />
+    </imageobject>
+  </mediaobject>
+</figure>
+
+<para>Of course, you wouldn’t want to type
+
+<screen>
+$ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn</screen>
+
+every time you want to run Subversion.  Of course we could set up the
+<envar>PATH</envar> environment variable to include the
+<filename>bin</filename> directory of every package we want to use,
+but this is not very convenient since changing <envar>PATH</envar>
+doesn’t take effect for already existing processes.  The solution Nix
+uses is to create directory trees of symlinks to
+<emphasis>activated</emphasis> packages.  These are called
+<emphasis>user environments</emphasis> and they are packages
+themselves (though automatically generated by
+<command>nix-env</command>), so they too reside in the Nix store.  For
+instance, in <xref linkend='fig-user-environments' /> the user
+environment <filename>/nix/store/0c1p5z4kda11...-user-env</filename>
+contains a symlink to just Subversion 1.1.2 (arrows in the figure
+indicate symlinks).  This would be what we would obtain if we had done
+
+<screen>
+$ nix-env -i subversion</screen>
+
+on a set of Nix expressions that contained Subversion 1.1.2.</para>
+
+<para>This doesn’t in itself solve the problem, of course; you
+wouldn’t want to type
+<filename>/nix/store/0c1p5z4kda11...-user-env/bin/svn</filename>
+either.  That’s why there are symlinks outside of the store that point
+to the user environments in the store; for instance, the symlinks
+<filename>default-42-link</filename> and
+<filename>default-43-link</filename> in the example.  These are called
+<emphasis>generations</emphasis> since every time you perform a
+<command>nix-env</command> operation, a new user environment is
+generated based on the current one.  For instance, generation 43 was
+created from generation 42 when we did
+
+<screen>
+$ nix-env -i subversion mozilla</screen>
+
+on a set of Nix expressions that contained Mozilla and a new version
+of Subversion.</para>
+
+<para>Generations are grouped together into
+<emphasis>profiles</emphasis> so that different users don’t interfere
+with each other if they don’t want to.  For example:
+
+<screen>
+$ ls -l /nix/var/nix/profiles/
+...
+lrwxrwxrwx  1 eelco ... default-42-link -> /nix/store/0c1p5z4kda11...-user-env
+lrwxrwxrwx  1 eelco ... default-43-link -> /nix/store/3aw2pdyx2jfc...-user-env
+lrwxrwxrwx  1 eelco ... default -> default-43-link</screen>
+
+This shows a profile called <filename>default</filename>.  The file
+<filename>default</filename> itself is actually a symlink that points
+to the current generation.  When we do a <command>nix-env</command>
+operation, a new user environment and generation link are created
+based on the current one, and finally the <filename>default</filename>
+symlink is made to point at the new generation.  This last step is
+atomic on Unix, which explains how we can do atomic upgrades.  (Note
+that the building/installing of new packages doesn’t interfere in
+any way with old packages, since they are stored in different
+locations in the Nix store.)</para>
+
+<para>If you find that you want to undo a <command>nix-env</command>
+operation, you can just do
+
+<screen>
+$ nix-env --rollback</screen>
+
+which will just make the current generation link point at the previous
+link.  E.g., <filename>default</filename> would be made to point at
+<filename>default-42-link</filename>.  You can also switch to a
+specific generation:
+
+<screen>
+$ nix-env --switch-generation 43</screen>
+
+which in this example would roll forward to generation 43 again.  You
+can also see all available generations:
+
+<screen>
+$ nix-env --list-generations</screen></para>
+
+<para>Actually, there is another level of indirection not shown in the
+figure above.  You generally wouldn’t have
+<filename>/nix/var/nix/profiles/<replaceable>some-profile</replaceable>/bin</filename>
+in your <envar>PATH</envar>.  Rather, there is a symlink
+<filename>~/.nix-profile</filename> that points to your current
+profile.  This means that you should put
+<filename>~/.nix-profile/bin</filename> in your <envar>PATH</envar>
+(and indeed, that’s what the initialisation script
+<filename>/nix/etc/profile.d/nix.sh</filename> does).  This makes it
+easier to switch to a different profile.  You can do that using the
+command <command>nix-env --switch-profile</command>:
+
+<screen>
+$ nix-env --switch-profile /nix/var/nix/profiles/my-profile
+
+$ nix-env --switch-profile /nix/var/nix/profiles/default</screen>
+
+These commands switch to the <filename>my-profile</filename> and
+default profile, respectively.  If the profile doesn’t exist, it will
+be created automatically.  You should be careful about storing a
+profile in another location than the <filename>profiles</filename>
+directory, since otherwise it might not be used as a root of the
+garbage collector (see <xref linkend='sec-garbage-collection'
+/>).</para>
+
+<para>All <command>nix-env</command> operations work on the profile
+pointed to by <command>~/.nix-profile</command>, but you can override
+this using the <option>--profile</option> option (abbreviation
+<option>-p</option>):
+
+<screen>
+$ nix-env -p /nix/var/nix/profiles/other-profile -i subversion</screen>
+
+This will <emphasis>not</emphasis> change the
+<command>~/.nix-profile</command> symlink.</para>
+
+</chapter>

doc/manual/packages/sharing-packages.xml

@@ -0,0 +1,82 @@
+<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="sec-sharing-packages">
+
+<title>Sharing Packages Between Machines</title>
+
+<para>Sometimes you want to copy a package from one machine to
+another.  Or, you want to install some packages and you know that
+another machine already has some or all of those packages or their
+dependencies.  In that case there are mechanisms to quickly copy
+packages between machines.</para>
+
+<para>The command <command
+linkend="sec-nix-copy-closure">nix-copy-closure</command> copies a Nix
+store path along with all its dependencies to or from another machine
+via the SSH protocol.  It doesn’t copy store paths that are already
+present on the target machine.  For example, the following command
+copies Firefox with all its dependencies:
+
+<screen>
+$ nix-copy-closure --to alice@itchy.example.org $(type -p firefox)</screen>
+
+See <xref linkend='sec-nix-copy-closure' /> for details.</para>
+
+<para>With <command linkend='refsec-nix-store-export'>nix-store
+--export</command> and <command
+linkend='refsec-nix-store-import'>nix-store --import</command> you can
+write the closure of a store path (that is, the path and all its
+dependencies) to a file, and then unpack that file into another Nix
+store.  For example,
+
+<screen>
+$ nix-store --export $(nix-store -qR $(type -p firefox)) > firefox.closure</screen>
+
+writes the closure of Firefox to a file.  You can then copy this file
+to another machine and install the closure:
+
+<screen>
+$ nix-store --import &lt; firefox.closure</screen>
+
+Any store paths in the closure that are already present in the target
+store are ignored.  It is also possible to pipe the export into
+another command, e.g. to copy and install a closure directly to/on
+another machine:
+
+<screen>
+$ nix-store --export $(nix-store -qR $(type -p firefox)) | bzip2 | \
+    ssh alice@itchy.example.org "bunzip2 | nix-store --import"</screen>
+
+But note that <command>nix-copy-closure</command> is generally more
+efficient in this example because it only copies paths that are not
+already present in the target Nix store.</para>
+
+<para>Finally, if you can mount the Nix store of a remote machine in
+your local filesystem, Nix can copy paths from the remote Nix store to
+the local Nix store <emphasis>on demand</emphasis>.  For instance,
+suppose that you mount a remote machine containing a Nix store via
+<command
+xlink:href="http://fuse.sourceforge.net/sshfs.html">sshfs</command>:
+
+<screen>
+$ sshfs alice@itchy.example.org:/ /mnt</screen>
+
+You should then set the <envar>NIX_OTHER_STORES</envar> environment
+variable to tell Nix about this remote Nix store:
+
+<screen>
+$ export NIX_OTHER_STORES=/mnt/nix</screen>
+
+Then if you do any Nix operation, e.g.
+
+<screen>
+$ nix-env -i firefox</screen>
+
+and Nix has to build a path that it sees is already present in
+<filename>/mnt/nix</filename>, then it will just copy from there
+instead of building it from source.</para>
+
+
+</chapter>

doc/manual/quick-start/getting-started.xml

@@ -1,17 +1,15 @@
 <chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="chap-quick-start">
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="ch-getting-started-nix"> 
 
-<title>Quick Start</title>
+<title>Getting Started with Nix</title>
 
+<para>This tutorial takes you through the basic tasks you might perform when you start using Nix.</para>
+<procedure>
 
-<para>This chapter is for impatient people who don't like reading
+<step><para>Install Nix by running the following:
-documentation.  For more in-depth information you are kindly referred
-to the following chapters.</para>
-
-<orderedlist>
-
-<listitem><para>Install Nix by running the following:
 
 <screen>
 $ bash &lt;(curl https://nixos.org/nix/install)
@@ -20,9 +18,9 @@ $ bash &lt;(curl https://nixos.org/nix/install)
 This will install Nix in <filename>/nix</filename>. The install script
 will create <filename>/nix</filename> using <command>sudo</command>,
 so make sure you have sufficient rights.  (For other installation
-methods, see <xref linkend="chap-installation"/>.)</para></listitem>
+methods, see <xref linkend="chap-installation"/>.)</para></step>
 
-<listitem><para>See what installable packages are currently available
+<step><para>See what installable packages are currently available
 in the channel:
 
 <screen>
@@ -33,17 +31,17 @@ hello-2.1.1
 libxslt-1.1.0
 <replaceable>...</replaceable></screen>
 
-</para></listitem>
+</para></step>
 
-<listitem><para>Install some packages from the channel:
+<step><para>Install some packages from the channel:
 
 <screen>
 $ nix-env -i hello <replaceable>...</replaceable> </screen>
 
 This should download pre-built packages; it should not build them
-locally (if it does, something went wrong).</para></listitem>
+locally (if it does, something went wrong).</para></step>
 
-<listitem><para>Test that they work:
+<step><para>Test that they work:
 
 <screen>
 $ which hello
@@ -52,16 +50,16 @@ $ hello
 Hello, world!
 </screen>
 
-</para></listitem>
+</para></step>
 
-<listitem><para>Uninstall a package:
+<step><para>Uninstall a package:
 
 <screen>
 $ nix-env -e hello</screen>
 
-</para></listitem>
+</para></step>
 
-<listitem><para>To keep up-to-date with the channel, do:
+<step><para>To keep up-to-date with the channel, do:
 
 <screen>
 $ nix-channel --update nixpkgs
@@ -69,9 +67,9 @@ $ nix-env -u '*'</screen>
 
 The latter command will upgrade each installed package for which there
 is a “newer” version (as determined by comparing the version
-numbers).</para></listitem>
+numbers).</para></step>
 
-<listitem><para>You can also install specific packages directly from
+<step><para>You can also install specific packages directly from
 your web browser.  For instance, you can go to <link
 xlink:href="http://hydra.nixos.org/jobset/nixpkgs/trunk/channel/latest"
 /> and click on any link for the individual packages for your
@@ -79,18 +77,18 @@ platform.  Associate <literal>application/nix-package</literal> with
 the program <command>nix-install-package</command>.  A window should
 appear asking you whether it’s okay to install the package.  Say
 <literal>Y</literal>.  The package and all its dependencies will be
-installed.</para></listitem>
+installed.</para></step>
 
-<listitem><para>If you're unhappy with the result of a
+<step><para>If you're unhappy with the result of a
 <command>nix-env</command> action (e.g., an upgraded package turned
 out not to work properly), you can go back:
 
 <screen>
 $ nix-env --rollback</screen>
 
-</para></listitem>
+</para></step>
 
-<listitem><para>You should periodically run the Nix garbage collector
+<step><para>You should periodically run the Nix garbage collector
 to get rid of unused packages, since uninstalls or upgrades don't
 actually delete them:
 
@@ -103,8 +101,8 @@ rollbacks impossible, but also making the packages in those old
 generations available for garbage collection), while the second
 command actually deletes them.-->
 
-</para></listitem>
+</para></step>
 
-</orderedlist>
+</procedure>
 
-</chapter>
+</chapter>

doc/manual/quick-start/quick-start.xml

@@ -0,0 +1,17 @@
+<part 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="chap-quick-start">
+
+<title>Quick-Start</title>
+
+<partintro>
+<para>This section is for impatient people who don't like reading
+documentation.  For more in-depth information you are kindly referred
+to subsequent chapters.</para>
+</partintro>
+
+<xi:include href="getting-started.xml" />
+
+</part>

doc/manual/release-notes/release-notes.xml

@@ -0,0 +1,43 @@
+<part 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="sec-relnotes">
+
+<title>Nix Release Notes</title>
+
+<partintro>
+<para>This section lists the release notes for each stable version of Nix.</para>
+</partintro>
+
+<!-- TODO 
+<xi:include href="rl-18.xml" />
+-->
+<xi:include href="rl-17.xml" />
+<xi:include href="rl-161.xml" />
+<xi:include href="rl-16.xml" />
+<xi:include href="rl-152.xml" />
+<xi:include href="rl-15.xml" />
+<xi:include href="rl-14.xml" />
+<xi:include href="rl-13.xml" />
+<xi:include href="rl-12.xml" />
+<xi:include href="rl-11.xml" />
+<xi:include href="rl-10.xml" />
+<xi:include href="rl-016.xml" />
+<xi:include href="rl-015.xml" />
+<xi:include href="rl-014.xml" />
+<xi:include href="rl-013.xml" />
+<xi:include href="rl-012.xml" />
+<xi:include href="rl-011.xml" />
+<xi:include href="rl-0101.xml" />
+<xi:include href="rl-010.xml" />
+<xi:include href="rl-092.xml" />
+<xi:include href="rl-091.xml" />
+<xi:include href="rl-09.xml" />
+<xi:include href="rl-081.xml" />
+<xi:include href="rl-08.xml" />
+<xi:include href="rl-07.xml" />
+<xi:include href="rl-06.xml" />
+<xi:include href="rl-05.xml" />
+
+</part>

doc/manual/release-notes/rl-010.xml

@@ -0,0 +1,323 @@
+<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-relnotes-0.10">
+
+<title>Release 0.10 (October 6, 2006)</title>
+
+<note><para>This version of Nix uses Berkeley DB 4.4 instead of 4.3.
+The database is upgraded automatically, but you should be careful not
+to use old versions of Nix that still use Berkeley DB 4.3.  In
+particular, if you use a Nix installed through Nix, you should run
+
+<screen>
+$ nix-store --clear-substitutes</screen>
+
+first.</para></note>
+
+<warning><para>Also, the database schema has changed slighted to fix a
+performance issue (see below).  When you run any Nix 0.10 command for
+the first time, the database will be upgraded automatically.  This is
+irreversible.</para></warning>
+
+<itemizedlist>
+
+
+  <!-- Usability / features -->
+
+
+  <listitem><para><command>nix-env</command> usability improvements:
+
+    <itemizedlist>
+
+      <listitem><para>An option <option>--compare-versions</option>
+      (or <option>-c</option>) has been added to <command>nix-env
+      --query</command> to allow you to compare installed versions of
+      packages to available versions, or vice versa.  An easy way to
+      see if you are up to date with what’s in your subscribed
+      channels is <literal>nix-env -qc \*</literal>.</para></listitem>
+
+      <listitem><para><literal>nix-env --query</literal> now takes as
+      arguments a list of package names about which to show
+      information, just like <option>--install</option>, etc.: for
+      example, <literal>nix-env -q gcc</literal>.  Note that to show
+      all derivations, you need to specify
+      <literal>\*</literal>.</para></listitem>
+
+      <listitem><para><literal>nix-env -i
+      <replaceable>pkgname</replaceable></literal> will now install
+      the highest available version of
+      <replaceable>pkgname</replaceable>, rather than installing all
+      available versions (which would probably give collisions)
+      (<literal>NIX-31</literal>).</para></listitem>
+
+      <listitem><para><literal>nix-env (-i|-u) --dry-run</literal> now
+      shows exactly which missing paths will be built or
+      substituted.</para></listitem>
+
+      <listitem><para><literal>nix-env -qa --description</literal>
+      shows human-readable descriptions of packages, provided that
+      they have a <literal>meta.description</literal> attribute (which
+      most packages in Nixpkgs don’t have yet).</para></listitem>
+
+    </itemizedlist>
+
+  </para></listitem>
+
+
+  <listitem><para>New language features:
+
+    <itemizedlist>
+
+      <listitem><para>Reference scanning (which happens after each
+      build) is much faster and takes a constant amount of
+      memory.</para></listitem>
+
+      <listitem><para>String interpolation.  Expressions like
+
+<programlisting>
+"--with-freetype2-library=" + freetype + "/lib"</programlisting>
+
+      can now be written as
+
+<programlisting>
+"--with-freetype2-library=${freetype}/lib"</programlisting>
+
+      You can write arbitrary expressions within
+      <literal>${<replaceable>...</replaceable>}</literal>, not just
+      identifiers.</para></listitem>
+
+      <listitem><para>Multi-line string literals.</para></listitem>
+
+      <listitem><para>String concatenations can now involve
+      derivations, as in the example <code>"--with-freetype2-library="
+      + freetype + "/lib"</code>.  This was not previously possible
+      because we need to register that a derivation that uses such a
+      string is dependent on <literal>freetype</literal>.  The
+      evaluator now properly propagates this information.
+      Consequently, the subpath operator (<literal>~</literal>) has
+      been deprecated.</para></listitem>
+
+      <listitem><para>Default values of function arguments can now
+      refer to other function arguments; that is, all arguments are in
+      scope in the default values
+      (<literal>NIX-45</literal>).</para></listitem>
+
+      <!--
+      <listitem><para>TODO: domain checks (r5895).</para></listitem>
+      -->
+
+      <listitem><para>Lots of new built-in primitives, such as
+      functions for list manipulation and integer arithmetic.  See the
+      manual for a complete list.  All primops are now available in
+      the set <varname>builtins</varname>, allowing one to test for
+      the availability of primop in a backwards-compatible
+      way.</para></listitem>
+
+      <listitem><para>Real let-expressions: <literal>let x = ...;
+      ... z = ...; in ...</literal>.</para></listitem>
+
+    </itemizedlist>
+
+  </para></listitem>
+
+
+  <listitem><para>New commands <command>nix-pack-closure</command> and
+  <command>nix-unpack-closure</command> than can be used to easily
+  transfer a store path with all its dependencies to another machine.
+  Very convenient whenever you have some package on your machine and
+  you want to copy it somewhere else.</para></listitem>
+
+
+  <listitem><para>XML support:
+
+    <itemizedlist>
+
+      <listitem><para><literal>nix-env -q --xml</literal> prints the
+      installed or available packages in an XML representation for
+      easy processing by other tools.</para></listitem>
+
+      <listitem><para><literal>nix-instantiate --eval-only
+      --xml</literal> prints an XML representation of the resulting
+      term.  (The new flag <option>--strict</option> forces ‘deep’
+      evaluation of the result, i.e., list elements and attributes are
+      evaluated recursively.)</para></listitem>
+
+      <listitem><para>In Nix expressions, the primop
+      <function>builtins.toXML</function> converts a term to an XML
+      representation.  This is primarily useful for passing structured
+      information to builders.</para></listitem>
+
+    </itemizedlist>
+
+  </para></listitem>
+
+
+  <listitem><para>You can now unambiguously specify which derivation to
+  build or install in <command>nix-env</command>,
+  <command>nix-instantiate</command> and <command>nix-build</command>
+  using the <option>--attr</option> / <option>-A</option> flags, which
+  takes an attribute name as argument.  (Unlike symbolic package names
+  such as <literal>subversion-1.4.0</literal>, attribute names in an
+  attribute set are unique.)  For instance, a quick way to perform a
+  test build of a package in Nixpkgs is <literal>nix-build
+  pkgs/top-level/all-packages.nix -A
+  <replaceable>foo</replaceable></literal>.  <literal>nix-env -q
+  --attr</literal> shows the attribute names corresponding to each
+  derivation.</para></listitem>
+
+
+  <listitem><para>If the top-level Nix expression used by
+  <command>nix-env</command>, <command>nix-instantiate</command> or
+  <command>nix-build</command> evaluates to a function whose arguments
+  all have default values, the function will be called automatically.
+  Also, the new command-line switch <option>--arg
+  <replaceable>name</replaceable>
+  <replaceable>value</replaceable></option> can be used to specify
+  function arguments on the command line.</para></listitem>
+
+
+  <listitem><para><literal>nix-install-package --url
+  <replaceable>URL</replaceable></literal> allows a package to be
+  installed directly from the given URL.</para></listitem>
+
+
+  <listitem><para>Nix now works behind an HTTP proxy server; just set
+  the standard environment variables <envar>http_proxy</envar>,
+  <envar>https_proxy</envar>, <envar>ftp_proxy</envar> or
+  <envar>all_proxy</envar> appropriately.  Functions such as
+  <function>fetchurl</function> in Nixpkgs also respect these
+  variables.</para></listitem>
+
+
+  <listitem><para><literal>nix-build -o
+  <replaceable>symlink</replaceable></literal> allows the symlink to
+  the build result to be named something other than
+  <literal>result</literal>.</para></listitem>
+
+
+  <!-- Stability / performance / etc. -->
+
+
+  <listitem><para>Platform support:
+
+    <itemizedlist>
+
+      <listitem><para>Support for 64-bit platforms, provided a <link
+      xlink:href="http://bugzilla.sen.cwi.nl:8080/show_bug.cgi?id=606">suitably
+      patched ATerm library</link> is used.  Also, files larger than 2
+      GiB are now supported.</para></listitem>
+
+      <listitem><para>Added support for Cygwin (Windows,
+      <literal>i686-cygwin</literal>), Mac OS X on Intel
+      (<literal>i686-darwin</literal>) and Linux on PowerPC
+      (<literal>powerpc-linux</literal>).</para></listitem>
+
+      <listitem><para>Users of SMP and multicore machines will
+      appreciate that the number of builds to be performed in parallel
+      can now be specified in the configuration file in the
+      <literal>build-max-jobs</literal> setting.</para></listitem>
+
+    </itemizedlist>
+
+  </para></listitem>
+
+
+  <listitem><para>Garbage collector improvements:
+
+    <itemizedlist>
+
+      <listitem><para>Open files (such as running programs) are now
+      used as roots of the garbage collector.  This prevents programs
+      that have been uninstalled from being garbage collected while
+      they are still running.  The script that detects these
+      additional runtime roots
+      (<filename>find-runtime-roots.pl</filename>) is inherently
+      system-specific, but it should work on Linux and on all
+      platforms that have the <command>lsof</command>
+      utility.</para></listitem>
+
+      <listitem><para><literal>nix-store --gc</literal>
+      (a.k.a. <command>nix-collect-garbage</command>) prints out the
+      number of bytes freed on standard output.  <literal>nix-store
+      --gc --print-dead</literal> shows how many bytes would be freed
+      by an actual garbage collection.</para></listitem>
+
+      <listitem><para><literal>nix-collect-garbage -d</literal>
+      removes all old generations of <emphasis>all</emphasis> profiles
+      before calling the actual garbage collector (<literal>nix-store
+      --gc</literal>).  This is an easy way to get rid of all old
+      packages in the Nix store.</para></listitem>
+
+      <listitem><para><command>nix-store</command> now has an
+      operation <option>--delete</option> to delete specific paths
+      from the Nix store.  It won’t delete reachable (non-garbage)
+      paths unless <option>--ignore-liveness</option> is
+      specified.</para></listitem>
+
+    </itemizedlist>
+
+  </para></listitem>
+
+
+  <listitem><para>Berkeley DB 4.4’s process registry feature is used
+  to recover from crashed Nix processes.</para></listitem>
+
+  <!--  <listitem><para>TODO: shared stores.</para></listitem> -->
+
+  <listitem><para>A performance issue has been fixed with the
+  <literal>referer</literal> table, which stores the inverse of the
+  <literal>references</literal> table (i.e., it tells you what store
+  paths refer to a given path).  Maintaining this table could take a
+  quadratic amount of time, as well as a quadratic amount of Berkeley
+  DB log file space (in particular when running the garbage collector)
+  (<literal>NIX-23</literal>).</para></listitem>
+
+  <listitem><para>Nix now catches the <literal>TERM</literal> and
+  <literal>HUP</literal> signals in addition to the
+  <literal>INT</literal> signal.  So you can now do a <literal>killall
+  nix-store</literal> without triggering a database
+  recovery.</para></listitem>
+
+  <listitem><para><command>bsdiff</command> updated to version
+  4.3.</para></listitem>
+
+  <listitem><para>Substantial performance improvements in expression
+  evaluation and <literal>nix-env -qa</literal>, all thanks to <link
+  xlink:href="http://valgrind.org/">Valgrind</link>.  Memory use has
+  been reduced by a factor 8 or so.  Big speedup by memoisation of
+  path hashing.</para></listitem>
+
+  <listitem><para>Lots of bug fixes, notably:
+
+    <itemizedlist>
+
+      <listitem><para>Make sure that the garbage collector can run
+      successfully when the disk is full
+      (<literal>NIX-18</literal>).</para></listitem>
+
+      <listitem><para><command>nix-env</command> now locks the profile
+      to prevent races between concurrent <command>nix-env</command>
+      operations on the same profile
+      (<literal>NIX-7</literal>).</para></listitem>
+
+      <listitem><para>Removed misleading messages from
+      <literal>nix-env -i</literal> (e.g., <literal>installing
+      `foo'</literal> followed by <literal>uninstalling
+      `foo'</literal>) (<literal>NIX-17</literal>).</para></listitem>
+
+    </itemizedlist>
+
+  </para></listitem>
+
+  <listitem><para>Nix source distributions are a lot smaller now since
+  we no longer include a full copy of the Berkeley DB source
+  distribution (but only the bits we need).</para></listitem>
+
+  <listitem><para>Header files are now installed so that external
+  programs can use the Nix libraries.</para></listitem>
+
+</itemizedlist>
+
+</chapter>

doc/manual/release-notes/rl-0101.xml

@@ -0,0 +1,13 @@
+<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-relnotes-0.10.1">
+
+<title>Release 0.10.1 (October 11, 2006)</title>
+
+<para>This release fixes two somewhat obscure bugs that occur when
+evaluating Nix expressions that are stored inside the Nix store
+(<literal>NIX-67</literal>).  These do not affect most users.</para>
+
+</chapter>

doc/manual/release-notes/rl-011.xml

@@ -0,0 +1,261 @@
+<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="ssec-relnotes-0.11">
+
+<title>Release 0.11 (December 31, 2007)</title>
+
+<para>Nix 0.11 has many improvements over the previous stable release.
+The most important improvement is secure multi-user support.  It also
+features many usability enhancements and language extensions, many of
+them prompted by NixOS, the purely functional Linux distribution based
+on Nix.  Here is an (incomplete) list:</para>
+
+
+<itemizedlist>
+
+
+  <listitem><para>Secure multi-user support.  A single Nix store can
+  now be shared between multiple (possible untrusted) users.  This is
+  an important feature for NixOS, where it allows non-root users to
+  install software.  The old setuid method for sharing a store between
+  multiple users has been removed.  Details for setting up a
+  multi-user store can be found in the manual.</para></listitem>
+
+
+  <listitem><para>The new command <command>nix-copy-closure</command>
+  gives you an easy and efficient way to exchange software between
+  machines.  It copies the missing parts of the closure of a set of
+  store path to or from a remote machine via
+  <command>ssh</command>.</para></listitem>
+
+
+  <listitem><para>A new kind of string literal: strings between double
+  single-quotes (<literal>''</literal>) have indentation
+  “intelligently” removed.  This allows large strings (such as shell
+  scripts or configuration file fragments in NixOS) to cleanly follow
+  the indentation of the surrounding expression.  It also requires
+  much less escaping, since <literal>''</literal> is less common in
+  most languages than <literal>"</literal>.</para></listitem>
+
+
+  <listitem><para><command>nix-env</command> <option>--set</option>
+  modifies the current generation of a profile so that it contains
+  exactly the specified derivation, and nothing else.  For example,
+  <literal>nix-env -p /nix/var/nix/profiles/browser --set
+  firefox</literal> lets the profile named
+  <filename>browser</filename> contain just Firefox.</para></listitem>
+
+
+  <listitem><para><command>nix-env</command> now maintains
+  meta-information about installed packages in profiles.  The
+  meta-information is the contents of the <varname>meta</varname>
+  attribute of derivations, such as <varname>description</varname> or
+  <varname>homepage</varname>.  The command <literal>nix-env -q --xml
+  --meta</literal> shows all meta-information.</para></listitem>
+
+
+  <listitem><para><command>nix-env</command> now uses the
+  <varname>meta.priority</varname> attribute of derivations to resolve
+  filename collisions between packages.  Lower priority values denote
+  a higher priority.  For instance, the GCC wrapper package and the
+  Binutils package in Nixpkgs both have a file
+  <filename>bin/ld</filename>, so previously if you tried to install
+  both you would get a collision.  Now, on the other hand, the GCC
+  wrapper declares a higher priority than Binutils, so the former’s
+  <filename>bin/ld</filename> is symlinked in the user
+  environment.</para></listitem>
+
+
+  <listitem><para><command>nix-env -i / -u</command>: instead of
+  breaking package ties by version, break them by priority and version
+  number.  That is, if there are multiple packages with the same name,
+  then pick the package with the highest priority, and only use the
+  version if there are multiple packages with the same
+  priority.</para>
+
+  <para>This makes it possible to mark specific versions/variant in
+  Nixpkgs more or less desirable than others.  A typical example would
+  be a beta version of some package (e.g.,
+  <literal>gcc-4.2.0rc1</literal>) which should not be installed even
+  though it is the highest version, except when it is explicitly
+  selected (e.g., <literal>nix-env -i
+  gcc-4.2.0rc1</literal>).</para></listitem>
+
+
+  <listitem><para><command>nix-env --set-flag</command> allows meta
+  attributes of installed packages to be modified.  There are several
+  attributes that can be usefully modified, because they affect the
+  behaviour of <command>nix-env</command> or the user environment
+  build script:
+
+    <itemizedlist>
+
+      <listitem><para><varname>meta.priority</varname> can be changed
+      to resolve filename clashes (see above).</para></listitem>
+
+      <listitem><para><varname>meta.keep</varname> can be set to
+      <literal>true</literal> to prevent the package from being
+      upgraded or replaced.  Useful if you want to hang on to an older
+      version of a package.</para></listitem>
+
+      <listitem><para><varname>meta.active</varname> can be set to
+      <literal>false</literal> to “disable” the package.  That is, no
+      symlinks will be generated to the files of the package, but it
+      remains part of the profile (so it won’t be garbage-collected).
+      Set it back to <literal>true</literal> to re-enable the
+      package.</para></listitem>
+
+    </itemizedlist>
+
+  </para></listitem>
+
+
+  <listitem><para><command>nix-env -q</command> now has a flag
+  <option>--prebuilt-only</option> (<option>-b</option>) that causes
+  <command>nix-env</command> to show only those derivations whose
+  output is already in the Nix store or that can be substituted (i.e.,
+  downloaded from somewhere).  In other words, it shows the packages
+  that can be installed “quickly”, i.e., don’t need to be built from
+  source.  The <option>-b</option> flag is also available in
+  <command>nix-env -i</command> and <command>nix-env -u</command> to
+  filter out derivations for which no pre-built binary is
+  available.</para></listitem>
+
+
+  <listitem><para>The new option <option>--argstr</option> (in
+  <command>nix-env</command>, <command>nix-instantiate</command> and
+  <command>nix-build</command>) is like <option>--arg</option>, except
+  that the value is a string.  For example, <literal>--argstr system
+  i686-linux</literal> is equivalent to <literal>--arg system
+  \"i686-linux\"</literal> (note that <option>--argstr</option>
+  prevents annoying quoting around shell arguments).</para></listitem>
+
+
+  <listitem><para><command>nix-store</command> has a new operation
+  <option>--read-log</option> (<option>-l</option>)
+  <parameter>paths</parameter> that shows the build log of the given
+  paths.</para></listitem>
+
+
+  <!--
+  <listitem><para>TODO: semantic cleanups of string concatenation
+  etc. (mostly in r6740).</para></listitem>
+  -->
+
+
+  <listitem><para>Nix now uses Berkeley DB 4.5.  The database is
+  upgraded automatically, but you should be careful not to use old
+  versions of Nix that still use Berkeley DB 4.4.</para></listitem>
+
+
+  <!-- foo
+  <listitem><para>TODO: option <option>- -reregister</option> in
+  <command>nix-store - -register-validity</command>.</para></listitem>
+  -->
+
+
+  <listitem><para>The option <option>--max-silent-time</option>
+  (corresponding to the configuration setting
+  <literal>build-max-silent-time</literal>) allows you to set a
+  timeout on builds — if a build produces no output on
+  <literal>stdout</literal> or <literal>stderr</literal> for the given
+  number of seconds, it is terminated.  This is useful for recovering
+  automatically from builds that are stuck in an infinite
+  loop.</para></listitem>
+
+
+  <listitem><para><command>nix-channel</command>: each subscribed
+  channel is its own attribute in the top-level expression generated
+  for the channel.  This allows disambiguation (e.g. <literal>nix-env
+  -i -A nixpkgs_unstable.firefox</literal>).</para></listitem>
+
+
+  <listitem><para>The substitutes table has been removed from the
+  database.  This makes operations such as <command>nix-pull</command>
+  and <command>nix-channel --update</command> much, much
+  faster.</para></listitem>
+
+
+  <listitem><para><command>nix-pull</command> now supports
+  bzip2-compressed manifests.  This speeds up
+  channels.</para></listitem>
+
+
+  <listitem><para><command>nix-prefetch-url</command> now has a
+  limited form of caching.  This is used by
+  <command>nix-channel</command> to prevent unnecessary downloads when
+  the channel hasn’t changed.</para></listitem>
+
+
+  <listitem><para><command>nix-prefetch-url</command> now by default
+  computes the SHA-256 hash of the file instead of the MD5 hash.  In
+  calls to <function>fetchurl</function> you should pass the
+  <literal>sha256</literal> attribute instead of
+  <literal>md5</literal>.  You can pass either a hexadecimal or a
+  base-32 encoding of the hash.</para></listitem>
+
+
+  <listitem><para>Nix can now perform builds in an automatically
+  generated “chroot”.  This prevents a builder from accessing stuff
+  outside of the Nix store, and thus helps ensure purity.  This is an
+  experimental feature.</para></listitem>
+
+
+  <listitem><para>The new command <command>nix-store
+  --optimise</command> reduces Nix store disk space usage by finding
+  identical files in the store and hard-linking them to each other.
+  It typically reduces the size of the store by something like
+  25-35%.</para></listitem>
+
+
+  <listitem><para><filename>~/.nix-defexpr</filename> can now be a
+  directory, in which case the Nix expressions in that directory are
+  combined into an attribute set, with the file names used as the
+  names of the attributes.  The command <command>nix-env
+  --import</command> (which set the
+  <filename>~/.nix-defexpr</filename> symlink) is
+  removed.</para></listitem>
+
+
+  <listitem><para>Derivations can specify the new special attribute
+  <varname>allowedReferences</varname> to enforce that the references
+  in the output of a derivation are a subset of a declared set of
+  paths.  For example, if <varname>allowedReferences</varname> is an
+  empty list, then the output must not have any references.  This is
+  used in NixOS to check that generated files such as initial ramdisks
+  for booting Linux don’t have any dependencies.</para></listitem>
+
+
+  <listitem><para>The new attribute
+  <varname>exportReferencesGraph</varname> allows builders access to
+  the references graph of their inputs.  This is used in NixOS for
+  tasks such as generating ISO-9660 images that contain a Nix store
+  populated with the closure of certain paths.</para></listitem>
+
+
+  <listitem><para>Fixed-output derivations (like
+  <function>fetchurl</function>) can define the attribute
+  <varname>impureEnvVars</varname> to allow external environment
+  variables to be passed to builders.  This is used in Nixpkgs to
+  support proxy configuration, among other things.</para></listitem>
+
+
+  <listitem><para>Several new built-in functions:
+  <function>builtins.attrNames</function>,
+  <function>builtins.filterSource</function>,
+  <function>builtins.isAttrs</function>,
+  <function>builtins.isFunction</function>,
+  <function>builtins.listToAttrs</function>,
+  <function>builtins.stringLength</function>,
+  <function>builtins.sub</function>,
+  <function>builtins.substring</function>,
+  <function>throw</function>,
+  <function>builtins.trace</function>,
+  <function>builtins.readFile</function>.</para></listitem>
+
+
+</itemizedlist>
+
+</chapter>

doc/manual/release-notes/rl-012.xml

@@ -0,0 +1,175 @@
+<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="ssec-relnotes-0.12">
+
+<title>Release 0.12 (November 20, 2008)</title>
+
+<itemizedlist>
+
+  <listitem>
+    <para>Nix no longer uses Berkeley DB to store Nix store metadata.
+    The principal advantages of the new storage scheme are: it works
+    properly over decent implementations of NFS (allowing Nix stores
+    to be shared between multiple machines); no recovery is needed
+    when a Nix process crashes; no write access is needed for
+    read-only operations; no more running out of Berkeley DB locks on
+    certain operations.</para>
+
+    <para>You still need to compile Nix with Berkeley DB support if
+    you want Nix to automatically convert your old Nix store to the
+    new schema.  If you don’t need this, you can build Nix with the
+    <filename>configure</filename> option
+    <option>--disable-old-db-compat</option>.</para>
+
+    <para>After the automatic conversion to the new schema, you can
+    delete the old Berkeley DB files:
+
+    <screen>
+$ cd /nix/var/nix/db
+$ rm __db* log.* derivers references referrers reserved validpaths DB_CONFIG</screen>
+
+    The new metadata is stored in the directories
+    <filename>/nix/var/nix/db/info</filename> and
+    <filename>/nix/var/nix/db/referrer</filename>.  Though the
+    metadata is stored in human-readable plain-text files, they are
+    not intended to be human-editable, as Nix is rather strict about
+    the format.</para>
+
+    <para>The new storage schema may or may not require less disk
+    space than the Berkeley DB environment, mostly depending on the
+    cluster size of your file system.  With 1 KiB clusters (which
+    seems to be the <literal>ext3</literal> default nowadays) it
+    usually takes up much less space.</para>
+  </listitem>
+
+  <listitem><para>There is a new substituter that copies paths
+  directly from other (remote) Nix stores mounted somewhere in the
+  filesystem.  For instance, you can speed up an installation by
+  mounting some remote Nix store that already has the packages in
+  question via NFS or <literal>sshfs</literal>.  The environment
+  variable <envar>NIX_OTHER_STORES</envar> specifies the locations of
+  the remote Nix directories,
+  e.g. <literal>/mnt/remote-fs/nix</literal>.</para></listitem>
+
+  <listitem><para>New <command>nix-store</command> operations
+  <option>--dump-db</option> and <option>--load-db</option> to dump
+  and reload the Nix database.</para></listitem>
+
+  <listitem><para>The garbage collector has a number of new options to
+  allow only some of the garbage to be deleted.  The option
+  <option>--max-freed <replaceable>N</replaceable></option> tells the
+  collector to stop after at least <replaceable>N</replaceable> bytes
+  have been deleted.  The option <option>--max-links
+  <replaceable>N</replaceable></option> tells it to stop after the
+  link count on <filename>/nix/store</filename> has dropped below
+  <replaceable>N</replaceable>.  This is useful for very large Nix
+  stores on filesystems with a 32000 subdirectories limit (like
+  <literal>ext3</literal>).  The option <option>--use-atime</option>
+  causes store paths to be deleted in order of ascending last access
+  time.  This allows non-recently used stuff to be deleted.  The
+  option <option>--max-atime <replaceable>time</replaceable></option>
+  specifies an upper limit to the last accessed time of paths that may
+  be deleted.  For instance,
+
+    <screen>
+    $ nix-store --gc -v --max-atime $(date +%s -d "2 months ago")</screen>
+
+  deletes everything that hasn’t been accessed in two months.</para></listitem>
+
+  <listitem><para><command>nix-env</command> now uses optimistic
+  profile locking when performing an operation like installing or
+  upgrading, instead of setting an exclusive lock on the profile.
+  This allows multiple <command>nix-env -i / -u / -e</command>
+  operations on the same profile in parallel.  If a
+  <command>nix-env</command> operation sees at the end that the profile
+  was changed in the meantime by another process, it will just
+  restart.  This is generally cheap because the build results are
+  still in the Nix store.</para></listitem>
+
+  <listitem><para>The option <option>--dry-run</option> is now
+  supported by <command>nix-store -r</command> and
+  <command>nix-build</command>.</para></listitem>
+
+  <listitem><para>The information previously shown by
+  <option>--dry-run</option> (i.e., which derivations will be built
+  and which paths will be substituted) is now always shown by
+  <command>nix-env</command>, <command>nix-store -r</command> and
+  <command>nix-build</command>.  The total download size of
+  substitutable paths is now also shown.  For instance, a build will
+  show something like
+
+    <screen>
+the following derivations will be built:
+  /nix/store/129sbxnk5n466zg6r1qmq1xjv9zymyy7-activate-configuration.sh.drv
+  /nix/store/7mzy971rdm8l566ch8hgxaf89x7lr7ik-upstart-jobs.drv
+  ...
+the following paths will be downloaded/copied (30.02 MiB):
+  /nix/store/4m8pvgy2dcjgppf5b4cj5l6wyshjhalj-samba-3.2.4
+  /nix/store/7h1kwcj29ip8vk26rhmx6bfjraxp0g4l-libunwind-0.98.6
+  ...</screen>
+
+  </para></listitem>
+
+  <listitem><para>Language features:
+
+    <itemizedlist>
+
+      <listitem><para>@-patterns as in Haskell.  For instance, in a
+      function definition
+
+      <programlisting>f = args @ {x, y, z}: <replaceable>...</replaceable>;</programlisting>
+
+      <varname>args</varname> refers to the argument as a whole, which
+      is further pattern-matched against the attribute set pattern
+      <literal>{x, y, z}</literal>.</para></listitem>
+
+      <listitem><para>“<literal>...</literal>” (ellipsis) patterns.
+      An attribute set pattern can now say <literal>...</literal>  at
+      the end of the attribute name list to specify that the function
+      takes <emphasis>at least</emphasis> the listed attributes, while
+      ignoring additional attributes.  For instance,
+
+      <programlisting>{stdenv, fetchurl, fuse, ...}: <replaceable>...</replaceable></programlisting>
+
+      defines a function that accepts any attribute set that includes
+      at least the three listed attributes.</para></listitem>
+
+      <listitem><para>New primops:
+      <varname>builtins.parseDrvName</varname> (split a package name
+      string like <literal>"nix-0.12pre12876"</literal> into its name
+      and version components, e.g. <literal>"nix"</literal> and
+      <literal>"0.12pre12876"</literal>),
+      <varname>builtins.compareVersions</varname> (compare two version
+      strings using the same algorithm that <command>nix-env</command>
+      uses), <varname>builtins.length</varname> (efficiently compute
+      the length of a list), <varname>builtins.mul</varname> (integer
+      multiplication), <varname>builtins.div</varname> (integer
+      division).
+      <!-- <varname>builtins.genericClosure</varname> -->
+      </para></listitem>
+
+    </itemizedlist>
+
+  </para></listitem>
+
+  <listitem><para><command>nix-prefetch-url</command> now supports
+  <literal>mirror://</literal> URLs, provided that the environment
+  variable <envar>NIXPKGS_ALL</envar> points at a Nixpkgs
+  tree.</para></listitem>
+
+  <listitem><para>Removed the commands
+  <command>nix-pack-closure</command> and
+  <command>nix-unpack-closure</command>.   You can do almost the same
+  thing but much more efficiently by doing <literal>nix-store --export
+  $(nix-store -qR <replaceable>paths</replaceable>) > closure</literal> and
+  <literal>nix-store --import &lt;
+  closure</literal>.</para></listitem>
+
+  <listitem><para>Lots of bug fixes, including a big performance bug in
+  the handling of <literal>with</literal>-expressions.</para></listitem>
+
+</itemizedlist>
+
+</chapter>

doc/manual/release-notes/rl-013.xml

@@ -0,0 +1,106 @@
+<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="ssec-relnotes-0.13">
+
+<title>Release 0.13 (November 5, 2009)</title>
+
+<para>This is primarily a bug fix release.  It has some new
+features:</para>
+
+<itemizedlist>
+
+  <listitem>
+    <para>Syntactic sugar for writing nested attribute sets.  Instead of
+
+<programlisting>
+{
+  foo = {
+    bar = 123;
+    xyzzy = true;
+  };
+  a = { b = { c = "d"; }; };
+}
+</programlisting>
+
+    you can write
+
+<programlisting>
+{
+  foo.bar = 123;
+  foo.xyzzy = true;
+  a.b.c = "d";
+}
+</programlisting>
+
+    This is useful, for instance, in NixOS configuration files.</para>
+
+  </listitem>
+
+  <listitem>
+    <para>Support for Nix channels generated by Hydra, the Nix-based
+    continuous build system.  (Hydra generates NAR archives on the
+    fly, so the size and hash of these archives isn’t known in
+    advance.)</para>
+  </listitem>
+
+  <listitem>
+    <para>Support <literal>i686-linux</literal> builds directly on
+    <literal>x86_64-linux</literal> Nix installations.  This is
+    implemented using the <function>personality()</function> syscall,
+    which causes <command>uname</command> to return
+    <literal>i686</literal> in child processes.</para>
+  </listitem>
+
+  <listitem>
+    <para>Various improvements to the <literal>chroot</literal>
+    support.  Building in a <literal>chroot</literal> works quite well
+    now.</para>
+  </listitem>
+
+  <listitem>
+    <para>Nix no longer blocks if it tries to build a path and another
+    process is already building the same path.  Instead it tries to
+    build another buildable path first.  This improves
+    parallelism.</para>
+  </listitem>
+
+  <listitem>
+    <para>Support for large (> 4 GiB) files in NAR archives.</para>
+  </listitem>
+
+  <listitem>
+    <para>Various (performance) improvements to the remote build
+    mechanism.</para>
+  </listitem>
+
+  <listitem>
+    <para>New primops: <varname>builtins.addErrorContext</varname> (to
+    add a string to stack traces — useful for debugging),
+    <varname>builtins.isBool</varname>,
+    <varname>builtins.isString</varname>,
+    <varname>builtins.isInt</varname>,
+    <varname>builtins.intersectAttrs</varname>.</para>
+  </listitem>
+
+  <listitem>
+    <para>OpenSolaris support (Sander van der Burg).</para>
+  </listitem>
+
+  <listitem>
+    <para>Stack traces are no longer displayed unless the
+    <option>--show-trace</option> option is used.</para>
+  </listitem>
+
+  <listitem>
+    <para>The scoping rules for <literal>inherit
+    (<replaceable>e</replaceable>) ...</literal> in recursive
+    attribute sets have changed.  The expression
+    <replaceable>e</replaceable> can now refer to the attributes
+    defined in the containing set.</para>
+  </listitem>
+
+</itemizedlist>
+
+</chapter>

doc/manual/release-notes/rl-014.xml

@@ -0,0 +1,44 @@
+<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="ssec-relnotes-0.14"><title>Release 0.14 (February 4, 2010)</title>
+
+<para>This release has the following improvements:</para>
+
+<itemizedlist>
+
+  <listitem>
+    <para>The garbage collector now starts deleting garbage much
+    faster than before.  It no longer determines liveness of all paths
+    in the store, but does so on demand.</para>
+  </listitem>
+
+  <listitem>
+    <para>Added a new operation, <command>nix-store --query
+    --roots</command>, that shows the garbage collector roots that
+    directly or indirectly point to the given store paths.</para>
+  </listitem>
+
+  <listitem>
+    <para>Removed support for converting Berkeley DB-based Nix
+    databases to the new schema.</para>
+  </listitem>
+
+  <listitem>
+    <para>Removed the <option>--use-atime</option> and
+    <option>--max-atime</option> garbage collector options.  They were
+    not very useful in practice.</para>
+  </listitem>
+
+  <listitem>
+    <para>On Windows, Nix now requires Cygwin 1.7.x.</para>
+  </listitem>
+
+  <listitem>
+    <para>A few bug fixes.</para>
+  </listitem>
+
+</itemizedlist>
+
+</chapter>

doc/manual/release-notes/rl-015.xml

@@ -0,0 +1,14 @@
+<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="ssec-relnotes-0.15">
+
+<title>Release 0.15 (March 17, 2010)</title>
+
+<para>This is a bug-fix release.  Among other things, it fixes
+building on Mac OS X (Snow Leopard), and improves the contents of
+<filename>/etc/passwd</filename> and <filename>/etc/group</filename>
+in <literal>chroot</literal> builds.</para>
+
+</chapter>

doc/manual/release-notes/rl-016.xml

@@ -0,0 +1,55 @@
+<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="ssec-relnotes-0.16">
+
+<title>Release 0.16 (August 17, 2010)</title>
+
+<para>This release has the following improvements:</para>
+
+<itemizedlist>
+
+  <listitem>
+    <para>The Nix expression evaluator is now much faster in most
+    cases: typically, <link
+    xlink:href="http://www.mail-archive.com/nix-dev@cs.uu.nl/msg04113.html">3
+    to 8 times compared to the old implementation</link>.  It also
+    uses less memory.  It no longer depends on the ATerm
+    library.</para>
+  </listitem>
+
+  <listitem>
+    <para>
+      Support for configurable parallelism inside builders.  Build
+      scripts have always had the ability to perform multiple build
+      actions in parallel (for instance, by running <command>make -j
+      2</command>), but this was not desirable because the number of
+      actions to be performed in parallel was not configurable.  Nix
+      now has an option <option>--cores
+      <replaceable>N</replaceable></option> as well as a configuration
+      setting <varname>build-cores =
+      <replaceable>N</replaceable></varname> that causes the
+      environment variable <envar>NIX_BUILD_CORES</envar> to be set to
+      <replaceable>N</replaceable> when the builder is invoked.  The
+      builder can use this at its discretion to perform a parallel
+      build, e.g., by calling <command>make -j
+      <replaceable>N</replaceable></command>.  In Nixpkgs, this can be
+      enabled on a per-package basis by setting the derivation
+      attribute <varname>enableParallelBuilding</varname> to
+      <literal>true</literal>.
+    </para>
+  </listitem>
+
+  <listitem>
+    <para><command>nix-store -q</command> now supports XML output
+    through the <option>--xml</option> flag.</para>
+  </listitem>
+
+  <listitem>
+    <para>Several bug fixes.</para>
+  </listitem>
+
+</itemizedlist>
+
+</chapter>

doc/manual/release-notes/rl-05.xml

@@ -0,0 +1,11 @@
+<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-relnotes-0.5">
+
+<title>Release 0.5 and earlier</title>
+
+<para>Please refer to the Subversion commit log messages.</para>
+
+</chapter>

doc/manual/release-notes/rl-06.xml

@@ -0,0 +1,122 @@
+<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-relnotes-0.6">
+
+<title>Release 0.6 (November 14, 2004)</title>
+
+<itemizedlist>
+
+  <listitem>
+    <para>Rewrite of the normalisation engine.
+
+    <itemizedlist>
+
+      <listitem><para>Multiple builds can now be performed in parallel
+      (option <option>-j</option>).</para></listitem>
+
+      <listitem><para>Distributed builds.  Nix can now call a shell
+      script to forward builds to Nix installations on remote
+      machines, which may or may not be of the same platform
+      type.</para></listitem>
+
+      <listitem><para>Option <option>--fallback</option> allows
+      recovery from broken substitutes.</para></listitem>
+
+      <listitem><para>Option <option>--keep-going</option> causes
+      building of other (unaffected) derivations to continue if one
+      failed.</para></listitem>
+
+    </itemizedlist>
+
+    </para>
+
+  </listitem>
+
+  <listitem><para>Improvements to the garbage collector (i.e., it
+  should actually work now).</para></listitem>
+
+  <listitem><para>Setuid Nix installations allow a Nix store to be
+  shared among multiple users.</para></listitem>
+
+  <listitem><para>Substitute registration is much faster
+  now.</para></listitem>
+
+  <listitem><para>A utility <command>nix-build</command> to build a
+  Nix expression and create a symlink to the result int the current
+  directory; useful for testing Nix derivations.</para></listitem>
+
+  <listitem><para>Manual updates.</para></listitem>
+
+  <listitem>
+
+    <para><command>nix-env</command> changes:
+
+    <itemizedlist>
+
+      <listitem><para>Derivations for other platforms are filtered out
+      (which can be overridden using
+      <option>--system-filter</option>).</para></listitem>
+
+      <listitem><para><option>--install</option> by default now
+      uninstall previous derivations with the same
+      name.</para></listitem>
+
+      <listitem><para><option>--upgrade</option> allows upgrading to a
+      specific version.</para></listitem>
+
+      <listitem><para>New operation
+      <option>--delete-generations</option> to remove profile
+      generations (necessary for effective garbage
+      collection).</para></listitem>
+
+      <listitem><para>Nicer output (sorted,
+      columnised).</para></listitem>
+
+    </itemizedlist>
+
+    </para>
+
+  </listitem>
+
+  <listitem><para>More sensible verbosity levels all around (builder
+  output is now shown always, unless <option>-Q</option> is
+  given).</para></listitem>
+
+  <listitem>
+
+    <para>Nix expression language changes:
+
+    <itemizedlist>
+
+      <listitem><para>New language construct: <literal>with
+      <replaceable>E1</replaceable>;
+      <replaceable>E2</replaceable></literal> brings all attributes
+      defined in the attribute set <replaceable>E1</replaceable> in
+      scope in <replaceable>E2</replaceable>.</para></listitem>
+
+      <listitem><para>Added a <function>map</function>
+      function.</para></listitem>
+
+      <listitem><para>Various new operators (e.g., string
+      concatenation).</para></listitem>
+
+    </itemizedlist>
+
+    </para>
+
+  </listitem>
+
+  <listitem><para>Expression evaluation is much
+  faster.</para></listitem>
+
+  <listitem><para>An Emacs mode for editing Nix expressions (with
+  syntax highlighting and indentation) has been
+  added.</para></listitem>
+
+  <listitem><para>Many bug fixes.</para></listitem>
+
+</itemizedlist>
+
+</chapter>

doc/manual/release-notes/rl-07.xml

@@ -0,0 +1,35 @@
+<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-relnotes-0.7">
+
+<title>Release 0.7 (January 12, 2005)</title>
+
+<itemizedlist>
+
+  <listitem><para>Binary patching.  When upgrading components using
+  pre-built binaries (through nix-pull / nix-channel), Nix can
+  automatically download and apply binary patches to already installed
+  components instead of full downloads.  Patching is “smart”: if there
+  is a <emphasis>sequence</emphasis> of patches to an installed
+  component, Nix will use it.  Patches are currently generated
+  automatically between Nixpkgs (pre-)releases.</para></listitem>
+
+  <listitem><para>Simplifications to the substitute
+  mechanism.</para></listitem>
+
+  <listitem><para>Nix-pull now stores downloaded manifests in
+  <filename>/nix/var/nix/manifests</filename>.</para></listitem>
+
+  <listitem><para>Metadata on files in the Nix store is canonicalised
+  after builds: the last-modified timestamp is set to 0 (00:00:00
+  1/1/1970), the mode is set to 0444 or 0555 (readable and possibly
+  executable by all; setuid/setgid bits are dropped), and the group is
+  set to the default.  This ensures that the result of a build and an
+  installation through a substitute is the same; and that timestamp
+  dependencies are revealed.</para></listitem>
+
+</itemizedlist>
+
+</chapter>

doc/manual/release-notes/rl-08.xml

@@ -0,0 +1,246 @@
+<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-relnotes-0.8">
+
+<title>Release 0.8 (April 11, 2005)</title>
+
+<para>NOTE: the hashing scheme in Nix 0.8 changed (as detailed below).
+As a result, <command>nix-pull</command> manifests and channels built
+for Nix 0.7 and below will now work anymore.  However, the Nix
+expression language has not changed, so you can still build from
+source.  Also, existing user environments continue to work.  Nix 0.8
+will automatically upgrade the database schema of previous
+installations when it is first run.</para>
+
+<para>If you get the error message
+
+<screen>
+you have an old-style manifest `/nix/var/nix/manifests/[...]'; please
+delete it</screen>
+
+you should delete previously downloaded manifests:
+
+<screen>
+$ rm /nix/var/nix/manifests/*</screen>
+
+If <command>nix-channel</command> gives the error message
+
+<screen>
+manifest `http://catamaran.labs.cs.uu.nl/dist/nix/channels/[channel]/MANIFEST'
+is too old (i.e., for Nix &lt;= 0.7)</screen>
+
+then you should unsubscribe from the offending channel
+(<command>nix-channel --remove
+<replaceable>URL</replaceable></command>; leave out
+<literal>/MANIFEST</literal>), and subscribe to the same URL, with
+<literal>channels</literal> replaced by <literal>channels-v3</literal>
+(e.g., <link
+xlink:href='http://catamaran.labs.cs.uu.nl/dist/nix/channels-v3/nixpkgs-unstable'
+/>).</para>
+
+<para>Nix 0.8 has the following improvements:
+
+<itemizedlist>
+
+  <listitem><para>The cryptographic hashes used in store paths are now
+  160 bits long, but encoded in base-32 so that they are still only 32
+  characters long (e.g.,
+  <filename>/nix/store/csw87wag8bqlqk7ipllbwypb14xainap-atk-1.9.0</filename>).
+  (This is actually a 160 bit truncation of a SHA-256
+  hash.)</para></listitem>
+
+  <listitem><para>Big cleanups and simplifications of the basic store
+  semantics.  The notion of “closure store expressions” is gone (and
+  so is the notion of “successors”); the file system references of a
+  store path are now just stored in the database.</para>
+
+  <para>For instance, given any store path, you can query its closure:
+
+  <screen>
+$ nix-store -qR $(which firefox)
+... lots of paths ...</screen>
+
+  Also, Nix now remembers for each store path the derivation that
+  built it (the “deriver”):
+
+  <screen>
+$ nix-store -qR $(which firefox)
+/nix/store/4b0jx7vq80l9aqcnkszxhymsf1ffa5jd-firefox-1.0.1.drv</screen>
+
+  So to see the build-time dependencies, you can do
+
+  <screen>
+$ nix-store -qR $(nix-store -qd $(which firefox))</screen>
+
+  or, in a nicer format:
+
+  <screen>
+$ nix-store -q --tree $(nix-store -qd $(which firefox))</screen>
+
+  </para>
+
+  <para>File system references are also stored in reverse.  For
+  instance, you can query all paths that directly or indirectly use a
+  certain Glibc:
+
+  <screen>
+$ nix-store -q --referrers-closure \
+    /nix/store/8lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4</screen>
+
+  </para>
+
+  </listitem>
+
+  <listitem><para>The concept of fixed-output derivations has been
+  formalised.  Previously, functions such as
+  <function>fetchurl</function> in Nixpkgs used a hack (namely,
+  explicitly specifying a store path hash) to prevent changes to, say,
+  the URL of the file from propagating upwards through the dependency
+  graph, causing rebuilds of everything.  This can now be done cleanly
+  by specifying the <varname>outputHash</varname> and
+  <varname>outputHashAlgo</varname> attributes.  Nix itself checks
+  that the content of the output has the specified hash.  (This is
+  important for maintaining certain invariants necessary for future
+  work on secure shared stores.)</para></listitem>
+
+  <listitem><para>One-click installation :-) It is now possible to
+  install any top-level component in Nixpkgs directly, through the web
+  — see, e.g., <link
+  xlink:href='http://catamaran.labs.cs.uu.nl/dist/nixpkgs-0.8/' />.
+  All you have to do is associate
+  <filename>/nix/bin/nix-install-package</filename> with the MIME type
+  <literal>application/nix-package</literal> (or the extension
+  <filename>.nixpkg</filename>), and clicking on a package link will
+  cause it to be installed, with all appropriate dependencies.  If you
+  just want to install some specific application, this is easier than
+  subscribing to a channel.</para></listitem>
+
+  <listitem><para><command>nix-store -r
+  <replaceable>PATHS</replaceable></command> now builds all the
+  derivations PATHS in parallel.  Previously it did them sequentially
+  (though exploiting possible parallelism between subderivations).
+  This is nice for build farms.</para></listitem>
+
+  <listitem><para><command>nix-channel</command> has new operations
+  <option>--list</option> and
+  <option>--remove</option>.</para></listitem>
+
+  <listitem><para>New ways of installing components into user
+  environments:
+
+  <itemizedlist>
+
+    <listitem><para>Copy from another user environment:
+
+    <screen>
+$ nix-env -i --from-profile .../other-profile firefox</screen>
+
+    </para></listitem>
+
+    <listitem><para>Install a store derivation directly (bypassing the
+    Nix expression language entirely):
+
+    <screen>
+$ nix-env -i /nix/store/z58v41v21xd3...-aterm-2.3.1.drv</screen>
+
+    (This is used to implement <command>nix-install-package</command>,
+    which is therefore immune to evolution in the Nix expression
+    language.)</para></listitem>
+
+    <listitem><para>Install an already built store path directly:
+
+    <screen>
+$ nix-env -i /nix/store/hsyj5pbn0d9i...-aterm-2.3.1</screen>
+
+    </para></listitem>
+
+    <listitem><para>Install the result of a Nix expression specified
+    as a command-line argument:
+
+    <screen>
+$ nix-env -f .../i686-linux.nix -i -E 'x: x.firefoxWrapper'</screen>
+
+    The difference with the normal installation mode is that
+    <option>-E</option> does not use the <varname>name</varname>
+    attributes of derivations.  Therefore, this can be used to
+    disambiguate multiple derivations with the same
+    name.</para></listitem>
+
+  </itemizedlist></para></listitem>
+
+  <listitem><para>A hash of the contents of a store path is now stored
+  in the database after a successful build.  This allows you to check
+  whether store paths have been tampered with: <command>nix-store
+  --verify --check-contents</command>.</para></listitem>
+
+  <listitem>
+
+    <para>Implemented a concurrent garbage collector.  It is now
+    always safe to run the garbage collector, even if other Nix
+    operations are happening simultaneously.</para>
+
+    <para>However, there can still be GC races if you use
+    <command>nix-instantiate</command> and <command>nix-store
+    --realise</command> directly to build things.  To prevent races,
+    use the <option>--add-root</option> flag of those commands.</para>
+
+  </listitem>
+
+  <listitem><para>The garbage collector now finally deletes paths in
+  the right order (i.e., topologically sorted under the “references”
+  relation), thus making it safe to interrupt the collector without
+  risking a store that violates the closure
+  invariant.</para></listitem>
+
+  <listitem><para>Likewise, the substitute mechanism now downloads
+  files in the right order, thus preserving the closure invariant at
+  all times.</para></listitem>
+
+  <listitem><para>The result of <command>nix-build</command> is now
+  registered as a root of the garbage collector.  If the
+  <filename>./result</filename> link is deleted, the GC root
+  disappears automatically.</para></listitem>
+
+  <listitem>
+
+    <para>The behaviour of the garbage collector can be changed
+    globally by setting options in
+    <filename>/nix/etc/nix/nix.conf</filename>.
+
+    <itemizedlist>
+
+      <listitem><para><literal>gc-keep-derivations</literal> specifies
+      whether deriver links should be followed when searching for live
+      paths.</para></listitem>
+
+      <listitem><para><literal>gc-keep-outputs</literal> specifies
+      whether outputs of derivations should be followed when searching
+      for live paths.</para></listitem>
+
+      <listitem><para><literal>env-keep-derivations</literal>
+      specifies whether user environments should store the paths of
+      derivations when they are added (thus keeping the derivations
+      alive).</para></listitem>
+
+    </itemizedlist>
+
+  </para></listitem>
+
+  <listitem><para>New <command>nix-env</command> query flags
+  <option>--drv-path</option> and
+  <option>--out-path</option>.</para></listitem>
+
+  <listitem><para><command>fetchurl</command> allows SHA-1 and SHA-256
+  in addition to MD5.  Just specify the attribute
+  <varname>sha1</varname> or <varname>sha256</varname> instead of
+  <varname>md5</varname>.</para></listitem>
+
+  <listitem><para>Manual updates.</para></listitem>
+
+</itemizedlist>
+
+</para>
+
+</chapter>

doc/manual/release-notes/rl-081.xml

@@ -0,0 +1,21 @@
+<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-relnotes-0.8.1">
+
+<title>Release 0.8.1 (April 13, 2005)</title>
+
+<para>This is a bug fix release.</para>
+
+<itemizedlist>
+
+  <listitem><para>Patch downloading was broken.</para></listitem>
+
+  <listitem><para>The garbage collector would not delete paths that
+  had references from invalid (but substitutable)
+  paths.</para></listitem>
+
+</itemizedlist>
+
+</chapter>

doc/manual/release-notes/rl-09.xml

@@ -0,0 +1,98 @@
+<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-relnotes-0.9">
+
+<title>Release 0.9 (September 16, 2005)</title>
+
+<para>NOTE: this version of Nix uses Berkeley DB 4.3 instead of 4.2.
+The database is upgraded automatically, but you should be careful not
+to use old versions of Nix that still use Berkeley DB 4.2.  In
+particular, if you use a Nix installed through Nix, you should run
+
+<screen>
+$ nix-store --clear-substitutes</screen>
+
+first.</para>
+
+
+<itemizedlist>
+
+  <listitem><para>Unpacking of patch sequences is much faster now
+  since we no longer do redundant unpacking and repacking of
+  intermediate paths.</para></listitem>
+
+  <listitem><para>Nix now uses Berkeley DB 4.3.</para></listitem>
+
+  <listitem><para>The <function>derivation</function> primitive is
+  lazier.  Attributes of dependent derivations can mutually refer to
+  each other (as long as there are no data dependencies on the
+  <varname>outPath</varname> and <varname>drvPath</varname> attributes
+  computed by <function>derivation</function>).</para>
+
+  <para>For example, the expression <literal>derivation
+  attrs</literal> now evaluates to (essentially)
+
+  <programlisting>
+attrs // {
+  type = "derivation";
+  outPath = derivation! attrs;
+  drvPath = derivation! attrs;
+}</programlisting>
+
+  where <function>derivation!</function> is a primop that does the
+  actual derivation instantiation (i.e., it does what
+  <function>derivation</function> used to do).  The advantage is that
+  it allows commands such as <command>nix-env -qa</command> and
+  <command>nix-env -i</command> to be much faster since they no longer
+  need to instantiate all derivations, just the
+  <varname>name</varname> attribute.</para>
+
+  <para>Also, it allows derivations to cyclically reference each
+  other, for example,
+
+  <programlisting>
+webServer = derivation {
+  ...
+  hostName = "svn.cs.uu.nl";
+  services = [svnService];
+};
+&#x20;
+svnService = derivation {
+  ...
+  hostName = webServer.hostName;
+};</programlisting>
+
+  Previously, this would yield a black hole (infinite recursion).</para>
+
+  </listitem>
+
+  <listitem><para><command>nix-build</command> now defaults to using
+  <filename>./default.nix</filename> if no Nix expression is
+  specified.</para></listitem>
+
+  <listitem><para><command>nix-instantiate</command>, when applied to
+  a Nix expression that evaluates to a function, will call the
+  function automatically if all its arguments have
+  defaults.</para></listitem>
+
+  <listitem><para>Nix now uses libtool to build dynamic libraries.
+  This reduces the size of executables.</para></listitem>
+
+  <listitem><para>A new list concatenation operator
+  <literal>++</literal>.  For example, <literal>[1 2 3] ++ [4 5
+  6]</literal> evaluates to <literal>[1 2 3 4 5
+  6]</literal>.</para></listitem>
+
+  <listitem><para>Some currently undocumented primops to support
+  low-level build management using Nix (i.e., using Nix as a Make
+  replacement).  See the commit messages for <literal>r3578</literal>
+  and <literal>r3580</literal>.</para></listitem>
+
+  <listitem><para>Various bug fixes and performance
+  improvements.</para></listitem>
+
+</itemizedlist>
+
+</chapter>

doc/manual/release-notes/rl-091.xml

@@ -0,0 +1,13 @@
+<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-relnotes-0.9.1">
+
+<title>Release 0.9.1 (September 20, 2005)</title>
+
+<para>This bug fix release addresses a problem with the ATerm library
+when the <option>--with-aterm</option> flag in
+<command>configure</command> was <emphasis>not</emphasis> used.</para>
+
+</chapter>

doc/manual/release-notes/rl-092.xml

@@ -0,0 +1,28 @@
+<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-relnotes-0.9.2">
+
+<title>Release 0.9.2 (September 21, 2005)</title>
+
+<para>This bug fix release fixes two problems on Mac OS X:
+
+<itemizedlist>
+
+  <listitem><para>If Nix was linked against statically linked versions
+  of the ATerm or Berkeley DB library, there would be dynamic link
+  errors at runtime.</para></listitem>
+
+  <listitem><para><command>nix-pull</command> and
+  <command>nix-push</command> intermittently failed due to race
+  conditions involving pipes and child processes with error messages
+  such as <literal>open2: open(GLOB(0x180b2e4), >&amp;=9) failed: Bad
+  file descriptor at /nix/bin/nix-pull line 77</literal> (issue
+  <literal>NIX-14</literal>).</para></listitem>
+
+</itemizedlist>
+
+</para>
+
+</chapter>

doc/manual/release-notes/rl-10.xml

@@ -0,0 +1,119 @@
+<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="ssec-relnotes-1.0">
+
+<title>Release 1.0 (May 11, 2012)</title>
+
+<para>There have been numerous improvements and bug fixes since the
+previous release.  Here are the most significant:</para>
+
+<itemizedlist>
+
+  <listitem>
+    <para>Nix can now optionally use the Boehm garbage collector.
+    This significantly reduces the Nix evaluator’s memory footprint,
+    especially when evaluating large NixOS system configurations.  It
+    can be enabled using the <option>--enable-gc</option> configure
+    option.</para>
+  </listitem>
+
+  <listitem>
+    <para>Nix now uses SQLite for its database.  This is faster and
+    more flexible than the old <emphasis>ad hoc</emphasis> format.
+    SQLite is also used to cache the manifests in
+    <filename>/nix/var/nix/manifests</filename>, resulting in a
+    significant speedup.</para>
+  </listitem>
+
+  <listitem>
+    <para>Nix now has an search path for expressions.  The search path
+    is set using the environment variable <envar>NIX_PATH</envar> and
+    the <option>-I</option> command line option.  In Nix expressions,
+    paths between angle brackets are used to specify files that must
+    be looked up in the search path.  For instance, the expression
+    <literal>&lt;nixpkgs/default.nix></literal> looks for a file
+    <filename>nixpkgs/default.nix</filename> relative to every element
+    in the search path.</para>
+  </listitem>
+
+  <listitem>
+    <para>The new command <command>nix-build --run-env</command>
+    builds all dependencies of a derivation, then starts a shell in an
+    environment containing all variables from the derivation.  This is
+    useful for reproducing the environment of a derivation for
+    development.</para>
+  </listitem>
+
+  <listitem>
+    <para>The new command <command>nix-store --verify-path</command>
+    verifies that the contents of a store path have not
+    changed.</para>
+  </listitem>
+
+  <listitem>
+    <para>The new command <command>nix-store --print-env</command>
+    prints out the environment of a derivation in a format that can be
+    evaluated by a shell.</para>
+  </listitem>
+
+  <listitem>
+    <para>Attribute names can now be arbitrary strings.  For instance,
+    you can write <literal>{ "foo-1.2" = …; "bla bla" = …; }."bla
+    bla"</literal>.</para>
+  </listitem>
+
+  <listitem>
+    <para>Attribute selection can now provide a default value using
+    the <literal>or</literal> operator.  For instance, the expression
+    <literal>x.y.z or e</literal> evaluates to the attribute
+    <literal>x.y.z</literal> if it exists, and <literal>e</literal>
+    otherwise.</para>
+  </listitem>
+
+  <listitem>
+    <para>The right-hand side of the <literal>?</literal> operator can
+    now be an attribute path, e.g., <literal>attrs ?
+    a.b.c</literal>.</para>
+  </listitem>
+
+  <listitem>
+    <para>On Linux, Nix will now make files in the Nix store immutable
+    on filesystems that support it.  This prevents accidental
+    modification of files in the store by the root user.</para>
+  </listitem>
+
+  <listitem>
+    <para>Nix has preliminary support for derivations with multiple
+    outputs.  This is useful because it allows parts of a package to
+    be deployed and garbage-collected separately.  For instance,
+    development parts of a package such as header files or static
+    libraries would typically not be part of the closure of an
+    application, resulting in reduced disk usage and installation
+    time.</para>
+  </listitem>
+
+  <listitem>
+    <para>The Nix store garbage collector is faster and holds the
+    global lock for a shorter amount of time.</para>
+  </listitem>
+
+  <listitem>
+    <para>The option <option>--timeout</option> (corresponding to the
+    configuration setting <literal>build-timeout</literal>) allows you
+    to set an absolute timeout on builds — if a build runs for more than
+    the given number of seconds, it is terminated.  This is useful for
+    recovering automatically from builds that are stuck in an infinite
+    loop but keep producing output, and for which
+    <literal>--max-silent-time</literal> is ineffective.</para>
+  </listitem>
+
+  <listitem>
+    <para>Nix development has moved to GitHub (<link
+    xlink:href="https://github.com/NixOS/nix" />).</para>
+  </listitem>
+
+</itemizedlist>
+
+</chapter>

doc/manual/release-notes/rl-11.xml

@@ -0,0 +1,100 @@
+<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="ssec-relnotes-1.1">
+
+<title>Release 1.1 (July 18, 2012)</title>
+
+<para>This release has the following improvements:</para>
+
+<itemizedlist>
+
+  <listitem>
+    <para>On Linux, when doing a chroot build, Nix now uses various
+    namespace features provided by the Linux kernel to improve
+    build isolation.  Namely:
+    <itemizedlist>
+      <listitem><para>The private network namespace ensures that
+      builders cannot talk to the outside world (or vice versa): each
+      build only sees a private loopback interface.  This also means
+      that two concurrent builds can listen on the same port (e.g. as
+      part of a test) without conflicting with each
+      other.</para></listitem>
+      <listitem><para>The PID namespace causes each build to start as
+      PID 1.  Processes outside of the chroot are not visible to those
+      on the inside.  On the other hand, processes inside the chroot
+      <emphasis>are</emphasis> visible from the outside (though with
+      different PIDs).</para></listitem>
+      <listitem><para>The IPC namespace prevents the builder from
+      communicating with outside processes using SysV IPC mechanisms
+      (shared memory, message queues, semaphores).  It also ensures
+      that all IPC objects are destroyed when the builder
+      exits.</para></listitem>
+      <listitem><para>The UTS namespace ensures that builders see a
+      hostname of <literal>localhost</literal> rather than the actual
+      hostname.</para></listitem>
+      <listitem><para>The private mount namespace was already used by
+      Nix to ensure that the bind-mounts used to set up the chroot are
+      cleaned up automatically.</para></listitem>
+    </itemizedlist>
+    </para>
+  </listitem>
+
+  <listitem>
+    <para>Build logs are now compressed using
+    <command>bzip2</command>.  The command <command>nix-store
+    -l</command> decompresses them on the fly.  This can be disabled
+    by setting the option <literal>build-compress-log</literal> to
+    <literal>false</literal>.</para>
+  </listitem>
+
+  <listitem>
+    <para>The creation of build logs in
+    <filename>/nix/var/log/nix/drvs</filename> can be disabled by
+    setting the new option <literal>build-keep-log</literal> to
+    <literal>false</literal>.  This is useful, for instance, for Hydra
+    build machines.</para>
+  </listitem>
+
+  <listitem>
+    <para>Nix now reserves some space in
+    <filename>/nix/var/nix/db/reserved</filename> to ensure that the
+    garbage collector can run successfully if the disk is full.  This
+    is necessary because SQLite transactions fail if the disk is
+    full.</para>
+  </listitem>
+
+  <listitem>
+    <para>Added a basic <function>fetchurl</function> function.  This
+    is not intended to replace the <function>fetchurl</function> in
+    Nixpkgs, but is useful for bootstrapping; e.g., it will allow us
+    to get rid of the bootstrap binaries in the Nixpkgs source tree
+    and download them instead.  You can use it by doing
+    <literal>import &lt;nix/fetchurl.nix> { url =
+    <replaceable>url</replaceable>; sha256 =
+    "<replaceable>hash</replaceable>"; }</literal>. (Shea Levy)</para>
+  </listitem>
+
+  <listitem>
+    <para>Improved RPM spec file. (Michel Alexandre Salim)</para>
+  </listitem>
+
+  <listitem>
+    <para>Support for on-demand socket-based activation in the Nix
+    daemon with <command>systemd</command>.</para>
+  </listitem>
+
+  <listitem>
+    <para>Added a manpage for
+    <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+  </listitem>
+
+  <listitem>
+    <para>When using the Nix daemon, the <option>-s</option> flag in
+    <command>nix-env -qa</command> is now much faster.</para>
+  </listitem>
+
+</itemizedlist>
+
+</chapter>

doc/manual/release-notes/rl-12.xml

@@ -0,0 +1,157 @@
+<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="ssec-relnotes-1.2">
+
+<title>Release 1.2 (December 6, 2012)</title>
+
+<para>This release has the following improvements and changes:</para>
+
+<itemizedlist>
+
+  <listitem>
+    <para>Nix has a new binary substituter mechanism: the
+    <emphasis>binary cache</emphasis>.  A binary cache contains
+    pre-built binaries of Nix packages.  Whenever Nix wants to build a
+    missing Nix store path, it will check a set of binary caches to
+    see if any of them has a pre-built binary of that path.  The
+    configuration setting <option>binary-caches</option> contains a
+    list of URLs of binary caches.  For instance, doing
+<screen>
+$ nix-env -i thunderbird --option binary-caches http://cache.nixos.org
+</screen>
+    will install Thunderbird and its dependencies, using the available
+    pre-built binaries in <uri>http://cache.nixos.org</uri>.
+    The main advantage over the old “manifest”-based method of getting
+    pre-built binaries is that you don’t have to worry about your
+    manifest being in sync with the Nix expressions you’re installing
+    from; i.e., you don’t need to run <command>nix-pull</command> to
+    update your manifest.  It’s also more scalable because you don’t
+    need to redownload a giant manifest file every time.
+    </para>
+
+    <para>A Nix channel can provide a binary cache URL that will be
+    used automatically if you subscribe to that channel.  If you use
+    the Nixpkgs or NixOS channels
+    (<uri>http://nixos.org/channels</uri>) you automatically get the
+    cache <uri>http://cache.nixos.org</uri>.</para>
+
+    <para>Binary caches are created using <command>nix-push</command>.
+    For details on the operation and format of binary caches, see the
+    <command>nix-push</command> manpage.  More details are provided in
+    <link xlink:href="http://lists.science.uu.nl/pipermail/nix-dev/2012-September/009826.html">this
+    nix-dev posting</link>.</para>
+  </listitem>
+
+  <listitem>
+    <para>Multiple output support should now be usable.  A derivation
+    can declare that it wants to produce multiple store paths by
+    saying something like
+<programlisting>
+outputs = [ "lib" "headers" "doc" ];
+</programlisting>
+    This will cause Nix to pass the intended store path of each output
+    to the builder through the environment variables
+    <literal>lib</literal>, <literal>headers</literal> and
+    <literal>doc</literal>.  Other packages can refer to a specific
+    output by referring to
+    <literal><replaceable>pkg</replaceable>.<replaceable>output</replaceable></literal>,
+    e.g.
+<programlisting>
+buildInputs = [ pkg.lib pkg.headers ];
+</programlisting>
+    If you install a package with multiple outputs using
+    <command>nix-env</command>, each output path will be symlinked
+    into the user environment.</para>
+  </listitem>
+
+  <listitem>
+    <para>Dashes are now valid as part of identifiers and attribute
+    names.</para>
+  </listitem>
+
+  <listitem>
+    <para>The new operation <command>nix-store --repair-path</command>
+    allows corrupted or missing store paths to be repaired by
+    redownloading them.  <command>nix-store --verify --check-contents
+    --repair</command> will scan and repair all paths in the Nix
+    store.  Similarly, <command>nix-env</command>,
+    <command>nix-build</command>, <command>nix-instantiate</command>
+    and <command>nix-store --realise</command> have a
+    <option>--repair</option> flag to detect and fix bad paths by
+    rebuilding or redownloading them.</para>
+  </listitem>
+
+  <listitem>
+    <para>Nix no longer sets the immutable bit on files in the Nix
+    store.  Instead, the recommended way to guard the Nix store
+    against accidental modification on Linux is to make it a read-only
+    bind mount, like this:
+
+<screen>
+$ mount --bind /nix/store /nix/store
+$ mount -o remount,ro,bind /nix/store
+</screen>
+
+    Nix will automatically make <filename>/nix/store</filename>
+    writable as needed (using a private mount namespace) to allow
+    modifications.</para>
+  </listitem>
+
+  <listitem>
+    <para>Store optimisation (replacing identical files in the store
+    with hard links) can now be done automatically every time a path
+    is added to the store.  This is enabled by setting the
+    configuration option <literal>auto-optimise-store</literal> to
+    <literal>true</literal> (disabled by default).</para>
+  </listitem>
+
+  <listitem>
+    <para>Nix now supports <command>xz</command> compression for NARs
+    in addition to <command>bzip2</command>.  It compresses about 30%
+    better on typical archives and decompresses about twice as
+    fast.</para>
+  </listitem>
+
+  <listitem>
+    <para>Basic Nix expression evaluation profiling: setting the
+    environment variable <envar>NIX_COUNT_CALLS</envar> to
+    <literal>1</literal> will cause Nix to print how many times each
+    primop or function was executed.</para>
+  </listitem>
+
+  <listitem>
+    <para>New primops: <varname>concatLists</varname>,
+    <varname>elem</varname>, <varname>elemAt</varname> and
+    <varname>filter</varname>.</para>
+  </listitem>
+
+  <listitem>
+    <para>The command <command>nix-copy-closure</command> has a new
+    flag <option>--use-substitutes</option> (<option>-s</option>) to
+    download missing paths on the target machine using the substitute
+    mechanism.</para>
+  </listitem>
+
+  <listitem>
+    <para>The command <command>nix-worker</command> has been renamed
+    to <command>nix-daemon</command>.  Support for running the Nix
+    worker in “slave” mode has been removed.</para>
+  </listitem>
+
+  <listitem>
+    <para>The <option>--help</option> flag of every Nix command now
+    invokes <command>man</command>.</para>
+  </listitem>
+
+  <listitem>
+    <para>Chroot builds are now supported on systemd machines.</para>
+  </listitem>
+
+</itemizedlist>
+
+<para>This release has contributions from Eelco Dolstra, Florian
+Friesdorf, Mats Erik Andersson and Shea Levy.</para>
+
+</chapter>

doc/manual/release-notes/rl-13.xml

@@ -0,0 +1,19 @@
+<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="ssec-relnotes-1.3">
+
+<title>Release 1.3 (January 4, 2013)</title>
+
+<para>This is primarily a bug fix release.  When this version is first
+run on Linux, it removes any immutable bits from the Nix store and
+increases the schema version of the Nix store.  (The previous release
+removed support for setting the immutable bit; this release clears any
+remaining immutable bits to make certain operations more
+efficient.)</para>
+
+<para>This release has contributions from Eelco Dolstra and Stuart
+Pernsteiner.</para>
+
+</chapter>

doc/manual/release-notes/rl-14.xml

@@ -0,0 +1,39 @@
+<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="ssec-relnotes-1.4">
+
+<title>Release 1.4 (February 26, 2013)</title>
+
+<para>This release fixes a security bug in multi-user operation.  It
+was possible for derivations to cause the mode of files outside of the
+Nix store to be changed to 444 (read-only but world-readable) by
+creating hard links to those files (<link
+xlink:href="https://github.com/NixOS/nix/commit/5526a282b5b44e9296e61e07d7d2626a79141ac4">details</link>).</para>
+
+<para>There are also the following improvements:</para>
+
+<itemizedlist>
+
+  <listitem><para>New built-in function:
+  <function>builtins.hashString</function>.</para></listitem>
+
+  <listitem><para>Build logs are now stored in
+  <filename>/nix/var/log/nix/drvs/<replaceable>XX</replaceable>/</filename>,
+  where <replaceable>XX</replaceable> is the first two characters of
+  the derivation.  This is useful on machines that keep a lot of build
+  logs (such as Hydra servers).</para></listitem>
+
+  <listitem><para>The function <function>corepkgs/fetchurl</function>
+  can now make the downloaded file executable.  This will allow
+  getting rid of all bootstrap binaries in the Nixpkgs source
+  tree.</para></listitem>
+
+  <listitem><para>Language change: The expression <literal>"${./path}
+  ..."</literal> now evaluates to a string instead of a
+  path.</para></listitem>
+
+</itemizedlist>
+
+</chapter>

doc/manual/release-notes/rl-15.xml

@@ -0,0 +1,12 @@
+<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="ssec-relnotes-1.5">
+
+<title>Release 1.5 (February 27, 2013)</title>
+
+<para>This is a brown paper bag release to fix a regression introduced
+by the hard link security fix in 1.4.</para>
+
+</chapter>

doc/manual/release-notes/rl-151.xml

@@ -0,0 +1,12 @@
+<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="ssec-relnotes-1.5.1">
+
+<title>Release 1.5.1 (February 28, 2013)</title>
+
+<para>The bug fix to the bug fix had a bug itself, of course.  But
+this time it will work for sure!</para>
+
+</chapter>

doc/manual/release-notes/rl-152.xml

@@ -0,0 +1,12 @@
+<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="ssec-relnotes-1.5.2">
+
+<title>Release 1.5.2 (May 13, 2013)</title>
+
+<para>This is primarily a bug fix release.  It has contributions from
+Eelco Dolstra, Lluís Batlle i Rossell and Shea Levy.</para>
+
+</chapter>

doc/manual/release-notes/rl-16.xml

@@ -0,0 +1,127 @@
+<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="ssec-relnotes-1.6.0">
+
+<title>Release 1.6 (September 10, 2013)</title>
+
+<para>In addition to the usual bug fixes, this release has several new
+features:</para>
+
+<itemizedlist>
+
+  <listitem>
+    <para>The command <command>nix-build --run-env</command> has been
+    renamed to <command>nix-shell</command>.</para>
+  </listitem>
+
+  <listitem>
+    <para><command>nix-shell</command> now sources
+    <filename>$stdenv/setup</filename> <emphasis>inside</emphasis> the
+    interactive shell, rather than in a parent shell.  This ensures
+    that shell functions defined by <literal>stdenv</literal> can be
+    used in the interactive shell.</para>
+  </listitem>
+
+  <listitem>
+    <para><command>nix-shell</command> has a new flag
+    <option>--pure</option> to clear the environment, so you get an
+    environment that more closely corresponds to the “real” Nix build.
+    </para>
+  </listitem>
+
+  <listitem>
+    <para><command>nix-shell</command> now sets the shell prompt
+    (<envar>PS1</envar>) to ensure that Nix shells are distinguishable
+    from your regular shells.</para>
+  </listitem>
+
+  <listitem>
+    <para><command>nix-env</command> no longer requires a
+    <literal>*</literal> argument to match all packages, so
+    <literal>nix-env -qa</literal> is equivalent to <literal>nix-env
+    -qa '*'</literal>.</para>
+  </listitem>
+
+  <listitem>
+    <para><command>nix-env -i</command> has a new flag
+    <option>--remove-all</option> (<option>-r</option>) to remove all
+    previous packages from the profile.  This makes it easier to do
+    declarative package management similar to NixOS’s
+    <option>environment.systemPackages</option>.  For instance, if you
+    have a specification <filename>my-packages.nix</filename> like this:
+
+<programlisting>
+with import &lt;nixpkgs> {};
+[ thunderbird
+  geeqie
+  ...
+]
+</programlisting>
+
+    then after any change to this file, you can run:
+
+<screen>
+$ nix-env -f my-packages.nix -ir
+</screen>
+
+    to update your profile to match the specification.</para>
+  </listitem>
+
+  <listitem>
+    <para>The ‘<literal>with</literal>’ language construct is now more
+    lazy.  It only evaluates its argument if a variable might actually
+    refer to an attribute in the argument.  For instance, this now
+    works:
+
+<programlisting>
+let
+  pkgs = with pkgs; { foo = "old"; bar = foo; } // overrides;
+  overrides = { foo = "new"; };
+in pkgs.bar
+</programlisting>
+
+    This evaluates to <literal>"new"</literal>, while previously it
+    gave an “infinite recursion” error.</para>
+  </listitem>
+
+  <listitem>
+    <para>Nix now has proper integer arithmetic operators. For
+    instance, you can write <literal>x + y</literal> instead of
+    <literal>builtins.add x y</literal>, or <literal>x &lt;
+    y</literal> instead of <literal>builtins.lessThan x y</literal>.
+    The comparison operators also work on strings.</para>
+  </listitem>
+
+  <listitem>
+    <para>On 64-bit systems, Nix integers are now 64 bits rather than
+    32 bits.</para>
+  </listitem>
+
+  <listitem>
+    <para>When using the Nix daemon, the <command>nix-daemon</command>
+    worker process now runs on the same CPU as the client, on systems
+    that support setting CPU affinity.  This gives a significant speedup
+    on some systems.</para>
+  </listitem>
+
+  <listitem>
+    <para>If a stack overflow occurs in the Nix evaluator, you now get
+    a proper error message (rather than “Segmentation fault”) on some
+    systems.</para>
+  </listitem>
+
+  <listitem>
+    <para>In addition to directories, you can now bind-mount regular
+    files in chroots through the (now misnamed) option
+    <option>build-chroot-dirs</option>.</para>
+  </listitem>
+
+</itemizedlist>
+
+<para>This release has contributions from Domen Kožar, Eelco Dolstra,
+Florian Friesdorf, Gergely Risko, Ivan Kozik, Ludovic Courtès and Shea
+Levy.</para>
+
+</chapter>

doc/manual/release-notes/rl-161.xml

@@ -0,0 +1,69 @@
+<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="ssec-relnotes-1.6.1">
+
+<title>Release 1.6.1 (October 28, 2013)</title>
+
+<para>This is primarily a bug fix release.  Changes of interest
+are:</para>
+
+<itemizedlist>
+
+  <listitem>
+    <para>Nix 1.6 accidentally changed the semantics of antiquoted
+    paths in strings, such as <literal>"${/foo}/bar"</literal>.  This
+    release reverts to the Nix 1.5.3 behaviour.</para>
+  </listitem>
+
+  <listitem>
+    <para>Previously, Nix optimised expressions such as
+    <literal>"${<replaceable>expr</replaceable>}"</literal> to
+    <replaceable>expr</replaceable>.  Thus it neither checked whether
+    <replaceable>expr</replaceable> could be coerced to a string, nor
+    applied such coercions.  This meant that
+    <literal>"${123}"</literal> evaluatued to <literal>123</literal>,
+    and <literal>"${./foo}"</literal> evaluated to
+    <literal>./foo</literal> (even though
+    <literal>"${./foo} "</literal> evaluates to
+    <literal>"/nix/store/<replaceable>hash</replaceable>-foo "</literal>).
+    Nix now checks the type of antiquoted expressions and
+    applies coercions.</para>
+  </listitem>
+
+  <listitem>
+    <para>Nix now shows the exact position of undefined variables.  In
+    particular, undefined variable errors in a <literal>with</literal>
+    previously didn't show <emphasis>any</emphasis> position
+    information, so this makes it a lot easier to fix such
+    errors.</para>
+  </listitem>
+
+  <listitem>
+    <para>Undefined variables are now treated consistently.
+    Previously, the <function>tryEval</function> function would catch
+    undefined variables inside a <literal>with</literal> but not
+    outside.  Now <function>tryEval</function> never catches undefined
+    variables.</para>
+  </listitem>
+
+  <listitem>
+    <para>Bash completion in <command>nix-shell</command> now works
+    correctly.</para>
+  </listitem>
+
+  <listitem>
+    <para>Stack traces are less verbose: they no longer show calls to
+    builtin functions and only show a single line for each derivation
+    on the call stack.</para>
+  </listitem>
+
+  <listitem>
+    <para>New built-in function: <function>builtins.typeOf</function>,
+    which returns the type of its argument as a string.</para>
+  </listitem>
+
+</itemizedlist>
+
+</chapter>