build(nix): the KWin version the module supports

komorebi relies on the per-output virtual desktops of KWin 6.8, and the
repository follows the tip of nixpkgs-unstable, so a system can have a KWin that
is too old, or one that no VM suite has run against yet.

nix/supported-kwin.nix records both ends: min, the oldest KWin komorebi
supports, and testedMax, the newest one every VM suite has passed against
(6.8.1, with nixpkgs d3b13ad). It is a plain attribute set, so a CI job can read
it with `nix eval --file`. The module asserts that pkgs.kdePackages.kwin is min
or newer, and warns when it is newer than testedMax;
services.komorebi.kwin.untestedIsError makes that an error.

nixos-module-eval gives the system a KWin of a version of its own, so that no
check depends on the KWin of the lock, which moves with the tip, and checks the
assertion, the warning and the option in ten more checks. CONTRIBUTING.md,
PLATFORM.md and vm-tests.md say how testedMax is raised: by a commit, once every
suite has passed against the newer KWin, that says which suites ran.
This commit is contained in:
LGUG2Z committed 2026-10-28 07:39:49 -07:00
1 parent bab8f35234
commit 04aa311f2e
10 files changed
+226 -10

No files matched your search

+11
View File
@@ -87,6 +87,17 @@ fixture corpus with `nix/tests/keybindings.expected`: write the file again with
the loop in `nix/tests/keybindings.nix`, and read the difference before
committing it.
[`nix/supported-kwin.nix`](nix/supported-kwin.nix) has the oldest KWin komorebi
supports, `min`, and the newest one every VM suite has passed against,
`testedMax`, which the module checks a system's KWin against. `testedMax` is
raised by hand, once every suite has passed against a newer KWin: in the weekly
canary job, or on a branch whose `flake.lock` has it. The commit changes
`testedMax` and the dated comment above it (the date, the nixpkgs revision and
the KWin), and its message says which run that was and which suites ran.
`nix eval --raw --file nix/supported-kwin.nix testedMax` reads it without the
flake. `min` changes with the code, in the commit that starts to use something an
older KWin does not have.
## VM tests
A change that needs a real KWin to be checked comes with a VM test, next to
+2 -1
View File
@@ -27,7 +27,8 @@ cargo run --bin komorebi --locked -- --fake-backend
Inside a Plasma Wayland session, `komorebi` loads a script into KWin, reads the
monitors and the windows that are open, tiles them, and tiles the windows again
whenever one opens, closes, takes the focus, is minimized or comes back, until
it is stopped with Ctrl-C. It needs KWin 6.8 or newer;
it is stopped with Ctrl-C. It needs KWin 6.8 or newer, which the NixOS module
checks against [`nix/supported-kwin.nix`](nix/supported-kwin.nix);
[`docs/dev/PLATFORM.md`](docs/dev/PLATFORM.md) has what it expects of the
session. Outside a Plasma session it exits with an error that says what is
missing. `--fake-backend` runs the window manager against an in-memory desktop
+13 -5
View File
@@ -1178,10 +1178,10 @@ The flake exports one module under two names, `nixosModules.default` and
`effects.borders.package` (by default `pkgs.kde-rounded-corners-komorebi`, from the overlay),
`effects.animation.enable` and `effects.animation.package`
(`pkgs.kwin-effect-geometry-change-komorebi`), `keybindings` (`format`, `text` or `file`, `mode`,
`chordTimeout`, `layout`, `strict`, `appAliases`), and `execStart`, which is read-only: the module
sets it to `bin/komorebi` of the package with `--log-level`, `--config` with a `komorebi.json`
when `configFile` or `config` is set, and `--keybindings` and the options of the engine when there
are key bindings. `config` is typed from
`chordTimeout`, `layout`, `strict`, `appAliases`), `kwin.untestedIsError`, and `execStart`, which is
read-only: the module sets it to `bin/komorebi` of the package with `--log-level`, `--config` with a
`komorebi.json` when `configFile` or `config` is set, and `--keybindings` and the options of the
engine when there are key bindings. `config` is typed from
`nix/komorebi-options.nix`, the options `schemars-nixgen` makes from the schema of `komorebi.json`;
the module writes it as JSON, with no null in it, and `configFile` and the written file both go
through `check-jsonschema` against `schema.json` when the system is built (comment lines taken out
@@ -1208,7 +1208,10 @@ With `services.komorebi.enable`, the module:
`share/kglobalaccel/*.desktop` (the static shortcuts) it installs in the system profile, with
the diagnostics in its `diagnostics.txt` and in the build log; and passes the file (a store
path), its format and mode, the chord timeout and the aliases to the daemon in `execStart`,
so that the daemon plans the file as the build did and runs the rest.
so that the daemon plans the file as the build did and runs the rest;
- checks the system's KWin, `pkgs.kdePackages.kwin.version`, against
[`supported-kwin.nix`]: it asserts that it is `min` or newer, and warns when it is newer than
`testedMax`, or asserts that it is not when `kwin.untestedIsError` is set.
The VM tests run on machines built with it ([vm-tests.md](vm-tests.md)). Their headless node
runs the daemon in test sessions, with a template unit, `komorebi@NAME`, that runs the module's
@@ -1218,6 +1221,9 @@ module's unit.
| Rule | Enforced by | Proof | Escape hatch |
|---|---|---|---|
| komorebi is enabled only on a machine with Plasma 6 | evaluation error: an assertion of the module | `nixos-module-eval` ("without Plasma 6, an assertion fails") | none |
| komorebi is enabled only with a KWin it supports, `min` of [`supported-kwin.nix`] or newer | evaluation error: an assertion of the module | `nixos-module-eval` ("a KWin older than min fails an assertion", "with a KWin older than min, the system does not evaluate") | none |
| A KWin newer than any every VM suite has passed against is reported | a warning of the module, at evaluation; an assertion with `kwin.untestedIsError` | `nixos-module-eval` ("a KWin newer than testedMax is a warning", "with untestedIsError, a KWin newer than testedMax fails an assertion") | `kwin.untestedIsError = false`, the default |
| `testedMax` is a KWin every VM suite has passed against | convention: a commit raises it after a run of every suite, and says which | none | none |
| The log level is one the daemon accepts | evaluation error: `logLevel` is an enum of the daemon's `--log-level` values | `nixos-module-eval` ("a log level the daemon does not have does not evaluate") | none |
| The unit runs `execStart`, and nothing but the module sets it | evaluation error: the option is read-only | `nixos-module-eval` ("execStart cannot be set", "the unit runs execStart") | a unit of your own |
| The daemon is configured by `configFile` when it is set, else by `config` | framework path: `execStart` passes the checked file as `--config`, which comes before the config home | `nixos-module-eval` ("configFile reaches execStart and the unit as --config", "config reaches execStart ..."), `vm-module` | none: with neither the daemon reads the file of the config home |
@@ -1958,11 +1964,13 @@ plan needs no engine. A failure to start is logged, and the window manager runs
[`nix/tests/vm/keys-corpus.py`](../../nix/tests/vm/keys-corpus.py), the corpus case `vm`
pressed in the three formats on a machine the module configured.
- [`nix/nixos-module.nix`](../../nix/nixos-module.nix): the NixOS module;
[`nix/supported-kwin.nix`](../../nix/supported-kwin.nix), the KWin versions it checks;
[`nix/tests/nixos-module.nix`](../../nix/tests/nixos-module.nix), its scenarios, evaluated in
real NixOS systems; and [`nix/tests/vm/suites/module`](../../nix/tests/vm/suites/module/test.py),
a Plasma session in which the module's unit runs the daemon.
[`nixos-module.nix`]: ../../nix/nixos-module.nix
[`supported-kwin.nix`]: ../../nix/supported-kwin.nix
[`StaticConfig`]: ../../komorebi/src/static_config.rs
[`StaticConfig::preload`]: ../../komorebi/src/static_config.rs
[`StaticConfig::postload`]: ../../komorebi/src/static_config.rs
+16
View File
@@ -793,3 +793,19 @@ lock every week runs the slow tier only when it is labeled. The canary job build
check, both VM tiers included, against the tip every week, without changing the repository,
and opens an issue when one fails, so that a break is known before the lock moves to it. A
break is fixed in a commit of its own rather than by pinning nixpkgs back.
## Why does the module check the version of KWin?
KWin 6.8 is the oldest KWin komorebi supports, because komorebi relies on the per-output virtual
desktops it introduced: the bridge reads the work area of each output for the desktop that output
shows. A NixOS system with an older KWin fails at evaluation, with a message that names both
versions.
The repository develops against the tip of nixpkgs-unstable, a weekly workflow moves
`flake.lock` to the tip, and a user's own nixpkgs can be newer still, so a system can have a
KWin that no VM suite has run against. Next to the floor,
[`nix/supported-kwin.nix`](../../nix/supported-kwin.nix) records `testedMax`, the newest KWin
every suite has passed against, and the module warns above it.
`services.komorebi.kwin.untestedIsError` turns the warning into an error. The two versions are
written down in that one file, which the module imports and anything else can read with `nix
eval`.
+13
View File
@@ -83,6 +83,19 @@ komorebi's use of them in a headless KWin:
lists it depends on the task manager's setting for showing the windows of the current desktop
only; the VM tests have no panel, so this is not measured.
[`nix/supported-kwin.nix`](../../nix/supported-kwin.nix) records both ends: `min`, the oldest
KWin komorebi supports (6.8), and `testedMax`, the newest KWin every VM suite has passed against
(6.8.1, with nixpkgs-unstable `d3b13ad`). The NixOS module reads the file. A system whose KWin
is older than `min` does not evaluate; one whose KWin is newer than `testedMax` builds with a
warning, unless `services.komorebi.kwin.untestedIsError` is set, which makes it an error. Outside
NixOS nothing checks the version.
The repository follows the tip of nixpkgs-unstable, so a newer KWin reaches it with a
`flake.lock` update or shows up first in the weekly canary job, which builds every check and runs
every VM suite against the tip. Once every suite has passed against a newer KWin, a commit raises
`testedMax` to it, with the date and the nixpkgs revision in the file's comment, and says in its
message which run it was and which suites ran ([CONTRIBUTING.md](../../CONTRIBUTING.md#the-nixos-module)).
### Wayland
komorebi runs in a Plasma Wayland session. There is no X11 session of Plasma 6.8 to run it in.
+7
View File
@@ -34,6 +34,13 @@ it.
TCG is software emulation. It is slow enough that only short suites are worth
running that way, and the library's `scale` argument (below) is 8 for it.
The suites are what `testedMax` in
[`nix/supported-kwin.nix`](../../nix/supported-kwin.nix) means: the newest KWin
every suite has passed against. When the weekly canary job, which runs every
suite against the tip of nixpkgs-unstable, passes with a newer KWin, a commit
raises `testedMax` to it and says which suites ran
([CONTRIBUTING.md](../../CONTRIBUTING.md#the-nixos-module)).
Each suite is a directory under
[`nix/tests/vm/suites`](../../nix/tests/vm/suites). The generator in
[`nix/tests/vm/default.nix`](../../nix/tests/vm/default.nix) lists that
+5
View File
@@ -72,6 +72,10 @@ the repository's `rust-toolchain.toml` selects, whatever nixpkgs your system use
killed could not, and KDE would keep them, doing nothing, until the next start.
- Without `services.desktopManager.plasma6.enable`, the configuration does not evaluate: an
assertion of the module fails, and its message names the option to set.
- It checks the KWin of your nixpkgs (`pkgs.kdePackages.kwin`) against the versions in the
repository's [`nix/supported-kwin.nix`](../nix/supported-kwin.nix). A KWin older than 6.8 is an
error. A KWin newer than the newest one komorebi has been tested with is a warning when you build
the system, or an error with `services.komorebi.kwin.untestedIsError`.
### Options
@@ -95,6 +99,7 @@ the repository's `rust-toolchain.toml` selects, whatever nixpkgs your system use
| `services.komorebi.keybindings.layout` | `"us"` | The keyboard layout of positional key names; `"us"` is the only one. |
| `services.komorebi.keybindings.strict` | `false` | Fail the build when something in the key bindings is not realized as its own hotkey daemon realizes it. |
| `services.komorebi.keybindings.appAliases` | `{ }` | Other names of an application, for the bindings that are for one application. |
| `services.komorebi.kwin.untestedIsError` | `false` | Makes a KWin newer than the newest one komorebi has been tested with an error instead of a warning. |
[Key bindings](usage/keybindings.md) explains the key binding options.
+36 -1
View File
@@ -124,6 +124,11 @@ let
"--app-alias"
(lib.escapeShellArg "${name}=${lib.concatStringsSep "," kb.appAliases.${name}}")
]) (lib.attrNames kb.appAliases);
# the KWin versions komorebi supports, and the KWin of this system
supportedKwin = import ./supported-kwin.nix;
kwinVersion = pkgs.kdePackages.kwin.version;
kwinUntested = lib.versionOlder supportedKwin.testedMax kwinVersion;
in
{
options.services.komorebi = {
@@ -420,6 +425,16 @@ in
'';
};
};
kwin.untestedIsError = lib.mkOption {
type = lib.types.bool;
default = false;
description = ''
Refuse a KWin newer than the newest one komorebi has been tested with (`testedMax` in
the repository's `nix/supported-kwin.nix`), instead of warning about it. A KWin older than
the oldest one komorebi supports (`min`) is refused either way.
'';
};
};
config = lib.mkMerge [
@@ -475,6 +490,21 @@ in
which would not be in the store; put its bindings in this one.
'';
}
{
assertion = lib.versionAtLeast kwinVersion supportedKwin.min;
message = ''
services.komorebi needs KWin ${supportedKwin.min} or newer, and pkgs.kdePackages.kwin is
${kwinVersion}. Use a nixpkgs with Plasma ${supportedKwin.min} or newer.
'';
}
{
assertion = !(cfg.kwin.untestedIsError && kwinUntested);
message = ''
pkgs.kdePackages.kwin is ${kwinVersion}, and komorebi has been tested with KWin
${supportedKwin.testedMax} and older. services.komorebi.kwin.untestedIsError is true, so
this is an error; set it to false to build the system with a warning instead.
'';
}
];
warnings =
@@ -492,7 +522,12 @@ in
&& (cfg.config.border or null) == true
&& !cfg.effects.borders.enable
)
"services.komorebi.config sets border to true, but services.komorebi.effects.borders.enable is false: without the effect, komorebi draws no border.";
"services.komorebi.config sets border to true, but services.komorebi.effects.borders.enable is false: without the effect, komorebi draws no border."
++ lib.optional (kwinUntested && !cfg.kwin.untestedIsError) ''
pkgs.kdePackages.kwin is ${kwinVersion}, and komorebi has been tested with KWin
${supportedKwin.testedMax} and older. Set services.komorebi.kwin.untestedIsError = true
to make this an error.
'';
environment.systemPackages = [
cfg.package
+15
View File
@@ -0,0 +1,15 @@
# The versions of KWin komorebi supports. The NixOS module checks the KWin of a system against
# them (nix/nixos-module.nix). The file is a plain attribute set, so a script or a CI job can
# read it without the flake:
#
# nix eval --raw --file nix/supported-kwin.nix testedMax
{
# The oldest KWin komorebi runs on. The bridge reads the work area of each output for the
# virtual desktop that output shows, which needs the per-output virtual desktops of KWin 6.8.
min = "6.8";
# The newest KWin that every VM suite has passed against. A commit that raises it says which
# suites ran, and against which nixpkgs (CONTRIBUTING.md).
# 2026-10-27: every VM suite, nixpkgs-unstable d3b13ad (2026-10-24), KWin 6.8.1.
testedMax = "6.8.1";
}
+108 -3
View File
@@ -1,8 +1,8 @@
# `nixos-module-eval`: `services.komorebi` in real NixOS systems, evaluated and never built. Each
# scenario is a `nixosSystem` with the module, and the checks read what it evaluates to: the
# assertions, the unit the module defines, and its read-only `execStart`. A scenario that must
# not evaluate is caught with `builtins.tryEval`. Nothing here builds a Linux package (the
# derivation below gets only check names and booleans), so a Mac runs it too.
# assertions and warnings, the unit the module defines, and its read-only `execStart`. A scenario
# that must not evaluate is caught with `builtins.tryEval`. Nothing here builds a Linux package
# (the derivation below gets only check names and booleans), so a Mac runs it too.
{
pkgs,
# nixpkgs' `lib.nixosSystem`
@@ -397,7 +397,57 @@ let
installed = config: map (p: p.name) config.environment.systemPackages;
supportedKwin = import ../supported-kwin.nix;
# The scenarios above have the KWin of the flake's nixpkgs, which the weekly canary moves to the
# tip of nixpkgs-unstable, so no check depends on its version. These give the system a KWin of
# a version of their own: nothing is built, so the package keeps its store path and only the
# version the module reads changes.
kwinAt = version: {
nixpkgs.overlays = [
(_: prev: {
kdePackages = prev.kdePackages // {
kwin = prev.kdePackages.kwin // {
inherit version;
};
};
})
];
};
withKwin =
version: settings:
eval {
imports = [
plasma
(kwinAt version)
];
services.komorebi = {
enable = true;
}
// settings;
};
# a KWin of Plasma 6.7, and one of the next major version after the newest one tested
olderKwin = "6.7.5";
newerKwin = "${toString (lib.toInt (lib.versions.major supportedKwin.testedMax) + 1)}.0";
kwinTooOld = withKwin olderKwin { };
kwinAtMin = withKwin supportedKwin.min { };
kwinTested = withKwin supportedKwin.testedMax { };
kwinNewer = withKwin newerKwin { };
kwinNewerIsError = withKwin newerKwin { kwin.untestedIsError = true; };
kwinTestedIsError = withKwin supportedKwin.testedMax { kwin.untestedIsError = true; };
kwinTooOldDisabled = eval {
imports = [
plasma
(kwinAt olderKwin)
];
};
failed = config: map (a: a.message) (lib.filter (a: !a.assertion) config.assertions);
# the module's warnings, and not those other modules may have
kwinWarnings = config: lib.filter (lib.hasInfix "untestedIsError") config.warnings;
unit = config: config.systemd.user.services.komorebi;
evaluates = value: (builtins.tryEval value).success;
@@ -750,6 +800,61 @@ let
}).services.komorebi.keybindings.layout
);
}
{
name = "untestedIsError is false by default";
ok = enabled.services.komorebi.kwin.untestedIsError == false;
}
{
name = "a KWin older than min fails an assertion that names min and the version";
ok = lib.any (
message: lib.hasInfix "KWin ${supportedKwin.min} or newer" message && lib.hasInfix olderKwin message
) (failed kwinTooOld);
got = failed kwinTooOld;
}
{
name = "with a KWin older than min, the system does not evaluate";
ok = !(evaluates kwinTooOld.system.build.toplevel.drvPath);
}
{
name = "with the KWin of min, the system evaluates";
ok = evaluates kwinAtMin.system.build.toplevel.drvPath;
}
{
name = "the KWin of min is supported, with no warning";
ok = failed kwinAtMin == [ ] && kwinWarnings kwinAtMin == [ ];
got = failed kwinAtMin ++ kwinWarnings kwinAtMin;
}
{
name = "the KWin of testedMax is supported, with no warning";
ok = failed kwinTested == [ ] && kwinWarnings kwinTested == [ ];
got = failed kwinTested ++ kwinWarnings kwinTested;
}
{
name = "a KWin newer than testedMax is a warning that names it and testedMax";
ok =
failed kwinNewer == [ ]
&& lib.any (
warning: lib.hasInfix newerKwin warning && lib.hasInfix supportedKwin.testedMax warning
) (kwinWarnings kwinNewer);
got = failed kwinNewer ++ kwinWarnings kwinNewer;
}
{
name = "with untestedIsError, a KWin newer than testedMax fails an assertion, with no warning";
ok =
lib.any (lib.hasInfix "untestedIsError is true") (failed kwinNewerIsError)
&& kwinWarnings kwinNewerIsError == [ ];
got = failed kwinNewerIsError ++ kwinWarnings kwinNewerIsError;
}
{
name = "with untestedIsError, the KWin of testedMax is supported";
ok = failed kwinTestedIsError == [ ];
got = failed kwinTestedIsError;
}
{
name = "disabled, a KWin older than min is not refused";
ok = failed kwinTooOldDisabled == [ ] && kwinWarnings kwinTooOldDisabled == [ ];
got = failed kwinTooOldDisabled;
}
];
failures = lib.filter (check: !check.ok) checks;