68 lines
2.3 KiB
ReStructuredText
68 lines
2.3 KiB
ReStructuredText
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.
|