feat: Nomarchy ground-up rewrite on NixOS 26.05
Full replacement of the previous iteration, rebuilt around three ideas:
- Pure evaluation: theme-state.json lives inside the flake and is read
via the nomarchy.stateFile option — no --impure, ever.
- All-Home-Manager theming: `nomarchy-theme-sync apply` writes the JSON
and runs `home-manager switch`; every theme change is one atomic,
rollbackable generation. Wallpaper (swww) is the sole runtime piece.
- Flat, downstream-first layout: modules/{nixos,home} with one
options.nix each, exported as nixosModules/homeModules + overlay +
flake template; system (nixos-rebuild) and desktop (home-manager
switch) rebuild paths are fully split.
Ships 21 themes imported from the previous iteration (palettes,
wallpapers, btop themes, six whole-swap Waybar identities), Stylix for
the GTK/Qt/cursor long tail, a live ISO target with offline theme
switching, and docs/TESTING.md with the QEMU verification workflow.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Bernardo Magri
89
docs/TESTING.md
Normal file
89
docs/TESTING.md
Normal file
@@ -0,0 +1,89 @@
|
||||
# Testing Nomarchy
|
||||
|
||||
How to verify changes actually work — from cheap eval checks to booting the
|
||||
full desktop. Adapted from the previous Nomarchy iteration's agent docs.
|
||||
|
||||
**The honesty rule (for humans and AI agents alike):** for Waybar, Hyprland,
|
||||
or any visual change, the only reliable check is booting the live ISO. If
|
||||
you can't boot it (e.g. you're on macOS or have no KVM), **say so** rather
|
||||
than claiming success. "All Nix files parse" is not "the bar renders."
|
||||
|
||||
## 1. Cheap checks (always do these first)
|
||||
|
||||
```sh
|
||||
nix flake check --no-build # full module-system evaluation, no builds
|
||||
nix-instantiate --parse <file> # syntax-only, works even on macOS
|
||||
python3 -m py_compile pkgs/nomarchy-theme-sync/nomarchy-theme-sync.py
|
||||
```
|
||||
|
||||
`nix flake check` needs a Linux machine (or a Linux builder) since all
|
||||
outputs are `x86_64-linux`. It catches type errors, missing options, and
|
||||
bad merges — most breakage stops here.
|
||||
|
||||
## 2. Build and boot the live ISO
|
||||
|
||||
```sh
|
||||
# Build + boot in QEMU, one command:
|
||||
tools/test-live-iso.sh
|
||||
|
||||
# Or by hand:
|
||||
nix build .#nixosConfigurations.nomarchy-live.config.system.build.isoImage
|
||||
# → result/iso/*.iso — dd it to a USB stick for real hardware
|
||||
```
|
||||
|
||||
The script prefers UEFI (OVMF) with a legacy-BIOS fallback, uses KVM when
|
||||
`/dev/kvm` is readable, and boots with `virtio-vga-gl` + `gl=on` —
|
||||
**Hyprland and Ghostty need real OpenGL in the guest**; without it the
|
||||
session may not start.
|
||||
|
||||
### What the live environment gives you
|
||||
|
||||
- Auto-login as `nomarchy` (no password, passwordless sudo), greetd →
|
||||
Hyprland via `initial_session`; logging out lands on tuigreet.
|
||||
- The flake is seeded writable at `~/.nomarchy` (from the read-only
|
||||
`/etc/nomarchy` copy) — `$NOMARCHY_PATH` already points there.
|
||||
- Locked flake inputs are pinned into the ISO store, so
|
||||
`home-manager switch` works **without a network**.
|
||||
|
||||
## 3. Verification checklist
|
||||
|
||||
Work through these in order; each one exercises a different layer.
|
||||
|
||||
| # | Check | Verifies |
|
||||
|---|---|---|
|
||||
| 1 | Boots to Hyprland with Tokyo Night wallpaper visible | greetd autologin, swww, session start |
|
||||
| 2 | Waybar shows at top, themed (blue accent on dark) | HM waybar module, palette baking |
|
||||
| 3 | `SUPER+Return` opens Ghostty with Tokyo Night colors | terminal default, ANSI palette |
|
||||
| 4 | `btop` in the terminal is themed | per-theme asset baking |
|
||||
| 5 | `nomarchy-theme-sync list` prints 21 presets | package, baked themes dir |
|
||||
| 6 | `nomarchy-theme-sync apply gruvbox` → state written, `home-manager switch` runs, desktop re-themes, wallpaper changes | the whole engine: state write, pure eval, HM rebuild, wallpaper hook |
|
||||
| 7 | `SUPER+SHIFT+T` cycles wallpapers instantly (try `tokyo-night`: 4 of them) | the runtime wallpaper path |
|
||||
| 8 | `nomarchy-theme-sync apply summer-night` → after the switch the bar has its own identity (light bar, different styling) | whole-swap waybar.css assets |
|
||||
| 9 | Open a GTK app — dark theme matching the palette | Stylix layer |
|
||||
| 10 | `home-manager generations` lists one generation per theme change; activating an older one rolls the theme back | atomicity / rollback story |
|
||||
|
||||
Items 6 and 8 are the big ones — they prove the all-Home-Manager theming
|
||||
model end to end.
|
||||
|
||||
## 4. VM-specific gotchas
|
||||
|
||||
- **No KVM** (e.g. nested without acceleration): everything works but
|
||||
`home-manager switch` will be painfully slow. Don't read slowness as
|
||||
breakage.
|
||||
- **Black screen / session exits**: almost always missing guest GL. Use the
|
||||
script's qemu flags; on real hardware check `journalctl -b -u greetd`.
|
||||
- **Tiny resolution**: the live config forces `monitor = ,highres,auto,1`;
|
||||
if QEMU still picks 1024×768, resize the window — Hyprland follows.
|
||||
- **First theme switch is the slowest**: it evaluates the flake on a RAM
|
||||
disk. Subsequent switches reuse the eval cache.
|
||||
|
||||
## 5. When something fails
|
||||
|
||||
- Session/login problems: `journalctl -b -u greetd`, then `journalctl
|
||||
--user -b`.
|
||||
- Theme switch failures: run `nomarchy-theme-sync apply <x>` from a
|
||||
terminal — the home-manager output streams there. The state file is
|
||||
written *before* the rebuild, so after fixing you can just re-run
|
||||
`home-manager switch --flake ~/.nomarchy`.
|
||||
- Report results faithfully: what booted, what rendered, what you could
|
||||
not verify and why.
|
||||
Reference in New Issue
Block a user