diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index 8f4c84790..a0fa19406 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -7,8 +7,8 @@ XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs \ --param html.stylesheet \'style.css\' SOURCES = manual.xml introduction.xml installation.xml overview.xml \ - common-options.xml nix-store.xml nix-instantiate.xml \ - troubleshooting.xml bugs.xml \ + nix-store.xml nix-instantiate.xml \ + troubleshooting.xml bugs.xml opt-verbose.xml \ style.css images manual.is-valid: $(SOURCES) version.xml diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml index fcb69c364..33bd96a02 100644 --- a/doc/manual/bugs.xml +++ b/doc/manual/bugs.xml @@ -5,24 +5,20 @@ - Nix should automatically remove Berkeley DB logfiles. - - - - - - Unify the concepts of successors and substitutes into a general notion - of equivalent expressions. 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 performance - characteristics. For example, realising a slice is more - efficient that realising the derivation from which that slice was + Unify the concepts of successors and substitutes into a + general notion of equivalent expressions. + 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 performance characteristics. + For example, realising a closure expression is more efficient + that realising the derivation expression from which it 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. + 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. diff --git a/doc/manual/common-options.xml b/doc/manual/common-options.xml deleted file mode 100644 index d04042993..000000000 --- a/doc/manual/common-options.xml +++ /dev/null @@ -1,13 +0,0 @@ - - Common options - - - - - - - diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index 9f88dd409..1df0d1fc9 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -6,7 +6,7 @@ - + @@ -36,7 +36,6 @@ Command Reference - &common-options; nix-store &nix-store; diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml index 686fe4c15..36abf7af3 100644 --- a/doc/manual/nix-store.xml +++ b/doc/manual/nix-store.xml @@ -7,10 +7,6 @@ nix-store - - - - @@ -25,106 +21,36 @@ - + 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. - - - - - Indicates that any identifier arguments to the operation are paths - in the store rather than identifiers. - - - - - - - - - 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. - - - - - - - + &opt-verbose; @@ -140,65 +66,103 @@ - + + + Environment variables + + + The following environment variables affect the behaviour of + nix-store. + + + + + + TMPDIR=path + + + 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. + + + + + - diff --git a/doc/manual/opt-verbose.xml b/doc/manual/opt-verbose.xml new file mode 100644 index 000000000..5a1007a6a --- /dev/null +++ b/doc/manual/opt-verbose.xml @@ -0,0 +1,73 @@ + + + + + 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. + + + + This option may be specified repeatedly. Currently, the + following verbosity levels exist: + + + + + 0 + + + Errors only: only print messages explaining + why the Nix invocation failed. + + + + + 1 + + + Informational: print + useful messages about what Nix is + doing. + + + + + 2 + + + Talkative: print more informational messages. + + + + + 3 + + + Chatty: print even more informational messages. + + + + + 4 + + + Debug: print debug information: + + + + + 5 + + + Vomit: print vast amounts of debug + information. + + + + + + + diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml index 1e35c6079..529943f91 100644 --- a/doc/manual/troubleshooting.xml +++ b/doc/manual/troubleshooting.xml @@ -1,22 +1,9 @@ Troubleshooting - - Database logfile removal - - - Every time a Nix database transaction takes place, Nix writes a record of - this transaction to a log 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: - - - - $ rm `db_archive -a -h prefix/var/nix/db` - - + + (Nothing.) +