CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>

Эта переменная определяет, как следует связывать библиотеку или фреймворк для указанного <FEATURE> при использовании выражения генератора LINK_LIBRARY, если язык связи для целевого объекта — <LANG>. Для того, чтобы эта переменная имела какой-либо эффект, связанная переменная CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED должна быть установлена в true.

Переменная CMAKE_LINK_LIBRARY_USING_<FEATURE> должна быть определена для функций, не зависящих от языка связи.

Имена функций чувствительны к регистру и могут содержать только буквы, цифры и символы подчеркивания. Имена функций, определенные в верхнем регистре, зарезервированы для собственных встроенных функций CMake (см. Предопределённые функции ниже).

Определения функций

Определение функции библиотеки — это список, содержащий один или три элемента:

[<PREFIX>] <LIBRARY_EXPRESSION> [<SUFFIX>]

Когда <PREFIX> и <SUFFIX> указаны, они предшествуют и следуют соответственно всему списку библиотек, указанных в выражении LINK_LIBRARY, а не каждой библиотеке по отдельности. Однако нет гарантии, что список указанных библиотек будет оставаться сгруппированным, поэтому <PREFIX> и <SUFFIX> могут появляться более одного раза, если список библиотек будет переупорядочен CMake для удовлетворения других ограничений. Это означает, что конструкции, такие как --start-group и --end-group, поддерживаемые линковщиком GNU ld, не могут использоваться таким образом. Вместо этого следует использовать выражение генератора LINK_GROUP.

<LIBRARY_EXPRESSION> используется для указания шаблона для построения соответствующего фрагмента в командной строке линковщика для каждой библиотеки. В выражении можно использовать следующие плейсхолдеры:

• <LIBRARY> расширяется до полного пути к библиотеке для целевых объектов CMake или до платформозависимого значения в зависимости от элемента (то же, что и <LINK_ITEM> в Windows или имя базовой библиотеки для других платформ).
• <LINK_ITEM> расширяется до того, как библиотека обычно связывается в командной строке линковщика.
• <LIB_ITEM> расширяется до полного пути к библиотеке для целевых объектов CMake или самого элемента точно так, как он указан в <LIBRARY_EXPRESSION> в противном случае.

В дополнение к вышесказанному, возможно иметь один шаблон для путей (целевые объекты CMake и внешние библиотеки, указанные с путями к файлам) и другой для других элементов, указанных только по имени. Обёртки PATH{} и NAME{} могут быть использованы для предоставления расширения для этих двух случаев соответственно. При использовании обёрток, обе должны быть присутствовать. Например:

set(CMAKE_LINK_LIBRARY_USING_weak_library
    "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}"
)

Для всех трёх элементов этой переменной (<PREFIX>, <LIBRARY_EXPRESSION>, и <SUFFIX>) может использоваться префикс LINKER:.

Для передачи опций линковщику, каждый компилятор имеет собственную синтаксическую конструкцию. Префикс 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: и пробела в качестве разделителя. Тогда предыдущий пример станет "LINKER:SHELL:-z defs".

Примеры

Загрузка всей статической библиотеки

Частой потребностью является предотвращение отбрасывания линковщиком каких-либо символов из статической библиотеки. Разные линковщики используют различные синтаксические конструкции для достижения этого. Следующий пример демонстрирует, как это может быть реализовано для некоторых линковщиков. Обратите внимание, что это только для иллюстративных целей. Проекты должны использовать встроенную функцию WHOLE_ARCHIVE вместо этого (см. Предопределённые функции), которая обеспечивает более полную и надёжную реализацию этой функциональности.

set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED TRUE)
if(CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
  set(CMAKE_C_LINK_LIBRARY_USING_load_archive "-force_load <LIB_ITEM>")
elseif(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
  set(CMAKE_C_LINK_LIBRARY_USING_load_archive
    "LINKER:--push-state,--whole-archive"
    "<LINK_ITEM>"
    "LINKER:--pop-state"
  )
elseif(CMAKE_C_COMPILER_ID STREQUAL "MSVC")
  set(CMAKE_C_LINK_LIBRARY_USING_load_archive "/WHOLEARCHIVE:<LIBRARY>")
else()
  # feature not yet supported for the other environments
  set(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED FALSE)
endif()

add_library(lib1 STATIC ...)
add_library(lib2 SHARED ...)

if(CMAKE_C_LINK_LIBRARY_USING_load_archive_SUPPORTED)
  # The -force_load Apple linker option requires a file name
  set(external_lib
    "$<IF:$<LINK_LANG_AND_ID:C,AppleClang>,libexternal.a,external>"
  )
  target_link_libraries(lib2 PRIVATE
    "$<LINK_LIBRARY:load_archive,lib1,${external_lib}>"
  )
else()
  target_link_libraries(lib2 PRIVATE lib1 external)
endif()

CMake сгенерирует следующие выражения связи:

• AppleClang: -force_load /path/to/lib1.a -force_load libexternal.a
• GNU: -Wl,--push-state,--whole-archive /path/to/lib1.a -lexternal -Wl,--pop-state
• MSVC: /WHOLEARCHIVE:/path/to/lib1.lib /WHOLEARCHIVE:external.lib

Связывание библиотеки как слабой

В macOS возможно связывание библиотеки в слабом режиме (библиотека и все ссылки помечены как слабые импорты). Для библиотеки, указанной по пути к файлу, необходимо использовать другие флаги, чем для библиотеки, указанной по имени. Это ограничение может быть решено с помощью обёрток PATH{} и NAME{} . Опять же, следующий пример демонстрирует, как это может быть реализовано для некоторых линковщиков, но он только для иллюстративных целей. Проекты должны использовать встроенные функции WEAK_FRAMEWORK или WEAK_LIBRARY вместо этого (см. Предопределённые функции), которые обеспечивают более полную и надёжную реализацию этой функциональности.

if (CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
  set(CMAKE_LINK_LIBRARY_USING_weak_library
      "PATH{-weak_library <LIBRARY>}NAME{LINKER:-weak-l<LIB_ITEM>}"
  )
  set(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED TRUE)
endif()

add_library(lib SHARED ...)
add_executable(main ...)
if(CMAKE_LINK_LIBRARY_USING_weak_library_SUPPORTED)
  target_link_libraries(main PRIVATE "$<LINK_LIBRARY:weak_library,lib,external>")
else()
  target_link_libraries(main PRIVATE lib external)
endif()

CMake сгенерирует следующий фрагмент командной строки линковщика при связывании main с помощью инструментальной цепочки AppleClang:

-weak_library /path/to/lib -Xlinker -weak-lexternal.

Предопределённые функции

Следующие встроенные функции библиотек предопределены CMake:

DEFAULT

Эта функция соответствует стандартному связыванию, по сути, эквивалентному использованию без каких-либо дополнительных функций. Она обычно используется только с целевыми свойствами LINK_LIBRARY_OVERRIDE и LINK_LIBRARY_OVERRIDE_<LIBRARY>.

WHOLE_ARCHIVE

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

• Linux.
• Все варианты BSD.
• SunOS.
• Все варианты Apple. Библиотека должна быть указана как имя целевого объекта CMake, имя файла библиотеки (например, libfoo.a), или путь к файлу библиотеки (например, /path/to/libfoo.a). Из-за ограничения Apple linker, она не может быть указана как простое имя библиотеки, например, foo, где foo не является целевым объектом CMake.
• Windows. При использовании MSVC или подобной цепочки инструментов, версия MSVC должна быть больше 1900.
• Cygwin.
• MSYS.

FRAMEWORK

Этот параметр сообщает linker о поиске указанной фреймворка с использованием параметра linker -framework. Он может быть использован только на платформах Apple и только с linker, понимающим используемый параметр (например, linker, предоставляемый Xcode, или совместимый с ним).

Фреймворк может быть указан как целевой объект CMake фреймворка, простое имя фреймворка или путь к файлу. Если задан целевой объект, для этого объекта должно быть установлено свойство целевого объекта FRAMEWORK в значение true. Для пути к файлу, если он содержит часть директории, эта директория будет добавлена в путь поиска фреймворка.

add_library(lib SHARED ...)
target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:FRAMEWORK,/path/to/my_framework>")

# The constructed linker command line will contain:
#   -F/path/to -framework my_framework

Пути к файлам должны соответствовать одному из следующих шаблонов (* — символ подстановки, а необязательные части показаны как [...]):

• [/path/to/]FwName[.framework]
• [/path/to/]FwName.framework/FwName[suffix]
• [/path/to/]FwName.framework/Versions/*/FwName[suffix]

Обратите внимание, что CMake распознаёт и автоматически обрабатывает целевые объекты фреймворка, даже без использования выражения $<LINK_LIBRARY:FRAMEWORK,...>. Выражение генератора все еще может использоваться с целевым объектом CMake, если проект хочет явно указать это, но это не обязательно. Командная строка linker может иметь некоторые различия при использовании выражения генератора или без него, но конечный результат должен быть одинаковым. С другой стороны, если задан путь к файлу, CMake распознает некоторые пути автоматически, но не все случаи. Проект может использовать $<LINK_LIBRARY:FRAMEWORK,...> для путей к файлам, чтобы ожидаемое поведение было ясным.

Добавлена в версии 3.25: Теперь свойство целевого объекта FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>, а также suffix имени библиотеки фреймворка поддерживаются функциями FRAMEWORK.

NEEDED_FRAMEWORK

Это аналогично функции FRAMEWORK, за исключением того, что она принуждает linker связывать с фреймворком даже если из него не используются какие-либо символы. Она использует параметр -needed_framework и имеет те же ограничения linker, что и FRAMEWORK.

REEXPORT_FRAMEWORK

Это аналогично функции FRAMEWORK, за исключением того, что она сообщает linker о том, что фреймворк должен быть доступен клиентам, связывающимся с создаваемой библиотекой. Она использует параметр -reexport_framework и имеет те же ограничения linker, что и FRAMEWORK.

WEAK_FRAMEWORK

Это аналогично функции FRAMEWORK, за исключением того, что она принуждает linker пометить фреймворк и все ссылки на него как слабые импорты. Она использует параметр -weak_framework и имеет те же ограничения linker, что и FRAMEWORK.

NEEDED_LIBRARY

Это аналогично функции NEEDED_FRAMEWORK, за исключением того, что она предназначена для использования с целевыми объектами или библиотеками, не являющимися фреймворками (только для платформ Apple). Она использует параметр -needed_library или -needed-l соответственно и имеет те же ограничения linker, что и NEEDED_FRAMEWORK.

REEXPORT_LIBRARY

Это аналогично функции REEXPORT_FRAMEWORK, за исключением того, что она предназначена для использования с целевыми объектами или библиотеками, не являющимися фреймворками (только для платформ Apple). Она использует параметр -reexport_library или -reexport-l соответственно и имеет те же ограничения linker, что и REEXPORT_FRAMEWORK.

WEAK_LIBRARY

Это аналогично функции WEAK_FRAMEWORK, за исключением того, что она предназначена для использования с целевыми объектами или библиотеками, не являющимися фреймворками (только для платформ Apple). Она использует параметр -weak_library или -weak-l соответственно и имеет те же ограничения linker, что и WEAK_FRAMEWORK.