diff options
Diffstat (limited to 'doc/manual/env-common.xml')
| -rw-r--r-- | doc/manual/env-common.xml | 347 |
1 files changed, 0 insertions, 347 deletions
diff --git a/doc/manual/env-common.xml b/doc/manual/env-common.xml deleted file mode 100644 index 9e97e58f57..0000000000 --- a/doc/manual/env-common.xml +++ /dev/null @@ -1,347 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xml:id="sec-common-env"> - -<title>Common environment variables</title> - - -<para>Most Nix commands interpret the following environment variables:</para> - -<variablelist xml:id="env-common"> - - -<varlistentry><term><envar>NIX_PATH</envar></term> - - <listitem> - - <para>A colon-separated list of directories used to look up Nix - expressions enclosed in angle brackets (i.e., - <literal><<replaceable>path</replaceable>></literal>). For - instance, the value - - <screen> -/home/eelco/Dev:/etc/nixos</screen> - - will cause Nix to look for paths relative to - <filename>/home/eelco/Dev</filename> and - <filename>/etc/nixos</filename>, in that order. It is also - possible to match paths against a prefix. For example, the value - - <screen> -nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos</screen> - - will cause Nix to search for - <literal><nixpkgs/<replaceable>path</replaceable>></literal> in - <filename>/home/eelco/Dev/nixpkgs-branch/<replaceable>path</replaceable></filename> - and - <filename>/etc/nixos/nixpkgs/<replaceable>path</replaceable></filename>. - </para> - - <para>The search path can be extended using the - <option>-I</option> option, which takes precedence over - <envar>NIX_PATH</envar>.</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> - - -<varlistentry><term><envar>TMPDIR</envar></term> - - <listitem><para>Use the specified directory to store temporary - files. In particular, this includes temporary build directories; - these can take up substantial amounts of disk space. The default is - <filename>/tmp</filename>.</para></listitem> - -</varlistentry> - - -<varlistentry xml:id="envar-build-hook"><term><envar>NIX_BUILD_HOOK</envar></term> - - <listitem> - - <para>Specifies the location of the <emphasis>build hook</emphasis>, - which is a program (typically some script) that Nix will call - whenever it wants to build a derivation. This is used to implement - distributed builds<phrase condition="manual"> (see <xref - linkend="chap-distributed-builds" />)</phrase>.</para> - - <!-- - The protocol by - which the calling Nix process and the build hook communicate is as - follows. - - <para>The build hook is called with the following command-line - arguments: - - <orderedlist> - - <listitem><para>A boolean value <literal>0</literal> or - <literal>1</literal> specifying whether Nix can locally execute - more builds, as per the <link - linkend="opt-max-jobs"><option>- -max-jobs</option> option</link>. - The purpose of this argument is to allow the hook to not have to - maintain bookkeeping for the local machine.</para></listitem> - - <listitem><para>The Nix platform identifier for the local machine - (e.g., <literal>i686-linux</literal>).</para></listitem> - - <listitem><para>The Nix platform identifier for the derivation, - i.e., its <link linkend="attr-system"><varname>system</varname> - attribute</link>.</para></listitem> - - <listitem><para>The store path of the derivation.</para></listitem> - - </orderedlist> - - </para> - - <para>On the basis of this information, and whatever persistent - state the build hook keeps about other machines and their current - load, it has to decide what to do with the build. It should print - out on standard error one of the following responses (terminated by - a newline, <literal>"\n"</literal>): - - <variablelist> - - <varlistentry><term><literal># decline</literal></term> - - <listitem><para>The build hook is not willing or able to perform - the build; the calling Nix process should do the build itself, - if possible.</para></listitem> - - </varlistentry> - - <varlistentry><term><literal># postpone</literal></term> - - <listitem><para>The build hook cannot perform the build now, but - can do so in the future (e.g., because all available build slots - on remote machines are in use). The calling Nix process should - postpone this build until at least one currently running build - has terminated.</para></listitem> - - </varlistentry> - - <varlistentry><term><literal># accept</literal></term> - - <listitem><para>The build hook has accepted the - build.</para></listitem> - - </varlistentry> - - </variablelist> - - </para> - - <para>After sending <literal># accept</literal>, the hook should - read one line from standard input, which will be the string - <literal>okay</literal>. It can then proceed with the build. - Before sending <literal>okay</literal>, Nix will store in the hook’s - current directory a number of text files that contain information - about the derivation: - - <variablelist> - - <varlistentry><term><filename>inputs</filename></term> - - <listitem><para>The set of store paths that are inputs to the - build process (one per line). These have to be copied - <emphasis>to</emphasis> the remote machine (in addition to the - store derivation itself).</para></listitem> - - </varlistentry> - - <varlistentry><term><filename>outputs</filename></term> - - <listitem><para>The set of store paths that are outputs of the - derivation (one per line). These have to be copied - <emphasis>from</emphasis> the remote machine if the build - succeeds.</para></listitem> - - </varlistentry> - - <varlistentry><term><filename>references</filename></term> - - <listitem><para>The reference graph of the inputs, in the format - accepted by the command <command>nix-store - - -register-validity</command>. It is necessary to run this - command on the remote machine after copying the inputs to inform - Nix on the remote machine that the inputs are valid - paths.</para></listitem> - - </varlistentry> - - </variablelist> - - </para> - - <para>The hook should copy the inputs to the remote machine, - register the validity of the inputs, perform the remote build, and - copy the outputs back to the local machine. An exit code other than - <literal>0</literal> indicates that the hook has failed. An exit - code equal to 100 means that the remote build failed (as opposed to, - e.g., a network error).</para> - --> - - </listitem> - - -</varlistentry> - - -<varlistentry xml:id="envar-remote"><term><envar>NIX_REMOTE</envar></term> - - <listitem><para>This variable should be set to - <literal>daemon</literal> if you want to use the Nix daemon to - execute Nix operations. This is necessary in <link - linkend="ssec-multi-user">multi-user Nix installations</link>. - Otherwise, it should be left unset.</para></listitem> - -</varlistentry> - - -<varlistentry xml:id="envar-other-stores"><term><envar>NIX_OTHER_STORES</envar></term> - - <listitem><para>This variable contains the paths of remote Nix - installations from which packages can be copied, separated by colons. - <phrase condition="manual">See <xref linkend="sec-sharing-packages" - /> for details.</phrase> Each path should be the - <filename>/nix</filename> directory of a remote Nix installation - (i.e., not the <filename>/nix/store</filename> directory). The - paths are subject to globbing, so you can set it so something like - <literal>/var/run/nix/remote-stores/*/nix</literal> and mount - multiple remote filesystems in - <literal>/var/run/nix/remote-stores</literal>.</para> - - <para>Note that if you’re building through the <link - linkend="sec-nix-daemon">Nix daemon</link>, the only setting for - this variable that matters is the one that the - <command>nix-daemon</command> process uses. So if you want to - change it, you have to restart the daemon.</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_SHOW_STATS</envar></term> - - <listitem><para>If set to <literal>1</literal>, Nix will print some - evaluation statistics, such as the number of values - allocated.</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_COUNT_CALLS</envar></term> - - <listitem><para>If set to <literal>1</literal>, Nix will print how - often functions were called during Nix expression evaluation. This - is useful for profiling your Nix expressions.</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>GC_INITIAL_HEAP_SIZE</envar></term> - - <listitem><para>If Nix has been configured to use the Boehm garbage - collector, this variable sets the initial size of the heap in bytes. - It defaults to 384 MiB. Setting it to a low value reduces memory - consumption, but will increase runtime due to the overhead of - garbage collection.</para></listitem> - -</varlistentry> - - -</variablelist> - - -</section> |