restructure attribute listing to derivation

[fricklerhandwerk]

Motivation

The most important part of the language is still documented somewhat sparsely, in somewhat dense language. This is a first step to provide some more predictable structure that is easier to parse.

Context

We still need many more examples and cross-links. This PR starts out on just the structure and the essentials.

Checklist for maintainers

This work is sponsored by Antithesis ✨

[fricklerhandwerk]

@Ericson2314 commented:

Building is strictly speaking store derivation -> store object (without using cache). I wouldn't include evaluation. nix build doing evaluation too is a porcelain convenience that shouldn't effect the definition of "building".

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/tweag-nix-dev-update-40/23480/1

[Ericson2314]

More broadly, I think if we have #4543 then the DerivedPath type (in the code, and in my NixCon talk) will finally be directly use-visible, and I think that in turn will unlock what I think are some big improvements in being able to explain things.

[tomberek]

notes from meeting:

realization

"Ensure a store path is valid (it and all of its transitive dependencies are in the store); either a derivation's output, or the store path itself if provided directly. When used with a derivation, Nix will either build or substitute the necessary store paths. When used directly with a store path, the necessary store paths will only be substituted, if available."

Two cases:

1. derivation ---(via building or substitution) ----> storePath is valid in a store
2. store path ---(via substitution) ---------------------> storePath is valid in a store

This operation will fail if the supplied derivation/store paths cannot be created by either building or substitution.

valid: this is a property of a store path in a store which ensures it and all transitive references to other store paths are readable using that store (for example: on a local FS store this means "on disk").... WIP

[fricklerhandwerk]

Discussed in Nix team meeting 2022-12-19:

• @edolstra: there should instead be a separate section about the store
  • @fricklerhandwerk: that's what the Architecture chapter will have
• @edolstra: merge it as is and move around the information when there is a better place
• (some discussion over wording of the precise definition of validity)
• @tomberek: we should focus on what's a blocker to merging and split out tangential considerations into issues or follow-up PRs
• @fricklerhandwerk: will rework the wording of definitions according to discussion outcome

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2022-12-19-nix-team-meeting-minutes-18/24121/1

[dpulls]

🎉 All dependencies have been resolved !

[Ericson2314]

I think you have another PR's text stuck in here?

[fricklerhandwerk]

Ah yeah the force push didn't get through. Will clean it up when I get back to a keyboard.

[fricklerhandwerk]

The build failing on linkcheck is very weird, as the highlighted link is actually correct. Checked with @roberth.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-08-21-nix-team-meeting-minutes-81/32082/1

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-08-28-nix-team-meeting-minutes-83/32290/1

[fricklerhandwerk]

Any blockers for merging this?

[Ericson2314]

Now that I look at the rendered view, I see how much this is just a pure reorg. Let's just merge it and worry about content changes separately.

After all, what really should happen is that we rework this content to just be about the store layer, and what is left can just be a much short thing for the builtins.derivation and builtins.derivationStrict primops

[fricklerhandwerk]

Merging this after addressing all comments and observing that the review seems to converge to minutiae.