You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
93 lines
3.2 KiB
93 lines
3.2 KiB
return
|
|
------
|
|
|
|
Return from a file, directory or function.
|
|
|
|
.. code-block:: cmake
|
|
|
|
return([PROPAGATE <var-name>...])
|
|
|
|
When this command is encountered in an included file (via :command:`include` or
|
|
:command:`find_package`), it causes processing of the current file to stop
|
|
and control is returned to the including file. If it is encountered in a
|
|
file which is not included by another file, e.g. a ``CMakeLists.txt``,
|
|
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 that function. Note that a :command:`macro`, unlike a :command:`function`,
|
|
is expanded in place and therefore cannot handle ``return()``.
|
|
|
|
Policy :policy:`CMP0140` controls the behavior regarding the arguments of the
|
|
command. All arguments are ignored unless that policy is set to ``NEW``.
|
|
|
|
``PROPAGATE``
|
|
.. versionadded:: 3.25
|
|
|
|
This option sets or unsets 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, except for the way it interacts
|
|
with the :command:`block` command, as described below.
|
|
|
|
The ``PROPAGATE`` option can be very useful in conjunction with the
|
|
:command:`block` command. A ``return`` will propagate the
|
|
specified variables through any enclosing block scopes created by the
|
|
:command:`block` commands. Inside a function, this ensures the variables
|
|
are propagated to the function's caller, regardless of any blocks within
|
|
the function. If not inside a function, it ensures the variables are
|
|
propagated to the parent file or directory scope. For example:
|
|
|
|
.. code-block:: cmake
|
|
:caption: CMakeLists.txt
|
|
|
|
cmake_version_required(VERSION 3.25)
|
|
project(example)
|
|
|
|
set(var1 "top-value")
|
|
|
|
block(SCOPE_FOR VARIABLES)
|
|
add_subdirectory(subDir)
|
|
# var1 has the value "block-nested"
|
|
endblock()
|
|
|
|
# var1 has the value "top-value"
|
|
|
|
.. code-block:: cmake
|
|
:caption: subDir/CMakeLists.txt
|
|
|
|
function(multi_scopes result_var1 result_var2)
|
|
block(SCOPE_FOR VARIABLES)
|
|
# This would only propagate out of the immediate block, not to
|
|
# the caller of the function.
|
|
#set(${result_var1} "new-value" PARENT_SCOPE)
|
|
#unset(${result_var2} PARENT_SCOPE)
|
|
|
|
# This propagates the variables through the enclosing block and
|
|
# out to the caller of the function.
|
|
set(${result_var1} "new-value")
|
|
unset(${result_var2})
|
|
return(PROPAGATE ${result_var1} ${result_var2})
|
|
endblock()
|
|
endfunction()
|
|
|
|
set(var1 "some-value")
|
|
set(var2 "another-value")
|
|
|
|
multi_scopes(var1 var2)
|
|
# Now var1 will hold "new-value" and var2 will be unset
|
|
|
|
block(SCOPE_FOR VARIABLES)
|
|
# This return() will set var1 in the directory scope that included us
|
|
# via add_subdirectory(). The surrounding block() here does not limit
|
|
# propagation to the current file, but the block() in the parent
|
|
# directory scope does prevent propagation going any further.
|
|
set(var1 "block-nested")
|
|
return(PROPAGATE var1)
|
|
endblock()
|
|
|
|
See Also
|
|
^^^^^^^^
|
|
|
|
* :command:`block`
|
|
* :command:`function`
|