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) or unset(PARENT_SCOPE) commands.

The option PROPAGATE can be very useful in conjunction with the block() command because the return() will cross over various scopes created by the block() 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().

See Also