Merge pull request #7485 from fricklerhandwerk/doc-store-derivation

define "store derivation"
This commit is contained in:
Théophane Hufschmitt 2023-01-02 13:26:41 +01:00 committed by GitHub
commit cfd6c7fc9b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
11 changed files with 67 additions and 29 deletions

View file

@ -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

View file

@ -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 Nixs

View file

@ -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.

View file

@ -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)

View file

@ -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`\

View file

@ -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),
@ -124,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

View file

@ -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},
});

View file

@ -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
@ -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

View file

@ -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

View file

@ -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.

View file

@ -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