mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-06 05:40:54 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Revise docs on Scripting Commands

Browse Source 
Revise docs for all "Scripting Commands", except four find_XXX
that use a macro suite of their own.

* Take full advantage of the improved syntax highlighting.
* Make consequential use of <..> placeholders.
* Clarify things here and there in the text.

Specific improvements to some command docs:

* "math": Correct description of novel hexadecimal capability.
* "if", "foreach", "while": Provide link to "endif" etc
* "foreach", "while": Mention "break" and "continue".
* "foreach": Simplify explanation of ``RANGE`` and ``IN`` signatures;
   advise against negative arguments or reverse ranges (compare issue #18461)
* "endif", "endfunction" etc: Explain that the argument is optional and
   maintained for compatibility only
This commit is contained in:
Joachim Wuttke (l)
2018-10-16 21:50:48 +02:00
committed by Joachim Wuttke (o)
parent 7053dd301c
commit c2efb3efcd
41 changed files with 478 additions and 325 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
Help/command/if.rst
View File

@@ -6,7 +6,7 @@ Conditionally execute a group of commands.
Synopsis
^^^^^^^^
::
.. code-block:: cmake
if(<condition>)
<commands>
@@ -23,8 +23,11 @@ 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 ``else`` and ``endif`` clause may also have a ``condition`` argument,
which then must be a verbatim repeat of the argument of the opening ``if`` clause.
Per legacy, the :command:`else` and :command:`elseif` commands admit
an optional ``<condition>`` argument.
If used, it must be a verbatim
repeat of the argument of the opening
``if`` command.
Condition Syntax
^^^^^^^^^^^^^^^^
@@ -202,21 +205,27 @@ 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::
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::
appears to the if command as
if(var1)
.. 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::
``${}`` from the example then the command sees
if(var2)
.. code-block:: cmake
if(var2)
which is true because ``var2`` is defined to "var1" which is not a false
constant.