Re: feedback as solicited by Guix manual (Section 7.1.5)

[Ethan Stefan Day <esday@ethan-stefan.net>]

[-- Attachment #1: Type: text/plain, Size: 4626 bytes --]



On 05/31/2016 02:35 PM, Matthew Jordan wrote:
> 
> I just looked ouver the installation part of the manual.
> 
>> What parts do you think should be added to our manual? A number of these
>> steps are already covered in section 7.1 System Installation.
> 
> That was mostly a copy paste from my notes.  But what I wouldn't mind
> seeing in the manual is as follows;
> 
> 1. Section 7.1.4.2 Networking;
> 
> mentions using ifconfig, correct me if I"m wrong but isn't ifconfig
> considered deprecated?
> 
> In which case iproute2 commands could be used;
> 
> $ ip link show
> $ ip link set ens3 up
> 
> 2. Section 7.1.4.3 Disk Partitioning
> 
> It would be nice to indicate that you may need additional swap space to
> build the various packages that come with the install.  Also sufficient
> space under /tmp is needed. In my case I had to bind mount the my tmp
> partition from the install target, and turn on the swap to achieve a
> successful install. I used these commands to achieve that.
> 
> $ mount --bind /mnt/tmp /tmp
> $ swapon /dev/sda3
> 
>> Personally, I don't like putting instructions on how to use 3rd party
>> software in manuals such as ours (or the Gentoo or Arch manuals) unless
>> the information is very specific to how we use the software.
>>
>> In my opinion, if there is some deficiency with the 3rd party programs'
>> documentation, that documentation should be improved.
>>
>> Otherwise, knowledge is fragmented into a variety of places where it
>> probably won't be updated as the 3rd party software changes. Also, each
>> system's manual or wiki will invariably contain some info that is
>> specific to that system but not declared as such. And the new, external
>> documentation will probably not be reviewed by the upstream maintainers
>> for correctness, spreading bad advice across the internet.  Finally, the
>> upstream manual will *still* not be improved.
>>
>> On the other hand, we should strive to make our system as easy to
>> install as possible. So, specific advice is most welcome! :)
> 
> While these are valid points, and I have to say I agree with them. Even
> Gentoo and Arch (which are among some of the more challenging distros),
> do provide some example/recipe to assist with partitioning.  I'm not
> saying we quote someone's manual, but someone might find it useful.
> 
> We could always indicate that one should refer to upstream manual for
> the latest info, and still provide some steps based on a partitioning
> plan. I think this would be very helpful to those who may not be fully
> verse in partitioning.  My first time using Gentoo was pretty decent
> because of the documentation provided. Here is the appropriate snippet
> from my notes;
> 
> Paritioning plan
> Assumming disk is 20GiB
> Bootloader 2MiB
> /boot 300MiB ext2/4
> Swap 1GiB
> / (rest of disk space) ext4
> 
> $ lsblk
> Start parted shell
> $ parted -a optimal /dev/sda
> (parted) unit MiB
> (parted) mklabel gpt
> (parted) mkpart primary 1MiB 3MiB
> (parted) name 1 grub
> (parted) set 1 bios_grub on
> (parted) print
> (parted) mkpart primary 3MiB 303MiB
> (parted) name 2 boot
> (parted) print
> 
> Calculation on host with zsh shell
> $ ((mib = 1 * (1024 ** 1)))
> $ print ${mib}
> 1024
> $ print $((mib + 303))
> 1327
> 
> (parted) mkpart primary 303MiB 1327MiB
> (parted) name 3 swap
> (parted) print
> (parted) mkpart primary 1327MiB -1
> (parted) name 4 root
> (parted) set 2 boot on
> (parted) print
> (parted) quit

From what I've gathered, it seems you should not need to both make a
bios_grub partition and toggle the boot flag on another.

> Of course feel free free to accept/reject these ideas, as they are just
> suggestions based on my state understanding when I first discovered Guix &
> GuixSD.  I like to think of Guix as the next evolution of Linux from
> Arch Linux or Gentoo Linux ^_^.
> 
> Respectfully,
> 

Parted is quite user-friendly.  The problem, for me at least, was not so
much use of the tools, but rather background knowledge about disk
partitioning in general.  The information I can find via web searching
is scattered.  The ideal solution would be to link to the GNU Storage
Guide, like the Parted manual does.  Unfortunately, that document does
not seem to exist, and I am not qualified to write it.  Other
distributions seem to get around this problem by providing an automated
partitioning tool and/or providing examples that work on a wide class of
machines.  Attached is a context diff for guix.texi in the git
repository that expands the partitioning example in a way that I suspect
will work on most modern (and perhaps higher-end) machines.

-Ethan Day


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: guix.texi.diff --]
[-- Type: text/x-patch; name="guix.texi.diff", Size: 4328 bytes --]

*** guix.texi	2016-05-31 16:07:52.443176978 -0400
--- guix-mod.texi	2016-05-31 16:36:07.895090213 -0400
***************
*** 5955,5961 ****
  
  Once this is done, you should be able to reboot the system and boot from
  the USB stick.  The latter usually requires you to get in the BIOS' boot
! menu, where you can choose to boot from the USB stick.
  
  @node Preparing for Installation
  @subsection Preparing for Installation
--- 5955,5962 ----
  
  Once this is done, you should be able to reboot the system and boot from
  the USB stick.  The latter usually requires you to get in the BIOS' boot
! menu, where you can choose to boot from the USB stick.  You may have to
! disable UEFI boot.
  
  @node Preparing for Installation
  @subsection Preparing for Installation
***************
*** 6069,6078 ****
  The installation image includes several partitioning tools, including
  Parted (@pxref{Overview,,, parted, GNU Parted User Manual}),
  @command{fdisk}, and @command{cfdisk}.  Run it and set up your disk with
! the partition layout you want:
  
  @example
! cfdisk
  @end example
  
  Once you are done partitioning the target hard disk drive, you have to
--- 6070,6090 ----
  The installation image includes several partitioning tools, including
  Parted (@pxref{Overview,,, parted, GNU Parted User Manual}),
  @command{fdisk}, and @command{cfdisk}.  Run it and set up your disk with
! the partition layout you want.  The following example assumes your
! motherboard supports GPT partition tables, and will render all data
! currently on your drive inaccessible.  Make sure you @code{select}
! the device you want to install GuixSD on.
  
  @example
! # parted
! (parted) print all
! (parted) select /dev/sda
! (parted) mklabel gpt
! (parted) mkpart primary 1MiB 2MiB
! (parted) toggle 1 bios_grub
! (parted) mkpart primary 2MiB 100%
! (parted) print
! (parted) quit
  @end example
  
  Once you are done partitioning the target hard disk drive, you have to
***************
*** 6089,6095 ****
  @code{my-root} can be created with:
  
  @example
! mkfs.ext4 -L my-root /dev/sda1
  @end example
  
  @c FIXME: Uncomment this once GRUB fully supports encrypted roots.
--- 6101,6107 ----
  @code{my-root} can be created with:
  
  @example
! mkfs.ext4 -L my-root /dev/sda2
  @end example
  
  @c FIXME: Uncomment this once GRUB fully supports encrypted roots.
***************
*** 6098,6104 ****
  @c @example
  @c # fdisk /dev/sdX
  @c @dots{} Create partitions etc.@dots{}
! @c # cryptsetup luksFormat /dev/sdX1
  @c # cryptsetup open --type luks /dev/sdX1 my-partition
  @c # mkfs.ext4 -L my-root /dev/mapper/my-partition
  @c @end example
--- 6110,6116 ----
  @c @example
  @c # fdisk /dev/sdX
  @c @dots{} Create partitions etc.@dots{}
! @c # cryptsetup luksFormat /dev/sdX2
  @c # cryptsetup open --type luks /dev/sdX1 my-partition
  @c # mkfs.ext4 -L my-root /dev/mapper/my-partition
  @c @end example
***************
*** 6108,6127 ****
  Cryptsetup/LUKS for disk encryption.
  
  Once that is done, mount the target root partition under @file{/mnt}
! with a command like (again, assuming @file{/dev/sda1} is the root
  partition):
  
  @example
! mount /dev/sda1 /mnt
  @end example
  
  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:
  
  @example
! mkswap /dev/sda2
  @end example
  
  @node Proceeding with the Installation
--- 6120,6139 ----
  Cryptsetup/LUKS for disk encryption.
  
  Once that is done, mount the target root partition under @file{/mnt}
! with a command like (again, assuming @file{/dev/sda2} is the root
  partition):
  
  @example
! mount /dev/sda2 /mnt
  @end example
  
  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/sda3}, you would run:
  
  @example
! mkswap /dev/sda3
  @end example
  
  @node Proceeding with the Installation