Copyright @copyright{} 2021 Alice Brenon@*
Copyright @copyright{} 2021, 2022 Josselin Poiret@*
Copyright @copyright{} 2021 muradm@*
-Copyright @copyright{} 2021 Andrew Tropin@*
+Copyright @copyright{} 2021, 2022 Andrew Tropin@*
Copyright @copyright{} 2021 Sarah Morgensen@*
Copyright @copyright{} 2022 Remco van 't Veer@*
Copyright @copyright{} 2022 Aleksandr Vityazev@*
Copyright @copyright{} 2022 Karl Hallsby@*
Copyright @copyright{} 2022 Justin Veilleux@*
Copyright @copyright{} 2022 Reily Siegel@*
+Copyright @copyright{} 2022 Simon Streit@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* System Configuration:: Configuring the operating system.
* Home Configuration:: Configuring the home environment.
* Documentation:: Browsing software user manuals.
+* Platforms:: Defining platforms.
+* System Images:: Creating system images.
* Installing Debugging Files:: Feeding the debugger.
* Using TeX and LaTeX:: Typesetting.
* Security Updates:: Deploying security fixes quickly.
* DNS Services:: DNS daemons.
* VPN Services:: VPN daemons.
* Network File System:: NFS related services.
+* Samba Services:: Samba services.
* Continuous Integration:: Cuirass and Laminar services.
* Power Management Services:: Extending battery life.
* Audio Services:: The MPD.
* Shepherd Services:: A particular type of service.
* Complex Configurations:: Defining bindings for complex configurations.
+Platforms
+
+* platform Reference:: Detail of platform declarations.
+* Supported Platforms:: Description of the supported platforms.
+
+System Images
+
+* image Reference:: Detail of image declarations.
+* Instantiate an Image:: How to instantiate an image record.
+* image-type Reference:: Detail of image types declaration.
+* Image Modules:: Definition of image modules.
+
Installing Debugging Files
* Separate Debug Info:: Installing 'debug' outputs.
guix import gem rails
@end example
+You can also ask for a specific version:
+
+@example
+guix import gem @@7.0.4
+@end example
+
@table @code
@item --recursive
@itemx -r
* DNS Services:: DNS daemons.
* VPN Services:: VPN daemons.
* Network File System:: NFS related services.
+* Samba Services:: Samba services.
* Continuous Integration:: Cuirass and Laminar services.
* Power Management Services:: Extending battery life.
* Audio Services:: The MPD.
@item @code{ignore-lid?} (default: @code{#f})
Ignore the lid state, this can be useful if it's incorrect on a device.
-@item @code{use-percentage-for-policy?} (default: @code{#f})
-Whether battery percentage based policy should be used. The default is to use
-the time left, change to @code{#t} to use the percentage.
+@item @code{use-percentage-for-policy?} (default: @code{#t})
+Whether a to use a policy based on battery percentage rather than on
+estimated time left. A policy based on battery percentage is usually
+more reliable.
@item @code{percentage-low} (default: @code{20})
When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
@item @code{nginx} (default: @code{nginx})
The nginx package to use.
+@item @code{shepherd-requirement} (default: @code{'()})
+This is a list of symbols naming Shepherd services the nginx service
+will depend on.
+
+This is useful if you would like @command{nginx} to be started after a
+back-end web server or a logging service such as Anonip has been
+started.
+
@item @code{log-directory} (default: @code{"/var/log/nginx"})
The directory to which NGinx will write log files.
@end table
@end deftp
+@node Samba Services, Continuous Integration, Network File System, Services
+@subsection Samba Services
+
+@cindex Samba
+@cindex SMB
+The @code{(gnu services samba)} module provides service definitions for
+Samba as well as additional helper services. Currently it provides the
+following services.
+
+@subsubheading Samba
+
+@uref{https://www.samba.org, Samba} provides network shares for folders
+and printers using the SMB/CIFS protocol commonly used on Windows. It
+can also act as an Active Directory Domain Controller (AD DC) for other
+hosts in an heterougenious network with different types of Computer
+systems.
+
+@defvar {Scheme variable} samba-service-type
+
+The service type to enable the samba services @code{samba}, @code{nmbd},
+@code{smbd} and @code{winbindd}. By default this service type does not
+run as an AD DC, hence @code{samba} remains disabled.
+
+@end defvar
+
+@deftp{Data Type} samba-service-configuration
+Configuration record for the Samba suite.
+
+@table @asis
+@item @code{package} (default: @code{samba})
+The samba package to use.
+
+@item @code{config-file} (default: @code{#f})
+The config file to use.
+
+@item @code{enable-samba?} (default: @code{#f})
+Manually enable the @code{samba} daemon.
+
+@item @code{enable-smbd?} (default: @code{#f})
+Manually enable the @code{smbd} daemon.
+
+@item @code{enable-nmbd?} (default: @code{#f})
+Manually enable the @code{nmbd} daemon.
+
+@item @code{enable-winbindd?} (default: @code{#f})
+Manually enable the @code{winbindd} daemon.
+
+@end table
+@end deftp
+
+@cindex wsdd
+@subsubheading Web Service Discovery Daemon
+
+Web Service Discovery Daemon implements
+@uref{http://docs.oasis-open.org/ws-dd/discovery/1.1/os/wsdd-discovery-1.1-spec-os.html,
+Web Services Dynamic Discovery} protocol that enables host discovery --
+similar to Avahi -- over Multicast DNS. It is a drop-in replacement for
+SMB hosts that have had SMBv1 disabled for security reasons.
+
+@defvr {Scheme Variable} wsdd-service-type
+
+Service type for the WSD host daemon. The value for
+this service type is a @code{wsdd-configuration} record. The details
+for the @code{wsdd-configuration} record type are given below.
+@end defvr
+
+@deftp{Data Type} wsdd-configuration This data type represents the
+configuration for the wsdd service.
+
+@table @asis
+
+@item @code{package} (default: @code{wsdd})
+The wsdd package to use.
+
+@item @code{ipv4only?} (default: @code{#f})
+Only listen to IPv4 addresses.
+
+@item @code{ipv6only} (default: @code{#f})
+Only listen to IPv6 addresses. Please note: Activating both options is
+not possible, since there would be no IP versions to listen to.
+
+@item @code{chroot} (default: @code{#f})
+Chroot into a separate directory to prevent access to other directories.
+This is to increase security in case there is a vulnerability in
+@command{wsdd}.
+
+@item @code{hop-limit} (default: @code{1})
+Limit to the level of hops for multicast packets. The default is
+@var{1} which should prevent packets from leaving the local network.
+
+@item @code{interface} (default: @code{'()})
+Limit to the given list of interfaces to listen to. By default wsdd
+will listen to all interfaces. Except the loopback interface is never
+used.
+
+@item @code{uuid-device} (default: @code{#f})
+The WSD protocol requires a device to have a UUID. Set this to manually
+assign the service a UUID.
+
+@item @code{domain} (default: @code{#f})
+Notify this host is a member of an Active Directory.
+
+@item @code{host-name} (default: @code{#f})
+Manually set the hostname rather than letting @command{wsdd} inherit
+this host's hostname. Only the host name part of a possible FQDN will
+be used in the default case.
+
+@item @code{preserve-case?} (default: @code{#f})
+By default @command{wsdd} will convert the hostname in workgroup to all
+uppercase. The opposite is true for hostnames in domains. Setting this
+parameter will preserve case.
+
+@item @code{workgroup} (default: @var{"WORKGROUP"})
+Change the name of the workgroup. By default @command{wsdd} reports
+this host being member of a workgroup.
+
+@end table
+@end deftp
+
@node Continuous Integration
@subsection Continuous Integration
@item @code{package} (default: @code{r-shiny})
The package to use.
-@item @code{binary} (defaunlt @code{"rshiny"})
+@item @code{binary} (default @code{"rshiny"})
The name of the binary or shell script located at @code{package/bin/} to
run when the service is run.
@item @code{extra-jails} (default: @code{()}) (type: list-of-fail2ban-jail-configurations)
Instances of @code{<fail2ban-jail-configuration>} explicitly provided.
-@item @code{extra-content} (type: maybe-string)
-Extra raw content to add to the end of the @file{jail.local} file.
+@item @code{extra-content} (default: @code{()}) (type: text-config)
+Extra raw content to add to the end of the @file{jail.local} file,
+provided as a list of file-like objects.
@end table
@item @code{action} (default: @code{()}) (type: list-of-fail2ban-jail-actions)
A list of @code{<fail2ban-jail-action-configuration>}.
-@item @code{extra-content} (type: maybe-string)
-Extra content for the jail configuration.
+@item @code{extra-content} (default: @code{()}) (type: text-config)
+Extra content for the jail configuration, provided as a list of file-like
+objects.
@end table
@dots{}))
@end lisp
+@item @code{chain-loader} (default: @code{#f})
+A string that can be accepted by @code{grub}'s @code{chainloader}
+directive. This has no effect if either @code{linux} or
+@code{multiboot-kernel} fields are specified. The following is an
+example of chainloading a different GNU/Linux system.
+
+@lisp
+(bootloader
+ (bootloader-configuration
+ ;; @dots{}
+ (menu-entries
+ (list
+ (menu-entry
+ (label "GNU/Linux")
+ (device (uuid "1C31-A17C" 'fat))
+ (chain-loader "/EFI/GNULinux/grubx64.efi"))))))
+@end lisp
+
@end table
@end deftp
bindings to navigate manuals. @xref{Getting Started,,, info, Info: An
Introduction}, for an introduction to Info navigation.
+@node Platforms
+@chapter Platforms
+
+The packages and systems built by Guix are intended, like most computer
+programs, to run on a CPU with a specific instruction set, and under a
+specific operating system. Those programs are often also targeting a
+specific kernel and system library. Those constraints are captured by
+Guix in @code{platform} records.
+
+@menu
+* platform Reference:: Detail of platform declarations.
+* Supported Platforms:: Description of the supported platforms.
+@end menu
+
+@node platform Reference
+@section @code{platform} Reference
+
+The @code{platform} data type describes a @dfn{platform}: an
+@acronym{ISA, instruction set architecture}, combined with an operating
+system and possibly additional system-wide settings such as the
+@acronym{ABI, application binary interface}.
+
+@deftp {Data Type} platform
+This is the data type representing a platform.
+
+@table @asis
+@item @code{target}
+This field specifies the platform's GNU triplet as a string
+(@pxref{Specifying Target Triplets, GNU configuration triplets,,
+autoconf, Autoconf}).
+
+@item @code{system}
+This string is the system type as it is known to Guix and passed,
+for instance, to the @option{--system} option of most commands.
+
+It usually has the form @code{"@var{cpu}-@var{kernel}"}, where
+@var{cpu} is the target CPU and @var{kernel} the target operating
+system kernel.
+
+It can be for instance @code{"aarch64-linux"} or @code{"armhf-linux"}.
+You will encounter system types when you perform native builds
+(@pxref{Native Builds}).
+
+@item @code{linux-architecture} (default: @code{#false})
+This optional string field is only relevant if the kernel is Linux. In
+that case, it corresponds to the ARCH variable used when building Linux,
+@code{"mips"} for instance.
+
+@item @code{glibc-dynamic-linker}
+This field is the name of the GNU C Library dynamic linker for the
+corresponding system, as a string. It can be
+@code{"/lib/ld-linux-armhf.so.3"}.
+
+@end table
+@end deftp
+
+@node Supported Platforms
+@section Supported Platforms
+
+The @code{(guix platforms @dots{})} modules export the following
+variables, each of which is bound to a @code{platform} record.
+
+@defvr {Scheme Variable} armv7-linux
+Platform targeting ARM v7 CPU running GNU/Linux.
+@end defvr
+
+@defvr {Scheme Variable} aarch64-linux
+Platform targeting ARM v8 CPU running GNU/Linux.
+@end defvr
+
+@defvr {Scheme Variable} mips64-linux
+Platform targeting MIPS little-endian 64-bit CPU running GNU/Linux.
+@end defvr
+
+@defvr {Scheme Variable} powerpc-linux
+Platform targeting PowerPC big-endian 32-bit CPU running GNU/Linux.
+@end defvr
+
+@defvr {Scheme Variable} powerpc64le-linux
+Platform targeting PowerPC little-endian 64-bit CPU running GNU/Linux.
+@end defvr
+
+@defvr {Scheme Variable} riscv64-linux
+Platform targeting RISC-V 64-bit CPU running GNU/Linux.
+@end defvr
+
+@defvr {Scheme Variable} i686-linux
+Platform targeting x86 CPU running GNU/Linux.
+@end defvr
+
+@defvr {Scheme Variable} x86_64-linux
+Platform targeting x86 64-bit CPU running GNU/Linux.
+@end defvr
+
+@defvr {Scheme Variable} i686-mingw
+Platform targeting x86 CPU running Windows, with run-time support from
+MinGW.
+@end defvr
+
+@defvr {Scheme Variable} x86_64-mingw
+Platform targeting x86 64-bit CPU running Windows, with run-time support
+from MinGW.
+@end defvr
+
+@defvr {Scheme Variable} i586-gnu
+Platform targeting x86 CPU running GNU/Hurd (also referred to as
+``GNU'').
+@end defvr
+
+@node System Images
+@chapter Creating System Images.
+
+@cindex system images
+When it comes to installing Guix System for the first time on a new
+machine, you can basically proceed in three different ways. The first
+one is to use an existing operating system on the machine to run the
+@command{guix system init} command (@pxref{Invoking guix system}). The
+second one, is to produce an installation image (@pxref{Building the
+Installation Image}). This is a bootable system which role is to
+eventually run @command{guix system init}. Finally, the third option
+would be to produce an image that is a direct instantiation of the
+system you wish to run. That image can then be copied on a bootable
+device such as an USB drive or a memory card. The target machine would
+then directly boot from it, without any kind of installation procedure.
+
+The @command{guix system image} command is able to turn an operating
+system definition into a bootable image. This command supports
+different image types, such as @code{efi-raw}, @code{iso9660} and
+@code{docker}. Any modern @code{x86_64} machine will probably be able
+to boot from an @code{iso9660} image. However, there are a few machines
+out there that require specific image types. Those machines, in general
+using @code{ARM} processors, may expect specific partitions at specific
+offsets.
+
+This chapter explains how to define customized system images and how to
+turn them into actual bootable images.
+
+@menu
+* image Reference:: Detail of image declarations.
+* Instantiate an Image:: How to instantiate an image record.
+* image-type Reference:: Detail of image types declaration.
+* Image Modules:: Definition of image modules.
+@end menu
+
+@node image Reference
+@section @code{image} Reference
+
+The @code{image} record, described right after, allows you to define a
+customized bootable system image.
+
+@deftp {Data Type} image
+This is the data type representing a system image.
+
+@table @asis
+@item @code{name} (default: @code{#false})
+The image name as a symbol, @code{'my-iso9660} for instance. The name
+is optional and it defaults to @code{#false}.
+
+@item @code{format}
+The image format as a symbol. The following formats are supported:
+
+@itemize
+@item @code{disk-image}, a raw disk image composed of one or multiple
+partitions.
+
+@item @code{compressed-qcow2}, a compressed qcow2 image composed of
+one or multiple partitions.
+
+@item @code{docker}, a Docker image.
+
+@item @code{iso9660}, an ISO-9660 image.
+
+@item @code{tarball}, a tar.gz image archive.
+
+@item @code{wsl2}, a WSL2 image.
+
+@end itemize
+
+@item @code{platform} (default: @code{#false})
+The @code{platform} record the image is targeting (@pxref{Platforms}),
+@code{aarch64-linux} for instance. By default, this field is set to
+@code{#false} and the image will target the host platform.
+
+@item @code{size} (default: @code{'guess})
+The image size in bytes or @code{'guess}. The @code{'guess} symbol,
+which is the default, means that the image size will be inferred based
+on the image content.
+
+@item @code{operating-system}
+The image's @code{operating-system} record that is instanciated.
+
+@item @code{partition-table-type} (default: @code{'mbr})
+The image partition table type as a symbol. Possible values are
+@code{'mbr} and @code{'gpt}. It default to @code{'mbr}.
+
+@item @code{partitions} (default: @code{'()})
+The image partitions as a list of @code{partition} records
+(@pxref{partition Reference}).
+
+@item @code{compression?} (default: @code{#true})
+Whether the image content should be compressed, as a boolean. It
+defaults to @code{#true} and only applies to @code{'iso9660} image
+formats.
+
+@item @code{volatile-root?} (default: @code{#true})
+Whether the image root partition should be made volatile, as a boolean.
+
+This is achieved by using a RAM backed file system (overlayfs) that is
+mounted on top of the root partition by the initrd. It defaults to
+@code{#true}. When set to @code{#false}, the image root partition is
+mounted as read-write partition by the initrd.
+
+@item @code{shared-store?} (default: @code{#false})
+Whether the image's store should be shared with the host system, as a
+boolean. This can be useful when creating images dedicated to virtual
+machines. When set to @code{#false}, which is the default, the image's
+@code{operating-system} closure is copied to the image. Otherwise, when
+set to @code{#true}, it is assumed that the host store will be made
+available at boot, using a @code{9p} mount for instance.
+
+@item @code{shared-network?} (default: @code{#false})
+Whether to use the host network interfaces within the image, as a
+boolean. This is only used for the @code{'docker} image format. It
+defaults to @code{#false}.
+
+@item @code{substitutable?} (default: @code{#true})
+Whether the image derivation should be substitutable, as a boolean. It
+defaults to @code{true}.
+
+@end table
+@end deftp
+
+@node partition Reference
+@subsection @code{partition} Reference
+
+In @code{image} record may contain some partitions.
+
+@deftp {Data Type} partition
+This is the data type representing an image partition.
+
+@table @asis
+@item @code{size} (default: @code{'guess})
+The partition size in bytes or @code{'guess}. The @code{'guess} symbol,
+which is the default, means that the partition size will be inferred
+based on the partition content.
+
+@item @code{offset} (default: @code{0})
+The partition's start offset in bytes, relative to the image start or
+the previous partition end. It defaults to @code{0} which means that
+there is no offset applied.
+
+@item @code{file-system} (default: @code{"ext4"})
+The partition file system as a string, defaulting to @code{"ext4"}. The
+supported values are @code{"vfat"}, @code{"fat16"}, @code{"fat32"} and
+@code{"ext4"}.
+
+@item @code{file-system-options} (default: @code{'()})
+The partition file system creation options that should be passed to the
+partition creation tool, as a list of strings. This is only supported
+when creating @code{"ext4"} partitions.
+
+See the @code{"extended-options"} man page section of the
+@code{"mke2fs"} tool for a more complete reference.
+
+@item @code{label}
+The partition label as a mandatory string, @code{"my-root"} for
+instance.
+
+@item @code{uuid} (default: @code{#false})
+The partition UUID as an @code{uuid} record (@pxref{File Systems}). By
+default it is @code{#false}, which means that the partition creation
+tool will attribute a random UUID to the partition.
+
+@item @code{flags} (default: @code{'()})
+The partition flags as a list of symbols. Possible values are
+@code{'boot} and @code{'esp}. The @code{'boot} flags should be set if
+you want to boot from this partition. Exactly one partition should have
+this flag set, usually the root one. The @code{'esp} flag identifies a
+UEFI System Partition.
+
+@item @code{initializer} (default: @code{#false})
+The partition initializer procedure as a gexp. This procedure is called
+to populate a partition. If no initializer is passed, the
+@code{initialize-root-partition} procedure from the @code{(gnu build
+image)} module is used.
+
+@end table
+@end deftp
+
+@node Instantiate an Image
+@section Instantiate an Image
+
+Let's say you would like to create an MBR image with three distinct
+partitions:
+
+@itemize
+@item The @acronym{ESP, EFI System Partition}, a partition of
+40@tie{}MiB at offset 1024@tie{}KiB with a vfat file system.
+
+@item an ext4 partition of 50@tie{}MiB data file, and labeled ``data''.
+
+@item an ext4 bootable partition containing the @code{%simple-os}
+operating-system.
+@end itemize
+
+You would then write the following image definition in a
+@code{my-image.scm} file for instance.
+
+@lisp
+(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))))))
+@end lisp
+
+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 @code{%simple-os} operating-system.
+
+You can now run:
+
+@example
+guix system image my-image.scm
+@end example
+
+to instantiate the @code{image} definition. That produces a disk image
+which has the expected structure:
+
+@example
+$ parted $(guix system image my-image.scm) print
+@dots{}
+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
+@end example
+
+The size of the @code{boot} partition has been inferred to @code{1619MB}
+so that it is large enough to host the @code{%simple-os}
+operating-system.
+
+You can also use existing @code{image} record definitions and inherit
+from them to simplify the @code{image} definition. The @code{(gnu
+system image)} module provides the following @code{image} definition
+variables.
+
+@defvr {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 @code{x86_64} and
+@code{i686} machines, supporting BIOS or UEFI booting.
+@end defvr
+
+@defvr {Scheme Variable} efi32-disk-image
+Same as @code{efi-disk-image} but with a 32 bits EFI partition.
+@end defvr
+
+@defvr {Scheme Variable} iso9660-image
+An ISO-9660 image composed of a single bootable partition. This image
+can also be used on most @code{x86_64} and @code{i686} machines.
+@end defvr
+
+@defvr {Scheme Variable} docker-image
+A Docker image that can be used to spawn a Docker container.
+@end defvr
+
+Using the @code{efi-disk-image} we can simplify our previous
+@code{image} declaration this way:
+
+@example
+(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)))))
+@end example
+
+This will give the exact same @code{image} instantiation but the
+@code{image} declaration is simpler.
+
+@node image-type Reference
+@section image-type Reference
+
+The @command{guix system image} command can, as we saw above, take a
+file containing an @code{image} declaration as argument and produce an
+actual disk image from it. The same command can also handle a file
+containing an @code{operating-system} declaration as argument. In that
+case, how is the @code{operating-system} turned into an image?
+
+That's where the @code{image-type} record intervenes. This record
+defines how to transform an @code{operating-system} record into an
+@code{image} record.
+
+@deftp {Data Type} image-type
+This is the data type representing an image-type.
+
+@table @asis
+@item @code{name}
+The image-type name as a mandatory symbol, @code{'efi32-raw} for
+instance.
+
+@item @code{constructor}
+The image-type constructor, as a mandatory procedure that takes an
+@code{operating-system} record as argument and returns an @code{image}
+record.
+
+@end table
+@end deftp
+
+There are several @code{image-type} records provided by the @code{(gnu
+system image)} and the @code{(gnu system images @dots{})} modules.
+
+@defvr {Scheme Variable} efi-raw-image-type
+Build an image based on the @code{efi-disk-image} image.
+@end defvr
+
+@defvr {Scheme Variable} efi32-raw-image-type
+Build an image based on the @code{efi32-disk-image} image.
+@end defvr
+
+@defvr {Scheme Variable} qcow2-image-type
+Build an image based on the @code{efi-disk-image} image but with the
+@code{compressed-qcow2} image format.
+@end defvr
+
+@defvr {Scheme Variable} iso-image-type
+Build a compressed image based on the @code{iso9660-image} image.
+@end defvr
+
+@defvr {Scheme Variable} uncompressed-iso-image-type
+Build an image based on the @code{iso9660-image} image but with the
+@code{compression?} field set to @code{#false}.
+@end defvr
+
+@defvr {Scheme Variable} docker-image-type
+Build an image based on the @code{docker-image} image.
+@end defvr
+
+@defvr {Scheme Variable} raw-with-offset-image-type
+Build an MBR image with a single partition starting at a @code{1024KiB}
+offset. This is useful to leave some room to install a bootloader in
+the post-MBR gap.
+@end defvr
+
+@defvr {Scheme Variable} pinebook-pro-image-type
+Build an image that is targeting the Pinebook Pro machine. The MBR
+image contains a single partition starting at a @code{9MiB} offset. The
+@code{u-boot-pinebook-pro-rk3399-bootloader} bootloader will be
+installed in this gap.
+@end defvr
+
+@defvr {Scheme Variable} rock64-image-type
+Build an image that is targeting the Rock64 machine. The MBR image
+contains a single partition starting at a @code{16MiB} offset. The
+@code{u-boot-rock64-rk3328-bootloader} bootloader will be installed in
+this gap.
+@end defvr
+
+@defvr {Scheme Variable} novena-image-type
+Build an image that is targeting the Novena machine. It has the same
+characteristics as @code{raw-with-offset-image-type}.
+@end defvr
+
+@defvr {Scheme Variable} pine64-image-type
+Build an image that is targeting the Pine64 machine. It has the same
+characteristics as @code{raw-with-offset-image-type}.
+@end defvr
+
+@defvr {Scheme Variable} hurd-image-type
+Build an image that is targeting a @code{i386} machine running the Hurd
+kernel. The MBR image contains a single ext2 partitions with specific
+@code{file-system-options} flags.
+@end defvr
+
+@defvr {Scheme Variable} hurd-qcow2-image-type
+Build an image similar to the one built by the @code{hurd-image-type}
+but with the @code{format} set to @code{'compressed-qcow2}.
+@end defvr
+
+@defvr {Scheme Variable} wsl2-image-type
+Build an image for the @acronym{WSL2, Windows Subsystem for Linux 2}.
+It can be imported by running:
+
+@example
+wsl --import Guix ./guix ./wsl2-image.tar.gz
+wsl -d Guix
+@end example
+
+@end defvr
+
+So, if we get back to the @code{guix system image} command taking an
+@code{operating-system} declaration as argument. By default, the
+@code{efi-raw-image-type} is used to turn the provided
+@code{operating-system} into an actual bootable image.
+
+To use a different @code{image-type}, the @code{--image-type} option can
+be used. The @code{--list-image-types} option will list all the
+supported image types. It turns out to be a textual listing of all the
+@code{image-types} variables described just above (@pxref{Invoking guix
+system}).
+
+@node Image Modules
+@section Image Modules
+
+Let's take the example of the Pine64, an ARM based machine. To be able
+to produce an image targeting this board, we need the following
+elements:
+
+@itemize
+@item An @code{operating-system} record containing at least
+an appropriate kernel (@code{linux-libre-arm64-generic}) and bootloader
+@code{u-boot-pine64-lts-bootloader}) for the Pine64.
+
+@item Possibly, an @code{image-type} record providing a way to
+turn an @code{operating-system} record to an @code{image} record
+suitable for the Pine64.
+
+@item An actual @code{image} that can be instantiated with the
+@command{guix system image} command.
+
+@end itemize
+
+The @code{(gnu system images pine64)} module provides all those
+elements: @code{pine64-barebones-os}, @code{pine64-image-type} and
+@code{pine64-barebones-raw-image} respectively.
+
+The module returns the @code{pine64-barebones-raw-image} in order for
+users to be able to run:
+
+@example
+guix system image gnu/system/images/pine64.scm
+@end example
+
+Now, thanks to the @code{pine64-image-type} record declaring the
+@code{'pine64-raw} @code{image-type}, one could also prepare a
+@code{my-pine.scm} file with the following content:
+
+@example
+(use-modules (gnu system images pine64))
+(operating-system
+ (inherit pine64-barebones-os)
+ (timezone "Europe/Athens"))
+@end example
+
+to customize the @code{pine64-barebones-os}, and run:
+
+@example
+$ guix system image --image-type=pine64-raw my-pine.scm
+@end example
+
+Note that there are other modules in the @code{gnu/system/images}
+directory targeting @code{Novena}, @code{Pine64}, @code{PinebookPro} and
+@code{Rock64} machines.
+
@node Installing Debugging Files
@chapter Installing Debugging Files
configuration triplets,, autoconf, Autoconf}), the equivalent
@var{system} in Nix notation, the name of the
@var{glibc-dynamic-linker}, and the corresponding Linux architecture
-name if applicable.
+name if applicable (@pxref{Platforms}).
Once the bootstrap tarball are built, the @code{(gnu packages
bootstrap)} module needs to be updated to refer to these binaries on the
HCoop / jackhill / guix / guix.git / blobdiff