Merge pull request #7376 from fricklerhandwerk/installable

clarify definition of "installable"

22 files changed, 120 insertions, 104 deletions

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index d0aff34e2..1256b272f 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -193,6 +193,11 @@
     A symlink to the current *user environment* of a user, e.g.,
     `/nix/var/nix/profiles/default`.
 
+  - [installable]{#gloss-installable}\
+    Something that can be realised in the Nix store.
+
+    See [installables](./command-ref/new-cli/nix.md#installables) for [`nix` commands](./command-ref/new-cli/nix.md) (experimental) for details.
+
   - [NAR]{#gloss-nar}\
     A *N*ix *AR*chive. This is a serialisation of a path in the Nix
     store. It can contain regular files, directories and symbolic
diff --git a/src/libcmd/command.hh b/src/libcmd/command.hh
index 49c7b4f9b..b8116b151 100644
--- a/src/libcmd/command.hh
+++ b/src/libcmd/command.hh
@@ -22,7 +22,7 @@ static constexpr Command::Category catSecondary = 100;
 static constexpr Command::Category catUtility = 101;
 static constexpr Command::Category catNixInstallation = 102;
 
-static constexpr auto installablesCategory = "Options that change the interpretation of installables";
+static constexpr auto installablesCategory = "Options that change the interpretation of [installables](@docroot@/command-ref/new-cli/nix.md#installables)";
 
 struct NixMultiCommand : virtual MultiCommand, virtual Command
 {
diff --git a/src/libcmd/installables.cc b/src/libcmd/installables.cc
index 7d444aac0..5ecf6293f 100644
--- a/src/libcmd/installables.cc
+++ b/src/libcmd/installables.cc
@@ -153,7 +153,7 @@ SourceExprCommand::SourceExprCommand()
         .longName = "file",
         .shortName = 'f',
         .description =
-            "Interpret installables as attribute paths relative to the Nix expression stored in *file*. "
+            "Interpret [*installables*](@docroot@/command-ref/new-cli/nix.md#installables) as attribute paths relative to the Nix expression stored in *file*. "
             "If *file* is the character -, then a Nix expression will be read from standard input. "
             "Implies `--impure`.",
         .category = installablesCategory,
@@ -164,7 +164,7 @@ SourceExprCommand::SourceExprCommand()
 
     addFlag({
         .longName = "expr",
-        .description = "Interpret installables as attribute paths relative to the Nix expression *expr*.",
+        .description = "Interpret [*installables*](@docroot@/command-ref/new-cli/nix.md#installables) as attribute paths relative to the Nix expression *expr*.",
         .category = installablesCategory,
         .labels = {"expr"},
         .handler = {&expr}
diff --git a/src/nix/build.md b/src/nix/build.md
index 6a79f308c..ee414dc86 100644
--- a/src/nix/build.md
+++ b/src/nix/build.md
@@ -82,7 +82,7 @@ R""(
 
 # Description
 
-`nix build` builds the specified *installables*. Installables that
+`nix build` builds the specified *installables*. [Installables](./nix.md#installables) that
 resolve to derivations are built (or substituted if possible). Store
 path installables are substituted.
 
diff --git a/src/nix/bundle.md b/src/nix/bundle.md
index a18161a3c..89458aaaa 100644
--- a/src/nix/bundle.md
+++ b/src/nix/bundle.md
@@ -29,7 +29,7 @@ R""(
 
 # Description
 
-`nix bundle`, by default, packs the closure of the *installable* into a single
+`nix bundle`, by default, packs the closure of the [*installable*](./nix.md#installables) into a single
 self-extracting executable. See the [`bundlers`
 homepage](https://github.com/NixOS/bundlers) for more details.
 
diff --git a/src/nix/develop.md b/src/nix/develop.md
index 4e8542d1b..c49b39669 100644
--- a/src/nix/develop.md
+++ b/src/nix/develop.md
@@ -76,7 +76,7 @@ R""(
 
 `nix develop` starts a `bash` shell that provides an interactive build
 environment nearly identical to what Nix would use to build
-*installable*. Inside this shell, environment variables and shell
+[*installable*](./nix.md#installables). Inside this shell, environment variables and shell
 functions are set up so that you can interactively and incrementally
 build your package.
 
diff --git a/src/nix/eval.md b/src/nix/eval.md
index 61334cde1..3b510737a 100644
--- a/src/nix/eval.md
+++ b/src/nix/eval.md
@@ -50,7 +50,7 @@ R""(
 
 # Description
 
-This command evaluates the Nix expression *installable* and prints the
+This command evaluates the given Nix expression and prints the
 result on standard output.
 
 # Output format
diff --git a/src/nix/flake.md b/src/nix/flake.md
index 810e9ebea..9073d0c3b 100644
--- a/src/nix/flake.md
+++ b/src/nix/flake.md
@@ -275,8 +275,8 @@ Currently the `type` attribute can be one of the following:
 # Flake format
 
 As an example, here is a simple `flake.nix` that depends on the
-Nixpkgs flake and provides a single package (i.e. an installable
-derivation):
+Nixpkgs flake and provides a single package (i.e. an
+[installable](./nix.md#installables) derivation):
 
 ```nix
 {
diff --git a/src/nix/log.md b/src/nix/log.md
index 1c76226a3..01e9801df 100644
--- a/src/nix/log.md
+++ b/src/nix/log.md
@@ -22,8 +22,7 @@ R""(
 
 # Description
 
-This command prints the log of a previous build of the derivation
-*installable* on standard output.
+This command prints the log of a previous build of the [*installable*](./nix.md#installables) on standard output.
 
 Nix looks for build logs in two places:
 
diff --git a/src/nix/make-content-addressed.md b/src/nix/make-content-addressed.md
index 32eecc880..b1f7da525 100644
--- a/src/nix/make-content-addressed.md
+++ b/src/nix/make-content-addressed.md
@@ -35,7 +35,9 @@ R""(
 # Description
 
 This command converts the closure of the store paths specified by
-*installables* to content-addressed form. Nix store paths are usually
+[*installables*](./nix.md#installables) to content-addressed form.
+
+Nix store paths are usually
 *input-addressed*, meaning that the hash part of the store path is
 computed from the contents of the derivation (i.e., the build-time
 dependency graph). Input-addressed paths need to be signed by a
diff --git a/src/nix/nix.md b/src/nix/nix.md
index db60c59ff..0a90fa6c9 100644
--- a/src/nix/nix.md
+++ b/src/nix/nix.md
@@ -48,102 +48,112 @@ manual](https://nixos.org/manual/nix/stable/).
 
 # Installables
 
-Many `nix` subcommands operate on one or more *installables*. These are
-command line arguments that represent something that can be built in
-the Nix store. Here are the recognised types of installables:
-
-* **Flake output attributes**: `nixpkgs#hello`
-
-  These have the form *flakeref*[`#`*attrpath*], where *flakeref* is a
-  flake reference and *attrpath* is an optional attribute path. For
-  more information on flakes, see [the `nix flake` manual
-  page](./nix3-flake.md).  Flake references are most commonly a flake
-  identifier in the flake registry (e.g. `nixpkgs`), or a raw path
-  (e.g. `/path/to/my-flake` or `.` or `../foo`), or a full URL
-  (e.g. `github:nixos/nixpkgs` or `path:.`)
-
-  When the flake reference is a raw path (a path without any URL
-  scheme), it is interpreted as a `path:` or `git+file:` url in the following
-  way:
-  
-  - If the path is within a Git repository, then the url will be of the form
-    `git+file://[GIT_REPO_ROOT]?dir=[RELATIVE_FLAKE_DIR_PATH]`
-    where `GIT_REPO_ROOT` is the path to the root of the git repository,
-    and `RELATIVE_FLAKE_DIR_PATH` is the path (relative to the directory
-    root) of the closest parent of the given path that contains a `flake.nix` within
-    the git repository.
-    If no such directory exists, then Nix will error-out.
-    
-    Note that the search will only include files indexed by git. In particular, files
-    which are matched by `.gitignore` or have never been `git add`-ed will not be
-    available in the flake. If this is undesirable, specify `path:<directory>` explicitly;
-    
-    For example, if `/foo/bar` is a git repository with the following structure:
-    ```
-    .
-    └── baz
-        ├── blah
-        │   └── file.txt
-        └── flake.nix
-    ```
+Many `nix` subcommands operate on one or more *installables*.
+These are command line arguments that represent something that can be realised in the Nix store.
 
-  Then `/foo/bar/baz/blah` will resolve to `git+file:///foo/bar?dir=baz`
+The following types of installable are supported by most commands:
 
-  - If the supplied path is not a git repository, then the url will have the form
-    `path:FLAKE_DIR_PATH` where `FLAKE_DIR_PATH` is the closest parent
-    of the supplied path that contains a `flake.nix` file (within the same file-system).
-    If no such directory exists, then Nix will error-out.
-    
-    For example, if `/foo/bar/flake.nix` exists, then `/foo/bar/baz/` will resolve to
-   `path:/foo/bar`
+- [Flake output attribute](#flake-output-attribute)
+- [Store path](#store-path)
+- [Nix file](#nix-file), optionally qualified by an attribute path
+- [Nix expression](#nix-expression), optionally qualified by an attribute path
 
-  If *attrpath* is omitted, Nix tries some default values; for most
-  subcommands, the default is `packages.`*system*`.default`
-  (e.g. `packages.x86_64-linux.default`), but some subcommands have
-  other defaults. If *attrpath* *is* specified, *attrpath* is
-  interpreted as relative to one or more prefixes; for most
-  subcommands, these are `packages.`*system*,
-  `legacyPackages.*system*` and the empty prefix. Thus, on
-  `x86_64-linux` `nix build nixpkgs#hello` will try to build the
-  attributes `packages.x86_64-linux.hello`,
-  `legacyPackages.x86_64-linux.hello` and `hello`.
+For most commands, if no installable is specified, `.` as assumed.
+That is, Nix will operate on the default flake output attribute of the flake in the current directory.
 
-* **Store paths**: `/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10`
+### Flake output attribute
 
-  These are paths inside the Nix store, or symlinks that resolve to a
-  path in the Nix store.
+Example: `nixpkgs#hello`
 
-* **Store derivations**: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv`
+These have the form *flakeref*[`#`*attrpath*], where *flakeref* is a
+[flake reference](./nix3-flake.md#flake-references) and *attrpath* is an optional attribute path. For
+more information on flakes, see [the `nix flake` manual
+page](./nix3-flake.md).  Flake references are most commonly a flake
+identifier in the flake registry (e.g. `nixpkgs`), or a raw path
+(e.g. `/path/to/my-flake` or `.` or `../foo`), or a full URL
+(e.g. `github:nixos/nixpkgs` or `path:.`)
 
-  By default, if you pass a [store derivation] path to a `nix` subcommand, the command will operate on the [output path]s of the derivation.
+When the flake reference is a raw path (a path without any URL
+scheme), it is interpreted as a `path:` or `git+file:` url in the following
+way:
 
-  [output path]: ../../glossary.md#gloss-output-path
+- If the path is within a Git repository, then the url will be of the form
+  `git+file://[GIT_REPO_ROOT]?dir=[RELATIVE_FLAKE_DIR_PATH]`
+  where `GIT_REPO_ROOT` is the path to the root of the git repository,
+  and `RELATIVE_FLAKE_DIR_PATH` is the path (relative to the directory
+  root) of the closest parent of the given path that contains a `flake.nix` within
+  the git repository.
+  If no such directory exists, then Nix will error-out.
 
-  For example, `nix path-info` prints information about the output paths:
+  Note that the search will only include files indexed by git. In particular, files
+  which are matched by `.gitignore` or have never been `git add`-ed will not be
+  available in the flake. If this is undesirable, specify `path:<directory>` explicitly;
 
-  ```console
-  # nix path-info --json /nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv
-  [{"path":"/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10",…}]
+  For example, if `/foo/bar` is a git repository with the following structure:
+  ```
+  .
+  └── baz
+      ├── blah
+      │   └── file.txt
+      └── flake.nix
   ```
 
-  If you want to operate on the store derivation itself, pass the
-  `--derivation` flag.
+  Then `/foo/bar/baz/blah` will resolve to `git+file:///foo/bar?dir=baz`
+
+- If the supplied path is not a git repository, then the url will have the form
+  `path:FLAKE_DIR_PATH` where `FLAKE_DIR_PATH` is the closest parent
+  of the supplied path that contains a `flake.nix` file (within the same file-system).
+  If no such directory exists, then Nix will error-out.
+
+  For example, if `/foo/bar/flake.nix` exists, then `/foo/bar/baz/` will resolve to
+ `path:/foo/bar`
+
+If *attrpath* is omitted, Nix tries some default values; for most
+subcommands, the default is `packages.`*system*`.default`
+(e.g. `packages.x86_64-linux.default`), but some subcommands have
+other defaults. If *attrpath* *is* specified, *attrpath* is
+interpreted as relative to one or more prefixes; for most
+subcommands, these are `packages.`*system*,
+`legacyPackages.*system*` and the empty prefix. Thus, on
+`x86_64-linux` `nix build nixpkgs#hello` will try to build the
+attributes `packages.x86_64-linux.hello`,
+`legacyPackages.x86_64-linux.hello` and `hello`.
+
+### Store path
+
+Example: `/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10`
+
+These are paths inside the Nix store, or symlinks that resolve to a path in the Nix store.
+
+A [store derivation] is also addressed by store path.
+
+Example: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv`
+
+If you want to refer to an output path of that store derivation, add the output name preceded by a caret (`^`).
+
+Example: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv^out`
+
+All outputs can be referred to at once with the special syntax `^*`.
+
+Example: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv^*`
+
+### Nix file
+
+Example: `--file /path/to/nixpkgs hello`
 
-* **Nix attributes**: `--file /path/to/nixpkgs hello`
+When the option `-f` / `--file` *path* \[*attrpath*...\] is given, installables are interpreted as the value of the expression in the Nix file at *path*.
+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.
 
-  When the `-f` / `--file` *path* option is given, installables are
-  interpreted as attribute paths referencing a value returned by
-  evaluating the Nix file *path*.
+### Nix expression
 
-* **Nix expressions**: `--expr '(import <nixpkgs> {}).hello.overrideDerivation (prev: { name = "my-hello"; })'`.
+Example: `--expr 'import <nixpkgs> {}' hello`
 
-  When the `--expr` option is given, all installables are interpreted
-  as Nix expressions. You may need to specify `--impure` if the
-  expression references impure inputs (such as `<nixpkgs>`).
+When the option `--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.
 
-For most commands, if no installable is specified, the default is `.`,
-i.e. Nix will operate on the default flake output attribute of the
-flake in the current directory.
+You may need to specify `--impure` if the expression references impure inputs (such as `<nixpkgs>`).
 
 ## Derivation output selection
 
diff --git a/src/nix/path-info.md b/src/nix/path-info.md
index b30898ac0..6ad23a02e 100644
--- a/src/nix/path-info.md
+++ b/src/nix/path-info.md
@@ -80,7 +80,7 @@ R""(
 # Description
 
 This command shows information about the store paths produced by
-*installables*, or about all paths in the store if you pass `--all`.
+[*installables*](./nix.md#installables), or about all paths in the store if you pass `--all`.
 
 By default, this command only prints the store paths. You can get
 additional information by passing flags such as `--closure-size`,
diff --git a/src/nix/print-dev-env.md b/src/nix/print-dev-env.md
index 2aad491de..a8ce9d36a 100644
--- a/src/nix/print-dev-env.md
+++ b/src/nix/print-dev-env.md
@@ -40,7 +40,7 @@ R""(
 
 This command prints a shell script that can be sourced by `bash` and
 that sets the variables and shell functions defined by the build
-process of *installable*. This allows you to get a similar build
+process of [*installable*](./nix.md#installables). This allows you to get a similar build
 environment in your current shell rather than in a subshell (as with
 `nix develop`).
 
diff --git a/src/nix/profile-install.md b/src/nix/profile-install.md
index aed414963..4c0f82c09 100644
--- a/src/nix/profile-install.md
+++ b/src/nix/profile-install.md
@@ -29,6 +29,6 @@ R""(
 
 # Description
 
-This command adds *installables* to a Nix profile.
+This command adds [*installables*](./nix.md#installables) to a Nix profile.
 
 )""
diff --git a/src/nix/run.md b/src/nix/run.md
index a0f362076..250ea65aa 100644
--- a/src/nix/run.md
+++ b/src/nix/run.md
@@ -35,7 +35,7 @@ R""(
 
 # Description
 
-`nix run` builds and runs *installable*, which must evaluate to an
+`nix run` builds and runs [*installable*](./nix.md#installables), which must evaluate to an
 *app* or a regular Nix derivation.
 
 If *installable* evaluates to an *app* (see below), it executes the
diff --git a/src/nix/search.md b/src/nix/search.md
index 5a5b5ae05..4caa90654 100644
--- a/src/nix/search.md
+++ b/src/nix/search.md
@@ -62,10 +62,10 @@ R""(
 
 # Description
 
-`nix search` searches *installable* (which must be evaluatable, e.g. a
-flake) for packages whose name or description matches all of the
+`nix search` searches [*installable*](./nix.md#installables) (which can be evaluated, that is, a
+flake or Nix expression, but not a store path or store derivation path) for packages whose name or description matches all of the
 regular expressions *regex*.  For each matching package, It prints the
-full attribute name (from the root of the installable), the version
+full attribute name (from the root of the [installable](./nix.md#installables)), the version
 and the `meta.description` field, highlighting the substrings that
 were matched by the regular expressions. If no regular expressions are
 specified, all packages are shown.
diff --git a/src/nix/shell.md b/src/nix/shell.md
index 9fa1031f5..13a389103 100644
--- a/src/nix/shell.md
+++ b/src/nix/shell.md
@@ -48,7 +48,7 @@ R""(
 # Description
 
 `nix shell` runs a command in an environment in which the `$PATH` variable
-provides the specified *installables*. If no command is specified, it starts the
+provides the specified [*installables*](./nix.md#installable). If no command is specified, it starts the
 default shell of your user account specified by `$SHELL`.
 
 )""
diff --git a/src/nix/show-derivation.md b/src/nix/show-derivation.md
index 2cd93aa62..1d37c6f5a 100644
--- a/src/nix/show-derivation.md
+++ b/src/nix/show-derivation.md
@@ -39,7 +39,7 @@ R""(
 # Description
 
 This command prints on standard output a JSON representation of the
-[store derivation]s to which *installables* evaluate. Store derivations
+[store derivation]s to which [*installables*](./nix.md#installables) evaluate. Store derivations
 are used internally by Nix. They are store paths with extension `.drv`
 that represent the build-time dependency graph to which a Nix
 expression evaluates.
diff --git a/src/nix/store-delete.md b/src/nix/store-delete.md
index db535f87c..431bc5f5e 100644
--- a/src/nix/store-delete.md
+++ b/src/nix/store-delete.md
@@ -10,7 +10,7 @@ R""(
 
 # Description
 
-This command deletes the store paths specified by *installables*. ,
+This command deletes the store paths specified by [*installables*](./nix.md#installables),
 but only if it is safe to do so; that is, when the path is not
 reachable from a root of the garbage collector. This means that you
 can only delete paths that would also be deleted by `nix store
diff --git a/src/nix/store-dump-path.md b/src/nix/store-dump-path.md
index 4ef563526..56e2174b6 100644
--- a/src/nix/store-dump-path.md
+++ b/src/nix/store-dump-path.md
@@ -18,6 +18,6 @@ R""(
 # Description
 
 This command generates a NAR file containing the serialisation of the
-store path *installable*. The NAR is written to standard output.
+store path [*installable*](./nix.md#installables). The NAR is written to standard output.
 
 )""
diff --git a/src/nix/store-repair.md b/src/nix/store-repair.md
index 92d2205a9..180c577ac 100644
--- a/src/nix/store-repair.md
+++ b/src/nix/store-repair.md
@@ -17,7 +17,7 @@ R""(
 # Description
 
 This command attempts to "repair" the store paths specified by
-*installables* by redownloading them using the available
+[*installables*](./nix.md#installables) by redownloading them using the available
 substituters. If no substitutes are available, then repair is not
 possible.
 
diff --git a/src/nix/verify.md b/src/nix/verify.md
index 1c43792e7..cc1122c02 100644
--- a/src/nix/verify.md
+++ b/src/nix/verify.md
@@ -24,7 +24,7 @@ R""(
 
 # Description
 
-This command verifies the integrity of the store paths *installables*,
+This command verifies the integrity of the store paths [*installables*](./nix.md#installables),
 or, if `--all` is given, the entire Nix store. For each path, it
 checks that