макрос

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

macro(<name> [<arg1> ...])
  <commands>
endmacro()

Определяет макрос с именем <name>, принимающий аргументы с именами <arg1>, ... Команды, перечисленные после макроса, но перед соответствующим endmacro(), не будут выполнены до вызова макроса.

Согласно предыдущим версиям, команда endmacro() допускает необязательный <name> аргумент. Если он используется, он должен быть точной копией аргумента открывающей команды macro.

См. документацию команды cmake_policy() для поведения политик внутри макросов.

См. раздел Макрос против функции ниже для отличий между CMake-макросами и командой functions.

Вызов

Вызов макроса регистронезависим. Макрос, определенный как

macro(foo)
  <commands>
endmacro()

может быть вызван с помощью любого из

foo()
Foo()
FOO()
cmake_language(CALL foo)

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

Аргументы

Когда макрос вызывается, команды, записанные в макросе, сначала изменяются заменой формальных параметров (${arg1}, ...) на переданные аргументы, а затем вызываются как обычные команды.

В дополнение к ссылке на формальные параметры вы можете ссылаться на значения ${ARGC}, которые будут установлены в число переданных аргументов, а также на ${ARGV0}, ${ARGV1}, ${ARGV2}, ... которые будут содержать фактические значения переданных аргументов. Это позволяет создавать макросы с необязательными аргументами.

Кроме того, ${ARGV} содержит список всех переданных аргументов, а ${ARGN} содержит список аргументов, начиная с последнего ожидаемого аргумента. Ссылка на аргументы ${ARGV#} за пределами ${ARGC} имеет неопределенное поведение. Проверка того, что ${ARGC} больше #, — единственный способ гарантировать, что ${ARGV#} был передан функции в качестве дополнительного аргумента.

Макрос против функции

Команда macro очень похожа на команду function(). Тем не менее, существуют некоторые важные отличия.

В функции ARGN, ARGC, ARGV и ARGV0, ARGV1, ... — это настоящие переменные в обычном смысле CMake. В макросе они таковыми не являются, они — строковые замены, подобные тому, как это делает препроцессор C с макросом. Это имеет ряд последствий, которые объясняются в разделе Ограничения аргументов ниже.

Другое различие между макросами и функциями — это поток управления. Функция выполняется путем передачи управления от вызывающей строки к телу функции. Макрос выполняется как если бы тело макроса было вставлено вместо вызывающей строки. Это означает, что return() в теле макроса не просто завершает выполнение макроса, а возвращает управление из области вызова макроса. Для избежания путаницы рекомендуется вообще избегать return() в макросах.

В отличие от функции, переменные CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNCTION_LIST_DIR, CMAKE_CURRENT_FUNCTION_LIST_FILE, CMAKE_CURRENT_FUNCTION_LIST_LINE для макроса не задаются.

Ограничения аргументов

Поскольку ARGN, ARGC, ARGV, ARGV0 и т.д. не являются переменными, вы НЕ сможете использовать команды, такие как

if(ARGV1) # ARGV1 is not a variable
if(DEFINED ARGV2) # ARGV2 is not a variable
if(ARGC GREATER 2) # ARGC is not a variable
foreach(loop_var IN LISTS ARGN) # ARGN is not a variable

В первом случае вы можете использовать if(${ARGV1}). Во втором и третьем случае правильным способом проверки того, что необязательная переменная была передана макросу, является использование if(${ARGC} GREATER 2). В последнем случае вы можете использовать foreach(loop_var ${ARGN}), но это пропустит пустые аргументы. Если вам нужно их включить, вы можете использовать

set(list_var "${ARGN}")
foreach(loop_var IN LISTS list_var)

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

macro(bar)
  foreach(arg IN LISTS ARGN)
    <commands>
  endforeach()
endmacro()

function(foo)
  bar(x y z)
endfunction()

foo(a b c)

Будет перебирать a;b;c и не перебирать x;y;z, как можно было ожидать. Если вам нужны настоящие переменные CMake и/или лучший контроль над областью CMake, вы должны использовать команду function.