Document "Import From Derivation"

[fricklerhandwerk]

The term "Import From Derivation" is historic and does not represent the concept well.

This change does not address the adequacy of term, and only explains the concept. Reviewers: Please assess the correctness and completeness of the description and how easy it is to understand.

Renaming can be done in a follow-up PR.

This work is sponsored by Antithesis ✨

Related: #8450 (but won't fix here)

[edolstra]

IMHO a glossary is not the right place for this kind of documentation. A glossary is a dictionary-like list of short descriptions, which can of course link to more extensive docs elsewhere. "Importing from a derivation" should probably be its own section in the Nix language chapter.

[Ericson2314]

Also, I think it is high time that we stop calling it "import from derivation"

1. We're not importing a derivation. You can actually do that, and if the drv is created at eval time (i.e. no RFC 92 stuff) it is not IFD! We are instead importing a derivation output or build result, and it is that that requires building.
2. It is not just import. builtins.readFile and other "input ingesting"-related primops are equally involved.

I would therefore call the section "reading build results", and just mention within the "import from derivation" term as something people do say that is misleading.

[Ericson2314]

Also I still don't like "realise": it is an English word without meaning, pure nonsense jargon. I think "built" is fine; even if we didn't do the building someone else did.

Passive language can help here

• "We need to build something" OK perhaps it sounds like we need to do the building ourselves.
• "We need something built" Great, it is clear that the task can be delegated to remote builder or retrieved from a cache.
• "We need to get a build result" Great, it clear what we need, and how we get it is left open-ended as it should be.

[fricklerhandwerk]

it is high time that we stop calling it "import from derivation"

@Ericson2314 @edolstra I agree, but renaming the concept makes this change much harder: we already have a configuration option allow-import-from-derivation which would need to be adapted, too. All I wanted to do is document the idea. I can do a follow-up to use a better name and a renaming strategy, which we can discuss in isolation.

I closed all the comments regarding the term itself.

We're not importing a derivation.

I avoided making explicit note of the historicity of the term, and focused on explaining the concept behind it instead. My request to reviewers is to check that the conceptual description is correct.

It is not just import. builtins.readFile and other "input ingesting"-related primops are equally involved.

This part already accounts for that fact.

I still don't like "realise": it is an English word without meaning, pure nonsense jargon.

I closed all the comments related to #7318 and #7320. Let us discuss those in isolation, please.

[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

[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

[nixos-discourse]

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

https://discourse.nixos.org/t/how-to-builtins-readdir-a-derivationss-subdir-when-the-subdirs-path-contains-a-symlink-to-another-derivations-directory/24987/5

[nixos-discourse]

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

https://discourse.nixos.org/t/2023-06-05-documentation-team-meeting-notes-52/28937/1

[fricklerhandwerk]

I know we discussed renaming IFD (proposal: Read From Realisation), but let's first agree on the documentation.

all comments addressed

[fricklerhandwerk]

This should be ready to merge.

[fricklerhandwerk]

Addressed all comments. Let's fix forward from here.

[infinisil]

Very nice! Here's some small things I noticed