return¶
Return from a file, directory or function.
return([PROPAGATE <var-name>...])
Returns from a file, directory or function. 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 the function.
PROPAGATE
New in version 3.25.
This option set or unset the specified variables in the parent directory or function caller scope. This is equivalent to
set(PARENT_SCOPE)
orunset(PARENT_SCOPE)
commands.The option
PROPAGATE
can be very useful in conjunction with theblock()
command because thereturn()
will cross over various scopes created by theblock()
commands.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 CMP0140
controls the behavior regarding the arguments of the
command.
Note that a macro
, unlike a function
,
is expanded in place and therefore cannot handle return()
.