<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-building-image">
  <title>Building a NixOS (Live) ISO</title>
  <para>
    Default live installer configurations are available inside
    <literal>nixos/modules/installer/cd-dvd</literal>. For building
    other system images,
    <link xlink:href="https://github.com/nix-community/nixos-generators">nixos-generators</link>
    is a good place to start looking at.
  </para>
  <para>
    You have two options:
  </para>
  <itemizedlist spacing="compact">
    <listitem>
      <para>
        Use any of those default configurations as is
      </para>
    </listitem>
    <listitem>
      <para>
        Combine them with (any of) your host config(s)
      </para>
    </listitem>
  </itemizedlist>
  <para>
    System images, such as the live installer ones, know how to enforce
    configuration settings on wich they immediately depend in order to
    work correctly.
  </para>
  <para>
    However, if you are confident, you can opt to override those
    enforced values with <literal>mkForce</literal>.
  </para>
  <section xml:id="sec-building-image-instructions">
    <title>Practical Instructions</title>
    <para>
      To build an ISO image for the channel
      <literal>nixos-unstable</literal>:
    </para>
    <programlisting>
$ git clone https://github.com/NixOS/nixpkgs.git
$ cd nixpkgs/nixos
$ git switch nixos-unstable
$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix
</programlisting>
    <para>
      To check the content of an ISO image, mount it like so:
    </para>
    <programlisting>
# mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso
</programlisting>
  </section>
  <section xml:id="sec-building-image-drivers">
    <title>Additional drivers or firmware</title>
    <para>
      If you need additional (non-distributable) drivers or firmware in
      the installer, you might want to extend these configurations.
    </para>
    <para>
      For example, to build the GNOME graphical installer ISO, but with
      support for certain WiFi adapters present in some MacBooks, you
      can create the following file at
      <literal>modules/installer/cd-dvd/installation-cd-graphical-gnome-macbook.nix</literal>:
    </para>
    <programlisting language="bash">
{ config, ... }:

{
  imports = [ ./installation-cd-graphical-gnome.nix ];

  boot.initrd.kernelModules = [ &quot;wl&quot; ];

  boot.kernelModules = [ &quot;kvm-intel&quot; &quot;wl&quot; ];
  boot.extraModulePackages = [ config.boot.kernelPackages.broadcom_sta ];
}
</programlisting>
    <para>
      Then build it like in the example above:
    </para>
    <programlisting>
$ git clone https://github.com/NixOS/nixpkgs.git
$ cd nixpkgs/nixos
$ export NIXPKGS_ALLOW_UNFREE=1
$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-graphical-gnome-macbook.nix default.nix
</programlisting>
  </section>
  <section xml:id="sec-building-image-tech-notes">
    <title>Technical Notes</title>
    <para>
      The config value enforcement is implemented via
      <literal>mkImageMediaOverride = mkOverride 60;</literal> and
      therefore primes over simple value assignments, but also yields to
      <literal>mkForce</literal>.
    </para>
    <para>
      This property allows image designers to implement in semantically
      correct ways those configuration values upon which the correct
      functioning of the image depends.
    </para>
    <para>
      For example, the iso base image overrides those file systems which
      it needs at a minimum for correct functioning, while the installer
      base image overrides the entire file system layout because there
      can’t be any other guarantees on a live medium than those given by
      the live medium itself. The latter is especially true befor
      formatting the target block device(s). On the other hand, the
      netboot iso only overrides its minimum dependencies since netboot
      images are always made-to-target.
    </para>
  </section>
</chapter>
