Commit graph

15326 commits

Author SHA1 Message Date
Valentin Gagarin
9c544813d7 paths -> path
use singular for terminology uniformly
2022-08-04 12:37:47 +02:00
Valentin Gagarin
1681f4e9f3 better explain reference scanning 2022-08-04 12:37:47 +02:00
Valentin Gagarin
fa7ad4593d explain store directory 2022-08-04 12:37:47 +02:00
Valentin Gagarin
f632816cba add explanation and examples of file system objects 2022-08-04 12:37:47 +02:00
Valentin Gagarin
84ddfbf8fd remove diagonal from operations diagram 2022-08-04 12:37:47 +02:00
Valentin Gagarin
93f721b0d2 remove draft on derivations 2022-08-04 12:37:47 +02:00
Valentin Gagarin
19d8a5d839 move first mention of file system object before diagram 2022-08-04 12:37:47 +02:00
Valentin Gagarin
a90fc62b61 make clear that file system is for processes
Co-authored-by: John Ericson <John.Ericson@Obsidian.Systems>
2022-08-04 12:37:47 +02:00
Valentin Gagarin
7993ba1f38 constrain garbage collection scope
garbage collection is now incremental, and may (in theory) never delete all unreferenced objects if it is slow enough.
2022-08-04 12:37:47 +02:00
Valentin Gagarin
195aa28ff7 references are added according to build task
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.
2022-08-04 12:37:47 +02:00
Valentin Gagarin
80de4a4804 operations diagram: store' to the right
this also looks more diverse, hopefully easier to distinguish

Co-authored-by: John Ericson <John.Ericson@Obsidian.Systems>
2022-08-04 12:37:47 +02:00
Valentin Gagarin
3794618cce add commas between output values 2022-08-04 12:37:47 +02:00
Valentin Gagarin
7b7e4c6340 use singular to match section heading 2022-08-04 12:37:47 +02:00
Valentin Gagarin
e63a768e21 use reference links for URLs 2022-08-04 12:37:47 +02:00
Valentin Gagarin
843288a451 add subsections for objects and references
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.
2022-08-04 12:37:47 +02:00
Valentin Gagarin
4341849193 move closure property to discussion references 2022-08-04 12:37:47 +02:00
Valentin Gagarin
445f753a82 replace pseudo code by diagrams
change prose description to visually resemble the data structure
2022-08-04 12:37:47 +02:00
Valentin Gagarin
db8703bcac use reference links for URLs 2022-08-04 12:37:47 +02:00
Valentin Gagarin
4adb6602bd clarify first sentence on store objects 2022-08-04 12:37:47 +02:00
Valentin Gagarin
4eb11d4592 fix grammar for clarity 2022-08-04 12:37:47 +02:00
Valentin Gagarin
b84f2bdfdd introduce mapping to Unix files and processes 2022-08-04 12:37:47 +02:00
Valentin Gagarin
207992a71d introduce store and store objects without file system details
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.
2022-08-04 12:37:47 +02:00
Valentin Gagarin
e72a7874dc beautify rosetta table
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.
2022-08-04 12:37:47 +02:00
Valentin Gagarin
b6b112b366 use reference links for URLs 2022-08-04 12:37:47 +02:00
Valentin Gagarin
d5eea66615 introduce build tasks
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.
2022-08-04 12:37:47 +02:00
Valentin Gagarin
7c3bca1372 revert to build plans in top-level overview
do not introduce build tasks yet, that is the next level of detail.
2022-08-04 12:37:47 +02:00
Valentin Gagarin
4639b36b53 use reference links for URLs 2022-08-04 12:37:47 +02:00
Valentin Gagarin
2303f84a68 revert to "build plan" in overview diagram
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.
2022-08-04 12:37:47 +02:00
Valentin Gagarin
25926c5fc6 Nix store does not underly literally everything
Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
2022-08-04 12:37:47 +02:00
Valentin Gagarin
0e63b9bf88 add link from overview to store section
the overview should only link to the three main concepts presented. the
store is now fairly fleshed out. others can follow later.
2022-08-04 12:37:47 +02:00
Valentin Gagarin
ef81276cc1 architecture overview: add link to command line reference 2022-08-04 12:37:47 +02:00
Valentin Gagarin
68d26010f6 architecture overview: add link to Nix expression language reference
update summary title to match file contents
2022-08-04 12:37:47 +02:00
Valentin Gagarin
75ce324052 use singular for class names consistently 2022-08-04 12:37:47 +02:00
Valentin Gagarin
689b32a543 clarify relation of tasks and plans 2022-08-04 12:37:47 +02:00
Valentin Gagarin
2a8532fb61 build rule -> build task
closer to "build systems a la carte", satisfies all other complaints
2022-08-04 12:37:47 +02:00
Valentin Gagarin
902638c519 build step -> build rule
"step" sounds atomic, while "rule" hints at internal structure, which in
our case consists of mapping inputs to outputs using build instructions.
2022-08-04 12:37:47 +02:00
Valentin Gagarin
87523f01e3 match grammatical case to arrow direction 2022-08-04 12:37:47 +02:00
Valentin Gagarin
d3effd014b update architecture diagram 2022-08-04 12:37:47 +02:00
Valentin Gagarin
ad8c2ed7f0 remove incomplete section: input/content-addressing 2022-08-04 12:37:47 +02:00
Valentin Gagarin
3bd125ebbe remove incomplete section: nix archives 2022-08-04 12:37:47 +02:00
Valentin Gagarin
b18852eb3f remove incomplete section: content-addressed objects 2022-08-04 12:37:47 +02:00
Valentin Gagarin
7cec9ee361 remove incomplete section: relocatability 2022-08-04 12:37:47 +02:00
Valentin Gagarin
96876b1eae remove incomplete section: related work 2022-08-04 12:37:47 +02:00
Valentin Gagarin
1ba6d8fb1d remove incomplete section: building 2022-08-04 12:37:47 +02:00
John Ericson
3d8f2f5cc1 Fix manual TOC links 2022-08-04 12:37:47 +02:00
John Ericson
b01bb65d30 Fix rel path in doc 2022-08-04 12:37:47 +02:00
Valentin Gagarin
b5ca3d12b6 reword details on keeping closure property 2022-08-04 12:37:47 +02:00
Valentin Gagarin
e90586c0a4 add motivation for references 2022-08-04 12:37:47 +02:00
Valentin Gagarin
07d490fd89 stores can also delete objects 2022-08-04 12:37:47 +02:00
Valentin Gagarin
5fda995491 formalize file system objects
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.
2022-08-04 12:37:47 +02:00