lix-project/lix
20
58
Fork 31
Code Issues 364 Code Review (Gerrit) Projects 3 Releases Wiki Activity

reword introduction to rosetta stone, add links

Browse source 
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.
This commit is contained in:
Valentin Gagarin 2022-04-25 13:25:43 +02:00
parent 5f96a0b4e8
commit 610ddf44aa
2 changed files with 15 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
doc/manual/src/architecture/architecture.md
View file

@ -27,7 +27,7 @@ Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_
At the top is the *command line interface*, translating from invocations of Nix executables to interactions with the underlying layers.
Below that is the *Nix language*, a [purely functional](https://en.m.wikipedia.org/wiki/Purely_functional_programming) configuration language.
It is used to compose expressions which ultimately evaluate to self-contained *build steps*, used to derive *build results* from referenced *build inputs*.
It is used to compose expressions which ultimately evaluate to self-contained *build plans*, used to derive *build results* from referenced *build inputs*.
::: {.note}
The Nix language itself does not have a notion of *packages* or *configurations*.

29
doc/manual/src/architecture/store/store.md
View file

@ -17,22 +17,21 @@ Examples:
Every store with a file system representation has a *store directory*, which contains that store’s objects accessible through [store paths](paths.md).
The store directory defaults to `/nix/store`, but is in principle arbitrary.
## A Rosetta stone for the Nix store.
## A [Rosetta stone](https://en.m.wikipedia.org/wiki/Rosetta_Stone) for build system terminology
The design of Nix is comparable to other build systems, even programming languages in general.
Here is a rough [Rosetta stone](https://en.m.wikipedia.org/wiki/Rosetta_Stone) for build system terminology.
If you are familiar with one of these columns, this might help the following sections make more sense.
The Nix store's design is comparable to other build systems.
Usage of terms is, for historic reasons, not entirely consistent within the Nix ecosystem, and still subject to slow change.
generic build system | Nix | Bazel | Build Systems à la Carte | lazy programming language
The following translation table points out similarities and equivalent terms, to help clarify their meaning and inform consistent use in the future.
generic build system | Nix | [Bazel](https://bazel.build/start/bazel-intro) | [Build Systems à la Carte](https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf) | programming language
-- | -- | -- | -- | --
data (build input, build result) | component | file (source, target) | value | value
build plan | derivation graph | action graph | `Tasks` | thunk
build step | derivation | rule | `Task` | thunk
build instructions | builder | (depends on action type) | `Task` | function
build | build | build | `Build` applied to arguments | evaluation
persistence layer | store | file system | `Store` | heap
data (build input, build result) | component | [artifact](https://bazel.build/reference/glossary#artifact) | value | value
build plan | derivation | [action](https://bazel.build/reference/glossary#action) | `Task` | [thunk](https://en.m.wikipedia.org/wiki/Thunk)
build graph | derivation graph | [action graph](https://bazel.build/reference/glossary#action-graph), [build graph](https://bazel.build/reference/glossary#build-graph) | `Tasks` | [call graph](https://en.m.wikipedia.org/wiki/Call_graph)
build instructions | builder | ([depends on action type](https://docs.bazel.build/versions/main/skylark/lib/actions.html)) | `Task` | function
build | realisation | build | application of `Build` | evaluation
persistence layer | store | [action cache](https://bazel.build/reference/glossary#action-cache) | `Store` | heap
(n.b. Bazel terms gotten from https://docs.bazel.build/versions/main/glossary.html.)
Plenty more could be said elaborating these comparisons.
We will save that for the end of this chapter, in the [Related Work](./related-work.md) section.
All of these systems share features of [declarative programming](https://en.m.wikipedia.org/wiki/Declarative_programming) languages, a key insight first put forward by Eelco Dolstra et al. in [Imposing a Memory Management Discipline on Software Deployment](https://edolstra.github.io/pubs/immdsd-icse2004-final.pdf) (2004), elaborated in his PhD thesis [The Purely Functional Software
Deployment Model](https://edolstra.github.io/pubs/phd-thesis.pdf) (2006), and further refined by Andrey Mokhov et al. in [Build Systems à la Carte](https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf) (2018).