The window manager decides where every window goes, and asks a compositor to put
it there. If it asked KWin directly, every test of its logic would have to boot
a virtual machine, so everything it needs from the desktop goes through one
trait, `Backend`: queries for windows, monitors, the focus and the pointer, and
commands to move, focus, raise, minimize and close a window and to put the
pointer somewhere. A real backend answers from a table that compositor events
keep up to date, so a query never waits for the compositor; a command returns
once it has been accepted, not once the client has acted.
`FakeBackend` is the other implementation: an in-memory desktop that does what
it is told, at once and exactly, and records every command so that a test can
assert on what the window manager asked for. A test can also do what a user does
without the window manager asking: move a window, close it, change the focus,
turn a window into a dialog. It is strict where KWin is (a command about a
window that is gone is an error) and clamps where a GTK4 client does (a minimum
size). `with_backend` overrides the process-wide backend for the current thread
only and puts the previous one back on drop, also on a panic, which is what
keeps one test's desktop out of the next.
The module is the first to have `#![deny(missing_docs)]`. The contract (what
must be implemented, that a backend is `Send + Sync`) is proved by two
`compile_fail` examples with their error codes, and the rules nothing checks are
listed as such.
docs/dev/ARCHITECTURE.md describes the trait, its roles and the layer that
enforces each rule, and docs/dev/DESIGN.md has the first decisions with their
reasons. Both grow with the code.
Configuration, commands and the layout code all speak in the same small types:
how a new window is added to a workspace, what happens to a window that crosses
a monitor boundary, which kind of window a border colour is for, how an
application is matched by what it calls itself. They are defined once, in
`core`, with the layout types re-exported next to them so that the rest of the
crate imports from one place.
The layouts themselves are `komorebi-layouts` from komorebi, a git dependency as
in komorebi for Mac, at f08aa55 (the tip of master when this was written). That
revision has the fix for resizing a tile by dragging its edge
(LGUG2Z/komorebi#1765) and the placement helpers this port uses, so nothing is
vendored. The crate pulls in serde_yaml, which has an advisory
(RUSTSEC-2024-0449, unmaintained unsafe-libyaml) for reading the Windows-only
custom layouts; nothing here calls it, and deny.toml says so where it ignores
the advisory.
The module also has what the rest is built from. `Ring` is a list with one
focused element, which monitors, workspaces and containers each keep their
children in; it has the unit tests and the example upstream's version never had.
`lockable_sequence` keeps locked containers at their positions when others are
inserted or removed around them. `core::pathext` resolves environment variables
in configured paths, and `core::config_generation` has the rules that match an
application, with tests for the two shapes a rule takes in JSON (an object, and
a list that must all match).
Types that belong to a feature come with the feature: the socket messages, the
placement rules and the animation styles are not here. The `impl_ring_elements`
macro waits for the first type that uses it.
Every module has a `//!` summary, and the README says what the library has.
`discover` asks the flake for the suites of each tier
(`legacyPackages.x86_64-linux.vmTiers`) and hands them to two matrices, so a new
directory under `nix/tests/vm/suites` is run without an edit to the workflow.
`vm-fast` runs the fast tier on every pull request, one machine per suite, as a
sandboxed `nix build` of the check. `vm-slow` runs on master, every week, and on
a pull request labeled `ci:vm-slow`; it builds the driver and runs it by hand,
outside the sandbox, so that the screenshots and journals of a failed run are
uploaded with `if: always()`.
A composite action installs nix with the store cached and, for the VM jobs,
frees disk space (a Plasma guest is a closure of about 10 GB), writes the udev
rule that makes /dev/kvm writable for the runner's user, checks it with `test
-w`, and adds `kvm` to nix's system features. KVM on hosted runners is
documented for public repositories only. Whether this private repository has it
is not known: the first run of these jobs says, and if it does not, they need a
different runner.
`lint` no longer runs `nix flake check`: on Linux that now boots every VM suite,
which a runner with no KVM cannot do. It builds the checks that need no virtual
machine, and `vm-lib`, the library's own tests.
CONTRIBUTING.md and docs/dev/vm-tests.md say what runs where.
A virtual KWin has no output to draw on, so every test about pixels, and later
about the pointer, needs a real session. The `session` node is the headless node
plus a login: plasma-login-manager logs the test user in by itself, the way
nixpkgs' own `plasma6` test does, and Plasma draws on the machine's display. The
choice of login manager is made in `nodes/session.nix` and nowhere else, and the
file says how to switch to sddm.
The node adds no display device. The test driver gives every aarch64 guest one
virtio-gpu and takes screenshots of it; a second device is a second KWin output
that screenshots never show, which is what a first attempt did (a blank 1280x800
console).
`Kde.session` attaches to the session once the desktop is up: the shell is
running, the user manager knows the Wayland display, and the splash screen has
gone. The display is read from the user manager because plasma-login-manager's
greeter has its own KWin and takes `wayland-0`, and the user's session gets
`wayland-1`. The splash condition is there because KSplash has over a thousand
colors on it, so a "not blank" check passed on the splash screen. NixOS wraps
programs, which is why processes are found by their command lines: `pgrep -x
plasmashell` never matches `.plasmashell-wrapped`, and an exact match for the
splash would have passed because nothing matched. `Kde.shot` returns a
screenshot as a Pillow image.
`vm-render-smoke` is the first slow suite: it starts a session, opens a
terminal, and checks the middle of the window is dark and that the desktop
behind it has thousands of colors. On aarch64 under HVF five runs gave the same
screenshot, with the desktop up after 34 seconds. docs/dev/vm-tests.md describes
the node and the two traps.
The unit tests run against a fake desktop and cannot say whether KWin does what
the daemon asks. This adds the other half: NixOS machines with Plasma in them, a
real KWin, and a Python library to drive it.
Every directory under `nix/tests/vm/suites` is a test. The generator lists the
directory, so a new suite appears as `checks.<system>.vm-NAME` on Linux and as
`legacyPackages.<system>.vm.NAME` everywhere, with no edit to the flake. A suite
names its tier and its node and has a `test.py`;
`legacyPackages.<system>.vmTiers` lists the names of each tier as JSON for the
CI matrix, `vmGuests` the guests to build on a Linux builder, and `vmTcg` the
same suites for a machine with no KVM. `scale` multiplies every wait: 1 for KVM,
1.5 for HVF, 8 for TCG.
The headless node runs `kwin_wayland --virtual` as user units of a lingering
user, one pair of units per session (`session-bus@NAME`, `kwin-virtual@NAME`),
so a test can run several sessions with their own bus and socket. A virtual KWin
has no output to draw on, so anything that needs pixels or a pointer needs the
session node.
The library, `komorebi_vm`, has `Checks` (counted checks that fail once, at the
end) and `Kde` (start a session, run clients and tools inside it, read windows
through kdotool, poll with `wait_for`). It depends on a small `Machine` protocol
rather than on the test driver. The `vm-lib` check runs its unit tests against a
fake machine, with ruff and ty. The driver type checks each `test.py` with ty,
which is how a protocol that did not match `QemuMachine.execute` was caught.
`vm-kwin` starts a KWin with two outputs, spawns a foot window, reads it back,
starts a second session and checks that it cannot see the first.
On a Mac the guest is built on a Linux builder and the driver run directly,
because the macOS nix sandbox cannot give QEMU the hypervisor: `scripts/vm-mac`,
`just vm NAME`. docs/dev/vm-tests.md covers this, adding a test, and the
builder.
`ci.yaml` runs two jobs on GitHub-hosted runners, gated on the repository name
so that forks do not run them. `cargo-deny` checks licenses, advisories and
sources. `lint` runs `nix flake check`, which builds every check of the flake,
and the repository's own macro rules from the justfile. The triggers are the
ones komorebi for Mac uses: pull requests, pushes to master, feature and hotfix
branches, version tags, a weekly schedule and a manual run. The Nix store is
cached with cache-nix-action, which needs no account.
komorebi follows the tip of nixpkgs-unstable, so `flake.lock` moves, and KWin
with it. `update-flake-lock.yaml` opens a pull request each week with the title
`chore(deps): flake.lock: Update`; the same jobs run on it, which is what says
whether the new KWin still works.
Dependabot keeps the actions and the crates up to date, and the pull request
template carries over from komorebi for Mac. CONTRIBUTING.md describes what CI
runs.
The flake builds the workspace with crane and checks it the way `just check`
does, so that CI and a laptop run the same things: `komorebi-workspace-fmt`
(nightly rustfmt, since rustfmt.toml uses unstable options), `-clippy` with
warnings denied, `-doc` with rustdoc warnings denied, `-toml-fmt`, `-deny` and
`-nextest`. Treefmt and a pre-commit hook format Rust, Nix, TOML and the
justfile. `nix develop` gives a toolchain with the nightly rustfmt, cargo-deny,
nextest and udeps.
Linux is where komorebi runs, so only Linux gets packages and the overlay. An
Apple silicon Mac gets the dev shell, the formatter and the checks; the tests
there run against the fake desktop that arrives with the backend trait.
x86_64-darwin is left out because nixpkgs 26.11 dropped it, and the flake
follows the tip of nixpkgs-unstable.
The commit hash is a constant (`nix-check`) for the dependencies and for every
check, and the real one only goes into the final build. The version crate reads
it with `env!`, so putting it in the shared arguments would rebuild the
dependencies and rerun every check for each commit.
The README and CONTRIBUTING.md describe `nix develop` and `nix flake check`.
komorebi for KDE is built up as a Cargo workspace with one crate per concern,
the way komorebi and komorebi for Mac are. The first two crates are the
`komorebi` daemon, which does nothing yet but report its version, and `version`,
which owns the string every binary of the workspace reports.
`version` reads the commit from git when HEAD is on a branch, and from
COMMIT_HASH otherwise. A jj workspace leaves HEAD detached, so
`.cargo/config.toml` defaults the variable to `unknown` (nix will set the real
commit), and a plain `cargo build` in a jj checkout compiles.
The tooling files come from komorebi for Mac: the licence, deny.toml (trimmed to
the licences in use), rustfmt.toml and the toolchain file. `just check` runs the
formatting check, clippy and rustdoc with warnings denied, and the tests.
rustfmt.toml uses an unstable option, so formatting needs a nightly rustfmt. The
`rg` calls in `just lint` name a path because rg reads stdin when it is given
none and stdin is not a terminal.
The README and CONTRIBUTING.md say how to run, check and commit.