target_link_libraries

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

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

  • Связывание объектных библиотек через $<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.28: Файл библиотеки может указывать на папку .xcframework на платформах Apple. Если это так, целевой объект получит каталог выбранной библиотеки 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_LINK_LIBRARIES_STRATEGY и соответствующее свойство целевого объекта LINK_LIBRARIES_STRATEGY для получения подробной информации о том, как CMake упорядочивает прямые зависимости от связывания в строке комманд линковщика.

См. руководство 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()