about summary refs log tree commit diff
path: root/doc/manual/command-ref/env-common.xml
blob: c532ffddea2263ee76457dc6228037faf8d2897c (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
<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>&lt;<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>&lt;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>/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-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>