mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-05 05:11:15 -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

34
Help/command/function.rst
View File

@@ -1,27 +1,29 @@
function
--------
Start recording a function for later invocation as a command::
Start recording a function for later invocation as a command.
function(<name> [arg1 [arg2 [arg3 ...]]])
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
...
endfunction(<name>)
.. code-block:: cmake
function(<name> [<arg1> ...])
<commands>
endfunction()
Defines a function named ``<name>`` that takes arguments
named ``<arg1>``, ...
The ``<commands>`` in the function definition are recorded;
they are not invoked until the function is invoked. When
the function is invoked, the recorded ``<commands>`` are first
modified by replacing formal parameters (``${arg1}``, ...)
with the arguments passed, and then invoked as normal commands.
Define a function named ``<name>`` that takes arguments named ``arg1``,
``arg2``, ``arg3``, (...).
Commands listed after function, but before the matching
:command:`endfunction()`, are not invoked until the function is invoked.
When it is invoked, the commands recorded in the function are first
modified by replacing formal parameters (``${arg1}``) with the arguments
passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
``ARGC`` variable which will be set to the number of arguments passed
into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ... which
will have the actual values of the arguments passed in.
This facilitates creating functions with optional arguments.
Additionally ``ARGV`` holds the list of all arguments given to the
Furthermore, ``ARGV`` holds the list of all arguments given to the
function and ``ARGN`` holds the list of arguments past the last expected
argument.
Referencing to ``ARGV#`` arguments beyond ``ARGC`` have undefined
@@ -29,6 +31,10 @@ behavior. Checking that ``ARGC`` is greater than ``#`` is the only way
to ensure that ``ARGV#`` was passed to the function as an extra
argument.
Per legacy, the :command:`endfunction` command admits an optional
``<name>`` argument. If used, it must be a verbatim repeat of the
argument of the opening ``function`` command.
A function opens a new scope: see :command:`set(var PARENT_SCOPE)` for
details.