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
Valentin Gagarin
fb2ec7e4ec
reword section on references
...
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.
2022-08-04 12:37:47 +02:00
Valentin Gagarin
90fc5b41a8
reword file system objects
...
- use singular for the "class"
- more consistency in type definition
- minor fixes in wording
2022-08-04 12:37:47 +02:00
Valentin Gagarin
e5e48593c8
move git comparison to related work
...
it should be pulled out of the branch before we go for merging
2022-08-04 12:37:47 +02:00
Valentin Gagarin
a145007a57
component -> store object, realisation -> build
2022-08-04 12:37:47 +02:00
Valentin Gagarin
40efe5b30b
build instrcution: Task -> function
2022-08-04 12:37:47 +02:00
Valentin Gagarin
ca5ebf6382
revert build plan/step distinction, reorder rows
2022-08-04 12:37:47 +02:00
Valentin Gagarin
610ddf44aa
reword introduction to rosetta stone, add links
...
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.
2022-08-04 12:37:47 +02:00
Valentin Gagarin
5f96a0b4e8
associated operations are not collected
...
Co-authored-by: John Ericson <git@JohnEricson.me>
2022-08-04 12:37:47 +02:00
Valentin Gagarin
070c85499b
fix grammar
...
Co-authored-by: John Ericson <git@JohnEricson.me>
2022-08-04 12:37:47 +02:00
Valentin Gagarin
7b5c00f67f
add concrete store examples, reword note on file system
2022-08-04 12:37:47 +02:00
Valentin Gagarin
c8c1b705ad
reword section on Nix store
2022-08-04 12:37:47 +02:00
Valentin Gagarin
39f01176a7
design -> architecture, add motivation
...
following ideas found in Architecture of Gazelle[1]
[1]: 56d35f8db0/Design.rst
2022-08-04 12:37:47 +02:00
Valentin Gagarin
d30033759a
address Nix language consistently as configuration language
2022-08-04 12:37:46 +02:00
Valentin Gagarin
7598126391
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-08-04 12:37:46 +02:00
Valentin Gagarin
34ea74c9ec
reword introductory section
...
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.
2022-08-04 12:37:46 +02:00
Valentin Gagarin
b387d80943
remove sentence for chapter transition
...
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.
2022-08-04 12:37:46 +02:00
John Ericson
89a7c956ff
Apply suggestions from code review
...
Co-authored-by: Valentin Gagarin <valentin@fricklerhandwerk.de>
2022-08-04 12:37:46 +02:00
Valentin Gagarin
51e6bed25e
do not mention implementation details
...
Co-authored-by: John Ericson <git@JohnEricson.me>
2022-08-04 12:37:46 +02:00
Valentin Gagarin
23ee0b24f7
correctly use comma for nesting
...
Co-authored-by: John Ericson <git@JohnEricson.me>
2022-08-04 12:37:46 +02:00
Valentin Gagarin
804e8bd747
indicate sequence with "then"
...
Co-authored-by: John Ericson <git@JohnEricson.me>
2022-08-04 12:37:46 +02:00
Valentin Gagarin
327ccd3b07
only use generic build system terminology
...
we will use a translation table to introduce nix-specific terms
2022-08-04 12:37:46 +02:00
Valentin Gagarin
0eae4bfad1
reword overview with clear terminology
...
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.
2022-08-04 12:37:46 +02:00
John Ericson
0737094161
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-08-04 12:37:46 +02:00
John Ericson
c86c1ec7e3
Make refernces sneak preview more concise
2022-08-04 12:37:46 +02:00
John Ericson
4e4bbd9e83
Improve store objects session more
2022-08-04 12:37:46 +02:00
