diff options
Diffstat (limited to 'Help/command/macro.rst')
| -rw-r--r-- | Help/command/macro.rst | 43 |
1 files changed, 26 insertions, 17 deletions
diff --git a/Help/command/macro.rst b/Help/command/macro.rst index 258dc50..6bee69c 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst @@ -1,9 +1,7 @@ macro ----- -Start recording a macro for later invocation as a command. - -:: +Start recording a macro for later invocation as a command:: macro(<name> [arg1 [arg2 [arg3 ...]]]) COMMAND1(ARGS ...) @@ -11,22 +9,28 @@ Start recording a macro for later invocation as a command. ... 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. +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 cmake_policy() command documentation for the behavior of -policies inside macros. +See the :command:`cmake_policy()` command documentation for the behavior +of policies inside macros. Macro Argument Caveats ^^^^^^^^^^^^^^^^^^^^^^ @@ -37,10 +41,15 @@ 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 case, you can -use ``foreach(loop_var ${ARGN})`` but this will skip empty arguments. +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}") |