document the store concept#9206
Conversation
fricklerhandwerk
force-pushed
the
doc-store-object
branch
from
f0bd83d to
bbc1e5f
Compare
Ericson2314
left a comment
Ericson2314
left a comment
There was a problem hiding this comment.
I think this is good for now.
I would like to rework the intro store page a lot eventually, as I think it should introduce the purpose / layer more than individual stores, but I don't think bikeshedding at this time is the right way to do that. I think we should instead accept this, move on to more constituent pages, and then circle back to the main page at the end.
After all, it is easiest to introduce something once we know what we are introducing :).
| @@ -0,0 +1,84 @@ | |||
| # Nix Store | |||
|
|
|||
| A Nix store is a collection of *store objects* with references between them. | |||
There was a problem hiding this comment.
This should say something to explain what the store concept is for, e.g.
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.
| A store object consists of | ||
|
|
||
| - A [file system object] as data | ||
| - A set of [store paths](@docroot@/glossary.md#gloss-store-path) as references to other store objects |
There was a problem hiding this comment.
Note that in Nix, only top-level FSOs have references. We do not keep track of the references of subdirectories. So references are really metadata that the store keeps per path.
There was a problem hiding this comment.
Yes this was supposed to be the "fields" of a store object, the first item is the root file system object.
(Or equivalently, from a functional programming perspective, "has" vs "refers to" doesn't really mater, and a file system object conceptually includes its children.)
Not really sure how to phrase this right, but do want to keep it simple, maybe:
- A set of [store paths](@docroot@/glossary.md#gloss-store-path) as references to other store objects
- A [file system object] treeon the previous line?
There was a problem hiding this comment.
(FWIW between hardlinks, FUSE, and other such things, I think "has own copy" vs "refers to with implementation-level reference (as opposed to store path)" are not really interface-level distinctions, since this stuff is immutable.
| [ store ] ---> add ----> [ store' ] | ||
| | | ||
| V | ||
| [ reference ] |
There was a problem hiding this comment.
I have a hard time parsing these graphs. Why not just a pseudo-code type signature like
add :: Store -> FSO -> (Store, Reference)
or something imperative
Reference Store::add(FSO)
Another issue: addToStore() does not return a "reference" but a StorePath. Maybe better to stick to the terminology used in the code, to minimize the gap between the architectural docs and the implementation.
| As a store keeps track of references, it can [garbage-collect] unused store objects. | ||
| This will remove all store objects not [reachable] from garbage collector roots. | ||
|
|
||
| [ store ] --> collect garbage --> [ store' ] |
There was a problem hiding this comment.
| [ store ] --> collect garbage --> [ store' ] |
GC is an example of why the purely functional notation doesn't really work: GC is not a function from a store to store, it's a process which isn't necessarily fully serializable with other concurrent operations on the same store. Probably better to describe it in terms of its pre- and post-conditions.
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-10-23-documentation-team-meeting-notes-88/34562/1 |
reword the glossary to link to more existing information instead of repeating it. move the store documentation to the top of the table of contents, in front of the Nix language. this will provide a natural place to document other aspects of the store as well as the various store types. move the package management section after the Nix language and before Advanced Topics to follow the pattern to layer more complex concepts on top of each other. this structure of the manual will also nudge beginners to learn Nix bottom-up and hopefully make more likely that they understand underlying concepts first before delving into complex use cases that may or may not be easy to implement with what's currently there. Co-authored-by: John Ericson <git@JohnEricson.me>
fricklerhandwerk
force-pushed
the
doc-store-object
branch
from
5556860 to
1312ca2
Compare
|
@edolstra following @Ericson2314's suggestion this now only implements the purpose part and moves the package management section after the Nix language and before the Advanced Topics section. I'll implement the other suggestions in follow-up PRs; the overview page is supposed to have some substance. We should put that up somewhere visible. |
4 participants
Motivation
This is another step to finally implement #6420, and also serves as the documentation part of NixOS/rfcs#134
Context
Reword the glossary to link to more existing information instead of repeating it.
Move the store documentation to the top of the table of contents, in front of the Nix language. This will provide a natural place to document other aspects of the store as well as the various store types.
This structure of the manual will also nudge beginners to learn Nix bottom-up and hopefully make more likely that they understand underlying concepts first before delving into complex use cases that may or may not be easy to implement with what's currently there.
The sort of beginner who likes to dive straight into reference documentation should prefer this approach. Conversely, the sort of beginner who would prefer the opposite top-down approach of trying to solve problems before they understand everything that is going on is better off reading other tutorial/guide material on nix.dev anyways, and will just "random-access" the reference manual as a last resort. For such random-access the order doesn't matter, so this restructure doesn't make them any worse off.
Priorities
Add 👍 to pull requests you find important.