Document what Nix is #6420

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.

They are too advanced for up front.

Co-authored-by: Valentin Gagarin <valentin@fricklerhandwerk.de>

Co-authored-by: Matthieu Coudron <teto@users.noreply.github.com>

This matches the terminology in Eelco's thesis.

In particular, Nix is *not* like Git, so that needs to be fixed.

See https://edolstra.github.io/pubs/phd-thesis.pdf, page 91.

@fricklerhandwerk

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>

trying to capture alternative terms in one go here, mirroring everyday use: derivation - build plan realise - execute build there will be more of that sort.

we will use a translation table to introduce nix-specific terms

Co-authored-by: John Ericson <git@JohnEricson.me>

Co-authored-by: Valentin Gagarin <valentin@fricklerhandwerk.de>

idea: sections could be read in different orders by linking them in different ways (e.g. depth-first or breadth-first). adding hard-coded transitions makes that confusing.

there should be a meta section for each chapter to give motivation of the presented structure. the structure itself is visible from the table of contents.

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.

following ideas found in Architecture of Gazelle[1] [1]: https://github.com/bazelbuild/bazel-gazelle/blob/56d35f8db086bb65ef876f96f7baa7b71516daf8/Design.rst

Co-authored-by: John Ericson <git@JohnEricson.me>

attempt to explain used and documented terminology, as well as how the declarative programming paradigm relates to building software. in the future one could highlight encouraged terms to shape future material into higher consistency.

it should be pulled out of the branch before we go for merging

- use singular for the "class" - more consistency in type definition - minor fixes in wording

use file Contents instead of Data, as that flows more naturally in the prose. simplify explanation of the idea behind scanning for store paths remove references to unfinished sections.

convention: describe every data type in prose, and illustrate with a class diagram, and a textual representation of an abstract data type. right now we save ourselves the trouble of doing class diagrams, we can add them later. but they are important.

"step" sounds atomic, while "rule" hints at internal structure, which in our case consists of mapping inputs to outputs using build instructions.

closer to "build systems a la carte", satisfies all other complaints

update summary title to match file contents

the overview should only link to the three main concepts presented. the store is now fairly fleshed out. others can follow later.

Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>

this displays correct composition again. build inputs and build results are not part of build plans in terms of data objects. also this is a much less complicated setup. this will be the first impression of architecture, and we want to get it right.

do not introduce build tasks yet, that is the next level of detail.

while it appears a bit much for the overview, this way we set the stage for going directly into data types when describing the store, instead of first having to say what build tasks are and how they relate to build plans.

while this may eventually introduce ugly diffs, the table will now render readably on the terminal (e.g. for `man nix` or `nix --help`) without further intervention.

this leaves open implementation details, especially about store paths and file system objects, and allows explaining them together were it is more appropriate. also leaves room to carefully introduce the key insight behind Nix: applying results from programming language theory to the operating system paradigm of files and processes.

change prose description to visually resemble the data structure

group description of data instead of spreading it across the section. that should help direct skimming. as it turns out, people do not actually read any of that.

this also looks more diverse, hopefully easier to distinguish Co-authored-by: John Ericson <John.Ericson@Obsidian.Systems>

at this level of abstraction we do not really care about build instructions or what they are, and also build instructions including their arguments really amount to the build task.

garbage collection is now incremental, and may (in theory) never delete all unreferenced objects if it is slow enough.

Co-authored-by: John Ericson <John.Ericson@Obsidian.Systems>

use singular for terminology uniformly

using JSON notation is unwarranted and not explained.

clarify that we are copying between different stores. we have not introduced that notion or why it would be interesting, but for now it should be fine to keep it in context of the store directory. we could move that later to a more detailed explanation of different store types.

try not to be too fancy, it's just for reading the diagram out loud.

the various levels of detail should describe the same things.

this should help nativate the chapter by indicating which terms should be known to understand a given concept.

invert arrows to/from derivation: - we need closures to form derivations - we need derivations to perform builds

this is not as compact any more, but it more closely resembles the chapter structure, and clearly shows that the closure property is the key idea on which most of Nix operates.

this has the weird but nice emergent property that terms at the same height are roughly at the same level of abstraction.

Co-authored-by: Thomas <twatson52@mac.com>

Nix itself does care a lot about what type of store object you have.

Nix omits E O U T characters for some reason.

Co-authored-by: Thomas <twatson52@mac.com>

the longer SHA-256 hashes are not truncated, but in fact processed. Co-authored-by: Thomas <twatson52@mac.com>

the store of course makes a distinction, but that is not relevant here

apparently it is not possible to link to page anchors with `mdBook`[1] [1]: rust-lang/mdBook#167

So we can iterate without worrying so much.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document what Nix is #6420

Document what Nix is #6420

Commits on Aug 4, 2022

Document what Nix *is* #6420

Document what Nix *is* #6420

Commits on Aug 4, 2022

Document what Nix is #6420

Document what Nix is #6420