doc/glossary: Define output closure and runtime closure

[roberth]

Motivation

I'd like to reference a definition of output closure from a new NixOS option description; no PR for that yet.

Context

• Has a TODO. I've already spent my scope creep budget by defining runtime closure as well.

Checklist for maintainers

Maintainers: tick if completed or explain if not relevant

• agreed on idea
• agreed on implementation strategy
• tests, as appropriate
  • functional tests - tests/**.sh
  • unit tests - src/*/tests
  • integration tests - tests/nixos/*
• documentation in the manual
• documentation in the internal API docs
• code and comments are self-explanatory
• commit message explains why the change was made
• new feature or incompatible change: updated release notes

Priorities

Add 👍 to pull requests you find important.

[fricklerhandwerk]

You opened a nice can of worms there. I suggest starting with the output closure separately, or possibly even sources, and then work our way up to more elaborate concepts.

[fricklerhandwerk]

Thinking about it more slowly, I'm not sure if we really need another term here.But maybe I'm missing something. Do you want to emphasize the fact that the closure of a "built" store object has different characteristics than say that of a store derivation?

I also think that introducing "runtime closure", and the particular examples, will make for more confusion than they resolve. We're at risk of mixing up the various layers to which the terms runtime and build time could apply. Here you mean runtime of the executables that appear in output paths, but that's not really important here because Nix itself (especially the store) doesn't care what ends up in an output path.

Finally, I have never encountered the term output closure. As @Ericson2314 suggested we should probably rather remove "output path" from the glossary because it's just the store path of a derivation output, and similarly the output closure would be the closure of the store object produced by a derivation. I don't really see a need to say more about it, because the particular semantics you're referring to here are in fact defined in Nixpkgs.

[roberth]

Output closure

My goal here is to establish a short and unambiguous term for this concept, so that we can get rid of "runtime closure", which is a clumsy term even for Nixpkgs.
As you suggest, the distinction between the closure of a derivation and a closure of its output(s) is significant, and that should be mentioned.

Users don't generally don't think in terms of "the closure over the references of the outputs of a package", and I don't think we should expect them to. Instead we should help by abbreviating that.
A definition that's an abbreviation of something like that doesn't carry nearly the weight of other definitions. Perhaps the amount of text should reflect that. Should it be a one-liner?

Runtime closure

Perhaps defining "runtime closure" appears contradictory to that goal, and I'm open to omitting its definition, but my reasoning was as follows.

• Glossaries define any term that is helpful. Whether it's an existing term from the pre-existing domain, or a novel term introduced by Nix itself does not matter for qualifying to be included in a glossary.
• "Runtime closure" is already used by the community sometimes.

I don't feel like mixing definitions of domain terms and Nix terms is all that confusing, but this discussion makes me think otherwise. Should we separate those? We could have two lists on the glossary page, or qualify each domain item with (domain) or something.
I'd also be ok with moving domain definitions to a separate piece of documentation, like the nix.dev's glossary which is almost empty and probably in the wrong place because it's reference documentation.
Or something else. I just don't like to leave readers hanging by putting a term in scare quotes and not adding a link.

Output path

just the store path of a derivation output

We have two kinds of paths for those

• output path: the final, built path
• derivable path: .drv^<output name>

This does remind me that RFC 92 adds another usable (but perhaps not all that useful) potential definition of "output closure", defined as the closure over the outputOf relation, instead of the closure of references after taking an output.

Nixpkgs

the particular semantics you're referring to here are in fact defined in Nixpkgs.

"Runtime" is from the domain of software packaging, and not specific to Nixpkgs at all. I also doubt that "Nixpkgs" actually defines it. I've checked its manual, and it only uses the term twice, without defining it.

[fricklerhandwerk]

A one-liner definition of output closure sounds reasonable to me.

The output path discussion reminds me that I still owe finishing and merging #8595.

Nixpkgs simply doesn't have a glossary, please someone just start that. (I won't reprioritise everything every week because old discussions get revived; it would mess up every attempt at scheduling.)

[fricklerhandwerk]

I kindly set this to draft, because I'm not convinced this has merit, in part because I don't understand which problem this is solving, see #8311 (comment). Also removing myself from assignees because I (ab)use assignments to track liabilities. @roberth feel free to debate this in writing or in person if needed, I'm still subscribed.

[roberth]

Maybe add an editing note, to add to the relevance.

Suggested change

	The [closure] of an [output path]. It only contains what is [reachable] from the output.
	The [closure] of an [output path]. It only contains what is [reachable] from the output.
	<!-- It is not the closure over the outputOf relation, which we'll leave out because it's a "dynamic derivations" thought that needs some deep thinking to even come up with, certainly as long as people aren't used to RFC 92 -->

[fricklerhandwerk]

Probably not necessary here, but I understand what you mean. This would be for one of your brilliant design issues.