1 files changed, 72 insertions, 0 deletions
diff --git a/nixos/doc/manual/from_md/development/building-nixos.chapter.xml b/nixos/doc/manual/from_md/development/building-nixos.chapter.xml
new file mode 100644
index 00000000000..ad9349da068
--- /dev/null
+++ b/nixos/doc/manual/from_md/development/building-nixos.chapter.xml
@@ -0,0 +1,72 @@
+<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>
+    <programlisting>
+$ git clone https://github.com/NixOS/nixpkgs.git
+$ cd nixpkgs/nixos
+$ 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-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>