Dependency

Operations to manipule dependencies. They mainly encapsulate the numerous function calls required to import and export dependencies. It requires CMake 3.20 or newer.

Synopsis

dependency(IMPORT <lib-target-name> [...])
dependency(ADD_INCLUDE_DIRECTORIES <lib-target-name> <SET|APPEND> PUBLIC <gen-expr>...)
dependency(SET_IMPORTED_LOCATION <lib-target-name> [CONFIGURATION <config-type>] PUBLIC <gen-expr>...)
dependency(EXPORT <lib-target-name>... <BUILD_TREE|INSTALL_TREE> [APPEND] OUTPUT_FILE <file-name>)

Usage

dependency(IMPORT <lib-target-name> [...])

Import a depedency:

dependency(IMPORT <lib-target-name>
          <STATIC|SHARED>
          [RELEASE_NAME <raw-filename>]
          [DEBUG_NAME <raw-filename>]
          ROOT_DIR <dir-path>
          INCLUDE_DIR <dir-path>)

Create an imported library target named <lib-target-name>, which should represent the base name of the library (without prefix or suffix), by locating its binary files and setting the necessary target properties. This command combines behavior similar to find_library() and add_library(IMPORTED).

The command requires either the STATIC or SHARED keyword to specify the type of library. Only one may be used. At least one of RELEASE_NAME <raw-filename> or DEBUG_NAME <raw-filename> must be provided. Both can be used. These arguments determine which configurations of the library will be available, typically matching values in the CMAKE_CONFIGURATION_TYPES variable.

The value of <raw-filename> should be the core name of the library file, stripped of:

• Any version numbers.

• Platform-specific prefixes (e.g. lib).

• Platform-specific suffixes (e.g. .so, .dll, .dll.a, .a, .lib).

The file will be resolved by scanning recursively all files in the given ROOT_DIR and attempting to match against expected filename patterns constructed using the relevant CMAKE_<CONFIG>_LIBRARY_PREFIX and CMAKE_<CONFIG>_LIBRARY_SUFFIX, accounting for platform conventions and possible version-number noise in filenames. More specifically, it tries to do a matching between the <raw-filename> in format <CMAKE_STATIC_LIBRARY_PREFIX|CMAKE_SHARED_LIBRARY_PREFIX><raw-filename> <verions-numbers><CMAKE_STATIC_LIBRARY_SUFFIX|CMAKE_SHARED_LIBRARY_SUFFIX> and each filename found striped from their numeric and special character version and their suffix and their prefix based on the plateform and the kind of library STATIC or SHARED. See the command module directory(SCAN), that is used internally, for full details.

If more than one file matches or no file is found, an error is raised.

Once located, an imported target is created using add_library(IMPORTED) and appropriate properties for each available configuration (RELEASE and/or DEBUG) are set, including paths to the binary and import libraries (if applicable), as well as the soname.

The INCLUDE_DIR keyword defines a public include directory required by the imported target. This directory populates the target's INTERFACE_INCLUDE_DIRECTORIES property, which specifies the list of directories published as usage requirements to consumers, and which are added to the compiler's header search path when another target links against it. In practice, this ensures that any consumer of the imported library automatically receives the correct include paths needed to compile against its headers.

The following target properties are configured:

INTERFACE_INCLUDE_DIRECTORIES

Set to the directory given by INCLUDE_DIR. This property defines the include directories as a usage requirement to consumers of the imported target, so that it is automatically added to their header search paths when they link against it.

In this context, the value is intended for source-tree usage, meaning that the directory path refers to headers available directly in the project source (rather than in an installed or exported package). See the CMake doc for full details. The value of this property can be overridden using dependency(ADD_INCLUDE_DIRECTORIES).

INTERFACE_INCLUDE_DIRECTORIES_BUILD

Set to an empty value. This is a custom property, not used by CMake natively, intended to track include directories for usage from the build-tree context. Use dependency(ADD_INCLUDE_DIRECTORIES) to populate this property.

INTERFACE_INCLUDE_DIRECTORIES_INSTALL

Set to an empty value. This is a custom property intended for tracking include paths during installation or packaging, for usage from the install-tree context. Use dependency(ADD_INCLUDE_DIRECTORIES) to populate this property.

IMPORTED_LOCATION_<CONFIG>

The full path to the actual library file (e.g. .so, .dll, .a, .lib), set separately for each configuration (RELEASE and/or DEBUG). See the CMake doc for full details.

IMPORTED_LOCATION_BUILD_<CONFIG>

Custom property set to an empty value. Intended for build-tree specific overrides of the library path, for usage from the build-tree context. Use dependency(SET_IMPORTED_LOCATION) to initialize this property.

IMPORTED_LOCATION_INSTALL_<CONFIG>

Custom property set to an empty value. Intended for install-time overrides of the library path, for usage from the install-tree context. Use dependency(SET_IMPORTED_LOCATION) to initialize this property.

IMPORTED_IMPLIB_<CONFIG>

On DLL-based platforms (e.g. Windows), set to the full path of the import library file (e.g. .dll.a, .a, .lib) for the corresponding configuration. For static libraries, this property is set to empty, because an import library is only for a shared library. See the CMake doc for full details.

IMPORTED_SONAME_<CONFIG>

Set to the filename of the resolved library (without path), allowing CMake to handle runtime linking and version resolution. See the CMake doc for full details.

IMPORTED_CONFIGURATIONS

Appended with each configuration for which a library was found and configured (e.g. RELEASE, DEBUG). See the CMake doc for full details.

Example usage:

# Import shared lib
dependency(IMPORT "my_shared_lib"
  SHARED
  RELEASE_NAME "mylib_1.11.0"
  DEBUG_NAME "mylibd_1.11.0"
  ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
  INCLUDE_DIR "${CMAKE_SOURCE_DIR}/include/mylib"
)
# Is more or less equivalent to:
add_library("my_shared_lib" SHARED IMPORTED)
set_target_properties("my_shared_lib" PROPERTIES
  INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_SOURCE_DIR}/include/mylib"
  INTERFACE_INCLUDE_DIRECTORIES_BUILD ""
  INTERFACE_INCLUDE_DIRECTORIES_INSTALL ""
)
find_library(lib NAMES "mylib_1.11.0")
find_library(implib NAMES "mylibd_1.11.0")
cmake_path(GET lib FILENAME lib_name)
set_target_properties("my_shared_lib" PROPERTIES
  IMPORTED_LOCATION_RELEASE "${lib}"
  IMPORTED_LOCATION_BUILD_RELEASE ""
  IMPORTED_LOCATION_INSTALL_RELEASE ""
  IMPORTED_IMPLIB_RELEASE "${implib}"
  IMPORTED_SONAME_RELEASE "${lib_name}"
)
set_property(TARGET "my_shared_lib"
  APPEND PROPERTY IMPORTED_CONFIGURATIONS "${CMAKE_BUILD_TYPE}"
)

# Import static lib
dependency(IMPORT "my_static_lib"
  STATIC
  RELEASE_NAME "mylib_1.11.0"
  DEBUG_NAME "mylibd_1.11.0"
  ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
  INCLUDE_DIR "${CMAKE_SOURCE_DIR}/include/mylib"
)
# Is more or less equivalent to:
add_library("my_shared_lib" SHARED IMPORTED)
set_target_properties("my_shared_lib" PROPERTIES
  INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_SOURCE_DIR}/include/mylib"
  INTERFACE_INCLUDE_DIRECTORIES_BUILD ""
  INTERFACE_INCLUDE_DIRECTORIES_INSTALL ""
)
find_library(lib NAMES "mylib_1.11.0")
find_library(implib NAMES "mylibd_1.11.0")
cmake_path(GET lib FILENAME lib_name)
set_target_properties("my_shared_lib" PROPERTIES
  IMPORTED_LOCATION_RELEASE "${lib}"
  IMPORTED_LOCATION_BUILD_RELEASE ""
  IMPORTED_LOCATION_INSTALL_RELEASE ""
  IMPORTED_IMPLIB_RELEASE "${implib}"
  IMPORTED_SONAME_RELEASE "${lib_name}"
)
set_property(TARGET "my_shared_lib"
  APPEND PROPERTY IMPORTED_CONFIGURATIONS "${CMAKE_BUILD_TYPE}"
)

dependency(ADD_INCLUDE_DIRECTORIES <lib-target-name> <SET|APPEND> PUBLIC <gen-expr>...)

Set or append public include directories required by the imported target <lib-target-name> to expose its headers to consumers. It populates its INTERFACE_INCLUDE_DIRECTORIES property and its derivatives to allow the target to be imported from the three contexts source-tree, build-tree, and install-tree.

The name should represent the base name of the library (without prefix or suffix). This command copies the behavior of target_include_directories() in CMake, but introduces a separation between build-time and install-time contexts for imported dependencies.

This command is intended for targets that have been previously declared using dependency(IMPORT), and is typically used in conjunction with dependency(EXPORT) to complete the definition of an imported target for external reuse. It fills in target properties that are used when generating the export script. Therefore, there is no benefit in calling it if the target is not intended to be exported.

The behavior differs from standard CMake in that it stores build and install include paths separately using generator expressions (see how write build specification with generator expressions).

The PUBLIC keyword indicates that the specified directories apply to the usage requirements of the target (i.e., will be propagated to consumers of the target). The directories following it must use generator expressions like $<BUILD_INTERFACE:...> and $<INSTALL_INTERFACE:...> to distinguish between build and install phases.

The command accepts the following mutually exclusive modifiers:

• SET: Replaces any existing include directories.

• APPEND: Adds to the current list of include directories.

This command internally sets or appends the following CMake properties on the target:

INTERFACE_INCLUDE_DIRECTORIES

This standard CMake target property specifies the public include directories for the imported target. These directories define the usage requirements of the target and are automatically propagated to any consuming target that links against it.

This property is populated from the $<BUILD_INTERFACE:...> portion of the arguments, corresponding to the directories available in the source-tree context. This ensures that when a target consumes the imported library during a build, it automatically receives the correct include paths for compilation.

For more details, see the official CMake documentation.

INTERFACE_INCLUDE_DIRECTORIES_BUILD

A custom property defined by this module to track the include directories used in the build-tree context. It contains the fully expanded list of directories extracted from the $<BUILD_INTERFACE:...> generator expressions. This ensures that when a target consumes the imported library during the build, it correctly receives all necessary include paths even before installation.

INTERFACE_INCLUDE_DIRECTORIES_INSTALL

A custom property defined by this module to track the include directories intended for use in the install-tree context. It contains the fully expanded list of directories extracted from the $<INSTALL_INTERFACE:...> generator expressions. This ensures that after installation, any consumer of the imported library will have the correct include paths set for compilation against the installed headers.

These custom properties (_BUILD and _INSTALL) are not directly used by CMake itself but are later re-injected into export files generated by dependency(EXPORT).

Example usage:

# Import libs
dependency(IMPORT "my_shared_lib"
  SHARED
  RELEASE_NAME "mylib_1.11.0"
  DEBUG_NAME "mylibd_1.11.0"
  ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
  INCLUDE_DIR "${CMAKE_SOURCE_DIR}/include/mylib"
)
dependency(IMPORT "my_static_lib"
  STATIC
  RELEASE_NAME "mylib_1.11.0"
  DEBUG_NAME "mylibd_1.11.0"
  ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
  INCLUDE_DIR "${CMAKE_SOURCE_DIR}/include/mylib"
)

# Set include directories for shared lib
dependency(ADD_INCLUDE_DIRECTORIES "my_shared_lib" SET
  PUBLIC
    "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/include/mylib>"
    "$<INSTALL_INTERFACE:include/mylib>"
)
# Is more or less equivalent to:
target_include_directories(static_mock_lib
  PUBLIC
      "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/include/mylib>"
      "$<INSTALL_INTERFACE:include/mylib>"
)

# Set include directories for static lib
dependency(ADD_INCLUDE_DIRECTORIES "my_static_lib" SET
  PUBLIC
    "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/include/mylib>"
    "$<INSTALL_INTERFACE:include/mylib>"
)
# Is more or less equivalent to:
target_include_directories(static_mock_lib
  PUBLIC
      "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/include/mylib>"
      "$<INSTALL_INTERFACE:include/mylib>"
)

This example sets my_shared_lib and my_static_lib to expose:

• ${CMAKE_SOURCE_DIR}/include/mylib during the build.

• <CMAKE_INSTALL_PREFIX>/include/mylib after installation (where <CMAKE_INSTALL_PREFIX> is resolved when imported via dependency(EXPORT)).

dependency(SET_IMPORTED_LOCATION <lib-target-name> [CONFIGURATION <config-type>] PUBLIC <gen-expr>...)

Set the IMPORTED_LOCATION_<CONFIG> property of the imported target <lib-target-name> using generator expressions to provide the full path to the library file. The name should represent the base name of the library (without prefix or suffix).

This command is intended for targets that have been previously declared using dependency(IMPORT), and is typically used in conjunction with dependency(EXPORT) to complete the definition of an imported target for external reuse. It allows specifying a different location for each build configuration type, or for all configurations if no configuration is specified. It fills in target properties that are used when generating the export script. Therefore, there is no benefit in calling it if the target is not intended to be exported.

If CONFIGURATION is given, the property is only set for that configuration. Otherwise, the property is set for all configurations supported by the target. Configuration types must match one of the values listed in the target's IMPORTED_CONFIGURATIONS property.

The PUBLIC keyword must be followed by one or more generator expressions that define the path to the library file during build and install phases. The paths following it must use generator expressions like $<BUILD_INTERFACE:...> and $<INSTALL_INTERFACE:...> to distinguish between build and install phases. (see how write build specification with generator expressions).

These expressions are evaluated to determine the value of the following CMake properties set by this command:

IMPORTED_LOCATION_<CONFIG>

The full path to the actual library file (e.g. .so, .dll, .a, .lib), set separately for each configuration (RELEASE and/or DEBUG). See the CMake doc for full details. The command directory(FIND_LIB) can be used to find the library file.

IMPORTED_LOCATION_BUILD_<CONFIG>

Custom property set to the full path to the actual library file, set separately for each configuration (RELEASE and/or DEBUG), and for usage from the build-tree context. This property is used by dependency(EXPORT) to complete the definition of an imported target for external reuse.

IMPORTED_LOCATION_INSTALL_<CONFIG>

Custom property set to the full path to the actual library file, set separately for each configuration (RELEASE and/or DEBUG), and for usage from the install-tree context. This property is used by dependency(EXPORT) to complete the definition of an imported target for external reuse.

Example usage:

# Import libs
dependency(IMPORT "my_shared_lib"
  SHARED
  RELEASE_NAME "mylib_1.11.0"
  DEBUG_NAME "mylibd_1.11.0"
  ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
  INCLUDE_DIR "${CMAKE_SOURCE_DIR}/include/mylib"
)
dependency(IMPORT "my_static_lib"
  STATIC
  RELEASE_NAME "mylib_1.11.0"
  DEBUG_NAME "mylibd_1.11.0"
  ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
  INCLUDE_DIR "${CMAKE_SOURCE_DIR}/include/mylib"
)

# Set imported location for shared lib
dependency(SET_IMPORTED_LOCATION "my_shared_lib"
  CONFIGURATION RELEASE
  PUBLIC
    "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/lib/mylib_1.11.0.dll>"
    "$<INSTALL_INTERFACE:lib/mylib_1.11.0.dll>"
)
dependency(SET_IMPORTED_LOCATION "my_shared_lib"
  CONFIGURATION DEBUG
  PUBLIC
    "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/lib/mylibd_1.11.0.dll>"
    "$<INSTALL_INTERFACE:lib/mylibd_1.11.0.dll>"
)

# Set include directories for static lib
dependency(SET_IMPORTED_LOCATION "my_static_lib"
  CONFIGURATION RELEASE
  PUBLIC
    "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/lib/mylib_1.11.0.lib>"
    "$<INSTALL_INTERFACE:lib/mylib_1.11.0.lib>"
)
dependency(SET_IMPORTED_LOCATION "my_static_lib"
  CONFIGURATION DEBUG
  PUBLIC
    "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/lib/mylibd_1.11.0.lib>"
    "$<INSTALL_INTERFACE:lib/mylibd_1.11.0.lib>"
)

dependency(EXPORT <lib-target-name>... <BUILD_TREE|INSTALL_TREE> [APPEND] OUTPUT_FILE <file-name>)

Creates a file <file-name> that may be included by outside projects to import targets in <lib-target-name> list from the current project's build-tree or install-tree. This command is functionally similar to using export(TARGETS) in a BUILD_TREE context and install(EXPORT) in an INSTALL_TREE context, but is designed specifically to export imported targets with dependency(IMPORT) instead of build targets.

The targets in <lib-target-name> list must be previously created imported targets. The names should match exactly the target names used during import.

One of BUILD_TREE or INSTALL_TREE must be specified to indicate the context in which the file is generated:

• When BUILD_TREE is used, the command generates the file in CMAKE_CURRENT_BINARY_DIR/<file-name>, similar to how export(TARGETS) produces a file to be included by other build projects. This file enables other projects to import the specified targets directly from the build-tree . It can be included from a <PackageName>Config.cmake file to provide usage information for downstream projects.

• When INSTALL_TREE is used, the file is generated in CMAKE_CURRENT_BINARY_DIR/cmake/export/<file-name> and an install rule is added to copy the file to CMAKE_INSTALL_PREFIX/cmake/export/ <file-name>. This is similar to combining install(TARGETS) with install(EXPORT), but applies to imported rather than built targets. This makes the export file available post-install and allows downstream projects to include the file from a package configuration file.

Note that no install rules are created for the actual binary files of the imported targets; only the export script OUTPUT_FILE itself is installed.

If the APPEND keyword is specified, the generated code is appended to the existing file instead of overwriting it. This is useful for exporting multiple targets incrementally to a single file.

The generated file defines all necessary target properties so that the imported targets can be used as if they were defined locally. The properties are identical to those set by the dependency(IMPORT) command; see its documentation for additional details.

Example usage:

# Import libs before exporting
dependency(IMPORT "my_shared_lib"
  SHARED
  RELEASE_NAME "mylib_1.11.0"
  DEBUG_NAME "mylibd_1.11.0"
  ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
  INCLUDE_DIR "${CMAKE_SOURCE_DIR}/include/mylib"
)
dependency(ADD_INCLUDE_DIRECTORIES "my_shared_lib" SET
  PUBLIC
    "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/include/mylib>"
    "$<INSTALL_INTERFACE:include/mylib>"
)
dependency(IMPORT "my_static_lib"
  STATIC
  RELEASE_NAME "mylib_1.11.0"
  DEBUG_NAME "mylibd_1.11.0"
  ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
  INCLUDE_DIR "${CMAKE_SOURCE_DIR}/include/mylib"
)
dependency(ADD_INCLUDE_DIRECTORIES "my_static_lib" SET
  PUBLIC
    "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/include/mylib>"
    "$<INSTALL_INTERFACE:include/mylib>"
)

# Export from Build-Tree
dependency(EXPORT "myimportedlib-1" "myimportedlib-2"
  BUILD_TREE
  OUTPUT_FILE "InternalDependencyTargets.cmake"
)
# Is more or less equivalent to:
export(TARGETS "myimportedlib-1" "myimportedlib-2"
  APPEND
  FILE "InternalDependencyTargets.cmake"
)

# Exporting from Install-Tree
set(CMAKE_INSTALL_PREFIX "${CMAKE_CURRENT_BINARY_DIR}/install")
dependency(EXPORT "myimportedlib-1" "myimportedlib-2"
  INSTALL_TREE
  OUTPUT_FILE "InternalDependencyTargets.cmake"
)
# Is more or less equivalent to:
install(TARGETS "myimportedlib-1" "myimportedlib-2"
  EXPORT "LibExport"
)
install(EXPORT "LibExport"
  DESTINATION "cmake/export"
  FILE "InternalDependencyTargets.cmake"
)

The resulting file InternalDependencyTargets.cmake may then be included by a package configuration file <PackageName>Config.cmake.in to be used by configure_package_config_file() command:

include("${CMAKE_CURRENT_LIST_DIR}/InternalDependencyTargets.cmake")