Merge pull request #7376 from fricklerhandwerk/installable

clarify definition of "installable"
This commit is contained in:
Théophane Hufschmitt 2023-03-06 10:44:14 +01:00 committed by GitHub
commit 2fbb2562c1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
22 changed files with 117 additions and 101 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,25 +48,36 @@ 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:
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.
* **Flake output attributes**: `nixpkgs#hello`
The following types of installable are supported by most commands:
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:.`)
- [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
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:
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.
- If the path is within a Git repository, then the url will be of the form
### Flake output attribute
Example: `nixpkgs#hello`
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:.`)
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
@ -89,7 +100,7 @@ the Nix store. Here are the recognised types of installables:
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
- 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.
@ -97,53 +108,52 @@ the Nix store. Here are the recognised types of installables:
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`.
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 paths**: `/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10`
### Store path
These are paths inside the Nix store, or symlinks that resolve to a
path in the Nix store.
Example: `/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10`
* **Store derivations**: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv`
These are paths inside the Nix store, or symlinks that resolve to a path in the Nix store.
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.
A [store derivation] is also addressed by store path.
[output path]: ../../glossary.md#gloss-output-path
Example: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv`
For example, `nix path-info` prints information about the output paths:
If you want to refer to an output path of that store derivation, add the output name preceded by a caret (`^`).
```console
# nix path-info --json /nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv
[{"path":"/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10",…}]
```
Example: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv^out`
If you want to operate on the store derivation itself, pass the
`--derivation` flag.
All outputs can be referred to at once with the special syntax `^*`.
* **Nix attributes**: `--file /path/to/nixpkgs hello`
Example: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv^*`
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 file
* **Nix expressions**: `--expr '(import <nixpkgs> {}).hello.overrideDerivation (prev: { name = "my-hello"; })'`.
Example: `--file /path/to/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 `-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.
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.
### Nix expression
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.
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