Jonas Chevalier
895516cadf
Motivation: maintain project-level configuration files. Document the whole situation a bit better so that it corresponds to the implementation, and add NIX_USER_CONF_FILES that allows overriding which user files Nix will load during startup.
210 lines
6.8 KiB
XML
210 lines
6.8 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><term><envar>IN_NIX_SHELL</envar></term>
|
||
|
||
<listitem><para>Indicator that tells if the current environment was set up by
|
||
<command>nix-shell</command>. Since Nix 2.0 the values are
|
||
<literal>"pure"</literal> and <literal>"impure"</literal></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 this 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-15.09.tar.gz</screen>
|
||
|
||
tells Nix to download the latest revision in the Nixpkgs/NixOS
|
||
15.09 channel.</para>
|
||
|
||
<para>A following shorthand can be used to refer to the official channels:
|
||
|
||
<screen>nixpkgs=channel:nixos-15.09</screen>
|
||
</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>/var/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 system Nix configuration
|
||
directory (default
|
||
<filename><replaceable>prefix</replaceable>/etc/nix</filename>).</para></listitem>
|
||
|
||
</varlistentry>
|
||
|
||
<varlistentry><term><envar>NIX_USER_CONF_FILES</envar></term>
|
||
|
||
<listitem><para>Overrides the location of the user Nix configuration files
|
||
to load from (defaults to the XDG spec locations). The variable is treated
|
||
as a list separated by the <literal>:</literal> token.</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-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>.
|
||
If the Nix daemon's Unix socket is at some non-standard path,
|
||
this variable should be set to <literal>unix://path/to/socket</literal>.
|
||
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>
|