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()