Merge pull request #9232 from fricklerhandwerk/doc-store-object

document store objects in terms of their constituent parts
NixOS · Nov 2, 2023 · 8c99d40 · 8c99d40
2 parents 90de958 + 4ba8b18
commit 8c99d40
Show file tree

Hide file tree

Showing 5 changed files with 16 additions and 4 deletions.
diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
@@ -18,6 +18,7 @@
   - [Uninstalling Nix](installation/uninstall.md)
 - [Nix Store](store/index.md)
   - [File System Object](store/file-system-object.md)
+  - [Store Object](store/store-object.md)
 - [Nix Language](language/index.md)
   - [Data Types](language/values.md)
   - [Language Constructs](language/constructs.md)

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
@@ -63,7 +63,7 @@ The command line interface and Nix expressions are what users deal with most.
 > The Nix language itself does not have a notion of *packages* or *configurations*.
 > As far as we are concerned here, the inputs and results of a build plan are just data.
 
-Underlying the command line interface and the Nix language evaluator is the [Nix store](../glossary.md#gloss-store), a mechanism to keep track of build plans, data, and references between them.
+Underlying the command line interface and the Nix language evaluator is the [Nix store](../store/index.md), a mechanism to keep track of build plans, data, and references between them.
 It can also execute build plans to produce new data, which are made available to the operating system as files.
 
 A build plan itself is a series of *build tasks*, together with their build inputs.

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
@@ -59,7 +59,7 @@
 - [store]{#gloss-store}
 
   A collection of store objects, with operations to manipulate that collection.
-  See [Nix Store] for details.
+  See [Nix store](./store/index.md) for details.
 
   There are many types of stores.
   See [`nix help-stores`](@docroot@/command-ref/new-cli/nix3-help-stores.md) for a complete list.

diff --git a/doc/manual/src/store/index.md b/doc/manual/src/store/index.md
@@ -1,4 +1,5 @@
 # Nix Store
 
-The *Nix store* is an abstraction used by Nix to store immutable filesystem artifacts (such as software packages) that can have dependencies (*references*) between them.
-There are multiple implementations of the Nix store, such as the actual filesystem (`/nix/store`) and binary caches.
+The *Nix store* is an abstraction to store immutable file system data (such as software packages) that can have dependencies on other such data.
+
+There are multiple implementations of Nix stores with different capabilities, such as the actual filesystem (`/nix/store`) or binary caches.
diff --git a/doc/manual/src/store/store-object.md b/doc/manual/src/store/store-object.md
@@ -0,0 +1,10 @@
+## Store Object
+
+A Nix store is a collection of *store objects* with *references* between them.
+A store object consists of
+
+  - A [file system object](./file-system-object.md) as data
+  - A set of [store paths](@docroot@/glossary.md#gloss-store-path) as references to other store objects
+
+Store objects are [immutable](https://en.wikipedia.org/wiki/Immutable_object):
+Once created, they do not change until they are deleted.