1if
2--
3
4Conditionally execute a group of commands.
5
6Synopsis
7^^^^^^^^
8
9.. code-block:: cmake
10
11  if(<condition>)
12    <commands>
13  elseif(<condition>) # optional block, can be repeated
14    <commands>
15  else()              # optional block
16    <commands>
17  endif()
18
19Evaluates the ``condition`` argument of the ``if`` clause according to the
20`Condition syntax`_ described below. If the result is true, then the
21``commands`` in the ``if`` block are executed.
22Otherwise, optional ``elseif`` blocks are processed in the same way.
23Finally, if no ``condition`` is true, ``commands`` in the optional ``else``
24block are executed.
25
26Per legacy, the :command:`else` and :command:`endif` commands admit
27an optional ``<condition>`` argument.
28If used, it must be a verbatim
29repeat of the argument of the opening
30``if`` command.
31
32.. _`Condition Syntax`:
33
34Condition Syntax
35^^^^^^^^^^^^^^^^
36
37The following syntax applies to the ``condition`` argument of
38the ``if``, ``elseif`` and :command:`while` clauses.
39
40Compound conditions are evaluated in the following order of precedence:
41Innermost parentheses are evaluated first. Next come unary tests such
42as `EXISTS`_, `COMMAND`_, and `DEFINED`_.  Then binary tests such as
43`EQUAL`_, `LESS`_, `LESS_EQUAL`_, `GREATER`_, `GREATER_EQUAL`_,
44`STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_, `STRGREATER`_,
45`STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_,
46`VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_,
47and `MATCHES`_.  Then the boolean operators in the order `NOT`_,  `AND`_,
48and finally `OR`_.
49
50Basic Expressions
51"""""""""""""""""
52
53``if(<constant>)``
54 True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``,
55 or a non-zero number.  False if the constant is ``0``, ``OFF``,
56 ``NO``, ``FALSE``, ``N``, ``IGNORE``, ``NOTFOUND``, the empty string,
57 or ends in the suffix ``-NOTFOUND``.  Named boolean constants are
58 case-insensitive.  If the argument is not one of these specific
59 constants, it is treated as a variable or string (see `Variable Expansion`_
60 further below) and one of the following two forms applies.
61
62``if(<variable>)``
63 True if given a variable that is defined to a value that is not a false
64 constant.  False otherwise, including if the variable is undefined.
65 Note that macro arguments are not variables.
66 Environment variables also cannot be tested this way, e.g.
67 ``if(ENV{some_var})`` will always evaluate to false.
68
69``if(<string>)``
70 A quoted string always evaluates to false unless:
71
72 * The string's value is one of the true constants, or
73 * Policy :policy:`CMP0054` is not set to ``NEW`` and the string's value
74   happens to be a variable name that is affected by :policy:`CMP0054`'s
75   behavior.
76
77Logic Operators
78"""""""""""""""
79
80.. _NOT:
81
82``if(NOT <condition>)``
83 True if the condition is not true.
84
85.. _AND:
86
87``if(<cond1> AND <cond2>)``
88 True if both conditions would be considered true individually.
89
90.. _OR:
91
92``if(<cond1> OR <cond2>)``
93 True if either condition would be considered true individually.
94
95``if((condition) AND (condition OR (condition)))``
96 The conditions inside the parenthesis are evaluated first and then
97 the remaining condition is evaluated as in the other examples.
98 Where there are nested parenthesis the innermost are evaluated as part
99 of evaluating the condition that contains them.
100
101Existence Checks
102""""""""""""""""
103
104.. _COMMAND:
105
106``if(COMMAND command-name)``
107 True if the given name is a command, macro or function that can be
108 invoked.
109
110``if(POLICY policy-id)``
111 True if the given name is an existing policy (of the form ``CMP<NNNN>``).
112
113``if(TARGET target-name)``
114 True if the given name is an existing logical target name created
115 by a call to the :command:`add_executable`, :command:`add_library`,
116 or :command:`add_custom_target` command that has already been invoked
117 (in any directory).
118
119``if(TEST test-name)``
120 .. versionadded:: 3.3
121  True if the given name is an existing test name created by the
122  :command:`add_test` command.
123
124.. _DEFINED:
125
126``if(DEFINED <name>|CACHE{<name>}|ENV{<name>})``
127 True if a variable, cache variable or environment variable
128 with given ``<name>`` is defined. The value of the variable
129 does not matter. Note that macro arguments are not variables.
130
131 .. versionadded:: 3.14
132  Added support for ``CACHE{<name>}`` variables.
133
134``if(<variable|string> IN_LIST <variable>)``
135 .. versionadded:: 3.3
136  True if the given element is contained in the named list variable.
137
138File Operations
139"""""""""""""""
140
141.. _EXISTS:
142
143``if(EXISTS path-to-file-or-directory)``
144 True if the named file or directory exists.  Behavior is well-defined
145 only for explicit full paths (a leading ``~/`` is not expanded as
146 a home directory and is considered a relative path).
147 Resolves symbolic links, i.e. if the named file or directory is a
148 symbolic link, returns true if the target of the symbolic link exists.
149
150``if(file1 IS_NEWER_THAN file2)``
151 True if ``file1`` is newer than ``file2`` or if one of the two files doesn't
152 exist.  Behavior is well-defined only for full paths.  If the file
153 time stamps are exactly the same, an ``IS_NEWER_THAN`` comparison returns
154 true, so that any dependent build operations will occur in the event
155 of a tie.  This includes the case of passing the same file name for
156 both file1 and file2.
157
158``if(IS_DIRECTORY path-to-directory)``
159 True if the given name is a directory.  Behavior is well-defined only
160 for full paths.
161
162``if(IS_SYMLINK file-name)``
163 True if the given name is a symbolic link.  Behavior is well-defined
164 only for full paths.
165
166``if(IS_ABSOLUTE path)``
167 True if the given path is an absolute path.  Note the following special
168 cases:
169
170 * An empty ``path`` evaluates to false.
171 * On Windows hosts, any ``path`` that begins with a drive letter and colon
172   (e.g. ``C:``), a forward slash or a backslash will evaluate to true.
173   This means a path like ``C:no\base\dir`` will evaluate to true, even
174   though the non-drive part of the path is relative.
175 * On non-Windows hosts, any ``path`` that begins with a tilde (``~``)
176   evaluates to true.
177
178Comparisons
179"""""""""""
180
181.. _MATCHES:
182
183``if(<variable|string> MATCHES regex)``
184 True if the given string or variable's value matches the given regular
185 expression.  See :ref:`Regex Specification` for regex format.
186
187 .. versionadded:: 3.9
188  ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables.
189
190.. _LESS:
191
192``if(<variable|string> LESS <variable|string>)``
193 True if the given string or variable's value is a valid number and less
194 than that on the right.
195
196.. _GREATER:
197
198``if(<variable|string> GREATER <variable|string>)``
199 True if the given string or variable's value is a valid number and greater
200 than that on the right.
201
202.. _EQUAL:
203
204``if(<variable|string> EQUAL <variable|string>)``
205 True if the given string or variable's value is a valid number and equal
206 to that on the right.
207
208.. _LESS_EQUAL:
209
210``if(<variable|string> LESS_EQUAL <variable|string>)``
211 .. versionadded:: 3.7
212  True if the given string or variable's value is a valid number and less
213  than or equal to that on the right.
214
215.. _GREATER_EQUAL:
216
217``if(<variable|string> GREATER_EQUAL <variable|string>)``
218 .. versionadded:: 3.7
219  True if the given string or variable's value is a valid number and greater
220  than or equal to that on the right.
221
222.. _STRLESS:
223
224``if(<variable|string> STRLESS <variable|string>)``
225 True if the given string or variable's value is lexicographically less
226 than the string or variable on the right.
227
228.. _STRGREATER:
229
230``if(<variable|string> STRGREATER <variable|string>)``
231 True if the given string or variable's value is lexicographically greater
232 than the string or variable on the right.
233
234.. _STREQUAL:
235
236``if(<variable|string> STREQUAL <variable|string>)``
237 True if the given string or variable's value is lexicographically equal
238 to the string or variable on the right.
239
240.. _STRLESS_EQUAL:
241
242``if(<variable|string> STRLESS_EQUAL <variable|string>)``
243 .. versionadded:: 3.7
244  True if the given string or variable's value is lexicographically less
245  than or equal to the string or variable on the right.
246
247.. _STRGREATER_EQUAL:
248
249``if(<variable|string> STRGREATER_EQUAL <variable|string>)``
250 .. versionadded:: 3.7
251  True if the given string or variable's value is lexicographically greater
252  than or equal to the string or variable on the right.
253
254Version Comparisons
255"""""""""""""""""""
256
257.. _VERSION_LESS:
258
259``if(<variable|string> VERSION_LESS <variable|string>)``
260 Component-wise integer version number comparison (version format is
261 ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
262 Any non-integer version component or non-integer trailing part of a version
263 component effectively truncates the string at that point.
264
265.. _VERSION_GREATER:
266
267``if(<variable|string> VERSION_GREATER <variable|string>)``
268 Component-wise integer version number comparison (version format is
269 ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
270 Any non-integer version component or non-integer trailing part of a version
271 component effectively truncates the string at that point.
272
273.. _VERSION_EQUAL:
274
275``if(<variable|string> VERSION_EQUAL <variable|string>)``
276 Component-wise integer version number comparison (version format is
277 ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
278 Any non-integer version component or non-integer trailing part of a version
279 component effectively truncates the string at that point.
280
281.. _VERSION_LESS_EQUAL:
282
283``if(<variable|string> VERSION_LESS_EQUAL <variable|string>)``
284 .. versionadded:: 3.7
285  Component-wise integer version number comparison (version format is
286  ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
287  Any non-integer version component or non-integer trailing part of a version
288  component effectively truncates the string at that point.
289
290.. _VERSION_GREATER_EQUAL:
291
292``if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)``
293 .. versionadded:: 3.7
294  Component-wise integer version number comparison (version format is
295  ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
296  Any non-integer version component or non-integer trailing part of a version
297  component effectively truncates the string at that point.
298
299Variable Expansion
300^^^^^^^^^^^^^^^^^^
301
302The if command was written very early in CMake's history, predating
303the ``${}`` variable evaluation syntax, and for convenience evaluates
304variables named by its arguments as shown in the above signatures.
305Note that normal variable evaluation with ``${}`` applies before the if
306command even receives the arguments.  Therefore code like
307
308.. code-block:: cmake
309
310 set(var1 OFF)
311 set(var2 "var1")
312 if(${var2})
313
314appears to the if command as
315
316.. code-block:: cmake
317
318  if(var1)
319
320and is evaluated according to the ``if(<variable>)`` case documented
321above.  The result is ``OFF`` which is false.  However, if we remove the
322``${}`` from the example then the command sees
323
324.. code-block:: cmake
325
326  if(var2)
327
328which is true because ``var2`` is defined to ``var1`` which is not a false
329constant.
330
331Automatic evaluation applies in the other cases whenever the
332above-documented condition syntax accepts ``<variable|string>``:
333
334* The left hand argument to ``MATCHES`` is first checked to see if it is
335  a defined variable, if so the variable's value is used, otherwise the
336  original value is used.
337
338* If the left hand argument to ``MATCHES`` is missing it returns false
339  without error
340
341* Both left and right hand arguments to ``LESS``, ``GREATER``, ``EQUAL``,
342  ``LESS_EQUAL``, and ``GREATER_EQUAL``, are independently tested to see if
343  they are defined variables, if so their defined values are used otherwise
344  the original value is used.
345
346* Both left and right hand arguments to ``STRLESS``, ``STRGREATER``,
347  ``STREQUAL``, ``STRLESS_EQUAL``, and ``STRGREATER_EQUAL`` are independently
348  tested to see if they are defined variables, if so their defined values are
349  used otherwise the original value is used.
350
351* Both left and right hand arguments to ``VERSION_LESS``,
352  ``VERSION_GREATER``, ``VERSION_EQUAL``, ``VERSION_LESS_EQUAL``, and
353  ``VERSION_GREATER_EQUAL`` are independently tested to see if they are defined
354  variables, if so their defined values are used otherwise the original value
355  is used.
356
357* The right hand argument to ``NOT`` is tested to see if it is a boolean
358  constant, if so the value is used, otherwise it is assumed to be a
359  variable and it is dereferenced.
360
361* The left and right hand arguments to ``AND`` and ``OR`` are independently
362  tested to see if they are boolean constants, if so they are used as
363  such, otherwise they are assumed to be variables and are dereferenced.
364
365.. versionchanged:: 3.1
366  To prevent ambiguity, potential variable or keyword names can be
367  specified in a :ref:`Quoted Argument` or a :ref:`Bracket Argument`.
368  A quoted or bracketed variable or keyword will be interpreted as a
369  string and not dereferenced or interpreted.
370  See policy :policy:`CMP0054`.
371
372There is no automatic evaluation for environment or cache
373:ref:`Variable References`.  Their values must be referenced as
374``$ENV{<name>}`` or ``$CACHE{<name>}`` wherever the above-documented
375condition syntax accepts ``<variable|string>``.
376