Legacy superbuild migration

Authoritative specification for migrating a legacy C++ superbuild (Linux CMake + manual Windows .vcxproj) to a unified CMake + Conan + CMake Presets workflow governed by tools/ai-rules/ (ai-workflows/superbuild-workflow).

Starting reality

Typical legacy state:

• Superbuild coordinates multiple C++ repositories
• Linux builds via CMake (quality varies)
• Windows development often driven by hand-maintained .vcxproj / .sln
• No unified macOS path
• Inconsistent dependency handling
• No shared AI/workflow submodule

Target end state

• CMake is the sole authoritative build description
• Conan supplies dependencies and toolchain integration (CMakeToolchain, CMakeDeps)
• CMake Presets define configure/build/test on Windows, Linux, macOS
• Visual Studio opens the workspace in native CMake folder mode
• tools/ai-rules/ submodule provides shared workflow policy
• Legacy .vcxproj removed per project once CMake builds are proven locally and in CI on all supported platforms

Confirmed organizational decisions

These decisions apply to consuming superbuild migrations unless a documented exception exists in the consumer's root AGENTS.md:

Decision	Policy
Conan version	Conan 2 only — CMakeToolchain + CMakeDeps integration
Conan recipe location	Single conanfile.py at superbuild root — not per-src/ repo by default
Platform scope	Linux, Windows, and macOS are all in scope for migration and CI
.vcxproj retirement	Remove legacy Visual C++ project files when the CMake migration has a proven working local build and CI build on the supported platforms — no arbitrary waiting period
Windows generators	Ninja + Visual Studio generator both supported — VS generator for multi-config debugging and MSBuild-based installers; Ninja for fast CLI and Linux/macOS parity on Windows

First migration step

Phase 0: Baseline and inventory — before changing build files.

The first concrete action is not "add Conan" or "delete vcxproj". It is:

1. Run legacy-superbuild-assessment.md
2. Produce inventory and migration order
3. Then Phase 1 submodule bootstrap

Skipping inventory causes big-bang risk and duplicated VS/CMake drift.

Central vs local work

Work item	Where
Migration methodology, mapping rules, checklists	tools/ai-rules/ (this repo)
Inventory, parity logs, project status	Consumer docs/migration/
CMake/Conan implementation	Consumer superbuild + src/
Submodule pin, local presets/profiles	Consumer root
Policy fixes discovered during migration	Upstream superbuild-workflow first

Phased migration model

Phase 0: Baseline and inventory

Goal: Evidence-based picture of the workspace.

Activities:

• Inventory all participating repositories under src/ and libs/
• Mark Linux CMake coverage vs Windows .vcxproj authority per project
• Catalog dependencies, includes, definitions, generated files, custom commands, linker settings, post-build steps
• Identify platform-specific assumptions in code and scripts
• Assign migration tier (A–D) and order

Exit: Inventory complete; migration order agreed. See legacy-superbuild-assessment.md.

---

Phase 1: Canonical workflow bootstrap

Goal: Attach shared workflow without yet finishing build unification.

Activities:

• Add tools/ai-rules/ submodule → ai-workflows/superbuild-workflow
• Create consumer root AGENTS.md from template
• Materialize cursor/rules/ → .cursor/rules/; add local overlay if needed
• Document that shared policy is read from submodule first
• Add consumer docs/migration/ directory for local status

Exit: Submodule initialized; team aligned on governance. See superbuild-integration-plan.md.

---

Phase 2: Normalize Linux CMake

Goal: Linux CMake becomes a credible baseline — not automatically "correct", but target-based and refactorable.

Activities:

• Refactor global include_directories, add_definitions, link_directories toward target_* APIs
• Replace file(GLOB) with explicit target_sources where practical
• Clarify target graph (libraries vs executables, PUBLIC/PRIVATE link semantics)
• Align naming with future Windows targets
• Keep Linux building at each step

Exit: Tier A/B projects use target-scoped CMake on Linux.

Principle: Preserve necessary behavior; do not blindly preserve poor structure.

---

Phase 3: Migrate Visual Studio intent into CMake

Goal: Windows behavior driven by CMake; .vcxproj used as reference only.

Activities:

• Extract settings from .vcxproj per visual-studio-to-cmake-mapping.md
• Map sources, includes, definitions, options, libraries, custom commands, generated files, output names
• Handle configuration-specific behavior with generator expressions
• Open workspace in Visual Studio CMake folder mode; build migrated targets
• Run parity validation (legacy MSBuild log vs CMake/VS build)

Exit: Windows builds via CMake for migrated projects; parity sign-off recorded.

FAQ — Reopen Visual Studio when files change? No manual .vcxproj maintenance. Add files to CMakeLists.txt (target_sources); VS CMake integration rescans on configure. Developer may need to reconfigure if CMake lists change — typically automatic on build or via "Generate Cache". Do not re-add files through VS UI into .vcxproj.

FAQ — Add new files how? Edit version control + target_sources in CMake. Commit. Reconfigure if needed. Never add to .vcxproj.

---

Phase 4: Introduce Conan

Goal: Dependency and toolchain bootstrap via Conan — incrementally, after CMake targets exist.

When: After Phase 3 for a given project (or in parallel for Tier A libs), workspace-level Conan lands in Phase 4. Do not require full Conan before first VS→CMake parity.

Activities:

• Add workspace conanfile.py and profiles
• conan install generates CMakeToolchain + CMakeDeps
• Migrate dependencies one-by-one from manual paths to find_package
• Keep libs/ only for documented exceptions

See conan-cmake-rollout.md.

Exit: Core dependencies on Conan for dev and CI; manual paths documented or removed.

---

Phase 5: Presets and unified invocation

Goal: Same logical commands on Linux, Windows, macOS (with documented platform differences).

Activities:

• Check in CMakePresets.json with stable names (dev-debug, ci-release, …)
• Include or extend Conan-generated preset/toolchain fragments
• Document standard configure/build/test in consumer AGENTS.md
• CI uses presets exclusively
• Visual Studio uses CMake presets / folder mode — not standalone .sln workflow

See conan-cmake-rollout.md for single-config vs multi-config.

Exit: Developers and CI use preset-driven workflow on all supported OSes.

---

Phase 6: Validation and deprecation

Goal: Retire legacy paths with evidence.

Activities:

• Compare legacy Linux build vs unified preset build (artifacts, tests)
• Compare legacy .vcxproj MSBuild vs CMake-on-VS for Windows
• Verify macOS preset build locally and in CI
• Remove .vcxproj / .sln from the repo once CMake builds are proven locally and in CI (Linux, Windows, macOS)
• Update project migration status to complete

Exit criteria — migration complete (per project):

Criterion	Required
CMake target-based build on Linux	Yes
CMake target-based build on Windows (VS or CLI)	Yes
CMake target-based build on macOS	Yes
Dependencies via Conan 2 or documented libs/ exception	Yes
CI uses presets + Conan on Linux, Windows, and macOS	Yes
Parity validation signed off (Windows VS reference)	Yes
Proven local + CI CMake builds on all supported platforms	Yes
.vcxproj / .sln removed from repo	Yes
Status doc updated	Yes

Workspace migration complete when all in-scope projects meet the above and no primary build authority remains outside CMake.

---

Migrating one individual project

Use templates/migration-checklist.md and templates/project-migration-template.md.

Typical sequence for project src/foo:

1. Complete assessment row (Phase 0)
2. Normalize Linux CMakeLists.txt (Phase 2)
3. Import VS settings from foo.vcxproj if present (Phase 3)
4. Validate parity on Windows
5. Switch team daily build to CMake-on-VS
6. Migrate foo dependencies to Conan (Phase 4, can overlap)
7. Prove local + CI CMake builds (Linux, Windows, macOS); remove foo.vcxproj (Phase 6)

One project per migration PR series where possible.

Day-to-day development after migration

Onboarding

git clone --recursive <superbuild-url>
cd <workspace>
./tools/setup-dev.sh          # submodules + materialize Cursor rules (consumer script)
conan install . -of build/dev-debug --build=missing -pr:h=conan/profiles/<platform-profile>
cmake --preset dev-debug
cmake --build --preset dev-debug
ctest --preset dev-debug        # if tests defined

Adapt paths to consumer AGENTS.md.

Windows development

Windows supports two CMake generators (see conan-cmake-rollout.md):

Visual Studio generator (default for debugging and installers)

1. conan install with profile matching the VS preset output folder
2. File → Open → Folder on superbuild root (not legacy .sln)
3. Select configure preset (e.g. windows-vs-dev)
4. Use configuration dropdown (Debug / Release) — multi-config
5. Build from VS CMake Targets view or cmake --build build/windows-vs-dev --config Debug
6. Installer/release: cmake --build build/windows-vs-dev --config Release then documented packaging step

Ninja (default for fast CLI)

1. conan install for windows-ninja-debug (or release) output folder
2. cmake --preset windows-ninja-debug
3. cmake --build build/windows-ninja-debug

Use separate build directories. Do not mix generators in one binaryDir.

Adding a source file

1. Add file to Git in correct directory
2. Add to target_sources(<target> PRIVATE new.cpp) in CMakeLists.txt
3. Build — CMake reconfigure runs as needed
4. Do not edit .vcxproj

Cross-platform work

• Linux and macOS: Ninja presets only
• Windows: Ninja + VS generator presets — document both in AGENTS.md
• Use generator expressions for platform-specific sources and flags
• CI: Linux + macOS + Windows (Ninja compile/test recommended; VS generator Release for installer pipeline)

AI agents

Agents read:

1. Consumer AGENTS.md
2. tools/ai-rules/AGENTS.md
3. tools/ai-rules/docs/legacy-superbuild-migration.md (this doc)
4. Project docs/migration/projects/<name>.md

Agents implement CMake changes; do not revive .vcxproj authority.

Governance

• Shared migration policy changes → superbuild-workflow first
• Consumer holds migration status and exceptions only
• Small scoped commits per project/subsystem
• Document decisions in migration status files
• Bump tools/ai-rules when shared policy updates

Related documents

Doc	Role
legacy-superbuild-assessment.md	Phase 0
visual-studio-to-cmake-mapping.md	Phase 3
conan-cmake-rollout.md	Phase 4–5
superbuild-integration-plan.md	Phase 1
cmake-conan-policy.md	Steady-state policy