From ff4d1d44f217bcbd90ba97f0fc41806cccb34e57 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Fri, 11 Dec 2020 18:25:42 +1100 Subject: Help: Clarify scope details of deferred call ids for cmake_language() Fixes: #21586 --- Help/command/cmake_language.rst | 17 ++++++++++++----- 1 file 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 ] GET_CALL_IDS ) This will store in ```` a :ref:`semicolon-separated list ` 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 ] CANCEL_CALL ...) -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 """""""""""""""""""""" -- cgit v0.12