diff options
author | Maxim Cournoyer <maxim.cournoyer@gmail.com> | 2022-09-27 15:59:30 -0400 |
---|---|---|
committer | Maxim Cournoyer <maxim.cournoyer@gmail.com> | 2022-09-27 15:59:30 -0400 |
commit | 990a4822f1cb45c1470fe38cbf17fd7bb54d0088 (patch) | |
tree | 1c1ff41c9264fe5af5ee0b8723d1e367e958c051 /doc | |
parent | 91db77c955cc7ef95dd8b535e40d6b4cf28669ec (diff) | |
parent | 3c6e220d8100281074c414a43c1efe9a01b53771 (diff) |
Merge branch 'staging' into core-updates
Conflicts resolved in:
gnu/local.mk
gnu/packages/cran.scm
gnu/packages/gnome.scm
gnu/packages/gtk.scm
gnu/packages/icu4c.scm
gnu/packages/java.scm
gnu/packages/machine-learning.scm
gnu/packages/tex.scm
Diffstat (limited to 'doc')
-rw-r--r-- | doc/contributing.texi | 41 | ||||
-rw-r--r-- | doc/guix.texi | 755 |
2 files changed, 795 insertions, 1 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 17a54f94cc..7712f63d67 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1406,6 +1406,47 @@ for more information. You can install @command{git send-email} with @command{guix install git:send-email}. @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html +To maximize the chances that you patch series is reviewed, the preferred +submission way is to use the @code{etc/teams.scm} script to notify the +appropriate team members (@pxref{Teams}). + +@unnumberedsubsec Teams +@anchor{Teams} +@cindex teams + +There are several teams mentoring different parts of the Guix source +code. To list all those teams, you can run from a Guix checkout: + +@example +$ ./etc/teams.scm list-teams +id: mentors +name: Mentors +description: A group of mentors who chaperone contributions by newcomers. +members: ++ Christopher Baines <mail@@cbaines.net> ++ Ricardo Wurmus <rekado@@elephly.net> ++ Mathieu Othacehe <othacehe@@gnu.org> ++ jgart <jgart@@dismail.de> ++ Ludovic Courtès <ludo@@gnu.org> +@dots{} +@end example + +You can run the following command to have the @code{Mentors} team put in +CC of a patch series: + +@example +$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch +@end example + +The appropriate team or teams can also be inferred from the modified +files. For instance, if you want to send the two latest commits of the +current Git repository to review, you can run: + +@example +$ guix shell -D guix +[env]$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch +@end example + @node Tracking Bugs and Patches @section Tracking Bugs and Patches diff --git a/doc/guix.texi b/doc/guix.texi index 8def1d8433..a173bea15f 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -106,6 +106,7 @@ Copyright @copyright{} 2022 Philip M@sup{c}Grath@* 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 @@ -182,6 +183,8 @@ Weblate} (@pxref{Translating Guix}). * 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. @@ -385,6 +388,7 @@ Services * 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. @@ -405,6 +409,18 @@ Defining Services * 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. @@ -17525,6 +17541,7 @@ declaration. * 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. @@ -31273,6 +31290,125 @@ The verbosity level of the daemon. @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 @@ -41142,6 +41278,623 @@ reader,, info-stnd, Stand-alone GNU Info}) and its Emacs counterpart 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: + +@lisp +(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 lisp + +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: + +@lisp +(use-modules (gnu system images pine64)) +(operating-system + (inherit pine64-barebones-os) + (timezone "Europe/Athens")) +@end lisp + +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 @@ -41888,7 +42641,7 @@ connection between a GNU triplet (@pxref{Specifying Target Triplets, GNU 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 |