diff --git a/doc/manual/redirects.js b/doc/manual/redirects.js index dea141391df..a1d30d9e81c 100644 --- a/doc/manual/redirects.js +++ b/doc/manual/redirects.js @@ -346,6 +346,9 @@ const redirects = { "scoping-rules": "scoping.html", "string-literal": "string-literals.html", }, + "language/derivations.md": { + "builder-execution": "store/drv/building.md#builder-execution", + }, "installation/installing-binary.html": { "linux": "uninstall.html#linux", "macos": "uninstall.html#macos", diff --git a/doc/manual/source/SUMMARY.md.in b/doc/manual/source/SUMMARY.md.in index a92bca42f4d..0abe691cc25 100644 --- a/doc/manual/source/SUMMARY.md.in +++ b/doc/manual/source/SUMMARY.md.in @@ -22,6 +22,8 @@ - [Store Object](store/store-object.md) - [Content-Addressing Store Objects](store/store-object/content-address.md) - [Store Path](store/store-path.md) + - [Store Derivation and Deriving Path](store/drv.md) + - [Building](store/building.md) - [Store Types](store/types/index.md) {{#include ./store/types/SUMMARY.md}} - [Nix Language](language/index.md) diff --git a/doc/manual/source/architecture/architecture.md b/doc/manual/source/architecture/architecture.md index 867a9c992d3..cbc469355f8 100644 --- a/doc/manual/source/architecture/architecture.md +++ b/doc/manual/source/architecture/architecture.md @@ -69,7 +69,7 @@ It can also execute build plans to produce new data, which are made available to A build plan itself is a series of *build tasks*, together with their build inputs. > **Important** -> A build task in Nix is called [derivation](@docroot@/glossary.md#gloss-derivation). +> A build task in Nix is called [store derivation](@docroot@/glossary.md#gloss-store-derivation). Each build task has a special build input executed as *build instructions* in order to perform the build. The result of a build task can be input to another build task. diff --git a/doc/manual/source/command-ref/nix-env/install.md b/doc/manual/source/command-ref/nix-env/install.md index aa5c2fbba83..527fd8f90d8 100644 --- a/doc/manual/source/command-ref/nix-env/install.md +++ b/doc/manual/source/command-ref/nix-env/install.md @@ -22,11 +22,11 @@ It is based on the current generation of the active [profile](@docroot@/command- The arguments *args* map to store paths in a number of possible ways: -- By default, *args* is a set of [derivation] names denoting derivations in the [default Nix expression]. +- By default, *args* is a set of names denoting derivations in the [default Nix expression]. These are [realised], and the resulting output paths are installed. Currently installed derivations with a name equal to the name of a derivation being added are removed unless the option `--preserve-installed` is specified. - [derivation]: @docroot@/glossary.md#gloss-derivation + [derivation expression]: @docroot@/glossary.md#gloss-derivation-expression [default Nix expression]: @docroot@/command-ref/files/default-nix-expression.md [realised]: @docroot@/glossary.md#gloss-realise @@ -66,11 +66,11 @@ The arguments *args* map to store paths in a number of possible ways: This can be used to override the priority of the derivations being installed. This is useful if *args* are [store paths], which don't have any priority information. -- If *args* are [store derivations](@docroot@/glossary.md#gloss-store-derivation), then these are [realised], and the resulting output paths are installed. +- If *args* are [store paths] that point to [store derivations][store derivation], then those store derivations are [realised], and the resulting output paths are installed. -- If *args* are [store paths] that are not store derivations, then these are [realised] and installed. +- If *args* are [store paths] that do not point to store derivations, then these are [realised] and installed. -- By default all [outputs](@docroot@/language/derivations.md#attr-outputs) are installed for each [derivation]. +- By default all [outputs](@docroot@/language/derivations.md#attr-outputs) are installed for each [store derivation]. This can be overridden by adding a `meta.outputsToInstall` attribute on the derivation listing a subset of the output names. Example: @@ -122,6 +122,8 @@ The arguments *args* map to store paths in a number of possible ways: manifest.nix ``` +[store derivation]: @docroot@/glossary.md#gloss-store-derivation + # Options - `--prebuilt-only` / `-b` diff --git a/doc/manual/source/command-ref/nix-env/query.md b/doc/manual/source/command-ref/nix-env/query.md index c67794ed58e..bde9b38202c 100644 --- a/doc/manual/source/command-ref/nix-env/query.md +++ b/doc/manual/source/command-ref/nix-env/query.md @@ -125,7 +125,10 @@ derivation is shown unless `--no-name` is specified. - `--drv-path` - Print the path of the [store derivation](@docroot@/glossary.md#gloss-store-derivation). + Print the [store path] to the [store derivation]. + + [store path]: @docroot@/glossary.md#gloss-store-path + [store derivation]: @docroot@/glossary.md#gloss-derivation - `--out-path` diff --git a/doc/manual/source/command-ref/nix-instantiate.md b/doc/manual/source/command-ref/nix-instantiate.md index 487ef8f102f..38454515d57 100644 --- a/doc/manual/source/command-ref/nix-instantiate.md +++ b/doc/manual/source/command-ref/nix-instantiate.md @@ -42,8 +42,8 @@ standard input. - `--eval` Just parse and evaluate the input files, and print the resulting - values on standard output. No instantiation of store derivations - takes place. + values on standard output. + Store derivations are not serialized and written to the store, but instead just hashed and discarded. > **Warning** > diff --git a/doc/manual/source/glossary.md b/doc/manual/source/glossary.md index fa357ece3d6..772116e9886 100644 --- a/doc/manual/source/glossary.md +++ b/doc/manual/source/glossary.md @@ -19,31 +19,35 @@ Besides content addressing, the Nix store also uses [input addressing](#gloss-input-addressed-store-object). -- [derivation]{#gloss-derivation} +- [store derivation]{#gloss-store-derivation} - A description of a build task. The result of a derivation is a - store object. Derivations declared in Nix expressions are specified - using the [`derivation` primitive](./language/derivations.md). These are - translated into low-level *store derivations* (implicitly by - `nix-build`, or explicitly by `nix-instantiate`). + A single build task. + See [Store Derivation](@docroot@/store/drv.md#store-derivation) for details. - [derivation]: #gloss-derivation + [store derivation]: #gloss-store-derivation -- [store derivation]{#gloss-store-derivation} +- [derivation path]{#gloss-derivation-path} - A [derivation] represented as a `.drv` file in the [store]. - It has a [store path], like any [store object]. - It is the [instantiated][instantiate] form of a derivation. + A [store path] which uniquely identifies a [store derivation]. - Example: `/nix/store/g946hcz4c8mdvq2g8vxx42z51qb71rvp-git-2.38.1.drv` + See [Referencing Store Derivations](@docroot@/store/drv.md#derivation-path) for details. - See [`nix derivation show`](./command-ref/new-cli/nix3-derivation-show.md) (experimental) for displaying the contents of store derivations. + Not to be confused with [deriving path]. - [store derivation]: #gloss-store-derivation + [derivation path]: #gloss-derivation-path + +- [derivation expression]{#gloss-derivation-expression} + + A description of a [store derivation] in the Nix language. + The output(s) of a derivation are store objects. + Derivations are typically specified in Nix expressions using the [`derivation` primitive](./language/derivations.md). + These are translated into store layer *derivations* (implicitly by `nix-env` and `nix-build`, or explicitly by `nix-instantiate`). + + [derivation expression]: #gloss-derivation-expression - [instantiate]{#gloss-instantiate}, instantiation - Save an evaluated [derivation] as a [store derivation] in the Nix [store]. + Translate a [derivation expression] into a [store derivation]. See [`nix-instantiate`](./command-ref/nix-instantiate.md), which produces a store derivation from a Nix expression that evaluates to a derivation. @@ -55,7 +59,7 @@ This can be achieved by: - Fetching a pre-built [store object] from a [substituter] - - Running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [derivation] + - Running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [store derivation] - Delegating to a [remote machine](@docroot@/command-ref/conf-file.md#conf-builders) and retrieving the outputs @@ -73,7 +77,7 @@ - [fixed-output derivation]{#gloss-fixed-output-derivation} (FOD) - A [derivation] where a cryptographic hash of the [output] is determined in advance using the [`outputHash`](./language/advanced-attributes.md#adv-attr-outputHash) attribute, and where the [`builder`](@docroot@/language/derivations.md#attr-builder) executable has access to the network. + A [store derivation] where a cryptographic hash of the [output] is determined in advance using the [`outputHash`](./language/advanced-attributes.md#adv-attr-outputHash) attribute, and where the [`builder`](@docroot@/language/derivations.md#attr-builder) executable has access to the network. - [store]{#gloss-store} @@ -188,7 +192,7 @@ > > The contents of a `.nix` file form a Nix expression. - Nix expressions specify [derivations][derivation], which are [instantiated][instantiate] into the Nix store as [store derivations][store derivation]. + Nix expressions specify [derivation expressions][derivation expression], which are [instantiated][instantiate] into the Nix store as [store derivations][store derivation]. These derivations can then be [realised][realise] to produce [outputs][output]. > **Example** @@ -230,14 +234,14 @@ - [output]{#gloss-output} - A [store object] produced by a [derivation]. + A [store object] produced by a [store derivation]. See [the `outputs` argument to the `derivation` function](@docroot@/language/derivations.md#attr-outputs) for details. [output]: #gloss-output - [output path]{#gloss-output-path} - The [store path] to the [output] of a [derivation]. + The [store path] to the [output] of a [store derivation]. [output path]: #gloss-output-path @@ -246,14 +250,11 @@ - [deriving path]{#gloss-deriving-path} - Deriving paths are a way to refer to [store objects][store object] that ar not yet [realised][realise]. - This is necessary because, in general and particularly for [content-addressed derivations][content-addressed derivation], the [output path] of an [output] is not known in advance. - There are two forms: + Deriving paths are a way to refer to [store objects][store object] that might not yet be [realised][realise]. - - *constant*: just a [store path] - It can be made [valid][validity] by copying it into the store: from the evaluator, command line interface or another store. + See [Deriving Path](./store/drv.md#deriving-path) for details. - - *output*: a pair of a [store path] to a [derivation] and an [output] name. + Not to be confused with [derivation path]. - [deriver]{#gloss-deriver} diff --git a/doc/manual/source/language/derivations.md b/doc/manual/source/language/derivations.md index 771b2bd9130..0f9284e9844 100644 --- a/doc/manual/source/language/derivations.md +++ b/doc/manual/source/language/derivations.md @@ -1,9 +1,10 @@ # Derivations -The most important built-in function is `derivation`, which is used to describe a single derivation: -a specification for running an executable on precisely defined input files to repeatably produce output files at uniquely determined file system paths. +The most important built-in function is `derivation`, which is used to describe a single store-layer [store derivation]. +Consult the [store chapter](@docroot@/store/drv.md) for what a store derivation is; +this section just concerns how to create one from the Nix language. -It takes as input an attribute set, the attributes of which specify the inputs to the process. +This builtin function takes as input an attribute set, the attributes of which specify the inputs to the process. It outputs an attribute set, and produces a [store derivation] as a side effect of evaluation. [store derivation]: @docroot@/glossary.md#gloss-store-derivation @@ -15,7 +16,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect - [`name`]{#attr-name} ([String](@docroot@/language/types.md#type-string)) A symbolic name for the derivation. - It is added to the [store path] of the corresponding [store derivation] as well as to its [output paths](@docroot@/glossary.md#gloss-output-path). + See [derivation outputs](@docroot@/store/drv.md#outputs) for what this is affects. [store path]: @docroot@/store/store-path.md @@ -28,17 +29,12 @@ It outputs an attribute set, and produces a [store derivation] as a side effect > } > ``` > - > The store derivation's path will be `/nix/store/-hello.drv`. + > The derivation's path will be `/nix/store/-hello.drv`. > The [output](#attr-outputs) paths will be of the form `/nix/store/-hello[-]` - [`system`]{#attr-system} ([String](@docroot@/language/types.md#type-string)) - The system type on which the [`builder`](#attr-builder) executable is meant to be run. - - A necessary condition for Nix to build derivations locally is that the `system` attribute matches the current [`system` configuration option]. - It can automatically [build on other platforms](@docroot@/language/derivations.md#attr-builder) by forwarding build requests to other machines. - - [`system` configuration option]: @docroot@/command-ref/conf-file.md#conf-system + See [system](@docroot@/store/drv.md#system). > **Example** > @@ -68,7 +64,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect - [`builder`]{#attr-builder} ([Path](@docroot@/language/types.md#type-path) | [String](@docroot@/language/types.md#type-string)) - Path to an executable that will perform the build. + See [builder](@docroot@/store/drv.md#builder). > **Example** > @@ -117,7 +113,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect Default: `[ ]` - Command-line arguments to be passed to the [`builder`](#attr-builder) executable. + See [args](@docroot@/store/drv.md#args). > **Example** > @@ -239,77 +235,3 @@ It outputs an attribute set, and produces a [store derivation] as a side effect passed as an empty string. - -## Builder execution - -The [`builder`](#attr-builder) is executed as follows: - -- A temporary directory is created under the directory specified by - `TMPDIR` (default `/tmp`) where the build will take place. The - current directory is changed to this directory. - -- The environment is cleared and set to the derivation attributes, as - specified above. - -- In addition, the following variables are set: - - - `NIX_BUILD_TOP` contains the path of the temporary directory for - this build. - - - Also, `TMPDIR`, `TEMPDIR`, `TMP`, `TEMP` are set to point to the - temporary directory. This is to prevent the builder from - accidentally writing temporary files anywhere else. Doing so - might cause interference by other processes. - - - `PATH` is set to `/path-not-set` to prevent shells from - initialising it to their built-in default value. - - - `HOME` is set to `/homeless-shelter` to prevent programs from - using `/etc/passwd` or the like to find the user's home - directory, which could cause impurity. Usually, when `HOME` is - set, it is used as the location of the home directory, even if - it points to a non-existent path. - - - `NIX_STORE` is set to the path of the top-level Nix store - directory (typically, `/nix/store`). - - - `NIX_ATTRS_JSON_FILE` & `NIX_ATTRS_SH_FILE` if `__structuredAttrs` - is set to `true` for the derivation. A detailed explanation of this - behavior can be found in the - [section about structured attrs](./advanced-attributes.md#adv-attr-structuredAttrs). - - - For each output declared in `outputs`, the corresponding - environment variable is set to point to the intended path in the - Nix store for that output. Each output path is a concatenation - of the cryptographic hash of all build inputs, the `name` - attribute and the output name. (The output name is omitted if - it’s `out`.) - -- If an output path already exists, it is removed. Also, locks are - acquired to prevent multiple Nix instances from performing the same - build at the same time. - -- A log of the combined standard output and error is written to - `/nix/var/log/nix`. - -- The builder is executed with the arguments specified by the - attribute `args`. If it exits with exit code 0, it is considered to - have succeeded. - -- The temporary directory is removed (unless the `-K` option was - specified). - -- If the build was successful, Nix scans each output path for - references to input paths by looking for the hash parts of the input - paths. Since these are potential runtime dependencies, Nix registers - them as dependencies of the output paths. - -- After the build, Nix sets the last-modified timestamp on all files - in the build result to 1 (00:00:01 1/1/1970 UTC), sets the group to - the default group, and sets the mode of the file to 0444 or 0555 - (i.e., read-only, with execute permission enabled if the file was - originally executable). Note that possible `setuid` and `setgid` - bits are cleared. Setuid and setgid programs are not currently - supported by Nix. This is because the Nix archives used in - deployment have no concept of ownership information, and because it - makes the build result dependent on the user performing the build. diff --git a/doc/manual/source/language/import-from-derivation.md b/doc/manual/source/language/import-from-derivation.md index e901f5bcf5b..f161c6fe391 100644 --- a/doc/manual/source/language/import-from-derivation.md +++ b/doc/manual/source/language/import-from-derivation.md @@ -71,8 +71,9 @@ Boxes are data structures, arrow labels are transformations. | evaluate | | | | | | | | | V | | | -| .------------. | | .------------------. | -| | derivation |----|-instantiate-|->| store derivation | | +| .------------. | | | +| | derivation | | | .------------------. | +| | expression |----|-instantiate-|->| store derivation | | | '------------' | | '------------------' | | | | | | | | | realise | diff --git a/doc/manual/source/language/string-interpolation.md b/doc/manual/source/language/string-interpolation.md index 27780dcbb39..a503d5f04bd 100644 --- a/doc/manual/source/language/string-interpolation.md +++ b/doc/manual/source/language/string-interpolation.md @@ -22,9 +22,9 @@ Rather than writing "--with-freetype2-library=" + freetype + "/lib" ``` -(where `freetype` is a [derivation]), you can instead write +(where `freetype` is a [derivation expression]), you can instead write -[derivation]: @docroot@/glossary.md#gloss-derivation +[derivation expression]: @docroot@/glossary.md#gloss-derivation-expression ```nix "--with-freetype2-library=${freetype}/lib" @@ -148,7 +148,7 @@ An expression that is interpolated must evaluate to one of the following: - `__toString` must be a function that takes the attribute set itself and returns a string - `outPath` must be a string - This includes [derivations](./derivations.md) or [flake inputs](@docroot@/command-ref/new-cli/nix3-flake.md#flake-inputs) (experimental). + This includes [derivation expressions](./derivations.md) or [flake inputs](@docroot@/command-ref/new-cli/nix3-flake.md#flake-inputs) (experimental). A string interpolates to itself. diff --git a/doc/manual/source/protocols/derivation-aterm.md b/doc/manual/source/protocols/derivation-aterm.md index 1ba757ae024..99e3c2be630 100644 --- a/doc/manual/source/protocols/derivation-aterm.md +++ b/doc/manual/source/protocols/derivation-aterm.md @@ -1,6 +1,8 @@ # Derivation "ATerm" file format -For historical reasons, [derivations](@docroot@/glossary.md#gloss-store-derivation) are stored on-disk in [ATerm](https://homepages.cwi.nl/~daybuild/daily-books/technology/aterm-guide/aterm-guide.html) format. +For historical reasons, [store derivations][store derivation] are stored on-disk in [ATerm](https://homepages.cwi.nl/~daybuild/daily-books/technology/aterm-guide/aterm-guide.html) format. + +## The ATerm format used Derivations are serialised in one of the following formats: @@ -17,3 +19,20 @@ Derivations are serialised in one of the following formats: The only `version-string`s that are in use today are for [experimental features](@docroot@/development/experimental-features.md): - `"xp-dyn-drv"` for the [`dynamic-derivations`](@docroot@/development/experimental-features.md#xp-feature-dynamic-derivations) experimental feature. + +## Use for encoding to store object + +When derivation is encoded to a [store object] we make the following choices: + +- The store path name is the derivation name with `.drv` suffixed at the end + + Indeed, the ATerm format above does *not* contain the name of the derivation, on the assumption that a store path will also be provided out-of-band. + +- The derivation is content-addressed using the ["Text" method] of content-addressing derivations + +Currently we always encode derivations to store object using the ATerm format (and the previous two choices), +but we reserve the option to encode new sorts of derivations differently in the future. + +[store derivation]: @docroot@/glossary.md#gloss-store-derivation +[store object]: @docroot@/glossary.md#gloss-store-object +["Text" method]: @docroot@/store/store-object/content-address.md#method-text diff --git a/doc/manual/source/protocols/json/store-object-info.md b/doc/manual/source/protocols/json/store-object-info.md index 6b4f4843711..b7348538c35 100644 --- a/doc/manual/source/protocols/json/store-object-info.md +++ b/doc/manual/source/protocols/json/store-object-info.md @@ -41,10 +41,10 @@ In other words, the same store object residing in different store could have dif * `deriver`: - If known, the path to the [derivation] from which this store object was produced. + If known, the path to the [store derivation] from which this store object was produced. Otherwise `null`. - [derivation]: @docroot@/glossary.md#gloss-store-derivation + [store derivation]: @docroot@/glossary.md#gloss-store-derivation * `registrationTime` (optional): diff --git a/doc/manual/source/release-notes/rl-0.8.md b/doc/manual/source/release-notes/rl-0.8.md index 626c0c92b79..5ba6e0e7217 100644 --- a/doc/manual/source/release-notes/rl-0.8.md +++ b/doc/manual/source/release-notes/rl-0.8.md @@ -39,29 +39,29 @@ Nix 0.8 has the following improvements: notion of “closure store expressions” is gone (and so is the notion of “successors”); the file system references of a store path are now just stored in the database. - + For instance, given any store path, you can query its closure: - + $ nix-store -qR $(which firefox) ... lots of paths ... - + Also, Nix now remembers for each store path the derivation that built it (the “deriver”): - + $ nix-store -qR $(which firefox) /nix/store/4b0jx7vq80l9aqcnkszxhymsf1ffa5jd-firefox-1.0.1.drv - + So to see the build-time dependencies, you can do - + $ nix-store -qR $(nix-store -qd $(which firefox)) - + or, in a nicer format: - + $ nix-store -q --tree $(nix-store -qd $(which firefox)) - + File system references are also stored in reverse. For instance, you can query all paths that directly or indirectly use a certain Glibc: - + $ nix-store -q --referrers-closure \ /nix/store/8lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4 @@ -92,28 +92,28 @@ Nix 0.8 has the following improvements: - `nix-channel` has new operations `--list` and `--remove`. - New ways of installing components into user environments: - + - Copy from another user environment: - + $ nix-env -i --from-profile .../other-profile firefox - + - Install a store derivation directly (bypassing the Nix expression language entirely): - + $ nix-env -i /nix/store/z58v41v21xd3...-aterm-2.3.1.drv - + (This is used to implement `nix-install-package`, which is therefore immune to evolution in the Nix expression language.) - + - Install an already built store path directly: - + $ nix-env -i /nix/store/hsyj5pbn0d9i...-aterm-2.3.1 - + - Install the result of a Nix expression specified as a command-line argument: - + $ nix-env -f .../i686-linux.nix -i -E 'x: x.firefoxWrapper' - + The difference with the normal installation mode is that `-E` does not use the `name` attributes of derivations. Therefore, this can be used to disambiguate multiple derivations with the @@ -127,7 +127,7 @@ Nix 0.8 has the following improvements: - Implemented a concurrent garbage collector. It is now always safe to run the garbage collector, even if other Nix operations are happening simultaneously. - + However, there can still be GC races if you use `nix-instantiate` and `nix-store --realise` directly to build things. To prevent races, use the @@ -147,13 +147,13 @@ Nix 0.8 has the following improvements: - The behaviour of the garbage collector can be changed globally by setting options in `/nix/etc/nix/nix.conf`. - + - `gc-keep-derivations` specifies whether deriver links should be followed when searching for live paths. - + - `gc-keep-outputs` specifies whether outputs of derivations should be followed when searching for live paths. - + - `env-keep-derivations` specifies whether user environments should store the paths of derivations when they are added (thus keeping the derivations alive). diff --git a/doc/manual/source/release-notes/rl-2.0.md b/doc/manual/source/release-notes/rl-2.0.md index 9f6d4aa8323..aad0de21189 100644 --- a/doc/manual/source/release-notes/rl-2.0.md +++ b/doc/manual/source/release-notes/rl-2.0.md @@ -8,13 +8,13 @@ The following incompatible changes have been made: It has been superseded by the binary cache substituter mechanism since several years. As a result, the following programs have been removed: - + - `nix-pull` - + - `nix-generate-patches` - + - `bsdiff` - + - `bspatch` - The “copy from other stores” substituter mechanism @@ -58,26 +58,26 @@ This release has the following new features: `nix-build`, `nix-shell -p`, `nix-env -qa`, `nix-instantiate --eval`, `nix-push` and `nix-copy-closure`. It has the following major features: - + - Unlike the legacy commands, it has a consistent way to refer to packages and package-like arguments (like store paths). For example, the following commands all copy the GNU Hello package to a remote machine: - + nix copy --to ssh://machine nixpkgs.hello - + nix copy --to ssh://machine /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10 - + nix copy --to ssh://machine '(with import {}; hello)' - + By contrast, `nix-copy-closure` only accepted store paths as arguments. - + - It is self-documenting: `--help` shows all available command-line arguments. If `--help` is given after a subcommand, it shows examples for that subcommand. `nix --help-config` shows all configuration options. - + - It is much less verbose. By default, it displays a single-line progress indicator that shows how many packages are left to be built or downloaded, and (if there are running builds) the most @@ -85,7 +85,7 @@ This release has the following new features: last few lines of builder output. The full build log can be retrieved using `nix log`. - + - It [provides](https://github.com/NixOS/nix/commit/b8283773bd64d7da6859ed520ee19867742a03ba) all `nix.conf` configuration options as command line flags. For @@ -93,122 +93,122 @@ This release has the following new features: http-connections 100` you can write `--http-connections 100`. Boolean options can be written as `--foo` or `--no-foo` (e.g. `--no-auto-optimise-store`). - + - Many subcommands have a `--json` flag to write results to stdout in JSON format. - + > **Warning** - > + > > Please note that the `nix` command is a work in progress and the > interface is subject to change. - + It provides the following high-level (“porcelain”) subcommands: - + - `nix build` is a replacement for `nix-build`. - + - `nix run` executes a command in an environment in which the specified packages are available. It is (roughly) a replacement for `nix-shell -p`. Unlike that command, it does not execute the command in a shell, and has a flag (`-c`) that specifies the unquoted command line to be executed. - + It is particularly useful in conjunction with chroot stores, allowing Linux users who do not have permission to install Nix in `/nix/store` to still use binary substitutes that assume `/nix/store`. For example, - + nix run --store ~/my-nix nixpkgs.hello -c hello --greeting 'Hi everybody!' - + downloads (or if not substitutes are available, builds) the GNU Hello package into `~/my-nix/nix/store`, then runs `hello` in a mount namespace where `~/my-nix/nix/store` is mounted onto `/nix/store`. - + - `nix search` replaces `nix-env -qa`. It searches the available packages for occurrences of a search string in the attribute name, package name or description. Unlike `nix-env -qa`, it has a cache to speed up subsequent searches. - + - `nix copy` copies paths between arbitrary Nix stores, generalising `nix-copy-closure` and `nix-push`. - + - `nix repl` replaces the external program `nix-repl`. It provides an interactive environment for evaluating and building Nix expressions. Note that it uses `linenoise-ng` instead of GNU Readline. - + - `nix upgrade-nix` upgrades Nix to the latest stable version. This requires that Nix is installed in a profile. (Thus it won’t work on NixOS, or if it’s installed outside of the Nix store.) - + - `nix verify` checks whether store paths are unmodified and/or “trusted” (see below). It replaces `nix-store --verify` and `nix-store --verify-path`. - + - `nix log` shows the build log of a package or path. If the build log is not available locally, it will try to obtain it from the configured substituters (such as [cache.nixos.org](https://cache.nixos.org/), which now provides build logs). - + - `nix edit` opens the source code of a package in your editor. - + - `nix eval` replaces `nix-instantiate --eval`. - + - `nix why-depends` shows why one store path has another in its closure. This is primarily useful to finding the causes of closure bloat. For example, - + nix why-depends nixpkgs.vlc nixpkgs.libdrm.dev - + shows a chain of files and fragments of file contents that cause the VLC package to have the “dev” output of `libdrm` in its closure — an undesirable situation. - + - `nix path-info` shows information about store paths, replacing `nix-store -q`. A useful feature is the option `--closure-size` (`-S`). For example, the following command show the closure sizes of every path in the current NixOS system closure, sorted by size: - + nix path-info -rS /run/current-system | sort -nk2 - + - `nix optimise-store` replaces `nix-store --optimise`. The main difference is that it has a progress indicator. - + A number of low-level (“plumbing”) commands are also available: - + - `nix ls-store` and `nix ls-nar` list the contents of a store path or NAR file. The former is primarily useful in conjunction with remote stores, e.g. - + nix ls-store --store https://cache.nixos.org/ -lR /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10 - + lists the contents of path in a binary cache. - + - `nix cat-store` and `nix cat-nar` allow extracting a file from a store path or NAR file. - + - `nix dump-path` writes the contents of a store path to stdout in NAR format. This replaces `nix-store --dump`. - + - `nix show-derivation` displays a store derivation in JSON format. This is an alternative to `pp-aterm`. - + - `nix add-to-store` replaces `nix-store --add`. - + - `nix sign-paths` signs store paths. - + - `nix copy-sigs` copies signatures from one store to another. - + - `nix show-config` shows all configuration options and their current values. @@ -224,11 +224,11 @@ This release has the following new features: `nix-copy-closure`, `nix-push` and substitution are all instances of the general notion of copying paths between different kinds of Nix stores. - + Stores are specified using an URI-like syntax, e.g. or . The following store types are supported: - + - `LocalStore` (stori URI `local` or an absolute path) and the misnamed `RemoteStore` (`daemon`) provide access to a local Nix store, the latter via the Nix daemon. You can use `auto` or the @@ -236,63 +236,63 @@ This release has the following new features: whether you have write permission to the Nix store. It is no longer necessary to set the `NIX_REMOTE` environment variable to use the Nix daemon. - + As noted above, `LocalStore` now supports chroot builds, allowing the “physical” location of the Nix store (e.g. `/home/alice/nix/store`) to differ from its “logical” location (typically `/nix/store`). This allows non-root users to use Nix while still getting the benefits from prebuilt binaries from [cache.nixos.org](https://cache.nixos.org/). - + - `BinaryCacheStore` is the abstract superclass of all binary cache stores. It supports writing build logs and NAR content listings in JSON format. - + - `HttpBinaryCacheStore` (`http://`, `https://`) supports binary caches via HTTP or HTTPS. If the server supports `PUT` requests, it supports uploading store paths via commands such as `nix copy`. - + - `LocalBinaryCacheStore` (`file://`) supports binary caches in the local filesystem. - + - `S3BinaryCacheStore` (`s3://`) supports binary caches stored in Amazon S3, if enabled at compile time. - + - `LegacySSHStore` (`ssh://`) is used to implement remote builds and `nix-copy-closure`. - + - `SSHStore` (`ssh-ng://`) supports arbitrary Nix operations on a remote machine via the same protocol used by `nix-daemon`. - Security has been improved in various ways: - + - Nix now stores signatures for local store paths. When paths are copied between stores (e.g., copied from a binary cache to a local store), signatures are propagated. - + Locally-built paths are signed automatically using the secret keys specified by the `secret-key-files` store option. Secret/public key pairs can be generated using `nix-store --generate-binary-cache-key`. - + In addition, locally-built store paths are marked as “ultimately trusted”, but this bit is not propagated when paths are copied between stores. - + - Content-addressable store paths no longer require signatures — they can be imported into a store by unprivileged users even if they lack signatures. - + - The command `nix verify` checks whether the specified paths are trusted, i.e., have a certain number of trusted signatures, are ultimately trusted, or are content-addressed. - + - Substitutions from binary caches [now](https://github.com/NixOS/nix/commit/ecbc3fedd3d5bdc5a0e1a0a51b29062f2874ac8b) require signatures by default. This was already the case on NixOS. - + - In Linux sandbox builds, we [now](https://github.com/NixOS/nix/commit/eba840c8a13b465ace90172ff76a0db2899ab11b) use `/build` instead of `/tmp` as the temporary build directory. @@ -309,7 +309,7 @@ This release has the following new features: hash or commit hash is specified. For example, calls to `builtins.fetchGit` are only allowed if a `rev` attribute is specified. - + The goal of this feature is to enable true reproducibility and traceability of builds (including NixOS system configurations) at the evaluation level. For example, in the future, `nixos-rebuild` @@ -367,21 +367,21 @@ This release has the following new features: log will be shown if a build fails. - Networking has been improved: - + - HTTP/2 is now supported. This makes binary cache lookups [much more efficient](https://github.com/NixOS/nix/commit/90ad02bf626b885a5dd8967894e2eafc953bdf92). - + - We now retry downloads on many HTTP errors, making binary caches substituters more resilient to temporary failures. - + - HTTP credentials can now be configured via the standard `netrc` mechanism. - + - If S3 support is enabled at compile time, URIs are [supported](https://github.com/NixOS/nix/commit/9ff9c3f2f80ba4108e9c945bbfda2c64735f987b) in all places where Nix allows URIs. - + - Brotli compression is now supported. In particular, [cache.nixos.org](https://cache.nixos.org/) build logs are now compressed using Brotli. @@ -431,9 +431,9 @@ The Nix language has the following new features: - Derivation attributes can now reference the outputs of the derivation using the `placeholder` builtin function. For example, the attribute - + configureFlags = "--prefix=${placeholder "out"} --includedir=${placeholder "dev"}"; - + will cause the `configureFlags` environment variable to contain the actual store paths corresponding to the `out` and `dev` outputs. @@ -444,7 +444,7 @@ The following builtin functions are new or extended: Nixpkgs, which fetches at build time and cannot be used to fetch Nix expressions during evaluation. A typical use case is to import external NixOS modules from your configuration, e.g. - + imports = [ (builtins.fetchGit https://github.com/edolstra/dwarffs + "/module.nix") ]; - Similarly, `builtins.fetchMercurial` allows you to fetch Mercurial @@ -485,7 +485,7 @@ The Nix build environment has the following changes: builder via the file `.attrs.json` in the builder’s temporary directory. This obviates the need for `passAsFile` since JSON files have no size restrictions, unlike process environments. - + [As a convenience to Bash builders](https://github.com/NixOS/nix/commit/2d5b1b24bf70a498e4c0b378704cfdb6471cc699), Nix writes a script named `.attrs.sh` to the builder’s directory diff --git a/doc/manual/source/store/building.md b/doc/manual/source/store/building.md new file mode 100644 index 00000000000..79808273edc --- /dev/null +++ b/doc/manual/source/store/building.md @@ -0,0 +1,97 @@ +# Building + +## Normalizing derivation inputs + +- Each input must be [realised] prior to building the derivation in question. + +[realised]: @docroot@/glossary.md#gloss-realise + +- Once this is done, the derivation is *normalized*, replacing each input deriving path with its store path, which we now know from realising the input. + +## Builder Execution + +The [`builder`](./drv.md#builder) is executed as follows: + +- A temporary directory is created under the directory specified by + `TMPDIR` (default `/tmp`) where the build will take place. The + current directory is changed to this directory. + +- The environment is cleared and set to the derivation attributes, as + specified above. + +- In addition, the following variables are set: + + - `NIX_BUILD_TOP` contains the path of the temporary directory for + this build. + + - Also, `TMPDIR`, `TEMPDIR`, `TMP`, `TEMP` are set to point to the + temporary directory. This is to prevent the builder from + accidentally writing temporary files anywhere else. Doing so + might cause interference by other processes. + + - `PATH` is set to `/path-not-set` to prevent shells from + initialising it to their built-in default value. + + - `HOME` is set to `/homeless-shelter` to prevent programs from + using `/etc/passwd` or the like to find the user's home + directory, which could cause impurity. Usually, when `HOME` is + set, it is used as the location of the home directory, even if + it points to a non-existent path. + + - `NIX_STORE` is set to the path of the top-level Nix store + directory (typically, `/nix/store`). + + - `NIX_ATTRS_JSON_FILE` & `NIX_ATTRS_SH_FILE` if `__structuredAttrs` + is set to `true` for the derivation. A detailed explanation of this + behavior can be found in the + [section about structured attrs](@docroot@/language/advanced-attributes.md#adv-attr-structuredAttrs). + + - For each output declared in `outputs`, the corresponding + environment variable is set to point to the intended path in the + Nix store for that output. Each output path is a concatenation + of the cryptographic hash of all build inputs, the `name` + attribute and the output name. (The output name is omitted if + it’s `out`.) + +- If an output path already exists, it is removed. Also, locks are + acquired to prevent multiple Nix instances from performing the same + build at the same time. + +- A log of the combined standard output and error is written to + `/nix/var/log/nix`. + +- The builder is executed with the arguments specified by the + attribute `args`. If it exits with exit code 0, it is considered to + have succeeded. + +- The temporary directory is removed (unless the `-K` option was + specified). + +## Processing outputs + +If the builder exited successfully, the following steps happen in order to turn the output directories left behind by the builder into proper store objects: + +- **Normalize the file permissions** + + Nix sets the last-modified timestamp on all files + in the build result to 1 (00:00:01 1/1/1970 UTC), sets the group to + the default group, and sets the mode of the file to 0444 or 0555 + (i.e., read-only, with execute permission enabled if the file was + originally executable). Any possible `setuid` and `setgid` + bits are cleared. + + > **Note** + > + > Setuid and setgid programs are not currently supported by Nix. + > This is because the Nix archives used in deployment have no concept of ownership information, + > and because it makes the build result dependent on the user performing the build. + +- **Calculate the references** + + Nix scans each output path for + references to input paths by looking for the hash parts of the input + paths. Since these are potential runtime dependencies, Nix registers + them as dependencies of the output paths. + + Nix also scans for references to other outputs' paths in the same way, because outputs are allowed to refer to each other. + If the outputs' references to each other form a cycle, this is an error, because the references of store objects much be acyclic. diff --git a/doc/manual/source/store/drv.md b/doc/manual/source/store/drv.md new file mode 100644 index 00000000000..b359f85fc8d --- /dev/null +++ b/doc/manual/source/store/drv.md @@ -0,0 +1,310 @@ +# Store Derivation and Deriving Path + +Besides functioning as a [content addressed store] the Nix store layer works as a [build system]. +Other system (like Git or IPFS) also store and transfer immutable data, but they don't concern themselves with *how* that data was created. + +This is where Nix distinguishes itself. +*Derivations* represent individual build steps, and *deriving paths* are needed to refer to the *outputs* of those build steps before they are built. + + +## Store Derivation {#store-derivation} + +A derivation is a specification for running an executable on precisely defined input files to repeatably produce output files at uniquely determined file system paths. + +A derivation consists of: + + - A name + + - A set of [*inputs*][inputs], a set of [deriving paths][deriving path] + + - A map of [*outputs*][outputs], from names to other data + + - The ["system" type][system] (e.g. `x86_64-linux`) where the executable is to run. + + - The [process creation fields]: to spawn the arbitrary process which will perform the build step. + +[store derivation]: #store-derivation +[inputs]: #inputs +[input]: #inputs +[outputs]: #outputs +[output]: #outputs +[process creation fields]: #process-creation-fields +[builder]: #builder +[args]: #args +[env]: #env +[system]: #system + +### Referencing derivations {#derivation-path} + +Derivations are always referred to by the [store path] of the store object they are encoded to. +See the [encoding section](#derivation-encoding) for more details on how this encoding works, and thus what exactly what store path we would end up with for a given derivation. + +The store path of the store object which encodes a derivation is often called a *derivation path* for brevity. + +## Deriving path {#deriving-path} + +Deriving paths are a way to refer to [store objects][store object] that may or may not yet be [realised][realise]. +There are two forms: + +- [*constant*]{#deriving-path-constant}: just a [store path]. + It can be made [valid][validity] by copying it into the store: from the evaluator, command line interface or another store. + +- [*output*]{#deriving-path-output}: a pair of a [store path] to a [store derivation] and an [output] name. + +In pseudo code: + +```typescript +type OutputName = String; + +type ConstantPath = { + path: StorePath; +}; + +type OutputPath = { + drvPath: StorePath; + output: OutputName; +}; + +type DerivingPath = ConstantPath | OutputPath; +``` + +Deriving paths are necessary because, in general and particularly for [content-addressed derivations][content-addressed derivation], the [store path] of an [output] is not known in advance. +We can use an output deriving path to refer to such an out, instead of the store path which we do not yet know. + +[deriving path]: #deriving-path +[validity]: @docroot@/glossary.md#gloss-validity + +## Parts of a derivation + +A derivation is constructed from the parts documented in the following subsections. + +### Inputs {#inputs} + +The inputs are a set of [deriving paths][deriving path], refering to all store objects needed in order to perform this build step. + +The [process creation fields] will presumably include many [store paths][store path]: + + - The path to the executable normally starts with a store path + - The arguments and environment variables likely contain many other store paths. + +But rather than somehow scanning all the other fields for inputs, Nix requires that all inputs be explicitly collected in the inputs field. It is instead the responsibility of the creator of a derivation (e.g. the evaluator) to ensure that every store object referenced in another field (e.g. referenced by store path) is included in this inputs field. + +### Outputs {#outputs} + +The outputs are the derivations are the [store objects][store object] it is obligated to produce. + +Outputs are assigned names, and also consistent of other information based on the type of derivation. + +Output names can be any string which is also a valid [store path] name. +The store path of the output store object (also called an [output path] for short), has a name based on the derivation name and the output name. +In the general case, store paths have name `derivationName + "-" + outputName`. +However, an output named "out" has a store path with name is just the derivation name. +This is to allow derivations with a single output to avoid a superfluous `"-${outputName}"` in their single output's name when no disambiguation is needed. + +> **Example** +> +> A derivation is named `hello`, and has two outputs, `out`, and `dev` +> +> - The derivation's path will be: `/nix/store/-hello.drv`. +> +> - The store path of `out` will be: `/nix/store/-hello`. +> +> - The store path of `dev` will be: `/nix/store/-hello-dev`. + +### System {#system} + +The system type on which the [`builder`](#attr-builder) executable is meant to be run. + +A necessary condition for Nix to schedule a given derivation on some Nix instance is for the "system" of that derivation to match that instance's [`system` configuration option]. + +By putting the `system` in each derivation, Nix allows *heterogenous* build plans, where not all steps can be run on the same machine or same sort of machine. +Nix can schedule builds such that it automatically builds on other platforms by [forwarding build requests](@docroot@/advanced-topics/distributed-builds.md) to other Nix instances. + +[`system` configuration option]: @docroot@/command-ref/conf-file.md#conf-system + +[content-addressed derivation]: @docroot@/glossary.md#gloss-content-addressed-derivation +[realise]: @docroot@/glossary.md#gloss-realise +[store object]: @docroot@/store/store-object.md +[store path]: @docroot@/store/store-path.md + +### Process creation fields {#process-creation-fields} + +These are the three fields which describe how to spawn the process which (along with any of its own child processes) will perform the build. +You may note that this has everything needed for an `execve` system call. + +#### Builder {#builder} + +This is the path to an executable that will perform the build and produce the [outputs]. + +#### Arguments {#args} + +Command-line arguments to be passed to the [`builder`](#builder) executable. + +Note that these are the arguments after the first argument. +The first argument passed to the `builder` will be the value of `builder`, as per the usual convention on Unix. +See [Wikipedia](https://en.wikipedia.org/wiki/Argv) for details. + +#### Environment Variables {#env} + +Environment variables which will be passed to the [builder](#builder) executable. + +### Placeholders + +Placeholders are opaque values used within the [process creation fields] to [store objects] for which we don't yet know [store path]s. +They are strings in the form `/` that are embedded anywhere within the strings of those fields, and we are [considering](https://github.com/NixOS/nix/issues/12361) to add store-path-like placeholders. + +> **Note** +> +> Output Deriving Path exist to solve the same problem as placeholders --- that is, referring to store objects for which we don't yet know a store path. +> They also have a string syntax with `^`, [described in the encoding section](#deriving-path-encoding). +> We could use that syntax instead of `/` for placeholders, but its human-legibility would cause problems. + +There are two types of placeholder, corresponding to the two cases where this problem arises: + +- [Output placeholder]{#output-placeholder}: + + This is a placeholder for a derivation's own output. + +- [Input placeholder]{#input-placeholder}: + + This is a placeholder to a derivation's non-constant [input], + i.e. an input that is an [output derived path]. + +> **Explanation** +> +> In general, we need to realise [realise] a [store object] in order to be sure to have a store object for it. +> But for these two cases this is either impossible or impractical: +> +> - In the output case this is impossible: +> +> We cannot build the output until we have a correct derivation, and we cannot have a correct derivation (without using placeholders) until we have the output path. +> +> - In the input case this is impractical: +> +> If we always build a dependency first, and then refer to its output by store path, we would lose the ability for a derivation graph to describe an entire build plan consisting of multiple build steps. + +## Encoding + +### Derivation {#derivation-encoding} + +There are two formats, documented separately: + +- The legacy ["ATerm" format](@docroot@/protocols/derivation-aterm.md) + +- The experimental, currently under development and changing [JSON format](@docroot@/protocols/json/derivation.md) + +Every derivation has a canonical choice of encoding used to serialize it to a store object. +This ensures that there is a canonical [store path] used to refer to the derivation, as described in [Referencing derivations](#derivation-path). + +> **Note** +> +> Currently, the canonical encoding for every derivation is the "ATerm" format, +> but this is subject to change for types derivations which are not yet stable. + +Regardless of the format used, when serializing a derivation to a store object, that store object will be content-addressed. + +In the common case, the inputs to store objects are either: + + - [constant deriving paths](#deriving-path-constant) for content-addressed source objects, which are "initial inputs" rather than the outputs of some other derivation + + - the outputs of other derivations + +If those other derivations *also* abide by this common case (and likewise for transitive inputs), then the entire closure of the serialized derivation will be content-addressed. + +### Deriving Path {#deriving-path-encoding} + +- *constant* + + Constant deriving paths are encoded simply as the underlying store path is. + Thus, we see that every encoded store path is also a valid encoded (constant) deriving path. + +- *output* + + Output deriving paths are encoded by + + - encoding of a store path referring to a derivation + + - a `^` separator (or `!` in some legacy contexts) + + - the name of an output of the previously referred derivation + + > **Example** + > + > ``` + > /nix/store/lxrn8v5aamkikg6agxwdqd1jz7746wz4-firefox-98.0.2.drv^out + > ``` + > + > This parses like so: + > + > ``` + > /nix/store/lxrn8v5aamkikg6agxwdqd1jz7746wz4-firefox-98.0.2.drv^out + > |------------------------------------------------------------| |-| + > store path (usual encoding) output name + > |--| + > note the ".drv" + > ``` + +## Extending the model to be higher-order + +**Experimental feature**: [`dynamic-derivations`](@docroot@/development/experimental-features.md#xp-feature-dynamic-derivations) + +So far, we have used store paths to refer to derivations. +That works because we've implicitly assumed that all derivations are created *statically* --- created by some mechanism out of band, and then manually inserted into the store. +But what if derivations could also be created dynamically within Nix? +In other words, what if derivations could be the outputs of other derivations? + +:::{.note} +In the parlance of "Build Systems à la carte", we are generalizing the Nix store layer to be a "Monadic" instead of "Applicative" build system. +::: + +How should we refer to such derivations? +A deriving path works, the same as how we refer to other derivation outputs. +But what about a dynamic derivations output? +(i.e. how do we refer to the output of an output of a derivation?) +For that we need to generalize the definition of deriving path, replacing the store path used to refer to the derivation with a nested deriving path: + +```diff + type OutputPath = { +- drvPath: StorePath; ++ drvPath: DerivingPath; + output: OutputName; + }; +``` + +Now, the `drvPath` field of `OutputPath` is itself a `DerivingPath` instead of a `StorePath`. + +With that change, here is updated definition: + +```typescript +type OutputName = String; + +type ConstantPath = { + path: StorePath; +}; + +type OutputPath = { + drvPath: DerivingPath; + output: OutputName; +}; + +type DerivingPath = ConstantPath | OutputPath; +``` + +Under this extended model, `DerivingPath`s are thus inductively built up from a root `ConstantPath`, wrapped with zero or more outer `OutputPath`s. + +### Encoding {#deriving-path-encoding} + +The encoding is adjusted in the natural way, encoding the `drv` field recursively using the same deriving path encoding. +The result of this is that it is possible to have a chain of `^` at the end of the final string, as opposed to just a single one. + +> **Example** +> +> ``` +> /nix/store/lxrn8v5aamkikg6agxwdqd1jz7746wz4-firefox-98.0.2.drv^foo.drv^bar.drv^out +> |----------------------------------------------------------------------------| |-| +> inner deriving path (usual encoding) output name +> |--------------------------------------------------------------------| |-----| +> even more inner deriving path (usual encoding) output name +> |------------------------------------------------------------| |-----| +> innermost constant store path (usual encoding) output name +> ``` diff --git a/src/libcmd/misc-store-flags.cc b/src/libcmd/misc-store-flags.cc index 06552c03223..664ceb35f5f 100644 --- a/src/libcmd/misc-store-flags.cc +++ b/src/libcmd/misc-store-flags.cc @@ -120,7 +120,7 @@ Args::Flag contentAddressMethod(ContentAddressMethod * method) - [`text`](@docroot@/store/store-object/content-address.md#method-text): Like `flat`, but used for - [derivations](@docroot@/glossary.md#store-derivation) serialized in store object and + [derivations](@docroot@/glossary.md#gloss-store-derivation) serialized in store object and [`builtins.toFile`](@docroot@/language/builtins.html#builtins-toFile). For advanced use-cases only; for regular usage prefer `nar` and `flat`. diff --git a/src/libexpr/primops.cc b/src/libexpr/primops.cc index e6f6f1dda24..51d2991e799 100644 --- a/src/libexpr/primops.cc +++ b/src/libexpr/primops.cc @@ -1595,9 +1595,13 @@ static RegisterPrimOp primop_placeholder({ .name = "placeholder", .args = {"output"}, .doc = R"( - Return a placeholder string for the specified *output* that will be - substituted by the corresponding output path at build time. Typical - outputs would be `"out"`, `"bin"` or `"dev"`. + Return at + [output placeholder string](@docroot@/store/drv.md#output-placeholder) + for the specified *output* that will be substituted by the corresponding + [output path](@docroot@/glossary.md#gloss-output-path) + at build time. + + Typical outputs would be `"out"`, `"bin"` or `"dev"`. )", .fun = prim_placeholder, }); @@ -2135,12 +2139,15 @@ static RegisterPrimOp primop_outputOf({ .name = "__outputOf", .args = {"derivation-reference", "output-name"}, .doc = R"( - Return the output path of a derivation, literally or using a placeholder if needed. + Return the output path of a derivation, literally or using an + [input placeholder string](@docroot@/store/drv.md#input-placeholder) + if needed. If the derivation has a statically-known output path (i.e. the derivation output is input-addressed, or fixed content-addresed), the output path will just be returned. - But if the derivation is content-addressed or if the derivation is itself not-statically produced (i.e. is the output of another derivation), a placeholder will be returned instead. + But if the derivation is content-addressed or if the derivation is itself not-statically produced (i.e. is the output of another derivation), an input placeholder will be returned instead. - *`derivation reference`* must be a string that may contain a regular store path to a derivation, or may be a placeholder reference. If the derivation is produced by a derivation, you must explicitly select `drv.outPath`. + *`derivation reference`* must be a string that may contain a regular store path to a derivation, or may be an input placeholder reference. + If the derivation is produced by a derivation, you must explicitly select `drv.outPath`. This primop can be chained arbitrarily deeply. For instance, @@ -2150,9 +2157,9 @@ static RegisterPrimOp primop_outputOf({ "out" ``` - will return a placeholder for the output of the output of `myDrv`. + will return a input placeholder for the output of the output of `myDrv`. - This primop corresponds to the `^` sigil for derivable paths, e.g. as part of installable syntax on the command line. + This primop corresponds to the `^` sigil for [deriving paths](@docroot@/glossary.md#gloss-deriving-paths), e.g. as part of installable syntax on the command line. )", .fun = prim_outputOf, .experimentalFeature = Xp::DynamicDerivations, diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh index ff3df46ba9e..e9a18016480 100644 --- a/src/libstore/globals.hh +++ b/src/libstore/globals.hh @@ -189,7 +189,7 @@ public: this, SYSTEM, "system", R"( The system type of the current Nix installation. - Nix will only build a given [derivation](@docroot@/language/derivations.md) locally when its `system` attribute equals any of the values specified here or in [`extra-platforms`](#conf-extra-platforms). + Nix will only build a given [store derivation](@docroot@/glossary.md#gloss-store-derivation) locally when its `system` attribute equals any of the values specified here or in [`extra-platforms`](#conf-extra-platforms). The default value is set when Nix itself is compiled for the system it will run on. The following system types are widely used, as Nix is actively supported on these platforms: @@ -825,7 +825,7 @@ public: R"( System types of executables that can be run on this machine. - Nix will only build a given [derivation](@docroot@/language/derivations.md) locally when its `system` attribute equals any of the values specified here or in the [`system` option](#conf-system). + Nix will only build a given [store derivation](@docroot@/glossary.md#gloss-store-derivation) locally when its `system` attribute equals any of the values specified here or in the [`system` option](#conf-system). Setting this can be useful to build derivations locally on compatible machines: - `i686-linux` executables can be run on `x86_64-linux` machines (set by default) diff --git a/src/nix/derivation-show.cc b/src/nix/derivation-show.cc index bf637246d83..5a07f58e6dc 100644 --- a/src/nix/derivation-show.cc +++ b/src/nix/derivation-show.cc @@ -1,5 +1,5 @@ -// FIXME: integrate this with nix path-info? -// FIXME: rename to 'nix store derivation show' or 'nix debug derivation show'? +// FIXME: integrate this with `nix path-info`? +// FIXME: rename to 'nix store derivation show'? #include "command.hh" #include "common-args.hh" diff --git a/src/nix/search.md b/src/nix/search.md index f65ac9b1748..d355a7764dc 100644 --- a/src/nix/search.md +++ b/src/nix/search.md @@ -62,8 +62,8 @@ R""( # Description -`nix search` searches [*installable*](./nix.md#installables) (which can be evaluated, that is, a -flake or Nix expression, but not a store path or store derivation path) for packages whose name or description matches all of the +`nix search` searches [*installable*](./nix.md#installables) that can be evaluated, that is, a +flake or Nix expression, but not a [store path] or [deriving path]) for packages whose name or description matches all of the regular expressions *regex*. For each matching package, It prints the full attribute name (from the root of the [installable](./nix.md#installables)), the version and the `meta.description` field, highlighting the substrings that @@ -75,6 +75,9 @@ it avoids highlighting the entire name and description of every package. > Note that in this context, `^` is the regex character to match the beginning of a string, *not* the delimiter for > [selecting a derivation output](@docroot@/command-ref/new-cli/nix.md#derivation-output-selection). +[store path]: @docroot@/glossary.md#gloss-store-path +[deriving path]: @docroot@/glossary.md#gloss-deriving-path + # Flake output attributes If no flake output attribute is given, `nix search` searches for