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
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
|
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xml:id="chap-stdenv">
<title>The Standard Environment</title>
<para>The standard build environment in the Nix Packages collection
provides a environment for building Unix packages that does a lot of
common build tasks automatically. In fact, for Unix packages that use
the standard <literal>./configure; make; make install</literal> build
interface, you don’t need to write a build script at all; the standard
environment does everything automatically. If
<literal>stdenv</literal> doesn’t do what you need automatically, you
can easily customise or override the various build phases.</para>
<section><title>Using <literal>stdenv</literal></title>
<para>To build a package with the standard environment, you use the
function <varname>stdenv.mkDerivation</varname>, instead of the
primitive built-in function <varname>derivation</varname>, e.g.
<programlisting>
stdenv.mkDerivation {
name = "libfoo-1.2.3";
src = fetchurl {
url = http://example.org/libfoo-1.2.3.tar.bz2;
md5 = "e1ec107956b6ddcb0b8b0679367e9ac9";
};
}</programlisting>
(<varname>stdenv</varname> needs to be in scope, so if you write this
in a separate Nix expression from
<filename>pkgs/all-packages.nix</filename>, you need to pass it as a
function argument.) Specifying a <varname>name</varname> and a
<varname>src</varname> is the absolute minimum you need to do. Many
packages have dependencies that are not provided in the standard
environment. It’s usually sufficient to specify those dependencies in
the <varname>buildInputs</varname> attribute:
<programlisting>
stdenv.mkDerivation {
name = "libfoo-1.2.3";
...
buildInputs = [libbar perl ncurses];
}</programlisting>
This attribute ensures that the <filename>bin</filename>
subdirectories of these packages appear in the <envar>PATH</envar>
environment variable during the build, that their
<filename>include</filename> subdirectories are searched by the C
compiler, and so on. (See <xref linkend="ssec-setup-hooks"/> for
details.)</para>
<para>Often it is necessary to override or modify some aspect of the
build. To make this easier, the standard environment breaks the
package build into a number of <emphasis>phases</emphasis>, all of
which can be overriden or modified individually: unpacking the
sources, applying patches, configuring, building, and installing.
(There are some others; see <xref linkend="ssec-stdenv-phases"/>.)
For instance, a package that doesn’t supply a makefile but instead has
to be compiled “manually” could be handled like this:
<programlisting>
stdenv.mkDerivation {
name = "fnord-4.5";
...
buildPhase = ''
gcc foo.c -o foo
'';
installPhase = ''
ensureDir $out/bin
cp foo $out/bin
'';
}</programlisting>
(Note the use of <literal>''</literal>-style string literals, which
are very convenient for large multi-line script fragments because they
don’t need escaping of <literal>"</literal> and <literal>\</literal>,
and because indentation is intelligently removed.)</para>
<para>There are many other attributes to customise the build. These
are listed in <xref linkend="ssec-stdenv-attributes"/>.</para>
<para>While the standard environment provides a generic builder, you
can still supply your own build script:
<programlisting>
stdenv.mkDerivation {
name = "libfoo-1.2.3";
...
builder = ./builder.sh;
}</programlisting>
where the builder can do anything it wants, but typically starts with
<programlisting>
source $stdenv/setup
</programlisting>
to let <literal>stdenv</literal> set up the environment (e.g., process
the <varname>buildInputs</varname>). If you want, you can still use
<literal>stdenv</literal>’s generic builder:
<programlisting>
source $stdenv/setup
buildPhase() {
echo "... this is my custom build phase ..."
gcc foo.c -o foo
}
installPhase() {
ensureDir $out/bin
cp foo $out/bin
}
genericBuild
</programlisting>
</para>
</section>
<section><title>Tools provided by <literal>stdenv</literal></title>
<para>The standard environment provides the following packages:
<itemizedlist>
<listitem><para>The GNU C Compiler, configured with C and C++
support.</para></listitem>
<listitem><para>GNU coreutils (contains a few dozen standard Unix
commands).</para></listitem>
<listitem><para>GNU findutils (contains
<command>find</command>).</para></listitem>
<listitem><para>GNU diffutils (contains <command>diff</command>,
<command>cmp</command>).</para></listitem>
<listitem><para>GNU <command>sed</command>.</para></listitem>
<listitem><para>GNU <command>grep</command>.</para></listitem>
<listitem><para>GNU <command>awk</command>.</para></listitem>
<listitem><para>GNU <command>tar</command>.</para></listitem>
<listitem><para><command>gzip</command> and
<command>bzip2</command>.</para></listitem>
<listitem><para>GNU Make. It has been patched to provide
<quote>nested</quote> output that can be fed into the
<command>nix-log2xml</command> command and
<command>log2html</command> stylesheet to create a structured,
readable output of the build steps performed by
Make.</para></listitem>
<listitem><para>Bash. This is the shell used for all builders in
the Nix Packages collection. Not using <command>/bin/sh</command>
removes a large source of portability problems.</para></listitem>
<listitem><para>The <command>patch</command>
command.</para></listitem>
</itemizedlist>
</para>
<para>On Linux, <literal>stdenv</literal> also includes the
<command>patchelf</command> utility.</para>
</section>
<section xml:id="ssec-stdenv-phases"><title>Build phases</title>
<para>The generic builder has a number of <emphasis>phases</emphasis>.
Each phase can be overriden in its entirety either by setting the
environment variable
<varname><replaceable>name</replaceable>Phase</varname> to a string
containing some shell commands to be executed, or by redefining the
shell function
<varname><replaceable>name</replaceable>Phase</varname>. The former
is convenient to override a phase from the derivation, while the
latter is convenient from a build script.</para>
<para>The phases are:
<itemizedlist>
<listitem>
<para><function>unpackPhase</function> unpacks the source files
listed in the <envar>src</envar> environment variable to the
current directory. It supports <filename>tar</filename> files,
optionally compressed with <command>gzip</command> or
<command>bzip2</command>; Zip files (but note that the
<command>unzip</command> command is not a part of the standard
environment; you should add it as a build input yourself); and
unpacked source trees (i.e., directories; they are copied
verbatim). You can add support for other file types by setting
the <varname>findUnpacker</varname> hook. This hook should set
the variable <varname>unpackCmd</varname> to contain the command
to be executed to unpack the file.</para>
<para>After running <function>unpackPhase</function>, the generic
builder changes the current directory to the directory created by
unpacking the sources. If there are multiple source directories,
you should set <varname>sourceRoot</varname> to the name of the
intended directory.</para>
<para>It also calls the hook <varname>postUnpack</varname> after
unpacking.</para>
</listitem>
<listitem><para><function>patchPhase</function> calls the
<command>patch</command> command with the <option>-p1</option>
option (overridable via <envar>patchFlags</envar>) for each patch
file listed in the <envar>patches</envar>
variable.</para></listitem>
<listitem>
<para><function>configurePhase</function> runs the script called
<filename>configure</filename> in the current directory with a
<option>--prefix</option> set to the output path. You can add
additional flags through the <varname>configureFlags</varname>
variable. If <filename>configure</filename> does not exist,
nothing happens.</para>
<para>Before and after running <filename>configure</filename>, the
hooks <varname>preConfigure</varname> and
<varname>postConfigure</varname> are called, respectively.</para>
</listitem>
<listitem>
<para><function>buildPhase</function> calls
<command>make</command>. You can set flags for
<command>make</command> through the <varname>makeFlags</varname>
variable.</para>
<para>Before and after running <command>make</command>, the hooks
<varname>preBuild</varname> and <varname>postBuild</varname> are
called, respectively.</para>
</listitem>
<listitem><para><function>checkPhase</function> calls <command>make
check</command>, but only if the <varname>doCheck</varname> variable
is set to <literal>1</literal>. Additional flags can be set through
the <varname>checkFlags</varname> variable.</para></listitem>
<listitem>
<para><function>installPhase</function> calls <command>make
install</command>. Additional flags can be set through the
<varname>installFlags</varname> variable.</para>
<para>Before and after running <command>make install</command>,
the hooks <varname>preInstall</varname> and
<varname>postInstall</varname> are called, respectively.</para>
</listitem>
<listitem>
<para><function>fixupPhase</function> cleans up the
installed files in various ways:
<itemizedlist>
<listitem><para>It moves the <filename>man/</filename>,
<filename>doc/</filename> and <filename>info/</filename>
subdirectories of <envar>$out</envar> to
<filename>share/</filename>.</para></listitem>
<listitem><para>It strips libraries and executables of debug
information.</para></listitem>
<listitem><para>On Linux, it applies the
<command>patchelf</command> command to ELF executables and
libraries to remove unused directories from the
<literal>RPATH</literal> in order to prevent unnecessary
dependencies.</para></listitem>
<listitem><para>It rewrites the interpreter paths of shell
scripts to paths found in <envar>PATH</envar>. E.g.,
<filename>/usr/bin/perl</filename> will be rewritten to
<filename>/nix/store/<replaceable>some-perl</replaceable>/bin/perl</filename>
found in <envar>PATH</envar>.</para></listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para><function>distPhase</function> calls <command>make
dist</command>, but only if the <varname>doDist</varname> variable
is set to <literal>1</literal>. Additional flags can be set
through the <varname>distFlags</varname> variable. The resulting
tarball is copied to the <filename>/tarballs</filename>
subdirectory of the output path.</para>
<para>Before and after running <command>make dist</command>, the
hooks <varname>preDist</varname> and <varname>postDist</varname>
are called, respectively.</para>
</listitem>
</itemizedlist>
</para>
<para>You can change the order in which phases are executed, or add
new phases, by setting the <varname>phases</varname> variable. The
default is <literal>patchPhase configurePhase buildPhase checkPhase
installPhase distPhase</literal>.</para>
</section>
<section xml:id="ssec-stdenv-attributes"><title>Attributes</title>
<para></para>
</section>
<section xml:id="ssec-setup-hooks"><title>Package setup hooks</title>
<para></para>
</section>
<section><title>Purity in Nixpkgs</title>
<para>[measures taken to prevent dependencies on packages outside the
store, and what you can do to prevent them]</para>
<para>GCC doesn't search in locations such as
<filename>/usr/include</filename>. In fact, attempts to add such
directories through the <option>-I</option> flag are filtered out.
Likewise, the linker (from GNU binutils) doesn't search in standard
locations such as <filename>/usr/lib</filename>. Programs built on
Linux are linked against a GNU C Library that likewise doesn't search
in the default system locations.</para>
</section>
</chapter>
|