bbjubjub2494/lix
0
0
Fork 0
forked from lix-project/lix
Code Pull requests Activity
lix/doc/manual/src/command-ref/opt-common.md

220 lines
9 KiB
Markdown
Raw Normal View History

Reconvert
2020-07-23 08:44:54 +00:00
# Common Options
Most Nix commands accept the following command-line options:
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--help`\
Reconvert
2020-07-23 08:44:54 +00:00
Prints out a summary of the command syntax and exits.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--version`\
Reconvert
2020-07-23 08:44:54 +00:00
Prints out the Nix version number on standard output and exits.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--verbose` / `-v`\
Reconvert
2020-07-23 08:44:54 +00:00
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.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
Reconvert
2020-07-23 08:44:54 +00:00
This option may be specified repeatedly. Currently, the following
verbosity levels exist:
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- 0\
Reconvert
2020-07-23 08:44:54 +00:00
“Errors only”: only print messages explaining why the Nix
invocation failed.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- 1\
Reconvert
2020-07-23 08:44:54 +00:00
“Informational”: print *useful* messages about what Nix is
doing. This is the default.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- 2\
Reconvert
2020-07-23 08:44:54 +00:00
“Talkative”: print more informational messages.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- 3\
Reconvert
2020-07-23 08:44:54 +00:00
“Chatty”: print even more informational messages.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- 4\
Reconvert
2020-07-23 08:44:54 +00:00
“Debug”: print debug information.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- 5\
Reconvert
2020-07-23 08:44:54 +00:00
“Vomit”: print vast amounts of debug information.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--quiet`\
Reconvert
2020-07-23 08:44:54 +00:00
Decreases the level of verbosity of diagnostic messages printed on
standard error. This is the inverse option to `-v` / `--verbose`.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
Reconvert
2020-07-23 08:44:54 +00:00
This option may be specified repeatedly. See the previous verbosity
levels list.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--log-format` *format*\
Reconvert
2020-07-23 08:44:54 +00:00
This option can be used to change the output of the log format, with
<replaceable> -> <emphasis> Pandoc doesn't know <replaceable> so let's force it to be rendered as italics.
2020-07-23 12:28:05 +00:00
*format* being one of:
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- raw\
Reconvert
2020-07-23 08:44:54 +00:00
This is the raw format, as outputted by nix-build.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- internal-json\
Merge remote-tracking branch 'origin/master' into markdown
2020-08-31 12:24:26 +00:00
Outputs the logs in a structured manner.
> **Warning**
>
> While the schema itself is relatively stable, the format of
> the error-messages (namely of the `msg`-field) can change
> between releases.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- bar\
Reconvert
2020-07-23 08:44:54 +00:00
Only display a progress bar during the builds.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- bar-with-logs\
Reconvert
2020-07-23 08:44:54 +00:00
Display the raw logs, with the progress bar at the bottom.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--no-build-output` / `-Q`\
Reconvert
2020-07-23 08:44:54 +00:00
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`.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--max-jobs` / `-j` *number*\
Reconvert
2020-07-23 08:44:54 +00:00
Sets the maximum number of build jobs that Nix will perform in
parallel to the specified number. Specify `auto` to use the number
Fix internal links
2020-07-24 13:46:16 +00:00
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.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
Reconvert
2020-07-23 08:44:54 +00:00
Setting it to `0` disallows building on the local machine, which is
useful when you want builds to happen only on remote builders.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--cores`\
Fix internal links
2020-07-24 13:46:16 +00:00
Sets the value of the `NIX_BUILD_CORES` environment variable in
the invocation of builders. Builders can use this variable at
their discretion to control the maximum amount of parallelism. For
Reconvert
2020-07-23 08:44:54 +00:00
instance, in Nixpkgs, if the derivation attribute
`enableParallelBuilding` is set to `true`, the builder passes the
Fix internal links
2020-07-24 13:46:16 +00:00
`-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.
Reconvert
2020-07-23 08:44:54 +00:00
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--max-silent-time`\
Reconvert
2020-07-23 08:44:54 +00:00
Sets the maximum number of seconds that a builder can go without
Fix internal links
2020-07-24 13:46:16 +00:00
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.
Reconvert
2020-07-23 08:44:54 +00:00
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--timeout`\
Reconvert
2020-07-23 08:44:54 +00:00
Sets the maximum number of seconds that a builder can run. The
Fix internal links
2020-07-24 13:46:16 +00:00
default is specified by the `timeout` configuration setting. `0`
means no timeout.
Reconvert
2020-07-23 08:44:54 +00:00
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--keep-going` / `-k`\
Reconvert
2020-07-23 08:44:54 +00:00
Keep going in case of failed builds, to the greatest extent
possible. 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).
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--keep-failed` / `-K`\
Reconvert
2020-07-23 08:44:54 +00:00
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.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--fallback`\
Reconvert
2020-07-23 08:44:54 +00:00
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.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
Reconvert
2020-07-23 08:44:54 +00:00
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).
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--readonly-mode`\
Reconvert
2020-07-23 08:44:54 +00:00
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.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--arg` *name* *value*\
Fix internal links
2020-07-24 13:46:16 +00:00
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](../expressions/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*.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
Reconvert
2020-07-23 08:44:54 +00:00
For instance, the top-level `default.nix` in Nixpkgs is actually a
function:
Enable syntax highlighting
2020-07-31 13:43:25 +00:00
```nix
{ # The system (e.g., `i686-linux') for which to build the packages.
system ? builtins.currentSystem
...
}: ...
```
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
doc: De-emphasize nix-env without -A The manual uses `nix-env -i` without `-A` prominently, teaching a bad practice to newcomers.
2021-11-17 15:30:39 +00:00
So if you call this Nix expression (e.g., when you do `nix-env -iA
Fix internal links
2020-07-24 13:46:16 +00:00
pkgname`), the function will be called automatically using the
value [`builtins.currentSystem`](../expressions/builtins.md) for
the `system` argument. You can override this using `--arg`, e.g.,
doc: De-emphasize nix-env without -A The manual uses `nix-env -i` without `-A` prominently, teaching a bad practice to newcomers.
2021-11-17 15:30:39 +00:00
`nix-env -iA pkgname --arg system \"i686-freebsd\"`. (Note that
Fix internal links
2020-07-24 13:46:16 +00:00
since the argument is a Nix string literal, you have to escape the
quotes.)
Reconvert
2020-07-23 08:44:54 +00:00
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--argstr` *name* *value*\
Fix internal links
2020-07-24 13:46:16 +00:00
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`.
Reconvert
2020-07-23 08:44:54 +00:00
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--attr` / `-A` *attrPath*\
Reconvert
2020-07-23 08:44:54 +00:00
Select an attribute from the top-level Nix expression being
evaluated. (`nix-env`, `nix-instantiate`, `nix-build` and
Fix internal links
2020-07-24 13:46:16 +00:00
`nix-shell` only.) The *attribute path* *attrPath* is a sequence
of attribute names separated by dots. 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`](nix-env.md#operation---install) for some
concrete examples.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
Reconvert
2020-07-23 08:44:54 +00:00
In addition to attribute names, you can also specify array indices.
For instance, the attribute path `foo.3.bar` selects the `bar`
attribute of the fourth element of the array in the `foo` attribute
of the top-level expression.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--expr` / `-E`\
Reconvert
2020-07-23 08:44:54 +00:00
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.)
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
Reconvert
2020-07-23 08:44:54 +00:00
For `nix-shell`, this option is commonly used to give you a shell in
which you can build the packages returned by the expression. If you
want to get a shell which contain the *built* packages ready for
use, give your expression to the `nix-shell -p` convenience flag
instead.
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `-I` *path*\
Reconvert
2020-07-23 08:44:54 +00:00
Add a path to the Nix expression search path. This option may be
Get rid of footnotes Markdown doesn't support them.
2020-07-24 09:43:44 +00:00
given multiple times. See the `NIX_PATH` environment variable for
information on the semantics of the Nix search path. Paths added
through `-I` take precedence over `NIX_PATH`.
Reconvert
2020-07-23 08:44:54 +00:00
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--option` *name* *value*\
<replaceable> -> <emphasis> Pandoc doesn't know <replaceable> so let's force it to be rendered as italics.
2020-07-23 12:28:05 +00:00
Set the Nix configuration option *name* to *value*. This overrides
Reconvert
2020-07-23 08:44:54 +00:00
settings in the Nix configuration file (see nix.conf5).
Replace the trailing markdown spaces by a backslash They are equivalent according to <https://spec.commonmark.org/0.29/#hard-line-breaks>, and the trailing spaces tend to be a pain (because the make git complain, editors tend to want to remove them − the `.editorconfig` actually specifies that − etc..).
2021-04-23 12:30:42 +00:00
- `--repair`\
Reconvert
2020-07-23 08:44:54 +00:00
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`.
Copy permalink