diff options
Diffstat (limited to 'nixpkgs/nixos/doc/manual/from_md/installation/building-nixos.chapter.xml')
| -rw-r--r-- | nixpkgs/nixos/doc/manual/from_md/installation/building-nixos.chapter.xml | 111 |
1 files changed, 111 insertions, 0 deletions
diff --git a/nixpkgs/nixos/doc/manual/from_md/installation/building-nixos.chapter.xml b/nixpkgs/nixos/doc/manual/from_md/installation/building-nixos.chapter.xml new file mode 100644 index 000000000000..ea2d01bebcc2 --- /dev/null +++ b/nixpkgs/nixos/doc/manual/from_md/installation/building-nixos.chapter.xml @@ -0,0 +1,111 @@ +<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> + <para> + To build an ISO image for the channel + <literal>nixos-unstable</literal>: + </para> + <programlisting> +$ git clone https://github.com/NixOS/nixpkgs.git +$ cd nixpkgs/nixos +$ git switch nixos-unstable +$ 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-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 = [ "wl" ]; + + boot.kernelModules = [ "kvm-intel" "wl" ]; + 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"> + <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> |