LINK_LIBRARY

This generator expression belongs to the Link Features family. See that section for related generator expressions.

Syntax

$<LINK_LIBRARY:feature,library-list>

Added in version 3.24.

Specify a set of libraries to link to a target, along with a feature which provides details about how they should be linked. For example:

add_library(lib1 STATIC ...)
add_library(lib2 ...)
target_link_libraries(lib2 PRIVATE "$<LINK_LIBRARY:WHOLE_ARCHIVE,lib1>")

This specifies that lib2 should link to lib1 and use the WHOLE_ARCHIVE feature when doing so.

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. The pre-defined built-in library features are:

DEFAULT

This feature corresponds to standard linking, essentially equivalent to using no feature at all. It is typically only used with the LINK_LIBRARY_OVERRIDE and LINK_LIBRARY_OVERRIDE_<LIBRARY> target properties.

WHOLE_ARCHIVE

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:

• Linux.

• All BSD variants.

• SunOS.

• All Apple variants. The library must be specified as a CMake target name, a library file name (such as libfoo.a), or a library file path (such as /path/to/libfoo.a). Due to a limitation of the Apple linker, it cannot be specified as a plain library name like foo, where foo is not a CMake target.

• Windows. When using a MSVC or MSVC-like toolchain, the MSVC version must be greater than 1900.

• Cygwin.

• MSYS.

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.

FRAMEWORK

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

Added in version 3.25: The FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG> target property as well as the suffix of the framework library name are now supported by the FRAMEWORK features.

NEEDED_FRAMEWORK

This 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_FRAMEWORK

This 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_FRAMEWORK

This 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_LIBRARY

This is similar to the NEEDED_FRAMEWORK feature, except it is for use with non-framework targets or libraries. This feature is only supported on the following platforms:

Apple

Uses the -needed_library or -needed-l option as appropriate, with the same linker constraints as NEEDED_FRAMEWORK.

Linux

Added in version 4.5.

Wraps the library with --no-as-needed / --as-needed to force an entry in the binary's DT_NEEDED list regardless of whether any symbols from the library are directly referenced. When the linker supports --push-state / --pop-state (GNU ld >= 2.25, gold, LLD, MOLD), the state-stacking form is used instead to correctly restore the pre-existing --as-needed state rather than unconditionally enabling it after the library. This feature is only meaningful for shared libraries; applying it to a static library produces a developer warning and has no effect.

REEXPORT_LIBRARY

This 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_LIBRARY

This 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:

• CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED

• CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>

• CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED

• CMAKE_LINK_LIBRARY_USING_<FEATURE>

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:

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

2. 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. Any CMake target named in the library-list should be wrapped in TARGET_NAME so that its name is namespaced on export; otherwise it is exported verbatim and will not resolve as an imported target.

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