'\" t .\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "CMAKE-COMMANDS" "7" "April 24, 2024" "3.29.2" "CMake" .SH NAME cmake-commands \- CMake Language Command Reference .SH SCRIPTING COMMANDS .sp These commands are always available. .SS block .sp New in version 3.25. .sp Evaluate a group of commands with a dedicated variable and/or policy scope. .INDENT 0.0 .INDENT 3.5 .sp .EX block([SCOPE_FOR [POLICIES] [VARIABLES] ] [PROPAGATE ...]) endblock() .EE .UNINDENT .UNINDENT .sp All commands between \fBblock()\fP and the matching \fI\%endblock()\fP are recorded without being invoked. Once the \fI\%endblock()\fP is evaluated, the recorded list of commands is invoked inside the requested scopes, then the scopes created by the \fBblock()\fP command are removed. .INDENT 0.0 .TP .B \fBSCOPE_FOR\fP Specify which scopes must be created. .INDENT 7.0 .TP .B \fBPOLICIES\fP Create a new policy scope. This is equivalent to \fI\%cmake_policy(PUSH)\fP with an automatic \fI\%cmake_policy(POP)\fP when leaving the block scope. .TP .B \fBVARIABLES\fP Create a new variable scope. .UNINDENT .sp If \fBSCOPE_FOR\fP is not specified, this is equivalent to: .INDENT 7.0 .INDENT 3.5 .sp .EX block(SCOPE_FOR VARIABLES POLICIES) .EE .UNINDENT .UNINDENT .TP .B \fBPROPAGATE\fP When a variable scope is created by the \fI\%block()\fP command, this option sets or unsets the specified variables in the parent scope. This is equivalent to \fI\%set(PARENT_SCOPE)\fP or \fI\%unset(PARENT_SCOPE)\fP commands. .INDENT 7.0 .INDENT 3.5 .sp .EX set(var1 \(dqINIT1\(dq) set(var2 \(dqINIT2\(dq) block(PROPAGATE var1 var2) set(var1 \(dqVALUE1\(dq) unset(var2) endblock() # Now var1 holds VALUE1, and var2 is unset .EE .UNINDENT .UNINDENT .sp This option is only allowed when a variable scope is created. An error will be raised in the other cases. .UNINDENT .sp When the \fBblock()\fP is inside a \fI\%foreach()\fP or \fI\%while()\fP command, the \fI\%break()\fP and \fI\%continue()\fP commands can be used inside the block. .INDENT 0.0 .INDENT 3.5 .sp .EX while(TRUE) block() ... # the break() command will terminate the while() command break() endblock() endwhile() .EE .UNINDENT .UNINDENT .SS See Also .INDENT 0.0 .IP \(bu 2 \fI\%endblock()\fP .IP \(bu 2 \fI\%return()\fP .IP \(bu 2 \fI\%cmake_policy()\fP .UNINDENT .SS break .sp Break from an enclosing foreach or while loop. .INDENT 0.0 .INDENT 3.5 .sp .EX break() .EE .UNINDENT .UNINDENT .sp Breaks from an enclosing \fI\%foreach()\fP or \fI\%while()\fP loop. .sp See also the \fI\%continue()\fP command. .SS cmake_host_system_information .sp Query various host system information. .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .EX \fI\%Query host system specific information\fP cmake_host_system_information(RESULT QUERY ...) \fI\%Query Windows registry\fP cmake_host_system_information(RESULT QUERY WINDOWS_REGISTRY ...) .EE .UNINDENT .UNINDENT .SS Query host system specific information .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_host_system_information(RESULT QUERY ...) .EE .UNINDENT .UNINDENT .sp Queries system information of the host system on which cmake runs. One or more \fB\fP can be provided to select the information to be queried. The list of queried values is stored in \fB\fP\&. .sp \fB\fP can be one of the following values: .INDENT 0.0 .TP .B \fBNUMBER_OF_LOGICAL_CORES\fP Number of logical cores .TP .B \fBNUMBER_OF_PHYSICAL_CORES\fP Number of physical cores .TP .B \fBHOSTNAME\fP Hostname .TP .B \fBFQDN\fP Fully qualified domain name .TP .B \fBTOTAL_VIRTUAL_MEMORY\fP Total virtual memory in MiB [1] .TP .B \fBAVAILABLE_VIRTUAL_MEMORY\fP Available virtual memory in MiB [1] .TP .B \fBTOTAL_PHYSICAL_MEMORY\fP Total physical memory in MiB [1] .TP .B \fBAVAILABLE_PHYSICAL_MEMORY\fP Available physical memory in MiB [1] .TP .B \fBIS_64BIT\fP New in version 3.10. .sp One if processor is 64Bit .TP .B \fBHAS_FPU\fP New in version 3.10. .sp One if processor has floating point unit .TP .B \fBHAS_MMX\fP New in version 3.10. .sp One if processor supports MMX instructions .TP .B \fBHAS_MMX_PLUS\fP New in version 3.10. .sp One if processor supports Ext. MMX instructions .TP .B \fBHAS_SSE\fP New in version 3.10. .sp One if processor supports SSE instructions .TP .B \fBHAS_SSE2\fP New in version 3.10. .sp One if processor supports SSE2 instructions .TP .B \fBHAS_SSE_FP\fP New in version 3.10. .sp One if processor supports SSE FP instructions .TP .B \fBHAS_SSE_MMX\fP New in version 3.10. .sp One if processor supports SSE MMX instructions .TP .B \fBHAS_AMD_3DNOW\fP New in version 3.10. .sp One if processor supports 3DNow instructions .TP .B \fBHAS_AMD_3DNOW_PLUS\fP New in version 3.10. .sp One if processor supports 3DNow+ instructions .TP .B \fBHAS_IA64\fP New in version 3.10. .sp One if IA64 processor emulating x86 .TP .B \fBHAS_SERIAL_NUMBER\fP New in version 3.10. .sp One if processor has serial number .TP .B \fBPROCESSOR_SERIAL_NUMBER\fP New in version 3.10. .sp Processor serial number .TP .B \fBPROCESSOR_NAME\fP New in version 3.10. .sp Human readable processor name .TP .B \fBPROCESSOR_DESCRIPTION\fP New in version 3.10. .sp Human readable full processor description .TP .B \fBOS_NAME\fP New in version 3.10. .sp See \fI\%CMAKE_HOST_SYSTEM_NAME\fP .TP .B \fBOS_RELEASE\fP New in version 3.10. .sp The OS sub\-type e.g. on Windows \fBProfessional\fP .TP .B \fBOS_VERSION\fP New in version 3.10. .sp The OS build ID .TP .B \fBOS_PLATFORM\fP New in version 3.10. .sp See \fI\%CMAKE_HOST_SYSTEM_PROCESSOR\fP .TP .B \fBMSYSTEM_PREFIX\fP New in version 3.28. .sp Available only on Windows hosts. In a MSYS or MinGW development environment that sets the \fBMSYSTEM\fP environment variable, this is its installation prefix. Otherwise, this is the empty string. .TP .B \fBDISTRIB_INFO\fP New in version 3.22. .sp Read \fB/etc/os\-release\fP file and define the given \fB\fP into a list of read variables .TP .B \fBDISTRIB_\fP New in version 3.22. .sp Get the \fB\fP variable (see \fI\%man 5 os\-release\fP) if it exists in the \fB/etc/os\-release\fP file .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .EX cmake_host_system_information(RESULT PRETTY_NAME QUERY DISTRIB_PRETTY_NAME) message(STATUS \(dq${PRETTY_NAME}\(dq) cmake_host_system_information(RESULT DISTRO QUERY DISTRIB_INFO) foreach(VAR IN LISTS DISTRO) message(STATUS \(dq${VAR}=\(ga${${VAR}}\(ga\(dq) endforeach() .EE .UNINDENT .UNINDENT .sp Output: .INDENT 7.0 .INDENT 3.5 .sp .EX \-\- Ubuntu 20.04.2 LTS \-\- DISTRO_BUG_REPORT_URL=\(gahttps://bugs.launchpad.net/ubuntu/\(ga \-\- DISTRO_HOME_URL=\(gahttps://www.ubuntu.com/\(ga \-\- DISTRO_ID=\(gaubuntu\(ga \-\- DISTRO_ID_LIKE=\(gadebian\(ga \-\- DISTRO_NAME=\(gaUbuntu\(ga \-\- DISTRO_PRETTY_NAME=\(gaUbuntu 20.04.2 LTS\(ga \-\- DISTRO_PRIVACY_POLICY_URL=\(gahttps://www.ubuntu.com/legal/terms\-and\-policies/privacy\-policy\(ga \-\- DISTRO_SUPPORT_URL=\(gahttps://help.ubuntu.com/\(ga \-\- DISTRO_UBUNTU_CODENAME=\(gafocal\(ga \-\- DISTRO_VERSION=\(ga20.04.2 LTS (Focal Fossa)\(ga \-\- DISTRO_VERSION_CODENAME=\(gafocal\(ga \-\- DISTRO_VERSION_ID=\(ga20.04\(ga .EE .UNINDENT .UNINDENT .UNINDENT .sp If \fB/etc/os\-release\fP file is not found, the command tries to gather OS identification via fallback scripts. The fallback script can use \fI\%various distribution\-specific files\fP to collect OS identification data and map it into \fI\%man 5 os\-release\fP variables. .SS Fallback Interface Variables .INDENT 0.0 .TP .B CMAKE_GET_OS_RELEASE_FALLBACK_SCRIPTS In addition to the scripts shipped with CMake, a user may append full paths to his script(s) to the this list. The script filename has the following format: \fBNNN\-.cmake\fP, where \fBNNN\fP is three digits used to apply collected scripts in a specific order. .UNINDENT .INDENT 0.0 .TP .B 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 \fBID\fP variable from the manual becomes \fBCMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID\fP\&. .UNINDENT .INDENT 0.0 .TP .B CMAKE_GET_OS_RELEASE_FALLBACK_RESULT The fallback script ought to store names of all assigned \fBCMAKE_GET_OS_RELEASE_FALLBACK_RESULT_\fP variables in this list. .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .EX # Try to detect some old distribution # See also # \- http://linuxmafia.com/faq/Admin/release\-files.html # if(NOT EXISTS \(dq${CMAKE_SYSROOT}/etc/foobar\-release\(dq) return() endif() # Get the first string only file( STRINGS \(dq${CMAKE_SYSROOT}/etc/foobar\-release\(dq 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 \(dqFoobar distribution release ([0\-9\e.]+) .*\(dq) set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME Foobar) set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME \(dq${CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT}\(dq) 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) .EE .UNINDENT .UNINDENT .SH FOOTNOTES .IP [1] 5 One MiB (mebibyte) is equal to 1024x1024 bytes. .SS Query Windows registry .sp New in version 3.24. .INDENT 0.0 .INDENT 3.5 .sp .EX 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 ]) .EE .UNINDENT .UNINDENT .sp 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 \fB\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Querying registry for any other platforms than \fBWindows\fP, including \fBCYGWIN\fP, will always returns an empty string and sets an error message in the variable specified with sub\-option \fBERROR_VARIABLE\fP\&. .UNINDENT .UNINDENT .sp \fB\fP specify the full path of a subkey on the local computer. The \fB\fP must include a valid root key. Valid root keys for the local computer are: .INDENT 0.0 .IP \(bu 2 \fBHKLM\fP or \fBHKEY_LOCAL_MACHINE\fP .IP \(bu 2 \fBHKCU\fP or \fBHKEY_CURRENT_USER\fP .IP \(bu 2 \fBHKCR\fP or \fBHKEY_CLASSES_ROOT\fP .IP \(bu 2 \fBHKU\fP or \fBHKEY_USERS\fP .IP \(bu 2 \fBHKCC\fP or \fBHKEY_CURRENT_CONFIG\fP .UNINDENT .sp And, optionally, the path to a subkey under the specified root key. The path separator can be the slash or the backslash. \fB\fP is not case sensitive. For example: .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY \(dqHKLM\(dq) cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY \(dqHKLM/SOFTWARE/Kitware\(dq) cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY \(dqHKCU\e\eSOFTWARE\e\eKitware\(dq) .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fBVALUE_NAMES\fP Request the list of value names defined under \fB\fP\&. If a default value is defined, it will be identified with the special name \fB(default)\fP\&. .TP .B \fBSUBKEYS\fP Request the list of subkeys defined under \fB\fP\&. .TP .B \fBVALUE \fP Request the data stored in value named \fB\fP\&. If \fBVALUE\fP is not specified or argument is the special name \fB(default)\fP, the content of the default value, if any, will be returned. .INDENT 7.0 .INDENT 3.5 .sp .EX # query default value for HKLM/SOFTWARE/Kitware key cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY \(dqHKLM/SOFTWARE/Kitware\(dq) # query default value for HKLM/SOFTWARE/Kitware key using special value name cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY \(dqHKLM/SOFTWARE/Kitware\(dq VALUE \(dq(default)\(dq) .EE .UNINDENT .UNINDENT .sp Supported types are: .INDENT 7.0 .IP \(bu 2 \fBREG_SZ\fP\&. .IP \(bu 2 \fBREG_EXPAND_SZ\fP\&. The returned data is expanded. .IP \(bu 2 \fBREG_MULTI_SZ\fP\&. The returned is expressed as a CMake list. See also \fBSEPARATOR\fP sub\-option. .IP \(bu 2 \fBREG_DWORD\fP\&. .IP \(bu 2 \fBREG_QWORD\fP\&. .UNINDENT .sp For all other types, an empty string is returned. .TP .B \fBVIEW\fP Specify which registry views must be queried. When not specified, \fBBOTH\fP view is used. .INDENT 7.0 .TP .B \fB64\fP Query the 64bit registry. On \fB32bit Windows\fP, returns always an empty string. .TP .B \fB32\fP Query the 32bit registry. .TP .B \fB64_32\fP For \fBVALUE\fP sub\-option or default value, query the registry using view \fB64\fP, and if the request failed, query the registry using view \fB32\fP\&. For \fBVALUE_NAMES\fP and \fBSUBKEYS\fP sub\-options, query both views (\fB64\fP and \fB32\fP) and merge the results (sorted and duplicates removed). .TP .B \fB32_64\fP For \fBVALUE\fP sub\-option or default value, query the registry using view \fB32\fP, and if the request failed, query the registry using view \fB64\fP\&. For \fBVALUE_NAMES\fP and \fBSUBKEYS\fP sub\-options, query both views (\fB32\fP and \fB64\fP) and merge the results (sorted and duplicates removed). .TP .B \fBHOST\fP Query the registry matching the architecture of the host: \fB64\fP on \fB64bit Windows\fP and \fB32\fP on \fB32bit Windows\fP\&. .TP .B \fBTARGET\fP Query the registry matching the architecture specified by \fI\%CMAKE_SIZEOF_VOID_P\fP variable. If not defined, fallback to \fBHOST\fP view. .TP .B \fBBOTH\fP Query both views (\fB32\fP and \fB64\fP). The order depends of the following rules: If \fI\%CMAKE_SIZEOF_VOID_P\fP variable is defined. Use the following view depending of the content of this variable: .INDENT 7.0 .IP \(bu 2 \fB8\fP: \fB64_32\fP .IP \(bu 2 \fB4\fP: \fB32_64\fP .UNINDENT .sp If \fI\%CMAKE_SIZEOF_VOID_P\fP variable is not defined, rely on architecture of the host: .INDENT 7.0 .IP \(bu 2 \fB64bit\fP: \fB64_32\fP .IP \(bu 2 \fB32bit\fP: \fB32\fP .UNINDENT .UNINDENT .TP .B \fBSEPARATOR\fP Specify the separator character for \fBREG_MULTI_SZ\fP type. When not specified, the character \fB\e0\fP is used. .TP .B \fBERROR_VARIABLE \fP Returns any error raised during query operation. In case of success, the variable holds an empty string. .UNINDENT .SS cmake_language .sp New in version 3.18. .sp Call meta\-operations on CMake commands. .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_language(\fI\%CALL\fP [...]) cmake_language(\fI\%EVAL\fP CODE ...) cmake_language(\fI\%DEFER\fP ... CALL [...]) cmake_language(\fI\%SET_DEPENDENCY_PROVIDER\fP SUPPORTED_METHODS ...) cmake_language(\fI\%GET_MESSAGE_LOG_LEVEL\fP ) cmake_language(\fI\%EXIT\fP ) .EE .UNINDENT .UNINDENT .SS Introduction .sp This command will call meta\-operations on built\-in CMake commands or those created via the \fI\%macro()\fP or \fI\%function()\fP commands. .sp \fBcmake_language\fP does not introduce a new variable or policy scope. .SS Calling Commands .INDENT 0.0 .TP .B cmake_language(CALL [...]) Calls the named \fB\fP with the given arguments (if any). For example, the code: .INDENT 7.0 .INDENT 3.5 .sp .EX set(message_command \(dqmessage\(dq) cmake_language(CALL ${message_command} STATUS \(dqHello World!\(dq) .EE .UNINDENT .UNINDENT .sp is equivalent to .INDENT 7.0 .INDENT 3.5 .sp .EX message(STATUS \(dqHello World!\(dq) .EE .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To ensure consistency of the code, the following commands are not allowed: .INDENT 0.0 .IP \(bu 2 \fBif\fP / \fBelseif\fP / \fBelse\fP / \fBendif\fP .IP \(bu 2 \fBblock\fP / \fBendblock\fP .IP \(bu 2 \fBwhile\fP / \fBendwhile\fP .IP \(bu 2 \fBforeach\fP / \fBendforeach\fP .IP \(bu 2 \fBfunction\fP / \fBendfunction\fP .IP \(bu 2 \fBmacro\fP / \fBendmacro\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Evaluating Code .INDENT 0.0 .TP .B cmake_language(EVAL CODE ...) Evaluates the \fB...\fP as CMake code. .sp For example, the code: .INDENT 7.0 .INDENT 3.5 .sp .EX set(A TRUE) set(B TRUE) set(C TRUE) set(condition \(dq(A AND B) OR C\(dq) cmake_language(EVAL CODE \(dq if (${condition}) message(STATUS TRUE) else() message(STATUS FALSE) endif()\(dq ) .EE .UNINDENT .UNINDENT .sp is equivalent to .INDENT 7.0 .INDENT 3.5 .sp .EX set(A TRUE) set(B TRUE) set(C TRUE) set(condition \(dq(A AND B) OR C\(dq) file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake \(dq if (${condition}) message(STATUS TRUE) else() message(STATUS FALSE) endif()\(dq ) include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake) .EE .UNINDENT .UNINDENT .UNINDENT .SS Deferring Calls .sp New in version 3.19. .INDENT 0.0 .TP .B cmake_language(DEFER ... CALL [...]) Schedules a call to the named \fB\fP 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\(aqs \fBCMakeLists.txt\fP file, except that they run even after a \fI\%return()\fP call. Variable references in arguments are evaluated at the time the deferred call is executed. .sp The options are: .INDENT 7.0 .TP .B \fBDIRECTORY \fP Schedule the call for the end of the given directory instead of the current directory. The \fB\fP may reference either a source directory or its corresponding binary directory. Relative paths are treated as relative to the current source directory. .sp The given directory must be known to CMake, being either the top\-level directory or one added by \fI\%add_subdirectory()\fP\&. Furthermore, the given directory must not yet be finished processing. This means it can be the current directory or one of its ancestors. .TP .B \fBID \fP Specify an identification for the deferred call. The \fB\fP may not be empty and may not begin with a capital letter \fBA\-Z\fP\&. The \fB\fP may begin with an underscore (\fB_\fP) only if it was generated automatically by an earlier call that used \fBID_VAR\fP to get the id. .TP .B \fBID_VAR \fP Specify a variable in which to store the identification for the deferred call. If \fBID \fP is not given, a new identification will be generated and the generated id will start with an underscore (\fB_\fP). .UNINDENT .sp The currently scheduled list of deferred calls may be retrieved: .INDENT 7.0 .INDENT 3.5 .sp .EX cmake_language(DEFER [DIRECTORY ] GET_CALL_IDS ) .EE .UNINDENT .UNINDENT .sp This will store in \fB\fP a \fI\%semicolon\-separated list\fP 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 \fBDIRECTORY\fP 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. .sp Details of a specific call may be retrieved from its id: .INDENT 7.0 .INDENT 3.5 .sp .EX cmake_language(DEFER [DIRECTORY ] GET_CALL ) .EE .UNINDENT .UNINDENT .sp This will store in \fB\fP a \fI\%semicolon\-separated list\fP in which the first element is the name of the command to be called, and the remaining elements are its unevaluated arguments (any contained \fB;\fP 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 \fBDIRECTORY\fP scope (or the current directory scope if no \fBDIRECTORY\fP option is given), this stores an empty string in the variable. .sp Deferred calls may be canceled by their id: .INDENT 7.0 .INDENT 3.5 .sp .EX cmake_language(DEFER [DIRECTORY ] CANCEL_CALL ...) .EE .UNINDENT .UNINDENT .sp This cancels all deferred calls matching any of the given ids in the specified \fBDIRECTORY\fP scope (or the current directory scope if no \fBDIRECTORY\fP option is given). Unknown ids are silently ignored. .UNINDENT .SS Deferred Call Examples .sp For example, the code: .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_language(DEFER CALL message \(dq${deferred_message}\(dq) cmake_language(DEFER ID_VAR id CALL message \(dqCanceled Message\(dq) cmake_language(DEFER CANCEL_CALL ${id}) message(\(dqImmediate Message\(dq) set(deferred_message \(dqDeferred Message\(dq) .EE .UNINDENT .UNINDENT .sp prints: .INDENT 0.0 .INDENT 3.5 .sp .EX Immediate Message Deferred Message .EE .UNINDENT .UNINDENT .sp The \fBCanceled Message\fP is never printed because its command is canceled. The \fBdeferred_message\fP variable reference is not evaluated until the call site, so it can be set after the deferred call is scheduled. .sp In order to evaluate variable references immediately when scheduling a deferred call, wrap it using \fBcmake_language(EVAL)\fP\&. However, note that arguments will be re\-evaluated in the deferred call, though that can be avoided by using bracket arguments. For example: .INDENT 0.0 .INDENT 3.5 .sp .EX set(deferred_message \(dqDeferred Message 1\(dq) set(re_evaluated [[${deferred_message}]]) cmake_language(EVAL CODE \(dq cmake_language(DEFER CALL message [[${deferred_message}]]) cmake_language(DEFER CALL message \e\(dq${re_evaluated}\e\(dq) \(dq) message(\(dqImmediate Message\(dq) set(deferred_message \(dqDeferred Message 2\(dq) .EE .UNINDENT .UNINDENT .sp also prints: .INDENT 0.0 .INDENT 3.5 .sp .EX Immediate Message Deferred Message 1 Deferred Message 2 .EE .UNINDENT .UNINDENT .SS Dependency Providers .sp New in version 3.24. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 A high\-level introduction to this feature can be found in the \fI\%Using Dependencies Guide\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B cmake_language(SET_DEPENDENCY_PROVIDER SUPPORTED_METHODS ...) When a call is made to \fI\%find_package()\fP or \fI\%FetchContent_MakeAvailable()\fP, 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 \fB\fP specified when the provider was set, CMake calls the provider\(aqs \fB\fP with a set of method\-specific arguments. If the provider does not fulfill the request, or if the provider doesn\(aqt support the request\(aqs method, or no provider is set, the built\-in \fI\%find_package()\fP or \fI\%FetchContent_MakeAvailable()\fP implementation is used to fulfill the request in the usual way. .sp One or more of the following values can be specified for the \fB\fP when setting the provider: .INDENT 7.0 .TP .B \fBFIND_PACKAGE\fP The provider command accepts \fI\%find_package()\fP requests. .TP .B \fBFETCHCONTENT_MAKEAVAILABLE_SERIAL\fP The provider command accepts \fI\%FetchContent_MakeAvailable()\fP requests. It expects each dependency to be fed to the provider command one at a time, not the whole list in one go. .UNINDENT .sp Only one provider can be set at any point in time. If a provider is already set when \fBcmake_language(SET_DEPENDENCY_PROVIDER)\fP is called, the new provider replaces the previously set one. The specified \fB\fP must already exist when \fBcmake_language(SET_DEPENDENCY_PROVIDER)\fP is called. As a special case, providing an empty string for the \fB\fP and no \fB\fP will discard any previously set provider. .sp The dependency provider can only be set while processing one of the files specified by the \fI\%CMAKE_PROJECT_TOP_LEVEL_INCLUDES\fP variable. Thus, dependency providers can only be set as part of the first call to \fI\%project()\fP\&. Calling \fBcmake_language(SET_DEPENDENCY_PROVIDER)\fP outside of that context will result in an error. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The choice of dependency provider should always be under the user\(aqs control. As a convenience, a project may choose to provide a file that users can list in their \fI\%CMAKE_PROJECT_TOP_LEVEL_INCLUDES\fP variable, but the use of such a file should always be the user\(aqs choice. .UNINDENT .UNINDENT .UNINDENT .SS Provider commands .sp Providers define a single \fB\fP 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 \fBxxx_provide_dependency()\fP, where \fBxxx\fP is the provider\-specific part (e.g. \fBvcpkg_provide_dependency()\fP, \fBconan_provide_dependency()\fP, \fBourcompany_provide_dependency()\fP, and so on). .INDENT 0.0 .INDENT 3.5 .sp .EX xxx_provide_dependency( [...]) .EE .UNINDENT .UNINDENT .sp 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. .sp 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 \fB\fP that was specified when setting the provider. .INDENT 0.0 .TP .B \fBFIND_PACKAGE\fP The \fB\fP will be everything passed to the \fI\%find_package()\fP call that requested the dependency. The first of these \fB\fP will therefore always be the name of the dependency. Dependency names are case\-sensitive for this method because \fI\%find_package()\fP treats them case\-sensitively too. .sp If the provider command fulfills the request, it must set the same variable that \fI\%find_package()\fP expects to be set. For a dependency named \fBdepName\fP, the provider must set \fBdepName_FOUND\fP 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. .sp If the provider needs to call the built\-in \fI\%find_package()\fP implementation as part of its processing, it can do so by including the \fBBYPASS_PROVIDER\fP keyword as one of the arguments. .TP .B \fBFETCHCONTENT_MAKEAVAILABLE_SERIAL\fP The \fB\fP will be everything passed to the \fI\%FetchContent_Declare()\fP call that corresponds to the requested dependency, with the following exceptions: .INDENT 7.0 .IP \(bu 2 If \fBSOURCE_DIR\fP or \fBBINARY_DIR\fP were not part of the original declared arguments, they will be added with their default values. .IP \(bu 2 If \fI\%FETCHCONTENT_TRY_FIND_PACKAGE_MODE\fP is set to \fBNEVER\fP, any \fBFIND_PACKAGE_ARGS\fP will be omitted. .IP \(bu 2 The \fBOVERRIDE_FIND_PACKAGE\fP keyword is always omitted. .UNINDENT .sp The first of the \fB\fP will always be the name of the dependency. Dependency names are case\-insensitive for this method because \fI\%FetchContent\fP also treats them case\-insensitively. .sp If the provider fulfills the request, it should call \fI\%FetchContent_SetPopulated()\fP, passing the name of the dependency as the first argument. The \fBSOURCE_DIR\fP and \fBBINARY_DIR\fP arguments to that command should only be given if the provider makes the dependency\(aqs source and build directories available in exactly the same way as the built\-in \fI\%FetchContent_MakeAvailable()\fP command. .sp If the provider returns without calling \fI\%FetchContent_SetPopulated()\fP for the named dependency, CMake will assume the request was not fulfilled and will fall back to the built\-in implementation. .sp Note that empty arguments may be significant for this method (e.g. an empty string following a \fBGIT_SUBMODULES\fP keyword). Therefore, if forwarding these arguments on to another command, extra care must be taken to avoid such arguments being silently dropped. .sp If \fBFETCHCONTENT_SOURCE_DIR_\fP is set, then the dependency provider will never see requests for the \fB\fP 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 \fI\%FETCHCONTENT_TRY_FIND_PACKAGE_MODE\fP and whether the \fBOVERRIDE_FIND_PACKAGE\fP option was given to \fI\%FetchContent_Declare()\fP, having \fBFETCHCONTENT_SOURCE_DIR_\fP set may also prevent the dependency provider from seeing requests for a \fBfind_package(depName)\fP call too. .UNINDENT .SS Provider Examples .sp This first example only intercepts \fI\%find_package()\fP 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. \fI\%FetchContent_MakeAvailable()\fP calls would not go through the provider. .sp mycomp_provider.cmake .INDENT 0.0 .INDENT 3.5 .sp .EX # 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 \(dqThe directory this provider installs packages to\(dq ) # 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 ) .EE .UNINDENT .UNINDENT .sp The user would then typically use the above file like so: .INDENT 0.0 .INDENT 3.5 .sp .EX cmake \-DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=/path/to/mycomp_provider.cmake ... .EE .UNINDENT .UNINDENT .sp The next example demonstrates a provider that accepts both methods, but only handles one specific dependency. It enforces providing Google Test using \fI\%FetchContent\fP, but leaves all other dependencies to be fulfilled by CMake\(aqs 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 \fI\%list()\fP command to preserve variables that may be overwritten by a call to \fI\%FetchContent_MakeAvailable()\fP\&. .sp mycomp_provider.cmake .INDENT 0.0 .INDENT 3.5 .sp .EX 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(\(dq${dep_name}\(dq MATCHES \(dq^(gtest|googletest)$\(dq) # 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(\(dq${method}\(dq STREQUAL \(dqFIND_PACKAGE\(dq) # 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 \(dq${dep_name}\(dq STREQUAL \(dqgoogletest\(dq) # 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 \(dq${googletest_SOURCE_DIR}\(dq BINARY_DIR \(dq${googletest_BINARY_DIR}\(dq ) endif() endif() endmacro() cmake_language( SET_DEPENDENCY_PROVIDER mycomp_provide_dependency SUPPORTED_METHODS FIND_PACKAGE FETCHCONTENT_MAKEAVAILABLE_SERIAL ) .EE .UNINDENT .UNINDENT .sp The final example demonstrates how to modify arguments to a \fI\%find_package()\fP call. It forces all such calls to have the \fBQUIET\fP keyword. It uses the \fBBYPASS_PROVIDER\fP keyword to prevent calling the provider command recursively for the same dependency. .sp mycomp_provider.cmake .INDENT 0.0 .INDENT 3.5 .sp .EX 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 ) .EE .UNINDENT .UNINDENT .SS Getting current message log level .sp New in version 3.25. .INDENT 0.0 .TP .B cmake_language(GET_MESSAGE_LOG_LEVEL ) Writes the current \fI\%message()\fP logging level into the given \fB\fP\&. .sp See \fI\%message()\fP for the possible logging levels. .sp The current message logging level can be set either using the \fI\%\-\-log\-level\fP command line option of the \fI\%cmake(1)\fP program or using the \fI\%CMAKE_MESSAGE_LOG_LEVEL\fP variable. .sp 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. .UNINDENT .SS Terminating Scripts .sp New in version 3.29. .INDENT 0.0 .TP .B cmake_language(EXIT ) Terminate the current \fI\%cmake \-P\fP script and exit with \fB\fP\&. .sp This command works only in \fI\%script mode\fP\&. If used outside of that context, it will cause a fatal error. .sp The \fB\fP should be non\-negative. If \fB\fP is negative, then the behavior is unspecified (e.g., on Windows the error code \-1 becomes \fB0xffffffff\fP, 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 \fB\fP in the range 0 to 125. .UNINDENT .SS cmake_minimum_required .sp Require a minimum version of cmake. .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_minimum_required(VERSION [...] [FATAL_ERROR]) .EE .UNINDENT .UNINDENT .sp New in version 3.12: The optional \fB\fP version. .sp Sets the minimum required version of cmake for a project. Also updates the policy settings as explained below. .sp \fB\fP and the optional \fB\fP are each CMake versions of the form \fBmajor.minor[.patch[.tweak]]\fP, and the \fB\&...\fP is literal. .sp If the running version of CMake is lower than the \fB\fP required version it will stop processing the project and report an error. The optional \fB\fP version, if specified, must be at least the \fB\fP version and affects policy settings as described in \fI\%Policy Settings\fP\&. If the running version of CMake is older than 3.12, the extra \fB\&...\fP dots will be seen as version component separators, resulting in the \fB\&...\fP part being ignored and preserving the pre\-3.12 behavior of basing policies on \fB\fP\&. .sp This command will set the value of the \fI\%CMAKE_MINIMUM_REQUIRED_VERSION\fP variable to \fB\fP\&. .sp The \fBFATAL_ERROR\fP 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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Call the \fBcmake_minimum_required()\fP command at the beginning of the top\-level \fBCMakeLists.txt\fP file even before calling the \fI\%project()\fP command. It is important to establish version and policy settings before invoking other commands whose behavior they may affect. See also policy \fI\%CMP0000\fP\&. .sp Calling \fBcmake_minimum_required()\fP inside a \fI\%function()\fP limits some effects to the function scope when invoked. For example, the \fI\%CMAKE_MINIMUM_REQUIRED_VERSION\fP variable won\(aqt be set in the calling scope. Functions do not introduce their own policy scope though, so policy settings of the caller \fIwill\fP be affected (see below). Due to this mix of things that do and do not affect the calling scope, calling \fBcmake_minimum_required()\fP inside a function is generally discouraged. .UNINDENT .UNINDENT .SS Policy Settings .sp The \fBcmake_minimum_required(VERSION)\fP command implicitly invokes the \fI\%cmake_policy(VERSION)\fP command to specify that the current project code is written for the given range of CMake versions. All policies known to the running version of CMake and introduced in the \fB\fP (or \fB\fP, if specified) version or earlier will be set to use \fBNEW\fP behavior. All policies introduced in later versions will be unset. This effectively requests behavior preferred as of a given CMake version and tells newer CMake versions to warn about their new policies. .sp When a \fB\fP version higher than 2.4 is specified the command implicitly invokes .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_policy(VERSION [...]) .EE .UNINDENT .UNINDENT .sp which sets CMake policies based on the range of versions specified. When a \fB\fP version 2.4 or lower is given the command implicitly invokes .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_policy(VERSION 2.4[...]) .EE .UNINDENT .UNINDENT .sp which enables compatibility features for CMake 2.4 and lower. .sp Changed in version 3.27: Compatibility with versions of CMake older than 3.5 is deprecated. Calls to \fI\%cmake_minimum_required(VERSION)\fP or \fI\%cmake_policy(VERSION)\fP that do not specify at least 3.5 as their policy version (optionally via \fB\&...\fP) will produce a deprecation warning in CMake 3.27 and above. .sp Changed in version 3.19: Compatibility with versions of CMake older than 2.8.12 is deprecated. Calls to \fI\%cmake_minimum_required(VERSION)\fP or \fI\%cmake_policy(VERSION)\fP that do not specify at least 2.8.12 as their policy version (optionally via \fB\&...\fP) will produce a deprecation warning in CMake 3.19 and above. .SS See Also .INDENT 0.0 .IP \(bu 2 \fI\%cmake_policy()\fP .UNINDENT .SS cmake_parse_arguments .sp Parse function or macro arguments. .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_parse_arguments( ...) cmake_parse_arguments(PARSE_ARGV ) .EE .UNINDENT .UNINDENT .sp New in version 3.5: This command is implemented natively. Previously, it has been defined in the module \fI\%CMakeParseArguments\fP\&. .sp 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. .sp The first signature reads processes arguments passed in the \fB...\fP\&. This may be used in either a \fI\%macro()\fP or a \fI\%function()\fP\&. .sp New in version 3.7: The \fBPARSE_ARGV\fP signature is only for use in a \fI\%function()\fP body. In this case the arguments that are parsed come from the \fBARGV#\fP variables of the calling function. The parsing starts with the \fB\fP\-th argument, where \fB\fP is an unsigned integer. This allows for the values to have special characters like \fB;\fP in them. .sp The \fB\fP argument contains all options for the respective macro, i.e. keywords which can be used when calling the macro without any value following, like e.g. the \fBOPTIONAL\fP keyword of the \fI\%install()\fP command. .sp The \fB\fP argument contains all keywords for this macro which are followed by one value, like e.g. \fBDESTINATION\fP keyword of the \fI\%install()\fP command. .sp The \fB\fP argument contains all keywords for this macro which can be followed by more than one value, like e.g. the \fBTARGETS\fP or \fBFILES\fP keywords of the \fI\%install()\fP command. .sp Changed in version 3.5: All keywords shall be unique. I.e. every keyword shall only be specified once in either \fB\fP, \fB\fP or \fB\fP\&. A warning will be emitted if uniqueness is violated. .sp When done, \fBcmake_parse_arguments\fP will consider for each of the keywords listed in \fB\fP, \fB\fP and \fB\fP a variable composed of the given \fB\fP followed by \fB\(dq_\(dq\fP and the name of the respective keyword. These variables will then hold the respective value from the argument list or be undefined if the associated option could not be found. For the \fB\fP keywords, these will always be defined, to \fBTRUE\fP or \fBFALSE\fP, whether the option is in the argument list or not. .sp All remaining arguments are collected in a variable \fB_UNPARSED_ARGUMENTS\fP that will be undefined if all arguments were recognized. This can be checked afterwards to see whether your macro was called with unrecognized parameters. .sp New in version 3.15: \fB\fP and \fB\fP that were given no values at all are collected in a variable \fB_KEYWORDS_MISSING_VALUES\fP that will be undefined if all keywords received values. This can be checked to see if there were keywords without any values given. .sp Consider the following example macro, \fBmy_install()\fP, which takes similar arguments to the real \fI\%install()\fP command: .INDENT 0.0 .INDENT 3.5 .sp .EX macro(my_install) set(options OPTIONAL FAST) set(oneValueArgs DESTINATION RENAME) set(multiValueArgs TARGETS CONFIGURATIONS) cmake_parse_arguments(MY_INSTALL \(dq${options}\(dq \(dq${oneValueArgs}\(dq \(dq${multiValueArgs}\(dq ${ARGN} ) # ... .EE .UNINDENT .UNINDENT .sp Assume \fBmy_install()\fP has been called like this: .INDENT 0.0 .INDENT 3.5 .sp .EX my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS) .EE .UNINDENT .UNINDENT .sp After the \fBcmake_parse_arguments\fP call the macro will have set or undefined the following variables: .INDENT 0.0 .INDENT 3.5 .sp .EX MY_INSTALL_OPTIONAL = TRUE MY_INSTALL_FAST = FALSE # was not used in call to my_install MY_INSTALL_DESTINATION = \(dqbin\(dq MY_INSTALL_RENAME # was not used MY_INSTALL_TARGETS = \(dqfoo;bar\(dq MY_INSTALL_CONFIGURATIONS # was not used MY_INSTALL_UNPARSED_ARGUMENTS = \(dqblub\(dq # nothing expected after \(dqOPTIONAL\(dq MY_INSTALL_KEYWORDS_MISSING_VALUES = \(dqCONFIGURATIONS\(dq # No value for \(dqCONFIGURATIONS\(dq given .EE .UNINDENT .UNINDENT .sp You can then continue and process these variables. .sp Keywords terminate lists of values, e.g. if directly after a \fBone_value_keyword\fP another recognized keyword follows, this is interpreted as the beginning of the new option. E.g. \fBmy_install(TARGETS foo DESTINATION OPTIONAL)\fP would result in \fBMY_INSTALL_DESTINATION\fP set to \fB\(dqOPTIONAL\(dq\fP, but as \fBOPTIONAL\fP is a keyword itself \fBMY_INSTALL_DESTINATION\fP will be empty (but added to \fBMY_INSTALL_KEYWORDS_MISSING_VALUES\fP) and \fBMY_INSTALL_OPTIONAL\fP will therefore be set to \fBTRUE\fP\&. .SS See Also .INDENT 0.0 .IP \(bu 2 \fI\%function()\fP .IP \(bu 2 \fI\%macro()\fP .UNINDENT .SS cmake_path .sp New in version 3.20. .sp 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 \fI\%file()\fP command. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBcmake_path\fP 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. .UNINDENT .UNINDENT .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .EX \fI\%Conventions\fP \fI\%Path Structure And Terminology\fP \fI\%Normalization\fP \fI\%Decomposition\fP cmake_path(\fI\%GET\fP \fI\%ROOT_NAME\fP ) cmake_path(\fI\%GET\fP \fI\%ROOT_DIRECTORY\fP ) cmake_path(\fI\%GET\fP \fI\%ROOT_PATH\fP ) cmake_path(\fI\%GET\fP \fI\%FILENAME\fP ) cmake_path(\fI\%GET\fP \fI\%EXTENSION\fP [LAST_ONLY] ) cmake_path(\fI\%GET\fP \fI\%STEM\fP [LAST_ONLY] ) cmake_path(\fI\%GET\fP \fI\%RELATIVE_PART\fP ) cmake_path(\fI\%GET\fP \fI\%PARENT_PATH\fP ) \fI\%Query\fP cmake_path(\fI\%HAS_ROOT_NAME\fP ) cmake_path(\fI\%HAS_ROOT_DIRECTORY\fP ) cmake_path(\fI\%HAS_ROOT_PATH\fP ) cmake_path(\fI\%HAS_FILENAME\fP ) cmake_path(\fI\%HAS_EXTENSION\fP ) cmake_path(\fI\%HAS_STEM\fP ) cmake_path(\fI\%HAS_RELATIVE_PART\fP ) cmake_path(\fI\%HAS_PARENT_PATH\fP ) cmake_path(\fI\%IS_ABSOLUTE\fP ) cmake_path(\fI\%IS_RELATIVE\fP ) cmake_path(\fI\%IS_PREFIX\fP [NORMALIZE] ) cmake_path(\fI\%COMPARE\fP ) \fI\%Modification\fP cmake_path(\fI\%SET\fP [NORMALIZE] ) cmake_path(\fI\%APPEND\fP [...] [OUTPUT_VARIABLE ]) cmake_path(\fI\%APPEND_STRING\fP [...] [OUTPUT_VARIABLE ]) cmake_path(\fI\%REMOVE_FILENAME\fP [OUTPUT_VARIABLE ]) cmake_path(\fI\%REPLACE_FILENAME\fP [OUTPUT_VARIABLE ]) cmake_path(\fI\%REMOVE_EXTENSION\fP [LAST_ONLY] [OUTPUT_VARIABLE ]) cmake_path(\fI\%REPLACE_EXTENSION\fP [LAST_ONLY] [OUTPUT_VARIABLE ]) \fI\%Generation\fP cmake_path(\fI\%NORMAL_PATH\fP [OUTPUT_VARIABLE ]) cmake_path(\fI\%RELATIVE_PATH\fP [BASE_DIRECTORY ] [OUTPUT_VARIABLE ]) cmake_path(\fI\%ABSOLUTE_PATH\fP [BASE_DIRECTORY ] [NORMALIZE] [OUTPUT_VARIABLE ]) \fI\%Native Conversion\fP cmake_path(\fI\%NATIVE_PATH\fP [NORMALIZE] ) cmake_path(\fI\%CONVERT\fP \fI\%TO_CMAKE_PATH_LIST\fP [NORMALIZE]) cmake_path(\fI\%CONVERT\fP \fI\%TO_NATIVE_PATH_LIST\fP [NORMALIZE]) \fI\%Hashing\fP cmake_path(\fI\%HASH\fP ) .EE .UNINDENT .UNINDENT .SS Conventions .sp The following conventions are used in this command\(aqs documentation: .INDENT 0.0 .TP .B \fB\fP Always the name of a variable. For commands that expect a \fB\fP as input, the variable must exist and it is expected to hold a single path. .TP .B \fB\fP 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. .TP .B \fB...\fP Zero or more string literal arguments. .TP .B \fB\fP The name of a variable into which the result of a command will be written. .UNINDENT .SS Path Structure And Terminology .sp A path has the following structure (all components are optional, with some constraints): .INDENT 0.0 .INDENT 3.5 .sp .EX root\-name root\-directory\-separator (item\-name directory\-separator)* filename .EE .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fBroot\-name\fP Identifies the root on a filesystem with multiple roots (such as \fB\(dqC:\(dq\fP or \fB\(dq//myserver\(dq\fP). It is optional. .TP .B \fBroot\-directory\-separator\fP A directory separator that, if present, indicates that this path is absolute. If it is missing and the first element other than the \fBroot\-name\fP is an \fBitem\-name\fP, then the path is relative. .TP .B \fBitem\-name\fP A sequence of characters that aren\(aqt directory separators. This name may identify a file, a hard link, a symbolic link, or a directory. Two special cases are recognized: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 The item name consisting of a single dot character \fB\&.\fP is a directory name that refers to the current directory. .IP \(bu 2 The item name consisting of two dot characters \fB\&..\fP is a directory name that refers to the parent directory. .UNINDENT .UNINDENT .UNINDENT .sp The \fB(...)*\fP pattern shown above is to indicate that there can be zero or more item names, with multiple items separated by a \fBdirectory\-separator\fP\&. The \fB()*\fP characters are not part of the path. .TP .B \fBdirectory\-separator\fP The only recognized directory separator is a forward slash character \fB/\fP\&. If this character is repeated, it is treated as a single directory separator. In other words, \fB/usr///////lib\fP is the same as \fB/usr/lib\fP\&. .UNINDENT .INDENT 0.0 .TP .B \fBfilename\fP A path has a \fBfilename\fP if it does not end with a \fBdirectory\-separator\fP\&. The \fBfilename\fP is effectively the last \fBitem\-name\fP of the path, so it can also be a hard link, symbolic link or a directory. .sp A \fBfilename\fP can have an \fIextension\fP\&. 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 \fBfilename\fP\&. In commands that accept a \fBLAST_ONLY\fP keyword, \fBLAST_ONLY\fP changes the interpretation to the sub\-string beginning at the right\-most period. .sp The following exceptions apply to the above interpretation: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 If the first character in the \fBfilename\fP is a period, that period is ignored (i.e. a \fBfilename\fP like \fB\(dq.profile\(dq\fP is treated as having no extension). .IP \(bu 2 If the \fBfilename\fP is either \fB\&.\fP or \fB\&..\fP, it has no extension. .UNINDENT .UNINDENT .UNINDENT .sp The \fIstem\fP is the part of the \fBfilename\fP before the extension. .UNINDENT .sp Some commands refer to a \fBroot\-path\fP\&. This is the concatenation of \fBroot\-name\fP and \fBroot\-directory\-separator\fP, either or both of which can be empty. A \fBrelative\-part\fP refers to the full path with any \fBroot\-path\fP removed. .SS Creating A Path Variable .sp While a path can be created with care using an ordinary \fI\%set()\fP command, it is recommended to use \fI\%cmake_path(SET)\fP instead, as it automatically converts the path to the required form where required. The \fI\%cmake_path(APPEND)\fP 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: .INDENT 0.0 .INDENT 3.5 .sp .EX set(path1 \(dq${CMAKE_CURRENT_SOURCE_DIR}/data\(dq) cmake_path(SET path2 \(dq${CMAKE_CURRENT_SOURCE_DIR}/data\(dq) cmake_path(APPEND path3 \(dq${CMAKE_CURRENT_SOURCE_DIR}\(dq \(dqdata\(dq) .EE .UNINDENT .UNINDENT .sp \fI\%Modification\fP and \fI\%Generation\fP sub\-commands can either store the result in\-place, or in a separate variable named after an \fBOUTPUT_VARIABLE\fP keyword. All other sub\-commands store the result in a mandatory \fB\fP variable. .SS Normalization .sp Some sub\-commands support \fInormalizing\fP a path. The algorithm used to normalize a path is as follows: .INDENT 0.0 .IP 1. 3 If the path is empty, stop (the normalized form of an empty path is also an empty path). .IP 2. 3 Replace each \fBdirectory\-separator\fP, which may consist of multiple separators, with a single \fB/\fP (\fB/a///b \-\-> /a/b\fP). .IP 3. 3 Remove each solitary period (\fB\&.\fP) and any immediately following \fBdirectory\-separator\fP (\fB/a/./b/. \-\-> /a/b\fP). .IP 4. 3 Remove each \fBitem\-name\fP (other than \fB\&..\fP) that is immediately followed by a \fBdirectory\-separator\fP and a \fB\&..\fP, along with any immediately following \fBdirectory\-separator\fP (\fB/a/b/../c \-\-> a/c\fP). .IP 5. 3 If there is a \fBroot\-directory\fP, remove any \fB\&..\fP and any \fBdirectory\-separators\fP immediately following them. The parent of the root directory is treated as still the root directory (\fB/../a \-\-> /a\fP). .IP 6. 3 If the last \fBitem\-name\fP is \fB\&..\fP, remove any trailing \fBdirectory\-separator\fP (\fB\&../ \-\-> ..\fP). .IP 7. 3 If the path is empty by this stage, add a \fBdot\fP (normal form of \fB\&./\fP is \fB\&.\fP). .UNINDENT .SS Decomposition .sp The following forms of the \fBGET\fP subcommand each retrieve a different component or group of components from a path. See \fI\%Path Structure And Terminology\fP for the meaning of each path component. .INDENT 0.0 .INDENT 3.5 .sp .EX 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 ) .EE .UNINDENT .UNINDENT .sp If a requested component is not present in the path, an empty string will be stored in \fB\fP\&. For example, only Windows systems have the concept of a \fBroot\-name\fP, so when the host machine is non\-Windows, the \fBROOT_NAME\fP subcommand will always return an empty string. .sp For \fBPARENT_PATH\fP, if the \fI\%HAS_RELATIVE_PART\fP subcommand returns false, the result is a copy of \fB\fP\&. Note that this implies that a root directory is considered to have a parent, with that parent being itself. Where \fI\%HAS_RELATIVE_PART\fP returns true, the result will essentially be \fB\fP with one less element. .SS Root examples .INDENT 0.0 .INDENT 3.5 .sp .EX set(path \(dqc:/a\(dq) cmake_path(GET path ROOT_NAME rootName) cmake_path(GET path ROOT_DIRECTORY rootDir) cmake_path(GET path ROOT_PATH rootPath) message(\(dqRoot name is \e\(dq${rootName}\e\(dq\(dq) message(\(dqRoot directory is \e\(dq${rootDir}\e\(dq\(dq) message(\(dqRoot path is \e\(dq${rootPath}\e\(dq\(dq) .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX Root name is \(dqc:\(dq Root directory is \(dq/\(dq Root path is \(dqc:/\(dq .EE .UNINDENT .UNINDENT .SS Filename examples .INDENT 0.0 .INDENT 3.5 .sp .EX set(path \(dq/a/b\(dq) cmake_path(GET path FILENAME filename) message(\(dqFirst filename is \e\(dq${filename}\e\(dq\(dq) # Trailing slash means filename is empty set(path \(dq/a/b/\(dq) cmake_path(GET path FILENAME filename) message(\(dqSecond filename is \e\(dq${filename}\e\(dq\(dq) .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX First filename is \(dqb\(dq Second filename is \(dq\(dq .EE .UNINDENT .UNINDENT .SS Extension and stem examples .INDENT 0.0 .INDENT 3.5 .sp .EX set(path \(dqname.ext1.ext2\(dq) cmake_path(GET path EXTENSION fullExt) cmake_path(GET path STEM fullStem) message(\(dqFull extension is \e\(dq${fullExt}\e\(dq\(dq) message(\(dqFull stem is \e\(dq${fullStem}\e\(dq\(dq) # Effect of LAST_ONLY cmake_path(GET path EXTENSION LAST_ONLY lastExt) cmake_path(GET path STEM LAST_ONLY lastStem) message(\(dqLast extension is \e\(dq${lastExt}\e\(dq\(dq) message(\(dqLast stem is \e\(dq${lastStem}\e\(dq\(dq) # Special cases set(dotPath \(dq/a/.\(dq) set(dotDotPath \(dq/a/..\(dq) set(someMorePath \(dq/a/.some.more\(dq) 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 dotMorePath EXTENSION someMoreExt) cmake_path(GET dotMorePath STEM someMoreStem) message(\(dqDot extension is \e\(dq${dotExt}\e\(dq\(dq) message(\(dqDot stem is \e\(dq${dotStem}\e\(dq\(dq) message(\(dqDot\-dot extension is \e\(dq${dotDotExt}\e\(dq\(dq) message(\(dqDot\-dot stem is \e\(dq${dotDotStem}\e\(dq\(dq) message(\(dq.some.more extension is \e\(dq${someMoreExt}\e\(dq\(dq) message(\(dq.some.more stem is \e\(dq${someMoreStem}\e\(dq\(dq) .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX Full extension is \(dq.ext1.ext2\(dq Full stem is \(dqname\(dq Last extension is \(dq.ext2\(dq Last stem is \(dqname.ext1\(dq Dot extension is \(dq\(dq Dot stem is \(dq.\(dq Dot\-dot extension is \(dq\(dq Dot\-dot stem is \(dq..\(dq \&.some.more extension is \(dq.more\(dq \&.some.more stem is \(dq.some\(dq .EE .UNINDENT .UNINDENT .SS Relative part examples .INDENT 0.0 .INDENT 3.5 .sp .EX set(path \(dqc:/a/b\(dq) cmake_path(GET path RELATIVE_PART result) message(\(dqRelative part is \e\(dq${result}\e\(dq\(dq) set(path \(dqc/d\(dq) cmake_path(GET path RELATIVE_PART result) message(\(dqRelative part is \e\(dq${result}\e\(dq\(dq) set(path \(dq/\(dq) cmake_path(GET path RELATIVE_PART result) message(\(dqRelative part is \e\(dq${result}\e\(dq\(dq) .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX Relative part is \(dqa/b\(dq Relative part is \(dqc/d\(dq Relative part is \(dq\(dq .EE .UNINDENT .UNINDENT .SS Path traversal examples .INDENT 0.0 .INDENT 3.5 .sp .EX set(path \(dqc:/a/b\(dq) cmake_path(GET path PARENT_PATH result) message(\(dqParent path is \e\(dq${result}\e\(dq\(dq) set(path \(dqc:/\(dq) cmake_path(GET path PARENT_PATH result) message(\(dqParent path is \e\(dq${result}\e\(dq\(dq) .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX Parent path is \(dqc:/a\(dq Parent path is \(dqc:/\(dq .EE .UNINDENT .UNINDENT .SS Query .sp Each of the \fBGET\fP subcommands has a corresponding \fBHAS_...\fP subcommand which can be used to discover whether a particular path component is present. See \fI\%Path Structure And Terminology\fP for the meaning of each path component. .INDENT 0.0 .INDENT 3.5 .sp .EX 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 ) .EE .UNINDENT .UNINDENT .sp Each of the above follows the predictable pattern of setting \fB\fP to true if the path has the associated component, or false otherwise. Note the following special cases: .INDENT 0.0 .IP \(bu 2 For \fBHAS_ROOT_PATH\fP, a true result will only be returned if at least one of \fBroot\-name\fP or \fBroot\-directory\fP is non\-empty. .IP \(bu 2 For \fBHAS_PARENT_PATH\fP, 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 \fI\%filename\fP\&. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(IS_ABSOLUTE ) .EE .UNINDENT .UNINDENT .sp Sets \fB\fP to true if \fB\fP 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 \fBroot\-name\fP and a \fBroot\-directory\-separator\fP to be considered absolute. On other platforms, just a \fBroot\-directory\-separator\fP is sufficient. Note that this means on Windows, \fBIS_ABSOLUTE\fP can be false while \fBHAS_ROOT_DIRECTORY\fP can be true. .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(IS_RELATIVE ) .EE .UNINDENT .UNINDENT .sp This will store the opposite of \fBIS_ABSOLUTE\fP in \fB\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(IS_PREFIX [NORMALIZE] ) .EE .UNINDENT .UNINDENT .sp Checks if \fB\fP is the prefix of \fB\fP\&. .sp When the \fBNORMALIZE\fP option is specified, \fB\fP and \fB\fP are \fI\%normalized\fP before the check. .INDENT 0.0 .INDENT 3.5 .sp .EX set(path \(dq/a/b/c\(dq) cmake_path(IS_PREFIX path \(dq/a/b/c/d\(dq result) # result = true cmake_path(IS_PREFIX path \(dq/a/b\(dq result) # result = false cmake_path(IS_PREFIX path \(dq/x/y/z\(dq result) # result = false set(path \(dq/a/b\(dq) cmake_path(IS_PREFIX path \(dq/a/c/../b\(dq NORMALIZE result) # result = true .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(COMPARE EQUAL ) cmake_path(COMPARE NOT_EQUAL ) .EE .UNINDENT .UNINDENT .sp 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: .INDENT 0.0 .INDENT 3.5 .sp .EX 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. .EE .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Unlike most other \fBcmake_path()\fP subcommands, the \fBCOMPARE\fP subcommand takes literal strings as input, not the names of variables. .UNINDENT .UNINDENT .SS Modification .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(SET [NORMALIZE] ) .EE .UNINDENT .UNINDENT .sp Assign the \fB\fP path to \fB\fP\&. If \fB\fP is a native path, it is converted into a cmake\-style path with forward\-slashes (\fB/\fP). On Windows, the long filename marker is taken into account. .sp When the \fBNORMALIZE\fP option is specified, the path is \fI\%normalized\fP after the conversion. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .EX set(native_path \(dqc:\e\ea\e\eb/..\e\ec\(dq) cmake_path(SET path \(dq${native_path}\(dq) message(\(dqCMake path is \e\(dq${path}\e\(dq\(dq) cmake_path(SET path NORMALIZE \(dq${native_path}\(dq) message(\(dqNormalized CMake path is \e\(dq${path}\e\(dq\(dq) .EE .UNINDENT .UNINDENT .sp Output: .INDENT 0.0 .INDENT 3.5 .sp .EX CMake path is \(dqc:/a/b/../c\(dq Normalized CMake path is \(dqc:/a/c\(dq .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(APPEND [...] [OUTPUT_VARIABLE ]) .EE .UNINDENT .UNINDENT .sp Append all the \fB\fP arguments to the \fB\fP using \fB/\fP as the \fBdirectory\-separator\fP\&. Depending on the \fB\fP, the previous contents of \fB\fP may be discarded. For each \fB\fP argument, the following algorithm (pseudo\-code) applies: .INDENT 0.0 .INDENT 3.5 .sp .EX # 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 .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(APPEND_STRING [...] [OUTPUT_VARIABLE ]) .EE .UNINDENT .UNINDENT .sp Append all the \fB\fP arguments to the \fB\fP without adding any \fBdirectory\-separator\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(REMOVE_FILENAME [OUTPUT_VARIABLE ]) .EE .UNINDENT .UNINDENT .sp Removes the \fI\%filename\fP component (as returned by \fI\%GET ... FILENAME\fP) from \fB\fP\&. After removal, any trailing \fBdirectory\-separator\fP is left alone, if present. .sp If \fBOUTPUT_VARIABLE\fP is not given, then after this function returns, \fI\%HAS_FILENAME\fP returns false for \fB\fP\&. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .EX set(path \(dq/a/b\(dq) cmake_path(REMOVE_FILENAME path) message(\(dqFirst path is \e\(dq${path}\e\(dq\(dq) # filename is now already empty, the following removes nothing cmake_path(REMOVE_FILENAME path) message(\(dqSecond path is \e\(dq${result}\e\(dq\(dq) .EE .UNINDENT .UNINDENT .sp Output: .INDENT 0.0 .INDENT 3.5 .sp .EX First path is \(dq/a/\(dq Second path is \(dq/a/\(dq .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(REPLACE_FILENAME [OUTPUT_VARIABLE ]) .EE .UNINDENT .UNINDENT .sp Replaces the \fI\%filename\fP component from \fB\fP with \fB\fP\&. If \fB\fP has no filename component (i.e. \fI\%HAS_FILENAME\fP returns false), the path is unchanged. The operation is equivalent to the following: .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(HAS_FILENAME path has_filename) if(has_filename) cmake_path(REMOVE_FILENAME path) cmake_path(APPEND path input); endif() .EE .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(REMOVE_EXTENSION [LAST_ONLY] [OUTPUT_VARIABLE ]) .EE .UNINDENT .UNINDENT .sp Removes the \fI\%extension\fP, if any, from \fB\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(REPLACE_EXTENSION [LAST_ONLY] [OUTPUT_VARIABLE ]) .EE .UNINDENT .UNINDENT .sp Replaces the \fI\%extension\fP with \fB\fP\&. Its effect is equivalent to the following: .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(REMOVE_EXTENSION path) if(NOT \(dqinput\(dq MATCHES \(dq^\e\e.\(dq) cmake_path(APPEND_STRING path \(dq.\(dq) endif() cmake_path(APPEND_STRING path \(dqinput\(dq) .EE .UNINDENT .UNINDENT .SS Generation .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(NORMAL_PATH [OUTPUT_VARIABLE ]) .EE .UNINDENT .UNINDENT .sp Normalize \fB\fP according the steps described in \fI\%Normalization\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(RELATIVE_PATH [BASE_DIRECTORY ] [OUTPUT_VARIABLE ]) .EE .UNINDENT .UNINDENT .sp Modifies \fB\fP to make it relative to the \fBBASE_DIRECTORY\fP argument. If \fBBASE_DIRECTORY\fP is not specified, the default base directory will be \fI\%CMAKE_CURRENT_SOURCE_DIR\fP\&. .sp For reference, the algorithm used to compute the relative path is the same as that used by C++ \fI\%std::filesystem::path::lexically_relative\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(ABSOLUTE_PATH [BASE_DIRECTORY ] [NORMALIZE] [OUTPUT_VARIABLE ]) .EE .UNINDENT .UNINDENT .sp If \fB\fP is a relative path (\fI\%IS_RELATIVE\fP is true), it is evaluated relative to the given base directory specified by \fBBASE_DIRECTORY\fP option. If \fBBASE_DIRECTORY\fP is not specified, the default base directory will be \fI\%CMAKE_CURRENT_SOURCE_DIR\fP\&. .sp When the \fBNORMALIZE\fP option is specified, the path is \fI\%normalized\fP after the path computation. .sp Because \fBcmake_path()\fP 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 \fI\%file(REAL_PATH)\fP command instead. .SS Native Conversion .sp For commands in this section, \fInative\fP refers to the host platform, not the target platform when cross\-compiling. .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(NATIVE_PATH [NORMALIZE] ) .EE .UNINDENT .UNINDENT .sp Converts a cmake\-style \fB\fP into a native path with platform\-specific slashes (\fB\e\fP on Windows hosts and \fB/\fP elsewhere). .sp When the \fBNORMALIZE\fP option is specified, the path is \fI\%normalized\fP before the conversion. .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(CONVERT TO_CMAKE_PATH_LIST [NORMALIZE]) .EE .UNINDENT .UNINDENT .sp Converts a native \fB\fP path into a cmake\-style path with forward slashes (\fB/\fP). On Windows hosts, the long filename marker is taken into account. The input can be a single path or a system search path like \fB$ENV{PATH}\fP\&. A search path will be converted to a cmake\-style list separated by \fB;\fP characters (on non\-Windows platforms, this essentially means \fB:\fP separators are replaced with \fB;\fP). The result of the conversion is stored in the \fB\fP variable. .sp When the \fBNORMALIZE\fP option is specified, the path is \fI\%normalized\fP before the conversion. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Unlike most other \fBcmake_path()\fP subcommands, the \fBCONVERT\fP subcommand takes a literal string as input, not the name of a variable. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(CONVERT TO_NATIVE_PATH_LIST [NORMALIZE]) .EE .UNINDENT .UNINDENT .sp Converts a cmake\-style \fB\fP path into a native path with platform\-specific slashes (\fB\e\fP on Windows hosts and \fB/\fP elsewhere). The input can be a single path or a cmake\-style list. A list will be converted into a native search path (\fB;\fP\-separated on Windows, \fB:\fP\-separated on other platforms). The result of the conversion is stored in the \fB\fP variable. .sp When the \fBNORMALIZE\fP option is specified, the path is \fI\%normalized\fP before the conversion. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Unlike most other \fBcmake_path()\fP subcommands, the \fBCONVERT\fP subcommand takes a literal string as input, not the name of a variable. .UNINDENT .UNINDENT .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .EX set(paths \(dq/a/b/c\(dq \(dq/x/y/z\(dq) cmake_path(CONVERT \(dq${paths}\(dq TO_NATIVE_PATH_LIST native_paths) message(\(dqNative path list is \e\(dq${native_paths}\e\(dq\(dq) .EE .UNINDENT .UNINDENT .sp Output on Windows: .INDENT 0.0 .INDENT 3.5 .sp .EX Native path list is \(dq\ea\eb\ec;\ex\ey\ez\(dq .EE .UNINDENT .UNINDENT .sp Output on all other platforms: .INDENT 0.0 .INDENT 3.5 .sp .EX Native path list is \(dq/a/b/c:/x/y/z\(dq .EE .UNINDENT .UNINDENT .SS Hashing .INDENT 0.0 .INDENT 3.5 .sp .EX cmake_path(HASH ) .EE .UNINDENT .UNINDENT .sp Compute a hash value of \fB\fP such that for two paths \fBp1\fP and \fBp2\fP that compare equal (\fI\%COMPARE ... EQUAL\fP), the hash value of \fBp1\fP is equal to the hash value of \fBp2\fP\&. The path is always \fI\%normalized\fP before the hash is computed. .SS cmake_policy .sp Manage CMake Policy settings. See the \fI\%cmake\-policies(7)\fP manual for defined policies. .sp 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 \fBCMP\fP where \fB\fP is an integer index. Documentation associated with each policy describes the \fBOLD\fP and \fBNEW\fP 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 \fBOLD\fP behavior is assumed and a warning is produced requesting that the policy be set. .SS Setting Policies by CMake Version .sp The \fBcmake_policy\fP command is used to set policies to \fBOLD\fP or \fBNEW\fP behavior. While setting policies individually is supported, we encourage projects to set policies based on CMake versions: .INDENT 0.0 .TP .B cmake_policy(VERSION [...]) .UNINDENT .sp New in version 3.12: The optional \fB\fP version. .sp \fB\fP and the optional \fB\fP are each CMake versions of the form \fBmajor.minor[.patch[.tweak]]\fP, and the \fB\&...\fP is literal. The \fB\fP version must be at least \fB2.4\fP and at most the running version of CMake. The \fB\fP version, if specified, must be at least the \fB\fP version but may exceed the running version of CMake. If the running version of CMake is older than 3.12, the extra \fB\&...\fP dots will be seen as version component separators, resulting in the \fB\&...\fP part being ignored and preserving the pre\-3.12 behavior of basing policies on \fB\fP\&. .sp This specifies that the current CMake code is written for the given range of CMake versions. All policies known to the running version of CMake and introduced in the \fB\fP (or \fB\fP, if specified) version or earlier will be set to use \fBNEW\fP behavior. All policies introduced in later versions will be unset (unless the \fI\%CMAKE_POLICY_DEFAULT_CMP\fP variable sets a default). This effectively requests behavior preferred as of a given CMake version and tells newer CMake versions to warn about their new policies. .sp Note that the \fI\%cmake_minimum_required(VERSION)\fP command implicitly calls \fBcmake_policy(VERSION)\fP too. .sp Changed in version 3.27: Compatibility with versions of CMake older than 3.5 is deprecated. Calls to \fI\%cmake_minimum_required(VERSION)\fP or \fI\%cmake_policy(VERSION)\fP that do not specify at least 3.5 as their policy version (optionally via \fB\&...\fP) will produce a deprecation warning in CMake 3.27 and above. .sp Changed in version 3.19: Compatibility with versions of CMake older than 2.8.12 is deprecated. Calls to \fI\%cmake_minimum_required(VERSION)\fP or \fI\%cmake_policy(VERSION)\fP that do not specify at least 2.8.12 as their policy version (optionally via \fB\&...\fP) will produce a deprecation warning in CMake 3.19 and above. .SS Setting Policies Explicitly .INDENT 0.0 .TP .B cmake_policy(SET CMP NEW|OLD) .UNINDENT .sp Tell CMake to use the \fBOLD\fP or \fBNEW\fP 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 \fBOLD\fP\&. Alternatively one may fix the project to work with the new behavior and set the policy state to \fBNEW\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBOLD\fP behavior of a policy is \fI\%deprecated by definition\fP and may be removed in a future version of CMake. .UNINDENT .UNINDENT .SS Checking Policy Settings .INDENT 0.0 .TP .B cmake_policy(GET CMP ) .UNINDENT .sp Check whether a given policy is set to \fBOLD\fP or \fBNEW\fP behavior. The output \fB\fP value will be \fBOLD\fP or \fBNEW\fP if the policy is set, and empty otherwise. .SS CMake Policy Stack .sp CMake keeps policy settings on a stack, so changes made by the \fBcmake_policy\fP 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 \fI\%include()\fP and \fI\%find_package()\fP commands except when invoked with the \fBNO_POLICY_SCOPE\fP option (see also policy \fI\%CMP0011\fP). The \fBcmake_policy\fP command provides an interface to manage custom entries on the policy stack: .INDENT 0.0 .TP .B cmake_policy(PUSH) Create a new entry on the policy stack. .UNINDENT .INDENT 0.0 .TP .B cmake_policy(POP) Remove the last policy stack entry created with \fBcmake_policy(PUSH)\fP\&. .UNINDENT .sp Each \fBPUSH\fP must have a matching \fBPOP\fP to erase any changes. This is useful to make temporary changes to policy settings. Calls to the \fI\%cmake_minimum_required(VERSION)\fP, \fI\%cmake_policy(VERSION)\fP, or \fI\%cmake_policy(SET)\fP commands influence only the current top of the policy stack. .sp New in version 3.25: The \fI\%block(SCOPE_FOR POLICIES)\fP 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 \fI\%return()\fP with a call to \fI\%cmake_policy(POP)\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .EX # 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() .EE .UNINDENT .UNINDENT .sp Commands created by the \fI\%function()\fP and \fI\%macro()\fP 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. .SS See Also .INDENT 0.0 .IP \(bu 2 \fI\%cmake_minimum_required()\fP .UNINDENT .SS configure_file .sp Copy a file to another location and modify its contents. .INDENT 0.0 .INDENT 3.5 .sp .EX configure_file( [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS | FILE_PERMISSIONS ...] [COPYONLY] [ESCAPE_QUOTES] [@ONLY] [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) .EE .UNINDENT .UNINDENT .sp Copies an \fB\fP file to an \fB\fP file while performing \fI\%transformations\fP of the input file content. .sp 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. .SS Options .sp The options are: .INDENT 0.0 .TP .B \fB\fP Path to the input file. A relative path is treated with respect to the value of \fI\%CMAKE_CURRENT_SOURCE_DIR\fP\&. The input path must be a file, not a directory. .TP .B \fB\fP Path to the output file or directory. A relative path is treated with respect to the value of \fI\%CMAKE_CURRENT_BINARY_DIR\fP\&. 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. .TP .B \fBNO_SOURCE_PERMISSIONS\fP New in version 3.19. .sp 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\-\-). .TP .B \fBUSE_SOURCE_PERMISSIONS\fP New in version 3.20. .sp 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 (\fBNO_SOURCE_PERMISSIONS\fP, \fBUSE_SOURCE_PERMISSIONS\fP or \fBFILE_PERMISSIONS\fP). The \fBUSE_SOURCE_PERMISSIONS\fP keyword mostly serves as a way of making the intended behavior clearer at the call site. .TP .B \fBFILE_PERMISSIONS ...\fP New in version 3.20. .sp Ignore the input file\(aqs permissions and use the specified \fB\fP for the output file instead. .TP .B \fBCOPYONLY\fP Copy the file without replacing any variable references or other content. This option may not be used with \fBNEWLINE_STYLE\fP\&. .TP .B \fBESCAPE_QUOTES\fP Escape any substituted quotes with backslashes (C\-style). .TP .B \fB@ONLY\fP Restrict variable replacement to references of the form \fB@VAR@\fP\&. This is useful for configuring scripts that use \fB${VAR}\fP syntax. .TP .B \fBNEWLINE_STYLE