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.