After an internal CMake package was reinstalled to a new prefix and CMAKE_PREFIX_PATH updated, reconfiguring still uses the old copy; why, and how do you fix it?
answer
- the result is cached
- <Name>_DIR survives reconfigure
- search order only runs when unset
- -U, --fresh, or explicit Ledger_DIR
basics
~20 sConfig mode stored the old directory in the Ledger_DIR cache entry, and find_package reuses a cached directory that still holds a valid config file without searching again. Remove that entry with -U Ledger_DIR or reconfigure with --fresh.
solid answer
~40 sIn config mode `find_package(Ledger)` writes the directory holding `LedgerConfig.cmake` into the cache entry `Ledger_DIR`. On the next configure it looks there first; if the directory still contains a config file of a compatible version, it uses it and never consults `CMAKE_PREFIX_PATH`. Changing the prefix therefore changes nothing while the old install still exists. Fixes: remove the entry (`cmake -U Ledger_DIR`, or delete it in `ccmake`), set `-DLedger_DIR=` to the new directory, or run `cmake --fresh` (since 3.24) to discard the whole cache. When no cache entry exists, the search runs in a documented order: `<Name>_ROOT` variables, then `CMAKE_PREFIX_PATH` from the cache, then environment paths, `HINTS`, `PATH`, the user package registry, system prefixes, the system package registry and finally `PATHS`; the first viable match wins, even if a newer version sits further down.
code
console · 8 lines$ cmake -S proj -B build -DCMAKE_PREFIX_PATH=$PWD/pkgA
-- Ledger_DIR=/work/pkgA/lib/cmake/Ledger
$ cmake -S proj -B build -DCMAKE_PREFIX_PATH=$PWD/pkgB
-- Ledger_DIR=/work/pkgA/lib/cmake/Ledger
$ grep Ledger_DIR build/CMakeCache.txt
Ledger_DIR:PATH=/work/pkgA/lib/cmake/Ledger
$ cmake -S proj -B build -U Ledger_DIR -DCMAKE_PREFIX_PATH=$PWD/pkgB
-- Ledger_DIR=/work/pkgB/lib/cmake/Ledgergo deeper
Remember that CMake keeps a cache between runs, so a value found once can stay even after you change the command line.
Name the Ledger_DIR cache entry config mode creates, and the main search groups: package roots, CMAKE_PREFIX_PATH, environment, system prefixes.
Diagnose the stale directory from the cache, fix it with -U, an explicit Ledger_DIR or --fresh, and use --debug-find-pkg and version requirements so it cannot recur.
Make dependency locations explicit and reproducible, in presets or toolchain files with stated versions, so no developer's machine state decides which library a build links.
## The symptom A team installs version 2 of its internal `Ledger` library to `/opt/ledger-2`, changes the build's `-DCMAKE_PREFIX_PATH=/opt/ledger-1` to `/opt/ledger-2`, and reconfigures the existing build directory. The configure log, or a `message(STATUS "${Ledger_DIR}")`, still shows `/opt/ledger-1/lib/cmake/Ledger`. The new headers are not used and a new function fails to link. ## Why the old copy sticks In **config mode** `find_package` records where it found the package in a **cache entry** named `<PackageName>_DIR`. The cache, `CMakeCache.txt`, persists across configure runs. Reproduced with CMake 4.4: ```console $ cmake -S . -B build -DCMAKE_PREFIX_PATH=$PWD/pkgA -- Ledger_DIR=.../pkgA/lib/cmake/Ledger $ cmake -S . -B build -DCMAKE_PREFIX_PATH=$PWD/pkgB -- Ledger_DIR=.../pkgA/lib/cmake/Ledger $ cmake -S . -B build -U Ledger_DIR -DCMAKE_PREFIX_PATH=$PWD/pkgB -- Ledger_DIR=.../pkgB/lib/cmake/Ledger ``` The rule in the `find_package` documentation is the key: CMake ignores `<PackageName>_DIR` and searches from scratch **only** if that directory no longer contains a config file, or the requested version is incompatible with the one found there. As long as the old install is intact and compatible, the cached directory wins over any change to the search paths. ## The search order when nothing is cached When `<PackageName>_DIR` is unset, CMake builds a list of installation prefixes and checks each in this order: 1. `<PackageName>_ROOT` and `<PACKAGENAME>_ROOT`, as CMake variables and then environment variables (with policies `CMP0074` and `CMP0144` set to `NEW`, which a `cmake_minimum_required` of 3.27 or later does); 2. the cache variables `CMAKE_PREFIX_PATH`, `CMAKE_FRAMEWORK_PATH` and `CMAKE_APPBUNDLE_PATH`; 3. the environment variables `<PackageName>_DIR`, `CMAKE_PREFIX_PATH`, `CMAKE_FRAMEWORK_PATH` and `CMAKE_APPBUNDLE_PATH`; 4. the `HINTS` given in the call; 5. the `PATH` environment variable, with a trailing `/bin` or `/sbin` stripped; 6. the user package registry; 7. platform prefixes from `CMAKE_SYSTEM_PREFIX_PATH`, including the install prefix; 8. the system package registry; 9. the `PATHS` given in the call. Under each prefix it tries several sub-directories, such as `lib/cmake/<name>*/` and `share/<name>*/`. **The first viable config file found is used, even if a newer version lives later in the list.** Each `NO_*` option in the call, or a `CMAKE_FIND_USE_*` variable, removes one group. ## Reading the search Two tools show what happened without guessing: - `grep Ledger_DIR build/CMakeCache.txt` shows the cached directory and settles whether the cache, rather than the search, supplied the result; - `cmake --debug-find-pkg=Ledger` (since CMake 3.23) puts the find commands in debug mode for that package and prints each search group and candidate directory, so a surprising winner, such as a copy in `/usr/local`, is visible at once. ## How to fix it | Goal | Command or setting | |---|---| | Re-run the search for one package | `cmake -U Ledger_DIR -S . -B build` | | Point at an exact directory | `-DLedger_DIR=/opt/ledger-2/lib/cmake/Ledger` | | Start the whole configure clean | `cmake --fresh -S . -B build` (since CMake 3.24) | | Make an old copy unacceptable | ask for it: `find_package(Ledger 2.0 REQUIRED)` | Once the entry is gone, `-DLedger_ROOT=/opt/ledger-2` steers the search for this one package ahead of `CMAKE_PREFIX_PATH`; while a valid `Ledger_DIR` is cached, it changes nothing either. The version row is worth adopting even without the bug: when the project states the version it needs, a cached directory that holds version 1 fails the compatibility check, and CMake searches again instead of silently reusing it. ## Related traps - **Find modules** cache their own results (for `FindZLIB`, `ZLIB_INCLUDE_DIR` and `ZLIB_LIBRARY_RELEASE`), so the same stickiness applies there, with different entry names. - A stray old install in `/usr/local` can win over a newer one in a later group, because the order is fixed and first-match. - When debugging, `cmake --debug-find-pkg=Ledger` prints every directory considered for that package. ## What to tell the team Treat a cached package location as state. Use version requirements so the cache cannot hold an incompatible copy, keep `CMAKE_PREFIX_PATH` in presets or the command line rather than in `CMakeLists.txt`, and reach for `--fresh` when switching toolchains or dependency sets wholesale.
- How do you see which directories find_package actually considered?Configure with `cmake --debug-find-pkg=Ledger` (or `--debug-find` for every find call). CMake prints the search groups, each candidate directory and the file it accepted, which shows whether a cached `Ledger_DIR`, a root variable or a system prefix supplied the result.
- Why does adding a version to find_package help with stale results?A cached `Ledger_DIR` is reused only while its version file declares the request compatible. With `find_package(Ledger 2.0 REQUIRED)`, a cached version 1 install fails that check and CMake searches from scratch, so the stale copy cannot be picked up silently.
- Changing CMAKE_PREFIX_PATH always forces find_package to search again
- find_package picks the newest version among all directories it searches
- Deleting the build directory is the only way to clear a found package
- CMAKE_PREFIX_PATH is searched before Ledger_ROOT
- Stale results are only a config-mode problem; Find modules never cache