CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>

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

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

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

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

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

<PREFIX> <SUFFIX>

В командной строке компоновщика <PREFIX> предшествует списку библиотек в группе, а <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".

Примеры

Решение перекрёстных ссылок между двумя статическими библиотеками

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

set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED TRUE)
if(CMAKE_C_COMPILER_ID STREQUAL "GNU" AND CMAKE_SYSTEM_NAME STREQUAL "Linux")
  set(CMAKE_C_LINK_GROUP_USING_cross_refs
    "LINKER:--start-group"
    "LINKER:--end-group"
  )
elseif(CMAKE_C_COMPILER_ID STREQUAL "SunPro" AND CMAKE_SYSTEM_NAME STREQUAL "SunOS")
  set(CMAKE_C_LINK_GROUP_USING_cross_refs
    "LINKER:-z,rescan-start"
    "LINKER:-z,rescan-end"
  )
else()
  # feature not yet supported for the other environments
  set(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED FALSE)
endif()

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

if(CMAKE_C_LINK_GROUP_USING_cross_refs_SUPPORTED)
  target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>")
else()
  target_link_libraries(lib2 PRIVATE lib1 external)
endif()

CMake сгенерирует следующие фрагменты командной строки компоновщика при компоновке lib2:

• GNU: -Wl,--start-group /path/to/lib1.a -lexternal -Wl,--end-group
• SunPro: -Wl,-z,rescan-start /path/to/lib1.a -lexternal -Wl,-z,rescan-end

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

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

RESCAN

Некоторые компоновщики поддерживают только одно прохождение. Для таких компоновщиков циклические ссылки между библиотеками обычно приводят к неразрешённым символам. Эта функция инструктирует компоновщик многократно искать указанные статические библиотеки до тех пор, пока не будут созданы новые неопределённые ссылки.

Обычно статическая библиотека ищется только один раз в порядке, в котором она указана в командной строке. Если символ в этой библиотеке необходим для разрешения неопределённого символа, на который ссылается объект в библиотеке, которая появляется позже в командной строке, компоновщик не сможет разрешить эту ссылку. Группируя статические библиотеки с помощью функции RESCAN, они будут все переиыскиваться до тех пор, пока все возможные ссылки не будут разрешены. Это будет использовать параметры компоновщика, такие как --start-group и --end-group, или на SunOS, -z rescan-start и -z rescan-end.

Использование этой функции имеет значительные затраты на производительность. Лучше использовать её только в случае неизбежных циклических ссылок между двумя или более статическими библиотеками.

Эта функция доступна при использовании инструментариев, ориентированных на Linux, BSD и SunOS. Она также может использоваться при работе с платформами Windows, если используется GNU-инструментарий.