Grmbl

This should get rid of a certificate warning from "nix-env -i" early
in the install script.

.gitignore

@@ -1,8 +1,6 @@
-# START "git svn show-ignore"
+Makefile.config
 
 # /
-/Makefile
-/Makefile.in
 /aclocal.m4
 /autom4te.cache
 /config.*
@@ -10,86 +8,31 @@
 /nix.spec
 /stamp-h1
 /svn-revision
-/NEWS
 /libtool
 
-# /config/
-/config/config.guess
-/config/config.sub
-/config/depcomp
-/config/install-sh
-/config/missing
-/config/mkinstalldirs
-/config/ltmain.sh
-
-# /corepkgs/
-/corepkgs/Makefile
-/corepkgs/Makefile.in
+/corepkgs/config.nix
 
 # /corepkgs/buildenv/
-/corepkgs/buildenv/Makefile.in
-/corepkgs/buildenv/Makefile
 /corepkgs/buildenv/builder.pl
 
 # /corepkgs/channels/
-/corepkgs/channels/Makefile.in
-/corepkgs/channels/Makefile
 /corepkgs/channels/unpack.sh
 
 # /corepkgs/nar/
-/corepkgs/nar/Makefile
-/corepkgs/nar/Makefile.in
 /corepkgs/nar/nar.sh
 /corepkgs/nar/unnar.sh
 
-# /doc/
-/doc/Makefile
-/doc/Makefile.in
-
 # /doc/manual/
-/doc/manual/Makefile
-/doc/manual/Makefile.in
 /doc/manual/manual.html
+/doc/manual/manual.xmli
+/doc/manual/manual.pdf
 /doc/manual/manual.is-valid
 /doc/manual/*.1
+/doc/manual/*.5
 /doc/manual/*.8
-/doc/manual/images
 /doc/manual/version.txt
-/doc/manual/NEWS.html
-/doc/manual/NEWS.txt
-
-# /externals/
-/externals/Makefile
-/externals/Makefile.in
-/externals/aterm-*
-/externals/have-aterm
-/externals/build-aterm
-/externals/inst-aterm
-/externals/bzip2-*
-/externals/have-bzip2
-/externals/build-bzip2
-/externals/inst-bzip2
-
-# /make/examples/aterm/
-/make/examples/aterm/result*
-
-# /make/examples/aterm/aterm/
-/make/examples/aterm/aterm/*
-
-# /make/examples/aterm/test/
-/make/examples/aterm/test/*
-
-# /misc/
-/misc/Makefile.in
-/misc/Makefile
-
-# /misc/emacs/
-/misc/emacs/Makefile.in
-/misc/emacs/Makefile
 
 # /scripts/
-/scripts/Makefile
-/scripts/Makefile.in
 /scripts/nix-profile.sh
 /scripts/nix-pull
 /scripts/nix-push
@@ -100,160 +43,80 @@
 /scripts/nix-channel
 /scripts/nix-build
 /scripts/nix-copy-closure
-/scripts/readmanifest.pm
-/scripts/readconfig.pm
+/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/generate-patches.pl
+/scripts/download-from-binary-cache.pl
 /scripts/find-runtime-roots.pl
 /scripts/build-remote.pl
-
-# /src/
-/src/Makefile
-/src/Makefile.in
-
-# /src/bin2c/
-/src/bin2c/Makefile.in
-/src/bin2c/Makefile
-/src/bin2c/bin2c
-/src/bin2c/.deps
-/src/bin2c/.libs
-
-# /src/boost/
-/src/boost/Makefile
-/src/boost/Makefile.in
-
-# /src/boost/format/
-/src/boost/format/Makefile
-/src/boost/format/Makefile.in
-/src/boost/format/.deps
-/src/boost/format/libformat.a
-/src/boost/format/.libs
+/scripts/nix-reduce-build
+/scripts/nix-http-export.cgi
 
 # /src/bsdiff-4.3/
-/src/bsdiff-4.3/Makefile
-/src/bsdiff-4.3/Makefile.in
 /src/bsdiff-4.3/bsdiff
 /src/bsdiff-4.3/bspatch
-/src/bsdiff-4.3/.deps
-/src/bsdiff-4.3/.libs
 
 # /src/libexpr/
-/src/libexpr/Makefile
-/src/libexpr/Makefile.in
-/src/libexpr/.deps
-/src/libexpr/libexpr.a
 /src/libexpr/lexer-tab.cc
 /src/libexpr/lexer-tab.hh
 /src/libexpr/parser-tab.cc
 /src/libexpr/parser-tab.hh
 /src/libexpr/parser-tab.output
-/src/libexpr/nixexpr-ast.hh
-/src/libexpr/nixexpr-ast.cc
-/src/libexpr/.libs
 /src/libexpr/nix.tbl
 
-# /src/libmain/
-/src/libmain/Makefile
-/src/libmain/Makefile.in
-/src/libmain/.deps
-/src/libmain/libmain.a
-/src/libmain/.libs
-
 # /src/libstore/
-/src/libstore/Makefile
-/src/libstore/Makefile.in
-/src/libstore/.deps
-/src/libstore/libstore.a
-/src/libstore/derivations-ast.cc
-/src/libstore/derivations-ast.hh
-/src/libstore/.libs
-
-# /src/libutil/
-/src/libutil/Makefile
-/src/libutil/Makefile.in
-/src/libutil/.deps
-/src/libutil/libutil.a
-/src/libutil/.libs
+/src/libstore/schema.sql.hh
 
 # /src/nix-env/
-/src/nix-env/Makefile.in
-/src/nix-env/Makefile
-/src/nix-env/.deps
 /src/nix-env/nix-env
-/src/nix-env/help.txt.hh
-/src/nix-env/.libs
 
 # /src/nix-hash/
-/src/nix-hash/Makefile
-/src/nix-hash/Makefile.in
-/src/nix-hash/.deps
-/src/nix-hash/.libs
 /src/nix-hash/nix-hash
-/src/nix-hash/help.txt.hh
 
 # /src/nix-instantiate/
-/src/nix-instantiate/Makefile.in
-/src/nix-instantiate/Makefile
-/src/nix-instantiate/.deps
 /src/nix-instantiate/nix-instantiate
-/src/nix-instantiate/help.txt.hh
-/src/nix-instantiate/.libs
 
 # /src/nix-log2xml/
-/src/nix-log2xml/Makefile.in
-/src/nix-log2xml/Makefile
-/src/nix-log2xml/.deps
 /src/nix-log2xml/nix-log2xml
-/src/nix-log2xml/test*.*
-/src/nix-log2xml/.libs
-/src/nix-log2xml/*.log
-/src/nix-log2xml/*.xml
-/src/nix-log2xml/*.html
-
-# /src/nix-setuid-helper/
-/src/nix-setuid-helper/Makefile.in
-/src/nix-setuid-helper/Makefile
-/src/nix-setuid-helper/.deps
-/src/nix-setuid-helper/nix-setuid-helper
-/src/nix-setuid-helper/help.txt.hh
-/src/nix-setuid-helper/.libs
 
 # /src/nix-store/
-/src/nix-store/Makefile
-/src/nix-store/Makefile.in
-/src/nix-store/.deps
-/src/nix-store/help.txt.hh
 /src/nix-store/nix-store
-/src/nix-store/.libs
 
-# /src/nix-worker/
-/src/nix-worker/Makefile.in
-/src/nix-worker/Makefile
-/src/nix-worker/.deps
-/src/nix-worker/nix-worker
-/src/nix-worker/help.txt.hh
-/src/nix-worker/.libs
+# /src/nix-daemon/
+/src/nix-daemon/nix-daemon
+
+# /src/download-via-ssh/
+/src/download-via-ssh/download-via-ssh
 
 # /tests/
-/tests/Makefile
-/tests/Makefile.in
 /tests/test-tmp
-/tests/config.nix
 /tests/common.sh
 /tests/dummy
+/tests/result*
 
 # /tests/lang/
 /tests/lang/*.out
 /tests/lang/*.out.xml
 /tests/lang/*.ast
 
-# END "git svn show-ignore"
+/perl/lib/Nix/Config.pm
+/perl/lib/Nix/Store.cc
 
-*.lo
-*.la
+/misc/systemd/nix-daemon.service
+/misc/systemd/nix-daemon.socket
+/misc/upstart/nix-daemon.conf
+
+*.a
 *.o
+*.so
+*.dll
+*.exe
+*.dep
 *~
+*.pc
 
 # GNU Global
 GPATH

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

Makefile

@@ -0,0 +1,39 @@
+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-hash/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/download-via-ssh/local.mk \
+  src/nix-log2xml/local.mk \
+  src/nix-prefetch-url/local.mk \
+  src/bsdiff-4.3/local.mk \
+  perl/local.mk \
+  scripts/local.mk \
+  corepkgs/local.mk \
+  misc/systemd/local.mk \
+  misc/launchd/local.mk \
+  misc/upstart/local.mk \
+  misc/emacs/local.mk \
+  doc/manual/local.mk \
+  tests/local.mk
+
+GLOBAL_CXXFLAGS += -std=c++0x -g -Wall
+
+-include Makefile.config
+
+OPTIMIZE = 1
+
+ifeq ($(OPTIMIZE), 1)
+  GLOBAL_CFLAGS += -O3
+  GLOBAL_CXXFLAGS += -O3
+endif
+
+include mk/lib.mk

Makefile.am

@@ -1,48 +0,0 @@
-SUBDIRS = externals src scripts corepkgs doc misc tests
-EXTRA_DIST = substitute.mk nix.spec nix.spec.in bootstrap.sh \
-  nix.conf.example NEWS version
-
-pkginclude_HEADERS = config.h
-
-include ./substitute.mk
-
-nix.spec: nix.spec.in
-
-install-data-local: init-state
-	$(INSTALL) -d $(DESTDIR)$(sysconfdir)/nix
-	$(INSTALL_DATA) $(srcdir)/nix.conf.example $(DESTDIR)$(sysconfdir)/nix
-	if ! test -e $(DESTDIR)$(sysconfdir)/nix/nix.conf; then \
-		$(INSTALL_DATA) $(srcdir)/nix.conf.example $(DESTDIR)$(sysconfdir)/nix/nix.conf; \
-	fi
-	$(INSTALL) -d $(DESTDIR)$(docdir)
-	$(INSTALL_DATA) README $(DESTDIR)$(docdir)/
-
-if INIT_STATE
-
-# For setuid operation, you can enable the following:
-# INIT_FLAGS = -g @NIX_GROUP@ -o @NIX_USER@
-# GROUP_WRITABLE = -m 775
-
-init-state:
-	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(localstatedir)/nix
-	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(localstatedir)/nix/db
-	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(localstatedir)/log/nix
-	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(localstatedir)/log/nix/drvs
-	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(localstatedir)/nix/profiles
-	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(localstatedir)/nix/gcroots
-	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(localstatedir)/nix/temproots
-	ln -sfn $(localstatedir)/nix/profiles $(DESTDIR)$(localstatedir)/nix/gcroots/profiles
-	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(localstatedir)/nix/userpool
-	-$(INSTALL) $(INIT_FLAGS) -m 1777 -d $(DESTDIR)$(storedir)
-	$(INSTALL) $(INIT_FLAGS) $(GROUP_WRITABLE) -d $(DESTDIR)$(localstatedir)/nix/manifests
-	ln -sfn $(localstatedir)/nix/manifests $(DESTDIR)$(localstatedir)/nix/gcroots/manifests
-
-else
-
-init-state:
-
-endif
-
-NEWS:
-	$(MAKE) -C doc/manual NEWS.txt
-	cp $(srcdir)/doc/manual/NEWS.txt NEWS

Makefile.config.in

@@ -0,0 +1,35 @@
+BDW_GC_LIBS = @BDW_GC_LIBS@
+CC = @CC@
+CFLAGS = @CFLAGS@
+CXX = @CXX@
+CXXFLAGS = @CXXFLAGS@
+HAVE_SODIUM = @HAVE_SODIUM@
+LIBCURL_LIBS = @LIBCURL_LIBS@
+OPENSSL_LIBS = @OPENSSL_LIBS@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+SODIUM_LIBS = @SODIUM_LIBS@
+SQLITE3_LIBS = @SQLITE3_LIBS@
+bash = @bash@
+bindir = @bindir@
+bsddiff_compat_include = @bsddiff_compat_include@
+curl = @curl@
+datadir = @datadir@
+datarootdir = @datarootdir@
+dblatex = @dblatex@
+docdir = @docdir@
+exec_prefix = @exec_prefix@
+includedir = @includedir@
+libdir = @libdir@
+libexecdir = @libexecdir@
+localstatedir = @localstatedir@
+mandir = @mandir@
+perl = @perl@
+perlbindings = @perlbindings@
+perllibdir = @perllibdir@
+pkglibdir = $(libdir)/$(PACKAGE_NAME)
+prefix = @prefix@
+storedir = @storedir@
+sysconfdir = @sysconfdir@
+xmllint = @xmllint@
+xsltproc = @xsltproc@

aterm-gc.supp

@@ -1,149 +0,0 @@
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Cond
-   fun:*
-   fun:AT_collect_minor
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Cond
-   fun:*
-   fun:*
-   fun:AT_collect_minor
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value4
-   fun:*
-   fun:AT_collect_minor
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value8
-   fun:*
-   fun:AT_collect_minor
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value4
-   fun:*
-   fun:*
-   fun:AT_collect_minor
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value8
-   fun:*
-   fun:*
-   fun:AT_collect_minor
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Addr4
-   fun:*
-   fun:AT_collect_minor
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Addr8
-   fun:*
-   fun:AT_collect_minor
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Cond
-   fun:*
-   fun:AT_collect
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value4
-   fun:*
-   fun:AT_collect
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value8
-   fun:*
-   fun:AT_collect
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Addr4
-   fun:*
-   fun:AT_collect
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Addr8
-   fun:*
-   fun:AT_collect
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value4
-   fun:*
-   fun:*
-   fun:AT_collect
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value8
-   fun:*
-   fun:*
-   fun:AT_collect
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Cond
-   fun:*
-   fun:*
-   fun:AT_collect
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value4
-   fun:*
-   fun:*
-   fun:mark_phase
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Cond
-   fun:*
-   fun:*
-   fun:mark_phase
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Value4
-   fun:*
-   fun:*
-   fun:mark_phase_young
-}
-
-{
-   ATerm library conservatively scans for GC roots
-   Memcheck:Cond
-   fun:*
-   fun:*
-   fun:mark_phase_young
-}

blacklisting/check-env.pl

@@ -1,252 +0,0 @@
-#! /usr/bin/perl -w -I /home/eelco/.nix-profile/lib/site_perl
-
-use strict;
-use XML::LibXML;
-#use XML::Simple;
-
-my $blacklistFN = shift @ARGV;
-die unless defined $blacklistFN;
-my $userEnv = shift @ARGV;
-die unless defined $userEnv;
-
-
-# Read the blacklist.
-my $parser = XML::LibXML->new();
-my $blacklist = $parser->parse_file($blacklistFN)->getDocumentElement;
-
-#print $blacklist->toString() , "\n";
-
-
-# Get all the elements of the user environment.
-my $userEnvElems = `nix-store --query --references '$userEnv'`;
-die "cannot query user environment elements" if $? != 0;
-my @userEnvElems = split ' ', $userEnvElems;
-
-
-my %storePathHashes;
-
-
-sub getElemNodes {
-    my $node = shift;
-    my @elems = ();
-    foreach my $node ($node->getChildNodes) {
-        push @elems, $node if $node->nodeType == XML_ELEMENT_NODE;
-    }
-    return @elems;
-}
-
-
-my %referencesCache;
-sub getReferences {
-    my $path = shift;
-    return $referencesCache{$path} if defined $referencesCache{$path};
-    
-    my $references = `nix-store --query --references '$path'`;
-    die "cannot query references" if $? != 0;
-    $referencesCache{$path} = [split ' ', $references];
-    
-    return $referencesCache{$path};
-}
-
-
-my %attrsCache;
-sub getAttr {
-    my $path = shift;
-    my $name = shift;
-    my $key = "$path/$name";
-    return $referencesCache{$key} if defined $referencesCache{$key};
-
-    my $value = `nix-store --query --binding '$name' '$path' 2> /dev/null`;
-    $value = "" if $? != 0; # !!!
-    chomp $value;
-    $referencesCache{$key} = $value;
-
-    return $value;
-}
-
-
-sub evalCondition;
-
-
-sub traverse {
-    my $done = shift;
-    my $set = shift;
-    my $path = shift;
-    my $stopCondition = shift;
-
-    return if defined $done->{$path};
-    $done->{$path} = 1;
-    $set->{$path} = 1;
-
-#    print "  in $path\n";
-
-    if (!evalCondition({$path => 1}, $stopCondition)) {
-#        print "  STOPPING in $path\n";
-        return;
-    }
-
-    # Get the requisites of the deriver.
-
-    foreach my $reference (@{getReferences $path}) {
-        traverse($done, $set, $reference, $stopCondition);
-    }
-}
-
-
-sub evalSet {
-    my $inSet = shift;
-    my $expr = shift;
-    my $name = $expr->getName;
-    
-    if ($name eq "traverse") {
-        my $stopCondition = (getElemNodes $expr)[0];
-        my $done = { };
-        my $set = { };
-        foreach my $path (keys %{$inSet}) {
-            traverse($done, $set, $path, $stopCondition);
-        }
-        return $set;
-    }
-
-    else {
-        die "unknown element `$name'";
-    }
-}
-
-
-# Function for evaluating conditions.
-sub evalCondition {
-    my $storePaths = shift;
-    my $condition = shift;
-    my $elemName = $condition->getName;
-    
-    if ($elemName eq "containsSource") {
-        my $hash = $condition->attributes->getNamedItem("hash")->getValue;
-        foreach my $path (keys %{$storePathHashes{$hash}}) {
-            return 1 if defined $storePaths->{$path};
-        }
-        return 0;
-    }
-
-    elsif ($elemName eq "hasName") { 
-        my $nameRE = $condition->attributes->getNamedItem("name")->getValue;
-        foreach my $path (keys %{$storePaths}) {
-            return 1 if $path =~ /$nameRE/;
-        }
-        return 0;
-    }
-    
-    elsif ($elemName eq "hasAttr") { 
-        my $name = $condition->attributes->getNamedItem("name")->getValue;
-        my $valueRE = $condition->attributes->getNamedItem("value")->getValue;
-        foreach my $path (keys %{$storePaths}) {
-            if ($path =~ /\.drv$/) {
-                my $value = getAttr($path, $name);
-#                print "    $path $name $value\n";
-                return 1 if $value =~ /$valueRE/;
-            }
-        }
-        return 0;
-    }
-    
-    elsif ($elemName eq "and") {
-        my $result = 1;
-        foreach my $node (getElemNodes $condition) {
-            $result &= evalCondition($storePaths, $node);
-        }
-        return $result;
-    }
-
-    elsif ($elemName eq "not") {
-        return !evalCondition($storePaths, (getElemNodes $condition)[0]);
-    }
-    
-    elsif ($elemName eq "within") {
-        my @elems = getElemNodes $condition;
-        my $set = evalSet($storePaths, $elems[0]);
-        return evalCondition($set, $elems[1]);
-    }
-
-    elsif ($elemName eq "true") {
-        return 1;
-    }
-
-    elsif ($elemName eq "false") {
-        return 0;
-    }
-
-    else {
-        die "unknown element `$elemName'";
-    }
-}
-
-
-sub evalOr {
-    my $storePaths = shift;
-    my $nodes = shift;
-
-    my $result = 0;
-    foreach my $node (@{$nodes}) {
-        $result |= evalCondition($storePaths, $node);
-    }
-    
-    return $result;
-}
-
-
-# Iterate over all elements, check them.
-foreach my $userEnvElem (@userEnvElems) {
-
-    # Get the deriver of this path.
-    my $deriver = `nix-store --query --deriver '$userEnvElem'`;
-    die "cannot query deriver" if $? != 0;
-    chomp $deriver;
-
-    if ($deriver eq "unknown-deriver") {
-#        print "  deriver unknown, cannot check sources\n";
-        next;
-    }
-
-    print "CHECKING $userEnvElem\n";
-
-
-    # Get the requisites of the deriver.
-#    my $requisites = `nix-store --query --requisites --include-outputs '$deriver'`;
-#    die "cannot query requisites" if $? != 0;
-#    my @requisites = split ' ', $requisites;
-
-
-    # Get the hashes of the requisites.
-#    my $hashes = `nix-store --query --hash @requisites`;
-#    die "cannot query hashes" if $? != 0;
-#    my @hashes = split ' ', $hashes;
-#    for (my $i = 0; $i < scalar @requisites; $i++) {
-#        die unless $i < scalar @hashes;
-#        my $hash = $hashes[$i];
-#        $storePathHashes{$hash} = {} unless defined $storePathHashes{$hash};
-#        my $r = $storePathHashes{$hash}; # !!! fix
-#        $$r{$requisites[$i]} = 1;
-#    }
-
-
-    # Evaluate each blacklist item.
-    foreach my $item ($blacklist->getChildrenByTagName("item")) {
-        my $itemId = $item->getAttributeNode("id")->getValue;
-#        print "  CHECKING FOR $itemId\n";
-
-        my $condition = ($item->getChildrenByTagName("condition"))[0];
-        die unless $condition;
-
-        # Evaluate the condition.
-        my @elems = getElemNodes $condition;
-        if (evalOr({$deriver => 1}, \@elems)) {
-            # Oops, condition triggered.
-            my $reason = ($item->getChildrenByTagName("reason"))[0]->getChildNodes->to_literal;
-            $reason =~ s/\s+/ /g;
-            $reason =~ s/^\s+//g;
-
-            print "    VULNERABLE TO `$itemId': $reason\n";
-        }
-    }
-}
-

bootstrap.sh

@@ -1,8 +1,4 @@
 #! /bin/sh -e
 rm -f aclocal.m4
 mkdir -p config
-libtoolize --copy
-aclocal
-autoheader
-automake --add-missing --copy
-autoconf
+exec autoreconf -vfi

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,36 +1,36 @@
-AC_INIT(nix, m4_esyscmd([echo -n $(cat ./version)$VERSION_SUFFIX]))
+AC_INIT(nix, m4_esyscmd([bash -c "echo -n $(cat ./version)$VERSION_SUFFIX"]))
 AC_CONFIG_SRCDIR(README)
 AC_CONFIG_AUX_DIR(config)
-AM_INIT_AUTOMAKE([dist-bzip2 foreign])
-
-AC_DEFINE_UNQUOTED(NIX_VERSION, ["$VERSION"], [Nix version.])
-
-AC_CANONICAL_HOST
 
+AC_PROG_SED
 
 # Construct a Nix system name (like "i686-linux").
+AC_CANONICAL_HOST
 AC_MSG_CHECKING([for the canonical Nix system name])
-cpu_name=$(uname -p | tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ ' 'abcdefghijklmnopqrstuvwxyz_')
-machine_name=$(uname -m | tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ ' 'abcdefghijklmnopqrstuvwxyz_')
 
-case $machine_name in
-    i*86)
-        machine_name=i686
-        ;;
-    x86_64)
-        machine_name=x86_64
-        ;;
-    ppc)
-        machine_name=powerpc
-        ;;
-    *)
-        if test "$cpu_name" != "unknown"; then
-            machine_name=$cpu_name
-        fi
-        ;;
-esac
+AC_ARG_WITH(system, AC_HELP_STRING([--with-system=SYSTEM],
+  [Platform identifier (e.g., `i686-linux').]),
+  [system=$withval],
+  [case "$host_cpu" in
+     i*86)
+        machine_name="i686";;
+     amd64)
+        machine_name="x86_64";;
+     *)
+        machine_name="$host_cpu";;
+   esac
 
-sys_name=$(uname -s | tr 'ABCDEFGHIJKLMNOPQRSTUVWXYZ ' 'abcdefghijklmnopqrstuvwxyz_')
+   case "$host_os" in
+     linux-gnu*)
+        # For backward compatibility, strip the `-gnu' part.
+        system="$machine_name-linux";;
+     *)
+        # Strip the version number from names such as `gnu0.3',
+        # `darwin10.2.0', etc.
+        system="$machine_name-`echo $host_os | "$SED" -e's/@<:@0-9.@:>@*$//g'`";;
+   esac])
+
+sys_name=$(uname -s | tr 'A-Z ' 'a-z_')
 
 case $sys_name in
     cygwin*)
@@ -38,9 +38,6 @@ case $sys_name in
         ;;
 esac
 
-AC_ARG_WITH(system, AC_HELP_STRING([--with-system=SYSTEM],
-  [Platform identifier (e.g., `i686-linux').]),
-  system=$withval, system="${machine_name}-${sys_name}")
 AC_MSG_RESULT($system)
 AC_SUBST(system)
 AC_DEFINE_UNQUOTED(SYSTEM, ["$system"], [platform identifier (`cpu-os')])
@@ -50,49 +47,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.
-if test "$sys_name" = "sunos"; then
+AC_STRUCT_DIRENT_D_TYPE
+if test "$sys_name" = sunos; then
     # Solaris requires -lsocket -lnsl for network functions
     LIBS="-lsocket -lnsl $LIBS"
 fi
 
 
+CFLAGS=
+CXXFLAGS=
 AC_PROG_CC
 AC_PROG_CXX
 
-# To build programs to be run in the build machine
-if test "$CC_FOR_BUILD" = ""; then
-    if test "$cross_compiling" = "yes"; then
-        AC_CHECK_PROGS(CC_FOR_BUILD, gcc cc)
-    else
-        CC_FOR_BUILD="$CC"
-    fi
-fi
-AC_SUBST([CC_FOR_BUILD])
-
-# We are going to use libtool.
-AC_DISABLE_STATIC
-AC_ENABLE_SHARED
-AC_PROG_LIBTOOL
-
-if test "$enable_shared" = yes; then
-   SUB_CONFIGURE_FLAGS="--enable-shared --disable-static"
-else
-   SUB_CONFIGURE_FLAGS="--enable-static --disable-shared"
-fi
-AC_SUBST(SUB_CONFIGURE_FLAGS)
-
 
 # Use 64-bit file system calls so that we can support files > 2 GiB.
 AC_SYS_LARGEFILE
@@ -110,21 +77,29 @@ static char buf[1024];]],
 AC_LANG_POP(C++)
 
 
-# Check for chroot support (requires chroot() and bind mounts).
-AC_CHECK_FUNCS([chroot])
-AC_CHECK_FUNCS([unshare])
-AC_CHECK_HEADERS([sched.h], [], [], [])
-AC_CHECK_HEADERS([sys/param.h], [], [], [])
-AC_CHECK_HEADERS([sys/mount.h], [], [],
-[#ifdef HAVE_SYS_PARAM_H
-# include <sys/param.h>
-# endif
-])
+AC_CHECK_FUNCS([statvfs])
+
+
+# Check for lutimes, optionally used for changing the mtime of
+# symlinks.
+AC_CHECK_FUNCS([lutimes])
+
+
+# Check whether the store optimiser can optimise symlinks.
+AC_MSG_CHECKING([whether it is possible to create a link to a symlink])
+ln -s bla tmp_link
+if ln tmp_link tmp_link2 2> /dev/null; then
+    AC_MSG_RESULT(yes)
+    AC_DEFINE(CAN_LINK_SYMLINK, 1, [Whether link() works on symlinks.])
+else
+    AC_MSG_RESULT(no)
+fi
+rm -f tmp_link tmp_link2
 
 
 # Check for <locale>.
 AC_LANG_PUSH(C++)
-AC_CHECK_HEADERS([locale], [], [], [])
+AC_CHECK_HEADERS([locale])
 AC_LANG_POP(C++)
 
 
@@ -133,17 +108,6 @@ AC_CHECK_HEADER([err.h], [], [bsddiff_compat_include="-Icompat-include"])
 AC_SUBST([bsddiff_compat_include])
 
 
-# Check whether we have the personality() syscall, which allows us to
-# do i686-linux builds on x86_64-linux machines.
-AC_CHECK_HEADERS([sys/personality.h])
-
-
-# Check for tr1/unordered_set.
-AC_LANG_PUSH(C++)
-AC_CHECK_HEADERS([tr1/unordered_set], [], [], [])
-AC_LANG_POP(C++)
-
-
 AC_DEFUN([NEED_PROG],
 [
 AC_PATH_PROG($1, $2)
@@ -157,19 +121,18 @@ NEED_PROG(bash, bash)
 NEED_PROG(patch, patch)
 AC_PATH_PROG(xmllint, xmllint, false)
 AC_PATH_PROG(xsltproc, xsltproc, false)
-AC_PATH_PROG(w3m, w3m, false)
 AC_PATH_PROG(flex, flex, false)
 AC_PATH_PROG(bison, bison, false)
 NEED_PROG(perl, perl)
 NEED_PROG(sed, sed)
 NEED_PROG(tar, tar)
+NEED_PROG(bzip2, bzip2)
+NEED_PROG(gzip, gzip)
+NEED_PROG(xz, xz)
 AC_PATH_PROG(dot, dot)
 AC_PATH_PROG(dblatex, dblatex)
-AC_PATH_PROG(gzip, gzip)
+AC_PATH_PROG(pv, pv, pv)
 
-AC_PATH_PROG(openssl_prog, openssl, openssl) # if not found, call openssl in $PATH
-AC_SUBST(openssl_prog)
-AC_DEFINE_UNQUOTED(OPENSSL_PATH, ["$openssl_prog"], [Path of the OpenSSL binary])
 
 # Test that Perl has the open/fork feature (Perl 5.8.0 and beyond).
 AC_MSG_CHECKING([whether Perl is recent enough])
@@ -179,6 +142,15 @@ if ! $perl -e 'open(FOO, "-|", "true"); while (<FOO>) { print; }; close FOO or d
 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)
+
+
 NEED_PROG(cat, cat)
 NEED_PROG(tr, tr)
 AC_ARG_WITH(coreutils-bin, AC_HELP_STRING([--with-coreutils-bin=PATH],
@@ -186,99 +158,125 @@ AC_ARG_WITH(coreutils-bin, AC_HELP_STRING([--with-coreutils-bin=PATH],
   coreutils=$withval, coreutils=$(dirname $cat))
 AC_SUBST(coreutils)
 
-AC_ARG_WITH(docbook-rng, AC_HELP_STRING([--with-docbook-rng=PATH],
-  [path of the DocBook RelaxNG schema]),
-  docbookrng=$withval, docbookrng=/docbook-rng-missing)
-AC_SUBST(docbookrng)
-
-AC_ARG_WITH(docbook-xsl, AC_HELP_STRING([--with-docbook-xsl=PATH],
-  [path of the DocBook XSL stylesheets]),
-  docbookxsl=$withval, docbookxsl=/docbook-xsl-missing)
-AC_SUBST(docbookxsl)
-
-AC_ARG_WITH(xml-flags, AC_HELP_STRING([--with-xml-flags=FLAGS],
-  [extra flags to be passed to xmllint and xsltproc]),
-  xmlflags=$withval, xmlflags=)
-AC_SUBST(xmlflags)
 
 AC_ARG_WITH(store-dir, AC_HELP_STRING([--with-store-dir=PATH],
-  [path of the Nix store]),
+  [path of the Nix store (defaults to /nix/store)]),
   storedir=$withval, storedir='/nix/store')
 AC_SUBST(storedir)
 
-AC_ARG_WITH(openssl, AC_HELP_STRING([--with-openssl=PATH],
-  [prefix of the OpenSSL library]),
-  openssl=$withval, openssl=)
-AM_CONDITIONAL(HAVE_OPENSSL, test -n "$openssl")
-if test -n "$openssl"; then
-  LDFLAGS="-L$openssl/lib -lcrypto $LDFLAGS"
-  CFLAGS="-I$openssl/include $CFLAGS"
-  CXXFLAGS="-I$openssl/include $CXXFLAGS"
-  AC_DEFINE(HAVE_OPENSSL, 1, [Whether to use OpenSSL.])
-fi
 
-AC_ARG_WITH(bzip2, AC_HELP_STRING([--with-bzip2=PATH],
-  [prefix of bzip2]),
-  bzip2=$withval, bzip2=)
-AM_CONDITIONAL(HAVE_BZIP2, test -n "$bzip2")
-ATERM_VERSION=2.5
-AC_SUBST(ATERM_VERSION)
-if test -z "$bzip2"; then
-  # Headers and libraries will be used from the temporary installation
-  # in externals/inst-bzip2.
-  bzip2_lib='-L${top_builddir}/externals/inst-bzip2/lib -lbz2'
-  bzip2_include='-I${top_builddir}/externals/inst-bzip2/include'
-  # The binary will be copied to $libexecdir.
-  bzip2_bin='${libexecdir}/nix'
-  # But for testing, we have to use the temporary copy :-(
-  bzip2_bin_test='${top_builddir}/externals/inst-bzip2/bin'
-else
-  bzip2_lib="-L$bzip2/lib -lbz2"
-  bzip2_include="-I$bzip2/include"
-  bzip2_bin="$bzip2/bin"
-  bzip2_bin_test="$bzip2/bin"
-fi
-AC_SUBST(bzip2_lib)
-AC_SUBST(bzip2_include)
-AC_SUBST(bzip2_bin)
-AC_SUBST(bzip2_bin_test)
+# Look for OpenSSL, a required dependency.
+AC_PATH_PROG(openssl, openssl, openssl) # if not found, call openssl in $PATH
+AC_SUBST(openssl)
+AC_DEFINE_UNQUOTED(OPENSSL_PATH, ["$openssl"], [Path of the OpenSSL binary])
+
+PKG_CHECK_MODULES([OPENSSL], [libcrypto], [CXXFLAGS="$OPENSSL_CFLAGS $CXXFLAGS"])
+
+
+# Look for libbz2, a required dependency.
+AC_CHECK_LIB([bz2], [BZ2_bzWriteOpen], [true],
+  [AC_MSG_ERROR([Nix requires libbz2, which is part of bzip2.  See http://www.bzip.org/.])])
+AC_CHECK_HEADERS([bzlib.h], [true],
+  [AC_MSG_ERROR([Nix requires libbz2, which is part of bzip2.  See http://www.bzip.org/.])])
+
+
+# Look for SQLite, a required dependency.
+PKG_CHECK_MODULES([SQLITE3], [sqlite3 >= 3.6.19], [CXXFLAGS="$SQLITE3_CFLAGS $CXXFLAGS"])
+
+
+# Look for libcurl, a required dependency.
+PKG_CHECK_MODULES([LIBCURL], [libcurl], [CXXFLAGS="$LIBCURL_CFLAGS $CXXFLAGS"])
+
+
+# Look for libsodium, an optional dependency.
+PKG_CHECK_MODULES([SODIUM], [libsodium],
+  [AC_DEFINE([HAVE_SODIUM], [1], [Whether to use libsodium for cryptography.])
+   CXXFLAGS="$SODIUM_CFLAGS $CXXFLAGS"
+   have_sodium=1], [have_sodium=])
+AC_SUBST(HAVE_SODIUM, [$have_sodium])
+
+
+# Look for liblzma, a required dependency.
+PKG_CHECK_MODULES([LIBLZMA], [liblzma], [CXXFLAGS="$LIBLZMA_CFLAGS $CXXFLAGS"])
 
-AC_ARG_WITH(sqlite, AC_HELP_STRING([--with-sqlite=PATH],
-  [prefix of SQLite]),
-  sqlite=$withval, sqlite=)
-AM_CONDITIONAL(HAVE_SQLITE, test -n "$sqlite")
-SQLITE_VERSION=3070500
-AC_SUBST(SQLITE_VERSION)
-if test -z "$sqlite"; then
-  sqlite_lib='${top_builddir}/externals/sqlite-autoconf-$(SQLITE_VERSION)/libsqlite3.la'
-  sqlite_include='-I${top_builddir}/externals/sqlite-autoconf-$(SQLITE_VERSION)'
-  sqlite_bin='${top_builddir}/externals/sqlite-autoconf-$(SQLITE_VERSION)'
-else
-  sqlite_lib="-L$sqlite/lib -lsqlite3"
-  sqlite_include="-I$sqlite/include"
-  sqlite_bin="$sqlite/bin"
-fi
-AC_SUBST(sqlite_lib)
-AC_SUBST(sqlite_include)
-AC_SUBST(sqlite_bin)
 
 # Whether to use the Boehm garbage collector.
 AC_ARG_ENABLE(gc, AC_HELP_STRING([--enable-gc],
-  [enable garbage collection in the Nix expression evaluator (requires Boehm GC)]),
-  gc=$enableval, gc=)
-if test -n "$gc"; then
+  [enable garbage collection in the Nix expression evaluator (requires Boehm GC) [default=no]]),
+  gc=$enableval, gc=no)
+if test "$gc" = yes; then
   PKG_CHECK_MODULES([BDW_GC], [bdw-gc])
-  boehmgc_lib="-L$boehmgc/lib -lgc"
   CXXFLAGS="$BDW_GC_CFLAGS $CXXFLAGS"
   AC_DEFINE(HAVE_BOEHMGC, 1, [Whether to use the Boehm garbage collector.])
 fi
-AC_SUBST(boehmgc_lib)
+
+
+# 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)
+
+
+# Check for otool, an optional dependency on Darwin.
+AC_PATH_PROG(otool, otool)
+AC_MSG_CHECKING([that otool works])
+case $host_os in
+  darwin*)
+    if test -z "$otool" || ! $otool --version 2>/dev/null; then
+      AC_MSG_RESULT(no)
+      AC_MSG_ERROR([Can't get version from otool; do you need to install developer tools?])
+    fi
+    AC_MSG_RESULT(yes)
+    ;;
+  *)
+    AC_MSG_RESULT(not needed)
+    ;;
+esac
+
+
+# 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
+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")
 
 
 # Setuid installations.
@@ -286,44 +284,43 @@ AC_CHECK_FUNCS([setresuid setreuid lchown])
 
 
 # Nice to have, but not essential.
-AC_CHECK_FUNCS([strsignal posix_fallocate nanosleep])
+AC_CHECK_FUNCS([strsignal posix_fallocate nanosleep sysconf])
 
 
-# This is needed if ATerm or bzip2 are static libraries,
-# and the Nix libraries are dynamic.
+# This is needed if bzip2 is a static library, and the Nix libraries
+# are dynamic.
 if test "$(uname)" = "Darwin"; then
     LDFLAGS="-all_load $LDFLAGS"
 fi
 
 
-AM_CONFIG_HEADER([config.h])
-AC_CONFIG_FILES([Makefile
-   externals/Makefile
-   src/Makefile
-   src/bin2c/Makefile
-   src/boost/Makefile
-   src/boost/format/Makefile
-   src/libutil/Makefile
-   src/libstore/Makefile
-   src/libmain/Makefile
-   src/nix-store/Makefile
-   src/nix-hash/Makefile
-   src/libexpr/Makefile
-   src/nix-instantiate/Makefile
-   src/nix-env/Makefile
-   src/nix-worker/Makefile
-   src/nix-setuid-helper/Makefile
-   src/nix-log2xml/Makefile
-   src/bsdiff-4.3/Makefile
-   scripts/Makefile
-   corepkgs/Makefile
-   corepkgs/nar/Makefile
-   corepkgs/buildenv/Makefile
-   corepkgs/channels/Makefile
-   doc/Makefile
-   doc/manual/Makefile
-   misc/Makefile
-   misc/emacs/Makefile
-   tests/Makefile
-  ])
+# Figure out the extension of dynamic libraries.
+eval dynlib_suffix=$shrext_cmds
+AC_SUBST(dynlib_suffix)
+
+
+# Do we have GNU tar?
+AC_MSG_CHECKING([if you have a recent GNU tar])
+if $tar --version 2> /dev/null | grep -q GNU && tar cvf /dev/null --warning=no-timestamp ./config.log > /dev/null; then
+    AC_MSG_RESULT(yes)
+    tarFlags="--warning=no-timestamp"
+else
+    AC_MSG_RESULT(no)
+fi
+AC_SUBST(tarFlags)
+
+
+# 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 +0,0 @@
-SUBDIRS = nar buildenv channels

corepkgs/buildenv.nix

@@ -0,0 +1,45 @@
+with import <nix/config.nix>;
+
+{ derivations, manifest }:
+
+derivation {
+  name = "user-environment";
+  system = builtins.currentSystem;
+  builder = perl;
+  args = [ "-w" ./buildenv.pl ];
+
+  inherit manifest;
+
+  # !!! grmbl, need structured data for passing this in a clean way.
+  derivations =
+    map (d:
+      [ (d.meta.active or "true")
+        (d.meta.priority or 5)
+        (builtins.length d.outputs)
+      ] ++ map (output: builtins.getAttr output d) d.outputs)
+      derivations;
+
+  # Building user environments remotely just causes huge amounts of
+  # network traffic, so don't do that.
+  preferLocalBuild = true;
+
+  # Also don't bother substituting.
+  allowSubstitutes = false;
+
+  __sandboxProfile = ''
+    (allow sysctl-read)
+    (allow file-read*
+           (literal "/usr/lib/libSystem.dylib")
+           (literal "/usr/lib/libSystem.B.dylib")
+           (literal "/usr/lib/libobjc.A.dylib")
+           (literal "/usr/lib/libobjc.dylib")
+           (literal "/usr/lib/libauto.dylib")
+           (literal "/usr/lib/libc++abi.dylib")
+           (literal "/usr/lib/libc++.1.dylib")
+           (literal "/usr/lib/libDiagnosticMessagesClient.dylib")
+           (subpath "/usr/lib/system")
+           (subpath "/dev"))
+  '';
+
+  inherit chrootDeps;
+}

corepkgs/buildenv.pl

@@ -1,8 +1,7 @@
-#! @perl@ -w
-
 use strict;
 use Cwd;
 use IO::Handle;
+use utf8;
 
 STDOUT->autoflush(1);
 
@@ -38,19 +37,16 @@ sub createLinks {
         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);
             }
@@ -58,18 +54,18 @@ sub createLinks {
             elsif (-l _) {
                 my $target = readlink $dstFile or die;
                 if (!-d $target) {
-                    die "collission between directory `$srcFile' and non-directory `$target'";
+                    die "collision between directory ‘$srcFile’ and non-directory ‘$target’";
                 }
-                unlink $dstFile or die "error unlinking `$dstFile': $!";
-                mkdir $dstFile, 0755 || 
-                    die "error creating directory `$dstFile': $!";
+                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': $!";
+                    die "error creating link ‘$dstFile’: $!";
                 $priorities{$dstFile} = $priority;
                 $symlinks++;
             }
@@ -80,17 +76,16 @@ sub createLinks {
             if (-l $dstFile) {
                 my $target = readlink $dstFile;
                 my $prevPriority = $priorities{$dstFile};
-                die ( "Collission between `$srcFile' and `$target'. "
-                    . "Suggested solution: use `nix-env --set-flag "
-                    . "priority NUMBER PKGNAME' to change the priority of "
-                    . "one of the conflicting packages.\n" )
+                die("collision 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': $!";
+                die "error creating link ‘$dstFile’: $!";
             $priorities{$dstFile} = $priority;
             $symlinks++;
         }
@@ -127,32 +122,34 @@ sub addPkg {
 
 # Convert the stuff we get from the environment back into a coherent
 # data type.
-my @paths = split ' ', $ENV{"paths"};
-my @active = split ' ', $ENV{"active"};
-my @priority = split ' ', $ENV{"priority"};
-
-die if scalar @paths != scalar @active;
-die if scalar @paths != scalar @priority;
-
-my %pkgs;
-
-for (my $n = 0; $n < scalar @paths; $n++) {
-    $pkgs{$paths[$n]} =
-        { active => $active[$n]
-        , priority => $priority[$n] };
+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.
-foreach my $pkg (sort (keys %pkgs)) {
+# 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, $pkgs{$pkg}->{priority}) if $pkgs{$pkg}->{active} ne "false";
+    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 by the user (i.e., package X declares that it wants 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

corepkgs/buildenv/Makefile.am

@@ -1,11 +0,0 @@
-all-local: builder.pl
-
-install-exec-local:
-	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs
-	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs/buildenv
-	$(INSTALL_DATA) $(srcdir)/default.nix $(DESTDIR)$(datadir)/nix/corepkgs/buildenv
-	$(INSTALL_PROGRAM) builder.pl $(DESTDIR)$(datadir)/nix/corepkgs/buildenv
-
-include ../../substitute.mk
-
-EXTRA_DIST = default.nix builder.pl.in

corepkgs/buildenv/default.nix

@@ -1,18 +0,0 @@
-{system, derivations, manifest}:
-
-derivation { 
-  name = "user-environment";
-  system = system;
-  builder = ./builder.pl;
-  
-  manifest = manifest;
-
-  # !!! grmbl, need structured data for passing this in a clean way.
-  paths = derivations;
-  active = map (x: if x ? meta && x.meta ? active then x.meta.active else "true") derivations;
-  priority = map (x: if x ? meta && x.meta ? priority then x.meta.priority else "5") derivations;
-
-  # Building user environments remotely just causes huge amounts of
-  # network traffic, so don't do that.
-  preferLocalBuild = true;
-}

corepkgs/channels/Makefile.am

@@ -1,11 +0,0 @@
-all-local: unpack.sh
-
-install-exec-local:
-	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs
-	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs/channels
-	$(INSTALL_DATA) $(srcdir)/unpack.nix $(DESTDIR)$(datadir)/nix/corepkgs/channels
-	$(INSTALL_PROGRAM) unpack.sh $(DESTDIR)$(datadir)/nix/corepkgs/channels
-
-include ../../substitute.mk
-
-EXTRA_DIST = unpack.nix unpack.sh.in

corepkgs/channels/unpack.nix

@@ -1,7 +0,0 @@
-{system, inputs}:
-
-derivation {
-  name = "channels";
-  builder = ./unpack.sh;
-  inherit system inputs;
-}

corepkgs/channels/unpack.sh.in

@@ -1,35 +0,0 @@
-#! @shell@ -e
-
-# Cygwin compatibility hack: bunzip2 expects cygwin.dll in $PATH.
-export PATH=@coreutils@
-
-@coreutils@/mkdir $out
-@coreutils@/mkdir $out/tmp
-cd $out/tmp
-
-inputs=($inputs)
-for ((n = 0; n < ${#inputs[*]}; n += 2)); do
-    channelName=${inputs[n]}
-    channelTarball=${inputs[n+1]}
-    
-    echo "unpacking channel $channelName"
-    
-    @bunzip2@ < $channelTarball | @tar@ xf -
-
-    if test -e */channel-name; then
-        channelName="$(@coreutils@/cat */channel-name)"
-    fi
-
-    nr=1
-    attrName=$(echo $channelName | @tr@ -- '- ' '__')
-    dirName=$attrName
-    while test -e ../$dirName; do
-        nr=$((nr+1))
-        dirName=$attrName-$nr
-    done
-
-    @coreutils@/mv * ../$dirName # !!! hacky
-done
-
-cd ..
-@coreutils@/rmdir tmp

corepkgs/config.nix.in

@@ -0,0 +1,26 @@
+let
+  fromEnv = var: def:
+    let val = builtins.getEnv var; in
+    if val != "" then val else def;
+in rec {
+  perl = "@perl@";
+  shell = "@bash@";
+  coreutils = "@coreutils@";
+  bzip2 = "@bzip2@";
+  gzip = "@gzip@";
+  xz = "@xz@";
+  tar = "@tar@";
+  tarFlags = "@tarFlags@";
+  tr = "@tr@";
+  nixBinDir = fromEnv "NIX_BIN_DIR" "@bindir@";
+  nixPrefix = "@prefix@";
+
+  # 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/derivation.nix

@@ -0,0 +1,27 @@
+/* This is the implementation of the ‘derivation’ builtin function.
+   It's actually a wrapper around the ‘derivationStrict’ primop. */
+
+drvAttrs @ { outputs ? [ "out" ], ... }:
+
+let
+
+  strict = derivationStrict drvAttrs;
+
+  commonAttrs = drvAttrs // (builtins.listToAttrs outputsList) //
+    { all = map (x: x.value) outputsList;
+      inherit drvAttrs;
+    };
+
+  outputToAttrListElement = outputName:
+    { name = outputName;
+      value = commonAttrs // {
+        outPath = builtins.getAttr outputName strict;
+        drvPath = strict.drvPath;
+        type = "derivation";
+        inherit outputName;
+      };
+    };
+
+  outputsList = map outputToAttrListElement outputs;
+
+in (builtins.head outputsList).value

corepkgs/fetchurl.nix

@@ -0,0 +1,38 @@
+with import <nix/config.nix>;
+
+{ system ? builtins.currentSystem
+, url
+, outputHash ? ""
+, outputHashAlgo ? ""
+, md5 ? "", sha1 ? "", sha256 ? ""
+, executable ? false
+, unpack ? false
+, name ? baseNameOf (toString url)
+}:
+
+assert (outputHash != "" && outputHashAlgo != "")
+    || md5 != "" || sha1 != "" || sha256 != "";
+
+derivation {
+  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;
+  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;
+
+  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"
+  ];
+}

corepkgs/imported-drv-to-derivation.nix

@@ -0,0 +1,21 @@
+attrs @ { drvPath, outputs, name, ... }:
+
+let
+
+  commonAttrs = (builtins.listToAttrs outputsList) //
+    { all = map (x: x.value) outputsList;
+      inherit drvPath name;
+      type = "derivation";
+    };
+
+  outputToAttrListElement = outputName:
+    { name = outputName;
+      value = commonAttrs // {
+        outPath = builtins.getAttr outputName attrs;
+        inherit outputName;
+      };
+    };
+    
+  outputsList = map outputToAttrListElement outputs;
+    
+in (builtins.head outputsList).value

corepkgs/local.mk

@@ -0,0 +1,5 @@
+corepkgs_FILES = nar.nix buildenv.nix buildenv.pl 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

@@ -0,0 +1,48 @@
+with import <nix/config.nix>;
+
+let
+
+  builder = builtins.toFile "nar.sh"
+    ''
+      export PATH=${nixBinDir}:${coreutils}
+
+      if [ $compressionType = xz ]; then
+        ext=.xz
+        compressor="| ${xz} -7"
+      elif [ $compressionType = bzip2 ]; then
+        ext=.bz2
+        compressor="| ${bzip2}"
+      else
+        ext=
+        compressor=
+      fi
+
+      echo "packing ‘$storePath’..."
+      mkdir $out
+      dst=$out/tmp.nar$ext
+
+      set -o pipefail
+      eval "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;
+
+  # Remote machines may not have ${nixBinDir} or ${coreutils} in the same prefixes
+  preferLocalBuild = true;
+
+  inherit chrootDeps;
+}

corepkgs/nar/Makefile.am

@@ -1,11 +0,0 @@
-all-local: nar.sh
-
-install-exec-local:
-	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs
-	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs/nar
-	$(INSTALL_DATA) $(srcdir)/nar.nix $(DESTDIR)$(datadir)/nix/corepkgs/nar
-	$(INSTALL_PROGRAM) nar.sh $(DESTDIR)$(datadir)/nix/corepkgs/nar
-
-include ../../substitute.mk
-
-EXTRA_DIST = nar.nix nar.sh.in

corepkgs/nar/nar.nix

@@ -1,7 +0,0 @@
-{system, storePath, hashAlgo}: 
-
-derivation {
-  name = "nar";
-  builder = ./nar.sh;
-  inherit system storePath hashAlgo;
-}

corepkgs/nar/nar.sh.in

@@ -1,12 +0,0 @@
-#! @shell@ -e
-
-echo "packing $storePath into $out..."
-@coreutils@/mkdir $out
-dst=$out/tmp.nar.bz2
-@bindir@/nix-store --dump "$storePath" > tmp
-
-@bzip2@ < tmp > $dst
-
-@bindir@/nix-hash --flat --type $hashAlgo --base32 $dst > $out/narbz2-hash
-
-@coreutils@/mv $out/tmp.nar.bz2 $out/$(@coreutils@/cat $out/narbz2-hash).nar.bz2

corepkgs/unpack-channel.nix

@@ -0,0 +1,41 @@
+with import <nix/config.nix>;
+
+let
+
+  builder = builtins.toFile "unpack-channel.sh"
+    ''
+      mkdir $out
+      cd $out
+      xzpat="\.xz\$"
+      gzpat="\.gz\$"
+      if [[ "$src" =~ $xzpat ]]; then
+        ${xz} -d < $src | ${tar} xf - ${tarFlags}
+      elif [[ "$src" =~ $gzpat ]]; then
+        ${gzip} -d < $src | ${tar} xf - ${tarFlags}
+      else
+        ${bzip2} -d < $src | ${tar} xf - ${tarFlags}
+      fi
+      mv * $out/$channelName
+      if [ -n "$binaryCacheURL" ]; then
+        mkdir $out/binary-caches
+        echo -n "$binaryCacheURL" > $out/binary-caches/$channelName
+      fi
+    '';
+
+in
+
+{ name, channelName, src, binaryCacheURL ? "" }:
+
+derivation {
+  system = builtins.currentSystem;
+  builder = shell;
+  args = [ "-e" builder ];
+  inherit name channelName src binaryCacheURL;
+
+  PATH = "${nixBinDir}:${coreutils}";
+
+  # No point in doing this remotely.
+  preferLocalBuild = true;
+
+  inherit chrootDeps;
+}

dev-shell

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+if [ -e tests/test-tmp ]; then
+    chmod -R u+w tests/test-tmp
+    rm -rf tests/test-tmp
+fi
+
+s=$(type -p nix-shell)
+exec $s release.nix -A tarball --command "
+    unset http_proxy
+    export NIX_REMOTE=$NIX_REMOTE
+    export NIX_PATH='$NIX_PATH'
+    export NIX_BUILD_SHELL=$(type -p bash)
+    export c=\$configureFlags
+    exec $s release.nix -A build.$(if [ $(uname -s) = Darwin ]; then echo x86_64-darwin; else echo x86_64-linux; fi) --exclude tarball --command '
+        configureFlags+=\" \$c --prefix=$(pwd)/inst --sysconfdir=$(pwd)/inst/etc\"
+        return
+    '" \
+    "$@"

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,103 +0,0 @@
-XMLLINT = $(xmllint) $(xmlflags)
-XSLTPROC = $(xsltproc) $(xmlflags) \
- --param section.autolabel 1 \
- --param section.label.includes.component.label 1 \
- --param html.stylesheet \'style.css\' \
- --param xref.with.number.and.title 1 \
- --param toc.section.depth 3 \
- --param admon.style \'\' \
- --param callout.graphics.extension \'.gif\' \
- --param contrib.inline.enabled 0
-
-dblatex_opts = \
- -P doc.collab.show=0 \
- -P latex.output.revhistory=0
-
-# Note: we use GIF for now, since the PNGs shipped with Docbook aren't
-# transparent.
-
-man1_MANS = nix-env.1 nix-build.1 nix-store.1 nix-instantiate.1 \
- nix-collect-garbage.1 nix-push.1 nix-pull.1 \
- nix-prefetch-url.1 nix-channel.1 \
- nix-install-package.1 nix-hash.1 nix-copy-closure.1
-
-man8_MANS = nix-worker.8
-
-FIGURES = figures/user-environments.png
-
-MANUAL_SRCS = manual.xml introduction.xml installation.xml \
- package-management.xml writing-nix-expressions.xml builtins.xml \
- build-farm.xml \
- $(man1_MANS:.1=.xml) $(man8_MANS:.8=.xml) \
- troubleshooting.xml bugs.xml opt-common.xml opt-common-syn.xml \
- env-common.xml quick-start.xml nix-lang-ref.xml glossary.xml \
- conf-file.xml release-notes.xml \
- style.css images
-
-# Note: RelaxNG validation requires xmllint >= 2.7.4.
-manual.is-valid: $(MANUAL_SRCS) version.txt
-	$(XMLLINT) --noout --nonet --xinclude --noxincludenode --relaxng $(docbookrng)/docbook.rng $<
-	touch $@
-
-version.txt:
-	echo -n $(VERSION) > version.txt
-
-man $(MANS): $(MANUAL_SRCS) manual.is-valid
-	$(XSLTPROC) --nonet --xinclude $(docbookxsl)/manpages/docbook.xsl manual.xml
-
-manual.html: $(MANUAL_SRCS) manual.is-valid images
-	$(XSLTPROC) --nonet --xinclude --output manual.html \
-	  $(docbookxsl)/html/docbook.xsl manual.xml
-
-manual.pdf: $(MANUAL_SRCS) manual.is-valid images
-	if test "$(dblatex)" != ""; then \
-		$(dblatex) $(dblatex_opts) manual.xml; \
-	else \
-		echo "Please install dblatex and rerun configure."; \
-		exit 1; \
-	fi
-
-
-NEWS_OPTS = \
- --stringparam generate.toc "article nop" \
- --stringparam section.autolabel.max.depth 0 \
- --stringparam header.rule 0
-
-NEWS.html: release-notes.xml
-	$(XSLTPROC) --nonet --xinclude --output $@ $(NEWS_OPTS) \
-	  $(docbookxsl)/html/docbook.xsl release-notes.xml
-
-NEWS.txt: release-notes.xml
-	$(XSLTPROC) --nonet --xinclude quote-literals.xsl release-notes.xml | \
-	  $(XSLTPROC) --nonet --output $@.tmp.html $(NEWS_OPTS) \
-	  $(docbookxsl)/html/docbook.xsl -
-	LANG=en_US $(w3m) -dump $@.tmp.html > $@
-	rm $@.tmp.html
-
-
-all-local: manual.html NEWS.html NEWS.txt
-
-install-data-local: manual.html
-	$(INSTALL) -d $(DESTDIR)$(docdir)/manual
-	$(INSTALL_DATA) manual.html $(DESTDIR)$(docdir)/manual
-	ln -sf manual.html $(DESTDIR)$(docdir)/manual/index.html
-	$(INSTALL_DATA) style.css $(DESTDIR)$(docdir)/manual
-	cp -r images $(DESTDIR)$(docdir)/manual/images
-	$(INSTALL) -d $(DESTDIR)$(docdir)/manual/figures
-	$(INSTALL_DATA) $(FIGURES) $(DESTDIR)$(docdir)/manual/figures
-	$(INSTALL) -d $(DESTDIR)$(docdir)/release-notes
-	$(INSTALL_DATA) NEWS.html $(DESTDIR)$(docdir)/release-notes/index.html
-	$(INSTALL_DATA) style.css $(DESTDIR)$(docdir)/release-notes/
-
-images:
-	mkdir images
-#	cp $(docbookxsl)/images/*.gif images
-	mkdir images/callouts
-	cp $(docbookxsl)/images/callouts/*.gif images/callouts
-	chmod -R +w images
-
-KEEP = manual.html manual.is-valid version.txt $(MANS) NEWS.html NEWS.txt
-
-EXTRA_DIST = $(MANUAL_SRCS) $(FIGURES) $(KEEP)
-
-DISTCLEANFILES = $(KEEP)

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

@@ -0,0 +1,115 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id='chap-distributed-builds'>
+
+<title>Distributed Builds</title>
+
+<para>Nix supports distributed builds, where a local Nix installation can
+forward Nix builds to other machines over the network.  This allows
+multiple builds to be performed in parallel (thus improving
+performance) and allows Nix to perform multi-platform builds in a
+semi-transparent way.  For instance, if you perform a build for a
+<literal>powerpc-darwin</literal> on an <literal>i686-linux</literal>
+machine, Nix can automatically forward the build to a
+<literal>powerpc-darwin</literal> machine, if available.</para>
+
+<para>You can enable distributed builds by setting the environment
+variable <envar>NIX_BUILD_HOOK</envar> to point to a program that Nix
+will call whenever it wants to build a derivation.  The build hook
+(typically a shell or Perl script) can decline the build, in which Nix
+will perform it in the usual way if possible, or it can accept it, in
+which case it is responsible for somehow getting the inputs of the
+build to another machine, doing the build there, and getting the
+results back.  The details of the build hook protocol are described in
+the documentation of the <link
+linkend="envar-build-hook"><envar>NIX_BUILD_HOOK</envar>
+variable</link>.</para>
+
+<example xml:id='ex-remote-systems'><title>Remote machine configuration:
+<filename>remote-systems.conf</filename></title>
+<programlisting>
+nix@mcflurry.labs.cs.uu.nl  powerpc-darwin  /home/nix/.ssh/id_quarterpounder_auto  2
+nix@scratchy.labs.cs.uu.nl  i686-linux      /home/nix/.ssh/id_scratchy_auto        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
+</programlisting>
+</example>
+
+<para>Nix ships with a build hook that should be suitable for most
+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>.
+You should also define a list of available build machines and point
+the environment variable <envar>NIX_REMOTE_SYSTEMS</envar> to it.  An
+example configuration is shown in <xref linkend='ex-remote-systems'
+/>.  Each line in the file specifies a machine, with the following
+bits of information:
+
+<orderedlist>
+
+  <listitem><para>The name of the remote machine, with optionally the
+  user under which the remote build should be performed.  This is
+  actually passed as an argument to <command>ssh</command>, so it can
+  be an alias defined in your
+  <filename>~/.ssh/config</filename>.</para></listitem>
+
+  <listitem><para>A comma-separated list of Nix platform type
+  identifiers, such as <literal>powerpc-darwin</literal>.  It is
+  possible for a machine to support multiple platform types, e.g.,
+  <literal>i686-linux,x86_64-linux</literal>.</para></listitem>
+
+  <listitem><para>The SSH private key to be used to log in to the
+  remote machine.  Since builds should be non-interactive, this key
+  should not have a passphrase!</para></listitem>
+
+  <listitem><para>The maximum number of builds that
+  <filename>build-remote.pl</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>
+
+  <listitem><para>The “speed factor”, indicating the relative speed of
+  the machine.  If there are multiple machines of the right type, Nix
+  will prefer the fastest, taking load into account.</para></listitem>
+
+  <listitem><para>A comma-separated list of <emphasis>supported
+  features</emphasis>.  If a derivation has the
+  <varname>requiredSystemFeatures</varname> attribute, then
+  <filename>build-remote.pl</filename> will only perform the
+  derivation on a machine that has the specified features.  For
+  instance, the attribute
+
+<programlisting>
+requiredSystemFeatures = [ "kvm" ];
+</programlisting>
+
+  will cause the build to be performed on a machine that has the
+  <literal>kvm</literal> feature (i.e., <literal>scratchy</literal> in
+  the example above).</para></listitem>
+
+  <listitem><para>A comma-separated list of <emphasis>mandatory
+  features</emphasis>.  A machine will only be used to build a
+  derivation if all of the machine’s mandatory features appear in the
+  derivation’s <varname>requiredSystemFeatures</varname> attribute.
+  Thus, in the example, the machine <literal>poochie</literal> will
+  only do derivations that have
+  <varname>requiredSystemFeatures</varname> set to <literal>["kvm"
+  "perf"]</literal> or <literal>["perf"]</literal>.</para></listitem>
+
+</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>
+
+</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/build-farm.xml

@@ -1,137 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id='chap-build-farm'>
-
-<title>Setting up a Build Farm</title>
-
-
-<para>This chapter provides some sketchy information on how to set up
-a Nix-based build farm.  Nix is particularly suited as a basis for a
-build farm, since:
-
-<itemizedlist>
-
-  <listitem><para>Nix supports distributed builds: a local Nix
-  installation can forward Nix builds to other machines over the
-  network.  This allows multiple builds to be performed in parallel
-  (thus improving performance), but more in importantly, it allows Nix
-  to perform multi-platform builds in a semi-transparent way.  For
-  instance, if you perform a build for a
-  <literal>powerpc-darwin</literal> on an
-  <literal>i686-linux</literal> machine, Nix can automatically forward
-  the build to a <literal>powerpc-darwin</literal> machine, if
-  available.</para></listitem>
-
-  <listitem><para>The Nix expression language is ideal for describing
-  build jobs, plus all their dependencies.  For instance, if your
-  package has some dependency, you don't have to manually install it
-  on all the machines in the build farm; they will be built
-  automatically.</para></listitem>
-
-  <listitem><para>Proper release management requires that builds (if
-  deployed) are traceable: it should be possible to figure out from
-  exactly what sources they were built, in what configuration, etc.;
-  and it should be possible to reproduce the build, if necessary.  Nix
-  makes this possible since Nix's hashing scheme uniquely identifies
-  builds, and Nix expressions are self-contained.</para></listitem>
-
-  <listitem><para>Nix will only rebuild things that have actually
-  changed.  For instance, if the sources of a package haven't changed
-  between runs of the build farm, the package won't be rebuilt (unless
-  it was garbage-collected).  Also, dependencies typically don't
-  change very often, so they only need to be built
-  once.</para></listitem>
-
-  <listitem><para>The results of a Nix build farm can be made
-  available through a channel, so successful builds can be deployed to
-  users immediately.</para></listitem>
-
-</itemizedlist>
-
-</para>
-
-
-<section><title>Overview</title>
-
-<para>TODO</para>
-
-<para>The sources of the Nix build farm are at <link
-xlink:href='https://svn.nixos.org/repos/nix/release/trunk'/>.</para>
-
-</section>
-
-
-<section xml:id='sec-distributed-builds'><title>Setting up distributed builds</title>
-
-<para>You can enable distributed builds by setting the environment
-variable <envar>NIX_BUILD_HOOK</envar> to point to a program that Nix
-will call whenever it wants to build a derivation.  The build hook
-(typically a shell or Perl script) can decline the build, in which Nix
-will perform it in the usual way if possible, or it can accept it, in
-which case it is responsible for somehow getting the inputs of the
-build to another machine, doing the build there, and getting the
-results back.  The details of the build hook protocol are described in
-the documentation of the <link
-linkend="envar-build-hook"><envar>NIX_BUILD_HOOK</envar>
-variable</link>.</para>
-
-<example xml:id='ex-remote-systems'><title>Remote machine configuration:
-<filename>remote-systems.conf</filename></title>
-<programlisting>
-nix@mcflurry.labs.cs.uu.nl  powerpc-darwin  /home/nix/.ssh/id_quarterpounder_auto  2
-nix@scratchy.labs.cs.uu.nl  i686-linux      /home/nix/.ssh/id_scratchy_auto        1
-</programlisting>
-</example>
-
-<para>An example build hook can be found in the Nix build farm
-sources: <link
-xlink:href='https://svn.nixos.org/repos/nix/release/trunk/common/distributed/build-remote.pl'
-/>.  It should be suitable for most purposes, with maybe some minor
-adjustments.  It uses <command>ssh</command> and
-<command>rsync</command> to copy the build inputs and outputs and
-perform the remote build.  You should define a list of available build
-machines and set the environment variable
-<envar>REMOTE_SYSTEMS</envar> to point to it.  An example
-configuration is shown in <xref linkend='ex-remote-systems' />.  Each
-line in the file specifies a machine, with the following bits of
-information:
-
-<orderedlist>
-  
-  <listitem><para>The name of the remote machine, with optionally the
-  user under which the remote build should be performed.  This is
-  actually passed as an argument to <command>ssh</command>, so it can
-  be an alias defined in your
-  <filename>~/.ssh/config</filename>.</para></listitem>
-
-  <listitem><para>The Nix platform type identifier, such as
-  <literal>powerpc-darwin</literal>.</para></listitem>
-
-  <listitem><para>The SSH private key to be used to log in to the
-  remote machine.  Since builds should be non-interactive, this key
-  should not have a passphrase!</para></listitem>
-
-  <listitem><para>The maximum <quote>load</quote> of the remote
-  machine.  This is just the maximum number of jobs that
-  <filename>build-remote.pl</filename> will execute in parallel on the
-  machine.  Typically this should be equal to the number of
-  CPUs.</para></listitem>
-
-</orderedlist>
-
-You should also set up the environment variable
-<envar>CURRENT_LOAD</envar> to point at a file that
-<filename>build-remote.pl</filename> uses to remember how many jobs it
-is currently executing remotely.  It doesn't look at the actual load
-on the remote machine, so if you have multiple instances of Nix
-running, they should use the same <envar>CURRENT_LOAD</envar>
-file<footnote><para>Although there are probably some race conditions
-in the script right now.</para></footnote>.  Maybe in the future
-<filename>build-remote.pl</filename> will look at the actual remote
-load.  The load file should exist, so you should just create it as an
-empty file initially.</para>
-  
-</section>
-
-
-</chapter>

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,639 @@
+<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 save 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 an Athlon 64
+    X2).  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-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 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-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 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-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 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-build-max-log-size"><term><literal>build-max-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>build-use-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-build-sandbox-paths'><literal>build-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 Mac OS X. 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-build-sandbox-paths">
+    <term><literal>build-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.</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-build-extra-sandbox-paths">
+    <term><literal>build-extra-sandbox-paths</literal></term>
+
+    <listitem><para>A list of additional paths appended to
+    <option>build-sandbox-paths</option>. Useful if you want to extend
+    its default value.</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-failure</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>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-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.  Unprivileged 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>extra-binary-caches</literal></term>
+
+    <listitem><para>Additional binary caches appended to those
+    specified in <option>binary-caches</option> and
+    <option>binary-caches-files</option>.  When used by unprivileged
+    users, untrusted binary caches (i.e. those not listed in
+    <option>trusted-binary-caches</option>) are silently
+    ignored.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>signed-binary-caches</literal></term>
+
+    <listitem><para>If set to <literal>*</literal>, Nix will only
+    download binaries if they are signed using one of the keys listed
+    in <option>binary-cache-public-keys</option>.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>binary-cache-public-keys</literal></term>
+
+    <listitem><para>A whitespace-separated list of public keys
+    corresponding to the secret keys trusted to sign binary
+    caches. For example:
+    <literal>cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
+    hydra.nixos.org-1:CNHJZBh9K4tP3EKF6FkkgeVYsS3ohTl+oS0Qa8bezVs=</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
+    25.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>verify-https-binary-caches</literal></term>
+
+    <listitem><para>Whether HTTPS binary caches are required to have a
+    certificate that can be verified. Defaults to
+    <literal>true</literal>.</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>, 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-log-servers"><term><literal>log-servers</literal></term>
+
+    <listitem>
+
+      <para>A list of URL prefixes (such as
+      <literal>http://hydra.nixos.org/log</literal>) from which
+      <command>nix-store -l</command> will try to fetch build logs if
+      they’re not available locally.</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>The users listed here have the ability to
+      compromise the security of a multi-user Nix store. For instance,
+      they could install Trojan horses subsequently executed by other
+      users. So you should consider carefully whether to add users to
+      this list.</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). The default is
+      <literal>false</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>build-sandbox-paths</literal>.</para>
+
+          </listitem>
+
+        </varlistentry>
+      </variablelist>
+    </listitem>
+
+  </varlistentry>
+
+
+  <varlistentry xml:id="conf-build-repeat"><term><literal>build-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>
+
+
+</variablelist>
+
+</para>
+
+</refsection>
+
+</refentry>

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

@@ -1,15 +1,63 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="sec-common-env">
+<chapter xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-common-env">
 
-<title>Common environment variables</title>
+<title>Common Environment Variables</title>
 
 
 <para>Most Nix commands interpret the following environment variables:</para>
 
-<variablelist>
+<variablelist xml:id="env-common">
+
+
+<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>
@@ -31,7 +79,7 @@
   you’re better off using <literal>bind</literal> mount points, e.g.,
 
   <screen>
-$ mkdir /nix   
+$ mkdir /nix
 $ mount -o bind /mnt/otherdisk/nix /nix</screen>
 
   Consult the <citerefentry><refentrytitle>mount</refentrytitle>
@@ -46,7 +94,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
 
   <listitem><para>Overrides the location of the Nix store (default
   <filename><replaceable>prefix</replaceable>/store</filename>).</para></listitem>
-  
+
 </varlistentry>
 
 
@@ -55,7 +103,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
   <listitem><para>Overrides the location of the Nix static data
   directory (default
   <filename><replaceable>prefix</replaceable>/share</filename>).</para></listitem>
-  
+
 </varlistentry>
 
 
@@ -63,7 +111,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
 
   <listitem><para>Overrides the location of the Nix log directory
   (default <filename><replaceable>prefix</replaceable>/log/nix</filename>).</para></listitem>
-  
+
 </varlistentry>
 
 
@@ -71,7 +119,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
 
   <listitem><para>Overrides the location of the Nix state directory
   (default <filename><replaceable>prefix</replaceable>/var/nix</filename>).</para></listitem>
-  
+
 </varlistentry>
 
 
@@ -80,7 +128,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
   <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>
 
 
@@ -89,18 +137,9 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
   <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>
 
@@ -108,7 +147,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
   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>
 
 
@@ -119,9 +158,13 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
   <para>Specifies the location of the <emphasis>build hook</emphasis>,
   which is a program (typically some script) that Nix will call
   whenever it wants to build a derivation.  This is used to implement
-  distributed builds (see <xref linkend="sec-distributed-builds"
-  />).  The protocol by which the calling Nix process and the build
-  hook communicate is as follows.</para>
+  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:
@@ -131,7 +174,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
     <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>.
+    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>
 
@@ -202,7 +245,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
       store derivation itself).</para></listitem>
 
     </varlistentry>
-  
+
     <varlistentry><term><filename>outputs</filename></term>
 
       <listitem><para>The set of store paths that are outputs of the
@@ -216,7 +259,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
 
       <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
+      - -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>
@@ -233,6 +276,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
   <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>
 
@@ -244,30 +288,27 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
 
   <listitem><para>This variable should be set to
   <literal>daemon</literal> if you want to use the Nix daemon to
-  executed Nix operations, which is necessary in <link
+  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.
-  See <xref linkend="sec-sharing-packages" /> for details.  Each path
-  should be the <filename>/nix</filename> directory of a remote Nix
-  installation (i.e., not the <filename>/nix/store</filename>
-  directory).  The paths are subject to globbing, so you can set it so
-  something like <literal>/var/run/nix/remote-stores/*/nix</literal>
-  and mount multiple remote filesystems in
-  <literal>/var/run/nix/remote-stores</literal>.</para>
+<varlistentry><term><envar>NIX_SHOW_STATS</envar></term>
 
-  <para>Note that if you’re building through the <link
-  linkend="sec-nix-worker">Nix daemon</link>, the only setting for
-  this variable that matters is the one that the
-  <command>nix-worker</command> process uses.  So if you want to
-  change it, you have to restart the daemon.</para></listitem>
+  <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>
 
@@ -282,8 +323,8 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
 
 </varlistentry>
 
-    
+
 </variablelist>
 
 
-</section>
+</chapter>

doc/manual/command-ref/files.xml

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

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

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

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

@@ -1,13 +1,14 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-build">
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-nix-build">
 
 <refmeta>
   <refentrytitle>nix-build</refentrytitle>
   <manvolnum>1</manvolnum>
   <refmiscinfo class="source">Nix</refmiscinfo>
-  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
 </refmeta>
 
 <refnamediv>
@@ -28,8 +29,8 @@
       </group>
       <replaceable>attrPath</replaceable>
     </arg>
+    <arg><option>--drv-link</option> <replaceable>drvlink</replaceable></arg>
     <arg><option>--add-drv-link</option></arg>
-    <arg><option>--drv-link </option><replaceable>drvlink</replaceable></arg>
     <arg><option>--no-out-link</option></arg>
     <arg>
       <group choice='req'>
@@ -57,6 +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,36 +83,35 @@ or renamed.  So don’t rename the symlink.</para></warning>
 
 <refsection><title>Options</title>
 
-<para>See also <xref linkend="sec-common-options" />.  All options not
-listed here are passed to <command>nix-store --realise</command>,
-except for <option>--arg</option> and <option>--attr</option> /
-<option>-A</option> which are passed to
-<command>nix-instantiate</command>.</para>
+<para>All options not listed here are passed to <command>nix-store
+--realise</command>, except for <option>--arg</option> and
+<option>--attr</option> / <option>-A</option> which are passed to
+<command>nix-instantiate</command>.  <phrase condition="manual">See
+also <xref linkend="sec-common-options" />.</phrase></para>
 
 <variablelist>
 
-  <varlistentry><term><option>--add-drv-link</option></term>
-  
-    <listitem><para>Add a symlink in the current directory to the
-    store derivation produced by <command>nix-instantiate</command>.
-    The symlink is called <filename>derivation</filename> (which is
-    numbered in the case of multiple derivations).  The derivation is
+  <varlistentry><term><option>--drv-link</option> <replaceable>drvlink</replaceable></term>
+
+    <listitem><para>Add a symlink named
+    <replaceable>drvlink</replaceable> to the store derivation
+    produced by <command>nix-instantiate</command>.  The derivation is
     a root of the garbage collector until the symlink is deleted or
-    renamed.</para></listitem>
-    
+    renamed.  If there are multiple derivations, numbers are suffixed
+    to <replaceable>drvlink</replaceable> to distinguish between
+    them.</para></listitem>
+
   </varlistentry>
 
-  <varlistentry><term><option>--drv-link</option> <replaceable>drvlink</replaceable></term>
-  
-    <listitem><para>Change the name of the symlink to the derivation
-    created when <option>--add-drv-link</option> is used from
-    <filename>derivation</filename> to
-    <replaceable>drvlink</replaceable>.</para></listitem>
+  <varlistentry><term><option>--add-drv-link</option></term>
+
+    <listitem><para>Shorthand for <option>--drv-link</option>
+    <filename>./derivation</filename>.</para></listitem>
 
   </varlistentry>
 
   <varlistentry><term><option>--no-out-link</option></term>
-  
+
     <listitem><para>Do not create a symlink to the output path.  Note
     that as a result the output does not become a root of the garbage
     collector, and so might be deleted by <command>nix-store
@@ -114,23 +121,28 @@ except for <option>--arg</option> and <option>--attr</option> /
 
   <varlistentry xml:id='opt-out-link'><term><option>--out-link</option> /
   <option>-o</option> <replaceable>outlink</replaceable></term>
-  
+
     <listitem><para>Change the name of the symlink to the output path
-    created unless <option>--no-out-link</option> is used from
-    <filename>result</filename> to
+    created from <filename>result</filename> to
     <replaceable>outlink</replaceable>.</para></listitem>
 
   </varlistentry>
 
 </variablelist>
 
+<para>The following common options are supported:</para>
+
+<variablelist condition="manpage">
+  <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" />
+</variablelist>
+
 </refsection>
 
 
 <refsection><title>Examples</title>
 
 <screen>
-$ nix-build pkgs/top-level/all-packages.nix -A firefox
+$ nix-build '&lt;nixpkgs>' -A firefox
 store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv
 /nix/store/d18hyl92g30l...-firefox-1.5.0.7
 
@@ -140,6 +152,54 @@ lrwxrwxrwx  <replaceable>...</replaceable>  result -> /nix/store/d18hyl92g30l...
 $ ls ./result/bin/
 firefox  firefox-config</screen>
 
+<para>If a derivation has multiple outputs,
+<command>nix-build</command> will build the default (first) output.
+You can also build all outputs:
+<screen>
+$ nix-build '&lt;nixpkgs>' -A openssl.all
+</screen>
+This will create a symlink for each output named
+<filename>result-<replaceable>outputname</replaceable></filename>.
+The suffix is omitted if the output name is <literal>out</literal>.
+So if <literal>openssl</literal> has outputs <literal>out</literal>,
+<literal>bin</literal> and <literal>man</literal>,
+<command>nix-build</command> will create symlinks
+<literal>result</literal>, <literal>result-bin</literal> and
+<literal>result-man</literal>.  It’s also possible to build a specific
+output:
+<screen>
+$ nix-build '&lt;nixpkgs>' -A openssl.man
+</screen>
+This will create a symlink <literal>result-man</literal>.</para>
+
+<para>Build a Nix expression given on the command line:
+
+<screen>
+$ nix-build -E 'with import &lt;nixpkgs> { }; runCommand "foo" { } "echo bar > $out"'
+$ cat ./result
+bar
+</screen>
+
+</para>
+
+<para>Build the GNU Hello package from the latest revision of the
+master branch of Nixpkgs:
+
+<screen>
+$ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello
+</screen>
+
+</para>
+
+</refsection>
+
+
+<refsection condition="manpage"><title>Environment variables</title>
+
+<variablelist>
+  <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" />
+</variablelist>
+
 </refsection>
 
 

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

@@ -0,0 +1,204 @@
+<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), makes them the
+    default for <command>nix-env</command> operations (by symlinking
+    them from the directory <filename>~/.nix-defexpr</filename>), and
+    performs a <command>nix-pull</command> on the manifests of all
+    channels to make pre-built binaries available.</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. Binary caches can
+    be created and maintained using
+    <command>nix-push</command>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><filename>MANIFEST.bz2</filename></term>
+
+    <listitem><para>(Deprecated in favour of binary caches.) A
+    manifest as created by <command>nix-push</command>. Only used if
+    <filename>binary-cache-url</filename> is not present or if the
+    <filename>nix.conf</filename> option
+    <option>force-manifest</option> is set.</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,15 @@
     <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>
 
@@ -34,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>
@@ -24,8 +24,15 @@
     </group>
     <arg><option>--sign</option></arg>
     <arg><option>--gzip</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>
+    <arg><option>-v</option></arg>
     <arg choice='plain'>
-      <arg><replaceable>user@</replaceable></arg><replaceable>machine</replaceable>
+      <replaceable>user@</replaceable><replaceable>machine</replaceable>
     </arg>
     <arg choice='plain'><replaceable>paths</replaceable></arg>
   </cmdsynopsis>
@@ -36,7 +43,7 @@
 
 <para><command>nix-copy-closure</command> gives you an easy and
 efficient way to exchange software between machines.  Given one or
-more Nix store paths <replaceable>paths</replaceable> on the local
+more Nix store <replaceable>paths</replaceable> on the local
 machine, <command>nix-copy-closure</command> computes the closure of
 those paths (i.e. all their dependencies in the Nix store), and copies
 all paths in the closure to the remote machine via the
@@ -61,7 +68,7 @@ those paths.  If this bothers you, use
 <refsection><title>Options</title>
 
 <variablelist>
-  
+
   <varlistentry><term><option>--to</option></term>
 
     <listitem><para>Copy the closure of
@@ -84,22 +91,57 @@ those paths.  If this bothers you, use
 
     <listitem><para>Let the sending machine cryptographically sign the
     dump of each path with the key in
-    <filename>/nix/etc/nix/signing-key.sec</filename>.  If the user on
-    the target machine does not have direct access to the Nix store
-    (i.e., if the target machine has a multi-user Nix installation),
-    then the target machine will check the dump against
-    <filename>/nix/etc/nix/signing-key.pub</filename> before unpacking
-    it in its Nix store.  This allows secure sharing of store paths
-    between untrusted users on two machines, provided that there is a
-    trust relation between the Nix installations on both machines
-    (namely, they have matching public/secret keys).</para></listitem>
+    <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>
 
   </varlistentry>
 
   <varlistentry><term><option>--gzip</option></term>
 
-    <listitem><para>Compress the dump of each path with
-    <command>gzip</command> before sending it.</para></listitem>
+    <listitem><para>Enable compression of the SSH
+    connection.</para></listitem>
+
+  </varlistentry>
+
+  <!--
+  <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>
+
+    <listitem><para>Also copy the outputs of store derivations
+    included in the closure.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--use-substitutes</option> / <option>-s</option></term>
+
+    <listitem><para>Attempt to download missing paths on the target
+    machine using Nix’s substitute mechanism.  Any paths that cannot
+    be substituted on the target are still copied normally from the
+    source.  This is useful, for instance, if the connection between
+    the source and target machine is slow, but the connection between
+    the target machine and <literal>nixos.org</literal> (the default
+    binary cache server) is fast.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>-v</option></term>
+
+    <listitem><para>Show verbose output.</para></listitem>
 
   </varlistentry>
 
@@ -118,7 +160,7 @@ those paths.  If this bothers you, use
     <command>ssh</command> on the command line.</para></listitem>
 
   </varlistentry>
-  
+
 </variablelist>
 
 </refsection>

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

@@ -1,24 +1,24 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-worker">
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-nix-daemon">
 
 <refmeta>
-  <refentrytitle>nix-worker</refentrytitle>
+  <refentrytitle>nix-daemon</refentrytitle>
   <manvolnum>8</manvolnum>
   <refmiscinfo class="source">Nix</refmiscinfo>
-  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
 </refmeta>
 
 <refnamediv>
-  <refname>nix-worker</refname>
+  <refname>nix-daemon</refname>
   <refpurpose>Nix multi-user support daemon</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
   <cmdsynopsis>
-    <command>nix-worker</command>
-    <arg choice="plain"><option>--daemon</option></arg>
+    <command>nix-daemon</command>
   </cmdsynopsis>
 </refsynopsisdiv>
 

doc/manual/command-ref/nix-generate-patches.xml

@@ -0,0 +1,44 @@
+<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-generate-patches">
+
+<refmeta>
+  <refentrytitle>nix-generate-patches</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>nix-generate-patches</refname>
+  <refpurpose>generates binary patches between NAR files</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-generate-patches</command>
+    <arg choice='plain'><replaceable>NAR-DIR</replaceable></arg>
+	<arg choice='plain'><replaceable>PATCH-DIR</replaceable></arg>
+	<arg choice='plain'><replaceable>PATCH-URI</replaceable></arg>
+	<arg choice='plain'><replaceable>OLD-MANIFEST</replaceable></arg>
+	<arg choice='plain'><replaceable>NEW-MANIFEST</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>The command <command>nix-generate-patches</command> generates
+binary patches between NAR files listed in OLD-MANIFEST and NEW-MANIFEST.
+The patches are written to the directory PATCH-DIR, and the prefix
+PATCH-URI is used to generate URIs for the patches.  The patches are
+added to NEW-MANIFEST.  All NARs are required to exist in NAR-DIR.
+Patches are generated between succeeding versions of packages with
+the same name.</para>
+
+</refsection>
+
+
+</refentry>

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>
@@ -91,8 +92,9 @@ cryptographic hash as <literal>nix-store --dump
 
   <varlistentry><term><option>--type</option> <replaceable>hashAlgo</replaceable></term>
 
-    <listitem><para>Specify a cryptographic hash, which can be one of
-    <literal>md5</literal>, <literal>sha1</literal>, and
+    <listitem><para>Use the specified cryptographic hash algorithm,
+    which can be one of <literal>md5</literal>,
+    <literal>sha1</literal>, and
     <literal>sha256</literal>.</para></listitem>
 
   </varlistentry>

doc/manual/command-ref/nix-install-package.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-install-package">
-  
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-nix-install-package">
+
 <refmeta>
   <refentrytitle>nix-install-package</refentrytitle>
   <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>
@@ -26,6 +27,7 @@
       </group>
       <replaceable>path</replaceable>
     </arg>
+    <arg><option>--set</option></arg>
     <sbr />
     <group choice='req'>
       <arg choice='req'>
@@ -45,8 +47,7 @@
 <para>The command <command>nix-install-package</command> interactively
 installs a Nix Package file (<filename>*.nixpkg</filename>), which is
 a small file that contains a store path to be installed along with the
-URL of a <link linkend="sec-nix-push"><command>nix-push</command>
-manifest</link>.  The Nix Package file is either
+URL of a binary cache.  The Nix Package file is either
 <replaceable>file</replaceable>, or automatically downloaded from
 <replaceable>url</replaceable> if the <option>--url</option> switch is
 used.</para>
@@ -74,7 +75,7 @@ to restart itself with <command>xterm</command>,
 <refsection><title>Options</title>
 
 <variablelist>
-  
+
   <varlistentry><term><option>--non-interactive</option></term>
 
     <listitem><para>Do not open a new terminal window and do not ask
@@ -90,6 +91,13 @@ to restart itself with <command>xterm</command>,
 
   </varlistentry>
 
+  <varlistentry><term><option>--set</option></term>
+
+    <listitem><para>Install the package as the profile so that the
+    profile contains exactly the contents of the package.</para></listitem>
+
+  </varlistentry>
+
 </variablelist>
 
 </refsection>
@@ -125,19 +133,19 @@ format:
 <screen>
 NIXPKG1 <replaceable>manifestURL</replaceable> <replaceable>name</replaceable> <replaceable>system</replaceable> <replaceable>drvPath</replaceable> <replaceable>outPath</replaceable></screen>
 
-The elemens are as follows:
+The elements are as follows:
 
 <variablelist>
 
   <varlistentry><term><literal>NIXPKG1</literal></term>
-  
+
     <listitem><para>The version of the Nix Package
     file.</para></listitem>
 
   </varlistentry>
 
   <varlistentry><term><replaceable>manifestURL</replaceable></term>
-  
+
     <listitem><para>The manifest to be pulled by
     <command>nix-pull</command>.  The manifest must contain
     <replaceable>outPath</replaceable>.</para></listitem>
@@ -145,21 +153,21 @@ The elemens are as follows:
   </varlistentry>
 
   <varlistentry><term><replaceable>name</replaceable></term>
-  
+
     <listitem><para>The symbolic name and version of the
     package.</para></listitem>
 
   </varlistentry>
 
   <varlistentry><term><replaceable>system</replaceable></term>
-  
+
     <listitem><para>The platform identifier of the platform for which
     this binary package is intended.</para></listitem>
 
   </varlistentry>
 
   <varlistentry><term><replaceable>drvPath</replaceable></term>
-  
+
     <listitem><para>The path in the Nix store of the derivation from
     which <replaceable>outPath</replaceable> was built.  Not currently
     used.</para></listitem>
@@ -167,17 +175,21 @@ The elemens are as follows:
   </varlistentry>
 
   <varlistentry><term><replaceable>outPath</replaceable></term>
-  
-    <listitem><para>The path in the Nix store of the package.  After
-    <command>nix-install-package</command> has obtained the manifest
-    from <replaceable>manifestURL</replaceable>, it performs a
-    <literal>nix-env -i</literal> <replaceable>outPath</replaceable>
-    to install the binary package.</para></listitem>
+
+    <listitem><para>The path in the Nix store of the
+    package.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><replaceable>binaryCacheURL</replaceable></term>
+
+    <listitem><para>The URL of a binary cache containing the closure
+    of <replaceable>outPath</replaceable>.</para></listitem>
 
   </varlistentry>
 
 </variablelist>
-  
+
 </para>
 
 <para>An example follows:

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,15 @@
 <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>--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,16 +38,14 @@
     </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>
-      </group>
-      <arg><option>--xml</option></arg>
-    </arg>
+    <group choice='req'>
+      <arg choice='plain'><option>--expr</option></arg>
+      <arg choice='plain'><option>-E</option></arg>
+    </group>
+    <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg>
+    <sbr/>
+    <command>nix-instantiate</command>
+    <arg choice='plain'><option>--find-file</option></arg>
     <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg>
   </cmdsynopsis>
 </refsynopsisdiv>
@@ -48,9 +55,10 @@
 
 <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>.  Each top-level expression should
-evaluate to a derivation, a list of derivations, or a set of
+Nix expressions.  It evaluates the Nix expressions in each of
+<replaceable>files</replaceable> (which defaults to
+<replaceable>./default.nix</replaceable>).  Each top-level expression
+should evaluate to a derivation, a list of derivations, or a set of
 derivations.  The paths of the resulting store derivations are printed
 on standard output.</para>
 
@@ -58,14 +66,8 @@ 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>See also <xref linkend="sec-common-options" /> for a list of
-common options.</para>
+<para condition="manual">See also <xref linkend="sec-common-options"
+/> for a list of common options.</para>
 
 </refsection>
 
@@ -83,27 +85,40 @@ common options.</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 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
+    <listitem><para>When used with <option>--parse</option> and
+    <option>--eval</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>
@@ -111,9 +126,18 @@ common options.</para>
 
   </varlistentry>
 
+  <varlistentry><term><option>--json</option></term>
+
+    <listitem><para>When used with <option>--parse</option> and
+    <option>--eval</option>, print the resulting expression as an
+    JSON representation of the abstract syntax tree rather than as an
+    ATerm.</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>
@@ -125,6 +149,21 @@ common options.</para>
 
   </varlistentry>
 
+  <varlistentry><term><option>--read-write-mode</option></term>
+
+    <listitem><para>When used with <option>--eval</option>, perform
+    evaluation in read/write mode so nix language features that
+    require it will still work (at the cost of needing to do
+    instantiation of every evaluated derivation).</para>
+
+    </listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+<variablelist condition="manpage">
+  <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" />
 </variablelist>
 
 </refsection>
@@ -149,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>
@@ -169,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>
@@ -198,4 +252,13 @@ $ echo 'rec { x = "foo"; y = x; }' | nix-instantiate --eval-only --xml --strict
 </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-prefetch-url.xml

@@ -0,0 +1,129 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-nix-prefetch-url">
+
+<refmeta>
+  <refentrytitle>nix-prefetch-url</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>nix-prefetch-url</refname>
+  <refpurpose>copy a file from a URL into the store and print its hash</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-prefetch-url</command>
+    <arg><option>--type</option> <replaceable>hashAlgo</replaceable></arg>
+    <arg><option>--print-path</option></arg>
+    <arg choice='plain'><replaceable>url</replaceable></arg>
+    <arg><replaceable>hash</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>The command <command>nix-prefetch-url</command> downloads the
+file referenced by the URL <replaceable>url</replaceable>, prints its
+cryptographic hash, and copies it into the Nix store.  The file name
+in the store is
+<filename><replaceable>hash</replaceable>-<replaceable>baseName</replaceable></filename>,
+where <replaceable>baseName</replaceable> is everything following the
+final slash in <replaceable>url</replaceable>.</para>
+
+<para>This command is just a convenience for Nix expression writers.
+Often a Nix expression fetches some source distribution from the
+network using the <literal>fetchurl</literal> expression contained in
+Nixpkgs.  However, <literal>fetchurl</literal> requires a
+cryptographic hash.  If you don't know the hash, you would have to
+download the file first, and then <literal>fetchurl</literal> would
+download it again when you build your Nix expression.  Since
+<literal>fetchurl</literal> uses the same name for the downloaded file
+as <command>nix-prefetch-url</command>, the redundant download can be
+avoided.</para>
+
+<para>If <replaceable>hash</replaceable> is specified, then a download
+is not performed if the Nix store already contains a file with the
+same hash and base name.  Otherwise, the file is downloaded, and an
+error if signaled if the actual hash of the file does not match the
+specified hash.</para>
+
+<para>This command prints the hash on standard output.  Additionally,
+if the option <option>--print-path</option> is used, the path of the
+downloaded file in the Nix store is also printed.</para>
+
+</refsection>
+
+
+<refsection><title>Options</title>
+
+<variablelist>
+
+  <varlistentry><term><option>--type</option> <replaceable>hashAlgo</replaceable></term>
+
+    <listitem><para>Use the specified cryptographic hash algorithm,
+    which can be one of <literal>md5</literal>,
+    <literal>sha1</literal>, and
+    <literal>sha256</literal>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--print-path</option></term>
+
+    <listitem><para>Print the store path of the downloaded file on
+    standard output.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--unpack</option></term>
+
+    <listitem><para>Unpack the archive (which must be a tarball or zip
+    file) and add the result to the Nix store. The resulting hash can
+    be used with functions such as Nixpkgs’s
+    <varname>fetchzip</varname> or
+    <varname>fetchFromGitHub</varname>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--name</option></term>
+
+    <listitem><para>Override the name of the file in the Nix store. By
+    default, this is
+    <literal><replaceable>hash</replaceable>-<replaceable>basename</replaceable></literal>,
+    where <replaceable>basename</replaceable> is the last component of
+    <replaceable>url</replaceable>. Overriding the name is necessary
+    when <replaceable>basename</replaceable> contains characters that
+    are not allowed in Nix store paths.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<screen>
+$ nix-prefetch-url ftp://ftp.gnu.org/pub/gnu/hello/hello-2.10.tar.gz
+0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
+
+$ nix-prefetch-url --print-path mirror://gnu/hello/hello-2.10.tar.gz
+0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
+/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz
+
+$ nix-prefetch-url --unpack --print-path https://github.com/NixOS/patchelf/archive/0.8.tar.gz
+079agjlv0hrv7fxnx9ngipx14gyncbkllxrp9cccnh3a50fxcmy7
+/nix/store/19zrmhm3m40xxaw81c8cqm6aljgrnwj2-0.8.tar.gz
+</screen>
+
+</refsection>
+
+
+</refentry>

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

@@ -1,18 +1,19 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink"
-          xmlns:xi="http://www.w3.org/2001/XInclude"
-          xml:id="sec-nix-pull">
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id="sec-nix-pull">
 
 <refmeta>
   <refentrytitle>nix-pull</refentrytitle>
   <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>
   <refname>nix-pull</refname>
-  <refpurpose>pull substitutes from a network cache</refpurpose>
+  <refpurpose>register availability of pre-built binaries (deprecated)</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
@@ -25,6 +26,9 @@
 
 <refsection><title>Description</title>
 
+<note><para>This command and the use of manifests is deprecated. It is
+better to use binary caches.</para></note>
+
 <para>The command <command>nix-pull</command> obtains a list of
 pre-built store paths from the URL <replaceable>url</replaceable>, and
 for each of these store paths, registers a substitute derivation that
@@ -42,7 +46,7 @@ with the files created by <replaceable>nix-push</replaceable>.</para>
 <refsection><title>Examples</title>
 
 <screen>
-$ nix-pull http://nix.cs.uu.nl/dist/nix/nixpkgs-0.5pre753/MANIFEST</screen>
+$ nix-pull https://nixos.org/releases/nixpkgs/nixpkgs-15.05pre54468.69858d7/MANIFEST</screen>
 
 </refsection>
 

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

@@ -0,0 +1,464 @@
+<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-push">
+
+<refmeta>
+  <refentrytitle>nix-push</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>nix-push</refname>
+  <refpurpose>generate a binary cache</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-push</command>
+    <arg choice='plain'><option>--dest</option> <replaceable>dest-dir</replaceable></arg>
+    <arg><option>--bzip2</option></arg>
+    <arg><option>--none</option></arg>
+    <arg><option>--force</option></arg>
+    <arg><option>--link</option></arg>
+    <arg><option>--manifest</option></arg>
+    <arg><option>--manifest-path</option> <replaceable>filename</replaceable></arg>
+    <arg><option>--url-prefix</option> <replaceable>url</replaceable></arg>
+    <arg><option>--key-file</option> <replaceable>path</replaceable></arg>
+    <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>The command <command>nix-push</command> produces a
+<emphasis>binary cache</emphasis>, a directory containing compressed
+Nix archives (NARs) plus some metadata of the closure of the specified
+store paths.  This directory can then be made available through a web
+server to other Nix installations, allowing them to skip building from
+source and instead download binaries from the cache
+automatically.</para>
+
+<para><command>nix-push</command> performs the following actions.
+
+<orderedlist>
+
+  <listitem><para>Each path in <replaceable>paths</replaceable> is
+  built (using <link
+  linkend='rsec-nix-store-realise'><command>nix-store
+  --realise</command></link>).</para></listitem>
+
+  <listitem><para>All paths in the closure of
+  <replaceable>paths</replaceable> are determined (using
+  <command>nix-store --query --requisites
+  --include-outputs</command>).  Note that since the
+  <option>--include-outputs</option> flag is used, if
+  <replaceable>paths</replaceable> includes a store derivation, you
+  get a combined source/binary distribution (e.g., source tarballs
+  will be included).</para></listitem>
+
+  <listitem><para>All store paths determined in the previous step are
+  packaged into a NAR (using <command>nix-store --dump</command>) and
+  compressed using <command>xz</command> or <command>bzip2</command>.
+  The resulting files have the extension <filename>.nar.xz</filename>
+  or <filename>.nar.bz2</filename>.  Also for each store path, Nix
+  generates a file with extension <filename>.narinfo</filename>
+  containing metadata such as the references, cryptographic hash and
+  size of each path.</para></listitem>
+
+  <listitem><para>Optionally, a single <emphasis>manifest</emphasis>
+  file is created that contains the same metadata as the
+  <filename>.narinfo</filename> files.  This is for compatibility with
+  Nix versions prior to 1.2 (see <command>nix-pull</command> for
+  details).</para></listitem>
+
+  <listitem><para>A file named <option>nix-cache-info</option> is
+  placed in the destination directory.  The existence of this file
+  marks the directory as a binary cache.</para></listitem>
+
+</orderedlist>
+
+</para>
+
+</refsection>
+
+
+<refsection><title>Options</title>
+
+<variablelist>
+
+  <varlistentry><term><option>--dest</option> <replaceable>dest-dir</replaceable></term>
+
+    <listitem><para>Set the destination directory to
+    <replaceable>dir</replaceable>, which is created if it does not
+    exist.  This flag is required.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--bzip2</option></term>
+
+    <listitem><para>Compress NARs using <command>bzip2</command>
+    instead of <command>xz</command>.  The latter compresses about 30%
+    better on typical archives, decompresses about twice as fast, but
+    compresses a lot slower and is not supported by Nix prior to
+    version 1.2.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--none</option></term>
+
+    <listitem><para>Do not compress NARs.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--force</option></term>
+
+    <listitem><para>Overwrite <filename>.narinfo</filename> files if
+    they already exist.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--link</option></term>
+
+    <listitem><para>By default, NARs are generated in the Nix store
+    and then copied to <replaceable>dest-dir</replaceable>.  If this
+    option is given, hard links are used instead.  This only works if
+    <replaceable>dest-dir</replaceable> is on the same filesystem as
+    the Nix store.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--manifest</option></term>
+
+    <listitem><para>Force the generation of a manifest suitable for
+    use by <command>nix-pull</command>.  The manifest is stored as
+    <filename><replaceable>dest-dir</replaceable>/MANIFEST</filename>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--manifest-path</option> <replaceable>filename</replaceable></term>
+
+    <listitem><para>Like <option>--manifest</option>, but store the
+    manifest in <replaceable>filename</replaceable>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--url-prefix</option> <replaceable>url</replaceable></term>
+
+    <listitem><para>Manifests are expected to contain the absolute
+    URLs of NARs.  For generating these URLs, the prefix
+    <replaceable>url</replaceable> is used.  It defaults to
+    <uri>file://<replaceable>dest-dir</replaceable></uri>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--key-file</option> <replaceable>path</replaceable></term>
+
+    <listitem><para>Sign the binary cache using the secret key stored
+    in <replaceable>path</replaceable>. This secret key must have been
+    created using <command
+    linkend="rsec-nix-store-generate-binary-cache-key">nix-store
+    --generate-binary-cache-key</command>. Users of this binary cache
+    should add the corresponding public key to the option
+    <option>binary-cache-public-keys</option> in
+    <filename>nix.conf</filename>.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<para>To add the closure of Thunderbird to a binary cache:
+
+<screen>
+$ nix-push --dest /tmp/cache $(nix-build -A thunderbird)
+</screen>
+
+Assuming that <filename>/tmp/cache</filename> is exported by a web
+server as <uri>http://example.org/cache</uri>, you can then use this
+cache on another machine to speed up the installation of Thunderbird:
+
+<screen>
+$ nix-build -A thunderbird --option binary-caches http://example.org/cache
+</screen>
+
+Alternatively, you could add <literal>binary-caches =
+http://example.org/cache</literal> to
+<filename>nix.conf</filename>.</para>
+
+<para>To also include build-time dependencies (such as source
+tarballs):
+
+<screen>
+$ nix-push --dest /tmp/cache $(nix-instantiate -A thunderbird)
+</screen>
+
+</para>
+
+<para>To generate a manifest suitable for <command>nix-pull</command>:
+
+<screen>
+$ nix-push --dest /tmp/cache $(nix-build -A thunderbird) --manifest
+</screen>
+
+On another machine you can then do:
+
+<screen>
+$ nix-pull http://example.org/cache
+</screen>
+
+to cause the binaries to be used by subsequent Nix operations.</para>
+
+<para>To generate a signed binary cache, you must first generate a key
+pair, in this example called <literal>cache.example.org-1</literal>,
+storing the secret key in <filename>./sk</filename> and the public key
+in <filename>./pk</filename>:
+
+<screen>
+$ nix-store --generate-binary-cache-key cache.example.org-1 sk pk
+
+$ cat sk
+cache.example.org-1:jcMRQYFo8pQKzTtimpQLIPeHkMYZjfhB24hGfwF+u9PuX8H8FO7q564+X3G/JDlqqIqGar3OXRRwS9N3Wh3vbw==
+
+$ cat pk
+cache.example.org-1:7l/B/BTu6ueuPl9xvyQ5aqiKhmq9zl0UcEvTd1od728=
+</screen>
+
+You can then generate a binary cache signed with the secret key:
+
+<screen>
+$ nix-push --dest /tmp/cache --key-file ./sk $(type -p firefox)
+</screen>
+
+Users who wish to verify the integrity of binaries downloaded from
+your cache would add the following to their
+<filename>nix.conf</filename>:
+
+<programlisting>
+binary-caches = http://cache.example.org
+signed-binary-caches = *
+binary-cache-public-keys = cache.example.org-1:7l/B/BTu6ueuPl9xvyQ5aqiKhmq9zl0UcEvTd1od728=
+</programlisting>
+
+Nix will then ignore any binary that has a missing, incorrect or
+unrecognised signature.</para>
+
+</refsection>
+
+
+<refsection><title>Binary cache format and operation</title>
+
+<para>A binary cache with URL <replaceable>url</replaceable> only
+denotes a valid binary cache if the file
+<uri><replaceable>url</replaceable>/nix-cache-info</uri> exists.  If
+this file does not exist (or cannot be downloaded), the cache is
+ignored.  If it does exist, it must be a text file containing cache
+properties.  Here’s an example:
+
+<screen>
+StoreDir: /nix/store
+WantMassQuery: 1
+Priority: 10
+</screen>
+
+The properties that are currently supported are:
+
+<variablelist>
+
+  <varlistentry><term><literal>StoreDir</literal></term>
+
+    <listitem><para>The path of the Nix store to which this binary
+    cache applies.  Binaries are not relocatable — a binary built for
+    <filename>/nix/store</filename> won’t generally work in
+    <filename>/home/alice/store</filename> — so to prevent binaries
+    from being used in a wrong store, a binary cache is only used if
+    its <literal>StoreDir</literal> matches the local Nix
+    configuration.  The default is
+    <filename>/nix/store</filename>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><literal>WantMassQuery</literal></term>
+
+    <listitem><para>Query operations such as <command>nix-env
+    -qas</command> can cause thousands of cache queries, and thus
+    thousands of HTTP requests, to determine which packages are
+    available in binary form.  While these requests are small, not
+    every server may appreciate a potential onslaught of queries.  If
+    <literal>WantMassQuery</literal> is set to <literal>0</literal>
+    (default), “mass queries” such as <command>nix-env -qas</command>
+    will skip this cache.  Thus a package may appear not to have a
+    binary substitute.  However, the binary will still be used when
+    you actually install the package.  If
+    <literal>WantMassQuery</literal> is set to <literal>1</literal>,
+    mass queries will use this cache.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><literal>Priority</literal></term>
+
+    <listitem><para>Each binary cache has a priority (defaulting to
+    50).  Binary caches are checked for binaries in order of ascending
+    priority; thus a higher number denotes a lower priority.  The
+    binary cache <uri>https://cache.nixos.org</uri> has priority
+    40.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</para>
+
+<para>Every time Nix needs to build some store path
+<replaceable>p</replaceable>, it will check each configured binary
+cache to see if it has a NAR file for <replaceable>p</replaceable>,
+until it finds one.  If no cache has a NAR, Nix will fall back to
+building the path from source (if applicable).  To see if a cache with
+URL <replaceable>url</replaceable> has a binary for
+<replaceable>p</replaceable>, Nix fetches
+<replaceable>url/h</replaceable>, where <replaceable>h</replaceable>
+is the hash part of <replaceable>p</replaceable>.  Thus, if we have a
+cache <uri>https://cache.nixos.org</uri> and we want to obtain the
+store path
+<screen>
+/nix/store/a8922c0h87iilxzzvwn2hmv8x210aqb9-glibc-2.7
+</screen>
+then Nix will attempt to fetch
+<screen>
+https://cache.nixos.org/a8922c0h87iilxzzvwn2hmv8x210aqb9.narinfo
+</screen>
+(Commands such as <command>nix-env -qas</command> will issue an HTTP
+HEAD request, since it only needs to know if the
+<filename>.narinfo</filename> file exists.)  The
+<filename>.narinfo</filename> file is a simple text file that looks
+like this:
+
+<screen>
+StorePath: /nix/store/a8922c0h87iilxzzvwn2hmv8x210aqb9-glibc-2.7
+URL: nar/0zzjpdz46mdn74v09m053yczlz4am038g8r74iy8w43gx8801h70.nar.bz2
+Compression: bzip2
+FileHash: sha256:0zzjpdz46mdn74v09m053yczlz4am038g8r74iy8w43gx8801h70
+FileSize: 24473768
+NarHash: sha256:0s491y1h9hxj5ghiizlxk7ax6jwbha00zwn7lpyd5xg5bhf60vzg
+NarSize: 109521136
+References: 2ma2k0ys8knh4an48n28vigcmc2z8773-linux-headers-2.6.23.16 ...
+Deriver: 7akyyc87ka32xwmqza9dvyg5pwx3j212-glibc-2.7.drv
+Sig: cache.example.org-1:WepnSp2UT0odDpR3NRjPVhJBHmdBgSBSTbHpdh4SCz92nGXwFY82bkPEmISoC0hGqBXDXEmB6y3Ohgna3mMgDg==
+</screen>
+
+The fields are as follows:
+
+<variablelist>
+
+  <varlistentry><term><literal>StorePath</literal></term>
+
+    <listitem><para>The full store path, including the name part
+    (e.g., <literal>glibc-2.7</literal>).  It must match the
+    requested store path.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><literal>URL</literal></term>
+
+    <listitem><para>The URL of the NAR, relative to the binary cache
+    URL.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><literal>Compression</literal></term>
+
+    <listitem><para>The compression method; either
+    <literal>xz</literal> or
+    <literal>bzip2</literal>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><literal>FileHash</literal></term>
+
+    <listitem><para>The SHA-256 hash of the compressed
+    NAR.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><literal>FileSize</literal></term>
+
+    <listitem><para>The size of the compressed NAR.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><literal>NarHash</literal></term>
+
+    <listitem><para>The SHA-256 hash of the uncompressed NAR.  This is
+    equal to the hash of the store path as returned by
+    <command>nix-store -q --hash
+    <replaceable>p</replaceable></command>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><literal>NarSize</literal></term>
+
+    <listitem><para>The size of the uncompressed NAR.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><literal>References</literal></term>
+
+    <listitem><para>The references of the store path, without the Nix
+    store prefix.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><literal>Deriver</literal></term>
+
+    <listitem><para>The deriver of the store path, without the Nix
+    store prefix.  This field is optional.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><literal>System</literal></term>
+
+    <listitem><para>The Nix platform type of this binary, if known.
+    This field is optional.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><literal>Sig</literal></term>
+
+    <listitem><para>A signature of the the form
+    <literal><replaceable>key-name</replaceable>:<replaceable>sig</replaceable></literal>,
+    where <replaceable>key-name</replaceable> is the symbolic name of
+    the key pair used to sign and verify the cache
+    (e.g. <literal>cache.example.org-1</literal>), and
+    <replaceable>sig</replaceable> is the actual signature, computed
+    over the <varname>StorePath</varname>, <varname>NarHash</varname>,
+    <varname>NarSize</varname> and <varname>References</varname>
+    fields using the <link
+    xlink:href="http://ed25519.cr.yp.to/">Ed25519 public-key signature
+    system</link>.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</para>
+
+<para>Thus, in our example, after recursively ensuring that the
+references exist (e.g.,
+<filename>/nix/store/2ma2k0ys8knh4an48n28vigcmc2z8773-linux-headers-2.6.23.16</filename>),
+Nix will fetch <screen>
+https://cache.nixos.org/nar/0zzjpdz46mdn74v09m053yczlz4am038g8r74iy8w43gx8801h70.nar.bz2
+</screen> and decompress and unpack it to
+<filename>/nix/store/a8922c0h87iilxzzvwn2hmv8x210aqb9-glibc-2.7</filename>.</para>
+
+</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'>
+      <group choice='plain'>
+        <group>
+          <arg choice='plain'><option>--packages</option></arg>
+          <arg choice='plain'><option>-p</option></arg>
+        </group>
+        <replaceable>packages</replaceable>
+      </group>
+      <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></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>#1 /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>
@@ -48,8 +49,9 @@ be performed.  These are documented below.</para>
 
 <para>This section lists the options that are common to all
 operations.  These options are allowed for every subcommand, though
-they may not always have an effect.  See also <xref
-linkend="sec-common-options" /> for a list of common options.</para>
+they may not always have an effect.  <phrase condition="manual">See
+also <xref linkend="sec-common-options" /> for a list of common
+options.</phrase></para>
 
 <variablelist>
 
@@ -57,8 +59,9 @@ linkend="sec-common-options" /> for a list of common options.</para>
 
     <listitem><para>Causes the result of a realisation
     (<option>--realise</option> and <option>--force-realise</option>)
-    to be registered as a root of the garbage collector (see <xref
-    linkend="ssec-gc-roots" />).  The root is stored in
+    to be registered as a root of the garbage collector<phrase
+    condition="manual"> (see <xref linkend="ssec-gc-roots"
+    />)</phrase>.  The root is stored in
     <replaceable>path</replaceable>, which must be inside a directory
     that is scanned for roots by the garbage collector (i.e.,
     typically in a subdirectory of
@@ -109,12 +112,16 @@ lrwxrwxrwx    1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r1134
     </listitem>
 
   </varlistentry>
-    
+
+</variablelist>
+
+<variablelist condition="manpage">
+  <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" />
 </variablelist>
 
 </refsection>
 
-  
+
 
 <!--######################################################################-->
 
@@ -135,7 +142,7 @@ lrwxrwxrwx    1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r1134
 </refsection>
 
 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--realise</option> essentially “builds”
 the specified store paths.  Realisation is a somewhat overloaded term:
 
@@ -158,7 +165,7 @@ the specified store paths.  Realisation is a somewhat overloaded term:
   exist in the file system).  If the path is already valid, we are
   done immediately.  Otherwise, the path and any missing paths in its
   closure may be produced through substitutes.  If there are no
-  (succesful) subsitutes, realisation fails.</para></listitem>
+  (successful) subsitutes, realisation fails.</para></listitem>
 
 </itemizedlist>
 
@@ -168,20 +175,55 @@ the specified store paths.  Realisation is a somewhat overloaded term:
 output.  (For non-derivations argument, the argument itself is
 printed.)</para>
 
-<para>If the <option>--dry-run</option> option is used, then
-<command>nix-store</command> will print on standard error a
-description of what packages would be built or downloaded, and then
-quit.</para>
+<para>The following flags are available:</para>
+
+<variablelist>
+
+  <varlistentry><term><option>--dry-run</option></term>
+
+    <listitem><para>Print on standard error a description of what
+    packages would be built or downloaded, without actually performing
+    the operation.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--ignore-unknown</option></term>
+
+    <listitem><para>If a non-derivation path does not have a
+    substitute, then silently ignore it.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--check</option></term>
+
+    <listitem><para>This option allows you to check whether a
+    derivation is deterministic. It rebuilds the specified derivation
+    and checks whether the result is bitwise-identical with the
+    existing outputs, printing an error if that’s not the case. The
+    outputs of the specified derivation must already exist. When used
+    with <option>-K</option>, if an output path is not identical to
+    the corresponding output from the previous build, the new output
+    path is left in
+    <filename>/nix/store/<replaceable>name</replaceable>-check.</filename></para>
+
+    <para>See also the <option>build-repeat</option> configuration
+    option, which repeats a derivation a number of times and prevents
+    its outputs from being registered as “valid” in the Nix store
+    unless they are identical.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
 
 </refsection>
-            
+
 
 <refsection><title>Examples</title>
 
 <para>This operation is typically used to build store derivations
 produced by <link
 linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>:
-    
+
 <screen>
 $ nix-store -r $(nix-instantiate ./test.nix)
 /nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1</screen>
@@ -189,12 +231,20 @@ $ 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 -r '&lt;nixpkgs>' -A hello --check -K
+</screen>
+
+</para>
+
 </refsection>
 
 
 </refsection>
 
-  
+
 
 <!--######################################################################-->
 
@@ -212,13 +262,12 @@ linkend="sec-nix-build"><command>nix-build</command></link> does.</para>
     <arg choice='plain'><option>--delete</option></arg>
   </group>
   <arg><option>--max-freed</option> <replaceable>bytes</replaceable></arg>
-  <arg><option>--max-links</option> <replaceable>nrlinks</replaceable></arg>
 </cmdsynopsis>
 
 </refsection>
 
 <refsection><title>Description</title>
-            
+
 <para>Without additional flags, the operation <option>--gc</option>
 performs a garbage collection on the Nix store.  That is, all paths in
 the Nix store not reachable via file system references from a set of
@@ -229,40 +278,40 @@ the Nix store not reachable via file system references from a set of
 <variablelist>
 
   <varlistentry><term><option>--print-roots</option></term>
-  
+
     <listitem><para>This operation prints on standard output the set
     of roots used by the garbage collector.  What constitutes a root
     is described in <xref linkend="ssec-gc-roots"
     />.</para></listitem>
-    
+
   </varlistentry>
 
   <varlistentry><term><option>--print-live</option></term>
-  
+
     <listitem><para>This operation prints on standard output the set
     of “live” store paths, which are all the store paths reachable
     from the roots.  Live paths should never be deleted, since that
     would break consistency — it would become possible that
     applications are installed that reference things that are no
     longer present in the store.</para></listitem>
-    
+
   </varlistentry>
 
   <varlistentry><term><option>--print-dead</option></term>
-  
+
     <listitem><para>This operation prints out on standard output the
     set of “dead” store paths, which is just the opposite of the set
     of live paths: any path in the store that is not live (with
     respect to the roots) is dead.</para></listitem>
-    
+
   </varlistentry>
 
   <varlistentry><term><option>--delete</option></term>
-  
+
     <listitem><para>This operation performs an actual garbage
     collection.  All dead paths are removed from the
     store.  This is the default.</para></listitem>
-    
+
   </varlistentry>
 
 </variablelist>
@@ -273,21 +322,15 @@ options control what gets deleted and in what order:
 <variablelist>
 
   <varlistentry><term><option>--max-freed</option> <replaceable>bytes</replaceable></term>
-  
-    <listitem><para>Keep deleting paths until at least
-    <replaceable>bytes</replaceable> bytes have been
-    deleted, then stop.</para></listitem>
-    
-  </varlistentry>
 
-  <varlistentry><term><option>--max-links</option> <replaceable>nrlinks</replaceable></term>
-  
-    <listitem><para>Keep deleting paths until the hard link count on
-    <filename>/nix/store</filename> is less than
-    <replaceable>nrlinks</replaceable>, then stop.  This is useful for
-    very large Nix stores on filesystems with a 32000 subdirectories
-    limit (like <literal>ext3</literal>).</para></listitem>
-    
+    <listitem><para>Keep deleting paths until at least
+    <replaceable>bytes</replaceable> bytes have been deleted, then
+    stop.  The argument <replaceable>bytes</replaceable> can be
+    followed by the multiplicative suffix <literal>K</literal>,
+    <literal>M</literal>, <literal>G</literal> or
+    <literal>T</literal>, denoting KiB, MiB, GiB or TiB
+    units.</para></listitem>
+
   </varlistentry>
 
 </variablelist>
@@ -311,7 +354,7 @@ would be freed.</para>
 <refsection><title>Examples</title>
 
 <para>To delete all unreachable paths, just do:
-    
+
 <screen>
 $ nix-store --gc
 deleting `/nix/store/kq82idx6g0nyzsp2s14gfsc38npai7lf-cairo-1.0.4.tar.gz.drv'
@@ -333,7 +376,7 @@ $ nix-store --gc --max-freed $((100 * 1024 * 1024))</screen>
 </refsection>
 
 
-  
+
 <!--######################################################################-->
 
 <refsection><title>Operation <option>--delete</option></title>
@@ -418,7 +461,7 @@ error: cannot delete path `/nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4'
 
 
 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--query</option> displays various bits of
 information about the store paths .  The queries are described below.  At
 most one query can be specified.  The default query is
@@ -438,16 +481,16 @@ query is applied to the target of the symlink.</para>
 
   <varlistentry><term><option>--use-output</option></term>
     <term><option>-u</option></term>
-  
+
     <listitem><para>For each argument to the query that is a store
     derivation, apply the query to the output path of the derivation
     instead.</para></listitem>
-    
+
   </varlistentry>
 
   <varlistentry><term><option>--force-realise</option></term>
     <term><option>-f</option></term>
-  
+
     <listitem><para>Realise each argument to the query first (see
     <link linkend="rsec-nix-store-realise"><command>nix-store
     --realise</command></link>).</para></listitem>
@@ -455,12 +498,12 @@ query is applied to the target of the symlink.</para>
   </varlistentry>
 
 </variablelist>
-        
+
 </refsection>
-    
+
 
 <refsection xml:id='nixref-queries'><title>Queries</title>
-            
+
 <variablelist>
 
   <varlistentry><term><option>--outputs</option></term>
@@ -470,7 +513,7 @@ query is applied to the target of the symlink.</para>
     derivations <replaceable>paths</replaceable>.  These are the paths
     that will be produced when the derivation is
     built.</para></listitem>
-    
+
   </varlistentry>
 
   <varlistentry><term><option>--requisites</option></term>
@@ -485,10 +528,10 @@ query is applied to the target of the symlink.</para>
     <variablelist>
 
       <varlistentry><term><option>--include-outputs</option></term>
-      
+
         <listitem><para>Also include the output path of store
         derivations, and their closures.</para></listitem>
-        
+
       </varlistentry>
 
     </variablelist>
@@ -502,13 +545,13 @@ query is applied to the target of the symlink.</para>
     including binaries of build-time-only dependencies) is obtained by
     distributing the closure of a store derivation and specifying the
     option <option>--include-outputs</option>.</para>
-    
+
     </listitem>
 
   </varlistentry>
 
   <varlistentry><term><option>--references</option></term>
-  
+
     <listitem><para>Prints the set of <link
     linkend="gloss-reference">references</link> of the store paths
     <replaceable>paths</replaceable>, that is, their immediate
@@ -516,9 +559,9 @@ query is applied to the target of the symlink.</para>
     <option>--requisites</option>.)</para></listitem>
 
   </varlistentry>
-  
+
   <varlistentry><term><option>--referrers</option></term>
-  
+
     <listitem><para>Prints the set of <emphasis>referrers</emphasis> of
     the store paths <replaceable>paths</replaceable>, that is, the
     store paths currently existing in the Nix store that refer to one
@@ -527,9 +570,9 @@ query is applied to the target of the symlink.</para>
     store paths are added or removed.</para></listitem>
 
   </varlistentry>
-  
+
   <varlistentry><term><option>--referrers-closure</option></term>
-  
+
     <listitem><para>Prints the closure of the set of store paths
     <replaceable>paths</replaceable> under the referrers relation; that
     is, all store paths that directly or indirectly refer to one of
@@ -540,7 +583,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
@@ -551,7 +594,7 @@ query is applied to the target of the symlink.</para>
   </varlistentry>
 
   <varlistentry><term><option>--graph</option></term>
-  
+
     <listitem><para>Prints the references graph of the store paths
     <replaceable>paths</replaceable> in the format of the
     <command>dot</command> tool of AT&amp;T's <link
@@ -564,7 +607,7 @@ query is applied to the target of the symlink.</para>
   </varlistentry>
 
   <varlistentry><term><option>--tree</option></term>
-  
+
     <listitem><para>Prints the references graph of the store paths
     <replaceable>paths</replaceable> as a nested ASCII tree.
     References are ordered by descending closure size; this tends to
@@ -576,7 +619,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
@@ -586,7 +629,7 @@ query is applied to the target of the symlink.</para>
   </varlistentry>
 
   <varlistentry><term><option>--hash</option></term>
-  
+
     <listitem><para>Prints the SHA-256 hash of the contents of the
     store paths <replaceable>paths</replaceable> (that is, the hash of
     the output of <command>nix-store --dump</command> on the given
@@ -596,7 +639,7 @@ query is applied to the target of the symlink.</para>
   </varlistentry>
 
   <varlistentry><term><option>--size</option></term>
-  
+
     <listitem><para>Prints the size in bytes of the contents of the
     store paths <replaceable>paths</replaceable> — to be precise, the
     size of the output of <command>nix-store --dump</command> on the
@@ -607,7 +650,7 @@ query is applied to the target of the symlink.</para>
   </varlistentry>
 
   <varlistentry><term><option>--roots</option></term>
-  
+
     <listitem><para>Prints the garbage collector roots that point,
     directly or indirectly, at the store paths
     <replaceable>paths</replaceable>.</para></listitem>
@@ -623,7 +666,7 @@ query is applied to the target of the symlink.</para>
 
 <para>Print the closure (runtime dependencies) of the
 <command>svn</command> program in the current user environment:
-    
+
 <screen>
 $ nix-store -qR $(which svn)
 /nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4
@@ -708,7 +751,7 @@ $ nix-store -q --roots $(which svn)
 
 </refsection>
 
-  
+
 
 <!--######################################################################-->
 
@@ -724,16 +767,50 @@ $ nix-store -q --roots $(which svn)
 </refsection>
 
 <refsection><title>Description</title>
-            
+
 <para>TODO</para>
 
 </refsection>
-            
+
 </refsection>
 -->
 
 
 
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--add</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-store</command>
+  <arg choice='plain'><option>--add</option></arg>
+  <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
+</cmdsynopsis>
+
+</refsection>
+
+<refsection><title>Description</title>
+
+<para>The operation <option>--add</option> adds the specified paths to
+the Nix store.  It prints the resulting paths in the Nix store on
+standard output.</para>
+
+</refsection>
+
+<refsection><title>Example</title>
+
+<screen>
+$ nix-store --add ./foo.c
+/nix/store/m7lrha58ph6rcnv109yzx1nk1cj7k7zf-foo.c</screen>
+
+</refsection>
+
+</refsection>
+
+
+
 <!--######################################################################-->
 
 <refsection xml:id='refsec-nix-store-verify'><title>Operation <option>--verify</option></title>
@@ -744,11 +821,12 @@ $ nix-store -q --roots $(which svn)
     <command>nix-store</command>
     <arg choice='plain'><option>--verify</option></arg>
     <arg><option>--check-contents</option></arg>
+    <arg><option>--repair</option></arg>
   </cmdsynopsis>
 </refsection>
 
 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--verify</option> verifies the internal
 consistency of the Nix database, and the consistency between the Nix
 database and the Nix store.  Any inconsistencies encountered are
@@ -756,27 +834,121 @@ automatically repaired.  Inconsistencies are generally the result of
 the Nix store or database being modified by non-Nix tools, or of bugs
 in Nix itself.</para>
 
-<para>There is one option:
+<para>This operation has the following options:
 
 <variablelist>
 
   <varlistentry><term><option>--check-contents</option></term>
-  
+
     <listitem><para>Checks that the contents of every valid store path
     has not been altered by computing a SHA-256 hash of the contents
     and comparing it with the hash stored in the Nix database at build
     time.  Paths that have been modified are printed out.  For large
     stores, <option>--check-contents</option> is obviously quite
     slow.</para></listitem>
-    
+
   </varlistentry>
-  
+
+  <varlistentry><term><option>--repair</option></term>
+
+    <listitem><para>If any valid path is missing from the store, or
+    (if <option>--check-contents</option> is given) the contents of a
+    valid path has been modified, then try to repair the path by
+    redownloading it.  See <command>nix-store --repair-path</command>
+    for details.</para></listitem>
+
+  </varlistentry>
+
 </variablelist>
 
 </para>
 
 </refsection>
-            
+
+
+</refsection>
+
+
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--verify-path</option></title>
+
+<refsection>
+  <title>Synopsis</title>
+  <cmdsynopsis>
+    <command>nix-store</command>
+    <arg choice='plain'><option>--verify-path</option></arg>
+    <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
+  </cmdsynopsis>
+</refsection>
+
+<refsection><title>Description</title>
+
+<para>The operation <option>--verify-path</option> compares the
+contents of the given store paths to their cryptographic hashes stored
+in Nix’s database.  For every changed path, it prints a warning
+message.  The exit status is 0 if no path has changed, and 1
+otherwise.</para>
+
+</refsection>
+
+<refsection><title>Example</title>
+
+<para>To verify the integrity of the <command>svn</command> command and all its dependencies:
+
+<screen>
+$ nix-store --verify-path $(nix-store -qR $(which svn))
+</screen>
+
+</para>
+
+</refsection>
+
+</refsection>
+
+
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--repair-path</option></title>
+
+<refsection>
+  <title>Synopsis</title>
+  <cmdsynopsis>
+    <command>nix-store</command>
+    <arg choice='plain'><option>--repair-path</option></arg>
+    <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
+  </cmdsynopsis>
+</refsection>
+
+<refsection><title>Description</title>
+
+<para>The operation <option>--repair-path</option> attempts to
+“repair” the specified paths by redownloading them using the available
+substituters.  If no substitutes are available, then repair is not
+possible.</para>
+
+<warning><para>During repair, there is a very small time window during
+which the old path (if it exists) is moved out of the way and replaced
+with the new path.  If repair is interrupted in between, then the
+system may be left in a broken state (e.g., if the path contains a
+critical system component like the GNU C Library).</para></warning>
+
+</refsection>
+
+<refsection><title>Example</title>
+
+<screen>
+$ nix-store --verify-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13
+path `/nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13' was modified!
+  expected hash `2db57715ae90b7e31ff1f2ecb8c12ec1cc43da920efcbe3b22763f36a1861588',
+  got `481c5aa5483ebc97c20457bb8bca24deea56550d3985cda0027f67fe54b808e4'
+
+$ nix-store --repair-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13
+fetching path `/nix/store/d7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13'...
+…
+</screen>
+
+</refsection>
 
 </refsection>
 
@@ -795,7 +967,7 @@ in Nix itself.</para>
 </refsection>
 
 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--dump</option> produces a NAR (Nix
 ARchive) file containing the contents of the file system tree rooted
 at <replaceable>path</replaceable>.  The archive is written to
@@ -826,7 +998,7 @@ links, but not other types of files (such as device nodes).</para>
 --restore</literal>.</para>
 
 </refsection>
-            
+
 
 </refsection>
 
@@ -845,13 +1017,13 @@ links, but not other types of files (such as device nodes).</para>
 </refsection>
 
 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--restore</option> unpacks a NAR archive
 to <replaceable>path</replaceable>, which must not already exist.  The
 archive is read from standard input.</para>
 
 </refsection>
-            
+
 
 </refsection>
 
@@ -870,7 +1042,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
@@ -897,7 +1069,7 @@ linkend="sec-nix-copy-closure">nix-copy-closure</command>
 command.</para>
 
 </refsection>
-            
+
 
 </refsection>
 
@@ -915,17 +1087,17 @@ command.</para>
 </refsection>
 
 <refsection><title>Description</title>
-            
-<para>The operation <option>--export</option> reads a serialisation of
+
+<para>The operation <option>--import</option> reads a serialisation of
 a set of store paths produced by <command
-linkend="refsec-nix-store-export">nix-store --import</command> from
+linkend="refsec-nix-store-export">nix-store --export</command> from
 standard input and adds those store paths to the Nix store.  Paths
 that already exist in the Nix store are ignored.  If a path refers to
 another path that doesn’t exist in the Nix store, the import
 fails.</para>
 
 </refsection>
-            
+
 
 </refsection>
 
@@ -943,7 +1115,7 @@ fails.</para>
 </refsection>
 
 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--optimise</option> reduces Nix store disk
 space usage by finding identical files in the store and hard-linking
 them to each other.  It typically reduces the size of the store by
@@ -960,7 +1132,7 @@ on the achieved savings is printed on standard error.</para>
 progress indication.</para>
 
 </refsection>
-            
+
 <refsection><title>Example</title>
 
 <screen>
@@ -994,7 +1166,7 @@ there are 114486 files with equal contents out of 215894 files in total
 </refsection>
 
 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--read-log</option> prints the build log
 of the specified store paths on standard output.  The build log is
 whatever the builder of a derivation wrote to standard output and
@@ -1003,12 +1175,17 @@ 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. If the log is not available
+locally, then <command>nix-store</command> will try to download the
+log from the servers specified in the Nix option
+<option>log-servers</option>. For example, if it’s set to
+<literal>http://hydra.nixos.org/log</literal>, then Nix will check
+<literal>http://hydra.nixos.org/log/<replaceable>base-name</replaceable></literal>.</para>
 
 </refsection>
-            
+
 <refsection><title>Example</title>
 
 <screen>
@@ -1040,20 +1217,20 @@ ktorrent-2.2.1/NEWS
 </refsection>
 
 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--dump-db</option> writes a dump of the
 Nix database to standard output.  It can be loaded into an empty Nix
 store using <option>--load-db</option>.  This is useful for making
 backups and when migrating to different database schemas.</para>
 
 </refsection>
-            
+
 </refsection>
 
 
 <!--######################################################################-->
 
-<refsection><title>Operation <option>--dump-db</option></title>
+<refsection><title>Operation <option>--load-db</option></title>
 
 <refsection>
   <title>Synopsis</title>
@@ -1064,13 +1241,188 @@ backups and when migrating to different database schemas.</para>
 </refsection>
 
 <refsection><title>Description</title>
-            
+
 <para>The operation <option>--load-db</option> reads a dump of the Nix
 database created by <option>--dump-db</option> from standard input and
 loads it into the Nix database.</para>
 
 </refsection>
-            
+
+</refsection>
+
+
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--print-env</option></title>
+
+<refsection>
+  <title>Synopsis</title>
+  <cmdsynopsis>
+    <command>nix-store</command>
+    <arg choice='plain'><option>--print-env</option></arg>
+    <arg choice='plain'><replaceable>drvpath</replaceable></arg>
+  </cmdsynopsis>
+</refsection>
+
+<refsection><title>Description</title>
+
+<para>The operation <option>--print-env</option> prints out the
+environment of a derivation in a format that can be evaluated by a
+shell.  The command line arguments of the builder are placed in the
+variable <envar>_args</envar>.</para>
+
+</refsection>
+
+<refsection><title>Example</title>
+
+<screen>
+$ nix-store --print-env $(nix-instantiate '&lt;nixpkgs>' -A firefox)
+<replaceable>…</replaceable>
+export src; src='/nix/store/plpj7qrwcz94z2psh6fchsi7s8yihc7k-firefox-12.0.source.tar.bz2'
+export stdenv; stdenv='/nix/store/7c8asx3yfrg5dg1gzhzyq2236zfgibnn-stdenv'
+export system; system='x86_64-linux'
+export _args; _args='-e /nix/store/9krlzvny65gdc8s7kpb6lkx8cd02c25c-default-builder.sh'
+</screen>
+
+</refsection>
+
+</refsection>
+
+
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--query-failed-paths</option></title>
+
+<refsection>
+  <title>Synopsis</title>
+  <cmdsynopsis>
+    <command>nix-store</command>
+    <arg choice='plain'><option>--query-failed-paths</option></arg>
+  </cmdsynopsis>
+</refsection>
+
+<refsection><title>Description</title>
+
+<para>If build failure caching is enabled through the
+<literal>build-cache-failure</literal> configuration option, the
+operation <option>--query-failed-paths</option> will print out all
+store paths that have failed to build.</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-failure</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>
+
+
+<!--######################################################################-->
+
+<refsection xml:id='rsec-nix-store-generate-binary-cache-key'><title>Operation <option>--generate-binary-cache-key</option></title>
+
+<refsection>
+  <title>Synopsis</title>
+  <cmdsynopsis>
+    <command>nix-store</command>
+    <arg choice='plain'>
+      <option>--generate-binary-cache-key</option>
+      <option>key-name</option>
+      <option>secret-key-file</option>
+      <option>public-key-file</option>
+    </arg>
+  </cmdsynopsis>
+</refsection>
+
+<refsection><title>Description</title>
+
+<para>This command generates an <link
+xlink:href="http://ed25519.cr.yp.to/">Ed25519 key pair</link> that can
+be used to create a signed binary cache. It takes three mandatory
+parameters:
+
+<orderedlist>
+
+  <listitem><para>A key name, such as
+  <literal>cache.example.org-1</literal>, that is used to look up keys
+  on the client when it verifies signatures. It can be anything, but
+  it’s suggested to use the host name of your cache
+  (e.g. <literal>cache.example.org</literal>) with a suffix denoting
+  the number of the key (to be incremented every time you need to
+  revoke a key).</para></listitem>
+
+  <listitem><para>The file name where the secret key is to be
+  stored.</para></listitem>
+
+  <listitem><para>The file name where the public key is to be
+  stored.</para></listitem>
+
+</orderedlist>
+
+For an example, see the manual page for <command
+linkend="sec-nix-push">nix-push</command>.</para>
+
+</refsection>
+
+</refsection>
+
+
+<!--######################################################################-->
+
+<refsection condition="manpage"><title>Environment variables</title>
+
+<variablelist>
+  <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" />
+</variablelist>
+
 </refsection>
 
 

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

@@ -14,11 +14,15 @@
   <replaceable>number</replaceable>
 </arg>
 <arg>
-  <arg><option>--cores</option></arg>
+  <option>--cores</option>
   <replaceable>number</replaceable>
 </arg>
 <arg>
-  <arg><option>--max-silent-time</option></arg>
+  <option>--max-silent-time</option>
+  <replaceable>number</replaceable>
+</arg>
+<arg>
+  <option>--timeout</option>
   <replaceable>number</replaceable>
 </arg>
 <arg><option>--keep-going</option></arg>
@@ -29,6 +33,15 @@
 <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>
+  <replaceable>path</replaceable>
+</arg>
+<arg>
+  <option>--option</option>
+  <replaceable>name</replaceable>
+  <replaceable>value</replaceable>
+</arg>
 <sbr />
 
 </nop>

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

@@ -1,22 +1,22 @@
-<section xmlns="http://docbook.org/ns/docbook" xml:id="sec-common-options">
+<chapter xmlns="http://docbook.org/ns/docbook" xml:id="sec-common-options">
 
-<title>Common options</title>
+<title>Common Options</title>
 
 
 <para>Most Nix commands accept the following command-line options:</para>
 
-<variablelist>
+<variablelist xml:id="opt-common">
 
 <varlistentry><term><option>--help</option></term>
-  
+
   <listitem><para>Prints out a summary of the command syntax and
   exits.</para></listitem>
-  
+
 </varlistentry>
 
 
 <varlistentry><term><option>--version</option></term>
-  
+
   <listitem><para>Prints out the Nix version number on standard output
   and exits.</para></listitem>
 </varlistentry>
@@ -26,7 +26,7 @@
   <term><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 +37,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,11 +68,11 @@
     <listitem><para>“Vomit”: print vast amounts of debug
     information.</para></listitem>
     </varlistentry>
-    
+
   </variablelist>
 
   </listitem>
-  
+
 </varlistentry>
 
 
@@ -85,7 +85,7 @@
   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>
 
 
@@ -99,7 +99,7 @@
   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>
 
 
@@ -117,7 +117,7 @@
   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>
 
 
@@ -132,6 +132,16 @@
 
 </varlistentry>
 
+<varlistentry xml:id="opt-timeout"><term><option>--timeout</option></term>
+
+  <listitem><para>Sets the maximum number of seconds that a builder
+  can run.  The default is specified by the <link
+  linkend='conf-build-timeout'><literal>build-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>
 
@@ -141,7 +151,7 @@
   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>
 
 
@@ -171,14 +181,14 @@
   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>
 
 
@@ -187,7 +197,7 @@
   <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>
 
 
@@ -226,7 +236,7 @@
       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
+      file that can be browsed interactively, using JavaScript to
       expand and collapse parts of the output.</para></listitem>
 
     </varlistentry>
@@ -237,12 +247,12 @@
 
     </varlistentry>
 
-  </variablelist>    
-  
+  </variablelist>
+
   </para>
 
   </listitem>
-  
+
 </varlistentry>
 
 
@@ -254,8 +264,8 @@
   expression evaluator will automatically try to call functions that
   it encounters.  It can automatically call functions for which every
   argument has a <link linkend='ss-functions'>default value</link>
-  (e.g., <literal>{<replaceable>argName</replaceable> ?
-  <replaceable>defaultValue</replaceable>}:
+  (e.g., <literal>{ <replaceable>argName</replaceable> ?
+  <replaceable>defaultValue</replaceable> }:
   <replaceable>...</replaceable></literal>).  With
   <option>--arg</option>, you can also call functions that have
   arguments without a default value (or override a default value).
@@ -300,10 +310,10 @@
 <varlistentry xml:id="opt-attr"><term><option>--attr</option> / <option>-A</option>
 <replaceable>attrPath</replaceable></term>
 
-  <listitem><para>In <command>nix-env</command>,
-  <command>nix-instantiate</command> and <command>nix-build</command>,
-  <option>--attr</option> allows you to select an attribute from the
-  top-level Nix expression being evaluated.  The <emphasis>attribute
+  <listitem><para>Select an attribute from the top-level Nix
+  expression being evaluated.  (<command>nix-env</command>,
+  <command>nix-instantiate</command>, <command>nix-build</command> and
+  <command>nix-shell</command> only.)  The <emphasis>attribute
   path</emphasis> <replaceable>attrPath</replaceable> is a sequence of
   attribute names separated by dots.  For instance, given a top-level
   Nix expression <replaceable>e</replaceable>, the attribute path
@@ -323,15 +333,58 @@
 </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 xml:id="opt-I"><term><option>-I</option> <replaceable>path</replaceable></term>
+
+  <listitem><para>Add a path to the Nix expression search path.  This
+  option may be given multiple times.  See the <envar
+  linkend="env-NIX_PATH">NIX_PATH</envar> environment variable for
+  information on the semantics of the Nix search path.  Paths added
+  through <option>-I</option> take precedence over
+  <envar>NIX_PATH</envar>.</para></listitem>
+
+</varlistentry>
+
+
+<varlistentry><term><option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term>
+
+  <listitem><para>Set the Nix configuration option
+  <replaceable>name</replaceable> to <replaceable>value</replaceable>.
+  This overrides settings in the Nix configuration file (see
+  <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</para></listitem>
+
+</varlistentry>
+
+
+<varlistentry><term><option>--repair</option></term>
+
+  <listitem><para>Fix corrupted or missing store paths by
+  redownloading or rebuilding them.  Note that this is slow because it
+  requires computing a cryptographic hash of the contents of every
+  path in the closure of the build.  Also note the warning under
+  <command>nix-store --repair-path</command>.</para></listitem>
+
 </varlistentry>
 
 
 </variablelist>
 
 
-</section>
+</chapter>

doc/manual/command-ref/utilities.xml

@@ -0,0 +1,26 @@
+<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-generate-patches.xml" />
+-->
+<xi:include href="nix-hash.xml" />
+<xi:include href="nix-install-package.xml" />
+<xi:include href="nix-instantiate.xml" />
+<xi:include href="nix-prefetch-url.xml" />
+<xi:include href="nix-pull.xml" />
+<xi:include href="nix-push.xml" />
+
+</chapter>

doc/manual/conf-file.xml

@@ -1,272 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="sec-conf-file">
-
-<title>Nix configuration file</title>
-
-
-<para>A number of persistent settings of Nix are stored in the file
-<filename><replaceable>prefix</replaceable>/etc/nix/nix.conf</filename>.
-This file is a list of <literal><replaceable>name</replaceable> =
-<replaceable>value</replaceable></literal> pairs, one per line.
-Comments start with a <literal>#</literal> character.  An example
-configuration file is shown in <xref linkend="ex-nix-conf" />.</para>
-
-<example xml:id='ex-nix-conf'><title>Nix configuration file</title>
-
-<programlisting>
-gc-keep-outputs = true       # Nice for developers
-gc-keep-derivations = true   # Idem
-env-keep-derivations = false
-</programlisting>
-</example>
-
-<para>The following variables are currently available: 
-
-<variablelist>
-
-  
-  <varlistentry xml:id="conf-gc-keep-outputs"><term><literal>gc-keep-outputs</literal></term>
-
-    <listitem><para>If <literal>true</literal>, the garbage collector
-    will keep the outputs of non-garbage derivations.  If
-    <literal>false</literal> (default), outputs will be deleted unless
-    they are GC roots themselves (or reachable from other roots).</para>
- 
-    <para>In general, outputs must be registered as roots separately.
-    However, even if the output of a derivation is registered as a
-    root, the collector will still delete store paths that are used
-    only at build time (e.g., the C compiler, or source tarballs
-    downloaded from the network).  To prevent it from doing so, set
-    this option to <literal>true</literal>.</para></listitem>
-
-  </varlistentry>
-  
-
-  <varlistentry xml:id="conf-gc-keep-derivations"><term><literal>gc-keep-derivations</literal></term>
-
-    <listitem><para>If <literal>true</literal> (default), the garbage
-    collector will keep the derivations from which non-garbage store
-    paths were built.  If <literal>false</literal>, they will be
-    deleted unless explicitly registered as a root (or reachable from
-    other roots).</para>
-
-    <para>Keeping derivation around is useful for querying and
-    traceability (e.g., it allows you to ask with what dependencies or
-    options a store path was built), so by default this option is on.
-    Turn it off to safe a bit of disk space (or a lot if
-    <literal>gc-keep-outputs</literal> is also turned on).</para></listitem>
-
-  </varlistentry>
-
-  
-  <varlistentry><term><literal>env-keep-derivations</literal></term>
-
-    <listitem><para>If <literal>false</literal> (default), derivations
-    are not stored in Nix user environments.  That is, the derivation
-    any build-time-only dependencies may be garbage-collected.</para>
-
-    <para>If <literal>true</literal>, when you add a Nix derivation to
-    a user environment, the path of the derivation is stored in the
-    user environment.  Thus, the derivation will not be
-    garbage-collected until the user environment generation is deleted
-    (<command>nix-env --delete-generations</command>).  To prevent
-    build-time-only dependencies from being collected, you should also
-    turn on <literal>gc-keep-outputs</literal>.</para>
-
-    <para>The difference between this option and
-    <literal>gc-keep-derivations</literal> is that this one is
-    “sticky”: it applies to any user environment created while this
-    option was enabled, while <literal>gc-keep-derivations</literal>
-    only applies at the moment the garbage collector is
-    run.</para></listitem>
-
-  </varlistentry>
-
-  
-  <varlistentry xml:id="conf-build-max-jobs"><term><literal>build-max-jobs</literal></term>
-
-    <listitem><para>This option defines the maximum number of jobs
-    that Nix will try to build in parallel.  The default is
-    <literal>1</literal>.  You should generally set it to the number
-    of CPUs in your system (e.g., <literal>2</literal> on a Athlon 64
-    X2).  It can be overriden using the <option
-    linkend='opt-max-jobs'>--max-jobs</option> (<option>-j</option>)
-    command line switch.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-build-cores"><term><literal>build-cores</literal></term>
-
-    <listitem><para>Sets the value of the
-    <envar>NIX_BUILD_CORES</envar> environment variable in the
-    invocation of builders.  Builders can use this variable at their
-    discretion to control the maximum amount of parallelism.  For
-    instance, in Nixpkgs, if the derivation attribute
-    <varname>enableParallelBuilding</varname> is set to
-    <literal>true</literal>, the builder passes the
-    <option>-j<replaceable>N</replaceable></option> flag to GNU Make.
-    It can be overriden using the <option
-    linkend='opt-cores'>--cores</option> command line switch and
-    defaults to <literal>1</literal>.  The value <literal>0</literal>
-    means that the builder should use all available CPU cores in the
-    system.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-build-max-silent-time"><term><literal>build-max-silent-time</literal></term>
-
-    <listitem>
-
-      <para>This option defines the maximum number of seconds that a
-      builder can go without producing any data on standard output or
-      standard error.  This is useful (for instance in a automated
-      build system) to catch builds that are stuck in an infinite
-      loop, or to catch remote builds that are hanging due to network
-      problems.  It can be overriden using the <option
-      linkend="opt-max-silent-time">--max-silent-time</option> command
-      line switch.</para>
-
-      <para>The value <literal>0</literal> means that there is no
-      timeout.  This is also the default.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-
-  <varlistentry xml:id="conf-build-users-group"><term><literal>build-users-group</literal></term>
-
-    <listitem><para>This options specifies the Unix group containing
-    the Nix build user accounts.  In multi-user Nix installations,
-    builds should not be performed by the Nix account since that would
-    allow users to arbitrarily modify the Nix store and database by
-    supplying specially crafted builders; and they cannot be performed
-    by the calling user since that would allow him/her to influence
-    the build result.</para>
-
-    <para>Therefore, if this option is non-empty and specifies a valid
-    group, builds will be performed under the user accounts that are a
-    member of the group specified here (as listed in
-    <filename>/etc/group</filename>).  Those user accounts should not
-    be used for any other purpose!</para>
-
-    <para>Nix will never run two builds under the same user account at
-    the same time.  This is to prevent an obvious security hole: a
-    malicious user writing a Nix expression that modifies the build
-    result of a legitimate Nix expression being built by another user.
-    Therefore it is good to have as many Nix build user accounts as
-    you can spare.  (Remember: uids are cheap.)</para>
-
-    <para>The build users should have permission to create files in
-    the Nix store, but not delete them.  Therefore,
-    <filename>/nix/store</filename> should be owned by the Nix
-    account, its group should be the group specified here, and its
-    mode should be <literal>1775</literal>.</para>
-
-    <para>If the build users group is empty, builds will be performed
-    under the uid of the Nix process (that is, the uid of the caller
-    if <envar>NIX_REMOTE</envar> is empty, the uid under which the Nix
-    daemon runs if <envar>NIX_REMOTE</envar> is
-    <literal>daemon</literal>, or the uid that owns the setuid
-    <command>nix-worker</command> program if <envar>NIX_REMOTE</envar>
-    is <literal>slave</literal>).  Obviously, this should not be used
-    in multi-user settings with untrusted users.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-
-  <varlistentry><term><literal>build-use-chroot</literal></term>
-
-    <listitem><para>If set to <literal>true</literal>, builds will be
-    performed in a <emphasis>chroot environment</emphasis>, i.e., the
-    build will be isolated from the normal file system hierarchy and
-    will only see the Nix store, the temporary build directory, and
-    the directories configured with the <link
-    linkend='conf-build-chroot-dirs'><literal>build-chroot-dirs</literal>
-    option</link> (such as <filename>/proc</filename> and
-    <filename>/dev</filename>).  This is useful to prevent undeclared
-    dependencies on files in directories such as
-    <filename>/usr/bin</filename>.</para>
-
-    <para>The use of a chroot requires that Nix is run as root (but
-    you can still use the <link
-    linkend='conf-build-users-group'>“build users” feature</link> to
-    perform builds under different users than root).  Currently,
-    chroot builds only work on Linux because Nix uses “bind mounts” to
-    make the Nix store and other directories available inside the
-    chroot.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-  
-  <varlistentry xml:id="conf-build-chroot-dirs"><term><literal>build-chroot-dirs</literal></term>
-
-    <listitem><para>When builds are performed in a chroot environment,
-    Nix will mount (using <command>mount --bind</command> on Linux)
-    some directories from the normal file system hierarchy inside the
-    chroot.  These are the Nix store, the temporary build directory
-    (usually
-    <filename>/tmp/nix-<replaceable>pid</replaceable>-<replaceable>number</replaceable></filename>)
-    and the directories listed here.  The default is <literal>dev
-    /proc</literal>.  Files in <filename>/dev</filename> (such as
-    <filename>/dev/null</filename>) are needed by many builds, and
-    some files in <filename>/proc</filename> may also be needed
-    occasionally.</para>
-
-    <para>The value used on NixOS is
-    
-<programlisting>
-build-use-chroot = /dev /proc /bin</programlisting>
-
-    to make the <filename>/bin/sh</filename> symlink available (which
-    is still needed by many builders).</para>
-
-    </listitem>
-
-  </varlistentry>
-
-  
-  <varlistentry><term><literal>system</literal></term>
-
-    <listitem><para>This option specifies the canonical Nix system
-    name of the current installation, such as
-    <literal>i686-linux</literal> or
-    <literal>powerpc-darwin</literal>.  Nix can only build derivations
-    whose <literal>system</literal> attribute equals the value
-    specified here.  In general, it never makes sense to modify this
-    value from its default, since you can use it to ‘lie’ about the
-    platform you are building on (e.g., perform a Mac OS build on a
-    Linux machine; the result would obviously be wrong).  It only
-    makes sense if the Nix binaries can run on multiple platforms,
-    e.g., ‘universal binaries’ that run on <literal>powerpc-darwin</literal> and
-    <literal>i686-darwin</literal>.</para>
-
-    <para>It defaults to the canonical Nix system name detected by
-    <filename>configure</filename> at build time.</para></listitem>
-
-  </varlistentry>
-
-
-  <varlistentry><term><literal>fsync-metadata</literal></term>
-
-    <listitem><para>If set to <literal>true</literal>, changes to the
-    Nix store metadata (in <filename>/nix/var/nix/db</filename>) are
-    synchronously flushed to disk.  This improves robustness in case
-    of system crashes, but reduces performance.  The default is
-    <literal>true</literal>.</para></listitem>
-
-  </varlistentry>
-    
-</variablelist>
-
-</para>
-
-
-</section>

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;
+  md5 = "70c9ccf9fac07f762c24f2df2290784d";
+}
+</programlisting>
+
+    It sometimes happens that the URL of the file changes, e.g.,
+    because servers are reorganised or no longer available.  We then
+    must update the call to <function>fetchurl</function>, e.g.,
+
+<programlisting>
+fetchurl {
+  url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
+  md5 = "70c9ccf9fac07f762c24f2df2290784d";
+}
+</programlisting>
+
+    If a <function>fetchurl</function> derivation was treated like a
+    normal derivation, the output paths of the derivation and
+    <emphasis>all derivations depending on it</emphasis> would change.
+    For instance, if we were to change the URL of the Glibc source
+    distribution in Nixpkgs (a package on which almost all other
+    packages depend) massive rebuilds would be needed.  This is
+    unfortunate for a change which we know cannot have a real effect
+    as it propagates upwards through the dependency graph.</para>
+
+    <para>For fixed-output derivations, on the other hand, the name of
+    the output path only depends on the <varname>outputHash*</varname>
+    and <varname>name</varname> attributes, while all other attributes
+    are ignored for the purpose of computing the output path.  (The
+    <varname>name</varname> attribute is included because it is part
+    of the path.)</para>
+
+    <para>As an example, here is the (simplified) Nix expression for
+    <varname>fetchurl</varname>:
+
+<programlisting>
+{ stdenv, curl }: # The <command>curl</command> program is used for downloading.
+
+{ url, md5 }:
+
+stdenv.mkDerivation {
+  name = baseNameOf (toString url);
+  builder = ./builder.sh;
+  buildInputs = [ curl ];
+
+  # This is a fixed-output derivation; the output must be a regular
+  # file with MD5 hash <varname>md5</varname>.
+  outputHashMode = "flat";
+  outputHashAlgo = "md5";
+  outputHash = md5;
+
+  inherit url;
+}
+</programlisting>
+
+    </para>
+
+    <para>The <varname>outputHashAlgo</varname> attribute specifies
+    the hash algorithm used to compute the hash.  It can currently be
+    <literal>"md5"</literal>, <literal>"sha1"</literal> or
+    <literal>"sha256"</literal>.</para>
+
+    <para>The <varname>outputHashMode</varname> attribute determines
+    how the hash is computed.  It must be one of the following two
+    values:
+
+    <variablelist>
+
+      <varlistentry><term><literal>"flat"</literal></term>
+
+        <listitem><para>The output must be a non-executable regular
+        file.  If it isn’t, the build fails.  The hash is simply
+        computed over the contents of that file (so it’s equal to what
+        Unix commands like <command>md5sum</command> or
+        <command>sha1sum</command> produce).</para>
+
+        <para>This is the default.</para></listitem>
+
+      </varlistentry>
+
+      <varlistentry><term><literal>"recursive"</literal></term>
+
+        <listitem><para>The hash is computed over the NAR archive dump
+        of the output (i.e., the result of <link
+        linkend="refsec-nix-store-dump"><command>nix-store
+        --dump</command></link>).  In this case, the output can be
+        anything, including a directory tree.</para></listitem>
+
+      </varlistentry>
+
+    </variablelist>
+
+    </para>
+
+    <para>The <varname>outputHash</varname> attribute, finally, must
+    be a string containing the hash in either hexadecimal or base-32
+    notation.  (See the <link
+    linkend="sec-nix-hash"><command>nix-hash</command> command</link>
+    for information about converting to and from base-32
+    notation.)</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><varname>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,14 +13,14 @@ 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>
 
-  
+
   <varlistentry><term><function>abort</function> <replaceable>s</replaceable></term>
 
     <listitem><para>Abort Nix expression evaluation, print error
@@ -27,7 +28,7 @@ is also available as <function>builtins.derivation</function>.</para>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>builtins.add</function>
   <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
 
@@ -37,25 +38,50 @@ is also available as <function>builtins.derivation</function>.</para>
 
   </varlistentry>
 
-  
-  <varlistentry><term><function>builtins.attrNames</function>
-  <replaceable>attrs</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:
+  <varlistentry><term><function>builtins.all</function>
+  <replaceable>pred</replaceable> <replaceable>list</replaceable></term>
 
-<programlisting>
-attrValues = attrs: map (name: builtins.getAttr name attrs) (builtins.attrNames attrs);</programlisting>
-
-    </para></listitem>
+    <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>set</replaceable></term>
+
+    <listitem><para>Return the names of the attributes in the set
+    <replaceable>set</replaceable> in a sorted list.  For instance,
+    <literal>builtins.attrNames { y = 1; x = "foo"; }</literal>
+    evaluates to <literal>[ "x" "y" ]</literal>.</para></listitem>
+
+  </varlistentry>
+
+
+  <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>
+
+
   <varlistentry><term><function>baseNameOf</function> <replaceable>s</replaceable></term>
 
     <listitem><para>Return the <emphasis>base name</emphasis> of the
@@ -65,11 +91,11 @@ attrValues = attrs: map (name: builtins.getAttr name attrs) (builtins.attrNames
 
   </varlistentry>
 
-  
+
   <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.,
 
@@ -82,7 +108,7 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>builtins.compareVersions</function>
   <replaceable>s1</replaceable> <replaceable>s2</replaceable></term>
 
@@ -99,7 +125,16 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
 
   </varlistentry>
 
-  
+
+  <varlistentry><term><function>builtins.concatLists</function>
+  <replaceable>lists</replaceable></term>
+
+    <listitem><para>Concatenate a list of lists into a single
+    list.</para></listitem>
+
+  </varlistentry>
+
+
   <varlistentry
   xml:id='builtin-currentSystem'><term><varname>builtins.currentSystem</varname></term>
 
@@ -124,7 +159,7 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
   </varlistentry>
   -->
 
-  
+
   <!--
   <varlistentry><term><function>dependencyClosure</function></term>
 
@@ -133,7 +168,20 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
   </varlistentry>
   -->
 
-  
+
+  <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>
 
@@ -152,7 +200,7 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>builtins.div</function>
   <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
 
@@ -162,7 +210,79 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
 
   </varlistentry>
 
-  
+
+  <varlistentry><term><function>builtins.elem</function>
+  <replaceable>x</replaceable> <replaceable>xs</replaceable></term>
+
+    <listitem><para>Return <literal>true</literal> if a value equal to
+    <replaceable>x</replaceable> occurs in the list
+    <replaceable>xs</replaceable>, and <literal>false</literal>
+    otherwise.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><function>builtins.elemAt</function>
+  <replaceable>xs</replaceable> <replaceable>n</replaceable></term>
+
+    <listitem><para>Return element <replaceable>n</replaceable> from
+    the list <replaceable>xs</replaceable>.  Elements are counted
+    starting from 0.  A fatal error occurs in the index is out of
+    bounds.</para></listitem>
+
+  </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>
+
+    </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>
+
+    <listitem><para>Return a list consisting of the elements of
+    <replaceable>xs</replaceable> for which the function
+    <replaceable>f</replaceable> returns
+    <literal>true</literal>.</para></listitem>
+
+  </varlistentry>
+
+
   <varlistentry><term><function>builtins.filterSource</function>
   <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
 
@@ -214,20 +334,85 @@ 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>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>builtins.getEnv</function>
   <replaceable>s</replaceable></term>
 
@@ -245,21 +430,33 @@ stdenv.mkDerivation {
 
   </varlistentry>
 
-  
+
   <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>
+
+
   <varlistentry><term><function>builtins.head</function>
   <replaceable>list</replaceable></term>
 
@@ -270,17 +467,19 @@ stdenv.mkDerivation {
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>import</function>
   <replaceable>path</replaceable></term>
 
     <listitem><para>Load, parse and return the Nix expression in the
-    file <replaceable>path</replaceable>.  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>
+    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 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
@@ -288,7 +487,7 @@ stdenv.mkDerivation {
     built-in).  Therefore, it cannot refer to variables that are in
     scope at the call site.  For instance, if you have a calling
     expression
-    
+
 <programlisting>
 rec {
   x = 123;
@@ -323,27 +522,27 @@ x: x + 456</programlisting>
 
   </varlistentry>
 
-  
+
   <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>
-        
-    
+
+
   <varlistentry><term><function>builtins.isAttrs</function>
   <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>
 
-  
+
   <varlistentry><term><function>builtins.isList</function>
   <replaceable>e</replaceable></term>
 
@@ -353,7 +552,7 @@ x: x + 456</programlisting>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>builtins.isFunction</function>
   <replaceable>e</replaceable></term>
 
@@ -363,7 +562,7 @@ x: x + 456</programlisting>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>builtins.isString</function>
   <replaceable>e</replaceable></term>
 
@@ -373,17 +572,17 @@ x: x + 456</programlisting>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>builtins.isInt</function>
   <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.isBool</function>
   <replaceable>e</replaceable></term>
 
@@ -393,7 +592,7 @@ x: x + 456</programlisting>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>isNull</function>
   <replaceable>e</replaceable></term>
 
@@ -403,12 +602,12 @@ x: x + 456</programlisting>
 
     <warning><para>This function is <emphasis>deprecated</emphasis>;
     just write <literal>e == null</literal> instead.</para></warning>
-    
+
     </listitem>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>builtins.length</function>
   <replaceable>e</replaceable></term>
 
@@ -417,7 +616,7 @@ x: x + 456</programlisting>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>builtins.lessThan</function>
   <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
 
@@ -430,22 +629,22 @@ x: x + 456</programlisting>
 
   </varlistentry>
 
-  
+
   <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:
 
 <programlisting>
-builtins.listToAttrs [
-  {name = "foo"; value = 123;}
-  {name = "bar"; value = 456;}
-]
+builtins.listToAttrs
+  [ { name = "foo"; value = 123; }
+    { name = "bar"; value = 456; }
+  ]
 </programlisting>
 
     evaluates to
@@ -457,7 +656,7 @@ builtins.listToAttrs [
     </para></listitem>
 
   </varlistentry>
-  
+
   <varlistentry><term><function>map</function>
   <replaceable>f</replaceable> <replaceable>list</replaceable></term>
 
@@ -466,14 +665,14 @@ builtins.listToAttrs [
     example,
 
 <programlisting>
-map (x: "foo" + x) ["bar" "bla" "abc"]</programlisting>
+map (x: "foo" + x) [ "bar" "bla" "abc" ]</programlisting>
+
+    evaluates to <literal>[ "foobar" "foobla" "fooabc"
+    ]</literal>.</para></listitem>
 
-    evaluates to <literal>["foobar" "foobla"
-    "fooabc"]</literal>.</para></listitem>
-    
   </varlistentry>
 
-  
+
   <varlistentry><term><function>builtins.mul</function>
   <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
 
@@ -483,7 +682,7 @@ map (x: "foo" + x) ["bar" "bla" "abc"]</programlisting>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>builtins.parseDrvName</function>
   <replaceable>s</replaceable></term>
 
@@ -491,14 +690,14 @@ 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>
+    returns <literal>{ name = "nix"; version = "0.12pre12876";
+    }</literal>.</para></listitem>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>builtins.pathExists</function>
   <replaceable>path</replaceable></term>
 
@@ -523,15 +722,28 @@ 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>
   <replaceable>path</replaceable></term>
 
@@ -539,24 +751,75 @@ in config.someSetting</programlisting>
     <replaceable>path</replaceable> as a string.</para></listitem>
 
   </varlistentry>
-  
-  
+
+
   <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>
+    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.stringLength</function>
   <replaceable>e</replaceable></term>
 
@@ -566,7 +829,7 @@ removeAttrs { x = 1; y = 2; z = 3; } ["a" "x" "z"]</screen>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>builtins.sub</function>
   <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
 
@@ -576,7 +839,7 @@ removeAttrs { x = 1; y = 2; z = 3; } ["a" "x" "z"]</screen>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>builtins.substring</function>
   <replaceable>start</replaceable> <replaceable>len</replaceable>
   <replaceable>s</replaceable></term>
@@ -594,7 +857,7 @@ removeAttrs { x = 1; y = 2; z = 3; } ["a" "x" "z"]</screen>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>builtins.tail</function>
   <replaceable>list</replaceable></term>
 
@@ -604,7 +867,7 @@ removeAttrs { x = 1; y = 2; z = 3; } ["a" "x" "z"]</screen>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>throw</function>
   <replaceable>s</replaceable></term>
 
@@ -618,7 +881,7 @@ removeAttrs { x = 1; y = 2; z = 3; } ["a" "x" "z"]</screen>
 
   </varlistentry>
 
-  
+
   <varlistentry
   xml:id='builtin-toFile'><term><function>builtins.toFile</function>
   <replaceable>name</replaceable> <replaceable>s</replaceable></term>
@@ -632,11 +895,11 @@ removeAttrs { x = 1; y = 2; z = 3; } ["a" "x" "z"]</screen>
     linkend='ex-hello-builder' /> into one file:
 
 <programlisting>
-{stdenv, fetchurl, perl}:
+{ stdenv, fetchurl, perl }:
 
 stdenv.mkDerivation {
   name = "hello-2.1.1";
-  
+
   builder = builtins.toFile "builder.sh" "
     source $stdenv/setup
 
@@ -655,7 +918,7 @@ stdenv.mkDerivation {
   };
   inherit perl;
 }</programlisting>
-  
+
     </para>
 
     <para>It is even possible for one file to refer to another, e.g.,
@@ -693,7 +956,20 @@ 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, 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
@@ -706,7 +982,7 @@ in foo</programlisting>
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>toString</function> <replaceable>e</replaceable></term>
 
     <listitem><para>Convert the expression
@@ -718,7 +994,7 @@ in foo</programlisting>
 
   </varlistentry>
 
-  
+
   <varlistentry xml:id='builtin-toXML'><term><function>builtins.toXML</function> <replaceable>e</replaceable></term>
 
     <listitem><para>Return a string containing an XML representation
@@ -736,7 +1012,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
@@ -763,15 +1039,15 @@ in foo</programlisting>
 
     <example xml:id='ex-toxml'><title>Passing information to a builder
     using <function>toXML</function></title>
-    
+
 <programlisting><![CDATA[
-{stdenv, fetchurl, libxslt, jira, uberwiki}:
+{ stdenv, fetchurl, libxslt, jira, uberwiki }:
 
 stdenv.mkDerivation (rec {
   name = "web-server";
 
-  buildInputs = [libxslt];
-  
+  buildInputs = [ libxslt ];
+
   builder = builtins.toFile "builder.sh" "
     source $stdenv/setup
     mkdir $out
@@ -804,7 +1080,7 @@ stdenv.mkDerivation (rec {
 
     <example xml:id='ex-toxml-result'><title>XML representation produced by
     <function>toXML</function></title>
-    
+
 <programlisting><![CDATA[<?xml version='1.0' encoding='utf-8'?>
 <expr>
   <list>
@@ -833,7 +1109,7 @@ stdenv.mkDerivation (rec {
 
   </varlistentry>
 
-  
+
   <varlistentry><term><function>builtins.trace</function>
   <replaceable>e1</replaceable> <replaceable>e2</replaceable></term>
 
@@ -844,7 +1120,20 @@ stdenv.mkDerivation (rec {
 
   </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> or
+    <literal>"lambda"</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>"powerpc-darwin"</literal><footnote><para>To figure out
+  your platform identifier, look at the line <quote>Checking for the
+  canonical Nix system name</quote> in the output of Nix's
+  <filename>configure</filename> script.</para></footnote> The build
+  can only be performed on a machine and operating system matching the
+  platform identifier.  (Nix can automatically forward builds for
+  other platforms by forwarding them to other machines; see <xref
+  linkend='chap-distributed-builds' />.)</para></listitem>
+
+  <listitem><para>There must be an attribute named
+  <varname>name</varname> whose value must be a string.  This is used
+  as a symbolic name for the package by <command>nix-env</command>,
+  and it is appended to the output paths of the
+  derivation.</para></listitem>
+
+  <listitem><para>There must be an attribute named
+  <varname>builder</varname> that identifies the program that is
+  executed to perform the build.  It can be either a derivation or a
+  source (a local file reference, e.g.,
+  <filename>./builder.sh</filename>).</para></listitem>
+
+  <listitem><para>Every attribute is passed as an environment variable
+  to the builder.  Attribute values are translated to environment
+  variables as follows:
+
+    <itemizedlist>
+
+      <listitem><para>Strings and integers are just passed
+      verbatim.</para></listitem>
+
+      <listitem><para>A <emphasis>path</emphasis> (e.g.,
+      <filename>../foo/sources.tar</filename>) causes the referenced
+      file to be copied to the store; its location in the store is put
+      in the environment variable.  The idea is that all sources
+      should reside in the Nix store, since all inputs to a derivation
+      should reside in the Nix store.</para></listitem>
+
+      <listitem><para>A <emphasis>derivation</emphasis> causes that
+      derivation to be built prior to the present derivation; its
+      default output path is put in the environment
+      variable.</para></listitem>
+
+      <listitem><para>Lists of the previous types are also allowed.
+      They are simply concatenated, separated by
+      spaces.</para></listitem>
+
+      <listitem><para><literal>true</literal> is passed as the string
+      <literal>1</literal>, <literal>false</literal> and
+      <literal>null</literal> are passed as an empty string.
+      </para></listitem>
+    </itemizedlist>
+
+  </para></listitem>
+
+  <listitem><para>The optional attribute <varname>args</varname>
+  specifies command-line arguments to be passed to the builder.  It
+  should be a list.</para></listitem>
+
+  <listitem><para>The optional attribute <varname>outputs</varname>
+  specifies a list of symbolic outputs of the derivation.  By default,
+  a derivation produces a single output path, denoted as
+  <literal>out</literal>.  However, derivations can produce multiple
+  output paths.  This is useful because it allows outputs to be
+  downloaded or garbage-collected separately.  For instance, imagine a
+  library package that provides a dynamic library, header files, and
+  documentation.  A program that links against the library doesn’t
+  need the header files and documentation at runtime, and it doesn’t
+  need the documentation at build time.  Thus, the library package
+  could specify:
+<programlisting>
+outputs = [ "lib" "headers" "doc" ];
+</programlisting>
+  This will cause Nix to pass environment variables
+  <literal>lib</literal>, <literal>headers</literal> and
+  <literal>doc</literal> to the builder containing the intended store
+  paths of each output.  The builder would typically do something like
+<programlisting>
+./configure --libdir=$lib/lib --includedir=$headers/include --docdir=$doc/share/doc
+</programlisting>
+  for an Autoconf-style package.  You can refer to each output of a
+  derivation by selecting it as an attribute, e.g.
+<programlisting>
+buildInputs = [ pkg.lib pkg.headers ];
+</programlisting>
+  The first element of <varname>output</varname> determines the
+  <emphasis>default output</emphasis>.  Thus, you could also write
+<programlisting>
+buildInputs = [ pkg pkg.headers ];
+</programlisting>
+  since <literal>pkg</literal> is equivalent to
+  <literal>pkg.lib</literal>.</para></listitem>
+
+</itemizedlist>
+
+<para>The function <function>mkDerivation</function> in the 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;
+    md5 = "70c9ccf9fac07f762c24f2df2290784d";
+  };
+  inherit perl; <co xml:id='ex-hello-nix-co-6' />
+}</programlisting>
+</example>
+
+<para><xref linkend='ex-hello-nix' /> shows a Nix expression for GNU
+Hello.  It's actually already in the Nix Packages collection in
+<filename>pkgs/applications/misc/hello/ex-1/default.nix</filename>.
+It is customary to place each package in a separate directory and call
+the single Nix expression in that directory
+<filename>default.nix</filename>.  The file has the following elements
+(referenced from the figure by number):
+
+<calloutlist>
+
+  <callout arearefs='ex-hello-nix-co-1'>
+
+    <para>This states that the expression is a
+    <emphasis>function</emphasis> that expects to be called with three
+    arguments: <varname>stdenv</varname>, <varname>fetchurl</varname>,
+    and <varname>perl</varname>.  They are needed to build Hello, but
+    we don't know how to build them here; that's why they are function
+    arguments.  <varname>stdenv</varname> is a package that is used
+    by almost all Nix Packages packages; it provides a
+    <quote>standard</quote> environment consisting of the things you
+    would expect in a basic Unix environment: a C/C++ compiler (GCC,
+    to be precise), the Bash shell, fundamental Unix tools such as
+    <command>cp</command>, <command>grep</command>,
+    <command>tar</command>, etc.  <varname>fetchurl</varname> is a
+    function that downloads files.  <varname>perl</varname> is the
+    Perl interpreter.</para>
+
+    <para>Nix functions generally have the form <literal>{ x, y, ...,
+    z }: e</literal> where <varname>x</varname>, <varname>y</varname>,
+    etc. are the names of the expected arguments, and where
+    <replaceable>e</replaceable> is the body of the function.  So
+    here, the entire remainder of the file is the body of the
+    function; when given the required arguments, the body should
+    describe how to build an instance of the Hello package.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-nix-co-2'>
+
+    <para>So we have to build a package.  Building something from
+    other stuff is called a <emphasis>derivation</emphasis> in Nix (as
+    opposed to sources, which are built by humans instead of
+    computers).  We perform a derivation by calling
+    <varname>stdenv.mkDerivation</varname>.
+    <varname>mkDerivation</varname> is a function provided by
+    <varname>stdenv</varname> that builds a package from a set of
+    <emphasis>attributes</emphasis>.  A set is just a list of
+    key/value pairs where each key is a string and each value is an
+    arbitrary Nix expression.  They take the general form <literal>{
+    <replaceable>name1</replaceable> =
+    <replaceable>expr1</replaceable>; <replaceable>...</replaceable>
+    <replaceable>nameN</replaceable> =
+    <replaceable>exprN</replaceable>; }</literal>.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-nix-co-3'>
+
+    <para>The attribute <varname>name</varname> specifies the symbolic
+    name and version of the package.  Nix doesn't really care about
+    these things, but they are used by for instance <command>nix-env
+    -q</command> to show a <quote>human-readable</quote> name for
+    packages.  This attribute is required by
+    <varname>mkDerivation</varname>.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-nix-co-4'>
+
+    <para>The attribute <varname>builder</varname> specifies the
+    builder.  This attribute can sometimes be omitted, in which case
+    <varname>mkDerivation</varname> will fill in a default builder
+    (which does a <literal>configure; make; make install</literal>, in
+    essence).  Hello is sufficiently simple that the default builder
+    would suffice, but in this case, we will show an actual builder
+    for educational purposes.  The value
+    <command>./builder.sh</command> refers to the shell script shown
+    in <xref linkend='ex-hello-builder' />, discussed below.</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-nix-co-5'>
+
+    <para>The builder has to know what the sources of the package
+    are.  Here, the attribute <varname>src</varname> is bound to the
+    result of a call to the <command>fetchurl</command> function.
+    Given a URL and an MD5 hash of the expected contents of the file
+    at that URL, this function builds a derivation that downloads the
+    file and checks its hash.  So the sources are a dependency that
+    like all other dependencies is built before Hello itself is
+    built.</para>
+
+    <para>Instead of <varname>src</varname> any other name could have
+    been used, and in fact there can be any number of sources (bound
+    to different attributes).  However, <varname>src</varname> is
+    customary, and it's also expected by the default builder (which we
+    don't use in this example).</para>
+
+  </callout>
+
+  <callout arearefs='ex-hello-nix-co-6'>
+
+    <para>Since the derivation requires Perl, we have to pass the
+    value of the <varname>perl</varname> function argument to the
+    builder.  All attributes in the set are actually passed as
+    environment variables to the builder, so declaring an attribute
+
+    <programlisting>
+perl = perl;</programlisting>
+
+    will do the trick: it binds an attribute <varname>perl</varname>
+    to the function argument which also happens to be called
+    <varname>perl</varname>.  However, it looks a bit silly, so there
+    is a shorter syntax.  The <literal>inherit</literal> keyword
+    causes the specified attributes to be bound to whatever variables
+    with the same name happen to be in scope.</para>
+
+  </callout>
+
+</calloutlist>
+
+</para>
+
+</section>

doc/manual/expressions/generic-builder.xml

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

doc/manual/expressions/language-operators.xml

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

doc/manual/expressions/language-values.xml

@@ -0,0 +1,278 @@
+<section xmlns="http://docbook.org/ns/docbook"
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xmlns:xi="http://www.w3.org/2001/XInclude"
+      version="5.0"
+      xml:id='ssec-values'>
+
+<title>Values</title>
+
+
+<simplesect><title>Simple Values</title>
+
+<para>Nix has the following basic data types:
+
+<itemizedlist>
+
+  <listitem>
+
+    <para><emphasis>Strings</emphasis> can be written in three
+    ways.</para>
+
+    <para>The most common way is to enclose the string between double
+    quotes, e.g., <literal>"foo bar"</literal>.  Strings can span
+    multiple lines.  The special characters <literal>"</literal> and
+    <literal>\</literal> and the character sequence
+    <literal>${</literal> must be escaped by prefixing them with a
+    backslash (<literal>\</literal>).  Newlines, carriage returns and
+    tabs can be written as <literal>\n</literal>,
+    <literal>\r</literal> and <literal>\t</literal>,
+    respectively.</para>
+
+    <para>You can include the result of an expression into a string by
+    enclosing it in
+    <literal>${<replaceable>...</replaceable>}</literal>, a feature
+    known as <emphasis>antiquotation</emphasis>.  The enclosed
+    expression must evaluate to something that can be coerced into a
+    string (meaning that it must be a string, a path, or a
+    derivation).  For instance, rather than writing
+
+<programlisting>
+"--with-freetype2-library=" + freetype + "/lib"</programlisting>
+
+    (where <varname>freetype</varname> is a derivation), you can
+    instead write the more natural
+
+<programlisting>
+"--with-freetype2-library=${freetype}/lib"</programlisting>
+
+    The latter is automatically translated to the former.  A more
+    complicated example (from the Nix expression for <link
+    xlink:href='http://www.trolltech.com/products/qt'>Qt</link>):
+
+<programlisting>
+configureFlags = "
+  -system-zlib -system-libpng -system-libjpeg
+  ${if openglSupport then "-dlopen-opengl
+    -L${mesa}/lib -I${mesa}/include
+    -L${libXmu}/lib -I${libXmu}/include" else ""}
+  ${if threadSupport then "-thread" else "-no-thread"}
+";</programlisting>
+
+    Note that Nix expressions and strings can be arbitrarily nested;
+    in this case the outer string contains various antiquotations that
+    themselves contain strings (e.g., <literal>"-thread"</literal>),
+    some of which in turn contain expressions (e.g.,
+    <literal>${mesa}</literal>).</para>
+
+    <para>The second way to write string literals is as an
+    <emphasis>indented string</emphasis>, which is enclosed between
+    pairs of <emphasis>double single-quotes</emphasis>, like so:
+
+<programlisting>
+''
+  This is the first line.
+  This is the second line.
+    This is the third line.
+''</programlisting>
+
+    This kind of string literal intelligently strips indentation from
+    the start of each line.  To be precise, it strips from each line a
+    number of spaces equal to the minimal indentation of the string as
+    a whole (disregarding the indentation of empty lines).  For
+    instance, the first and second line are indented two space, while
+    the third line is indented four spaces.  Thus, two spaces are
+    stripped from each line, so the resulting string is
+
+<programlisting>
+"This is the first line.\nThis is the second line.\n  This is the third line.\n"</programlisting>
+
+    </para>
+
+    <para>Note that the whitespace and newline following the opening
+    <literal>''</literal> is ignored if there is no non-whitespace
+    text on the initial line.</para>
+
+    <para>Antiquotation
+    (<literal>${<replaceable>expr</replaceable>}</literal>) is
+    supported in indented strings.</para>
+
+    <para>Since <literal>${</literal> and <literal>''</literal> have
+    special meaning in indented strings, you need a way to quote them.
+    <literal>${</literal> can be escaped by prefixing it with
+    <literal>''</literal> (that is, two single quotes), i.e.,
+    <literal>''${</literal>.  <literal>''</literal> can be escaped by
+    prefixing it with <literal>'</literal>, i.e.,
+    <literal>'''</literal>.  Finally, linefeed, carriage-return and
+    tab characters can be written as <literal>''\n</literal>,
+    <literal>''\r</literal>, <literal>''\t</literal>.</para>
+
+    <para>Indented strings are primarily useful in that they allow
+    multi-line string literals to follow the indentation of the
+    enclosing Nix expression, and that less escaping is typically
+    necessary for strings representing languages such as shell scripts
+    and configuration files because <literal>''</literal> is much less
+    common than <literal>"</literal>.  Example:
+
+<programlisting>
+stdenv.mkDerivation {
+  <replaceable>...</replaceable>
+  postInstall =
+    ''
+      mkdir $out/bin $out/etc
+      cp foo $out/bin
+      echo "Hello World" > $out/etc/foo.conf
+      ${if enableBar then "cp bar $out/bin" else ""}
+    '';
+  <replaceable>...</replaceable>
+}
+</programlisting>
+
+    </para>
+
+    <para>Finally, as a convenience, <emphasis>URIs</emphasis> as
+    defined in appendix B of <link
+    xlink:href='http://www.ietf.org/rfc/rfc2396.txt'>RFC 2396</link>
+    can be written <emphasis>as is</emphasis>, without quotes.  For
+    instance, the string
+    <literal>"http://example.org/foo.tar.bz2"</literal>
+    can also be written as
+    <literal>http://example.org/foo.tar.bz2</literal>.</para>
+
+  </listitem>
+
+  <listitem><para><emphasis>Integers</emphasis>, e.g.,
+  <literal>123</literal>.</para></listitem>
+
+  <listitem><para><emphasis>Paths</emphasis>, e.g.,
+  <filename>/bin/sh</filename> or <filename>./builder.sh</filename>.
+  A path must contain at least one slash to be recognised as such; for
+  instance, <filename>builder.sh</filename> is not a
+  path<footnote><para>It's parsed as an expression that selects the
+  attribute <varname>sh</varname> from the variable
+  <varname>builder</varname>.</para></footnote>.  If the file name is
+  relative, i.e., if it does not begin with a slash, it is made
+  absolute at parse time relative to the directory of the Nix
+  expression that contained it.  For instance, if a Nix expression in
+  <filename>/foo/bar/bla.nix</filename> refers to
+  <filename>../xyzzy/fnord.nix</filename>, the absolute path is
+  <filename>/foo/xyzzy/fnord.nix</filename>.</para>
+
+  <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></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>
+
+
+</simplesect>
+
+
+</section>

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

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

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

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>
+$ ./dev-shell
+</screen>
+To build Nix itself in this shell:
+<screen>
+[nix-shell]$ ./bootstrap.sh
+[nix-shell]$ configurePhase
+[nix-shell]$ make
+</screen>
+To test it:
+<screen>
+[nix-shell]$ make install
+[nix-shell]$ make installcheck
+</screen>
+
+</para>
+
+</appendix>

doc/manual/installation.xml

@@ -1,482 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="chap-installation">
-
-<title>Installation</title>
-
-
-<section><title>Supported platforms</title>
-
-<para>Nix is currently supported on the following platforms:
-
-<itemizedlist>
-
-  <listitem><para>Linux (particularly on x86, x86_64, and
-  PowerPC).</para></listitem>
-
-  <listitem><para>Mac OS X, both on Intel and
-  PowerPC.</para></listitem>
-
-  <listitem><para>FreeBSD (only tested on Intel).</para></listitem>
-
-  <listitem><para>Windows through <link
-  xlink:href="http://www.cygwin.com/">Cygwin</link>.</para>
-
-  <warning><para>On Cygwin, Nix <emphasis>must</emphasis> be installed
-  on an NTFS partition.  It will not work correctly on a FAT
-  partition.</para></warning>
-
-  </listitem>
-
-</itemizedlist>
-
-</para>
-
-<para>Nix is pretty portable, so it should work on most other Unix
-platforms as well.</para>
-
-</section>
-
-
-<section><title>Obtaining Nix</title>
-
-<para>The easiest way to obtain Nix is to download a <link
-xlink:href="http://nixos.org/">source distribution</link>.  RPMs
-for Red Hat, SuSE, and Fedora Core are also available.</para>
-
-<para>Alternatively, the most recent sources of Nix can be obtained
-from its <link
-xlink:href="https://svn.nixos.org/repos/nix/nix/trunk">Subversion
-repository</link>.  For example, the following command will check out
-the latest revision into a directory called
-<filename>nix</filename>:</para>
-
-<screen>
-$ svn checkout https://svn.nixos.org/repos/nix/nix/trunk nix</screen>
-
-<para>Likewise, specific releases can be obtained from the <link
-xlink:href="https://svn.nixos.org/repos/nix/nix/tags">tags
-directory</link> of the repository.</para>
-
-</section>
-
-
-<section><title>Prerequisites</title>
-
-<para><emphasis>The following prerequisites only apply when you build
-from source</emphasis>.  Binary releases (e.g., RPMs) have no
-prerequisites.</para>
-
-<para>A fairly recent version of GCC/G++ is required.  Version 2.95
-and higher should work.</para>
-
-<para>To build this manual and the man-pages you need the
-<command>xmllint</command> and <command>xsltproc</command> programs,
-which are part of the <literal>libxml2</literal> and
-<literal>libxslt</literal> packages, respectively.  You also need the
-<link
-xlink:href="http://docbook.sourceforge.net/projects/xsl/">DocBook XSL
-stylesheets</link> and optionally the <link
-xlink:href="http://www.docbook.org/schemas/5x"> DocBook 5.0 RELAX NG
-schemas</link>.  Note that these are only required if you modify the
-manual sources or when you are building from the Subversion
-repository.</para>
-
-<para>To build the parser, very <emphasis>recent</emphasis> versions
-of Bison and Flex are required.  (This is because Nix needs GLR
-support in Bison and reentrancy support in Flex.)  For Bison, you need
-version 2.3 or higher (1.875 does <emphasis>not</emphasis> work),
-which can be obtained from
-the <link xlink:href="ftp://alpha.gnu.org/pub/gnu/bison">GNU FTP
-server</link>.  For Flex, you need version 2.5.33, which is available
-on <link xlink:href="http://lex.sourceforge.net/">SourceForge</link>.
-Slightly older versions may also work, but ancient versions like the
-ubiquitous 2.5.4a won't.  Note that these are only required if you
-modify the parser or when you are building from the Subversion
-repository.</para>
-
-<para>Nix uses the bzip2 compressor (including the bzip2 library).  It
-is included in the Nix source distribution.  If you build from the
-Subversion repository, you must download it yourself and place it in
-the <filename>externals/</filename> directory.  See
-<filename>externals/Makefile.am</filename> for the precise URLs of
-this packages.  Alternatively, if you already have it installed, you
-can use <command>configure</command>'s <option>--with-bzip2</option>
-options to point to their respective locations.</para>
-
-<para>Nix can optionally use the <link
-xlink:href="http://www.hpl.hp.com/personal/Hans_Boehm/gc/">Boehm
-garbage collector</link> to reduce the evaluator’s memory consumption.
-To enable it, install <literal>pkgconfig</literal> and the Boehm
-garbage collector, and pass the flag <option>--enable-gc</option> to
-<command>configure</command>.</para>
-
-</section>
-
-
-<section><title>Building Nix from source</title>
-
-<para>After unpacking or checking out the Nix sources, issue the
-following commands:
-
-<screen>
-$ ./configure <replaceable>options...</replaceable>
-$ make
-$ make install</screen>
-
-</para>
-
-<para>When building from the Subversion repository, these should be
-preceded by the command:
-
-<screen>
-$ ./bootstrap.sh</screen>
-
-</para>
-
-<para>The installation path can be specified by passing the
-<option>--prefix=<replaceable>prefix</replaceable></option> to
-<command>configure</command>.  The default installation directory is
-<filename>/usr/local</filename>.  You can change this to any location
-you like.  You must have write permission to the
-<replaceable>prefix</replaceable> path.</para>
-
-<para>Nix keeps its <emphasis>store</emphasis> (the place where
-packages are stored) in <filename>/nix/store</filename> by default.
-This can be changed using
-<option>--with-store-dir=<replaceable>path</replaceable></option>.</para>
-
-<warning><para>It is best <emphasis>not</emphasis> to change the Nix
-store from its default, since doing so makes it impossible to use
-pre-built binaries from the standard Nixpkgs channels — that is, all
-packages will need to be built from source.</para></warning>
-
-<para>Nix keeps state (such as its database and log files) in
-<filename>/nix/var</filename> by default.  This can be changed using
-<option>--localstatedir=<replaceable>path</replaceable></option>.</para>
-
-<para>If you want to rebuild the documentation, pass the full path to
-the DocBook RELAX NG schemas and to the DocBook XSL stylesheets using
-the
-<option>--with-docbook-rng=<replaceable>path</replaceable></option>
-and
-<option>--with-docbook-xsl=<replaceable>path</replaceable></option>
-options.</para>
-
-</section>
-
-
-<section><title>Installing a binary distribution</title>
-
-<para>RPM and Deb packages of Nix for a number of different versions
-of Fedora, openSUSE, Debian and Ubuntu can be downloaded from <link
-xlink:href="http://nixos.org/" />.  Once downloaded, the RPMs can be
-installed or upgraded using <command>rpm -U</command>.  For example,
-
-<screen>
-$ rpm -U nix-0.13pre18104-1.i386.rpm</screen>
-
-Likewise, for a Deb package:
-
-<screen>
-$ dpkg -i nix_0.13pre18104-1_amd64.deb</screen>
-
-</para>
-
-<para>Nix can be uninstalled using <command>rpm -e nix</command> or
-<command>dpkg -r nix</command>.  After this you should manually remove
-the Nix store and other auxiliary data, if desired:
-
-<screen>
-$ rm -rf /nix/store
-$ rm -rf /nix/var</screen>
-
-</para>
-
-</section>
-
-
-<!-- TODO: should be updated
-<section><title>Upgrading Nix through Nix</title>
-
-<para>You can install the latest stable version of Nix through Nix
-itself by subscribing to the channel <link
-xlink:href="http://nixos.org/releases/nix/channels/nix-stable" />,
-or the latest unstable version by subscribing to the channel <link
-xlink:href="http://nixos.org/releases/nix/channels/nix-unstable" />.
-You can also do a <link linkend="sec-one-click">one-click
-installation</link> by clicking on the package links at <link
-xlink:href="http://nixos.org/releases/full-index-nix.html" />.</para>
-
-</section>
--->
-
-
-<section><title>Security</title>
-
-<para>Nix has two basic security models.  First, it can be used in
-“single-user mode”, which is similar to what most other package
-management tools do: there is a single user (typically <systemitem
-class="username">root</systemitem>) who performs all package
-management operations.  All other users can then use the installed
-packages, but they cannot perform package management operations
-themselves.</para>
-
-<para>Alternatively, you can configure Nix in “multi-user mode”.  In
-this model, all users can perform package management operations — for
-instance, every user can install software without requiring root
-privileges.  Nix ensures that this is secure.  For instance, it’s not
-possible for one user to overwrite a package used by another user with
-a Trojan horse.</para>
-
-
-<section><title>Single-user mode</title>
-  
-<para>In single-user mode, all Nix operations that access the database
-in <filename><replaceable>prefix</replaceable>/var/nix/db</filename>
-or modify the Nix store in
-<filename><replaceable>prefix</replaceable>/store</filename> must be
-performed under the user ID that owns those directories.  This is
-typically <systemitem class="username">root</systemitem>.  (If you
-install from RPM packages, that’s in fact the default ownership.)
-However, on single-user machines, it is often convenient to
-<command>chown</command> those directories to your normal user account
-so that you don’t have to <command>su</command> to <systemitem
-class="username">root</systemitem> all the time.</para>
-
-</section>
-
-
-<section xml:id="ssec-multi-user"><title>Multi-user mode</title>
-
-<para>To allow a Nix store to be shared safely among multiple users,
-it is important that users are not able to run builders that modify
-the Nix store or database in arbitrary ways, or that interfere with
-builds started by other users.  If they could do so, they could
-install a Trojan horse in some package and compromise the accounts of
-other users.</para>
-
-<para>To prevent this, the Nix store and database are owned by some
-privileged user (usually <literal>root</literal>) and builders are
-executed under special user accounts (usually named
-<literal>nixbld1</literal>, <literal>nixbld2</literal>, etc.).  When a
-unprivileged user runs a Nix command, actions that operate on the Nix
-store (such as builds) are forwarded to a <emphasis>Nix
-daemon</emphasis> running under the owner of the Nix store/database
-that performs the operation.</para>
-
-<note><para>Multi-user mode has one important limitation: only
-<systemitem class="username">root</systemitem> can run <command
-linkend="sec-nix-pull">nix-pull</command> to register the availability
-of pre-built binaries.  However, those registrations are shared by all
-users, so they still get the benefit from <command>nix-pull</command>s
-done by <systemitem class="username">root</systemitem>.</para></note>
-
-
-<section><title>Setting up the build users</title>
-
-<para>The <emphasis>build users</emphasis> are the special UIDs under
-which builds are performed.  They should all be members of the
-<emphasis>build users group</emphasis> (usually called
-<literal>nixbld</literal>).  This group should have no other members.
-The build users should not be members of any other group.</para>
-
-<para>Here is a typical <filename>/etc/group</filename> definition of
-the build users group with 10 build users:
-
-<programlisting>
-nixbld:!:30000:nixbld1,nixbld2,nixbld3,nixbld4,nixbld5,nixbld6,nixbld7,nixbld8,nixbld9,nixbld10
-</programlisting>
-
-In this example the <literal>nixbld</literal> group has UID 30000, but
-of course it can be anything that doesn’t collide with an existing
-group.</para>
-
-<para>Here is the corresponding part of
-<filename>/etc/passwd</filename>:
-
-<programlisting>
-nixbld1:x:30001:65534:Nix build user 1:/var/empty:/noshell
-nixbld2:x:30002:65534:Nix build user 2:/var/empty:/noshell
-nixbld3:x:30003:65534:Nix build user 3:/var/empty:/noshell
-...
-nixbld10:x:30010:65534:Nix build user 10:/var/empty:/noshell
-</programlisting>
-
-The home directory of the build users should not exist or should be an
-empty directory to which they do not have write access.</para>
-
-<para>The build users should have write access to the Nix store, but
-they should not have the right to delete files.  Thus the Nix store’s
-group should be the build users group, and it should have the sticky
-bit turned on (like <filename>/tmp</filename>):
-
-<screen>
-$ chgrp nixbld /nix/store
-$ chmod 1777 /nix/store
-</screen>
-
-</para>
-
-<para>Finally, you should tell Nix to use the build users by
-specifying the build users group in the <link
-linkend="conf-build-users-group"><literal>build-users-group</literal>
-option</link> in the <link linkend="sec-conf-file">Nix configuration
-file</link> (<literal>/nix/etc/nix/nix.conf</literal>):
-
-<programlisting>
-build-users-group = nixbld
-</programlisting>
-
-</para>
-
-</section>
-
-
-<section><title>Nix store/database owned by root</title>
-
-<para>The simplest setup is to let <literal>root</literal> own the Nix
-store and database.  I.e.,
-
-<screen>
-$ chown -R root /nix/store /nix/var/nix</screen>
-
-</para>
-
-<para>The <link linkend="sec-nix-worker">Nix daemon</link> should be
-started as follows (as <literal>root</literal>):
-
-<screen>
-$ nix-worker --daemon</screen>
-
-You’ll want to put that line somewhere in your system’s boot
-scripts.</para>
-
-<para>To let unprivileged users use the daemon, they should set the
-<link linkend="envar-remote"><envar>NIX_REMOTE</envar> environment
-variable</link> to <literal>daemon</literal>.  So you should put a
-line like
-
-<programlisting>
-export NIX_REMOTE=daemon</programlisting>
-
-into the users’ login scripts.</para>
-
-</section>
-
-
-<section><title>Nix store/database not owned by root</title>
-
-<para>It is also possible to let the Nix store and database be owned
-by a non-root user, which should be more secure<footnote><para>Note
-however that even when the Nix daemon runs as root, not
-<emphasis>that</emphasis> much code is executed as root: Nix
-expression evaluation is performed by the calling (unprivileged) user,
-and builds are performed under the special build user accounts.  So
-only the code that accesses the database and starts builds is executed
-as <literal>root</literal>.</para></footnote>.  Typically, this user
-is a special account called <literal>nix</literal>, but it can be
-named anything.  It should own the Nix store and database:
-
-<screen>
-$ chown -R root /nix/store /nix/var/nix</screen>
-
-and of course <command>nix-worker --daemon</command> should be started
-under that user, e.g.,
-
-<screen>
-$ su - nix -c "exec /nix/bin/nix-worker --daemon"</screen>
-
-</para>
-
-<para>There is a catch, though: non-<literal>root</literal> users
-cannot start builds under the build user accounts, since the
-<function>setuid</function> system call is obviously privileged.  To
-allow a non-<literal>root</literal> Nix daemon to use the build user
-feature, it calls a setuid-root helper program,
-<command>nix-setuid-helper</command>.  This program is installed in
-<filename><replaceable>prefix</replaceable>/libexec/nix-setuid-helper</filename>.
-To set the permissions properly (Nix’s <command>make install</command>
-doesn’t do this, since we don’t want to ship setuid-root programs
-out-of-the-box):
-
-<screen>
-$ chown root.root /nix/libexec/nix-setuid-helper
-$ chmod 4755 /nix/libexec/nix-setuid-helper
-</screen>
-
-(This example assumes that the Nix binaries are installed in
-<filename>/nix</filename>.)</para>
-
-<para>Of course, the <command>nix-setuid-helper</command> command
-should not be usable by just anybody, since then anybody could run
-commands under the Nix build user accounts.  For that reason there is
-a configuration file <filename>/etc/nix-setuid.conf</filename> that
-restricts the use of the helper.  This file should be a text file
-containing precisely two lines, the first being the Nix daemon user
-and the second being the build users group, e.g.,
-
-<programlisting>
-nix
-nixbld
-</programlisting>
-
-The setuid-helper barfs if it is called by a user other than the one
-specified on the first line, or if it is asked to execute a build
-under a user who is not a member of the group specified on the second
-line.  The file <filename>/etc/nix-setuid.conf</filename> must be
-owned by root, and must not be group- or world-writable.  The
-setuid-helper barfs if this is not the case.</para>
-
-</section>
-
-
-<section><title>Restricting access</title>
-
-<para>To limit which users can perform Nix operations, you can use the
-permissions on the directory
-<filename>/nix/var/nix/daemon-socket</filename>.  For instance, if you
-want to restrict the use of Nix to the members of a group called
-<literal>nix-users</literal>, do
-
-<screen>
-$ chgrp nix-users /nix/var/nix/daemon-socket
-$ chmod ug=rwx,o= /nix/var/nix/daemon-socket
-</screen>
-
-This way, users who are not in the <literal>nix-users</literal> group
-cannot connect to the Unix domain socket
-<filename>/nix/var/nix/daemon-socket/socket</filename>, so they cannot
-perform Nix operations.</para>
-
-</section>
-
-
-</section> <!-- end of multi-user -->
-
-
-</section> <!-- end of security -->
-
-
-<section><title>Using Nix</title>
-
-<para>To use Nix, some environment variables should be set.  In
-particular, <envar>PATH</envar> should contain the directories
-<filename><replaceable>prefix</replaceable>/bin</filename> and
-<filename>~/.nix-profile/bin</filename>.  The first directory contains
-the Nix tools themselves, while <filename>~/.nix-profile</filename> is
-a symbolic link to the current <emphasis>user environment</emphasis>
-(an automatically generated package consisting of symlinks to
-installed packages).  The simplest way to set the required environment
-variables is to include the file
-<filename><replaceable>prefix</replaceable>/etc/profile.d/nix.sh</filename>
-in your <filename>~/.bashrc</filename> (or similar), like this:</para>
-
-<screen>
-source <replaceable>prefix</replaceable>/etc/profile.d/nix.sh</screen>
-
-</section>
-
-
-</chapter>

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>