Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

manual: architecture overview #7066

Merged
merged 7 commits into from
Jan 2, 2023
Merged

manual: architecture overview #7066

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
be8744f
manual: architecture overview
fricklerhandwerk Sep 19, 2022
b5728ac
add articles
fricklerhandwerk Sep 23, 2022
98447c1
clarify subject of sentence
fricklerhandwerk Sep 23, 2022
3d716df
make diagrams compatible with svgbob
fricklerhandwerk Oct 15, 2022
9d20a05
remove external link
fricklerhandwerk Nov 9, 2022
4ed8bb1
suggestions from review
fricklerhandwerk Dec 12, 2022
c162c90
add more explanation to diagrams
fricklerhandwerk Dec 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/manual/src/SUMMARY.md.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@
@manpages@
- [Files](command-ref/files.md)
- [nix.conf](command-ref/conf-file.md)
- [Architecture](architecture/architecture.md)
- [Glossary](glossary.md)
- [Contributing](contributing/contributing.md)
- [Hacking](contributing/hacking.md)
Expand Down
84 changes: 84 additions & 0 deletions doc/manual/src/architecture/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
# Architecture

This chapter describes how Nix works.
It should help users understand why Nix behaves as it does, and it should help developers understand how to modify Nix and how to write similar tools.

## Overview

Nix consists of [hierarchical layers].

[hierarchical layers]: https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers

```
+---------------------------------------------------------------+
| Nix .-------------------------. |
| | commmand line interface |------. |
| '-------------------------' | |
| | | |
| evaluates | |
fricklerhandwerk marked this conversation as resolved.
Show resolved Hide resolved
| | manages |
| V | |
| .-------------------------. | |
| | configuration language | | |
| '-------------------------' | |
| | | |
| evaluates to | |
| | V |
| +----------------------------|------------------------------+ |
| | store | | |
| | referenced by V builds | |
| | .-------------. .------------. .--------------. | |
| | | build input |----->| build plan | ---->| build result | | |
| | '-------------' '------------' '--------------' | |
| +-----------------------------------------------------------+ |
+---------------------------------------------------------------+
fricklerhandwerk marked this conversation as resolved.
Show resolved Hide resolved
fricklerhandwerk marked this conversation as resolved.
Show resolved Hide resolved
```

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.

Below that is the [Nix language](../language/index.md), the configuration language for Nix.
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.

> **Note**
> 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.

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.
It can also execute build plans to produce new data.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"It" here seems to refer to the Nix store, which cannot be said to execute build plans.


A build plan is a series of *build tasks*.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find it a bit counterintuitive that the first term introduced is "build task", only then for the term to be redefined in a "boxed paragraph".

Also, by introducing this term ("build task"), I think you're increasing the cognitive load, as it is not going to be useful in the broader Nix context.

My suggesiton is instead

Suggested change
A build plan is a series of *build tasks*.
A build plan is a series of "build tasks", which in Nix are called [derivations](../glossary#gloss-derivation).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, maybe it's better to use "derivation" instead of "build task", which is not a term that appears in the Nix source.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We still don't have a definition of what exactly a derivation even is. I'd argue the term derivation should be reserved for Nix's specific implementation of build tasks, whatever it is we define it to be - store derivation or the Nix language concept.

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**
> A build task in Nix is called [derivation](../glossary#gloss-derivation).

```
+----------------------------------------------------------------------------------+
| store - - - - - - - - - - - - - - - - - - - - - - |
| : build plan : |
| .-------------. : : |
| | build input |---instructions-. : |
| '-------------' : | : |
| : v : |
| .-------------. : .------------. : |
| | build input |--------->| build task |-instructions-. : |
| '-------------' : '------------' | : |
| : v : |
| .-------------. : .------------. : .--------------. |
| | build input |---instructions-. | build task |--->| build result | |
| '-------------' : | '------------' : '--------------' |
| : v ^ : |
| .-------------. : .------------. | : |
| | build input |--------->| build task |--------------' : |
| '-------------' : '------------' : |
| : ^ : |
| .-------------. : | : |
| | build input |----------------' : |
| '-------------' : : |
| :_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _: |
+----------------------------------------------------------------------------------+
```