diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 584b9072..a024a052 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,6 +59,19 @@ The messages between the bridge and the daemon are in 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 +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), +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 +.#checks.aarch64-darwin.nixos-module-eval`. A change to what the unit does in a +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. + ## VM tests A change that needs a real KWin to be checked comes with a VM test, next to diff --git a/README.md b/README.md index abb6b4ee..0ceb1a95 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,15 @@ A tiling window manager for KDE Plasma on Wayland, in the family of decides where each window goes, and KWin, the window manager of Plasma, does the moving and the drawing. +## Installing it + +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. [`docs/installation.md`](docs/installation.md) has both +ways. There are no prebuilt binaries: the Komorebi license does not allow third +parties to redistribute them. + ## Running it locally ```sh @@ -83,14 +92,16 @@ a git dependency at the revision `Cargo.toml` pins. rustdoc with warnings denied, and the type check and tests of the bridge (no package.json: `tsc` and `node` come from the dev shell), inside `nix develop`. `nix flake check` runs the same checks as derivations, plus `cargo deny`, the -TOML and Nix formatting, and the tests under `cargo nextest`, on Linux and on an -Apple silicon Mac. On Linux it also boots every VM test, which needs KVM. A Mac -runs the tests against the fake desktop, since KWin only exists on Linux. -`nix fmt` formats every file the checks look at. +TOML and Nix formatting, the tests under `cargo nextest`, and +`nixos-module-eval`, which evaluates the NixOS module in real NixOS systems, on +Linux and on an Apple silicon Mac. On Linux it also boots every VM test, which +needs KVM. A Mac runs the tests against the fake desktop, since KWin only exists +on Linux. `nix fmt` formats every file the checks look at. -The VM tests boot NixOS with Plasma and run a real KWin. `just vm NAME` runs -one; [`docs/dev/vm-tests.md`](docs/dev/vm-tests.md) has the details, including -how to run them on a Mac. +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 +the details, including how to run them on a Mac. ## How it fits together @@ -125,10 +136,15 @@ listens on a socket of its own, and after each event and each message, the daemon connects to it and writes the event or the message with the state of the window manager. +On NixOS, the module [`nix/nixos-module.nix`](nix/nixos-module.nix) runs the +daemon as a systemd user unit that the Plasma session starts, and systemd +starts it again if it fails. + ## Documentation -The user guide starts at [`docs/index.md`](docs/index.md), and -[`docs/cli`](docs/cli) has a page for every `komorebic` subcommand, which +The user guide starts at [`docs/index.md`](docs/index.md), +[`docs/installation.md`](docs/installation.md) says how to install komorebi, +and [`docs/cli`](docs/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. diff --git a/docs/dev/ARCHITECTURE.md b/docs/dev/ARCHITECTURE.md index 9cb61ff1..23c072a0 100644 --- a/docs/dev/ARCHITECTURE.md +++ b/docs/dev/ARCHITECTURE.md @@ -8,8 +8,8 @@ tested, without one. This page describes that trait, who implements and calls it, where each of its rules is enforced, the model of the desktop the window manager tiles, the backend that reaches KWin, how an event about a window becomes a tile, how a message on the daemon's socket is -answered, and how subscribers are notified of both. It grows with the code: each part of the -daemon that is added has its place here. +answered, how subscribers are notified of both, and how the NixOS module runs the daemon. It +grows with the code: each part of the daemon that is added has its place here. ## Vocabulary @@ -45,6 +45,9 @@ daemon that is added has its place here. keep up to date and the queries are answered from. - **Held call**: the `Poll` call the bridge always has open, which the daemon answers when it has commands for the bridge, or after 10 seconds with none. +- **Module**: `services.komorebi`, the NixOS module ([`nixos-module.nix`]), which installs + komorebi and runs the daemon in every Plasma session as the systemd user unit + `komorebi.service`. ## Design @@ -227,6 +230,41 @@ channel of [`window_manager_event_listener`], and past 20 the backend drops them When the daemon stops ([`WindowManager::stop`], or `SIGINT` and `SIGTERM` in `main.rs`), it connects to each subscriber and shuts the connection down without writing anything. +## The NixOS module + +The flake exports one module under two names, `nixosModules.default` and +`nixosModules.komorebi`: [`nixos-module.nix`] and the flake's overlay, which builds +`komorebi-full` (both programs) with the flake's nixpkgs and Rust toolchain. Its options are +`enable`, `package` (by default `pkgs.komorebi-full`, from the overlay), `logLevel`, and +`execStart`, which is read-only: the module sets it to `bin/komorebi` of the package with +`--log-level`. With `services.komorebi.enable`, the module: + +- installs the package in the system profile; +- defines the user unit `komorebi.service`, which every user of the machine has. Plasma's + `plasma-workspace.target` wants it, so a Plasma session starts it at login, and it is ordered + after `plasma-core.target`, which Plasma orders after KWin's service, `plasma-kwin_wayland`; +- runs `execStart` in it, with `Restart=on-failure`, the exit status of a `SIGTERM` (130) + counted as success, and a `PATH` of `/run/wrappers/bin`, `/etc/profiles/per-user/%u/bin` and + `/run/current-system/sw/bin` instead of the store paths NixOS gives a unit; +- asserts that Plasma 6 is enabled. + +The VM tests run on machines built with it ([vm-tests.md](vm-tests.md)). Their headless node +runs the daemon in test sessions, with a template unit, `komorebi@NAME`, that runs the module's +`execStart` on the session's private bus. The session node logs in to Plasma, which starts the +module's unit. + +| Rule | Enforced by | Proof | Escape hatch | +|---|---|---|---| +| komorebi is enabled only on a machine with Plasma 6 | evaluation error: an assertion of the module | `nixos-module-eval` ("without Plasma 6, an assertion fails") | none | +| The log level is one the daemon accepts | evaluation error: `logLevel` is an enum of the daemon's `--log-level` values | `nixos-module-eval` ("a log level the daemon does not have does not evaluate") | none | +| The unit runs `execStart`, and nothing but the module sets it | evaluation error: the option is read-only | `nixos-module-eval` ("execStart cannot be set", "the unit runs execStart") | a unit of your own | +| `komorebi` and `komorebic` are on every user's `PATH` | the module installs the package in the system profile | `nixos-module-eval`; every VM suite runs `komorebic` | none | +| Every Plasma session starts komorebi, once KWin's service has started | systemd: the user unit is wanted by `plasma-workspace.target`, after `plasma-core.target` | `nixos-module-eval`, `vm-module` | `systemctl --user mask komorebi` | +| A daemon that fails or is killed is started again | systemd: `Restart=on-failure` | `vm-module` (`SIGKILL`) | none | +| A daemon that is told to stop stays stopped, and the unit is not failed | systemd: the exit statuses of `Stop` (0) and of `SIGTERM` (130) are successes | `vm-module` | none | +| The daemon has the `PATH` of a terminal in the session | the unit's environment, with NixOS's default `PATH` turned off | `nixos-module-eval`, `vm-module` | none | +| 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 @@ -271,6 +309,8 @@ connects to each subscriber and shuts the connection down without writing anythi fake with `--fake-backend`, makes the window manager, which binds the socket, loads and tiles the desktop, starts the threads that listen on the socket and handle events, and waits to be stopped. +- [`nixos-module.nix`]: the NixOS module, which installs komorebi and runs the daemon as a + systemd user unit of every Plasma session. The handle is a process-wide singleton so that a window can be a small `Copy` value that carries only its id, and ask the backend for what it needs. A test replaces it for @@ -429,7 +469,12 @@ A window is shown, and ends up on a tile: driven end to end against the fake. - [`komorebi/tests/socket.rs`](../../komorebi/tests/socket.rs): the daemon over its socket, from its start to a `Stop`. +- [`nix/nixos-module.nix`](../../nix/nixos-module.nix): the NixOS module; + [`nix/tests/nixos-module.nix`](../../nix/tests/nixos-module.nix), its scenarios, evaluated in + real NixOS systems; and [`nix/tests/vm/suites/module`](../../nix/tests/vm/suites/module/test.py), + a Plasma session in which the module's unit runs the daemon. +[`nixos-module.nix`]: ../../nix/nixos-module.nix [`Backend`]: ../../komorebi/src/backend/mod.rs [`WindowInfo`]: ../../komorebi/src/backend/mod.rs [`MonitorInfo`]: ../../komorebi/src/backend/mod.rs diff --git a/docs/dev/DESIGN.md b/docs/dev/DESIGN.md index 1454bb66..7ee69a41 100644 --- a/docs/dev/DESIGN.md +++ b/docs/dev/DESIGN.md @@ -182,3 +182,31 @@ and komorebi for Mac sends the same notifications to Unix sockets, which is also ([its README](https://github.com/LGUG2Z/komorebi-for-mac#window-manager-event-subscriptions)). A subscriber here is a Unix socket, as on macOS. The named pipes that komorebi on Windows sends notifications to are not ported, since the socket subscribers do the same. + +## Why does the flake have a NixOS module? + +So that komorebi runs on NixOS with one flake input and one module line. The module installs +komorebi and starts it with every Plasma session, and it adds the flake's overlay to nixpkgs +itself, so a configuration needs nothing else to find the package. Its options follow those of +the nix-darwin module of komorebi for Mac: `enable`, `package` and `logLevel`. + +## Why does komorebi run as a systemd user unit? + +Because a user unit covers every user: it is defined once for the machine and runs for each +user who logs in. It is wanted by `plasma-workspace.target`, so it runs in Plasma sessions and +nowhere else, and it is ordered after `plasma-core.target`, which Plasma orders after KWin's +service: the daemon exits when KWin is not on the session bus. systemd starts a daemon that fails +again. + +## Why is there no binary cache? + +The Komorebi license does not allow third parties to redistribute binaries. There is no public +binary cache for komorebi, and every installation builds it from source. + +## Why do the VM tests run on machines built with the module? + +So that the tests exercise the module. Every VM suite boots a machine that imports +`nixosModules.default` and installs komorebi through it. The headless node runs the daemon with +the module's read-only `execStart`, and the session node runs the module's unit itself. A change +to the module that breaks how komorebi is installed or started fails the VM suites, and not only +`nixos-module-eval`. diff --git a/docs/dev/PLATFORM.md b/docs/dev/PLATFORM.md index d56e38fe..34773adb 100644 --- a/docs/dev/PLATFORM.md +++ b/docs/dev/PLATFORM.md @@ -59,6 +59,12 @@ The same questions, for each place the daemon can be started: Through the session bus. When the daemon is started from the session (a terminal, an autostart entry, a user unit of the session), the bus is already in its environment. +On NixOS, the module's user unit, `komorebi.service`, is wanted by `plasma-workspace.target` +and ordered after `plasma-core.target`, which Plasma orders after KWin's service, +`plasma-kwin_wayland.service`: the session starts the daemon once KWin's service has started +([installation.md](../installation.md)). The unit's `PATH` is `/run/wrappers/bin`, +`/etc/profiles/per-user//bin` and `/run/current-system/sw/bin`. + #### What komorebi does It connects to the session bus as `org.komorebi.Bridge`, writes the bridge to diff --git a/docs/dev/vm-tests.md b/docs/dev/vm-tests.md index 27c78e22..edc86552 100644 --- a/docs/dev/vm-tests.md +++ b/docs/dev/vm-tests.md @@ -37,7 +37,8 @@ A suite has two files: - `default.nix` sets `tier` (`"fast"` or `"slow"`), `kind` (the node it runs on) and `timeoutMinutes`, and may set `node`, a NixOS module that adds to the node - for this suite alone (more memory, the clients it starts). + for this suite alone (more memory, the clients it starts, the options of + `services.komorebi`). - `test.py` is the test, a Python script for the NixOS test driver. It is prefixed with `SCALE = `, how many times slower than KVM the machine is. @@ -47,23 +48,38 @@ A suite has two files: `kind` picks a file under [`nix/tests/vm/nodes`](../../nix/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 +`services.komorebi`, which installs `komorebi` and `komorebic`, built from the +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 +suite `module` checks its unit in a Plasma session. + `headless` is a machine with Plasma installed and no login. Each KWin a test starts is a pair of user units of the test user, `session-bus@NAME` (a private D-Bus session bus) and `kwin-virtual@NAME` (`kwin_wayland --virtual` with its own Wayland socket), so a test can run several sessions side by side and none touches another. A virtual KWin has no real output, so it cannot draw: it can place windows and answer questions about them, but it cannot take a screenshot. -A third unit, `komorebi@NAME`, runs the daemon in a session, built from the -commit under test and installed on the node with `komorebic`; it is not bound to -KWin's unit, so a test can restart KWin under a running daemon. +A third unit, `komorebi@NAME`, runs the daemon in a session: it is the module's +unit, `komorebi.service`, moved to the session's bus and Wayland socket, and runs +the module's `execStart` followed by the arguments the test gives. It is not +bound to KWin's unit, so a test can restart KWin under a running daemon. The +module's unit itself starts with a Plasma session, which this node does not +have. KWin wants a DRM render node, which needs a GPU. The test driver gives every aarch64 guest one `virtio-gpu-pci`; on x86_64 the node adds it, unless `komorebi.vm.renderNode` is false. `session` is the headless node plus a login: plasma-login-manager logs the test user in by itself, as in nixpkgs' own `plasma6` test, and Plasma draws on the -machine's display device. It is the node for anything that needs pixels. The -choice of login manager is made in +machine's display device. The login starts the module's unit, so komorebi runs +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. The choice of login manager is made in [`nodes/session.nix`](../../nix/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 @@ -100,9 +116,11 @@ the run. user would, and `wid_by_class` finds a window by its app id or X11 class. `Kde.headless(..., xwayland=True)` gives the session XWayland, for X11 clients. -- `start_komorebi(*args)` starts the daemon in the session, `stop_komorebi()` - stops it with `SIGTERM`, `komorebi_log()` returns its log since it was last - started, and `script_loaded()` asks KWin whether it runs the bridge. +- `start_komorebi(*args)` starts the daemon in the session, with the module's + `execStart` and `args` after it (not `--log-level`, which `execStart` has), + `stop_komorebi()` stops it with `SIGTERM`, `komorebi_log()` returns its log + since it was last started, and `script_loaded()` asks KWin whether it runs + the bridge. `restart_kwin()` stops the session's KWin and starts a new one on the same bus, as when the compositor of a running session crashes, and waits for it. - `komorebic(*args)` runs `komorebic` in the session and returns what it @@ -110,8 +128,8 @@ the run. `komorebic state` prints it, `managed(workspace)` the number of windows the daemon has on a workspace of the first monitor, and `focused_title(workspace)` the title of the window it has focused there. -- `daemon` reads the daemon's view of the desktop from that log, started with - `--log-level debug`: `daemon.events(log)` lists the window events it handled, +- `daemon` reads the daemon's view of the desktop from that log, at the debug + level the nodes set: `daemon.events(log)` lists the window events it handled, in order, `daemon.window_ids(log)` maps a window's title to the daemon's id for it, and `daemon.requests(log)` returns the frame the daemon last asked KWin for, for each window. @@ -179,4 +197,6 @@ 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 `print()` goes to the same journal. The daemon's log is -`/run/user/1000/komorebi-NAME.log`. +`/run/user/1000/komorebi-NAME.log`. On the session node, the daemon of the +module's unit logs to `journalctl --user -u komorebi`, with colors, and to +`~/.local/share/komorebi/komorebi_plaintext.log.DATE`, without. diff --git a/docs/index.md b/docs/index.md index 7a5f98a1..09f529d9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -28,8 +28,10 @@ key bindings --------> komorebic <------> komorebi ## Getting started -[Running komorebi](usage/running-komorebi.md) explains how to get the two programs, start and -stop the daemon, ask it what it is doing and read its log. +[Installing komorebi](installation.md) explains how to install the two programs: on NixOS with +the flake's module, which also starts komorebi with every Plasma session, and from source +anywhere else. [Running komorebi](usage/running-komorebi.md) explains how to start and stop the +daemon, ask it what it is doing and read its log. [Subscribing to notifications](usage/subscribing-to-notifications.md) explains how a program such as a status bar follows what komorebi does. The [CLI reference](cli/start.md) has a page for every `komorebic` command, generated from its help. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..58063c83 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,152 @@ +# Installing komorebi + +`komorebi` is two programs: `komorebi`, the daemon that tiles the windows, and `komorebic`, the +command line that controls it. The daemon runs in a KDE Plasma Wayland session with KWin 6.8 or +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. + +There is no binary cache and there are no prebuilt binaries: the Komorebi license does not allow +third parties to redistribute binaries, so every installation builds komorebi from source. On +NixOS, Nix does that for you, the first time you switch to a configuration that has it. + +## NixOS + +### The module + +Add the repository to the inputs of your system's flake, and import its module, +`nixosModules.default`, into your configuration: + +```nix +{ + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable"; + komorebi.url = "github:LGUG2Z/komorebi-for-kde"; + }; + + outputs = + { nixpkgs, komorebi, ... }: + { + nixosConfigurations.HOSTNAME = nixpkgs.lib.nixosSystem { + modules = [ + komorebi.nixosModules.default + ./configuration.nix + ]; + }; + }; +} +``` + +Then enable it, next to Plasma, in `configuration.nix`: + +```nix +{ + services.desktopManager.plasma6.enable = true; + services.komorebi.enable = true; +} +``` + +The module adds the flake's overlay, which provides `pkgs.komorebi-full`, to your nixpkgs, so +nothing else is needed. komorebi is built with the flake's nixpkgs and the Rust toolchain that +the repository's `rust-toolchain.toml` selects, whatever nixpkgs your system uses. + +### What the module does + +- It installs `komorebi` and `komorebic` in the system profile, so they are on every user's + `PATH`. +- It defines a systemd user unit, `komorebi.service`, for every user of the machine. Plasma's + `plasma-workspace.target` starts it when a user logs in to a Plasma session, after + `plasma-core.target`, which Plasma orders after KWin. The unit runs the daemon with the `PATH` + of a terminal in the session. +- systemd starts the daemon again when it fails or is killed. When it is stopped (`komorebic + stop`, or `systemctl --user stop komorebi`), it stays stopped until the next login or + `systemctl --user start komorebi`. +- Without `services.desktopManager.plasma6.enable`, the configuration does not evaluate: an + assertion of the module fails, and its message names the option to set. + +### Options + +| Option | Default | What it does | +|---|---|---| +| `services.komorebi.enable` | `false` | Installs komorebi and starts it with every Plasma session. | +| `services.komorebi.package` | `pkgs.komorebi-full` | The package with `bin/komorebi` and `bin/komorebic`; the unit runs the first, and both are installed. | +| `services.komorebi.logLevel` | `"info"` | The daemon's `--log-level`: `"error"`, `"warn"`, `"info"`, `"debug"` or `"trace"`. | +| `services.komorebi.execStart` | read only | The command line the unit starts komorebi with, built from `package` and `logLevel`. A unit of your own that runs komorebi uses it to start komorebi the same way. | + +### Running it + +`plasma-workspace.target` starts komorebi when you log in. In a session that was already +running when you switched to the new configuration, start it yourself: + +```sh +systemctl --user start komorebi +systemctl --user status komorebi +journalctl --user -u komorebi +``` + +[`komorebic stop`](cli/stop.md) stops it until you start it again or log in again. +[`komorebic start`](cli/start.md) finds the daemon the unit runs and does nothing, and a second +`komorebi` in the same session exits: the session bus gives the name komorebi needs to one +daemon. [Running komorebi](usage/running-komorebi.md) has the rest: asking komorebi what it is +doing, and its log. + +### The packages without the module + +The flake's packages are `komorebi`, `komorebic`, and `komorebi-full`, which has both and is the +`default`. To install them without the unit, and start komorebi yourself: + +```sh +nix profile install github:LGUG2Z/komorebi-for-kde +``` + +On a NixOS configuration, the overlay, `overlays.default`, provides `pkgs.komorebi`, +`pkgs.komorebic` and `pkgs.komorebi-full` for `environment.systemPackages`. + +## Other distributions: from source + +You need a Plasma 6.8 (or newer) Wayland session, [rustup](https://rustup.rs) with the stable +toolchain, which `rust-toolchain.toml` selects, and a C compiler (`cc`): the crate that makes the +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 komorebic +``` + +`cargo` installs both in `~/.cargo/bin`, which has to be on your `PATH`. Start komorebi from a +terminal in your Plasma session with [`komorebic start`](cli/start.md). + +To start it with every Plasma session instead, write the unit the NixOS module defines, without +the NixOS paths, to `~/.config/systemd/user/komorebi.service`: + +```ini +[Unit] +Description=komorebi, the tiling window manager +After=plasma-core.target + +[Service] +ExecStart=%h/.cargo/bin/komorebi +Restart=on-failure +SuccessExitStatus=130 + +[Install] +WantedBy=plasma-workspace.target +``` + +and enable it with `systemctl --user enable komorebi`. At time of writing (2026-10-27), only the +module's unit has been run, on NixOS; this one has not been tried on another distribution. + +## Uninstalling + +Stop the daemon first, with `komorebic stop`. + +- With the module, remove `services.komorebi.enable` (or the module) from your configuration and + switch to it. +- From source, remove the unit if you wrote one (`systemctl --user disable komorebi`, then the + file), and the programs, with `cargo uninstall komorebi komorebic`. + +The daemon's logs are in `~/.local/share/komorebi` (`$XDG_DATA_HOME/komorebi`), which you can +delete. Its socket is in `$XDG_RUNTIME_DIR/komorebi`, which is removed when you log out. diff --git a/docs/usage/running-komorebi.md b/docs/usage/running-komorebi.md index 0e0eb08f..cf0e8020 100644 --- a/docs/usage/running-komorebi.md +++ b/docs/usage/running-komorebi.md @@ -6,16 +6,22 @@ doing, and reading its log. ## Getting the two programs -On Linux, the flake's default package has both: in a checkout of the repository, -`nix build` leaves them in `result/bin`, and `nix profile install .` puts them on your -`PATH`. Without nix, build them with the Rust toolchain that `rust-toolchain.toml` -selects: +[Installing komorebi](../installation.md) covers NixOS, where the flake's module installs both +and starts the daemon with every Plasma session, and building them from source. In a checkout of +the repository, on Linux, `nix build` leaves them in `result/bin`, and `nix profile install .` +puts them on your `PATH`. Without nix, build them with the Rust toolchain that +`rust-toolchain.toml` selects: ```sh cargo build --release --locked export PATH="$PWD/target/release:$PATH" ``` +With the NixOS module, the daemon is the user unit `komorebi.service`, which starts when you log +in to Plasma. `systemctl --user start komorebi` starts it again after a `komorebic stop`, and +`journalctl --user -u komorebi` shows what it wrote. Everything else on this page applies to it +as it is. + ## Starting and stopping [`komorebic start`](../cli/start.md) runs the `komorebi` on your `PATH` in the background, diff --git a/flake.nix b/flake.nix index e7f51b82..f8d1cee1 100644 --- a/flake.nix +++ b/flake.nix @@ -123,12 +123,12 @@ pkgs = mkPkgs system; build = mkKomorebiPackages { inherit pkgs; }; isLinux = pkgs.stdenv.hostPlatform.isLinux; - # the daemon and komorebic each guest runs, built for the guest's system - komorebiFor = guestSystem: self.packages.${guestSystem}.komorebi-full; + # the guests install komorebi through the module, as a NixOS user does + komorebiModule = self.nixosModules.default; # a Mac runs the guests under HVF, which is slower than KVM vm = import ./nix/tests/vm { hostPkgs = pkgs; - inherit komorebiFor; + inherit komorebiModule; scale = if isLinux then 1 else 1.5; }; nightlyRustfmt = pkgs.rust-bin.nightly.latest.rustfmt; @@ -211,6 +211,15 @@ ''; vm-lib = vm.lib; + + # The NixOS module in real NixOS systems, evaluated and never built, so a Mac checks it + # too. A VM suite, `vm-module`, runs it. + nixos-module-eval = import ./nix/tests/nixos-module.nix { + inherit pkgs; + inherit (nixpkgs.lib) nixosSystem; + module = self.nixosModules.default; + komorebiFor = guestSystem: self.packages.${guestSystem}.komorebi-full; + }; } # The VM tests need QEMU with KVM, so only Linux checks them. A Mac runs the same tests # through legacyPackages..vm, see docs/dev/vm-tests.md. @@ -231,7 +240,7 @@ vmTcg = (import ./nix/tests/vm { hostPkgs = pkgs; - inherit komorebiFor; + inherit komorebiModule; scale = 8; }).suites; }; @@ -295,13 +304,24 @@ }; flake = { - overlays.default = final: _: { - inherit ((mkKomorebiPackages { pkgs = mkPkgs final.stdenv.hostPlatform.system; })) - komorebi - komorebic - ; - }; + overlays.default = + final: _: + let + build = mkKomorebiPackages { pkgs = mkPkgs final.stdenv.hostPlatform.system; }; + in + { + inherit (build) komorebi komorebic; + komorebi-full = build.fullBuild; + }; overlays.komorebi = self.overlays.default; + + # `services.komorebi`, with the overlay that provides its package, so that a NixOS + # configuration needs this flake as an input and one module line (docs/installation.md) + nixosModules.default = { + imports = [ ./nix/nixos-module.nix ]; + nixpkgs.overlays = [ self.overlays.default ]; + }; + nixosModules.komorebi = self.nixosModules.default; }; }; } diff --git a/nix/nixos-module.nix b/nix/nixos-module.nix new file mode 100644 index 00000000..69333f15 --- /dev/null +++ b/nix/nixos-module.nix @@ -0,0 +1,96 @@ +# `services.komorebi`: komorebi in the Plasma session of every user of a NixOS machine. The flake +# exports this module as `nixosModules.default` and `nixosModules.komorebi`, together with its +# overlay, which provides `pkgs.komorebi-full` (see docs/installation.md). What the module +# guarantees, and what enforces each guarantee, is in docs/dev/ARCHITECTURE.md; its tests are +# nix/tests/nixos-module.nix and the VM suite `module`. +{ + config, + lib, + pkgs, + ... +}: +let + cfg = config.services.komorebi; +in +{ + options.services.komorebi = { + enable = lib.mkEnableOption "komorebi, the tiling window manager, in the Plasma session of every user"; + + package = lib.mkPackageOption pkgs "komorebi-full" { + extraDescription = '' + It must have `bin/komorebi`, which the unit runs, and `bin/komorebic`. The module installs + both in the system profile. + ''; + }; + + logLevel = lib.mkOption { + type = lib.types.enum [ + "error" + "warn" + "info" + "debug" + "trace" + ]; + default = "info"; + description = '' + How much the daemon logs: its `--log-level`. The log goes to the journal of the unit + (`journalctl --user -u komorebi`) and to the daemon's log files, which `komorebic log` + follows. + ''; + }; + + execStart = lib.mkOption { + type = lib.types.str; + readOnly = true; + description = '' + The command line the unit starts komorebi with: `bin/komorebi` of `package`, with + `logLevel`. The module sets it, and setting it anywhere else is an error. A unit of your + own that runs komorebi somewhere else, as the VM tests do in their headless sessions, + starts it with this, the way the module does. + ''; + }; + }; + + config = lib.mkMerge [ + { + services.komorebi.execStart = "${lib.getExe' cfg.package "komorebi"} --log-level ${cfg.logLevel}"; + } + + (lib.mkIf cfg.enable { + assertions = [ + { + assertion = config.services.desktopManager.plasma6.enable; + message = '' + services.komorebi needs Plasma 6: komorebi runs in a Plasma Wayland session, and the + session starts it. Set services.desktopManager.plasma6.enable = true. + ''; + } + ]; + + environment.systemPackages = [ cfg.package ]; + + # A user unit, so it runs for every user who logs in to Plasma. plasma-workspace.target is + # the target of a Plasma session's services, and plasma-core.target, which it requires, is + # ordered after KWin's service: the daemon exits when KWin is not on the session bus. + systemd.user.services.komorebi = { + description = "komorebi, the tiling window manager"; + wantedBy = [ "plasma-workspace.target" ]; + after = [ "plasma-core.target" ]; + # NixOS gives a unit a PATH made of a few store paths; this is the PATH a terminal in the + # user's session has + enableDefaultPath = false; + environment.PATH = lib.concatStringsSep ":" [ + "/run/wrappers/bin" + "/etc/profiles/per-user/%u/bin" + "/run/current-system/sw/bin" + ]; + serviceConfig = { + ExecStart = cfg.execStart; + Restart = "on-failure"; + # what komorebi exits with when it is stopped with SIGTERM, as systemd stops a unit + SuccessExitStatus = 130; + }; + }; + }) + ]; +} diff --git a/nix/tests/nixos-module.nix b/nix/tests/nixos-module.nix new file mode 100644 index 00000000..9544be83 --- /dev/null +++ b/nix/tests/nixos-module.nix @@ -0,0 +1,215 @@ +# `nixos-module-eval`: `services.komorebi` in real NixOS systems, evaluated and never built. Each +# scenario is a `nixosSystem` with the module, and the checks read what it evaluates to: the +# assertions, the unit the module defines, and its read-only `execStart`. A scenario that must +# not evaluate is caught with `builtins.tryEval`. Nothing here builds a Linux package (the +# derivation below gets only check names and booleans), so a Mac runs it too. +{ + pkgs, + # nixpkgs' `lib.nixosSystem` + nixosSystem, + # the module, as the flake exports it, with its overlay + module, + # the flake's komorebi-full for a system, which the overlay has to provide + komorebiFor, +}: +let + inherit (pkgs) lib; + + # the systems are of the host's architecture + system = "${pkgs.stdenv.hostPlatform.parsed.cpu.name}-linux"; + + # enough of a machine for every NixOS assertion to hold, since no scenario is ever built + machine = { + nixpkgs.hostPlatform = system; + boot.loader.grub.enable = false; + fileSystems."/" = { + device = "/dev/vda"; + fsType = "ext4"; + }; + system.stateVersion = lib.trivial.release; + }; + + plasma = { + services.desktopManager.plasma6.enable = true; + }; + + eval = + scenario: + (nixosSystem { + modules = [ + module + machine + scenario + ]; + }).config; + + enabled = eval { + imports = [ plasma ]; + services.komorebi.enable = true; + }; + + disabled = eval plasma; + + withoutPlasma = eval { services.komorebi.enable = true; }; + + debug = eval { + imports = [ plasma ]; + services.komorebi = { + enable = true; + logLevel = "debug"; + }; + }; + + # a package that is not the overlay's: any package will do, since nothing is built + otherPackage = eval ( + { pkgs, ... }: + { + imports = [ plasma ]; + services.komorebi = { + enable = true; + package = pkgs.hello; + }; + } + ); + + unknownLevel = eval { + imports = [ plasma ]; + services.komorebi = { + enable = true; + logLevel = "verbose"; + }; + }; + + execStartSet = eval { + imports = [ plasma ]; + services.komorebi = { + enable = true; + execStart = "/bin/true"; + }; + }; + + failed = config: map (a: a.message) (lib.filter (a: !a.assertion) config.assertions); + unit = config: config.systemd.user.services.komorebi; + evaluates = value: (builtins.tryEval value).success; + + checks = [ + { + name = "enabled with Plasma 6, every assertion holds"; + ok = failed enabled == [ ]; + got = failed enabled; + } + { + name = "the unit is started by plasma-workspace.target"; + ok = (unit enabled).wantedBy == [ "plasma-workspace.target" ]; + got = (unit enabled).wantedBy; + } + { + name = "the unit starts after plasma-core.target"; + ok = lib.elem "plasma-core.target" (unit enabled).after; + got = (unit enabled).after; + } + { + name = "the unit is restarted when it fails"; + ok = (unit enabled).serviceConfig.Restart == "on-failure"; + } + { + name = "the unit counts the exit status of a SIGTERM (130) as success"; + ok = (unit enabled).serviceConfig.SuccessExitStatus == 130; + } + { + name = "the unit runs execStart"; + ok = (unit enabled).serviceConfig.ExecStart == enabled.services.komorebi.execStart; + got = (unit enabled).serviceConfig.ExecStart; + } + { + name = "execStart is bin/komorebi of the package, at the info level"; + ok = + enabled.services.komorebi.execStart + == "${enabled.services.komorebi.package}/bin/komorebi --log-level info"; + got = enabled.services.komorebi.execStart; + } + { + name = "the default package is the flake's komorebi-full, from the overlay"; + ok = enabled.services.komorebi.package.outPath == (komorebiFor system).outPath; + } + { + name = "the unit has the PATH of the user's session"; + ok = + (unit enabled).environment.PATH + == "/run/wrappers/bin:/etc/profiles/per-user/%u/bin:/run/current-system/sw/bin"; + got = (unit enabled).environment.PATH; + } + { + name = "the package is installed in the system profile"; + ok = lib.elem enabled.services.komorebi.package enabled.environment.systemPackages; + } + { + name = "disabled, every assertion holds"; + ok = failed disabled == [ ]; + got = failed disabled; + } + { + name = "disabled, there is no unit"; + ok = !(disabled.systemd.user.services ? komorebi); + } + { + name = "disabled, nothing is installed"; + ok = !(lib.elem disabled.services.komorebi.package disabled.environment.systemPackages); + } + { + name = "without Plasma 6, an assertion fails and names the option to set"; + ok = lib.any (lib.hasInfix "services.desktopManager.plasma6.enable = true") (failed withoutPlasma); + got = failed withoutPlasma; + } + { + name = "logLevel reaches execStart and the unit"; + ok = + debug.services.komorebi.execStart + == "${debug.services.komorebi.package}/bin/komorebi --log-level debug" + && (unit debug).serviceConfig.ExecStart == debug.services.komorebi.execStart; + got = (unit debug).serviceConfig.ExecStart; + } + { + name = "another package is the one the unit runs and the one installed"; + ok = + (unit otherPackage).serviceConfig.ExecStart + == "${otherPackage.services.komorebi.package}/bin/komorebi --log-level info" + && lib.elem otherPackage.services.komorebi.package otherPackage.environment.systemPackages; + got = (unit otherPackage).serviceConfig.ExecStart; + } + { + name = "a log level the daemon does not have does not evaluate"; + ok = !(evaluates unknownLevel.services.komorebi.logLevel); + } + { + name = "execStart cannot be set"; + ok = !(evaluates execStartSet.services.komorebi.execStart); + } + ]; + + failures = lib.filter (check: !check.ok) checks; + + # what a failed check got, without the store paths' context: this derivation must not depend on + # a Linux package + show = + check: + check.name + + lib.optionalString (check ? got) ( + ": got " + builtins.unsafeDiscardStringContext (builtins.toJSON check.got) + ); +in +pkgs.runCommand "nixos-module-eval" { } ( + if failures == [ ] then + '' + ${lib.concatMapStringsSep "\n" (check: "echo ${lib.escapeShellArg "ok: ${check.name}"}") checks} + echo "${toString (lib.length checks)} checks of services.komorebi passed" + touch $out + '' + else + '' + ${lib.concatMapStringsSep "\n" ( + check: "echo ${lib.escapeShellArg "FAILED: ${show check}"}" + ) failures} + exit 1 + '' +) diff --git a/nix/tests/vm/default.nix b/nix/tests/vm/default.nix index 245f72cb..5d15e3f2 100644 --- a/nix/tests/vm/default.nix +++ b/nix/tests/vm/default.nix @@ -2,21 +2,19 @@ # (Linux) and `legacyPackages..vm.` (everywhere), so a new suite needs no edit to # the flake. See docs/dev/vm-tests.md. # -# `hostPkgs` is the pkgs of the machine that runs QEMU; the guests are always Linux. `komorebiFor` -# returns the package of `komorebi` and `komorebic` for a system, and the guests get the one of -# their own. `scale` says how much slower than KVM that machine is (1 for KVM, 1.5 for HVF on a -# Mac, 8 for TCG), and every wait in the suites is multiplied by it. +# `hostPkgs` is the pkgs of the machine that runs QEMU; the guests are always Linux. +# `komorebiModule` is the flake's NixOS module, `services.komorebi`, which every node imports: its +# overlay builds `komorebi` and `komorebic` for the guest's system. `scale` says how much slower +# than KVM that machine is (1 for KVM, 1.5 for HVF on a Mac, 8 for TCG), and every wait in the +# suites is multiplied by it. { hostPkgs, - komorebiFor, + komorebiModule, scale ? 1, }: let inherit (hostPkgs) lib; - # a Linux guest of the host's architecture, which is what the test driver boots - guestSystem = "${hostPkgs.stdenv.hostPlatform.parsed.cpu.name}-linux"; - # the library the suites import, built for the python of the test driver komorebiVm = ps: @@ -80,8 +78,10 @@ let globalTimeout = builtins.ceil (suite.timeoutMinutes * 60 * scale); passthru.tier = suite.tier; - # the nodes take the daemon as an argument, `komorebi` - node.specialArgs.komorebi = komorebiFor guestSystem; + # the nodes import the module, `komorebiModule`, which adds its overlay to nixpkgs: the test + # framework's pkgs, which cannot be changed, would refuse it + node.specialArgs = { inherit komorebiModule; }; + node.pkgsReadOnly = false; nodes.machine = { # a suite's `node`, if it has one, adds to the node of its kind diff --git a/nix/tests/vm/lib/komorebi_vm/daemon.py b/nix/tests/vm/lib/komorebi_vm/daemon.py index abd7957b..5546bfc2 100644 --- a/nix/tests/vm/lib/komorebi_vm/daemon.py +++ b/nix/tests/vm/lib/komorebi_vm/daemon.py @@ -1,10 +1,10 @@ """What the komorebi daemon logs about the events it handles. A test reads the daemon's view of the desktop from its log -([`Kde.komorebi_log`](komorebi_vm.kde.Kde.komorebi_log)), started with -`--log-level debug`: every event it handles is an info line, every focus -change KWin reports names the window by the daemon's id and its title, and -every frame the daemon asks KWin for is a debug line. +([`Kde.komorebi_log`](komorebi_vm.kde.Kde.komorebi_log)), at the debug level +the test nodes set (`services.komorebi.logLevel`): every event it handles is an +info line, every focus change KWin reports names the window by the daemon's id +and its title, and every frame the daemon asks KWin for is a debug line. """ import re diff --git a/nix/tests/vm/lib/komorebi_vm/kde.py b/nix/tests/vm/lib/komorebi_vm/kde.py index b7eae826..e07c3e32 100644 --- a/nix/tests/vm/lib/komorebi_vm/kde.py +++ b/nix/tests/vm/lib/komorebi_vm/kde.py @@ -218,8 +218,10 @@ class Kde: def start_komorebi(self, *args: str) -> None: """Starts the daemon in this session, with `args`, as the user unit `komorebi@NAME`. - The unit runs the `komorebi` the node has, against this session's bus and KWin, and - writes its log to a file that [`Kde.komorebi_log`][] reads, emptied on every start. + The unit runs the NixOS module's `execStart` with `args` after it, against this + session's bus and KWin, and writes its log to a file that [`Kde.komorebi_log`][] reads, + emptied on every start. `execStart` already has `--log-level`, from the node's + `services.komorebi.logLevel` (debug), and `komorebi` refuses a second one. """ words = shlex.quote(" ".join(args)) self.as_user(f"echo KOMOREBI_ARGS={words} > {self.runtime}/komorebi-{self.name}.env") diff --git a/nix/tests/vm/lib/tests/test_kde.py b/nix/tests/vm/lib/tests/test_kde.py index 9e246032..21dbe48a 100644 --- a/nix/tests/vm/lib/tests/test_kde.py +++ b/nix/tests/vm/lib/tests/test_kde.py @@ -139,10 +139,10 @@ def test_shot_returns_the_screenshot_as_rgb(machine: FakeMachine) -> None: def test_start_komorebi_writes_the_arguments_and_starts_the_unit(machine: FakeMachine) -> None: - Kde(machine, "main").start_komorebi("--log-level", "debug") + Kde(machine, "main").start_komorebi("--fake-backend") scripts = [inner(command) for command in machine.commands if " sh -c " in command] - assert "echo KOMOREBI_ARGS='--log-level debug' > /run/user/1000/komorebi-main.env" in scripts + assert "echo KOMOREBI_ARGS=--fake-backend > /run/user/1000/komorebi-main.env" in scripts assert "systemctl --user start komorebi@main.service" in scripts diff --git a/nix/tests/vm/nodes/headless.nix b/nix/tests/vm/nodes/headless.nix index bd0ccb22..f731b53f 100644 --- a/nix/tests/vm/nodes/headless.nix +++ b/nix/tests/vm/nodes/headless.nix @@ -1,23 +1,35 @@ # A machine with Plasma installed and no login: `kwin_wayland --virtual` runs as the test user's # own user units, once for every session a test starts, each with its own private session bus and # Wayland socket (`session-bus@NAME`, `kwin-virtual@NAME`). A virtual KWin has no real output, so it -# cannot draw: pixel and pointer tests use the session node instead. `komorebi@NAME` runs the daemon -# in a session; `komorebi` is the package of the daemon and `komorebic`, which the test framework -# passes in. +# cannot draw: pixel and pointer tests use the session node instead. +# +# komorebi comes from the NixOS module, `komorebiModule`, which the test framework passes in: the +# node imports it and enables `services.komorebi` as a user's machine does, which installs +# `komorebi` and `komorebic`. The module's unit starts with a Plasma session, and this node has +# none; `komorebi@NAME` runs the module's `execStart` in a test session instead. { config, lib, pkgs, - komorebi, + komorebiModule, ... }: { - imports = [ ./options.nix ]; + imports = [ + ./options.nix + komorebiModule + ]; # KWin, its plugins and the environment a session expects services.desktopManager.plasma6.enable = true; hardware.graphics.enable = true; + # A suite can change either in its `node`. The tests read the daemon's debug log. + services.komorebi = { + enable = lib.mkDefault true; + logLevel = lib.mkDefault "debug"; + }; + users.users.komorebi = { isNormalUser = true; uid = 1000; @@ -40,7 +52,6 @@ kdotool kdePackages.libkscreen kdePackages.qttools - komorebi ]; systemd.user.services = { @@ -70,7 +81,8 @@ }; }; - # Not bound to KWin's unit: a test restarts KWin under a running daemon + # The module's unit, moved to the test session's bus and Wayland socket. Not bound to KWin's + # unit: a test restarts KWin under a running daemon. "komorebi@" = { description = "komorebi in the test session %i"; requires = [ "session-bus@%i.service" ]; @@ -86,10 +98,11 @@ NO_COLOR = "1"; }; serviceConfig = { - # the library writes KOMOREBI_ARGS (the log level) before it starts the unit + # the library writes KOMOREBI_ARGS (what follows the module's command line) before it + # starts the unit EnvironmentFile = "-%t/komorebi-%i.env"; # a log file per run, emptied on every start, which the library reads - ExecStart = "${pkgs.runtimeShell} -c 'exec ${komorebi}/bin/komorebi $${KOMOREBI_ARGS} > %t/komorebi-%i.log 2>&1'"; + ExecStart = "${pkgs.runtimeShell} -c 'exec ${config.services.komorebi.execStart} $${KOMOREBI_ARGS} > %t/komorebi-%i.log 2>&1'"; # what komorebi exits with when it is told to stop SuccessExitStatus = 130; }; diff --git a/nix/tests/vm/nodes/session.nix b/nix/tests/vm/nodes/session.nix index ebc68060..73d75042 100644 --- a/nix/tests/vm/nodes/session.nix +++ b/nix/tests/vm/nodes/session.nix @@ -1,5 +1,8 @@ # A real Plasma Wayland session that logs in by itself, on a machine that can draw. Everything the -# headless node has is here too, so a test can still start a virtual KWin next to it. +# headless node has is here too, so a test can still start a virtual KWin next to it. The module's +# unit, `komorebi.service`, starts komorebi in the session when the user logs in, as on a user's +# machine; a suite that wants the session without it sets `services.komorebi.enable = false` in +# its `node`. # # The choice of login manager is made here and nowhere else. nixpkgs' own `plasma6` test uses # plasma-login-manager, so that is what this node follows; sddm with a Wayland greeter is the other diff --git a/nix/tests/vm/suites/client-geometry/test.py b/nix/tests/vm/suites/client-geometry/test.py index 6055401e..bb435781 100644 --- a/nix/tests/vm/suites/client-geometry/test.py +++ b/nix/tests/vm/suites/client-geometry/test.py @@ -32,7 +32,7 @@ machine.wait_for_unit("user@1000.service") checks = Checks() kde = Kde.headless(machine, "main", size=(W, H), xwayland=True, scale=SCALE) kde.as_user("mkdir -p /tmp/firefox-profile") -kde.start_komorebi("--log-level", "debug") +kde.start_komorebi() checks.check( "the daemon loaded its script into KWin", kde.wait_for(lambda: "loaded the KWin bridge script" in kde.komorebi_log(), timeout=30), diff --git a/nix/tests/vm/suites/core-e2e/test.py b/nix/tests/vm/suites/core-e2e/test.py index 231508b9..8fdbb315 100644 --- a/nix/tests/vm/suites/core-e2e/test.py +++ b/nix/tests/vm/suites/core-e2e/test.py @@ -74,7 +74,7 @@ def report(titles: list[str]) -> None: print("== 1. start") -kde.start_komorebi("--log-level", "debug") +kde.start_komorebi() checks.check( "the daemon loaded its script into KWin", kde.wait_for(lambda: "loaded the KWin bridge script" in daemon_log(), timeout=30), diff --git a/nix/tests/vm/suites/kwin-events/test.py b/nix/tests/vm/suites/kwin-events/test.py index df38a6d3..c6e082bc 100644 --- a/nix/tests/vm/suites/kwin-events/test.py +++ b/nix/tests/vm/suites/kwin-events/test.py @@ -29,7 +29,7 @@ checks.check( ) before = kde.wid("before") -kde.start_komorebi("--log-level", "debug") +kde.start_komorebi() checks.check( "the daemon loaded its script into KWin", kde.wait_for(lambda: "loaded the KWin bridge script" in daemon_log(), timeout=30), diff --git a/nix/tests/vm/suites/kwin-restart/test.py b/nix/tests/vm/suites/kwin-restart/test.py index eaac35a7..def9ad61 100644 --- a/nix/tests/vm/suites/kwin-restart/test.py +++ b/nix/tests/vm/suites/kwin-restart/test.py @@ -83,7 +83,7 @@ def restart(old: list[str], loaded: int) -> None: print("== 1. three windows are tiled") -kde.start_komorebi("--log-level", "debug") +kde.start_komorebi() checks.check( "the daemon loaded its script into KWin", kde.wait_for(lambda: loads() == 1, timeout=30) ) diff --git a/nix/tests/vm/suites/latency/default.nix b/nix/tests/vm/suites/latency/default.nix index a4ba7be3..a4fe5777 100644 --- a/nix/tests/vm/suites/latency/default.nix +++ b/nix/tests/vm/suites/latency/default.nix @@ -6,5 +6,7 @@ { pkgs, ... }: { environment.systemPackages = [ pkgs.dbus ]; + # this suite times the daemon, so it runs at the default log level, as a user's does + services.komorebi.logLevel = "info"; }; } diff --git a/nix/tests/vm/suites/module/default.nix b/nix/tests/vm/suites/module/default.nix new file mode 100644 index 00000000..7fae097d --- /dev/null +++ b/nix/tests/vm/suites/module/default.nix @@ -0,0 +1,5 @@ +{ + tier = "fast"; + kind = "session"; + timeoutMinutes = 10; +} diff --git a/nix/tests/vm/suites/module/test.py b/nix/tests/vm/suites/module/test.py new file mode 100644 index 00000000..0fa30990 --- /dev/null +++ b/nix/tests/vm/suites/module/test.py @@ -0,0 +1,123 @@ +# The NixOS module runs komorebi in a real Plasma session: nothing in this test starts the daemon. +# What only a real session can tell: that logging in starts the module's user unit through +# `plasma-workspace.target`, that the daemon it runs reaches KWin from there and tiles a window +# opened in the session, that it runs with the module's log level and the PATH of the user's +# session, that systemd starts it again when it is killed, and that a clean stop is not a failure. +# The options and the unit the module writes are checked without a machine by `nixos-module-eval` +# (`nix/tests/nixos-module.nix`). +import json + +from komorebi_vm import Checks, Kde, Rect, daemon + +UNIT = "komorebi.service" +# foot sizes itself to whole cells of its font, so its frame can be short of the one asked for +CELL = 24 +# the daemon's log of the day, without colors, which the unit's journal has +LOG = "/home/komorebi/.local/share/komorebi/komorebi_plaintext.log.*" + +start_all() +machine.wait_for_unit("multi-user.target") + +checks = Checks() +kde = Kde.session(machine, scale=SCALE) + + +def active() -> bool: + return kde.run(f"systemctl --user is-active --quiet {UNIT}")[0] == 0 + + +def failed() -> bool: + return kde.run(f"systemctl --user is-failed --quiet {UNIT}")[0] == 0 + + +def main_pid() -> str: + return kde.sh(f"systemctl --user show --property MainPID --value {UNIT}").strip() + + +def answering() -> bool: + return kde.run("komorebic monitor-information")[0] == 0 + + +def managed_titles() -> list[str]: + """The titles of the windows komorebi has on the first workspace of the first monitor.""" + workspace = kde.state()["monitors"]["elements"][0]["workspaces"]["elements"][0] + return [ + window["details"]["title"] + for container in workspace["containers"]["elements"] + for window in container["windows"]["elements"] + ] + + +def daemon_log() -> str: + return machine.execute(f"cat {LOG}")[1] + + +print("== 1. logging in starts komorebi") +checks.check("the session started the module's unit", kde.wait_for(active, timeout=60)) +checks.check("its daemon answers komorebic", kde.wait_for(answering, timeout=60)) + +pid = main_pid() +command = kde.sh(f"tr '\\0' ' ' < /proc/{pid}/cmdline").split() +print(f" the unit runs: {' '.join(command)}") +checks.check("the unit runs bin/komorebi", command[0].endswith("/bin/komorebi")) +checks.check("... at the module's log level", command[1:] == ["--log-level", "debug"]) +environment = kde.sh(f"tr '\\0' '\\n' < /proc/{pid}/environ").splitlines() +path = next((line[len("PATH=") :] for line in environment if line.startswith("PATH=")), "") +checks.check( + "... with the PATH of the user's session", + path.split(":") + == ["/run/wrappers/bin", "/etc/profiles/per-user/komorebi/bin", "/run/current-system/sw/bin"], +) + +print("== 2. a window opened in the session is tiled") +width = json.loads(kde.komorebic("monitor-information"))[0]["size"]["right"] + + +def asked() -> Rect | None: + return daemon.asked(daemon_log(), "tiled") + + +def tiled() -> bool: + """KWin has the window where komorebi asked, and that is a tile across the screen.""" + want, wid = asked(), kde.wid("tiled") + if want is None or wid == "": + return False + have = kde.rect(wid) + return ( + (have.x, have.y) == (want.x, want.y) + and 0 <= want.w - have.w < CELL + and 0 <= want.h - have.h < CELL + and want.w > width // 2 + ) + + +kde.spawn("foot -T tiled sleep 3000") +checks.check("the window opens", kde.wait_for(lambda: kde.wid("tiled") != "", timeout=60)) +checks.check("komorebi manages it", kde.wait_for(lambda: "tiled" in managed_titles(), timeout=30)) +checks.check("KWin has it on its tile", kde.wait_for(tiled, timeout=30)) +print(f" asked {asked()}, has {kde.rect(kde.wid('tiled'))}") + +print("== 3. systemd starts a komorebi that was killed again") +kde.systemctl("kill", "--signal=SIGKILL", UNIT) +checks.check( + "the unit runs a new daemon", + kde.wait_for(lambda: active() and main_pid() not in ("0", pid), timeout=30), +) +checks.check("... which answers komorebic", kde.wait_for(answering, timeout=60)) +checks.check( + "... and manages the window again", + kde.wait_for(lambda: "tiled" in managed_titles(), timeout=30), +) + +print("== 4. a stop is not a failure") +kde.systemctl("stop", UNIT) +checks.check("stopped with SIGTERM, the unit is inactive", not active()) +checks.check("... and not failed", not failed()) +kde.systemctl("start", UNIT) +checks.check("started again, its daemon answers", kde.wait_for(answering, timeout=60)) +kde.komorebic("stop") +checks.check("komorebic stop stops the unit", kde.wait_for(lambda: not active(), timeout=30)) +checks.check("... which is not failed", not failed()) +checks.check("... and not started again", not kde.wait_for(active, timeout=5)) + +checks.finish() diff --git a/nix/tests/vm/suites/render-smoke/default.nix b/nix/tests/vm/suites/render-smoke/default.nix index 743bab13..73d4e563 100644 --- a/nix/tests/vm/suites/render-smoke/default.nix +++ b/nix/tests/vm/suites/render-smoke/default.nix @@ -2,4 +2,6 @@ tier = "slow"; kind = "session"; timeoutMinutes = 10; + # the session draws without komorebi: a tiled terminal would cover the desktop this test looks at + node.services.komorebi.enable = false; }