16.2 Instantiate an Image

Let’s say you would like to create an MBR image with three distinct partitions:

• The ESP (EFI System Partition), a partition of 40 MiB at offset 1024 KiB with a vfat file system.
• an ext4 partition of 50 MiB data file, and labeled “data”.
• an ext4 bootable partition containing the %simple-os operating-system.

You would then write the following image definition in a my-image.scm file for instance.

(use-modules (gnu)
             (gnu image)
             (gnu tests)
             (gnu system image)
             (guix gexp))

(define MiB (expt 2 20))

(image
 (format 'disk-image)
 (operating-system %simple-os)
 (partitions
  (list
   (partition
    (size (* 40 MiB))
    (offset (* 1024 1024))
    (label "GNU-ESP")
    (file-system "vfat")
    (flags '(esp))
    (initializer (gexp initialize-efi-partition)))
   (partition
    (size (* 50 MiB))
    (label "DATA")
    (file-system "ext4")
    (initializer #~(lambda* (root . rest)
                     (mkdir root)
                     (call-with-output-file
                         (string-append root "/data")
                       (lambda (port)
                         (format port "my-data"))))))
   (partition
    (size 'guess)
    (label root-label)
    (file-system "ext4")
    (flags '(boot))
    (initializer (gexp initialize-root-partition))))))

Note that the first and third partitions use generic initializers procedures, initialize-efi-partition and initialize-root-partition respectively. The initialize-efi-partition installs a GRUB EFI loader that is loading the GRUB bootloader located in the root partition. The initialize-root-partition instantiates a complete system as defined by the %simple-os operating-system.

You can now run:

guix system image my-image.scm

to instantiate the image definition. That produces a disk image which has the expected structure:

$ parted $(guix system image my-image.scm) print
…
Model:  (file)
Disk /gnu/store/yhylv1bp5b2ypb97pd3bbhz6jk5nbhxw-disk-image: 1714MB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Disk Flags:

Number  Start   End     Size    Type     File system  Flags
 1      1049kB  43.0MB  41.9MB  primary  fat16        esp
 2      43.0MB  95.4MB  52.4MB  primary  ext4
 3      95.4MB  1714MB  1619MB  primary  ext4         boot

The size of the boot partition has been inferred to 1619MB so that it is large enough to host the %simple-os operating-system.

You can also use existing image record definitions and inherit from them to simplify the image definition. The (gnu system image) module provides the following image definition variables.

Scheme Variable: efi-disk-image

A MBR disk-image composed of two partitions: a 64 bits ESP partition and a ROOT boot partition. This image can be used on most x86_64 and i686 machines, supporting BIOS or UEFI booting.

Scheme Variable: efi32-disk-image

Same as efi-disk-image but with a 32 bits EFI partition.

Scheme Variable: iso9660-image

An ISO-9660 image composed of a single bootable partition. This image can also be used on most x86_64 and i686 machines.

Scheme Variable: docker-image

A Docker image that can be used to spawn a Docker container.

Using the efi-disk-image we can simplify our previous image declaration this way:

(use-modules (gnu)
             (gnu image)
             (gnu tests)
             (gnu system image)
             (guix gexp)
             (ice-9 match))

(define MiB (expt 2 20))

(define data
  (partition
   (size (* 50 MiB))
   (label "DATA")
   (file-system "ext4")
   (initializer #~(lambda* (root . rest)
                    (mkdir root)
                    (call-with-output-file
                        (string-append root "/data")
                      (lambda (port)
                        (format port "my-data")))))))

(image
 (inherit efi-disk-image)
 (operating-system %simple-os)
 (partitions
  (match (image-partitions efi-disk-image)
    ((esp root)
     (list esp data root)))))

This will give the exact same image instantiation but the image declaration is simpler.