Files
aevolution/docs/adr/0086-windows-client-package.md
2026-10-08 12:08:53 -04:00

4.2 KiB

[Reviewed]

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.

Amendment (M10.5c, 2026-10-06): msquic.dll

  • The package adds msquic.dll (msquic 2.6.2, MIT, with OpenSSL 3.5.9 built static inside, Apache-2.0; pins and sources as in ADR-0090) and LICENSES/msquic.txt and LICENSES/OpenSSL.txt, copied from the verified sources. BUILD-INFO lists both pins.
  • msquic links the whole C runtime statically (QUIC_STATIC_LINK_PARTIAL_CRT=OFF; its default imported the UCRT forwarders). Allowed imports add msquic.dll and the system DLLs it needs: crypt32, iphlpapi, ncrypt, ntdll. All three images are checked.
  • Determinism: OpenSSL is built by msquic with nmake, outside CMake's /Brepro; the package script sets CL=/Brepro (cl.exe reads options from it) and SOURCE_DATE_EPOCH (the commit time, used by OpenSSL's build-date string) for the build.
  • The package CTest run adds the label quic-session (QUIC session and client remote session tests).