diff options
author | Chaoren Lin <aoe@google.com> | 2016-07-12 11:53:58 -0700 |
---|---|---|
committer | Chaoren Lin <aoe@google.com> | 2016-07-13 11:35:29 -0700 |
commit | ecf0ec027d28d2c26ce13075003dc57db20d279e (patch) | |
tree | 8ad8b5881235f6e813451e8916201104d8155bd5 /share/cmake-3.6/Help/command/macro.rst | |
parent | 091caafda44f7fe52a94387b2eafcf204ea909d3 (diff) | |
download | linux-x86-ecf0ec027d28d2c26ce13075003dc57db20d279e.tar.gz |
Update prebuilts to CMake 3.6.0-rc2 (go/ab/3043163).
Change-Id: Ibe6715663df09f1d9ac5fcb588e12c657b2caab1
Diffstat (limited to 'share/cmake-3.6/Help/command/macro.rst')
-rw-r--r-- | share/cmake-3.6/Help/command/macro.rst | 76 |
1 files changed, 76 insertions, 0 deletions
diff --git a/share/cmake-3.6/Help/command/macro.rst b/share/cmake-3.6/Help/command/macro.rst new file mode 100644 index 0000000..6bee69c --- /dev/null +++ b/share/cmake-3.6/Help/command/macro.rst @@ -0,0 +1,76 @@ +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. |