diff options
Diffstat (limited to 'Help/command/if.rst')
| -rw-r--r-- | Help/command/if.rst | 392 |
1 files changed, 207 insertions, 185 deletions
diff --git a/Help/command/if.rst b/Help/command/if.rst index 684c1135b1..be855e1e0b 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -39,7 +39,7 @@ the ``if``, ``elseif`` and :command:`while` clauses. Compound conditions are evaluated in the following order of precedence: -1. Parentheses. +1. `Parentheses`_. 2. Unary tests such as `EXISTS`_, `COMMAND`_, and `DEFINED`_. @@ -57,262 +57,284 @@ Compound conditions are evaluated in the following order of precedence: 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. - :ref:`Environment Variables <CMake Language 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. +.. signature:: if(<constant>) + :target: 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. + +.. signature:: if(<variable>) + :target: 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. + :ref:`Environment Variables <CMake Language Environment Variables>` also + cannot be tested this way, e.g. ``if(ENV{some_var})`` will always evaluate + to false. + +.. signature:: if(<string>) + :target: 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: +.. signature:: if(NOT <condition>) + + True if the condition is not true. -``if(NOT <condition>)`` - True if the condition is not true. +.. signature:: if(<cond1> AND <cond2>) + :target: AND -.. _AND: + True if both conditions would be considered true individually. -``if(<cond1> AND <cond2>)`` - True if both conditions would be considered true individually. +.. signature:: if(<cond1> OR <cond2>) + :target: OR -.. _OR: + True if either condition would be considered true individually. -``if(<cond1> OR <cond2>)`` - True if either condition would be considered true individually. +.. signature:: if((condition) AND (condition OR (condition))) + :target: parentheses -``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. + 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: +.. signature:: if(COMMAND <command-name>) + + True if the given name is a command, macro or function that can be + invoked. + +.. signature:: if(POLICY <policy-id>) + + True if the given name is an existing policy (of the form ``CMP<NNNN>``). -``if(COMMAND command-name)`` - True if the given name is a command, macro or function that can be - invoked. +.. signature:: if(TARGET <target-name>) -``if(POLICY policy-id)`` - True if the given name is an existing policy (of the form ``CMP<NNNN>``). + 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(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). +.. signature:: if(TEST <test-name>) + + .. versionadded:: 3.3 -``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: +.. signature:: if(DEFINED <name>|CACHE{<name>}|ENV{<name>}) -``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: + 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})``. + * 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 +.. signature:: if(<variable|string> IN_LIST <variable>) + :target: IN_LIST + + .. versionadded:: 3.3 + True if the given element is contained in the named list variable. File Operations """"""""""""""" -.. _EXISTS: +.. signature:: 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. + + False if the given path is an empty string. -``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. +.. signature:: if(<file1> IS_NEWER_THAN <file2>) + :target: IS_NEWER_THAN - False if the given path is an empty string. + 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(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. +.. signature:: if(IS_DIRECTORY <path>) -``if(IS_DIRECTORY path)`` - True if ``path`` is a directory. Behavior is well-defined only - for full paths. + True if ``path`` is a directory. Behavior is well-defined only + for full paths. - False if the given path is an empty string. + False if the given path is an empty string. -``if(IS_SYMLINK file-name)`` - True if the given name is a symbolic link. Behavior is well-defined - only for full paths. +.. signature:: if(IS_SYMLINK <path>) -``if(IS_ABSOLUTE path)`` - True if the given path is an absolute path. Note the following special - cases: + True if the given path is a symbolic link. Behavior is well-defined + only for full paths. - * 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. +.. signature:: 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: +.. signature:: if(<variable|string> MATCHES <regex>) + :target: 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. + 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. + .. versionadded:: 3.9 + ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables. -.. _LESS: +.. signature:: if(<variable|string> LESS <variable|string>) + :target: 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. + True if the given string or variable's value is a valid number and less + than that on the right. -.. _GREATER: +.. signature:: if(<variable|string> GREATER <variable|string>) + :target: GREATER + + True if the given string or variable's value is a valid number and greater + than that on the right. -``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. +.. signature:: if(<variable|string> EQUAL <variable|string>) + :target: EQUAL -.. _EQUAL: + True if the given string or variable's value is a valid number and equal + to that on the right. -``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. +.. signature:: if(<variable|string> LESS_EQUAL <variable|string>) + :target: LESS_EQUAL -.. _LESS_EQUAL: + .. versionadded:: 3.7 -``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: +.. signature:: if(<variable|string> GREATER_EQUAL <variable|string>) + :target: GREATER_EQUAL + + .. versionadded:: 3.7 -``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: +.. signature:: if(<variable|string> STRLESS <variable|string>) + :target: 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. + True if the given string or variable's value is lexicographically less + than the string or variable on the right. -.. _STRGREATER: +.. signature:: if(<variable|string> STRGREATER <variable|string>) + :target: 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. + True if the given string or variable's value is lexicographically greater + than the string or variable on the right. -.. _STREQUAL: +.. signature:: if(<variable|string> STREQUAL <variable|string>) + :target: 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. + True if the given string or variable's value is lexicographically equal + to the string or variable on the right. -.. _STRLESS_EQUAL: +.. signature:: if(<variable|string> STRLESS_EQUAL <variable|string>) + :target: STRLESS_EQUAL + + .. versionadded:: 3.7 -``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: +.. signature:: if(<variable|string> STRGREATER_EQUAL <variable|string>) + :target: STRGREATER_EQUAL + + .. versionadded:: 3.7 -``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: +.. signature:: if(<variable|string> VERSION_LESS <variable|string>) + :target: 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. + 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: +.. signature:: if(<variable|string> VERSION_GREATER <variable|string>) + :target: 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. + 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: +.. signature:: if(<variable|string> VERSION_EQUAL <variable|string>) + :target: 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. + 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: +.. signature:: if(<variable|string> VERSION_LESS_EQUAL <variable|string>) + :target: VERSION_LESS_EQUAL + + .. versionadded:: 3.7 -``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: +.. signature:: if(<variable|string> VERSION_GREATER_EQUAL <variable|string>) + :target: VERSION_GREATER_EQUAL + + .. versionadded:: 3.7 -``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 @@ -321,9 +343,9 @@ Version Comparisons Path Comparisons """""""""""""""" -.. _PATH_EQUAL: +.. signature:: if(<variable|string> PATH_EQUAL <variable|string>) + :target: PATH_EQUAL -``if(<variable|string> PATH_EQUAL <variable|string>)`` .. versionadded:: 3.24 Compares the two paths component-by-component. Only if every component of @@ -386,35 +408,35 @@ 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 +* 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 +* 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 +* 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 +* 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 +* 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 +* 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 +* 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 |