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).