diff options
author | Florian Klink <flokli@flokli.de> | 2022-04-16 15:19:03 +0200 |
---|---|---|
committer | Florian Klink <flokli@flokli.de> | 2022-04-16 15:19:03 +0200 |
commit | b2f53084006be15f213f87fd2fc1739899869016 (patch) | |
tree | b26f5289711c808f63bf843296e8e65fc1aba219 /nixos/doc/manual/installation | |
parent | b2383b63292ea4188b80e07988b9484d3620c74b (diff) |
nixos/doc: move "Building NixOS" into "Installation", not "Development"
This section mostly describes how to build various installer images, so it fits better in that chapter. Proposed in https://github.com/NixOS/nixpkgs/pull/168306#discussion_r848329534
Diffstat (limited to 'nixos/doc/manual/installation')
-rw-r--r-- | nixos/doc/manual/installation/building-nixos.chapter.md | 77 | ||||
-rw-r--r-- | nixos/doc/manual/installation/installation.xml | 1 |
2 files changed, 78 insertions, 0 deletions
diff --git a/nixos/doc/manual/installation/building-nixos.chapter.md b/nixos/doc/manual/installation/building-nixos.chapter.md new file mode 100644 index 0000000000000..27d7e1d385539 --- /dev/null +++ b/nixos/doc/manual/installation/building-nixos.chapter.md @@ -0,0 +1,77 @@ +# Building a NixOS (Live) ISO {#sec-building-image} + +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 +$ cd nixpkgs/nixos +$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix +``` + +To check the content of an ISO image, mount it like so: + +```ShellSession +# 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;` +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. diff --git a/nixos/doc/manual/installation/installation.xml b/nixos/doc/manual/installation/installation.xml index 1d443bbd0ee16..ba07d71d0ca35 100644 --- a/nixos/doc/manual/installation/installation.xml +++ b/nixos/doc/manual/installation/installation.xml @@ -14,4 +14,5 @@ <xi:include href="../from_md/installation/installing.chapter.xml" /> <xi:include href="../from_md/installation/changing-config.chapter.xml" /> <xi:include href="../from_md/installation/upgrading.chapter.xml" /> + <xi:include href="../from_md/installation/building-nixos.chapter.xml" /> </part> |