1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
macro
-----
Start recording a macro for later invocation as a command
.. code-block:: cmake
macro(<name> [<arg1> ...])
<commands>
endmacro()
Defines a macro named ``<name>`` that takes arguments named
``<arg1>``, ... Commands listed after macro, but before the
matching :command:`endmacro()`, are not executed until the macro
is invoked.
Per legacy, the :command:`endmacro` command admits an optional
``<name>`` argument. If used, it must be a verbatim repeat of the
argument of the opening ``macro`` command.
See the :command:`cmake_policy()` command documentation for the behavior
of policies inside macros.
See the :ref:`Macro vs Function` section below for differences
between CMake macros and :command:`functions <function>`.
Invocation
^^^^^^^^^^
The macro invocation is case-insensitive. A macro defined as
.. code-block:: cmake
macro(foo)
<commands>
endmacro()
can be invoked through any of
.. code-block:: cmake
foo()
Foo()
FOO()
cmake_language(CALL foo)
and so on. However, it is strongly recommended to stay with the
case chosen in the macro definition. Typically macros use
all-lowercase names.
The :command:`cmake_language(CALL ...)` command can also be used to
invoke the macro.
Arguments
^^^^^^^^^
When a macro 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.
.. _`Macro vs Function`:
Macro vs Function
^^^^^^^^^^^^^^^^^
The ``macro`` command is very similar to the :command:`function` command.
Nonetheless, there are a few important differences.
In a function, ``ARGN``, ``ARGC``, ``ARGV`` and ``ARGV0``, ``ARGV1``, ...
are true variables in the usual CMake sense. In a macro, they are not,
they are string replacements much like the C preprocessor would do
with a macro. This has a number of consequences, as explained in
the :ref:`Argument Caveats` section below.
Another difference between macros and functions is the control flow.
A function is executed by transferring control from the calling
statement to the function body. A macro is executed as if the macro
body were pasted in place of the calling statement. This has the
consequence that a :command:`return()` in a macro body does not
just terminate execution of the macro; rather, control is returned
from the scope of the macro call. To avoid confusion, it is recommended
to avoid :command:`return()` in macros altogether.
Unlike a function, the :variable:`CMAKE_CURRENT_FUNCTION`,
:variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`,
:variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`,
:variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE` variables are not
set for a macro.
.. _`Argument Caveats`:
Argument Caveats
^^^^^^^^^^^^^^^^
Since ``ARGN``, ``ARGC``, ``ARGV``, ``ARGV0`` etc. are not variables,
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 have expected.
If you want true CMake variables and/or better CMake scope control you
should look at the function command.
|
