WIP: Document the design of Nix #4280
Conversation
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.
|
[For the record, let no one construe this as people writing more docs because markdown 😀. I go with the flow and prefer to write docs after the dust settles, but I do not like markdown.] |
|
Note that there is a lot of material in https://edolstra.github.io/pubs/phd-thesis.pdf (especially chapters 5 and 6) that we could reuse here, rather than start from scratch. |
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/documenting-the-design-of-nix/10177/1 |
|
|
||
| ## File system data | ||
|
|
||
| Nix supports the a similar model of the file system as Git. |
| 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. | ||
| 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.\] |
There was a problem hiding this comment.
There are quite a few occurrences of the word "store" in these sentences to the point where it gets confusing. Not sure how to resolve that though.
There was a problem hiding this comment.
This whole section is too advanced, so I moved it to a bonus topic at the end.
|
|
||
| Store entries can refer to both other store entries and themselves. | ||
|
|
||
| Store references are normally calculated by scanning the file system data for store paths when a new store entry is created, but this isn't mandatory, as store entries are allowed to have references that don't correspond to contained store paths, and contained store paths that don't correspond to references. |
There was a problem hiding this comment.
The use of "normally" makes me question if store references may be computed in other ways. I don't think that's the case, so perhaps removing "normally" would help.
Alternatively, "contained" might refer to "contained in the closure of a store path". The way it's used here sort of implies that's how closures are tracked.
There was a problem hiding this comment.
DRV files have references which are declared by fiat. Since then, addToStoreFromDump not just addTextToStore also allows this.
|
I marked this as stale due to inactivity. → More info |
There was a problem hiding this comment.
Ah, now I had a bunch of incomplete comments. @Ericson2314 hopefully most of this still applies. Now that the PR has become so big, can we maybe split his up somehow? For example, start with a PR just for the overview, and then add chapters one by one?
I'd prefer to have as little as possible but fairly polished text. Many people may end up reading this, and we want to be careful with their attentive resources.
Co-authored-by: Valentin Gagarin <valentin@fricklerhandwerk.de>
Co-authored-by: Valentin Gagarin <valentin@fricklerhandwerk.de>
Co-authored-by: Valentin Gagarin <valentin@fricklerhandwerk.de>
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/tweag-nix-dev-update-27/18433/1 |
Co-authored-by: Matthieu Coudron <teto@users.noreply.github.com>
|
Per https://discourse.nixos.org/t/documenting-what-is-nix/10177/2 @fricklerhandwerk and I (and hopefully you too!) will iterate on a separate branch, try to get the large scale structure / outline down, and then send PRs upstream as specific sections are ready. There is no way to modify the source branch of a PR, so closing this instead. |
|
#6420 too |
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.