starred/komorebi
1
0 Fork 0
mirror of https://github.com/LGUG2Z/komorebi.git synced 2026-11-15 21:32:26 +01:00
Code Issues 87 Packages Projects Releases 11 Wiki Activity

docs: build-and-test.md, the commands and the known flakes per platform

Browse Source 
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.
This commit is contained in:
LGUG2Z committed 2026-11-05 15:03:26 -08:00
1 parent 0008c6c27d
commit 9c2c50cc40
1 file changed
+231
Download Patch File Download Diff File Expand all files Collapse all files
docs/dev/build-and-test.md
+231
View File
@@ -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/<scenario>/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.