* Documented common environment variables.

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;
+}