skip to content

In CMake, what must the geom project install so another team can write find_package(geom 2.1) and link geom::geom?

level: middleimportance: should knowfreq 50%

answer

  1. an export set names the targets
  2. a namespace on imported names
  3. Config file plus ConfigVersion file
  4. CMakePackageConfigHelpers

basics

~10 s

Install geom into an export set, install that set with install(EXPORT ... NAMESPACE geom::), and install geomConfig.cmake, which includes the generated targets file, plus geomConfigVersion.cmake from write_basic_package_version_file, all under lib/cmake/geom.

solid answer

~30 s

`find_package(geom 2.1)` in config mode looks for `geomConfig.cmake` (or `geom-config.cmake`) and asks the matching `geomConfigVersion.cmake` whether 2.1 is acceptable. So `geom` installs four things: the library through `install(TARGETS geom EXPORT geomTargets ...)`; the export set through `install(EXPORT geomTargets NAMESPACE geom:: DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/geom)`, which writes `geomTargets.cmake` defining the imported target `geom::geom`; a `geomConfig.cmake` made by `configure_package_config_file` from a template that includes `geomTargets.cmake`; and `geomConfigVersion.cmake` from `write_basic_package_version_file(... COMPATIBILITY SameMajorVersion)`. In a run with geom 2.3.1 installed, `find_package(geom 2.1)` succeeded while requests for 3.0 and 1.0 were rejected. CMake 4.4 added `SamePatchVersion`, `SameFullVersion` and `SemanticVersion` and deprecated `ExactVersion`.

code

cmake · 17 lines
cmake
project(geom VERSION 2.3.1 LANGUAGES CXX)
include(GNUInstallDirs)
include(CMakePackageConfigHelpers)

install(TARGETS geom units EXPORT geomTargets)
install(EXPORT geomTargets NAMESPACE geom::
        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/geom)

configure_package_config_file(cmake/geomConfig.cmake.in
  ${CMAKE_CURRENT_BINARY_DIR}/geomConfig.cmake
  INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/geom)
write_basic_package_version_file(
  ${CMAKE_CURRENT_BINARY_DIR}/geomConfigVersion.cmake
  COMPATIBILITY SameMajorVersion)
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/geomConfig.cmake
              ${CMAKE_CURRENT_BINARY_DIR}/geomConfigVersion.cmake
        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/geom)

go deeper

for a junior

Recall the three generated or written files next to the library: the targets file, the Config file and the ConfigVersion file.

for a middle

Explain export sets, the NAMESPACE, what configure_package_config_file and write_basic_package_version_file produce, and how the compatibility modes accept or reject a request.

for a senior

Package a library so consumers write two lines, keep the export set complete, and choose a compatibility mode that matches the library's actual versioning promise.

for a principal

Treat the package's version compatibility mode as a public promise that release management must honour across every team that pins it.

## What find_package needs to find In **config mode**, `find_package(geom 2.1)` searches its prefixes for a package configuration file named `geomConfig.cmake` or `geom-config.cmake`. Next to it, it loads a version file, `geomConfigVersion.cmake` or `geom-config-version.cmake`, which decides whether the installed version satisfies the request. How CMake searches is covered with package discovery; this answer covers what the library must install so that search succeeds. | Installed file | Produced by | Role | |---|---|---| | `libgeom.a` | `install(TARGETS geom EXPORT geomTargets ...)` | the library itself | | `geomTargets.cmake` (+ `geomTargets-release.cmake`) | `install(EXPORT geomTargets ...)` | defines the imported target `geom::geom` and its usage requirements | | `geomConfig.cmake` | `configure_package_config_file()` | entry point: finds dependencies, includes the targets file | | `geomConfigVersion.cmake` | `write_basic_package_version_file()` | answers "is this version compatible?" | ## Export sets and the namespace `install(TARGETS geom EXPORT geomTargets ...)` installs the files and also adds `geom` to an **export set** named `geomTargets`. `install(EXPORT geomTargets NAMESPACE geom:: DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/geom)` then writes CMake code that recreates every target in the set as an **imported target**, with its usage requirements: include directories, compile definitions and link interface. `NAMESPACE geom::` prefixes the names, so consumers link `geom::geom`. A name containing `::` is always treated as a target, so a typo fails at configure time instead of turning into `-lgeom::geom`. Projects usually also declare `add_library(geom::geom ALIAS geom)`, so code that consumes `geom` through `add_subdirectory` or FetchContent uses the same name as package consumers. Every target in an export set's link interface must be exported too. When `geom` is static and links a helper `units` privately, the link interface still needs `units`, and CMake 4.4.4 refuses to generate: `install(EXPORT "geomTargets" ...) includes target "geom" which requires target "units" that is not in any export set.` ## The config file The config file is written by hand as a template and processed by `configure_package_config_file` from the `CMakePackageConfigHelpers` module: ```cmake @PACKAGE_INIT@ include(CMakeFindDependencyMacro) find_dependency(Threads) include("${CMAKE_CURRENT_LIST_DIR}/geomTargets.cmake") check_required_components(geom) ``` `@PACKAGE_INIT@` expands into code that computes the package's prefix from the file's own location and defines the `set_and_check()` and `check_required_components()` helpers. `find_dependency` re-finds packages whose imported targets `geom`'s link interface names, before the targets file refers to them. ## The version file `write_basic_package_version_file(geomConfigVersion.cmake COMPATIBILITY <mode>)` takes the version from `VERSION` or `PROJECT_VERSION`. The modes, as documented in CMake 4.4: - `AnyNewerVersion`: any installed version at least the requested one. - `SameMajorVersion`: same major, at least the requested version; 2.3.1 satisfies 2.1 but not 1.0 or 3.0. - `SameMinorVersion`: same major and minor. - `SamePatchVersion` and `SameFullVersion`, **new in 4.4**: match through the patch component, or through every specified component. - `SemanticVersion`, **new in 4.4**: `SameMajorVersion` above major 0, `SameMinorVersion` at major 0. - `ExactVersion`: **deprecated in 4.4**, same as `SamePatchVersion`. By default the version file also rejects a package built for a different architecture; `ARCH_INDEPENDENT` turns that off for header-only packages. ## What the consumer sees With 2.3.1 installed under `SameMajorVersion`, a run of a consumer gave: 1. `find_package(geom 2.1 REQUIRED)` succeeded and `target_link_libraries(app PRIVATE geom::geom)` built. 2. `find_package(geom 3.0 REQUIRED)` failed with "Could not find a configuration file for package "geom" that is compatible with requested version "3.0"", listing `geomConfig.cmake, version: 2.3.1` as considered but not accepted. 3. A request for 1.0 failed the same way. The consumer side then needs only: ```cmake find_package(geom 2.1 REQUIRED) target_link_libraries(app PRIVATE geom::geom) ``` ## Gaps that break the package - **No version file.** `find_package` documents that a config file without a matching version file is assumed not compatible with *any* requested version, so `find_package(geom 2.1)` fails although `find_package(geom)` works. - **Mismatched destinations.** The config file includes the targets file through `${CMAKE_CURRENT_LIST_DIR}`, so both must be installed into the same directory, and `INSTALL_DESTINATION` must name that directory. - **An incomplete export set.** Every project target in the link interface must be exported, as the `units` error above shows. - **Missing `find_dependency` calls** for imported targets from other packages, which fail only when another team first consumes the package.

  • Why install geomTargets.cmake and a separate geomConfig.cmake instead of naming the export file geomConfig.cmake?
    The generated targets file can only recreate targets. A hand-written config file adds what generation cannot know: `find_dependency` calls for imported dependencies, component checks, helper variables. Keeping them apart lets the template stay small while the targets file is regenerated on every install.
  • Which COMPATIBILITY mode suits a header-only library that promises compatibility within a major version?
    `SameMajorVersion` with `ARCH_INDEPENDENT`. The mode accepts any installed 2.x at or above the requested 2.y; `ARCH_INDEPENDENT` skips the default check that the package was built for the consumer's architecture, which is meaningless when there is no binary.

  • install(TARGETS) alone is enough for find_package to work
  • NAMESPACE renames the library file on disk
  • Without a version file, find_package(geom 2.1) accepts any installed version
  • Private static dependencies never need to be exported
  • ExactVersion is the recommended mode in CMake 4.4

Assumes CMake 4.4: write_basic_package_version_file gained SamePatchVersion, SameFullVersion and SemanticVersion and deprecated ExactVersion in 4.4; older releases offer AnyNewerVersion, SameMajorVersion, SameMinorVersion (3.11+) and ExactVersion.