diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 95afe818..11d3f3d1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/README.md b/README.md index 9ae77d8e..e33bf031 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/dev/ARCHITECTURE.md b/docs/dev/ARCHITECTURE.md index 12e9a991..534350d4 100644 --- a/docs/dev/ARCHITECTURE.md +++ b/docs/dev/ARCHITECTURE.md @@ -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 diff --git a/docs/dev/DESIGN.md b/docs/dev/DESIGN.md index 306566d5..769a9b4d 100644 --- a/docs/dev/DESIGN.md +++ b/docs/dev/DESIGN.md @@ -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`. diff --git a/docs/dev/PLATFORM.md b/docs/dev/PLATFORM.md index c84c64ed..90561500 100644 --- a/docs/dev/PLATFORM.md +++ b/docs/dev/PLATFORM.md @@ -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. diff --git a/docs/dev/vm-tests.md b/docs/dev/vm-tests.md index f5fef97b..85c86322 100644 --- a/docs/dev/vm-tests.md +++ b/docs/dev/vm-tests.md @@ -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 diff --git a/docs/installation.md b/docs/installation.md index 795d6853..575218ef 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -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. diff --git a/nix/nixos-module.nix b/nix/nixos-module.nix index f5ee757f..5b86905e 100644 --- a/nix/nixos-module.nix +++ b/nix/nixos-module.nix @@ -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 diff --git a/nix/supported-kwin.nix b/nix/supported-kwin.nix new file mode 100644 index 00000000..9a68e069 --- /dev/null +++ b/nix/supported-kwin.nix @@ -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"; +} diff --git a/nix/tests/nixos-module.nix b/nix/tests/nixos-module.nix index 2316f728..23bade17 100644 --- a/nix/tests/nixos-module.nix +++ b/nix/tests/nixos-module.nix @@ -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;