GNU bug report logs - #45957
[PATCH] * doc/guix-cookbook.texi (Guix System Image API): new section

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 45957 in the body.
You can then email your comments to 45957 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Joshua Branson <jbranso <at> dismail.de>
To: othacehe <at> gnu.org
Cc: help-guix <at> gnu.org, Joshua Branson <jbranso <at> dismail.de>,
 guix-patches <at> gnu.org
Subject: [PATCH] * doc/guix-cookbook.texi (Guix System Image API): new section
Date: Mon, 18 Jan 2021 11:38:35 -0500

---
 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>
+  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  ;<operating-system>
+                      (default #f))
+  (partitions         image-partitions ;list of <partition>
+                      (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>
+  image-type make-image-type
+  image-type?
+  (name           image-type-name) ;symbol
+  (constructor    image-type-constructor)) ;<operating-system> -> <image>
+@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

Message #8 received at 45957 <at> debbugs.gnu.org (full text, mbox):

From: Joshua Branson <jbranso <at> dismail.de>
To: 45957 <at> debbugs.gnu.org
Date: Mon, 18 Jan 2021 12:53:22 -0500

> 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

Message #11 received at 45957 <at> debbugs.gnu.org (full text, mbox):

From: Mathieu Othacehe <othacehe <at> gnu.org>
To: Joshua Branson <jbranso <at> dismail.de>
Cc: 45957 <at> debbugs.gnu.org
Subject: Re: [bug#45957] (no subject)
Date: Wed, 20 Jan 2021 14:06:04 +0100

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

Message #14 received at 45957 <at> debbugs.gnu.org (full text, mbox):

From: Joshua Branson <jbranso <at> dismail.de>
To: Mathieu Othacehe <othacehe <at> gnu.org>
Cc: 45957 <at> debbugs.gnu.org
Subject: Re: [bug#45957] (no subject)
Date: Wed, 20 Jan 2021 12:17:41 -0500

Mathieu Othacehe <othacehe <at> gnu.org> 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

Message #17 received at 45957 <at> debbugs.gnu.org (full text, mbox):

From: Joshua Branson <jbranso <at> dismail.de>
To: othacehe <at> gnu.org
Cc: 45957 <at> debbugs.gnu.org, Joshua Branson <jbranso <at> dismail.de>
Subject: [PATCH] * doc/guix-cookbook.texi (Guix System Image API): new section
Date: Wed, 20 Jan 2021 12:12:54 -0500

---
 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>
+  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  ;<operating-system>
+                      (default #f))
+  (partitions         image-partitions ;list of <partition>
+                      (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>
+  image-type make-image-type
+  image-type?
+  (name           image-type-name) ;symbol
+  (constructor    image-type-constructor)) ;<operating-system> -> <image>
+@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

Message #20 received at 45957 <at> debbugs.gnu.org (full text, mbox):

From: Mathieu Othacehe <othacehe <at> gnu.org>
To: Joshua Branson <jbranso <at> dismail.de>
Cc: 45957 <at> debbugs.gnu.org
Subject: Re: [PATCH] * doc/guix-cookbook.texi (Guix System Image API): new
 section
Date: Thu, 21 Jan 2021 12:14:01 +0100

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

Message #23 received at 45957 <at> debbugs.gnu.org (full text, mbox):

From: Joshua Branson <jbranso <at> dismail.de>
To: othacehe <at> gnu.org
Cc: 45957 <at> debbugs.gnu.org
Subject: Re: learning git-send-email is interesting
Date: Thu, 21 Jan 2021 07:22:06 -0500

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.

Message #26 received at 45957 <at> debbugs.gnu.org (full text, mbox):

From: Joshua Branson <jbranso <at> dismail.de>
To: othacehe <at> gnu.org
Cc: 45957 <at> debbugs.gnu.org, Joshua Branson <jbranso <at> dismail.de>
Subject: [PATCH] * doc/guix-cookbook.texi (Guix System Image API): new section
Date: Thu, 21 Jan 2021 07:22:07 -0500

---
 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>
+  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  ;<operating-system>
+                      (default #f))
+  (partitions         image-partitions ;list of <partition>
+                      (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>
+  image-type make-image-type
+  image-type?
+  (name           image-type-name) ;symbol
+  (constructor    image-type-constructor)) ;<operating-system> -> <image>
+@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

Message #29 received at 45957 <at> debbugs.gnu.org (full text, mbox):

From: jbranso <at> dismail.de
To: "Mathieu Othacehe" <othacehe <at> gnu.org>
Cc: 45957 <at> debbugs.gnu.org
Subject: Re: [bug#45957] thanks
Date: Thu, 21 Jan 2021 12:33:55 +0000

Also thanks for your commitment and patience to
help me get this merged into the cookbook.  And thanks for saying my coding
sessions are helpful.  It's certainly helping me learn a lot!

And thanks for pointing out (inherit)  That is an awesome!  Guix's
define-record-type* is fantastic.  If guix is ok with it, I might try to see
if we can include that in the default installation of guile.

Guile already has a define*.  Let's add a define-record-type*

Thanks again,

Joshua

Message #34 received at 45957-done <at> debbugs.gnu.org (full text, mbox):

From: Mathieu Othacehe <othacehe <at> gnu.org>
To: Joshua Branson <jbranso <at> dismail.de>
Cc: 45957-done <at> debbugs.gnu.org
Subject: Re: [bug#45957] [PATCH] * doc/guix-cookbook.texi (Guix System Image
 API): new section
Date: Thu, 21 Jan 2021 14:41:56 +0100

Hey,

I fixed the commit message and edited a few things before pushing.

Thanks,

Mathieu

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.