clarify definition of "installable"

the term was hard to discover, as its definition and explanation were in
a very long document lacking an overview section.
search did not help because it occurs so often.

- clarify wording in the definition
- add an overview of installable types
- add "installable" to glossary
- link to definition from occurrences of the term
- be more precise about where store derivation outputs are processed
- installable Nix expressions must evaluate to a derivation

Co-authored-by: Adam Joseph <54836058+amjoseph-nixpkgs@users.noreply.github.com>
This commit is contained in:
Valentin Gagarin 2022-12-01 01:57:02 +01:00
parent 1e87d5f1ea
commit 2af9fd20c6
22 changed files with 61 additions and 51 deletions

View file

@ -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

View file

@ -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
{

View file

@ -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}

View file

@ -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.

View file

@ -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.

View file

@ -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.

View file

@ -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

View file

@ -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
{

View file

@ -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:

View file

@ -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

View file

@ -48,22 +48,26 @@ 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.
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.
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.
The following types of installable are supported by most commands:
Here are the recognised types of installables:
- [Flake output attribute](#flake-output-attribute)
- [Store path](#store-path)
- [Store derivation](#store-derivation)
- [Nix file](#nix-file), optionally qualified by an attribute path
- [Nix expression](#nix-expression), optionally qualified by an attribute path
## Flake output attributes
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.
### Flake output attribute
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
@ -116,46 +120,46 @@ subcommands, these are `packages.`*system*,
attributes `packages.x86_64-linux.hello`,
`legacyPackages.x86_64-linux.hello` and `hello`.
## Store paths
### 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.
These are paths inside the Nix store, or symlinks that resolve to a path in the Nix store.
## Store derivations
### Store derivation
Example: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv`
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.
By default, if you pass a [store derivation] path to a `nix` subcommand other than [`show-derivation`](./nix3-show-derivation.md), the command will operate on the [output path]s of the derivation.
[output path]: ../../glossary.md#gloss-output-path
For example, `nix path-info` prints information about the output paths:
For example, [`nix path-info`](./nix3-path-info.md) prints information about the output paths:
```console
# nix path-info --json /nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv
[{"path":"/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10",…}]
```
If you want to operate on the store derivation itself, pass the
`--derivation` flag.
If you want to operate on the store derivation itself, pass the `--derivation` flag.
## Nix attributes
### Nix file
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*.
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.
## Nix expressions
### Nix expression
Example: `--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.
You may need to specify `--impure` if the expression references impure inputs (such as `<nixpkgs>`).
## Derivation output selection

View file

@ -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`,

View file

@ -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`).

View file

@ -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.
)""

View file

@ -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

View file

@ -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.

View file

@ -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`.
)""

View file

@ -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.

View file

@ -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

View file

@ -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.
)""

View file

@ -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.

View file

@ -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