target_link_libraries

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

• Компоновка объектных библиотек

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

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

Обзор

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

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

Указанная <target> должна быть создана такой командой, как add_executable() или add_library(), и не должна быть целью ALIAS. Если политика 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. Для обсуждения другого случая в версиях CMake до 4.0 см. политику CMP0060.

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

  Добавлено в версии 3.28: На платформах Apple файл библиотеки может указывать на папку .xcframework. В этом случае каталог 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>.

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

  В качестве альтернативы генераторные выражения, например $<CONFIG>, позволяют точнее настраивать компоновку <item> для каждой конфигурации. Для более структурированного подхода можно добиться большей детализации, создав и связав импортированные целевые библиотеки со свойством IMPORTED_CONFIGURATIONS, особенно в модулях поиска.

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

Подробные сведения о порядке размещения CMake прямых зависимостей компоновки в командных строках компоновщика см. в переменной CMAKE_LINK_LIBRARIES_STRATEGY и соответствующем свойстве цели LINK_LIBRARIES_STRATEGY.

Дополнительные сведения об определении свойств системы сборки см. в руководстве cmake-buildsystem(7).

Обработка различий драйверов компилятора

У каждого драйвера компилятора свой синтаксис передачи параметров инструменту компоновщика. Для переносимого указания параметров, передаваемых инструменту компоновщика, можно использовать префикс LINKER: и разделитель ,. LINKER: заменяется соответствующим параметром драйвера, а , — соответствующим разделителем драйвера. Префикс и разделитель драйвера задаются значениями переменных CMAKE_<LANG>_LINKER_WRAPPER_FLAG и CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP.

Например, "LINKER:-z,defs" превращается в -Xlinker -z -Xlinker defs для Clang и в -Wl,-z,defs для GNU GCC.

В качестве альтернативного синтаксиса префикс LINKER: поддерживает указание аргументов с помощью префикса SHELL: и пробела в качестве разделителя. Тогда предыдущий пример принимает вид "LINKER:SHELL:-z defs".

Библиотеки для цели и/или её зависимых целей

target_link_libraries(<target>
  {INTERFACE|PUBLIC|PRIVATE} <item>...
  [{INTERFACE|PUBLIC|PRIVATE} <item>...]...)

Ключевые слова области видимости scope PUBLIC, PRIVATE и INTERFACE позволяют одной командой указать как зависимости компоновки, так и интерфейс компоновки.

Библиотеки и цели после PUBLIC участвуют в компоновке и включаются в интерфейс компоновки. Библиотеки и цели после PRIVATE участвуют в компоновке, но не включаются в интерфейс компоновки. Библиотеки после INTERFACE добавляются в интерфейс компоновки и не используются для компоновки <target>.

Библиотеки и для цели, и для её зависимых целей

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

При использовании этой сигнатуры зависимости библиотек по умолчанию являются транзитивными. Если эта цель включается в другую цель, связанные с ней библиотеки также появятся в строке компоновки другой цели. Этот транзитивный «интерфейс компоновки» хранится в свойстве цели INTERFACE_LINK_LIBRARIES; его можно переопределить, задав свойство напрямую.

В версиях CMake до 4.0, если политика CMP0022 не установлена в NEW, транзитивная компоновка включена, но может быть переопределена свойством LINK_INTERFACE_LIBRARIES. Вызовы других сигнатур этой команды могут задавать это свойство, делая все библиотеки, связанные исключительно этой сигнатурой, приватными.

Библиотеки для цели и/или её зависимых целей (устаревший вариант)

Эта сигнатура оставлена только для совместимости. Вместо неё предпочтительно использовать ключевые слова PUBLIC или PRIVATE.

target_link_libraries(<target>
                      <LINK_PRIVATE|LINK_PUBLIC> <lib>...
                     [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)

Режимы LINK_PUBLIC и LINK_PRIVATE позволяют одной командой указать как зависимости компоновки, так и интерфейс компоновки.

Библиотеки и цели после LINK_PUBLIC участвуют в компоновке и включаются в INTERFACE_LINK_LIBRARIES.

В версиях CMake до 4.0, если политика CMP0022 не установлена в NEW, они также включаются в LINK_INTERFACE_LIBRARIES. Библиотеки и цели после LINK_PRIVATE участвуют в компоновке, но не включаются в INTERFACE_LINK_LIBRARIES (или LINK_INTERFACE_LIBRARIES).

Библиотеки только для зависимых целей (устаревший вариант)

Эта сигнатура оставлена только для совместимости. Вместо неё предпочтительно использовать режим INTERFACE.

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

Режим LINK_INTERFACE_LIBRARIES добавляет библиотеки в свойство цели INTERFACE_LINK_LIBRARIES, а не использует их для компоновки.

В версиях CMake до 4.0, если политика CMP0022 не установлена в NEW, этот режим также добавляет библиотеки в LINK_INTERFACE_LIBRARIES и соответствующее свойство для отдельных конфигураций.

Компоновка объектных библиотек

Объектные библиотеки можно использовать в качестве аргумента <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()