mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-21 16:11:37 +01:00
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.
This commit is contained in:
1 parent
633e7453cd
commit
374269646e
1 file changed
+177
@@ -0,0 +1,177 @@
|
||||
# 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`.
|
||||
|
||||
0. 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.
|
||||
1. 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).
|
||||
2. 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`.
|
||||
3. 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`.
|
||||
4. `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`).
|
||||
5. `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.
|
||||
6. `komorebi-client` unified (modules per platform), same pattern. Gates C, E (Windows client is in the
|
||||
closure of `komorebi.exe`).
|
||||
7. `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.
|
||||
8. 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.
|
||||
9. 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.
|
||||
Reference in new issue
Block a user