diff options
Diffstat (limited to 'doc/manual/command-ref/opt-common.xml')
| -rw-r--r-- | doc/manual/command-ref/opt-common.xml | 412 |
1 files changed, 0 insertions, 412 deletions
diff --git a/doc/manual/command-ref/opt-common.xml b/doc/manual/command-ref/opt-common.xml deleted file mode 100644 index 093bc2526..000000000 --- a/doc/manual/command-ref/opt-common.xml +++ /dev/null @@ -1,412 +0,0 @@ -<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> |