From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:52592) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dAc90-0004XY-3K for guix-patches@gnu.org; Tue, 16 May 2017 09:04:13 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dAc8w-0005yf-TB for guix-patches@gnu.org; Tue, 16 May 2017 09:04:06 -0400 Received: from debbugs.gnu.org ([208.118.235.43]:44866) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dAc8w-0005xu-OJ for guix-patches@gnu.org; Tue, 16 May 2017 09:04:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1dAc8w-0005yi-Bv for guix-patches@gnu.org; Tue, 16 May 2017 09:04:02 -0400 Subject: bug#26339: [PATCH] doc: Adapt to multiple bootloader support. References: <20170402134916.2871-1-m.othacehe@gmail.com> In-Reply-To: <20170402134916.2871-1-m.othacehe@gmail.com> Resent-Message-ID: From: Mathieu Othacehe Date: Tue, 16 May 2017 15:03:06 +0200 Message-Id: <20170516130306.10414-1-m.othacehe@gmail.com> List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+kyle=kyleam.com@gnu.org Sender: "Guix-patches" To: 26339@debbugs.gnu.org * doc/guix.texi (GRUB configuration): Rename to "Bootloader configuration". [menu-entry]: Switch to "boot-parameters" and adapt fields. Adapt occurences of "GRUB" in other sections. --- Hi, Here's the doc patch. While writting it, I noticed that using for 's menu-entry fields was maybe not a good idea. has no default values and it might be hard to understand by final users. WDYT ? Thanks, Mathieu doc/guix.texi | 208 +++++++++++++++++++++++++++++++++------------------------- 1 file changed, 118 insertions(+), 90 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 7baf6ee38..455dbbc84 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -198,7 +198,7 @@ System Configuration * X.509 Certificates:: Authenticating HTTPS servers. * Name Service Switch:: Configuring libc's name service switch. * Initial RAM Disk:: Linux-Libre bootstrapping. -* GRUB Configuration:: Configuring the boot loader. +* Bootloader Configuration:: Configuring the boot loader. * Invoking guix system:: Instantiating a system configuration. * Running GuixSD in a VM:: How to run GuixSD in a virtual machine. * Defining Services:: Adding new service definitions. @@ -7731,7 +7731,7 @@ instance to support new system services. * X.509 Certificates:: Authenticating HTTPS servers. * Name Service Switch:: Configuring libc's name service switch. * Initial RAM Disk:: Linux-Libre bootstrapping. -* GRUB Configuration:: Configuring the boot loader. +* Bootloader Configuration:: Configuring the boot loader. * Invoking guix system:: Instantiating a system configuration. * Running GuixSD in a VM:: How to run GuixSD in a virtual machine. * Defining Services:: Adding new service definitions. @@ -7914,7 +7914,7 @@ system, should you ever need to. Speaking of roll-back, each time you run @command{guix system reconfigure}, a new @dfn{generation} of the system is created---without modifying or deleting previous generations. Old system generations get -an entry in the GRUB boot menu, allowing you to boot them in case +an entry in the bootloader boot menu, allowing you to boot them in case something went wrong with the latest generation. Reassuring, no? The @command{guix system list-generations} command lists the system generations available on disk. It is also possible to roll back the @@ -7970,7 +7970,7 @@ 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{GRUB Configuration}. +The system bootloader configuration object. @xref{Bootloader Configuration}. @item @code{initrd} (default: @code{base-initrd}) @cindex initrd @@ -15229,32 +15229,41 @@ upon booting. All the derivations referenced by @var{exp} are automatically copied to the initrd. @end deffn -@node GRUB Configuration -@subsection GRUB Configuration +@node Bootloader Configuration +@subsection Bootloader Configuration -@cindex GRUB +@cindex Bootloader @cindex boot loader -The operating system uses GNU@tie{}GRUB as its boot loader -(@pxref{Overview, overview of GRUB,, grub, GNU GRUB Manual}). It is -configured using a @code{grub-configuration} declaration. This data type -is exported by the @code{(gnu system grub)} module and described below. +The operating system supports multiple bootloaders. The bootloader is +configured using @code{bootloader-configuration} declaration. All the +fields of this structure are bootloader agnostic except for one field, +@code{bootloader} that indicates the bootloader to be configured and +installed. -@deftp {Data Type} grub-configuration -The type of a GRUB configuration declaration. +Note that all fields of @code{bootloader-configuration} are not +necessarily handled by all GuixSD supported bootloaders. + +@deftp {Data Type} bootloader-configuration +The type of a bootloader configuration declaration. @table @asis +@item @code{bootloader} +The bootloader to use, as a @code{bootloader} object. For now +@code{grub}, @code{grub-efi} and @code{syslinux} are supported. + @item @code{device} This is a string denoting the boot device. It must be a device name -understood by the @command{grub-install} command, such as -@code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub, +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}). @item @code{menu-entries} (default: @code{()}) -A possibly empty list of @code{menu-entry} objects (see below), denoting -entries to appear in the GRUB boot menu, in addition to the current -system entry and the entry pointing to previous system generations. +A possibly empty list of @code{boot-parameters} objects (see below), +denoting entries to appear in the bootloader menu, in addition to the +current system entry and the entry pointing to previous system +generations. @item @code{default-entry} (default: @code{0}) The index of the default boot menu entry. Index 0 is for the entry of the @@ -15264,37 +15273,37 @@ current system. The number of seconds to wait for keyboard input before booting. Set to 0 to boot immediately, and to -1 to wait indefinitely. -@item @code{theme} (default: @var{%default-theme}) -The @code{grub-theme} object describing the theme to use. - -@item @code{grub} (default: @code{grub}) -The GRUB package to use. +@item @code{theme} (default: @var{#f}) +The bootloader theme object describing the theme to use. If no theme +is provided, some bootloaders might use a default theme, that's true +for GRUB. @item @code{terminal-outputs} (default: @code{'gfxterm}) -The output terminals used for the GRUB boot menu, as a list of symbols. -These values are accepted: @code{console}, @code{serial}, -@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text}, @code{mda_text}, -@code{morse}, and @code{pkmodem}. This field corresponds to the GRUB -variable GRUB_TERMINAL_OUTPUT (@pxref{Simple configuration,,, grub,GNU -GRUB manual}). +The output terminals used for the bootloader boot menu, as a list of +symbols. GRUB accepts the values: @code{console}, @code{serial}, +@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text}, +@code{mda_text}, @code{morse}, and @code{pkmodem}. This field +corresponds to the GRUB variable GRUB_TERMINAL_OUTPUT (@pxref{Simple +configuration,,, grub,GNU GRUB manual}). @item @code{terminal-inputs} (default: @code{'()}) -The input terminals used for the GRUB boot menu, as a list of symbols. -The default is the native platform terminal as determined by GRUB at -run-time. These values are accepted: @code{console}, @code{serial}, -@code{serial_@{0-3@}}, @code{at_keyboard}, and @code{usb_keyboard}. -This field corresponds to the GRUB variable GRUB_TERMINAL_INPUT -(@pxref{Simple configuration,,, grub,GNU GRUB manual}). +The input terminals used for the bootloader boot menu, as a list of +symbols. For GRUB, the default is the native platform terminal as +determined at run-time. GRUB accepts the values: @code{console}, +@code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and +@code{usb_keyboard}. This field corresponds to the GRUB variable +GRUB_TERMINAL_INPUT (@pxref{Simple configuration,,, grub,GNU GRUB +manual}). @item @code{serial-unit} (default: @code{#f}) -The serial unit used by GRUB, as an integer from 0 to 3. The default -value is chosen by GRUB at run-time; currently GRUB chooses 0, which +The serial unit used by the bootloader, as an integer from 0 to 3. +For GRUB it is choosen at run-time; currently GRUB chooses 0, which corresponds to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}). @item @code{serial-speed} (default: @code{#f}) -The speed of the serial interface, as an integer. The default value is -chosen by GRUB at run-time; currently GRUB chooses 9600@tie{}bps -(@pxref{Serial terminal,,, grub,GNU GRUB manual}). +The speed of the serial interface, as an integer. For GRUB, the +default value is chosen at run-time; currently GRUB chooses +9600@tie{}bps (@pxref{Serial terminal,,, grub,GNU GRUB manual}). @end table @end deftp @@ -15303,38 +15312,68 @@ chosen by GRUB at run-time; currently GRUB chooses 9600@tie{}bps @cindex boot menu Should you want to list additional boot menu entries @i{via} the @code{menu-entries} field above, you will need to create them with the -@code{menu-entry} form. For example, imagine you want to be able to +@code{boot-parameters} form. For example, imagine you want to be able to boot another distro (hard to imagine!), you can define a menu entry along these lines: @example -(menu-entry +(boot-parameters (label "The Other Distro") - (linux "/boot/old/vmlinux-2.6.32") - (linux-arguments '("root=/dev/sda2")) + (root-device "my-root") + (boot-name 'grub) + (store-device "my-root") + (store-mount-point "/") + (kernel "/boot/old/vmlinux-2.6.32") + (kernel-arguments '("root=/dev/sda2")) (initrd "/boot/old/initrd")) @end example Details below. -@deftp {Data Type} menu-entry -The type of an entry in the GRUB boot menu. +@deftp {Data Type} boot-parameters +The type of an entry in the bootloader boot menu. @table @asis @item @code{label} The label to show in the menu---e.g., @code{"GNU"}. -@item @code{linux} -The Linux kernel image to boot, for example: +@item @code{root-device} +The root device identifier. It has to correspond exactly to the device +field of the object representing the OS's root file +system, so it might be a device path like @code{"/dev/sda3"}. + +@item @code{boot-device} +The name of the bootloader used to boot this entry (@code{'grub} or +@code{'syslinux} for instance). + +@item @code{store-device} +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}). + +Depending on the bootloader, this may be a file system label (a +string), a file system UUID (a bytevector, @pxref{File Systems}), or +@code{#f}. If set to @code{#f}, GRUB 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{store-mount-point} +The mount point of the above device on the system. You probably want +to set it to @code{"/"}. GuixSD uses it to strip the prefix of store +file names for systems where @file{/gnu} or @file{/gnu/store} is on a +separate partition. + +@item @code{kernel} +The kernel image to boot, for example: @example (file-append linux-libre "/bzImage") @end example -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: +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" @@ -15343,40 +15382,27 @@ GNU GRUB manual}), for 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., +@item @code{kernel-arguments} +The list of extra kernel command-line arguments---e.g., @code{("console=ttyS0")}. @item @code{initrd} 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., the 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 GRUB 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: @code{"/"}) -The mount point of the above device on the system. You probably do not -need to change the default value. GuixSD uses it to strip the prefix of -store file names for systems where @file{/gnu} or @file{/gnu/store} is -on a separate partition. - @end table @end deftp @c FIXME: Write documentation once it's stable. -Themes are created using the @code{grub-theme} form, which is not -documented yet. +Fow now only GRUB has theme support. GRUB Themes are created using +the @code{grub-theme} form, which is not documented yet. @defvr {Scheme Variable} %default-theme -This is the default GRUB theme used by the operating system, with a -fancy background image displaying the GNU and Guix logos. +This is the default GRUB theme used by the operating system if no +@code{theme} field is specified in @code{bootloader-configuration} +record. + +It comes with a fancy background image displaying the GNU and Guix +logos. @end defvr @@ -15416,9 +15442,9 @@ list-generations}). If that generation already exists, it will be overwritten. This behavior mirrors that of @command{guix package} (@pxref{Invoking guix package}). -It also adds a GRUB menu entry for the new OS configuration, and moves -entries for older configurations to a submenu---unless -@option{--no-bootloader} is passed. +It also adds a bootloader menu entry for the new OS configuration, +---unless @option{--no-bootloader} is passed. For GRUB, it moves +entries for older configurations to a submenu. @quotation Note @c The paragraph below refers to the problem discussed at @@ -15432,11 +15458,12 @@ once @command{reconfigure} has completed. @item switch-generation @cindex generations Switch to an existing system generation. This action atomically -switches the system profile to the specified system generation. It also -rearranges the system's existing GRUB menu entries. It makes the menu -entry for the specified system generation the default, and it moves the -entries for the other generations to a submenu. The next time the -system boots, it will use the specified system generation. +switches the system profile to the specified system generation. It +also rearranges the system's existing bootloader menu entries. It +makes the menu entry for the specified system generation the default, +and it moves the entries for the other generations to a submenu. The +next time the system boots, it will use the specified system +generation. The target generation can be specified explicitly by its generation number. For example, the following invocation would switch to system @@ -15458,11 +15485,11 @@ guix system switch-generation -- -1 @end example Currently, the effect of invoking this action is @emph{only} to switch -the system profile to an existing generation and rearrange the GRUB 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 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. This action will fail if the specified generation does not exist. @@ -15497,8 +15524,9 @@ files, packages, and so on. It also creates other essential files needed for the system to operate correctly---e.g., the @file{/etc}, @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file. -This command also installs GRUB on the device specified in -@file{my-os-config}, unless the @option{--no-bootloader} option was passed. +This command also installs bootloader on the device specified in +@file{my-os-config}, unless the @option{--no-bootloader} option was +passed. @item vm @cindex virtual machine @@ -15638,7 +15666,7 @@ build users of the daemon (@pxref{Build Environment Setup}). Once you have built, configured, re-configured, and re-re-configured your GuixSD installation, you may find it useful to list the operating system generations available on disk---and that you can choose from the -GRUB boot menu: +bootloader boot menu: @table @code -- 2.13.0