Merge changes Id1a67156,I03f4c7c1,I146736bb,I3b1453cb into main

* changes:
  docs: clarify how ^ works for -E/-f installables
  docs: give translation examples from nix-build -E/-A to installables
  docs: clarify how the different kinds of installables are selected
  docs: guide to installables docs in installable commands' docs
This commit is contained in:
Qyriad 2024-05-03 13:39:49 +00:00 committed by Gerrit Code Review
commit 19645a4a64
21 changed files with 74 additions and 4 deletions

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
* Build the default package from the flake in the current directory: * Build the default package from the flake in the current directory:

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
* Bundle Hello: * Bundle Hello:

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Description # Description
This command reads from standard input a JSON representation of a This command reads from standard input a JSON representation of a

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
* Show the [store derivation] that results from evaluating the Hello * Show the [store derivation] that results from evaluating the Hello

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
* Start a shell with the build environment of the default package of * Start a shell with the build environment of the default package of

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
* Show what got added and removed between two versions of the NixOS * Show what got added and removed between two versions of the NixOS

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
* Open the Nix expression of the GNU Hello package: * Open the Nix expression of the GNU Hello package:

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
* Evaluate a Nix expression given on the command line: * Evaluate a Nix expression given on the command line:

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
With [nixpkgs-fmt](https://github.com/nix-community/nixpkgs-fmt): With [nixpkgs-fmt](https://github.com/nix-community/nixpkgs-fmt):

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
* Get the build log of GNU Hello: * Get the build log of GNU Hello:

View file

@ -59,9 +59,13 @@ These are command line arguments that represent something that can be realised i
The following types of installable are supported by most commands: The following types of installable are supported by most commands:
- [Flake output attribute](#flake-output-attribute) (experimental) - [Flake output attribute](#flake-output-attribute) (experimental)
- This is the default
- [Store path](#store-path) - [Store path](#store-path)
- This is assumed if the argument is a Nix store path or a symlink to a Nix store path
- [Nix file](#nix-file), optionally qualified by an attribute path - [Nix file](#nix-file), optionally qualified by an attribute path
- Specified with `--file`/`-f`
- [Nix expression](#nix-expression), optionally qualified by an attribute path - [Nix expression](#nix-expression), optionally qualified by an attribute path
- Specified with `--expr`/`-E`
For most commands, if no installable is specified, `.` is assumed. For most commands, if no installable is specified, `.` is assumed.
That is, Nix will operate on the default flake output attribute of the flake in the current directory. That is, Nix will operate on the default flake output attribute of the flake in the current directory.
@ -158,16 +162,28 @@ When the option `-f` / `--file` *path* \[*attrpath*...\] is given, installables
If attribute paths are provided, commands will operate on the corresponding values accessible at these paths. If attribute paths are provided, commands will operate on the corresponding values accessible at these paths.
The Nix expression in that file, or any selected attribute, must evaluate to a derivation. The Nix expression in that file, or any selected attribute, must evaluate to a derivation.
To emulate the `nix-build '<nixpkgs>' -A hello` pattern, use:
```console
$ nix build -f '<nixpkgs>' hello
```
### Nix expression ### Nix expression
Example: `--expr 'import <nixpkgs> {}' hello` Example: `--expr 'import <nixpkgs> {}' hello`
When the option `--expr` *expression* \[*attrpath*...\] is given, installables are interpreted as the value of the of the Nix expression. When the option `-E` / `--expr` *expression* \[*attrpath*...\] is given, installables are interpreted as the value of the of the Nix expression.
If attribute paths are provided, commands will operate on the corresponding values accessible at these paths. If attribute paths are provided, commands will operate on the corresponding values accessible at these paths.
The Nix expression, or any selected attribute, must evaluate to a derivation. The Nix expression, or any selected attribute, must evaluate to a derivation.
You may need to specify `--impure` if the expression references impure inputs (such as `<nixpkgs>`). You may need to specify `--impure` if the expression references impure inputs (such as `<nixpkgs>`).
To emulate the `nix-build -E 'with import <nixpkgs> { }; hello' pattern use:
```console
$ nix build --impure -E 'with import <nixpkgs> { }; hello'
```
## Derivation output selection ## Derivation output selection
Derivations can have multiple outputs, each corresponding to a Derivations can have multiple outputs, each corresponding to a
@ -176,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'
@ -193,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:

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
* Print the store path produced by `nixpkgs#hello`: * Print the store path produced by `nixpkgs#hello`:

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
* Apply the build environment of GNU hello to the current shell: * Apply the build environment of GNU hello to the current shell:

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
* Install a package from Nixpkgs: * Install a package from Nixpkgs:

View file

@ -1,5 +1,7 @@
R""( R""(
**Note**: unlike [`nix profile install`](./nix3-profile-install.md), this command does *not* take installables.
# Examples # Examples
* Remove a package by name: * Remove a package by name:

View file

@ -1,5 +1,7 @@
R""( R""(
**Note**: unlike [`nix profile install`](./nix3-profile-install.md), this command does *not* take installables.
# Examples # Examples
* Upgrade all packages that were installed using an unlocked flake * Upgrade all packages that were installed using an unlocked flake

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
* Display all special commands within the REPL: * Display all special commands within the REPL:

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
* Run the default app from the `blender-bin` flake: * Run the default app from the `blender-bin` flake:

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
* Show all packages in the `nixpkgs` flake: * Show all packages in the `nixpkgs` flake:

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
* Start a shell providing `youtube-dl` from the `nixpkgs` flake: * Start a shell providing `youtube-dl` from the `nixpkgs` flake:

View file

@ -1,5 +1,7 @@
R""( R""(
**Note:** this command's interface is based heavily around [*installables*](./nix.md#installables), which you may want to read about first (`nix --help`).
# Examples # Examples
* Show one path through the dependency graph leading from Hello to * Show one path through the dependency graph leading from Hello to