# macro

Start recording a macro for later invocation as a command:

    macro(<name> [arg1 [arg2 [arg3 ...]]])
      COMMAND1(ARGS ...)
      COMMAND2(ARGS ...)
      ...
    endmacro(<name>)

Define a macro named `<name>` that takes arguments named `arg1`, `arg2`, `arg3`, (…). Commands listed after macro, but before the matching `endmacro()`, are not invoked until the macro is invoked. When it is invoked, the commands recorded in the macro are first modified by replacing formal parameters (`${arg1}`) with the arguments passed, and then invoked as normal commands. In addition to referencing the formal parameters you can reference the values `${ARGC}` which will be set to the number of arguments passed into the function as well as `${ARGV0}`, `${ARGV1}`, `${ARGV2}`, … which will have the actual values of the arguments passed in. This facilitates creating macros with optional arguments. Additionally `${ARGV}` holds the list of all arguments given to the macro and `${ARGN}` holds the list of arguments past the last expected argument. Referencing to `${ARGV#}` arguments beyond `${ARGC}` have undefined behavior. Checking that `${ARGC}` is greater than `#` is the only way to ensure that `${ARGV#}` was passed to the function as an extra argument.

See the `cmake_policy()` command documentation for the behavior of policies inside macros.

## Macro Argument Caveats

Note that the parameters to a macro and values such as `ARGN` are not variables in the usual CMake sense. They are string replacements much like the C preprocessor would do with a macro. Therefore you will NOT be able to use commands like:

    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

In the first case, you can use `if(${ARGV1})`. In the second and third case, the proper way to check if an optional variable was passed to the macro is to use `if(${ARGC} GREATER 2)`. In the last case, you can use `foreach(loop_var ${ARGN})` but this will skip empty arguments. If you need to include them, you can use:

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

Note that if you have a variable with the same name in the scope from which the macro is called, using unreferenced names will use the existing variable instead of the arguments. For example:

    macro(_BAR)
      foreach(arg IN LISTS ARGN)
        [...]
      endforeach()
    endmacro()

    function(_FOO)
      _bar(x y z)
    endfunction()

    _foo(a b c)

Will loop over `a;b;c` and not over `x;y;z` as one might be expecting. If you want true CMake variables and/or better CMake scope control you should look at the function command.