diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index 8bf06cf2b..94077acc0 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -6,8 +6,12 @@ XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs \
--param section.label.includes.component.label 1 \
--param html.stylesheet \'style.css\'
+man1_MANS = nix-env.1 nix-store.1 nix-instantiate.1 \
+ nix-collect-garbage.1 nix-push.1 nix-pull.1 \
+ nix-prefetch-url.1
+
SOURCES = manual.xml introduction.xml installation.xml overview.xml \
- nix-env.xml nix-store.xml nix-instantiate.xml \
+ $(man1_MANS:.1=.xml) \
troubleshooting.xml bugs.xml opt-common.xml opt-common-syn.xml \
quick-start.xml style.css images
@@ -18,8 +22,6 @@ manual.is-valid: $(SOURCES) version.xml
version.xml:
echo -n $(VERSION) > version.xml
-man1_MANS = nix-env.1 nix-store.1 nix-instantiate.1
-
man $(MANS): $(SOURCES) manual.is-valid
$(XSLTPROC) $(docbookxsl)/manpages/docbook.xsl manual.xml
diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml
index 77579776b..eb479945a 100644
--- a/doc/manual/bugs.xml
+++ b/doc/manual/bugs.xml
@@ -9,6 +9,16 @@
+
+
+ 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.
+
+
+
Unify the concepts of successors and substitutes into a
@@ -43,12 +53,63 @@
+
+
+ The current garbage collector is a hack. It should be
+ integrated into nix-store. It should
+ delete derivations in an order determined by topologically
+ sorting derivations under the points-to relation. This
+ ensures that no store paths ever exist that point to
+ non-existant store paths.
+
+
+
+
+
+ There are race conditions between the garbage collector and
+ other Nix tools. For instance, when we run
+ nix-env to build and install a derivation
+ and run the garbage collector at the same time, the garbage
+ collector may kick in exactly between the build and
+ installation steps, i.e., before the newly built derivation
+ has become reachable from a root of the garbage collector.
+
+
+
+ One solution would be for these programs to properly register
+ temporary roots for the collector. Another would be to use
+ stop-the-world garbage collection: if any tool is running, the
+ garbage collector blocks, and vice versa. These solutions do
+ not solve the situation where multiple tools are involved,
+ e.g.,
+
+
+$ nix-store -r $(nix-instantiate foo.nix)
+
+ since even if nix-instantiate where to
+ register a temporary root, it would be released by the time
+ nix-store is started. A solution would be
+ to write the intermediate value to a file that is used as a
+ root to the collector, e.g.,
+
+
+$ nix-instantiate foo.nix > /nix/var/nix/roots/bla
+$ nix-store -r $(cat /nix/var/nix/roots/bla)
+
+
+
+
+
+
+ For security, nix-push manifests should be
+ digitally signed, and nix-pull 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
+ fetchurl.nix checks them).
+
+
+
-
-
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index 686ab612f..8188a1ff9 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -12,6 +12,10 @@
+
+
+
+
@@ -52,6 +56,22 @@
nix-instantiate
&nix-instantiate;
+
+ nix-collect-garbage
+ &nix-collect-garbage;
+
+
+ nix-push
+ &nix-push;
+
+
+ nix-pull
+ &nix-pull;
+
+
+ nix-prefetch-url
+ &nix-prefetch-url;
+
&troubleshooting;
diff --git a/doc/manual/nix-collect-garbage.xml b/doc/manual/nix-collect-garbage.xml
new file mode 100644
index 000000000..8ff741e22
--- /dev/null
+++ b/doc/manual/nix-collect-garbage.xml
@@ -0,0 +1,75 @@
+
+
+ nix-collect-garbage
+ determine the set of unreachable store paths
+
+
+
+
+ nix-collect-garbage
+
+
+
+
+
+
+ Description
+
+
+ The command nix-collect-garbage determines
+ the paths in the Nix store that are garbage, that is, not
+ reachable from outside of the store. These paths can be safely
+ deleted without affecting the integrity of the system.
+
+
+
+
+
+ Options
+
+
+
+
+
+
+
+ Causes the set of reachable paths to
+ be printed, rather than the unreachable paths. These are
+ the paths that may not be deleted.
+
+
+
+
+
+
+
+
+ Causes nix-collect-garbage not to
+ follow successor relations. By default, if a derivation
+ store expression is reachable, its successor (i.e., a
+ closure store expression) is also considered to be
+ reachable. This option is always safe, but garbage
+ collecting successors may cause undesirable rebuilds later
+ on.
+
+
+
+
+
+
+
+
+
+ Examples
+
+
+ To delete all unreachable paths, do the following:
+
+
+$ nix-collect-garbage | xargs nix-store --delete
+
+
+
+
+
+
diff --git a/doc/manual/nix-env.xml b/doc/manual/nix-env.xml
index 874f27081..70069fa1a 100644
--- a/doc/manual/nix-env.xml
+++ b/doc/manual/nix-env.xml
@@ -111,8 +111,9 @@
For the ,
- and
- operations, this flag will
+ , ,
+ and
+ operations, this flag will
cause nix-env to print what
would be done if this flag had not
been specified, without actually doing it.
@@ -594,4 +595,225 @@ foo-1.2.3
+
+
+
+
+ Operation <option>--switch-profile</option>
+
+
+ Synopsis
+
+ nix-env
+
+
+
+
+ path
+
+
+
+
+ Description
+
+
+ This operation makes path the
+ current profile for the user. That is, the symlink
+ ~/.nix-profile is made to point to
+ path.
+
+
+
+
+
+ Examples
+
+
+$ nix-env -S ~/my-profile
+
+
+
+
+
+
+
+
+
+
+ Operation <option>--list-generations</option>
+
+
+ Synopsis
+
+ nix-env
+
+
+
+
+
+ Description
+
+
+ This operation print a list of all the currently existing
+ generations for the active profile. These may be switched to
+ using the operation. It
+ also prints the creation date of the generation, and indicates
+ the current generation.
+
+
+
+
+
+ Examples
+
+
+$ 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)
+
+
+
+
+
+
+
+
+
+
+ Operation <option>--switch-generation</option>
+
+
+ Synopsis
+
+ nix-env
+
+
+
+
+ generation
+
+
+
+
+ Description
+
+
+ This operation makes generation number
+ generation the current generation
+ of the active profile. That is, if the
+ profile is the
+ path to the active profile, then the symlink
+ profile is
+ made to point to
+ profile-generation-link,
+ which is in turn a symlink to the actual user environment in
+ the Nix store.
+
+
+
+ Switching will fail if the specified generation does not
+ exist.
+
+
+
+
+
+ Examples
+
+
+$ nix-env -G 42
+switching from generation 50 to 42
+
+
+
+
+
+
+
+
+
+
+ Operation <option>--rollback</option>
+
+
+ Synopsis
+
+ nix-env
+
+
+
+
+
+ Description
+
+
+ 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
+ and
+ .
+
+
+
+
+
+ Examples
+
+
+$ nix-env --rollback
+switching from generation 92 to 91
+
+$ nix-env --rolback
+error: no generation older than the current (91) exists
+
+
+
+
+
+
+
+
+
+
+ Operation <option>--import</option>
+
+
+ Synopsis
+
+ nix-env
+
+
+
+
+ path
+
+
+
+
+ Description
+
+
+ This operation makes path the
+ default active Nix expression for the user. That is, the
+ symlink ~/.nix-userenv is made to point
+ to path.
+
+
+
+
+
+ Examples
+
+
+$ nix-env -I ~/nixpkgs-0.5/
+
+
+
+
+
+
+
diff --git a/doc/manual/nix-instantiate.xml b/doc/manual/nix-instantiate.xml
index ee073a17b..69630cb55 100644
--- a/doc/manual/nix-instantiate.xml
+++ b/doc/manual/nix-instantiate.xml
@@ -8,18 +8,58 @@
nix-instantiate
&opt-common-syn;
- files
+ files
-
+ Description
The command nix-instantiate generates
(low-level) store expressions from (high-level) Nix expressions.
+ It loads and evaluates the Nix expressions in each of
+ files. Each top-level expression
+ should evaluate to a derivation, a list of derivations, or a set
+ of derivations. The paths of the resulting store expressions
+ are printed on standard output.
-
+
+ This command is generally used for testing Nix expression before
+ they are used with nix-env.
+
+
+
+
+ Options
+
+
+
+ &opt-common;
+
+
+
+
+
+
+ Examples
+
+
+$ nix-instantiate gcc.nix (instantiate)
+/nix/store/468abdcb93aa22bb721142615b97698b-d-gcc-3.3.2.store
+
+$ nix-store -r $(nix-instantiate gcc.nix) (build)
+
+$ nix-store -r $(nix-instantiate gcc.nix) (print output path)
+/nix/store/9afa718cddfdfe94b5b9303d0430ceb1-gcc-3.3.2
+
+$ ls -l /nix/store/9afa718cddfdfe94b5b9303d0430ceb1-gcc-3.3.2
+dr-xr-xr-x 2 eelco users 360 2003-12-01 16:12 bin
+dr-xr-xr-x 3 eelco users 72 2003-12-01 16:12 include
+...
+
+
+
diff --git a/doc/manual/nix-prefetch-url.xml b/doc/manual/nix-prefetch-url.xml
new file mode 100644
index 000000000..a6b3711e3
--- /dev/null
+++ b/doc/manual/nix-prefetch-url.xml
@@ -0,0 +1,54 @@
+
+
+ nix-prefetch-url
+ copy a file from a URL into the store and print its MD5 hash
+
+
+
+
+ nix-prefetch-url
+ url
+
+
+
+
+ Description
+
+
+ The command nix-prefetch-url downloads the
+ file referenced by the URL url,
+ prints its MD5 cryptographic hash code, and copies it into the
+ Nix store. The file name in the store is
+ hash-basename,
+ where basename is everything
+ following the final slash in url.
+
+
+
+ This command is just a convenience to Nix expression writers.
+ Often a Nix expressions fetch some source distribution from the
+ network using the fetchurl expression
+ contained in nixpkgs. However,
+ fetchurl requires an MD5 hash. If you don't
+ know the hash, you would have to download the file first, and
+ then fetchurl would download it again when
+ you build your Nix expression. Since
+ fetchurl uses the same name for the
+ downloaded file as nix-prefetch-url, the
+ redundant download can be avoided.
+
+
+
+
+
+ Examples
+
+
+$ nix-prefetch-url ftp://ftp.nluug.nl/pub/gnu/make/make-3.80.tar.bz2
+...
+file has hash 0bbd1df101bc0294d440471e50feca71
+...
+
+
+
+
diff --git a/doc/manual/nix-pull.xml b/doc/manual/nix-pull.xml
new file mode 100644
index 000000000..2e0723c10
--- /dev/null
+++ b/doc/manual/nix-pull.xml
@@ -0,0 +1,43 @@
+
+
+ nix-pull
+ pull substitutes from a network cache
+
+
+
+
+ nix-pull
+ url
+
+
+
+
+ Description
+
+
+ The command nix-pull obtains a list of
+ pre-built store paths from the URL
+ url, 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.
+
+
+
+ The file at url must be compatible
+ with the files created by nix-push.
+
+
+
+
+
+ Examples
+
+
+$ nix-pull http://catamaran.labs.cs.uu.nl/dist/nix/nixpkgs-0.5pre753/MANIFEST
+
+
+
+
diff --git a/doc/manual/nix-push.xml b/doc/manual/nix-push.xml
new file mode 100644
index 000000000..be704d746
--- /dev/null
+++ b/doc/manual/nix-push.xml
@@ -0,0 +1,138 @@
+
+
+ nix-push
+ push store paths onto a network cache
+
+
+
+
+ nix-push
+ archives-put-url
+ archives-get-url
+ manifest-put-url
+ paths
+
+
+
+
+ Description
+
+
+ The command nix-push builds a set of store
+ expressions (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
+ nix-pull command.
+
+
+
+ nix-push performs the following actions.
+
+
+
+
+
+ The store expressions stored in
+ paths are realised (using
+ nix-store --realise).
+
+
+
+
+
+ All paths in the closure of the store expressions stored
+ in paths are determined (using
+ nix-store --query --requisites
+ --include-successors). It should be noted that
+ since the flag is
+ used, if you specify a derivation store expression, you
+ get a combined source/binary distribution. If you only
+ want a binary distribution, you should specify the closure
+ store expression that result from realising these (see
+ below).
+
+
+
+
+
+ All store paths determined in the previous step are
+ packaged and compressed into a bzipped
+ NAR archive (extension .nar.bz2).
+
+
+
+
+
+ A manifest 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.
+
+
+
+
+
+ Each store path is uploaded to the remote directory
+ specified by archives-put-url.
+ HTTP PUT requests are used to do this. However, before a
+ file x is uploaded to
+ archives-put-url/x,
+ nix-push first determines whether this
+ upload is unnecessary by issuing a HTTP HEAD request on
+ archives-get-url/x.
+ This allows a cache to be shared between many partially
+ overlapping nix-push 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.)
+
+
+
+
+
+ The manifest is uploaded using an HTTP PUT request to
+ manifest-put-url. The
+ corresponding URL to download the manifest can then be
+ used by nix-pull.
+
+
+
+
+
+
+
+
+
+ Examples
+
+
+ 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 foo.nix,
+ passing appropriate authentication information:
+
+
+$ 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)
+
+ This will push both sources and binaries (and any build-time
+ dependencies used in the build, such as compilers).
+
+
+
+ If we just want to push binaries, not sources and build-time
+ dependencies, we can do:
+
+
+$ nix-push urls $(nix-instantiate $(nix-store -r foo.nix))
+
+
+
+
+
+
diff --git a/doc/manual/overview.xml b/doc/manual/overview.xml
index e42c811c0..d3a7e443b 100644
--- a/doc/manual/overview.xml
+++ b/doc/manual/overview.xml
@@ -173,9 +173,8 @@ $ nix-env -if pkgs/system/i686-linux.nix pan
-$ nix-pull
-http://catamaran.labs.cs.uu.nl/dist/nix/nixpkgs-version/
-obtaining list of Nix archives at http://catamaran.labs.cs.uu.nl/dist/nix/nixpkgs-version...
+$ nix-pull http://catamaran.labs.cs.uu.nl/dist/nix/nixpkgs-version/MANIFEST
+obtaining list of Nix archives at http://catamaran.labs.cs.uu.nl/dist/nix/nixpkgs-version/MANIFEST...
...
diff --git a/doc/manual/quick-start.xml b/doc/manual/quick-start.xml
index b16fe7de8..294fbcba2 100644
--- a/doc/manual/quick-start.xml
+++ b/doc/manual/quick-start.xml
@@ -51,7 +51,7 @@ $ tar xfj nixpkgs-version.tar.bz2
network, rather than built from source.
-$ nix-pull http://.../nix/nixpkgs-version/
+$ nix-pull http://.../nix/nixpkgs-version/MANIFEST
diff --git a/doc/manual/style.css b/doc/manual/style.css
index 3ff9edbd4..5b8534533 100644
--- a/doc/manual/style.css
+++ b/doc/manual/style.css
@@ -1,5 +1,5 @@
-/* Copied from http://bakefile.sourceforge.net/ and covered by the GNU
- GPL. */
+/* Copied from http://bakefile.sourceforge.net/, which appears
+ licensed under the GNU GPL. */
/***************************************************************************
diff --git a/scripts/nix-prefetch-url.in b/scripts/nix-prefetch-url.in
index 050955682..71ba3caab 100644
--- a/scripts/nix-prefetch-url.in
+++ b/scripts/nix-prefetch-url.in
@@ -25,7 +25,7 @@ rename $out, $out2;
# Create a Nix expression.
my $nixexpr =
"(import @datadir@/nix/corepkgs/fetchurl) " .
- "{url = $url; md5 = \"$hash\"; system = \"@system@\"}";
+ "{url = $url; md5 = \"$hash\"; system = \"@system@\";}";
print "expr: $nixexpr\n";
diff --git a/scripts/nix-push.in b/scripts/nix-push.in
index 1e1d905ed..b5899e458 100644
--- a/scripts/nix-push.in
+++ b/scripts/nix-push.in
@@ -169,5 +169,5 @@ foreach my $nararchive (@nararchives) {
# Upload the manifest.
print STDERR "uploading manifest...\n";
system("$curl --show-error --upload-file " .
- "'$manifest' '$manifest_put_url/' > /dev/null") == 0 or
+ "'$manifest' '$manifest_put_url' > /dev/null") == 0 or
die "curl failed on $manifest: $?";
diff --git a/scripts/readmanifest.pm.in b/scripts/readmanifest.pm.in
index 2c6223807..08227a5d7 100644
--- a/scripts/readmanifest.pm.in
+++ b/scripts/readmanifest.pm.in
@@ -11,7 +11,7 @@ sub processURL {
print "obtaining list of Nix archives at $url...\n";
system("curl --fail --silent --show-error " .
- "'$url/MANIFEST' > '$manifest' 2> /dev/null") == 0
+ "'$url' > '$manifest' 2> /dev/null") == 0
or die "curl failed: $?";
open MANIFEST, "<$manifest";
diff --git a/src/nix-hash/help.txt b/src/nix-hash/help.txt
index 84ba152c5..a38c2ab9e 100644
--- a/src/nix-hash/help.txt
+++ b/src/nix-hash/help.txt
@@ -1,6 +1,6 @@
nix-hash [OPTIONS...] [FILES...]
-`nix-hash computes and prints cryptographic hashes for the specified
+`nix-hash' computes and prints cryptographic hashes for the specified
files.
--flat: compute hash of regular file contents, not metadata