starred/komorebi
1
0 Fork 0
mirror of https://github.com/LGUG2Z/komorebi.git synced 2026-11-13 12:23:38 +01:00
Code Issues 87 Packages Projects Releases 11 Wiki Activity

docs(dev): the flake, with the old-name to new-name table, and the nix commands of build-and-test

Browse Source 
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.<s>.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).
This commit is contained in:
LGUG2Z committed 2026-11-05 15:03:27 -08:00
1 parent f7f444efb6
commit 30322bd68d
2 files changed
+211 -54
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/dev/build-and-test.md
+49 -54
View File
@@ -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
docs/dev/flake.md
+162
View File
@@ -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 `<platform>-<check>` (`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.<s>.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.<linux>.heavyChecks` for now (see Checks); the suites are also `legacyPackages.<s>.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.<s>.kfde-vm` (root); `legacyPackages.<s>.vm`, `vmTiers`, `vmGuests`, `vmTcg` (nested) | `legacyPackages.<s>.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.<s>.default` | `devShells.<s>.default` (all three platforms, cross environment for Windows) and `devShells.<s>.native` (the same without the cross environment) |
| `formatter.<s>` | `formatter.<s>` (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.<system>.heavyChecks.<name>` (`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}`