| 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. |
| |
| 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 |
| foreach(loop_var IN LISTS ARGN) # ARGN is not a variable |
| |
| In the first case you can use ``if(${ARGV1})``, in the second 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. |