From 1d3b92e80ca1564bf2c5ee207df707e215188633 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Fri, 5 Aug 2022 10:39:43 -0700 Subject: move package-management/terminology into glossary.md --- doc/manual/src/glossary.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) (limited to 'doc/manual/src/glossary.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 -- cgit v1.2.3 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: Update doc/manual/src/glossary.md Co-authored-by: Valentin Gagarin --- doc/manual/src/glossary.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) (limited to 'doc/manual/src/glossary.md') 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 -- cgit v1.2.3 From 520587b9a0327194371146f4dd25c9227a2c79e2 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 13:38:07 -0700 Subject: glossary: local store: clarify --- doc/manual/src/glossary.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/manual/src/glossary.md') 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` -- cgit v1.2.3 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: Update doc/manual/src/glossary.md Co-authored-by: John Ericson --- doc/manual/src/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/manual/src/glossary.md') 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: -- cgit v1.2.3 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: Update doc/manual/src/glossary.md Co-authored-by: John Ericson --- doc/manual/src/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/manual/src/glossary.md') 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` -- cgit v1.2.3 From 41153f30bd5ca1bd9fa10d18da7a6b5b78a94087 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 13:54:09 -0700 Subject: glossary: substituter: merge output-addressed cases --- doc/manual/src/glossary.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'doc/manual/src/glossary.md') 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 -- cgit v1.2.3 From 1f56b5d77247d89a15a2c16ba2f5d1d672c835e8 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 14:09:06 -0700 Subject: doc/manual: un-inline definitions from `substitute` --- doc/manual/src/glossary.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) (limited to 'doc/manual/src/glossary.md') 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 -- cgit v1.2.3 From 0a98d564b3d8d195c023429e5f7faf63e20b5d93 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 14:41:27 -0700 Subject: glossary: resolve FIXME in #gloss-fixed-output-derivation --- doc/manual/src/glossary.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) (limited to 'doc/manual/src/glossary.md') 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 -- cgit v1.2.3 From 1b2b8c39fd64871b3df261c05ed001fcd1057a6c Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 14:47:17 -0700 Subject: fix link to language/advanced-attributes.md#adv-attr-contentAddressed --- doc/manual/src/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/manual/src/glossary.md') 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}\ -- cgit v1.2.3 From def4fb9a0f73046efbf9fdb4f1e35898fb27ca34 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 14:47:33 -0700 Subject: __outputHash: add link --- doc/manual/src/glossary.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/manual/src/glossary.md') 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 -- cgit v1.2.3 From 8139bbe2ba767458cba4158627ee3d58f4a35d7d Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 15:01:07 -0700 Subject: implement https://github.com/NixOS/nix/pull/6870#pullrequestreview-1093700220 --- doc/manual/src/glossary.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/manual/src/glossary.md') 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 -- cgit v1.2.3 From 57f12df5e4cde436566d3c4f0226d329e6eedf1a Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 15:09:10 -0700 Subject: input-addressed store object: include FODOs --- doc/manual/src/glossary.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'doc/manual/src/glossary.md') 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}\ -- cgit v1.2.3 From d5e064d8162e377556dc9daba99868085561a080 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 17:46:31 -0700 Subject: glossary: fix broken link --- doc/manual/src/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/manual/src/glossary.md') 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}\ -- cgit v1.2.3 From 887e922be29d37d377ef766c7fe7a2103f43ca21 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 17:47:13 -0700 Subject: glossary: outputHash, not __outputHash --- doc/manual/src/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/manual/src/glossary.md') 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 -- cgit v1.2.3 From f6c750e8b2f299e9876fd8f2578f9093682f6d7f Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 17:48:34 -0700 Subject: glossary: remove extraneous comma --- doc/manual/src/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/manual/src/glossary.md') 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}\ -- cgit v1.2.3 From 59dc8346ca53f49ccdbbd6709b12a479376d1464 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 17:51:56 -0700 Subject: move substituter signature-checking conditions to configuration file documentation --- doc/manual/src/glossary.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) (limited to 'doc/manual/src/glossary.md') 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 -- cgit v1.2.3 From e6f5352e71a1811eb2eb3bfb989e109de590c7a7 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 18:27:00 -0700 Subject: #binary-cache -> #gloss-binary-cache --- doc/manual/src/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/manual/src/glossary.md') 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 -- cgit v1.2.3 From e90f2fcfc71ca997f254c86f8ed12fc143374752 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 1 Sep 2022 18:28:05 -0700 Subject: glossary: add entry for `chroot store` (used 11 times in nix) --- doc/manual/src/glossary.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'doc/manual/src/glossary.md') 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 -- cgit v1.2.3