forked from lix-project/lix
Merge pull request #7376 from fricklerhandwerk/installable
clarify definition of "installable"
This commit is contained in:
Théophane Hufschmitt
GitHub
commit
2fbb2562c1
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
{
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
{
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
154
src/nix/nix.md
154
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:
|
||||
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
|
||||
`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.
|
||||
### Flake output attribute
|
||||
|
||||
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;
|
||||
Example: `nixpkgs#hello`
|
||||
|
||||
For example, if `/foo/bar` is a git repository with the following structure:
|
||||
```
|
||||
.
|
||||
└── baz
|
||||
├── blah
|
||||
│ └── file.txt
|
||||
└── flake.nix
|
||||
```
|
||||
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
|
||||
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
|
||||
```
|
||||
|
||||
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.
|
||||
- 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`
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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`,
|
||||
|
|
|
|||
|
|
@ -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`).
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
)""
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
||||
)""
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
)""
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue