diff options
author | David Arnold <dgx.arnold@gmail.com> | 2021-08-05 18:39:56 -0500 |
---|---|---|
committer | David Arnold <dgx.arnold@gmail.com> | 2021-08-05 18:53:59 -0500 |
commit | 2937038bf36a50993a7548e9ba805332db8a0910 (patch) | |
tree | 7c1effd33df5ac5031269ae46cb1412d7f3dfc09 /nixos | |
parent | 9e42d02047fe1153555f8c81039cb48135311e6d (diff) | |
download | nixpkgs-2937038bf36a50993a7548e9ba805332db8a0910.tar nixpkgs-2937038bf36a50993a7548e9ba805332db8a0910.tar.gz nixpkgs-2937038bf36a50993a7548e9ba805332db8a0910.tar.bz2 nixpkgs-2937038bf36a50993a7548e9ba805332db8a0910.tar.lz nixpkgs-2937038bf36a50993a7548e9ba805332db8a0910.tar.xz nixpkgs-2937038bf36a50993a7548e9ba805332db8a0910.tar.zst nixpkgs-2937038bf36a50993a7548e9ba805332db8a0910.zip |
lib/modules: add mkImageMediaOverride docs
Diffstat (limited to 'nixos')
-rw-r--r-- | nixos/doc/manual/development/building-nixos.chapter.md | 40 | ||||
-rw-r--r-- | nixos/doc/manual/from_md/development/building-nixos.chapter.xml | 85 |
2 files changed, 96 insertions, 29 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. 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 ceb744447da..ad9349da068 100644 --- a/nixos/doc/manual/from_md/development/building-nixos.chapter.xml +++ b/nixos/doc/manual/from_md/development/building-nixos.chapter.xml @@ -1,33 +1,72 @@ -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-building-cd"> - <title>Building Your Own NixOS CD</title> +<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> - Building a NixOS CD is as easy as configuring your own computer. The - idea is to use another module which will replace your - <literal>configuration.nix</literal> to configure the system that - would be installed on the CD. + 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> - Default CD/DVD configurations are available inside - <literal>nixos/modules/installer/cd-dvd</literal> + You have two options: </para> - <programlisting> + <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> - Before burning your CD/DVD, you can check the content of the image - by mounting anywhere like suggested by the following command: - </para> - <programlisting> -# mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen> + <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> - <para> - If you want to customize your NixOS CD in more detail, or generate - other kinds of images, you might want to check out - <link xlink:href="https://github.com/nix-community/nixos-generators">nixos-generators</link>. - This can also be a good starting point when you want to use Nix to - build a <quote>minimal</quote> image that doesn’t include a NixOS - installation. - </para> + </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> |