cmake-dependency-triage

Imported from ocx-sh/find_ocx (.claude/skills/cmake-dependency-triage/SKILL.md). Install upstream with npx skills add ocx-sh/find_ocx --skill cmake-dependency-triage. Copyright stays with the author (Apache-2.0).

cmake-dependency-triage

Answer one question with evidence: which copy, which version and which mechanism resolved this dependency, and why not the one you expected. Then hand the fix to the rule that owns it.

It assumes the cmake-build and cpp-packaging rule sets and repeats the MUST rows it leans on at the end. Everything below ran on CMake 3.31.12, 4.3.4 and 4.4.2 against real trees (2026-09-26). The references name each tree and tool.

Contents: Stop condition · The evidence rule · Before you start · The read order · Check the classes · Pick the entry point · T1 to T15 · Pinned defaults · MUST rows this procedure enforces · References

Stop condition

Stop when the triage names all three. Any one missing and it is a guess.

• Which copy. On a --fresh configure, <Pkg>_DIR (or a Find module's library cache line, or the provider that answered) names the copy you intended, and step 4's C3 and C8 reads find no other copy in the artifact.
• Which mechanism put it there. A stale cache entry, a FetchContent or CPM redirect, a provider, a toolchain-injected root, a Find module, a bundled copy, a second lookup, or the manager's resolution. "It found X" is not one.
• The rule that fixes it, and its check passing. Applied at the file and line that decided, never at a layer that did not.

Out of scope, because each turns a diagnosis into a defect: a global floor switch, wiping the tree before step 1, a hand-edited lockfile (CMK-CONAN-09), and cmake_language(DEFER) as an ordering fix (CMK-TC-05).

The evidence rule

Provenance comes only from the configure's own records (class C1): CMakeCache.txt read by grep (never cmake -L, which omits the UNINITIALIZED type of a plain -Ddep_ROOT=...), CMakeFiles/pkgRedirects/, CMakeConfigureLog.yaml events on 4.1 and newer, and --debug-find-pkg=NAME output from a --fresh configure only. Never from the call site, a green configure, a manager's trace (VCPKG_TRACE_FIND_PACKAGE, vcpkg depend-info), conan graph info, or cmake --graphviz. A bundled copy's record is its version macro (T14), and each lookup of a library has its own record (C8).

Before you start

cmake --version

The binary line decides the gate spelling and which floor rule applies. Every configure in this skill passes the gate for its line and, because a fetch may be involved, -DCMAKE_POLICY_DEFAULT_CMP0170=NEW (floor pinned below).

-Werror=author below 4.4 is ignored silently, so one command line serving both sides uses -Werror=dev, which 4.4.2 still honours (CMK-CORE-01).

The read order

Run the four steps in order, on the tree that showed the symptom. build and dep stand for the leg's build directory and the name as the call spells it.

1. Grep the cache, before any flag

NAME=dep
grep -rn --include='CMakeCache.txt' -e "^${NAME}_DIR" -e "^${NAME}_ROOT" -e '^CMAKE_PREFIX_PATH' -e '^VCPKG_INSTALLED_DIR' -e '^CMAKE_TOOLCHAIN_FILE' -e '^CMAKE_PROJECT_TOP_LEVEL_INCLUDES' -e '^CPM_PACKAGE_' -e '^CPM_USE_LOCAL_PACKAGES' -e '^CPM_SOURCE_CACHE' -e '^HUNTER_CACHED_ROOT' build

The patterns are a union, so read each line, and the first row below that matches decides. Empty output means build is not the leg's tree, or no call, hint or manager reached this cache: check both before the last-but-one row. Save the output before step 2, because --fresh deletes the cache it came from. Lines from a second CMakeCache.txt are a nested configure's (C8).

2. Reconfigure fresh, with the search printed

GATE=-Werror=dev
GEN=Ninja
cmake -S . -B build -G "$GEN" --fresh "$GATE" -DCMAKE_POLICY_DEFAULT_CMP0170=NEW --debug-find-pkg="$NAME"

Pass the same -G, -D hints and --toolchain the leg passes. --fresh drops the cached generator, and a superbuild's next build then stops on its inner tree's generator (exit 2 on 3.31.12, 4.3.4 and 4.4.2). A preset leg runs cmake --preset "$PRESET" --fresh "$GATE" -DCMAKE_POLICY_DEFAULT_CMP0170=NEW --debug-find-pkg="$NAME" with its configure preset, so its cache variables and warnings block apply exactly as in CI.

• The file was found at followed by a path names the file that answered. The item was found at is a find_library or find_path answer: for a Find module those lines are the copy, and The file was found at names the module.
• Package was found by the dependency provider means the provider returned, not that it supplied the copy. cmake-conan prints it after its fallback search too, so read the path above it (C1, T13).
• On a reused tree the same flag lists only the cached candidate and prints the old answer with no warning (measured, both lines). That is why it never runs before step 1, and never without --fresh.
• A gated configure that stops at a floor error first is T5 or T6.

Then re-run the step 1 grep beside the saved output (C2), comparing values, not line numbers, which --fresh shifts. A moved dep_DIR is a stale cache, and step 4's C4 question reads one that stayed (T1, CMK-DEP-21).

3. On CMake 4.1 and newer, read the configure log

grep -rc --include='CMakeConfigureLog.yaml' -e 'kind: "find_package-v1"' build
grep -rn --include='CMakeConfigureLog.yaml' -e '^    name: ' -e '^      path: ' -e '^      mode: ' -e '^      version: ' build

Run both only after step 2's --fresh configure, because the log appends on a reused tree. Empty output from the count means no configure log (not applicable), and 0 on 3.x is expected. 0 on 4.1 or newer after a find_package ran is a finding (CMK-DEP-17), but a FetchContent or CPM redirect logs an event only under --debug-find-pkg, with its path: in pkgRedirects and a blank found version: (4.3.4 and 4.4.2). A blank found version: beside any other path means the package ships no version file (json-c 0.17 and 0.18): read its version macro (step 4's C3). The second command pairs each name: with its path:, mode: and version: lines, the request's version first. A found version other than the manager's is the finding. A Find module reports the version it parsed, usually the header's (C8). Empty output means no find_package resolved. On 3.x, read the version file beside step 1's _DIR (references). cmake-conan's events: references.

4. Check the eight classes before you name the copy

Every failure this read order has shown on a real tree is one of eight mechanisms, and so is a symptom no entry row names. Ask each question and follow the first that fails (measured cases).

The C3 reads of the artifact and its source, whatever the entry row:

BIN=build/app
ldd "$BIN"
readelf -d "$BIN"
grep -rho --include='build.ninja' --include='flags.make' -e '-isystem [^ ]*' -e ' -I[^ ]*' build | sort -u
grep -rn --include='*.h' --include='*.hpp' -e 'define FMT_VERSION ' /usr/local/include /opt/spdlog/include
DIR=build/_deps/dep-src
git -C "$DIR" status --porcelain
grep -rn --include='CMakeLists.txt' --include='*.cmake' -e 'PATCH_COMMAND' .
grep -rn --include='CMakeLists.txt' --include='*.cmake' --include='CMakePresets.json' --include='CMakeUserPresets.json' --include='*.yml' --include='*.yaml' --include='*.sh' -e 'FETCHCONTENT_SOURCE_DIR_' .
PKGDIR=/usr/local/lib/cmake/dep
grep -rn --include='*.cmake' -e 'IMPORTED_CONFIGURATIONS' "$PKGDIR"
grep -rn --include='CMakeCache.txt' -e '^CMAKE_BUILD_TYPE' -e '^CMAKE_CONFIGURATION_TYPES' -e '^CMAKE_MAP_IMPORTED_CONFIG_' build

• T11, ldd and readelf -d on the binary and its build-tree twin. The ldd line naming the library is the copy that loads. Another file name of the recorded package (a postfix such as d) is another build of it (the imported configuration). None, or not a dynamic executable, means not applicable. An installed binary with no RUNPATH or RPATH line, whose twin has one, lost it at install, so a same-SONAME copy on the loader's path wins with exit 0. Fix with CMK-INST-11 ($ORIGIN) for the same prefix, INSTALL_RPATH_USE_LINK_PATH ON for another, never LD_LIBRARY_PATH. A RUNPATH naming two directories that both hold the SONAME is C8, not T11.
• T14, the macro grep, over each directory the include grep prints (empty: another generator, so step 1's prefixes). One hit passes, and empty output means a wrong macro or directory. A second hit under the same package's other prefix is a second lookup (C8). One under another package's tree is a bundled copy: consume the package's build that uses the external copy, never an include order (CMK-DEP-33, references).
• T15, git. Set DIR to step 1's _SOURCE_DIR value. Empty output passes, not a git repository means a URL download (not applicable), and a line means another project edited the shared checkout (CMK-DEP-16).
• T7, the last two greps. FETCHCONTENT_SOURCE_DIR_<X> skips the declare's PATCH_COMMAND (3.31.12, 4.3.4 and 4.4.2). Empty first output means no dependency is patched, so the cause is elsewhere in the offline probe (CMK-DEP-16). Empty second output means no override (not applicable). A name in both whose override directory lacks the patched line is the finding (CMK-DEP-31). The probe always carries -DCMAKE_POLICY_DEFAULT_CMP0170=NEW, or a missing source directory exits 0.
• The imported configuration, the last two greps, with PKGDIR from step 1's dep_DIR. Empty first output: not applicable. Empty second output: build is not a configured tree. A leg configuration that no IMPORTED_CONFIGURATIONS line lists and no map line maps links the first listed, DEBUG by file order, with exit 0 and no warning (lz4). Map it in the leg's preset or toolchain, CMAKE_MAP_IMPORTED_CONFIG_RELWITHDEBINFO as RelWithDebInfo;Release as vcpkg's toolchain does, never empty (CMK-INST-22).

The C8 reads, from the artifact's side, with LIB as the library's file name:

LIB=libzstd
grep -rho --include='build.ninja' --include='link.txt' -e "[^ ]*/${LIB}[.][^ ]*" build | sort -u
grep -rn --include='CMakeConfigureLog.yaml' -e "^    found: \"[^\"]*/${LIB}[.]" build
grep -rl --include='CMakeCache.txt' -e '^CMAKE_HOME_DIRECTORY' build

• Link lines. One directory passes. Empty output means a wrong LIB, or a link line naming another build: re-run with the ldd line's file name. Two directories are two lookups on two copies: resolve the library once and link that target everywhere (CMK-DEP-33). The ungated Cannot generate a safe runtime search path warning with cycle is the same finding.
• found: lines (4.1 and newer) are find_library answers, pkg-config's included. A prefix that steps 1 and 3 do not name is a second lookup, and empty output passes.
• Caches. One file passes. More than one is a nested configure: run steps 1 to 3 on the tree that holds the artifact, with the arguments in its <name>-prefix/tmp/<name>-cfgcmd.txt. A list forwarded through CMAKE_ARGS arrives cut to its first entry (CMK-DEP-34, forwarding). Count also under each -B the console names and a manager's root, where HunterGate's bootstrap keeps its cache (C8).

Pick the entry point

T1 and T13 Wrong copy, or a re-pointed hint had no effect

A resolved find_package keeps <Pkg>_DIR in the cache, so re-pointing <Pkg>_ROOT, CMAKE_PREFIX_PATH, VCPKG_INSTALLED_DIR or a Conan output folder keeps the old copy while the hint prints the new value (both lines). Step 4's C4 answer picks the branch:

• Listed, and _DIR moves under --fresh. Stale cache (C2): --fresh or a new tree, and -U <Pkg>_DIR only when the toolchain did not change (CMK-TC-03). A module that writes a _ROOT cache entry on every configure needs CMK-DEP-13's guarded unset(<Pkg>_DIR CACHE) (the module grep).
• Listed, and _DIR stays put under --fresh and starts with a root. CMAKE_FIND_ROOT_PATH or CMAKE_SYSROOT is non-empty (step 2 prints both), and every rooted candidate beats an unrooted _ROOT hint. Pin the copy with <Pkg>_DIR (CMK-DEP-21, and CMK-TC-10 under a Conan cross build).
• T13, considered but not accepted names the generators copy, or both roots are empty while step 1 names cmake-conan. cmake-conan re-runs a failed generators search with CMake's default search, so a request that rejects Conan's copy, or a conanfile without the package, lets another copy win with exit 0 (references). Fix the request or the conanfile, never with a _DIR pin. A leg that must use Conan's copy asserts that step 1 prints no <Pkg>_DIR line for it (CMK-DEP-32).
• Never listed, and _DIR stays put outside every root in a cross build. The target's copy was never a candidate, and the toolchain leaves the find-root modes at BOTH (CMK-TC-08). A sysroot's usr/lib/<triplet> is searched only when CMAKE_LIBRARY_ARCHITECTURE is set, which a compiler with no implicit link directories leaves empty, so the toolchain also sets the triplet (CMK-TC-11, references).

T2 Installed copy ignored, fetched copy built

dep_DIR under CMakeFiles/pkgRedirects means an OVERRIDE_FIND_PACKAGE declare, or a FIND_PACKAGE_ARGS declare that fell through to a fetch, won, and --debug-find-pkg never names the installed prefix (both lines). Name the declaring line with a grep, never a trace:

grep -rn --include='*.cmake' --include='CMakeLists.txt' -e 'OVERRIDE_FIND_PACKAGE' .

Empty output, or a hit only inside CPM.cmake (CPM writes the redirect for every package it fetches: T15), means no override declare. Then a FIND_PACKAGE_ARGS try-find missed on a name spelled unlike the Config file: re-run step 1 with that spelling (C5, references). A hit in an installable library outside a top-level guard is a CMK-DEP-07 finding. A later find_package(dep 2.0 ...) against the redirect passes with a blank version (CMK-DEP-09). A CI leg on the installed copy asserts step 1's path (CMK-DEP-32).

T3 and T10 A provider that never supplies the package

Providers intercept only find_package and FetchContent_MakeAvailable. T3's tell is in the console output, never in CMakeConfigureLog.yaml, and the second grep is T10's:

PRESET=default
mkdir -p logs
cmake --preset "$PRESET" --fresh "$GATE" -DCMAKE_POLICY_DEFAULT_CMP0170=NEW > logs/configure.log 2>&1
grep -rn --include='configure.log' -e 'conan_cmakedeps_paths' logs
grep -rn --include='CMakeLists.txt' --include='*.cmake' -e 'SET_DEPENDENCY_PROVIDER' -e 'CMAKE_PROJECT_TOP_LEVEL_INCLUDES' .

A leg without presets captures the step 2 command the same way. Empty output from the first grep means CMakeDeps, whose content no find_* call sees. A Loading line means CMakeConfigDeps, whose paths exist after the first intercepted find_package, in that directory scope (4.4.2). The fix is CMK-TC-05, and DEFER never helps (references).

T10: step 1 shows the user's file in CMAKE_PROJECT_TOP_LEVEL_INCLUDES, and step 2 never credits the provider. A project set() hides the user's file, and a list(APPEND) registers the project's provider last, which wins. Empty output from the second grep passes, and any project hit is the finding (CMK-TC-04).

T4 Consumer fails after Configuring done

The error names the installed *Targets.cmake: the exporter never redeclared a dependency on its link interface. Only a compiled consumer fails (class C7).

NAME=dep2
PREFIX=/usr/local
grep -rn --include="${NAME}Config.cmake" --include="${NAME}-config.cmake" -e 'find_dependency' "$PREFIX"
grep -rn --include="${NAME}*argets.cmake" -e 'INTERFACE_LINK_LIBRARIES' "$PREFIX"

Empty output from the first while the second names another package's target is the finding (CMK-INST-03). Empty output from the second means no exported target links another package (not applicable). The proof is the CMK-INST-01 round trip with a compiled consumer.

T5, T6 and T12 The gate stops inside a dependency

Each is class C6: the remedy changes the dependency's input, never the gate. T5 is 4.x's "Compatibility with CMake < 3.5 has been removed". T6 is the gate on "< 3.10 will be removed" (CMake Deprecation Error on 3.31.12 and 4.3.4, CMake Error (deprecated) on 4.4.2). Both name the dependency's cmake_minimum_required line, relative to the configure that printed it: if the project's line holds no such call, the tree is the console's reproduce line's -H and -B (C8). On 4.x the fix is CMK-DEP-15, value 3.10 (never 3.5), scoped to the one call that adds the dependency. On 3.x it is CMK-DEP-30, a re-pin or a one-line PATCH_COMMAND, because 3.31.12 ignores CMAKE_POLICY_VERSION_MINIMUM. A child configure (a manager's bootstrap, execute_process of cmake) sees neither the scoped value nor a -D, nor the gate on 3.x: on every line re-pin or patch the file that writes its floor (the third grep, FM, CMK-DEP-06). T12 is 4.4's install-absolute-destination inside a dependency: only one PATCH_COMMAND over every absolute destination clears it on 4.4.2 (FM11). List the floor writes, then the absolute destinations:

grep -rn --include='*.cmake' --include='CMakeLists.txt' --include='CMakePresets.json' --include='*.yml' --include='*.yaml' -e 'CMAKE_POLICY_VERSION_MINIMUM' -e 'CMAKE_POLICY_DEFAULT_CMP' .
grep -rn --include='CMakeLists.txt' --include='*.cmake' -e 'CMAKE_INSTALL_FULL_' build/_deps
grep -rn --include='CMakeLists.txt' --include='*.cmake' -e '"cmake_minimum_required(VERSION' .

Empty first output passes. Each hit must be a set/restore around one call that adds the dependency, a set() inside a function, or a vcpkg port's own arguments, and a preset, workflow or file-scope hit is the finding. Empty second output means a literal absolute path, so read the error's file:line. The third lists floors written into a generated project, and empty output means none (not applicable). The gate never drops (CMK-CORE-01).

T8 and T9 Which version the manager put in this tree

Both are class C1. Conan's graph info (with the build's conan install flags) prints what the conanfile resolves to now. The grep reads the generators folder the tree builds against:

conan graph info . --profile:host=default --profile:build=default
grep -rn --include='*ConfigVersion.cmake' --include='*-config-version.cmake' --include='*-data.cmake' -e 'set(PACKAGE_VERSION ' -e '_PACKAGE_FOLDER_[A-Z]* "' build

Hits under generators are this tree's version and package folder, and empty output means no generators folder (not applicable). Another version than graph info's means conan install did not run after a change (CMK-CONAN-07, CMK-CONAN-09, references). For vcpkg, step 1's lines answer "which tree" (a _DIR outside VCPKG_INSTALLED_DIR is T1), and status answers the version:

grep -rn --include='status' -e '^Package: ' -e '^Version: ' -e '^Status: ' build/vcpkg_installed/vcpkg

Only an install ok installed entry counts, and empty output means no manifest install ran into this tree. A version above a version>= floor is the baseline winning (CMK-VCPKG-02, references).

T15 CPM chose another copy

Step 1's CPM_PACKAGE_<name>_VERSION and _SOURCE_DIR lines are CPM's record. List the declarations, the lock included:

grep -rn --include='CMakeLists.txt' --include='*.cmake' --exclude='CPM.cmake' --exclude='cpm-package-lock.cmake' --exclude-dir='_deps' -e 'CPMUsePackageLock' -e 'CPMDeclarePackage' -e 'CPMAddPackage' .

Empty output means no CPM (not applicable). A CPMDeclarePackage beats every CPMAddPackage of the name with one ungated warning, so a bump goes in the lock (CMK-DEP-10). Step 2's Debug Log at cmake/CPM.cmake is the cached local search: pass -DCPM_USE_LOCAL_PACKAGES=OFF, and a CI leg asserts the copy (CMK-DEP-32). A _SOURCE_DIR under CPM_SOURCE_CACHE gets step 4's git read (CMK-DEP-16, references).

Pinned defaults

Agreed once, never re-litigated during a triage. Every shipped probe's floor is cmake_minimum_required(VERSION 3.25...4.4). The gate and floor value are as in Before you start and T5 and T6, with CMAKE_POLICY_VERSION_MINIMUM 3.5 only inside a vcpkg port build. Conan runs an explicit conan install, then cmake --preset, and the cmake-conan provider is legal within CMK-TC-05's limits, never with DEFER as a fix. One manager of record per configure (CMK-PKG-01, CMK-TC-02).

MUST rows this procedure enforces

Duplicated as a hedge against the scoped rule set not being loaded. The full rows live in the cmake-build and cpp-packaging rule sets, which settle a dispute.

References

Read one level down, on demand.