lix/doc/manual/opt-common.xml

<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>

  <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><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>--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>


<varlistentry id="opt-log-type"><term><option>--log-type</option>
<replaceable>type</replaceable></term>

  <listitem>

  <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>


</variablelist>


</sect1>