Document Derivations and Deriving Paths #12290
Draft
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
And get rid of "store derivation" nonsense.
It is not a language topic.
roberth
reviewed
Jan 19, 2025
Comment on lines
+3
to
+4
| So far, we have covered "inert" [store objects][store object]. | ||
| But the point of the Nix store layer is to be a build system. |
There was a problem hiding this comment.
Did we? Not sure how the reader lands here. I guess we could make So far a link, but how about:
Suggested change
| So far, we have covered "inert" [store objects][store object]. | |
| But the point of the Nix store layer is to be a build system. | |
| Besides functioning as a [content addressed store] the Nix store layer works as a [build system]. |
(my links and link targets need work, sorry)
doc/manual/source/store/drv.md
Outdated
| Other system (like Git or IPFS) also store and transfer immutable data, but they don't concern themselves with *how* that data was created. | ||
|
|
||
| This is where Nix distinguishes itself. | ||
| *Derivations* represent individual build steps, and *deriving paths* are needed to to the *outputs* of those build steps. |
There was a problem hiding this comment.
Suggested change
| *Derivations* represent individual build steps, and *deriving paths* are needed to to the *outputs* of those build steps. | |
| *Derivations* represent individual build steps, and *deriving paths* are needed to refer to the *outputs* of those build steps. |
|
|
||
| This is where Nix distinguishes itself. | ||
| *Derivations* represent individual build steps, and *deriving paths* are needed to to the *outputs* of those build steps. | ||
| The two concepts need to be introduced together because, as described below, each depends on the other. |
There was a problem hiding this comment.
Suggested change
| The two concepts need to be introduced together because, as described below, each depends on the other. | |
| <!-- The two concepts need to be introduced together because, as described below, each depends on the other. --> |
Sounds like it's relevant to editors, mostly.
|
|
||
| A derivation is a specification for running an executable on precisely defined input files to repeatably produce output files at uniquely determined file system paths. | ||
|
|
||
| What is natural Unix analog for a build step *in action*? |
There was a problem hiding this comment.
Suggested change
| What is natural Unix analog for a build step *in action*? | |
| What is the natural Unix analog for a build step *in action*? |
| A derivation is a specification for running an executable on precisely defined input files to repeatably produce output files at uniquely determined file system paths. | ||
|
|
||
| What is natural Unix analog for a build step *in action*? | ||
| Answer: a process that will eventually exit, leaving behind some output date. |
There was a problem hiding this comment.
Suggested change
| Answer: a process that will eventually exit, leaving behind some output date. | |
| Answer: a process that will eventually exit, leaving behind some output files. |
We're talking vague Unix, so everything is a file, and that's good enough, and better than data.
| } | ||
| ``` | ||
|
|
||
| Now, the `drv` field of `Output` is itself a `DerivingPath` instead of an `StorePath`. |
There was a problem hiding this comment.
Suggested change
| Now, the `drv` field of `Output` is itself a `DerivingPath` instead of an `StorePath`. | |
| Now, the `drv` field of `Output` is itself a `DerivingPath` instead of a `StorePath`. |
|
|
||
| ### Encoding {#deriving-path-encoding} | ||
|
|
||
| The encoding is adjusted in a very simplest way, merely displaying the same |
|
|
||
| ### `__structuredAttrs` | ||
|
|
||
| Historically speaking, most users of Nix made GNU Bash with a script the command run, regardless of what they were doing. |
Comment on lines
+283
to
+284
| However, since derivations can already contain arbitary input sources, the vast majority of `__structuredAttrs` can be handled by upper layers. | ||
| We might consider implementing `__structuredAttrs` in higher layers in the future, and simplifying the store layer. |
There was a problem hiding this comment.
Suggested change
| However, since derivations can already contain arbitary input sources, the vast majority of `__structuredAttrs` can be handled by upper layers. | |
| We might consider implementing `__structuredAttrs` in higher layers in the future, and simplifying the store layer. |
This should be an issue, and not docs.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation
Continue documenting the store layer
Context
Some material pulled from #6877
Add 👍 to pull requests you find important.
The Nix maintainer team uses a GitHub project board to schedule and track reviews.