From 30322bd68d339f6374b5ee4c8e474231cabf4d63 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sun, 1 Nov 2026 09:19:58 -0800 Subject: [PATCH] docs(dev): the flake, with the old-name to new-name table, and the nix commands of build-and-test docs/dev/flake.md (new): the layout of the one flake, the naming rule, the table of every old attribute (root flake, kfde-, kfm- and the nested flakes) and its new name, the inputs and why there are two nixpkgs (x86_64-darwin only), how the source of each platform is cut and why the stubs are needed, the check groups (the NixOS/VM checks are heavyChecks until the structure of the check sets is decided), the dev shells, what to run after an update. docs/dev/build-and-test.md: the nix commands use windows-*, linux-*, macos-* names, the final directories and legacyPackages..vm.NAME for a VM suite. Verified: not run as prose; the attribute names were evaluated by nix flake check --no-build --all-systems and the Windows ones built (see the flake revision). --- docs/dev/build-and-test.md | 103 +++++++++++------------ docs/dev/flake.md | 162 +++++++++++++++++++++++++++++++++++++ 2 files changed, 211 insertions(+), 54 deletions(-) create mode 100644 docs/dev/flake.md diff --git a/docs/dev/build-and-test.md b/docs/dev/build-and-test.md index cd145a19..cc3594eb 100644 --- a/docs/dev/build-and-test.md +++ b/docs/dev/build-and-test.md @@ -1,10 +1,9 @@ # 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. +Status: the nix commands name the outputs of the one root flake ([flake.md](flake.md) has the +old-name to new-name table and the layout). Commands marked "ran" were run on the Linux host at the revision +that made the flake; the rest are documented from `flake.nix`, the justfile, the Cargo manifests or the e2e +README. 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`, @@ -20,12 +19,13 @@ shims `komorebic-linux`, `komorebic-macos`, `komorebi-client-linux`, `komorebi-c 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. +- Without a `.git` (a jj workspace) the build script of the macOS and Linux crates needs `COMMIT_HASH=dev`. Do + not run a plain `nix flake check` on the root flake (it boots the VM suites); name the check, or run + `nix flake check --no-build --all-systems` for the evaluation only. +- Text edits under `komorebi-linux/`, `komorebi-hotkeys/` or `komorebi-macos/` change only that platform's nix + derivations (each platform builds from its own filtered source, `nix/workspace-src.nix`); a docs-only edit + elsewhere changes none, because the commit stamp is a constant in the checks (`COMMIT_HASH=nix-check`) and + only the native `default` and `windows-default` packages carry 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). @@ -38,7 +38,7 @@ workspace of the repository; none of them writes to the source tree. |---|---| | `tools/fast-check [--list] [--range \| --since REV]` | only the checks the touched paths need; warm in seconds (Windows clippy 8-9 s, KDE 1-3 s, macOS 2-3 s) | | `tools/e2e-needed [--since REV]` | does this diff change the Windows e2e binaries (`NO` carries a previous passing e2e over) | -| `tools/kde-closure-check` | the KDE source filter list matches the KDE cargo closure | +| `tools/kde-closure-check` | the Linux source filter list (`nix/linux/root-crates.json`) matches the Linux cargo closure | | `tools/mac-check.sh` | macOS type-check on Linux (fake C compiler `tools/cc-fake.sh`) | | `tools/trim-target`, `tools/gate-lock`, `tools/lite-env` | disk trimming, a heavy-gate lock, debug-info-off builds | @@ -49,24 +49,24 @@ The persistent target directories are under `$FAST_CHECK_SCRATCH` (default `~/.c 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 +nix build .#windows-komorebi .#windows-komorebic .#windows-komorebi-bar # result*/bin/*.exe; also windows-komorebic-no-console, -komorebi-gui, -komorebi-shortcuts, -komorebi-testwin +nix build .#windows-default # windows-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 +nix build -L --no-link .#checks.x86_64-linux.windows-clippy +nix build -L --no-link .#checks.x86_64-linux.windows-nextest +nix build -L --no-link .#checks.x86_64-linux.windows-fmt .#checks.x86_64-linux.windows-toml-fmt .#checks.x86_64-linux.windows-deny +nix build -L --no-link .#checks.x86_64-linux.windows-e2e-tests # the Python of the e2e (pytest), no guest needed ``` Quick loop without nix builds (what `tools/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 +nix develop --command cargo clippy --locked --all-targets -- -D warnings ``` On a Windows machine itself: `just build` / `just install` (the root `justfile`, PowerShell), or @@ -78,8 +78,7 @@ Platform-neutral crates test natively on Linux, with no cross toolchain: `cargo ## 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): +From the repository root (a C compiler is needed: `nix shell nixpkgs#gcc -c`, or `nix develop .#native`): ```sh cargo check -p komorebi-linux -p komorebi -p komorebic # ran, 27 s with a warm target @@ -88,40 +87,36 @@ cargo test -p komorebi-linux --test schemas -- --test-threads=1 # 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`). +A single test file: `cargo test -p komorebi-linux --test NAME` (the files are in `komorebi-linux/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` (see [tools/README.md](../../tools/README.md)) 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`. +Run `tools/kde-closure-check` (see [tools/README.md](../../tools/README.md)) after any dependency change in the KDE crates or the crates they use: the Linux +source takes only the crates listed in `nix/linux/root-crates.json`. -KDE nix checks (no VM): from the root flake they are prefixed `kfde-`, and the VM checks are left out: +KDE nix checks (no VM), prefixed `linux-`: ```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 +nix build -L --no-link .#checks.x86_64-linux.linux-clippy +nix build -L --no-link .#checks.x86_64-linux.linux-nextest +# also linux-{fmt,toml-fmt,deny,doc,bridge-js,schema-fresh,nix-options-validation,nixos-module-eval, +# keybindings-fixtures,plasma-guests-eval} +nix build -L .#komorebi .#komorebic # the native packages of the Linux system ``` -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. +`just check` runs `cargo test --workspace`, which would build the Windows crates on Linux. Use the commands +above; `just vm NAME` and `just nixgen-linux` 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). +Each suite under `nix/linux/tests/vm/suites/NAME` boots NixOS with Plasma and KWin; they need KVM +(nested is enough under WSL2; `nix run .#wsl2-probe` measures it). ```sh -# from komorebi-for-kde/ -just vm NAME # = nix build -L .#checks.x86_64-linux.vm-NAME +just vm NAME # = nix build -L .#legacyPackages.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 build -L .#legacyPackages.x86_64-linux.vm.NAME # the same suite as a test with a `driver` +# the names of each tier as JSON (ran; CI reads it) nix eval --json .#legacyPackages.x86_64-linux.vmTiers ``` @@ -133,12 +128,12 @@ Tiers (the `tier` in each suite's `default.nix`; CI runs `fast` on every pull re 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 run only some steps of a suite: `E2E_ONLY=stacks,monocle nix build --impure .#legacyPackages.x86_64-linux.vm.core-e2e -L` +(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 +nix build --impure .#legacyPackages.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 +[docs/linux/dev/vm-tests.md](../linux/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 @@ -154,7 +149,7 @@ cargo test --locked -p komorebi-macos -p komorebic -p komorebi-client -p komore 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 +target/debug/komorebi-bar --schema | cmp - schemas/macos/schema.bar.json ``` Never `-p komorebic-macos` together with `-p komorebic` (the shims `komorebic-macos`, `komorebi-client-macos` @@ -169,10 +164,10 @@ On Linux, macOS can only be type-checked, through a fake C compiler and the targ tools/mac-check.sh # = COMMIT_HASH=dev cargo check --target aarch64-apple-darwin ... --all-targets, CC set to tools/cc-fake.sh ``` -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-*`. +Nix, on a Mac: the `macos-*` checks (`macos-{clippy,fmt,toml-fmt,deny,nextest}`, +`macos-nix-options-validation`, `macos-darwin-module-validation`) and the packages `komorebi`, `komorebic`, +`komorebi-bar` of `aarch64-darwin`. From Linux they can be evaluated only (`nix flake check --no-build +--all-systems`, `nix eval`), which proves nothing builds. ## 4. Windows e2e (QEMU guest) @@ -210,12 +205,12 @@ A change to the Windows daemon or bar needs these before it is considered landed | 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-windows/` (Windows daemon) | Windows clippy and nextest, then e2e (section 4) | +| `komorebi-linux/`, `komorebi-hotkeys/` | section 2 cargo, then KDE checks, VM `fast` tier | +| `komorebi-macos/` | 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 | +| `flake.nix`, `nix/**`, `flake.lock` | `nix flake check --no-build --all-systems`, then the checks of the platform edited | | docs only | nothing, unless under a platform tree (see section 0) | ## 6. Known flakes diff --git a/docs/dev/flake.md b/docs/dev/flake.md new file mode 100644 index 00000000..6359693f --- /dev/null +++ b/docs/dev/flake.md @@ -0,0 +1,162 @@ +# The flake + +One `flake.nix` and one `flake.lock` at the repository root build, check and test the three platforms: +Windows (cross-built on Linux with xwin), KDE Plasma (native Linux) and macOS (native on an Apple machine). +The nested flakes of `komorebi-for-kde/` and `komorebi-for-mac/` and the `kfde-` and `kfm-` input prefixes are gone. + +## Layout + +| File | What it holds | +|---|---| +| `flake.nix` | the inputs and the list of modules; nothing else | +| `nix/common.nix` | the systems, `pkgs`, the formatter (treefmt), the pre-commit hook, the dev shells, the default overlay and the old-name aliases | +| `nix/lib.nix` | helpers: `repoFile` (a file of the repository as a store path of its own), `mkPkgs`, the workspace version, the systems of each platform, the manifest-only source | +| `nix/workspace-src.nix` | the source of one platform, cut from the one Cargo workspace (below) | +| `nix/windows/{build,flake-module}.nix` | the xwin SDK, the clang-cl environment, the crane derivations, the `windows-*` outputs, `e2e-windows` | +| `nix/linux/{build,flake-module}.nix` | the crane derivations of the KDE packages, the `linux-*` checks, the `vm-*` checks, the NixOS module, the Plasma guests | +| `nix/macos/{build,flake-module}.nix` | the crane derivations of the macOS packages, the `macos-*` checks, the darwin module | +| `nix/linux/*`, `nix/macos/*` | the NixOS module and options, the darwin module and options, the VM test suites, the KWin effects | + +## Naming rule + +The unprefixed names are the NATIVE build of the system: on Linux (`x86_64-linux`, `aarch64-linux`) they are +the KDE packages, on macOS (`aarch64-darwin`, `x86_64-darwin`) the macOS ones. The Windows cross-built outputs +are prefixed `windows-`. Checks are `-` (`windows-clippy`, `linux-nextest`, `macos-deny`), and +the VM tests keep their `vm-NAME` names. + +| System | Windows (`windows-*`) | Linux (native names, `linux-*` checks, `vm-*`) | macOS (native names, `macos-*` checks) | +|---|---|---|---| +| `x86_64-linux` | packages, apps, checks, `e2e-windows` | packages, apps, checks, VM tests | | +| `aarch64-linux` | packages, apps, checks | packages, apps, checks, VM tests | | +| `aarch64-darwin` | packages, apps, checks | checks and `legacyPackages.vm` (the fake desktop and the guests' definitions) | packages, apps, checks | +| `x86_64-darwin` | | | packages, apps, checks | + +## Old name -> new name + +The names of the root flake before this change (the Windows flake, plus the nested flakes re-exported with the +prefixes `kfde-` and `kfm-`) and of the nested flakes themselves. + +### Packages and apps + +| Old | New | +|---|---| +| `packages..komorebi`, `komorebic`, `komorebic-no-console`, `komorebi-bar`, `komorebi-gui`, `komorebi-shortcuts`, `komorebi-testwin`, `komorebi-e2e-agent` (Windows) | `windows-komorebi`, `windows-komorebic`, `windows-komorebic-no-console`, `windows-komorebi-bar`, `windows-komorebi-gui`, `windows-komorebi-shortcuts`, `windows-komorebi-testwin`, `windows-komorebi-e2e-agent` | +| `windowsSdk` | `windows-sdk` | +| `komorebi-testwin-e2e` | `windows-komorebi-testwin-e2e` | +| `komorebi-full` (Windows) | `windows-komorebi-full` | +| `default` (Windows), `apps.default` | `windows-default` (`default` is now the native package) | +| `apps.komorebi`, `komorebic`, `komorebic-no-console`, `komorebi-bar`, `komorebi-gui`, `komorebi-shortcuts` (Windows) | `apps.windows-komorebi`, ... (`e2e-windows` is unchanged) | +| `kfde-komorebi`, `kfde-komorebic`, `kfde-komorebi-full`, `kfde-default` | `komorebi`, `komorebic`, `komorebi-full`, `default` on the Linux systems | +| `kfde-kde-rounded-corners-komorebi`, `kfde-kwin-effect-geometry-change-komorebi`, `kfde-run-kde`, `kfde-wsl2-probe`, `kfde-wsl2-probe-guest` | the same names without `kfde-` | +| `kfm-komorebi`, `kfm-komorebic`, `kfm-komorebi-bar`, `kfm-komorebi-full`, `kfm-default` | `komorebi`, `komorebic`, `komorebi-bar`, `komorebi-full`, `default` on the Darwin systems | +| apps of the nested flakes: `komorebi`, `komorebic`, `run-kde`, `wsl2-probe`, `default` (Linux); `komorebi`, `komorebic`, `komorebi-bar`, `default` (macOS) | unchanged, per system | + +### Checks + +| Old | New | +|---|---| +| `komorebi-workspace-clippy`, `-fmt`, `-toml-fmt`, `-deny`, `-nextest` (Windows) | `windows-clippy`, `windows-fmt`, `windows-toml-fmt`, `windows-deny`, `windows-nextest` | +| `e2e-tests` | `windows-e2e-tests` | +| `kfde-komorebi-workspace-clippy`, `-doc`, `-fmt`, `-toml-fmt`, `-deny`, `-nextest` | `linux-clippy`, `linux-doc`, `linux-fmt`, `linux-toml-fmt`, `linux-deny`, `linux-nextest` | +| `kfde-komorebi-bridge-js` | `linux-bridge-js` | +| `kfde-schema-fresh`, `kfde-nix-options-validation`, `kfde-keybindings-fixtures`, `kfde-nixos-module-eval`, `kfde-plasma-guests-eval` | `linux-schema-fresh`, `linux-nix-options-validation`, `linux-keybindings-fixtures`, `linux-nixos-module-eval`, `linux-plasma-guests-eval` | +| `kfde-wsl2-probe`, `kfde-wsl2-probe-dry-run`, `kfde-run-kde`, `kfde-run-kde-doctor`, `kfde-run-kde-dry-run` | `linux-wsl2-probe`, `linux-wsl2-probe-dry-run`, `linux-run-kde`, `linux-run-kde-doctor`, `linux-run-kde-dry-run` | +| `kfde-kde-rounded-corners-komorebi-install`, `kfde-kwin-effect-geometry-change-komorebi-install` | `linux-kde-rounded-corners-komorebi-install`, `linux-kwin-effect-geometry-change-komorebi-install` | +| `vm-NAME`, `vm-lib` (nested KDE flake only; the root flake left them out) | unchanged names, in `legacyPackages..heavyChecks` for now (see Checks); the suites are also `legacyPackages..vm.NAME` | +| `kfm-komorebi-workspace-clippy`, `-fmt`, `-toml-fmt`, `-deny`, `-nextest` | `macos-clippy`, `macos-fmt`, `macos-toml-fmt`, `macos-deny`, `macos-nextest` | +| `kfm-nix-options-validation`, `kfm-darwin-module-validation` | `macos-nix-options-validation`, `macos-darwin-module-validation` | +| `pre-commit`, `treefmt`, `kfde-pre-commit`, `kfde-treefmt`, `kfm-pre-commit`, `kfm-treefmt` | `pre-commit`, `treefmt` (one each, for the whole repository) | + +### Other outputs + +| Old | New | +|---|---| +| `legacyPackages..kfde-vm` (root); `legacyPackages..vm`, `vmTiers`, `vmGuests`, `vmTcg` (nested) | `legacyPackages..vm`, `vmTiers`, `vmGuests`, `vmTcg` | +| `nixosModules.komorebi-for-kde` (root); `nixosModules.default`, `komorebi`, `forVmTests` (nested) | `nixosModules.komorebi` (= `default`), `forVmTests`; `komorebi-for-kde` stays as an alias | +| `darwinModules.komorebi-for-mac` (root); `darwinModules.default`, `komorebi` (nested) | `darwinModules.komorebi` (= `default`); `komorebi-for-mac` stays as an alias | +| `overlays.komorebi-for-kde` (root); `overlays.default`, `komorebi`, `forVmTests` (nested) | `overlays.default` and `komorebi` (the native packages of the system the overlay is applied to), `overlays.linux`, `overlays.macos`, `overlays.forVmTests`; `komorebi-for-kde` stays as an alias | +| `nixosConfigurations.*` (nested KDE flake) | unchanged: `plasma-vm`, `plasma-vm-session`, `plasma-utm`, `plasma-vm-x86_64`, ..., `run-kde-x86_64`, `run-kde-aarch64` | +| `devShells..default` | `devShells..default` (all three platforms, cross environment for Windows) and `devShells..native` (the same without the cross environment) | +| `formatter.` | `formatter.` (one treefmt for the repository) | + +## Inputs + +One of each: `nixpkgs` (nixpkgs-unstable), `flake-parts`, `crane`, `rust-overlay`, `treefmt-nix`, +`git-hooks-nix`, and `asc` (the application-specific configuration komorebic embeds on Windows). They are the +revisions the KDE flake was locked to, because the KDE VM suites run against the Plasma and KWin of the pinned +nixpkgs and the KDE flake was the newest of the three (nixpkgs f05535a0, 2026-10-27, KWin 6.8.2, which is +`testedMax` in `nix/linux/supported-kwin.nix`; rust-overlay 19ecdd08 gives rustc 1.99.1, and sysinfo 0.39.6 +needs 1.95). + +One second nixpkgs, `nixpkgs-x86_64-darwin` (16c7794d, 2026-01-02), is used for the `x86_64-darwin` outputs and +for nothing else: nixpkgs 26.11 dropped x86_64-darwin and evaluating it with the unified pin throws +(`Nixpkgs 26.11 has dropped support for x86_64-darwin`). Drop the input together with x86_64-darwin when Intel +Macs are no longer supported. + +Updating: `nix flake update NAME` for one input; never a blanket `nix flake update`. A new nixpkgs has to keep +every VM suite green (`just vm-all`), and the Windows and macOS groups build. + +## The source of a build + +The Cargo workspace lists the members of all three platforms (`default-members` is the Windows set), so cargo +loads every member in every build. `nix/workspace-src.nix` cuts one source per platform: + +- `real` is the filtered source: the platform's members, the root manifest, lock and toolchain files, the + platform's own files of the crates the platforms share (`komorebic`, `komorebi-client`, `komorebi-bar`, + `komorebi-daemon`: the `linux`, `macos` and `windows` modules and tests are told apart by name) and the data + files the sources and tests read (docs, schemas, fixtures). +- `src` is `real` plus a stub for every other member: its manifest with an empty library and a `main` that does + nothing. Stubs are needed: cargo refuses a workspace with a member that is not there, and `--locked` refuses + a lock file that has packages the workspace does not have. A stub carries the manifest only, so an edit of + another platform's code changes nothing here. +- The dependency derivations (`buildDepsOnly`) use a dummy source made of the manifests of every member + (`manifestSource` in `nix/lib.nix`), the same for the three platforms. It is a plain path, not a + derivation, so crane reads it at evaluation without building: `nix flake check --no-build --all-systems` + needs that to evaluate the Darwin outputs on a Linux host. + +The Linux source takes the crates listed in `nix/linux/root-crates.json` (the crates outside the Linux-only +ones that `cargo tree` says the KDE packages depend on, so an edit of the egui bar does not rebuild the KDE +packages); `tools/kde-closure-check` fails when the list and `cargo tree` differ. The Windows source is the +whole workspace except the Linux and macOS crates and files; the macOS source is the macOS crates, the shared +crates and `crates/`. + +## Checks + +Every platform's checks run on its own source, so a change in one platform's directories does not rebuild the +others' derivations. A change in a crate under `crates/` (or in `komorebic`, `komorebi-client`, +`komorebi-daemon`), in `Cargo.toml`, `Cargo.lock`, `rust-toolchain.toml` or `deny.toml` rebuilds those that read it. + +- `windows-clippy`, `windows-nextest`, `windows-fmt`, `windows-toml-fmt`, `windows-deny`, `windows-e2e-tests` +- `linux-clippy`, `linux-doc`, `linux-nextest`, `linux-fmt`, `linux-toml-fmt`, `linux-deny`, `linux-bridge-js`, + `linux-schema-fresh`, `linux-nix-options-validation`, `linux-keybindings-fixtures`, `linux-nixos-module-eval`, + `linux-plasma-guests-eval`, `linux-wsl2-probe`, `linux-wsl2-probe-dry-run`, `linux-run-kde*`, + `linux-*-install` +- `macos-clippy`, `macos-nextest`, `macos-fmt`, `macos-toml-fmt`, `macos-deny`, `macos-nix-options-validation`, + `macos-darwin-module-validation` +- `treefmt` and `pre-commit` for the whole tree + +The checks that evaluate a NixOS system or a VM (`vm-lib`, one `vm-NAME` per suite, `linux-nixos-module-eval`, +`linux-plasma-guests-eval`, `linux-run-kde`, `linux-run-kde-doctor`, `linux-run-kde-dry-run`) are NOT in `checks`: +they are `legacyPackages..heavyChecks.` (`nix build -L .#legacyPackages.x86_64-linux.heavyChecks.vm-lib`). +Evaluating them takes minutes and more memory than `nix flake check --no-build --all-systems` can use (it was +killed at 28 GB). This is a placeholder until the structure of the check sets is decided. Name the check you want (`nix build -L +.#checks.x86_64-linux.windows-clippy`). `nix flake check --no-build --all-systems` evaluates every output of +every system (42 s) and is the evaluation test of this file. + +## Dev shells + +`nix develop` has the tools of all three platforms: the nightly rustfmt over the toolchain of +`rust-toolchain.toml` with the Windows target, the xwin cross environment (`CARGO_BUILD_TARGET` is +`x86_64-pc-windows-msvc`, so a bare `cargo` command builds for Windows), cargo-deny, cargo-nextest, the KDE +bridge's node and tsc, the VM library's ruff and ty, QEMU and swtpm for the Windows e2e guest. For `cargo` +commands on the Linux or macOS packages use `nix develop .#native` (the same tools, no cross environment), or +`--target` on a command. + +## Updating the flake: what to run + +- the evaluation: `nix flake check --no-build --all-systems` +- the Windows group: `windows-clippy`, `windows-nextest`, `windows-fmt`, `windows-toml-fmt`, `windows-deny`, + `windows-e2e-tests`, the `windows-*` packages +- the Linux group: the `linux-*` checks and packages, one VM suite (`vm-lib`, then a cheap suite) +- on a Mac: `nix build -L .#checks.aarch64-darwin.macos-{clippy,nextest,fmt,toml-fmt,deny,nix-options-validation,darwin-module-validation}` + and `nix build -L .#packages.aarch64-darwin.{komorebi,komorebic,komorebi-bar}`