Files
aevolution/docs/adr/0086-windows-client-package.md
T
dingoandClaude Opus 5.5 6262c778c7 Add M9.8e reproducible Windows client package
Static-runtime client-package preset with /Brepro and a build identity printed by
evo-client --version (ADR-0086). tools/client packages an explicit allowlist with
licence texts from the verified sources, BUILD-INFO and SHA256SUMS into a
deterministic ZIP, refusing credentials, profile paths and non-system imports;
verification runs the extracted client without Visual Studio, and a self-test
proves each guard. Publication via Gitea Actions waits for a Windows runner.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-02 16:48:12 -04:00

3.3 KiB

ADR-0086: Windows client package

Status

Accepted for M9.8e (2026-10-02). Local packaging on the Windows development host; Gitea Actions publication waits for a Windows runner. Internal test builds only.

Context

Testers need a Windows x64 ZIP of the engineering client that runs on a clean machine, says exactly which build it is, carries third-party notices, and cannot leak development credentials. No Windows CI runner exists yet; the Linux runner must not silently build Windows packages and no untested cross-compile is assumed.

Decision

  • Preset client-package (client + network) links the static MSVC runtime (CMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded) for the client, SDL, Mbed TLS and Dear ImGui, so no Visual C++ redistributable or Microsoft runtime DLL is shipped or required. Executables may import only listed Windows system DLLs and the bundled SDL3.dll; the scripts check this from the PE import tables.
  • EVO_REPRODUCIBLE adds /Brepro to every MSVC compile and link, before any dependency is added. ZIP entries are sorted, under one top folder, stamped with the commit time. A rebuild of the same commit on the same toolchain should give the same ZIP; this is verified, not assumed (see VALIDATION.md).
  • Identity g<12 hex of commit>[-dirty] is configured as EVO_BUILD_IDENTITY and printed by evo-client --version. Packaging refuses uncommitted tracked changes unless -AllowDirty, which marks the identity dirty.
  • tools/client/package-windows.ps1 builds and runs the client/network CTest suite in that preset, then stages an explicit allowlist: evo-client.exe, SDL3.dll, README, BUILD-INFO (commit, toolchain, dependency versions and source checksums, test summary), THIRD-PARTY-NOTICES and LICENSES copied from the checksum-verified sources (SDL with its compiled HIDAPI, yuv2rgb, stb_image and Khronos headers; Mbed TLS under Apache-2.0; Dear ImGui with embedded fonts and stb headers), and SHA256SUMS. It refuses any other file, credential file types, PEM private keys or certificates, and embedded user-profile paths.
  • tools/client/verify-windows-package.ps1 needs no Visual Studio: it checks the ZIP digest, content and checksums, imports and secrets, then runs the extracted client with only system directories on PATH (version, usage error, fixture and launcher with the dummy driver, credential-file failure; optionally a window).
  • The README states an internal engineering test build: no licence is granted and it must not be redistributed. Third-party licences are reproduced in full.
  • Publication: none automated yet. The ZIP and .sha256 are produced locally; a Gitea Actions job will be added only with a registered Windows runner.

Alternatives considered

  • App-local VC++ runtime DLLs: redistributes Microsoft binaries and their terms.
  • Requiring the VC++ redistributable: a setup step that testers can miss.
  • CPack: adds a generator layer for a single ZIP with custom checks.
  • A gated Windows workflow job now: unexecuted and untested until a runner exists.

Consequences

Static runtime: each image has its own CRT state; SDL's C API passes no CRT objects across the DLL boundary. Package and verification scripts change with the file list. Clean-machine/VM runs and minimum hardware remain M9.8g qualification. The notice inventory is an engineering record, not a legal review.