From bc9de373c7dc6c84e90e06dff477d4b44b8f653d Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Tue, 20 Dec 2022 16:24:13 +0100 Subject: [PATCH 1/8] reword definition of "reference" --- doc/manual/src/glossary.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index e63f6becc..538db7230 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -115,14 +115,12 @@ then be built. - [reference]{#gloss-reference}\ - A store path `P` is said to have a reference to a store path `Q` if - the store object at `P` contains the path `Q` somewhere. The - *references* of a store path are the set of store paths to which it - has a reference. + A [store path] `P` is said to have a *reference* to a store path `Q` if the string `Q` appears in the [store object] at `P`. + The *references* of a store path `P` are the set of store paths to which `P` has a reference. - A derivation can reference other derivations and sources (but not - output paths), whereas an output path only references other output - paths. + A [derivation] can reference other derivations and source files, but not [output path]s, whereas an output path can only reference other output paths. + + [reference]: #gloss-reference - [reachable]{#gloss-reachable}\ A store path `Q` is reachable from another store path `P` if `Q` From 59f03437c2015259c228a4926e1e2f484dfa505b Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 5 Jan 2023 15:34:18 +0100 Subject: [PATCH 2/8] references refer to store objects, not paths as noted by @Ericson2314 --- doc/manual/src/glossary.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index 538db7230..cf0cf2294 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -115,10 +115,12 @@ then be built. - [reference]{#gloss-reference}\ - A [store path] `P` is said to have a *reference* to a store path `Q` if the string `Q` appears in the [store object] at `P`. - The *references* of a store path `P` are the set of store paths to which `P` has a reference. + A [store object] `O` is said to have a *reference* to a store object `P` if the [store path] of `P` appears in the contents of `O`. + The *references* of a store object `O` are the set of store objects to which `O` has a reference. - A [derivation] can reference other derivations and source files, but not [output path]s, whereas an output path can only reference other output paths. + Source files have no references. + A [store derivation] can only reference source files and other store derivations, including itself. + In contrast, a store object that was produced from a [derivation] can only reference other "derived" store objects. [reference]: #gloss-reference @@ -137,7 +139,7 @@ files could be missing. The command `nix-store -qR` prints out closures of store paths. - As an example, if the store object at path `P` contains a reference + As an example, if the store object at path `P` contains a [reference] to path `Q`, then `Q` is in the closure of `P`. Further, if `Q` references `R` then `R` is also in the closure of `P`. From 9be3c6c7c77ade79446f0d6349c6e4b82ccbbb83 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Tue, 17 Jan 2023 12:33:23 +0100 Subject: [PATCH 3/8] add note on self-references and cycles Co-authored-by: John Ericson --- doc/manual/src/glossary.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index cf0cf2294..fa52b6937 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -118,9 +118,9 @@ A [store object] `O` is said to have a *reference* to a store object `P` if the [store path] of `P` appears in the contents of `O`. The *references* of a store object `O` are the set of store objects to which `O` has a reference. - Source files have no references. - A [store derivation] can only reference source files and other store derivations, including itself. - In contrast, a store object that was produced from a [derivation] can only reference other "derived" store objects. + Store objects can refer to both other store objects and themselves. + References from a store object to itself are called *self-references*. + References other than a self-reference must not form a cycle. [reference]: #gloss-reference From e4f12ff482594ec562291bda300feb70a07de96b Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Tue, 7 Feb 2023 11:59:18 +0100 Subject: [PATCH 4/8] store paths are not uniquely determined --- 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 fa52b6937..a17a9e9eb 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -115,7 +115,7 @@ then be built. - [reference]{#gloss-reference}\ - A [store object] `O` is said to have a *reference* to a store object `P` if the [store path] of `P` appears in the contents of `O`. + A [store object] `O` is said to have a *reference* to a store object `P` if a [store path] to `P` appears in the contents of `O`. The *references* of a store object `O` are the set of store objects to which `O` has a reference. Store objects can refer to both other store objects and themselves. From f370a5a26cf8680f0d77b07d71b471a3e5222a48 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Tue, 7 Feb 2023 20:40:29 +0100 Subject: [PATCH 5/8] 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 a17a9e9eb..eeabdbfdc 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -140,7 +140,7 @@ closures of store paths. As an example, if the store object at path `P` contains a [reference] - to path `Q`, then `Q` is in the closure of `P`. Further, if `Q` + to store object `Q`, then `Q` is in the closure of `P`. Further, if `Q` references `R` then `R` is also in the closure of `P`. - [output path]{#gloss-output-path}\ From ec317949f9c27f00e292e65e0d956ed187a4fd63 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 27 Feb 2023 12:55:14 +0100 Subject: [PATCH 6/8] remove "references" as distinct term --- doc/manual/src/glossary.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index eeabdbfdc..28842834b 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -116,7 +116,6 @@ - [reference]{#gloss-reference}\ A [store object] `O` is said to have a *reference* to a store object `P` if a [store path] to `P` appears in the contents of `O`. - The *references* of a store object `O` are the set of store objects to which `O` has a reference. Store objects can refer to both other store objects and themselves. References from a store object to itself are called *self-references*. From b0c23999d265d5dca27f99cc0fb4c8ca111f42b2 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 27 Feb 2023 12:56:22 +0100 Subject: [PATCH 7/8] add link to definition --- 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 28842834b..03ccc1983 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -138,7 +138,7 @@ files could be missing. The command `nix-store -qR` prints out closures of store paths. - As an example, if the store object at path `P` contains a [reference] + As an example, if the [store object] at path `P` contains a [reference] to store object `Q`, then `Q` is in the closure of `P`. Further, if `Q` references `R` then `R` is also in the closure of `P`. From 1b49e6fea9ccca9ae2aa6b493040f8df46d63963 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 27 Feb 2023 13:04:54 +0100 Subject: [PATCH 8/8] use the term reference correctly --- 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 03ccc1983..d2feecb2f 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -139,7 +139,7 @@ closures of store paths. As an example, if the [store object] at path `P` contains a [reference] - to store object `Q`, then `Q` is in the closure of `P`. Further, if `Q` + to a store object at path `Q`, then `Q` is in the closure of `P`. Further, if `Q` references `R` then `R` is also in the closure of `P`. - [output path]{#gloss-output-path}\