clarify definition of "installable"

[fricklerhandwerk]

the term was hard to discover, as its definition and explanation were in
a very long document lacking an overview section.
search did not help because it occurs so often.

• clarify wording in the definition
• add an overview of installable types
• add "installable" to glossary
• link to definition from occurrences of the term

the first commit makes descriptions of each installable type its own subsection.
it makes for a messy diff but does not change contents. read the second commit to see the actual changes.

This work is sponsored by Antithesis ✨

[nixos-discourse]

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

https://discourse.nixos.org/t/2022-12-02-nix-team-meeting-minutes-13/23731/1

[ghost]

I think that trying to mash together "anything accepted by any nix command is an installable and vice versa" is not only confusing but also incorrect. See below, a lot of nix commands which "take installables" reject some kinds of installables.

We shouldn't try to hide the difference between an outpath and its deriver from users.

This "everything is an installable and there is nothing but installables" papers over the many-to-one (Edit: many-to-many!) relationship between derivers and store objects. That will come back to bite us later, just like the "referring to a derivation always means referring to its realisation, except when it doesn't" problem that led to the --derivation flag did.

[fricklerhandwerk]

@amjoseph-nixpkgs I think you're right, and all this hints at is that the CLI has some design issues. We should try to be as precise as possible, but I feel it's only worthwhile up to a point. Saying "it doesn't actually work for all the commands" has to suffice for now. Indeed we'd have to untangle the underlying issues first, which here is the overloading of argument types, but this is not the PR and, in my opinion, not yet the time to do so.

I'll fix up what seems reasonable and would then try to get closer to merging.

[fricklerhandwerk]

@amjoseph-nixpkgs updated according to your suggestions. @Nixos/nix-team ready for review.

[ghost]

Your identification of the installables which "can be evaluated, that is, a flake or Nix expression, but not a store path or store derivation path" is a very important clarification -- so much so that I think it deserves a name (I used evaluatable below, but if you have another one you like better go ahead and change it).

With definitions for the terms installable and evaluatable we can give accurate and very succinct specifications for the arguments of every command except nix show-derivation. I think that's a sign that we've got the right taxonomy.

I think if you add a definition for evaluatable the result is pretty coherent.

[ghost]

So it turns out that nix copy foo.drv doesn't do the same thing as nix copy $(nix-store -r foo.drv).

In other words, "operations on derivations operate on their realisation except when --derivation is used" isn't correct. There is a third behavior.

[Ericson2314]

@amjoseph-nixpkgs the one difference for nix copy I know of is CA derivation realizations. Is that what you hit?

[ghost]

the one difference for nix-copy I know of is CA derivation realizations. Is that what you hit?

I don't think so; I don't have them in my experimental-features at the moment.

I think the problem is actually in the $(nix-store -r). Here is an example that doesn't need nix copy, both in prose and bash. It breaks the "using a derivation as an installable produces exactly the same result as using its realisation as an installable" rule.

Prose

If your local store has neither particular outpath (say, /nix/store/outpath) nor its deriver (say, /nix/store/deriver.drv), then running

nix-store -r /nix/store/outpath

will copy the outpath, but not its deriver, to your local machine.

If you instead run

nix-store -r /nix/store/deriver.drv

then both the outpath and the deriver will be copied to your local machine.

This contradicts the rule "using a derivation as an installable produces exactly the same result as using its realisation as an installable".

Bash

$ nix-store -r /nix/store/dhkv3d1a4hjkfabhi91m6kzpp9x40vpp-bootstrap-tools
this path will be fetched (122.16 MiB download, 122.16 MiB unpacked):
  /nix/store/dhkv3d1a4hjkfabhi91m6kzpp9x40vpp-bootstrap-tools
copying path '/nix/store/dhkv3d1a4hjkfabhi91m6kzpp9x40vpp-bootstrap-tools' from 'http://substituter'...
warning: you did not specify '--add-root'; the result might be removed by the garbage collector
/nix/store/dhkv3d1a4hjkfabhi91m6kzpp9x40vpp-bootstrap-tools

$ ls $(nix-store -qd /nix/store/dhkv3d1a4hjkfabhi91m6kzpp9x40vpp-bootstrap-tools)
ls: cannot access '/nix/store/iqwd30cadrajfampslvykwbv8wps1jsx-bootstrap-tools.drv': No such file or directory

$ nix-store -r $(nix-store -qd /nix/store/dhkv3d1a4hjkfabhi91m6kzpp9x40vpp-bootstrap-tools)
don't know how to build these paths:
  /nix/store/iqwd30cadrajfampslvykwbv8wps1jsx-bootstrap-tools.drv
copying path '/nix/store/iqwd30cadrajfampslvykwbv8wps1jsx-bootstrap-tools.drv' from 'http://substituter'...
warning: you did not specify '--add-root'; the result might be removed by the garbage collector
/nix/store/dhkv3d1a4hjkfabhi91m6kzpp9x40vpp-bootstrap-tools

$ ls $(nix-store -qd /nix/store/dhkv3d1a4hjkfabhi91m6kzpp9x40vpp-bootstrap-tools)
/nix/store/iqwd30cadrajfampslvykwbv8wps1jsx-bootstrap-tools.drv

[fricklerhandwerk]

@amjoseph-nixpkgs I also encountered this inconsistency and think it's a valid point we should address with a design decision. Please open an issue.

@thufschmitt While it's still not perfect, I think it's ready to merge. Could you please take look?

[Ericson2314]

@amjoseph-nixpkgs is this just the old CLI? Or also nix copy?

[Ericson2314]

This is looking very nice!

[fricklerhandwerk]

@thufschmitt please take a look.

[nixos-discourse]

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

https://discourse.nixos.org/t/this-month-in-nix-docs-1-march-2023/26913/1