From 9c2c50cc40ad405eb0fd3ee97e68279ea52baf08 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 15:03:17 -0700 Subject: [PATCH] docs: build-and-test.md, the commands and the known flakes per platform One page with the exact commands for each platform, so nobody has to reconstruct them from the flakes and the progress notes: - Windows: nix cross build of the binaries, the crane checks (clippy is the pre-landing gate), the e2e-tests check, native tests of the neutral crates; - KDE: cargo check/test with the right package names (the unit tests are in komorebi-linux, not the thin komorebi binary package), the schema test with one thread, the kfde-* checks of the root flake, the VM suites with `just vm`, the tier lists, E2E_ONLY and KOMOREBI_RECORDER for VM runs; - macOS: cargo build/test/clippy with `-p komorebic -p komorebi -p komorebi-bar`, never `-p komorebic-macos` together with `-p komorebic`, and the Linux-only type-check; - Windows e2e: `nix run .#e2e-windows`, the `bar` scenario, E2E_ONLY, trace, recorder, KEEP_GUEST, SCALE, STATE, bins from another commit; - a what-to-run table and the known flakes with counts, summarised from the flake registry kept by the gate runs (no personal paths). It also records that komorebi-for-kde/justfile still assumes a KDE-only workspace (`just check` would build the Windows crates). Verified by running: `cargo metadata --no-deps` (package names), `cargo check -p komorebi-linux -p komorebi -p komorebic` in komorebi-for-kde (ok), `nix eval --json .#legacyPackages.x86_64-linux.vmTiers` (the tier lists match). Other commands were read from flake.nix, justfiles and the e2e README, not run. --- docs/dev/build-and-test.md | 231 +++++++++++++++++++++++++++++++++++++ 1 file changed, 231 insertions(+) create mode 100644 docs/dev/build-and-test.md diff --git a/docs/dev/build-and-test.md b/docs/dev/build-and-test.md new file mode 100644 index 00000000..c88fc533 --- /dev/null +++ b/docs/dev/build-and-test.md @@ -0,0 +1,231 @@ +# Build and test, per platform + +Status (wip-cand4): current. Every command below was read from `flake.nix`, the justfiles, the Cargo +manifests or the e2e README; the ones marked "ran" were run on the Linux host at this revision (cheap checks +only: `cargo metadata --no-deps`, `cargo check -p komorebi-linux -p komorebi -p komorebic` in +`komorebi-for-kde/`). Everything else, including every nix build, e2e and VM run, is documented but was not +run for this page. macOS cannot be built or run on Linux; Linux can only type-check it. + +The map of the repository is [ARCHITECTURE-UNIFIED.md](ARCHITECTURE-UNIFIED.md). Package names in this +repository (`cargo metadata --no-deps`, ran): `komorebi` (the daemon, `komorebi-daemon/`), `komorebic`, +`komorebi-client`, `komorebi-bar`, the libraries `komorebi-windows`, `komorebi-linux`, `komorebi-macos`, the +shims `komorebic-linux`, `komorebic-macos`, `komorebi-client-linux`, `komorebi-client-macos`, +`komorebi-bar-macos`, and `komorebi-backend`, `-bar-core`, `komorebic-core`, `-collections`, `-config`, +`-core`, `-protocol`, `-settings`, `-transport`. + +## 0. General rules + +- Platform is chosen by `cfg(target_os)`: `cargo build -p komorebi -p komorebic -p komorebi-bar` builds the + program of the OS you are on. The Windows daemon is only buildable for the Windows target (cross build in + section 1); on Linux `-p komorebi` is the KDE daemon, on macOS the macOS one. +- Never put `komorebic` and `komorebic-linux`/`komorebic-macos` in one command (same binary name). The shims + stay until the cutover. +- Without a `.git` (a jj workspace) the build script of the macOS and KDE trees needs `COMMIT_HASH=dev`; the + `nix flake check --no-build` command fails with `attribute 'dirtyRev' missing` for the same reason. Do not run + `nix flake check` on the root flake at all (it builds the VM suites); name the check. +- Text edits under `komorebi-for-kde/` and `komorebi-for-mac/` change those trees' nix derivations (they are + inputs); a docs-only edit elsewhere does not, because the commit stamp is a constant in the checks + (`COMMIT_HASH=nix-check`) and only `packages.default` carries the real commit. +- Heavy builds and e2e should not run at the same time as a timing-sensitive e2e: the Windows `commands` + scenario is the most sensitive (section 6). + +## 1. Windows (cross build from Linux via nix) + +Binaries (the flake cross-compiles to `x86_64-pc-windows-msvc` with an xwin SDK): + +```sh +nix build .#komorebi .#komorebic .#komorebi-bar # result*/bin/*.exe; also komorebic-no-console, komorebi-gui, komorebi-shortcuts, komorebi-testwin +nix build .#default # komorebi-full: everything, with the real commit stamp +``` + +Checks (crane; the clippy one is the pre-landing gate, about 3.5 min warm deps; the dependency derivation is +shared by all of them): + +```sh +nix build -L --no-link .#checks.x86_64-linux.komorebi-workspace-clippy +nix build -L --no-link .#checks.x86_64-linux.komorebi-workspace-nextest +nix build -L --no-link .#checks.x86_64-linux.komorebi-workspace-fmt .#checks.x86_64-linux.komorebi-workspace-toml-fmt .#checks.x86_64-linux.komorebi-workspace-deny +nix build -L --no-link .#checks.x86_64-linux.e2e-tests # the Python of the e2e (pytest), no guest needed +``` + +Quick loop without nix (what `fast-check` runs; clippy of the Windows tree from the nix dev shell): + +```sh +nix develop --command cargo clippy --workspace --locked --all-targets -- -D warnings +``` + +On a Windows machine itself: `just build` / `just install` (the root `justfile`, PowerShell), or +`cargo build -p komorebi -p komorebic -p komorebi-bar --locked`. + +Platform-neutral crates test natively on Linux, with no cross toolchain: `cargo test -p komorebi-protocol +-p komorebi-config -p komorebi-collections -p komorebi-core -p komorebi-backend -p komorebi-settings +-p komorebi-transport -p komorebic-core -p komorebi-bar-core -p komorebi-layouts -p komorebi-scrolling`. + +## 2. KDE Plasma (native Linux) + +From `komorebi-for-kde/` (cargo finds the root workspace; a C compiler is needed, `nix shell nixpkgs#gcc -c` +or the dev shell): + +```sh +cargo check -p komorebi-linux -p komorebi -p komorebic # ran, 27 s with a warm target +cargo test -p komorebi-linux --lib # the daemon's unit tests (294 passed at the step-8 measurement) +cargo test -p komorebi-linux --test schemas -- --test-threads=1 # the schema oracle; shares a pid-only socket path, keep one thread +cargo test -p komorebi -p komorebic -p komorebi-client -p komorebi-hotkeys # daemon-binary, CLI and client tests (tests/linux_*.rs) +``` + +A single test file: `cargo test -p komorebi-linux --test NAME` (the files are in `komorebi-for-kde/komorebi/tests`). +The `-p komorebi --lib` that older notes use is the thin binary package now: the unit tests are in +`komorebi-linux`. + +Run `tools/kde-closure-check` after any dependency change in the KDE tree or the crates it uses: the KDE +flake takes only the crates listed in `komorebi-for-kde/nix/root-crates.json`. + +KDE nix checks (no VM): from the root flake they are prefixed `kfde-`, and the VM checks are left out: + +```sh +nix build -L --no-link .#checks.x86_64-linux.kfde-komorebi-workspace-clippy +nix build -L --no-link .#checks.x86_64-linux.kfde-komorebi-workspace-nextest +# also kfde-komorebi-workspace-{fmt,toml-fmt,deny,doc}, kfde-nix-options-validation, kfde-nixos-module-eval, +# kfde-keybindings-fixtures, kfde-schema-fresh +nix build -L .#packages.x86_64-linux.kfde-komorebi .#packages.x86_64-linux.kfde-komorebic +``` + +Inside `komorebi-for-kde/` the same checks have no prefix (`nix build .#checks.x86_64-linux.NAME`). +`komorebi-for-kde/justfile` (`just check`, `just docgen`, `just jsonschema`) still assumes a KDE-only +workspace: `just check` runs `cargo test --workspace`, which would build the Windows crates on Linux. Use the +commands above; `just vm NAME` and `just nixgen` are fine. + +### KDE VM suites + +Each suite under `komorebi-for-kde/nix/tests/vm/suites/NAME` boots NixOS with Plasma and KWin; they need KVM +(nested is enough under WSL2; `nix run .#wsl2-probe` from `komorebi-for-kde/` measures it). + +```sh +# from komorebi-for-kde/ +just vm NAME # = nix build -L .#checks.x86_64-linux.vm-NAME +just vm-all # every suite in the order of the flake +# from the repository root (the VM checks are left out of the root `checks`, the suites are here) +nix build -L .#legacyPackages.x86_64-linux.kfde-vm.NAME +# from komorebi-for-kde/: the names of each tier as JSON (ran; CI reads it) +nix eval --json .#legacyPackages.x86_64-linux.vmTiers +``` + +Tiers (the `tier` in each suite's `default.nix`; CI runs `fast` on every pull request, `slow` on master): + +- fast: `check hotplug commands kwin-restart kwin-events scrolling workspace-rules core-e2e kwin-contract kwin + workspace-switch stacks module placement user-maximize run-kde` +- slow: `client-geometry restart-survival keys-whkd core-lock keys-sxhkd render-smoke drag-resize rdp features + focus-follows-mouse latency keys-engine live-resize lock-sleep look keys-skhd keys-static wallpaper` +- `vm-lib` (a check, not a suite) runs the unit tests of the VM library; no VM boots. + +To run only some steps of a suite: `E2E_ONLY=stacks,monocle nix build --impure .#checks.x86_64-linux.vm-core-e2e -L` +(from `komorebi-for-kde/`; a substring of the printed `module.function`; `KFDE_ONLY` is the old name). +To record a run: `KOMOREBI_RECORDER=$(nix build ~/komorebi-recorder#komorebi-recorder --no-link --print-out-paths) +nix build --impure .#checks.x86_64-linux.vm-core-lock -L` (the recorder's repository is private; `core-e2e` and +`core-lock` keep `recording-NAME.tar.gz`). Details, the library and how to add a suite: +[komorebi-for-kde/docs/dev/vm-tests.md](../../komorebi-for-kde/docs/dev/vm-tests.md). The suites use a daemon +built once with the constant stamp, so a new commit does not rebuild it. + +## 3. macOS + +On a Mac (aarch64-darwin), from the repository root (a `.git` checkout, or `COMMIT_HASH=dev` in the +environment). These are the commands for the Mac Mini; none has been run on a Mac against wip-cand4 unless +[macos-handcheck.md](macos-handcheck.md) says so: + +```sh +cargo build --locked -p komorebi -p komorebic -p komorebi-bar +cargo clippy --locked -p komorebi -p komorebi-macos -p komorebic -p komorebi-client -p komorebi-bar -p komorebi-bar-core --all-targets -- -D warnings +cargo test --locked -p komorebi-macos -p komorebic -p komorebi-client -p komorebi-bar-core -p komorebi-bar +cargo build --locked --features deadlock_detection -p komorebi # the feature is forwarded +target/debug/komorebi --version # komorebi 0.1.0 (the macOS version crate) +target/debug/komorebic --help; target/debug/komorebic docgen --output /tmp/docs-mac +target/debug/komorebi-bar --schema | cmp - komorebi-for-mac/schema.bar.json +``` + +Never `-p komorebic-macos` together with `-p komorebic` (the shims `komorebic-macos`, `komorebi-client-macos` +and `komorebi-bar-macos` still build alone). Before any change that touches macOS code, run the unit tests on +the Mac first: nothing else can run them. After that walk [macos-handcheck.md](macos-handcheck.md). + +On Linux, macOS can only be type-checked, through a fake C compiler and the target +`aarch64-apple-darwin` (`tools/fast-check` does it; it cannot link or run): + +```sh +COMMIT_HASH=dev cargo check --target aarch64-apple-darwin --workspace --all-targets # with CC_aarch64_apple_darwin set to a fake cc +``` + +Nix, on a Mac: the checks of `komorebi-for-mac/flake.nix` (`komorebi-workspace-{clippy,fmt,toml-fmt,deny,nextest}`, +`nix-options-validation`, `darwin-module-validation`). From Linux they can be evaluated only +(`nix flake show --all-systems`, `nix eval`), which proves nothing builds. Through the root flake they are +`kfm-*`. + +## 4. Windows e2e (QEMU guest) + +Full text: `e2e/platforms/qemu_windows/README.md` (building the golden image, every variable). Short form: + +```sh +E2E_GOLDEN=golden nix run .#e2e-windows -- OUT SCENARIO... # e.g. OUT tiling focus commands +E2E_GOLDEN=golden KOMOREBI_E2E_SCALE=1.5 nix run .#e2e-windows -- OUT bar # the komorebi-bar scenario +``` + +The app uses this checkout's binaries, built with the constant stamp `e2e` (so a docs-only commit reuses them); +the commit under test is `KOMOREBI_E2E_COMMIT` (default: the flake revision). To test another commit: +`build-ref.sh REF bins` then `KOMOREBI_E2E_BINS=bins ...` (`bins` needs `komorebi-bar.exe` for `bar`). + +| Variable | Effect | +|---|---| +| `E2E_ONLY=word,word` | run only the steps whose printed name contains a word (a rerun of one step) | +| `KOMOREBI_E2E_LOG_LEVEL=trace` | the daemon's log level (`debug`, `trace`) | +| `KOMOREBI_E2E_RECORDER=DIR` | record with komorebi-recorder (a folder with `komorebi-recorder.exe`); comes back as `recording.zip` | +| `KOMOREBI_E2E_KEEP_GUEST=1` | keep the guest's run directory (overlay, TPM state) instead of deleting it | +| `KOMOREBI_E2E_SCALE=1.5` | every wait is 1.5 times as long, for a busy host | +| `KOMOREBI_E2E_STATE=DIR` | restore guests from a saved state (3 s instead of 50-90 s start) | +| `KOMOREBI_E2E_CAPTURE=DIR` | save raw `komorebic state` fixtures | +| `SWEEP_TWO_DISPLAYS=1` | `commands` adds a second display | + +Keep output and run directories on a short path (unix socket paths are limited to about 108 bytes). Each +scenario gets its own guest (about 4 vCPU and 6 GB). Results are in `OUT//result.json`; trust it over +the printed line. `docs/dev/bar-e2e.md` describes the `bar` scenario. + +A change to the Windows daemon or bar needs these before it is considered landed (commit types BEHAVIOUR): +`commands`, plus the scenario of the cluster named in the revision body (see backend-switch.md for the table). + +## 5. What runs where (summary) + +| Change touches | Run | +|---|---| +| `crates/*` (not bar/komorebic) | section 1 native crate tests, then Windows clippy (section 1), KDE (section 2) and macOS type-check (section 3) | +| `komorebi/` (Windows daemon) | Windows clippy and nextest, then e2e (section 4) | +| `komorebi-for-kde/` | section 2 cargo, then KDE checks, VM `fast` tier | +| `komorebi-for-mac/` | macOS type-check on Linux; build and tests on a Mac | +| `komorebi-bar/`, `komorebi-bar-core` | Windows clippy, `cargo test -p komorebi-bar-core`, macOS type-check, e2e `bar` | +| `komorebic*`, `komorebic-core` | `cargo test -p komorebic-core` (CLI doc oracle), all three platforms' checks | +| `*.nix`, `flake.lock` | evaluation only (`nix eval ...drvPath`) before a build | +| docs only | nothing, unless under a platform tree (see section 0) | + +## 6. Known flakes + +Policy: on any e2e or VM failure, check this list by check name and by log signature first; do not soak to +re-prove a known flake. Write rates as `failures/runs` with the commit and host load. A known flake needs +`baseline-seen` evidence (it occurred before the consolidation) or at least 3 occurrences with the same +signature. A name-only match gets one rerun on a calm host at `trace` with logs kept; no match gets one calm +rerun, and a second failure is a regression candidate to bisect by revision. A soak is only for a candidate +that failed twice or a flake whose rate looks more than 2x higher with at least 3 failures. Passing under +load stays a pass; failing under high load is not evidence of a regression. A full `commands` sweep takes 4 +to 6 minutes, so the `E2E_ONLY` runs come first. + +| Check | Platform | What is seen | Rate (from a measured set) | +|---|---|---|---| +| `commands`, daemon stops answering `komorebic state` | Windows | the daemon logs nothing from any thread for 3 to 3.6 s after answering `State`; the reply write hits a closed socket (`os error 10054`); `border manager: stuck for ~3000 ms in locking the window manager`; `could not acquire window manager lock`. Cause not found (host I/O stalls are a candidate) | 1/10 sweeps before the consolidation, 1/12 after; probe 0.35% vs 0.39% of calls | +| `lifecycle_hidden` (monocle after crash) | Windows | no signature captured (capture at `trace` next time) | 1/10 before, 2/12 after | +| `resize` (drag checks `win2:bottomleft`, `win3:top`) | Windows | drag checks fail, pass on rerun; documented as flaky | 1 failure in the first run, passed twice | +| daemon does not start (`failed call to AllowSetForegroundWindow after 5 retries`) | Windows | the scenario prints "did not run, counted as 1 failed", no `result.json`; only seen at load 6.6-8 | candidate, 4/~45 starts at that load vs 0/~150 at load 3-5 | +| `hotplug` with the recorder on (`AgentLost ... during exec tasklist`) | Windows | after the display unplug, in the recorder collection step; the rerun passed | candidate, 1 occurrence | +| `maximizing.user`, `placement` (integer case), `unknown_monitor` (2) | Windows | not flakes: the same 4 checks fail on every commit (stale known-failure markers) | fix or re-mark them | +| `focus_follows_mouse` "did not run" | Windows | reporting quirk of the runner, `result.json` says 15/0 | ignore the line | +| `vm-commands`, `vm-core-e2e` | KDE | `commands.py` (guest D-Bus stops replying, BrokenPipe), `handover.py` ("win3 is inside the work area and not on a tile"), `lifecycle_hidden.py`, `manage_rules.py` (window never appeared, 30 s), `core_e2e.py` (KWin script never reported in) | 0 green in 6 runs before the consolidation at host load 25 to 190; load-dependent is plausible, not shown; no gate decision until one calm-host run exists | +| `golden` test of `komorebi-protocol` | native | "5 passed; 1 failed" once, six reruns passed, text not captured | 1 occurrence; keep the text if it recurs | +| KDE `tests/schemas.rs` | native | shares a pid-only socket path | keep `--test-threads=1` | + +Observed rates are consistent with a wide range: 1 failure in 10 runs fits anything from about 0.3% to 45% per +run. Quote the counts, not "flaky". The source registry of the consolidation runs (with commits and logs) is +kept by whoever runs the gates; add new occurrences there and update this table when a rate changes.