SSS/GNU system - Manual & Documentation

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

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.

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.

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/.

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.

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

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

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

If you know what you are doing, and want to use certain code from SSS as a library, feel free to do so, and import it as a Guix channel.

(cons*
(channel
 (name 'sss)
 (url "https://codeberg.org/jjba23/sss.git")
 (branch "trunk")
 (introduction
  (make-channel-introduction "914dc7ff51fd7c66f1ecc574b40ad1481731b936"
                             (openpgp-fingerprint
                              "83BC 6E1C 8726 B8C2 97F8 D16E 24F4 6738 CE11 4AF6"))))
 %default-channels)

Then once you have done a guix pull you will be all set.

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.

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

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.

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.

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.

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.

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.

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

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:

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.

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.

Bear in mind you might need to use Flatseal in order to grant additional permissions to some of your Flatpak packages.

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.

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.

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:

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, and install it as Flatpak. I am trying to use it more often day-to-day, in combination with Firefox, and I am forced to use Chrome for some work aspects.

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

Here's an example installation session on SBCL:

cd ~ && 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)

Then you can remove quicklisp.lisp as it will already be installed to ~/quicklisp/setup.lisp.

You are then ready to start the Nyxt browser, all configuration should work well from then on. Nyxt should be in the application launcher. If installed via flatpak, you can run it with flatpak run engineer.atlas.Nyxt

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

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

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.

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

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

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.

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

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!

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.

• 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.

• 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

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