From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms11 with LMTPS id AMJoDL03BGD6dQAA0tVLHw (envelope-from ) for ; Sun, 17 Jan 2021 13:12:29 +0000 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0 with LMTPS id eGQ5CL03BGAZbQAA1q6Kng (envelope-from ) for ; Sun, 17 Jan 2021 13:12:29 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id E5BAC9403AC for ; Sun, 17 Jan 2021 13:12:24 +0000 (UTC) Received: from localhost ([::1]:58980 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1l17qw-0006Nu-9b for larch@yhetil.org; Sun, 17 Jan 2021 08:12:22 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:54544) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1l17qZ-0006Nf-SE for help-guix@gnu.org; Sun, 17 Jan 2021 08:12:01 -0500 Received: from mx1.dismail.de ([78.46.223.134]:49061) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1l17qV-0000Yu-2w; Sun, 17 Jan 2021 08:11:59 -0500 Received: from mx1.dismail.de (localhost [127.0.0.1]) by mx1.dismail.de (OpenSMTPD) with ESMTP id d20b7cda; Sun, 17 Jan 2021 14:11:46 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=dismail.de; h=from:to:cc :subject:date:message-id:in-reply-to:references:mime-version :content-transfer-encoding; s=20190914; bh=OvzW/gB+0nnzOw1hPAFgx 2+pbTZNyecMaR3InsLGmBI=; b=RSYG67GLzHGcrI8dIU7dFvqKYfCwaAV390m/G UdyqettRdFm7Z4T+b4dvKLkBPcGTW5o7t+rq6dQsSzqKOIk5KyCc340MjaCphiy4 LEgLgTCzd31mY18xcKd6YmFXjxSRdk82Buo9NPshWfZ+tigoXUZYgFReF6/pAUk3 lqj3Di8ZHtY7rTQUKeSR1dTIjMuD1JnzP8gIvdOIvtPZf8Kjoc+uiYWpkIGetmGe +txCyfHAzW9fJKE5iXxAFupmR1DbpQbGBkjotXv5Gni5IBtq2I75oUNXCNuDNLCe XBiaN992t5apIO4Q2de3jltMtl4p1TbM0SkfF4DRRKGlHfsfg== Received: from smtp1.dismail.de ( [10.240.26.11]) by mx1.dismail.de (OpenSMTPD) with ESMTP id 4245e1d2; Sun, 17 Jan 2021 14:11:46 +0100 (CET) Received: from smtp1.dismail.de (localhost [127.0.0.1]) by smtp1.dismail.de (OpenSMTPD) with ESMTP id 50b6086e; Sun, 17 Jan 2021 14:11:46 +0100 (CET) Received: by dismail.de (OpenSMTPD) with ESMTPSA id 56538145 (TLSv1.3:AEAD-AES256-GCM-SHA384:256:NO); Sun, 17 Jan 2021 14:11:45 +0100 (CET) From: Joshua Branson To: othacehe@gnu.org Subject: [PATCH] * doc/guix-cookbook.texi (Guix System Image API): new section Date: Sun, 17 Jan 2021 08:10:53 -0500 Message-Id: <20210117131053.32763-1-jbranso@dismail.de> X-Mailer: git-send-email 2.30.0 In-Reply-To: <87sg73xuks.fsf@dismail.de> References: <87sg73xuks.fsf@dismail.de> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Received-SPF: pass client-ip=78.46.223.134; envelope-from=jbranso@dismail.de; helo=mx1.dismail.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: help-guix@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: help-guix@gnu.org, Joshua Branson Errors-To: help-guix-bounces+larch=yhetil.org@gnu.org Sender: "Help-Guix" X-Migadu-Flow: FLOW_IN X-Migadu-Spam-Score: 2.52 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=dismail.de header.s=20190914 header.b=RSYG67GL; dmarc=pass (policy=reject) header.from=dismail.de; spf=pass (aspmx1.migadu.com: domain of help-guix-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=help-guix-bounces@gnu.org X-Migadu-Queue-Id: E5BAC9403AC X-Spam-Score: 2.52 X-Migadu-Scanner: scn1.migadu.com X-TUID: 3U1DiCPoysry --- doc/guix-cookbook.texi | 187 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index 54ab99558e..2bc8fe8a99 100644 --- a/doc/guix-cookbook.texi +++ b/doc/guix-cookbook.texi @@ -1353,6 +1353,7 @@ reference. @menu * Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System. +* Guix System Image API:: Customizing the disk-image to target specific platforms. * Connecting to Wireguard VPN:: Connecting to a Wireguard VPN. * Customizing a Window Manager:: Handle customization of a Window manager on Guix System. * Running Guix on a Linode Server:: Running Guix on a Linode Server @@ -1601,6 +1602,192 @@ likely that you'll need to modify the initrd on a machine using a custom kernel, since certain modules which are expected to be built may not be available for inclusion into the initrd. +@node Guix System Image API +@section Guix System Image API + +Historically, Guix System is centered around an @code{operating-system} +structure. This structure contains various fields ranging from the +bootloader and kernel declaration to the services to install. This is +useful to create an installer image, but the new Guix System image API +makes it possible to create an image that the user boots into directly. +For example, an image that targets the Beagleboard or PinePhone +directly. + +Turning an @code{operating-system} structure into a disk-image requires +additional information such as the image label, size and +partitioning. To this end, we can use the new @code{image} record. + +@lisp +(define-record-type* + image make-image + image? + (name image-name ;symbol + (default #f)) + (format image-format) ;symbol + (target image-target + (default #f)) + (size image-size ;size in bytes as integer + (default 'guess)) + (operating-system image-operating-system ; + (default #f)) + (partitions image-partitions ;list of + (default '())) + (compression? image-compression? ;boolean + (default #t)) + (volatile-root? image-volatile-root? ;boolean + (default #t)) + (substitutable? image-substitutable? ;boolean + (default #t))) +@end lisp + +This record also contains the operating-system to instantiate. The +@code{format} field defines the image type and can be @code{disk-image}, +@code{compressed-qcow2} or @code{iso9660}. In the future, it could be +extended to @code{docker} or other image types. + +A new directory in the Guix sources is dedicated to images definition. For now +there are two files: + +@itemize @bullet +@item +- @file{gnu/system/images/hurd.scm} + +@item +- @file{gnu/system/images/pine64.scm} + +@end itemize + +Let's have a look to @file{pine64.scm}. It contains the +@code{pine64-barebones-os} variable which is a minimal definition of an +operating-system dedicated to the @b{Pine A64 LTS} board. + +@lisp +(define pine64-barebones-os + (operating-system + (host-name "vignemale") + (timezone "Europe/Paris") + (locale "en_US.utf8") + (bootloader (bootloader-configuration + (bootloader u-boot-pine64-lts-bootloader) + (target "/dev/vda"))) + (initrd-modules '()) + (kernel linux-libre-arm64-generic) + (file-systems (cons (file-system + (device (file-system-label "my-root")) + (mount-point "/") + (type "ext4")) + %base-file-systems)) + (services (cons (service agetty-service-type + (agetty-configuration + (extra-options '("-L")) ; no carrier detect + (baud-rate "115200") + (term "vt100") + (tty "ttyS0"))) + %base-services)))) +@end lisp + +The @code{kernel} and @code{bootloader} fields are pointing to packages +dedicated to this board. + +Right below, the @code{pine64-image-type} variable is also defined. + +@lisp +(define pine64-image-type + (image-type + (name 'pine64-raw) + (constructor (cut image-with-os arm64-disk-image <>)))) +@end lisp + +It's using a record we haven't talked about yet, the @code{image-type} record, +defined this way: + +@lisp +(define-record-type* + image-type make-image-type + image-type? + (name image-type-name) ;symbol + (constructor image-type-constructor)) ; -> +@end lisp + +The main purpose of this record is to associate a name to a procedure +transforming an @code{operating-system} to an image. To understand why +it is necessary, let's have a look to the command producing a disk-image +from an @code{operating-system} configuration file: + +@example +guix system disk-image my-os.scm +@end example + +This command expects an @code{operating-system} configuration but how +should we indicate that we want an image targeting a Pine64 board? We +need to provide an extra information, the @code{image-type}, by passing +the @code{--image-type} or @code{-t} flag, this way: + +@example +guix system disk-image --image-type=pine64-raw my-os.scm +@end example + +This @code{image-type} parameter points to the @code{pine64-image-type} +defined above. Hence, the @code{operating-system} declared in +@code{my-os.scm} will be applied the @code{(cut image-with-os +arm64-disk-image <>)} procedure to turn it into an image. + +The resulting image looks like: + +@lisp +(image + (format 'disk-image) + (target "aarch64-linux-gnu") + (operating-system my-os) + (partitions + (list (partition + (inherit root-partition) + (offset root-offset))))) +@end lisp + +which is the aggregation of the @code{operating-system} defined in + @code{my-os.scm} to the @code{arm64-disk-image} record. + +But enough Scheme madness. What does this image API bring to the Guix user? + +One can run: + +@example +mathieu@@cervin:~$ guix system --list-image-types +The available image types are: + + - pine64-raw + - hurd-raw + - hurd-qcow2 + - iso9660 + - uncompressed-iso9660 + - raw + - qcow2 +@end example + +and by writing an @code{operating-system} file based on +@code{pine64-barebones-os} or @code{hurd-barebones-os} run: + +@example +guix system --image-type=pine64-raw my-pine-os.scm +@end example + +or, + +@example +guix system --image-type=hurd-raw my-hurd-os.scm +@end example + +to get a disk-image that can directly be written to a support and booted from. + +Without changing anything to @code{my-hurd-os.scm}, calling: + +@example +guix system --image-type=hurd-qcow2 my-hurd-os.scm +@end example + +will instead produce a Hurd QEMU image. + @node Connecting to Wireguard VPN @section Connecting to Wireguard VPN -- 2.30.0