* Sync with thesis: do not include store location in the hash

computation (in the intensional model).

AUTHORS

@@ -0,0 +1,8 @@
+The following people contributed to Nix, in alphabetical order:
+
+Martin Bravenboer
+Eelco Dolstra
+Niels Janssen
+Armijn Hemel
+Rob Vermaas
+Eelco Visser

Makefile.am

@@ -1,3 +1,47 @@
-SUBDIRS = externals src scripts corepkgs doc
+SUBDIRS = externals src scripts corepkgs doc misc tests
+EXTRA_DIST = substitute.mk nix.spec nix.spec.in bootstrap.sh \
+  svn-revision nix.conf.example
 
-EXTRA_DIST = boost/*.hpp boost/format/*.hpp substitute.mk
+include ./substitute.mk
+
+nix.spec: nix.spec.in
+
+rpm: nix.spec dist
+	rpm $(EXTRA_RPM_FLAGS) -ta $(distdir).tar.gz
+
+relname:
+	echo -n $(distdir) > relname
+
+install-data-local: init-state
+	$(INSTALL) -d $(DESTDIR)$(sysconfdir)/nix
+	$(INSTALL_DATA) nix.conf.example $(DESTDIR)$(sysconfdir)/nix
+	if ! test -e $(DESTDIR)$(sysconfdir)/nix/nix.conf; then \
+		$(INSTALL_DATA) nix.conf.example $(DESTDIR)$(sysconfdir)/nix/nix.conf; \
+	fi
+
+if INIT_STATE
+if SETUID_HACK
+INIT_FLAGS = -g @NIX_GROUP@ -o @NIX_USER@
+GROUP_WRITABLE = -m 775
+endif
+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
+	$(INSTALL) $(INIT_FLAGS) $(GROUP_WRITABLE) -d $(DESTDIR)$(localstatedir)/nix/gcroots/tmp
+	$(INSTALL) $(INIT_FLAGS) $(GROUP_WRITABLE) -d $(DESTDIR)$(localstatedir)/nix/gcroots/channels
+	rm -f $(DESTDIR)$(localstatedir)/nix/gcroots/profiles
+	ln -s $(localstatedir)/nix/profiles $(DESTDIR)$(localstatedir)/nix/gcroots/profiles
+	$(INSTALL) $(INIT_FLAGS) -d $(DESTDIR)$(prefix)/store
+	$(INSTALL) $(INIT_FLAGS) $(GROUP_WRITABLE) -d $(DESTDIR)$(localstatedir)/nix/manifests
+#	$(bindir)/nix-store --init
+else
+init-state:
+endif
+
+svn-revision:
+	svnversion . > svn-revision

NEWS

@@ -0,0 +1,261 @@
+Version 0.9
+
+* Unpacking of patch sequences is much faster now by not doing
+  redundant unpacking and repacking of intermediate paths.
+
+
+Version 0.8 (April 11, 2005)
+
+NOTE: the hashing scheme in Nix 0.8 changed (as detailed below).  As a
+result, `nix-pull' manifests and channels built for Nix 0.7 and below
+will now work anymore.  However, the Nix expression language has not
+changed, so you can still build from source.  Also, existing user
+environments continue to work.  Nix 0.8 will automatically upgrade the
+database schema of previous installations when it is first run.
+
+If you get the error message
+
+  you have an old-style manifest `/nix/var/nix/manifests/[...]';
+  please delete it
+
+you should delete previously downloaded manifests:
+
+  $ rm /nix/var/nix/manifests/*
+
+If `nix-channel' gives the error message
+
+  manifest `http://catamaran.labs.cs.uu.nl/dist/nix/channels/[channel]/MANIFEST'
+  is too old (i.e., for Nix <= 0.7)
+
+then you should unsubscribe from the offending channel (`nix-channel
+--remove URL'; leave out `/MANIFEST'), and subscribe to the same URL,
+with `channels' replaced by `channels-v3' (e.g.,
+http://catamaran.labs.cs.uu.nl/dist/nix/channels-v3/nixpkgs-unstable).
+
+Nix 0.8 has the following improvements:
+
+* The cryptographic hashes used in store paths are now 160 bits long,
+  but encoded in base-32 so that they are still only 32 characters
+  long (e.g., /nix/store/csw87wag8bqlqk7ipllbwypb14xainap-atk-1.9.0).
+  (This is actually a 160 bit truncation of a SHA-256 hash.)
+
+* Big cleanups and simplifications of the basic store semantics.  The
+  notion of "closure store expressions" is gone (and so is the notion
+  of "successors"); the file system references of a store path are now
+  just stored in the database.
+
+  For instance, given any store path, you can query its closure:
+
+    $ nix-store -qR $(which firefox)
+    ... lots of paths ...
+
+  Also, Nix now remembers for each store path the derivation that
+  built it (the "deriver"):
+
+    $ nix-store -qR $(which firefox)
+    /nix/store/4b0jx7vq80l9aqcnkszxhymsf1ffa5jd-firefox-1.0.1.drv
+
+  So to see the build-time dependencies, you can do
+  
+    $ nix-store -qR $(nix-store -qd $(which firefox))
+
+  or, in a nicer format:
+
+    $ nix-store -q --tree $(nix-store -qd $(which firefox))
+
+  File system references are also stored in reverse.  For instance,
+  you can query all paths that directly or indirectly use a certain
+  Glibc:
+
+    $ nix-store -q --referers-closure \
+        /nix/store/8lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4
+
+* The concept of fixed-output derivations has been formalised.
+  Previously, functions such as `fetchurl' in Nixpkgs used a hack
+  (namely, explicitly specifying a store path hash) to prevent changes
+  to, say, the URL of the file from propagating upwards through the
+  dependency graph, causing rebuilds of everything.  This can now be
+  done cleanly by specifying the `outputHash' and `outputHashAlgo'
+  attributes.  Nix itself checks that the content of the output has
+  the specified hash.  (This is important for maintaining certain
+  invariants necessary for future work on secure shared stores.)
+
+* One-click installation :-)  It is now possible to install any
+  top-level component in Nixpkgs directly, through the web - see,
+  e.g., http://catamaran.labs.cs.uu.nl/dist/nixpkgs-0.8/.  All you
+  have to do is associate `/nix/bin/nix-install-package' with the MIME
+  type `application/nix-package' (or the extension `.nixpkg'), and
+  clicking on a package link will cause it to be installed, with all
+  appropriate dependencies.  If you just want to install some specific
+  application, this is easier than subscribing to a channel.
+
+* `nix-store -r PATHS' now builds all the derivations PATHS in
+  parallel.  Previously it did them sequentially (though exploiting
+  possible parallelism between subderivations).  This is nice for
+  build farms.
+
+* `nix-channel' has new operations `--list' and `--remove'.
+
+* New ways of installing components into user environments:
+
+  - Copy from another user environment:
+
+      $ nix-env -i --from-profile .../other-profile firefox
+
+  - Install a store derivation directly (bypassing the Nix expression
+    language entirely):
+
+      $ nix-env -i /nix/store/z58v41v21xd3...-aterm-2.3.1.drv
+
+    (This is used to implement `nix-install-package', which is
+    therefore immune to evolution in the Nix expression language.)
+
+  - Install an already built store path directly:
+
+      $ nix-env -i /nix/store/hsyj5pbn0d9i...-aterm-2.3.1
+
+  - Install the result of a Nix expression specified as a command-line
+    argument:
+
+      $ nix-env -f .../i686-linux.nix -i -E 'x: x.firefoxWrapper'
+
+    The difference with the normal installation mode is that `-E' does
+    not use the `name' attributes of derivations.  Therefore, this can
+    be used to disambiguate multiple derivations with the same name.
+
+* A hash of the contents of a store path is now stored in the database
+  after a succesful build.  This allows you to check whether store
+  paths have been tampered with: `nix-store --verify --check-contents'.
+    
+* Implemented a concurrent garbage collector.  It is now always safe
+  to run the garbage collector, even if other Nix operations are
+  happening simultaneously.
+
+  However, there can still be GC races if you use `nix-instantiate'
+  and `nix-store -r' directly to build things.  To prevent races, use
+  the `--add-root' flag of those commands.
+
+* The garbage collector now finally deletes paths in the right order
+  (i.e., topologically sorted under the `references' relation), thus
+  making it safe to interrupt the collector without risking a store
+  that violates the closure invariant.
+
+* Likewise, the substitute mechanism now downloads files in the right
+  order, thus preserving the closure invariant at all times.
+
+* The result of `nix-build' is now registered as a root of the garbage
+  collector.  If the `./result' link is deleted, the GC root
+  disappears automatically.
+
+* The behaviour of the garbage collector can be changed globally by
+  setting options in `/nix/etc/nix/nix.conf'.
+
+  - `gc-keep-derivations' specifies whether deriver links should be
+    followed when searching for live paths.
+
+  - `gc-keep-outputs' specifies whether outputs of derivations should
+    be followed when searching for live paths.
+  
+  - `env-keep-derivations' specifies whether user environments should
+    store the paths of derivations when they are added (thus keeping
+    the derivations alive).
+
+* New `nix-env' query flags `--drv-path' and `--out-path'.
+
+* `fetchurl' allows SHA-1 and SHA-256 in addition to MD5.  Just
+  specify the attribute `sha1' or `sha256' instead of `md5'.
+
+* Manual updates.
+
+  
+Version 0.7 (January 12, 2005)
+
+* Binary patching.  When upgrading components using pre-built binaries
+  (through nix-pull / nix-channel), Nix can automatically download and
+  apply binary patches to already installed components instead of full
+  downloads.  Patching is "smart": if there is a *sequence* of patches
+  to an installed component, Nix will use it.  Patches are currently
+  generated automatically between Nixpkgs (pre-)releases.
+
+* Simplifications to the substitute mechanism.
+
+* Nix-pull now stores downloaded manifests in /nix/var/nix/manifests.
+
+* Metadata on files in the Nix store is canonicalised after builds:
+  the last-modified timestamp is set to 0 (00:00:00 1/1/1970), the
+  mode is set to 0444 or 0555 (readable and possibly executable by
+  all; setuid/setgid bits are dropped), and the group is set to the
+  default.  This ensures that the result of a build and an
+  installation through a substitute is the same; and that timestamp
+  dependencies are revealed.
+
+
+Version 0.6 (November 14, 2004)
+
+Major changes include the following:
+
+* Rewrite of the normalisation engine.
+
+  * Multiple builds can now be performed in parallel (option `-j').
+
+  * Distributed builds.  Nix can now call a shell script to forward
+    builds to Nix installations on remote machines, which may or may
+    not be of the same platform type.
+
+  * Option `--fallback' allows recovery from broken substitutes.
+
+  * Option `--keep-going' causes building of other (unaffected)
+    derivations to continue if one failed.
+    
+* Improvements to the garbage collector (i.e., it should actually work
+  now).
+
+* Setuid Nix installations allow a Nix store to be shared among
+  multiple users.
+
+* Substitute registration is much faster now.
+
+* A utility `nix-build' to build a Nix expression and create a symlink
+  to the result int the current directory; useful for testing Nix
+  derivations.
+
+* Manual updates.
+
+* `nix-env' changes:
+
+  * Derivations for other platforms are filtered out (which can be
+    overriden using `--system-filter').
+
+  * `--install' by default now uninstall previous derivations with the
+    same name.
+
+  * `--upgrade' allows upgrading to a specific version.
+
+  * New operation `--delete-generations' to remove profile
+    generations (necessary for effective garbage collection).
+
+  * Nicer output (sorted, columnised).
+
+* More sensible verbosity levels all around (builder output is now
+  shown always, unless `-Q' is given).
+
+* Nix expression language changes:
+
+  * New language construct: `with E1; E2' brings all attributes
+    defined in the attribute set E1 in scope in E2.
+
+  * Added a `map' function.
+
+  * Various new operators (e.g., string concatenation).
+
+* Expression evaluation is much faster.
+
+* An Emacs mode for editing Nix expressions (with syntax highlighting
+  and indentation) has been added.
+
+* Many bug fixes.
+
+
+Version 0.5 and earlier
+
+Please refer to the Subversion commit log messages.

README

@@ -1,36 +1,9 @@
-Overview
-========
-
-Nix is a package manager, deployment system, and component glue
-mechanism.
+For installation and usage instructions, please read the manual, which
+can be found in `docs/manual/manual.html', and additionally at the Nix
+website at <http://www.cs.uu.nl/groups/ST/Trace/Nix>.
 
 
-Prerequisites
-=============
+Acknowledgments
 
-* Berkeley DB 4.0.14
-* CWI ATerm 2.0
-
-
-Installation
-============
-
-* When building from the Subversion repository, first do:
-
-    autoreconf -i
-
-* To build, do:
-
-    ./configure
-    make
-    make install
-
-  Note that this will install to /nix, which is the default prefix.
-  You can specify another prefix, but this is not recommended if you
-  want to use prebuilt packages from other sources.
-
-
-Usage
-=====
-
-TODO
+This product includes software developed by the OpenSSL Project for
+use in the OpenSSL Toolkit (http://www.OpenSSL.org/)

blacklisting/check-env.pl

@@ -0,0 +1,252 @@
+#! /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

@@ -0,0 +1,5 @@
+#! /bin/sh -e
+aclocal
+autoheader
+automake --add-missing --copy
+autoconf

configure.ac

@@ -1,23 +1,206 @@
-AC_INIT(nix, 0.3)
-AC_CONFIG_SRCDIR(src/nix.cc)
+AC_INIT(nix, "0.9")
+AC_CONFIG_SRCDIR(README)
 AC_CONFIG_AUX_DIR(config)
-AM_INIT_AUTOMAKE
+AM_INIT_AUTOMAKE([dist-bzip2])
+
+# Change to `1' to produce a `stable' release (i.e., the `preREVISION'
+# suffix is not added).
+STABLE=0
+
+# Put the revision number in the version.
+if test "$STABLE" != "1"; then
+    if REVISION=`test -d $srcdir/.svn && svnversion $srcdir 2> /dev/null`; then
+        VERSION="${VERSION}pre${REVISION}"
+    elif REVISION=`cat $srcdir/svn-revision 2> /dev/null`; then
+        VERSION="${VERSION}pre${REVISION}"
+    fi
+fi
 
 AC_PREFIX_DEFAULT(/nix)
 
 AC_CANONICAL_HOST
 
+# Construct a Nix system name (like "i686-linux").
+AC_MSG_CHECKING([for the canonical Nix system name])
+cpu_name=$(uname -p | tr 'A-Z ' 'a-z_')
+machine_name=$(uname -m | tr 'A-Z ' 'a-z_')
+
+case $machine_name in
+    i*86)
+        machine_name=i686
+        ;;
+    *)
+        if test "$cpu_name" != "unknown"; then
+            machine_name=$cpu_name
+        fi
+        ;;
+esac
+
+sys_name=$(uname -s | tr 'A-Z ' 'a-z_')
+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')])
+
 AC_PROG_CC
 AC_PROG_CXX
 AC_PROG_RANLIB
 
-AC_PATH_PROG(wget, wget)
+# Check for pubsetbuf.
+AC_MSG_CHECKING([for pubsetbuf])
+AC_LANG_PUSH(C++)
+AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <iostream>
+using namespace std;
+static char buf[1024];]],
+    [[cerr.rdbuf()->pubsetbuf(buf, sizeof(buf));]])],
+    [AC_MSG_RESULT(yes) AC_DEFINE(HAVE_PUBSETBUF, 1, [whether pubsetbuf is available])],
+    AC_MSG_RESULT(no))
+AC_LANG_POP(C++)
+
+# Check for <locale>
+AC_LANG_PUSH(C++)
+AC_CHECK_HEADERS([locale])
+AC_LANG_POP(C++)
+
+AC_DEFUN([NEED_PROG],
+[
+AC_PATH_PROG($1, $2)
+if test -z "$$1"; then
+    AC_MSG_ERROR([$2 is required])
+fi
+])
+
+NEED_PROG(curl, curl)
+NEED_PROG(bzip2, bzip2)
+NEED_PROG(bunzip2, bunzip2)
+NEED_PROG(shell, sh)
+AC_PATH_PROG(xmllint, xmllint, false)
+AC_PATH_PROG(xsltproc, xsltproc, false)
+AC_PATH_PROG(flex, flex, false)
+AC_PATH_PROG(bison, bison, false)
+NEED_PROG(perl, perl)
+NEED_PROG(tar, tar)
+                
+NEED_PROG(cat, cat)
+AC_ARG_WITH(coreutils-bin, AC_HELP_STRING([--with-coreutils-bin=PATH],
+  [path of cat, mkdir, etc.]),
+  coreutils=$withval, coreutils=$(dirname $cat))
+AC_SUBST(coreutils)
+
+AC_ARG_WITH(docbook-catalog, AC_HELP_STRING([--with-docbook-catalog=PATH],
+  [path of the DocBook XML DTD]),
+  docbookcatalog=$withval, docbookcatalog=/docbook-dtd-missing)
+AC_SUBST(docbookcatalog)
+
+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]),
+  storedir=$withval, storedir='${prefix}/store')
+AC_SUBST(storedir)
+
+AC_ARG_WITH(bdb, AC_HELP_STRING([--with-bdb=PATH],
+  [prefix of Berkeley DB]),
+  bdb=$withval, bdb=)
+AM_CONDITIONAL(HAVE_BDB, test -n "$bdb")
+if test -z "$bdb"; then
+  bdb_lib='-L${top_builddir}/externals/inst-bdb/lib -ldb_cxx'
+  bdb_include='-I${top_builddir}/externals/inst-bdb/include'
+else
+  bdb_lib="-L$bdb/lib -ldb_cxx"
+  bdb_include="-I$bdb/include"
+fi
+AC_SUBST(bdb_lib)
+AC_SUBST(bdb_include)
+
+AC_ARG_WITH(aterm, AC_HELP_STRING([--with-aterm=PATH],
+  [prefix of CWI ATerm library]),
+  aterm=$withval, aterm=)
+AM_CONDITIONAL(HAVE_ATERM, test -n "$aterm")
+if test -z "$aterm"; then
+  aterm_lib='-L${top_builddir}/externals/inst-aterm/lib -lATerm'
+  aterm_include='-I${top_builddir}/externals/inst-aterm/include'
+  aterm_bin='${top_builddir}/externals/inst-aterm/bin'
+else
+  aterm_lib="-L$aterm/lib -lATerm"
+  aterm_include="-I$aterm/include"
+  aterm_bin="$aterm/bin"
+fi
+AC_SUBST(aterm_lib)
+AC_SUBST(aterm_include)
+AC_SUBST(aterm_bin)
 
 AC_CHECK_LIB(pthread, pthread_mutex_init)
 
+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")
+
+
+AC_ARG_ENABLE(setuid, AC_HELP_STRING([--enable-setuid],
+  [install Nix setuid]),
+  setuid_hack=$enableval, setuid_hack=no)
+AM_CONDITIONAL(SETUID_HACK, test "$setuid_hack" = "yes")
+if test "$setuid_hack" = "yes"; then
+    AC_DEFINE(SETUID_HACK, 1, [whether to install Nix setuid])
+fi
+
+AC_CHECK_FUNC(setresuid, [HAVE_SETRESUID=1], [HAVE_SETRESUID=])
+AM_CONDITIONAL(HAVE_SETRESUID, test "$HAVE_SETRESUID" = "1")
+if test "$HAVE_SETRESUID" = "1"; then
+    AC_DEFINE(HAVE_SETRESUID, 1, [whether we have setresuid()])
+fi
+
+AC_ARG_WITH(nix-user, AC_HELP_STRING([--with-nix-user=USER],
+  [user for Nix setuid binaries]),
+  NIX_USER=$withval, NIX_USER=nix)
+AC_SUBST(NIX_USER)
+AC_DEFINE_UNQUOTED(NIX_USER, ["$NIX_USER"], [Nix user])
+                                                      
+AC_ARG_WITH(nix-group, AC_HELP_STRING([--with-nix-group=USER],
+  [group for Nix setuid binaries]),
+  NIX_GROUP=$withval, NIX_GROUP=nix)
+AC_SUBST(NIX_GROUP)
+AC_DEFINE_UNQUOTED(NIX_GROUP, ["$NIX_GROUP"], [Nix group])
+
+                                                                                                            
 AM_CONFIG_HEADER([config.h])
-AC_CONFIG_FILES([Makefile externals/Makefile src/Makefile scripts/Makefile
-			  corepkgs/Makefile corepkgs/fetchurl/Makefile
-			  corepkgs/nar/Makefile
-			  doc/Makefile doc/manual/Makefile])
+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/log2xml/Makefile
+   src/bsdiff-4.2/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
+  ])
 AC_OUTPUT

corepkgs/Makefile.am

@@ -1 +1 @@
-SUBDIRS = fetchurl nar
+SUBDIRS = nar buildenv channels

corepkgs/buildenv/Makefile.am

@@ -0,0 +1,11 @@
+all-local: builder.pl
+
+install-exec-local:
+	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs
+	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs/buildenv
+	$(INSTALL_DATA) 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/builder.pl.in

@@ -0,0 +1,108 @@
+#! @perl@ -w
+
+use strict;
+use Cwd;
+use IO::Handle;
+
+STDOUT->autoflush(1);
+
+my $out = $ENV{"out"};
+mkdir "$out", 0755 || die "error creating $out";
+
+
+# For each activated package, create symlinks.
+
+sub createLinks {
+    my $srcDir = shift;
+    my $dstDir = shift;
+
+    my @srcFiles = glob("$srcDir/*");
+
+    foreach my $srcFile (@srcFiles) {
+        my $baseName = $srcFile;
+        $baseName =~ s/^.*\///g; # strip directory
+        my $dstFile = "$dstDir/$baseName";
+        
+	if ($srcFile =~ /\/propagated-build-inputs$/ ||
+            $srcFile =~ /\/nix-support$/ ||
+            $srcFile =~ /\/perllocal.pod$/ ||
+            $srcFile =~ /\/log$/)
+        {
+            # Do nothing.
+	}
+
+        elsif (-d $srcFile) {
+
+            lstat $dstFile;
+            
+            if (-d _) {
+                createLinks($srcFile, $dstFile);
+            }
+
+            elsif (-l _) {
+                my $target = readlink $dstFile or die;
+                if (!-d $target) {
+                    die "collission between directory `$srcFile' and non-directory `$target'";
+                }
+                unlink $dstFile or die "error unlinking `$dstFile': $!";
+                mkdir $dstFile, 0755 || 
+                    die "error creating directory `$dstFile': $!";
+                createLinks($target, $dstFile);
+                createLinks($srcFile, $dstFile);
+            }
+
+            else {
+                symlink($srcFile, $dstFile) ||
+                    die "error creating link `$dstFile': $!";
+            }
+        }
+
+        elsif (-l $dstFile) {
+            my $target = readlink $dstFile;
+            die "collission between `$srcFile' and `$target'";
+        }
+
+        else {
+#            print "linking $dstFile to $srcFile\n";
+            symlink($srcFile, $dstFile) ||
+                die "error creating link `$dstFile': $!";
+        }
+    }
+}
+
+
+my %done;
+
+sub addPkg;
+sub addPkg {
+    my $pkgDir = shift;
+
+    return if (defined $done{$pkgDir});
+    $done{$pkgDir} = 1;
+
+    print "adding $pkgDir\n";
+    createLinks("$pkgDir", "$out");
+
+    my $propagatedFN = "$pkgDir/nix-support/propagated-build-inputs";
+    if (-e $propagatedFN) {
+        open PROP, "<$propagatedFN" or die;
+        my $propagated = <PROP>;
+        close PROP;
+        my @propagated = split ' ', $propagated;
+        foreach my $p (@propagated) {
+            addPkg $p;
+        }
+    }
+        
+}
+
+
+my @args = split ' ', $ENV{"derivations"};
+
+while (scalar @args > 0) {
+    my $drvPath = shift @args;
+    addPkg($drvPath);
+}
+
+
+symlink($ENV{"manifest"}, "$out/manifest") or die "cannot create manifest";

corepkgs/buildenv/default.nix

@@ -0,0 +1,9 @@
+{system, derivations, manifest}:
+
+derivation { 
+  name = "user-environment";
+  system = system;
+  builder = ./builder.pl;
+  derivations = derivations;
+  manifest = manifest;
+}

corepkgs/channels/Makefile.am

@@ -0,0 +1,11 @@
+all-local: unpack.sh
+
+install-exec-local:
+	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs
+	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/corepkgs/channels
+	$(INSTALL_DATA) 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

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

corepkgs/channels/unpack.sh.in

@@ -0,0 +1,22 @@
+#! @shell@ -e
+
+@coreutils@/mkdir $out
+@coreutils@/mkdir $out/tmp
+cd $out/tmp
+
+expr=$out/default.nix
+echo '[' > $expr
+
+nr=0
+for i in $inputs; do
+    echo "unpacking $i"
+    @bunzip2@ < $i | @tar@ xf -
+    @coreutils@/mv * ../$nr # !!! hacky
+    echo "(import ./$nr)" >> $expr
+    nr=$(($nr + 1))
+done
+
+echo ']' >> $expr
+
+cd ..
+@coreutils@/rmdir tmp

corepkgs/fetchurl/Makefile.am

@@ -1,10 +0,0 @@
-all-local: fetchurl.sh
-
-install-exec-local:
-	$(INSTALL) -d $(datadir)/fix/fetchurl
-	$(INSTALL_DATA) fetchurl.fix $(datadir)/fix/fetchurl
-	$(INSTALL_PROGRAM) fetchurl.sh $(datadir)/fix/fetchurl
-
-include ../../substitute.mk
-
-EXTRA_DIST = fetchurl.fix fetchurl.sh

corepkgs/fetchurl/fetchurl.fix

@@ -1,10 +0,0 @@
-Function(["url", "md5"],
-  Package(
-    [ ("build", Relative("fetchurl/fetchurl.sh"))
-    , ("url", Var("url"))
-    , ("md5", Var("md5"))
-    , ("name", BaseName(Var("url")))
-    , ("id", Var("md5"))
-    ]
-  )
-)

corepkgs/fetchurl/fetchurl.sh.in

@@ -1,19 +0,0 @@
-#! /bin/sh
-
-export PATH=/bin:/usr/bin
-
-echo "downloading $url into $out..."
-
-prefetch=@prefix@/store/nix-prefetch-url-$md5
-if test -f "$prefetch"; then
-    echo "using prefetched $prefetch";
-    mv $prefetch $out || exit 1
-else
-    @wget@ "$url" -O "$out" || exit 1
-fi
-
-actual=$(@bindir@/nix-hash --flat $out)
-if test "$actual" != "$md5"; then
-    echo "hash is $actual, expected $md5"
-    exit 1
-fi

corepkgs/nar/Makefile.am

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

corepkgs/nar/nar.fix

@@ -1,8 +0,0 @@
-Function(["path"],
-  Package(
-    [ ("name", "nar")
-    , ("build", Relative("nar/nar.sh"))
-    , ("path", Var("path"))
-    ]
-  )
-)

corepkgs/nar/nar.nix

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

corepkgs/nar/nar.sh.in

@@ -1,10 +1,14 @@
-#! /bin/sh
+#! @shell@ -e
 
 echo "packing $path into $out..."
-mkdir $out || exit 1
-tmp=$out/tmp
-@bindir@/nix --dump --path "$path" | bzip2 > $out/tmp || exit 1
+@coreutils@/mkdir $out
+dst=$out/tmp.nar.bz2
+@bindir@/nix-store --dump "$path" > tmp
 
-md5=$(md5sum -b $tmp | cut -c1-32)
-if test $? != 0; then exit 1; fi
-mv $out/tmp $out/$md5-`basename $path`.nar.bz2 || exit 1
+@bzip2@ < tmp > $dst
+
+@bindir@/nix-hash -vvvvv --flat --type $hashAlgo --base32 tmp > $out/nar-hash
+
+@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/nar/unnar.fix

@@ -1,9 +0,0 @@
-Function(["nar", "name"],
-  Package(
-    [ ("name", Var("name"))
-    , ("build", Relative("nar/unnar.sh"))
-    , ("nar", Var("nar"))
-    , ("id", Var("id"))
-    ]
-  )
-)

corepkgs/nar/unnar.sh.in

@@ -1,4 +0,0 @@
-#! /bin/sh
-
-echo "unpacking $nar to $out..."
-bunzip2 < $nar | @bindir@/nix --restore "$out" || exit 1

doc/dev/release-procedures.txt

@@ -0,0 +1,30 @@
+To produce a `stable' release from the trunk:
+
+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 release; 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,30 +1,61 @@
-DOCBOOK_DTD = /nix/current/xml/dtd/docbook
-DOCBOOK_XSL = /nix/current/xml/xsl/docbook
+ENV = SGML_CATALOG_FILES=$(docbookcatalog)
 
-ENV = SGML_CATALOG_FILES=$(DOCBOOK_DTD)/docbook.cat
+XMLLINT = $(ENV) $(xmllint) $(xmlflags) --catalogs
+XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs \
+ --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
 
-XMLLINT = $(ENV) xmllint --catalogs
-XSLTPROC = $(ENV) xsltproc --catalogs
+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
 
-SOURCES = book.xml introduction.xml installation.xml nix-reference.xml \
- troubleshooting.xml bugs.xml
+FIGURES = figures/user-environments.png
 
-book.is-valid: $(SOURCES)
-	$(XMLLINT) --noout --valid book.xml
+MANUAL_SRCS = manual.xml introduction.xml installation.xml \
+ package-management.xml writing-nix-expressions.xml \
+ build-farm.xml \
+ $(man1_MANS:.1=.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 \
+ style.css images
+
+manual.is-valid: $(MANUAL_SRCS) version.txt
+	$(XMLLINT) --xinclude $< | $(XMLLINT) --noout --nonet --valid -
 	touch $@
 
-man1_MANS = nix.1 fix.1
+version.txt:
+	echo -n $(VERSION) > version.txt
 
-man nix.1 fix.1: $(SOURCES) book.is-valid
-	$(XSLTPROC) $(DOCBOOK_XSL)/manpages/docbook.xsl book.xml
+man $(MANS): $(MANUAL_SRCS) manual.is-valid
+	$(XSLTPROC) --nonet --xinclude $(docbookxsl)/manpages/docbook.xsl manual.xml
 
-book.html: $(SOURCES) book.is-valid
-	$(XSLTPROC) --output book.html $(DOCBOOK_XSL)/html/docbook.xsl book.xml
+manual.html: $(MANUAL_SRCS) manual.is-valid images
+	$(XSLTPROC) --nonet --xinclude --output manual.html \
+	  $(docbookxsl)/html/docbook.xsl manual.xml
 
-all-local: book.html
+all-local: manual.html
 
-install-data-local: book.html
-	$(INSTALL) -d $(datadir)/nix/manual
-	$(INSTALL_DATA) book.html $(datadir)/nix/manual
+install-data-local: manual.html
+	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/manual
+	$(INSTALL_DATA) manual.html $(DESTDIR)$(datadir)/nix/manual
+	$(INSTALL_DATA) style.css $(DESTDIR)$(datadir)/nix/manual
+	cp -r images $(DESTDIR)$(datadir)/nix/manual/images
+	$(INSTALL) -d $(DESTDIR)$(datadir)/nix/manual/figures
+	$(INSTALL_DATA) $(FIGURES) $(DESTDIR)$(datadir)/nix/manual/figures
 
-EXTRA_DIST = $(SOURCES) book.html nix.1 fix.1 book.is-valid
+images:
+	mkdir images
+	cp $(docbookxsl)/images/*.png images
+	mkdir images/callouts
+	cp $(docbookxsl)/images/callouts/*.png images/callouts
+	chmod +w -R images
+
+KEEP = manual.html manual.is-valid version.txt $(MANS)
+
+EXTRA_DIST = $(MANUAL_SRCS) $(FIGURES) $(KEEP)
+
+DISTCLEANFILES = $(KEEP)

doc/manual/book.xml

@@ -1,64 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book
-    PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[
-<!ENTITY introduction SYSTEM "introduction.xml">
-<!ENTITY installation SYSTEM "installation.xml">
-<!ENTITY nix-reference SYSTEM "nix-reference.xml">
-<!ENTITY fix-reference SYSTEM "fix-reference.xml">
-<!ENTITY troubleshooting SYSTEM "troubleshooting.xml">
-<!ENTITY bugs SYSTEM "bugs.xml">
-]>
-
-<book>
-  <title>Nix: The Manual</title>
-
-  <bookinfo>
-    <author>
-      <firstname>Eelco</firstname>
-      <surname>Dolstra</surname>
-    </author>
-    <copyright>
-      <year>2003</year>
-      <holder>Eelco Dolstra</holder>
-    </copyright>
-  </bookinfo>
-
-  &introduction;
-  &installation;
-
-  <chapter>
-    <title>A Guided Tour</title>
-    <para>
-    </para>
-  </chapter>
-
-  <chapter>
-    <title>Nix Syntax and Semantics</title>
-    <para>
-    </para>
-  </chapter>
-
-  <chapter>
-    <title>Fix Language Reference</title>
-    <para>
-    </para>
-  </chapter>
-
-  <chapter>
-    <title>Writing Builders</title>
-    <para>
-    </para>
-  </chapter>
-
-  <appendix>
-    <title>Command Reference</title>
-    &nix-reference;
-    &fix-reference;
-  </appendix>
-
-  &troubleshooting;
-  &bugs;
-
-</book>

doc/manual/bugs.xml

@@ -1,43 +1,46 @@
-<appendix>
-  <title>Bugs</title>
+<appendix><title>Bugs / To-Do</title>
 
-  <itemizedlist>
+<itemizedlist>
 
-    <listitem>
-      <para>
-	Nix should automatically recover the Berkeley DB database.
-      </para>
-    </listitem>
+<listitem><para>The man-pages generated from the DocBook documentation
+are ugly.</para></listitem>
 
-    <listitem>
-      <para>
-	Nix should automatically remove Berkeley DB logfiles.
-      </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>
-	Unify the concepts of successors and substitutes into a general notion
-	of <emphasis>equivalent expressions</emphasis>.  Expressions are
-	equivalent if they have the same target paths with the same
-	identifiers.  However, even though they are functionally equivalent,
-	they may differ stronly with respect to their <emphasis>performance
-	  characteristics</emphasis>.  For example, realising a slice is more
-	efficient that realising the derivation from which that slice was
-	produced.  On the other hand, distributing sources may be more
-	efficient (storage- or bandwidth-wise) than distributing binaries.  So
-	we need to be able to attach weigths or priorities or performance
-	annotations to expressions; Nix can then choose the most efficient
-	expression dependent on the context.
-      </para>
-    </listitem>
+<listitem><para><emphasis>Build management.</emphasis> In principle it
+is already possible to do build management using Nix (by writing
+builders that perform appropriate build steps), but the Nix expression
+language is not yet powerful enough to make this pleasant (?).  The
+language should be extended with features from the <ulink
+url='http://www.cs.uu.nl/~eelco/maak/'>Maak build manager</ulink>.
+Another interesting idea is to write a <command>make</command>
+implementation that uses Nix as a back-end to support <ulink
+url='http://www.research.att.com/~bs/bs_faq.html#legacy'>legacy</ulink>
+build files.</para></listitem>
 
-  </itemizedlist>
+<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>
-
-<!--
-local variables:
-sgml-parent-document: ("book.xml" "appendix")
-end:
--->

doc/manual/build-farm.xml

@@ -0,0 +1,132 @@
+<chapter 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 component haven't
+  changed between runs of the build farm, the component won't be
+  rebuild (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 <ulink
+url='https://svn.cs.uu.nl:12443/repos/trace/release/trunk' />.</para>
+
+</section>
+
+
+<section 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 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: <ulink
+url='https://svn.cs.uu.nl:12443/repos/trace/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/conf-file.xml

@@ -0,0 +1,82 @@
+<sect1 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 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 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 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>
+
+</variablelist>
+
+</para>
+
+</sect1>

doc/manual/env-common.xml

@@ -0,0 +1,274 @@
+<sect1 id="sec-common-env"><title>Common environment variables</title>
+
+<para>Most Nix commands interpret the following environment variables:</para>
+
+<variablelist>
+
+  
+<varlistentry><term><envar>NIX_ROOT</envar></term>
+
+  <listitem><para>If <envar>NIX_ROOT</envar> is set, the Nix command
+  will on startup perform a <function>chroot()</function> to the
+  specified directory.  This is useful in certain bootstrapping
+  situations (e.g., when installing a Nix installation onto a hard
+  disk from CD-ROM).</para></listitem>
+
+</varlistentry>
+
+  
+<varlistentry><term><envar>NIX_IGNORE_SYMLINK_STORE</envar></term>
+
+  <listitem>
+
+  <para>Normally, the Nix store directory (typically
+  <filename>/nix/store</filename>) is not allowed to contain any
+  symlink components.  This is to prevent “impure” builds.  Builders
+  sometimes “canonicalise” paths by resolving all symlink components.
+  Thus, builds on different machines (with
+  <filename>/nix/store</filename> resolving to different locations)
+  could yield different results.  This is generally not a problem,
+  except when builds are deployed to machines where
+  <filename>/nix/store</filename> resolves differently.  If you are
+  sure that you’re not going to do that, you can set
+  <envar>NIX_IGNORE_SYMLINK_STORE</envar> to <envar>1</envar>.</para>
+
+  <para>Note that if you’re symlinking the Nix store so that you can
+  put it on another file system than the root file system, on Linux
+  you’re better off using <literal>bind</literal> mount points, e.g.,
+
+  <screen>
+$ mkdir /nix   
+$ mount -o bind /mnt/otherdisk/nix /nix</screen>
+
+  Consult the <citerefentry><refentrytitle>mount</refentrytitle>
+  <manvolnum>8</manvolnum></citerefentry> manual page for details.</para>
+
+  </listitem>
+
+</varlistentry>
+
+
+<varlistentry><term><envar>NIX_STORE_DIR</envar></term>
+
+  <listitem><para>Overrides the location of the Nix store (default
+  <filename><replaceable>prefix</replaceable>/store</filename>).</para></listitem>
+  
+</varlistentry>
+
+
+<varlistentry><term><envar>NIX_DATA_DIR</envar></term>
+
+  <listitem><para>Overrides the location of the Nix static data
+  directory (default
+  <filename><replaceable>prefix</replaceable>/share</filename>).</para></listitem>
+  
+</varlistentry>
+
+
+<varlistentry><term><envar>NIX_LOG_DIR</envar></term>
+
+  <listitem><para>Overrides the location of the Nix log directory
+  (default <filename><replaceable>prefix</replaceable>/log/nix</filename>).</para></listitem>
+  
+</varlistentry>
+
+
+<varlistentry><term><envar>NIX_STATE_DIR</envar></term>
+
+  <listitem><para>Overrides the location of the Nix state directory
+  (default <filename><replaceable>prefix</replaceable>/var/nix</filename>).</para></listitem>
+  
+</varlistentry>
+
+
+<varlistentry><term><envar>NIX_DB_DIR</envar></term>
+
+  <listitem><para>Overrides the location of the Nix database (default
+  <filename><replaceable>$NIX_STATE_DIR</replaceable>/db</filename>, i.e.,
+  <filename><replaceable>prefix</replaceable>/var/nix/db</filename>).</para></listitem>
+  
+</varlistentry>
+
+
+<varlistentry><term><envar>NIX_CONF_DIR</envar></term>
+
+  <listitem><para>Overrides the location of the Nix configuration
+  directory (default
+  <filename><replaceable>prefix</replaceable>/etc/nix</filename>).</para></listitem>
+  
+</varlistentry>
+
+
+<varlistentry><term><envar>NIX_LOG_TYPE</envar></term>
+
+  <listitem><para>Equivalent to the <link
+  linkend="opt-log-type"><option>--log-type</option>
+  option</link>.</para></listitem>
+
+</varlistentry>
+  
+
+<varlistentry><term><envar>TMPDIR</envar></term>
+
+  <listitem><para>Use the specified directory to store temporary
+  files.  In particular, this includes temporary build directories;
+  these can take up substantial amounts of disk space.  The default is
+  <filename>/tmp</filename>.</para></listitem>
+  
+</varlistentry>
+
+
+<varlistentry id="envar-build-hook"><term><envar>NIX_BUILD_HOOK</envar></term>
+
+  <listitem>
+
+  <para>Specifies the location of the <emphasis>build hook</emphasis>,
+  which is a program (typically some script) that Nix will call
+  whenever it wants to build a derivation.  This is used to implement
+  distributed builds (see <xref linkend="sec-distributed-builds"
+  />).  The protocol by which the calling Nix process and the build
+  hook communicate is as follows.</para>
+
+  <para>The build hook is called with the following command-line
+  arguments:
+
+  <orderedlist>
+
+    <listitem><para>A boolean value <literal>0</literal> or
+    <literal>1</literal> specifying whether Nix can locally execute
+    more builds, as per the <link
+    linkend="opt-max-jobs"><option>--max-jobs</option> option</link>.
+    The purpose of this argument is to allow the hook to not have to
+    maintain bookkeeping for the local machine.</para></listitem>
+
+    <listitem><para>The Nix platform identifier for the local machine
+    (e.g., <literal>i686-linux</literal>).</para></listitem>
+
+    <listitem><para>The Nix platform identifier for the derivation,
+    i.e., its <link linkend="attr-system"><varname>system</varname>
+    attribute</link>.</para></listitem>
+
+    <listitem><para>The store path of the derivation.</para></listitem>
+
+  </orderedlist>
+
+  </para>
+
+  <para>On the basis of this information, and whatever persistent
+  state the build hook keeps about other machines and their current
+  load, it has to decide what to do with the build.  It should print
+  out on file descriptor 3 one of the following responses (terminated
+  by a newline, <literal>"\n"</literal>):
+
+  <variablelist>
+
+    <varlistentry><term><literal>decline</literal></term>
+
+      <listitem><para>The build hook is not willing or able to perform
+      the build; the calling Nix process should do the build itself,
+      if possible.</para></listitem>
+
+    </varlistentry>
+
+    <varlistentry><term><literal>postpone</literal></term>
+
+      <listitem><para>The build hook cannot perform the build now, but
+      can do so in the future (e.g., because all available build slots
+      on remote machines are in use).  The calling Nix process should
+      postpone this build until at least one currently running build
+      has terminated.</para></listitem>
+
+    </varlistentry>
+
+    <varlistentry><term><literal>accept</literal></term>
+
+      <listitem><para>The build hook has accepted the
+      build.</para></listitem>
+
+    </varlistentry>
+
+  </variablelist>
+
+  </para>
+
+  <para>If the build hook accepts the build, it is possible that it is
+  no longer necessary to do the build because some other process has
+  performed the build in the meantime.  To prevent races, the hook
+  must read from file descriptor 4 a single line that tells it whether
+  to continue:
+
+  <variablelist>
+
+    <varlistentry><term><literal>cancel</literal></term>
+
+      <listitem><para>The build has already been done, so the hook
+      should exit.</para></listitem>
+
+    </varlistentry>
+  
+    <varlistentry><term><literal>okay</literal></term>
+
+      <listitem><para>The hook should proceed with the build.  At this
+      point, the calling Nix process has acquired locks on the output
+      path, so no other Nix process will perform the
+      build.</para></listitem>
+
+    </varlistentry>
+
+  </variablelist>
+
+  </para>
+
+  <para>If the hook has been told to proceed, Nix will store in the
+  hook’s current directory a number of text files that contain
+  information about the derivation:
+
+  <variablelist>
+
+    <varlistentry><term><filename>inputs</filename></term>
+
+      <listitem><para>The set of store paths that are inputs to the
+      build process (one per line).  These have to be copied
+      <emphasis>to</emphasis> the remote machine (in addition to the
+      store derivation itself).</para></listitem>
+
+    </varlistentry>
+  
+    <varlistentry><term><filename>outputs</filename></term>
+
+      <listitem><para>The set of store paths that are outputs of the
+      derivation (one per line).  These have to be copied
+      <emphasis>from</emphasis> the remote machine if the build
+      succeeds.</para></listitem>
+
+    </varlistentry>
+
+    <varlistentry><term><filename>references</filename></term>
+
+      <listitem><para>The reference graph of the inputs, in the format
+      accepted by the command <command>nix-store
+      --register-validity</command>.  It is necessary to run this
+      command on the remote machine after copying the inputs to inform
+      Nix on the remote machine that the inputs are valid
+      paths.</para></listitem>
+
+    </varlistentry>
+
+  </variablelist>
+
+  </para>
+
+  <para>The hook should copy the inputs to the remote machine,
+  register the validity of the inputs, perform the remote build, and
+  copy the outputs back to the local machine.  An exit code other than
+  <literal>0</literal> indicates that the hook has failed.</para>
+
+  </listitem>
+
+
+</varlistentry>
+
+
+</variablelist>
+
+</sect1>

doc/manual/fix-reference.xml

@@ -1,37 +0,0 @@
-<refentry>
-  <refnamediv>
-    <refname>fix</refname>
-    <refpurpose>generate Nix expressions from a high-level description</refpurpose>
-  </refnamediv>
-
-  <refsynopsisdiv>
-    <cmdsynopsis>
-      <command>fix</command>
-      <group choice='opt' rep='repeat'>
-	<arg><option>--verbose</option></arg>
-	<arg><option>-v</option></arg>
-      </group>
-      <arg rep='repeat'><replaceable>files</replaceable></arg>
-    </cmdsynopsis>
-  </refsynopsisdiv>
-
-  <refsect1>
-    <title>Description</title>
-
-    <para>
-      The command <command>fix</command> generates Nix expressions from
-      expressions is Fix's own high-level language.  While Nix expressions are
-      very primitive and not intended to be written directly, Fix expressions
-      are quite easy to write.
-    </para>
-
-  </refsect1>
-
-</refentry>
-
-
-<!--
-local variables:
-sgml-parent-document: ("book.xml" "refentry")
-end:
--->

doc/manual/glossary.xml

@@ -0,0 +1,163 @@
+<appendix><title>Glossary</title>
+
+<glosslist>
+
+
+<glossentry id="gloss-derivation"><glossterm>derivation</glossterm>
+
+  <glossdef><para>A description of a build action.  The result of a
+  derivation is a store object.  Derivations are typically specified
+  in Nix expressions using the <link
+  linkend="ssec-derivation"><function>derivation</function>
+  primitive</link>.  These are translated into low-level
+  <emphasis>store derivations</emphasis> (implicitly by
+  <command>nix-env</command> and <command>nix-build</command>, or
+  explicitly by <command>nix-instantiate</command>).</para></glossdef>
+
+</glossentry>
+
+
+<glossentry><glossterm>store</glossterm>
+
+  <glossdef><para>The location in the file system where store objects
+  live.  Typically <filename>/nix/store</filename>.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry><glossterm>store path</glossterm>
+
+  <glossdef><para>The location in the file system of a store object,
+  i.e., an immediate child of the Nix store
+  directory.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry><glossterm>store object</glossterm>
+
+  <glossdef><para>A file that is an immediate child of the Nix store
+  directory.  These can be regular files, but also entire directory
+  trees.  Store objects can be sources (objects copied from outside of
+  the store), derivation outputs (objects produced by running a build
+  action), or derivations (files describing a build
+  action).</para></glossdef>
+
+</glossentry>
+
+
+<glossentry id="gloss-substitute"><glossterm>substitute</glossterm>
+
+  <glossdef><para>A substitute is a command invocation stored in the
+  Nix database that describes how to build a store object, bypassing
+  normal the build mechanism (i.e., derivations).  Typically, the
+  substitute builds the store object by downloading a pre-built
+  version of the store object from some server.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry><glossterm>purity</glossterm>
+
+  <glossdef><para>The assumption that equal Nix derivations when run
+  always produce the same output.  This cannot be guaranteed in
+  general (e.g., a builder can rely on external inputs such as the
+  network or the system time) but the Nix model assumes
+  it.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry><glossterm>Nix expression</glossterm>
+
+  <glossdef><para>A high-level description of software components and
+  compositions thereof.  Deploying software using Nix entails writing
+  Nix expressions for your components.  Nix expressions are translated
+  to derivations that are stored in the Nix store.  These derivations
+  can then be built.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry id="gloss-reference"><glossterm>reference</glossterm>
+
+  <glossdef><para>A store path <varname>P</varname> is said to have a
+  reference to a store path <varname>Q</varname> if the store object
+  at <varname>P</varname> contains the path <varname>Q</varname>
+  somewhere.  This implies than an execution involving
+  <varname>P</varname> potentially needs <varname>Q</varname> to be
+  present.  The <emphasis>references</emphasis> of a store path are
+  the set of store paths to which it has a reference.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry id="gloss-closure"><glossterm>closure</glossterm>
+
+  <glossdef><para>The closure of a store path is the set of store
+  paths that are directly or indirectly “reachable” from that store
+  path; that is, it’s the closure of the path under the <link
+  linkend="gloss-reference">references</link> relation.  For instance,
+  if the store object at path <varname>P</varname> contains a
+  reference to path <varname>Q</varname>, then <varname>Q</varname> is
+  in the closure of <varname>P</varname>.  For correct deployment it
+  is necessary to deploy whole closures, since otherwise at runtime
+  files could be missing.  The command <command>nix-store
+  -qR</command> prints out closures of store paths.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry id="gloss-output-path"><glossterm>output path</glossterm>
+
+  <glossdef><para>A store path produced by a derivation.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry id="gloss-deriver"><glossterm>deriver</glossterm>
+
+  <glossdef><para>The deriver of an <link
+  linkend="gloss-output-path">output path</link> is the store
+  derivation that built it.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry id="gloss-validity"><glossterm>validity</glossterm>
+
+  <glossdef><para>A store path is considered
+  <emphasis>valid</emphasis> if it exists in the file system, is
+  listed in the Nix database as being valid, and if all paths in its
+  closure are also valid.</para></glossdef>
+
+</glossentry>
+
+
+<glossentry id="gloss-user-env"><glossterm>user environment</glossterm>
+
+  <glossdef><para>An automatically generated store object that
+  consists of a set of symlinks to “active” applications, i.e., other
+  store paths.  These are generated automatically by <link
+  linkend="sec-nix-env"><command>nix-env</command></link>.  See <xref
+  linkend="sec-profiles" />.</para>
+
+  </glossdef>
+  
+</glossentry>
+
+
+<glossentry id="gloss-profile"><glossterm>profile</glossterm>
+
+  <glossdef><para>A symlink to the current <link
+  linkend="gloss-user-env">user environment</link> of a user, e.g.,
+  <filename>/nix/var/nix/profiles/default</filename>.</para></glossdef>
+
+</glossentry>
+
+
+
+</glosslist>
+
+
+</appendix>

doc/manual/installation.xml

@@ -1,80 +1,212 @@
-<chapter>
-  <title>Installation</title>
+<chapter id='chap-installation'><title>Installation</title>
 
-  <sect1>
-    <title>Prerequisites</title>
 
-    <para>
-      Nix uses Sleepycat's Berkeley DB and CWI's ATerm library.  However, these
-      are fetched automatically as part of the build process.
+<sect1><title>Obtaining Nix</title>
+
+<para>The easiest way to obtain Nix is to download a <ulink
+url='http://www.cs.uu.nl/groups/ST/Trace/Nix'>source
+distribution</ulink>.  RPMs for Red Hat, SuSE, and Fedore Core are
+also available.</para>
+
+<para>Alternatively, the most recent sources of Nix can be obtained
+from its <ulink
+url='https://svn.cs.uu.nl:12443/repos/trace/nix/trunk'>Subversion
+repository</ulink>.  For example, the following command will check out
+the latest revision into a directory called <filename>nix</filename>:</para>
+
+<screen>
+$ svn checkout https://svn.cs.uu.nl:12443/repos/trace/nix/trunk nix</screen>
+
+<para>Likewise, specific releases can be obtained from the <ulink
+url='https://svn.cs.uu.nl:12443/repos/trace/nix/tags'>tags
+directory</ulink> of the repository.  If you don't have Subversion,
+you can also download an automatically generated <ulink
+url='https://svn.cs.uu.nl:12443/dist/trace/'>compressed
+tar-file</ulink> of the head revision of the trunk.</para>
+
+</sect1>
+
+
+<sect1><title>Prerequisites</title>
+
+<para>The following prerequisites only apply when you build from
+source.  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
+<ulink url='http://docbook.sourceforge.net/projects/xsl/'>DocBook XSL
+stylesheets</ulink> and optionally the <ulink
+url='http://www.oasis-open.org/docbook/xml/4.2/docbook-xml-4.2.zip'>
+DocBook XML 4.2 DTD</ulink>.  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 1.875c or higher (1.875 does <emphasis>not</emphasis> work),
+which can be obtained from the <ulink
+url='ftp://alpha.gnu.org/pub/gnu/bison'>GNU FTP server</ulink>.  For
+Flex, you need version 2.5.31, which is available on <ulink
+url='http://lex.sourceforge.net/'>SourceForge</ulink>.  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 Sleepycat's Berkeley DB and CWI's ATerm library.  These
+are included in the Nix source distribution.  If you build from the
+Subversion repository, you must download them yourself and place them
+in the <filename>externals/</filename> directory.  See
+<filename>externals/Makefile.am</filename> for the precise URLs of
+these packages.  Alternatively, if you already have them installed,
+you can use <command>configure</command>'s <option>--with-bdb</option>
+and <option>--with-aterm</option> options to point to their respective
+locations.  Note that Berkeley DB <emphasis>must</emphasis> be version
+4.2; other versions may not have compatible database formats.</para>
+
+</sect1>
+
+
+<sect1><title>Building Nix from source</title>
+
+<para>After unpacking or checking out the Nix sources, issue the
+following commands:
     </para>
 
-    <para>
-      Other than that, you need a good C++ compiler.  GCC 2.95 does not appear
-      to work; please use GCC 3.x.
-    </para>
-  </sect1>
-
-  <sect1>
-    <title>Obtaining Nix</title>
-
-    <para>
-      Nix can be obtained from its <ulink
-	url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk'>Subversion 
-	repository</ulink>.  For example, the following command will check out
-      the latest revision into a directory called <filename>nix</filename>:
-    </para>
-
-    <screen>
-$ svn checkout http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/trunk nix</screen>
-
-    <para>
-      Likewise, specific releases can be obtained from the <ulink
-	url='http://losser.st-lab.cs.uu.nl:12080/repos/trace/nix/tags'>tags
-	directory</ulink> of the repository.  If you don't have Subversion, you
-      can download a <ulink
-	url='http://losser.st-lab.cs.uu.nl:12080/dist/trace/'>compressed
-	tar-file</ulink> of the latest revision of the repository.
-    </para>
-
-  </sect1>
-
-  <sect1>
-    <title>Building Nix</title>
-
-    <para>
-      To build Nix, do the following:
-    </para>
-
-    <screen>
-$ autoreconf -i
+<screen>
 $ ./configure <replaceable>options...</replaceable>
 $ make
 $ make install</screen>
 
-    <para>
-      Currently, the only useful switch for <command>configure</command> is
-      <option>--prefix=<replaceable>prefix</replaceable></option> to specify
-      where Nix is to be installed.  The default installation directory is
-      <filename>/nix</filename>.  You can change this to any location you like.
-      You should ensure that you have write permission to the installation
-      prefix. 
+<para>When building from the Subversion repository, these should be
+preceded by the command:
     </para>
 
-    <warning>
-      <para>
-	It is advisable <emphasis>not</emphasis> to change the installation
-	prefix, since doing so will in all likelihood make it impossible to use
-	derivates built on other systems.
-      </para>
-    </warning>
+<screen>
+$ autoreconf -i</screen>
+
+<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>/nix</filename>.  You can change this to any location you
+like.  You must have write permission to the
+<replaceable>prefix</replaceable> path.</para>
+
+<warning><para>It is advisable <emphasis>not</emphasis> to change the
+installation prefix from its default, since doing so will in all
+likelihood make it impossible to use derivations built on other
+systems.</para></warning>
+
+<para>If you want to rebuilt the documentation, pass the full path to
+the DocBook XML catalog file (<filename>docbook.cat</filename>) and to
+the DocBook XSL stylesheets using the
+<option>--with-docbook-catalog=<replaceable>path</replaceable></option>
+and
+<option>--with-docbook-xsl=<replaceable>path</replaceable></option>
+options.</para>
+
+</sect1>
+
+
+<sect1><title>Installing from RPMs</title>
+
+<para>RPM packages of Nix can be downloaded from <ulink
+url='http://www.cs.uu.nl/groups/ST/Trace/Nix' />.  These RPMs should
+work for most fairly recent releases of SuSE and Red Hat Linux.  They
+have been known to work work on SuSE Linux 8.1 and 9.0, and Red Hat
+9.0.  In fact, it should work on any RPM-based Linux distribution
+based on <literal>glibc</literal> 2.3 or later.</para>
+
+<para>Once downloaded, the RPMs can be installed or upgraded using
+<command>rpm -U</command>.  For example,</para>
+
+<screen>
+$ rpm -U nix-0.5pre664-1.i386.rpm</screen>
+
+<para>The RPMs install into the directory <filename>/nix</filename>.
+Nix can be uninstalled using <command>rpm -e nix</command>.  After
+this it will be necessary to manually remove the Nix store and other
+auxiliary data:</para>
+
+<screen>
+$ rm -rf /nix/store
+$ rm -rf /nix/var</screen>
+
+</sect1>
+
+
+<sect1><title>Permissions</title>
+
+<para>All Nix operations must be performed under the user ID that owns
+the Nix store and database
+(<filename><replaceable>prefix</replaceable>/store</filename> and
+<filename><replaceable>prefix</replaceable>/var/nix/db</filename>,
+respectively).  When installed from the RPM packages, these
+directories are owned by <systemitem
+class='username'>root</systemitem>.</para>
+
+<sect2><title>Setuid installation</title>
+
+<para>As a somewhat <emphasis>ad hoc</emphasis> hack, you can also
+install the Nix binaries <quote>setuid</quote> so that a Nix store can
+be shared among several users.  To do this, configure Nix with the
+<emphasis>--enable-setuid</emphasis> option.  Nix will be installed as
+owned by a user and group specified by the
+<option>--with-nix-user=<parameter>user</parameter></option> and
+<option>--with-nix-group=<parameter>group</parameter></option>
+options.  E.g.,
+
+<screen>
+$ ./configure --enable-setuid --with-nix-user=my_nix_user --with-nix-group=my_nix_group</screen>
+
+The user and group default to <literal>nix</literal>.  You should make
+sure that both the user and the group exist.  Any <quote>real</quote>
+users that you want to allow access should be added to the Nix
+group.</para>
+
+<warning><para>A setuid installation should only by used if the users
+in the Nix group are mutually trusted, since any user in that group
+has the ability to change anything in the Nix store or database.  For
+instance, they could install a trojan horse in executables used by
+other users.</para></warning>
+
+<warning><para>On some platforms, the Nix binaries will be installed
+as setuid <literal>root</literal>.  They drop root privileges
+immediately after startup and switch to the Nix user.  The reason for
+this is that both the real and effective user must be set to the Nix
+user, and POSIX has no system call to do this.  This is not the case
+on systems that have the <function>setresuid()</function> system call
+(such as Linux and FreeBSD), so on those systems the binaries are
+simply owned by the Nix user.</para></warning>
+
+</sect2>
+
+</sect1>
+
+
+<sect1><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>
+
+</sect1>
 
-  </sect1>
 
 </chapter>
-
-<!--
-local variables:
-sgml-parent-document: ("book.xml" "chapter")
-end:
--->

doc/manual/introduction.xml

@@ -1,184 +1,150 @@
-<chapter>
-  <title>Introduction</title>
-
-  <sect1>
-    <title>The problem space</title>
-
-    <para>
-      Nix is a system for controlling the automatic creation and distribution
-      of data, such as computer programs and other software artifacts.  This is
-      a very general problem, and there are many applications that fall under
-      this description.
-    </para>
-
-    <sect2>
-      <title>Build management</title>
-
-      <para>
-	Build management tools are used to perform <emphasis>software
-	  builds</emphasis>, that is, the construction of derived products such
-	as executable programs from source code.  A commonly used build tool is
-	Make, which is a standard tool on Unix systems. These tools have to
-	deal with several issues:
-	<itemizedlist>
-	  <listitem>
-	    <para>
-	    </para>
-	  </listitem>
-	</itemizedlist>
-      </para>
-
-    </sect2>
-
-    <sect2>
-      <title>Package management</title>
-
-      <para>
-	After software has been built, is must also be
-	<emphasis>deployed</emphasis> in the intended target environment, e.g.,
-	the user's workstation.  Examples include the Red Hat package manager
-	(RPM), Microsoft's MSI, and so on.  Here also we have to deal with
-	several issues:
-	<itemizedlist>
-	  <listitem>
-	    <para>
-	      The <emphasis>creation</emphasis> of packages from some formal
-	      description of what artifacts should be distributed in the
-	      package.
-	    </para>
-	  </listitem>
-	  <listitem>
-	    <para>
-	      The <emphasis>deployment</emphasis> of packages, that is, the
-	      mechanism by which we get them onto the intended target
-	      environment.  This can be as simple as copying a file, but
-	      complexity comes from the wide range of possible installation
-	      media (such as a network install), and the scalability of the
-	      process (if a program must be installed on a thousand systems, we
-	      do not want to visit each system and perform some manual steps to
-	      install the program on that system; that is, the complexity for
-	      the system administrator should be constant, not linear).
-	    </para>
-	  </listitem>
-	</itemizedlist>
-      </para>
-    </sect2>
-
-  </sect1>
-
-
-  <!--######################################################################-->
-
-  <sect1>
-    <title>What Nix can do for you</title>
-
-    <para>
-      Here is a summary of what Nix provides:
-    </para>
-
-    <itemizedlist>
-
-      <listitem>
-	<para>
-	  <emphasis>Reliable dependencies.</emphasis>
-	</para>
-      </listitem>
-
-      <listitem>
-	<para>
-	  <emphasis>Support for variability.</emphasis>
-	</para>
-      </listitem>
-
-      <listitem>
-	<para>
-	  <emphasis>Transparent source/binary deployment.</emphasis>
-	</para>
-      </listitem>
-
-      <listitem>
-	<para>
-	  <emphasis>Easy configuration duplication.</emphasis>
-	</para>
-      </listitem>
-
-      <listitem>
-	<para>
-	  <emphasis>Automatic storage management.</emphasis>
-	</para>
-      </listitem>
-
-      <listitem>
-	<para>
-	  <emphasis>Atomic upgrades and rollbacks.</emphasis>
-	</para>
-      </listitem>
-
-      <listitem>
-	<para>
-	  <emphasis>Support for many simultaneous configurations.</emphasis>
-	</para>
-      </listitem>
-
-    </itemizedlist>
-
-    <para>
-      Here is what Nix doesn't yet provide, but will:
-    </para>
-
-    <itemizedlist>
-
-      <listitem>
-	<para>
-	  <emphasis>Build management.</emphasis>  In principle it is already
-	  possible to do build management using Fix (by writing builders that
-	  perform appropriate build steps), but the Fix language is not yet
-	  powerful enough to make this pleasant.  The <ulink
-	    url='http://www.cs.uu.nl/~eelco/maak/'>Maak build manager</ulink>
-	  should be retargeted to produce Nix expressions, or alternatively,
-	  extend Fix with Maak's semantics and concrete syntax (since Fix needs
-	  a concrete syntax anyway).  Another interesting idea is to write a
-	  <command>make</command> implementation that uses Nix as a back-end to
-	  support <ulink
-	    url='http://www.research.att.com/~bs/bs_faq.html#legacy'>legacy</ulink> 
-	  build files.
-	</para>
-      </listitem>
-
-    </itemizedlist>
-
-  </sect1>
-
-
-  <!--######################################################################-->
-
-  <sect1>
-    <title>The Nix system</title>
-
-    <para>
-      ...
-    </para>
-
-    <para>
-      Existing tools in this field generally both a underlying model (such as
-      the derivation graph of build tools, or the versioning scheme that
-      determines when two packages are <quote>compatible</quote> in a package
-      management system) and a formalism that allows ...
-    </para>
-
-    <para>
-      Following the principle of separation of mechanism and policy, the Nix
-      system separates the <emphasis>low-level aspect</emphasis> of file system
-      object management form the <emphasis>high-level aspect</emphasis> of the
-      ...
-    </para>
-
-  </sect1>
-
-</chapter>
+<chapter><title>Introduction</title>
 
 <!--
-local variables:
-sgml-parent-document: ("book.xml" "chapter")
-end:
+<epigraph><para><quote>The number of Nix installations in the world
+has grown to 5, with more expected.</quote></para></epigraph>
 -->
+
+<para>Nix is a system for the deployment of software.  Software
+deployment is concerned with the creation, distribution, and
+management of software components (<quote>packages</quote>).  Its main
+features are:
+
+<itemizedlist>
+
+<listitem><para>It helps you make sure that dependency specifications
+are complete.  In general in a deployment system you have to specify
+for each component what its dependencies are, but there are no
+guarantees that this specification is complete.  If you forget a
+dependency, then the component will build and work correctly on
+<emphasis>your</emphasis> machine if you have the dependency
+installed, but not on the end user's machine if it's not
+there.</para></listitem>
+
+<listitem><para>It is possible to have <emphasis>multiple versions or
+variants</emphasis> of a component installed at the same time.  In
+contrast, in systems such as RPM different versions of the same
+package tend to install to the same location in the file system, so
+installing one version will remove the other.  This is especially
+important if you want to use applications that have conflicting
+requirements on different versions of a component (e.g., application A
+requires version 1.0 of library X, while application B requires a
+non-backwards compatible version 1.1).</para></listitem>
+
+<listitem><para>Users can have different <quote>views</quote>
+(<quote>profiles</quote> in Nix parlance) on the set of installed
+applications in a system.  For instance, one user can have version 1.0
+of some package visible, while another is using version 1.1, and a
+third doesn't use it at all.</para></listitem>
+
+<listitem><para>It is possible to atomically
+<emphasis>upgrade</emphasis> software.  I.e., there is no time window
+during an upgrade in which part of the old version and part of the new
+version are simultaneously visible (which might well cause the
+component to fail).</para></listitem>
+
+<listitem><para>Likewise, it is possible to atomically roll back after
+an install, upgrade, or uninstall action.  That is, in a fast (O(1))
+operation the previous configuration of the system can be restored.
+This is because upgrade or uninstall actions don't actually remove
+components from the system.</para></listitem>
+
+<listitem><para>Unused components can be
+<emphasis>garbage-collected</emphasis> automatically and safely: when
+you remove an application from a profile, its dependencies will be
+deleted by the garbage collector only if there are no other active
+applications using them.</para></listitem>
+
+<listitem><para>Nix supports both source-based deployment models
+(where you distribute <emphasis>Nix expressions</emphasis> that tell
+Nix how to build software from source) and binary-based deployment
+models.  The latter is more-or-less transparent: installation of
+components is always based on Nix expressions, but if the expressions
+have been built before and Nix knows that the resulting binaries are
+available somewhere, it will use those instead.</para></listitem>
+
+<listitem><para>Nix is flexible in the deployment policies that it
+supports.  There is a clear separation between the tools that
+implement basic Nix <emphasis>mechanisms</emphasis> (e.g., building
+Nix expressions), and the tools that implement various deployment
+<emphasis>policies</emphasis>.  For instance, there is a concept of
+<quote>Nix channels</quote> that can be used to keep software
+installations up-to-date automatically from a network source.  This is
+a policy that is implemented by a fairly short Perl script, which can
+be adapted easily to achieve similar policies.</para></listitem>
+
+<listitem><para>Nix component builds aim to be <quote>pure</quote>;
+that is, unaffected by anything other than the declared dependencies.
+This means that if a component was built successfully once, it can be
+rebuilt again on another machine and the result will be the same.  We
+cannot <emphasis>guarantee</emphasis> this (e.g., if the build depends
+on the time-of-day), but Nix (and the tools in the Nix Packages
+collection) takes special care to help achieve this.</para></listitem>
+
+<listitem><para>Nix expressions (the things that tell Nix how to build
+components) are self-contained: they describe not just components but
+complete compositions.  In other words, Nix expressions also describe
+how to build all the dependencies.  This is in contrast to component
+specification languages like RPM spec files, which might say that a
+component X depends on some other component Y, but since it does not
+describe <emphasis>exactly</emphasis> what Y is, the result of
+building or running X might be different on different machines.
+Combined with purity, self-containedness ensures that a component that
+<quote>works</quote> on one machine also works on another, when
+deployed using Nix.</para></listitem>
+
+<listitem><para>The Nix expression language makes it easy to describe
+variability in components (e.g., optional features or
+dependencies).</para></listitem>
+
+<listitem><para>Nix is ideal for building build farms that do
+continuous builds of software from a version management system, since
+it can take care of building all the dependencies as well.  Also, Nix
+only rebuilds components that have changed, so there are no
+unnecessary builds.  In addition, Nix can transparently distribute
+build jobs over different machines, including different
+platforms.</para></listitem>
+
+<listitem><para>Nix can be used not only for software deployment, but
+also for <emphasis>service deployment</emphasis>, such as the
+deployment of a complete web server with all its configuration files,
+static pages, software dependencies, and so on.  Nix's advantages for
+software deployment also apply here: for instance, the ability
+trivially to have multiple configurations at the same time, or the
+ability to do rollbacks.</para></listitem>
+
+<listitem><para>Nix can efficiently upgrade between different versions
+of a component through <emphasis>binary patching</emphasis>.  If
+patches are available on a server, and you try to install a new
+version of some component, Nix will automatically apply a patch (or
+sequence of patches), if available, to transform the installed
+component into the new version.</para></listitem> 
+
+</itemizedlist>
+
+</para>
+
+<para>This manual tells you how to install and use Nix and how to
+write Nix expressions for software not already in the Nix Packages
+collection.  It also discusses some advanced topics, such as setting
+up a Nix-based build farm, and doing service deployment using
+Nix.</para>
+
+<note><para>Some background information on Nix can be found in three
+papers.  The ICSE 2004 paper <ulink
+url='http://www.cs.uu.nl/~eelco/pubs/immdsd-icse2004-final.pdf'><citetitle>Imposing
+a Memory Management Discipline on Software
+Deployment</citetitle></ulink> discusses the hashing mechanism used to
+ensure reliable dependency identification and non-interference between
+different versions and variants of packages.  The LISA 2004 paper
+<ulink
+url='http://www.cs.uu.nl/~eelco/pubs/nspfssd-lisa2004-final.pdf'><citetitle>Nix:
+A Safe and Policy-Free System for Software
+Deployment</citetitle></ulink> gives a more general discussion of Nix
+from a system-administration perspective.  The CBSE 2005 paper <ulink
+url='http://www.cs.uu.nl/~eelco/pubs/eupfcdm-cbse2005-final.pdf'><citetitle>Efficient
+Upgrading in a Purely Functional Component Deployment Model
+</citetitle></ulink> is about transparent patch deployment in
+Nix.</para></note>
+
+</chapter>

doc/manual/manual.xml

@@ -0,0 +1,83 @@
+<?xml version="1.0"?>
+<!DOCTYPE book
+    PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+    "http://www.docbook.org/xml/4.3/docbook-xml-4.3.zip"
+[
+]>
+
+<book>
+  <title>Nix User's Guide</title>
+
+  <subtitle>Draft (Version <xi:include
+  xmlns:xi="http://www.w3.org/2001/XInclude"
+  href="version.txt" parse="text" />)</subtitle>
+  
+  <bookinfo>
+    <author>
+      <firstname>Eelco</firstname>
+      <surname>Dolstra</surname>
+    </author>
+    <copyright>
+      <year>2004</year>
+      <year>2005</year>
+      <holder>Eelco Dolstra</holder>
+    </copyright>
+  </bookinfo>
+  
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="introduction.xml" />
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="quick-start.xml" />
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="installation.xml" />
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="package-management.xml" />
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="writing-nix-expressions.xml" />
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="build-farm.xml" />
+
+  <appendix>
+    <title>Command Reference</title>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common.xml" />
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="env-common.xml" />
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="conf-file.xml" />
+    <sect1 id="sec-nix-env">
+      <title>nix-env</title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-env.xml" />
+    </sect1>
+    <sect1 id="sec-nix-build">
+      <title>nix-build</title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-build.xml" />
+    </sect1>
+    <sect1>
+      <title>nix-store</title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-store.xml" />
+    </sect1>
+    <sect1 id="sec-nix-instantiate">
+      <title>nix-instantiate</title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-instantiate.xml" />
+    </sect1>
+    <sect1>
+      <title>nix-collect-garbage</title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-collect-garbage.xml" />
+    </sect1>
+    <sect1 id="sec-nix-channel">
+      <title>nix-channel</title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-channel.xml" />
+    </sect1>
+    <sect1>
+      <title>nix-push</title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-push.xml" />
+    </sect1>
+    <sect1>
+      <title>nix-pull</title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-pull.xml" />
+    </sect1>
+    <sect1>
+      <title>nix-prefetch-url</title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-prefetch-url.xml" />
+    </sect1>
+  </appendix>
+
+  <!--  &nix-lang-ref; -->
+
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="troubleshooting.xml" />
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="bugs.xml" />
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="glossary.xml" />
+
+</book>

doc/manual/nix-build.xml

@@ -0,0 +1,74 @@
+<refentry>
+  
+<refnamediv>
+  <refname>nix-build</refname>
+  <refpurpose>build a Nix expression</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-build</command>
+    <arg><option>--add-drv-link</option></arg>
+    <arg><option>--no-link</option></arg>
+    <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsection><title>Description</title>
+
+<para>The <command>nix-build</command> command builds the derivations
+described by the Nix expressions in <replaceable>paths</replaceable>.
+If the build succeeds, it places a symlink to the result in the
+current directory.  The symlink is called <filename>result</filename>.
+If there are multiple Nix expressions, or the Nix expressions evaluate
+to multiple derivations, multiple sequentially numbered symlinks are
+created (<filename>result</filename>, <filename>result-2</filename>,
+and so on).</para>
+
+<note><para><command>nix-build</command> is essentially a wrapper
+around <link
+linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>
+(to translate a high-level Nix expression to a low-level store
+derivation) and <link
+linkend="rsec-nix-store-realise"><command>nix-store
+--realise</command></link> (to build the store
+derivation).</para></note>
+
+<warning><para>The result of the build is automatically registered as
+a root of the Nix garbage collector.  This root disappears
+automatically when the <filename>result</filename> symlink is deleted
+or renamed.  So don’t rename the symlink.</para></warning>
+
+</refsection>
+
+
+<refsection><title>Options</title>
+
+<variablelist>
+
+  <varlistentry><term><option>--add-drv-link</option></term>
+  
+    <listitem><para>Add a symlink in the current directory to the
+    store derivation produced by <command>nix-instantiate</command>.
+    The symlink is called <filename>derivation</filename> (which is
+    numbered in the case of multiple derivations).  The derivation is
+    a root of the garbage collector until the symlink is deleted or
+    renamed.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><option>--no-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
+    --gc</command>.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+</refentry>

doc/manual/nix-channel.xml

@@ -0,0 +1,83 @@
+<refentry>
+  
+<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>
+      <arg choice='plain'><option>--remove</option> <replaceable>url</replaceable></arg>
+      <arg choice='plain'><option>--list</option></arg>
+      <arg choice='plain'><option>--update</option></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 that contains a set of Nix
+expressions, as well as a <command>nix-push</command> manifest.  See
+also <xref linkend="sec-channels" />.</para>
+
+<para>This command has the following operations:
+
+<variablelist>
+
+  <varlistentry><term><option>--add</option> <replaceable>url</replaceable></term>
+
+    <listitem><para>Adds <replaceable>url</replaceable> to the list of
+    subscribed channels.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--remove</option> <replaceable>url</replaceable></term>
+
+    <listitem><para>Removes <replaceable>url</replaceable> from the
+    list of subscribed channels.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--list</option></term>
+
+    <listitem><para>Prints the URLs of all subscribed channels on
+    standard output.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--update</option></term>
+
+    <listitem><para>Downloads the Nix expressions of all subscribed
+    channels, makes the conjunction of these the default for
+    <command>nix-env</command> operations (by calling <command>nix-env
+    -I</command>), and performs a <command>nix-pull</command> on the
+    manifests of all channels to make pre-built binaries
+    available.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</para>
+
+<para>Note that <option>--add</option> and <option>--remove</option>
+do not automatically perform an update.</para>
+
+<para>The list of subscribed channels is stored in
+<filename>~/.nix-channels</filename>.</para>
+
+<para>A channel consists of two elements: a bzipped Tar archive
+containing the Nix expressions, and a manifest created by
+<command>nix-push</command>.  These must be stored under
+<literal><replaceable>url</replaceable>/nixexprs.tar.bz2</literal> and
+<literal><replaceable>url</replaceable>/MANIFEST</literal>,
+respectively.</para>
+
+</refsection>
+
+</refentry>

doc/manual/nix-collect-garbage.xml

@@ -0,0 +1,29 @@
+<refentry>
+  
+<refnamediv>
+  <refname>nix-collect-garbage</refname>
+  <refpurpose>delete unreachable store paths</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-collect-garbage</command>
+    <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>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsection><title>Description</title>
+
+<para>The command <command>nix-collect-garbage</command> is an
+obsolete wrapper around <link
+linkend="rsec-nix-store-gc"><command>nix-store
+--gc</command></link>.</para>
+
+</refsection>
+
+</refentry>

doc/manual/nix-env.xml

@@ -0,0 +1,928 @@
+<refentry>
+  
+<refnamediv>
+  <refname>nix-env</refname>
+  <refpurpose>manipulate or query Nix user environments</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-env</command>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xpointer(/nop/*)" />
+    <arg>
+      <group choice='req'>
+        <arg choice='plain'><option>--file</option></arg>
+        <arg choice='plain'><option>-f</option></arg>
+      </group>
+      <replaceable>path</replaceable>
+    </arg>
+    <arg>
+      <group choice='req'>
+        <arg choice='plain'><option>--profile</option></arg>
+        <arg choice='plain'><option>-p</option></arg>
+      </group>
+      <replaceable>path</replaceable>
+    </arg>
+    <arg><option>--preserve-installed</option></arg>
+    <arg>
+      <arg choice='plain'><option>--system-filter</option></arg>
+      <replaceable>system</replaceable>
+    </arg>
+    <arg><option>--dry-run</option></arg>
+    <arg><option>--from-expression</option></arg>
+    <arg><option>-E</option></arg>
+    <arg><option>--from-profile</option> <replaceable>path</replaceable></arg>
+    <arg choice='plain'><replaceable>operation</replaceable></arg>
+    <arg rep='repeat'><replaceable>options</replaceable></arg>
+    <arg rep='repeat'><replaceable>arguments</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>The command <command>nix-env</command> is used to manipulate Nix
+user environments.  User environments are sets of software components
+available to a user at some point in time.  In other words, they are a
+synthesised view of the programs available in the Nix store.  There
+may be many user environments: different users can have different
+environments, and individual users can switch between different
+environments.</para>
+
+<para><command>nix-env</command> takes exactly one
+<emphasis>operation</emphasis> flag which indicates the subcommand to
+be performed.  These are documented below.</para>
+    
+</refsection>
+
+
+
+<!--######################################################################-->
+
+<refsection><title>Common options</title>
+
+<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" />.</para>
+
+<variablelist>
+
+  <varlistentry><term><option>--file</option></term>
+    <term><option>-f</option></term>
+  
+    <listitem><para>Specifies the Nix expression (designated below as
+    the <emphasis>active Nix expression</emphasis>) used by the
+    <option>--install</option>, <option>--upgrade</option>, and
+    <option>--query --available</option> operations to obtain
+    derivations.  The default is
+    <filename>~/.nix-defexpr</filename>.</para></listitem>
+    
+  </varlistentry>
+      
+  <varlistentry><term><option>--profile</option></term>
+    <term><option>-p</option></term>
+  
+    <listitem><para>Specifies the profile to be used by those
+    operations that operate on a profile (designated below as the
+    <emphasis>active profile</emphasis>).  A profile is sequence of
+    user environments called <emphasis>generations</emphasis>, one of
+    which is the <emphasis>current generation</emphasis>.  The default
+    profile is the target of the symbolic link
+    <filename>~/.nix-profile</filename> (see below).</para></listitem>
+    
+  </varlistentry>
+      
+  <varlistentry><term><option>--dry-run</option></term>
+  
+    <listitem><para>For the <option>--install</option>,
+    <option>--upgrade</option>, <option>--uninstall</option>,
+    <option>--switch-generation</option> and
+    <option>--rollback</option> operations, this flag will cause
+    <command>nix-env</command> to print what
+    <emphasis>would</emphasis> be done if this flag had not been
+    specified, without actually doing it.</para></listitem>
+    
+  </varlistentry>
+      
+  <varlistentry><term><option>--preserve-installed</option></term>
+  
+    <listitem><para>By default, when you install a derivation with the
+    <option>--install</option> operation, it will replace previously
+    installed versions with the same derivation name (regardless of
+    the version number).  This option causes those previously
+    installed versions to be kept in the new generation of the
+    profile.  Note that this will generally cause conflicts in the
+    creation of the user environment (since multiple versions of a
+    package typically contain the same programs).</para></listitem>
+    
+  </varlistentry>
+      
+  <varlistentry><term><option>--system-filter</option> <replaceable>system</replaceable></term>
+  
+    <listitem><para>By default, operations such as <option>--query
+    --available</option> only include derivations matching the current
+    platform.  This option allows you to use derivations for the
+    specified platform <replaceable>system</replaceable>.  The special
+    value <literal>*</literal> causes derivations for any platform to
+    be included.</para></listitem>
+    
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+  
+
+<!--######################################################################-->
+
+<refsection><title>Files</title>
+
+<variablelist>
+
+  <varlistentry><term><filename>~/.nix-defexpr</filename></term>
+  
+    <listitem><para>The default Nix expression used by the
+    <option>--install</option>, <option>--upgrade</option>, and
+    <option>--query --available</option> operations to obtain
+    derivations.  It is generally a symbolic link to some other
+    location set using the <option>--import</option> operation.  The
+    <option>--file</option> option may be used to override this
+    default.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><filename>~/.nix-profile</filename></term>
+  
+    <listitem><para>A symbolic link to the user's current profile.  By
+    default, this symlink points to
+    <filename><replaceable>prefix</replaceable>/var/nix/profiles/default</filename>.
+    The <envar>PATH</envar> environment variable should include
+    <filename>~/.nix-profile/bin</filename> for the user environment
+    to be visible to the user.</para></listitem>
+    
+  </varlistentry>
+
+</variablelist>
+        
+</refsection>
+
+  
+
+<!--######################################################################-->
+
+<refsection id="rsec-nix-env-install"><title>Operation <option>--install</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-env</command>
+  <group choice='req'>
+    <arg choice='plain'><option>--install</option></arg>
+    <arg choice='plain'><option>-i</option></arg>
+  </group>
+  <group choice='opt'>
+    <arg choice='plain'><option>--preserve-installed</option></arg>
+    <arg choice='plain'><option>-P</option></arg>
+  </group>
+  <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
+</cmdsynopsis>
+
+</refsection>
+
+
+<refsection><title>Description</title>
+            
+<para>The install operation creates a new user environment, based on
+the current generation of the active profile, to which a set of store
+paths described by <replaceable>args</replaceable> is added.  The
+arguments <replaceable>args</replaceable> map to store paths in a
+number of possible ways:
+
+<itemizedlist>
+
+  <listitem><para>By default, <replaceable>args</replaceable> is a set
+  of derivation names denoting derivations in the active Nix
+  expression.  These are realised, and the resulting output paths are
+  installed.  Currently installed derivations with a name equal to the
+  name of a derivation being added are removed unless the option
+  <option>--preserve-installed</option> is
+  specified.</para></listitem>
+
+  <listitem><para>If <option>--from-profile</option>
+  <replaceable>path</replaceable> is given,
+  <replaceable>args</replaceable> is a set of names denoting installed
+  store paths in the profile <replaceable>path</replaceable>.  This is
+  an easy way to copy user environment elements from one profile to
+  another.</para></listitem>
+
+  <listitem><para>If <option>--from-expression</option> is given,
+  <replaceable>args</replaceable> are Nix <link
+  linkend="ss-functions">functions</link> that are called with the
+  active Nix expression as their single argument.  The derivations
+  returned by those function calls are installed.  This allows
+  derivations to be specified in a unambiguous way, which is necessary
+  if there are multiple derivations with the same
+  name.</para></listitem>
+
+  <listitem><para>If <replaceable>args</replaceable> are store
+  derivations, then these are <link
+  linkend="rsec-nix-store-realise">realised</link>, and the resulting
+  output paths are installed.</para></listitem>
+
+  <listitem><para>If <replaceable>args</replaceable> are store paths
+  that are not store derivations, then these are <link
+  linkend="rsec-nix-store-realise">realised</link> and
+  installed.</para></listitem>
+
+</itemizedlist>
+
+</para>
+
+</refsection>
+
+
+<refsection><title>Flags</title>
+
+<variablelist>
+
+  <varlistentry><term><option>--preserve-installed</option></term>
+    <term><option>-P</option></term>
+  
+    <listitem><para>Do not remove derivations with a name matching one
+    of the derivations being installed.  Usually, trying to have two
+    versions of the same package installed in the same generation of a
+    profile will lead to an error in building the generation, due to
+    file name clashes between the two versions.  However, this is not
+    the case for all packages.</para></listitem>
+    
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+            
+
+<refsection><title>Examples</title>
+
+<para>To install a specific version of <command>gcc</command> from the
+active Nix expression:
+
+<screen>
+$ nix-env --install gcc-3.3.2 
+installing `gcc-3.3.2'
+uninstalling `gcc-3.1'</screen>
+
+Note the the previously installed version is removed, since
+<option>--preserve-installed</option> was not specified.</para>
+
+<para>To install an arbitrary version:
+
+<screen>
+$ nix-env --install gcc
+installing `gcc-3.3.2'</screen>
+
+</para>
+
+<para>To install all derivations in the Nix expression <filename>foo.nix</filename>:
+
+<screen>
+$ nix-env -f ~/foo.nix -i '*'</screen>
+
+</para>
+
+<para>To copy the store path with symbolic name <literal>gcc</literal>
+from another profile:
+
+<screen>
+$ nix-env -i --from-profile /nix/var/nix/profiles/foo -i gcc</screen>
+
+</para>
+
+<para>To install a specific store derivation (typically created by
+<command>nix-instantiate</command>):
+
+<screen>
+$ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv</screen>
+
+</para>
+
+<para>To install a specific output path:
+
+<screen>
+$ nix-env -i /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3</screen>
+
+</para>
+
+<para>To install from a Nix expression specified on the command-line:
+
+<screen>
+$ nix-env -f ./foo.nix -i -E \
+    'f: (f {system = "i686-linux";}).subversionWithJava'</screen>
+
+I.e., this evaluates to <literal>(f: (f {system =
+"i686-linux";}).subversionWithJava) (import ./foo.nix)</literal>, thus
+selecting the <literal>subversionWithJava</literal> attribute from the
+attribute set returned by calling the function defined in
+<filename>./foo.nix</filename>.</para>
+
+</refsection>
+    
+</refsection>
+
+
+  
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--upgrade</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-env</command>
+  <group choice='req'>
+    <arg choice='plain'><option>--upgrade</option></arg>
+    <arg choice='plain'><option>-u</option></arg>
+  </group>
+  <group choice='opt'>
+    <arg choice='plain'><option>--lt</option></arg>
+    <arg choice='plain'><option>--leq</option></arg>
+    <arg choice='plain'><option>--always</option></arg>
+  </group>
+  <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
+</cmdsynopsis>
+
+</refsection>
+
+<refsection><title>Description</title>
+            
+<para>The upgrade operation creates a new user environment, based on
+the current generation of the active profile, in which all store paths
+are replaced for which there are newer versions in the set of paths
+described by <replaceable>args</replaceable>.  Paths for which there
+are no newer versions are left untouched; this is not an error.  It is
+also not an error if an element of <replaceable>args</replaceable>
+matches no installed derivations.</para>
+
+<para>For a description of how <replaceable>args</replaceable> is
+mapped to a set of store paths, see <link
+linkend="rsec-nix-env-install"><option>--install</option></link>.  If
+<replaceable>args</replaceable> describes multiple store paths with
+the same symbolic name, only the one with the highest version is
+installed.</para>
+
+</refsection>
+            
+<refsection><title>Flags</title>
+
+<variablelist>
+
+  <varlistentry><term><option>--lt</option></term>
+  
+    <listitem><para>Only upgrade a derivation to newer versions.  This
+    is the default.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><option>--leq</option></term>
+  
+    <listitem><para>In addition to upgrading to newer versions, also
+    “upgrade” to derivations that have the same version.  Version are
+    not a unique identification of a derivation, so there may be many
+    derivations that have the same version.  This flag may be useful
+    to force “synchronisation” between the installed and available
+    derivations.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><option>--always</option></term>
+  
+    <listitem><para>In addition to upgrading to newer versions, also
+    “upgrade” to derivations that have the same or a lower version.
+    I.e., derivations may actually be downgraded depending on what is
+    available in the active Nix expression.</para></listitem>
+    
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+<refsection><title>Examples</title>
+
+<screen>
+$ nix-env --upgrade gcc
+upgrading `gcc-3.3.1' to `gcc-3.4'
+
+$ nix-env -u gcc-3.3.2 --always <lineannotation>(switch to a specific version)</lineannotation>
+upgrading `gcc-3.4' to `gcc-3.3.2'
+
+$ nix-env --upgrade pan
+<lineannotation>(no upgrades available, so nothing happens)</lineannotation>
+
+$ nix-env -u '*' <lineannotation>(try to upgrade everything)</lineannotation>
+upgrading `hello-2.1.2' to `hello-2.1.3'
+upgrading `mozilla-1.2' to `mozilla-1.4'</screen>        
+
+</refsection>
+    
+<refsection><title>Versions</title>
+
+<para>The upgrade operation determines whether a derivation
+<varname>y</varname> is an upgrade of a derivation
+<varname>x</varname> by looking at their respective
+<literal>name</literal> attributes.  The names (e.g.,
+<literal>gcc-3.3.1</literal> are split into two parts: the package
+name (<literal>gcc</literal>), and the version
+(<literal>3.3.1</literal>).  The version part starts after the first
+dash not following by a letter.  <varname>x</varname> is considered an
+upgrade of <varname>y</varname> if their package names match, and the
+version of <varname>y</varname> is higher that that of
+<varname>x</varname>.</para>
+
+<para>The versions are compared by splitting them into contiguous
+components of numbers and letters.  E.g., <literal>3.3.1pre5</literal>
+is split into <literal>[3, 3, 1, "pre", 5]</literal>.  These lists are
+then compared lexicographically (from left to right).  Corresponding
+components <varname>a</varname> and <varname>b</varname> are compared
+as follows.  If they are both numbers, integer comparison is used.  If
+<varname>a</varname> is an empty string and <varname>b</varname> is a
+number, <varname>a</varname> is considered less than
+<varname>b</varname>.  The special string component
+<literal>pre</literal> (for <emphasis>pre-release</emphasis>) is
+considered to be less than other components.  String components are
+considered less than number components.  Otherwise, they are compared
+lexicographically (i.e., using case-sensitive string comparison).</para>
+
+<para>This is illustrated by the following examples:
+
+<screen>
+1.0 &lt; 2.3
+2.1 &lt; 2.3
+2.3 = 2.3
+2.5 > 2.3
+3.1 > 2.3
+2.3.1 > 2.3
+2.3.1 > 2.3a
+2.3pre1 &lt; 2.3
+2.3pre3 &lt; 2.3pre12
+2.3a &lt; 2.3c
+2.3pre1 &lt; 2.3c
+2.3pre1 &lt; 2.3q</screen>
+        
+</para>
+
+</refsection>
+            
+</refsection>
+
+  
+
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--uninstall</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-env</command>
+  <group choice='req'>
+    <arg choice='plain'><option>--uninstall</option></arg>
+    <arg choice='plain'><option>-e</option></arg>
+  </group>
+  <arg choice='plain' rep='repeat'><replaceable>drvnames</replaceable></arg>
+</cmdsynopsis>
+</refsection>
+
+<refsection><title>Description</title>
+            
+<para>The uninstall operation creates a new user environment, based on
+the current generation of the active profile, from which the store
+paths designated by the symbolic names
+<replaceable>names</replaceable> are removed.</para>
+
+</refsection>
+            
+<refsection><title>Examples</title>
+
+<screen>
+$ nix-env --uninstall gcc
+$ nix-env -e '*' <lineannotation>(remove everything)</lineannotation></screen>
+
+</refsection>
+    
+</refsection>
+
+
+  
+<!--######################################################################-->
+  
+<refsection><title>Operation <option>--query</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-env</command>
+  <group choice='req'>
+    <arg choice='plain'><option>--query</option></arg>
+    <arg choice='plain'><option>-q</option></arg>
+  </group>
+  <group choice='opt'>
+    <arg choice='plain'><option>--installed</option></arg>
+    <arg choice='plain'><option>--available</option></arg>
+    <arg choice='plain'><option>-a</option></arg>
+  </group>
+  <group choice='req'>
+    <arg choice='plain'><option>--name</option></arg>
+    <arg choice='plain'><option>--expr</option></arg>
+    <arg choice='plain'><option>--status</option></arg>
+    <arg choice='plain'><option>-s</option></arg>
+  </group>
+</cmdsynopsis>
+
+</refsection>
+
+
+<refsection><title>Description</title>
+            
+<para>The query operation displays information about either the store
+paths that are installed in the current generation of the active
+profile (<option>--installed</option>), or the derivations that are
+available for installation in the active Nix expression
+(<option>--available</option>).</para>
+
+<para>The derivations are sorted by their <literal>name</literal>
+attributes.</para>
+
+</refsection>
+
+
+<refsection><title>Source selection</title>
+
+<para>The following flags specify the set of things on which the query
+operates.</para>
+
+<variablelist>
+
+  <varlistentry><term><option>--installed</option></term>
+  
+    <listitem><para>The query operates on the store paths that are
+    installed in the current generation of the active profile.  This
+    is the default.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><option>--available</option></term>
+    <term><option>-a</option></term>
+  
+    <listitem><para>The query operates on the derivations that are
+    available in the active Nix expression.</para></listitem>
+    
+  </varlistentry>
+
+</variablelist>
+            
+</refsection>
+
+
+<refsection><title>Queries</title>
+
+<para>The following flags specify what information to display about
+the selected derivations.  Multiple flags may be specified, in which
+case the information is shown in the order given here.  Note that the
+name of the derivation is shown unless <option>--no-name</option> is
+specified.</para>
+
+<!-- TODO: fix the terminology here; i.e., derivations, store paths,
+user environment elements, etc. -->
+
+<variablelist>
+
+  <varlistentry><term><option>--status</option></term>
+    <term><option>-s</option></term>
+  
+    <listitem><para>Print the <emphasis>status</emphasis> of the
+    derivation.  The status consists of three characters.  The first
+    is <literal>I</literal> or <literal>-</literal>, indicating
+    whether the derivation is currently installed in the current
+    generation of the active profile.  This is by definition the case
+    for <option>--installed</option>, but not for
+    <option>--available</option>.  The second is <literal>P</literal>
+    or <literal>-</literal>, indicating whether the derivation is
+    present on the system.  This indicates whether installation of an
+    available derivation will require the derivation to be built.  The
+    third is <literal>S</literal> or <literal>-</literal>, indicating
+    whether a substitute is available for the
+    derivation.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><option>--no-name</option></term>
+  
+    <listitem><para>Suppress printing of the <literal>name</literal>
+    attribute of each derivation.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><option>--system</option></term>
+  
+    <listitem><para>Print the <literal>system</literal> attribute of
+    the derivation.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><option>--drv-path</option></term>
+  
+    <listitem><para>Print the path of the store
+    derivation.</para></listitem>
+    
+  </varlistentry>
+
+  <varlistentry><term><option>--out-path</option></term>
+  
+    <listitem><para>Print the output path of the
+    derivation.</para></listitem>
+    
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<screen>
+$ nix-env -q <lineannotation>(show installed derivations)</lineannotation>
+MozillaFirebird-0.7
+bison-1.875c
+docbook-xml-4.2
+...
+
+$ nix-env -qa <lineannotation>(show available derivations)</lineannotation>
+GConf-2.4.0.1
+MPlayer-1.0pre3
+MozillaFirebird-0.7
+ORBit2-2.8.3
+...
+
+$ nix-env -qas <lineannotation>(show status of available derivations)</lineannotation>
+-P- GConf-2.4.0.1 <lineannotation>(not installed but present)</lineannotation>
+--S MPlayer-1.0pre3 <lineannotation>(not present, but there is a substitute for fast installation)</lineannotation>
+--S MozillaFirebird-0.7 <lineannotation>(i.e., this is not the installed Firebird, even though the version is the same!)</lineannotation>
+IP- bison-1.875c <lineannotation>(installed and by definition present)</lineannotation>
+...
+
+$ nix-env -f ./foo.nix -qa <lineannotation>(show available derivations in the Nix expression <filename>foo.nix</filename>)</lineannotation>
+foo-1.2.3</screen>
+
+</refsection>
+
+</refsection>
+  
+    
+
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--switch-profile</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-env</command>
+  <group choice='req'>
+    <arg choice='plain'><option>--switch-profile</option></arg>
+    <arg choice='plain'><option>-S</option></arg>
+  </group>
+  <arg choice='req'><replaceable>path</replaceable></arg>
+</cmdsynopsis>
+
+</refsection>
+
+
+<refsection><title>Description</title>
+            
+<para>This operation makes <replaceable>path</replaceable> the current
+profile for the user.  That is, the symlink
+<filename>~/.nix-profile</filename> is made to point to
+<replaceable>path</replaceable>.</para>
+
+</refsection>
+            
+<refsection><title>Examples</title>
+
+<screen>
+$ nix-env -S ~/my-profile</screen>
+
+</refsection>
+    
+</refsection>
+
+
+  
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--list-generations</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-env</command>
+  <arg choice='plain'><option>--list-generations</option></arg>
+</cmdsynopsis>
+
+</refsection>
+
+
+<refsection><title>Description</title>
+            
+<para>This operation print a list of all the currently existing
+generations for the active profile.  These may be switched to using
+the <option>--switch-generation</option> operation.  It also prints
+the creation date of the generation, and indicates the current
+generation.</para>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<screen>
+$ nix-env --list-generations
+  95   2004-02-06 11:48:24
+  96   2004-02-06 11:49:01
+  97   2004-02-06 16:22:45
+  98   2004-02-06 16:24:33   (current)</screen>
+
+</refsection>
+    
+</refsection>
+
+
+  
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--delete-generations</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-env</command>
+  <arg choice='plain'><option>--delete-generations</option></arg>
+  <arg choice='plain' rep='repeat'><replaceable>generations</replaceable></arg>
+</cmdsynopsis>
+
+</refsection>
+
+
+<refsection><title>Description</title>
+            
+<para>This operation deletes the specified generations of the current
+profile.  The generations can be a list of generation numbers, or the
+special value <literal>old</literal> to delete all non-current
+generations.  Periodically deleting old generations is important to
+make garbage collection effective.</para>
+
+</refsection>
+            
+<refsection><title>Examples</title>
+
+<screen>
+$ nix-env --delete-generations 3 4 8
+
+$ nix-env -p other_profile --delete-generations old</screen>
+
+</refsection>
+    
+</refsection>
+
+
+  
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--switch-generation</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-env</command>
+  <group choice='req'>
+    <arg choice='plain'><option>--switch-generation</option></arg>
+    <arg choice='plain'><option>-G</option></arg>
+  </group>
+  <arg choice='req'><replaceable>generation</replaceable></arg>
+</cmdsynopsis>
+
+</refsection>
+
+
+<refsection><title>Description</title>
+            
+<para>This operation makes generation number
+<replaceable>generation</replaceable> the current generation of the
+active profile.  That is, if the
+<filename><replaceable>profile</replaceable></filename> is the path to
+the active profile, then the symlink
+<filename><replaceable>profile</replaceable></filename> is made to
+point to
+<filename><replaceable>profile</replaceable>-<replaceable>generation</replaceable>-link</filename>,
+which is in turn a symlink to the actual user environment in the Nix
+store.</para>
+
+<para>Switching will fail if the specified generation does not exist.</para>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<screen>
+$ nix-env -G 42
+switching from generation 50 to 42</screen>
+
+</refsection>
+    
+</refsection>
+
+
+  
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--rollback</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-env</command>
+  <arg choice='plain'><option>--rollback</option></arg>
+</cmdsynopsis>
+
+</refsection>
+
+<refsection><title>Description</title>
+            
+<para>This operation switches to the “previous” generation of the
+active profile, that is, the highest numbered generation lower than
+the current generation, if it exists.  It is just a convenience
+wrapper around <option>--list-generations</option> and
+<option>--switch-generation</option>.</para>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<screen>
+$ nix-env --rollback
+switching from generation 92 to 91
+
+$ nix-env --rolback
+error: no generation older than the current (91) exists</screen>
+
+</refsection>
+    
+</refsection>
+
+
+  
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--import</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-env</command>
+  <group choice='req'>
+    <arg choice='plain'><option>--import</option></arg>
+    <arg choice='plain'><option>-I</option></arg>
+  </group>
+  <arg choice='req'><replaceable>path</replaceable></arg>
+</cmdsynopsis>
+
+</refsection>
+
+
+<refsection><title>Description</title>
+            
+<para>This operation makes <replaceable>path</replaceable> the default
+active Nix expression for the user.  That is, the symlink
+<filename>~/.nix-userenv</filename> is made to point to
+<replaceable>path</replaceable>.</para>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<screen>
+$ nix-env -I ~/nixpkgs-0.5/</screen>
+
+</refsection>
+    
+</refsection>
+
+
+  
+</refentry>

doc/manual/nix-instantiate.xml

@@ -0,0 +1,97 @@
+<refentry>
+  
+<refnamediv>
+  <refname>nix-instantiate</refname>
+  <refpurpose>instantiate store derivations from Nix expressions</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-instantiate</command>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xpointer(/nop/*)" />
+    <arg><option>--add-root</option> <replaceable>path</replaceable></arg>
+    <arg><option>--indirect</option></arg>
+    <group choice='opt'>
+      <arg choice='plain'><option>--parse-only</option></arg>
+      <arg choice='plain'><option>--eval-only</option></arg>
+    </group>
+    <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>The command <command>nix-instantiate</command> generates <link
+linkend="gloss-derivation">store derivations</link> from (high-level)
+Nix expressions.  It 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
+derivations.  The paths of the resulting store derivations are printed
+on standard output.</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>
+
+</refsection>
+
+
+<refsection><title>Options</title>
+
+<variablelist>
+
+  <varlistentry>
+    <term><option>--add-root</option> <replaceable>path</replaceable></term>
+    <term><option>--indirect</option></term>
+
+    <listitem><para>See the <link linkend="opt-add-root">corresponding
+    options</link> in <command>nix-store</command>.</para></listitem>
+
+  </varlistentry>
+
+    
+  <varlistentry><term><option>--parse-only</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>
+  
+    <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>
+
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<screen>
+$ nix-instantiate test.nix <lineannotation>(instantiate)</lineannotation>
+/nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv
+
+$ nix-store -r $(nix-instantiate test.nix) <lineannotation>(build)</lineannotation>
+<replaceable>...</replaceable>
+/nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 <lineannotation>(output path)</lineannotation>
+
+$ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26
+dr-xr-xr-x    2 eelco    users        4096 1970-01-01 01:00 lib
+...</screen>
+
+</refsection>
+
+
+</refentry>

doc/manual/nix-lang-ref.xml

@@ -0,0 +1,277 @@
+<appendix>
+  <title>Nix Language Reference</title>
+
+  <sect1>
+    <title>Grammar</title>
+
+    <productionset>
+      <title>Expressions</title>
+      
+      <production id="nix.expr">
+        <lhs>Expr</lhs>
+        <rhs>
+          <nonterminal def="#nix.expr_function" />
+        </rhs>
+      </production>
+      
+      <production id="nix.expr_function">
+        <lhs>ExprFunction</lhs>
+        <rhs>
+          '{' <nonterminal def="#nix.formals" /> '}' ':' <nonterminal def="#nix.expr_function" />
+          <sbr />|
+          <nonterminal def="#nix.expr_assert" />
+        </rhs>
+      </production>
+      
+      <production id="nix.expr_assert">
+        <lhs>ExprAssert</lhs>
+        <rhs>
+          'assert' <nonterminal def="#nix.expr" /> ';' <nonterminal def="#nix.expr_assert" />
+          <sbr />|
+          <nonterminal def="#nix.expr_if" />
+        </rhs>
+      </production>
+      
+      <production id="nix.expr_if">
+        <lhs>ExprIf</lhs>
+        <rhs>
+          'if' <nonterminal def="#nix.expr" /> 'then' <nonterminal def="#nix.expr" />
+          'else' <nonterminal def="#nix.expr" />
+          <sbr />|
+          <nonterminal def="#nix.expr_op" />
+        </rhs>
+      </production>
+      
+      <production id="nix.expr_op">
+        <lhs>ExprOp</lhs>
+        <rhs>
+          '!' <nonterminal def="#nix.expr_op" />
+          <sbr />|
+          <nonterminal def="#nix.expr_op" /> '==' <nonterminal def="#nix.expr_op" />
+          <sbr />|
+          <nonterminal def="#nix.expr_op" /> '!=' <nonterminal def="#nix.expr_op" />
+          <sbr />|
+          <nonterminal def="#nix.expr_op" /> '&amp;&amp;' <nonterminal def="#nix.expr_op" />
+          <sbr />|
+          <nonterminal def="#nix.expr_op" /> '||' <nonterminal def="#nix.expr_op" />
+          <sbr />|
+          <nonterminal def="#nix.expr_op" /> '->' <nonterminal def="#nix.expr_op" />
+          <sbr />|
+          <nonterminal def="#nix.expr_op" /> '//' <nonterminal def="#nix.expr_op" />
+          <sbr />|
+          <nonterminal def="#nix.expr_op" /> '~' <nonterminal def="#nix.expr_op" />
+          <sbr />|
+          <nonterminal def="#nix.expr_op" /> '?' <nonterminal def="#nix.id" />
+          <sbr />|
+          <nonterminal def="#nix.expr_app" />
+        </rhs>
+      </production>
+      
+      <production id="nix.expr_app">
+        <lhs>ExprApp</lhs>
+        <rhs>
+          <nonterminal def="#nix.expr_app" /> '.' <nonterminal def="#nix.expr_select" />
+          <sbr />|
+          <nonterminal def="#nix.expr_select" />
+        </rhs>
+      </production>
+      
+      <production id="nix.expr_select">
+        <lhs>ExprSelect</lhs>
+        <rhs>
+          <nonterminal def="#nix.expr_select" /> <nonterminal def="#nix.id" />
+          <sbr />|
+          <nonterminal def="#nix.expr_simple" />
+        </rhs>
+      </production>
+      
+      <production id="nix.expr_simple">
+        <lhs>ExprSimple</lhs>
+        <rhs>
+          <nonterminal def="#nix.id" /> |
+          <nonterminal def="#nix.int" /> |
+          <nonterminal def="#nix.str" /> |
+          <nonterminal def="#nix.path" /> |
+          <nonterminal def="#nix.uri" />
+          <sbr />|
+          'true' | 'false' | 'null'
+          <sbr />|
+          '(' <nonterminal def="#nix.expr" /> ')'
+          <sbr />|
+          '{' <nonterminal def="#nix.bind" />* '}'
+          <sbr />|
+          'let' '{' <nonterminal def="#nix.bind" />* '}'
+          <sbr />|
+          'rec' '{' <nonterminal def="#nix.bind" />* '}'
+          <sbr />|
+          '[' <nonterminal def="#nix.expr_select" />* ']'
+        </rhs>
+      </production>
+
+      <production id="nix.bind">
+        <lhs>Bind</lhs>
+        <rhs>
+          <nonterminal def="#nix.id" /> '=' <nonterminal def="#nix.expr" /> ';'
+          <sbr />|
+          'inherit' ('(' <nonterminal def="#nix.expr" /> ')')? <nonterminal def="#nix.id" />* ';'
+        </rhs>
+      </production>
+
+      <production id="nix.formals">
+        <lhs>Formals</lhs>
+        <rhs>
+          <nonterminal def="#nix.formal" /> ',' <nonterminal def="#nix.formals" />
+          | <nonterminal def="#nix.formal" />
+        </rhs>
+      </production>
+          
+      <production id="nix.formal">
+        <lhs>Formal</lhs>
+        <rhs>
+          <nonterminal def="#nix.id" />
+          <sbr />|
+          <nonterminal def="#nix.id" /> '?' <nonterminal def="#nix.expr" />
+        </rhs>
+      </production>
+          
+    </productionset>
+
+    <productionset>
+      <title>Terminals</title>
+
+      <production id="nix.id">
+        <lhs>Id</lhs>
+        <rhs>[a-zA-Z\_][a-zA-Z0-9\_\']*</rhs>
+      </production>
+    
+      <production id="nix.int">
+        <lhs>Int</lhs>
+        <rhs>[0-9]+</rhs>
+      </production>
+    
+      <production id="nix.str">
+        <lhs>Str</lhs>
+        <rhs>\"[^\n\"]*\"</rhs>
+      </production>
+
+      <production id="nix.path">
+        <lhs>Path</lhs>
+        <rhs>[a-zA-Z0-9\.\_\-\+]*(\/[a-zA-Z0-9\.\_\-\+]+)+</rhs>
+      </production>
+    
+      <production id="nix.uri">
+        <lhs>Uri</lhs>
+        <rhs>[a-zA-Z][a-zA-Z0-9\+\-\.]*\:[a-zA-Z0-9\%\/\?\:\@\&amp;\=\+\$\,\-\_\.\!\~\*\']+</rhs>
+      </production>
+
+      <production id="nix.ws">
+        <lhs>Whitespace</lhs>
+        <rhs>
+          [ \t\n]+
+          <sbr />|
+          \#[^\n]*
+          <sbr />|
+          \/\*(.|\n)*\*\/
+        </rhs>
+      </production>
+
+    </productionset>
+    
+  </sect1>
+  
+
+
+  <sect1>
+    <title>Semantics</title>
+
+
+    
+    <sect2>
+      <title>Built-in functions</title>
+
+      <para>
+        The Nix language provides the following built-in function
+        (<quote>primops</quote>):
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term><function>import</function>
+          <replaceable>e</replaceable></term>
+          <listitem>
+            <para>
+              Evaluates the expression <replaceable>e</replaceable>,
+              which must yield a path value.  The Nix expression
+              stored at this path in the file system is then read,
+              parsed, and evaluated.  Returns the result of the
+              evaluation of the Nix expression just read.
+            </para>
+
+            <para>
+              Example: <literal>import ./foo.nix</literal> evaluates
+              the expression stored in <filename>foo.nix</filename>
+              (in the directory containing the expression in which the
+              <function>import</function> occurs).
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><function>derivation</function>
+          <replaceable>e</replaceable></term>
+          <listitem>
+            <para>
+              Evaluates the expression <replaceable>e</replaceable>,
+              which must yield an attribute set.  [...]
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><function>baseNameOf</function>
+          <replaceable>e</replaceable></term>
+          <listitem>
+            <para>
+              Evaluates the expression <replaceable>e</replaceable>,
+              which must yield a string value, and returns a string
+              representing its <emphasis>base name</emphasis>.  This
+              is the substring following the last path separator
+              (<literal>/</literal>).
+            </para>
+
+            <para>
+              Example: <literal>baseNameOf "/foo/bar"</literal>
+              returns <literal>"bar"</literal>, and
+              <literal>baseNameOf "/foo/bar/"</literal> returns
+              <literal>""</literal>.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><function>toString</function>
+          <replaceable>e</replaceable></term>
+          <listitem>
+            <para>
+              Evaluates the expression <replaceable>e</replaceable>
+              and coerces it into a string, if possible.  Only
+              strings, paths, and URIs can be so coerced.
+            </para>
+
+            <para>
+              Example: <literal>toString
+              http://www.cs.uu.nl/</literal> returns
+              <literal>"http://www.cs.uu.nl/"</literal>.
+            </para>
+          </listitem>
+        </varlistentry>
+            
+      </variablelist>
+
+    </sect2>
+
+  </sect1>
+  
+
+</appendix>

doc/manual/nix-prefetch-url.xml

@@ -0,0 +1,69 @@
+<refentry>
+  
+<refnamediv>
+  <refname>nix-prefetch-url</refname>
+  <refpurpose>copy a file from a URL into the store and print its MD5 hash</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-prefetch-url</command>
+    <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>The environment variable <envar>NIX_HASH_ALGO</envar> specifies
+which hash algorithm to use.  It can be either <literal>md5</literal>,
+<literal>sha1</literal>, or <literal>sha256</literal>.  The default is
+<literal>md5</literal>.</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 environment variable <envar>PRINT_PATH</envar> is set, the path
+of the downloaded file in the Nix store is also printed.</para>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<screen>
+$ nix-prefetch-url ftp://ftp.nluug.nl/pub/gnu/make/make-3.80.tar.bz2
+0bbd1df101bc0294d440471e50feca71
+
+$ PRINT_PATH=1 nix-prefetch-url ftp://ftp.nluug.nl/pub/gnu/make/make-3.80.tar.bz2
+0bbd1df101bc0294d440471e50feca71
+/nix/store/wvyz8ifdn7wyz1p3pqyn0ra45ka2l492-make-3.80.tar.bz2</screen>
+
+</refsection>
+
+    
+</refentry>

doc/manual/nix-pull.xml

@@ -0,0 +1,43 @@
+<refentry>
+  <refnamediv>
+    <refname>nix-pull</refname>
+    <refpurpose>pull substitutes from a network cache</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>nix-pull</command>
+      <arg choice='plain'><replaceable>url</replaceable></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Description</title>
+
+    <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 downloads and
+      unpacks it into the Nix store.  This is used to speed up
+      installations: if you attempt to install something that has
+      already been built and stored into the network cache, Nix can
+      transparently re-use the pre-built store paths.
+    </para>
+
+    <para>
+      The file at <replaceable>url</replaceable> must be compatible
+      with the files created by <replaceable>nix-push</replaceable>.
+    </para>
+
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <screen>
+$ nix-pull http://catamaran.labs.cs.uu.nl/dist/nix/nixpkgs-0.5pre753/MANIFEST</screen>
+
+  </refsection>
+    
+</refentry>

doc/manual/nix-push.xml

@@ -0,0 +1,116 @@
+<refentry>
+
+<refnamediv>
+  <refname>nix-push</refname>
+  <refpurpose>push store paths onto a network cache</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-push</command>
+    <group choice='req'>
+      <arg choice='req'>
+        <arg choice='plain'><replaceable>archivesPutURL</replaceable></arg>
+        <arg choice='plain'><replaceable>archivesGetURL</replaceable></arg>
+        <arg choice='plain'><replaceable>manifestPutURL</replaceable></arg>
+      </arg>
+      <arg choice='req'>
+        <arg choice='plain'><option>--copy</option></arg>
+        <arg choice='plain'><replaceable>archivesDir</replaceable></arg>
+        <arg choice='plain'><replaceable>manifestFile</replaceable></arg>
+      </arg>
+    </group>
+    <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>The command <command>nix-push</command> builds a set of store
+paths (if necessary), and then packages and uploads all store paths in
+the resulting closures to a server.  A network cache thus populated
+can subsequently be used to speed up software deployment on other
+machines using the <command>nix-pull</command> command.</para>
+
+<para><command>nix-push</command> performs the following actions.
+      
+<orderedlist>
+
+  <listitem><para>Each path in <replaceable>paths</replaceable> is
+  realised (using <link
+  linkend='rsec-nix-store-realise'><literal>nix-store
+  --realise</literal></link>).</para></listitem>
+
+  <listitem><para>All paths in the closure of the store expressions
+  stored in <replaceable>paths</replaceable> are determined (using
+  <literal>nix-store --query --requisites
+  --include-outputs</literal>).  It should be noted that since the
+  <option>--include-outputs</option> flag is used, you get a combined
+  source/binary distribution.</para></listitem>
+
+  <listitem><para>All store paths determined in the previous step are
+  packaged and compressed into a <command>bzip</command>ped NAR
+  archive (extension <filename>.nar.bz2</filename>).</para></listitem>
+
+  <listitem><para>A <emphasis>manifest</emphasis> is created that
+  contains information on the store paths, their eventual URLs in the
+  cache, and cryptographic hashes of the contents of the NAR
+  archives.</para></listitem>
+
+  <listitem><para>Each store path is uploaded to the remote directory
+  specified by <replaceable>archivesPutURL</replaceable>.  HTTP PUT
+  requests are used to do this.  However, before a file
+  <varname>x</varname> is uploaded to
+  <literal><replaceable>archivesPutURL</replaceable>/<varname>x</varname></literal>,
+  <command>nix-push</command> first determines whether this upload is
+  unnecessary by issuing a HTTP HEAD request on
+  <literal><replaceable>archivesGetURL</replaceable>/<varname>x</varname></literal>.
+  This allows a cache to be shared between many partially overlapping
+  <command>nix-push</command> invocations.  (We use two URLs because
+  the upload URL typically refers to a CGI script, while the download
+  URL just refers to a file system directory on the server.)</para></listitem>
+
+  <listitem><para>The manifest is uploaded using an HTTP PUT request
+  to <replaceable>manifestPutURL</replaceable>.  The corresponding
+  URL to download the manifest can then be used by
+  <command>nix-pull</command>.</para></listitem>
+        
+</orderedlist>
+
+</para>
+
+<para>TODO: <option>--copy</option></para>
+            
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<para>To upload files there typically is some CGI script on the server
+side.  This script should be be protected with a password.  The
+following example uploads the store paths resulting from building the
+Nix expressions in <filename>foo.nix</filename>, passing appropriate
+authentication information:
+    
+<screen>
+$ nix-push \
+    http://foo@bar:server.domain/cgi-bin/upload.pl/cache \
+    http://server.domain/cache \
+    http://foo@bar:server.domain/cgi-bin/upload.pl/MANIFEST \
+    $(nix-instantiate foo.nix)</screen>
+
+This will push both sources and binaries (and any build-time
+dependencies used in the build, such as compilers).</para>
+
+<para>If we just want to push binaries, not sources and build-time
+dependencies, we can do:
+      
+<screen>
+$ nix-push <replaceable>urls</replaceable> $(nix-instantiate $(nix-store -r foo.nix))</screen>
+    
+</para>
+
+</refsection>
+    
+</refentry>

doc/manual/nix-reference.xml

@@ -1,444 +0,0 @@
-<refentry>
-  <refnamediv>
-    <refname>nix</refname>
-    <refpurpose>manipulate or query the Nix store</refpurpose>
-  </refnamediv>
-
-  <refsynopsisdiv>
-    <cmdsynopsis>
-      <command>nix</command>
-      <group choice='opt'>
-	<arg><option>--path</option></arg>
-	<arg><option>-p</option></arg>
-      </group>
-      <group choice='opt' rep='repeat'>
-	<arg><option>--verbose</option></arg>
-	<arg><option>-v</option></arg>
-      </group>
-      <group choice='opt' rep='repeat'>
-	<arg><option>--keep-failed</option></arg>
-	<arg><option>-K</option></arg>
-      </group>
-      <arg choice='plain'><replaceable>operation</replaceable></arg>
-      <arg rep='repeat'><replaceable>options</replaceable></arg>
-      <arg rep='repeat'><replaceable>arguments</replaceable></arg>
-    </cmdsynopsis>
-  </refsynopsisdiv>
-
-  <refsect1>
-    <title>Description</title>
-
-    <para>
-      The command <command>nix</command> provides access to the Nix store. This
-      is the (set of) path(s) where Nix expressions and the file system objects
-      built by them are stored.
-    </para>
-
-    <para>
-      <command>nix</command> has many subcommands called
-      <emphasis>operations</emphasis>.  These are individually documented
-      below.  Exactly one operation must always be provided.
-    </para>
-
-  </refsect1>
-
-  <refsect1>
-    <title>Common Options</title>
-
-    <para>
-      In this section the options that are common to all Nix operations are
-      listed.  These options are allowed for every subcommand (although they
-      may not always have an effect).
-    </para>
-
-    <variablelist>
-
-      <varlistentry>
-	<term><option>--path</option></term>
-	<listitem>
-	  <para>
-	    Indicates that any identifier arguments to the operation are paths
-	    in the store rather than identifiers.
-	  </para>
-	</listitem>
-      </varlistentry>
-
-      <varlistentry>
-	<term><option>--verbose</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 and specified below in the
-	    respective sections.  Any diagnostic information is printed on
-	    standard error, never on standard output.
-	  </para>
-
-	  <para>
-	    This option may be specified repeatedly.  Currently, the following
-	    verbosity levels exist:
-	  </para>
-
-	  <variablelist>
-	    <varlistentry>
-	      <term>0</term>
-	      <listitem>
-		<para>
-		  Print error messages only.
-		</para>
-	      </listitem>
-	    </varlistentry>
-	    <varlistentry>
-	      <term>1</term>
-	      <listitem>
-		<para>
-		  Print informational messages.
-		</para>
-	      </listitem>
-	    </varlistentry>
-	    <varlistentry>
-	      <term>2</term>
-	      <listitem>
-		<para>
-		  Print even more informational messages.
-		</para>
-	      </listitem>
-	    </varlistentry>
-	    <varlistentry>
-	      <term>3</term>
-	      <listitem>
-		<para>
-		  Print messages that should only be useful for debugging.
-		</para>
-	      </listitem>
-	    </varlistentry>
-	    <varlistentry>
-	      <term>4</term>
-	      <listitem>
-		<para>
-		  <quote>Vomit mode</quote>: print vast amounts of debug
-		  information.
-		</para>
-	      </listitem>
-	    </varlistentry>
-	  </variablelist>
-
-	</listitem>
-      </varlistentry>
-
-      <varlistentry>
-	<term><option>--keep-failed</option></term>
-	<listitem>
-	  <para>
-	    Specifies that in case of a build failure, the temporary directory
-            (usually in <filename>/tmp</filename>) in which the build takes
-            place should not be deleted.  The path of the build directory is
-            printed as an informational message.
-	  </para>
-	</listitem>
-      </varlistentry>
-
-    </variablelist>
-
-  </refsect1>
-
-
-  <!--######################################################################-->
-
-  <refsect1>
-    <title>Operation <option>--install</option></title>
-
-    <refsect2>
-      <title>Synopsis</title>
-      <cmdsynopsis>
-	<command>nix</command>
-	<group>
-	  <arg><option>--install</option></arg>
-	  <arg><option>-i</option></arg>
-	</group>
-	<arg choice='plain' rep='repeat'><replaceable>ids</replaceable></arg>
-      </cmdsynopsis>
-    </refsect2>
-
-    <refsect2>
-      <title>Description</title>
-	    
-      <para>
-	The operation <option>--install</option> realises the Nix expressions
-	identified by <replaceable>ids</replaceable> in the file system.  If
-	these expressions are derivation expressions, they are first
-	normalised.  That is, their target paths are are built, unless a normal
-	form is already known.
-      </para>
-
-      <para>
-	The identifiers of the normal forms of the given Nix expressions are
-	printed on standard output.
-      </para>
-
-    </refsect2>
-	    
-  </refsect1>
-
-
-  <!--######################################################################-->
-
-  <refsect1>
-    <title>Operation <option>--delete</option></title>
-
-    <refsect2>
-      <title>Synopsis</title>
-      <cmdsynopsis>
-	<command>nix</command>
-	<group>
-	  <arg><option>--delete</option></arg>
-	  <arg><option>-d</option></arg>
-	</group>
-	<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
-      </cmdsynopsis>
-    </refsect2>
-
-    <refsect2>
-      <title>Description</title>
-	    
-      <para>
-	The operation <option>--delete</option> unconditionally deletes the
-	paths <replaceable>paths</replaceable> from the Nix store. It is an
-	error to attempt to delete paths outside of the store.
-      </para>
-
-      <warning>
-	<para>
-	  This operation should almost never be called directly, since no
-	  attempt is made to verify that no references exist to the paths to
-	  be deleted.  Therefore, careless deletion can result in an
-	  inconsistent system. Deletion of paths in the store is done by the
-	  garbage collector (which uses <option>--delete</option> to delete
-	  unreferenced paths).
-	  
-	</para>
-      </warning>
-
-    </refsect2>
-	    
-  </refsect1>
-
-
-  <!--######################################################################-->
-
-  <refsect1>
-    <title>Operation <option>--query</option></title>
-
-    <refsect2>
-      <title>Synopsis</title>
-      <cmdsynopsis>
-	<command>nix</command>
-	<group>
-	  <arg><option>--query</option></arg>
-	  <arg><option>-q</option></arg>
-	</group>
-	<group>
-	  <group>
-	    <arg><option>--list</option></arg>
-	    <arg><option>-l</option></arg>
-	  </group>
-	  <group>
-	    <arg><option>--requisites</option></arg>
-	    <arg><option>-r</option></arg>
-	  </group>
-	  <group>
-	    <arg><option>--expansion</option></arg>
-	    <arg><option>-e</option></arg>
-	  </group>
-	  <group>
-	    <arg><option>--graph</option></arg>
-	    <arg><option>-g</option></arg>
-	  </group>
-	</group>
-	<arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
-      </cmdsynopsis>
-    </refsect2>
-
-    <refsect2>
-      <title>Description</title>
-	    
-      <para>
-	The operation <option>--query</option> displays various bits of
-	information about Nix expressions or paths in the store.  The queries
-	are described in <xref linkend='nixref-queries' />.  At most one query
-	can be specified; the default query is <option>--list</option>.
-      </para>
-
-    </refsect2>
-
-    <refsect2 id='nixref-queries'>
-      <title>Queries</title>
-	    
-      <variablelist>
-
-	<varlistentry>
-	  <term><option>--list</option></term>
-	  <listitem>
-	    <para>
-	      Prints out the target paths of the Nix expressions indicated by
-	      the identifiers <replaceable>args</replaceable>.  In the case of
-	      a derivation expression, these are the paths that will be
-	      produced by the builder of the expression.  In the case of a
-	      slice expression, these are the root paths (which are generally
-	      the paths that were produced by the builder of the derivation
-	      expression of which the slice is a normal form).
-	    </para>
-
-	    <para>
-	      This query has one option:
-	    </para>
-
-	    <variablelist>
-
-	      <varlistentry>
-		<term><option>--normalise</option></term>
-		<listitem>
-		  <para>
-		    Causes the target paths of the <emphasis>normal
-		      forms</emphasis> of the expressions to be printed, rather
-		    than the target paths of the expressions themselves.
-		  </para>
-		</listitem>
-	      </varlistentry>
-
-	    </variablelist>
-	    
-	  </listitem>
-	</varlistentry>
-
-	<varlistentry>
-	  <term><option>--requisites</option></term>
-	  <listitem>
-	    <para>
-	      Prints out the requisite paths of the Nix expressions indicated
-	      by the identifiers <replaceable>args</replaceable>.  The
-	      requisite paths of a Nix expression are the paths that need to be
-	      present in the system to be able to realise the expression.  That
-	      is, they form the <emphasis>closure</emphasis> of the expression
-	      in the file system (i.e., no path in the set of requisite paths
-	      points to anything outside the set of requisite paths).
-	    </para>
-
-	    <para>
-	      The notion of requisite paths is very useful when one wants to
-	      distribute Nix expressions.  Since they form a closure, they are
-	      the only paths one needs to distribute to another system to be
-	      able to realise the expression on the other system.
-	    </para>
-
-	    <para>
-	      This query is generally used to implement various kinds of
-	      distribution.  A <emphasis>source distribution</emphasis> is
-	      obtained by distributing the requisite paths of a derivation
-	      expression.  A <emphasis>binary distribution</emphasis> is
-	      obtained by distributing the requisite paths of a slice
-	      expression (i.e., the normal form of a derivation expression; you
-	      can directly specify the identifier of the slice expression, or
-	      use <option>--normalise</option> and specify the identifier of a
-	      derivation expression).  A <emphasis>cache
-		distribution</emphasis> is obtained by distributing the
-	      requisite paths of a derivation expression and specifying the
-	      option <option>--include-successors</option>.  This will include
-	      not just the paths of a source and binary distribution, but also
-	      all expressions and paths of subterms of the source.  This is
-	      useful if one wants to realise on the target system a Nix
-	      expression that is similar but not quite the same as the one
-	      being distributed, since any common subterms will be reused.
-	    </para>
-
-	    <para>
-	      This query has a number of options:
-	    </para> 
-
-	    <variablelist>
-
-	      <varlistentry>
-		<term><option>--normalise</option></term>
-		<listitem>
-		  <para>
-		    Causes the requisite paths of the <emphasis>normal
-		      forms</emphasis> of the expressions to be printed, rather
-		    than the requisite paths of the expressions themselves.
-		  </para>
-		</listitem>
-	      </varlistentry>
-
-	      <varlistentry>
-		<term><option>--exclude-exprs</option></term>
-		<listitem>
-		  <para>
-		    Excludes the paths of Nix expressions.  This causes the
-		    closure property to be lost, that is, the resulting set of
-		    paths is not enough to ensure realisibility.
-		  </para>
-		</listitem>
-	      </varlistentry>
-
-	      <varlistentry>
-		<term><option>--include-successors</option></term>
-		<listitem>
-		  <para>
-		    Also include the requisites of successors (normal forms).
-		    Only the requisites of <emphasis>known</emphasis>
-		    successors are included, i.e., the normal forms of
-		    derivation expressions that have never been normalised will
-		    not be included.
-		  </para>
-
-		  <para>
-		    Note that not just the successor of a derivation expression
-		    will be included, but also the successors of all input
-		    expressions of that derivation expression.  I.e., all
-		    normal forms of subterms involved in the normalisation of
-		    the top-level term are included.
-		  </para>
-		</listitem>
-	      </varlistentry>
-
-	    </variablelist>
-
-	  </listitem>
-	</varlistentry>
-
-	<varlistentry>
-	  <term><option>--expansion</option></term>
-	  <listitem>
-	    <para>
-	      For each identifier in <replaceable>args</replaceable>, prints
-	      all expansions of that identifier, that is, all paths whose
-	      current content matches the identifier.
-	    </para>
-	  </listitem>
-	</varlistentry>
-
-	<varlistentry>
-	  <term><option>--graph</option></term>
-	  <listitem>
-	    <para>
-	      Prints a graph of the closure of the expressions identified by
-	      <replaceable>args</replaceable> in the format of the
-	      <command>dot</command> tool of AT&amp;T's GraphViz package.
-	    </para>
-	  </listitem>
-	</varlistentry>
-
-      </variablelist>
-
-    </refsect2>
-
-  </refsect1>
-
-
-</refentry>
-
-
-<!--
-local variables:
-sgml-parent-document: ("book.xml" "refentry")
-end:
--->

doc/manual/nix-store.xml

@@ -0,0 +1,676 @@
+<refentry>
+
+<refnamediv>
+  <refname>nix-store</refname>
+  <refpurpose>manipulate or query the Nix store</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-store</command>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xpointer(/nop/*)" />
+    <arg><option>--add-root</option> <replaceable>path</replaceable></arg>
+    <arg><option>--indirect</option></arg>
+    <arg choice='plain'><replaceable>operation</replaceable></arg>
+    <arg rep='repeat'><replaceable>options</replaceable></arg>
+    <arg rep='repeat'><replaceable>arguments</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>The command <command>nix-store</command> performs primitive
+operations on the Nix store.  You generally do not need to run this
+command manually.</para>
+
+<para><command>nix-store</command> takes exactly one
+<emphasis>operation</emphasis> flag which indicates the subcommand to
+be performed.  These are documented below.</para>
+
+</refsection>
+
+
+
+<!--######################################################################-->
+
+<refsection><title>Common options</title>
+
+<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>
+
+<variablelist>
+
+  <varlistentry id="opt-add-root"><term><option>--add-root</option> <replaceable>path</replaceable></term>
+
+    <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
+    <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
+    <filename>/nix/var/nix/gcroots/</filename>)
+    <emphasis>unless</emphasis> the <option>--indirect</option> flag
+    is used.</para>
+
+    <para>If there are multiple results, then multiple symlinks will
+    be created by sequentially numbering symlinks beyond the first one
+    (e.g., <filename>foo</filename>, <filename>foo-2</filename>,
+    <filename>foo-3</filename>, and so on).</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--indirect</option></term>
+
+    <listitem>
+
+    <para>In conjunction with <option>--add-root</option>, this option
+    allows roots to be stored <emphasis>outside</emphasis> of the GC
+    roots directory.  This is useful for commands such as
+    <command>nix-build</command> that place a symlink to the build
+    result in the current directory; such a build result should not be
+    garbage-collected unless the symlink is removed.</para>
+
+    <para>The <option>--indirect</option> flag causes a uniquely named
+    symlink to <replaceable>path</replaceable> to be stored in
+    <filename>/nix/var/nix/gcroots/auto/</filename>.  For instance,
+
+    <screen>
+$ nix-store --add-root /home/eelco/bla/result --indirect -r <replaceable>...</replaceable>
+
+$ ls -l /nix/var/nix/gcroots/auto
+lrwxrwxrwx    1 ... 2005-03-13 21:10 dn54lcypm8f8... -> /home/eelco/bla/result
+
+$ ls -l /home/eelco/bla/result
+lrwxrwxrwx    1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r11343n6qd4...-f-spot-0.0.10</screen>
+
+    Thus, when <filename>/home/eelco/bla/result</filename> is removed,
+    the GC root in the <filename>auto</filename> directory becomes a
+    dangling symlink and will be ignored by the collector.</para>
+
+    <warning><para>Note that it is not possible to move or rename
+    indirect GC roots, since the symlink in the
+    <filename>auto</filename> directory will still point to the old
+    location.</para></warning>
+
+    </listitem>
+
+  </varlistentry>
+    
+</variablelist>
+
+</refsection>
+
+  
+
+<!--######################################################################-->
+
+<refsection id='rsec-nix-store-realise'><title>Operation
+<option>--realise</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-store</command>
+  <group choice='req'>
+    <arg choice='plain'><option>--realise</option></arg>
+    <arg choice='plain'><option>-r</option></arg>
+  </group>
+  <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
+</cmdsynopsis>
+
+</refsection>
+
+<refsection><title>Description</title>
+            
+<para>The operation <option>--realise</option> essentially “builds”
+the specified store paths.  Realisation is a somewhat overloaded term:
+
+<itemizedlist>
+
+  <listitem><para>If the store path is a
+  <emphasis>derivation</emphasis>, realisation ensures that the output
+  paths of the derivation are <link
+  linkend="gloss-validity">valid</link> (i.e., the output path and its
+  closure exist in the file system).  This can be done in several
+  ways.  First, it is possible that the outputs are already valid, in
+  which case we are done immediately.  Otherwise, there may be <link
+  linkend="gloss-substitute">substitutes</link> that produce the
+  outputs (e.g., by downloading them).  Finally, the outputs can be
+  produced by performing the build action described by the
+  derivation.</para></listitem>
+
+  <listitem><para>If the store path is not a derivation, realisation
+  ensures that the specified path is valid (i.e., it and its closure
+  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>
+
+</itemizedlist>
+
+</para>
+
+<para>The output path of each derivation is printed on standard
+output.  (For non-derivations argument, the argument itself is
+printed.)</para>
+
+</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>
+
+This is essentially what <link
+linkend="sec-nix-build"><command>nix-build</command></link> does.</para>
+
+</refsection>
+
+
+</refsection>
+
+  
+
+<!--######################################################################-->
+
+<refsection id='rsec-nix-store-gc'><title>Operation <option>--gc</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-store</command>
+  <arg choice='plain'><option>--gc</option></arg>
+  <group>
+    <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>
+</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
+“roots”, are deleted.</para>
+
+<para>The following suboperations may be specified:</para>
+
+<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>
+
+<para>The behaviour of the collector is influenced by the <link
+linkend="conf-gc-keep-outputs"><literal>gc-keep-outputs</literal></link>
+and <link
+linkend="conf-gc-keep-derivations"><literal>gc-keep-derivations</literal></link>
+variables in the Nix configuration file.</para>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<para>To delete all unreachable paths, just do:
+    
+<screen>
+$ nix-store --gc</screen>
+
+</para>
+
+</refsection>
+
+
+</refsection>
+
+
+  
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--query</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-store</command>
+  <group choice='req'>
+    <arg choice='plain'><option>--query</option></arg>
+    <arg choice='plain'><option>-q</option></arg>
+  </group>
+  <group choice='req'>
+    <arg choice='plain'><option>--outputs</option></arg>
+    <arg choice='plain'><option>--requisites</option></arg>
+    <arg choice='plain'><option>-R</option></arg>
+    <arg choice='plain'><option>--references</option></arg>
+    <arg choice='plain'><option>--referers</option></arg>
+    <arg choice='plain'><option>--referers-closure</option></arg>
+    <arg choice='plain'><option>--deriver</option></arg>
+    <arg choice='plain'><option>--deriver</option></arg>
+    <arg choice='plain'><option>--graph</option></arg>
+    <arg choice='plain'><option>--tree</option></arg>
+    <arg choice='plain'><option>--binding</option> <replaceable>name</replaceable></arg>
+    <arg choice='plain'><option>--hash</option></arg>
+  </group>
+  <arg><option>--use-output</option></arg>
+  <arg><option>-u</option></arg>
+  <arg><option>--force-realise</option></arg>
+  <arg><option>-f</option></arg>
+  <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
+</cmdsynopsis>
+
+</refsection>
+
+
+<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
+<option>--outputs</option>.</para>
+
+<para>The paths <replaceable>paths</replaceable> may also be symlinks
+from outside of the Nix store, to the Nix store.  In that case, the
+query is applied to the target of the symlink.</para>
+
+
+</refsection>
+
+
+<refsection><title>Common query options</title>
+
+<variablelist>
+
+  <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>
+
+  </varlistentry>
+
+</variablelist>
+        
+</refsection>
+    
+
+<refsection id='nixref-queries'><title>Queries</title>
+            
+<variablelist>
+
+  <varlistentry><term><option>--outputs</option></term>
+
+    <listitem><para>Prints out the <link
+    linkend="gloss-output-path">output paths</link> of the store
+    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>
+    <term><option>-R</option></term>
+
+    <listitem><para>Prints out the <link
+    linkend="gloss-closure">closure</link> of the store path
+    <replaceable>paths</replaceable>.</para>
+
+    <para>This query has one option:</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>
+
+    <para>This query can be used to implement various kinds of
+    deployment.  A <emphasis>source deployment</emphasis> is obtained
+    by distributing the closure of a store derivation.  A
+    <emphasis>binary deployment</emphasis> is obtained by distributing
+    the closure of an output path.  A <emphasis>cache
+    deployment</emphasis> (combined source/binary deployment,
+    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
+    dependencies.  (For <emphasis>all</emphasis> dependencies, use
+    <option>--requisites</option>.)</para></listitem>
+
+  </varlistentry>
+  
+  <varlistentry><term><option>--referers</option></term>
+  
+    <listitem><para>Prints the set of <emphasis>referers</emphasis> of
+    the store paths <replaceable>paths</replaceable>, that is, the
+    store paths currently existing in the Nix store that refer to one
+    of <replaceable>paths</replaceable>.  Note that contrary to the
+    references, the set of referers is not constant; it can change as
+    store paths are added or removed.</para></listitem>
+
+  </varlistentry>
+  
+  <varlistentry><term><option>--referers-closure</option></term>
+  
+    <listitem><para>Prints the closure of the set of store paths
+    <replaceable>paths</replaceable> under the referers relation; that
+    is, all store paths that directly or indirectly refer to one of
+    <replaceable>paths</replaceable>.  These are all the path currently
+    in the Nix store that are dependent on
+    <replaceable>paths</replaceable>.</para></listitem>
+
+  </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
+    (e.g., if it is a source file), or if the deriver is not known
+    (e.g., in the case of a binary-only deployment), the string
+    <literal>unknown-deriver</literal> is printed.</para></listitem>
+
+  </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 <ulink
+    url="http://www.graphviz.org/">Graphviz package</ulink>.  This can
+    be used to visualise dependency graphs.  To obtain a build-time
+    dependency graph, apply this to a store derivation.  To obtain a
+    runtime dependency graph, apply it to an output
+    path.</para></listitem>
+
+  </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
+    flatten the tree, making it more readable.  The query only
+    recurses into a store path when it is first encountered; this
+    prevents a blowup of the tree representation of the
+    graph.</para></listitem>
+
+  </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
+    error for a derivation to not have the specified
+    attribute.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--hash</option></term>
+  
+    <listitem><para>Prints the SHA-256 hash of the contents of the
+    store path <replaceable>paths</replaceable>.  Since the hash is
+    stored in the Nix database, this is a fast
+    operation.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<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
+/nix/store/9lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4
+<replaceable>...</replaceable></screen>
+
+</para>
+
+<para>Print the build-time dependencies of <command>svn</command>:
+
+<screen>
+$ nix-store -qR $(nix-store -qd $(which svn))
+/nix/store/02iizgn86m42q905rddvg4ja975bk2i4-grep-2.5.1.tar.bz2.drv
+/nix/store/07a2bzxmzwz5hp58nf03pahrv2ygwgs3-gcc-wrapper.sh
+/nix/store/0ma7c9wsbaxahwwl04gbw3fcd806ski4-glibc-2.3.4.drv
+<replaceable>... lots of other paths ...</replaceable></screen>
+
+The difference with the previous example is that we ask the closure of
+the derivation (<option>-qd</option>), not the closure of the output
+path that contains <command>svn</command>.</para>
+
+<para>Show the build-time dependencies as a tree:
+
+<screen>
+$ nix-store -q --tree $(nix-store -qd $(which svn))
+/nix/store/7i5082kfb6yjbqdbiwdhhza0am2xvh6c-subversion-1.1.4.drv
++---/nix/store/d8afh10z72n8l1cr5w42366abiblgn54-builder.sh
++---/nix/store/fmzxmpjx2lh849ph0l36snfj9zdibw67-bash-3.0.drv
+|   +---/nix/store/570hmhmx3v57605cqg9yfvvyh0nnb8k8-bash
+|   +---/nix/store/p3srsbd8dx44v2pg6nbnszab5mcwx03v-builder.sh
+<replaceable>...</replaceable></screen>
+
+</para>
+
+<para>Show all paths that depend on the same OpenSSL library as
+<command>svn</command>:
+
+<screen>
+$ nix-store -q --referers $(nix-store -q --binding openssl $(nix-store -qd $(which svn)))
+/nix/store/23ny9l9wixx21632y2wi4p585qhva1q8-sylpheed-1.0.0
+/nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4
+/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3
+/nix/store/l51240xqsgg8a7yrbqdx1rfzyv6l26fx-lynx-2.8.5</screen>
+
+</para>
+
+<para>Show all paths that directly or indirectly depend on the Glibc
+(C library) used by <command>svn</command>:
+
+<screen>
+$ nix-store -q --referers-closure $(ldd $(which svn) | grep /libc.so | awk '{print $3}')
+/nix/store/034a6h4vpz9kds5r6kzb9lhh81mscw43-libgnomeprintui-2.8.2
+/nix/store/15l3yi0d45prm7a82pcrknxdh6nzmxza-gawk-3.1.4
+<replaceable>...</replaceable></screen>
+
+Note that <command>ldd</command> is a command that prints out the
+dynamic libraries used by an ELF executable.</para>
+
+<para>Make a picture of the runtime dependency graph of the current
+user environment:
+
+<screen>
+$ nix-store -q --graph ~/.nix-profile | dot -Tps > graph.ps
+$ gv graph.ps</screen>
+
+</para>
+
+</refsection>
+
+
+</refsection>
+
+  
+
+<!--######################################################################-->
+
+<!--
+<refsection id="rsec-nix-store-reg-val"><title>Operation <option>-XXX-register-validity</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-store</command>
+  <arg choice='plain'><option>-XXX-register-validity</option></arg>
+</cmdsynopsis>
+</refsection>
+
+<refsection><title>Description</title>
+            
+<para>TODO</para>
+
+</refsection>
+            
+</refsection>
+-->
+
+
+
+<!--######################################################################-->
+
+<!--
+<refsection><title>Operation <option>-XXX-substitute</option></title>
+
+<refsection><title>Synopsis</title>
+
+<cmdsynopsis>
+  <command>nix-store</command>
+  <arg choice='plain'><option>-XXX-substitute</option></arg>
+  <arg choice='plain'
+       rep='repeat'><replaceable>srcpath</replaceable> <replaceable>subpath</replaceable></arg>
+</cmdsynopsis>
+</refsection>
+
+<refsection><title>Description</title>
+            
+<para>The operation <option>-XXX-substitute</option> registers that the
+store path <replaceable>srcpath</replaceable> can be built by
+realising the derivation expression in
+<replaceable>subpath</replaceable>.  This is used to implement binary
+deployment.</para>
+
+</refsection>
+            
+</refsection>
+-->
+
+
+
+<!--######################################################################-->
+
+<refsection><title>Operation <option>--verify</option></title>
+
+<refsection>
+  <title>Synopsis</title>
+  <cmdsynopsis>
+    <command>nix-store</command>
+    <arg choice='plain'><option>--verify</option></arg>
+    <arg><option>--check-contents</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
+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:
+
+<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>
+  
+</variablelist>
+
+</para>
+
+</refsection>
+            
+</refsection>
+
+
+
+</refentry>

doc/manual/opt-common-syn.xml

@@ -0,0 +1,24 @@
+<nop>
+  
+<arg><option>--help</option></arg>
+<arg><option>--version</option></arg>
+<arg rep='repeat'><option>--verbose</option></arg>
+<arg rep='repeat'><option>-v</option></arg>
+<arg><option>--no-build-output</option></arg>
+<arg><option>-Q</option></arg>
+<arg>
+  <group choice='req'>
+    <arg choice='plain'><option>--max-jobs</option></arg>
+    <arg choice='plain'><option>-j</option></arg>
+  </group>
+  <replaceable>number</replaceable>
+</arg>
+<arg><option>--keep-going</option></arg>
+<arg><option>-k</option></arg>
+<arg><option>--keep-failed</option></arg>
+<arg><option>-K</option></arg>
+<arg><option>--fallback</option></arg>
+<arg><option>--readonly-mode</option></arg>
+<arg><option>--log-type</option> <replaceable>type</replaceable></arg>
+
+</nop>

doc/manual/opt-common.xml

@@ -0,0 +1,216 @@
+<sect1 id="sec-common-options"><title>Common options</title>
+
+<para>Most Nix commands accept the following command-line options:</para>
+
+<variablelist>
+
+<varlistentry><term><option>--help</option></term>
+  
+  <listitem><para>Prints out a summary of the command syntax and
+  exits.</para></listitem>
+  
+</varlistentry>
+
+
+<varlistentry><term><option>--version</option></term>
+  
+  <listitem><para>Prints out the Nix version number on standard output
+  and exits.</para></listitem>
+</varlistentry>
+
+
+<varlistentry><term><option>--verbose</option></term>
+  <term><option>-v</option></term>
+
+  <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
+  information is printed on standard error, never on standard
+  output.</para>
+
+  <para>This option may be specified repeatedly.  Currently, the
+  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>
+    </varlistentry>
+
+    <varlistentry><term>3</term>
+    <listitem><para>“Chatty”: print even more
+    informational messages.</para></listitem>
+    </varlistentry>
+
+    <varlistentry><term>4</term>
+    <listitem><para>“Debug”: print debug
+    information.</para></listitem>
+    </varlistentry>
+
+    <varlistentry><term>5</term>
+    <listitem><para>“Vomit”: print vast amounts of debug
+    information.</para></listitem>
+    </varlistentry>
+    
+  </variablelist>
+
+  </listitem>
+  
+</varlistentry>
+
+
+<varlistentry><term><option>--no-build-output</option></term>
+  <term><option>-Q</option></term>
+
+  <listitem><para>By default, output written by builders to standard
+  output and standard error is echoed to the Nix command's standard
+  error.  This option suppresses this behaviour.  Note that the
+  builder's standard output and error are always written to a log file
+  in
+  <filename><replaceable>prefix</replaceable>/nix/var/log/nix</filename>.</para></listitem>
+  
+</varlistentry>
+
+
+<varlistentry id="opt-max-jobs"><term><option>--max-jobs</option></term>
+  <term><option>-j</option></term>
+
+  <listitem><para>Sets the maximum number of build jobs that Nix will
+  perform in parallel to the specified number.  The default is 1.  A
+  higher value is useful on SMP systems or to exploit I/O latency.</para></listitem>
+  
+</varlistentry>
+
+
+<varlistentry><term><option>--keep-going</option></term>
+  <term><option>-k</option></term>
+
+  <listitem><para>Keep going in case of failed builds, to the
+  greatest extent possible.  That is, if building an input of some
+  derivation fails, Nix will still build the other inputs, but not the
+  derivation itself.  Without this option, Nix stops if any build
+  fails (except for builds of substitutes), possibly killing builds in
+  progress (in case of parallel or distributed builds).</para></listitem>
+  
+</varlistentry>
+
+
+<varlistentry><term><option>--keep-failed</option></term>
+  <term><option>-K</option></term>
+
+  <listitem><para>Specifies that in case of a build failure, the
+  temporary directory (usually in <filename>/tmp</filename>) in which
+  the build takes place should not be deleted.  The path of the build
+  directory is printed as an informational message.
+    </para>
+  </listitem>
+</varlistentry>
+
+
+<varlistentry><term><option>--fallback</option></term>
+
+  <listitem>
+
+  <para>Whenever Nix attempts to build a derivation for which
+  substitutes are known for each output path, but realising the output
+  paths through the substitutes fails, fall back on building the
+  derivation.</para>
+
+  <para>The most common scenario in which this is useful is when we
+  have registered substitutes in order to perform binary distribution
+  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.
+  This option is not the default since it is generally not desirable
+  for a transient failure in obtaining the substitutes to lead to a
+  full build from source (with the related consumption of
+  resources).</para>
+
+  </listitem>
+  
+</varlistentry>
+
+
+<varlistentry><term><option>--readonly-mode</option></term>
+
+  <listitem><para>When this option is used, no attempt is made to open
+  the Nix database.  Most Nix operations do need database access, so
+  those operations will fail.</para></listitem>
+  
+</varlistentry>
+
+
+<varlistentry id="opt-log-type"><term><option>--log-type</option>
+<replaceable>type</replaceable></term>
+
+  <listitem>
+
+  <para>This option determines how the output written to standard
+  error is formatted.  Nix’s diagnostic messages are typically
+  <emphasis>nested</emphasis>.  For instance, when tracing Nix
+  expression evaluation (<command>nix-env -vvvvv</command>, messages
+  from subexpressions are nested inside their parent expressions.  Nix
+  builder output is also often nested.  For instance, the Nix Packages
+  generic builder nests the various build tasks (unpack, configure,
+  compile, etc.), and the GNU Make in <literal>stdenv-linux</literal>
+  has been patched to provide nesting for recursive Make
+  invocations.</para>
+
+  <para><replaceable>type</replaceable> can be one of the
+  following:
+
+  <variablelist>
+
+    <varlistentry><term><literal>pretty</literal></term>
+
+      <listitem><para>Pretty-print the output, indicating different
+      nesting levels using spaces.  This is the
+      default.</para></listitem>
+
+    </varlistentry>
+
+    <varlistentry><term><literal>escapes</literal></term>
+
+      <listitem><para>Indicate nesting using escape codes that can be
+      interpreted by the <command>log2xml</command> tool in the Nix
+      source distribution.  The resulting XML file can be fed into the
+      <command>log2html.xsl</command> stylesheet to create an HTML
+      file that can be browsed interactively, using Javascript to
+      expand and collapse parts of the output.</para></listitem>
+
+    </varlistentry>
+
+    <varlistentry><term><literal>flat</literal></term>
+
+      <listitem><para>Remove all nesting.</para></listitem>
+
+    </varlistentry>
+
+  </variablelist>    
+  
+  </para>
+
+  </listitem>
+  
+</varlistentry>
+
+
+</variablelist>
+
+
+</sect1>

doc/manual/package-management.xml

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

doc/manual/quick-start.xml

@@ -0,0 +1,118 @@
+<chapter><title>Quick Start</title>
+
+<para>This chapter is for impatient people who don't like reading
+documentation.  For more in-depth information you are kindly referred
+to the following chapters.</para>
+
+<orderedlist>
+
+<listitem><para>Download a source tarball or RPM from <ulink
+url='http://www.cs.uu.nl/groups/ST/Trace/Nix'/>.  Build source
+distributions using the regular sequence:
+        
+<screen>
+$ tar xvfj nix-<replaceable>version</replaceable>.tar.bz2
+$ ./configure
+$ make
+$ make install <lineannotation>(as root)</lineannotation></screen>
+
+This will install Nix in <filename>/nix</filename>.  You shouldn't
+change the prefix if at all possible since that will make it
+impossible to use our pre-built components.  Alternatively, you could
+grab an RPM if you're on an RPM-based system.  You should also add
+<filename>/nix/etc/profile.d/nix.sh</filename> to your
+<filename>~/.bashrc</filename> (or some other login
+file).</para></listitem>
+
+<listitem><para>Subscribe to the Nix Packages channel.
+
+<screen>
+$ nix-channel --add http://catamaran.labs.cs.uu.nl/dist/nix/channels/nixpkgs-unstable</screen>
+
+</para></listitem>
+
+<listitem><para>Download the latest Nix expressions available in the channel.
+<screen>
+$ nix-channel --update</screen>
+
+Note that this in itself doesn't download any components, it just
+downloads the Nix expressions that build them and stores them
+somewhere (under <filename>~/.nix-defexpr</filename>, in case you're
+curious).  Also, it registers the fact that pre-built binaries are
+available remotely.</para></listitem>
+
+<listitem><para>See what installable components are currently
+available in the channel:
+
+<screen>
+$ nix-env -qa
+docbook-xml-4.2
+firefox-1.0pre-PR-0.10.1
+hello-2.1.1
+libxslt-1.1.0
+<replaceable>...</replaceable></screen>
+
+</para></listitem>
+
+<listitem><para>Install some components from the channel:
+        
+<screen>
+$ nix-env -i hello firefox <replaceable>...</replaceable> </screen>
+
+This should download the pre-built components; it should not build
+them locally (if it does, something went wrong).</para></listitem>
+
+<listitem><para>Test that they work:
+
+<screen>
+$ which hello
+/home/eelco/.nix-profile/bin/hello
+$ hello
+Hello, world!
+$ firefox
+<lineannotation>(read Slashdot or something)</lineannotation></screen>
+
+</para></listitem>
+    
+<listitem><para>Uninstall a package:
+
+<screen>
+$ nix-env -e hello</screen>
+
+</para></listitem>
+
+<listitem><para>To keep up-to-date with the channel, do:
+
+<screen>
+$ nix-channel --update
+$ nix-env -u '*'</screen>
+
+The latter command will upgrade each installed component for which
+there is a “newer” version (as determined by comparing the version
+numbers).</para></listitem>
+
+<listitem><para>If you're unhappy with the result of a
+<command>nix-env</command> action (e.g., an upgraded component turned
+out not to work properly), you can go back:
+
+<screen>
+$ nix-env --rollback</screen>
+
+</para></listitem>
+
+<listitem><para>You should periodically run the Nix garbage collector
+to get rid of unused packages, since uninstalls or upgrades don't
+actually delete them:
+
+<screen>
+$ nix-env --delete-generations old
+$ nix-store --gc</screen>
+
+The first command deletes old “generations” of your profile (making
+rollbacks impossible, but also making the components in those old
+generations available for garbage collection), while the second
+command actually deletes them.</para></listitem>
+
+</orderedlist>
+
+</chapter>

doc/manual/schemas.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0"?>
+<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
+  <uri pattern="*.xml" typeId="DocBook"/>
+</locatingRules>

doc/manual/style.css

@@ -0,0 +1,234 @@
+/* Copied from http://bakefile.sourceforge.net/, which appears
+   licensed under the GNU GPL. */
+
+
+/***************************************************************************
+                             Basic headers and text:
+ ***************************************************************************/
+
+body
+{
+    font-family: sans-serif;
+    background: white;
+  
+    margin: 2em 1em 2em 1em;
+}
+
+h1,h2,h3
+{
+    color: #005aa0;
+    text-align: left;
+}
+
+h1 /* title */
+{
+    font-size: 200%;
+}
+
+h2 /* chapters, appendices, subtitle */
+{
+    font-size: 180%;
+}
+
+/* Extra space between chapters, appendices. */
+div.chapter > div.titlepage h2, div.appendix > div.titlepage h2 
+{ 
+    margin-top: 1.5em;
+/*    border-top: solid #005aa0; */
+}
+
+div.sect1 h2 /* sections */
+{
+    font-size: 150%;
+}
+
+div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */
+{
+    font-size: 125%;
+}
+
+div.refsection h3
+{
+    font-size: 110%;
+}
+
+h3 /* subsections */
+{
+    font-size: 125%;
+}
+
+
+
+/***************************************************************************
+                               Program listings:
+ ***************************************************************************/
+
+div.example
+{
+    border: 1px solid #6185a0;
+    padding: 6px 6px;
+    margin-left: 3em;
+    margin-right: 3em;
+    background: #eeeeee;
+}
+
+pre.programlisting
+{
+    color: #600000;
+    font-family: monospace;
+}
+
+
+/***************************************************************************
+                            Screen dumps:
+ ***************************************************************************/
+
+pre.screen
+{
+    border: 1px solid #6185a0;
+    padding: 6px 6px;
+    margin-left: 3em;
+    margin-right: 3em;
+    color: #600000;
+    background: #eeeeee;
+    font-family: monospace;
+    /* font-size: 90%; */
+}
+
+
+/***************************************************************************
+                               Notes, warnings etc:
+ ***************************************************************************/
+
+.note,.warning
+{
+    margin-top: 1em;
+    margin-bottom: 1em;
+    border: 1px solid #6185a0;
+    padding: 0px 1em;
+    background: #fffff5;
+}
+
+div.note,div.warning
+{
+    font-style: italic;
+}
+
+div.warning h3
+{
+    color: red;
+    font-size: 100%;
+}
+
+div.note h3
+{
+    color: blue;
+    font-size: 100%;
+}
+
+div.navfooter *
+{
+    font-size: 90%;
+}
+
+
+/***************************************************************************
+                        Links colors and highlighting: 
+ ***************************************************************************/
+
+a:link { color: #0048b3; }
+a:visited { color: #002a6a; }
+a:hover { background: #ffffcd; }
+
+
+/***************************************************************************
+                              Table of contents:
+ ***************************************************************************/
+
+.toc
+{
+    font-size: 90%;
+}
+
+
+
+/***************************************************************************
+                               Special elements:
+ ***************************************************************************/
+
+tt, code
+{
+    color: #400000;
+}
+
+.term
+{
+    font-weight: bold;
+    
+}
+
+div.variablelist dd
+{
+    margin-bottom: 1em;
+}
+
+.default
+{
+    font-style: italic;
+}
+
+.availability
+{
+    font-style: italic;
+}
+
+.varname
+{
+    color: #400000;
+}
+
+
+div.informaltable table
+{
+  border: 1px solid #6185a0;
+  width: 100%;
+}
+
+div.informaltable td
+{
+  border: 0;
+  padding: 5px;
+}
+
+div.informaltable td.default
+{
+  text-align: right;
+}
+
+div.informaltable th
+{
+  text-align: left;
+  color: #005aa0;
+  border: 0;
+  padding: 5px;
+  background: #fffff5;
+  font-weight: normal;
+  font-style: italic;
+}
+
+td.varname, td.tagname, td.paramname
+{
+  font-weight: bold;
+  vertical-align: top;
+}
+
+div.epigraph
+{
+    font-style: italic;
+    text-align: right;
+}
+
+table.productionset table.productionset
+{
+    font-family: monospace;
+}

doc/manual/troubleshooting.xml

@@ -1,48 +1,71 @@
-<appendix>
-  <title>Troubleshooting</title>
+<appendix><title>Troubleshooting</title>
 
-  <sect1>
-    <title>Database hangs</title>
-
-    <para>
-      If Nix or Fix appear to hang immediately after they are started, Nix's
-      database is probably <quote>wedged</quote>, i.e., some process died while
-      it held a lock on the database.  The solution is to ensure that no other
-      processes are accessing the database and then run the following command:
-    </para>
-
-    <screen>
-      $ db_recover -e -h <replaceable>prefix</replaceable>/var/nix/db</screen>
-
-    <para>
-      Here, <replaceable>prefix</replaceable> should be replaced by Nix's
-      installation prefix.
-    </para>
-
-  </sect1>
+<para>This section provides solutions for some common problems.</para>
 
 
-  <sect1>
-    <title>Database logfile removal</title>
+<sect1><title>Berkeley DB: <quote>Cannot allocate memory</quote></title>
 
-    <para>
-      Every time a Nix database transaction takes place, Nix writes a record of
-      this transaction to a <emphasis>log</emphasis> in its database directory
-      to ensure that the operation can be replayed in case of a application or
-      system crash.  However, without manual intervention, the log grows
-      indefinitely.  Hence, unused log files should be deleted periodically.
-      This can be accomplished using the following command:
-    </para>
+<para>Symptom: Nix operations (in particular the
+<command>nix-store</command> operations <option>--gc</option>,
+<option>--verify</option>, and <option>--clear-substitutes</option> —
+the latter being called by <command>nix-channel --update</command>)
+failing:
+
+<screen>
+$ nix-store --verify
+error: Db::del: Cannot allocate memory</screen>
+
+</para>
+
+<para>Possible solution: make sure that no Nix processes are running,
+then do:
+
+<screen>
+$ cd /nix/var/nix/db
+$ rm __db.00*</screen>
+
+</para>
+
+</sect1>
+
+
+<sect1><title>Collisions in <command>nix-env</command></title>
+
+<para>Symptom: when installing or upgrading, you get an error message such as
+
+<screen>
+$ nix-env -i docbook-xml
+...
+adding /nix/store/s5hyxgm62gk2...-docbook-xml-4.2
+collission between `/nix/store/s5hyxgm62gk2...-docbook-xml-4.2/xml/dtd/docbook/calstblx.dtd'
+  and `/nix/store/06h377hr4b33...-docbook-xml-4.3/xml/dtd/docbook/calstblx.dtd'
+  at /nix/store/...-builder.pl line 62.</screen>
+
+</para>
+
+<para>The cause is that two installed packages in the user environment
+have overlapping filenames (e.g.,
+<filename>xml/dtd/docbook/calstblx.dtd</filename>.  This usually
+happens when you accidentally try to install two versions of the same
+package.  For instance, in the example above, the Nix Packages
+collection contains two versions of <literal>docbook-xml</literal>, so
+<command>nix-env -i</command> will try to install both.  The default
+user environment builder has no way to way to resolve such conflicts,
+so it just gives up.</para>
+
+<para>Solution: remove one of the offending packages from the user
+environment (if already installed) using <command>nix-env
+-u</command>, or specify exactly which version should be installed
+(e.g., <literal>nix-env -i docbook-xml-4.2</literal>).</para>
+
+<para>Alternatively, you can modify the user environment builder
+script (in
+<filename><replaceable>prefix</replaceable>/share/nix/corepkgs/buildenv/builder.pl</filename>)
+to implement some conflict resolution policy.  E.g., the script could
+be modified to rename conflicting file names, or to pick one over the
+other.</para>
+
+</sect1>
 
-    <screen>
-      $ rm `db_archive -a -h <replaceable>prefix</replaceable>/var/nix/db`</screen>
 
-  </sect1>
-	
 </appendix>
-
-<!--
-local variables:
-sgml-parent-document: ("book.xml" "appendix")
-end:
--->

externals/Makefile.am

@@ -1,11 +1,11 @@
 # Berkeley DB
 
-DB = db-4.0.14
+DB = db-4.3.28.NC
 
 $(DB).tar.gz:
 	@echo "Nix requires Berkeley DB to build."
-	@echo "Please download version 4.0.14 from"
-	@echo "  http://www.sleepycat.com/update/snapshot/db-4.0.14.tar.gz"
+	@echo "Please download version 4.3.28 from"
+	@echo "  http://downloads.sleepycat.com/db-4.3.28.NC.tar.gz"
 	@echo "and place it in the externals/ directory."
 	false
 
@@ -16,24 +16,30 @@ have-db:
 	$(MAKE) $(DB)
 	touch have-db
 
+if HAVE_BDB
+build-db:
+else
 build-db: have-db
 	(pfx=`pwd` && \
 	cd $(DB)/build_unix && \
-	CC=$(CC) CXX=$(CXX) ../dist/configure --prefix=$$pfx/inst \
-	 --enable-cxx --disable-shared && \
-	make && \
-	make install)
+	CC="$(CC)" CXX="$(CXX)" CFLAGS="$(CFLAGS)" CXXFLAGS="$(CXXFLAGS)" \
+	 ../dist/configure --prefix=$$pfx/inst-bdb \
+	 --enable-cxx --disable-shared --disable-cryptography \
+         --disable-replication --disable-verify && \
+	$(MAKE) && \
+	$(MAKE) install)
 	touch build-db
+endif
 
 
 # CWI ATerm
 
-ATERM = aterm-2.0
+ATERM = aterm-2.3.1
 
 $(ATERM).tar.gz:
 	@echo "Nix requires the CWI ATerm library to build."
-	@echo "Please download version 2.0 from"
-	@echo "  http://www.cwi.nl/projects/MetaEnv/aterm/aterm-2.0.tar.gz"
+	@echo "Please download version 2.3.1 from"
+	@echo "  http://www.cwi.nl/projects/MetaEnv/aterm/aterm-2.3.1.tar.gz"
 	@echo "and place it in the externals/ directory."
 	false
 
@@ -44,15 +50,23 @@ have-aterm:
 	$(MAKE) $(ATERM)
 	touch have-aterm
 
+if HAVE_ATERM
+build-aterm:
+else
 build-aterm: have-aterm
 	(pfx=`pwd` && \
 	cd $(ATERM) && \
-	./configure --prefix=$$pfx/inst && \
-	make && \
-	make install)
+	CC="$(CC)" ./configure --prefix=$$pfx/inst-aterm && \
+	$(MAKE) && \
+	$(MAKE) install)
 	touch build-aterm
+endif
 
 
 all: build-db build-aterm
 
 EXTRA_DIST = $(DB).tar.gz $(ATERM).tar.gz
+
+ext-clean:
+	$(RM) -f have-db build-db have-aterm build-aterm
+	$(RM) -rf $(DB) $(ATERM)

make/examples/aterm/aterm/default.nix

@@ -0,0 +1,34 @@
+{sharedLib ? true}:
+
+rec {
+
+  inherit (import ../../../lib) compileC makeLibrary;
+
+  sources = [
+    ./afun.c
+    ./aterm.c
+    ./bafio.c
+    ./byteio.c
+    ./gc.c
+    ./hash.c
+    ./list.c
+    ./make.c
+    ./md5c.c
+    ./memory.c
+    ./tafio.c
+    ./version.c
+  ];
+
+  compile = fn: compileC {
+    main = fn;
+    localIncludes = "auto";
+    forSharedLib = sharedLib;
+  };
+
+  libATerm = makeLibrary {
+    libraryName = "ATerm";
+    objects = map compile sources;
+    inherit sharedLib;
+  };
+
+}

make/examples/aterm/default.nix

@@ -0,0 +1 @@
+import test/default.nix

make/examples/aterm/test/default.nix

@@ -0,0 +1,18 @@
+let {
+
+  inherit (import ../../../lib) compileC link;
+
+  inherit (import ../aterm {}) libATerm;
+
+  compile = fn: compileC {
+    main = fn;
+    localIncludes = "auto";
+    cFlags = "-I../aterm";
+  };
+
+  fib = link {objects = compile ./fib.c; libraries = libATerm;};
+
+  primes = link {objects = compile ./primes.c; libraries = libATerm;};
+  
+  body = [fib primes];
+}

make/examples/default.nix

@@ -0,0 +1,6 @@
+[ (import ./trivial)
+  (import ./simple-header)
+  (import ./not-so-simple-header)
+  (import ./not-so-simple-header-auto)
+  (import ./aterm)
+]

make/examples/not-so-simple-header-auto/bar/hello.h

@@ -0,0 +1 @@
+#define WHAT "World"

make/examples/not-so-simple-header-auto/default.nix

@@ -0,0 +1,11 @@
+let {
+
+  inherit (import ../../lib) compileC findIncludes link;
+
+  hello = link {programName = "hello"; objects = compileC {
+    main = ./foo/hello.c;
+    localIncludes = "auto";
+  };};
+
+  body = [hello];
+}

make/examples/not-so-simple-header-auto/foo/fnord/indirect.h

@@ -0,0 +1,3 @@
+#define HELLO "Hello"
+
+#include "../../bar/hello.h"

make/examples/not-so-simple-header-auto/foo/hello.c

@@ -0,0 +1,9 @@
+#include <stdio.h>
+
+#include "fnord/indirect.h"
+
+int main(int argc, char * * argv)
+{
+    printf(HELLO " " WHAT "\n");
+    return 0;
+}

make/examples/not-so-simple-header/bar/hello.h

@@ -0,0 +1 @@
+#define WHAT "World"

make/examples/not-so-simple-header/default.nix

@@ -0,0 +1,14 @@
+let {
+
+  inherit (import ../../lib) compileC link;
+
+  hello = link {programName = "hello"; objects = compileC {
+    main = ./foo/hello.c;
+    localIncludes = [
+      [./foo/fnord/indirect.h "fnord/indirect.h"]
+      [./bar/hello.h "fnord/../../bar/hello.h"]
+    ];
+  };};
+
+  body = [hello];
+}

make/examples/not-so-simple-header/foo/fnord/indirect.h

@@ -0,0 +1,3 @@
+#define HELLO "Hello"
+
+#include "../../bar/hello.h"

make/examples/not-so-simple-header/foo/hello.c

@@ -0,0 +1,9 @@
+#include <stdio.h>
+
+#include "fnord/indirect.h"
+
+int main(int argc, char * * argv)
+{
+    printf(HELLO " " WHAT "\n");
+    return 0;
+}

make/examples/simple-header/default.nix

@@ -0,0 +1,11 @@
+let {
+
+  inherit (import ../../lib) compileC link;
+
+  hello = link {objects = compileC {
+    main = ./hello.c;
+    localIncludes = [ [./hello.h "hello.h"] ];
+  };};
+
+  body = [hello];
+}

make/examples/simple-header/hello.c

@@ -0,0 +1,9 @@
+#include <stdio.h>
+
+#include "hello.h"
+
+int main(int argc, char * * argv)
+{
+    printf("Hello " WHAT "\n");
+    return 0;
+}

make/examples/simple-header/hello.h

@@ -0,0 +1 @@
+#define WHAT "World"

make/examples/trivial/default.nix

@@ -0,0 +1,8 @@
+let {
+
+  inherit (import ../../lib) compileC link;
+
+  hello = link {objects = compileC {main = ./hello.c;};};
+
+  body = [hello];
+}

make/examples/trivial/hello.c

@@ -0,0 +1,7 @@
+#include <stdio.h>
+
+int main(int argc, char * * argv)
+{
+    printf("Hello World\n");
+    return 0;
+}

make/lib/compile-c.sh

@@ -0,0 +1,73 @@
+. $stdenv/setup
+
+mainName=$(basename $main | cut -c34-)
+
+echo "compiling \`$mainName'..."
+
+# Turn $localIncludes into an array.
+localIncludes=($localIncludes)
+
+# Determine how many `..' levels appear in the header file references.
+# E.g., if there is some reference `../../foo.h', then we have to
+# insert two extra levels in the directory structure, so that `a.c' is
+# stored at `dotdot/dotdot/a.c', and a reference from it to
+# `../../foo.h' resolves to `dotdot/dotdot/../../foo.h' == `foo.h'.
+n=0
+maxDepth=0
+for ((n = 0; n < ${#localIncludes[*]}; n += 2)); do
+    target=${localIncludes[$((n + 1))]}
+
+    # Split the target name into path components using some IFS magic.
+    savedIFS="$IFS"
+    IFS=/
+    components=($target)
+    depth=0
+    for ((m = 0; m < ${#components[*]}; m++)); do
+        c=${components[m]}
+        if test "$c" = ".."; then
+            depth=$((depth + 1))
+        fi
+    done
+    IFS="$savedIFS"
+
+    if test $depth -gt $maxDepth; then
+        maxDepth=$depth;
+    fi
+done
+
+# Create the extra levels in the directory hierarchy.
+prefix=
+for ((n = 0; n < maxDepth; n++)); do
+    prefix="dotdot/$prefix"
+done
+
+# Create symlinks to the header files.
+for ((n = 0; n < ${#localIncludes[*]}; n += 2)); do
+    source=${localIncludes[n]}
+    target=${localIncludes[$((n + 1))]}
+
+    # Create missing directories.  We use IFS magic to split the path
+    # into path components.
+    savedIFS="$IFS"
+    IFS=/
+    components=($prefix$target)
+    fullPath=(.)
+    for ((m = 0; m < ${#components[*]} - 1; m++)); do
+        fullPath=("${fullPath[@]}" ${components[m]})
+        if ! test -d "${fullPath[*]}"; then
+            mkdir "${fullPath[*]}"
+        fi
+    done
+    IFS="$savedIFS"
+    
+    ln -sf $source $prefix$target
+done
+
+# Create a symlink to the main file.
+if ! test "$(readlink $prefix$mainName)" = $main; then
+    ln -s $main $prefix$mainName
+fi
+
+mkdir $out
+test "$prefix" && cd $prefix
+gcc -Wall $cFlags -c $mainName -o $out/$mainName.o

make/lib/default.nix

@@ -0,0 +1,59 @@
+rec {
+
+  # Should point at your Nixpkgs installation.
+  pkgPath = ./pkgs;
+
+  pkgs = import (pkgPath + /system/all-packages.nix) {};
+
+  stdenv = pkgs.stdenv;
+  
+
+  compileC = {main, localIncludes ? [], cFlags ? "", forSharedLib ? false}:
+  stdenv.mkDerivation {
+    name = "compile-c";
+    builder = ./compile-c.sh;
+    localIncludes =
+      if localIncludes == "auto" then
+        import (findIncludes {
+          main = toString main;
+          hack = __currentTime;
+          inherit cFlags;
+        })
+      else
+        localIncludes;
+    inherit main;
+    cFlags = [
+      cFlags
+      (if forSharedLib then ["-fpic"] else [])
+    ];
+  };
+
+  /*
+  runCommand = {command}: {
+    name = "run-command";
+    builder = ./run-command.sh;
+    inherit command;
+  };
+  */
+
+  findIncludes = {main, hack, cFlags ? ""}: stdenv.mkDerivation {
+    name = "find-includes";
+    builder = ./find-includes.sh;
+    inherit main hack cFlags;
+  };
+  
+  link = {objects, programName ? "program", libraries ? []}: stdenv.mkDerivation {
+    name = "link";
+    builder = ./link.sh;
+    inherit objects programName libraries;
+  };
+
+  makeLibrary = {objects, libraryName ? [], sharedLib ? false}:
+  # assert sharedLib -> fold (obj: x: assert obj.sharedLib && x) false objects
+  stdenv.mkDerivation {
+    name = "library";
+    builder = ./make-library.sh;
+    inherit objects libraryName sharedLib;
+  };
+
+}

make/lib/find-includes.sh

@@ -0,0 +1,20 @@
+. $stdenv/setup
+
+echo "finding includes of \`$(basename $main)'..."
+
+makefile=$NIX_BUILD_TOP/makefile
+
+mainDir=$(dirname $main)
+(cd $mainDir && gcc $cFlags -MM $(basename $main) -MF $makefile) || false
+
+echo "[" >$out
+
+while read line; do
+    line=$(echo "$line" | sed 's/.*://')
+    for i in $line; do
+        fullPath=$(readlink -f $mainDir/$i)
+        echo "  [ $fullPath \"$i\" ]" >>$out
+    done
+done < $makefile
+
+echo "]" >>$out

make/lib/link.sh

@@ -0,0 +1,21 @@
+. $stdenv/setup
+
+shopt -s nullglob
+
+objs=
+for i in $objects; do
+    obj=$(echo $i/*.o)
+    objs="$objs $obj"
+done
+
+libs=
+for i in $libraries; do
+    lib=$(echo $i/*.a; echo $i/*.so)
+    name=$(echo $(basename $lib) | sed -e 's/^lib//' -e 's/.a$//' -e 's/.so$//')
+    libs="$libs -L$(dirname $lib) -l$name" 
+done
+
+echo "linking object files into \`$programName'..."
+
+mkdir $out
+gcc -o $out/$programName $objs $libs

make/lib/make-library.sh

@@ -0,0 +1,28 @@
+. $stdenv/setup
+
+objs=
+for i in $objects; do
+    obj=$(echo $i/*.o)
+    objs="$objs $obj"
+done
+
+echo "archiving object files into library \`$libraryName'..."
+
+ensureDir $out
+
+if test -z "$sharedLib"; then
+
+    outPath=$out/lib${libraryName}.a
+
+    ar crs $outPath $objs
+    ranlib $outPath
+
+else
+
+    outPath=$out/lib${libraryName}.so
+
+    gcc -shared -o $outPath $objs
+
+fi    
+
+    

misc/Makefile.am

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

misc/emacs/Makefile.am

@@ -0,0 +1,5 @@
+EXTRA_DIST = nix-mode.el
+
+install-data-local:
+	$(INSTALL) -d $(DESTDIR)$(datadir)/emacs/site-lisp
+	$(INSTALL_DATA) nix-mode.el $(DESTDIR)$(datadir)/emacs/site-lisp

misc/emacs/README

@@ -0,0 +1,10 @@
+The Nix Emacs mode supports syntax highlighting, somewhat sensible
+indenting, and refilling of comments.
+
+To enable Nix mode in Emacs, add something like this to your ~/.emacs
+file:
+
+  (load "/nix/share/emacs/site-lisp/nix-mode.el")
+
+This automatically causes Nix mode to be activated for all files with
+extension `.nix'.

misc/emacs/nix-mode.el

@@ -0,0 +1,109 @@
+(defun nix-mode ()
+  "Major mode for editing Nix expressions.
+
+The following commands may be useful:
+
+  '\\[newline-and-indent]'
+    Insert a newline and move the cursor to align with the previous
+    non-empty line.
+
+  '\\[fill-paragraph]'
+    Refill a paragraph so that all lines are at most `fill-column'
+    lines long.  This should do the right thing for comments beginning
+    with `#'.  However, this command doesn't work properly yet if the
+    comment is adjacent to code (i.e., no intervening empty lines).
+    In that case, select the text to be refilled and use
+    `\\[fill-region]' instead.
+
+The hook `nix-mode-hook' is run when Nix mode is started.
+
+\\{nix-mode-map}
+"
+
+  (interactive)
+  
+  (kill-all-local-variables)
+  
+  (setq major-mode 'nix-mode)
+  (setq mode-name "Nix")
+
+  (use-local-map nix-mode-map)
+
+  (set-syntax-table nix-mode-syntax-table)
+
+  ;; Font lock support.
+  (setq font-lock-defaults '(nix-keywords nil nil nil nil))
+
+  ;; Automatic indentation [C-j].
+  (make-local-variable 'indent-line-function)
+  (setq indent-line-function 'nix-indent-line)
+
+  ;; Indenting of comments.
+  (make-local-variable 'comment-start)
+  (setq comment-start "# ")
+  (make-local-variable 'comment-end)
+  (setq comment-end "")
+  (make-local-variable 'comment-start-skip)
+  (setq comment-start-skip "\\(^\\|\\s-\\);?#+ *")
+
+  ;; Filling of comments.
+  (make-local-variable 'adaptive-fill-mode)
+  (setq adaptive-fill-mode t)
+  (make-local-variable 'paragraph-start)
+  (setq paragraph-start "[ \t]*\\(#+[ \t]*\\)?$")
+  (make-local-variable 'paragraph-separate)
+  (setq paragraph-separate paragraph-start)
+  
+  (run-hooks 'nix-mode-hook)
+  )
+
+
+(defvar nix-mode-map nil
+  "Keymap for Nix mode.")
+
+(setq nix-mode-map (make-sparse-keymap))
+;(define-key nix-mode-map [tab] 'tab-to-tab-stop)
+
+
+(defvar nix-keywords
+  '("\\<if\\>" "\\<then\\>" "\\<else\\>" "\\<assert\\>"
+    "\\<let\\>" "\\<rec\\>" "\\<inherit\\>"
+    ("\\<true\\>" . font-lock-builtin-face)
+    ("\\<false\\>" . font-lock-builtin-face)
+    ("\\<null\\>" . font-lock-builtin-face)
+    ("\\<import\\>" . font-lock-builtin-face)
+    ("\\<derivation\\>" . font-lock-builtin-face)
+    ("\\<baseNameOf\\>" . font-lock-builtin-face)
+    ("\\<toString\\>" . font-lock-builtin-face)
+    ("\\<isNull\\>" . font-lock-builtin-face)
+    ("\\<\\([a-zA-Z_][a-zA-Z0-9_']*\\)[ \t]*="
+     (1 font-lock-variable-name-face nil nil))
+    ("[a-zA-Z][a-zA-Z0-9\\+-\\.]*:[a-zA-Z0-9%/\\?:@&=\\+\\$,_\\.!~\\*'-]+"
+     . font-lock-constant-face)
+    ("[a-zA-Z0-9._\\+-]*\\(/[a-zA-Z0-9._\\+-]+\\)+"
+     . font-lock-constant-face)
+    ))
+
+
+(defvar nix-mode-syntax-table nil
+  "Syntax table for Nix mode.")
+
+(if nix-mode-syntax-table
+    nil
+    (progn
+      (setq nix-mode-syntax-table (make-syntax-table))
+      (modify-syntax-entry ?/ ". 14" nix-mode-syntax-table)
+      (modify-syntax-entry ?* ". 23" nix-mode-syntax-table)
+      (modify-syntax-entry ?# "< b" nix-mode-syntax-table)
+      (modify-syntax-entry ?\n "> b" nix-mode-syntax-table)
+      ))
+
+
+(defun nix-indent-line ()
+  "Indent current line in a Nix expression."
+  (interactive)
+  (indent-relative-maybe))
+
+
+(setq auto-mode-alist (cons '("\\.nix\\'" . nix-mode) auto-mode-alist))
+(setq auto-mode-alist (cons '("\\.nix.in\\'" . nix-mode) auto-mode-alist))

nix.conf.example

@@ -0,0 +1,49 @@
+### Option `gc-keep-outputs'
+#
+# If `true', the garbage collector will keep the outputs of
+# non-garbage derivations.  If `false' (default), outputs will be
+# deleted unless they are GC roots themselves (or reachable from other
+# roots).
+# 
+# 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
+# `true'.
+gc-keep-outputs = false
+
+
+### Option `gc-keep-derivations'
+#
+# If `true' (default), the garbage collector will keep the derivations
+# from which non-garbage store paths were built.  If `false', they
+# will be deleted unless explicitly registered as a root (or reachable
+# from other roots).
+#
+# 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 `gc-keep-outputs' is also
+# turned on).
+gc-keep-derivations = true
+
+
+### Option `env-keep-derivations'
+#
+# If `false' (default), derivations are not stored in Nix user
+# environments.  That is, the derivation any build-time-only
+# dependencies may be garbage-collected.
+#
+# If `true', 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 (`nix-env --delete-generations').  To prevent
+# build-time-only dependencies from being collected, you should also
+# turn on `gc-keep-outputs'.
+#
+# The difference between this option and `gc-keep-derivations' is that
+# this one is `sticky': it applies to any user environment created
+# while this option was enabled, while `gc-keep-derivations' only
+# applies at the moment the garbage collector is run.
+env-keep-derivations = false

nix.spec.in

@@ -0,0 +1,77 @@
+%define enable_setuid ""
+%define nix_user "nix"
+%define nix_group "nix"
+
+# If set, the Nix user and group will be created by the RPM
+# pre-install script.
+%define nix_user_uid ""
+%define nix_group_gid ""
+
+Summary: The Nix software deployment system
+Name: nix
+Version: @version@
+Release: 1
+License: GPL
+Group: Software Deployment
+URL: http://www.cs.uu.nl/groups/ST/Trace/Nix
+Source0: %{name}-@version@.tar.bz2
+BuildRoot: %{_tmppath}/%{name}-%{version}-buildroot
+%define _prefix /nix
+Prefix: %{_prefix}
+Requires: /usr/bin/perl
+
+# Hack to make that shitty RPM scanning hack shut up.
+Provides: perl(readmanifest)
+                                                               
+%description
+
+Nix is a system for software deployment.
+
+%prep
+%setup -q
+
+%build
+extraFlags=
+if test -n "%{enable_setuid}"; then
+    extraFlags="$extraFlags --enable-setuid"
+    if test -n "%{nix_user}"; then
+        extraFlags="$extraFlags --with-nix-user=%{nix_user}"
+    fi
+    if test -n "%{nix_group}"; then
+        extraFlags="$extraFlags --with-nix-group=%{nix_group}"
+    fi
+fi
+./configure --prefix=%{_prefix} $extraFlags
+make
+make check
+
+%install
+rm -rf $RPM_BUILD_ROOT
+make DESTDIR=$RPM_BUILD_ROOT install
+strip $RPM_BUILD_ROOT/%{_prefix}/bin/* || true
+
+%clean
+rm -rf $RPM_BUILD_ROOT
+
+%pre
+if test -n "%{nix_group_gid}"; then
+    /usr/sbin/groupadd -g %{nix_group_gid} %{nix_group} || true
+fi
+if test -n "%{nix_user_uid}"; then
+    /usr/sbin/useradd -c "Nix" -u %{nix_user_uid} \
+        -s /sbin/nologin -r -d /var/empty %{nix_user} \
+        -g %{nix_group} || true
+fi
+
+%files
+#%defattr(-,root,root)
+%{_prefix}/bin
+%{_prefix}/libexec
+%{_prefix}/var
+%{_prefix}/share
+%{_prefix}/man
+%{_prefix}/store
+%config
+%{_prefix}/etc
+#%doc
+#%{_prefix}/share/nix/manual

scripts/Makefile.am

@@ -1,19 +1,26 @@
-bin_SCRIPTS = nix-switch nix-collect-garbage \
- nix-pull nix-push nix-prefetch-url
+bin_SCRIPTS = nix-collect-garbage \
+  nix-pull nix-push nix-prefetch-url \
+  nix-install-package nix-channel nix-build
 
-noinst_SCRIPTS = nix-profile.sh
+noinst_SCRIPTS = nix-profile.sh generate-patches.pl
 
-install-exec-local:
-	$(INSTALL) -d $(sysconfdir)/profile.d
-	$(INSTALL_PROGRAM) nix-profile.sh $(sysconfdir)/profile.d/nix.sh
-	$(INSTALL) -d $(sysconfdir)/nix
-# !!! don't overwrite local modifications
-	$(INSTALL_DATA) prebuilts.conf $(sysconfdir)/nix/prebuilts.conf
+nix-pull nix-push: readmanifest.pm download-using-manifests.pl
+
+install-exec-local: readmanifest.pm download-using-manifests.pl
+	$(INSTALL) -d $(DESTDIR)$(sysconfdir)/profile.d
+	$(INSTALL_PROGRAM) nix-profile.sh $(DESTDIR)$(sysconfdir)/profile.d/nix.sh
+	$(INSTALL) -d $(DESTDIR)$(libexecdir)/nix
+	$(INSTALL_DATA) readmanifest.pm $(DESTDIR)$(libexecdir)/nix 
+	$(INSTALL_PROGRAM) download-using-manifests.pl $(DESTDIR)$(libexecdir)/nix 
+	$(INSTALL) -d $(DESTDIR)$(sysconfdir)/nix
 
 include ../substitute.mk
 
-EXTRA_DIST = nix-switch.in nix-collect-garbage.in \
- nix-pull.in nix-push.in nix-profile.sh.in \
- nix-prefetch-url.in \
- prebuilts.conf
-
+EXTRA_DIST = nix-collect-garbage.in \
+  nix-pull.in nix-push.in nix-profile.sh.in \
+  nix-prefetch-url.in nix-install-package.in \
+  nix-channel.in \
+  readmanifest.pm.in \
+  nix-build.in \
+  download-using-manifests.pl.in \
+  generate-patches.pl.in

scripts/copying-collector.pl

@@ -0,0 +1,111 @@
+#! /usr/bin/perl -w
+
+use strict;
+
+my @paths = `nix-store -qR /home/eelco/.nix-profile/bin/firefox`;
+
+my %copyMap;
+my %rewriteMap;
+
+
+my $counter = 0;
+
+foreach my $path (@paths) {
+    chomp $path;
+
+    $path =~ /^(.*)\/([^-]+)-(.*)$/ or die "invalid store path `$path'";
+    my $hash = $2;
+
+#    my $newHash = "deadbeef" . (sprintf "%024d", $counter++);
+    my $newHash = "deadbeef" . substr($hash, 0, 24);
+    my $newPath = "/home/eelco/chroot/$1/$newHash-$3";
+
+    die unless length $newHash == length $hash;
+
+    $copyMap{$path} = $newPath;
+    $rewriteMap{$hash} = $newHash;
+}
+
+
+my %rewriteMap2;
+
+
+sub rewrite;
+sub rewrite {
+    my $src = shift;
+    my $dst = shift;
+
+    if (-l $dst) {
+
+        my $target = readlink $dst or die;
+
+        foreach my $srcHash (keys %rewriteMap2) {
+            my $dstHash = $rewriteMap{$srcHash};
+            print "  $srcHash -> $dstHash\n";
+            $target =~ s/$srcHash/$dstHash/g;
+        }
+
+        unlink $dst or die;
+
+        symlink $target, $dst;
+        
+    }
+
+    elsif (-f $dst) {
+
+        print "$dst\n";
+
+        foreach my $srcHash (keys %rewriteMap2) {
+            my $dstHash = $rewriteMap{$srcHash};
+            print "  $srcHash -> $dstHash\n";
+
+            my @stats = lstat $dst or die;
+            
+            system "sed s/$srcHash/$dstHash/g < '$dst' > '$dst.tmp'";
+            die if $? != 0;
+            rename "$dst.tmp", $dst or die;
+
+            chmod $stats[2], $dst or die;
+        }
+
+    }
+
+    elsif (-d $dst) {
+
+        chmod 0755, $dst;
+        
+        opendir(DIR, "$dst") or die "cannot open `$dst': $!";
+        my @files = readdir DIR;
+        closedir DIR;
+        
+        foreach my $file (@files) {
+            next if $file eq "." || $file eq "..";
+            rewrite "$src/$file", "$dst/$file";
+        }
+    }
+}
+
+
+foreach my $src (keys %copyMap) {
+    my $dst = $copyMap{$src};
+    print "$src -> $dst\n";
+
+    if (!-e $dst) {
+        system "cp -prd $src $dst";
+        die if $? != 0;
+
+        my @refs = `nix-store -q --references $src`;
+
+        %rewriteMap2 = ();
+        foreach my $ref (@refs) {
+            chomp $ref;
+
+            $ref =~ /^(.*)\/([^-]+)-(.*)$/ or die "invalid store path `$ref'";
+            my $hash = $2;
+
+            $rewriteMap2{$hash} = $rewriteMap{$hash};
+        }
+
+        rewrite $src, $dst;
+    }
+}

scripts/download-using-manifests.pl.in

@@ -0,0 +1,279 @@
+#! @perl@ -w -I@libexecdir@/nix
+
+use strict;
+use readmanifest;
+
+my $manifestDir = "@localstatedir@/nix/manifests";
+my $logFile = "@localstatedir@/log/nix/downloads";
+
+open LOGFILE, ">>$logFile" or die "cannot open log file $logFile";
+
+
+# Check the arguments.
+die unless scalar @ARGV == 1;
+my $targetPath = $ARGV[0];
+
+my $date = `date` or die;
+chomp $date;
+print LOGFILE "$$ get $targetPath $date\n";
+
+print "\n*** Trying to download/patch `$targetPath'\n";
+
+
+# Load all manifests.
+my %narFiles;
+my %patches;
+my %successors;
+
+for my $manifest (glob "$manifestDir/*.nixmanifest") {
+#    print STDERR "reading $manifest\n";
+    if (readManifest($manifest, \%narFiles, \%patches, \%successors) < 3) {
+        print STDERR "you have an old-style manifest `$manifest'; please delete it\n";
+        exit 1;
+    }
+}
+
+
+# Build a graph of all store paths that might contribute to the
+# construction of $targetPath, and the special node "start".  The
+# edges are either patch operations, or downloads of full NAR files.
+# The latter edges only occur between "start" and a store path.
+
+my %graph;
+
+$graph{"start"} = {d => 0, pred => undef, edges => []};
+
+my @queue = ();
+my $queueFront = 0;
+my %done;
+
+sub addToQueue {
+    my $v = shift;
+    return if defined $done{$v};
+    $done{$v} = 1;
+    push @queue, $v;
+}
+
+sub addNode {
+    my $u = shift;
+    $graph{$u} = {d => 999999999999, pred => undef, edges => []}
+        unless defined $graph{$u};
+}
+
+sub addEdge {
+    my $u = shift;
+    my $v = shift;
+    my $w = shift;
+    my $type = shift;
+    my $info = shift;
+    addNode $u;
+    push @{$graph{$u}->{edges}},
+        {weight => $w, start => $u, end => $v, type => $type, info => $info};
+    my $n = scalar @{$graph{$u}->{edges}};
+}
+
+addToQueue $targetPath;
+
+sub isValidPath {
+    my $p = shift;
+    system "@bindir@/nix-store --check-validity '$p' 2> /dev/null";
+    return $? == 0;
+}
+
+sub parseHash {
+    my $hash = shift;
+    if ($hash =~ /^(.+):(.+)$/) {
+        return ($1, $2);
+    } else {
+        return ("md5", $hash);
+    }
+}
+
+while ($queueFront < scalar @queue) {
+    my $u = $queue[$queueFront++];
+#    print "$u\n";
+
+    addNode $u;
+
+    # If the path already exists, it has distance 0 from the "start"
+    # node.
+    if (isValidPath($u)) {
+        addEdge "start", $u, 0, "present", undef;
+    }
+
+    else {
+
+        # Add patch edges.
+        my $patchList = $patches{$u};
+        foreach my $patch (@{$patchList}) {
+            if (isValidPath($patch->{basePath})) {
+                # !!! this should be cached
+                my ($baseHashAlgo, $baseHash) = parseHash $patch->{baseHash};
+                my $format = "--base32";
+                $format = "" if $baseHashAlgo eq "md5";
+                my $hash = `@bindir@/nix-hash --type '$baseHashAlgo' $format "$patch->{basePath}"`;
+                chomp $hash;
+#                print "  MY HASH is $hash\n";
+                if ($hash ne $baseHash) {
+                    print LOGFILE "$$ rejecting $patch->{basePath}\n";
+                    next;
+                }
+            }
+#            print "  PATCH from $patch->{basePath}\n";
+            addToQueue $patch->{basePath};
+            addEdge $patch->{basePath}, $u, $patch->{size}, "patch", $patch;
+        }
+
+        # Add NAR file edges to the start node.
+        my $narFileList = $narFiles{$u};
+        foreach my $narFile (@{$narFileList}) {
+#            print "  NAR from $narFile->{url}\n";
+            addEdge "start", $u, $narFile->{size}, "narfile", $narFile;
+            if ($u eq $targetPath) {
+                print LOGFILE "$$ full-download-would-be $narFile->{size}\n";
+            }
+        }
+
+    }
+}
+
+
+# Run Dijkstra's shortest path algorithm to determine the shortest
+# sequence of download and/or patch actions that will produce
+# $targetPath.
+
+sub byDistance { # sort by distance, reversed
+    return -($graph{$a}->{d} <=> $graph{$b}->{d});
+}
+
+my @todo = keys %graph;
+
+while (scalar @todo > 0) {
+
+    # Remove the closest element from the todo list.
+    @todo = sort byDistance @todo;
+    my $u = pop @todo;
+
+    my $u_ = $graph{$u};
+
+#    print "IN $u $u_->{d}\n";
+
+    foreach my $edge (@{$u_->{edges}}) {
+        my $v_ = $graph{$edge->{end}};
+        if ($v_->{d} > $u_->{d} + $edge->{weight}) {
+            $v_->{d} = $u_->{d} + $edge->{weight};
+            # Store the edge; to edge->start is actually the
+            # predecessor.
+            $v_->{pred} = $edge; 
+#            print "  RELAX $edge->{end} $v_->{d}\n";
+        }
+    }
+}
+
+
+# Retrieve the shortest path from "start" to $targetPath.
+my @path = ();
+my $cur = $targetPath;
+die "don't know how to produce $targetPath\n"
+    unless defined $graph{$targetPath}->{pred};
+while ($cur ne "start") {
+    push @path, $graph{$cur}->{pred};
+    $cur = $graph{$cur}->{pred}->{start};
+}
+
+
+# Traverse the shortest path, perform the actions described by the
+# edges.
+my $curStep = 1;
+my $maxStep = scalar @path;
+
+sub downloadFile {
+    my $url = shift;
+    my ($hashAlgo, $hash) = parseHash(shift);
+    $ENV{"PRINT_PATH"} = 1;
+    $ENV{"QUIET"} = 1;
+    $ENV{"NIX_HASH_ALGO"} = $hashAlgo;
+    my ($hash2, $path) = `@bindir@/nix-prefetch-url '$url' '$hash'`;
+    die "download of `$url' failed" unless $? == 0;
+    chomp $hash2;
+    chomp $path;
+    die "hash mismatch, expected $hash, got $hash2" if $hash ne $hash2;
+    return $path;
+}
+
+while (scalar @path > 0) {
+    my $edge = pop @path;
+    my $u = $edge->{start};
+    my $v = $edge->{end};
+
+    print "\n*** Step $curStep/$maxStep: ";
+
+    if ($edge->{type} eq "present") {
+        print "using already present path `$v'\n";
+        print LOGFILE "$$ present $v\n";
+
+        if ($curStep < $maxStep) {
+            # Since this is not the last step, the path will be used
+            # as a base to one or more patches.  So turn the base path
+            # into a NAR archive, to which we can apply the patch.
+            print "  packing base path...\n";
+            system "@bindir@/nix-store --dump $v > /tmp/nar";
+            die "cannot dump `$v'" if ($? != 0);
+        }
+    }
+
+    elsif ($edge->{type} eq "patch") {
+        my $patch = $edge->{info};
+        print "applying patch `$patch->{url}' to `$u' to create `$v'\n";
+
+        print LOGFILE "$$ patch $patch->{url} $patch->{size} $patch->{baseHash} $u $v\n";
+
+        # Download the patch.
+        print "  downloading patch...\n";
+        my $patchPath = downloadFile "$patch->{url}", "$patch->{hash}";
+
+        # Apply the patch to the NAR archive produced in step 1 (for
+        # the already present path) or a later step (for patch sequences).
+        print "  applying patch...\n";
+        system "@libexecdir@/bspatch /tmp/nar /tmp/nar2 $patchPath";
+        die "cannot apply patch `$patchPath' to /tmp/nar" if ($? != 0);
+
+        if ($curStep < $maxStep) {
+            # The archive will be used as the base of the next patch.
+            rename "/tmp/nar2", "/tmp/nar" or die "cannot rename NAR archive: $!";
+        } else {
+            # This was the last patch.  Unpack the final NAR archive
+            # into the target path.
+            print "  unpacking patched archive...\n";
+            system "@bindir@/nix-store --restore $v < /tmp/nar2";
+            die "cannot unpack /tmp/nar2 into `$v'" if ($? != 0);
+        }
+    }
+
+    elsif ($edge->{type} eq "narfile") {
+        my $narFile = $edge->{info};
+        print "downloading `$narFile->{url}' into `$v'\n";
+
+        print LOGFILE "$$ narfile $narFile->{url} $narFile->{size} $v\n";
+        
+        # Download the archive.
+        print "  downloading archive...\n";
+        my $narFilePath = downloadFile "$narFile->{url}", "$narFile->{hash}";
+
+        if ($curStep < $maxStep) {
+            # The archive will be used a base to a patch.
+            system "@bunzip2@ < '$narFilePath' > /tmp/nar";
+        } else {
+            # Unpack the archive into the target path.
+            print "  unpacking archive...\n";
+            system "@bunzip2@ < '$narFilePath' | @bindir@/nix-store --restore '$v'";
+            die "cannot unpack `$narFilePath' into `$v'" if ($? != 0);
+        }
+    }
+
+    $curStep++;
+}
+
+
+print LOGFILE "$$ success\n";
+close LOGFILE;

scripts/gc-releases.pl

@@ -0,0 +1,75 @@
+#! /usr/bin/perl -w
+
+use strict;
+use readmanifest;
+
+
+# Read the archive directories.
+my @archives = ();
+my %archives;
+
+sub readDir {
+    my $dir = shift;
+    opendir(DIR, "$dir") or die "cannot open `$dir': $!";
+    my @as = readdir DIR;
+    foreach my $archive (@as) {
+        push @archives, $archive;
+        $archives{$archive} = "$dir/$archive";
+    }
+    closedir DIR;
+}
+
+readDir "/mnt/scratchy/eelco/public_html/nix-cache";
+readDir "/mnt/scratchy/eelco/public_html/patches";
+
+print STDERR scalar @archives, "\n";
+
+
+# Read the manifests.
+my %narFiles;
+my %patches;
+my %successors;
+
+foreach my $manifest (@ARGV) {
+    print STDERR "loading $manifest\n";
+    if (readManifest($manifest, \%narFiles, \%patches, \%successors, 1) < 3) {
+#        die "manifest `$manifest' is too old (i.e., for Nix <= 0.7)\n";
+    }
+}
+
+
+# Find the live archives.
+my %usedFiles;
+
+foreach my $narFile (keys %narFiles) {
+    foreach my $file (@{$narFiles{$narFile}}) {
+        $file->{url} =~ /\/([^\/]+)$/;
+        my $basename = $1;
+        die unless defined $basename;
+#        print $basename, "\n";
+        $usedFiles{$basename} = 1;
+        die "missing archive `$basename'"
+            unless defined $archives{$basename};
+    }
+}
+
+foreach my $patch (keys %patches) {
+    foreach my $file (@{$patches{$patch}}) {
+        $file->{url} =~ /\/([^\/]+)$/;
+        my $basename = $1;
+        die unless defined $basename;
+#        print $basename, "\n";
+        $usedFiles{$basename} = 1;
+        die "missing archive `$basename'"
+            unless defined $archives{$basename};
+    }
+}
+
+
+# Print out the dead archives.
+foreach my $archive (@archives) {
+    next if $archive eq "." || $archive eq "..";
+    if (!defined $usedFiles{$archive}) {
+        print $archives{$archive}, "\n";
+    }
+}

scripts/generate-patches.pl.in

@@ -0,0 +1,376 @@
+#! @perl@ -w -I@libexecdir@/nix
+
+use strict;
+use POSIX qw(tmpnam);
+use readmanifest;
+
+die unless scalar @ARGV == 5;
+
+my $hashAlgo = "sha256";
+
+my $cacheDir = $ARGV[0];
+my $patchesDir = $ARGV[1];
+my $patchesURL = $ARGV[2];
+my $srcDir = $ARGV[3];
+my $dstDir = $ARGV[4];
+
+my $tmpdir;
+do { $tmpdir = tmpnam(); }
+until mkdir $tmpdir, 0777;
+
+print "TEMP = $tmpdir\n";
+
+#END { rmdir $tmpdir; }
+
+my %srcNarFiles;
+my %srcPatches;
+my %srcSuccessors;
+
+my %dstNarFiles;
+my %dstPatches;
+my %dstSuccessors;
+
+readManifest "$srcDir/MANIFEST",
+    \%srcNarFiles, \%srcPatches, \%srcSuccessors;
+
+readManifest "$dstDir/MANIFEST",
+    \%dstNarFiles, \%dstPatches, \%dstSuccessors;
+
+
+sub findOutputPaths {
+    my $narFiles = shift;
+    my $successors = shift;
+
+    my %outPaths;
+    
+    foreach my $p (keys %{$narFiles}) {
+
+        # Ignore store expressions.
+        next if ($p =~ /\.store$/);
+        next if ($p =~ /\.drv$/);
+        
+        # Ignore builders (too much ambiguity -- they're all called
+        # `builder.sh').
+        next if ($p =~ /\.sh$/);
+        next if ($p =~ /\.patch$/);
+        
+        # Don't bother including tar files etc.
+        next if ($p =~ /\.tar\.(gz|bz2)$/ || $p =~ /\.zip$/ || $p =~ /\.bin$/);
+
+        $outPaths{$p} = 1;
+    }
+
+    return %outPaths;
+}
+
+print "finding src output paths...\n";
+my %srcOutPaths = findOutputPaths \%srcNarFiles, \%srcSuccessors;
+
+print "finding dst output paths...\n";
+my %dstOutPaths = findOutputPaths \%dstNarFiles, \%dstSuccessors;
+
+
+sub getNameVersion {
+    my $p = shift;
+    $p =~ /\/[0-9a-z]+((?:-[a-zA-Z][^\/-]*)+)([^\/]*)$/;
+    my $name = $1;
+    my $version = $2;
+    $name =~ s/^-//;
+    $version =~ s/^-//;
+    return ($name, $version);
+}
+
+
+# A quick hack to get a measure of the `distance' between two
+# versions: it's just the position of the first character that differs
+# (or 999 if they are the same).
+sub versionDiff {
+    my $s = shift;
+    my $t = shift;
+    my $i;
+    return 999 if $s eq $t;
+    for ($i = 0; $i < length $s; $i++) {
+        return $i if $i >= length $t or
+            substr($s, $i, 1) ne substr($t, $i, 1);
+    }
+    return $i;
+}
+
+
+sub getNarBz2 {
+    my $narFiles = shift;
+    my $storePath = shift;
+    
+    my $narFileList = $$narFiles{$storePath};
+    die "missing store expression $storePath" unless defined $narFileList;
+
+    my $narFile = @{$narFileList}[0];
+    die unless defined $narFile;
+
+    $narFile->{url} =~ /\/([^\/]+)$/;
+    die unless defined $1;
+    return "$cacheDir/$1";
+}
+
+
+sub containsPatch {
+    my $patches = shift;
+    my $storePath = shift;
+    my $basePath = shift;
+    my $patchList = $$patches{$storePath};
+    return 0 if !defined $patchList;
+    my $found = 0;
+    foreach my $patch (@{$patchList}) {
+        # !!! baseHash might differ
+        return 1 if $patch->{basePath} eq $basePath;
+    }
+    return 0;
+}
+
+
+# Compute the "weighted" number of uses of a path in the build graph.
+sub computeUses {
+    my $narFiles = shift;
+    my $path = shift;
+
+    # Find the deriver of $path.
+    return 1 unless defined $$narFiles{$path};
+    my $deriver = @{$$narFiles{$path}}[0]->{deriver};
+    return 1 unless defined $deriver && $deriver ne "";
+
+#    print "  DERIVER $deriver\n";
+
+    # Optimisation: build the referers graph from the references
+    # graph.
+    my %referers;
+    foreach my $q (keys %{$narFiles}) {
+        my @refs = split " ", @{$$narFiles{$q}}[0]->{references};
+        foreach my $r (@refs) {
+            $referers{$r} = [] unless defined $referers{$r};
+            push @{$referers{$r}}, $q;
+        }
+    }
+
+    # Determine the shortest path from $deriver to all other reachable
+    # paths in the `referers' graph.
+
+    my %dist;
+    $dist{$deriver} = 0;
+
+    my @queue = ($deriver);
+    my $pos = 0;
+    
+    while ($pos < scalar @queue) {
+        my $p = $queue[$pos];
+        $pos++;
+
+        foreach my $q (@{$referers{$p}}) {
+            if (!defined $dist{$q}) {
+                $dist{$q} = $dist{$p} + 1;
+#                print "    $q $dist{$q}\n";
+                push @queue, $q;
+            }
+        }
+    }
+
+    my $wuse = 1.0;
+    foreach my $user (keys %dist) {
+        next if $user eq $deriver;
+#        print "    $user $dist{$user}\n";
+        $wuse += 1.0 / 2.0**$dist{$user};
+    }
+
+#    print "    XXX $path $wuse\n";
+    
+    return $wuse;
+}
+
+
+# For each output path in the destination, see if we need to / can
+# create a patch.
+
+print "creating patches...\n";
+
+foreach my $p (keys %dstOutPaths) {
+
+    # If exactly the same path already exists in the source, skip it.
+    next if defined $srcOutPaths{$p};
+    
+    print "  $p\n";
+
+    # If not, then we should find the paths in the source that are
+    # `most' likely to be present on a system that wants to install
+    # this path.
+
+    (my $name, my $version) = getNameVersion $p;
+
+    my @closest = ();
+    my $closestVersion;
+    my $minDist = -1; # actually, larger means closer
+
+    # Find all source paths with the same name.
+
+    foreach my $q (keys %srcOutPaths) {
+        (my $name2, my $version2) = getNameVersion $q;
+        if ($name eq $name2) {
+
+            # If the sizes differ too much, then skip.  This
+            # disambiguates between, e.g., a real component and a
+            # wrapper component (cf. Firefox in Nixpkgs).
+            my $srcSize = @{$srcNarFiles{$q}}[0]->{size};
+            my $dstSize = @{$dstNarFiles{$p}}[0]->{size};
+            my $ratio = $srcSize / $dstSize;
+            $ratio = 1 / $ratio if $ratio < 1;
+#            print "  SIZE $srcSize $dstSize $ratio $q\n";
+
+            if ($ratio >= 3) {
+                print "  SKIPPING $q due to size ratio $ratio ($srcSize $dstSize)\n";
+                next;
+            }
+
+            # If the numbers of weighted uses differ too much, then
+            # skip.  This disambiguates between, e.g., the bootstrap
+            # GCC and the final GCC in Nixpkgs.
+            my $srcUses = computeUses \%srcNarFiles, $q;
+            my $dstUses = computeUses \%dstNarFiles, $p;
+            $ratio = $srcUses / $dstUses;
+            $ratio = 1 / $ratio if $ratio < 1;
+            print "  USE $srcUses $dstUses $ratio $q\n";
+            
+#            if ($ratio >= 2) {
+#                print "  SKIPPING $q due to use ratio $ratio ($srcUses $dstUses)\n";
+#                next;
+#            }
+
+            # If there are multiple matching names, include the ones
+            # with the closest version numbers.
+            my $dist = versionDiff $version, $version2;
+            if ($dist > $minDist) {
+                $minDist = $dist;
+                @closest = ($q);
+                $closestVersion = $version2;
+            } elsif ($dist == $minDist) {
+                push @closest, $q;
+            }
+        }
+    }
+
+    if (scalar(@closest) == 0) {
+        print "  NO BASE: $p\n";
+        next;
+    }
+
+    foreach my $closest (@closest) {
+
+        # Generate a patch between $closest and $p.
+        print "  $p <- $closest\n";
+
+        # If the patch already exists, skip it.
+        if (containsPatch(\%srcPatches, $p, $closest) ||
+            containsPatch(\%dstPatches, $p, $closest))
+        {
+            print "    skipping, already exists\n";
+            next;
+        }
+
+#        next;
+        
+        my $srcNarBz2 = getNarBz2 \%srcNarFiles, $closest;
+        my $dstNarBz2 = getNarBz2 \%dstNarFiles, $p;
+        
+        system("@bunzip2@ < $srcNarBz2 > $tmpdir/A") == 0
+            or die "cannot unpack $srcNarBz2";
+
+        system("@bunzip2@ < $dstNarBz2 > $tmpdir/B") == 0
+            or die "cannot unpack $dstNarBz2";
+
+        system("@libexecdir@/bsdiff $tmpdir/A $tmpdir/B $tmpdir/DIFF") == 0
+            or die "cannot compute binary diff";
+
+        my $baseHash = `@bindir@/nix-hash --flat --type $hashAlgo --base32 $tmpdir/A` or die;
+        chomp $baseHash;
+
+        my $narHash = `@bindir@/nix-hash --flat --type $hashAlgo --base32 $tmpdir/B` or die;
+        chomp $narHash;
+
+        my $narDiffHash = `@bindir@/nix-hash --flat --type $hashAlgo --base32 $tmpdir/DIFF` or die;
+        chomp $narDiffHash;
+
+        my $narDiffSize = (stat "$tmpdir/DIFF")[7];
+        my $dstNarBz2Size = (stat $dstNarBz2)[7];
+
+        if ($narDiffSize >= $dstNarBz2Size) {
+            print "    rejecting; patch bigger than full archive\n";
+            next;
+        }
+    
+        my $finalName =
+            "$narDiffHash.nar-bsdiff";
+
+        print "    size $narDiffSize; full size $dstNarBz2Size\n";
+        
+        if (-e "$patchesDir/$finalName") {
+            print "    not copying, already exists\n";
+        }
+
+        else {
+
+            system("cp '$tmpdir/DIFF' '$patchesDir/$finalName.tmp'") == 0
+                or die "cannot copy diff";
+            
+            rename("$patchesDir/$finalName.tmp", "$patchesDir/$finalName")
+                or die "cannot rename $patchesDir/$finalName.tmp";
+            
+        }
+        
+        # Add the patch to the manifest.
+        addPatch \%dstPatches, $p,
+            { url => "$patchesURL/$finalName", hash => "$hashAlgo:$narDiffHash"
+            , size => $narDiffSize, basePath => $closest, baseHash => "$hashAlgo:$baseHash"
+            , narHash => "$hashAlgo:$narHash", patchType => "nar-bsdiff"
+            }, 0;
+    }
+}
+
+
+# Add in any potentially useful patches in the source (namely, those
+# patches that produce either paths in the destination or paths that
+# can be used as the base for other useful patches).
+
+my $changed;
+do {
+    # !!! we repeat this to reach the transitive closure; inefficient
+    $changed = 0;
+
+    foreach my $p (keys %srcPatches) {
+        my $patchList = $srcPatches{$p};
+
+        my $include = 0;
+
+        # Is path $p included in the destination?  If so, include
+        # patches that produce it.
+        $include = 1 if (defined $dstNarFiles{$p});
+
+        # Is path $p a path that serves as a base for paths in the
+        # destination?  If so, include patches that produce it.
+        foreach my $q (keys %dstPatches) {
+            foreach my $patch (@{$dstPatches{$q}}) {
+                # !!! check baseHash
+                $include = 1 if ($p eq $patch->{basePath});
+            }
+        }
+
+        if ($include) {
+            foreach my $patch (@{$patchList}) {
+                $changed = 1 if addPatch \%dstPatches, $p, $patch;
+            }
+        }            
+        
+    }
+    
+} while $changed;
+
+
+# Rewrite the manifest of the destination (with the new patches).
+writeManifest "$dstDir/MANIFEST",
+    \%dstNarFiles, \%dstPatches, \%dstSuccessors;

scripts/nix-build.in

@@ -0,0 +1,59 @@
+#! @shell@ -e
+
+nixExpr=$1
+
+if test -z "$nixExpr"; then
+    echo "syntax: $0 NIX-EXPR..." >&2
+    exit 1
+fi
+
+extraArgs=
+addDrvLink=0
+addOutLink=1
+
+
+trap 'rm -f ./.nix-build-tmp-*' EXIT
+
+
+# Process the arguments.
+for i in "$@"; do
+    case "$i" in
+    
+        --add-drv-link)
+            addDrvLink=1
+            ;;
+            
+        --no-link)
+            addOutLink=0
+            ;;
+            
+        -*)
+            extraArgs="$extraArgs $i"
+            ;;
+            
+        *)
+            # Instantiate the Nix expression.
+            prefix=
+            if test "$addDrvLink" = 0; then prefix=.nix-build-tmp-; fi
+            storeExprs=$(@bindir@/nix-instantiate \
+                --add-root ./${prefix}derivation --indirect \
+                "$i")
+                
+            for j in $storeExprs; do
+                echo "store expression is $(readlink "$j")" >&2
+            done
+
+            # Build the resulting store derivation.
+            prefix=
+            if test "$addOutLink" = 0; then prefix=.nix-build-tmp-; fi
+            outPaths=$(@bindir@/nix-store \
+                --add-root ./${prefix}result --indirect \
+                -rv $extraArgs $storeExprs)
+                
+            for j in $outPaths; do
+                echo "$(readlink "$j")"
+            done
+            
+            ;;
+    esac
+done

scripts/nix-channel.in

@@ -0,0 +1,174 @@
+#! @perl@ -w
+
+use strict;
+
+my $rootsDir = "@localstatedir@/nix/gcroots/channels";
+
+
+# Figure out the name of the `.nix-channels' file to use.
+my $home = $ENV{"HOME"};
+die '$HOME not set' unless defined $home;
+my $channelsList = "$home/.nix-channels";
+    
+
+my @channels;
+
+
+# Reads the list of channels from the file $channelsList;
+sub readChannels {
+    return if (!-f $channelsList);
+    open CHANNELS, "<$channelsList" or die "cannot open `$channelsList': $!";
+    while (<CHANNELS>) {
+        chomp;
+        push @channels, $_;
+    }
+    close CHANNELS;
+}
+
+
+# Writes the list of channels to the file $channelsList;
+sub writeChannels {
+    open CHANNELS, ">$channelsList" or die "cannot open `$channelsList': $!";
+    foreach my $url (@channels) {
+        print CHANNELS "$url\n";
+    }
+    close CHANNELS;
+}
+
+
+# Adds a channel to the file $channelsList;
+sub addChannel {
+    my $url = shift;
+    readChannels;
+    foreach my $url2 (@channels) {
+        return if $url eq $url2;
+    }
+    push @channels, $url;
+    writeChannels;
+}
+
+
+# Remove a channel from the file $channelsList;
+sub removeChannel {
+    my $url = shift;
+    my @left = ();
+    readChannels;
+    foreach my $url2 (@channels) {
+        push @left, $url2 if $url ne $url2;
+    }
+    @channels = @left;
+    writeChannels;
+}
+
+
+# Fetch Nix expressions and pull cache manifests from the subscribed
+# channels.
+sub update {
+    readChannels;
+
+    # Get rid of all the old substitutes.
+    system "@bindir@/nix-store --clear-substitutes";
+    die "cannot clear substitutes" if ($? != 0);
+
+    # Pull cache manifests.
+    foreach my $url (@channels) {
+        print "pulling cache manifest from `$url'\n";
+        system "@bindir@/nix-pull '$url'/MANIFEST";
+        die "cannot pull cache manifest from `$url'" if ($? != 0);
+    }
+
+    # Create a Nix expression that fetches and unpacks the channel Nix
+    # expressions.
+
+    my $nixExpr = "[";
+    foreach my $url (@channels) {
+        my $fullURL = "$url/nixexprs.tar.bz2";
+        $ENV{"PRINT_PATH"} = 1;
+        my ($hash, $path) = `@bindir@/nix-prefetch-url '$fullURL' 2> /dev/null`;
+        die "cannot fetch `$fullURL'" if $? != 0;
+        chomp $path;
+        $nixExpr .= $path . " ";
+    }
+    $nixExpr .= "]";
+
+    $nixExpr =
+        "(import @datadir@/nix/corepkgs/channels/unpack.nix) " .
+        "{inputs = $nixExpr; system = \"@system@\";}";
+
+    # Figure out a name for the GC root.
+    my $userName = getpwuid($<);
+    die "who ARE you? go away" unless defined $userName;
+
+    my $rootFile = "$rootsDir/$userName";
+    
+    # Instantiate the Nix expression.
+    my $storeExpr = `echo '$nixExpr' | @bindir@/nix-instantiate --add-root '$rootFile'.tmp -`
+        or die "cannot instantiate Nix expression";
+    chomp $storeExpr;
+
+    # Build the resulting derivation.
+    my $outPath = `nix-store --add-root '$rootFile' -r '$storeExpr'`
+        or die "cannot realise store expression";
+    chomp $outPath;
+
+    unlink "$rootFile.tmp";
+
+    # Make it the default Nix expression for `nix-env'.
+    system "@bindir@/nix-env --import '$outPath'";
+    die "cannot pull set default Nix expression to `$outPath'" if ($? != 0);
+}
+
+
+sub usageError {
+    print STDERR <<EOF;
+Usage:
+  nix-channel --add URL
+  nix-channel --remove URL
+  nix-channel --list
+  nix-channel --update
+EOF
+    exit 1;
+}
+
+
+usageError if scalar @ARGV == 0;
+
+
+while (scalar @ARGV) {
+    my $arg = shift @ARGV;
+
+    if ($arg eq "--add") {
+        usageError if scalar @ARGV != 1;
+        addChannel (shift @ARGV);
+        last;
+    }
+
+    if ($arg eq "--remove") {
+        usageError if scalar @ARGV != 1;
+        removeChannel (shift @ARGV);
+        last;
+    }
+
+    if ($arg eq "--list") {
+        usageError if scalar @ARGV != 0;
+        readChannels;
+        foreach my $url (@channels) {
+            print "$url\n";
+        }
+        last;
+    }
+
+    elsif ($arg eq "--update") {
+        usageError if scalar @ARGV != 0;
+        update;
+        last;
+    }
+    
+    elsif ($arg eq "--help") {
+        usageError;
+    }
+
+    else {
+        die "unknown argument `$arg'; try `--help'";
+    }
+}

scripts/nix-collect-garbage.in

@@ -1,39 +1,2 @@
-#! /usr/bin/perl -w
-
-my $linkdir = "@localstatedir@/nix/links";
-my $storedir = "@prefix@/store";
-
-my %alive;
-
-my $keepsuccessors = 0;
-my $invert = 0;
-
-foreach my $arg (@ARGV) {
-    if ($arg eq "--keep-successors") { $keepsuccessors = 1; }
-    elsif ($arg eq "--invert") { $invert = 1; }
-    else { die "unknown argument `$arg'" };
-}
-
-my $extraarg = "";
-if ($keepsuccessors) { $extraarg = "--include-successors"; };
-open HASHES, "nix --query --requisites $extraarg \$(cat $linkdir/*.id) |" or die "in `nix -qrh'";
-while (<HASHES>) {
-	chomp;
-	$alive{$_} = 1;
-	if ($invert) { print "$_\n"; };
-}
-close HASHES;
-
-exit 0 if ($invert);
-
-opendir(DIR, $storedir) or die "cannot opendir $storedir: $!";
-my @names = readdir(DIR);
-closedir DIR;
-
-foreach my $name (@names) {
-    next if ($name eq "." || $name eq "..");
-    $name = "$storedir/$name";
-    if (!$alive{$name}) {
-        print "$name\n";
-    }
-}
+#! @shell@ -e
+exec @bindir@/nix-store --gc "$@"

scripts/nix-install-package.in

@@ -0,0 +1,51 @@
+#! @perl@ -w
+
+use strict;
+use POSIX qw(tmpnam);
+
+my $pkgFile = $ARGV[0];
+die unless defined $pkgFile;
+
+
+# Re-execute in a terminal, if necessary, so that if we're executed
+# from a web browser, the user gets to see us.
+if (!defined $ENV{"NIX_HAVE_TERMINAL"}) {
+    $ENV{"NIX_HAVE_TERMINAL"} = "1";
+    $ENV{"LD_LIBRARY_PATH"} = "";
+    exec("xterm", "-e", "@shell@", "-c", "@bindir@/nix-install-package '$pkgFile' || read");
+    die "cannot execute `xterm'";
+}
+
+
+# Read and parse the package file.
+open PKGFILE, "<$pkgFile" or die "cannot open `$pkgFile': $!";
+my $contents = <PKGFILE>;
+close PKGFILE;
+
+$contents =~ /^\s*(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)/ or die "invalid package contents";
+my $version = $1;
+my $manifestURL = $2;
+my $drvName = $3;
+my $system = $4;
+my $drvPath = $5;
+my $outPath = $6;
+
+die "invalid package version `$version'" unless $version eq "NIXPKG1";
+
+
+# Ask confirmation.
+print "Do you want to install `$drvName' (Y/N)? ";
+my $reply = <STDIN>;
+chomp $reply;
+exit if $reply ne "y" && $reply ne "Y";
+
+print "\nPulling manifests...\n";
+system "@bindir@/nix-pull '$manifestURL'";
+die if $? != 0;
+
+print "\nInstalling package...\n";
+system "@bindir@/nix-env -i '$outPath'";
+die if $? != 0;
+
+print "\nInstallation succeeded! Press Enter to continue.\n";
+<STDIN>;

scripts/nix-prefetch-url.in

@@ -1,48 +1,69 @@
-#! /usr/bin/perl -w
+#! @shell@ -e
 
-use strict;
-use IPC::Open2;
+url=$1
+expHash=$2
 
-my $url = shift @ARGV;
-defined $url or die;
+hashType=$NIX_HASH_ALGO
+if test -z "$hashType"; then
+    hashType=md5
+fi
 
-print "fetching $url...\n";
+hashFormat=
+if test "$hashType" != "md5"; then
+    hashFormat=--base32
+fi
 
-my $out = "@prefix@/store/nix-prefetch-url-$$";
+if test -z "$url"; then
+    echo "syntax: nix-prefetch-url URL [EXPECTED-HASH]" >&2
+    exit 1
+fi
 
-system "@wget@ '$url' -O '$out'";
-$? == 0 or die "unable to fetch $url";
+name=$(basename "$url")
+if test -z "$name"; then echo "invalid url"; exit 1; fi
 
-my $hash=`@bindir@/nix-hash --flat $out`;
-$? == 0 or die "unable to hash $out";
-chomp $hash;
 
-print "file has hash $hash\n";
+# If the hash was given, a file with that hash may already be in the
+# store.
+if test -n "$expHash"; then
+    finalPath=$(@bindir@/nix-store --print-fixed-path "$hashType" "$expHash" "$name")
+    if ! @bindir@/nix-store --check-validity "$finalPath" 2> /dev/null; then
+        finalPath=
+    fi
+    hash=$expHash
+fi
 
-my $out2 = "@prefix@/store/nix-prefetch-url-$hash";
-rename $out, $out2;
 
-# Create a Fix expression.
-my $fixexpr = 
-    "App(IncludeFix(\"fetchurl/fetchurl.fix\"), " .
-    "[(\"url\", \"$url\"), (\"md5\", \"$hash\")])";
+# If we don't know the hash or a file with that hash doesn't exist,
+# download the file and add it to the store.
+if test -z "$finalPath"; then
 
-# Instantiate a Nix expression.
-print STDERR "running fix...\n";
-my $pid = open2(\*READ, \*WRITE, "fix -") or die "cannot run fix";
+    tmpPath=/tmp/nix-prefetch-url-$$ # !!! security?
+    tmpFile=$tmpPath/$name
+    mkdir $tmpPath
 
-print WRITE $fixexpr;
-close WRITE;
+    # Perform the download.
+    @curl@ --fail --location --max-redirs 20 "$url" > $tmpFile
 
-my $id = <READ>;
-chomp $id;
+    # Compute the hash.
+    hash=$(@bindir@/nix-hash --type "$hashType" $hashFormat --flat $tmpFile)
+    if ! test -n "$QUIET"; then echo "hash is $hash" >&2; fi
 
-waitpid $pid, 0;
-$? == 0 or die "fix failed";
+    # Add the downloaded file to the Nix store.
+    finalPath=$(@bindir@/nix-store --add-fixed "$hashType" $tmpFile)
 
-# Run Nix.
-print STDERR "running nix...\n";
-system "nix --install $id > /dev/null";
-$? == 0 or die "`nix --install' failed";
+    if test -n "$tmpPath"; then rm -rf $tmpPath || true; fi
 
-unlink $out2;
+    if test -n "$expHash" -a "$expHash" != "$hash"; then
+        echo "hash mismatch for URL \`$url'"
+        exit 1
+    fi
+fi
+
+
+if ! test -n "$QUIET"; then echo "path is $finalPath" >&2; fi
+
+echo $hash
+
+if test -n "$PRINT_PATH"; then
+    echo $finalPath
+fi

scripts/nix-profile.sh.in

@@ -1,20 +1,11 @@
-#if test -z "$NIX_SET"; then
+if test -n "$HOME"; then
+    NIX_LINK="$HOME/.nix-profile"
 
-#    export NIX_SET=1
+    if ! test -L "$NIX_LINK"; then
+        echo "creating $NIX_LINK"
+        _NIX_DEF_LINK=@localstatedir@/nix/profiles/default
+        ln -s "$_NIX_DEF_LINK" "$NIX_LINK"
+    fi
 
-    NIX_LINKS=@localstatedir@/nix/links/current
-
-    export PATH=$NIX_LINKS/bin:@prefix@/bin:$PATH
-
-#    export LD_LIBRARY_PATH=$NIX_LINKS/lib:$LD_LIBRARY_PATH
-
-    export LIBRARY_PATH=$NIX_LINKS/lib:$LIBRARY_PATH
-
-    export C_INCLUDE_PATH=$NIX_LINKS/include:$C_INCLUDE_PATH
-    export CPLUS_INCLUDE_PATH=$NIX_LINKS/include:$CPLUS_INCLUDE_PATH
-
-    export PKG_CONFIG_PATH=$NIX_LINKS/lib/pkgconfig:$PKG_CONFIG_PATH
-
-#    export MANPATH=$NIX_LINKS/man:$MANPATH
-
-#fi
+    export PATH=$NIX_LINK/bin:@prefix@/bin:$PATH
+fi

scripts/nix-pull.in

@@ -1,115 +1,101 @@
-#! /usr/bin/perl -w
+#! @perl@ -w -I@libexecdir@/nix
 
 use strict;
 use IPC::Open2;
+use POSIX qw(tmpnam);
+use readmanifest;
 
-my $tmpfile = "@localstatedir@/nix/pull.tmp";
-my $conffile = "@sysconfdir@/nix/prebuilts.conf";
+my $tmpdir;
+do { $tmpdir = tmpnam(); }
+until mkdir $tmpdir, 0777;
 
-my @ids;
-my @subs;
-my @sucs;
+my $manifest = "$tmpdir/manifest";
 
-my $fullexpr = "[";
-my $first = 1;
+END { unlink $manifest; rmdir $tmpdir; }
 
-open CONFFILE, "<$conffile";
+my $binDir = $ENV{"NIX_BIN_DIR"};
+$binDir = "@bindir@" unless defined $binDir;
 
-while (<CONFFILE>) {
+my $libexecDir = $ENV{"NIX_LIBEXEC_DIR"};
+$libexecDir = "@libexecdir@" unless defined $libexecDir;
 
-    chomp;
-    if (/^\s*(\S+)\s*(\#.*)?$/) {
-        my $url = $1;
+my $stateDir = $ENV{"NIX_STATE_DIR"};
+$stateDir = "@localstatedir@/nix" unless defined $stateDir;
 
-        print "obtaining list of Nix archives at $url...\n";
 
-        system "wget '$url' -O '$tmpfile' 2> /dev/null"; # !!! escape
-        if ($?) { die "`wget' failed"; }
-        
-        open INDEX, "<$tmpfile";
+# Prevent access problems in shared-stored installations.
+umask 0022;
 
-        while (<INDEX>) {
-            # Get all links to prebuilts, that is, file names of the
-            # form foo-HASH-HASH.tar.bz2.
-            next unless (/HREF=\"([^\"]*)\"/);
-            my $fn = $1;
-            next if $fn =~ /\.\./;
-            next if $fn =~ /\//;
-            next unless $fn =~ /^([0-9a-z]{32})-([0-9a-z]{32})(.*)\.nar\.bz2$/;
-            my $hash = $1;
-            my $id = $2;
-            my $outname = $3;
-            my $fsid;
-            if ($outname =~ /^-/) {
-                next unless $outname =~ /^-((s-([0-9a-z]{32}))?.*)$/;
-                $outname = $1;
-                $fsid = $3;
-            } else {
-                $outname = "unnamed";
-            }
 
-            print STDERR "$id ($outname)\n";
+# Obtain URLs either from the command line or from a configuration file.
+my %narFiles;
+my %patches;
+my %successors;
 
-            # Construct a Fix expression that fetches and unpacks a
-            # Nix archive from the network.
-            my $fetch =
-              "App(IncludeFix(\"fetchurl/fetchurl.fix\"), " .
-              "[(\"url\", \"$url/$fn\"), (\"md5\", \"$hash\")])";
-            my $fixexpr = 
-                "App(IncludeFix(\"nar/unnar.fix\"), " .
-                "[ (\"nar\", $fetch)" .
-                ", (\"name\", \"$outname\")" .
-                ", (\"id\", \"$id\")" .
-                "])";
-            
-	    if (!$first) { $fullexpr .= "," };
-	    $first = 0;
-	    $fullexpr .= $fixexpr; # !!! O(n^2)?
+sub processURL {
+    my $url = shift;
 
-	    push @ids, $id;
+    $url =~ s/\/$//;
+    print "obtaining list of Nix archives at $url...\n";
 
-            # Does the name encode a successor relation?
-            if (defined $fsid) {
-                push @sucs, $fsid;
-                push @sucs, $id;
-            }
-        }
+    system("@curl@ --fail --silent --show-error --location --max-redirs 20 " .
+           "'$url' > '$manifest'") == 0
+           or die "curl failed: $?";
 
-        close INDEX;
-
-        unlink $tmpfile;
+    if (readManifest($manifest, \%narFiles, \%patches, \%successors) < 3) {
+        die "manifest `$url' is too old (i.e., for Nix <= 0.7)\n";
     }
 
+    my $baseName = "unnamed";
+    if ($url =~ /\/([^\/]+)\/[^\/]+$/) { # get the forelast component
+        $baseName = $1;
+    }
+
+    my $hash = `$binDir/nix-hash --flat '$manifest'`
+        or die "cannot hash `$manifest'";
+    chomp $hash;
+    
+    my $finalPath = "$stateDir/manifests/$baseName-$hash.nixmanifest";
+    
+    system("mv -f '$manifest' '$finalPath'") == 0
+        or die "cannot move `$manifest' to `$finalPath";
 }
 
-$fullexpr .= "]";
-
-# Instantiate Nix expressions from the Fix expressions we created above.
-print STDERR "running fix...\n";
-my $pid = open2(\*READ, \*WRITE, "fix -") or die "cannot run fix";
-
-print WRITE $fullexpr;
-close WRITE;
-my $i = 0;
-while (<READ>) {
-    chomp;
-    die unless /^([0-9a-z]{32})$/;
-    my $nid = $1;
-    die unless ($i < scalar @ids);
-    my $id = $ids[$i++];
-    push @subs, $id;
-    push @subs, $nid;
+while (@ARGV) {
+    my $url = shift @ARGV;
+    processURL $url;
 }
 
-waitpid $pid, 0;
-$? == 0 or die "fix failed";
+
+my $size = scalar (keys %narFiles);
+print "$size store paths in manifest\n";
+
 
 # Register all substitutes.
 print STDERR "registering substitutes...\n";
-system "nix --substitute @subs";
-if ($?) { die "`nix --substitute' failed"; }
 
-# Register all successors.
-print STDERR "registering successors...\n";
-system "nix --successor @sucs";
-if ($?) { die "`nix --successor' failed"; }
+my $pid = open2(\*READ, \*WRITE, "$binDir/nix-store --register-substitutes")
+    or die "cannot run nix-store";
+
+close READ;
+
+foreach my $storePath (keys %narFiles) {
+    my $narFileList = $narFiles{$storePath};
+    foreach my $narFile (@{$narFileList}) {
+        print WRITE "$storePath\n";
+        print WRITE "$narFile->{deriver}\n";
+        print WRITE "$libexecDir/nix/download-using-manifests.pl\n";
+        print WRITE "0\n";
+        my @references = split " ", $narFile->{references};
+        my $count = scalar @references;
+        print WRITE "$count\n";
+        foreach my $reference (@references) {
+            print WRITE "$reference\n";
+        }
+    }
+}
+
+close WRITE;
+
+waitpid $pid, 0;
+$? == 0 or die "nix-store failed";

scripts/nix-push.in

@@ -1,96 +1,259 @@
-#! /usr/bin/perl -w
+#! @perl@ -w -I@libexecdir@/nix
 
-my $fixfile = "/tmp/nix-push-tmp.fix";
-open FIX, ">$fixfile";
-print FIX "[";
-my $first = 1;
+use strict;
+use IPC::Open2;
+use POSIX qw(tmpnam);
+use readmanifest;
 
-foreach my $id (@ARGV) {
+my $hashAlgo = "sha256";
 
-    die unless $id =~ /^([0-9a-z]{32})$/;
+my $tmpdir;
+do { $tmpdir = tmpnam(); }
+until mkdir $tmpdir, 0777;
+
+my $nixfile = "$tmpdir/create-nars.nix";
+my $manifest = "$tmpdir/MANIFEST";
+
+END { unlink $manifest; unlink $nixfile; rmdir $tmpdir; }
+
+my $curl = "@curl@ --fail --silent";
+my $extraCurlFlags = ${ENV{'CURL_FLAGS'}};
+$curl = "$curl $extraCurlFlags" if defined $extraCurlFlags;
+
+my $binDir = $ENV{"NIX_BIN_DIR"};
+$binDir = "@bindir@" unless defined $binDir;
+
+my $dataDir = $ENV{"NIX_DATA_DIR"};
+$dataDir = "@datadir@" unless defined $dataDir;
+
+
+# Parse the command line.
+my $localCopy;
+my $localArchivesDir;
+my $localManifestFile;
+
+my $archivesPutURL;
+my $archivesGetURL;
+my $manifestPutURL;
+
+if ($ARGV[0] eq "--copy") {
+    die "syntax: nix-push --copy ARCHIVES_DIR MANIFEST_FILE PATHS...\n" if scalar @ARGV < 3;
+    $localCopy = 1;
+    shift @ARGV;
+    $localArchivesDir = shift @ARGV;
+    $localManifestFile = shift @ARGV;
+}
+else {
+    die "syntax: nix-push ARCHIVES_PUT_URL ARCHIVES_GET_URL " .
+        "MANIFEST_PUT_URL PATHS...\n" if scalar @ARGV < 3;
+    $localCopy = 0;
+    $archivesPutURL = shift @ARGV;
+    $archivesGetURL = shift @ARGV;
+    $manifestPutURL = shift @ARGV;
+}
+
+
+# From the given store paths, determine the set of requisite store
+# paths, i.e, the paths required to realise them.
+my %storePaths;
+
+foreach my $path (@ARGV) {
+    die unless $path =~ /^\//;
 
     # Get all paths referenced by the normalisation of the given 
-    # fstate expression.
-    system "nix --install $id";
-    if ($?) { die "`nix --install' failed"; }
-
-    my @paths;
-
-    open PATHS, "nix --query --requisites --include-successors $id 2> /dev/null |" or die "nix -qr";
-    while (<PATHS>) {
+    # Nix expression.
+    my $pid = open2(\*READ, \*WRITE,
+        "$binDir/nix-store --query --requisites --force-realise " .
+        "--include-outputs '$path'") or die;
+    close WRITE;
+    
+    while (<READ>) {
         chomp;
         die "bad: $_" unless /^\//;
-        push @paths, $_;
-    }
-    close PATHS;
-
-    # Also add all normal forms that are contained in these paths.
-#    open PATHS, "nix --query --generators --path @paths |" or die "nix -qg";
-#    while (<PATHS>) {
-#	chomp;
-#        die "bad: $_" unless /^\//;
-#	push @paths, $_;
-#    }
-#    close PATHS;
-
-    # For each path, create a Fix expression that turns the path into
-    # a Nix archive.
-    foreach my $path (@paths) {
-
-	next unless ($path =~ /\/([0-9a-z]{32})[^\/]*/);
-	print "$path\n";
-	my $pathid = $1;
-
-        # Construct a name for the Nix archive.  If the file is an
-        # fstate successor, encode this into the name.
-        my $name = $pathid;
-        if ($path =~ /-s-([0-9a-z]{32}).nix$/) {
-            $name = "$name-s-$1";
-        }
-        $name = $name . ".nar.bz2";
-
-        # Construct a Fix expression that creates a Nix archive.
-        my $fixexpr = 
-          "App(IncludeFix(\"nar/nar.fix\"), " .
-          "[ (\"path\", Slice([\"$pathid\"], [(\"$path\", \"$pathid\", [])]))" .
-          "])";
-	
-	print FIX "," unless ($first);
-	$first = 0;
-        print FIX $fixexpr;
-
+        $storePaths{$_} = "";
     }
+    close READ;
+    
+    waitpid $pid, 0;
+    $? == 0 or die "nix-store failed";
 }
 
-print FIX "]";
-close FIX;
+my @storePaths = keys %storePaths;
 
-# Instantiate a Nix expression from the Fix expression.
-my @nids;
-print STDERR "running fix...\n";
-open NIDS, "fix $fixfile |" or die "cannot run fix";
-while (<NIDS>) {
+
+# For each path, create a Nix expression that turns the path into
+# a Nix archive.
+open NIX, ">$nixfile";
+print NIX "[";
+
+foreach my $storePath (@storePaths) {
+    die unless ($storePath =~ /\/[0-9a-z]{32}.*$/);
+
+    # Construct a Nix expression that creates a Nix archive.
+    my $nixexpr = 
+        "((import $dataDir/nix/corepkgs/nar/nar.nix) " .
+        "{path = \"$storePath\"; system = \"@system@\"; hashAlgo = \"$hashAlgo\";}) ";
+    
+    print NIX $nixexpr;
+}
+
+print NIX "]";
+close NIX;
+
+
+# Instantiate store expressions from the Nix expression.
+my @storeExprs;
+print STDERR "instantiating store expressions...\n";
+my $pid = open2(\*READ, \*WRITE, "$binDir/nix-instantiate $nixfile")
+    or die "cannot run nix-instantiate";
+close WRITE;
+while (<READ>) {
     chomp;
-    die unless /^([0-9a-z]{32})$/;
-    push @nids, $1;
+    die unless /^\//;
+    push @storeExprs, $_;
 }
+close READ;
+
+waitpid $pid, 0;
+$? == 0 or die "nix-instantiate failed";
 
 
-# Realise the Nix expression.
-my @pushlist;
+# Realise the store expressions.
 print STDERR "creating archives...\n";
-system "nix --install @nids > /dev/null";
-if ($?) { die "`nix --install' failed"; }
 
-open NIDS, "nix --query --list @nids |" or die "cannot run nix";
-while (<NIDS>) {
-    chomp;
-    die unless (/^\//);
-    print "$_\n";
-    push @pushlist, "$_/*";
+my @narPaths;
+
+my @tmp = @storeExprs;
+while (scalar @tmp > 0) {
+    my $n = scalar @tmp;
+    if ($n > 256) { $n = 256 };
+    my @tmp2 = @tmp[0..$n - 1];
+    @tmp = @tmp[$n..scalar @tmp - 1];
+
+    my $pid = open2(\*READ, \*WRITE, "$binDir/nix-store --realise @tmp2")
+        or die "cannot run nix-store";
+    close WRITE;
+    while (<READ>) {
+        chomp;
+        die unless (/^\//);
+        push @narPaths, "$_";
+    }
+    close READ;
+
+    waitpid $pid, 0;
+    $? == 0 or die "nix-store failed";
 }
 
-# Push the prebuilts to the server. !!! FIXME
-if (scalar @pushlist > 0) {
-    system "rsync -av -e ssh @pushlist eelco\@losser.st-lab.cs.uu.nl:/home/eelco/public_html/nix-dist/";
+
+# Create the manifest.
+print STDERR "creating manifest...\n";
+
+my %narFiles;
+my %patches;
+
+my @narArchives;
+for (my $n = 0; $n < scalar @storePaths; $n++) {
+    my $storePath = $storePaths[$n];
+    my $narDir = $narPaths[$n];
+    
+    $storePath =~ /\/([^\/]*)$/;
+    my $basename = $1;
+    defined $basename or die;
+
+    open HASH, "$narDir/narbz2-hash" or die "cannot open narbz2-hash";
+    my $narbz2Hash = <HASH>;
+    chomp $narbz2Hash;
+    $narbz2Hash =~ /^[0-9a-z]+$/ or die "invalid hash";
+    close HASH;
+
+    open HASH, "$narDir/nar-hash" or die "cannot open nar-hash";
+    my $narHash = <HASH>;
+    chomp $narHash;
+    $narHash =~ /^[0-9a-z]+$/ or die "invalid hash";
+    close HASH;
+    
+    my $narName = "$narbz2Hash.nar.bz2";
+
+    my $narFile = "$narDir/$narName";
+    (-f $narFile) or die "narfile for $storePath not found";
+    push @narArchives, $narFile;
+
+    my $narbz2Size = (stat $narFile)[7];
+
+    my $references = `$binDir/nix-store --query --references '$storePath'`;
+    die "cannot query references for `$storePath'" if $? != 0;
+    $references = join(" ", split(" ", $references));
+
+    my $deriver = `$binDir/nix-store --query --deriver '$storePath'`;
+    die "cannot query deriver for `$storePath'" if $? != 0;
+    chomp $deriver;
+    $deriver = "" if $deriver eq "unknown-deriver";
+
+    my $url;
+    if ($localCopy) {
+        $url = "file://$localArchivesDir/$narName";
+    } else {
+        $url = "$archivesGetURL/$narName";
+    }
+    $narFiles{$storePath} = [
+        { url => $url
+        , hash => "$hashAlgo:$narbz2Hash"
+        , size => $narbz2Size
+        , narHash => "$hashAlgo:$narHash"
+        , references => $references
+        , deriver => $deriver
+        }
+    ];
+}
+
+writeManifest $manifest, \%narFiles, \%patches;
+
+
+sub copyFile {
+    my $src = shift;
+    my $dst = shift;
+    system("cp '$src' '$dst.tmp'") == 0 or die "cannot copy file";
+    rename("$dst.tmp", "$dst") or die "cannot rename file";
+}
+
+
+# Upload the archives.
+print STDERR "uploading archives...\n";
+
+sub archiveExists {
+    my $name = shift;
+    print STDERR "  HEAD on $archivesGetURL/$name\n";
+    return system("$curl --head $archivesGetURL/$name > /dev/null") == 0;
+}
+
+foreach my $narArchive (@narArchives) {
+
+    $narArchive =~ /\/([^\/]*)$/;
+    my $basename = $1;
+
+    if ($localCopy) {
+        if (! -f "$localArchivesDir/$basename") {
+            print STDERR "  $narArchive\n";
+            copyFile $narArchive, "$localArchivesDir/$basename";
+        }
+    }
+    else {
+        if (!archiveExists("$basename")) {
+            print STDERR "  $narArchive\n";
+            system("$curl --show-error --upload-file " .
+                   "'$narArchive' '$archivesPutURL/$basename' > /dev/null") == 0 or
+                   die "curl failed on $narArchive: $?";
+        }
+    }
+}
+
+
+# Upload the manifest.
+print STDERR "uploading manifest...\n";
+if ($localCopy) {
+    copyFile $manifest, $localManifestFile;
+} else {
+    system("$curl  --show-error --upload-file " .
+           "'$manifest' '$manifestPutURL' > /dev/null") == 0 or
+           die "curl failed on $manifest: $?";
 }

scripts/nix-switch.in

@@ -1,86 +0,0 @@
-#! /usr/bin/perl -w
-
-use strict;
-
-my $keep = 0;
-my $sourceroot = 0;
-my $name = "current";
-my $srcid;
-
-my $argnr = 0;
-while ($argnr < scalar @ARGV) {
-    my $arg = $ARGV[$argnr++];
-    if ($arg eq "--keep") { $keep = 1; }
-    elsif ($arg eq "--source-root") { $sourceroot = 1; }
-    elsif ($arg eq "--name") { $name = $ARGV[$argnr++]; }
-    elsif ($arg =~ /^([0-9a-z]{32})$/) { $srcid = $arg; }
-    else { die "unknown argument `$arg'" };
-}
-
-my $linkdir = "@localstatedir@/nix/links";
-
-# Build the specified package, and all its dependencies.
-my $nfid = `nix --install $srcid`;
-if ($?) { die "`nix --install' failed"; }
-chomp $nfid;
-die unless $nfid =~ /^([0-9a-z]{32})$/;
-
-my $pkgdir = `nix --query --list $nfid`;
-if ($?) { die "`nix --query --list' failed"; }
-chomp $pkgdir;
-
-# Figure out a generation number.
-opendir(DIR, $linkdir);
-my $nr = 0;
-foreach my $n (sort(readdir(DIR))) {
-    next if (!($n =~ /^\d+$/));
-    $nr = $n + 1 if ($n >= $nr);
-}
-closedir(DIR);
-
-my $link = "$linkdir/$nr";
-
-# Create a symlink from $link to $pkgdir.
-symlink($pkgdir, $link) or die "cannot create $link: $!";
-
-# Store the id of the normal form.  This is useful for garbage
-# collection and the like.
-my $idfile = "$linkdir/$nr.id";
-open ID, "> $idfile" or die "cannot create $idfile";
-print ID "$nfid\n";
-close ID;
-
-# Optionally store the source id.
-if ($sourceroot) {
-    $idfile = "$linkdir/$nr-src.id";
-    open ID, "> $idfile" or die "cannot create $idfile";
-    print ID "$srcid\n";
-    close ID;
-}
-
-my $current = "$linkdir/$name";
-
-# Read the current generation so that we can delete it (if --keep
-# wasn't specified).
-my $oldlink = readlink($current);
-
-# Make $link the current generation by pointing $linkdir/current to
-# it.  The rename() system call is supposed to be essentially atomic
-# on Unix.  That is, if we have links `current -> X' and `new_current
-# -> Y', and we rename new_current to current, a process accessing
-# current will see X or Y, but never a file-not-found or other error
-# condition.  This is sufficient to atomically switch the current link
-# tree.
-
-print "switching $current to $link\n";
-
-my $tmplink = "$linkdir/.new_$name";
-symlink($link, $tmplink) or die "cannot create $tmplink";
-rename($tmplink, $current) or die "cannot rename $tmplink";
-
-if (!$keep && defined $oldlink) {
-    print "deleting old $oldlink\n";
-    unlink($oldlink) == 1 or print "cannot delete $oldlink\n";
-    unlink("$oldlink.id") == 1 or print "cannot delete $oldlink.id\n";
-    unlink("$oldlink-src.id");
-}

scripts/optimise-store.pl

@@ -0,0 +1,69 @@
+#! /usr/bin/perl -w
+
+use strict;
+
+{ my $ofh = select STDOUT;
+  $| = 1;
+  select $ofh;
+}
+
+#my @paths = ("/nix/store/caef3a49150506d233f474322a824e50-glibc-2.3.3", "/nix/store/a8a9d585d1ad4b1bc911be7743b3b996-glibc-2.3.3");
+my @paths = ("/nix/store");
+
+my $tmpfile = "/tmp/nix-optimise-hash-list";
+#my $tmpfile = "/data/nix-optimise-hash-list";
+
+system("find @paths -type f -print0 | xargs -0 md5sum -- > $tmpfile") == 0
+    or die "cannot hash store files";
+
+system("sort $tmpfile > $tmpfile.sorted") == 0
+    or die "cannot sort list";
+
+open LIST, "<$tmpfile.sorted" or die;
+
+my $prevFile;
+my $prevHash;
+
+my $totalSpace = 0;
+my $savedSpace = 0;
+
+my $files = 0;
+
+while (<LIST>) {
+#    print "D";
+    /^([0-9a-f]*)\s+(.*)$/ or die;
+    my $curFile = $2;
+    my $curHash = $1;
+
+#    print "A";
+    my $fileSize = (stat $curFile)[7];
+#    print "B";
+#    my $fileSize = 1;
+    $totalSpace += $fileSize;
+
+    if (defined $prevHash && $curHash eq $prevHash) {
+        
+#        print "$curFile = $prevFile\n";
+
+        $savedSpace += $fileSize;
+        
+    } else {
+        $prevFile = $curFile;
+        $prevHash = $curHash;
+    }
+
+    print "." if ($files++ % 100 == 0);
+    #print ".";
+
+#    print "C";
+}
+
+print "\n";
+
+print "total space = $totalSpace\n";
+print "saved space = $savedSpace\n";
+my $savings = ($savedSpace / $totalSpace) * 100.0;
+print "savings = $savings %\n";
+
+
+close LIST;