docs: clarify how ^ works for -E/-f installables

We didn't even realize you *could* use this syntax with -E and -f, much
less that the attribute path could be *empty*.

Change-Id: Id1a6715609f3a76a5ce477bd43a7832effbbe07b
This commit is contained in:
Qyriad 2024-04-29 08:09:50 -06:00 committed by Valentin Gagarin
parent 8ff169715d
commit cb5a5dd4f3

View file

@ -182,9 +182,10 @@ that contains programs, and a `dev` output that provides development
artifacts like C/C++ header files. The outputs on which `nix` commands
operate are determined as follows:
* You can explicitly specify the desired outputs using the syntax
*installable*`^`*output1*`,`*...*`,`*outputN*. For example, you can
obtain the `dev` and `static` outputs of the `glibc` package:
* You can explicitly specify the desired outputs using the syntax *installable*`^`*output1*`,`*...*`,`*outputN* — that is, a caret followed immediately by a comma-separated list of derivation outputs to select.
For installables specified as [Flake output attributes](#flake-output-attribute) or [Store paths](#store-path), the output is specified in the same argument:
For example, you can obtain the `dev` and `static` outputs of the `glibc` package:
```console
# nix build 'nixpkgs#glibc^dev,static'
@ -199,6 +200,19 @@ operate are determined as follows:
```
For `-e`/`--expr` and `-f`/`--file`, the derivation output is specified as part of the attribute path:
```console
$ nix build -f '<nixpkgs>' 'glibc^dev,static'
$ nix build --impure -E 'import <nixpkgs> { }' 'glibc^dev,static'
```
This syntax is the same even if the actual attribute path is empty:
```console
$ nix build -E 'let pkgs = import <nixpkgs> { }; in pkgs.glibc' '^dev,static'
```
* You can also specify that *all* outputs should be used using the
syntax *installable*`^*`. For example, the following shows the size
of all outputs of the `glibc` package in the binary cache: