mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-06 05:40:54 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Revise docs on Scripting Commands

Browse Source 
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
This commit is contained in:
Joachim Wuttke (l)
2018-10-16 21:50:48 +02:00
committed by Joachim Wuttke (o)
parent 7053dd301c
commit c2efb3efcd
41 changed files with 478 additions and 325 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
Help/command/macro.rst
View File

@@ -1,27 +1,29 @@
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 ...)
COMMAND2(ARGS ...)
...
.. code-block:: cmake
macro(<name> [<arg1> ...])
<commands>
endmacro(<name>)
Define a macro named ``<name>`` that takes arguments named ``arg1``,
``arg2``, ``arg3``, (...).
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.
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
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
@@ -38,7 +40,9 @@ 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::
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
@@ -50,18 +54,22 @@ 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::
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::
existing variable instead of the arguments. For example:
.. code-block:: cmake
macro(_BAR)
foreach(arg IN LISTS ARGN)
[...]
<commands>
endforeach()
endmacro()