CMAKE-COMMANDS(7) CMake CMAKE-COMMANDS(7) NAME cmake-commands - CMake Language Command Reference SCRIPTING COMMANDS These commands are always available. block Added in version 3.25. Evaluate a group of commands with a dedicated variable and/or policy scope. block([SCOPE_FOR [DIAGNOSTICS] [POLICIES] [VARIABLES]] [PROPAGATE ...]) endblock() All commands between block() and the matching endblock() <# command:endblock> are recorded without being invoked. Once the endblock() <#command:endblock> is evaluated, the recorded list of commands is invoked inside the requested scopes, then the scopes created by the block() command are removed. SCOPE_FOR Specify which scopes must be created. DIAGNOSTICS Added in version 4.4. Create a new diagnostic scope. This is equivalent to cmake_diagnostic(PUSH) <#push> with an automatic cmake_diagnostic(POP) <#pop> when leaving the block scope. POLICIES Create a new policy scope. This is equivalent to cmake_policy(PUSH) <#push> with an automatic cmake_policy(POP) <#pop> when leaving the block scope. VARIABLES Create a new variable scope. If SCOPE_FOR is not specified, this is equivalent to: block(SCOPE_FOR VARIABLES POLICIES DIAGNOSTICS) PROPAGATE When a variable scope is created by the block() command, this option sets or unsets the specified variables in the parent scope. This is equivalent to set(PARENT_SCOPE) <#command:set> or unset(PARENT_SCOPE) <#command:unset> commands. set(var1 "INIT1") set(var2 "INIT2") set(var3 "INIT3") block(PROPAGATE var1 var2) set(var1 "VALUE1") unset(var2) set(var3 "VALUE3") endblock() # Now var1 holds VALUE1, var2 is unset, and var3 holds the initial value INIT3 This option is only allowed when a variable scope is created. An error will be raised in the other cases. When the block() is inside a foreach() <#command:foreach> or while() <# command:while> command, the break() <#command:break> and continue() <# command:continue> commands can be used inside the block. while(TRUE) block() ... # the break() command will terminate the while() command break() endblock() endwhile() See Also o endblock() <#command:endblock> o return() <#command:return> o cmake_policy() <#command:cmake_policy> break Break from an enclosing foreach or while loop. break() Breaks from an enclosing foreach() <#command:foreach> or while() <# command:while> loop. See also the continue() <#command:continue> command. cmake_diagnostic Added in version 4.4. Manage CMake Diagnostic settings. See the cmake-diagnostics(7) <# manual:cmake-diagnostics(7)> manual for a list of available categories. Synopsis Setting Diagnostics cmake_diagnostic(SET [RECURSE]) cmake_diagnostic(PROMOTE [NO_RECURSE]) cmake_diagnostic(DEMOTE [NO_RECURSE]) Checking Diagnostic Actions cmake_diagnostic(GET ) CMake Diagnostic Stack cmake_diagnostic(PUSH) cmake_diagnostic(POP) Setting Diagnostics cmake_diagnostic(SET CMD_ [RECURSE]) cmake_diagnostic(PROMOTE CMD_ [NO_RECURSE]) cmake_diagnostic(DEMOTE CMD_ [NO_RECURSE]) Set or alter the action taken when a diagnostic belonging to a particular category is triggered. The SET subcommand sets the action for the specified diagnostic category. The PROMOTE subcommand increases the severity for the specified diagnostic category, or does nothing if the action was already set to an equal or higher severity. The DEMOTE subcommand decreases the severity for the specified diagnostic category, or does nothing if the action was already set to an equal or lower severity. The possible s (in order of severity) are: IGNORE Do nothing. WARN Report a warning and continue processing. SEND_ERROR Report an error, continue processing, but skip generation. The cmake(1) <#manual:cmake(1)> executable will return a non-zero exit code <#cmake-exit-code>. FATAL_ERROR Report an error, stop processing and generation. The cmake(1) <#manual:cmake(1)> executable will return a non-zero exit code <#cmake-exit-code>. Some diagnostic categories are hierarchical. The RECURSE and NO_RECURSE options determine whether changing the action for a diagnostic category also modifies any child categories. By default, the PROMOTE and DEMOTE subcommands are recursive, while the SET subcommand is not. Note that the alteration for child categories is independent of the prior action set on any parents; that is, PROMOTE and DEMOTE, when operating recursively, will operate on all child categories even if a parent category's action was not altered. Checking Diagnostic Actions cmake_diagnostic(GET CMD_ ) Check what action is currently specified for a diagnostic category. The output value will be one of IGNORE, WARN, SEND_ERROR or FATAL_ERROR. CMake Diagnostic Stack CMake keeps diagnostic settings on a stack, so changes made by the cmake_diagnostic command affect only the top of the stack. A new entry on the diagnostic stack is managed automatically for each subdirectory to protect its parents and siblings. CMake also manages a new entry for scripts loaded by include() <#command:include> and find_package() <#command:find_package> commands except when invoked with the NO_DIAGNOSTIC_SCOPE option. The cmake_diagnostic command provides an interface to manage custom entries on the diagnostic stack: cmake_diagnostic(PUSH) Create a new entry on the diagnostic stack. cmake_diagnostic(POP) Remove the last diagnostic stack entry created with cmake_diagnostic(PUSH). Each PUSH must have a matching POP to erase any changes. This is useful to make temporary changes to diagnostic settings. Calls to the cmake_diagnostic(SET), cmake_diagnostic(PROMOTE), or cmake_diagnostic(DEMOTE) commands influence only the current top of the diagnostic stack. The block(SCOPE_FOR DIAGNOSTICS) <#command:block> command offers a more flexible and more secure way to manage the diagnostic stack. The pop action is done automatically when leaving the block scope, so there is no need to precede each return() <#command:return> with a call to cmake_diagnostic(POP). # stack management with cmake_diagnostic() function(my_func) cmake_diagnostic(PUSH) cmake_diagnostic(SET ...) if () ... cmake_diagnostic(POP) return() elseif() ... cmake_diagnostic(POP) return() endif() ... cmake_diagnostic(POP) endfunction() # stack management with block()/endblock() function(my_func) block(SCOPE_FOR DIAGNOSTICS) cmake_diagnostic(SET ...) if () ... return() elseif() ... return() endif() ... endblock() endfunction() Commands created by the function() <#command:function> and macro() <# command:macro> commands record diagnostic settings when they are created and use the pre-record diagnostics when they are invoked. If the function or macro implementation sets diagnostics, the changes automatically propagate up through callers until they reach the closest nested diagnostic stack entry. cmake_host_system_information Query various host system information. Synopsis Query host system specific information cmake_host_system_information(RESULT QUERY ...) Query the Windows registry cmake_host_system_information(RESULT QUERY WINDOWS_REGISTRY ...) Query host system specific information cmake_host_system_information(RESULT QUERY ...) Queries system information of the host system on which cmake runs. One or more can be provided to select the information to be queried. The list of queried values is stored in . can be one of the following values: NUMBER_OF_LOGICAL_CORES Number of logical cores NUMBER_OF_PHYSICAL_CORES Number of physical cores HOSTNAME Hostname FQDN Fully qualified domain name TOTAL_VIRTUAL_MEMORY Total virtual memory in MiB [1] AVAILABLE_VIRTUAL_MEMORY Available virtual memory in MiB [1] TOTAL_PHYSICAL_MEMORY Total physical memory in MiB [1] AVAILABLE_PHYSICAL_MEMORY Available physical memory in MiB [1] IS_64BIT Added in version 3.10. One if processor is 64Bit HAS_FPU Added in version 3.10. One if processor has floating point unit HAS_MMX Added in version 3.10. One if processor supports MMX instructions HAS_MMX_PLUS Added in version 3.10. One if processor supports Ext. MMX instructions HAS_SSE Added in version 3.10. One if processor supports SSE instructions HAS_SSE2 Added in version 3.10. One if processor supports SSE2 instructions HAS_SSE_FP Added in version 3.10. One if processor supports SSE FP instructions HAS_SSE_MMX Added in version 3.10. One if processor supports SSE MMX instructions HAS_AMD_3DNOW Added in version 3.10. One if processor supports 3DNow instructions HAS_AMD_3DNOW_PLUS Added in version 3.10. One if processor supports 3DNow+ instructions HAS_IA64 Added in version 3.10. One if IA64 processor emulating x86 HAS_SERIAL_NUMBER Added in version 3.10. One if processor has serial number HAS_APIC Added in version 4.3. One if processor supports APIC HAS_L1_CACHE Added in version 4.3. One if processor has L1 cache PROCESSOR_SERIAL_NUMBER Added in version 3.10. Processor serial number PROCESSOR_NAME Added in version 3.10. Human readable processor name PROCESSOR_DESCRIPTION Added in version 3.10. Human readable full processor description LOCALE_CHARSET Added in version 4.3. The locale's character set, if known, otherwise empty. This is the encoding <#cmake-language-encoding> expected in cmake-language(7) <#manual:cmake-language(7)> files and scripts: o On Windows, this is always UTF-8. o On UNIX and macOS, this is based on the current locale. OS_NAME Added in version 3.10. The host operating system name: o On UNIX platforms, this is uname -s. o On Apple platforms, this is sw_vers -productName. o On Windows, this is Windows. See also CMAKE_HOST_SYSTEM_NAME <# variable:CMAKE_HOST_SYSTEM_NAME>. OS_RELEASE Added in version 3.10. The OS sub-type e.g. on Windows Professional OS_VERSION Added in version 3.10. The OS build ID OS_PLATFORM Added in version 3.10. See CMAKE_HOST_SYSTEM_PROCESSOR <# variable:CMAKE_HOST_SYSTEM_PROCESSOR> MSYSTEM_PREFIX Added in version 3.28. Available only on Windows hosts. In a MSYS or MinGW development environment that sets the MSYSTEM environment variable, this is its installation prefix. Otherwise, this is the empty string. FAMILY_ID Added in version 4.3. The processor family name MODEL_ID Added in version 4.3. The processor model ID MODEL_NAME Added in version 4.3. The processor model name PROCESSOR_APIC_ID Added in version 4.3. The processor APIC ID PROCESSOR_CACHE_SIZE Added in version 4.3. The processor L1 cache size PROCESSOR_CLOCK_FREQUENCY Added in version 4.3. The processor clock frequency VENDOR_ID Added in version 4.3. The processor vendor ID VENDOR_STRING Added in version 4.3. The processor vendor string DISTRIB_INFO Added in version 3.22. Read /etc/os-release file and define the given into a list of read variables DISTRIB_ Added in version 3.22. Get the variable (see man 5 os-release ) if it exists in the /etc/os-release file Example: cmake_host_system_information(RESULT PRETTY_NAME QUERY DISTRIB_PRETTY_NAME) message(STATUS "${PRETTY_NAME}") cmake_host_system_information(RESULT DISTRO QUERY DISTRIB_INFO) foreach(VAR IN LISTS DISTRO) message(STATUS "${VAR}=`${${VAR}}`") endforeach() Output: -- Ubuntu 20.04.2 LTS -- DISTRO_BUG_REPORT_URL=`https://bugs.launchpad.net/ubuntu/` -- DISTRO_HOME_URL=`https://www.ubuntu.com/` -- DISTRO_ID=`ubuntu` -- DISTRO_ID_LIKE=`debian` -- DISTRO_NAME=`Ubuntu` -- DISTRO_PRETTY_NAME=`Ubuntu 20.04.2 LTS` -- DISTRO_PRIVACY_POLICY_URL=`https://www.ubuntu.com/legal/terms-and-policies/privacy-policy` -- DISTRO_SUPPORT_URL=`https://help.ubuntu.com/` -- DISTRO_UBUNTU_CODENAME=`focal` -- DISTRO_VERSION=`20.04.2 LTS (Focal Fossa)` -- DISTRO_VERSION_CODENAME=`focal` -- DISTRO_VERSION_ID=`20.04` If /etc/os-release file is not found, the command tries to gather OS identification via fallback scripts. The fallback script can use various distribution-specific files to collect OS identification data and map it into man 5 os-release variables. Fallback Interface Variables CMAKE_GET_OS_RELEASE_FALLBACK_SCRIPTS In addition to the scripts shipped with CMake, a user may append full paths of their script(s) to this list. The script filename has the following format: NNN-.cmake, where NNN is three digits used to apply collected scripts in a specific order. CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ Variables collected by the user provided fallback script ought to be assigned to CMake variables using this naming convention. Example, the ID variable from the manual becomes CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID. CMAKE_GET_OS_RELEASE_FALLBACK_RESULT The fallback script ought to store names of all assigned CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ variables in this list. Example: # 000-FallbackScript.cmake # # Try to detect some old distribution # See also # - http://linuxmafia.com/faq/Admin/release-files.html # if(NOT EXISTS "${CMAKE_SYSROOT}/etc/foobar-release") return() endif() # Get the first string only file( STRINGS "${CMAKE_SYSROOT}/etc/foobar-release" CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT LIMIT_COUNT 1 ) # # Example: # # Foobar distribution release 1.2.3 (server) # if(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT MATCHES "Foobar distribution release ([0-9\.]+) .*") set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME Foobar) set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME "${CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT}") set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID foobar) set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION ${CMAKE_MATCH_1}) set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID ${CMAKE_MATCH_1}) list( APPEND CMAKE_GET_OS_RELEASE_FALLBACK_RESULT CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID ) endif() unset(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT) Then this script can be applied as a fallback to determine the missing host system information: list( APPEND CMAKE_GET_OS_RELEASE_FALLBACK_SCRIPTS ${CMAKE_CURRENT_SOURCE_DIR}/000-FallbackScript.cmake ) cmake_host_system_information(RESULT info QUERY DISTRIB_INFO) FOOTNOTES [1] One MiB (mebibyte) is equal to 1024x1024 bytes. Query the Windows registry Added in version 3.24. cmake_host_system_information(RESULT QUERY WINDOWS_REGISTRY [VALUE_NAMES|SUBKEYS|VALUE ] [VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)] [SEPARATOR ] [ERROR_VARIABLE ]) Performs query operations on local computer registry subkey. Returns a list of subkeys or value names that are located under the specified subkey in the registry or the data of the specified value name. The result of the queried entity is stored in . Note: Querying registry for any other platforms than Windows, including CYGWIN, will always returns an empty string and sets an error message in the variable specified with sub-option ERROR_VARIABLE. specify the full path of a subkey on the local computer. The must include a valid root key. Valid root keys for the local computer are: o HKLM or HKEY_LOCAL_MACHINE o HKCU or HKEY_CURRENT_USER o HKCR or HKEY_CLASSES_ROOT o HKU or HKEY_USERS o HKCC or HKEY_CURRENT_CONFIG And, optionally, the path to a subkey under the specified root key. The path separator can be the slash or the backslash. is not case sensitive. For example: cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM") cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware") cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKCU\\SOFTWARE\\Kitware") VALUE_NAMES Request the list of value names defined under . If a default value is defined, it will be identified with the special name (default). SUBKEYS Request the list of subkeys defined under . VALUE Request the data stored in value named . If VALUE is not specified or argument is the special name (default), the content of the default value, if any, will be returned. # query default value for HKLM/SOFTWARE/Kitware key cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware") # query default value for HKLM/SOFTWARE/Kitware key using special value name cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware" VALUE "(default)") Supported types are: o REG_SZ. o REG_EXPAND_SZ. The returned data is expanded. o REG_MULTI_SZ. The returned is expressed as a CMake list. See also SEPARATOR sub-option. o REG_DWORD. o REG_QWORD. For all other types, an empty string is returned. VIEW Specify which registry views must be queried. When not specified, BOTH view is used. 64 Query the 64bit registry. On 32bit Windows, returns always an empty string. 32 Query the 32bit registry. 64_32 For VALUE sub-option or default value, query the registry using view 64, and if the request failed, query the registry using view 32. For VALUE_NAMES and SUBKEYS sub-options, query both views (64 and 32) and merge the results (sorted and duplicates removed). 32_64 For VALUE sub-option or default value, query the registry using view 32, and if the request failed, query the registry using view 64. For VALUE_NAMES and SUBKEYS sub-options, query both views (32 and 64) and merge the results (sorted and duplicates removed). HOST Query the registry matching the architecture of the host: 64 on 64bit Windows and 32 on 32bit Windows. TARGET Query the registry matching the architecture specified by CMAKE_SIZEOF_VOID_P <#variable:CMAKE_SIZEOF_VOID_P> variable. If not defined, fallback to HOST view. BOTH Query both views (32 and 64). The order depends of the following rules: If CMAKE_SIZEOF_VOID_P <# variable:CMAKE_SIZEOF_VOID_P> variable is defined. Use the following view depending of the content of this variable: o 8: 64_32 o 4: 32_64 If CMAKE_SIZEOF_VOID_P <#variable:CMAKE_SIZEOF_VOID_P> variable is not defined, rely on architecture of the host: o 64bit: 64_32 o 32bit: 32 SEPARATOR Specify the separator character for REG_MULTI_SZ type. When not specified, the character \0 is used. ERROR_VARIABLE Returns any error raised during query operation. In case of success, the variable holds an empty string. cmake_language Added in version 3.18. Call meta-operations on CMake commands. Synopsis cmake_language(CALL [...]) cmake_language(EVAL CODE ...) cmake_language(DEFER ... CALL [...]) cmake_language(SET_DEPENDENCY_PROVIDER SUPPORTED_METHODS ...) cmake_language(GET_MESSAGE_LOG_LEVEL ) cmake_language(EXIT ) cmake_language(TRACE ...) Introduction This command will call meta-operations on built-in CMake commands or those created via the macro() <#command:macro> or function() <# command:function> commands. cmake_language does not introduce a new variable or policy scope. Calling Commands cmake_language(CALL [...]) Calls the named 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: o if / elseif / else / endif o block / endblock o while / endwhile o foreach / endforeach o function / endfunction o macro / endmacro Evaluating Code cmake_language(EVAL CODE ...) Evaluates the ... 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 Added in version 3.19. cmake_language(DEFER ... CALL [...]) Schedules a call to the named with the given arguments (if any) to occur at a later time. By default, deferred calls are executed as if written at the end of the current directory's CMakeLists.txt file, except that they run even after a return() <#command:return> call. Variable references in arguments are evaluated at the time the deferred call is executed. The options are: DIRECTORY Schedule the call for the end of the given directory instead of the current directory. The may reference either a source directory or its corresponding binary directory. Relative paths are treated as relative to the current source directory. The given directory must be known to CMake, being either the top-level directory or one added by add_subdirectory() <#command:add_subdirectory>. Furthermore, the given directory must not yet be finished processing. This means it can be the current directory or one of its ancestors. ID Specify an identification for the deferred call. The may not be empty and may not begin with a capital letter A-Z. The may begin with an underscore (_) only if it was generated automatically by an earlier call that used ID_VAR to get the id. ID_VAR Specify a variable in which to store the identification for the deferred call. If ID is not given, a new identification will 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 ] GET_CALL_IDS ) This will store in a semicolon-separated list <#cmake- language-lists> of deferred call ids. The ids are for the directory scope in which the calls have been deferred to (i.e. where they will be executed), which can be different to the scope in which they were created. The DIRECTORY option 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 scope will be returned. Details of a specific call may be retrieved from its id: cmake_language(DEFER [DIRECTORY ] GET_CALL ) This will store in a semicolon-separated list <#cmake- language-lists> in which the first element is the name of the command to be called, and the remaining elements are its unevaluated arguments (any contained ; characters are included literally and cannot be distinguished from 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 in the specified DIRECTORY scope (or the current directory scope if no DIRECTORY option is given), this stores an empty string in the variable. Deferred calls may be canceled by their id: cmake_language(DEFER [DIRECTORY ] CANCEL_CALL ...) This cancels all deferred calls matching any of the given ids in the specified DIRECTORY scope (or the current directory scope if no DIRECTORY option is 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 Message Deferred Message The Canceled Message is never printed because its command is canceled. The deferred_message variable reference is not evaluated until the call site, so it can be set after the deferred call is scheduled. In order to evaluate variable references immediately when scheduling a deferred call, wrap it using cmake_language(EVAL). However, note that arguments will be re-evaluated in the deferred call, though that can be avoided 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 Message Deferred Message 1 Deferred Message 2 Dependency Providers Added in version 3.24. Note: A high-level introduction to this feature can be found in the Using Dependencies Guide <#dependency-providers-overview>. cmake_language(SET_DEPENDENCY_PROVIDER SUPPORTED_METHODS ...) When a call is made to find_package() <#command:find_package> or FetchContent_MakeAvailable() <# command:fetchcontent_makeavailable>, the call may be forwarded to a dependency provider which then has the opportunity to fulfill the request. If the request is for one of the specified when the provider was set, CMake calls the provider's with a set of method-specific arguments. If the provider does not fulfill the request, or if the provider doesn't support the request's method, or no provider is set, the built-in find_package() <#command:find_package> or FetchContent_MakeAvailable() <# command:fetchcontent_makeavailable> implementation is used to fulfill the request in the usual way. One or more of the following values can be specified for the when setting the provider: FIND_PACKAGE The provider command accepts find_package() <# command:find_package> requests. FETCHCONTENT_MAKEAVAILABLE_SERIAL The provider command accepts FetchContent_MakeAvailable() <#command:fetchcontent_makeavailable> requests. It expects each dependency to be fed to the provider command one 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 already set when cmake_language(SET_DEPENDENCY_PROVIDER) is called, the new provider replaces the previously set one. The specified must already exist when cmake_language(SET_DEPENDENCY_PROVIDER) is called. As a special case, providing an empty string for the and no will discard any previously set provider. The dependency provider can only be set while processing one of the files specified by the CMAKE_PROJECT_TOP_LEVEL_INCLUDES <# variable:CMAKE_PROJECT_TOP_LEVEL_INCLUDES> variable. Thus, dependency providers can only be set as part of the first call to project() <#command:project>. Calling cmake_language(SET_DEPENDENCY_PROVIDER) outside of that context will result in an error. Added in version 3.30: The PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE <# prop_gbl:PROPAGATE_TOP_LEVEL_INCLUDES_TO_TRY_COMPILE> global property can be set if the dependency provider also wants to be enabled in whole-project calls to try_compile() <# command: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 can list in their CMAKE_PROJECT_TOP_LEVEL_INCLUDES <# variable:CMAKE_PROJECT_TOP_LEVEL_INCLUDES> variable, but the use of such a file should always be the user's choice. Provider commands Providers define a single to accept requests. The name of the command should be specific to that provider, not something overly generic that another provider might also use. This enables users to compose different providers in their own custom provider. The recommended form is xxx_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( [...]) 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 a function. This ensures it does not introduce a new variable scope. The arguments CMake passes to the dependency provider depend on the type of request. The first argument is always the method, and it will only ever be one of the that was specified when setting the provider. FIND_PACKAGE The will be everything passed to the find_package() <#command:find_package> call that requested the dependency. The first of these will therefore always be the name of the dependency. Dependency names are case-sensitive for this method because find_package() <#command:find_package> treats them case-sensitively too. If the provider command fulfills the request, it must set the same variable that find_package() <#command:find_package> expects to be set. For a dependency named depName, the provider must set depName_FOUND to true if it fulfilled the request. If the provider returns without setting this variable, CMake will assume the request was not fulfilled and will fall back to the built-in implementation. If the provider needs to call the built-in find_package() <# command:find_package> implementation as part of its processing, it can do so by including the BYPASS_PROVIDER keyword as one of the arguments. FETCHCONTENT_MAKEAVAILABLE_SERIAL The will be everything passed to the FetchContent_Declare() <#command:fetchcontent_declare> call that corresponds to the requested dependency, with the following exceptions: o If SOURCE_DIR or BINARY_DIR were not part of the original declared arguments, they will be added with their default values. o If FETCHCONTENT_TRY_FIND_PACKAGE_MODE <# variable:FETCHCONTENT_TRY_FIND_PACKAGE_MODE> is set to NEVER, any FIND_PACKAGE_ARGS will be omitted. o The OVERRIDE_FIND_PACKAGE keyword is always omitted. The first of the will always be the name of the dependency. Dependency names are case-insensitive for this method because FetchContent <#module:FetchContent> also treats them case-insensitively. If the provider fulfills the request, it should call FetchContent_SetPopulated() <# command:fetchcontent_setpopulated>, passing the name of the dependency as the first argument. The SOURCE_DIR and BINARY_DIR arguments to that command should only be given if the provider makes the dependency's source and build directories available in exactly the same way as the built-in FetchContent_MakeAvailable() <# command:fetchcontent_makeavailable> command. If the provider returns without calling FetchContent_SetPopulated() <#command:fetchcontent_setpopulated> for the named dependency, CMake will assume the request was not fulfilled and will fall back to the built-in implementation. Note that empty arguments may be significant for this method (e.g. an empty string following a GIT_SUBMODULES keyword). Therefore, if forwarding these arguments on to another command, extra care must be taken to avoid such arguments being silently dropped. If FETCHCONTENT_SOURCE_DIR_ is set, then the dependency provider will never see requests for the dependency for this method. When the user sets such a variable, they are explicitly overriding where to get that dependency from and are taking on the responsibility that their overriding version meets any requirements for that dependency and is compatible with whatever else in the project uses it. Depending on the value of FETCHCONTENT_TRY_FIND_PACKAGE_MODE <# variable:FETCHCONTENT_TRY_FIND_PACKAGE_MODE> and whether the OVERRIDE_FIND_PACKAGE option was given to FetchContent_Declare() <#command:fetchcontent_declare>, having FETCHCONTENT_SOURCE_DIR_ set may also prevent the dependency provider from seeing requests for a find_package(depName) call too. Provider Examples This first example only intercepts find_package() <# command:find_package> calls. The provider command runs an external tool which copies the relevant artifacts into 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() <#command:fetchcontent_makeavailable> calls would not go through the provider. mycomp_provider.cmake # Always ensure we have the policy settings this provider expects cmake_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 it list(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, but only handles one specific dependency. It enforces providing Google Test using FetchContent <#module:FetchContent>, but leaves all other dependencies to be fulfilled by CMake's built-in implementation. It accepts a few different names, which demonstrates one way of working around projects that hard-code an unusual or undesirable way of adding this particular dependency to the build. The example also demonstrates how to use the list() <#command:list> command to preserve variables that may be overwritten by a call to FetchContent_MakeAvailable() <# command:fetchcontent_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 thing include(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 a find_package() <#command:find_package> call. It forces all such calls to have the QUIET keyword. It uses the BYPASS_PROVIDER keyword to prevent calling 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 Added in version 3.25. cmake_language(GET_MESSAGE_LOG_LEVEL ) Writes the current message() <#command:message> logging level into the given . See message() <#command:message> for the possible logging levels. The current message logging level can be set either using the --log-level <#cmdoption-cmake-log-level> command line option of the cmake(1) <#manual:cmake(1)> program or using the CMAKE_MESSAGE_LOG_LEVEL <#variable:CMAKE_MESSAGE_LOG_LEVEL> variable. If both the command line option and the variable are set, the command line option takes precedence. If neither are set, the default logging level is returned. Terminating Scripts Added in version 3.29. cmake_language(EXIT ) Terminate the current cmake -P <#cmdoption-cmake-P> script and exit with . This command works only in script mode <#script-processing- mode>. If used outside of that context, it will cause a fatal error. The should be non-negative. If is negative, then the behavior is unspecified (e.g., on Windows the error code -1 becomes 0xffffffff, and on Linux it becomes 255). Exit codes above 255 may not be supported by the underlying shell or platform, and some shells may interpret values above 125 specially. Therefore, it is advisable to only specify an in the range 0 to 125. Trace Control Added in version 4.2. cmake_language(TRACE ON [EXPAND]) cmake_language(TRACE OFF) The TRACE subcommand controls runtime tracing of executed CMake commands and macros within the current process. When enabled, trace output is written in the same format as if CMake had been started with the cmake --trace <#cmdoption-cmake-trace> or cmake --trace-expand <#cmdoption-cmake-trace-expand> command line options. Tracing scopes are nestable. Multiple TRACE ON calls may be active at the same time, and each TRACE OFF deactivates one nesting level. If CMake is run with cmake --trace <#cmdoption-cmake-trace> or cmake --trace-expand <#cmdoption-cmake-trace-expand>, those options override and force tracing globally, regardless of cmake_language(TRACE OFF) calls. In such cases, the command may still be invoked but has no effect on the trace state. cmake_minimum_required Require a minimum version of cmake. cmake_minimum_required(VERSION [...] [FATAL_ERROR]) Added in version 3.12: The optional version behavior; ignored in older CMake. Sets the minimum required version of cmake for a project. Also updates the policy settings as explained below. and the optional are each CMake versions of the form major.minor[.patch[.tweak]], and the ... is literal. If the running version of CMake is lower than the required version it will stop processing the project and report an error. The optional version, if specified, must be at least the version and sets the Policy Version. If the running version of CMake is older than 3.12, the extra ... dots will be seen as version component separators, resulting in the ... part being ignored and preserving the pre-3.12 behavior of basing policies on . This command will set the value of the CMAKE_MINIMUM_REQUIRED_VERSION <#variable:CMAKE_MINIMUM_REQUIRED_VERSION> variable to . The FATAL_ERROR option is accepted but ignored by CMake 2.6 and higher. It should be specified so CMake versions 2.4 and lower fail with an error instead of just a warning. Note: Call the cmake_minimum_required() command at the beginning of the top-level CMakeLists.txt file even before calling the project() <# command:project> command. It is important to establish version and policy settings before invoking other commands whose behavior they may affect. See also policy CMP0000 <#policy:CMP0000>. Calling cmake_minimum_required() inside a function() <# command:function> limits some effects to the function scope when invoked. For example, the CMAKE_MINIMUM_REQUIRED_VERSION <# variable:CMAKE_MINIMUM_REQUIRED_VERSION> variable won't be set in the calling scope. Functions do not introduce their own policy scope though, so policy settings of the caller will be affected (see below). Due to this mix of things that do and do not affect the calling scope, calling cmake_minimum_required() inside a function is generally discouraged. Policy Version cmake_minimum_required(VERSION [...]) implicitly invokes cmake_policy(VERSION [...]) This specifies that the current CMake code is written for the given range of CMake versions, [...]. It sets the "policy version" to: o the range's version, if specified, or to o the version, or to o the value of the CMAKE_POLICY_VERSION_MINIMUM <# variable:CMAKE_POLICY_VERSION_MINIMUM> variable if it is higher than the other two versions. The policy version effectively requests behavior preferred as of a given CMake version and tells newer CMake versions to warn about their new policies. All policies known to the running version of CMake and introduced in the policy version or earlier will be set to use NEW behavior. All policies introduced in later versions will be unset (unless the CMAKE_POLICY_DEFAULT_CMP <# variable:CMAKE_POLICY_DEFAULT_CMP> variable sets a default). Note: ... does not signify that later CMake versions are forbidden. It merely specifies the highest CMake version for which the project or module has been actively updated and maintained. Changed in version 4.0: Compatibility with versions of CMake older than 3.5 is removed. Calls to cmake_minimum_required(VERSION) or cmake_policy(VERSION) <#version> that do not specify at least 3.5 as their policy version (optionally via ...) will produce an error in CMake 4.0 and above. Changed in version 3.31: Compatibility with versions of CMake older than 3.10 is deprecated. Calls to cmake_minimum_required(VERSION) or cmake_policy(VERSION) <#version> that do not specify at least 3.10 as their policy version (optionally via ...) will produce a deprecation warning in CMake 3.31 and above. Changed in version 3.27: Compatibility with versions of CMake older than 3.5 is deprecated. Calls to cmake_minimum_required(VERSION) or cmake_policy(VERSION) <#version> that do not specify at least 3.5 as their policy version (optionally via ...) will produce a deprecation warning in CMake 3.27 and above. Changed in version 3.19: Compatibility with versions of CMake older than 2.8.12 is deprecated. Calls to cmake_minimum_required(VERSION) or cmake_policy(VERSION) <#version> that do not specify at least 2.8.12 as their policy version (optionally via ...) will produce a deprecation warning in CMake 3.19 and above. See Also o cmake_policy() <#command:cmake_policy> cmake_parse_arguments Parse function or macro arguments. cmake_parse_arguments( ...) cmake_parse_arguments(PARSE_ARGV ) cmake_parse_arguments(PARSE_ARGN ) Added in version 3.5: This command is implemented natively. Previously, it has been defined in the module CMakeParseArguments <# module:CMakeParseArguments>. This command is for use in macros or functions. It processes the arguments given to that macro or function, and defines a set of variables which hold the values of the respective options. The first signature reads arguments passed in the .... This may be used in either a macro() <#command:macro> or a function() <# command:function>. Added in version 3.7: The PARSE_ARGV signature is only for use in a function() <#command:function> body. In this case, the arguments that are parsed come from the ARGV# variables of the calling function. The parsing starts with the -th argument, where is an unsigned integer. This allows for the values to have special characters like ; in them. Added in version 4.4: The PARSE_ARGN signature is only for use in a function() <#command:function> body. This starts parsing after the last named argument of the calling function and works exactly like PARSE_ARGV with being the number of parameters in the function definition. The argument contains all options for the respective function or macro. These are keywords that have no value following them, like the OPTIONAL keyword of the install() <#command:install> command. The argument contains all keywords for this function or macro which are followed by one value, like the DESTINATION keyword of the install() <#command:install> command. The argument contains all keywords for this function or macro which can be followed by more than one value, like the TARGETS or FILES keywords of the install() <#command:install> command. Changed in version 3.5: All keywords must be unique. Each keyword can only be specified once in any of the , , or . A warning will be emitted if uniqueness is violated. When done, cmake_parse_arguments will consider for each of the keywords listed in , , and , a variable composed of the given followed by "_" and the name of the respective keyword. For and , these variables will then hold the respective value(s) from the argument list, or be undefined if the associated keyword was not given (policy CMP0174 <#policy:CMP0174> can also affect the behavior for ). For the keywords, these variables will always be defined, and they will be set to TRUE if the keyword is present, or FALSE if it is not. All remaining arguments are collected in a variable _UNPARSED_ARGUMENTS that will be undefined if all arguments were recognized. This can be checked afterwards to see whether your macro or function was called with unrecognized parameters. Added in version 3.15: and that were given no values at all are collected in a variable _KEYWORDS_MISSING_VALUES that will be undefined if all keywords received values. This can be checked to see if there were keywords without any values given. Changed in version 3.31: If a is followed by an empty string as its value, policy CMP0174 <#policy:CMP0174> controls whether a corresponding _ variable is defined or not. Choose a carefully to avoid clashing with existing variable names. When used inside a function, it is usually suitable to use the prefix arg. There is a very strong convention that all keywords are fully uppercase, so this prefix results in variables of the form arg_SOME_KEYWORD. This makes the code more readable, and it minimizes the chance of clashing with cache variables, which also have a strong convention of being all uppercase. function(my_install) set(options OPTIONAL FAST) set(oneValueArgs DESTINATION RENAME) set(multiValueArgs TARGETS CONFIGURATIONS) cmake_parse_arguments(PARSE_ARGV 0 arg "${options}" "${oneValueArgs}" "${multiValueArgs}" ) # The above will set or unset variables with the following names: # arg_OPTIONAL # arg_FAST # arg_DESTINATION # arg_RENAME # arg_TARGETS # arg_CONFIGURATIONS # # The following will also be set or unset: # arg_UNPARSED_ARGUMENTS # arg_KEYWORDS_MISSING_VALUES When used inside a macro, arg might not be a suitable prefix because the code will affect the calling scope. If another macro also called in the same scope were to use arg in its own call to cmake_parse_arguments(), and if there are any common keywords between the two macros, the later call's variables can overwrite or remove those of the earlier macro's call. Therefore, it is advisable to incorporate something unique from the macro name in the , such as arg_lowercase_macro_name. macro(my_install) set(options OPTIONAL FAST) set(oneValueArgs DESTINATION RENAME) set(multiValueArgs TARGETS CONFIGURATIONS) cmake_parse_arguments(arg_my_install "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN} ) # ... endmacro() macro(my_special_install) # NOTE: Has the same keywords as my_install() set(options OPTIONAL FAST) set(oneValueArgs DESTINATION RENAME) set(multiValueArgs TARGETS CONFIGURATIONS) cmake_parse_arguments(arg_my_special_install "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN} ) # ... endmacro() Suppose the above macros are called one after the other, like so: my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS) my_special_install(TARGETS barry DESTINATION sbin RENAME FAST) After these two calls, the following describes the variables that will be set or unset: arg_my_install_OPTIONAL = TRUE arg_my_install_FAST = FALSE # was not present in call to my_install arg_my_install_DESTINATION = "bin" arg_my_install_RENAME # was not present arg_my_install_TARGETS = "foo;bar" arg_my_install_CONFIGURATIONS # was not present arg_my_install_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL" arg_my_install_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS" # value was missing arg_my_special_install_OPTIONAL = FALSE # was not present arg_my_special_install_FAST = TRUE arg_my_special_install_DESTINATION = "sbin" arg_my_special_install_RENAME # value was missing arg_my_special_install_TARGETS = "barry" arg_my_special_install_CONFIGURATIONS # was not present arg_my_special_install_UNPARSED_ARGUMENTS arg_my_special_install_KEYWORDS_MISSING_VALUES = "RENAME" Keywords terminate lists of values. If a keyword is given directly after a , that preceding receives no value and the keyword is added to the _KEYWORDS_MISSING_VALUES variable. In the above example, the call to my_special_install() contains the RENAME keyword immediately followed by the FAST keyword. In this case, FAST terminates processing of the RENAME keyword. arg_my_special_install_FAST is set to TRUE, arg_my_special_install_RENAME is unset, and arg_my_special_install_KEYWORDS_MISSING_VALUES contains the value RENAME. See Also o function() <#command:function> o macro() <#command:macro> cmake_path Added in version 3.20. This command is for the manipulation of paths. Only syntactic aspects of paths are handled, there is no interaction of any kind with any underlying file system. The path may represent a non-existing path or even one that is not allowed to exist on the current file system or platform. For operations that do interact with the filesystem, see the file() <#command:file> command. Note: The cmake_path command handles paths in the format of the build system (i.e. the host platform), not the target system. When cross-compiling, if the path contains elements that are not representable on the host platform (e.g. a drive letter when the host is not Windows), the results will be unpredictable. Synopsis Conventions Path Structure And Terminology Normalization Decomposition cmake_path(GET ROOT_NAME ) cmake_path(GET ROOT_DIRECTORY ) cmake_path(GET ROOT_PATH ) cmake_path(GET FILENAME ) cmake_path(GET EXTENSION [LAST_ONLY] ) cmake_path(GET STEM [LAST_ONLY] ) cmake_path(GET RELATIVE_PART ) cmake_path(GET PARENT_PATH ) Query cmake_path(HAS_ROOT_NAME ) cmake_path(HAS_ROOT_DIRECTORY ) cmake_path(HAS_ROOT_PATH ) cmake_path(HAS_FILENAME ) cmake_path(HAS_EXTENSION ) cmake_path(HAS_STEM ) cmake_path(HAS_RELATIVE_PART ) cmake_path(HAS_PARENT_PATH ) cmake_path(IS_ABSOLUTE ) cmake_path(IS_RELATIVE ) cmake_path(IS_PREFIX [NORMALIZE] ) Comparison cmake_path(COMPARE ) Modification cmake_path(SET [NORMALIZE] ) cmake_path(APPEND [...] [OUTPUT_VARIABLE ]) cmake_path(APPEND_STRING [...] [OUTPUT_VARIABLE ]) cmake_path(REMOVE_FILENAME [OUTPUT_VARIABLE ]) cmake_path(REPLACE_FILENAME [OUTPUT_VARIABLE ]) cmake_path(REMOVE_EXTENSION [LAST_ONLY] [OUTPUT_VARIABLE ]) cmake_path(REPLACE_EXTENSION [LAST_ONLY] [OUTPUT_VARIABLE ]) Generation cmake_path(NORMAL_PATH [OUTPUT_VARIABLE ]) cmake_path(RELATIVE_PATH [BASE_DIRECTORY ] [OUTPUT_VARIABLE ]) cmake_path(ABSOLUTE_PATH [BASE_DIRECTORY ] [NORMALIZE] [OUTPUT_VARIABLE ]) Native Conversion cmake_path(NATIVE_PATH [NORMALIZE] ) cmake_path(CONVERT TO_CMAKE_PATH_LIST [NORMALIZE]) cmake_path(CONVERT TO_NATIVE_PATH_LIST [NORMALIZE]) Hashing cmake_path(HASH ) Conventions The following conventions are used in this command's documentation: Always the name of a variable. For commands that expect a as input, the variable must exist and it is expected to hold a single path. A string literal which may contain a path, path fragment, or multiple paths with a special separator depending on the command. See the description of each command to see how this is interpreted. ... Zero or more string literal arguments. The name of a variable into which the result of a command will be written. Path Structure And Terminology A path has the following structure (all components are optional, with some constraints): root-name root-directory-separator (item-name directory-separator)* filename root-name Identifies the root on a filesystem with multiple roots (such as "C:" or "//myserver"). It is optional. root-directory-separator A directory separator that, if present, indicates that this path is absolute. If it is missing and the first element other than the root-name is an item-name, then the path is relative. item-name A sequence of characters that aren't directory separators. This name may identify a file, a hard link, a symbolic link, or a directory. Two special cases are recognized: o The item name consisting of a single dot character . is a directory name that refers to the current directory. o The item name consisting of two dot characters .. is a directory name that refers to the parent directory. The (...)* pattern shown above is to indicate that there can be zero or more item names, with multiple items separated by a directory-separator. The ()* characters are not part of the path. directory-separator The only recognized directory separator is a forward slash character /. If this character is repeated, it is treated as a single directory separator. In other words, /usr///////lib is the same as /usr/lib. filename A path has a filename if it does not end with a directory-separator. The filename is effectively the last item-name of the path, so it can also be a hard link, symbolic link or a directory. A filename can have an extension. By default, the extension is defined as the sub-string beginning at the left-most period (including the period) and until the end of the filename. In commands that accept a LAST_ONLY keyword, LAST_ONLY changes the interpretation to the sub-string beginning at the right-most period. The following exceptions apply to the above interpretation: o If the first character in the filename is a period, that period is ignored (i.e. a filename like ".profile" is treated as having no extension). o If the filename is either . or .., it has no extension. The stem is the part of the filename before the extension. Some commands refer to a root-path. This is the concatenation of root-name and root-directory-separator, either or both of which can be empty. A relative-part refers to the full path with any root-path removed. Creating A Path Variable While a path can be created with care using an ordinary set() <# command:set> command, it is recommended to use cmake_path(SET) instead, as it automatically converts the path to the required form where required. The cmake_path(APPEND) subcommand may be another suitable alternative where a path needs to be constructed by joining fragments. The following example compares the three methods for constructing the same path: set(path1 "${CMAKE_CURRENT_SOURCE_DIR}/data") cmake_path(SET path2 "${CMAKE_CURRENT_SOURCE_DIR}/data") cmake_path(APPEND path3 "${CMAKE_CURRENT_SOURCE_DIR}" "data") Modification and Generation sub-commands can either store the result in-place, or in a separate variable named after an OUTPUT_VARIABLE keyword. All other sub-commands store the result in a mandatory variable. Note: The cmake_path command can be used directly with variables provided by CMake representing paths (e.g., CMAKE_SOURCE_DIR <# variable:CMAKE_SOURCE_DIR>). However, since the command can modify these variables, and many of them have undefined behavior when modified, they should never be specified as an , and only as the when a separate is specified. See cmake-variables(7) <#manual:cmake-variables(7)> for the list of CMake variables and identifiers reserved by CMake. Normalization Some sub-commands support normalizing a path. The algorithm used to normalize a path is as follows: 1. If the path is empty, stop (the normalized form of an empty path is also an empty path). 2. Replace each directory-separator, which may consist of multiple separators, with a single / (/a///b --> /a/b). 3. Remove each solitary period (.) and any immediately following directory-separator (/a/./b/. --> /a/b). 4. Remove each item-name (other than ..) that is immediately followed by a directory-separator and a .., along with any immediately following directory-separator (/a/b/../c --> a/c). 5. If there is a root-directory, remove any .. and any directory-separators immediately following them. The parent of the root directory is treated as still the root directory (/../a --> /a). 6. If the last item-name is .., remove any trailing directory-separator (../ --> ..). 7. If the path is empty by this stage, add a dot (normal form of ./ is .). Decomposition The following forms of the GET subcommand each retrieve a different component or group of components from a path. See Path Structure And Terminology for the meaning of each path component. cmake_path(GET ROOT_NAME ) cmake_path(GET ROOT_DIRECTORY ) cmake_path(GET ROOT_PATH ) cmake_path(GET FILENAME ) cmake_path(GET EXTENSION [LAST_ONLY] ) cmake_path(GET STEM [LAST_ONLY] ) cmake_path(GET RELATIVE_PART ) cmake_path(GET PARENT_PATH ) If a requested component is not present in the path, an empty string will be stored in . For example, only Windows systems have the concept of a root-name, so when the host machine is non-Windows, the ROOT_NAME subcommand will always return an empty string. For PARENT_PATH, if the HAS_RELATIVE_PART sub-command returns false, the result is a copy of . Note that this implies that a root directory is considered to have a parent, with that parent being itself. Where HAS_RELATIVE_PART returns true, the result will essentially be with one less element. Root examples set(path "c:/a") cmake_path(GET path ROOT_NAME rootName) cmake_path(GET path ROOT_DIRECTORY rootDir) cmake_path(GET path ROOT_PATH rootPath) message("Root name is \"${rootName}\"") message("Root directory is \"${rootDir}\"") message("Root path is \"${rootPath}\"") Root name is "c:" Root directory is "/" Root path is "c:/" Filename examples set(path "/a/b") cmake_path(GET path FILENAME filename) message("First filename is \"${filename}\"") # Trailing slash means filename is empty set(path "/a/b/") cmake_path(GET path FILENAME filename) message("Second filename is \"${filename}\"") First filename is "b" Second filename is "" Extension and stem examples set(path "name.ext1.ext2") cmake_path(GET path EXTENSION fullExt) cmake_path(GET path STEM fullStem) message("Full extension is \"${fullExt}\"") message("Full stem is \"${fullStem}\"") # Effect of LAST_ONLY cmake_path(GET path EXTENSION LAST_ONLY lastExt) cmake_path(GET path STEM LAST_ONLY lastStem) message("Last extension is \"${lastExt}\"") message("Last stem is \"${lastStem}\"") # Special cases set(dotPath "/a/.") set(dotDotPath "/a/..") set(someMorePath "/a/.some.more") cmake_path(GET dotPath EXTENSION dotExt) cmake_path(GET dotPath STEM dotStem) cmake_path(GET dotDotPath EXTENSION dotDotExt) cmake_path(GET dotDotPath STEM dotDotStem) cmake_path(GET someMorePath EXTENSION someMoreExt) cmake_path(GET someMorePath STEM someMoreStem) message("Dot extension is \"${dotExt}\"") message("Dot stem is \"${dotStem}\"") message("Dot-dot extension is \"${dotDotExt}\"") message("Dot-dot stem is \"${dotDotStem}\"") message(".some.more extension is \"${someMoreExt}\"") message(".some.more stem is \"${someMoreStem}\"") Full extension is ".ext1.ext2" Full stem is "name" Last extension is ".ext2" Last stem is "name.ext1" Dot extension is "" Dot stem is "." Dot-dot extension is "" Dot-dot stem is ".." .some.more extension is ".more" .some.more stem is ".some" Relative part examples set(path "c:/a/b") cmake_path(GET path RELATIVE_PART result) message("Relative part is \"${result}\"") set(path "c/d") cmake_path(GET path RELATIVE_PART result) message("Relative part is \"${result}\"") set(path "/") cmake_path(GET path RELATIVE_PART result) message("Relative part is \"${result}\"") Relative part is "a/b" Relative part is "c/d" Relative part is "" Path traversal examples set(path "c:/a/b") cmake_path(GET path PARENT_PATH result) message("Parent path is \"${result}\"") set(path "c:/") cmake_path(GET path PARENT_PATH result) message("Parent path is \"${result}\"") Parent path is "c:/a" Parent path is "c:/" Query Each of the GET subcommands has a corresponding HAS_... subcommand which can be used to discover whether a particular path component is present. See Path Structure And Terminology for the meaning of each path component. cmake_path(HAS_ROOT_NAME ) cmake_path(HAS_ROOT_DIRECTORY ) cmake_path(HAS_ROOT_PATH ) cmake_path(HAS_FILENAME ) cmake_path(HAS_EXTENSION ) cmake_path(HAS_STEM ) cmake_path(HAS_RELATIVE_PART ) cmake_path(HAS_PARENT_PATH ) Each of the above follows the predictable pattern of setting to true if the path has the associated component, or false otherwise. Note the following special cases: o For HAS_ROOT_PATH, a true result will only be returned if at least one of root-name or root-directory is non-empty. o For HAS_PARENT_PATH, the root directory is also considered to have a parent, which will be itself. The result is true except if the path consists of just a filename. cmake_path(IS_ABSOLUTE ) Sets to true if is absolute. An absolute path is a path that unambiguously identifies the location of a file without reference to an additional starting location. On Windows, this means the path must have both a root-name and a root-directory-separator to be considered absolute. On other platforms, just a root-directory-separator is sufficient. Note that this means on Windows, IS_ABSOLUTE can be false while HAS_ROOT_DIRECTORY can be true. cmake_path(IS_RELATIVE ) This will store the opposite of IS_ABSOLUTE in . cmake_path(IS_PREFIX [NORMALIZE] ) Checks if is the prefix of . When the NORMALIZE option is specified, and are normalized before the check. set(path "/a/b/c") cmake_path(IS_PREFIX path "/a/b/c/d" result) # result = true cmake_path(IS_PREFIX path "/a/b" result) # result = false cmake_path(IS_PREFIX path "/x/y/z" result) # result = false set(path "/a/b") cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result) # result = true Comparison cmake_path(COMPARE EQUAL ) cmake_path(COMPARE NOT_EQUAL ) Compares the lexical representations of two paths provided as string literals. No normalization is performed on either path, except multiple consecutive directory separators are effectively collapsed into a single separator. Equality is determined according to the following pseudo-code logic: if(NOT .root_name() STREQUAL .root_name()) return FALSE if(.has_root_directory() XOR .has_root_directory()) return FALSE Return FALSE if a relative portion of is not lexicographically equal to the relative portion of . This comparison is performed path component-wise. If all of the components compare equal, then return TRUE. Note: Unlike most other cmake_path() subcommands, the COMPARE subcommand takes literal strings as input, not the names of variables. Modification cmake_path(SET [NORMALIZE] ) Assigns the path to . If is a native path, it is converted into a CMake-style path with forward-slashes (/). On Windows, the long filename marker is taken into account. When the NORMALIZE option is specified, the path is normalized after the conversion. For example: set(native_path "c:\\a\\b/..\\c") cmake_path(SET path "${native_path}") message("CMake path is \"${path}\"") cmake_path(SET path NORMALIZE "${native_path}") message("Normalized CMake path is \"${path}\"") Output: CMake path is "c:/a/b/../c" Normalized CMake path is "c:/a/c" cmake_path(APPEND [...] [OUTPUT_VARIABLE ]) Appends all the arguments to the using / as the directory-separator. Depending on the , the previous contents of may be discarded. For each argument, the following algorithm (pseudo-code) applies: # is the contents of if(.is_absolute() OR (.has_root_name() AND NOT .root_name() STREQUAL .root_name())) replace with return() endif() if(.has_root_directory()) remove any root-directory and the entire relative path from elseif(.has_filename() OR (NOT .has_root_directory() OR .is_absolute())) append directory-separator to endif() append omitting any root-name to See Creating A Path Variable for details on the output variable. cmake_path(APPEND_STRING [...] [OUTPUT_VARIABLE ]) Appends all the arguments to the without adding any directory-separator. See Creating A Path Variable for details on the output variable. cmake_path(REMOVE_FILENAME [OUTPUT_VARIABLE ]) Removes the filename component (as returned by GET ... FILENAME) from . After removal, any trailing directory-separator is left alone, if present. HAS_FILENAME will return false for the result, whether stored in or . For example: set(path "/a/b") cmake_path(REMOVE_FILENAME path) message("First path is \"${path}\"") # filename is now already empty, the following removes nothing cmake_path(REMOVE_FILENAME path) message("Second path is \"${path}\"") Output: First path is "/a/" Second path is "/a/" See Creating A Path Variable for details on the output variable. cmake_path(REPLACE_FILENAME [OUTPUT_VARIABLE ]) Replaces the filename component from with . If has no filename component (i.e. HAS_FILENAME returns false), the path is unchanged. The operation is equivalent to the following: cmake_path(HAS_FILENAME path has_filename) if(has_filename) cmake_path(REMOVE_FILENAME path) cmake_path(APPEND path "${input}") endif() See Creating A Path Variable for details on the output variable. cmake_path(REMOVE_EXTENSION [LAST_ONLY] [OUTPUT_VARIABLE ]) Removes the extension, if any, from . See Creating A Path Variable for details on the output variable. cmake_path(REPLACE_EXTENSION [LAST_ONLY] [OUTPUT_VARIABLE ]) Replaces the extension with . Its effect is equivalent to the following: cmake_path(REMOVE_EXTENSION path) if(NOT input MATCHES "^\\.") cmake_path(APPEND_STRING path ".") endif() cmake_path(APPEND_STRING path "${input}") See Creating A Path Variable for details on the output variable. Generation cmake_path(NORMAL_PATH [OUTPUT_VARIABLE ]) Normalizes according the steps described in Normalization. See Creating A Path Variable for details on the output variable. cmake_path(RELATIVE_PATH [BASE_DIRECTORY ] [OUTPUT_VARIABLE ]) Modifies to make it relative to the BASE_DIRECTORY argument. If BASE_DIRECTORY is not specified, the default base directory will be CMAKE_CURRENT_SOURCE_DIR <# variable:CMAKE_CURRENT_SOURCE_DIR>. For reference, the algorithm used to compute the relative path is the same as that used by C++ std::filesystem::path::lexically_relative . See Creating A Path Variable for details on the output variable. cmake_path(ABSOLUTE_PATH [BASE_DIRECTORY ] [NORMALIZE] [OUTPUT_VARIABLE ]) If is a relative path (IS_RELATIVE is true), it is evaluated relative to the given base directory specified by BASE_DIRECTORY option. If BASE_DIRECTORY is not specified, the default base directory will be CMAKE_CURRENT_SOURCE_DIR <# variable:CMAKE_CURRENT_SOURCE_DIR>. When the NORMALIZE option is specified, the path is normalized after the path computation. Because cmake_path() does not access the filesystem, symbolic links are not resolved and any leading tilde is not expanded. To compute a real path with symbolic links resolved and leading tildes expanded, use the file(REAL_PATH) <#real-path> command instead. See Creating A Path Variable for details on the output variable. Native Conversion For commands in this section, native refers to the host platform, not the target platform when cross-compiling. cmake_path(NATIVE_PATH [NORMALIZE] ) Converts a CMake-style into a native path with platform-specific slashes (\ on Windows hosts and / elsewhere). When the NORMALIZE option is specified, the path is normalized before the conversion. See Creating A Path Variable for details on the output variable. cmake_path(CONVERT TO_CMAKE_PATH_LIST [NORMALIZE]) Converts a native path into a CMake-style path with forward slashes (/). On Windows hosts, the long filename marker is taken into account. The input can be a single path or a system search path like $ENV{PATH}. A search path will be converted to a semicolon-separated list <#cmake-language-lists> (on non-Windows platforms, this essentially means : separators are replaced with ;). When the NORMALIZE option is specified, the path is normalized before the conversion. See Creating A Path Variable for details on the output variable. Note: Unlike most other cmake_path() subcommands, the CONVERT subcommand takes a literal string as input, not the name of a variable. cmake_path(CONVERT TO_NATIVE_PATH_LIST [NORMALIZE]) Converts a CMake-style path into a native path with platform-specific slashes (\ on Windows hosts and / elsewhere). The input can be a single path or a semicolon-separated list <# cmake-language-lists>. A list will be converted into a native search path (;-separated on Windows, :-separated on other platforms). When the NORMALIZE option is specified, the path is normalized before the conversion. See Creating A Path Variable for details on the output variable. Note: Unlike most other cmake_path() subcommands, the CONVERT subcommand takes a literal string as input, not the name of a variable. For example: set(paths "/a/b/c" "/x/y/z") cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths) message("Native path list is \"${native_paths}\"") Output on Windows: Native path list is "\a\b\c;\x\y\z" Output on all other platforms: Native path list is "/a/b/c:/x/y/z" Hashing cmake_path(HASH ) Computes a hash value of such that for two paths p1 and p2 that compare equal (COMPARE ... EQUAL), the hash value of p1 is equal to the hash value of p2. The path is always normalized before the hash is computed. See Creating A Path Variable for details on the output variable. cmake_pkg_config Added in version 3.31. Process pkg-config format package files. Synopsis cmake_pkg_config(EXTRACT [] [...]) cmake_pkg_config(POPULATE [] [...]) cmake_pkg_config(IMPORT [] [...]) Introduction This command generates CMake variables and targets from pkg-config format package files natively, without needing to invoke or even require the presence of a pkg-config implementation. A is either an absolute path to a package file, or a package name to be searched for using the typical pkg-config search patterns. The optional string has the same format and semantics as a pkg-config style version specifier, with the exception that if no comparison operator is specified = is assumed. PkgConfig Targets cmake_pkg_config may recursively generate target-like names in the global scope in order to resolve a package IMPORT or POPULATE command. These names take the form of @foreign_pkgcfg::[_] and are exposed via the INTERFACE_LINK_LIBRARIES <# prop_tgt:INTERFACE_LINK_LIBRARIES> target property of an IMPORT-generated target. It is not possible to modify or address these pkg-config native targets via normal target-based commands. Limited control over their generation is possible via the POPULATE command, but modification should generally be performed inside the corresponding package file, not downstream in CMake. Pkg-config targets are reused across commands. Once a given package name has been resolved via POPULATE or IMPORT (but not EXTRACT), all future requests for the corresponding package name by those commands will resolve to the previously generated pkg-config target. EXTRACT always performs the complete package name lookup in order to allow searches for multiple installations of the same package in custom dependency management schemes. Common Options There are multiple signatures for this command, and some of the options are common between them. They are: EXACT / QUIET / REQUIRED The EXACT option requests that the version string be matched exactly (including empty string, if no version is provided), overriding the typical pkg-config version comparison algorithm. This will ignore any comparison operator attached to the version string. The QUIET option disables informational messages, including those indicating that the package cannot be found if it is not REQUIRED. The REQUIRED option stops processing with an error message if the package cannot be found. STRICTNESS Specify how strictly the contents of the package files will be verified during parsing and resolution. An invalid file, under the provided strictness mode, will cause the command to fail. Possible modes are: o STRICT: Closely mirrors the behavior of the original FDO pkg-config. Variables and keywords must be unique. Variables must be defined before they are used. The Name, Description, and Version keywords must be present. The overall structure of the file must be valid and parsable. o PERMISSIVE: Closely mirrors the behavior of the pkgconf implementation. Duplicate variables are overridden. Duplicate keywords are appended. Undefined variables resolve to empty strings. The Name, Description, and Version keywords must be present. The overall structure of the file must be valid and parsable. o BEST_EFFORT: Same behavior as PERMISSIVE with regards to duplicate or uninitialized variables and keywords, but will not fail under any conditions. Package files which require BEST_EFFORT will fail validation under all other major implementations and should be fixed. The default strictness is PERMISSIVE. ENV_MODE Specifies which environment variables will be queried when running a given command. Possible modes are: o FDO: Queries only the original set of PKG_CONFIG_* environment variables used by the freedesktop.org pkg-config implementation. o PKGCONF: Queries the more extensive set of environment variables used by the pkgconf implementation. o IGNORE: Ignores the presence, absence, and value of environment variables entirely. In all cases an environment variable would be queried its treated as defined, but with a value of empty string for the purpose of the operation. This does not modify the current environment. For boolean environment variables, such as PKG_CONFIG_ALLOW_*, this means they are evaluated as truthy. PKG_CONFIG_SYSROOT_PATH is a minor exception. When ENV_MODE IGNORE is used, no root path prepending will occur by default and pc_sysrootdir remains defaulted to /. Target-generating subcommands always ignore flag-filtering environment variables. The default environment mode is PKGCONF. PC_LIBDIR ... Overrides the default search location for package files; also used to derive the pc_path package variable. When this option is not provided, the default library directory is the first available of the following values: 1. CMAKE_PKG_CONFIG_PC_LIB_DIRS 2. The PKG_CONFIG_LIBDIR environment variable 3. The output of pkg-config --variable pc_path pkg-config 4. A platform-dependent default value PC_PATH ... Overrides the supplemental package file directories which will be prepended to the search path; also used to derive the pc_path package variable. When this option is not provided, the default paths are the first available of the following values: 1. CMAKE_PKG_CONFIG_PC_PATH 2. The PKG_CONFIG_PATH environment variable 3. Empty list DISABLE_UNINSTALLED Overrides the search behavior for "uninstalled" package files. These are package files with an "-uninstalled" suffix which describe packages integrated directly from a build tree. Normally such package files have higher priority than "installed" packages. When DISABLE_UNINSTALLED is true, searching for "uninstalled" packages is disabled. When this option is not provided, the default search behavior is determined by the first available of the following values: 1. CMAKE_PKG_CONFIG_DISABLE_UNINSTALLED 2. If the PKG_CONFIG_DISABLE_UNINSTALLED environment variable is defined the search is disabled, otherwise it is enabled. PC_SYSROOT_DIR Overrides the root path which will be prepended to paths specified by -I compile flags and -L library search locations; also used to derive the pc_sysrootdir package variable. When this option is not provided, the default root path is provided by the first available of the following values: 1. CMAKE_PKG_CONFIG_SYSROOT_DIR 2. The PKG_CONFIG_SYSROOT_DIR environment variable 3. If no root path is available, nothing will be prepended to include or library directory paths and pc_sysrootdir will be set to / TOP_BUILD_DIR Overrides the top build directory path used to derive the pc_top_builddir package variable. When this option is not provided, the default top build directory path is the first available of the following values: 1. CMAKE_PKG_CONFIG_TOP_BUILD_DIR 2. The PKG_CONFIG_TOP_BUILD_DIR environment variable 3. If no top build directory path is available, the pc_top_builddir package variable is not set PREFIX Specifying a prefix creates an independent collection of pkg-config targets separate from previously populated targets. This enables multiple version of a given package to co-exist, for example packages from different sysroots. The default prefix is an empty string. BIND_PC_REQUIRES <=>... A list of = pairs, the name is a package name as it appears in the Requires list of a pkg-config file and the target is a CMake-native target name (not a pkg-config target). When a given package name appears in the Requires list of a package, it will be fulfilled with the associated CMake target. This behavior applies to all dependencies in the pkg-config graph that have not been previously populated. Signatures cmake_pkg_config(EXTRACT [] [...]) Added in version 3.31. Extract the contents of the package into variables. cmake_pkg_config(EXTRACT [] [REQUIRED] [EXACT] [QUIET] [SYSTEM_INCLUDE_DIRS ...] [SYSTEM_LIBRARY_DIRS ...] [ALLOW_SYSTEM_INCLUDES ] [ALLOW_SYSTEM_LIBS ] [STRICTNESS ] [ENV_MODE ] [PC_LIBDIR ...] [PC_PATH ...] [DISABLE_UNINSTALLED ] [PC_SYSROOT_DIR ] [TOP_BUILD_DIR ]) The following variables will be populated from the contents of package file: +---------------------------------+--------+-------------------------+ |Variable | Type | Definition | +---------------------------------+--------+-------------------------+ |CMAKE_PKG_CONFIG_NAME | String | Value of the Name | | | | keyword | +---------------------------------+--------+-------------------------+ |CMAKE_PKG_CONFIG_DESCRIPTION | String | Value of the | | | | Description keyword | +---------------------------------+--------+-------------------------+ |CMAKE_PKG_CONFIG_VERSION | String | Value of the Version | | | | keyword | +---------------------------------+--------+-------------------------+ |CMAKE_PKG_CONFIG_PROVIDES | List | Value of the Provides | | | | keyword | +---------------------------------+--------+-------------------------+ |CMAKE_PKG_CONFIG_REQUIRES | List | Value of the Requires | | | | keyword | +---------------------------------+--------+-------------------------+ |CMAKE_PKG_CONFIG_CONFLICTS | List | Value of the Conflicts | | | | keyword | +---------------------------------+--------+-------------------------+ |CMAKE_PKG_CONFIG_CFLAGS | String | Value of the CFlags / | | | | Cflags keyword | +---------------------------------+--------+-------------------------+ |CMAKE_PKG_CONFIG_INCLUDES | List | All -I prefixed flags | | | | from | | | | CMAKE_PKG_CONFIG_CFLAGS | +---------------------------------+--------+-------------------------+ |CMAKE_PKG_CONFIG_COMPILE_OPTIONS | List | All flags not prefixed | | | | with -I from | | | | CMAKE_PKG_CONFIG_CFLAGS | +---------------------------------+--------+-------------------------+ |CMAKE_PKG_CONFIG_LIBS | String | Value of the Libs | | | | keyword | +---------------------------------+--------+-------------------------+ |CMAKE_PKG_CONFIG_LIBDIRS | List | All -L prefixed flags | | | | from | | | | CMAKE_PKG_CONFIG_LIBS | +---------------------------------+--------+-------------------------+ |CMAKE_PKG_CONFIG_LIBNAMES | List | All -l prefixed flags | | | | from | | | | CMAKE_PKG_CONFIG_LIBS | +---------------------------------+--------+-------------------------+ |CMAKE_PKG_CONFIG_LINK_OPTIONS | List | All flags not prefixed | | | | with -L or -l from | | | | CMAKE_PKG_CONFIG_LIBS | +---------------------------------+--------+-------------------------+ |CMAKE_PKG_CONFIG_*_PRIVATE | * | CFLAGS / LIBS / | | | | REQUIRES and derived, | | | | but in their .private | | | | suffix forms | +---------------------------------+--------+-------------------------+ SYSTEM_INCLUDE_DIRS Overrides the "system" directories for the purpose of flag mangling include directories in CMAKE_PKG_CONFIG_CFLAGS and derived variables. When this option is not provided, the default directories are provided by the first available of the following values: 1. CMAKE_PKG_CONFIG_SYS_INCLUDE_DIRS 2. The PKG_CONFIG_SYSTEM_INCLUDE_PATH environment variable 3. The output of pkgconf --variable pc_system_includedirs pkg-config 4. A platform-dependent default value Additionally, when the ENV_MODE is PKGCONF the CMAKE_PKG_CONFIG_PKGCONF_INCLUDES variable will be concatenated to the list if available. If it is not available, the following environment variables will be queried and concatenated: o CPATH o C_INCLUDE_PATH o CPLUS_INCLUDE_PATH o OBJC_INCLUDE_PATH o INCLUDE (Windows Only) SYSTEM_LIBRARY_DIRS Overrides the "system" directories for the purpose of flag mangling library directories in CMAKE_PKG_CONFIG_LIBS and derived variables. When this option is not provided, the default directories are provided by the first available of the following values: 1. CMAKE_PKG_CONFIG_SYS_LIB_DIRS 2. The PKG_CONFIG_SYSTEM_LIBRARY_PATH environment variable 3. The output of pkgconf --variable pc_system_libdirs pkg-config 4. A platform-dependent default value Additionally, when the ENV_MODE is PKGCONF the CMAKE_PKG_CONFIG_PKGCONF_LIB_DIRS variable will be concatenated to the list if available. If it is not available, the LIBRARY_PATH environment variable will be queried and concatenated. ALLOW_SYSTEM_INCLUDES Preserves "system" directories during flag mangling of include directories in CMAKE_PKG_CONFIG_CFLAGS and derived variables. When this option is not provided, the default value is determined by the first available of the following values: 1. CMAKE_PKG_CONFIG_ALLOW_SYS_INCLUDES 2. If the PKG_CONFIG_ALLOW_SYSTEM_CFLAGS environment variable is defined the flags are preserved, otherwise they are filtered during flag mangling. ALLOW_SYSTEM_LIBS Preserves "system" directories during flag mangling of library directories in CMAKE_PKG_CONFIG_LIBS and derived variables. When this option is not provided, the default value is determined by the first available of the following values: 1. CMAKE_PKG_CONFIG_ALLOW_SYS_LIBS 2. If the PKG_CONFIG_ALLOW_SYSTEM_LIBS environment variable is defined the flags are preserved, otherwise they are filtered during flag mangling. cmake_pkg_config(POPULATE [] [...]) Added in version 4.1. Populate a package in the pkg-config target namespace cmake_pkg_config(POPULATE [] [REQUIRED] [EXACT] [QUIET] [PREFIX ] [BIND_PC_REQUIRES <=>...] [STRICTNESS ] [ENV_MODE ] [PC_LIBDIR ...] [PC_PATH ...] [DISABLE_UNINSTALLED ] [PC_SYSROOT_DIR ] [TOP_BUILD_DIR ]) POPULATE enables manual control of resolution of a given package's Requires list without importing onto a native CMake target. Once populated, a package and its dependencies will be used for resolution of all future POPULATE and IMPORT commands. A PKGCONFIG__FOUND variable will be set to indicate whether the package was found. cmake_pkg_config(IMPORT [] [...]) Added in version 4.1. Import a pkg-config target as a CMake IMPORTED <# prop_tgt:IMPORTED> target cmake_pkg_config(IMPORT [] [REQUIRED] [EXACT] [QUIET] [NAME ] [PREFIX ] [BIND_PC_REQUIRES <=>...] [STRICTNESS ] [ENV_MODE ] [PC_LIBDIR ...] [PC_PATH ...] [DISABLE_UNINSTALLED ] [PC_SYSROOT_DIR ] [TOP_BUILD_DIR ]) Creates a native CMake IMPORTED target that can be linked to via target_link_libraries() <#command:target_link_libraries>. This new target is named PkgConfig:: by default. A PKGCONFIG__FOUND variable will be set to indicate whether the package was found. NAME Overrides the name of the created CMake target to PkgConfig::. This does not affect the PKGCONFIG__FOUND variable. cmake_policy Manage CMake Policy settings. See the cmake-policies(7) <# manual:cmake-policies(7)> manual for defined policies. As CMake evolves it is sometimes necessary to change existing behavior in order to fix bugs or improve implementations of existing features. The CMake Policy mechanism is designed to help keep existing projects building as new versions of CMake introduce changes in behavior. Each new policy (behavioral change) is given an identifier of the form CMP where is an integer index. Documentation associated with each policy describes the OLD and NEW behavior and the reason the policy was introduced. Projects may set each policy to select the desired behavior. When CMake needs to know which behavior to use it checks for a setting specified by the project. If no setting is available the OLD behavior is assumed and a warning is produced requesting that the policy be set. Setting Policies by CMake Version The cmake_policy command is used to set policies to OLD or NEW behavior. While setting policies individually is supported, we encourage projects to set policies based on CMake versions: cmake_policy(VERSION [...]) Added in version 3.12: The optional version. and the optional are each CMake versions of the form major.minor[.patch[.tweak]], and the ... is literal. The version must be at least 2.4 and at most the running version of CMake. The version, if specified, must be at least the version but may exceed the running version of CMake. If the running version of CMake is older than 3.12, the extra ... dots will be seen as version component separators, resulting in the ... part being ignored and preserving the pre-3.12 behavior of basing policies on . This specifies that the current CMake code is written for the given range of CMake versions, [...]. It sets the "policy version" to: o the range's version, if specified, or to o the version, or to o the value of the CMAKE_POLICY_VERSION_MINIMUM <# variable:CMAKE_POLICY_VERSION_MINIMUM> variable if it is higher than the other two versions. The policy version effectively requests behavior preferred as of a given CMake version and tells newer CMake versions to warn about their new policies. All policies known to the running version of CMake and introduced in the policy version or earlier will be set to use NEW behavior. All policies introduced in later versions will be unset (unless the CMAKE_POLICY_DEFAULT_CMP <# variable:CMAKE_POLICY_DEFAULT_CMP> variable sets a default). Note: ... does not signify that later CMake versions are forbidden. It merely specifies the highest CMake version for which the project or module has been actively updated and maintained. Note that the cmake_minimum_required(VERSION) <# command:cmake_minimum_required> command implicitly calls cmake_policy(VERSION) too. Changed in version 4.0: Compatibility with versions of CMake older than 3.5 is removed. Calls to cmake_minimum_required(VERSION) <# command:cmake_minimum_required> or cmake_policy(VERSION) that do not specify at least 3.5 as their policy version (optionally via ...) will produce an error in CMake 4.0 and above. Changed in version 3.31: Compatibility with versions of CMake older than 3.10 is deprecated. Calls to cmake_minimum_required(VERSION) <# command:cmake_minimum_required> or cmake_policy(VERSION) that do not specify at least 3.10 as their policy version (optionally via ...) will produce a deprecation warning in CMake 3.31 and above. Changed in version 3.27: Compatibility with versions of CMake older than 3.5 is deprecated. Calls to cmake_minimum_required(VERSION) <# command:cmake_minimum_required> or cmake_policy(VERSION) that do not specify at least 3.5 as their policy version (optionally via ...) will produce a deprecation warning in CMake 3.27 and above. Changed in version 3.19: Compatibility with versions of CMake older than 2.8.12 is deprecated. Calls to cmake_minimum_required(VERSION) <# command:cmake_minimum_required> or cmake_policy(VERSION) that do not specify at least 2.8.12 as their policy version (optionally via ...) will produce a deprecation warning in CMake 3.19 and above. Setting Policies Explicitly cmake_policy(SET CMP NEW|OLD) Tell CMake to use the OLD or NEW behavior for a given policy. Projects depending on the old behavior of a given policy may silence a policy warning by setting the policy state to OLD. Alternatively one may fix the project to work with the new behavior and set the policy state to NEW. Note: The OLD behavior of a policy is deprecated by definition <#cmake- policies-intro> and may be removed in a future version of CMake. Checking Policy Settings cmake_policy(GET CMP ) Check whether a given policy is set to OLD or NEW behavior. The output value will be OLD or NEW if the policy is set, and empty otherwise. CMake Policy Stack CMake keeps policy settings on a stack, so changes made by the cmake_policy command affect only the top of the stack. A new entry on the policy stack is managed automatically for each subdirectory to protect its parents and siblings. CMake also manages a new entry for scripts loaded by include() <#command:include> and find_package() <# command:find_package> commands except when invoked with the NO_POLICY_SCOPE option (see also policy CMP0011 <#policy:CMP0011>). The cmake_policy command provides an interface to manage custom entries on the policy stack: cmake_policy(PUSH) Create a new entry on the policy stack. cmake_policy(POP) Remove the last policy stack entry created with cmake_policy(PUSH). Each PUSH must have a matching POP to erase any changes. This is useful to make temporary changes to policy settings. Calls to the cmake_minimum_required(VERSION) <#command:cmake_minimum_required>, cmake_policy(VERSION), or cmake_policy(SET) commands influence only the current top of the policy stack. Added in version 3.25: The block(SCOPE_FOR POLICIES) <#command:block> command offers a more flexible and more secure way to manage the policy stack. The pop action is done automatically when leaving the block scope, so there is no need to precede each return() <#command:return> with a call to cmake_policy(POP). # stack management with cmake_policy() function(my_func) cmake_policy(PUSH) cmake_policy(SET ...) if () ... cmake_policy(POP) return() elseif() ... cmake_policy(POP) return() endif() ... cmake_policy(POP) endfunction() # stack management with block()/endblock() function(my_func) block(SCOPE_FOR POLICIES) cmake_policy(SET ...) if () ... return() elseif() ... return() endif() ... endblock() endfunction() Commands created by the function() <#command:function> and macro() <# command:macro> commands record policy settings when they are created and use the pre-record policies when they are invoked. If the function or macro implementation sets policies, the changes automatically propagate up through callers until they reach the closest nested policy stack entry. See Also o cmake_minimum_required() <#command:cmake_minimum_required> configure_file Copy a file to another location and modify its contents. configure_file( [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS | FILE_PERMISSIONS ...] [COPYONLY] [ESCAPE_QUOTES] [@ONLY] [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF]]) Copies an file to an file while performing transformations of the input file content. If the input file is modified the build system will re-run CMake to re-configure the file and generate the build system again. The generated file is modified and its timestamp updated on subsequent cmake runs only if its content is changed. Options The options are: Path to the input file. A relative path is treated with respect to the value of CMAKE_CURRENT_SOURCE_DIR <# variable:CMAKE_CURRENT_SOURCE_DIR>. The input path must be a file, not a directory. Path to the output file or directory. A relative path is treated with respect to the value of CMAKE_CURRENT_BINARY_DIR <# variable:CMAKE_CURRENT_BINARY_DIR>. If the path names an existing directory the output file is placed in that directory with the same file name as the input file. If the path contains non-existent directories, they are created. NO_SOURCE_PERMISSIONS Added in version 3.19. Do not transfer the permissions of the input file to the output file. The copied file permissions default to the standard 644 value (-rw-r--r--). USE_SOURCE_PERMISSIONS Added in version 3.20. Transfer the permissions of the input file to the output file. This is already the default behavior if none of the three permissions-related keywords are given (NO_SOURCE_PERMISSIONS, USE_SOURCE_PERMISSIONS or FILE_PERMISSIONS). The USE_SOURCE_PERMISSIONS keyword mostly serves as a way of making the intended behavior clearer at the call site. FILE_PERMISSIONS ... Added in version 3.20. Ignore the input file's permissions and use the specified for the output file instead. COPYONLY Copy the file without replacing any variable references or other content. This option may not be used with NEWLINE_STYLE. ESCAPE_QUOTES Escape any substituted quotes with backslashes (C-style). @ONLY Restrict variable replacement to references of the form @VAR@. This is useful for configuring scripts that use ${VAR} syntax. NEWLINE_STYLE