diff options
Diffstat (limited to 'doc/manual/command-ref/env-common.xml')
| -rw-r--r-- | doc/manual/command-ref/env-common.xml | 327 |
1 files changed, 327 insertions, 0 deletions
diff --git a/doc/manual/command-ref/env-common.xml b/doc/manual/command-ref/env-common.xml new file mode 100644 index 000000000000..c757cb17bd10 --- /dev/null +++ b/doc/manual/command-ref/env-common.xml @@ -0,0 +1,327 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + 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>IN_NIX_SHELL</envar></term> + + <listitem><para>Indicator that tells if the current environment was set up by + <command>nix-shell</command>.</para></listitem> + +</varlistentry> + +<varlistentry xml:id="env-NIX_PATH"><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>If a path in the Nix search path starts with + <literal>http://</literal> or <literal>https://</literal>, it is + interpreted as the URL of a tarball that will be downloaded and + unpacked to a temporary location. The tarball must consist of a + single top-level directory. For example, setting + <envar>NIX_PATH</envar> to + + <screen> +nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz</screen> + + tells Nix to download the latest revision in the Nixpkgs/NixOS + 14.12 channel.</para> + + <para>The search path can be extended using the <option + linkend="opt-I">-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_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>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><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> + + +</chapter> |