summaryrefslogtreecommitdiffstats
path: root/Help
diff options
context:
space:
mode:
authorCraig Scott <craig.scott@crascit.com>2020-12-11 07:25:42 (GMT)
committerCraig Scott <craig.scott@crascit.com>2020-12-11 07:25:42 (GMT)
commitff4d1d44f217bcbd90ba97f0fc41806cccb34e57 (patch)
tree1015ce99bc97a1c7c5474edd0d3156c12b9445ba /Help
parentb4c02a0a1d4ab285ba0594fc830cf5f0114464d9 (diff)
downloadCMake-ff4d1d44f217bcbd90ba97f0fc41806cccb34e57.zip
CMake-ff4d1d44f217bcbd90ba97f0fc41806cccb34e57.tar.gz
CMake-ff4d1d44f217bcbd90ba97f0fc41806cccb34e57.tar.bz2
Help: Clarify scope details of deferred call ids for cmake_language()
Fixes: #21586
Diffstat (limited to 'Help')
-rw-r--r--Help/command/cmake_language.rst17
1 files changed, 12 insertions, 5 deletions
diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst
index 40a45e3..99f874b 100644
--- a/Help/command/cmake_language.rst
+++ b/Help/command/cmake_language.rst
@@ -150,7 +150,12 @@ The currently scheduled list of deferred calls may be retrieved:
cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)
This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language
-Lists>` of deferred call ids.
+Lists>` of deferred call ids. The ids are for the directory scope in which
+the calls have been deferred to (i.e. where they will be executed), which can
+be different to the scope in which they were created. The ``DIRECTORY``
+option can be used to specify the scope for which to retrieve the call ids.
+If that option is not given, the call ids for the current directory scope will
+be returned.
Details of a specific call may be retrieved from its id:
@@ -163,8 +168,9 @@ Lists>` in which the first element is the name of the command to be
called, and the remaining elements are its unevaluated arguments (any
contained ``;`` characters are included literally and cannot be distinguished
from multiple arguments). If multiple calls are scheduled with the same id,
-this retrieves the first one. If no call is scheduled with the given id,
-this stores an empty string in the variable.
+this retrieves the first one. If no call is scheduled with the given id in
+the specified ``DIRECTORY`` scope (or the current directory scope if no
+``DIRECTORY`` option is given), this stores an empty string in the variable.
Deferred calls may be canceled by their id:
@@ -172,8 +178,9 @@ Deferred calls may be canceled by their id:
cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)
-This cancels all deferred calls matching any of the given ids.
-Unknown ids are silently ignored.
+This cancels all deferred calls matching any of the given ids in the specified
+``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option
+is given). Unknown ids are silently ignored.
Deferred Call Examples
""""""""""""""""""""""