"Fossies" - the Fresh Open Source Software Archive

Member "cmake-3.6.2-win32-x86/share/cmake-3.6/Help/command/macro.rst" (7 Sep 2016, 2870 Bytes) of archive /windows/misc/cmake-3.6.2-win32-x86.zip:

As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.


Start recording a macro for later invocation as a command::

macro( [arg1 [arg2 [arg3 …]]]) COMMAND1(ARGS …) COMMAND2(ARGS …) … endmacro()

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.