Getting started

Building Solium, running it, installing it, and a first configuration. The first three sections are the README’s; the last two are the start of Ricing Solium, which goes on from there.

Building

Solium needs Rust 1.88 or newer (edition 2024), a C++17 compiler, Qt 6.5 or newer (Qt Quick and Qml), and the development files for Wayland, libinput, libudev, libseat, xkbcommon, GBM, EGL and libdrm. Lua is compiled in and needs nothing installed. The build also runs Qt’s moc on the headers of Solium’s own QML types; QT_MOC names it when the build cannot find it, and dev/README.md says where it looks.

Rust is easiest from rustup; a distribution’s own Rust works too if it is new enough. The system packages:

Fedora

sudo dnf install gcc gcc-c++ pkgconf-pkg-config wayland-devel libinput-devel \
    systemd-devel libseat-devel libxkbcommon-devel mesa-libgbm-devel \
    mesa-libEGL-devel libdrm-devel qt6-qtbase-devel qt6-qtdeclarative-devel

Arch Linux

sudo pacman -S --needed base-devel wayland libinput systemd-libs seatd \
    libxkbcommon mesa libdrm qt6-base qt6-declarative

Debian 13 and Ubuntu 24.10 or newer (older releases ship a Qt older than 6.5)

sudo apt install build-essential pkg-config libwayland-dev libinput-dev \
    libudev-dev libseat-dev libxkbcommon-dev libgbm-dev libegl-dev libdrm-dev \
    qt6-base-dev qt6-declarative-dev

openSUSE Tumbleweed

sudo zypper install gcc-c++ pkgconf qt6-base-devel qt6-declarative-devel \
    'pkgconfig(wayland-server)' 'pkgconfig(libinput)' 'pkgconfig(libudev)' \
    'pkgconfig(libseat)' 'pkgconfig(xkbcommon)' 'pkgconfig(gbm)' 'pkgconfig(egl)' \
    'pkgconfig(libdrm)'

Then, from the checkout:

cargo build            # target/debug/solium; add --release for an optimised build

Or in a container, on Fedora without the development packages. The image has the C toolchain and the libraries, and your own rustup install is mounted into it. It is an image of Fedora, and what it builds links that release’s libraries, so build it for the release you run: FEDORA_VERSION (44 by default) is a build argument of dev/Containerfile. On any other distribution, install the packages above instead. A release whose Qt is older than 6.5 cannot run Solium at all; a pull request from one still gets every check except the GPU one from CI.

podman build -t solium-build:fc44 -f dev/Containerfile dev/
SOLIUM_GATE_IMAGE=localhost/solium-build:fc44 dev/gate.sh

dev/gate.sh builds and runs every check; dev/README.md has the plain podman run for a build on its own, and CONTRIBUTING.md has the rest of what a change needs.

Running it

From a free TTY (Ctrl+Alt+F3), and not from inside a running desktop session — --tty takes the screen and will fight whatever else has it:

cargo build
./target/debug/solium --tty

Nested, as a window inside an existing session, for development:

./target/debug/solium

Once installed (the Fedora package or dev/install.sh, below), the command is solium: from a text console run solium --tty, and solium --probe, which is safe inside a running desktop, first shows what the hardware offers.

Three flags worth knowing:

solium --help lists every flag and the variables that change a session, and a flag Solium does not know is refused rather than started with.

super+shift+q ends the session and super+shift+r reloads the configuration without ending it. The rest of the bindings come from --check, because they belong to a script rather than to the compositor, and Key bindings lists every one that ships.

On the hardware, anything that goes wrong is also written to ~/.local/state/solium/session.log, synchronously — that log exists for the case where the screen is gone and the power button is the only way out.

Install

On Fedora 44, either build a package of the checkout and install it with dnf, or install from the checkout into ~/.local. The login screen offers Solium after either. Use one: with both, it lists Solium twice.

A Fedora package, a development snapshot of the commit checked out:

podman build -t solium-build:fc44 -f dev/Containerfile dev/   # once
dev/rpm.sh                                                     # prints the dnf line
sudo dnf install ./target/rpm/RPMS/x86_64/solium-0.0.0~git*.rpm

dev/rpm.sh builds the release binary in the build container, packages it with this machine’s rpmbuild (sudo dnf install rpm-build), checks the package unpacked, and prints the dnf line. It installs under /usr, so there is no other step, and sudo dnf remove solium takes it out. It is built for Fedora 44: copy the .rpm to another Fedora 44 machine and install it the same way, with no Rust or build image there. Another release needs a package built for it. dev/README.md has the details.

From a checkout, on Fedora 44 (or a Fedora with the same Qt):

podman build -t solium-build:fc44 -f dev/Containerfile dev/   # once
dev/install.sh
sudo install -Dm644 ~/.local/share/solium/solium.desktop /usr/local/share/wayland-sessions/solium.desktop

dev/install.sh builds a release binary in the build container, copies it and the shipped QML and Lua into ~/.local (--prefix picks another place), runs the installed copy’s --check, and prints the sudo line above — the one step that needs root, which it leaves to you. Then log out and pick Solium from the session list.

Getting back. The login screen remembers the last session, so from then on it offers Solium first: pick Plasma to return. Inside Solium, Ctrl+Alt+Backspace ends the session whatever your configuration says (unless the screen is locked), and so does super+shift+q in the shipped configuration. Ctrl+Alt+F3 switches to a text console, where you can log in and read ~/.local/state/solium/session.log. Solium handles both chords itself, so neither helps if Solium itself hangs.

What it installs is a copy: rebuilding or checking out another branch does not change it, and running dev/install.sh again replaces it. When the login screen’s session file is from an older install, it says so, and the sudo line has to be run again. It refuses while a Solium session is running from it, and while ~/.local/share/solium is a link, which it would otherwise delete through.

The rest of the session. It also puts solium-session.target and solium-autostart.target in ~/.config/systemd/user, and lilium-portals.conf in ~/.config/xdg-desktop-portal. The session file starts solium-session, which starts Solium as the session: Solium tells systemd and D-Bus where its display is and starts those targets, which start graphical-session.target and XDG autostart, and they are stopped again when it ends, a crash included. A Solium that has stopped answering ends itself five seconds after logout asks it to (session.stop_timeout), so that it is cleaned up after too. One Solium session runs per user at a time. Portals, the programs in ~/.config/autostart, and user services written for a graphical session then find Solium. A file there that you have edited, or linked, is left alone. The portal file sends screen capture to xdg-desktop-portal-wlr, which Fedora packages separately (sudo dnf install xdg-desktop-portal-wlr). The Fedora package puts the units in /usr/lib/systemd/user and the portal file in /usr/share/xdg-desktop-portal instead, and recommends xdg-desktop-portal-wlr, so dnf installs it; it also recommends foot, so super+return always has a terminal to open. A polkit agent, a keyring, applets and other separate programs start through XDG autostart or a user unit with PartOf=graphical-session.target. docs/shell-boundary.md says how, with the one command that starts Fedora’s KDE polkit agent under Solium. session.systemd = false in your configuration turns all of it off.

To remove it, dev/install.sh --uninstall, then the sudo rm -f /usr/local/share/wayland-sessions/solium.desktop it prints. Your ~/.config/solium and the session log stay.

Still to come (#66): COPR, so that dnf installs and updates Solium without a checkout, and an Arch PKGBUILD. dev/README.md has the details.

The thirty-second version

Two files, and the difference matters. user.lua is settings: a table of what you want changed, merged over the defaults, and everything you do not mention keeps shipping. Bindings are settings too — there is a bindings section, so adding a key does not cost you the second file. init.lua is the entry point — writing one replaces the shipped configuration entirely, layouts and modes included, and is what you want only when you are rewriting the session rather than adjusting it.

Almost everything on this page is user.lua.

Write ~/.config/solium/user.lua with only what you want changed:

return {
    gap = 4,
    pane = "reactive",
    tiling = { split = 0.618 },
}

It is merged over the defaults, key by key, through nested tables — so tiling = { split = ... } keeps the animations underneath it. Lists are replaced whole, because a list of column widths with one entry changed is a different list, not a longer one.

Every setting is the list of everything you can put in there, one row per section, and the configuration reference explains each key. Both are made from config.lua, the file that sets the defaults, so they cannot drift from it. Key bindings is every key that ships, and what it does.

Three guides go deeper than the recipes below:

Where things live

~/.config is $XDG_CONFIG_HOME when that is set, and ~/.local/state is $XDG_STATE_HOME.

For the files you write, your directory is searched first in every case but your colours. A file you write shadows the one that ships, and everything you did not write still comes from the shipped set — including its later improvements. Your own Theme.qml does not shadow the shipped one yet: the shipped Solium module is found first (#88). Don’t edit the shipped files in place: an install replaces them, and user.lua does the same job without being overwritten.