Rename content-addressed derivations's "realisation" to "build trace"

[Ericson2314]

"realisation" is a bad term because we already use it for other things (building, including input-addressed derivations) and because it is vague.

The term in https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf and https://cloud.ins.jku.at/index.php/s/txgoHps6FyNpiDk "trace"; we should use that instead, in documentation and code.

[mschwaig]

closes #7254, which has some alternative suggestions

[edolstra]

"Realisation" is not a great term, but "trace" is no better, IMHO. It really tells me nothing about what it is.

[Ericson2314]

How about throwing on an adjective, like "build trace"? That's getting clearer. I want it to be something involving "trace" in order to stay connected to the literature.

[roberth]

Ambiguous with --show-trace

[Ericson2314]

Fair point. Well then there we go: build trace vs eval trace! There are enough simularities that I am glad both use "trace".

[mschwaig]

Another alternative name that is a bit more distrinct would be kvtrace, with the k and v standing for key and value.
That highlights how each kvtrace represents an entry in a map from build inputs to build outputs.

[Ericson2314]

Maybe the whole thing should be called "build trace" or "build trace map"? and an individual one is a "build trace kv pair"?

[roberth]

We might actually be talking about two representations for information about builds.

• the occurrence of a build, including output content for the whole derivation
• a record that maps (drv, outname) -> output content

Excuse my ignorance about undocumented features, but I believe the prior is a realisation, whereas the latter is the more useful and accurate concept for reasoning about build inputs, and perhaps this is the mapping that deserves to be called a build trace?
These concepts convey largely the same information, but they give rise to a slightly different data model (or different part of a data model).

• realisation: drv -> (map outname contenthash)
• build trace: (drv, output) -> contenthash

To make the distinction a bit more concrete, consider a derivation graph where one of the derivations has an unused testresults output, containing a timestamp. By comparing realisations, you would falsely flag a frankenbuild, whereas a set of traces would accurately report "no frankenbuild", because none of the impure outputs were used.

[nixos-discourse]

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

https://discourse.nixos.org/t/2024-11-27-nix-team-meeting-minutes-198/56691/1

[roberth]

Relevant quote from the minutes:

@mschwaig: using a realisation both for the process and the data may be ambiguous. Makes it hard to talk about the process vs the data.

[Ericson2314]

@roberth Good point, I too would prefer to query the map. There is little-to-no valid use-case to upload a partial output map to the cache; best just upload the whole thing or none of it.