From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms11 with LMTPS id dnE7MsO5BWBlOwAA0tVLHw (envelope-from ) for ; Mon, 18 Jan 2021 16:39:31 +0000 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id IIrcLcO5BWBzAgAAB5/wlQ (envelope-from ) for ; Mon, 18 Jan 2021 16:39:31 +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 37F7E94042A for ; Mon, 18 Jan 2021 16:39:31 +0000 (UTC) Received: from localhost ([::1]:48138 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1l1XYv-0007m5-Ii for larch@yhetil.org; Mon, 18 Jan 2021 11:39:29 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:37518) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1l1XYi-0007ie-Im; Mon, 18 Jan 2021 11:39:16 -0500 Received: from mx1.dismail.de ([78.46.223.134]:19249) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1l1XYf-0002mf-SD; Mon, 18 Jan 2021 11:39:16 -0500 Received: from mx1.dismail.de (localhost [127.0.0.1]) by mx1.dismail.de (OpenSMTPD) with ESMTP id 526095eb; Mon, 18 Jan 2021 17:39:09 +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=5yoOyfMWuIpCbA2I4aVDl tWmPg3e1gQ8VsfEudIoKsg=; b=oWCmtvbYL/EOfqYc5XMUMQyi7lvysYXcQ9156 eLol3NshxDqUcIC+bkm+9eNmsPZRFBNEChcBQDmkD3QBf2I7rQ3jii6JWpvtJcBp nsrSkQ5PXW9jGaA5YxcRMd7pt8u8cQSf+HSsbC27+GShl66J9BuVFDG13FHrNJx2 JEScT3ELMrLi2psTz7QgEUD8FC0O3AxLqAzbM94rJkWpB2lgxLR696n1MEB3HeY0 pwDu0y9vg602UyrRS+4PUbDWfNI7K7f9m5mVtRJiLGinQBh7lD/FBeDziBuv5Job YZIpcbFGHuZTSNNNW1EOpbNsQwvEnC1n14ysy7GnM+5xD7gNw== Received: from smtp2.dismail.de ( [10.240.26.12]) by mx1.dismail.de (OpenSMTPD) with ESMTP id f4353f35; Mon, 18 Jan 2021 17:39:08 +0100 (CET) Received: from smtp2.dismail.de (localhost [127.0.0.1]) by smtp2.dismail.de (OpenSMTPD) with ESMTP id 17711ab6; Mon, 18 Jan 2021 17:39:08 +0100 (CET) Received: by dismail.de (OpenSMTPD) with ESMTPSA id 6f4a7f7d (TLSv1.3:AEAD-AES256-GCM-SHA384:256:NO); Mon, 18 Jan 2021 17:39:08 +0100 (CET) To: othacehe@gnu.org Subject: [PATCH] * doc/guix-cookbook.texi (Guix System Image API): new section Date: Mon, 18 Jan 2021 11:38:35 -0500 Message-Id: <20210118163835.13004-1-jbranso@dismail.de> X-Mailer: git-send-email 2.30.0 In-Reply-To: <87h7nepe4v.fsf@gnu.org> References: <87h7nepe4v.fsf@gnu.org> 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 , guix-patches@gnu.org Errors-To: help-guix-bounces+larch=yhetil.org@gnu.org Sender: "Help-Guix" Reply-to: Joshua Branson From: jbranso--- via X-Migadu-Flow: FLOW_IN X-Migadu-Spam-Score: 1.14 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=dismail.de header.s=20190914 header.b=oWCmtvbY; dmarc=pass (policy=none) header.from=gnu.org; 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: 37F7E94042A X-Spam-Score: 1.14 X-Migadu-Scanner: scn0.migadu.com X-TUID: N+SOuQJXKFkP --- doc/guix-cookbook.texi | 187 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index 54ab99558e..d9835c43f5 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 disk images 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