opt-common.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. NOTE: the json schema is not guarantees to be stable between releases.</para></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>