diff options
Diffstat (limited to 'nixos/doc/manual/development/building-parts.xml')
| -rw-r--r-- | nixos/doc/manual/development/building-parts.xml | 113 |
1 files changed, 113 insertions, 0 deletions
diff --git a/nixos/doc/manual/development/building-parts.xml b/nixos/doc/manual/development/building-parts.xml new file mode 100644 index 000000000000..cb8dee039c8e --- /dev/null +++ b/nixos/doc/manual/development/building-parts.xml @@ -0,0 +1,113 @@ +<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-building-parts"> + +<title>Building Specific Parts of NixOS</title> + +<para>With the command <command>nix-build</command>, you can build +specific parts of your NixOS configuration. This is done as follows: + +<screen> +$ cd <replaceable>/path/to/nixpkgs/nixos</replaceable> +$ nix-build -A config.<replaceable>option</replaceable></screen> + +where <replaceable>option</replaceable> is a NixOS option with type +“derivation” (i.e. something that can be built). Attributes of +interest include: + +<variablelist> + + <varlistentry> + <term><varname>system.build.toplevel</varname></term> + <listitem> + <para>The top-level option that builds the entire NixOS system. + Everything else in your configuration is indirectly pulled in by + this option. This is what <command>nixos-rebuild</command> + builds and what <filename>/run/current-system</filename> points + to afterwards.</para> + + <para>A shortcut to build this is: + +<screen> +$ nix-build -A system</screen> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>system.build.manual.manual</varname></term> + <listitem><para>The NixOS manual.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>system.build.etc</varname></term> + <listitem><para>A tree of symlinks that form the static parts of + <filename>/etc</filename>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>system.build.initialRamdisk</varname></term> + <term><varname>system.build.kernel</varname></term> + <listitem> + <para>The initial ramdisk and kernel of the system. This allows + a quick way to test whether the kernel and the initial ramdisk + boot correctly, by using QEMU’s <option>-kernel</option> and + <option>-initrd</option> options: + +<screen> +$ nix-build -A config.system.build.initialRamdisk -o initrd +$ nix-build -A config.system.build.kernel -o kernel +$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null +</screen> + + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>system.build.nixos-rebuild</varname></term> + <term><varname>system.build.nixos-install</varname></term> + <term><varname>system.build.nixos-generate-config</varname></term> + <listitem> + <para>These build the corresponding NixOS commands.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.units.<replaceable>unit-name</replaceable>.unit</varname></term> + <listitem> + <para>This builds the unit with the specified name. Note that + since unit names contain dots + (e.g. <literal>httpd.service</literal>), you need to put them + between quotes, like this: + +<screen> +$ nix-build -A 'config.systemd.units."httpd.service".unit' +</screen> + + You can also test individual units, without rebuilding the whole + system, by putting them in + <filename>/run/systemd/system</filename>: + +<screen> +$ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \ + /run/systemd/system/tmp-httpd.service +$ systemctl daemon-reload +$ systemctl start tmp-httpd.service +</screen> + + Note that the unit must not have the same name as any unit in + <filename>/etc/systemd/system</filename> since those take + precedence over <filename>/run/systemd/system</filename>. + That’s why the unit is installed as + <filename>tmp-httpd.service</filename> here.</para> + </listitem> + </varlistentry> + +</variablelist> + +</para> + +</chapter> \ No newline at end of file |