You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
77 lines
2.7 KiB
77 lines
2.7 KiB
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
|
|
:command:`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 :command:`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.
|