mirror of
https://github.com/LGUG2Z/komorebi.git
synced 2026-11-22 00:21:43 +01:00
docs(linux): paths and links name the consolidated layout
The KDE docs were moved from komorebi-for-kde/ to docs/linux/ and the sources, nix files, scripts and schemas to komorebi-linux/, nix/linux/, scripts/linux/ and schemas/linux/, so every relative link that left docs/ (to sources, nix files, scripts, schemas, .envrc, rust-toolchain.toml, the old CI file) was broken, and the text named the old paths. Links were rewritten mechanically by resolving each broken target against the old location and mapping it to the new one; link texts and code-span paths were updated to the new paths (komorebi/src -> komorebi-linux/src, nix/ -> nix/linux/, scripts/ -> scripts/linux/, docs/ -> docs/linux/, schema.json -> schemas/linux/schema.json). The crate list of the README names komorebi-linux, komorebi-daemon and komorebi-version; `cargo install --path komorebi` becomes komorebi-daemon; the comparison paragraph of CONTRIBUTING.md says compare-gen.py is stale (it looks for the old sibling trees). URLs of the old GitHub repositories are left as they are (a release decision). COMPARE.md is left as it is (already marked stale). Verified: a link checker over every markdown file (outside cli/, nix/, tools/, old-ci) reports no broken link in docs/linux. Nothing was built.
This commit is contained in:
1 parent
5b2381efb4
commit
a7b78cc7e4
20 files changed
+358
-355
No files matched your search
+22
-22
@@ -12,12 +12,12 @@ they are laid out, how to run them, and how to add one.
|
||||
| CI, `x86_64-linux` | `nix build -L .#checks.x86_64-linux.vm-NAME` | KVM |
|
||||
| CI, `x86_64-linux`, the weekly canary | the same, with nixpkgs moved to the tip of nixpkgs-unstable | KVM |
|
||||
| A Linux machine with KVM | `just vm NAME` | KVM |
|
||||
| A Mac | `just vm NAME`, which runs `scripts/vm-mac` | HVF |
|
||||
| A Mac | `just vm NAME`, which runs `scripts/linux/vm-mac` | HVF |
|
||||
| A Linux machine with no KVM | `nix build -L .#legacyPackages.SYSTEM.vmTcg.NAME` | TCG |
|
||||
|
||||
CI runs the `fast` tier on every pull request and the `slow` tier on `master`,
|
||||
every week, and on pull requests labeled `ci:vm-slow`
|
||||
([`ci.yaml`](../../.github/workflows/ci.yaml)). The slow jobs run the driver
|
||||
([`ci.yaml`](../../dev/old-ci/linux/workflows/ci.yaml)). The slow jobs run the driver
|
||||
by hand instead of building the check, so that the screenshots and journals of a
|
||||
failed run can be uploaded as an artifact. KVM on GitHub-hosted runners is
|
||||
documented for public repositories; the first step of each VM job checks that
|
||||
@@ -27,7 +27,7 @@ The `canary` job runs both tiers once more every week, against the tip of
|
||||
nixpkgs-unstable instead of the nixpkgs `flake.lock` pins: it runs
|
||||
`nix flake update nixpkgs` in a copy of the checkout, builds every check there,
|
||||
the suites one after the other on one machine, and opens an issue when one
|
||||
fails ([`CONTRIBUTING.md`](../../CONTRIBUTING.md#continuous-integration)). It is
|
||||
fails ([`CONTRIBUTING.md`](../CONTRIBUTING.md#continuous-integration)). It is
|
||||
how a new KWin or Plasma that breaks a suite is found before the lock moves to
|
||||
it.
|
||||
|
||||
@@ -39,15 +39,15 @@ depends on settings of Windows. `nix run .#wsl2-probe` boots a tiny guest with
|
||||
and without KVM and times both ([wsl2-probe.md](wsl2-probe.md)).
|
||||
|
||||
The suites are what `testedMax` in
|
||||
[`nix/supported-kwin.nix`](../../nix/supported-kwin.nix) means: the newest KWin
|
||||
[`nix/linux/supported-kwin.nix`](../../../nix/linux/supported-kwin.nix) means: the newest KWin
|
||||
every suite has passed against. When the weekly canary job, which runs every
|
||||
suite against the tip of nixpkgs-unstable, passes with a newer KWin, a commit
|
||||
raises `testedMax` to it and says which suites ran
|
||||
([CONTRIBUTING.md](../../CONTRIBUTING.md#the-nixos-module)).
|
||||
([CONTRIBUTING.md](../CONTRIBUTING.md#the-nixos-module)).
|
||||
|
||||
Each suite is a directory under
|
||||
[`nix/tests/vm/suites`](../../nix/tests/vm/suites). The generator in
|
||||
[`nix/tests/vm/default.nix`](../../nix/tests/vm/default.nix) lists that
|
||||
[`nix/linux/tests/vm/suites`](../../../nix/linux/tests/vm/suites). The generator in
|
||||
[`nix/linux/tests/vm/default.nix`](../../../nix/linux/tests/vm/default.nix) lists that
|
||||
directory, so a new suite is a new directory and nothing else: it appears as
|
||||
`checks.<system>.vm-NAME` on Linux and as `legacyPackages.<system>.vm.NAME`
|
||||
everywhere. `legacyPackages.<system>.vmTiers` lists the names of each tier as
|
||||
@@ -69,7 +69,7 @@ A suite has two files:
|
||||
## Nodes
|
||||
|
||||
`kind` picks a file under
|
||||
[`nix/tests/vm/nodes`](../../nix/tests/vm/nodes).
|
||||
[`nix/linux/tests/vm/nodes`](../../../nix/linux/tests/vm/nodes).
|
||||
|
||||
Both nodes are built with the NixOS module, as a user's machine is: they import
|
||||
`nixosModules.default`, which the generator passes to them, and enable
|
||||
@@ -78,7 +78,7 @@ commit under test. `services.komorebi.logLevel` is `"debug"`, because the tests
|
||||
read the daemon's debug log. A suite can change either option in its `node`:
|
||||
`latency`, which times the daemon, runs it at `"info"`.
|
||||
The checks of the module that need no machine are `nixos-module-eval`
|
||||
([`nix/tests/nixos-module.nix`](../../nix/tests/nixos-module.nix)), and the
|
||||
([`nix/linux/tests/nixos-module.nix`](../../../nix/linux/tests/nixos-module.nix)), and the
|
||||
suite `module` checks its unit in a Plasma session.
|
||||
|
||||
`headless` is a machine with Plasma installed and no login. Each KWin a test
|
||||
@@ -104,7 +104,7 @@ in the session from the start, as on a user's machine; `render-smoke`, which
|
||||
checks that the session draws, turns it off. It is the node for anything that
|
||||
needs pixels: `features` reads what komorebi does from screenshots of it. The
|
||||
choice of login manager is made in
|
||||
[`nodes/session.nix`](../../nix/tests/vm/nodes/session.nix) and nowhere else;
|
||||
[`nodes/session.nix`](../../../nix/linux/tests/vm/nodes/session.nix) and nowhere else;
|
||||
the file says how to switch to sddm, the other one that has been seen to work.
|
||||
Its display is 1280x800, because screenshots are taken of the machine's one
|
||||
display device: the `virtio-gpu-pci` that the test driver adds to every aarch64
|
||||
@@ -119,9 +119,9 @@ On aarch64 under HVF, at time of writing (2026-10-27), the session has the
|
||||
Wayland socket after 11 to 19 seconds and a painted desktop after 35 seconds.
|
||||
|
||||
A suite's `node` can import a module of the repository: `rdp` imports
|
||||
[`nix/dev/krdp.nix`](../../nix/dev/krdp.nix), the RDP server of the Plasma
|
||||
[`nix/linux/dev/krdp.nix`](../../../nix/linux/dev/krdp.nix), the RDP server of the Plasma
|
||||
guests to develop in, so that the suite checks the unit those guests run, and
|
||||
`run-kde` imports [`nix/dev/run-kde.nix`](../../nix/dev/run-kde.nix), the demo
|
||||
`run-kde` imports [`nix/linux/dev/run-kde.nix`](../../../nix/linux/dev/run-kde.nix), the demo
|
||||
guest that the command `run-kde` starts, so that what CI boots is what the
|
||||
command starts. The node of `run-kde` also makes the directory that the host
|
||||
shares with that guest (`/run/run-kde`), owned by a user the guest does not
|
||||
@@ -132,7 +132,7 @@ mounted it. The guests themselves, which stay up for a person to use, are in
|
||||
## The library
|
||||
|
||||
Suites import from `komorebi_vm`, in
|
||||
[`nix/tests/vm/lib`](../../nix/tests/vm/lib). It does not depend on the test
|
||||
[`nix/linux/tests/vm/lib`](../../../nix/linux/tests/vm/lib). It does not depend on the test
|
||||
driver. It depends on the small `Machine` protocol, and its unit tests pass a
|
||||
fake machine, so the `vm-lib` check tests it without booting anything. The
|
||||
check also runs `ruff` and `ty` over it. The driver type checks every
|
||||
@@ -173,7 +173,7 @@ the run.
|
||||
The scenarios run on two platforms. KDE runs them in `core-e2e`, except `resize` and
|
||||
`focus_follows_mouse`, which need a pointer and run at the end of `drag-resize`. A
|
||||
Windows 11 guest under QEMU, which kfw drives from its own tree with this `core/` copied
|
||||
unchanged (`scripts/sync-e2e-core` keeps the copy in step until `core/` moves there),
|
||||
unchanged (`scripts/linux/sync-e2e-core` keeps the copy in step until `core/` moves there),
|
||||
runs all of them against kfw's daemon. [BEHAVIOUR.md](BEHAVIOUR.md) says what each
|
||||
scenario found on each port, and what turned red when the daemon was deliberately broken.
|
||||
- `Checks` counts checks and fails once, at the end, so that one failure does
|
||||
@@ -255,7 +255,7 @@ the run.
|
||||
guest, milliseconds apart: moves that each wait for the test are seconds
|
||||
apart, and KWin was seen to lose the horizontal part of such a drag. The
|
||||
pointer lands within a pixel of where it is asked. The program itself is
|
||||
[`komorebi_vm/uinput.py`](../../nix/tests/vm/lib/komorebi_vm/uinput.py),
|
||||
[`nix/linux/tests/vm/lib/komorebi_vm/uinput.py`](../../../nix/linux/tests/vm/lib/komorebi_vm/uinput.py),
|
||||
whose arithmetic the `vm-lib` check tests.
|
||||
- `RdpClient(machine, kde)` is FreeRDP's client on an X server of its own, for a
|
||||
node that runs KRDP: `listening()` asks the guest whether the server has its
|
||||
@@ -314,7 +314,7 @@ Two traps are worth knowing about before writing a screenshot test:
|
||||
|
||||
QEMU has to run on the Mac to use HVF, and the guest is Linux, so the guest's
|
||||
closure is built on a Linux builder and the driver runs on the Mac. The nix
|
||||
sandbox on macOS cannot give QEMU the hypervisor, so `scripts/vm-mac` runs the
|
||||
sandbox on macOS cannot give QEMU the hypervisor, so `scripts/linux/vm-mac` runs the
|
||||
driver directly instead of building the check.
|
||||
|
||||
```sh
|
||||
@@ -335,9 +335,9 @@ The script prints where the artifacts (screenshots, logs) are, under
|
||||
|
||||
## Writing a test
|
||||
|
||||
1. Create `nix/tests/vm/suites/NAME/default.nix` and `test.py`. Start from
|
||||
[`suites/kwin`](../../nix/tests/vm/suites/kwin), or from
|
||||
[`suites/kwin-events`](../../nix/tests/vm/suites/kwin-events) for a test that
|
||||
1. Create `nix/linux/tests/vm/suites/NAME/default.nix` and `test.py`. Start from
|
||||
[`suites/kwin`](../../../nix/linux/tests/vm/suites/kwin), or from
|
||||
[`suites/kwin-events`](../../../nix/linux/tests/vm/suites/kwin-events) for a test that
|
||||
runs the daemon.
|
||||
2. Pick the tier. `fast` suites are the pull request gate and should take
|
||||
minutes. `slow` suites run on `master` and every week.
|
||||
@@ -351,7 +351,7 @@ Add `git add -N` for new files first: a flake only sees files git knows about.
|
||||
## Writing a scenario
|
||||
|
||||
A scenario is a function `run(platform, checks, ...)` in
|
||||
`nix/tests/vm/lib/komorebi_vm/core/scenarios/`. It is what runs on every
|
||||
`nix/linux/tests/vm/lib/komorebi_vm/core/scenarios/`. It is what runs on every
|
||||
platform, so it follows four rules:
|
||||
|
||||
- It reaches the desktop only through the `Platform`, and the daemon only through
|
||||
@@ -383,7 +383,7 @@ the fake and fails on KDE has found a bug in the fake, the library or the daemon
|
||||
- **The daemon is built once, not once per commit.** The VM tests install the daemon built with the
|
||||
constant commit `nix-check` (`nixosModules.forVmTests`), as the checks do, so a new commit does not
|
||||
build it again. The version a VM test sees is therefore not the commit. The source of the build
|
||||
leaves out `nix/tests/vm/`, so editing a test, the library or a fixture does not rebuild it either.
|
||||
leaves out `nix/linux/tests/vm/`, so editing a test, the library or a fixture does not rebuild it either.
|
||||
`nix build .#komorebi-full`, and what a user installs, still has the real commit.
|
||||
- **Each step says how long it took.** `run_suite` prints `[scope] module.function: 12.3 s` after
|
||||
every step, so a log shows which scenario the time went to.
|
||||
@@ -417,7 +417,7 @@ with the run's other artifacts. A run without the variable records nothing.
|
||||
## Looking inside a failed run
|
||||
|
||||
`nix build -L` prints the guest's console, and a session test keeps its screenshots. Run the driver by hand, as
|
||||
`scripts/vm-mac` does, to keep the screenshots. For an interactive session
|
||||
`scripts/linux/vm-mac` does, to keep the screenshots. For an interactive session
|
||||
build `driverInteractive` instead of `driver`, run it, and call `start_all()`
|
||||
and `machine.shell_interact()` at its prompt. In the guest, KWin's own log is
|
||||
`journalctl --user -u kwin-virtual@NAME` as the test user, and a KWin script's
|
||||
|
||||
Reference in new issue
Block a user