Cmake Build Project Management

Recovery

If "Compiler not found":

1. Stop.
2. Delete CMakeCache.txt.
3. Re-run using the wrapper above.

2. Configuration Verification

Objective: Prevent vcpkg rebuilds caused by compiler/toolchain hash mismatches.

Mandate: BEFORE any CMake build:

1. Run cmake --version.
2. VERIFY path matches Visual Studio: *Microsoft Visual Studio*Common7*IDE*CommonExtensions*Microsoft*CMake*CMake*bin*.
3. INVALID: C:\Program Files\CMake\bin, C:\Strawberry\....

Remediation: If path is wrong:

1. STOP.
2. WARN USER: "CMake path mismatch. Update PATH to prioritize Visual Studio version."
3. DO NOT PROCEED until fixed.

2.1 vcpkg Repository Pinning

Objective: Prevent ABI hash invalidation that forces full package rebuilds (10+ minutes).

Rules:

1. Pin the vcpkg checkout to the builtin-baseline commit in vcpkg.json. Do NOT let vcpkg sit at an arbitrary HEAD.
2. NEVER git pull vcpkg unless intentionally updating dependencies. A git pull changes port recipe files, which invalidates every cached ABI hash and triggers a full source rebuild.
3. NEVER delete vcpkg_installed/ during clean builds. The build workflow MUST preserve this directory.
4. Keep vcpkg.json minimal — only declare packages verified by #include scan.

Recovery (if ABI cache is invalidated):

• Do NOT interrupt the rebuild. Let it complete to repopulate the binary cache.
• Subsequent builds will restore to ~2ms install time.

2.2 Shared Install Directory

All CMake presets share a single vcpkg_installed directory via VCPKG_INSTALLED_DIR in CMakePresets.json. This prevents multi-GB duplication when switching between debug and release.

3. Static Runtime Mandate

Context: The "StockApp" project and its dependencies (SqlLib, etc.) are strictly standardized on the MSVC Static Runtime (/MT for Release, /MTd for Debug).

Rule:

1. ALWAYS explicitly enforce the use of Static Runtimes for MSVC.
2. NEVER allow the default /MD configuration to persist.
3. VERIFY that CMAKE_MSVC_RUNTIME_LIBRARY is set to MultiThreaded (Release) or MultiThreadedDebug (Debug).

Implementation Pattern: In CMakeLists.txt:

if(MSVC)
    set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
endif()

4. IDE Project Definition Hygiene

Explicit File Inclusion

• Constraint: All source code files (.cpp, .c) AND header files (.h, .hpp) must be explicitly listed in CMakeLists.txt.
• Reasoning: Ensures files are visible in IDE "Solution Explorer", enabling Object Browser, Class View, and Refactoring tools.

Review Protocol

1. Update: Immediately update CMakeLists.txt when adding/removing/renaming files.
2. Verify: Check that the file appears in the IDE project tree.

Globbing vs. Explicit Lists

• Rule: YOU MUST manually maintain the list. Do not rely on file(GLOB ...) unless explicitly authorized, as it hides files from the build system's dependency tracker.