From b4de12d8929f70c0469aa15acbe5a108fcd4ee77 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Thu, 1 Dec 2022 01:57:02 +0100 Subject: [PATCH] add "installable" to glossary, link from occurrences the term is hard to discover, as its definition and explanation is in a very long document. search does not help because it occurs so often. --- doc/manual/src/glossary.md | 12 ++++++++++++ src/libcmd/command.hh | 2 +- src/nix/build.md | 2 +- src/nix/bundle.md | 2 +- src/nix/develop.md | 2 +- src/nix/eval.md | 2 +- src/nix/flake.md | 4 ++-- src/nix/log.md | 2 +- src/nix/make-content-addressed.md | 4 +++- src/nix/nix.md | 22 ++++++++++++++++------ src/nix/path-info.md | 2 +- src/nix/print-dev-env.md | 2 +- src/nix/profile-install.md | 2 +- src/nix/run.md | 2 +- src/nix/search.md | 6 +++--- src/nix/shell.md | 2 +- src/nix/show-derivation.md | 2 +- src/nix/store-delete.md | 2 +- src/nix/store-dump-path.md | 2 +- src/nix/store-repair.md | 2 +- src/nix/verify.md | 2 +- 21 files changed, 52 insertions(+), 28 deletions(-) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index b13709f8a981..25629d77e454 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -1,5 +1,15 @@ # Glossary + - [installable]{#gloss-installable}\ + Argument type that can be passed to [`nix-build`](./command-ref/nix-build.md) or [`nix build`](./command-ref/new-cli/nix3-build.md) (experimental): + + - path to Nix expression + - store derivation path + - [store path] + - [flake reference](./command-ref/new-cli/nix3-flake.md#flake-references) (only for [`nix build`](./command-ref/new-cli/nix3-build.md), experimental) + + See [`nix` Installables](./command-ref/new-cli/nix3.md#installables) for details. + - [derivation]{#gloss-derivation}\ A description of a build task. The result of a derivation is a store object. Derivations are typically specified in Nix expressions @@ -49,6 +59,8 @@ The location in the file system of a store object, i.e., an immediate child of the Nix store directory. + [store path]: #gloss-store-path + - [store object]{#gloss-store-object}\ A file that is an immediate child of the Nix store directory. These can be regular files, but also entire directory trees. Store objects diff --git a/src/libcmd/command.hh b/src/libcmd/command.hh index 3b4b40981def..80bcdd9d7b75 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](../../glossary.md#gloss-installable)"; struct NixMultiCommand : virtual MultiCommand, virtual Command { diff --git a/src/nix/build.md b/src/nix/build.md index 6a79f308cc04..126e09ded9a9 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](../../glossary.md#gloss-installable) 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 a18161a3c2a0..2ad079915c49 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*](../../glossary.md#gloss-installable) 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 4e8542d1bba0..d576ac051841 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*](../../glossary.md#gloss-installable). 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 61334cde1bf5..0e99a6373702 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 Nix expression [*installable*](../../glossary.md#gloss-installable) and prints the result on standard output. # Output format diff --git a/src/nix/flake.md b/src/nix/flake.md index a1ab432811f1..48eb9a1477ed 100644 --- a/src/nix/flake.md +++ b/src/nix/flake.md @@ -270,8 +270,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](../../glossary.md#gloss-installable) derivation): ```nix { diff --git a/src/nix/log.md b/src/nix/log.md index 1c76226a34a6..d2d005691bf2 100644 --- a/src/nix/log.md +++ b/src/nix/log.md @@ -23,7 +23,7 @@ R""( # Description This command prints the log of a previous build of the derivation -*installable* on standard output. +[*installable*](../../glossary.md#gloss-installable) 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 32eecc88060d..c15e64bd3932 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*](../../glossary.md#gloss-installable) 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 d48682a94323..92e4ec26543a 100644 --- a/src/nix/nix.md +++ b/src/nix/nix.md @@ -52,10 +52,12 @@ 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` +* **Flake output attributes** + + Example: `nixpkgs#hello` These have the form *flakeref*[`#`*attrpath*], where *flakeref* is a - flake reference and *attrpath* is an optional attribute path. For + [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 @@ -108,12 +110,16 @@ the Nix store. Here are the recognised types of installables: attributes `packages.x86_64-linux.hello`, `legacyPackages.x86_64-linux.hello` and `hello`. -* **Store paths**: `/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10` +* **Store paths** + + 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. -* **Store derivations**: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv` +* **Store derivations** + + Example: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv` Store derivations are store paths with extension `.drv` and are a low-level representation of a build-time dependency graph used @@ -130,13 +136,17 @@ the Nix store. Here are the recognised types of installables: If you want to operate on the store derivation itself, pass the `--derivation` flag. -* **Nix attributes**: `--file /path/to/nixpkgs hello` +* **Nix attributes** + + Example: `--file /path/to/nixpkgs hello` 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 expressions**: `--expr '(import {}).hello.overrideDerivation (prev: { name = "my-hello"; })'`. +* **Nix expressions** + + Example: `--expr '(import {}).hello.overrideDerivation (prev: { name = "my-hello"; })'`. When the `--expr` option is given, all installables are interpreted as Nix expressions. You may need to specify `--impure` if the diff --git a/src/nix/path-info.md b/src/nix/path-info.md index 7a1714ba436a..24245beded6e 100644 --- a/src/nix/path-info.md +++ b/src/nix/path-info.md @@ -78,7 +78,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*](../../glossary.md#gloss-installable), 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 2aad491de48e..c8734c9fda99 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*](../../glossary.md#gloss-installable). 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 aed4149630bd..cd9b3129e1aa 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*](../../glossary.md#gloss-installable) to a Nix profile. )"" diff --git a/src/nix/run.md b/src/nix/run.md index a0f362076ca4..ee81e56f2538 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*](../../glossary.md#gloss-installable), 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 5a5b5ae058fa..dc0987a407cb 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*](../../glossary.md#gloss-installable) (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](../../glossary.md#gloss-installable)), 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 9fa1031f5e73..dee8f327e6c5 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*](../../glossary.md#gloss-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 aa863899ce85..026b7d8108c8 100644 --- a/src/nix/show-derivation.md +++ b/src/nix/show-derivation.md @@ -37,7 +37,7 @@ R""( # Description This command prints on standard output a JSON representation of the -store derivations to which *installables* evaluate. Store derivations +store derivations to which [*installables*](../../glossary.md#gloss-installable) 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 db535f87cae0..cdc16721f542 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*](../../glossary.md#gloss-installable), 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 4ef5635264ac..745a3ed71af0 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*](../../glossary.md#gloss-installable). The NAR is written to standard output. )"" diff --git a/src/nix/store-repair.md b/src/nix/store-repair.md index 92d2205a9d0c..de03589c3263 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*](../../glossary.md#gloss-installable) 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 1c43792e7651..a940b23d9cb5 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*](../../glossary.md#gloss-installable), or, if `--all` is given, the entire Nix store. For each path, it checks that