cmake-generator-expressions(7)

Введение
Пробелы и цитирование
Отладка
Справочник по выражениям генератора

Введение

Выражения генератора вычисляются во время генерации системы сборки, чтобы получить информацию, специфичную для каждой конфигурации сборки. Они имеют вид $<...>. Например:

target_include_directories(tgt PRIVATE /opt/include/$<CXX_COMPILER_ID>)

Это будет расширено до /opt/include/GNU, /opt/include/Clang, и т.д. в зависимости от используемого компилятора C++.

Выражения генератора разрешены в контексте многих свойств целевых объектов, таких как LINK_LIBRARIES, INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS и другие. Они также могут использоваться при использовании команд для заполнения этих свойств, таких как target_link_libraries(), target_include_directories(), target_compile_definitions() и другие. Они позволяют условную компоновку, условные определения, используемые при компиляции, условные каталоги включения и многое другое. Условия могут основываться на конфигурации сборки, свойствах целевого объекта, информации о платформе или любой другой запрашиваемой информации.

Выражения генератора могут быть вложенными:

target_compile_definitions(tgt PRIVATE
  $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER>
)

Вышеперечисленное будет расширено до OLD_COMPILER если CMAKE_CXX_COMPILER_VERSION меньше 4.2.0.

Пробелы и цитирование

Выражения генератора обычно анализируются после аргументов команд. Если выражение генератора содержит пробелы, новые строки, точки с запятой или другие символы, которые могут быть интерпретированы как разделители аргументов команд, всё выражение должно быть заключено в кавычки при передаче в команду. Отсутствие этого может привести к разделению выражения, и оно может больше не распознаваться как выражение генератора.

При использовании add_custom_command() или add_custom_target(), используйте опции VERBATIM и COMMAND_EXPAND_LISTS для получения надёжного разделения и цитирования аргументов.

# WRONG: Embedded space will be treated as an argument separator.
# This ends up not being seen as a generator expression at all.
add_custom_target(run_some_tool
  COMMAND some_tool -I$<JOIN:$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>, -I>
  VERBATIM
)

# Better, but still not robust. Quotes prevent the space from splitting the
# expression. However, the tool will receive the expanded value as a single
# argument.
add_custom_target(run_some_tool
  COMMAND some_tool "-I$<JOIN:$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>, -I>"
  VERBATIM
)

# Nearly correct. Using a semicolon to separate arguments and adding the
# COMMAND_EXPAND_LISTS option means that paths with spaces will be handled
# correctly. Quoting the whole expression ensures it is seen as a generator
# expression. But if the target property is empty, we will get a bare -I
# with nothing after it.
add_custom_target(run_some_tool
  COMMAND some_tool "-I$<JOIN:$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>,;-I>"
  COMMAND_EXPAND_LISTS
  VERBATIM
)

Использование переменных для построения более сложного выражения генератора также является хорошим способом уменьшить ошибки и улучшить читабельность. Приведенный выше пример можно дополнительно улучшить следующим образом:

# The $<BOOL:...> check prevents adding anything if the property is empty,
# assuming the property value cannot be one of CMake's false constants.
set(prop "$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>")
add_custom_target(run_some_tool
  COMMAND some_tool "$<$<BOOL:${prop}>:-I$<JOIN:${prop},;-I>>"
  COMMAND_EXPAND_LISTS
  VERBATIM
)

Наконец, вышеприведенный пример можно выразить более простым и надёжным способом, используя альтернативное выражение генератора:

add_custom_target(run_some_tool
  COMMAND some_tool "$<LIST:TRANSFORM,$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>,PREPEND,-I>"
  COMMAND_EXPAND_LISTS
  VERBATIM
)

Частая ошибка — попытка разбить выражение генератора на несколько строк с отступами:

# WRONG: New lines and spaces all treated as argument separators, so the
# generator expression is split and not recognized correctly.
target_compile_definitions(tgt PRIVATE
  $<$<AND:
      $<CXX_COMPILER_ID:GNU>,
      $<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,5>
    >:HAVE_5_OR_LATER>
)

Вместо этого используйте вспомогательные переменные с хорошо выбранными именами, чтобы построить читаемое выражение:

set(is_gnu "$<CXX_COMPILER_ID:GNU>")
set(v5_or_later "$<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,5>")
set(meet_requirements "$<AND:${is_gnu},${v5_or_later}>")
target_compile_definitions(tgt PRIVATE
  "$<${meet_requirements}:HAVE_5_OR_LATER>"
)

Отладка

Поскольку выражения генератора оцениваются во время генерации системы сборки, а не во время обработки файлов CMakeLists.txt, невозможно проверить их результат с помощью команды message(). Один из возможных способов вывода сообщений об отладке — добавить целевой объект:

add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>")

После запуска cmake, вы можете затем собрать целевой объект genexdebug для вывода результата выражения $<...> (например, запустите команду cmake --build ... --target genexdebug).

Другой способ — записать сообщения об отладке в файл с помощью file(GENERATE):

file(GENERATE OUTPUT filename CONTENT "$<...>")

Справочник по выражениям генератора

Примечание

Этот справочник отличается от большей части документации CMake тем, что он опускает угловые скобки <...> вокруг заполнитель, таких как condition, string, target, и т.д. Это предотвращает возможность неправильного толкования этих заполнитель как выражений генератора.

Условные выражения

Фундаментальная категория выражений генератора связана с условной логикой. Поддерживаются две формы условных выражений генератора:

$<condition:true_string>: Вычисляется как true_string если condition равно 1, или как пустая строка, если condition вычисляется как 0. Любое другое значение для condition приводит к ошибке.

$<IF:condition,true_string,false_string>: Новое в версии 3.8.

Вычисляется как true_string если condition равно 1, или как false_string если condition равно 0. Любое другое значение для condition приводит к ошибке.

Обычно condition само по себе является выражением генератора. Например, следующее выражение расширяется до DEBUG_MODE при использовании конфигурации Debug, и до пустой строки при всех других конфигурациях:

$<$<CONFIG:Debug>:DEBUG_MODE>

Булевые значения condition , отличные от 1 или 0, могут обрабатываться с помощью выражения генератора $<BOOL:...>.

$<BOOL:string>

Преобразует string в 0 или 1. Вычисляется как 0, если выполняется хотя бы одно из следующих условий:

string пустое,
string без учёта регистра равно 0, FALSE, OFF, N, NO, IGNORE, или NOTFOUND, или
string заканчивается на суффикс -NOTFOUND (учитывая регистр).

В противном случае вычисляется как 1.

Выражение генератора $<BOOL:...> часто используется, когда condition предоставляется переменной CMake:

$<$<BOOL:${HAVE_SOME_FEATURE}>:-DENABLE_SOME_FEATURE>

Логические операторы

Поддерживаются стандартные логические операторы:

$<AND:conditions>: где conditions — это список логических выражений, разделенных запятыми, все из которых должны вычисляться либо как 1 либо как 0. Весь выражение вычисляется как 1 если все условия 1. Если какое-либо условие 0, то все выражение вычисляется как 0.

$<OR:conditions>: где conditions — это список логических выражений, разделенных запятыми, все из которых должны вычисляться либо как 1 либо как 0. Весь выражение вычисляется как 1 если хотя бы одно из conditions является 1. Если все conditions вычисляются как 0, то все выражение вычисляется как 0.

$<NOT:condition>: condition должно быть 0 или 1. Результат выражения — 0 если condition равно 1, иначе 1.

Основные выражения сравнения

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

Сравнения строк

$<STREQUAL:string1,string2>

1 если string1 и string2 равны, иначе 0. Сравнение чувствительно к регистру. Для сравнения без учета регистра комбинируйте с выражением генератора преобразования строк. Например, следующее выражение вычисляется как 1 если ${foo} равно BAR, Bar, bar, и т. д.

$<STREQUAL:$<UPPER_CASE:${foo}>,BAR>

$<EQUAL:value1,value2>: 1 если value1 и value2 численно равны, иначе 0.

Сравнения версий

$<VERSION_LESS:v1,v2>: 1 если v1 — версия меньше, чем v2, иначе 0.

$<VERSION_GREATER:v1,v2>: 1 если v1 — версия больше, чем v2, иначе 0.

$<VERSION_EQUAL:v1,v2>: 1 если v1 — та же версия, что и v2, иначе 0.

$<VERSION_LESS_EQUAL:v1,v2>: Новая версия с 3.7.

1 если v1 — версия меньше или равна v2, иначе 0.

$<VERSION_GREATER_EQUAL:v1,v2>: Новая версия с 3.7.

1 если v1 — версия больше или равна v2, иначе 0.

Преобразования строк

$<LOWER_CASE:string>: Содержимое string преобразуется в нижний регистр.

$<UPPER_CASE:string>: Содержимое string преобразуется в верхний регистр.

$<MAKE_C_IDENTIFIER:...>: Содержимое ... преобразуется в идентификатор C. Преобразование следует тем же правилам, что и string(MAKE_C_IDENTIFIER).

Выражения списков

Большинство выражений в этом разделе тесно связаны с командой list(), предоставляя те же возможности, но в форме выражения генератора.

В каждом из следующих выражений, связанных со списками, list не должно содержать запятых, если выражение генератора ожидает что-то после list. Например, выражение $<LIST:FIND,list,value> требует value после list. Поскольку запятая используется для разделения list и value, то list не может содержать запятую. Это ограничение не относится к команде list(), оно специфично только для выражений генератора, обрабатывающих списки.

Сравнения списков

$<IN_LIST:string,list>: Новая версия с 3.12.

1 если string является элементом в списке, разделенном точками с запятой list, иначе 0. Используется сравнение, чувствительное к регистру.

Запросы к спискам

$<LIST:LENGTH,list>: Новая версия с 3.27.

Количество элементов в list.

$<LIST:GET,list,index,...>: Новая версия с 3.27.

Выводит список элементов, указанных индексами из list.

$<LIST:SUBLIST,list,begin,length>: Новая версия с 3.27.

Подсписок данного list. Если length равно 0, будет возвращен пустой список. Если length равно -1 или список меньше begin + length, будут возвращены оставшиеся элементы списка, начиная с begin.

$<LIST:FIND,list,value>: Новая версия с 3.27.

Индекс первого элемента в list со значением value, или -1, если value не содержится в list.

Преобразования списков

$<LIST:JOIN,list,glue>: Новая версия с 3.27.

Преобразует list в одну строку, вставляя содержимое строки glue между каждым элементом. По сути, это та же операция, что и $<JOIN:list,glue>, но с разным поведением в отношении пустых элементов. $<LIST:JOIN,list,glue> сохраняет все пустые элементы, в то время как $<JOIN:list,glue> удаляет все пустые элементы из списка.

$<LIST:APPEND,list,item,...>: Новая версия с 3.27.

Список list с присоединенными к нему элементами item. Несколько элементов должны быть разделены запятыми.

$<LIST:PREPEND,list,item,...>: Новая версия с 3.27.

Список list с вставленными элементами item в начале. Если есть несколько элементов, они должны быть разделены запятыми, и порядок вставленных элементов будет сохранен.

$<LIST:INSERT,list,index,item,...>

Новая версия с 3.27.

Список list с вставленными элементами item (или несколькими элементами) по указанному index. Несколько элементов должны быть разделены запятыми.

Ошибка при указании индекса за пределами диапазона index. Действительные индексы — от 0 до N, где N — длина списка включительно. Длина пустого списка равна 0.

$<LIST:POP_BACK,list>: Новая версия с 3.27.

Список list с удаленным последним элементом.

$<LIST:POP_FRONT,list>: Новая версия с 3.27.

Список list с удаленным первым элементом.

$<LIST:REMOVE_ITEM,list,value,...>: Новое в версии 3.27.

Список list со всеми вхождениями заданных value (или значений) удалены. Если указано несколько значений, они должны быть разделены запятыми.

$<LIST:REMOVE_AT,list,index,...>: Новое в версии 3.27.

Список list с элементом на каждом заданном index удалён.

$<LIST:REMOVE_DUPLICATES,list>: Новое в версии 3.27.

Список list со всеми дублированными элементами удалены. Относительный порядок элементов сохраняется, но если встречаются дубликаты, сохраняется только первое вхождение. Результат такой же, как $<REMOVE_DUPLICATES:list>.

$<LIST:FILTER,list,INCLUDE|EXCLUDE,regex>: Новое в версии 3.27.

Список элементов из list, которые соответствуют (INCLUDE) или не соответствуют (EXCLUDE) регулярному выражению regex. Результат такой же, как $<FILTER:list,INCLUDE|EXCLUDE,regex>.

$<LIST:TRANSFORM,list,ACTION[,SELECTOR]>

Новое в версии 3.27.

Список list преобразован путём применения ACTION ко всем элементам, или, указав SELECTOR, к выбранным элементам списка.

Примечание

Подкоманда TRANSFORM не изменяет количество элементов в списке. Если указан SELECTOR, только некоторые элементы будут изменены, а другие останутся такими же, как и до преобразования.

ACTION задаёт действие, которое необходимо применить к элементам списка. Действия имеют точно такой же смысл, как и для команды list(TRANSFORM). ACTION должно быть одним из следующих:

APPEND, PREPEND

Добавление, вставка заданного значения в каждый элемент списка.

$<LIST:TRANSFORM,list,(APPEND|PREPEND),value[,SELECTOR]>

TOLOWER, TOUPPER

Преобразование каждого элемента списка в строчные, прописные символы.

$<LIST:TRANSFORM,list,(TOLOWER|TOUPPER)[,SELECTOR]>

STRIP

Удаление начальных и конечных пробелов из каждого элемента списка.

$<LIST:TRANSFORM,list,STRIP[,SELECTOR]>

REPLACE:

Сопоставление регулярного выражения как можно большее количество раз и замена выражения подстановки для совпадения для каждого элемента списка.

$<LIST:TRANSFORM,list,REPLACE,regular_expression,replace_expression[,SELECTOR]>

SELECTOR определяет, какие элементы списка будут преобразованы. Одновременно может быть указан только один тип селектора. При указании SELECTOR должно быть одним из следующих:

AT

Указывает список индексов.

$<LIST:TRANSFORM,list,ACTION,AT,index[,index...]>

FOR

Указывает диапазон с, необязательно, приращением, используемым для итерации по диапазону.

$<LIST:TRANSFORM,list,ACTION,FOR,start,stop[,step]>

REGEX

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

$<LIST:TRANSFORM,list,ACTION,REGEX,regular_expression>

$<JOIN:list,glue>: Объединяет list с содержанием glue строки, вставленной между каждым элементом. Это концептуально такая же операция, как $<LIST:JOIN,list,glue>, но две операции ведут себя по-разному в отношении пустых элементов. $<LIST:JOIN,list,glue> сохраняет все пустые элементы, а $<JOIN,list,glue> удаляет все пустые элементы из списка.

$<REMOVE_DUPLICATES:list>: Новое в версии 3.15.

Удаляет дублированные элементы в заданном list. Относительный порядок элементов сохраняется, и если встречаются дубликаты, сохраняется только первое вхождение. Результат такой же, как $<LIST:REMOVE_DUPLICATES,list>.

$<FILTER:list,INCLUDE|EXCLUDE,regex>: Новое в версии 3.15.

Включает или исключает элементы из list , которые соответствуют регулярному выражению regex. Результат такой же, как $<LIST:FILTER,list,INCLUDE|EXCLUDE,regex>.

Порядок элементов списка

$<LIST:REVERSE,list>: Новое в версии 3.27.

Список list с элементами в обратном порядке.

$<LIST:SORT,list[,(COMPARE:option|CASE:option|ORDER:option)]...>

Новое в версии 3.27.

Список list отсортирован в соответствии с указанными параметрами.

Используйте один из COMPARE параметров для выбора метода сравнения для сортировки:

STRING: Сортирует список строк в алфавитном порядке. Это поведение по умолчанию, если параметр COMPARE не указан.
FILE_BASENAME: Сортирует список путей к файлам по их именам файлов.
NATURAL: Сортирует список строк в естественном порядке (см. страницу справки для strverscmp(3)), так что смежные цифры сравниваются как целые числа. Например, следующий список 10.0 1.1 2.1 8.0 2.0 3.1 будет отсортирован как 1.1 2.0 2.1 3.1 8.0 10.0 , если выбран параметр сравнения NATURAL, в то время как он будет отсортирован как 1.1 10.0 2.0 2.1 3.1 8.0 с параметром сравнения STRING.

Используйте один из CASE параметров для выбора режима сортировки, чувствительной или нечувствительной к регистру:

SENSITIVE: Элементы списка сортируются в режиме чувствительности к регистру. Это поведение по умолчанию, если параметр CASE не указан.
INSENSITIVE: Элементы списка сортируются в режиме нечувствительности к регистру. Порядок элементов, отличающихся только регистром символов, не определен.

Для управления порядком сортировки можно указать один из ORDER параметров:

ASCENDING: Сортирует список в порядке возрастания. Это поведение по умолчанию, когда параметр ORDER не указан.
DESCENDING: Сортирует список в порядке убывания.

Параметры могут быть указаны в любом порядке, но ошибка указывать один и тот же параметр несколько раз.

$<LIST:SORT,list,CASE:SENSITIVE,COMPARE:STRING,ORDER:DESCENDING>

Выражения путей

Большинство выражений в этом разделе тесно связаны с командой cmake_path(), обеспечивая такие же возможности, но в виде выражения генератора.

Для всех выражений генератора в этом разделе пути ожидаются в формате CMake. Выражение генератора $<PATH:CMAKE_PATH> может использоваться для преобразования пути в формате ОС в путь в формате CMake.

Сравнения путей

$<PATH_EQUAL:path1,path2>

Новое в версии 3.24.

Сравнивает лексические представления двух путей. Никакая нормализация не выполняется ни для одного пути. Возвращает 1 , если пути равны, 0 в противном случае.

См. cmake_path(COMPARE) для получения дополнительной информации.

Запросы к путям

Эти выражения предоставляют возможности генерации, эквивалентные параметрам запроса Запрос команды cmake_path(). Все пути ожидаются в формате CMake.

$<PATH:HAS_*,path>

Новое в версии 3.24.

Следующие операции возвращают 1 , если соответствующий компонент пути присутствует, 0 в противном случае. См. Структуру пути и терминологию для значения каждого компонента пути.

$<PATH:HAS_ROOT_NAME,path>
$<PATH:HAS_ROOT_DIRECTORY,path>
$<PATH:HAS_ROOT_PATH,path>
$<PATH:HAS_FILENAME,path>
$<PATH:HAS_EXTENSION,path>
$<PATH:HAS_STEM,path>
$<PATH:HAS_RELATIVE_PART,path>
$<PATH:HAS_PARENT_PATH,path>

Обратите внимание на следующие частные случаи:

Для HAS_ROOT_PATH, истинный результат будет возвращен только в том случае, если хотя бы один из root-name или root-directory не пустой.
Для HAS_PARENT_PATH, корневой каталог также считается имеющим родительский каталог, который будет являться им самим. Результат будет истинным, за исключением случая, когда путь состоит только из имени файла.

$<PATH:IS_ABSOLUTE,path>: Новое в версии 3.24.

Возвращает 1 , если путь является абсолютным, 0 в противном случае.

$<PATH:IS_RELATIVE,path>: Новое в версии 3.24.

Это вернёт обратное значение IS_ABSOLUTE.

$<PATH:IS_PREFIX[,NORMALIZE],path,input>

Новое в версии 3.24.

Возвращает 1 , если path является префиксом input , 0 в противном случае.

При указании параметра NORMALIZE, path и input будут нормализованы перед проверкой.

Разложение пути

Эти выражения предоставляют возможности генерации, эквивалентные параметрам Разложения в команде cmake_path(). Ожидается, что все пути будут в формате cmake.

$<PATH:GET_*,...>

Новое в версии 3.24.

Следующие операции извлекают различные компоненты или группы компонентов из пути. См. Структуру пути и терминологию для значения каждого компонента пути.

Изменено в версии 3.27: Все операции теперь принимают список путей в качестве аргумента. При указании списка путей операция будет применена к каждому пути.

$<PATH:GET_ROOT_NAME,path...>
$<PATH:GET_ROOT_DIRECTORY,path...>
$<PATH:GET_ROOT_PATH,path...>
$<PATH:GET_FILENAME,path...>
$<PATH:GET_EXTENSION[,LAST_ONLY],path...>
$<PATH:GET_STEM[,LAST_ONLY],path...>
$<PATH:GET_RELATIVE_PART,path...>
$<PATH:GET_PARENT_PATH,path...>

Если запрашиваемый компонент отсутствует в пути, возвращается пустая строка.

Преобразования пути

Эти выражения предоставляют возможности генерации, эквивалентные параметрам Модификации и Генерации в команде cmake_path(). Ожидается, что все пути будут в формате cmake.

$<PATH:CMAKE_PATH[,NORMALIZE],path...>

Новое в версии 3.24.

Возвращает path. Если path является системным путем, он преобразуется в путь cmake со слешами вперед (/). В Windows учитывается маркер длинного имени файла.

При указании параметра NORMALIZE, путь нормализуется после преобразования.

$<PATH:APPEND,path...,input,...>

Новое в версии 3.24.

Возвращает все аргументы input , добавленные к path с использованием / в качестве directory-separator . В зависимости от input, значение path может быть отброшено.

См. cmake_path(APPEND) для получения дополнительной информации.

$<PATH:REMOVE_FILENAME,path...>

Новое в версии 3.24.

Возвращает path , из которого удалён компонент имени файла (как возвращает $<PATH:GET_FILENAME>). После удаления любые хвостовые directory-separator остаются неизменными, если они присутствуют.

См. cmake_path(REMOVE_FILENAME) для получения дополнительной информации.

$<PATH:REPLACE_FILENAME,path...,input>

Новое в версии 3.24.

Возвращает path , с компонентом имени файла, заменённым на input . Если path не имеет компонента имени файла (т.е. $<PATH:HAS_FILENAME> возвращает 0 ), path остаётся без изменений.

См. cmake_path(REPLACE_FILENAME) для получения дополнительной информации.

$<PATH:REMOVE_EXTENSION[,LAST_ONLY],path...>

Новое в версии 3.24.

Возвращает path , из которого удалено расширение, если оно есть.

См. cmake_path(REMOVE_EXTENSION) для получения дополнительной информации.

$<PATH:REPLACE_EXTENSION[,LAST_ONLY],path...,input>

Новое в версии 3.24.

Возвращает path , с расширением, заменённым на input, если оно есть.

См. cmake_path(REPLACE_EXTENSION) для получения дополнительной информации.

$<PATH:NORMAL_PATH,path...>: Новое в версии 3.24.

Возвращает path , нормализованный в соответствии с шагами, описанными в Нормализации.

$<PATH:RELATIVE_PATH,path...,base_directory>

Новое в версии 3.24.

Возвращает path, преобразованный, чтобы сделать его относительным к аргументу base_directory.

См. cmake_path(RELATIVE_PATH) для получения дополнительной информации.

$<PATH:ABSOLUTE_PATH[,NORMALIZE],path...,base_directory>

Новое в версии 3.24.

Возвращает path в абсолютном формате. Если path является относительным путем ($<PATH:IS_RELATIVE> возвращает 1 ), он вычисляется относительно заданного базового каталога, указанного в аргументе base_directory.

При указании параметра NORMALIZE, путь нормализуется после вычисления пути.

См. cmake_path(ABSOLUTE_PATH) для получения дополнительной информации.

Пути оболочки

$<SHELL_PATH:...>: Новое в версии 3.4.

Содержимое ... преобразуется в стиль пути оболочки. Например, косые черты преобразуются в обратные косые черты в оболочках Windows, а буквы диска преобразуются в пути POSIX в оболочках MSYS. ... должен быть абсолютным путём.

Новое в версии 3.14: ... может быть списком, разделённым точкой с запятой путей, в этом случае каждый путь преобразуется индивидуально, а результирующий список генерируется с использованием разделителя путей оболочки (: в POSIX и ; в Windows). Убедитесь, что аргумент, содержащий этот genex, заключён в двойные кавычки в исходном коде CMake, чтобы ; не разделял аргументы.

Выражения конфигурации

$<CONFIG>: Имя конфигурации. Используйте это вместо устаревшего выражения генератора CONFIGURATION.

$<CONFIG:cfgs>: 1 если конфигурация является одним из элементов в списке, разделённом запятыми cfgs, в противном случае 0. Это сравнение без учёта регистра. Сопоставление в MAP_IMPORTED_CONFIG_<CONFIG> также учитывается этим выражением при его оценке на свойстве целевого объекта IMPORTED.

Изменено в версии 3.19: Для cfgs могут быть указаны несколько конфигураций. CMake 3.18 и более ранние версии принимали только одну конфигурацию.

$<OUTPUT_CONFIG:...>: Новое в версии 3.20.

Действительно только в add_custom_command() и add_custom_target() как внешнее выражение генератора в аргументе. С генератором Ninja Multi-Config выражения генератора в ... вычисляются с использованием «конфигурации вывода» пользовательской команды. В других генераторах содержимое ... вычисляется стандартным способом.

$<COMMAND_CONFIG:...>: Новое в версии 3.20.

Действительно только в add_custom_command() и add_custom_target() как внешнее выражение генератора в аргументе. С генератором Ninja Multi-Config выражения генератора в ... вычисляются с использованием «конфигурации команды» пользовательской команды. В других генераторах содержимое ... вычисляется стандартным способом.

Выражения инструментальной цепочки и языка

Платформа

$<PLATFORM_ID>: Идентификатор платформы текущей системы CMake. См. также переменную CMAKE_SYSTEM_NAME.

$<PLATFORM_ID:platform_ids>: 1 если идентификатор платформы CMake соответствует любому из элементов в списке, разделённом запятыми platform_ids, в противном случае 0. См. также переменную CMAKE_SYSTEM_NAME.

Версия компилятора

См. также переменную CMAKE_<LANG>_COMPILER_VERSION, которая тесно связана с выражениями в этом подраздёле.

$<C_COMPILER_VERSION>: Версия используемого компилятора C.

$<C_COMPILER_VERSION:version>: 1 если версия компилятора C соответствует version, в противном случае 0.

$<CXX_COMPILER_VERSION>: Версия используемого компилятора CXX.

$<CXX_COMPILER_VERSION:version>: 1 если версия компилятора CXX соответствует version, в противном случае 0.

$<CUDA_COMPILER_VERSION>: Новое в версии 3.15.

Версия используемого компилятора CUDA.

$<CUDA_COMPILER_VERSION:version>: Новое в версии 3.15.

1 если версия компилятора CXX соответствует version, в противном случае 0.

$<OBJC_COMPILER_VERSION>: Новое в версии 3.16.

Версия используемого компилятора OBJC.

$<OBJC_COMPILER_VERSION:version>: Новое в версии 3.16.

1 если версия компилятора OBJC соответствует version, в противном случае 0.

$<OBJCXX_COMPILER_VERSION>: Новое в версии 3.16.

Версия используемого компилятора OBJCXX.

$<OBJCXX_COMPILER_VERSION:version>: Новое в версии 3.16.

1 если версия компилятора OBJCXX соответствует version, в противном случае 0.

$<Fortran_COMPILER_VERSION>: Версия используемого компилятора Fortran.

$<Fortran_COMPILER_VERSION:version>: 1 если версия компилятора Fortran соответствует version, в противном случае 0.

$<HIP_COMPILER_VERSION>: Новое в версии 3.21.

Версия используемого компилятора HIP.

$<HIP_COMPILER_VERSION:version>: Новое в версии 3.21.

1 если версия компилятора HIP соответствует version, в противном случае 0.

$<ISPC_COMPILER_VERSION>: Новое в версии 3.19.

Версия используемого компилятора ISPC.

$<ISPC_COMPILER_VERSION:version>: Новое в версии 3.19.

1 если версия компилятора ISPC соответствует version, в противном случае 0.

Язык и идентификатор компилятора

См. также переменную CMAKE_<LANG>_COMPILER_ID, которая тесно связана с большинством выражений в этом подраздёле.

$<C_COMPILER_ID>: Идентификатор компилятора C, используемый CMake.

$<C_COMPILER_ID:compiler_ids>: где compiler_ids - это список, разделённый запятыми. 1 если идентификатор компилятора C CMake соответствует одному из элементов в compiler_ids, в противном случае 0.

$<CXX_COMPILER_ID>: Идентификатор компилятора CMake для используемого компилятора CXX.

$<CXX_COMPILER_ID:compiler_ids>: где compiler_ids — список, разделенный запятыми. 1 если идентификатор компилятора CMake для компилятора CXX соответствует одному из элементов в compiler_ids, в противном случае 0.

$<CUDA_COMPILER_ID>: Добавлена в версии 3.15.

Идентификатор компилятора CMake для используемого компилятора CUDA.

$<CUDA_COMPILER_ID:compiler_ids>: Добавлена в версии 3.15.

где compiler_ids — список, разделенный запятыми. 1 если идентификатор компилятора CMake для компилятора CUDA соответствует одному из элементов в compiler_ids, в противном случае 0.

$<OBJC_COMPILER_ID>: Добавлена в версии 3.16.

Идентификатор компилятора CMake для используемого компилятора OBJC.

$<OBJC_COMPILER_ID:compiler_ids>: Добавлена в версии 3.16.

где compiler_ids — список, разделенный запятыми. 1 если идентификатор компилятора Objective-C компилятора соответствует одному из элементов в compiler_ids, в противном случае 0.

$<OBJCXX_COMPILER_ID>: Добавлена в версии 3.16.

Идентификатор компилятора CMake для используемого компилятора OBJCXX.

$<OBJCXX_COMPILER_ID:compiler_ids>: Добавлена в версии 3.16.

где compiler_ids — список, разделенный запятыми. 1 если идентификатор компилятора Objective-C++ соответствует одному из элементов в compiler_ids, в противном случае 0.

$<Fortran_COMPILER_ID>: Идентификатор компилятора CMake для используемого компилятора Fortran.

$<Fortran_COMPILER_ID:compiler_ids>: где compiler_ids — список, разделенный запятыми. 1 если идентификатор компилятора Fortran соответствует одному из элементов в compiler_ids, в противном случае 0.

$<HIP_COMPILER_ID>: Добавлена в версии 3.21.

Идентификатор компилятора CMake для используемого компилятора HIP.

$<HIP_COMPILER_ID:compiler_ids>: Добавлена в версии 3.21.

где compiler_ids — список, разделенный запятыми. 1 если идентификатор компилятора HIP соответствует одному из элементов в compiler_ids, в противном случае 0.

$<ISPC_COMPILER_ID>: Добавлена в версии 3.19.

Идентификатор компилятора CMake для используемого компилятора ISPC.

$<ISPC_COMPILER_ID:compiler_ids>: Добавлена в версии 3.19.

где compiler_ids — список, разделенный запятыми. 1 если идентификатор компилятора ISPC соответствует одному из элементов в compiler_ids, в противном случае 0.

$<COMPILE_LANGUAGE>: Добавлена в версии 3.3.

Язык компиляции исходных файлов при оценке опций компиляции. См. соответствующее логическое выражение $<COMPILE_LANGUAGE:language> для заметок о переносимости этого выражения генератора.

$<COMPILE_LANGUAGE:languages>

Добавлена в версии 3.3.

Изменено в версии 3.15: Для languages можно указать несколько языков. CMake 3.14 и более ранние версии принимали только один язык.

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

add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
target_compile_options(myapp
  PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
)
target_compile_definitions(myapp
  PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
          $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA>
)
target_include_directories(myapp
  PRIVATE $<$<COMPILE_LANGUAGE:CXX,CUDA>:/opt/foo/headers>
)

Это указывает на использование опции компиляции -fno-exceptions, определения компиляции COMPILING_CXX и каталога включения cxx_headers только для C++. (Проверки идентификаторов компилятора опушены). Также указывается определение компиляции COMPILING_CUDA для CUDA.

Обратите внимание, что в генераторах Visual Studio и Xcode нет способа представить определения компиляции или каталоги включения для отдельных целей для языков C и CXX. Также в генераторах Visual Studio нет способа представить флаги отдельных целей для языков C и CXX. В этих генераторах выражения для файлов исходного кода C и C++ будут оцениваться с использованием CXX если есть какие-либо файлы исходного кода C++, и в противном случае с использованием C. Обходным решением является создание отдельных библиотек для каждого языка исходных файлов:

add_library(myapp_c foo.c)
add_library(myapp_cxx bar.cpp)
target_compile_options(myapp_cxx PUBLIC -fno-exceptions)
add_executable(myapp main.cpp)
target_link_libraries(myapp myapp_c myapp_cxx)

$<COMPILE_LANG_AND_ID:language,compiler_ids>

Добавлена в версии 3.15.

1 если язык, используемый для компиляции блока, соответствует language и идентификатор компилятора language соответствует одному из элементов, разделенных запятыми, в compiler_ids, в противном случае 0. Это выражение является сокращенной формой сочетания $<COMPILE_LANGUAGE:language> и $<LANG_COMPILER_ID:compiler_ids>. Это выражение можно использовать для указания опций компиляции, определений компиляции и каталогов включения для исходных файлов определенной комбинации языка и компилятора в целевом объекте. Например:

add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
target_compile_definitions(myapp
  PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG>
          $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL>
          $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG>
)

Это указывает на использование различных определений компиляции в зависимости от идентификатора компилятора и языка компиляции. В этом примере будет использоваться определение компиляции COMPILING_CXX_WITH_CLANG когда Clang является компилятором CXX, и COMPILING_CXX_WITH_INTEL когда Intel является компилятором CXX. Аналогично, когда компилятором C является Clang, он будет видеть только определение COMPILING_C_WITH_CLANG.

Без выражения генератора COMPILE_LANG_AND_ID тот же логика выражалась бы так:

target_compile_definitions(myapp
  PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG>
          $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL>
          $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG>
)

Compile Features

$<COMPILE_FEATURES:features>: Добавлена в версии 3.1.

где features — список, разделенный запятыми. Принимает значение 1 если все features доступны для целевого объекта «head», и 0 в противном случае. Если это выражение используется при оценке реализации линковки целевого объекта и если любая зависимость транзитивно увеличивает требуемую C_STANDARD или CXX_STANDARD для целевого объекта «head», выводится ошибка. См. руководство cmake-compile-features(7) для получения информации о функциях компиляции и списке поддерживаемых компиляторов.

Compile Context

$<COMPILE_ONLY:...>

Новое в версии 3.27.

Содержимое ..., при сборе Требований к транзитивному использованию, в противном случае — пустая строка. Это предназначено для использования в INTERFACE_LINK_LIBRARIES и LINK_LIBRARIES свойствах целей, как правило, заполняемых командой target_link_libraries(). Обеспечивает требования к компиляции без требований к линковке.

Примеры использования включают использование только заголовков, где все использования не имеют требований к линковке (например, все inline или C++ шаблонные библиотеки).

Обратите внимание, что для правильной оценки этого выражения требуется политика CMP0099, установленная на NEW.

Язык и идентификатор линковщика

$<LINK_LANGUAGE>: Новое в версии 3.18.

Язык линковки целевого объекта при оценке параметров линковки. См. соответствующее булево выражение $<LINK_LANGUAGE:languages> для заметок о переносимости этого генераторного выражения.

Примечание

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

$<LINK_LANGUAGE:languages>

Новое в версии 3.18.

1 если язык, используемый для шага линковки, соответствует любому из значений, разделенных запятыми, в languages, в противном случае 0. Это выражение можно использовать для указания библиотек линковки, параметров линковки, каталогов линковки и зависимостей линковки для конкретного языка в целевом объекте. Например:

add_library(api_C ...)
add_library(api_CXX ...)
add_library(api INTERFACE)
target_link_options(api   INTERFACE $<$<LINK_LANGUAGE:C>:-opt_c>
                                    $<$<LINK_LANGUAGE:CXX>:-opt_cxx>)
target_link_libraries(api INTERFACE $<$<LINK_LANGUAGE:C>:api_C>
                                    $<$<LINK_LANGUAGE:CXX>:api_CXX>)

add_executable(myapp1 main.c)
target_link_options(myapp1 PRIVATE api)

add_executable(myapp2 main.cpp)
target_link_options(myapp2 PRIVATE api)

Это указывает на использование целевого объекта api для линковки целевых объектов myapp1 и myapp2. На практике, myapp1 будет линковаться с целевым объектом api_C и параметром -opt_c, потому что он будет использовать C в качестве языка линковки. А myapp2 будет линковаться с api_CXX и параметром -opt_cxx, потому что CXX будет языком линковки.

Примечание

Для определения языка линковки целевого объекта необходимо транзитивно собрать все целевые объекты, которые будут линковаться с ним. Таким образом, для свойств библиотек линковки будет выполнена двойная оценка. Во время первой оценки выражения $<LINK_LANGUAGE:..> всегда возвращают 0. Вычисленный язык линковки после этого первого прохода будет использован для второго прохода. Для предотвращения несоответствия требуется, чтобы второй проход не изменял язык линковки. Кроме того, для предотвращения непредвиденных побочных эффектов необходимо указывать полные сущности в качестве части выражения $<LINK_LANGUAGE:..>. Например:

add_library(lib STATIC file.cxx)
add_library(libother STATIC file.c)

# bad usage
add_executable(myapp1 main.c)
target_link_libraries(myapp1 PRIVATE lib$<$<LINK_LANGUAGE:C>:other>)

# correct usage
add_executable(myapp2 main.c)
target_link_libraries(myapp2 PRIVATE $<$<LINK_LANGUAGE:C>:libother>)

В этом примере, для myapp1, первый проход неожиданно определит, что язык линковки — CXX, так как оценка генераторного выражения будет пустой строкой, поэтому myapp1 зависит от целевого объекта lib, который является C++. Напротив, для myapp2, первая оценка даст C в качестве языка линковки, поэтому второй проход правильно добавит целевой объект libother как зависимость линковки.

$<LINK_LANG_AND_ID:language,compiler_ids>

Новое в версии 3.18.

1 если используемый для линковки язык соответствует language и идентификатор компилятора CMake линковщика языка совпадает с любым из значений, разделенных запятыми, в compiler_ids, в противном случае 0. Это выражение является сокращенной формой комбинации $<LINK_LANGUAGE:language> и $<LANG_COMPILER_ID:compiler_ids>. Это выражение можно использовать для указания библиотек линковки, параметров линковки, каталогов линковки и зависимостей линковки для конкретной комбинации языка и линковщика в целевом объекте. Например:

add_library(libC_Clang ...)
add_library(libCXX_Clang ...)
add_library(libC_Intel ...)
add_library(libCXX_Intel ...)

add_executable(myapp main.c)
if (CXX_CONFIG)
  target_sources(myapp PRIVATE file.cxx)
endif()
target_link_libraries(myapp
  PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang>
          $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang>
          $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel>
          $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>)

Это указывает на использование различных библиотек линковки на основе как идентификатора компилятора, так и языка линковки. В этом примере у целевого объекта libCXX_Clang будет зависимость линковки, когда Clang или AppleClang является линковщиком CXX, и libCXX_Intel когда Intel является линковщиком CXX. Аналогично, когда линковщик C является Clang или AppleClang, целевой объект libC_Clang будет добавлен в качестве зависимости линковки, а libC_Intel когда Intel является линковщиком C.

См. примечание, связанное с $<LINK_LANGUAGE:language> для ограничений по использованию этого генераторного выражения.

Функции линковки

$<LINK_LIBRARY:feature,library-list>

Новое в версии 3.24.

Укажите набор библиотек для ссылки на целевой объект, а также feature, который предоставляет сведения о том, как они должны быть связаны. Например:

add_library(lib1 STATIC ...)
add_library(lib2 ...)
target_link_libraries(lib2 PRIVATE "$<LINK_LIBRARY:WHOLE_ARCHIVE,lib1>")

Это указывает, что lib2 должен ссылаться на lib1 и использовать функцию WHOLE_ARCHIVE при этом.

Имена функций чувствительны к регистру и могут содержать только буквы, цифры и символы подчеркивания. Имена функций, определенные в верхнем регистре, зарезервированы для собственных встроенных функций 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

Этот параметр сообщает линковщику искать указанную структуру, используя параметр линковщика -framework. Он может использоваться только на платформах Apple и только с линковщиком, понимающим используемый параметр (т.е. линковщик, предоставленный 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, если проект хочет быть явным, но это не требуется. Командная строка линковщика может иметь некоторые различия при использовании выражения генератора или без него, но конечный результат должен быть одинаковым. С другой стороны, если указан путь к файлу, CMake будет автоматически распознавать некоторые пути, но не все случаи. Проект может захотеть использовать $<LINK_LIBRARY:FRAMEWORK,...> для путей к файлам, чтобы ожидаемое поведение было ясным.

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

NEEDED_FRAMEWORK

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

REEXPORT_FRAMEWORK

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

WEAK_FRAMEWORK

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

NEEDED_LIBRARY

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

REEXPORT_LIBRARY

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

WEAK_LIBRARY

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

Встроенные и пользовательские функции библиотек определены в терминах следующих переменных:

Используемое значение для каждой из этих переменных — значение, установленное в конце области каталога, в которой был создан целевой объект. Использование:

Если языковая переменная CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED имеет значение true, то feature должно быть определено соответствующей переменной CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>.
Если какая-либо языковая feature не поддерживается, то переменная CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED должна иметь значение true, и feature должно быть определено соответствующей переменной CMAKE_LINK_LIBRARY_USING_<FEATURE>.

Следует отметить следующие ограничения:

Выражение library-list может указывать на целевые объекты CMake или библиотеки. Любой целевой объект CMake типа OBJECT или INTERFACE проигнорирует аспект функции выражения и вместо этого будет подключён стандартным способом.
Генераторское выражение $<LINK_LIBRARY:...> может использоваться только для указания библиотек подключения. На практике это означает, что оно может встречаться в свойствах целевого объекта LINK_LIBRARIES, INTERFACE_LINK_LIBRARIES и INTERFACE_LINK_LIBRARIES_DIRECT, а также в командах target_link_libraries() и link_libraries().
Если генераторское выражение $<LINK_LIBRARY:...> встречается в свойстве INTERFACE_LINK_LIBRARIES целевого объекта, оно будет включено в импортированный целевой объект, созданный командой install(EXPORT). Ответственность за определение функции связи, используемой этим выражением, лежит на среде, использующей этот импорт.
Каждый целевой объект или библиотека, участвующие в шаге связывания, должны иметь не более одного типа функции библиотеки. Отсутствие функции также несовместимо со всеми другими функциями. Например:
```
add_library(lib1 ...)
add_library(lib2 ...)
add_library(lib3 ...)

# lib1 will be associated with feature1
target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature1,lib1>")

# lib1 is being linked with no feature here. This conflicts with the
# use of feature1 in the line above and would result in an error.
target_link_libraries(lib3 PRIVATE lib1 lib2)
```
В тех случаях, когда невозможно использовать одну и ту же функцию на протяжении всего построения для данного целевого объекта или библиотеки, можно использовать свойства целевого объекта LINK_LIBRARY_OVERRIDE и LINK_LIBRARY_OVERRIDE_<LIBRARY> для разрешения таких несовместимостей.
Генераторское выражение $<LINK_LIBRARY:...> не гарантирует, что список указанных целевых объектов и библиотек будет сохранён в группе. Чтобы управлять конструкциями типа --start-group и --end-group, поддерживаемыми линкером GNU ld, используйте генераторское выражение LINK_GROUP.

$<LINK_GROUP:feature,library-list>

Новое в версии 3.24.

Указывает группу библиотек для компоновки с целевым объектом, а также feature, определяющий, как эта группа должна быть скомпонована. Например:

add_library(lib1 STATIC ...)
add_library(lib2 ...)
target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:RESCAN,lib1,external>")

Это указывает, что lib2 должен быть скомпонован с lib1 и external, и что обе эти библиотеки должны быть включены в командную строку компоновщика в соответствии с определением функции RESCAN.

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

RESCAN

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

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

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

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

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

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

Если языковая переменная CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED имеет значение true, то feature должно быть определено соответствующей переменной CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>.
Если для языка не поддерживается feature, тогда переменная CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED должна иметь значение true, и feature должно быть определено соответствующей переменной CMAKE_LINK_GROUP_USING_<FEATURE>.

Выражение генератора LINK_GROUP совместимо с выражением генератора LINK_LIBRARY. Библиотеки, участвующие в группе, могут быть указаны с помощью выражения генератора LINK_LIBRARY.

Каждый целевой объект или внешняя библиотека, участвующая в шаге компоновки, может быть частью нескольких групп, но только если все участвующие группы указывают одну и ту же feature. Такие группы не будут объединены в командной строке компоновщика, отдельные группы всё равно будут сохранены. Смешивание различных функций группирования для одного целевого объекта или библиотеки запрещено.

add_library(lib1 ...)
add_library(lib2 ...)
add_library(lib3 ...)
add_library(lib4 ...)
add_library(lib5 ...)

target_link_libraries(lib3 PUBLIC  "$<LINK_GROUP:feature1,lib1,lib2>")
target_link_libraries(lib4 PRIVATE "$<LINK_GROUP:feature1,lib1,lib3>")
# lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3}.
# Both groups specify the same feature, so this is fine.

target_link_libraries(lib5 PRIVATE "$<LINK_GROUP:feature2,lib1,lib3>")
# An error will be raised here because both lib1 and lib3 are part of two
# groups with different features.

Когда целевой объект или внешняя библиотека участвует в шаге компоновки как часть группы и также не входит ни в одну группу, любое вхождение элемента компоновки без группы будет заменено группами, к которым оно относится.

add_library(lib1 ...)
add_library(lib2 ...)
add_library(lib3 ...)
add_library(lib4 ...)

target_link_libraries(lib3 PUBLIC lib1)

target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>")
# lib4 will only be linked with lib3 and the group {lib1,lib2}

Поскольку lib1 входит в группу, определённую для lib4, эта группа затем применяется к использованию lib1 для lib3. Конечный результат будет таким, как если бы взаимосвязь компоновки для lib3 была указана следующим образом:

target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>")

Обратите внимание, что приоритет группы над элементом компоновки без группы может привести к циклическим зависимостям между группами. Если это произойдёт, возникает ошибка, так как циклические зависимости для групп не допускаются.

add_library(lib1A ...)
add_library(lib1B ...)
add_library(lib2A ...)
add_library(lib2B ...)
add_library(lib3 ...)

# Non-group linking relationships, these are non-circular so far
target_link_libraries(lib1A PUBLIC lib2A)
target_link_libraries(lib2B PUBLIC lib1B)

# The addition of these groups creates circular dependencies
target_link_libraries(lib3 PRIVATE
  "$<LINK_GROUP:feat,lib1A,lib1B>"
  "$<LINK_GROUP:feat,lib2A,lib2B>"
)

Из-за групп, определённых для lib3, взаимосвязи компоновки для lib1A и lib2B фактически расширяются до эквивалента:

target_link_libraries(lib1A PUBLIC "$<LINK_GROUP:feat,lib2A,lib2B>")
target_link_libraries(lib2B PUBLIC "$<LINK_GROUP:feat,lib1A,lib1B>")

Это создаёт циклическую зависимость между группами: lib1A --> lib2B --> lib1A.

Следует также отметить следующие ограничения:

library-list может указывать целевые объекты CMake или библиотеки. Любой целевой объект CMake типа ОБЪЕКТ или ИНТЕРФЕЙС проигнорирует аспект функции выражения и вместо этого будет скомпонован стандартным способом.
Выражение генератора $<LINK_GROUP:...> может использоваться только для указания библиотек компоновки. На практике это означает, что оно может появляться в свойствах целевого объекта LINK_LIBRARIES, INTERFACE_LINK_LIBRARIES и INTERFACE_LINK_LIBRARIES_DIRECT, и быть указанным в командах target_link_libraries() и link_libraries().
Если выражение генератора $<LINK_GROUP:...> появляется в свойстве INTERFACE_LINK_LIBRARIES целевого объекта, оно будет включено в импортированный целевой объект, сгенерированный командой install(EXPORT). Ответственность за определение функции компоновки, используемой этим выражением, лежит на среде, потребляющей этот импорт.

Контекст компоновки

$<LINK_ONLY:...>: Новое в версии 3.1.

Содержимое ..., за исключением сбора Требований транзитивного использования, в этом случае пустая строка. Это предназначено для использования в свойстве целевого объекта INTERFACE_LINK_LIBRARIES, как правило, заполненное командой target_link_libraries() для указания частных зависимостей компоновки без других требований к использованию, таких как каталоги включения или параметры компиляции.

Новое в версии 3.24: LINK_ONLY также может быть использовано в свойстве целевого объекта LINK_LIBRARIES. См. политику CMP0131.

$<DEVICE_LINK:list>: Новое в версии 3.18.

Возвращает список, если это шаг компоновки устройства, в противном случае пустой список. Шаг компоновки устройства контролируется свойствами CUDA_SEPARABLE_COMPILATION и CUDA_RESOLVE_DEVICE_SYMBOLS и политикой CMP0105. Это выражение может использоваться только для указания параметров компоновки.

$<HOST_LINK:list>: Новое в версии 3.18.

Возвращает список, если это обычный этап линковки, в противном случае пустой список. Это выражение полезно в основном, когда также участвует этап линковки устройства (см. выражение генератора $<DEVICE_LINK:list>). Это выражение может быть использовано только для указания опций линковки.

Зависимые от целевых выражения

Эти запросы относятся к цели tgt. Если не указано иное, это может быть любой исполняемый файл, а именно:

Исполняемый файл, созданный с помощью add_executable().
Целевая библиотека динамической компоновки (.so, .dll но не их .lib библиотека импорта) созданная с помощью add_library().
Целевая статическая библиотека, созданная с помощью add_library().

В дальнейшем фраза «имя файла целевого бинарника» означает имя бинарного файла целевого объекта. Это необходимо отличать от фразы «имя целевого объекта», которая просто строка tgt.

$<TARGET_EXISTS:tgt>: Новое в версии 3.12.

1 если tgt существует как целевой объект CMake, иначе 0.

$<TARGET_NAME_IF_EXISTS:tgt>

Новое в версии 3.12.

Имя целевого объекта tgt если целевой объект существует, в противном случае пустая строка.

Обратите внимание, что tgt не добавляется в качестве зависимости к целевому объекту, для которого оценивается это выражение.

$<TARGET_NAME:...>: Помечает ... как имя целевого объекта. Это необходимо, если целевые объекты экспортируются в несколько зависимых наборов экспорта. ... должен быть буквенным именем целевого объекта, он не может содержать выражения генератора.

$<TARGET_PROPERTY:tgt,prop>

Значение свойства prop для целевого объекта tgt.

Изменено в версии 3.26: При обнаружении во время оценки Требований на использование зависимостей, обычно в свойстве целевого объекта INTERFACE_*, поиск имени tgt происходит в каталоге целевого объекта, указывающего требование, а не в каталоге потребляющего целевого объекта, для которого оценивается выражение.

$<TARGET_PROPERTY:prop>: Значение свойства prop для целевого объекта, для которого оценивается выражение. Обратите внимание, что для выражений генератора в Требований на использование зависимостей это потребляющий целевой объект, а не целевой объект, указывающий требование.

$<TARGET_OBJECTS:tgt>: Новое в версии 3.1.

Список объектов, полученных в результате сборки tgt. Это обычно используется для целевых объектов библиотек объектов.

$<TARGET_POLICY:policy>: 1 если policy было NEW при создании целевого объекта 'head', иначе 0. Если policy не было установлено, сообщение об ошибке для политики будет выведено. Это выражение генератора работает только для подмножества политик.

$<TARGET_FILE:tgt>

Полный путь к бинарному файлу целевого объекта.

Обратите внимание, что tgt не добавляется в качестве зависимости к целевому объекту, если это выражение не используется в add_custom_command() или add_custom_target().

$<TARGET_FILE_BASE_NAME:tgt>

Новое в версии 3.15.

Базовое имя tgt, т. е. $<TARGET_FILE_NAME:tgt> без префикса и суффикса. Например, если имя файла целевого бинарника libbase.so, базовое имя base.

См. также свойства целевого объекта OUTPUT_NAME, ARCHIVE_OUTPUT_NAME, LIBRARY_OUTPUT_NAME и RUNTIME_OUTPUT_NAME и их конфигурационно-зависимые варианты OUTPUT_NAME_<CONFIG>, ARCHIVE_OUTPUT_NAME_<CONFIG>, LIBRARY_OUTPUT_NAME_<CONFIG> и RUNTIME_OUTPUT_NAME_<CONFIG>.

Также можно рассмотреть свойства целевого объекта <CONFIG>_POSTFIX и DEBUG_POSTFIX.

$<TARGET_FILE_PREFIX:tgt>

Новое в версии 3.15.

Префикс имени файла целевого бинарника (например, lib).

См. также свойство целевого объекта PREFIX.

$<TARGET_FILE_SUFFIX:tgt>

Новое в версии 3.15.

Суффикс имени файла целевого бинарника (расширение, например, .so или .exe).

См. также свойство целевого объекта SUFFIX.

$<TARGET_FILE_NAME:tgt>

Имя файла целевого бинарника.

Обратите внимание, что tgt не добавляется в качестве зависимости к целевому объекту (см. политику CMP0112).

$<TARGET_FILE_DIR:tgt>

Директория бинарного файла целевого объекта.

Обратите внимание, что tgt не добавляется в качестве зависимости к целевому объекту (см. политику CMP0112).

$<TARGET_IMPORT_FILE:tgt>

Новое в версии 3.27.

Полный путь к файлу импорта компоновщика. На платформах DLL это будет файл .lib . Для исполняемых файлов на AIX и для библиотек динамической компоновки на macOS это могут быть, соответственно, файлы импорта .imp или .tbd в зависимости от значения свойства ENABLE_EXPORTS.

Это расширяется до пустой строки, когда нет файла импорта, связанного с целевым объектом.

END_OF_DOCUMENT_MARKER ```

$<TARGET_IMPORT_FILE_BASE_NAME:tgt>

Новое в версии 3.27.

Базовое имя файла импорта компоновщика целевого объекта tgt без префикса или суффикса. Например, если имя целевого файла libbase.tbd, то базовое имя base.

См. также целевые свойства OUTPUT_NAME и ARCHIVE_OUTPUT_NAME и их конфигурационно-специфические варианты OUTPUT_NAME_<CONFIG> и ARCHIVE_OUTPUT_NAME_<CONFIG>.

Также можно учитывать целевые свойства <CONFIG>_POSTFIX и DEBUG_POSTFIX.

Обратите внимание, что tgt не добавляется в качестве зависимости целевого объекта, для которого вычисляется данное выражение.

$<TARGET_IMPORT_FILE_PREFIX:tgt>

Новое в версии 3.27.

Префикс файла импорта целевого объекта tgt.

См. также целевое свойство IMPORT_PREFIX.

$<TARGET_IMPORT_FILE_SUFFIX:tgt>

Новое в версии 3.27.

Суффикс файла импорта целевого объекта tgt.

Суффикс соответствует расширению файла (например, .lib или .tbd).

См. также целевое свойство IMPORT_SUFFIX.

$<TARGET_IMPORT_FILE_NAME:tgt>

Новое в версии 3.27.

Имя файла импорта целевого объекта tgt.

$<TARGET_IMPORT_FILE_DIR:tgt>

Новое в версии 3.27.

Директория файла импорта целевого объекта tgt.

$<TARGET_LINKER_FILE:tgt>

Файл, используемый при компоновке с целевым объектом tgt. Обычно это библиотека, которую tgt представляет (.a, .lib, .so), но для общей библиотеки на платформах DLL это файл импорта DLL, связанный с DLL.

Новое в версии 3.27: На macOS это может быть файл импорта, связанный с общей библиотекой, в зависимости от значения свойства ENABLE_EXPORTS.

Это выражение генератора эквивалентно выражениям генератора $<TARGET_LINKER_LIBRARY_FILE> или $<TARGET_LINKER_IMPORT_FILE>, в зависимости от характеристик целевого объекта и платформы.

$<TARGET_LINKER_FILE_BASE_NAME:tgt>

Новое в версии 3.15.

Базовое имя файла, используемого для компоновки целевого объекта tgt, т.е. $<TARGET_LINKER_FILE_NAME:tgt> без префикса и суффикса. Например, если имя целевого файла libbase.a, то базовое имя base.

См. также целевые свойства OUTPUT_NAME, ARCHIVE_OUTPUT_NAME и LIBRARY_OUTPUT_NAME и их конфигурационно-специфические варианты OUTPUT_NAME_<CONFIG>, ARCHIVE_OUTPUT_NAME_<CONFIG> и LIBRARY_OUTPUT_NAME_<CONFIG>.

Также можно учитывать целевые свойства <CONFIG>_POSTFIX и DEBUG_POSTFIX.

$<TARGET_LINKER_FILE_PREFIX:tgt>

Новое в версии 3.15.

Префикс файла, используемого для компоновки целевого объекта tgt.

См. также целевые свойства PREFIX и IMPORT_PREFIX.

$<TARGET_LINKER_FILE_SUFFIX:tgt>

Новое в версии 3.15.

Суффикс файла, используемого для компоновки, где tgt - имя целевого объекта.

Суффикс соответствует расширению файла (например, ".so" или ".lib").

См. также целевые свойства SUFFIX и IMPORT_SUFFIX.

$<TARGET_LINKER_FILE_NAME:tgt>

Имя файла, используемого для компоновки целевого объекта tgt.

Обратите внимание, что tgt не добавляется в качестве зависимости целевого объекта, для которого вычисляется данное выражение (см. политику CMP0112).

$<TARGET_LINKER_FILE_DIR:tgt>

Директория файла, используемого для компоновки целевого объекта tgt.

$<TARGET_LINKER_LIBRARY_FILE:tgt>: Новое в версии 3.27.

Файл, используемый при компоновке с целевым объектом tgt напрямую с использованием библиотеки, а не файла импорта. Обычно это библиотека, которую tgt представляет (.a, .so, .dylib). Таким образом, на платформах DLL это будет пустая строка.

$<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt>

Новое в версии 3.27.

Базовое имя файла библиотеки, используемого для компоновки целевого объекта tgt, т.е. $<TARGET_LINKER_LIBRARY_FILE_NAME:tgt> без префикса и суффикса. Например, если имя файла целевого объекта libbase.a, то базовое имя равно base.

См. также свойства целевого объекта OUTPUT_NAME, ARCHIVE_OUTPUT_NAME и LIBRARY_OUTPUT_NAME и их конфигурационно-специфические варианты OUTPUT_NAME_<CONFIG>, ARCHIVE_OUTPUT_NAME_<CONFIG> и LIBRARY_OUTPUT_NAME_<CONFIG>.

Также можно рассмотреть свойства целевого объекта <CONFIG>_POSTFIX и DEBUG_POSTFIX.

Обратите внимание, что tgt не добавляется в качестве зависимости целевого объекта, на котором вычисляется данное выражение.

$<TARGET_LINKER_LIBRARY_FILE_PREFIX:tgt>

Новое в версии 3.27.

Префикс файла библиотеки, используемого для компоновки целевого объекта tgt.

См. также свойство целевого объекта PREFIX.

$<TARGET_LINKER_LIBRARY_FILE_SUFFIX:tgt>

Новое в версии 3.27.

Суффикс файла библиотеки, используемого для компоновки целевого объекта tgt.

Суффикс соответствует расширению файла (например, ".a" или ".dylib").

См. также свойство целевого объекта SUFFIX.

$<TARGET_LINKER_LIBRARY_FILE_NAME:tgt>

Новое в версии 3.27.

Имя файла библиотеки, используемого для компоновки целевого объекта tgt.

$<TARGET_LINKER_LIBRARY_FILE_DIR:tgt>

Новое в версии 3.27.

Директория файла библиотеки, используемого для компоновки целевого объекта tgt.

$<TARGET_LINKER_IMPORT_FILE:tgt>: Новое в версии 3.27.

Файл, используемый при компоновке целевого объекта tgt с использованием файла импорта. Обычно это файл импорта, который представляет tgt (.lib, .tbd). Таким образом, когда в шаге компоновки не используется файл импорта, возвращается пустая строка.

$<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt>

Новое в версии 3.27.

Базовое имя файла импорта, используемого для компоновки целевого объекта tgt, т.е. $<TARGET_LINKER_IMPORT_FILE_NAME:tgt> без префикса и суффикса. Например, если имя файла целевого объекта libbase.tbd, то базовое имя равно base.

См. также свойства целевого объекта OUTPUT_NAME и ARCHIVE_OUTPUT_NAME и их конфигурационно-специфические варианты OUTPUT_NAME_<CONFIG> и ARCHIVE_OUTPUT_NAME_<CONFIG>.

Также можно рассмотреть свойства целевого объекта <CONFIG>_POSTFIX и DEBUG_POSTFIX.

$<TARGET_LINKER_IMPORT_FILE_PREFIX:tgt>

Новое в версии 3.27.

Префикс файла импорта, используемого для компоновки целевого объекта tgt.

См. также свойство целевого объекта IMPORT_PREFIX.

$<TARGET_LINKER_IMPORT_FILE_SUFFIX:tgt>

Новое в версии 3.27.

Суффикс файла импорта, используемого для компоновки целевого объекта tgt.

Суффикс соответствует расширению файла (например, ".lib" или ".tbd").

См. также свойство целевого объекта IMPORT_SUFFIX.

$<TARGET_LINKER_IMPORT_FILE_NAME:tgt>

Новое в версии 3.27.

Имя файла импорта, используемого для компоновки целевого объекта tgt.

$<TARGET_LINKER_IMPORT_FILE_DIR:tgt>

Новое в версии 3.27.

Директория файла импорта, используемого для компоновки целевого объекта tgt.

$<TARGET_SONAME_FILE:tgt>: Файл с soname (.so.3) где tgt — имя целевого объекта.

$<TARGET_SONAME_FILE_NAME:tgt>

Имя файла с soname (.so.3).

Обратите внимание, что tgt не добавляется в качестве зависимости целевого объекта, на котором вычисляется данное выражение (см. политику CMP0112).

$<TARGET_SONAME_FILE_DIR:tgt>

Директория файла с soname (.so.3).

$<TARGET_SONAME_IMPORT_FILE:tgt>: Новое в версии 3.27.

Файл импорта с soname (.3.tbd) где tgt — имя целевого объекта.

$<TARGET_SONAME_IMPORT_FILE_NAME:tgt>

Новое в версии 3.27.

Имя файла импорта с soname (.3.tbd).

$<TARGET_SONAME_IMPORT_FILE_DIR:tgt>

Новое в версии 3.27.

Директория файла импорта с soname (.3.tbd).

END_OF_DOCUMENT_MARKER

$<TARGET_PDB_FILE:tgt>

Новые в версии 3.1.

Полный путь к файлу базы данных программы, сгенерированному линковщиком (.pdb), где tgt — имя целевого объекта.

См. также свойства целевого объекта PDB_NAME и PDB_OUTPUT_DIRECTORY и их конфигурационно-зависимые варианты PDB_NAME_<CONFIG> и PDB_OUTPUT_DIRECTORY_<CONFIG>.

$<TARGET_PDB_FILE_BASE_NAME:tgt>

Новые в версии 3.15.

Базовое имя файла базы данных программы, сгенерированного линковщиком (.pdb), где tgt — имя целевого объекта.

Базовое имя соответствует имени файла PDB целевого объекта (см. $<TARGET_PDB_FILE_NAME:tgt>) без префикса и суффикса. Например, если имя файла целевого объекта base.pdb, то базовое имя base.

См. также свойство целевого объекта PDB_NAME и его конфигурационно-зависимый вариант PDB_NAME_<CONFIG>.

Также можно учитывать свойства целевого объекта <CONFIG>_POSTFIX и DEBUG_POSTFIX.

$<TARGET_PDB_FILE_NAME:tgt>

Новые в версии 3.1.

Имя файла базы данных программы, сгенерированного линковщиком (.pdb).

$<TARGET_PDB_FILE_DIR:tgt>

Новые в версии 3.1.

Директория файла базы данных программы, сгенерированного линковщиком (.pdb).

$<TARGET_BUNDLE_DIR:tgt>

Новые в версии 3.9.

Полный путь к директории пакета (/path/to/my.app, /path/to/my.framework, или /path/to/my.bundle), где tgt — имя целевого объекта.

$<TARGET_BUNDLE_DIR_NAME:tgt>

Новые в версии 3.24.

Имя директории пакета (my.app, my.framework, или my.bundle), где tgt — имя целевого объекта.

$<TARGET_BUNDLE_CONTENT_DIR:tgt>

Новые в версии 3.9.

Полный путь к директории содержимого пакета, где tgt — имя целевого объекта. Для macOS SDK это /path/to/my.app/Contents, /path/to/my.framework, или /path/to/my.bundle/Contents. Для всех других SDK (например, iOS) это /path/to/my.app, /path/to/my.framework, или /path/to/my.bundle из-за плоской структуры пакета.

$<TARGET_RUNTIME_DLLS:tgt>

Новые в версии 3.21.

Список DLL, от которых зависит целевой объект во время выполнения. Это определяется расположением всех SHARED целевых объектов в транзитивных зависимостях целевого объекта. Если нужны только директории DLL, используйте генераторское выражение TARGET_RUNTIME_DLL_DIRS. Использование этого генераторского выражения для целей, отличных от исполняемых файлов, SHARED библиотек и MODULE библиотек, является ошибкой. На платформах, не поддерживающих DLL, это выражение всегда вычисляет пустую строку.

Это генераторское выражение может использоваться для копирования всех DLL, от которых зависит целевой объект, в его выходную директорию в POST_BUILD пользовательской команде с помощью команды cmake -E copy -t. Например:

find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT)

add_executable(exe main.c)
target_link_libraries(exe PRIVATE foo::foo foo::bar)
add_custom_command(TARGET exe POST_BUILD
  COMMAND ${CMAKE_COMMAND} -E copy -t $<TARGET_FILE_DIR:exe> $<TARGET_RUNTIME_DLLS:exe>
  COMMAND_EXPAND_LISTS
)

Примечание

Импортированные целевые объекты поддерживаются только если они знают расположение своих .dll файлов. Импортированная SHARED библиотека должна иметь свойство IMPORTED_LOCATION, установленное на её .dll файл. Подробности см. в разделе add_library импортированные библиотеки. Многие модули поиска Find Модули генерируют импортированные целевые объекты с типом UNKNOWN и поэтому будут проигнорированы.

На платформах, поддерживающих пути во время выполнения (RPATH), см. свойство целевого объекта INSTALL_RPATH. На платформах Apple см. свойство целевого объекта INSTALL_NAME_DIR.

$<TARGET_RUNTIME_DLL_DIRS:tgt>

Новые в версии 3.27.

Список директорий, содержащих DLL, от которых зависит целевой объект во время выполнения (см. TARGET_RUNTIME_DLLS). Это определяется расположением всех SHARED целевых объектов в транзитивных зависимостях целевого объекта. Использование этого генераторского выражения для целей, отличных от исполняемых файлов, SHARED библиотек и MODULE библиотек, является ошибкой. На платформах, не поддерживающих DLL, это выражение всегда вычисляет пустую строку.

Это генераторское выражение, например, может использоваться для создания текстового файла с помощью file(GENERATE) для соответствующей установки переменной среды PATH.

Выражения экспорта и установки

$<INSTALL_INTERFACE:...>: Содержимое ... при экспорте свойства с помощью install(EXPORT), в противном случае пусто.

$<BUILD_INTERFACE:...>: Содержимое ... при экспорте свойства с помощью export() или когда целевой объект используется другим целевым объектом в той же системе сборки. В противном случае возвращает пустую строку.

$<BUILD_LOCAL_INTERFACE:...>: Новые в версии 3.26.

Содержимое ... при использовании целевого объекта другим целевым объектом в одной и той же системе сборки. В противном случае возвращает пустую строку.

$<INSTALL_PREFIX>: Содержимое префикса установки, когда целевой объект экспортируется с помощью install(EXPORT), или когда вычисляется в свойстве INSTALL_NAME_DIR, аргумент INSTALL_NAME_DIR команды install(RUNTIME_DEPENDENCY_SET), аргумент code команды install(CODE), или аргумент file команды install(SCRIPT), и пустая строка в противном случае.

Многоуровневая оценка выражений

$<GENEX_EVAL:expr>: Новая функция в версии 3.12.

Содержимое expr вычисляется как выражение генератора в текущем контексте. Это позволяет использовать выражения генератора, результаты вычисления которых сами являются выражениями генератора.

$<TARGET_GENEX_EVAL:tgt,expr>

Новая функция в версии 3.12.

Содержимое expr вычисляется как выражение генератора в контексте целевого объекта tgt. Это позволяет использовать пользовательские свойства целевых объектов, которые сами содержат выражения генератора.

Возможность вычисления выражений генератора очень полезна, когда нужно управлять пользовательскими свойствами, поддерживающими выражения генератора. Например:

add_library(foo ...)

set_property(TARGET foo PROPERTY
  CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>
)

add_custom_target(printFooKeys
  COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS>
)

Эта упрощенная реализация пользовательской команды printFooKeys неверна, потому что свойство целевого объекта CUSTOM_KEYS не вычисляется, и содержимое передается как есть (то есть $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>).

Чтобы получить ожидаемый результат (то есть FOO_EXTRA_THINGS если config Debug), необходимо вычислить результат $<TARGET_PROPERTY:foo,CUSTOM_KEYS>.

add_custom_target(printFooKeys
  COMMAND ${CMAKE_COMMAND} -E
    echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>>
)

Экранированные символы

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

$<ANGLE-R>: Литеральный >. Используется, например, для сравнения строк, содержащих >.

$<COMMA>: Литеральный ,. Используется, например, для сравнения строк, содержащих ,.

$<SEMICOLON>: Литеральный ;. Используется для предотвращения расширения списка в аргументе с ;.

Устаревшие выражения

$<CONFIGURATION>: Имя конфигурации. Устарело с CMake 3.0. Используйте CONFIG вместо этого.

© 2000–2024 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.27/manual/cmake-generator-expressions.7.html