commit 2937038bf36a50993a7548e9ba805332db8a0910 · pyrox.dev/nixpkgs

+34 -6

nixos/doc/manual/development/building-nixos.chapter.md

···

       1
       1
       -
       # Building Your Own NixOS CD {#sec-building-cd}

     

       2
       2
       -
       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.

     

       1
       1
       +
       # Building a NixOS (Live) ISO {#sec-building-image}

     

       3
       2
        
       

     

       4
       4
       -
       Default CD/DVD configurations are available inside `nixos/modules/installer/cd-dvd`

     

       3
       3
       +
       Default live installer configurations are available inside `nixos/modules/installer/cd-dvd`.

     

       4
       4
       +
       For building other system images, [nixos-generators] is a good place to start looking at.

     

       5
       5
       +
       

     

       6
       6
       +
       You have two options:

     

       7
       7
       +
       

     

       8
       8
       +
       - Use any of those default configurations as is

     

       9
       9
       +
       - Combine them with (any of) your host config(s)

     

       10
       10
       +
       

     

       11
       11
       +
       System images, such as the live installer ones, know how to enforce configuration settings

     

       12
       12
       +
       on wich they immediately depend in order to work correctly.

     

       13
       13
       +
       

     

       14
       14
       +
       However, if you are confident, you can opt to override those

     

       15
       15
       +
       enforced values with `mkForce`.

     

       16
       16
       +
       

     

       17
       17
       +
       [nixos-generators]: https://github.com/nix-community/nixos-generators

     

       18
       18
       +
       

     

       19
       19
       +
       ## Practical Instructions {#sec-building-image-instructions}

     

       5
       20
        
       

     

       6
       21
        
       ```ShellSession

     

       7
       22
        
       $ git clone https://github.com/NixOS/nixpkgs.git

     
···

       9
       24
        
       $ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix

     

       10
       25
        
       ```

     

       11
       26
        
       

     

       12
       12
       -
       Before burning your CD/DVD, you can check the content of the image by mounting anywhere like suggested by the following command:

     

       27
       27
       +
       To check the content of an ISO image, mount it like so:

     

       13
       28
        
       

     

       14
       29
        
       ```ShellSession

     

       15
       15
       -
       # mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen>

     

       30
       30
       +
       # mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso

     

       16
       31
        
       ```

     

       17
       32
        
       

     

       18
       18
       -
       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.

     

       33
       33
       +
       ## Technical Notes {#sec-building-image-tech-notes}

     

       34
       34
       +
       

     

       35
       35
       +
       The config value enforcement is implemented via `mkImageMediaOverride = mkOverride 60;`

     

       36
       36
       +
       and therefore primes over simple value assignments, but also yields to `mkForce`.

     

       37
       37
       +
       

     

       38
       38
       +
       This property allows image designers to implement in semantically correct ways those

     

       39
       39
       +
       configuration values upon which the correct functioning of the image depends.

     

       40
       40
       +
       

     

       41
       41
       +
       For example, the iso base image overrides those file systems which it needs at a minimum

     

       42
       42
       +
       for correct functioning, while the installer base image overrides the entire file system

     

       43
       43
       +
       layout because there can't be any other guarantees on a live medium than those given

     

       44
       44
       +
       by the live medium itself. The latter is especially true befor formatting the target

     

       45
       45
       +
       block device(s). On the other hand, the netboot iso only overrides its minimum dependencies

     

       46
       46
       +
       since netboot images are always made-to-target.

+62 -23

nixos/doc/manual/from_md/development/building-nixos.chapter.xml

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-building-cd">

     

       2
       2
       -
         <title>Building Your Own NixOS CD</title>

     

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-building-image">

     

       2
       2
       +
         <title>Building a NixOS (Live) ISO</title>

     

       3
       3
       +
         <para>

     

       4
       4
       +
           Default live installer configurations are available inside

     

       5
       5
       +
           <literal>nixos/modules/installer/cd-dvd</literal>. For building

     

       6
       6
       +
           other system images,

     

       7
       7
       +
           <link xlink:href="https://github.com/nix-community/nixos-generators">nixos-generators</link>

     

       8
       8
       +
           is a good place to start looking at.

     

       9
       9
       +
         </para>

     

       10
       10
       +
         <para>

     

       11
       11
       +
           You have two options:

     

       12
       12
       +
         </para>

     

       13
       13
       +
         <itemizedlist spacing="compact">

     

       14
       14
       +
           <listitem>

     

       15
       15
       +
             <para>

     

       16
       16
       +
               Use any of those default configurations as is

     

       17
       17
       +
             </para>

     

       18
       18
       +
           </listitem>

     

       19
       19
       +
           <listitem>

     

       20
       20
       +
             <para>

     

       21
       21
       +
               Combine them with (any of) your host config(s)

     

       22
       22
       +
             </para>

     

       23
       23
       +
           </listitem>

     

       24
       24
       +
         </itemizedlist>

     

       3
       25
        
         <para>

     

       4
       4
       -
           Building a NixOS CD is as easy as configuring your own computer. The

     

       5
       5
       -
           idea is to use another module which will replace your

     

       6
       6
       -
           <literal>configuration.nix</literal> to configure the system that

     

       7
       7
       -
           would be installed on the CD.

     

       26
       26
       +
           System images, such as the live installer ones, know how to enforce

     

       27
       27
       +
           configuration settings on wich they immediately depend in order to

     

       28
       28
       +
           work correctly.

     

       8
       29
        
         </para>

     

       9
       30
        
         <para>

     

       10
       10
       -
           Default CD/DVD configurations are available inside

     

       11
       11
       -
           <literal>nixos/modules/installer/cd-dvd</literal>

     

       31
       31
       +
           However, if you are confident, you can opt to override those

     

       32
       32
       +
           enforced values with <literal>mkForce</literal>.

     

       12
       33
        
         </para>

     

       13
       13
       -
         <programlisting>

     

       34
       34
       +
         <section xml:id="sec-building-image-instructions">

     

       35
       35
       +
           <title>Practical Instructions</title>

     

       36
       36
       +
           <programlisting>

     

       14
       37
        
       $ git clone https://github.com/NixOS/nixpkgs.git

     

       15
       38
        
       $ cd nixpkgs/nixos

     

       16
       39
        
       $ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix

     

       17
       40
        
       </programlisting>

     

       18
       18
       -
         <para>

     

       19
       19
       -
           Before burning your CD/DVD, you can check the content of the image

     

       20
       20
       -
           by mounting anywhere like suggested by the following command:

     

       21
       21
       -
         </para>

     

       22
       22
       -
         <programlisting>

     

       23
       23
       -
       # mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso&lt;/screen&gt;

     

       41
       41
       +
           <para>

     

       42
       42
       +
             To check the content of an ISO image, mount it like so:

     

       43
       43
       +
           </para>

     

       44
       44
       +
           <programlisting>

     

       45
       45
       +
       # mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso

     

       24
       46
        
       </programlisting>

     

       25
       25
       -
         <para>

     

       26
       26
       -
           If you want to customize your NixOS CD in more detail, or generate

     

       27
       27
       -
           other kinds of images, you might want to check out

     

       28
       28
       -
           <link xlink:href="https://github.com/nix-community/nixos-generators">nixos-generators</link>.

     

       29
       29
       -
           This can also be a good starting point when you want to use Nix to

     

       30
       30
       -
           build a <quote>minimal</quote> image that doesn’t include a NixOS

     

       31
       31
       -
           installation.

     

       32
       32
       -
         </para>

     

       47
       47
       +
         </section>

     

       48
       48
       +
         <section xml:id="sec-building-image-tech-notes">

     

       49
       49
       +
           <title>Technical Notes</title>

     

       50
       50
       +
           <para>

     

       51
       51
       +
             The config value enforcement is implemented via

     

       52
       52
       +
             <literal>mkImageMediaOverride = mkOverride 60;</literal> and

     

       53
       53
       +
             therefore primes over simple value assignments, but also yields to

     

       54
       54
       +
             <literal>mkForce</literal>.

     

       55
       55
       +
           </para>

     

       56
       56
       +
           <para>

     

       57
       57
       +
             This property allows image designers to implement in semantically

     

       58
       58
       +
             correct ways those configuration values upon which the correct

     

       59
       59
       +
             functioning of the image depends.

     

       60
       60
       +
           </para>

     

       61
       61
       +
           <para>

     

       62
       62
       +
             For example, the iso base image overrides those file systems which

     

       63
       63
       +
             it needs at a minimum for correct functioning, while the installer

     

       64
       64
       +
             base image overrides the entire file system layout because there

     

       65
       65
       +
             can’t be any other guarantees on a live medium than those given by

     

       66
       66
       +
             the live medium itself. The latter is especially true befor

     

       67
       67
       +
             formatting the target block device(s). On the other hand, the

     

       68
       68
       +
             netboot iso only overrides its minimum dependencies since netboot

     

       69
       69
       +
             images are always made-to-target.

     

       70
       70
       +
           </para>

     

       71
       71
       +
         </section>

     

       33
       72
        
       </chapter>