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

68 lines
4.2 KiB
Markdown

[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).