about summary refs log tree commit diff
path: root/doc/manual/nix-build.xml
blob: 3832f5fc34503a0286328d030c1d50e57cbe4150 (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
<refentry xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          xml:id="sec-nix-build">

<refmeta>
  <refentrytitle>nix-build</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="source">Nix</refmiscinfo>
  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
</refmeta>

<refnamediv>
  <refname>nix-build</refname>
  <refpurpose>build a Nix expression</refpurpose>
</refnamediv>

<refsynopsisdiv>
  <cmdsynopsis>
    <command>nix-build</command>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
    <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
    <arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
    <arg>
      <group choice='req'>
        <arg choice='plain'><option>--attr</option></arg>
        <arg choice='plain'><option>-A</option></arg>
      </group>
      <replaceable>attrPath</replaceable>
    </arg>
    <arg><option>--drv-link</option> <replaceable>drvlink</replaceable></arg>
    <arg><option>--add-drv-link</option></arg>
    <arg><option>--no-out-link</option></arg>
    <arg>
      <group choice='req'>
        <arg choice='plain'><option>--out-link</option></arg>
        <arg choice='plain'><option>-o</option></arg>
      </group>
      <replaceable>outlink</replaceable>
    </arg>
    <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
  </cmdsynopsis>
</refsynopsisdiv>

<refsection><title>Description</title>

<para>The <command>nix-build</command> command builds the derivations
described by the Nix expressions in <replaceable>paths</replaceable>.
If the build succeeds, it places a symlink to the result in the
current directory.  The symlink is called <filename>result</filename>.
If there are multiple Nix expressions, or the Nix expressions evaluate
to multiple derivations, multiple sequentially numbered symlinks are
created (<filename>result</filename>, <filename>result-2</filename>,
and so on).</para>

<para>If no <replaceable>paths</replaceable> are specified, then
<command>nix-build</command> will use <filename>default.nix</filename>
in the current directory, if it exists.</para>

<para><command>nix-build</command> is essentially a wrapper around
<link
linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>
(to translate a high-level Nix expression to a low-level store
derivation) and <link
linkend="rsec-nix-store-realise"><command>nix-store
--realise</command></link> (to build the store derivation).</para>

<warning><para>The result of the build is automatically registered as
a root of the Nix garbage collector.  This root disappears
automatically when the <filename>result</filename> symlink is deleted
or renamed.  So don’t rename the symlink.</para></warning>

</refsection>


<refsection><title>Options</title>

<para>All options not listed here are passed to <command>nix-store
--realise</command>, except for <option>--arg</option> and
<option>--attr</option> / <option>-A</option> which are passed to
<command>nix-instantiate</command>.  <phrase condition="manual">See
also <xref linkend="sec-common-options" />.</phrase></para>

<variablelist>

  <varlistentry><term><option>--drv-link</option> <replaceable>drvlink</replaceable></term>

    <listitem><para>Add a symlink named
    <replaceable>drvlink</replaceable> to the store derivation
    produced by <command>nix-instantiate</command>.  The derivation is
    a root of the garbage collector until the symlink is deleted or
    renamed.  If there are multiple derivations, numbers are suffixed
    to <replaceable>drvlink</replaceable> to distinguish between
    them.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--add-drv-link</option></term>

    <listitem><para>Shorthand for <option>--drv-link</option>
    <filename>./derivation</filename>.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--no-out-link</option></term>

    <listitem><para>Do not create a symlink to the output path.  Note
    that as a result the output does not become a root of the garbage
    collector, and so might be deleted by <command>nix-store
    --gc</command>.</para></listitem>

  </varlistentry>

  <varlistentry xml:id='opt-out-link'><term><option>--out-link</option> /
  <option>-o</option> <replaceable>outlink</replaceable></term>

    <listitem><para>Change the name of the symlink to the output path
    created from <filename>result</filename> to
    <replaceable>outlink</replaceable>.</para></listitem>

  </varlistentry>

</variablelist>

<para>The following common options are supported:</para>

<variablelist condition="manpage">
  <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" />
</variablelist>

</refsection>


<refsection><title>Examples</title>

<screen>
$ nix-build '&lt;nixpkgs>' -A firefox
store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv
/nix/store/d18hyl92g30l...-firefox-1.5.0.7

$ ls -l result
lrwxrwxrwx  <replaceable>...</replaceable>  result -> /nix/store/d18hyl92g30l...-firefox-1.5.0.7

$ ls ./result/bin/
firefox  firefox-config</screen>

<para>If a derivation has multiple outputs,
<command>nix-build</command> will build the default (first) output.
You can also build all outputs:
<screen>
$ nix-build '&lt;nixpkgs>' -A openssl.all
</screen>
This will create a symlink for each output named
<filename>result-<replaceable>outputname</replaceable></filename>.
The suffix is omitted if the output name is <literal>out</literal>.
So if <literal>openssl</literal> has outputs <literal>out</literal>,
<literal>bin</literal> and <literal>man</literal>,
<command>nix-build</command> will create symlinks
<literal>result</literal>, <literal>result-bin</literal> and
<literal>result-man</literal>.  It’s also possible to build a specific
output:
<screen>
$ nix-build '&lt;nixpkgs>' -A openssl.man
</screen>
This will create a symlink <literal>result-man</literal>.</para>

<para>Build a Nix expression given on the command line:

<screen>
$ nix-build -E 'with import &lt;nixpkgs> { }; runCommand "foo" { } "echo bar > $out"'
$ cat ./result
bar
</screen>

</para>

</refsection>


<refsection condition="manpage"><title>Environment variables</title>

<variablelist>
  <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" />
</variablelist>

</refsection>


</refentry>