Force inclusion of all members of a static library when linked as a
dependency of consuming Executables, Shared Libraries,
and Module Libraries. This feature is only supported for the
following platforms, with limitations as noted:
Note
Since Static Libraries are archives and not linked binaries,
CMake records their link dependencies for transitive use when linking
consuming binaries. Therefore WHOLE_ARCHIVE does not cause a
static library's objects to be included in other static libraries.
Use Object Libraries for that.
FRAMEWORKThis option tells the linker to search for the specified framework using
the -framework linker option. It can only be used on Apple platforms,
and only with a linker that understands the option used (i.e. the linker
provided with Xcode, or one compatible with it).
The framework can be specified as a CMake framework target, a bare framework
name, or a file path. If a target is given, that target must have the
FRAMEWORK target property set to true. For a file path, if it
contains a directory part, that directory will be added as a framework
search path.
add_library(lib SHARED ...)
target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:FRAMEWORK,/path/to/my_framework>")
# The constructed linker command line will contain:
# -F/path/to -framework my_framework
File paths must conform to one of the following patterns (* is a
wildcard, and optional parts are shown as [...]):
[/path/to/]FwName[.framework]
[/path/to/]FwName.framework/FwName[suffix]
[/path/to/]FwName.framework/Versions/*/FwName[suffix]
Note that CMake recognizes and automatically handles framework targets,
even without using the $<LINK_LIBRARY:FRAMEWORK,...> expression.
The generator expression can still be used with a CMake target if the
project wants to be explicit about it, but it is not required to do so.
The linker command line may have some differences between using the
generator expression or not, but the final result should be the same.
On the other hand, if a file path is given, CMake will recognize some paths
automatically, but not all cases. The project may want to use
$<LINK_LIBRARY:FRAMEWORK,...> for file paths so that the expected
behavior is clear.
NEEDED_FRAMEWORKThis is similar to the FRAMEWORK feature, except it forces the linker
to link with the framework even if no symbols are used from it. It uses
the -needed_framework option and has the same linker constraints as
FRAMEWORK.
REEXPORT_FRAMEWORKThis is similar to the FRAMEWORK feature, except it tells the linker
that the framework should be available to clients linking to the library
being created. It uses the -reexport_framework option and has the
same linker constraints as FRAMEWORK.
WEAK_FRAMEWORKThis is similar to the FRAMEWORK feature, except it forces the linker
to mark the framework and all references to it as weak imports. It uses
the -weak_framework option and has the same linker constraints as
FRAMEWORK.
NEEDED_LIBRARYThis is similar to the NEEDED_FRAMEWORK feature, except it is for use
with non-framework targets or libraries (Apple platforms only).
It uses the -needed_library or -needed-l option as appropriate,
and has the same linker constraints as NEEDED_FRAMEWORK.
REEXPORT_LIBRARYThis is similar to the REEXPORT_FRAMEWORK feature, except it is for use
with non-framework targets or libraries (Apple platforms only).
It uses the -reexport_library or -reexport-l option as appropriate,
and has the same linker constraints as REEXPORT_FRAMEWORK.
WEAK_LIBRARYThis is similar to the WEAK_FRAMEWORK feature, except it is for use
with non-framework targets or libraries (Apple platforms only).
It uses the -weak_library or -weak-l option as appropriate,
and has the same linker constraints as WEAK_FRAMEWORK.
Built-in and custom library features are defined in terms of the following
variables:
The value used for each of these variables is the value as set at the end of
the directory scope in which the target was created. The usage is as follows:
If the language-specific
CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED variable
is true, the feature must be defined by the corresponding
CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE> variable.
If no language-specific feature is supported, then the
CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED variable must be
true and the feature must be defined by the corresponding
CMAKE_LINK_LIBRARY_USING_<FEATURE> variable.
The following limitations should be noted:
The library-list can specify CMake targets or libraries.
Any CMake target of type OBJECT
or INTERFACE will ignore the feature aspect
of the expression and instead be linked in the standard way.
The $<LINK_LIBRARY:...> generator expression can only be used to
specify link libraries. In practice, this means it can appear in the
LINK_LIBRARIES, INTERFACE_LINK_LIBRARIES, and
INTERFACE_LINK_LIBRARIES_DIRECT target properties, and be
specified in target_link_libraries() and link_libraries()
commands.
If a $<LINK_LIBRARY:...> generator expression appears in the
INTERFACE_LINK_LIBRARIES property of a target, it will be
included in the imported target generated by a install(EXPORT)
command. It is the responsibility of the environment consuming this
import to define the link feature used by this expression.
Each target or library involved in the link step must have at most only
one kind of library feature. The absence of a feature is also incompatible
with all other features. For example:
add_library(lib1 ...)
add_library(lib2 ...)
add_library(lib3 ...)
# lib1 will be associated with feature1
target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature1,lib1>")
# lib1 is being linked with no feature here. This conflicts with the
# use of feature1 in the line above and would result in an error.
target_link_libraries(lib3 PRIVATE lib1 lib2)
Where it isn't possible to use the same feature throughout a build for a
given target or library, the LINK_LIBRARY_OVERRIDE and
LINK_LIBRARY_OVERRIDE_<LIBRARY> target properties can be
used to resolve such incompatibilities.
The $<LINK_LIBRARY:...> generator expression does not guarantee
that the list of specified targets and libraries will be kept grouped
together. To manage constructs like --start-group and --end-group,
as supported by the GNU ld linker, use the LINK_GROUP
generator expression instead.
-
$<LINK_GROUP:feature,library-list>
-
Specify a group of libraries to link to a target, along with a feature
which defines how that group should be linked. For example:
add_library(lib1 STATIC ...)
add_library(lib2 ...)
target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:RESCAN,lib1,external>")
This specifies that lib2 should link to lib1 and external, and
that both of those two libraries should be included on the linker command
line according to the definition of the RESCAN feature.
Feature names are case-sensitive and may only contain letters, numbers and
underscores. Feature names defined in all uppercase are reserved for CMake's
own built-in features. Currently, there is only one pre-defined built-in
group feature:
RESCANSome linkers are single-pass only. For such linkers, circular references
between libraries typically result in unresolved symbols. This feature
instructs the linker to search the specified static libraries repeatedly
until no new undefined references are created.
Normally, a static library is searched only once in the order that it is
specified on the command line. If a symbol in that library is needed to
resolve an undefined symbol referred to by an object in a library that
appears later on the command line, the linker would not be able to resolve
that reference. By grouping the static libraries with the RESCAN
feature, they will all be searched repeatedly until all possible references
are resolved. This will use linker options like --start-group and
--end-group, or on SunOS, -z rescan-start and -z rescan-end.
Using this feature has a significant performance cost. It is best to use it
only when there are unavoidable circular references between two or more
static libraries.
This feature is available when using toolchains that target Linux, BSD, and
SunOS. It can also be used when targeting Windows platforms if the GNU
toolchain is used.
Built-in and custom group features are defined in terms of the following
variables:
The value used for each of these variables is the value as set at the end of
the directory scope in which the target was created. The usage is as follows:
If the language-specific
CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED variable
is true, the feature must be defined by the corresponding
CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE> variable.
If no language-specific feature is supported, then the
CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED variable must be
true and the feature must be defined by the corresponding
CMAKE_LINK_GROUP_USING_<FEATURE> variable.
The LINK_GROUP generator expression is compatible with the
LINK_LIBRARY generator expression. The libraries involved in a
group can be specified using the LINK_LIBRARY generator expression.
Each target or external library involved in the link step is allowed to be
part of multiple groups, but only if all the groups involved specify the
same feature. Such groups will not be merged on the linker command line,
the individual groups will still be preserved. Mixing different group
features for the same target or library is forbidden.
add_library(lib1 ...)
add_library(lib2 ...)
add_library(lib3 ...)
add_library(lib4 ...)
add_library(lib5 ...)
target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>")
target_link_libraries(lib4 PRIVATE "$<LINK_GROUP:feature1,lib1,lib3>")
# lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3}.
# Both groups specify the same feature, so this is fine.
target_link_libraries(lib5 PRIVATE "$<LINK_GROUP:feature2,lib1,lib3>")
# An error will be raised here because both lib1 and lib3 are part of two
# groups with different features.
When a target or an external library is involved in the link step as part of
a group and also as not part of any group, any occurrence of the non-group
link item will be replaced by the groups it belongs to.
add_library(lib1 ...)
add_library(lib2 ...)
add_library(lib3 ...)
add_library(lib4 ...)
target_link_libraries(lib3 PUBLIC lib1)
target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>")
# lib4 will only be linked with lib3 and the group {lib1,lib2}
Because lib1 is part of the group defined for lib4, that group then
gets applied back to the use of lib1 for lib3. The end result will
be as though the linking relationship for lib3 had been specified as:
target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>")
Be aware that the precedence of the group over the non-group link item can
result in circular dependencies between groups. If this occurs, a fatal
error is raised because circular dependencies are not allowed for groups.
add_library(lib1A ...)
add_library(lib1B ...)
add_library(lib2A ...)
add_library(lib2B ...)
add_library(lib3 ...)
# Non-group linking relationships, these are non-circular so far
target_link_libraries(lib1A PUBLIC lib2A)
target_link_libraries(lib2B PUBLIC lib1B)
# The addition of these groups creates circular dependencies
target_link_libraries(lib3 PRIVATE
"$<LINK_GROUP:feat,lib1A,lib1B>"
"$<LINK_GROUP:feat,lib2A,lib2B>"
)
Because of the groups defined for lib3, the linking relationships for
lib1A and lib2B effectively get expanded to the equivalent of:
target_link_libraries(lib1A PUBLIC "$<LINK_GROUP:feat,lib2A,lib2B>")
target_link_libraries(lib2B PUBLIC "$<LINK_GROUP:feat,lib1A,lib1B>")
This creates a circular dependency between groups:
lib1A --> lib2B --> lib1A.
The following limitations should also be noted:
-
$<LINK_ONLY:...>
-
Content of ..., except while collecting usage requirements from
transitive compile properties,
in which case it is the empty string. This is intended for use in an
INTERFACE_LINK_LIBRARIES target property, typically populated
via the target_link_libraries() command, to specify private link
dependencies without other usage requirements such as include directories or
compile options.
-
$<DEVICE_LINK:list>
-
Returns the list if it is the device link step, an empty list otherwise.
The device link step is controlled by CUDA_SEPARABLE_COMPILATION
and CUDA_RESOLVE_DEVICE_SYMBOLS properties and
policy CMP0105. This expression can only be used to specify link
options.
-
$<HOST_LINK:list>
-
Returns the list if it is the normal link step, an empty list otherwise.
This expression is mainly useful when a device link step is also involved
(see $<DEVICE_LINK:list> generator expression). This expression can
only be used to specify link options.
See also the CMAKE_<LANG>_COMPILER_LINKER_ID and
CMAKE_<LANG>_COMPILER_LINKER_FRONTEND_VARIANT variables, which are
closely related to most of the expressions in this sub-section.
-
$<C_COMPILER_LINKER_ID>
-
CMake's linker id of the C linker used.
-
$<C_COMPILER_LINKER_ID:linker_ids>
-
where linker_ids is a comma-separated list.
1 if CMake's linker id of the C linker matches any one
of the entries in linker_ids, otherwise 0.
-
$<CXX_COMPILER_LINKER_ID>
-
CMake's linker id of the C++ linker used.
-
$<CXX_COMPILER_LINKER_ID:linker_ids>
-
where linker_ids is a comma-separated list.
1 if CMake's linker id of the C++ linker matches any one
of the entries in linker_ids, otherwise 0.
-
$<CUDA_COMPILER_LINKER_ID>
-
CMake's linker id of the CUDA linker used.
-
$<CUDA_COMPILER_LINKER_ID:linker_ids>
-
where linker_ids is a comma-separated list.
1 if CMake's linker id of the CUDA linker matches any one
of the entries in linker_ids, otherwise 0.
-
$<OBJC_COMPILER_LINKER_ID>
-
CMake's linker id of the Objective-C linker used.
-
$<OBJC_COMPILER_LINKER_ID:linker_ids>
-
where linker_ids is a comma-separated list.
1 if CMake's linker id of the Objective-C linker matches any one
of the entries in linker_ids, otherwise 0.
-
$<OBJCXX_COMPILER_LINKER_ID>
-
CMake's linker id of the Objective-C++ linker used.
-
$<OBJCXX_COMPILER_LINKER_ID:linker_ids>
-
where linker_ids is a comma-separated list.
1 if CMake's linker id of the Objective-C++ linker matches any one
of the entries in linker_ids, otherwise 0.
-
$<Fortran_COMPILER_LINKER_ID>
-
CMake's linker id of the Fortran linker used.
-
$<Fortran_COMPILER_LINKER_ID:linker_ids>
-
where linker_ids is a comma-separated list.
1 if CMake's linker id of the Fortran linker matches any one
of the entries in linker_ids, otherwise 0.
-
$<HIP_COMPILER_LINKER_ID>
-
CMake's linker id of the HIP linker used.
-
$<HIP_COMPILER_LINKER_ID:linker_ids>
-
where linker_ids is a comma-separated list.
1 if CMake's linker id of the HIP linker matches any one
of the entries in linker_ids, otherwise 0.
-
$<C_COMPILER_LINKER_FRONTEND_VARIANT>
-
CMake's linker frontend variant of the C linker used.
-
$<C_COMPILER_LINKER_FRONTEND_VARIANT:variant_ids>
-
where variant_ids is a comma-separated list.
1 if CMake's linker frontend variant of the C linker matches any one
of the entries in variant_ids, otherwise 0.
-
$<CXX_COMPILER_LINKER_FRONTEND_VARIANT>
-
CMake's linker frontend variant of the C++ linker used.
-
$<CXX_COMPILER_LINKER_FRONTEND_VARIANT:variant_ids>
-
where variant_ids is a comma-separated list.
1 if CMake's linker frontend variant of the C++ linker matches any one
of the entries in variant_ids, otherwise 0.
-
$<CUDA_COMPILER_LINKER_FRONTEND_VARIANT>
-
CMake's linker frontend variant of the CUDA linker used.
-
$<CUDA_COMPILER_LINKER_FRONTEND_VARIANT:variant_ids>
-
where variant_ids is a comma-separated list.
1 if CMake's linker frontend variant of the CUDA linker matches any one
of the entries in variant_ids, otherwise 0.
-
$<OBJC_COMPILER_LINKER_FRONTEND_VARIANT>
-
CMake's linker frontend variant of the Objective-C linker used.
-
$<OBJC_COMPILER_LINKER_FRONTEND_VARIANT:variant_ids>
-
where variant_ids is a comma-separated list.
1 if CMake's linker frontend variant of the Objective-C linker matches
any one of the entries in variant_ids, otherwise 0.
-
$<OBJCXX_COMPILER_LINKER_FRONTEND_VARIANT>
-
CMake's linker frontend variant of the Objective-C++ linker used.
-
$<OBJCXX_COMPILER_LINKER_FRONTEND_VARIANT:variant_ids>
-
where variant_ids is a comma-separated list.
1 if CMake's linker frontend variant of the Objective-C++ linker matches
any one of the entries in variant_ids, otherwise 0.
-
$<Fortran_COMPILER_LINKER_FRONTEND_VARIANT>
-
CMake's linker frontend variant of the Fortran linker used.
-
$<Fortran_COMPILER_LINKER_FRONTEND_VARIANT:variant_ids>
-
where variant_ids is a comma-separated list.
1 if CMake's linker frontend variant of the Fortran linker matches
any one of the entries in variant_ids, otherwise 0.
-
$<HIP_COMPILER_LINKER_FRONTEND_VARIANT>
-
CMake's linker frontend variant of the HIP linker used.
-
$<HIP_COMPILER_LINKER_FRONTEND_VARIANT:variant_ids>
-
where variant_ids is a comma-separated list.
1 if CMake's linker frontend variant of the HIP linker matches
any one of the entries in variant_ids, otherwise 0.
These expressions look up the values of
target properties.
-
$<TARGET_PROPERTY:tgt,prop>
Value of the property prop on the target tgt, or empty if
the property is not set.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
Changed in version 3.26: When encountered during evaluation of Target Usage Requirements,
typically in an INTERFACE_* target property, lookup of the tgt
name occurs in the directory of the target specifying the requirement,
rather than the directory of the consuming target for which the
expression is being evaluated.
-
$<TARGET_PROPERTY:prop>
Value of the property prop on the target for which the expression
is being evaluated, or empty if the property is not set.
Note that for generator expressions in Target Usage Requirements
this is the consuming target rather than the target specifying the
requirement.
The expressions have special evaluation rules for some properties:
- Target Build Specification Properties
These evaluate as a semicolon-separated list
representing the union of the value on the target itself with the values
of the corresponding Target Usage Requirements on targets named by
the target's LINK_LIBRARIES:
- Target Usage Requirement Properties
These evaluate as a semicolon-separated list
representing the union of the value on the target itself with the values
of the same properties on targets named by the target's
INTERFACE_LINK_LIBRARIES:
- Custom Transitive Properties
-
These are processed during evaluation as follows:
Evaluation of $<TARGET_PROPERTY:tgt,PROP> for some property
PROP, named without an INTERFACE_ prefix,
checks the TRANSITIVE_COMPILE_PROPERTIES
and TRANSITIVE_LINK_PROPERTIES properties on target tgt,
on targets named by its LINK_LIBRARIES, and on the
transitive closure of targets named by the linked targets'
INTERFACE_LINK_LIBRARIES.
If PROP is listed by one of those properties, then it evaluates as
a semicolon-separated list representing
the union of the value on the target itself with the values of the
corresponding INTERFACE_PROP on targets named by the target's
LINK_LIBRARIES:
Evaluation of $<TARGET_PROPERTY:tgt,INTERFACE_PROP> for some
property INTERFACE_PROP, named with an INTERFACE_ prefix,
checks the TRANSITIVE_COMPILE_PROPERTIES
and TRANSITIVE_LINK_PROPERTIES properties on target tgt,
and on the transitive closure of targets named by its
INTERFACE_LINK_LIBRARIES.
If the corresponding PROP is listed by one of those properties,
then INTERFACE_PROP evaluates as a
semicolon-separated list representing the
union of the value on the target itself with the value of the same
property on targets named by the target's
INTERFACE_LINK_LIBRARIES:
If a PROP is named by both TRANSITIVE_COMPILE_PROPERTIES
and TRANSITIVE_LINK_PROPERTIES, the latter takes precedence.
- Compatible Interface Properties
These evaluate as a single value combined from the target itself,
from targets named by the target's LINK_LIBRARIES, and
from the transitive closure of the linked targets'
INTERFACE_LINK_LIBRARIES. Values of a compatible
interface property from multiple targets combine based on the type
of compatibility required by the COMPATIBLE_INTERFACE_* property
defining it.
These expressions look up information about artifacts associated with
a given target tgt. Unless otherwise stated, this can be any
runtime artifact, namely:
In the following, the phrase "the tgt filename" means the name of the
tgt binary file. This has to be distinguished from the phrase
"the target name", which is just the string tgt.
-
$<TARGET_FILE:tgt>
Full path to the tgt binary file.
Note that tgt is not added as a dependency of the target this
expression is evaluated on, unless the expression is being used in
add_custom_command() or add_custom_target().
-
$<TARGET_FILE_BASE_NAME:tgt[,POSTFIX:(INCLUDE|EXCLUDE)]>
-
New in version 4.2: The option POSTFIX, which can be used to control the inclusion or not
of the <CONFIG>_POSTFIX target property value as part of the
base name. The default is POSTFIX:INCLUDE.
Base name of tgt, i.e. $<TARGET_FILE_NAME:tgt> without prefix and
suffix and, optionally, postfix.
For example, if the tgt filename is libbase_postfix.so, the base name
is:
base_postfix for $<TARGET_FILE_BASE_NAME:tgt> or
$<TARGET_FILE_BASE_NAME:tgt,POSTFIX:INCLUDE>.
base for $<TARGET_FILE_BASE_NAME:tgt,POSTFIX:EXCLUDE>.
See also the OUTPUT_NAME, ARCHIVE_OUTPUT_NAME,
LIBRARY_OUTPUT_NAME and RUNTIME_OUTPUT_NAME
target properties, their configuration-specific variants
OUTPUT_NAME_<CONFIG>, ARCHIVE_OUTPUT_NAME_<CONFIG>,
LIBRARY_OUTPUT_NAME_<CONFIG> and
RUNTIME_OUTPUT_NAME_<CONFIG>, and
the <CONFIG>_POSTFIX and DEBUG_POSTFIX target
properties.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_FILE_PREFIX:tgt>
-
Prefix of the tgt filename (such as lib).
See also the PREFIX target property.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_FILE_SUFFIX:tgt>
-
Suffix of the tgt filename (extension such as .so or .exe).
See also the SUFFIX target property.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_FILE_NAME:tgt>
The tgt filename.
Note that tgt is not added as a dependency of the target this
expression is evaluated on (see policy CMP0112).
-
$<TARGET_FILE_DIR:tgt>
Directory of the tgt binary file.
Note that tgt is not added as a dependency of the target this
expression is evaluated on (see policy CMP0112).
-
$<TARGET_IMPORT_FILE:tgt>
-
Full path to the linker import file. On DLL platforms, it would be the
.lib file. For executables on AIX, and for shared libraries on macOS,
it could be, respectively, the .imp or .tbd import file,
depending on the value of the ENABLE_EXPORTS property.
This expands to an empty string when there is no import file associated
with the target.
-
$<TARGET_IMPORT_FILE_BASE_NAME:tgt[,POSTFIX:(INCLUDE|EXCLUDE)]>
-
New in version 4.2: The option POSTFIX, which can be used to control the inclusion or not
of the <CONFIG>_POSTFIX target property value as part of the
base name. The default is POSTFIX:INCLUDE.
Base name of the linker import file of the target tgt without prefix or
suffix and, optionally, postfix.
For example, if the target file name is libbase_postfix.tbd, the base
name is:
base_postfix for $<TARGET_IMPORT_FILE_BASE_NAME:tgt> or
$<TARGET_IMPORT_FILE_BASE_NAME:tgt,POSTFIX:INCLUDE>.
base for $<TARGET_IMPORT_FILE_BASE_NAME:tgt,POSTFIX:EXCLUDE>.
See also the OUTPUT_NAME and ARCHIVE_OUTPUT_NAME
target properties, their configuration-specific variants
OUTPUT_NAME_<CONFIG> and
ARCHIVE_OUTPUT_NAME_<CONFIG>, and
the <CONFIG>_POSTFIX and DEBUG_POSTFIX target
properties.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_IMPORT_FILE_PREFIX:tgt>
-
Prefix of the import file of the target tgt.
See also the IMPORT_PREFIX target property.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_IMPORT_FILE_SUFFIX:tgt>
-
Suffix of the import file of the target tgt.
The suffix corresponds to the file extension (such as .lib or .tbd).
See also the IMPORT_SUFFIX target property.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_IMPORT_FILE_NAME:tgt>
-
Name of the import file of the target tgt.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_IMPORT_FILE_DIR:tgt>
-
Directory of the import file of the target tgt.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_LINKER_FILE:tgt>
File used when linking to the tgt target. This will usually
be the library that tgt represents (.a, .lib, .so),
but for a shared library on DLL platforms, it would be the .lib
import library associated with the DLL.
New in version 3.27: On macOS, it could be the .tbd import file associated with the shared
library, depending on the value of the ENABLE_EXPORTS property.
This generator expression is equivalent to
$<TARGET_LINKER_LIBRARY_FILE> or
$<TARGET_LINKER_IMPORT_FILE> generator expressions, depending on the
characteristics of the target and the platform.
-
$<TARGET_LINKER_FILE_BASE_NAME:tgt[,POSTFIX:(INCLUDE|EXCLUDE)]>
-
New in version 4.2: The option POSTFIX, which can be used to control the inclusion or not
of the <CONFIG>_POSTFIX target property value as part of the
base name. The default is POSTFIX:INCLUDE.
Base name of file used to link the target tgt, i.e.
$<TARGET_LINKER_FILE_NAME:tgt> without prefix and suffix, and,
optionally, postfix.
For example, if target file name is libbase_postfix.a, the base name is:
base_postfix for $<TARGET_LINKER_FILE_BASE_NAME:tgt> or
$<TARGET_LINKER_FILE_BASE_NAME:tgt,POSTFIX:INCLUDE>.
base for $<TARGET_LINKER_FILE_BASE_NAME:tgt,POSTFIX:EXCLUDE>.
See also the OUTPUT_NAME, ARCHIVE_OUTPUT_NAME,
and LIBRARY_OUTPUT_NAME target properties, their
configuration-specific variants OUTPUT_NAME_<CONFIG>,
ARCHIVE_OUTPUT_NAME_<CONFIG> and
LIBRARY_OUTPUT_NAME_<CONFIG>, and
the <CONFIG>_POSTFIX and DEBUG_POSTFIX target
properties.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_LINKER_FILE_PREFIX:tgt>
-
Prefix of file used to link target tgt.
See also the PREFIX and IMPORT_PREFIX target
properties.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_LINKER_FILE_SUFFIX:tgt>
-
Suffix of file used to link where tgt is the name of a target.
The suffix corresponds to the file extension (such as ".so" or ".lib").
See also the SUFFIX and IMPORT_SUFFIX target
properties.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_LINKER_FILE_NAME:tgt>
Name of file used to link target tgt.
Note that tgt is not added as a dependency of the target this
expression is evaluated on (see policy CMP0112).
-
$<TARGET_LINKER_FILE_DIR:tgt>
Directory of file used to link target tgt.
Note that tgt is not added as a dependency of the target this
expression is evaluated on (see policy CMP0112).
-
$<TARGET_LINKER_LIBRARY_FILE:tgt>
-
File used when linking o the tgt target is done using directly the
library, and not an import file. This will usually be the library that
tgt represents (.a, .so, .dylib). So, on DLL platforms, it
will be an empty string.
-
$<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt[,POSTFIX:(INCLUDE|EXCLUDE)]>
-
New in version 4.2: The option POSTFIX, which can be used to control the inclusion or not
of the <CONFIG>_POSTFIX target property value as part of the
base name. The default is POSTFIX:INCLUDE.
Base name of library file used to link the target tgt, i.e.
$<TARGET_LINKER_LIBRARY_FILE_NAME:tgt> without prefix and
suffix,and, optionally, postfix.
For example, if target file name is libbase_postfix.a, the base name is:
base_postfix for $<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt> or
$<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt,POSTFIX:INCLUDE>.
base for
$<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt,POSTFIX:EXCLUDE>.
See also the OUTPUT_NAME, ARCHIVE_OUTPUT_NAME,
and LIBRARY_OUTPUT_NAME target properties, their
configuration-specific variants OUTPUT_NAME_<CONFIG>,
ARCHIVE_OUTPUT_NAME_<CONFIG> and
LIBRARY_OUTPUT_NAME_<CONFIG>, and
the <CONFIG>_POSTFIX and DEBUG_POSTFIX target
properties.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_LINKER_LIBRARY_FILE_PREFIX:tgt>
-
Prefix of the library file used to link target tgt.
See also the PREFIX target property.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_LINKER_LIBRARY_FILE_SUFFIX:tgt>
-
Suffix of the library file used to link target tgt.
The suffix corresponds to the file extension (such as ".a" or ".dylib").
See also the SUFFIX target property.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_LINKER_LIBRARY_FILE_NAME:tgt>
-
Name of the library file used to link target tgt.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_LINKER_LIBRARY_FILE_DIR:tgt>
-
Directory of the library file used to link target tgt.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_LINKER_IMPORT_FILE:tgt>
-
File used when linking to the tgt target is done using an import
file. This will usually be the import file that tgt represents
(.lib, .tbd). So, when no import file is involved in the link step,
an empty string is returned.
-
$<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt[,POSTFIX:(INCLUDE|EXCLUDE)]>
-
New in version 4.2: The option POSTFIX, which can be used to control the inclusion or not
of the <CONFIG>_POSTFIX target property value as part of the
base name. The default is POSTFIX:INCLUDE.
Base name of the import file used to link the target tgt, i.e.
$<TARGET_LINKER_IMPORT_FILE_NAME:tgt> without prefix and suffix,
and, optionally, postfix.
For example, if target file name is libbase_postfix.tbd, the base name is
base_postfix for $<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt> or
$<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt,POSTFIX:INCLUDE>.
base for
$<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt,POSTFIX:EXCLUDE>.
See also the OUTPUT_NAME and ARCHIVE_OUTPUT_NAME,
target properties, their configuration-specific variants
OUTPUT_NAME_<CONFIG> and
ARCHIVE_OUTPUT_NAME_<CONFIG>, and
the <CONFIG>_POSTFIX and DEBUG_POSTFIX target
properties.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_LINKER_IMPORT_FILE_PREFIX:tgt>
-
Prefix of the import file used to link target tgt.
See also the IMPORT_PREFIX target property.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_LINKER_IMPORT_FILE_SUFFIX:tgt>
-
Suffix of the import file used to link target tgt.
The suffix corresponds to the file extension (such as ".lib" or ".tbd").
See also the IMPORT_SUFFIX target property.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_LINKER_IMPORT_FILE_NAME:tgt>
-
Name of the import file used to link target tgt.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_LINKER_IMPORT_FILE_DIR:tgt>
-
Directory of the import file used to link target tgt.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_SONAME_FILE:tgt>
File with soname (.so.3) where tgt is the name of a target.
-
$<TARGET_SONAME_FILE_NAME:tgt>
Name of file with soname (.so.3).
Note that tgt is not added as a dependency of the target this
expression is evaluated on (see policy CMP0112).
-
$<TARGET_SONAME_FILE_DIR:tgt>
Directory of file with soname (.so.3).
Note that tgt is not added as a dependency of the target this
expression is evaluated on (see policy CMP0112).
-
$<TARGET_SONAME_IMPORT_FILE:tgt>
-
Import file with soname (.3.tbd) where tgt is the name of a target.
-
$<TARGET_SONAME_IMPORT_FILE_NAME:tgt>
-
Name of the import file with soname (.3.tbd).
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_SONAME_IMPORT_FILE_DIR:tgt>
-
Directory of the import file with soname (.3.tbd).
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_PDB_FILE:tgt>
-
Full path to the linker generated program database file (.pdb)
where tgt is the name of a target.
See also the PDB_NAME and PDB_OUTPUT_DIRECTORY
target properties and their configuration specific variants
PDB_NAME_<CONFIG> and PDB_OUTPUT_DIRECTORY_<CONFIG>.
-
$<TARGET_PDB_FILE_BASE_NAME:tgt[,POSTFIX:(INCLUDE|EXCLUDE)]>
-
Base name of the linker generated program database file (.pdb)
where tgt is the name of a target.
New in version 4.2: The option POSTFIX, which can be used to control the inclusion or not
of the <CONFIG>_POSTFIX target property value as part of the
base name. The default is POSTFIX:INCLUDE.
Changed in version 4.2: The postfix, as specified by DEBUG_POSTFIX or
<CONFIG>_POSTFIX target properties, is always included in the
PDB base name, except if option POSTFIX has value EXCLUDE.
See the policy CMP0202.
The base name corresponds to the target PDB file name (see
$<TARGET_PDB_FILE_NAME:tgt>) without prefix and suffix, and, optionally,
postfix. For example, if target file name is base_postfix.pdb, the base
name is
base_postfix for $<TARGET_PDB_FILE_BASE_NAME:tgt> or
$<TARGET_PDB_FILE_BASE_NAME:tgt,POSTFIX:INCLUDE>.
base for $<TARGET_PDB_FILE_BASE_NAME:tgt,POSTFIX:EXCLUDE>.
See also the OUTPUT_NAME, PDB_NAME target properties,
and their configuration-specific variants OUTPUT_NAME_<CONFIG>
and PDB_NAME_<CONFIG>, and the <CONFIG>_POSTFIX and
DEBUG_POSTFIX target properties.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
-
$<TARGET_PDB_FILE_NAME:tgt>
-
Name of the linker generated program database file (.pdb).
Note that tgt is not added as a dependency of the target this
expression is evaluated on (see policy CMP0112).
-
$<TARGET_PDB_FILE_DIR:tgt>
-
Directory of the linker generated program database file (.pdb).
Note that tgt is not added as a dependency of the target this
expression is evaluated on (see policy CMP0112).
-
$<TARGET_BUNDLE_DIR:tgt>
-
Full path to the bundle directory (/path/to/my.app,
/path/to/my.framework, or /path/to/my.bundle),
where tgt is the name of a target.
Note that tgt is not added as a dependency of the target this
expression is evaluated on (see policy CMP0112).
-
$<TARGET_BUNDLE_DIR_NAME:tgt>
-
Name of the bundle directory (my.app, my.framework, or
my.bundle), where tgt is the name of a target.
Note that tgt is not added as a dependency of the target this
expression is evaluated on (see policy CMP0112).
-
$<TARGET_BUNDLE_CONTENT_DIR:tgt>
-
Full path to the bundle content directory where tgt is the name of a
target. For the macOS SDK it leads to /path/to/my.app/Contents,
/path/to/my.framework, or /path/to/my.bundle/Contents.
For all other SDKs (e.g. iOS) it leads to /path/to/my.app,
/path/to/my.framework, or /path/to/my.bundle due to the flat
bundle structure.
Note that tgt is not added as a dependency of the target this
expression is evaluated on (see policy CMP0112).
-
$<TARGET_OBJECTS:tgt>
-
List of objects resulting from building tgt. This would typically be
used on object library targets.
-
$<TARGET_RUNTIME_DLLS:tgt>
-
List of DLLs that the target depends on at runtime. This is determined by
the locations of all the SHARED targets in the target's transitive
dependencies. If only the directories of the DLLs are needed, see the
TARGET_RUNTIME_DLL_DIRS generator expression.
Using this generator expression on targets other than
executables, SHARED libraries, and MODULE libraries is an error.
On non-DLL platforms, this expression always evaluates to an empty string.
This generator expression can be used to copy all of the DLLs that a target
depends on into its output directory in a POST_BUILD custom command using
the cmake -E copy -t command. For example:
find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT)
add_executable(exe main.c)
target_link_libraries(exe PRIVATE foo::foo foo::bar)
add_custom_command(TARGET exe POST_BUILD
COMMAND ${CMAKE_COMMAND} -E copy -t $<TARGET_FILE_DIR:exe> $<TARGET_RUNTIME_DLLS:exe>
COMMAND_EXPAND_LISTS
)
Note
Imported Targets are supported only if they know the location
of their .dll files. An imported SHARED library must have
IMPORTED_LOCATION set to its .dll file. See the
add_library imported libraries
section for details. Many Find Modules produce imported targets
with the UNKNOWN type and therefore will be ignored.
On platforms that support runtime paths (RPATH), refer to the
INSTALL_RPATH target property.
On Apple platforms, refer to the INSTALL_NAME_DIR target property.
-
$<TARGET_RUNTIME_DLL_DIRS:tgt>
-
List of the directories which contain the DLLs that the target depends on at
runtime (see TARGET_RUNTIME_DLLS). This is determined by
the locations of all the SHARED targets in the target's transitive
dependencies. Using this generator expression on targets other than
executables, SHARED libraries, and MODULE libraries is an error.
On non-DLL platforms, this expression always evaluates to an empty string.
This generator expression can e.g. be used to create a batch file using
file(GENERATE) which sets the PATH environment variable accordingly.
-
$<TARGET_INTERMEDIATE_DIR:tgt>
-
The full path to the directory where intermediate target files, such as
object and dependency files, are stored.
-
$<INSTALL_INTERFACE:...>
Content of ... when the property is exported using
install(EXPORT), and empty otherwise.
-
$<BUILD_INTERFACE:...>
Content of ... when the property is exported using export(), or
when the target is used by another target in the same buildsystem. Expands to
the empty string otherwise.
-
$<BUILD_LOCAL_INTERFACE:...>
-
Content of ... when the target is used by another target in the same
buildsystem. Expands to the empty string otherwise.
-
$<INSTALL_PREFIX>
Content of the install prefix when the target is exported via
install(EXPORT), or when evaluated in the
INSTALL_NAME_DIR property or the INSTALL_NAME_DIR argument of
install(RUNTIME_DEPENDENCY_SET), and empty otherwise.
Changed in version 3.27: Evaluates to the content of the install prefix
in the code argument of install(CODE) or
the file argument of install(SCRIPT).
-
$<GENEX_EVAL:expr>
-
Content of expr evaluated as a generator expression in the current
context. This enables consumption of generator expressions whose
evaluation results itself in generator expressions.
-
$<TARGET_GENEX_EVAL:tgt,expr>
-
Content of expr evaluated as a generator expression in the context of
tgt target. This enables consumption of custom target properties that
themselves contain generator expressions.
Having the capability to evaluate generator expressions is very useful when
you want to manage custom properties supporting generator expressions.
For example:
add_library(foo ...)
set_property(TARGET foo PROPERTY
CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>
)
add_custom_target(printFooKeys
COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS>
)
This naive implementation of the printFooKeys custom command is wrong
because CUSTOM_KEYS target property is not evaluated and the content
is passed as is (i.e. $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>).
To have the expected result (i.e. FOO_EXTRA_THINGS if config is
Debug), it is required to evaluate the output of
$<TARGET_PROPERTY:foo,CUSTOM_KEYS>:
add_custom_target(printFooKeys
COMMAND ${CMAKE_COMMAND} -E
echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>>
)
These expressions evaluate to specific string literals. Use them in place of
the actual string literal where you need to prevent them from having their
special meaning.
-
$<ANGLE-R>
A literal >. Used for example to compare strings that contain a >.
-
$<COMMA>
A literal ,. Used for example to compare strings which contain a ,.
-
$<SEMICOLON>
A literal ;. Used to prevent list expansion on an argument with ;.
-
$<QUOTE>
-
A literal ". Used to allow string literal quotes inside a generator expression.
-
$<CONFIGURATION>
Configuration name. Deprecated since CMake 3.0. Use CONFIG instead.
