<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 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>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_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>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>