* Documented common environment variables.
This commit is contained in:
Eelco Dolstra
parent
f982df3cd7
commit
ad3121a52d
|
|
@ -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 -
|
||||
|
|
|
|||
112
doc/manual/env-common.xml
Normal file
112
doc/manual/env-common.xml
Normal file
|
|
@ -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>
|
||||
|
|
@ -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" />
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,188 +1,209 @@
|
|||
<nop>
|
||||
<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>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>--help</option></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Prints out a summary of the command syntax and exits.
|
||||
|
||||
<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>--version</option></term>
|
||||
<varlistentry><term><option>--fallback</option></term>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Prints out the Nix version number on standard output and exits.
|
||||
</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>--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>
|
||||
<varlistentry><term><option>--readonly-mode</option></term>
|
||||
|
||||
<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>
|
||||
<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>--no-build-output</option> / <option>-Q</option></term>
|
||||
<varlistentry id="opt-log-type"><term><option>--log-type</option>
|
||||
<replaceable>type</replaceable></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>
|
||||
|
||||
<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>
|
||||
|
||||
|
||||
<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>
|
||||
</variablelist>
|
||||
|
||||
|
||||
<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>
|
||||
|
||||
</nop>
|
||||
</sect1>
|
||||
|
|
@ -229,4 +229,9 @@ div.epigraph
|
|||
table.productionset table.productionset
|
||||
{
|
||||
font-family: monospace;
|
||||
}
|
||||
}
|
||||
|
||||
a[href] {
|
||||
text-decoration: none;
|
||||
border-bottom: 1px dotted #005aa0;
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue