return — CMake 4.0.2 Documentation (original) (raw)
Return from a file, directory or function.
return([PROPAGATE ...])
When this command is encountered in an included file (via include() orfind_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) orunset(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 theblock() command. A return
will propagate the specified variables through any enclosing block scopes created by theblock() 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_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"
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 <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>r</mi><mi>e</mi><mi>s</mi><mi>u</mi><mi>l</mi><msub><mi>t</mi><mi>v</mi></msub><mi>a</mi><mi>r</mi><mn>1</mn></mrow><annotation encoding="application/x-tex">{result_var1} </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8444em;vertical-align:-0.15em;"></span><span class="mord"><span class="mord mathnormal">res</span><span class="mord mathnormal">u</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord"><span class="mord mathnormal">t</span><span class="msupsub"><span class="vlist-t vlist-t2"><span class="vlist-r"><span class="vlist" style="height:0.1514em;"><span style="top:-2.55em;margin-left:0em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mathnormal mtight" style="margin-right:0.03588em;">v</span></span></span></span><span class="vlist-s"></span></span><span class="vlist-r"><span class="vlist" style="height:0.15em;"><span></span></span></span></span></span></span><span class="mord mathnormal">a</span><span class="mord mathnormal" style="margin-right:0.02778em;">r</span><span class="mord">1</span></span></span></span></span>{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()