From 194ba8a02f5dabc831259f359c234acaa0ec29fa Mon Sep 17 00:00:00 2001 From: Qyriad Date: Mon, 29 Apr 2024 07:39:10 -0600 Subject: [PATCH 1/4] docs: guide to installables docs in installable commands' docs The installables syntax is not documented in any of the man pages or docbook pages for any of those individual commands. And while these commands really should at least peripherally individually document how installables work, in the meantime we can at least direct people to the right place. This commit also clarifies the unexpected fact that `nix profile remove` and `nix profile upgrade` do *not* take installables. Change-Id: I3b1453cb197a613bbab639c66a466365c3592c6d --- src/nix/build.md | 2 ++ src/nix/bundle.md | 2 ++ src/nix/derivation-add.md | 2 ++ src/nix/derivation-show.md | 2 ++ src/nix/develop.md | 2 ++ src/nix/diff-closures.md | 2 ++ src/nix/edit.md | 2 ++ src/nix/eval.md | 2 ++ src/nix/fmt.md | 2 ++ src/nix/log.md | 2 ++ src/nix/nix.md | 2 +- src/nix/path-info.md | 2 ++ src/nix/print-dev-env.md | 2 ++ src/nix/profile-install.md | 2 ++ src/nix/profile-remove.md | 2 ++ src/nix/profile-upgrade.md | 2 ++ src/nix/repl.md | 2 ++ src/nix/run.md | 2 ++ src/nix/search.md | 2 ++ src/nix/shell.md | 2 ++ src/nix/why-depends.md | 2 ++ 21 files changed, 41 insertions(+), 1 deletion(-) diff --git a/src/nix/build.md b/src/nix/build.md index 0fbb39cc3..2435c1ef6 100644 --- a/src/nix/build.md +++ b/src/nix/build.md @@ -1,5 +1,7 @@ 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 * Build the default package from the flake in the current directory: diff --git a/src/nix/bundle.md b/src/nix/bundle.md index 89458aaaa..156f040ba 100644 --- a/src/nix/bundle.md +++ b/src/nix/bundle.md @@ -1,5 +1,7 @@ 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 * Bundle Hello: diff --git a/src/nix/derivation-add.md b/src/nix/derivation-add.md index f116681ab..ba75b402a 100644 --- a/src/nix/derivation-add.md +++ b/src/nix/derivation-add.md @@ -1,5 +1,7 @@ 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 This command reads from standard input a JSON representation of a diff --git a/src/nix/derivation-show.md b/src/nix/derivation-show.md index 1296e2885..f644a429d 100644 --- a/src/nix/derivation-show.md +++ b/src/nix/derivation-show.md @@ -1,5 +1,7 @@ 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 * Show the [store derivation] that results from evaluating the Hello diff --git a/src/nix/develop.md b/src/nix/develop.md index c49b39669..e39048bb1 100644 --- a/src/nix/develop.md +++ b/src/nix/develop.md @@ -1,5 +1,7 @@ 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 * Start a shell with the build environment of the default package of diff --git a/src/nix/diff-closures.md b/src/nix/diff-closures.md index 0294c0d8d..5f81aa4e2 100644 --- a/src/nix/diff-closures.md +++ b/src/nix/diff-closures.md @@ -1,5 +1,7 @@ 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 * Show what got added and removed between two versions of the NixOS diff --git a/src/nix/edit.md b/src/nix/edit.md index 89bd09abf..d120f3205 100644 --- a/src/nix/edit.md +++ b/src/nix/edit.md @@ -1,5 +1,7 @@ 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 * Open the Nix expression of the GNU Hello package: diff --git a/src/nix/eval.md b/src/nix/eval.md index d1daaf755..eb9f753c5 100644 --- a/src/nix/eval.md +++ b/src/nix/eval.md @@ -1,5 +1,7 @@ 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 * Evaluate a Nix expression given on the command line: diff --git a/src/nix/fmt.md b/src/nix/fmt.md index 1c78bb36f..8b90f33ef 100644 --- a/src/nix/fmt.md +++ b/src/nix/fmt.md @@ -1,5 +1,7 @@ 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 With [nixpkgs-fmt](https://github.com/nix-community/nixpkgs-fmt): diff --git a/src/nix/log.md b/src/nix/log.md index 01e9801df..81bfefd96 100644 --- a/src/nix/log.md +++ b/src/nix/log.md @@ -1,5 +1,7 @@ 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 * Get the build log of GNU Hello: diff --git a/src/nix/nix.md b/src/nix/nix.md index e0f459d6b..7a4a03395 100644 --- a/src/nix/nix.md +++ b/src/nix/nix.md @@ -162,7 +162,7 @@ The Nix expression in that file, or any selected attribute, must evaluate to a d Example: `--expr 'import {}' 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. The Nix expression, or any selected attribute, must evaluate to a derivation. diff --git a/src/nix/path-info.md b/src/nix/path-info.md index 2dda866d0..5f31215d7 100644 --- a/src/nix/path-info.md +++ b/src/nix/path-info.md @@ -1,5 +1,7 @@ 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 * Print the store path produced by `nixpkgs#hello`: diff --git a/src/nix/print-dev-env.md b/src/nix/print-dev-env.md index a8ce9d36a..a7b1cc2b6 100644 --- a/src/nix/print-dev-env.md +++ b/src/nix/print-dev-env.md @@ -1,5 +1,7 @@ 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 * Apply the build environment of GNU hello to the current shell: diff --git a/src/nix/profile-install.md b/src/nix/profile-install.md index 4c0f82c09..8fe31ac4d 100644 --- a/src/nix/profile-install.md +++ b/src/nix/profile-install.md @@ -1,5 +1,7 @@ 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 * Install a package from Nixpkgs: diff --git a/src/nix/profile-remove.md b/src/nix/profile-remove.md index ba85441d8..91684b9eb 100644 --- a/src/nix/profile-remove.md +++ b/src/nix/profile-remove.md @@ -1,5 +1,7 @@ R""( +**Note**: unlike [`nix profile install`](./nix3-profile-install.md), this command does *not* take installables. + # Examples * Remove a package by position: diff --git a/src/nix/profile-upgrade.md b/src/nix/profile-upgrade.md index 39cca428b..b24ab8e3d 100644 --- a/src/nix/profile-upgrade.md +++ b/src/nix/profile-upgrade.md @@ -1,5 +1,7 @@ R""( +**Note**: unlike [`nix profile install`](./nix3-profile-install.md), this command does *not* take installables. + # Examples * Upgrade all packages that were installed using an unlocked flake diff --git a/src/nix/repl.md b/src/nix/repl.md index c5113be61..f8ad49199 100644 --- a/src/nix/repl.md +++ b/src/nix/repl.md @@ -1,5 +1,7 @@ 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 * Display all special commands within the REPL: diff --git a/src/nix/run.md b/src/nix/run.md index 250ea65aa..7639e4d3e 100644 --- a/src/nix/run.md +++ b/src/nix/run.md @@ -1,5 +1,7 @@ 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 * Run the default app from the `blender-bin` flake: diff --git a/src/nix/search.md b/src/nix/search.md index f65ac9b17..c0e48d4b3 100644 --- a/src/nix/search.md +++ b/src/nix/search.md @@ -1,5 +1,7 @@ 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 * Show all packages in the `nixpkgs` flake: diff --git a/src/nix/shell.md b/src/nix/shell.md index f36919575..598a39854 100644 --- a/src/nix/shell.md +++ b/src/nix/shell.md @@ -1,5 +1,7 @@ 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 * Start a shell providing `youtube-dl` from the `nixpkgs` flake: diff --git a/src/nix/why-depends.md b/src/nix/why-depends.md index dc13619e1..fdbebbedc 100644 --- a/src/nix/why-depends.md +++ b/src/nix/why-depends.md @@ -1,5 +1,7 @@ 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 * Show one path through the dependency graph leading from Hello to From bd2619868c8e6f2f8a9724400f1ee9da0bcbb157 Mon Sep 17 00:00:00 2001 From: Qyriad Date: Mon, 29 Apr 2024 08:15:16 -0600 Subject: [PATCH 2/4] docs: clarify how the different kinds of installables are selected Change-Id: I146736bb97ebe035e04be69ce9fb60a557e38c6c --- src/nix/nix.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/nix/nix.md b/src/nix/nix.md index 7a4a03395..7b2cd7b7b 100644 --- a/src/nix/nix.md +++ b/src/nix/nix.md @@ -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: - [Flake output attribute](#flake-output-attribute) (experimental) + - This is the default - [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 + - Specified with `--file`/`-f` - [Nix expression](#nix-expression), optionally qualified by an attribute path + - Specified with `--expr`/`-E` 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. From 6abeea70e9dac328159a9ba4d6f0d84c5c3a2387 Mon Sep 17 00:00:00 2001 From: Qyriad Date: Mon, 29 Apr 2024 08:15:52 -0600 Subject: [PATCH 3/4] docs: give translation examples from nix-build -E/-A to installables Change-Id: I03f4c7c1049063539a35ba500a07bb8f866d4cb7 --- src/nix/nix.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/nix/nix.md b/src/nix/nix.md index 7b2cd7b7b..65fe0c5b5 100644 --- a/src/nix/nix.md +++ b/src/nix/nix.md @@ -162,6 +162,12 @@ 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. The Nix expression in that file, or any selected attribute, must evaluate to a derivation. +To emulate the `nix-build '' -A hello` pattern, use: + +```console +$ nix build -f '' hello +``` + ### Nix expression Example: `--expr 'import {}' hello` @@ -172,6 +178,12 @@ 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 ``). +To emulate the `nix-build -E 'with import { }; hello' pattern use: + +```console +$ nix build --impure -E 'with import { }; hello' +``` + ## Derivation output selection Derivations can have multiple outputs, each corresponding to a From 4942e4e2d2217b6c4a4a7a02fefb06c831c26b97 Mon Sep 17 00:00:00 2001 From: Qyriad Date: Mon, 29 Apr 2024 08:09:50 -0600 Subject: [PATCH 4/4] 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 --- src/nix/nix.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/src/nix/nix.md b/src/nix/nix.md index 65fe0c5b5..0d588cd01 100644 --- a/src/nix/nix.md +++ b/src/nix/nix.md @@ -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 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' @@ -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 '' 'glibc^dev,static' + $ nix build --impure -E 'import { }' 'glibc^dev,static' + ``` + + This syntax is the same even if the actual attribute path is empty: + + ```console + $ nix build -E 'let pkgs = import { }; 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: