From 57d023a184bdc2f30cd7052c157e43ba1bca8288 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Thu, 7 Apr 2005 10:47:58 +0000 Subject: [PATCH] * More manual updates. --- doc/manual/Makefile.am | 5 +- doc/manual/glossary.xml | 12 +++- doc/manual/manual.xml | 6 +- doc/manual/nix-build.xml | 72 ++++++++++++++++++++++ doc/manual/nix-store.xml | 84 ++++++++++++++++++-------- doc/manual/writing-nix-expressions.xml | 3 +- 6 files changed, 153 insertions(+), 29 deletions(-) create mode 100644 doc/manual/nix-build.xml diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index f5dfdb1dd8..60853df05d 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -5,9 +5,10 @@ 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 0 + --param xref.with.number.and.title 0 \ + --param toc.section.depth 3 -man1_MANS = nix-env.1 nix-store.1 nix-instantiate.1 \ +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 diff --git a/doc/manual/glossary.xml b/doc/manual/glossary.xml index cf0da38245..c3dc36fb3f 100644 --- a/doc/manual/glossary.xml +++ b/doc/manual/glossary.xml @@ -46,7 +46,7 @@ -substitute +substitute A substitute is a command invocation stored in the Nix database that describes how to build a store object, bypassing @@ -94,6 +94,16 @@ +validity + + A store path is considered + valid 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. + + + + diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index 9f0e4ae94c..b71798e80a 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -39,11 +39,15 @@ nix-env + + nix-build + + nix-store - + nix-instantiate diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml new file mode 100644 index 0000000000..2a5af6adb3 --- /dev/null +++ b/doc/manual/nix-build.xml @@ -0,0 +1,72 @@ + + + + nix-build + build a Nix expression + + + + + nix-build + paths + + + +Description + +The nix-build command builds the derivations +described by the Nix expressions in paths. +If the build succeeds, it places a symlink to the result in the +current directory. The symlink is called result. +If there are multiple Nix expressions, or the Nix expressions evaluate +to multiple derivations, multiple sequentially numbered symlinks are +created (result, result-2, +and so on). + +nix-build is essentially a wrapper +around nix-instantiate +(to translate a high-level Nix expression to a low-level store +derivation) and nix-store +--realise (to build the store +derivation). + +The result of the build is automatically registered as +a root of the Nix garbage collector. This root disappears +automatically when the result symlink is deleted +or renamed. So don’t rename the symlink. + + + + +Options + + + + + + Add a symlink in the current directory to the + store derivation produced by nix-instantiate. + The symlink is called derivation (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. + + + + + + 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 nix-store + --gc. + + + + + + + + + diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml index d9ef17e26e..c67e20266f 100644 --- a/doc/manual/nix-store.xml +++ b/doc/manual/nix-store.xml @@ -45,7 +45,7 @@ linkend="sec-common-options" /> for a list of common options. path - Causes the result of a build action + Causes the result of a realisation ( and ) to be registered as a root of the garbage collector (see ). The root is stored in @@ -54,7 +54,12 @@ linkend="sec-common-options" /> for a list of common options. typically in a subdirectory of /nix/var/nix/gcroots/) unless the flag - is used. + is used. + + If there are multiple results, then multiple symlinks will + be created by sequentially numbering symlinks beyond the first one + (e.g., foo, foo-2, + foo-3, and so on). @@ -121,25 +126,56 @@ lrwxrwxrwx 1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r1134 Description -The operation realises in the file -system the store expressions stored in -paths. If these expressions are derivation -expressions, they are first normalised into a -closure expression. This may happen in two ways. First, the -corresponding closure expression (the successor) -may already known (either because the build has already been -performed, or because a successor was explicitly registered through -the operation). Otherwise, the build -action described by the derivation is performed, and a closure -expression is computed by scanning the result of the build for -references to other paths in the store. +The operation essentially “builds” +the specified store paths. Realisation is a somewhat overloaded term: -The paths of the closure expression corresponding to each -expression in paths is printed on standard -output. + + + If the store path is a + derivation, realisation ensures that the output + paths of the derivation are valid (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 substitutes that produce the + outputs (e.g., by downloading them). Finally, the outputs can be + produced by performing the build action described by the + derivation. + + 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. + + + + + +The output path of each derivation is printed on standard +output. (For non-derivations argument, the argument itself is +printed.) + +Examples + +This operation is typically used to build store derivations +produced by nix-instantiate: + + +$ nix-store -r $(nix-instantiate ./foo.nix) + +This is essentially what nix-build does. + + + + @@ -168,7 +204,7 @@ output. Without additional flags, the operation 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. +“roots”, are deleted. The following suboperations may be specified: @@ -184,9 +220,9 @@ the Nix store not reachable via file system references from a set of 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 + 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. @@ -195,9 +231,9 @@ the Nix store not reachable via file system references from a set of 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. + 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. diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index 1b177c7dab..a664f1e325 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -447,7 +447,8 @@ following: (import pkgs/system/i686-linux.nix).hello Call it test.nix. You can then build it without -installing it using the command nix-build: +installing it using the command nix-build: $ nix-build ./test.nix