forked from lix-project/lix
Maximilian Bosch
6ccfdb79c7
The new error-format is pretty nice from a UX point-of-view, however
it's fairly hard to parse the output e.g. for editor plugins such as
vim-ale[1] that use `nix-instantiate --parse` to determine syntax errors in
Nix expression files.
This patch extends the `internal-json` logger by adding the fields
`line`, `column` and `file` to easily locate an error in a file and the
field `raw_msg` which contains the error-message itself without
code-lines and additional helpers.
An exemplary output may look like this:
```
[nix-shell]$ ./inst/bin/nix-instantiate ~/test.nix --log-format minimal
{"action":"msg","column":1,"file":"/home/ma27/test.nix","level":0,"line":4,"raw_msg":"syntax error, unexpected IF, expecting $end","msg":"<full error-msg with code-lines etc>"}
```
[1] https://github.com/dense-analysis/ale
413 lines
14 KiB
XML
413 lines
14 KiB
XML
<chapter xmlns="http://docbook.org/ns/docbook" xml:id="sec-common-options">
|
|
|
|
<title>Common Options</title>
|
|
|
|
|
|
<para>Most Nix commands accept the following command-line options:</para>
|
|
|
|
<variablelist xml:id="opt-common">
|
|
|
|
<varlistentry><term><option>--help</option></term>
|
|
|
|
<listitem><para>Prints out a summary of the command syntax and
|
|
exits.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry><term><option>--version</option></term>
|
|
|
|
<listitem><para>Prints out the Nix version number on standard output
|
|
and exits.</para></listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry><term><option>--verbose</option> / <option>-v</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>This option may be specified repeatedly. Currently, the
|
|
following verbosity levels exist:</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry><term>0</term>
|
|
<listitem><para>“Errors only”: only print messages
|
|
explaining why the Nix invocation failed.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>1</term>
|
|
<listitem><para>“Informational”: print
|
|
<emphasis>useful</emphasis> messages about what Nix is doing.
|
|
This is the default.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>2</term>
|
|
<listitem><para>“Talkative”: print more informational
|
|
messages.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>3</term>
|
|
<listitem><para>“Chatty”: print even more
|
|
informational messages.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>4</term>
|
|
<listitem><para>“Debug”: print debug
|
|
information.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>5</term>
|
|
<listitem><para>“Vomit”: print vast amounts of debug
|
|
information.</para></listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry><term><option>--quiet</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>Decreases the level of verbosity of diagnostic messages
|
|
printed on standard error. This is the inverse option to
|
|
<option>-v</option> / <option>--verbose</option>.
|
|
</para>
|
|
|
|
<para>This option may be specified repeatedly. See the previous
|
|
verbosity levels list.</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry xml:id="opt-log-format"><term><option>--log-format</option> <replaceable>format</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>This option can be used to change the output of the log format, with
|
|
<replaceable>format</replaceable> being one of:</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry><term>raw</term>
|
|
<listitem><para>This is the raw format, as outputted by nix-build.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>internal-json</term>
|
|
<listitem>
|
|
<para>Outputs the logs in a structured manner.</para>
|
|
<warning>
|
|
<para>
|
|
While the schema itself is relatively stable, the format of the error-messages (namely of the <literal>msg</literal>-field) can change between several releases.
|
|
</para>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>bar</term>
|
|
<listitem><para>Only display a progress bar during the builds.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term>bar-with-logs</term>
|
|
<listitem><para>Display the raw logs, with the progress bar at the bottom.</para></listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><option>--no-build-output</option> / <option>-Q</option></term>
|
|
|
|
<listitem><para>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
|
|
<filename><replaceable>prefix</replaceable>/nix/var/log/nix</filename>.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry xml:id="opt-max-jobs"><term><option>--max-jobs</option> / <option>-j</option>
|
|
<replaceable>number</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>Sets the maximum number of build jobs that Nix will
|
|
perform in parallel to the specified number. Specify
|
|
<literal>auto</literal> to use the number of CPUs in the system.
|
|
The default is specified by the <link
|
|
linkend='conf-max-jobs'><literal>max-jobs</literal></link>
|
|
configuration setting, which itself defaults to
|
|
<literal>1</literal>. A higher value is useful on SMP systems or to
|
|
exploit I/O latency.</para>
|
|
|
|
<para> Setting it to <literal>0</literal> disallows building on the local
|
|
machine, which is useful when you want builds to happen only on remote
|
|
builders.</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry xml:id="opt-cores"><term><option>--cores</option></term>
|
|
|
|
<listitem><para>Sets the value of the <envar>NIX_BUILD_CORES</envar>
|
|
environment variable in the invocation of builders. Builders can
|
|
use this variable at their discretion to control the maximum amount
|
|
of parallelism. For instance, in Nixpkgs, if the derivation
|
|
attribute <varname>enableParallelBuilding</varname> is set to
|
|
<literal>true</literal>, the builder passes the
|
|
<option>-j<replaceable>N</replaceable></option> flag to GNU Make.
|
|
It defaults to the value of the <link
|
|
linkend='conf-cores'><literal>cores</literal></link>
|
|
configuration setting, if set, or <literal>1</literal> otherwise.
|
|
The value <literal>0</literal> means that the builder should use all
|
|
available CPU cores in the system.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry xml:id="opt-max-silent-time"><term><option>--max-silent-time</option></term>
|
|
|
|
<listitem><para>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 <link
|
|
linkend='conf-max-silent-time'><literal>max-silent-time</literal></link>
|
|
configuration setting. <literal>0</literal> means no
|
|
time-out.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="opt-timeout"><term><option>--timeout</option></term>
|
|
|
|
<listitem><para>Sets the maximum number of seconds that a builder
|
|
can run. The default is specified by the <link
|
|
linkend='conf-timeout'><literal>timeout</literal></link>
|
|
configuration setting. <literal>0</literal> means no
|
|
timeout.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><option>--keep-going</option> / <option>-k</option></term>
|
|
|
|
<listitem><para>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).</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry><term><option>--keep-failed</option> / <option>-K</option></term>
|
|
|
|
<listitem><para>Specifies that in case of a build failure, the
|
|
temporary directory (usually in <filename>/tmp</filename>) in which
|
|
the build takes place should not be deleted. The path of the build
|
|
directory is printed as an informational message.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry><term><option>--fallback</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>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).</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry><term><option>--no-build-hook</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>Disables the build hook mechanism. This allows to ignore remote
|
|
builders if they are setup on the machine.</para>
|
|
|
|
<para>It's useful in cases where the bandwidth between the client and the
|
|
remote builder is too low. In that case it can take more time to upload the
|
|
sources to the remote builder and fetch back the result than to do the
|
|
computation locally.</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry><term><option>--readonly-mode</option></term>
|
|
|
|
<listitem><para>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.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry><term><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term>
|
|
|
|
<listitem><para>This option is accepted by
|
|
<command>nix-env</command>, <command>nix-instantiate</command>,
|
|
<command>nix-shell</command> and <command>nix-build</command>.
|
|
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 <link linkend='ss-functions'>default value</link>
|
|
(e.g., <literal>{ <replaceable>argName</replaceable> ?
|
|
<replaceable>defaultValue</replaceable> }:
|
|
<replaceable>...</replaceable></literal>). With
|
|
<option>--arg</option>, 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 <replaceable>name</replaceable>, it will call it with value
|
|
<replaceable>value</replaceable>.</para>
|
|
|
|
<para>For instance, the top-level <literal>default.nix</literal> in
|
|
Nixpkgs is actually a function:
|
|
|
|
<programlisting>
|
|
{ # The system (e.g., `i686-linux') for which to build the packages.
|
|
system ? builtins.currentSystem
|
|
<replaceable>...</replaceable>
|
|
}: <replaceable>...</replaceable></programlisting>
|
|
|
|
So if you call this Nix expression (e.g., when you do
|
|
<literal>nix-env -i <replaceable>pkgname</replaceable></literal>),
|
|
the function will be called automatically using the value <link
|
|
linkend='builtin-currentSystem'><literal>builtins.currentSystem</literal></link>
|
|
for the <literal>system</literal> argument. You can override this
|
|
using <option>--arg</option>, e.g., <literal>nix-env -i
|
|
<replaceable>pkgname</replaceable> --arg system
|
|
\"i686-freebsd\"</literal>. (Note that since the argument is a Nix
|
|
string literal, you have to escape the quotes.)</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry><term><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term>
|
|
|
|
<listitem><para>This option is like <option>--arg</option>, only the
|
|
value is not a Nix expression but a string. So instead of
|
|
<literal>--arg system \"i686-linux\"</literal> (the outer quotes are
|
|
to keep the shell happy) you can say <literal>--argstr system
|
|
i686-linux</literal>.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry xml:id="opt-attr"><term><option>--attr</option> / <option>-A</option>
|
|
<replaceable>attrPath</replaceable></term>
|
|
|
|
<listitem><para>Select an attribute from the top-level Nix
|
|
expression being evaluated. (<command>nix-env</command>,
|
|
<command>nix-instantiate</command>, <command>nix-build</command> and
|
|
<command>nix-shell</command> only.) The <emphasis>attribute
|
|
path</emphasis> <replaceable>attrPath</replaceable> is a sequence of
|
|
attribute names separated by dots. For instance, given a top-level
|
|
Nix expression <replaceable>e</replaceable>, the attribute path
|
|
<literal>xorg.xorgserver</literal> would cause the expression
|
|
<literal><replaceable>e</replaceable>.xorg.xorgserver</literal> to
|
|
be used. See <link
|
|
linkend='refsec-nix-env-install-examples'><command>nix-env
|
|
--install</command></link> for some concrete examples.</para>
|
|
|
|
<para>In addition to attribute names, you can also specify array
|
|
indices. For instance, the attribute path
|
|
<literal>foo.3.bar</literal> selects the <literal>bar</literal>
|
|
attribute of the fourth element of the array in the
|
|
<literal>foo</literal> attribute of the top-level
|
|
expression.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry><term><option>--expr</option> / <option>-E</option></term>
|
|
|
|
<listitem><para>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.
|
|
(<command>nix-instantiate</command>, <command>nix-build</command>
|
|
and <command>nix-shell</command> only.)</para>
|
|
|
|
<para>For <command>nix-shell</command>, 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
|
|
<emphasis>built</emphasis> packages ready for use, give your
|
|
expression to the <command>nix-shell -p</command> convenience flag
|
|
instead.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry xml:id="opt-I"><term><option>-I</option> <replaceable>path</replaceable></term>
|
|
|
|
<listitem><para>Add a path to the Nix expression search path. This
|
|
option may be given multiple times. See the <envar
|
|
linkend="env-NIX_PATH">NIX_PATH</envar> environment variable for
|
|
information on the semantics of the Nix search path. Paths added
|
|
through <option>-I</option> take precedence over
|
|
<envar>NIX_PATH</envar>.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry><term><option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term>
|
|
|
|
<listitem><para>Set the Nix configuration option
|
|
<replaceable>name</replaceable> to <replaceable>value</replaceable>.
|
|
This overrides settings in the Nix configuration file (see
|
|
<citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry><term><option>--repair</option></term>
|
|
|
|
<listitem><para>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
|
|
<command>nix-store --repair-path</command>.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
</variablelist>
|
|
|
|
|
|
</chapter>
|