From 92e832348db13637875c4f529ed0aa83d3d34493 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Tue, 10 Feb 2004 16:14:47 +0000 Subject: [PATCH] * Lots of manual stuff. Reference pages for most Nix commands. * nix-pull now requires the full url to the manifest, i.e., `/MANIFEST/' is no longer automatically appended. * nix-prefetch-url works again. --- doc/manual/Makefile.am | 8 +- doc/manual/bugs.xml | 73 +++++++++- doc/manual/manual.xml | 20 +++ doc/manual/nix-collect-garbage.xml | 75 ++++++++++ doc/manual/nix-env.xml | 226 ++++++++++++++++++++++++++++- doc/manual/nix-instantiate.xml | 46 +++++- doc/manual/nix-prefetch-url.xml | 54 +++++++ doc/manual/nix-pull.xml | 43 ++++++ doc/manual/nix-push.xml | 138 ++++++++++++++++++ doc/manual/overview.xml | 5 +- doc/manual/quick-start.xml | 2 +- doc/manual/style.css | 4 +- scripts/nix-prefetch-url.in | 2 +- scripts/nix-push.in | 2 +- scripts/readmanifest.pm.in | 2 +- src/nix-hash/help.txt | 2 +- 16 files changed, 678 insertions(+), 24 deletions(-) create mode 100644 doc/manual/nix-collect-garbage.xml create mode 100644 doc/manual/nix-prefetch-url.xml create mode 100644 doc/manual/nix-pull.xml create mode 100644 doc/manual/nix-push.xml 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