Commit graph

1730 commits

Author SHA1 Message Date
Travis A. Everett 4bd52bf6c4
Apply suggestions from code review
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2022-09-17 13:20:11 -05:00
Adam Joseph ad5b09423a release-notes/rl-next.md: note new argument to fetchurl.nix 2022-09-16 01:59:24 -07:00
Valentin Gagarin dc8c0b173c
Update doc/manual/src/contributing/hacking.md 2022-09-16 09:36:55 +02:00
Valentin Gagarin 1ae974120a
Update doc/manual/src/contributing/hacking.md 2022-09-16 09:36:37 +02:00
Valentin Gagarin 0a4bd9fe88
Update doc/manual/src/contributing/hacking.md 2022-09-16 09:36:30 +02:00
Valentin Gagarin 47fa1087c8
Update doc/manual/src/contributing/hacking.md 2022-09-16 09:36:20 +02:00
Valentin Gagarin 1d295e5fe7
Merge pull request #6934 from fricklerhandwerk/revert-architecture
Revert #6420 "Document what Nix *is*" so we can start over with smaller change sets
2022-09-09 13:31:05 +02:00
Valentin Gagarin 8dd5ba2f47 more precise variable types 2022-09-09 09:54:24 +02:00
Valentin Gagarin 548c904d40 optimize performance
remove loops and function calls, modify arrays in place

this makes the whole thing harder to read, and probably only
marginally faster.
2022-09-08 11:58:43 +02:00
Guillaume Maudoux eb460a9529 WIP: broken merge but need a git checkpoint 2022-09-07 00:34:03 +02:00
Valentin Gagarin 59be1e500a generalize anchor redirects
renaming section headers and changing manually set `id`s will break URLs
in the wild.

this change allows keeping track of all changes to ensure backwards
compatibility.
2022-09-06 00:49:16 +02:00
Adam Joseph e90f2fcfc7 glossary: add entry for chroot store (used 11 times in nix) 2022-09-01 18:28:05 -07:00
Adam Joseph e6f5352e71 #binary-cache -> #gloss-binary-cache 2022-09-01 18:27:00 -07:00
Adam Joseph 59dc8346ca move substituter signature-checking conditions to configuration file documentation 2022-09-01 17:51:56 -07:00
Adam Joseph f6c750e8b2 glossary: remove extraneous comma 2022-09-01 17:48:34 -07:00
Adam Joseph 887e922be2 glossary: outputHash, not __outputHash 2022-09-01 17:47:13 -07:00
Adam Joseph d5e064d816 glossary: fix broken link 2022-09-01 17:46:31 -07:00
Adam Joseph 57f12df5e4 input-addressed store object: include FODOs 2022-09-01 15:09:10 -07:00
Adam Joseph 8139bbe2ba implement https://github.com/NixOS/nix/pull/6870#pullrequestreview-1093700220 2022-09-01 15:01:07 -07:00
Adam Joseph def4fb9a0f __outputHash: add link 2022-09-01 14:47:33 -07:00
Adam Joseph 1b2b8c39fd fix link to language/advanced-attributes.md#adv-attr-contentAddressed 2022-09-01 14:47:17 -07:00
Adam Joseph 0a98d564b3 glossary: resolve FIXME in #gloss-fixed-output-derivation 2022-09-01 14:41:27 -07:00
Adam Joseph 1f56b5d772 doc/manual: un-inline definitions from substitute 2022-09-01 14:13:21 -07:00
Adam Joseph 41153f30bd glossary: substituter: merge output-addressed cases 2022-09-01 14:13:21 -07:00
Adam Joseph 9cb8412143
Update doc/manual/src/glossary.md
Co-authored-by: John Ericson <git@JohnEricson.me>
2022-09-01 20:41:04 +00:00
Adam Joseph 2812682ebe
Update doc/manual/src/glossary.md
Co-authored-by: John Ericson <git@JohnEricson.me>
2022-09-01 20:40:39 +00:00
Adam Joseph 520587b9a0 glossary: local store: clarify 2022-09-01 13:39:48 -07:00
Valentin Gagarin f35b3aa47b do not use unwarranted pkgs in example 2022-08-31 09:16:37 +02:00
Eelco Dolstra 1f2b12b30e
Merge pull request #6968 from fricklerhandwerk/man-no-weblinks
do not render relative links in help pages
2022-08-29 08:46:35 +02:00
Valentin Gagarin e7dcacbd7c do not render relative links in help pages
this simplifies the setup a lot, and avoids weird looking `./file.md`
links showing up.

it also does not show regular URLs any more. currently the command
reference only has few of them, and not showing them in the offline
documentation is hopefully not a big deal.

instead of building more special-case solutions, clumsily preprocessing
the input, or issuing verbal rules on dealing with URLs, should better
be solved sustainably by not rendering relative links in `lowdown`:

https://github.com/kristapsdz/lowdown/issues/105
2022-08-26 17:10:41 +02:00
Eelco Dolstra b0488a29dc Branch 2.11 release notes 2022-08-24 22:44:58 +02:00
Eelco Dolstra 04e74f7c8b
Merge pull request #6612 from NixOS/parallel-nix-copy
Make nix copy parallel again
2022-08-24 15:31:42 +02:00
Eelco Dolstra 4c96761c2b Merge remote-tracking branch 'origin/master' into parallel-nix-copy 2022-08-22 15:29:10 +02:00
Valentin Gagarin d8e54d19f7 Revert "Merge pull request #6420 from nix-community/doc-what-is-nix"
This reverts commit 81e101345f, reversing
changes made to 7d1280bbaf.
2022-08-22 12:52:15 +02:00
Andrei Boar 50f5b6c733
Update doc/manual/src/command-ref/env-common.md
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2022-08-19 12:28:51 +03:00
Andrei Boar 82b867d0b5 cover empty string case 2022-08-19 11:51:32 +03:00
Valentin Gagarin 703b335c1d reword description of language properties
the list style is supposed to give more structure.
each property is explained as concisely as possible while trying not to
sound too fancy.
2022-08-15 11:34:39 +02:00
Valentin Gagarin 71e9c28694 reword introduction to overview 2022-08-15 11:15:03 +02:00
Valentin Gagarin bc315326fa fix whitespace to please markdown
keep some indentation to ease source readability
2022-08-15 11:13:05 +02:00
Valentin Gagarin 6ba8d6dc82 add more examples on string interpolation 2022-08-15 11:06:40 +02:00
Valentin Gagarin c209e6e108 add more list examples 2022-08-15 10:18:56 +02:00
Valentin Gagarin 0378531bf2 add curried function 2022-08-15 10:18:56 +02:00
Valentin Gagarin 2e4704ca93 add second @ pattern example 2022-08-15 10:18:56 +02:00
Valentin Gagarin 5c25bdee50 add null 2022-08-15 10:18:56 +02:00
Valentin Gagarin 391fd10b12 add home path 2022-08-15 10:18:56 +02:00
Valentin Gagarin 587ae9ada5 add search path 2022-08-15 10:18:56 +02:00
Valentin Gagarin 21438acc70 add absolute path 2022-08-15 10:18:56 +02:00
Valentin Gagarin e6f7c180de add floating point number 2022-08-15 10:18:56 +02:00
Valentin Gagarin 292cab039d add multi-line string 2022-08-15 10:18:56 +02:00
Valentin Gagarin f165a8ae08 flarify relative path semantics 2022-08-15 10:18:56 +02:00
Valentin Gagarin 43188d3d18 make hash and version distinguishable as placeholder 2022-08-15 10:18:56 +02:00
Valentin Gagarin 90836397d3 remove stale section link 2022-08-15 10:18:56 +02:00
Valentin Gagarin 3378a3bce8 add syntax overview from NixOS manual
taken verbatim to keep track of required corrections.

made it an HTML table to more easily change structure and keep diffs
minimal.
2022-08-15 10:18:56 +02:00
Eelco Dolstra af4e8b00fb
Merge pull request #6882 from DeterminateSystems/allow-multi-user-as-root
Allow installing multi-user as root on macOS and Linux
2022-08-12 10:19:03 +02:00
Graham Christensen 7bb1e913b3 Don't prompt about using sudo if we're already root 2022-08-10 09:37:08 -04:00
Graham Christensen 88a0f3b6ba Strip whitespace in installing-binary.md 2022-08-10 09:37:08 -04:00
Adam Joseph bac1e1bf8c
Update doc/manual/src/glossary.md
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2022-08-08 17:52:31 +00:00
Travis A. Everett 9b7bd2dd1f
Apply suggestions from code review
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2022-08-08 10:04:27 -05:00
Travis A. Everett b5d85f0922
Apply suggestions from code review
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2022-08-05 13:49:18 -05:00
Adam Joseph 1d3b92e80c move package-management/terminology into glossary.md 2022-08-05 10:39:43 -07:00
Adam Joseph 4de95f7f56 gesture at explanation of why binary caches exist 2022-08-05 10:33:48 -07:00
Adam Joseph d5506aa712
Update doc/manual/src/package-management/terminology.md
Co-authored-by: Attila Gulyas <toraritte@gmail.com>
2022-08-05 17:19:52 +00:00
Adam Joseph 66a93a76b9
Update doc/manual/src/package-management/terminology.md
Co-authored-by: Attila Gulyas <toraritte@gmail.com>
2022-08-05 17:15:37 +00:00
Adam Joseph 2eb74c918d derivations do not need to be signed 2022-08-05 10:13:41 -07:00
Adam Joseph aae771cad2 !implement https://github.com/NixOS/nix/pull/6870#discussion_r938912244 2022-08-05 10:12:46 -07:00
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
Andrei Boar 1c2c1a6e00
Update doc/manual/src/command-ref/env-common.md
Co-authored-by: Jan Tojnar <jtojnar@gmail.com>
2022-08-04 16:17:24 +03:00
John Ericson bc118854d0 Merge remote-tracking branch 'upstream/master' into doc-what-is-nix 2022-08-04 09:11:42 -04:00
Andrei Boar a8ac6a4120
Update doc/manual/src/command-ref/env-common.md
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2022-08-04 16:01:02 +03:00
Andrei Boar cedcfe861c Merge branch 'manual-nix-path-empty' of github.com:zuzuleinen/nix into manual-nix-path-empty 2022-08-04 15:56:13 +03:00
Andrei Boar f72545e864 update to suggested changes 2022-08-04 15:56:01 +03: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
Andrei Boar 6dfd8a78d9
Update doc/manual/src/command-ref/env-common.md
Co-authored-by: Eelco Dolstra <edolstra@gmail.com>
2022-08-04 15:04:52 +03: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
Andrei Boar 5a75aa8595 manual: update docs when NIX_PATH is empty 2022-08-04 14:19:51 +03: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
Ilya K 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
John Ericson 12461e246b Leverage existing docs for new store-path^outputs syntax 2022-07-15 14:04:22 +00:00
John Ericson 279ecf7cde Remove computed-derivations experimental feature
We don't need it yet.
2022-07-15 13:42:17 +00:00
John Ericson 6cafe308c9 Merge remote-tracking branch 'upstream/master' into indexed-store-path-outputs 2022-07-14 16:15:37 -04: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
Travis A. Everett 649c9d9b4c doc: acknowledge post-rsync reality
Before #5150 the copy-to-store phase of the install was idempotent,
but the recursive cp isn't. This is probably baiting a few people
into trying corrective installs that will fail.
2022-06-30 13:31:04 -05:00
Travis A. Everett fe76b9f4b4 doc: fix some darwin uninstall gaps 2022-06-16 09:37:52 -05:00
Tom Bereknyei 51268ceb79 Merge branch 'master' into nix-repl-flakes 2022-06-15 09:17:03 -04:00
tomberek dae4a8a6c8
Apply suggestions from code review
Co-authored-by: Théophane Hufschmitt <7226587+thufschmitt@users.noreply.github.com>
2022-06-15 09:02:36 -04:00
Hugo Osvaldo Barrera fd7f795750 Add disambiguation to man page
This should help future lost newcomers like myself understand where to
find the docs for both of these commands and how they differ.
2022-06-14 18:13:35 +02:00
Travis A. Everett edfcc8256e doc: add install test info to hacking.md 2022-06-11 13:30:51 -05:00
Théophane Hufschmitt 34d90fbe22 Mention the parallel copy in the release notes 2022-06-08 15:25:52 +02:00
Tom Bereknyei ffd41d1757 Merge branch 'master' into nix-repl-flakes 2022-06-02 16:58:35 -04:00
John Ericson b585548dfe Merge remote-tracking branch 'upstream/master' into indexed-store-path-outputs 2022-06-02 19:53:11 +00:00
Théophane Hufschmitt a5f7b934bd
Merge branch 'master' into lto 2022-06-01 17:55:03 +02:00
Eelco Dolstra 04a699b8a9
Typo 2022-05-31 10:38:03 +02:00
Eelco Dolstra de13b44573
Branch 2.9 release notes 2022-05-30 20:42:55 +02:00
Eelco Dolstra 8e8e9d8705
Respect the outputSpecified attribute
E.g. 'nix build nixpkgs#libxml2.dev' will build the 'dev' output.
2022-05-30 11:34:47 +02:00
Eelco Dolstra d67a2ae52d
Merge branch 'doc-redirects' of https://github.com/jtojnar/nix 2022-05-27 11:12:41 +02:00
Jan Tojnar 26d1877d6e doc: Add redirects for the DocBook manual
There are still many links to the old manual on the web and
having them end up on the Introduction page is a bad user experience.
2022-05-26 18:17:21 +02:00
Jan Tojnar a793863b97 doc: Manually insert some anchors 2022-05-26 18:17:21 +02:00
Jan Tojnar 7708a34a51 doc: Add anchors to long lists
Added using the following sed scripts:

- For command-ref/opt-common.md:

    s~- `(--?)([^`]+)`~- [`\1\2`]{#opt-\2}~g

- For expressions/builtin-constants.md:

    s~- `(builtins\.?)([^`]+)`~- [`\1\2`]{#builtins-\2}~g

- For expressions/advanced-attributes.md

    s~^  - `([^`]+)`~  - [`\1`]{#adv-attr-\1}~g

  and manually adjusted outputHashAlgo & outputHashMode.

- For glossary.md

    s~^  - (`([^`]+)`|(.+)) ?\\~  - [\1]{#gloss-\2\3}\\~g;
    s~(gloss-\w+) ~\1-~g

  and manually adjusted anchors for Nix expression, user environment, NAR, ∅ and ε.

- For command-ref/env-common.md

    s~^  - `([^`]+)`~  - [`\1`]{#env-\1}~g'
2022-05-26 18:17:21 +02:00
Jan Tojnar 3272afa17b doc: Port anchors preprocessor to jq script
Python is only pulled into the build closure by Mercurial, which might end up being removed.
Let’s port the script to jq, which is more likely to stay.
2022-05-26 18:17:21 +02:00
Jan Tojnar 4de84e095d doc: Introduce pre-processor for adding anchors to text
It is now possible to use the following syntax to insert anchors into the text:

    []{#anchor-name}

The anchor will allow linking to the location it is placed by appending #anchor-name to the URL.

Additionally, it is possible to create a link pointing to its own location by adding text between the square brackets:

    [`--add-root`]{#opt-add-root}
2022-05-26 17:54:15 +02:00
Eelco Dolstra 8f4548d401
Tweak IN_NIX_SHELL description 2022-05-26 12:40:01 +02:00
Ben Burdette 9a5ea6c359
Merge branch 'master' into debug-exploratory-PR 2022-05-25 10:41:10 -06:00
Ben Burdette 6031a36208 add --debugger to rl-next list 2022-05-25 10:38:13 -06:00
pennae b092afe77d
Merge branch 'master' into lto 2022-05-25 11:55:13 +00:00
Tom Bereknyei 82c4af41e3 repl: clarify change and usage of <nixpkgs> 2022-05-20 01:49:49 -04:00
Tony Olagbaiye 5b8c1deb18 fetchTree: Allow fetching plain files
Add a new `file` fetcher type, which will fetch a plain file over
http(s), or from the local file.

Because plain `http(s)://` or `file://` urls can already correspond to
`tarball` inputs (if the path ends-up with a know archive extension),
the URL parsing logic is a bit convuluted in that:

- {http,https,file}:// urls will be interpreted as either a tarball or a
  file input, depending on the extensions of the path part (so
  `https://foo.com/bar` will be a `file` input and
  `https://foo.com/bar.tar.gz` as a `tarball` input)
- `file+{something}://` urls will be interpreted as `file` urls (with
  the `file+` part removed)
- `tarball+{something}://` urls will be interpreted as `tarball` urls (with
  the `tarball+` part removed)

Fix #3785

Co-Authored-By: Tony Olagbaiye <me@fron.io>
2022-05-19 18:24:49 +02:00
Tom Bereknyei 1ca3f6035d repl: update docs with installables 2022-05-18 21:21:38 -04:00