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