318 lines
10 KiB
XML
318 lines
10 KiB
XML
<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>
|