aboutsummaryrefslogtreecommitdiff
path: root/doc/manual/src/design/store
diff options
context:
space:
mode:
authorJohn Ericson <John.Ericson@Obsidian.Systems>2022-04-18 21:53:39 -0400
committerValentin Gagarin <valentin.gagarin@tweag.io>2022-08-04 12:37:46 +0200
commit4e2d5ae2027a19ab12d6d024cdf5125c3200a7a1 (patch)
tree43b1c86eeaf648244bda9bb1c2112f99dc897108 /doc/manual/src/design/store
parente308602fdfabf0ff1f0cd95baf1d90ba54a02281 (diff)
doc: Store entry -> store object
This matches the terminology in Eelco's thesis.
Diffstat (limited to 'doc/manual/src/design/store')
-rw-r--r--doc/manual/src/design/store/building.md4
-rw-r--r--doc/manual/src/design/store/drvs/drvs.md14
-rw-r--r--doc/manual/src/design/store/entries.md20
-rw-r--r--doc/manual/src/design/store/paths.md8
-rw-r--r--doc/manual/src/design/store/relocatability.md10
-rw-r--r--doc/manual/src/design/store/store.md2
6 files changed, 29 insertions, 29 deletions
diff --git a/doc/manual/src/design/store/building.md b/doc/manual/src/design/store/building.md
index 5adccbc0b..f97b74952 100644
--- a/doc/manual/src/design/store/building.md
+++ b/doc/manual/src/design/store/building.md
@@ -2,10 +2,10 @@
## Scanning for references
-Before in the section on [store entries](../entries.md), we talked abstractly about scanning for references.
+Before in the section on [store objects](../entries.md), we talked abstractly about scanning for references.
Now we can make this concrete.
-After the derivation's command is run, Nix needs to process the "raw" output directories to turn them into legit store entries.
+After the derivation's command is run, Nix needs to process the "raw" output directories to turn them into legit store objects.
There is a few steps of this, but let's start with the simple case of one input-addressed output first.
\[Overview of things that need to happen.]
diff --git a/doc/manual/src/design/store/drvs/drvs.md b/doc/manual/src/design/store/drvs/drvs.md
index 98e95809b..766a7b47f 100644
--- a/doc/manual/src/design/store/drvs/drvs.md
+++ b/doc/manual/src/design/store/drvs/drvs.md
@@ -1,23 +1,23 @@
# Derivations
-Derivations are recipes to create store entries.
+Derivations are recipes to create store objects.
Derivations are the heart of Nix.
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 comes in.
Derivations produce data by running arbitrary commands, like Make or Ninja rules.
-Unlike those systems, derivations do not produce arbitrary files, but only specific store entries.
-They cannot modify the store in any way, other than creating those store entries.
+Unlike those systems, derivations do not produce arbitrary files, but only specific store objects.
+They cannot modify the store in any way, other than creating those store objects.
This rigid specification of what they do is what allows Nix's caching to be so simple and yet robust.
Based on the above, we can conceptually break derivations down into 3 parts:
1. What command will be run?
-2. What existing store entries are needed as inputs?
+2. What existing store objects are needed as inputs?
-3. What store entries will be produced as outputs?
+3. What store objects will be produced as outputs?
## What command will be run?
@@ -30,12 +30,12 @@ Commands consist of 3 parts:
3. Environment variables.
-## What existing store entries are needed as inputs?
+## What existing store objects are needed as inputs?
The previous sub-section begs the question "how can we be sure the path to the executable points to what we think it does?"
It's a good questions!
-## What store entries will be produced as outputs?
+## What store objects will be produced as outputs?
## Extra extensions
diff --git a/doc/manual/src/design/store/entries.md b/doc/manual/src/design/store/entries.md
index 74f429e78..ddfefa166 100644
--- a/doc/manual/src/design/store/entries.md
+++ b/doc/manual/src/design/store/entries.md
@@ -1,10 +1,10 @@
-# Store Entries
+# Store Objects
-File system data in Nix is organized into *store entries*.
-A store entry is the combination of
+File system data in Nix is organized into *store objects*.
+A store object is the combination of
- some file system data
- - references to store entries
+ - references to store objects
## File system data
@@ -17,7 +17,7 @@ In particular, every file system object falls into these three cases:
File children additionally have an executable flag.
- Symlink: may point anywhere.
- In particular, Symlinks that do not point within the containing file system data or that of another store entry referenced by the containing store entry are allowed, but might not function as intended.
+ In particular, Symlinks that do not point within the containing file system data or that of another store object referenced by the containing store object are allowed, but might not function as intended.
A bare file as the "root" file system object is allowed.
Note that it cannot be executable, though.
@@ -27,15 +27,15 @@ Without a flag saying which, whether root files are executable or non-executable
## References
-Store entries can refer to both other store entries and themselves.
+Store objects can refer to both other store objects and themselves.
-References are normally calculated by scanning the file system data for store paths (which we describe in the next section) referring to store entries.
-For now, it suffices to say that a store path is a string encoding of a reference to a store paths, and therefore it is something that we can search for in the contents of files, and thus in store entries by searching in all their files.
+References are normally calculated by scanning the file system data for store paths (which we describe in the next section) referring to store objects.
+For now, it suffices to say that a store path is a string encoding of a reference to a store paths, and therefore it is something that we can search for in the contents of files, and thus in store objects by searching in all their files.
When we get to building in a future section, this process will be described in precise detail.
However, scanning for references is not mandatory.
-Store entries are allowed to have official references that *don't* correspond to store paths contained in their contents,
+Store objects are allowed to have official references that *don't* correspond to store paths contained in their contents,
and they are also allowed to *not* have references that *do* correspond to store paths contained in their store.
Taken together, this means there is no actual rule relating the store paths contained in the contents to the store paths deemed references.
-This is why it's its necessary for correctness, and not just performance, that Nix remember the references of each store entry, rather than try to recompute them on the fly by scanning their contents.
+This is why it's its necessary for correctness, and not just performance, that Nix remember the references of each store object, rather than try to recompute them on the fly by scanning their contents.
diff --git a/doc/manual/src/design/store/paths.md b/doc/manual/src/design/store/paths.md
index 18ba27ecb..d7d2ef960 100644
--- a/doc/manual/src/design/store/paths.md
+++ b/doc/manual/src/design/store/paths.md
@@ -39,12 +39,12 @@ Some of the details will be saved for later.
Store paths are either content-addressed or "input-addressed".
-Content addressing means that the digest ultimately derives from referred store entry's file system data and references, and thus can be verified (if one knows how it was calculated).
+Content addressing means that the digest ultimately derives from referred store object's file system data and references, and thus can be verified (if one knows how it was calculated).
Input addressing means that the digest derives from how the store path was produced -- the "inputs" and plan that it was built from.
-Store paths of this sort can not be validated from the content of the store entry.
-Rather, the store entry might come with the store path it expects to be referred to by, and a signature of that path, the contents of the store path, and other metadata.
-The signature indicates that someone is vouching for the store entry really being the results of a plan with that digest.
+Store paths of this sort can not be validated from the content of the store object.
+Rather, the store object might come with the store path it expects to be referred to by, and a signature of that path, the contents of the store path, and other metadata.
+The signature indicates that someone is vouching for the store object really being the results of a plan with that digest.
While metadata is included in the digest calculation explaining which method it was calculated by, this only serves to thwart pre-image attacks.
That metadata is scrambled with everything else so that it is difficult to tell how a given store path was produced short of a brute-force search.
diff --git a/doc/manual/src/design/store/relocatability.md b/doc/manual/src/design/store/relocatability.md
index 04b581459..5cdbe9486 100644
--- a/doc/manual/src/design/store/relocatability.md
+++ b/doc/manual/src/design/store/relocatability.md
@@ -1,15 +1,15 @@
-## Advanced Topic: store entry relocatability
+## Advanced Topic: store object relocatability
-Now that we know the fundamentals of the design of the Nix store, let's explore one consequence of that design: the question when it is permissable to relocate a store entry to a store with a different mount point.
+Now that we know the fundamentals of the design of the Nix store, let's explore one consequence of that design: the question when it is permissable to relocate a store object to a store with a different mount point.
Recall from the section on [store paths](./store-paths.md), concrete store paths look like `<store-dir>/<hash>-<name>`.
~~The two final restrictions of the previous section yield an alternative view of the same information.~~
-Rather than associating store dirs with the references, we can say a store entry itself has a store dir if and only if it has at least one reference.
+Rather than associating store dirs with the references, we can say a store object itself has a store dir if and only if it has at least one reference.
-This corresponds to the observation that a store entry with references, i.e. with a store directory under this interpretation, is confined to stores sharing that same store directory, but a store entry without any references, i.e. thus without a store directory, can exist in any store.
+This corresponds to the observation that a store object with references, i.e. with a store directory under this interpretation, is confined to stores sharing that same store directory, but a store object without any references, i.e. thus without a store directory, can exist in any store.
Lastly, this illustrates the purpose of tracking self references.
-Store entries without self-references or other references are relocatable, while store paths with self-references aren't.
+Store objects without self-references or other references are relocatable, while store paths with self-references aren't.
This is used to tell apart e.g. source code which can be stored anywhere, and pesky non-reloctable executables which assume they are installed to a certain path.
\[The default method of calculating references by scanning for store paths handles these two example cases surprisingly well.\]
diff --git a/doc/manual/src/design/store/store.md b/doc/manual/src/design/store/store.md
index c2431f1c5..e91f0f6e4 100644
--- a/doc/manual/src/design/store/store.md
+++ b/doc/manual/src/design/store/store.md
@@ -1,4 +1,4 @@
-A Nix store is a collection of *store entries* referred to by *store paths*.
+A Nix store is a collection of *store objects* referred to by *store paths*.
Every store also has a "store directory path", which is a path prefix used for various purposes.
There are many types of stores, but all of them at least respect this model.