target_link_libraries

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

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

Обзор

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

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

Именованный <target> должен быть создан в текущей директории командой, такой как add_executable() или add_library(), и не должен быть целевым объектом-псевдонимом. Повторные вызовы для одного и того же <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_FLAGS, чтобы добавить флаги связывания явно. Тогда флаги будут размещены в определенном инструментарием месте флагов в команде связывания.

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

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

Аргументы к target_link_libraries могут использовать «генераторские выражения» с синтаксисом $<...>. Однако обратите внимание, что генераторские выражения не будут использоваться в старой обработке CMP0003 или CMP0004. См. руководство cmake-generator-expressions(7) для доступных выражений. См. руководство 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).

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