nix-shell: Only download requested outputs

Fixes #2116. (cherry picked from commit a1adcdf087)
In restricted eval mode, allow access to the closure of store paths
2018-05-29 14:18:55 +02:00 · 2018-05-29 14:18:42 +02:00 · 2018-05-29 14:17:23 +02:00 · 2018-05-29 13:54:48 +02:00 · 2018-05-26 12:42:54 -04:00 · 2018-05-26 12:42:54 -04:00
743 changed files with 76817 additions and 28720 deletions
--- a/.dir-locals.el
+++ b/.dir-locals.el
@@ -0,0 +1,16 @@
+((c++-mode . (
+  (c-file-style . "k&r")
+  (c-basic-offset . 4)
+  (indent-tabs-mode . nil)
+  (tab-width . 4)
+  (show-trailing-whitespace . t)
+  (indicate-empty-lines . t)
+  (eval . (c-set-offset 'innamespace 0))
+  (eval . (c-set-offset 'defun-open 0))
+  (eval . (c-set-offset 'inline-open 0))
+  (eval . (c-set-offset 'arglist-intro '+))
+  (eval . (c-set-offset 'arglist-cont 0))
+  (eval . (c-set-offset 'arglist-cont-nonempty '+))
+  (eval . (c-set-offset 'substatement-open 0))
+  (eval . (c-set-offset 'access-label '-))
+  )))
--- a/.editorconfig
+++ b/.editorconfig
@@ -0,0 +1,26 @@
+# EditorConfig configuration for nix
+# http://EditorConfig.org
+
+# Top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file, utf-8 charset
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+
+# Match nix files, set indent to spaces with width of two
+[*.nix]
+indent_style = space
+indent_size = 2
+
+# Match c++/shell/perl, set indent to spaces with width of four
+[*.{hpp,cc,hh,sh,pl}]
+indent_style = space
+indent_size = 4
+
+# Match diffs, avoid to trim trailing whitespace
+[*.{diff,patch}]
+trim_trailing_whitespace = false
--- a/.github/ISSUE_TEMPLATE.md
+++ b/.github/ISSUE_TEMPLATE.md
@@ -0,0 +1,27 @@
+<!--
+
+# Filing a Nix issue
+
+*WAIT* Are you sure you're filing your issue in the right repository?
+
+We appreciate you taking the time to tell us about issues you encounter, but routing the issue to the right place will get you help sooner and save everyone time.
+
+This is the Nix repository, and issues here should be about Nix the build and package management *_tool_*.
+
+If you have a problem with a specific package on NixOS or when using Nix, you probably want to file an issue with _nixpkgs_, whose issue tracker is over at https://github.com/NixOS/nixpkgs/issues.
+
+Examples of _Nix_ issues:
+
+- Nix segfaults when I run `nix-build -A blahblah`
+- The Nix language needs a new builtin: `builtins.foobar`
+- Regression in the behavior of `nix-env` in Nix 2.0
+
+Examples of _nixpkgs_ issues:
+
+- glibc is b0rked on aarch64
+- chromium in NixOS doesn't support U2F but google-chrome does!
+- The OpenJDK package on macOS is missing a key component
+
+Chances are if you're a newcomer to the Nix world, you'll probably want the [nixpkgs tracker](https://github.com/NixOS/nixpkgs/issues). It also gets a lot more eyeball traffic so you'll probably get a response a lot more quickly.
+
+-->
--- a/.gitignore
+++ b/.gitignore
@@ -1,8 +1,7 @@
-# START "git svn show-ignore"
+Makefile.config
+perl/Makefile.config

 # /
-/Makefile
-/Makefile.in
 /aclocal.m4
 /autom4te.cache
 /config.*
@@ -10,250 +9,111 @@
 /nix.spec
 /stamp-h1
 /svn-revision
-/NEWS
 /libtool

-# /config/
-/config/config.guess
-/config/config.sub
-/config/depcomp
-/config/install-sh
-/config/missing
-/config/mkinstalldirs
-/config/ltmain.sh
-
-# /corepkgs/
-/corepkgs/Makefile
-/corepkgs/Makefile.in
+/corepkgs/config.nix

 # /corepkgs/buildenv/
-/corepkgs/buildenv/Makefile.in
-/corepkgs/buildenv/Makefile
 /corepkgs/buildenv/builder.pl

 # /corepkgs/channels/
-/corepkgs/channels/Makefile.in
-/corepkgs/channels/Makefile
 /corepkgs/channels/unpack.sh

 # /corepkgs/nar/
-/corepkgs/nar/Makefile
-/corepkgs/nar/Makefile.in
 /corepkgs/nar/nar.sh
 /corepkgs/nar/unnar.sh

-# /doc/
-/doc/Makefile
-/doc/Makefile.in
-
 # /doc/manual/
-/doc/manual/Makefile
-/doc/manual/Makefile.in
 /doc/manual/manual.html
+/doc/manual/manual.xmli
+/doc/manual/manual.pdf
 /doc/manual/manual.is-valid
 /doc/manual/*.1
+/doc/manual/*.5
 /doc/manual/*.8
-/doc/manual/images
 /doc/manual/version.txt
-/doc/manual/NEWS.html
-/doc/manual/NEWS.txt
-
-# /externals/
-/externals/Makefile
-/externals/Makefile.in
-/externals/aterm-*
-/externals/have-aterm
-/externals/build-aterm
-/externals/inst-aterm
-/externals/bzip2-*
-/externals/have-bzip2
-/externals/build-bzip2
-/externals/inst-bzip2
-
-# /make/examples/aterm/
-/make/examples/aterm/result*
-
-# /make/examples/aterm/aterm/
-/make/examples/aterm/aterm/*
-
-# /make/examples/aterm/test/
-/make/examples/aterm/test/*
-
-# /misc/
-/misc/Makefile.in
-/misc/Makefile
-
-# /misc/emacs/
-/misc/emacs/Makefile.in
-/misc/emacs/Makefile

 # /scripts/
-/scripts/Makefile
-/scripts/Makefile.in
 /scripts/nix-profile.sh
-/scripts/nix-pull
-/scripts/nix-push
-/scripts/nix-switch
-/scripts/nix-collect-garbage
-/scripts/nix-prefetch-url
-/scripts/nix-install-package
-/scripts/nix-channel
-/scripts/nix-build
 /scripts/nix-copy-closure
-/scripts/readmanifest.pm
-/scripts/readconfig.pm
-/scripts/download-using-manifests.pl
-/scripts/copy-from-other-stores.pl
-/scripts/generate-patches.pl
-/scripts/find-runtime-roots.pl
-/scripts/build-remote.pl
-
-# /src/
-/src/Makefile
-/src/Makefile.in
-
-# /src/bin2c/
-/src/bin2c/Makefile.in
-/src/bin2c/Makefile
-/src/bin2c/bin2c
-/src/bin2c/.deps
-/src/bin2c/.libs
-
-# /src/boost/
-/src/boost/Makefile
-/src/boost/Makefile.in
-
-# /src/boost/format/
-/src/boost/format/Makefile
-/src/boost/format/Makefile.in
-/src/boost/format/.deps
-/src/boost/format/libformat.a
-/src/boost/format/.libs
-
-# /src/bsdiff-4.3/
-/src/bsdiff-4.3/Makefile
-/src/bsdiff-4.3/Makefile.in
-/src/bsdiff-4.3/bsdiff
-/src/bsdiff-4.3/bspatch
-/src/bsdiff-4.3/.deps
-/src/bsdiff-4.3/.libs
+/scripts/nix-reduce-build
+/scripts/nix-http-export.cgi
+/scripts/nix-profile-daemon.sh

 # /src/libexpr/
-/src/libexpr/Makefile
-/src/libexpr/Makefile.in
-/src/libexpr/.deps
-/src/libexpr/libexpr.a
 /src/libexpr/lexer-tab.cc
 /src/libexpr/lexer-tab.hh
 /src/libexpr/parser-tab.cc
 /src/libexpr/parser-tab.hh
 /src/libexpr/parser-tab.output
-/src/libexpr/nixexpr-ast.hh
-/src/libexpr/nixexpr-ast.cc
-/src/libexpr/.libs
 /src/libexpr/nix.tbl

-# /src/libmain/
-/src/libmain/Makefile
-/src/libmain/Makefile.in
-/src/libmain/.deps
-/src/libmain/libmain.a
-/src/libmain/.libs
-
 # /src/libstore/
-/src/libstore/Makefile
-/src/libstore/Makefile.in
-/src/libstore/.deps
-/src/libstore/libstore.a
-/src/libstore/derivations-ast.cc
-/src/libstore/derivations-ast.hh
-/src/libstore/.libs
+/src/libstore/*.gen.hh

-# /src/libutil/
-/src/libutil/Makefile
-/src/libutil/Makefile.in
-/src/libutil/.deps
-/src/libutil/libutil.a
-/src/libutil/.libs
+/src/nix/nix

 # /src/nix-env/
-/src/nix-env/Makefile.in
-/src/nix-env/Makefile
-/src/nix-env/.deps
 /src/nix-env/nix-env
-/src/nix-env/help.txt.hh
-/src/nix-env/.libs
-
-# /src/nix-hash/
-/src/nix-hash/Makefile
-/src/nix-hash/Makefile.in
-/src/nix-hash/.deps
-/src/nix-hash/.libs
-/src/nix-hash/nix-hash
-/src/nix-hash/help.txt.hh

 # /src/nix-instantiate/
-/src/nix-instantiate/Makefile.in
-/src/nix-instantiate/Makefile
-/src/nix-instantiate/.deps
 /src/nix-instantiate/nix-instantiate
-/src/nix-instantiate/help.txt.hh
-/src/nix-instantiate/.libs
-
-# /src/nix-log2xml/
-/src/nix-log2xml/Makefile.in
-/src/nix-log2xml/Makefile
-/src/nix-log2xml/.deps
-/src/nix-log2xml/nix-log2xml
-/src/nix-log2xml/test*.*
-/src/nix-log2xml/.libs
-/src/nix-log2xml/*.log
-/src/nix-log2xml/*.xml
-/src/nix-log2xml/*.html
-
-# /src/nix-setuid-helper/
-/src/nix-setuid-helper/Makefile.in
-/src/nix-setuid-helper/Makefile
-/src/nix-setuid-helper/.deps
-/src/nix-setuid-helper/nix-setuid-helper
-/src/nix-setuid-helper/help.txt.hh
-/src/nix-setuid-helper/.libs

 # /src/nix-store/
-/src/nix-store/Makefile
-/src/nix-store/Makefile.in
-/src/nix-store/.deps
-/src/nix-store/help.txt.hh
 /src/nix-store/nix-store
-/src/nix-store/.libs

-# /src/nix-worker/
-/src/nix-worker/Makefile.in
-/src/nix-worker/Makefile
-/src/nix-worker/.deps
-/src/nix-worker/nix-worker
-/src/nix-worker/help.txt.hh
-/src/nix-worker/.libs
+/src/nix-prefetch-url/nix-prefetch-url
+
+# /src/nix-daemon/
+/src/nix-daemon/nix-daemon
+
+/src/nix-collect-garbage/nix-collect-garbage
+
+# /src/nix-channel/
+/src/nix-channel/nix-channel
+
+# /src/buildenv/
+/src/buildenv/buildenv
+
+# /src/nix-build/
+/src/nix-build/nix-build
+
+/src/nix-copy-closure/nix-copy-closure
+
+/src/build-remote/build-remote

 # /tests/
-/tests/Makefile
-/tests/Makefile.in
 /tests/test-tmp
-/tests/config.nix
 /tests/common.sh
 /tests/dummy
+/tests/result*

 # /tests/lang/
 /tests/lang/*.out
 /tests/lang/*.out.xml
 /tests/lang/*.ast

-# END "git svn show-ignore"
+/perl/lib/Nix/Config.pm
+/perl/lib/Nix/Store.cc

-*.lo
-*.la
+/misc/systemd/nix-daemon.service
+/misc/systemd/nix-daemon.socket
+/misc/upstart/nix-daemon.conf
+
+/src/resolve-system-dependencies/resolve-system-dependencies
+
+inst/
+
+*.a
 *.o
+*.so
+*.dylib
+*.dll
+*.exe
+*.dep
 *~
+*.pc
+*.plist

 # GNU Global
 GPATH
--- a/.travis.yml
+++ b/.travis.yml
@@ -0,0 +1,2 @@
+os: osx
+script: ./tests/install-darwin.sh
--- a/8
+++ b/8
@@ -1,8 +0,0 @@
-The following people contributed to Nix, in alphabetical order:
-
-Martin Bravenboer
-Eelco Dolstra
-Niels Janssen
-Armijn Hemel
-Rob Vermaas
-Eelco Visser
--- a/229
+++ b/229
@@ -1,229 +0,0 @@
-Copyright 1994, 1995, 1996, 1999, 2000, 2001, 2002 Free Software
-Foundation, Inc.
-
-   This file is free documentation; the Free Software Foundation gives
-unlimited permission to copy, distribute and modify it.
-
-Basic Installation
-==================
-
-   These are generic installation instructions.
-
-   The `configure' shell script attempts to guess correct values for
-various system-dependent variables used during compilation.  It uses
-those values to create a `Makefile' in each directory of the package.
-It may also create one or more `.h' files containing system-dependent
-definitions.  Finally, it creates a shell script `config.status' that
-you can run in the future to recreate the current configuration, and a
-file `config.log' containing compiler output (useful mainly for
-debugging `configure').
-
-   It can also use an optional file (typically called `config.cache'
-and enabled with `--cache-file=config.cache' or simply `-C') that saves
-the results of its tests to speed up reconfiguring.  (Caching is
-disabled by default to prevent problems with accidental use of stale
-cache files.)
-
-   If you need to do unusual things to compile the package, please try
-to figure out how `configure' could check whether to do them, and mail
-diffs or instructions to the address given in the `README' so they can
-be considered for the next release.  If you are using the cache, and at
-some point `config.cache' contains results you don't want to keep, you
-may remove or edit it.
-
-   The file `configure.ac' (or `configure.in') is used to create
-`configure' by a program called `autoconf'.  You only need
-`configure.ac' if you want to change it or regenerate `configure' using
-a newer version of `autoconf'.
-
-The simplest way to compile this package is:
-
-  1. `cd' to the directory containing the package's source code and type
-     `./configure' to configure the package for your system.  If you're
-     using `csh' on an old version of System V, you might need to type
-     `sh ./configure' instead to prevent `csh' from trying to execute
-     `configure' itself.
-
-     Running `configure' takes awhile.  While running, it prints some
-     messages telling which features it is checking for.
-
-  2. Type `make' to compile the package.
-
-  3. Optionally, type `make check' to run any self-tests that come with
-     the package.
-
-  4. Type `make install' to install the programs and any data files and
-     documentation.
-
-  5. You can remove the program binaries and object files from the
-     source code directory by typing `make clean'.  To also remove the
-     files that `configure' created (so you can compile the package for
-     a different kind of computer), type `make distclean'.  There is
-     also a `make maintainer-clean' target, but that is intended mainly
-     for the package's developers.  If you use it, you may have to get
-     all sorts of other programs in order to regenerate files that came
-     with the distribution.
-
-Compilers and Options
-=====================
-
-   Some systems require unusual options for compilation or linking that
-the `configure' script does not know about.  Run `./configure --help'
-for details on some of the pertinent environment variables.
-
-   You can give `configure' initial values for configuration parameters
-by setting variables in the command line or in the environment.  Here
-is an example:
-
-     ./configure CC=c89 CFLAGS=-O2 LIBS=-lposix
-
-   *Note Defining Variables::, for more details.
-
-Compiling For Multiple Architectures
-====================================
-
-   You can compile the package for more than one kind of computer at the
-same time, by placing the object files for each architecture in their
-own directory.  To do this, you must use a version of `make' that
-supports the `VPATH' variable, such as GNU `make'.  `cd' to the
-directory where you want the object files and executables to go and run
-the `configure' script.  `configure' automatically checks for the
-source code in the directory that `configure' is in and in `..'.
-
-   If you have to use a `make' that does not support the `VPATH'
-variable, you have to compile the package for one architecture at a
-time in the source code directory.  After you have installed the
-package for one architecture, use `make distclean' before reconfiguring
-for another architecture.
-
-Installation Names
-==================
-
-   By default, `make install' will install the package's files in
-`/usr/local/bin', `/usr/local/man', etc.  You can specify an
-installation prefix other than `/usr/local' by giving `configure' the
-option `--prefix=PATH'.
-
-   You can specify separate installation prefixes for
-architecture-specific files and architecture-independent files.  If you
-give `configure' the option `--exec-prefix=PATH', the package will use
-PATH as the prefix for installing programs and libraries.
-Documentation and other data files will still use the regular prefix.
-
-   In addition, if you use an unusual directory layout you can give
-options like `--bindir=PATH' to specify different values for particular
-kinds of files.  Run `configure --help' for a list of the directories
-you can set and what kinds of files go in them.
-
-   If the package supports it, you can cause programs to be installed
-with an extra prefix or suffix on their names by giving `configure' the
-option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
-
-Optional Features
-=================
-
-   Some packages pay attention to `--enable-FEATURE' options to
-`configure', where FEATURE indicates an optional part of the package.
-They may also pay attention to `--with-PACKAGE' options, where PACKAGE
-is something like `gnu-as' or `x' (for the X Window System).  The
-`README' should mention any `--enable-' and `--with-' options that the
-package recognizes.
-
-   For packages that use the X Window System, `configure' can usually
-find the X include and library files automatically, but if it doesn't,
-you can use the `configure' options `--x-includes=DIR' and
-`--x-libraries=DIR' to specify their locations.
-
-Specifying the System Type
-==========================
-
-   There may be some features `configure' cannot figure out
-automatically, but needs to determine by the type of machine the package
-will run on.  Usually, assuming the package is built to be run on the
-_same_ architectures, `configure' can figure that out, but if it prints
-a message saying it cannot guess the machine type, give it the
-`--build=TYPE' option.  TYPE can either be a short name for the system
-type, such as `sun4', or a canonical name which has the form:
-
-     CPU-COMPANY-SYSTEM
-
-where SYSTEM can have one of these forms:
-
-     OS KERNEL-OS
-
-   See the file `config.sub' for the possible values of each field.  If
-`config.sub' isn't included in this package, then this package doesn't
-need to know the machine type.
-
-   If you are _building_ compiler tools for cross-compiling, you should
-use the `--target=TYPE' option to select the type of system they will
-produce code for.
-
-   If you want to _use_ a cross compiler, that generates code for a
-platform different from the build platform, you should specify the
-"host" platform (i.e., that on which the generated programs will
-eventually be run) with `--host=TYPE'.
-
-Sharing Defaults
-================
-
-   If you want to set default values for `configure' scripts to share,
-you can create a site shell script called `config.site' that gives
-default values for variables like `CC', `cache_file', and `prefix'.
-`configure' looks for `PREFIX/share/config.site' if it exists, then
-`PREFIX/etc/config.site' if it exists.  Or, you can set the
-`CONFIG_SITE' environment variable to the location of the site script.
-A warning: not all `configure' scripts look for a site script.
-
-Defining Variables
-==================
-
-   Variables not defined in a site shell script can be set in the
-environment passed to `configure'.  However, some packages may run
-configure again during the build, and the customized values of these
-variables may be lost.  In order to avoid this problem, you should set
-them in the `configure' command line, using `VAR=value'.  For example:
-
-     ./configure CC=/usr/local2/bin/gcc
-
-will cause the specified gcc to be used as the C compiler (unless it is
-overridden in the site shell script).
-
-`configure' Invocation
-======================
-
-   `configure' recognizes the following options to control how it
-operates.
-
-`--help'
-`-h'
-     Print a summary of the options to `configure', and exit.
-
-`--version'
-`-V'
-     Print the version of Autoconf used to generate the `configure'
-     script, and exit.
-
-`--cache-file=FILE'
-     Enable the cache: use and save the results of the tests in FILE,
-     traditionally `config.cache'.  FILE defaults to `/dev/null' to
-     disable caching.
-
-`--config-cache'
-`-C'
-     Alias for `--cache-file=config.cache'.
-
-`--quiet'
-`--silent'
-`-q'
-     Do not print messages saying which checks are being made.  To
-     suppress all normal output, redirect it to `/dev/null' (any error
-     messages will still be shown).
-
-`--srcdir=DIR'
-     Look for the package's source code in directory DIR.  Usually
-     `configure' can determine that directory automatically.
-
-`configure' also accepts some other, not widely useful, options.  Run
-`configure --help' for more details.
-
--- a/41
+++ b/41
@@ -0,0 +1,41 @@
+makefiles = \
+  local.mk \
+  src/boost/format/local.mk \
+  src/libutil/local.mk \
+  src/libstore/local.mk \
+  src/libmain/local.mk \
+  src/libexpr/local.mk \
+  src/nix/local.mk \
+  src/nix-store/local.mk \
+  src/nix-instantiate/local.mk \
+  src/nix-env/local.mk \
+  src/nix-daemon/local.mk \
+  src/nix-collect-garbage/local.mk \
+  src/nix-copy-closure/local.mk \
+  src/nix-prefetch-url/local.mk \
+  src/buildenv/local.mk \
+  src/resolve-system-dependencies/local.mk \
+  src/nix-channel/local.mk \
+  src/nix-build/local.mk \
+  src/build-remote/local.mk \
+  scripts/local.mk \
+  corepkgs/local.mk \
+  misc/systemd/local.mk \
+  misc/launchd/local.mk \
+  misc/upstart/local.mk \
+  doc/manual/local.mk \
+  tests/local.mk \
+  tests/plugins/local.mk
+
+GLOBAL_CXXFLAGS += -std=c++14 -g -Wall -include config.h
+
+-include Makefile.config
+
+OPTIMIZE = 1
+
+ifeq ($(OPTIMIZE), 1)
+  GLOBAL_CFLAGS += -O3
+  GLOBAL_CXXFLAGS += -O3
+endif
+
+include mk/lib.mk
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,48 +0,0 @@
-SUBDIRS = externals src scripts corepkgs doc misc tests
-EXTRA_DIST = substitute.mk nix.spec nix.spec.in bootstrap.sh \
-  nix.conf.example NEWS version
-
-pkginclude_HEADERS = config.h
-
-include ./substitute.mk
-
-nix.spec: nix.spec.in
-
-install-data-local: init-state
-	$(INSTALL) -d $(DESTDIR)$(sysconfdir)/nix
-	$(INSTALL_DATA) $(srcdir)/nix.conf.example $(DESTDIR)$(sysconfdir)/nix
-	if ! test -e $(DESTDIR)$(sysconfdir)/nix/nix.conf; then \
-		$(INSTALL_DATA) $(srcdir)/nix.conf.example $(DESTDIR)$(sysconfdir)/nix/nix.conf; \
-	fi
-	$(INSTALL) -d $(DESTDIR)$(docdir)
-	$(INSTALL_DATA) README $(DESTDIR)$(docdir)/
-
-if INIT_STATE
-
-# For setuid operation, you can enable the following:
-# INIT_FLAGS = -g @NIX_GROUP@ -o @NIX_USER@
-# GROUP_WRITABLE = -m 775
-
-init-state:
-	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(localstatedir)/nix
-	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(localstatedir)/nix/db
-	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(localstatedir)/log/nix
-	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(localstatedir)/log/nix/drvs
-	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(localstatedir)/nix/profiles
-	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(localstatedir)/nix/gcroots
-	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(localstatedir)/nix/temproots
-	ln -sfn $(localstatedir)/nix/profiles $(DESTDIR)$(localstatedir)/nix/gcroots/profiles
-	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(localstatedir)/nix/userpool
-	-$(INSTALL) $(INIT_FLAGS) -m 1777 -d $(DESTDIR)$(storedir)
-	$(INSTALL) $(INIT_FLAGS) $(GROUP_WRITABLE) -d $(DESTDIR)$(localstatedir)/nix/manifests
-	ln -sfn $(localstatedir)/nix/manifests $(DESTDIR)$(localstatedir)/nix/gcroots/manifests
-
-else
-
-init-state:
-
-endif
-
-NEWS:
-	$(MAKE) -C doc/manual NEWS.txt
-	cp $(srcdir)/doc/manual/NEWS.txt NEWS
--- a/Makefile.config.in
+++ b/Makefile.config.in
@@ -0,0 +1,39 @@
+BDW_GC_LIBS = @BDW_GC_LIBS@
+CC = @CC@
+CFLAGS = @CFLAGS@
+CXX = @CXX@
+CXXFLAGS = @CXXFLAGS@
+ENABLE_S3 = @ENABLE_S3@
+HAVE_SODIUM = @HAVE_SODIUM@
+HAVE_READLINE = @HAVE_READLINE@
+HAVE_BROTLI = @HAVE_BROTLI@
+HAVE_SECCOMP = @HAVE_SECCOMP@
+LIBCURL_LIBS = @LIBCURL_LIBS@
+OPENSSL_LIBS = @OPENSSL_LIBS@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+SODIUM_LIBS = @SODIUM_LIBS@
+LIBLZMA_LIBS = @LIBLZMA_LIBS@
+SQLITE3_LIBS = @SQLITE3_LIBS@
+LIBBROTLI_LIBS = @LIBBROTLI_LIBS@
+bash = @bash@
+bindir = @bindir@
+brotli = @brotli@
+lsof = @lsof@
+datadir = @datadir@
+datarootdir = @datarootdir@
+docdir = @docdir@
+exec_prefix = @exec_prefix@
+includedir = @includedir@
+libdir = @libdir@
+libexecdir = @libexecdir@
+localstatedir = @localstatedir@
+mandir = @mandir@
+pkglibdir = $(libdir)/$(PACKAGE_NAME)
+prefix = @prefix@
+sandbox_shell = @sandbox_shell@
+storedir = @storedir@
+sysconfdir = @sysconfdir@
+doc_generate = @doc_generate@
+xmllint = @xmllint@
+xsltproc = @xsltproc@
--- a/10
+++ b/10
@@ -1,10 +0,0 @@
-Nix is a purely functional package manager.  For installation and
-usage instructions, please read the manual, which can be found in
-`docs/manual/manual.html', and additionally at the Nix website at
-<http://nixos.org/>.
-
-
-Acknowledgments
-
-This product includes software developed by the OpenSSL Project for
-use in the OpenSSL Toolkit (http://www.OpenSSL.org/).
--- a/README.md
+++ b/README.md
@@ -0,0 +1,22 @@
+Nix, the purely functional package manager
+------------------------------------------
+
+Nix is a new take on package management that is fairly unique. Because of its
+purity aspects, a lot of issues found in traditional package managers don't
+appear with Nix.
+
+To find out more about the tool, usage and installation instructions, please
+read the manual, which is available on the Nix website at
+<http://nixos.org/nix/manual>.
+
+## Contributing
+
+Take a look at the [Hacking Section](http://nixos.org/nix/manual/#chap-hacking)
+of the manual. It helps you to get started with building Nix from source.
+
+## License
+
+Nix is released under the LGPL v2.1
+
+This product includes software developed by the OpenSSL Project for
+use in the [OpenSSL Toolkit](http://www.OpenSSL.org/).
--- a/aterm-gc.supp
+++ b/aterm-gc.supp
@@ -1,149 +0,0 @@
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Cond
-   fun:*
-   fun:AT_collect_minor
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Cond
-   fun:*
-   fun:*
-   fun:AT_collect_minor
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value4
-   fun:*
-   fun:AT_collect_minor
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value8
-   fun:*
-   fun:AT_collect_minor
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value4
-   fun:*
-   fun:*
-   fun:AT_collect_minor
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value8
-   fun:*
-   fun:*
-   fun:AT_collect_minor
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Addr4
-   fun:*
-   fun:AT_collect_minor
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Addr8
-   fun:*
-   fun:AT_collect_minor
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Cond
-   fun:*
-   fun:AT_collect
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value4
-   fun:*
-   fun:AT_collect
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value8
-   fun:*
-   fun:AT_collect
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Addr4
-   fun:*
-   fun:AT_collect
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Addr8
-   fun:*
-   fun:AT_collect
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value4
-   fun:*
-   fun:*
-   fun:AT_collect
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value8
-   fun:*
-   fun:*
-   fun:AT_collect
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Cond
-   fun:*
-   fun:*
-   fun:AT_collect
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value4
-   fun:*
-   fun:*
-   fun:mark_phase
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Cond
-   fun:*
-   fun:*
-   fun:mark_phase
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value4
-   fun:*
-   fun:*
-   fun:mark_phase_young
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Cond
-   fun:*
-   fun:*
-   fun:mark_phase_young
-}
--- a/blacklisting/check-env.pl
+++ b/blacklisting/check-env.pl
@@ -1,252 +0,0 @@
-#! /usr/bin/perl -w -I /home/eelco/.nix-profile/lib/site_perl
-
-use strict;
-use XML::LibXML;
-#use XML::Simple;
-
-my $blacklistFN = shift @ARGV;
-die unless defined $blacklistFN;
-my $userEnv = shift @ARGV;
-die unless defined $userEnv;
-
-
-# Read the blacklist.
-my $parser = XML::LibXML->new();
-my $blacklist = $parser->parse_file($blacklistFN)->getDocumentElement;
-
-#print $blacklist->toString() , "\n";
-
-
-# Get all the elements of the user environment.
-my $userEnvElems = `nix-store --query --references '$userEnv'`;
-die "cannot query user environment elements" if $? != 0;
-my @userEnvElems = split ' ', $userEnvElems;
-
-
-my %storePathHashes;
-
-
-sub getElemNodes {
-    my $node = shift;
-    my @elems = ();
-    foreach my $node ($node->getChildNodes) {
-        push @elems, $node if $node->nodeType == XML_ELEMENT_NODE;
-    }
-    return @elems;
-}
-
-
-my %referencesCache;
-sub getReferences {
-    my $path = shift;
-    return $referencesCache{$path} if defined $referencesCache{$path};
-    
-    my $references = `nix-store --query --references '$path'`;
-    die "cannot query references" if $? != 0;
-    $referencesCache{$path} = [split ' ', $references];
-    
-    return $referencesCache{$path};
-}
-
-
-my %attrsCache;
-sub getAttr {
-    my $path = shift;
-    my $name = shift;
-    my $key = "$path/$name";
-    return $referencesCache{$key} if defined $referencesCache{$key};
-
-    my $value = `nix-store --query --binding '$name' '$path' 2> /dev/null`;
-    $value = "" if $? != 0; # !!!
-    chomp $value;
-    $referencesCache{$key} = $value;
-
-    return $value;
-}
-
-
-sub evalCondition;
-
-
-sub traverse {
-    my $done = shift;
-    my $set = shift;
-    my $path = shift;
-    my $stopCondition = shift;
-
-    return if defined $done->{$path};
-    $done->{$path} = 1;
-    $set->{$path} = 1;
-
-#    print "  in $path\n";
-
-    if (!evalCondition({$path => 1}, $stopCondition)) {
-#        print "  STOPPING in $path\n";
-        return;
-    }
-
-    # Get the requisites of the deriver.
-
-    foreach my $reference (@{getReferences $path}) {
-        traverse($done, $set, $reference, $stopCondition);
-    }
-}
-
-
-sub evalSet {
-    my $inSet = shift;
-    my $expr = shift;
-    my $name = $expr->getName;
-    
-    if ($name eq "traverse") {
-        my $stopCondition = (getElemNodes $expr)[0];
-        my $done = { };
-        my $set = { };
-        foreach my $path (keys %{$inSet}) {
-            traverse($done, $set, $path, $stopCondition);
-        }
-        return $set;
-    }
-
-    else {
-        die "unknown element `$name'";
-    }
-}
-
-
-# Function for evaluating conditions.
-sub evalCondition {
-    my $storePaths = shift;
-    my $condition = shift;
-    my $elemName = $condition->getName;
-    
-    if ($elemName eq "containsSource") {
-        my $hash = $condition->attributes->getNamedItem("hash")->getValue;
-        foreach my $path (keys %{$storePathHashes{$hash}}) {
-            return 1 if defined $storePaths->{$path};
-        }
-        return 0;
-    }
-
-    elsif ($elemName eq "hasName") { 
-        my $nameRE = $condition->attributes->getNamedItem("name")->getValue;
-        foreach my $path (keys %{$storePaths}) {
-            return 1 if $path =~ /$nameRE/;
-        }
-        return 0;
-    }
-    
-    elsif ($elemName eq "hasAttr") { 
-        my $name = $condition->attributes->getNamedItem("name")->getValue;
-        my $valueRE = $condition->attributes->getNamedItem("value")->getValue;
-        foreach my $path (keys %{$storePaths}) {
-            if ($path =~ /\.drv$/) {
-                my $value = getAttr($path, $name);
-#                print "    $path $name $value\n";
-                return 1 if $value =~ /$valueRE/;
-            }
-        }
-        return 0;
-    }
-    
-    elsif ($elemName eq "and") {
-        my $result = 1;
-        foreach my $node (getElemNodes $condition) {
-            $result &= evalCondition($storePaths, $node);
-        }
-        return $result;
-    }
-
-    elsif ($elemName eq "not") {
-        return !evalCondition($storePaths, (getElemNodes $condition)[0]);
-    }
-    
-    elsif ($elemName eq "within") {
-        my @elems = getElemNodes $condition;
-        my $set = evalSet($storePaths, $elems[0]);
-        return evalCondition($set, $elems[1]);
-    }
-
-    elsif ($elemName eq "true") {
-        return 1;
-    }
-
-    elsif ($elemName eq "false") {
-        return 0;
-    }
-
-    else {
-        die "unknown element `$elemName'";
-    }
-}
-
-
-sub evalOr {
-    my $storePaths = shift;
-    my $nodes = shift;
-
-    my $result = 0;
-    foreach my $node (@{$nodes}) {
-        $result |= evalCondition($storePaths, $node);
-    }
-    
-    return $result;
-}
-
-
-# Iterate over all elements, check them.
-foreach my $userEnvElem (@userEnvElems) {
-
-    # Get the deriver of this path.
-    my $deriver = `nix-store --query --deriver '$userEnvElem'`;
-    die "cannot query deriver" if $? != 0;
-    chomp $deriver;
-
-    if ($deriver eq "unknown-deriver") {
-#        print "  deriver unknown, cannot check sources\n";
-        next;
-    }
-
-    print "CHECKING $userEnvElem\n";
-
-
-    # Get the requisites of the deriver.
-#    my $requisites = `nix-store --query --requisites --include-outputs '$deriver'`;
-#    die "cannot query requisites" if $? != 0;
-#    my @requisites = split ' ', $requisites;
-
-
-    # Get the hashes of the requisites.
-#    my $hashes = `nix-store --query --hash @requisites`;
-#    die "cannot query hashes" if $? != 0;
-#    my @hashes = split ' ', $hashes;
-#    for (my $i = 0; $i < scalar @requisites; $i++) {
-#        die unless $i < scalar @hashes;
-#        my $hash = $hashes[$i];
-#        $storePathHashes{$hash} = {} unless defined $storePathHashes{$hash};
-#        my $r = $storePathHashes{$hash}; # !!! fix
-#        $$r{$requisites[$i]} = 1;
-#    }
-
-
-    # Evaluate each blacklist item.
-    foreach my $item ($blacklist->getChildrenByTagName("item")) {
-        my $itemId = $item->getAttributeNode("id")->getValue;
-#        print "  CHECKING FOR $itemId\n";
-
-        my $condition = ($item->getChildrenByTagName("condition"))[0];
-        die unless $condition;
-
-        # Evaluate the condition.
-        my @elems = getElemNodes $condition;
-        if (evalOr({$deriver => 1}, \@elems)) {
-            # Oops, condition triggered.
-            my $reason = ($item->getChildrenByTagName("reason"))[0]->getChildNodes->to_literal;
-            $reason =~ s/\s+/ /g;
-            $reason =~ s/^\s+//g;
-
-            print "    VULNERABLE TO `$itemId': $reason\n";
-        }
-    }
-}
-
--- a/bootstrap.sh
+++ b/bootstrap.sh
@@ -1,8 +1,4 @@
 #! /bin/sh -e
 rm -f aclocal.m4
 mkdir -p config
-libtoolize --copy
-aclocal
-autoheader
-automake --add-missing --copy
-autoconf
+exec autoreconf -vfi
--- a/config/config.guess
+++ b/config/config.guess
--- a/config/config.sub
+++ b/config/config.sub
--- a/config/install-sh
+++ b/config/install-sh
@@ -0,0 +1,527 @@
+#!/bin/sh
+# install - install a program, script, or datafile
+
+scriptversion=2011-11-20.07; # UTC
+
+# This originates from X11R5 (mit/util/scripts/install.sh), which was
+# later released in X11R6 (xc/config/util/install.sh) with the
+# following copyright and license.
+#
+# Copyright (C) 1994 X Consortium
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+# X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+# AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNEC-
+# TION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+# Except as contained in this notice, the name of the X Consortium shall not
+# be used in advertising or otherwise to promote the sale, use or other deal-
+# ings in this Software without prior written authorization from the X Consor-
+# tium.
+#
+#
+# FSF changes to this file are in the public domain.
+#
+# Calling this script install-sh is preferred over install.sh, to prevent
+# 'make' implicit rules from creating a file called install from it
+# when there is no Makefile.
+#
+# This script is compatible with the BSD install script, but was written
+# from scratch.
+
+nl='
+'
+IFS=" ""	$nl"
+
+# set DOITPROG to echo to test this script
+
+# Don't use :- since 4.3BSD and earlier shells don't like it.
+doit=${DOITPROG-}
+if test -z "$doit"; then
+  doit_exec=exec
+else
+  doit_exec=$doit
+fi
+
+# Put in absolute file names if you don't have them in your path;
+# or use environment vars.
+
+chgrpprog=${CHGRPPROG-chgrp}
+chmodprog=${CHMODPROG-chmod}
+chownprog=${CHOWNPROG-chown}
+cmpprog=${CMPPROG-cmp}
+cpprog=${CPPROG-cp}
+mkdirprog=${MKDIRPROG-mkdir}
+mvprog=${MVPROG-mv}
+rmprog=${RMPROG-rm}
+stripprog=${STRIPPROG-strip}
+
+posix_glob='?'
+initialize_posix_glob='
+  test "$posix_glob" != "?" || {
+    if (set -f) 2>/dev/null; then
+      posix_glob=
+    else
+      posix_glob=:
+    fi
+  }
+'
+
+posix_mkdir=
+
+# Desired mode of installed file.
+mode=0755
+
+chgrpcmd=
+chmodcmd=$chmodprog
+chowncmd=
+mvcmd=$mvprog
+rmcmd="$rmprog -f"
+stripcmd=
+
+src=
+dst=
+dir_arg=
+dst_arg=
+
+copy_on_change=false
+no_target_directory=
+
+usage="\
+Usage: $0 [OPTION]... [-T] SRCFILE DSTFILE
+   or: $0 [OPTION]... SRCFILES... DIRECTORY
+   or: $0 [OPTION]... -t DIRECTORY SRCFILES...
+   or: $0 [OPTION]... -d DIRECTORIES...
+
+In the 1st form, copy SRCFILE to DSTFILE.
+In the 2nd and 3rd, copy all SRCFILES to DIRECTORY.
+In the 4th, create DIRECTORIES.
+
+Options:
+     --help     display this help and exit.
+     --version  display version info and exit.
+
+  -c            (ignored)
+  -C            install only if different (preserve the last data modification time)
+  -d            create directories instead of installing files.
+  -g GROUP      $chgrpprog installed files to GROUP.
+  -m MODE       $chmodprog installed files to MODE.
+  -o USER       $chownprog installed files to USER.
+  -s            $stripprog installed files.
+  -t DIRECTORY  install into DIRECTORY.
+  -T            report an error if DSTFILE is a directory.
+
+Environment variables override the default commands:
+  CHGRPPROG CHMODPROG CHOWNPROG CMPPROG CPPROG MKDIRPROG MVPROG
+  RMPROG STRIPPROG
+"
+
+while test $# -ne 0; do
+  case $1 in
+    -c) ;;
+
+    -C) copy_on_change=true;;
+
+    -d) dir_arg=true;;
+
+    -g) chgrpcmd="$chgrpprog $2"
+	shift;;
+
+    --help) echo "$usage"; exit $?;;
+
+    -m) mode=$2
+	case $mode in
+	  *' '* | *'	'* | *'
+'*	  | *'*'* | *'?'* | *'['*)
+	    echo "$0: invalid mode: $mode" >&2
+	    exit 1;;
+	esac
+	shift;;
+
+    -o) chowncmd="$chownprog $2"
+	shift;;
+
+    -s) stripcmd=$stripprog;;
+
+    -t) dst_arg=$2
+	# Protect names problematic for 'test' and other utilities.
+	case $dst_arg in
+	  -* | [=\(\)!]) dst_arg=./$dst_arg;;
+	esac
+	shift;;
+
+    -T) no_target_directory=true;;
+
+    --version) echo "$0 $scriptversion"; exit $?;;
+
+    --)	shift
+	break;;
+
+    -*)	echo "$0: invalid option: $1" >&2
+	exit 1;;
+
+    *)  break;;
+  esac
+  shift
+done
+
+if test $# -ne 0 && test -z "$dir_arg$dst_arg"; then
+  # When -d is used, all remaining arguments are directories to create.
+  # When -t is used, the destination is already specified.
+  # Otherwise, the last argument is the destination.  Remove it from $@.
+  for arg
+  do
+    if test -n "$dst_arg"; then
+      # $@ is not empty: it contains at least $arg.
+      set fnord "$@" "$dst_arg"
+      shift # fnord
+    fi
+    shift # arg
+    dst_arg=$arg
+    # Protect names problematic for 'test' and other utilities.
+    case $dst_arg in
+      -* | [=\(\)!]) dst_arg=./$dst_arg;;
+    esac
+  done
+fi
+
+if test $# -eq 0; then
+  if test -z "$dir_arg"; then
+    echo "$0: no input file specified." >&2
+    exit 1
+  fi
+  # It's OK to call 'install-sh -d' without argument.
+  # This can happen when creating conditional directories.
+  exit 0
+fi
+
+if test -z "$dir_arg"; then
+  do_exit='(exit $ret); exit $ret'
+  trap "ret=129; $do_exit" 1
+  trap "ret=130; $do_exit" 2
+  trap "ret=141; $do_exit" 13
+  trap "ret=143; $do_exit" 15
+
+  # Set umask so as not to create temps with too-generous modes.
+  # However, 'strip' requires both read and write access to temps.
+  case $mode in
+    # Optimize common cases.
+    *644) cp_umask=133;;
+    *755) cp_umask=22;;
+
+    *[0-7])
+      if test -z "$stripcmd"; then
+	u_plus_rw=
+      else
+	u_plus_rw='% 200'
+      fi
+      cp_umask=`expr '(' 777 - $mode % 1000 ')' $u_plus_rw`;;
+    *)
+      if test -z "$stripcmd"; then
+	u_plus_rw=
+      else
+	u_plus_rw=,u+rw
+      fi
+      cp_umask=$mode$u_plus_rw;;
+  esac
+fi
+
+for src
+do
+  # Protect names problematic for 'test' and other utilities.
+  case $src in
+    -* | [=\(\)!]) src=./$src;;
+  esac
+
+  if test -n "$dir_arg"; then
+    dst=$src
+    dstdir=$dst
+    test -d "$dstdir"
+    dstdir_status=$?
+  else
+
+    # Waiting for this to be detected by the "$cpprog $src $dsttmp" command
+    # might cause directories to be created, which would be especially bad
+    # if $src (and thus $dsttmp) contains '*'.
+    if test ! -f "$src" && test ! -d "$src"; then
+      echo "$0: $src does not exist." >&2
+      exit 1
+    fi
+
+    if test -z "$dst_arg"; then
+      echo "$0: no destination specified." >&2
+      exit 1
+    fi
+    dst=$dst_arg
+
+    # If destination is a directory, append the input filename; won't work
+    # if double slashes aren't ignored.
+    if test -d "$dst"; then
+      if test -n "$no_target_directory"; then
+	echo "$0: $dst_arg: Is a directory" >&2
+	exit 1
+      fi
+      dstdir=$dst
+      dst=$dstdir/`basename "$src"`
+      dstdir_status=0
+    else
+      # Prefer dirname, but fall back on a substitute if dirname fails.
+      dstdir=`
+	(dirname "$dst") 2>/dev/null ||
+	expr X"$dst" : 'X\(.*[^/]\)//*[^/][^/]*/*$' \| \
+	     X"$dst" : 'X\(//\)[^/]' \| \
+	     X"$dst" : 'X\(//\)$' \| \
+	     X"$dst" : 'X\(/\)' \| . 2>/dev/null ||
+	echo X"$dst" |
+	    sed '/^X\(.*[^/]\)\/\/*[^/][^/]*\/*$/{
+		   s//\1/
+		   q
+		 }
+		 /^X\(\/\/\)[^/].*/{
+		   s//\1/
+		   q
+		 }
+		 /^X\(\/\/\)$/{
+		   s//\1/
+		   q
+		 }
+		 /^X\(\/\).*/{
+		   s//\1/
+		   q
+		 }
+		 s/.*/./; q'
+      `
+
+      test -d "$dstdir"
+      dstdir_status=$?
+    fi
+  fi
+
+  obsolete_mkdir_used=false
+
+  if test $dstdir_status != 0; then
+    case $posix_mkdir in
+      '')
+	# Create intermediate dirs using mode 755 as modified by the umask.
+	# This is like FreeBSD 'install' as of 1997-10-28.
+	umask=`umask`
+	case $stripcmd.$umask in
+	  # Optimize common cases.
+	  *[2367][2367]) mkdir_umask=$umask;;
+	  .*0[02][02] | .[02][02] | .[02]) mkdir_umask=22;;
+
+	  *[0-7])
+	    mkdir_umask=`expr $umask + 22 \
+	      - $umask % 100 % 40 + $umask % 20 \
+	      - $umask % 10 % 4 + $umask % 2
+	    `;;
+	  *) mkdir_umask=$umask,go-w;;
+	esac
+
+	# With -d, create the new directory with the user-specified mode.
+	# Otherwise, rely on $mkdir_umask.
+	if test -n "$dir_arg"; then
+	  mkdir_mode=-m$mode
+	else
+	  mkdir_mode=
+	fi
+
+	posix_mkdir=false
+	case $umask in
+	  *[123567][0-7][0-7])
+	    # POSIX mkdir -p sets u+wx bits regardless of umask, which
+	    # is incompatible with FreeBSD 'install' when (umask & 300) != 0.
+	    ;;
+	  *)
+	    tmpdir=${TMPDIR-/tmp}/ins$RANDOM-$$
+	    trap 'ret=$?; rmdir "$tmpdir/d" "$tmpdir" 2>/dev/null; exit $ret' 0
+
+	    if (umask $mkdir_umask &&
+		exec $mkdirprog $mkdir_mode -p -- "$tmpdir/d") >/dev/null 2>&1
+	    then
+	      if test -z "$dir_arg" || {
+		   # Check for POSIX incompatibilities with -m.
+		   # HP-UX 11.23 and IRIX 6.5 mkdir -m -p sets group- or
+		   # other-writable bit of parent directory when it shouldn't.
+		   # FreeBSD 6.1 mkdir -m -p sets mode of existing directory.
+		   ls_ld_tmpdir=`ls -ld "$tmpdir"`
+		   case $ls_ld_tmpdir in
+		     d????-?r-*) different_mode=700;;
+		     d????-?--*) different_mode=755;;
+		     *) false;;
+		   esac &&
+		   $mkdirprog -m$different_mode -p -- "$tmpdir" && {
+		     ls_ld_tmpdir_1=`ls -ld "$tmpdir"`
+		     test "$ls_ld_tmpdir" = "$ls_ld_tmpdir_1"
+		   }
+		 }
+	      then posix_mkdir=:
+	      fi
+	      rmdir "$tmpdir/d" "$tmpdir"
+	    else
+	      # Remove any dirs left behind by ancient mkdir implementations.
+	      rmdir ./$mkdir_mode ./-p ./-- 2>/dev/null
+	    fi
+	    trap '' 0;;
+	esac;;
+    esac
+
+    if
+      $posix_mkdir && (
+	umask $mkdir_umask &&
+	$doit_exec $mkdirprog $mkdir_mode -p -- "$dstdir"
+      )
+    then :
+    else
+
+      # The umask is ridiculous, or mkdir does not conform to POSIX,
+      # or it failed possibly due to a race condition.  Create the
+      # directory the slow way, step by step, checking for races as we go.
+
+      case $dstdir in
+	/*) prefix='/';;
+	[-=\(\)!]*) prefix='./';;
+	*)  prefix='';;
+      esac
+
+      eval "$initialize_posix_glob"
+
+      oIFS=$IFS
+      IFS=/
+      $posix_glob set -f
+      set fnord $dstdir
+      shift
+      $posix_glob set +f
+      IFS=$oIFS
+
+      prefixes=
+
+      for d
+      do
+	test X"$d" = X && continue
+
+	prefix=$prefix$d
+	if test -d "$prefix"; then
+	  prefixes=
+	else
+	  if $posix_mkdir; then
+	    (umask=$mkdir_umask &&
+	     $doit_exec $mkdirprog $mkdir_mode -p -- "$dstdir") && break
+	    # Don't fail if two instances are running concurrently.
+	    test -d "$prefix" || exit 1
+	  else
+	    case $prefix in
+	      *\'*) qprefix=`echo "$prefix" | sed "s/'/'\\\\\\\\''/g"`;;
+	      *) qprefix=$prefix;;
+	    esac
+	    prefixes="$prefixes '$qprefix'"
+	  fi
+	fi
+	prefix=$prefix/
+      done
+
+      if test -n "$prefixes"; then
+	# Don't fail if two instances are running concurrently.
+	(umask $mkdir_umask &&
+	 eval "\$doit_exec \$mkdirprog $prefixes") ||
+	  test -d "$dstdir" || exit 1
+	obsolete_mkdir_used=true
+      fi
+    fi
+  fi
+
+  if test -n "$dir_arg"; then
+    { test -z "$chowncmd" || $doit $chowncmd "$dst"; } &&
+    { test -z "$chgrpcmd" || $doit $chgrpcmd "$dst"; } &&
+    { test "$obsolete_mkdir_used$chowncmd$chgrpcmd" = false ||
+      test -z "$chmodcmd" || $doit $chmodcmd $mode "$dst"; } || exit 1
+  else
+
+    # Make a couple of temp file names in the proper directory.
+    dsttmp=$dstdir/_inst.$$_
+    rmtmp=$dstdir/_rm.$$_
+
+    # Trap to clean up those temp files at exit.
+    trap 'ret=$?; rm -f "$dsttmp" "$rmtmp" && exit $ret' 0
+
+    # Copy the file name to the temp name.
+    (umask $cp_umask && $doit_exec $cpprog "$src" "$dsttmp") &&
+
+    # and set any options; do chmod last to preserve setuid bits.
+    #
+    # If any of these fail, we abort the whole thing.  If we want to
+    # ignore errors from any of these, just make sure not to ignore
+    # errors from the above "$doit $cpprog $src $dsttmp" command.
+    #
+    { test -z "$chowncmd" || $doit $chowncmd "$dsttmp"; } &&
+    { test -z "$chgrpcmd" || $doit $chgrpcmd "$dsttmp"; } &&
+    { test -z "$stripcmd" || $doit $stripcmd "$dsttmp"; } &&
+    { test -z "$chmodcmd" || $doit $chmodcmd $mode "$dsttmp"; } &&
+
+    # If -C, don't bother to copy if it wouldn't change the file.
+    if $copy_on_change &&
+       old=`LC_ALL=C ls -dlL "$dst"	2>/dev/null` &&
+       new=`LC_ALL=C ls -dlL "$dsttmp"	2>/dev/null` &&
+
+       eval "$initialize_posix_glob" &&
+       $posix_glob set -f &&
+       set X $old && old=:$2:$4:$5:$6 &&
+       set X $new && new=:$2:$4:$5:$6 &&
+       $posix_glob set +f &&
+
+       test "$old" = "$new" &&
+       $cmpprog "$dst" "$dsttmp" >/dev/null 2>&1
+    then
+      rm -f "$dsttmp"
+    else
+      # Rename the file to the real destination.
+      $doit $mvcmd -f "$dsttmp" "$dst" 2>/dev/null ||
+
+      # The rename failed, perhaps because mv can't rename something else
+      # to itself, or perhaps because mv is so ancient that it does not
+      # support -f.
+      {
+	# Now remove or move aside any old file at destination location.
+	# We try this two ways since rm can't unlink itself on some
+	# systems and the destination file might be busy for other
+	# reasons.  In this case, the final cleanup might fail but the new
+	# file should still install successfully.
+	{
+	  test ! -f "$dst" ||
+	  $doit $rmcmd -f "$dst" 2>/dev/null ||
+	  { $doit $mvcmd -f "$dst" "$rmtmp" 2>/dev/null &&
+	    { $doit $rmcmd -f "$rmtmp" 2>/dev/null; :; }
+	  } ||
+	  { echo "$0: cannot unlink or rename $dst" >&2
+	    (exit 1); exit 1
+	  }
+	} &&
+
+	# Now rename the file to the real destination.
+	$doit $mvcmd "$dsttmp" "$dst"
+      }
+    fi || exit 1
+
+    trap '' 0
+  fi
+done
+
+# Local variables:
+# eval: (add-hook 'write-file-hooks 'time-stamp)
+# time-stamp-start: "scriptversion="
+# time-stamp-format: "%:y-%02m-%02d.%02H"
+# time-stamp-time-zone: "UTC"
+# time-stamp-end: "; # UTC"
+# End:
--- a/configure.ac
+++ b/configure.ac
@@ -1,36 +1,38 @@
-AC_INIT(nix, m4_esyscmd([echo -n $(cat ./version)$VERSION_SUFFIX]))
-AC_CONFIG_SRCDIR(README)
+AC_INIT(nix, m4_esyscmd([bash -c "echo -n $(cat ./version)$VERSION_SUFFIX"]))
+AC_CONFIG_SRCDIR(README.md)
 AC_CONFIG_AUX_DIR(config)
-AM_INIT_AUTOMAKE([dist-bzip2 foreign])
-
-AC_DEFINE_UNQUOTED(NIX_VERSION, ["$VERSION"], [Nix version.])
-
-AC_CANONICAL_HOST

+AC_PROG_SED

 # Construct a Nix system name (like "i686-linux").
+AC_CANONICAL_HOST
 AC_MSG_CHECKING([for the canonical Nix system name])
-cpu_name=$(uname -p | tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ ' 'abcdefghijklmnopqrstuvwxyz_')
-machine_name=$(uname -m | tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ ' 'abcdefghijklmnopqrstuvwxyz_')

-case $machine_name in
-    i*86)
-        machine_name=i686
-        ;;
-    x86_64)
-        machine_name=x86_64
-        ;;
-    ppc)
-        machine_name=powerpc
-        ;;
-    *)
-        if test "$cpu_name" != "unknown"; then
-            machine_name=$cpu_name
-        fi
-        ;;
-esac
+AC_ARG_WITH(system, AC_HELP_STRING([--with-system=SYSTEM],
+  [Platform identifier (e.g., `i686-linux').]),
+  [system=$withval],
+  [case "$host_cpu" in
+     i*86)
+        machine_name="i686";;
+     amd64)
+        machine_name="x86_64";;
+     armv6|armv7)
+        machine_name="${host_cpu}l";;
+     *)
+        machine_name="$host_cpu";;
+   esac

-sys_name=$(uname -s | tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ ' 'abcdefghijklmnopqrstuvwxyz_')
+   case "$host_os" in
+     linux-gnu*|linux-musl*)
+        # For backward compatibility, strip the `-gnu' part.
+        system="$machine_name-linux";;
+     *)
+        # Strip the version number from names such as `gnu0.3',
+        # `darwin10.2.0', etc.
+        system="$machine_name-`echo $host_os | "$SED" -e's/@<:@0-9.@:>@*$//g'`";;
+   esac])
+
+sys_name=$(uname -s | tr 'A-Z ' 'a-z_')

 case $sys_name in
    cygwin*)
@@ -38,9 +40,6 @@ case $sys_name in
        ;;
 esac

-AC_ARG_WITH(system, AC_HELP_STRING([--with-system=SYSTEM],
-  [Platform identifier (e.g., `i686-linux').]),
-  system=$withval, system="${machine_name}-${sys_name}")
 AC_MSG_RESULT($system)
 AC_SUBST(system)
 AC_DEFINE_UNQUOTED(SYSTEM, ["$system"], [platform identifier (`cpu-os')])
@@ -50,48 +49,20 @@ AC_DEFINE_UNQUOTED(SYSTEM, ["$system"], [platform identifier (`cpu-os')])
 test "$localstatedir" = '${prefix}/var' && localstatedir=/nix/var


-# Windows-specific stuff.  On Cygwin, dynamically linking against the
-# ATerm DLL works, except that it requires the ATerm "lib" directory
-# to be in $PATH, as Windows doesn't have anything like an RPATH
-# embedded in executable.  Since this is kind of annoying, we use
-# static libraries for now.
-if test "$sys_name" = "cygwin"; then
-    AC_DISABLE_SHARED
-    AC_ENABLE_STATIC
-fi
-
-
 # Solaris-specific stuff.
-if test "$sys_name" = "sunos"; then
+AC_STRUCT_DIRENT_D_TYPE
+if test "$sys_name" = sunos; then
    # Solaris requires -lsocket -lnsl for network functions
    LIBS="-lsocket -lnsl $LIBS"
 fi


+CFLAGS=
+CXXFLAGS=
 AC_PROG_CC
 AC_PROG_CXX
-
-# To build programs to be run in the build machine
-if test "$CC_FOR_BUILD" = ""; then
-    if test "$cross_compiling" = "yes"; then
-        AC_CHECK_PROGS(CC_FOR_BUILD, gcc cc)
-    else
-        CC_FOR_BUILD="$CC"
-    fi
-fi
-AC_SUBST([CC_FOR_BUILD])
-
-# We are going to use libtool.
-AC_DISABLE_STATIC
-AC_ENABLE_SHARED
-AC_PROG_LIBTOOL
-
-if test "$enable_shared" = yes; then
-   SUB_CONFIGURE_FLAGS="--enable-shared --disable-static"
-else
-   SUB_CONFIGURE_FLAGS="--enable-static --disable-shared"
-fi
-AC_SUBST(SUB_CONFIGURE_FLAGS)
+AC_PROG_CPP
+AX_CXX_COMPILE_STDCXX_11


 # Use 64-bit file system calls so that we can support files > 2 GiB.
@@ -110,37 +81,29 @@ static char buf[1024];]],
 AC_LANG_POP(C++)


-# Check for chroot support (requires chroot() and bind mounts).
-AC_CHECK_FUNCS([chroot])
-AC_CHECK_FUNCS([unshare])
-AC_CHECK_HEADERS([sched.h], [], [], [])
-AC_CHECK_HEADERS([sys/param.h], [], [], [])
-AC_CHECK_HEADERS([sys/mount.h], [], [],
-[#ifdef HAVE_SYS_PARAM_H
-# include <sys/param.h>
-# endif
-])
+AC_CHECK_FUNCS([statvfs pipe2])
+
+
+# Check for lutimes, optionally used for changing the mtime of
+# symlinks.
+AC_CHECK_FUNCS([lutimes])
+
+
+# Check whether the store optimiser can optimise symlinks.
+AC_MSG_CHECKING([whether it is possible to create a link to a symlink])
+ln -s bla tmp_link
+if ln tmp_link tmp_link2 2> /dev/null; then
+    AC_MSG_RESULT(yes)
+    AC_DEFINE(CAN_LINK_SYMLINK, 1, [Whether link() works on symlinks.])
+else
+    AC_MSG_RESULT(no)
+fi
+rm -f tmp_link tmp_link2


 # Check for <locale>.
 AC_LANG_PUSH(C++)
-AC_CHECK_HEADERS([locale], [], [], [])
-AC_LANG_POP(C++)
-
-
-# Check for <err.h>.
-AC_CHECK_HEADER([err.h], [], [bsddiff_compat_include="-Icompat-include"])
-AC_SUBST([bsddiff_compat_include])
-
-
-# Check whether we have the personality() syscall, which allows us to
-# do i686-linux builds on x86_64-linux machines.
-AC_CHECK_HEADERS([sys/personality.h])
-
-
-# Check for tr1/unordered_set.
-AC_LANG_PUSH(C++)
-AC_CHECK_HEADERS([tr1/unordered_set], [], [], [])
+AC_CHECK_HEADERS([locale])
 AC_LANG_POP(C++)


@@ -152,32 +115,22 @@ if test -z "$$1"; then
 fi
 ])

-NEED_PROG(curl, curl)
 NEED_PROG(bash, bash)
 NEED_PROG(patch, patch)
 AC_PATH_PROG(xmllint, xmllint, false)
 AC_PATH_PROG(xsltproc, xsltproc, false)
-AC_PATH_PROG(w3m, w3m, false)
 AC_PATH_PROG(flex, flex, false)
 AC_PATH_PROG(bison, bison, false)
-NEED_PROG(perl, perl)
 NEED_PROG(sed, sed)
 NEED_PROG(tar, tar)
+NEED_PROG(bzip2, bzip2)
+NEED_PROG(gzip, gzip)
+NEED_PROG(xz, xz)
 AC_PATH_PROG(dot, dot)
-AC_PATH_PROG(dblatex, dblatex)
-AC_PATH_PROG(gzip, gzip)
+AC_PATH_PROG(pv, pv, pv)
+AC_PATH_PROGS(brotli, brotli bro, bro)
+AC_PATH_PROG(lsof, lsof, lsof)

-AC_PATH_PROG(openssl_prog, openssl, openssl) # if not found, call openssl in $PATH
-AC_SUBST(openssl_prog)
-AC_DEFINE_UNQUOTED(OPENSSL_PATH, ["$openssl_prog"], [Path of the OpenSSL binary])
-
-# Test that Perl has the open/fork feature (Perl 5.8.0 and beyond).
-AC_MSG_CHECKING([whether Perl is recent enough])
-if ! $perl -e 'open(FOO, "-|", "true"); while (<FOO>) { print; }; close FOO or die;'; then
-    AC_MSG_RESULT(no)
-    AC_MSG_ERROR([Your Perl version is too old.  Nix requires Perl 5.8.0 or newer.])
-fi
-AC_MSG_RESULT(yes)

 NEED_PROG(cat, cat)
 NEED_PROG(tr, tr)
@@ -186,99 +139,110 @@ AC_ARG_WITH(coreutils-bin, AC_HELP_STRING([--with-coreutils-bin=PATH],
  coreutils=$withval, coreutils=$(dirname $cat))
 AC_SUBST(coreutils)

-AC_ARG_WITH(docbook-rng, AC_HELP_STRING([--with-docbook-rng=PATH],
-  [path of the DocBook RelaxNG schema]),
-  docbookrng=$withval, docbookrng=/docbook-rng-missing)
-AC_SUBST(docbookrng)
-
-AC_ARG_WITH(docbook-xsl, AC_HELP_STRING([--with-docbook-xsl=PATH],
-  [path of the DocBook XSL stylesheets]),
-  docbookxsl=$withval, docbookxsl=/docbook-xsl-missing)
-AC_SUBST(docbookxsl)
-
-AC_ARG_WITH(xml-flags, AC_HELP_STRING([--with-xml-flags=FLAGS],
-  [extra flags to be passed to xmllint and xsltproc]),
-  xmlflags=$withval, xmlflags=)
-AC_SUBST(xmlflags)

 AC_ARG_WITH(store-dir, AC_HELP_STRING([--with-store-dir=PATH],
-  [path of the Nix store]),
+  [path of the Nix store (defaults to /nix/store)]),
  storedir=$withval, storedir='/nix/store')
 AC_SUBST(storedir)

-AC_ARG_WITH(openssl, AC_HELP_STRING([--with-openssl=PATH],
-  [prefix of the OpenSSL library]),
-  openssl=$withval, openssl=)
-AM_CONDITIONAL(HAVE_OPENSSL, test -n "$openssl")
-if test -n "$openssl"; then
-  LDFLAGS="-L$openssl/lib -lcrypto $LDFLAGS"
-  CFLAGS="-I$openssl/include $CFLAGS"
-  CXXFLAGS="-I$openssl/include $CXXFLAGS"
-  AC_DEFINE(HAVE_OPENSSL, 1, [Whether to use OpenSSL.])
+
+# Look for OpenSSL, a required dependency.
+PKG_CHECK_MODULES([OPENSSL], [libcrypto], [CXXFLAGS="$OPENSSL_CFLAGS $CXXFLAGS"])
+
+
+# Look for libbz2, a required dependency.
+AC_CHECK_LIB([bz2], [BZ2_bzWriteOpen], [true],
+  [AC_MSG_ERROR([Nix requires libbz2, which is part of bzip2.  See http://www.bzip.org/.])])
+AC_CHECK_HEADERS([bzlib.h], [true],
+  [AC_MSG_ERROR([Nix requires libbz2, which is part of bzip2.  See http://www.bzip.org/.])])
+
+
+# Look for SQLite, a required dependency.
+PKG_CHECK_MODULES([SQLITE3], [sqlite3 >= 3.6.19], [CXXFLAGS="$SQLITE3_CFLAGS $CXXFLAGS"])
+
+
+# Look for libcurl, a required dependency.
+PKG_CHECK_MODULES([LIBCURL], [libcurl], [CXXFLAGS="$LIBCURL_CFLAGS $CXXFLAGS"])
+
+
+# Look for libsodium, an optional dependency.
+PKG_CHECK_MODULES([SODIUM], [libsodium],
+  [AC_DEFINE([HAVE_SODIUM], [1], [Whether to use libsodium for cryptography.])
+   CXXFLAGS="$SODIUM_CFLAGS $CXXFLAGS"
+   have_sodium=1], [have_sodium=])
+AC_SUBST(HAVE_SODIUM, [$have_sodium])
+
+
+# Look for liblzma, a required dependency.
+PKG_CHECK_MODULES([LIBLZMA], [liblzma], [CXXFLAGS="$LIBLZMA_CFLAGS $CXXFLAGS"])
+AC_CHECK_LIB([lzma], [lzma_stream_encoder_mt],
+  [AC_DEFINE([HAVE_LZMA_MT], [1], [xz multithreaded compression support])])
+
+
+# Look for libbrotli{enc,dec}, optional dependencies
+PKG_CHECK_MODULES([LIBBROTLI], [libbrotlienc libbrotlidec],
+  [AC_DEFINE([HAVE_BROTLI], [1], [Whether to use libbrotli.])
+   CXXFLAGS="$LIBBROTLI_CFLAGS $CXXFLAGS"]
+   have_brotli=1], [have_brotli=])
+AC_SUBST(HAVE_BROTLI, [$have_brotli])
+
+# Look for libseccomp, required for Linux sandboxing.
+if test "$sys_name" = linux; then
+  AC_ARG_ENABLE([seccomp-sandboxing],
+                AC_HELP_STRING([--disable-seccomp-sandboxing],
+                               [Don't build support for seccomp sandboxing (only recommended if your arch doesn't support libseccomp yet!)]
+                              ))
+  if test "x$enable_seccomp_sandboxing" != "xno"; then
+    PKG_CHECK_MODULES([LIBSECCOMP], [libseccomp],
+                      [CXXFLAGS="$LIBSECCOMP_CFLAGS $CXXFLAGS"])
+    have_seccomp=1
+    AC_DEFINE([HAVE_SECCOMP], [1], [Whether seccomp is available and should be used for sandboxing.])
+  else
+    have_seccomp=
+  fi
+else
+  have_seccomp=
+fi
+AC_SUBST(HAVE_SECCOMP, [$have_seccomp])
+
+
+# Look for aws-cpp-sdk-s3.
+AC_LANG_PUSH(C++)
+AC_CHECK_HEADERS([aws/s3/S3Client.h],
+  [AC_DEFINE([ENABLE_S3], [1], [Whether to enable S3 support via aws-sdk-cpp.])
+  enable_s3=1], [enable_s3=])
+AC_SUBST(ENABLE_S3, [$enable_s3])
+AC_LANG_POP(C++)
+
+if test -n "$enable_s3"; then
+  declare -a aws_version_tokens=($(printf '#include <aws/core/VersionConfig.h>\nAWS_SDK_VERSION_STRING' | $CPP - | grep -v '^#.*' | sed 's/"//g' | tr '.' ' '))
+  AC_DEFINE_UNQUOTED([AWS_VERSION_MAJOR], ${aws_version_tokens@<:@0@:>@}, [Major version of aws-sdk-cpp.])
+  AC_DEFINE_UNQUOTED([AWS_VERSION_MINOR], ${aws_version_tokens@<:@1@:>@}, [Minor version of aws-sdk-cpp.])
 fi

-AC_ARG_WITH(bzip2, AC_HELP_STRING([--with-bzip2=PATH],
-  [prefix of bzip2]),
-  bzip2=$withval, bzip2=)
-AM_CONDITIONAL(HAVE_BZIP2, test -n "$bzip2")
-ATERM_VERSION=2.5
-AC_SUBST(ATERM_VERSION)
-if test -z "$bzip2"; then
-  # Headers and libraries will be used from the temporary installation
-  # in externals/inst-bzip2.
-  bzip2_lib='-L${top_builddir}/externals/inst-bzip2/lib -lbz2'
-  bzip2_include='-I${top_builddir}/externals/inst-bzip2/include'
-  # The binary will be copied to $libexecdir.
-  bzip2_bin='${libexecdir}/nix'
-  # But for testing, we have to use the temporary copy :-(
-  bzip2_bin_test='${top_builddir}/externals/inst-bzip2/bin'
-else
-  bzip2_lib="-L$bzip2/lib -lbz2"
-  bzip2_include="-I$bzip2/include"
-  bzip2_bin="$bzip2/bin"
-  bzip2_bin_test="$bzip2/bin"
-fi
-AC_SUBST(bzip2_lib)
-AC_SUBST(bzip2_include)
-AC_SUBST(bzip2_bin)
-AC_SUBST(bzip2_bin_test)
-
-AC_ARG_WITH(sqlite, AC_HELP_STRING([--with-sqlite=PATH],
-  [prefix of SQLite]),
-  sqlite=$withval, sqlite=)
-AM_CONDITIONAL(HAVE_SQLITE, test -n "$sqlite")
-SQLITE_VERSION=3070500
-AC_SUBST(SQLITE_VERSION)
-if test -z "$sqlite"; then
-  sqlite_lib='${top_builddir}/externals/sqlite-autoconf-$(SQLITE_VERSION)/libsqlite3.la'
-  sqlite_include='-I${top_builddir}/externals/sqlite-autoconf-$(SQLITE_VERSION)'
-  sqlite_bin='${top_builddir}/externals/sqlite-autoconf-$(SQLITE_VERSION)'
-else
-  sqlite_lib="-L$sqlite/lib -lsqlite3"
-  sqlite_include="-I$sqlite/include"
-  sqlite_bin="$sqlite/bin"
-fi
-AC_SUBST(sqlite_lib)
-AC_SUBST(sqlite_include)
-AC_SUBST(sqlite_bin)

 # Whether to use the Boehm garbage collector.
 AC_ARG_ENABLE(gc, AC_HELP_STRING([--enable-gc],
-  [enable garbage collection in the Nix expression evaluator (requires Boehm GC)]),
-  gc=$enableval, gc=)
-if test -n "$gc"; then
+  [enable garbage collection in the Nix expression evaluator (requires Boehm GC) [default=no]]),
+  gc=$enableval, gc=no)
+if test "$gc" = yes; then
  PKG_CHECK_MODULES([BDW_GC], [bdw-gc])
-  boehmgc_lib="-L$boehmgc/lib -lgc"
  CXXFLAGS="$BDW_GC_CFLAGS $CXXFLAGS"
  AC_DEFINE(HAVE_BOEHMGC, 1, [Whether to use the Boehm garbage collector.])
 fi
-AC_SUBST(boehmgc_lib)


 AC_ARG_ENABLE(init-state, AC_HELP_STRING([--disable-init-state],
  [do not initialise DB etc. in `make install']),
  init_state=$enableval, init_state=yes)
-AM_CONDITIONAL(INIT_STATE, test "$init_state" = "yes")
+#AM_CONDITIONAL(INIT_STATE, test "$init_state" = "yes")
+
+
+# documentation generation switch
+AC_ARG_ENABLE(doc-gen, AC_HELP_STRING([--disable-doc-gen],
+  [disable documentation generation]),
+  doc_generate=$enableval, doc_generate=yes)
+AC_SUBST(doc_generate)


 # Setuid installations.
@@ -286,44 +250,49 @@ AC_CHECK_FUNCS([setresuid setreuid lchown])


 # Nice to have, but not essential.
-AC_CHECK_FUNCS([strsignal posix_fallocate nanosleep])
+AC_CHECK_FUNCS([strsignal posix_fallocate sysconf])


-# This is needed if ATerm or bzip2 are static libraries,
-# and the Nix libraries are dynamic.
+# This is needed if bzip2 is a static library, and the Nix libraries
+# are dynamic.
 if test "$(uname)" = "Darwin"; then
    LDFLAGS="-all_load $LDFLAGS"
 fi


-AM_CONFIG_HEADER([config.h])
-AC_CONFIG_FILES([Makefile
-   externals/Makefile
-   src/Makefile
-   src/bin2c/Makefile
-   src/boost/Makefile
-   src/boost/format/Makefile
-   src/libutil/Makefile
-   src/libstore/Makefile
-   src/libmain/Makefile
-   src/nix-store/Makefile
-   src/nix-hash/Makefile
-   src/libexpr/Makefile
-   src/nix-instantiate/Makefile
-   src/nix-env/Makefile
-   src/nix-worker/Makefile
-   src/nix-setuid-helper/Makefile
-   src/nix-log2xml/Makefile
-   src/bsdiff-4.3/Makefile
-   scripts/Makefile
-   corepkgs/Makefile
-   corepkgs/nar/Makefile
-   corepkgs/buildenv/Makefile
-   corepkgs/channels/Makefile
-   doc/Makefile
-   doc/manual/Makefile
-   misc/Makefile
-   misc/emacs/Makefile
-   tests/Makefile
-  ])
+# Figure out the extension of dynamic libraries.
+eval dynlib_suffix=$shrext_cmds
+AC_SUBST(dynlib_suffix)
+
+
+# Do we have GNU tar?
+AC_MSG_CHECKING([if you have a recent GNU tar])
+if $tar --version 2> /dev/null | grep -q GNU && tar cvf /dev/null --warning=no-timestamp ./config.log > /dev/null; then
+    AC_MSG_RESULT(yes)
+    tarFlags="--warning=no-timestamp"
+else
+    AC_MSG_RESULT(no)
+fi
+AC_SUBST(tarFlags)
+
+
+AC_ARG_WITH(sandbox-shell, AC_HELP_STRING([--with-sandbox-shell=PATH],
+  [path of a statically-linked shell to use as /bin/sh in sandboxes]),
+  sandbox_shell=$withval)
+AC_SUBST(sandbox_shell)
+
+
+# Expand all variables in config.status.
+test "$prefix" = NONE && prefix=$ac_default_prefix
+test "$exec_prefix" = NONE && exec_prefix='${prefix}'
+for name in $ac_subst_vars; do
+    declare $name="$(eval echo "${!name}")"
+    declare $name="$(eval echo "${!name}")"
+    declare $name="$(eval echo "${!name}")"
+done
+
+rm -f Makefile.config
+
+AC_CONFIG_HEADER([config.h])
+AC_CONFIG_FILES([])
 AC_OUTPUT
--- a/corepkgs/Makefile.am
+++ b/corepkgs/Makefile.am
@@ -1 +0,0 @@
-SUBDIRS = nar buildenv channels
--- a/corepkgs/buildenv.nix
+++ b/corepkgs/buildenv.nix
@@ -0,0 +1,44 @@
+with import <nix/config.nix>;
+
+{ derivations, manifest }:
+
+derivation {
+  name = "user-environment";
+  system = builtins.currentSystem;
+  builder = nixLibexecDir + "/nix/buildenv";
+
+  inherit manifest;
+
+  # !!! grmbl, need structured data for passing this in a clean way.
+  derivations =
+    map (d:
+      [ (d.meta.active or "true")
+        (d.meta.priority or 5)
+        (builtins.length d.outputs)
+      ] ++ map (output: builtins.getAttr output d) d.outputs)
+      derivations;
+
+  # Building user environments remotely just causes huge amounts of
+  # network traffic, so don't do that.
+  preferLocalBuild = true;
+
+  # Also don't bother substituting.
+  allowSubstitutes = false;
+
+  __sandboxProfile = ''
+    (allow sysctl-read)
+    (allow file-read*
+           (literal "/usr/lib/libSystem.dylib")
+           (literal "/usr/lib/libSystem.B.dylib")
+           (literal "/usr/lib/libobjc.A.dylib")
+           (literal "/usr/lib/libobjc.dylib")
+           (literal "/usr/lib/libauto.dylib")
+           (literal "/usr/lib/libc++abi.dylib")
+           (literal "/usr/lib/libc++.1.dylib")
+           (literal "/usr/lib/libDiagnosticMessagesClient.dylib")
+           (subpath "/usr/lib/system")
+           (subpath "/dev"))
+  '';
+
+  inherit chrootDeps;
+}
--- a/corepkgs/buildenv/Makefile.am
+++ b/corepkgs/buildenv/Makefile.am
@@ -1,11 +0,0 @@
-all-local: builder.pl
-
-install-exec-local:
-	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs
-	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs/buildenv
-	$(INSTALL_DATA) $(srcdir)/default.nix $(DESTDIR)$(datadir)/nix/corepkgs/buildenv
-	$(INSTALL_PROGRAM) builder.pl $(DESTDIR)$(datadir)/nix/corepkgs/buildenv
-
-include ../../substitute.mk
-
-EXTRA_DIST = default.nix builder.pl.in
--- a/corepkgs/buildenv/builder.pl.in
+++ b/corepkgs/buildenv/builder.pl.in
@@ -1,171 +0,0 @@
-#! @perl@ -w
-
-use strict;
-use Cwd;
-use IO::Handle;
-
-STDOUT->autoflush(1);
-
-my $out = $ENV{"out"};
-mkdir "$out", 0755 || die "error creating $out";
-
-
-my $symlinks = 0;
-
-my %priorities;
-
-
-# For each activated package, create symlinks.
-
-sub createLinks {
-    my $srcDir = shift;
-    my $dstDir = shift;
-    my $priority = shift;
-
-    my @srcFiles = glob("$srcDir/*");
-
-    foreach my $srcFile (@srcFiles) {
-        my $baseName = $srcFile;
-        $baseName =~ s/^.*\///g; # strip directory
-        my $dstFile = "$dstDir/$baseName";
-
-        # The files below are special-cased so that they don't show up
-        # in user profiles, either because they are useless, or
-        # because they would cause pointless collisions (e.g., each
-        # Python package brings its own
-        # `$out/lib/pythonX.Y/site-packages/easy-install.pth'.)
-        # Urgh, hacky...
-        if ($srcFile =~ /\/propagated-build-inputs$/ ||
-            $srcFile =~ /\/nix-support$/ ||
-            $srcFile =~ /\/perllocal.pod$/ ||
-            $srcFile =~ /\/easy-install.pth$/ ||
-            $srcFile =~ /\/site.py$/ ||
-            $srcFile =~ /\/site.pyc$/ ||
-            $srcFile =~ /\/info\/dir$/ ||
-            $srcFile =~ /\/log$/)
-        {
-            # Do nothing.
-	}
-
-        elsif (-d $srcFile) {
-
-            lstat $dstFile;
-            
-            if (-d _) {
-                createLinks($srcFile, $dstFile, $priority);
-            }
-
-            elsif (-l _) {
-                my $target = readlink $dstFile or die;
-                if (!-d $target) {
-                    die "collission between directory `$srcFile' and non-directory `$target'";
-                }
-                unlink $dstFile or die "error unlinking `$dstFile': $!";
-                mkdir $dstFile, 0755 || 
-                    die "error creating directory `$dstFile': $!";
-                createLinks($target, $dstFile, $priorities{$dstFile});
-                createLinks($srcFile, $dstFile, $priority);
-            }
-
-            else {
-                symlink($srcFile, $dstFile) ||
-                    die "error creating link `$dstFile': $!";
-                $priorities{$dstFile} = $priority;
-                $symlinks++;
-            }
-        }
-
-        else {
-
-            if (-l $dstFile) {
-                my $target = readlink $dstFile;
-                my $prevPriority = $priorities{$dstFile};
-                die ( "Collission between `$srcFile' and `$target'. "
-                    . "Suggested solution: use `nix-env --set-flag "
-                    . "priority NUMBER PKGNAME' to change the priority of "
-                    . "one of the conflicting packages.\n" )
-                    if $prevPriority == $priority;
-                next if $prevPriority < $priority;
-                unlink $dstFile or die;
-            }
-            
-            symlink($srcFile, $dstFile) ||
-                die "error creating link `$dstFile': $!";
-            $priorities{$dstFile} = $priority;
-            $symlinks++;
-        }
-    }
-}
-
-
-my %done;
-my %postponed;
-
-sub addPkg;
-sub addPkg {
-    my $pkgDir = shift;
-    my $priority = shift;
-
-    return if (defined $done{$pkgDir});
-    $done{$pkgDir} = 1;
-
-#    print "symlinking $pkgDir\n";
-    createLinks("$pkgDir", "$out", $priority);
-
-    my $propagatedFN = "$pkgDir/nix-support/propagated-user-env-packages";
-    if (-e $propagatedFN) {
-        open PROP, "<$propagatedFN" or die;
-        my $propagated = <PROP>;
-        close PROP;
-        my @propagated = split ' ', $propagated;
-        foreach my $p (@propagated) {
-            $postponed{$p} = 1 unless defined $done{$p};
-        }
-    }
-}
-
-
-# Convert the stuff we get from the environment back into a coherent
-# data type.
-my @paths = split ' ', $ENV{"paths"};
-my @active = split ' ', $ENV{"active"};
-my @priority = split ' ', $ENV{"priority"};
-
-die if scalar @paths != scalar @active;
-die if scalar @paths != scalar @priority;
-
-my %pkgs;
-
-for (my $n = 0; $n < scalar @paths; $n++) {
-    $pkgs{$paths[$n]} =
-        { active => $active[$n]
-        , priority => $priority[$n] };
-}
-
-
-# Symlink to the packages that have been installed explicitly by the
-# user.
-foreach my $pkg (sort (keys %pkgs)) {
-    #print $pkg, " ", $pkgs{$pkg}->{priority}, "\n";
-    addPkg($pkg, $pkgs{$pkg}->{priority}) if $pkgs{$pkg}->{active} ne "false";
-}
-
-
-# Symlink to the packages that have been "propagated" by packages
-# installed by the user (i.e., package X declares that it want Y
-# installed as well).  We do these later because they have a lower
-# priority in case of collisions.
-my $priorityCounter = 1000; # don't care about collisions
-while (scalar(keys %postponed) > 0) {
-    my @pkgDirs = keys %postponed;
-    %postponed = ();
-    foreach my $pkgDir (sort @pkgDirs) {
-        addPkg($pkgDir, $priorityCounter++);
-    }
-}
-
-
-print STDERR "created $symlinks symlinks in user environment\n";
-
-
-symlink($ENV{"manifest"}, "$out/manifest.nix") or die "cannot create manifest";
--- a/corepkgs/buildenv/default.nix
+++ b/corepkgs/buildenv/default.nix
@@ -1,18 +0,0 @@
-{system, derivations, manifest}:
-
-derivation { 
-  name = "user-environment";
-  system = system;
-  builder = ./builder.pl;
-  
-  manifest = manifest;
-
-  # !!! grmbl, need structured data for passing this in a clean way.
-  paths = derivations;
-  active = map (x: if x ? meta && x.meta ? active then x.meta.active else "true") derivations;
-  priority = map (x: if x ? meta && x.meta ? priority then x.meta.priority else "5") derivations;
-
-  # Building user environments remotely just causes huge amounts of
-  # network traffic, so don't do that.
-  preferLocalBuild = true;
-}
--- a/corepkgs/channels/Makefile.am
+++ b/corepkgs/channels/Makefile.am
@@ -1,11 +0,0 @@
-all-local: unpack.sh
-
-install-exec-local:
-	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs
-	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs/channels
-	$(INSTALL_DATA) $(srcdir)/unpack.nix $(DESTDIR)$(datadir)/nix/corepkgs/channels
-	$(INSTALL_PROGRAM) unpack.sh $(DESTDIR)$(datadir)/nix/corepkgs/channels
-
-include ../../substitute.mk
-
-EXTRA_DIST = unpack.nix unpack.sh.in
--- a/corepkgs/channels/unpack.nix
+++ b/corepkgs/channels/unpack.nix
@@ -1,7 +0,0 @@
-{system, inputs}:
-
-derivation {
-  name = "channels";
-  builder = ./unpack.sh;
-  inherit system inputs;
-}
--- a/corepkgs/channels/unpack.sh.in
+++ b/corepkgs/channels/unpack.sh.in
@@ -1,35 +0,0 @@
-#! @shell@ -e
-
-# Cygwin compatibility hack: bunzip2 expects cygwin.dll in $PATH.
-export PATH=@coreutils@
-
-@coreutils@/mkdir $out
-@coreutils@/mkdir $out/tmp
-cd $out/tmp
-
-inputs=($inputs)
-for ((n = 0; n < ${#inputs[*]}; n += 2)); do
-    channelName=${inputs[n]}
-    channelTarball=${inputs[n+1]}
-    
-    echo "unpacking channel $channelName"
-    
-    @bunzip2@ < $channelTarball | @tar@ xf -
-
-    if test -e */channel-name; then
-        channelName="$(@coreutils@/cat */channel-name)"
-    fi
-
-    nr=1
-    attrName=$(echo $channelName | @tr@ -- '- ' '__')
-    dirName=$attrName
-    while test -e ../$dirName; do
-        nr=$((nr+1))
-        dirName=$attrName-$nr
-    done
-
-    @coreutils@/mv * ../$dirName # !!! hacky
-done
-
-cd ..
-@coreutils@/rmdir tmp
--- a/corepkgs/config.nix.in
+++ b/corepkgs/config.nix.in
@@ -0,0 +1,29 @@
+let
+  fromEnv = var: def:
+    let val = builtins.getEnv var; in
+    if val != "" then val else def;
+in rec {
+  shell = "@bash@";
+  coreutils = "@coreutils@";
+  bzip2 = "@bzip2@";
+  gzip = "@gzip@";
+  xz = "@xz@";
+  tar = "@tar@";
+  tarFlags = "@tarFlags@";
+  tr = "@tr@";
+  nixBinDir = fromEnv "NIX_BIN_DIR" "@bindir@";
+  nixPrefix = "@prefix@";
+  nixLibexecDir = fromEnv "NIX_LIBEXEC_DIR" "@libexecdir@";
+  nixLocalstateDir = "@localstatedir@";
+  nixSysconfDir = "@sysconfdir@";
+  nixStoreDir = fromEnv "NIX_STORE_DIR" "@storedir@";
+
+  # If Nix is installed in the Nix store, then automatically add it as
+  # a dependency to the core packages. This ensures that they work
+  # properly in a chroot.
+  chrootDeps =
+    if dirOf nixPrefix == builtins.storeDir then
+      [ (builtins.storePath nixPrefix) ]
+    else
+      [ ];
+}
--- a/corepkgs/derivation.nix
+++ b/corepkgs/derivation.nix
@@ -0,0 +1,27 @@
+/* This is the implementation of the ‘derivation’ builtin function.
+   It's actually a wrapper around the ‘derivationStrict’ primop. */
+
+drvAttrs @ { outputs ? [ "out" ], ... }:
+
+let
+
+  strict = derivationStrict drvAttrs;
+
+  commonAttrs = drvAttrs // (builtins.listToAttrs outputsList) //
+    { all = map (x: x.value) outputsList;
+      inherit drvAttrs;
+    };
+
+  outputToAttrListElement = outputName:
+    { name = outputName;
+      value = commonAttrs // {
+        outPath = builtins.getAttr outputName strict;
+        drvPath = strict.drvPath;
+        type = "derivation";
+        inherit outputName;
+      };
+    };
+
+  outputsList = map outputToAttrListElement outputs;
+
+in (builtins.head outputsList).value
--- a/corepkgs/fetchurl.nix
+++ b/corepkgs/fetchurl.nix
@@ -0,0 +1,37 @@
+{ system ? "" # obsolete
+, url
+, md5 ? "", sha1 ? "", sha256 ? "", sha512 ? ""
+, outputHash ?
+    if sha512 != "" then sha512 else if sha1 != "" then sha1 else if md5 != "" then md5 else sha256
+, outputHashAlgo ?
+    if sha512 != "" then "sha512" else if sha1 != "" then "sha1" else if md5 != "" then "md5" else "sha256"
+, executable ? false
+, unpack ? false
+, name ? baseNameOf (toString url)
+}:
+
+derivation {
+  builder = "builtin:fetchurl";
+
+  # New-style output content requirements.
+  inherit outputHashAlgo outputHash;
+  outputHashMode = if unpack || executable then "recursive" else "flat";
+
+  inherit name url executable unpack;
+
+  system = "builtin";
+
+  # No need to double the amount of network traffic
+  preferLocalBuild = true;
+
+  impureEnvVars = [
+    # We borrow these environment variables from the caller to allow
+    # easy proxy configuration.  This is impure, but a fixed-output
+    # derivation like fetchurl is allowed to do so since its result is
+    # by definition pure.
+    "http_proxy" "https_proxy" "ftp_proxy" "all_proxy" "no_proxy"
+  ];
+
+  # To make "nix-prefetch-url" work.
+  urls = [ url ];
+}
--- a/corepkgs/imported-drv-to-derivation.nix
+++ b/corepkgs/imported-drv-to-derivation.nix
@@ -0,0 +1,21 @@
+attrs @ { drvPath, outputs, name, ... }:
+
+let
+
+  commonAttrs = (builtins.listToAttrs outputsList) //
+    { all = map (x: x.value) outputsList;
+      inherit drvPath name;
+      type = "derivation";
+    };
+
+  outputToAttrListElement = outputName:
+    { name = outputName;
+      value = commonAttrs // {
+        outPath = builtins.getAttr outputName attrs;
+        inherit outputName;
+      };
+    };
+    
+  outputsList = map outputToAttrListElement outputs;
+    
+in (builtins.head outputsList).value
--- a/corepkgs/local.mk
+++ b/corepkgs/local.mk
@@ -0,0 +1,5 @@
+corepkgs_FILES = buildenv.nix unpack-channel.nix derivation.nix fetchurl.nix imported-drv-to-derivation.nix
+
+$(foreach file,config.nix $(corepkgs_FILES),$(eval $(call install-data-in,$(d)/$(file),$(datadir)/nix/corepkgs)))
+
+template-files += $(d)/config.nix
--- a/corepkgs/nar/Makefile.am
+++ b/corepkgs/nar/Makefile.am
@@ -1,11 +0,0 @@
-all-local: nar.sh
-
-install-exec-local:
-	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs
-	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs/nar
-	$(INSTALL_DATA) $(srcdir)/nar.nix $(DESTDIR)$(datadir)/nix/corepkgs/nar
-	$(INSTALL_PROGRAM) nar.sh $(DESTDIR)$(datadir)/nix/corepkgs/nar
-
-include ../../substitute.mk
-
-EXTRA_DIST = nar.nix nar.sh.in
--- a/corepkgs/nar/nar.nix
+++ b/corepkgs/nar/nar.nix
@@ -1,7 +0,0 @@
-{system, storePath, hashAlgo}: 
-
-derivation {
-  name = "nar";
-  builder = ./nar.sh;
-  inherit system storePath hashAlgo;
-}
--- a/corepkgs/nar/nar.sh.in
+++ b/corepkgs/nar/nar.sh.in
@@ -1,12 +0,0 @@
-#! @shell@ -e
-
-echo "packing $storePath into $out..."
-@coreutils@/mkdir $out
-dst=$out/tmp.nar.bz2
-@bindir@/nix-store --dump "$storePath" > tmp
-
-@bzip2@ < tmp > $dst
-
-@bindir@/nix-hash --flat --type $hashAlgo --base32 $dst > $out/narbz2-hash
-
-@coreutils@/mv $out/tmp.nar.bz2 $out/$(@coreutils@/cat $out/narbz2-hash).nar.bz2
--- a/corepkgs/unpack-channel.nix
+++ b/corepkgs/unpack-channel.nix
@@ -0,0 +1,43 @@
+with import <nix/config.nix>;
+
+let
+
+  builder = builtins.toFile "unpack-channel.sh"
+    ''
+      mkdir $out
+      cd $out
+      xzpat="\.xz\$"
+      gzpat="\.gz\$"
+      if [[ "$src" =~ $xzpat ]]; then
+        ${xz} -d < $src | ${tar} xf - ${tarFlags}
+      elif [[ "$src" =~ $gzpat ]]; then
+        ${gzip} -d < $src | ${tar} xf - ${tarFlags}
+      else
+        ${bzip2} -d < $src | ${tar} xf - ${tarFlags}
+      fi
+      if [ * != $channelName ]; then
+        mv * $out/$channelName
+      fi
+      if [ -n "$binaryCacheURL" ]; then
+        mkdir $out/binary-caches
+        echo -n "$binaryCacheURL" > $out/binary-caches/$channelName
+      fi
+    '';
+
+in
+
+{ name, channelName, src, binaryCacheURL ? "" }:
+
+derivation {
+  system = builtins.currentSystem;
+  builder = shell;
+  args = [ "-e" builder ];
+  inherit name channelName src binaryCacheURL;
+
+  PATH = "${nixBinDir}:${coreutils}";
+
+  # No point in doing this remotely.
+  preferLocalBuild = true;
+
+  inherit chrootDeps;
+}
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1 +0,0 @@
-SUBDIRS = manual
--- a/doc/dev/release-procedures.txt
+++ b/doc/dev/release-procedures.txt
@@ -1,33 +0,0 @@
-To produce a `stable' release from the trunk:
-
-1. Update the release notes; make sure that the release date is
-    correct.
-
-0. Make sure that the trunk builds in the release supervisor.
-
-1. Branch the trunk, e.g., `svn cp .../trunk
-   .../branches/0.5-release'.
-
-2. Switch to the branch, e.g., `svn switch .../branches/0.5-release'.
-
-3. In `configure.ac', change `STABLE=0' into `STABLE=1' and commit.
-
-4. In the release supervisor, add a one-time job to build
-   `.../branches/0.5-release'.
-
-5. Make sure that the release succeeds.
-
-6. Move the branch to a tag, e.g., `svn mv .../branches/0.5-release
-   .../tags/0.5'.
-
-   Note that the branch should not be used for maintenance; it should
-   be deleted after the release has been created.  A maintenance
-   branch (e.g., `.../branches/0.5') should be created from the
-   original revision of the trunk (since maintenance releases should
-   also be tested first; hence, we cannot have `STABLE=1').  The same
-   procedure can then be followed to produce maintenance releases;
-   just substitute `.../branches/VERSION' for the trunk.
-
-7. Switch back to the trunk.
-
-8. Bump the version number in `configure.ac' (in AC_INIT).
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -1,103 +0,0 @@
-XMLLINT = $(xmllint) $(xmlflags)
-XSLTPROC = $(xsltproc) $(xmlflags) \
- --param section.autolabel 1 \
- --param section.label.includes.component.label 1 \
- --param html.stylesheet \'style.css\' \
- --param xref.with.number.and.title 1 \
- --param toc.section.depth 3 \
- --param admon.style \'\' \
- --param callout.graphics.extension \'.gif\' \
- --param contrib.inline.enabled 0
-
-dblatex_opts = \
- -P doc.collab.show=0 \
- -P latex.output.revhistory=0
-
-# Note: we use GIF for now, since the PNGs shipped with Docbook aren't
-# transparent.
-
-man1_MANS = nix-env.1 nix-build.1 nix-store.1 nix-instantiate.1 \
- nix-collect-garbage.1 nix-push.1 nix-pull.1 \
- nix-prefetch-url.1 nix-channel.1 \
- nix-install-package.1 nix-hash.1 nix-copy-closure.1
-
-man8_MANS = nix-worker.8
-
-FIGURES = figures/user-environments.png
-
-MANUAL_SRCS = manual.xml introduction.xml installation.xml \
- package-management.xml writing-nix-expressions.xml builtins.xml \
- build-farm.xml \
- $(man1_MANS:.1=.xml) $(man8_MANS:.8=.xml) \
- troubleshooting.xml bugs.xml opt-common.xml opt-common-syn.xml \
- env-common.xml quick-start.xml nix-lang-ref.xml glossary.xml \
- conf-file.xml release-notes.xml \
- style.css images
-
-# Note: RelaxNG validation requires xmllint >= 2.7.4.
-manual.is-valid: $(MANUAL_SRCS) version.txt
-	$(XMLLINT) --noout --nonet --xinclude --noxincludenode --relaxng $(docbookrng)/docbook.rng $<
-	touch $@
-
-version.txt:
-	echo -n $(VERSION) > version.txt
-
-man $(MANS): $(MANUAL_SRCS) manual.is-valid
-	$(XSLTPROC) --nonet --xinclude $(docbookxsl)/manpages/docbook.xsl manual.xml
-
-manual.html: $(MANUAL_SRCS) manual.is-valid images
-	$(XSLTPROC) --nonet --xinclude --output manual.html \
-	  $(docbookxsl)/html/docbook.xsl manual.xml
-
-manual.pdf: $(MANUAL_SRCS) manual.is-valid images
-	if test "$(dblatex)" != ""; then \
-		$(dblatex) $(dblatex_opts) manual.xml; \
-	else \
-		echo "Please install dblatex and rerun configure."; \
-		exit 1; \
-	fi
-
-
-NEWS_OPTS = \
- --stringparam generate.toc "article nop" \
- --stringparam section.autolabel.max.depth 0 \
- --stringparam header.rule 0
-
-NEWS.html: release-notes.xml
-	$(XSLTPROC) --nonet --xinclude --output $@ $(NEWS_OPTS) \
-	  $(docbookxsl)/html/docbook.xsl release-notes.xml
-
-NEWS.txt: release-notes.xml
-	$(XSLTPROC) --nonet --xinclude quote-literals.xsl release-notes.xml | \
-	  $(XSLTPROC) --nonet --output $@.tmp.html $(NEWS_OPTS) \
-	  $(docbookxsl)/html/docbook.xsl -
-	LANG=en_US $(w3m) -dump $@.tmp.html > $@
-	rm $@.tmp.html
-
-
-all-local: manual.html NEWS.html NEWS.txt
-
-install-data-local: manual.html
-	$(INSTALL) -d $(DESTDIR)$(docdir)/manual
-	$(INSTALL_DATA) manual.html $(DESTDIR)$(docdir)/manual
-	ln -sf manual.html $(DESTDIR)$(docdir)/manual/index.html
-	$(INSTALL_DATA) style.css $(DESTDIR)$(docdir)/manual
-	cp -r images $(DESTDIR)$(docdir)/manual/images
-	$(INSTALL) -d $(DESTDIR)$(docdir)/manual/figures
-	$(INSTALL_DATA) $(FIGURES) $(DESTDIR)$(docdir)/manual/figures
-	$(INSTALL) -d $(DESTDIR)$(docdir)/release-notes
-	$(INSTALL_DATA) NEWS.html $(DESTDIR)$(docdir)/release-notes/index.html
-	$(INSTALL_DATA) style.css $(DESTDIR)$(docdir)/release-notes/
-
-images:
-	mkdir images
-#	cp $(docbookxsl)/images/*.gif images
-	mkdir images/callouts
-	cp $(docbookxsl)/images/callouts/*.gif images/callouts
-	chmod -R +w images
-
-KEEP = manual.html manual.is-valid version.txt $(MANS) NEWS.html NEWS.txt
-
-EXTRA_DIST = $(MANUAL_SRCS) $(FIGURES) $(KEEP)
-
-DISTCLEANFILES = $(KEEP)
--- a/doc/manual/advanced-topics/advanced-topics.xml
+++ b/doc/manual/advanced-topics/advanced-topics.xml
@@ -0,0 +1,10 @@
+<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">
+
+<title>Advanced Topics</title>
+
+<xi:include href="distributed-builds.xml" />
+
+</part>
--- a/doc/manual/advanced-topics/distributed-builds.xml
+++ b/doc/manual/advanced-topics/distributed-builds.xml
@@ -0,0 +1,182 @@
+<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='chap-distributed-builds'>
+
+<title>Remote Builds</title>
+
+<para>Nix supports remote builds, where a local Nix installation can
+forward Nix builds to other machines.  This allows multiple builds to
+be performed in parallel and allows Nix to perform multi-platform
+builds in a semi-transparent way.  For instance, if you perform a
+build for a <literal>x86_64-darwin</literal> on an
+<literal>i686-linux</literal> machine, Nix can automatically forward
+the build to a <literal>x86_64-darwin</literal> machine, if
+available.</para>
+
+<para>To forward a build to a remote machine, it’s required that the
+remote machine is accessible via SSH and that it has Nix
+installed. You can test whether connecting to the remote Nix instance
+works, e.g.
+
+<screen>
+$ nix ping-store --store ssh://mac
+</screen>
+
+will try to connect to the machine named <literal>mac</literal>. It is
+possible to specify an SSH identity file as part of the remote store
+URI, e.g.
+
+<screen>
+$ nix ping-store --store ssh://mac?ssh-key=/home/alice/my-key
+</screen>
+
+Since builds should be non-interactive, the key should not have a
+passphrase. Alternatively, you can load identities ahead of time into
+<command>ssh-agent</command> or <command>gpg-agent</command>.</para>
+
+<para>If you get the error
+
+<screen>
+bash: nix-store: command not found
+error: cannot connect to 'mac'
+</screen>
+
+then you need to ensure that the <envar>PATH</envar> of
+non-interactive login shells contains Nix.</para>
+
+<warning><para>If you are building via the Nix daemon, it is the Nix
+daemon user account (that is, <literal>root</literal>) that should
+have SSH access to the remote machine. If you can’t or don’t want to
+configure <literal>root</literal> to be able to access to remote
+machine, you can use a private Nix store instead by passing
+e.g. <literal>--store ~/my-nix</literal>.</para></warning>
+
+<para>The list of remote machines can be specified on the command line
+or in the Nix configuration file. The former is convenient for
+testing. For example, the following command allows you to build a
+derivation for <literal>x86_64-darwin</literal> on a Linux machine:
+
+<screen>
+$ uname
+Linux
+
+$ nix build \
+  '(with import &lt;nixpkgs> { system = "x86_64-darwin"; }; runCommand "foo" {} "uname > $out")' \
+  --builders 'ssh://mac x86_64-darwin'
+[1/0/1 built, 0.0 MiB DL] building foo on ssh://mac
+
+$ cat ./result
+Darwin
+</screen>
+
+It is possible to specify multiple builders separated by a semicolon
+or a newline, e.g.
+
+<screen>
+  --builders 'ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd'
+</screen>
+</para>
+
+<para>Each machine specification consists of the following elements,
+separated by spaces. Only the first element is required.
+
+<orderedlist>
+
+  <listitem><para>The URI of the remote store in the format
+  <literal>ssh://[<replaceable>username</replaceable>@]<replaceable>hostname</replaceable></literal>,
+  e.g. <literal>ssh://nix@mac</literal> or
+  <literal>ssh://mac</literal>. For backward compatibility,
+  <literal>ssh://</literal> may be omitted. The hostname may be an
+  alias defined in your
+  <filename>~/.ssh/config</filename>.</para></listitem>
+
+  <listitem><para>A comma-separated list of Nix platform type
+  identifiers, such as <literal>x86_64-darwin</literal>.  It is
+  possible for a machine to support multiple platform types, e.g.,
+  <literal>i686-linux,x86_64-linux</literal>. If omitted, this
+  defaults to the local platform type.</para></listitem>
+
+  <listitem><para>The SSH identity file to be used to log in to the
+  remote machine. If omitted, SSH will use its regular
+  identities.</para></listitem>
+
+  <listitem><para>The maximum number of builds that Nix will execute
+  in parallel on the machine.  Typically this should be equal to the
+  number of CPU cores.  For instance, the machine
+  <literal>itchy</literal> in the example will execute up to 8 builds
+  in parallel.</para></listitem>
+
+  <listitem><para>The “speed factor”, indicating the relative speed of
+  the machine.  If there are multiple machines of the right type, Nix
+  will prefer the fastest, taking load into account.</para></listitem>
+
+  <listitem><para>A comma-separated list of <emphasis>supported
+  features</emphasis>.  If a derivation has the
+  <varname>requiredSystemFeatures</varname> attribute, then Nix will
+  only perform the derivation on a machine that has the specified
+  features.  For instance, the attribute
+
+<programlisting>
+requiredSystemFeatures = [ "kvm" ];
+</programlisting>
+
+  will cause the build to be performed on a machine that has the
+  <literal>kvm</literal> feature.</para></listitem>
+
+  <listitem><para>A comma-separated list of <emphasis>mandatory
+  features</emphasis>.  A machine will only be used to build a
+  derivation if all of the machine’s mandatory features appear in the
+  derivation’s <varname>requiredSystemFeatures</varname>
+  attribute..</para></listitem>
+
+</orderedlist>
+
+For example, the machine specification
+
+<programlisting>
+nix@scratchy.labs.cs.uu.nl  i686-linux      /home/nix/.ssh/id_scratchy_auto        8 1 kvm
+nix@itchy.labs.cs.uu.nl     i686-linux      /home/nix/.ssh/id_scratchy_auto        8 2
+nix@poochie.labs.cs.uu.nl   i686-linux      /home/nix/.ssh/id_scratchy_auto        1 2 kvm benchmark
+</programlisting>
+
+specifies several machines that can perform
+<literal>i686-linux</literal> builds. However,
+<literal>poochie</literal> will only do builds that have the attribute
+
+<programlisting>
+requiredSystemFeatures = [ "benchmark" ];
+</programlisting>
+
+or
+
+<programlisting>
+requiredSystemFeatures = [ "benchmark" "kvm" ];
+</programlisting>
+
+<literal>itchy</literal> cannot do builds that require
+<literal>kvm</literal>, but <literal>scratchy</literal> does support
+such builds. For regular builds, <literal>itchy</literal> will be
+preferred over <literal>scratchy</literal> because it has a higher
+speed factor.</para>
+
+<para>Remote builders can also be configured in
+<filename>nix.conf</filename>, e.g.
+
+<programlisting>
+builders = ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd
+</programlisting>
+
+Finally, remote builders can be configured in a separate configuration
+file included in <option>builders</option> via the syntax
+<literal>@<replaceable>file</replaceable></literal>. For example,
+
+<programlisting>
+builders = @/etc/nix/machines
+</programlisting>
+
+causes the list of machines in <filename>/etc/nix/machines</filename>
+to be included. (This is the default.)</para>
+
+</chapter>
--- a/doc/manual/bugs.xml
+++ b/doc/manual/bugs.xml
@@ -1,39 +0,0 @@
-<appendix xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink">
-
-<title>Bugs / To-Do</title>
-
-
-<itemizedlist>
-
-<listitem><para>The man-pages generated from the DocBook documentation
-are ugly.</para></listitem>
-
-<listitem><para>Generations properly form a tree.  E.g., if after
-switching to generation 39, we perform an installation action, a
-generation 43 is created which is a descendant of 39, not 42.  So a
-rollback from 43 ought to go back to 39.  This is not currently
-implemented; generations form a linear sequence.</para></listitem>
-
-<listitem><para>For security, <command>nix-push</command> manifests
-should be digitally signed, and <command>nix-pull</command> should
-verify the signatures.  The actual NAR archives in the cache do not
-need to be signed, since the manifest contains cryptographic hashes of
-these files (and <filename>fetchurl.nix</filename> checks
-them).</para></listitem>
-
-<listitem><para>It would be useful to have an option in
-<command>nix-env --delete-generations</command> to remove non-current
-generations older than a certain age.</para></listitem>
-
-<listitem><para>There should be a flexible way to change the user
-environment builder.  Currently, you have to replace
-<filename><replaceable>prefix</replaceable>/share/nix/corepkgs/buildenv/builder.pl</filename>,
-which is hard-coded into <command>nix-env</command>.  Also, the
-default builder should be more powerful.  For instance, there should
-be some way to specify priorities to resolve
-collisions.</para></listitem>
-
-</itemizedlist>
-
-</appendix>
--- a/doc/manual/build-farm.xml
+++ b/doc/manual/build-farm.xml
@@ -1,137 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id='chap-build-farm'>
-
-<title>Setting up a Build Farm</title>
-
-
-<para>This chapter provides some sketchy information on how to set up
-a Nix-based build farm.  Nix is particularly suited as a basis for a
-build farm, since:
-
-<itemizedlist>
-
-  <listitem><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), but more in importantly, it 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></listitem>
-
-  <listitem><para>The Nix expression language is ideal for describing
-  build jobs, plus all their dependencies.  For instance, if your
-  package has some dependency, you don't have to manually install it
-  on all the machines in the build farm; they will be built
-  automatically.</para></listitem>
-
-  <listitem><para>Proper release management requires that builds (if
-  deployed) are traceable: it should be possible to figure out from
-  exactly what sources they were built, in what configuration, etc.;
-  and it should be possible to reproduce the build, if necessary.  Nix
-  makes this possible since Nix's hashing scheme uniquely identifies
-  builds, and Nix expressions are self-contained.</para></listitem>
-
-  <listitem><para>Nix will only rebuild things that have actually
-  changed.  For instance, if the sources of a package haven't changed
-  between runs of the build farm, the package won't be rebuilt (unless
-  it was garbage-collected).  Also, dependencies typically don't
-  change very often, so they only need to be built
-  once.</para></listitem>
-
-  <listitem><para>The results of a Nix build farm can be made
-  available through a channel, so successful builds can be deployed to
-  users immediately.</para></listitem>
-
-</itemizedlist>
-
-</para>
-
-
-<section><title>Overview</title>
-
-<para>TODO</para>
-
-<para>The sources of the Nix build farm are at <link
-xlink:href='https://svn.nixos.org/repos/nix/release/trunk'/>.</para>
-
-</section>
-
-
-<section xml:id='sec-distributed-builds'><title>Setting up 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
-will call whenever it wants to build a derivation.  The build hook
-(typically a shell or Perl script) can decline the build, in which Nix
-will perform it in the usual way if possible, or it can accept it, in
-which case it is responsible for somehow getting the inputs of the
-build to another machine, doing the build there, and getting the
-results back.  The details of the build hook protocol are described in
-the documentation of the <link
-linkend="envar-build-hook"><envar>NIX_BUILD_HOOK</envar>
-variable</link>.</para>
-
-<example xml:id='ex-remote-systems'><title>Remote machine configuration:
-<filename>remote-systems.conf</filename></title>
-<programlisting>
-nix@mcflurry.labs.cs.uu.nl  powerpc-darwin  /home/nix/.ssh/id_quarterpounder_auto  2
-nix@scratchy.labs.cs.uu.nl  i686-linux      /home/nix/.ssh/id_scratchy_auto        1
-</programlisting>
-</example>
-
-<para>An example build hook can be found in the Nix build farm
-sources: <link
-xlink:href='https://svn.nixos.org/repos/nix/release/trunk/common/distributed/build-remote.pl'
-/>.  It should be suitable for most purposes, with maybe some minor
-adjustments.  It uses <command>ssh</command> and
-<command>rsync</command> to copy the build inputs and outputs and
-perform the remote build.  You should define a list of available build
-machines and set the environment variable
-<envar>REMOTE_SYSTEMS</envar> to point to it.  An example
-configuration is shown in <xref linkend='ex-remote-systems' />.  Each
-line in the file specifies a machine, with the following bits of
-information:
-
-<orderedlist>
-  
-  <listitem><para>The name of the remote machine, with optionally the
-  user under which the remote build should be performed.  This is
-  actually passed as an argument to <command>ssh</command>, so it can
-  be an alias defined in your
-  <filename>~/.ssh/config</filename>.</para></listitem>
-
-  <listitem><para>The Nix platform type identifier, such as
-  <literal>powerpc-darwin</literal>.</para></listitem>
-
-  <listitem><para>The SSH private key to be used to log in to the
-  remote machine.  Since builds should be non-interactive, this key
-  should not have a passphrase!</para></listitem>
-
-  <listitem><para>The maximum <quote>load</quote> of the remote
-  machine.  This is just the maximum number of jobs that
-  <filename>build-remote.pl</filename> will execute in parallel on the
-  machine.  Typically this should be equal to the number of
-  CPUs.</para></listitem>
-
-</orderedlist>
-
-You should also set up the environment variable
-<envar>CURRENT_LOAD</envar> to point at a file that
-<filename>build-remote.pl</filename> uses to remember how many jobs it
-is currently executing remotely.  It doesn't look at the actual load
-on the remote machine, so if you have multiple instances of Nix
-running, they should use the same <envar>CURRENT_LOAD</envar>
-file<footnote><para>Although there are probably some race conditions
-in the script right now.</para></footnote>.  Maybe in the future
-<filename>build-remote.pl</filename> will look at the actual remote
-load.  The load file should exist, so you should just create it as an
-empty file initially.</para>
-  
-</section>
-
-
-</chapter>
--- a/doc/manual/command-ref/command-ref.xml
+++ 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>
--- a/doc/manual/command-ref/conf-file.xml
+++ b/doc/manual/command-ref/conf-file.xml
@@ -0,0 +1,782 @@
+<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-conf-file">
+
+<refmeta>
+  <refentrytitle>nix.conf</refentrytitle>
+  <manvolnum>5</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>nix.conf</refname>
+  <refpurpose>Nix configuration file</refpurpose>
+</refnamediv>
+
+<refsection><title>Description</title>
+
+<para>Nix reads settings from two configuration files:</para>
+
+<itemizedlist>
+
+  <listitem>
+    <para>The system-wide configuration file
+    <filename><replaceable>sysconfdir</replaceable>/nix/nix.conf</filename>
+    (i.e. <filename>/etc/nix/nix.conf</filename> on most systems), or
+    <filename>$NIX_CONF_DIR/nix.conf</filename> if
+    <envar>NIX_CONF_DIR</envar> is set.</para>
+  </listitem>
+
+  <listitem>
+    <para>The user configuration file
+    <filename>$XDG_CONFIG_HOME/nix/nix.conf</filename>, or
+    <filename>~/.config/nix/nix.conf</filename> if
+    <envar>XDG_CONFIG_HOME</envar> is not set.</para>
+  </listitem>
+
+</itemizedlist>
+
+<para>The configuration files consist of
+<literal><replaceable>name</replaceable> =
+<replaceable>value</replaceable></literal> pairs, one per line. Other
+files can be included with a line like <literal>include
+<replaceable>path</replaceable></literal>, where
+<replaceable>path</replaceable> is interpreted relative to the current
+conf file and a missing file is an error unless
+<literal>!include</literal> is used instead.
+Comments start with a <literal>#</literal> character.  Here is an
+example configuration file:</para>
+
+<programlisting>
+keep-outputs = true       # Nice for developers
+keep-derivations = true   # Idem
+</programlisting>
+
+<para>You can override settings on the command line using the
+<option>--option</option> flag, e.g. <literal>--option keep-outputs
+false</literal>.</para>
+
+<para>The following settings are currently available:
+
+<variablelist>
+
+
+  <varlistentry xml:id="conf-allowed-uris"><term><literal>allowed-uris</literal></term>
+
+    <listitem>
+
+      <para>A list of URI prefixes to which access is allowed in
+      restricted evaluation mode. For example, when set to
+      <literal>https://github.com/NixOS</literal>, builtin functions
+      such as <function>fetchGit</function> are allowed to access
+      <literal>https://github.com/NixOS/patchelf.git</literal>.</para>
+
+    </listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-allow-import-from-derivation"><term><literal>allow-import-from-derivation</literal></term>
+
+    <listitem><para>By default, Nix allows you to <function>import</function> from a derivation,
+    allowing building at evaluation time. With this option set to false, Nix will throw an error
+    when evaluating an expression that uses this feature, allowing users to ensure their evaluation
+    will not require any builds to take place.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-allow-new-privileges"><term><literal>allow-new-privileges</literal></term>
+
+    <listitem><para>(Linux-specific.) By default, builders on Linux
+    cannot acquire new privileges by calling setuid/setgid programs or
+    programs that have file capabilities. For example, programs such
+    as <command>sudo</command> or <command>ping</command> will
+    fail. (Note that in sandbox builds, no such programs are available
+    unless you bind-mount them into the sandbox via the
+    <option>sandbox-paths</option> option.) You can allow the
+    use of such programs by enabling this option. This is impure and
+    usually undesirable, but may be useful in certain scenarios
+    (e.g. to spin up containers or set up userspace network interfaces
+    in tests).</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-allowed-users"><term><literal>allowed-users</literal></term>
+
+    <listitem>
+
+      <para>A list of names of users (separated by whitespace) that
+      are allowed to connect to the Nix daemon. As with the
+      <option>trusted-users</option> option, you can specify groups by
+      prefixing them with <literal>@</literal>. Also, you can allow
+      all users by specifying <literal>*</literal>. The default is
+      <literal>*</literal>.</para>
+
+      <para>Note that trusted users are always allowed to connect.</para>
+
+    </listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>auto-optimise-store</literal></term>
+
+    <listitem><para>If set to <literal>true</literal>, Nix
+    automatically detects files in the store that have identical
+    contents, and replaces them with hard links to a single copy.
+    This saves disk space.  If set to <literal>false</literal> (the
+    default), you can still run <command>nix-store
+    --optimise</command> to get rid of duplicate
+    files.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-builders">
+    <term><literal>builders</literal></term>
+    <listitem>
+      <para>A list of machines on which to perform builds. <phrase
+      condition="manual">See <xref linkend="chap-distributed-builds"
+      /> for details.</phrase></para>
+    </listitem>
+  </varlistentry>
+
+
+  <varlistentry><term><literal>builders-use-substitutes</literal></term>
+
+    <listitem><para>If set to <literal>true</literal>, Nix will instruct
+    remote build machines to use their own binary substitutes if available. In
+    practical terms, this means that remote hosts will fetch as many build
+    dependencies as possible from their own substitutes (e.g, from
+    <literal>cache.nixos.org</literal>), instead of waiting for this host to
+    upload them all. This can drastically reduce build times if the network
+    connection between this computer and the remote build host is slow. Defaults
+    to <literal>false</literal>.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-build-users-group"><term><literal>build-users-group</literal></term>
+
+    <listitem><para>This options specifies the Unix group containing
+    the Nix build user accounts.  In multi-user Nix installations,
+    builds should not be performed by the Nix account since that would
+    allow users to arbitrarily modify the Nix store and database by
+    supplying specially crafted builders; and they cannot be performed
+    by the calling user since that would allow him/her to influence
+    the build result.</para>
+
+    <para>Therefore, if this option is non-empty and specifies a valid
+    group, builds will be performed under the user accounts that are a
+    member of the group specified here (as listed in
+    <filename>/etc/group</filename>).  Those user accounts should not
+    be used for any other purpose!</para>
+
+    <para>Nix will never run two builds under the same user account at
+    the same time.  This is to prevent an obvious security hole: a
+    malicious user writing a Nix expression that modifies the build
+    result of a legitimate Nix expression being built by another user.
+    Therefore it is good to have as many Nix build user accounts as
+    you can spare.  (Remember: uids are cheap.)</para>
+
+    <para>The build users should have permission to create files in
+    the Nix store, but not delete them.  Therefore,
+    <filename>/nix/store</filename> should be owned by the Nix
+    account, its group should be the group specified here, and its
+    mode should be <literal>1775</literal>.</para>
+
+    <para>If the build users group is empty, builds will be performed
+    under the uid of the Nix process (that is, the uid of the caller
+    if <envar>NIX_REMOTE</envar> is empty, the uid under which the Nix
+    daemon runs if <envar>NIX_REMOTE</envar> is
+    <literal>daemon</literal>).  Obviously, this should not be used in
+    multi-user settings with untrusted users.</para>
+
+    </listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>compress-build-log</literal></term>
+
+    <listitem><para>If set to <literal>true</literal> (the default),
+    build logs written to <filename>/nix/var/log/nix/drvs</filename>
+    will be compressed on the fly using bzip2.  Otherwise, they will
+    not be compressed.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-connect-timeout"><term><literal>connect-timeout</literal></term>
+
+    <listitem>
+
+      <para>The timeout (in seconds) for establishing connections in
+      the binary cache substituter.  It corresponds to
+      <command>curl</command>’s <option>--connect-timeout</option>
+      option.</para>
+
+    </listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-cores"><term><literal>cores</literal></term>
+
+    <listitem><para>Sets the value of the
+    <envar>NIX_BUILD_CORES</envar> environment variable in the
+    invocation of builders.  Builders can use this variable at their
+    discretion to control the maximum amount of parallelism.  For
+    instance, in Nixpkgs, if the derivation attribute
+    <varname>enableParallelBuilding</varname> is set to
+    <literal>true</literal>, the builder passes the
+    <option>-j<replaceable>N</replaceable></option> flag to GNU Make.
+    It can be overridden using the <option
+    linkend='opt-cores'>--cores</option> command line switch and
+    defaults to <literal>1</literal>.  The value <literal>0</literal>
+    means that the builder should use all available CPU cores in the
+    system.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-extra-sandbox-paths">
+    <term><literal>extra-sandbox-paths</literal></term>
+
+    <listitem><para>A list of additional paths appended to
+    <option>sandbox-paths</option>. Useful if you want to extend
+    its default value.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>extra-substituters</literal></term>
+
+    <listitem><para>Additional binary caches appended to those
+    specified in <option>substituters</option>.  When used by
+    unprivileged users, untrusted substituters (i.e. those not listed
+    in <option>trusted-substituters</option>) are silently
+    ignored.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>fallback</literal></term>
+
+    <listitem><para>If set to <literal>true</literal>, Nix will fall
+    back to building from source if a binary substitute fails.  This
+    is equivalent to the <option>--fallback</option> flag.  The
+    default is <literal>false</literal>.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>fsync-metadata</literal></term>
+
+    <listitem><para>If set to <literal>true</literal>, changes to the
+    Nix store metadata (in <filename>/nix/var/nix/db</filename>) are
+    synchronously flushed to disk.  This improves robustness in case
+    of system crashes, but reduces performance.  The default is
+    <literal>true</literal>.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-hashed-mirrors"><term><literal>hashed-mirrors</literal></term>
+
+    <listitem><para>A list of web servers used by
+    <function>builtins.fetchurl</function> to obtain files by
+    hash. The default is
+    <literal>http://tarballs.nixos.org/</literal>. Given a hash type
+    <replaceable>ht</replaceable> and a base-16 hash
+    <replaceable>h</replaceable>, Nix will try to download the file
+    from
+    <literal>hashed-mirror/<replaceable>ht</replaceable>/<replaceable>h</replaceable></literal>.
+    This allows files to be downloaded even if they have disappeared
+    from their original URI. For example, given the default mirror
+    <literal>http://tarballs.nixos.org/</literal>, when building the derivation
+
+<programlisting>
+builtins.fetchurl {
+  url = https://example.org/foo-1.2.3.tar.xz;
+  sha256 = "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae";
+}
+</programlisting>
+
+    Nix will attempt to download this file from
+    <literal>http://tarballs.nixos.org/sha256/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae</literal>
+    first. If it is not available there, if will try the original URI.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>http-connections</literal></term>
+
+    <listitem><para>The maximum number of parallel TCP connections
+    used to fetch files from binary caches and by other downloads. It
+    defaults to 25. 0 means no limit.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>keep-build-log</literal></term>
+
+    <listitem><para>If set to <literal>true</literal> (the default),
+    Nix will write the build log of a derivation (i.e. the standard
+    output and error of its builder) to the directory
+    <filename>/nix/var/log/nix/drvs</filename>.  The build log can be
+    retrieved using the command <command>nix-store -l
+    <replaceable>path</replaceable></command>.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-keep-derivations"><term><literal>keep-derivations</literal></term>
+
+    <listitem><para>If <literal>true</literal> (default), the garbage
+    collector will keep the derivations from which non-garbage store
+    paths were built.  If <literal>false</literal>, they will be
+    deleted unless explicitly registered as a root (or reachable from
+    other roots).</para>
+
+    <para>Keeping derivation around is useful for querying and
+    traceability (e.g., it allows you to ask with what dependencies or
+    options a store path was built), so by default this option is on.
+    Turn it off to save a bit of disk space (or a lot if
+    <literal>keep-outputs</literal> is also turned on).</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>keep-env-derivations</literal></term>
+
+    <listitem><para>If <literal>false</literal> (default), derivations
+    are not stored in Nix user environments.  That is, the derivation
+    any build-time-only dependencies may be garbage-collected.</para>
+
+    <para>If <literal>true</literal>, when you add a Nix derivation to
+    a user environment, the path of the derivation is stored in the
+    user environment.  Thus, the derivation will not be
+    garbage-collected until the user environment generation is deleted
+    (<command>nix-env --delete-generations</command>).  To prevent
+    build-time-only dependencies from being collected, you should also
+    turn on <literal>keep-outputs</literal>.</para>
+
+    <para>The difference between this option and
+    <literal>keep-derivations</literal> is that this one is
+    “sticky”: it applies to any user environment created while this
+    option was enabled, while <literal>keep-derivations</literal>
+    only applies at the moment the garbage collector is
+    run.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-keep-outputs"><term><literal>keep-outputs</literal></term>
+
+    <listitem><para>If <literal>true</literal>, the garbage collector
+    will keep the outputs of non-garbage derivations.  If
+    <literal>false</literal> (default), outputs will be deleted unless
+    they are GC roots themselves (or reachable from other roots).</para>
+
+    <para>In general, outputs must be registered as roots separately.
+    However, even if the output of a derivation is registered as a
+    root, the collector will still delete store paths that are used
+    only at build time (e.g., the C compiler, or source tarballs
+    downloaded from the network).  To prevent it from doing so, set
+    this option to <literal>true</literal>.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-max-build-log-size"><term><literal>max-build-log-size</literal></term>
+
+    <listitem>
+
+      <para>This option defines the maximum number of bytes that a
+      builder can write to its stdout/stderr.  If the builder exceeds
+      this limit, it’s killed.  A value of <literal>0</literal> (the
+      default) means that there is no limit.</para>
+
+    </listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-max-jobs"><term><literal>max-jobs</literal></term>
+
+    <listitem><para>This option defines the maximum number of jobs
+    that Nix will try to build in parallel.  The default is
+    <literal>1</literal>. The special value <literal>auto</literal>
+    causes Nix to use the number of CPUs in your system.  It can be
+    overridden using the <option
+    linkend='opt-max-jobs'>--max-jobs</option> (<option>-j</option>)
+    command line switch.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-max-silent-time"><term><literal>max-silent-time</literal></term>
+
+    <listitem>
+
+      <para>This option defines the maximum number of seconds that a
+      builder can go without producing any data on standard output or
+      standard error.  This is useful (for instance in an automated
+      build system) to catch builds that are stuck in an infinite
+      loop, or to catch remote builds that are hanging due to network
+      problems.  It can be overridden using the <option
+      linkend="opt-max-silent-time">--max-silent-time</option> command
+      line switch.</para>
+
+      <para>The value <literal>0</literal> means that there is no
+      timeout.  This is also the default.</para>
+
+    </listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>netrc-file</literal></term>
+
+    <listitem><para>If set to an absolute path to a <filename>netrc</filename>
+    file, Nix will use the HTTP authentication credentials in this file when
+    trying to download from a remote host through HTTP or HTTPS. Defaults to
+    <filename>$NIX_CONF_DIR/netrc</filename>.</para>
+
+    <para>The <filename>netrc</filename> file consists of a list of
+    accounts in the following format:
+
+<screen>
+machine <replaceable>my-machine</replaceable>
+login <replaceable>my-username</replaceable>
+password <replaceable>my-password</replaceable>
+</screen>
+
+    For the exact syntax, see <link
+    xlink:href="https://ec.haxx.se/usingcurl-netrc.html">the
+    <literal>curl</literal> documentation.</link></para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-plugin-files">
+    <term><literal>plugin-files</literal></term>
+    <listitem>
+      <para>
+        A list of plugin files to be loaded by Nix. Each of these
+        files will be dlopened by Nix, allowing them to affect
+        execution through static initialization. In particular, these
+        plugins may construct static instances of RegisterPrimOp to
+        add new primops or constants to the expression language,
+        RegisterStoreImplementation to add new store implementations,
+        RegisterCommand to add new subcommands to the
+        <literal>nix</literal> command, and RegisterSetting to add new
+        nix config settings. See the constructors for those types for
+        more details.
+      </para>
+      <para>
+        Since these files are loaded into the same address space as
+        Nix itself, they must be DSOs compatible with the instance of
+        Nix running at the time (i.e. compiled against the same
+        headers, not linked to any incompatible libraries). They
+        should not be linked to any Nix libs directly, as those will
+        be available already at load time.
+      </para>
+      <para>
+        If an entry in the list is a directory, all files in the
+        directory are loaded as plugins (non-recursively).
+      </para>
+    </listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-pre-build-hook"><term><literal>pre-build-hook</literal></term>
+
+    <listitem>
+
+
+      <para>If set, the path to a program that can set extra
+      derivation-specific settings for this system. This is used for settings
+      that can't be captured by the derivation model itself and are too variable
+      between different versions of the same system to be hard-coded into nix.
+      </para>
+
+      <para>The hook is passed the derivation path and, if sandboxes are enabled,
+      the sandbox directory. It can then modify the sandbox and send a series of
+      commands to modify various settings to stdout. The currently recognized
+      commands are:</para>
+
+      <variablelist>
+        <varlistentry xml:id="extra-sandbox-paths">
+          <term><literal>extra-sandbox-paths</literal></term>
+
+          <listitem>
+
+            <para>Pass a list of files and directories to be included in the
+            sandbox for this build. One entry per line, terminated by an empty
+            line. Entries have the same format as
+            <literal>sandbox-paths</literal>.</para>
+
+          </listitem>
+
+        </varlistentry>
+      </variablelist>
+    </listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-repeat"><term><literal>repeat</literal></term>
+
+    <listitem><para>How many times to repeat builds to check whether
+    they are deterministic. The default value is 0. If the value is
+    non-zero, every build is repeated the specified number of
+    times. If the contents of any of the runs differs from the
+    previous ones, the build is rejected and the resulting store paths
+    are not registered as “valid” in Nix’s database.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>require-sigs</literal></term>
+
+    <listitem><para>If set to <literal>true</literal> (the default),
+    any non-content-addressed path added or copied to the Nix store
+    (e.g. when substituting from a binary cache) must have a valid
+    signature, that is, be signed using one of the keys listed in
+    <option>trusted-public-keys</option> or
+    <option>secret-key-files</option>. Set to <literal>false</literal>
+    to disable signature checking.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-restrict-eval"><term><literal>restrict-eval</literal></term>
+
+    <listitem>
+
+      <para>If set to <literal>true</literal>, the Nix evaluator will
+      not allow access to any files outside of the Nix search path (as
+      set via the <envar>NIX_PATH</envar> environment variable or the
+      <option>-I</option> option), or to URIs outside of
+      <option>allowed-uri</option>. The default is
+      <literal>false</literal>.</para>
+
+    </listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>sandbox</literal></term>
+
+    <listitem><para>If set to <literal>true</literal>, builds will be
+    performed in a <emphasis>sandboxed environment</emphasis>, i.e.,
+    they’re isolated from the normal file system hierarchy and will
+    only see their dependencies in the Nix store, the temporary build
+    directory, private versions of <filename>/proc</filename>,
+    <filename>/dev</filename>, <filename>/dev/shm</filename> and
+    <filename>/dev/pts</filename> (on Linux), and the paths configured with the
+    <link linkend='conf-sandbox-paths'><literal>sandbox-paths</literal>
+    option</link>. This is useful to prevent undeclared dependencies
+    on files in directories such as <filename>/usr/bin</filename>. In
+    addition, on Linux, builds run in private PID, mount, network, IPC
+    and UTS namespaces to isolate them from other processes in the
+    system (except that fixed-output derivations do not run in private
+    network namespace to ensure they can access the network).</para>
+
+    <para>Currently, sandboxing only work on Linux and macOS. The use
+    of a sandbox requires that Nix is run as root (so you should use
+    the <link linkend='conf-build-users-group'>“build users”
+    feature</link> to perform the actual builds under different users
+    than root).</para>
+
+    <para>If this option is set to <literal>relaxed</literal>, then
+    fixed-output derivations and derivations that have the
+    <varname>__noChroot</varname> attribute set to
+    <literal>true</literal> do not run in sandboxes.</para>
+
+    <para>The default is <literal>false</literal>.</para>
+
+    </listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-sandbox-dev-shm-size"><term><literal>sandbox-dev-shm-size</literal></term>
+
+    <listitem><para>This option determines the maximum size of the
+    <literal>tmpfs</literal> filesystem mounted on
+    <filename>/dev/shm</filename> in Linux sandboxes. For the format,
+    see the description of the <option>size</option> option of
+    <literal>tmpfs</literal> in
+    <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The
+    default is <literal>50%</literal>.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-sandbox-paths">
+    <term><literal>sandbox-paths</literal></term>
+
+    <listitem><para>A list of paths bind-mounted into Nix sandbox
+    environments. You can use the syntax
+    <literal><replaceable>target</replaceable>=<replaceable>source</replaceable></literal>
+    to mount a path in a different location in the sandbox; for
+    instance, <literal>/bin=/nix-bin</literal> will mount the path
+    <literal>/nix-bin</literal> as <literal>/bin</literal> inside the
+    sandbox. If <replaceable>source</replaceable> is followed by
+    <literal>?</literal>, then it is not an error if
+    <replaceable>source</replaceable> does not exist; for example,
+    <literal>/dev/nvidiactl?</literal> specifies that
+    <filename>/dev/nvidiactl</filename> will only be mounted in the
+    sandbox if it exists in the host filesystem.</para>
+
+    <para>Depending on how Nix was built, the default value for this option
+    may be empty or provide <filename>/bin/sh</filename> as a
+    bind-mount of <command>bash</command>.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>secret-key-files</literal></term>
+
+    <listitem><para>A whitespace-separated list of files containing
+    secret (private) keys. These are used to sign locally-built
+    paths. They can be generated using <command>nix-store
+    --generate-binary-cache-key</command>. The corresponding public
+    key can be distributed to other users, who can add it to
+    <option>trusted-public-keys</option> in their
+    <filename>nix.conf</filename>.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-show-trace"><term><literal>show-trace</literal></term>
+
+    <listitem><para>Causes Nix to print out a stack trace in case of Nix
+    expression evaluation errors.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>substitute</literal></term>
+
+    <listitem><para>If set to <literal>true</literal> (default), Nix
+    will use binary substitutes if available.  This option can be
+    disabled to force building from source.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>substituters</literal></term>
+
+    <listitem><para>A list of URLs of substituters, separated by
+    whitespace.  The default is
+    <literal>https://cache.nixos.org</literal>.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>system</literal></term>
+
+    <listitem><para>This option specifies the canonical Nix system
+    name of the current installation, such as
+    <literal>i686-linux</literal> or
+    <literal>x86_64-darwin</literal>.  Nix can only build derivations
+    whose <literal>system</literal> attribute equals the value
+    specified here.  In general, it never makes sense to modify this
+    value from its default, since you can use it to ‘lie’ about the
+    platform you are building on (e.g., perform a Mac OS build on a
+    Linux machine; the result would obviously be wrong).  It only
+    makes sense if the Nix binaries can run on multiple platforms,
+    e.g., ‘universal binaries’ that run on <literal>x86_64-linux</literal> and
+    <literal>i686-linux</literal>.</para>
+
+    <para>It defaults to the canonical Nix system name detected by
+    <filename>configure</filename> at build time.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-timeout"><term><literal>timeout</literal></term>
+
+    <listitem>
+
+      <para>This option defines the maximum number of seconds that a
+      builder can run.  This is useful (for instance in an automated
+      build system) to catch builds that are stuck in an infinite loop
+      but keep writing to their standard output or standard error.  It
+      can be overridden using the <option
+      linkend="opt-timeout">--timeout</option> command line
+      switch.</para>
+
+      <para>The value <literal>0</literal> means that there is no
+      timeout.  This is also the default.</para>
+
+    </listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>trusted-public-keys</literal></term>
+
+    <listitem><para>A whitespace-separated list of public keys. When
+    paths are copied from another Nix store (such as a binary cache),
+    they must be signed with one of these keys. For example:
+    <literal>cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
+    hydra.nixos.org-1:CNHJZBh9K4tP3EKF6FkkgeVYsS3ohTl+oS0Qa8bezVs=</literal>.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>trusted-substituters</literal></term>
+
+    <listitem><para>A list of URLs of substituters, separated by
+    whitespace.  These are not used by default, but can be enabled by
+    users of the Nix daemon by specifying <literal>--option
+    substituters <replaceable>urls</replaceable></literal> on the
+    command line.  Unprivileged users are only allowed to pass a
+    subset of the URLs listed in <literal>substituters</literal> and
+    <literal>trusted-substituters</literal>.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-trusted-users"><term><literal>trusted-users</literal></term>
+
+    <listitem>
+
+      <para>A list of names of users (separated by whitespace) that
+      have additional rights when connecting to the Nix daemon, such
+      as the ability to specify additional binary caches, or to import
+      unsigned NARs. You can also specify groups by prefixing them
+      with <literal>@</literal>; for instance,
+      <literal>@wheel</literal> means all users in the
+      <literal>wheel</literal> group. The default is
+      <literal>root</literal>.</para>
+
+      <warning><para>Adding a user to <option>trusted-users</option>
+      is essentially equivalent to giving that user root access to the
+      system. For example, the user can set
+      <option>sandbox-paths</option> and thereby obtain read access to
+      directories that are otherwise inacessible to
+      them.</para></warning>
+
+    </listitem>
+
+  </varlistentry>
+
+
+</variablelist>
+
+</para>
+
+</refsection>
+
+</refentry>
--- a/doc/manual/command-ref/env-common.xml
+++ b/doc/manual/command-ref/env-common.xml
@@ -0,0 +1,196 @@
+<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>
+
+
+<para>Most Nix commands interpret the following environment variables:</para>
+
+<variablelist xml:id="env-common">
+
+<varlistentry><term><envar>IN_NIX_SHELL</envar></term>
+
+  <listitem><para>Indicator that tells if the current environment was set up by
+  <command>nix-shell</command>.</para></listitem>
+
+</varlistentry>
+
+<varlistentry xml:id="env-NIX_PATH"><term><envar>NIX_PATH</envar></term>
+
+  <listitem>
+
+    <para>A colon-separated list of directories used to look up Nix
+    expressions enclosed in angle brackets (i.e.,
+    <literal>&lt;<replaceable>path</replaceable>></literal>).  For
+    instance, the value
+
+    <screen>
+/home/eelco/Dev:/etc/nixos</screen>
+
+    will cause Nix to look for paths relative to
+    <filename>/home/eelco/Dev</filename> and
+    <filename>/etc/nixos</filename>, in that order.  It is also
+    possible to match paths against a prefix.  For example, the value
+
+    <screen>
+nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos</screen>
+
+    will cause Nix to search for
+    <literal>&lt;nixpkgs/<replaceable>path</replaceable>></literal> in
+    <filename>/home/eelco/Dev/nixpkgs-branch/<replaceable>path</replaceable></filename>
+    and
+    <filename>/etc/nixos/nixpkgs/<replaceable>path</replaceable></filename>.</para>
+
+    <para>If a path in the Nix search path starts with
+    <literal>http://</literal> or <literal>https://</literal>, it is
+    interpreted as the URL of a tarball that will be downloaded and
+    unpacked to a temporary location. The tarball must consist of a
+    single top-level directory. For example, setting
+    <envar>NIX_PATH</envar> to
+
+    <screen>
+nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz</screen>
+
+    tells Nix to download the latest revision in the Nixpkgs/NixOS
+    14.12 channel.</para>
+
+    <para>The search path can be extended using the <option
+    linkend="opt-I">-I</option> option, which takes precedence over
+    <envar>NIX_PATH</envar>.</para></listitem>
+
+</varlistentry>
+
+
+<varlistentry><term><envar>NIX_IGNORE_SYMLINK_STORE</envar></term>
+
+  <listitem>
+
+  <para>Normally, the Nix store directory (typically
+  <filename>/nix/store</filename>) is not allowed to contain any
+  symlink components.  This is to prevent “impure” builds.  Builders
+  sometimes “canonicalise” paths by resolving all symlink components.
+  Thus, builds on different machines (with
+  <filename>/nix/store</filename> resolving to different locations)
+  could yield different results.  This is generally not a problem,
+  except when builds are deployed to machines where
+  <filename>/nix/store</filename> resolves differently.  If you are
+  sure that you’re not going to do that, you can set
+  <envar>NIX_IGNORE_SYMLINK_STORE</envar> to <envar>1</envar>.</para>
+
+  <para>Note that if you’re symlinking the Nix store so that you can
+  put it on another file system than the root file system, on Linux
+  you’re better off using <literal>bind</literal> mount points, e.g.,
+
+  <screen>
+$ mkdir /nix
+$ mount -o bind /mnt/otherdisk/nix /nix</screen>
+
+  Consult the <citerefentry><refentrytitle>mount</refentrytitle>
+  <manvolnum>8</manvolnum></citerefentry> manual page for details.</para>
+
+  </listitem>
+
+</varlistentry>
+
+
+<varlistentry><term><envar>NIX_STORE_DIR</envar></term>
+
+  <listitem><para>Overrides the location of the Nix store (default
+  <filename><replaceable>prefix</replaceable>/store</filename>).</para></listitem>
+
+</varlistentry>
+
+
+<varlistentry><term><envar>NIX_DATA_DIR</envar></term>
+
+  <listitem><para>Overrides the location of the Nix static data
+  directory (default
+  <filename><replaceable>prefix</replaceable>/share</filename>).</para></listitem>
+
+</varlistentry>
+
+
+<varlistentry><term><envar>NIX_LOG_DIR</envar></term>
+
+  <listitem><para>Overrides the location of the Nix log directory
+  (default <filename><replaceable>prefix</replaceable>/log/nix</filename>).</para></listitem>
+
+</varlistentry>
+
+
+<varlistentry><term><envar>NIX_STATE_DIR</envar></term>
+
+  <listitem><para>Overrides the location of the Nix state directory
+  (default <filename><replaceable>prefix</replaceable>/var/nix</filename>).</para></listitem>
+
+</varlistentry>
+
+
+<varlistentry><term><envar>NIX_CONF_DIR</envar></term>
+
+  <listitem><para>Overrides the location of the Nix configuration
+  directory (default
+  <filename><replaceable>prefix</replaceable>/etc/nix</filename>).</para></listitem>
+
+</varlistentry>
+
+
+<varlistentry><term><envar>TMPDIR</envar></term>
+
+  <listitem><para>Use the specified directory to store temporary
+  files.  In particular, this includes temporary build directories;
+  these can take up substantial amounts of disk space.  The default is
+  <filename>/tmp</filename>.</para></listitem>
+
+</varlistentry>
+
+
+<varlistentry xml:id="envar-remote"><term><envar>NIX_REMOTE</envar></term>
+
+  <listitem><para>This variable should be set to
+  <literal>daemon</literal> if you want to use the Nix daemon to
+  execute Nix operations. This is necessary in <link
+  linkend="ssec-multi-user">multi-user Nix installations</link>.
+  If the Nix daemon's Unix socket is at some non-standard path,
+  this variable should be set to <literal>unix://path/to/socket</literal>.
+  Otherwise, it should be left unset.</para></listitem>
+
+</varlistentry>
+
+
+<varlistentry><term><envar>NIX_SHOW_STATS</envar></term>
+
+  <listitem><para>If set to <literal>1</literal>, Nix will print some
+  evaluation statistics, such as the number of values
+  allocated.</para></listitem>
+
+</varlistentry>
+
+
+<varlistentry><term><envar>NIX_COUNT_CALLS</envar></term>
+
+  <listitem><para>If set to <literal>1</literal>, Nix will print how
+  often functions were called during Nix expression evaluation.  This
+  is useful for profiling your Nix expressions.</para></listitem>
+
+</varlistentry>
+
+
+<varlistentry><term><envar>GC_INITIAL_HEAP_SIZE</envar></term>
+
+  <listitem><para>If Nix has been configured to use the Boehm garbage
+  collector, this variable sets the initial size of the heap in bytes.
+  It defaults to 384 MiB.  Setting it to a low value reduces memory
+  consumption, but will increase runtime due to the overhead of
+  garbage collection.</para></listitem>
+
+</varlistentry>
+
+
+</variablelist>
+
+
+</chapter>
--- a/doc/manual/command-ref/files.xml
+++ 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>
--- a/doc/manual/command-ref/main-commands.xml
+++ 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>
--- a/doc/manual/command-ref/nix-build.xml
+++ b/doc/manual/command-ref/nix-build.xml
@@ -1,13 +1,14 @@
 <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>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="source">Nix</refmiscinfo>
-  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
 </refmeta>

 <refnamediv>
@@ -28,8 +29,6 @@
      </group>
      <replaceable>attrPath</replaceable>
    </arg>
-    <arg><option>--add-drv-link</option></arg>
-    <arg><option>--drv-link </option><replaceable>drvlink</replaceable></arg>
    <arg><option>--no-out-link</option></arg>
    <arg>
      <group choice='req'>
@@ -57,6 +56,13 @@ and so on).</para>
 <command>nix-build</command> will use <filename>default.nix</filename>
 in the current directory, if it exists.</para>

+<para>If an element of <replaceable>paths</replaceable> starts with
+<literal>http://</literal> or <literal>https://</literal>, it is
+interpreted as the URL of a tarball that will be downloaded and
+unpacked to a temporary location. The tarball must include a single
+top-level directory containing at least a file named
+<filename>default.nix</filename>.</para>
+
 <para><command>nix-build</command> is essentially a wrapper around
 <link
 linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>
@@ -75,36 +81,16 @@ or renamed.  So don’t rename the symlink.</para></warning>

 <refsection><title>Options</title>

-<para>See also <xref linkend="sec-common-options" />.  All options not
-listed here are passed to <command>nix-store --realise</command>,
-except for <option>--arg</option> and <option>--attr</option> /
-<option>-A</option> which are passed to
-<command>nix-instantiate</command>.</para>
+<para>All options not listed here are passed to <command>nix-store
+--realise</command>, except for <option>--arg</option> and
+<option>--attr</option> / <option>-A</option> which are passed to
+<command>nix-instantiate</command>.  <phrase condition="manual">See
+also <xref linkend="sec-common-options" />.</phrase></para>

 <variablelist>

-  <varlistentry><term><option>--add-drv-link</option></term>
-  
-    <listitem><para>Add a symlink in the current directory to the
-    store derivation produced by <command>nix-instantiate</command>.
-    The symlink is called <filename>derivation</filename> (which is
-    numbered in the case of multiple derivations).  The derivation is
-    a root of the garbage collector until the symlink is deleted or
-    renamed.</para></listitem>
-    
-  </varlistentry>
-
-  <varlistentry><term><option>--drv-link</option> <replaceable>drvlink</replaceable></term>
-  
-    <listitem><para>Change the name of the symlink to the derivation
-    created when <option>--add-drv-link</option> is used from
-    <filename>derivation</filename> to
-    <replaceable>drvlink</replaceable>.</para></listitem>
-
-  </varlistentry>
-
  <varlistentry><term><option>--no-out-link</option></term>
-  
+
    <listitem><para>Do not create a symlink to the output path.  Note
    that as a result the output does not become a root of the garbage
    collector, and so might be deleted by <command>nix-store
@@ -114,23 +100,28 @@ except for <option>--arg</option> and <option>--attr</option> /

  <varlistentry xml:id='opt-out-link'><term><option>--out-link</option> /
  <option>-o</option> <replaceable>outlink</replaceable></term>
-  
+
    <listitem><para>Change the name of the symlink to the output path
-    created unless <option>--no-out-link</option> is used from
-    <filename>result</filename> to
+    created from <filename>result</filename> to
    <replaceable>outlink</replaceable>.</para></listitem>

  </varlistentry>

 </variablelist>

+<para>The following common options are supported:</para>
+
+<variablelist condition="manpage">
+  <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" />
+</variablelist>
+
 </refsection>


 <refsection><title>Examples</title>

 <screen>
-$ nix-build pkgs/top-level/all-packages.nix -A firefox
+$ nix-build '&lt;nixpkgs>' -A firefox
 store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv
 /nix/store/d18hyl92g30l...-firefox-1.5.0.7

@@ -140,6 +131,54 @@ lrwxrwxrwx  <replaceable>...</replaceable>  result -> /nix/store/d18hyl92g30l...
 $ ls ./result/bin/
 firefox  firefox-config</screen>

+<para>If a derivation has multiple outputs,
+<command>nix-build</command> will build the default (first) output.
+You can also build all outputs:
+<screen>
+$ nix-build '&lt;nixpkgs>' -A openssl.all
+</screen>
+This will create a symlink for each output named
+<filename>result-<replaceable>outputname</replaceable></filename>.
+The suffix is omitted if the output name is <literal>out</literal>.
+So if <literal>openssl</literal> has outputs <literal>out</literal>,
+<literal>bin</literal> and <literal>man</literal>,
+<command>nix-build</command> will create symlinks
+<literal>result</literal>, <literal>result-bin</literal> and
+<literal>result-man</literal>.  It’s also possible to build a specific
+output:
+<screen>
+$ nix-build '&lt;nixpkgs>' -A openssl.man
+</screen>
+This will create a symlink <literal>result-man</literal>.</para>
+
+<para>Build a Nix expression given on the command line:
+
+<screen>
+$ nix-build -E 'with import &lt;nixpkgs> { }; runCommand "foo" { } "echo bar > $out"'
+$ cat ./result
+bar
+</screen>
+
+</para>
+
+<para>Build the GNU Hello package from the latest revision of the
+master branch of Nixpkgs:
+
+<screen>
+$ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello
+</screen>
+
+</para>
+
+</refsection>
+
+
+<refsection condition="manpage"><title>Environment variables</title>
+
+<variablelist>
+  <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" />
+</variablelist>
+
 </refsection>


--- a/doc/manual/command-ref/nix-channel.xml
+++ b/doc/manual/command-ref/nix-channel.xml
@@ -0,0 +1,191 @@
+<refentry 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-nix-channel">
+
+<refmeta>
+  <refentrytitle>nix-channel</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>nix-channel</refname>
+  <refpurpose>manage Nix channels</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-channel</command>
+    <group choice='req'>
+      <arg choice='plain'><option>--add</option> <replaceable>url</replaceable> <arg choice='opt'><replaceable>name</replaceable></arg></arg>
+      <arg choice='plain'><option>--remove</option> <replaceable>name</replaceable></arg>
+      <arg choice='plain'><option>--list</option></arg>
+      <arg choice='plain'><option>--update</option> <arg rep='repeat'><replaceable>names</replaceable></arg></arg>
+      <arg choice='plain'><option>--rollback</option> <arg choice='opt'><replaceable>generation</replaceable></arg></arg>
+    </group>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsection><title>Description</title>
+
+<para>A Nix channel is a mechanism that allows you to automatically stay
+up-to-date with a set of pre-built Nix expressions.  A Nix channel is
+just a URL that points to a place containing both a set of Nix
+expressions and a pointer to a binary cache.  <phrase
+condition="manual">See also <xref linkend="sec-channels"
+/>.</phrase></para>
+
+<para>This command has the following operations:
+
+<variablelist>
+
+  <varlistentry><term><option>--add</option> <replaceable>url</replaceable> [<replaceable>name</replaceable>]</term>
+
+    <listitem><para>Adds a channel named
+    <replaceable>name</replaceable> with URL
+    <replaceable>url</replaceable> to the list of subscribed channels.
+    If <replaceable>name</replaceable> is omitted, it defaults to the
+    last component of <replaceable>url</replaceable>, with the
+    suffixes <literal>-stable</literal> or
+    <literal>-unstable</literal> removed.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--remove</option> <replaceable>name</replaceable></term>
+
+    <listitem><para>Removes the channel named
+    <replaceable>name</replaceable> from the list of subscribed
+    channels.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--list</option></term>
+
+    <listitem><para>Prints the names and URLs of all subscribed
+    channels on standard output.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--update</option> [<replaceable>names</replaceable>…]</term>
+
+    <listitem><para>Downloads the Nix expressions of all subscribed
+    channels (or only those included in
+    <replaceable>names</replaceable> if specified) and makes them the
+    default for <command>nix-env</command> operations (by symlinking
+    them from the directory
+    <filename>~/.nix-defexpr</filename>).</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--rollback</option> [<replaceable>generation</replaceable>]</term>
+
+    <listitem><para>Reverts the previous call to <command>nix-channel
+    --update</command>. Optionally, you can specify a specific channel
+    generation number to restore.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</para>
+
+<para>Note that <option>--add</option> does not automatically perform
+an update.</para>
+
+<para>The list of subscribed channels is stored in
+<filename>~/.nix-channels</filename>.</para>
+
+</refsection>
+
+<refsection><title>Examples</title>
+
+<para>To subscribe to the Nixpkgs channel and install the GNU Hello package:</para>
+
+<screen>
+$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
+$ nix-channel --update
+$ nix-env -iA nixpkgs.hello</screen>
+
+<para>You can revert channel updates using <option>--rollback</option>:</para>
+
+<screen>
+$ nix-instantiate --eval -E '(import &lt;nixpkgs> {}).lib.nixpkgsVersion'
+"14.04.527.0e935f1"
+
+$ nix-channel --rollback
+switching from generation 483 to 482
+
+$ nix-instantiate --eval -E '(import &lt;nixpkgs> {}).lib.nixpkgsVersion'
+"14.04.526.dbadfad"
+</screen>
+
+</refsection>
+
+<refsection><title>Files</title>
+
+<variablelist>
+
+  <varlistentry><term><filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/channels</filename></term>
+
+    <listitem><para><command>nix-channel</command> uses a
+    <command>nix-env</command> profile to keep track of previous
+    versions of the subscribed channels. Every time you run
+    <command>nix-channel --update</command>, a new channel generation
+    (that is, a symlink to the channel Nix expressions in the Nix store)
+    is created. This enables <command>nix-channel --rollback</command>
+    to revert to previous versions.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><filename>~/.nix-defexpr/channels</filename></term>
+
+    <listitem><para>This is a symlink to
+    <filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/channels</filename>. It
+    ensures that <command>nix-env</command> can find your channels. In
+    a multi-user installation, you may also have
+    <filename>~/.nix-defexpr/channels_root</filename>, which links to
+    the channels of the root user.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+<refsection><title>Channel format</title>
+
+<para>A channel URL should point to a directory containing the
+following files:</para>
+
+<variablelist>
+
+  <varlistentry><term><filename>nixexprs.tar.xz</filename></term>
+
+    <listitem><para>A tarball containing Nix expressions and files
+    referenced by them (such as build scripts and patches). At the
+    top level, the tarball should contain a single directory. That
+    directory must contain a file <filename>default.nix</filename>
+    that serves as the channel’s “entry point”.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><filename>binary-cache-url</filename></term>
+
+    <listitem><para>A file containing the URL to a binary cache (such
+    as <uri>https://cache.nixos.org</uri>). Nix will automatically
+    check this cache for pre-built binaries, if the user has
+    sufficient rights to add binary caches. For instance, in a
+    multi-user Nix setup, the binary caches provided by the channels
+    of the root user are used automatically, but caches corresponding
+    to the channels of non-root users are ignored.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+</refentry>
--- a/doc/manual/command-ref/nix-collect-garbage.xml
+++ b/doc/manual/command-ref/nix-collect-garbage.xml
@@ -1,13 +1,14 @@
 <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>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="source">Nix</refmiscinfo>
-  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
 </refmeta>

 <refnamediv>
@@ -20,12 +21,9 @@
    <command>nix-collect-garbage</command>
    <arg><option>--delete-old</option></arg>
    <arg><option>-d</option></arg>
-    <group choice='opt'>
-      <arg choice='plain'><option>--print-roots</option></arg>
-      <arg choice='plain'><option>--print-live</option></arg>
-      <arg choice='plain'><option>--print-dead</option></arg>
-      <arg choice='plain'><option>--delete</option></arg>
-    </group>
+    <arg><option>--delete-older-than</option> <replaceable>period</replaceable></arg>
+    <arg><option>--max-freed</option> <replaceable>bytes</replaceable></arg>
+    <arg><option>--dry-run</option></arg>
  </cmdsynopsis>
 </refsynopsisdiv>

@@ -34,13 +32,19 @@
 <para>The command <command>nix-collect-garbage</command> is mostly an
 alias of <link linkend="rsec-nix-store-gc"><command>nix-store
 --gc</command></link>, that is, it deletes all unreachable paths in
-the Nix store to clean up your system.  However, it provides an
-additional option <option>-d</option> (<option>--delete-old</option>)
-that deletes all old generations of all profiles in
+the Nix store to clean up your system.  However, it provides two
+additional options: <option>-d</option> (<option>--delete-old</option>),
+which deletes all old generations of all profiles in
 <filename>/nix/var/nix/profiles</filename> by invoking
-<literal>nix-env --delete-generations old</literal> on all profiles.
-Of course, this makes rollbacks to previous configurations
-impossible.</para>
+<literal>nix-env --delete-generations old</literal> on all profiles
+(of course, this makes rollbacks to previous configurations
+impossible); and
+<option>--delete-older-than</option> <replaceable>period</replaceable>,
+where period is a value such as <literal>30d</literal>, which deletes
+all generations older than the specified number of days in all profiles
+in <filename>/nix/var/nix/profiles</filename> (except for the generations
+that were active at that point in time).
+</para>

 </refsection>

--- a/doc/manual/command-ref/nix-copy-closure.xml
+++ b/doc/manual/command-ref/nix-copy-closure.xml
@@ -7,7 +7,7 @@
  <refentrytitle>nix-copy-closure</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="source">Nix</refmiscinfo>
-  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
 </refmeta>

 <refnamediv>
@@ -22,10 +22,18 @@
      <arg choice='plain'><option>--to</option></arg>
      <arg choice='plain'><option>--from</option></arg>
    </group>
-    <arg><option>--sign</option></arg>
    <arg><option>--gzip</option></arg>
+    <!--
+    <arg><option>- -show-progress</option></arg>
+    -->
+    <arg><option>--include-outputs</option></arg>
+    <group>
+      <arg choice='plain'><option>--use-substitutes</option></arg>
+      <arg choice='plain'><option>-s</option></arg>
+    </group>
+    <arg><option>-v</option></arg>
    <arg choice='plain'>
-      <arg><replaceable>user@</replaceable></arg><replaceable>machine</replaceable>
+      <replaceable>user@</replaceable><replaceable>machine</replaceable>
    </arg>
    <arg choice='plain'><replaceable>paths</replaceable></arg>
  </cmdsynopsis>
@@ -36,7 +44,7 @@

 <para><command>nix-copy-closure</command> gives you an easy and
 efficient way to exchange software between machines.  Given one or
-more Nix store paths <replaceable>paths</replaceable> on the local
+more Nix store <replaceable>paths</replaceable> on the local
 machine, <command>nix-copy-closure</command> computes the closure of
 those paths (i.e. all their dependencies in the Nix store), and copies
 all paths in the closure to the remote machine via the
@@ -61,7 +69,7 @@ those paths.  If this bothers you, use
 <refsection><title>Options</title>

 <variablelist>
-  
+
  <varlistentry><term><option>--to</option></term>

    <listitem><para>Copy the closure of
@@ -80,26 +88,44 @@ those paths.  If this bothers you, use

  </varlistentry>

-  <varlistentry><term><option>--sign</option></term>
+  <varlistentry><term><option>--gzip</option></term>

-    <listitem><para>Let the sending machine cryptographically sign the
-    dump of each path with the key in
-    <filename>/nix/etc/nix/signing-key.sec</filename>.  If the user on
-    the target machine does not have direct access to the Nix store
-    (i.e., if the target machine has a multi-user Nix installation),
-    then the target machine will check the dump against
-    <filename>/nix/etc/nix/signing-key.pub</filename> before unpacking
-    it in its Nix store.  This allows secure sharing of store paths
-    between untrusted users on two machines, provided that there is a
-    trust relation between the Nix installations on both machines
-    (namely, they have matching public/secret keys).</para></listitem>
+    <listitem><para>Enable compression of the SSH
+    connection.</para></listitem>

  </varlistentry>

-  <varlistentry><term><option>--gzip</option></term>
+  <!--
+  <varlistentry><term><option>- -show-progress</option></term>

-    <listitem><para>Compress the dump of each path with
-    <command>gzip</command> before sending it.</para></listitem>
+    <listitem><para>Show the progress of each path's transfer as it's made.
+    This requires the <command>pv</command> utility to be in <envar>PATH</envar>.</para></listitem>
+
+  </varlistentry>
+  -->
+
+  <varlistentry><term><option>--include-outputs</option></term>
+
+    <listitem><para>Also copy the outputs of store derivations
+    included in the closure.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--use-substitutes</option> / <option>-s</option></term>
+
+    <listitem><para>Attempt to download missing paths on the target
+    machine using Nix’s substitute mechanism.  Any paths that cannot
+    be substituted on the target are still copied normally from the
+    source.  This is useful, for instance, if the connection between
+    the source and target machine is slow, but the connection between
+    the target machine and <literal>nixos.org</literal> (the default
+    binary cache server) is fast.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>-v</option></term>
+
+    <listitem><para>Show verbose output.</para></listitem>

  </varlistentry>

@@ -118,7 +144,7 @@ those paths.  If this bothers you, use
    <command>ssh</command> on the command line.</para></listitem>

  </varlistentry>
-  
+
 </variablelist>

 </refsection>
--- a/doc/manual/command-ref/nix-daemon.xml
+++ b/doc/manual/command-ref/nix-daemon.xml
@@ -1,24 +1,24 @@
 <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-worker">
+      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-worker</refentrytitle>
+  <refentrytitle>nix-daemon</refentrytitle>
  <manvolnum>8</manvolnum>
  <refmiscinfo class="source">Nix</refmiscinfo>
-  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
 </refmeta>

 <refnamediv>
-  <refname>nix-worker</refname>
+  <refname>nix-daemon</refname>
  <refpurpose>Nix multi-user support daemon</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
-    <command>nix-worker</command>
-    <arg choice="plain"><option>--daemon</option></arg>
+    <command>nix-daemon</command>
  </cmdsynopsis>
 </refsynopsisdiv>

--- a/doc/manual/command-ref/nix-env.xml
+++ b/doc/manual/command-ref/nix-env.xml
--- a/doc/manual/command-ref/nix-hash.xml
+++ b/doc/manual/command-ref/nix-hash.xml
@@ -1,13 +1,14 @@
 <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>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="source">Nix</refmiscinfo>
-  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
 </refmeta>

 <refnamediv>
@@ -43,7 +44,9 @@
 cryptographic hash of the contents of each
 <replaceable>path</replaceable> and prints it on standard output.  By
 default, it computes an MD5 hash, but other hash algorithms are
-available as well.  The hash is printed in hexadecimal.</para>
+available as well.  The hash is printed in hexadecimal.  To generate
+the same hash as <command>nix-prefetch-url</command> you have to
+specify multiple arguments, see below for an example.</para>

 <para>The hash is computed over a <emphasis>serialisation</emphasis>
 of each path: a dump of the file system tree rooted at the path.  This
@@ -91,8 +94,9 @@ cryptographic hash as <literal>nix-store --dump

  <varlistentry><term><option>--type</option> <replaceable>hashAlgo</replaceable></term>

-    <listitem><para>Specify a cryptographic hash, which can be one of
-    <literal>md5</literal>, <literal>sha1</literal>, and
+    <listitem><para>Use the specified cryptographic hash algorithm,
+    which can be one of <literal>md5</literal>,
+    <literal>sha1</literal>, and
    <literal>sha256</literal>.</para></listitem>

  </varlistentry>
@@ -120,6 +124,15 @@ cryptographic hash as <literal>nix-store --dump

 <refsection><title>Examples</title>

+<para>Computing the same hash as <command>nix-prefetch-url</command>:
+<screen>
+$ nix-prefetch-url file://&lt;(echo test)
+1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj
+$ nix-hash --type sha256 --flat --base32 &lt;(echo test)
+1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj
+</screen>
+</para>
+
 <para>Computing hashes:

 <screen>
--- a/doc/manual/command-ref/nix-instantiate.xml
+++ b/doc/manual/command-ref/nix-instantiate.xml
@@ -0,0 +1,264 @@
+<refentry 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-nix-instantiate">
+
+<refmeta>
+  <refentrytitle>nix-instantiate</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>nix-instantiate</refname>
+  <refpurpose>instantiate store derivations from Nix expressions</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-instantiate</command>
+    <group>
+      <arg choice='plain'><option>--parse</option></arg>
+      <arg choice='plain'>
+        <option>--eval</option>
+        <arg><option>--strict</option></arg>
+        <arg><option>--json</option></arg>
+        <arg><option>--xml</option></arg>
+      </arg>
+    </group>
+    <arg><option>--read-write-mode</option></arg>
+    <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
+    <arg>
+      <group choice='req'>
+        <arg choice='plain'><option>--attr</option></arg>
+        <arg choice='plain'><option>-A</option></arg>
+      </group>
+      <replaceable>attrPath</replaceable>
+    </arg>
+    <arg><option>--add-root</option> <replaceable>path</replaceable></arg>
+    <arg><option>--indirect</option></arg>
+    <group>
+      <arg choice='plain'><option>--expr</option></arg>
+      <arg choice='plain'><option>-E</option></arg>
+    </group>
+    <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg>
+  </cmdsynopsis>
+  <cmdsynopsis>
+    <command>nix-instantiate</command>
+    <arg choice='plain'><option>--find-file</option></arg>
+    <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>The command <command>nix-instantiate</command> generates <link
+linkend="gloss-derivation">store derivations</link> from (high-level)
+Nix expressions.  It evaluates the Nix expressions in each of
+<replaceable>files</replaceable> (which defaults to
+<replaceable>./default.nix</replaceable>).  Each top-level expression
+should evaluate to a derivation, a list of derivations, or a set of
+derivations.  The paths of the resulting store derivations are printed
+on standard output.</para>
+
+<para>If <replaceable>files</replaceable> is the character
+<literal>-</literal>, then a Nix expression will be read from standard
+input.</para>
+
+<para condition="manual">See also <xref linkend="sec-common-options"
+/> for a list of common options.</para>
+
+</refsection>
+
+
+<refsection><title>Options</title>
+
+<variablelist>
+
+  <varlistentry>
+    <term><option>--add-root</option> <replaceable>path</replaceable></term>
+    <term><option>--indirect</option></term>
+
+    <listitem><para>See the <link linkend="opt-add-root">corresponding
+    options</link> in <command>nix-store</command>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--parse</option></term>
+
+    <listitem><para>Just parse the input files, and print their
+    abstract syntax trees on standard output in ATerm
+    format.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--eval</option></term>
+
+    <listitem><para>Just parse and evaluate the input files, and print
+    the resulting values on standard output.  No instantiation of
+    store derivations takes place.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--find-file</option></term>
+
+    <listitem><para>Look up the given files in Nix’s search path (as
+    specified by the <envar linkend="env-NIX_PATH">NIX_PATH</envar>
+    environment variable).  If found, print the corresponding absolute
+    paths on standard output.  For instance, if
+    <envar>NIX_PATH</envar> is
+    <literal>nixpkgs=/home/alice/nixpkgs</literal>, then
+    <literal>nix-instantiate --find-file nixpkgs/default.nix</literal>
+    will print
+    <literal>/home/alice/nixpkgs/default.nix</literal>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--strict</option></term>
+
+    <listitem><para>When used with <option>--eval</option>,
+    recursively evaluate list elements and attributes.  Normally, such
+    sub-expressions are left unevaluated (since the Nix expression
+    language is lazy).</para>
+
+    <warning><para>This option can cause non-termination, because lazy
+    data structures can be infinitely large.</para></warning>
+
+    </listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--json</option></term>
+
+    <listitem><para>When used with <option>--eval</option>, print the resulting
+    value as an JSON representation of the abstract syntax tree rather
+    than as an ATerm.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--xml</option></term>
+
+    <listitem><para>When used with <option>--eval</option>, print the resulting
+    value as an XML representation of the abstract syntax tree rather than as
+    an ATerm. The schema is the same as that used by the <link
+    linkend="builtin-toXML"><function>toXML</function> built-in</link>.
+    </para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--read-write-mode</option></term>
+
+    <listitem><para>When used with <option>--eval</option>, perform
+    evaluation in read/write mode so nix language features that
+    require it will still work (at the cost of needing to do
+    instantiation of every evaluated derivation).</para>
+
+    </listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+<variablelist condition="manpage">
+  <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" />
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<para>Instantiating store derivations from a Nix expression, and
+building them using <command>nix-store</command>:
+
+<screen>
+$ nix-instantiate test.nix <lineannotation>(instantiate)</lineannotation>
+/nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv
+
+$ nix-store -r $(nix-instantiate test.nix) <lineannotation>(build)</lineannotation>
+<replaceable>...</replaceable>
+/nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 <lineannotation>(output path)</lineannotation>
+
+$ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26
+dr-xr-xr-x    2 eelco    users        4096 1970-01-01 01:00 lib
+...</screen>
+
+</para>
+
+<para>You can also give a Nix expression on the command line:
+
+<screen>
+$ nix-instantiate -E 'with import &lt;nixpkgs> { }; hello'
+/nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv
+</screen>
+
+This is equivalent to:
+
+<screen>
+$ nix-instantiate '&lt;nixpkgs>' -A hello
+</screen>
+
+</para>
+
+<para>Parsing and evaluating Nix expressions:
+
+<screen>
+$ nix-instantiate --parse -E '1 + 2'
+1 + 2
+
+$ nix-instantiate --eval -E '1 + 2'
+3
+
+$ nix-instantiate --eval --xml -E '1 + 2'
+<![CDATA[<?xml version='1.0' encoding='utf-8'?>
+<expr>
+  <int value="3" />
+</expr>]]></screen>
+
+</para>
+
+<para>The difference between non-strict and strict evaluation:
+
+<screen>
+$ nix-instantiate --eval --xml -E 'rec { x = "foo"; y = x; }'
+<replaceable>...</replaceable><![CDATA[
+  <attr name="x">
+    <string value="foo" />
+  </attr>
+  <attr name="y">
+    <unevaluated />
+  </attr>]]>
+<replaceable>...</replaceable></screen>
+
+Note that <varname>y</varname> is left unevaluated (the XML
+representation doesn’t attempt to show non-normal forms).
+
+<screen>
+$ nix-instantiate --eval --xml --strict -E 'rec { x = "foo"; y = x; }'
+<replaceable>...</replaceable><![CDATA[
+  <attr name="x">
+    <string value="foo" />
+  </attr>
+  <attr name="y">
+    <string value="foo" />
+  </attr>]]>
+<replaceable>...</replaceable></screen>
+
+</para>
+
+</refsection>
+
+
+<refsection condition="manpage"><title>Environment variables</title>
+
+<variablelist>
+  <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" />
+</variablelist>
+
+</refsection>
+
+
+</refentry>
--- a/doc/manual/command-ref/nix-prefetch-url.xml
+++ b/doc/manual/command-ref/nix-prefetch-url.xml
@@ -0,0 +1,131 @@
+<refentry 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-nix-prefetch-url">
+
+<refmeta>
+  <refentrytitle>nix-prefetch-url</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>nix-prefetch-url</refname>
+  <refpurpose>copy a file from a URL into the store and print its hash</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-prefetch-url</command>
+    <arg><option>--version</option></arg>
+    <arg><option>--type</option> <replaceable>hashAlgo</replaceable></arg>
+    <arg><option>--print-path</option></arg>
+    <arg><option>--unpack</option></arg>
+    <arg><option>--name</option> <replaceable>name</replaceable></arg>
+    <arg choice='plain'><replaceable>url</replaceable></arg>
+    <arg><replaceable>hash</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsection><title>Description</title>
+
+<para>The command <command>nix-prefetch-url</command> downloads the
+file referenced by the URL <replaceable>url</replaceable>, prints its
+cryptographic hash, and copies it into the Nix store.  The file name
+in the store is
+<filename><replaceable>hash</replaceable>-<replaceable>baseName</replaceable></filename>,
+where <replaceable>baseName</replaceable> is everything following the
+final slash in <replaceable>url</replaceable>.</para>
+
+<para>This command is just a convenience for Nix expression writers.
+Often a Nix expression fetches some source distribution from the
+network using the <literal>fetchurl</literal> expression contained in
+Nixpkgs.  However, <literal>fetchurl</literal> requires a
+cryptographic hash.  If you don't know the hash, you would have to
+download the file first, and then <literal>fetchurl</literal> would
+download it again when you build your Nix expression.  Since
+<literal>fetchurl</literal> uses the same name for the downloaded file
+as <command>nix-prefetch-url</command>, the redundant download can be
+avoided.</para>
+
+<para>If <replaceable>hash</replaceable> is specified, then a download
+is not performed if the Nix store already contains a file with the
+same hash and base name.  Otherwise, the file is downloaded, and an
+error if signaled if the actual hash of the file does not match the
+specified hash.</para>
+
+<para>This command prints the hash on standard output.  Additionally,
+if the option <option>--print-path</option> is used, the path of the
+downloaded file in the Nix store is also printed.</para>
+
+</refsection>
+
+
+<refsection><title>Options</title>
+
+<variablelist>
+
+  <varlistentry><term><option>--type</option> <replaceable>hashAlgo</replaceable></term>
+
+    <listitem><para>Use the specified cryptographic hash algorithm,
+    which can be one of <literal>md5</literal>,
+    <literal>sha1</literal>, and
+    <literal>sha256</literal>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--print-path</option></term>
+
+    <listitem><para>Print the store path of the downloaded file on
+    standard output.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--unpack</option></term>
+
+    <listitem><para>Unpack the archive (which must be a tarball or zip
+    file) and add the result to the Nix store. The resulting hash can
+    be used with functions such as Nixpkgs’s
+    <varname>fetchzip</varname> or
+    <varname>fetchFromGitHub</varname>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--name</option> <replaceable>name</replaceable></term>
+
+    <listitem><para>Override the name of the file in the Nix store. By
+    default, this is
+    <literal><replaceable>hash</replaceable>-<replaceable>basename</replaceable></literal>,
+    where <replaceable>basename</replaceable> is the last component of
+    <replaceable>url</replaceable>. Overriding the name is necessary
+    when <replaceable>basename</replaceable> contains characters that
+    are not allowed in Nix store paths.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<screen>
+$ nix-prefetch-url ftp://ftp.gnu.org/pub/gnu/hello/hello-2.10.tar.gz
+0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
+
+$ nix-prefetch-url --print-path mirror://gnu/hello/hello-2.10.tar.gz
+0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
+/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz
+
+$ nix-prefetch-url --unpack --print-path https://github.com/NixOS/patchelf/archive/0.8.tar.gz
+079agjlv0hrv7fxnx9ngipx14gyncbkllxrp9cccnh3a50fxcmy7
+/nix/store/19zrmhm3m40xxaw81c8cqm6aljgrnwj2-0.8.tar.gz
+</screen>
+
+</refsection>
+
+
+</refentry>
--- a/doc/manual/command-ref/nix-shell.xml
+++ b/doc/manual/command-ref/nix-shell.xml
@@ -0,0 +1,374 @@
+<refentry 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-nix-shell">
+
+<refmeta>
+  <refentrytitle>nix-shell</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>nix-shell</refname>
+  <refpurpose>start an interactive shell based on a Nix expression</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-shell</command>
+    <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
+    <arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
+    <arg>
+      <group choice='req'>
+        <arg choice='plain'><option>--attr</option></arg>
+        <arg choice='plain'><option>-A</option></arg>
+      </group>
+      <replaceable>attrPath</replaceable>
+    </arg>
+    <arg><option>--command</option> <replaceable>cmd</replaceable></arg>
+    <arg><option>--run</option> <replaceable>cmd</replaceable></arg>
+    <arg><option>--exclude</option> <replaceable>regexp</replaceable></arg>
+    <arg><option>--pure</option></arg>
+    <group choice='req'>
+      <arg choice='plain'>
+        <group choice='req'>
+          <arg choice='plain'><option>--packages</option></arg>
+          <arg choice='plain'><option>-p</option></arg>
+        </group>
+        <arg choice='plain' rep='repeat'><replaceable>packages</replaceable></arg>
+      </arg>
+      <arg><replaceable>path</replaceable></arg>
+    </group>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsection><title>Description</title>
+
+<para>The command <command>nix-shell</command> will build the
+dependencies of the specified derivation, but not the derivation
+itself.  It will then start an interactive shell in which all
+environment variables defined by the derivation
+<replaceable>path</replaceable> have been set to their corresponding
+values, and the script <literal>$stdenv/setup</literal> has been
+sourced.  This is useful for reproducing the environment of a
+derivation for development.</para>
+
+<para>If <replaceable>path</replaceable> is not given,
+<command>nix-shell</command> defaults to
+<filename>shell.nix</filename> if it exists, and
+<filename>default.nix</filename> otherwise.</para>
+
+<para>If <replaceable>path</replaceable> starts with
+<literal>http://</literal> or <literal>https://</literal>, it is
+interpreted as the URL of a tarball that will be downloaded and
+unpacked to a temporary location. The tarball must include a single
+top-level directory containing at least a file named
+<filename>default.nix</filename>.</para>
+
+<para>If the derivation defines the variable
+<varname>shellHook</varname>, it will be evaluated after
+<literal>$stdenv/setup</literal> has been sourced.  Since this hook is
+not executed by regular Nix builds, it allows you to perform
+initialisation specific to <command>nix-shell</command>.  For example,
+the derivation attribute
+
+<programlisting>
+shellHook =
+  ''
+    echo "Hello shell"
+  '';
+</programlisting>
+
+will cause <command>nix-shell</command> to print <literal>Hello shell</literal>.</para>
+
+</refsection>
+
+
+<refsection><title>Options</title>
+
+<para>All options not listed here are passed to <command>nix-store
+--realise</command>, except for <option>--arg</option> and
+<option>--attr</option> / <option>-A</option> which are passed to
+<command>nix-instantiate</command>.  <phrase condition="manual">See
+also <xref linkend="sec-common-options" />.</phrase></para>
+
+<variablelist>
+
+  <varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term>
+
+    <listitem><para>In the environment of the derivation, run the
+    shell command <replaceable>cmd</replaceable>. This command is
+    executed in an interactive shell. (Use <option>--run</option> to
+    use a non-interactive shell instead.) However, a call to
+    <literal>exit</literal> is implicitly added to the command, so the
+    shell will exit after running the command. To prevent this, add
+    <literal>return</literal> at the end; e.g. <literal>--command
+    "echo Hello; return"</literal> will print <literal>Hello</literal>
+    and then drop you into the interactive shell. This can be useful
+    for doing any additional initialisation.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--run</option> <replaceable>cmd</replaceable></term>
+
+    <listitem><para>Like <option>--command</option>, but executes the
+    command in a non-interactive shell. This means (among other
+    things) that if you hit Ctrl-C while the command is running, the
+    shell exits.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--exclude</option> <replaceable>regexp</replaceable></term>
+
+    <listitem><para>Do not build any dependencies whose store path
+    matches the regular expression <replaceable>regexp</replaceable>.
+    This option may be specified multiple times.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--pure</option></term>
+
+    <listitem><para>If this flag is specified, the environment is
+    almost entirely cleared before the interactive shell is started,
+    so you get an environment that more closely corresponds to the
+    “real” Nix build.  A few variables, in particular
+    <envar>HOME</envar>, <envar>USER</envar> and
+    <envar>DISPLAY</envar>, are retained.  Note that
+    <filename>~/.bashrc</filename> and (depending on your Bash
+    installation) <filename>/etc/bashrc</filename> are still sourced,
+    so any variables set there will affect the interactive
+    shell.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--packages</option> / <option>-p</option> <replaceable>packages</replaceable>…</term>
+
+    <listitem><para>Set up an environment in which the specified
+    packages are present.  The command line arguments are interpreted
+    as attribute names inside the Nix Packages collection.  Thus,
+    <literal>nix-shell -p libjpeg openjdk</literal> will start a shell
+    in which the packages denoted by the attribute names
+    <varname>libjpeg</varname> and <varname>openjdk</varname> are
+    present.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>-i</option> <replaceable>interpreter</replaceable></term>
+
+    <listitem><para>The chained script interpreter to be invoked by
+    <command>nix-shell</command>. Only applicable in
+    <literal>#!</literal>-scripts (described <link
+    linkend="ssec-nix-shell-shebang">below</link>).</para>
+
+    </listitem></varlistentry>
+
+</variablelist>
+
+<para>The following common options are supported:</para>
+
+<variablelist condition="manpage">
+  <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" />
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Environment variables</title>
+
+<variablelist>
+
+  <varlistentry><term><envar>NIX_BUILD_SHELL</envar></term>
+    
+    <listitem><para>Shell used to start the interactive environment. 
+    Defaults to the <command>bash</command> found in <envar>PATH</envar>.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<para>To build the dependencies of the package Pan, and start an
+interactive shell in which to build it:
+
+<screen>
+$ nix-shell '&lt;nixpkgs>' -A pan
+[nix-shell]$ unpackPhase
+[nix-shell]$ cd pan-*
+[nix-shell]$ configurePhase
+[nix-shell]$ buildPhase
+[nix-shell]$ ./pan/gui/pan
+</screen>
+
+To clear the environment first, and do some additional automatic
+initialisation of the interactive shell:
+
+<screen>
+$ nix-shell '&lt;nixpkgs>' -A pan --pure \
+    --command 'export NIX_DEBUG=1; export NIX_CORES=8; return'
+</screen>
+
+Nix expressions can also be given on the command line.  For instance,
+the following starts a shell containing the packages
+<literal>sqlite</literal> and <literal>libX11</literal>:
+
+<screen>
+$ nix-shell -E 'with import &lt;nixpkgs> { }; runCommand "dummy" { buildInputs = [ sqlite xorg.libX11 ]; } ""'
+</screen>
+
+A shorter way to do the same is:
+
+<screen>
+$ nix-shell -p sqlite xorg.libX11
+[nix-shell]$ echo $NIX_LDFLAGS
+… -L/nix/store/j1zg5v…-sqlite-3.8.0.2/lib -L/nix/store/0gmcz9…-libX11-1.6.1/lib …
+</screen>
+
+The <command>-p</command> flag looks up Nixpkgs in the Nix search
+path. You can override it by passing <option>-I</option> or setting
+<envar>NIX_PATH</envar>. For example, the following gives you a shell
+containing the Pan package from a specific revision of Nixpkgs:
+
+<screen>
+$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz
+
+[nix-shell:~]$ pan --version
+Pan 0.139
+</screen>
+
+</para>
+
+</refsection>
+
+
+<refsection xml:id="ssec-nix-shell-shebang"><title>Use as a <literal>#!</literal>-interpreter</title>
+
+<para>You can use <command>nix-shell</command> as a script interpreter
+to allow scripts written in arbitrary languages to obtain their own
+dependencies via Nix. This is done by starting the script with the
+following lines:
+
+<programlisting>
+#! /usr/bin/env nix-shell
+#! nix-shell -i <replaceable>real-interpreter</replaceable> -p <replaceable>packages</replaceable>
+</programlisting>
+
+where <replaceable>real-interpreter</replaceable> is the “real” script
+interpreter that will be invoked by <command>nix-shell</command> after
+it has obtained the dependencies and initialised the environment, and
+<replaceable>packages</replaceable> are the attribute names of the
+dependencies in Nixpkgs.</para>
+
+<para>The lines starting with <literal>#! nix-shell</literal> specify
+<command>nix-shell</command> options (see above). Note that you cannot
+write <literal>#! /usr/bin/env nix-shell -i ...</literal> because
+many operating systems only allow one argument in
+<literal>#!</literal> lines.</para>
+
+<para>For example, here is a Python script that depends on Python and
+the <literal>prettytable</literal> package:
+
+<programlisting>
+#! /usr/bin/env nix-shell
+#! nix-shell -i python -p python pythonPackages.prettytable
+
+import prettytable
+
+# Print a simple table.
+t = prettytable.PrettyTable(["N", "N^2"])
+for n in range(1, 10): t.add_row([n, n * n])
+print t
+</programlisting>
+
+</para>
+
+<para>Similarly, the following is a Perl script that specifies that it
+requires Perl and the <literal>HTML::TokeParser::Simple</literal> and
+<literal>LWP</literal> packages:
+
+<programlisting>
+#! /usr/bin/env nix-shell
+#! nix-shell -i perl -p perl perlPackages.HTMLTokeParserSimple perlPackages.LWP
+
+use HTML::TokeParser::Simple;
+
+# Fetch nixos.org and print all hrefs.
+my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/');
+
+while (my $token = $p->get_tag("a")) {
+    my $href = $token->get_attr("href");
+    print "$href\n" if $href;
+}
+</programlisting>
+
+</para>
+
+<para>Finally, the following Haskell script uses a specific branch of
+Nixpkgs/NixOS (the 14.12 stable branch):
+
+<programlisting><![CDATA[
+#! /usr/bin/env nix-shell
+#! nix-shell -i runghc -p haskellPackages.ghc haskellPackages.HTTP haskellPackages.tagsoup
+#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz
+
+import Network.HTTP
+import Text.HTML.TagSoup
+
+-- Fetch nixos.org and print all hrefs.
+main = do
+  resp <- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/")
+  body <- getResponseBody resp
+  let tags = filter (isTagOpenName "a") $ parseTags body
+  let tags' = map (fromAttrib "href") tags
+  mapM_ putStrLn $ filter (/= "") tags'
+]]></programlisting>
+
+If you want to be even more precise, you can specify a specific
+revision of Nixpkgs:
+
+<programlisting>
+#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/0672315759b3e15e2121365f067c1c8c56bb4722.tar.gz
+</programlisting>
+
+</para>
+
+<para>The examples above all used <option>-p</option> to get
+dependencies from Nixpkgs. You can also use a Nix expression to build
+your own dependencies. For example, the Python example could have been
+written as:
+
+<programlisting>
+#! /usr/bin/env nix-shell
+#! nix-shell deps.nix -i python
+</programlisting>
+
+where the file <filename>deps.nix</filename> in the same directory
+as the <literal>#!</literal>-script contains:
+
+<programlisting>
+with import &lt;nixpkgs> {};
+
+runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""
+</programlisting>
+
+</para>
+
+</refsection>
+
+
+<refsection condition="manpage"><title>Environment variables</title>
+
+<variablelist>
+  <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" />
+</variablelist>
+
+</refsection>
+
+
+</refentry>
--- a/doc/manual/command-ref/nix-store.xml
+++ b/doc/manual/command-ref/nix-store.xml
@@ -1,13 +1,14 @@
 <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>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="source">Nix</refmiscinfo>
-  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
 </refmeta>

 <refnamediv>
@@ -48,8 +49,9 @@ be performed.  These are documented below.</para>

 <para>This section lists the options that are common to all
 operations.  These options are allowed for every subcommand, though
-they may not always have an effect.  See also <xref
-linkend="sec-common-options" /> for a list of common options.</para>
+they may not always have an effect.  <phrase condition="manual">See
+also <xref linkend="sec-common-options" /> for a list of common
+options.</phrase></para>

 <variablelist>

@@ -57,8 +59,9 @@ linkend="sec-common-options" /> for a list of common options.</para>

    <listitem><para>Causes the result of a realisation
    (<option>--realise</option> and <option>--force-realise</option>)
-    to be registered as a root of the garbage collector (see <xref
-    linkend="ssec-gc-roots" />).  The root is stored in
+    to be registered as a root of the garbage collector<phrase
+    condition="manual"> (see <xref linkend="ssec-gc-roots"
+    />)</phrase>.  The root is stored in
    <replaceable>path</replaceable>, which must be inside a directory
    that is scanned for roots by the garbage collector (i.e.,
    typically in a subdirectory of
@@ -109,12 +112,16 @@ lrwxrwxrwx    1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r1134
    </listitem>

  </varlistentry>
-    
+
+</variablelist>
+
+<variablelist condition="manpage">
+  <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" />
 </variablelist>

 </refsection>

-  
+

 <!--######################################################################-->

@@ -135,7 +142,7 @@ lrwxrwxrwx    1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r1134
 </refsection>

 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--realise</option> essentially “builds”
 the specified store paths.  Realisation is a somewhat overloaded term:

@@ -158,7 +165,7 @@ the specified store paths.  Realisation is a somewhat overloaded term:
  exist in the file system).  If the path is already valid, we are
  done immediately.  Otherwise, the path and any missing paths in its
  closure may be produced through substitutes.  If there are no
-  (succesful) subsitutes, realisation fails.</para></listitem>
+  (successful) subsitutes, realisation fails.</para></listitem>

 </itemizedlist>

@@ -168,20 +175,55 @@ the specified store paths.  Realisation is a somewhat overloaded term:
 output.  (For non-derivations argument, the argument itself is
 printed.)</para>

-<para>If the <option>--dry-run</option> option is used, then
-<command>nix-store</command> will print on standard error a
-description of what packages would be built or downloaded, and then
-quit.</para>
+<para>The following flags are available:</para>
+
+<variablelist>
+
+  <varlistentry><term><option>--dry-run</option></term>
+
+    <listitem><para>Print on standard error a description of what
+    packages would be built or downloaded, without actually performing
+    the operation.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--ignore-unknown</option></term>
+
+    <listitem><para>If a non-derivation path does not have a
+    substitute, then silently ignore it.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--check</option></term>
+
+    <listitem><para>This option allows you to check whether a
+    derivation is deterministic. It rebuilds the specified derivation
+    and checks whether the result is bitwise-identical with the
+    existing outputs, printing an error if that’s not the case. The
+    outputs of the specified derivation must already exist. When used
+    with <option>-K</option>, if an output path is not identical to
+    the corresponding output from the previous build, the new output
+    path is left in
+    <filename>/nix/store/<replaceable>name</replaceable>.check.</filename></para>
+
+    <para>See also the <option>build-repeat</option> configuration
+    option, which repeats a derivation a number of times and prevents
+    its outputs from being registered as “valid” in the Nix store
+    unless they are identical.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>

 </refsection>
-            
+

 <refsection><title>Examples</title>

 <para>This operation is typically used to build store derivations
 produced by <link
 linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>:
-    
+
 <screen>
 $ nix-store -r $(nix-instantiate ./test.nix)
 /nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1</screen>
@@ -189,12 +231,79 @@ $ nix-store -r $(nix-instantiate ./test.nix)
 This is essentially what <link
 linkend="sec-nix-build"><command>nix-build</command></link> does.</para>

+<para>To test whether a previously-built derivation is deterministic:
+
+<screen>
+$ nix-build '&lt;nixpkgs>' -A hello --check -K
+</screen>
+
+</para>
+
 </refsection>


 </refsection>

-  
+
+
+<!--######################################################################-->
+
+<refsection xml:id='rsec-nix-store-serve'><title>Operation <option>--serve</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-store</command>
+  <arg choice='plain'><option>--serve</option></arg>
+  <arg><option>--write</option></arg>
+</cmdsynopsis>
+
+</refsection>
+
+<refsection><title>Description</title>
+
+<para>The operation <option>--serve</option> provides access to
+the Nix store over stdin and stdout, and is intended to be used
+as a means of providing Nix store access to a restricted ssh user.
+</para>
+
+<para>The following flags are available:</para>
+
+<variablelist>
+
+  <varlistentry><term><option>--write</option></term>
+
+    <listitem><para>Allow the connected client to request the realization
+    of derivations. In effect, this can be used to make the host act
+    as a build slave.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<para>To turn a host into a build server, the
+<filename>authorized_keys</filename> file can be used to provide build
+access to a given SSH public key:
+
+<screen>
+$ cat &lt;&lt;EOF >>/root/.ssh/authorized_keys
+command="nice -n20 nix-store --serve --write" ssh-rsa AAAAB3NzaC1yc2EAAAA...
+EOF
+</screen>
+
+</para>
+
+</refsection>
+
+
+</refsection>
+
+

 <!--######################################################################-->

@@ -212,13 +321,12 @@ linkend="sec-nix-build"><command>nix-build</command></link> does.</para>
    <arg choice='plain'><option>--delete</option></arg>
  </group>
  <arg><option>--max-freed</option> <replaceable>bytes</replaceable></arg>
-  <arg><option>--max-links</option> <replaceable>nrlinks</replaceable></arg>
 </cmdsynopsis>

 </refsection>

 <refsection><title>Description</title>
-            
+
 <para>Without additional flags, the operation <option>--gc</option>
 performs a garbage collection on the Nix store.  That is, all paths in
 the Nix store not reachable via file system references from a set of
@@ -229,40 +337,40 @@ the Nix store not reachable via file system references from a set of
 <variablelist>

  <varlistentry><term><option>--print-roots</option></term>
-  
+
    <listitem><para>This operation prints on standard output the set
    of roots used by the garbage collector.  What constitutes a root
    is described in <xref linkend="ssec-gc-roots"
    />.</para></listitem>
-    
+
  </varlistentry>

  <varlistentry><term><option>--print-live</option></term>
-  
+
    <listitem><para>This operation prints on standard output the set
    of “live” store paths, which are all the store paths reachable
    from the roots.  Live paths should never be deleted, since that
    would break consistency — it would become possible that
    applications are installed that reference things that are no
    longer present in the store.</para></listitem>
-    
+
  </varlistentry>

  <varlistentry><term><option>--print-dead</option></term>
-  
+
    <listitem><para>This operation prints out on standard output the
    set of “dead” store paths, which is just the opposite of the set
    of live paths: any path in the store that is not live (with
    respect to the roots) is dead.</para></listitem>
-    
+
  </varlistentry>

  <varlistentry><term><option>--delete</option></term>
-  
+
    <listitem><para>This operation performs an actual garbage
    collection.  All dead paths are removed from the
    store.  This is the default.</para></listitem>
-    
+
  </varlistentry>

 </variablelist>
@@ -273,21 +381,15 @@ options control what gets deleted and in what order:
 <variablelist>

  <varlistentry><term><option>--max-freed</option> <replaceable>bytes</replaceable></term>
-  
-    <listitem><para>Keep deleting paths until at least
-    <replaceable>bytes</replaceable> bytes have been
-    deleted, then stop.</para></listitem>
-    
-  </varlistentry>

-  <varlistentry><term><option>--max-links</option> <replaceable>nrlinks</replaceable></term>
-  
-    <listitem><para>Keep deleting paths until the hard link count on
-    <filename>/nix/store</filename> is less than
-    <replaceable>nrlinks</replaceable>, then stop.  This is useful for
-    very large Nix stores on filesystems with a 32000 subdirectories
-    limit (like <literal>ext3</literal>).</para></listitem>
-    
+    <listitem><para>Keep deleting paths until at least
+    <replaceable>bytes</replaceable> bytes have been deleted, then
+    stop.  The argument <replaceable>bytes</replaceable> can be
+    followed by the multiplicative suffix <literal>K</literal>,
+    <literal>M</literal>, <literal>G</literal> or
+    <literal>T</literal>, denoting KiB, MiB, GiB or TiB
+    units.</para></listitem>
+
  </varlistentry>

 </variablelist>
@@ -295,9 +397,9 @@ options control what gets deleted and in what order:
 </para>

 <para>The behaviour of the collector is also influenced by the <link
-linkend="conf-gc-keep-outputs"><literal>gc-keep-outputs</literal></link>
+linkend="conf-keep-outputs"><literal>keep-outputs</literal></link>
 and <link
-linkend="conf-gc-keep-derivations"><literal>gc-keep-derivations</literal></link>
+linkend="conf-keep-derivations"><literal>keep-derivations</literal></link>
 variables in the Nix configuration file.</para>

 <para>With <option>--delete</option>, the collector prints the total
@@ -311,7 +413,7 @@ would be freed.</para>
 <refsection><title>Examples</title>

 <para>To delete all unreachable paths, just do:
-    
+
 <screen>
 $ nix-store --gc
 deleting `/nix/store/kq82idx6g0nyzsp2s14gfsc38npai7lf-cairo-1.0.4.tar.gz.drv'
@@ -333,7 +435,7 @@ $ nix-store --gc --max-freed $((100 * 1024 * 1024))</screen>
 </refsection>


-  
+
 <!--######################################################################-->

 <refsection><title>Operation <option>--delete</option></title>
@@ -399,10 +501,11 @@ error: cannot delete path `/nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4'
    <arg choice='plain'><option>--referrers</option></arg>
    <arg choice='plain'><option>--referrers-closure</option></arg>
    <arg choice='plain'><option>--deriver</option></arg>
-    <arg choice='plain'><option>--deriver</option></arg>
+    <arg choice='plain'><option>-d</option></arg>
    <arg choice='plain'><option>--graph</option></arg>
    <arg choice='plain'><option>--tree</option></arg>
    <arg choice='plain'><option>--binding</option> <replaceable>name</replaceable></arg>
+    <arg choice='plain'><option>-b</option> <replaceable>name</replaceable></arg>
    <arg choice='plain'><option>--hash</option></arg>
    <arg choice='plain'><option>--size</option></arg>
    <arg choice='plain'><option>--roots</option></arg>
@@ -418,7 +521,7 @@ error: cannot delete path `/nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4'


 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--query</option> displays various bits of
 information about the store paths .  The queries are described below.  At
 most one query can be specified.  The default query is
@@ -438,16 +541,16 @@ query is applied to the target of the symlink.</para>

  <varlistentry><term><option>--use-output</option></term>
    <term><option>-u</option></term>
-  
+
    <listitem><para>For each argument to the query that is a store
    derivation, apply the query to the output path of the derivation
    instead.</para></listitem>
-    
+
  </varlistentry>

  <varlistentry><term><option>--force-realise</option></term>
    <term><option>-f</option></term>
-  
+
    <listitem><para>Realise each argument to the query first (see
    <link linkend="rsec-nix-store-realise"><command>nix-store
    --realise</command></link>).</para></listitem>
@@ -455,12 +558,12 @@ query is applied to the target of the symlink.</para>
  </varlistentry>

 </variablelist>
-        
+
 </refsection>
-    
+

 <refsection xml:id='nixref-queries'><title>Queries</title>
-            
+
 <variablelist>

  <varlistentry><term><option>--outputs</option></term>
@@ -470,7 +573,7 @@ query is applied to the target of the symlink.</para>
    derivations <replaceable>paths</replaceable>.  These are the paths
    that will be produced when the derivation is
    built.</para></listitem>
-    
+
  </varlistentry>

  <varlistentry><term><option>--requisites</option></term>
@@ -485,10 +588,10 @@ query is applied to the target of the symlink.</para>
    <variablelist>

      <varlistentry><term><option>--include-outputs</option></term>
-      
+
        <listitem><para>Also include the output path of store
        derivations, and their closures.</para></listitem>
-        
+
      </varlistentry>

    </variablelist>
@@ -502,13 +605,13 @@ query is applied to the target of the symlink.</para>
    including binaries of build-time-only dependencies) is obtained by
    distributing the closure of a store derivation and specifying the
    option <option>--include-outputs</option>.</para>
-    
+
    </listitem>

  </varlistentry>

  <varlistentry><term><option>--references</option></term>
-  
+
    <listitem><para>Prints the set of <link
    linkend="gloss-reference">references</link> of the store paths
    <replaceable>paths</replaceable>, that is, their immediate
@@ -516,9 +619,9 @@ query is applied to the target of the symlink.</para>
    <option>--requisites</option>.)</para></listitem>

  </varlistentry>
-  
+
  <varlistentry><term><option>--referrers</option></term>
-  
+
    <listitem><para>Prints the set of <emphasis>referrers</emphasis> of
    the store paths <replaceable>paths</replaceable>, that is, the
    store paths currently existing in the Nix store that refer to one
@@ -527,9 +630,9 @@ query is applied to the target of the symlink.</para>
    store paths are added or removed.</para></listitem>

  </varlistentry>
-  
+
  <varlistentry><term><option>--referrers-closure</option></term>
-  
+
    <listitem><para>Prints the closure of the set of store paths
    <replaceable>paths</replaceable> under the referrers relation; that
    is, all store paths that directly or indirectly refer to one of
@@ -540,7 +643,8 @@ query is applied to the target of the symlink.</para>
  </varlistentry>

  <varlistentry><term><option>--deriver</option></term>
-  
+    <term><option>-d</option></term>
+
    <listitem><para>Prints the <link
    linkend="gloss-deriver">deriver</link> of the store paths
    <replaceable>paths</replaceable>.  If the path has no deriver
@@ -551,7 +655,7 @@ query is applied to the target of the symlink.</para>
  </varlistentry>

  <varlistentry><term><option>--graph</option></term>
-  
+
    <listitem><para>Prints the references graph of the store paths
    <replaceable>paths</replaceable> in the format of the
    <command>dot</command> tool of AT&amp;T's <link
@@ -564,7 +668,7 @@ query is applied to the target of the symlink.</para>
  </varlistentry>

  <varlistentry><term><option>--tree</option></term>
-  
+
    <listitem><para>Prints the references graph of the store paths
    <replaceable>paths</replaceable> as a nested ASCII tree.
    References are ordered by descending closure size; this tends to
@@ -576,7 +680,8 @@ query is applied to the target of the symlink.</para>
  </varlistentry>

  <varlistentry><term><option>--binding</option> <replaceable>name</replaceable></term>
-  
+    <term><option>-b</option> <replaceable>name</replaceable></term>
+
    <listitem><para>Prints the value of the attribute
    <replaceable>name</replaceable> (i.e., environment variable) of
    the store derivations <replaceable>paths</replaceable>.  It is an
@@ -586,7 +691,7 @@ query is applied to the target of the symlink.</para>
  </varlistentry>

  <varlistentry><term><option>--hash</option></term>
-  
+
    <listitem><para>Prints the SHA-256 hash of the contents of the
    store paths <replaceable>paths</replaceable> (that is, the hash of
    the output of <command>nix-store --dump</command> on the given
@@ -596,7 +701,7 @@ query is applied to the target of the symlink.</para>
  </varlistentry>

  <varlistentry><term><option>--size</option></term>
-  
+
    <listitem><para>Prints the size in bytes of the contents of the
    store paths <replaceable>paths</replaceable> — to be precise, the
    size of the output of <command>nix-store --dump</command> on the
@@ -607,7 +712,7 @@ query is applied to the target of the symlink.</para>
  </varlistentry>

  <varlistentry><term><option>--roots</option></term>
-  
+
    <listitem><para>Prints the garbage collector roots that point,
    directly or indirectly, at the store paths
    <replaceable>paths</replaceable>.</para></listitem>
@@ -623,7 +728,7 @@ query is applied to the target of the symlink.</para>

 <para>Print the closure (runtime dependencies) of the
 <command>svn</command> program in the current user environment:
-    
+
 <screen>
 $ nix-store -qR $(which svn)
 /nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4
@@ -708,7 +813,7 @@ $ nix-store -q --roots $(which svn)

 </refsection>

-  
+

 <!--######################################################################-->

@@ -724,16 +829,50 @@ $ nix-store -q --roots $(which svn)
 </refsection>

 <refsection><title>Description</title>
-            
+
 <para>TODO</para>

 </refsection>
-            
+
 </refsection>
 -->



+<!--######################################################################-->
+
+<refsection><title>Operation <option>--add</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-store</command>
+  <arg choice='plain'><option>--add</option></arg>
+  <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
+</cmdsynopsis>
+
+</refsection>
+
+<refsection><title>Description</title>
+
+<para>The operation <option>--add</option> adds the specified paths to
+the Nix store.  It prints the resulting paths in the Nix store on
+standard output.</para>
+
+</refsection>
+
+<refsection><title>Example</title>
+
+<screen>
+$ nix-store --add ./foo.c
+/nix/store/m7lrha58ph6rcnv109yzx1nk1cj7k7zf-foo.c</screen>
+
+</refsection>
+
+</refsection>
+
+
+
 <!--######################################################################-->

 <refsection xml:id='refsec-nix-store-verify'><title>Operation <option>--verify</option></title>
@@ -744,11 +883,12 @@ $ nix-store -q --roots $(which svn)
    <command>nix-store</command>
    <arg choice='plain'><option>--verify</option></arg>
    <arg><option>--check-contents</option></arg>
+    <arg><option>--repair</option></arg>
  </cmdsynopsis>
 </refsection>

 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--verify</option> verifies the internal
 consistency of the Nix database, and the consistency between the Nix
 database and the Nix store.  Any inconsistencies encountered are
@@ -756,27 +896,121 @@ automatically repaired.  Inconsistencies are generally the result of
 the Nix store or database being modified by non-Nix tools, or of bugs
 in Nix itself.</para>

-<para>There is one option:
+<para>This operation has the following options:

 <variablelist>

  <varlistentry><term><option>--check-contents</option></term>
-  
+
    <listitem><para>Checks that the contents of every valid store path
    has not been altered by computing a SHA-256 hash of the contents
    and comparing it with the hash stored in the Nix database at build
    time.  Paths that have been modified are printed out.  For large
    stores, <option>--check-contents</option> is obviously quite
    slow.</para></listitem>
-    
+
  </varlistentry>
-  
+
+  <varlistentry><term><option>--repair</option></term>
+
+    <listitem><para>If any valid path is missing from the store, or
+    (if <option>--check-contents</option> is given) the contents of a
+    valid path has been modified, then try to repair the path by
+    redownloading it.  See <command>nix-store --repair-path</command>
+    for details.</para></listitem>
+
+  </varlistentry>
+
 </variablelist>

 </para>

 </refsection>
-            
+
+
+</refsection>
+
+
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--verify-path</option></title>
+
+<refsection>
+  <title>Synopsis</title>
+  <cmdsynopsis>
+    <command>nix-store</command>
+    <arg choice='plain'><option>--verify-path</option></arg>
+    <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
+  </cmdsynopsis>
+</refsection>
+
+<refsection><title>Description</title>
+
+<para>The operation <option>--verify-path</option> compares the
+contents of the given store paths to their cryptographic hashes stored
+in Nix’s database.  For every changed path, it prints a warning
+message.  The exit status is 0 if no path has changed, and 1
+otherwise.</para>
+
+</refsection>
+
+<refsection><title>Example</title>
+
+<para>To verify the integrity of the <command>svn</command> command and all its dependencies:
+
+<screen>
+$ nix-store --verify-path $(nix-store -qR $(which svn))
+</screen>
+
+</para>
+
+</refsection>
+
+</refsection>
+
+
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--repair-path</option></title>
+
+<refsection>
+  <title>Synopsis</title>
+  <cmdsynopsis>
+    <command>nix-store</command>
+    <arg choice='plain'><option>--repair-path</option></arg>
+    <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
+  </cmdsynopsis>
+</refsection>
+
+<refsection><title>Description</title>
+
+<para>The operation <option>--repair-path</option> attempts to
+“repair” the specified paths by redownloading them using the available
+substituters.  If no substitutes are available, then repair is not
+possible.</para>
+
+<warning><para>During repair, there is a very small time window during
+which the old path (if it exists) is moved out of the way and replaced
+with the new path.  If repair is interrupted in between, then the
+system may be left in a broken state (e.g., if the path contains a
+critical system component like the GNU C Library).</para></warning>
+
+</refsection>
+
+<refsection><title>Example</title>
+
+<screen>
+$ nix-store --verify-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13
+path `/nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13' was modified!
+  expected hash `2db57715ae90b7e31ff1f2ecb8c12ec1cc43da920efcbe3b22763f36a1861588',
+  got `481c5aa5483ebc97c20457bb8bca24deea56550d3985cda0027f67fe54b808e4'
+
+$ nix-store --repair-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13
+fetching path `/nix/store/d7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13'...
+…
+</screen>
+
+</refsection>

 </refsection>

@@ -795,7 +1029,7 @@ in Nix itself.</para>
 </refsection>

 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--dump</option> produces a NAR (Nix
 ARchive) file containing the contents of the file system tree rooted
 at <replaceable>path</replaceable>.  The archive is written to
@@ -826,7 +1060,7 @@ links, but not other types of files (such as device nodes).</para>
 --restore</literal>.</para>

 </refsection>
-            
+

 </refsection>

@@ -845,13 +1079,13 @@ links, but not other types of files (such as device nodes).</para>
 </refsection>

 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--restore</option> unpacks a NAR archive
 to <replaceable>path</replaceable>, which must not already exist.  The
 archive is read from standard input.</para>

 </refsection>
-            
+

 </refsection>

@@ -870,7 +1104,7 @@ archive is read from standard input.</para>
 </refsection>

 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--export</option> writes a serialisation
 of the specified store paths to standard output in a format that can
 be imported into another Nix store with <command
@@ -884,20 +1118,20 @@ path).</para>
 <para>This command does not produce a <emphasis>closure</emphasis> of
 the specified paths, so if a store path references other store paths
 that are missing in the target Nix store, the import will fail.  To
-copy a whole closure, do something like
+copy a whole closure, do something like:

 <screen>
 $ nix-store --export $(nix-store -qR <replaceable>paths</replaceable>) > out</screen>

+To import the whole closure again, run:
+
+<screen>
+$ nix-store --import &lt; out</screen>
+
 </para>

-<para>For an example of how <option>--export</option> and
-<option>--import</option> can be used, see the source of the <command
-linkend="sec-nix-copy-closure">nix-copy-closure</command>
-command.</para>
-
 </refsection>
-            
+

 </refsection>

@@ -915,17 +1149,17 @@ command.</para>
 </refsection>

 <refsection><title>Description</title>
-            
-<para>The operation <option>--export</option> reads a serialisation of
+
+<para>The operation <option>--import</option> reads a serialisation of
 a set of store paths produced by <command
-linkend="refsec-nix-store-export">nix-store --import</command> from
+linkend="refsec-nix-store-export">nix-store --export</command> from
 standard input and adds those store paths to the Nix store.  Paths
 that already exist in the Nix store are ignored.  If a path refers to
 another path that doesn’t exist in the Nix store, the import
 fails.</para>

 </refsection>
-            
+

 </refsection>

@@ -943,7 +1177,7 @@ fails.</para>
 </refsection>

 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--optimise</option> 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
@@ -960,7 +1194,7 @@ on the achieved savings is printed on standard error.</para>
 progress indication.</para>

 </refsection>
-            
+
 <refsection><title>Example</title>

 <screen>
@@ -994,7 +1228,7 @@ there are 114486 files with equal contents out of 215894 files in total
 </refsection>

 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--read-log</option> prints the build log
 of the specified store paths on standard output.  The build log is
 whatever the builder of a derivation wrote to standard output and
@@ -1003,12 +1237,12 @@ the store path is used.</para>

 <para>Build logs are kept in
 <filename>/nix/var/log/nix/drvs</filename>.  However, there is no
-guarantee that a build log is available for any particular store
-path.  For instance, if the path was downloaded as a pre-built binary
-through a substitute, then the log is unavailable.</para>
+guarantee that a build log is available for any particular store path.
+For instance, if the path was downloaded as a pre-built binary through
+a substitute, then the log is unavailable.</para>

 </refsection>
-            
+
 <refsection><title>Example</title>

 <screen>
@@ -1040,20 +1274,20 @@ ktorrent-2.2.1/NEWS
 </refsection>

 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--dump-db</option> writes a dump of the
 Nix database to standard output.  It can be loaded into an empty Nix
 store using <option>--load-db</option>.  This is useful for making
 backups and when migrating to different database schemas.</para>

 </refsection>
-            
+
 </refsection>


 <!--######################################################################-->

-<refsection><title>Operation <option>--dump-db</option></title>
+<refsection><title>Operation <option>--load-db</option></title>

 <refsection>
  <title>Synopsis</title>
@@ -1064,13 +1298,111 @@ backups and when migrating to different database schemas.</para>
 </refsection>

 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--load-db</option> reads a dump of the Nix
 database created by <option>--dump-db</option> from standard input and
 loads it into the Nix database.</para>

 </refsection>
-            
+
+</refsection>
+
+
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--print-env</option></title>
+
+<refsection>
+  <title>Synopsis</title>
+  <cmdsynopsis>
+    <command>nix-store</command>
+    <arg choice='plain'><option>--print-env</option></arg>
+    <arg choice='plain'><replaceable>drvpath</replaceable></arg>
+  </cmdsynopsis>
+</refsection>
+
+<refsection><title>Description</title>
+
+<para>The operation <option>--print-env</option> prints out the
+environment of a derivation in a format that can be evaluated by a
+shell.  The command line arguments of the builder are placed in the
+variable <envar>_args</envar>.</para>
+
+</refsection>
+
+<refsection><title>Example</title>
+
+<screen>
+$ nix-store --print-env $(nix-instantiate '&lt;nixpkgs>' -A firefox)
+<replaceable>…</replaceable>
+export src; src='/nix/store/plpj7qrwcz94z2psh6fchsi7s8yihc7k-firefox-12.0.source.tar.bz2'
+export stdenv; stdenv='/nix/store/7c8asx3yfrg5dg1gzhzyq2236zfgibnn-stdenv'
+export system; system='x86_64-linux'
+export _args; _args='-e /nix/store/9krlzvny65gdc8s7kpb6lkx8cd02c25c-default-builder.sh'
+</screen>
+
+</refsection>
+
+</refsection>
+
+
+<!--######################################################################-->
+
+<refsection xml:id='rsec-nix-store-generate-binary-cache-key'><title>Operation <option>--generate-binary-cache-key</option></title>
+
+<refsection>
+  <title>Synopsis</title>
+  <cmdsynopsis>
+    <command>nix-store</command>
+    <arg choice='plain'>
+      <option>--generate-binary-cache-key</option>
+      <option>key-name</option>
+      <option>secret-key-file</option>
+      <option>public-key-file</option>
+    </arg>
+  </cmdsynopsis>
+</refsection>
+
+<refsection><title>Description</title>
+
+<para>This command generates an <link
+xlink:href="http://ed25519.cr.yp.to/">Ed25519 key pair</link> that can
+be used to create a signed binary cache. It takes three mandatory
+parameters:
+
+<orderedlist>
+
+  <listitem><para>A key name, such as
+  <literal>cache.example.org-1</literal>, that is used to look up keys
+  on the client when it verifies signatures. It can be anything, but
+  it’s suggested to use the host name of your cache
+  (e.g. <literal>cache.example.org</literal>) with a suffix denoting
+  the number of the key (to be incremented every time you need to
+  revoke a key).</para></listitem>
+
+  <listitem><para>The file name where the secret key is to be
+  stored.</para></listitem>
+
+  <listitem><para>The file name where the public key is to be
+  stored.</para></listitem>
+
+</orderedlist>
+
+</para>
+
+</refsection>
+
+</refsection>
+
+
+<!--######################################################################-->
+
+<refsection condition="manpage"><title>Environment variables</title>
+
+<variablelist>
+  <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" />
+</variablelist>
+
 </refsection>


--- a/doc/manual/command-ref/opt-common-syn.xml
+++ b/doc/manual/command-ref/opt-common-syn.xml
@@ -0,0 +1,61 @@
+<nop xmlns="http://docbook.org/ns/docbook">
+  
+<arg><option>--help</option></arg>
+<arg><option>--version</option></arg>
+<arg rep='repeat'>
+  <group choice='req'>
+    <arg choice='plain'><option>--verbose</option></arg>
+    <arg choice='plain'><option>-v</option></arg>
+  </group>
+</arg>
+<arg>
+  <group choice='plain'>
+    <arg choice='plain'><option>--no-build-output</option></arg>
+    <arg choice='plain'><option>-Q</option></arg>
+  </group>
+</arg>
+<arg>
+  <group choice='req'>
+    <arg choice='plain'><option>--max-jobs</option></arg>
+    <arg choice='plain'><option>-j</option></arg>
+  </group>
+  <replaceable>number</replaceable>
+</arg>
+<arg>
+  <option>--cores</option>
+  <replaceable>number</replaceable>
+</arg>
+<arg>
+  <option>--max-silent-time</option>
+  <replaceable>number</replaceable>
+</arg>
+<arg>
+  <option>--timeout</option>
+  <replaceable>number</replaceable>
+</arg>
+<arg>
+  <group choice='plain'>
+    <arg choice='plain'><option>--keep-going</option></arg>
+    <arg choice='plain'><option>-k</option></arg>
+  </group>
+</arg>
+<arg>
+  <group choice='plain'>
+    <arg choice='plain'><option>--keep-failed</option></arg>
+    <arg choice='plain'><option>-K</option></arg>
+  </group>
+</arg>
+<arg><option>--fallback</option></arg>
+<arg><option>--readonly-mode</option></arg>
+<arg>
+  <option>-I</option>
+  <replaceable>path</replaceable>
+</arg>
+<arg>
+  <option>--option</option>
+  <replaceable>name</replaceable>
+  <replaceable>value</replaceable>
+</arg>
+<sbr />
+
+</nop>
--- a/doc/manual/command-ref/opt-common.xml
+++ b/doc/manual/command-ref/opt-common.xml
@@ -1,32 +1,31 @@
-<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>

-<variablelist>
+<variablelist xml:id="opt-common">

 <varlistentry><term><option>--help</option></term>
-  
+
  <listitem><para>Prints out a summary of the command syntax and
  exits.</para></listitem>
-  
+
 </varlistentry>


 <varlistentry><term><option>--version</option></term>
-  
+
  <listitem><para>Prints out the Nix version number on standard output
  and exits.</para></listitem>
 </varlistentry>


-<varlistentry><term><option>--verbose</option></term>
-  <term><option>-v</option></term>
+<varlistentry><term><option>--verbose</option> / <option>-v</option></term>

  <listitem>
-    
+
  <para>Increases the level of verbosity of diagnostic messages
  printed on standard error.  For each Nix operation, the information
  printed on standard output is well-defined; any diagnostic
@@ -37,18 +36,18 @@
  following verbosity levels exist:</para>

  <variablelist>
-    
+
    <varlistentry><term>0</term>
    <listitem><para>“Errors only”: only print messages
    explaining why the Nix invocation failed.</para></listitem>
    </varlistentry>
-      
+
    <varlistentry><term>1</term>
    <listitem><para>“Informational”: print
    <emphasis>useful</emphasis> messages about what Nix is doing.
    This is the default.</para></listitem>
    </varlistentry>
-      
+
    <varlistentry><term>2</term>
    <listitem><para>“Talkative”: print more informational
    messages.</para></listitem>
@@ -68,16 +67,15 @@
    <listitem><para>“Vomit”: print vast amounts of debug
    information.</para></listitem>
    </varlistentry>
-    
+
  </variablelist>

  </listitem>
-  
+
 </varlistentry>


-<varlistentry><term><option>--no-build-output</option></term>
-  <term><option>-Q</option></term>
+<varlistentry><term><option>--no-build-output</option> / <option>-Q</option></term>

  <listitem><para>By default, output written by builders to standard
  output and standard error is echoed to the Nix command's standard
@@ -85,21 +83,22 @@
  builder's standard output and error are always written to a log file
  in
  <filename><replaceable>prefix</replaceable>/nix/var/log/nix</filename>.</para></listitem>
-  
+
 </varlistentry>


-<varlistentry xml:id="opt-max-jobs"><term><option>--max-jobs</option></term>
-  <term><option>-j</option></term>
+<varlistentry xml:id="opt-max-jobs"><term><option>--max-jobs</option> / <option>-j</option>
+<replaceable>number</replaceable></term>

  <listitem><para>Sets the maximum number of build jobs that Nix will
-  perform in parallel to the specified number.  The default is
-  specified by the <link
-  linkend='conf-build-max-jobs'><literal>build-max-jobs</literal></link>
+  perform in parallel to the specified number.  Specify
+  <literal>auto</literal> to use the number of CPUs in the system.
+  The default is specified by the <link
+  linkend='conf-max-jobs'><literal>max-jobs</literal></link>
  configuration setting, which itself defaults to
  <literal>1</literal>.  A higher value is useful on SMP systems or to
  exploit I/O latency.</para></listitem>
-  
+
 </varlistentry>


@@ -113,11 +112,11 @@
  <literal>true</literal>, the builder passes the
  <option>-j<replaceable>N</replaceable></option> flag to GNU Make.
  It defaults to the value of the <link
-  linkend='conf-build-cores'><literal>build-cores</literal></link>
+  linkend='conf-cores'><literal>cores</literal></link>
  configuration setting, if set, or <literal>1</literal> otherwise.
  The value <literal>0</literal> means that the builder should use all
  available CPU cores in the system.</para></listitem>
-  
+
 </varlistentry>


@@ -126,14 +125,23 @@
  <listitem><para>Sets the maximum number of seconds that a builder
  can go without producing any data on standard output or standard
  error.  The default is specified by the <link
-  linkend='conf-build-max-silent-time'><literal>build-max-silent-time</literal></link>
+  linkend='conf-max-silent-time'><literal>max-silent-time</literal></link>
  configuration setting.  <literal>0</literal> means no
  time-out.</para></listitem>

 </varlistentry>

-<varlistentry><term><option>--keep-going</option></term>
-  <term><option>-k</option></term>
+<varlistentry xml:id="opt-timeout"><term><option>--timeout</option></term>
+
+  <listitem><para>Sets the maximum number of seconds that a builder
+  can run.  The default is specified by the <link
+  linkend='conf-timeout'><literal>timeout</literal></link>
+  configuration setting.  <literal>0</literal> means no
+  timeout.</para></listitem>
+
+</varlistentry>
+
+<varlistentry><term><option>--keep-going</option> / <option>-k</option></term>

  <listitem><para>Keep going in case of failed builds, to the
  greatest extent possible.  That is, if building an input of some
@@ -141,12 +149,11 @@
  derivation itself.  Without this option, Nix stops if any build
  fails (except for builds of substitutes), possibly killing builds in
  progress (in case of parallel or distributed builds).</para></listitem>
-  
+
 </varlistentry>


-<varlistentry><term><option>--keep-failed</option></term>
-  <term><option>-K</option></term>
+<varlistentry><term><option>--keep-failed</option> / <option>-K</option></term>

  <listitem><para>Specifies that in case of a build failure, the
  temporary directory (usually in <filename>/tmp</filename>) in which
@@ -171,78 +178,40 @@
  from, say, a network repository.  If the repository is down, the
  realisation of the derivation will fail.  When this option is
  specified, Nix will build the derivation instead.  Thus,
-  installation from binaries falls back on nstallation from source.
+  installation from binaries falls back on installation from source.
  This option is not the default since it is generally not desirable
  for a transient failure in obtaining the substitutes to lead to a
  full build from source (with the related consumption of
  resources).</para>

  </listitem>
-  
+
 </varlistentry>

+<varlistentry><term><option>--no-build-hook</option></term>
+
+  <listitem>
+
+  <para>Disables the build hook mechanism.  This allows to ignore remote
+  builders if they are setup on the machine.</para>
+
+  <para>It's useful in cases where the bandwidth between the client and the
+  remote builder is too low.  In that case it can take more time to upload the
+  sources to the remote builder and fetch back the result than to do the
+  computation locally.</para>
+
+  </listitem>
+
+</varlistentry>
+
+

 <varlistentry><term><option>--readonly-mode</option></term>

  <listitem><para>When this option is used, no attempt is made to open
  the Nix database.  Most Nix operations do need database access, so
  those operations will fail.</para></listitem>
-  
-</varlistentry>

-
-<varlistentry xml:id="opt-log-type"><term><option>--log-type</option>
-<replaceable>type</replaceable></term>
-
-  <listitem>
-
-  <para>This option determines how the output written to standard
-  error is formatted.  Nix’s diagnostic messages are typically
-  <emphasis>nested</emphasis>.  For instance, when tracing Nix
-  expression evaluation (<command>nix-env -vvvvv</command>, messages
-  from subexpressions are nested inside their parent expressions.  Nix
-  builder output is also often nested.  For instance, the Nix Packages
-  generic builder nests the various build tasks (unpack, configure,
-  compile, etc.), and the GNU Make in <literal>stdenv-linux</literal>
-  has been patched to provide nesting for recursive Make
-  invocations.</para>
-
-  <para><replaceable>type</replaceable> can be one of the
-  following:
-
-  <variablelist>
-
-    <varlistentry><term><literal>pretty</literal></term>
-
-      <listitem><para>Pretty-print the output, indicating different
-      nesting levels using spaces.  This is the
-      default.</para></listitem>
-
-    </varlistentry>
-
-    <varlistentry><term><literal>escapes</literal></term>
-
-      <listitem><para>Indicate nesting using escape codes that can be
-      interpreted by the <command>nix-log2xml</command> tool in the
-      Nix source distribution.  The resulting XML file can be fed into
-      the <command>log2html.xsl</command> stylesheet to create an HTML
-      file that can be browsed interactively, using Javascript to
-      expand and collapse parts of the output.</para></listitem>
-
-    </varlistentry>
-
-    <varlistentry><term><literal>flat</literal></term>
-
-      <listitem><para>Remove all nesting.</para></listitem>
-
-    </varlistentry>
-
-  </variablelist>    
-  
-  </para>
-
-  </listitem>
-  
 </varlistentry>


@@ -254,8 +223,8 @@
  expression evaluator will automatically try to call functions that
  it encounters.  It can automatically call functions for which every
  argument has a <link linkend='ss-functions'>default value</link>
-  (e.g., <literal>{<replaceable>argName</replaceable> ?
-  <replaceable>defaultValue</replaceable>}:
+  (e.g., <literal>{ <replaceable>argName</replaceable> ?
+  <replaceable>defaultValue</replaceable> }:
  <replaceable>...</replaceable></literal>).  With
  <option>--arg</option>, you can also call functions that have
  arguments without a default value (or override a default value).
@@ -263,9 +232,8 @@
  named <replaceable>name</replaceable>, it will call it with value
  <replaceable>value</replaceable>.</para>

-  <para>For instance, the file
-  <literal>pkgs/top-level/all-packages.nix</literal> in Nixpkgs is
-  actually a function:
+  <para>For instance, the top-level <literal>default.nix</literal> in
+  Nixpkgs is actually a function:

 <programlisting>
 { # The system (e.g., `i686-linux') for which to build the packages.
@@ -300,10 +268,10 @@
 <varlistentry xml:id="opt-attr"><term><option>--attr</option> / <option>-A</option>
 <replaceable>attrPath</replaceable></term>

-  <listitem><para>In <command>nix-env</command>,
-  <command>nix-instantiate</command> and <command>nix-build</command>,
-  <option>--attr</option> allows you to select an attribute from the
-  top-level Nix expression being evaluated.  The <emphasis>attribute
+  <listitem><para>Select an attribute from the top-level Nix
+  expression being evaluated.  (<command>nix-env</command>,
+  <command>nix-instantiate</command>, <command>nix-build</command> and
+  <command>nix-shell</command> only.)  The <emphasis>attribute
  path</emphasis> <replaceable>attrPath</replaceable> is a sequence of
  attribute names separated by dots.  For instance, given a top-level
  Nix expression <replaceable>e</replaceable>, the attribute path
@@ -323,15 +291,51 @@
 </varlistentry>


-<varlistentry><term><option>--show-trace</option></term>
-  
-  <listitem><para>Causes Nix to print out a stack trace in case of Nix
-  expression evaluation errors.</para></listitem>
-  
+<varlistentry><term><option>--expr</option> / <option>-E</option></term>
+
+  <listitem><para>Interpret the command line arguments as a list of
+  Nix expressions to be parsed and evaluated, rather than as a list
+  of file names of Nix expressions.
+  (<command>nix-instantiate</command>, <command>nix-build</command>
+  and <command>nix-shell</command> only.)</para></listitem>
+
+</varlistentry>
+
+
+<varlistentry xml:id="opt-I"><term><option>-I</option> <replaceable>path</replaceable></term>
+
+  <listitem><para>Add a path to the Nix expression search path.  This
+  option may be given multiple times.  See the <envar
+  linkend="env-NIX_PATH">NIX_PATH</envar> environment variable for
+  information on the semantics of the Nix search path.  Paths added
+  through <option>-I</option> take precedence over
+  <envar>NIX_PATH</envar>.</para></listitem>
+
+</varlistentry>
+
+
+<varlistentry><term><option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term>
+
+  <listitem><para>Set the Nix configuration option
+  <replaceable>name</replaceable> to <replaceable>value</replaceable>.
+  This overrides settings in the Nix configuration file (see
+  <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</para></listitem>
+
+</varlistentry>
+
+
+<varlistentry><term><option>--repair</option></term>
+
+  <listitem><para>Fix corrupted or missing store paths by
+  redownloading or rebuilding them.  Note that this is slow because it
+  requires computing a cryptographic hash of the contents of every
+  path in the closure of the build.  Also note the warning under
+  <command>nix-store --repair-path</command>.</para></listitem>
+
 </varlistentry>


 </variablelist>


-</section>
+</chapter>
--- a/doc/manual/command-ref/opt-inst-syn.xml
+++ b/doc/manual/command-ref/opt-inst-syn.xml
--- a/doc/manual/command-ref/utilities.xml
+++ b/doc/manual/command-ref/utilities.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-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-instantiate.xml" />
+<xi:include href="nix-prefetch-url.xml" />
+
+</chapter>
--- a/doc/manual/conf-file.xml
+++ b/doc/manual/conf-file.xml
@@ -1,272 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="sec-conf-file">
-
-<title>Nix configuration file</title>
-
-
-<para>A number of persistent settings of Nix are stored in the file
-<filename><replaceable>prefix</replaceable>/etc/nix/nix.conf</filename>.
-This file is a list of <literal><replaceable>name</replaceable> =
-<replaceable>value</replaceable></literal> pairs, one per line.
-Comments start with a <literal>#</literal> character.  An example
-configuration file is shown in <xref linkend="ex-nix-conf" />.</para>
-
-<example xml:id='ex-nix-conf'><title>Nix configuration file</title>
-
-<programlisting>
-gc-keep-outputs = true       # Nice for developers
-gc-keep-derivations = true   # Idem
-env-keep-derivations = false
-</programlisting>
-</example>
-
-<para>The following variables are currently available: 
-
-<variablelist>
-
-  
-  <varlistentry xml:id="conf-gc-keep-outputs"><term><literal>gc-keep-outputs</literal></term>
-
-    <listitem><para>If <literal>true</literal>, the garbage collector
-    will keep the outputs of non-garbage derivations.  If
-    <literal>false</literal> (default), outputs will be deleted unless
-    they are GC roots themselves (or reachable from other roots).</para>
- 
-    <para>In general, outputs must be registered as roots separately.
-    However, even if the output of a derivation is registered as a
-    root, the collector will still delete store paths that are used
-    only at build time (e.g., the C compiler, or source tarballs
-    downloaded from the network).  To prevent it from doing so, set
-    this option to <literal>true</literal>.</para></listitem>
-
-  </varlistentry>
-  
-
-  <varlistentry xml:id="conf-gc-keep-derivations"><term><literal>gc-keep-derivations</literal></term>
-
-    <listitem><para>If <literal>true</literal> (default), the garbage
-    collector will keep the derivations from which non-garbage store
-    paths were built.  If <literal>false</literal>, they will be
-    deleted unless explicitly registered as a root (or reachable from
-    other roots).</para>
-
-    <para>Keeping derivation around is useful for querying and
-    traceability (e.g., it allows you to ask with what dependencies or
-    options a store path was built), so by default this option is on.
-    Turn it off to safe a bit of disk space (or a lot if
-    <literal>gc-keep-outputs</literal> is also turned on).</para></listitem>
-
-  </varlistentry>
-
-  
-  <varlistentry><term><literal>env-keep-derivations</literal></term>
-
-    <listitem><para>If <literal>false</literal> (default), derivations
-    are not stored in Nix user environments.  That is, the derivation
-    any build-time-only dependencies may be garbage-collected.</para>
-
-    <para>If <literal>true</literal>, when you add a Nix derivation to
-    a user environment, the path of the derivation is stored in the
-    user environment.  Thus, the derivation will not be
-    garbage-collected until the user environment generation is deleted
-    (<command>nix-env --delete-generations</command>).  To prevent
-    build-time-only dependencies from being collected, you should also
-    turn on <literal>gc-keep-outputs</literal>.</para>
-
-    <para>The difference between this option and
-    <literal>gc-keep-derivations</literal> is that this one is
-    “sticky”: it applies to any user environment created while this
-    option was enabled, while <literal>gc-keep-derivations</literal>
-    only applies at the moment the garbage collector is
-    run.</para></listitem>
-
-  </varlistentry>
-
-  
-  <varlistentry xml:id="conf-build-max-jobs"><term><literal>build-max-jobs</literal></term>
-
-    <listitem><para>This option defines the maximum number of jobs
-    that Nix will try to build in parallel.  The default is
-    <literal>1</literal>.  You should generally set it to the number
-    of CPUs in your system (e.g., <literal>2</literal> on a Athlon 64
-    X2).  It can be overriden using the <option
-    linkend='opt-max-jobs'>--max-jobs</option> (<option>-j</option>)
-    command line switch.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-build-cores"><term><literal>build-cores</literal></term>
-
-    <listitem><para>Sets the value of the
-    <envar>NIX_BUILD_CORES</envar> environment variable in the
-    invocation of builders.  Builders can use this variable at their
-    discretion to control the maximum amount of parallelism.  For
-    instance, in Nixpkgs, if the derivation attribute
-    <varname>enableParallelBuilding</varname> is set to
-    <literal>true</literal>, the builder passes the
-    <option>-j<replaceable>N</replaceable></option> flag to GNU Make.
-    It can be overriden using the <option
-    linkend='opt-cores'>--cores</option> command line switch and
-    defaults to <literal>1</literal>.  The value <literal>0</literal>
-    means that the builder should use all available CPU cores in the
-    system.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-build-max-silent-time"><term><literal>build-max-silent-time</literal></term>
-
-    <listitem>
-
-      <para>This option defines the maximum number of seconds that a
-      builder can go without producing any data on standard output or
-      standard error.  This is useful (for instance in a automated
-      build system) to catch builds that are stuck in an infinite
-      loop, or to catch remote builds that are hanging due to network
-      problems.  It can be overriden using the <option
-      linkend="opt-max-silent-time">--max-silent-time</option> command
-      line switch.</para>
-
-      <para>The value <literal>0</literal> means that there is no
-      timeout.  This is also the default.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-build-users-group"><term><literal>build-users-group</literal></term>
-
-    <listitem><para>This options specifies the Unix group containing
-    the Nix build user accounts.  In multi-user Nix installations,
-    builds should not be performed by the Nix account since that would
-    allow users to arbitrarily modify the Nix store and database by
-    supplying specially crafted builders; and they cannot be performed
-    by the calling user since that would allow him/her to influence
-    the build result.</para>
-
-    <para>Therefore, if this option is non-empty and specifies a valid
-    group, builds will be performed under the user accounts that are a
-    member of the group specified here (as listed in
-    <filename>/etc/group</filename>).  Those user accounts should not
-    be used for any other purpose!</para>
-
-    <para>Nix will never run two builds under the same user account at
-    the same time.  This is to prevent an obvious security hole: a
-    malicious user writing a Nix expression that modifies the build
-    result of a legitimate Nix expression being built by another user.
-    Therefore it is good to have as many Nix build user accounts as
-    you can spare.  (Remember: uids are cheap.)</para>
-
-    <para>The build users should have permission to create files in
-    the Nix store, but not delete them.  Therefore,
-    <filename>/nix/store</filename> should be owned by the Nix
-    account, its group should be the group specified here, and its
-    mode should be <literal>1775</literal>.</para>
-
-    <para>If the build users group is empty, builds will be performed
-    under the uid of the Nix process (that is, the uid of the caller
-    if <envar>NIX_REMOTE</envar> is empty, the uid under which the Nix
-    daemon runs if <envar>NIX_REMOTE</envar> is
-    <literal>daemon</literal>, or the uid that owns the setuid
-    <command>nix-worker</command> program if <envar>NIX_REMOTE</envar>
-    is <literal>slave</literal>).  Obviously, this should not be used
-    in multi-user settings with untrusted users.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-
-  <varlistentry><term><literal>build-use-chroot</literal></term>
-
-    <listitem><para>If set to <literal>true</literal>, builds will be
-    performed in a <emphasis>chroot environment</emphasis>, i.e., the
-    build will be isolated from the normal file system hierarchy and
-    will only see the Nix store, the temporary build directory, and
-    the directories configured with the <link
-    linkend='conf-build-chroot-dirs'><literal>build-chroot-dirs</literal>
-    option</link> (such as <filename>/proc</filename> and
-    <filename>/dev</filename>).  This is useful to prevent undeclared
-    dependencies on files in directories such as
-    <filename>/usr/bin</filename>.</para>
-
-    <para>The use of a chroot requires that Nix is run as root (but
-    you can still use the <link
-    linkend='conf-build-users-group'>“build users” feature</link> to
-    perform builds under different users than root).  Currently,
-    chroot builds only work on Linux because Nix uses “bind mounts” to
-    make the Nix store and other directories available inside the
-    chroot.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-  
-  <varlistentry xml:id="conf-build-chroot-dirs"><term><literal>build-chroot-dirs</literal></term>
-
-    <listitem><para>When builds are performed in a chroot environment,
-    Nix will mount (using <command>mount --bind</command> on Linux)
-    some directories from the normal file system hierarchy inside the
-    chroot.  These are the Nix store, the temporary build directory
-    (usually
-    <filename>/tmp/nix-<replaceable>pid</replaceable>-<replaceable>number</replaceable></filename>)
-    and the directories listed here.  The default is <literal>dev
-    /proc</literal>.  Files in <filename>/dev</filename> (such as
-    <filename>/dev/null</filename>) are needed by many builds, and
-    some files in <filename>/proc</filename> may also be needed
-    occasionally.</para>
-
-    <para>The value used on NixOS is
-    
-<programlisting>
-build-use-chroot = /dev /proc /bin</programlisting>
-
-    to make the <filename>/bin/sh</filename> symlink available (which
-    is still needed by many builders).</para>
-
-    </listitem>
-
-  </varlistentry>
-
-  
-  <varlistentry><term><literal>system</literal></term>
-
-    <listitem><para>This option specifies the canonical Nix system
-    name of the current installation, such as
-    <literal>i686-linux</literal> or
-    <literal>powerpc-darwin</literal>.  Nix can only build derivations
-    whose <literal>system</literal> attribute equals the value
-    specified here.  In general, it never makes sense to modify this
-    value from its default, since you can use it to ‘lie’ about the
-    platform you are building on (e.g., perform a Mac OS build on a
-    Linux machine; the result would obviously be wrong).  It only
-    makes sense if the Nix binaries can run on multiple platforms,
-    e.g., ‘universal binaries’ that run on <literal>powerpc-darwin</literal> and
-    <literal>i686-darwin</literal>.</para>
-
-    <para>It defaults to the canonical Nix system name detected by
-    <filename>configure</filename> at build time.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry><term><literal>fsync-metadata</literal></term>
-
-    <listitem><para>If set to <literal>true</literal>, changes to the
-    Nix store metadata (in <filename>/nix/var/nix/db</filename>) are
-    synchronously flushed to disk.  This improves robustness in case
-    of system crashes, but reduces performance.  The default is
-    <literal>true</literal>.</para></listitem>
-
-  </varlistentry>
-    
-</variablelist>
-
-</para>
-
-
-</section>
--- a/doc/manual/env-common.xml
+++ b/doc/manual/env-common.xml
@@ -1,289 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="sec-common-env">
-
-<title>Common environment variables</title>
-
-
-<para>Most Nix commands interpret the following environment variables:</para>
-
-<variablelist>
-
-  
-<varlistentry><term><envar>NIX_IGNORE_SYMLINK_STORE</envar></term>
-
-  <listitem>
-
-  <para>Normally, the Nix store directory (typically
-  <filename>/nix/store</filename>) is not allowed to contain any
-  symlink components.  This is to prevent “impure” builds.  Builders
-  sometimes “canonicalise” paths by resolving all symlink components.
-  Thus, builds on different machines (with
-  <filename>/nix/store</filename> resolving to different locations)
-  could yield different results.  This is generally not a problem,
-  except when builds are deployed to machines where
-  <filename>/nix/store</filename> resolves differently.  If you are
-  sure that you’re not going to do that, you can set
-  <envar>NIX_IGNORE_SYMLINK_STORE</envar> to <envar>1</envar>.</para>
-
-  <para>Note that if you’re symlinking the Nix store so that you can
-  put it on another file system than the root file system, on Linux
-  you’re better off using <literal>bind</literal> mount points, e.g.,
-
-  <screen>
-$ mkdir /nix   
-$ mount -o bind /mnt/otherdisk/nix /nix</screen>
-
-  Consult the <citerefentry><refentrytitle>mount</refentrytitle>
-  <manvolnum>8</manvolnum></citerefentry> manual page for details.</para>
-
-  </listitem>
-
-</varlistentry>
-
-
-<varlistentry><term><envar>NIX_STORE_DIR</envar></term>
-
-  <listitem><para>Overrides the location of the Nix store (default
-  <filename><replaceable>prefix</replaceable>/store</filename>).</para></listitem>
-  
-</varlistentry>
-
-
-<varlistentry><term><envar>NIX_DATA_DIR</envar></term>
-
-  <listitem><para>Overrides the location of the Nix static data
-  directory (default
-  <filename><replaceable>prefix</replaceable>/share</filename>).</para></listitem>
-  
-</varlistentry>
-
-
-<varlistentry><term><envar>NIX_LOG_DIR</envar></term>
-
-  <listitem><para>Overrides the location of the Nix log directory
-  (default <filename><replaceable>prefix</replaceable>/log/nix</filename>).</para></listitem>
-  
-</varlistentry>
-
-
-<varlistentry><term><envar>NIX_STATE_DIR</envar></term>
-
-  <listitem><para>Overrides the location of the Nix state directory
-  (default <filename><replaceable>prefix</replaceable>/var/nix</filename>).</para></listitem>
-  
-</varlistentry>
-
-
-<varlistentry><term><envar>NIX_DB_DIR</envar></term>
-
-  <listitem><para>Overrides the location of the Nix database (default
-  <filename><replaceable>$NIX_STATE_DIR</replaceable>/db</filename>, i.e.,
-  <filename><replaceable>prefix</replaceable>/var/nix/db</filename>).</para></listitem>
-  
-</varlistentry>
-
-
-<varlistentry><term><envar>NIX_CONF_DIR</envar></term>
-
-  <listitem><para>Overrides the location of the Nix configuration
-  directory (default
-  <filename><replaceable>prefix</replaceable>/etc/nix</filename>).</para></listitem>
-  
-</varlistentry>
-
-
-<varlistentry><term><envar>NIX_LOG_TYPE</envar></term>
-
-  <listitem><para>Equivalent to the <link
-  linkend="opt-log-type"><option>--log-type</option>
-  option</link>.</para></listitem>
-
-</varlistentry>
-  
-
-<varlistentry><term><envar>TMPDIR</envar></term>
-
-  <listitem><para>Use the specified directory to store temporary
-  files.  In particular, this includes temporary build directories;
-  these can take up substantial amounts of disk space.  The default is
-  <filename>/tmp</filename>.</para></listitem>
-  
-</varlistentry>
-
-
-<varlistentry xml:id="envar-build-hook"><term><envar>NIX_BUILD_HOOK</envar></term>
-
-  <listitem>
-
-  <para>Specifies the location of the <emphasis>build hook</emphasis>,
-  which is a program (typically some script) that Nix will call
-  whenever it wants to build a derivation.  This is used to implement
-  distributed builds (see <xref linkend="sec-distributed-builds"
-  />).  The protocol by which the calling Nix process and the build
-  hook communicate is as follows.</para>
-
-  <para>The build hook is called with the following command-line
-  arguments:
-
-  <orderedlist>
-
-    <listitem><para>A boolean value <literal>0</literal> or
-    <literal>1</literal> specifying whether Nix can locally execute
-    more builds, as per the <link
-    linkend="opt-max-jobs"><option>--max-jobs</option> option</link>.
-    The purpose of this argument is to allow the hook to not have to
-    maintain bookkeeping for the local machine.</para></listitem>
-
-    <listitem><para>The Nix platform identifier for the local machine
-    (e.g., <literal>i686-linux</literal>).</para></listitem>
-
-    <listitem><para>The Nix platform identifier for the derivation,
-    i.e., its <link linkend="attr-system"><varname>system</varname>
-    attribute</link>.</para></listitem>
-
-    <listitem><para>The store path of the derivation.</para></listitem>
-
-  </orderedlist>
-
-  </para>
-
-  <para>On the basis of this information, and whatever persistent
-  state the build hook keeps about other machines and their current
-  load, it has to decide what to do with the build.  It should print
-  out on standard error one of the following responses (terminated by
-  a newline, <literal>"\n"</literal>):
-
-  <variablelist>
-
-    <varlistentry><term><literal># decline</literal></term>
-
-      <listitem><para>The build hook is not willing or able to perform
-      the build; the calling Nix process should do the build itself,
-      if possible.</para></listitem>
-
-    </varlistentry>
-
-    <varlistentry><term><literal># postpone</literal></term>
-
-      <listitem><para>The build hook cannot perform the build now, but
-      can do so in the future (e.g., because all available build slots
-      on remote machines are in use).  The calling Nix process should
-      postpone this build until at least one currently running build
-      has terminated.</para></listitem>
-
-    </varlistentry>
-
-    <varlistentry><term><literal># accept</literal></term>
-
-      <listitem><para>The build hook has accepted the
-      build.</para></listitem>
-
-    </varlistentry>
-
-  </variablelist>
-
-  </para>
-
-  <para>After sending <literal># accept</literal>, the hook should
-  read one line from standard input, which will be the string
-  <literal>okay</literal>.  It can then proceed with the build.
-  Before sending <literal>okay</literal>, Nix will store in the hook’s
-  current directory a number of text files that contain information
-  about the derivation:
-
-  <variablelist>
-
-    <varlistentry><term><filename>inputs</filename></term>
-
-      <listitem><para>The set of store paths that are inputs to the
-      build process (one per line).  These have to be copied
-      <emphasis>to</emphasis> the remote machine (in addition to the
-      store derivation itself).</para></listitem>
-
-    </varlistentry>
-  
-    <varlistentry><term><filename>outputs</filename></term>
-
-      <listitem><para>The set of store paths that are outputs of the
-      derivation (one per line).  These have to be copied
-      <emphasis>from</emphasis> the remote machine if the build
-      succeeds.</para></listitem>
-
-    </varlistentry>
-
-    <varlistentry><term><filename>references</filename></term>
-
-      <listitem><para>The reference graph of the inputs, in the format
-      accepted by the command <command>nix-store
-      --register-validity</command>.  It is necessary to run this
-      command on the remote machine after copying the inputs to inform
-      Nix on the remote machine that the inputs are valid
-      paths.</para></listitem>
-
-    </varlistentry>
-
-  </variablelist>
-
-  </para>
-
-  <para>The hook should copy the inputs to the remote machine,
-  register the validity of the inputs, perform the remote build, and
-  copy the outputs back to the local machine.  An exit code other than
-  <literal>0</literal> indicates that the hook has failed.  An exit
-  code equal to 100 means that the remote build failed (as opposed to,
-  e.g., a network error).</para>
-
-  </listitem>
-
-
-</varlistentry>
-
-
-<varlistentry xml:id="envar-remote"><term><envar>NIX_REMOTE</envar></term>
-
-  <listitem><para>This variable should be set to
-  <literal>daemon</literal> if you want to use the Nix daemon to
-  executed Nix operations, which is necessary in <link
-  linkend="ssec-multi-user">multi-user Nix installations</link>.
-  Otherwise, it should be left unset.</para></listitem>
-
-</varlistentry>
-
-    
-<varlistentry xml:id="envar-other-stores"><term><envar>NIX_OTHER_STORES</envar></term>
-
-  <listitem><para>This variable contains the paths of remote Nix
-  installations from whichs paths can be copied, separated by colons.
-  See <xref linkend="sec-sharing-packages" /> for details.  Each path
-  should be the <filename>/nix</filename> directory of a remote Nix
-  installation (i.e., not the <filename>/nix/store</filename>
-  directory).  The paths are subject to globbing, so you can set it so
-  something like <literal>/var/run/nix/remote-stores/*/nix</literal>
-  and mount multiple remote filesystems in
-  <literal>/var/run/nix/remote-stores</literal>.</para>
-
-  <para>Note that if you’re building through the <link
-  linkend="sec-nix-worker">Nix daemon</link>, the only setting for
-  this variable that matters is the one that the
-  <command>nix-worker</command> process uses.  So if you want to
-  change it, you have to restart the daemon.</para></listitem>
-
-</varlistentry>
-
-
-<varlistentry><term><envar>GC_INITIAL_HEAP_SIZE</envar></term>
-
-  <listitem><para>If Nix has been configured to use the Boehm garbage
-  collector, this variable sets the initial size of the heap in bytes.
-  It defaults to 384 MiB.  Setting it to a low value reduces memory
-  consumption, but will increase runtime due to the overhead of
-  garbage collection.</para></listitem>
-
-</varlistentry>
-
-    
-</variablelist>
-
-
-</section>
--- a/doc/manual/expressions/advanced-attributes.xml
+++ b/doc/manual/expressions/advanced-attributes.xml
@@ -0,0 +1,289 @@
+<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>allowedRequisites</varname></term>
+
+    <listitem><para>This attribute is similar to
+    <varname>allowedReferences</varname>, but it specifies the legal
+    requisites of the whole closure, so all the dependencies
+    recursively.  For example,
+
+<programlisting>
+allowedRequisites = [ foobar ];
+</programlisting>
+
+    enforces that the output of a derivation cannot have any other
+    runtime dependency than <varname>foobar</varname>, and in addition
+    it enforces that <varname>foobar</varname> itself doesn't
+    introduce any other dependency itself.</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><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 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;
+  sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
+}
+</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;
+  sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
+}
+</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>passAsFile</varname></term>
+
+    <listitem><para>A list of names of attributes that should be
+    passed via files rather than environment variables.  For example,
+    if you have
+
+    <programlisting>
+passAsFile = ["big"];
+big = "a very long string";
+    </programlisting>
+
+    then when the builder runs, the environment variable
+    <envar>bigPath</envar> will contain the absolute path to a
+    temporary file containing <literal>a very long
+    string</literal>. That is, for any attribute
+    <replaceable>x</replaceable> listed in
+    <varname>passAsFile</varname>, Nix will pass an environment
+    variable <envar><replaceable>x</replaceable>Path</envar> holding
+    the path of the file containing the value of attribute
+    <replaceable>x</replaceable>. This is useful when you need to pass
+    large strings to a builder, since most operating systems impose a
+    limit on the size of the environment (typically, a few hundred
+    kilobyte).</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>
--- a/doc/manual/expressions/arguments-variables.xml
+++ 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>
--- a/doc/manual/expressions/build-script.xml
+++ 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>
--- a/doc/manual/expressions/builder-syntax.xml
+++ 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>
--- a/doc/manual/expressions/builtins.xml
+++ b/doc/manual/expressions/builtins.xml
--- a/doc/manual/expressions/derivations.xml
+++ 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>"x86_64-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 numbers 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>outputs</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 Nixpkgs
+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
+the Nixpkgs manual for details.</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>
--- a/doc/manual/expressions/expression-language.xml
+++ 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>
--- a/doc/manual/expressions/expression-syntax.xml
+++ 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;
+    sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
+  };
+  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 a SHA-256 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>
--- a/doc/manual/expressions/generic-builder.xml
+++ 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 the Nixpkgs manual for details.</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>
--- a/doc/manual/expressions/language-constructs.xml
+++ b/doc/manual/expressions/language-constructs.xml
@@ -0,0 +1,391 @@
+<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 or in a let-expression 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>
+
+is equivalent to
+
+<programlisting>
+let x = 123; in
+{ x = x;
+  y = 456;
+}</programlisting>
+
+and both evaluate 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>
+
+<para>
+Summarizing the fragment
+
+<programlisting>
+...
+inherit x y z;
+inherit (src-set) a b c;
+...</programlisting>
+
+is equivalent to
+
+<programlisting>
+...
+x = x; y = y; z = z;
+a = src-set.a; b = src-set.b; c = src-set.c;
+...</programlisting>
+
+when used while defining local variables in a let-expression or
+while defining a set.</para>
+
+</simplesect>
+
+
+<simplesect xml:id="ss-functions"><title>Functions</title>
+
+<para>Functions have the following form:
+
+<programlisting>
+<replaceable>pattern</replaceable>: <replaceable>body</replaceable></programlisting>
+
+The pattern specifies what the argument of the function must look
+like, and binds variables in the body to (parts of) the
+argument.  There are three kinds of patterns:</para>
+
+<itemizedlist>
+
+
+  <listitem><para>If a pattern is a single identifier, then the
+  function matches any argument.  Example:
+
+  <programlisting>
+let negate = x: !x;
+    concat = x: y: x + y;
+in if negate true then concat "foo" "bar" else ""</programlisting>
+
+  Note that <function>concat</function> is a function that takes one
+  argument and returns a function that takes another argument.  This
+  allows partial parameterisation (i.e., only filling some of the
+  arguments of a function); e.g.,
+
+  <programlisting>
+map (concat "foo") [ "bar" "bla" "abc" ]</programlisting>
+
+  evaluates to <literal>[ "foobar" "foobla"
+  "fooabc" ]</literal>.</para></listitem>
+
+
+  <listitem><para>A <emphasis>set pattern</emphasis> of the form
+  <literal>{ name1, name2, …, nameN }</literal> matches a set
+  containing the listed attributes, and binds the values of those
+  attributes to variables in the function body.  For example, the
+  function
+
+<programlisting>
+{ x, y, z }: z + y + x</programlisting>
+
+  can only be called with a set containing exactly the attributes
+  <varname>x</varname>, <varname>y</varname> and
+  <varname>z</varname>.  No other attributes are allowed.  If you want
+  to allow additional arguments, you can use an ellipsis
+  (<literal>...</literal>):
+
+<programlisting>
+{ x, y, z, ... }: z + y + x</programlisting>
+
+  This works on any set that contains at least the three named
+  attributes.</para>
+
+  <para>It is possible to provide <emphasis>default values</emphasis>
+  for attributes, in which case they are allowed to be missing.  A
+  default value is specified by writing
+  <literal><replaceable>name</replaceable> ?
+  <replaceable>e</replaceable></literal>, where
+  <replaceable>e</replaceable> is an arbitrary expression.  For example,
+
+<programlisting>
+{ x, y ? "foo", z ? "bar" }: z + y + x</programlisting>
+
+  specifies a function that only requires an attribute named
+  <varname>x</varname>, but optionally accepts <varname>y</varname>
+  and <varname>z</varname>.</para></listitem>
+
+
+  <listitem><para>An <literal>@</literal>-pattern provides a means of referring
+  to the whole value being matched:
+
+<programlisting> args@{ x, y, z, ... }: z + y + x + args.a</programlisting>
+
+but can also be written as:
+
+<programlisting> { x, y, z, ... } @ args: 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>. <literal>@</literal>-pattern makes mainly sense with an 
+  ellipsis(<literal>...</literal>) as you can access attribute names as 
+  <literal>a</literal>, using <literal>args.a</literal>, which was given as an
+  additional attribute to the function.
+  </para></listitem>
+
+</itemizedlist>
+
+<para>Note that functions do not have names.  If you want to give them
+a name, you can bind them to an attribute, e.g.,
+
+<programlisting>
+let concat = { x, y }: x + y;
+in concat { x = "foo"; y = "bar"; }</programlisting>
+
+</para>
+
+</simplesect>
+
+
+<simplesect><title>Conditionals</title>
+
+<para>Conditionals look like this:
+
+<programlisting>
+if <replaceable>e1</replaceable> then <replaceable>e2</replaceable> else <replaceable>e3</replaceable></programlisting>
+
+where <replaceable>e1</replaceable> is an expression that should
+evaluate to a Boolean value (<literal>true</literal> or
+<literal>false</literal>).</para>
+
+</simplesect>
+
+
+<simplesect><title>Assertions</title>
+
+<para>Assertions are generally used to check that certain requirements
+on or between features and dependencies hold.  They look like this:
+
+<programlisting>
+assert <replaceable>e1</replaceable>; <replaceable>e2</replaceable></programlisting>
+
+where <replaceable>e1</replaceable> is an expression that should
+evaluate to a Boolean value.  If it evaluates to
+<literal>true</literal>, <replaceable>e2</replaceable> is returned;
+otherwise expression evaluation is aborted and a backtrace is printed.</para>
+
+<example xml:id='ex-subversion-nix'><title>Nix expression for Subversion</title>
+<programlisting>
+{ localServer ? false
+, httpServer ? false
+, sslSupport ? false
+, pythonBindings ? false
+, javaSwigBindings ? false
+, javahlBindings ? false
+, stdenv, fetchurl
+, openssl ? null, httpd ? null, db4 ? null, expat, swig ? null, j2sdk ? null
+}:
+
+assert localServer -> db4 != null; <co xml:id='ex-subversion-nix-co-1' />
+assert httpServer -> httpd != null &amp;&amp; httpd.expat == expat; <co xml:id='ex-subversion-nix-co-2' />
+assert sslSupport -> openssl != null &amp;&amp; (httpServer -> httpd.openssl == openssl); <co xml:id='ex-subversion-nix-co-3' />
+assert pythonBindings -> swig != null &amp;&amp; swig.pythonSupport;
+assert javaSwigBindings -> swig != null &amp;&amp; swig.javaSupport;
+assert javahlBindings -> j2sdk != null;
+
+stdenv.mkDerivation {
+  name = "subversion-1.1.1";
+  ...
+  openssl = if sslSupport then openssl else null; <co xml:id='ex-subversion-nix-co-4' />
+  ...
+}</programlisting>
+</example>
+
+<para><xref linkend='ex-subversion-nix' /> show how assertions are
+used in the Nix expression for Subversion.</para>
+
+<calloutlist>
+
+  <callout arearefs='ex-subversion-nix-co-1'>
+    <para>This assertion states that if Subversion is to have support
+    for local repositories, then Berkeley DB is needed.  So if the
+    Subversion function is called with the
+    <varname>localServer</varname> argument set to
+    <literal>true</literal> but the <varname>db4</varname> argument
+    set to <literal>null</literal>, then the evaluation fails.</para>
+  </callout>
+
+  <callout arearefs='ex-subversion-nix-co-2'>
+    <para>This is a more subtle condition: if Subversion is built with
+    Apache (<literal>httpServer</literal>) support, then the Expat
+    library (an XML library) used by Subversion should be same as the
+    one used by Apache.  This is because in this configuration
+    Subversion code ends up being linked with Apache code, and if the
+    Expat libraries do not match, a build- or runtime link error or
+    incompatibility might occur.</para>
+  </callout>
+
+  <callout arearefs='ex-subversion-nix-co-3'>
+    <para>This assertion says that in order for Subversion to have SSL
+    support (so that it can access <literal>https</literal> URLs), an
+    OpenSSL library must be passed.  Additionally, it says that
+    <emphasis>if</emphasis> Apache support is enabled, then Apache's
+    OpenSSL should match Subversion's.  (Note that if Apache support
+    is not enabled, we don't care about Apache's OpenSSL.)</para>
+  </callout>
+
+  <callout arearefs='ex-subversion-nix-co-4'>
+    <para>The conditional here is not really related to assertions,
+    but is worth pointing out: it ensures that if SSL support is
+    disabled, then the Subversion derivation is not dependent on
+    OpenSSL, even if a non-<literal>null</literal> value was passed.
+    This prevents an unnecessary rebuild of Subversion if OpenSSL
+    changes.</para>
+  </callout>
+
+</calloutlist>
+
+</simplesect>
+
+
+
+<simplesect><title>With-expressions</title>
+
+<para>A <emphasis>with-expression</emphasis>,
+
+<programlisting>
+with <replaceable>e1</replaceable>; <replaceable>e2</replaceable></programlisting>
+
+introduces the set <replaceable>e1</replaceable> into the lexical
+scope of the expression <replaceable>e2</replaceable>.  For instance,
+
+<programlisting>
+let as = { x = "foo"; y = "bar"; };
+in with as; x + y</programlisting>
+
+evaluates to <literal>"foobar"</literal> since the
+<literal>with</literal> adds the <varname>x</varname> and
+<varname>y</varname> attributes of <varname>as</varname> to the
+lexical scope in the expression <literal>x + y</literal>.  The most
+common use of <literal>with</literal> is in conjunction with the
+<function>import</function> function.  E.g.,
+
+<programlisting>
+with (import ./definitions.nix); ...</programlisting>
+
+makes all attributes defined in the file
+<filename>definitions.nix</filename> available as if they were defined
+locally in a <literal>let</literal>-expression.</para>
+
+<para>The bindings introduced by <literal>with</literal> do not shadow bindings
+introduced by other means, e.g.
+
+<programlisting>
+let a = 3; in with { a = 1; }; let a = 4; in with { a = 2; }; ...</programlisting>
+
+establishes the same scope as
+
+<programlisting>
+let a = 1; in let a = 2; in let a = 3; in let a = 4; in ...</programlisting>
+
+</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>
--- a/doc/manual/expressions/language-operators.xml
+++ b/doc/manual/expressions/language-operators.xml
@@ -0,0 +1,135 @@
+<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><literal>-</literal> <replaceable>e</replaceable></entry>
+        <entry>none</entry>
+        <entry>Arithmetic negation.</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>,
+          <replaceable>e1</replaceable> <literal>/</literal> <replaceable>e2</replaceable>
+        </entry>
+        <entry>left</entry>
+        <entry>Arithmetic multiplication and division.</entry>
+      </row>
+      <row>
+        <entry>
+          <replaceable>e1</replaceable> <literal>+</literal> <replaceable>e2</replaceable>,
+          <replaceable>e1</replaceable> <literal>-</literal> <replaceable>e2</replaceable>
+        </entry>
+        <entry>left</entry>
+        <entry>Arithmetic addition and subtraction.  String or path concatenation (only by <literal>+</literal>).</entry>
+      </row>
+      <row>
+        <entry><literal>!</literal> <replaceable>e</replaceable></entry>
+        <entry>none</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>&lt;</literal> <replaceable>e2</replaceable>,
+          <replaceable>e1</replaceable> <literal>&gt;</literal> <replaceable>e2</replaceable>,
+          <replaceable>e1</replaceable> <literal>&lt;=</literal> <replaceable>e2</replaceable>,
+          <replaceable>e1</replaceable> <literal>&gt;=</literal> <replaceable>e2</replaceable>
+        </entry>
+        <entry>none</entry>
+        <entry>Arithmetic comparison.</entry>
+      </row>
+      <row>
+        <entry>
+          <replaceable>e1</replaceable> <literal>==</literal> <replaceable>e2</replaceable>,
+          <replaceable>e1</replaceable> <literal>!=</literal> <replaceable>e2</replaceable>
+        </entry>
+        <entry>none</entry>
+        <entry>Equality and inequality.</entry>
+      </row>
+      <row>
+        <entry><replaceable>e1</replaceable> <literal>&amp;&amp;</literal>
+        <replaceable>e2</replaceable></entry>
+        <entry>left</entry>
+        <entry>Logical AND.</entry>
+      </row>
+      <row>
+        <entry><replaceable>e1</replaceable> <literal>||</literal>
+        <replaceable>e2</replaceable></entry>
+        <entry>left</entry>
+        <entry>Logical OR.</entry>
+      </row>
+      <row>
+        <entry><replaceable>e1</replaceable> <literal>-></literal>
+        <replaceable>e2</replaceable></entry>
+        <entry>none</entry>
+        <entry>Logical implication (equivalent to
+        <literal>!<replaceable>e1</replaceable> ||
+        <replaceable>e2</replaceable></literal>).</entry>
+      </row>
+    </tbody>
+  </tgroup>
+</table>
+
+</section>
--- a/doc/manual/expressions/language-values.xml
+++ b/doc/manual/expressions/language-values.xml
@@ -0,0 +1,313 @@
+<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>. <literal>$</literal> removes any special meaning
+    from the following <literal>$</literal>. Linefeed, carriage-return and tab
+    characters can be written as <literal>''\n</literal>,
+    <literal>''\r</literal>, <literal>''\t</literal>, and <literal>''\</literal>
+    escapes any other character.
+
+    </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>Numbers, which can be <emphasis>integers</emphasis> (like
+  <literal>123</literal>) or <emphasis>floating point</emphasis> (like
+  <literal>123.43</literal> or <literal>.27e13</literal>).</para>
+
+  <para>Numbers are type-compatible: pure integer operations will always
+  return integers, whereas any operation involving at least one floating point
+  number will have a floating point number as a result.</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>
+
+  <para>If the first component of a path is a <literal>~</literal>,
+  it is interpreted as if the rest of the path were relative to the
+  user's home directory. e.g. <filename>~/foo</filename> would be
+  equivalent to <filename>/home/edolstra/foo</filename> for a user
+  whose home directory is <filename>/home/edolstra</filename>.
+  </para>
+
+  <para>Paths can also be specified between angle brackets, e.g.
+  <literal>&lt;nixpkgs&gt;</literal>. This means that the directories
+  listed in the environment variable
+  <envar linkend="env-NIX_PATH">NIX_PATH</envar> will be searched
+  for the given file or directory name.
+  </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>
+
+<para>Note that lists are only lazy in values, and they are strict in length.
+</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>
+
+<para>A set that has a <literal>__functor</literal> attribute whose value
+is callable (i.e. is itself a function or a set with a
+<literal>__functor</literal> attribute whose value is callable) can be
+applied as if it were a function, with the set itself passed in first
+, e.g.,
+
+<programlisting>
+let add = { __functor = self: x: x + self.x; };
+    inc = add // { x = 1; };
+in inc 1
+</programlisting>
+
+evaluates to <literal>2</literal>. This can be used to attach metadata to a
+function without the caller needing to treat it specially, or to implement
+a form of object-oriented programming, for example.
+
+</para>
+
+</simplesect>
+
+
+</section>
--- a/doc/manual/expressions/simple-building-testing.xml
+++ b/doc/manual/expressions/simple-building-testing.xml
@@ -0,0 +1,84 @@
+<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 -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 -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.  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 -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>
--- a/doc/manual/expressions/simple-expression.xml
+++ 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>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>
+
+<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>
--- a/doc/manual/expressions/writing-nix-expressions.xml
+++ b/doc/manual/expressions/writing-nix-expressions.xml
@@ -0,0 +1,26 @@
+<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>Writing 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" />
+
+</part>
--- a/doc/manual/figures/user-environments.png
+++ b/doc/manual/figures/user-environments.png
--- a/doc/manual/glossary/glossary.xml
+++ b/doc/manual/glossary/glossary.xml
@@ -54,7 +54,7 @@

  <glossdef><para>A substitute is a command invocation stored in the
  Nix database that describes how to build a store object, bypassing
-  normal the build mechanism (i.e., derivations).  Typically, the
+  the normal build mechanism (i.e., derivations).  Typically, the
  substitute builds the store object by downloading a pre-built
  version of the store object from some server.</para></glossdef>

@@ -160,6 +160,18 @@
 </glossentry>


+<glossentry xml:id="gloss-nar"><glossterm>NAR</glossterm>
+
+  <glossdef><para>A <emphasis>N</emphasis>ix
+  <emphasis>AR</emphasis>chive.  This is a serialisation of a path in
+  the Nix store.  It can contain regular files, directories and
+  symbolic links.  NARs are generated and unpacked using
+  <command>nix-store --dump</command> and <command>nix-store
+  --restore</command>.</para></glossdef>
+
+</glossentry>
+
+

 </glosslist>

--- a/doc/manual/hacking.xml
+++ b/doc/manual/hacking.xml
@@ -0,0 +1,41 @@
+<appendix xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xml:id="chap-hacking">
+
+<title>Hacking</title>
+
+<para>This section provides some notes on how to hack on Nix.  To get
+the latest version of Nix from GitHub:
+<screen>
+$ git clone git://github.com/NixOS/nix.git
+$ cd nix
+</screen>
+</para>
+
+<para>To build it and its dependencies:
+<screen>
+$ nix-build release.nix -A build.x86_64-linux
+</screen>
+</para>
+
+<para>To build all dependencies and start a shell in which all
+environment variables are set up so that those dependencies can be
+found:
+<screen>
+$ nix-shell
+</screen>
+To build Nix itself in this shell:
+<screen>
+[nix-shell]$ ./bootstrap.sh
+[nix-shell]$ configurePhase
+[nix-shell]$ make
+</screen>
+To install it in <literal>$(pwd)/nix</literal> and test it:
+<screen>
+[nix-shell]$ make install
+[nix-shell]$ make installcheck
+</screen>
+
+</para>
+
+</appendix>
--- a/doc/manual/images/callouts/1.gif
+++ b/doc/manual/images/callouts/1.gif
--- a/doc/manual/images/callouts/10.gif
+++ b/doc/manual/images/callouts/10.gif
--- a/doc/manual/images/callouts/11.gif
+++ b/doc/manual/images/callouts/11.gif
--- a/doc/manual/images/callouts/12.gif
+++ b/doc/manual/images/callouts/12.gif
--- a/doc/manual/images/callouts/13.gif
+++ b/doc/manual/images/callouts/13.gif
--- a/doc/manual/images/callouts/14.gif
+++ b/doc/manual/images/callouts/14.gif
--- a/doc/manual/images/callouts/15.gif
+++ b/doc/manual/images/callouts/15.gif
--- a/doc/manual/images/callouts/2.gif
+++ b/doc/manual/images/callouts/2.gif
--- a/doc/manual/images/callouts/3.gif
+++ b/doc/manual/images/callouts/3.gif
--- a/doc/manual/images/callouts/4.gif
+++ b/doc/manual/images/callouts/4.gif
--- a/doc/manual/images/callouts/5.gif
+++ b/doc/manual/images/callouts/5.gif
--- a/doc/manual/images/callouts/6.gif
+++ b/doc/manual/images/callouts/6.gif
--- a/doc/manual/images/callouts/7.gif
+++ b/doc/manual/images/callouts/7.gif
--- a/doc/manual/images/callouts/8.gif
+++ b/doc/manual/images/callouts/8.gif
--- a/doc/manual/images/callouts/9.gif
+++ b/doc/manual/images/callouts/9.gif
--- a/doc/manual/installation.xml
+++ b/doc/manual/installation.xml
@@ -1,482 +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, both on Intel and
-  PowerPC.</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>Obtaining Nix</title>
-
-<para>The easiest way to obtain Nix is to download a <link
-xlink:href="http://nixos.org/">source distribution</link>.  RPMs
-for Red Hat, SuSE, and Fedora Core are also available.</para>
-
-<para>Alternatively, the most recent sources of Nix can be obtained
-from its <link
-xlink:href="https://svn.nixos.org/repos/nix/nix/trunk">Subversion
-repository</link>.  For example, the following command will check out
-the latest revision into a directory called
-<filename>nix</filename>:</para>
-
-<screen>
-$ svn checkout https://svn.nixos.org/repos/nix/nix/trunk nix</screen>
-
-<para>Likewise, specific releases can be obtained from the <link
-xlink:href="https://svn.nixos.org/repos/nix/nix/tags">tags
-directory</link> of the repository.</para>
-
-</section>
-
-
-<section><title>Prerequisites</title>
-
-<para><emphasis>The following prerequisites only apply when you build
-from source</emphasis>.  Binary releases (e.g., RPMs) have no
-prerequisites.</para>
-
-<para>A fairly recent version of GCC/G++ is required.  Version 2.95
-and higher should work.</para>
-
-<para>To build this manual and the man-pages you need the
-<command>xmllint</command> and <command>xsltproc</command> programs,
-which 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 Subversion
-repository.</para>
-
-<para>To build the parser, very <emphasis>recent</emphasis> versions
-of Bison and Flex are required.  (This is because Nix needs GLR
-support in Bison and reentrancy support in Flex.)  For Bison, you need
-version 2.3 or higher (1.875 does <emphasis>not</emphasis> work),
-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.33, 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 Subversion
-repository.</para>
-
-<para>Nix uses the bzip2 compressor (including the bzip2 library).  It
-is included in the Nix source distribution.  If you build from the
-Subversion repository, you must download it yourself and place it in
-the <filename>externals/</filename> directory.  See
-<filename>externals/Makefile.am</filename> for the precise URLs of
-this packages.  Alternatively, if you already have it installed, you
-can use <command>configure</command>'s <option>--with-bzip2</option>
-options to point to their respective locations.</para>
-
-<para>Nix can optionally use the <link
-xlink:href="http://www.hpl.hp.com/personal/Hans_Boehm/gc/">Boehm
-garbage collector</link> to reduce the evaluator’s memory consumption.
-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>
-
-</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>
-
-</para>
-
-<para>When building from the Subversion 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><title>Installing a binary distribution</title>
-
-<para>RPM and Deb packages of Nix for a number of different versions
-of Fedora, openSUSE, Debian and Ubuntu can be downloaded from <link
-xlink:href="http://nixos.org/" />.  Once downloaded, the RPMs can be
-installed or upgraded using <command>rpm -U</command>.  For example,
-
-<screen>
-$ rpm -U nix-0.13pre18104-1.i386.rpm</screen>
-
-Likewise, for a Deb package:
-
-<screen>
-$ dpkg -i nix_0.13pre18104-1_amd64.deb</screen>
-
-</para>
-
-<para>Nix can be uninstalled using <command>rpm -e nix</command> or
-<command>dpkg -r nix</command>.  After this you should manually remove
-the Nix store and other auxiliary data, if desired:
-
-<screen>
-$ rm -rf /nix/store
-$ rm -rf /nix/var</screen>
-
-</para>
-
-</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> (usually called
-<literal>nixbld</literal>).  This group should have no other members.
-The build users should not be members of any other group.</para>
-
-<para>Here is a typical <filename>/etc/group</filename> definition of
-the build users group with 10 build users:
-
-<programlisting>
-nixbld:!:30000:nixbld1,nixbld2,nixbld3,nixbld4,nixbld5,nixbld6,nixbld7,nixbld8,nixbld9,nixbld10
-</programlisting>
-
-In this example the <literal>nixbld</literal> group has UID 30000, but
-of course it can be anything that doesn’t collide with an existing
-group.</para>
-
-<para>Here is the corresponding part of
-<filename>/etc/passwd</filename>:
-
-<programlisting>
-nixbld1:x:30001:65534:Nix build user 1:/var/empty:/noshell
-nixbld2:x:30002:65534:Nix build user 2:/var/empty:/noshell
-nixbld3:x:30003:65534:Nix build user 3:/var/empty:/noshell
-...
-nixbld10:x:30010:65534:Nix build user 10:/var/empty:/noshell
-</programlisting>
-
-The home directory of the build users should not exist or should be an
-empty directory to which they do not have write access.</para>
-
-<para>The build users should have write access to the Nix store, but
-they should not have the right to delete files.  Thus the Nix store’s
-group should be the build users group, and it should have the sticky
-bit turned on (like <filename>/tmp</filename>):
-
-<screen>
-$ chgrp nixbld /nix/store
-$ chmod 1777 /nix/store
-</screen>
-
-</para>
-
-<para>Finally, you should tell Nix to use the build users by
-specifying the build users group in the <link
-linkend="conf-build-users-group"><literal>build-users-group</literal>
-option</link> in the <link linkend="sec-conf-file">Nix configuration
-file</link> (<literal>/nix/etc/nix/nix.conf</literal>):
-
-<programlisting>
-build-users-group = nixbld
-</programlisting>
-
-</para>
-
-</section>
-
-
-<section><title>Nix store/database owned by root</title>
-
-<para>The simplest setup is to let <literal>root</literal> own the Nix
-store and database.  I.e.,
-
-<screen>
-$ chown -R root /nix/store /nix/var/nix</screen>
-
-</para>
-
-<para>The <link linkend="sec-nix-worker">Nix daemon</link> should be
-started as follows (as <literal>root</literal>):
-
-<screen>
-$ nix-worker --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>Nix store/database not owned by root</title>
-
-<para>It is also possible to let the Nix store and database be owned
-by a non-root user, which should be more secure<footnote><para>Note
-however that even when the Nix daemon runs as root, not
-<emphasis>that</emphasis> much code is executed as root: Nix
-expression evaluation is performed by the calling (unprivileged) user,
-and builds are performed under the special build user accounts.  So
-only the code that accesses the database and starts builds is executed
-as <literal>root</literal>.</para></footnote>.  Typically, this user
-is a special account called <literal>nix</literal>, but it can be
-named anything.  It should own the Nix store and database:
-
-<screen>
-$ chown -R root /nix/store /nix/var/nix</screen>
-
-and of course <command>nix-worker --daemon</command> should be started
-under that user, e.g.,
-
-<screen>
-$ su - nix -c "exec /nix/bin/nix-worker --daemon"</screen>
-
-</para>
-
-<para>There is a catch, though: non-<literal>root</literal> users
-cannot start builds under the build user accounts, since the
-<function>setuid</function> system call is obviously privileged.  To
-allow a non-<literal>root</literal> Nix daemon to use the build user
-feature, it calls a setuid-root helper program,
-<command>nix-setuid-helper</command>.  This program is installed in
-<filename><replaceable>prefix</replaceable>/libexec/nix-setuid-helper</filename>.
-To set the permissions properly (Nix’s <command>make install</command>
-doesn’t do this, since we don’t want to ship setuid-root programs
-out-of-the-box):
-
-<screen>
-$ chown root.root /nix/libexec/nix-setuid-helper
-$ chmod 4755 /nix/libexec/nix-setuid-helper
-</screen>
-
-(This example assumes that the Nix binaries are installed in
-<filename>/nix</filename>.)</para>
-
-<para>Of course, the <command>nix-setuid-helper</command> command
-should not be usable by just anybody, since then anybody could run
-commands under the Nix build user accounts.  For that reason there is
-a configuration file <filename>/etc/nix-setuid.conf</filename> that
-restricts the use of the helper.  This file should be a text file
-containing precisely two lines, the first being the Nix daemon user
-and the second being the build users group, e.g.,
-
-<programlisting>
-nix
-nixbld
-</programlisting>
-
-The setuid-helper barfs if it is called by a user other than the one
-specified on the first line, or if it is asked to execute a build
-under a user who is not a member of the group specified on the second
-line.  The file <filename>/etc/nix-setuid.conf</filename> must be
-owned by root, and must not be group- or world-writable.  The
-setuid-helper barfs if this is not the case.</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>~/.bashrc</filename> (or similar), like this:</para>
-
-<screen>
-source <replaceable>prefix</replaceable>/etc/profile.d/nix.sh</screen>
-
-</section>
-
-
-</chapter>
--- a/doc/manual/installation/building-source.xml
+++ b/doc/manual/installation/building-source.xml
@@ -0,0 +1,49 @@
+<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>
+
+</section>
--- a/Show More
+++ b/Show More