From 9ff1ab4037e2c20bb4ff11af452e4321d17edc99 Mon Sep 17 00:00:00 2001
From: Florian Klink <flokli@flokli.de>
Date: Mon, 11 Apr 2022 20:54:10 +0200
Subject: [PATCH] nixos/doc: add notes on additional drivers or firmware

This describes how to build your own installer medium with some custom
firmware/drivers, using an Intel MacBook as an example - on which WiFi
doesn't work out of the box, due to it being nonfree.

Fixes #15162.

Co-authored-by: Lucas Hoffmann <lucc@users.noreply.github.com>
Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
---
 .../development/building-nixos.chapter.md     | 31 +++++++++++++++++
 .../development/building-nixos.chapter.xml    | 34 +++++++++++++++++++
 2 files changed, 65 insertions(+)

diff --git a/nixos/doc/manual/development/building-nixos.chapter.md b/nixos/doc/manual/development/building-nixos.chapter.md
index 3310dee98f9..27d7e1d3855 100644
--- a/nixos/doc/manual/development/building-nixos.chapter.md
+++ b/nixos/doc/manual/development/building-nixos.chapter.md
@@ -30,6 +30,37 @@ To check the content of an ISO image, mount it like so:
 # mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso
 ```
 
+## Additional drivers or firmware {#sec-building-image-drivers}
+
+If you need additional (non-distributable) drivers or firmware in the
+installer, you might want to extend these configurations.
+
+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 `modules/installer/cd-dvd/installation-cd-graphical-gnome-macbook.nix`:
+
+```nix
+{ config, ... }:
+
+{
+  imports = [ ./installation-cd-graphical-gnome.nix ];
+
+  boot.initrd.kernelModules = [ "wl" ];
+
+  boot.kernelModules = [ "kvm-intel" "wl" ];
+  boot.extraModulePackages = [ config.boot.kernelPackages.broadcom_sta ];
+}
+```
+
+Then build it like in the example above:
+
+```ShellSession
+$ 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
+```
+
 ## Technical Notes {#sec-building-image-tech-notes}
 
 The config value enforcement is implemented via `mkImageMediaOverride = mkOverride 60;`
diff --git a/nixos/doc/manual/from_md/development/building-nixos.chapter.xml b/nixos/doc/manual/from_md/development/building-nixos.chapter.xml
index ad9349da068..e7a76a6d715 100644
--- a/nixos/doc/manual/from_md/development/building-nixos.chapter.xml
+++ b/nixos/doc/manual/from_md/development/building-nixos.chapter.xml
@@ -43,6 +43,40 @@ $ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd
     </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">