[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
161/376: Restructuring the Nix manual
|
From: |
Ludovic Courtès |
|
Subject: |
161/376: Restructuring the Nix manual |
|
Date: |
Wed, 28 Jan 2015 22:04:44 +0000 |
civodul pushed a commit to tag 1.8
in repository guix.
commit 8901acc97664aa8ebf687ee904428aa57a5192be
Author: Mikey Ariel <address@hidden>
Date: Wed Aug 27 18:41:09 2014 +0200
Restructuring the Nix manual
---
doc/manual/{ => bugs}/bugs.xml | 0
doc/manual/builds/build-farm.xml | 22 +
.../{build-farm.xml => builds/enabling-builds.xml} | 21 +-
doc/manual/command-ref/command-ref.xml | 20 +
doc/manual/{ => command-ref}/conf-file.xml | 0
doc/manual/{ => command-ref}/env-common.xml | 12 +-
doc/manual/command-ref/files.xml | 14 +
doc/manual/command-ref/main-commands.xml | 17 +
doc/manual/{ => command-ref}/nix-build.xml | 7 +-
doc/manual/{ => command-ref}/nix-channel.xml | 7 +-
.../{ => command-ref}/nix-collect-garbage.xml | 7 +-
doc/manual/{ => command-ref}/nix-copy-closure.xml | 0
doc/manual/{ => command-ref}/nix-daemon.xml | 7 +-
doc/manual/{ => command-ref}/nix-env.xml | 7 +-
doc/manual/{ => command-ref}/nix-hash.xml | 7 +-
.../{ => command-ref}/nix-install-package.xml | 7 +-
doc/manual/{ => command-ref}/nix-instantiate.xml | 7 +-
doc/manual/{ => command-ref}/nix-prefetch-url.xml | 7 +-
doc/manual/{ => command-ref}/nix-pull.xml | 7 +-
doc/manual/{ => command-ref}/nix-push.xml | 7 +-
doc/manual/{ => command-ref}/nix-shell.xml | 7 +-
doc/manual/{ => command-ref}/nix-store.xml | 7 +-
doc/manual/{ => command-ref}/opt-common-syn.xml | 0
doc/manual/{ => command-ref}/opt-common.xml | 6 +-
doc/manual/{ => command-ref}/opt-inst-syn.xml | 0
doc/manual/command-ref/utilities.xml | 23 +
doc/manual/expressions/advanced-attributes.xml | 243 ++
doc/manual/expressions/arguments-variables.xml | 121 +
doc/manual/expressions/build-script.xml | 119 +
doc/manual/expressions/builder-syntax.xml | 119 +
doc/manual/{ => expressions}/builtins.xml | 9 +-
doc/manual/expressions/custom-builder.xml | 26 +
doc/manual/expressions/debug-build.xml | 33 +
doc/manual/expressions/derivations.xml | 211 ++
doc/manual/expressions/expression-language.xml | 30 +
doc/manual/expressions/expression-syntax.xml | 148 ++
doc/manual/expressions/generic-builder.xml | 98 +
doc/manual/expressions/language-constructs.xml | 344 +++
doc/manual/expressions/language-operators.xml | 113 +
doc/manual/expressions/language-values.xml | 268 +++
doc/manual/expressions/simple-building-testing.xml | 86 +
doc/manual/expressions/simple-expression.xml | 47 +
doc/manual/expressions/standard-env.xml | 60 +
doc/manual/expressions/writing-nix-expressions.xml | 27 +
doc/manual/{ => glossary}/glossary.xml | 0
doc/manual/installation.xml | 447 ----
doc/manual/installation/building-source.xml | 57 +
doc/manual/installation/env-variables.xml | 24 +
doc/manual/installation/installation.xml | 34 +
doc/manual/installation/installing-binary.xml | 81 +
doc/manual/installation/installing-source.xml | 17 +
doc/manual/installation/multi-user.xml | 106 +
doc/manual/installation/nix-security.xml | 27 +
doc/manual/installation/obtaining-source.xml | 30 +
doc/manual/installation/prerequisites-source.xml | 73 +
doc/manual/installation/single-user.xml | 21 +
doc/manual/installation/supported-platforms.xml | 38 +
.../about-nix.xml} | 32 +-
doc/manual/introduction/introduction.xml | 16 +
doc/manual/introduction/nix-license.xml | 20 +
doc/manual/manual.xml | 75 +-
doc/manual/package-management.xml | 591 -----
doc/manual/packages/basic-package-mgmt.xml | 170 ++
doc/manual/packages/channels.xml | 57 +
doc/manual/packages/garbage-collection.xml | 70 +
doc/manual/packages/garbage-collector-roots.xml | 29 +
doc/manual/packages/one-click.xml | 37 +
doc/manual/packages/package-management.xml | 24 +
doc/manual/packages/profiles.xml | 159 ++
doc/manual/packages/sharing-packages.xml | 82 +
.../getting-started.xml} | 56 +-
doc/manual/quick-start/quick-start.xml | 17 +
doc/manual/release-notes.xml | 2521 --------------------
doc/manual/release-notes/release-notes.xml | 43 +
doc/manual/release-notes/rl-010.xml | 323 +++
doc/manual/release-notes/rl-0101.xml | 13 +
doc/manual/release-notes/rl-011.xml | 261 ++
doc/manual/release-notes/rl-012.xml | 175 ++
doc/manual/release-notes/rl-013.xml | 106 +
doc/manual/release-notes/rl-014.xml | 44 +
doc/manual/release-notes/rl-015.xml | 14 +
doc/manual/release-notes/rl-016.xml | 55 +
doc/manual/release-notes/rl-05.xml | 11 +
doc/manual/release-notes/rl-06.xml | 122 +
doc/manual/release-notes/rl-07.xml | 35 +
doc/manual/release-notes/rl-08.xml | 246 ++
doc/manual/release-notes/rl-081.xml | 21 +
doc/manual/release-notes/rl-09.xml | 98 +
doc/manual/release-notes/rl-091.xml | 13 +
doc/manual/release-notes/rl-092.xml | 28 +
doc/manual/release-notes/rl-10.xml | 119 +
doc/manual/release-notes/rl-11.xml | 100 +
doc/manual/release-notes/rl-12.xml | 157 ++
doc/manual/release-notes/rl-13.xml | 19 +
doc/manual/release-notes/rl-14.xml | 39 +
doc/manual/release-notes/rl-15.xml | 12 +
doc/manual/release-notes/rl-151.xml | 12 +
doc/manual/release-notes/rl-152.xml | 12 +
doc/manual/release-notes/rl-16.xml | 127 +
doc/manual/release-notes/rl-161.xml | 69 +
doc/manual/release-notes/rl-17.xml | 263 ++
doc/manual/release-notes/rl-18.xml | 11 +
doc/manual/troubleshooting.xml | 92 -
doc/manual/troubleshooting/collisions-nixenv.xml | 43 +
doc/manual/troubleshooting/links-nix-store.xml | 43 +
doc/manual/troubleshooting/troubleshooting.xml | 18 +
doc/manual/writing-nix-expressions.xml | 1901 ---------------
107 files changed, 6162 insertions(+), 5722 deletions(-)
diff --git a/doc/manual/bugs.xml b/doc/manual/bugs/bugs.xml
similarity index 100%
rename from doc/manual/bugs.xml
rename to doc/manual/bugs/bugs.xml
diff --git a/doc/manual/builds/build-farm.xml b/doc/manual/builds/build-farm.xml
new file mode 100644
index 0000000..e0e9f10
--- /dev/null
+++ b/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>
diff --git a/doc/manual/build-farm.xml b/doc/manual/builds/enabling-builds.xml
similarity index 87%
rename from doc/manual/build-farm.xml
rename to doc/manual/builds/enabling-builds.xml
index 2e0d86b..4b45812 100644
--- a/doc/manual/build-farm.xml
+++ b/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";
- xml:id='chap-distributed-builds'>
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ version="5.0"
+ xml:id="ch-enabling-builds">
-<title>Setting Up 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>
+<title>Enabling Distributed Builds</title>
<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>
\ No newline at end of file
diff --git a/doc/manual/command-ref/command-ref.xml
b/doc/manual/command-ref/command-ref.xml
new file mode 100644
index 0000000..cfad9b7
--- /dev/null
+++ b/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>
diff --git a/doc/manual/conf-file.xml b/doc/manual/command-ref/conf-file.xml
similarity index 100%
rename from doc/manual/conf-file.xml
rename to doc/manual/command-ref/conf-file.xml
diff --git a/doc/manual/env-common.xml b/doc/manual/command-ref/env-common.xml
similarity index 97%
rename from doc/manual/env-common.xml
rename to doc/manual/command-ref/env-common.xml
index 91a3e9e..c501d1c 100644
--- a/doc/manual/env-common.xml
+++ b/doc/manual/command-ref/env-common.xml
@@ -1,8 +1,10 @@
-<section xmlns="http://docbook.org/ns/docbook";
- xmlns:xlink="http://www.w3.org/1999/xlink";
- xml:id="sec-common-env">
+<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-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>
diff --git a/doc/manual/command-ref/files.xml b/doc/manual/command-ref/files.xml
new file mode 100644
index 0000000..7bbc96e
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/command-ref/main-commands.xml
b/doc/manual/command-ref/main-commands.xml
new file mode 100644
index 0000000..0f41692
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/nix-build.xml b/doc/manual/command-ref/nix-build.xml
similarity index 97%
rename from doc/manual/nix-build.xml
rename to doc/manual/command-ref/nix-build.xml
index 3832f5f..669a48f 100644
--- a/doc/manual/nix-build.xml
+++ b/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:xi="http://www.w3.org/2001/XInclude";
- xml:id="sec-nix-build">
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ version="5.0"
+ xml:id="sec-nix-build">
<refmeta>
<refentrytitle>nix-build</refentrytitle>
diff --git a/doc/manual/nix-channel.xml b/doc/manual/command-ref/nix-channel.xml
similarity index 96%
rename from doc/manual/nix-channel.xml
rename to doc/manual/command-ref/nix-channel.xml
index 2c4e115..e13394c 100644
--- a/doc/manual/nix-channel.xml
+++ b/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:xi="http://www.w3.org/2001/XInclude";
- xml:id="sec-nix-channel">
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ version="5.0"
+ xml:id="sec-nix-channel">
<refmeta>
<refentrytitle>nix-channel</refentrytitle>
diff --git a/doc/manual/nix-collect-garbage.xml
b/doc/manual/command-ref/nix-collect-garbage.xml
similarity index 93%
rename from doc/manual/nix-collect-garbage.xml
rename to doc/manual/command-ref/nix-collect-garbage.xml
index cf87074..f2009dc 100644
--- a/doc/manual/nix-collect-garbage.xml
+++ b/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:xi="http://www.w3.org/2001/XInclude";
- xml:id="sec-nix-collect-garbage">
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ version="5.0"
+ xml:id="sec-nix-collect-garbage">
<refmeta>
<refentrytitle>nix-collect-garbage</refentrytitle>
diff --git a/doc/manual/nix-copy-closure.xml
b/doc/manual/command-ref/nix-copy-closure.xml
similarity index 100%
rename from doc/manual/nix-copy-closure.xml
rename to doc/manual/command-ref/nix-copy-closure.xml
diff --git a/doc/manual/nix-daemon.xml b/doc/manual/command-ref/nix-daemon.xml
similarity index 83%
rename from doc/manual/nix-daemon.xml
rename to doc/manual/command-ref/nix-daemon.xml
index c68605f..4311664 100644
--- a/doc/manual/nix-daemon.xml
+++ b/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:xi="http://www.w3.org/2001/XInclude";
- xml:id="sec-nix-daemon">
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ version="5.0"
+ xml:id="sec-nix-daemon">
<refmeta>
<refentrytitle>nix-daemon</refentrytitle>
diff --git a/doc/manual/nix-env.xml b/doc/manual/command-ref/nix-env.xml
similarity index 99%
rename from doc/manual/nix-env.xml
rename to doc/manual/command-ref/nix-env.xml
index c440208..494edc3 100644
--- a/doc/manual/nix-env.xml
+++ b/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:xi="http://www.w3.org/2001/XInclude";
- xml:id="sec-nix-env">
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ version="5.0"
+ xml:id="sec-nix-env">
<refmeta>
<refentrytitle>nix-env</refentrytitle>
diff --git a/doc/manual/nix-hash.xml b/doc/manual/command-ref/nix-hash.xml
similarity index 97%
rename from doc/manual/nix-hash.xml
rename to doc/manual/command-ref/nix-hash.xml
index af4e361..897d92e 100644
--- a/doc/manual/nix-hash.xml
+++ b/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:xi="http://www.w3.org/2001/XInclude";
- xml:id="sec-nix-hash">
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ version="5.0"
+ xml:id="sec-nix-hash">
<refmeta>
<refentrytitle>nix-hash</refentrytitle>
diff --git a/doc/manual/nix-install-package.xml
b/doc/manual/command-ref/nix-install-package.xml
similarity index 97%
rename from doc/manual/nix-install-package.xml
rename to doc/manual/command-ref/nix-install-package.xml
index 54a6634..fa3b46e 100644
--- a/doc/manual/nix-install-package.xml
+++ b/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:xi="http://www.w3.org/2001/XInclude";
- xml:id="sec-nix-install-package">
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ version="5.0"
+ xml:id="sec-nix-install-package">
<refmeta>
<refentrytitle>nix-install-package</refentrytitle>
diff --git a/doc/manual/nix-instantiate.xml
b/doc/manual/command-ref/nix-instantiate.xml
similarity index 98%
rename from doc/manual/nix-instantiate.xml
rename to doc/manual/command-ref/nix-instantiate.xml
index 936f154..a4e45cf 100644
--- a/doc/manual/nix-instantiate.xml
+++ b/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:xi="http://www.w3.org/2001/XInclude";
- xml:id="sec-nix-instantiate">
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ version="5.0"
+ xml:id="sec-nix-instantiate">
<refmeta>
<refentrytitle>nix-instantiate</refentrytitle>
diff --git a/doc/manual/nix-prefetch-url.xml
b/doc/manual/command-ref/nix-prefetch-url.xml
similarity index 95%
rename from doc/manual/nix-prefetch-url.xml
rename to doc/manual/command-ref/nix-prefetch-url.xml
index c416e67..885c958 100644
--- a/doc/manual/nix-prefetch-url.xml
+++ b/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:xi="http://www.w3.org/2001/XInclude";
- xml:id="sec-nix-prefetch-url">
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ version="5.0"
+ xml:id="sec-nix-prefetch-url">
<refmeta>
<refentrytitle>nix-prefetch-url</refentrytitle>
diff --git a/doc/manual/nix-pull.xml b/doc/manual/command-ref/nix-pull.xml
similarity index 90%
rename from doc/manual/nix-pull.xml
rename to doc/manual/command-ref/nix-pull.xml
index 8e4a505..43d5a6c 100644
--- a/doc/manual/nix-pull.xml
+++ b/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:xi="http://www.w3.org/2001/XInclude";
- xml:id="sec-nix-pull">
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ version="5.0"
+ xml:id="sec-nix-pull">
<refmeta>
<refentrytitle>nix-pull</refentrytitle>
diff --git a/doc/manual/nix-push.xml b/doc/manual/command-ref/nix-push.xml
similarity index 98%
rename from doc/manual/nix-push.xml
rename to doc/manual/command-ref/nix-push.xml
index e789bbf..9c6cdfa 100644
--- a/doc/manual/nix-push.xml
+++ b/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:xi="http://www.w3.org/2001/XInclude";
- xml:id="sec-nix-push">
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ version="5.0"
+ xml:id="sec-nix-push">
<refmeta>
<refentrytitle>nix-push</refentrytitle>
diff --git a/doc/manual/nix-shell.xml b/doc/manual/command-ref/nix-shell.xml
similarity index 97%
rename from doc/manual/nix-shell.xml
rename to doc/manual/command-ref/nix-shell.xml
index d5f70a9..1cb2ebf 100644
--- a/doc/manual/nix-shell.xml
+++ b/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:xi="http://www.w3.org/2001/XInclude";
- xml:id="sec-nix-shell">
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ version="5.0"
+ xml:id="sec-nix-shell">
<refmeta>
<refentrytitle>nix-shell</refentrytitle>
diff --git a/doc/manual/nix-store.xml b/doc/manual/command-ref/nix-store.xml
similarity index 99%
rename from doc/manual/nix-store.xml
rename to doc/manual/command-ref/nix-store.xml
index c9a912f..ae0f683 100644
--- a/doc/manual/nix-store.xml
+++ b/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:xi="http://www.w3.org/2001/XInclude";
- xml:id="sec-nix-store">
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ version="5.0"
+ xml:id="sec-nix-store">
<refmeta>
<refentrytitle>nix-store</refentrytitle>
diff --git a/doc/manual/opt-common-syn.xml
b/doc/manual/command-ref/opt-common-syn.xml
similarity index 100%
rename from doc/manual/opt-common-syn.xml
rename to doc/manual/command-ref/opt-common-syn.xml
diff --git a/doc/manual/opt-common.xml b/doc/manual/command-ref/opt-common.xml
similarity index 99%
rename from doc/manual/opt-common.xml
rename to doc/manual/command-ref/opt-common.xml
index f8584f4..3486c7e 100644
--- a/doc/manual/opt-common.xml
+++ b/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>
diff --git a/doc/manual/opt-inst-syn.xml
b/doc/manual/command-ref/opt-inst-syn.xml
similarity index 100%
rename from doc/manual/opt-inst-syn.xml
rename to doc/manual/command-ref/opt-inst-syn.xml
diff --git a/doc/manual/command-ref/utilities.xml
b/doc/manual/command-ref/utilities.xml
new file mode 100644
index 0000000..190962c
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/expressions/advanced-attributes.xml
b/doc/manual/expressions/advanced-attributes.xml
new file mode 100644
index 0000000..40a5a80
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/expressions/arguments-variables.xml
b/doc/manual/expressions/arguments-variables.xml
new file mode 100644
index 0000000..bf60cb7
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/expressions/build-script.xml
b/doc/manual/expressions/build-script.xml
new file mode 100644
index 0000000..7bad8f8
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/expressions/builder-syntax.xml
b/doc/manual/expressions/builder-syntax.xml
new file mode 100644
index 0000000..e51bade
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/builtins.xml b/doc/manual/expressions/builtins.xml
similarity index 99%
rename from doc/manual/builtins.xml
rename to doc/manual/expressions/builtins.xml
index b289c6f..4edb3a1 100644
--- a/doc/manual/builtins.xml
+++ b/doc/manual/expressions/builtins.xml
@@ -1,9 +1,10 @@
<section xmlns="http://docbook.org/ns/docbook";
- xmlns:xlink="http://www.w3.org/1999/xlink";
- xml:id='ssec-builtins'>
-
-<title>Built-in functions</title>
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ version="5.0"
+ 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
diff --git a/doc/manual/expressions/custom-builder.xml
b/doc/manual/expressions/custom-builder.xml
new file mode 100644
index 0000000..c26deac
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/expressions/debug-build.xml
b/doc/manual/expressions/debug-build.xml
new file mode 100644
index 0000000..508cb2c
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/expressions/derivations.xml
b/doc/manual/expressions/derivations.xml
new file mode 100644
index 0000000..b57c33f
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/expressions/expression-language.xml
b/doc/manual/expressions/expression-language.xml
new file mode 100644
index 0000000..240ef80
--- /dev/null
+++ b/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>
diff --git a/doc/manual/expressions/expression-syntax.xml
b/doc/manual/expressions/expression-syntax.xml
new file mode 100644
index 0000000..6f1a3a1
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/expressions/generic-builder.xml
b/doc/manual/expressions/generic-builder.xml
new file mode 100644
index 0000000..f8567a0
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/expressions/language-constructs.xml
b/doc/manual/expressions/language-constructs.xml
new file mode 100644
index 0000000..ddb3498
--- /dev/null
+++ b/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>
address@hidden 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 && httpd.expat == expat; <co
xml:id='ex-subversion-nix-co-2' />
+assert sslSupport -> openssl != null && (httpServer -> httpd.openssl
== openssl); <co xml:id='ex-subversion-nix-co-3' />
+assert pythonBindings -> swig != null && swig.pythonSupport;
+assert javaSwigBindings -> swig != null && 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>
\ No newline at end of file
diff --git a/doc/manual/expressions/language-operators.xml
b/doc/manual/expressions/language-operators.xml
new file mode 100644
index 0000000..a3323ce
--- /dev/null
+++ b/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>&&</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>
\ No newline at end of file
diff --git a/doc/manual/expressions/language-values.xml
b/doc/manual/expressions/language-values.xml
new file mode 100644
index 0000000..519657f
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/expressions/simple-building-testing.xml
b/doc/manual/expressions/simple-building-testing.xml
new file mode 100644
index 0000000..cc90409
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/expressions/simple-expression.xml
b/doc/manual/expressions/simple-expression.xml
new file mode 100644
index 0000000..a8eb96f
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/expressions/standard-env.xml
b/doc/manual/expressions/standard-env.xml
new file mode 100644
index 0000000..2571f43
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/expressions/writing-nix-expressions.xml
b/doc/manual/expressions/writing-nix-expressions.xml
new file mode 100644
index 0000000..6d64f24
--- /dev/null
+++ b/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>
diff --git a/doc/manual/glossary.xml b/doc/manual/glossary/glossary.xml
similarity index 100%
rename from doc/manual/glossary.xml
rename to doc/manual/glossary/glossary.xml
diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml
deleted file mode 100644
index 423bef5..0000000
--- a/doc/manual/installation.xml
+++ /dev/null
@@ -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 <(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>
diff --git a/doc/manual/installation/building-source.xml
b/doc/manual/installation/building-source.xml
new file mode 100644
index 0000000..2202ec7
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/installation/env-variables.xml
b/doc/manual/installation/env-variables.xml
new file mode 100644
index 0000000..fc39cdd
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/installation/installation.xml
b/doc/manual/installation/installation.xml
new file mode 100644
index 0000000..8789593
--- /dev/null
+++ b/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>
diff --git a/doc/manual/installation/installing-binary.xml
b/doc/manual/installation/installing-binary.xml
new file mode 100644
index 0000000..a5f9ac8
--- /dev/null
+++ b/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 <(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>
\ No newline at end of file
diff --git a/doc/manual/installation/installing-source.xml
b/doc/manual/installation/installing-source.xml
new file mode 100644
index 0000000..77beff1
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/installation/multi-user.xml
b/doc/manual/installation/multi-user.xml
new file mode 100644
index 0000000..2eb4c25
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/installation/nix-security.xml
b/doc/manual/installation/nix-security.xml
new file mode 100644
index 0000000..d888ff1
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/installation/obtaining-source.xml
b/doc/manual/installation/obtaining-source.xml
new file mode 100644
index 0000000..968822c
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/installation/prerequisites-source.xml
b/doc/manual/installation/prerequisites-source.xml
new file mode 100644
index 0000000..47adc9a
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/installation/single-user.xml
b/doc/manual/installation/single-user.xml
new file mode 100644
index 0000000..09cdaa5
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/installation/supported-platforms.xml
b/doc/manual/installation/supported-platforms.xml
new file mode 100644
index 0000000..a31c643
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/introduction.xml b/doc/manual/introduction/about-nix.xml
similarity index 91%
rename from doc/manual/introduction.xml
rename to doc/manual/introduction/about-nix.xml
index e0300dc..38dd7e6 100644
--- a/doc/manual/introduction.xml
+++ b/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";
- xml:id="chap-introduction">
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ xmlns:xi="http://www.w3.org/2001/XInclude";
+ version="5.0"
+ xml:id="ch-about-nix">
-<title>Introduction</title>
-
-
-<section><title>About Nix</title>
+<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>
-
-
-<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>
+</chapter>
\ No newline at end of file
diff --git a/doc/manual/introduction/introduction.xml
b/doc/manual/introduction/introduction.xml
new file mode 100644
index 0000000..f7f0b01
--- /dev/null
+++ b/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>
diff --git a/doc/manual/introduction/nix-license.xml
b/doc/manual/introduction/nix-license.xml
new file mode 100644
index 0000000..af9cef7
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index 6593d13..8fae04f 100644
--- a/doc/manual/manual.xml
+++ b/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>
-
- <xi:include href="introduction.xml" />
- <xi:include href="quick-start.xml" />
- <xi:include href="installation.xml" />
- <xi:include href="package-management.xml" />
- <xi:include href="writing-nix-expressions.xml" />
- <xi:include href="build-farm.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" />
+<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/introduction.xml" />
+ <xi:include href="quicks-start/quick-start.xml" />
+ <xi:include href="installation/installation.xml" />
+ <xi:include href="packages/package-management.xml" />
+ <xi:include href="expressions/writing-nix-expressions.xml" />
+ <xi:include href="builds/build-farm.xml" />
+ <xi:include href="command-ref/command-ref.xml" />
+ <xi:include href="troubleshooting/troubleshooting.xml" />
<!-- <xi:include href="bugs.xml" /> -->
- <xi:include href="glossary.xml" />
+ <xi:include href="glossary/glossary.xml" />
<xi:include href="hacking.xml" />
-
- <appendix>
+ <xi:include href="release-notes/release-notes.xml" />
+
+<!--
+<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>
diff --git a/doc/manual/package-management.xml
b/doc/manual/package-management.xml
deleted file mode 100644
index e1d24b1..0000000
--- a/doc/manual/package-management.xml
+++ /dev/null
@@ -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 address@hidden $(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 < 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 address@hidden "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 address@hidden:/ /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>
diff --git a/doc/manual/packages/basic-package-mgmt.xml
b/doc/manual/packages/basic-package-mgmt.xml
new file mode 100644
index 0000000..69c955c
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/packages/channels.xml b/doc/manual/packages/channels.xml
new file mode 100644
index 0000000..094e11f
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/packages/garbage-collection.xml
b/doc/manual/packages/garbage-collection.xml
new file mode 100644
index 0000000..ae28c48
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/packages/garbage-collector-roots.xml
b/doc/manual/packages/garbage-collector-roots.xml
new file mode 100644
index 0000000..8338e53
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/packages/one-click.xml
b/doc/manual/packages/one-click.xml
new file mode 100644
index 0000000..cef9a2b
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/packages/package-management.xml
b/doc/manual/packages/package-management.xml
new file mode 100644
index 0000000..5cc5c38
--- /dev/null
+++ b/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>
diff --git a/doc/manual/packages/profiles.xml b/doc/manual/packages/profiles.xml
new file mode 100644
index 0000000..ad5e92a
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/packages/sharing-packages.xml
b/doc/manual/packages/sharing-packages.xml
new file mode 100644
index 0000000..573b7c1
--- /dev/null
+++ b/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 address@hidden $(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 < 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 address@hidden "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 address@hidden:/ /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>
\ No newline at end of file
diff --git a/doc/manual/quick-start.xml
b/doc/manual/quick-start/getting-started.xml
similarity index 63%
rename from doc/manual/quick-start.xml
rename to doc/manual/quick-start/getting-started.xml
index 1707990..a6b1f47 100644
--- a/doc/manual/quick-start.xml
+++ b/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";
- xml:id="chap-quick-start">
+ xmlns:xlink="http://www.w3.org/1999/xlink";
+ 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
-documentation. For more in-depth information you are kindly referred
-to the following chapters.</para>
-
-<orderedlist>
-
-<listitem><para>Install Nix by running the following:
+<step><para>Install Nix by running the following:
<screen>
$ bash <(curl https://nixos.org/nix/install)
@@ -20,9 +18,9 @@ $ bash <(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>
\ No newline at end of file
diff --git a/doc/manual/quick-start/quick-start.xml
b/doc/manual/quick-start/quick-start.xml
new file mode 100644
index 0000000..b4757cb
--- /dev/null
+++ b/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>
diff --git a/doc/manual/release-notes.xml b/doc/manual/release-notes.xml
deleted file mode 100644
index 426078b..0000000
--- a/doc/manual/release-notes.xml
+++ /dev/null
@@ -1,2521 +0,0 @@
-<article xmlns="http://docbook.org/ns/docbook";
- xmlns:xlink="http://www.w3.org/1999/xlink";
- xml:id="sec-relnotes">
-
-<title>Nix Release Notes</title>
-
-
-<!--==================================================================-->
-
-<section xml:id="ssec-relnotes-1.8"><title>Release 1.8 (TBA)</title>
-
-<para>TODO</para>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section xml:id="ssec-relnotes-1.7"><title>Release 1.7 (April 11, 2014)</title>
-
-<para>In addition to the usual bug fixes, this release has the
-following new features:</para>
-
-<itemizedlist>
-
- <listitem>
- <para>Antiquotation is now allowed inside of quoted attribute
- names (e.g. <literal>set."${foo}"</literal>). In the case where
- the attribute name is just a single antiquotation, the quotes can
- be dropped (e.g. the above example can be written
- <literal>set.${foo}</literal>). If an attribute name inside of a
- set declaration evaluates to <literal>null</literal> (e.g.
- <literal>{ ${null} = false; }</literal>), then that attribute is
- not added to the set.</para>
- </listitem>
-
- <listitem>
- <para>Experimental support for cryptographically signed binary
- caches. See <link
-
xlink:href="https://github.com/NixOS/nix/commit/0fdf4da0e979f992db75cc17376e455ddc5a96d8";>the
- commit for details</link>.</para>
- </listitem>
-
- <listitem>
- <para>An experimental new substituter,
- <command>download-via-ssh</command>, that fetches binaries from
- remote machines via SSH. Specifying the flags <literal>--option
- use-ssh-substituter true --option ssh-substituter-hosts
- <replaceable>address@hidden</replaceable></literal> will cause Nix
- to download binaries from the specified machine, if it has
- them.</para>
- </listitem>
-
- <listitem>
- <para><command>nix-store -r</command> and
- <command>nix-build</command> have a new flag,
- <option>--check</option>, that builds a previously built
- derivation again, and prints an error message if the output is not
- exactly the same. This helps to verify whether a derivation is
- truly deterministic. For example:
-
-<screen>
-$ nix-build '<nixpkgs>' -A patchelf
-<replaceable>…</replaceable>
-$ nix-build '<nixpkgs>' -A patchelf --check
-<replaceable>…</replaceable>
-error: derivation `/nix/store/1ipvxs…-patchelf-0.6' may not be deterministic:
- hash mismatch in output `/nix/store/4pc1dm…-patchelf-0.6.drv'
-</screen>
-
- </para>
-
- </listitem>
-
- <listitem>
- <para>The <command>nix-instantiate</command> flags
- <option>--eval-only</option> and <option>--parse-only</option>
- have been renamed to <option>--eval</option> and
- <option>--parse</option>, respectively.</para>
- </listitem>
-
- <listitem>
- <para><command>nix-instantiate</command>,
- <command>nix-build</command> and <command>nix-shell</command> now
- have a flag <option>--expr</option> (or <option>-E</option>) that
- allows you to specify the expression to be evaluated as a command
- line argument. For instance, <literal>nix-instantiate --eval -E
- '1 + 2'</literal> will print <literal>3</literal>.</para>
- </listitem>
-
- <listitem>
- <para><command>nix-shell</command> improvements:</para>
-
- <itemizedlist>
-
- <listitem>
- <para>It has a new flag, <option>--packages</option> (or
- <option>-p</option>), that sets up a build environment
- containing the specified packages from Nixpkgs. For example,
- the command
-
-<screen>
-$ nix-shell -p sqlite xorg.libX11 hello
-</screen>
-
- will start a shell in which the given packages are
- present.</para>
- </listitem>
-
- <listitem>
- <para>It now uses <filename>shell.nix</filename> as the
- default expression, falling back to
- <filename>default.nix</filename> if the former doesn’t
- exist. This makes it convenient to have a
- <filename>shell.nix</filename> in your project to set up a
- nice development environment.</para>
- </listitem>
-
- <listitem>
- <para>It evaluates the derivation attribute
- <varname>shellHook</varname>, if set. Since
- <literal>stdenv</literal> does not normally execute this hook,
- it allows you to do <command>nix-shell</command>-specific
- setup.</para>
- </listitem>
-
- <listitem>
- <para>It preserves the user’s timezone setting.</para>
- </listitem>
-
- </itemizedlist>
-
- </listitem>
-
- <listitem>
- <para>In chroots, Nix now sets up a <filename>/dev</filename>
- containing only a minimal set of devices (such as
- <filename>/dev/null</filename>). Note that it only does this if
- you <emphasis>don’t</emphasis> have <filename>/dev</filename>
- listed in your <option>build-chroot-dirs</option> setting;
- otherwise, it will bind-mount the <literal>/dev</literal> from
- outside the chroot.</para>
-
- <para>Similarly, if you don’t have <filename>/dev/pts</filename> listed
- in <option>build-chroot-dirs</option>, Nix will mount a private
- <literal>devpts</literal> filesystem on the chroot’s
- <filename>/dev/pts</filename>.</para>
-
- </listitem>
-
- <listitem>
- <para>New built-in function: <function>builtins.toJSON</function>,
- which returns a JSON representation of a value.</para>
- </listitem>
-
- <listitem>
- <para><command>nix-env -q</command> has a new flag
- <option>--json</option> to print a JSON representation of the
- installed or available packages.</para>
- </listitem>
-
- <listitem>
- <para><command>nix-env</command> now supports meta attributes with
- more complex values, such as attribute sets.</para>
- </listitem>
-
- <listitem>
- <para>The <option>-A</option> flag now allows attribute names with
- dots in them, e.g.
-
-<screen>
-$ nix-instantiate --eval '<nixos>' -A
'config.systemd.units."nscd.service".text'
-</screen>
-
- </para>
- </listitem>
-
- <listitem>
- <para>The <option>--max-freed</option> option to
- <command>nix-store --gc</command> now accepts a unit
- specifier. For example, <literal>nix-store --gc --max-freed
- 1G</literal> will free up to 1 gigabyte of disk space.</para>
- </listitem>
-
- <listitem>
- <para><command>nix-collect-garbage</command> has a new flag
- <option>--delete-older-than</option>
- <replaceable>N</replaceable><literal>d</literal>, which deletes
- all user environment generations older than
- <replaceable>N</replaceable> days. Likewise, <command>nix-env
- --delete-generations</command> accepts a
- <replaceable>N</replaceable><literal>d</literal> age limit.</para>
- </listitem>
-
- <listitem>
- <para>Nix now heuristically detects whether a build failure was
- due to a disk-full condition. In that case, the build is not
- flagged as “permanently failedâ€. This is mostly useful for Hydra,
- which needs to distinguish between permanent and transient build
- failures.</para>
- </listitem>
-
- <listitem>
- <para>There is a new symbol <literal>__curPos</literal> that
- expands to an attribute set containing its file name and line and
- column numbers, e.g. <literal>{ file = "foo.nix"; line = 10;
- column = 5; }</literal>. There also is a new builtin function,
- <varname>unsafeGetAttrPos</varname>, that returns the position of
- an attribute. This is used by Nixpkgs to provide location
- information in error messages, e.g.
-
-<screen>
-$ nix-build '<nixpkgs>' -A libreoffice --argstr system x86_64-darwin
-error: the package ‘libreoffice-4.0.5.2’ in
‘.../applications/office/libreoffice/default.nix:263’
- is not supported on ‘x86_64-darwin’
-</screen>
-
- </para>
- </listitem>
-
- <listitem>
- <para>The garbage collector is now more concurrent with other Nix
- processes because it releases certain locks earlier.</para>
- </listitem>
-
- <listitem>
- <para>The binary tarball installer has been improved. You can now
- install Nix by running:
-
-<screen>
-$ bash <(curl https://nixos.org/nix/install)
-</screen>
-
- </para>
- </listitem>
-
- <listitem>
- <para>More evaluation errors include position information. For
- instance, selecting a missing attribute will print something like
-
-<screen>
-error: attribute `nixUnstabl' missing, at
/etc/nixos/configurations/misc/eelco/mandark.nix:216:15
-</screen>
-
- </para>
- </listitem>
-
- <listitem>
- <para>The command <command>nix-setuid-helper</command> is
- gone.</para>
- </listitem>
-
- <listitem>
- <para>Nix no longer uses Automake, but instead has a
- non-recursive, GNU Make-based build system.</para>
- </listitem>
-
- <listitem>
- <para>All installed libraries now have the prefix
- <literal>libnix</literal>. In particular, this gets rid of
- <literal>libutil</literal>, which could clash with libraries with
- the same name from other packages.</para>
- </listitem>
-
- <listitem>
- <para>Nix now requires a compiler that supports C++11.</para>
- </listitem>
-
-</itemizedlist>
-
-<para>This release has contributions from Danny Wilson, Domen Kožar,
-Eelco Dolstra, Ian-Woo Kim, Ludovic Courtès, Maxim Ivanov, Petr
-Rockai, Ricardo M. Correia and Shea Levy.</para>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section 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>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section 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 <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 <
- 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>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section xml:id="ssec-relnotes-1.5.3"><title>Release 1.5.3 (June 17,
2013)</title>
-
-<para>This is primarily a bug fix release. The following changes are
-noteworthy:</para>
-
-<itemizedlist>
-
- <listitem>
- <para>Yet another security bug involving hard links to files
- outside the store was fixed. This bug only affected multi-user
- installations that do not have hard link restrictions
- enabled. (NixOS is thus not vulnerable.)</para>
- </listitem>
-
- <listitem>
- <para>The default binary cache URL has changed from
- <uri>http://nixos.org/binary-cache</uri> to
- <uri>http://cache.nixos.org</uri>. The latter is hosted on Amazon
- CloudFront (courtesy of <link
- xlink:href="http://www.logicblox.com/";>LogicBlox</link>) and
- should provide better performance for users in both Europe and
- North America.</para>
- </listitem>
-
- <listitem>
- <para>The binary cache substituter now prints a warning message if
- fetching information from the cache takes more than five seconds.
- Thus network or server problems no longer make Nix appear to just
- hang.</para>
- </listitem>
-
- <listitem>
- <para>Stack traces now show function names, e.g.
-<screen>
-while evaluating `concatMapStrings' at
`<replaceable>...</replaceable>/nixpkgs/pkgs/lib/strings.nix:18:25':
-</screen>
- Also, if a function is called with an unexpected argument, Nix
- now shows the name of the argument.
- </para>
- </listitem>
-
-</itemizedlist>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section 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>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section 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>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section 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>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section 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>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section 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>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section 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>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section 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 <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>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section 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><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>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section 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/address@hidden/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>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section 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>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section 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>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section 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>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section 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 <
- 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>
-
-</section>
-
-
-<!--==================================================================-->
-
-<section 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>
-
-</section>
-
-
-
-<!--==================================================================-->
-
-<section><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>
-
-</section>
-
-
-
-<!--==================================================================-->
-
-<section><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>
-
-</section>
-
-
-
-<!--==================================================================-->
-
-<section><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), >&=9) failed: Bad
- file descriptor at /nix/bin/nix-pull line 77</literal> (issue
- <literal>NIX-14</literal>).</para></listitem>
-
-</itemizedlist>
-
-</para>
-
-</section>
-
-
-
-<!--==================================================================-->
-
-<section><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>
-
-</section>
-
-
-
-<!--==================================================================-->
-
-<section><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];
-};
- 
-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>
-
-</section>
-
-
-
-<!--==================================================================-->
-
-<section><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>
-
-</section>
-
-
-
-<!--==================================================================-->
-
-<section><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 <= 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>
-
-</section>
-
-
-
-<!--==================================================================-->
-
-<section><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>
-
-</section>
-
-
-
-<!--==================================================================-->
-
-<section><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>
-
-</section>
-
-
-
-<!--==================================================================-->
-
-<section><title>Release 0.5 and earlier</title>
-
-<para>Please refer to the Subversion commit log messages.</para>
-
-</section>
-
-
-
-</article>
diff --git a/doc/manual/release-notes/release-notes.xml
b/doc/manual/release-notes/release-notes.xml
new file mode 100644
index 0000000..c9bb2e1
--- /dev/null
+++ b/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>
diff --git a/doc/manual/release-notes/rl-010.xml
b/doc/manual/release-notes/rl-010.xml
new file mode 100644
index 0000000..fb55bd2
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-0101.xml
b/doc/manual/release-notes/rl-0101.xml
new file mode 100644
index 0000000..884b1b8
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-011.xml
b/doc/manual/release-notes/rl-011.xml
new file mode 100644
index 0000000..40f83bb
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-012.xml
b/doc/manual/release-notes/rl-012.xml
new file mode 100644
index 0000000..173ed79
--- /dev/null
+++ b/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 <
+ 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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-013.xml
b/doc/manual/release-notes/rl-013.xml
new file mode 100644
index 0000000..c116e42
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-014.xml
b/doc/manual/release-notes/rl-014.xml
new file mode 100644
index 0000000..456be8b
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-015.xml
b/doc/manual/release-notes/rl-015.xml
new file mode 100644
index 0000000..ae6e12a
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-016.xml
b/doc/manual/release-notes/rl-016.xml
new file mode 100644
index 0000000..49ac2ce
--- /dev/null
+++ b/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/address@hidden/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-05.xml
b/doc/manual/release-notes/rl-05.xml
new file mode 100644
index 0000000..f7b40c1
--- /dev/null
+++ b/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>
diff --git a/doc/manual/release-notes/rl-06.xml
b/doc/manual/release-notes/rl-06.xml
new file mode 100644
index 0000000..a4d78ed
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-07.xml
b/doc/manual/release-notes/rl-07.xml
new file mode 100644
index 0000000..d6d61c1
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-08.xml
b/doc/manual/release-notes/rl-08.xml
new file mode 100644
index 0000000..5f1e940
--- /dev/null
+++ b/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 <= 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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-081.xml
b/doc/manual/release-notes/rl-081.xml
new file mode 100644
index 0000000..986e4cb
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-09.xml
b/doc/manual/release-notes/rl-09.xml
new file mode 100644
index 0000000..be0e5fa
--- /dev/null
+++ b/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];
+};
+ 
+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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-091.xml
b/doc/manual/release-notes/rl-091.xml
new file mode 100644
index 0000000..f90206d
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-092.xml
b/doc/manual/release-notes/rl-092.xml
new file mode 100644
index 0000000..ea0412d
--- /dev/null
+++ b/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), >&=9) failed: Bad
+ file descriptor at /nix/bin/nix-pull line 77</literal> (issue
+ <literal>NIX-14</literal>).</para></listitem>
+
+</itemizedlist>
+
+</para>
+
+</chapter>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-10.xml
b/doc/manual/release-notes/rl-10.xml
new file mode 100644
index 0000000..21721b6
--- /dev/null
+++ b/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><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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-11.xml
b/doc/manual/release-notes/rl-11.xml
new file mode 100644
index 0000000..db9939b
--- /dev/null
+++ b/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 <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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-12.xml
b/doc/manual/release-notes/rl-12.xml
new file mode 100644
index 0000000..72d164f
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-13.xml
b/doc/manual/release-notes/rl-13.xml
new file mode 100644
index 0000000..8e52648
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-14.xml
b/doc/manual/release-notes/rl-14.xml
new file mode 100644
index 0000000..d1a8cd6
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-15.xml
b/doc/manual/release-notes/rl-15.xml
new file mode 100644
index 0000000..7319b52
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-151.xml
b/doc/manual/release-notes/rl-151.xml
new file mode 100644
index 0000000..625d0af
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-152.xml
b/doc/manual/release-notes/rl-152.xml
new file mode 100644
index 0000000..1446992
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-16.xml
b/doc/manual/release-notes/rl-16.xml
new file mode 100644
index 0000000..c0285b6
--- /dev/null
+++ b/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 <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 <
+ 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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-161.xml
b/doc/manual/release-notes/rl-161.xml
new file mode 100644
index 0000000..f6d3a6b
--- /dev/null
+++ b/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>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-17.xml
b/doc/manual/release-notes/rl-17.xml
new file mode 100644
index 0000000..7257bc8
--- /dev/null
+++ b/doc/manual/release-notes/rl-17.xml
@@ -0,0 +1,263 @@
+<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.7">
+
+<title>Release 1.7 (April 11, 2014)</title>
+
+<para>In addition to the usual bug fixes, this release has the
+following new features:</para>
+
+<itemizedlist>
+
+ <listitem>
+ <para>Antiquotation is now allowed inside of quoted attribute
+ names (e.g. <literal>set."${foo}"</literal>). In the case where
+ the attribute name is just a single antiquotation, the quotes can
+ be dropped (e.g. the above example can be written
+ <literal>set.${foo}</literal>). If an attribute name inside of a
+ set declaration evaluates to <literal>null</literal> (e.g.
+ <literal>{ ${null} = false; }</literal>), then that attribute is
+ not added to the set.</para>
+ </listitem>
+
+ <listitem>
+ <para>Experimental support for cryptographically signed binary
+ caches. See <link
+
xlink:href="https://github.com/NixOS/nix/commit/0fdf4da0e979f992db75cc17376e455ddc5a96d8";>the
+ commit for details</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>An experimental new substituter,
+ <command>download-via-ssh</command>, that fetches binaries from
+ remote machines via SSH. Specifying the flags <literal>--option
+ use-ssh-substituter true --option ssh-substituter-hosts
+ <replaceable>address@hidden</replaceable></literal> will cause Nix
+ to download binaries from the specified machine, if it has
+ them.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>nix-store -r</command> and
+ <command>nix-build</command> have a new flag,
+ <option>--check</option>, that builds a previously built
+ derivation again, and prints an error message if the output is not
+ exactly the same. This helps to verify whether a derivation is
+ truly deterministic. For example:
+
+<screen>
+$ nix-build '<nixpkgs>' -A patchelf
+<replaceable>…</replaceable>
+$ nix-build '<nixpkgs>' -A patchelf --check
+<replaceable>…</replaceable>
+error: derivation `/nix/store/1ipvxs…-patchelf-0.6' may not be deterministic:
+ hash mismatch in output `/nix/store/4pc1dm…-patchelf-0.6.drv'
+</screen>
+
+ </para>
+
+ </listitem>
+
+ <listitem>
+ <para>The <command>nix-instantiate</command> flags
+ <option>--eval-only</option> and <option>--parse-only</option>
+ have been renamed to <option>--eval</option> and
+ <option>--parse</option>, respectively.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>nix-instantiate</command>,
+ <command>nix-build</command> and <command>nix-shell</command> now
+ have a flag <option>--expr</option> (or <option>-E</option>) that
+ allows you to specify the expression to be evaluated as a command
+ line argument. For instance, <literal>nix-instantiate --eval -E
+ '1 + 2'</literal> will print <literal>3</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>nix-shell</command> improvements:</para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>It has a new flag, <option>--packages</option> (or
+ <option>-p</option>), that sets up a build environment
+ containing the specified packages from Nixpkgs. For example,
+ the command
+
+<screen>
+$ nix-shell -p sqlite xorg.libX11 hello
+</screen>
+
+ will start a shell in which the given packages are
+ present.</para>
+ </listitem>
+
+ <listitem>
+ <para>It now uses <filename>shell.nix</filename> as the
+ default expression, falling back to
+ <filename>default.nix</filename> if the former doesn’t
+ exist. This makes it convenient to have a
+ <filename>shell.nix</filename> in your project to set up a
+ nice development environment.</para>
+ </listitem>
+
+ <listitem>
+ <para>It evaluates the derivation attribute
+ <varname>shellHook</varname>, if set. Since
+ <literal>stdenv</literal> does not normally execute this hook,
+ it allows you to do <command>nix-shell</command>-specific
+ setup.</para>
+ </listitem>
+
+ <listitem>
+ <para>It preserves the user’s timezone setting.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ </listitem>
+
+ <listitem>
+ <para>In chroots, Nix now sets up a <filename>/dev</filename>
+ containing only a minimal set of devices (such as
+ <filename>/dev/null</filename>). Note that it only does this if
+ you <emphasis>don’t</emphasis> have <filename>/dev</filename>
+ listed in your <option>build-chroot-dirs</option> setting;
+ otherwise, it will bind-mount the <literal>/dev</literal> from
+ outside the chroot.</para>
+
+ <para>Similarly, if you don’t have <filename>/dev/pts</filename> listed
+ in <option>build-chroot-dirs</option>, Nix will mount a private
+ <literal>devpts</literal> filesystem on the chroot’s
+ <filename>/dev/pts</filename>.</para>
+
+ </listitem>
+
+ <listitem>
+ <para>New built-in function: <function>builtins.toJSON</function>,
+ which returns a JSON representation of a value.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>nix-env -q</command> has a new flag
+ <option>--json</option> to print a JSON representation of the
+ installed or available packages.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>nix-env</command> now supports meta attributes with
+ more complex values, such as attribute sets.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <option>-A</option> flag now allows attribute names with
+ dots in them, e.g.
+
+<screen>
+$ nix-instantiate --eval '<nixos>' -A
'config.systemd.units."nscd.service".text'
+</screen>
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>The <option>--max-freed</option> option to
+ <command>nix-store --gc</command> now accepts a unit
+ specifier. For example, <literal>nix-store --gc --max-freed
+ 1G</literal> will free up to 1 gigabyte of disk space.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>nix-collect-garbage</command> has a new flag
+ <option>--delete-older-than</option>
+ <replaceable>N</replaceable><literal>d</literal>, which deletes
+ all user environment generations older than
+ <replaceable>N</replaceable> days. Likewise, <command>nix-env
+ --delete-generations</command> accepts a
+ <replaceable>N</replaceable><literal>d</literal> age limit.</para>
+ </listitem>
+
+ <listitem>
+ <para>Nix now heuristically detects whether a build failure was
+ due to a disk-full condition. In that case, the build is not
+ flagged as “permanently failedâ€. This is mostly useful for Hydra,
+ which needs to distinguish between permanent and transient build
+ failures.</para>
+ </listitem>
+
+ <listitem>
+ <para>There is a new symbol <literal>__curPos</literal> that
+ expands to an attribute set containing its file name and line and
+ column numbers, e.g. <literal>{ file = "foo.nix"; line = 10;
+ column = 5; }</literal>. There also is a new builtin function,
+ <varname>unsafeGetAttrPos</varname>, that returns the position of
+ an attribute. This is used by Nixpkgs to provide location
+ information in error messages, e.g.
+
+<screen>
+$ nix-build '<nixpkgs>' -A libreoffice --argstr system x86_64-darwin
+error: the package ‘libreoffice-4.0.5.2’ in
‘.../applications/office/libreoffice/default.nix:263’
+ is not supported on ‘x86_64-darwin’
+</screen>
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>The garbage collector is now more concurrent with other Nix
+ processes because it releases certain locks earlier.</para>
+ </listitem>
+
+ <listitem>
+ <para>The binary tarball installer has been improved. You can now
+ install Nix by running:
+
+<screen>
+$ bash <(curl https://nixos.org/nix/install)
+</screen>
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>More evaluation errors include position information. For
+ instance, selecting a missing attribute will print something like
+
+<screen>
+error: attribute `nixUnstabl' missing, at
/etc/nixos/configurations/misc/eelco/mandark.nix:216:15
+</screen>
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>The command <command>nix-setuid-helper</command> is
+ gone.</para>
+ </listitem>
+
+ <listitem>
+ <para>Nix no longer uses Automake, but instead has a
+ non-recursive, GNU Make-based build system.</para>
+ </listitem>
+
+ <listitem>
+ <para>All installed libraries now have the prefix
+ <literal>libnix</literal>. In particular, this gets rid of
+ <literal>libutil</literal>, which could clash with libraries with
+ the same name from other packages.</para>
+ </listitem>
+
+ <listitem>
+ <para>Nix now requires a compiler that supports C++11.</para>
+ </listitem>
+
+</itemizedlist>
+
+<para>This release has contributions from Danny Wilson, Domen Kožar,
+Eelco Dolstra, Ian-Woo Kim, Ludovic Courtès, Maxim Ivanov, Petr
+Rockai, Ricardo M. Correia and Shea Levy.</para>
+
+</chapter>
\ No newline at end of file
diff --git a/doc/manual/release-notes/rl-18.xml
b/doc/manual/release-notes/rl-18.xml
new file mode 100644
index 0000000..0fe3c2d
--- /dev/null
+++ b/doc/manual/release-notes/rl-18.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="ssec-relnotes-1.8">
+
+<title>Release 1.8 (TBA)</title>
+
+<para>TODO</para>
+
+</chapter>
\ No newline at end of file
diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml
deleted file mode 100644
index ec8c4c9..0000000
--- a/doc/manual/troubleshooting.xml
+++ /dev/null
@@ -1,92 +0,0 @@
-<appendix xmlns="http://docbook.org/ns/docbook";
- xmlns:xlink="http://www.w3.org/1999/xlink";>
-
-<title>Troubleshooting</title>
-
-
-<para>This section provides solutions for some common problems. See
-the <link xlink:href="http://bugs.strategoxt.org/browse/NIX";>Nix
-bug tracker</link> for a list of currently known issues.</para>
-
-
-<section><title>Collisions in <command>nix-env</command></title>
-
-<para>Symptom: when installing or upgrading, you get an error message such as
-
-<screen>
-$ nix-env -i docbook-xml
-...
-adding /nix/store/s5hyxgm62gk2...-docbook-xml-4.2
-collision between
`/nix/store/s5hyxgm62gk2...-docbook-xml-4.2/xml/dtd/docbook/calstblx.dtd'
- and `/nix/store/06h377hr4b33...-docbook-xml-4.3/xml/dtd/docbook/calstblx.dtd'
- at /nix/store/...-builder.pl line 62.</screen>
-
-</para>
-
-<para>The cause is that two installed packages in the user environment
-have overlapping filenames (e.g.,
-<filename>xml/dtd/docbook/calstblx.dtd</filename>. This usually
-happens when you accidentally try to install two versions of the same
-package. For instance, in the example above, the Nix Packages
-collection contains two versions of <literal>docbook-xml</literal>, so
-<command>nix-env -i</command> will try to install both. The default
-user environment builder has no way to way to resolve such conflicts,
-so it just gives up.</para>
-
-<para>Solution: remove one of the offending packages from the user
-environment (if already installed) using <command>nix-env
--e</command>, or specify exactly which version should be installed
-(e.g., <literal>nix-env -i docbook-xml-4.2</literal>).</para>
-
-<para>Alternatively, you can modify the user environment builder
-script (in
-<filename><replaceable>prefix</replaceable>/share/nix/corepkgs/buildenv/builder.pl</filename>)
-to implement some conflict resolution policy. E.g., the script could
-be modified to rename conflicting file names, or to pick one over the
-other.</para>
-
-</section>
-
-
-<section><title><quote>Too many links</quote> error in the Nix
-store</title>
-
-
-<para>Symptom: when building something, you get an error message such as
-
-<screen>
-...
-<literal>mkdir: cannot create directory
`/nix/store/<replaceable>name</replaceable>': Too many links</literal></screen>
-
-</para>
-
-<para>This is usually because you have more than 32,000 subdirectories
-in <filename>/nix/store</filename>, as can be seen using <command>ls
--l</command>:
-
-<screen>
-$ ls -l /nix/store
-drwxrwxrwt 32000 nix nix 4620288 Sep 8 15:08 store</screen>
-
-The <literal>ext2</literal> file system is limited to an inode link
-count of 32,000 (each subdirectory increasing the count by one).
-Furthermore, the <literal>st_nlink</literal> field of the
-<function>stat</function> system call is a 16-bit value.</para>
-
-<para>This only happens on very large Nix installations (such as build
-machines).</para>
-
-<para>Quick solution: run the garbage collector. You may want to use
-the <option>--max-links</option> option.</para>
-
-<para>Real solution: put the Nix store on a file system that supports
-more than 32,000 subdirectories per directory, such as ReiserFS.
-(This doesn’t solve the <literal>st_nlink</literal> limit, but
-ReiserFS lies to the kernel by reporting a link count of 1 if it
-exceeds the limit.)</para>
-
-</section>
-
-
-
-</appendix>
diff --git a/doc/manual/troubleshooting/collisions-nixenv.xml
b/doc/manual/troubleshooting/collisions-nixenv.xml
new file mode 100644
index 0000000..addc4cc
--- /dev/null
+++ b/doc/manual/troubleshooting/collisions-nixenv.xml
@@ -0,0 +1,43 @@
+<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-collisions-nixenv">
+
+<title>Collisions in <command>nix-env</command></title>
+
+<para>Symptom: when installing or upgrading, you get an error message such as
+
+<screen>
+$ nix-env -i docbook-xml
+...
+adding /nix/store/s5hyxgm62gk2...-docbook-xml-4.2
+collision between
`/nix/store/s5hyxgm62gk2...-docbook-xml-4.2/xml/dtd/docbook/calstblx.dtd'
+ and `/nix/store/06h377hr4b33...-docbook-xml-4.3/xml/dtd/docbook/calstblx.dtd'
+ at /nix/store/...-builder.pl line 62.</screen>
+
+</para>
+
+<para>The cause is that two installed packages in the user environment
+have overlapping filenames (e.g.,
+<filename>xml/dtd/docbook/calstblx.dtd</filename>. This usually
+happens when you accidentally try to install two versions of the same
+package. For instance, in the example above, the Nix Packages
+collection contains two versions of <literal>docbook-xml</literal>, so
+<command>nix-env -i</command> will try to install both. The default
+user environment builder has no way to way to resolve such conflicts,
+so it just gives up.</para>
+
+<para>Solution: remove one of the offending packages from the user
+environment (if already installed) using <command>nix-env
+-e</command>, or specify exactly which version should be installed
+(e.g., <literal>nix-env -i docbook-xml-4.2</literal>).</para>
+
+<para>Alternatively, you can modify the user environment builder
+script (in
+<filename><replaceable>prefix</replaceable>/share/nix/corepkgs/buildenv/builder.pl</filename>)
+to implement some conflict resolution policy. E.g., the script could
+be modified to rename conflicting file names, or to pick one over the
+other.</para>
+
+</chapter>
\ No newline at end of file
diff --git a/doc/manual/troubleshooting/links-nix-store.xml
b/doc/manual/troubleshooting/links-nix-store.xml
new file mode 100644
index 0000000..5efec8e
--- /dev/null
+++ b/doc/manual/troubleshooting/links-nix-store.xml
@@ -0,0 +1,43 @@
+<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-links-nix-store">
+
+<title><quote>Too many links</quote> Error in the Nix store</title>
+
+
+<para>Symptom: when building something, you get an error message such as
+
+<screen>
+...
+<literal>mkdir: cannot create directory
`/nix/store/<replaceable>name</replaceable>': Too many links</literal></screen>
+
+</para>
+
+<para>This is usually because you have more than 32,000 subdirectories
+in <filename>/nix/store</filename>, as can be seen using <command>ls
+-l</command>:
+
+<screen>
+$ ls -l /nix/store
+drwxrwxrwt 32000 nix nix 4620288 Sep 8 15:08 store</screen>
+
+The <literal>ext2</literal> file system is limited to an inode link
+count of 32,000 (each subdirectory increasing the count by one).
+Furthermore, the <literal>st_nlink</literal> field of the
+<function>stat</function> system call is a 16-bit value.</para>
+
+<para>This only happens on very large Nix installations (such as build
+machines).</para>
+
+<para>Quick solution: run the garbage collector. You may want to use
+the <option>--max-links</option> option.</para>
+
+<para>Real solution: put the Nix store on a file system that supports
+more than 32,000 subdirectories per directory, such as ReiserFS.
+(This doesn’t solve the <literal>st_nlink</literal> limit, but
+ReiserFS lies to the kernel by reporting a link count of 1 if it
+exceeds the limit.)</para>
+
+</chapter>
\ No newline at end of file
diff --git a/doc/manual/troubleshooting/troubleshooting.xml
b/doc/manual/troubleshooting/troubleshooting.xml
new file mode 100644
index 0000000..e538e53
--- /dev/null
+++ b/doc/manual/troubleshooting/troubleshooting.xml
@@ -0,0 +1,18 @@
+<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-troubleshooting">
+
+<title>Troubleshooting</title>
+
+<partintro>
+<para>This section provides solutions for some common problems. See
+the <link xlink:href="http://bugs.strategoxt.org/browse/NIX";>Nix
+bug tracker</link> for a list of currently known issues.</para>
+</partintro>
+
+<xi:include href="collisions-nixenv.xml" />
+<xi:include href="links-nix-store.xml" />
+
+</part>
diff --git a/doc/manual/writing-nix-expressions.xml
b/doc/manual/writing-nix-expressions.xml
deleted file mode 100644
index 0470625..0000000
--- a/doc/manual/writing-nix-expressions.xml
+++ /dev/null
@@ -1,1901 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook";
- xmlns:xlink="http://www.w3.org/1999/xlink";
- xml:id='chap-writing-nix-expressions'
- xmlns:xi="http://www.w3.org/2001/XInclude";>
-
-<title>Writing Nix Expressions</title>
-
-
-<para>This chapter shows you how to write Nix expressions, which are
-the things that tell 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>
-
-
-<section><title>A simple Nix expression</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>
-
-
-<section><title>The Nix expression</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>
-
-
-<section><title>The builder</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>
-
-
-<section><title>Composition</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>
-
-
-<section><title>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>
-
-
-<section><title>The generic builder</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>
-
-
-</section>
-
-
-
-<section><title>The 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>
-
-
-<section 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>
-
-
-<section><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>
address@hidden 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 && httpd.expat == expat; <co
xml:id='ex-subversion-nix-co-2' />
-assert sslSupport -> openssl != null && (httpServer -> httpd.openssl
== openssl); <co xml:id='ex-subversion-nix-co-3' />
-assert pythonBindings -> swig != null && swig.pythonSupport;
-assert javaSwigBindings -> swig != null && 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>
-
-
-<section><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>&&</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>
-
-
-<section 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>
-
-
-<section><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>
-
-
-</section>
-
-
-
-<xi:include href="builtins.xml" />
-
-
-</section>
-
-
-
-<section 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>
-
-
-<section><title>Customising 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>
-
-
-<section><title>Debugging failed builds</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>
-
-
-</section>
-
-
-</chapter>
- 237/376: Don't recompile the same regex over and over, (continued)
- 237/376: Don't recompile the same regex over and over, Ludovic Courtès, 2015/01/28
- 297/376: Build Ubuntu 14.10 package, Ludovic Courtès, 2015/01/28
- 268/376: Document some primops, Ludovic Courtès, 2015/01/28
- 272/376: Shut up a clang warning, Ludovic Courtès, 2015/01/28
- 257/376: Revert "binary download: Use $NIX_CURL_FLAGS", Ludovic Courtès, 2015/01/28
- 266/376: doc: fixed nix-instantiate --find-file, Ludovic Courtès, 2015/01/28
- 282/376: download-from-binary-cache.pl: Fix flushing of stderr, Ludovic Courtès, 2015/01/28
- 256/376: Merge pull request #372 from wmertens/patch-4, Ludovic Courtès, 2015/01/28
- 280/376: Typo, Ludovic Courtès, 2015/01/28
- 281/376: nix-store --gc: Don't warn about missing manifests directory, Ludovic Courtès, 2015/01/28
- 161/376: Restructuring the Nix manual,
Ludovic Courtès <=
- 271/376: Revert "Revert "Temporarily disable darwin builds while hydra's darwin is borked"", Ludovic Courtès, 2015/01/28
- 299/376: Remove Hydra scheduling priorities, Ludovic Courtès, 2015/01/28
- 285/376: Make ~DerivationGoal more reliable, Ludovic Courtès, 2015/01/28
- 277/376: nix-daemon: Get peer credentials on Mac OS X, Ludovic Courtès, 2015/01/28
- 286/376: build-remote.pl.in: Add some more trace messages, Ludovic Courtès, 2015/01/28
- 288/376: Add functors (callable attribute sets)., Ludovic Courtès, 2015/01/28
- 236/376: nix-env: Add regular expression support in selectors, Ludovic Courtès, 2015/01/28
- 261/376: Improve printing of ASTs, Ludovic Courtès, 2015/01/28
- 269/376: Update release notes, Ludovic Courtès, 2015/01/28