path: root/nixos/doc/manual/from_md/development/building-parts.chapter.xml

<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-building-parts">
  <title>Building Specific Parts of NixOS</title>
  <para>
    With the command <literal>nix-build</literal>, you can build
    specific parts of your NixOS configuration. This is done as follows:
  </para>
  <programlisting>
$ cd /path/to/nixpkgs/nixos
$ nix-build -A config.option
</programlisting>
  <para>
    where <literal>option</literal> is a NixOS option with type
    <quote>derivation</quote> (i.e. something that can be built).
    Attributes of interest include:
  </para>
  <variablelist>
    <varlistentry>
      <term>
        <literal>system.build.toplevel</literal>
      </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 <literal>nixos-rebuild</literal>
          builds and what <literal>/run/current-system</literal> points
          to afterwards.
        </para>
        <para>
          A shortcut to build this is:
        </para>
        <programlisting>
$ nix-build -A system
</programlisting>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <literal>system.build.manual.manualHTML</literal>
      </term>
      <listitem>
        <para>
          The NixOS manual.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <literal>system.build.etc</literal>
      </term>
      <listitem>
        <para>
          A tree of symlinks that form the static parts of
          <literal>/etc</literal>.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <literal>system.build.initialRamdisk</literal> ,
        <literal>system.build.kernel</literal>
      </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 <literal>-kernel</literal> and
          <literal>-initrd</literal> options:
        </para>
        <programlisting>
$ 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
</programlisting>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <literal>system.build.nixos-rebuild</literal> ,
        <literal>system.build.nixos-install</literal> ,
        <literal>system.build.nixos-generate-config</literal>
      </term>
      <listitem>
        <para>
          These build the corresponding NixOS commands.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <literal>systemd.units.unit-name.unit</literal>
      </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:
        </para>
        <programlisting>
$ nix-build -A 'config.systemd.units.&quot;httpd.service&quot;.unit'
</programlisting>
        <para>
          You can also test individual units, without rebuilding the
          whole system, by putting them in
          <literal>/run/systemd/system</literal>:
        </para>
        <programlisting>
$ cp $(nix-build -A 'config.systemd.units.&quot;httpd.service&quot;.unit')/httpd.service \
    /run/systemd/system/tmp-httpd.service
# systemctl daemon-reload
# systemctl start tmp-httpd.service
</programlisting>
        <para>
          Note that the unit must not have the same name as any unit in
          <literal>/etc/systemd/system</literal> since those take
          precedence over <literal>/run/systemd/system</literal>. That’s
          why the unit is installed as
          <literal>tmp-httpd.service</literal> here.
        </para>
      </listitem>
    </varlistentry>
  </variablelist>
</chapter>