From b5942155314ea4b479fabde6ce236866f5ef4b97 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Thu, 8 Jan 2004 15:01:37 +0000 Subject: * Manual updates. --- doc/manual/nix-store.xml | 450 ++++++++++++++++++++++++++--------------------- 1 file changed, 250 insertions(+), 200 deletions(-) (limited to 'doc/manual/nix-store.xml') diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml index 686fe4c15643..36abf7af3659 100644 --- a/doc/manual/nix-store.xml +++ b/doc/manual/nix-store.xml @@ -7,10 +7,6 @@ nix-store - - - - @@ -25,180 +21,148 @@ - + Description - The command nix 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. + The command nix-store performs primitive + operations on the Nix store. You generally do not need to run + this command manually. - nix has many subcommands called - operations. These are individually documented - below. Exactly one operation must always be provided. + nix-store takes exactly one + operation flag which indicated the + subcommand to be performed. These are individually + documented below. - + - - Common Options + + Common options - 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). + This section lists the options that are common to all Nix + operations. These options are allowed for every subcommand, + though they may not always have an effect. + &opt-verbose; + - + - Indicates that any identifier arguments to the operation are paths - in the store rather than identifiers. + Specifies that in case of a build failure, the temporary directory + (usually in /tmp) in which the build takes + place should not be deleted. The path of the build directory is + printed as an informational message. - - - - - 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. - + - - This option may be specified repeatedly. Currently, the following - verbosity levels exist: - + - - - 0 - - - Print error messages only. - - - - - 1 - - - Print informational messages. - - - - - 2 - - - Print even more informational messages. - - - - - 3 - - - Print messages that should only be useful for debugging. - - - - - 4 - - - Vomit mode: print vast amounts of debug - information. - - - - - - + + Environment variables + + + The following environment variables affect the behaviour of + nix-store. + + + - + TMPDIR=path - Specifies that in case of a build failure, the temporary directory - (usually in /tmp) in which the build takes - place should not be deleted. The path of the build directory is - printed as an informational message. + Use the directory path to store + temporary files. In particular, this includes temporary + build directories; these can take up substantial amounts + of disk space. The default is /tmp. + + - - + - - Operation <option>--install</option> + + Operation <option>--realise</option> - + Synopsis - nix + nix-store - - + + - ids + paths - + - + Description - The operation realises the Nix expressions - identified by ids 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. + 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 identifiers of the normal forms of the given Nix expressions are - printed on standard output. + The paths of the closure expression corresponding to each + expression in paths is printed on + standard output. - + - + + - + Operation <option>--delete</option> - + Synopsis - nix + nix-store paths - + - + Description @@ -215,24 +179,24 @@ inconsistent system. Deletion of paths in the store is done by the garbage collector (which uses to delete unreferenced paths). - - + - + + - + Operation <option>--query</option> - + Synopsis - nix + nix-store @@ -244,34 +208,28 @@ - - - - - - - - - + + + args - + - + Description The operation displays various bits of - information about Nix expressions or paths in the store. The queries + information about store expressions or store paths. The queries are described in . At most one query - can be specified; the default query is . + can be specified. The default query is . - + - + Queries @@ -280,34 +238,15 @@ - Prints out the target paths of the Nix expressions indicated by - the identifiers args. 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). + Prints out the output paths of the + store expressions indicated by the identifiers + args. In the case of a + derivation expression, these are the paths that will be + produced when the derivation is realised. In the case + of a closure expression, these are the paths that were + produced the derivation expression of which the closure + expression is a successor. - - - This query has one option: - - - - - - - - - Causes the target paths of the normal - forms of the expressions to be printed, rather - than the target paths of the expressions themselves. - - - - - - @@ -315,40 +254,42 @@ - Prints out the requisite paths of the Nix expressions indicated - by the identifiers args. 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 closure 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). + Prints out the requisite paths of the store expressions + indicated by the identifiers + args. 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 closure 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). - 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. + The notion of requisite paths is very useful when one + wants to distribute store 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. - This query is generally used to implement various kinds of - distribution. A source distribution is - obtained by distributing the requisite paths of a derivation - expression. A binary distribution 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 and specify the identifier of a - derivation expression). A cache - distribution is obtained by distributing the - requisite paths of a derivation expression and specifying the - 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. + This query is generally used to implement various kinds + of deployment. A source deployment + is obtained by distributing the requisite paths of a + derivation expression. A binary + deployment is obtained by distributing the + requisite paths of a closure expression. A + cache deployment is obtained by + distributing the requisite paths of a derivation + expression and specifying the option + . This will + include not just the paths of a source and binary + deployment, 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. @@ -361,9 +302,10 @@ - Causes the requisite paths of the normal - forms of the expressions to be printed, rather - than the requisite paths of the expressions themselves. + Causes the requisite paths of the + successor of the given store + expressions to be printed, rather than the + requisite paths of the expressions themselves. @@ -372,9 +314,10 @@ - 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. + Excludes the paths of store expressions. This + causes the closure property to be lost, that is, + the resulting set of paths is not enough to ensure + realisibility. @@ -406,12 +349,16 @@ - + - For each identifier in args, prints - all expansions of that identifier, that is, all paths whose - current content matches the identifier. + For each store expression stored at paths + args, prints its + predecessors. A derivation + expression p is a predecessor of a + store expression q iff + q is a successor of + p. @@ -420,18 +367,121 @@ - Prints a graph of the closure of the expressions identified by - args in the format of the - dot tool of AT&T's GraphViz package. + Prints a graph of the closure of the store expressions + identified by args in the + format of the dot tool of AT&T's + GraphViz package. - + + + + + + + + + + Operation <option>--successor</option> + + + Synopsis + + nix-store + + + + srcpath sucpath + + + + + Description + + + The operation registers that the + closure expression in sucpath is a + successor of the derivation expression in + srcpath. This is used to implement + binary deployment. + + + + + + + + + + + + Operation <option>--substitute</option> + + + Synopsis + + nix-store + + + + srcpath subpath + + + + + Description + + + The operation registers that the + store path srcpath can be built by + realising the derivation expression in + subpath. This is used to implement + binary deployment. + + + + + + + + + + + + Operation <option>--verify</option> + + + Synopsis + + nix-store + + + + + + + + Description + + + The operation 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. + + + + + - -- cgit 1.4.1