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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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>
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.
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
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.
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'
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.
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}
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>
Ilya K