Subject: bug#30312: documentation: misleading EFI partitioning instructions

From: Marius Bakke <[email-masked]>
Date: Tue, 26 Jun 2018 12:11:51 +0200

[email-masked] (Ludovic Courtès) writes:

> Hello gentlefolks!
>
> Ricardo Wurmus <[email-masked]> skribis:
>
>> First, this sounds like it’s up to the user to pick either EFI-based
>> GRUB or BIOS-based GRUB.  It is not clear that this is determined by
>> whether the machine has a {BIOS, EFI in legacy mode} or EFI.  It’s
>> really not much of a choice.
>>
>> Second, the “parted” command operates on the first partition (“1”), yet
>> for the second command the second partition (“/dev/sda2”) is used.  It’s
>> better to be consistent here, i.e. to change “set 1 esp on” to “set 2
>> esp on” and to state that this would modify “/dev/sda2”.
>>
>> Finally, it is not clear where the efi partition should be mounted.
>> Should it be /mnt/boot/efi?  If so, should the configuration file
>> specify “/mnt/boot/efi” as the target?  Or should it be “/boot/efi”?
>>
>> An example would be useful here.
>
> It’d be nice to fix this before the release.  Anyone could take a look
> to address these issues?

I've tried to address the latter issue in <https://bugs.gnu.org/31959>.

I tested it by installing in a virtual machine with the ESP mounted at
"/mnt/boot/efi", using a Guix snapshot that included that commit.  It
also works on my installed system with the ESP on /boot/efi.

Here is a patch addressing the second issue:

From 28b1aff2f0a78e7736c214880bbcfce1c0135346 Mon Sep 17 00:00:00 2001
From: Marius Bakke <[email-masked]>
Date: Tue, 26 Jun 2018 11:59:51 +0200
Subject: [PATCH] doc: Use a consistent partitioning scheme.

* doc/guix.texi (Preparing for Installation): Consistently refer to the ESP as
/dev/sda1; root file system as /dev/sda2; and swap as /dev/sda3.
---
 doc/guix.texi | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index da05a200a..d3375601a 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -8641,21 +8641,21 @@ create a file system on the relevant partition(s)@footnote{Currently
 GuixSD only supports ext4 and btrfs file systems.  In particular, code
 that reads file system UUIDs and labels only works for these file system
 types.}.  For the ESP, if you have one and assuming it is
-@file{/dev/sda2}, run:
+@file{/dev/sda1}, run:
 
 @example
-mkfs.fat -F32 /dev/sda2
+mkfs.fat -F32 /dev/sda1
 @end example
 
 Preferably, assign file systems a label so that you can easily and
 reliably refer to them in @code{file-system} declarations (@pxref{File
 Systems}).  This is typically done using the @code{-L} option of
 @command{mkfs.ext4} and related commands.  So, assuming the target root
-partition lives at @file{/dev/sda1}, a file system with the label
+partition lives at @file{/dev/sda2}, a file system with the label
 @code{my-root} can be created with:
 
 @example
-mkfs.ext4 -L my-root /dev/sda1
+mkfs.ext4 -L my-root /dev/sda2
 @end example
 
 @cindex encrypted disk
@@ -8663,12 +8663,12 @@ If you are instead planning to encrypt the root partition, you can use
 the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html,
 @uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}},
 @code{man cryptsetup}} for more information.)  Assuming you want to
-store the root partition on @file{/dev/sda1}, the command sequence would
+store the root partition on @file{/dev/sda2}, the command sequence would
 be along these lines:
 
 @example
-cryptsetup luksFormat /dev/sda1
-cryptsetup open --type luks /dev/sda1 my-partition
+cryptsetup luksFormat /dev/sda2
+cryptsetup open --type luks /dev/sda2 my-partition
 mkfs.ext4 -L my-root /dev/mapper/my-partition
 @end example
 
@@ -8688,11 +8688,11 @@ by @code{guix system init} afterwards.
 Finally, if you plan to use one or more swap partitions (@pxref{Memory
 Concepts, swap space,, libc, The GNU C Library Reference Manual}), make
 sure to initialize them with @command{mkswap}.  Assuming you have one
-swap partition on @file{/dev/sda2}, you would run:
+swap partition on @file{/dev/sda3}, you would run:
 
 @example
-mkswap /dev/sda2
-swapon /dev/sda2
+mkswap /dev/sda3
+swapon /dev/sda3
 @end example
 
 Alternatively, you may use a swap file.  For example, assuming that in
-- 
2.18.0

I'm not sure how to best resolve the first issue.  I suppose we can
mention that if unsure which GRUB to use, the user can test whether
"/sys/firmware/efi" exists on the live image.

We could also make it clearer when booting whether the installer is in
"UEFI" mode or not.