target_link_libraries

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

• Создание ссылок на библиотеки объектов

  • Создание ссылок на библиотеки объектов через $<TARGET_OBJECTS>
• Циклические зависимости статических библиотек
• Создание переносимых пакетов
• См. также

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

Обзор

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

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

См. также

• target_compile_definitions()
• target_compile_features()
• target_compile_options()
• target_include_directories()
• target_link_directories()
• target_link_options()
• target_precompile_headers()
• target_sources()