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 UL6FJXZyCWDkcQAA0tVLHw (envelope-from ) for ; Thu, 21 Jan 2021 12:24:22 +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 GH1dIXZyCWAaaAAA1q6Kng (envelope-from ) for ; Thu, 21 Jan 2021 12:24:22 +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 32ADA940501 for ; Thu, 21 Jan 2021 12:24:22 +0000 (UTC) Received: from localhost ([::1]:42916 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1l2Z0f-0001Oc-19 for larch@yhetil.org; Thu, 21 Jan 2021 07:24:21 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:36850) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1l2Z0N-0001Bx-3k for guix-patches@gnu.org; Thu, 21 Jan 2021 07:24:03 -0500 Received: from debbugs.gnu.org ([209.51.188.43]:45474) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1l2Z0M-0000Nf-T6 for guix-patches@gnu.org; Thu, 21 Jan 2021 07:24:02 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1l2Z0M-0007lq-PM for guix-patches@gnu.org; Thu, 21 Jan 2021 07:24: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: Thu, 21 Jan 2021 12:24:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 45957 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: othacehe@gnu.org Received: via spool by 45957-submit@debbugs.gnu.org id=B45957.161123179729807 (code B ref 45957); Thu, 21 Jan 2021 12:24:02 +0000 Received: (at 45957) by debbugs.gnu.org; 21 Jan 2021 12:23:17 +0000 Received: from localhost ([127.0.0.1]:57019 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l2Yzc-0007kh-JJ for submit@debbugs.gnu.org; Thu, 21 Jan 2021 07:23:17 -0500 Received: from mx1.dismail.de ([78.46.223.134]:44537) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l2YzX-0007kB-Hp for 45957@debbugs.gnu.org; Thu, 21 Jan 2021 07:23:12 -0500 Received: from mx1.dismail.de (localhost [127.0.0.1]) by mx1.dismail.de (OpenSMTPD) with ESMTP id 19d4b9c8; Thu, 21 Jan 2021 13:23: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=8wbSEa1s1kqDHoTyylWPk x2cmGseI6sQeLg5iOMhp0Y=; b=Pg7Llyg8E250BvBcrdzRdCcYSXCaddXpvfCWI H7M0HHavFZzOXmuqTJ7dHr3iowieL2qDMzVSuw3tYQg4clxA0QfGKY897z9OSPS6 1EglhsnrleLcoYVv4ao30AdmUdqVbHv1gJeW8aFhrsVBeI/X8uitQ9WOUq/vHlQF FyqDaHo3eXnkQmiNVThXOtuKQ9uEwxh3ErHzyZq1OyhPM0SohXYBv/3WFiZnBSrr UJKAfRsfwQKGB9336kslcEIElDOnOoAUaFSGb9fza7Jfy3W+VDHm+dou3Z5JiP11 iiSZrL1I4SZZ4BU0Xst6nHblp19WA3TUQ3PKkf8I+szFmSeWw== Received: from smtp1.dismail.de ( [10.240.26.11]) by mx1.dismail.de (OpenSMTPD) with ESMTP id 7d9733ca; Thu, 21 Jan 2021 13:23:08 +0100 (CET) Received: from smtp1.dismail.de (localhost [127.0.0.1]) by smtp1.dismail.de (OpenSMTPD) with ESMTP id 64a25f3c; Thu, 21 Jan 2021 13:23:08 +0100 (CET) Received: by dismail.de (OpenSMTPD) with ESMTPSA id bd5e3a3e (TLSv1.3:AEAD-AES256-GCM-SHA384:256:NO); Thu, 21 Jan 2021 13:23:06 +0100 (CET) Date: Thu, 21 Jan 2021 07:22:07 -0500 Message-Id: <20210121122206.6911-2-jbranso@dismail.de> X-Mailer: git-send-email 2.30.0 In-Reply-To: <87o8hiilty.fsf@gnu.org> References: <87o8hiilty.fsf@gnu.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit 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, Joshua Branson Errors-To: guix-patches-bounces+larch=yhetil.org@gnu.org Sender: "Guix-patches" Reply-to: Joshua Branson X-ACL-Warn: , Joshua Branson via Guix-patches From: guix-patches--- via X-Migadu-Flow: FLOW_IN X-Migadu-Spam-Score: 1.15 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=dismail.de header.s=20190914 header.b=Pg7Llyg8; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of guix-patches-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=guix-patches-bounces@gnu.org X-Migadu-Queue-Id: 32ADA940501 X-Spam-Score: 1.15 X-Migadu-Scanner: scn0.migadu.com X-TUID: gXZz5gWT0e3G --- doc/guix-cookbook.texi | 221 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 221 insertions(+) diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index 54ab99558e..32175fbcda 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,226 @@ 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 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{efi-raw}, +@code{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 four files: + +@itemize @bullet +@item +@file{gnu/system/images/hurd.scm} + +@item +@file{gnu/system/images/pine64.scm} + +@item +@file{gnu/system/images/novena.scm} + +@item +@file{gnu/system/images/pinebook-pro.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 an image +from an @code{operating-system} configuration file: + +@example +guix system 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 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: + + - pinebook-pro-raw + - pine64-raw + - novena-raw + - hurd-raw + - hurd-qcow2 + - qcow2 + - uncompressed-iso9660 + - efi-raw + - arm64-raw + - arm32-raw + - iso9660 +@end example + +and by writing an @code{operating-system} file based on +@code{pine64-barebones-os} (or @code{hurd-barebones-os}) you could +customize your image to your preferences in a file +(@file{my-pine-os.scm}) like this: + +@lisp +(use-modules + (srfi srfi-9) + (srfi srfi-9 gnu) + (gnu services linux) + (gnu system images pine64)) + +(let ((base-os pine64-barebones-os)) + (operating-system + (inherit base-os) + (timezone "America/Indiana/Indianapolis") + (services + (cons* + (service earlyoom-service-type + (earlyoom-configuration + (prefer-regexp "icecat|chromium|firefox"))) + (operating-system-user-services base-os))))) +@end lisp + +run: + +@example +guix system image --image-type=pine64-raw my-pine-os.scm +@end example + +or, + +@example +guix system image --image-type=hurd-raw my-hurd-os.scm +@end example + +to get an image that can be written directly to a hard drive and booted +from. + +Without changing anything to @code{my-hurd-os.scm}, calling: + +@example +guix system image --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