c2efb3efcd
Revise docs for all "Scripting Commands", except four find_XXX that use a macro suite of their own. * Take full advantage of the improved syntax highlighting. * Make consequential use of <..> placeholders. * Clarify things here and there in the text. Specific improvements to some command docs: * "math": Correct description of novel hexadecimal capability. * "if", "foreach", "while": Provide link to "endif" etc * "foreach", "while": Mention "break" and "continue". * "foreach": Simplify explanation of ``RANGE`` and ``IN`` signatures; advise against negative arguments or reverse ranges (compare issue #18461) * "endif", "endfunction" etc: Explain that the argument is optional and maintained for compatibility only
85 lines
2.8 KiB
ReStructuredText
85 lines
2.8 KiB
ReStructuredText
macro
|
|
-----
|
|
|
|
Start recording a macro for later invocation as a command
|
|
|
|
.. code-block:: cmake
|
|
|
|
macro(<name> [<arg1> ...])
|
|
<commands>
|
|
endmacro(<name>)
|
|
|
|
Defines a macro named ``<name>`` that takes arguments
|
|
named ``<arg1>``, ...
|
|
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.
|
|
|
|
Furthermore, ``${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
|
|
|
|
.. code-block:: cmake
|
|
|
|
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
|
|
|
|
.. code-block:: cmake
|
|
|
|
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:
|
|
|
|
.. code-block:: cmake
|
|
|
|
macro(_BAR)
|
|
foreach(arg IN LISTS ARGN)
|
|
<commands>
|
|
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.
|