doc: Adapt to multiple bootloader support.

* doc/guix.texi (GRUB configuration): Rename to "Bootloader
  configuration".
  Remove device-mount-point field from menu-entry description.
  Adapt occurences of "GRUB" in other sections.
This commit is contained in:
Mathieu Othacehe 2017-05-16 11:54:55 +02:00
parent 8b22107e5d
commit 74e6472451
No known key found for this signature in database
GPG Key ID: 8354763531769CA6
1 changed files with 98 additions and 79 deletions

View File

@ -199,7 +199,7 @@ System Configuration
* X.509 Certificates:: Authenticating HTTPS servers. * X.509 Certificates:: Authenticating HTTPS servers.
* Name Service Switch:: Configuring libc's name service switch. * Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping. * 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. * Invoking guix system:: Instantiating a system configuration.
* Running GuixSD in a VM:: How to run GuixSD in a virtual machine. * Running GuixSD in a VM:: How to run GuixSD in a virtual machine.
* Defining Services:: Adding new service definitions. * Defining Services:: Adding new service definitions.
@ -7797,7 +7797,7 @@ instance to support new system services.
* X.509 Certificates:: Authenticating HTTPS servers. * X.509 Certificates:: Authenticating HTTPS servers.
* Name Service Switch:: Configuring libc's name service switch. * Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping. * 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. * Invoking guix system:: Instantiating a system configuration.
* Running GuixSD in a VM:: How to run GuixSD in a virtual machine. * Running GuixSD in a VM:: How to run GuixSD in a virtual machine.
* Defining Services:: Adding new service definitions. * Defining Services:: Adding new service definitions.
@ -7980,7 +7980,7 @@ system, should you ever need to.
Speaking of roll-back, each time you run @command{guix system Speaking of roll-back, each time you run @command{guix system
reconfigure}, a new @dfn{generation} of the system is created---without reconfigure}, a new @dfn{generation} of the system is created---without
modifying or deleting previous generations. Old system generations get 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 something went wrong with the latest generation. Reassuring, no? The
@command{guix system list-generations} command lists the system @command{guix system list-generations} command lists the system
generations available on disk. It is also possible to roll back the generations available on disk. It is also possible to roll back the
@ -8036,7 +8036,7 @@ List of strings or gexps representing additional arguments to pass on
the command-line of the kernel---e.g., @code{("console=ttyS0")}. the command-line of the kernel---e.g., @code{("console=ttyS0")}.
@item @code{bootloader} @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}) @item @code{initrd} (default: @code{base-initrd})
@cindex initrd @cindex initrd
@ -15711,32 +15711,52 @@ upon booting. All the derivations referenced by @var{exp} are
automatically copied to the initrd. automatically copied to the initrd.
@end deffn @end deffn
@node GRUB Configuration @node Bootloader Configuration
@subsection GRUB Configuration @subsection Bootloader Configuration
@cindex GRUB @cindex bootloader
@cindex boot loader @cindex boot loader
The operating system uses GNU@tie{}GRUB as its boot loader The operating system supports multiple bootloaders. The bootloader is
(@pxref{Overview, overview of GRUB,, grub, GNU GRUB Manual}). It is configured using @code{bootloader-configuration} declaration. All the
configured using a @code{grub-configuration} declaration. This data type fields of this structure are bootloader agnostic except for one field,
is exported by the @code{(gnu system grub)} module and described below. @code{bootloader} that indicates the bootloader to be configured and
installed.
@deftp {Data Type} grub-configuration Some of the bootloaders do not honor every field of
The type of a GRUB configuration declaration. @code{bootloader-configuration}. For instance, the extlinux
bootloader does not support themes and thus ignores the @code{theme}
field.
@deftp {Data Type} bootloader-configuration
The type of a bootloader configuration declaration.
@table @asis @table @asis
@item @code{bootloader}
@cindex EFI, bootloader
@cindex UEFI, bootloader
@cindex BIOS, bootloader
The bootloader to use, as a @code{bootloader} object. For now
@code{grub-bootloader}, @code{grub-efi-bootloader} and
@code{extlinux-bootloader} are supported. @code{grub-efi-bootloader},
allows to boot on modern systems using the @dfn{Unified Extensible
Firmware Interface} (UEFI).
Available bootloaders are described in @code{(gnu bootloader @dots{})}
modules.
@item @code{device} @item @code{device}
This is a string denoting the boot device. It must be a device name This is a string denoting the boot device. It must be a device name
understood by the @command{grub-install} command, such as understood by the bootloader @command{installer} command, such as
@code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub, @code{/dev/sda} or @code{(hd0)} (for GRUB, @pxref{Invoking grub-install,,, grub,
GNU GRUB Manual}). GNU GRUB Manual}).
@item @code{menu-entries} (default: @code{()}) @item @code{menu-entries} (default: @code{()})
A possibly empty list of @code{menu-entry} objects (see below), denoting 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 entries to appear in the bootloader menu, in addition to the current
system entry and the entry pointing to previous system generations. system entry and the entry pointing to previous system generations.
generations.
@item @code{default-entry} (default: @code{0}) @item @code{default-entry} (default: @code{0})
The index of the default boot menu entry. Index 0 is for the entry of the The index of the default boot menu entry. Index 0 is for the entry of the
@ -15746,42 +15766,37 @@ current system.
The number of seconds to wait for keyboard input before booting. Set to The number of seconds to wait for keyboard input before booting. Set to
0 to boot immediately, and to -1 to wait indefinitely. 0 to boot immediately, and to -1 to wait indefinitely.
@item @code{theme} (default: @var{%default-theme}) @item @code{theme} (default: @var{#f})
The @code{grub-theme} object describing the theme to use. The bootloader theme object describing the theme to use. If no theme
is provided, some bootloaders might use a default theme, that's true
@item @code{grub} (default: @code{grub}) for GRUB.
@cindex EFI, bootloader
@cindex UEFI, bootloader
@cindex BIOS, bootloader
The GRUB package to use. Currently either @code{grub}, for ``legacy''
x86 BIOS systems, or @code{grub-efi}, for modern systems using the
@dfn{Unified Extensible Firmware Interface} (UEFI).
@item @code{terminal-outputs} (default: @code{'gfxterm}) @item @code{terminal-outputs} (default: @code{'gfxterm})
The output terminals used for the GRUB boot menu, as a list of symbols. The output terminals used for the bootloader boot menu, as a list of
These values are accepted: @code{console}, @code{serial}, symbols. GRUB accepts the values: @code{console}, @code{serial},
@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text}, @code{mda_text}, @code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text},
@code{morse}, and @code{pkmodem}. This field corresponds to the GRUB @code{mda_text}, @code{morse}, and @code{pkmodem}. This field
variable GRUB_TERMINAL_OUTPUT (@pxref{Simple configuration,,, grub,GNU corresponds to the GRUB variable GRUB_TERMINAL_OUTPUT (@pxref{Simple
GRUB manual}). configuration,,, grub,GNU GRUB manual}).
@item @code{terminal-inputs} (default: @code{'()}) @item @code{terminal-inputs} (default: @code{'()})
The input terminals used for the GRUB boot menu, as a list of symbols. The input terminals used for the bootloader boot menu, as a list of
The default is the native platform terminal as determined by GRUB at symbols. For GRUB, the default is the native platform terminal as
run-time. These values are accepted: @code{console}, @code{serial}, determined at run-time. GRUB accepts the values: @code{console},
@code{serial_@{0-3@}}, @code{at_keyboard}, and @code{usb_keyboard}. @code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and
This field corresponds to the GRUB variable GRUB_TERMINAL_INPUT @code{usb_keyboard}. This field corresponds to the GRUB variable
(@pxref{Simple configuration,,, grub,GNU GRUB manual}). GRUB_TERMINAL_INPUT (@pxref{Simple configuration,,, grub,GNU GRUB
manual}).
@item @code{serial-unit} (default: @code{#f}) @item @code{serial-unit} (default: @code{#f})
The serial unit used by GRUB, as an integer from 0 to 3. The default The serial unit used by the bootloader, as an integer from 0 to 3.
value is chosen by GRUB at run-time; currently GRUB chooses 0, which For GRUB it is choosen at run-time; currently GRUB chooses 0, which
corresponds to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}). corresponds to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
@item @code{serial-speed} (default: @code{#f}) @item @code{serial-speed} (default: @code{#f})
The speed of the serial interface, as an integer. The default value is The speed of the serial interface, as an integer. For GRUB, the
chosen by GRUB at run-time; currently GRUB chooses 9600@tie{}bps default value is chosen at run-time; currently GRUB chooses
(@pxref{Serial terminal,,, grub,GNU GRUB manual}). 9600@tie{}bps (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
@end table @end table
@end deftp @end deftp
@ -15805,7 +15820,7 @@ along these lines:
Details below. Details below.
@deftp {Data Type} menu-entry @deftp {Data Type} menu-entry
The type of an entry in the GRUB boot menu. The type of an entry in the bootloader menu.
@table @asis @table @asis
@ -15819,9 +15834,9 @@ The Linux kernel image to boot, for example:
(file-append linux-libre "/bzImage") (file-append linux-libre "/bzImage")
@end example @end example
It is also possible to specify a device explicitly in the file path For GRUB, it is also possible to specify a device explicitly in the
using GRUB's device naming convention (@pxref{Naming convention,,, grub, file path using GRUB's device naming convention (@pxref{Naming
GNU GRUB manual}), for example: convention,,, grub, GNU GRUB manual}), for example:
@example @example
"(hd0,msdos1)/boot/vmlinuz" "(hd0,msdos1)/boot/vmlinuz"
@ -15837,33 +15852,30 @@ The list of extra Linux kernel command-line arguments---e.g.,
@item @code{initrd} @item @code{initrd}
A G-Expression or string denoting the file name of the initial RAM disk A G-Expression or string denoting the file name of the initial RAM disk
to use (@pxref{G-Expressions}). to use (@pxref{G-Expressions}).
@item @code{device} (default: @code{#f}) @item @code{device} (default: @code{#f})
The device where the kernel and initrd are to be found---i.e., the GRUB 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}). @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 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 bytevector, @pxref{File Systems}), or @code{#f}, in which case
search the device containing the file specified by the @code{linux} the bootloader will search the device containing the file specified by
field (@pxref{search,,, grub, GNU GRUB manual}). It must @emph{not} be the @code{linux} field (@pxref{search,,, grub, GNU GRUB manual}). It
an OS device name such as @file{/dev/sda1}. 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 table
@end deftp @end deftp
@c FIXME: Write documentation once it's stable. @c FIXME: Write documentation once it's stable.
Themes are created using the @code{grub-theme} form, which is not Fow now only GRUB has theme support. GRUB themes are created using
documented yet. the @code{grub-theme} form, which is not documented yet.
@defvr {Scheme Variable} %default-theme @defvr {Scheme Variable} %default-theme
This is the default GRUB theme used by the operating system, with a This is the default GRUB theme used by the operating system if no
fancy background image displaying the GNU and Guix logos. @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 @end defvr
@ -15903,9 +15915,10 @@ list-generations}). If that generation already exists, it will be
overwritten. This behavior mirrors that of @command{guix package} overwritten. This behavior mirrors that of @command{guix package}
(@pxref{Invoking guix package}). (@pxref{Invoking guix package}).
It also adds a GRUB menu entry for the new OS configuration, and moves It also adds a bootloader menu entry for the new OS configuration,
entries for older configurations to a submenu---unless ---unless @option{--no-bootloader} is passed. For GRUB, it moves
@option{--no-bootloader} is passed. entries for older configurations to a submenu, allowing you to choose
an older system generation at boot time should you need it.
@quotation Note @quotation Note
@c The paragraph below refers to the problem discussed at @c The paragraph below refers to the problem discussed at
@ -15919,11 +15932,16 @@ once @command{reconfigure} has completed.
@item switch-generation @item switch-generation
@cindex generations @cindex generations
Switch to an existing system generation. This action atomically Switch to an existing system generation. This action atomically
switches the system profile to the specified system generation. It also switches the system profile to the specified system generation. It
rearranges the system's existing GRUB menu entries. It makes the menu also rearranges the system's existing bootloader menu entries. It
entry for the specified system generation the default, and it moves the makes the menu entry for the specified system generation the default,
entries for the other generations to a submenu. The next time the and it moves the entries for the other generatiors to a submenu, if
system boots, it will use the specified system generation. supported by the bootloader being used. The next time the system
boots, it will use the specified system generation.
The bootloader itself is not being reinstalled when using this
command. Thus, the installed bootloader is used with an updated
configuration file.
The target generation can be specified explicitly by its generation The target generation can be specified explicitly by its generation
number. For example, the following invocation would switch to system number. For example, the following invocation would switch to system
@ -15945,11 +15963,11 @@ guix system switch-generation -- -1
@end example @end example
Currently, the effect of invoking this action is @emph{only} to switch Currently, the effect of invoking this action is @emph{only} to switch
the system profile to an existing generation and rearrange the GRUB menu the system profile to an existing generation and rearrange the
entries. To actually start using the target system generation, you must bootloader menu entries. To actually start using the target system
reboot after running this action. In the future, it will be updated to generation, you must reboot after running this action. In the future,
do the same things as @command{reconfigure}, like activating and it will be updated to do the same things as @command{reconfigure},
deactivating services. like activating and deactivating services.
This action will fail if the specified generation does not exist. This action will fail if the specified generation does not exist.
@ -15984,8 +16002,9 @@ files, packages, and so on. It also creates other essential files
needed for the system to operate correctly---e.g., the @file{/etc}, needed for the system to operate correctly---e.g., the @file{/etc},
@file{/var}, and @file{/run} directories, and the @file{/bin/sh} file. @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
This command also installs GRUB on the device specified in This command also installs bootloader on the device specified in
@file{my-os-config}, unless the @option{--no-bootloader} option was passed. @file{my-os-config}, unless the @option{--no-bootloader} option was
passed.
@item vm @item vm
@cindex virtual machine @cindex virtual machine
@ -16125,7 +16144,7 @@ build users of the daemon (@pxref{Build Environment Setup}).
Once you have built, configured, re-configured, and re-re-configured Once you have built, configured, re-configured, and re-re-configured
your GuixSD installation, you may find it useful to list the operating your GuixSD installation, you may find it useful to list the operating
system generations available on disk---and that you can choose from the system generations available on disk---and that you can choose from the
GRUB boot menu: bootloader boot menu:
@table @code @table @code