From mboxrd@z Thu Jan 1 00:00:00 1970 From: cmmarusich@gmail.com Subject: [PATCH 10/10] Mention new 'guix system' features in the manual Date: Fri, 28 Oct 2016 03:07:27 -0700 Message-ID: <20161028100727.1182-11-cmmarusich@gmail.com> References: <20161028100727.1182-1-cmmarusich@gmail.com> Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:56872) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c044q-0004VJ-Bm for guix-devel@gnu.org; Fri, 28 Oct 2016 06:07:57 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c044o-00042i-OE for guix-devel@gnu.org; Fri, 28 Oct 2016 06:07:56 -0400 Received: from mail-pf0-x244.google.com ([2607:f8b0:400e:c00::244]:34593) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1c044o-00041l-BV for guix-devel@gnu.org; Fri, 28 Oct 2016 06:07:54 -0400 Received: by mail-pf0-x244.google.com with SMTP id u84so875073pfj.1 for ; Fri, 28 Oct 2016 03:07:54 -0700 (PDT) In-Reply-To: <20161028100727.1182-1-cmmarusich@gmail.com> List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: guix-devel@gnu.org From: Chris Marusich * doc/guix.texi (GRUB Configuration, Invoking guix system): Mention the new field 'device', update the custom example, and mention the new actions 'guix system roll-back' and 'guix system switch-generation' in the manual. * gnu/system/grub.scm (strip-mount-point): Add a TODO comment. * guix/scripts/system.scm (show-help): Point users to the manual for details. --- doc/guix.texi | 90 +++++++++++++++++++++++++++++++++++++++++++------ gnu/system/grub.scm | 4 +++ guix/scripts/system.scm | 2 +- 3 files changed, 85 insertions(+), 11 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 1293b8b..26fb930 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -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. diff --git a/gnu/system/grub.scm b/gnu/system/grub.scm index d45fdca..5b520ca 100644 --- a/gnu/system/grub.scm +++ b/gnu/system/grub.scm @@ -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 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)) diff --git a/guix/scripts/system.scm b/guix/scripts/system.scm index 2ee145a..54c6eeb 100644 --- a/guix/scripts/system.scm +++ b/guix/scripts/system.scm @@ -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) -- 2.9.2