[bug#72457] [PATCH v6 12/12] doc: Update bootloader documentation.

[Herman Rimm]

From: Lilah Tascheter <lilah@lunabee.space>

* doc/guix.texi (Manual Installation)[Proceeding with the Installation]:
Offload target reference.

(System Installation)[Building the Installation Image]: Don't reference
deleted variables.

(System Configuration)[Using the Configuration System]: Update example.
[operating-system Reference]<bootloader>: Can use multiple bootloaders.
[Proceeding with the installation]: Refer to Bootloader Configuration.
[Building the Installation Image]: Update example.
[Bootloader Configuration]<bootloader>: Update documentation for all
bootloaders, and add new ones. Document new fields efi-removable?,
32bit?, and keypair.
<bootloader-target>: New record.
<menu-entry>: Remove now-unsupported GRUB specifics in linux.  Move
device documentation and add some for device-mount-point and
device-subvol.  Fix typo in multiboot-arguments.  Document chain-loader
for arbitrary bootloaders.
[Invoking guix system]<switch-generation>: Bootloaders are now
reinstalled.
<image> Other bootloaders may be used.
[Invoking guix deploy]: Update template.

Change-Id: I45ac9d5ad3cb491c693e9a4b2f0b44b527478ee7
---
 doc/guix.texi | 380 ++++++++++++++++++++++++++++----------------------
 1 file changed, 212 insertions(+), 168 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index a3338b098a..194fbbf69c 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2529,12 +2529,9 @@ Proceeding with the Installation
 Make sure the @code{bootloader-configuration} form refers to the targets
 you want to install GRUB on.  It should mention @code{grub-bootloader}
 if you are installing GRUB in the legacy way, or
-@code{grub-efi-bootloader} for newer UEFI systems.  For legacy systems,
-the @code{targets} field contain the names of the devices, like
-@code{(list "/dev/sda")}; for UEFI systems it names the paths to mounted
-EFI partitions, like @code{(list "/boot/efi")}; do make sure the paths
-are currently mounted and a @code{file-system} entry is specified in
-your configuration.
+@code{grub-efi-bootloader} for newer UEFI systems.
+@xref{Bootloader Configuration} for information on how to format the
+@code{targets} field.
 
 @item
 Be sure that your file system labels match the value of their respective
@@ -17297,7 +17294,9 @@ Using the Configuration System
 @lisp
 (bootloader-configuration
   (bootloader grub-efi-bootloader)
-  (targets '("/boot/efi")))
+  (targets (list (bootloader-target
+                   (type 'esp)
+                   (path "/boot/efi")))))
 @end lisp
 
 @xref{Bootloader Configuration}, for more information on the available
@@ -17603,8 +17602,10 @@ operating-system Reference
 List of strings or gexps representing additional arguments to pass on
 the command-line of the kernel---e.g., @code{("console=ttyS0")}.
 
-@item @code{bootloader}
-The system bootloader configuration object.  @xref{Bootloader Configuration}.
+@item @code{bootloader} (default: '())
+The system bootloader configuration object.  Can either be a single
+@code{bootloader-configuration} or a list of them, to install multiple or no
+bootloaders.  @xref{Bootloader Configuration}.
 
 @item @code{label}
 This is the label (a string) as it appears in the bootloader's menu entry.
@@ -18799,7 +18800,9 @@ Keyboard Layout
   (keyboard-layout (keyboard-layout "tr"))  ;for the console
   (bootloader (bootloader-configuration
                 (bootloader grub-efi-bootloader)
-                (targets '("/boot/efi"))
+                (targets (list (bootloader-target
+                                 (type 'esp)
+                                 (path "/boot/efi"))))
                 (keyboard-layout keyboard-layout))) ;for GRUB
   (services (cons (set-xorg-configuration
                     (xorg-configuration             ;for Xorg
@@ -42437,18 +42440,8 @@ Bootloader Configuration
 @cindex EFI, bootloader
 @cindex UEFI, bootloader
 @cindex BIOS, bootloader
-The bootloader to use, as a @code{bootloader} object.  For now
-@code{grub-bootloader}, @code{grub-efi-bootloader},
-@code{grub-efi-removable-bootloader}, @code{grub-efi-netboot-bootloader},
-@code{grub-efi-netboot-removable-bootloader}, @code{extlinux-bootloader}
-and @code{u-boot-bootloader} are supported.
-
-@cindex ARM, bootloaders
-@cindex AArch64, bootloaders
-Available bootloaders are described in @code{(gnu bootloader @dots{})}
-modules.  In particular, @code{(gnu bootloader u-boot)} contains definitions
-of bootloaders for a wide range of ARM and AArch64 systems, using the
-@uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.
+The bootloader to use.  Available bootloaders, in addition to what
+target types they require, are as follows:
 
 @itemize
 @vindex depthcharge-veyron-speedy-bootloader
@@ -42457,118 +42450,105 @@ Bootloader Configuration
 install the kernel blob as a @code{device}, @code{label}, or @code{uuid}.
 
 @vindex grub-bootloader
-@code{grub-bootloader} allows you to boot in particular Intel-based machines
-in ``legacy'' BIOS mode.
+@item @code{grub-bootloader}
+GRUB2 for BIOS systems.  Requires a @code{'disk} target providing either a
+@code{device}, @code{label}, or @code{uuid}.  If root is mounted over NFS, it
+will load its files and the Guix System over
+@acronym{PXE, Preboot eXecution Environment}.
+
+@vindex grub-minimal-bootloader
+@item @code{grub-minimal-bootloader}
+As above, but using a minimal build of GRUB.
 
 @vindex grub-efi-bootloader
-@code{grub-efi-bootloader} allows to boot on modern systems using the
-@dfn{Unified Extensible Firmware Interface} (UEFI).  This is what you should
-use if the installation image contains a @file{/sys/firmware/efi} directory
-when you boot it on your system.
-
-@vindex grub-efi-removable-bootloader
-@code{grub-efi-removable-bootloader} allows you to boot your system from
-removable media by writing the GRUB file to the UEFI-specification location of
-@file{/EFI/BOOT/BOOTX64.efi} of the boot directory, usually @file{/boot/efi}.
-This is also useful for some UEFI firmwares that ``forget'' their configuration
-from their non-volatile storage. Like @code{grub-efi-bootloader}, this can only
-be used if the @file{/sys/firmware/efi} directory is available.
+@item @code{grub-efi-bootloader}
+GRUB2 for "modern" systems using the
+@acronym{UEFI, Unified Extensible Firmware Interface}.  It requires an
+@code{'esp} target providing a mount point @code{path} for the EFI
+System Partition.  If root is mounted over NFS, a PXE client will load
+the boot files and Guix System from a
+@acronym{TFTP, Trivial File Transfer Protocol} server, discovered via
+@acronym{DHCP, Dynamic Host Configuration Protocol}.
+
+@vindex extlinux-bootloader
+@item @code{extlinux-bootloader}
+Extlinux for "legacy" BIOS systems which use an MBR partition table.
+It requires a @code{'disk} target providing either a @code{device},
+@code{label}, or @code{uuid}.
+
+@vindex extlinux-gpt-bootloader
+@item @code{extlinux-gpt-bootloader}
+This is the same as above, but for systems with a GPT partition table.
 
-@quotation Note
-This @emph{will} overwrite the GRUB file from any other operating systems that
-also place their GRUB file in the UEFI-specification location; making them
-unbootable.
-@end quotation
+@cindex ARM, bootloaders
+@cindex AArch64, bootloaders
+@vindex u-boot-a20-olinuxino-lime-bootloader
+@vindex u-boot-a20-olinuxino-lime2-bootloader
+@vindex u-boot-a20-olinuxino-micro-bootloader
+@vindex u-boot-bananapi-m2-ultra-bootloader
+@vindex u-boot-beaglebone-black-bootloader
+@vindex u-boot-cubietruck-bootloader
+@vindex u-boot-firefly-rk3399-bootloader
+@vindex u-boot-mx6cuboxi-bootloader
+@vindex u-boot-nanopi-r4s-bootloader
+@vindex u-boot-nintendo-nes-classic-edition-bootloader
+@vindex u-boot-novena-bootloader
+@vindex u-boot-orangepi-r1-plus-lts-rk3328-bootloader
+@vindex u-boot-orangepi-zero-2w-bootloader
+@vindex u-boot-pine64-plus-bootloader
+@vindex u-boot-pine64-lts-bootloader
+@vindex u-boot-pinebook-bootloader
+@vindex u-boot-pinebook-pro-rk3399-bootloader
+@vindex u-boot-puma-rk3399-bootloader
+@vindex u-boot-qemu-riscv64-bootloader
+@vindex u-boot-rock64-rk3328-bootloader
+@vindex u-boot-rockpro64-rk3399-bootloader
+@vindex u-boot-rpi-2-bootloader
+@vindex u-boot-rpi-3-bootloader
+@vindex u-boot-rpi-4-bootloader
+@vindex u-boot-rpi-bootloader
+@vindex u-boot-sifive-unmatched-bootloader
+@vindex u-boot-starfive-visionfive2-bootloader
+@vindex u-boot-ts7970-q-2g-1000mhz-c-bootloader
+@vindex u-boot-wandboard-bootloader
+@item U-Boot
+U-Boot has individual bootloaders @code{u-boot-board-bootloader} for
+each of the following @code{board}s: @code{a20-olinuxino-lime},
+@code{a20-olinuxino-lime2}, @code{a20-olinuxino-micro},
+@code{bananapi-m2-ultra}, @code{beaglebone-black}, @code{cubietruck},
+@code{firefly-rk3399}, @code{mx6cuboxi}, @code{nanopi-r4s},
+@code{nintendo-nes-classic-edition}, @code{novena},
+@code{orangepi-r1-plus-lts-rk3328}, @code{orangepi-zero-2w},
+@code{pine64-plus}, @code{pine64-lts}, @code{pinebook},
+@code{pinebook-pro-rk3399}, @code{puma-rk3399}, @code{qemu-riscv64},
+@code{rock64-rk3328}, @code{rockpro64-rk3399}, @code{rpi-2},
+@code{rpi-3}, @code{rpi-4}, @code{rpi}, @code{sifive-unmatched},
+@code{ts7970-q-2g-1000mhz-c}, and @code{wandboard}.
+
+Each of these require a @code{'disk} target providing either a @code{device},
+@code{label}, or @code{uuid}, except the @code{ts7970-q-2g-1000mhz-c}
+and @code{qemu-riscv64} boards.  Here the bootloader just copies U-Boot
+to @file{/boot/u-boot.imx} or @file{/boot/u-boot.bin}, respectively.
+You should then manually flash it to the SPI flash at the U-Boot prompt.
+
+By default Guix configures U-Boot to use a generated extlinux config.
+However U-Boot can be configured to run a UEFI application, if you want
+to chain load another bootloader.
+@end itemize
 
-@vindex grub-efi-netboot-bootloader
-@code{grub-efi-netboot-bootloader} allows you to boot your system over network
-through TFTP@.  In combination with an NFS root file system this allows you to
-build a diskless Guix system.
-
-The installation of the @code{grub-efi-netboot-bootloader} generates the
-content of the TFTP root directory at @code{targets} (@pxref{Bootloader
-Configuration, @code{targets}}) below the sub-directory @file{efi/Guix}, to be
-served by a TFTP server.  You may want to mount your TFTP server directories
-onto the @code{targets} to move the required files to the TFTP server
-automatically during installation.
-
-If you plan to use an NFS root file system as well (actually if you mount the
-store from an NFS share), then the TFTP server needs to serve the file
-@file{/boot/grub/grub.cfg} and other files from the store (like GRUBs 
background
-image, the kernel (@pxref{operating-system Reference, @code{kernel}}) and the
-initrd (@pxref{operating-system Reference, @code{initrd}})), too.  All these
-files from the store will be accessed by GRUB through TFTP with their normal
-store path, for example as
-@file{tftp://tftp-server/gnu/store/…-initrd/initrd.cpio.gz}.
-
-Two symlinks are created to make this possible.  For each target in the
-@code{targets} field, the first symlink is
-@samp{target}@file{/efi/Guix/boot/grub/grub.cfg} pointing to
-@file{../../../boot/grub/grub.cfg}, where @samp{target} may be
-@file{/boot}.  In this case the link is not leaving the served TFTP root
-directory, but otherwise it does.  The second link is
-@samp{target}@file{/gnu/store} and points to @file{../gnu/store}.  This
-link is leaving the served TFTP root directory.
-
-The assumption behind all this is that you have an NFS server exporting
-the root file system for your Guix system, and additionally a TFTP
-server exporting your @code{targets} directories—usually a single
-@file{/boot}—from that same root file system for your Guix system.  In
-this constellation the symlinks will work.
-
-For other constellations you will have to program your own bootloader
-installer, which then takes care to make necessary files from the store
-accessible through TFTP, for example by copying them into the TFTP root
-directory for your @code{targets}.
-
-It is important to note that symlinks pointing outside the TFTP root directory
-may need to be allowed in the configuration of your TFTP server.  Further the
-store link exposes the whole store through TFTP@.  Both points need to be
-considered carefully for security aspects.  It is advised to disable any TFTP
-write access!
-
-Please note, that this bootloader will not modify the ‘UEFI Boot Manager’ of
-the system.
-
-Beside the @code{grub-efi-netboot-bootloader}, the already mentioned TFTP and
-NFS servers, you also need a properly configured DHCP server to make the 
booting
-over netboot possible.  For all this we can currently only recommend you to 
look
-for instructions about @acronym{PXE, Preboot eXecution Environment}.
-
-If a local EFI System Partition (ESP) or a similar partition with a FAT
-file system is mounted in @code{targets}, then symlinks cannot be
-created.  In this case everything will be prepared for booting from
-local storage, matching the behavior of @code{grub-efi-bootloader}, with
-the difference that all GRUB binaries are copied to @code{targets},
-necessary for booting over the network.
-
-@vindex grub-efi-netboot-removable-bootloader
-@code{grub-efi-netboot-removable-bootloader} is identical to
-@code{grub-efi-netboot-bootloader} with the exception that the
-sub-directory @file{efi/boot} will be used instead of @file{efi/Guix} to
-comply with the UEFI specification for removable media.
+@item @code{targets}
+This is a list of @code{bootloader-target} (see below) structures denoting
+where the bootloader should install itself.  Interpretation of specific target
+types and target requirements depend on the specific @code{bootloader} used.
 
 @quotation Note
-This @emph{will} overwrite the GRUB file from any other operating systems that
-also place their GRUB file in the UEFI-specification location; making them
-unbootable.
+Bootloaders have a set of default targets, that can interact with 
user-specified
+targets.  For UEFI bootloaders using the @code{'esp} target, this typically
+includes a @code{'vendir} target.  If you configure multiple UEFI bootloaders,
+you should set different @code{'vendir} target @code{path}s for each, each
+@code{offset} from @code{'esp}.
 @end quotation
 
-@item @code{targets}
-This is a list of strings denoting the targets onto which to install the
-bootloader.
-
-The interpretation of targets depends on the bootloader in question.
-For @code{grub-bootloader}, for example, they should be device names
-understood by the bootloader @command{installer} command, such as
-@code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
-GNU GRUB Manual}).  For @code{grub-efi-bootloader} and
-@code{grub-efi-removable-bootloader} they should be mount
-points of the EFI file system, usually @file{/boot/efi}.  For
-@code{grub-efi-netboot-bootloader}, @code{targets} should be the mount
-points corresponding to TFTP root directories served by your TFTP
-server.
-
 @item @code{menu-entries} (default: @code{'()})
 A possibly empty list of @code{menu-entry} objects (see below), denoting
 entries to appear in the bootloader menu, in addition to the current
@@ -42578,6 +42558,29 @@ Bootloader Configuration
 The index of the default boot menu entry.  Index 0 is for the entry of the
 current system.
 
+@item @code{efi-removable?} (default: @var{#f})
+Used by all UEFI bootloaders to determine whether they should be installed to
+the UEFI standard fallback bootloader path (on x86_64,
+@file{/EFI/BOOT/BOOTX64.EFI}).  This allows it to be booted from removable 
media
+or otherwise in cases where the system has not been booted from UEFI already.
+
+@quotation Warning
+This will override any other bootloaders installed to the same path!
+@end quotation
+
+@item @code{32bit?} (default: @var{#f})
+Some 64-bit systems require their bootloaders to be 32-bit, including some 
early
+UEFI systems and some Raspberry Pis.  If that is the case, and the bootloader
+supports it, setting this option will force the bootloader to install as if it
+were on a 32-bit system.
+
+@item @code{keypair} (default: @var{#f})
+Designates a keypair to be used by bootloaders that support some kind of
+cryptographic signature, such as UEFI Secure Boot.  This must be a pair
+@code{'(cert . priv)} of paths to the public key (@code{cert}) and private key
+(@code{priv}).  The keys these paths point to should be owned by root with 600
+permissions for security purposes.
+
 @item @code{timeout} (default: @code{5})
 The number of seconds to wait for keyboard input before booting.  Set to
 0 to boot immediately, and to -1 to wait indefinitely.
@@ -42689,6 +42692,51 @@ Bootloader Configuration
 
 @end deftp
 
+@vindex bootloader-target
+Configuring bootloader targets uses a specialized record designed for clarity
+and to abstract over the varying user-supplied paths bootloaders.  Only the
+@code{type} field is required; Guix will attempt to extrapolate as needed from
+what information you provide, though at least one of @code{path}, 
@code{device},
+@code{label}, or @code{uuid} is required to do so.
+
+@deftp {Data Type} bootloader-target
+The type of a target as used in @code{bootloader-configuration}.
+
+@table @asis
+
+@item @code{type}
+What target this record is describing.  Must be a symbol, for example
+@code{'esp} or @code{'disk}.
+
+@item @code{path} (default: @var{#f})
+@code{path} denotes a string path, usually interpreted by the bootloader to
+signify a mount point (such as in the case of @code{'esp}).  This value is
+automatically offset from the target denoted by @code{offset}, even if the path
+given is absolute.  This allows for bootloaders to know what device or 
partition
+a @code{path} is actually stored on, and how to locate it.
+
+@item @code{offset} (default: @code{'root} when @code{path}, otherwise 
@var{#f})
+All @code{path} values, even if absolute, are automatically offset from 
another.
+@code{offset} is a symbol denoting which target type the path should be offset
+from.  This allows for bootloaders to know what device or partition a
+@code{path} is actually stored on, and how to locate it.
+
+@item @code{device} (default: @var{#f})
+@itemx @code{label} (default: @var{#f})
+@itemx @code{uuid} (default: @var{#f})
+These all work as a way of defining some kind of physical device or partition.
+Using @code{uuid} and @code{label} to refer to a filesystem's UUID or
+label is vastly preferred over using @code{device} to refer to block
+devices, as they can vary per boot and may not exist at boot-time.
+
+@item @code{file-system} (default: @var{#f})
+A string denoting a file system type, as used in @ref{File Systems}.  Unless
+your filesystem isn't being detected properly, or is unmounted at bootloader
+install-time, you shouldn't need to specify this.
+
+@end table
+@end deftp
+
 @cindex dual boot
 @cindex boot menu
 Should you want to list additional boot menu entries @i{via} the
@@ -42700,6 +42748,8 @@ Bootloader Configuration
 @lisp
 (menu-entry
   (label "The Other Distro")
+  (device (file-system-label "boot"))
+  (device-mount-point "/boot")
   (linux "/boot/old/vmlinux-2.6.32")
   (linux-arguments '("root=/dev/sda2"))
   (initrd "/boot/old/initrd"))
@@ -42715,6 +42765,29 @@ Bootloader Configuration
 @item @code{label}
 The label to show in the menu---e.g., @code{"GNU"}.
 
+@item @code{device} (default: @var{#f})
+The device where any files specified below are to be found.  For GRUB,
+this is what @dfn{root} (@pxref{root,,, grub, GNU GRUB manual}) is set
+to for this menu entry.
+
+This may be a file system label (a string), a file system UUID (a
+bytevector, @pxref{File Systems}), or @code{#f}, in which case
+the bootloader will search the device containing the file specified by
+the @code{linux} field (@pxref{search,,, grub, GNU GRUB manual}).  It
+must @emph{not} be an OS device name such as @file{/dev/sda1}.
+
+@item @code{device-mount-point} (default: @var{#f})
+This is where @code{device} is mounted onto your file system.  If provided, it
+allows for you to specify full paths for provided files, which will be
+automatically realized into paths local to their device.
+
+This is not necessary if specified files are already referring to files local 
to
+@code{device}, including if they're on your root filesystem.
+
+@item @code{device-subvol} (default: @var{#f})
+This is a btrfs subvolume name, useful in case you wish to access files from a
+btrfs subvolume on a device.  @xref{Btrfs file system}.
+
 @item @code{linux} (default: @code{#f})
 The Linux kernel image to boot, for example:
 
@@ -42722,17 +42795,6 @@ Bootloader Configuration
 (file-append linux-libre "/bzImage")
 @end lisp
 
-For GRUB, it is also possible to specify a device explicitly in the
-file path using GRUB's device naming convention (@pxref{Naming
-convention,,, grub, GNU GRUB manual}), for example:
-
-@example
-"(hd0,msdos1)/boot/vmlinuz"
-@end example
-
-If the device is specified explicitly as above, then the @code{device}
-field is ignored entirely.
-
 @item @code{linux-arguments} (default: @code{'()})
 The list of extra Linux kernel command-line arguments---e.g.,
 @code{'("console=ttyS0")}.
@@ -42741,16 +42803,6 @@ Bootloader Configuration
 A G-Expression or string denoting the file name of the initial RAM disk
 to use (@pxref{G-Expressions}).
 
-@item @code{device} (default: @code{#f})
-The device where the kernel and initrd are to be found---i.e., for GRUB,
-@dfn{root} for this menu entry (@pxref{root,,, grub, GNU GRUB manual}).
-
-This may be a file system label (a string), a file system UUID (a
-bytevector, @pxref{File Systems}), or @code{#f}, in which case
-the bootloader will search the device containing the file specified by
-the @code{linux} field (@pxref{search,,, grub, GNU GRUB manual}).  It
-must @emph{not} be an OS device name such as @file{/dev/sda1}.
-
 @item @code{multiboot-kernel} (default: @code{#f})
 The kernel to boot in Multiboot-mode (@pxref{multiboot,,, grub, GNU GRUB
 manual}).  When this field is set, a Multiboot menu-entry is generated.
@@ -42773,7 +42825,7 @@ Bootloader Configuration
 To use the new and still experimental
 @uref{https://darnassus.sceen.net/~hurd-web/rump_kernel/, rumpdisk
 user-level disk driver} instead of GNU@tie{}Mach's in-kernel IDE driver,
-set @code{kernel-arguments} to:
+set @code{multiboot-arguments} to:
 
 @lisp
 '("noide")
@@ -42796,10 +42848,8 @@ Bootloader Configuration
 @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.
+Varies slightly depending on bootloader.  For @code{grub}, this is anything 
that
+the @code{chainloader} directive can accept
 
 @lisp
 (bootloader
@@ -43007,10 +43057,6 @@ Invoking guix system
 supported by the bootloader being used.  The next time the system
 boots, it will use the specified system generation.
 
-The bootloader itself is not being reinstalled when using this
-command.  Thus, the installed bootloader is used with an updated
-configuration file.
-
 The target generation can be specified explicitly by its generation
 number.  For example, the following invocation would switch to system
 generation 7:
@@ -43031,11 +43077,10 @@ Invoking guix system
 @end example
 
 Currently, the effect of invoking this action is @emph{only} to switch
-the system profile to an existing generation and rearrange the
-bootloader menu entries.  To actually start using the target system
-generation, you must reboot after running this action.  In the future,
-it will be updated to do the same things as @command{reconfigure},
-like activating and deactivating services.
+the system profile to an existing generation and reinstall the bootloader.  To
+actually start using the target system generation, you must reboot after
+running this action.  In the future, it will be updated to do the same things
+as @command{reconfigure}, like activating and deactivating services.
 
 This action will fail if the specified generation does not exist.
 
@@ -43211,11 +43256,9 @@ Invoking guix system
 When using the @code{qcow2} image type, the returned image is in qcow2
 format, which the QEMU emulator can efficiently use. @xref{Running Guix
 in a VM}, for more information on how to run the image in a virtual
-machine.  The @code{grub-bootloader} bootloader is always used
-independently of what is declared in the @code{operating-system} file
-passed as argument.  This is to make it easier to work with QEMU, which
-uses the SeaBIOS BIOS by default, expecting a bootloader to be installed
-in the Master Boot Record (MBR).
+machine.  Currently, QEMU as packaged in Guix does not have UEFI support,
+so you should select a bootloader for BIOS systems in your
+@code{operating-system} configuration.
 
 @cindex docker-image, creating docker images
 When using the @code{docker} image type, a Docker image is produced.
@@ -43533,7 +43576,6 @@ Invoking guix deploy
 ;; forwarded to the host's loopback interface.
 
 (use-service-modules networking ssh)
-(use-package-modules bootloaders)
 
 (define %system
   (operating-system
@@ -43541,7 +43583,9 @@ Invoking guix deploy
    (timezone "Etc/UTC")
    (bootloader (bootloader-configuration
                 (bootloader grub-bootloader)
-                (targets '("/dev/vda"))
+                (targets (list (bootloader-target
+                                 (type 'disk)
+                                 (device "/dev/sda"))))
                 (terminal-outputs '(console))))
    (file-systems (cons (file-system
                         (mount-point "/")
-- 
2.45.2