SSS/GNU system - Manual & Documentation

Table of Contents

scheme-guile.svg gnu-guix.svg gnu-emacs.svg shell-eshell.svg shell-fish.svg gnu-make.svg license-gpl3+.svg license-fdl13+.svg

SSS is a Lisp machine adventure, where the hacking culture is celebrated. Let me help you achieve GNUrvana.


You are reading the manual for the Supreme Sexp System (SSS).

This manual documents the SSS/GNU system and its functionalities.

If you like my work, please support me by buying me a cup of coffee so I can continue with a lot of motivation.

You can follow the project here on Codeberg, or on the fediverse at Mastodon: https://mastodon.social/@sss_project


SSS is a custom GNU + Linux setup lets you customize everything endlessly, inspires creativity and problem-solving, and gives you a great user experience. This is partly thanks to the REPL (Read Eval Print Loop) and Lisp programming languages.

SSS strives to have all things configured via Lisp dialects when possible and convenient, staying accessible to all kinds of users, and allowing for magical things to happen šŸŖ„.

āš ļø Installing and managing SSS is not meant for people new to GNU/Linux systems. You should already have some experience with software development. Knowing Lisp dialects, or functional programming techniques is also a big help and is something you will learn further.

dall-e-3-thumb.png

I would appreciate if you write your findings when using SSS and if you can, fork the project, and contribute some improvements, or mail me at <jjbigorra@gmail.com>

It is recommended to use tagged releases of SSS, as those are considered as stable by the developers.


1. Licensing

sss and all of its source code are free software, licensed under the GNU General Public License v3 (or newer at your convenience).

https://www.gnu.org/licenses/gpl-3.0.nl.html

The documentation and examples, including this manual, which are provided with sss, are all licensed under the GNU Free Documentation License v1.3 (or newer at your convenience).

https://www.gnu.org/licenses/fdl-1.3.html


2. What lies here?

2.1. An operating system (OS) configured in Lisp (Guile Scheme)

  • GNU Guix system configuration
  • šŸŽØ Theme palettes that affect the entire system (ef-themes, solarized-light, everforest dark and light)
  • Hyprland configuration (power user session)
  • Labwc configuration (work-in progress - universal session)
  • Fish shell configuration
  • Alacritty terminal emulator
  • Firefox custom declarative configuration inspired on BetterFox
  • Waybar configuration and style
  • Rofi application launcher
  • Mako configuration and style
  • multi-user Git configuration setup (work/personal)
  • Fastfetch configuration
  • Multi user configuration

    and more….

2.2. Joe's Emacs configuration

An operating system unto itself šŸ‚.

  • Advanced and modular Emacs configurations with Emacs Lisp + Elpaca
  • Dev setup for: Scheme, Scala, Haskell, Lisp, Rust, Python, Shell, Nix, Golang and more

2.3. Universal session

I also include a (work in progress) Windows-like session for "non-geek" users, with "normal floating windows". This session uses labwc compositor and waybar.


3. Code of conduct

This project adheres to the jointhefreeworld code of conduct. Find it here:

https://jointhefreeworld.org/blog/articles/personal/jointhefreeworld-code-of-conduct/index.html

In summary, we foster an inclusive, respectful, and cooperative environment for all contributors and users of this free software project. Inspired by the ideals of the GNU Project, we strive to uphold freedom, equality, and community as guiding principles. We believe that collaboration in a community of mutual respect is essential to creating excellent free software.

4. Why ?

Find the divine sayings, and the destined computer configurations, all my Guix, Scheme, Hyprland, and Emacs Lisp and more configurations here for learning you a fully Lisp machine with GNU/Linux for a great good.

āš ļø Warning: parts of the code and settings might default to the Dutch language ( nl_NL.UTF-8 ).

I refer to SSS lovingly as the modern Lisp machine. With this one obtains a computing style and programming environment that can be referred to as Lisp user space. This is a modern iteration of the Lisp machines of yore.

You can be aware of all the code that is running on your machine, which puts free GNU systems among the most secure operating systems on Earth.

Learning Lisps is really going down a rabbit hole, but trust me, you will come out with a better understanding of programming as a whole out the other end.

Lisp user space provides an introspective, hackable, and transactionable operating system that can be modified live in a REPL.

⭐ The lines between data and code fade, allowing insane flexibility and power.

In some ways this is a laboratory of experimentation for my computing environment. What I do with any other program that forms part of SSS is only meant to work for me. As such, I will try to maintain backwards compatibility and consistency, but I may introduce breaking changes without prior notice.

This configuration is somewhat biased towards containing a joe user who also acts as administrator for most of the time. This is trivial to change and should be easy to adapt to your needs. Your mileage may vary (YMMV).

I have a bias towards Emacs-style behaviors and keyboard shortcuts, so most of my preferences in software settings get reflected on SSS, while I do try to make it all configurable.

Some commands in the Makefile are more geared towards joe since we assume a device is most frequently only tended to by one system administration most of the time. Some examples are make fr or make jr. Feel free to change this or contribute improvements to make this modular.

The system and home folders of users are managed independently of each other, in quite a loosely coupled manner.

5. What is Guix

GNU Guix is a package management tool for and distribution of the GNU system. Guix makes reproducibility easy and allows users to install, upgrade, or remove software packages, to roll back to a previous package set, to build packages from source, and generally assists with the creation and maintenance of software environments.

While you can install GNU Guix on top of an existing GNU/Linux system where it complements the available tools without interference, I encourage the use of Guix system, as standalone operating system distro, on top of which I have built the Supreme Sexp System (SSS).

I highly recommend refering to and studying the Guix reference manual, it's a super valuable source of knowledge: https://guix.gnu.org/manual/en/html_node/.

6. On Non-free software

SSS attempts to stay as libre as possible, while also respecting your convenience.

This means, among other things that SSS:

  • includes the OG Linux kernel (with proprietary blobs) so as to be more compatible with modern hardware
  • includes non-guix software channel by default, so as to allow installation of convenient software to which few/no libre alternatives exist.

With this being said, SSS strives to provide the four freedoms, and will help you and steer you towards free choices that respect your freedom, rights and privacy.

7. About this manual

This manual is written by hand with care and attention for detail.

We try to write this manual to cater to the widest possible audience, and to make it easy to onboard new users to SSS. We also try to document things extensively here, so you have a point of reference.

When keybindings (shortcurts) are defined or mentioned, the following legend applies (a la Emacs):

term meaning
s Super / Windows / CMD key
S Shift key
M Meta / Alt / Option key
C Control key
SPC Space key

8. Showcase

Note: Screenshots below might be outdated and no longer representative of the current, ever-changing state of SSS.

7bdfaa50fbc45b63.png

2025-03-05-2.png

2025-03-05-3.png


9. Videos about SSS (Supreme Sexp System)

Some tutorials, conversations and videos have been made about SSS, some more up to date than others:

<2025-03-06 do>

SSS/GNU - Supreme Sexp System Installation Demo - How to install Joe's riced up Guix system @ virtual machine

https://youtu.be/wZUes_10US8


10. Bootstrapping

It's possible you need to some manual installations, and temporary workarounds, in order to install sss on a brand-new Guix installation.

Some aspects will be dependent on the manner of installation and hardware. Below follows a simple startup guide.

On Hardware Requirements:

While SSS is designed to be lightweight and efficient, certain hardware configurations will provide a smoother experience. The following are recommended minimums:

  • CPU: A modern x86-64 processor (Intel or AMD) is preferred. ARM64 is supported but may require additional configuration.
  • RAM: 4GB of RAM is the absolute minimum. 8GB or more is highly recommended for a comfortable experience, especially if you plan to run memory-intensive applications or virtual machines.
  • Disk Space: 90GB of disk space is a good starting point. Consider more if you plan to install a large number of packages, store many files, or use virtual machines extensively. SSDs are strongly recommended for optimal performance.
  • Graphics: SSS leverages Wayland and Hyprland. Most modern graphics cards should work well. If you encounter issues, consult the Hyprland documentation for compatibility information.

Download and the Guix GNU/Linux distribution from the official Guix page: https://guix.gnu.org/download/ and make a bootable installation medium convenient for your use case.

If you are not familiar with the dd command which is present in all GNU/Linux distributions and in macOS, you can always feel free to use something like Rufus on Windows, or balenaEtcher, to flash this image into a USB, with which you can then boot your computer.

It is highly recommended to first become familiar with SSS and Guix via a throw-away virtual machine where you can experiment and do mistakes. After familiarity is acquired then a bare metal installation is the best.

SSS strives to be completely cross-architecture and should work well everywhere. That being said, as of the latest manual, x86-64 is the preferred architecture.

If your system doesn't boot due to lack of drivers, it can be useful to add the nomodeset option after quiet in the GRUB menu, by editing the boot "command" of the latest entry.

If you are on aarch64/arm64, or other more niche architectures, then you might need to put in some more work to get an installer image, and to get it working, likely having to generate an ISO image yourself to install Guix or a qcow2 virtual machine.

The following articles may be of help: https://jointhefreeworld.org/blog/articles/gnu-linux/gnu-guix-virtual-machine-image-aarch64/

If things really aren't working with your hardware, you can build your own ISO with the right drivers, or use the one from nonguix: https://gitlab.com/nonguix/nonguix/-/releases

It is highly recommended to connect your device to Internet via an Ethernet cable or some other form of wired connection, specially since Guix by default will only come with free software drivers, and as such, might not immediately support your WiFi card. After installing SSS drivers will be there and you can use WiFi.

When installing Guix, make sure you take note of the Scheme code that gets generated by it, specially for the disk partitioning. You will see this at the last install step. This code can also be found after installing, at /etc/config.scm by default. Parts of this code will later need to be added to the per-host.scm.

After having installed things using the guided Guix installer, or via the command line for advanced users, boot into your new system.

I would recommend to then use a web browser and visit the web version of this manual: https://codeberg.org/jjba23/sss/src/branch/trunk/docs/Manual.

Once you have a working Guix base installation on your machine, you are ready to go about installing SSS.

11. Per host - per-host/sss/overrides.scm

It is REQUIRED to include a per-host/sss/overrides.scm in the root of this project, which is excluded from Git, and will determine certain settings for your own machine.

The idea is that by default, we will use the settings that come from src/sss/defaults.scm, unless there exists an override with a matching name at per-host/sss/overrides.scm.

For example if you want to set your own system language, and thus not use default-lang, you need to define and export a override-lang with a compatible value. This logic applies to all settings in src/sss/defaults.scm.

You will NEED a file at per-host/sss/overrides.scm with at least:

(define-module (sss overrides))

Although you will likely want to add your filesystems, to get a working Guix system.

Find here an example configuration of a SSS overrides file for one of my machines, this one with BTRFS and LUKS encryption.

;;; SSS - Supreme Sexp System

;; Copyright Ā© Josep Bigorra <jjbigorra@gmail.com>

;; sss is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; sss is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with sss.  If not, see <https://www.gnu.org/licenses/>.

(define-module (sss overrides)
  #:declarative? #t
  #:use-module (gnu)
  #:use-module (gnu packages)
  #:use-module (gnu bootloader)
  #:use-module (gnu system file-systems)
  #:use-module (gnu system accounts)
  #:export (override-extra-packages override-filesystems
                                    override-hostname
                                    override-hyprland-extra-startups
                                    override-hyprland-monitors
                                    override-keyboard-layout
                                    override-lang
                                    override-mapped-devices
                                    override-palette
                                    override-subgids
                                    override-subuids
                                    override-sudoers
                                    override-users
                                    override-timezone))

(define override-sudoers
  (let ((no-passwd-cmd (string-join '("/run/current-system/profile/sbin/halt"
                                      "/run/current-system/profile/bin/chvt"
                                      "/run/current-system/profile/sbin/reboot"
                                      "/run/current-system/profile/bin/loginctl")
                                    ",")))
    (string-join `("root ALL=(ALL) NOPASSWD:ALL" "%wheel ALL=(ALL) ALL"
                   "joe ALL=(ALL) NOPASSWD:ALL"
                   ,(format #f "manon ALL=(ALL) NOPASSWD:~a" no-passwd-cmd)
                   ,(format #f "claudio ALL=(ALL) NOPASSWD:~a" no-passwd-cmd))
                 "\n")))

(define override-subgids
  (list (subid-range (name "joe"))
        (subid-range (name "manon"))))

(define override-subuids
  (list (subid-range (name "joe"))
        (subid-range (name "manon"))))

(define joe-user-account
  (user-account
    (name "joe")
    (group "users")
    (supplementary-groups '("wheel" "netdev"
                            "audio"
                            "video"
                            "input"
                            "libvirt"
                            "cgroup"))
    (comment "Josep Bigorra's account")
    (home-directory "/home/joe")))

(define manon-user-account
  (user-account
    (name "manon")
    (group "users")
    (supplementary-groups '("wheel" "netdev"
                            "audio"
                            "video"
                            "input"
                            "libvirt"
                            "cgroup"))
    (comment "Manon van den Bout's account")
    (home-directory "/home/manon")))

(define override-users
  (list joe-user-account manon-user-account))

;; system language
(define override-lang
  "nl_NL")

;; system timezone
(define override-timezone
  "Europe/Amsterdam")

;; system keyboard layout
(define override-keyboard-layout
  "us")

;; system hostname
(define override-hostname
  "gnu-framework")

(define override-extra-packages
  '("amd-microcode" "amdgpu-firmware" "prismlauncher"))

(define override-hyprland-extra-startups
  '("sudo warp-svc" "sudo mkdir -p /usr/share/warp/images"
    "sleep 1 && warp-taskbar"))

(define override-palette
  'ef-dream)

(define override-mapped-devices
  (list (mapped-device
          (source (uuid "e84af212-b13b-4163-9165-57bd6f1b787d"))
          (target "rootfs")
          (type luks-device-mapping))))

(define override-filesystems
  (list (file-system
          (mount-point "/")
          (device "/dev/mapper/rootfs")
          (type "btrfs")
          (dependencies override-mapped-devices))
        (file-system
          (mount-point "/boot/efi")
          (device (uuid "FC82-5EC0"
                        'fat32))
          (type "vfat"))))

(define override-hyprland-monitors
  '("monitor = , preferred, auto, 1.33333"))

When doing a system or home reconfigure, SSS will try to give you as much information as possible about the current settings you chose for. Here follows an example:

[INFO] 2025-05-27 18:35:06+02:00 - begin working on target: joe-reconfigure...

(get-setting 'lang): "nl_NL"
(get-setting 'timezone): "Europe/Amsterdam"
(get-setting 'keyboard-layout): "us"
(get-setting 'caps-to-ctrl?): #t
(get-setting 'hostname): "gnu-framework"
(get-setting 'clone-dir): "$HOME/hacking/sss"
(get-setting 'palette): ef-dream
(get-setting 'hyprland-monitors): ("monitor = , preferred, auto, 1.33333")
(get-setting 'hyprland-extra-startups): ("sudo warp-svc" "sudo mkdir -p /usr/share/warp/images" "sleep 1 && warp-taskbar")
(get-setting 'labwc-extra-startups): ()
(get-setting 'flatpak-user-remotes): ((flathub . "https://dl.flathub.org/repo/flathub.flatpakrepo"))
(length (get-setting 'flatpak-pkgs)): 5
(length (get-setting 'extra-packages)): 3
(length (get-setting 'nixpkgs)): 30

12. Explaining certain choices

Q: Why choose for Emacs-style keybindings in the power-user session?

A: SSS puts a heavy emphasis on mnemonics and ease of use. Emacs keybindings are well documented, well known and are quite easy to remember thanks to mnemonics, as well as being quite ergonomic too, specially when combined with split keyboards and thumb clusters. In the universal session we choose for CUA-style keybindings to be familiar to most people.

Q: Why choose to put Waybar at the bottom, when most rices put it at the top?

A: SSS chooses to place the status bar at the bottom of the screen to minimize distractions. We mostly read things from top-left to top-right, and having a bar take that prominent space in the screen can be wasteful and distracting, and you end up looking at the clock or start button more often than the actual task you are working on. This is true for both the power-user session and the universal session (it might help for people that used Windows).

Q: Capabilities?

A: In SSS, the concept of "capabilities" is fundamentally woven into the system's design. It represents a higher-order approach to managing your computing environment, abstracting away complexity and details beyond the granular configuration of individual Guix Home files or distinct Guix services.

This abstraction simplifies configuration, promotes reusability, and fosters a more intuitive interaction with the system, allowing for the composition of complex environments by simply enabling a collection of predefined, yet customizable, functionalities.

See home/joe.scm for more examples on how to use the capabilities, and see src/sss/ for more details on all the capabilities available.


13. User Management

SSS works by programatically define users via code. By default there will be a user sss that is in the wheel group.

You should create users by tweaking the Scheme code in the per-host overrides and you should also create a Guix home file (home/<user>.scm) if you want to use the home services SSS provides.

When everything is in place, if it's a new user, you can add a password to the user with sudo passwd <user>. If this user was created by the Guix install then this will already be done for you.

āš ļø You shouldn't create users manually with useradd or the likes, and sudoers should also be managed from Scheme code, not by manually editing /etc/sudoers. If you do these things manually, Guix will reset them at next reboot or reconfigure.


14. Adding channels

Add nonguix in your channels file ($HOME/.config/guix/channels.scm). This will later be overwritten by SSS.

(cons* (channel
      (name 'nonguix)
      (url "https://gitlab.com/nonguix/nonguix")
      (introduction
       (make-channel-introduction
        "897c1a470da759236cc11798f4e0a5f7d4d59fbc"
        (openpgp-fingerprint
         "2A39 3FFF 68F4 EF7A 3D29 12AF 6F51 20A0 22FB B2D5"))))
     %default-channels)

After adding the channel, perform a guix pull from your user account (no sudo or root) and let all channels get updated.

15. Installation of SSS

Once you have followed all those above steps, you can enter a temporary Guix shell, so as to bootstrap SSS.

You can do this with guix shell make git icecat. Icecat is a 100% libre version of Firefox, and it will be temporarily used for you to browse temporarily to Codeberg and download and install SSS.

Then proceed to clone SSS with git clone --recursive https://codeberg.org/jjba23/sss.git to your favourite location. This location will need to be added to your per-host/sss/overrides.scm. You can skip the --recursive option if you are not interested in the wallpapers and other art.

If digital-art-dreams (the wallpapers and so on) didn't get properly cloned to your destination, you can always cd into the SSS clone path, and then do a git submodule add https://codeberg.org/jjba23/digital-art-dreams.git submodules/digital-art-dreams and then a git submodule update --init --recursive. Also from time to time, handy to keep the submodules updated with git submodule update --recursive --remote.

See more about Git submodules here:

https://git-scm.com/book/en/v2/Git-Tools-Submodules


You should have by now written an appropriate per-host/sss/overrides.scm for your setup. See the above section on this topic.

Enter the directory of SSS: cd sss and do a make sr.

Note: make sr translates to sudo guix system reconfigure with some extra settings.

While unlikely, it's possible that some packages fail to install/build for your setup. I would encourage to temporarily comment those out of the configuration (likely at src/sss/packages/) and try again. After a working SSS setup, you can uncomment them and try again.

For more commands take a look at the SSS Makefile: ../../Makefile.

The --fallback option is optional, and simply helps when upstream substitute (cache) servers are less available.

Once the system reconfigure is complete, you should also bootstrap your user's GNU home with something like: guix home reconfigure

You might at this point want to reset the font cache for the system and user.

fc-cache -frv
sudo fc-cache -frv

You can then reboot and you should be greeted by a simple TTY.


15.1. Keeping SSS updated

You should every now and then update the SSS repo with git pull. You also should regularly do a guix pull from your regular user, and then rebuild this system with the root user (make sr).

It's important to also keep the SSS modules updated, and thus from time to time run git submodule update --recursive --remote.

Guix is a rolling distribution and you don't need to be always on bleeding edge releases, but it's nice to stay updated.


16. Login managers, and login screen

SSS uses no login managers like GDM or SDDM. Simply login to the TTY and start your favorite GUI (or not). That being said, feel free to use your own.

I like to alias my login command to gui, or sometimes I directly run hyprland or labwc from the TTY.

Sometimes for the fun I work in Emacs from the TTY for that 60's and 70's computer vibe.

If you run traditional X11 sessions, you could choose to do startx instead of a Wayland session, but SSS is more geared to Wayland.


17. Important directories

SSS uses the Guix and GNU/Linux conventions as closely as possible, and also tries to adhere to the XDG standards. Apart from that, here are some interesting files and directories that may not be so obvious:

  • Guix Shepherd Home Services and Timerslog file: $XDG_STATE_HOME/shepherd/shepherd.log which is often ~/.local/state/shepherd/shepherd.log

18. On Emacs

A customized Emacs is an extension to a human's being, and an invaluable tool in productivity. Part of SSS is my Emacs configuration as well. I do try to make my config as portable as possible, and it should work pretty well out of the box in non-Guix systems, although it's best enjoyed as part of SSS and with Guix (and Guix home).

Thanks to using modern standards and a modular approach, SSS has a very flexible and powerful Emacs configuration, with facilities for all kinds of software development with comfort, that will make your IDE-using coworkers green with envy, it has creative writing features, ergonomics and mnemonics in mind, and doesn't sacrifice in good looks.

Package management is done with Elpaca in an asynchronous and non-blocking way, ensuring that Emacs starts up blazingly fast (faster than certain Vim setups) and making sure that packages are loaded properly and with good practices.

Some of the tweaks and improvements you get:

Ultra smooth scrolling (yes also on touchpad/trackpad), super fast startup, pretty modeline, nice welcome screen, transparency in Emacs, good use of monospace and sans-serif fonts, no-config and no-headache language server integrations with many languages, opinionated and good-practice settings for language servers, pretty and fast Org mode buffers, etc.

I split the Emacs configuration into several modules that you can optionally include/exclude, see src/sss/emacs/modules. Here follow some explanations of each module:

18.0.1. common-lisp.el

This module configures the sly package, transforming Emacs into a robust Common Lisp development environment. It installs sly directly from its GitHub repository and ensures it loads immediately when Emacs starts. The configuration also specifies that sly should connect to SBCL (Steel Bank Common Lisp) as the preferred underlying Lisp interpreter, providing a complete suite of tools for writing, evaluating, and debugging Common Lisp code within Emacs.

18.0.2. consult.el

This module significantly upgrades Emacs's search and navigation through the configuration of the consult package. The primary functionality it provides is a unified and enhanced interface for nearly all interactive searching and jumping within Emacs. This means you get much more powerful ways to:

  • Navigate quickly: Easily switch between open buffers, browse bookmarks, and find recent files, including those part of a specific project. You can also jump precisely to lines, headings, marks, or code symbols within a file.
  • Search efficiently: Perform robust searches across files using tools like grep, git grep, and ripgrep, search specifically within the current buffer, and more.
  • Manage history and commands: Access and cycle through your command history and kill-ring (yanked text) with greater ease.

The configuration heavily customizes keybindings, mapping a wide array of consult commands to intuitive shortcuts under prefixes like C-c, M-g, and M-s. It also integrates consult with Emacs's default completion system and cross-reference features, providing a seamless and more intelligent user experience across the board.

18.0.3. dashboard.el

This module configures a custom "dashboard" or "welcome screen" using the welkomscherm package, offering quick access to frequently used directories and system actions.

The primary functionality is to provide a personalized, interactive starting point within Emacs. It organizes and presents:

  • Custom Bookmarks: Two distinct sets of bookmarks are defined: personal and work. These bookmarks are designed for quick navigation to specific file paths.
  • Action Buttons: A set of interactive buttons allows for one-click execution of common Emacs actions and system commands. This includes switching to essential buffers like scratch and Messages, re-rendering the welcome screen itself, and/or executing system rebuild commands (sss-sys-reconfigure and sss-joe-reconfigure).

The welkomscherm package itself is installed directly from its Codeberg repository. The configuration binds the welkomscherm command to C-c SPC SPC, making it easily accessible.

18.0.4. dev.el

This module transforms Emacs into a comprehensive development environment by configuring various language-specific modes and essential developer utilities.

The configuration provides specialized support for numerous programming languages, ensuring proper syntax highlighting, intelligent indentation, and language-specific features. This includes dedicated modes for Rust, Python (with integrated black auto-formatting on save), Haskell, Scala, Lua, TypeScript, Nix, TOML, YAML and more.

For Lisp-based languages such as Emacs Lisp and Scheme, the setup enables aggressive-indent for consistent automatic indentation. Additionally, it configures geiser and geiser-guile to provide a robust interactive development environment for Scheme (Guile). I actually use Ares/Arei for Guile instead of Geiser by the way, but for other Schemes it can be nice.

Beyond language-specific features, the code integrates several packages designed to streamline common developer workflows. package-lint assists in linting Emacs Lisp packages, while smartparens enhances code editing with intelligent auto-pairing and manipulation of delimiters. direnv integrates with your system's direnv setup, automatically managing environment variables when navigating project directories.

For containerization, it includes support for Docker, with a dedicated mode for Containerfiles/Dockerfiles with podman, and keybindings for container interactions.

Visual enhancements come from fancy-compilation, which improves the appearance of compilation output, and diff-hl, which provides visual indicators in the margin for changes in version-controlled files, seamlessly integrating with magit and dired.

For document editing, markdown-mode is set up for better readability with adjusted line wrapping and font settings, as well as more alignment with Org mode.

Finally, request provides general HTTP client capabilities, and flymake-collection enables on-the-fly syntax checking and error highlighting.

18.0.5. dired.el

This module significantly upgrades the dired file manager, turning it into a more powerful and visually intuitive tool for file and directory navigation. The primary functionality centers on improving the user's interaction with dired.

It enables subtree navigation through the dired-subtree package, letting you expand and collapse directories right within the dired buffer for a convenient tree-like view of your file system (use TAB).

This setup also customizes the display, ensuring a cleaner look. Additionally, dired-open-with is included to allow opening files in dired using external applications, similar to a graphical file manager's "Open With" feature. Finally, nerd-icons-dired integrates visually appealing icons next to files and directories in dired listings, making file types more quickly identifiable and enhancing the overall aesthetic.

Together, these packages combine to make dired a more user-friendly, visually rich, and efficient file management solution within Emacs.

18.0.6. eglot.el

This module heavily customizes eglot, Emacs's built-in client for the Language Server Protocol (LSP). This setup transforms Emacs into a sophisticated, feature-rich integrated development environment (IDE) by enabling advanced language-aware functionalities across numerous programming languages.

This includes real-time diagnostics (errors and warnings), code completion, "go to definition," "find references," code formatting, refactoring capabilities (like renaming symbols), and displaying type information.

The configuration explicitly enables eglot for Scala, Shell scripts, Haskell, Markdown, Nix, Go, Python, Rust, and YAML modes, ensuring that language features are available automatically when you open files in these modes. It also binds numerous eglot commands to C-c i prefixes, making these powerful features readily accessible. Furthermore, it's configured to format the buffer automatically before saving, helping maintain consistent code style.

Regarding package configuration, eglot itself is the central piece here. The configuration fine-tunes eglot's behavior with several settings: it ensures eglot servers automatically shut down when no longer needed (eglot-autoshutdown t), confirms server edits without prompting (eglot-confirm-server-edits nil), and displays progress reports (eglot-report-progress t). It also enables eglot to integrate with Emacs's cross-referencing system and to automatically reconnect to servers.

Crucially, the configuration customizes which language servers eglot uses for specific modes: for Scala, it explicitly uses the "metals" server; for Nix, it uses "nil" (likely referring to the nil LSP server for Nix); and for Markdown, it uses "marksman".

It also sets language-specific configurations for metals (Scala), haskell (using ormolu for formatting), typescript and javascript (setting formatting rules like indent size and semicolon removal), rust-analyzer (enabling cargo features, build scripts, and proc macros), and yaml (enabling formatting, validation, hover, completion, and schema validation with specific schema URLs). Finally, it integrates eglot's diagnostics with Emacs's eldoc and flymake systems, ensuring that errors and information are displayed prominently, and sets up flake8 as the linter for Python through flymake when eglot is active.

18.0.7. emacs-core.el

This module focuses on refining the core Emacs user experience and integrating essential tools for a more efficient workflow.

We set up flymake for efficient navigation through code diagnostics and errors, allowing for quick issue resolution. The which-key package (now built-in) is configured to offer interactive keybinding help, making it much easier to discover and remember Emacs commands as you type. For a consistent visual experience, a custom new-frame-setup function is defined to apply initial UI scaling and base face settings across all Emacs frames, regardless of whether they are graphical or terminal-based.

Beyond these, the configuration deeply customizes fundamental Emacs behaviors. It rebinds common actions like buffer management to ibuffer, adds shortcuts for comparing buffers, toggling debugging, and evaluating Emacs Lisp code. Crucially, it introduces numerous custom keybindings for system-level reconfigurations and updates (e.g., sss-joe-reconfigure, sss-sys-update) and project-specific actions like starting REPLs, formatting code, running tests, and initiating development environments.

Text editing and display are refined with settings for line spacing, automatic indentation (preferring spaces), and global symbol prettification for better code readability. It ensures automatic line wrapping in text modes and that Emacs remembers your cursor position and recently opened files across sessions.

Enhancements to the dired file manager include a cleaner listing view and optimized buffer handling. Finally, the startup experience is personalized to display a custom "welkomscherm" (welcome screen), and recentf-mode is enabled to keep a convenient history of your opened files.

The setup also includes global line highlighting and a preferred bar cursor (often better for writing and a more intuitive approach than a block cursor like in a terminal).

18.0.8. erc.el

This module configures erc, Emacs's built-in IRC (Internet Relay Chat) client, turning Emacs into a fully functional chat interface.

This includes connecting to IRC networks, joining channels, and participating in chat. The configuration sets a default nickname and automatically joins specific channels upon connecting. It's also tailored to improve the chat experience by customizing message display, such as hiding common "JOIN," "PART," and "QUIT" messages to reduce clutter, and configuring how text fills and wraps in chat buffers. For reliability, it sets up automatic server reconnection attempts.

The setup explicitly enables erc-services-mode and incorporates additional erc modules for notifications and spelling, enhancing the client's utility by providing alerts for messages and assisting with correct grammar.

18.0.9. go.el

This module configures go-mode, providing dedicated support for developing in the Go programming language within Emacs.

This includes proper handling of Go source files, syntax highlighting and intelligent navigation. It integrates with external Go tools by specifying that gofumpt should be used as the code formatter, ensuring consistent code style. When a Go file is opened, it automatically sets the indentation to use tabs with a width of 4 spaces, adhering to common Go style conventions.

18.0.10. libs.el

This module configures several general-purpose utility libraries and also a macro recording tool, all designed to enhance Emacs's foundational capabilities.

We setup the transient package, which is a core component for many modern Emacs features, streamlining complex multi-key commands and interactive completion.

We also incorporate the f package for convenient filesystem utilities, simplifying common operations with files and directories directly within Emacs Lisp.

For visual organization, page-break-lines adds distinct indicators for page breaks, useful for segmenting documents or code.

A queue data structure is introduced through its dedicated package, providing a fundamental programming construct for various internal Emacs Lisp operations.

Lastly, elmacro is configured to enhance Emacs's built-in macro capabilities, allowing for more sophisticated recording and playback of command sequences, and is activated globally.

18.0.11. macros.el

This module defines and configures several editor macros, small abstractions that make text editing and other tasks faster and more efficient, by means of automation. You can use elmacro to record keyboard macro/sequences into clean Emacs Lisp code. You can then also bind these macros to a key for convenient access.

18.0.12. maps.el

This module configures the osm package, integrating OpenStreetMap functionalities directly into Emacs. The primary functionalities provided include the ability to view and interact with maps within Emacs, save coordinates, integrate with Org mode. It allows you to display OpenStreetMap data, and the configuration ensures that copyright information is shown on the maps.

It also sets up a dedicated prefix key, C-c m, for osm commands, making it convenient to access map-related functions.

18.0.13. misc.el

This module configures additional miscellaneous extensions and tweaks to Emacs. Some of those include git-riddance to nuke Git repo history (also on remote), dagboek to easily create and organize your daily diary entries, gptel for LLM integration inside Emacs, guix for integration with the amazing Guix package manager, and more.

18.0.14. music.el

This module significantly enhances Emacs's capabilities for music in different ways.

It configures fretboard, which provides tools for visualizing and interacting with guitar fretboards and chords.

It sets up smudge to allow controlling Spotify from within Emacs (note you need a running Spotify client in your machine).

Finally, it configures emms (Emacs Multimedia System), turning Emacs into a full-featured music player. It ensures all emms components and default players are loaded, specifically enabling emms-mpris for integration with desktop media players.

The default directory for music files is set to sss-ews-music-directory, and album covers are configured to be displayed asynchronously in the browser.

18.0.15. org.el

This module deeply integrates and customizes Org mode, Emacs's powerful plain-text note-taking and outlining system, transforming it into a robust environment for personal knowledge management, task tracking, and document creation.

The primary functionality provided centers around enhancing the core Org mode experience. It customizes org-mode itself with specific hooks that apply a variable-pitch font for better readability, enable Org indent mode, disable auto-fill for greater control, and activate olivetti-mode for a more focused writing experience.

Visual clutter is reduced by hiding emphasis markers and leading stars, and pretty entities are enabled for improved display.

Source code blocks within Org files are configured for native fontification and tab behavior, with zero indentation for cleaner editing. Keybindings are also adjusted, including one to toggle link display.

For task management, org-todo-keywords are set to a workflow including "TODO," "WIP," "REVIEWING," and "DONE," with done tasks automatically logging their completion time.

Beyond the core org package, this module integrates org-roam and org-roam-ui to create a sophisticated Zettelkasten-style personal knowledge management system.

org-roam facilitates rapid note creation, linking, and navigation, with custom keybindings for finding nodes, inserting new ones, capturing dailies, and toggling a buffer for linked notes. It's configured to automatically sync the database and uses a custom template for node display, showing both title and tags. org-roam-ui provides a graphical web interface for visualizing your org-roam graph, configured to sync themes, follow node selections, update on save, and open automatically when Emacs starts.

Additional functionalities include org-present for creating presentations directly from Org files, and org-auto-tangle, which automatically extracts source code blocks from Org files, making it ideal for literate programming configurations. Finally, ob-http and ob-mermaid are included, extending Org mode's ability to execute HTTP requests and render Mermaid diagrams directly within Org buffers.

18.0.16. search.el

This module enhances Emacs's searching capabilities by integrating powerful external tools. It sets up ripgrep, a fast, modern grep alternative, to handle efficient text searching across files (considering .gitignore too).

Complementing this, the module also configures deadgrep, which provides a user-friendly interface within Emacs for executing ripgrep searches and navigating their results. A dedicated keybinding, C-c z g, is assigned to deadgrep, making these advanced search functionalities easily accessible.

18.0.17. shell.el

This module profoundly customizes Emacs's Eshell, its built-in command-line shell, to provide a more functional and aesthetically pleasing terminal experience, along with integrating Git information.

The primary functionality offered centers on enhancing the shell's usability and integrating it seamlessly with Emacs's file management and version control. It introduces a custom function, git-prompt-branch-name, to dynamically retrieve and display the current Git branch name directly within the shell prompt, offering immediate context when navigating repositories.

The eshell-here function C-! allows you to quickly open an Eshell buffer in the directory of your current file, intelligently renaming the Eshell buffer to reflect that directory for easier management of multiple shell sessions.

To keep the prompt concise, the fish-path function intelligently abbreviates long directory paths, replacing parent directories with their initial characters.

The core of the shell's appearance is customized through the sss-eshell-prompt function, which creates a visually informative multi-line prompt displaying the username, hostname, current directory (abbreviated), and the Git branch name, all with enhanced font styling. It also sets up a custom banner message for a personalized welcome.

For better workflow, a collection of aliases is defined, mapping common shell commands to their Emacs equivalents or custom functions. This includes g for magit (Git interface), gl for magit-log, d for dired (file manager), and o and oo for opening files in the current or another window. It also includes l and ll for a detailed directory listing.

Overall, this module transforms Eshell into a powerful and user-friendly command-line environment tailored for development and system interaction.

18.0.18. sss.el

This module acts as the core integration for SSS (Supreme Sexp System) environment, defining crucial variables and a suite of functions for system maintenance, project development, and general utilities within Emacs.

The module first establishes several user-configurable variables.

A significant part of this module is dedicated to automating various system and project-specific tasks, primarily by executing make commands asynchronously.

For general utility, sss-uuidgen generates and yanks a unique identifier to the kill ring, while sss-uuidgen-string simply returns it as a string.

The module also introduces several robust utilities to streamline project-based operations. sss-do-in-project is a versatile function that runs a given operation within the root directory of your current version-controlled project.

async-shell-to-buffer is a helper that executes shell commands in the background, directing their output to a dedicated Emacs buffer so you can continue working uninterrupted. Building on this, the module includes specialized functions for common development tasks: sss-project-start-repl-process kicks off a project-specific REPL, sss-project-fmt initiates project-wide code formatting, sss-project-start-dev begins a development session, and sss-project-start-test runs the project's test suite.

Finally, the module provides specialized functions for code formatting and data presentation. sss-guix-fmt formats the current buffer in place using the guix style command, ensuring adherence to specific coding standards.

Additionally, sss-new-buffer-with-json creates a new buffer, inserts JSON data, attempts to format it neatly, and then switches you to that new buffer for easy viewing. This is useful for working with HTTP bodies and responses too.

18.0.19. theme.el

This module manages the visual appearance of Emacs by configuring and applying various color themes.

Its primary functionality is to provide a flexible system for loading different Emacs themes, particularly focusing on ef-themes, solarized-theme, and everforest.

The module also includes custom palette overrides for certain ef-themes (like ef-bio, ef-autumn, and ef-cyprus), allowing for fine-grained adjustments to their default color schemes.

The module then conditionally loads a specific theme based on the value of the sss-emacs-theme variable. This ensures that your Emacs instance consistently loads your chosen aesthetic from the defined collection of themes upon startup.

18.0.20. ui.el

This module significantly enhances Emacs's user interface and visual feedback, focusing on dynamic visual cues, optimized text presentation, intelligent font scaling, and comprehensive display customization.

The module configures pulsar to provide dynamic visual feedback, causing the cursor or targeted text to "pulse" when certain actions occur, such as jumping to a location or revealing entries after a search. This visual cue is customized with specific colors based on the active Emacs theme (ef-dream, everforest-hard-dark, everforest-hard-light), enhancing immediate feedback.

olivetti is also included, a package that centers text within the buffer, promoting a more focused writing or reading experience by limiting line width.

vertico is configured as the primary completion UI, providing a highly performant and customizable experience with features like cycling through candidates and dynamic resizing. marginalia works alongside vertico to add descriptive annotations to completion candidates.

At its heart, this module integrates tekengrootte, a package designed for highly granular control over font sizes across various Emacs UI elements. It provides numerous keybindings (C-c f c, C-c f j, C-c f x, C-c f l, C-c f r, C-c f s, C-c f t, C-c f n) to instantly switch between predefined font scales from "colossal" to "nano."

A crucial hook ensures that whenever the font scale changes, the sss-set-base-faces function is called to meticulously adjust the size, color, and font family of a wide array of Emacs faces. This includes the default text, mode lines, window dividers, and specific elements within Markdown and Org mode, ensuring a consistent and aesthetically pleasing appearance regardless of the chosen scale.

For a richer visual experience, nerd-icons is enabled, bringing a vast collection of icons to Emacs. This is complemented by nerd-icons-completion, which integrates these icons into completion frameworks like marginalia and vertico, making command and file selection more intuitive.

spacious-padding, adds customizable padding around Emacs UI elements, such as internal borders, header lines, and fringes, creating a less cramped and more modern look.

The module also includes svg-lib, a library for SVG rendering and manipulation, and kind-icon, which integrates icons into corfu completion margins, further enhancing visual cues during interactive completion.

modusregel customizes the mode line format, integrating keycast-mode-line to display current commands and their keybindings directly in the mode line, while keycast itself is enabled globally to show this information.

To improve navigation, ultra-scroll is enabled, refining Emacs's scrolling behavior with advanced settings for smooth, controlled movement.


19. Nix profile

Nixpkgs contains a lot of software which we can leverage and manage from Guix.

SSS will automatically install and provide the Nix package manager for you.

SSS also provides some facilities to manage Nix from the comfort of your Guile Scheme.

You might need to activate and link the profile in order to be able to use, for the first time.

Assuming joe as user in question.

/nix/var/nix/profiles/per-user/ should be:

joe@guixvm ~ Ī»  ll /nix/var/nix/profiles/per-user/

drwxr-xr-x 2 joe  users  16K 29 dec 23:09 joe/
drwxr-xr-x 2 root root  4,0K 22 nov 13:23 root/

For this, make the directory an link it to your home.

sudo mkdir -p /nix/var/nix/profiles/per-user/joe
sudo chown -R joe:users /nix/var/nix/profiles/per-user/joe
ln -sfv /nix/var/nix/profiles/per-user/joe/profile $HOME/.nix-profile

It's possible you might need to logout and log back in to re-activate the profile.

You can switch your install to use nixpkgs-unstable with:

nix-channel --add https://nixos.org/channels/nixpkgs-unstable
nix-channel --update

You can install Nix packages by running:

nix -L profile install --impure nixpkgs#package-name

You can keep your Nix packages updated by running:

NIXPGS_ALLOW_UNFREE=1 nix profile upgrade --impure '.*'

The installed software will be available, for example at: $HOME/.nix-profile/bin/

SSS provides some scripts that allow you to maintain your Nix configuration and installed packages programatically with Lisp.

You can find these scripts and the list file at system/scripts in this repo and in the Makefile.

Installing all wanted Nix packages can be done with make npi for example and updating them with make npu.


20. Flatpaks

SSS takes care of flatpak origins and installing and maintaining your flatpaks up to date, all programatically and with Lisp.

You can find these scripts and the list file at system/scripts in this repo and in the Makefile.

Installing all wanted Flatpak packages can be done with make fpi for example and updating them with make fpu.


21. System audio

SSS favors modern technologies and thus makes use of Pipewire for all your GNU/Linux audio needs.

In practice this means that any user account in your system that wants to make use of audio, should have the (service home-dbus-service-type) and (service home-pipewire-service-type) services enabled for their account (yes per-user basis).

You will also want to set the RTC_USE_PIPEWIRE variable to true. This is already the case by default in SSS.


22. Wallpapers

SSS automatically loads at startup a matching wallpaper for the currently enabled theme.

This is currently done with custom scripts and swaybg. SSS automatically loads a random wallpaper (within the palette) every 10 minutes.

Pressing s-S b will select a random other wallpaper within the palette.


23. Firefox custom declarative configurations

I like to declaratively customize and configure my software, and my web browsers of course too.

With Firefox (from nonguix) I like to configure it in Lisp (Guile Scheme) code, generating user.js , userChrome.css and more, from Lisp code, to customize, harden and optimize it, all declaratively.

See src/sss/firefox.scm for more.

As for manual work needed for achieving Firefox Zen, we document several tips below:

23.1. Stick to SSS defaults when it comes to hardening

If you need more then just go for Tor.

23.2. Recommended extensions

23.2.1. TODO: declarative extension installation and configuration via Guile Scheme and Guix

uBlock Origin: Finally, an efficient wide-spectrum content blocker. Easy on CPU and memory.

Adaptive Tab Bar Color: Changes the color of Firefox theme to match the website’s appearance.

Search by Image: A powerful reverse image search tool, with support for various search engines, such as Google, Bing, Yandex, Baidu and TinEye.

Dark Reader: Dark mode for every website. Take care of your eyes, use dark theme for night and daily browsing.

Copy PlainText: Copy Plain Text without any formatting

1password: worth it if you have a license: The best way to experience 1Password in your browser. Easily sign in to sites, generate passwords, and store secure information, including logins, credit cards, notes, and more.

Emoji: It permits just with a single click to copy an emoji. There is a search-box and the "Most used emojis" section (the first one). If you want to send feedback or report bug, please contact me

Video DownloadHelper: Download videos from the web. Easy, smart, no tracking.

To Google Translate: Right-click a section of text and click the Translate icon next to it to text translate or listen to it in your language.

Privacy Badger: Automatically learns to block invisible trackers.

Web Archives: View archived and cached versions of web pages on various search engines, such as the Wayback Machine and Archive․is.

Download All Images: Easily save images with a wide range of customization features, such as file size, dimensions, and image type.

Language Tool: With this extension you can check text with the free style and grammar checker LanguageTool. It finds many errors that a simple spell checker cannot detect, like mixing up there/their, a/an, or repeating a word.

Weather Extension: The best way to see the weather right in your browser. Easier than looking outside!

User Agent Switcher and Manager: Spoof websites trying to gather information about your web navigation—like your browser type and operating system—to deliver distinct content you may not want.

Firefox Multi-Account Containers: Firefox Multi-Account Containers lets you keep parts of your online life separated into color-coded tabs. Cookies are separated by container, allowing you to use the web with multiple accounts and integrate Mozilla VPN for an extra layer of privacy.

24. Nyxt browser (experimental)

Nyxt is a fantastic web browser, infinitely extensible, and in Emacs-spirit. It is a great fit for SSS. I am currently experimenting with it, since it's not production-ready yet. I for now am content with Firefox for 99% of things and Chrome for work.

Find more about Nyxt here: https://nyxt.atlas.engineer/

Before you start Nyxt, you need to perform a one-time action so as to allow the SSS Nyxt config to work properly.

What we need is Quicklisp (refer to https://quicklisp.org for more details).

You only need to load quicklisp.lisp once to install Quicklisp.

Here's an example installation session on SBCL:

curl -O https://beta.quicklisp.org/quicklisp.lisp
sbcl --load quicklisp.lisp

You will then, if all went well, be inside a Common Lisp REPL. Here, all you need to do is type the following commands, each followed by ENTER:

(quicklisp-quickstart:install)
(quit)

You are then ready to start the Nyxt browser, all configuration should work well from then on.


25. Git

  1. TODO: make this more configurable.

    Joe's account is automatically configured with a multi-user Git setup. See src/sss/git.scm. Currently this works on a per-directory basis, and is configured by default to my preferred settings.

    My settings are:

    • $HOME/hacking is where I keep my personal development projects. These are uploaded to Codeberg, and use their own gitconfig, email address, default git message, GPG key, and SSH keys.
    • $HOME/work is where I keep my work projects. These are uploaded to Github, and use their own gitconfig, email address, default git message, GPG key, and SSH keys.

26. šŸ”„ Firewall

By default, the Supreme Sexp System (SSS) chooses the sane default firewall settings for a "desktop" or "laptop" computer.

This means rejecting any incoming network calls by default, only accepting ping requests and calls that originate from the machine itself (loopback device). This allows security, and developing software in the same machine as well (test local ports, expose services, etc.)

Adding SSH access or other network capabilities is done by tweaking the iptables of SSS (in Scheme code).


27. Disk space

Reproducibility and isolation of builds naturally leads to a little more disk usage than other systems. This is not a problem nowadays, with cheap storage.

That being said, here follow some useful reminders, every now and then clean:

  • Guix generations
  • Guix store
  • Nix store
  • Unused Steam games

You could run something like this:

sudo guix system delete-generations 1d
sudo guix gc
nix-store --gc

If you'd like to find the largest files in your disk, here’s an example command:

du -ah / | sort -rh | head -n 20

28. Bluetooth

The real best way to manage your bluetooth is using the bluetoothctl shell. That being said SSS comes with a GUI graphical interface to manage Bluetooth. You can also go low-level, and programatically connect to your devices, setup shortcuts for "favourite" connections, and much more with bluetoothctl.


29. Virtualization

SSS comes equipped with libvirt and libvirt-manager (the GUI).

I'd recommend for most cases to simply use the GUI to create a new NAT network, and have your VMs be able to connect to the Internet.

If you want two-way traffic, and your machine is connected wirelessly to the network, you won’t be able to use a true network bridge.

In this case, the next best option is to use a virtual bridge with static routing and to configure a libvirt-powered virtual machine to use it (via the virt-manager GUI for example).


30. Mime types

SSS supports specifying default applications to use for certain files, and also xdg-open, and customize allowed options, all in comfortable Scheme code.

Refer to the sss mime module at src/sss/ and the sss-mimeapps-list-file function to understand more how it works.

(define sss-mime-default-applications
  '((application/pdf org.gnome.Evince firefox)
    (text/html firefox emacsclient)))

The XDG MIME Applications specification builds upon the shared MIME database and desktop entries to provide default applications.

Added Associations indicates that the applications support opening that MIME type. For example: bar.desktop and baz.desktop can open JPEG images. This might affect the application list you see when right-clicking a file in a file browser.

Removed Associations indicates that the applications do not support that MIME type. For example, baz.desktop cannot open H.264 video.

Default Applications indicates that the applications should be the default choice for opening that MIME type. For example, JPEG images should be opened with foo.desktop. This implicitly adds an association between the application and the MIME type. If there are multiple applications, they are tried in order.

At ~/.config/mimeapps.list you get this:

[Default Applications]
application/pdf=evince.desktop;firefox.desktop
text/html=firefox.desktop;emacsclient.desktop

31. Troubleshooting FAQ

Q: I ran out of disk space, and have too much garbage in the system!

A: Check the Makefile of SSS and run a make full-gc followed by a make sr


Q: Grub install fails due to missing disk space / input-output error!

A: It's recommended to delete some old generations of the system (perhaps also a make full-gc) and to clean the dump file at: /sys/firmware/efi/efivars/dump*


Q: I have a strange error, where guix system reconfigure or guix home reconfigure fails, and some error about expected string ~`Derive String(['! This is also not consistently reproducible and happens in some machines, others not!

A: Sorry, your guix store is partially corrupted. There is some things you can do luckily. First of all backup your important data. Then try to identify the culprit, i.e. the file in the store which is being read and not successfully parsed.

You could first try to do a sudo guix gc --verify=repair,contents, but that may not help. If it does then great you are done! Otherwise try to find a way to disable the dependency on this in your config if possible. Proceed to delete all Guix home generations (except current), after which you should delete all system generations (except current) and do an intensive garbage collection (make full-gc).

You can optionally do a guix pull now to see if maybe a new version of things comes along and helps. In any case try to reconfigure (make jr / make sr) again and it should work, after which you can turn the "offender" back on.


Q: I am unable to generate a GPG key! I get errors about pin-item or pinentry!

A: Try with gpg --pinentry-mode loopback --full-gen-key. Otherwise try other options and check you have the right pinentry programs installed.


32. SSS project

Contributing to free software is a uniquely beautiful act because it embodies principles of generosity, collaboration, and empowerment.

We welcome everyone to feel invited to the SSS Project, and encourage active contribution in all forms, to improve it and/or suggest improvements, brainstorm with me, make it more modular/flexible, etc, feel free to contact me <jjbigorra@gmail.com> to chat, discuss or report feedback.

Find here the Backlog and Kanban boards for SSS: https://lucidplan.jointhefreeworld.org/tickets/sss


33. Postume: Inheriting an SSS/GNU system

While we may not like thinking about these situations, life has an expiry date for us all, and as such we should prepare for a day when we are no more.

Instructions are crucial in this case because the computer systems we posess might hold valuable or sentimental information.

Without guidance, it could be difficult to figure out how to access these computers, specially a somewhat niche setup like SSS.

Our loved ones can hopefully thanks to this section of the manual understand how to use the computer, retrieve important files, or preserve their work.

Firstly, get a hold of as many passwords as you can and account information, before turning on the device.

Proceed to turn on the device. If immediately a password prompt appears, this is likely a system-wide BIOS password, which you will need to unlock to even use the computer.

Choose the boot option for Guix/GNU/Linux if the choice is presented. If multiple options are shown, just press ENTER to choose the default option or use the arrow keys to move around the GRUB boot menu. If the machine struggles to boot, something like Universal Rescue Disk could come in handy.

Once you boot into SSS (Guix + GNU + Linux), you will see a fast succession of letters in a black screen, wait a bit until you see appear something like:

This is the GNU system! login:

At this point you should type the username of the session you want to log into (generally this is short and all lowercase letters), followed by ENTER.

Then you will get a password prompt. Type the password and press ENTER. Don't worry if you don't see any * characters for the password, your typing worked, this is just a security measure.

If the details were not correct, you will get prompted to login again.

If they were correct, then you will enter the user's shell, at which point you could type gui followed by ENTER to start a graphical user interface. If it doesn't work, try hyprland or labwc.

You should have then booted into a more familiar environment. If the user you logged into has the Hyprland session, the keyboard bindings are documented in sections above. You could for example use Super+/ to open the fuzzy application finder (Super is often the "Windows" or "command" key).

Good luck!


34. Window Manager keybindings

Find here the Hyprland keybindings. I usually use these bindings in other WMs too. Labwc session has a a more windows-like style of bindings.

34.1. General keybindings

keybind command
s-k Kill/Close a window or application
s-l Lock screen
s-1..9 Move focus to workspace 1..9
s-S-1..9 Move window to workspace 1..9
s-v Vertical splits
s-h Horizontal splits
s-S-SPC Toggle floating/tiling mode for window
   

34.2. Application keybindings

keybind command
s-/ Launch application fuzzy finder menu (Rofi)
s-i Open a Web Browser (Firefox)
s-S-i Open a bloated Web Browser (Chrome)
s-t Open a terminal emulator (Alacritty)
s-e Open text editor (Emacs GUI Client)
s-- Open password manager (1password)
s-b Open file manager (Nemo)

34.3. More keybindings

keybind command
s-S-. Copy screenshot of entire screen
s-. Save screenshot of entire screen
s-S-, Copy screenshot of selected area
s-, Save screenshot of selected area
s-S-b Set wallpaper to theme's default

35. Some relevant Emacs keybindings

35.1. General non-vanilla bindings

keybind command description
M-s r consult-ripgrep Grep (ripgrep) through project, with minibuffer completion
M-s o consult-occur find occurences in file

35.2. SSS specific keybindings

keybind command description
C-c # s sss-sys-reconfigure Perform a system rebuild
C-c # j sss-joe-reconfigure Perform a user (joe) rebuild
C-c # f sss-full-reconfigure Perform a system + user (joe) rebuild

35.3. More bindings

keybind command description
C-x C-f find-file Open a file.
C-x C-s save-buffer Save the current buffer.
C-x C-w write-file Save the current buffer to a different file.
C-x C-b list-buffers List open buffers.
C-g keyboard-quit Cancel the current command.
C-x k kill-buffer Kill (close) the current buffer.
C-x C-c save-buffers-kill-emacs Save all buffers and exit Emacs.
C-y yank Paste the most recently killed (cut or copied) text.
C-w kill-region Cut the selected region.
M-w kill-ring-save Copy the selected region.
C-k kill-line Cut the text from the cursor to the end of the line.
C-d delete-char Delete the character under the cursor.
C-a beginning-of-line Move the cursor to the beginning of the line.
C-e end-of-line Move the cursor to the end of the line.
C-p previous-line Move the cursor to the previous line.
C-n next-line Move the cursor to the next line.
C-f forward-char Move the cursor forward one character.
C-b backward-char Move the cursor backward one character.
M-f forward-word Move the cursor forward one word.
M-b backward-word Move the cursor backward one word.
C-v scroll-up-command Scroll the buffer up one screen.
M-v scroll-down-command Scroll the buffer down one screen.
C-s isearch-forward Incremental search forward.
C-r isearch-backward Incremental search backward.
M-x execute-extended-command Execute an extended command (by name).
C-h k describe-key Describe a key binding.
C-h f describe-function Describe a function.
C-h v describe-variable Describe a variable.
C-h m describe-mode Describe the current major mode.
C-h i info Open the Emacs Info manual.
C-x 2 split-window-below Split the current window horizontally.
C-x 3 split-window-right Split the current window vertically.
C-x 0 delete-window Delete the current window.
C-x 1 delete-other-windows Delete all other windows.
C-x o other-window Switch to the next window.
C-l recenter-top-bottom Recenter the current line in the window.
M-g g goto-line Go to a specific line number.
C-x u undo Undo the last change.
C-/ redo Redo the last undone change.
C-j newline Insert a newline.
TAB indent-for-tab-command Indent the current line (or region).
M-TAB completion-at-point Attempt completion at point.
C-t transpose-chars Transpose the characters around point.
M-t transpose-words Transpose the words around point.
C-x C-l downcase-region Convert the selected region to lowercase.
C-x C-u upcase-region Convert the selected region to uppercase.
M-u upcase-word Uppercase the word at point.
M-l downcase-word Lowercase the word at point.
M-c capitalize-word Capitalize the word at point.
C-x h mark-whole-buffer Select the entire buffer.
C-v scroll-down Scroll down in the buffer
M-v scroll-up Scroll up in the buffer

36. On Software engineering

36.1. Development environments, manifests and flakes

I would encourage that all your software projects have a reproducible build process, and preferably use Guix or Nix to declare a manifest.scm or flake.nix.

This way, and leveraging direnv and .envrc we can enter in our editor (Emacs, VSCode, IntelliJ…) in a reproducible build environment and dependencies.

36.1.1. Guile Scheme hacking

I can't think of a better setup than using Emacs to work with Lisp languages, with good paren matching, structural editing, sexp aware, smartparens, paredit if you like. Then you can use a nice REPL via Emacs, like Geiser, or as I do, Arei and Ares. I usually like to use watchexec as well for hot reloading.

36.1.2. Guix and manifests

Using Guix is fantastic , and for me it's my first choice to build software with:

(use-modules (guix packages)
             (gnu)
             ;;;
             ;;; ...
             ;;;
             (gnu packages autotools)
             ((guix licenses)
              #:prefix license:))

(define-public guile-uuid
  (let ((commit "64002d74025f577e1eeea7bc51218a2c7929631f")
        (revision "0"))
    (package
      (name "guile-uuid")
      (version (git-version "0.0.0" revision commit))
      (source
       (origin
         (method git-fetch)
         (uri (git-reference
               (url "https://codeberg.org/elb/guile-uuid.git")
               (commit commit)))
         (file-name (git-file-name name version))
         (sha256
          (base32 "1q6dqm2hzq75aa5mrrwgqdml864pdrxc98j7pyj1y0827phnzjfj"))))
      (build-system guile-build-system)
      (native-inputs (list guile-3.0
                           (specification->package "guile-gcrypt")))
      (home-page "https://codeberg.org/elb/guile-uuid")
      (synopsis
       "Guile-UUID is a UUID generation and manipulation module for GNU Guile.")
      (description
       "This package implements RFC 9562 UUIDs, and can generate versions 1 and 3–8 from that specification.
        It provides parsing for UUIDs in standard hex-and-dash format of any variant and version.
        It can also query the variant and version of UUIDs from the RFC.
        Simple routines for converting between binary and hex-and-dash string UUIDs are included.")
      (license license:gpl3+))))

(define-public guile-hygguile
  (let ((commit "4b9989caa65ebacf56c0e48df68f812daf254e71")
        (base32-sha-signature
         "1r5i9fcc4syf4p7xr1b7ml5v93pnkmxn2dy0m1qyvd6y2vbbhxjf")
        (revision "0"))
    (package
      (name "guile-hygguile")
      (version (git-version "0.0.0" revision commit))
      (source
       (origin
         (method git-fetch)
         (uri (git-reference
               (url "https://codeberg.org/jjba23/hygguile.git")
               (commit commit)))
         (file-name (git-file-name name version))
         (sha256
          (base32 base32-sha-signature))))
      (build-system guile-build-system)
      (native-inputs (list guile-3.0))
      (arguments
       (list
        #:source-directory "src"))
      (home-page "https://codeberg.org/jjba23/hygguile")
      (synopsis
       "SXML and TailwindCSS UI component library for Lisp (Guile Scheme) software projects")
      (description
       "Cozy and professional user-interfaces for everyone.
        SXML and TailwindCSS UI component library for Lisp (Guile Scheme) software projects.
        hygge + guile = hygguile")
      (license license:lgpl3+))))

(packages->manifest (list (specification->package "make")
                          (specification->package "gettext")
                          guile-next
                          guile-uuid
                          guile-ares-rs
                          artanis
                          guile-hygguile
                          guile-dbi
                          guile-dbd-sqlite3))

36.1.3. Nix and flakes

Using Nix (and flakes) allows one to quickly spin up and manage multiple reproducible development environments, as well as development shells.

Read more about Nix here: https://nixos.org/.

In a nutshell you get a "per project" isolated environment, allowing you to for example seamlessly switch between Scala versions for different projects.

You can search for packages (80k+) here: https://search.nixos.org/packages.

With this setup you don't need to install things globally, just on a per project level, allowing more flexibility and reproducibility.

See here how a simple Scala 2.13 development flake looks like.

  {
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    systems.url = "github:nix-systems/default";
  };
  outputs = { systems, nixpkgs, ... }:
    let
      eachSystem = f:
        nixpkgs.lib.genAttrs (import systems)
        (system: f nixpkgs.legacyPackages.${system});
    in {
      devShells = eachSystem (pkgs: {
        default = pkgs.mkShell {
          buildInputs = with pkgs; [
            scala_2_13
            jdk21
            metals
            sbt
            scalafmt
            scalafix
            scala-cli
            coursier
          ];
        };
      });
    };
}

In order to use this flake, you can use direnv: https://github.com/direnv/direnv and combine it with a .envrc to allow your editor to enter this isolated environment.

Assuming you place the Nix flake above at the root of a repo, at flake.nix, you can have a .envrc file with the contents:

use flake

You will then just do a one time direnv allow and now your editor will magically load the right env variables and tools from the environment.

37. Glossary

  • GNU/Linux: A free and open-source operating system combining the GNU system and the Linux kernel.
  • Lisp Machine: A type of computer optimized for running Lisp, a family of programming languages.
  • GNU Guix: A functional package management tool and standalone distribution of the GNU system.
  • REPL (Read Eval Print Loop): An interactive programming environment for evaluating code and seeing immediate results.
  • TTY (TeleTYpewriter): A text terminal for interacting with a computer system.
  • Scheme: A Lisp dialect often used for scripting in GNU Guix.
  • Wayland: A protocol for a display server, often used as a modern alternative to X11.
  • Hyprland: A Wayland compositor with great and smooth graphics.
  • PipeWire: A modern multimedia framework for managing audio and video streams.
  • Elpaca: A package manager for Emacs that supports advanced configuration options.
  • Libre: Free and open-source software that respects user freedom.

38. Acronyms

  • SSS: Supreme Sexp System
  • GNU: GNU's Not Unix
  • OS: Operating System
  • REPL: Read Eval Print Loop
  • TTY: TeleTYpewriter
  • X11: The X Window System
  • DBus: Desktop Bus (inter-process communication system)
  • RTC: Real-Time Communication

39. Acknowledgments

The SSS project has been inspired by countless free software projects and amazing people. Here follow some shoutouts and thank yous, in no particular order:

Inspiring Projects

GNU Emacs, GNU Guix, Arch Linux, Void Linux, Nix, NixOS, Hyprland, …

Inspiring People

  • Richard M. Stallman for starting and making the free software movement thrive
  • Ludovic CourtĆØs for his work on Guix and more
  • Andrew Tropin for his work on Guix and more, great videos, starting the RDE project
  • Derek Taylor (DT) for his great videos on free software and the GNU/Linux ecosystem
  • Mu Lei (NalaGinrut) for his great work on GNU Artanis and Scheme, and inspiring me to pursue my projects and power them with a Lispy flavor

Author: Josep Bigorra

Created: 2025-05-31 za 21:15

Validate