pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-building-parts">
2 <title>Building Specific Parts of NixOS</title>
3 <para>
4 With the command <literal>nix-build</literal>, you can build
5 specific parts of your NixOS configuration. This is done as follows:
6 </para>
7 <programlisting>
8$ cd /path/to/nixpkgs/nixos
9$ nix-build -A config.option
10</programlisting>
11 <para>
12 where <literal>option</literal> is a NixOS option with type
13 <quote>derivation</quote> (i.e. something that can be built).
14 Attributes of interest include:
15 </para>
16 <variablelist>
17 <varlistentry>
18 <term>
19 <literal>system.build.toplevel</literal>
20 </term>
21 <listitem>
22 <para>
23 The top-level option that builds the entire NixOS system.
24 Everything else in your configuration is indirectly pulled in
25 by this option. This is what <literal>nixos-rebuild</literal>
26 builds and what <literal>/run/current-system</literal> points
27 to afterwards.
28 </para>
29 <para>
30 A shortcut to build this is:
31 </para>
32 <programlisting>
33$ nix-build -A system
34</programlisting>
35 </listitem>
36 </varlistentry>
37 <varlistentry>
38 <term>
39 <literal>system.build.manual.manualHTML</literal>
40 </term>
41 <listitem>
42 <para>
43 The NixOS manual.
44 </para>
45 </listitem>
46 </varlistentry>
47 <varlistentry>
48 <term>
49 <literal>system.build.etc</literal>
50 </term>
51 <listitem>
52 <para>
53 A tree of symlinks that form the static parts of
54 <literal>/etc</literal>.
55 </para>
56 </listitem>
57 </varlistentry>
58 <varlistentry>
59 <term>
60 <literal>system.build.initialRamdisk</literal> ,
61 <literal>system.build.kernel</literal>
62 </term>
63 <listitem>
64 <para>
65 The initial ramdisk and kernel of the system. This allows a
66 quick way to test whether the kernel and the initial ramdisk
67 boot correctly, by using QEMU’s <literal>-kernel</literal> and
68 <literal>-initrd</literal> options:
69 </para>
70 <programlisting>
71$ nix-build -A config.system.build.initialRamdisk -o initrd
72$ nix-build -A config.system.build.kernel -o kernel
73$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null
74</programlisting>
75 </listitem>
76 </varlistentry>
77 <varlistentry>
78 <term>
79 <literal>system.build.nixos-rebuild</literal> ,
80 <literal>system.build.nixos-install</literal> ,
81 <literal>system.build.nixos-generate-config</literal>
82 </term>
83 <listitem>
84 <para>
85 These build the corresponding NixOS commands.
86 </para>
87 </listitem>
88 </varlistentry>
89 <varlistentry>
90 <term>
91 <literal>systemd.units.unit-name.unit</literal>
92 </term>
93 <listitem>
94 <para>
95 This builds the unit with the specified name. Note that since
96 unit names contain dots (e.g.
97 <literal>httpd.service</literal>), you need to put them
98 between quotes, like this:
99 </para>
100 <programlisting>
101$ nix-build -A 'config.systemd.units."httpd.service".unit'
102</programlisting>
103 <para>
104 You can also test individual units, without rebuilding the
105 whole system, by putting them in
106 <literal>/run/systemd/system</literal>:
107 </para>
108 <programlisting>
109$ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \
110 /run/systemd/system/tmp-httpd.service
111# systemctl daemon-reload
112# systemctl start tmp-httpd.service
113</programlisting>
114 <para>
115 Note that the unit must not have the same name as any unit in
116 <literal>/etc/systemd/system</literal> since those take
117 precedence over <literal>/run/systemd/system</literal>. That’s
118 why the unit is installed as
119 <literal>tmp-httpd.service</literal> here.
120 </para>
121 </listitem>
122 </varlistentry>
123 </variablelist>
124</chapter>