lib/modules: add mkImageMediaOverride docs

1 files changed, 34 insertions, 6 deletions

diff --git a/nixos/doc/manual/development/building-nixos.chapter.md b/nixos/doc/manual/development/building-nixos.chapter.md
index 699a75f4115..3310dee98f9 100644
--- a/nixos/doc/manual/development/building-nixos.chapter.md
+++ b/nixos/doc/manual/development/building-nixos.chapter.md
@@ -1,7 +1,22 @@
-# Building Your Own NixOS CD {#sec-building-cd}
-Building a NixOS CD is as easy as configuring your own computer. The idea is to use another module which will replace your `configuration.nix` to configure the system that would be installed on the CD.
+# Building a NixOS (Live) ISO {#sec-building-image}
 
-Default CD/DVD configurations are available inside `nixos/modules/installer/cd-dvd`
+Default live installer configurations are available inside `nixos/modules/installer/cd-dvd`.
+For building other system images, [nixos-generators] is a good place to start looking at.
+
+You have two options:
+
+- Use any of those default configurations as is
+- Combine them with (any of) your host config(s)
+
+System images, such as the live installer ones, know how to enforce configuration settings
+on wich they immediately depend in order to work correctly.
+
+However, if you are confident, you can opt to override those
+enforced values with `mkForce`.
+
+[nixos-generators]: https://github.com/nix-community/nixos-generators
+
+## Practical Instructions {#sec-building-image-instructions}
 
 ```ShellSession
 $ git clone https://github.com/NixOS/nixpkgs.git
@@ -9,10 +24,23 @@ $ cd nixpkgs/nixos
 $ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix
 ```
 
-Before burning your CD/DVD, you can check the content of the image by mounting anywhere like suggested by the following command:
+To check the content of an ISO image, mount it like so:
 
 ```ShellSession
-# mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen>
+# mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso
 ```
 
-If you want to customize your NixOS CD in more detail, or generate other kinds of images, you might want to check out [nixos-generators](https://github.com/nix-community/nixos-generators). This can also be a good starting point when you want to use Nix to build a 'minimal' image that doesn't include a NixOS installation.
+## Technical Notes {#sec-building-image-tech-notes}
+
+The config value enforcement is implemented via `mkImageMediaOverride = mkOverride 60;`
+and therefore primes over simple value assignments, but also yields to `mkForce`.
+
+This property allows image designers to implement in semantically correct ways those
+configuration values upon which the correct functioning of the image depends.
+
+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.