From 610ddf44aa86924834bf2ac3735c7cb75a6a1f1c Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 25 Apr 2022 13:25:43 +0200 Subject: [PATCH] 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. --- doc/manual/src/architecture/architecture.md | 2 +- doc/manual/src/architecture/store/store.md | 29 ++++++++++----------- 2 files changed, 15 insertions(+), 16 deletions(-) diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md index b17eacd2e..836b40c91 100644 --- a/doc/manual/src/architecture/architecture.md +++ b/doc/manual/src/architecture/architecture.md @@ -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*. diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md index 624439f73..af0609d4b 100644 --- a/doc/manual/src/architecture/store/store.md +++ b/doc/manual/src/architecture/store/store.md @@ -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).