nix-super/doc/manual/src/architecture/store/store.md

# Store

A Nix store is a collection of [store objects](objects.md) and associated operations.

These store objects can hold arbitrary data, and Nix makes no distinction if they are used as build inputs, build results, or build plans.

A Nix store allows to add and retrieve store objects.
It can perform builds, that is, transform build inputs using instructions from the build plans into build outputs.
It also keeps track of *references* between data and can therefore garbage-collect unused store objects.

There exist different types of stores, which all follow this model.
Examples:
- store on the local file system
- remote store accessible via SSH
- binary cache store accessible via HTTP

Every store with a file system representation has a *store directory*, which contains that store’s objects accessible through [store paths](paths.md).
The store directory defaults to `/nix/store`, but is in principle arbitrary.

## A Rosetta stone for the Nix store.

The design of Nix is comparable to other build systems, even programming languages in general.
Here is a rough [Rosetta stone](https://en.m.wikipedia.org/wiki/Rosetta_Stone) for build system terminology.
If you are familiar with one of these columns, this might help the following sections make more sense.

generic build system | Nix | Bazel | Build Systems à la Carte | lazy programming language
-- | -- | -- | -- | --
data (build input, build result) | component | file (source, target) | value | value
build plan | derivation graph | action graph | `Tasks` | thunk
build step | derivation | rule | `Task` | thunk
build instructions | builder | (depends on action type) | `Task` | function
build | build | build | `Build` applied to arguments | evaluation
persistence layer | store | file system | `Store` | heap

(n.b. Bazel terms gotten from https://docs.bazel.build/versions/main/glossary.html.)

Plenty more could be said elaborating these comparisons.
We will save that for the end of this chapter, in the [Related Work](./related-work.md) section.
-												remove separate meta-section, add architecture diagram

the diagram is a first approximation and only covers that same section.
of course there is much more going on, and other features should at some
point also be illustrated.

we also have to think about presentation format and technicalities
behind it. the manual has to render to `man`, but we may want something
more refined for web view.

											
										
										
											2022-04-27 22:17:44 +03:00
+								# Store
-												Add draft "Rosetta stone" by @fricklerhandwerk and stub commentary

The idea and most of the execution are @fricklerhandwerk's. I changed a
few things best I could based on @edolstra's corrections, and a Bazel
glossary.

Valentin Gagarin <valentin@fricklerhandwerk.de>

											
										
										
											2022-04-22 08:39:30 +03:00
-												reword section on Nix store

											
										
										
											2022-04-24 22:34:33 +03:00
+								A Nix store is a collection of [store objects](objects.md) and associated operations.
-												WIP: Document the design of Nix

The current docs are all "how to do things" and no "what is Nix" or "why
are things the way they are".

I see lots of misconception on the wider internet, and I also think we
would benefit from a "living document" to answer some questions people
currently turn to the thesis for.

I think a new section of the manual can address all these issues.

											
										
										
											2020-11-24 15:38:12 +02:00
-												reword section on Nix store

											
										
										
											2022-04-24 22:34:33 +03:00
+								These store objects can hold arbitrary data, and Nix makes no distinction if they are used as build inputs, build results, or build plans.
-												add concrete store examples, reword note on file system

											
										
										
											2022-04-28 02:15:27 +03:00
+								A Nix store allows to add and retrieve store objects.
 								It can perform builds, that is, transform build inputs using instructions from the build plans into build outputs.
 								It also keeps track of *references* between data and can therefore garbage-collect unused store objects.
-												reword section on Nix store

											
										
										
											2022-04-24 22:34:33 +03:00
-												add concrete store examples, reword note on file system

											
										
										
											2022-04-28 02:15:27 +03:00
+								There exist different types of stores, which all follow this model.
 								Examples:
 								- store on the local file system
 								- remote store accessible via SSH
 								- binary cache store accessible via HTTP
 								Every store with a file system representation has a *store directory*, which contains that store’s objects accessible through [store paths](paths.md).
 								The store directory defaults to `/nix/store`, but is in principle arbitrary.
-												Add draft "Rosetta stone" by @fricklerhandwerk and stub commentary

The idea and most of the execution are @fricklerhandwerk's. I changed a
few things best I could based on @edolstra's corrections, and a Bazel
glossary.

Valentin Gagarin <valentin@fricklerhandwerk.de>

											
										
										
											2022-04-22 08:39:30 +03:00
 								## A Rosetta stone for the Nix store.
 								The design of Nix is comparable to other build systems, even programming languages in general.
 								Here is a rough [Rosetta stone](https://en.m.wikipedia.org/wiki/Rosetta_Stone) for build system terminology.
 								If you are familiar with one of these columns, this might help the following sections make more sense.
 								generic build system | Nix | Bazel | Build Systems à la Carte | lazy programming language
 								-- | -- | -- | -- | --
 								data (build input, build result) | component | file (source, target) | value | value
 								build plan | derivation graph | action graph | `Tasks` | thunk
 								build step | derivation | rule | `Task` | thunk
 								build instructions | builder | (depends on action type) | `Task` | function
 								build | build | build | `Build` applied to arguments | evaluation
 								persistence layer | store | file system | `Store` | heap
 								(n.b. Bazel terms gotten from https://docs.bazel.build/versions/main/glossary.html.)
 								Plenty more could be said elaborating these comparisons.
 								We will save that for the end of this chapter, in the [Related Work](./related-work.md) section.