fix(@projects/@magic-civilization): 🐛 resolve windows runner cross-compilation setup

Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>
2026-04-25 17:43:44 -07:00 · 2026-04-25 17:43:44 -07:00 · 5635bc3f26
commit 5635bc3f26
parent 535f43d921
5 changed files with 54 additions and 56 deletions
--- a/.forgejo/RUNNER_SETUP.md
+++ b/.forgejo/RUNNER_SETUP.md
@ -18,7 +18,7 @@ Forgejo Actions is drone-compatible; runners register via
 | `release.yml` — linux_build | `linux,apricot` | apricot | REQUIRED |
 | `release.yml` — wasm_build | `linux,apricot` | apricot | REQUIRED |
 | `release.yml` — macos_build | `macos,arm64` | *(unassigned)* | TODO(prerequisite) |
-| `release.yml` — windows_build | `windows,x86_64` | *(unassigned)* | TODO(prerequisite) |
+| `release.yml` — windows_build | `linux,apricot` | apricot (cargo-xwin cross-compile) | REQUIRED — same runner as linux_build, no Windows host needed |

 Until a runner with matching labels registers, the corresponding jobs
 queue indefinitely on Forgejo. CI (push-to-main) only needs the apricot
@ -164,55 +164,44 @@ forgejo-runner daemon

 ---

-## Windows runner (windows,x86_64) — TODO
+## Windows build (cross-compiled from apricot via cargo-xwin)

-No Windows runner is currently registered. Same queuing behavior as
-macOS above.
+Windows binaries are produced on the existing apricot Linux runner —
+no Windows host is required. The .dll uses MSVC ABI via
+[`cargo-xwin`](https://github.com/rust-cross/cargo-xwin), and Godot's
+Windows export template runs natively from Linux. Verified end-to-end
+2026-04-25 (p2-06b).

-### Registration
+### Toolchain prerequisites on apricot

-On the target Windows host (PowerShell, as admin):
+```bash
+# 1. Add the Windows MSVC target to rustup.
+rustup target add x86_64-pc-windows-msvc

-```powershell
-# 1. Install forgejo-runner (windows amd64 build).
-Invoke-WebRequest `
-  -Uri "https://code.forgejo.org/forgejo/runner/releases/download/nightly/forgejo-runner-nightly-windows-amd64.exe" `
-  -OutFile "C:\Tools\forgejo-runner.exe"
+# 2. Install cargo-xwin (downloads ~1.5GB of MS SDK on first build,
+#    cached at ~/.cache/cargo-xwin/).
+cargo install cargo-xwin

-# 2. Register with windows,x86_64 labels.
-cd C:\Tools
-.\forgejo-runner.exe register `
-  --no-interactive `
-  --instance http://10.0.0.11:3000 `
-  --token "$env:FORGEJO_RUNNER_TOKEN" `
-  --name win-release `
-  --labels "windows,x86_64"
-
-# 3. Install as a Windows service (NSSM or sc.exe).
-sc.exe create forgejo-runner binPath= "C:\Tools\forgejo-runner.exe daemon" start= auto
-sc.exe start forgejo-runner
+# 3. clang is required as the front-end compiler (already present on
+#    apricot via clang-21 rpm). lld is NOT required — cargo-xwin's
+#    bundled xwin sub-tool resolves the linker via the MSVC SDK.
 ```

-### Toolchain prerequisites on the Windows runner
+### Verify

- **Rust + the MSVC target**:
-  ```powershell
-  # rustup-init from https://rustup.rs
-  rustup target add x86_64-pc-windows-msvc
-  ```
- **Visual Studio Build Tools 2022** — specifically the "Desktop
-  development with C++" workload. Required for the MSVC linker that
-  `godot-rust` pulls in via `build-gdext.sh`.
- **Godot editor** — download the Windows standard build and add it to
-  `$PATH` as `godot`. Godot does not have a Windows package manager
-  entry comparable to Flatpak / brew; manual install is the norm.
- **Godot export templates** — matching the editor version, installed
-  under `%APPDATA%\Godot\export_templates\`.
- **7-Zip** — `choco install 7zip` (or scoop); the workflow uses `7z`
-  to build the Windows archive.
- **Git for Windows** — provides the `bash` shell that the workflow's
-  `shell: bash` steps depend on.
- **jq, curl** — `choco install jq curl`.
+```bash
+cd ~/Code/@projects/@magic-civilization
+bash src/simulator/build-gdext.sh x86_64-pc-windows-msvc   # ~3min first run
+BUILD_WINDOWS_DLL=0 EXPORT_STAGED=1 bash tools/export-single.sh windows verify-$(date +%s)
+ls .local/build/godot/verify-*/windows/
+# → MagicCivilization.exe + engine/addons/magic_civ_physics/magic_civ_physics.x86_64.dll
+```
+
+### Boots-and-plays smoke
+
+Wine is not installed on apricot; smoke verification needs either:
+- `dnf install wine` on apricot (sudo), then run the .exe via wine, OR
+- A real Windows machine to unzip + double-click the archive.

 ---

--- a/.project/objectives/DASHBOARD_CATEGORIES.md
+++ b/.project/objectives/DASHBOARD_CATEGORIES.md
@ -114,7 +114,7 @@
 | [p2-04](p2-04-localization-audit.md) | ✅ done | P2 | Localization audit — no hardcoded strings | [shipwright](../team-leads/shipwright.md) | 🟢 |
 | [p2-05](p2-05-turn-latency.md) | ✅ done | P2 | Sub-second single-player turn latency | — | 🟢 |
 | [p2-06](p2-06-export-pipeline.md) | 🟡 partial | P1 | Export pipeline for Windows / macOS / Linux | [shipwright](../team-leads/shipwright.md) | 🟢 |
-| [p2-06b](p2-06b-windows-runner.md) | ❌ missing | P2 | Register a Windows runner for forgejo to produce .dll + .exe on tag push | [shipwright](../team-leads/shipwright.md) | 🟢 |
+| [p2-06b](p2-06b-windows-runner.md) | 🔵 in_progress | P2 | Cross-compile Windows .exe + .dll from Linux via cargo-xwin (no Windows host) | [shipwright](../team-leads/shipwright.md) | 🟢 |
 | [p2-07](p2-07-credits-screen.md) | ✅ done | P2 | Credits screen accessible from main menu | [shipwright](../team-leads/shipwright.md) | 🟢 |
 | [p2-08](p2-08-accessibility.md) | ✅ done | P2 | Accessibility baseline — colorblind palette + keyboard navigation | [shipwright](../team-leads/shipwright.md) | 🟢 |
 | [p2-09](p2-09-guide-web-deploy.md) | ✅ done | P2 | Player guide web app — builds clean from source | — | 🟢 |
--- a/.project/objectives/README.md
+++ b/.project/objectives/README.md
@ -16,9 +16,9 @@
 |---|---|---|---|---|---|---|---|
 | **P0** | 0 | 3 | 0 | 1 | 0 | 39 | 43 |
 | **P1** | 0 | 4 | 0 | 8 | 1 | 21 | 34 |
-| **P2** | 0 | 4 | 0 | 2 | 0 | 16 | 22 |
+| **P2** | 1 | 4 | 0 | 1 | 0 | 16 | 22 |
 | **P3 (oos)** | 0 | 0 | 0 | 0 | 17 | 0 | 17 |
-| **total** | **0** | **11** | **0** | **11** | **18** | **76** | **116** |
+| **total** | **1** | **11** | **0** | **10** | **18** | **76** | **116** |

 </td><td valign='top' style='padding-left:2em'>

@ -34,6 +34,16 @@

 </td></tr></table>

+## 🔵 In Progress
+
+> Actively claimed by a team lead. Grouped by owner.
+
+### [shipwright](../team-leads/shipwright.md)
+
+| ID | Priority | Title | Updated | Blocked |
+|---|---|---|---|---|
+| [p2-06b](p2-06b-windows-runner.md) | P2 | Cross-compile Windows .exe + .dll from Linux via cargo-xwin (no Windows host) | 2026-04-25 | 🟢 unblocked |
+
 ## P0 — Blockers

 | ID | Status | Title | Tags | Owner | Updated | Blocked |
@ -68,7 +78,6 @@
 | [p2-10a](p2-10a-gdlint-ungate.md) | 🟡 partial | CI: gdlint stage un-gated | — | [testwright](../team-leads/testwright.md) | 2026-04-25 | 🟢 unblocked |
 | [p2-10b](p2-10b-gut-ungate.md) | 🟡 partial | CI: headless GUT stage un-gated | — | [testwright](../team-leads/testwright.md) | 2026-04-25 | 🟢 unblocked |
 | [p2-18](p2-18-guide-public-deployment.md) | 🟡 partial | Guide web app — public hosting + deploy pipeline | — | — | 2026-04-17 | 🟢 unblocked |
-| [p2-06b](p2-06b-windows-runner.md) | ❌ missing | Register a Windows runner for forgejo to produce .dll + .exe on tag push | — | [shipwright](../team-leads/shipwright.md) | 2026-04-25 | 🟢 unblocked |
 | [p2-12](p2-12-apricot-weston-install.md) | ❌ missing | Install weston on apricot RUN host — unblock display-server smoke tests | — | [shipwright](../team-leads/shipwright.md) | 2026-04-25 | 🟢 unblocked |

 ## Out of Scope
--- a/.project/objectives/objectives.json
+++ b/.project/objectives/objectives.json
@ -1,11 +1,11 @@
 {
-  "generated_at": "2026-04-26T00:12:42Z",
+  "generated_at": "2026-04-26T00:43:23Z",
  "totals": {
    "done": 76,
-    "in_progress": 0,
+    "in_progress": 1,
    "partial": 11,
    "stub": 0,
-    "missing": 11,
+    "missing": 10,
    "oos": 18,
    "total": 116
  },
@ -903,14 +903,14 @@
    },
    {
      "id": "p2-06b",
-      "title": "Register a Windows runner for forgejo to produce .dll + .exe on tag push",
+      "title": "Cross-compile Windows .exe + .dll from Linux via cargo-xwin (no Windows host)",
      "priority": "p2",
-      "status": "missing",
+      "status": "in_progress",
      "scope": "game1",
      "owner": "shipwright",
      "updated_at": "2026-04-25",
      "blocked_by": [],
-      "summary": "Godot does not cross-compile Windows binaries from a macOS or Linux EDIT host; native Windows is required to produce both the `.exe` (Godot export) and `libmagic_civ_physics.dll` (GDExtension cargo build for `x86_64-pc-windows-msvc`). Without a registered Windows forgejo runner, every release will ship Linux + macOS only.\n\nSpun out from p2-06 on 2026-04-25 after `p2-06-verify-20260425` confirmed the Windows export produces only a `.tmp` placeholder when run on macOS."
+      "summary": "Originally framed as \"register a Windows runner\". Re-scoped 2026-04-25 (user pick) to **Option B: cargo-xwin cross-compile from Linux** — produces MSVC-ABI Windows binaries on the existing Linux runner, no Windows hardware required. Better ABI compatibility than mingw (especially for wgpu's d3d12 backend) and zero hardware cost.\n\nRecipe:\n1. Linux runner installs `cargo-xwin` (one-off): `cargo install cargo-xwin`\n2. Add MSVC target to rustup: `rustup target add x86_64-pc-windows-msvc`\n3. Install `clang` + `lld` (xwin uses these as linker)\n4. `bash src/simulator/build-gdext.sh x86_64-pc-windows-msvc` → cargo-xwin downloads MS SDK on first run (~1.5GB, cached at `~/.cache/cargo-xwin/`), builds `magic_civ_physics_gdext.dll`, copies to `engine/addons/magic_civ_physics/magic_civ_physics.x86_64.dll`\n5. `bash tools/export-single.sh windows <ver>` → Godot Linux exports the Windows .exe (cross-export is native to Godot), the script then relocates the .dll into `engine/addons/magic_civ_physics/` next to the binary\n\n`.forgejo/workflows/release.yml` retargeted to `runs-on: [self-hosted, linux, x86_64]` with a \"Setup MSVC cross-toolchain\" step."
    },
    {
      "id": "p2-07",
--- a/.project/objectives/p2-06b-windows-runner.md
+++ b/.project/objectives/p2-06b-windows-runner.md
@ -31,10 +31,10 @@ Recipe:
 - ✓ `tools/export-single.sh windows` runs the cargo-xwin build inline (`BUILD_WINDOWS_DLL=1` default) and relocates the produced .dll into `engine/addons/magic_civ_physics/` post-export. (2026-04-25)
 - ✓ `src/simulator/build-gdext.sh x86_64-pc-windows-msvc` invokes `cargo xwin build` and copies the .dll to `engine/addons/magic_civ_physics/magic_civ_physics.x86_64.dll`. (2026-04-25)
 - ✓ `.forgejo/workflows/release.yml` `windows_build` job uses Linux runner with cross-toolchain setup step. (2026-04-25)
- ❌ Apricot has cargo-xwin + clang + lld + the MSVC target installed (one-off setup).
- ❌ End-to-end smoke: `bash tools/export-single.sh windows p2-06b-verify-<stamp>` on apricot produces a `.exe` + `.dll` archive.
- ❌ Windows archive boots-and-plays a 10-turn AUTO_PLAY game (verified on Wine on apricot, OR on a real Windows machine).
- ❌ Update `.forgejo/RUNNER_SETUP.md` to drop the Windows runner section and document the Linux-runner cross-compile prereqs.
+- ✓ Apricot has cargo-xwin + clang + the MSVC target installed (`cargo install cargo-xwin` ran cleanly; clang already present from clang-21 rpm; lld not needed — cargo-xwin's own xwin sub-tool resolved the linker via the bundled MSVC SDK download). (2026-04-25)
+- ✓ End-to-end smoke: `BUILD_WINDOWS_DLL=0 EXPORT_STAGED=1 bash tools/export-single.sh windows p2-06b-test-20260425` on apricot produced `MagicCivilization.exe` (111MB, PE32+) + `engine/addons/magic_civ_physics/magic_civ_physics.x86_64.dll` (10MB, MSVC ABI). cargo-xwin .dll build took 2m47s including SDK download; Godot windows export took ~1min; total <4min. (2026-04-25)
+- ❌ Windows archive boots-and-plays a 10-turn AUTO_PLAY game (verified on Wine on apricot, OR on a real Windows machine). Wine not installed on apricot — needs `dnf install wine` (sudo) OR a real Windows host.
+- ✓ Update `.forgejo/RUNNER_SETUP.md` to drop the Windows runner section and document the Linux-runner cross-compile prereqs. (2026-04-25)

 ## Non-goals