01/04: doc: Improve UEFI/BIOS bootloader documentation.

[Ludovic Courtès]

civodul pushed a commit to branch version-0.15.0
in repository guix.

commit fc0e663f782896f542d008c871d21b9cf636a75c
Author: Ludovic Courtès <address@hidden>
Date:   Thu Jul 5 11:44:46 2018 +0200

    doc: Improve UEFI/BIOS bootloader documentation.
    
    Partly fixes <https://bugs.gnu.org/30312>.
    
    * 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 841bc2a..a913c2e 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
 
address@hidden Note
address@hidden grub-bootloader
address@hidden grub-efi-bootloader
+Unsure whether to use EFI- or BIOS-based GRUB?  If the directory
address@hidden/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
address@hidden  @xref{Bootloader Configuration}, for more info on
+bootloaders.
address@hidden 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}.
 
address@hidden Bootloader
+
address@hidden legacy boot, on Intel machines
address@hidden BIOS boot, on Intel machines
address@hidden UEFI boot
address@hidden 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:
+
address@hidden
+(bootloader-configuration
+  (bootloader grub-efi-bootloader)
+  (target "/boot/efi"))
address@hidden example
+
address@hidden 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
 
address@hidden 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.
+
address@hidden grub-efi-bootloader
 @code{grub-efi-bootloader} allows to boot on modern systems using the
address@hidden Extensible Firmware Interface} (UEFI).
address@hidden 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.
+
address@hidden grub-bootloader
address@hidden 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
address@hidden/dev/sda} or @code{(hd0)} (for GRUB, @pxref{Invoking
-grub-install,,, grub, GNU GRUB Manual}).  For
address@hidden, it should be the path to a mounted EFI file
-system.
+bootloader.
+
+The interpretation depends on the bootloader in question.  For
address@hidden, for example, it should be a device name understood by
+the bootloader @command{installer} command, such as @code{/dev/sda} or
address@hidden(hd0)} (@pxref{Invoking grub-install,,, grub, GNU GRUB Manual}).  
For
address@hidden, 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 cb6d262..b763258 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 e874040..ea21e1d 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'.