about summary refs log tree commit diff
path: root/doc/manual/command-ref/env-common.xml
blob: c501d1c011c068e66e7b5a6ff1cf712eb0690a12 (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
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
<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>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>The search path can be extended using the
    <option>-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 xml:id="envar-other-stores"><term><envar>NIX_OTHER_STORES</envar></term>

  <listitem><para>This variable contains the paths of remote Nix
  installations from which packages can be copied, separated by colons.
  <phrase condition="manual">See <xref linkend="sec-sharing-packages"
  /> for details.</phrase>  Each path should be the
  <filename>/nix</filename> directory of a remote Nix installation
  (i.e., not the <filename>/nix/store</filename> directory).  The
  paths are subject to globbing, so you can set it so something like
  <literal>/var/run/nix/remote-stores/*/nix</literal> and mount
  multiple remote filesystems in
  <literal>/var/run/nix/remote-stores</literal>.</para>

  <para>Note that if you’re building through the <link
  linkend="sec-nix-daemon">Nix daemon</link>, the only setting for
  this variable that matters is the one that the
  <command>nix-daemon</command> process uses.  So if you want to
  change it, you have to restart the daemon.</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>