Merge topic 'return-propagate-variables'

838a5fae23 return(): Propagate variables to result scope
8f0e1f2111 cmMakefile: add RaiseScope for list of variables

Acked-by: Kitware Robot <kwrobot@kitware.com>
Tested-by: buildbot <buildbot@kitware.com>
Acked-by: Robert Maynard <robertjmaynard@gmail.com>
Merge-request: !7634

Help/command/block.rst

@@ -71,4 +71,5 @@ See Also
 ^^^^^^^^
 
   * :command:`endblock`
+  * :command:`return`
   * :command:`cmake_policy`

Help/command/return.rst

@@ -5,7 +5,7 @@ Return from a file, directory or function.
 
 .. code-block:: cmake
 
-  return()
+  return([PROPAGATE <var-name>...])
 
 Returns from a file, directory or function.  When this command is
 encountered in an included file (via :command:`include` or
@@ -16,5 +16,39 @@ deferred calls scheduled by :command:`cmake_language(DEFER)` are invoked and
 control is returned to the parent directory if there is one.  If return is
 called in a function, control is returned to the caller of the function.
 
+``PROPAGATE``
+  .. versionadded:: 3.25
+
+  This option set or unset the specified variables in the parent directory or
+  function caller scope. This is equivalent to :command:`set(PARENT_SCOPE)` or
+  :command:`unset(PARENT_SCOPE)` commands.
+
+  The option ``PROPAGATE`` can be very useful in conjunction with the
+  :command:`block` command because the :command:`return` will cross over
+  various scopes created by the :command:`block` commands.
+
+  .. code-block:: cmake
+
+    function(MULTI_SCOPES RESULT_VARIABLE)
+      block(SCOPE_FOR VARIABLES)
+        # here set(PARENT_SCOPE) is not usable because it will not set the
+        # variable in the caller scope but in the parent scope of the block()
+        set(${RESULT_VARIABLE} "new-value")
+        return(PROPAGATE ${RESULT_VARIABLE})
+      endblock()
+    endfunction()
+
+    set(MY_VAR "initial-value")
+    multi_scopes(MY_VAR)
+    # here MY_VAR will holds "new-value"
+
+Policy :policy:`CMP0140` controls the behavior regarding the arguments of the
+command.
+
 Note that a :command:`macro <macro>`, unlike a :command:`function <function>`,
 is expanded in place and therefore cannot handle ``return()``.
+
+See Also
+^^^^^^^^
+
+  * :command:`block`

Help/command/set.rst

@@ -30,9 +30,9 @@ applicable to the case at hand). The previous state of the variable's value
 stays the same in the current scope (e.g., if it was undefined before, it is
 still undefined and if it had a value, it is still that value).
 
-The :command:`block(PROPAGATE)` command can be used as an alternate method to
-:command:`set(PARENT_SCOPE)` and :command:`unset(PARENT_SCOPE)` commands to
-update the parent scope.
+The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands can
+be used as an alternate method to the :command:`set(PARENT_SCOPE)` and
+:command:`unset(PARENT_SCOPE)` commands to update the parent scope.
 
 Set Cache Entry
 ^^^^^^^^^^^^^^^

Help/manual/cmake-policies.7.rst

@@ -52,6 +52,14 @@ to determine whether to report an error on use of deprecated macros or
 functions.
 
 
+Policies Introduced by CMake 3.25
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0140: The return() command checks its arguments. </policy/CMP0140>
+
 Policies Introduced by CMake 3.24
 =================================
 

Help/policy/CMP0140.rst

@@ -0,0 +1,17 @@
+CMP0140
+-------
+
+.. versionadded:: 3.25
+
+The :command:`return` command checks its parameters.
+
+The ``OLD`` behavior for this policy is to ignore any parameters given to the
+command.
+The ``NEW`` behavior is to check validity of the parameters.
+
+This policy was introduced in CMake version 3.25.
+CMake version |release| warns when the policy is not set and uses
+``OLD`` behavior.  Use the :command:`cmake_policy` command to set
+it to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt

Help/release/dev/return-PROPAGATE.rst

@@ -0,0 +1,5 @@
+return-PROPAGATE
+----------------
+
+* The :command:`return` command gains the capability to propagate variables to
+  the include directory of function caller scope. See policy :policy:`CMP0140`.