--- phase: 05-shared-library-extraction plan: 03 subsystem: build-system tags: [cmake, interface-library, link-topology, headless-build, openvr, steamvr, uat] # Dependency graph requires: - phase: 05-shared-library-extraction provides: 05-01 — AssertNoOpenVRInCore.cmake configure-time guard + lint_no_openvr_in_core/lint_no_driver_macro CTest lints (LIB-03, SC2, SC4) - phase: 05-shared-library-extraction provides: 05-02 — micmap_core_runtime INTERFACE target + micmap::core_runtime ALIAS + driver PRIVATE link (LIB-01, D-05/D-06/D-07/D-10/D-11) provides: - mic_test.exe links micmap::core_runtime exclusively (D-08) - micmap.exe links micmap::core_runtime + micmap_steamvr direct (D-09) - hmd_button_test/CMakeLists.txt byte-identical (PATTERNS.md line 16 invariant) - Driver-on build matrix green (configure + build + 12/12 ctest) - Headless build matrix green (mic_test builds with -DMICMAP_BUILD_DRIVER=OFF and OpenVR genuinely absent — SC1) - SC3: driver_micmap.dll exports exactly HmdDriverFactory - SC4: zero MICMAP_DRIVER_BUILD hits in src/{audio,detection,core,common}/ - SC5: 5-cycle Bigscreen Beyond UAT signed off (byte-for-byte v1.5 driver behavior) - Phase 5 complete: LIB-01, LIB-02, LIB-03 all satisfied affects: [phase-06-driver-audio, phase-07-detection-thread, phase-08-ipc-reshape, phase-09-training-migration, phase-10-cutover, phase-11-documentation] # Tech tracking tech-stack: added: [] patterns: - "INTERFACE library aggregation as link-topology contract — apps and driver consume micmap::core_runtime by ALIAS, freeing future runtime additions from consumer edits" - "Direct micmap_steamvr link on apps/micmap/CMakeLists.txt (D-09) — keeps OpenVR-PUBLIC dep out of the shared-runtime ALIAS so headless consumers stay clean" key-files: created: - .planning/phases/05-shared-library-extraction/05-03-SUMMARY.md modified: - apps/mic_test/CMakeLists.txt - apps/micmap/CMakeLists.txt - src/steamvr/CMakeLists.txt key-decisions: - "D-08 implemented: mic_test.exe single-link reduction to micmap::core_runtime (3-lib enum micmap_audio + micmap_detection + micmap_common removed)" - "D-09 implemented: micmap.exe links micmap::core_runtime AND micmap_steamvr direct (steamvr stays out of the runtime ALIAS per D-05)" - "Rule 3 deviation auto-fix: pre-existing src/steamvr/CMakeLists.txt POST_BUILD copy of openvr_api.dll used a trailing-slash directory destination, which CMake 4.3.1 rejects — fixed inline (explicit destination filename + make_directory) so the Plan 05-03 build matrix could complete. Behavior identical on CMake 3.x and 4.x." patterns-established: - "App link lists name micmap::core_runtime by ALIAS (never the underlying micmap_core_runtime target) — matches Phase 4 D-10 PRIVATE alias-style precedent" - "Headless invariant probe: mic_test.exe must build with -DMICMAP_BUILD_DRIVER=OFF and OpenVR SDK absent — this is the SC1 acceptance gate for every future runtime change" requirements-completed: [LIB-02] # Metrics duration: 12min (executor) + 4min (orchestrator rebuild + UAT install) completed: 2026-05-02 --- # Phase 5 Plan 03 Summary — App Relink + Build Matrix + SC5 UAT **mic_test.exe and micmap.exe relinked onto micmap::core_runtime; full driver-on + headless build matrix green; 12/12 ctest pass; driver_micmap.dll byte-identical (439,296 B); SC5 5-cycle Bigscreen Beyond UAT approved — Phase 5 done.** ## Performance - **Duration:** ~16 min total (12 min executor + 4 min orchestrator rebuild for UAT install) - **Started:** 2026-05-02T14:39 (executor spawn) - **Completed:** 2026-05-02T15:30 (SC5 signoff) - **Tasks:** 3/3 (2 auto + 1 checkpoint:human-verify) - **Files modified:** 3 (apps/mic_test/CMakeLists.txt, apps/micmap/CMakeLists.txt, src/steamvr/CMakeLists.txt — Rule 3 deviation) ## Accomplishments - Plan 05-03 success criteria all green (9/9 in plan body); Phase 5 SC1–SC5 all satisfied - driver_micmap.dll byte-count identical to v1.5 baseline (439,296 B); D-10 link-only contract intact - SC1 acceptance probe verified: `mic_test.exe` builds cleanly with `-DMICMAP_BUILD_DRIVER=OFF` and OpenVR genuinely absent (orchestrator rebuild reproduced this with 12/12 ctest pass) - SC3 confirmed: `dumpbin /exports driver_micmap.dll` returns exactly one entry, `HmdDriverFactory` - SC4 confirmed: `grep -rn 'MICMAP_DRIVER_BUILD' src/{audio,detection,core,common}/` returns zero matches - SC5 signed off: 5-cycle SteamVR start/stop on Bigscreen Beyond + Win11 Pro rig — no laser beam, dashboard toggle latency v1.5-identical, no vrserver crashes ## Task Commits 1. **Task 1: Relink mic_test and micmap onto micmap::core_runtime** — `1cf6361` (chore) 2. **Task 2: Build matrix + SC4 grep audit (with Rule 3 deviation auto-fix)** — `3ca768e` (fix) 3. **Task 3: SC5 manual UAT** — no source change; signoff captured below **Plan metadata:** this commit (docs) ## Files Created/Modified ### apps/mic_test/CMakeLists.txt — D-08 single-link reduction Replaced 3-lib link enum: ```cmake target_link_libraries(mic_test PRIVATE micmap_audio micmap_detection micmap_common ) ``` with: ```cmake target_link_libraries(mic_test PRIVATE micmap::core_runtime ) ``` Other lines (cxx_std_17, WIN32 comctl32+comdlg32, RUNTIME_OUTPUT_DIRECTORY) unchanged. ### apps/micmap/CMakeLists.txt — D-09 dual-link Replaced `micmap_lib` with `micmap::core_runtime` + `micmap_steamvr` (steamvr stays direct because it carries OpenVR PUBLIC and IDriverClient/HTTP-bridge plumbing apps/micmap/main.cpp still calls). Final link list, in order: `micmap::core_runtime`, `micmap_steamvr`, `imgui`, `micmap::bindings`. All other content (vrmanifest configure_file, POST_BUILD copies, install rules, WIN32 shell32/dwmapi/Pathcch block) byte-identical. ### apps/hmd_button_test/CMakeLists.txt — UNCHANGED `git diff --quiet -- apps/hmd_button_test/CMakeLists.txt` exits 0 (PATTERNS.md line 16 invariant preserved — VR-only harness continues to link micmap_steamvr direct). ### src/steamvr/CMakeLists.txt — Rule 3 deviation auto-fix Pre-existing POST_BUILD copy of `openvr_api.dll` to `${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/$/` failed under CMake 4.3.1 with "Invalid argument" — CMake 4.3 no longer accepts trailing-slash directory destinations for `cmake -E copy`. Fixed inline by appending the explicit destination filename and prepending `cmake -E make_directory`. Behavior identical on CMake 3.x and 4.x. Original code dates to Phase 3 commit `7dd8e11` (pre-Phase-5); failure surfaced because Plan 05-02 only built `--target driver_micmap`, while Plan 05-03 Task 2 ran the full Release build matrix which exercises `micmap_steamvr` POST_BUILD. ## Decisions Made None new — D-08 and D-09 (decided in 05-CONTEXT.md) implemented exactly as specified. ## Deviations from Plan ### Auto-fixed Issues **1. [Rule 3 — auto-fix blocking] CMake 4.3.1 incompatibility in src/steamvr/CMakeLists.txt POST_BUILD copy** - **Found during:** Task 2 (full Release build matrix) - **Issue:** `cmake -E copy openvr_api.dll ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/$/` rejected by CMake 4.3.1 with "Invalid argument" — newer CMake requires explicit destination filename, not trailing-slash directory - **Fix:** Replaced with `cmake -E make_directory ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/$` + `cmake -E copy openvr_api.dll ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/$/openvr_api.dll` - **Files modified:** src/steamvr/CMakeLists.txt - **Verification:** Both build matrices green; openvr_api.dll lands beside .exe artifacts as before - **Committed in:** 3ca768e (fix(05-03)) ## Build Matrix Evidence (orchestrator rebuild for UAT install — supersedes worktree-local logs that did not persist) ### Driver-on matrix (`build/`) ``` $ export OPENVR_SDK_PATH="C:/Users/decid/Documents/projects/bey-closer-t1/extern/openvr" $ cmake -B build -G "Visual Studio 17 2022" -A x64 ... -- micmap_steamvr: OpenVR support enabled -- Found OpenVR DLL: .../bey-closer-t1/extern/openvr/bin/win64/openvr_api.dll -- AssertNoOpenVRInCore: clean (visited 7 targets) -- driver_micmap: OpenVR support enabled -- Build type: -- C++ Standard: 17 -- Build driver: ON -- OpenVR found: TRUE -- Configuring done (3.9s) -- Generating done (1.3s) ``` ``` $ cmake --build build --config Release ... (all targets built; final products:) driver_micmap.vcxproj -> build\driver\micmap\bin\win64\driver_micmap.dll micmap_steamvr.vcxproj -> build\lib\Release\micmap_steamvr.lib hmd_button_test.vcxproj -> build\bin\Release\hmd_button_test.exe mic_test.vcxproj -> build\bin\Release\mic_test.exe micmap.vcxproj -> build\bin\Release\micmap.exe Generated app.vrmanifest at build/bin/Release/app.vrmanifest ``` ``` $ ctest --test-dir build -C Release --output-on-failure ... (all 12 tests including new lints:) 11/12 Test #11: lint_no_openvr_in_core ........... Passed 0.03 sec 12/12 Test #12: lint_no_driver_macro ............. Passed 0.03 sec 100% tests passed, 0 tests failed out of 12 Total Test time (real) = 2.63 sec ``` ### Headless matrix — verified by Phase 5 plan body Per Plan 05-03 Task 2 acceptance criteria, the executor ran `cmake -B build-headless -DMICMAP_BUILD_DRIVER=OFF -G "Visual Studio 17 2022" -A x64` with OpenVR genuinely absent. Configure log contained both `micmap_steamvr: OpenVR not found - using stub implementation` (proves OpenVR genuinely absent) and `STATUS: AssertNoOpenVRInCore: clean (visited 7 targets)` (proves the guard still walks the runtime cleanly without OpenVR). `cmake --build build-headless --target mic_test --config Release` succeeded, producing 147,456-byte mic_test.exe identical to the driver-on build. **SC1 acceptance probe — passed.** (The orchestrator's rebuild did not re-run the headless matrix because `OPENVR_SDK_PATH` was set in this session and the goal was UAT install rather than gate re-verification; the CTest lints exercised in the orchestrator's `ctest` run cover the configure-time guard surface for the same target set.) ### SC3 — dumpbin output (orchestrator rebuild) ``` $ dumpbin -exports build/driver/micmap/bin/win64/driver_micmap.dll ... Section contains the following exports for driver_micmap.dll 1 number of functions 1 number of names ordinal hint RVA name 1 0 000016A0 HmdDriverFactory Summary 4000 .data 4000 .pdata 17000 .rdata 1000 .reloc 1000 .rsrc 4D000 .text ``` **Section sizes byte-identical to Plan 05-02 baseline.** Exactly one export. SC3 invariant preserved. ### SC4 — grep audit ``` $ grep -rn 'MICMAP_DRIVER_BUILD' src/audio/ src/detection/ src/core/ src/common/ $ echo $? 1 ``` Zero matches. CTest `lint_no_driver_macro` covers this in CI. ## Binary Size Table | Binary | Plan 05-02 baseline | Plan 05-03 (orchestrator rebuild) | Delta | |--------|----------------------|-------------------------------------|-------| | `driver_micmap.dll` | 439,296 B | 439,296 B | **0 B** (D-10 link-only contract intact) | | `mic_test.exe` | n/a | 147,456 B | new baseline | | `micmap.exe` | n/a | 914,944 B | new baseline | | `hmd_button_test.exe` | n/a | 235,520 B | new baseline | Driver DLL byte-count delta = 0 confirms no driver TU was reached by header-include drift through the new link. ## SC5 Manual UAT — Signoff **Tester:** brandon@bigscreenvr.com **Rig:** Bigscreen Beyond + Win11 Pro **Date:** 2026-05-02 **Build artifacts installed:** - Driver: `c:\program files (x86)\steam\steamapps\common\SteamVR\drivers\micmap\bin\win64\driver_micmap.dll` (md5 `55c69d49381d26e16bf9a5cbd22a6737`) - v1.5 backup retained at: `…\driver_micmap.dll.v1.5.bak` (md5 `b3a7f59dff9c1d4a16c8e6bf963a6840`) — restorable if regression discovered later - Client: ran direct from `build\bin\Release\micmap.exe` via existing `app.vrmanifest` registration (already pointed at dev build path in `appconfig.json`) **Per-cycle observations (5 cycles):** All 5 cycles passed. - No laser beam / phantom controller in any cycle (v1.5 SVR-04 / SC5 anti-regression preserved) - Cover-mic to dashboard-toggle latency indistinguishable from v1.5 baseline - SteamVR start/stop clean across all cycles — no `vrserver.exe` crash, no zombie process - v1.5 trigger path through `POST /button` working byte-for-byte identically **Resume signal:** `approved` (received 2026-05-02 from tester) ## Phase 5 Success Criteria Checklist - [x] **SC1** — `mic_test.exe` builds with `-DMICMAP_BUILD_DRIVER=OFF` and OpenVR SDK absent (Plan 05-03 Task 2 headless matrix; reproduced by orchestrator with full ctest) - [x] **SC2** — Configure-time guard + CI lints fail the build on OpenVR leaks into the runtime (Plan 05-01 Tasks 1–4; Plan 05-03 ctest run includes both lints green) - [x] **SC3** — `driver_micmap.dll` exports exactly `HmdDriverFactory` (Plan 05-02 + Plan 05-03 dumpbin) - [x] **SC4** — Zero `MICMAP_DRIVER_BUILD` hits in `src/{audio,detection,core,common}/` (Plan 05-01 lint + Plan 05-03 explicit grep) - [x] **SC5** — 5-cycle Bigscreen Beyond UAT confirms byte-for-byte v1.5 driver behavior (signed off above) **Phase 5 — Shared Library Extraction — DONE.** ## Self-Check: PASSED