In CMake, what is the difference between find_package module mode and config mode, and how does it choose between them?
answer
- who writes the script
- Find<Name>.cmake versus <Name>Config.cmake
- basic signature tries module first
- CONFIG, MODULE, PREFER_CONFIG
basics
~20 sModule mode loads a Find<Name>.cmake script written outside the package that searches for its files; config mode loads the <Name>Config.cmake file the package installed. The basic signature tries module mode first, then config mode; CONFIG or MODULE forces one.
solid answer
~40 sIn **module mode** `find_package(ZLIB)` looks for `FindZLIB.cmake` in `CMAKE_MODULE_PATH`, then among the Find modules CMake ships. Such a module is written by someone other than the package, searches heuristically with `find_path` and `find_library`, and can fall out of date. In **config mode** CMake looks for `<Name>Config.cmake` or `<lowercasename>-config.cmake` (and, since CMake 4.3, `.cps` files) that the package installed, plus an optional version file; that file knows the exact layout and usually defines imported targets. The basic signature tries module mode first and falls back to config mode; `CMAKE_FIND_PACKAGE_PREFER_CONFIG` reverses the order. `MODULE` restricts the call to module mode, while `CONFIG`, `NO_MODULE` or any full-signature option such as `NAMES` or `PATHS` restricts it to config mode, which records the directory found in the `<Name>_DIR` cache entry.
go deeper
Recall the two file names, FindFoo.cmake for module mode and FooConfig.cmake or foo-config.cmake for config mode, and that config files come from the package itself.
Explain the order the basic signature uses, what CONFIG, MODULE and CMAKE_FIND_PACKAGE_PREFER_CONFIG change, and why config packages are more reliable than heuristic Find modules.
Diagnose a project-local Find module shadowing a newer upstream config package, and know which CMake releases moved GTest and Boost towards config mode.
Decide when a team should still own Find modules at all, versus requiring every internal library to install a config package so discovery stays exact.
## Two ways to describe a package `find_package(<PackageName>)` does not search for libraries by itself. It finds and runs a **CMake script** that does the describing, and the two modes differ in who wrote that script. | | Module mode | Config mode | |---|---|---| | File loaded | `Find<PackageName>.cmake` | `<PackageName>Config.cmake` or `<lowercasename>-config.cmake` (plus `.cps` since CMake 4.3) | | Written by | CMake, the OS vendor or your project | the package's own build, at install time | | Where it is searched | `CMAKE_MODULE_PATH`, then CMake's own modules | a set of prefixes and sub-paths (the search procedure) | | How it finds files | heuristics: `find_path`, `find_library` | direct knowledge of the installed layout | | Version check | up to the module | an optional `<Name>ConfigVersion.cmake` or `<lowercasename>-config-version.cmake` file | | Cache entry recording the hit | module-specific, such as `ZLIB_INCLUDE_DIR` | `<PackageName>_DIR` | **Module mode** exists because many libraries were never built with CMake and install no CMake files. CMake ships Find modules for common ones (`FindZLIB`, `FindThreads`, `FindOpenSSL`), and a project can add its own directory of `Find*.cmake` files to `CMAKE_MODULE_PATH`. The CMake documentation itself calls these modules heuristic and prone to going out of date, because they are maintained apart from the library they describe. **Config mode** is the preferred form whenever the library provides it. The file is generated by the library's own install step, so it knows exactly where the headers and libraries landed and normally defines namespaced imported targets. ## How one call picks a mode 1. The **basic signature** (`find_package(Name [version] [REQUIRED] [COMPONENTS ...])`) searches module mode first. If no `FindName.cmake` exists, it falls back to config mode. 2. Setting `CMAKE_FIND_PACKAGE_PREFER_CONFIG` to true (since CMake 3.15) reverses the order: config first, module as the fallback. 3. The `MODULE` keyword allows module mode only. 4. `CONFIG`, its synonym `NO_MODULE`, or any option that belongs only to the full signature (`NAMES`, `CONFIGS`, `HINTS`, `PATHS`, `NO_DEFAULT_PATH` and others) restricts the call to config mode. Whatever the mode, `<PackageName>_FOUND` reports the outcome. When neither mode succeeds, the error says both what was missing and how to help, for example: ```plaintext CMake Error at CMakeLists.txt:3 (find_package): By not providing "FindLedger.cmake" in CMAKE_MODULE_PATH this project has asked CMake to find a package configuration file provided by "Ledger", but CMake did not find one. ``` followed by the list of config file names it tried and the advice to add the install prefix to `CMAKE_PREFIX_PATH` or set `Ledger_DIR`. ## Modules that defer to config files The line between the modes keeps moving towards config packages: - Since CMake 3.20 the shipped `FindGTest` module first tries GoogleTest's own `GTestConfig.cmake` and returns that result when it exists, falling back to its heuristic search otherwise. - Policy `CMP0167` (CMake 3.30) removes the `FindBoost` module: with the policy set to `NEW`, `find_package(Boost)` looks for the `BoostConfig.cmake` that upstream Boost has installed since 1.70. - Since CMake 4.3 config mode also finds Common Package Specification (`.cps`) files, which carry version information in the main file. ## Choosing in your own CMakeLists.txt - Use the **basic signature** with just name, version, `REQUIRED` and components unless you have a reason not to; it leaves both modes and dependency providers able to satisfy the call. - Add `CONFIG` when you know the dependency ships a config package and you do not want a stale Find module (your own or a system one) to win. - Write a `Find<Name>.cmake` only for a library that installs no CMake or `.cps` files, and have it create an imported target rather than only variables. - Never ship a Find module for a library that already installs a config file; the two will disagree sooner or later. ## Where the zlib case lands On a machine with zlib in a system location, `find_package(ZLIB REQUIRED)` finds CMake's `FindZLIB.cmake` and uses module mode, printing a line such as `Found ZLIB: .../libz.tbd (found version "1.2.12")`. An internal library from another repository, installed with its own `LedgerConfig.cmake`, is found in config mode, and CMake stores the directory of that file in the `Ledger_DIR` cache entry.
- Your project ships cmake/FindFoo.cmake, and Foo now installs FooConfig.cmake. Which one does find_package(Foo) use?With the basic signature, module mode runs first, so if `cmake/` is on `CMAKE_MODULE_PATH` your `FindFoo.cmake` wins and the upstream config file is ignored. Delete the module, call `find_package(Foo CONFIG)`, or set `CMAKE_FIND_PACKAGE_PREFER_CONFIG` to make the config package take priority.
- What does a config package's version file decide?When the call asks for a version, CMake loads `<Name>ConfigVersion.cmake` (or `<lowercasename>-config-version.cmake`) beside the config file and reads whether it declares the request compatible. An incompatible candidate is skipped and the search continues. A config package with no version file cannot satisfy a versioned request.
- Config mode means CMake reads a CMakeCache-style config of the dependency's build tree
- Find modules are installed by the library itself alongside its headers
- find_package(Foo) always tries config mode before any Find module
- Adding PATHS to the call still lets module mode run first
- Module mode records the found directory in a Foo_DIR cache entry
Assumes CMake 4.4; .cps search arrived in 4.3, FindBoost removal is policy CMP0167 from 3.30, FindGTest's config-first lookup from 3.20.