Understanding config.scm Modules

[address@hidden]

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)))