pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-building-image">
2 <title>Building a NixOS (Live) ISO</title>
3 <para>
4 Default live installer configurations are available inside
5 <literal>nixos/modules/installer/cd-dvd</literal>. For building
6 other system images,
7 <link xlink:href="https://github.com/nix-community/nixos-generators">nixos-generators</link>
8 is a good place to start looking at.
9 </para>
10 <para>
11 You have two options:
12 </para>
13 <itemizedlist spacing="compact">
14 <listitem>
15 <para>
16 Use any of those default configurations as is
17 </para>
18 </listitem>
19 <listitem>
20 <para>
21 Combine them with (any of) your host config(s)
22 </para>
23 </listitem>
24 </itemizedlist>
25 <para>
26 System images, such as the live installer ones, know how to enforce
27 configuration settings on wich they immediately depend in order to
28 work correctly.
29 </para>
30 <para>
31 However, if you are confident, you can opt to override those
32 enforced values with <literal>mkForce</literal>.
33 </para>
34 <section xml:id="sec-building-image-instructions">
35 <title>Practical Instructions</title>
36 <para>
37 To build an ISO image for the channel
38 <literal>nixos-unstable</literal>:
39 </para>
40 <programlisting>
41$ git clone https://github.com/NixOS/nixpkgs.git
42$ cd nixpkgs/nixos
43$ git switch nixos-unstable
44$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix
45</programlisting>
46 <para>
47 To check the content of an ISO image, mount it like so:
48 </para>
49 <programlisting>
50# mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso
51</programlisting>
52 </section>
53 <section xml:id="sec-building-image-drivers">
54 <title>Additional drivers or firmware</title>
55 <para>
56 If you need additional (non-distributable) drivers or firmware in
57 the installer, you might want to extend these configurations.
58 </para>
59 <para>
60 For example, to build the GNOME graphical installer ISO, but with
61 support for certain WiFi adapters present in some MacBooks, you
62 can create the following file at
63 <literal>modules/installer/cd-dvd/installation-cd-graphical-gnome-macbook.nix</literal>:
64 </para>
65 <programlisting language="bash">
66{ config, ... }:
67
68{
69 imports = [ ./installation-cd-graphical-gnome.nix ];
70
71 boot.initrd.kernelModules = [ "wl" ];
72
73 boot.kernelModules = [ "kvm-intel" "wl" ];
74 boot.extraModulePackages = [ config.boot.kernelPackages.broadcom_sta ];
75}
76</programlisting>
77 <para>
78 Then build it like in the example above:
79 </para>
80 <programlisting>
81$ git clone https://github.com/NixOS/nixpkgs.git
82$ cd nixpkgs/nixos
83$ export NIXPKGS_ALLOW_UNFREE=1
84$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-graphical-gnome-macbook.nix default.nix
85</programlisting>
86 </section>
87 <section xml:id="sec-building-image-tech-notes">
88 <title>Technical Notes</title>
89 <para>
90 The config value enforcement is implemented via
91 <literal>mkImageMediaOverride = mkOverride 60;</literal> and
92 therefore primes over simple value assignments, but also yields to
93 <literal>mkForce</literal>.
94 </para>
95 <para>
96 This property allows image designers to implement in semantically
97 correct ways those configuration values upon which the correct
98 functioning of the image depends.
99 </para>
100 <para>
101 For example, the iso base image overrides those file systems which
102 it needs at a minimum for correct functioning, while the installer
103 base image overrides the entire file system layout because there
104 can’t be any other guarantees on a live medium than those given by
105 the live medium itself. The latter is especially true befor
106 formatting the target block device(s). On the other hand, the
107 netboot iso only overrides its minimum dependencies since netboot
108 images are always made-to-target.
109 </para>
110 </section>
111</chapter>