blob: 3c4a1cd8a6eb775699c45cb4cb7cf3508472685d (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
|
return
------
Return from a file, directory or function.
.. code-block:: cmake
return([PROPAGATE <var-name>...])
Returns from a file, directory or function. When this command is
encountered in an included file (via :command:`include` or
:command:`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 :command:`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``
.. versionadded:: 3.25
This option set or unset the specified variables in the parent directory or
function caller scope. This is equivalent to :command:`set(PARENT_SCOPE)` or
:command:`unset(PARENT_SCOPE)` commands.
The option ``PROPAGATE`` can be very useful in conjunction with the
:command:`block` command because the :command:`return` will cross over
various scopes created by the :command:`block` commands.
.. code-block:: cmake
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 :policy:`CMP0140` controls the behavior regarding the arguments of the
command.
Note that a :command:`macro <macro>`, unlike a :command:`function <function>`,
is expanded in place and therefore cannot handle ``return()``.
See Also
^^^^^^^^
* :command:`block`
* :command:`function`
|
