diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index af366552e..082c034f1 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 000000000..7a436beba
--- /dev/null
+++ b/doc/manual/env-common.xml
@@ -0,0 +1,112 @@
+Common environment variables
+
+Most Nix commands interpret the following environment variables:
+
+
+
+
+NIX_ROOT
+
+ If NIX_ROOT is set, the Nix command
+ will on startup perform a chroot() 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).
+
+
+
+
+NIX_IGNORE_SYMLINK_STORE
+
+
+
+ Normally, the Nix store directory (typically
+ /nix/store) 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
+ /nix/store resolving to different locations)
+ could yield different results. This is generally not a problem,
+ except when builds are deployed to machines where
+ /nix/store resolves differently. If you are
+ sure that you’re not going to do that, you can set
+ NIX_IGNORE_SYMLINK_STORE to 1.
+
+ 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 bind mount points, e.g.,
+
+
+$ mkdir /nix
+$ mount -o bind /mnt/otherdisk/nix /nix
+
+ Consult the mount
+ 8 manual page for details.
+
+
+
+
+
+
+NIX_STORE_DIR
+
+ Overrides the location of the Nix store (default
+ prefix/store).
+
+
+
+
+NIX_DATA_DIR
+
+ Overrides the location of the Nix static data
+ directory (default
+ prefix/share).
+
+
+
+
+NIX_LOG_DIR
+
+ Overrides the location of the Nix log directory
+ (default prefix/log/nix).
+
+
+
+
+NIX_STATE_DIR
+
+ Overrides the location of the Nix state directory
+ (default prefix/var/nix).
+
+
+
+
+NIX_DB_DIR
+
+ Overrides the location of the Nix database (default
+ $NIX_STATE_DIR/db, i.e.,
+ prefix/var/nix/db).
+
+
+
+
+NIX_CONF_DIR
+
+ Overrides the location of the Nix configuration
+ directory (default
+ prefix/etc/nix).
+
+
+
+
+NIX_LOG_TYPE
+
+ Equivalent to the
+ option.
+
+
+
+
+
+
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index 5bdb7b324..244c4ca23 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -33,6 +33,8 @@
Command Reference
+
+ nix-env
diff --git a/doc/manual/nix-env.xml b/doc/manual/nix-env.xml
index b830cd5ea..6d145a212 100644
--- a/doc/manual/nix-env.xml
+++ b/doc/manual/nix-env.xml
@@ -74,13 +74,12 @@
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 .
-
-
/
diff --git a/doc/manual/nix-instantiate.xml b/doc/manual/nix-instantiate.xml
index ec26eaa71..d854941a0 100644
--- a/doc/manual/nix-instantiate.xml
+++ b/doc/manual/nix-instantiate.xml
@@ -31,7 +31,8 @@
This command is generally used for testing Nix expression before
- they are used with nix-env.
+ they are used with nix-env. See also .
@@ -41,8 +42,6 @@
-
-
diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml
index 9304c4bec..5eb70c4eb 100644
--- a/doc/manual/nix-store.xml
+++ b/doc/manual/nix-store.xml
@@ -41,15 +41,10 @@
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 .
-
-
-
-
-
-
diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml
index b0e581ff9..a8f252128 100644
--- a/doc/manual/opt-common.xml
+++ b/doc/manual/opt-common.xml
@@ -1,188 +1,209 @@
-
+Common options
+
+Most Nix commands accept the following command-line options:
+
+
+
+
+
+ Prints out a summary of the command syntax and
+ exits.
+
+
+
+
+
+
+ Prints out the Nix version number on standard output
+ and exits.
+
+
+
+ /
-
-
-
- Prints out a summary of the command syntax and exits.
+
+ 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.
+
+ This option may be specified repeatedly. Currently, the
+ following verbosity levels exist:
+
+
+
+ 0
+ Errors only: only print messages
+ explaining why the Nix invocation failed.
+
+
+ 1
+ Informational: print
+ useful messages about what Nix is doing.
+ This is the default.
+
+
+ 2
+ Talkative: print more informational
+ messages.
+
+
+ 3
+ Chatty: print even more
+ informational messages.
+
+
+ 4
+ Debug: print debug
+ information.
+
+
+ 5
+ Vomit: print vast amounts of debug
+ information.
+
+
+
+
+
+
+
+
+
+ /
+
+ 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
+ prefix/nix/var/log/nix.
+
+
+
+
+ /
+
+ 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.
+
+
+
+
+ /
+
+ 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).
+
+
+
+
+ /
+
+ Specifies that in case of a build failure, the
+ temporary directory (usually in /tmp) in which
+ the build takes place should not be deleted. The path of the build
+ directory is printed as an informational message.
-
-
+
+
-
- Prints out the Nix version number on standard output and exits.
-
+
+ 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.
+
+ 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).
+
+
-
- /
-
-
- 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.
-
+
-
- This option may be specified repeatedly. Currently, the
- following verbosity levels exist:
-
-
-
-
- 0
-
-
- Errors only: only print messages explaining
- why the Nix invocation failed.
-
-
-
-
- 1
-
-
- Informational: print
- useful messages about what Nix is
- doing. This is the default.
-
-
-
-
- 2
-
-
- Talkative: print more informational messages.
-
-
-
-
- 3
-
-
- Chatty: print even more informational messages.
-
-
-
-
- 4
-
-
- Debug: print debug information:
-
-
-
-
- 5
-
-
- Vomit: print vast amounts of debug
- information.
-
-
-
-
-
-
+ 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.
+
-
- /
+
+type
+
-
- 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
- prefix/nix/var/log/nix.
-
+
+ This option determines how the output written to standard
+ error is formatted. Nix’s diagnostic messages are typically
+ nested. For instance, when tracing Nix
+ expression evaluation (nix-env -vvvvv, 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 stdenv-linux
+ has been patched to provide nesting for recursive Make
+ invocations.
+
+ type can be one of the
+ following:
+
+
+
+ pretty
+
+ Pretty-print the output, indicating different
+ nesting levels using spaces. This is the
+ default.
+
+
+
+ escapes
+
+ Indicate nesting using escape codes that can be
+ interpreted by the log2xml tool in the Nix
+ source distribution. The resulting XML file can be fed into the
+ log2html.xsl stylesheet to create an HTML
+ file that can be browsed interactively, using Javascript to
+ expand and collapse parts of the output.
+
+
+
+ flat
+
+ Remove all nesting.
+
+
+
+
+
+
+
+
-
- /
-
-
- 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.
-
-
-
+
-
- /
-
-
- 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).
-
-
-
-
-
-
- /
-
-
- Specifies that in case of a build failure, the temporary
- directory (usually in /tmp) in which the
- build takes place should not be deleted. The path of the build
- directory is printed as an informational message.
-
-
-
-
-
-
-
-
-
- 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.
-
-
-
- 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).
-
-
-
-
-
-
-
-
-
- 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.
-
-
-
-
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/doc/manual/style.css b/doc/manual/style.css
index 893e7db3f..c97cb9cbf 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;
+}