target_link_libraries

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

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

  • Связывание объектных библиотек через $<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.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 могут использоваться для указания как зависимостей прилинковки, так и интерфейса прилинковки в одной команде. Библиотеки и целевые объекты, следующие за 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) для обсуждения дополнительных мер предосторожности, которые необходимо принять при указании требований использования при создании пакетов для распространения.