Document derived paths

[Ericson2314]

The implementation and shorthand syntax allows for multiple output paths, but at as @roberth has pointed out we should document the concept as just being a single path:

Two cases:

• Opaque Store Path:
  • a single store path:
  • Example: /nix/store/fwc0m6fsccir8zznkl7m8iznv5wsjznw-bash-interactive-5.1-p16/bin/bash
• Built Store Path:
  • a pair of
    • a drvPath (store path to drv file)
    • *, or a comma-separated lists of output names
  • For a syntax, we separate these two with a ^
  • Examples:
    • /nix/store/z6q1q65r7rxa6dxnqykkfmh1xha2k5ww-bash-interactive-5.1-p16.drv^*
    • /nix/store/z6q1q65r7rxa6dxnqykkfmh1xha2k5ww-bash-interactive-5.1-p16.drv^out
    • /nix/store/z6q1q65r7rxa6dxnqykkfmh1xha2k5ww-bash-interactive-5.1-p16.drv^out,dev

Where does it show up:

1. (user visible!) Command line, the most basic type of "installable"
2. Dependencies of derivations are derived paths
3. "String context" in the Nix language is a set of derived paths. (Actually has a bit more information in the presence or absence of the = per path element, but that's a very obscure additional bit if information).

Underlying idea is that derived paths represent distilled goals or targets. This is why they are the parameters of many operations (internally and as exposed in the CLI.)

[nixos-discourse]

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

https://discourse.nixos.org/t/2022-12-15-documentation-team-meeting-notes-20/24035/1