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-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()