New in version 3.18.
Call meta-operations on CMake commands.
Synopsis¶
cmake_language(CALL <command> [<arg>...])cmake_language(EVAL CODE <code>...)cmake_language(DEFER <options>... CALL <command> [<arg>...])cmake_language(SET_DEPENDENCY_PROVIDER <command> SUPPORTED_METHODS <methods>...)cmake_language(GET_MESSAGE_LOG_LEVEL <out-var>)cmake_language(EXIT <exit-code>)
Introduction¶
This command will call meta-operations on built-in CMake commands orthose created via the macro() or function() commands.
cmake_language does not introduce a new variable or policy scope.
Calling Commands¶
- cmake_language(CALL <command> [<arg>...])¶
Calls the named
<command>with the given arguments (if any).For example, the code:set(message_command "message")cmake_language(CALL ${message_command} STATUS "Hello World!")
is equivalent to
message(STATUS "Hello World!")
Note
To ensure consistency of the code, the following commands are not allowed:
if/elseif/else/endifblock/endblockwhile/endwhileforeach/endforeachfunction/endfunctionmacro/endmacro
Evaluating Code¶
- cmake_language(EVAL CODE <code>...)¶
Evaluates the
<code>...as CMake code.For example, the code:
set(A TRUE)set(B TRUE)set(C TRUE)set(condition "(A AND B) OR C")cmake_language(EVAL CODE " if (${condition}) message(STATUS TRUE) else() message(STATUS FALSE) endif()")
is equivalent to
set(A TRUE)set(B TRUE)set(C TRUE)set(condition "(A AND B) OR C")file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake " if (${condition}) message(STATUS TRUE) else() message(STATUS FALSE) endif()")include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)
Deferring Calls¶
New in version 3.19.
- cmake_language(DEFER <options>... CALL <command> [<arg>...])¶
Schedules a call to the named
<command>with the given arguments (if any)to occur at a later time. By default, deferred calls are executed as ifwritten at the end of the current directory'sCMakeLists.txtfile,except that they run even after a return() call. Variablereferences in arguments are evaluated at the time the deferred call isexecuted.See AlsoIntroduction to the Basics · Modern CMakeCMake basics, how does one write a good CMake project?The options are:
DIRECTORY <dir>Schedule the call for the end of the given directory instead of thecurrent directory. The
<dir>may reference either a sourcedirectory or its corresponding binary directory. Relative paths aretreated as relative to the current source directory.The given directory must be known to CMake, being either the top-leveldirectory or one added by add_subdirectory(). Furthermore,the given directory must not yet be finished processing. This meansit can be the current directory or one of its ancestors.
ID <id>Specify an identification for the deferred call.The
<id>may not be empty and may not begin with a capital letterA-Z.The<id>may begin with an underscore (_) only if it was generatedautomatically by an earlier call that usedID_VARto get the id.ID_VAR <var>Specify a variable in which to store the identification for thedeferred call. If
ID <id>is not given, a new identificationwill be generated and the generated id will start with an underscore (_).
The currently scheduled list of deferred calls may be retrieved:
cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)
This will store in
<var>a semicolon-separated list of deferred call ids. The ids are for the directory scope in whichthe calls have been deferred to (i.e. where they will be executed), which canbe different to the scope in which they were created. TheDIRECTORYoption can be used to specify the scope for which to retrieve the call ids.If that option is not given, the call ids for the current directory scopewill be returned.Details of a specific call may be retrieved from its id:
cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)
This will store in
<var>a semicolon-separated list in which the first element is the name of the command to becalled, and the remaining elements are its unevaluated arguments (anycontained;characters are included literally and cannot be distinguishedfrom multiple arguments). If multiple calls are scheduled with the same id,this retrieves the first one. If no call is scheduled with the given id inthe specifiedDIRECTORYscope (or the current directory scope if noDIRECTORYoption is given), this stores an empty string in the variable.Deferred calls may be canceled by their id:
cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)
This cancels all deferred calls matching any of the given ids in the specified
DIRECTORYscope (or the current directory scope if noDIRECTORYoptionis given). Unknown ids are silently ignored.
Deferred Call Examples¶
For example, the code:
cmake_language(DEFER CALL message "${deferred_message}")cmake_language(DEFER ID_VAR id CALL message "Canceled Message")cmake_language(DEFER CANCEL_CALL ${id})message("Immediate Message")set(deferred_message "Deferred Message")
prints:
Immediate MessageDeferred Message
The Canceled Message is never printed because its command iscanceled. The deferred_message variable reference is not evaluateduntil the call site, so it can be set after the deferred call is scheduled.
In order to evaluate variable references immediately when scheduling adeferred call, wrap it using cmake_language(EVAL). However, note thatarguments will be re-evaluated in the deferred call, though that can beavoided by using bracket arguments. For example:
set(deferred_message "Deferred Message 1")set(re_evaluated [[${deferred_message}]])cmake_language(EVAL CODE " cmake_language(DEFER CALL message [[${deferred_message}]]) cmake_language(DEFER CALL message \"${re_evaluated}\")")message("Immediate Message")set(deferred_message "Deferred Message 2")
also prints:
Immediate MessageDeferred Message 1Deferred Message 2
Dependency Providers¶
New in version 3.24.
Note
A high-level introduction to this feature can be found in theUsing Dependencies Guide.
- cmake_language(SET_DEPENDENCY_PROVIDER <command> SUPPORTED_METHODS <methods>...)¶
When a call is made to find_package() orFetchContent_MakeAvailable(), the call may be forwarded to adependency provider which then has the opportunity to fulfill the request.If the request is for one of the
<methods>specified when the providerwas set, CMake calls the provider's<command>with a set ofmethod-specific arguments. If the provider does not fulfill the request,or if the provider doesn't support the request's method, or no provideris set, the built-in find_package() orFetchContent_MakeAvailable() implementation is used to fulfillthe request in the usual way.One or more of the following values can be specified for the
<methods>when setting the provider:FIND_PACKAGEThe provider command accepts find_package() requests.
FETCHCONTENT_MAKEAVAILABLE_SERIALThe provider command accepts FetchContent_MakeAvailable()requests. It expects each dependency to be fed to the provider commandone at a time, not the whole list in one go.
Only one provider can be set at any point in time. If a provider is alreadyset when
cmake_language(SET_DEPENDENCY_PROVIDER)is called, the newprovider replaces the previously set one. The specified<command>mustalready exist whencmake_language(SET_DEPENDENCY_PROVIDER)is called.As a special case, providing an empty string for the<command>and no<methods>will discard any previously set provider.The dependency provider can only be set while processing one of the filesspecified by the CMAKE_PROJECT_TOP_LEVEL_INCLUDES variable.Thus, dependency providers can only be set as part of the first call toproject(). Calling
cmake_language(SET_DEPENDENCY_PROVIDER)outside of that context will result in an error.New in version 3.30: The PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE globalproperty can be set if the dependency provider also wants to be enabledin whole-project calls to try_compile().
Note
The choice of dependency provider should always be under the user's control.As a convenience, a project may choose to provide a file that users canlist in their CMAKE_PROJECT_TOP_LEVEL_INCLUDES variable, butthe use of such a file should always be the user's choice.
Provider commands¶
Providers define a single <command> to accept requests. The name ofthe command should be specific to that provider, not something overlygeneric that another provider might also use. This enables users to composedifferent providers in their own custom provider. The recommended form isxxx_provide_dependency(), where xxx is the provider-specific part(e.g. vcpkg_provide_dependency(), conan_provide_dependency(),ourcompany_provide_dependency(), and so on).
xxx_provide_dependency(<method> [<method-specific-args>...])
Because some methods expect certain variables to be set in the calling scope,the provider command should typically be implemented as a macro rather than afunction. This ensures it does not introduce a new variable scope.
The arguments CMake passes to the dependency provider depend on the type ofrequest. The first argument is always the method, and it will only everbe one of the <methods> that was specified when setting the provider.
FIND_PACKAGEThe
<method-specific-args>will be everything passed to thefind_package() call that requested the dependency. The first ofthese<method-specific-args>will therefore always be the name of thedependency. Dependency names are case-sensitive for this method becausefind_package() treats them case-sensitively too.If the provider command fulfills the request, it must set the same variablethat find_package() expects to be set. For a dependency named
depName, the provider must setdepName_FOUNDto true if it fulfilledthe request. If the provider returns without setting this variable, CMakewill assume the request was not fulfilled and will fall back to thebuilt-in implementation.If the provider needs to call the built-in find_package()implementation as part of its processing, it can do so by including the
BYPASS_PROVIDERkeyword as one of the arguments.FETCHCONTENT_MAKEAVAILABLE_SERIALThe
<method-specific-args>will be everything passed to theFetchContent_Declare() call that corresponds to the requesteddependency, with the following exceptions:If
SOURCE_DIRorBINARY_DIRwere not part of the originaldeclared arguments, they will be added with their default values.If FETCHCONTENT_TRY_FIND_PACKAGE_MODE is set to
NEVER,anyFIND_PACKAGE_ARGSwill be omitted.The
OVERRIDE_FIND_PACKAGEkeyword is always omitted.
The first of the
<method-specific-args>will always be the name of thedependency. Dependency names are case-insensitive for this method becauseFetchContent also treats them case-insensitively.If the provider fulfills the request, it should callFetchContent_SetPopulated(), passing the name of the dependency asthe first argument. The
SOURCE_DIRandBINARY_DIRarguments to thatcommand should only be given if the provider makes the dependency's sourceand build directories available in exactly the same way as the built-inFetchContent_MakeAvailable() command.If the provider returns without calling FetchContent_SetPopulated()for the named dependency, CMake will assume the request was not fulfilledand will fall back to the built-in implementation.
Note that empty arguments may be significant for this method (e.g. an emptystring following a
GIT_SUBMODULESkeyword). Therefore, if forwardingthese arguments on to another command, extra care must be taken to avoid sucharguments being silently dropped.If
FETCHCONTENT_SOURCE_DIR_<uppercaseDepName>is set, then thedependency provider will never see requests for the<depName>dependencyfor this method. When the user sets such a variable, they are explicitlyoverriding where to get that dependency from and are taking on theresponsibility that their overriding version meets any requirements for thatdependency and is compatible with whatever else in the project uses it.Depending on the value of FETCHCONTENT_TRY_FIND_PACKAGE_MODEand whether theOVERRIDE_FIND_PACKAGEoption was given toFetchContent_Declare(), havingFETCHCONTENT_SOURCE_DIR_<uppercaseDepName>set may also prevent thedependency provider from seeing requests for afind_package(depName)call too.
Provider Examples¶
This first example only intercepts find_package() calls. Theprovider command runs an external tool which copies the relevant artifactsinto a provider-specific directory, if that tool knows about the dependency.It then relies on the built-in implementation to then find those artifacts.FetchContent_MakeAvailable() calls would not go through the provider.
mycomp_provider.cmake¶
# Always ensure we have the policy settings this provider expectscmake_minimum_required(VERSION 3.24)set(MYCOMP_PROVIDER_INSTALL_DIR ${CMAKE_BINARY_DIR}/mycomp_packages CACHE PATH "The directory this provider installs packages to")# Tell the built-in implementation to look in our area first, unless# the find_package() call uses NO_..._PATH options to exclude itlist(APPEND CMAKE_MODULE_PATH ${MYCOMP_PROVIDER_INSTALL_DIR}/cmake)list(APPEND CMAKE_PREFIX_PATH ${MYCOMP_PROVIDER_INSTALL_DIR})macro(mycomp_provide_dependency method package_name) execute_process( COMMAND some_tool ${package_name} --installdir ${MYCOMP_PROVIDER_INSTALL_DIR} COMMAND_ERROR_IS_FATAL ANY )endmacro()cmake_language( SET_DEPENDENCY_PROVIDER mycomp_provide_dependency SUPPORTED_METHODS FIND_PACKAGE)
The user would then typically use the above file like so:
cmake -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=/path/to/mycomp_provider.cmake ...
The next example demonstrates a provider that accepts both methods, butonly handles one specific dependency. It enforces providing Google Testusing FetchContent, but leaves all other dependencies to befulfilled by CMake's built-in implementation. It accepts a few differentnames, which demonstrates one way of working around projects that hard-codean unusual or undesirable way of adding this particular dependency to thebuild. The example also demonstrates how to use the list() commandto preserve variables that may be overwritten by a call toFetchContent_MakeAvailable().
mycomp_provider.cmake¶
cmake_minimum_required(VERSION 3.24)# Because we declare this very early, it will take precedence over any# details the project might declare later for the same thinginclude(FetchContent)FetchContent_Declare( googletest GIT_REPOSITORY https://github.com/google/googletest.git GIT_TAG e2239ee6043f73722e7aa812a459f54a28552929 # release-1.11.0)# Both FIND_PACKAGE and FETCHCONTENT_MAKEAVAILABLE_SERIAL methods provide# the package or dependency name as the first method-specific argument.macro(mycomp_provide_dependency method dep_name) if("${dep_name}" MATCHES "^(gtest|googletest)$") # Save our current command arguments in case we are called recursively list(APPEND mycomp_provider_args ${method} ${dep_name}) # This will forward to the built-in FetchContent implementation, # which detects a recursive call for the same thing and avoids calling # the provider again if dep_name is the same as the current call. FetchContent_MakeAvailable(googletest) # Restore our command arguments list(POP_BACK mycomp_provider_args dep_name method) # Tell the caller we fulfilled the request if("${method}" STREQUAL "FIND_PACKAGE") # We need to set this if we got here from a find_package() call # since we used a different method to fulfill the request. # This example assumes projects only use the gtest targets, # not any of the variables the FindGTest module may define. set(${dep_name}_FOUND TRUE) elseif(NOT "${dep_name}" STREQUAL "googletest") # We used the same method, but were given a different name to the # one we populated with. Tell the caller about the name it used. FetchContent_SetPopulated(${dep_name} SOURCE_DIR "${googletest_SOURCE_DIR}" BINARY_DIR "${googletest_BINARY_DIR}" ) endif() endif()endmacro()cmake_language( SET_DEPENDENCY_PROVIDER mycomp_provide_dependency SUPPORTED_METHODS FIND_PACKAGE FETCHCONTENT_MAKEAVAILABLE_SERIAL)
The final example demonstrates how to modify arguments to afind_package() call. It forces all such calls to have theQUIET keyword. It uses the BYPASS_PROVIDER keyword to preventcalling the provider command recursively for the same dependency.
mycomp_provider.cmake¶
cmake_minimum_required(VERSION 3.24)macro(mycomp_provide_dependency method) find_package(${ARGN} BYPASS_PROVIDER QUIET)endmacro()cmake_language( SET_DEPENDENCY_PROVIDER mycomp_provide_dependency SUPPORTED_METHODS FIND_PACKAGE)
Getting current message log level¶
New in version 3.25.
- cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>)¶
Writes the current message() logging levelinto the given
<output_variable>.See message() for the possible logging levels.
The current message logging level can be set either using the--log-levelcommand line option of the cmake(1) program or usingthe CMAKE_MESSAGE_LOG_LEVEL variable.
If both the command line option and the variable are set, the command lineoption takes precedence. If neither are set, the default logging levelis returned.
Terminating Scripts¶
New in version 3.29.
- cmake_language(EXIT <exit-code>)¶
Terminate the current cmake -P script and exit with
<exit-code>.This command works only in script mode.If used outside of that context, it will cause a fatal error.
The
<exit-code>should be non-negative.If<exit-code>is negative, then the behavioris unspecified (e.g., on Windows the error code -1becomes0xffffffff, and on Linux it becomes 255).Exit codes above 255 may not be supported by the underlyingshell or platform, and some shells may interpret valuesabove 125 specially. Therefore, it is advisable to onlyspecify an<exit-code>in the range 0 to 125.
