add more explanation to diagrams

this is to help reading the diagrams, otherwise arrows and labels were
reported as being ambiguous.
This commit is contained in:
Valentin Gagarin 2022-12-20 09:59:59 +01:00
parent 4ed8bb1cb1
commit c162c90b43

View file

@ -9,18 +9,29 @@ Nix consists of [hierarchical layers].
[hierarchical layers]: https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers [hierarchical layers]: https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers
The following [concept map] shows its main components (rectangles), the objects they operate on (rounded rectangles), and their interactions (connecting phrases):
[concept map]: https://en.m.wikipedia.org/wiki/Concept_map
``` ```
+---------------------------------------------------------------+
| Nix .-------------------------. | .----------------.
| | commmand line interface |------. | | Nix expression |----------.
| '-------------------------' | | '----------------' |
| | | | | passed to
| calls | | | |
| | manages | +----------|-------------------|--------------------------------+
| V | | | Nix | V |
| .-------------------------. | | | | +-------------------------+ |
| | language evaluator | | | | | | commmand line interface |------. |
| '-------------------------' | | | | +-------------------------+ | |
| | | | |
| evaluated by calls manages |
| | | | |
| | V | |
| | +--------------------+ | |
| '-------->| language evaluator | | |
| +--------------------+ | |
| | | | | | | |
| produces | | | produces | |
| | V | | | V |
@ -28,57 +39,77 @@ Nix consists of [hierarchical layers].
| | store | | | | | store | | |
| | referenced by V builds | | | | referenced by V builds | |
| | .-------------. .------------. .--------------. | | | | .-------------. .------------. .--------------. | |
| | | build input |----->| build plan | ---->| build result | | | | | | build input |----->| build plan |----->| build result | | |
| | '-------------' '------------' '--------------' | | | | '-------------' '------------' '--------------' | |
| +-----------------------------------------------------------+ | | +-------------------------------------------------|---------+ |
+---------------------------------------------------------------+ +---------------------------------------------------|-----------+
|
represented as
|
V
.---------------.
| file |
'---------------'
``` ```
At the top is the [command line interface](../command-ref/command-ref.md), translating from invocations of Nix executables to interactions with the underlying layers. At the top is the [command line interface](../command-ref/command-ref.md) that drives the underlying layers.
Below that is the evaluator for the [Nix language](../language/index.md), the configuration language for Nix. The [Nix language](../language/index.md) evaluator transforms Nix expressions into self-contained *build plans*, which are used to derive *build results* from referenced *build inputs*.
Its expressions ultimately evaluate to self-contained *build plans*, used to derive *build results* from referenced *build inputs*.
The command line interface and the Nix language are what users interact with most. The command line interface and Nix expressions are what users deal with most.
> **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*.
> As far as we are concerned here, the inputs and results of a build plan are just data. > As far as we are concerned here, the inputs and results of a build plan are just data.
Underlying the command line interface and the Nix language is the [Nix store](../glossary.md#gloss-store), a mechanism to keep track of build plans, data, and references between them. Underlying the command line interface and the Nix language evaluator is the [Nix store](../glossary.md#gloss-store), a mechanism to keep track of build plans, data, and references between them.
It can also execute build plans to produce new data. It can also execute build plans to produce new data, which are made available to the operating system as files.
A build plan is a series of *build tasks*. A build plan itself is a series of *build tasks*, together with their build inputs.
Each build task has a special build input, which is used as *build instructions*.
The result of a build task can be input to another build task.
> **Important** > **Important**
> A build task in Nix is called [derivation](../glossary#gloss-derivation). > A build task in Nix is called [derivation](../glossary#gloss-derivation).
Each build task has a special build input executed as *build instructions* in order to perform the build.
The result of a build task can be input to another build task.
The following [data flow diagram] shows a build plan for illustration.
Build inputs used as instructions to a build task are marked accordingly:
[data flow diagram]: https://en.m.wikipedia.org/wiki/Data-flow_diagram
``` ```
+----------------------------------------------------------------------------------+ +--------------------------------------------------------------------+
| store - - - - - - - - - - - - - - - - - - - - - - | | build plan |
| : build plan : | | |
| .-------------. : : | | .-------------. |
| | build input |---instructions-. : | | | build input |---------. |
| '-------------' : | : | | '-------------' | |
| : v : | | instructions |
| .-------------. : .------------. : | | | |
| | build input |--------->| build task |-instructions-. : | | v |
| '-------------' : '------------' | : | | .-------------. .----------. |
| : v : | | | build input |-->( build task )-------. |
| .-------------. : .------------. : .--------------. | | '-------------' '----------' | |
| | build input |---instructions-. | build task |--->| build result | | | instructions |
| '-------------' : | '------------' : '--------------' | | | |
| : v ^ : | | v |
| .-------------. : .------------. | : | | .-------------. .----------. .--------------. |
| | build input |--------->| build task |--------------' : | | | build input |---------. ( build task )--->| build result | |
| '-------------' : '------------' : | | '-------------' | '----------' '--------------' |
| : ^ : | | instructions ^ |
| .-------------. : | : | | | | |
| | build input |----------------' : | | v | |
| '-------------' : : | | .-------------. .----------. | |
| :_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _: | | | build input |-->( build task )-------' |
+----------------------------------------------------------------------------------+ | '-------------' '----------' |
| ^ |
| | |
| | |
| .-------------. | |
| | build input |---------' |
| '-------------' |
| |
+--------------------------------------------------------------------+
``` ```