Merge topic 'doc-clarify-if-TARGET'
6b8662eHelp: Clarify if(TARGET) behavior (#14646)b74819eHelp: Format 'if' command documentation
This commit is contained in:
Brad King
CMake Topic Stage
commit
b375c18b9e
|
|
@ -3,7 +3,7 @@ if
|
||||||
|
|
||||||
Conditionally execute a group of commands.
|
Conditionally execute a group of commands.
|
||||||
|
|
||||||
::
|
.. code-block:: cmake
|
||||||
|
|
||||||
if(expression)
|
if(expression)
|
||||||
# then section.
|
# then section.
|
||||||
|
|
@ -28,212 +28,174 @@ section are invoked. The elseif and else sections are optional. You
|
||||||
may have multiple elseif clauses. Note that the expression in the
|
may have multiple elseif clauses. Note that the expression in the
|
||||||
else and endif clause is optional. Long expressions can be used and
|
else and endif clause is optional. Long expressions can be used and
|
||||||
there is a traditional order of precedence. Parenthetical expressions
|
there is a traditional order of precedence. Parenthetical expressions
|
||||||
are evaluated first followed by unary operators such as EXISTS,
|
are evaluated first followed by unary tests such as ``EXISTS``,
|
||||||
COMMAND, and DEFINED. Then any EQUAL, LESS, GREATER, STRLESS,
|
``COMMAND``, and ``DEFINED``. Then any binary tests such as
|
||||||
STRGREATER, STREQUAL, MATCHES will be evaluated. Then NOT operators
|
``EQUAL``, ``LESS``, ``GREATER``, ``STRLESS``, ``STRGREATER``,
|
||||||
and finally AND, OR operators will be evaluated. Possible expressions
|
``STREQUAL``, and ``MATCHES`` will be evaluated. Then boolean ``NOT``
|
||||||
are:
|
operators and finally boolean ``AND`` and then ``OR`` operators will
|
||||||
|
be evaluated.
|
||||||
|
|
||||||
::
|
Possible expressions are:
|
||||||
|
|
||||||
if(<constant>)
|
``if(<constant>)``
|
||||||
|
True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``,
|
||||||
|
or a non-zero number. 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 constants, it
|
||||||
|
is treated as a variable.
|
||||||
|
|
||||||
True if the constant is 1, ON, YES, TRUE, Y, or a non-zero number.
|
``if(<variable>)``
|
||||||
False if the constant is 0, OFF, NO, FALSE, N, IGNORE, NOTFOUND, '',
|
True if the variable is defined to a value that is not a false
|
||||||
or ends in the suffix '-NOTFOUND'. Named boolean constants are
|
constant. False otherwise. (Note macro arguments are not variables.)
|
||||||
case-insensitive. If the argument is not one of these constants, it
|
|
||||||
is treated as a variable:
|
|
||||||
|
|
||||||
::
|
``if(NOT <expression>)``
|
||||||
|
True if the expression is not true.
|
||||||
|
|
||||||
if(<variable>)
|
``if(<expr1> AND <expr2>)``
|
||||||
|
True if both expressions would be considered true individually.
|
||||||
|
|
||||||
True if the variable is defined to a value that is not a false
|
``if(<expr1> OR <expr2>)``
|
||||||
constant. False otherwise. (Note macro arguments are not variables.)
|
True if either expression would be considered true individually.
|
||||||
|
|
||||||
::
|
``if(COMMAND command-name)``
|
||||||
|
True if the given name is a command, macro or function that can be
|
||||||
|
invoked.
|
||||||
|
|
||||||
if(NOT <expression>)
|
``if(POLICY policy-id)``
|
||||||
|
True if the given name is an existing policy (of the form ``CMP<NNNN>``).
|
||||||
|
|
||||||
True if the expression is not true.
|
``if(TARGET target-name)``
|
||||||
|
True if the given name is an existing logical target name such as those
|
||||||
|
created by the :command:`add_executable`, :command:`add_library`, or
|
||||||
|
:command:`add_custom_target` commands.
|
||||||
|
|
||||||
::
|
``if(EXISTS path-to-file-or-directory)``
|
||||||
|
True if the named file or directory exists. Behavior is well-defined
|
||||||
|
only for full paths.
|
||||||
|
|
||||||
if(<expr1> AND <expr2>)
|
``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.
|
||||||
|
|
||||||
True if both expressions would be considered true individually.
|
``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(<expr1> OR <expr2>)
|
``if(IS_ABSOLUTE path)``
|
||||||
|
True if the given path is an absolute path.
|
||||||
|
|
||||||
True if either expression would be considered true individually.
|
``if(<variable|string> MATCHES regex)``
|
||||||
|
True if the given string or variable's value matches the given regular
|
||||||
|
expression.
|
||||||
|
|
||||||
::
|
``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.
|
||||||
|
|
||||||
if(COMMAND command-name)
|
``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.
|
||||||
|
|
||||||
True if the given name is a command, macro or function that can be
|
``if(<variable|string> EQUAL <variable|string>)``
|
||||||
invoked.
|
True if the given string or variable's value is a valid number and equal
|
||||||
|
to that on the right.
|
||||||
|
|
||||||
::
|
``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.
|
||||||
|
|
||||||
if(POLICY policy-id)
|
``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 name is an existing policy (of the form CMP<NNNN>).
|
``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.
|
||||||
|
|
||||||
::
|
``if(<variable|string> VERSION_LESS <variable|string>)``
|
||||||
|
Component-wise integer version number comparison (version format is
|
||||||
|
``major[.minor[.patch[.tweak]]]``).
|
||||||
|
|
||||||
if(TARGET target-name)
|
``if(<variable|string> VERSION_EQUAL <variable|string>)``
|
||||||
|
Component-wise integer version number comparison (version format is
|
||||||
|
``major[.minor[.patch[.tweak]]]``).
|
||||||
|
|
||||||
True if the given name is an existing target, built or imported.
|
``if(<variable|string> VERSION_GREATER <variable|string>)``
|
||||||
|
Component-wise integer version number comparison (version format is
|
||||||
|
``major[.minor[.patch[.tweak]]]``).
|
||||||
|
|
||||||
::
|
``if(DEFINED <variable>)``
|
||||||
|
True if the given variable is defined. It does not matter if the
|
||||||
|
variable is true or false just if it has been set. (Note macro
|
||||||
|
arguments are not variables.)
|
||||||
|
|
||||||
if(EXISTS file-name)
|
``if((expression) AND (expression OR (expression)))``
|
||||||
if(EXISTS directory-name)
|
The expressions inside the parenthesis are evaluated first and then
|
||||||
|
the remaining expression is evaluated as in the previous examples.
|
||||||
True if the named file or directory exists. Behavior is well-defined
|
Where there are nested parenthesis the innermost are evaluated as part
|
||||||
only for full paths.
|
of evaluating the expression that contains them.
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
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 directory-name)
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
if(<variable|string> MATCHES regex)
|
|
||||||
|
|
||||||
True if the given string or variable's value matches the given regular
|
|
||||||
expression.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
if(<variable|string> LESS <variable|string>)
|
|
||||||
if(<variable|string> GREATER <variable|string>)
|
|
||||||
if(<variable|string> EQUAL <variable|string>)
|
|
||||||
|
|
||||||
True if the given string or variable's value is a valid number and the
|
|
||||||
inequality or equality is true.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
if(<variable|string> STRLESS <variable|string>)
|
|
||||||
if(<variable|string> STRGREATER <variable|string>)
|
|
||||||
if(<variable|string> STREQUAL <variable|string>)
|
|
||||||
|
|
||||||
True if the given string or variable's value is lexicographically less
|
|
||||||
(or greater, or equal) than the string or variable on the right.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
if(<variable|string> VERSION_LESS <variable|string>)
|
|
||||||
if(<variable|string> VERSION_EQUAL <variable|string>)
|
|
||||||
if(<variable|string> VERSION_GREATER <variable|string>)
|
|
||||||
|
|
||||||
Component-wise integer version number comparison (version format is
|
|
||||||
major[.minor[.patch[.tweak]]]).
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
if(DEFINED <variable>)
|
|
||||||
|
|
||||||
True if the given variable is defined. It does not matter if the
|
|
||||||
variable is true or false just if it has been set. (Note macro
|
|
||||||
arguments are not variables.)
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
if((expression) AND (expression OR (expression)))
|
|
||||||
|
|
||||||
The expressions inside the parenthesis are evaluated first and then
|
|
||||||
the remaining expression is evaluated as in the previous examples.
|
|
||||||
Where there are nested parenthesis the innermost are evaluated as part
|
|
||||||
of evaluating the expression that contains them.
|
|
||||||
|
|
||||||
The if command was written very early in CMake's history, predating
|
The if command was written very early in CMake's history, predating
|
||||||
the ${} variable evaluation syntax, and for convenience evaluates
|
the ``${}`` variable evaluation syntax, and for convenience evaluates
|
||||||
variables named by its arguments as shown in the above signatures.
|
variables named by its arguments as shown in the above signatures.
|
||||||
Note that normal variable evaluation with ${} applies before the if
|
Note that normal variable evaluation with ``${}`` applies before the if
|
||||||
command even receives the arguments. Therefore code like
|
command even receives the arguments. Therefore code like::
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
set(var1 OFF)
|
set(var1 OFF)
|
||||||
set(var2 "var1")
|
set(var2 "var1")
|
||||||
if(${var2})
|
if(${var2})
|
||||||
|
|
||||||
appears to the if command as
|
appears to the if command as::
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
if(var1)
|
if(var1)
|
||||||
|
|
||||||
and is evaluated according to the if(<variable>) case documented
|
and is evaluated according to the ``if(<variable>)`` case documented
|
||||||
above. The result is OFF which is false. However, if we remove the
|
above. The result is ``OFF`` which is false. However, if we remove the
|
||||||
${} from the example then the command sees
|
``${}`` from the example then the command sees::
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
if(var2)
|
if(var2)
|
||||||
|
|
||||||
which is true because var2 is defined to "var1" which is not a false
|
which is true because ``var2`` is defined to "var1" which is not a false
|
||||||
constant.
|
constant.
|
||||||
|
|
||||||
Automatic evaluation applies in the other cases whenever the
|
Automatic evaluation applies in the other cases whenever the
|
||||||
above-documented signature accepts <variable|string>:
|
above-documented signature accepts ``<variable|string>``:
|
||||||
|
|
||||||
1) The left hand argument to MATCHES is first checked to see if it is
|
* 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
|
a defined variable, if so the variable's value is used, otherwise the
|
||||||
original value is used.
|
original value is used.
|
||||||
|
|
||||||
2) 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
|
without error
|
||||||
|
|
||||||
3) Both left and right hand arguments to LESS GREATER EQUAL are
|
* Both left and right hand arguments to ``LESS``, ``GREATER``, and
|
||||||
independently tested to see if they are defined variables, if so their
|
``EQUAL`` are independently tested to see if they are defined
|
||||||
defined values are used otherwise the original value is used.
|
variables, if so their defined values are used otherwise the original
|
||||||
|
value is used.
|
||||||
|
|
||||||
4) Both left and right hand arguments to STRLESS STREQUAL STRGREATER
|
* Both left and right hand arguments to ``STRLESS``, ``STREQUAL``, and
|
||||||
are independently tested to see if they are defined variables, if so
|
``STRGREATER`` are independently tested to see if they are defined
|
||||||
their defined values are used otherwise the original value is used.
|
variables, if so their defined values are used otherwise the original
|
||||||
|
value is used.
|
||||||
|
|
||||||
5) Both left and right hand argumemnts to VERSION_LESS VERSION_EQUAL
|
* Both left and right hand argumemnts to ``VERSION_LESS``,
|
||||||
VERSION_GREATER are independently tested to see if they are defined
|
``VERSION_EQUAL``, and ``VERSION_GREATER`` are independently tested
|
||||||
variables, if so their defined values are used otherwise the original
|
to see if they are defined variables, if so their defined values are
|
||||||
value is used.
|
used otherwise the original value is used.
|
||||||
|
|
||||||
6) The right hand argument to NOT is tested to see if it is a boolean
|
* 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
|
constant, if so the value is used, otherwise it is assumed to be a
|
||||||
variable and it is dereferenced.
|
variable and it is dereferenced.
|
||||||
|
|
||||||
7) The left and right hand arguments to AND OR are independently
|
* 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
|
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.
|
such, otherwise they are assumed to be variables and are dereferenced.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue