From ad3121a52dacba417387df543df573816cd15b55 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Wed, 16 Mar 2005 16:45:29 +0000 Subject: [PATCH] * Documented common environment variables. --- doc/manual/Makefile.am | 2 +- doc/manual/env-common.xml | 112 +++++++++++ doc/manual/manual.xml | 2 + doc/manual/nix-env.xml | 5 +- doc/manual/nix-instantiate.xml | 5 +- doc/manual/nix-store.xml | 9 +- doc/manual/opt-common.xml | 351 +++++++++++++++++---------------- doc/manual/style.css | 7 +- 8 files changed, 313 insertions(+), 180 deletions(-) create mode 100644 doc/manual/env-common.xml diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index af366552e4..082c034f19 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 0000000000..7a436bebac --- /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 5bdb7b324b..244c4ca238 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 b830cd5eae..6d145a2129 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 ec26eaa713..d854941a09 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 9304c4becc..5eb70c4eb9 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 b0e581ff90..a8f2521280 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 893e7db3f1..c97cb9cbf4 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; +}