Add memoise primop

'builtins.memoise f x' is equal to 'f x', but uses a cache to speed up
repeated invocations of 'f' with the same 'x'. A typical application
is memoising evaluations of Nixpkgs in NixOps network
specifications. For example, with the patch below, the time to
evaluate a 10-machine NixOps network is reduced from 17.1s to 9.6s,
while memory consumption goes from 4486 MiB to 3089 MiB. (This is with
GC_INITIAL_HEAP_SIZE=16G.)

Nixpkgs patch:

diff --git a/pkgs/top-level/impure.nix b/pkgs/top-level/impure.nix
index a9f21e45aed..f641067e022 100644
--- a/pkgs/top-level/impure.nix
+++ b/pkgs/top-level/impure.nix
@@ -79,7 +79,7 @@ in
 # not be passed.
 assert args ? localSystem -> !(args ? system || args ? platform);

-import ./. (builtins.removeAttrs args [ "system" "platform" ] // {
+builtins.memoise or (x: x) (import ./.) (builtins.removeAttrs args [ "system" "platform" ] // {
   inherit config overlays crossSystem;
   # Fallback: Assume we are building packages on the current (build, in GNU
   # Autotools parlance) system.

.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 '-))
+  )))

.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

.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 1.12
+
+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.
+
+-->

.gitignore

@@ -1,5 +1,5 @@
-Makefile
-Makefile.in
+Makefile.config
+perl/Makefile.config
 
 # /
 /aclocal.m4
@@ -9,18 +9,8 @@ Makefile.in
 /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/config.nix
 
 # /corepkgs/buildenv/
@@ -41,38 +31,14 @@ Makefile.in
 /doc/manual/*.1
 /doc/manual/*.5
 /doc/manual/*.8
-/doc/manual/images
 /doc/manual/version.txt
-/doc/manual/NEWS.html
-/doc/manual/NEWS.txt
 
 # /scripts/
 /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/nix-generate-patches
-/scripts/NixConfig.pm
-/scripts/NixManifest.pm
-/scripts/GeneratePatches.pm
-/scripts/download-using-manifests.pl
-/scripts/copy-from-other-stores.pl
-/scripts/download-from-binary-cache.pl
-/scripts/find-runtime-roots.pl
-/scripts/build-remote.pl
 /scripts/nix-reduce-build
 /scripts/nix-http-export.cgi
 
-# /src/bsdiff-4.3/
-/src/bsdiff-4.3/bsdiff
-/src/bsdiff-4.3/bspatch
-
 # /src/libexpr/
 /src/libexpr/lexer-tab.cc
 /src/libexpr/lexer-tab.hh
@@ -82,36 +48,41 @@ Makefile.in
 /src/libexpr/nix.tbl
 
 # /src/libstore/
-/src/libstore/schema.sql.hh
+/src/libstore/*.gen.hh
+
+/src/nix/nix
 
 # /src/nix-env/
 /src/nix-env/nix-env
 
-# /src/nix-hash/
-/src/nix-hash/nix-hash
-
 # /src/nix-instantiate/
 /src/nix-instantiate/nix-instantiate
 
-# /src/nix-log2xml/
-/src/nix-log2xml/nix-log2xml
-/src/nix-log2xml/test*.*
-/src/nix-log2xml/*.log
-/src/nix-log2xml/*.xml
-/src/nix-log2xml/*.html
-
-# /src/nix-setuid-helper/
-/src/nix-setuid-helper/nix-setuid-helper
-
 # /src/nix-store/
 /src/nix-store/nix-store
 
+/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/test-tmp
-/tests/config.nix
 /tests/common.sh
 /tests/dummy
 /tests/result*
@@ -124,14 +95,24 @@ Makefile.in
 /perl/lib/Nix/Config.pm
 /perl/lib/Nix/Store.cc
 
-.deps
-.libs
+/misc/systemd/nix-daemon.service
+/misc/systemd/nix-daemon.socket
+/misc/upstart/nix-daemon.conf
+
+/src/resolve-system-dependencies/resolve-system-dependencies
+
+inst/
+
 *.a
-*.lo
-*.la
 *.o
 *.so
+*.dylib
+*.dll
+*.exe
+*.dep
 *~
+*.pc
+*.plist
 
 # GNU Global
 GPATH

.travis.yml

@@ -0,0 +1,2 @@
+os: osx
+script: ./tests/install-darwin.sh

AUTHORS

@@ -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

INSTALL

@@ -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.
-

Makefile

@@ -0,0 +1,40 @@
+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
+
+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

Makefile.am

@@ -1,44 +0,0 @@
-SUBDIRS = src perl scripts corepkgs doc misc tests
-EXTRA_DIST = substitute.mk nix.spec nix.spec.in bootstrap.sh \
-  NEWS version misc/systemd/nix-daemon.service
-
-pkginclude_HEADERS = config.h
-
-include ./substitute.mk
-
-nix.spec: nix.spec.in
-
-install-data-local: init-state
-	$(INSTALL) -d $(DESTDIR)$(sysconfdir)/nix
-	$(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) -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

Makefile.config.in

@@ -0,0 +1,38 @@
+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@
+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@

README

@@ -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/).

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/).

build.nix

@@ -1,169 +0,0 @@
-with import <nix-make/lib>;
-with pkgs;
-
-rec {
-
-  bin2c = link {
-    objects = [ (compileC { main = ./src/bin2c/bin2c.c; }) ];
-    programName = "bin2c";
-  };
-
-  bsdiff = link {
-    objects = [ (compileC { main = ./src/bsdiff-4.3/bsdiff.c; buildInputs = [ pkgs.bzip2 ]; }) ];
-    programName = "bsdiff";
-    buildInputs = [ pkgs.bzip2 ];
-    flags = "-lbz2";
-  };
-
-  bspatch = link {
-    objects = [ (compileC { main = ./src/bsdiff-4.3/bspatch.c; buildInputs = [ pkgs.bzip2 ]; }) ];
-    programName = "bspatch";
-    buildInputs = [ pkgs.bzip2 ];
-    flags = "-lbz2";
-  };
-
-  libformat = makeLibrary {
-    objects =
-      map (fn: compileC {
-        main = fn;
-        localIncludePath = [ ./src ];
-      })
-      [ ./src/boost/format/format_implementation.cc
-        ./src/boost/format/free_funcs.cc
-        ./src/boost/format/parsing.cc
-      ];
-    libraryName = "format";
-  };
-
-  libutil = makeLibrary {
-    objects =
-      map (fn: compileC {
-        main = fn;
-        localIncludePath = [ ./src/libutil ./src ./. ];
-        buildInputs = [ pkgs.openssl ];
-      })
-      [ ./src/libutil/util.cc
-        ./src/libutil/hash.cc
-        ./src/libutil/serialise.cc
-        ./src/libutil/archive.cc
-        ./src/libutil/xml-writer.cc
-        ./src/libutil/immutable.cc
-      ];
-    libraryName = "util";
-  };
-
-  libstore = makeLibrary {
-    objects =
-      map (fn: compileC {
-        main = fn;
-        localIncludePath = [ ./src/libstore ./src/libutil ./src ./. ];
-        buildInputs = [ pkgs.sqlite ];
-        cFlags = "-DNIX_STORE_DIR=\"/nix/store\" -DNIX_DATA_DIR=\"/home/eelco/Dev/nix/inst/share\" -DNIX_STATE_DIR=\"/nix/var/nix\" -DNIX_LOG_DIR=\"/foo\" -DNIX_CONF_DIR=\"/foo\" -DNIX_LIBEXEC_DIR=\"/foo\" -DNIX_BIN_DIR=\"/home/eelco/Dev/nix/inst/bin\"";
-      })
-      [ ./src/libstore/store-api.cc
-        ./src/libstore/local-store.cc
-        ./src/libstore/remote-store.cc
-        ./src/libstore/derivations.cc
-        ./src/libstore/build.cc
-        ./src/libstore/misc.cc
-        ./src/libstore/globals.cc
-        ./src/libstore/references.cc
-        ./src/libstore/pathlocks.cc
-        ./src/libstore/gc.cc
-        ./src/libstore/optimise-store.cc
-      ];
-    libraryName = "store";
-  };
-
-  libmain = makeLibrary {
-    objects =
-      map (fn: compileC {
-        main = fn;
-        localIncludePath = [ ./src/libmain ./src/libstore ./src/libutil ./src ./. ];
-      })
-      [ ./src/libmain/shared.cc ];
-    libraryName = "main";
-  };
-
-  nix_hash = link {
-    objects =
-      map (fn: compileC {
-        main = fn;
-        localIncludePath = [ ./src/nix-hash ./src/libmain ./src/libstore ./src/libutil ./src ./. ];
-      })
-      [ ./src/nix-hash/nix-hash.cc
-      ];
-    libraries = [ libformat libutil libstore libmain ];
-    buildInputs = [ pkgs.openssl pkgs.sqlite ];
-    flags = "-lssl -lsqlite3 -lstdc++";
-    programName = "nix-hash";
-  };
-
-  nix_store = link {
-    objects =
-      map (fn: compileC {
-        main = fn;
-        localIncludePath = [ ./src/nix-store ./src/libmain ./src/libstore ./src/libutil ./src ./. ];
-      })
-      [ ./src/nix-store/nix-store.cc
-        ./src/nix-store/dotgraph.cc
-        ./src/nix-store/xmlgraph.cc
-      ];
-    libraries = [ libformat libutil libstore libmain ];
-    buildInputs = [ pkgs.openssl pkgs.sqlite ];
-    flags = "-lssl -lsqlite3 -lstdc++";
-    programName = "nix-store";
-  };
-
-  libexpr = makeLibrary {
-    objects =
-      map (fn: compileC {
-        main = fn;
-        localIncludePath = [ ./src/libexpr ./src/libstore ./src/libutil ./src ./. ];
-      })
-      [ ./src/libexpr/nixexpr.cc
-        ./src/libexpr/eval.cc
-        ./src/libexpr/primops.cc
-        ./src/libexpr/lexer-tab.cc
-        ./src/libexpr/parser-tab.cc
-        ./src/libexpr/get-drvs.cc
-        ./src/libexpr/attr-path.cc
-        ./src/libexpr/value-to-xml.cc
-        ./src/libexpr/common-opts.cc
-        ./src/libexpr/names.cc
-      ];
-    libraryName = "expr";
-  };
-
-  nix_instantiate = link {
-    objects =
-      map (fn: compileC {
-        main = fn;
-        localIncludePath = [ ./src/nix-instantiate ./src/libexpr ./src/libmain ./src/libstore ./src/libutil ./src ./. ];
-      })
-      [ ./src/nix-instantiate/nix-instantiate.cc ];
-    libraries = [ libformat libutil libstore libmain libexpr ];
-    buildInputs = [ pkgs.openssl pkgs.sqlite ];
-    flags = "-lssl -lsqlite3 -lstdc++";
-    programName = "nix-instantiate";
-  };
-
-  nix_env = link {
-    objects =
-      map (fn: compileC {
-        main = fn;
-        localIncludePath = [ ./src/nix-env ./src/libexpr ./src/libmain ./src/libstore ./src/libutil ./src ./. ];
-      })
-      [ ./src/nix-env/nix-env.cc
-        ./src/nix-env/profiles.cc
-        ./src/nix-env/user-env.cc
-      ];
-    libraries = [ libformat libutil libstore libmain libexpr ];
-    buildInputs = [ pkgs.openssl pkgs.sqlite ];
-    flags = "-lssl -lsqlite3 -lstdc++";
-    programName = "nix-env";
-  };
-
-  all = [ bsdiff bspatch nix_hash nix_store nix_instantiate nix_env ];
-
-}

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:

configure.ac

@@ -1,9 +1,6 @@
-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_PROG_SED
 
@@ -19,12 +16,14 @@ AC_ARG_WITH(system, AC_HELP_STRING([--with-system=SYSTEM],
         machine_name="i686";;
      amd64)
         machine_name="x86_64";;
+     armv6|armv7)
+        machine_name="${host_cpu}l";;
      *)
         machine_name="$host_cpu";;
    esac
 
    case "$host_os" in
-     linux-gnu*)
+     linux-gnu*|linux-musl*)
         # For backward compatibility, strip the `-gnu' part.
         system="$machine_name-linux";;
      *)
@@ -50,41 +49,19 @@ 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.
+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
+AX_CXX_COMPILE_STDCXX_11
 
 
 # Use 64-bit file system calls so that we can support files > 2 GiB.
@@ -103,20 +80,7 @@ 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
-])
-
-
-# Check for vfork.
-#AC_FUNC_FORK()
+AC_CHECK_FUNCS([statvfs pipe2])
 
 
 # Check for lutimes, optionally used for changing the mtime of
@@ -142,26 +106,6 @@ 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 <linux/fs.h> (for immutable file support).
-AC_CHECK_HEADERS([linux/fs.h])
-
-
-# Check for tr1/unordered_set.
-AC_LANG_PUSH(C++)
-AC_CHECK_HEADERS([tr1/unordered_set])
-AC_LANG_POP(C++)
-
-
 AC_DEFUN([NEED_PROG],
 [
 AC_PATH_PROG($1, $2)
@@ -170,40 +114,21 @@ 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)
-
-
-# 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)
-
-
-# Figure out where to install Perl modules.
-AC_MSG_CHECKING([for the Perl installation prefix])
-perlversion=$($perl -e 'use Config; print $Config{version};')
-perlarchname=$($perl -e 'use Config; print $Config{archname};')
-AC_SUBST(perllibdir, [$\(libdir\)/perl5/site_perl/$perlversion/$perlarchname])
-AC_MSG_RESULT($perllibdir)
+AC_PATH_PROGS(brotli, brotli bro, bro)
+AC_PATH_PROG(lsof, lsof, lsof)
 
 
 NEED_PROG(cat, cat)
@@ -214,39 +139,14 @@ AC_ARG_WITH(coreutils-bin, AC_HELP_STRING([--with-coreutils-bin=PATH],
 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 (defaults to /nix/store)]),
   storedir=$withval, storedir='/nix/store')
 AC_SUBST(storedir)
 
 
-# Look for OpenSSL, an optional dependency.
-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])
-
-PKG_CHECK_MODULES([OPENSSL], [libcrypto],
-  [AC_DEFINE([HAVE_OPENSSL], [1], [Whether to use OpenSSL.])
-   CXXFLAGS="$OPENSSL_CFLAGS $CXXFLAGS"
-   have_openssl=1], [true])
-AM_CONDITIONAL(HAVE_OPENSSL, test "$have_openssl" = 1)
+# Look for OpenSSL, a required dependency.
+PKG_CHECK_MODULES([OPENSSL], [libcrypto], [CXXFLAGS="$OPENSSL_CFLAGS $CXXFLAGS"])
 
 
 # Look for libbz2, a required dependency.
@@ -260,6 +160,51 @@ AC_CHECK_HEADERS([bzlib.h], [true],
 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"])
+
+
+# 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
+  PKG_CHECK_MODULES([LIBSECCOMP], [libseccomp],
+                    [CXXFLAGS="$LIBSECCOMP_CFLAGS $CXXFLAGS"])
+fi
+
+
+# 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 -E | 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
+
+
 # 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) [default=no]]),
@@ -271,56 +216,17 @@ if test "$gc" = yes; then
 fi
 
 
-# Check for the required Perl dependencies (DBI, DBD::SQLite and WWW::Curl).
-perlFlags="-I$perllibdir"
-
-AC_ARG_WITH(dbi, AC_HELP_STRING([--with-dbi=PATH],
-  [prefix of the Perl DBI library]),
-  perlFlags="$perlFlags -I$withval")
-
-AC_ARG_WITH(dbd-sqlite, AC_HELP_STRING([--with-dbd-sqlite=PATH],
-  [prefix of the Perl DBD::SQLite library]),
-  perlFlags="$perlFlags -I$withval")
-
-AC_ARG_WITH(www-curl, AC_HELP_STRING([--with-www-curl=PATH],
-  [prefix of the Perl WWW::Curl library]),
-  perlFlags="$perlFlags -I$withval")
-
-AC_MSG_CHECKING([whether DBD::SQLite works])
-if ! $perl $perlFlags -e 'use DBI; use DBD::SQLite;' 2>&5; then
-    AC_MSG_RESULT(no)
-    AC_MSG_FAILURE([The Perl modules DBI and/or DBD::SQLite are missing.])
-fi
-AC_MSG_RESULT(yes)
-
-AC_MSG_CHECKING([whether WWW::Curl works])
-if ! $perl $perlFlags -e 'use WWW::Curl;' 2>&5; then
-    AC_MSG_RESULT(no)
-    AC_MSG_FAILURE([The Perl module WWW::Curl is missing.])
-fi
-AC_MSG_RESULT(yes)
-
-AC_SUBST(perlFlags)
-
-
-# Whether to build the Perl bindings
-AC_MSG_CHECKING([whether to build the Perl bindings])
-AC_ARG_ENABLE(perl-bindings, AC_HELP_STRING([--enable-perl-bindings],
-  [whether to build the Perl bindings (recommended) [default=yes]]),
-  perlbindings=$enableval, perlbindings=yes)
-if test "$enable_shared" = no; then
-   # Perl bindings require shared libraries.
-   perlbindings=no
-fi
-AM_CONDITIONAL(PERL_BINDINGS, test "$perlbindings" = "yes")
-AC_SUBST(perlbindings)
-AC_MSG_RESULT($perlbindings)
-
-
 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.
@@ -328,7 +234,7 @@ AC_CHECK_FUNCS([setresuid setreuid lchown])
 
 
 # Nice to have, but not essential.
-AC_CHECK_FUNCS([strsignal posix_fallocate nanosleep sysconf])
+AC_CHECK_FUNCS([strsignal posix_fallocate sysconf])
 
 
 # This is needed if bzip2 is a static library, and the Nix libraries
@@ -354,30 +260,23 @@ fi
 AC_SUBST(tarFlags)
 
 
-AM_CONFIG_HEADER([config.h])
-AC_CONFIG_FILES([Makefile
-   src/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-daemon/Makefile
-   src/nix-setuid-helper/Makefile
-   src/nix-log2xml/Makefile
-   src/bsdiff-4.3/Makefile
-   perl/Makefile
-   scripts/Makefile
-   corepkgs/Makefile
-   doc/Makefile
-   doc/manual/Makefile
-   misc/Makefile
-   misc/emacs/Makefile
-   tests/Makefile
-  ])
+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

corepkgs/Makefile.am

@@ -1,12 +0,0 @@
-all-local: config.nix
-
-files = nar.nix buildenv.nix buildenv.pl unpack-channel.nix derivation.nix fetchurl.nix \
-	imported-drv-to-derivation.nix
-
-install-exec-local:
-	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs
-	$(INSTALL_DATA) config.nix $(files) $(DESTDIR)$(datadir)/nix/corepkgs
-
-include ../substitute.mk
-
-EXTRA_DIST = config.nix.in $(files)

corepkgs/buildenv.nix

@@ -5,10 +5,9 @@ with import <nix/config.nix>;
 derivation {
   name = "user-environment";
   system = builtins.currentSystem;
-  builder = perl;
-  args = [ "-w" ./buildenv.pl ];
+  builder = nixLibexecDir + "/nix/buildenv";
 
-  manifest = manifest;
+  inherit manifest;
 
   # !!! grmbl, need structured data for passing this in a clean way.
   derivations =
@@ -23,6 +22,23 @@ derivation {
   # network traffic, so don't do that.
   preferLocalBuild = true;
 
-  # Don't build in a chroot because Nix's dependencies may not be there.
-  __noChroot = 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;
 }

corepkgs/buildenv.pl

@@ -1,171 +0,0 @@
-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'; "
-                    . "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 @pkgs;
-my @derivations = split ' ', $ENV{"derivations"};
-while (scalar @derivations) {
-    my $active = shift @derivations;
-    my $priority = shift @derivations;
-    my $outputs = shift @derivations;
-    for (my $n = 0; $n < $outputs; $n++) {
-        my $path = shift @derivations;
-        push @pkgs,
-            { path => $path
-            , active => $active ne "false"
-            , priority => int($priority) };
-    }
-}
-
-
-# Symlink to the packages that have been installed explicitly by the
-# user.  Process in priority order to reduce unnecessary
-# symlink/unlink steps.
-@pkgs = sort { $a->{priority} <=> $b->{priority} || $a->{path} cmp $b->{path} } @pkgs;
-foreach my $pkg (@pkgs) {
-    #print $pkg, " ", $pkgs{$pkg}->{priority}, "\n";
-    addPkg($pkg->{path}, $pkg->{priority}) if $pkg->{active};
-}
-
-
-# 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";

corepkgs/config.nix.in

@@ -2,15 +2,28 @@ let
   fromEnv = var: def:
     let val = builtins.getEnv var; in
     if val != "" then val else def;
-in {
-  perl = "@perl@";
-  shell = "@shell@";
+in rec {
+  shell = "@bash@";
   coreutils = "@coreutils@";
   bzip2 = "@bzip2@";
+  gzip = "@gzip@";
   xz = "@xz@";
   tar = "@tar@";
   tarFlags = "@tarFlags@";
   tr = "@tr@";
-  curl = "@curl@";
   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
+      [ ];
 }

corepkgs/fetchurl.nix

@@ -1,36 +1,35 @@
-with import <nix/config.nix>;
+{ system ? builtins.currentSystem
+, 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)
+}:
 
-{system ? builtins.currentSystem, url, outputHash ? "", outputHashAlgo ? "", md5 ? "", sha1 ? "", sha256 ? ""}:
-
-assert (outputHash != "" && outputHashAlgo != "")
-    || md5 != "" || sha1 != "" || sha256 != "";
-
-let
-
-  builder = builtins.toFile "fetchurl.sh"
-    ''
-      echo "downloading $url into $out"
-      ${curl} --fail --location --max-redirs 20 --insecure "$url" > "$out"
-    '';
-
-in
-    
 derivation {
-  name = baseNameOf (toString url);
-  builder = shell;
-  args = [ "-e" builder ];
+  builder = "builtin:fetchurl";
 
   # New-style output content requirements.
-  outputHashAlgo = if outputHashAlgo != "" then outputHashAlgo else
-      if sha256 != "" then "sha256" else if sha1 != "" then "sha1" else "md5";
-  outputHash = if outputHash != "" then outputHash else
-      if sha256 != "" then sha256 else if sha1 != "" then sha1 else md5;
-  
-  inherit system url;
+  inherit outputHashAlgo outputHash;
+  outputHashMode = if unpack || executable then "recursive" else "flat";
+
+  inherit name system url executable unpack;
 
   # No need to double the amount of network traffic
   preferLocalBuild = true;
 
-  # Don't build in a chroot because Nix's dependencies may not be there.
-  __noChroot = 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 ];
 }

corepkgs/imported-drv-to-derivation.nix

@@ -1,10 +1,10 @@
-attrs @ { drvPath, outputs, ... }:
+attrs @ { drvPath, outputs, name, ... }:
 
 let
 
   commonAttrs = (builtins.listToAttrs outputsList) //
     { all = map (x: x.value) outputsList;
-      inherit drvPath;
+      inherit drvPath name;
       type = "derivation";
     };
 

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

corepkgs/nar.nix

@@ -1,43 +0,0 @@
-with import <nix/config.nix>;
-
-let
-
-  builder = builtins.toFile "nar.sh"
-    ''
-      export PATH=${nixBinDir}:${coreutils}
-
-      if [ $compressionType = "xz" ]; then
-        ext=xz
-        compressor="${xz} -9"
-      else
-        ext=bz2
-        compressor="${bzip2}"
-      fi
-
-      echo "packing ‘$storePath’..."
-      mkdir $out
-      dst=$out/tmp.nar.$ext
-
-      set -o pipefail
-      nix-store --dump "$storePath" | $compressor > $dst
-
-      hash=$(nix-hash --flat --type $hashAlgo --base32 $dst)
-      echo -n $hash > $out/nar-compressed-hash
-
-      mv $dst $out/$hash.nar.$ext
-    '';
-
-in
-
-{ storePath, hashAlgo, compressionType }:
-
-derivation {
-  name = "nar";
-  system = builtins.currentSystem;
-  builder = shell;
-  args = [ "-e" builder ];
-  inherit storePath hashAlgo compressionType;
-
-  # Don't build in a chroot because Nix's dependencies may not be there.
-  __noChroot = true;
-}

corepkgs/unpack-channel.nix

@@ -6,13 +6,18 @@ let
     ''
       mkdir $out
       cd $out
-      pat="\.xz\$"
-      if [[ "$src" =~ $pat ]]; then
+      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
-      mv * $out/$channelName
+      if [ * != $channelName ]; then
+        mv * $out/$channelName
+      fi
       if [ -n "$binaryCacheURL" ]; then
         mkdir $out/binary-caches
         echo -n "$binaryCacheURL" > $out/binary-caches/$channelName
@@ -34,6 +39,5 @@ derivation {
   # No point in doing this remotely.
   preferLocalBuild = true;
 
-  # Don't build in a chroot because Nix's dependencies may not be there.
-  __noChroot = true;
+  inherit chrootDeps;
 }

doc/Makefile.am

@@ -1 +0,0 @@
-SUBDIRS = manual

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).

doc/manual/Makefile.am

@@ -1,117 +0,0 @@
-XMLLINT = $(xmllint) --nonet $(xmlflags)
-XSLTPROC = $(xsltproc) --nonet $(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
-
-man5_MANS = nix.conf.5
-
-man8_MANS = nix-daemon.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 opt-inst-syn.xml \
- env-common.xml quick-start.xml nix-lang-ref.xml glossary.xml \
- conf-file.xml release-notes.xml \
- style.css images
-
-# Do XInclude processing.
-manual.xmli: $(MANUAL_SRCS) version.txt
-	$(XMLLINT) --xinclude $< -o $@.tmp
-	mv $@.tmp $@
-
-# Note: RelaxNG validation requires xmllint >= 2.7.4.
-manual.is-valid: manual.xmli
-	$(XSLTPROC) --novalid --stringparam profile.condition manual \
-	  $(docbookxsl)/profiling/profile.xsl $< 2> /dev/null | \
-	  $(XMLLINT) --noout --relaxng $(docbookrng)/docbook.rng -
-	touch $@
-
-version.txt:
-	echo -n $(VERSION) > version.txt
-
-man $(MANS): manual.is-valid
-	$(XSLTPROC) --stringparam profile.condition manpage \
-	  $(docbookxsl)/profiling/profile.xsl manual.xmli 2> /dev/null | \
-	  $(XSLTPROC) $(docbookxsl)/manpages/docbook.xsl -
-
-manual.html: $(MANUAL_SRCS) manual.is-valid images
-	$(XSLTPROC) --xinclude --stringparam profile.condition manual \
-	  $(docbookxsl)/profiling/profile.xsl manual.xml | \
-	  $(XSLTPROC) --output manual.html $(docbookxsl)/html/docbook.xsl -
-
-manual.pdf: $(MANUAL_SRCS) manual.is-valid images
-	if test "$(dblatex)" != ""; then \
-		$(XSLTPROC) --xinclude --stringparam profile.condition manual \
-		  $(docbookxsl)/profiling/profile.xsl manual.xml | \
-		  $(dblatex) -o manual.pdf $(dblatex_opts) -; \
-	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) --xinclude --output $@ $(NEWS_OPTS) \
-	  $(docbookxsl)/html/docbook.xsl release-notes.xml
-
-NEWS.txt: release-notes.xml
-	$(XSLTPROC) --xinclude quote-literals.xsl release-notes.xml | \
-	  $(XSLTPROC) --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.xmli manual.is-valid version.txt $(MANS) NEWS.html NEWS.txt
-
-EXTRA_DIST = $(MANUAL_SRCS) $(FIGURES) $(KEEP)
-
-DISTCLEANFILES = $(KEEP)

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>

doc/manual/advanced-topics/distributed-builds.xml

@@ -1,17 +1,19 @@
 <chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id='chap-distributed-builds'>
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id='chap-distributed-builds'>
 
-<title>Setting Up Distributed Builds</title>
+<title>Distributed Builds</title>
 
-<para>Nix supports distributed builds: a local Nix installation can
+<para>Nix supports distributed builds, where a local Nix installation can
 forward Nix builds to other machines over the network.  This allows
 multiple builds to be performed in parallel (thus improving
 performance) and allows Nix to perform multi-platform builds in a
 semi-transparent way.  For instance, if you perform a build for a
-<literal>powerpc-darwin</literal> on an <literal>i686-linux</literal>
+<literal>x86_64-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>
+<literal>x86_64-darwin</literal> machine, if available.</para>
 
 <para>You can enable distributed builds by setting the environment
 variable <envar>NIX_BUILD_HOOK</envar> to point to a program that Nix
@@ -20,15 +22,12 @@ will call whenever it wants to build a derivation.  The build hook
 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>
+results back.</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@mcflurry.labs.cs.uu.nl  x86_64-darwin   /home/nix/.ssh/id_quarterpounder_auto  2
 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        8 2 kvm perf
@@ -40,15 +39,16 @@ purposes.  It uses <command>ssh</command> and
 <command>nix-copy-closure</command> to copy the build inputs and
 outputs and perform the remote build.  To use it, you should set
 <envar>NIX_BUILD_HOOK</envar> to
-<filename><replaceable>prefix</replaceable>/libexec/nix/build-remote.pl</filename>.
+<filename><replaceable>prefix</replaceable>/libexec/nix/build-remote</filename>.
 You should also define a list of available build machines and point
-the environment variable <envar>NIX_REMOTE_SYSTEMS</envar> to it.  An
+the environment variable <envar>NIX_REMOTE_SYSTEMS</envar> to
+it. <envar>NIX_REMOTE_SYSTEMS</envar> must be an absolute path. 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
@@ -56,7 +56,7 @@ bits of information:
   <filename>~/.ssh/config</filename>.</para></listitem>
 
   <listitem><para>A comma-separated list of Nix platform type
-  identifiers, such as <literal>powerpc-darwin</literal>.  It is
+  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>.</para></listitem>
 
@@ -65,7 +65,7 @@ bits of information:
   should not have a passphrase!</para></listitem>
 
   <listitem><para>The maximum number of builds that
-  <filename>build-remote.pl</filename> will execute in parallel on the
+  <filename>build-remote</filename> 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>
@@ -77,12 +77,12 @@ bits of information:
   <listitem><para>A comma-separated list of <emphasis>supported
   features</emphasis>.  If a derivation has the
   <varname>requiredSystemFeatures</varname> attribute, then
-  <filename>build-remote.pl</filename> will only perform the
+  <filename>build-remote</filename> will only perform the
   derivation on a machine that has the specified features.  For
   instance, the attribute
-  
+
 <programlisting>
-requiredSystemFeatures = [ "kvm" ];  
+requiredSystemFeatures = [ "kvm" ];
 </programlisting>
 
   will cause the build to be performed on a machine that has the
@@ -100,14 +100,6 @@ requiredSystemFeatures = [ "kvm" ];
 
 </orderedlist>
 
-You should also set up the environment variable
-<envar>NIX_CURRENT_LOAD</envar> to point at a directory (e.g.,
-<filename>/var/run/nix/current-load</filename>) that
-<filename>build-remote.pl</filename> uses to remember how many builds
-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>NIX_CURRENT_LOAD</envar>
-file.  Maybe in the future <filename>build-remote.pl</filename> will
-look at the actual remote load.</para>
-  
+</para>
+
 </chapter>

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>

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

@@ -0,0 +1,20 @@
+<part xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id='part-command-ref'>
+
+<title>Command Reference</title>
+
+<partintro>
+<para>This section lists commands and options that you can use when you
+work with Nix.</para>
+</partintro>
+
+<xi:include href="opt-common.xml" />
+<xi:include href="env-common.xml" />
+<xi:include href="main-commands.xml" />
+<xi:include href="utilities.xml" />
+<xi:include href="files.xml" />
+
+</part>

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

@@ -0,0 +1,743 @@
+<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.
+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-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-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-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-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-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 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 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-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>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-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 xml:id="conf-extra-sandbox-paths">
+    <term><literal>build-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>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>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><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>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><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><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>binary-caches-files</literal></term>
+
+    <listitem><para>A list of names of files that will be read to
+    obtain additional binary cache URLs.  The default is
+    <literal>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/channels/binary-caches/*</literal>.
+    Note that when you’re using the Nix daemon,
+    <replaceable>username</replaceable> is always equal to
+    <literal>root</literal>, so Nix will only use the binary caches
+    provided by the channels installed by root.  Do not set this
+    option to read files created by untrusted users!</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><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>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><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>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><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>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><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><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><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-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-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>
+
+
+  <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 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 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-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 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-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-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>
+
+
+</variablelist>
+
+</para>
+
+</refsection>
+
+</refentry>

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

@@ -0,0 +1,194 @@
+<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>.
+  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>

doc/manual/command-ref/files.xml

@@ -0,0 +1,14 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id='ch-files'>
+
+<title>Files</title>
+
+<para>This section lists configuration files that you can use when you
+work with Nix.</para>
+
+<xi:include href="conf-file.xml" />
+
+</chapter>

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

@@ -0,0 +1,17 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id='ch-main-commands'>
+
+<title>Main Commands</title>
+
+<para>This section lists commands and options that you can use when you
+work with Nix.</para>
+
+<xi:include href="nix-env.xml" />
+<xi:include href="nix-build.xml" />
+<xi:include href="nix-shell.xml" />
+<xi:include href="nix-store.xml" />
+
+</chapter>

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

@@ -1,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>
@@ -38,11 +39,6 @@
       </group>
       <replaceable>outlink</replaceable>
     </arg>
-    <arg>
-      <option>--run-env</option>
-      <arg><option>--command</option> <replaceable>cmd</replaceable></arg>
-      <arg><option>--exclude</option> <replaceable>regexp</replaceable></arg>
-    </arg>
     <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
   </cmdsynopsis>
 </refsynopsisdiv>
@@ -62,6 +58,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,13 +78,6 @@ a root of the Nix garbage collector.  This root disappears
 automatically when the <filename>result</filename> symlink is deleted
 or renamed.  So don’t rename the symlink.</para></warning>
 
-<para>The subcommand <command>nix-build --run-env</command> will build
-the dependencies of the derivation, but not the derivation itself.  It
-will then start an interactive shell in which all environment
-variables defined by the derivation have been set to their
-corresponding values.  This is useful for reproducing the environment
-of a derivation for development.</para>
-
 </refsection>
 
 
@@ -134,32 +130,12 @@ also <xref linkend="sec-common-options" />.</phrase></para>
 
 </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>
 
-<para>The following options apply to <command>nix-build --run-env</command>.</para>
-
-<variablelist>
-
-  <varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term>
-
-    <listitem><para>In the environment of the derivation, executeq the
-    command <replaceable>cmd</replaceable> instead of the default
-    interactive shell.</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>
-
-</variablelist>
-
 </refsection>
 
 
@@ -176,20 +152,6 @@ lrwxrwxrwx  <replaceable>...</replaceable>  result -> /nix/store/d18hyl92g30l...
 $ ls ./result/bin/
 firefox  firefox-config</screen>
 
-<para>To build the dependencies of the package Pan, and start an
-interactive shell in which to build it:
-
-<screen>
-$ nix-build '&lt;nixpkgs>' --run-env -A pan
-$ tar xf $src
-$ cd pan-*
-$ ./configure
-$ make
-$ ./pan/gui/pan
-</screen>
-
-</para>
-
 <para>If a derivation has multiple outputs,
 <command>nix-build</command> will build the default (first) output.
 You can also build all outputs:
@@ -210,6 +172,25 @@ $ 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>
 
 

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 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
+    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>

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,14 @@
     <command>nix-collect-garbage</command>
     <arg><option>--delete-old</option></arg>
     <arg><option>-d</option></arg>
+    <arg><option>--delete-older-than</option> <replaceable>period</replaceable></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>--max-freed</option> <replaceable>bytes</replaceable></arg>
     <arg><option>--dry-run</option></arg>
   </cmdsynopsis>
 </refsynopsisdiv>
@@ -35,13 +38,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>
 

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,14 +22,16 @@
       <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>--bzip2</option></arg>
-    <arg><option>--xz</option></arg>
-    <arg><option>--show-progress</option></arg>
+    <!--
+    <arg><option>- -show-progress</option></arg>
+    -->
     <arg><option>--include-outputs</option></arg>
-    <arg><option>--use-substitutes</option></arg>
-    <arg><option>-s</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'>
       <replaceable>user@</replaceable><replaceable>machine</replaceable>
     </arg>
@@ -42,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
@@ -86,39 +88,21 @@ 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><replaceable>sysconfdir</replaceable>/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><replaceable>sysconfdir</replaceable>/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> / <option>--bzip2</option> / <option>--xz</option></term>
-
-    <listitem><para>Compress the dump of each path with respectively
-    <command>gzip</command>, <command>bzip2</command> or
-    <command>xz</command> before sending it.  The corresponding
-    decompression program must be installed on the target
-    machine.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--show-progress</option></term>
+  <!--
+  <varlistentry><term><option>- -show-progress</option></term>
 
     <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>
 
@@ -139,6 +123,12 @@ those paths.  If this bothers you, use
 
   </varlistentry>
 
+  <varlistentry><term><option>-v</option></term>
+
+    <listitem><para>Show verbose output.</para></listitem>
+
+  </varlistentry>
+
 </variablelist>
 
 </refsection>

doc/manual/command-ref/nix-daemon.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-daemon">
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-nix-daemon">
 
 <refmeta>
   <refentrytitle>nix-daemon</refentrytitle>
   <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>

doc/manual/command-ref/nix-env.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-env">
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-nix-env">
 
 <refmeta>
   <refentrytitle>nix-env</refentrytitle>
   <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>
@@ -65,6 +66,75 @@ be performed.  These are documented below.</para>
 
 
 
+<!--######################################################################-->
+
+<refsection><title>Selectors</title>
+
+<para>Several commands, such as <command>nix-env -q</command> and
+<command>nix-env -i</command>, take a list of arguments that specify
+the packages on which to operate. These are extended regular
+expressions that must match the entire name of the package. (For
+details on regular expressions, see
+<citerefentry><refentrytitle>regex</refentrytitle><manvolnum>7</manvolnum></citerefentry>.)
+The match is case-sensitive. The regular expression can optionally be
+followed by a dash and a version number; if omitted, any version of
+the package will match.  Here are some examples:
+
+<variablelist>
+
+  <varlistentry>
+    <term><literal>firefox</literal></term>
+    <listitem><para>Matches the package name
+    <literal>firefox</literal> and any version.</para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><literal>firefox-32.0</literal></term>
+    <listitem><para>Matches the package name
+    <literal>firefox</literal> and version
+    <literal>32.0</literal>.</para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><literal>gtk\\+</literal></term>
+    <listitem><para>Matches the package name
+    <literal>gtk+</literal>. The <literal>+</literal> character must
+    be escaped using a backslash to prevent it from being interpreted
+    as a quantifier, and the backslash must be escaped in turn with
+    another backslash to ensure that the shell passes it
+    on.</para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><literal>.\*</literal></term>
+    <listitem><para>Matches any package name. This is the default for
+    most commands.</para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><literal>'.*zip.*'</literal></term>
+    <listitem><para>Matches any package name containing the string
+    <literal>zip</literal>. Note the dots: <literal>'*zip*'</literal>
+    does not work, because in a regular expression, the character
+    <literal>*</literal> is interpreted as a
+    quantifier.</para></listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><literal>'.*(firefox|chromium).*'</literal></term>
+    <listitem><para>Matches any package name containing the strings
+    <literal>firefox</literal> or
+    <literal>chromium</literal>.</para></listitem>
+  </varlistentry>
+
+</variablelist>
+
+</para>
+
+</refsection>
+
+
+
 <!--######################################################################-->
 
 <refsection><title>Common options</title>
@@ -76,20 +146,26 @@ also <xref linkend="sec-common-options" />.</phrase></para>
 
 <variablelist>
 
-  <varlistentry><term><option>--file</option></term>
-    <term><option>-f</option></term>
+  <varlistentry><term><option>--file</option> / <option>-f</option> <replaceable>path</replaceable></term>
 
     <listitem><para>Specifies the Nix expression (designated below as
     the <emphasis>active Nix expression</emphasis>) used by the
     <option>--install</option>, <option>--upgrade</option>, and
     <option>--query --available</option> operations to obtain
     derivations.  The default is
-    <filename>~/.nix-defexpr</filename>.</para></listitem>
+    <filename>~/.nix-defexpr</filename>.</para>
+
+    <para>If the argument 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>
+
+    </listitem>
 
   </varlistentry>
 
-  <varlistentry><term><option>--profile</option></term>
-    <term><option>-p</option></term>
+  <varlistentry><term><option>--profile</option> / <option>-p</option> <replaceable>path</replaceable></term>
 
     <listitem><para>Specifies the profile to be used by those
     operations that operate on a profile (designated below as the
@@ -153,11 +229,10 @@ also <xref linkend="sec-common-options" />.</phrase></para>
     default.</para>
 
     <para>The Nix expressions in this directory are combined into a
-    single attribute set, with each file as an attribute that has the
-    name of the file.  Thus, if <filename>~/.nix-defexpr</filename>
-    contains two files, <filename>foo</filename> and
-    <filename>bar</filename>, then the default Nix expression will
-    essentially be
+    single set, with each file as an attribute that has the name of
+    the file.  Thus, if <filename>~/.nix-defexpr</filename> contains
+    two files, <filename>foo</filename> and <filename>bar</filename>,
+    then the default Nix expression will essentially be
 
 <programlisting>
 {
@@ -209,6 +284,10 @@ also <xref linkend="sec-common-options" />.</phrase></para>
     <arg choice='plain'><option>--preserve-installed</option></arg>
     <arg choice='plain'><option>-P</option></arg>
   </group>
+  <group choice='opt'>
+    <arg choice='plain'><option>--remove-all</option></arg>
+    <arg choice='plain'><option>-r</option></arg>
+  </group>
   <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
 </cmdsynopsis>
 
@@ -258,7 +337,7 @@ number of possible ways:
   <emphasis>attribute paths</emphasis> that select attributes from the
   top-level Nix expression.  This is faster than using derivation
   names and unambiguous.  To find out the attribute paths of available
-  packages, use <literal>nix-env -qaP '*'</literal>.</para></listitem>
+  packages, use <literal>nix-env -qaP</literal>.</para></listitem>
 
   <listitem><para>If <option>--from-profile</option>
   <replaceable>path</replaceable> is given,
@@ -272,7 +351,7 @@ number of possible ways:
   linkend="ss-functions">functions</link> that are called with the
   active Nix expression as their single argument.  The derivations
   returned by those function calls are installed.  This allows
-  derivations to be specified in a unambiguous way, which is necessary
+  derivations to be specified in an unambiguous way, which is necessary
   if there are multiple derivations with the same
   name.</para></listitem>
 
@@ -286,6 +365,10 @@ number of possible ways:
   linkend="rsec-nix-store-realise">realised</link> and
   installed.</para></listitem>
 
+  <listitem><para>By default all outputs are installed for each derivation.
+  That can be reduced by setting <literal>meta.outputsToInstall</literal>.
+  </para></listitem> <!-- TODO: link nixpkgs docs on the ability to override those. -->
+
 </itemizedlist>
 
 </para>
@@ -297,7 +380,7 @@ number of possible ways:
 
 <variablelist>
 
-  <varlistentry><term><option>--prebuild-only</option> / <option>-b</option></term>
+  <varlistentry><term><option>--prebuilt-only</option> / <option>-b</option></term>
 
     <listitem><para>Use only derivations for which a substitute is
     registered, i.e., there is a pre-built binary available that can
@@ -318,6 +401,16 @@ number of possible ways:
 
   </varlistentry>
 
+  <varlistentry><term><option>--remove-all</option></term>
+    <term><option>-r</option></term>
+
+    <listitem><para>Remove all previously installed packages first.
+    This is equivalent to running <literal>nix-env -e '.*'</literal>
+    first, except that everything happens in a single
+    transaction.</para></listitem>
+
+  </varlistentry>
+
 </variablelist>
 
 </refsection>
@@ -333,7 +426,7 @@ $ nix-env --install gcc-3.3.2
 installing `gcc-3.3.2'
 uninstalling `gcc-3.1'</screen>
 
-Note the the previously installed version is removed, since
+Note the previously installed version is removed, since
 <option>--preserve-installed</option> was not specified.</para>
 
 <para>To install an arbitrary version:
@@ -355,7 +448,7 @@ $ nix-env -i -A xorg.xorgserver</screen>
 <para>To install all derivations in the Nix expression <filename>foo.nix</filename>:
 
 <screen>
-$ nix-env -f ~/foo.nix -i '*'</screen>
+$ nix-env -f ~/foo.nix -i '.*'</screen>
 
 </para>
 
@@ -391,28 +484,34 @@ $ nix-env -f ./foo.nix -i -E \
 I.e., this evaluates to <literal>(f: (f {system =
 "i686-linux";}).subversionWithJava) (import ./foo.nix)</literal>, thus
 selecting the <literal>subversionWithJava</literal> attribute from the
-attribute set returned by calling the function defined in
+set returned by calling the function defined in
 <filename>./foo.nix</filename>.</para>
 
 <para>A dry-run tells you which paths will be downloaded or built from
 source:
 
 <screen>
-$ nix-env -f pkgs/top-level/all-packages.nix -i f-spot --dry-run
+$ nix-env -f '&lt;nixpkgs>' -iA hello --dry-run
 (dry run; not doing anything)
-installing `f-spot-0.0.10'
-the following derivations will be built:
-  /nix/store/0g63jv9aagwbgci4nnzs2dkxqz84kdja-libgnomeprintui-2.12.1.tar.bz2.drv
-  /nix/store/0gfarvxq6sannsdw8a1ir40j1ys2mqb4-ORBit2-2.14.2.tar.bz2.drv
-  /nix/store/0i9gs5zc04668qiy60ga2rc16abkj7g8-sqlite-2.8.17.drv
-  <replaceable>...</replaceable>
-the following paths will be substituted:
-  /nix/store/8zbipvm4gp9jfqh9nnk1n3bary1a37gs-perl-XML-Parser-2.34
-  /nix/store/b8a2bg7gnyvvvjjibp4axg9x1hzkw36c-mono-1.1.4
+installing ‘hello-2.10’
+these paths will be fetched (0.04 MiB download, 0.19 MiB unpacked):
+  /nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10
   <replaceable>...</replaceable></screen>
 
 </para>
 
+<para>To install Firefox from the latest revision in the Nixpkgs/NixOS
+14.12 channel:
+
+<screen>
+$ nix-env -f https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz -iA firefox
+</screen>
+
+(The GitHub repository <literal>nixpkgs-channels</literal> is updated
+automatically from the main <literal>nixpkgs</literal> repository
+after certain tests have succeeded and binaries have been built and
+uploaded to the binary cache at <uri>cache.nixos.org</uri>.)</para>
+
 </refsection>
 
 </refsection>
@@ -523,7 +622,7 @@ upgrading `gcc-3.4' to `gcc-3.3.2'
 $ nix-env --upgrade pan
 <lineannotation>(no upgrades available, so nothing happens)</lineannotation>
 
-$ nix-env -u '*' <lineannotation>(try to upgrade everything)</lineannotation>
+$ nix-env -u <lineannotation>(try to upgrade everything)</lineannotation>
 upgrading `hello-2.1.2' to `hello-2.1.3'
 upgrading `mozilla-1.2' to `mozilla-1.4'</screen>
 
@@ -610,7 +709,45 @@ paths designated by the symbolic names
 
 <screen>
 $ nix-env --uninstall gcc
-$ nix-env -e '*' <lineannotation>(remove everything)</lineannotation></screen>
+$ nix-env -e '.*' <lineannotation>(remove everything)</lineannotation></screen>
+
+</refsection>
+
+</refsection>
+
+
+
+<!--######################################################################-->
+
+<refsection xml:id="rsec-nix-env-set"><title>Operation <option>--set</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-env</command>
+  <arg choice='plain'><option>--set</option></arg>
+  <arg choice='plain'><replaceable>drvname</replaceable></arg>
+</cmdsynopsis>
+</refsection>
+
+<refsection><title>Description</title>
+
+<para>The <option>--set</option> operation modifies the current generation of a
+profile so that it contains exactly the specified derivation, and nothing else.
+</para>
+
+</refsection>
+
+<refsection><title>Examples</title>
+
+<para>
+The following updates a profile such that its current generation will contain
+just Firefox:
+
+<screen>
+$ nix-env -p /nix/var/nix/profiles/browser --set firefox</screen>
+
+</para>
 
 </refsection>
 
@@ -686,13 +823,13 @@ After this, <command>nix-env -u</command> will ignore Firefox.</para>
 Firefox while the old remains part of the profile:
 
 <screen>
-$ nix-env -q \*
+$ nix-env -q
 firefox-2.0.0.9 <lineannotation>(the current one)</lineannotation>
 
 $ nix-env --preserve-installed -i firefox-2.0.0.11
 installing `firefox-2.0.0.11'
 building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment'
-Collission between `/nix/store/<replaceable>...</replaceable>-firefox-2.0.0.11/bin/firefox'
+collision between `/nix/store/<replaceable>...</replaceable>-firefox-2.0.0.11/bin/firefox'
   and `/nix/store/<replaceable>...</replaceable>-firefox-2.0.0.9/bin/firefox'.
 <lineannotation>(i.e., can’t have two active at the same time)</lineannotation>
 
@@ -702,7 +839,7 @@ setting flag on `firefox-2.0.0.9'
 $ nix-env --preserve-installed -i firefox-2.0.0.11
 installing `firefox-2.0.0.11'
 
-$ nix-env -q \*
+$ nix-env -q
 firefox-2.0.0.11 <lineannotation>(the enabled one)</lineannotation>
 firefox-2.0.0.9 <lineannotation>(the disabled one)</lineannotation></screen>
 
@@ -771,6 +908,7 @@ $ nix-env --set-flag priority 10 gcc</screen>
   <sbr />
 
   <arg><option>--xml</option></arg>
+  <arg><option>--json</option></arg>
   <arg>
     <group choice='req'>
       <arg choice='plain'><option>--prebuilt-only</option></arg>
@@ -802,8 +940,7 @@ profile (<option>--installed</option>), or the derivations that are
 available for installation in the active Nix expression
 (<option>--available</option>).  It only prints information about
 derivations whose symbolic name matches one of
-<replaceable>names</replaceable>.  The wildcard <literal>*</literal>
-shows all derivations.</para>
+<replaceable>names</replaceable>.</para>
 
 <para>The derivations are sorted by their <literal>name</literal>
 attributes.</para>
@@ -864,7 +1001,14 @@ user environment elements, etc. -->
 
   </varlistentry>
 
-  <varlistentry><term><option>--prebuild-only</option> / <option>-b</option></term>
+  <varlistentry><term><option>--json</option></term>
+
+    <listitem><para>Print the result in a JSON representation suitable
+    for automatic processing by other tools.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--prebuilt-only</option> / <option>-b</option></term>
 
     <listitem><para>Show only derivations for which a substitute is
     registered, i.e., there is a pre-built binary available that can
@@ -990,7 +1134,7 @@ user environment elements, etc. -->
 
     <listitem><para>Print all of the meta-attributes of the
     derivation.  This option is only available with
-    <option>--xml</option>.</para></listitem>
+    <option>--xml</option> or <option>--json</option>.</para></listitem>
 
   </varlistentry>
 
@@ -1001,48 +1145,102 @@ user environment elements, etc. -->
 
 <refsection><title>Examples</title>
 
+<para>To show installed packages:
+
 <screen>
-$ nix-env -q '*' <lineannotation>(show installed derivations)</lineannotation>
+$ nix-env -q
 bison-1.875c
 docbook-xml-4.2
 firefox-1.0.4
 MPlayer-1.0pre7
 ORBit2-2.8.3
-...
+<replaceable>…</replaceable>
+</screen>
 
-$ nix-env -qa '*' <lineannotation>(show available derivations)</lineannotation>
+</para>
+
+<para>To show available packages:
+
+<screen>
+$ nix-env -qa
 firefox-1.0.7
 GConf-2.4.0.1
 MPlayer-1.0pre7
 ORBit2-2.8.3
-...
+<replaceable>…</replaceable>
+</screen>
 
-$ nix-env -qas '*' <lineannotation>(show status of available derivations)</lineannotation>
+</para>
+
+<para>To show the status of available packages:
+
+<screen>
+$ nix-env -qas
 -P- firefox-1.0.7   <lineannotation>(not installed but present)</lineannotation>
 --S GConf-2.4.0.1   <lineannotation>(not present, but there is a substitute for fast installation)</lineannotation>
 --S MPlayer-1.0pre3 <lineannotation>(i.e., this is not the installed MPlayer, even though the version is the same!)</lineannotation>
 IP- ORBit2-2.8.3    <lineannotation>(installed and by definition present)</lineannotation>
-...
+<replaceable>…</replaceable>
+</screen>
 
-<lineannotation>(show available derivations in the Nix expression <!-- !!! <filename>-->foo.nix<!-- </filename> -->)</lineannotation>
-$ nix-env -f ./foo.nix -qa '*'
+</para>
+
+<para>To show available packages in the Nix expression <filename>foo.nix</filename>:
+
+<screen>
+$ nix-env -f ./foo.nix -qa
 foo-1.2.3
+</screen>
 
-$ nix-env -qc '*' <lineannotation>(compare installed versions to what’s available)</lineannotation>
+</para>
+
+<para>To compare installed versions to what’s available:
+
+<screen>
+$ nix-env -qc
 <replaceable>...</replaceable>
 acrobat-reader-7.0 - ?      <lineannotation>(package is not available at all)</lineannotation>
 autoconf-2.59      = 2.59   <lineannotation>(same version)</lineannotation>
 firefox-1.0.4      &lt; 1.0.7  <lineannotation>(a more recent version is available)</lineannotation>
 <replaceable>...</replaceable>
+</screen>
 
-<lineannotation>(show info about a specific package, in XML)</lineannotation>
-$ nix-env -qa --xml --description firefox
-<![CDATA[<?xml version='1.0' encoding='utf-8'?>
-<items>
-  <item attrPath="0.0.firefoxWrapper"
-    description="Mozilla Firefox - the browser, reloaded (with various plugins)"
-    name="firefox-1.5.0.7" system="i686-linux" />
-</items>]]></screen>
+</para>
+
+<para>To show all packages with “<literal>zip</literal>” in the name:
+
+<screen>
+$ nix-env -qa '.*zip.*'
+bzip2-1.0.6
+gzip-1.6
+zip-3.0
+<replaceable>…</replaceable>
+</screen>
+
+</para>
+
+<para>To show all packages with “<literal>firefox</literal>” or
+“<literal>chromium</literal>” in the name:
+
+<screen>
+$ nix-env -qa '.*(firefox|chromium).*'
+chromium-37.0.2062.94
+chromium-beta-38.0.2125.24
+firefox-32.0.3
+firefox-with-plugins-13.0.1
+<replaceable>…</replaceable>
+</screen>
+
+</para>
+
+<para>To show all packages in the latest revision of the Nixpkgs
+repository:
+
+<screen>
+$ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa
+</screen>
+
+</para>
 
 </refsection>
 
@@ -1146,10 +1344,13 @@ $ nix-env --list-generations
 <refsection><title>Description</title>
 
 <para>This operation deletes the specified generations of the current
-profile.  The generations can be a list of generation numbers, or the
+profile.  The generations can be a list of generation numbers, the
 special value <literal>old</literal> to delete all non-current
-generations.  Periodically deleting old generations is important to
-make garbage collection effective.</para>
+generations, or a value such as <literal>30d</literal> to delete all
+generations older than the specified number of days (except for the
+generation that was active at that point in time).
+Periodically deleting old generations is important to make garbage
+collection effective.</para>
 
 </refsection>
 
@@ -1158,6 +1359,8 @@ make garbage collection effective.</para>
 <screen>
 $ nix-env --delete-generations 3 4 8
 
+$ nix-env --delete-generations 30d
+
 $ nix-env -p other_profile --delete-generations old</screen>
 
 </refsection>
@@ -1244,7 +1447,7 @@ wrapper around <option>--list-generations</option> and
 $ nix-env --rollback
 switching from generation 92 to 91
 
-$ nix-env --rolback
+$ nix-env --rollback
 error: no generation older than the current (91) exists</screen>
 
 </refsection>

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
@@ -121,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>

doc/manual/command-ref/nix-instantiate.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-instantiate">
-  
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-nix-instantiate">
+
 <refmeta>
   <refentrytitle>nix-instantiate</refentrytitle>
   <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>
@@ -18,7 +19,16 @@
 <refsynopsisdiv>
   <cmdsynopsis>
     <command>nix-instantiate</command>
-    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
+    <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'>
@@ -29,17 +39,15 @@
     </arg>
     <arg><option>--add-root</option> <replaceable>path</replaceable></arg>
     <arg><option>--indirect</option></arg>
-    <arg>
-      <group choice='req'>
-        <arg choice='plain'><option>--parse-only</option></arg>
-        <arg choice='plain'>
-          <option>--eval-only</option>
-          <arg><option>--strict</option></arg>
-        </arg>
-        <arg choice='plain'><option>--find-file</option></arg>
-      </group>
-      <arg><option>--xml</option></arg>
-    </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>
@@ -49,8 +57,8 @@
 
 <para>The command <command>nix-instantiate</command> generates <link
 linkend="gloss-derivation">store derivations</link> from (high-level)
-Nix expressions.  It loads and evaluates the Nix expressions in each
-of <replaceable>files</replaceable> (which defaults to
+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
@@ -60,12 +68,6 @@ on standard output.</para>
 <literal>-</literal>, then a Nix expression will be read from standard
 input.</para>
 
-<para>Most users and developers don’t need to use this command
-(<command>nix-env</command> and <command>nix-build</command> perform
-store derivation instantiation from Nix expressions automatically).
-It is most commonly used for implementing new deployment
-policies.</para>
-
 <para condition="manual">See also <xref linkend="sec-common-options"
 /> for a list of common options.</para>
 
@@ -85,50 +87,39 @@ policies.</para>
 
   </varlistentry>
 
-    
-  <varlistentry><term><option>--parse-only</option></term>
-  
+  <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-only</option></term>
-  
+
+  <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>NIX_PATH</envar> environment variable).
-    If found, print the corresponding absolute paths on standard
-    output.  For instance, if <envar>NIX_PATH</envar> is
+    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>--xml</option></term>
-
-    <listitem><para>When used with <option>--parse-only</option> and
-    <option>--eval-only</option>, print the resulting expression 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>--strict</option></term>
 
-    <listitem><para>When used with <option>--eval-only</option>,
+    <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>
@@ -140,6 +131,35 @@ policies.</para>
 
   </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">
@@ -168,19 +188,34 @@ dr-xr-xr-x    2 eelco    users        4096 1970-01-01 01:00 lib
 
 </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>
-$ echo '"foo" + "bar"' | nix-instantiate --parse-only -
-OpPlus(Str("foo"),Str("bar"))
+$ nix-instantiate --parse -E '1 + 2'
+1 + 2
 
-$ echo '"foo" + "bar"' | nix-instantiate --eval-only -
-Str("foobar")
+$ nix-instantiate --eval -E '1 + 2'
+3
 
-$ echo '"foo" + "bar"' | nix-instantiate --eval-only --xml -
+$ nix-instantiate --eval --xml -E '1 + 2'
 <![CDATA[<?xml version='1.0' encoding='utf-8'?>
 <expr>
-  <string value="foobar" />
+  <int value="3" />
 </expr>]]></screen>
 
 </para>
@@ -188,28 +223,28 @@ $ echo '"foo" + "bar"' | nix-instantiate --eval-only --xml -
 <para>The difference between non-strict and strict evaluation:
 
 <screen>
-$ echo 'rec { x = "foo"; y = x; }' | nix-instantiate --eval-only --xml -
+$ 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>]]>
+  <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>
-$ echo 'rec { x = "foo"; y = x; }' | nix-instantiate --eval-only --xml --strict -
+$ 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>]]>
+  <attr name="x">
+    <string value="foo" />
+  </attr>
+  <attr name="y">
+    <string value="foo" />
+  </attr>]]>
 <replaceable>...</replaceable></screen>
 
 </para>
@@ -224,6 +259,6 @@ $ echo 'rec { x = "foo"; y = x; }' | nix-instantiate --eval-only --xml --strict
 </variablelist>
 
 </refsection>
-  
+
 
 </refentry>

doc/manual/command-ref/nix-prefetch-url.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-prefetch-url">
-  
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-nix-prefetch-url">
+
 <refmeta>
   <refentrytitle>nix-prefetch-url</refentrytitle>
   <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>
@@ -18,13 +19,16 @@
 <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
@@ -53,8 +57,8 @@ 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 environment variable <envar>PRINT_PATH</envar> is set, the path
-of the downloaded file in the Nix store is also printed.</para>
+if the option <option>--print-path</option> is used, the path of the
+downloaded file in the Nix store is also printed.</para>
 
 </refsection>
 
@@ -62,7 +66,7 @@ of the downloaded file in the Nix store is also printed.</para>
 <refsection><title>Options</title>
 
 <variablelist>
-  
+
   <varlistentry><term><option>--type</option> <replaceable>hashAlgo</replaceable></term>
 
     <listitem><para>Use the specified cryptographic hash algorithm,
@@ -72,6 +76,35 @@ of the downloaded file in the Nix store is also printed.</para>
 
   </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>
@@ -80,14 +113,19 @@ of the downloaded file in the Nix store is also printed.</para>
 <refsection><title>Examples</title>
 
 <screen>
-$ nix-prefetch-url ftp://ftp.nluug.nl/pub/gnu/make/make-3.80.tar.bz2
-0bbd1df101bc0294d440471e50feca71
+$ nix-prefetch-url ftp://ftp.gnu.org/pub/gnu/hello/hello-2.10.tar.gz
+0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
 
-$ PRINT_PATH=1 nix-prefetch-url ftp://ftp.nluug.nl/pub/gnu/make/make-3.80.tar.bz2
-0bbd1df101bc0294d440471e50feca71
-/nix/store/wvyz8ifdn7wyz1p3pqyn0ra45ka2l492-make-3.80.tar.bz2</screen>
+$ 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>

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>

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>
@@ -111,7 +112,7 @@ lrwxrwxrwx    1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r1134
     </listitem>
 
   </varlistentry>
-    
+
 </variablelist>
 
 <variablelist condition="manpage">
@@ -120,7 +121,7 @@ lrwxrwxrwx    1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r1134
 
 </refsection>
 
-  
+
 
 <!--######################################################################-->
 
@@ -141,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:
 
@@ -164,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>
 
@@ -193,17 +194,36 @@ printed.)</para>
 
   </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>
@@ -211,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>
+
+
 
 <!--######################################################################-->
 
@@ -239,7 +326,7 @@ linkend="sec-nix-build"><command>nix-build</command></link> does.</para>
 </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
@@ -250,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>
@@ -294,11 +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>
-    
+    <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>
@@ -306,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
@@ -322,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'
@@ -344,7 +435,7 @@ $ nix-store --gc --max-freed $((100 * 1024 * 1024))</screen>
 </refsection>
 
 
-  
+
 <!--######################################################################-->
 
 <refsection><title>Operation <option>--delete</option></title>
@@ -429,7 +520,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
@@ -449,16 +540,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>
@@ -466,12 +557,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>
@@ -481,7 +572,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>
@@ -496,10 +587,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>
@@ -513,13 +604,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
@@ -527,9 +618,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
@@ -538,9 +629,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
@@ -551,7 +642,7 @@ query is applied to the target of the symlink.</para>
   </varlistentry>
 
   <varlistentry><term><option>--deriver</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
@@ -562,7 +653,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
@@ -575,7 +666,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
@@ -587,7 +678,7 @@ query is applied to the target of the symlink.</para>
   </varlistentry>
 
   <varlistentry><term><option>--binding</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
@@ -597,7 +688,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
@@ -607,7 +698,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
@@ -618,7 +709,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>
@@ -634,7 +725,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
@@ -719,7 +810,7 @@ $ nix-store -q --roots $(which svn)
 
 </refsection>
 
-  
+
 
 <!--######################################################################-->
 
@@ -735,11 +826,11 @@ $ nix-store -q --roots $(which svn)
 </refsection>
 
 <refsection><title>Description</title>
-            
+
 <para>TODO</para>
 
 </refsection>
-            
+
 </refsection>
 -->
 
@@ -794,7 +885,7 @@ $ nix-store --add ./foo.c
 </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
@@ -807,32 +898,32 @@ in Nix itself.</para>
 <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>
 
@@ -851,15 +942,15 @@ in Nix itself.</para>
 </refsection>
 
 <refsection><title>Description</title>
-            
-<para>The operation <option>--verify-paths</option> compares the
+
+<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:
@@ -871,7 +962,7 @@ $ nix-store --verify-path $(nix-store -qR $(which svn))
 </para>
 
 </refsection>
-            
+
 </refsection>
 
 
@@ -889,7 +980,7 @@ $ nix-store --verify-path $(nix-store -qR $(which svn))
 </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
@@ -902,7 +993,7 @@ 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>
@@ -917,7 +1008,7 @@ fetching path `/nix/store/d7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13'...
 </screen>
 
 </refsection>
-            
+
 </refsection>
 
 
@@ -935,7 +1026,7 @@ fetching path `/nix/store/d7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13'...
 </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
@@ -966,7 +1057,7 @@ links, but not other types of files (such as device nodes).</para>
 --restore</literal>.</para>
 
 </refsection>
-            
+
 
 </refsection>
 
@@ -985,13 +1076,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>
 
@@ -1010,7 +1101,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
@@ -1024,20 +1115,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>
 
@@ -1055,17 +1146,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>
 
@@ -1083,7 +1174,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
@@ -1100,7 +1191,7 @@ on the achieved savings is printed on standard error.</para>
 progress indication.</para>
 
 </refsection>
-            
+
 <refsection><title>Example</title>
 
 <screen>
@@ -1134,7 +1225,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
@@ -1143,12 +1234,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>
@@ -1180,14 +1271,14 @@ 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>
 
 
@@ -1204,13 +1295,13 @@ 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>
 
 
@@ -1228,103 +1319,76 @@ loads it into the Nix database.</para>
 </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/7c8asx3yfrg5dg1gzhzyq2236zfgibnm-stdenv'
+export stdenv; stdenv='/nix/store/7c8asx3yfrg5dg1gzhzyq2236zfgibnn-stdenv'
 export system; system='x86_64-linux'
-export _args; _args='-e /nix/store/9krlzvny65gdc8s7kpb6lkx8cd02c25b-default-builder.sh'
+export _args; _args='-e /nix/store/9krlzvny65gdc8s7kpb6lkx8cd02c25c-default-builder.sh'
 </screen>
 
 </refsection>
-            
+
 </refsection>
 
 
 <!--######################################################################-->
 
-<refsection><title>Operation <option>--query-failed-paths</option></title>
+<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>--query-failed-paths</option></arg>
+    <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>If build failure caching is enabled through the
-<literal>build-cache-failures</literal> configuration option, the
-operation <option>--query-failed-paths</option> will print out all
-store paths that have failed to build.</para>
+
+<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><title>Example</title>
 
-<screen>
-$ nix-store --query-failed-paths
-/nix/store/000zi5dcla86l92jn1g997jb06sidm7x-perl-PerlMagick-6.59
-/nix/store/0011iy7sfwbc1qj5a1f6ifjnbcdail8a-haskell-gitit-ghc7.0.4-0.8.1
-/nix/store/001c0yn1hkh86gprvrb46cxnz3pki7q3-gamin-0.1.10
-<replaceable>…</replaceable>
-</screen>
-
-</refsection>
-            
-</refsection>
-
-
-<!--######################################################################-->
-
-<refsection><title>Operation <option>--clear-failed-paths</option></title>
-
-<refsection>
-  <title>Synopsis</title>
-  <cmdsynopsis>
-    <command>nix-store</command>
-    <arg choice='plain'><option>--clear-failed-paths</option></arg>
-    <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
-  </cmdsynopsis>
-</refsection>
-
-<refsection><title>Description</title>
-            
-<para>If build failure caching is enabled through the
-<literal>build-cache-failures</literal> configuration option, the
-operation <option>--clear-failed-paths</option> clears the “failed”
-state of the given store paths, allowing them to be built again.  This
-is useful if the failure was actually transient (e.g. because the disk
-was full).</para>
-
-<para>If a path denotes a derivation, its output paths are cleared.
-You can provide the argument <literal>*</literal> to clear all store
-paths.</para>
-
-</refsection>
-            
-<refsection><title>Example</title>
-
-<screen>
-$ nix-store --clear-failed-paths /nix/store/000zi5dcla86l92jn1g997jb06sidm7x-perl-PerlMagick-6.59
-$ nix-store --clear-failed-paths *
-</screen>
-
-</refsection>
-            
 </refsection>
 
 
@@ -1337,6 +1401,6 @@ $ nix-store --clear-failed-paths *
 </variablelist>
 
 </refsection>
-  
+
 
 </refentry>

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

@@ -2,10 +2,18 @@
   
 <arg><option>--help</option></arg>
 <arg><option>--version</option></arg>
-<arg rep='repeat'><option>--verbose</option></arg>
-<arg rep='repeat'><option>-v</option></arg>
-<arg><option>--no-build-output</option></arg>
-<arg><option>-Q</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>
@@ -25,13 +33,20 @@
   <option>--timeout</option>
   <replaceable>number</replaceable>
 </arg>
-<arg><option>--keep-going</option></arg>
-<arg><option>-k</option></arg>
-<arg><option>--keep-failed</option></arg>
-<arg><option>-K</option></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>--log-type</option> <replaceable>type</replaceable></arg>
 <arg><option>--show-trace</option></arg>
 <arg>
   <option>-I</option>

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

@@ -1,6 +1,6 @@
-<section xmlns="http://docbook.org/ns/docbook" xml:id="sec-common-options">
+<chapter xmlns="http://docbook.org/ns/docbook" xml:id="sec-common-options">
 
-<title>Common options</title>
+<title>Common Options</title>
 
 
 <para>Most Nix commands accept the following command-line options:</para>
@@ -8,25 +8,24 @@
 <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,7 +125,7 @@
   <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>
 
@@ -136,14 +135,13 @@
 
   <listitem><para>Sets the maximum number of seconds that a builder
   can run.  The default is specified by the <link
-  linkend='conf-build-timeout'><literal>build-timeout</literal></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></term>
-  <term><option>-k</option></term>
+<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
@@ -151,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
@@ -181,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>
 
 
@@ -273,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.
@@ -310,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
@@ -333,31 +291,43 @@
 </varlistentry>
 
 
+<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><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>
 
 
-<varlistentry><term><option>-I</option> <replaceable>path</replaceable></term>
-  
-  <listitem><para>Add a path to the Nix expression search path.  See
-  the <envar>NIX_PATH</envar> environment variable for details.  Paths
-  added through <option>-I</option> take precedence over
+<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>
 
 
@@ -375,4 +345,4 @@
 </variablelist>
 
 
-</section>
+</chapter>

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>

doc/manual/conf-file.xml

@@ -1,432 +0,0 @@
-<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>A number of persistent settings of Nix are stored in the file
-<filename><replaceable>sysconfdir</replaceable>/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.  Here is an example
-configuration file:</para>
-
-<programlisting>
-gc-keep-outputs = true       # Nice for developers
-gc-keep-derivations = true   # Idem
-env-keep-derivations = false
-</programlisting>
-
-<para>You can override settings using the <option>--option</option>
-flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
-
-<para>The following settings 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-timeout"><term><literal>build-timeout</literal></term>
-
-    <listitem>
-
-      <para>This option defines the maximum number of seconds that a
-      builder can run.  This is useful (for instance in a 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 overriden 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 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>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 some directories from the normal file system
-    hierarchy inside the chroot.  These are the Nix store, the
-    temporary build directory (usually
-    <filename>/tmp/nix-build-<replaceable>drvname</replaceable>-<replaceable>number</replaceable></filename>),
-    the <literal>/proc</literal> filesystem, and the directories
-    listed here.  The default is <literal>/dev /dev/pts</literal>,
-    since these contain files needed by many builds (such as
-    <filename>/dev/null</filename>).  You can use the syntax
-    <literal><replaceable>target</replaceable>=<replaceable>source</replaceable></literal>
-    to mount a path in a different location in the chroot; for
-    instance, <literal>/bin=/nix-bin</literal> will mount the
-    directory <literal>/nix-bin</literal> as <literal>/bin</literal>
-    inside the chroot.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry><term><literal>build-use-substitutes</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>build-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>build-cache-failures</literal></term>
-
-    <listitem><para>If set to <literal>true</literal>, Nix will
-    “cache” build failures, meaning that it will remember (in its
-    database) that a derivation previously failed.  If you then try to
-    build the derivation again, Nix will immediately fail rather than
-    perform the build again.  Failures in fixed-output derivations
-    (such as <function>fetchurl</function> calls) are never cached.
-    The “failed” status of a derivation can be cleared using
-    <command>nix-store --clear-failed-paths</command>.  By default,
-    failure caching is disabled.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry><term><literal>build-keep-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><term><literal>build-compress-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><term><literal>use-binary-caches</literal></term>
-
-    <listitem><para>If set to <literal>true</literal> (the default),
-    Nix will check the binary caches specified by
-    <option>binary-caches</option> and related options to obtain
-    binary substitutes.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry><term><literal>binary-caches</literal></term>
-
-    <listitem><para>A list of URLs of binary caches, separated by
-    whitespace.  The default is
-    <literal>http://nixos.org/binary-cache</literal>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry><term><literal>binary-caches-files</literal></term>
-
-    <listitem><para>A list of names of files that will be read to
-    obtain additional binary cache URLs.  The default is
-    <literal>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/channels/binary-caches/*</literal>.
-    Note that when you’re using the Nix daemon,
-    <replaceable>username</replaceable> is always equal to
-    <literal>root</literal>, so Nix will only use the binary caches
-    provided by the channels installed by root.  Do not set this
-    option to read files created by untrusted users!</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry><term><literal>trusted-binary-caches</literal></term>
-
-    <listitem><para>A list of URLs of binary caches, separated by
-    whitespace.  These are not used by default, but can be enabled by
-    users of the Nix daemon by specifying <literal>--option
-    binary-caches <replaceable>urls</replaceable></literal> on the
-    command line.  Daemon users are only allowed to pass a subset of
-    the URLs listed in <literal>binary-caches</literal> and
-    <literal>trusted-binary-caches</literal>.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry><term><literal>binary-caches-parallel-connections</literal></term>
-
-    <listitem><para>The maximum number of parallel HTTP connections
-    used by the binary cache substituter to get NAR info files.  This
-    number should be high to minimise latency.  It defaults to
-    150.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry><term><literal>force-manifest</literal></term>
-
-    <listitem><para>If this option is set to <literal>false</literal>
-    (default) and a Nix channel provides both a manifest and a binary
-    cache, only the binary cache will be used.  If set to
-    <literal>true</literal>, the manifest will be fetched as well.
-    This is useful if you want to use binary patches (which are
-    currently not supported by binary caches).</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>
-
-
-  <varlistentry><term><literal>auto-optimise-store</literal></term>
-
-    <listitem><para>If set to <literal>true</literal> (the default),
-    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>, you
-    can still run <command>nix-store --optimise</command> to get rid
-    of duplicate files.</para></listitem>
-
-  </varlistentry>
-
-
-</variablelist>
-
-</para>
-
-</refsection>
-
-</refentry>

doc/manual/env-common.xml

@@ -1,329 +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 xml:id="env-common">
-
-  
-<varlistentry><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>The search path can be extended using the
-    <option>-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_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<phrase condition="manual"> (see <xref
-  linkend="chap-distributed-builds" />)</phrase>.</para>
-
-  <!--
-  The protocol by
-  which the calling Nix process and the build hook communicate is as
-  follows.
-
-  <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
-  execute Nix operations. This 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.
-  <phrase condition="manual">See <xref linkend="sec-sharing-packages"
-  /> for details.</phrase>  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-daemon">Nix daemon</link>, the only setting for
-  this variable that matters is the one that the
-  <command>nix-daemon</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>

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>

doc/manual/expressions/arguments-variables.xml

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

doc/manual/expressions/build-script.xml

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

doc/manual/expressions/builder-syntax.xml

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

doc/manual/expressions/builtins.xml

@@ -1,9 +1,10 @@
 <section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id='ssec-builtins'>
-
-<title>Built-in functions</title>
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id='ssec-builtins'>
 
+<title>Built-in Functions</title>
 
 <para>This section lists the functions and constants built into the
 Nix expression evaluator.  (The built-in function
@@ -12,9 +13,9 @@ such as <function>derivation</function>, are always in scope of every
 Nix expression; you can just access them right away.  But to prevent
 polluting the namespace too much, most built-ins are not in scope.
 Instead, you can access them through the <varname>builtins</varname>
-built-in value, which is an attribute set that contains all built-in
-functions and values.  For instance, <function>derivation</function>
-is also available as <function>builtins.derivation</function>.</para>
+built-in value, which is a set that contains all built-in functions
+and values.  For instance, <function>derivation</function> is also
+available as <function>builtins.derivation</function>.</para>
 
 
 <variablelist>
@@ -31,27 +32,52 @@ is also available as <function>builtins.derivation</function>.</para>
   <varlistentry><term><function>builtins.add</function>
   <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
 
-    <listitem><para>Return the sum of the integers
+    <listitem><para>Return the sum of the numbers
     <replaceable>e1</replaceable> and
     <replaceable>e2</replaceable>.</para></listitem>
 
   </varlistentry>
 
 
+  <varlistentry><term><function>builtins.all</function>
+  <replaceable>pred</replaceable> <replaceable>list</replaceable></term>
+
+    <listitem><para>Return <literal>true</literal> if the function
+    <replaceable>pred</replaceable> returns <literal>true</literal>
+    for all elements of <replaceable>list</replaceable>,
+    and <literal>false</literal> otherwise.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><function>builtins.any</function>
+  <replaceable>pred</replaceable> <replaceable>list</replaceable></term>
+
+    <listitem><para>Return <literal>true</literal> if the function
+    <replaceable>pred</replaceable> returns <literal>true</literal>
+    for at least one element of <replaceable>list</replaceable>,
+    and <literal>false</literal> otherwise.</para></listitem>
+
+  </varlistentry>
+
+
   <varlistentry><term><function>builtins.attrNames</function>
-  <replaceable>attrs</replaceable></term>
+  <replaceable>set</replaceable></term>
 
-    <listitem><para>Return the names of the attributes in the
-    attribute set <replaceable>attrs</replaceable> in a sorted list.
-    For instance, <literal>builtins.attrNames { y = 1; x = "foo";
-    }</literal> evaluates to <literal>[ "x" "y" ]</literal>.  There is
-    no built-in function <function>attrValues</function>, but you can
-    easily define it yourself:
+    <listitem><para>Return the names of the attributes in the set
+    <replaceable>set</replaceable> in an alphabetically sorted list.  For instance,
+    <literal>builtins.attrNames { y = 1; x = "foo"; }</literal>
+    evaluates to <literal>[ "x" "y" ]</literal>.</para></listitem>
 
-<programlisting>
-attrValues = attrs: map (name: builtins.getAttr name attrs) (builtins.attrNames attrs);</programlisting>
+  </varlistentry>
 
-    </para></listitem>
+
+  <varlistentry><term><function>builtins.attrValues</function>
+  <replaceable>set</replaceable></term>
+
+    <listitem><para>Return the values of the attributes in the set
+    <replaceable>set</replaceable> in the order corresponding to the
+    sorted attribute names.</para></listitem>
 
   </varlistentry>
 
@@ -68,8 +94,8 @@ attrValues = attrs: map (name: builtins.getAttr name attrs) (builtins.attrNames
 
   <varlistentry><term><varname>builtins</varname></term>
 
-    <listitem><para>The attribute set <varname>builtins</varname>
-    contains all the built-in functions and values.  You can use
+    <listitem><para>The set <varname>builtins</varname> contains all
+    the built-in functions and values.  You can use
     <varname>builtins</varname> to test for the availability of
     features in the Nix installation, e.g.,
 
@@ -108,6 +134,14 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
 
   </varlistentry>
 
+  <varlistentry><term><function>builtins.concatStringsSep</function>
+  <replaceable>separator</replaceable> <replaceable>list</replaceable></term>
+
+    <listitem><para>Concatenate a list of strings with a separator
+    between each element, e.g. <literal>concatStringsSep "/"
+    ["usr" "local" "bin"] == "usr/local/bin"</literal></para></listitem>
+
+  </varlistentry>
 
   <varlistentry
   xml:id='builtin-currentSystem'><term><varname>builtins.currentSystem</varname></term>
@@ -116,7 +150,7 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
     evaluates to the Nix platform identifier for the Nix installation
     on which the expression is being evaluated, such as
     <literal>"i686-linux"</literal> or
-    <literal>"powerpc-darwin"</literal>.</para></listitem>
+    <literal>"x86_64-darwin"</literal>.</para></listitem>
 
   </varlistentry>
 
@@ -143,6 +177,19 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
   -->
 
 
+  <varlistentry><term><function>builtins.deepSeq</function>
+  <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
+
+    <listitem><para>This is like <literal>seq
+    <replaceable>e1</replaceable>
+    <replaceable>e2</replaceable></literal>, except that
+    <replaceable>e1</replaceable> is evaluated
+    <emphasis>deeply</emphasis>: if it’s a list or set, its elements
+    or attributes are also evaluated recursively.</para></listitem>
+
+  </varlistentry>
+
+
   <varlistentry><term><function>derivation</function>
   <replaceable>attrs</replaceable></term>
 
@@ -165,13 +212,12 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
   <varlistentry><term><function>builtins.div</function>
   <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
 
-    <listitem><para>Return the quotient of the integers
+    <listitem><para>Return the quotient of the numbers
     <replaceable>e1</replaceable> and
     <replaceable>e2</replaceable>.</para></listitem>
 
   </varlistentry>
 
-
   <varlistentry><term><function>builtins.elem</function>
   <replaceable>x</replaceable> <replaceable>xs</replaceable></term>
 
@@ -194,6 +240,63 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
   </varlistentry>
 
 
+  <varlistentry><term><function>builtins.fetchurl</function>
+  <replaceable>url</replaceable></term>
+
+    <listitem><para>Download the specified URL and return the path of
+    the downloaded file. This function is not available if <link
+    linkend="conf-restrict-eval">restricted evaluation mode</link> is
+    enabled.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><function>fetchTarball</function>
+  <replaceable>url</replaceable></term>
+
+    <listitem><para>Download the specified URL, unpack it and return
+    the path of the unpacked tree. The file must be a tape archive
+    (<filename>.tar</filename>) compressed with
+    <literal>gzip</literal>, <literal>bzip2</literal> or
+    <literal>xz</literal>. The top-level path component of the files
+    in the tarball is removed, so it is best if the tarball contains a
+    single directory at top level. The typical use of the function is
+    to obtain external Nix expression dependencies, such as a
+    particular version of Nixpkgs, e.g.
+
+<programlisting>
+with import (fetchTarball https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz) {};
+
+stdenv.mkDerivation { … }
+</programlisting>
+
+    Note that when obtaining the hash with <varname>nix-prefetch-url
+    </varname> the option <varname>--unpack</varname> is required.
+    </para>
+
+    <para>This function can also verify the contents against a hash.
+    In that case, the function takes a set instead of a URL. The set
+    requires the attribute <varname>url</varname> and the attribute
+    <varname>sha256</varname>, e.g.
+
+<programlisting>
+with import (fetchTarball {
+  url = https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz;
+  sha256 = "1jppksrfvbk5ypiqdz4cddxdl8z6zyzdb2srq8fcffr327ld5jj2";
+}) {};
+
+stdenv.mkDerivation { … }
+</programlisting>
+
+    </para>
+
+    <para>This function is not available if <link
+    linkend="conf-restrict-eval">restricted evaluation mode</link> is
+    enabled.</para></listitem>
+
+  </varlistentry>
+
+
   <varlistentry><term><function>builtins.filter</function>
   <replaceable>f</replaceable> <replaceable>xs</replaceable></term>
 
@@ -257,12 +360,77 @@ stdenv.mkDerivation {
   </varlistentry>
 
 
+  <varlistentry><term><function>builtins.foldl’</function>
+    <replaceable>op</replaceable> <replaceable>nul</replaceable> <replaceable>list</replaceable></term>
+
+    <listitem><para>Reduce a list by applying a binary operator, from
+    left to right, e.g. <literal>foldl’ op nul [x0 x1 x2 ...] = op (op
+    (op nul x0) x1) x2) ...</literal>. The operator is applied
+    strictly, i.e., its arguments are evaluated first. For example,
+    <literal>foldl’ (x: y: x + y) 0 [1 2 3]</literal> evaluates to
+    6.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><function>builtins.functionArgs</function>
+    <replaceable>f</replaceable></term>
+
+    <listitem><para>
+    Return a set containing the names of the formal arguments expected
+    by the function <replaceable>f</replaceable>.
+    The value of each attribute is a Boolean denoting whether the corresponding
+    argument has a default value.  For instance,
+    <literal>functionArgs ({ x, y ? 123}: ...)  =  { x = false; y = true; }</literal>.
+    </para>
+
+    <para>"Formal argument" here refers to the attributes pattern-matched by
+    the function.  Plain lambdas are not included, e.g.
+    <literal>functionArgs (x: ...)  =  { }</literal>.
+    </para></listitem>
+  </varlistentry>
+
+
+  <varlistentry><term><function>builtins.fromJSON</function> <replaceable>e</replaceable></term>
+
+    <listitem><para>Convert a JSON string to a Nix
+    value. For example,
+
+<programlisting>
+builtins.fromJSON ''{"x": [1, 2, 3], "y": null}''
+</programlisting>
+
+    returns the value <literal>{ x = [ 1 2 3 ]; y = null;
+    }</literal>. Floating point numbers are not
+    supported.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><function>builtins.genList</function>
+  <replaceable>generator</replaceable> <replaceable>length</replaceable></term>
+
+    <listitem><para>Generate list of size
+    <replaceable>length</replaceable>, with each element
+    <replaceable>i</replaceable> equal to the value returned by
+    <replaceable>generator</replaceable> <literal>i</literal>. For
+    example,
+
+<programlisting>
+builtins.genList (x: x * x) 5
+</programlisting>
+
+    returns the list <literal>[ 0 1 4 9 16 ]</literal>.</para></listitem>
+
+  </varlistentry>
+
+
   <varlistentry><term><function>builtins.getAttr</function>
-  <replaceable>s</replaceable> <replaceable>attrs</replaceable></term>
+  <replaceable>s</replaceable> <replaceable>set</replaceable></term>
 
     <listitem><para><function>getAttr</function> returns the attribute
-    named <replaceable>s</replaceable> from the attribute set
-    <replaceable>attrs</replaceable>.  Evaluation aborts if the
+    named <replaceable>s</replaceable> from
+    <replaceable>set</replaceable>.  Evaluation aborts if the
     attribute doesn’t exist.  This is a dynamic version of the
     <literal>.</literal> operator, since <replaceable>s</replaceable>
     is an expression rather than an identifier.</para></listitem>
@@ -289,15 +457,27 @@ stdenv.mkDerivation {
 
 
   <varlistentry><term><function>builtins.hasAttr</function>
-  <replaceable>s</replaceable> <replaceable>attrs</replaceable></term>
+  <replaceable>s</replaceable> <replaceable>set</replaceable></term>
 
     <listitem><para><function>hasAttr</function> returns
-    <literal>true</literal> if the attribute set
-    <replaceable>attrs</replaceable> has an attribute named
-    <replaceable>s</replaceable>, and <literal>false</literal>
-    otherwise.  This is a dynamic version of the <literal>?</literal>
-    operator, since <replaceable>s</replaceable> is an expression
-    rather than an identifier.</para></listitem>
+    <literal>true</literal> if <replaceable>set</replaceable> has an
+    attribute named <replaceable>s</replaceable>, and
+    <literal>false</literal> otherwise.  This is a dynamic version of
+    the <literal>?</literal>  operator, since
+    <replaceable>s</replaceable> is an expression rather than an
+    identifier.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><function>builtins.hashString</function>
+  <replaceable>type</replaceable> <replaceable>s</replaceable></term>
+
+    <listitem><para>Return a base-16 representation of the
+    cryptographic hash of string <replaceable>s</replaceable>.  The
+    hash algorithm specified by <replaceable>type</replaceable> must
+    be one of <literal>"md5"</literal>, <literal>"sha1"</literal> or
+    <literal>"sha256"</literal>.</para></listitem>
 
   </varlistentry>
 
@@ -319,12 +499,12 @@ stdenv.mkDerivation {
     <listitem><para>Load, parse and return the Nix expression in the
     file <replaceable>path</replaceable>.  If <replaceable>path
     </replaceable> is a directory, the file <filename>default.nix
-    </filename> in that directory is loaded.  Evaluation aborts if
-    the file doesn’t exist or contains an incorrect Nix
-    expression.  <function>import</function> implements Nix’s module
-    system: you can put any Nix expression (such as an attribute set
-    or a function) in a separate file, and use it from Nix expressions
-    in other files.</para>
+    </filename> in that directory is loaded.  Evaluation aborts if the
+    file doesn’t exist or contains an incorrect Nix expression.
+    <function>import</function> implements Nix’s module system: you
+    can put any Nix expression (such as a set or a function) in a
+    separate file, and use it from Nix expressions in other
+    files.</para>
 
     <para>A Nix expression loaded by <function>import</function> must
     not contain any <emphasis>free variables</emphasis> (identifiers
@@ -371,9 +551,9 @@ x: x + 456</programlisting>
   <varlistentry><term><function>builtins.intersectAttrs</function>
   <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
 
-    <listitem><para>Return an attribute set consisting of the
-    attributes in the set <replaceable>e2</replaceable> that also
-    exist in the set <replaceable>e1</replaceable>.</para></listitem>
+    <listitem><para>Return a set consisting of the attributes in the
+    set <replaceable>e2</replaceable> that also exist in the set
+    <replaceable>e1</replaceable>.</para></listitem>
 
   </varlistentry>
 
@@ -382,7 +562,7 @@ x: x + 456</programlisting>
   <replaceable>e</replaceable></term>
 
     <listitem><para>Return <literal>true</literal> if
-    <replaceable>e</replaceable> evaluates to an attribute set, and
+    <replaceable>e</replaceable> evaluates to a set, and
     <literal>false</literal> otherwise.</para></listitem>
 
   </varlistentry>
@@ -422,7 +602,17 @@ x: x + 456</programlisting>
   <replaceable>e</replaceable></term>
 
     <listitem><para>Return <literal>true</literal> if
-    <replaceable>e</replaceable> evaluates to a int, and
+    <replaceable>e</replaceable> evaluates to an int, and
+    <literal>false</literal> otherwise.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><function>builtins.isFloat</function>
+  <replaceable>e</replaceable></term>
+
+    <listitem><para>Return <literal>true</literal> if
+    <replaceable>e</replaceable> evaluates to a float, and
     <literal>false</literal> otherwise.</para></listitem>
 
   </varlistentry>
@@ -465,12 +655,12 @@ x: x + 456</programlisting>
   <varlistentry><term><function>builtins.lessThan</function>
   <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
 
-    <listitem><para>Return <literal>true</literal> if the integer
-    <replaceable>e1</replaceable> is less than the integer
+    <listitem><para>Return <literal>true</literal> if the number
+    <replaceable>e1</replaceable> is less than the number
     <replaceable>e2</replaceable>, and <literal>false</literal>
     otherwise.  Evaluation aborts if either
     <replaceable>e1</replaceable> or <replaceable>e2</replaceable>
-    does not evaluate to an integer.</para></listitem>
+    does not evaluate to a number.</para></listitem>
 
   </varlistentry>
 
@@ -478,9 +668,9 @@ x: x + 456</programlisting>
   <varlistentry><term><function>builtins.listToAttrs</function>
   <replaceable>e</replaceable></term>
 
-    <listitem><para>Construct an attribute set from a list specifying
-    the names and values of each attribute.  Each element of the list
-    should be an attribute set consisting of a string-valued attribute
+    <listitem><para>Construct a set from a list specifying the names
+    and values of each attribute.  Each element of the list should be
+    a set consisting of a string-valued attribute
     <varname>name</varname> specifying the name of the attribute, and
     an attribute <varname>value</varname> specifying its value.
     Example:
@@ -518,10 +708,46 @@ map (x: "foo" + x) [ "bar" "bla" "abc" ]</programlisting>
   </varlistentry>
 
 
+  <varlistentry><term><function>builtins.match</function>
+  <replaceable>regex</replaceable> <replaceable>str</replaceable></term>
+
+  <listitem><para>Returns a list if the <link
+  xlink:href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04">extended
+  POSIX regular expression</link> <replaceable>regex</replaceable>
+  matches <replaceable>str</replaceable> precisely, otherwise returns
+  <literal>null</literal>.  Each item in the list is a regex group.
+
+<programlisting>
+builtins.match "ab" "abc"
+</programlisting>
+
+Evaluates to <literal>null</literal>.
+
+<programlisting>
+builtins.match "abc" "abc"
+</programlisting>
+
+Evaluates to <literal>[ ]</literal>.
+
+<programlisting>
+builtins.match "a(b)(c)" "abc"
+</programlisting>
+
+Evaluates to <literal>[ "b" "c" ]</literal>.
+
+<programlisting>
+builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" "  FOO   "
+</programlisting>
+
+Evaluates to <literal>[ "foo" ]</literal>.
+
+  </para></listitem>
+  </varlistentry>
+
   <varlistentry><term><function>builtins.mul</function>
   <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
 
-    <listitem><para>Return the product of the integers
+    <listitem><para>Return the product of the numbers
     <replaceable>e1</replaceable> and
     <replaceable>e2</replaceable>.</para></listitem>
 
@@ -535,7 +761,7 @@ map (x: "foo" + x) [ "bar" "bla" "abc" ]</programlisting>
     a package name and version.  The package name is everything up to
     but not including the first dash followed by a digit, and the
     version is everything following that dash.  The result is returned
-    in an attribute set <literal>{ name, version }</literal>.  Thus,
+    in a set <literal>{ name, version }</literal>.  Thus,
     <literal>builtins.parseDrvName "nix-0.12pre12876"</literal>
     returns <literal>{ name = "nix"; version = "0.12pre12876";
     }</literal>.</para></listitem>
@@ -567,13 +793,26 @@ in config.someSetting</programlisting>
   </varlistentry>
 
 
-  <!--
-  <varlistentry><term><function>relativise</function></term>
+  <varlistentry><term><function>builtins.readDir</function>
+  <replaceable>path</replaceable></term>
 
-    <listitem><para>TODO</para></listitem>
+    <listitem><para>Return the contents of the directory
+    <replaceable>path</replaceable> as a set mapping directory entries
+    to the corresponding file type. For instance, if directory
+    <filename>A</filename> contains a regular file
+    <filename>B</filename> and another directory
+    <filename>C</filename>, then <literal>builtins.readDir
+    ./A</literal> will return the set
+
+<programlisting>
+{ B = "regular"; C = "directory"; }</programlisting>
+
+    The possible values for the file type are
+    <literal>"regular"</literal>, <literal>"directory"</literal>,
+    <literal>"symlink"</literal> and
+    <literal>"unknown"</literal>.</para></listitem>
 
   </varlistentry>
-  -->
 
 
   <varlistentry><term><function>builtins.readFile</function>
@@ -586,21 +825,109 @@ in config.someSetting</programlisting>
 
 
   <varlistentry><term><function>removeAttrs</function>
-  <replaceable>attrs</replaceable> <replaceable>list</replaceable></term>
+  <replaceable>set</replaceable> <replaceable>list</replaceable></term>
 
     <listitem><para>Remove the attributes listed in
-    <replaceable>list</replaceable> from the attribute set
-    <replaceable>attrs</replaceable>.  The attributes don’t have to
-    exist in <replaceable>attrs</replaceable>. For instance,
+    <replaceable>list</replaceable> from
+    <replaceable>set</replaceable>.  The attributes don’t have to
+    exist in <replaceable>set</replaceable>. For instance,
 
-<screen>
-removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]</screen>
+<programlisting>
+removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]</programlisting>
 
     evaluates to <literal>{ y = 2; }</literal>.</para></listitem>
 
   </varlistentry>
 
 
+  <varlistentry><term><function>builtins.replaceStrings</function>
+  <replaceable>from</replaceable> <replaceable>to</replaceable> <replaceable>s</replaceable></term>
+
+    <listitem><para>Given string <replaceable>s</replaceable>, replace
+    every occurrence of the strings in <replaceable>from</replaceable>
+    with the corresponding string in
+    <replaceable>to</replaceable>. For example,
+
+<programlisting>
+builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar"
+</programlisting>
+
+    evaluates to <literal>"fabir"</literal>.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><function>builtins.seq</function>
+  <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
+
+    <listitem><para>Evaluate <replaceable>e1</replaceable>, then
+    evaluate and return <replaceable>e2</replaceable>. This ensures
+    that a computation is strict in the value of
+    <replaceable>e1</replaceable>.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><function>builtins.sort</function>
+  <replaceable>comparator</replaceable> <replaceable>list</replaceable></term>
+
+    <listitem><para>Return <replaceable>list</replaceable> in sorted
+    order. It repeatedly calls the function
+    <replaceable>comparator</replaceable> with two elements. The
+    comparator should return <literal>true</literal> if the first
+    element is less than the second, and <literal>false</literal>
+    otherwise. For example,
+
+<programlisting>
+builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ]
+</programlisting>
+
+    produces the list <literal>[ 42 77 147 249 483 526
+    ]</literal>.</para>
+
+    <para>This is a stable sort: it preserves the relative order of
+    elements deemed equal by the comparator.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><function>builtins.split</function>
+  <replaceable>regex</replaceable> <replaceable>str</replaceable></term>
+
+  <listitem><para>Returns a list composed of non matched strings interleaved
+  with the lists of the <link
+  xlink:href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04">extended
+  POSIX regular expression</link> <replaceable>regex</replaceable> matches
+  of <replaceable>str</replaceable>. Each item in the lists of matched
+  sequences is a regex group.
+
+<programlisting>
+builtins.split "(a)b" "abc"
+</programlisting>
+
+Evaluates to <literal>[ "" [ "a" ] "c" ]</literal>.
+
+<programlisting>
+builtins.split "([ac])" "abc"
+</programlisting>
+
+Evaluates to <literal>[ "" [ "a" ] "b" [ "c" ] "" ]</literal>.
+
+<programlisting>
+builtins.split "(a)|(c)" "abc"
+</programlisting>
+
+Evaluates to <literal>[ "" [ "a" null ] "b" [ null "c" ] "" ]</literal>.
+
+<programlisting>
+builtins.split "([[:upper:]]+)" "  FOO   "
+</programlisting>
+
+Evaluates to <literal>[ "  " [ "FOO" ] "   " ]</literal>.
+
+  </para></listitem>
+  </varlistentry>
+
   <varlistentry><term><function>builtins.stringLength</function>
   <replaceable>e</replaceable></term>
 
@@ -614,7 +941,7 @@ removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]</screen>
   <varlistentry><term><function>builtins.sub</function>
   <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
 
-    <listitem><para>Return the difference between the integers
+    <listitem><para>Return the difference between the numbers
     <replaceable>e1</replaceable> and
     <replaceable>e2</replaceable>.</para></listitem>
 
@@ -634,7 +961,14 @@ removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]</screen>
     len</replaceable> lies beyond the end of the string, only the
     substring up to the end of the string is returned.
     <replaceable>start</replaceable> must be
-    non-negative.</para></listitem>
+    non-negative. For example,
+
+<programlisting>
+builtins.substring 0 3 "nixos"
+</programlisting>
+
+   evaluates to <literal>"nix"</literal>.
+   </para></listitem>
 
   </varlistentry>
 
@@ -694,8 +1028,8 @@ stdenv.mkDerivation {
   ";
 
   src = fetchurl {
-    url = http://nix.cs.uu.nl/dist/tarballs/hello-2.1.1.tar.gz;
-    md5 = "70c9ccf9fac07f762c24f2df2290784d";
+    url = http://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
+    sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
   };
   inherit perl;
 }</programlisting>
@@ -738,6 +1072,19 @@ in foo</programlisting>
   </varlistentry>
 
 
+  <varlistentry><term><function>builtins.toJSON</function> <replaceable>e</replaceable></term>
+
+    <listitem><para>Return a string containing a JSON representation
+    of <replaceable>e</replaceable>.  Strings, integers, floats, booleans,
+    nulls and lists are mapped to their JSON equivalents.  Sets
+    (except derivations) are represented as objects.  Derivations are
+    translated to a JSON string containing the derivation’s output
+    path.  Paths are copied to the store and represented as a JSON
+    string of the resulting store path.</para></listitem>
+
+  </varlistentry>
+
+
   <varlistentry><term><function>builtins.toPath</function> <replaceable>s</replaceable></term>
 
     <listitem><para>Convert the string value
@@ -755,10 +1102,17 @@ in foo</programlisting>
 
     <listitem><para>Convert the expression
     <replaceable>e</replaceable> to a string.
-    <replaceable>e</replaceable> can be a string (in which case
-    <function>toString</function> is a no-op) or a path (e.g.,
-    <literal>toString /foo/bar</literal> yields
-    <literal>"/foo/bar"</literal>.</para></listitem>
+    <replaceable>e</replaceable> can be:</para>
+    <itemizedlist>
+      <listitem><para>A string (in which case the string is returned unmodified).</para></listitem>
+      <listitem><para>A path (e.g., <literal>toString /foo/bar</literal> yields <literal>"/foo/bar"</literal>.</para></listitem>
+      <listitem><para>A set containing <literal>{ __toString = self: ...; }</literal>.</para></listitem>
+      <listitem><para>An integer.</para></listitem>
+      <listitem><para>A list, in which case the string representations of its elements are joined with spaces.</para></listitem>
+      <listitem><para>A Boolean (<literal>false</literal> yields <literal>""</literal>, <literal>true</literal> yields <literal>"1"</literal>.</para></listitem>
+      <listitem><para><literal>null</literal>, which yields the empty string.</para></listitem>
+    </itemizedlist>
+    </listitem>
 
   </varlistentry>
 
@@ -780,7 +1134,7 @@ in foo</programlisting>
     servlet container</link>.  A servlet container contains a number
     of servlets (<filename>*.war</filename> files) each exported under
     a specific URI prefix.  So the servlet configuration is a list of
-    attribute sets containing the <varname>path</varname> and
+    sets containing the <varname>path</varname> and
     <varname>war</varname> of the servlet (<xref
     linkend='ex-toxml-co-servlets' />).  This kind of information is
     difficult to communicate with the normal method of passing
@@ -888,6 +1242,33 @@ stdenv.mkDerivation (rec {
 
   </varlistentry>
 
+  <varlistentry><term><function>builtins.tryEval</function>
+  <replaceable>e</replaceable></term>
+
+    <listitem><para>Try to evaluate <replaceable>e</replaceable>.
+    Return a set containing the attributes <literal>success</literal>
+    (<literal>true</literal> if <replaceable>e</replaceable> evaluated
+    successfully, <literal>false</literal> if an error was thrown) and
+    <literal>value</literal>, equalling <replaceable>e</replaceable>
+    if successful and <literal>false</literal> otherwise.
+    </para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><function>builtins.typeOf</function>
+  <replaceable>e</replaceable></term>
+
+    <listitem><para>Return a string representing the type of the value
+    <replaceable>e</replaceable>, namely <literal>"int"</literal>,
+    <literal>"bool"</literal>, <literal>"string"</literal>,
+    <literal>"path"</literal>, <literal>"null"</literal>,
+    <literal>"set"</literal>, <literal>"list"</literal>,
+    <literal>"lambda"</literal> or
+    <literal>"float"</literal>.</para></listitem>
+
+  </varlistentry>
+
 
 </variablelist>
 

doc/manual/expressions/debug-build.xml

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

doc/manual/expressions/derivations.xml

@@ -0,0 +1,211 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="ssec-derivation">
+
+<title>Derivations</title>
+
+<para>The most important built-in function is
+<function>derivation</function>, which is used to describe a single
+derivation (a build action).  It takes as input a set, the attributes
+of which specify the inputs of the build.</para>
+
+<itemizedlist>
+
+  <listitem xml:id="attr-system"><para>There must be an attribute named
+  <varname>system</varname> whose value must be a string specifying a
+  Nix platform identifier, such as <literal>"i686-linux"</literal> or
+  <literal>"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>

doc/manual/expressions/expression-language.xml

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

doc/manual/expressions/expression-syntax.xml

@@ -0,0 +1,148 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id='sec-expression-syntax'>
+
+<title>Expression Syntax</title>
+
+<example xml:id='ex-hello-nix'><title>Nix expression for GNU Hello
+(<filename>default.nix</filename>)</title>
+<programlisting>
+{ stdenv, fetchurl, perl }: <co xml:id='ex-hello-nix-co-1' />
+
+stdenv.mkDerivation { <co xml:id='ex-hello-nix-co-2' />
+  name = "hello-2.1.1"; <co xml:id='ex-hello-nix-co-3' />
+  builder = ./builder.sh; <co xml:id='ex-hello-nix-co-4' />
+  src = fetchurl { <co xml:id='ex-hello-nix-co-5' />
+    url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
+    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>

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>

doc/manual/expressions/language-constructs.xml

@@ -0,0 +1,363 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-constructs">
+
+<title>Language Constructs</title>
+
+<simplesect><title>Recursive sets</title>
+
+<para>Recursive sets are just normal sets, but the attributes can
+refer to each other.  For example,
+
+<programlisting>
+rec {
+  x = y;
+  y = 123;
+}.x
+</programlisting>
+
+evaluates to <literal>123</literal>.  Note that without
+<literal>rec</literal> the binding <literal>x = y;</literal> would
+refer to the variable <varname>y</varname> in the surrounding scope,
+if one exists, and would be invalid if no such variable exists.  That
+is, in a normal (non-recursive) set, attributes are not added to the
+lexical scope; in a recursive set, they are.</para>
+
+<para>Recursive sets of course introduce the danger of infinite
+recursion.  For example,
+
+<programlisting>
+rec {
+  x = y;
+  y = x;
+}.x</programlisting>
+
+does not terminate<footnote><para>Actually, Nix detects infinite
+recursion in this case and aborts (<quote>infinite recursion
+encountered</quote>).</para></footnote>.</para>
+
+</simplesect>
+
+
+<simplesect><title>Let-expressions</title>
+
+<para>A let-expression allows you define local variables for an
+expression.  For instance,
+
+<programlisting>
+let
+  x = "foo";
+  y = "bar";
+in x + y</programlisting>
+
+evaluates to <literal>"foobar"</literal>.
+
+</para>
+
+</simplesect>
+
+
+<simplesect><title>Inheriting attributes</title>
+
+<para>When defining a set it is often convenient to copy variables
+from the surrounding lexical scope (e.g., when you want to propagate
+attributes).  This can be shortened using the
+<literal>inherit</literal> keyword.  For instance,
+
+<programlisting>
+let x = 123; in
+{ inherit x;
+  y = 456;
+}</programlisting>
+
+evaluates to <literal>{ x = 123; y = 456; }</literal>.  (Note that
+this works because <varname>x</varname> is added to the lexical scope
+by the <literal>let</literal> construct.)  It is also possible to
+inherit attributes from another set.  For instance, in this fragment
+from <filename>all-packages.nix</filename>,
+
+<programlisting>
+  graphviz = (import ../tools/graphics/graphviz) {
+    inherit fetchurl stdenv libpng libjpeg expat x11 yacc;
+    inherit (xlibs) libXaw;
+  };
+
+  xlibs = {
+    libX11 = ...;
+    libXaw = ...;
+    ...
+  }
+
+  libpng = ...;
+  libjpg = ...;
+  ...</programlisting>
+
+the set used in the function call to the function defined in
+<filename>../tools/graphics/graphviz</filename> inherits a number of
+variables from the surrounding scope (<varname>fetchurl</varname>
+... <varname>yacc</varname>), but also inherits
+<varname>libXaw</varname> (the X Athena Widgets) from the
+<varname>xlibs</varname> (X11 client-side libraries) set.</para>
+
+</simplesect>
+
+
+<simplesect xml:id="ss-functions"><title>Functions</title>
+
+<para>Functions have the following form:
+
+<programlisting>
+<replaceable>pattern</replaceable>: <replaceable>body</replaceable></programlisting>
+
+The pattern specifies what the argument of the function must look
+like, and binds variables in the body to (parts of) the
+argument.  There are three kinds of patterns:</para>
+
+<itemizedlist>
+
+
+  <listitem><para>If a pattern is a single identifier, then the
+  function matches any argument.  Example:
+
+  <programlisting>
+let negate = x: !x;
+    concat = x: y: x + y;
+in if negate true then concat "foo" "bar" else ""</programlisting>
+
+  Note that <function>concat</function> is a function that takes one
+  argument and returns a function that takes another argument.  This
+  allows partial parameterisation (i.e., only filling some of the
+  arguments of a function); e.g.,
+
+  <programlisting>
+map (concat "foo") [ "bar" "bla" "abc" ]</programlisting>
+
+  evaluates to <literal>[ "foobar" "foobla"
+  "fooabc" ]</literal>.</para></listitem>
+
+
+  <listitem><para>A <emphasis>set pattern</emphasis> of the form
+  <literal>{ name1, name2, …, nameN }</literal> matches a set
+  containing the listed attributes, and binds the values of those
+  attributes to variables in the function body.  For example, the
+  function
+
+<programlisting>
+{ x, y, z }: z + y + x</programlisting>
+
+  can only be called with a set containing exactly the attributes
+  <varname>x</varname>, <varname>y</varname> and
+  <varname>z</varname>.  No other attributes are allowed.  If you want
+  to allow additional arguments, you can use an ellipsis
+  (<literal>...</literal>):
+
+<programlisting>
+{ x, y, z, ... }: z + y + x</programlisting>
+
+  This works on any set that contains at least the three named
+  attributes.</para>
+
+  <para>It is possible to provide <emphasis>default values</emphasis>
+  for attributes, in which case they are allowed to be missing.  A
+  default value is specified by writing
+  <literal><replaceable>name</replaceable> ?
+  <replaceable>e</replaceable></literal>, where
+  <replaceable>e</replaceable> is an arbitrary expression.  For example,
+
+<programlisting>
+{ x, y ? "foo", z ? "bar" }: z + y + x</programlisting>
+
+  specifies a function that only requires an attribute named
+  <varname>x</varname>, but optionally accepts <varname>y</varname>
+  and <varname>z</varname>.</para></listitem>
+
+
+  <listitem><para>An <literal>@</literal>-pattern provides a means of referring
+  to the whole value being matched:
+
+<programlisting> args@{ x, y, z, ... }: z + y + x + args.a</programlisting>
+
+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>

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>

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>

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

@@ -0,0 +1,86 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id='sec-building-simple'>
+
+<title>Building and Testing</title>
+
+<para>You can now try to build Hello.  Of course, you could do
+<literal>nix-env -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>
+
+<xi:include href="debug-build.xml" />
+
+</section>

doc/manual/expressions/simple-expression.xml

@@ -0,0 +1,47 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="ch-simple-expression">
+
+<title>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>

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>

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>
 

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>

doc/manual/installation.xml

@@ -1,550 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="chap-installation">
-
-<title>Installation</title>
-
-
-<section><title>Supported platforms</title>
-
-<para>Nix is currently supported on the following platforms:
-
-<itemizedlist>
-
-  <listitem><para>Linux (particularly on x86, x86_64, and
-  PowerPC).</para></listitem>
-
-  <listitem><para>Mac OS X.</para></listitem>
-
-  <listitem><para>FreeBSD (only tested on Intel).</para></listitem>
-
-  <!--
-  <listitem><para>Windows through <link
-  xlink:href="http://www.cygwin.com/">Cygwin</link>.</para>
-
-  <warning><para>On Cygwin, Nix <emphasis>must</emphasis> be installed
-  on an NTFS partition.  It will not work correctly on a FAT
-  partition.</para></warning>
-
-  </listitem>
-  -->
-
-</itemizedlist>
-
-</para>
-
-<para>Nix is pretty portable, so it should work on most other Unix
-platforms as well.</para>
-
-</section>
-
-
-<section><title>Installing a binary distribution</title>
-
-<para>The easiest way to install Nix is to use a binary package.
-Binary packages of the latest stable release are available for Fedora,
-Debian, Ubuntu, Mac OS X and various other systems from the <link
-xlink:href="http://nixos.org/nix/download.html">Nix homepage</link>.
-You can also get builds of the latest development release from our
-<link
-xlink:href="http://hydra.nixos.org/view/nix/trunk/latest">continuous
-build system</link>.</para>
-
-<para>For Fedora, RPM packages are available.  These can be installed
-or upgraded using <command>rpm -U</command>.  For example,
-
-<screen>
-$ rpm -U nix-1.0-1.i386.rpm</screen>
-
-</para>
-
-<para>For Debian and Ubuntu, you can download a Deb package and
-install it like this:
-
-<screen>
-$ dpkg -i nix_1.0-1_amd64.deb</screen>
-
-</para>
-
-<para>For other platforms, including Mac OS X (Darwin), FreeBSD and
-other Linux distributions, you can download a binary tarball.  It
-contains Nix and all its dependencies.  You should unpack it in the
-root directory, then run <command>nix-finish-install</command>:
-
-<screen>
-$ cd /
-$ tar xfj nix-1.1-x86_64-darwin.tar.bz2
-$ nix-finish-install
-</screen>
-
-After this you can delete
-<filename>/usr/bin/nix-finish-install</filename>.</para>
-
-<para>If you plan to use Nix from a single non-root user account, it’s
-probably convenient to change the ownership of the entire Nix store
-and database to that user account.  In that case, install as follows:
-
-<screen>
-alice$ cd /
-alice$ sudo tar xfj nix-1.1-x86_64-darwin.tar.bz2
-alice$ sudo chown -R alice /nix
-alice$ nix-finish-install
-</screen>
-
-</para>
-
-<para>Nix can be uninstalled using <command>rpm -e nix</command> or
-<command>dpkg -r nix</command> on RPM- and Dpkg-based systems,
-respectively.  After this you should manually remove the Nix store and
-other auxiliary data, if desired:
-
-<screen>
-$ rm -rf /nix</screen>
-
-</para>
-
-</section>
-
-
-<section><title>Installing Nix from source</title>
-
-<para>If no binary package is available, you can download and compile
-a source distribution.</para>
-
-<section><title>Prerequisites</title>
-
-<itemizedlist>
-
-  <listitem><para>GNU Make.</para></listitem>
-
-  <listitem><para>A fairly recent version of GCC/G++.  Version 2.95
-  and higher should work.  Clang will also work.</para></listitem>
-
-  <listitem><para>Perl 5.8 or higher.</para></listitem>
-
-  <listitem><para><command>pkg-config</command> to locate
-  dependencies.  If your distribution does not provide it, you can get
-  it from <link
-  xlink:href="http://www.freedesktop.org/wiki/Software/pkg-config"
-  />.</para></listitem>
-
-  <listitem><para>The bzip2 compressor program and the
-  <literal>libbz2</literal> library.  Thus you must have bzip2
-  installed, including development headers and libraries.  If your
-  distribution does not provide these, you can obtain bzip2 from <link
-  xlink:href="http://www.bzip.org/"/>.</para></listitem>
-
-  <listitem><para>The SQLite embedded database library, version 3.6.19
-  or higher.  If your distribution does not provide it, please install
-  it from <link xlink:href="http://www.sqlite.org/" />.</para></listitem>
-
-  <listitem><para>The Perl DBI and DBD::SQLite libraries, which are
-  available from <link
-  xlink:href="http://search.cpan.org/">CPAN</link> if your
-  distribution does not provide them.</para></listitem>
-
-  <listitem><para>The <link
-  xlink:href="http://www.hpl.hp.com/personal/Hans_Boehm/gc/">Boehm
-  garbage collector</link> to reduce the evaluator’s memory
-  consumption (optional).  To enable it, install
-  <literal>pkgconfig</literal> and the Boehm garbage collector, and
-  pass the flag <option>--enable-gc</option> to
-  <command>configure</command>.</para></listitem>
-
-  <listitem><para>The <command>xmllint</command> and
-  <command>xsltproc</command> programs to build this manual and the
-  man-pages.  These are part of the <literal>libxml2</literal> and
-  <literal>libxslt</literal> packages, respectively.  You also need
-  the <link
-  xlink:href="http://docbook.sourceforge.net/projects/xsl/">DocBook
-  XSL stylesheets</link> and optionally the <link
-  xlink:href="http://www.docbook.org/schemas/5x"> DocBook 5.0 RELAX NG
-  schemas</link>.  Note that these are only required if you modify the
-  manual sources or when you are building from the Git
-  repository.</para></listitem>
-
-  <listitem><para>Recent versions of Bison and Flex to build the
-  parser.  (This is because Nix needs GLR support in Bison and
-  reentrancy support in Flex.)  For Bison, you need version 2.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 Git
-  repository.</para></listitem>
-
-</itemizedlist>
-
-</section>
-
-
-<section><title>Obtaining a source distribution</title>
-
-<para>The source tarball of the most recent stable release can be
-downloaded from the <link
-xlink:href="http://nixos.org/nix/download.html">Nix homepage</link>.
-You can also grab the <link
-xlink:href="http://hydra.nixos.org/view/nix/trunk/latest/tarball/download-by-type/file/source-dist">most
-recent development release</link>.</para>
-
-<para>Alternatively, the most recent sources of Nix can be obtained
-from its <link
-xlink:href="https://github.com/NixOS/nix">Git
-repository</link>.  For example, the following command will check out
-the latest revision into a directory called
-<filename>nix</filename>:</para>
-
-<screen>
-$ git clone https://github.com/NixOS/nix</screen>
-
-<para>Likewise, specific releases can be obtained from the <link
-xlink:href="https://github.com/NixOS/nix/tags">tags</link> of the
-repository.</para>
-
-</section>
-
-
-<section><title>Building Nix from source</title>
-
-<para>After unpacking or checking out the Nix sources, issue the
-following commands:
-
-<screen>
-$ ./configure <replaceable>options...</replaceable>
-$ make
-$ make install</screen>
-
-Nix requires GNU Make so you may need to invoke
-<command>gmake</command> instead.</para>
-
-<para>When building from the Git repository, these should be preceded
-by the command:
-
-<screen>
-$ ./bootstrap.sh</screen>
-
-</para>
-
-<para>The installation path can be specified by passing the
-<option>--prefix=<replaceable>prefix</replaceable></option> to
-<command>configure</command>.  The default installation directory is
-<filename>/usr/local</filename>.  You can change this to any location
-you like.  You must have write permission to the
-<replaceable>prefix</replaceable> path.</para>
-
-<para>Nix keeps its <emphasis>store</emphasis> (the place where
-packages are stored) in <filename>/nix/store</filename> by default.
-This can be changed using
-<option>--with-store-dir=<replaceable>path</replaceable></option>.</para>
-
-<warning><para>It is best <emphasis>not</emphasis> to change the Nix
-store from its default, since doing so makes it impossible to use
-pre-built binaries from the standard Nixpkgs channels — that is, all
-packages will need to be built from source.</para></warning>
-
-<para>Nix keeps state (such as its database and log files) in
-<filename>/nix/var</filename> by default.  This can be changed using
-<option>--localstatedir=<replaceable>path</replaceable></option>.</para>
-
-<para>If you want to rebuild the documentation, pass the full path to
-the DocBook RELAX NG schemas and to the DocBook XSL stylesheets using
-the
-<option>--with-docbook-rng=<replaceable>path</replaceable></option>
-and
-<option>--with-docbook-xsl=<replaceable>path</replaceable></option>
-options.</para>
-
-</section>
-
-
-</section>
-
-
-<!-- TODO: should be updated
-<section><title>Upgrading Nix through Nix</title>
-
-<para>You can install the latest stable version of Nix through Nix
-itself by subscribing to the channel <link
-xlink:href="http://nixos.org/releases/nix/channels/nix-stable" />,
-or the latest unstable version by subscribing to the channel <link
-xlink:href="http://nixos.org/releases/nix/channels/nix-unstable" />.
-You can also do a <link linkend="sec-one-click">one-click
-installation</link> by clicking on the package links at <link
-xlink:href="http://nixos.org/releases/full-index-nix.html" />.</para>
-
-</section>
--->
-
-
-<section><title>Security</title>
-
-<para>Nix has two basic security models.  First, it can be used in
-“single-user mode”, which is similar to what most other package
-management tools do: there is a single user (typically <systemitem
-class="username">root</systemitem>) who performs all package
-management operations.  All other users can then use the installed
-packages, but they cannot perform package management operations
-themselves.</para>
-
-<para>Alternatively, you can configure Nix in “multi-user mode”.  In
-this model, all users can perform package management operations — for
-instance, every user can install software without requiring root
-privileges.  Nix ensures that this is secure.  For instance, it’s not
-possible for one user to overwrite a package used by another user with
-a Trojan horse.</para>
-
-
-<section><title>Single-user mode</title>
-  
-<para>In single-user mode, all Nix operations that access the database
-in <filename><replaceable>prefix</replaceable>/var/nix/db</filename>
-or modify the Nix store in
-<filename><replaceable>prefix</replaceable>/store</filename> must be
-performed under the user ID that owns those directories.  This is
-typically <systemitem class="username">root</systemitem>.  (If you
-install from RPM packages, that’s in fact the default ownership.)
-However, on single-user machines, it is often convenient to
-<command>chown</command> those directories to your normal user account
-so that you don’t have to <command>su</command> to <systemitem
-class="username">root</systemitem> all the time.</para>
-
-</section>
-
-
-<section xml:id="ssec-multi-user"><title>Multi-user mode</title>
-
-<para>To allow a Nix store to be shared safely among multiple users,
-it is important that users are not able to run builders that modify
-the Nix store or database in arbitrary ways, or that interfere with
-builds started by other users.  If they could do so, they could
-install a Trojan horse in some package and compromise the accounts of
-other users.</para>
-
-<para>To prevent this, the Nix store and database are owned by some
-privileged user (usually <literal>root</literal>) and builders are
-executed under special user accounts (usually named
-<literal>nixbld1</literal>, <literal>nixbld2</literal>, etc.).  When a
-unprivileged user runs a Nix command, actions that operate on the Nix
-store (such as builds) are forwarded to a <emphasis>Nix
-daemon</emphasis> running under the owner of the Nix store/database
-that performs the operation.</para>
-
-<note><para>Multi-user mode has one important limitation: only
-<systemitem class="username">root</systemitem> can run <command
-linkend="sec-nix-pull">nix-pull</command> to register the availability
-of pre-built binaries.  However, those registrations are shared by all
-users, so they still get the benefit from <command>nix-pull</command>s
-done by <systemitem class="username">root</systemitem>.</para></note>
-
-
-<section><title>Setting up the build users</title>
-
-<para>The <emphasis>build users</emphasis> are the special UIDs under
-which builds are performed.  They should all be members of the
-<emphasis>build users group</emphasis> (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 1775 /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> (usually <literal>/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-daemon">Nix daemon</link> should be
-started as follows (as <literal>root</literal>):
-
-<screen>
-$ nix-daemon</screen>
-
-You’ll want to put that line somewhere in your system’s boot
-scripts.</para>
-
-<para>To let unprivileged users use the daemon, they should set the
-<link linkend="envar-remote"><envar>NIX_REMOTE</envar> environment
-variable</link> to <literal>daemon</literal>.  So you should put a
-line like
-
-<programlisting>
-export NIX_REMOTE=daemon</programlisting>
-
-into the users’ login scripts.</para>
-
-</section>
-
-
-<section><title>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 nix /nix/store /nix/var/nix</screen>
-
-and of course <command>nix-daemon</command> should be started under
-that user, e.g.,
-
-<screen>
-$ su - nix -c "exec /nix/bin/nix-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>

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>

doc/manual/installation/env-variables.xml

@@ -0,0 +1,24 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="ch-env-variables">
+
+<title>Environment Variables</title>
+
+<para>To use Nix, some environment variables should be set.  In
+particular, <envar>PATH</envar> should contain the directories
+<filename><replaceable>prefix</replaceable>/bin</filename> and
+<filename>~/.nix-profile/bin</filename>.  The first directory contains
+the Nix tools themselves, while <filename>~/.nix-profile</filename> is
+a symbolic link to the current <emphasis>user environment</emphasis>
+(an automatically generated package consisting of symlinks to
+installed packages).  The simplest way to set the required environment
+variables is to include the file
+<filename><replaceable>prefix</replaceable>/etc/profile.d/nix.sh</filename>
+in your <filename>~/.profile</filename> (or similar), like this:</para>
+
+<screen>
+source <replaceable>prefix</replaceable>/etc/profile.d/nix.sh</screen>
+
+</chapter>

doc/manual/installation/installation.xml

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

doc/manual/installation/installing-binary.xml

@@ -0,0 +1,100 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="ch-installing-binary">
+
+<title>Installing a Binary Distribution</title>
+
+<para>If you are using Linux or macOS, the easiest way to install
+Nix is to run the following command:
+
+<screen>
+$ bash &lt;(curl https://nixos.org/nix/install)
+</screen>
+
+This will perform a single-user installation of Nix, meaning that
+<filename>/nix</filename> is owned by the invoking user.  You should
+run this under your usual user account, <emphasis>not</emphasis> as
+root.  The script will invoke <command>sudo</command> to create
+<filename>/nix</filename> if it doesn’t already exist.  If you don’t
+have <command>sudo</command>, you should manually create
+<command>/nix</command> first as root, e.g.:
+
+<screen>
+$ mkdir /nix
+$ chown alice /nix
+</screen>
+
+The install script will modify the first writable file from amongst
+<filename>.bash_profile</filename>, <filename>.bash_login</filename>
+and <filename>.profile</filename> to source
+<filename>~/.nix-profile/etc/profile.d/nix.sh</filename>. You can set
+the <command>NIX_INSTALLER_NO_MODIFY_PROFILE</command> environment
+variable before executing the install script to disable this
+behaviour.
+
+</para>
+
+<!--
+<para>You can also manually download and install a binary package.
+Binary packages of the latest stable release are available for Fedora,
+Debian, Ubuntu, macOS and various other systems from the <link
+xlink:href="http://nixos.org/nix/download.html">Nix homepage</link>.
+You can also get builds of the latest development release from our
+<link
+xlink:href="http://hydra.nixos.org/job/nix/master/release/latest-finished#tabs-constituents">continuous
+build system</link>.</para>
+
+<para>For Fedora, RPM packages are available.  These can be installed
+or upgraded using <command>rpm -U</command>.  For example,
+
+<screen>
+$ rpm -U nix-1.8-1.i386.rpm</screen>
+
+</para>
+
+<para>For Debian and Ubuntu, you can download a Deb package and
+install it like this:
+
+<screen>
+$ dpkg -i nix_1.8-1_amd64.deb</screen>
+
+</para>
+-->
+
+<para>You can also download a binary tarball that contains Nix and all
+its dependencies.  (This is what the install script at
+<uri>https://nixos.org/nix/install</uri> does automatically.)  You
+should unpack it somewhere (e.g. in <filename>/tmp</filename>), and
+then run the script named <command>install</command> inside the binary
+tarball:
+
+<screen>
+alice$ cd /tmp
+alice$ tar xfj nix-1.8-x86_64-darwin.tar.bz2
+alice$ cd nix-1.8-x86_64-darwin
+alice$ ./install
+</screen>
+
+</para>
+
+<para>Nix can be uninstalled using <command>rpm -e nix</command> or
+<command>dpkg -r nix</command> on RPM- and Dpkg-based systems,
+respectively.  After this you should manually remove the Nix store and
+other auxiliary data, if desired:
+
+<screen>
+$ rm -rf /nix</screen>
+
+</para>
+
+<para>You can uninstall Nix simply by running:
+
+<screen>
+$ rm -rf /nix
+</screen>
+
+</para>
+
+</chapter>

doc/manual/installation/installing-source.xml

@@ -0,0 +1,16 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="ch-installing-source">
+
+<title>Installing Nix from Source</title>
+
+<para>If no binary package is available, you can download and compile
+a source distribution.</para>
+
+<xi:include href="prerequisites-source.xml" />
+<xi:include href="obtaining-source.xml" />
+<xi:include href="building-source.xml" />
+
+</chapter>

doc/manual/installation/multi-user.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="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> and a set of trusted
+users specified in <filename>nix.conf</filename> can specify arbitrary
+binary caches. So while unprivileged users may install packages from
+arbitrary Nix expressions, they may not get pre-built
+binaries.</para></note>
+
+
+<simplesect>
+
+<title>Setting up the build users</title>
+
+<para>The <emphasis>build users</emphasis> are the special UIDs under
+which builds are performed.  They should all be members of the
+<emphasis>build users group</emphasis> <literal>nixbld</literal>.
+This group should have no other members.  The build users should not
+be members of any other group. On Linux, you can create the group and
+users as follows:
+
+<screen>
+$ groupadd -r nixbld
+$ for n in $(seq 1 10); do useradd -c "Nix build user $n" \
+    -d /var/empty -g nixbld -G nixbld -M -N -r -s "$(which nologin)" \
+    nixbld$n; done
+</screen>
+
+This creates 10 build users. There can never be more concurrent builds
+than the number of build users, so you may want to increase this if
+you expect to do many builds at the same time.</para>
+
+<para>On macOS, you can create the required group and users by
+running the following script:
+
+<programlisting>
+#! /bin/bash -e
+
+dseditgroup -o create nixbld -q
+
+gid=$(dscl . -read /Groups/nixbld | awk '($1 == "PrimaryGroupID:") {print $2 }')
+
+echo "created nixbld group with gid $gid"
+
+for i in $(seq 1 10); do
+    user=/Users/nixbld$i
+    uid="$((30000 + $i))"
+    dscl . create $user
+    dscl . create $user RealName "Nix build user $i"
+    dscl . create $user PrimaryGroupID "$gid"
+    dscl . create $user UserShell /usr/bin/false
+    dscl . create $user NFSHomeDirectory /var/empty
+    dscl . create $user UniqueID "$uid"
+    dseditgroup -o edit -a nixbld$i -t user nixbld
+    echo "created nixbld$i user with uid $uid"
+done
+</programlisting>
+
+</para>
+
+</simplesect>
+
+
+<simplesect>
+
+<title>Running the daemon</title>
+
+<para>The <link linkend="sec-nix-daemon">Nix daemon</link> should be
+started as follows (as <literal>root</literal>):
+
+<screen>
+$ nix-daemon</screen>
+
+You’ll want to put that line somewhere in your system’s boot
+scripts.</para>
+
+<para>To let unprivileged users use the daemon, they should set the
+<link linkend="envar-remote"><envar>NIX_REMOTE</envar> environment
+variable</link> to <literal>daemon</literal>.  So you should put a
+line like
+
+<programlisting>
+export NIX_REMOTE=daemon</programlisting>
+
+into the users’ login scripts.</para>
+
+</simplesect>
+
+
+<simplesect>
+
+<title>Restricting access</title>
+
+<para>To limit which users can perform Nix operations, you can use the
+permissions on the directory
+<filename>/nix/var/nix/daemon-socket</filename>.  For instance, if you
+want to restrict the use of Nix to the members of a group called
+<literal>nix-users</literal>, do
+
+<screen>
+$ chgrp nix-users /nix/var/nix/daemon-socket
+$ chmod ug=rwx,o= /nix/var/nix/daemon-socket
+</screen>
+
+This way, users who are not in the <literal>nix-users</literal> group
+cannot connect to the Unix domain socket
+<filename>/nix/var/nix/daemon-socket/socket</filename>, so they cannot
+perform Nix operations.</para>
+
+</simplesect>
+
+
+</section>

doc/manual/installation/nix-security.xml

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

doc/manual/installation/obtaining-source.xml

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

doc/manual/installation/prerequisites-source.xml

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

doc/manual/installation/single-user.xml

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

doc/manual/installation/supported-platforms.xml

@@ -0,0 +1,39 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="ch-supported-platforms">
+
+<title>Supported Platforms</title>
+
+<para>Nix is currently supported on the following platforms:
+
+<itemizedlist>
+
+  <listitem><para>Linux (i686, x86_64).</para></listitem>
+
+  <listitem><para>macOS (x86_64).</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 fairly portable, so it should work on most platforms that
+support POSIX threads and have a C++11 compiler.</para>
+
+</chapter>