diff options
| -rw-r--r-- | doc/manual/Makefile.am | 2 | ||||
| -rw-r--r-- | doc/manual/env-common.xml | 112 | ||||
| -rw-r--r-- | doc/manual/manual.xml | 2 | ||||
| -rw-r--r-- | doc/manual/nix-env.xml | 5 | ||||
| -rw-r--r-- | doc/manual/nix-instantiate.xml | 5 | ||||
| -rw-r--r-- | doc/manual/nix-store.xml | 9 | ||||
| -rw-r--r-- | doc/manual/opt-common.xml | 321 | ||||
| -rw-r--r-- | doc/manual/style.css | 7 |
8 files changed, 298 insertions, 165 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index af366552e41e..082c034f195a 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -18,7 +18,7 @@ MANUAL_SRCS = manual.xml introduction.xml installation.xml \ build-farm.xml \ $(man1_MANS:.1=.xml) \ troubleshooting.xml bugs.xml opt-common.xml opt-common-syn.xml \ - quick-start.xml nix-lang-ref.xml style.css images + env-common.xml quick-start.xml nix-lang-ref.xml style.css images manual.is-valid: $(MANUAL_SRCS) version.txt $(XMLLINT) --xinclude $< | $(XMLLINT) --noout --valid - diff --git a/doc/manual/env-common.xml b/doc/manual/env-common.xml new file mode 100644 index 000000000000..7a436bebac34 --- /dev/null +++ b/doc/manual/env-common.xml @@ -0,0 +1,112 @@ +<sect1 id="sec-common-env"><title>Common environment variables</title> + +<para>Most Nix commands interpret the following environment variables:</para> + +<variablelist> + + +<varlistentry><term><envar>NIX_ROOT</envar></term> + + <listitem><para>If <envar>NIX_ROOT</envar> is set, the Nix command + will on startup perform a <function>chroot()</function> to the + specified directory. This is useful in certain bootstrapping + situations (e.g., when installing a Nix installation onto a hard + disk from CD-ROM).</para></listitem> + +</varlistentry> + + +<varlistentry><term><envar>NIX_IGNORE_SYMLINK_STORE</envar></term> + + <listitem> + + <para>Normally, the Nix store directory (typically + <filename>/nix/store</filename>) is not allowed to contain any + symlink components. This is to prevent “impure” builds. Builders + sometimes “canonicalise” paths by resolving all symlink components. + Thus, builds on different machines (with + <filename>/nix/store</filename> resolving to different locations) + could yield different results. This is generally not a problem, + except when builds are deployed to machines where + <filename>/nix/store</filename> resolves differently. If you are + sure that you’re not going to do that, you can set + <envar>NIX_IGNORE_SYMLINK_STORE</envar> to <envar>1</envar>.</para> + + <para>Note that if you’re symlinking the Nix store so that you can + put it on another file system than the root file system, on Linux + you’re better off using <literal>bind</literal> mount points, e.g., + + <screen> +$ mkdir /nix +$ mount -o bind /mnt/otherdisk/nix /nix</screen> + + Consult the <citerefentry><refentrytitle>mount</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> manual page for details.</para> + + </listitem> + +</varlistentry> + + +<varlistentry><term><envar>NIX_STORE_DIR</envar></term> + + <listitem><para>Overrides the location of the Nix store (default + <filename><replaceable>prefix</replaceable>/store</filename>).</para></listitem> + +</varlistentry> + + +<varlistentry><term><envar>NIX_DATA_DIR</envar></term> + + <listitem><para>Overrides the location of the Nix static data + directory (default + <filename><replaceable>prefix</replaceable>/share</filename>).</para></listitem> + +</varlistentry> + + +<varlistentry><term><envar>NIX_LOG_DIR</envar></term> + + <listitem><para>Overrides the location of the Nix log directory + (default <filename><replaceable>prefix</replaceable>/log/nix</filename>).</para></listitem> + +</varlistentry> + + +<varlistentry><term><envar>NIX_STATE_DIR</envar></term> + + <listitem><para>Overrides the location of the Nix state directory + (default <filename><replaceable>prefix</replaceable>/var/nix</filename>).</para></listitem> + +</varlistentry> + + +<varlistentry><term><envar>NIX_DB_DIR</envar></term> + + <listitem><para>Overrides the location of the Nix database (default + <filename><replaceable>$NIX_STATE_DIR</replaceable>/db</filename>, i.e., + <filename><replaceable>prefix</replaceable>/var/nix/db</filename>).</para></listitem> + +</varlistentry> + + +<varlistentry><term><envar>NIX_CONF_DIR</envar></term> + + <listitem><para>Overrides the location of the Nix configuration + directory (default + <filename><replaceable>prefix</replaceable>/etc/nix</filename>).</para></listitem> + +</varlistentry> + + +<varlistentry><term><envar>NIX_LOG_TYPE</envar></term> + + <listitem><para>Equivalent to the <link + linkend="opt-log-type"><option>--log-type</option> + option</link>.</para></listitem> + +</varlistentry> + +</variablelist> + +</sect1> diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index 5bdb7b324be8..244c4ca23881 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -33,6 +33,8 @@ <appendix> <title>Command Reference</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="env-common.xml" /> <sect1> <title>nix-env</title> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-env.xml" /> diff --git a/doc/manual/nix-env.xml b/doc/manual/nix-env.xml index b830cd5eae9f..6d145a2129ff 100644 --- a/doc/manual/nix-env.xml +++ b/doc/manual/nix-env.xml @@ -74,13 +74,12 @@ <para> This section lists the options that are common to all operations. These options are allowed for every subcommand, - though they may not always have an effect. + though they may not always have an effect. See also <xref + linkend="sec-common-options" />. </para> <variablelist> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common.xml#xpointer(/nop/*)" /> - <varlistentry> <term><option>--file</option> / <option>-f</option></term> <listitem> diff --git a/doc/manual/nix-instantiate.xml b/doc/manual/nix-instantiate.xml index ec26eaa71379..d854941a09bd 100644 --- a/doc/manual/nix-instantiate.xml +++ b/doc/manual/nix-instantiate.xml @@ -31,7 +31,8 @@ <para> This command is generally used for testing Nix expression before - they are used with <command>nix-env</command>. + they are used with <command>nix-env</command>. See also <xref + linkend="sec-common-options" />. </para> </refsection> @@ -41,8 +42,6 @@ <variablelist> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common.xml#xpointer(/nop/*)" /> - <varlistentry> <term><option>--parse-only</option></term> <listitem> diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml index 9304c4becc84..5eb70c4eb93a 100644 --- a/doc/manual/nix-store.xml +++ b/doc/manual/nix-store.xml @@ -41,15 +41,10 @@ <para> This section lists the options that are common to all operations. These options are allowed for every subcommand, - though they may not always have an effect. + though they may not always have an effect. See also <xref + linkend="sec-common-options" />. </para> - <variablelist> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common.xml#xpointer(/nop/*)" /> - - </variablelist> - </refsection> 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 diff --git a/doc/manual/style.css b/doc/manual/style.css index 893e7db3f1df..c97cb9cbf4b8 100644 --- a/doc/manual/style.css +++ b/doc/manual/style.css @@ -229,4 +229,9 @@ div.epigraph table.productionset table.productionset { font-family: monospace; -} \ No newline at end of file +} + +a[href] { + text-decoration: none; + border-bottom: 1px dotted #005aa0; +} |