Merge pull request #8932 from fricklerhandwerk/formatting
dedent common options listing; one sentence per line
This commit is contained in:
John Ericson
GitHub
commit
216c66ddcf
1 changed files with 161 additions and 174 deletions
|
|
@ -2,56 +2,66 @@
|
||||||
|
|
||||||
Most Nix commands accept the following command-line options:
|
Most Nix commands accept the following command-line options:
|
||||||
|
|
||||||
- <span id="opt-help">[`--help`](#opt-help)</span>\
|
- <span id="opt-help">[`--help`](#opt-help)</span>
|
||||||
|
|
||||||
Prints out a summary of the command syntax and exits.
|
Prints out a summary of the command syntax and exits.
|
||||||
|
|
||||||
- <span id="opt-version">[`--version`](#opt-version)</span>\
|
- <span id="opt-version">[`--version`](#opt-version)</span>
|
||||||
|
|
||||||
Prints out the Nix version number on standard output and exits.
|
Prints out the Nix version number on standard output and exits.
|
||||||
|
|
||||||
- <span id="opt-verbose">[`--verbose`](#opt-verbose)</span> / `-v`\
|
- <span id="opt-verbose">[`--verbose`](#opt-verbose)</span> / `-v`
|
||||||
Increases the level of verbosity of diagnostic messages printed on
|
|
||||||
standard error. For each Nix operation, the information printed on
|
|
||||||
standard output is well-defined; any diagnostic information is
|
|
||||||
printed on standard error, never on standard output.
|
|
||||||
|
|
||||||
This option may be specified repeatedly. Currently, the following
|
Increases the level of verbosity of diagnostic messages printed on standard error.
|
||||||
verbosity levels exist:
|
For each Nix operation, the information printed on standard output is well-defined;
|
||||||
|
any diagnostic information is printed on standard error, never on standard output.
|
||||||
|
|
||||||
- 0\
|
This option may be specified repeatedly.
|
||||||
“Errors only”: only print messages explaining why the Nix
|
Currently, the following verbosity levels exist:
|
||||||
invocation failed.
|
|
||||||
|
|
||||||
- 1\
|
- `0` “Errors only”
|
||||||
“Informational”: print *useful* messages about what Nix is
|
|
||||||
doing. This is the default.
|
|
||||||
|
|
||||||
- 2\
|
Only print messages explaining why the Nix invocation failed.
|
||||||
“Talkative”: print more informational messages.
|
|
||||||
|
|
||||||
- 3\
|
- `1` “Informational”
|
||||||
“Chatty”: print even more informational messages.
|
|
||||||
|
|
||||||
- 4\
|
Print *useful* messages about what Nix is doing.
|
||||||
“Debug”: print debug information.
|
This is the default.
|
||||||
|
|
||||||
- 5\
|
- `2` “Talkative”
|
||||||
“Vomit”: print vast amounts of debug information.
|
|
||||||
|
|
||||||
- <span id="opt-quiet">[`--quiet`](#opt-quiet)</span>\
|
Print more informational messages.
|
||||||
Decreases the level of verbosity of diagnostic messages printed on
|
|
||||||
standard error. This is the inverse option to `-v` / `--verbose`.
|
|
||||||
|
|
||||||
This option may be specified repeatedly. See the previous verbosity
|
- `3` “Chatty”
|
||||||
levels list.
|
|
||||||
|
|
||||||
- <span id="opt-log-format">[`--log-format`](#opt-log-format)</span> *format*\
|
Print even more informational messages.
|
||||||
This option can be used to change the output of the log format, with
|
|
||||||
*format* being one of:
|
- `4` “Debug”
|
||||||
|
|
||||||
|
Print debug information.
|
||||||
|
|
||||||
|
- `5` “Vomit”
|
||||||
|
|
||||||
|
Print vast amounts of debug information.
|
||||||
|
|
||||||
|
- <span id="opt-quiet">[`--quiet`](#opt-quiet)</span>
|
||||||
|
|
||||||
|
Decreases the level of verbosity of diagnostic messages printed on standard error.
|
||||||
|
This is the inverse option to `-v` / `--verbose`.
|
||||||
|
|
||||||
|
This option may be specified repeatedly.
|
||||||
|
See the previous verbosity levels list.
|
||||||
|
|
||||||
|
- <span id="opt-log-format">[`--log-format`](#opt-log-format)</span> *format*
|
||||||
|
|
||||||
|
This option can be used to change the output of the log format, with *format* being one of:
|
||||||
|
|
||||||
|
- `raw`
|
||||||
|
|
||||||
- raw\
|
|
||||||
This is the raw format, as outputted by nix-build.
|
This is the raw format, as outputted by nix-build.
|
||||||
|
|
||||||
- internal-json\
|
- `internal-json`
|
||||||
|
|
||||||
Outputs the logs in a structured manner.
|
Outputs the logs in a structured manner.
|
||||||
|
|
||||||
> **Warning**
|
> **Warning**
|
||||||
|
|
@ -60,100 +70,85 @@ Most Nix commands accept the following command-line options:
|
||||||
> the error-messages (namely of the `msg`-field) can change
|
> the error-messages (namely of the `msg`-field) can change
|
||||||
> between releases.
|
> between releases.
|
||||||
|
|
||||||
- bar\
|
- `bar`
|
||||||
|
|
||||||
Only display a progress bar during the builds.
|
Only display a progress bar during the builds.
|
||||||
|
|
||||||
- bar-with-logs\
|
- `bar-with-logs`
|
||||||
|
|
||||||
Display the raw logs, with the progress bar at the bottom.
|
Display the raw logs, with the progress bar at the bottom.
|
||||||
|
|
||||||
- <span id="opt-no-build-output">[`--no-build-output`](#opt-no-build-output)</span> / `-Q`\
|
- <span id="opt-no-build-output">[`--no-build-output`](#opt-no-build-output)</span> / `-Q`
|
||||||
By default, output written by builders to standard output and
|
|
||||||
standard error is echoed to the Nix command's standard error. This
|
|
||||||
option suppresses this behaviour. Note that the builder's standard
|
|
||||||
output and error are always written to a log file in
|
|
||||||
`prefix/nix/var/log/nix`.
|
|
||||||
|
|
||||||
- <span id="opt-max-jobs">[`--max-jobs`](#opt-max-jobs)</span> / `-j` *number*\
|
By default, output written by builders to standard output and standard error is echoed to the Nix command's standard error.
|
||||||
Sets the maximum number of build jobs that Nix will perform in
|
This option suppresses this behaviour.
|
||||||
parallel to the specified number. Specify `auto` to use the number
|
Note that the builder's standard output and error are always written to a log file in `prefix/nix/var/log/nix`.
|
||||||
of CPUs in the system. The default is specified by the `max-jobs`
|
|
||||||
configuration setting, which itself defaults to `1`. A higher
|
|
||||||
value is useful on SMP systems or to exploit I/O latency.
|
|
||||||
|
|
||||||
Setting it to `0` disallows building on the local machine, which is
|
- <span id="opt-max-jobs">[`--max-jobs`](#opt-max-jobs)</span> / `-j` *number*
|
||||||
useful when you want builds to happen only on remote builders.
|
|
||||||
|
|
||||||
- <span id="opt-cores">[`--cores`](#opt-cores)</span>\
|
Sets the maximum number of build jobs that Nix will perform in parallel to the specified number.
|
||||||
Sets the value of the `NIX_BUILD_CORES` environment variable in
|
Specify `auto` to use the number of CPUs in the system.
|
||||||
the invocation of builders. Builders can use this variable at
|
The default is specified by the `max-jobs` configuration setting, which itself defaults to `1`.
|
||||||
their discretion to control the maximum amount of parallelism. For
|
A higher value is useful on SMP systems or to exploit I/O latency.
|
||||||
instance, in Nixpkgs, if the derivation attribute
|
|
||||||
`enableParallelBuilding` is set to `true`, the builder passes the
|
|
||||||
`-jN` flag to GNU Make. It defaults to the value of the `cores`
|
|
||||||
configuration setting, if set, or `1` otherwise. The value `0`
|
|
||||||
means that the builder should use all available CPU cores in the
|
|
||||||
system.
|
|
||||||
|
|
||||||
- <span id="opt-max-silent-time">[`--max-silent-time`](#opt-max-silent-time)</span>\
|
Setting it to `0` disallows building on the local machine, which is useful when you want builds to happen only on remote builders.
|
||||||
Sets the maximum number of seconds that a builder can go without
|
|
||||||
producing any data on standard output or standard error. The
|
|
||||||
default is specified by the `max-silent-time` configuration
|
|
||||||
setting. `0` means no time-out.
|
|
||||||
|
|
||||||
- <span id="opt-timeout">[`--timeout`](#opt-timeout)</span>\
|
- <span id="opt-cores">[`--cores`](#opt-cores)</span>
|
||||||
Sets the maximum number of seconds that a builder can run. The
|
|
||||||
default is specified by the `timeout` configuration setting. `0`
|
|
||||||
means no timeout.
|
|
||||||
|
|
||||||
- <span id="opt-keep-going">[`--keep-going`](#opt-keep-going)</span> / `-k`\
|
Sets the value of the `NIX_BUILD_CORES` environment variable in the invocation of builders.
|
||||||
Keep going in case of failed builds, to the greatest extent
|
Builders can use this variable at their discretion to control the maximum amount of parallelism.
|
||||||
possible. That is, if building an input of some derivation fails,
|
For instance, in Nixpkgs, if the derivation attribute `enableParallelBuilding` is set to `true`, the builder passes the `-jN` flag to GNU Make.
|
||||||
Nix will still build the other inputs, but not the derivation
|
It defaults to the value of the `cores` configuration setting, if set, or `1` otherwise.
|
||||||
itself. Without this option, Nix stops if any build fails (except
|
The value `0` means that the builder should use all available CPU cores in the system.
|
||||||
for builds of substitutes), possibly killing builds in progress (in
|
|
||||||
case of parallel or distributed builds).
|
|
||||||
|
|
||||||
- <span id="opt-keep-failed">[`--keep-failed`](#opt-keep-failed)</span> / `-K`\
|
- <span id="opt-max-silent-time">[`--max-silent-time`](#opt-max-silent-time)</span>
|
||||||
Specifies that in case of a build failure, the temporary directory
|
|
||||||
(usually in `/tmp`) in which the build takes place should not be
|
|
||||||
deleted. The path of the build directory is printed as an
|
|
||||||
informational message.
|
|
||||||
|
|
||||||
- <span id="opt-fallback">[`--fallback`](#opt-fallback)</span>\
|
Sets the maximum number of seconds that a builder can go without producing any data on standard output or standard error.
|
||||||
Whenever Nix attempts to build a derivation for which substitutes
|
The default is specified by the `max-silent-time` configuration setting.
|
||||||
are known for each output path, but realising the output paths
|
`0` means no time-out.
|
||||||
through the substitutes fails, fall back on building the derivation.
|
|
||||||
|
|
||||||
The most common scenario in which this is useful is when we have
|
- <span id="opt-timeout">[`--timeout`](#opt-timeout)</span>
|
||||||
registered substitutes in order to perform binary distribution from,
|
|
||||||
say, a network repository. If the repository is down, the
|
|
||||||
realisation of the derivation will fail. When this option is
|
|
||||||
specified, Nix will build the derivation instead. Thus, installation
|
|
||||||
from binaries falls back on installation from source. This option is
|
|
||||||
not the default since it is generally not desirable for a transient
|
|
||||||
failure in obtaining the substitutes to lead to a full build from
|
|
||||||
source (with the related consumption of resources).
|
|
||||||
|
|
||||||
- <span id="opt-readonly-mode">[`--readonly-mode`](#opt-readonly-mode)</span>\
|
Sets the maximum number of seconds that a builder can run.
|
||||||
When this option is used, no attempt is made to open the Nix
|
The default is specified by the `timeout` configuration setting.
|
||||||
database. Most Nix operations do need database access, so those
|
`0` means no timeout.
|
||||||
operations will fail.
|
|
||||||
|
|
||||||
- <span id="opt-arg">[`--arg`](#opt-arg)</span> *name* *value*\
|
- <span id="opt-keep-going">[`--keep-going`](#opt-keep-going)</span> / `-k`
|
||||||
This option is accepted by `nix-env`, `nix-instantiate`,
|
|
||||||
`nix-shell` and `nix-build`. When evaluating Nix expressions, the
|
|
||||||
expression evaluator will automatically try to call functions that
|
|
||||||
it encounters. It can automatically call functions for which every
|
|
||||||
argument has a [default
|
|
||||||
value](@docroot@/language/constructs.md#functions) (e.g.,
|
|
||||||
`{ argName ? defaultValue }: ...`). With `--arg`, you can also
|
|
||||||
call functions that have arguments without a default value (or
|
|
||||||
override a default value). That is, if the evaluator encounters a
|
|
||||||
function with an argument named *name*, it will call it with value
|
|
||||||
*value*.
|
|
||||||
|
|
||||||
For instance, the top-level `default.nix` in Nixpkgs is actually a
|
Keep going in case of failed builds, to the greatest extent possible.
|
||||||
function:
|
That is, if building an input of some derivation fails, Nix will still build the other inputs, but not the derivation itself.
|
||||||
|
Without this option, Nix stops if any build fails (except for builds of substitutes), possibly killing builds in progress (in case of parallel or distributed builds).
|
||||||
|
|
||||||
|
- <span id="opt-keep-failed">[`--keep-failed`](#opt-keep-failed)</span> / `-K`
|
||||||
|
|
||||||
|
Specifies that in case of a build failure, the temporary directory (usually in `/tmp`) in which the build takes place should not be deleted.
|
||||||
|
The path of the build directory is printed as an informational message.
|
||||||
|
|
||||||
|
- <span id="opt-fallback">[`--fallback`](#opt-fallback)</span>
|
||||||
|
|
||||||
|
Whenever Nix attempts to build a derivation for which substitutes are known for each output path, but realising the output paths through the substitutes fails, fall back on building the derivation.
|
||||||
|
|
||||||
|
The most common scenario in which this is useful is when we have registered substitutes in order to perform binary distribution from, say, a network repository.
|
||||||
|
If the repository is down, the realisation of the derivation will fail.
|
||||||
|
When this option is specified, Nix will build the derivation instead.
|
||||||
|
Thus, installation from binaries falls back on installation from source.
|
||||||
|
This option is not the default since it is generally not desirable for a transient failure in obtaining the substitutes to lead to a full build from source (with the related consumption of resources).
|
||||||
|
|
||||||
|
- <span id="opt-readonly-mode">[`--readonly-mode`](#opt-readonly-mode)</span>
|
||||||
|
|
||||||
|
When this option is used, no attempt is made to open the Nix database.
|
||||||
|
Most Nix operations do need database access, so those operations will fail.
|
||||||
|
|
||||||
|
- <span id="opt-arg">[`--arg`](#opt-arg)</span> *name* *value*
|
||||||
|
|
||||||
|
This option is accepted by `nix-env`, `nix-instantiate`, `nix-shell` and `nix-build`.
|
||||||
|
When evaluating Nix expressions, the expression evaluator will automatically try to call functions that it encounters.
|
||||||
|
It can automatically call functions for which every argument has a [default value](@docroot@/language/constructs.md#functions) (e.g., `{ argName ? defaultValue }: ...`).
|
||||||
|
|
||||||
|
With `--arg`, you can also call functions that have arguments without a default value (or override a default value).
|
||||||
|
That is, if the evaluator encounters a function with an argument named *name*, it will call it with value *value*.
|
||||||
|
|
||||||
|
For instance, the top-level `default.nix` in Nixpkgs is actually a function:
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
{ # The system (e.g., `i686-linux') for which to build the packages.
|
{ # The system (e.g., `i686-linux') for which to build the packages.
|
||||||
|
|
@ -162,57 +157,49 @@ Most Nix commands accept the following command-line options:
|
||||||
}: ...
|
}: ...
|
||||||
```
|
```
|
||||||
|
|
||||||
So if you call this Nix expression (e.g., when you do `nix-env --install --attr
|
So if you call this Nix expression (e.g., when you do `nix-env --install --attr pkgname`), the function will be called automatically using the value [`builtins.currentSystem`](@docroot@/language/builtins.md) for the `system` argument.
|
||||||
pkgname`), the function will be called automatically using the
|
You can override this using `--arg`, e.g., `nix-env --install --attr pkgname --arg system \"i686-freebsd\"`.
|
||||||
value [`builtins.currentSystem`](@docroot@/language/builtins.md) for
|
(Note that since the argument is a Nix string literal, you have to escape the quotes.)
|
||||||
the `system` argument. You can override this using `--arg`, e.g.,
|
|
||||||
`nix-env --install --attr pkgname --arg system \"i686-freebsd\"`. (Note that
|
|
||||||
since the argument is a Nix string literal, you have to escape the
|
|
||||||
quotes.)
|
|
||||||
|
|
||||||
- <span id="opt-argstr">[`--argstr`](#opt-argstr)</span> *name* *value*\
|
- <span id="opt-argstr">[`--argstr`](#opt-argstr)</span> *name* *value*
|
||||||
This option is like `--arg`, only the value is not a Nix
|
|
||||||
expression but a string. So instead of `--arg system
|
|
||||||
\"i686-linux\"` (the outer quotes are to keep the shell happy) you
|
|
||||||
can say `--argstr system i686-linux`.
|
|
||||||
|
|
||||||
- <span id="opt-attr">[`--attr`](#opt-attr)</span> / `-A` *attrPath*\
|
This option is like `--arg`, only the value is not a Nix expression but a string.
|
||||||
Select an attribute from the top-level Nix expression being
|
So instead of `--arg system \"i686-linux\"` (the outer quotes are to keep the shell happy) you can say `--argstr system i686-linux`.
|
||||||
evaluated. (`nix-env`, `nix-instantiate`, `nix-build` and
|
|
||||||
`nix-shell` only.) The *attribute path* *attrPath* is a sequence
|
- <span id="opt-attr">[`--attr`](#opt-attr)</span> / `-A` *attrPath*
|
||||||
of attribute names separated by dots. For instance, given a
|
|
||||||
top-level Nix expression *e*, the attribute path `xorg.xorgserver`
|
Select an attribute from the top-level Nix expression being evaluated.
|
||||||
would cause the expression `e.xorg.xorgserver` to be used. See
|
(`nix-env`, `nix-instantiate`, `nix-build` and `nix-shell` only.)
|
||||||
[`nix-env --install`](@docroot@/command-ref/nix-env/install.md) for some
|
The *attribute path* *attrPath* is a sequence of attribute names separated by dots.
|
||||||
concrete examples.
|
For instance, given a top-level Nix expression *e*, the attribute path `xorg.xorgserver` would cause the expression `e.xorg.xorgserver` to be used.
|
||||||
|
See [`nix-env --install`](@docroot@/command-ref/nix-env/install.md) for some concrete examples.
|
||||||
|
|
||||||
In addition to attribute names, you can also specify array indices.
|
In addition to attribute names, you can also specify array indices.
|
||||||
For instance, the attribute path `foo.3.bar` selects the `bar`
|
For instance, the attribute path `foo.3.bar` selects the `bar`
|
||||||
attribute of the fourth element of the array in the `foo` attribute
|
attribute of the fourth element of the array in the `foo` attribute
|
||||||
of the top-level expression.
|
of the top-level expression.
|
||||||
|
|
||||||
- <span id="opt-expr">[`--expr`](#opt-expr)</span> / `-E`\
|
- <span id="opt-expr">[`--expr`](#opt-expr)</span> / `-E`
|
||||||
Interpret the command line arguments as a list of Nix expressions to
|
|
||||||
be parsed and evaluated, rather than as a list of file names of Nix
|
|
||||||
expressions. (`nix-instantiate`, `nix-build` and `nix-shell` only.)
|
|
||||||
|
|
||||||
For `nix-shell`, this option is commonly used to give you a shell in
|
Interpret the command line arguments as a list of Nix expressions to be parsed and evaluated, rather than as a list of file names of Nix expressions.
|
||||||
which you can build the packages returned by the expression. If you
|
(`nix-instantiate`, `nix-build` and `nix-shell` only.)
|
||||||
want to get a shell which contain the *built* packages ready for
|
|
||||||
use, give your expression to the `nix-shell --packages ` convenience flag
|
For `nix-shell`, this option is commonly used to give you a shell in which you can build the packages returned by the expression.
|
||||||
instead.
|
If you want to get a shell which contain the *built* packages ready for use, give your expression to the `nix-shell --packages ` convenience flag instead.
|
||||||
|
|
||||||
|
- <span id="opt-I">[`-I`](#opt-I)</span> *path*
|
||||||
|
|
||||||
- <span id="opt-I">[`-I`](#opt-I)</span> *path*\
|
|
||||||
Add an entry to the [Nix expression search path](@docroot@/command-ref/conf-file.md#conf-nix-path).
|
Add an entry to the [Nix expression search path](@docroot@/command-ref/conf-file.md#conf-nix-path).
|
||||||
This option may be given multiple times.
|
This option may be given multiple times.
|
||||||
Paths added through `-I` take precedence over [`NIX_PATH`](@docroot@/command-ref/env-common.md#env-NIX_PATH).
|
Paths added through `-I` take precedence over [`NIX_PATH`](@docroot@/command-ref/env-common.md#env-NIX_PATH).
|
||||||
|
|
||||||
- <span id="opt-option">[`--option`](#opt-option)</span> *name* *value*\
|
- <span id="opt-option">[`--option`](#opt-option)</span> *name* *value*
|
||||||
Set the Nix configuration option *name* to *value*. This overrides
|
|
||||||
settings in the Nix configuration file (see nix.conf5).
|
|
||||||
|
|
||||||
- <span id="opt-repair">[`--repair`](#opt-repair)</span>\
|
Set the Nix configuration option *name* to *value*.
|
||||||
Fix corrupted or missing store paths by redownloading or rebuilding
|
This overrides settings in the Nix configuration file (see nix.conf5).
|
||||||
them. Note that this is slow because it requires computing a
|
|
||||||
cryptographic hash of the contents of every path in the closure of
|
- <span id="opt-repair">[`--repair`](#opt-repair)</span>
|
||||||
the build. Also note the warning under `nix-store --repair-path`.
|
|
||||||
|
Fix corrupted or missing store paths by redownloading or rebuilding them.
|
||||||
|
Note that this is slow because it requires computing a cryptographic hash of the contents of every path in the closure of the build.
|
||||||
|
Also note the warning under `nix-store --repair-path`.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue