Dependency

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

Synopsis

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

Usage

dependency(BUILD <target-name> [...])

Build a dependency from source:

dependency(BUILD <target-name>
           TYPE <STATIC|SHARED|HEADER|EXEC>
           [COMPILE_FEATURES <feature>...]
           [COMPILE_DEFINITIONS <definition>...]
           [COMPILE_OPTIONS <option>...]
           [LINK_OPTIONS <option>...]
           DEP_DIR <dir-path>
           SOURCE_FILES [<*>|<file-path>...]
           HEADER_FILES [<*>|<file-path>...]
           [INCLUDE_DIRS <dir-path>...|<gen-expr>...]
           [LINK_LIBRARIES <target-name>...|<gen-expr>...]
           [DEPENDENCIES <target-dependency-name>...]
           [EXPORT_HEADERS <*>|<file-path>...]
           [EXPORT_EXTRA_SOURCES <*>|<file-path>...])

Creates the binary target <target-name> of type STATIC, SHARED, HEADER, or EXEC. The target is generated from the files listed under SOURCE_FILES and HEADER_FILES located inside the directory specified by DEP_DIR. All file and directory paths must be relative to this dependency root directory.

The options are:

<target-name>: (required)

The unique name of the build target.

TYPE <STATIC|SHARED|HEADER|EXEC>: (required)

The actual target type to build. The valid values are: STATIC, SHARED, HEADER, and EXEC.

COMPILE_FEATURES <feature>...: (optional)

A list of compile features to pass to the target. Example: ["cxx_std_20", "cxx_thread_local", "cxx_trailing_return_types"].

COMPILE_DEFINITIONS <definition>...: (optional)

A list of preprocessor definitions applied when compiling the target. Example: ["DEFINE_ONE=1", "DEFINE_TWO=2", "OPTION_1"].

COMPILE_OPTIONS <option>...: (optional)

A list of compiler options to pass when building the target. Example: ["-Wall", "-Wextra", "/W4"].

LINK_OPTIONS <option>...: (optional)

A list of linker options to pass when building the target. Example: ["-s", "-z", "/INCREMENTAL:NO"].

DEP_DIR <dir-path>: (required)

The path to the directory containing all dependency files. Any relative path is treated as relative to the current source directory (i.e. CMAKE_CURRENT_SOURCE_DIR). This path will be used as base directory for all other paths of this command.

SOURCE_FILES <*>|<file-path>...: (required)

The list of source files (e.g., .cpp, .c) to use when building the target. All paths must be relative to the dependency root directory DEP_DIR. The list can be empty, especially for header-only dependencies. A wildcard * may be used to automatically collect all .cpp, .cc, or .cxx files recursively from DEP_DIR.

HEADER_FILES <*>|<file-path>...: (required)

The list of header files (e.g., .h) to use when building the target. All paths must be relative to the dependency root directory DEP_DIR. The list can be empty, especially for header-only dependencies. A wildcard * may be used to automatically collect all .h, .hpp, .hxx, .inl, or .tpp files recursively from DEP_DIR.

INCLUDE_DIRS <dir-path>...|<gen-expr>...: (optional)

Include directories added to the target with PRIVATE visibility. Paths must be relative to DEP_DIR. Generator expressions may be used with the syntax $<...>.

LINK_LIBRARIES <target-name>...|<gen-expr>...: (optional)

The list of libraries that the target should be linked with. They can be target names or generator expressions with the syntax $<...>.

DEPENDENCIES <target-dependency-name>...: (optional)

The list of targets on which <target-name> depends on and that must be built before.

EXPORT_HEADERS <*>|<file-path>...: (optional)

The set of header files copied at install time from the source-tree to the install-tree. These headers become available for inclusion to the source files in all targets that transitively depend on it. If * is used, files with the extensions .h, .hpp, .hxx, .inl, or .tpp are collected recursively from the directories listed in INCLUDE_DIRS when present, otherwise from DEP_DIR.

During installation, the directory structure is copied verbatim to the standards-conforming location: <CMAKE_INSTALL_PREFIX>/<CMAKE_INSTALL_INCLUDEDIR>/<PROJECT_NAME>/lib/<DEP_DIR_NAME>

EXPORT_EXTRA_SOURCES <*>|<file-path>...: (optional)

The set of additional source files copied at install time from the source -tree to the install-tree. These files become available for inclusion to the source files in all targets that transitively depend on it. If * is used, files are collected recursively from the directories listed in INCLUDE_DIRS when present, otherwise from DEP_DIR. When both EXPORT_HEADERS and EXPORT_EXTRA_SOURCES are used, any duplicated paths found in EXPORT_EXTRA_SOURCES are removed.

During installation, the directory structure is copied verbatim to the standards-conforming location: <CMAKE_INSTALL_PREFIX>/<CMAKE_INSTALL_INCLUDEDIR>/<PROJECT_NAME>/lib/<DEP_DIR_NAME>

Example usage:

# Build a shared lib dependency
dependency(BUILD "my_shared_lib"
  TYPE SHARED
  COMPILE_FEATURES "cxx_std_20" "cxx_thread_local" "cxx_trailing_return_types"
  COMPILE_DEFINITIONS "DEFINE_ONE=1" "DEFINE_TWO=2" "OPTION_1"
  COMPILE_OPTIONS "-Wall" "-Wextra"
  LINK_OPTIONS "-s" "-z"
  DEP_DIR "lib/my_shared_lib"
  SOURCE_FILES "src/main.cpp" "src/util.cpp" "src/source_1.cpp"
  HEADER_FILES "src/util.h" "src/source_1.h" "include/lib_1.h" "include/lib_2.h"
  INCLUDE_DIRS "include"
  LINK_LIBRARIES "dep_1" "dep_2"
  DEPENDENCIES "dep_3"
  EXPORT_HEADERS "*"
  EXPORT_EXTRA_SOURCES "my_shared_lib.cpp")
dependency(IMPORT <lib-target-name> [...])

Import a depedency:

dependency(IMPORT <lib-target-name>
           TYPE <STATIC|SHARED>
           FIND_ROOT_DIR <dir-path>
           [FIND_RELEASE_FILE <lib-file-basename>]
           [FIND_DEBUG_FILE <lib-file-basename>])

Create an imported library target named <PROJECT_NAME>_<lib-target-name> by locating its binary files in FIND_ROOT_DIR for RELEASE and/or DEBUG configurations, and set the necessary target properties. Note that the logical name of the target <target-name> is prefixed with <PROJECT_NAME>_ in order to follow best practices. That is also why an aliased target is created with the name <PROJECT_NAME>::<lib-target-name>.

This command combines calls to directory(FIND_LIB), add_library(IMPORTED) and set_target_properties(). Its main purpose is to manually import a target from a package that does not provide a generated import script for the build-tree (with export(TARGETS)) or the install-tree (with install(EXPORT)).

The command requires a TYPE value to specify the type of library ( STATIC or SHARED). At least one of FIND_RELEASE_FILE <lib-file-basename> or FIND_DEBUG_FILE <lib-file-basename> 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 <lib-file-basename> should have no extension or prefixes; it should be the core name of the library file, stripped of:

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

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

The file will be resolved by scanning recursively all files in the given FIND_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 <lib-file-basename> in format <CMAKE_STATIC_LIBRARY_PREFIX|CMAKE_SHARED_LIBRARY_PREFIX><lib-file-basename> <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(FIND_LIB), that is used internally, for full details.

An error is raised if more than one file matches or no file is found.

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 following target properties are configured:

INTERFACE_INCLUDE_DIRECTORIES

Set to an empty value. 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. Use dependency(ADD_INCLUDE_DIRECTORIES) to populate this property.

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.

To provide maximum flexibility when importing a library with this command, it mirrors CMake's official requirements for FindXxx.cmake modules by initializing the requires standard variables. It also supports use in multiples Build Configurations contexts by replicating the behavior of the SelectLibraryConfigurations module.

This command then returns the following result variables, where <lib-target-fullname> is set to <PROJECT_NAME>_<lib-target-name>:

<lib-target-fullname>_LIBRARY_RELEASE

The full absolute path to the Release build of the library. If no file found, its value is set to <lib-target-fullname>_LIBRARY_RELEASE-NOTFOUND. The variable is undefined when the FIND_RELEASE_FILE argument is not provided.

<lib-target-fullname>_LIBRARY_DEBUG

The full absolute path to the Debug build of the library. If no file found, its value is set to <lib-target-fullname>_LIBRARY_DEBUG-NOTFOUND. The variable is undefined when the FIND_DEBUG_FILE argument is not provided.

<lib-target-fullname>_IMP_LIBRARY_RELEASE

The full absolute path to the Release import build of the library. If no file found, its value is set to <lib-target-fullname>_IMP_LIBRARY_RELEASE-NOTFOUND. The variable is undefined when the FIND_RELEASE_FILE argument is not provided.

<lib-target-fullname>_IMP_LIBRARY_DEBUG

The full absolute path to the Debug import build of the library. If no file found, its value is set to <lib-target-fullname>_IMP_LIBRARY_DEBUG-NOTFOUND. The variable is undefined when the FIND_DEBUG_FILE argument is not provided.

<lib-target-fullname>_FOUND_RELEASE

Set to true if the Release library and import library has been found successfully, otherwise set to false. To be true, both <lib-target-fullname>_LIBRARY_RELEASE and <lib-target-fullname>_IMP_LIBRARY_RELEASE must not be set to -NOTFOUND. The variable is undefined when the FIND_RELEASE_FILE argument is not provided.

<lib-target-fullname>_FOUND_DEBUG

Set to true if the Debug library and import library has been found successfully, otherwise set to false. To be true, both <lib-target-fullname>_LIBRARY_DEBUG and <lib-target-fullname>_IMP_LIBRARY_DEBUG must not be set to -NOTFOUND. The variable is undefined when the FIND_DEBUG_FILE argument is not provided.

<lib-target-fullname>_FOUND

Set to false if <lib-target-fullname>_FOUND_RELEASE or <lib-target-fullname>_FOUND_DEBUG are defined and set to false. Otherwise, set to true.

<lib-target-fullname>_LIBRARY

The value of <lib-target-fullname>_LIBRARY_RELEASE variable if found, otherwise it is set to the value of <lib-target-fullname>_LIBRARY_DEBUG variable if found. If both are found, the release library value takes precedence. If both are not found, because <lib-target-fullname>_FOUND_RELEASE and <lib-target-fullname>_FOUND_DEBUG are set to false, it is set to value <lib-target-fullname>_LIBRARY-NOTFOUND.

If the CMake Generator in use supports build configurations, then this variable will be a list of found libraries each prepended with the optimized or debug keywords specifying which library should be linked for the given configuration. These keywords are used by the target_link_libraries() command. If a build configuration has not been set or the generator in use does not support build configurations, then this variable value will not contain these keywords.

<lib-target-fullname>_LIBRARIES

The same value as the <lib-target-fullname>_LIBRARY variable.

<lib-target-fullname>_ROOT_DIR

The base directory absolute path where to look for the <lib-target-fullname> files. The value is set to the FIND_ROOT_DIR argument.

No library is added if <lib-target-fullname>_FOUND is set to false.

Example usage:

# Import shared lib
dependency(IMPORT "my_shared_lib"
  TYPE SHARED
  FIND_ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
  FIND_RELEASE_FILE "mylib_1.11.0"
  FIND_DEBUG_FILE "mylibd_1.11.0"
)
# Is equivalent to:
add_library("my_shared_lib" SHARED IMPORTED)
set_target_properties("my_shared_lib" PROPERTIES
  INTERFACE_INCLUDE_DIRECTORIES ""
  INTERFACE_INCLUDE_DIRECTORIES_BUILD ""
  INTERFACE_INCLUDE_DIRECTORIES_INSTALL ""
)
directory(FIND_LIB lib
  FIND_IMPLIB implib
  NAME "mylib_1.11.0"
  SHARED
  RELATIVE false
  ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
)
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 "RELEASE"
)
directory(FIND_LIB lib
  FIND_IMPLIB implib
  NAME "mylibd_1.11.0"
  SHARED
  RELATIVE false
  ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
)
cmake_path(GET lib FILENAME lib_name)
set_target_properties("my_shared_lib" PROPERTIES
  IMPORTED_LOCATION_DEBUG "${lib}"
  IMPORTED_LOCATION_BUILD_DEBUG ""
  IMPORTED_LOCATION_INSTALL_DEBUG ""
  IMPORTED_IMPLIB_DEBUG "${implib}"
  IMPORTED_SONAME_DEBUG "${lib_name}"
)
set_property(TARGET "my_shared_lib"
  APPEND PROPERTY IMPORTED_CONFIGURATIONS "DEBUG"
)

# Import static lib
dependency(IMPORT "my_static_lib"
  TYPE STATIC
  FIND_ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
  FIND_RELEASE_FILE "mylib_1.11.0"
  FIND_DEBUG_FILE "mylibd_1.11.0"
)
# Is equivalent to:
add_library("my_static_lib" SHARED IMPORTED)
set_target_properties("my_static_lib" PROPERTIES
  INTERFACE_INCLUDE_DIRECTORIES ""
  INTERFACE_INCLUDE_DIRECTORIES_BUILD ""
  INTERFACE_INCLUDE_DIRECTORIES_INSTALL ""
)
directory(FIND_LIB lib
  FIND_IMPLIB implib
  NAME "mylib_1.11.0"
  SHARED
  RELATIVE false
  ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
)
cmake_path(GET lib FILENAME lib_name)
set_target_properties("my_static_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_static_lib"
  APPEND PROPERTY IMPORTED_CONFIGURATIONS "RELEASE"
)
directory(FIND_LIB lib
  FIND_IMPLIB implib
  NAME "mylibd_1.11.0"
  SHARED
  RELATIVE false
  ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
)
cmake_path(GET lib FILENAME lib_name)
set_target_properties("my_static_lib" PROPERTIES
  IMPORTED_LOCATION_DEBUG "${lib}"
  IMPORTED_LOCATION_BUILD_DEBUG ""
  IMPORTED_LOCATION_INSTALL_DEBUG ""
  IMPORTED_IMPLIB_DEBUG "${implib}"
  IMPORTED_SONAME_DEBUG "${lib_name}"
)
set_property(TARGET "my_static_lib"
  APPEND PROPERTY IMPORTED_CONFIGURATIONS "DEBUG"
)
dependency(ADD_INCLUDE_DIRECTORIES <lib-target-name> <SET|APPEND> INTERFACE <gen-expr>...)

Set or append interface include directories required by the imported target <lib-target-name> to expose its headers to consumers. It 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.

This command populate the target's 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.

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 to write build specification with generator expressions).

The INTERFACE visibility keyword indicates how the specified directories apply to the usage requirements of the target: they will not be used by the imported target but propagated to its consumers. 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.

See the CMake doc for full details.

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).

To provide maximum flexibility when manaing a library with this module, this command mirrors CMake's official requirements for FindXxx.cmake modules by initializing a part of some requires standard variables.

This command then returns the following result variables:

<lib-target-name>_INCLUDE_DIR

The base directory absolute path where to find headers for using the library (or more accurately, the path that consumers of the library should add to their header search path).

<lib-target-name>_INCLUDE_DIRS

The final set of include directories listed in one variable for use by client code.

Note

The dependency(ADD_INCLUDE_DIRECTORIES) command should be called after importing the target with dependency(IMPORT) to ensure that the target properties and result variables are set correctly.

Example usage:

# Import libs
dependency(IMPORT "my_shared_lib"
  TYPE SHARED
  FIND_ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
  FIND_RELEASE_FILE "mylib_1.11.0"
  FIND_DEBUG_FILE "mylibd_1.11.0"
)
dependency(IMPORT "my_static_lib"
  TYPE STATIC
  FIND_ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
  FIND_RELEASE_FILE "mylib_1.11.0"
  FIND_DEBUG_FILE "mylibd_1.11.0"
)

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

# Set include directories for static lib
dependency(ADD_INCLUDE_DIRECTORIES "<PROJECT_NAME>_my_static_lib" SET
  INTERFACE
    "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/include/mylib>"
    "$<INSTALL_INTERFACE:include/mylib>"
)
# Is more or less equivalent to:
target_include_directories(my_static_lib
  INTERFACE
      "$<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>] INTERFACE <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 (DEBUG, RELEASE, etc.), 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 INTERFACE 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.

Note

The dependency(SET_IMPORTED_LOCATION) command should be called after importing the target with dependency(IMPORT) to ensure that the target properties and result variables are set correctly.

Example usage:

# Import libs
dependency(IMPORT "my_shared_lib"
  TYPE SHARED
  FIND_ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
  FIND_RELEASE_FILE "mylib_1.11.0"
  FIND_DEBUG_FILE "mylibd_1.11.0"
)
dependency(IMPORT "my_static_lib"
  TYPE STATIC
  FIND_ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
  FIND_RELEASE_FILE "mylib_1.11.0"
  FIND_DEBUG_FILE "mylibd_1.11.0"
)

# Set imported location for shared lib
dependency(SET_IMPORTED_LOCATION "<PROJECT_NAME>_my_shared_lib"
  CONFIGURATION RELEASE
  INTERFACE
    "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/lib/mylib_1.11.0.dll>"
    "$<INSTALL_INTERFACE:lib/mylib_1.11.0.dll>"
)
dependency(SET_IMPORTED_LOCATION "<PROJECT_NAME>_my_shared_lib"
  CONFIGURATION DEBUG
  INTERFACE
    "$<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 "<PROJECT_NAME>_my_static_lib"
  CONFIGURATION RELEASE
  INTERFACE
    "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/lib/mylib_1.11.0.lib>"
    "$<INSTALL_INTERFACE:lib/mylib_1.11.0.lib>"
)
dependency(SET_IMPORTED_LOCATION "<PROJECT_NAME>_my_static_lib"
  CONFIGURATION DEBUG
  INTERFACE
    "$<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_NAME <file-name>)

Creates a file <file-name> in CMAKE_CURRENT_BINARY_DIR 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_NAME 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.

Note

The dependency(EXPORT) command should be called after importing the target with dependency(IMPORT) to ensure that the target properties and result variables are set correctly.

Example usage:

# Import libs before exporting
dependency(IMPORT "my_shared_lib"
  TYPE SHARED
  FIND_ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
  FIND_RELEASE_FILE "mylib_1.11.0"
  FIND_DEBUG_FILE "mylibd_1.11.0"
)
dependency(ADD_INCLUDE_DIRECTORIES "<PROJECT_NAME>_my_shared_lib" SET
  INTERFACE
    "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/include/mylib>"
    "$<INSTALL_INTERFACE:include/mylib>"
)
dependency(IMPORT "my_static_lib"
  TYPE STATIC
  FIND_ROOT_DIR "${CMAKE_SOURCE_DIR}/lib"
  FIND_RELEASE_FILE "mylib_1.11.0"
  FIND_DEBUG_FILE "mylibd_1.11.0"
)
dependency(ADD_INCLUDE_DIRECTORIES "<PROJECT_NAME>_my_static_lib" SET
  INTERFACE
    "$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}/include/mylib>"
    "$<INSTALL_INTERFACE:include/mylib>"
)

# Export from Build-Tree
dependency(EXPORT "<PROJECT_NAME>_my_shared_lib" "<PROJECT_NAME>_my_static_lib"
  BUILD_TREE
  OUTPUT_FILE_NAME "InternalDependencyTargets.cmake"
)
# Is more or less equivalent to:
export(TARGETS "my_shared_lib" "my_static_lib"
  APPEND
  FILE "InternalDependencyTargets.cmake"
)

# Exporting from Install-Tree
set(CMAKE_INSTALL_PREFIX "${CMAKE_CURRENT_BINARY_DIR}/install")
dependency(EXPORT "<PROJECT_NAME>_my_shared_lib" "<PROJECT_NAME>_my_static_lib"
  INSTALL_TREE
  OUTPUT_FILE_NAME "InternalDependencyTargets.cmake"
)
# Is more or less equivalent to:
install(TARGETS "my_shared_lib" "my_static_lib"
  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")