Start CMake modernization scaffold

2026-05-31 23:40:43 +02:00
parent ee027984b7
commit c38ff8209b
36 changed files with 2118 additions and 1556 deletions
--- a/docs/modernization/roadmap.md
+++ b/docs/modernization/roadmap.md
@@ -0,0 +1,553 @@
+# PanoPainter Modernization Roadmap
+
+Status: live
+Last updated: 2026-05-31
+
+This is the living roadmap for modernizing PanoPainter into independently
+testable C++23 components while retaining all existing functionality. Keep this
+file current as phases are implemented. Do not let shortcuts, skipped platforms,
+or temporary adapters live only in chat history.
+
+## How To Keep This Roadmap Live
+
+- Update the phase status before and after each implementation pass.
+- When a shortcut is introduced, add it to the debt log section in this file
+  until `docs/modernization/debt.md` exists, then move debt entries there.
+- When a major architectural decision is made, add an ADR under `docs/adr/`
+  once that directory exists.
+- Every phase must preserve old behavior unless the roadmap explicitly says
+  otherwise.
+- Each phase must leave the repo in a buildable and testable state.
+- Do not add stubs without a debt entry, validation command, and removal
+  condition.
+
+## Locked Decisions
+
+- Graphics path: keep OpenGL working first; add Vulkan and Metal after the
+  renderer boundary exists.
+- Required platforms at phase gates: Windows desktop/AppX, macOS, iOS,
+  Android standard, Quest, Focus/Wave, Linux, and WebGL.
+- Dependency policy: use vcpkg where reliable; keep SDK, patched, or
+  vendor-only dependencies with documented reasons.
+- Test stack: Catch2, golden/approval tests, and fuzz/property tests where
+  useful.
+- Automation: local reproducible matrix first; hosted CI can be added later.
+- Documentation: ADRs, debt log, and this living roadmap.
+- "vkpkg" in older notes means `vcpkg`.
+- Target C++ standard: C++23.
+- Initial Windows CMake generator target: Visual Studio 2026 when available.
+
+## Phase Status
+
+| Phase | Name | Status | Gate |
+| --- | --- | --- | --- |
+| 0 | Inventory, Safety Rails, And Memory | Complete | No behavior changes; old builds still work |
+| 1 | Unified CMake Skeleton | In progress | Root CMake builds the Windows app and owns the source list |
+| 2 | Toolchain, Diagnostics, And Dependencies | In progress | Strict desktop library builds compile cleanly |
+| 3 | Test Harness And Agent-Ready Automation | In progress | `ctest --preset desktop-fast` runs headlessly |
+| 4 | Component Split Without Behavior Change | Started | Each extracted target builds and tests |
+| 5 | Renderer Boundary And OpenGL Parity | Not started | OpenGL output matches golden readbacks |
+| 6 | Platform Alignment | Not started | Every supported platform has named validation |
+| 7 | Hardening, Coverage, And Breaking-Point Tests | Not started | Each component has edge/failure tests |
+| 8 | Future Backend Readiness | Not started | Vulkan/Metal lab targets remain non-default |
+
+## Target Component Architecture
+
+The refactor should move toward one-way dependencies:
+
+```text
+pp_foundation
+  -> pp_assets
+  -> pp_paint
+  -> pp_document
+  -> pp_renderer_api
+  -> pp_renderer_gl
+  -> pp_paint_renderer
+  -> pp_ui_core
+  -> pp_panopainter_ui
+  -> pp_platform_*
+  -> panopainter_app
+```
+
+Intended responsibilities:
+
+- `pp_foundation`: logging facade, math/util helpers, events, task queues,
+  binary streams.
+- `pp_assets`: `Asset`, `Image`, `Settings`, serialization, ABR, PPBR, and PPI
+  helpers.
+- `pp_paint`: pure `Brush`, `Stroke`, stroke sampling, and CPU reference blend
+  math.
+- `pp_document`: canvas document model, layers, animation frames, and undo/redo
+  model.
+- `pp_renderer_api`: renderer-neutral interfaces for textures, render targets,
+  shaders, meshes, readback, frame capture, and tracing.
+- `pp_renderer_gl`: current OpenGL implementation behind renderer interfaces.
+- `pp_paint_renderer`: stroke rasterization, layer compositing, cube/equirect
+  export using `pp_renderer_api`.
+- `pp_ui_core`: `Node`, layout, generic controls, text/image primitives.
+- `pp_panopainter_ui`: panels, dialogs, `NodeCanvas`, and app-specific
+  workflows.
+- `pp_platform_*`: Windows, macOS/iOS, Android, Linux, and WebGL shells.
+- `panopainter_app`: composition root only.
+
+Rules:
+
+- Component headers must not include platform SDK or graphics API headers unless
+  the component name includes that backend or platform.
+- Pure libraries must build and test without a window, GL context, network,
+  tablet, VR headset, or filesystem outside test temp directories.
+- Public APIs should return explicit status/result objects. PanoPainter app
+  code keeps exceptions disabled unless isolated SDK wrappers require them.
+- Singleton access should be replaced at component boundaries with context or
+  service objects. Temporary facade shims require debt entries.
+
+## Phase 0: Inventory, Safety Rails, And Memory
+
+Status: complete on 2026-05-31. Created this roadmap,
+`docs/modernization/debt.md`, `docs/modernization/capability-map.md`,
+`docs/modernization/build-inventory.md`, and ADR 0001.
+
+Goal: create durable project memory and prevent silent shortcuts before large
+refactors begin.
+
+Implementation tasks:
+
+- Add `docs/modernization/roadmap.md`, `docs/modernization/debt.md`, and
+  `docs/adr/`.
+- Add a shortcut rule: every temporary adapter, fallback, skipped platform, or
+  retained vendored dependency must have owner, reason, validation command, and
+  removal condition.
+- Generate a current capability map covering:
+  - project open/save and PPI compatibility
+  - image import/export and thumbnails
+  - brush presets, ABR import, PPBR export/import
+  - layers, blend modes, alpha lock, selection mask
+  - animation frames and MP4/timelapse recording
+  - VR, tablet, touch, mouse, keyboard, gestures
+  - cloud upload/download/browse
+  - UI dialogs, panels, layout XML, settings
+  - Windows/AppX, macOS, iOS, Android standard, Quest, Focus/Wave, Linux, WebGL
+- Record current build commands and known platform prerequisites.
+
+Gate:
+
+- No behavior changes.
+- Existing Visual Studio, platform CMake, Gradle, Apple, Linux, and WebGL paths
+  are not removed.
+
+## Phase 1: Unified CMake Skeleton
+
+Goal: make CMake the canonical source list without breaking existing projects.
+
+Status: in progress. Root `CMakeLists.txt`, `CMakePresets.json`, and project
+option targets exist. The Windows desktop app builds through CMake as
+`PanoPainter`; the raw Visual Studio solution/project files were removed on
+2026-05-31 by user decision. Non-Windows platform build files remain during
+Phase 6 alignment.
+
+Implementation tasks:
+
+- Add root `CMakeLists.txt` and shared CMake modules under `cmake/`.
+- Add `CMakePresets.json` with at least:
+  - `windows-vs2026-x64`
+  - `windows-clangcl-asan`
+  - `linux-clang`
+  - `android-arm64`
+  - `android-x64`
+  - `emscripten`
+  - `macos`
+  - `ios-device`
+  - `ios-simulator`
+- Keep Android CMake, Linux CMake, WebGL CMake, Apple project files, and AppX
+  packaging during the transition until each consumes shared component targets.
+- Move version generation into a CMake custom command using
+  `scripts/pre-build.py`.
+- Fix `scripts/pre-build.py` only if required to avoid unnecessary rewrites or
+  missing-tag failures.
+- Add CMake options:
+  - `PP_BUILD_APP`
+  - `PP_BUILD_TESTS`
+  - `PP_BUILD_TOOLS`
+  - `PP_ENABLE_OPENGL`
+  - `PP_ENABLE_VULKAN_EXPERIMENTAL=OFF`
+  - `PP_ENABLE_VR`
+  - `PP_ENABLE_CLOUD`
+  - `PP_ENABLE_VIDEO`
+- Define source-list helper targets so per-platform source duplication can be
+  reduced incrementally.
+
+Gate:
+
+- Windows desktop app builds through CMake.
+- New CMake can configure on Windows.
+- Source list differences are understood and documented.
+- Non-Windows platform migration is debt-tracked until Phase 6.
+
+## Phase 2: Toolchain, Diagnostics, And Dependencies
+
+Goal: turn the build into an error-finding system before deep refactors.
+
+Status: in progress. Initial warning/sanitizer option targets and `vcpkg.json`
+exist. Dependency migration is not complete until component targets consume
+vcpkg packages and platform triplets are validated.
+
+Implementation tasks:
+
+- Set C++23 through target features, not raw compiler flags.
+- Add warning profiles:
+  - MSVC: `/W4 /permissive- /Zc:__cplusplus /Zc:preprocessor`.
+  - Optional MSVC analysis preset: `/analyze`.
+  - Clang/GCC: `-Wall -Wextra -Wpedantic -Wconversion -Wshadow
+    -Wnull-dereference`.
+- Keep exceptions disabled for PanoPainter targets, except isolated SDK wrapper
+  targets when unavoidable.
+- Add sanitizer presets:
+  - Clang/GCC ASan and UBSan for headless libraries.
+  - MSVC ASan where supported.
+  - TSan only for pure/headless targets.
+- Add tooling hooks:
+  - `clang-tidy`
+  - `cppcheck`
+  - shader validation or compile checks
+  - CTest dashboard output
+- Add `vcpkg.json`.
+- Move reliable dependencies to vcpkg first:
+  - `fmt`
+  - `glm`
+  - `tinyxml2`
+  - `stb`
+  - `curl`
+  - `sqlite3`
+  - `glad`
+  - `Catch2`
+- Keep vendored until proven:
+  - OpenVR
+  - OVR/Wave SDKs
+  - Wacom WinTab
+  - AppCenter
+  - openh264
+  - mp4v2
+  - libyuv
+  - patched or SDK-specific libraries
+
+Gate:
+
+- Desktop library targets compile with strict diagnostics.
+- New warnings caused by refactor are fixed or locally justified.
+- No global blanket warning suppression for project code.
+
+## Phase 3: Test Harness And Agent-Ready Automation
+
+Goal: make each component reachable by automated tools and future agents.
+
+Status: in progress. `tests/` exists, `desktop-fast` runs headlessly, and
+PowerShell/bash wrappers exist for configure/build/test/analyze. `pano_cli`
+exists with a first JSON automation command for validating create-document
+inputs; full document/app integration is debt-tracked as DEBT-0006.
+
+Implementation tasks:
+
+- Add `tests/` with one executable per component.
+- Register CTest labels:
+  - `foundation`
+  - `assets`
+  - `paint`
+  - `document`
+  - `renderer`
+  - `ui`
+  - `platform`
+  - `integration`
+  - `fuzz`
+  - `slow`
+  - `gpu`
+- Add `tools/pano_cli` for headless automation.
+- `pano_cli` should support:
+  - create document
+  - load project
+  - save project
+  - apply scripted strokes
+  - import/export images
+  - inspect layers
+  - run layout parse
+  - emit JSON results
+- Add local automation wrappers under `scripts/automation/`:
+  - configure
+  - build
+  - test
+  - analyze
+  - package smoke
+- All wrappers must return machine-readable logs or summaries.
+- Establish `tests/data/` fixtures:
+  - tiny PPI files
+  - corrupt/truncated PPI cases
+  - PNG/JPEG fixtures
+  - ABR/PPBR samples
+  - layout XML
+  - shader snippets
+  - brush stroke scripts
+
+Gate:
+
+- `ctest --preset desktop-fast --build-config Debug` runs without a GL
+  context.
+- Non-render components can be tested on a headless machine.
+
+## Phase 4: Component Split Without Behavior Change
+
+Goal: split libraries while keeping current app behavior.
+
+Status: started. `pp_foundation` exists with binary stream utilities and
+boundary/overread tests. Continue extracting legacy-safe utilities before
+moving assets, paint, or document behavior.
+
+Implementation tasks:
+
+- Extract components in this order:
+  1. `pp_foundation`
+  2. `pp_assets`
+  3. `pp_paint`
+  4. `pp_document`
+  5. `pp_renderer_api`
+  6. `pp_renderer_gl`
+  7. `pp_paint_renderer`
+  8. `pp_ui_core`
+  9. `pp_panopainter_ui`
+  10. `pp_platform_*`
+  11. `panopainter_app`
+- Remove renderer/platform dependencies from pure headers first, especially:
+  - `Brush`
+  - document/layer model
+  - serializer
+  - UI core headers
+- Keep facade shims where needed, but debt-track every shim.
+- Avoid large behavioral rewrites during extraction.
+- Each extracted component gets a focused test suite before moving to the next.
+
+Gate:
+
+- Old app still launches.
+- Component tests pass after every extraction.
+- No undocumented stubs or shortcuts.
+
+## Phase 5: Renderer Boundary And OpenGL Parity
+
+Goal: make OpenGL an implementation detail and establish parity tests before
+adding new backends.
+
+Implementation tasks:
+
+- Introduce renderer interfaces:
+  - `IRenderDevice`
+  - `ITexture2D`
+  - `IRenderTarget`
+  - `IShaderProgram`
+  - `IMesh`
+  - `ICommandContext`
+  - `IReadbackBuffer`
+  - `IRenderTrace`
+- Port current renderer classes behind OpenGL backend types:
+  - `RTT`
+  - `Texture2D`
+  - `Sampler`
+  - `ShaderManager`
+  - `Shape`
+- Preserve current shader behavior and asset paths.
+- Add deterministic GPU tests:
+  - clear
+  - blit
+  - texture upload/download
+  - stroke composite
+  - erase
+  - layer blend
+  - equirect export
+  - readback bounds
+- Add CPU reference tests for blend modes.
+- Compare GPU output to golden/reference data with explicit tolerances.
+
+Gate:
+
+- OpenGL readbacks match golden data on Windows and Linux.
+- Mobile/WebGL compile gates remain green.
+
+## Phase 6: Platform Alignment
+
+Goal: every supported platform consumes the same component targets.
+
+Implementation tasks:
+
+- Convert these builds to shared component targets:
+  - Windows desktop
+  - Windows AppX
+  - macOS
+  - iOS
+  - Android standard
+  - Android Quest
+  - Android Focus/Wave
+  - Linux
+  - WebGL/Emscripten
+- Keep platform entrypoints thin:
+  - window lifecycle
+  - input dispatch
+  - clipboard
+  - file picker/share
+  - GL context creation
+  - VR SDK bridge
+  - packaging only
+- Add or refine CMake toolchain/preset support for:
+  - Android NDK ABIs
+  - iOS device
+  - iOS simulator
+  - macOS
+  - Emscripten
+- Keep SDK-only imported libraries documented until vcpkg triplets are proven.
+
+Gate:
+
+- Every platform has a named configure/build command.
+- Missing local prerequisites are documented.
+- Each platform has at least compile or package validation.
+
+## Phase 7: Hardening, Coverage, And Breaking-Point Tests
+
+Goal: tests should try to break components, not only confirm current happy
+paths.
+
+Implementation tasks:
+
+- Add property/fuzz tests for:
+  - binary streams
+  - serializers
+  - PPI parsing
+  - ABR parsing
+  - layout XML parsing
+  - image metadata parsing
+  - brush parameter extremes
+  - layer/frame operations
+  - undo/redo invariants
+- Add stress tests for:
+  - thousands of stroke samples
+  - extreme resolutions guarded by memory limits
+  - rapid layer/frame edits
+  - corrupt assets
+  - cancellation during export
+  - concurrent render/UI task scheduling
+- Add coverage for headless libraries on Clang/GCC.
+- Require coverage reports for changed components first; do not set a global
+  threshold until the baseline is meaningful.
+- Add tracing spans around:
+  - project load/save
+  - render passes
+  - stroke commit
+  - readback
+  - export
+  - UI layout
+  - platform I/O
+- Logs must include component, thread, frame/stroke id, and timing.
+
+Gate:
+
+- No shortcut remains undocumented.
+- Every component has unit tests and at least one failure or edge test.
+
+## Phase 8: Future Backend Readiness
+
+Goal: prepare Vulkan and Metal without destabilizing the OpenGL parity path.
+
+Implementation tasks:
+
+- Create non-default targets only after OpenGL backend parity:
+  - `pp_renderer_vulkan_lab`
+  - `pp_renderer_metal_lab`
+- Use `D:\Dev\vkpaint` as reference material for Vulkan painting experiments,
+  not as direct production code.
+- Before integration, prove:
+  - ping-pong compositing path
+  - input-attachment/subpass path where applicable
+  - feedback-loop or framebuffer-fetch-style path where supported
+  - synchronization and layout correctness under validation layers
+- Keep WebGPU as an optional future portability backend, not the core renderer
+  contract.
+
+Gate:
+
+- Vulkan/Metal lab targets are opt-in.
+- OpenGL production backend remains stable.
+
+## Test Matrix
+
+| Preset/Label | Purpose | Requires |
+| --- | --- | --- |
+| `desktop-fast` | Pure component unit tests | No GPU/window |
+| `desktop-gpu` | OpenGL backend golden/readback tests | GPU/GL context |
+| `fuzz` | Parser and serializer fuzzing | Fuzzer-capable compiler |
+| `stress` | Large and adversarial scenarios | Longer runtime |
+| `platform-build` | Configure/build each supported platform | Local toolchains |
+| `package-smoke` | AppX/APK/Apple/WebGL package smoke | Platform SDKs |
+
+Acceptance for each phase:
+
+- Previous phase tests still pass.
+- New component has its own tests.
+- No undocumented stubs.
+- No skipped platform without a debt entry.
+- Automation command is recorded in this roadmap or linked docs.
+
+## Verified Commands
+
+Last verified on 2026-05-31:
+
+```powershell
+cmake --preset windows-msvc-default
+cmake --build --preset windows-msvc-default --config Debug --target pp_foundation_tests pano_cli PanoPainter
+ctest --preset desktop-fast --build-config Debug
+powershell -ExecutionPolicy Bypass -File scripts\automation\test.ps1 -Preset desktop-fast -Configuration Debug
+powershell -ExecutionPolicy Bypass -File scripts\automation\build.ps1 -Preset windows-msvc-default -Configuration Debug -Target pano_cli
+```
+
+Results:
+
+- `pp_foundation_tests` passed.
+- `pano_cli_create_document_smoke` passed.
+- `PanoPainter.exe` built through CMake at
+  `out/build/windows-msvc-default/Debug/PanoPainter.exe`.
+- PowerShell build/test automation wrappers return JSON summaries and passed
+  local smoke checks.
+- Known remaining warnings: legacy project/vendor diagnostics, Visual Studio
+  vcpkg-manifest warning, `LNK4099` missing libyuv PDBs, and `LNK4098` runtime
+  library conflict from retained vendor binaries.
+
+## Current Debt Log
+
+The canonical debt log is now `docs/modernization/debt.md`. Keep this section
+as a reminder only; do not add new debt entries here.
+
+| ID | Status | Owner | Item | Reason | Validation | Removal Condition |
+| --- | --- | --- | --- | --- | --- | --- |
+| DEBT-0001 | Open | TBD | Existing platform build files remain alongside new CMake | Required for incremental migration | Existing platform builds plus new CMake configure | Remove after all platform builds consume shared CMake targets |
+| DEBT-0002 | Open | TBD | Vendored SDK and patched libraries retained initially | Some dependencies are SDK-only or have platform-specific binaries | Dependency inventory and platform build smoke tests | Replace or document permanent vendored status after vcpkg triplet evaluation |
+| DEBT-0003 | Open | TBD | Existing singletons remain during initial split | Avoid behavior changes while introducing boundaries | App launch and component tests | Replace singleton reaches with context/service injection at component boundaries |
+
+## Current Capability Map Seed
+
+Use this as the starting checklist for Phase 0 inventory.
+
+- Project I/O: PPI open/save, thumbnails, version metadata, autosave/save-as
+  flows.
+- Image I/O: JPEG/PNG import/export, cube faces, equirectangular export,
+  depth export.
+- Brush system: ABR import, PPBR import/export, presets, tip/pattern/dual brush,
+  pressure, jitter, blend modes.
+- Painting: six cube faces, temporary stroke buffers, erase, flood fill, masks,
+  alpha lock, layer compositing.
+- Layers and animation: layer add/remove/move/merge, blend/opacity/visibility,
+  frame add/remove/duplicate/duration, MP4/timelapse export.
+- UI: XML layout, Yoga layout, panels, dialogs, color tools, brush tools,
+  layers, animation timeline, settings, shortcuts, manual/changelog/about.
+- Input: mouse, keyboard, touch, gestures, Wacom tablet, stylus pressure,
+  VR controllers.
+- Platform services: clipboard, file picker, save picker, directory picker,
+  share/display file, keyboard show/hide.
+- VR/platform variants: OpenVR desktop, Quest, Focus/Wave, Android standard,
+  iOS/macOS, Linux, WebGL.
+- Cloud/network: upload, download, browse, license/check flows.
+- Recording/export: PBO readbacks, MP4 encoder, timelapse frames.