Document <drvPath>^<outputName> syntax for installables

[ghost]

The ^ syntax for installables was added in these three PRs:

• nix: Respect meta.outputsToInstall, and use all outputs by default #6426
• Low level <drvPath>^<outputName> installable syntax to match existing <highLevelInstallable>^<outputNames> syntax  #4543
• Get rid of .drv special-casing for store path installable #7600

... but was not added to the manual. This commit documents the syntax for this fifth type of installable.

My earlier complaints about vagueness in #4543 are solved if /nix/store/xyz.drv^outname counts as an installable, since this syntax gives us a way to use installable-accepting commands (like nix copy) on a derivation without using the command on its outputs (or vice versa).

At the time of that discussion the ^ syntax had not yet reached the then-stable version of Nix, and I didn't find out about it until a few months ago. I think it is awesome. The --derivation flag always seemed like an ugly hack.

Anyways, I assume that the intent is that /nix/store/xyz.drv^outname counts as an installable. If so, this is my attempt at documenting that fact.

[fricklerhandwerk]

Nice!

I'm not sure about the installables part, @Ericson2314 will know better.

[fricklerhandwerk]

Suggested change

	A plain store derivation path refers to the first output declared for that derivation.

[ghost]

Hrm, @fricklerhandwerk did you mean to delete those lines in your suggestion, or did you intend to only add the new line?

[Ericson2314]

We should document "Deriving Paths" first. That is the underlying concept. The fact that those never got documented means people just see ad-hoc syntax and don't know how to think about it. That is the first problem.

This is the same thing I think should block #8595 too.

[Ericson2314]

But yes you are right @amjoseph-nixpkgs, Store paths are a type of Deriving Path ("constant" deriving paths @roberth came up with the name), which in turn are type of installable.

We also support ^ on the other installables but I think I want to get rid of that. Maybe also get rid of ^ supporting multiple names when we can just use shell {a,b,c} too. (and that works for .output too).

[fricklerhandwerk]

@Ericson2314 none of that should be blocking here. IMO this can be fixed up and merged.

[Ericson2314]

@fricklerhandwerk I think it is blocking because it is quite annoying to get text that is inline and delete it later. Much better to have the small pages/outline so people know what they should document / what they should refer to to the get go.

https://github.com/NixOS/nix/compare/document-derivation-and-deriving-path I pushed some text there taken from my other branch. I also got rid of "store derivation" per @roberth's #6507. I think if we fix that stuff up it will take a little bit but not too long, and then we'll have a much better foundation for these other things.

It's really important to me that read don't waste neurons building independent mental models for:

1. low-level "installables"
2. derivation inputs
3. string context elements

because they missed the fact that these are all essentially the same thing.

[ghost]

We should document "Deriving Paths" first.

Okay but if that is not imminent we should at least merge a one-line change that adds the fifth bullet point to the definition of installable. Even if it's a placeholder. Otherwise there's a huge gap between the documented behavior and the actual behavior -- for nearly every command.

https://github.com/NixOS/nix/compare/document-derivation-and-deriving-path

Is there a PR to discuss this?

👍 I like the addition of the qualifier expression to derivation to make it clear when you're talking about something in the Nix language rather than something on the disk.

I pushed some text there taken from my other branch. I also got rid of "store derivation" per @roberth's #6507.

👎 I would leave it. Then we have two clearly-defined terms:

• expression derivation
• store derivation

Anybody who neglects to include one of the two qualifiers is asking the reader to infer the qualifier themselves... which is how we talk on github and irc but not appropriate for polished documentation.

Regarding #6507, that PR is correct that:

Nix doesn't really have a notion of "package".

... and I don't think that's going to change in the immediate future, or without some raging debates occurring. I think we should let sleeping dogs lie here and not try to define "package" in the Nix manual. At least for now.

We also support ^ on the other installables but I think I want to get rid of that.

Yeah I was going to mention that. It's one reason I picked "store derivation output reference"... it means we can define the parallel concept "flake attribute output reference" for the thing you get when you put ^outputName at the end of a flake attribute.

Maybe also get rid of ^ supporting multiple names when we can just use shell {a,b,c} too. (and that works for .output too).

... but not for ^* unfortunately.

[Ericson2314]

@amjoseph-nixpkgs So on second thought in the Nix Team meeting I think I am scope creeping too much so It is better to just begin with your PR.

Can you add the glossary entry for deriving paths from #8595 and then reference that? That will do for now.

[Ericson2314]

Then both these become deriving path

[Ericson2314]

And down below the "Store path" description becomes "Deriving Path"

[Ericson2314]

Also see the "Derivation output selection" section down below.

[Qyriad]

Suggested change

	See also: The store path section of the [installables syntax](@docroot@/command-ref/new-cli/nix.html#store-path), where output references are used.

It'd be good to link or explain what this syntax is a part of and where it's used.

[nixos-discourse]

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

https://discourse.nixos.org/t/2023-11-17-nix-team-meeting-minutes-104/35753/1