SSS/GNU system - Manual & Documentation

Find the divine sayings, and the destined computer configurations, all my Guix, Scheme, SwayFX, 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 am currently working on the GNU operating system in order to create a secure libre Lisp workstation.

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.

Lisp user space is centered on accessible interfaces that are mostly text-based, and can be mostly used without a mouse, which makes it easier to use for people living with disabilities as well as power users.

All of the system can be inspected and most of it can be hacked live in a REPL, making it a pure expression of the libre software ethic, and an incredibly versatile tool for a skilled programmer.

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

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.

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

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

I write my documents in Org format from Emacs and export them for your convenience to several other formats. A usual release of the manual happens as follows:

• Edit the SSS manual
• Run C-c # m from Emacs, which runs lib/sss-manual.el, exporting the Org document to several other formats (LaTEX, PDF, HTML, Markdown, etc.)

SSS supports several user customizations, more specifically:

Several color palettes, inspired by the great `ef-themes` by Protesilaos Stavrou, including ef-bio, ef-cyprus and ef-dream.

Find Prot's themes here: https://github.com/protesilaos/ef-themes

It is REQUIRED to include a per-host.scm in the root of this project, which is excluded from Git, and will determine certain settings for your own machine. Find here a reference configuration with what is required.

  (use-modules (gnu)
               (gnu packages))

  ;; system language
  (define sss-lang "en_US")

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

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

  ;; caps to control enabled
  (define sss-keyboard-caps-to-ctrl
    #t)

  ;; system hostname
  (define sss-hostname "gnusystem")

  ;; disk partitioning
  (define sss-filesystems
    (list (file-system
           (device "/dev/nvme0n1p3")
           (mount-point "/")
           (type "ext4"))
          (file-system
           (device "/dev/nvme0n1p1")
           (mount-point "/boot/efi")
           (type "vfat"))))

  ;; packages that should only be installed in the current host
  ;; or (define sss-per-host-packages '())
  (define sss-per-host-packages '(
                                  ;; AMD non-free drivers
                                  "amd-microcode" "amdgpu-firmware"
                                  ;; Games
                                  "prismlauncher" "steam")
    )

  ;; location where you cloned SSS Git repository
  (define sss-clone-dir
    "$HOME/Ontwikkeling/Persoonlijk/sss")

  ;;
  ;; Define the active palette for all users accounts
  ;; You should reconfigure and ideally restart the system
  ;; for all changes to take effect
  ;;
  ;; Note: You could choose on a per-user basis to set a fixed palette
  ;; and not follow system wide, by just redefining this value
  ;;
  ;; Possible values are:
  ;;   - sss-palette-ef-bio
  ;;   - sss-palette-ef-cyprus
  ;;   - sss-palette-ef-dream
  ;;
  (define-public sss-active-palette
    'sss-palette-ef-dream)

  ;; Nix packages to install
(define-public sss-nixpkgs
  '("yaml-language-server" "bash-language-server"
    "monaspace"
    "jdt-language-server"
    "nil"
    "black"
    "pyright"
    "marksman"
    "_1password-gui"
    "_1password-cli"
    "stack"
    "sbt"
    "scala_2_13"
    "firefox"
    "thunderbird"
    "postman"
    "vscode-langservers-extracted"
    "nwg-look"
    "krew"
    "mermaid-cli"
    "jetbrains.idea-community"))

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.

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.

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#firefox

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.

Find the project management of SSS here

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.

Most of the times, Sway will have set the correct resolution and scale (fractional) for your device. This also happens automatically when plugging in/out external monitors.

You might want to customize things though, here follow some examples of commands I use daily for this:

# Set fractional scaling to 1.5x , perfect for my Framework laptop 13,5"
swaymsg -- output eDP-1 scale 1.5
# Set resolution to 4k and scale 2x
swaymsg -- output Virtual-1 mode --custom 3840x2160 scale 2
# Set resolution and refresh rate
swaymsg -- output HDMI-A-1 mode --custom 1680x1050@50
# 1080p
swaymsg -- output Virtual-1 mode --custom 1920x1080 scale 1

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

This uses swww and thus can load animated images as well and do fancy transitions. If you have bugs loading wallpaper at startup, try reloading the wallpaper with s-S-b.

TODO: allow more dynamics and often changing of wallpapers, also random wallpaper script (but within theme)

SSS is automatically configured with SSH setup, and multi-user Git setup.

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. This is a little more manual and low-level, but it will allow your to programatically connect to your devices, setup shortcuts for "favourite" connections, and much more.

# Run bluetoothctl in a shell
user@host $ bluetoothctl
#
# Waiting to connect to bluetoothd...[bluetooth]# Agent registered
# [bluetooth]# hci0 new_settings: powered bondable ssp br/edr le secure-conn cis-central cis-peripheral 
# [bluetooth]# [CHG] Controller C8:A3:E8:76:98:80 Pairable: yes
# [bluetooth]# AdvertisementMonitor path registered
# [bluetooth]#

#  help

# then turn your bluethooth on:
#  power on
#
# [bluetooth]# Changing power on succeeded

# scan for devices around you:
#  scan on
#
# [bluetooth]# SetDiscoveryFilter success
# [bluetooth]# Discovery started
# [bluetooth]# [CHG] Controller C8:A3:E8:76:98:80 Discovering: yes
# [bluetooth]# [NEW] Device 52:B7:C5:C2:54:3A 52-B7-C5-C2-54-3A
# [bluetooth]# [NEW] Device 4B:C8:1D:17:55:A6 4B-C8-1D-17-55-A6
# [bluetooth]# [NEW] Device 27:9F:3F:70:13:71 27-9F-3F-70-13-71
# [bluetooth]# [NEW] Device E3:FE:C8:39:99:36 Wahoo KICKR 6F8D

# pair C0:23:8D:57:73:CF 

# exit

• 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.
• Sway: A Wayland compositor compatible with i3-style window management.
• 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