mirror of
https://github.com/NixOS/nix.git
synced 2024-11-21 22:32:26 +00:00
Merge pull request #10935 from fricklerhandwerk/cli-docs-formatting
use separate paragraphs inside list items
This commit is contained in:
John Ericson
GitHub
commit
0c6029669d
@ -55,20 +55,20 @@ All options not listed here are passed to
|
||||
[`nix-store --realise`](nix-store/realise.md),
|
||||
except for `--arg` and `--attr` / `-A` which are passed to [`nix-instantiate`](nix-instantiate.md).
|
||||
|
||||
- <span id="opt-no-out-link">[`--no-out-link`](#opt-no-out-link)<span>
|
||||
- <span id="opt-no-out-link">[`--no-out-link`](#opt-no-out-link)<span>
|
||||
|
||||
Do not create a symlink to the output path. Note that as a result
|
||||
the output does not become a root of the garbage collector, and so
|
||||
might be deleted by `nix-store --gc`.
|
||||
Do not create a symlink to the output path. Note that as a result
|
||||
the output does not become a root of the garbage collector, and so
|
||||
might be deleted by `nix-store --gc`.
|
||||
|
||||
- <span id="opt-dry-run">[`--dry-run`](#opt-dry-run)</span>
|
||||
- <span id="opt-dry-run">[`--dry-run`](#opt-dry-run)</span>
|
||||
|
||||
Show what store paths would be built or downloaded.
|
||||
Show what store paths would be built or downloaded.
|
||||
|
||||
- <span id="opt-out-link">[`--out-link`](#opt-out-link)</span> / `-o` *outlink*
|
||||
- <span id="opt-out-link">[`--out-link`](#opt-out-link)</span> / `-o` *outlink*
|
||||
|
||||
Change the name of the symlink to the output path created from
|
||||
`result` to *outlink*.
|
||||
Change the name of the symlink to the output path created from
|
||||
`result` to *outlink*.
|
||||
|
||||
{{#include ./status-build-failure.md}}
|
||||
|
||||
|
||||
@ -27,40 +27,46 @@ The moving parts of channels are:
|
||||
|
||||
This command has the following operations:
|
||||
|
||||
- `--add` *url* \[*name*\]\
|
||||
Add a channel *name* located at *url* to the list of subscribed channels.
|
||||
If *name* is omitted, default to the last component of *url*, with the suffixes `-stable` or `-unstable` removed.
|
||||
- `--add` *url* \[*name*\]
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> `--add` does not automatically perform an update.
|
||||
> Use `--update` explicitly.
|
||||
Add a channel *name* located at *url* to the list of subscribed channels.
|
||||
If *name* is omitted, default to the last component of *url*, with the suffixes `-stable` or `-unstable` removed.
|
||||
|
||||
A channel URL must point to a directory containing a file `nixexprs.tar.gz`.
|
||||
At the top level, that tarball must contain a single directory with a `default.nix` file that serves as the channel’s entry point.
|
||||
> **Note**
|
||||
>
|
||||
> `--add` does not automatically perform an update.
|
||||
> Use `--update` explicitly.
|
||||
|
||||
- `--remove` *name*\
|
||||
Remove the channel *name* from the list of subscribed channels.
|
||||
A channel URL must point to a directory containing a file `nixexprs.tar.gz`.
|
||||
At the top level, that tarball must contain a single directory with a `default.nix` file that serves as the channel’s entry point.
|
||||
|
||||
- `--list`\
|
||||
Print the names and URLs of all subscribed channels on standard output.
|
||||
- `--remove` *name*
|
||||
|
||||
- `--update` \[*names*…\]\
|
||||
Download the Nix expressions of subscribed channels and create a new generation.
|
||||
Update all channels if none is specified, and only those included in *names* otherwise.
|
||||
Remove the channel *name* from the list of subscribed channels.
|
||||
|
||||
- `--list-generations`\
|
||||
Prints a list of all the current existing generations for the
|
||||
channel profile.
|
||||
- `--list`
|
||||
|
||||
Works the same way as
|
||||
```
|
||||
nix-env --profile /nix/var/nix/profiles/per-user/$USER/channels --list-generations
|
||||
```
|
||||
Print the names and URLs of all subscribed channels on standard output.
|
||||
|
||||
- `--rollback` \[*generation*\]\
|
||||
Revert channels to the state before the last call to `nix-channel --update`.
|
||||
Optionally, you can specify a specific channel *generation* number to restore.
|
||||
- `--update` \[*names*…\]
|
||||
|
||||
Download the Nix expressions of subscribed channels and create a new generation.
|
||||
Update all channels if none is specified, and only those included in *names* otherwise.
|
||||
|
||||
- `--list-generations`
|
||||
|
||||
Prints a list of all the current existing generations for the
|
||||
channel profile.
|
||||
|
||||
Works the same way as
|
||||
```
|
||||
nix-env --profile /nix/var/nix/profiles/per-user/$USER/channels --list-generations
|
||||
```
|
||||
|
||||
- `--rollback` \[*generation*\]
|
||||
|
||||
Revert channels to the state before the last call to `nix-channel --update`.
|
||||
Optionally, you can specify a specific channel *generation* number to restore.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
|
||||
@ -48,12 +48,14 @@ Instead, it looks in a few locations, and acts on all profiles it finds there:
|
||||
|
||||
These options are for deleting old [profiles] prior to deleting unreachable [store objects].
|
||||
|
||||
- <span id="opt-delete-old">[`--delete-old`](#opt-delete-old)</span> / `-d`\
|
||||
- <span id="opt-delete-old">[`--delete-old`](#opt-delete-old)</span> / `-d`
|
||||
|
||||
Delete all old generations of profiles.
|
||||
|
||||
This is the equivalent of invoking [`nix-env --delete-generations old`](@docroot@/command-ref/nix-env/delete-generations.md#generations-old) on each found profile.
|
||||
|
||||
- <span id="opt-delete-older-than">[`--delete-older-than`](#opt-delete-older-than)</span> *period*\
|
||||
- <span id="opt-delete-older-than">[`--delete-older-than`](#opt-delete-older-than)</span> *period*
|
||||
|
||||
Delete all generations of profiles older than the specified amount (except for the generations that were active at that point in time).
|
||||
*period* is a value such as `30d`, which would mean 30 days.
|
||||
|
||||
|
||||
@ -27,38 +27,38 @@ When using public key authentication, you can avoid typing the passphrase with `
|
||||
|
||||
# Options
|
||||
|
||||
- `--to`
|
||||
- `--to`
|
||||
|
||||
Copy the closure of _paths_ from a Nix store accessible from the local machine to the Nix store on the remote _machine_.
|
||||
This is the default behavior.
|
||||
Copy the closure of _paths_ from a Nix store accessible from the local machine to the Nix store on the remote _machine_.
|
||||
This is the default behavior.
|
||||
|
||||
- `--from`
|
||||
- `--from`
|
||||
|
||||
Copy the closure of _paths_ from the Nix store on the remote _machine_ to the local machine's specified Nix store.
|
||||
Copy the closure of _paths_ from the Nix store on the remote _machine_ to the local machine's specified Nix store.
|
||||
|
||||
- `--gzip`
|
||||
- `--gzip`
|
||||
|
||||
Enable compression of the SSH connection.
|
||||
Enable compression of the SSH connection.
|
||||
|
||||
- `--include-outputs`
|
||||
- `--include-outputs`
|
||||
|
||||
Also copy the outputs of [store derivation]s included in the closure.
|
||||
Also copy the outputs of [store derivation]s included in the closure.
|
||||
|
||||
[store derivation]: @docroot@/glossary.md#gloss-store-derivation
|
||||
[store derivation]: @docroot@/glossary.md#gloss-store-derivation
|
||||
|
||||
- `--use-substitutes` / `-s`
|
||||
- `--use-substitutes` / `-s`
|
||||
|
||||
Attempt to download missing store objects on the target from [substituters](@docroot@/command-ref/conf-file.md#conf-substituters).
|
||||
Any store objects that cannot be substituted on the target are still copied normally from the source.
|
||||
This is useful, for instance, if the connection between the source and target machine is slow, but the connection between the target machine and `cache.nixos.org` (the default binary cache server) is fast.
|
||||
Attempt to download missing store objects on the target from [substituters](@docroot@/command-ref/conf-file.md#conf-substituters).
|
||||
Any store objects that cannot be substituted on the target are still copied normally from the source.
|
||||
This is useful, for instance, if the connection between the source and target machine is slow, but the connection between the target machine and `cache.nixos.org` (the default binary cache server) is fast.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
# Environment variables
|
||||
|
||||
- `NIX_SSHOPTS`
|
||||
- `NIX_SSHOPTS`
|
||||
|
||||
Additional options to be passed to `ssh` on the command line.
|
||||
Additional options to be passed to `ssh` on the command line.
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
|
||||
@ -12,7 +12,8 @@ This operation deletes the specified generations of the current profile.
|
||||
|
||||
*generations* can be a one of the following:
|
||||
|
||||
- <span id="generations-list">[`<number>...`](#generations-list)</span>:\
|
||||
- <span id="generations-list">[`<number>...`](#generations-list)</span>
|
||||
|
||||
A list of generation numbers, each one a separate command-line argument.
|
||||
|
||||
Delete exactly the profile generations given by their generation number.
|
||||
@ -30,7 +31,8 @@ This operation deletes the specified generations of the current profile.
|
||||
> Because one can roll back to a previous generation, it is possible to have generations newer than the current one.
|
||||
> They will also be deleted.
|
||||
|
||||
- <span id="generations-time">[`<number>d`](#generations-time)</span>:\
|
||||
- <span id="generations-time">[`<number>d`](#generations-time)</span>
|
||||
|
||||
The last *number* days
|
||||
|
||||
*Example*: `30d`
|
||||
@ -38,7 +40,8 @@ This operation deletes the specified generations of the current profile.
|
||||
Delete all generations created more than *number* days ago, except the most recent one of them.
|
||||
This allows rolling back to generations that were available within the specified period.
|
||||
|
||||
- <span id="generations-count">[`+<number>`](#generations-count)</span>:\
|
||||
- <span id="generations-count">[`+<number>`](#generations-count)</span>
|
||||
|
||||
The last *number* generations up to the present
|
||||
|
||||
*Example*: `+5`
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
# Environment variables
|
||||
|
||||
- `NIX_PROFILE`\
|
||||
- `NIX_PROFILE`
|
||||
|
||||
Location of the Nix profile. Defaults to the target of the symlink
|
||||
`~/.nix-profile`, if it exists, or `/nix/var/nix/profiles/default`
|
||||
otherwise.
|
||||
|
||||
@ -21,125 +21,125 @@ It is based on the current generation of the active [profile](@docroot@/command-
|
||||
|
||||
The arguments *args* map to store paths in a number of possible ways:
|
||||
|
||||
- By default, *args* is a set of [derivation] names denoting derivations in the [default Nix expression].
|
||||
These are [realised], and the resulting output paths are installed.
|
||||
Currently installed derivations with a name equal to the name of a derivation being added are removed unless the option `--preserve-installed` is specified.
|
||||
- By default, *args* is a set of [derivation] names denoting derivations in the [default Nix expression].
|
||||
These are [realised], and the resulting output paths are installed.
|
||||
Currently installed derivations with a name equal to the name of a derivation being added are removed unless the option `--preserve-installed` is specified.
|
||||
|
||||
[derivation]: @docroot@/glossary.md#gloss-derivation
|
||||
[default Nix expression]: @docroot@/command-ref/files/default-nix-expression.md
|
||||
[realised]: @docroot@/glossary.md#gloss-realise
|
||||
[derivation]: @docroot@/glossary.md#gloss-derivation
|
||||
[default Nix expression]: @docroot@/command-ref/files/default-nix-expression.md
|
||||
[realised]: @docroot@/glossary.md#gloss-realise
|
||||
|
||||
If there are multiple derivations matching a name in *args* that
|
||||
have the same name (e.g., `gcc-3.3.6` and `gcc-4.1.1`), then the
|
||||
derivation with the highest *priority* is used. A derivation can
|
||||
define a priority by declaring the `meta.priority` attribute. This
|
||||
attribute should be a number, with a higher value denoting a lower
|
||||
priority. The default priority is `5`.
|
||||
If there are multiple derivations matching a name in *args* that
|
||||
have the same name (e.g., `gcc-3.3.6` and `gcc-4.1.1`), then the
|
||||
derivation with the highest *priority* is used. A derivation can
|
||||
define a priority by declaring the `meta.priority` attribute. This
|
||||
attribute should be a number, with a higher value denoting a lower
|
||||
priority. The default priority is `5`.
|
||||
|
||||
If there are multiple matching derivations with the same priority,
|
||||
then the derivation with the highest version will be installed.
|
||||
If there are multiple matching derivations with the same priority,
|
||||
then the derivation with the highest version will be installed.
|
||||
|
||||
You can force the installation of multiple derivations with the same
|
||||
name by being specific about the versions. For instance, `nix-env --install
|
||||
gcc-3.3.6 gcc-4.1.1` will install both version of GCC (and will
|
||||
probably cause a user environment conflict\!).
|
||||
You can force the installation of multiple derivations with the same
|
||||
name by being specific about the versions. For instance, `nix-env --install
|
||||
gcc-3.3.6 gcc-4.1.1` will install both version of GCC (and will
|
||||
probably cause a user environment conflict\!).
|
||||
|
||||
- If [`--attr`](#opt-attr) / `-A` is specified, the arguments are *attribute paths* that select attributes from the [default Nix expression].
|
||||
This is faster than using derivation names and unambiguous.
|
||||
Show the attribute paths of available packages with [`nix-env --query`](./query.md):
|
||||
- If [`--attr`](#opt-attr) / `-A` is specified, the arguments are *attribute paths* that select attributes from the [default Nix expression].
|
||||
This is faster than using derivation names and unambiguous.
|
||||
Show the attribute paths of available packages with [`nix-env --query`](./query.md):
|
||||
|
||||
```console
|
||||
nix-env --query --available --attr-path
|
||||
```
|
||||
```console
|
||||
nix-env --query --available --attr-path
|
||||
```
|
||||
|
||||
- If `--from-profile` *path* is given, *args* is a set of names
|
||||
denoting installed [store paths] in the profile *path*. This is an
|
||||
easy way to copy user environment elements from one profile to
|
||||
another.
|
||||
- If `--from-profile` *path* is given, *args* is a set of names
|
||||
denoting installed [store paths] in the profile *path*. This is an
|
||||
easy way to copy user environment elements from one profile to
|
||||
another.
|
||||
|
||||
- If `--from-expression` is given, *args* are [Nix language functions](@docroot@/language/constructs.md#functions) that are called with the [default Nix expression] as their single argument.
|
||||
The derivations returned by those function calls are installed.
|
||||
This allows derivations to be specified in an unambiguous way, which is necessary if there are multiple derivations with the same name.
|
||||
- If `--from-expression` is given, *args* are [Nix language functions](@docroot@/language/constructs.md#functions) that are called with the [default Nix expression] as their single argument.
|
||||
The derivations returned by those function calls are installed.
|
||||
This allows derivations to be specified in an unambiguous way, which is necessary if there are multiple derivations with the same name.
|
||||
|
||||
- If *args* are [store derivations](@docroot@/glossary.md#gloss-store-derivation), then these are [realised], and the resulting output paths are installed.
|
||||
- If *args* are [store derivations](@docroot@/glossary.md#gloss-store-derivation), then these are [realised], and the resulting output paths are installed.
|
||||
|
||||
- If *args* are [store paths] that are not store derivations, then these are [realised] and installed.
|
||||
- If *args* are [store paths] that are not store derivations, then these are [realised] and installed.
|
||||
|
||||
- By default all [outputs](@docroot@/language/derivations.md#attr-outputs) are installed for each [derivation].
|
||||
This can be overridden by adding a `meta.outputsToInstall` attribute on the derivation listing a subset of the output names.
|
||||
- By default all [outputs](@docroot@/language/derivations.md#attr-outputs) are installed for each [derivation].
|
||||
This can be overridden by adding a `meta.outputsToInstall` attribute on the derivation listing a subset of the output names.
|
||||
|
||||
Example:
|
||||
Example:
|
||||
|
||||
The file `example.nix` defines a derivation with two outputs `foo` and `bar`, each containing a file.
|
||||
The file `example.nix` defines a derivation with two outputs `foo` and `bar`, each containing a file.
|
||||
|
||||
```nix
|
||||
# example.nix
|
||||
let
|
||||
pkgs = import <nixpkgs> {};
|
||||
command = ''
|
||||
${pkgs.coreutils}/bin/mkdir -p $foo $bar
|
||||
echo foo > $foo/foo-file
|
||||
echo bar > $bar/bar-file
|
||||
'';
|
||||
in
|
||||
derivation {
|
||||
name = "example";
|
||||
builder = "${pkgs.bash}/bin/bash";
|
||||
args = [ "-c" command ];
|
||||
outputs = [ "foo" "bar" ];
|
||||
system = builtins.currentSystem;
|
||||
}
|
||||
```
|
||||
```nix
|
||||
# example.nix
|
||||
let
|
||||
pkgs = import <nixpkgs> {};
|
||||
command = ''
|
||||
${pkgs.coreutils}/bin/mkdir -p $foo $bar
|
||||
echo foo > $foo/foo-file
|
||||
echo bar > $bar/bar-file
|
||||
'';
|
||||
in
|
||||
derivation {
|
||||
name = "example";
|
||||
builder = "${pkgs.bash}/bin/bash";
|
||||
args = [ "-c" command ];
|
||||
outputs = [ "foo" "bar" ];
|
||||
system = builtins.currentSystem;
|
||||
}
|
||||
```
|
||||
|
||||
Installing from this Nix expression will make files from both outputs appear in the current profile.
|
||||
Installing from this Nix expression will make files from both outputs appear in the current profile.
|
||||
|
||||
```console
|
||||
$ nix-env --install --file example.nix
|
||||
installing 'example'
|
||||
$ ls ~/.nix-profile
|
||||
foo-file
|
||||
bar-file
|
||||
manifest.nix
|
||||
```
|
||||
```console
|
||||
$ nix-env --install --file example.nix
|
||||
installing 'example'
|
||||
$ ls ~/.nix-profile
|
||||
foo-file
|
||||
bar-file
|
||||
manifest.nix
|
||||
```
|
||||
|
||||
Adding `meta.outputsToInstall` to that derivation will make `nix-env` only install files from the specified outputs.
|
||||
Adding `meta.outputsToInstall` to that derivation will make `nix-env` only install files from the specified outputs.
|
||||
|
||||
```nix
|
||||
# example-outputs.nix
|
||||
import ./example.nix // { meta.outputsToInstall = [ "bar" ]; }
|
||||
```
|
||||
```nix
|
||||
# example-outputs.nix
|
||||
import ./example.nix // { meta.outputsToInstall = [ "bar" ]; }
|
||||
```
|
||||
|
||||
```console
|
||||
$ nix-env --install --file example-outputs.nix
|
||||
installing 'example'
|
||||
$ ls ~/.nix-profile
|
||||
bar-file
|
||||
manifest.nix
|
||||
```
|
||||
```console
|
||||
$ nix-env --install --file example-outputs.nix
|
||||
installing 'example'
|
||||
$ ls ~/.nix-profile
|
||||
bar-file
|
||||
manifest.nix
|
||||
```
|
||||
|
||||
# Options
|
||||
|
||||
- `--prebuilt-only` / `-b`
|
||||
- `--prebuilt-only` / `-b`
|
||||
|
||||
Use only derivations for which a substitute is registered, i.e.,
|
||||
there is a pre-built binary available that can be downloaded in lieu
|
||||
of building the derivation. Thus, no packages will be built from
|
||||
source.
|
||||
Use only derivations for which a substitute is registered, i.e.,
|
||||
there is a pre-built binary available that can be downloaded in lieu
|
||||
of building the derivation. Thus, no packages will be built from
|
||||
source.
|
||||
|
||||
- `--preserve-installed` / `-P`
|
||||
- `--preserve-installed` / `-P`
|
||||
|
||||
Do not remove derivations with a name matching one of the
|
||||
derivations being installed. Usually, trying to have two versions of
|
||||
the same package installed in the same generation of a profile will
|
||||
lead to an error in building the generation, due to file name
|
||||
clashes between the two versions. However, this is not the case for
|
||||
all packages.
|
||||
Do not remove derivations with a name matching one of the
|
||||
derivations being installed. Usually, trying to have two versions of
|
||||
the same package installed in the same generation of a profile will
|
||||
lead to an error in building the generation, due to file name
|
||||
clashes between the two versions. However, this is not the case for
|
||||
all packages.
|
||||
|
||||
- `--remove-all` / `-r`
|
||||
- `--remove-all` / `-r`
|
||||
|
||||
Remove all previously installed packages first. This is equivalent
|
||||
to running `nix-env --uninstall '.*'` first, except that everything happens
|
||||
in a single transaction.
|
||||
Remove all previously installed packages first. This is equivalent
|
||||
to running `nix-env --uninstall '.*'` first, except that everything happens
|
||||
in a single transaction.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
|
||||
@ -2,34 +2,37 @@
|
||||
|
||||
The following options are allowed for all `nix-env` operations, but may not always have an effect.
|
||||
|
||||
- `--file` / `-f` *path*\
|
||||
Specifies the Nix expression (designated below as the *active Nix
|
||||
expression*) used by the `--install`, `--upgrade`, and `--query
|
||||
--available` operations to obtain derivations. The default is
|
||||
`~/.nix-defexpr`.
|
||||
- `--file` / `-f` *path*
|
||||
|
||||
If the argument starts with `http://` or `https://`, it is
|
||||
interpreted as the URL of a tarball that will be downloaded and
|
||||
unpacked to a temporary location. The tarball must include a single
|
||||
top-level directory containing at least a file named `default.nix`.
|
||||
Specifies the Nix expression (designated below as the *active Nix
|
||||
expression*) used by the `--install`, `--upgrade`, and `--query
|
||||
--available` operations to obtain derivations. The default is
|
||||
`~/.nix-defexpr`.
|
||||
|
||||
- `--profile` / `-p` *path*\
|
||||
Specifies the profile to be used by those operations that operate on
|
||||
a profile (designated below as the *active profile*). A profile is a
|
||||
sequence of user environments called *generations*, one of which is
|
||||
the *current generation*.
|
||||
If the argument starts with `http://` or `https://`, it is
|
||||
interpreted as the URL of a tarball that will be downloaded and
|
||||
unpacked to a temporary location. The tarball must include a single
|
||||
top-level directory containing at least a file named `default.nix`.
|
||||
|
||||
- `--dry-run`\
|
||||
For the `--install`, `--upgrade`, `--uninstall`,
|
||||
`--switch-generation`, `--delete-generations` and `--rollback`
|
||||
operations, this flag will cause `nix-env` to print what *would* be
|
||||
done if this flag had not been specified, without actually doing it.
|
||||
- `--profile` / `-p` *path*
|
||||
|
||||
`--dry-run` also prints out which paths will be
|
||||
[substituted](@docroot@/glossary.md) (i.e., downloaded) and which paths
|
||||
will be built from source (because no substitute is available).
|
||||
Specifies the profile to be used by those operations that operate on
|
||||
a profile (designated below as the *active profile*). A profile is a
|
||||
sequence of user environments called *generations*, one of which is
|
||||
the *current generation*.
|
||||
|
||||
- `--system-filter` *system*\
|
||||
By default, operations such as `--query
|
||||
--available` show derivations matching any platform. This option
|
||||
allows you to use derivations for the specified platform *system*.
|
||||
- `--dry-run`
|
||||
|
||||
For the `--install`, `--upgrade`, `--uninstall`,
|
||||
`--switch-generation`, `--delete-generations` and `--rollback`
|
||||
operations, this flag will cause `nix-env` to print what *would* be
|
||||
done if this flag had not been specified, without actually doing it.
|
||||
|
||||
`--dry-run` also prints out which paths will be
|
||||
[substituted](@docroot@/glossary.md) (i.e., downloaded) and which paths
|
||||
will be built from source (because no substitute is available).
|
||||
|
||||
- `--system-filter` *system*
|
||||
|
||||
By default, operations such as `--query --available` show derivations matching any platform. This option
|
||||
allows you to use derivations for the specified platform *system*.
|
||||
|
||||
@ -35,11 +35,13 @@ The derivations are sorted by their `name` attributes.
|
||||
The following flags specify the set of things on which the query
|
||||
operates.
|
||||
|
||||
- `--installed`\
|
||||
- `--installed`
|
||||
|
||||
The query operates on the store paths that are installed in the
|
||||
current generation of the active profile. This is the default.
|
||||
|
||||
- `--available`; `-a`\
|
||||
- `--available` / `-a`
|
||||
|
||||
The query operates on the derivations that are available in the
|
||||
active Nix expression.
|
||||
|
||||
@ -50,24 +52,28 @@ selected derivations. Multiple flags may be specified, in which case the
|
||||
information is shown in the order given here. Note that the name of the
|
||||
derivation is shown unless `--no-name` is specified.
|
||||
|
||||
- `--xml`\
|
||||
- `--xml`
|
||||
|
||||
Print the result in an XML representation suitable for automatic
|
||||
processing by other tools. The root element is called `items`, which
|
||||
contains a `item` element for each available or installed
|
||||
derivation. The fields discussed below are all stored in attributes
|
||||
of the `item` elements.
|
||||
|
||||
- `--json`\
|
||||
- `--json`
|
||||
|
||||
Print the result in a JSON representation suitable for automatic
|
||||
processing by other tools.
|
||||
|
||||
- `--prebuilt-only` / `-b`\
|
||||
- `--prebuilt-only` / `-b`
|
||||
|
||||
Show only derivations for which a substitute is registered, i.e.,
|
||||
there is a pre-built binary available that can be downloaded in lieu
|
||||
of building the derivation. Thus, this shows all packages that
|
||||
probably can be installed quickly.
|
||||
|
||||
- `--status`; `-s`\
|
||||
- `--status` / `-s`
|
||||
|
||||
Print the *status* of the derivation. The status consists of three
|
||||
characters. The first is `I` or `-`, indicating whether the
|
||||
derivation is currently installed in the current generation of the
|
||||
@ -78,49 +84,61 @@ derivation is shown unless `--no-name` is specified.
|
||||
derivation to be built. The third is `S` or `-`, indicating whether
|
||||
a substitute is available for the derivation.
|
||||
|
||||
- `--attr-path`; `-P`\
|
||||
- `--attr-path` / `-P`
|
||||
|
||||
Print the *attribute path* of the derivation, which can be used to
|
||||
unambiguously select it using the `--attr` option available in
|
||||
commands that install derivations like `nix-env --install`. This
|
||||
option only works together with `--available`
|
||||
|
||||
- `--no-name`\
|
||||
- `--no-name`
|
||||
|
||||
Suppress printing of the `name` attribute of each derivation.
|
||||
|
||||
- `--compare-versions` / `-c`\
|
||||
- `--compare-versions` / `-c`
|
||||
|
||||
Compare installed versions to available versions, or vice versa (if
|
||||
`--available` is given). This is useful for quickly seeing whether
|
||||
upgrades for installed packages are available in a Nix expression. A
|
||||
column is added with the following meaning:
|
||||
|
||||
- `<` *version*\
|
||||
- `<` *version*
|
||||
|
||||
A newer version of the package is available or installed.
|
||||
|
||||
- `=` *version*\
|
||||
- `=` *version*
|
||||
|
||||
At most the same version of the package is available or
|
||||
installed.
|
||||
|
||||
- `>` *version*\
|
||||
- `>` *version*
|
||||
|
||||
Only older versions of the package are available or installed.
|
||||
|
||||
- `- ?`\
|
||||
- `- ?`
|
||||
|
||||
No version of the package is available or installed.
|
||||
|
||||
- `--system`\
|
||||
- `--system`
|
||||
|
||||
Print the `system` attribute of the derivation.
|
||||
|
||||
- `--drv-path`\
|
||||
- `--drv-path`
|
||||
|
||||
Print the path of the [store derivation](@docroot@/glossary.md#gloss-store-derivation).
|
||||
|
||||
- `--out-path`\
|
||||
- `--out-path`
|
||||
|
||||
Print the output path of the derivation.
|
||||
|
||||
- `--description`\
|
||||
- `--description`
|
||||
|
||||
Print a short (one-line) description of the derivation, if
|
||||
available. The description is taken from the `meta.description`
|
||||
attribute of the derivation.
|
||||
|
||||
- `--meta`\
|
||||
- `--meta`
|
||||
|
||||
Print all of the meta-attributes of the derivation. This option is
|
||||
only available with `--xml` or `--json`.
|
||||
|
||||
|
||||
@ -13,24 +13,24 @@ to be modified. There are several attributes that can be usefully
|
||||
modified, because they affect the behaviour of `nix-env` or the user
|
||||
environment build script:
|
||||
|
||||
- `priority` can be changed to resolve filename clashes. The user
|
||||
environment build script uses the `meta.priority` attribute of
|
||||
derivations to resolve filename collisions between packages. Lower
|
||||
priority values denote a higher priority. For instance, the GCC
|
||||
wrapper package and the Binutils package in Nixpkgs both have a file
|
||||
`bin/ld`, so previously if you tried to install both you would get a
|
||||
collision. Now, on the other hand, the GCC wrapper declares a higher
|
||||
priority than Binutils, so the former’s `bin/ld` is symlinked in the
|
||||
user environment.
|
||||
- `priority` can be changed to resolve filename clashes. The user
|
||||
environment build script uses the `meta.priority` attribute of
|
||||
derivations to resolve filename collisions between packages. Lower
|
||||
priority values denote a higher priority. For instance, the GCC
|
||||
wrapper package and the Binutils package in Nixpkgs both have a file
|
||||
`bin/ld`, so previously if you tried to install both you would get a
|
||||
collision. Now, on the other hand, the GCC wrapper declares a higher
|
||||
priority than Binutils, so the former’s `bin/ld` is symlinked in the
|
||||
user environment.
|
||||
|
||||
- `keep` can be set to `true` to prevent the package from being
|
||||
upgraded or replaced. This is useful if you want to hang on to an
|
||||
older version of a package.
|
||||
- `keep` can be set to `true` to prevent the package from being
|
||||
upgraded or replaced. This is useful if you want to hang on to an
|
||||
older version of a package.
|
||||
|
||||
- `active` can be set to `false` to “disable” the package. That is, no
|
||||
symlinks will be generated to the files of the package, but it
|
||||
remains part of the profile (so it won’t be garbage-collected). It
|
||||
can be set back to `true` to re-enable the package.
|
||||
- `active` can be set to `false` to “disable” the package. That is, no
|
||||
symlinks will be generated to the files of the package, but it
|
||||
remains part of the profile (so it won’t be garbage-collected). It
|
||||
can be set back to `true` to re-enable the package.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
|
||||
@ -28,42 +28,48 @@ version is installed.
|
||||
|
||||
# Flags
|
||||
|
||||
- `--lt`\
|
||||
Only upgrade a derivation to newer versions. This is the default.
|
||||
- `--lt`
|
||||
|
||||
- `--leq`\
|
||||
In addition to upgrading to newer versions, also “upgrade” to
|
||||
derivations that have the same version. Version are not a unique
|
||||
identification of a derivation, so there may be many derivations
|
||||
that have the same version. This flag may be useful to force
|
||||
“synchronisation” between the installed and available derivations.
|
||||
Only upgrade a derivation to newer versions. This is the default.
|
||||
|
||||
- `--eq`\
|
||||
*Only* “upgrade” to derivations that have the same version. This may
|
||||
not seem very useful, but it actually is, e.g., when there is a new
|
||||
release of Nixpkgs and you want to replace installed applications
|
||||
with the same versions built against newer dependencies (to reduce
|
||||
the number of dependencies floating around on your system).
|
||||
- `--leq`
|
||||
|
||||
- `--always`\
|
||||
In addition to upgrading to newer versions, also “upgrade” to
|
||||
derivations that have the same or a lower version. I.e., derivations
|
||||
may actually be downgraded depending on what is available in the
|
||||
active Nix expression.
|
||||
In addition to upgrading to newer versions, also “upgrade” to
|
||||
derivations that have the same version. Version are not a unique
|
||||
identification of a derivation, so there may be many derivations
|
||||
that have the same version. This flag may be useful to force
|
||||
“synchronisation” between the installed and available derivations.
|
||||
|
||||
- `--prebuilt-only` / `-b`\
|
||||
Use only derivations for which a substitute is registered, i.e.,
|
||||
there is a pre-built binary available that can be downloaded in lieu
|
||||
of building the derivation. Thus, no packages will be built from
|
||||
source.
|
||||
- `--eq`
|
||||
|
||||
- `--preserve-installed` / `-P`\
|
||||
Do not remove derivations with a name matching one of the
|
||||
derivations being installed. Usually, trying to have two versions of
|
||||
the same package installed in the same generation of a profile will
|
||||
lead to an error in building the generation, due to file name
|
||||
clashes between the two versions. However, this is not the case for
|
||||
all packages.
|
||||
*Only* “upgrade” to derivations that have the same version. This may
|
||||
not seem very useful, but it actually is, e.g., when there is a new
|
||||
release of Nixpkgs and you want to replace installed applications
|
||||
with the same versions built against newer dependencies (to reduce
|
||||
the number of dependencies floating around on your system).
|
||||
|
||||
- `--always`
|
||||
|
||||
In addition to upgrading to newer versions, also “upgrade” to
|
||||
derivations that have the same or a lower version. I.e., derivations
|
||||
may actually be downgraded depending on what is available in the
|
||||
active Nix expression.
|
||||
|
||||
- `--prebuilt-only` / `-b`
|
||||
|
||||
Use only derivations for which a substitute is registered, i.e.,
|
||||
there is a pre-built binary available that can be downloaded in lieu
|
||||
of building the derivation. Thus, no packages will be built from
|
||||
source.
|
||||
|
||||
- `--preserve-installed` / `-P`
|
||||
|
||||
Do not remove derivations with a name matching one of the
|
||||
derivations being installed. Usually, trying to have two versions of
|
||||
the same package installed in the same generation of a profile will
|
||||
lead to an error in building the generation, due to file name
|
||||
clashes between the two versions. However, this is not the case for
|
||||
all packages.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
|
||||
@ -29,54 +29,65 @@ md5sum`.
|
||||
|
||||
# Options
|
||||
|
||||
- `--flat`\
|
||||
Print the cryptographic hash of the contents of each regular file *path*.
|
||||
That is, instead of computing
|
||||
the hash of the [Nix Archive (NAR)](@docroot@/store/file-system-object/content-address.md#serial-nix-archive) of *path*,
|
||||
just [directly hash]((@docroot@/store/file-system-object/content-address.md#serial-flat) *path* as is.
|
||||
This requires *path* to resolve to a regular file rather than directory.
|
||||
The result is identical to that produced by the GNU commands
|
||||
`md5sum` and `sha1sum`.
|
||||
- `--flat`
|
||||
|
||||
- `--base16`\
|
||||
Print the hash in a hexadecimal representation (default).
|
||||
Print the cryptographic hash of the contents of each regular file *path*.
|
||||
That is, instead of computing
|
||||
the hash of the [Nix Archive (NAR)](@docroot@/store/file-system-object/content-address.md#serial-nix-archive) of *path*,
|
||||
just [directly hash]((@docroot@/store/file-system-object/content-address.md#serial-flat) *path* as is.
|
||||
This requires *path* to resolve to a regular file rather than directory.
|
||||
The result is identical to that produced by the GNU commands
|
||||
`md5sum` and `sha1sum`.
|
||||
|
||||
- `--base32`\
|
||||
Print the hash in a base-32 representation rather than hexadecimal.
|
||||
This base-32 representation is more compact and can be used in Nix
|
||||
expressions (such as in calls to `fetchurl`).
|
||||
- `--base16`
|
||||
|
||||
- `--base64`\
|
||||
Similar to --base32, but print the hash in a base-64 representation,
|
||||
which is more compact than the base-32 one.
|
||||
Print the hash in a hexadecimal representation (default).
|
||||
|
||||
- `--sri`\
|
||||
Print the hash in SRI format with base-64 encoding.
|
||||
The type of hash algorithm will be prepended to the hash string,
|
||||
followed by a hyphen (-) and the base-64 hash body.
|
||||
- `--base32`
|
||||
|
||||
- `--truncate`\
|
||||
Truncate hashes longer than 160 bits (such as SHA-256) to 160 bits.
|
||||
Print the hash in a base-32 representation rather than hexadecimal.
|
||||
This base-32 representation is more compact and can be used in Nix
|
||||
expressions (such as in calls to `fetchurl`).
|
||||
|
||||
- `--type` *hashAlgo*\
|
||||
Use the specified cryptographic hash algorithm, which can be one of
|
||||
`md5`, `sha1`, `sha256`, and `sha512`.
|
||||
- `--base64`
|
||||
|
||||
- `--to-base16`\
|
||||
Don’t hash anything, but convert the base-32 hash representation
|
||||
*hash* to hexadecimal.
|
||||
Similar to --base32, but print the hash in a base-64 representation,
|
||||
which is more compact than the base-32 one.
|
||||
|
||||
- `--to-base32`\
|
||||
Don’t hash anything, but convert the hexadecimal hash representation
|
||||
*hash* to base-32.
|
||||
- `--sri`
|
||||
|
||||
- `--to-base64`\
|
||||
Don’t hash anything, but convert the hexadecimal hash representation
|
||||
*hash* to base-64.
|
||||
Print the hash in SRI format with base-64 encoding.
|
||||
The type of hash algorithm will be prepended to the hash string,
|
||||
followed by a hyphen (-) and the base-64 hash body.
|
||||
|
||||
- `--to-sri`\
|
||||
Don’t hash anything, but convert the hexadecimal hash representation
|
||||
*hash* to SRI.
|
||||
- `--truncate`
|
||||
|
||||
Truncate hashes longer than 160 bits (such as SHA-256) to 160 bits.
|
||||
|
||||
- `--type` *hashAlgo*
|
||||
|
||||
Use the specified cryptographic hash algorithm, which can be one of
|
||||
`md5`, `sha1`, `sha256`, and `sha512`.
|
||||
|
||||
- `--to-base16`
|
||||
|
||||
Don’t hash anything, but convert the base-32 hash representation
|
||||
*hash* to hexadecimal.
|
||||
|
||||
- `--to-base32`
|
||||
|
||||
Don’t hash anything, but convert the hexadecimal hash representation
|
||||
*hash* to base-32.
|
||||
|
||||
- `--to-base64`
|
||||
|
||||
Don’t hash anything, but convert the hexadecimal hash representation
|
||||
*hash* to base-64.
|
||||
|
||||
- `--to-sri`
|
||||
|
||||
Don’t hash anything, but convert the hexadecimal hash representation
|
||||
*hash* to SRI.
|
||||
|
||||
# Examples
|
||||
|
||||
|
||||
@ -30,89 +30,97 @@ standard input.
|
||||
|
||||
# Options
|
||||
|
||||
- `--add-root` *path*\
|
||||
See the [corresponding option](nix-store.md) in `nix-store`.
|
||||
- `--add-root` *path*
|
||||
|
||||
- `--parse`\
|
||||
Just parse the input files, and print their abstract syntax trees on
|
||||
standard output as a Nix expression.
|
||||
See the [corresponding option](nix-store.md) in `nix-store`.
|
||||
|
||||
- `--eval`\
|
||||
Just parse and evaluate the input files, and print the resulting
|
||||
values on standard output. No instantiation of store derivations
|
||||
takes place.
|
||||
- `--parse`
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
> This option produces output which can be parsed as a Nix expression which
|
||||
> will produce a different result than the input expression when evaluated.
|
||||
> For example, these two Nix expressions print the same result despite
|
||||
> having different meaning:
|
||||
>
|
||||
> ```console
|
||||
> $ nix-instantiate --eval --expr '{ a = {}; }'
|
||||
> { a = <CODE>; }
|
||||
> $ nix-instantiate --eval --expr '{ a = <CODE>; }'
|
||||
> { a = <CODE>; }
|
||||
> ```
|
||||
>
|
||||
> For human-readable output, `nix eval` (experimental) is more informative:
|
||||
>
|
||||
> ```console
|
||||
> $ nix-instantiate --eval --expr 'a: a'
|
||||
> <LAMBDA>
|
||||
> $ nix eval --expr 'a: a'
|
||||
> «lambda @ «string»:1:1»
|
||||
> ```
|
||||
>
|
||||
> For machine-readable output, the `--xml` option produces unambiguous
|
||||
> output:
|
||||
>
|
||||
> ```console
|
||||
> $ nix-instantiate --eval --xml --expr '{ foo = <CODE>; }'
|
||||
> <?xml version='1.0' encoding='utf-8'?>
|
||||
> <expr>
|
||||
> <attrs>
|
||||
> <attr column="3" line="1" name="foo">
|
||||
> <unevaluated />
|
||||
> </attr>
|
||||
> </attrs>
|
||||
> </expr>
|
||||
> ```
|
||||
Just parse the input files, and print their abstract syntax trees on
|
||||
standard output as a Nix expression.
|
||||
|
||||
- `--find-file`\
|
||||
Look up the given files in Nix’s search path (as specified by the
|
||||
`NIX_PATH` environment variable). If found, print the corresponding
|
||||
absolute paths on standard output. For instance, if `NIX_PATH` is
|
||||
`nixpkgs=/home/alice/nixpkgs`, then `nix-instantiate --find-file
|
||||
nixpkgs/default.nix` will print `/home/alice/nixpkgs/default.nix`.
|
||||
- `--eval`
|
||||
|
||||
- `--strict`\
|
||||
When used with `--eval`, recursively evaluate list elements and
|
||||
attributes. Normally, such sub-expressions are left unevaluated
|
||||
(since the Nix language is lazy).
|
||||
Just parse and evaluate the input files, and print the resulting
|
||||
values on standard output. No instantiation of store derivations
|
||||
takes place.
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
> This option can cause non-termination, because lazy data
|
||||
> structures can be infinitely large.
|
||||
> **Warning**
|
||||
>
|
||||
> This option produces output which can be parsed as a Nix expression which
|
||||
> will produce a different result than the input expression when evaluated.
|
||||
> For example, these two Nix expressions print the same result despite
|
||||
> having different meaning:
|
||||
>
|
||||
> ```console
|
||||
> $ nix-instantiate --eval --expr '{ a = {}; }'
|
||||
> { a = <CODE>; }
|
||||
> $ nix-instantiate --eval --expr '{ a = <CODE>; }'
|
||||
> { a = <CODE>; }
|
||||
> ```
|
||||
>
|
||||
> For human-readable output, `nix eval` (experimental) is more informative:
|
||||
>
|
||||
> ```console
|
||||
> $ nix-instantiate --eval --expr 'a: a'
|
||||
> <LAMBDA>
|
||||
> $ nix eval --expr 'a: a'
|
||||
> «lambda @ «string»:1:1»
|
||||
> ```
|
||||
>
|
||||
> For machine-readable output, the `--xml` option produces unambiguous
|
||||
> output:
|
||||
>
|
||||
> ```console
|
||||
> $ nix-instantiate --eval --xml --expr '{ foo = <CODE>; }'
|
||||
> <?xml version='1.0' encoding='utf-8'?>
|
||||
> <expr>
|
||||
> <attrs>
|
||||
> <attr column="3" line="1" name="foo">
|
||||
> <unevaluated />
|
||||
> </attr>
|
||||
> </attrs>
|
||||
> </expr>
|
||||
> ```
|
||||
|
||||
- `--json`\
|
||||
When used with `--eval`, print the resulting value as an JSON
|
||||
representation of the abstract syntax tree rather than as a Nix expression.
|
||||
- `--find-file`
|
||||
|
||||
- `--xml`\
|
||||
When used with `--eval`, print the resulting value as an XML
|
||||
representation of the abstract syntax tree rather than as a Nix expression.
|
||||
The schema is the same as that used by the [`toXML`
|
||||
built-in](../language/builtins.md).
|
||||
Look up the given files in Nix’s search path (as specified by the
|
||||
`NIX_PATH` environment variable). If found, print the corresponding
|
||||
absolute paths on standard output. For instance, if `NIX_PATH` is
|
||||
`nixpkgs=/home/alice/nixpkgs`, then `nix-instantiate --find-file
|
||||
nixpkgs/default.nix` will print `/home/alice/nixpkgs/default.nix`.
|
||||
|
||||
- `--read-write-mode`\
|
||||
When used with `--eval`, perform evaluation in read/write mode so
|
||||
nix language features that require it will still work (at the cost
|
||||
of needing to do instantiation of every evaluated derivation). If
|
||||
this option is not enabled, there may be uninstantiated store paths
|
||||
in the final output.
|
||||
- `--strict`
|
||||
|
||||
When used with `--eval`, recursively evaluate list elements and
|
||||
attributes. Normally, such sub-expressions are left unevaluated
|
||||
(since the Nix language is lazy).
|
||||
|
||||
> **Warning**
|
||||
>
|
||||
> This option can cause non-termination, because lazy data
|
||||
> structures can be infinitely large.
|
||||
|
||||
- `--json`
|
||||
|
||||
When used with `--eval`, print the resulting value as an JSON
|
||||
representation of the abstract syntax tree rather than as a Nix expression.
|
||||
|
||||
- `--xml`
|
||||
|
||||
When used with `--eval`, print the resulting value as an XML
|
||||
representation of the abstract syntax tree rather than as a Nix expression.
|
||||
The schema is the same as that used by the [`toXML`
|
||||
built-in](../language/builtins.md).
|
||||
|
||||
- `--read-write-mode`
|
||||
|
||||
When used with `--eval`, perform evaluation in read/write mode so
|
||||
nix language features that require it will still work (at the cost
|
||||
of needing to do instantiation of every evaluated derivation). If
|
||||
this option is not enabled, there may be uninstantiated store paths
|
||||
in the final output.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
|
||||
@ -39,27 +39,32 @@ the path of the downloaded file in the Nix store is also printed.
|
||||
|
||||
# Options
|
||||
|
||||
- `--type` *hashAlgo*\
|
||||
Use the specified cryptographic hash algorithm,
|
||||
which can be one of `md5`, `sha1`, `sha256`, and `sha512`.
|
||||
The default is `sha256`.
|
||||
- `--type` *hashAlgo*
|
||||
|
||||
- `--print-path`\
|
||||
Print the store path of the downloaded file on standard output.
|
||||
Use the specified cryptographic hash algorithm,
|
||||
which can be one of `md5`, `sha1`, `sha256`, and `sha512`.
|
||||
The default is `sha256`.
|
||||
|
||||
- `--unpack`\
|
||||
Unpack the archive (which must be a tarball or zip file) and add the
|
||||
result to the Nix store. The resulting hash can be used with
|
||||
functions such as Nixpkgs’s `fetchzip` or `fetchFromGitHub`.
|
||||
- `--print-path`
|
||||
|
||||
- `--executable`\
|
||||
Set the executable bit on the downloaded file.
|
||||
Print the store path of the downloaded file on standard output.
|
||||
|
||||
- `--name` *name*\
|
||||
Override the name of the file in the Nix store. By default, this is
|
||||
`hash-basename`, where *basename* is the last component of *url*.
|
||||
Overriding the name is necessary when *basename* contains characters
|
||||
that are not allowed in Nix store paths.
|
||||
- `--unpack`
|
||||
|
||||
Unpack the archive (which must be a tarball or zip file) and add the
|
||||
result to the Nix store. The resulting hash can be used with
|
||||
functions such as Nixpkgs’s `fetchzip` or `fetchFromGitHub`.
|
||||
|
||||
- `--executable`
|
||||
|
||||
Set the executable bit on the downloaded file.
|
||||
|
||||
- `--name` *name*
|
||||
|
||||
Override the name of the file in the Nix store. By default, this is
|
||||
`hash-basename`, where *basename* is the last component of *url*.
|
||||
Overriding the name is necessary when *basename* contains characters
|
||||
that are not allowed in Nix store paths.
|
||||
|
||||
# Examples
|
||||
|
||||
|
||||
@ -60,55 +60,63 @@ All options not listed here are passed to `nix-store
|
||||
--realise`, except for `--arg` and `--attr` / `-A` which are passed to
|
||||
`nix-instantiate`.
|
||||
|
||||
- `--command` *cmd*\
|
||||
In the environment of the derivation, run the shell command *cmd*.
|
||||
This command is executed in an interactive shell. (Use `--run` to
|
||||
use a non-interactive shell instead.) However, a call to `exit` is
|
||||
implicitly added to the command, so the shell will exit after
|
||||
running the command. To prevent this, add `return` at the end;
|
||||
e.g. `--command "echo Hello; return"` will print `Hello` and then
|
||||
drop you into the interactive shell. This can be useful for doing
|
||||
any additional initialisation.
|
||||
- `--command` *cmd*
|
||||
|
||||
- `--run` *cmd*\
|
||||
Like `--command`, but executes the command in a non-interactive
|
||||
shell. This means (among other things) that if you hit Ctrl-C while
|
||||
the command is running, the shell exits.
|
||||
In the environment of the derivation, run the shell command *cmd*.
|
||||
This command is executed in an interactive shell. (Use `--run` to
|
||||
use a non-interactive shell instead.) However, a call to `exit` is
|
||||
implicitly added to the command, so the shell will exit after
|
||||
running the command. To prevent this, add `return` at the end;
|
||||
e.g. `--command "echo Hello; return"` will print `Hello` and then
|
||||
drop you into the interactive shell. This can be useful for doing
|
||||
any additional initialisation.
|
||||
|
||||
- `--exclude` *regexp*\
|
||||
Do not build any dependencies whose store path matches the regular
|
||||
expression *regexp*. This option may be specified multiple times.
|
||||
- `--run` *cmd*
|
||||
|
||||
- `--pure`\
|
||||
If this flag is specified, the environment is almost entirely
|
||||
cleared before the interactive shell is started, so you get an
|
||||
environment that more closely corresponds to the “real” Nix build. A
|
||||
few variables, in particular `HOME`, `USER` and `DISPLAY`, are
|
||||
retained.
|
||||
Like `--command`, but executes the command in a non-interactive
|
||||
shell. This means (among other things) that if you hit Ctrl-C while
|
||||
the command is running, the shell exits.
|
||||
|
||||
- `--packages` / `-p` *packages*…\
|
||||
Set up an environment in which the specified packages are present.
|
||||
The command line arguments are interpreted as attribute names inside
|
||||
the Nix Packages collection. Thus, `nix-shell --packages libjpeg openjdk`
|
||||
will start a shell in which the packages denoted by the attribute
|
||||
names `libjpeg` and `openjdk` are present.
|
||||
- `--exclude` *regexp*
|
||||
|
||||
- `-i` *interpreter*\
|
||||
The chained script interpreter to be invoked by `nix-shell`. Only
|
||||
applicable in `#!`-scripts (described below).
|
||||
Do not build any dependencies whose store path matches the regular
|
||||
expression *regexp*. This option may be specified multiple times.
|
||||
|
||||
- `--keep` *name*\
|
||||
When a `--pure` shell is started, keep the listed environment
|
||||
variables.
|
||||
- `--pure`
|
||||
|
||||
If this flag is specified, the environment is almost entirely
|
||||
cleared before the interactive shell is started, so you get an
|
||||
environment that more closely corresponds to the “real” Nix build. A
|
||||
few variables, in particular `HOME`, `USER` and `DISPLAY`, are
|
||||
retained.
|
||||
|
||||
- `--packages` / `-p` *packages*…
|
||||
|
||||
Set up an environment in which the specified packages are present.
|
||||
The command line arguments are interpreted as attribute names inside
|
||||
the Nix Packages collection. Thus, `nix-shell --packages libjpeg openjdk`
|
||||
will start a shell in which the packages denoted by the attribute
|
||||
names `libjpeg` and `openjdk` are present.
|
||||
|
||||
- `-i` *interpreter*
|
||||
|
||||
The chained script interpreter to be invoked by `nix-shell`. Only
|
||||
applicable in `#!`-scripts (described below).
|
||||
|
||||
- `--keep` *name*
|
||||
|
||||
When a `--pure` shell is started, keep the listed environment
|
||||
variables.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
# Environment variables
|
||||
|
||||
- `NIX_BUILD_SHELL`\
|
||||
Shell used to start the interactive environment. Defaults to the
|
||||
`bash` found in `<nixpkgs>`, falling back to the `bash` found in
|
||||
`PATH` if not found.
|
||||
- `NIX_BUILD_SHELL`
|
||||
|
||||
Shell used to start the interactive environment. Defaults to the
|
||||
`bash` found in `<nixpkgs>`, falling back to the `bash` found in
|
||||
`PATH` if not found.
|
||||
|
||||
{{#include ./env-common.md}}
|
||||
|
||||
|
||||
@ -16,9 +16,10 @@ public url or broke since the download expression was written.
|
||||
|
||||
This operation has the following options:
|
||||
|
||||
- `--recursive`\
|
||||
Use recursive instead of flat hashing mode, used when adding
|
||||
directories to the store.
|
||||
- `--recursive`
|
||||
|
||||
Use recursive instead of flat hashing mode, used when adding
|
||||
directories to the store.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
|
||||
@ -14,30 +14,34 @@ reachable via file system references from a set of “roots”, are deleted.
|
||||
|
||||
The following suboperations may be specified:
|
||||
|
||||
- `--print-roots`\
|
||||
This operation prints on standard output the set of roots used by
|
||||
the garbage collector.
|
||||
- `--print-roots`
|
||||
|
||||
- `--print-live`\
|
||||
This operation prints on standard output the set of “live” store
|
||||
paths, which are all the store paths reachable from the roots. Live
|
||||
paths should never be deleted, since that would break consistency —
|
||||
it would become possible that applications are installed that
|
||||
reference things that are no longer present in the store.
|
||||
This operation prints on standard output the set of roots used by
|
||||
the garbage collector.
|
||||
|
||||
- `--print-dead`\
|
||||
This operation prints out on standard output the set of “dead” store
|
||||
paths, which is just the opposite of the set of live paths: any path
|
||||
in the store that is not live (with respect to the roots) is dead.
|
||||
- `--print-live`
|
||||
|
||||
This operation prints on standard output the set of “live” store
|
||||
paths, which are all the store paths reachable from the roots. Live
|
||||
paths should never be deleted, since that would break consistency —
|
||||
it would become possible that applications are installed that
|
||||
reference things that are no longer present in the store.
|
||||
|
||||
- `--print-dead`
|
||||
|
||||
This operation prints out on standard output the set of “dead” store
|
||||
paths, which is just the opposite of the set of live paths: any path
|
||||
in the store that is not live (with respect to the roots) is dead.
|
||||
|
||||
By default, all unreachable paths are deleted. The following options
|
||||
control what gets deleted and in what order:
|
||||
|
||||
- `--max-freed` *bytes*\
|
||||
Keep deleting paths until at least *bytes* bytes have been deleted,
|
||||
then stop. The argument *bytes* can be followed by the
|
||||
multiplicative suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB
|
||||
or TiB units.
|
||||
- `--max-freed` *bytes*
|
||||
|
||||
Keep deleting paths until at least *bytes* bytes have been deleted,
|
||||
then stop. The argument *bytes* can be followed by the
|
||||
multiplicative suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB
|
||||
or TiB units.
|
||||
|
||||
The behaviour of the collector is also influenced by the
|
||||
`keep-outputs` and `keep-derivations` settings in the Nix
|
||||
|
||||
@ -24,122 +24,138 @@ symlink.
|
||||
|
||||
# Common query options
|
||||
|
||||
- `--use-output`; `-u`\
|
||||
For each argument to the query that is a [store derivation], apply the
|
||||
query to the output path of the derivation instead.
|
||||
- `--use-output` / `-u`
|
||||
|
||||
- `--force-realise`; `-f`\
|
||||
Realise each argument to the query first (see [`nix-store --realise`](./realise.md)).
|
||||
For each argument to the query that is a [store derivation], apply the
|
||||
query to the output path of the derivation instead.
|
||||
|
||||
- `--force-realise` / `-f`
|
||||
|
||||
Realise each argument to the query first (see [`nix-store --realise`](./realise.md)).
|
||||
|
||||
[store derivation]: @docroot@/glossary.md#gloss-store-derivation
|
||||
|
||||
# Queries
|
||||
|
||||
- `--outputs`\
|
||||
Prints out the [output paths] of the store
|
||||
derivations *paths*. These are the paths that will be produced when
|
||||
the derivation is built.
|
||||
- `--outputs`
|
||||
|
||||
[output paths]: @docroot@/glossary.md#gloss-output-path
|
||||
Prints out the [output paths] of the store
|
||||
derivations *paths*. These are the paths that will be produced when
|
||||
the derivation is built.
|
||||
|
||||
- `--requisites`; `-R`\
|
||||
Prints out the [closure] of the store path *paths*.
|
||||
[output paths]: @docroot@/glossary.md#gloss-output-path
|
||||
|
||||
[closure]: @docroot@/glossary.md#gloss-closure
|
||||
- `--requisites` / `-R`
|
||||
|
||||
This query has one option:
|
||||
Prints out the [closure] of the store path *paths*.
|
||||
|
||||
- `--include-outputs`
|
||||
Also include the existing output paths of [store derivation]s,
|
||||
and their closures.
|
||||
[closure]: @docroot@/glossary.md#gloss-closure
|
||||
|
||||
This query can be used to implement various kinds of deployment. A
|
||||
*source deployment* is obtained by distributing the closure of a
|
||||
store derivation. A *binary deployment* is obtained by distributing
|
||||
the closure of an output path. A *cache deployment* (combined
|
||||
source/binary deployment, including binaries of build-time-only
|
||||
dependencies) is obtained by distributing the closure of a store
|
||||
derivation and specifying the option `--include-outputs`.
|
||||
This query has one option:
|
||||
|
||||
- `--references`\
|
||||
Prints the set of [references] of the store paths
|
||||
*paths*, that is, their immediate dependencies. (For *all*
|
||||
dependencies, use `--requisites`.)
|
||||
- `--include-outputs`
|
||||
Also include the existing output paths of [store derivation]s,
|
||||
and their closures.
|
||||
|
||||
[references]: @docroot@/glossary.md#gloss-reference
|
||||
This query can be used to implement various kinds of deployment. A
|
||||
*source deployment* is obtained by distributing the closure of a
|
||||
store derivation. A *binary deployment* is obtained by distributing
|
||||
the closure of an output path. A *cache deployment* (combined
|
||||
source/binary deployment, including binaries of build-time-only
|
||||
dependencies) is obtained by distributing the closure of a store
|
||||
derivation and specifying the option `--include-outputs`.
|
||||
|
||||
- `--referrers`\
|
||||
Prints the set of *referrers* of the store paths *paths*, that is,
|
||||
the store paths currently existing in the Nix store that refer to
|
||||
one of *paths*. Note that contrary to the references, the set of
|
||||
referrers is not constant; it can change as store paths are added or
|
||||
removed.
|
||||
- `--references`
|
||||
|
||||
- `--referrers-closure`\
|
||||
Prints the closure of the set of store paths *paths* under the
|
||||
referrers relation; that is, all store paths that directly or
|
||||
indirectly refer to one of *paths*. These are all the path currently
|
||||
in the Nix store that are dependent on *paths*.
|
||||
Prints the set of [references] of the store paths
|
||||
*paths*, that is, their immediate dependencies. (For *all*
|
||||
dependencies, use `--requisites`.)
|
||||
|
||||
- `--deriver`; `-d`\
|
||||
Prints the [deriver] that was used to build the store paths *paths*. If
|
||||
the path has no deriver (e.g., if it is a source file), or if the
|
||||
deriver is not known (e.g., in the case of a binary-only
|
||||
deployment), the string `unknown-deriver` is printed.
|
||||
The returned deriver is not guaranteed to exist in the local store, for
|
||||
example when *paths* were substituted from a binary cache.
|
||||
Use `--valid-derivers` instead to obtain valid paths only.
|
||||
[references]: @docroot@/glossary.md#gloss-reference
|
||||
|
||||
[deriver]: @docroot@/glossary.md#gloss-deriver
|
||||
- `--referrers`
|
||||
|
||||
- `--valid-derivers`\
|
||||
Prints a set of derivation files (`.drv`) which are supposed produce
|
||||
said paths when realized. Might print nothing, for example for source paths
|
||||
or paths subsituted from a binary cache.
|
||||
Prints the set of *referrers* of the store paths *paths*, that is,
|
||||
the store paths currently existing in the Nix store that refer to
|
||||
one of *paths*. Note that contrary to the references, the set of
|
||||
referrers is not constant; it can change as store paths are added or
|
||||
removed.
|
||||
|
||||
- `--graph`\
|
||||
Prints the references graph of the store paths *paths* in the format
|
||||
of the `dot` tool of AT\&T's [Graphviz
|
||||
package](http://www.graphviz.org/). This can be used to visualise
|
||||
dependency graphs. To obtain a build-time dependency graph, apply
|
||||
this to a store derivation. To obtain a runtime dependency graph,
|
||||
apply it to an output path.
|
||||
- `--referrers-closure`
|
||||
|
||||
- `--tree`\
|
||||
Prints the references graph of the store paths *paths* as a nested
|
||||
ASCII tree. References are ordered by descending closure size; this
|
||||
tends to flatten the tree, making it more readable. The query only
|
||||
recurses into a store path when it is first encountered; this
|
||||
prevents a blowup of the tree representation of the graph.
|
||||
Prints the closure of the set of store paths *paths* under the
|
||||
referrers relation; that is, all store paths that directly or
|
||||
indirectly refer to one of *paths*. These are all the path currently
|
||||
in the Nix store that are dependent on *paths*.
|
||||
|
||||
- `--graphml`\
|
||||
Prints the references graph of the store paths *paths* in the
|
||||
[GraphML](http://graphml.graphdrawing.org/) file format. This can be
|
||||
used to visualise dependency graphs. To obtain a build-time
|
||||
dependency graph, apply this to a [store derivation]. To obtain a
|
||||
runtime dependency graph, apply it to an output path.
|
||||
- `--deriver` / `-d`
|
||||
|
||||
- `--binding` *name*; `-b` *name*\
|
||||
Prints the value of the attribute *name* (i.e., environment
|
||||
variable) of the [store derivation]s *paths*. It is an error for a
|
||||
derivation to not have the specified attribute.
|
||||
Prints the [deriver] that was used to build the store paths *paths*. If
|
||||
the path has no deriver (e.g., if it is a source file), or if the
|
||||
deriver is not known (e.g., in the case of a binary-only
|
||||
deployment), the string `unknown-deriver` is printed.
|
||||
The returned deriver is not guaranteed to exist in the local store, for
|
||||
example when *paths* were substituted from a binary cache.
|
||||
Use `--valid-derivers` instead to obtain valid paths only.
|
||||
|
||||
- `--hash`\
|
||||
Prints the SHA-256 hash of the contents of the store paths *paths*
|
||||
(that is, the hash of the output of `nix-store --dump` on the given
|
||||
paths). Since the hash is stored in the Nix database, this is a fast
|
||||
operation.
|
||||
[deriver]: @docroot@/glossary.md#gloss-deriver
|
||||
|
||||
- `--size`\
|
||||
Prints the size in bytes of the contents of the store paths *paths*
|
||||
— to be precise, the size of the output of `nix-store --dump` on
|
||||
the given paths. Note that the actual disk space required by the
|
||||
store paths may be higher, especially on filesystems with large
|
||||
cluster sizes.
|
||||
- `--valid-derivers`
|
||||
|
||||
- `--roots`\
|
||||
Prints the garbage collector roots that point, directly or
|
||||
indirectly, at the store paths *paths*.
|
||||
Prints a set of derivation files (`.drv`) which are supposed produce
|
||||
said paths when realized. Might print nothing, for example for source paths
|
||||
or paths subsituted from a binary cache.
|
||||
|
||||
- `--graph`
|
||||
|
||||
Prints the references graph of the store paths *paths* in the format
|
||||
of the `dot` tool of AT\&T's [Graphviz
|
||||
package](http://www.graphviz.org/). This can be used to visualise
|
||||
dependency graphs. To obtain a build-time dependency graph, apply
|
||||
this to a store derivation. To obtain a runtime dependency graph,
|
||||
apply it to an output path.
|
||||
|
||||
- `--tree`
|
||||
|
||||
Prints the references graph of the store paths *paths* as a nested
|
||||
ASCII tree. References are ordered by descending closure size; this
|
||||
tends to flatten the tree, making it more readable. The query only
|
||||
recurses into a store path when it is first encountered; this
|
||||
prevents a blowup of the tree representation of the graph.
|
||||
|
||||
- `--graphml`
|
||||
|
||||
Prints the references graph of the store paths *paths* in the
|
||||
[GraphML](http://graphml.graphdrawing.org/) file format. This can be
|
||||
used to visualise dependency graphs. To obtain a build-time
|
||||
dependency graph, apply this to a [store derivation]. To obtain a
|
||||
runtime dependency graph, apply it to an output path.
|
||||
|
||||
- `--binding` *name* / `-b` *name*
|
||||
|
||||
Prints the value of the attribute *name* (i.e., environment
|
||||
variable) of the [store derivation]s *paths*. It is an error for a
|
||||
derivation to not have the specified attribute.
|
||||
|
||||
- `--hash`
|
||||
|
||||
Prints the SHA-256 hash of the contents of the store paths *paths*
|
||||
(that is, the hash of the output of `nix-store --dump` on the given
|
||||
paths). Since the hash is stored in the Nix database, this is a fast
|
||||
operation.
|
||||
|
||||
- `--size`
|
||||
|
||||
Prints the size in bytes of the contents of the store paths *paths*
|
||||
— to be precise, the size of the output of `nix-store --dump` on
|
||||
the given paths. Note that the actual disk space required by the
|
||||
store paths may be higher, especially on filesystems with large
|
||||
cluster sizes.
|
||||
|
||||
- `--roots`
|
||||
|
||||
Prints the garbage collector roots that point, directly or
|
||||
indirectly, at the store paths *paths*.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
|
||||
@ -42,23 +42,26 @@ For non-derivation arguments, the argument itself is printed.
|
||||
|
||||
# Options
|
||||
|
||||
- `--dry-run`\
|
||||
Print on standard error a description of what packages would be
|
||||
built or downloaded, without actually performing the operation.
|
||||
- `--dry-run`
|
||||
|
||||
- `--ignore-unknown`\
|
||||
If a non-derivation path does not have a substitute, then silently
|
||||
ignore it.
|
||||
Print on standard error a description of what packages would be
|
||||
built or downloaded, without actually performing the operation.
|
||||
|
||||
- `--check`\
|
||||
This option allows you to check whether a derivation is
|
||||
deterministic. It rebuilds the specified derivation and checks
|
||||
whether the result is bitwise-identical with the existing outputs,
|
||||
printing an error if that’s not the case. The outputs of the
|
||||
specified derivation must already exist. When used with `-K`, if an
|
||||
output path is not identical to the corresponding output from the
|
||||
previous build, the new output path is left in
|
||||
`/nix/store/name.check.`
|
||||
- `--ignore-unknown`
|
||||
|
||||
If a non-derivation path does not have a substitute, then silently
|
||||
ignore it.
|
||||
|
||||
- `--check`
|
||||
|
||||
This option allows you to check whether a derivation is
|
||||
deterministic. It rebuilds the specified derivation and checks
|
||||
whether the result is bitwise-identical with the existing outputs,
|
||||
printing an error if that’s not the case. The outputs of the
|
||||
specified derivation must already exist. When used with `-K`, if an
|
||||
output path is not identical to the corresponding output from the
|
||||
previous build, the new output path is left in
|
||||
`/nix/store/name.check.`
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
|
||||
@ -14,10 +14,11 @@ access to a restricted ssh user.
|
||||
|
||||
The following flags are available:
|
||||
|
||||
- `--write`\
|
||||
Allow the connected client to request the realization of
|
||||
derivations. In effect, this can be used to make the host act as a
|
||||
remote builder.
|
||||
- `--write`
|
||||
|
||||
Allow the connected client to request the realization of
|
||||
derivations. In effect, this can be used to make the host act as a
|
||||
remote builder.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
|
||||
@ -16,18 +16,20 @@ being modified by non-Nix tools, or of bugs in Nix itself.
|
||||
|
||||
This operation has the following options:
|
||||
|
||||
- `--check-contents`\
|
||||
Checks that the contents of every valid store path has not been
|
||||
altered by computing a SHA-256 hash of the contents and comparing it
|
||||
with the hash stored in the Nix database at build time. Paths that
|
||||
have been modified are printed out. For large stores,
|
||||
`--check-contents` is obviously quite slow.
|
||||
- `--check-contents`
|
||||
|
||||
- `--repair`\
|
||||
If any valid path is missing from the store, or (if
|
||||
`--check-contents` is given) the contents of a valid path has been
|
||||
modified, then try to repair the path by redownloading it. See
|
||||
`nix-store --repair-path` for details.
|
||||
Checks that the contents of every valid store path has not been
|
||||
altered by computing a SHA-256 hash of the contents and comparing it
|
||||
with the hash stored in the Nix database at build time. Paths that
|
||||
have been modified are printed out. For large stores,
|
||||
`--check-contents` is obviously quite slow.
|
||||
|
||||
- `--repair`
|
||||
|
||||
If any valid path is missing from the store, or (if
|
||||
`--check-contents` is given) the contents of a valid path has been
|
||||
modified, then try to repair the path by redownloading it. See
|
||||
`nix-store --repair-path` for details.
|
||||
|
||||
{{#include ./opt-common.md}}
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user