INTERFACE_LINK_LIBRARIES_DIRECT

Список библиотек, которые потребители этой библиотеки должны рассматривать как прямые зависимости.

Это свойство целевого объекта может быть установлено для включения элементов в конечный набор прямых зависимостей целевого объекта-зависимости. См. свойство целевого объекта INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE для исключения элементов.

Начальный набор прямых зависимостей целевого объекта-зависимости задается его свойством целевого объекта LINK_LIBRARIES. Косвенные зависимости задаются транзитивным замыканием прямых зависимостей, указанных свойствами INTERFACE_LINK_LIBRARIES. Любая зависимость может указать дополнительные прямые зависимости с помощью свойства INTERFACE_LINK_LIBRARIES_DIRECT. Затем набор прямых зависимостей фильтруется для исключения элементов, указанных в свойстве INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE целевого объекта любой зависимости.

Значение INTERFACE_LINK_LIBRARIES_DIRECT может использовать generator expressions.

Прямые зависимости как требования использования

Свойства INTERFACE_LINK_LIBRARIES_DIRECT и INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE являются требованиями использования. Их эффекты распространяются на зависимые целевые объекты транзитивно и, следовательно, могут влиять на прямые зависимости каждого целевого объекта в цепочке зависимых библиотек. Всякий раз, когда целевой объект некоторой библиотеки X ссылается на другой целевой объект библиотеки 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 помещается в INTERFACE_LINK_LIBRARIES X, поэтому требования использования Y, включая INTERFACE_LINK_LIBRARIES_DIRECT, INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE, и требования использования, объявленные прямыми зависимостями, которые они добавляют, распространяются на зависимые целевые объекты X.

• Если X является статической библиотекой или библиотекой объектов и скрыто подключает Y:

  target_link_libraries(X PRIVATE Y)
  

  тогда $<LINK_ONLY:Y> помещается в INTERFACE_LINK_LIBRARIES X. Требования подключения Y , включая INTERFACE_LINK_LIBRARIES_DIRECT, INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE, и транзитивные зависимости подключения, объявленные прямыми зависимостями, которые они добавляют, распространяются на зависимые целевые объекты X . Однако требования использования Y без подключения блокируются генератором выражения LINK_ONLY и не распространяются на зависимые целевые объекты X.

• Если X является общей библиотекой или исполняемым файлом и скрыто подключает Y:

  target_link_libraries(X PRIVATE Y)
  

  тогда Y не помещается в INTERFACE_LINK_LIBRARIES X, поэтому требования использования Y, даже INTERFACE_LINK_LIBRARIES_DIRECT и INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE, не распространяются на зависимые целевые объекты X.

• Во всех случаях содержимое INTERFACE_LINK_LIBRARIES X не изменяется требованиями использования Y или INTERFACE_LINK_LIBRARIES_DIRECT INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE.

Можно ограничить действие INTERFACE_LINK_LIBRARIES_DIRECT и INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE подмножеством зависимых целевых объектов, используя генератор выражения TARGET_PROPERTY. Например, для ограничения действия на исполняемые целевые объекты используйте запись следующего формата:

"$<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:...>"

Аналогично, для ограничения действия на определённые целевые объекты используйте запись следующего формата:

"$<$<BOOL:$<TARGET_PROPERTY:USE_IT>>:...>"

Эта запись будет влиять только на целевые объекты, которые установили своё свойство целевого объекта USE_IT в истинное значение.

Порядок прямых зависимостей подключения

Список прямых зависимостей подключения для целевого объекта вычисляется из начального упорядоченного списка в его свойстве целевого объекта LINK_LIBRARIES. Для каждого элемента обнаруживаются дополнительные прямые зависимости от его прямых и транзитивных требований использования INTERFACE_LINK_LIBRARIES_DIRECT. Каждый обнаруженный элемент вставляется перед элементом, который его указал. Однако обнаруженный элемент добавляется не более одного раза, и только если он не появлялся нигде в начальном списке. Это даёт LINK_LIBRARIES контроль над порядком тех прямых зависимостей подключения, которые он явно указывает.

После того, как все прямые зависимости подключения будут собраны, элементы, указанные во всех их требованиях использования INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE, удаляются из конечного списка. Это не влияет на порядок оставшихся элементов.

Пример: Статические плагины

Рассмотрим статическую библиотеку Foo, которая предоставляет статический плагин FooPlugin для исполняемых файлов-потребителей, где реализация плагина зависит от Foo и других вещей. В этом случае приложение должно напрямую подключаться к FooPlugin перед Foo . Однако автору приложения известно только о 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)

Свойство INTERFACE_LINK_LIBRARIES_DIRECT целевого объекта Foo сообщает CMake, что app также напрямую подключается к FooPlugin . Свойство целевого объекта INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE целевого объекта Foo сообщает 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.