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

<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>
      <group choice='req'>
        <arg choice='plain'><option>--attr</option></arg>
        <arg choice='plain'><option>-A</option></arg>
      </group>
      <replaceable>attrPath</replaceable>
    </arg>
    <arg><option>--add-drv-link</option></arg>
    <arg><option>--drv-link </option><replaceable>drvlink</replaceable></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>See also <xref linkend="sec-common-options" />.  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>.</para>

<variablelist>

  <varlistentry><term><option>--add-drv-link</option></term>
  
    <listitem><para>Add a symlink in the current directory to the
    store derivation produced by <command>nix-instantiate</command>.
    The symlink is called <filename>derivation</filename> (which is
    numbered in the case of multiple derivations).  The derivation is
    a root of the garbage collector until the symlink is deleted or
    renamed.</para></listitem>
    
  </varlistentry>

  <varlistentry><term><option>--drv-link</option> <replaceable>drvlink</replaceable></term>
  
    <listitem><para>Change the name of the symlink to the derivation
    created when <option>--add-drv-link</option> is used from
    <filename>derivation</filename> to
    <replaceable>drvlink</replaceable>.</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 unless <option>--no-out-link</option> is used from
    <filename>result</filename> to
    <replaceable>outlink</replaceable>.</para></listitem>

  </varlistentry>

</variablelist>

</refsection>


<refsection><title>Examples</title>

<screen>
$ nix-build pkgs/top-level/all-packages.nix -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>

</refsection>


</refentry>