| if |
| -- |
| |
| Conditionally execute a group of commands. |
| |
| Synopsis |
| ^^^^^^^^ |
| |
| .. code-block:: cmake |
| |
| if(<condition>) |
| <commands> |
| elseif(<condition>) # optional block, can be repeated |
| <commands> |
| else() # optional block |
| <commands> |
| endif() |
| |
| Evaluates the ``condition`` argument of the ``if`` clause according to the |
| `Condition syntax`_ described below. If the result is true, then the |
| ``commands`` in the ``if`` block are executed. |
| Otherwise, optional ``elseif`` blocks are processed in the same way. |
| Finally, if no ``condition`` is true, ``commands`` in the optional ``else`` |
| block are executed. |
| |
| Per legacy, the :command:`else` and :command:`endif` commands admit |
| an optional ``<condition>`` argument. |
| If used, it must be a verbatim |
| repeat of the argument of the opening |
| ``if`` command. |
| |
| .. _`Condition Syntax`: |
| |
| Condition Syntax |
| ^^^^^^^^^^^^^^^^ |
| |
| The following syntax applies to the ``condition`` argument of |
| the ``if``, ``elseif`` and :command:`while` clauses. |
| |
| Compound conditions are evaluated in the following order of precedence: |
| |
| 1. Parentheses. |
| |
| 2. Unary tests such as `EXISTS`_, `COMMAND`_, and `DEFINED`_. |
| |
| 3. Binary tests such as `EQUAL`_, `LESS`_, `LESS_EQUAL`_, `GREATER`_, |
| `GREATER_EQUAL`_, `STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_, |
| `STRGREATER`_, `STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_, |
| `VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_, |
| and `MATCHES`_. |
| |
| 4. Unary logical operator `NOT`_. |
| |
| 5. Binary logical operators `AND`_ and `OR`_, from left to right, |
| without any short-circuit. |
| |
| Basic Expressions |
| """"""""""""""""" |
| |
| ``if(<constant>)`` |
| True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``, |
| or a non-zero number (including floating point numbers). |
| False if the constant is ``0``, ``OFF``, |
| ``NO``, ``FALSE``, ``N``, ``IGNORE``, ``NOTFOUND``, the empty string, |
| or ends in the suffix ``-NOTFOUND``. Named boolean constants are |
| case-insensitive. If the argument is not one of these specific |
| constants, it is treated as a variable or string (see `Variable Expansion`_ |
| further below) and one of the following two forms applies. |
| |
| ``if(<variable>)`` |
| True if given a variable that is defined to a value that is not a false |
| constant. False otherwise, including if the variable is undefined. |
| Note that macro arguments are not variables. |
| Environment variables also cannot be tested this way, e.g. |
| ``if(ENV{some_var})`` will always evaluate to false. |
| |
| ``if(<string>)`` |
| A quoted string always evaluates to false unless: |
| |
| * The string's value is one of the true constants, or |
| * Policy :policy:`CMP0054` is not set to ``NEW`` and the string's value |
| happens to be a variable name that is affected by :policy:`CMP0054`'s |
| behavior. |
| |
| Logic Operators |
| """"""""""""""" |
| |
| .. _NOT: |
| |
| ``if(NOT <condition>)`` |
| True if the condition is not true. |
| |
| .. _AND: |
| |
| ``if(<cond1> AND <cond2>)`` |
| True if both conditions would be considered true individually. |
| |
| .. _OR: |
| |
| ``if(<cond1> OR <cond2>)`` |
| True if either condition would be considered true individually. |
| |
| ``if((condition) AND (condition OR (condition)))`` |
| The conditions inside the parenthesis are evaluated first and then |
| the remaining condition is evaluated as in the other examples. |
| Where there are nested parenthesis the innermost are evaluated as part |
| of evaluating the condition that contains them. |
| |
| Existence Checks |
| """""""""""""""" |
| |
| .. _COMMAND: |
| |
| ``if(COMMAND command-name)`` |
| True if the given name is a command, macro or function that can be |
| invoked. |
| |
| ``if(POLICY policy-id)`` |
| True if the given name is an existing policy (of the form ``CMP<NNNN>``). |
| |
| ``if(TARGET target-name)`` |
| True if the given name is an existing logical target name created |
| by a call to the :command:`add_executable`, :command:`add_library`, |
| or :command:`add_custom_target` command that has already been invoked |
| (in any directory). |
| |
| ``if(TEST test-name)`` |
| .. versionadded:: 3.3 |
| True if the given name is an existing test name created by the |
| :command:`add_test` command. |
| |
| .. _DEFINED: |
| |
| ``if(DEFINED <name>|CACHE{<name>}|ENV{<name>})`` |
| True if a variable, cache variable or environment variable |
| with given ``<name>`` is defined. The value of the variable |
| does not matter. Note the following caveats: |
| |
| * Macro arguments are not variables. |
| * It is not possible to test directly whether a `<name>` is a non-cache |
| variable. The expression ``if(DEFINED someName)`` will evaluate to true |
| if either a cache or non-cache variable ``someName`` exists. In |
| comparison, the expression ``if(DEFINED CACHE{someName})`` will only |
| evaluate to true if a cache variable ``someName`` exists. Both expressions |
| need to be tested if you need to know whether a non-cache variable exists: |
| ``if(DEFINED someName AND NOT DEFINED CACHE{someName})``. |
| |
| .. versionadded:: 3.14 |
| Added support for ``CACHE{<name>}`` variables. |
| |
| ``if(<variable|string> IN_LIST <variable>)`` |
| .. versionadded:: 3.3 |
| True if the given element is contained in the named list variable. |
| |
| File Operations |
| """"""""""""""" |
| |
| .. _EXISTS: |
| |
| ``if(EXISTS path-to-file-or-directory)`` |
| True if the named file or directory exists. Behavior is well-defined |
| only for explicit full paths (a leading ``~/`` is not expanded as |
| a home directory and is considered a relative path). |
| Resolves symbolic links, i.e. if the named file or directory is a |
| symbolic link, returns true if the target of the symbolic link exists. |
| |
| ``if(file1 IS_NEWER_THAN file2)`` |
| True if ``file1`` is newer than ``file2`` or if one of the two files doesn't |
| exist. Behavior is well-defined only for full paths. If the file |
| time stamps are exactly the same, an ``IS_NEWER_THAN`` comparison returns |
| true, so that any dependent build operations will occur in the event |
| of a tie. This includes the case of passing the same file name for |
| both file1 and file2. |
| |
| ``if(IS_DIRECTORY path-to-directory)`` |
| True if the given name is a directory. Behavior is well-defined only |
| for full paths. |
| |
| ``if(IS_SYMLINK file-name)`` |
| True if the given name is a symbolic link. Behavior is well-defined |
| only for full paths. |
| |
| ``if(IS_ABSOLUTE path)`` |
| True if the given path is an absolute path. Note the following special |
| cases: |
| |
| * An empty ``path`` evaluates to false. |
| * On Windows hosts, any ``path`` that begins with a drive letter and colon |
| (e.g. ``C:``), a forward slash or a backslash will evaluate to true. |
| This means a path like ``C:no\base\dir`` will evaluate to true, even |
| though the non-drive part of the path is relative. |
| * On non-Windows hosts, any ``path`` that begins with a tilde (``~``) |
| evaluates to true. |
| |
| Comparisons |
| """"""""""" |
| |
| .. _MATCHES: |
| |
| ``if(<variable|string> MATCHES regex)`` |
| True if the given string or variable's value matches the given regular |
| expression. See :ref:`Regex Specification` for regex format. |
| |
| .. versionadded:: 3.9 |
| ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables. |
| |
| .. _LESS: |
| |
| ``if(<variable|string> LESS <variable|string>)`` |
| True if the given string or variable's value is a valid number and less |
| than that on the right. |
| |
| .. _GREATER: |
| |
| ``if(<variable|string> GREATER <variable|string>)`` |
| True if the given string or variable's value is a valid number and greater |
| than that on the right. |
| |
| .. _EQUAL: |
| |
| ``if(<variable|string> EQUAL <variable|string>)`` |
| True if the given string or variable's value is a valid number and equal |
| to that on the right. |
| |
| .. _LESS_EQUAL: |
| |
| ``if(<variable|string> LESS_EQUAL <variable|string>)`` |
| .. versionadded:: 3.7 |
| True if the given string or variable's value is a valid number and less |
| than or equal to that on the right. |
| |
| .. _GREATER_EQUAL: |
| |
| ``if(<variable|string> GREATER_EQUAL <variable|string>)`` |
| .. versionadded:: 3.7 |
| True if the given string or variable's value is a valid number and greater |
| than or equal to that on the right. |
| |
| .. _STRLESS: |
| |
| ``if(<variable|string> STRLESS <variable|string>)`` |
| True if the given string or variable's value is lexicographically less |
| than the string or variable on the right. |
| |
| .. _STRGREATER: |
| |
| ``if(<variable|string> STRGREATER <variable|string>)`` |
| True if the given string or variable's value is lexicographically greater |
| than the string or variable on the right. |
| |
| .. _STREQUAL: |
| |
| ``if(<variable|string> STREQUAL <variable|string>)`` |
| True if the given string or variable's value is lexicographically equal |
| to the string or variable on the right. |
| |
| .. _STRLESS_EQUAL: |
| |
| ``if(<variable|string> STRLESS_EQUAL <variable|string>)`` |
| .. versionadded:: 3.7 |
| True if the given string or variable's value is lexicographically less |
| than or equal to the string or variable on the right. |
| |
| .. _STRGREATER_EQUAL: |
| |
| ``if(<variable|string> STRGREATER_EQUAL <variable|string>)`` |
| .. versionadded:: 3.7 |
| True if the given string or variable's value is lexicographically greater |
| than or equal to the string or variable on the right. |
| |
| Version Comparisons |
| """"""""""""""""""" |
| |
| .. _VERSION_LESS: |
| |
| ``if(<variable|string> VERSION_LESS <variable|string>)`` |
| Component-wise integer version number comparison (version format is |
| ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). |
| Any non-integer version component or non-integer trailing part of a version |
| component effectively truncates the string at that point. |
| |
| .. _VERSION_GREATER: |
| |
| ``if(<variable|string> VERSION_GREATER <variable|string>)`` |
| Component-wise integer version number comparison (version format is |
| ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). |
| Any non-integer version component or non-integer trailing part of a version |
| component effectively truncates the string at that point. |
| |
| .. _VERSION_EQUAL: |
| |
| ``if(<variable|string> VERSION_EQUAL <variable|string>)`` |
| Component-wise integer version number comparison (version format is |
| ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). |
| Any non-integer version component or non-integer trailing part of a version |
| component effectively truncates the string at that point. |
| |
| .. _VERSION_LESS_EQUAL: |
| |
| ``if(<variable|string> VERSION_LESS_EQUAL <variable|string>)`` |
| .. versionadded:: 3.7 |
| Component-wise integer version number comparison (version format is |
| ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). |
| Any non-integer version component or non-integer trailing part of a version |
| component effectively truncates the string at that point. |
| |
| .. _VERSION_GREATER_EQUAL: |
| |
| ``if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)`` |
| .. versionadded:: 3.7 |
| Component-wise integer version number comparison (version format is |
| ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). |
| Any non-integer version component or non-integer trailing part of a version |
| component effectively truncates the string at that point. |
| |
| Variable Expansion |
| ^^^^^^^^^^^^^^^^^^ |
| |
| The if command was written very early in CMake's history, predating |
| the ``${}`` variable evaluation syntax, and for convenience evaluates |
| variables named by its arguments as shown in the above signatures. |
| Note that normal variable evaluation with ``${}`` applies before the if |
| command even receives the arguments. Therefore code like |
| |
| .. code-block:: cmake |
| |
| set(var1 OFF) |
| set(var2 "var1") |
| if(${var2}) |
| |
| appears to the if command as |
| |
| .. code-block:: cmake |
| |
| if(var1) |
| |
| and is evaluated according to the ``if(<variable>)`` case documented |
| above. The result is ``OFF`` which is false. However, if we remove the |
| ``${}`` from the example then the command sees |
| |
| .. code-block:: cmake |
| |
| if(var2) |
| |
| which is true because ``var2`` is defined to ``var1`` which is not a false |
| constant. |
| |
| Automatic evaluation applies in the other cases whenever the |
| above-documented condition syntax accepts ``<variable|string>``: |
| |
| * The left hand argument to ``MATCHES`` is first checked to see if it is |
| a defined variable, if so the variable's value is used, otherwise the |
| original value is used. |
| |
| * If the left hand argument to ``MATCHES`` is missing it returns false |
| without error |
| |
| * Both left and right hand arguments to ``LESS``, ``GREATER``, ``EQUAL``, |
| ``LESS_EQUAL``, and ``GREATER_EQUAL``, are independently tested to see if |
| they are defined variables, if so their defined values are used otherwise |
| the original value is used. |
| |
| * Both left and right hand arguments to ``STRLESS``, ``STRGREATER``, |
| ``STREQUAL``, ``STRLESS_EQUAL``, and ``STRGREATER_EQUAL`` are independently |
| tested to see if they are defined variables, if so their defined values are |
| used otherwise the original value is used. |
| |
| * Both left and right hand arguments to ``VERSION_LESS``, |
| ``VERSION_GREATER``, ``VERSION_EQUAL``, ``VERSION_LESS_EQUAL``, and |
| ``VERSION_GREATER_EQUAL`` are independently tested to see if they are defined |
| variables, if so their defined values are used otherwise the original value |
| is used. |
| |
| * The right hand argument to ``NOT`` is tested to see if it is a boolean |
| constant, if so the value is used, otherwise it is assumed to be a |
| variable and it is dereferenced. |
| |
| * The left and right hand arguments to ``AND`` and ``OR`` are independently |
| tested to see if they are boolean constants, if so they are used as |
| such, otherwise they are assumed to be variables and are dereferenced. |
| |
| .. versionchanged:: 3.1 |
| To prevent ambiguity, potential variable or keyword names can be |
| specified in a :ref:`Quoted Argument` or a :ref:`Bracket Argument`. |
| A quoted or bracketed variable or keyword will be interpreted as a |
| string and not dereferenced or interpreted. |
| See policy :policy:`CMP0054`. |
| |
| There is no automatic evaluation for environment or cache |
| :ref:`Variable References`. Their values must be referenced as |
| ``$ENV{<name>}`` or ``$CACHE{<name>}`` wherever the above-documented |
| condition syntax accepts ``<variable|string>``. |