Return from a file, directory or function.
return([PROPAGATE <var-name>...])
When this command is encountered in an included file (via include()
or
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 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 macro()
, unlike a function()
,
is expanded in place and therefore cannot handle return()
.
Policy CMP0140
controls the behavior regarding the arguments of the
command. All arguments are ignored unless that policy is set to NEW
.
PROPAGATE
Added in version 3.25.
This option sets or unsets the specified variables in the parent directory or
function caller scope. This is equivalent to set(PARENT_SCOPE)
or
unset(PARENT_SCOPE)
commands, except for the way it interacts
with the block()
command, as described below.
The PROPAGATE
option can be very useful in conjunction with the
block()
command. A return
will propagate the
specified variables through any enclosing block scopes created by the
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:
cmake_minimum_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"
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()