diff --git a/docs/linux/CONTRIBUTING.md b/docs/linux/CONTRIBUTING.md index b635b98c..662dcd47 100644 --- a/docs/linux/CONTRIBUTING.md +++ b/docs/linux/CONTRIBUTING.md @@ -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 diff --git a/docs/linux/README.md b/docs/linux/README.md index faf89a9e..b71d1a6a 100644 --- a/docs/linux/README.md +++ b/docs/linux/README.md @@ -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. diff --git a/docs/linux/dev/ARCHITECTURE.md b/docs/linux/dev/ARCHITECTURE.md index 6a8789e9..756210e2 100644 --- a/docs/linux/dev/ARCHITECTURE.md +++ b/docs/linux/dev/ARCHITECTURE.md @@ -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, `.skhdrc`, +- [`tests/fixtures`](../../../komorebi-hotkeys/tests/fixtures): the corpus, `.skhdrc`, `.whkdrc` and `.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. diff --git a/docs/linux/dev/BEHAVIOUR.md b/docs/linux/dev/BEHAVIOUR.md index 2465f9b8..ff960c1e 100644 --- a/docs/linux/dev/BEHAVIOUR.md +++ b/docs/linux/dev/BEHAVIOUR.md @@ -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 ``` @@ -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 diff --git a/docs/linux/dev/DESIGN.md b/docs/linux/dev/DESIGN.md index 8728a699..8cee55ee 100644 --- a/docs/linux/dev/DESIGN.md +++ b/docs/linux/dev/DESIGN.md @@ -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 diff --git a/docs/linux/dev/PLATFORM.md b/docs/linux/dev/PLATFORM.md index cd52d97c..1e019b02 100644 --- a/docs/linux/dev/PLATFORM.md +++ b/docs/linux/dev/PLATFORM.md @@ -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). diff --git a/docs/linux/dev/platform-contract.md b/docs/linux/dev/platform-contract.md index b985b9f3..8ad2d728 100644 --- a/docs/linux/dev/platform-contract.md +++ b/docs/linux/dev/platform-contract.md @@ -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 diff --git a/docs/linux/dev/scrolling-next.md b/docs/linux/dev/scrolling-next.md index 2afea698..f3eec1ab 100644 --- a/docs/linux/dev/scrolling-next.md +++ b/docs/linux/dev/scrolling-next.md @@ -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 diff --git a/docs/linux/dev/utm.md b/docs/linux/dev/utm.md index e248289f..0756f6a0 100644 --- a/docs/linux/dev/utm.md +++ b/docs/linux/dev/utm.md @@ -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..run-kde` and `apps..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 diff --git a/docs/linux/dev/vm-tests.md b/docs/linux/dev/vm-tests.md index 3051182f..d5164e7b 100644 --- a/docs/linux/dev/vm-tests.md +++ b/docs/linux/dev/vm-tests.md @@ -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..vm-NAME` on Linux and as `legacyPackages..vm.NAME` everywhere. `legacyPackages..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 diff --git a/docs/linux/dev/wsl2-probe.md b/docs/linux/dev/wsl2-probe.md index abc250e1..0c574fc7 100644 --- a/docs/linux/dev/wsl2-probe.md +++ b/docs/linux/dev/wsl2-probe.md @@ -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..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..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 diff --git a/docs/linux/drag-resize.md b/docs/linux/drag-resize.md index 78160c76..222de04d 100644 --- a/docs/linux/drag-resize.md +++ b/docs/linux/drag-resize.md @@ -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 diff --git a/docs/linux/example-configurations.md b/docs/linux/example-configurations.md index 842afa19..b35f136c 100644 --- a/docs/linux/example-configurations.md +++ b/docs/linux/example-configurations.md @@ -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 diff --git a/docs/linux/installation.md b/docs/linux/installation.md index 9156dcb4..03ec43f5 100644 --- a/docs/linux/installation.md +++ b/docs/linux/installation.md @@ -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 ``` diff --git a/docs/linux/trying-it.md b/docs/linux/trying-it.md index ebf2acdd..194cc1fe 100644 --- a/docs/linux/trying-it.md +++ b/docs/linux/trying-it.md @@ -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 | diff --git a/docs/linux/usage/application-specific-configuration.md b/docs/linux/usage/application-specific-configuration.md index 3701ea35..05d2f8c2 100644 --- a/docs/linux/usage/application-specific-configuration.md +++ b/docs/linux/usage/application-specific-configuration.md @@ -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. diff --git a/docs/linux/usage/configuration.md b/docs/linux/usage/configuration.md index 92b3ee98..cf16518b 100644 --- a/docs/linux/usage/configuration.md +++ b/docs/linux/usage/configuration.md @@ -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: diff --git a/docs/linux/usage/quickstart-and-autostart.md b/docs/linux/usage/quickstart-and-autostart.md index 67a38c80..c6e49212 100644 --- a/docs/linux/usage/quickstart-and-autostart.md +++ b/docs/linux/usage/quickstart-and-autostart.md @@ -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. diff --git a/docs/linux/usage/running-komorebi.md b/docs/linux/usage/running-komorebi.md index c0c2554f..5701ff2f 100644 --- a/docs/linux/usage/running-komorebi.md +++ b/docs/linux/usage/running-komorebi.md @@ -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`. diff --git a/docs/linux/usage/themes.md b/docs/linux/usage/themes.md index 4e49a6c4..32bfd719 100644 --- a/docs/linux/usage/themes.md +++ b/docs/linux/usage/themes.md @@ -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