target_link_libraries

• Обзор
• Библиотеки для целевого объекта и/или его зависимостей
• Библиотеки как для целевого объекта, так и для его зависимостей
• Библиотеки для целевого объекта и/или его зависимостей (устаревшая версия)
• Библиотеки только для зависимостей (устаревшая версия)

• Связывание объектных библиотек

  • Связывание объектных библиотек через $<TARGET_OBJECTS>
• Циклические зависимости статических библиотек
• Создание переносимых пакетов
• См. также

Укажите библиотеки или флаги, которые следует использовать при связывании данного целевого объекта и/или его зависимостей. Требования к использованию из связанных целевых библиотек будут распространены. Требования к использованию зависимостей целевого объекта влияют на компиляцию его собственных исходных кодов.

Обзор

Эта команда имеет несколько подписей, как подробно описано в подразделах ниже. Все они имеют общий вид

target_link_libraries(<target> ... <item>... ...)

Именованный <target> должен был быть создан командой, такой как add_executable() или add_library() и не должен быть целевым объектом-псевдонимом. Если политика CMP0079 не установлена в NEW, то целевой объект должен быть создан в текущем каталоге. Повторные вызовы для того же <target> добавляют элементы в порядке вызова.

Каждый <item> может быть:

• Имя целевого объекта библиотеки: Сгенерированная строка для связи будет содержать полный путь к файлу связуемой библиотеки, связанной с целевым объектом. Система построения будет иметь зависимость от повторной связи <target>, если файл библиотеки изменится.

  Именованный целевой объект должен быть создан командой add_library() в проекте или как импортированная библиотека. Если он создан в рамках проекта, в системе построения будет автоматически добавлена зависимость по порядку, чтобы убедиться, что именованный целевой объект библиотеки обновлен перед связыванием <target>.

  Если у импортированной библиотеки установлено свойство целевого объекта IMPORTED_NO_SONAME, CMake может попросить компоновщик найти библиотеку вместо использования полного пути (например, /usr/lib/libfoo.so становится -lfoo).

  Полный путь к артефакту целевого объекта будет автоматически заключен в кавычки/экранирован для оболочки.

• Полный путь к файлу библиотеки: Сгенерированная строка для связи обычно сохраняет полный путь к файлу. Система построения будет иметь зависимость от повторной связи <target>, если файл библиотеки изменится.

  В некоторых случаях CMake может попросить компоновщик найти библиотеку (например, /usr/lib/libfoo.so становится -lfoo), например, когда обнаружено, что у динамической библиотеки нет поля SONAME. См. политику CMP0060 для обсуждения другого случая.

  Если файл библиотеки находится в macOS-фреймворке, каталог Headers фреймворка также будет обрабатываться как требование к использованию. Это имеет тот же эффект, что и передача каталога фреймворка как каталога включаемых файлов.

  Добавлена в версии 3.28: Файл библиотеки может указывать на папку .xcframework на платформах Apple. Если это так, целевой объект получит каталог выбранной библиотеки Headers как требование к использованию.

  Добавлена в версии 3.8: В генераторах Visual Studio для VS 2010 и выше, файлы библиотек, заканчивающиеся на .targets, будут обрабатываться как файлы целей MSBuild и импортироваться в сгенерированные файлы проектов. Это не поддерживается другими генераторами.

  Полный путь к файлу библиотеки будет автоматически заключен в кавычки/экранирован для оболочки.

• Простое имя библиотеки: Сгенерированная строка для связи попросит компоновщик найти библиотеку (например, foo становится -lfoo или foo.lib).

  Имя/флаг библиотеки обрабатывается как фрагмент строки командной строки и будет использоваться без дополнительных кавычек или экранирования.

• Флаг связи: Имена элементов, начинающиеся с -, но не с -l или -framework, обрабатываются как флаги компоновщика. Обратите внимание, что такие флаги будут обрабатываться как любой другой элемент связи библиотек с точки зрения транзитивных зависимостей, поэтому они в целом безопасны для указания только как частных элементов связи, которые не будут распространяться на зависимые объекты.

  Флаги связи, указанные здесь, вставляются в команду связи в том же месте, что и элементы связи библиотек. Это может быть неверно в зависимости от компоновщика. Используйте свойство целевого объекта LINK_OPTIONS или команду target_link_options() для явного добавления флагов связи. Флаги затем будут размещены в определенном инструментом построения месте в команде связи.

  Добавлена в версии 3.13: Свойство целевого объекта LINK_OPTIONS и команда target_link_options(). Для более ранних версий CMake используйте свойство LINK_FLAGS вместо этого.

  Флаг связи обрабатывается как фрагмент строки командной строки и будет использоваться без дополнительных кавычек или экранирования.

• Выражение генератора: Выражение генератора $<...> generator expression может привести к любому из вышеперечисленных элементов или к списку, разделенному точкой с запятой этих элементов. Если выражение генератора содержит символы ;, например, после вычисления переменной ${list}, убедитесь, что вы используете явное аргумент в кавычках "$<...>", чтобы эта команда получила его как один <item>.

  Кроме того, выражение генератора может использоваться как фрагмент любого из вышеперечисленных элементов, например, foo$<1:_d>.

  Обратите внимание, что выражения генератора не будут использоваться в старой обработке политики CMP0003 или политики CMP0004.

• Ключевое слово debug, optimized, или general, за которым сразу следует другой <item>. Элемент, следующий за таким ключевым словом, будет использоваться только для соответствующей конфигурации построения. Ключевое слово debug соответствует конфигурации Debug (или конфигурациям, указанным в свойстве глобальной переменной DEBUG_CONFIGURATIONS, если оно установлено). Ключевое слово optimized соответствует всем другим конфигурациям. Ключевое слово general соответствует всем конфигурациям и является чисто необязательным. Для достижения большей точности в правилах для каждой конфигурации можно создавать и связывать импортированные целевые объекты библиотек.

Элементы, содержащие ::, такие как Foo::Bar, предполагаются импортированными или псевдонимами целевыми объектами библиотек и приведут к ошибке, если такой целевой объект не существует. См. политику CMP0028.

См. переменную CMAKE_LINK_LIBRARIES_STRATEGY и соответствующее свойство целевого объекта LINK_LIBRARIES_STRATEGY для получения подробной информации о том, как CMake упорядочивает прямые зависимости для связи в строках команд компоновщика.

См. руководство cmake-buildsystem(7) для получения дополнительной информации об определении свойств системы построения.

Библиотеки для целевого объекта и/или его зависимостей

target_link_libraries(<target>
                      <PRIVATE|PUBLIC|INTERFACE> <item>...
                     [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)

Ключевые слова PUBLIC, PRIVATE и INTERFACE scope могут использоваться для указания как зависимостей компоновки, так и интерфейса компоновки в одной команде.

Библиотеки и целевые объекты, следующие за PUBLIC, подключаются и становятся частью интерфейса компоновки. Библиотеки и целевые объекты, следующие за PRIVATE, подключаются, но не включаются в интерфейс компоновки. Библиотеки, следующие за INTERFACE, добавляются в интерфейс компоновки и не используются для компоновки <target>.

Библиотеки для целевого объекта и его зависимостей

target_link_libraries(<target> <item>...)

Зависимости библиотек по умолчанию являются транзитивными при использовании этого синтаксиса. Когда этот целевой объект подключается к другому целевому объекту, библиотеки, подключенные к этому целевому объекту, также появятся в строке компоновки другого целевого объекта. Этот транзитивный «интерфейс компоновки» хранится в свойстве целевого объекта INTERFACE_LINK_LIBRARIES и может быть переопределён путём непосредственного задания свойства. Когда CMP0022 не установлено в NEW, транзитивная компоновка включена, но может быть переопределена свойством LINK_INTERFACE_LIBRARIES. Вызовы других синтаксических конструкций этой команды могут задать свойство, сделав любые библиотеки, подключенные исключительно по этому синтаксису, закрытыми.

Библиотеки для целевого объекта и/или его зависимостей (устаревшее)

target_link_libraries(<target>
                      <LINK_PRIVATE|LINK_PUBLIC> <lib>...
                     [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)

Режимы LINK_PUBLIC и LINK_PRIVATE могут быть использованы для указания как зависимостей компоновки, так и интерфейса компоновки в одной команде.

Этот синтаксис предназначен только для совместимости. Предпочтительнее использовать ключевые слова PUBLIC или PRIVATE.

Библиотеки и целевые объекты, следующие за LINK_PUBLIC, подключаются и включаются в INTERFACE_LINK_LIBRARIES. Если политика CMP0022 не установлена в NEW, они также включаются в LINK_INTERFACE_LIBRARIES. Библиотеки и целевые объекты, следующие за LINK_PRIVATE, подключаются, но не включаются в INTERFACE_LINK_LIBRARIES (или LINK_INTERFACE_LIBRARIES).

Библиотеки только для зависимостей (устаревшее)

target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)

Режим LINK_INTERFACE_LIBRARIES добавляет библиотеки в свойство целевого объекта INTERFACE_LINK_LIBRARIES вместо их использования для компоновки. Если политика CMP0022 не установлена в NEW, этот режим также добавляет библиотеки в LINK_INTERFACE_LIBRARIES и его эквивалент для каждой конфигурации.

Этот синтаксис предназначен только для совместимости. Предпочтительнее использовать режим INTERFACE.

Библиотеки, указанные как debug оборачиваются в генераторское выражение для соответствия сборке для отладки. Если политика CMP0022 не установлена в NEW, библиотеки также добавляются в свойство LINK_INTERFACE_LIBRARIES_DEBUG (или в свойства, соответствующие конфигурациям, перечисленным в глобальном свойстве DEBUG_CONFIGURATIONS, если оно задано). Библиотеки, указанные как optimized добавляются в свойство INTERFACE_LINK_LIBRARIES. Если политика CMP0022 не установлена в NEW, они также добавляются в LINK_INTERFACE_LIBRARIES. Библиотеки, указанные как general (или без ключевого слова), обрабатываются так, как если бы они были указаны как для debug, так и для optimized.

Связывание библиотек объектов

Библиотеки объектов могут использоваться в качестве аргумента <target> (первого) в target_link_libraries для указания зависимостей их источников от других библиотек. Например, код

add_library(A SHARED a.c)
target_compile_definitions(A PUBLIC A)

add_library(obj OBJECT obj.c)
target_compile_definitions(obj PUBLIC OBJ)
target_link_libraries(obj PUBLIC A)

компилирует obj.c с -DA -DOBJ и устанавливает требования к использованию obj, которые распространяются на его зависимые объекты.

Обычные библиотеки и исполняемые файлы могут подключаться к библиотекам объектов для получения их объектов и требований к использованию. Продолжая пример выше, код

add_library(B SHARED b.c)
target_link_libraries(B PUBLIC obj)

компилирует b.c с -DA -DOBJ, создаёт динамическую библиотеку B с объектами из b.c и obj.c, и подключает B к A.

Кроме того, код

add_executable(main main.c)
target_link_libraries(main B)

компилирует main.c с -DA -DOBJ и подключает исполняемый файл main к B и A.

Требования к использованию библиотеки объектов распространяются транзитивно через B, но её объектные файлы не включаются.

Библиотеки объектов могут «подключаться» к другим библиотекам объектов для получения требований к использованию, но поскольку у них нет шага компоновки, с их объектами файлами ничего не делается. Продолжая пример выше, код:

add_library(obj2 OBJECT obj2.c)
target_link_libraries(obj2 PUBLIC obj)

add_executable(main2 main2.c)
target_link_libraries(main2 obj2)

компилирует obj2.c с -DA -DOBJ, создаёт исполняемый файл main2 с объектами из main2.c и obj2.c, и подключает main2 к A.

Другими словами, когда Библиотеки объектов появляются в свойстве INTERFACE_LINK_LIBRARIES целевого объекта, они будут обрабатываться как Библиотеки интерфейса, но когда они появляются в свойстве LINK_LIBRARIES целевого объекта, их объектные файлы также будут включены в компоновку.

Связывание библиотек объектов через $<TARGET_OBJECTS>

Объектные файлы, связанные с библиотекой объектов, могут быть обработаны с помощью генераторского выражения $<TARGET_OBJECTS>. Такие объектные файлы размещаются в строке компоновки перед всеми библиотеками, независимо от их относительного порядка. Кроме того, в систему сборки будет добавлена зависимость порядка, чтобы убедиться, что библиотека объектов обновлена перед подключением зависимого целевого объекта. Например, код

add_library(obj3 OBJECT obj3.c)
target_compile_definitions(obj3 PUBLIC OBJ3)

add_executable(main3 main3.c)
target_link_libraries(main3 PRIVATE a3 $<TARGET_OBJECTS:obj3> b3)

подключает исполняемый файл main3 с объектами из main3.c и obj3.c, за которым следуют библиотеки a3 и b3.

main3.c не компилируется с требованиями к использованию от obj3, таких как -DOBJ3.

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

add_library(iface_obj3 INTERFACE)
target_link_libraries(iface_obj3 INTERFACE obj3 $<TARGET_OBJECTS:obj3>)

создаёт библиотеку интерфейса iface_obj3, которая передаёт требования к использованию obj3 и добавляет объектные файлы obj3 в строки компоновки зависимых объектов.

Код

add_executable(use_obj3 use_obj3.c)
target_link_libraries(use_obj3 PRIVATE iface_obj3)

компилирует use_obj3.c с -DOBJ3 и подключает исполняемый файл use_obj3 с объектами из use_obj3.c и obj3.c.

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

add_library(static3 STATIC static3.c)
target_link_libraries(static3 PRIVATE iface_obj3)

add_executable(use_static3 use_static3.c)
target_link_libraries(use_static3 PRIVATE static3)

компилирует static3.c с -DOBJ3 и создаёт libstatic3.a только с собственным объектным файлом.

use_static3.c компилируется без -DOBJ3, так как требование к использованию не транзитивно через закрытую зависимость static3.

Однако, зависимости компоновки static3 распространяются, включая ссылку iface_obj3 на $<TARGET_OBJECTS:obj3>.

Исполняемый файл use_static3 создаётся с объектами из use_static3.c и obj3.c, и подключается к библиотеке libstatic3.a.

При использовании этого подхода, проект обязан избегать связывания нескольких зависимых библиотек с iface_obj3, поскольку все они получат obj3 файлы объектов в своих строках линковки.

Циклические зависимости статических библиотек

Граф зависимостей библиотек обычно является ациклическим (DAG), но в случае взаимно-зависимых STATIC библиотек CMake разрешает графу содержать циклы (сильно связанные компоненты). Когда другой целевой элемент связывается с одной из библиотек, CMake повторяет весь связанный компонент. Например, код

add_library(A STATIC a.c)
add_library(B STATIC b.c)
target_link_libraries(A B)
target_link_libraries(B A)
add_executable(main main.c)
target_link_libraries(main A)

связывает main с A B A B. В то время как одно повторение обычно достаточно, патологические расположения файлов объектов и символов могут потребовать больше. Можно обрабатывать такие случаи, используя свойство целевого элемента LINK_INTERFACE_MULTIPLICITY или вручную повторяя компонент в последнем target_link_libraries вызове. Однако, если две архивы действительно настолько взаимозависимы, они, вероятно, должны быть объединены в один архив, возможно, используя Объектные библиотеки.

Создание переносимых пакетов

Обратите внимание, что не рекомендуется заполнять INTERFACE_LINK_LIBRARIES целевого элемента абсолютными путями к зависимостям. Это жестко закодирует в установленных пакетах пути к файлам библиотек для зависимостей так, как они найдены на машине, на которой был создан пакет.

См. раздел Создание переносимых пакетов руководства cmake-packages(7) для обсуждения дополнительной осторожности, которая должна быть соблюдена при указании требований к использованию при создании пакетов для распространения.

См. также

• target_compile_definitions()
• target_compile_features()
• target_compile_options()
• target_include_directories()
• target_link_directories()
• target_link_options()
• target_precompile_headers()
• target_sources()