In CMake, what makes an installed geom package relocatable, so it still works after its install prefix is moved or unpacked elsewhere?
answer
- paths relative to the file itself
- _IMPORT_PREFIX in the targets file
- @PACKAGE_INIT@ and PATH_VARS
- no CMAKE_INSTALL_PREFIX baked in
basics
~20 sEvery path the package publishes must be computed from the package files' own location, never from the build machine's prefix. install(EXPORT) does this for targets; configure_package_config_file with @PACKAGE_INIT@ and PATH_VARS does it for the config file.
solid answer
~40 sA **relocatable** package works wherever its files land: a different `--prefix`, a CPack archive unpacked in a home directory, a CI cache. `install(EXPORT)` is designed for it: the generated `geomTargets.cmake` derives `_IMPORT_PREFIX` by walking up from its own location and writes paths such as `${_IMPORT_PREFIX}/include`, provided the target's installed usage requirements are relative (`$<INSTALL_INTERFACE:include>`, not `${CMAKE_INSTALL_PREFIX}/include`). The hand-written config file is the usual leak: `configure_file` with `@CMAKE_INSTALL_FULL_INCLUDEDIR@` hard-codes the build machine's prefix. `configure_package_config_file` with `@PACKAGE_INIT@` and `PATH_VARS` instead generates `PACKAGE_<var>` paths relative to the installed file. In a run, `geom` installed to one directory, moved to another, and a consumer pointed there with `CMAKE_PREFIX_PATH` still configured, linked `<moved>/lib/libgeom.a` and ran.
code
cmake · 11 lines# geomConfig.cmake.in
@PACKAGE_INIT@
set_and_check(geom_DATA_DIR "@PACKAGE_CMAKE_INSTALL_DATADIR@/geom")
include("${CMAKE_CURRENT_LIST_DIR}/geomTargets.cmake")
check_required_components(geom)
# CMakeLists.txt
configure_package_config_file(cmake/geomConfig.cmake.in
${CMAKE_CURRENT_BINARY_DIR}/geomConfig.cmake
INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/geom
PATH_VARS CMAKE_INSTALL_DATADIR)go deeper
Recall that an installed package should work wherever its files are copied, so it must not contain the build machine's paths.
Explain how the targets file computes _IMPORT_PREFIX and why installed usage requirements must be relative.
Find absolute paths leaking through config templates and dependency paths, use PATH_VARS and set_and_check, and prove relocation by moving the install tree in CI.
Require relocatable packages for anything distributed as binaries, because caches, archives and developer machines will all place them somewhere new.
## What relocatable means A package is **relocatable** when it does not depend on where it was originally installed. That matters more often than it seems: - a library installed with `cmake --install build --prefix <stage>` and then copied into a shared toolchain directory; - a CPack `.tar.gz` or `.zip` that each developer unpacks wherever they like; - a binary cache in CI that restores the install tree under a different path; - a Windows installer where the user picks the destination folder. The CMake packaging manual puts the rule plainly: a relocatable package must not reference absolute paths of files on the machine where the package is built that will not exist on the machines where it may be installed. ## How install(EXPORT) handles targets The generated targets file computes its prefix at load time. From a CMake 4.4.4 install of `geom`: ```cmake get_filename_component(_IMPORT_PREFIX "${CMAKE_CURRENT_LIST_FILE}" PATH) get_filename_component(_IMPORT_PREFIX "${_IMPORT_PREFIX}" PATH) get_filename_component(_IMPORT_PREFIX "${_IMPORT_PREFIX}" PATH) get_filename_component(_IMPORT_PREFIX "${_IMPORT_PREFIX}" PATH) ... INTERFACE_INCLUDE_DIRECTORIES "${_IMPORT_PREFIX}/include" ``` Each line strips one directory from `<prefix>/lib/cmake/geom/geomTargets.cmake`, so `_IMPORT_PREFIX` is wherever the tree now lives. The per-configuration file sets the library location the same way. This works only if what you feed it is relative: | Usage requirement | Result in the export | |---|---| | `$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>` | `${_IMPORT_PREFIX}/include`: relocatable | | `$<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include>` | an absolute path written verbatim: not relocatable | | a path from a dependency, such as an absolute `.so` found with `find_library` | an absolute path on the build machine: not relocatable | The manual advises against putting dependency paths into `INTERFACE_*` properties at all; link the dependency's imported target and let the config file re-find it. ## How configure_package_config_file handles the config file The config file is a template you write, so it is where absolute paths creep in. The `CMakePackageConfigHelpers` documentation shows the classic mistakes, such as `set(FOO_INCLUDE_DIR "@CMAKE_INSTALL_FULL_INCLUDEDIR@")`, which bakes the build-time prefix into the installed file. The relocatable recipe: 1. Put `@PACKAGE_INIT@` on the first line of `geomConfig.cmake.in`. 2. Pass install directories as `PATH_VARS`, for example `PATH_VARS CMAKE_INSTALL_DATADIR`. 3. Refer to them as `@PACKAGE_CMAKE_INSTALL_DATADIR@`, ideally through `set_and_check()`, which fails loudly if the path does not exist. 4. Generate the file with `configure_package_config_file(... INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/geom)` instead of `configure_file`. The helper computes each `PACKAGE_<var>` relative to the installed config file, so it follows the tree when it moves. In the installed `geomConfig.cmake` from the run below, the template line became: ```cmake get_filename_component(PACKAGE_PREFIX_DIR "${CMAKE_CURRENT_LIST_DIR}/../../../" ABSOLUTE) set_and_check(geom_DATA_DIR "${PACKAGE_PREFIX_DIR}/share/geom") ``` Since CMake 3.30, `PACKAGE_PREFIX_DIR` is documented as always defined after `@PACKAGE_INIT@`. ## Proving it A test that catches every leak at once: ```console cmake --install build --prefix /tmp/stage mv /tmp/stage /tmp/moved cmake -S consumer -B consumer/build -DCMAKE_PREFIX_PATH=/tmp/moved cmake --build consumer/build ``` In the run behind this answer, the consumer configured, `geom_DATA_DIR` resolved to `<moved>/share/geom`, the link line used `moved/lib/libgeom.a` and `moved/lib/libunits.a`, and the program printed its result. Any absolute path from the original prefix would have shown up as a missing file or, worse, as a silent use of a stale copy that still existed there. ## A checklist before publishing 1. Every `INTERFACE_*` path in an exported target is relative, or wrapped so the installed form is relative. 2. The config template uses `@PACKAGE_INIT@`, `PATH_VARS` and `set_and_check()`, and never `CMAKE_INSTALL_PREFIX` or a `CMAKE_INSTALL_FULL_*` variable. 3. Dependencies are linked as imported targets and re-found with `find_dependency`, so no dependency's absolute path is copied into the export. 4. All `install()` destinations are relative to the prefix. 5. CI installs to one prefix, moves the tree, and builds a consumer against the moved copy. ## Related concerns - **Shared libraries** also need a run-time search path that does not point at the build machine; that belongs to RPATH settings and the linker material. - **`DESTDIR`** staging on UNIX prepends a directory at install time without changing the prefix, which is a different mechanism from moving a finished tree. - **CPack** archives inherit relocatability from the install rules, which is one more reason their destinations must be relative.
- Why is set(geom_INCLUDE_DIR "@CMAKE_INSTALL_FULL_INCLUDEDIR@") in a config template a relocation bug?`CMAKE_INSTALL_FULL_INCLUDEDIR` is the absolute path computed from the build-time `CMAKE_INSTALL_PREFIX`, and `configure_file` writes it verbatim. After the tree moves, or after `cmake --install --prefix` installs elsewhere, the variable still points at the original location. Use `PATH_VARS` and `@PACKAGE_CMAKE_INSTALL_INCLUDEDIR@` instead.
- Does cmake --install --prefix fix a config file that hard-codes the prefix?No. `--prefix` changes where files are copied, but the config file was generated at configure time with whatever absolute path it embedded. Only paths computed at load time, like `_IMPORT_PREFIX` and the `PACKAGE_<var>` helpers, follow the files.
- Absolute paths are safer because they cannot be misresolved
- cmake --install --prefix rewrites paths inside the installed config file
- configure_file and configure_package_config_file produce the same result
- Relocatability only matters for Windows installers