Understanding config.scm Modules

Understanding config.scm Modules

[mhrunnels]

Hi All,

With the help of Timo Wilken and Paren, I have a working system and am endeavoring to configure Guix to meet my needs.  That said, I am struggling with the Guix manual.  While written well for Guix experts, the manual is a challenge for non-developers and neophytes.  What follows is a practical example of my consternation.

Though working, my current configuration is not the end system I am looking to manifest.  Reading and re-reading section 12 of the manual is not helping.  What is apparent is that a Guix system configuration comprises two parts: the definition of modules and the system definition. The following are module definitions pulled from section 12 of the manual and from my own configuration.

Example 1 - bare bones system

(use-modules (gnu))
(use-service-modules networking ssh)
(use-package-modules screen ssh)

Example 2 - typical desktop system

(use-modules (gnu) (gnu system nss) (guix utils))
(use-service-modules desktop sddm xorg)
(use-package-modules certs gnome)

Example 3 - lightweight window manager system

(use-modules (gnu) (gnu system nss))
(use-service-modules desktop)
(use-package-modules bootloaders certs emacs emacs-xyz ratpoison suckless wm xorg)

Example 4 - my system (full config.scm appended below)

(use-modules (gnu))
(use-service-modules cups desktop networking ssh xorg)

Okay, now the questions ...

1) Where does the manual explain how an end-user constructs each of these examples in the context of a desired system?

2) For example, what is the purpose of "use-modules", "use-service-modules", and "use-package-modules"?

3) Where does the manual explain the options to be included or excluded with "use-modules", "use-service-modules, and "use-package-modules"?

4) Where does the manual list the modules and module options for quick reference?

5) Are there other "modules" types not listed in these examples?

6) Why does the "use-modules" line always include another element or elements in parenthesis "( )" when the "use-service-modules" and "use-packages-modules" lines do not?

7) As an end-user, how would I understand, from the manual, the Guix system "concept of operation", "theory of operation", or "top-level architecture" sufficiently well to construct the examples presented above without just copying and pasting from the manual?

Hopefully, the variation of the presented examples underscores the frustration for those trying to understand what Guix is and how Guix works to construct their own config.scm. Further, these examples are not meant to be critical of Guix or the hard work of all the volunteers to date.  These questions are meant to reflect the "chasm" of knowledge and understanding between expert Guix users or Guix developers and simple end-users.

Finally, I have invested over 40 hours reading the manual and other supporting material.  So, for the "RTM" crowd, I think that time investment reflects a commitment to learn and understand the Guix system. Accordingly, I look forward to hearing from those that can "fill in the gaps" missing from the manual or direct me to the specific resources necessary for me to comprehend what I don't understand.  And as a new Guix user, I am more than willing to contribute by assisting those working to improve the documentation.  A noob to help noobs, if you will indulge the thought.

My current config.scm is listed below.

Thank You,

MH

PS - once this knowledge "hump" is conquered, questions on the mysteries of %base-services, %base-packages and %desktop-services are next on my list.
------

;; Current Guix Operating System Configuration

;; Modules Imported - Access Configuration Variables
(use-modules (gnu))
(use-service-modules cups desktop networking ssh xorg)

(operating-system
  ;; Local System Information
  (locale "en_US.utf8")
  (timezone "America/New_York")
  (keyboard-layout (keyboard-layout "us"))
  (host-name "L85")

  ;; User Account Information - "root account implicit"
  ;; Accounts Appended to %base-user-accounts
  (users (cons* (user-account
                  (name "J37")
                  (comment "J37")
                  (group "users")
                  (home-directory "/home/J37")
                  (supplementary-groups '("wheel" "netdev" "audio" "video")))
                %base-user-accounts))

  ;; Packages Installed System-Wide  
  ;; Packages Appended to %base-packages
  (packages (append (list (specification->package "awesome")
                          (specification->package "nss-certs"))
                    %base-packages))

  ;; System Services List
  ;; Services Appended to %desktop-services
  ;; Services Search - Run 'guix system search KEYWORD'
  (services (append (list (service tor-service-type)
                    (service cups-service-type)
                    (set-xorg-configuration
                    (xorg-configuration (keyboard-layout keyboard-layout))))
                  %desktop-services))

  ;; Bootloader Configuration
  (bootloader (bootloader-configuration
                (bootloader grub-efi-bootloader)
                (targets (list "/boot/efi"))
                (keyboard-layout keyboard-layout)))

  ;; Swap Space Configuration
  ;; /dev/sda3
  (swap-devices (list (swap-space (target (uuid "cd7b1172-d35e-41d4-b6aa-f1e718a1b434")))))

  ;; File System - Hard Drive Configuration 
  ;; File Systems Appended to %base-file-systems 
  (file-systems (cons* (file-system ;; /dev/sda1
                         (mount-point "/boot/efi")
                         (device (uuid "6614-6330" 'fat32))
                         (type "vfat"))

               (file-system ;; /dev/sda2
                         (mount-point "/")
                         (device (uuid "04fa7446-9ded-4c60-8599-53f656d9094d" 'ext4))
                         (type "ext4"))
              
               (file-system ;; /dev/sda4
                         (mount-point "/")
                         (device (uuid "13752492-1791-4403-bcda-3aadaaca02f1" 'ext4))
                         (type "ext4"))

               (file-system ;; /dev/sdb2
                         (mount-point "/")
                         (device (uuid "45fdce17-5ed0-4204-9f39-76b02ac52aa3" 'ext4))
                         (type "ext4")) 
               
               (file-system ;; /dev/sdb3
                         (mount-point "/")
                         (device (uuid "b266a56d-07ad-4a55-bb8c-48c7d2d1e347" 'ext4))
                         (type "ext4"))

               (file-system ;; /dev/sdb4
                         (mount-point "/")
                         (device (uuid "6cf97056-26f2-4228-b785-9ec340bb5037" 'ext4))
                         (type "ext4")) 

               (file-system ;; /dev/sdb5
                         (mount-point "/")
                         (device (uuid "6ec784fb-1e57-4e8a-aae9-fd6b7cdd96ed" 'ext4))
                         (type "ext4"))  
                       %base-file-systems)))

Re: Understanding config.scm Modules

[Simon Tournier]

Hi,

Thanks for your feedback.

No answer to your questions means “I do not know” or “Something is indeed
missing on Guix side”.


On jeu., 02 févr. 2023 at 19:02, "mhrunnels@yahoo.com" <mhrunnels@yahoo.com> wrote:


> 2) For example, what is the purpose of "use-modules",
> "use-service-modules", and "use-package-modules"?

use-modules is from Guile
https://www.gnu.org/software/guile/manual/guile.html#Using-the-Guile-Module-System

The others are Guix specific.

> 4) Where does the manual list the modules and module options for quick
> reference?

I do not understand this question but I guess it is because the question
#2.


> 5) Are there other "modules" types not listed in these examples?

Nothing I am aware.


> 6) Why does the "use-modules" line always include another element or
> elements in parenthesis "( )" when the "use-service-modules" and
> "use-packages-modules" lines do not?

Example:

    (use-modules (guix)
                 (gnu packages base))

loads the modules named (guix) and named (gnu packages base).  See #2.

Since all the packages are defined in modules (gnu packages FOO) then it
is very common to write (gnu packages emacs-xyz) or (gnu packages
bioconductor) or etc. then ’use-package-modules’ provides a shortcut;
other said,

    (use-package-modules emacs-xyz bioconductor)

is equivalent to:

    (use-modules (gnu packages emacs-xyz)
                 (gnu packages bioconductor))


> Finally, I have invested over 40 hours reading the manual and other
> supporting material.  So, for the "RTM" crowd, I think that time
> investment reflects a commitment to learn and understand the Guix
> system. Accordingly, I look forward to hearing from those that can
> "fill in the gaps" missing from the manual or direct me to the
> specific resources necessary for me to comprehend what I don't
> understand.  And as a new Guix user, I am more than willing to
> contribute by assisting those working to improve the documentation.  A
> noob to help noobs, if you will indulge the thought.

Thanks for your effort and perseverance!  Your feedback is very valuable
and I hope that it could help in improving the manual by connecting some
missing dots.

Cheers,
simon

Re: Understanding config.scm Modules

[Luis Felipe]

[-- Attachment #1.1: Type: text/plain, Size: 1229 bytes --]

On Wednesday, February 8th, 2023 at 14:07, Simon Tournier <zimon.toutoune@gmail.com> wrote:

> On jeu., 02 févr. 2023 at 19:02, "mhrunnels@yahoo.com" mhrunnels@yahoo.com wrote:
> 

> > 4) Where does the manual list the modules and module options for quick
> > reference?
> 

> I do not understand this question but I guess it is because the question
> #2.

I guess mhrunnels refers to an index of modules, something that is commonly found in API documents. As far as I know, Guix doesn't provide such an index or separate API reference documentation. The Guix manual mentions modules and what they provide in the context of sections.

What you can do is explore the "gnu" and "guix" directories in Guix's source (https://git.savannah.gnu.org/cgit/guix.git/tree/), which provide all those modules and submodules you see imported everywhere. You might also check this video for an explanation of the source tree: https://10years.guix.gnu.org/program/#guixy-guile-the-derivation-factory-a-tour-of-the-guix-source-tree.

Also, You can explore modules using Emacs Geiser and its "Module documentation" option.

Personally, though, I'd like to see a complete Guix API index on the web (that's on my project manager).

[-- Attachment #1.2: publickey - luis.felipe.la@protonmail.com - 0x12DE1598.asc --]
[-- Type: application/pgp-keys, Size: 1722 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 509 bytes --]

Re: Understanding config.scm Modules

[Simon Tournier]

Hi,

On Wed, 8 Feb 2023 at 16:49, Luis Felipe <luis.felipe.la@protonmail.com> wrote:
>
> On Wednesday, February 8th, 2023 at 14:07, Simon Tournier <zimon.toutoune@gmail.com> wrote:
>
> > On jeu., 02 févr. 2023 at 19:02, "mhrunnels@yahoo.com" mhrunnels@yahoo.com wrote:
> >
>
> > > 4) Where does the manual list the modules and module options for quick
> > > reference?
> >
>
> > I do not understand this question but I guess it is because the question
> > #2.
>
> I guess mhrunnels refers to an index of modules, something that is commonly found in API documents. As far as I know, Guix doesn't provide such an index or separate API reference documentation. The Guix manual mentions modules and what they provide in the context of sections.

Ah I see.  Well, using use-package-modules or use-service-modules, why
would you need to know that index of modules?

However, yeah, I agree that some modules from 'gnu' or 'guix' could be
also required.  Indeed, this video...

> https://10years.guix.gnu.org/program/#guixy-guile-the-derivation-factory-a-tour-of-the-guix-source-tree.

...is a really good start.  Maybe, it could be a starting point for
improving the manual.


In addition, I would mention: https://toys.whereis.みんな/

Cheers,
simon

Re: Understanding config.scm Modules

[Andreas Enge]

Hello,

Am Thu, Feb 02, 2023 at 07:02:09PM +0000 schrieb mhrunnels@yahoo.com:
> With the help of Timo Wilken and Paren, I have a working system and am endeavoring to configure Guix to meet my needs.  That said, I am struggling with the Guix manual.  While written well for Guix experts, the manual is a challenge for non-developers and neophytes.  What follows is a practical example of my consternation.

nice that you got the system set up, and cudos for taking the time and
sharing your critique with us. Unfortunately I will mainly reply to the
easier parts, like my predecessors ;-)

> 2) For example, what is the purpose of "use-modules", "use-service-modules", and "use-package-modules"?

Beware that although the system description looks just like an ordinary
text file (much like a configuration file), it is actually a piece of
programming written in Guile/Scheme. So when my configuration contains
something like
  (services
    (append
      (list (service xfce-desktop-service-type)
            (service cups-service-type
                     (cups-configuration
                       (web-interface? #t)
                       (extensions (list cups-filters hplip-minimal))))
   ...
the last entry "(service cups-service-type" etc. defines a printer service
from the Scheme variable cups-service-type, which is defined in a module;
which I need to include by
   (use-service-modules cups)
Or the xfce-desktop-service-type by
   (use-service-modules desktop)
Or both in one by
   (use-service-modules desktop cups)
The modules correspond to files; for instance, the service module cups
is a shortcut for the module (gnu services cups), which you find in
the file gnu/services/cups.scm.

Something similar holds for package modules, but one can do things more
easily. I have this:
  (packages
    (append
      (list (specification->package "nss-certs")
            (specification->package "vim"))
      %base-packages))
Here the line (specification->package "vim") returns the Scheme variable
corresponding to the package with name "vim"; I think one could obtain
the same just writing vim, but would then need to write
   (use-package-modules vim)
as a shortcut to
   (use-modules (gnu packages vim))

> 3) Where does the manual explain the options to be included or excluded with "use-modules", "use-service-modules, and "use-package-modules"?
> 4) Where does the manual list the modules and module options for quick reference?

Watch out, there are no module options: use-modules, use-service-modules
and use-package-modules are just followed by an arbitrary number of modules
(like cups and desktop above).

The way I go about it is to usually (and quite systematically) forget the
inclusion of a module; then most of the time Guix emits a helpful warning
message, and then I add the module as told.

Alternatively, for services, they are documented in the manual. Say you
are interested in printing:
   https://guix.gnu.org/manual/en/guix.html#Printing-Services
It starts by stating "The (gnu services cups) module ...".
So you will have to do a
   (use-modules (gnu services cups))
or
   (use-service-modules cups)

> Finally, I have invested over 40 hours reading the manual and other supporting material.  So, for the "RTM" crowd, I think that time investment reflects a commitment to learn and understand the Guix system. Accordingly, I look forward to hearing from those that can "fill in the gaps" missing from the manual or direct me to the specific resources necessary for me to comprehend what I don't understand.  And as a new Guix user, I am more than willing to contribute by assisting those working to improve the documentation.  A noob to help noobs, if you will indulge the thought.

I hope you enjoyed the manual and did not feel like you wasted your time!
Otherwise feel free to suggest changes.

> PS - once this knowledge "hump" is conquered, questions on the mysteries of %base-services, %base-packages and %desktop-services are next on my list.
> ;; Current Guix Operating System Configuration
>   ;; Packages Appended to %base-packages
>   (packages (append (list (specification->package "awesome")
>                           (specification->package "nss-certs"))
>                     %base-packages))

Maybe I can try to answer a question before it is asked ;-)
%base-packages is a predefined list of packages, that the Guix
people thought would probably be needed all the time.
It is in gnu/system.scm:
(define %base-packages
  ;; Default set of packages globally visible.  It should include anything
  ;; required for basic administrator tasks.
  (append %base-packages-artwork
          %base-packages-interactive
          %base-packages-linux
          %base-packages-networking
          %base-packages-utils))
It is the concatenation ("append") of the more specific lists of
packages %base-packages-artwork and so on, which are given just a few
lines before.
And in your operating system definition you do a similar thing, you
create a list with two packages and concatenate it with this predefined
list.

>   ;; System Services List
>   ;; Services Appended to %desktop-services
>   ;; Services Search - Run 'guix system search KEYWORD'
>   (services (append (list (service tor-service-type)
>                     (service cups-service-type)
>                     (set-xorg-configuration
>                     (xorg-configuration (keyboard-layout keyboard-layout))))
>                   %desktop-services))

Same principle!

Andreas