CMAKE__LINK_GROUP_USING_

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