Files
alkane-toolkit/docs/adr/0004-windows-port.md

2.5 KiB

ADR 0004: Windows port

Date: 2026-11-02

Context

The GUI is wxWidgets through the patched wx-rs bridge (ADR 0002), so most of it is portable, but the patches and the app had only ever run on GTK. The Windows build has to look and behave like a native Windows 10/11 application, ship from the same CI as Linux, and stay maintainable for a team that develops on Linux.

Decision

  • Build on Linux: cross-compile with mingw-w64 (posix threads) against the vendored wxWidgets built as static wxMSW (scripts/build-wx-windows.sh). The wx-rs build script now picks the platform from CARGO_CFG_TARGET_* (a build script's cfg!() describes the host) and builds Windows/GNU through wx-config exactly like GTK. The C++ runtime is linked statically; the .exe imports only Windows system DLLs.
  • Native look comes from wxMSW plus an application manifest (crates/alkane-gui/windows/): Common Controls v6, per-monitor DPI awareness v2, UTF-8 code page, Windows 10/11 compatibility, icon and version resources. Light/dark follows the Windows app mode.
  • Platform code is contained: OS differences in Rust live in alkane_core::platform (config directory, owner-only secret files, null device, console-less child processes); in C++ they are #ifdef __WXMSW__ / __WXGTK__ sections of the bridge, with shared logic (icon hit-testing) in plain functions both use.
  • Sizes cross the Rust/C++ boundary in DIPs, converted per window with FromDIP/ToDIP. That is the identity on GTK, so Linux output is unchanged.
  • SSH password logins use SSH_ASKPASS with the toolkit's own executable as the helper, on every platform, replacing sshpass (absent on Windows).
  • CI tests the Windows build under Wine on the existing Linux runners (the release gate), and again on real Windows 11 through a self-hosted VM runner (advisory, never blocking).
  • The wx-rs patch queue must reproduce the patched tree from the pristine upstream crate; scripts/wx_rs_patches.py check enforces it in CI.

Consequences

  • One toolchain and one CI fleet for both platforms; no Windows build machine.
  • Wine is a good but not perfect stand-in for Windows; the native VM job covers the gap without making releases depend on the VM being up.
  • Bridge changes need checking on both toolkits: GTK uses the native tree view, wxMSW the generic data view, which differ in input routing, painting and selection style (see docs/windows.md).
  • macOS remains out of scope (no Mac to build or test on).