return

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

New 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:

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"
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