@@ -11064,35 +11064,66 @@ along these lines:
@example
(menu-entry
(label "The Other Distro")
- (linux "/boot/old/vmlinux-2.6.32")
+ (device #f)
+ (linux "(hd0,msdos2)/boot/old/vmlinux-2.6.32")
(linux-arguments '("root=/dev/sda2"))
- (initrd "/boot/old/initrd"))
+ (initrd "(hd0,msdos2)/boot/old/initrd"))
@end example
Details below.
@deftp {Data Type} menu-entry
-The type of an entry in the GRUB boot menu.
+The type of an entry in the GRUB boot menu. Below, the phrase
+``string-valued G-Expression'' means a string or any object which can be
+inserted (via @code{ungexp}) as a string in a G-Expression
+(@pxref{G-Expressions}).
@table @asis
@item @code{label}
-The label to show in the menu---e.g., @code{"GNU"}.
+The label to show in the menu---e.g., @code{"GNU"}. This is a string-valued G-Expression.
@item @code{linux}
-The Linux kernel image to boot, for example:
+The Linux kernel image to boot. This is a string-valued G-Expression.
+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:
+
+@example
+"(hd0,msdos1)/bzImage"
+@end example
+
+If the device is specified explicitly as above, then the @code{device}
+field is ignored entirely.
+
+@item @code{device}
+The device to use as GRUB's root for this menu entry (@pxref{root,,,
+grub, GNU GRUB manual}). This may be a file system label (a string), a
+file system UUID (@pxref{File Systems}), or @code{#f}, in which case
+GRUB will automatically find the device containing the file specified by
+the @code{linux} field via a file-based search (@pxref{search,,, grub,
+GNU GRUB manual}).
+
+@c For details, see (guix gnu system).
+Currently, the @code{device} field is not suitable for use in custom
+menu entries. Therefore, if you need to specify a custom menu entry,
+for now it is best to just pass a dummy value to it (such as @code{#f})
+and specify the device explicitly using GRUB's device naming convention,
+as in the example above.
+
@item @code{linux-arguments} (default: @code{()})
The list of extra Linux kernel command-line arguments---e.g.,
-@code{("console=ttyS0")}.
+@code{("console=ttyS0")}. This is a list of string-valued
+G-Expressions.
@item @code{initrd}
-A G-Expression or string denoting the file name of the initial RAM disk
-to use (@pxref{G-Expressions}).
+The initial RAM disk file to use. This is a string-valued G-Expression.
@end table
@end deftp
@@ -11126,8 +11157,9 @@ supported:
@table @code
@item reconfigure
Build the operating system described in @var{file}, activate it, and
-switch to it@footnote{This action is usable only on systems already
-running GuixSD.}.
+switch to it@footnote{This action and the related actions
+@code{switch-generation} and @code{roll-back}) are usable only on
+systems already running GuixSD.}.
This effects all the configuration specified in @var{file}: user
accounts, system services, global package list, setuid programs, etc.
@@ -11149,6 +11181,44 @@ guix pull}). Failing to do that you would see an older version of Guix
once @command{reconfigure} has completed.
@end quotation
+@item switch-generation
+Switch to an existing system generation. This action rearranges the
+existing GRUB menu entries. It makes the menu entry for the target
+system generation the default, and it moves the entries for the other
+system 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
+generation 7:
+
+@example
+guix system switch-generation 7
+@end example
+
+The target generation can also be specified relative to the current
+generation with the form @code{+N} or @code{-N}, where @code{+3} means
+``3 generations ahead of the current generation,'' and @code{-1} means
+``1 generation prior to the current generation.''
+
+Currently, the effect of invoking this action is only to rearrange the
+GRUB menu entries. Therefore, 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.
+
+@item roll-back
+Switch to the preceding system generation. The next time the system
+boots, it will use the preceding system generation. This is the inverse
+of @command{reconfigure}, and it is exactly the same as invoking
+@code{switch-generation -1}.
+
+Currently, as with @command{switch-system}, you must reboot after
+running this action to actually start using the preceding system
+generation.
+
@item build
Build the derivation of the operating system, which includes all the
configuration files and programs needed to boot and run the system.
@@ -65,6 +65,10 @@
(define (strip-mount-point mount-point file)
"Strip MOUNT-POINT from FILE, which is a gexp or other lowerable
object denoting a file name."
+ ;; TODO: gracefully handle the case where the file resides in a location
+ ;; outside of the store, for example "/home/alice/vmlinuz". Currently, any
+ ;; attempt to create a custom <menu-entry> with a 'linux' field set to
+ ;; something like that will likely result in an un-bootable GRUB entry.
(if (string=? mount-point "/")
file
#~(let ((file #$file))
@@ -704,7 +704,7 @@ building anything."
(define (show-help)
(display (_ "Usage: guix system [OPTION ...] ACTION [ARG ...] [FILE]
Build the operating system declared in FILE according to ACTION.
-Some ACTIONS support additional ARGS.\n"))
+Some ACTIONS support additional ARGS. See 'info guix' for details.\n"))
(newline)
(display (_ "The valid values for ACTION are:\n"))
(newline)