diff options
Diffstat (limited to 'doc/manual/opt-common.xml')
| -rw-r--r-- | doc/manual/opt-common.xml | 321 |
1 files changed, 171 insertions, 150 deletions
diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml index b0e581ff9075..a8f252128023 100644 --- a/doc/manual/opt-common.xml +++ b/doc/manual/opt-common.xml @@ -1,188 +1,209 @@ -<nop> +<sect1 id="sec-common-options"><title>Common options</title> -<varlistentry> - <term><option>--help</option></term> - <listitem> - <para> - Prints out a summary of the command syntax and exits. - </para> - </listitem> +<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><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>--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>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> - <para> - This option may be specified repeatedly. Currently, the - following verbosity levels exist: - </para> + </listitem> + +</varlistentry> - <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><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>--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><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>--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><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-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). +<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>--keep-failed</option> / <option>-K</option></term> +<varlistentry><term><option>--fallback</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> + + <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>--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> +<varlistentry><term><option>--readonly-mode</option></term> - <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> + <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>--readonly-mode</option></term> +<varlistentry id="opt-log-type"><term><option>--log-type</option> +<replaceable>type</replaceable></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> + + <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> -</nop> \ No newline at end of file + +</variablelist> + + +</sect1> \ No newline at end of file |