From debbugs-submit-bounces@debbugs.gnu.org Mon Jan 18 11:39:19 2021 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) From: Joshua Branson 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-Spam-Score: -1.4 (-) X-Debbugs-Envelope-To: submit Cc: help-guix@gnu.org, Joshua Branson , guix-patches@gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.4 (--) --- 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 From debbugs-submit-bounces@debbugs.gnu.org Mon Jan 18 12:53:34 2021 Received: (at 45957) by debbugs.gnu.org; 18 Jan 2021 17:53:35 +0000 Received: from localhost ([127.0.0.1]:48372 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l1Yic-0002PH-Oj for submit@debbugs.gnu.org; Mon, 18 Jan 2021 12:53:34 -0500 Received: from mx1.dismail.de ([78.46.223.134]:31708) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l1Yib-0002P3-8r for 45957@debbugs.gnu.org; Mon, 18 Jan 2021 12:53:34 -0500 Received: from mx1.dismail.de (localhost [127.0.0.1]) by mx1.dismail.de (OpenSMTPD) with ESMTP id 4a253f6d for <45957@debbugs.gnu.org>; Mon, 18 Jan 2021 18:53:25 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=dismail.de; h=date :message-id:from:to; s=20190914; bh=H5jszeukngEW2sgBlfnh3drfyBd9 8vQJ4CjloFU/cR0=; b=N5OdMDf6U5vAYPJ6+iO2E+Ho03CCnA93Eb8sTWL6PxUA uJAG7zpQVvdZwA/AFOxm3PXfaMmq5nEWrHQIOc/rGVy2GEAF8Jd3yq0qt8RgWRve Hx6dS/VTNJYriWKleSBpB7tfuFqBsGq78fQzxF4onq4hoDwMrZRg7PTQEEWZmPsw cDHleEYb8nJiVwJQG42K/Ak6wwG+9TKJ6f/NsIQ00YeIivWsSIzGX3X3Ezam6JoE LlY76tPUL6cUQqI7Ov1qzvn17Ox3jlc0kZnqI213YZrzl2vtXTybSFPFbySZ1t/z Yuk1VbPR3MgR/lgoVwoB6kngNqEXlLARaYbJ0CXWgA== Received: from smtp2.dismail.de ( [10.240.26.12]) by mx1.dismail.de (OpenSMTPD) with ESMTP id 895e232f for <45957@debbugs.gnu.org>; Mon, 18 Jan 2021 18:53:25 +0100 (CET) Received: from smtp2.dismail.de (localhost [127.0.0.1]) by smtp2.dismail.de (OpenSMTPD) with ESMTP id d1f7e735 for <45957@debbugs.gnu.org>; Mon, 18 Jan 2021 18:53:25 +0100 (CET) Received: by dismail.de (OpenSMTPD) with ESMTPSA id 3c52c474 (TLSv1.3:AEAD-AES256-GCM-SHA384:256:NO) for <45957@debbugs.gnu.org>; Mon, 18 Jan 2021 18:53:24 +0100 (CET) Date: Mon, 18 Jan 2021 12:53:22 -0500 Message-Id: <87v9buuo6l.fsf@dismail.de> From: Joshua Branson To: 45957@debbugs.gnu.org X-Spam-Score: -0.3 (/) X-Debbugs-Envelope-To: 45957 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.3 (-) > I have a pending patchset renaming "disk-image" command to "image". We > will need to update it accordingly. I did not change any of the "disk-image" commands to disk-image. If you'd like me to do that, then please let me know. Thanks, Joshua From debbugs-submit-bounces@debbugs.gnu.org Wed Jan 20 08:06:15 2021 Received: (at 45957) by debbugs.gnu.org; 20 Jan 2021 13:06:15 +0000 Received: from localhost ([127.0.0.1]:53176 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l2DBf-0001pm-Dj for submit@debbugs.gnu.org; Wed, 20 Jan 2021 08:06:15 -0500 Received: from eggs.gnu.org ([209.51.188.92]:47982) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l2DBd-0001pP-Q9 for 45957@debbugs.gnu.org; Wed, 20 Jan 2021 08:06:14 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]:49508) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1l2DBX-0004n9-Li; Wed, 20 Jan 2021 08:06:07 -0500 Received: from [2a01:e0a:19b:d9a0:98b7:b002:9499:5e2c] (port=35396 helo=cervin) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1l2DBX-0004Zz-5B; Wed, 20 Jan 2021 08:06:07 -0500 From: Mathieu Othacehe To: Joshua Branson Subject: Re: [bug#45957] (no subject) References: <20210118163835.13004-1-jbranso@dismail.de> <87v9buuo6l.fsf@dismail.de> Date: Wed, 20 Jan 2021 14:06:04 +0100 In-Reply-To: <87v9buuo6l.fsf@dismail.de> (Joshua Branson's message of "Mon, 18 Jan 2021 12:53:22 -0500") Message-ID: <87o8hjzrk3.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.3 (/) X-Debbugs-Envelope-To: 45957 Cc: 45957@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.3 (-) Hello Joshua, > I did not change any of the "disk-image" commands to disk-image. If > you'd like me to do that, then please let me know. I pushed the "disk-image" -> "image" patch yesterday. It would be great if you could send an updated version. Thanks, Mathieu From debbugs-submit-bounces@debbugs.gnu.org Wed Jan 20 12:17:54 2021 Received: (at 45957) by debbugs.gnu.org; 20 Jan 2021 17:17:54 +0000 Received: from localhost ([127.0.0.1]:56176 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l2H7B-0004T1-Me for submit@debbugs.gnu.org; Wed, 20 Jan 2021 12:17:53 -0500 Received: from mx1.dismail.de ([78.46.223.134]:19275) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l2H79-0004Ol-Ip for 45957@debbugs.gnu.org; Wed, 20 Jan 2021 12:17:52 -0500 Received: from mx1.dismail.de (localhost [127.0.0.1]) by mx1.dismail.de (OpenSMTPD) with ESMTP id 46dbcd58; Wed, 20 Jan 2021 18:17:45 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=dismail.de; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; s=20190914; bh=XqlkmENtTSe/aIsxnZv/LA7Rl8r3SQmlea iw2/P+jJk=; b=Q81yFJ2gC5bn85F6qMOOtvQYmC4vT02S7tORkmNoGfzBKtRlya kGsbMlHFDQomhZQzkPo494FcTkRhNev45pxal0lynRyN3aNV7sWPtON8NHgPCzkO Usmri0sChw4r6SeciJDgR9v4cwdVlRg4fDlUUhnFHZUDXI/NJ5v/8uJgVaQtqmKI FUP1BZpWJWIoiCFDFaWnWtyxNbD7rH+c5b8IWXLyWF+BB/R99CQfTEh788ubhEEW MSm9V1nZQIJR/7Z5/i/pFvLre91Un/pD0XtDKB+a+YMw4VYxAbzzRU7Cix4QUlRU 9CTR5/O/Y0Nk1IlAe6iyYMuiTD2HMeip6Hvg== Received: from smtp1.dismail.de ( [10.240.26.11]) by mx1.dismail.de (OpenSMTPD) with ESMTP id d421c23d; Wed, 20 Jan 2021 18:17:45 +0100 (CET) Received: from smtp1.dismail.de (localhost [127.0.0.1]) by smtp1.dismail.de (OpenSMTPD) with ESMTP id 658961ca; Wed, 20 Jan 2021 18:17:45 +0100 (CET) Received: by dismail.de (OpenSMTPD) with ESMTPSA id f7d9c319 (TLSv1.3:AEAD-AES256-GCM-SHA384:256:NO); Wed, 20 Jan 2021 18:17:44 +0100 (CET) From: Joshua Branson To: Mathieu Othacehe Subject: Re: [bug#45957] (no subject) References: <20210118163835.13004-1-jbranso@dismail.de> <87v9buuo6l.fsf@dismail.de> <87o8hjzrk3.fsf@gnu.org> Date: Wed, 20 Jan 2021 12:17:41 -0500 In-Reply-To: <87o8hjzrk3.fsf@gnu.org> (Mathieu Othacehe's message of "Wed, 20 Jan 2021 14:06:04 +0100") Message-ID: <87k0s74jey.fsf@dismail.de> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.3 (/) X-Debbugs-Envelope-To: 45957 Cc: 45957@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.3 (-) Mathieu Othacehe writes: > Hello Joshua, > >> I did not change any of the "disk-image" commands to disk-image. If >> you'd like me to do that, then please let me know. > > I pushed the "disk-image" -> "image" patch yesterday. It would be great > if you could send an updated version. I am about to send an updated patch. I actually edited it a good amount, and I added in a section where I customized the pine-os image to change the timezone and add in a early-oom-service. I feel very proud of myself. Thanks leoprikler and RhodiumToad in #guile for helping me figure out to use set-field. spoiler alert: don't forget to add in (use-modules (srfi srfi-9 gnu)) Joshua P.S. I also have been recording my coding progress for this documentation effort online. If anyone likes watching an amateur coding here's a link: https://video.hardlimit.com/videos/watch/e4628d8f-0128-4811-b22f-9eabe834a213 > > Thanks, > > Mathieu -- Joshua Branson (joshuaBPMan in #guix) Sent from Emacs and Gnus https://gnucode.me https://video.hardlimit.com/accounts/joshua_branson/video-channels https://propernaming.org "You can have whatever you want, as long as you help enough other people get what they want." - Zig Ziglar From debbugs-submit-bounces@debbugs.gnu.org Wed Jan 20 12:18:04 2021 Received: (at 45957) by debbugs.gnu.org; 20 Jan 2021 17:18:04 +0000 Received: from localhost ([127.0.0.1]:56181 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l2H7M-0004YR-0F for submit@debbugs.gnu.org; Wed, 20 Jan 2021 12:18:04 -0500 Received: from mx1.dismail.de ([78.46.223.134]:19275) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l2H7J-0004Ol-UO for 45957@debbugs.gnu.org; Wed, 20 Jan 2021 12:18:02 -0500 Received: from mx1.dismail.de (localhost [127.0.0.1]) by mx1.dismail.de (OpenSMTPD) with ESMTP id 97f171f5; Wed, 20 Jan 2021 18:18:00 +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=BxUUslVHjZPJGIVwaWVzw Cu8kWa8l5PacCISkolTx+Y=; b=Ecu/ReazXZlfS9SJaY0lhFsLpsZadjJvqBRMD fE/XhlnimP1hIbr62LuZ+d81oVc0cHRPr4pxFN5YWAs4Wgh95hjRoSv+hKZ0ZOgl QB4AFJHMQlwEMWGbtz/0XKhSFRK1d29ZQpEcjFBc/HqVXGgg6bb5kPndTbBj3K4p HJOWtOYLxcMo7dBRqBOVPpRpHBObRi0q0DDnaqjCGqQe0h9Ar16Fx48Cq3g0Nntm 2cNCKpFChIh02haLJmjWb8/32RanuvuWp+gpcqgPEt8buhnLZMAcJvSxyC1KaSqK UQ21AyTwujNMcWE0NPQYpu9BvR39u2SolATw2iLI8iT0z0IIA== Received: from smtp2.dismail.de ( [10.240.26.12]) by mx1.dismail.de (OpenSMTPD) with ESMTP id 87507337; Wed, 20 Jan 2021 18:18:00 +0100 (CET) Received: from smtp2.dismail.de (localhost [127.0.0.1]) by smtp2.dismail.de (OpenSMTPD) with ESMTP id e91a348b; Wed, 20 Jan 2021 18:18:00 +0100 (CET) Received: by dismail.de (OpenSMTPD) with ESMTPSA id 85b7f64e (TLSv1.3:AEAD-AES256-GCM-SHA384:256:NO); Wed, 20 Jan 2021 18:17:54 +0100 (CET) From: Joshua Branson To: othacehe@gnu.org Subject: [PATCH] * doc/guix-cookbook.texi (Guix System Image API): new section Date: Wed, 20 Jan 2021 12:12:54 -0500 Message-Id: <20210120171254.3403-1-jbranso@dismail.de> X-Mailer: git-send-email 2.30.0 In-Reply-To: <87o8hjzrk3.fsf@gnu.org> References: <87o8hjzrk3.fsf@gnu.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 45957 Cc: 45957@debbugs.gnu.org, Joshua Branson X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) --- doc/guix-cookbook.texi | 222 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 222 insertions(+) diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index 54ab99558e..3971edf83f 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,227 @@ 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{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 four files: + +@itemize @bullet +@item +@file{gnu/system/images/hurd.scm} + +@item +@file{gnu/system/images/pine64.scm} + +@item +@file{gnu/guix/guix-src/gnu/system/images/novena.scm} + +@item +@file{gnu/guix/guix-src/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 + - 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)) + +(define my-pine64-barebones-os + (set-fields pine64-barebones-os + ((operating-system-timezone) "America/Indiana/Indianapolis") + ((operating-system-user-services) + (cons* + (service earlyoom-service-type + (earlyoom-configuration + (prefer-regexp "icecat|chromium|firefox"))) + (operating-system-user-services pine64-barebones-os))))) + +my-pine64-barebones-os +@end lisp + +run: + +@example +guix system --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 From debbugs-submit-bounces@debbugs.gnu.org Thu Jan 21 06:14:13 2021 Received: (at 45957) by debbugs.gnu.org; 21 Jan 2021 11:14:13 +0000 Received: from localhost ([127.0.0.1]:56953 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l2Xun-0005sa-Bn for submit@debbugs.gnu.org; Thu, 21 Jan 2021 06:14:13 -0500 Received: from eggs.gnu.org ([209.51.188.92]:55736) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l2Xuj-0005sE-Sq for 45957@debbugs.gnu.org; Thu, 21 Jan 2021 06:14:12 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]:40337) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1l2Xud-0001VW-JR; Thu, 21 Jan 2021 06:14:03 -0500 Received: from [2a01:e0a:19b:d9a0:98b7:b002:9499:5e2c] (port=44170 helo=cervin) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1l2Xuc-0004gR-T6; Thu, 21 Jan 2021 06:14:03 -0500 From: Mathieu Othacehe To: Joshua Branson Subject: Re: [PATCH] * doc/guix-cookbook.texi (Guix System Image API): new section References: <87o8hjzrk3.fsf@gnu.org> <20210120171254.3403-1-jbranso@dismail.de> Date: Thu, 21 Jan 2021 12:14:01 +0100 In-Reply-To: <20210120171254.3403-1-jbranso@dismail.de> (Joshua Branson's message of "Wed, 20 Jan 2021 12:12:54 -0500") Message-ID: <87o8hiilty.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 45957 Cc: 45957@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Hello Joshua, Thanks for this new revision! It's really nice to follow your live coding sessions. I think it can be very valuable for newcomers willing to dive into Guix internals. > +This record also contains the operating-system to instantiate. The > +@code{format} field defines the image type and can be @code{disk-image}, ^ efi-raw > +@code{compressed-qcow2} or @code{iso9660}. In the future, it could be ^ qcow2 The supported image types list is now longer, so you could add "for instance". We could also specify that "raw" designates disk-image that can be copied as is on the installation media. > +@file{gnu/guix/guix-src/gnu/system/images/novena.scm} You mean @file{gnu/system/images/novena.scm}, right? > + - pinebook-pro-raw > + - pine64-raw > + - novena-raw > + - hurd-raw > + - hurd-qcow2 > + - qcow2 > + - uncompressed-iso9660 > + - raw > + - arm64-raw > + - arm32-raw > + - iso9660 Since recently "raw" has been renamed "efi-raw". > +@lisp > +(use-modules > + (srfi srfi-9) > + (srfi srfi-9 gnu) > + (gnu services linux) > + (gnu system images pine64)) > + > +(define my-pine64-barebones-os > + (set-fields pine64-barebones-os > + ((operating-system-timezone) "America/Indiana/Indianapolis") > + ((operating-system-user-services) > + (cons* > + (service earlyoom-service-type > + (earlyoom-configuration > + (prefer-regexp "icecat|chromium|firefox"))) > + (operating-system-user-services pine64-barebones-os))))) Nice example. However, we generally prefer using inheritance. That would give: --8<---------------cut here---------------start------------->8--- (use-modules (gnu system) (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))))) --8<---------------cut here---------------end--------------->8--- WDYT? Thanks, Mathieu From debbugs-submit-bounces@debbugs.gnu.org Thu Jan 21 07:23:12 2021 Received: (at 45957) by debbugs.gnu.org; 21 Jan 2021 12:23:12 +0000 Received: from localhost ([127.0.0.1]:57017 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l2YzY-0007kT-Dk for submit@debbugs.gnu.org; Thu, 21 Jan 2021 07:23:12 -0500 Received: from mx1.dismail.de ([78.46.223.134]:44537) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l2YzW-0007kB-N5 for 45957@debbugs.gnu.org; Thu, 21 Jan 2021 07:23:11 -0500 Received: from mx1.dismail.de (localhost [127.0.0.1]) by mx1.dismail.de (OpenSMTPD) with ESMTP id a6354327; Thu, 21 Jan 2021 13:23:04 +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=2VRMbx5ITkyogQUTbtjZz FrTKq8bsf+0bbhZsKwkQbM=; b=rSYjLu7rkN56yfozPmw6QTONns6pHg/xqwtjZ 3sc3KZrqS6naxrI7bTILj0Rqgqne8KGlA43ydI2Tz66BQG44S/DWSwAA1UCQoTv/ LbxUbMcQrL8ITNP1cu7WJ3/OKPI3AE+mjIXMNVU0c2CyQHljE3hhTpWEOZ55KEny ab2Q1LsA1OWLK4q+kLHTQcqrYpbnEchKfL/J5DQTF9ShnqQhg0foG+FoGiFviRmT mYjCfCtVZk/1rYpnAoqDFBR4V8U46yZougjX6Tz+SCRQ29gBLO8Yl17F6BluvmZQ JDcTYB6v4+axJ8jVqMjNDnVTqrXD9VVogCPqCxHZ3TPQgl0HQ== Received: from smtp1.dismail.de ( [10.240.26.11]) by mx1.dismail.de (OpenSMTPD) with ESMTP id 559eea73; Thu, 21 Jan 2021 13:23:03 +0100 (CET) Received: from smtp1.dismail.de (localhost [127.0.0.1]) by smtp1.dismail.de (OpenSMTPD) with ESMTP id c7bd8dab; Thu, 21 Jan 2021 13:23:03 +0100 (CET) Received: by dismail.de (OpenSMTPD) with ESMTPSA id 27b8f79b (TLSv1.3:AEAD-AES256-GCM-SHA384:256:NO); Thu, 21 Jan 2021 13:23:03 +0100 (CET) From: Joshua Branson To: othacehe@gnu.org Subject: Re: learning git-send-email is interesting Date: Thu, 21 Jan 2021 07:22:06 -0500 Message-Id: <20210121122206.6911-1-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-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 45957 Cc: 45957@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Thanks for the edit suggestions. I appreciated learning about (inherit ) procedure. That is super helpful! Here's an updated commit. Thanks for your timely responses in helping me merge this to the cookbook! Let me know if this "intro" section makes it hard for you to merge this patch. I just learning about --compose from git-send-email 5 minutes ago. From debbugs-submit-bounces@debbugs.gnu.org Thu Jan 21 07:23:17 2021 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) From: Joshua Branson To: othacehe@gnu.org Subject: [PATCH] * doc/guix-cookbook.texi (Guix System Image API): new section 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-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 45957 Cc: 45957@debbugs.gnu.org, Joshua Branson X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) --- 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 From debbugs-submit-bounces@debbugs.gnu.org Thu Jan 21 07:34:04 2021 Received: (at 45957) by debbugs.gnu.org; 21 Jan 2021 12:34:04 +0000 Received: from localhost ([127.0.0.1]:57027 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l2ZA3-0001du-SA for submit@debbugs.gnu.org; Thu, 21 Jan 2021 07:34:04 -0500 Received: from mx1.dismail.de ([78.46.223.134]:8943) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l2ZA2-0001dQ-PX for 45957@debbugs.gnu.org; Thu, 21 Jan 2021 07:34:03 -0500 Received: from mx1.dismail.de (localhost [127.0.0.1]) by mx1.dismail.de (OpenSMTPD) with ESMTP id 027e20e4; Thu, 21 Jan 2021 13:33:56 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=dismail.de; h= mime-version:date:content-type:content-transfer-encoding:from :message-id:subject:to:cc:in-reply-to:references; s=20190914; bh=F9BJojlleFpIfIQfDH3LpBTHrBhczCgDc3HM9RgCi54=; b=BYTrNs3Zv6fD 60fnJzqX+/RCUqNr9OCibOpa9v0WJw4sCqO7Ab6rpLW8FiHxKOiRfjh8q4srFhZB +J8oEcTE0MZVcmXbc1AZgrc5X5NrEKQyAQ6wXMFebn9wO/LhO3rjrXRK8JFFel6T HinvmbqitMkUnvZQc+ubveOf2fvz55qOzL3/nPHzKwu0BKwWl22zB4Uid85ivyPM 49YITxKMYqMe7m+9knNaRBhG9092TwZ7ZspXTWPU79aI37rYsNITu1Wri8VoczjW KvZ5107ZvLGHPorxcUeXA1bziKhfnM0Pngkd/uI4/eEAxdOk5U7TPKcxoEJhYidB epW5y6HMzw== Received: from smtp1.dismail.de ( [10.240.26.11]) by mx1.dismail.de (OpenSMTPD) with ESMTP id 88a8f0fa; Thu, 21 Jan 2021 13:33:55 +0100 (CET) Received: from smtp1.dismail.de (localhost [127.0.0.1]) by smtp1.dismail.de (OpenSMTPD) with ESMTP id 4e2b848a; Thu, 21 Jan 2021 13:33:55 +0100 (CET) Received: by dismail.de (OpenSMTPD) with ESMTPSA id 5d37367f (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256:NO); Thu, 21 Jan 2021 13:33:55 +0100 (CET) MIME-Version: 1.0 Date: Thu, 21 Jan 2021 12:33:55 +0000 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-Mailer: RainLoop/1.14.0a From: jbranso@dismail.de Message-ID: Subject: Re: [bug#45957] thanks To: "Mathieu Othacehe" In-Reply-To: <87o8hjzrk3.fsf@gnu.org> References: <87o8hjzrk3.fsf@gnu.org> <20210118163835.13004-1-jbranso@dismail.de> <87v9buuo6l.fsf@dismail.de> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 45957 Cc: 45957@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Also thanks for your commitment and patience to=0Ahelp me get this merged= into the cookbook. And thanks for saying my coding=0Asessions are helpf= ul. It's certainly helping me learn a lot!=0A=0AAnd thanks for pointing = out (inherit) That is an awesome! Guix's=0Adefine-record-type* is fanta= stic. If guix is ok with it, I might try to see=0Aif we can include that= in the default installation of guile.=0A=0AGuile already has a define*. = Let's add a define-record-type*=0A=0AThanks again,=0A=0AJoshua From debbugs-submit-bounces@debbugs.gnu.org Thu Jan 21 08:42:08 2021 Received: (at 45957-done) by debbugs.gnu.org; 21 Jan 2021 13:42:08 +0000 Received: from localhost ([127.0.0.1]:57094 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l2aDv-0003KN-VY for submit@debbugs.gnu.org; Thu, 21 Jan 2021 08:42:08 -0500 Received: from eggs.gnu.org ([209.51.188.92]:60560) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1l2aDu-0003Ju-7z for 45957-done@debbugs.gnu.org; Thu, 21 Jan 2021 08:42:06 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]:41919) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1l2aDm-0001M6-HK; Thu, 21 Jan 2021 08:42:00 -0500 Received: from [2a01:e0a:19b:d9a0:98b7:b002:9499:5e2c] (port=45458 helo=cervin) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1l2aDl-0000BK-OE; Thu, 21 Jan 2021 08:41:58 -0500 From: Mathieu Othacehe To: Joshua Branson Subject: Re: [bug#45957] [PATCH] * doc/guix-cookbook.texi (Guix System Image API): new section References: <87o8hiilty.fsf@gnu.org> <20210121122206.6911-2-jbranso@dismail.de> Date: Thu, 21 Jan 2021 14:41:56 +0100 In-Reply-To: <20210121122206.6911-2-jbranso@dismail.de> (Joshua Branson's message of "Thu, 21 Jan 2021 07:22:07 -0500") Message-ID: <87lfcmiezf.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 45957-done Cc: 45957-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Hey, I fixed the commit message and edited a few things before pushing. Thanks, Mathieu From unknown Fri Jun 20 07:22:30 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Fri, 19 Feb 2021 12:24:07 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator