diff --git a/doc/manual/glossary/glossary.xml b/doc/manual/glossary/glossary.xml index e0636044c..a13630d2a 100644 --- a/doc/manual/glossary/glossary.xml +++ b/doc/manual/glossary/glossary.xml @@ -85,29 +85,48 @@ reference - A store path P is said to have a - reference to a store path Q if the store object - at P contains the path Q - somewhere. This implies than an execution involving - P potentially needs Q to be - present. The references of a store path are - the set of store paths to which it has a reference. + + A store path P is said to have a + reference to a store path Q if the store object + at P contains the path Q + somewhere. The references of a store path are + the set of store paths to which it has a reference. + + A derivation can reference other derivations and sources + (but not output paths), whereas an output path only references other + output paths. + + +reachable + + A store path Q is reachable from + another store path P if Q is in the + closure of the + references relation. + + closure The closure of a store path is the set of store paths that are directly or indirectly “reachable” from that store path; that is, it’s the closure of the path under the references relation. For instance, - if the store object at path P contains a - reference to path Q, then Q is - in the closure of P. For correct deployment it - is necessary to deploy whole closures, since otherwise at runtime - files could be missing. The command nix-store - -qR prints out closures of store paths. + linkend="gloss-reference">references relation. For a package, the + closure of its derivation is equivalent to the build-time + dependencies, while the closure of its output path is equivalent to its + runtime dependencies. For correct deployment it is necessary to deploy whole + closures, since otherwise at runtime files could be missing. The command + nix-store -qR prints out closures of store paths. + + As an example, if the store object at path P contains + a reference to path Q, then Q is + in the closure of P. Further, if Q + references R then R is also in + the closure of P. + @@ -147,7 +166,7 @@ linkend="sec-profiles" />. - + diff --git a/doc/manual/introduction/about-nix.xml b/doc/manual/introduction/about-nix.xml index 83a2b6786..e8c0a2975 100644 --- a/doc/manual/introduction/about-nix.xml +++ b/doc/manual/introduction/about-nix.xml @@ -60,7 +60,8 @@ This is because tools such as compilers don’t search in per-packages directories such as /nix/store/5lbfaxb722zp…-openssl-0.9.8d/include, so if a package builds correctly on your system, this is because you -specified the dependency explicitly. +specified the dependency explicitly. This takes care of the build-time +dependencies. Once a package is built, runtime dependencies are found by scanning binaries for the hash parts of Nix store paths (such as diff --git a/doc/manual/packages/garbage-collection.xml b/doc/manual/packages/garbage-collection.xml index 03b8e4c97..a1b0ef22a 100644 --- a/doc/manual/packages/garbage-collection.xml +++ b/doc/manual/packages/garbage-collection.xml @@ -52,6 +52,14 @@ garbage collector as follows: $ nix-store --gc +The behaviour of the gargage collector is affected by the keep- +derivations (default: true) and keep-outputs +(default: false) options in the Nix configuration file. The defaults will ensure +that all derivations that are not build-time dependencies of garbage collector roots +will be collected but that all output paths that are not runtime dependencies +will be collected. (This is usually what you want, but while you are developing +it may make sense to keep outputs to ensure that rebuild times are quick.) + If you are feeling uncertain, you can also first view what files would be deleted: