target_link_libraries

• Обзор
• Библиотеки для целевого объекта и/или его зависимостей
• Библиотеки для целевого объекта и его зависимостей
• Библиотеки для целевого объекта и/или его зависимостей (устаревшее)
• Библиотеки только для зависимостей (устаревшее)
• Связывание библиотек объектов
• Циклические зависимости статических библиотек
• Создание переносимых пакетов

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

Обзор

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

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 для обсуждения другого случая.

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

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

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

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

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

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

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

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

• Выражение генератора: $<...> 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. Вызовы других сигнатур этой команды могут устанавливать свойство, делая любые библиотеки, связанные исключительно по этому сигнутуру, приватными.

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

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

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

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

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

Граф зависимостей библиотек обычно является ациклическим (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) для обсуждения дополнительной осторожности, которая должна быть соблюдена при указании требований к использованию при создании пакетов для перераспределения.