From 62f4f883a7f63380be578ebb6167641ec111b59e Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Tue, 20 Dec 2022 15:11:31 +0100 Subject: [PATCH 1/3] define "store derivation" --- doc/manual/src/glossary.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index aa775b163..117b43a88 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -7,6 +7,18 @@ translated into low-level *store derivations* (implicitly by `nix-env` and `nix-build`, or explicitly by `nix-instantiate`). + [derivation]: #gloss-derivation + + - [store derivation]{#gloss-store-derivation}\ + A [derivation] represented as a `.drv` file in the [store]. + It has a [store path], like any [store object]. + + Example: `/nix/store/g946hcz4c8mdvq2g8vxx42z51qb71rvp-git-2.38.1.drv` + + See [`nix show-derivation`](./command-ref/new-cli/nix3-show-derivation.md) (experimental) for displaying the contents of store derivations. + + [store derivation]: #gloss-store-derivation + - [content-addressed derivation]{#gloss-content-addressed-derivation}\ A derivation which has the [`__contentAddressed`](./language/advanced-attributes.md#adv-attr-__contentAddressed) @@ -34,6 +46,8 @@ directory on another machine, accessed via `ssh` or served by the `nix-serve` Perl script. + [store]: #gloss-store + - [chroot store]{#gloss-chroot-store}\ A local store whose canonical path is anything other than `/nix/store`. @@ -49,6 +63,10 @@ The location in the file system of a store object, i.e., an immediate child of the Nix store directory. + Example: `/nix/store/a040m110amc4h71lds2jmr8qrkj2jhxd-git-2.38.1` + + [store path]: #gloss-store-path + - [store object]{#gloss-store-object}\ A file that is an immediate child of the Nix store directory. These can be regular files, but also entire directory trees. Store objects @@ -56,6 +74,8 @@ derivation outputs (objects produced by running a build task), or derivations (files describing a build task). + [store object]: #gloss-store-object + - [input-addressed store object]{#gloss-input-addressed-store-object}\ A store object produced by building a non-[content-addressed](#gloss-content-addressed-derivation), From 3a66d82e1da1302586055a70903de2f9a7425087 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Tue, 20 Dec 2022 15:26:05 +0100 Subject: [PATCH 2/3] update description of "store derivation" in installables section a store derivation is not a store path itself, it has a store path. --- doc/manual/src/glossary.md | 4 +++- src/nix/nix.md | 12 ++++++------ 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index 117b43a88..0fcc2b07b 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -144,7 +144,9 @@ references `R` then `R` is also in the closure of `P`. - [output path]{#gloss-output-path}\ - A store path produced by a derivation. + A [store path] produced by a [derivation]. + + [output path]: #gloss-output-path - [deriver]{#gloss-deriver}\ The deriver of an *output path* is the store diff --git a/src/nix/nix.md b/src/nix/nix.md index 723d3c87e..43de6869b 100644 --- a/src/nix/nix.md +++ b/src/nix/nix.md @@ -115,12 +115,12 @@ the Nix store. Here are the recognised types of installables: * **Store derivations**: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv` - Store derivations are store paths with extension `.drv` and are a - low-level representation of a build-time dependency graph used - internally by Nix. By default, if you pass a store derivation to a - `nix` subcommand, it will operate on the *output paths* of the - derivation. For example, `nix path-info` prints information about - the output paths: + Store derivations are a low-level, internal representation of build tasks in Nix, and have store paths with extension `.drv`. + By default, if you pass the path to a store derivation to a `nix` subcommand, the command will operate on the [output path]s of the derivation. + + [output path]: ../../glossary.md#gloss-output-path + + For example, `nix path-info` prints information about the output paths: ```console # nix path-info --json /nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv From 7797661a70bcd6a7caf756964785ea7727ed1be0 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Tue, 20 Dec 2022 15:37:40 +0100 Subject: [PATCH 3/3] link "store derivation" to glossary definition --- doc/manual/src/command-ref/nix-build.md | 4 +++- doc/manual/src/command-ref/nix-copy-closure.md | 4 +++- doc/manual/src/command-ref/nix-env.md | 8 +++++--- doc/manual/src/command-ref/nix-instantiate.md | 10 +++++----- doc/manual/src/command-ref/nix-store.md | 14 ++++++++------ src/libcmd/installables.cc | 2 +- src/nix/nix.md | 4 +++- src/nix/path-info.md | 4 +++- src/nix/show-derivation.md | 6 ++++-- src/nix/store-copy-log.md | 4 +++- 10 files changed, 38 insertions(+), 22 deletions(-) diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md index 3a47feaae..937b046b8 100644 --- a/doc/manual/src/command-ref/nix-build.md +++ b/doc/manual/src/command-ref/nix-build.md @@ -37,10 +37,12 @@ directory containing at least a file named `default.nix`. `nix-build` is essentially a wrapper around [`nix-instantiate`](nix-instantiate.md) (to translate a high-level Nix -expression to a low-level store derivation) and [`nix-store +expression to a low-level [store derivation]) and [`nix-store --realise`](nix-store.md#operation---realise) (to build the store derivation). +[store derivation]: ../glossary.md#gloss-store-derivation + > **Warning** > > The result of the build is automatically registered as a root of the diff --git a/doc/manual/src/command-ref/nix-copy-closure.md b/doc/manual/src/command-ref/nix-copy-closure.md index 9a29030bd..83e8a2936 100644 --- a/doc/manual/src/command-ref/nix-copy-closure.md +++ b/doc/manual/src/command-ref/nix-copy-closure.md @@ -47,7 +47,9 @@ authentication, you can avoid typing the passphrase with `ssh-agent`. Enable compression of the SSH connection. - `--include-outputs`\ - Also copy the outputs of store derivations included in the closure. + Also copy the outputs of [store derivation]s included in the closure. + + [store derivation]: ../../glossary.md#gloss-store-derivation - `--use-substitutes` / `-s`\ Attempt to download missing paths on the target machine using Nix’s diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md index a5df35d77..f4fa5b50c 100644 --- a/doc/manual/src/command-ref/nix-env.md +++ b/doc/manual/src/command-ref/nix-env.md @@ -205,10 +205,12 @@ a number of possible ways: unambiguous way, which is necessary if there are multiple derivations with the same name. - - If *args* are store derivations, then these are + - If *args* are [store derivation]s, then these are [realised](nix-store.md#operation---realise), and the resulting output paths are installed. + [store derivation]: ../glossary.md#gloss-store-derivation + - If *args* are store paths that are not store derivations, then these are [realised](nix-store.md#operation---realise) and installed. @@ -280,7 +282,7 @@ To copy the store path with symbolic name `gcc` from another profile: $ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc ``` -To install a specific store derivation (typically created by +To install a specific [store derivation] (typically created by `nix-instantiate`): ```console @@ -665,7 +667,7 @@ derivation is shown unless `--no-name` is specified. Print the `system` attribute of the derivation. - `--drv-path`\ - Print the path of the store derivation. + Print the path of the [store derivation]. - `--out-path`\ Print the output path of the derivation. diff --git a/doc/manual/src/command-ref/nix-instantiate.md b/doc/manual/src/command-ref/nix-instantiate.md index 8f143729e..432fb2608 100644 --- a/doc/manual/src/command-ref/nix-instantiate.md +++ b/doc/manual/src/command-ref/nix-instantiate.md @@ -17,13 +17,14 @@ # Description -The command `nix-instantiate` generates [store -derivations](../glossary.md) from (high-level) Nix expressions. It -evaluates the Nix expressions in each of *files* (which defaults to +The command `nix-instantiate` produces [store derivation]s from (high-level) Nix expressions. +It evaluates the Nix expressions in each of *files* (which defaults to *./default.nix*). Each top-level expression should evaluate to a derivation, a list of derivations, or a set of derivations. The paths of the resulting store derivations are printed on standard output. +[store derivation]: ../glossary.md#gloss-store-derivation + If *files* is the character `-`, then a Nix expression will be read from standard input. @@ -79,8 +80,7 @@ standard input. # Examples -Instantiating store derivations from a Nix expression, and building them -using `nix-store`: +Instantiate [store derivation]s from a Nix expression, and build them using `nix-store`: ```console $ nix-instantiate test.nix (instantiate) diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md index b712a7463..acf29e4aa 100644 --- a/doc/manual/src/command-ref/nix-store.md +++ b/doc/manual/src/command-ref/nix-store.md @@ -137,8 +137,10 @@ or. ## Examples -This operation is typically used to build store derivations produced by -[`nix-instantiate`](nix-instantiate.md): +This operation is typically used to build [store derivation]s produced by +[`nix-instantiate`](./nix-instantiate.md): + +[store derivation]: ../glossary.md#gloss-store-derivation ```console $ nix-store -r $(nix-instantiate ./test.nix) @@ -298,7 +300,7 @@ symlink. ## Common query options - `--use-output`; `-u`\ - For each argument to the query that is a store derivation, apply the + For each argument to the query that is a [store derivation], apply the query to the output path of the derivation instead. - `--force-realise`; `-f`\ @@ -318,7 +320,7 @@ symlink. This query has one option: - `--include-outputs` - Also include the existing output paths of store derivations, + Also include the existing output paths of [store derivation]s, and their closures. This query can be used to implement various kinds of deployment. A @@ -372,12 +374,12 @@ symlink. Prints the references graph of the store paths *paths* in the [GraphML](http://graphml.graphdrawing.org/) file format. This can be used to visualise dependency graphs. To obtain a build-time - dependency graph, apply this to a store derivation. To obtain a + dependency graph, apply this to a [store derivation]. To obtain a runtime dependency graph, apply it to an output path. - `--binding` *name*; `-b` *name*\ Prints the value of the attribute *name* (i.e., environment - variable) of the store derivations *paths*. It is an error for a + variable) of the [store derivation]s *paths*. It is an error for a derivation to not have the specified attribute. - `--hash`\ diff --git a/src/libcmd/installables.cc b/src/libcmd/installables.cc index 5cdd3e12c..d2600ca91 100644 --- a/src/libcmd/installables.cc +++ b/src/libcmd/installables.cc @@ -168,7 +168,7 @@ SourceExprCommand::SourceExprCommand(bool supportReadOnlyMode) addFlag({ .longName = "derivation", - .description = "Operate on the store derivation rather than its outputs.", + .description = "Operate on the [store derivation](../../glossary.md#gloss-store-derivation) rather than its outputs.", .category = installablesCategory, .handler = {&operateOn, OperateOn::Derivation}, }); diff --git a/src/nix/nix.md b/src/nix/nix.md index 43de6869b..9641cccb2 100644 --- a/src/nix/nix.md +++ b/src/nix/nix.md @@ -202,9 +202,11 @@ operate are determined as follows: a command like `nix shell nixpkgs#libxml2` will provide only those two outputs by default. - Note that a store derivation (given by `.drv` file store path) doesn't have + Note that a [store derivation] (given by its `.drv` file store path) doesn't have any attributes like `meta`, and thus this case doesn't apply to it. + [store derivation]: ../../glossary.md#gloss-store-derivation + * Otherwise, Nix will use all outputs of the derivation. # Nix stores diff --git a/src/nix/path-info.md b/src/nix/path-info.md index 7a1714ba4..b30898ac0 100644 --- a/src/nix/path-info.md +++ b/src/nix/path-info.md @@ -68,7 +68,9 @@ R""( ] ``` -* Print the path of the store derivation produced by `nixpkgs#hello`: +* Print the path of the [store derivation] produced by `nixpkgs#hello`: + + [store derivation]: ../../glossary.md#gloss-store-derivation ```console # nix path-info --derivation nixpkgs#hello diff --git a/src/nix/show-derivation.md b/src/nix/show-derivation.md index aa863899c..2cd93aa62 100644 --- a/src/nix/show-derivation.md +++ b/src/nix/show-derivation.md @@ -2,9 +2,11 @@ R""( # Examples -* Show the store derivation that results from evaluating the Hello +* Show the [store derivation] that results from evaluating the Hello package: + [store derivation]: ../../glossary.md#gloss-store-derivation + ```console # nix show-derivation nixpkgs#hello { @@ -37,7 +39,7 @@ R""( # Description This command prints on standard output a JSON representation of the -store derivations to which *installables* evaluate. Store derivations +[store derivation]s to which *installables* evaluate. Store derivations are used internally by Nix. They are store paths with extension `.drv` that represent the build-time dependency graph to which a Nix expression evaluates. diff --git a/src/nix/store-copy-log.md b/src/nix/store-copy-log.md index 19ae57079..0937250f2 100644 --- a/src/nix/store-copy-log.md +++ b/src/nix/store-copy-log.md @@ -18,7 +18,9 @@ R""( (The flag `--substituters ''` avoids querying `https://cache.nixos.org` for the log.) -* To copy the log for a specific store derivation via SSH: +* To copy the log for a specific [store derivation] via SSH: + + [store derivation]: ../../glossary.md#gloss-store-derivation ```console # nix store copy-log --to ssh-ng://machine /nix/store/ilgm50plpmcgjhcp33z6n4qbnpqfhxym-glibc-2.33-59.drv