summaryrefslogtreecommitdiff
path: root/doc/guix.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/guix.texi')
-rw-r--r--doc/guix.texi185
1 files changed, 103 insertions, 82 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index f69c84dea6..87aaae8545 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -37,7 +37,8 @@ Copyright @copyright{} 2017 Carlo Zancanaro@*
Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2017 humanitiesNerd@*
Copyright @copyright{} 2017 Christopher Allan Webber@*
-Copyright @copyright{} 2017 Marius Bakke
+Copyright @copyright{} 2017 Marius Bakke@*
+Copyright @copyright{} 2017 Hartmut Goebel
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -138,7 +139,7 @@ Programming Interface
Defining Packages
-* package Reference:: The package data type.
+* package Reference :: The package data type.
* origin Reference:: The origin data type.
Utilities
@@ -163,6 +164,7 @@ Invoking @command{guix build}
* Common Build Options:: Build options for most commands.
* Package Transformation Options:: Creating variants of packages.
* Additional Build Options:: Options specific to 'guix build'.
+* Debugging Build Failures:: Real life packaging experience.
GNU Distribution
@@ -199,7 +201,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.
@@ -4866,7 +4868,7 @@ described in the subsections below.
* Common Build Options:: Build options for most commands.
* Package Transformation Options:: Creating variants of packages.
* Additional Build Options:: Options specific to 'guix build'.
-* Debugging Build Failures:: Real life packaging experience
+* Debugging Build Failures:: Real life packaging experience.
@end menu
@node Common Build Options
@@ -7797,7 +7799,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.
@@ -7980,7 +7982,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
@@ -8036,7 +8038,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
@@ -15711,32 +15713,52 @@ 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.
+
+Some of the bootloaders do not honor every field of
+@code{bootloader-configuration}. For instance, the extlinux
+bootloader does not support themes and thus ignores the @code{theme}
+field.
-@deftp {Data Type} grub-configuration
-The type of a GRUB configuration declaration.
+@deftp {Data Type} bootloader-configuration
+The type of a bootloader configuration declaration.
@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}
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
+entries to appear in the bootloader menu, in addition to the current
system entry and the entry pointing to previous system generations.
+generations.
@item @code{default-entry} (default: @code{0})
The index of the default boot menu entry. Index 0 is for the entry of the
@@ -15746,42 +15768,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})
-@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{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
@@ -15805,7 +15822,7 @@ along these lines:
Details below.
@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
@@ -15819,9 +15836,9 @@ The Linux kernel image to boot, for 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"
@@ -15837,33 +15854,30 @@ The list of extra Linux kernel command-line arguments---e.g.,
@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
+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}).
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.
+bytevector, @pxref{File Systems}), or @code{#f}, in which case
+the bootloader 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}.
@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
@@ -15903,9 +15917,10 @@ 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, allowing you to choose
+an older system generation at boot time should you need it.
@quotation Note
@c The paragraph below refers to the problem discussed at
@@ -15919,11 +15934,16 @@ 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 generatiors to a submenu, if
+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
number. For example, the following invocation would switch to system
@@ -15945,11 +15965,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.
@@ -15984,8 +16004,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
@@ -16125,7 +16146,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