docs(linux): paths and links name the consolidated layout

The KDE docs were moved from komorebi-for-kde/ to docs/linux/ and the sources, nix files,
scripts and schemas to komorebi-linux/, nix/linux/, scripts/linux/ and schemas/linux/, so
every relative link that left docs/ (to sources, nix files, scripts, schemas, .envrc,
rust-toolchain.toml, the old CI file) was broken, and the text named the old paths.

Links were rewritten mechanically by resolving each broken target against the old
location and mapping it to the new one; link texts and code-span paths were updated to
the new paths (komorebi/src -> komorebi-linux/src, nix/ -> nix/linux/, scripts/ ->
scripts/linux/, docs/ -> docs/linux/, schema.json -> schemas/linux/schema.json). The
crate list of the README names komorebi-linux, komorebi-daemon and komorebi-version;
`cargo install --path komorebi` becomes komorebi-daemon; the comparison paragraph of
CONTRIBUTING.md says compare-gen.py is stale (it looks for the old sibling trees).

URLs of the old GitHub repositories are left as they are (a release decision).
COMPARE.md is left as it is (already marked stale).

Verified: a link checker over every markdown file (outside cli/, nix/, tools/, old-ci)
reports no broken link in docs/linux. Nothing was built.
This commit is contained in:
LGUG2Z committed 2026-11-05 15:03:27 -08:00
1 parent 5b2381efb4
commit a7b78cc7e4
20 files changed
+358 -355

No files matched your search

+37 -35
View File
@@ -31,9 +31,9 @@ the 0-BSD license.
## Working on the code
`nix develop` (or [direnv](https://direnv.net), through the [`.envrc`](.envrc))
`nix develop` (or [direnv](https://direnv.net), through the [`.envrc`](../../.envrc))
provides the Rust toolchain, a nightly `rustfmt` and the tools the checks use.
[`rustfmt.toml`](rustfmt.toml) uses an unstable option, which is why the
[`rustfmt.toml`](../../rustfmt.toml) uses an unstable option, which is why the
formatter is a nightly one.
`just check` runs everything a change has to pass before it is pushed: the
@@ -46,25 +46,25 @@ KVM.
## The bridge
[`bridge.js`](komorebi/src/kwin/bridge.js), the script komorebi loads into
[`bridge.js`](../../komorebi-linux/src/kwin/bridge.js), the script komorebi loads into
KWin, is JavaScript that KWin runs as it is: there is no package.json and no
build step. Its types are JSDoc comments, which `tsc` checks against
[`kwin-api.d.ts`](komorebi/src/kwin/kwin-api.d.ts), the part of KWin's
[`kwin-api.d.ts`](../../komorebi-linux/src/kwin/kwin-api.d.ts), the part of KWin's
scripting API the bridge uses; something the bridge starts to use is declared
there first. Its tests, [`bridge.test.js`](komorebi/src/kwin/bridge.test.js),
there first. Its tests, [`bridge.test.js`](../../komorebi-linux/src/kwin/bridge.test.js),
run under `node --test` against a fake KWin. `just check-js` runs both, with the
`tsc` and `node` of the dev shell.
The messages between the bridge and the daemon are in
[`komorebi/src/kwin/fixtures`](komorebi/src/kwin/fixtures), which the tests of
[`komorebi-linux/src/kwin/fixtures`](../../komorebi-linux/src/kwin/fixtures), which the tests of
both sides read. A change to a message changes the fixture, the bridge and the
daemon in the same commit.
## The NixOS module
[`nix/nixos-module.nix`](nix/nixos-module.nix) is `services.komorebi`, which the
[`nix/linux/nixos-module.nix`](../../nix/linux/nixos-module.nix) is `services.komorebi`, which the
flake exports as `nixosModules.default` with its overlay. A change to it comes
with a scenario in [`nix/tests/nixos-module.nix`](nix/tests/nixos-module.nix),
with a scenario in [`nix/linux/tests/nixos-module.nix`](../../nix/linux/tests/nixos-module.nix),
the `nixos-module-eval` check: each scenario is a real NixOS system that is
evaluated and never built, and its checks read the assertions, the unit and
the options it evaluates to. It runs on a Mac too, with `nix build
@@ -73,8 +73,8 @@ session also changes the VM suite `module`, which logs in to Plasma on a machine
with the module and checks the daemon the unit runs. Every other VM suite runs
on machines built with the module too.
Three files are generated from the Rust types and committed: `schema.json` and
`schema.asc.json` (`just jsonschema`), and `nix/komorebi-options.nix`, which types the
Three files are generated from the Rust types and committed: `schemas/linux/schema.json` and
`schemas/linux/schema.asc.json` (`just jsonschema`), and `nix/linux/komorebi-options.nix`, which types the
module's `config` (`just nixgen`, which needs `schemars-nixgen`, `cargo install
schemars-nixgen`). A change to what `komorebi.json` or an `applications.json` can
say regenerates them in the same commit, and the check `schema-fresh` fails when
@@ -83,33 +83,35 @@ made from, which is how the check tells without running `schemars-nixgen`.
A change to what `komorebic hotkeys compile` prints for a key binding file shows
in `keybindings-fixtures`, which compares its output for every file of the
fixture corpus with `nix/tests/keybindings.expected`: write the file again with
the loop in `nix/tests/keybindings.nix`, and read the difference before
fixture corpus with `nix/linux/tests/keybindings.expected`: write the file again with
the loop in `nix/linux/tests/keybindings.nix`, and read the difference before
committing it.
[`nix/supported-kwin.nix`](nix/supported-kwin.nix) has the oldest KWin komorebi
[`nix/linux/supported-kwin.nix`](../../nix/linux/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
`nix eval --raw --file nix/linux/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.
## The comparison
[`docs/dev/COMPARE.md`](docs/dev/COMPARE.md) compares komorebi for KDE with komorebi
[`docs/linux/dev/COMPARE.md`](dev/COMPARE.md) compares komorebi for KDE with komorebi
for Windows and komorebi for Mac, and its tables are generated by
[`scripts/compare-gen.py`](scripts/compare-gen.py) (Python 3 and nothing else) from
this checkout and from checkouts of the other two: the komorebi repository around it and its
`komorebi-for-mac/` when this is `komorebi-for-kde/` of that repository, else `~/komorebi` and
`~/komorebi-for-mac`, unless `--kfw` and `--kfm` say otherwise. Continuous
integration has neither checkout, so it does not run the script. A change to a
[`scripts/linux/compare-gen.py`](../../scripts/linux/compare-gen.py) (Python 3 and nothing else) from
this checkout and from checkouts of the other two. The script is stale: it was written when
komorebi for KDE lived in `komorebi-for-kde/` of a repository next to `komorebi-for-mac/`, and
it looks for the other two trees there (or in `~/komorebi` and `~/komorebi-for-mac`). Since the
consolidation they are `komorebi-windows/` and `komorebi-macos/` of this repository, and the
script and `COMPARE.md` have not been made again. Continuous
integration has no checkouts, so it does not run the script. A change to a
`komorebic` command, a `SocketMessage`, a key of `komorebi.json`, a
`WindowManagerEvent`, a method of `Backend` or a list of keys in `check.rs` is
followed by `python3 -I scripts/compare-gen.py --check docs/dev/COMPARE.md`, and
followed by `python3 -I scripts/linux/compare-gen.py --check docs/linux/dev/COMPARE.md`, and
by `--update` when it reports a stale block, in the same commit. The script stops
and says what when a command, key, event or method has no note about why it
differs, and when a sentence of the document stops being true; the text around an
@@ -119,19 +121,19 @@ updated block is read again each time.
A change that needs a real KWin to be checked comes with a VM test, next to
the Rust test that covers the same behavior against the fake desktop.
[`docs/dev/vm-tests.md`](docs/dev/vm-tests.md) says how they are laid out, how
[`docs/linux/dev/vm-tests.md`](dev/vm-tests.md) says how they are laid out, how
to run one (`just vm NAME`) and how to add one.
## The KWin effects
The patches in [`nix`](nix) change the KWin effects komorebi drives. Each one
The patches in [`nix`](../../nix/linux) change the KWin effects komorebi drives. Each one
is a derivative work of its effect, which is under the GNU General Public
License version 3, and is under the same license. A patch starts with a header
that describes the change and carries the license notice; `patch` skips the
text before the first `diff` line. To change a patch, make the change in the
effect's source at the version the package pins, and write the whole diff again
with `diff -ruN a b` below the header. The check of each package, named after
it (in [`nix/tests/effects.nix`](nix/tests/effects.nix)), builds the package
it (in [`nix/linux/tests/effects.nix`](../../nix/linux/tests/effects.nix)), builds the package
and checks the files it installs, and for a patched package that the patch is
in them:
@@ -142,32 +144,32 @@ nix build .#checks.x86_64-linux.kwin-effect-geometry-change-komorebi-install
## Plasma guests to develop in
[`nix/dev`](nix/dev) has NixOS guests with Plasma for trying a change by hand,
[`nix/linux/dev`](../../nix/linux/dev) has NixOS guests with Plasma for trying a change by hand,
on an Apple silicon Mac (two that QEMU runs and a disk image for UTM) and on a
Linux machine with KVM (the same two QEMU guests, for `x86_64` and for
`aarch64`, and a demo guest, [`nix/dev/run-kde.nix`](nix/dev/run-kde.nix)).
[`docs/dev/utm.md`](docs/dev/utm.md) says how to build and run them,
`aarch64`, and a demo guest, [`nix/linux/dev/run-kde.nix`](../../nix/linux/dev/run-kde.nix)).
[`docs/linux/dev/utm.md`](dev/utm.md) says how to build and run them,
and what a builder has to be for a Mac. They install komorebi with the NixOS
module, and carry nothing of the person who uses them: a key, a password or a
configuration of yours goes into the guest when it runs, never into these files.
The `plasma-guests-eval` check evaluates them, the VM suite `rdp` runs their
RDP server, [`nix/dev/krdp.nix`](nix/dev/krdp.nix), and the VM suite `run-kde`
RDP server, [`nix/linux/dev/krdp.nix`](../../nix/linux/dev/krdp.nix), and the VM suite `run-kde`
boots the demo guest. The demo guest has no
password and no key in its closure: the host shares a directory with them, and
`run-kde` ([`scripts/run-kde`](scripts/run-kde)) starts it. The script is
`run-kde` ([`scripts/linux/run-kde`](../../scripts/linux/run-kde)) starts it. The script is
shellchecked when the package is built, and `run-kde-dry-run` and
`run-kde-doctor` compare what it prints for made-up machines with the texts in
[`nix/tests/run-kde`](nix/tests/run-kde): change one with the other.
[`nix/linux/tests/run-kde`](../../nix/linux/tests/run-kde): change one with the other.
## Continuous integration
[`ci.yaml`](.github/workflows/ci.yaml) runs on every pull request and on every
[`ci.yaml`](../dev/old-ci/linux/workflows/ci.yaml) runs on every pull request and on every
push to `master`, `feature/*` and `hotfix/*`, in this repository only. The
`lint` job builds every check that needs no virtual machine and runs
`just lint`, `cargo-deny` checks licenses and advisories, and
the VM tests run on KVM in two jobs: `vm-fast` on every pull request and
`vm-slow` on `master`, every week, and on pull requests labeled `ci:vm-slow`. A weekly
[workflow](.github/workflows/update-flake-lock.yaml) opens a pull request that
[workflow](../dev/old-ci/linux/workflows/update-flake-lock.yaml) opens a pull request that
moves `flake.lock`, and the same jobs run on it.
The flake follows the tip of nixpkgs-unstable, so KWin and Plasma change
@@ -185,7 +187,7 @@ nixpkgs is not pinned back.
## Releases
A release is a tag. Set `version` in
[`komorebi/Cargo.toml`](komorebi/Cargo.toml) (which the flake reads) to the new version, commit it, and push the tag
[`komorebi-linux/Cargo.toml`](../../komorebi-linux/Cargo.toml) (which the flake reads) to the new version, commit it, and push the tag
`vVERSION` on that commit. For every run, the `build` job of `ci.yaml` builds
`komorebi` and `komorebic` with nix on an x86_64 and an arm64 runner, and keeps
them as an artifact of the run for 14 days. On a tag, once `lint`, `vm-fast` and
@@ -195,7 +197,7 @@ with:
- `komorebi-VERSION-x86_64-unknown-linux-gnu.zip` and
`komorebi-VERSION-aarch64-unknown-linux-gnu.zip`, each with the two binaries;
- `checksums.txt`, the SHA-256 sum of every other file of the release;
- `schema.json`, the schema of `komorebi.json`, when the repository has one;
- `schemas/linux/schema.json`, the schema of `komorebi.json`, when the repository has one;
- release notes that [kokai](https://github.com/Joxit/kokai) writes from the
commit messages since the previous version tag.
@@ -222,7 +224,7 @@ included, is at most 80 columns, and the body says why the change is made.
Documentation lands in the commit that changes the behavior it describes, not
in a later one. A change to a `komorebic` subcommand regenerates its page in
[`docs/cli`](docs/cli) with `just docgen`.
[`docs/linux/cli`](cli) with `just docgen`.
## Zero-Clause BSD
+42 -41
View File
@@ -12,7 +12,7 @@ On NixOS, the flake's module, `services.komorebi`, installs `komorebi` and
`komorebic` and starts komorebi with every Plasma session: one flake input,
one module line and `services.komorebi.enable = true`. Elsewhere, both are
built from source, or taken from a release of this repository
([Binaries](#binaries)). [`docs/installation.md`](docs/installation.md) has the
([Binaries](#binaries)). [`docs/linux/installation.md`](installation.md) has the
module and the build from source. The Komorebi license does not allow anyone
else to redistribute binaries.
@@ -29,8 +29,8 @@ 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, 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
checks against [`nix/linux/supported-kwin.nix`](../../nix/linux/supported-kwin.nix);
[`docs/linux/dev/PLATFORM.md`](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
with one monitor and no windows instead.
@@ -41,7 +41,7 @@ directory): a message can ask for the state of the window manager, ask which
monitor, workspace or container has the focus, give the focus to another
window, move the focused window to another tile, change the layout, resize a
tile, float a window, give one window the whole work area or have KWin maximize it, retile every
monitor, or stop the daemon. [`komorebi-client`](komorebi-client) writes them, and `komorebic`,
monitor, or stop the daemon. [`komorebi-client`](../../komorebi-client) writes them, and `komorebic`,
the command line, is how a person sends them. `komorebic start` runs the
`komorebi` on the `PATH`, and passes it what follows a `--`. In a Plasma
session:
@@ -57,9 +57,9 @@ komorebic stop
`komorebic start -- --fake-backend` tries the daemon and `komorebic` without a
compositor, against the in-memory desktop.
`nix develop` provides the Rust toolchain that [`rust-toolchain.toml`](rust-toolchain.toml)
`nix develop` provides the Rust toolchain that [`rust-toolchain.toml`](../../rust-toolchain.toml)
selects, a nightly `rustfmt`, and the tools `just check` and the flake's checks
use. With [direnv](https://direnv.net), the [`.envrc`](.envrc) does it on
use. With [direnv](https://direnv.net), the [`.envrc`](../../.envrc) does it on
`cd`. On Linux, `nix run .#komorebi -- --version` builds and runs the daemon
without a checkout of the toolchain.
@@ -73,7 +73,7 @@ nix run .#run-kde
```
`run-kde --doctor` checks the machine and says how to fix what is missing.
[`docs/trying-it.md`](docs/trying-it.md) says what you need, what you see, the key bindings to try
[`docs/linux/trying-it.md`](trying-it.md) says what you need, what you see, the key bindings to try
and what to do when it does not start.
## Binaries
@@ -88,14 +88,15 @@ the system they run on, which has to be 2.39 or newer at time of writing
[nix-ld](https://github.com/nix-community/nix-ld); on NixOS, build komorebi
from this flake instead.
The [Komorebi License](LICENSE.md) allows anyone to distribute the source code,
The [Komorebi License](../../LICENSE.md) allows anyone to distribute the source code,
but not binaries built from it. The releases of this repository are the only
binaries, and there is no public binary cache for the flake: nix builds
komorebi from source.
## Crates
- [`komorebi`](komorebi): the daemon, and the library behind it. The library has
- [`komorebi-linux`](../../komorebi-linux): the library behind the daemon (the `komorebi` binary is the
package [`komorebi-daemon`](../../komorebi-daemon), which calls its `daemon::run` on Linux). The library has
the vocabulary the window manager is written in (`core`), the `Backend` trait
through which it reaches a compositor and the in-memory desktop the tests use
(`backend`), the backend that reaches KWin through a script it runs and edits
@@ -122,24 +123,24 @@ komorebi from source.
key binding file, and the desktop it runs on, for mistakes without the daemon
(`check`). With a key binding file, it registers keys with KWin's global
shortcut daemon and runs their commands (`kwin::hotkeys`).
- [`komorebi-client`](komorebi-client): a library that sends messages to the
- [`komorebi-client`](../../komorebi-client): a library (shared with Windows and macOS, with a `linux` module) that sends messages to the
daemon, reads its answers, subscribes to its notifications, and re-exports
the types they are made of.
- [`komorebi-hotkeys`](komorebi-hotkeys): reads the key binding files of skhd,
- [`komorebi-hotkeys`](../../komorebi-hotkeys): reads the key binding files of skhd,
whkd and sxhkd into one model, with the keys as KDE stores them, plans each
binding as a KDE shortcut file or as a key komorebi registers itself, and has
the engine that decides, with no I/O of its own, which keys komorebi holds
and what each press does. It does not depend on the daemon. Its tests read the files in
[`komorebi-hotkeys/tests/fixtures`](komorebi-hotkeys/tests/fixtures), where
[`komorebi-hotkeys/tests/fixtures`](../../komorebi-hotkeys/tests/fixtures), where
each case is written in every format that can express it.
- [`komorebic`](komorebic): the command line. A subcommand that asks something
- [`komorebic`](../../komorebic): the command line (one package for the three platforms, with a `linux` module). A subcommand that asks something
of the daemon is one message on its socket, and the others work without the daemon:
`start` and the autostart commands start it, `check` looks at the files and the
desktop, `quickstart` writes files, `export-kde-shortcuts` and `hotkeys compile`
write the bindings of a key binding file that KDE can run by itself as shortcut
files, and `configuration`, `log`, `data-directory`, `completions`, the schema
printers and the hidden `docgen` print.
- [`version`](version): the version string every binary reports.
- [`komorebi-version`](../../crates/komorebi-version): the version string every binary reports.
The layouts, which turn a work area and a number of containers into a rectangle
for each, are `komorebi-layouts` from [komorebi](https://github.com/LGUG2Z/komorebi),
@@ -151,20 +152,20 @@ The flake also builds the KWin effects komorebi drives, which are not part of
KWin:
- `kde-rounded-corners-komorebi`
([`nix/kde-rounded-corners.nix`](nix/kde-rounded-corners.nix)): KDE Rounded
([`nix/linux/kde-rounded-corners.nix`](../../nix/linux/kde-rounded-corners.nix)): KDE Rounded
Corners 0.11.0, which draws an outline around each window, built so that KWin
does not load it until it is asked to, and with a patch that lets komorebi
give each window a color of its own.
- `kwin-effect-geometry-change-komorebi`
([`nix/kwin-effect-geometry-change.nix`](nix/kwin-effect-geometry-change.nix)):
([`nix/linux/kwin-effect-geometry-change.nix`](../../nix/linux/kwin-effect-geometry-change.nix)):
Geometry Change 1.5, a scripted effect that animates a window that a program
or a script moves or resizes, with a patch that makes its easing curve a
setting.
Each one is a package for Linux and an attribute of `overlays.default`, built
with the KWin of the nixpkgs the overlay is applied to.
[`nix/tests/effects.nix`](nix/tests/effects.nix) checks the files each package
installs. [`docs/dev/PLATFORM.md`](docs/dev/PLATFORM.md#kwin-effects) has what
[`nix/linux/tests/effects.nix`](../../nix/linux/tests/effects.nix) checks the files each package
installs. [`docs/linux/dev/PLATFORM.md`](dev/PLATFORM.md#kwin-effects) has what
they need from KWin.
## Checks
@@ -179,7 +180,7 @@ TOML and Nix formatting, the tests under `cargo nextest`, and
`nixos-module-eval`, which evaluates the NixOS module in real NixOS systems,
`keybindings-fixtures`, which runs every key binding file of the fixture corpus
through `komorebic hotkeys compile` and compares what it prints with
`nix/tests/keybindings.expected`, `schema-fresh`, which compares the schemas and
`nix/linux/tests/keybindings.expected`, `schema-fresh`, which compares the schemas and
the options made from them with the Rust types, and `nix-options-validation`,
which checks the example configuration, in Nix and in JSON, against the schema,
all on Linux and on an Apple silicon Mac. On Linux it also builds the KWin effects and checks
@@ -188,7 +189,7 @@ desktop, since KWin only exists on Linux. `nix fmt` formats every file the check
The VM tests boot NixOS with Plasma and run a real KWin, on machines configured
with the NixOS module, so every one of them runs komorebi as the module installs
it. `just vm NAME` runs one; [`docs/dev/vm-tests.md`](docs/dev/vm-tests.md) has
it. `just vm NAME` runs one; [`docs/linux/dev/vm-tests.md`](dev/vm-tests.md) has
the details, including how to run them on a Mac.
To try komorebi by hand in a real Plasma session, the flake has Plasma guests
@@ -199,7 +200,7 @@ for `x86_64` and for `aarch64`, and a demo guest of the session guest, which
shows komorebi tiling a few windows in the first minute. On Linux,
`nix run .#run-kde` (or `just run-kde`) starts the demo in a window, and
`run-kde --doctor` says what the machine lacks.
[`docs/dev/utm.md`](docs/dev/utm.md) says how to build and run them;
[`docs/linux/dev/utm.md`](dev/utm.md) says how to build and run them;
`plasma-guests-eval` evaluates them on every system, and `run-kde-dry-run` and
`run-kde-doctor` run the command against machines that a test makes up.
@@ -208,7 +209,7 @@ shows komorebi tiling a few windows in the first minute. On Linux,
The daemon decides where every window goes and asks the compositor to put it
there. Everything it needs from the compositor is behind one trait, `Backend`,
so the window manager logic runs against a real compositor and against an
in-memory fake desktop alike. [`docs/dev/ARCHITECTURE.md`](docs/dev/ARCHITECTURE.md)
in-memory fake desktop alike. [`docs/linux/dev/ARCHITECTURE.md`](dev/ARCHITECTURE.md)
describes the trait and where each of its rules is enforced.
On KDE Plasma the backend is in two parts. A script that komorebi loads into
@@ -332,8 +333,8 @@ workspace change layout with the number of windows it has, as the file's
has as a `komorebi.json`, and `replace-configuration` makes the daemon start over from
another file. `quickstart` writes an example configuration and sample key bindings, and
`enable-autostart` an autostart entry that has Plasma start komorebi at login. The Rust types that read the file describe it as a JSON Schema
(`schema.json`, written by `just jsonschema` and printed by `static-config-schema`), and the
module's `config` option is typed from that schema (`nix/komorebi-options.nix`, written by
(`schemas/linux/schema.json`, written by `just jsonschema` and printed by `static-config-schema`), and the
module's `config` option is typed from that schema (`nix/linux/komorebi-options.nix`, written by
`just nixgen`), so a configuration written in Nix is checked when it is evaluated.
`check` reads the file the way the daemon does and says in words what is wrong with it: JSON that
does not parse, with the line, a value komorebi does not read, a key that is not a setting (with
@@ -349,7 +350,7 @@ listens on a socket of its own, and after each event, each message and each
change of the monitors, the daemon connects to it and writes it with the state
of the window manager.
On NixOS, the module [`nix/nixos-module.nix`](nix/nixos-module.nix) runs the
On NixOS, the module [`nix/linux/nixos-module.nix`](../../nix/linux/nixos-module.nix) runs the
daemon as a systemd user unit that the Plasma session starts, and systemd
starts it again if it fails.
@@ -381,34 +382,34 @@ and the unit starts the daemon with the file.
## Documentation
The user guide starts at [`docs/index.md`](docs/index.md),
[`docs/trying-it.md`](docs/trying-it.md) starts a guest in which komorebi tiles a few windows,
[`docs/installation.md`](docs/installation.md) says how to install komorebi,
[`docs/usage/configuration.md`](docs/usage/configuration.md) explains `komorebi.json`,
[`docs/example-configurations.md`](docs/example-configurations.md) has an example of it,
[`docs/usage/keybindings.md`](docs/usage/keybindings.md) how to give komorebi key bindings,
and [`docs/cli`](docs/cli) has a page for every `komorebic` subcommand, which
The user guide starts at [`docs/linux/index.md`](index.md),
[`docs/linux/trying-it.md`](trying-it.md) starts a guest in which komorebi tiles a few windows,
[`docs/linux/installation.md`](installation.md) says how to install komorebi,
[`docs/linux/usage/configuration.md`](usage/configuration.md) explains `komorebi.json`,
[`docs/linux/example-configurations.md`](example-configurations.md) has an example of it,
[`docs/linux/usage/keybindings.md`](usage/keybindings.md) how to give komorebi key bindings,
and [`docs/linux/cli`](cli) has a page for every `komorebic` subcommand, which
`just docgen` writes from the subcommands' help.
`cargo doc --workspace --no-deps --open` builds the API documentation.
[`CONTRIBUTING.md`](CONTRIBUTING.md) says how to work on the code.
[`docs/dev/ARCHITECTURE.md`](docs/dev/ARCHITECTURE.md) describes the model,
[`docs/dev/DESIGN.md`](docs/dev/DESIGN.md) says why it is built that way,
[`docs/dev/PLATFORM.md`](docs/dev/PLATFORM.md) what it needs from KDE Plasma,
[`docs/dev/COMPARE.md`](docs/dev/COMPARE.md) what is the same and what is different in
[`docs/linux/dev/ARCHITECTURE.md`](dev/ARCHITECTURE.md) describes the model,
[`docs/linux/dev/DESIGN.md`](dev/DESIGN.md) says why it is built that way,
[`docs/linux/dev/PLATFORM.md`](dev/PLATFORM.md) what it needs from KDE Plasma,
[`docs/linux/dev/COMPARE.md`](dev/COMPARE.md) what is the same and what is different in
komorebi for Windows and komorebi for Mac,
[`docs/dev/vm-tests.md`](docs/dev/vm-tests.md) how the VM tests work, and
[`docs/dev/utm.md`](docs/dev/utm.md) how to develop in a Plasma guest, and
[`docs/dev/wsl2-probe.md`](docs/dev/wsl2-probe.md) how to find out whether a
[`docs/linux/dev/vm-tests.md`](dev/vm-tests.md) how the VM tests work, and
[`docs/linux/dev/utm.md`](dev/utm.md) how to develop in a Plasma guest, and
[`docs/linux/dev/wsl2-probe.md`](dev/wsl2-probe.md) how to find out whether a
NixOS-WSL2 machine can run one (`nix run .#wsl2-probe`).
## License
komorebi for KDE is under the [Komorebi License](LICENSE.md). Contributions
komorebi for KDE is under the [Komorebi License](../../LICENSE.md). Contributions
are accepted under the terms in [`CONTRIBUTING.md`](CONTRIBUTING.md).
The license lets others distribute the source code but not binaries, so there
is no public binary cache for what the flake builds: komorebi and the KWin
effects are built on each machine that installs them, with their dependencies
from nixpkgs. The patches to the effects in [`nix`](nix) are derivative works
from nixpkgs. The patches to the effects in [`nix`](../../nix/linux) are derivative works
of the effects, which are under the GNU General Public License version 3, and
are under the same license, as the header of each one states.
+181 -181
View File
@@ -2,7 +2,7 @@
komorebi is a tiling window manager. It decides where every window goes and asks a
compositor to put it there. Everything it needs from the compositor is behind one trait,
[`Backend`](../../komorebi/src/backend/mod.rs), so the window manager is written, and
[`Backend`](../../../komorebi-linux/src/backend/mod.rs), so the window manager is written, and
tested, without one.
This page describes that trait, who implements and calls it, where each of its rules is
@@ -93,9 +93,9 @@ same and what is different in komorebi for Windows and komorebi for Mac.
is the effect that draws the border, and Geometry Change the one that animates windows.
- **Compositor**: the program that owns the screen and the windows. On KDE Plasma it is
KWin.
- **Backend**: the implementation of the [`Backend`](../../komorebi/src/backend/mod.rs)
- **Backend**: the implementation of the [`Backend`](../../../komorebi-linux/src/backend/mod.rs)
trait that talks to a compositor.
- **Fake**: [`FakeBackend`](../../komorebi/src/backend/fake.rs), the in-memory backend
- **Fake**: [`FakeBackend`](../../../komorebi-linux/src/backend/fake.rs), the in-memory backend
the tests use.
- **Bridge**: the script komorebi loads into KWin ([`bridge.js`]). It reports what KWin
tells it and carries out what the daemon asks.
@@ -635,7 +635,7 @@ monocle that is maximized leaves the monocle. While a window is maximized, the m
about the tiles are dropped before they are handled: `MoveWindow`, `CycleMoveWindow`, the stack
messages, the resize, promote and preselect messages, `ToggleLock`, `ToggleFloat`,
`ToggleMonocle`, and the messages that send a container to another monitor or workspace
(`is_layout_command` in [`process_command`](../../komorebi/src/process_command.rs)). A window that
(`is_layout_command` in [`process_command`](../../../komorebi-linux/src/process_command.rs)). A window that
closes while it is maximized leaves the workspace like any other. `FocusWindow` finds no
container on any side of the maximized window, so the focus goes to the monitor on that side and
fails where there is none, and a maximized window, or a monocle, on the workspace it reaches is
@@ -957,9 +957,9 @@ that of an applications file, and `notification-schema` and `socket-schema` thos
[`Notification`] and of a [`SocketMessage`]; the daemon answers the same four questions on its
socket (the fourth is the schema of a list of applications files, where `komorebic` prints the
schema of one).
The schemas of the first two are committed (`schema.json`, `schema.asc.json`, written by `just
The schemas of the first two are committed (`schemas/linux/schema.json`, `schemas/linux/schema.asc.json`, written by `just
jsonschema`), and so are the options the module's `config` is typed with
(`nix/komorebi-options.nix`, which `schemars-nixgen` makes from `schema.json` and `just nixgen`
(`nix/linux/komorebi-options.nix`, which `schemars-nixgen` makes from `schemas/linux/schema.json` and `just nixgen`
gives the hash of the schema as its first line). The check `schema-fresh` compares the schemas with
what the Rust types print and the hash with the schema, so a change to a key that leaves one of
them behind fails.
@@ -1027,8 +1027,8 @@ asks for what it cannot do.
| `--configuration-only` leaves the desktop out | framework path: the section is pushed only without it | `configuration_only_leaves_the_desktop_out` | none |
| `komorebic check` exits with status 1 if and only if a finding is an error | framework path: `komorebic` exits through [`Report::has_errors`] | `a_good_configuration_passes`, `a_typo_is_a_warning_with_the_word_that_was_meant_and_does_not_fail`, `a_file_that_is_not_json_fails_and_shows_the_line` | none |
| The rules of an applications file and of the configuration add up | framework path: both are appended to the process-wide lists | `the_rules_of_the_configuration_and_of_the_file_add_up`, `every_file_of_a_list_is_read` | none |
| `schema.json` and `schema.asc.json` are what the Rust types print | Nix check `schema-fresh`, and a test that compares them with `komorebic`'s output | `schema-fresh`, `the_schema_files_of_the_repository_are_what_the_subcommands_print` | `just jsonschema` |
| The options the module is typed with are made from the committed schema | the hash of `schema.json` in the first line of `nix/komorebi-options.nix`, compared by `schema-fresh` | `schema-fresh` | `just nixgen` |
| `schemas/linux/schema.json` and `schemas/linux/schema.asc.json` are what the Rust types print | Nix check `schema-fresh`, and a test that compares them with `komorebic`'s output | `schema-fresh`, `the_schema_files_of_the_repository_are_what_the_subcommands_print` | `just jsonschema` |
| The options the module is typed with are made from the committed schema | the hash of `schemas/linux/schema.json` in the first line of `nix/linux/komorebi-options.nix`, compared by `schema-fresh` | `schema-fresh` | `just nixgen` |
| The example, in Nix and in JSON, follows the schema, and says the same in both | Nix check `nix-options-validation`: the options evaluated against the Nix example, both examples checked with `check-jsonschema`, and one contained in the other | `nix-options-validation` | none |
| A window a workspace rule names ends on its workspace, and on that workspace's desktop once the workspace is shown | framework path: [`WindowManager::enforce_workspace_rules`] moves it in the model, and has the target monitor put it on the desktop | `a_rule_sends_the_window_of_an_application_to_its_workspace`, `a_window_a_rule_moves_between_workspaces_that_are_out_of_view_is_put_on_the_new_desktop`, `vm-workspace-rules` | none |
| A window a workspace rule takes off the workspace in front is out of sight until its workspace is shown | framework path: [`WindowManager::enforce_workspace_rules`] hides it, and showing the workspace restores it | `a_rule_sends_the_window_of_an_application_to_its_workspace`, `vm-workspace-rules` | none |
@@ -1046,7 +1046,7 @@ asks for what it cannot do.
| The highest of the rules a count of containers reaches decides the layout, the offset and the container behavior | framework path: [`Workspace::update`] reads the rules, kept in the order of their thresholds | `layout_rules_change_the_layout_with_the_number_of_windows`, `work_area_offset_rules_change_the_offset_with_the_number_of_windows`, `window_container_behaviour_rules_change_the_behaviour_with_the_number_of_containers` | none |
| A workspace's own container behavior and float override come before the one for every workspace, and its floating layer behavior before its monitor's, which comes before the one for every workspace | framework path: [`WindowManager::window_management_behaviour`] reads the workspace, then (for the floating layer) the monitor, then the window manager | `the_behaviour_of_a_workspace_comes_before_the_one_for_every_workspace`, `the_float_override_of_a_workspace_comes_before_the_one_for_every_workspace`, `the_floating_layer_behaviour_of_a_workspace_comes_before_a_monitors_and_that_before_the_default` | none |
| A workspace places the windows that open by the `initial_window_placement_rules` of its entry in `komorebi.json` | framework path: [`Workspace::load_static_config`] sets [`Workspace::initial_window_placement_rules`] from the entry, and [`Workspace::new_container_for_window`] reads it | `a_workspace_in_komorebi_json_has_them`, `the_rules_come_from_the_configuration_of_the_workspace`, `vm-placement` | none |
| The schema, and the module's typed `config`, take a place in each form the daemon reads: a name, a number, or text that is a number | test: the schema of [`PlacementTarget`] is written by hand, to say what its `Serialize` and `Deserialize` do, and a file with a place of each form is checked against `schema.json` | `a_place_is_described_as_a_name_a_number_or_text_that_is_a_number`, `nix-options-validation`, `nixos-module-eval` ("the place a workspace gives the windows that open is a typed option in each form it is read") | none |
| The schema, and the module's typed `config`, take a place in each form the daemon reads: a name, a number, or text that is a number | test: the schema of [`PlacementTarget`] is written by hand, to say what its `Serialize` and `Deserialize` do, and a file with a place of each form is checked against `schemas/linux/schema.json` | `a_place_is_described_as_a_name_a_number_or_text_that_is_a_number`, `nix-options-validation`, `nixos-module-eval` ("the place a workspace gives the windows that open is a typed option in each form it is read") | none |
| The configuration the daemon generates loads and says the same | test | `a_configuration_comes_out_again_as_the_settings_of_the_window_manager` | none |
| The daemon reads the file it is given or the one in the config home, not both | startup order: `main.rs` takes `--config` before the config home | `the_daemon_follows_the_file_it_is_given_when_the_file_changes`, `the_daemon_reads_komorebi_json_from_the_config_home` | none |
@@ -1091,7 +1091,7 @@ Without a border, because they are off or the compositor has no effect to draw o
given back the next time the workspace is tiled.
The KWin backend draws the border with the effect KDE Rounded Corners
([`kwin::effects`](../../komorebi/src/kwin/effects.rs)). `apply_look` writes the effect's settings
([`kwin::effects`](../../../komorebi-linux/src/kwin/effects.rs)). `apply_look` writes the effect's settings
into the user's `kwinrc`, group `[Round-Corners]`, through [`Kwinrc`]; loads the effect with
`loadEffect` unless it is loaded; and always asks it to read its settings again
(`reconfigureEffect`), since KWin hands an effect the copy of `kwinrc` it read when it started. A
@@ -1199,9 +1199,9 @@ The flake exports one module under two names, `nixosModules.default` and
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`;
`nix/linux/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
through `check-jsonschema` against `schemas/linux/schema.json` when the system is built (comment lines taken out
first, since the checker reads plain JSON). `applicationSpecificConfiguration.sources` are files
fetched from GitHub that become `app_specific_configuration_path`; the module has none by default.
`internal.configAttrs` is the configuration as the attribute set the options make, for the tests.
@@ -1259,23 +1259,23 @@ too.
| The static shortcuts the module installs and the bindings its daemon runs are one plan of one file | framework path: the build and `execStart` get the same store file, format and mode, and `plan` is deterministic | `nixos-module-eval` (the key binding scenarios), `vm-keys-skhd`, `vm-keys-whkd`, `vm-keys-sxhkd` | none |
| Key bindings have one source, a format, and no skhd `.load` | evaluation error: assertions of the module | `nixos-module-eval` ("text and file together", "without a format", "skhd's .load") | none |
| `strict` fails the build on a warning or an error | `komorebic hotkeys compile --strict` exits non-zero before it writes anything, and the module's build of the key bindings passes `--strict` only when `strict` is set and fails when `komorebic` does | `strict_refuses_a_file_with_a_warning_and_writes_nothing`, `nixos-module-eval` ("with strict, the build of the key bindings runs komorebic hotkeys compile --strict", "without strict ... no --strict") | none |
| What `hotkeys compile` prints for every file of the corpus is what was reviewed | test: a diff against `nix/tests/keybindings.expected` | `keybindings-fixtures` | writing the file again |
| What `hotkeys compile` prints for every file of the corpus is what was reviewed | test: a diff against `nix/linux/tests/keybindings.expected` | `keybindings-fixtures` | writing the file again |
| The VM suites run komorebi as the module installs it | framework path: the test nodes import the module, and `komorebi@NAME` runs its `execStart` | every VM suite | a suite's `node` can set `services.komorebi.enable = false` (`vm-render-smoke` does) |
## The parts
- [`backend`](../../komorebi/src/backend/mod.rs): the trait, the two data types, and the
- [`backend`](../../../komorebi-linux/src/backend/mod.rs): the trait, the two data types, and the
process-wide handle ([`set_backend`], [`backend`], [`with_backend`]).
- [`backend::fake`](../../komorebi/src/backend/fake.rs): the fake.
- [`backend::fake`](../../../komorebi-linux/src/backend/fake.rs): the fake.
- [`ring`](../../../crates/komorebi-collections/src/ring.rs): the [`Ring`], and the macro that gives every type
holding one the same accessors (`containers()`, `focused_container_mut()`, ...).
- [`monitor`](../../komorebi/src/monitor.rs), [`workspace`](../../komorebi/src/workspace.rs),
[`container`](../../komorebi/src/container.rs), [`window`](../../komorebi/src/window.rs):
- [`monitor`](../../../komorebi-linux/src/monitor.rs), [`workspace`](../../../komorebi-linux/src/workspace.rs),
[`container`](../../../komorebi-linux/src/container.rs), [`window`](../../../komorebi-linux/src/window.rs):
the four levels of the tree; `window` also has the rule engine ([`should_act`]).
- [`lockable_sequence`](../../../crates/komorebi-collections/src/lockable_sequence.rs): inserting, removing and
swapping in a list where some elements are locked in place, which is how a workspace
changes its containers.
- [`window_manager`](../../komorebi/src/window_manager.rs): the [`WindowManager`] and the
- [`window_manager`](../../../komorebi-linux/src/window_manager.rs): the [`WindowManager`] and the
operations on it (tile the workspace in front, tile every monitor, take a minimized
window out, move the focus, move the focused container, change the layout, resize or
promote the focused container, float a window, switch the layer, put a container in
@@ -1285,59 +1285,59 @@ too.
something else, name a workspace and find it by its name, set the layout of a workspace
that is not in front, focus another monitor, and move containers and workspaces between
monitors).
- [`desktop`](../../komorebi/src/desktop.rs): loads the monitors and the open windows from
- [`desktop`](../../../komorebi-linux/src/desktop.rs): loads the monitors and the open windows from
the backend, and reads the sizes of the monitors again.
- [`window_manager_event`](../../komorebi/src/window_manager_event.rs) and
[`process_event`](../../komorebi/src/process_event.rs): the events, and what the window
- [`window_manager_event`](../../../komorebi-linux/src/window_manager_event.rs) and
[`process_event`](../../../komorebi-linux/src/process_event.rs): the events, and what the window
manager does with each.
- [`window_manager_event_listener`](../../komorebi/src/window_manager_event_listener.rs): the
- [`window_manager_event_listener`](../../../komorebi-linux/src/window_manager_event_listener.rs): the
channel that carries events from the backend to the window manager, and
[`listen_for_events`], the thread that takes them off it.
- [`monitor_reconciliator`](../../komorebi/src/monitor_reconciliator.rs): the channel the KWin
- [`monitor_reconciliator`](../../../komorebi-linux/src/monitor_reconciliator.rs): the channel the KWin
backend sends [`MonitorNotification`]s on, [`listen_for_notifications`], the thread that
takes them, and [`reconcile_display_change`], which brings the window manager's monitors in
line with the outputs, and [`wake_up`], which puts the desktop in order after a wake;
[`reconcile`](../../komorebi/src/reconcile.rs): moves what was on a monitor that went to the
[`reconcile`](../../../komorebi-linux/src/reconcile.rs): moves what was on a monitor that went to the
monitors that are left, and every container whose window is on another monitor to that
monitor.
- [`kwin`](../../komorebi/src/kwin/mod.rs): the KWin backend, its D-Bus service and the held
call; [`kwin::state`](../../komorebi/src/kwin/state.rs), the table;
[`kwin::power`](../../komorebi/src/kwin/power.rs), the watchers of logind's sleep signal and the
- [`kwin`](../../../komorebi-linux/src/kwin/mod.rs): the KWin backend, its D-Bus service and the held
call; [`kwin::state`](../../../komorebi-linux/src/kwin/state.rs), the table;
[`kwin::power`](../../../komorebi-linux/src/kwin/power.rs), the watchers of logind's sleep signal and the
lock screen's;
[`kwin::kwinrc`](../../komorebi/src/kwin/kwinrc.rs), the editor of the user's `kwinrc`, which
[`kwin::kwinrc`](../../../komorebi-linux/src/kwin/kwinrc.rs), the editor of the user's `kwinrc`, which
keeps the values it changes and puts them back; the parking desktop is made, swept and removed
in `kwin` and tracked in `kwin::state`; and
[`bridge.js`](../../komorebi/src/kwin/bridge.js), the bridge.
- [`static_config`](../../komorebi/src/static_config.rs): `komorebi.json`, [`StaticConfig`], and
[`bridge.js`](../../../komorebi-linux/src/kwin/bridge.js), the bridge.
- [`static_config`](../../../komorebi-linux/src/static_config.rs): `komorebi.json`, [`StaticConfig`], and
how it is loaded, reloaded and generated.
- [`border_manager`](../../komorebi/src/border_manager/mod.rs): the border settings, and the
- [`border_manager`](../../../komorebi-linux/src/border_manager/mod.rs): the border settings, and the
[`Look`] they make, which it asks the backend for.
- [`animation`](../../komorebi/src/animation/mod.rs): the animation settings, which the look has.
- [`theme_manager`](../../komorebi/src/theme_manager.rs): a theme's colors for the borders, and the
- [`animation`](../../../komorebi-linux/src/animation/mod.rs): the animation settings, which the look has.
- [`theme_manager`](../../../komorebi-linux/src/theme_manager.rs): a theme's colors for the borders, and the
palettes made from pictures.
- [`kwin::wallpaper`](../../komorebi/src/kwin/wallpaper.rs): the Plasma shell's side of a
- [`kwin::wallpaper`](../../../komorebi-linux/src/kwin/wallpaper.rs): the Plasma shell's side of a
wallpaper: the screen of an output, what it shows, and the picture set.
- [`transparency_manager`](../../komorebi/src/transparency_manager.rs): which windows are
- [`transparency_manager`](../../../komorebi-linux/src/transparency_manager.rs): which windows are
see-through, and the opacity they are given.
- [`kwin::effects`](../../komorebi/src/kwin/effects.rs): the KWin effect that draws the border,
- [`kwin::effects`](../../../komorebi-linux/src/kwin/effects.rs): the KWin effect that draws the border,
its settings and the state komorebi keeps of it.
- [`check`](../../komorebi/src/check.rs): the checks behind `komorebic check` (the configuration,
- [`check`](../../../komorebi-linux/src/check.rs): the checks behind `komorebic check` (the configuration,
and the desktop it runs on), the [`Finding`]s they return and the [`Report`] `komorebic` gathers
them in.
- [`process_command`](../../komorebi/src/process_command.rs): the thread that listens on the
- [`process_command`](../../../komorebi-linux/src/process_command.rs): the thread that listens on the
socket, and what the window manager does with each message.
- [`state`](../../komorebi/src/state.rs): the [`State`] a `State` message is answered with,
- [`state`](../../../komorebi-linux/src/state.rs): the [`State`] a `State` message is answered with,
and whether an event or a message changed it.
- [`lib.rs`](../../komorebi/src/lib.rs): the subscribers, the [`Notification`], and
- [`lib.rs`](../../../komorebi-linux/src/lib.rs): the subscribers, the [`Notification`], and
[`notify_subscribers`].
- [`komorebi-client`](../../komorebi-client/src/lib.rs): a library that writes messages on
- [`komorebi-client`](../../../komorebi-client/src/lib.rs): a library that writes messages on
the socket and reads the answers, and subscribes to notifications, for programs that talk
to the daemon.
- [`komorebic`](../../../komorebic/src/linux/mod.rs): the command line. A subcommand that asks
something of the daemon is one message, sent with `komorebi-client`; `start` runs the
daemon, `log` follows its log file in [`LOG_DIR`], and the hidden `docgen` writes
`docs/cli`.
- [`daemon.rs`](../../komorebi/src/daemon.rs): the daemon. It connects to KWin, or installs the
`docs/linux/cli`.
- [`daemon.rs`](../../../komorebi-linux/src/daemon.rs): the daemon. It connects to KWin, or installs the
fake with `--fake-backend`, makes the window manager from `komorebi.json` when there is one,
which binds the socket, loads the desktop, gives the monitors their configuration, asks for the
borders and tiles, starts the threads that listen on the socket, handle events and take the
@@ -1509,14 +1509,14 @@ the fake. The window manager is its only caller, through [`backend`]. The contra
| A subscriber that wants only changes of the state is sent every change of the monitors | framework path: [`notify_subscribers`] treats a monitor notification as an override of the filter | `a_change_of_the_monitors_is_sent_to_a_subscriber_that_filters_state_changes_too` | none |
| Moving the focus moves no window | test | `focus_gives_the_focus_to_the_window_on_that_side_and_moves_nothing`, `vm-core-e2e` ("moving the focus moved no window") | none |
| A subscriber that is gone is dropped, not retried | test | `a_subscriber_that_is_gone_is_dropped_and_not_tried_again` | none |
| The bridge holds no window manager logic | convention, with every decision about an event in the table, which the `kwin::state` unit tests pin | the unit tests in `komorebi/src/kwin/state.rs` | none |
| The bridge holds no window manager logic | convention, with every decision about an event in the table, which the `kwin::state` unit tests pin | the unit tests in `komorebi-linux/src/kwin/state.rs` | none |
| What the bridge sends is what the table reads | type checker: the JSDoc types of the messages in [`bridge.js`]; tests: the events of [`fixtures`] are what the bridge's tests check it sends and what the table's tests feed it | `what the bridge sends for a session is what the daemon's tests read`, `the_bridges_events_for_a_session_are_the_window_events_komorebi_expects` | none |
| What the backend sends is what the bridge carries out | tests: the commands of [`fixtures`] are what the backend's tests check it sends and what the bridge's tests answer it with, checking what KWin is asked to do for each | `the_commands_of_a_session_go_to_the_bridge_as_the_bridges_tests_answer_it`, `what the bridge sends for a session is what the daemon's tests read`, `a command for a window KWin no longer has is given back, and the rest are carried out` | none |
| Everything the bridge sends over D-Bus is one string | type checker: [`kwin-api.d.ts`] gives `callDBus` one string argument | `tsc`, `every call goes to the daemon's names, with one JSON string` | none |
| The bridge uses nothing a KWin script does not have | type checker: the library is ECMAScript 2016 alone, and KWin's API is what [`kwin-api.d.ts`] declares | `tsc` | a declaration KWin does not match: the VM tests run the bridge in KWin |
| A border takes room around the windows only while the compositor draws it | framework path: [`border_manager::send_notification`] keeps the backend's answer in [`BORDER_DRAWN`], which [`Monitor::update_workspace_globals`] reads | `a_border_the_compositor_draws_takes_room_around_each_window_and_none_is_taken_without_one`, `a_look_is_a_command_once_and_says_whether_borders_are_drawn` | none |
| The compositor is asked for the look after every event, every message and every retile, and only a changed look reaches it | framework path: [`WindowManager::process_event`], [`WindowManager::process_command`] and [`WindowManager::retile_all`] call [`border_manager::send_notification`], and a backend compares with the look it applied last | `the_border_messages_set_the_border_and_the_compositor_is_asked_for_it`, `a_look_is_a_command_once_and_says_whether_borders_are_drawn` | the same look applied twice by the KWin backend is not tested |
| No outline is drawn inside a window, and a border is never thicker than the effect can draw | framework path: [`kwin::effects`](../../komorebi/src/kwin/effects.rs) sets every inner outline to 0 and clamps the width to 20 | `the_border_is_the_outer_outline_and_nothing_is_drawn_inside_the_window`, `a_border_thicker_than_the_effect_can_draw_is_the_thickest_it_can`, `vm-look` | none |
| No outline is drawn inside a window, and a border is never thicker than the effect can draw | framework path: [`kwin::effects`](../../../komorebi-linux/src/kwin/effects.rs) sets every inner outline to 0 and clamps the width to 20 | `the_border_is_the_outer_outline_and_nothing_is_drawn_inside_the_window`, `a_border_thicker_than_the_effect_can_draw_is_the_thickest_it_can`, `vm-look` | none |
| Every window has the border color of what it is to the layout, and a window whose kind changes has the new one at once | framework path: [`border_manager::update_colours`] is called after every event and every message, from [`border_manager::window_kinds`], and the backend sends the colors it did not send last time | `the_focused_window_has_the_focus_colour_and_the_others_do_not`, `a_locked_container_that_is_not_focused_is_marked`, `a_stack_has_its_own_colour_when_it_has_the_focus`, `a_monocled_window_has_the_monocle_colour`, `a_floating_window_has_the_floating_colour_while_it_has_the_focus`, `border_colours_are_a_command_only_when_they_change`, `vm-features` (section C) | the stock effect: two colors for every window |
| With borders off no window has a color | framework path: [`border_manager::update_colours`] tells the backend an empty list when `BORDER_ENABLED` is false | `with_borders_off_no_window_has_a_colour` | none |
| The settings of one kind of animation win over the global ones, and a global setting clears them | framework path: the arms of [`WindowManager::process_command`] for `Animation`, `AnimationDuration` and `AnimationStyle`, and [`animation::movement_animation`] and [`animation::movement_style`], which read the kind's setting before the global one | `the_animation_messages_set_the_animation_and_the_compositor_is_asked_for_it` | none |
@@ -1608,7 +1608,7 @@ A window is shown, and ends up on a tile:
## Key bindings
[`komorebi-hotkeys`](../../komorebi-hotkeys/src/lib.rs) is a crate of its own, which does not
[`komorebi-hotkeys`](../../../komorebi-hotkeys/src/lib.rs) is a crate of its own, which does not
depend on the daemon. Its model is the content of a key binding file of any of three hotkey
daemons: skhd (macOS), whkd (Windows) and sxhkd (X11).
@@ -1641,38 +1641,38 @@ daemons: skhd (macOS), whkd (Windows) and sxhkd (X11).
### The parts of the key bindings
- [`qt`](../../komorebi-hotkeys/src/qt.rs): key names to Qt key codes, in the vocabulary of each
- [`qt`](../../../komorebi-hotkeys/src/qt.rs): key names to Qt key codes, in the vocabulary of each
format (skhd's literals and macOS keycodes, whkd's virtual key names, sxhkd's X keysyms), and
`Combo`, which applies the shifted symbol rule: KWin matches the character a key press
produced, so Alt+Shift+1 is registered as Alt+!.
- [`ir`](../../komorebi-hotkeys/src/ir.rs): the model.
- [`skhd`](../../komorebi-hotkeys/src/skhd.rs): reads an skhdrc. A mode may be used before it
- [`ir`](../../../komorebi-hotkeys/src/ir.rs): the model.
- [`skhd`](../../../komorebi-hotkeys/src/skhd.rs): reads an skhdrc. A mode may be used before it
is declared, so each binding waits for the end of the file to be put in its modes. skhd.zig's
`.define` templates and application groups are expanded where they are used.
- [`whkd`](../../komorebi-hotkeys/src/whkd.rs): reads a whkdrc, in any order of its sections,
- [`whkd`](../../../komorebi-hotkeys/src/whkd.rs): reads a whkdrc, in any order of its sections,
where whkd requires one. `tests/whkd_parser.rs` compares it with whkd's own parser,
`whkd-parser` (a dev-dependency), on every whkdrc of the corpus.
- [`sxhkd`](../../komorebi-hotkeys/src/sxhkd.rs): reads an sxhkdrc. Braces are expanded first,
- [`sxhkd`](../../../komorebi-hotkeys/src/sxhkd.rs): reads an sxhkdrc. Braces are expanded first,
into one binding per alternative. A chord chain (`a ; b`) is one binding with several combos;
a chain that stays open (`a : b`) is a mode named after its prefix, entered by the prefix and
left by Escape.
- [`parse`](../../komorebi-hotkeys/src/lib.rs) picks the reader by format.
- [`plan`](../../komorebi-hotkeys/src/plan.rs): sorts a keymap into static shortcuts and the
- [`parse`](../../../komorebi-hotkeys/src/lib.rs) picks the reader by format.
- [`plan`](../../../komorebi-hotkeys/src/plan.rs): sorts a keymap into static shortcuts and the
engine's keymap, by mode: `Auto` (static where it can be), `Engine` (the default: everything
through the engine) or `Static` (no engine; what needs it is left out with a warning).
- [`engine`](../../komorebi-hotkeys/src/engine.rs): the engine, a state machine with no I/O and
- [`engine`](../../../komorebi-hotkeys/src/engine.rs): the engine, a state machine with no I/O and
no clock. Its inputs are a press or a release of an active combo, a change of focus, and the
time; after each it computes the active set it wants from the mode, the chord chain being
typed, the focused application and whether it is paused, and returns the commands to run and
the difference with the active set as effects. The daemon carries them out with kglobalacceld
(`setShortcutKeys`, `setInactive`) and feeds it kglobalacceld's signals.
- [`kde`](../../komorebi-hotkeys/src/kde.rs): writes static shortcuts as `.desktop` files for
- [`kde`](../../../komorebi-hotkeys/src/kde.rs): writes static shortcuts as `.desktop` files for
kglobalacceld (`X-KDE-Shortcuts`, `X-KDE-GlobalAccel-CommandShortcut`, an `Exec` line quoted as
the desktop entry specification requires), and replaces the files it wrote before, and no
other.
- [`text`](../../komorebi-hotkeys/src/text.rs): what the readers share: line numbers, comments,
- [`text`](../../../komorebi-hotkeys/src/text.rs): what the readers share: line numbers, comments,
continued lines and the diagnostics' wording.
- [`tests/fixtures`](../../komorebi-hotkeys/tests/fixtures): the corpus, `<case>.skhdrc`,
- [`tests/fixtures`](../../../komorebi-hotkeys/tests/fixtures): the corpus, `<case>.skhdrc`,
`<case>.whkdrc` and `<case>.sxhkdrc`, each case in every format that can express it.
### The front end
@@ -1698,7 +1698,7 @@ the ones `kde::diff` says that plan would write. It reads no file the desktop ha
### The engine in the daemon
[`komorebi/src/kwin/hotkeys.rs`](../../komorebi/src/kwin/hotkeys.rs) runs the engine against
[`komorebi-linux/src/kwin/hotkeys.rs`](../../../komorebi-linux/src/kwin/hotkeys.rs) runs the engine against
kglobalaccel, on a session bus connection and a thread of its own. The daemon reads the file
it is given with `--keybindings` (or the first it finds in the config directory), plans it in
`--keybindings-mode`, and hands the plan's engine keymap to `kwin::hotkeys::start`, unless the
@@ -1785,213 +1785,213 @@ plan needs no engine. A failure to start is logged, and the window manager runs
## Where to look in the code
- [`komorebi/src/backend/mod.rs`](../../komorebi/src/backend/mod.rs): the trait.
- [`komorebi/src/backend/fake.rs`](../../komorebi/src/backend/fake.rs): the fake and its
- [`komorebi-linux/src/backend/mod.rs`](../../../komorebi-linux/src/backend/mod.rs): the trait.
- [`komorebi-linux/src/backend/fake.rs`](../../../komorebi-linux/src/backend/fake.rs): the fake and its
tests.
- [`komorebi/src/core`](../../komorebi/src/core/mod.rs): the vocabulary the rest is written
- [`komorebi-linux/src/core/mod.rs`](../../../komorebi-linux/src/core/mod.rs): the vocabulary the rest is written
in.
- [`komorebi/src/workspace.rs`](../../komorebi/src/workspace.rs): tiling, in
- [`komorebi-linux/src/workspace.rs`](../../../komorebi-linux/src/workspace.rs): tiling, in
`Workspace::update`.
- [`komorebi/src/monitor.rs`](../../komorebi/src/monitor.rs): the work area, padding and
- [`komorebi-linux/src/monitor.rs`](../../../komorebi-linux/src/monitor.rs): the work area, padding and
offset a monitor gives the workspace it shows.
- [`komorebi/src/static_config.rs`](../../komorebi/src/static_config.rs): `komorebi.json`.
[`komorebi/tests/config.rs`](../../komorebi/tests/config.rs) loads files over the fake
desktop, [`komorebi/tests/config_displays.rs`](../../komorebi/tests/config_displays.rs) one
- [`komorebi-linux/src/static_config.rs`](../../../komorebi-linux/src/static_config.rs): `komorebi.json`.
[`komorebi-linux/tests/config.rs`](../../../komorebi-linux/tests/config.rs) loads files over the fake
desktop, [`komorebi-linux/tests/config_displays.rs`](../../../komorebi-linux/tests/config_displays.rs) one
with several monitors, [`komorebi-daemon/tests/linux_hot_reload.rs`](../../../komorebi-daemon/tests/linux_hot_reload.rs) the
daemon following a file, and
[`komorebi/tests/config_parity.rs`](../../komorebi/tests/config_parity.rs) the files of other
[`komorebi-linux/tests/config_parity.rs`](../../../komorebi-linux/tests/config_parity.rs) the files of other
platforms and the example, which load;
[`komorebi/tests/replace_configuration.rs`](../../komorebi/tests/replace_configuration.rs)
[`komorebi-linux/tests/replace_configuration.rs`](../../../komorebi-linux/tests/replace_configuration.rs)
the `ReplaceConfiguration` message;
[`komorebi/tests/workspace_rules.rs`](../../komorebi/tests/workspace_rules.rs) the workspace
rules; [`komorebi/tests/schemas.rs`](../../komorebi/tests/schemas.rs) the schemas the daemon answers
with; [`schema.json`](../../schema.json), [`schema.asc.json`](../../schema.asc.json) and
[`nix/komorebi-options.nix`](../../nix/komorebi-options.nix), which are generated;
[`nix/tests/default.nix`](../../nix/tests/default.nix) and
[`nix/tests/komorebi-example.nix`](../../nix/tests/komorebi-example.nix), the check of the options
and the example it evaluates them against; [`komorebi/tests/asc.rs`](../../komorebi/tests/asc.rs)
the applications files; [`komorebi/src/core/asc.rs`](../../komorebi/src/core/asc.rs) their
[`komorebi-linux/tests/workspace_rules.rs`](../../../komorebi-linux/tests/workspace_rules.rs) the workspace
rules; [`komorebi-linux/tests/schemas.rs`](../../../komorebi-linux/tests/schemas.rs) the schemas the daemon answers
with; [`schemas/linux/schema.json`](../../../schemas/linux/schema.json), [`schemas/linux/schema.asc.json`](../../../schemas/linux/schema.asc.json) and
[`nix/linux/komorebi-options.nix`](../../../nix/linux/komorebi-options.nix), which are generated;
[`nix/linux/tests/default.nix`](../../../nix/linux/tests/default.nix) and
[`nix/linux/tests/komorebi-example.nix`](../../../nix/linux/tests/komorebi-example.nix), the check of the options
and the example it evaluates them against; [`komorebi-linux/tests/asc.rs`](../../../komorebi-linux/tests/asc.rs)
the applications files; [`komorebi-linux/src/core/asc.rs`](../../../komorebi-linux/src/core/asc.rs) their
format.
- [`komorebi/src/check.rs`](../../komorebi/src/check.rs): the checks of `komorebic check`, with
- [`komorebi-linux/src/check.rs`](../../../komorebi-linux/src/check.rs): the checks of `komorebic check`, with
their tests; [`komorebic/tests/linux_check.rs`](../../../komorebic/tests/linux_check.rs) runs the command on
configurations, on key binding files and on buses that are not there, and reads what it prints
and its exit status;
[`nix/tests/vm/suites/check`](../../nix/tests/vm/suites/check/test.py), the desktop check against
[`nix/linux/tests/vm/suites/check/test.py`](../../../nix/linux/tests/vm/suites/check/test.py), the desktop check against
a real KWin, with the daemon running, with its script gone, with no daemon and with no KWin.
- [`komorebi/src/process_event.rs`](../../komorebi/src/process_event.rs): what each event
- [`komorebi-linux/src/process_event.rs`](../../../komorebi-linux/src/process_event.rs): what each event
does, and the thread that handles them.
- [`komorebi/src/process_command.rs`](../../komorebi/src/process_command.rs): the socket, what
- [`komorebi-linux/src/process_command.rs`](../../../komorebi-linux/src/process_command.rs): the socket, what
each message does, and the tests that send messages through a real socket.
- [`komorebi-client/src/lib.rs`](../../komorebi-client/src/lib.rs): the client side of the
- [`komorebi-client/src/lib.rs`](../../../komorebi-client/src/lib.rs): the client side of the
socket.
- [`komorebi-client/tests/linux_subscribe.rs`](../../../komorebi-client/tests/linux_subscribe.rs):
subscribers and the notifications they are sent, through real sockets.
- [`komorebic/src/linux/mod.rs`](../../../komorebic/src/linux/mod.rs): the subcommands, and
[`komorebic/tests/linux_cli.rs`](../../../komorebic/tests/linux_cli.rs), what each writes on the socket.
- [`komorebi/src/kwin/mod.rs`](../../komorebi/src/kwin/mod.rs): the KWin backend, its D-Bus
- [`komorebi-linux/src/kwin/mod.rs`](../../../komorebi-linux/src/kwin/mod.rs): the KWin backend, its D-Bus
service and the held call.
- [`komorebi/src/kwin/state.rs`](../../komorebi/src/kwin/state.rs): the table, with the
- [`komorebi-linux/src/kwin/state.rs`](../../../komorebi-linux/src/kwin/state.rs): the table, with the
shapes of the bridge's events, and its tests.
- [`komorebi/src/kwin/bridge.js`](../../komorebi/src/kwin/bridge.js): the bridge, with the
- [`komorebi-linux/src/kwin/bridge.js`](../../../komorebi-linux/src/kwin/bridge.js): the bridge, with the
types of its messages; [`kwin-api.d.ts`] and
[`tsconfig.json`](../../komorebi/src/kwin/tsconfig.json), what `tsc` checks it against;
[`tsconfig.json`](../../../komorebi-linux/src/kwin/tsconfig.json), what `tsc` checks it against;
[`bridge.test.js`], its tests; [`fixtures`], the messages both sides' tests read.
- [`nix/tests/vm/suites/kwin-events`](../../nix/tests/vm/suites/kwin-events/test.py): the
- [`nix/linux/tests/vm/suites/kwin-events/test.py`](../../../nix/linux/tests/vm/suites/kwin-events/test.py): the
events of a real KWin, through the daemon.
- [`nix/tests/vm/suites/core-e2e`](../../nix/tests/vm/suites/core-e2e/test.py): the daemon
- [`nix/linux/tests/vm/suites/core-e2e/test.py`](../../../nix/linux/tests/vm/suites/core-e2e/test.py): the daemon
tiling a real KWin, checked against what KWin has, with a window in monocle, and read and
stopped with `komorebic`.
- [`nix/tests/vm/suites/kwin-restart`](../../nix/tests/vm/suites/kwin-restart/test.py): KWin
- [`nix/linux/tests/vm/suites/kwin-restart/test.py`](../../../nix/linux/tests/vm/suites/kwin-restart/test.py): KWin
restarting under the daemon.
- [`nix/kde-rounded-corners.nix`](../../nix/kde-rounded-corners.nix): the build of the KWin
- [`nix/linux/kde-rounded-corners.nix`](../../../nix/linux/kde-rounded-corners.nix): the build of the KWin
effect that draws an outline around each window, with
[`komorebi-border-colours.patch`](../../nix/kde-rounded-corners/komorebi-border-colours.patch),
[`komorebi-border-colours.patch`](../../../nix/linux/kde-rounded-corners/komorebi-border-colours.patch),
which lets komorebi give each window a color;
[`nix/kwin-effect-geometry-change.nix`](../../nix/kwin-effect-geometry-change.nix), the
[`nix/linux/kwin-effect-geometry-change.nix`](../../../nix/linux/kwin-effect-geometry-change.nix), the
effect that animates a window going to its place, with
[`curve.patch`](../../nix/kwin-effect-geometry-change/curve.patch), which makes its easing
[`curve.patch`](../../../nix/linux/kwin-effect-geometry-change/curve.patch), which makes its easing
curve a setting; and
[`nix/tests/effects.nix`](../../nix/tests/effects.nix), the checks of the files each effect
[`nix/linux/tests/effects.nix`](../../../nix/linux/tests/effects.nix), the checks of the files each effect
package installs.
- [`komorebi/tests/borders.rs`](../../komorebi/tests/borders.rs) and
[`komorebi/tests/border_commands.rs`](../../komorebi/tests/border_commands.rs): the room a drawn
- [`komorebi-linux/tests/borders.rs`](../../../komorebi-linux/tests/borders.rs) and
[`komorebi-linux/tests/border_commands.rs`](../../../komorebi-linux/tests/border_commands.rs): the room a drawn
border takes, and the messages that set the border, against the fake;
[`komorebi/tests/animation.rs`](../../komorebi/tests/animation.rs), the messages that set the
animation, [`komorebi/tests/animation_config.rs`](../../komorebi/tests/animation_config.rs), its
key of the file, and [`komorebi/tests/animation_stack.rs`](../../komorebi/tests/animation_stack.rs),
the stack commands that turn it off; [`komorebi/tests/themes.rs`](../../komorebi/tests/themes.rs),
a named theme and [`komorebi/tests/theme_config.rs`](../../komorebi/tests/theme_config.rs), the
colors and the theme of the file; [`komorebi/tests/focus_follows_mouse.rs`](../../komorebi/tests/focus_follows_mouse.rs),
focus follows mouse; [`komorebi/tests/transparency.rs`](../../komorebi/tests/transparency.rs)
and [`komorebi/tests/transparency_config.rs`](../../komorebi/tests/transparency_config.rs),
transparency and its keys of the file; [`komorebi/tests/border_colours.rs`](../../komorebi/tests/border_colours.rs) and
[`komorebi/tests/borders_off.rs`](../../komorebi/tests/borders_off.rs), the color of each
[`komorebi-linux/tests/animation.rs`](../../../komorebi-linux/tests/animation.rs), the messages that set the
animation, [`komorebi-linux/tests/animation_config.rs`](../../../komorebi-linux/tests/animation_config.rs), its
key of the file, and [`komorebi-linux/tests/animation_stack.rs`](../../../komorebi-linux/tests/animation_stack.rs),
the stack commands that turn it off; [`komorebi-linux/tests/themes.rs`](../../../komorebi-linux/tests/themes.rs),
a named theme and [`komorebi-linux/tests/theme_config.rs`](../../../komorebi-linux/tests/theme_config.rs), the
colors and the theme of the file; [`komorebi-linux/tests/focus_follows_mouse.rs`](../../../komorebi-linux/tests/focus_follows_mouse.rs),
focus follows mouse; [`komorebi-linux/tests/transparency.rs`](../../../komorebi-linux/tests/transparency.rs)
and [`komorebi-linux/tests/transparency_config.rs`](../../../komorebi-linux/tests/transparency_config.rs),
transparency and its keys of the file; [`komorebi-linux/tests/border_colours.rs`](../../../komorebi-linux/tests/border_colours.rs) and
[`komorebi-linux/tests/borders_off.rs`](../../../komorebi-linux/tests/borders_off.rs), the color of each
window's border, and none with borders off;
[`nix/tests/vm/suites/look`](../../nix/tests/vm/suites/look/test.py), the border in a real
[`nix/linux/tests/vm/suites/look/test.py`](../../../nix/linux/tests/vm/suites/look/test.py), the border in a real
Plasma session, read from the pixels of a screenshot, and
[`nix/tests/vm/suites/features`](../../nix/tests/vm/suites/features/test.py), the colors of the
kinds of window; [`nix/tests/vm/suites/focus-follows-mouse`](../../nix/tests/vm/suites/focus-follows-mouse/test.py),
focus follows mouse with a real pointer, which [`Pointer`](../../nix/tests/vm/lib/komorebi_vm/pointer.py)
moves from inside the guest; [`komorebi/tests/wallpaper.rs`](../../komorebi/tests/wallpaper.rs), the
[`nix/linux/tests/vm/suites/features/test.py`](../../../nix/linux/tests/vm/suites/features/test.py), the colors of the
kinds of window; [`nix/linux/tests/vm/suites/focus-follows-mouse/test.py`](../../../nix/linux/tests/vm/suites/focus-follows-mouse/test.py),
focus follows mouse with a real pointer, which [`Pointer`](../../../nix/linux/tests/vm/lib/komorebi_vm/pointer.py)
moves from inside the guest; [`komorebi-linux/tests/wallpaper.rs`](../../../komorebi-linux/tests/wallpaper.rs), the
wallpapers and the colors made of them, against the fake; and
[`nix/tests/vm/suites/wallpaper`](../../nix/tests/vm/suites/wallpaper/test.py), against the
[`nix/linux/tests/vm/suites/wallpaper/test.py`](../../../nix/linux/tests/vm/suites/wallpaper/test.py), against the
real Plasma shell.
- [`komorebi/tests/wm_events.rs`](../../komorebi/tests/wm_events.rs): the window manager
- [`komorebi-linux/tests/wm_events.rs`](../../../komorebi-linux/tests/wm_events.rs): the window manager
driven end to end against the fake.
- [`komorebi-daemon/tests/linux_socket.rs`](../../../komorebi-daemon/tests/linux_socket.rs): the daemon over its socket,
from its start to a `Stop`.
- [`komorebi/tests/focus.rs`](../../komorebi/tests/focus.rs),
[`komorebi/tests/moving.rs`](../../komorebi/tests/moving.rs) and
[`komorebi/tests/layouts.rs`](../../komorebi/tests/layouts.rs): the focus, move and layout
- [`komorebi-linux/tests/focus.rs`](../../../komorebi-linux/tests/focus.rs),
[`komorebi-linux/tests/moving.rs`](../../../komorebi-linux/tests/moving.rs) and
[`komorebi-linux/tests/layouts.rs`](../../../komorebi-linux/tests/layouts.rs): the focus, move and layout
commands against the fake;
[`komorebi/tests/layout_options.rs`](../../komorebi/tests/layout_options.rs) and
[`komorebi/tests/scrolling.rs`](../../komorebi/tests/scrolling.rs), the layout options and the
scrolling layout; [`komorebi/tests/resize.rs`](../../komorebi/tests/resize.rs), resizing;
[`komorebi/tests/promote.rs`](../../komorebi/tests/promote.rs), promoting;
[`komorebi/tests/float.rs`](../../komorebi/tests/float.rs), floating;
[`komorebi/tests/lock.rs`](../../komorebi/tests/lock.rs), locking;
[`komorebi/tests/floating_layer.rs`](../../komorebi/tests/floating_layer.rs), the layers;
[`komorebi/tests/monocle.rs`](../../komorebi/tests/monocle.rs), the monocle;
[`komorebi/tests/maximize.rs`](../../komorebi/tests/maximize.rs) and
[`komorebi/tests/maximize_commands.rs`](../../komorebi/tests/maximize_commands.rs), maximizing;
[`komorebi/tests/user_maximize.rs`](../../komorebi/tests/user_maximize.rs) and
[`komorebi/tests/user_maximize_cases.rs`](../../komorebi/tests/user_maximize_cases.rs), a window
[`komorebi-linux/tests/layout_options.rs`](../../../komorebi-linux/tests/layout_options.rs) and
[`komorebi-linux/tests/scrolling.rs`](../../../komorebi-linux/tests/scrolling.rs), the layout options and the
scrolling layout; [`komorebi-linux/tests/resize.rs`](../../../komorebi-linux/tests/resize.rs), resizing;
[`komorebi-linux/tests/promote.rs`](../../../komorebi-linux/tests/promote.rs), promoting;
[`komorebi-linux/tests/float.rs`](../../../komorebi-linux/tests/float.rs), floating;
[`komorebi-linux/tests/lock.rs`](../../../komorebi-linux/tests/lock.rs), locking;
[`komorebi-linux/tests/floating_layer.rs`](../../../komorebi-linux/tests/floating_layer.rs), the layers;
[`komorebi-linux/tests/monocle.rs`](../../../komorebi-linux/tests/monocle.rs), the monocle;
[`komorebi-linux/tests/maximize.rs`](../../../komorebi-linux/tests/maximize.rs) and
[`komorebi-linux/tests/maximize_commands.rs`](../../../komorebi-linux/tests/maximize_commands.rs), maximizing;
[`komorebi-linux/tests/user_maximize.rs`](../../../komorebi-linux/tests/user_maximize.rs) and
[`komorebi-linux/tests/user_maximize_cases.rs`](../../../komorebi-linux/tests/user_maximize_cases.rs), a window
the user maximizes;
[`komorebi/tests/fullscreen.rs`](../../komorebi/tests/fullscreen.rs), a window that goes
[`komorebi-linux/tests/fullscreen.rs`](../../../komorebi-linux/tests/fullscreen.rs), a window that goes
fullscreen and comes back;
[`komorebi/tests/placement.rs`](../../komorebi/tests/placement.rs) and
[`komorebi/tests/placement_cases.rs`](../../komorebi/tests/placement_cases.rs), the placement
[`komorebi-linux/tests/placement.rs`](../../../komorebi-linux/tests/placement.rs) and
[`komorebi-linux/tests/placement_cases.rs`](../../../komorebi-linux/tests/placement_cases.rs), the placement
rules;
[`komorebi/tests/manage.rs`](../../komorebi/tests/manage.rs), minimizing, closing,
[`komorebi-linux/tests/manage.rs`](../../../komorebi-linux/tests/manage.rs), minimizing, closing,
unmanaging and managing the focused window, and pausing;
[`komorebi/tests/padding.rs`](../../komorebi/tests/padding.rs), the paddings and the work area
offsets; [`komorebi/tests/rules.rs`](../../komorebi/tests/rules.rs) and
[`komorebi/tests/rule_commands.rs`](../../komorebi/tests/rule_commands.rs), the rules and the
[`komorebi-linux/tests/padding.rs`](../../../komorebi-linux/tests/padding.rs), the paddings and the work area
offsets; [`komorebi-linux/tests/rules.rs`](../../../komorebi-linux/tests/rules.rs) and
[`komorebi-linux/tests/rule_commands.rs`](../../../komorebi-linux/tests/rule_commands.rs), the rules and the
messages that add and show them;
[`komorebi/tests/drag_swap.rs`](../../komorebi/tests/drag_swap.rs), dragging a window onto
[`komorebi-linux/tests/drag_swap.rs`](../../../komorebi-linux/tests/drag_swap.rs), dragging a window onto
another tile and onto another monitor;
[`komorebi/tests/drag_resize.rs`](../../komorebi/tests/drag_resize.rs), dragging an edge;
[`komorebi/tests/live_resize.rs`](../../komorebi/tests/live_resize.rs), the neighbors following
[`komorebi-linux/tests/drag_resize.rs`](../../../komorebi-linux/tests/drag_resize.rs), dragging an edge;
[`komorebi-linux/tests/live_resize.rs`](../../../komorebi-linux/tests/live_resize.rs), the neighbors following
it.
- [`nix/tests/vm/suites/scrolling`](../../nix/tests/vm/suites/scrolling/test.py): the scrolling
- [`nix/linux/tests/vm/suites/scrolling/test.py`](../../../nix/linux/tests/vm/suites/scrolling/test.py): the scrolling
strip in a real KWin, with its columns out of view off the screen.
- [`nix/tests/vm/suites/features`](../../nix/tests/vm/suites/features/test.py): what is on the
- [`nix/linux/tests/vm/suites/features/test.py`](../../../nix/linux/tests/vm/suites/features/test.py): what is on the
screen of a real compositing session, read from screenshots.
- [`nix/tests/vm/suites/user-maximize`](../../nix/tests/vm/suites/user-maximize/test.py): a window
- [`nix/linux/tests/vm/suites/user-maximize/test.py`](../../../nix/linux/tests/vm/suites/user-maximize/test.py): a window
the user maximizes, in a real KWin.
- [`nix/tests/vm/suites/placement`](../../nix/tests/vm/suites/placement/test.py): where the
- [`nix/linux/tests/vm/suites/placement/test.py`](../../../nix/linux/tests/vm/suites/placement/test.py): where the
windows of a real KWin go in the layout, by the placement rules of a `komorebi.json`.
- [`nix/tests/vm/suites/commands`](../../nix/tests/vm/suites/commands/test.py): every layout,
- [`nix/linux/tests/vm/suites/commands/test.py`](../../../nix/linux/tests/vm/suites/commands/test.py): every layout,
and every `komorebic` command, against a real KWin with two outputs.
- [`nix/tests/vm/suites/drag-resize`](../../nix/tests/vm/suites/drag-resize/test.py): edges and
- [`nix/linux/tests/vm/suites/drag-resize/test.py`](../../../nix/linux/tests/vm/suites/drag-resize/test.py): edges and
corners dragged with a pointer in a Plasma session;
[`nix/tests/vm/suites/live-resize`](../../nix/tests/vm/suites/live-resize/test.py), the
[`nix/linux/tests/vm/suites/live-resize/test.py`](../../../nix/linux/tests/vm/suites/live-resize/test.py), the
neighbors read while the edge is held.
- [`komorebi/tests/monitor_resize.rs`](../../komorebi/tests/monitor_resize.rs),
[`komorebi/tests/hotplug.rs`](../../komorebi/tests/hotplug.rs) and
[`komorebi/tests/follow_output.rs`](../../komorebi/tests/follow_output.rs): a monitor that
- [`komorebi-linux/tests/monitor_resize.rs`](../../../komorebi-linux/tests/monitor_resize.rs),
[`komorebi-linux/tests/hotplug.rs`](../../../komorebi-linux/tests/hotplug.rs) and
[`komorebi-linux/tests/follow_output.rs`](../../../komorebi-linux/tests/follow_output.rs): a monitor that
changes size, monitors that are unplugged and plugged in, and windows that move to another
output, against the fake;
[`nix/tests/vm/suites/hotplug`](../../nix/tests/vm/suites/hotplug/test.py), both against a real
[`nix/linux/tests/vm/suites/hotplug/test.py`](../../../nix/linux/tests/vm/suites/hotplug/test.py), both against a real
KWin with two outputs.
- [`komorebi/tests/wake.rs`](../../komorebi/tests/wake.rs): the desktop after a wake, against the
fake; [`komorebi/tests/power.rs`](../../komorebi/tests/power.rs), the signals of logind and
- [`komorebi-linux/tests/wake.rs`](../../../komorebi-linux/tests/wake.rs): the desktop after a wake, against the
fake; [`komorebi-linux/tests/power.rs`](../../../komorebi-linux/tests/power.rs), the signals of logind and
of the lock screen, on private buses;
[`nix/tests/vm/suites/lock-sleep`](../../nix/tests/vm/suites/lock-sleep/test.py), the lock
[`nix/linux/tests/vm/suites/lock-sleep/test.py`](../../../nix/linux/tests/vm/suites/lock-sleep/test.py), the lock
screen of a real Plasma session.
- [`komorebi/tests/workspaces.rs`](../../komorebi/tests/workspaces.rs): workspaces as the
- [`komorebi-linux/tests/workspaces.rs`](../../../komorebi-linux/tests/workspaces.rs): workspaces as the
fake's desktops;
[`komorebi/tests/workspace_commands.rs`](../../komorebi/tests/workspace_commands.rs), naming,
[`komorebi-linux/tests/workspace_commands.rs`](../../../komorebi-linux/tests/workspace_commands.rs), naming,
cycling and the other workspace commands;
[`komorebi/tests/monitors.rs`](../../komorebi/tests/monitors.rs), two monitors: crossing from
one to the other, the monitor commands and `EagerFocus`; [`komorebi/src/kwin/kwinrc.rs`](../../komorebi/src/kwin/kwinrc.rs), the
[`komorebi-linux/tests/monitors.rs`](../../../komorebi-linux/tests/monitors.rs), two monitors: crossing from
one to the other, the monitor commands and `EagerFocus`; [`komorebi-linux/src/kwin/kwinrc.rs`](../../../komorebi-linux/src/kwin/kwinrc.rs), the
`kwinrc` editor and its tests.
- [`komorebi/tests/stacks.rs`](../../komorebi/tests/stacks.rs): stacking, unstacking and the windows
- [`komorebi-linux/tests/stacks.rs`](../../../komorebi-linux/tests/stacks.rs): stacking, unstacking and the windows
a stack hides, the behavior of new windows and the float override, against the fake;
[`nix/tests/vm/suites/stacks`](../../nix/tests/vm/suites/stacks/test.py), the same in a real
[`nix/linux/tests/vm/suites/stacks/test.py`](../../../nix/linux/tests/vm/suites/stacks/test.py), the same in a real
KWin, with the parking desktop, a crash and a stop.
- [`nix/tests/vm/suites/workspace-rules`](../../nix/tests/vm/suites/workspace-rules/test.py):
- [`nix/linux/tests/vm/suites/workspace-rules/test.py`](../../../nix/linux/tests/vm/suites/workspace-rules/test.py):
workspace rules sending windows to other workspaces of a real KWin, out of sight on the parking
desktop until the workspace is shown.
- [`nix/tests/vm/suites/workspace-switch`](../../nix/tests/vm/suites/workspace-switch/test.py):
- [`nix/linux/tests/vm/suites/workspace-switch/test.py`](../../../nix/linux/tests/vm/suites/workspace-switch/test.py):
workspaces as a real KWin's desktops, switched by `komorebic` and by KWin;
[`nix/tests/vm/suites/kwin-contract`](../../nix/tests/vm/suites/kwin-contract/test.py), the
[`nix/linux/tests/vm/suites/kwin-contract/test.py`](../../../nix/linux/tests/vm/suites/kwin-contract/test.py), the
behavior of KWin's per-output virtual desktops komorebi relies on, with two outputs and no
komorebi.
- [`komorebi-hotkeys/src/lib.rs`](../../komorebi-hotkeys/src/lib.rs): the key binding model,
[`komorebi-hotkeys/src/qt.rs`](../../komorebi-hotkeys/src/qt.rs) the keys, and one module per
format, [`skhd.rs`](../../komorebi-hotkeys/src/skhd.rs),
[`whkd.rs`](../../komorebi-hotkeys/src/whkd.rs) and
[`sxhkd.rs`](../../komorebi-hotkeys/src/sxhkd.rs);
[`plan.rs`](../../komorebi-hotkeys/src/plan.rs) and [`kde.rs`](../../komorebi-hotkeys/src/kde.rs)
for the shortcuts, [`engine.rs`](../../komorebi-hotkeys/src/engine.rs) for the engine.
- [`komorebi-hotkeys/src/lib.rs`](../../../komorebi-hotkeys/src/lib.rs): the key binding model,
[`komorebi-hotkeys/src/qt.rs`](../../../komorebi-hotkeys/src/qt.rs) the keys, and one module per
format, [`skhd.rs`](../../../komorebi-hotkeys/src/skhd.rs),
[`whkd.rs`](../../../komorebi-hotkeys/src/whkd.rs) and
[`sxhkd.rs`](../../../komorebi-hotkeys/src/sxhkd.rs);
[`plan.rs`](../../../komorebi-hotkeys/src/plan.rs) and [`kde.rs`](../../../komorebi-hotkeys/src/kde.rs)
for the shortcuts, [`engine.rs`](../../../komorebi-hotkeys/src/engine.rs) for the engine.
- [`komorebic/src/linux/hotkeys.rs`](../../../komorebic/src/linux/hotkeys.rs): `export-kde-shortcuts` and
`hotkeys compile`, and the key bindings section of `komorebic check`;
[`komorebic/tests/linux_hotkeys.rs`](../../../komorebic/tests/linux_hotkeys.rs), what they write.
- [`nix/tests/vm/suites/keys-static`](../../nix/tests/vm/suites/keys-static/test.py): static
- [`nix/linux/tests/vm/suites/keys-static/test.py`](../../../nix/linux/tests/vm/suites/keys-static/test.py): static
shortcuts run by a real KWin.
- [`komorebi/src/kwin/hotkeys.rs`](../../komorebi/src/kwin/hotkeys.rs): the engine against
- [`komorebi-linux/src/kwin/hotkeys.rs`](../../../komorebi-linux/src/kwin/hotkeys.rs): the engine against
kglobalaccel, and
[`nix/tests/vm/suites/keys-engine`](../../nix/tests/vm/suites/keys-engine/test.py), keys
[`nix/linux/tests/vm/suites/keys-engine/test.py`](../../../nix/linux/tests/vm/suites/keys-engine/test.py), keys
pressed in a real KWin with the daemon running;
[`nix/tests/vm/suites/restart-survival`](../../nix/tests/vm/suites/restart-survival/test.py),
[`nix/linux/tests/vm/suites/restart-survival/test.py`](../../../nix/linux/tests/vm/suites/restart-survival/test.py),
the keys when the daemon and KWin go away.
- [`komorebi-hotkeys/tests`](../../komorebi-hotkeys/tests): the corpus test and the comparison
- [`komorebi-hotkeys/tests`](../../../komorebi-hotkeys/tests): the corpus test and the comparison
with `whkd-parser`.
- [`nix/tests/keybindings.nix`](../../nix/tests/keybindings.nix): `keybindings-fixtures`, and
[`nix/tests/vm/keys-corpus.py`](../../nix/tests/vm/keys-corpus.py), the corpus case `vm`
- [`nix/linux/tests/keybindings.nix`](../../../nix/linux/tests/keybindings.nix): `keybindings-fixtures`, and
[`nix/linux/tests/vm/keys-corpus.py`](../../../nix/linux/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),
- [`nix/linux/nixos-module.nix`](../../../nix/linux/nixos-module.nix): the NixOS module;
[`nix/linux/supported-kwin.nix`](../../../nix/linux/supported-kwin.nix), the KWin versions it checks;
[`nix/linux/tests/nixos-module.nix`](../../../nix/linux/tests/nixos-module.nix), its scenarios, evaluated in
real NixOS systems; and [`nix/linux/tests/vm/suites/module/test.py`](../../../nix/linux/tests/vm/suites/module/test.py),
a Plasma session in which the module's unit runs the daemon.
- [`scripts/compare-gen.py`](../../scripts/compare-gen.py): writes the tables of
- [`scripts/linux/compare-gen.py`](../../../scripts/linux/compare-gen.py): writes the tables of
[COMPARE.md](COMPARE.md) from this checkout and from checkouts of komorebi for Windows and
komorebi for Mac, and checks them. Continuous integration has neither checkout and does not run
it.
- [`scripts/wsl2-probe.sh`](../../scripts/wsl2-probe.sh), wrapped by
[`nix/dev/wsl2-probe.nix`](../../nix/dev/wsl2-probe.nix): probes a NixOS-WSL2 machine for KVM,
- [`scripts/linux/wsl2-probe.sh`](../../../scripts/linux/wsl2-probe.sh), wrapped by
[`nix/linux/dev/wsl2-probe.nix`](../../../nix/linux/dev/wsl2-probe.nix): probes a NixOS-WSL2 machine for KVM,
WSLg, a GPU and RDP ([wsl2-probe.md](wsl2-probe.md)). The flake checks `wsl2-probe` (ShellCheck
over the script and over the guest's init) and `wsl2-probe-dry-run` (the script's `--dry-run` in
the build sandbox) keep it building.
+7 -7
View File
@@ -2,7 +2,7 @@
[COMPARE.md](COMPARE.md) compares komorebi for KDE Plasma (kfde) with komorebi for Windows (kfw)
from their sources. This document compares them from running them: the scenarios in
`nix/tests/vm/lib/komorebi_vm/core/scenarios` are written once, against the `Platform` of
`nix/linux/tests/vm/lib/komorebi_vm/core/scenarios` are written once, against the `Platform` of
[vm-tests.md](vm-tests.md), and run on a real KWin and on a real Windows 11 desktop. A scenario that
passes on both says the two ports behave the same in that respect, as far as the scenario looks. A
scenario that fails on one says where they differ, and is a finding to look into, not an assertion
@@ -16,7 +16,7 @@ runs, and goes stale when the code changes.
- **kfde**: the suites of this repository, run on 2026-10-29 on a Windows 11 machine's WSL 2 (a
Ryzen 9 5900X, nested KVM), at `scale` 1.5.
- **kfw**: a Windows 11 guest under QEMU on the same machine, running kfw's daemon, driven from
kfw's tree with a copy of `core/` that `scripts/sync-e2e-core` keeps in step. These results were
kfw's tree with a copy of `core/` that `scripts/linux/sync-e2e-core` keeps in step. These results were
reported by the session that ran them, and are not repeated here. The guest is a Windows 11
evaluation image. Its display driver was the basic one for the scenarios that have run; a second
display, added and removed while it runs, has since worked with a QXL device and Red Hat's signed
@@ -73,13 +73,13 @@ and the cause is not known.
## What the last runs said
The table above says what each scenario checks. This one is made from the runs themselves, by
`scripts/scenario-status`, from the logs of the suites on KDE and the result files of kfw
`scripts/linux/scenario-status`, from the logs of the suites on KDE and the result files of kfw
(`result.json` for each scenario), so it says what happened and not what somebody wrote. A scenario
a run did not include shows as `-`; kfw's counts are of the checks labelled `shared`. Regenerate
it after a run:
```sh
scripts/scenario-status --kde LOG... --windows DIR --update docs/dev/BEHAVIOUR.md
scripts/linux/scenario-status --kde LOG... --windows DIR --update docs/linux/dev/BEHAVIOUR.md
```
<!-- scenario-status:begin -->
@@ -173,7 +173,7 @@ from the enum rather than the hand-written deserializer, describes the type as o
description of the case and the reason, and records the case that way, whether the daemon does not
start or puts the windows elsewhere. The other four cases give the same order on both ports.
Fixed upstream in kfw (`3b424dd7`: accept an integer as well as a string, and a schema written by hand);
kfde already had the same fix, and its unit test is in `komorebi/src/core/mod.rs`. A Windows run
kfde already had the same fix, and its unit test is in `komorebi-linux/src/core/mod.rs`. A Windows run
of kfw's `next` passes all 5 cases.
**`hotplug` on kfw (fixed upstream).** After a display is unplugged, Windows reports one display within a second,
@@ -244,7 +244,7 @@ window it did not have again as a `Show` on a title change, so that a rule on th
decided (windows are often announced before their title is set), and a window that renamed itself
away from an ignore rule was tiled. The `title_rule` scenario found the difference (kfw's first
Windows run: the window was never managed). The decision is that the ports match, and kfde changed:
`WindowManagerEvent::TitleUpdate` does nothing, the unit tests in `komorebi/tests/rule_commands.rs`
`WindowManagerEvent::TitleUpdate` does nothing, the unit tests in `komorebi-linux/tests/rule_commands.rs`
say so, and `title_rule` asserts it on both ports. Passes on a real KWin (5 checks). The price on
KDE: a window that opens with no title and gets one later is decided by the rules on the empty
title only.
@@ -314,7 +314,7 @@ set of five had one run lose its agent for over a minute, mid-sweep, which nothi
## Does a broken daemon turn them red
On kfde, with a real KWin: `komorebi/src/workspace.rs` was changed, for one run and never
On kfde, with a real KWin: `komorebi-linux/src/workspace.rs` was changed, for one run and never
committed, to make every tile 200 pixels too wide after the layout is calculated, so that tiles
overlap. `core-e2e` failed 7 checks and passed 139: the overlap checks of the suite's own first
tiling and of the `tiling` scenario (two each), the one in the suite that says two windows share
+19 -19
View File
@@ -295,7 +295,7 @@ window in the task manager would leave the monitor showing the parking desktop,
on it but hidden windows. The table sends the monitor straight back to the desktop it showed
before, and the window's own focus change then brings it to the front of its stack.
komorebi keeps a table of the windows it hid, [`HIDDEN_WINDOWS`](../../komorebi/src/lib.rs), and
komorebi keeps a table of the windows it hid, [`HIDDEN_WINDOWS`](../../../komorebi-linux/src/lib.rs), and
records a window in it before it asks the backend to hide it. What the compositor reports about a
hidden window (a minimize, a move to another desktop) is the echo of a command komorebi sent, and
the window manager has to be able to tell that from the user's own: a window that the user
@@ -304,9 +304,9 @@ minimizes leaves the layout, and one komorebi hid does not.
## Why is the monocle container not one of the containers?
Because a layout gives every container a tile, and the monocle container is the one that has the
whole work area. [`Workspace::new_monocle_container`](../../komorebi/src/workspace.rs) takes the
whole work area. [`Workspace::new_monocle_container`](../../../komorebi-linux/src/workspace.rs) takes the
focused container out of the workspace's containers and remembers its index, and
[`Workspace::update`](../../komorebi/src/workspace.rs) puts the window of the monocle container on
[`Workspace::update`](../../../komorebi-linux/src/workspace.rs) puts the window of the monocle container on
the work area and gives the other containers no tile. The container is taken out and put back
with the plain remove and insert of the ring, and not the ones that respect locked containers:
the comments of the code say that a monocle, like a maximize, takes over the whole screen before
@@ -325,7 +325,7 @@ adjustment of the container in monocle would be lost when it came back (the comm
Because KWin has a maximize of its own, and komorebi asks for it. The window gets the work area of
its output with the panels left alone, and a restore goes back to where the window was
(see the comment in the bridge where it carries the command out). It is the work
area and not the padded one that [`Workspace::update`](../../komorebi/src/workspace.rs) maximizes
area and not the padded one that [`Workspace::update`](../../../komorebi-linux/src/workspace.rs) maximizes
a window to ("the compositor's own maximize, which is the work area and not the padded one"), so
the window cannot be a container: a layout would give it a tile, less the padding. It is held in
`maximized_window` instead, with the index it came from, and when it is restored it goes back to
@@ -383,11 +383,11 @@ script that is still in KWin when its daemon is gone is a warning, since startin
replaces it. The check tells which of the three it is by connecting to the daemon's socket and by
asking KWin whether it has loaded `komorebi-bridge`.
## Why does `nix/komorebi-options.nix` start with the hash of the schema?
## Why does `nix/linux/komorebi-options.nix` start with the hash of the schema?
Because the check that the options are fresh cannot make them again. `schemars-nixgen` makes
`nix/komorebi-options.nix` from `schema.json`, and it is not in the dev shell or in CI (it is
installed with `cargo install`). `just nixgen` writes the hash of `schema.json` as the first line
`nix/linux/komorebi-options.nix` from `schemas/linux/schema.json`, and it is not in the dev shell or in CI (it is
installed with `cargo install`). `just nixgen` writes the hash of `schemas/linux/schema.json` as the first line
of the file, and the check `schema-fresh` compares that with the hash of the committed schema, and
the schema with what `komorebic static-config-schema` prints. A change to a key that leaves the
schema or the options behind fails the check, with no tool but the build.
@@ -406,7 +406,7 @@ unit do not go together, since the session bus gives its name to one komorebi.
Because 0.10.0 draws its outline in the wrong place on KWin 6.8, the oldest KWin komorebi
supports: about 24 px too low, across the title bar. 0.11.0 is the release that handles the
texture coordinates KWin 6.8 inverted, so
[`nix/kde-rounded-corners.nix`](../../nix/kde-rounded-corners.nix) sets the version and the
[`nix/linux/kde-rounded-corners.nix`](../../../nix/linux/kde-rounded-corners.nix) sets the version and the
source of the nixpkgs package to it ([PLATFORM.md](PLATFORM.md#kwin-effects)). nixpkgs `d3b13ad`
(2026-10-24) has 0.10.0 and `f05535a` (2026-10-27) has 0.11.0, so at time of writing
(2026-10-28) setting them changes nothing. The package still sets them, because the patch that
@@ -427,7 +427,7 @@ default, and its check asserts it, so that an update of the effect cannot change
Because the compositor has the frames, the corners and the shadows of the windows, and komorebi
has none of them. komorebi decides what the windows look like and describes it to the backend as a
`Look` ([`Backend::apply_look`](../../komorebi/src/backend/mod.rs)); on KWin the effect KDE
`Look` ([`Backend::apply_look`](../../../komorebi-linux/src/backend/mod.rs)); on KWin the effect KDE
Rounded Corners draws it, and komorebi writes the effect's settings. The same code that decides the
look then runs against the fake desktop, which records the look it was asked for.
@@ -470,7 +470,7 @@ build every kind falls back to the two colors of the look, and komorebi says so
Because the compositor draws the windows: an animation komorebi made would be a series of frames
asked of KWin, each a command, where the Geometry Change effect animates what is painted, in the
compositor, at the refresh rate of the screen. komorebi tells the effect how long an animation
lasts ([`border_manager::current_look`](../../komorebi/src/border_manager/mod.rs)). That is why
lasts ([`border_manager::current_look`](../../../komorebi-linux/src/border_manager/mod.rs)). That is why
`animation-fps` is accepted and does nothing, and why the frame KWin reports for a window is the
final one from the start of the animation: the effect moves what is painted and not the window
([PLATFORM.md](PLATFORM.md#kwin-effects)).
@@ -485,7 +485,7 @@ resize, and what the window shows does not change.
Because KWin animates with `QEasingCurve`, and a style is a curve KWin has when it is Qt's name
without the "Ease": `EaseInOutSine` is `InOutSine`
([`QtCurve::qt_curve`](../../komorebi/src/core/animation.rs)). A custom cubic Bézier is not
([`QtCurve::qt_curve`](../../../komorebi-linux/src/core/animation.rs)). A custom cubic Bézier is not
one of Qt's curves, and is drawn as an ease out, the kind of curve a window moving to its place
wants. The stock Geometry Change has one curve, an exponential ease out, so komorebi's build of
it reads a `Curve` setting ([PLATFORM.md](PLATFORM.md#the-patches)).
@@ -493,7 +493,7 @@ it reads a `Curve` setting ([PLATFORM.md](PLATFORM.md#the-patches)).
## Why does the window manager keep the opacity it gave each window?
So that the backend is told only what changed. `transparency_manager::apply`
([`transparency_manager.rs`](../../komorebi/src/transparency_manager.rs)) is called after every
([`transparency_manager.rs`](../../../komorebi-linux/src/transparency_manager.rs)) is called after every
event and every message, and most of them change no window's opacity: the window manager keeps
the opacity it gave each window that is not opaque (`WindowManager::opacity_applied`), sends the
difference, makes a window opaque again when it should no longer be see-through (and only if it is
@@ -683,7 +683,7 @@ already as it asked, but the user's title bar does it without komorebi's knowing
stayed a tile would be asked to move at the next retile: the code that reads the windows that are
open when komorebi starts says a window that is already maximized is "the maximized window, not a tile
that would be asked to leave the maximized state". So
[`WindowManager::adopt_maximize_change`](../../komorebi/src/window_manager.rs) takes the window out of
[`WindowManager::adopt_maximize_change`](../../../komorebi-linux/src/window_manager.rs) takes the window out of
the layout as `toggle-maximize` makes a window leave it, and what is asked of the layout does
nothing "until it is restored, by `toggle-maximize` or by the user" (the comment in
`process_command`). Because the report is the same either way, one comparison serves both: a window
@@ -692,7 +692,7 @@ that is, or is not, already the workspace's maximized window changes nothing.
## Why does komorebi leave a fullscreen window alone, and tile the workspace when it comes back?
Because the window covers the monitor on purpose. The comment in
[`Window::set_position`](../../komorebi/src/window.rs) says that "moving it would take it out of
[`Window::set_position`](../../../komorebi-linux/src/window.rs) says that "moving it would take it out of
fullscreen, or be ignored", and that "it goes back to its tile when it leaves fullscreen". The
window stays in its container, so the other windows are tiled as if it were not fullscreen, and
every move the window manager makes goes through `set_position`, which is where the window is
@@ -700,13 +700,13 @@ skipped. When the window comes back, "KWin gives it the frame it had before, whi
tile it has now" (the comment in `handle_event`), so the workspace is tiled again. The bridge's
second request for a position gives up after three tries for the same reason: so that a window that
cannot go where it was asked, "a fullscreen one, say", is left alone rather than chased (the comment
on `settle` in [`bridge.js`](../../komorebi/src/kwin/bridge.js)).
on `settle` in [`bridge.js`](../../../komorebi-linux/src/kwin/bridge.js)).
## Why does `initial_window_placement_rules` take a number as well as text?
Because the documentation of the setting shows a number (`"initial_window_placement_rules": 3`),
and a JSON object's keys can only be text: the doc comment on the `Deserialize` of
[`PlacementTarget`](../../komorebi/src/core/mod.rs) says both. The place is read from `"Primary"`,
[`PlacementTarget`](../../../komorebi-linux/src/core/mod.rs) says both. The place is read from `"Primary"`,
`"3"` and `3`, so the form the page shows works as well as the form a map's keys force. In komorebi
for Windows, at its commit 83c4e11d, the deserializer reads only text, so the number its page shows
is refused. [The page of this repository](../initial-window-placement-rules.md#on-kde) says which
@@ -714,8 +714,8 @@ forms are read.
The JSON schema of the type is written by hand, so that it says the same. The one `schemars`
derives for the enum is an object with a `Placement` or an `Index` key, which the comment on the
`JsonSchema` impl of [`PlacementTarget`](../../komorebi/src/core/mod.rs) calls "not what
`Serialize` and `Deserialize` read and write". The schema `schema.json` has says a name, a number,
`JsonSchema` impl of [`PlacementTarget`](../../../komorebi-linux/src/core/mod.rs) calls "not what
`Serialize` and `Deserialize` read and write". The schema `schemas/linux/schema.json` has says a name, a number,
or text that is a number, which is also what the module's typed `config` takes.
## Why are the key binding files read by parsers written for komorebi?
@@ -813,7 +813,7 @@ 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
[`nix/linux/supported-kwin.nix`](../../../nix/linux/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
+10 -10
View File
@@ -19,7 +19,7 @@ tests of this repository run against the nixpkgs that `flake.lock` pins: at time
- **Session bus**: the D-Bus bus of the session. komorebi and KWin talk over it.
- **KWin**: the compositor and window manager of Plasma, `kwin_wayland`.
- **Script**: a JavaScript program that KWin runs inside itself, through its scripting API.
komorebi's is the **bridge**, [`bridge.js`](../../komorebi/src/kwin/bridge.js).
komorebi's is the **bridge**, [`bridge.js`](../../../komorebi-linux/src/kwin/bridge.js).
- **Output**: KWin's name for a monitor.
- **Desktop**: one of KWin's virtual desktops. Each output shows one; komorebi's workspace `i`
is desktop `i`.
@@ -92,7 +92,7 @@ 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
[`nix/linux/supported-kwin.nix`](../../../nix/linux/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.2, with nixpkgs-unstable `f05535a`). 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
@@ -103,7 +103,7 @@ The repository follows the tip of nixpkgs-unstable, so a newer KWin reaches it w
`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)).
message which run it was and which suites ran ([CONTRIBUTING.md](../CONTRIBUTING.md#the-nixos-module)).
### Wayland
@@ -517,7 +517,7 @@ configuration it has.
What the KWin scripting API offers a script, and what it does not, at time of writing
(2026-10-27). The bridge is written around these, and
[`kwin-api.d.ts`](../../komorebi/src/kwin/kwin-api.d.ts) declares the part of the API it
[`kwin-api.d.ts`](../../../komorebi-linux/src/kwin/kwin-api.d.ts) declares the part of the API it
uses, which `tsc` checks it against with ECMAScript 2016's library and nothing else. Node and
TypeScript are needed only for those checks: in the session the bridge needs KWin alone.
@@ -620,7 +620,7 @@ with two outputs of 1920x1080:
At time of writing (2026-10-27), a real suspend and resume is not tested: the QEMU guests the VM
tests run in have no way to wake from one. The signals are tested on private buses
(`komorebi/tests/power.rs`), and the lock screen against a real KWin in a Plasma session
(`komorebi-linux/tests/power.rs`), and the lock screen against a real KWin in a Plasma session
(`vm-lock-sleep`, which locks and unlocks with `loginctl lock-session` and `unlock-session`).
## How long a retile takes
@@ -651,7 +651,7 @@ patches (see [The patches](#the-patches)):
Each package is in the flake's `packages` for Linux and in `overlays.default`, which builds it
with the `callPackage` of the nixpkgs it is applied to, so that it follows that nixpkgs' KWin.
[`nix/tests/effects.nix`](../../nix/tests/effects.nix) has a check for each, which builds the
[`nix/linux/tests/effects.nix`](../../../nix/linux/tests/effects.nix) has a check for each, which builds the
package and inspects its files the way KWin finds them, without a session.
At time of writing (2026-10-27):
@@ -725,7 +725,7 @@ Each patch is a derivative work of the effect it changes, and is under the same
GNU General Public License version 3; its header states the license and describes the
change. The check of a patched package asserts that the patch is in the build.
[`komorebi-border-colours.patch`](../../nix/kde-rounded-corners/komorebi-border-colours.patch),
[`komorebi-border-colours.patch`](../../../nix/linux/kde-rounded-corners/komorebi-border-colours.patch),
for KDE Rounded Corners, makes two changes:
- **A color for each window.** The stock effect has one outline color for the active window
@@ -745,7 +745,7 @@ for KDE Rounded Corners, makes two changes:
contents change or the window is resized, so a change of opacity alone would not show. The
patched effect redirects the window again when its opacity changes.
[`curve.patch`](../../nix/kwin-effect-geometry-change/curve.patch), for Geometry Change, adds
[`curve.patch`](../../../nix/linux/kwin-effect-geometry-change/curve.patch), for Geometry Change, adds
a `Curve` setting to the effect's group: the name of any of Qt's easing curves (`OutExpo`,
`InOutSine`, ...), read with the effect's other settings and used for every animation. An
unknown or missing name is the stock effect's curve, `OutExpo`. The check asserts that the
@@ -819,7 +819,7 @@ At time of writing (2026-10-27):
### RDP into the session
The session guests to develop in ([utm.md](utm.md)) run KRDP as a user unit of the session,
[`nix/dev/krdp.nix`](../../nix/dev/krdp.nix): `krdpserver --plasma`, which asks KWin for the
[`nix/linux/dev/krdp.nix`](../../../nix/linux/dev/krdp.nix): `krdpserver --plasma`, which asks KWin for the
screen and for input through its own Wayland protocols (KRDP's desktop file lists
`zkde_screencast_unstable_v1` and `org_kde_kwin_fake_input`), so no portal asks the user first. The
unit makes a self-signed certificate, and logs in the session's user with a password the user
@@ -855,7 +855,7 @@ and KRDP 6.8.1 and FreeRDP 3.32.2:
`run-kde` is written for NixOS in WSL 2 on Windows 11 with an AMD CPU and an x86_64 guest, and
nothing in this section has been measured on that machine yet. The table says what the command
expects and what is still to be recorded, as dated facts, from the probe
(`scripts/wsl2-probe.sh`) when somebody runs it there. The facts that were measured on a Linux machine
(`scripts/linux/wsl2-probe.sh`) when somebody runs it there. The facts that were measured on a Linux machine
with KVM and no WSL, window or GPU are in [Rendering in virtual machines and over
RDP](#rendering-in-virtual-machines-and-over-rdp).
+1 -1
View File
@@ -1,6 +1,6 @@
# The contract of a Platform
A shared scenario (`nix/tests/vm/lib/komorebi_vm/core/scenarios`) runs on KDE here and on
A shared scenario (`nix/linux/tests/vm/lib/komorebi_vm/core/scenarios`) runs on KDE here and on
Windows in kfw's guests, through the `Platform` protocol (`core/platform.py`). A check
that one port answers by how its implementation happens to work, and the other by what
the system says, passes on one port for the wrong reason. This file lists what each member
+7 -7
View File
@@ -17,13 +17,13 @@ is, whether it is hidden, how wide it really is) is a call to the backend in kfd
| Commit | What it changes | kfde |
|---|---|---|
| `9ccf2efce` model of a scrollable strip | New crate `komorebi-scrolling`: columns of tiles, widths (proportion or fixed, limits), heights, view offset, centring (`Never`, `Always`, `OnOverflow`), pan, swipe tracker. No Windows code. Tests in the crate. | **Ported by dependency.** `komorebi-scrolling` is a git dependency at the same revision as the layouts. Its tests are upstream's; kfde tests the glue. |
| `abd4fde3e` lay out with the model | The workspace keeps a `ScrollingSpace` keyed by container id; `update()` places containers from it instead of recomputing equal columns from the last layout. | **Ported** (`komorebi/src/scrolling.rs`, `Workspace::update`). |
| `cb127204c` platform-free glue | `komorebi_layouts::scrolling` (options, `place`, `resize`, hand-over between workspaces), `ScrollingCentering` replaces the `bool` of `center_focused_column`; Workspace methods for focus, order, consume, expel, stack. | **Ported:** the layouts half by the bump, the Workspace half in `komorebi/src/scrolling.rs`. |
| `abd4fde3e` lay out with the model | The workspace keeps a `ScrollingSpace` keyed by container id; `update()` places containers from it instead of recomputing equal columns from the last layout. | **Ported** (`komorebi-linux/src/scrolling.rs`, `Workspace::update`). |
| `cb127204c` platform-free glue | `komorebi_layouts::scrolling` (options, `place`, `resize`, hand-over between workspaces), `ScrollingCentering` replaces the `bool` of `center_focused_column`; Workspace methods for focus, order, consume, expel, stack. | **Ported:** the layouts half by the bump, the Workspace half in `komorebi-linux/src/scrolling.rs`. |
| `249709e60` commands and config | Socket messages and `komorebic` commands `consume`, `expel`, `toggle-column-stack`, `scrolling-layout-full-width`, `center-focus`, `expand`; focus, move, resize, retile and close go through the strip. The message says a top level `scrolling` section too. | **Ported**, except the `scrolling` section: neither kfw nor kfde has one (only komorebi for Mac has; COMPARE.md says so). |
| `9ff278eb5` schemas | `center_focused_column` is a boolean or a name; docs for the new commands; `schema.bar.json`. | **Ported:** `schema.json`, `nix/komorebi-options.nix`, `docs/cli/`. `schema.bar.json` is kfw's (kfde has no bar). |
| `9ff278eb5` schemas | `center_focused_column` is a boolean or a name; docs for the new commands; `schema.bar.json`. | **Ported:** `schema.json`, `nix/linux/komorebi-options.nix`, `docs/linux/cli/`. `schema.bar.json` is kfw's (kfde has no bar). |
| `2dff53095` room for windows that will not get narrow | After windows are placed, a window wider than its column widens the column (never narrower again, never wider than the screen), for an overhang of 16 px or more. | **Ported, with a different trigger.** kfde cannot ask a window how wide it is right after moving it: the frame comes back from KWin a moment later. The widths are read at the first layout after the frames have settled (`WIDTH_SETTLE`), as upstream does with animations on. Covered by unit tests in `scrolling.rs`; no VM check, because it needs a client that will not get narrower and foot has no minimum width. |
| `e75f3db47` rest windows at the edge | A window out of view rests at the edge it left by with 5 px on screen and keeps its size. | **Ported** (`parked`). On KDE this also keeps the window from being resized while it moves out of view, which is what KWin pulls back (PLATFORM.md). |
| `ab1896330` docs | `docs/usage/scrolling-layout.md`, `mkdocs.yml`. | **Ported**, rewritten for KDE (no animation, no borders at the edges, no touchpad). |
| `ab1896330` docs | `docs/linux/usage/scrolling-layout.md`, `mkdocs.yml`. | **Ported**, rewritten for KDE (no animation, no borders at the edges, no touchpad). |
| `1531a892a` more than one monitor | Removes the single-monitor restriction; a window out of view past an edge with a monitor next to it is hidden, not parked; a partly visible one is cut to its work area; a window that comes back is shown first, only the one at the front of a stack. | **Ported** (`rest`, `other_monitors`, `should_restore_when_placed`, from `backend().monitors()` and `Window::hide`). kfde never had the restriction. This answers the open question in PLATFORM.md about a strip that spills onto the next monitor. |
| `abb230b45` spread a stack out | The window that stays in the container is restored; focus stays on the column while the containers are inserted. | **Ported.** |
| `ca22b0f81` refocus after Hide | The `Hide` event arm refocuses like `Destroy`. | **Not applicable.** kfde has no `Hide` event: KWin reports a closed window as a destroyed one, which already refocuses. |
@@ -47,15 +47,15 @@ is, whether it is hidden, how wide it really is) is a call to the backend in kfd
## What is tested, and where
- `komorebi/src/scrolling.rs`: the glue against a workspace with no desktop (widths, consume, expel,
- `komorebi-linux/src/scrolling.rs`: the glue against a workspace with no desktop (widths, consume, expel,
moving a column, stacking and spreading out with the windows that are hidden, expanding, panning,
where a window rests, which monitors are the others, what a window that will not get narrow
says). The model itself has its tests in upstream's `komorebi-scrolling`.
- `komorebi/tests/scrolling.rs` and `layout_options.rs`: the commands through
- `komorebi-linux/tests/scrolling.rs` and `layout_options.rs`: the commands through
`WindowManager::process_command` against the fake desktop, a strip next to another monitor, and a
drag of the left edge of a column.
- `komorebic/tests/linux_cli.rs`: each new subcommand sends its message.
- `nix/tests/vm/lib/komorebi_vm/core/scenarios/scrolling.py` (`columns`, shared with komorebi for
- `nix/linux/tests/vm/lib/komorebi_vm/core/scenarios/scrolling.py` (`columns`, shared with komorebi for
Windows), run by `vm-scrolling` and `core-e2e`: where the daemon keeps a window at the edge and the
commands of the columns, in a real session. Run on KDE: the `scrolling` suite passes
(32 checks, with `two_monitors`). KWin leaves a window resting at the left edge with its right edge a few pixels inside the
+9 -9
View File
@@ -18,10 +18,10 @@ The guests of a Mac are `aarch64-linux`. A guest of a Linux host that has no KVM
the runner refuses, because Plasma under software emulation is too slow to try anything.
They are `nixosConfigurations` of the flake, made from
[`nix/dev/plasma-vm.nix`](../../nix/dev/plasma-vm.nix),
[`nix/dev/plasma-utm.nix`](../../nix/dev/plasma-utm.nix) and
[`nix/dev/krdp.nix`](../../nix/dev/krdp.nix), by `mkPlasmaGuest` in
[`flake.nix`](../../flake.nix), which takes the system of the guest and the packages of the machine
[`nix/linux/dev/plasma-vm.nix`](../../../nix/linux/dev/plasma-vm.nix),
[`nix/linux/dev/plasma-utm.nix`](../../../nix/linux/dev/plasma-utm.nix) and
[`nix/linux/dev/krdp.nix`](../../../nix/linux/dev/krdp.nix), by `mkPlasmaGuest` in
[`flake.nix`](../../../flake.nix), which takes the system of the guest and the packages of the machine
that runs QEMU. Each one installs komorebi with the flake's NixOS
module, `services.komorebi`, so the komorebi in a guest is the one of the commit the guest was
built from, and in the session guests the module's unit starts it at login. They carry no key,
@@ -46,7 +46,7 @@ and the builder needs room for it and for its build: the defaults of `darwin.lin
core, 3 GB of memory, a 20 GB disk) are too small. Six cores and 10 GB of memory worked, at time
of writing (2026-10-27).
The examples below use the same variables as `scripts/vm-mac`:
The examples below use the same variables as `scripts/linux/vm-mac`:
```sh
export KOMOREBI_BUILDER=ssh-ng://builder@localhost # the store URL of your builder
@@ -115,7 +115,7 @@ session guest shows nothing on the host, as on a Mac: it is reached over RDP ([b
## The demo guest
`run-kde-x86_64` and `run-kde-aarch64` are the session guest with a demo on it, made by
[`nix/dev/run-kde.nix`](../../nix/dev/run-kde.nix) on top of `plasma-vm.nix`. komorebi is
[`nix/linux/dev/run-kde.nix`](../../../nix/linux/dev/run-kde.nix) on top of `plasma-vm.nix`. komorebi is
configured by the module's typed `config` (eight workspaces with a layout each, borders and
animation) and by the sample key bindings, `docs/skhdrc.sample`, in the module's default mode. At
login the guest opens two Konsole windows, Kate and Dolphin, which komorebi tiles, and a cheat sheet
@@ -171,7 +171,7 @@ the closure is built:
## The command
`run-kde` starts the demo guest on a Linux machine, from a checkout: `nix run .#run-kde -- [options]`,
or `just run-kde [options]`. It is [`scripts/run-kde`](../../scripts/run-kde), which the flake wraps
or `just run-kde [options]`. It is [`scripts/linux/run-kde`](../../../scripts/linux/run-kde), which the flake wraps
with the runner of the machine's guest (`run-kde-x86_64` or `run-kde-aarch64`) written into it, as
`packages.<system>.run-kde` and `apps.<system>.run-kde`. The package names the runner and does not
depend on it, so `nix run` does not fetch 4 GB before the command can say what the machine lacks.
@@ -233,11 +233,11 @@ script reads the machine through variables, so that a test can make up a machine
`RUN_KDE_WSLCONFIG`, besides `WAYLAND_DISPLAY` and `DISPLAY`; and `RUN_KDE_GUEST` and
`RUN_KDE_RUNNER_BIN`, which the package sets, and `RUN_KDE_QEMU_OPTS`, which adds to the options of
QEMU. The checks `run-kde-dry-run` and `run-kde-doctor`
([`nix/tests/run-kde.nix`](../../nix/tests/run-kde.nix)) run it against a WSL 2 with WSLg and a GPU,
([`nix/linux/tests/run-kde.nix`](../../../nix/linux/tests/run-kde.nix)) run it against a WSL 2 with WSLg and a GPU,
one with WSLg and a software OpenGL, one with WSLg and no GPU device, a Linux machine with no
window, `--tcg` with no KVM, and machines that cannot run the guest (no KVM, a KVM the user cannot
open, a `virtiofsd` that exits), a `/dev/fuse` that is missing or closed, and compare the output
with the texts in [`nix/tests/run-kde`](../../nix/tests/run-kde). The check `run-kde` builds the package, which
with the texts in [`nix/linux/tests/run-kde`](../../../nix/linux/tests/run-kde). The check `run-kde` builds the package, which
shellchecks the script.
## The UTM disk
+22 -22
View File
@@ -12,12 +12,12 @@ they are laid out, how to run them, and how to add one.
| CI, `x86_64-linux` | `nix build -L .#checks.x86_64-linux.vm-NAME` | KVM |
| CI, `x86_64-linux`, the weekly canary | the same, with nixpkgs moved to the tip of nixpkgs-unstable | KVM |
| A Linux machine with KVM | `just vm NAME` | KVM |
| A Mac | `just vm NAME`, which runs `scripts/vm-mac` | HVF |
| A Mac | `just vm NAME`, which runs `scripts/linux/vm-mac` | HVF |
| A Linux machine with no KVM | `nix build -L .#legacyPackages.SYSTEM.vmTcg.NAME` | TCG |
CI runs the `fast` tier on every pull request and the `slow` tier on `master`,
every week, and on pull requests labeled `ci:vm-slow`
([`ci.yaml`](../../.github/workflows/ci.yaml)). The slow jobs run the driver
([`ci.yaml`](../../dev/old-ci/linux/workflows/ci.yaml)). The slow jobs run the driver
by hand instead of building the check, so that the screenshots and journals of a
failed run can be uploaded as an artifact. KVM on GitHub-hosted runners is
documented for public repositories; the first step of each VM job checks that
@@ -27,7 +27,7 @@ The `canary` job runs both tiers once more every week, against the tip of
nixpkgs-unstable instead of the nixpkgs `flake.lock` pins: it runs
`nix flake update nixpkgs` in a copy of the checkout, builds every check there,
the suites one after the other on one machine, and opens an issue when one
fails ([`CONTRIBUTING.md`](../../CONTRIBUTING.md#continuous-integration)). It is
fails ([`CONTRIBUTING.md`](../CONTRIBUTING.md#continuous-integration)). It is
how a new KWin or Plasma that breaks a suite is found before the lock moves to
it.
@@ -39,15 +39,15 @@ depends on settings of Windows. `nix run .#wsl2-probe` boots a tiny guest with
and without KVM and times both ([wsl2-probe.md](wsl2-probe.md)).
The suites are what `testedMax` in
[`nix/supported-kwin.nix`](../../nix/supported-kwin.nix) means: the newest KWin
[`nix/linux/supported-kwin.nix`](../../../nix/linux/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)).
([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
[`nix/linux/tests/vm/suites`](../../../nix/linux/tests/vm/suites). The generator in
[`nix/linux/tests/vm/default.nix`](../../../nix/linux/tests/vm/default.nix) lists that
directory, so a new suite is a new directory and nothing else: it appears as
`checks.<system>.vm-NAME` on Linux and as `legacyPackages.<system>.vm.NAME`
everywhere. `legacyPackages.<system>.vmTiers` lists the names of each tier as
@@ -69,7 +69,7 @@ A suite has two files:
## Nodes
`kind` picks a file under
[`nix/tests/vm/nodes`](../../nix/tests/vm/nodes).
[`nix/linux/tests/vm/nodes`](../../../nix/linux/tests/vm/nodes).
Both nodes are built with the NixOS module, as a user's machine is: they import
`nixosModules.default`, which the generator passes to them, and enable
@@ -78,7 +78,7 @@ commit under test. `services.komorebi.logLevel` is `"debug"`, because the tests
read the daemon's debug log. A suite can change either option in its `node`:
`latency`, which times the daemon, runs it at `"info"`.
The checks of the module that need no machine are `nixos-module-eval`
([`nix/tests/nixos-module.nix`](../../nix/tests/nixos-module.nix)), and the
([`nix/linux/tests/nixos-module.nix`](../../../nix/linux/tests/nixos-module.nix)), and the
suite `module` checks its unit in a Plasma session.
`headless` is a machine with Plasma installed and no login. Each KWin a test
@@ -104,7 +104,7 @@ in the session from the start, as on a user's machine; `render-smoke`, which
checks that the session draws, turns it off. It is the node for anything that
needs pixels: `features` reads what komorebi does from screenshots of it. The
choice of login manager is made in
[`nodes/session.nix`](../../nix/tests/vm/nodes/session.nix) and nowhere else;
[`nodes/session.nix`](../../../nix/linux/tests/vm/nodes/session.nix) and nowhere else;
the file says how to switch to sddm, the other one that has been seen to work.
Its display is 1280x800, because screenshots are taken of the machine's one
display device: the `virtio-gpu-pci` that the test driver adds to every aarch64
@@ -119,9 +119,9 @@ On aarch64 under HVF, at time of writing (2026-10-27), the session has the
Wayland socket after 11 to 19 seconds and a painted desktop after 35 seconds.
A suite's `node` can import a module of the repository: `rdp` imports
[`nix/dev/krdp.nix`](../../nix/dev/krdp.nix), the RDP server of the Plasma
[`nix/linux/dev/krdp.nix`](../../../nix/linux/dev/krdp.nix), the RDP server of the Plasma
guests to develop in, so that the suite checks the unit those guests run, and
`run-kde` imports [`nix/dev/run-kde.nix`](../../nix/dev/run-kde.nix), the demo
`run-kde` imports [`nix/linux/dev/run-kde.nix`](../../../nix/linux/dev/run-kde.nix), the demo
guest that the command `run-kde` starts, so that what CI boots is what the
command starts. The node of `run-kde` also makes the directory that the host
shares with that guest (`/run/run-kde`), owned by a user the guest does not
@@ -132,7 +132,7 @@ mounted it. The guests themselves, which stay up for a person to use, are in
## The library
Suites import from `komorebi_vm`, in
[`nix/tests/vm/lib`](../../nix/tests/vm/lib). It does not depend on the test
[`nix/linux/tests/vm/lib`](../../../nix/linux/tests/vm/lib). It does not depend on the test
driver. It depends on the small `Machine` protocol, and its unit tests pass a
fake machine, so the `vm-lib` check tests it without booting anything. The
check also runs `ruff` and `ty` over it. The driver type checks every
@@ -173,7 +173,7 @@ the run.
The scenarios run on two platforms. KDE runs them in `core-e2e`, except `resize` and
`focus_follows_mouse`, which need a pointer and run at the end of `drag-resize`. A
Windows 11 guest under QEMU, which kfw drives from its own tree with this `core/` copied
unchanged (`scripts/sync-e2e-core` keeps the copy in step until `core/` moves there),
unchanged (`scripts/linux/sync-e2e-core` keeps the copy in step until `core/` moves there),
runs all of them against kfw's daemon. [BEHAVIOUR.md](BEHAVIOUR.md) says what each
scenario found on each port, and what turned red when the daemon was deliberately broken.
- `Checks` counts checks and fails once, at the end, so that one failure does
@@ -255,7 +255,7 @@ the run.
guest, milliseconds apart: moves that each wait for the test are seconds
apart, and KWin was seen to lose the horizontal part of such a drag. The
pointer lands within a pixel of where it is asked. The program itself is
[`komorebi_vm/uinput.py`](../../nix/tests/vm/lib/komorebi_vm/uinput.py),
[`nix/linux/tests/vm/lib/komorebi_vm/uinput.py`](../../../nix/linux/tests/vm/lib/komorebi_vm/uinput.py),
whose arithmetic the `vm-lib` check tests.
- `RdpClient(machine, kde)` is FreeRDP's client on an X server of its own, for a
node that runs KRDP: `listening()` asks the guest whether the server has its
@@ -314,7 +314,7 @@ Two traps are worth knowing about before writing a screenshot test:
QEMU has to run on the Mac to use HVF, and the guest is Linux, so the guest's
closure is built on a Linux builder and the driver runs on the Mac. The nix
sandbox on macOS cannot give QEMU the hypervisor, so `scripts/vm-mac` runs the
sandbox on macOS cannot give QEMU the hypervisor, so `scripts/linux/vm-mac` runs the
driver directly instead of building the check.
```sh
@@ -335,9 +335,9 @@ The script prints where the artifacts (screenshots, logs) are, under
## Writing a test
1. Create `nix/tests/vm/suites/NAME/default.nix` and `test.py`. Start from
[`suites/kwin`](../../nix/tests/vm/suites/kwin), or from
[`suites/kwin-events`](../../nix/tests/vm/suites/kwin-events) for a test that
1. Create `nix/linux/tests/vm/suites/NAME/default.nix` and `test.py`. Start from
[`suites/kwin`](../../../nix/linux/tests/vm/suites/kwin), or from
[`suites/kwin-events`](../../../nix/linux/tests/vm/suites/kwin-events) for a test that
runs the daemon.
2. Pick the tier. `fast` suites are the pull request gate and should take
minutes. `slow` suites run on `master` and every week.
@@ -351,7 +351,7 @@ Add `git add -N` for new files first: a flake only sees files git knows about.
## Writing a scenario
A scenario is a function `run(platform, checks, ...)` in
`nix/tests/vm/lib/komorebi_vm/core/scenarios/`. It is what runs on every
`nix/linux/tests/vm/lib/komorebi_vm/core/scenarios/`. It is what runs on every
platform, so it follows four rules:
- It reaches the desktop only through the `Platform`, and the daemon only through
@@ -383,7 +383,7 @@ the fake and fails on KDE has found a bug in the fake, the library or the daemon
- **The daemon is built once, not once per commit.** The VM tests install the daemon built with the
constant commit `nix-check` (`nixosModules.forVmTests`), as the checks do, so a new commit does not
build it again. The version a VM test sees is therefore not the commit. The source of the build
leaves out `nix/tests/vm/`, so editing a test, the library or a fixture does not rebuild it either.
leaves out `nix/linux/tests/vm/`, so editing a test, the library or a fixture does not rebuild it either.
`nix build .#komorebi-full`, and what a user installs, still has the real commit.
- **Each step says how long it took.** `run_suite` prints `[scope] module.function: 12.3 s` after
every step, so a log shows which scenario the time went to.
@@ -417,7 +417,7 @@ with the run's other artifacts. A run without the variable records nothing.
## Looking inside a failed run
`nix build -L` prints the guest's console, and a session test keeps its screenshots. Run the driver by hand, as
`scripts/vm-mac` does, to keep the screenshots. For an interactive session
`scripts/linux/vm-mac` does, to keep the screenshots. For an interactive session
build `driverInteractive` instead of `driver`, run it, and call `start_all()`
and `machine.shell_interact()` at its prompt. In the guest, KWin's own log is
`journalctl --user -u kwin-virtual@NAME` as the test user, and a KWin script's
+4 -4
View File
@@ -237,12 +237,12 @@ when `nixos-rebuild` rejects one, its options page has the current name.
## How the script is checked
The script is `scripts/wsl2-probe.sh` and the flake wraps it
([`nix/dev/wsl2-probe.nix`](../../nix/dev/wsl2-probe.nix)): `packages.<system>.wsl2-probe`
The script is `scripts/linux/wsl2-probe.sh` and the flake wraps it
([`nix/linux/dev/wsl2-probe.nix`](../../../nix/linux/dev/wsl2-probe.nix)): `packages.<system>.wsl2-probe`
and the app of the same name, and `wsl2-probe-guest`, the kernel and the initrd
(with the modules of virtio's PCI transport and of virtiofs).
The initrd's init and the loop are `nix/dev/wsl2-probe-init.sh` and
`nix/dev/wsl2-probe-loop.sh`; the same loop file is what the script times on the
The initrd's init and the loop are `nix/linux/dev/wsl2-probe-init.sh` and
`nix/linux/dev/wsl2-probe-loop.sh`; the same loop file is what the script times on the
machine.
Two checks of the flake keep the script from rotting between the times someone
+3 -3
View File
@@ -98,21 +98,21 @@ of a column.
## How it is tested
- `komorebi/tests/drag_resize.rs`, against the fake desktop: a drag of the split between two
- `komorebi-linux/tests/drag_resize.rs`, against the fake desktop: a drag of the split between two
tiles; a long drag of the narrow right-hand stack of the ultrawide vertical stack; a drag past
what the neighbor can give; a shrink past what the tile can lose; a drag of a window that is
short of its tile, which must not move the divider on its other side; a drag of a window that is
not the focused one; an edge with no neighbor; a drag that changed nothing; a corner; the edge
of a stack; a floating window and the window of a monocle; a drag whose frame had not got to
where the user took the edge when the window manager read the end.
- `komorebi/src/kwin/state.rs`: the end of a resize is the frame the user asked for and a frame
- `komorebi-linux/src/kwin/state.rs`: the end of a resize is the frame the user asked for and a frame
event after it does not change that, the end of a move is the frame, and the frame a drag began
with is kept while the frame changes.
- `vm-drag-resize`, in a Plasma session with a pointer device: edges and corners of three tiles
are dragged with the pointer, and the tiles are checked exactly (the dragged edge moved by what
the pointer moved, the neighbor's with it, nothing else), the frames within a cell of the
terminal's font.
- `komorebi/tests/live_resize.rs`, against the fake desktop: the neighbors follow a drag while it
- `komorebi-linux/tests/live_resize.rs`, against the fake desktop: the neighbors follow a drag while it
goes on and the dragged window is left alone; the same result with steps as without; a drag
taken back; a step with no drag going on; a window that opens part way through.
- `vm-live-resize`, in the same session: the edge is held part way and then all the way, and the
+2 -2
View File
@@ -2,7 +2,7 @@
`komorebi`, and tiling window managers in general, are very complex pieces of software. To make
starting out easier, the repository has an example configuration,
[`docs/komorebi.example.json`](komorebi.example.json), which is kept working: a test loads it with
[`docs/linux/komorebi.example.json`](komorebi.example.json), which is kept working: a test loads it with
every change.
Besides `komorebi.json`, komorebi for KDE is configured by the NixOS module, which installs it and
@@ -89,7 +89,7 @@ each workspace, are there too.
`app_specific_configuration_path` names a file of rules for the applications that need them, which
the repository has a start of in
[`komorebic/applications.json`](../komorebic/applications.json). `komorebic quickstart` puts a copy
[`komorebic/applications.json`](../../komorebic/applications.json). `komorebic quickstart` puts a copy
where the example says, `~/.config/komorebi/applications.json`; a path with no file behind it is
skipped.
[Application specific configuration](usage/application-specific-configuration.md) explains the
+3 -3
View File
@@ -6,7 +6,7 @@ newer ([PLATFORM.md](dev/PLATFORM.md) has what it needs from the session).
On NixOS, the repository's flake has a module that installs both programs and starts komorebi
with every Plasma session. On any other distribution, build them from source, or take the
binaries of a release ([Binaries](../README.md#binaries) says which and what they need).
binaries of a release ([Binaries](README.md#binaries) says which and what they need).
There is no binary cache: the Komorebi license does not allow third parties to redistribute
binaries, so the flake builds komorebi from source on each machine that installs it. On NixOS,
@@ -75,7 +75,7 @@ the repository's `rust-toolchain.toml` selects, whatever nixpkgs your system use
- 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
repository's [`nix/linux/supported-kwin.nix`](../../nix/linux/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`.
@@ -180,7 +180,7 @@ version string builds libgit2, and zlib when the system has none. Then:
```sh
git clone https://github.com/LGUG2Z/komorebi-for-kde
cd komorebi-for-kde
cargo install --locked --path komorebi
cargo install --locked --path komorebi-daemon
cargo install --locked --path komorebic
```
+3 -3
View File
@@ -7,8 +7,8 @@ It is for a Linux machine with KVM, and the steps below are for NixOS in WSL 2 o
is the machine it was written for. Nothing on this page has been run on WSL 2 yet: what was run, and
what was not, is [at the end](#what-is-known).
The virtual machine is the demo guest of [`nix/dev/run-kde.nix`](../nix/dev/run-kde.nix), and the
command that starts it is [`scripts/run-kde`](../scripts/run-kde). [Plasma guests to develop
The virtual machine is the demo guest of [`nix/linux/dev/run-kde.nix`](../../nix/linux/dev/run-kde.nix), and the
command that starts it is [`scripts/linux/run-kde`](../../scripts/linux/run-kde). [Plasma guests to develop
in](dev/utm.md) says how they are made.
## What you need
@@ -154,7 +154,7 @@ between runs, in the state directory.
### The key bindings
komorebi reads the bindings of [`docs/skhdrc.sample`](skhdrc.sample), in the module's default mode,
komorebi reads the bindings of [`docs/linux/skhdrc.sample`](skhdrc.sample), in the module's default mode,
where the daemon handles every binding. Alt is either Alt key. The ones to start with:
| Keys | What they do |
@@ -67,7 +67,7 @@ extension `.json` is read.
## The file komorebi ships
[`komorebic/applications.json`](../../komorebic/applications.json) in the repository has an
[`komorebic/applications.json`](../../../komorebic/applications.json) in the repository has an
entry for KDE Plasma, which floats the calculators of KDE and GNOME, the screenshot tool, the
authentication dialog of Plasma and System Settings. A test loads it, and opens the windows it
names.
+2 -2
View File
@@ -244,8 +244,8 @@ rule of the workspace away and leave it with the layout it has.
## The schema
The Rust types that read `komorebi.json` also describe it as a JSON Schema, which an editor can
check the file against, and which the NixOS module is typed from. [`schema.json`](../../schema.json)
in the repository is the schema of `komorebi.json`, [`schema.asc.json`](../../schema.asc.json) the
check the file against, and which the NixOS module is typed from. [`schemas/linux/schema.json`](../../../schemas/linux/schema.json)
in the repository is the schema of `komorebi.json`, [`schemas/linux/schema.asc.json`](../../../schemas/linux/schema.asc.json) the
schema of an [`applications.json`](application-specific-configuration.md), and the commands print
them (and two more), without a daemon:
+3 -3
View File
@@ -5,12 +5,12 @@
[`komorebic quickstart`](../cli/quickstart.md) writes three example files into the config home
(`~/.config/komorebi`, or `$KOMOREBI_CONFIG_HOME`), which it makes if it has to:
- `komorebi.json`, which is [`docs/komorebi.example.json`](../example-configurations.md):
- `komorebi.json`, which is [`docs/linux/example-configurations.md`](../example-configurations.md):
eight workspaces on the first monitor, each with another layout, and some padding;
- `applications.json`, which is
[`komorebic/applications.json`](application-specific-configuration.md#the-file-komorebi-ships),
[`docs/linux/usage/application-specific-configuration.md`](application-specific-configuration.md#the-file-komorebi-ships),
the rules `komorebi.json` names for the applications that need them;
- `skhdrc`, which is [`docs/skhdrc.sample`](../skhdrc.sample): the [key bindings](keybindings.md)
- `skhdrc`, which is [`docs/linux/skhdrc.sample`](../skhdrc.sample): the [key bindings](keybindings.md)
of the sample, in the format of skhd, which the daemon and `komorebic hotkeys compile` read from
there.
+1 -1
View File
@@ -165,5 +165,5 @@ komorebic completions bash > ~/.local/share/bash-completion/completions/komorebi
## Every command
[`docs/cli`](../cli/start.md) has a page for every `komorebic` command, generated from its
[`docs/linux/cli/start.md`](../cli/start.md) has a page for every `komorebic` command, generated from its
help with `just docgen`.
+1 -1
View File
@@ -8,7 +8,7 @@ Base16 palette of your own.
There is no `komorebic` command for it: the daemon takes it from the `theme` key of
[`komorebi.json`](configuration.md#borders), or as a message on its socket, the `Theme` message,
which a program sends with [`komorebi-client`](../../komorebi-client/src/lib.rs) or a script writes
which a program sends with [`komorebi-client`](../../../komorebi-client/src/lib.rs) or a script writes
as a line of JSON.
```rust