1cmake_language
2--------------
3
4.. versionadded:: 3.18
5
6Call meta-operations on CMake commands.
7
8Synopsis
9^^^^^^^^
10
11.. parsed-literal::
12
13  cmake_language(`CALL`_ <command> [<arg>...])
14  cmake_language(`EVAL`_ CODE <code>...)
15  cmake_language(`DEFER`_ <options>... CALL <command> [<arg>...])
16
17Introduction
18^^^^^^^^^^^^
19
20This command will call meta-operations on built-in CMake commands or
21those created via the :command:`macro` or :command:`function` commands.
22
23``cmake_language`` does not introduce a new variable or policy scope.
24
25Calling Commands
26^^^^^^^^^^^^^^^^
27
28.. _CALL:
29
30.. code-block:: cmake
31
32  cmake_language(CALL <command> [<arg>...])
33
34Calls the named ``<command>`` with the given arguments (if any).
35For example, the code:
36
37.. code-block:: cmake
38
39  set(message_command "message")
40  cmake_language(CALL ${message_command} STATUS "Hello World!")
41
42is equivalent to
43
44.. code-block:: cmake
45
46  message(STATUS "Hello World!")
47
48.. note::
49  To ensure consistency of the code, the following commands are not allowed:
50
51  * ``if`` / ``elseif`` / ``else`` / ``endif``
52  * ``while`` / ``endwhile``
53  * ``foreach`` / ``endforeach``
54  * ``function`` / ``endfunction``
55  * ``macro`` / ``endmacro``
56
57Evaluating Code
58^^^^^^^^^^^^^^^
59
60.. _EVAL:
61
62.. code-block:: cmake
63
64  cmake_language(EVAL CODE <code>...)
65
66Evaluates the ``<code>...`` as CMake code.
67
68For example, the code:
69
70.. code-block:: cmake
71
72  set(A TRUE)
73  set(B TRUE)
74  set(C TRUE)
75  set(condition "(A AND B) OR C")
76
77  cmake_language(EVAL CODE "
78    if (${condition})
79      message(STATUS TRUE)
80    else()
81      message(STATUS FALSE)
82    endif()"
83  )
84
85is equivalent to
86
87.. code-block:: cmake
88
89  set(A TRUE)
90  set(B TRUE)
91  set(C TRUE)
92  set(condition "(A AND B) OR C")
93
94  file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
95    if (${condition})
96      message(STATUS TRUE)
97    else()
98      message(STATUS FALSE)
99    endif()"
100  )
101
102  include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)
103
104Deferring Calls
105^^^^^^^^^^^^^^^
106
107.. versionadded:: 3.19
108
109.. _DEFER:
110
111.. code-block:: cmake
112
113  cmake_language(DEFER <options>... CALL <command> [<arg>...])
114
115Schedules a call to the named ``<command>`` with the given arguments (if any)
116to occur at a later time.  By default, deferred calls are executed as if
117written at the end of the current directory's ``CMakeLists.txt`` file,
118except that they run even after a :command:`return` call.  Variable
119references in arguments are evaluated at the time the deferred call is
120executed.
121
122The options are:
123
124``DIRECTORY <dir>``
125  Schedule the call for the end of the given directory instead of the
126  current directory.  The ``<dir>`` may reference either a source
127  directory or its corresponding binary directory.  Relative paths are
128  treated as relative to the current source directory.
129
130  The given directory must be known to CMake, being either the top-level
131  directory or one added by :command:`add_subdirectory`.  Furthermore,
132  the given directory must not yet be finished processing.  This means
133  it can be the current directory or one of its ancestors.
134
135``ID <id>``
136  Specify an identification for the deferred call.
137  The ``<id>`` may not be empty and may not begin with a capital letter ``A-Z``.
138  The ``<id>`` may begin with an underscore (``_``) only if it was generated
139  automatically by an earlier call that used ``ID_VAR`` to get the id.
140
141``ID_VAR <var>``
142  Specify a variable in which to store the identification for the
143  deferred call.  If ``ID <id>`` is not given, a new identification
144  will be generated and the generated id will start with an underscore (``_``).
145
146The currently scheduled list of deferred calls may be retrieved:
147
148.. code-block:: cmake
149
150  cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)
151
152This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
153Lists>` of deferred call ids.  The ids are for the directory scope in which
154the calls have been deferred to (i.e. where they will be executed), which can
155be different to the scope in which they were created.  The ``DIRECTORY``
156option can be used to specify the scope for which to retrieve the call ids.
157If that option is not given, the call ids for the current directory scope will
158be returned.
159
160Details of a specific call may be retrieved from its id:
161
162.. code-block:: cmake
163
164  cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)
165
166This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
167Lists>` in which the first element is the name of the command to be
168called, and the remaining elements are its unevaluated arguments (any
169contained ``;`` characters are included literally and cannot be distinguished
170from multiple arguments).  If multiple calls are scheduled with the same id,
171this retrieves the first one.  If no call is scheduled with the given id in
172the specified ``DIRECTORY`` scope (or the current directory scope if no
173``DIRECTORY`` option is given), this stores an empty string in the variable.
174
175Deferred calls may be canceled by their id:
176
177.. code-block:: cmake
178
179  cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)
180
181This cancels all deferred calls matching any of the given ids in the specified
182``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option
183is given).  Unknown ids are silently ignored.
184
185Deferred Call Examples
186""""""""""""""""""""""
187
188For example, the code:
189
190.. code-block:: cmake
191
192  cmake_language(DEFER CALL message "${deferred_message}")
193  cmake_language(DEFER ID_VAR id CALL message "Canceled Message")
194  cmake_language(DEFER CANCEL_CALL ${id})
195  message("Immediate Message")
196  set(deferred_message "Deferred Message")
197
198prints::
199
200  Immediate Message
201  Deferred Message
202
203The ``Cancelled Message`` is never printed because its command is
204canceled.  The ``deferred_message`` variable reference is not evaluated
205until the call site, so it can be set after the deferred call is scheduled.
206
207In order to evaluate variable references immediately when scheduling a
208deferred call, wrap it using ``cmake_language(EVAL)``.  However, note that
209arguments will be re-evaluated in the deferred call, though that can be
210avoided by using bracket arguments.  For example:
211
212.. code-block:: cmake
213
214  set(deferred_message "Deferred Message 1")
215  set(re_evaluated [[${deferred_message}]])
216  cmake_language(EVAL CODE "
217    cmake_language(DEFER CALL message [[${deferred_message}]])
218    cmake_language(DEFER CALL message \"${re_evaluated}\")
219  ")
220  message("Immediate Message")
221  set(deferred_message "Deferred Message 2")
222
223also prints::
224
225  Immediate Message
226  Deferred Message 1
227  Deferred Message 2
228