FEnigma/packaging/windows/README.md

# Windows .msi build (via dockur/windows)

Builds a Windows installer for FEnigma on a Linux host with no Windows
machine and no GitHub, by booting a real Windows VM inside a container
([dockur/windows](https://github.com/dockur/windows), QEMU+KVM under the
hood, no license key needed for the eval install it fetches automatically)
and driving the whole build over a shared folder.

**Status: has actually been run.** Two real environment issues hit and
fixed so far (both already applied in this directory, see "Confirmed
issues hit" below); Windows install itself was still in progress as of
last check. `oem/install.bat` onward (MSYS2/GTK4/WiX provisioning, the
actual .msi packaging) has NOT been reached/exercised yet — treat that
part as still a debugging session, not a push-button success. Watch it
happen at http://localhost:8006 (dockur's noVNC viewer) if it stalls.

## Confirmed issues hit (on Fedora + BTRFS)

- **SELinux blocks the bind mounts** ("Storage folder (/storage) is not
  writeable!") — fixed with `:Z` on every volume in `docker-compose.yml`.
  Harmless no-op on a host without SELinux.
- **The repeated "loading/starting Boot0004" log lines are NOT a boot
  loop** — that was an earlier misdiagnosis here (blamed on BTRFS+QEMU,
  "fixed" with `chattr +C` on `storage/`). Checked the actual noVNC
  screen instead of just the text log and it was genuine, progressing
  Windows Setup the whole time ("This might take a few minutes" →
  "Please keep your PC on and plugged in" → desktop) — Setup legitimately
  reboots the VM multiple times, each one re-prints those same firmware
  log lines. The `chattr +C` disables copy-on-write for the VM's disk
  image regardless (a real, independently-documented dockur/QEMU/BTRFS
  caveat), so it's staying, but it likely wasn't fixing an actual
  problem this time. **Lesson: check the screen, not just the log,
  before concluding something's stuck.**
- **The build watcher registered as a SYSTEM-context Scheduled Task
  never fires in practice**: `Z:\` (the `/shared` mount) is mapped per
  interactive session, invisible to a task with no session of its own,
  so it spun forever on `watch_build.bat`'s own `if not exist Z:\`
  wait — confirmed by a build request sitting unclaimed for hours.
  Fixed in `install.bat`: an All-Users Startup-folder entry instead,
  which runs in whichever user's session actually logs in.

## How it fits together

- `docker-compose.yml` — boots the VM. Needs `/dev/kvm` on the host.
- `oem/install.bat` — **one-time** provisioning, auto-run by Windows's own
  unattended setup on first boot (dockur/windows's `/oem` mechanism):
  installs MSYS2, then GTK4/libadwaita/PyGObject/numpy/Pillow/OpenCV/
  Tesseract through it, plus the WiX v3 toolset, and registers a
  boot-time watcher task. This is the slow part (Windows install itself,
  then package downloads) and only ever happens once — it lives on the
  VM's persistent disk (`./storage`, gitignored) from then on.
- `oem/watch_build.bat` — runs at every boot from here on, polls the
  shared `Z:\` drive for a build request.
- `oem/build.bat` — the actual per-build packaging: assembles a dist tree
  (bundled MSYS2 `mingw64` runtime + the `fenigma` package), harvests it
  into WiX components with `heat.exe`, and links it into an `.msi` with
  `candle.exe`/`light.exe`.
- `oem/product.wxs` — the hand-authored shell around that harvested file
  list: install directory, Start Menu shortcut, and the `PYTHONPATH`
  environment variable the shortcut needs (mirrors `run.sh`'s
  `PYTHONPATH=src python -m fenigma.app`).
- `build_windows.sh` — run this. Starts the VM, copies `../../src` onto
  the shared folder, drops a request file, waits for the `.msi` to come
  back, copies it to `../../dist-windows/`.

## Running it

```bash
cd packaging/windows
./build_windows.sh [version]
```

First run: full unattended Windows install + provisioning, likely
30-90 minutes, unattended (no interaction needed, but it needs to
actually finish — don't kill it early). Every run after that: just boot
the already-provisioned VM and build, a few minutes.

Requires `/dev/kvm` (virtualization enabled, your user in the `kvm`
group) and Docker with Compose.

## Known rough edges / likely follow-up work

- **The dist tree is fat, not lean.** `build.bat` bulk-copies the entire
  `mingw64/` runtime rather than tracing the actual DLL/typelib/icon-
  theme/schema dependency closure of the app — reliable, but probably
  1GB+. Trimming it (e.g. by walking `pythonw.exe`'s and the compiled
  extension modules' actual dependencies) is a real but separate project.
- **`heat.exe`'s default harvest options are a starting guess** for a
  tree this large and this GTK-specific (icon caches, gschemas, typelibs);
  it may need `-t` transforms or manual exclusions to produce a working
  component set.
- **Not tested against a real GTK4/libadwaita Windows install at all** —
  MSYS2 ships these, but this is the first time this specific app has
  been pointed at them; expect a missing-DLL or schema error on first
  actual launch, not just a packaging error.
- No code signing — Windows will show an "unknown publisher" warning.