From 1bc9257d7c5980fb048b519eeaa2a2b2e8925099 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 3 May 2023 15:36:13 +0200 Subject: [PATCH 01/13] reword description of how realisation works --- .../src/command-ref/nix-store/opt-common.md | 4 +- .../src/command-ref/nix-store/realise.md | 50 +++++++++---------- 2 files changed, 27 insertions(+), 27 deletions(-) diff --git a/doc/manual/src/command-ref/nix-store/opt-common.md b/doc/manual/src/command-ref/nix-store/opt-common.md index dd9a6bf21..104b20076 100644 --- a/doc/manual/src/command-ref/nix-store/opt-common.md +++ b/doc/manual/src/command-ref/nix-store/opt-common.md @@ -1,6 +1,6 @@ -# Options +# Command options -The following options are allowed for all `nix-store` operations, but may not always have an effect. +The following options are allowed for all operations in the `nix-store` command, but may not always have an effect. - [`--add-root`](#opt-add-root) *path* diff --git a/doc/manual/src/command-ref/nix-store/realise.md b/doc/manual/src/command-ref/nix-store/realise.md index c19aea75e..2881a69b3 100644 --- a/doc/manual/src/command-ref/nix-store/realise.md +++ b/doc/manual/src/command-ref/nix-store/realise.md @@ -8,33 +8,37 @@ # Description -The operation `--realise` essentially “builds” the specified store -paths. Realisation is a somewhat overloaded term: +Ensure that the given [store paths] are [valid]. - - If the store path is a *derivation*, realisation ensures that the - output paths of the derivation are [valid] (i.e., - the output path and its closure exist in the file system). This - can be done in several ways. First, it is possible that the - outputs are already valid, in which case we are done - immediately. Otherwise, there may be [substitutes] - that produce the outputs (e.g., by downloading them). Finally, the - outputs can be produced by running the build task described - by the derivation. +Realisation of a store path works as follows: - - If the store path is not a derivation, realisation ensures that the - specified path is valid (i.e., it and its closure exist in the file - system). If the path is already valid, we are done immediately. - Otherwise, the path and any missing paths in its closure may be - produced through substitutes. If there are no (successful) - substitutes, realisation fails. +- If the path is already valid, do nothing. +- If the path leads to a [store derivation]: + 1. Realise the store derivation file itself, as a regular store path. + 2. Realise its [output paths]: + - Try to fetch from [substituters] the [store objects] associated with the output paths in the store derivation's [closure]. + - With [content-addressed derivations] (experimental): Determine the output paths to realise by querying build certificates in the [Nix database]. + - For any store paths that cannot be substituted, produce the required store objects by first realising all outputs of the derivation's dependencies and then running the derivation's build instructions. +- Otherwise: Try to fetch the associated [store objects] in the paths' [closure] from the [substituters]. +If no substitutes are available and no store derivation is given, realisation fails. + +[store paths]: @docroot@/glossary.md#gloss-store-path [valid]: @docroot@/glossary.md#gloss-validity -[substitutes]: @docroot@/glossary.md#gloss-substitute +[store derivation]: @docroot@/glossary.md#gloss-store-derivation +[output paths]: @docroot@/glossary.md#gloss-output-path +[store objects]: @docroot@/glossary.md#gloss-store-object +[closure]: @docroot@/glossary.md#gloss-closure +[substituters]: @docroot@/command-ref/conf-file.md#conf-substituters +[content-addressed derivations]: @docroot@/contributing/experimental-features.md#xp-feature-ca-derivations +[Nix database]: @docroot@/glossary.md#gloss-nix-database -The output path of each derivation is printed on standard output. (For -non-derivations argument, the argument itself is printed.) +The resulting paths are printed on standard output. +For non-derivation arguments, the argument itself is printed. -The following flags are available: +{{#include ../status-build-failure.md}} + +# Options - `--dry-run`\ Print on standard error a description of what packages would be @@ -54,8 +58,6 @@ The following flags are available: previous build, the new output path is left in `/nix/store/name.check.` -{{#include ../status-build-failure.md}} - {{#include ./opt-common.md}} {{#include ../opt-common.md}} @@ -67,8 +69,6 @@ The following flags are available: This operation is typically used to build [store derivation]s produced by [`nix-instantiate`](@docroot@/command-ref/nix-instantiate.md): -[store derivation]: @docroot@/glossary.md#gloss-store-derivation - ```console $ nix-store --realise $(nix-instantiate ./test.nix) /nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1 From 315a11bcc9ce97cb25a41dcdfb4a859c7384f74b Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 21 Jun 2023 10:54:46 +0200 Subject: [PATCH 02/13] remove superfluous word --- doc/manual/src/command-ref/nix-store/realise.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/src/command-ref/nix-store/realise.md b/doc/manual/src/command-ref/nix-store/realise.md index 2881a69b3..f304dde2e 100644 --- a/doc/manual/src/command-ref/nix-store/realise.md +++ b/doc/manual/src/command-ref/nix-store/realise.md @@ -19,7 +19,7 @@ Realisation of a store path works as follows: - Try to fetch from [substituters] the [store objects] associated with the output paths in the store derivation's [closure]. - With [content-addressed derivations] (experimental): Determine the output paths to realise by querying build certificates in the [Nix database]. - For any store paths that cannot be substituted, produce the required store objects by first realising all outputs of the derivation's dependencies and then running the derivation's build instructions. -- Otherwise: Try to fetch the associated [store objects] in the paths' [closure] from the [substituters]. +- Otherwise: Try to fetch the associated [store objects] in the paths' [closure] from [substituters]. If no substitutes are available and no store derivation is given, realisation fails. From a57e0e8c5c1be81e9352499ac31dcfce87ca44be Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Tue, 27 Jun 2023 09:16:36 +0200 Subject: [PATCH 03/13] reword introductory sentence --- doc/manual/src/command-ref/nix-store/realise.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/src/command-ref/nix-store/realise.md b/doc/manual/src/command-ref/nix-store/realise.md index f304dde2e..00acee99c 100644 --- a/doc/manual/src/command-ref/nix-store/realise.md +++ b/doc/manual/src/command-ref/nix-store/realise.md @@ -10,7 +10,7 @@ Ensure that the given [store paths] are [valid]. -Realisation of a store path works as follows: +Each of *paths* is processed as follows: - If the path is already valid, do nothing. - If the path leads to a [store derivation]: From b7e9e2960566b8e21f4f69b6f222b945fababce7 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Tue, 27 Jun 2023 09:16:56 +0200 Subject: [PATCH 04/13] remove abstract description --- doc/manual/src/command-ref/nix-store/realise.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/manual/src/command-ref/nix-store/realise.md b/doc/manual/src/command-ref/nix-store/realise.md index 00acee99c..72dfa618c 100644 --- a/doc/manual/src/command-ref/nix-store/realise.md +++ b/doc/manual/src/command-ref/nix-store/realise.md @@ -8,7 +8,6 @@ # Description -Ensure that the given [store paths] are [valid]. Each of *paths* is processed as follows: From d50f116421f7c999748887955b2d3c2e8b934b28 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Tue, 27 Jun 2023 09:17:12 +0200 Subject: [PATCH 05/13] add reference link --- doc/manual/src/command-ref/nix-store/realise.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/src/command-ref/nix-store/realise.md b/doc/manual/src/command-ref/nix-store/realise.md index 72dfa618c..2028631d0 100644 --- a/doc/manual/src/command-ref/nix-store/realise.md +++ b/doc/manual/src/command-ref/nix-store/realise.md @@ -11,7 +11,7 @@ Each of *paths* is processed as follows: -- If the path is already valid, do nothing. +- If the path is already [valid], do nothing. - If the path leads to a [store derivation]: 1. Realise the store derivation file itself, as a regular store path. 2. Realise its [output paths]: From 0cd8f36644042b41516e86e527ebfb19faebcbc9 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 13 Jul 2023 22:17:51 +0200 Subject: [PATCH 06/13] add anchor to `builder` --- doc/manual/src/command-ref/nix-store/realise.md | 2 +- doc/manual/src/glossary.md | 2 +- doc/manual/src/language/derivations.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/manual/src/command-ref/nix-store/realise.md b/doc/manual/src/command-ref/nix-store/realise.md index 2028631d0..9dfe74277 100644 --- a/doc/manual/src/command-ref/nix-store/realise.md +++ b/doc/manual/src/command-ref/nix-store/realise.md @@ -17,7 +17,7 @@ Each of *paths* is processed as follows: 2. Realise its [output paths]: - Try to fetch from [substituters] the [store objects] associated with the output paths in the store derivation's [closure]. - With [content-addressed derivations] (experimental): Determine the output paths to realise by querying build certificates in the [Nix database]. - - For any store paths that cannot be substituted, produce the required store objects by first realising all outputs of the derivation's dependencies and then running the derivation's build instructions. + - For any store paths that cannot be substituted, produce the required store objects by first realising all outputs of the derivation's dependencies and then running the derivation's [`builder`](@docroot@/language/derivations.md#attr-builder) executable. - Otherwise: Try to fetch the associated [store objects] in the paths' [closure] from [substituters]. If no substitutes are available and no store derivation is given, realisation fails. diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index d950a4ca8..2fbb23311 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -33,7 +33,7 @@ Ensure a [store path] is [valid][validity]. - This means either running the `builder` executable as specified in the corresponding [derivation] or fetching a pre-built [store object] from a [substituter]. + This means either running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [derivation] or fetching a pre-built [store object] from a [substituter]. See [`nix-build`](./command-ref/nix-build.md) and [`nix-store --realise`](@docroot@/command-ref/nix-store/realise.md). diff --git a/doc/manual/src/language/derivations.md b/doc/manual/src/language/derivations.md index 043a38191..79a09122a 100644 --- a/doc/manual/src/language/derivations.md +++ b/doc/manual/src/language/derivations.md @@ -17,7 +17,7 @@ the attributes of which specify the inputs of the build. string. This is used as a symbolic name for the package by `nix-env`, and it is appended to the output paths of the derivation. - - There must be an attribute named `builder` that identifies the + - There must be an attribute named [`builder`]{#attr-builder} that identifies the program that is executed to perform the build. It can be either a derivation or a source (a local file reference, e.g., `./builder.sh`). From 6b3320ab05cefe73c21a469d077b277cff47733b Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 19 Jul 2023 09:27:36 +0200 Subject: [PATCH 07/13] mention remote builders Co-authored-by: Robert Hensing --- doc/manual/src/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index 2fbb23311..8f0b25c89 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -33,7 +33,7 @@ Ensure a [store path] is [valid][validity]. - This means either running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [derivation] or fetching a pre-built [store object] from a [substituter]. + This means either running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [derivation], or fetching a pre-built [store object] from a [substituter], or delegating to a [remote builder](@docroot@/advanced-topics/distributed-builds.html) and retrieving the outputs. See [`nix-build`](./command-ref/nix-build.md) and [`nix-store --realise`](@docroot@/command-ref/nix-store/realise.md). From d460dbdd30e3b518de962314bcf183961caf7f53 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 19 Jul 2023 09:31:03 +0200 Subject: [PATCH 08/13] be more precise about substituting store derivations Co-authored-by: Robert Hensing --- doc/manual/src/command-ref/nix-store/realise.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/manual/src/command-ref/nix-store/realise.md b/doc/manual/src/command-ref/nix-store/realise.md index 9dfe74277..750cbeaff 100644 --- a/doc/manual/src/command-ref/nix-store/realise.md +++ b/doc/manual/src/command-ref/nix-store/realise.md @@ -11,9 +11,8 @@ Each of *paths* is processed as follows: -- If the path is already [valid], do nothing. - If the path leads to a [store derivation]: - 1. Realise the store derivation file itself, as a regular store path. + 1. If it is not [valid], substitute the store derivation file itself. 2. Realise its [output paths]: - Try to fetch from [substituters] the [store objects] associated with the output paths in the store derivation's [closure]. - With [content-addressed derivations] (experimental): Determine the output paths to realise by querying build certificates in the [Nix database]. From cf4e14d58da04465c2afd05af6975d568f58ce1d Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 19 Jul 2023 13:28:44 +0200 Subject: [PATCH 09/13] accommodate "do nothing" branch --- doc/manual/src/command-ref/nix-store/realise.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/src/command-ref/nix-store/realise.md b/doc/manual/src/command-ref/nix-store/realise.md index 750cbeaff..6dc908c19 100644 --- a/doc/manual/src/command-ref/nix-store/realise.md +++ b/doc/manual/src/command-ref/nix-store/realise.md @@ -17,7 +17,7 @@ Each of *paths* is processed as follows: - Try to fetch from [substituters] the [store objects] associated with the output paths in the store derivation's [closure]. - With [content-addressed derivations] (experimental): Determine the output paths to realise by querying build certificates in the [Nix database]. - For any store paths that cannot be substituted, produce the required store objects by first realising all outputs of the derivation's dependencies and then running the derivation's [`builder`](@docroot@/language/derivations.md#attr-builder) executable. -- Otherwise: Try to fetch the associated [store objects] in the paths' [closure] from [substituters]. +- Otherwise, and if the path is not already valid: Try to fetch the associated [store objects] in the path's [closure] from [substituters]. If no substitutes are available and no store derivation is given, realisation fails. From b951e862d0bdb93a64e2c85af8762a9294d575c9 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 19 Jul 2023 13:30:40 +0200 Subject: [PATCH 10/13] more meaningful tagline --- doc/manual/src/command-ref/nix-store/realise.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/src/command-ref/nix-store/realise.md b/doc/manual/src/command-ref/nix-store/realise.md index 6dc908c19..680e54ffa 100644 --- a/doc/manual/src/command-ref/nix-store/realise.md +++ b/doc/manual/src/command-ref/nix-store/realise.md @@ -1,6 +1,6 @@ # Name -`nix-store --realise` - realise specified store paths +`nix-store --realise` - build or fetch store objects # Synopsis From 894cbe43bc5caa339dab7f8af31bf065020c9f8d Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 31 Aug 2023 20:50:22 +0200 Subject: [PATCH 11/13] don't invent terms yet --- doc/manual/src/command-ref/nix-store/realise.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/src/command-ref/nix-store/realise.md b/doc/manual/src/command-ref/nix-store/realise.md index 680e54ffa..b97c1f735 100644 --- a/doc/manual/src/command-ref/nix-store/realise.md +++ b/doc/manual/src/command-ref/nix-store/realise.md @@ -15,7 +15,7 @@ Each of *paths* is processed as follows: 1. If it is not [valid], substitute the store derivation file itself. 2. Realise its [output paths]: - Try to fetch from [substituters] the [store objects] associated with the output paths in the store derivation's [closure]. - - With [content-addressed derivations] (experimental): Determine the output paths to realise by querying build certificates in the [Nix database]. + - With [content-addressed derivations] (experimental): Determine the output paths to realise by querying content-addressed realisation entries in the [Nix database]. - For any store paths that cannot be substituted, produce the required store objects by first realising all outputs of the derivation's dependencies and then running the derivation's [`builder`](@docroot@/language/derivations.md#attr-builder) executable. - Otherwise, and if the path is not already valid: Try to fetch the associated [store objects] in the path's [closure] from [substituters]. From d38a539437943f4ae6b1f72321c7dc29559547c5 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 31 Aug 2023 20:50:50 +0200 Subject: [PATCH 12/13] make description open-ended, add TODO Co-authored-by: Robert Hensing --- doc/manual/src/command-ref/nix-store/realise.md | 2 +- doc/manual/src/glossary.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/manual/src/command-ref/nix-store/realise.md b/doc/manual/src/command-ref/nix-store/realise.md index b97c1f735..a421a4220 100644 --- a/doc/manual/src/command-ref/nix-store/realise.md +++ b/doc/manual/src/command-ref/nix-store/realise.md @@ -16,7 +16,7 @@ Each of *paths* is processed as follows: 2. Realise its [output paths]: - Try to fetch from [substituters] the [store objects] associated with the output paths in the store derivation's [closure]. - With [content-addressed derivations] (experimental): Determine the output paths to realise by querying content-addressed realisation entries in the [Nix database]. - - For any store paths that cannot be substituted, produce the required store objects by first realising all outputs of the derivation's dependencies and then running the derivation's [`builder`](@docroot@/language/derivations.md#attr-builder) executable. + - For any store paths that cannot be substituted, produce the required store objects. This involves first realising all outputs of the derivation's dependencies and then running the derivation's [`builder`](@docroot@/language/derivations.md#attr-builder) executable. - Otherwise, and if the path is not already valid: Try to fetch the associated [store objects] in the path's [closure] from [substituters]. If no substitutes are available and no store derivation is given, realisation fails. diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index 8f0b25c89..57a3334dd 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -33,7 +33,7 @@ Ensure a [store path] is [valid][validity]. - This means either running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [derivation], or fetching a pre-built [store object] from a [substituter], or delegating to a [remote builder](@docroot@/advanced-topics/distributed-builds.html) and retrieving the outputs. + This means either running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [derivation], or fetching a pre-built [store object] from a [substituter], or delegating to a [remote builder](@docroot@/advanced-topics/distributed-builds.html) and retrieving the outputs. See [`nix-build`](./command-ref/nix-build.md) and [`nix-store --realise`](@docroot@/command-ref/nix-store/realise.md). From 1ac181759d975e4faeaf9083259287562009b4ec Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 31 Aug 2023 21:25:33 +0200 Subject: [PATCH 13/13] revert some random change --- doc/manual/src/command-ref/nix-store/opt-common.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/manual/src/command-ref/nix-store/opt-common.md b/doc/manual/src/command-ref/nix-store/opt-common.md index 104b20076..dd9a6bf21 100644 --- a/doc/manual/src/command-ref/nix-store/opt-common.md +++ b/doc/manual/src/command-ref/nix-store/opt-common.md @@ -1,6 +1,6 @@ -# Command options +# Options -The following options are allowed for all operations in the `nix-store` command, but may not always have an effect. +The following options are allowed for all `nix-store` operations, but may not always have an effect. - [`--add-root`](#opt-add-root) *path*