INTERFACE_LINK_LIBRARIES_DIRECT¶
在 3.24 版本中添加。
此属性是一个列表,其中包含此库的消费者应视为直接链接依赖项的库。
此目标属性可以设置为在依赖目标的最终直接链接依赖项集中*包含*项。请参阅 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
目标属性以排除项。
依赖目标的初始直接链接依赖项集由其 LINK_LIBRARIES
目标属性指定。间接链接依赖项由直接链接依赖项的 INTERFACE_LINK_LIBRARIES
属性的传递闭包指定。任何链接依赖项都可以使用 INTERFACE_LINK_LIBRARIES_DIRECT
目标属性指定附加的直接链接依赖项。然后对直接链接依赖项集进行过滤,以排除任何依赖项的 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
目标属性中命名的项。
INTERFACE_LINK_LIBRARIES_DIRECT
的值可以使用 生成器表达式
。
注意
INTERFACE_LINK_LIBRARIES_DIRECT
目标属性旨在用于高级用例,例如将静态插件注入到消费可执行文件中。它不应被用作组织对 target_link_libraries()
的常规调用的替代。
直接链接依赖项作为使用要求¶
INTERFACE_LINK_LIBRARIES_DIRECT
和 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
目标属性是 使用要求。它们的效果会传递性地传播到依赖目标,因此可以影响依赖库链中每个目标的直接链接依赖项。每当某些库目标 X
链接到另一个库目标 Y
,而 Y
的直接或传递使用要求包含 INTERFACE_LINK_LIBRARIES_DIRECT
或 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
时,这些属性可能会影响 X
的直接链接依赖项列表。
如果
X
是共享库或可执行文件,则其依赖项会被链接。它们还会影响编译X
源文件的使用要求。如果
X
是静态库或对象库,它实际上不进行链接,因此其依赖项至多影响编译X
源文件的使用要求。
这些属性也可能影响 X
依赖项的直接链接依赖项列表。
如果
X
公开链接Y
target_link_libraries(X PUBLIC Y)
则
Y
被放置在X
的INTERFACE_LINK_LIBRARIES
中,因此Y
的使用要求,包括INTERFACE_LINK_LIBRARIES_DIRECT
、INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
以及它们添加的直接链接依赖项声明的使用要求,会传播到X
的依赖项。如果
X
是静态库或对象库,并且私有链接Y
target_link_libraries(X PRIVATE Y)
则
$<LINK_ONLY:Y>
被放置在X
的INTERFACE_LINK_LIBRARIES
中。Y
的链接要求,包括INTERFACE_LINK_LIBRARIES_DIRECT
、INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
以及它们添加的直接链接依赖项声明的传递链接依赖项,会传播到X
的依赖项。但是,Y
的非链接使用要求被LINK_ONLY
生成器表达式阻止,并且不会传播到X
的依赖项。如果
X
是共享库或可执行文件,并且私有链接Y
target_link_libraries(X PRIVATE Y)
则
Y
不被放置在X
的INTERFACE_LINK_LIBRARIES
中,因此Y
的使用要求,即使是INTERFACE_LINK_LIBRARIES_DIRECT
和INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
,也不会传播到X
的依赖项。在所有情况下,
X
的INTERFACE_LINK_LIBRARIES
的内容不受Y
的INTERFACE_LINK_LIBRARIES_DIRECT
或INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
的影响。
可以使用 TARGET_PROPERTY
生成器表达式将 INTERFACE_LINK_LIBRARIES_DIRECT
和 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
的效果限制为依赖目标的子集。例如,要将效果限制为可执行目标,请使用以下形式的条目:
"$<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:...>"
同样,要将效果限制为特定目标,请使用以下形式的条目:
"$<$<BOOL:$<TARGET_PROPERTY:USE_IT>>:...>"
此条目只会影响将其 USE_IT
目标属性设置为 true 值的目标。
直接链接依赖项排序¶
目标的直接链接依赖项列表是根据其 LINK_LIBRARIES
目标属性中的初始有序列表计算的。对于每个项,从其直接和传递的 INTERFACE_LINK_LIBRARIES_DIRECT
使用要求中发现附加的直接链接依赖项。每个发现的项都会在其指定它的项之前注入。但是,发现的项最多添加一次,并且仅当它未出现在初始列表中的任何位置时才添加。这使得 LINK_LIBRARIES
可以控制其明确指定的那些直接链接依赖项的排序。
一旦收集了所有直接链接依赖项,将从最终列表中移除所有 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
使用要求中命名的项。这不会影响保留项的顺序。
示例:静态插件¶
考虑一个静态库 Foo
,它为消费应用程序可执行文件提供一个静态插件 FooPlugin
,其中插件的实现依赖于 Foo
和其他东西。在这种情况下,应用程序应该在 Foo
之前直接链接到 FooPlugin
。但是,应用程序作者只知道 Foo
。我们可以这样表达:
# Core library used by other components.
add_library(Core STATIC core.cpp)
# Foo is a static library for use by applications.
# Implementation of Foo depends on Core.
add_library(Foo STATIC foo.cpp foo_plugin_helper.cpp)
target_link_libraries(Foo PRIVATE Core)
# Extra parts of Foo for use by its static plugins.
# Implementation of Foo's extra parts depends on both Core and Foo.
add_library(FooExtras STATIC foo_extras.cpp)
target_link_libraries(FooExtras PRIVATE Core Foo)
# The Foo library has an associated static plugin
# that should be linked into the final executable.
# Implementation of the plugin depends on Core, Foo, and FooExtras.
add_library(FooPlugin STATIC foo_plugin.cpp)
target_link_libraries(FooPlugin PRIVATE Core Foo FooExtras)
# An app that links Foo should link Foo's plugin directly.
set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT FooPlugin)
# An app does not need to link Foo directly because the plugin links it.
set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE Foo)
应用程序 app
只需指定它链接到 Foo
add_executable(app main.cpp)
target_link_libraries(app PRIVATE Foo)
Foo
上的 INTERFACE_LINK_LIBRARIES_DIRECT
目标属性告诉 CMake 假装 app
也直接链接到 FooPlugin
。Foo
上的 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
目标属性告诉 CMake 假装 app
*未*直接链接到 Foo
。相反,Foo
将作为 FooPlugin
的依赖项进行链接。app
的最终链接行将按以下顺序链接库:
FooPlugin
作为app
的直接链接依赖项(通过Foo
的使用要求)。FooExtras
作为FooPlugin
的依赖项。Foo
作为FooPlugin
和FooExtras
的依赖项。Core
作为FooPlugin
、FooExtras
和Foo
的依赖项。
请注意,如果没有 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
目标属性,Foo
将被链接两次:一次作为 app
的直接依赖项,另一次作为 FooPlugin
的依赖项。
示例:可选静态插件¶
在上面的 示例:静态插件 中,app
可执行文件指定它直接链接到 Foo
。在实际应用程序中,可能有一个中间库
add_library(app_impl STATIC app_impl.cpp)
target_link_libraries(app_impl PRIVATE Foo)
add_executable(app main.cpp)
target_link_libraries(app PRIVATE app_impl)
在这种情况下,我们不希望 Foo
的 INTERFACE_LINK_LIBRARIES_DIRECT
和 INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
目标属性影响 app_impl
的直接依赖项。为避免这种情况,我们可以修改属性值以使其效果可选:
# An app that links Foo should link Foo's plugin directly.
set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT
"$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:FooPlugin>"
)
# An app does not need to link Foo directly because the plugin links it.
set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
"$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:Foo>"
)
现在,app
可执行文件可以选择获取 Foo
的插件:
set_property(TARGET app PROPERTY FOO_STATIC_PLUGINS 1)
现在,app
的最终链接行将按以下顺序链接库:
FooPlugin
作为app
的直接链接依赖项(通过Foo
的使用要求)。app_impl
作为app
的直接链接依赖项。FooExtras
作为FooPlugin
的依赖项。Foo
作为app_impl
、FooPlugin
和FooExtras
的依赖项。Core
作为FooPlugin
、FooExtras
和Foo
的依赖项。