max/nix-super
1
0
Fork 0
mirror of https://github.com/privatevoid-net/nix-super.git synced 2024-11-10 08:16:15 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions
13096 commits 7 branches 0 tags 62 MiB
Commit graph

1550 commits

Author SHA1 Message Date
Eelco Dolstra
4eb566603a
Comment out the architecture section 
This needs more review and probably should be a separate book.
 2022-08-05 11:01:40 +02:00
Adam Joseph
1b97f3872e !fixup: transposed characters 2022-08-04 14:22:14 -07:00
Adam Joseph
62674659ed !fixup capitalize Nix 2022-08-04 14:21:17 -07:00
Adam Joseph
8f44d24c52 !fixup whitespace 2022-08-04 14:19:25 -07:00
Adam Joseph
56d4fc194b fourth trust condition: FODs 2022-08-04 14:14:24 -07:00
Adam Joseph
a5be5e0120 doc/manual: define {local,remote} store, binary cache, substituter 
Nix veterans intuitively know what the following terms mean.  They are
used in several places in the nix documentation, but never defined:

- local store
- remote store
- binary cache
- substituter

In particular, I found the last two terms to be confusingly similar.
Let's give definitions for them.
 2022-08-04 14:07:06 -07:00
John Ericson
39d32ac4c6 Add disclaimer that arch section is WIP and links may rot 
So we can iterate without worrying so much.
 2022-08-04 14:02:58 -04:00
John Ericson
6f6498f59c Remove header fragments which is not needd 2022-08-04 14:02:38 -04:00
John Ericson
016d7a8f78 Fix rosetta stone file name 2022-08-04 14:02:19 -04:00
John Ericson
b430a6743c Remove sections within from SUMMARY 2022-08-04 14:01:55 -04:00
John Ericson
bc118854d0 Merge remote-tracking branch 'upstream/master' into doc-what-is-nix 2022-08-04 09:11:42 -04:00
Valentin Gagarin
b631742277 fix page rendering 
apparently it is not possible to link to page anchors with `mdBook`[1]

[1]: https://github.com/rust-lang/mdBook/issues/167
 2022-08-04 14:31:33 +02:00
Domen Kožar
7d1280bbaf
Merge pull request #6678 from abathur/update_darwin_uninstall 
doc: update darwin uninstall instructions
 2022-08-04 14:09:09 +02:00
Valentin Gagarin
cc3a5f4ba2 use correct mdBook syntax for callouts 2022-08-04 14:04:14 +02:00
Valentin Gagarin
8cec32e7f5 fix directory tree renderings 2022-08-04 13:51:35 +02:00
Domen Kožar
84a26882f8
Update doc/manual/src/installation/installing-binary.md 
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
 2022-08-04 06:23:45 -05:00
Domen Kožar
3c2de2da01
Update doc/manual/src/installation/installing-binary.md 
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
 2022-08-04 06:23:36 -05:00
Valentin Gagarin
3df1ee2ba5 clarify what explicitly declaring certain dependencies means 2022-08-04 12:37:48 +02:00
Valentin Gagarin
b7309ce624 move architecture to the end 2022-08-04 12:37:48 +02:00
Valentin Gagarin
00a7eaed67 add file system object to table of contents 2022-08-04 12:37:48 +02:00
Valentin Gagarin
db6faf44a9 clarify what store objects can be 
the store of course makes a distinction, but that is not relevant here
 2022-08-04 12:37:48 +02:00
Valentin Gagarin
0228eb8ae7 add Java example on manual dependency declaration 2022-08-04 12:37:48 +02:00
Valentin Gagarin
29c062537d hashes: truncate -> reduce, mention SHA-256 
the longer SHA-256 hashes are not truncated, but in fact processed.

Co-authored-by: Thomas <twatson52@mac.com>
 2022-08-04 12:37:48 +02:00
Valentin Gagarin
9cabba1fc3 mention hard links 
Co-authored-by: Thomas <twatson52@mac.com>
 2022-08-04 12:37:48 +02:00
Valentin Gagarin
bac86231ad use "build plan" consistently 2022-08-04 12:37:47 +02:00
Valentin Gagarin
5a5a95696f note customized base32 
Nix omits E O U T characters for some reason.
 2022-08-04 12:37:47 +02:00
Valentin Gagarin
de5dea45f7 use correct Nix entity 
Nix itself does care a lot about what type of store object you have.
 2022-08-04 12:37:47 +02:00
Valentin Gagarin
fe4c0b8d75 fix typo 
Co-authored-by: Thomas <twatson52@mac.com>
 2022-08-04 12:37:47 +02:00
Valentin Gagarin
def80d5777 add subsections to table of contents 2022-08-04 12:37:47 +02:00
Valentin Gagarin
c345345dee concept map: align hights 
this has the weird but nice emergent property that terms at the same
height are roughly at the same level of abstraction.
 2022-08-04 12:37:47 +02:00
Valentin Gagarin
a28d6878b2 concept map: put closure as it is in the chapter 
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.
 2022-08-04 12:37:47 +02:00
Valentin Gagarin
475a332025 make concept map even more compact 2022-08-04 12:37:47 +02:00
Valentin Gagarin
d8b2f9f772 make concept map more compact 
invert arrows to/from derivation:
- we need closures to form derivations
- we need derivations to perform builds
 2022-08-04 12:37:47 +02:00
Valentin Gagarin
348432f48f store: add concept map 
this should help nativate the chapter by indicating which terms should
be known to understand a given concept.
 2022-08-04 12:37:47 +02:00
Valentin Gagarin
ec43977553 store: match chapter introduction to outline 
the various levels of detail should describe the same things.
 2022-08-04 12:37:47 +02:00
Valentin Gagarin
7c656d90ca simplify description of diagram 
try not to be too fancy, it's just for reading the diagram out loud.
 2022-08-04 12:37:47 +02:00
Valentin Gagarin
631ca18ee6 reword notes on copying 
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.
 2022-08-04 12:37:47 +02:00
Valentin Gagarin
c10dcccccd make example a simple list 
using JSON notation is unwarranted and not explained.
 2022-08-04 12:37:47 +02:00
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
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
John Ericson
e4eea5e84e Include abstract syntax based on the thesis for FSOs 
See https://edolstra.github.io/pubs/phd-thesis.pdf, page 91.
 2022-08-04 12:37:46 +02:00
John Ericson
b98dc3b19c store objects, better opining sentances 2022-08-04 12:37:46 +02:00
John Ericson
55b437b551 Improve store path section 2022-08-04 12:37:46 +02:00
John Ericson
b4df351880 Relocability -> relocation in store object title 2022-08-04 12:37:46 +02:00
John Ericson
5f4d2ac091 Improve store object section 
In particular, Nix is *not* like Git, so that needs to be fixed.
 2022-08-04 12:37:46 +02:00
John Ericson
1bbad62c7d doc: File system data -> file system object, to match Nix 2022-08-04 12:37:46 +02:00
John Ericson
838ba26fda Rename files after store entry -> store object rename 2022-08-04 12:37:46 +02:00
John Ericson
4e2d5ae202 doc: Store entry -> store object 
This matches the terminology in Eelco's thesis.
 2022-08-04 12:37:46 +02:00
John Ericson
e308602fdf Update doc/manual/src/design/store/drvs/drvs.md 
Co-authored-by: Matthieu Coudron <teto@users.noreply.github.com>
 2022-08-04 12:37:46 +02:00
John Ericson
cdb0bf3b65 Update doc/manual/src/design/overview.md 
Co-authored-by: Valentin Gagarin <valentin@fricklerhandwerk.de>
 2022-08-04 12:37:46 +02:00
John Ericson
75c5191a1f Update doc/manual/src/design/overview.md 
Co-authored-by: Valentin Gagarin <valentin@fricklerhandwerk.de>
 2022-08-04 12:37:46 +02:00
John Ericson
a04340f9a1 Update doc/manual/src/design/overview.md 
Co-authored-by: Valentin Gagarin <valentin@fricklerhandwerk.de>
 2022-08-04 12:37:46 +02:00
John Ericson
f5386d7059 Fix stub file's name 2022-08-04 12:37:46 +02:00
John Ericson
678d75baea Start on the derivations section 2022-08-04 12:37:46 +02:00
John Ericson
e3a0209a9e Move the bits on relocating store entires to the end 
They are too advanced for up front.
 2022-08-04 12:37:46 +02:00
John Ericson
a210504bc7 Apply suggestions from code review 2022-08-04 12:37:46 +02:00
John Ericson
e64633f98f Flesh out TOC 2022-08-04 12:37:46 +02:00
John Ericson
a2b3160f28 Briefly describe the digest of a store path 2022-08-04 12:37:46 +02:00
John Ericson
523359d133 WIP: Document the design of Nix 
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.
 2022-08-04 12:37:46 +02:00
Valentin Gagarin
499ed26508 manual: remove "Writing Nix Expressions" chapter 
it is out of date, all over the place in level of detail, is really
about `nixpkgs`, and in general instructions should not be part of
a reference manual.

also:
- update redirects and internal links
- use "Nix language" consistently
 2022-08-04 11:59:25 +02:00
Théophane Hufschmitt
7d1ccd9105
Merge pull request #6846 from fricklerhandwerk/values 
manual: use subheadings for primitive types
 2022-08-03 14:50:41 +02:00
Théophane Hufschmitt
c55bea4204 Fix the html id of the list headers 2022-08-03 14:16:00 +02:00
Valentin Gagarin
ceed4d4142 encode primitive as list with anchors 
to make it consistent with builtins and configuration options
 2022-08-03 11:25:41 +02:00
K900
f675ba5331
doc/distributed-builds: don't use deprecated alias 
`nix ping-store` -> `nix store ping`.
 2022-08-01 13:50:35 +03:00
Valentin Gagarin
27138f1ec6
manual: use singular in body, too 
Co-authored-by: Cole Helbling <cole.e.helbling@outlook.com>
 2022-07-28 23:30:07 +02:00
Valentin Gagarin
41a3b315fd manual: values -> data types 2022-07-28 17:25:25 +02:00
Valentin Gagarin
8f4fab8fab manual: use singular for headings 2022-07-28 17:25:18 +02:00
Valentin Gagarin
4ff48854b8 manual: simple values -> primitives 
"simple" is a loaded term
 2022-07-28 17:23:57 +02:00
Valentin Gagarin
3063e5b94c manual: use subheadings for primitive types 
this gives us HTML anchors for each of them
 2022-07-28 17:23:57 +02:00
Valentin Gagarin
85cdaebcd6 manual: set -> attribute set 
reword description to have shorter sentences.
 2022-07-28 16:10:24 +02:00
Valentin Gagarin
be4654c344 manual: fix section title in table of contents 2022-07-28 15:55:41 +02:00
Théophane Hufschmitt
7ed91d6c6a
Merge branch 'master' into parallel-nix-copy 2022-07-20 10:05:34 +02:00
Eelco Dolstra
28e913c605 Branch 2.10 release notes 2022-07-11 21:10:23 +02:00
Eelco Dolstra
545383208e
Merge pull request #6777 from laalsaas/master 
Fix logical and typographical errors in nix-env man page
 2022-07-11 13:52:40 +02:00
Eelco Dolstra
517ce38dad Update release notes 2022-07-11 11:17:19 +02:00
laalsaas
eac211a171 Fix logical and typographical errors in nix-env man page 2022-07-10 12:30:17 +02:00
Théophane Hufschmitt
6fa95c35c7
Add a release notes entry for #4914 
cc @gytis-ivaskevicius
 2022-07-06 06:46:54 +02:00