122 lines
4.8 KiB
Markdown
122 lines
4.8 KiB
Markdown
# AGENTS.md
|
|
|
|
This file is the quick-start map for agents working in this repository. Keep it
|
|
small and point to the live docs instead of duplicating the whole plan.
|
|
|
|
## Current Modernization Goal
|
|
|
|
PanoPainter is being incrementally modernized into independently testable C++23
|
|
components while preserving current behavior. OpenGL remains the working backend
|
|
until the renderer boundary is proven; Vulkan/Metal/WebGPU work waits behind that
|
|
boundary.
|
|
|
|
Read these first:
|
|
|
|
- `docs/modernization/roadmap.md` - live phase roadmap, recent results, and next
|
|
work queue.
|
|
- `docs/modernization/debt.md` - required debt log. Every temporary adapter,
|
|
retained legacy dependency, skipped platform, fallback, or shortcut needs an
|
|
entry with validation and removal conditions.
|
|
- `docs/modernization/capability-map.md` - behavior that must be preserved.
|
|
- `docs/modernization/build-inventory.md` - current build/component inventory.
|
|
- `docs/adr/0001-modernization-boundaries.md` - component boundary decisions.
|
|
|
|
## Working Rules
|
|
|
|
- Work on `codex/modernization-cmake-foundation` unless the user says otherwise.
|
|
- Commit and push each verified successful progress slice.
|
|
- Prefer larger coherent slices over tiny checkpoints, but keep docs/debt updated
|
|
with each slice.
|
|
- Do not revert user changes. Unrelated untracked notes, such as
|
|
`docs/human-review-notes.md`, should be left alone unless explicitly requested.
|
|
- Use CMake as the source of truth. Legacy Visual Studio project files are not the
|
|
modernization path.
|
|
- Use `apply_patch` for manual source/doc edits.
|
|
|
|
## Build And Test
|
|
|
|
Primary Windows configure/build:
|
|
|
|
```powershell
|
|
cmake --preset windows-msvc-default
|
|
cmake --build --preset windows-msvc-default --config Debug --target PanoPainter pano_cli
|
|
```
|
|
|
|
Focused fast validation:
|
|
|
|
```powershell
|
|
ctest --preset desktop-fast --build-config Debug --output-on-failure
|
|
```
|
|
|
|
Useful targeted pattern:
|
|
|
|
```powershell
|
|
ctest --preset desktop-fast --build-config Debug -R "pp_app_core|pano_cli_plan" --output-on-failure
|
|
```
|
|
|
|
If MSVC reports corrupt debug information or stale PDB/object errors, clean the
|
|
generated build tree target before judging source changes:
|
|
|
|
```powershell
|
|
cmake --build --preset windows-msvc-default --config Debug --target clean
|
|
```
|
|
|
|
## Code Navigation
|
|
|
|
Prefer compiler-aware navigation when following C++ symbols across the legacy
|
|
flat source tree and extracted components:
|
|
|
|
```powershell
|
|
python scripts/dev/clangd_nav.py symbols --file src/app_core/brush_ui.h --name execute_brush
|
|
python scripts/dev/clangd_nav.py symbols --file src/app_core/brush_ui.h --name-regex "execute_.*preset"
|
|
python scripts/dev/clangd_nav.py definition --file src/node_panel_brush.cpp --line 511 --column 39
|
|
python scripts/dev/clangd_nav.py references --file src/app_core/brush_ui.h --line 783 --column 45
|
|
```
|
|
|
|
The helper talks to `clangd` using an existing `compile_commands.json`. It
|
|
defaults to `out/build/windows-clangcl-asan` and then `out/build/android-arm64`;
|
|
pass `--compile-commands-dir` or set `PP_CLANGD_COMPILE_COMMANDS_DIR` when using
|
|
another Ninja build tree. Use `--name` and `--max-results` to keep output small.
|
|
Use `--name-regex` for regex filtering against `qualifiedName`; matching is
|
|
case-insensitive by default, and `--no-ignore-case` makes it case-sensitive.
|
|
Treat symbol, hover, declaration, definition, and implementation lookups as the
|
|
reliable path. Reference lookups are riskier because a one-shot clangd process
|
|
may not have a complete project index; the helper refuses reference queries
|
|
unless callers pass `--background-index` for broader best-effort results or
|
|
`--allow-incomplete-references` for explicitly current-translation-unit-only
|
|
results. Do not use incomplete reference output as proof that a symbol has no
|
|
other users.
|
|
|
|
## Current Architecture Direction
|
|
|
|
The desired component split is documented in the roadmap. Current extracted or
|
|
in-progress boundaries include:
|
|
|
|
- `pp_foundation`
|
|
- `pp_assets`
|
|
- `pp_paint`
|
|
- `pp_document`
|
|
- `pp_renderer_api`
|
|
- `pp_renderer_gl`
|
|
- `pp_paint_renderer`
|
|
- `pp_app_core`
|
|
- `pp_panopainter_ui`
|
|
- `pp_platform_*`
|
|
- `panopainter_app`
|
|
|
|
Legacy UI/app code still exists and is being reduced through pure planners,
|
|
service interfaces, CLI automation, and CTest coverage. When moving behavior out
|
|
of a legacy node, preserve current behavior first, add focused tests, document
|
|
remaining shortcuts in `docs/modernization/debt.md`, then wire the live adapter.
|
|
|
|
## Legacy Context
|
|
|
|
PanoPainter started as a flat C++17 OpenGL panoramic painting app centered on
|
|
singletons such as `App::I`, `Canvas::I`, `Settings`, and `WacomTablet::I`.
|
|
Rendering uses GLAD/OpenGL and shaders in `data/shaders/`. UI is XML/Yoga based
|
|
with many `Node*` subclasses. Project files are PPI, brush packages are PPBR,
|
|
and Photoshop brushes import through ABR support.
|
|
|
|
Exceptions are disabled in app code. Public modernization APIs should return
|
|
explicit status/result objects.
|