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. The following variables are set in the scope of the function:

ARGC

The number of arguments passed into the function.

ARGV

The list of all arguments given to the function.

ARGV#

The variables ARGV0, ARGV1, ARGV2, ... which will have the actual values of the arguments passed in. References 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.

ARGN

The list of arguments past the last expected argument.

ARGNC

Added in version 4.5.

The number of arguments past the last expected argument.

See Also