macro

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

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

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

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

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

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

Вызов

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

macro(foo)
  <commands>
endmacro()

может быть вызван любым из

foo()
Foo()
FOO()

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

Аргументы

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

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

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

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

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

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

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

Особенности аргументов

Так как 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, следует обратиться к команде функции.