* Documented common environment variables.
This commit is contained in:
Eelco Dolstra
parent
f982df3cd7
commit
ad3121a52d
8 changed files with 313 additions and 180 deletions
|
|
@ -1,188 +1,209 @@
|
|||
<nop>
|
||||
<sect1 id="sec-common-options"><title>Common options</title>
|
||||
|
||||
<para>Most Nix commands accept the following command-line options:</para>
|
||||
|
||||
<variablelist>
|
||||
|
||||
<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>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>--help</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Prints out a summary of the command syntax and exits.
|
||||
|
||||
<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><quote>Errors only</quote>: only print messages
|
||||
explaining why the Nix invocation failed.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>1</term>
|
||||
<listitem><para><quote>Informational</quote>: print
|
||||
<emphasis>useful</emphasis> messages about what Nix is doing.
|
||||
This is the default.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>2</term>
|
||||
<listitem><para><quote>Talkative</quote>: print more informational
|
||||
messages.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>3</term>
|
||||
<listitem><para><quote>Chatty</quote>: print even more
|
||||
informational messages.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>4</term>
|
||||
<listitem><para><quote>Debug</quote>: print debug
|
||||
information.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>5</term>
|
||||
<listitem><para><quote>Vomit</quote>: print vast amounts of debug
|
||||
information.</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><term><option>--max-jobs</option> / <option>-j</option></term>
|
||||
|
||||
<listitem><para>Sets the maximum number of build jobs that Nix will
|
||||
perform in parallel to the specified number. The default is 1. A
|
||||
higher value is useful on SMP systems or to exploit I/O latency.</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>--version</option></term>
|
||||
<varlistentry><term><option>--fallback</option></term>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Prints out the Nix version number on standard output and exits.
|
||||
</para>
|
||||
|
||||
<para>Whenever Nix attempts to realise a derivation for which a
|
||||
closure is already known, but this closure cannot be realised, fall
|
||||
back on normalising 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, binary
|
||||
installation falls back on a source installation. 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>--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>
|
||||
<varlistentry><term><option>--readonly-mode</option></term>
|
||||
|
||||
<para>
|
||||
This option may be specified repeatedly. Currently, the
|
||||
following verbosity levels exist:
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>0</term>
|
||||
<listitem>
|
||||
<para>
|
||||
<quote>Errors only</quote>: only print messages explaining
|
||||
why the Nix invocation failed.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>1</term>
|
||||
<listitem>
|
||||
<para>
|
||||
<quote>Informational</quote>: print
|
||||
<emphasis>useful</emphasis> messages about what Nix is
|
||||
doing. This is the default.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>2</term>
|
||||
<listitem>
|
||||
<para>
|
||||
<quote>Talkative</quote>: print more informational messages.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>3</term>
|
||||
<listitem>
|
||||
<para>
|
||||
<quote>Chatty</quote>: print even more informational messages.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>4</term>
|
||||
<listitem>
|
||||
<para>
|
||||
<quote>Debug</quote>: print debug information:
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>5</term>
|
||||
<listitem>
|
||||
<para>
|
||||
<quote>Vomit</quote>: print vast amounts of debug
|
||||
information.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
</listitem>
|
||||
<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>--no-build-output</option> / <option>-Q</option></term>
|
||||
<varlistentry id="opt-log-type"><term><option>--log-type</option>
|
||||
<replaceable>type</replaceable></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>
|
||||
|
||||
<para>This option determines how the output written to standard
|
||||
error is formatted. Nix’s diagnostic messages are typically
|
||||
<emphasis>nested</emphasis>. For instance, when tracing Nix
|
||||
expression evaluation (<command>nix-env -vvvvv</command>, messages
|
||||
from subexpressions are nested inside their parent expressions. Nix
|
||||
builder output is also often nested. For instance, the Nix Packages
|
||||
generic builder nests the various build tasks (unpack, configure,
|
||||
compile, etc.), and the GNU Make in <literal>stdenv-linux</literal>
|
||||
has been patched to provide nesting for recursive Make
|
||||
invocations.</para>
|
||||
|
||||
<para><replaceable>type</replaceable> can be one of the
|
||||
following:
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry><term><literal>pretty</literal></term>
|
||||
|
||||
<listitem><para>Pretty-print the output, indicating different
|
||||
nesting levels using spaces. This is the
|
||||
default.</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term><literal>escapes</literal></term>
|
||||
|
||||
<listitem><para>Indicate nesting using escape codes that can be
|
||||
interpreted by the <command>log2xml</command> tool in the Nix
|
||||
source distribution. The resulting XML file can be fed into the
|
||||
<command>log2html.xsl</command> stylesheet to create an HTML
|
||||
file that can be browsed interactively, using Javascript to
|
||||
expand and collapse parts of the output.</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term><literal>flat</literal></term>
|
||||
|
||||
<listitem><para>Remove all nesting.</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</para>
|
||||
|
||||
</listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term><option>--max-jobs</option> / <option>-j</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Sets the maximum number of build jobs that Nix will perform in
|
||||
parallel to the specified number. The default is 1. A higher
|
||||
value is useful on SMP systems or to exploit I/O latency.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
|
||||
<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 realise a derivation for which a
|
||||
closure is already known, but this closure cannot be realised,
|
||||
fall back on normalising 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,
|
||||
binary installation falls back on a source installation. 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>--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>
|
||||
|
||||
</nop>
|
||||
</sect1>
|
||||
Loading…
Add table
Add a link
Reference in a new issue