lib/modules: add mkImageMediaOverride docs
This commit is contained in:
David Arnold
parent
9e42d02047
commit
2937038bf3
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue