Legacy superbuild assessment

How to assess a legacy superbuild workspace before migration to the modern CMake + Conan workflow. Output of this phase feeds the migration plan and per-project status documents.

Assessment goals

Produce an evidence-based inventory that answers:

• What builds today on Linux via CMake?
• What still depends on manual .vcxproj / .sln on Windows?
• What dependencies are manual paths vs packaged?
• What platform assumptions are embedded in code, CMake, or IDE projects?
• What is the macOS build path today (CMake, Xcode, none)?
• What is the migration order risk (critical path, coupling, generated code)?

Do not start rewriting builds until Phase 0 artifacts exist.

Scope of inventory

Workspace-level

Item	Record
Superbuild root CMakeLists.txt	Location, subprojects registered, ordering
Top-level scripts	build.sh, batch files, CI YAML
Submodule list	src/*, libs/*, other
Existing Conan usage	None / partial / workspace recipe
Existing CMakePresets.json	Present / absent / stale
tools/ai-rules/ submodule	Present / absent / pinned revision
Root AGENTS.md	Present / absent

Per participating repository / project

Create one row per migratable unit (library, executable, plugin, tool). Use templates/project-migration-template.md.

Field	What to capture
Name / path	e.g. src/foo, libs/bar
Linux CMake	Yes / partial / none
Windows .vcxproj / .sln	Primary / secondary / none
CMake quality	Global flags / target-based / mixed
Dependencies	System, vendored libs/, manual LIBRARY_PATH, Conan candidate
Generated sources	Codegen tools, timestamps, custom commands
Platform-specific sources	#ifdef _WIN32, .rc, .def, macOS bundles
Tests	CTest / custom / none
CI coverage	Linux / Windows / macOS / combinations
Owners	Team contact

Per .vcxproj (when Windows IDE is authoritative)

Extract or document equivalents for CMake mapping (see visual-studio-to-cmake-mapping.md):

• ClCompile / ClInclude / None items
• AdditionalIncludeDirectories
• PreprocessorDefinitions
• AdditionalOptions (compiler and linker)
• AdditionalDependencies / AdditionalLibraryDirectories
• SubSystem, EntryPointSymbol, .def files
• CustomBuild / PreBuildEvent / PostBuildEvent
• OutDir, TargetName, TargetExt
• Per-configuration differences (Debug / Release / custom)
• Platform toolset and Windows SDK version

Per legacy CMakeLists.txt (Linux baseline)

Signal	Risk if ignored
include_directories() global	Leaks transitive includes; hard to map per-target
add_definitions() global	Configuration drift vs Windows
link_directories()	Non-portable search paths
file(GLOB ...)	Misses new files; non-deterministic
Hardcoded /usr or C:\ paths	Breaks cross-platform
Missing target_* usage	VS migration cannot attach cleanly

Dependencies and third-party

Category	Examples	Migration note
Conan-ready	boost, openssl, zlib	Phase 4 candidate
Vendored in libs/	patched fork	Keep in tree; CMake target
System packages (Linux)	apt libs	Replace with Conan or document exception
Manual Windows redistributables	.lib in repo tree	Map to target_link_libraries; then Conan
Header-only vendored	include/ tree	INTERFACE target

Platform assumptions in source

Search and catalog:

• Backslash paths in strings or includes
• WIN32 vs _WIN32 inconsistency
• Assumed DLL vs static linking per platform
• Path length / Unicode assumptions
• Shell-only commands in custom steps

Assessment procedure

Step 1: Clone and build as-is

git clone --recursive <superbuild-url>
cd <workspace>
# Record exact commands that work today on Linux
cmake -S . -B build-legacy-linux -DCMAKE_BUILD_TYPE=Debug
cmake --build build-legacy-linux

On Windows (if available), record the current developer path:

• Open .sln / .vcxproj and build Debug|x64
• Note which projects are excluded from Linux CMake

Step 2: Generate inventories

1. Repository manifest — table of all src/ and libs/ entries with build authority column
2. VS project manifest — list every .vcxproj, its configurations, and mapped CMake counterpart (or NONE)
3. Dependency graph — directed edges between projects and external libs
4. Gap list — behaviors in VS not expressible in current Linux CMake

Step 3: Classify migration difficulty

Tier	Criteria	Strategy
A	Linux CMake target-based; no VS-only projects	Normalize + presets + Conan deps
B	Linux CMake with globals; parallel .vcxproj	Refactor CMake, then VS parity pass
C	VS-primary; weak or missing Linux CMake	VS intent extraction → new CMake
D	Heavy codegen, custom commands, post-build	Dedicated sub-phase; parity tests early

Step 4: Propose migration order

Order by:

1. Leaf libraries (few dependents)
2. Shared infrastructure used by many targets
3. Applications and integration targets last

Avoid migrating the highest coupling node first unless it unlocks others.

Step 5: Record baseline artifacts

Store under consumer-controlled docs (not in tools/ai-rules/):

<consumer>/docs/migration/
├── inventory.md
├── dependency-graph.md
├── projects/
│   └── <name>.md   # from project-migration-template
└── baselines/
    ├── linux-build-log.txt
    └── windows-build-notes.md

Shared policy for how to assess lives here in superbuild-workflow. Per-workspace inventory data lives in the consuming repo.

Assessment exit criteria (Phase 0 complete)

• Every participating project has a migration tier (A–D)
• Every .vcxproj primary project has an owner and mapping worksheet started
• Linux and Windows build entry points documented with exact commands
• Dependency graph reviewed for Conan candidacy
• Migration order agreed with engineering leads
• No project started Phase 2+ without an inventory row

Related documents

• legacy-superbuild-migration.md — full phased migration
• visual-studio-to-cmake-mapping.md — VS field mapping
• templates/migration-checklist.md — per-project checklist