Files
komorebi/docs/dev/unified-binaries.md
T
LGUG2Z 374269646e docs: unified komorebi, komorebic and komorebi-bar packages (layout, migration order, risks)
Records the spike (revisions on wip-u-pkg-spike, nothing landed on wip-main): one root
workspace holds the Windows, KDE and macOS crates with one Cargo.lock (+41 packages), the
unified komorebic builds on all three targets, KDE tests pass unchanged except one test
that reads the package name. Recommends komorebic and bar as one crate with cfg(target_os)
modules and the daemon as three gated libraries behind one thin binary, lists the migration
order, risks, gates (compile, S oracle, nix, e2e, KDE VM, Mac hand check) and the file moves
that conflict with the open wip-u-* stacks.

Verified: Windows cargo check -p komorebic, KDE check and 879 of 880 tests, macOS fake-CC
check, all on the spike tree. Not verified: nix builds, e2e, VM, any macOS link or run.
2026-10-31 11:27:53 -07:00

15 KiB

One komorebi, one komorebic, one komorebi-bar

Goal: three packages and three binaries that build on Windows, KDE (Linux) and macOS, the platform chosen by cfg(target_os) (generics, cfg_select!, exhaustive match; no macros as a design tool). This file records a spike (throwaway revisions on bookmark wip-u-pkg-spike, titled spike:; nothing landed on wip-main), the layout it recommends, the migration order, the risks and the gates.

Measured on wip-main 633e7453 with the light gates only (nice -n 19, 3 jobs, persistent target dirs, COMMIT_HASH=dev); no nix build, no e2e, no VM. macOS is type-checked with the fake CC only: it was never linked or run.

What the spike did

  1. spike: one root workspace ... (rev yuuyzssl): the 10 KDE and macOS member crates became members of the root workspace. Their two [workspace] manifests were deleted, their workspace = true dependencies were written out, packages renamed (komorebi-linux, komorebic-linux, komorebi-client-linux, komorebi-hotkeys-linux, version-linux, and -macos for the macOS ones including komorebi-bar-macos); binary and lib names stayed ([lib] name, [[bin]] name) so no source file changed. One Cargo.lock.
  2. spike: unified komorebic package by #[path] includes: the root komorebic package became the unified one. src/main.rs is a cfg_select! over target_os that includes the old Windows main.rs (moved to windows.rs) and, by #[path], the KDE and macOS main.rs where they live. Dependencies are in [target.'cfg(...)'.dependencies] tables. Edits to the old files: fn main became pub fn main; crate::HOME_DIR became super::HOME_DIR in KDE hotkeys.rs.
  3. spike: target-gate the macOS daemon crate: objc2 and friends under [target.'cfg(target_os = "macos")'.dependencies] plus #![cfg(target_os = "macos")] in komorebi-macos, to test cargo check --workspace on a foreign target.

The script that did step 1 is S/pkg-spike.py (scratchpad; rerunnable on a fresh wip-main).

Results

question result
One lock resolves? Yes. 859 packages (root) -> 900. All 859 Windows entries unchanged. The KDE lock had 644 and the macOS lock 786 entries, so +41 only. Crates with more than one version: 81 -> 95 (the sysinfo 0.38/0.39/0.40, dirs 6/7, parking_lot 0.12/0.13, shadow-rs 1/2, netdev 0.40/0.46 splits coexist; nothing needs unifying).
Locked versions kept? Not exactly: crates that only KDE or macOS use were re-resolved to newest: zbus/zbus_macros 6.1 -> 6.2, zbus_utils, zruntime, sysinfo 0.40.0 -> 0.40.1, libz-sys, unicode-width. Pin with cargo update zbus@6.2.0 --precise 6.1.0 (needs the name@version spelling) if the VM suites must see the old versions.
Windows cargo check -p komorebic --target x86_64-pc-windows-msvc (nix develop) passes, 14.8 s wall warm (11.2 s compile); unified komorebic also passes, 7 s.
KDE native cargo check -p komorebi-linux -p komorebic-linux passes; 1 m 38 s cold into a fresh lite target dir. Unified komorebic on Linux passes (1.4 s after touch) when openssl is available (see risk 2).
KDE tests unchanged cargo test -p komorebi-linux --lib: 294 passed. --test schemas -- --test-threads=1: 5 passed. All four KDE packages, --no-fail-fast, 1 m 26 s warm: 879 passed, 1 failed. The failure is tests/version.rs: komorebi-linux 0.1.0 instead of komorebi 0.1.0 (clap takes the command name from CARGO_PKG_NAME); a renamed package needs #[command(name = "komorebi")]. Nothing else depends on the package name.
macOS fake-CC cargo check --target aarch64-apple-darwin -p komorebi-macos -p komorebic-macos -p komorebi-bar-macos --all-targets --locked passes, 32 s warm (6 warnings in the bar, as before). Unified komorebic on macOS passes, 12 s. Type-check only.
Feature unification Resolver 2 keeps komorebi-layouts/darwin off Windows: cargo tree -p komorebic --target x86_64-pc-windows-msvc -e features -i komorebi-layouts shows only default, the macOS package shows darwin. This holds only while the package that asks for darwin is not in the same build; cargo ... --workspace on one target selects them all (see risk 3).
cargo check --workspace for Windows (what clippy, fmt, nextest and crane do today) FAILS in 52 s: objc2 only works on Apple platforms. With objc2 target-gated and #![cfg(target_os = "macos")], komorebi-macos compiles empty on Windows (spike 3), so the fix is to gate every foreign-platform crate, not to exclude them. Done for one crate only.
Same dependency key, different path per target REJECTED by cargo: Dependency 'komorebi-client' has different source paths depending on the build target. Same for version. So the unified package must use one key per platform (komorebi-client-linux, komorebi-client-macos, ...) and the platform module must alias it (extern crate komorebi_client_linux as komorebi_client; at the root, or use komorebi_linux as komorebi; at the top of each platform module). The spike used extern crate.
Compile time No extra cost on a target: a build selects its own target's dependency tables, so Windows never sees zbus or objc2 and Linux never sees windows. The only added cost is resolution (cargo metadata 6.5 s with the network).

Option A or B

Measured size of what would have to move into #[cfg(target_os)] mod of one crate (Option B): daemon crate:: paths: Windows 669, KDE 447, macOS 587 (35,149 / 32,932 / 34,505 lines, 3 lib+bin crates each with their own tests and a komorebi-client that re-exports them); bar 111 / 90 (7,710 / 5,551 lines); komorebic 0 (1,467 / 807 / 1,537 lines).

Recommendation:

  • komorebic: B. One package komorebic, src/main.rs = cfg_select! choosing mod windows, mod linux, mod macos (each the present main.rs, hotkeys.rs for Linux), one clap command name, target-gated dependencies. Zero crate:: rewrites, so the files move whole. This is what the spike built (with #[path] instead of the final moves).
  • komorebi-bar: B, as bar-unification.md already plans (src/bar/{mod,windows,macos}.rs, os/{windows,macos}.rs); needs the bar stack integrated first.
  • komorebi (daemon): A. Keep three library crates, rename to komorebi-windows, komorebi-linux, komorebi-macos (distinct lib names, komorebi_windows etc.), each gated to its OS (#![cfg(target_os = ...)], target-gated dependencies, so --workspace works everywhere), each keeping its own crate:: paths and its own tests (KDE's 881 run unchanged but for the name). One thin komorebi binary package: src/main.rs is a cfg_select! over the three daemons' main bodies (each daemon's present main.rs becomes pub fn run() of its library). Option B for the daemon would be a rewrite of about 1,700 crate:: paths (669 + 447 + 587) for no behavioural gain, and it would put KDE's tests and the VM suites on a moving target.
  • komorebi-client: one package with src/{windows,linux,macos}.rs (211 / 394 / 225 lines, almost all pub use komorebi::...), each starting with use komorebi_windows as komorebi; and so on.

Migration order

Every revision keeps the three existing trees building with their present gates. "Gate" says what must pass before it counts as landed: C compile (fast-check, the three checks), S the CLI oracle (S/step4/oracle-check.sh, byte-identical for all three platforms; it reads komorebic/src/main.rs of each tree, so it needs its paths updated in the revision that moves a file), N nix evaluation (nix flake show), NB a nix build of the checks in an idle window, E Windows e2e, V KDE VM fast.

  1. Prerequisites, no moves (any time, small): explicit #[command(name = ...)] on the three CLIs; build.rs of komorebic stops fetching applications.json over the network (the file is checked in; a build script that needs reqwest, and so openssl, on Linux is what stopped the unified package building natively); pub fn main and crate:: -> super:: in the komorebic files. Gates C, S. Not behaviour.
  2. Package renames inside the present workspaces (KDE: komorebi-linux and so on; macOS the same; Windows daemon komorebi-windows last), with [lib] name and [[bin]] name unchanged. Gates C, N; the Windows daemon rename is E (the executable's inputs change).
  3. Workspace merge: delete komorebi-for-kde/Cargo.toml and komorebi-for-mac/Cargo.toml, add their crates to the root members, write out the inherited dependencies, one lock (+41 packages), add .cargo/config.toml with [env] COMMIT_HASH (KDE's file moves from komorebi-for-kde/.cargo; cargo reads it from the working directory upward only). Same revision gates every foreign crate (#![cfg(target_os)], target-gated dependencies) so --workspace works on all targets. Gates C on all three, plus KDE tests unchanged. Cargo-wise this is one revision (the spike's script); it must not be split without breaking --locked.
  4. Flakes, same integration as 2 (nix cannot be half-merged): the root flake builds all three; the two nested flakes already take the whole repository as their source (lib.mkOutputs), so they become thin: workspaceArgs change from a subdirectory workspace to -p <package>. The KDE source filter must list the new member directories. Gates N, then NB (deps, clippy, nextest of each system), then V.
  5. komorebic unified by #[path] (spike 2, minus the hacks): new komorebic/src/main.rs, target tables, aliases. The old komorebic-linux/-macos packages stay until step 5 so the old names work. Gates C, S, and E for komorebic.exe (the Windows main moves to windows.rs).
  6. komorebic real moves, one platform per revision: komorebi-for-kde/komorebic/src/* to komorebic/src/linux/, the macOS one to komorebic/src/macos/, tests with them, then delete the old packages. Pure moves (jj does not follow moves, so each is a delete/modify conflict if another stack touches those files; today none does). Gates C, S, tests.
  7. komorebi-client unified (modules per platform), same pattern. Gates C, E (Windows client is in the closure of komorebi.exe).
  8. komorebi-bar unified after the bar stack integrates: bar-unification.md plan; Windows bar screenshot gate and the Mac hand check are owed by that stack.
  9. Daemon: three libraries gated to their OS and one thin komorebi package with the cfg_select! main. KDE main.rs and the Windows main.rs become run() in their libraries. Gates C, E, V, Mac hand check.
  10. Cutover: one flake output per binary, old per-platform package names, justfile, CI (.github/workflows), docs paths, release version (0.1.42 / 0.1.0 / 0.1.1 become one).

Risks

  1. One lock for three platforms: a cargo update for one platform moves the others; crane's dummy source includes every member's manifest and the lock, so any dependency change rebuilds the dependency derivation of all three systems (today a KDE-only lock change cannot touch Windows). The COMMIT_HASH-constant fix (flow finding 1) must be in first or every commit rebuilds ~1,000 crates.
  2. build.rs fetching over the network is not usable in a unified package (openssl on Linux); see step 0.
  3. --workspace commands (clippy, fmt, nextest, crane) select every member on every target: every foreign crate must compile empty (spike 3 shows it works for the daemon; only one crate was converted). Without it, feature unification would also turn komorebi-layouts/darwin on for Windows in a whole-workspace build.
  4. The one-key-one-path rule forces distinct dependency keys and aliases per platform module.
  5. CARGO_BUILD_TARGET is set by the root nix develop shell, so native Linux checks must run outside it (as fast-check does) or pass --target x86_64-unknown-linux-gnu.
  6. Command names and --version text come from CARGO_PKG_NAME/the version crate: pin them or the KDE version test and the docs oracle change. shadow-rs major versions differ (2 on Windows, 1 on macOS); the unified komorebic build script can only use one.
  7. The KDE VM suites rebuild on any change to the KDE closure: the merge is one full V run.
  8. Tests that use CARGO_BIN_EXE_* or relative paths (tests/schemas.rs writes beside the manifest) must move with their package; not exercised beyond the spike.

Gates by step, in short

Compile only: 0, 4 (but see E), 5, 6 at the Rust level; nix evaluation only: 3 until built. Needs e2e (Windows guest): anything that changes an input of komorebi.exe, komorebic.exe or the client (tools/e2e-needed says: 1 for the Windows daemon, 4, 6, 8). Needs the KDE VM: 2, 3, 8. Needs a Mac, by hand: 4, 7, 8, 9.

Mac hand check (type-check proves none of it): komorebic --version and --help show the macOS command set and the name komorebic; komorebic start finds and starts komorebi, stop stops it; komorebic docgen unchanged; komorebi --version; the daemon starts, tiles and komorebic state answers; komorebi-bar opens, --schema equals komorebi-for-mac/schema.bar.json; the embedded applications.json is the macOS one; otool -L of each binary lists no Windows or Linux-only library.

Conflicts with the open stacks (sequence in a quiet period)

Paths touched by each bookmark relative to wip-main:

bookmark touches moves in this plan that conflict
wip-u-kfw komorebi/src/**, crates/komorebi-backend/** daemon rename and any move of komorebi/ (steps 1 Windows, 8)
wip-u-kfm komorebi-for-mac/komorebi/src/**, crates/komorebi-backend/** macOS daemon rename and moves (1, 8)
wip-u-kfde komorebi-for-kde/komorebi/{src,tests}/** KDE daemon rename (1) and moves (8); tests are edited
wip-u-bar Cargo.lock, komorebi-for-mac/Cargo.lock, komorebi-bar/src/**, komorebi-for-mac/komorebi-bar/src/**, crates/komorebi-bar-core step 2 (locks, manifests) and step 7
wip-u-settings Cargo.toml, Cargo.lock, crates/komorebi-settings step 2 (root manifest and lock)
wip-u-nix flake.nix, komorebi-for-kde/flake.nix, komorebi-for-kde/nix/** step 3

Not touched by any open stack, so safe now: komorebic/** (all three), the komorebic tests, the version crates, the komorebi-client crates (steps 0, 4, 5, 6 are free of conflicts except the lock and root manifest lines of step 2/4). Hard conflicts: every Cargo.lock and the root Cargo.toml members list (resolve by taking one side and running cargo metadata; never hand-merge a lock), flake.nix lines for the extracted binaries. Suggested order: integrate kfw, kfm, kfde, bar, settings, nix first; then steps 0 and 1; then 2 and 3 as one integration; the rest in any order, daemon (8) last.

What landed

Only this file. The spike revisions are on wip-u-pkg-spike and can be dropped or cherry-picked. Step 0 and the renames were not landed because they only pay off with step 2, which edits the locks and manifests that three open stacks edit.