target_link_libraries

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

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

Обзор

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

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

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