lix-project/lix
20
55
Fork 31
Code Issues 344 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. 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. 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} ::: {.note}
The Nix language itself does not have a notion of *packages* or *configurations*. 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). 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. 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. The Nix store's design is comparable to other build systems.
Here is a rough [Rosetta stone](https://en.m.wikipedia.org/wiki/Rosetta_Stone) for build system terminology. Usage of terms is, for historic reasons, not entirely consistent within the Nix ecosystem, and still subject to slow change.
If you are familiar with one of these columns, this might help the following sections make more sense.
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 data (build input, build result) | component | [artifact](https://bazel.build/reference/glossary#artifact) | value | value
build plan | derivation graph | action graph | `Tasks` | thunk build plan | derivation | [action](https://bazel.build/reference/glossary#action) | `Task` | [thunk](https://en.m.wikipedia.org/wiki/Thunk)
build step | derivation | rule | `Task` | 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) | `Task` | function build instructions | builder | ([depends on action type](https://docs.bazel.build/versions/main/skylark/lib/actions.html)) | `Task` | function
build | build | build | `Build` applied to arguments | evaluation build | realisation | build | application of `Build` | evaluation
persistence layer | store | file system | `Store` | heap 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.) 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).
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.