skip to content

In CMake, why does an exported library wrap its include directory in $<BUILD_INTERFACE> and $<INSTALL_INTERFACE>, and what happens without them?

level: seniorimportance: should knowfreq 50%

answer

  1. two places the headers live
  2. build tree versus install tree
  3. prefixed in the source directory
  4. relative paths stay relocatable

basics

~20 s

The headers live in the source tree while building and under the install prefix afterwards. $<BUILD_INTERFACE:...> applies only inside the build, $<INSTALL_INTERFACE:...> only in the installed export; a plain source path makes install(EXPORT) fail at generate time.

solid answer

~30 s

An include directory in `INTERFACE_INCLUDE_DIRECTORIES` is copied into whatever describes the target to consumers. In-tree consumers need `${CMAKE_CURRENT_SOURCE_DIR}/include`; consumers of the installed package need the install prefix's `include`. `$<BUILD_INTERFACE:...>` keeps its content for targets in the same build and for `export()`, and is empty in an installed export; `$<INSTALL_INTERFACE:...>` is the reverse. Without them CMake refuses to generate: `Target "imgproc" INTERFACE_INCLUDE_DIRECTORIES property contains path: ... which is prefixed in the source directory.` Give `$<INSTALL_INTERFACE:include>` a relative path, which CMake resolves against the package's own location; `$<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include>` generates without complaint but hard-codes `/opt/imgproc/include` into the export.

code

cmake · 9 lines
cmake
include(GNUInstallDirs)
add_library(imgproc STATIC blur.cpp)
target_include_directories(imgproc PUBLIC
  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
  $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)

install(TARGETS imgproc EXPORT imgprocTargets)
install(EXPORT imgprocTargets NAMESPACE imgproc::
        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/imgproc)

go deeper

for a junior

Recall that headers live in one place while building and another after install, and that BUILD_INTERFACE and INSTALL_INTERFACE pick the right one.

for a middle

Explain which export each expression is kept or emptied in, and why the installed path should be relative to the prefix.

for a senior

Recognize the prefixed-in-the-source-directory error and absolute install paths in exports as the two classic packaging bugs, and know file sets as the modern alternative.

for a principal

Make relocatable exports a release requirement for shared libraries, checked by installing to a throwaway prefix in CI and building a consumer against it.

## One target, two audiences A library such as `imgproc` keeps its public headers in `include/imgproc/` of its source tree. Two kinds of consumers need to find them: - **In-tree consumers**: tests and tools in the same build, or another project that adds `imgproc` through `add_subdirectory`. They must look in the source tree. - **Installed-package consumers**: other teams that call `find_package(imgproc)` after it was installed under some prefix. They must look in that prefix's `include/` directory and must never see a path on the machine that built the package. A single plain path cannot serve both. The two **export and install generator expressions** split the value: | Expression | Kept when | Empty when | |---|---|---| | `$<BUILD_INTERFACE:...>` | the target is used in the same build system, or exported with `export()` | written by `install(EXPORT)` | | `$<INSTALL_INTERFACE:...>` | written by `install(EXPORT)` | everywhere else | | `$<BUILD_LOCAL_INTERFACE:...>` (CMake 3.26+) | used in the same build system | exported by either command | ## The canonical form ```cmake include(GNUInstallDirs) target_include_directories(imgproc PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include> $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>) ``` In a CMake 4.4.4 run, the in-tree compile line received `-I<source>/include`, while the generated `imgprocTargets.cmake` contained: ```cmake INTERFACE_INCLUDE_DIRECTORIES "${_IMPORT_PREFIX}/include" ``` `_IMPORT_PREFIX` is computed by that file from its own location when a consumer loads it, which is why the installed package still works after the prefix is copied elsewhere. ## What happens without them 1. **A plain source path.** `target_include_directories(imgproc PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)` works for every in-tree consumer, but the generate step fails as soon as an `install(EXPORT)` includes the target: `Target "imgproc" INTERFACE_INCLUDE_DIRECTORIES property contains path: "<source>/include" which is prefixed in the source directory.` CMake refuses to publish a path that will not exist on a consumer's machine; a path inside the build directory is rejected the same way. 2. **An absolute install path.** `$<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include>` passes every check and writes `/opt/imgproc/include` into the export. The package then works only where it was installed and breaks when it is unpacked under another prefix. The CMake packaging manual lists exactly this as the non-relocatable form. 3. **Only `$<INSTALL_INTERFACE>`.** In-tree consumers get no include path at all and fail with missing headers. Relative paths inside `$<INSTALL_INTERFACE>` are resolved against the install prefix. When a complex expression needs the prefix explicitly, `$<INSTALL_PREFIX>` is the relocatable placeholder. ## Alternatives that do the wrapping for you - **File sets** (CMake 3.23+): `target_sources(imgproc PUBLIC FILE_SET HEADERS BASE_DIRS include FILES ...)` adds the base directory to the include path wrapped in `$<BUILD_INTERFACE>`, and installing the file set supplies the installed include path. - **`install(TARGETS ... INCLUDES DESTINATION include)`** adds an installed include directory to the exported target; relative paths are taken against `$<INSTALL_PREFIX>`. Both remove most hand-written wrapping, but the rule behind them is the same and comes up whenever a path differs between the build tree and the install tree: link libraries, compile definitions that embed a path, or a data directory. ## Where this sits in the bigger job Writing the `install()` rules, the package config file and the version file is packaging work covered with installing and exporting. The generator expressions answer only one question within it: *which value does each audience see?* A quick check before publishing a library: - grep its `target_*` calls for `CMAKE_CURRENT_SOURCE_DIR`, `CMAKE_SOURCE_DIR` and `CMAKE_BINARY_DIR`; - every hit on a `PUBLIC` or `INTERFACE` item should sit inside `$<BUILD_INTERFACE>`; - every installed counterpart should be a relative path. ## Verifying the exported paths The generated files are plain CMake code, so the check is mechanical: 1. **Configure and generate.** A plain source or build path fails right here, at the generate step, with the "prefixed in the source directory" or "prefixed in the build directory" error. 2. **Read the export.** After `cmake --install`, open `imgprocTargets.cmake` under the installed `cmake/imgproc` directory and look at `INTERFACE_INCLUDE_DIRECTORIES`. A value starting with `${_IMPORT_PREFIX}` is relocatable; a literal absolute path such as `/opt/imgproc/include` is not. 3. **Move the prefix.** Copy the installed tree somewhere else and configure a small consumer that calls `find_package(imgproc)` with `CMAKE_PREFIX_PATH` pointing at the copy. If it compiles against `imgproc/imgproc.hpp`, both expressions did their job. Step 3 also catches paths that do not involve include directories, which is why packaging checklists usually keep it.

  • What is $<BUILD_LOCAL_INTERFACE> for, given that $<BUILD_INTERFACE> exists?
    Added in CMake 3.26, it keeps its content only for consumers in the same build system and is empty for both `export()` and `install(EXPORT)`. Use it for requirements that must never appear in any exported file, such as a link to an internal helper target used only by in-tree consumers.
  • Why does $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include> pass CMake's checks yet still cause trouble?
    The check rejects paths inside the source or build tree, and an absolute install path is neither. It is written verbatim into the export, though, so the package only works at that exact prefix. A relative `$<INSTALL_INTERFACE:include>` is resolved from the package's own location instead.

  • A plain source include path works fine once the library is installed
  • Absolute install paths in INSTALL_INTERFACE keep the package relocatable
  • BUILD_INTERFACE content is written into the installed export file
  • Only INSTALL_INTERFACE is needed if the library is installed