From fc0e663f782896f542d008c871d21b9cf636a75c Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Thu, 5 Jul 2018 11:44:46 +0200 Subject: doc: Improve UEFI/BIOS bootloader documentation. Partly fixes . * doc/guix.texi (Preparing for Installation): Add note on how to choose between UEFI and BIOS. (Using the Configuration System)[Bootloader]: New subsubsection. (Bootloader Configuration): Expound on the bootloader type and target. * gnu/system/examples/desktop.tmpl: Switch to UEFI. * gnu/system/examples/bare-bones.tmpl: Explicitly mention "legacy" and "BIOS" in the comments. --- doc/guix.texi | 60 ++++++++++++++++++++++++++++++------- gnu/system/examples/bare-bones.tmpl | 5 ++-- gnu/system/examples/desktop.tmpl | 8 ++--- 3 files changed, 57 insertions(+), 16 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 841bc2a34f..a913c2ea3d 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -8636,6 +8636,17 @@ must have the @code{esp} flag set. E.g., for @command{parted}: parted /dev/sda set 1 esp on @end example +@quotation Note +@vindex grub-bootloader +@vindex grub-efi-bootloader +Unsure whether to use EFI- or BIOS-based GRUB? If the directory +@file{/sys/firmware/efi} exists in the installation image, the you should +probably perform an EFI installation, using @code{grub-efi-bootloader}. +Otherwise you should use the BIOS-based GRUB, known as +@code{grub-bootloader}. @xref{Bootloader Configuration}, for more info on +bootloaders. +@end quotation + Once you are done partitioning the target hard disk drive, you have to create a file system on the relevant partition(s)@footnote{Currently GuixSD only supports ext4 and btrfs file systems. In particular, code @@ -8964,6 +8975,27 @@ Below we discuss the effect of some of the most important fields fields), and how to @dfn{instantiate} the operating system using @command{guix system}. +@unnumberedsubsubsec Bootloader + +@cindex legacy boot, on Intel machines +@cindex BIOS boot, on Intel machines +@cindex UEFI boot +@cindex EFI boot +The @code{bootloader} field describes the method that will be used to boot +your system. Machines based on Intel processors can boot in ``legacy'' BIOS +mode, as in the example above. However, more recent machines rely instead on +the @dfn{Unified Extensible Firmware Interface} (UEFI) to boot. In that case, +the @code{bootloader} field should contain something along these lines: + +@example +(bootloader-configuration + (bootloader grub-efi-bootloader) + (target "/boot/efi")) +@end example + +@xref{Bootloader Configuration}, for more information on the available +configuration options. + @unnumberedsubsubsec Globally-Visible Packages @vindex %base-packages @@ -9074,8 +9106,7 @@ management, power management, and more, would look like this: @include os-config-desktop.texi @end lisp -@cindex UEFI -A graphical UEFI system with a choice of lightweight window managers +A graphical system with a choice of lightweight window managers instead of full-blown desktop environments would look like this: @lisp @@ -20697,21 +20728,30 @@ The type of a bootloader configuration declaration. The bootloader to use, as a @code{bootloader} object. For now @code{grub-bootloader}, @code{grub-efi-bootloader}, @code{extlinux-bootloader} and @code{u-boot-bootloader} are supported. + +@vindex grub-efi-bootloader @code{grub-efi-bootloader} allows to boot on modern systems using the -@dfn{Unified Extensible Firmware Interface} (UEFI). +@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-bootloader +@code{grub-bootloader} allows you to boot in particular Intel-based machines +in ``legacy'' BIOS mode. Available bootloaders are described in @code{(gnu bootloader @dots{})} modules. @item @code{target} This is a string denoting the target onto which to install the -bootloader. The exact interpretation depends on the bootloader in -question; for @code{grub-bootloader}, for example, it should be a device -name understood by the bootloader @command{installer} command, such as -@code{/dev/sda} or @code{(hd0)} (for GRUB, @pxref{Invoking -grub-install,,, grub, GNU GRUB Manual}). For -@code{grub-efi-bootloader}, it should be the path to a mounted EFI file -system. +bootloader. + +The interpretation depends on the bootloader in question. For +@code{grub-bootloader}, for example, it should be a device name 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}, it should be the mount point of the EFI file +system, usually @file{/boot/efi}. @item @code{menu-entries} (default: @code{()}) A possibly empty list of @code{menu-entry} objects (see below), denoting diff --git a/gnu/system/examples/bare-bones.tmpl b/gnu/system/examples/bare-bones.tmpl index cb6d2623db..b763258e52 100644 --- a/gnu/system/examples/bare-bones.tmpl +++ b/gnu/system/examples/bare-bones.tmpl @@ -10,8 +10,9 @@ (timezone "Europe/Berlin") (locale "en_US.utf8") - ;; Assuming /dev/sdX is the target hard disk, and "my-root" is - ;; the label of the target root file system. + ;; Boot in "legacy" BIOS mode, assuming /dev/sdX is the + ;; target hard disk, and "my-root" is the label of the target + ;; root file system. (bootloader (bootloader-configuration (bootloader grub-bootloader) (target "/dev/sdX"))) diff --git a/gnu/system/examples/desktop.tmpl b/gnu/system/examples/desktop.tmpl index e8740407d0..ea21e1df66 100644 --- a/gnu/system/examples/desktop.tmpl +++ b/gnu/system/examples/desktop.tmpl @@ -11,11 +11,11 @@ (timezone "Europe/Paris") (locale "en_US.utf8") - ;; Assuming /dev/sdX is the target hard disk, and "my-root" - ;; is the label of the target root file system. + ;; Use the UEFI variant of GRUB with the EFI System + ;; Partition mounted on /boot/efi. (bootloader (bootloader-configuration - (bootloader grub-bootloader) - (target "/dev/sdX"))) + (bootloader grub-efi-bootloader) + (target "/boot/efi"))) ;; Specify a mapped device for the encrypted root partition. ;; The UUID is that returned by 'cryptsetup luksUUID'. -- cgit v1.2.3