komorebi/docs/dev/flake.md

# 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` (`-nextest` ran no test and is gone, see flake-checks.md) |
| `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 `checks` (`vm-lib`) or the sets `vm-fast`, `vm-slow` (see Checks and flake-checks.md); 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`: 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`), in `Cargo.toml`, `Cargo.lock`, `rust-toolchain.toml` or `deny.toml` rebuilds those that read it.

- `windows-clippy`, `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 are in sets (docs/dev/flake-checks.md): `checks.<system>` has the members of the sets of
`defaultCheckSets` in `nix/checks.nix`, the cheap ones. The ones that evaluate NixOS systems (the VM suites,
`linux-nixos-module-eval`, `linux-plasma-guests-eval`, `linux-run-kde*`) are the sets `vm-fast`, `vm-slow`,
`linux-nixos-eval` and `linux-demo`, which `nix flake check` leaves out (evaluating them took more memory than the host
has): `nix build -L .#checkSets.<set>`, or one member, `.#checkMembers.<set>.<name>`. A check is named as before
(`nix build -L .#checks.x86_64-linux.windows-clippy`). `nix flake check --no-build --all-systems` evaluates the
default sets and every other output of every system 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-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}`