From a5be5e01200a12cc34d0e3a2e3f964d5c95208b9 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 4 Aug 2022 14:07:06 -0700 Subject: [PATCH 01/29] doc/manual: define {local,remote} store, binary cache, substituter Nix veterans intuitively know what the following terms mean. They are used in several places in the nix documentation, but never defined: - local store - remote store - binary cache - substituter In particular, I found the last two terms to be confusingly similar. Let's give definitions for them. --- doc/manual/src/SUMMARY.md.in | 1 + .../src/package-management/terminology.md | 27 +++++++++++++++++++ 2 files changed, 28 insertions(+) create mode 100644 doc/manual/src/package-management/terminology.md diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in index a47d39f31..f8da2247b 100644 --- a/doc/manual/src/SUMMARY.md.in +++ b/doc/manual/src/SUMMARY.md.in @@ -22,6 +22,7 @@ - [Garbage Collector Roots](package-management/garbage-collector-roots.md) - [Channels](package-management/channels.md) - [Sharing Packages Between Machines](package-management/sharing-packages.md) + - [Terminology](package-management/terminology.md) - [Serving a Nix store via HTTP](package-management/binary-cache-substituter.md) - [Copying Closures via SSH](package-management/copy-closure.md) - [Serving a Nix store via SSH](package-management/ssh-substituter.md) diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md new file mode 100644 index 000000000..28e2a1f0b --- /dev/null +++ b/doc/manual/src/package-management/terminology.md @@ -0,0 +1,27 @@ +# Terminology + +A *local store* exists on the local filesystem of the machine where +Nix is invoked. The `/nix/store` directory is one example of a +local store. You can use other local stores by passing the +`--store` flag to `nix`. + +A *remote store* is a store which exists anywhere other than the +local filesystem. One example is the `/nix/store` directory on +another machine, accessed via `ssh` or served by the `nix-serve` +Perl script. + +A *binary cache* is a remote store which is not the local store of +any machine. Examples of binary caches include S3 buckets and the +[NixOS binary cache](https://cache.nixos.org). Binary caches use a +disk layout that is different from local stores; in particular, they +keep metadata and signatures in `.narinfo` files rather than in +`/nix/var/nix/db`. + +A *substituter* is a store other than `/nix/store` from which nix will +copy the realisation of a derivation instead of building it. Nix will +not copy a realisation from a remote store unless one of the following +is true: + +- the realisation is signed by one of the `trusted-public-key`s +- the substituter is in the `trusted-substituters` list +- the `no-require-sigs` option has been set to disable signature checking From 56d4fc194ba90ee4e559a07a895f6bf4a61ef462 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 4 Aug 2022 14:14:24 -0700 Subject: [PATCH 02/29] fourth trust condition: FODs --- doc/manual/src/package-management/terminology.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md index 28e2a1f0b..1722a9fc8 100644 --- a/doc/manual/src/package-management/terminology.md +++ b/doc/manual/src/package-management/terminology.md @@ -25,3 +25,5 @@ is true: - the realisation is signed by one of the `trusted-public-key`s - the substituter is in the `trusted-substituters` list - the `no-require-sigs` option has been set to disable signature checking +- the derivation is a fixed-output derivation + From 8f44d24c525160b2ddef5e18a4af4ce667e23e9f Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 4 Aug 2022 14:19:25 -0700 Subject: [PATCH 03/29] !fixup whitespace --- doc/manual/src/package-management/terminology.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md index 1722a9fc8..d800bafc1 100644 --- a/doc/manual/src/package-management/terminology.md +++ b/doc/manual/src/package-management/terminology.md @@ -26,4 +26,3 @@ is true: - the substituter is in the `trusted-substituters` list - the `no-require-sigs` option has been set to disable signature checking - the derivation is a fixed-output derivation - From 62674659ed7b7fc6a2c884f52df2474e344400f8 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 4 Aug 2022 14:21:17 -0700 Subject: [PATCH 04/29] !fixup capitalize Nix --- doc/manual/src/package-management/terminology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md index d800bafc1..8dc2ede33 100644 --- a/doc/manual/src/package-management/terminology.md +++ b/doc/manual/src/package-management/terminology.md @@ -17,7 +17,7 @@ disk layout that is different from local stores; in particular, they keep metadata and signatures in `.narinfo` files rather than in `/nix/var/nix/db`. -A *substituter* is a store other than `/nix/store` from which nix will +A *substituter* is a store other than `/nix/store` from which Nix will copy the realisation of a derivation instead of building it. Nix will not copy a realisation from a remote store unless one of the following is true: From 1b97f3872ed70d9ad5d19d27dc56b42ba4d26382 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 4 Aug 2022 14:22:14 -0700 Subject: [PATCH 05/29] !fixup: transposed characters --- doc/manual/src/package-management/terminology.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md index 8dc2ede33..6ad0f6833 100644 --- a/doc/manual/src/package-management/terminology.md +++ b/doc/manual/src/package-management/terminology.md @@ -22,7 +22,7 @@ copy the realisation of a derivation instead of building it. Nix will not copy a realisation from a remote store unless one of the following is true: -- the realisation is signed by one of the `trusted-public-key`s +- the realisation is signed by one of the `trusted-public-keys` - the substituter is in the `trusted-substituters` list - the `no-require-sigs` option has been set to disable signature checking - the derivation is a fixed-output derivation From aae771cad26a3803ef0a0855c782823d22949cf3 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Fri, 5 Aug 2022 10:12:46 -0700 Subject: [PATCH 06/29] !implement https://github.com/NixOS/nix/pull/6870#discussion_r938912244 --- doc/manual/src/package-management/terminology.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md index 6ad0f6833..241bb6c5a 100644 --- a/doc/manual/src/package-management/terminology.md +++ b/doc/manual/src/package-management/terminology.md @@ -18,11 +18,10 @@ keep metadata and signatures in `.narinfo` files rather than in `/nix/var/nix/db`. A *substituter* is a store other than `/nix/store` from which Nix will -copy the realisation of a derivation instead of building it. Nix will -not copy a realisation from a remote store unless one of the following -is true: +copy a store path instead of building it. Nix will not copy a store +path from a remote store unless one of the following is true: -- the realisation is signed by one of the `trusted-public-keys` +- the store object is signed by one of the `trusted-public-keys` - the substituter is in the `trusted-substituters` list - the `no-require-sigs` option has been set to disable signature checking -- the derivation is a fixed-output derivation +- the store object is the realisation of a fixed-output derivation From 2eb74c918dc7dc04ed36b3fdcd95406007d97690 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Fri, 5 Aug 2022 10:13:41 -0700 Subject: [PATCH 07/29] derivations do not need to be signed --- doc/manual/src/package-management/terminology.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md index 241bb6c5a..4b9e68de9 100644 --- a/doc/manual/src/package-management/terminology.md +++ b/doc/manual/src/package-management/terminology.md @@ -24,4 +24,5 @@ path from a remote store unless one of the following is true: - the store object is signed by one of the `trusted-public-keys` - the substituter is in the `trusted-substituters` list - the `no-require-sigs` option has been set to disable signature checking +- the store object is a derivation - the store object is the realisation of a fixed-output derivation From 66a93a76b9842ac18188b91f5a30c4ac4f2b6118 Mon Sep 17 00:00:00 2001 From: Adam Joseph <54836058+amjoseph-nixpkgs@users.noreply.github.com> Date: Fri, 5 Aug 2022 17:15:37 +0000 Subject: [PATCH 08/29] Update doc/manual/src/package-management/terminology.md Co-authored-by: Attila Gulyas --- .../src/package-management/terminology.md | 24 ++++++++++++------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md index 4b9e68de9..564667f93 100644 --- a/doc/manual/src/package-management/terminology.md +++ b/doc/manual/src/package-management/terminology.md @@ -1,14 +1,22 @@ # Terminology -A *local store* exists on the local filesystem of the machine where -Nix is invoked. The `/nix/store` directory is one example of a -local store. You can use other local stores by passing the -`--store` flag to `nix`. +From the perspective of the location where Nix is +invoked1, the Nix store can be referred to +as a "_local_" or a "_remote_" one: -A *remote store* is a store which exists anywhere other than the -local filesystem. One example is the `/nix/store` directory on -another machine, accessed via `ssh` or served by the `nix-serve` -Perl script. +\[1]: Where "invoking Nix" means an executing a Nix core +action/operation on a Nix store. For example, using any CLI +commands from the `NixOS/nix` implementation. + ++ A *local store* exists on the local filesystem of + the machine where Nix is invoked. You can use other + local stores by passing the `--store` flag to the + `nix` command. + ++ A *remote store* exists anywhere other than the + local filesystem. One example is the `/nix/store` + directory on another machine, accessed via `ssh` or + served by the `nix-serve` Perl script. A *binary cache* is a remote store which is not the local store of any machine. Examples of binary caches include S3 buckets and the From d5506aa71200425b65cc1777077478f5ff8d2aff Mon Sep 17 00:00:00 2001 From: Adam Joseph <54836058+amjoseph-nixpkgs@users.noreply.github.com> Date: Fri, 5 Aug 2022 17:19:52 +0000 Subject: [PATCH 09/29] Update doc/manual/src/package-management/terminology.md Co-authored-by: Attila Gulyas --- doc/manual/src/package-management/terminology.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md index 564667f93..b3e9ea040 100644 --- a/doc/manual/src/package-management/terminology.md +++ b/doc/manual/src/package-management/terminology.md @@ -18,12 +18,10 @@ commands from the `NixOS/nix` implementation. directory on another machine, accessed via `ssh` or served by the `nix-serve` Perl script. -A *binary cache* is a remote store which is not the local store of -any machine. Examples of binary caches include S3 buckets and the -[NixOS binary cache](https://cache.nixos.org). Binary caches use a -disk layout that is different from local stores; in particular, they -keep metadata and signatures in `.narinfo` files rather than in -`/nix/var/nix/db`. +A *binary cache* is a specialized Nix store whose metadata and +signatures are kept in `.narinfo` files rather than in the Nix +database. Examples of binary caches include S3 buckets and the +[NixOS binary cache](https://cache.nixos.org). A *substituter* is a store other than `/nix/store` from which Nix will copy a store path instead of building it. Nix will not copy a store From 4de95f7f565df71d8ebddb7434e2b0feb49a833b Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Fri, 5 Aug 2022 10:33:48 -0700 Subject: [PATCH 10/29] gesture at explanation of why binary caches exist --- doc/manual/src/package-management/terminology.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md index b3e9ea040..493f5f03e 100644 --- a/doc/manual/src/package-management/terminology.md +++ b/doc/manual/src/package-management/terminology.md @@ -18,10 +18,12 @@ commands from the `NixOS/nix` implementation. directory on another machine, accessed via `ssh` or served by the `nix-serve` Perl script. -A *binary cache* is a specialized Nix store whose metadata and -signatures are kept in `.narinfo` files rather than in the Nix -database. Examples of binary caches include S3 buckets and the -[NixOS binary cache](https://cache.nixos.org). +A *binary cache* is a Nix store which uses a different format: its +metadata and signatures are kept in `.narinfo` files rather than in a +Nix database. This different format simplifies serving store objects +over the network, but cannot host builds. Examples of binary caches +include S3 buckets and the [NixOS binary +cache](https://cache.nixos.org). A *substituter* is a store other than `/nix/store` from which Nix will copy a store path instead of building it. Nix will not copy a store From 1d3b92e80ca1564bf2c5ee207df707e215188633 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Fri, 5 Aug 2022 10:39:43 -0700 Subject: [PATCH 11/29] move package-management/terminology into glossary.md --- doc/manual/src/SUMMARY.md.in | 1 - doc/manual/src/glossary.md | 37 +++++++++++++++++++ .../src/package-management/terminology.md | 36 ------------------ 3 files changed, 37 insertions(+), 37 deletions(-) delete mode 100644 doc/manual/src/package-management/terminology.md diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in index f8da2247b..a47d39f31 100644 --- a/doc/manual/src/SUMMARY.md.in +++ b/doc/manual/src/SUMMARY.md.in @@ -22,7 +22,6 @@ - [Garbage Collector Roots](package-management/garbage-collector-roots.md) - [Channels](package-management/channels.md) - [Sharing Packages Between Machines](package-management/sharing-packages.md) - - [Terminology](package-management/terminology.md) - [Serving a Nix store via HTTP](package-management/binary-cache-substituter.md) - [Copying Closures via SSH](package-management/copy-closure.md) - [Serving a Nix store via SSH](package-management/ssh-substituter.md) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index aa0ac78cb..f4c51588d 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -11,6 +11,32 @@ The location in the file system where store objects live. Typically `/nix/store`. + From the perspective of the location where Nix is + invoked1, the Nix store can be referred to + as a "_local_" or a "_remote_" one: + + \[1]: Where "invoking Nix" means an executing a Nix core + action/operation on a Nix store. For example, using any CLI + commands from the `NixOS/nix` implementation. + + + A *local store* exists on the local filesystem of + the machine where Nix is invoked. You can use other + local stores by passing the `--store` flag to the + `nix` command. + + + A *remote store* exists anywhere other than the + local filesystem. One example is the `/nix/store` + directory on another machine, accessed via `ssh` or + served by the `nix-serve` Perl script. + + - [binary cache]{#binary-cache}\ + A *binary cache* is a Nix store which uses a different format: its + metadata and signatures are kept in `.narinfo` files rather than in a + Nix database. This different format simplifies serving store objects + over the network, but cannot host builds. Examples of binary caches + include S3 buckets and the [NixOS binary + cache](https://cache.nixos.org). + - [store path]{#gloss-store-path}\ The location in the file system of a store object, i.e., an immediate child of the Nix store directory. @@ -29,6 +55,17 @@ store object by downloading a pre-built version of the store object from some server. + - [substituter]{#gloss-substituter}\ + A *substituter* is a store other than `/nix/store` from which Nix will + copy a store path instead of building it. Nix will not copy a store + path from a remote store unless one of the following is true: + + - the store object is signed by one of the `trusted-public-keys` + - the substituter is in the `trusted-substituters` list + - the `no-require-sigs` option has been set to disable signature checking + - the store object is a derivation + - the store object is the realisation of a fixed-output derivation + - [purity]{#gloss-purity}\ The assumption that equal Nix derivations when run always produce the same output. This cannot be guaranteed in general (e.g., a diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md deleted file mode 100644 index 493f5f03e..000000000 --- a/doc/manual/src/package-management/terminology.md +++ /dev/null @@ -1,36 +0,0 @@ -# Terminology - -From the perspective of the location where Nix is -invoked1, the Nix store can be referred to -as a "_local_" or a "_remote_" one: - -\[1]: Where "invoking Nix" means an executing a Nix core -action/operation on a Nix store. For example, using any CLI -commands from the `NixOS/nix` implementation. - -+ A *local store* exists on the local filesystem of - the machine where Nix is invoked. You can use other - local stores by passing the `--store` flag to the - `nix` command. - -+ A *remote store* exists anywhere other than the - local filesystem. One example is the `/nix/store` - directory on another machine, accessed via `ssh` or - served by the `nix-serve` Perl script. - -A *binary cache* is a Nix store which uses a different format: its -metadata and signatures are kept in `.narinfo` files rather than in a -Nix database. This different format simplifies serving store objects -over the network, but cannot host builds. Examples of binary caches -include S3 buckets and the [NixOS binary -cache](https://cache.nixos.org). - -A *substituter* is a store other than `/nix/store` from which Nix will -copy a store path instead of building it. Nix will not copy a store -path from a remote store unless one of the following is true: - -- the store object is signed by one of the `trusted-public-keys` -- the substituter is in the `trusted-substituters` list -- the `no-require-sigs` option has been set to disable signature checking -- the store object is a derivation -- the store object is the realisation of a fixed-output derivation From bac1e1bf8c359b5e6831c3974a05bdce867775a5 Mon Sep 17 00:00:00 2001 From: Adam Joseph <54836058+amjoseph-nixpkgs@users.noreply.github.com> Date: Mon, 8 Aug 2022 17:52:31 +0000 Subject: [PATCH 12/29] Update doc/manual/src/glossary.md Co-authored-by: Valentin Gagarin --- doc/manual/src/glossary.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index f4c51588d..77de58965 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -12,13 +12,9 @@ `/nix/store`. From the perspective of the location where Nix is - invoked1, the Nix store can be referred to + invoked, the Nix store can be referred to as a "_local_" or a "_remote_" one: - \[1]: Where "invoking Nix" means an executing a Nix core - action/operation on a Nix store. For example, using any CLI - commands from the `NixOS/nix` implementation. - + A *local store* exists on the local filesystem of the machine where Nix is invoked. You can use other local stores by passing the `--store` flag to the From 520587b9a0327194371146f4dd25c9227a2c79e2 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 13:38:07 -0700 Subject: [PATCH 13/29] glossary: local store: clarify --- doc/manual/src/glossary.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index 77de58965..d653a2ae4 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -15,10 +15,10 @@ invoked, the Nix store can be referred to as a "_local_" or a "_remote_" one: - + A *local store* exists on the local filesystem of + + A *local store* exists on the filesystem of the machine where Nix is invoked. You can use other local stores by passing the `--store` flag to the - `nix` command. + `nix` command. Local stores can be used for building derivations. + A *remote store* exists anywhere other than the local filesystem. One example is the `/nix/store` From 2812682ebee9d4419ba89690177b31564ce5ba77 Mon Sep 17 00:00:00 2001 From: Adam Joseph <54836058+amjoseph-nixpkgs@users.noreply.github.com> Date: Thu, 1 Sep 2022 20:40:39 +0000 Subject: [PATCH 14/29] Update doc/manual/src/glossary.md Co-authored-by: John Ericson --- 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 d653a2ae4..f072f35e1 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -52,7 +52,7 @@ from some server. - [substituter]{#gloss-substituter}\ - A *substituter* is a store other than `/nix/store` from which Nix will + A *substituter* is an additional store from which Nix will copy a store path instead of building it. Nix will not copy a store path from a remote store unless one of the following is true: From 9cb84121435e8ca6a51950b9d96a3d3be47c809e Mon Sep 17 00:00:00 2001 From: Adam Joseph <54836058+amjoseph-nixpkgs@users.noreply.github.com> Date: Thu, 1 Sep 2022 20:41:04 +0000 Subject: [PATCH 15/29] Update doc/manual/src/glossary.md Co-authored-by: John Ericson --- 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 f072f35e1..91865c807 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -53,7 +53,7 @@ - [substituter]{#gloss-substituter}\ A *substituter* is an additional store from which Nix will - copy a store path instead of building it. Nix will not copy a store + copy store objects it doesn't have. Nix will not copy a store path from a remote store unless one of the following is true: - the store object is signed by one of the `trusted-public-keys` From 41153f30bd5ca1bd9fa10d18da7a6b5b78a94087 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 13:54:09 -0700 Subject: [PATCH 16/29] glossary: substituter: merge output-addressed cases --- doc/manual/src/glossary.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index 91865c807..608beb8f8 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -59,8 +59,9 @@ - the store object is signed by one of the `trusted-public-keys` - the substituter is in the `trusted-substituters` list - the `no-require-sigs` option has been set to disable signature checking - - the store object is a derivation - - the store object is the realisation of a fixed-output derivation + - the store object is *output-addressed*; this includes + derivations, the outputs of content-addressed derivations, and + the outputs of fixed-output derivations. - [purity]{#gloss-purity}\ The assumption that equal Nix derivations when run always produce From 1f56b5d77247d89a15a2c16ba2f5d1d672c835e8 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 14:09:06 -0700 Subject: [PATCH 17/29] doc/manual: un-inline definitions from `substitute` --- doc/manual/src/glossary.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index 608beb8f8..8dff4646c 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -7,6 +7,14 @@ translated into low-level *store derivations* (implicitly by `nix-env` and `nix-build`, or explicitly by `nix-instantiate`). + - [content-addressed derivation]{#gloss-fixed-output-derivation} + FIXME + + - [fixed-output derivation]{#gloss-fixed-output-derivation} + A derivation which includes the `__outHash` attribute; the output + of such derivations must exactly match the hash. All fixed-output + derivations are [content-addressed derivations](#gloss-content-addressed-derivation). + - [store]{#gloss-store}\ The location in the file system where store objects live. Typically `/nix/store`. @@ -44,6 +52,16 @@ derivation outputs (objects produced by running a build action), or derivations (files describing a build action). + - [input-addressed store object]{#gloss-input-addressed-store-object}\ + Store objects produced by building a + non-[content-addressed](#gloss-content-addressed-derivation) + derivation. + + - [output-addressed store object]{#gloss-output-addressed-store-object}\ + A store object whose store path hashes its content. This + includes derivations and the outputs of + [content-addressed derivations](#gloss-content-addressed-derivation) + - [substitute]{#gloss-substitute}\ A substitute is a command invocation stored in the Nix database that describes how to build a store object, bypassing the normal build @@ -59,9 +77,7 @@ - the store object is signed by one of the `trusted-public-keys` - the substituter is in the `trusted-substituters` list - the `no-require-sigs` option has been set to disable signature checking - - the store object is *output-addressed*; this includes - derivations, the outputs of content-addressed derivations, and - the outputs of fixed-output derivations. + - the store object is [output-addressed](#gloss-output-addressed-store-object) - [purity]{#gloss-purity}\ The assumption that equal Nix derivations when run always produce From 0a98d564b3d8d195c023429e5f7faf63e20b5d93 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 14:41:27 -0700 Subject: [PATCH 18/29] glossary: resolve FIXME in #gloss-fixed-output-derivation --- doc/manual/src/glossary.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index 8dff4646c..473aef03c 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -7,13 +7,14 @@ translated into low-level *store derivations* (implicitly by `nix-env` and `nix-build`, or explicitly by `nix-instantiate`). - - [content-addressed derivation]{#gloss-fixed-output-derivation} - FIXME + - [content-addressed derivation]{#gloss-content-addressed-derivation}\ + A derivation which has the + [`__contentAddressed`](language/advanced-attributes.md#contentAddressed) + attribute set to `true`. - - [fixed-output derivation]{#gloss-fixed-output-derivation} - A derivation which includes the `__outHash` attribute; the output - of such derivations must exactly match the hash. All fixed-output - derivations are [content-addressed derivations](#gloss-content-addressed-derivation). + - [fixed-output derivation]{#gloss-fixed-output-derivation}\ + A derivation which includes the `__outputHash` attribute; the output + of such derivations must exactly match the hash. - [store]{#gloss-store}\ The location in the file system where store objects live. Typically @@ -59,8 +60,10 @@ - [output-addressed store object]{#gloss-output-addressed-store-object}\ A store object whose store path hashes its content. This - includes derivations and the outputs of - [content-addressed derivations](#gloss-content-addressed-derivation) + includes derivations, the outputs of + [content-addressed derivations](#gloss-content-addressed-derivation), + and the outputs of + [fixed-output derivations](#gloss-fixed-output-derivation). - [substitute]{#gloss-substitute}\ A substitute is a command invocation stored in the Nix database that From 1b2b8c39fd64871b3df261c05ed001fcd1057a6c Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 14:47:17 -0700 Subject: [PATCH 19/29] fix link to language/advanced-attributes.md#adv-attr-contentAddressed --- 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 473aef03c..bf1d0cf05 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -9,7 +9,7 @@ - [content-addressed derivation]{#gloss-content-addressed-derivation}\ A derivation which has the - [`__contentAddressed`](language/advanced-attributes.md#contentAddressed) + [`__contentAddressed`](language/advanced-attributes.md#adv-attr-contentAddressed) attribute set to `true`. - [fixed-output derivation]{#gloss-fixed-output-derivation}\ From def4fb9a0f73046efbf9fdb4f1e35898fb27ca34 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 14:47:33 -0700 Subject: [PATCH 20/29] __outputHash: add link --- doc/manual/src/glossary.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index bf1d0cf05..d61cfc823 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -13,8 +13,8 @@ attribute set to `true`. - [fixed-output derivation]{#gloss-fixed-output-derivation}\ - A derivation which includes the `__outputHash` attribute; the output - of such derivations must exactly match the hash. + A derivation which includes the + [`__outputHash`](language/advanced-attributes.md#adv-attr-outputHash) attribute. - [store]{#gloss-store}\ The location in the file system where store objects live. Typically From 8139bbe2ba767458cba4158627ee3d58f4a35d7d Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 15:01:07 -0700 Subject: [PATCH 21/29] implement https://github.com/NixOS/nix/pull/6870#pullrequestreview-1093700220 --- doc/manual/src/glossary.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index d61cfc823..b30633833 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -74,8 +74,8 @@ - [substituter]{#gloss-substituter}\ A *substituter* is an additional store from which Nix will - copy store objects it doesn't have. Nix will not copy a store - path from a remote store unless one of the following is true: + copy store objects it doesn't have. Nix will copy a store + path from a remote store only if one of the following is true: - the store object is signed by one of the `trusted-public-keys` - the substituter is in the `trusted-substituters` list From 57f12df5e4cde436566d3c4f0226d329e6eedf1a Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 15:09:10 -0700 Subject: [PATCH 22/29] input-addressed store object: include FODOs --- doc/manual/src/glossary.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index b30633833..89a9b94a1 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -54,8 +54,9 @@ derivations (files describing a build action). - [input-addressed store object]{#gloss-input-addressed-store-object}\ - Store objects produced by building a - non-[content-addressed](#gloss-content-addressed-derivation) + A store object produced by building a + non-[content-addressed](#gloss-content-addressed-derivation), + non-[fixed-output](#gloss-fixed-output-derivation), derivation. - [output-addressed store object]{#gloss-output-addressed-store-object}\ From d5e064d8162e377556dc9daba99868085561a080 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 17:46:31 -0700 Subject: [PATCH 23/29] glossary: fix broken link --- 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 89a9b94a1..1aebdaa67 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -9,7 +9,7 @@ - [content-addressed derivation]{#gloss-content-addressed-derivation}\ A derivation which has the - [`__contentAddressed`](language/advanced-attributes.md#adv-attr-contentAddressed) + [`__contentAddressed`](language/advanced-attributes.md#adv-attr-__contentAddressed) attribute set to `true`. - [fixed-output derivation]{#gloss-fixed-output-derivation}\ From 887e922be29d37d377ef766c7fe7a2103f43ca21 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 17:47:13 -0700 Subject: [PATCH 24/29] glossary: outputHash, not __outputHash --- 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 1aebdaa67..73e209103 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -14,7 +14,7 @@ - [fixed-output derivation]{#gloss-fixed-output-derivation}\ A derivation which includes the - [`__outputHash`](language/advanced-attributes.md#adv-attr-outputHash) attribute. + [`outputHash`](language/advanced-attributes.md#adv-attr-outputHash) attribute. - [store]{#gloss-store}\ The location in the file system where store objects live. Typically From f6c750e8b2f299e9876fd8f2578f9093682f6d7f Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 17:48:34 -0700 Subject: [PATCH 25/29] glossary: remove extraneous comma --- 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 73e209103..7ba595ba0 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -56,7 +56,7 @@ - [input-addressed store object]{#gloss-input-addressed-store-object}\ A store object produced by building a non-[content-addressed](#gloss-content-addressed-derivation), - non-[fixed-output](#gloss-fixed-output-derivation), + non-[fixed-output](#gloss-fixed-output-derivation) derivation. - [output-addressed store object]{#gloss-output-addressed-store-object}\ From 59dc8346ca53f49ccdbbd6709b12a479376d1464 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 17:51:56 -0700 Subject: [PATCH 26/29] move substituter signature-checking conditions to configuration file documentation --- doc/manual/src/glossary.md | 9 ++------- src/libstore/globals.hh | 8 ++++++++ 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index 7ba595ba0..6bf041e7c 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -75,13 +75,8 @@ - [substituter]{#gloss-substituter}\ A *substituter* is an additional store from which Nix will - copy store objects it doesn't have. Nix will copy a store - path from a remote store only if one of the following is true: - - - the store object is signed by one of the `trusted-public-keys` - - the substituter is in the `trusted-substituters` list - - the `no-require-sigs` option has been set to disable signature checking - - the store object is [output-addressed](#gloss-output-addressed-store-object) + copy store objects it doesn't have. For details, see the + [`substituters` option](command-ref/conf-file.html#conf-substituters). - [purity]{#gloss-purity}\ The assumption that equal Nix derivations when run always produce diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh index d7f351166..a659036e2 100644 --- a/src/libstore/globals.hh +++ b/src/libstore/globals.hh @@ -613,6 +613,14 @@ public: are tried based on their Priority value, which each substituter can set independently. Lower value means higher priority. The default is `https://cache.nixos.org`, with a Priority of 40. + + Nix will copy a store path from a remote store only if one + of the following is true: + + - the store object is signed by one of the `trusted-public-keys` + - the substituter is in the `trusted-substituters` list + - the `no-require-sigs` option has been set to disable signature checking + - the store object is [output-addressed](#gloss-output-addressed-store-object) )", {"binary-caches"}}; From 1ab913467ef8e9ff946e64bd31841775d743b2d6 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 17:54:23 -0700 Subject: [PATCH 27/29] linkify mention of other options --- src/libstore/globals.hh | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh index a659036e2..a4db3bf08 100644 --- a/src/libstore/globals.hh +++ b/src/libstore/globals.hh @@ -617,10 +617,10 @@ public: Nix will copy a store path from a remote store only if one of the following is true: - - the store object is signed by one of the `trusted-public-keys` - - the substituter is in the `trusted-substituters` list - - the `no-require-sigs` option has been set to disable signature checking - - the store object is [output-addressed](#gloss-output-addressed-store-object) + - the store object is signed by one of the [`trusted-public-keys`](#conf-trusted-public-keys) + - the substituter is in the [`trusted-substituters`](#conf-trusted-substituters) list + - the [`require-sigs`](#conf-require-sigs) option has been set to `false` + - the store object is [output-addressed](glossary.md#gloss-output-addressed-store-object) )", {"binary-caches"}}; From e6f5352e71a1811eb2eb3bfb989e109de590c7a7 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 18:27:00 -0700 Subject: [PATCH 28/29] #binary-cache -> #gloss-binary-cache --- 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 6bf041e7c..a34b8a60c 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -34,7 +34,7 @@ directory on another machine, accessed via `ssh` or served by the `nix-serve` Perl script. - - [binary cache]{#binary-cache}\ + - [binary cache]{#gloss-binary-cache}\ A *binary cache* is a Nix store which uses a different format: its metadata and signatures are kept in `.narinfo` files rather than in a Nix database. This different format simplifies serving store objects From e90f2fcfc71ca997f254c86f8ed12fc143374752 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 18:28:05 -0700 Subject: [PATCH 29/29] glossary: add entry for `chroot store` (used 11 times in nix) --- doc/manual/src/glossary.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index a34b8a60c..70a0eb994 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -34,6 +34,9 @@ directory on another machine, accessed via `ssh` or served by the `nix-serve` Perl script. + - [chroot store]{#gloss-chroot-store}\ + A local store whose canonical path is anything other than `/nix/store`. + - [binary cache]{#gloss-binary-cache}\ A *binary cache* is a Nix store which uses a different format: its metadata and signatures are kept in `.narinfo` files rather than in a