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 приводит к ошибке.

Добавлен в версии 3.28: Это выражение генератора выполняется по принципу короткой цепочки, таким образом, выражения генератора в false_string не будут оцениваться, когда condition равно 1, а выражения генератора в true_string не будут оцениваться, когда условие равно 0.

Обычно 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.

Добавлено в версии 3.28: Логические операторы используют короткое замыкание, поэтому выражения-генераторы в списке аргументов не будут вычисляться, как только будет определено возвращаемое значение.

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

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.

END_OF_DOCUMENT_MARKER

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

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

Toolchain And Language Expressions

Platform

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

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

Compiler Version

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Версия используемого компилятора Objective-C++.

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

1 если версия компилятора Objective-C++ соответствует 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.

Compiler Language, ID, and Frontend-Variant

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

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

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

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

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

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

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

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

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

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

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

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

Идентификатор компилятора Objective-C, используемый CMake.

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

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

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

Идентификатор компилятора Objective-C++, используемый CMake.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вариант фронтенда компилятора C, используемый CMake.

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

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

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

Вариант фронтенда компилятора C++, используемый CMake.

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

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

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

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

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

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

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

Вариант фронтенда компилятора Objective-C, используемый CMake.

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

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

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

Вариант фронтенда компилятора Objective-C++, используемый CMake.

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

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

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

Идентификатор компилятора Fortran, используемый CMake.

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

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

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

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

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

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

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

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

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

где compiler_ids — список, разделённый запятыми. 1 если вариант фронтенда компилятора ISPC CMake соответствует одному из элементов в 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, а идентификатор компилятора CMake для 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:features>: Добавлена в версии 3.1.

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

Контекст компиляции

$<COMPILE_ONLY:...>

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

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

Примеры использования — для использования только заголовков, где известно, что все использования не требуют связывания (например, все библиотеки шаблонов 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-компонователя, его нельзя указать как простое имя библиотеки, например, 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 типа OBJECT или INTERFACE проигнорирует аспект функции выражения и вместо этого будет слинкован стандартным способом.
Выражение генератора $<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>). Это выражение может быть использовано только для указания параметров линковки.

Зависимые от целевого объекта выражения

Метаданные целевого объекта

Эти выражения ищут информацию о целевом объекте.

$<TARGET_EXISTS:tgt>: Добавлена в версии 3.12.

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

$<TARGET_NAME_IF_EXISTS:tgt>

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

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

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

$<TARGET_NAME:tgt>: Имя целевого объекта tgt в указанном виде. Это отмечает tgt как имя целевого объекта внутри более крупного выражения, что необходимо при экспорте целевых объектов в несколько зависимых наборов экспорта. Текст tgt должен быть буквальным именем целевого объекта; он не может содержать генераторские выражения. Целевой объект не обязательно должен существовать.

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

Свойства целевых объектов

Эти выражения ищут значения свойств целевых объектов.

$<TARGET_PROPERTY:tgt,prop>

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

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

Изменено в версии 3.31: Генераторские выражения для свойств интерфейса, передающихся по цепочке, такие как $<TARGET_PROPERTY:target,INTERFACE_*>, теперь правильно обрабатывают повторные оценки внутри вложенных генераторских выражений. Раньше эти повторные оценки возвращали пустые значения из-за оптимизации для транзитивных замыканий. Это изменение гарантирует согласованную оценку для операций, не являющихся объединением.

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

Для некоторых свойств выражения имеют особые правила оценки:

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

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

Для свойств компиляции целевого объекта оценка соответствующих требований к использованию передаётся по цепочке по замыканию связанных целевых объектов INTERFACE_LINK_LIBRARIES исключая записи, защищённые генераторским выражением LINK_ONLY.
Для свойств линковки целевого объекта оценка соответствующих требований к использованию передаётся по цепочке по замыканию связанных целевых объектов INTERFACE_LINK_LIBRARIES включая записи, защищённые генераторским выражением LINK_ONLY. См. политику CMP0166.

Оценка LINK_LIBRARIES сама по себе не передаётся по цепочке.

Свойства требований к использованию целевого объекта

Эти выражения оцениваются как список, разделённый точкой с запятой, представляющий объединение значения самого целевого объекта со значениями тех же свойств для целевых объектов, имена которых указаны в INTERFACE_LINK_LIBRARIES:

Для свойств компиляции, передающихся по цепочке, оценка передаётся по цепочке по замыканию целевых объектов INTERFACE_LINK_LIBRARIES исключая записи, защищённые генераторским выражением LINK_ONLY.
Для свойств линковки, передающихся по цепочке, оценка передаётся по цепочке по замыканию целевых объектов INTERFACE_LINK_LIBRARIES включая записи, защищённые генераторским выражением LINK_ONLY. См. политику CMP0166.

Оценка INTERFACE_LINK_LIBRARIES сама по себе не передаётся по цепочке.

Пользовательские свойства, передающиеся по цепочке

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

Эти значения обрабатываются во время вычисления следующим образом:

Вычисление $<TARGET_PROPERTY:tgt,PROP> для некоторого свойства PROP, названного без префикса INTERFACE_, проверяет свойства TRANSITIVE_COMPILE_PROPERTIES и TRANSITIVE_LINK_PROPERTIES на целевом объекте tgt, на целевых объектах, именованных с помощью его LINK_LIBRARIES, и на транзитивном замыкании целевых объектов, именованных с помощью INTERFACE_LINK_LIBRARIES связанных целевых объектов.

Если PROP указано одним из этих свойств, тогда оно вычисляется как список, разделённый точками с запятой, представляющий объединение значения на самом целевом объекте с значениями соответствующего INTERFACE_PROP на целевых объектах, именованных с помощью LINK_LIBRARIES:
- Если PROP названо с помощью TRANSITIVE_COMPILE_PROPERTIES, вычисление соответствующего INTERFACE_PROP является транзитивным относительно замыкания связанных целевых объектов INTERFACE_LINK_LIBRARIES, исключая записи, защищённые выражением генератора LINK_ONLY.
- Если PROP названо с помощью TRANSITIVE_LINK_PROPERTIES, вычисление соответствующего INTERFACE_PROP является транзитивным относительно замыкания связанных целевых объектов INTERFACE_LINK_LIBRARIES, включая записи, защищённые выражением генератора LINK_ONLY.
Вычисление $<TARGET_PROPERTY:tgt,INTERFACE_PROP> для некоторого свойства INTERFACE_PROP, названного с префиксом INTERFACE_, проверяет свойства TRANSITIVE_COMPILE_PROPERTIES и TRANSITIVE_LINK_PROPERTIES на целевом объекте tgt, и на транзитивном замыкании целевых объектов, именованных с помощью INTERFACE_LINK_LIBRARIES.

Если соответствующее PROP указано одним из этих свойств, тогда INTERFACE_PROP вычисляется как список, разделённый точками с запятой, представляющий объединение значения на целевом объекте с значением того же свойства на целевых объектах, именованных с помощью INTERFACE_LINK_LIBRARIES:
- Если PROP названо с помощью TRANSITIVE_COMPILE_PROPERTIES, вычисление соответствующего INTERFACE_PROP является транзитивным относительно замыкания связанных целевых объектов INTERFACE_LINK_LIBRARIES, исключая записи, защищённые выражением генератора LINK_ONLY.
- Если PROP названо с помощью TRANSITIVE_LINK_PROPERTIES, вычисление соответствующего INTERFACE_PROP является транзитивным относительно замыкания связанных целевых объектов INTERFACE_LINK_LIBRARIES, включая записи, защищённые выражением генератора LINK_ONLY.

Если PROP названо и с помощью TRANSITIVE_COMPILE_PROPERTIES, и с помощью TRANSITIVE_LINK_PROPERTIES, то последнее имеет приоритет.

Совместимые свойства интерфейса

Эти значения вычисляются как единое значение, составленное из значения самого целевого объекта, значений целевых объектов, именованных с помощью LINK_LIBRARIES, и из транзитивного замыкания целевых объектов, именованных с помощью INTERFACE_LINK_LIBRARIES. Значения совместимого свойства интерфейса от нескольких целевых объектов объединяются в соответствии с типом совместимости, требуемым свойством COMPATIBLE_INTERFACE_*, определяющим его.

Артефакты целевого объекта

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

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

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

$<TARGET_FILE:tgt>

Полный путь к двоичному файлу tgt.

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

END_OF_DOCUMENT_MARKER

$<TARGET_FILE_BASE_NAME:tgt>

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

Базовое имя tgt, т.е. $<TARGET_FILE_NAME:tgt> без префикса и суффикса. Например, если имя файла 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.

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

$<TARGET_FILE_PREFIX:tgt>

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

Префикс имени файла tgt (например, lib).

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

$<TARGET_FILE_SUFFIX:tgt>

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

Суффикс имени файла tgt (расширение, например, .so или .exe).

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

$<TARGET_FILE_NAME:tgt>

Имя файла tgt.

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

$<TARGET_FILE_DIR:tgt>

Директория двоичного файла tgt.

$<TARGET_IMPORT_FILE:tgt>

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

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

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

$<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.

$<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 это будет библиотека импорта .lib DLL.

Добавлен в версии 3.27: На macOS это может быть файл импорта .tbd общей библиотеки, в зависимости от значения свойства 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.

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

$<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.

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

$<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). Таким образом, если в процессе линковки импортный файл не используется, возвращается пустая строка.

END_OF_DOCUMENT_MARKER

$<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).

$<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).

$<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 — имя целевого объекта.

END_OF_DOCUMENT_MARKER

$<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 из-за плоской структуры пакета.

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

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

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

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

Изменено в версии 3.27: Возвращает содержимое префикса установки в аргументе `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 если конфигурация 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>: Литеральный ;. Используется для предотвращения расширения списка в аргументе с ;.

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

Литеральный ". Используется для разрешения использования строковых литералов в выражениях генератора.

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

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

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