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
parent 6abeea70e9
commit 4942e4e2d2

View file

@ -192,9 +192,10 @@ that contains programs, and a `dev` output that provides development
artifacts like C/C++ header files. The outputs on which `nix` commands artifacts like C/C++ header files. The outputs on which `nix` commands
operate are determined as follows: operate are determined as follows:
* You can explicitly specify the desired outputs using the syntax * 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.
*installable*`^`*output1*`,`*...*`,`*outputN*. For example, you can For installables specified as [Flake output attributes](#flake-output-attribute) or [Store paths](#store-path), the output is specified in the same argument:
obtain the `dev` and `static` outputs of the `glibc` package:
For example, you can obtain the `dev` and `static` outputs of the `glibc` package:
```console ```console
# nix build 'nixpkgs#glibc^dev,static' # nix build 'nixpkgs#glibc^dev,static'
@ -209,6 +210,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 * You can also specify that *all* outputs should be used using the
syntax *installable*`^*`. For example, the following shows the size syntax *installable*`^*`. For example, the following shows the size
of all outputs of the `glibc` package in the binary cache: of all outputs of the `glibc` package in the binary cache: