From patchwork Mon Jan 18 16:38:35 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "ashish.is--- via Guix-patches\" via" X-Patchwork-Id: 26466 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 5EA6227BC15; Mon, 18 Jan 2021 16:40:13 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-2.8 required=5.0 tests=BAYES_00,DKIM_SIGNED, MAILING_LIST_MULTI,RCVD_IN_MSPIKE_H4,RCVD_IN_MSPIKE_WL,SPF_HELO_PASS, T_DKIM_INVALID,URIBL_BLOCKED autolearn=unavailable autolearn_force=no version=3.4.2 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id 6B28D27BC14 for ; Mon, 18 Jan 2021 16:40:12 +0000 (GMT) Received: from localhost ([::1]:50684 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1l1XZb-0000V7-GR for patchwork@mira.cbaines.net; Mon, 18 Jan 2021 11:40:11 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:37702) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1l1XZS-0000Pr-Do for guix-patches@gnu.org; Mon, 18 Jan 2021 11:40:02 -0500 Received: from debbugs.gnu.org ([209.51.188.43]:36543) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1l1XZS-00031L-4g for guix-patches@gnu.org; Mon, 18 Jan 2021 11:40:02 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1l1XZS-0006mH-1G for guix-patches@gnu.org; Mon, 18 Jan 2021 11:40:02 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#45957] [PATCH] * doc/guix-cookbook.texi (Guix System Image API): new section Resent-From: Joshua Branson Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Mon, 18 Jan 2021 16:40:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 45957 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: othacehe@gnu.org X-Debbugs-Original-Cc: help-guix@gnu.org, Joshua Branson , guix-patches@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.161098795925997 (code B ref -1); Mon, 18 Jan 2021 16:40:01 +0000 Received: (at submit) by debbugs.gnu.org; 18 Jan 2021 16:39:19 +0000 Received: from localhost ([127.0.0.1]:48089 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l1XYl-0006lD-0q for submit@debbugs.gnu.org; Mon, 18 Jan 2021 11:39:19 -0500 Received: from lists.gnu.org ([209.51.188.17]:42200) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l1XYi-0006l5-V2 for submit@debbugs.gnu.org; Mon, 18 Jan 2021 11:39:17 -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) 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 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: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: 45957@debbugs.gnu.org, help-guix@gnu.org, jbranso@dismail.de Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: "Guix-patches" Reply-to: Joshua Branson X-ACL-Warn: , Joshua Branson via Guix-patches X-Patchwork-Original-From: guix-patches--- via From: "ashish.is--- via Guix-patches\" via" X-getmail-retrieved-from-mailbox: Patches --- 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