function¶
Start recording a function for later invocation as a command.
function(<name> [<arg1> ...])
<commands>
endfunction()
Defines a function named <name> that takes arguments named
<arg1>, ... The <commands> in the function definition
are recorded; they are not executed until the function is invoked.
Per legacy, the endfunction() command admits an optional
<name> argument. If used, it must be a verbatim repeat of the
argument of the opening function command.
A function opens a new scope: see set(var PARENT_SCOPE) for
details.
See the cmake_policy() command documentation for the behavior
of policies inside functions.
See the macro() command documentation for differences
between CMake functions and macros.
Invocation¶
The function invocation is case-insensitive. A function defined as
function(foo)
<commands>
endfunction()
can be invoked through any of
foo()
Foo()
FOO()
cmake_language(CALL foo)
and so on. However, it is strongly recommended to stay with the case chosen in the function definition. Typically functions use all-lowercase names.
Added in version 3.18: The cmake_language(CALL ...) command can also be used to
invoke the function.
Arguments¶
When the function is invoked, the recorded <commands> are first
modified by replacing formal parameters (${arg1}, ...) with the
arguments passed, and then invoked as normal commands.
In addition to referencing the formal parameters you can reference the
ARGC variable which will be set to the number of arguments passed
into the function as well as ARGV0, ARGV1, ARGV2, ... which
will have the actual values of the arguments passed in. This facilitates
creating functions with optional arguments.
Furthermore, ARGV holds the list of all arguments given to the
function and ARGN holds the list of arguments past the last expected
argument. Referencing to ARGV# arguments beyond ARGC have
undefined behavior. Checking that ARGC is greater than # is
the only way to ensure that ARGV# was passed to the function as an
extra argument.