| .\" Man page generated from reStructuredText. |
| . |
| .TH "CMAKE-COMMANDS" "7" "Apr 12, 2022" "3.23.1" "CMake" |
| .SH NAME |
| cmake-commands \- CMake Language Command Reference |
| . |
| .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 |
| .. |
| .SH SCRIPTING COMMANDS |
| .sp |
| These commands are always available. |
| .SS break |
| .sp |
| Break from an enclosing foreach or while loop. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| break() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Breaks from an enclosing \fBforeach()\fP or \fBwhile()\fP loop. |
| .sp |
| See also the \fBcontinue()\fP command. |
| .SS cmake_host_system_information |
| .sp |
| Query host system specific information. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_host_system_information(RESULT <variable> QUERY <key> ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Queries system information of the host system on which cmake runs. |
| One or more \fB<key>\fP can be provided to select the information to be |
| queried. The list of queried values is stored in \fB<variable>\fP\&. |
| .sp |
| \fB<key>\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 \fBCMAKE_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 \fBCMAKE_HOST_SYSTEM_PROCESSOR\fP |
| .TP |
| .B \fBDISTRIB_INFO\fP |
| New in version 3.22. |
| |
| .sp |
| Read \fB/etc/os\-release\fP file and define the given \fB<variable>\fP |
| into a list of read variables |
| .TP |
| .B \fBDISTRIB_<name>\fP |
| New in version 3.22. |
| |
| .sp |
| Get the \fB<name>\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 |
| .nf |
| .ft C |
| 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}=\(ga${${VAR}}\(ga") |
| endforeach() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Output: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \-\- 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 |
| .ft P |
| .fi |
| .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\-<name>.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_<varname> |
| 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_<varname>\fP variables in this list. |
| .UNINDENT |
| .sp |
| Example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # 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\e.]+) .*") |
| 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) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SH FOOTNOTES |
| .IP [1] 5 |
| One MiB (mebibyte) is equal to 1024x1024 bytes. |
| .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 |
| .nf |
| .ft C |
| cmake_language(\fI\%CALL\fP <command> [<arg>...]) |
| cmake_language(\fI\%EVAL\fP CODE <code>...) |
| cmake_language(\fI\%DEFER\fP <options>... CALL <command> [<arg>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Introduction |
| .sp |
| This command will call meta\-operations on built\-in CMake commands or |
| those created via the \fBmacro()\fP or \fBfunction()\fP commands. |
| .sp |
| \fBcmake_language\fP does not introduce a new variable or policy scope. |
| .SS Calling Commands |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_language(CALL <command> [<arg>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Calls the named \fB<command>\fP with the given arguments (if any). |
| For example, the code: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(message_command "message") |
| cmake_language(CALL ${message_command} STATUS "Hello World!") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| is equivalent to |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| message(STATUS "Hello World!") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.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 |
| \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 |
| .SS Evaluating Code |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_language(EVAL CODE <code>...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Evaluates the \fB<code>...\fP as CMake code. |
| .sp |
| For example, the code: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| 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()" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| is equivalent to |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| 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) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Deferring Calls |
| .sp |
| New in version 3.19. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_language(DEFER <options>... CALL <command> [<arg>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Schedules a call to the named \fB<command>\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 \fBreturn()\fP call. Variable |
| references in arguments are evaluated at the time the deferred call is |
| executed. |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBDIRECTORY <dir>\fP |
| Schedule the call for the end of the given directory instead of the |
| current directory. The \fB<dir>\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 \fBadd_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 <id>\fP |
| Specify an identification for the deferred call. |
| The \fB<id>\fP may not be empty and may not begin with a capital letter \fBA\-Z\fP\&. |
| The \fB<id>\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 <var>\fP |
| Specify a variable in which to store the identification for the |
| deferred call. If \fBID <id>\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 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This will store in \fB<var>\fP a semicolon\-separated list 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 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This will store in \fB<var>\fP a semicolon\-separated list 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 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...) |
| .ft P |
| .fi |
| .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. |
| .SS Deferred Call Examples |
| .sp |
| For example, the code: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| 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") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| prints: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Immediate Message |
| Deferred Message |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBCancelled 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 |
| .nf |
| .ft C |
| 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 \e"${re_evaluated}\e") |
| ") |
| message("Immediate Message") |
| set(deferred_message "Deferred Message 2") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| also prints: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Immediate Message |
| Deferred Message 1 |
| Deferred Message 2 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS cmake_minimum_required |
| .sp |
| Require a minimum version of cmake. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_minimum_required(VERSION <min>[...<policy_max>] [FATAL_ERROR]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.12: The optional \fB<policy_max>\fP version. |
| |
| .sp |
| Sets the minimum required version of cmake for a project. |
| Also updates the policy settings as explained below. |
| .sp |
| \fB<min>\fP and the optional \fB<policy_max>\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<min>\fP required |
| version it will stop processing the project and report an error. |
| The optional \fB<policy_max>\fP version, if specified, must be at least the |
| \fB<min>\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\&...<max>\fP part being ignored and preserving the pre\-3.12 behavior |
| of basing policies on \fB<min>\fP\&. |
| .sp |
| This command will set the value of the |
| \fBCMAKE_MINIMUM_REQUIRED_VERSION\fP variable to \fB<min>\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 |
| \fBproject()\fP command. It is important to establish version |
| and policy settings before invoking other commands whose behavior |
| they may affect. See also policy \fBCMP0000\fP\&. |
| .sp |
| Calling \fBcmake_minimum_required()\fP inside a \fBfunction()\fP |
| limits some effects to the function scope when invoked. For example, |
| the \fBCMAKE_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 |
| \fBcmake_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<min>\fP (or \fB<max>\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<min>\fP version higher than 2.4 is specified the command |
| implicitly invokes |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_policy(VERSION <min>[...<max>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| which sets CMake policies based on the range of versions specified. |
| When a \fB<min>\fP version 2.4 or lower is given the command implicitly |
| invokes |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_policy(VERSION 2.4[...<max>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| which enables compatibility features for CMake 2.4 and lower. |
| .SS cmake_parse_arguments |
| .sp |
| Parse function or macro arguments. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_parse_arguments(<prefix> <options> <one_value_keywords> |
| <multi_value_keywords> <args>...) |
| |
| cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options> |
| <one_value_keywords> <multi_value_keywords>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.5: This command is implemented natively. Previously, it has been defined in the |
| module \fBCMakeParseArguments\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<args>...\fP\&. |
| This may be used in either a \fBmacro()\fP or a \fBfunction()\fP\&. |
| .sp |
| New in version 3.7: The \fBPARSE_ARGV\fP signature is only for use in a \fBfunction()\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<N>\fP\-th argument, where \fB<N>\fP is an unsigned integer. |
| This allows for the values to have special characters like \fB;\fP in them. |
| |
| .sp |
| The \fB<options>\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 \fBinstall()\fP |
| command. |
| .sp |
| The \fB<one_value_keywords>\fP argument contains all keywords for this macro |
| which are followed by one value, like e.g. \fBDESTINATION\fP keyword of the |
| \fBinstall()\fP command. |
| .sp |
| The \fB<multi_value_keywords>\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 \fBinstall()\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<options>\fP, \fB<one_value_keywords>\fP or |
| \fB<multi_value_keywords>\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<options>\fP, \fB<one_value_keywords>\fP and |
| \fB<multi_value_keywords>\fP a variable composed of the given \fB<prefix>\fP |
| followed by \fB"_"\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<options>\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<prefix>_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<one_value_keywords>\fP and \fB<multi_value_keywords>\fP that were given no |
| values at all are collected in a variable |
| \fB<prefix>_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 \fBinstall()\fP command: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| macro(my_install) |
| set(options OPTIONAL FAST) |
| set(oneValueArgs DESTINATION RENAME) |
| set(multiValueArgs TARGETS CONFIGURATIONS) |
| cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" |
| "${multiValueArgs}" ${ARGN} ) |
| |
| # ... |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Assume \fBmy_install()\fP has been called like this: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS) |
| .ft P |
| .fi |
| .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 |
| .nf |
| .ft C |
| MY_INSTALL_OPTIONAL = TRUE |
| MY_INSTALL_FAST = FALSE # was not used in call to my_install |
| MY_INSTALL_DESTINATION = "bin" |
| MY_INSTALL_RENAME <UNDEFINED> # was not used |
| MY_INSTALL_TARGETS = "foo;bar" |
| MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used |
| MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL" |
| MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS" |
| # No value for "CONFIGURATIONS" given |
| .ft P |
| .fi |
| .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"OPTIONAL"\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 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 \fBfile()\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 |
| .nf |
| .ft C |
| \fI\%Conventions\fP |
| |
| \fI\%Path Structure And Terminology\fP |
| |
| \fI\%Normalization\fP |
| |
| \fI\%Decomposition\fP |
| cmake_path(\fI\%GET\fP <path\-var> \fI\%ROOT_NAME\fP <out\-var>) |
| cmake_path(\fI\%GET\fP <path\-var> \fI\%ROOT_DIRECTORY\fP <out\-var>) |
| cmake_path(\fI\%GET\fP <path\-var> \fI\%ROOT_PATH\fP <out\-var>) |
| cmake_path(\fI\%GET\fP <path\-var> \fI\%FILENAME\fP <out\-var>) |
| cmake_path(\fI\%GET\fP <path\-var> \fI\%EXTENSION\fP [LAST_ONLY] <out\-var>) |
| cmake_path(\fI\%GET\fP <path\-var> \fI\%STEM\fP [LAST_ONLY] <out\-var>) |
| cmake_path(\fI\%GET\fP <path\-var> \fI\%RELATIVE_PART\fP <out\-var>) |
| cmake_path(\fI\%GET\fP <path\-var> \fI\%PARENT_PATH\fP <out\-var>) |
| |
| \fI\%Query\fP |
| cmake_path(\fI\%HAS_ROOT_NAME\fP <path\-var> <out\-var>) |
| cmake_path(\fI\%HAS_ROOT_DIRECTORY\fP <path\-var> <out\-var>) |
| cmake_path(\fI\%HAS_ROOT_PATH\fP <path\-var> <out\-var>) |
| cmake_path(\fI\%HAS_FILENAME\fP <path\-var> <out\-var>) |
| cmake_path(\fI\%HAS_EXTENSION\fP <path\-var> <out\-var>) |
| cmake_path(\fI\%HAS_STEM\fP <path\-var> <out\-var>) |
| cmake_path(\fI\%HAS_RELATIVE_PART\fP <path\-var> <out\-var>) |
| cmake_path(\fI\%HAS_PARENT_PATH\fP <path\-var> <out\-var>) |
| cmake_path(\fI\%IS_ABSOLUTE\fP <path\-var> <out\-var>) |
| cmake_path(\fI\%IS_RELATIVE\fP <path\-var> <out\-var>) |
| cmake_path(\fI\%IS_PREFIX\fP <path\-var> <input> [NORMALIZE] <out\-var>) |
| cmake_path(\fI\%COMPARE\fP <input1> <OP> <input2> <out\-var>) |
| |
| \fI\%Modification\fP |
| cmake_path(\fI\%SET\fP <path\-var> [NORMALIZE] <input>) |
| cmake_path(\fI\%APPEND\fP <path\-var> [<input>...] [OUTPUT_VARIABLE <out\-var>]) |
| cmake_path(\fI\%APPEND_STRING\fP <path\-var> [<input>...] [OUTPUT_VARIABLE <out\-var>]) |
| cmake_path(\fI\%REMOVE_FILENAME\fP <path\-var> [OUTPUT_VARIABLE <out\-var>]) |
| cmake_path(\fI\%REPLACE_FILENAME\fP <path\-var> <input> [OUTPUT_VARIABLE <out\-var>]) |
| cmake_path(\fI\%REMOVE_EXTENSION\fP <path\-var> [LAST_ONLY] [OUTPUT_VARIABLE <out\-var>]) |
| cmake_path(\fI\%REPLACE_EXTENSION\fP <path\-var> [LAST_ONLY] <input> [OUTPUT_VARIABLE <out\-var>]) |
| |
| \fI\%Generation\fP |
| cmake_path(\fI\%NORMAL_PATH\fP <path\-var> [OUTPUT_VARIABLE <out\-var>]) |
| cmake_path(\fI\%RELATIVE_PATH\fP <path\-var> [BASE_DIRECTORY <input>] [OUTPUT_VARIABLE <out\-var>]) |
| cmake_path(\fI\%ABSOLUTE_PATH\fP <path\-var> [BASE_DIRECTORY <input>] [NORMALIZE] [OUTPUT_VARIABLE <out\-var>]) |
| |
| \fI\%Native Conversion\fP |
| cmake_path(\fI\%NATIVE_PATH\fP <path\-var> [NORMALIZE] <out\-var>) |
| cmake_path(\fI\%CONVERT\fP <input> \fI\%TO_CMAKE_PATH_LIST\fP <out\-var> [NORMALIZE]) |
| cmake_path(\fI\%CONVERT\fP <input> \fI\%TO_NATIVE_PATH_LIST\fP <out\-var> [NORMALIZE]) |
| |
| \fI\%Hashing\fP |
| cmake_path(\fI\%HASH\fP <path\-var> <out\-var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Conventions |
| .sp |
| The following conventions are used in this command\(aqs documentation: |
| .INDENT 0.0 |
| .TP |
| .B \fB<path\-var>\fP |
| Always the name of a variable. For commands that expect a \fB<path\-var>\fP |
| as input, the variable must exist and it is expected to hold a single path. |
| .TP |
| .B \fB<input>\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<input>...\fP |
| Zero or more string literal arguments. |
| .TP |
| .B \fB<out\-var>\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 |
| .nf |
| .ft C |
| root\-name root\-directory\-separator (item\-name directory\-separator)* filename |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBroot\-name\fP |
| Identifies the root on a filesystem with multiple roots (such as \fB"C:"\fP |
| or \fB"//myserver"\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".profile"\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 \fBset()\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 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: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| 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") |
| .ft P |
| .fi |
| .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<out\-var>\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 |
| .nf |
| .ft C |
| cmake_path(GET <path\-var> ROOT_NAME <out\-var>) |
| cmake_path(GET <path\-var> ROOT_DIRECTORY <out\-var>) |
| cmake_path(GET <path\-var> ROOT_PATH <out\-var>) |
| cmake_path(GET <path\-var> FILENAME <out\-var>) |
| cmake_path(GET <path\-var> EXTENSION [LAST_ONLY] <out\-var>) |
| cmake_path(GET <path\-var> STEM [LAST_ONLY] <out\-var>) |
| cmake_path(GET <path\-var> RELATIVE_PART <out\-var>) |
| cmake_path(GET <path\-var> PARENT_PATH <out\-var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If a requested component is not present in the path, an empty string will be |
| stored in \fB<out\-var>\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<path\-var>\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<path\-var>\fP with one less element. |
| .SS Root examples |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| 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 \e"${rootName}\e"") |
| message("Root directory is \e"${rootDir}\e"") |
| message("Root path is \e"${rootPath}\e"") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Root name is "c:" |
| Root directory is "/" |
| Root path is "c:/" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Filename examples |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(path "/a/b") |
| cmake_path(GET path FILENAME filename) |
| message("First filename is \e"${filename}\e"") |
| |
| # Trailing slash means filename is empty |
| set(path "/a/b/") |
| cmake_path(GET path FILENAME filename) |
| message("Second filename is \e"${filename}\e"") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| First filename is "b" |
| Second filename is "" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Extension and stem examples |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(path "name.ext1.ext2") |
| |
| cmake_path(GET path EXTENSION fullExt) |
| cmake_path(GET path STEM fullStem) |
| message("Full extension is \e"${fullExt}\e"") |
| message("Full stem is \e"${fullStem}\e"") |
| |
| # Effect of LAST_ONLY |
| cmake_path(GET path EXTENSION LAST_ONLY lastExt) |
| cmake_path(GET path STEM LAST_ONLY lastStem) |
| message("Last extension is \e"${lastExt}\e"") |
| message("Last stem is \e"${lastStem}\e"") |
| |
| # 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 dotMorePath EXTENSION someMoreExt) |
| cmake_path(GET dotMorePath STEM someMoreStem) |
| message("Dot extension is \e"${dotExt}\e"") |
| message("Dot stem is \e"${dotStem}\e"") |
| message("Dot\-dot extension is \e"${dotDotExt}\e"") |
| message("Dot\-dot stem is \e"${dotDotStem}\e"") |
| message(".some.more extension is \e"${someMoreExt}\e"") |
| message(".some.more stem is \e"${someMoreStem}\e"") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| 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" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Relative part examples |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(path "c:/a/b") |
| cmake_path(GET path RELATIVE_PART result) |
| message("Relative part is \e"${result}\e"") |
| |
| set(path "c/d") |
| cmake_path(GET path RELATIVE_PART result) |
| message("Relative part is \e"${result}\e"") |
| |
| set(path "/") |
| cmake_path(GET path RELATIVE_PART result) |
| message("Relative part is \e"${result}\e"") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Relative part is "a/b" |
| Relative part is "c/d" |
| Relative part is "" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Path traversal examples |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(path "c:/a/b") |
| cmake_path(GET path PARENT_PATH result) |
| message("Parent path is \e"${result}\e"") |
| |
| set(path "c:/") |
| cmake_path(GET path PARENT_PATH result) |
| message("Parent path is \e"${result}\e"") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Parent path is "c:/a" |
| Parent path is "c:/" |
| .ft P |
| .fi |
| .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 |
| .nf |
| .ft C |
| cmake_path(HAS_ROOT_NAME <path\-var> <out\-var>) |
| cmake_path(HAS_ROOT_DIRECTORY <path\-var> <out\-var>) |
| cmake_path(HAS_ROOT_PATH <path\-var> <out\-var>) |
| cmake_path(HAS_FILENAME <path\-var> <out\-var>) |
| cmake_path(HAS_EXTENSION <path\-var> <out\-var>) |
| cmake_path(HAS_STEM <path\-var> <out\-var>) |
| cmake_path(HAS_RELATIVE_PART <path\-var> <out\-var>) |
| cmake_path(HAS_PARENT_PATH <path\-var> <out\-var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Each of the above follows the predictable pattern of setting \fB<out\-var>\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 |
| .nf |
| .ft C |
| cmake_path(IS_ABSOLUTE <path\-var> <out\-var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets \fB<out\-var>\fP to true if \fB<path\-var>\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 |
| .nf |
| .ft C |
| cmake_path(IS_RELATIVE <path\-var> <out\-var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This will store the opposite of \fBIS_ABSOLUTE\fP in \fB<out\-var>\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_path(IS_PREFIX <path\-var> <input> [NORMALIZE] <out\-var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Checks if \fB<path\-var>\fP is the prefix of \fB<input>\fP\&. |
| .sp |
| When the \fBNORMALIZE\fP option is specified, \fB<path\-var>\fP and \fB<input>\fP |
| are \fI\%normalized\fP before the check. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| 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 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_path(COMPARE <input1> EQUAL <input2> <out\-var>) |
| cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out\-var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Compares the lexical representations of two paths provided as string literals. |
| No normalization is performed on either path. Equality is determined |
| according to the following pseudo\-code logic: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| if(NOT <input1>.root_name() STREQUAL <input2>.root_name()) |
| return FALSE |
| |
| if(<input1>.has_root_directory() XOR <input2>.has_root_directory()) |
| return FALSE |
| |
| Return FALSE if a relative portion of <input1> is not lexicographically |
| equal to the relative portion of <input2>. This comparison is performed path |
| component\-wise. If all of the components compare equal, then return TRUE. |
| .ft P |
| .fi |
| .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 |
| .nf |
| .ft C |
| cmake_path(SET <path\-var> [NORMALIZE] <input>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Assign the \fB<input>\fP path to \fB<path\-var>\fP\&. If \fB<input>\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 before the conversion. |
| .sp |
| For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(native_path "c:\e\ea\e\eb/..\e\ec") |
| cmake_path(SET path "${native_path}") |
| message("CMake path is \e"${path}\e"") |
| |
| cmake_path(SET path NORMALIZE "${native_path}") |
| message("Normalized CMake path is \e"${path}\e"") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Output: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CMake path is "c:/a/b/../c" |
| Normalized CMake path is "c:/a/c" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_path(APPEND <path\-var> [<input>...] [OUTPUT_VARIABLE <out\-var>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Append all the \fB<input>\fP arguments to the \fB<path\-var>\fP using \fB/\fP as |
| the \fBdirectory\-separator\fP\&. Depending on the \fB<input>\fP, the previous |
| contents of \fB<path\-var>\fP may be discarded. For each \fB<input>\fP argument, |
| the following algorithm (pseudo\-code) applies: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # <path> is the contents of <path\-var> |
| |
| if(<input>.is_absolute() OR |
| (<input>.has_root_name() AND |
| NOT <input>.root_name() STREQUAL <path>.root_name())) |
| replace <path> with <input> |
| return() |
| endif() |
| |
| if(<input>.has_root_directory()) |
| remove any root\-directory and the entire relative path from <path> |
| elseif(<path>.has_filename() OR |
| (NOT <path\-var>.has_root_directory() OR <path>.is_absolute())) |
| append directory\-separator to <path> |
| endif() |
| |
| append <input> omitting any root\-name to <path> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_path(APPEND_STRING <path\-var> [<input>...] [OUTPUT_VARIABLE <out\-var>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Append all the \fB<input>\fP arguments to the \fB<path\-var>\fP without adding any |
| \fBdirectory\-separator\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_path(REMOVE_FILENAME <path\-var> [OUTPUT_VARIABLE <out\-var>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Removes the \fI\%filename\fP component (as returned by |
| \fI\%GET ... FILENAME\fP) from \fB<path\-var>\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<path\-var>\fP\&. |
| .sp |
| For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(path "/a/b") |
| cmake_path(REMOVE_FILENAME path) |
| message("First path is \e"${path}\e"") |
| |
| # filename is now already empty, the following removes nothing |
| cmake_path(REMOVE_FILENAME path) |
| message("Second path is \e"${result}\e"") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Output: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| First path is "/a/" |
| Second path is "/a/" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_path(REPLACE_FILENAME <path\-var> <input> [OUTPUT_VARIABLE <out\-var>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Replaces the \fI\%filename\fP component from \fB<path\-var>\fP |
| with \fB<input>\fP\&. If \fB<path\-var>\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 |
| .nf |
| .ft C |
| cmake_path(HAS_FILENAME path has_filename) |
| if(has_filename) |
| cmake_path(REMOVE_FILENAME path) |
| cmake_path(APPEND path input); |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_path(REMOVE_EXTENSION <path\-var> [LAST_ONLY] |
| [OUTPUT_VARIABLE <out\-var>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Removes the \fI\%extension\fP, if any, from \fB<path\-var>\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_path(REPLACE_EXTENSION <path\-var> [LAST_ONLY] <input> |
| [OUTPUT_VARIABLE <out\-var>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Replaces the \fI\%extension\fP with \fB<input>\fP\&. Its effect |
| is equivalent to the following: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_path(REMOVE_EXTENSION path) |
| if(NOT "input" MATCHES "^\e\e.") |
| cmake_path(APPEND_STRING path ".") |
| endif() |
| cmake_path(APPEND_STRING path "input") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Generation |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_path(NORMAL_PATH <path\-var> [OUTPUT_VARIABLE <out\-var>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Normalize \fB<path\-var>\fP according the steps described in \fI\%Normalization\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_path(RELATIVE_PATH <path\-var> [BASE_DIRECTORY <input>] |
| [OUTPUT_VARIABLE <out\-var>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Modifies \fB<path\-var>\fP to make it relative to the \fBBASE_DIRECTORY\fP argument. |
| If \fBBASE_DIRECTORY\fP is not specified, the default base directory will be |
| \fBCMAKE_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 |
| .nf |
| .ft C |
| cmake_path(ABSOLUTE_PATH <path\-var> [BASE_DIRECTORY <input>] [NORMALIZE] |
| [OUTPUT_VARIABLE <out\-var>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If \fB<path\-var>\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 |
| \fBCMAKE_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 |
| \fBfile(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 |
| .nf |
| .ft C |
| cmake_path(NATIVE_PATH <path\-var> [NORMALIZE] <out\-var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Converts a cmake\-style \fB<path\-var>\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 |
| .nf |
| .ft C |
| cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out\-var> [NORMALIZE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Converts a native \fB<input>\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<out\-var>\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 |
| .nf |
| .ft C |
| cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out\-var> [NORMALIZE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Converts a cmake\-style \fB<input>\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<out\-var>\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 |
| .nf |
| .ft C |
| set(paths "/a/b/c" "/x/y/z") |
| cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths) |
| message("Native path list is \e"${native_paths}\e"") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Output on Windows: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Native path list is "\ea\eb\ec;\ex\ey\ez" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Output on all other platforms: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Native path list is "/a/b/c:/x/y/z" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Hashing |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_path(HASH <path\-var> <out\-var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Compute a hash value of \fB<path\-var>\fP such that for two paths \fBp1\fP and |
| \fBp2\fP that compare equal (COMPARE ... EQUAL), 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 \fBcmake\-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<NNNN>\fP where \fB<NNNN>\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 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_policy(VERSION <min>[...<max>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.12: The optional \fB<max>\fP version. |
| |
| .sp |
| \fB<min>\fP and the optional \fB<max>\fP are each CMake versions of the form |
| \fBmajor.minor[.patch[.tweak]]\fP, and the \fB\&...\fP is literal. The \fB<min>\fP |
| version must be at least \fB2.4\fP and at most the running version of CMake. |
| The \fB<max>\fP version, if specified, must be at least the \fB<min>\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\&...<max>\fP part being ignored and |
| preserving the pre\-3.12 behavior of basing policies on \fB<min>\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<min>\fP (or \fB<max>\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 |
| \fBCMAKE_POLICY_DEFAULT_CMP<NNNN>\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 \fBcmake_minimum_required(VERSION)\fP |
| command implicitly calls \fBcmake_policy(VERSION)\fP too. |
| .SS Setting Policies Explicitly |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_policy(SET CMP<NNNN> NEW) |
| cmake_policy(SET CMP<NNNN> OLD) |
| .ft P |
| .fi |
| .UNINDENT |
| .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 |
| \fBdeprecated by definition\fP |
| and may be removed in a future version of CMake. |
| .UNINDENT |
| .UNINDENT |
| .SS Checking Policy Settings |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_policy(GET CMP<NNNN> <variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Check whether a given policy is set to \fBOLD\fP or \fBNEW\fP behavior. |
| The output \fB<variable>\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 \fBinclude()\fP and \fBfind_package()\fP commands |
| except when invoked with the \fBNO_POLICY_SCOPE\fP option |
| (see also policy \fBCMP0011\fP). |
| The \fBcmake_policy\fP command provides an interface to manage custom |
| entries on the policy stack: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_policy(PUSH) |
| cmake_policy(POP) |
| .ft P |
| .fi |
| .UNINDENT |
| .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 \fBcmake_minimum_required(VERSION)\fP, |
| \fBcmake_policy(VERSION)\fP, or \fBcmake_policy(SET)\fP commands |
| influence only the current top of the policy stack. |
| .sp |
| Commands created by the \fBfunction()\fP and \fBmacro()\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 configure_file |
| .sp |
| Copy a file to another location and modify its contents. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| configure_file(<input> <output> |
| [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS | |
| FILE_PERMISSIONS <permissions>...] |
| [COPYONLY] [ESCAPE_QUOTES] [@ONLY] |
| [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Copies an \fB<input>\fP file to an \fB<output>\fP file and substitutes |
| variable values referenced as \fB@VAR@\fP or \fB${VAR}\fP in the input |
| file content. Each variable reference will be replaced with the |
| current value of the variable, or the empty string if the variable |
| is not defined. Furthermore, input lines of the form |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #cmakedefine VAR ... |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will be replaced with either |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #define VAR ... |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| or |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| /* #undef VAR */ |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| depending on whether \fBVAR\fP is set in CMake to any value not considered |
| a false constant by the \fBif()\fP command. The "..." content on the |
| line after the variable name, if any, is processed as above. |
| .sp |
| Unlike lines of the form \fB#cmakedefine VAR ...\fP, in lines of the form |
| \fB#cmakedefine01 VAR\fP, \fBVAR\fP itself will expand to \fBVAR 0\fP or \fBVAR 1\fP |
| rather than being assigned the value \fB\&...\fP\&. Therefore, input lines of the form |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #cmakedefine01 VAR |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will be replaced with either |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #define VAR 0 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| or |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #define VAR 1 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Input lines of the form \fB#cmakedefine01 VAR ...\fP will expand |
| as \fB#cmakedefine01 VAR ... 0\fP or \fB#cmakedefine01 VAR ... 0\fP, |
| which may lead to undefined behavior. |
| .sp |
| New in version 3.10: The result lines (with the exception of the \fB#undef\fP comments) can be |
| indented using spaces and/or tabs between the \fB#\fP character |
| and the \fBcmakedefine\fP or \fBcmakedefine01\fP words. This whitespace |
| indentation will be preserved in the output lines: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # cmakedefine VAR |
| # cmakedefine01 VAR |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will be replaced, if \fBVAR\fP is defined, with |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # define VAR |
| # define VAR 1 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| |
| .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. |
| .sp |
| The arguments are: |
| .INDENT 0.0 |
| .TP |
| .B \fB<input>\fP |
| Path to the input file. A relative path is treated with respect to |
| the value of \fBCMAKE_CURRENT_SOURCE_DIR\fP\&. The input path |
| must be a file, not a directory. |
| .TP |
| .B \fB<output>\fP |
| Path to the output file or directory. A relative path is treated |
| with respect to the value of \fBCMAKE_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 <permissions>...\fP |
| New in version 3.20. |
| |
| .sp |
| Ignore the input file\(aqs permissions and use the specified \fB<permissions>\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 <style>\fP |
| Specify the newline style for the output file. Specify |
| \fBUNIX\fP or \fBLF\fP for \fB\en\fP newlines, or specify |
| \fBDOS\fP, \fBWIN32\fP, or \fBCRLF\fP for \fB\er\en\fP newlines. |
| This option may not be used with \fBCOPYONLY\fP\&. |
| .UNINDENT |
| .SS Example |
| .sp |
| Consider a source tree containing a \fBfoo.h.in\fP file: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #cmakedefine FOO_ENABLE |
| #cmakedefine FOO_STRING "@FOO_STRING@" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| An adjacent \fBCMakeLists.txt\fP may use \fBconfigure_file\fP to |
| configure the header: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| option(FOO_ENABLE "Enable Foo" ON) |
| if(FOO_ENABLE) |
| set(FOO_STRING "foo") |
| endif() |
| configure_file(foo.h.in foo.h @ONLY) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This creates a \fBfoo.h\fP in the build directory corresponding to |
| this source directory. If the \fBFOO_ENABLE\fP option is on, the |
| configured file will contain: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| #define FOO_ENABLE |
| #define FOO_STRING "foo" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Otherwise it will contain: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| /* #undef FOO_ENABLE */ |
| /* #undef FOO_STRING */ |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| One may then use the \fBinclude_directories()\fP command to |
| specify the output directory as an include directory: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include_directories(${CMAKE_CURRENT_BINARY_DIR}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| so that sources may include the header as \fB#include <foo.h>\fP\&. |
| .SS continue |
| .sp |
| New in version 3.2. |
| |
| .sp |
| Continue to the top of enclosing foreach or while loop. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| continue() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBcontinue\fP command allows a cmake script to abort the rest of a block |
| in a \fBforeach()\fP or \fBwhile()\fP loop, and start at the top of |
| the next iteration. |
| .sp |
| See also the \fBbreak()\fP command. |
| .SS else |
| .sp |
| Starts the else portion of an if block. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| else([<condition>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| See the \fBif()\fP command. |
| .SS elseif |
| .sp |
| Starts an elseif portion of an if block. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| elseif(<condition>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| See the \fBif()\fP command, especially for the syntax and logic |
| of the \fB<condition>\fP\&. |
| .SS endforeach |
| .sp |
| Ends a list of commands in a foreach block. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| endforeach([<loop_var>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| See the \fBforeach()\fP command. |
| .sp |
| The optional \fB<loop_var>\fP argument is supported for backward compatibility |
| only. If used it must be a verbatim repeat of the \fB<loop_var>\fP argument of |
| the opening \fBforeach\fP clause. |
| .SS endfunction |
| .sp |
| Ends a list of commands in a function block. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| endfunction([<name>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| See the \fBfunction()\fP command. |
| .sp |
| The optional \fB<name>\fP argument is supported for backward compatibility |
| only. If used it must be a verbatim repeat of the \fB<name>\fP argument |
| of the opening \fBfunction\fP command. |
| .SS endif |
| .sp |
| Ends a list of commands in an if block. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| endif([<condition>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| See the \fBif()\fP command. |
| .sp |
| The optional \fB<condition>\fP argument is supported for backward compatibility |
| only. If used it must be a verbatim repeat of the argument of the opening |
| \fBif\fP clause. |
| .SS endmacro |
| .sp |
| Ends a list of commands in a macro block. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| endmacro([<name>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| See the \fBmacro()\fP command. |
| .sp |
| The optional \fB<name>\fP argument is supported for backward compatibility |
| only. If used it must be a verbatim repeat of the \fB<name>\fP argument |
| of the opening \fBmacro\fP command. |
| .SS endwhile |
| .sp |
| Ends a list of commands in a while block. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| endwhile([<condition>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| See the \fBwhile()\fP command. |
| .sp |
| The optional \fB<condition>\fP argument is supported for backward compatibility |
| only. If used it must be a verbatim repeat of the argument of the opening |
| \fBwhile\fP clause. |
| .SS execute_process |
| .sp |
| Execute one or more child processes. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| execute_process(COMMAND <cmd1> [<arguments>] |
| [COMMAND <cmd2> [<arguments>]]... |
| [WORKING_DIRECTORY <directory>] |
| [TIMEOUT <seconds>] |
| [RESULT_VARIABLE <variable>] |
| [RESULTS_VARIABLE <variable>] |
| [OUTPUT_VARIABLE <variable>] |
| [ERROR_VARIABLE <variable>] |
| [INPUT_FILE <file>] |
| [OUTPUT_FILE <file>] |
| [ERROR_FILE <file>] |
| [OUTPUT_QUIET] |
| [ERROR_QUIET] |
| [COMMAND_ECHO <where>] |
| [OUTPUT_STRIP_TRAILING_WHITESPACE] |
| [ERROR_STRIP_TRAILING_WHITESPACE] |
| [ENCODING <name>] |
| [ECHO_OUTPUT_VARIABLE] |
| [ECHO_ERROR_VARIABLE] |
| [COMMAND_ERROR_IS_FATAL <ANY|LAST>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Runs the given sequence of one or more commands. |
| .sp |
| Commands are executed concurrently as a pipeline, with the standard |
| output of each process piped to the standard input of the next. |
| A single standard error pipe is used for all processes. |
| .sp |
| Options: |
| .INDENT 0.0 |
| .TP |
| .B \fBCOMMAND\fP |
| A child process command line. |
| .sp |
| CMake executes the child process using operating system APIs directly. |
| All arguments are passed VERBATIM to the child process. |
| No intermediate shell is used, so shell operators such as \fB>\fP |
| are treated as normal arguments. |
| (Use the \fBINPUT_*\fP, \fBOUTPUT_*\fP, and \fBERROR_*\fP options to |
| redirect stdin, stdout, and stderr.) |
| .sp |
| If a sequential execution of multiple commands is required, use multiple |
| \fI\%execute_process()\fP calls with a single \fBCOMMAND\fP argument. |
| .TP |
| .B \fBWORKING_DIRECTORY\fP |
| The named directory will be set as the current working directory of |
| the child processes. |
| .TP |
| .B \fBTIMEOUT\fP |
| After the specified number of seconds (fractions allowed), all unfinished |
| child processes will be terminated, and the \fBRESULT_VARIABLE\fP will be |
| set to a string mentioning the "timeout". |
| .TP |
| .B \fBRESULT_VARIABLE\fP |
| The variable will be set to contain the result of last child process. |
| This will be an integer return code from the last child or a string |
| describing an error condition. |
| .TP |
| .B \fBRESULTS_VARIABLE <variable>\fP |
| New in version 3.10. |
| |
| .sp |
| The variable will be set to contain the result of all processes as a |
| semicolon\-separated list, in order of the |
| given \fBCOMMAND\fP arguments. Each entry will be an integer return code |
| from the corresponding child or a string describing an error condition. |
| .TP |
| .B \fBOUTPUT_VARIABLE\fP, \fBERROR_VARIABLE\fP |
| The variable named will be set with the contents of the standard output |
| and standard error pipes, respectively. If the same variable is named |
| for both pipes their output will be merged in the order produced. |
| .TP |
| .B \fBINPUT_FILE, OUTPUT_FILE\fP, \fBERROR_FILE\fP |
| The file named will be attached to the standard input of the first |
| process, standard output of the last process, or standard error of |
| all processes, respectively. |
| .sp |
| New in version 3.3: If the same file is named for both output and error then it will be used |
| for both. |
| |
| .TP |
| .B \fBOUTPUT_QUIET\fP, \fBERROR_QUIET\fP |
| The standard output or standard error results will be quietly ignored. |
| .TP |
| .B \fBCOMMAND_ECHO <where>\fP |
| New in version 3.15. |
| |
| .sp |
| The command being run will be echo\(aqed to \fB<where>\fP with \fB<where>\fP |
| being set to one of \fBSTDERR\fP, \fBSTDOUT\fP or \fBNONE\fP\&. |
| See the \fBCMAKE_EXECUTE_PROCESS_COMMAND_ECHO\fP variable for a way |
| to control the default behavior when this option is not present. |
| .TP |
| .B \fBENCODING <name>\fP |
| New in version 3.8. |
| |
| .sp |
| On Windows, the encoding that is used to decode output from the process. |
| Ignored on other platforms. |
| Valid encoding names are: |
| .INDENT 7.0 |
| .TP |
| .B \fBNONE\fP |
| Perform no decoding. This assumes that the process output is encoded |
| in the same way as CMake\(aqs internal encoding (UTF\-8). |
| This is the default. |
| .TP |
| .B \fBAUTO\fP |
| Use the current active console\(aqs codepage or if that isn\(aqt |
| available then use ANSI. |
| .TP |
| .B \fBANSI\fP |
| Use the ANSI codepage. |
| .TP |
| .B \fBOEM\fP |
| Use the original equipment manufacturer (OEM) code page. |
| .TP |
| .B \fBUTF8\fP or \fBUTF\-8\fP |
| Use the UTF\-8 codepage. |
| .sp |
| New in version 3.11: Accept \fBUTF\-8\fP spelling for consistency with the |
| \fI\%UTF\-8 RFC\fP naming convention. |
| |
| .UNINDENT |
| .TP |
| .B \fBECHO_OUTPUT_VARIABLE\fP, \fBECHO_ERROR_VARIABLE\fP |
| New in version 3.18. |
| |
| .sp |
| The standard output or standard error will not be exclusively redirected to |
| the configured variables. |
| .sp |
| The output will be duplicated, it will be sent into the configured variables |
| and also on standard output or standard error. |
| .sp |
| This is analogous to the \fBtee\fP Unix command. |
| .TP |
| .B \fBCOMMAND_ERROR_IS_FATAL <ANY|LAST>\fP |
| New in version 3.19. |
| |
| .sp |
| The option following \fBCOMMAND_ERROR_IS_FATAL\fP determines the behavior when |
| an error is encountered: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| \fBANY\fP |
| If any of the commands in the list of commands fail, the |
| \fBexecute_process()\fP command halts with an error. |
| .sp |
| \fBLAST\fP |
| If the last command in the list of commands fails, the |
| \fBexecute_process()\fP command halts with an error. Commands earlier in the |
| list will not cause a fatal error. |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If more than one \fBOUTPUT_*\fP or \fBERROR_*\fP option is given for the |
| same pipe the precedence is not specified. |
| If no \fBOUTPUT_*\fP or \fBERROR_*\fP options are given the output will |
| be shared with the corresponding pipes of the CMake process itself. |
| .sp |
| The \fI\%execute_process()\fP command is a newer more powerful version of |
| \fBexec_program()\fP, but the old command has been kept for compatibility. |
| Both commands run while CMake is processing the project prior to build |
| system generation. Use \fBadd_custom_target()\fP and |
| \fBadd_custom_command()\fP to create custom commands that run at |
| build time. |
| .SS file |
| .sp |
| File manipulation command. |
| .sp |
| This command is dedicated to file and path manipulation requiring access to the |
| filesystem. |
| .sp |
| For other path manipulation, handling only syntactic aspects, have a look at |
| \fBcmake_path()\fP command. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The sub\-commands \fI\%RELATIVE_PATH\fP, \fI\%TO_CMAKE_PATH\fP and \fI\%TO_NATIVE_PATH\fP has |
| been superseded, respectively, by sub\-commands |
| RELATIVE_PATH, |
| CONVERT ... TO_CMAKE_PATH_LIST and |
| CONVERT ... TO_NATIVE_PATH_LIST of |
| \fBcmake_path()\fP command. |
| .UNINDENT |
| .UNINDENT |
| .SS Synopsis |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \fI\%Reading\fP |
| file(\fI\%READ\fP <filename> <out\-var> [...]) |
| file(\fI\%STRINGS\fP <filename> <out\-var> [...]) |
| file(\fI\%<HASH>\fP <filename> <out\-var>) |
| file(\fI\%TIMESTAMP\fP <filename> <out\-var> [...]) |
| file(\fI\%GET_RUNTIME_DEPENDENCIES\fP [...]) |
| |
| \fI\%Writing\fP |
| file({\fI\%WRITE\fP | \fI\%APPEND\fP} <filename> <content>...) |
| file({\fI\%TOUCH\fP | \fI\%TOUCH_NOCREATE\fP} [<file>...]) |
| file(\fI\%GENERATE\fP OUTPUT <output\-file> [...]) |
| file(\fI\%CONFIGURE\fP OUTPUT <output\-file> CONTENT <content> [...]) |
| |
| \fI\%Filesystem\fP |
| file({\fI\%GLOB\fP | \fI\%GLOB_RECURSE\fP} <out\-var> [...] [<globbing\-expr>...]) |
| file(\fI\%MAKE_DIRECTORY\fP [<dir>...]) |
| file({\fI\%REMOVE\fP | \fI\%REMOVE_RECURSE\fP } [<files>...]) |
| file(\fI\%RENAME\fP <oldname> <newname> [...]) |
| file(\fI\%COPY_FILE\fP <oldname> <newname> [...]) |
| file({\fI\%COPY\fP | \fI\%INSTALL\fP} <file>... DESTINATION <dir> [...]) |
| file(\fI\%SIZE\fP <filename> <out\-var>) |
| file(\fI\%READ_SYMLINK\fP <linkname> <out\-var>) |
| file(\fI\%CREATE_LINK\fP <original> <linkname> [...]) |
| file(\fI\%CHMOD\fP <files>... <directories>... PERMISSIONS <permissions>... [...]) |
| file(\fI\%CHMOD_RECURSE\fP <files>... <directories>... PERMISSIONS <permissions>... [...]) |
| |
| \fI\%Path Conversion\fP |
| file(\fI\%REAL_PATH\fP <path> <out\-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE]) |
| file(\fI\%RELATIVE_PATH\fP <out\-var> <directory> <file>) |
| file({\fI\%TO_CMAKE_PATH\fP | \fI\%TO_NATIVE_PATH\fP} <path> <out\-var>) |
| |
| \fI\%Transfer\fP |
| file(\fI\%DOWNLOAD\fP <url> [<file>] [...]) |
| file(\fI\%UPLOAD\fP <file> <url> [...]) |
| |
| \fI\%Locking\fP |
| file(\fI\%LOCK\fP <path> [...]) |
| |
| \fI\%Archiving\fP |
| file(\fI\%ARCHIVE_CREATE\fP OUTPUT <archive> PATHS <paths>... [...]) |
| file(\fI\%ARCHIVE_EXTRACT\fP INPUT <archive> [...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Reading |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(READ <filename> <variable> |
| [OFFSET <offset>] [LIMIT <max\-in>] [HEX]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Read content from a file called \fB<filename>\fP and store it in a |
| \fB<variable>\fP\&. Optionally start from the given \fB<offset>\fP and |
| read at most \fB<max\-in>\fP bytes. The \fBHEX\fP option causes data to |
| be converted to a hexadecimal representation (useful for binary data). If the |
| \fBHEX\fP option is specified, letters in the output (\fBa\fP through \fBf\fP) are in |
| lowercase. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(STRINGS <filename> <variable> [<options>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Parse a list of ASCII strings from \fB<filename>\fP and store it in |
| \fB<variable>\fP\&. Binary data in the file are ignored. Carriage return |
| (\fB\er\fP, CR) characters are ignored. The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBLENGTH_MAXIMUM <max\-len>\fP |
| Consider only strings of at most a given length. |
| .TP |
| .B \fBLENGTH_MINIMUM <min\-len>\fP |
| Consider only strings of at least a given length. |
| .TP |
| .B \fBLIMIT_COUNT <max\-num>\fP |
| Limit the number of distinct strings to be extracted. |
| .TP |
| .B \fBLIMIT_INPUT <max\-in>\fP |
| Limit the number of input bytes to read from the file. |
| .TP |
| .B \fBLIMIT_OUTPUT <max\-out>\fP |
| Limit the number of total bytes to store in the \fB<variable>\fP\&. |
| .TP |
| .B \fBNEWLINE_CONSUME\fP |
| Treat newline characters (\fB\en\fP, LF) as part of string content |
| instead of terminating at them. |
| .TP |
| .B \fBNO_HEX_CONVERSION\fP |
| Intel Hex and Motorola S\-record files are automatically converted to |
| binary while reading unless this option is given. |
| .TP |
| .B \fBREGEX <regex>\fP |
| Consider only strings that match the given regular expression, |
| as described under string(REGEX)\&. |
| .TP |
| .B \fBENCODING <encoding\-type>\fP |
| New in version 3.1. |
| |
| .sp |
| Consider strings of a given encoding. Currently supported encodings are: |
| \fBUTF\-8\fP, \fBUTF\-16LE\fP, \fBUTF\-16BE\fP, \fBUTF\-32LE\fP, \fBUTF\-32BE\fP\&. |
| If the \fBENCODING\fP option is not provided and the file has a Byte Order Mark, |
| the \fBENCODING\fP option will be defaulted to respect the Byte Order Mark. |
| .sp |
| New in version 3.2: Added the \fBUTF\-16LE\fP, \fBUTF\-16BE\fP, \fBUTF\-32LE\fP, \fBUTF\-32BE\fP encodings. |
| |
| .UNINDENT |
| .sp |
| For example, the code |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(STRINGS myfile.txt myfile) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| stores a list in the variable \fBmyfile\fP in which each item is a line |
| from the input file. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(<HASH> <filename> <variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Compute a cryptographic hash of the content of \fB<filename>\fP and |
| store it in a \fB<variable>\fP\&. The supported \fB<HASH>\fP algorithm names |
| are those listed by the string(<HASH>) |
| command. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(TIMESTAMP <filename> <variable> [<format>] [UTC]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Compute a string representation of the modification time of \fB<filename>\fP |
| and store it in \fB<variable>\fP\&. Should the command be unable to obtain a |
| timestamp variable will be set to the empty string (""). |
| .sp |
| See the \fBstring(TIMESTAMP)\fP command for documentation of |
| the \fB<format>\fP and \fBUTC\fP options. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(GET_RUNTIME_DEPENDENCIES |
| [RESOLVED_DEPENDENCIES_VAR <deps_var>] |
| [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>] |
| [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>] |
| [EXECUTABLES [<executable_files>...]] |
| [LIBRARIES [<library_files>...]] |
| [MODULES [<module_files>...]] |
| [DIRECTORIES [<directories>...]] |
| [BUNDLE_EXECUTABLE <bundle_executable_file>] |
| [PRE_INCLUDE_REGEXES [<regexes>...]] |
| [PRE_EXCLUDE_REGEXES [<regexes>...]] |
| [POST_INCLUDE_REGEXES [<regexes>...]] |
| [POST_EXCLUDE_REGEXES [<regexes>...]] |
| [POST_INCLUDE_FILES [<files>...]] |
| [POST_EXCLUDE_FILES [<files>...]] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Recursively get the list of libraries depended on by the given files. |
| .sp |
| Please note that this sub\-command is not intended to be used in project mode. |
| It is intended for use at install time, either from code generated by the |
| \fBinstall(RUNTIME_DEPENDENCY_SET)\fP command, or from code provided by |
| the project via \fBinstall(CODE)\fP or \fBinstall(SCRIPT)\fP\&. |
| For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install(CODE [[ |
| file(GET_RUNTIME_DEPENDENCIES |
| # ... |
| ) |
| ]]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The arguments are as follows: |
| .INDENT 0.0 |
| .TP |
| .B \fBRESOLVED_DEPENDENCIES_VAR <deps_var>\fP |
| Name of the variable in which to store the list of resolved dependencies. |
| .TP |
| .B \fBUNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>\fP |
| Name of the variable in which to store the list of unresolved dependencies. |
| If this variable is not specified, and there are any unresolved dependencies, |
| an error is issued. |
| .TP |
| .B \fBCONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>\fP |
| Variable prefix in which to store conflicting dependency information. |
| Dependencies are conflicting if two files with the same name are found in |
| two different directories. The list of filenames that conflict are stored in |
| \fB<conflicting_deps_prefix>_FILENAMES\fP\&. For each filename, the list of paths |
| that were found for that filename are stored in |
| \fB<conflicting_deps_prefix>_<filename>\fP\&. |
| .TP |
| .B \fBEXECUTABLES <executable_files>\fP |
| List of executable files to read for dependencies. These are executables that |
| are typically created with \fBadd_executable()\fP, but they do not have to |
| be created by CMake. On Apple platforms, the paths to these files determine |
| the value of \fB@executable_path\fP when recursively resolving the libraries. |
| Specifying any kind of library (\fBSTATIC\fP, \fBMODULE\fP, or \fBSHARED\fP) here |
| will result in undefined behavior. |
| .TP |
| .B \fBLIBRARIES <library_files>\fP |
| List of library files to read for dependencies. These are libraries that are |
| typically created with \fBadd_library(SHARED)\fP, but they do not have |
| to be created by CMake. Specifying \fBSTATIC\fP libraries, \fBMODULE\fP |
| libraries, or executables here will result in undefined behavior. |
| .TP |
| .B \fBMODULES <module_files>\fP |
| List of loadable module files to read for dependencies. These are modules |
| that are typically created with \fBadd_library(MODULE)\fP, but they do |
| not have to be created by CMake. They are typically used by calling |
| \fBdlopen()\fP at runtime rather than linked at link time with \fBld \-l\fP\&. |
| Specifying \fBSTATIC\fP libraries, \fBSHARED\fP libraries, or executables here |
| will result in undefined behavior. |
| .TP |
| .B \fBDIRECTORIES <directories>\fP |
| List of additional directories to search for dependencies. On Linux |
| platforms, these directories are searched if the dependency is not found in |
| any of the other usual paths. If it is found in such a directory, a warning |
| is issued, because it means that the file is incomplete (it does not list all |
| of the directories that contain its dependencies). On Windows platforms, |
| these directories are searched if the dependency is not found in any of the |
| other search paths, but no warning is issued, because searching other paths |
| is a normal part of Windows dependency resolution. On Apple platforms, this |
| argument has no effect. |
| .TP |
| .B \fBBUNDLE_EXECUTABLE <bundle_executable_file>\fP |
| Executable to treat as the "bundle executable" when resolving libraries. On |
| Apple platforms, this argument determines the value of \fB@executable_path\fP |
| when recursively resolving libraries for \fBLIBRARIES\fP and \fBMODULES\fP files. |
| It has no effect on \fBEXECUTABLES\fP files. On other platforms, it has no |
| effect. This is typically (but not always) one of the executables in the |
| \fBEXECUTABLES\fP argument which designates the "main" executable of the |
| package. |
| .UNINDENT |
| .sp |
| The following arguments specify filters for including or excluding libraries to |
| be resolved. See below for a full description of how they work. |
| .INDENT 0.0 |
| .TP |
| .B \fBPRE_INCLUDE_REGEXES <regexes>\fP |
| List of pre\-include regexes through which to filter the names of |
| not\-yet\-resolved dependencies. |
| .TP |
| .B \fBPRE_EXCLUDE_REGEXES <regexes>\fP |
| List of pre\-exclude regexes through which to filter the names of |
| not\-yet\-resolved dependencies. |
| .TP |
| .B \fBPOST_INCLUDE_REGEXES <regexes>\fP |
| List of post\-include regexes through which to filter the names of resolved |
| dependencies. |
| .TP |
| .B \fBPOST_EXCLUDE_REGEXES <regexes>\fP |
| List of post\-exclude regexes through which to filter the names of resolved |
| dependencies. |
| .TP |
| .B \fBPOST_INCLUDE_FILES <files>\fP |
| New in version 3.21. |
| |
| .sp |
| List of post\-include filenames through which to filter the names of resolved |
| dependencies. Symlinks are resolved when attempting to match these filenames. |
| .TP |
| .B \fBPOST_EXCLUDE_FILES <files>\fP |
| New in version 3.21. |
| |
| .sp |
| List of post\-exclude filenames through which to filter the names of resolved |
| dependencies. Symlinks are resolved when attempting to match these filenames. |
| .UNINDENT |
| .sp |
| These arguments can be used to exclude unwanted system libraries when |
| resolving the dependencies, or to include libraries from a specific |
| directory. The filtering works as follows: |
| .INDENT 0.0 |
| .IP 1. 3 |
| If the not\-yet\-resolved dependency matches any of the |
| \fBPRE_INCLUDE_REGEXES\fP, steps 2 and 3 are skipped, and the dependency |
| resolution proceeds to step 4. |
| .IP 2. 3 |
| If the not\-yet\-resolved dependency matches any of the |
| \fBPRE_EXCLUDE_REGEXES\fP, dependency resolution stops for that dependency. |
| .IP 3. 3 |
| Otherwise, dependency resolution proceeds. |
| .IP 4. 3 |
| \fBfile(GET_RUNTIME_DEPENDENCIES)\fP searches for the dependency according to |
| the linking rules of the platform (see below). |
| .IP 5. 3 |
| If the dependency is found, and its full path matches one of the |
| \fBPOST_INCLUDE_REGEXES\fP or \fBPOST_INCLUDE_FILES\fP, the full path is added |
| to the resolved dependencies, and \fBfile(GET_RUNTIME_DEPENDENCIES)\fP |
| recursively resolves that library\(aqs own dependencies. Otherwise, resolution |
| proceeds to step 6. |
| .IP 6. 3 |
| If the dependency is found, but its full path matches one of the |
| \fBPOST_EXCLUDE_REGEXES\fP or \fBPOST_EXCLUDE_FILES\fP, it is not added to the |
| resolved dependencies, and dependency resolution stops for that dependency. |
| .IP 7. 3 |
| If the dependency is found, and its full path does not match either |
| \fBPOST_INCLUDE_REGEXES\fP, \fBPOST_INCLUDE_FILES\fP, \fBPOST_EXCLUDE_REGEXES\fP, |
| or \fBPOST_EXCLUDE_FILES\fP, the full path is added to the resolved |
| dependencies, and \fBfile(GET_RUNTIME_DEPENDENCIES)\fP recursively resolves |
| that library\(aqs own dependencies. |
| .UNINDENT |
| .sp |
| Different platforms have different rules for how dependencies are resolved. |
| These specifics are described here. |
| .sp |
| On Linux platforms, library resolution works as follows: |
| .INDENT 0.0 |
| .IP 1. 3 |
| If the depending file does not have any \fBRUNPATH\fP entries, and the library |
| exists in one of the depending file\(aqs \fBRPATH\fP entries, or its parents\(aq, in |
| that order, the dependency is resolved to that file. |
| .IP 2. 3 |
| Otherwise, if the depending file has any \fBRUNPATH\fP entries, and the |
| library exists in one of those entries, the dependency is resolved to that |
| file. |
| .IP 3. 3 |
| Otherwise, if the library exists in one of the directories listed by |
| \fBldconfig\fP, the dependency is resolved to that file. |
| .IP 4. 3 |
| Otherwise, if the library exists in one of the \fBDIRECTORIES\fP entries, the |
| dependency is resolved to that file. In this case, a warning is issued, |
| because finding a file in one of the \fBDIRECTORIES\fP means that the |
| depending file is not complete (it does not list all the directories from |
| which it pulls dependencies). |
| .IP 5. 3 |
| Otherwise, the dependency is unresolved. |
| .UNINDENT |
| .sp |
| On Windows platforms, library resolution works as follows: |
| .INDENT 0.0 |
| .IP 1. 3 |
| The dependent DLL name is converted to lowercase. Windows DLL names are |
| case\-insensitive, and some linkers mangle the case of the DLL dependency |
| names. However, this makes it more difficult for \fBPRE_INCLUDE_REGEXES\fP, |
| \fBPRE_EXCLUDE_REGEXES\fP, \fBPOST_INCLUDE_REGEXES\fP, and |
| \fBPOST_EXCLUDE_REGEXES\fP to properly filter DLL names \- every regex would |
| have to check for both uppercase and lowercase letters. For example: |
| .INDENT 3.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(GET_RUNTIME_DEPENDENCIES |
| # ... |
| PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\e\e.[Dd][Ll][Ll]$" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Converting the DLL name to lowercase allows the regexes to only match |
| lowercase names, thus simplifying the regex. For example: |
| .INDENT 3.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(GET_RUNTIME_DEPENDENCIES |
| # ... |
| PRE_INCLUDE_REGEXES "^mylibrary\e\e.dll$" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This regex will match \fBmylibrary.dll\fP regardless of how it is cased, |
| either on disk or in the depending file. (For example, it will match |
| \fBmylibrary.dll\fP, \fBMyLibrary.dll\fP, and \fBMYLIBRARY.DLL\fP\&.) |
| .sp |
| Please note that the directory portion of any resolved DLLs retains its |
| casing and is not converted to lowercase. Only the filename portion is |
| converted. |
| .IP 2. 3 |
| (\fBNot yet implemented\fP) If the depending file is a Windows Store app, and |
| the dependency is listed as a dependency in the application\(aqs package |
| manifest, the dependency is resolved to that file. |
| .IP 3. 3 |
| Otherwise, if the library exists in the same directory as the depending |
| file, the dependency is resolved to that file. |
| .IP 4. 3 |
| Otherwise, if the library exists in either the operating system\(aqs |
| \fBsystem32\fP directory or the \fBWindows\fP directory, in that order, the |
| dependency is resolved to that file. |
| .IP 5. 3 |
| Otherwise, if the library exists in one of the directories specified by |
| \fBDIRECTORIES\fP, in the order they are listed, the dependency is resolved to |
| that file. In this case, a warning is not issued, because searching other |
| directories is a normal part of Windows library resolution. |
| .IP 6. 3 |
| Otherwise, the dependency is unresolved. |
| .UNINDENT |
| .sp |
| On Apple platforms, library resolution works as follows: |
| .INDENT 0.0 |
| .IP 1. 3 |
| If the dependency starts with \fB@executable_path/\fP, and an \fBEXECUTABLES\fP |
| argument is in the process of being resolved, and replacing |
| \fB@executable_path/\fP with the directory of the executable yields an |
| existing file, the dependency is resolved to that file. |
| .IP 2. 3 |
| Otherwise, if the dependency starts with \fB@executable_path/\fP, and there is |
| a \fBBUNDLE_EXECUTABLE\fP argument, and replacing \fB@executable_path/\fP with |
| the directory of the bundle executable yields an existing file, the |
| dependency is resolved to that file. |
| .IP 3. 3 |
| Otherwise, if the dependency starts with \fB@loader_path/\fP, and replacing |
| \fB@loader_path/\fP with the directory of the depending file yields an |
| existing file, the dependency is resolved to that file. |
| .IP 4. 3 |
| Otherwise, if the dependency starts with \fB@rpath/\fP, and replacing |
| \fB@rpath/\fP with one of the \fBRPATH\fP entries of the depending file yields |
| an existing file, the dependency is resolved to that file. Note that |
| \fBRPATH\fP entries that start with \fB@executable_path/\fP or \fB@loader_path/\fP |
| also have these items replaced with the appropriate path. |
| .IP 5. 3 |
| Otherwise, if the dependency is an absolute file that exists, the dependency |
| is resolved to that file. |
| .IP 6. 3 |
| Otherwise, the dependency is unresolved. |
| .UNINDENT |
| .sp |
| This function accepts several variables that determine which tool is used for |
| dependency resolution: |
| .INDENT 0.0 |
| .TP |
| .B CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM |
| Determines which operating system and executable format the files are built |
| for. This could be one of several values: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBlinux+elf\fP |
| .IP \(bu 2 |
| \fBwindows+pe\fP |
| .IP \(bu 2 |
| \fBmacos+macho\fP |
| .UNINDENT |
| .sp |
| If this variable is not specified, it is determined automatically by system |
| introspection. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL |
| Determines the tool to use for dependency resolution. It could be one of |
| several values, depending on the value of |
| \fI\%CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM\fP: |
| .TS |
| center; |
| |l|l|. |
| _ |
| T{ |
| \fBCMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM\fP |
| T} T{ |
| \fBCMAKE_GET_RUNTIME_DEPENDENCIES_TOOL\fP |
| T} |
| _ |
| T{ |
| \fBlinux+elf\fP |
| T} T{ |
| \fBobjdump\fP |
| T} |
| _ |
| T{ |
| \fBwindows+pe\fP |
| T} T{ |
| \fBdumpbin\fP |
| T} |
| _ |
| T{ |
| \fBwindows+pe\fP |
| T} T{ |
| \fBobjdump\fP |
| T} |
| _ |
| T{ |
| \fBmacos+macho\fP |
| T} T{ |
| \fBotool\fP |
| T} |
| _ |
| .TE |
| .sp |
| If this variable is not specified, it is determined automatically by system |
| introspection. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND |
| Determines the path to the tool to use for dependency resolution. This is the |
| actual path to \fBobjdump\fP, \fBdumpbin\fP, or \fBotool\fP\&. |
| .sp |
| If this variable is not specified, it is determined by the value of |
| \fBCMAKE_OBJDUMP\fP if set, else by system introspection. |
| .sp |
| New in version 3.18: Use \fBCMAKE_OBJDUMP\fP if set. |
| |
| .UNINDENT |
| .SS Writing |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(WRITE <filename> <content>...) |
| file(APPEND <filename> <content>...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Write \fB<content>\fP into a file called \fB<filename>\fP\&. If the file does |
| not exist, it will be created. If the file already exists, \fBWRITE\fP |
| mode will overwrite it and \fBAPPEND\fP mode will append to the end. |
| Any directories in the path specified by \fB<filename>\fP that do not |
| exist will be created. |
| .sp |
| If the file is a build input, use the \fBconfigure_file()\fP command |
| to update the file only when its content changes. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(TOUCH [<files>...]) |
| file(TOUCH_NOCREATE [<files>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Create a file with no content if it does not yet exist. If the file already |
| exists, its access and/or modification will be updated to the time when the |
| function call is executed. |
| .sp |
| Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file |
| does not exist it will be silently ignored. |
| .sp |
| With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be |
| modified. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(GENERATE OUTPUT output\-file |
| <INPUT input\-file|CONTENT content> |
| [CONDITION expression] [TARGET target] |
| [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS | |
| FILE_PERMISSIONS <permissions>...] |
| [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Generate an output file for each build configuration supported by the current |
| \fBCMake Generator\fP\&. Evaluate |
| \fBgenerator expressions\fP |
| from the input content to produce the output content. The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBCONDITION <condition>\fP |
| Generate the output file for a particular configuration only if |
| the condition is true. The condition must be either \fB0\fP or \fB1\fP |
| after evaluating generator expressions. |
| .TP |
| .B \fBCONTENT <content>\fP |
| Use the content given explicitly as input. |
| .TP |
| .B \fBINPUT <input\-file>\fP |
| Use the content from a given file as input. |
| .sp |
| Changed in version 3.10: A relative path is treated with respect to the value of |
| \fBCMAKE_CURRENT_SOURCE_DIR\fP\&. See policy \fBCMP0070\fP\&. |
| |
| .TP |
| .B \fBOUTPUT <output\-file>\fP |
| Specify the output file name to generate. Use generator expressions |
| such as \fB$<CONFIG>\fP to specify a configuration\-specific output file |
| name. Multiple configurations may generate the same output file only |
| if the generated content is identical. Otherwise, the \fB<output\-file>\fP |
| must evaluate to an unique name for each configuration. |
| .sp |
| Changed in version 3.10: A relative path (after evaluating generator expressions) is treated |
| with respect to the value of \fBCMAKE_CURRENT_BINARY_DIR\fP\&. |
| See policy \fBCMP0070\fP\&. |
| |
| .TP |
| .B \fBTARGET <target>\fP |
| New in version 3.19. |
| |
| .sp |
| Specify which target to use when evaluating generator expressions that |
| require a target for evaluation (e.g. \fB$<COMPILE_FEATURES:...>\fP, |
| \fB$<TARGET_PROPERTY:prop>\fP). |
| .TP |
| .B \fBNO_SOURCE_PERMISSIONS\fP |
| New in version 3.20. |
| |
| .sp |
| The generated 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 file permissions of the \fBINPUT\fP file to the generated 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. |
| It is an error to specify this option without \fBINPUT\fP\&. |
| .TP |
| .B \fBFILE_PERMISSIONS <permissions>...\fP |
| New in version 3.20. |
| |
| .sp |
| Use the specified permissions for the generated file. |
| .TP |
| .B \fBNEWLINE_STYLE <style>\fP |
| New in version 3.20. |
| |
| .sp |
| Specify the newline style for the generated file. Specify |
| \fBUNIX\fP or \fBLF\fP for \fB\en\fP newlines, or specify |
| \fBDOS\fP, \fBWIN32\fP, or \fBCRLF\fP for \fB\er\en\fP newlines. |
| .UNINDENT |
| .sp |
| Exactly one \fBCONTENT\fP or \fBINPUT\fP option must be given. A specific |
| \fBOUTPUT\fP file may be named by at most one invocation of \fBfile(GENERATE)\fP\&. |
| Generated files are modified and their timestamp updated on subsequent cmake |
| runs only if their content is changed. |
| .sp |
| Note also that \fBfile(GENERATE)\fP does not create the output file until the |
| generation phase. The output file will not yet have been written when the |
| \fBfile(GENERATE)\fP command returns, it is written only after processing all |
| of a project\(aqs \fBCMakeLists.txt\fP files. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(CONFIGURE OUTPUT output\-file |
| CONTENT content |
| [ESCAPE_QUOTES] [@ONLY] |
| [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.18. |
| |
| .sp |
| Generate an output file using the input given by \fBCONTENT\fP and substitute |
| variable values referenced as \fB@VAR@\fP or \fB${VAR}\fP contained therein. The |
| substitution rules behave the same as the \fBconfigure_file()\fP command. |
| In order to match \fBconfigure_file()\fP\(aqs behavior, generator expressions |
| are not supported for both \fBOUTPUT\fP and \fBCONTENT\fP\&. |
| .sp |
| The arguments are: |
| .INDENT 0.0 |
| .TP |
| .B \fBOUTPUT <output\-file>\fP |
| Specify the output file name to generate. A relative path is treated with |
| respect to the value of \fBCMAKE_CURRENT_BINARY_DIR\fP\&. |
| \fB<output\-file>\fP does not support generator expressions. |
| .TP |
| .B \fBCONTENT <content>\fP |
| Use the content given explicitly as input. |
| \fB<content>\fP does not support generator expressions. |
| .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 <style>\fP |
| Specify the newline style for the output file. Specify |
| \fBUNIX\fP or \fBLF\fP for \fB\en\fP newlines, or specify |
| \fBDOS\fP, \fBWIN32\fP, or \fBCRLF\fP for \fB\er\en\fP newlines. |
| .UNINDENT |
| .SS Filesystem |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(GLOB <variable> |
| [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] |
| [<globbing\-expressions>...]) |
| file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS] |
| [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] |
| [<globbing\-expressions>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Generate a list of files that match the \fB<globbing\-expressions>\fP and |
| store it into the \fB<variable>\fP\&. Globbing expressions are similar to |
| regular expressions, but much simpler. If \fBRELATIVE\fP flag is |
| specified, the results will be returned as relative paths to the given |
| path. |
| .sp |
| Changed in version 3.6: The results will be ordered lexicographically. |
| |
| .sp |
| On Windows and macOS, globbing is case\-insensitive even if the underlying |
| filesystem is case\-sensitive (both filenames and globbing expressions are |
| converted to lowercase before matching). On other platforms, globbing is |
| case\-sensitive. |
| .sp |
| New in version 3.3: By default \fBGLOB\fP lists directories \- directories are omitted in result if |
| \fBLIST_DIRECTORIES\fP is set to false. |
| |
| .sp |
| New in version 3.12: If the \fBCONFIGURE_DEPENDS\fP flag is specified, CMake will add logic |
| to the main build system check target to rerun the flagged \fBGLOB\fP commands |
| at build time. If any of the outputs change, CMake will regenerate the build |
| system. |
| |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| We do not recommend using GLOB to collect a list of source files from |
| your source tree. If no CMakeLists.txt file changes when a source is |
| added or removed then the generated build system cannot know when to |
| ask CMake to regenerate. |
| The \fBCONFIGURE_DEPENDS\fP flag may not work reliably on all generators, or if |
| a new generator is added in the future that cannot support it, projects using |
| it will be stuck. Even if \fBCONFIGURE_DEPENDS\fP works reliably, there is |
| still a cost to perform the check on every rebuild. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Examples of globbing expressions include: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| *.cxx \- match all files with extension cxx |
| *.vt? \- match all files with extension vta,...,vtz |
| f[3\-5].txt \- match files f3.txt, f4.txt, f5.txt |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBGLOB_RECURSE\fP mode will traverse all the subdirectories of the |
| matched directory and match the files. Subdirectories that are symlinks |
| are only traversed if \fBFOLLOW_SYMLINKS\fP is given or policy |
| \fBCMP0009\fP is not set to \fBNEW\fP\&. |
| .sp |
| New in version 3.3: By default \fBGLOB_RECURSE\fP omits directories from result list \- setting |
| \fBLIST_DIRECTORIES\fP to true adds directories to result list. |
| If \fBFOLLOW_SYMLINKS\fP is given or policy \fBCMP0009\fP is not set to |
| \fBNEW\fP then \fBLIST_DIRECTORIES\fP treats symlinks as directories. |
| |
| .sp |
| Examples of recursive globbing include: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| /dir/*.py \- match all python files in /dir and subdirectories |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(MAKE_DIRECTORY [<directories>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Create the given directories and their parents as needed. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(REMOVE [<files>...]) |
| file(REMOVE_RECURSE [<files>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Remove the given files. The \fBREMOVE_RECURSE\fP mode will remove the given |
| files and directories, also non\-empty directories. No error is emitted if a |
| given file does not exist. Relative input paths are evaluated with respect |
| to the current source directory. |
| .sp |
| Changed in version 3.15: Empty input paths are ignored with a warning. Previous versions of CMake |
| interpreted empty strings as a relative path with respect to the current |
| directory and removed its contents. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(RENAME <oldname> <newname> |
| [RESULT <result>] |
| [NO_REPLACE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Move a file or directory within a filesystem from \fB<oldname>\fP to |
| \fB<newname>\fP, replacing the destination atomically. |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBRESULT <result>\fP |
| New in version 3.21. |
| |
| .sp |
| Set \fB<result>\fP variable to \fB0\fP on success or an error message otherwise. |
| If \fBRESULT\fP is not specified and the operation fails, an error is emitted. |
| .TP |
| .B \fBNO_REPLACE\fP |
| New in version 3.21. |
| |
| .sp |
| If the \fB<newname>\fP path already exists, do not replace it. |
| If \fBRESULT <result>\fP is used, the result variable will be |
| set to \fBNO_REPLACE\fP\&. Otherwise, an error is emitted. |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(COPY_FILE <oldname> <newname> |
| [RESULT <result>] |
| [ONLY_IF_DIFFERENT]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.21. |
| |
| .sp |
| Copy a file from \fB<oldname>\fP to \fB<newname>\fP\&. Directories are not |
| supported. Symlinks are ignored and \fB<oldfile>\fP\(aqs content is read and |
| written to \fB<newname>\fP as a new file. |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBRESULT <result>\fP |
| Set \fB<result>\fP variable to \fB0\fP on success or an error message otherwise. |
| If \fBRESULT\fP is not specified and the operation fails, an error is emitted. |
| .TP |
| .B \fBONLY_IF_DIFFERENT\fP |
| If the \fB<newname>\fP path already exists, do not replace it if the file\(aqs |
| contents are already the same as \fB<oldname>\fP (this avoids updating |
| \fB<newname>\fP\(aqs timestamp). |
| .UNINDENT |
| .sp |
| This sub\-command has some similarities to \fBconfigure_file()\fP with the |
| \fBCOPYONLY\fP option. An important difference is that \fBconfigure_file()\fP |
| creates a dependency on the source file, so CMake will be re\-run if it changes. |
| The \fBfile(COPY_FILE)\fP sub\-command does not create such a dependency. |
| .sp |
| See also the \fBfile(COPY)\fP sub\-command just below which provides |
| further file\-copying capabilities. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(<COPY|INSTALL> <files>... DESTINATION <dir> |
| [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS] |
| [FILE_PERMISSIONS <permissions>...] |
| [DIRECTORY_PERMISSIONS <permissions>...] |
| [FOLLOW_SYMLINK_CHAIN] |
| [FILES_MATCHING] |
| [[PATTERN <pattern> | REGEX <regex>] |
| [EXCLUDE] [PERMISSIONS <permissions>...]] [...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| For a simple file copying operation, the \fBfile(COPY_FILE)\fP sub\-command |
| just above may be easier to use. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBCOPY\fP signature copies files, directories, and symlinks to a |
| destination folder. Relative input paths are evaluated with respect |
| to the current source directory, and a relative destination is |
| evaluated with respect to the current build directory. Copying |
| preserves input file timestamps, and optimizes out a file if it exists |
| at the destination with the same timestamp. Copying preserves input |
| permissions unless explicit permissions or \fBNO_SOURCE_PERMISSIONS\fP |
| are given (default is \fBUSE_SOURCE_PERMISSIONS\fP). |
| .sp |
| New in version 3.15: If \fBFOLLOW_SYMLINK_CHAIN\fP is specified, \fBCOPY\fP will recursively resolve |
| the symlinks at the paths given until a real file is found, and install |
| a corresponding symlink in the destination for each symlink encountered. For |
| each symlink that is installed, the resolution is stripped of the directory, |
| leaving only the filename, meaning that the new symlink points to a file in |
| the same directory as the symlink. This feature is useful on some Unix systems, |
| where libraries are installed as a chain of symlinks with version numbers, with |
| less specific versions pointing to more specific versions. |
| \fBFOLLOW_SYMLINK_CHAIN\fP will install all of these symlinks and the library |
| itself into the destination directory. For example, if you have the following |
| directory structure: |
| |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fB/opt/foo/lib/libfoo.so.1.2.3\fP |
| .IP \(bu 2 |
| \fB/opt/foo/lib/libfoo.so.1.2 \-> libfoo.so.1.2.3\fP |
| .IP \(bu 2 |
| \fB/opt/foo/lib/libfoo.so.1 \-> libfoo.so.1.2\fP |
| .IP \(bu 2 |
| \fB/opt/foo/lib/libfoo.so \-> libfoo.so.1\fP |
| .UNINDENT |
| .sp |
| and you do: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This will install all of the symlinks and \fBlibfoo.so.1.2.3\fP itself into |
| \fBlib\fP\&. |
| .sp |
| See the \fBinstall(DIRECTORY)\fP command for documentation of |
| permissions, \fBFILES_MATCHING\fP, \fBPATTERN\fP, \fBREGEX\fP, and |
| \fBEXCLUDE\fP options. Copying directories preserves the structure |
| of their content even if options are used to select a subset of |
| files. |
| .sp |
| The \fBINSTALL\fP signature differs slightly from \fBCOPY\fP: it prints |
| status messages, and \fBNO_SOURCE_PERMISSIONS\fP is default. |
| .sp |
| Installation scripts generated by the \fBinstall()\fP command |
| use this signature (with some undocumented options for internal use). |
| .sp |
| Changed in version 3.22: The environment variable \fBCMAKE_INSTALL_MODE\fP can override the |
| default copying behavior of \fI\%file(INSTALL)\fP\&. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(SIZE <filename> <variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.14. |
| |
| .sp |
| Determine the file size of the \fB<filename>\fP and put the result in |
| \fB<variable>\fP variable. Requires that \fB<filename>\fP is a valid path |
| pointing to a file and is readable. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(READ_SYMLINK <linkname> <variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.14. |
| |
| .sp |
| This subcommand queries the symlink \fB<linkname>\fP and stores the path it |
| points to in the result \fB<variable>\fP\&. If \fB<linkname>\fP does not exist or |
| is not a symlink, CMake issues a fatal error. |
| .sp |
| Note that this command returns the raw symlink path and does not resolve |
| a relative path. The following is an example of how to ensure that an |
| absolute path is obtained: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(linkname "/path/to/foo.sym") |
| file(READ_SYMLINK "${linkname}" result) |
| if(NOT IS_ABSOLUTE "${result}") |
| get_filename_component(dir "${linkname}" DIRECTORY) |
| set(result "${dir}/${result}") |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(CREATE_LINK <original> <linkname> |
| [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.14. |
| |
| .sp |
| Create a link \fB<linkname>\fP that points to \fB<original>\fP\&. |
| It will be a hard link by default, but providing the \fBSYMBOLIC\fP option |
| results in a symbolic link instead. Hard links require that \fBoriginal\fP |
| exists and is a file, not a directory. If \fB<linkname>\fP already exists, |
| it will be overwritten. |
| .sp |
| The \fB<result>\fP variable, if specified, receives the status of the operation. |
| It is set to \fB0\fP upon success or an error message otherwise. If \fBRESULT\fP |
| is not specified and the operation fails, a fatal error is emitted. |
| .sp |
| Specifying \fBCOPY_ON_ERROR\fP enables copying the file as a fallback if |
| creating the link fails. It can be useful for handling situations such as |
| \fB<original>\fP and \fB<linkname>\fP being on different drives or mount points, |
| which would make them unable to support a hard link. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(CHMOD <files>... <directories>... |
| [PERMISSIONS <permissions>...] |
| [FILE_PERMISSIONS <permissions>...] |
| [DIRECTORY_PERMISSIONS <permissions>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.19. |
| |
| .sp |
| Set the permissions for the \fB<files>...\fP and \fB<directories>...\fP specified. |
| Valid permissions are \fBOWNER_READ\fP, \fBOWNER_WRITE\fP, \fBOWNER_EXECUTE\fP, |
| \fBGROUP_READ\fP, \fBGROUP_WRITE\fP, \fBGROUP_EXECUTE\fP, \fBWORLD_READ\fP, |
| \fBWORLD_WRITE\fP, \fBWORLD_EXECUTE\fP, \fBSETUID\fP, \fBSETGID\fP\&. |
| .sp |
| Valid combination of keywords are: |
| .INDENT 0.0 |
| .TP |
| .B \fBPERMISSIONS\fP |
| All items are changed. |
| .TP |
| .B \fBFILE_PERMISSIONS\fP |
| Only files are changed. |
| .TP |
| .B \fBDIRECTORY_PERMISSIONS\fP |
| Only directories are changed. |
| .TP |
| .B \fBPERMISSIONS\fP and \fBFILE_PERMISSIONS\fP |
| \fBFILE_PERMISSIONS\fP overrides \fBPERMISSIONS\fP for files. |
| .TP |
| .B \fBPERMISSIONS\fP and \fBDIRECTORY_PERMISSIONS\fP |
| \fBDIRECTORY_PERMISSIONS\fP overrides \fBPERMISSIONS\fP for directories. |
| .TP |
| .B \fBFILE_PERMISSIONS\fP and \fBDIRECTORY_PERMISSIONS\fP |
| Use \fBFILE_PERMISSIONS\fP for files and \fBDIRECTORY_PERMISSIONS\fP for |
| directories. |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(CHMOD_RECURSE <files>... <directories>... |
| [PERMISSIONS <permissions>...] |
| [FILE_PERMISSIONS <permissions>...] |
| [DIRECTORY_PERMISSIONS <permissions>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.19. |
| |
| .sp |
| Same as \fI\%CHMOD\fP, but change the permissions of files and directories present in |
| the \fB<directories>...\fP recursively. |
| .SS Path Conversion |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(REAL_PATH <path> <out\-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.19. |
| |
| .sp |
| Compute the absolute path to an existing file or directory with symlinks |
| resolved. |
| .INDENT 0.0 |
| .TP |
| .B \fBBASE_DIRECTORY <dir>\fP |
| If the provided \fB<path>\fP is a relative path, it is evaluated relative to the |
| given base directory \fB<dir>\fP\&. If no base directory is provided, the default |
| base directory will be \fBCMAKE_CURRENT_SOURCE_DIR\fP\&. |
| .TP |
| .B \fBEXPAND_TILDE\fP |
| New in version 3.21. |
| |
| .sp |
| If the \fB<path>\fP is \fB~\fP or starts with \fB~/\fP, the \fB~\fP is replaced by |
| the user\(aqs home directory. The path to the home directory is obtained from |
| environment variables. On Windows, the \fBUSERPROFILE\fP environment variable |
| is used, falling back to the \fBHOME\fP environment variable if \fBUSERPROFILE\fP |
| is not defined. On all other platforms, only \fBHOME\fP is used. |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(RELATIVE_PATH <variable> <directory> <file>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Compute the relative path from a \fB<directory>\fP to a \fB<file>\fP and |
| store it in the \fB<variable>\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(TO_CMAKE_PATH "<path>" <variable>) |
| file(TO_NATIVE_PATH "<path>" <variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBTO_CMAKE_PATH\fP mode converts a native \fB<path>\fP into a cmake\-style |
| path with forward\-slashes (\fB/\fP). 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. |
| .sp |
| The \fBTO_NATIVE_PATH\fP mode converts a cmake\-style \fB<path>\fP into a native |
| path with platform\-specific slashes (\fB\e\fP on Windows hosts and \fB/\fP |
| elsewhere). |
| .sp |
| Always use double quotes around the \fB<path>\fP to be sure it is treated |
| as a single argument to this command. |
| .SS Transfer |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(DOWNLOAD <url> [<file>] [<options>...]) |
| file(UPLOAD <file> <url> [<options>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBDOWNLOAD\fP subcommand downloads the given \fB<url>\fP to a local \fB<file>\fP\&. |
| The \fBUPLOAD\fP mode uploads a local \fB<file>\fP to a given \fB<url>\fP\&. |
| .sp |
| New in version 3.19: If \fB<file>\fP is not specified for \fBfile(DOWNLOAD)\fP, the file is not saved. |
| This can be useful if you want to know if a file can be downloaded (for example, |
| to check that it exists) without actually saving it anywhere. |
| |
| .sp |
| Options to both \fBDOWNLOAD\fP and \fBUPLOAD\fP are: |
| .INDENT 0.0 |
| .TP |
| .B \fBINACTIVITY_TIMEOUT <seconds>\fP |
| Terminate the operation after a period of inactivity. |
| .TP |
| .B \fBLOG <variable>\fP |
| Store a human\-readable log of the operation in a variable. |
| .TP |
| .B \fBSHOW_PROGRESS\fP |
| Print progress information as status messages until the operation is |
| complete. |
| .TP |
| .B \fBSTATUS <variable>\fP |
| Store the resulting status of the operation in a variable. |
| The status is a \fB;\fP separated list of length 2. |
| The first element is the numeric return value for the operation, |
| and the second element is a string value for the error. |
| A \fB0\fP numeric error means no error in the operation. |
| .TP |
| .B \fBTIMEOUT <seconds>\fP |
| Terminate the operation after a given total time has elapsed. |
| .TP |
| .B \fBUSERPWD <username>:<password>\fP |
| New in version 3.7. |
| |
| .sp |
| Set username and password for operation. |
| .TP |
| .B \fBHTTPHEADER <HTTP\-header>\fP |
| New in version 3.7. |
| |
| .sp |
| HTTP header for operation. Suboption can be repeated several times. |
| .TP |
| .B \fBNETRC <level>\fP |
| New in version 3.11. |
| |
| .sp |
| Specify whether the .netrc file is to be used for operation. If this |
| option is not specified, the value of the \fBCMAKE_NETRC\fP variable |
| will be used instead. |
| Valid levels are: |
| .INDENT 7.0 |
| .TP |
| .B \fBIGNORED\fP |
| The .netrc file is ignored. |
| This is the default. |
| .TP |
| .B \fBOPTIONAL\fP |
| The .netrc file is optional, and information in the URL is preferred. |
| The file will be scanned to find which ever information is not specified |
| in the URL. |
| .TP |
| .B \fBREQUIRED\fP |
| The .netrc file is required, and information in the URL is ignored. |
| .UNINDENT |
| .TP |
| .B \fBNETRC_FILE <file>\fP |
| New in version 3.11. |
| |
| .sp |
| Specify an alternative .netrc file to the one in your home directory, |
| if the \fBNETRC\fP level is \fBOPTIONAL\fP or \fBREQUIRED\fP\&. If this option |
| is not specified, the value of the \fBCMAKE_NETRC_FILE\fP variable will |
| be used instead. |
| .TP |
| .B \fBTLS_VERIFY <ON|OFF>\fP |
| Specify whether to verify the server certificate for \fBhttps://\fP URLs. |
| The default is to \fInot\fP verify. If this option is not specified, the value |
| of the \fBCMAKE_TLS_VERIFY\fP variable will be used instead. |
| .sp |
| New in version 3.18: Added support to \fBfile(UPLOAD)\fP\&. |
| |
| .TP |
| .B \fBTLS_CAINFO <file>\fP |
| Specify a custom Certificate Authority file for \fBhttps://\fP URLs. If this |
| option is not specified, the value of the \fBCMAKE_TLS_CAINFO\fP |
| variable will be used instead. |
| .sp |
| New in version 3.18: Added support to \fBfile(UPLOAD)\fP\&. |
| |
| .UNINDENT |
| .sp |
| For \fBhttps://\fP URLs CMake must be built with OpenSSL support. \fBTLS/SSL\fP |
| certificates are not checked by default. Set \fBTLS_VERIFY\fP to \fBON\fP to |
| check certificates. |
| .sp |
| Additional options to \fBDOWNLOAD\fP are: |
| .sp |
| \fBEXPECTED_HASH ALGO=<value>\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Verify that the downloaded content hash matches the expected value, where |
| \fBALGO\fP is one of the algorithms supported by \fBfile(<HASH>)\fP\&. |
| If it does not match, the operation fails with an error. It is an error to |
| specify this if \fBDOWNLOAD\fP is not given a \fB<file>\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBEXPECTED_MD5 <value>\fP |
| Historical short\-hand for \fBEXPECTED_HASH MD5=<value>\fP\&. It is an error to |
| specify this if \fBDOWNLOAD\fP is not given a \fB<file>\fP\&. |
| .UNINDENT |
| .SS Locking |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(LOCK <path> [DIRECTORY] [RELEASE] |
| [GUARD <FUNCTION|FILE|PROCESS>] |
| [RESULT_VARIABLE <variable>] |
| [TIMEOUT <seconds>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.2. |
| |
| .sp |
| Lock a file specified by \fB<path>\fP if no \fBDIRECTORY\fP option present and file |
| \fB<path>/cmake.lock\fP otherwise. File will be locked for scope defined by |
| \fBGUARD\fP option (default value is \fBPROCESS\fP). \fBRELEASE\fP option can be used |
| to unlock file explicitly. If option \fBTIMEOUT\fP is not specified CMake will |
| wait until lock succeed or until fatal error occurs. If \fBTIMEOUT\fP is set to |
| \fB0\fP lock will be tried once and result will be reported immediately. If |
| \fBTIMEOUT\fP is not \fB0\fP CMake will try to lock file for the period specified |
| by \fB<seconds>\fP value. Any errors will be interpreted as fatal if there is no |
| \fBRESULT_VARIABLE\fP option. Otherwise result will be stored in \fB<variable>\fP |
| and will be \fB0\fP on success or error message on failure. |
| .sp |
| Note that lock is advisory \- there is no guarantee that other processes will |
| respect this lock, i.e. lock synchronize two or more CMake instances sharing |
| some modifiable resources. Similar logic applied to \fBDIRECTORY\fP option \- |
| locking parent directory doesn\(aqt prevent other \fBLOCK\fP commands to lock any |
| child directory or file. |
| .sp |
| Trying to lock file twice is not allowed. Any intermediate directories and |
| file itself will be created if they not exist. \fBGUARD\fP and \fBTIMEOUT\fP |
| options ignored on \fBRELEASE\fP operation. |
| .SS Archiving |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(ARCHIVE_CREATE OUTPUT <archive> |
| PATHS <paths>... |
| [FORMAT <format>] |
| [COMPRESSION <compression> [COMPRESSION_LEVEL <compression\-level>]] |
| [MTIME <mtime>] |
| [VERBOSE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.18. |
| |
| .sp |
| Creates the specified \fB<archive>\fP file with the files and directories |
| listed in \fB<paths>\fP\&. Note that \fB<paths>\fP must list actual files or |
| directories, wildcards are not supported. |
| .sp |
| Use the \fBFORMAT\fP option to specify the archive format. Supported values |
| for \fB<format>\fP are \fB7zip\fP, \fBgnutar\fP, \fBpax\fP, \fBpaxr\fP, \fBraw\fP and |
| \fBzip\fP\&. If \fBFORMAT\fP is not given, the default format is \fBpaxr\fP\&. |
| .sp |
| Some archive formats allow the type of compression to be specified. |
| The \fB7zip\fP and \fBzip\fP archive formats already imply a specific type of |
| compression. The other formats use no compression by default, but can be |
| directed to do so with the \fBCOMPRESSION\fP option. Valid values for |
| \fB<compression>\fP are \fBNone\fP, \fBBZip2\fP, \fBGZip\fP, \fBXZ\fP, and \fBZstd\fP\&. |
| .sp |
| New in version 3.19: The compression level can be specified with the \fBCOMPRESSION_LEVEL\fP option. |
| The \fB<compression\-level>\fP should be between 0\-9, with the default being 0. |
| The \fBCOMPRESSION\fP option must be present when \fBCOMPRESSION_LEVEL\fP is given. |
| |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| With \fBFORMAT\fP set to \fBraw\fP only one file will be compressed with the |
| compression type specified by \fBCOMPRESSION\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBVERBOSE\fP option enables verbose output for the archive operation. |
| .sp |
| To specify the modification time recorded in tarball entries, use |
| the \fBMTIME\fP option. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| file(ARCHIVE_EXTRACT INPUT <archive> |
| [DESTINATION <dir>] |
| [PATTERNS <patterns>...] |
| [LIST_ONLY] |
| [VERBOSE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.18. |
| |
| .sp |
| Extracts or lists the content of the specified \fB<archive>\fP\&. |
| .sp |
| The directory where the content of the archive will be extracted to can |
| be specified using the \fBDESTINATION\fP option. If the directory does not |
| exist, it will be created. If \fBDESTINATION\fP is not given, the current |
| binary directory will be used. |
| .sp |
| If required, you may select which files and directories to list or extract |
| from the archive using the specified \fB<patterns>\fP\&. Wildcards are supported. |
| If the \fBPATTERNS\fP option is not given, the entire archive will be listed or |
| extracted. |
| .sp |
| \fBLIST_ONLY\fP will list the files in the archive rather than extract them. |
| .sp |
| With \fBVERBOSE\fP, the command will produce verbose output. |
| .SS find_file |
| .sp |
| A short\-hand signature is: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_file (<VAR> name1 [path1 path2 ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The general signature is: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_file ( |
| <VAR> |
| name | NAMES name1 [name2 ...] |
| [HINTS [path | ENV var]... ] |
| [PATHS [path | ENV var]... ] |
| [PATH_SUFFIXES suffix1 [suffix2 ...]] |
| [DOC "cache documentation string"] |
| [NO_CACHE] |
| [REQUIRED] |
| [NO_DEFAULT_PATH] |
| [NO_PACKAGE_ROOT_PATH] |
| [NO_CMAKE_PATH] |
| [NO_CMAKE_ENVIRONMENT_PATH] |
| [NO_SYSTEM_ENVIRONMENT_PATH] |
| [NO_CMAKE_SYSTEM_PATH] |
| [CMAKE_FIND_ROOT_PATH_BOTH | |
| ONLY_CMAKE_FIND_ROOT_PATH | |
| NO_CMAKE_FIND_ROOT_PATH] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command is used to find a full path to named file\&. |
| A cache entry, or a normal variable if \fBNO_CACHE\fP is specified, |
| named by \fB<VAR>\fP is created to store the result of this command. |
| If the full path to a file is found the result is stored in the variable |
| and the search will not be repeated unless the variable is cleared. |
| If nothing is found, the result will be \fB<VAR>\-NOTFOUND\fP\&. |
| .sp |
| Options include: |
| .INDENT 0.0 |
| .TP |
| .B \fBNAMES\fP |
| Specify one or more possible names for the full path to a file\&. |
| .sp |
| When using this to specify names with and without a version |
| suffix, we recommend specifying the unversioned name first |
| so that locally\-built packages can be found before those |
| provided by distributions. |
| .TP |
| .B \fBHINTS\fP, \fBPATHS\fP |
| Specify directories to search in addition to the default locations. |
| The \fBENV var\fP sub\-option reads paths from a system environment |
| variable. |
| .TP |
| .B \fBPATH_SUFFIXES\fP |
| Specify additional subdirectories to check below each directory |
| location otherwise considered. |
| .TP |
| .B \fBDOC\fP |
| Specify the documentation string for the \fB<VAR>\fP cache entry. |
| .TP |
| .B \fBNO_CACHE\fP |
| New in version 3.21. |
| |
| .sp |
| The result of the search will be stored in a normal variable rather than |
| a cache entry. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| If the variable is already set before the call (as a normal or cache |
| variable) then the search will not occur. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBWARNING:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| This option should be used with caution because it can greatly increase |
| the cost of repeated configure steps. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBREQUIRED\fP |
| New in version 3.18. |
| |
| .sp |
| Stop processing with an error message if nothing is found, otherwise |
| the search will be attempted again the next time find_file is invoked |
| with the same variable. |
| .UNINDENT |
| .sp |
| If \fBNO_DEFAULT_PATH\fP is specified, then no additional paths are |
| added to the search. |
| If \fBNO_DEFAULT_PATH\fP is not specified, the search process is as follows: |
| .INDENT 0.0 |
| .IP 1. 3 |
| New in version 3.12: If called from within a find module or any other script loaded by a call to |
| \fBfind_package(<PackageName>)\fP, search prefixes unique to the |
| current package being found. Specifically, look in the |
| \fB<PackageName>_ROOT\fP CMake variable and the |
| \fB<PackageName>_ROOT\fP environment variable. |
| The package root variables are maintained as a stack, so if called from |
| nested find modules or config packages, root paths from the parent\(aqs find |
| module or config package will be searched after paths from the current |
| module or package. In other words, the search order would be |
| \fB<CurrentPackage>_ROOT\fP, \fBENV{<CurrentPackage>_ROOT}\fP, |
| \fB<ParentPackage>_ROOT\fP, \fBENV{<ParentPackage>_ROOT}\fP, etc. |
| This can be skipped if \fBNO_PACKAGE_ROOT_PATH\fP is passed or by setting |
| the \fBCMAKE_FIND_USE_PACKAGE_ROOT_PATH\fP to \fBFALSE\fP\&. |
| See policy \fBCMP0074\fP\&. |
| |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>\fP in the |
| \fB<PackageName>_ROOT\fP CMake variable and the |
| \fB<PackageName>_ROOT\fP environment variable if |
| called from within a find module loaded by |
| \fBfind_package(<PackageName>)\fP |
| .UNINDENT |
| .IP 2. 3 |
| Search paths specified in cmake\-specific cache variables. |
| These are intended to be used on the command line with a \fB\-DVAR=value\fP\&. |
| The values are interpreted as semicolon\-separated lists\&. |
| This can be skipped if \fBNO_CMAKE_PATH\fP is passed or by setting the |
| \fBCMAKE_FIND_USE_CMAKE_PATH\fP to \fBFALSE\fP\&. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>\fP in \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_INCLUDE_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_FRAMEWORK_PATH\fP |
| .UNINDENT |
| .IP 3. 3 |
| Search paths specified in cmake\-specific environment variables. |
| These are intended to be set in the user\(aqs shell configuration, |
| and therefore use the host\(aqs native path separator |
| (\fB;\fP on Windows and \fB:\fP on UNIX). |
| This can be skipped if \fBNO_CMAKE_ENVIRONMENT_PATH\fP is passed or |
| by setting the \fBCMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH\fP to \fBFALSE\fP\&. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>\fP in \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_INCLUDE_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_FRAMEWORK_PATH\fP |
| .UNINDENT |
| .IP 4. 3 |
| Search the paths specified by the \fBHINTS\fP option. |
| These should be paths computed by system introspection, such as a |
| hint provided by the location of another item already found. |
| Hard\-coded guesses should be specified with the \fBPATHS\fP option. |
| .IP 5. 3 |
| Search the standard system environment variables. |
| This can be skipped if \fBNO_SYSTEM_ENVIRONMENT_PATH\fP is passed or by |
| setting the \fBCMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH\fP to \fBFALSE\fP\&. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| The directories in \fBINCLUDE\fP |
| and \fBPATH\fP\&. |
| .IP \(bu 2 |
| On Windows hosts: |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>/[s]bin\fP in \fBPATH\fP, and |
| \fB<entry>/include\fP for other entries in \fBPATH\fP\&. |
| .UNINDENT |
| .IP 6. 3 |
| Search cmake variables defined in the Platform files |
| for the current system. This can be skipped if \fBNO_CMAKE_SYSTEM_PATH\fP |
| is passed or by setting the \fBCMAKE_FIND_USE_CMAKE_SYSTEM_PATH\fP |
| to \fBFALSE\fP\&. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>\fP in |
| \fBCMAKE_SYSTEM_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_INCLUDE_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_FRAMEWORK_PATH\fP |
| .UNINDENT |
| .sp |
| The platform paths that these variables contain are locations that |
| typically include installed software. An example being \fB/usr/local\fP for |
| UNIX based platforms. |
| .IP 7. 3 |
| Search the paths specified by the PATHS option |
| or in the short\-hand version of the command. |
| These are typically hard\-coded guesses. |
| .UNINDENT |
| .sp |
| The \fBCMAKE_IGNORE_PATH\fP, \fBCMAKE_IGNORE_PREFIX_PATH\fP, |
| \fBCMAKE_SYSTEM_IGNORE_PATH\fP and |
| \fBCMAKE_SYSTEM_IGNORE_PREFIX_PATH\fP variables can also cause some |
| of the above locations to be ignored. |
| .sp |
| New in version 3.16: Added \fBCMAKE_FIND_USE_<CATEGORY>_PATH\fP variables to globally disable |
| various search locations. |
| |
| .sp |
| On macOS the \fBCMAKE_FIND_FRAMEWORK\fP and |
| \fBCMAKE_FIND_APPBUNDLE\fP variables determine the order of |
| preference between Apple\-style and unix\-style package components. |
| .sp |
| The CMake variable \fBCMAKE_FIND_ROOT_PATH\fP specifies one or more |
| directories to be prepended to all other search directories. This |
| effectively "re\-roots" the entire search under given locations. |
| Paths which are descendants of the \fBCMAKE_STAGING_PREFIX\fP are excluded |
| from this re\-rooting, because that variable is always a path on the host system. |
| By default the \fBCMAKE_FIND_ROOT_PATH\fP is empty. |
| .sp |
| The \fBCMAKE_SYSROOT\fP variable can also be used to specify exactly one |
| directory to use as a prefix. Setting \fBCMAKE_SYSROOT\fP also has other |
| effects. See the documentation for that variable for more. |
| .sp |
| These variables are especially useful when cross\-compiling to |
| point to the root directory of the target environment and CMake will |
| search there too. By default at first the directories listed in |
| \fBCMAKE_FIND_ROOT_PATH\fP are searched, then the \fBCMAKE_SYSROOT\fP |
| directory is searched, and then the non\-rooted directories will be |
| searched. The default behavior can be adjusted by setting |
| \fBCMAKE_FIND_ROOT_PATH_MODE_INCLUDE\fP\&. This behavior can be manually |
| overridden on a per\-call basis using options: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_FIND_ROOT_PATH_BOTH\fP |
| Search in the order described above. |
| .TP |
| .B \fBNO_CMAKE_FIND_ROOT_PATH\fP |
| Do not use the \fBCMAKE_FIND_ROOT_PATH\fP variable. |
| .TP |
| .B \fBONLY_CMAKE_FIND_ROOT_PATH\fP |
| Search only the re\-rooted directories and directories below |
| \fBCMAKE_STAGING_PREFIX\fP\&. |
| .UNINDENT |
| .sp |
| The default search order is designed to be most\-specific to |
| least\-specific for common use cases. |
| Projects may override the order by simply calling the command |
| multiple times and using the \fBNO_*\fP options: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_file (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH) |
| find_file (<VAR> NAMES name) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Once one of the calls succeeds the result variable will be set |
| and stored in the cache so that no call will search again. |
| .SS find_library |
| .sp |
| A short\-hand signature is: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_library (<VAR> name1 [path1 path2 ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The general signature is: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_library ( |
| <VAR> |
| name | NAMES name1 [name2 ...] [NAMES_PER_DIR] |
| [HINTS [path | ENV var]... ] |
| [PATHS [path | ENV var]... ] |
| [PATH_SUFFIXES suffix1 [suffix2 ...]] |
| [DOC "cache documentation string"] |
| [NO_CACHE] |
| [REQUIRED] |
| [NO_DEFAULT_PATH] |
| [NO_PACKAGE_ROOT_PATH] |
| [NO_CMAKE_PATH] |
| [NO_CMAKE_ENVIRONMENT_PATH] |
| [NO_SYSTEM_ENVIRONMENT_PATH] |
| [NO_CMAKE_SYSTEM_PATH] |
| [CMAKE_FIND_ROOT_PATH_BOTH | |
| ONLY_CMAKE_FIND_ROOT_PATH | |
| NO_CMAKE_FIND_ROOT_PATH] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command is used to find a library\&. |
| A cache entry, or a normal variable if \fBNO_CACHE\fP is specified, |
| named by \fB<VAR>\fP is created to store the result of this command. |
| If the library is found the result is stored in the variable |
| and the search will not be repeated unless the variable is cleared. |
| If nothing is found, the result will be \fB<VAR>\-NOTFOUND\fP\&. |
| .sp |
| Options include: |
| .INDENT 0.0 |
| .TP |
| .B \fBNAMES\fP |
| Specify one or more possible names for the library\&. |
| .sp |
| When using this to specify names with and without a version |
| suffix, we recommend specifying the unversioned name first |
| so that locally\-built packages can be found before those |
| provided by distributions. |
| .TP |
| .B \fBHINTS\fP, \fBPATHS\fP |
| Specify directories to search in addition to the default locations. |
| The \fBENV var\fP sub\-option reads paths from a system environment |
| variable. |
| .TP |
| .B \fBPATH_SUFFIXES\fP |
| Specify additional subdirectories to check below each directory |
| location otherwise considered. |
| .TP |
| .B \fBDOC\fP |
| Specify the documentation string for the \fB<VAR>\fP cache entry. |
| .TP |
| .B \fBNO_CACHE\fP |
| New in version 3.21. |
| |
| .sp |
| The result of the search will be stored in a normal variable rather than |
| a cache entry. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| If the variable is already set before the call (as a normal or cache |
| variable) then the search will not occur. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBWARNING:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| This option should be used with caution because it can greatly increase |
| the cost of repeated configure steps. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBREQUIRED\fP |
| New in version 3.18. |
| |
| .sp |
| Stop processing with an error message if nothing is found, otherwise |
| the search will be attempted again the next time find_library is invoked |
| with the same variable. |
| .UNINDENT |
| .sp |
| If \fBNO_DEFAULT_PATH\fP is specified, then no additional paths are |
| added to the search. |
| If \fBNO_DEFAULT_PATH\fP is not specified, the search process is as follows: |
| .INDENT 0.0 |
| .IP 1. 3 |
| New in version 3.12: If called from within a find module or any other script loaded by a call to |
| \fBfind_package(<PackageName>)\fP, search prefixes unique to the |
| current package being found. Specifically, look in the |
| \fB<PackageName>_ROOT\fP CMake variable and the |
| \fB<PackageName>_ROOT\fP environment variable. |
| The package root variables are maintained as a stack, so if called from |
| nested find modules or config packages, root paths from the parent\(aqs find |
| module or config package will be searched after paths from the current |
| module or package. In other words, the search order would be |
| \fB<CurrentPackage>_ROOT\fP, \fBENV{<CurrentPackage>_ROOT}\fP, |
| \fB<ParentPackage>_ROOT\fP, \fBENV{<ParentPackage>_ROOT}\fP, etc. |
| This can be skipped if \fBNO_PACKAGE_ROOT_PATH\fP is passed or by setting |
| the \fBCMAKE_FIND_USE_PACKAGE_ROOT_PATH\fP to \fBFALSE\fP\&. |
| See policy \fBCMP0074\fP\&. |
| |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/lib/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP is set, |
| and \fB<prefix>/lib\fP for each \fB<prefix>\fP in the |
| \fB<PackageName>_ROOT\fP CMake variable and the |
| \fB<PackageName>_ROOT\fP environment variable if |
| called from within a find module loaded by |
| \fBfind_package(<PackageName>)\fP |
| .UNINDENT |
| .IP 2. 3 |
| Search paths specified in cmake\-specific cache variables. |
| These are intended to be used on the command line with a \fB\-DVAR=value\fP\&. |
| The values are interpreted as semicolon\-separated lists\&. |
| This can be skipped if \fBNO_CMAKE_PATH\fP is passed or by setting the |
| \fBCMAKE_FIND_USE_CMAKE_PATH\fP to \fBFALSE\fP\&. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/lib/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP is set, |
| and \fB<prefix>/lib\fP for each \fB<prefix>\fP in \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_LIBRARY_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_FRAMEWORK_PATH\fP |
| .UNINDENT |
| .IP 3. 3 |
| Search paths specified in cmake\-specific environment variables. |
| These are intended to be set in the user\(aqs shell configuration, |
| and therefore use the host\(aqs native path separator |
| (\fB;\fP on Windows and \fB:\fP on UNIX). |
| This can be skipped if \fBNO_CMAKE_ENVIRONMENT_PATH\fP is passed or |
| by setting the \fBCMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH\fP to \fBFALSE\fP\&. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/lib/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP is set, |
| and \fB<prefix>/lib\fP for each \fB<prefix>\fP in \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_LIBRARY_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_FRAMEWORK_PATH\fP |
| .UNINDENT |
| .IP 4. 3 |
| Search the paths specified by the \fBHINTS\fP option. |
| These should be paths computed by system introspection, such as a |
| hint provided by the location of another item already found. |
| Hard\-coded guesses should be specified with the \fBPATHS\fP option. |
| .IP 5. 3 |
| Search the standard system environment variables. |
| This can be skipped if \fBNO_SYSTEM_ENVIRONMENT_PATH\fP is passed or by |
| setting the \fBCMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH\fP to \fBFALSE\fP\&. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| The directories in \fBLIB\fP |
| and \fBPATH\fP\&. |
| .IP \(bu 2 |
| On Windows hosts: |
| \fB<prefix>/lib/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/lib\fP for each \fB<prefix>/[s]bin\fP in \fBPATH\fP, and |
| \fB<entry>/lib\fP for other entries in \fBPATH\fP\&. |
| .UNINDENT |
| .IP 6. 3 |
| Search cmake variables defined in the Platform files |
| for the current system. This can be skipped if \fBNO_CMAKE_SYSTEM_PATH\fP |
| is passed or by setting the \fBCMAKE_FIND_USE_CMAKE_SYSTEM_PATH\fP |
| to \fBFALSE\fP\&. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/lib/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP is set, |
| and \fB<prefix>/lib\fP for each \fB<prefix>\fP in |
| \fBCMAKE_SYSTEM_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_LIBRARY_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_FRAMEWORK_PATH\fP |
| .UNINDENT |
| .sp |
| The platform paths that these variables contain are locations that |
| typically include installed software. An example being \fB/usr/local\fP for |
| UNIX based platforms. |
| .IP 7. 3 |
| Search the paths specified by the PATHS option |
| or in the short\-hand version of the command. |
| These are typically hard\-coded guesses. |
| .UNINDENT |
| .sp |
| The \fBCMAKE_IGNORE_PATH\fP, \fBCMAKE_IGNORE_PREFIX_PATH\fP, |
| \fBCMAKE_SYSTEM_IGNORE_PATH\fP and |
| \fBCMAKE_SYSTEM_IGNORE_PREFIX_PATH\fP variables can also cause some |
| of the above locations to be ignored. |
| .sp |
| New in version 3.16: Added \fBCMAKE_FIND_USE_<CATEGORY>_PATH\fP variables to globally disable |
| various search locations. |
| |
| .sp |
| On macOS the \fBCMAKE_FIND_FRAMEWORK\fP and |
| \fBCMAKE_FIND_APPBUNDLE\fP variables determine the order of |
| preference between Apple\-style and unix\-style package components. |
| .sp |
| The CMake variable \fBCMAKE_FIND_ROOT_PATH\fP specifies one or more |
| directories to be prepended to all other search directories. This |
| effectively "re\-roots" the entire search under given locations. |
| Paths which are descendants of the \fBCMAKE_STAGING_PREFIX\fP are excluded |
| from this re\-rooting, because that variable is always a path on the host system. |
| By default the \fBCMAKE_FIND_ROOT_PATH\fP is empty. |
| .sp |
| The \fBCMAKE_SYSROOT\fP variable can also be used to specify exactly one |
| directory to use as a prefix. Setting \fBCMAKE_SYSROOT\fP also has other |
| effects. See the documentation for that variable for more. |
| .sp |
| These variables are especially useful when cross\-compiling to |
| point to the root directory of the target environment and CMake will |
| search there too. By default at first the directories listed in |
| \fBCMAKE_FIND_ROOT_PATH\fP are searched, then the \fBCMAKE_SYSROOT\fP |
| directory is searched, and then the non\-rooted directories will be |
| searched. The default behavior can be adjusted by setting |
| \fBCMAKE_FIND_ROOT_PATH_MODE_LIBRARY\fP\&. This behavior can be manually |
| overridden on a per\-call basis using options: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_FIND_ROOT_PATH_BOTH\fP |
| Search in the order described above. |
| .TP |
| .B \fBNO_CMAKE_FIND_ROOT_PATH\fP |
| Do not use the \fBCMAKE_FIND_ROOT_PATH\fP variable. |
| .TP |
| .B \fBONLY_CMAKE_FIND_ROOT_PATH\fP |
| Search only the re\-rooted directories and directories below |
| \fBCMAKE_STAGING_PREFIX\fP\&. |
| .UNINDENT |
| .sp |
| The default search order is designed to be most\-specific to |
| least\-specific for common use cases. |
| Projects may override the order by simply calling the command |
| multiple times and using the \fBNO_*\fP options: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_library (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH) |
| find_library (<VAR> NAMES name) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Once one of the calls succeeds the result variable will be set |
| and stored in the cache so that no call will search again. |
| .sp |
| When more than one value is given to the \fBNAMES\fP option this command by |
| default will consider one name at a time and search every directory |
| for it. The \fBNAMES_PER_DIR\fP option tells this command to consider one |
| directory at a time and search for all names in it. |
| .sp |
| Each library name given to the \fBNAMES\fP option is first considered |
| as a library file name and then considered with platform\-specific |
| prefixes (e.g. \fBlib\fP) and suffixes (e.g. \fB\&.so\fP). Therefore one |
| may specify library file names such as \fBlibfoo.a\fP directly. |
| This can be used to locate static libraries on UNIX\-like systems. |
| .sp |
| If the library found is a framework, then \fB<VAR>\fP will be set to the full |
| path to the framework \fB<fullPath>/A.framework\fP\&. When a full path to a |
| framework is used as a library, CMake will use a \fB\-framework A\fP, and a |
| \fB\-F<fullPath>\fP to link the framework to the target. |
| .sp |
| If the \fBCMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX\fP variable is set all |
| search paths will be tested as normal, with the suffix appended, and with |
| all matches of \fBlib/\fP replaced with |
| \fBlib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX}/\fP\&. This variable overrides |
| the \fBFIND_LIBRARY_USE_LIB32_PATHS\fP, |
| \fBFIND_LIBRARY_USE_LIBX32_PATHS\fP, |
| and \fBFIND_LIBRARY_USE_LIB64_PATHS\fP global properties. |
| .sp |
| If the \fBFIND_LIBRARY_USE_LIB32_PATHS\fP global property is set |
| all search paths will be tested as normal, with \fB32/\fP appended, and |
| with all matches of \fBlib/\fP replaced with \fBlib32/\fP\&. This property is |
| automatically set for the platforms that are known to need it if at |
| least one of the languages supported by the \fBproject()\fP command |
| is enabled. |
| .sp |
| If the \fBFIND_LIBRARY_USE_LIBX32_PATHS\fP global property is set |
| all search paths will be tested as normal, with \fBx32/\fP appended, and |
| with all matches of \fBlib/\fP replaced with \fBlibx32/\fP\&. This property is |
| automatically set for the platforms that are known to need it if at |
| least one of the languages supported by the \fBproject()\fP command |
| is enabled. |
| .sp |
| If the \fBFIND_LIBRARY_USE_LIB64_PATHS\fP global property is set |
| all search paths will be tested as normal, with \fB64/\fP appended, and |
| with all matches of \fBlib/\fP replaced with \fBlib64/\fP\&. This property is |
| automatically set for the platforms that are known to need it if at |
| least one of the languages supported by the \fBproject()\fP command |
| is enabled. |
| .SS find_package |
| .sp |
| Find a package (usually provided by something external to the project), |
| and load its package\-specific details. |
| .SS Search Modes |
| .sp |
| The command has two very distinct ways of conducting the search: |
| .INDENT 0.0 |
| .TP |
| \fBModule mode\fP |
| In this mode, CMake searches for a file called \fBFind<PackageName>.cmake\fP, |
| looking first in the locations listed in the \fBCMAKE_MODULE_PATH\fP, |
| then among the Find Modules provided by the CMake installation. |
| If the file is found, it is read and processed by CMake. It is responsible |
| for finding the package, checking the version, and producing any needed |
| messages. Some Find modules provide limited or no support for versioning; |
| check the Find module\(aqs documentation. |
| .sp |
| The \fBFind<PackageName>.cmake\fP file is not typically provided by the |
| package itself. Rather, it is normally provided by something external to |
| the package, such as the operating system, CMake itself, or even the project |
| from which the \fBfind_package()\fP command was called. Being externally |
| provided, Find Modules tend to be heuristic in nature and are |
| susceptible to becoming out\-of\-date. They typically search for certain |
| libraries, files and other package artifacts. |
| .sp |
| Module mode is only supported by the |
| \fI\%basic command signature\fP\&. |
| .TP |
| \fBConfig mode\fP |
| In this mode, CMake searches for a file called |
| \fB<lowercasePackageName>\-config.cmake\fP or \fB<PackageName>Config.cmake\fP\&. |
| It will also look for \fB<lowercasePackageName>\-config\-version.cmake\fP or |
| \fB<PackageName>ConfigVersion.cmake\fP if version details were specified |
| (see \fI\%Config Mode Version Selection\fP for an explanation of how these separate |
| version files are used). |
| .sp |
| In config mode, the command can be given a list of names to search for |
| as package names. The locations where CMake searches for the config and |
| version files is considerably more complicated than for Module mode |
| (see \fI\%Config Mode Search Procedure\fP). |
| .sp |
| The config and version files are typically installed as part of the |
| package, so they tend to be more reliable than Find modules. They usually |
| contain direct knowledge of the package contents, so no searching or |
| heuristics are needed within the config or version files themselves. |
| .sp |
| Config mode is supported by both the \fI\%basic\fP and |
| \fI\%full\fP command signatures. |
| .UNINDENT |
| .sp |
| The command arguments determine which of the above modes is used. When the |
| \fI\%basic signature\fP is used, the command searches in Module mode first. |
| If the package is not found, the search falls back to Config mode. |
| A user may set the \fBCMAKE_FIND_PACKAGE_PREFER_CONFIG\fP variable |
| to true to reverse the priority and direct CMake to search using Config mode |
| first before falling back to Module mode. The basic signature can also be |
| forced to use only Module mode with a \fBMODULE\fP keyword. If the |
| \fI\%full signature\fP is used, the command only searches in Config mode. |
| .sp |
| Where possible, user code should generally look for packages using the |
| \fI\%basic signature\fP, since that allows the package to be found with either mode. |
| Project maintainers wishing to provide a config package should understand |
| the bigger picture, as explained in \fI\%Full Signature\fP and all subsequent |
| sections on this page. |
| .SS Basic Signature |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE] |
| [REQUIRED] [[COMPONENTS] [components...]] |
| [OPTIONAL_COMPONENTS components...] |
| [NO_POLICY_SCOPE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The basic signature is supported by both Module and Config modes. |
| The \fBMODULE\fP keyword implies that only Module mode can be used to find |
| the package, with no fallback to Config mode. |
| .sp |
| Regardless of the mode used, a \fB<PackageName>_FOUND\fP variable will be |
| set to indicate whether the package was found. When the package is found, |
| package\-specific information may be provided through other variables and |
| Imported Targets documented by the package itself. The |
| \fBQUIET\fP option disables informational messages, including those indicating |
| that the package cannot be found if it is not \fBREQUIRED\fP\&. The \fBREQUIRED\fP |
| option stops processing with an error message if the package cannot be found. |
| .sp |
| A package\-specific list of required components may be listed after the |
| \fBCOMPONENTS\fP keyword. If any of these components are not able to be |
| satisfied, the package overall is considered to be not found. If the |
| \fBREQUIRED\fP option is also present, this is treated as a fatal error, |
| otherwise execution still continues. As a form of shorthand, if the |
| \fBREQUIRED\fP option is present, the \fBCOMPONENTS\fP keyword can be omitted |
| and the required components can be listed directly after \fBREQUIRED\fP\&. |
| .sp |
| Additional optional components may be listed after |
| \fBOPTIONAL_COMPONENTS\fP\&. If these cannot be satisfied, the package overall |
| can still be considered found, as long as all required components are |
| satisfied. |
| .sp |
| The set of available components and their meaning are defined by the |
| target package. Formally, it is up to the target package how to |
| interpret the component information given to it, but it should follow |
| the expectations stated above. For calls where no components are specified, |
| there is no single expected behavior and target packages should clearly |
| define what occurs in such cases. Common arrangements include assuming it |
| should find all components, no components or some well\-defined subset of the |
| available components. |
| .sp |
| The \fB[version]\fP argument requests a version with which the package found |
| should be compatible. There are two possible forms in which it may be |
| specified: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .IP \(bu 2 |
| A single version with the format \fBmajor[.minor[.patch[.tweak]]]\fP, where |
| each component is a numeric value. |
| .IP \(bu 2 |
| A version range with the format \fBversionMin...[<]versionMax\fP where |
| \fBversionMin\fP and \fBversionMax\fP have the same format and constraints |
| on components being integers as the single version. By default, both end |
| points are included. By specifying \fB<\fP, the upper end point will be |
| excluded. Version ranges are only supported with CMake 3.19 or later. |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBEXACT\fP option requests that the version be matched exactly. This option |
| is incompatible with the specification of a version range. |
| .sp |
| If no \fB[version]\fP and/or component list is given to a recursive invocation |
| inside a find\-module, the corresponding arguments are forwarded |
| automatically from the outer call (including the \fBEXACT\fP flag for |
| \fB[version]\fP). Version support is currently provided only on a |
| package\-by\-package basis (see the \fI\%Version Selection\fP section below). |
| When a version range is specified but the package is only designed to expect |
| a single version, the package will ignore the upper end point of the range and |
| only take the single version at the lower end of the range into account. |
| .sp |
| See the \fBcmake_policy()\fP command documentation for discussion |
| of the \fBNO_POLICY_SCOPE\fP option. |
| .SS Full Signature |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package(<PackageName> [version] [EXACT] [QUIET] |
| [REQUIRED] [[COMPONENTS] [components...]] |
| [OPTIONAL_COMPONENTS components...] |
| [CONFIG|NO_MODULE] |
| [NO_POLICY_SCOPE] |
| [NAMES name1 [name2 ...]] |
| [CONFIGS config1 [config2 ...]] |
| [HINTS path1 [path2 ... ]] |
| [PATHS path1 [path2 ... ]] |
| [PATH_SUFFIXES suffix1 [suffix2 ...]] |
| [NO_DEFAULT_PATH] |
| [NO_PACKAGE_ROOT_PATH] |
| [NO_CMAKE_PATH] |
| [NO_CMAKE_ENVIRONMENT_PATH] |
| [NO_SYSTEM_ENVIRONMENT_PATH] |
| [NO_CMAKE_PACKAGE_REGISTRY] |
| [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing. |
| [NO_CMAKE_SYSTEM_PATH] |
| [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY] |
| [CMAKE_FIND_ROOT_PATH_BOTH | |
| ONLY_CMAKE_FIND_ROOT_PATH | |
| NO_CMAKE_FIND_ROOT_PATH]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBCONFIG\fP option, the synonymous \fBNO_MODULE\fP option, or the use |
| of options not specified in the \fI\%basic signature\fP all enforce pure Config |
| mode. In pure Config mode, the command skips Module mode search and |
| proceeds at once with Config mode search. |
| .sp |
| Config mode search attempts to locate a configuration file provided by the |
| package to be found. A cache entry called \fB<PackageName>_DIR\fP is created to |
| hold the directory containing the file. By default the command |
| searches for a package with the name \fB<PackageName>\fP\&. If the \fBNAMES\fP option |
| is given the names following it are used instead of \fB<PackageName>\fP\&. |
| The command searches for a file called \fB<PackageName>Config.cmake\fP or |
| \fB<lowercasePackageName>\-config.cmake\fP for each name specified. |
| A replacement set of possible configuration file names may be given |
| using the \fBCONFIGS\fP option. The \fI\%Config Mode Search Procedure\fP is specified below. |
| Once found, any \fI\%version constraint\fP is checked, |
| and if satisfied, the configuration file is read and processed by CMake. |
| Since the file is provided by the package it already knows the |
| location of package contents. The full path to the configuration file |
| is stored in the cmake variable \fB<PackageName>_CONFIG\fP\&. |
| .sp |
| All configuration files which have been considered by CMake while |
| searching for the package with an appropriate version are stored in the |
| \fB<PackageName>_CONSIDERED_CONFIGS\fP variable, and the associated versions |
| in the \fB<PackageName>_CONSIDERED_VERSIONS\fP variable. |
| .sp |
| If the package configuration file cannot be found CMake will generate |
| an error describing the problem unless the \fBQUIET\fP argument is |
| specified. If \fBREQUIRED\fP is specified and the package is not found a |
| fatal error is generated and the configure step stops executing. If |
| \fB<PackageName>_DIR\fP has been set to a directory not containing a |
| configuration file CMake will ignore it and search from scratch. |
| .sp |
| Package maintainers providing CMake package configuration files are |
| encouraged to name and install them such that the \fI\%Config Mode Search Procedure\fP |
| outlined below will find them without requiring use of additional options. |
| .SS Config Mode Search Procedure |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| When Config mode is used, this search procedure is applied regardless of |
| whether the \fI\%full\fP or \fI\%basic\fP |
| signature was given. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| CMake constructs a set of possible installation prefixes for the |
| package. Under each prefix several directories are searched for a |
| configuration file. The tables below show the directories searched. |
| Each entry is meant for installation trees following Windows (\fBW\fP), UNIX |
| (\fBU\fP), or Apple (\fBA\fP) conventions: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| <prefix>/ (W) |
| <prefix>/(cmake|CMake)/ (W) |
| <prefix>/<name>*/ (W) |
| <prefix>/<name>*/(cmake|CMake)/ (W) |
| <prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/ (U) |
| <prefix>/(lib/<arch>|lib*|share)/<name>*/ (U) |
| <prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (U) |
| <prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/ (W/U) |
| <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ (W/U) |
| <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| On systems supporting macOS \fBFRAMEWORK\fP and \fBBUNDLE\fP, the |
| following directories are searched for Frameworks or Application Bundles |
| containing a configuration file: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| <prefix>/<name>.framework/Resources/ (A) |
| <prefix>/<name>.framework/Resources/CMake/ (A) |
| <prefix>/<name>.framework/Versions/*/Resources/ (A) |
| <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A) |
| <prefix>/<name>.app/Contents/Resources/ (A) |
| <prefix>/<name>.app/Contents/Resources/CMake/ (A) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In all cases the \fB<name>\fP is treated as case\-insensitive and corresponds |
| to any of the names specified (\fB<PackageName>\fP or names given by \fBNAMES\fP). |
| .sp |
| Paths with \fBlib/<arch>\fP are enabled if the |
| \fBCMAKE_LIBRARY_ARCHITECTURE\fP variable is set. \fBlib*\fP includes one |
| or more of the values \fBlib64\fP, \fBlib32\fP, \fBlibx32\fP or \fBlib\fP (searched in |
| that order). |
| .INDENT 0.0 |
| .IP \(bu 2 |
| Paths with \fBlib64\fP are searched on 64 bit platforms if the |
| \fBFIND_LIBRARY_USE_LIB64_PATHS\fP property is set to \fBTRUE\fP\&. |
| .IP \(bu 2 |
| Paths with \fBlib32\fP are searched on 32 bit platforms if the |
| \fBFIND_LIBRARY_USE_LIB32_PATHS\fP property is set to \fBTRUE\fP\&. |
| .IP \(bu 2 |
| Paths with \fBlibx32\fP are searched on platforms using the x32 ABI |
| if the \fBFIND_LIBRARY_USE_LIBX32_PATHS\fP property is set to \fBTRUE\fP\&. |
| .IP \(bu 2 |
| The \fBlib\fP path is always searched. |
| .UNINDENT |
| .sp |
| If \fBPATH_SUFFIXES\fP is specified, the suffixes are appended to each |
| (\fBW\fP) or (\fBU\fP) directory entry one\-by\-one. |
| .sp |
| This set of directories is intended to work in cooperation with |
| projects that provide configuration files in their installation trees. |
| Directories above marked with (\fBW\fP) are intended for installations on |
| Windows where the prefix may point at the top of an application\(aqs |
| installation directory. Those marked with (\fBU\fP) are intended for |
| installations on UNIX platforms where the prefix is shared by multiple |
| packages. This is merely a convention, so all (\fBW\fP) and (\fBU\fP) directories |
| are still searched on all platforms. Directories marked with (\fBA\fP) are |
| intended for installations on Apple platforms. The |
| \fBCMAKE_FIND_FRAMEWORK\fP and \fBCMAKE_FIND_APPBUNDLE\fP |
| variables determine the order of preference. |
| .sp |
| The set of installation prefixes is constructed using the following |
| steps. If \fBNO_DEFAULT_PATH\fP is specified all \fBNO_*\fP options are |
| enabled. |
| .INDENT 0.0 |
| .IP 1. 3 |
| New in version 3.12: Search paths specified in the \fB<PackageName>_ROOT\fP CMake |
| variable and the \fB<PackageName>_ROOT\fP environment variable, |
| where \fB<PackageName>\fP is the package to be found. |
| The package root variables are maintained as a stack so if |
| called from within a find module, root paths from the parent\(aqs find |
| module will also be searched after paths for the current package. |
| This can be skipped if \fBNO_PACKAGE_ROOT_PATH\fP is passed or by setting |
| the \fBCMAKE_FIND_USE_PACKAGE_ROOT_PATH\fP to \fBFALSE\fP\&. |
| See policy \fBCMP0074\fP\&. |
| |
| .IP 2. 3 |
| Search paths specified in cmake\-specific cache variables. These |
| are intended to be used on the command line with a \fB\-DVAR=value\fP\&. |
| The values are interpreted as semicolon\-separated lists\&. |
| This can be skipped if \fBNO_CMAKE_PATH\fP is passed or by setting the |
| \fBCMAKE_FIND_USE_CMAKE_PATH\fP to \fBFALSE\fP: |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_FRAMEWORK_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_APPBUNDLE_PATH\fP |
| .UNINDENT |
| .IP 3. 3 |
| Search paths specified in cmake\-specific environment variables. |
| These are intended to be set in the user\(aqs shell configuration, |
| and therefore use the host\(aqs native path separator |
| (\fB;\fP on Windows and \fB:\fP on UNIX). |
| This can be skipped if \fBNO_CMAKE_ENVIRONMENT_PATH\fP is passed or by setting |
| the \fBCMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH\fP to \fBFALSE\fP: |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<PackageName>_DIR\fP |
| .IP \(bu 2 |
| \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_FRAMEWORK_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_APPBUNDLE_PATH\fP |
| .UNINDENT |
| .IP 4. 3 |
| Search paths specified by the \fBHINTS\fP option. These should be paths |
| computed by system introspection, such as a hint provided by the |
| location of another item already found. Hard\-coded guesses should |
| be specified with the \fBPATHS\fP option. |
| .IP 5. 3 |
| Search the standard system environment variables. This can be |
| skipped if \fBNO_SYSTEM_ENVIRONMENT_PATH\fP is passed or by setting the |
| \fBCMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH\fP to \fBFALSE\fP\&. Path entries |
| ending in \fB/bin\fP or \fB/sbin\fP are automatically converted to their |
| parent directories: |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fBPATH\fP |
| .UNINDENT |
| .IP 6. 3 |
| Search paths stored in the CMake User Package Registry\&. |
| This can be skipped if \fBNO_CMAKE_PACKAGE_REGISTRY\fP is passed or by |
| setting the variable \fBCMAKE_FIND_USE_PACKAGE_REGISTRY\fP |
| to \fBFALSE\fP or the deprecated variable |
| \fBCMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY\fP to \fBTRUE\fP\&. |
| .sp |
| See the \fBcmake\-packages(7)\fP manual for details on the user |
| package registry. |
| .IP 7. 3 |
| Search cmake variables defined in the Platform files for the |
| current system. This can be skipped if \fBNO_CMAKE_SYSTEM_PATH\fP is |
| passed or by setting the \fBCMAKE_FIND_USE_CMAKE_SYSTEM_PATH\fP |
| to \fBFALSE\fP: |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_FRAMEWORK_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_APPBUNDLE_PATH\fP |
| .UNINDENT |
| .sp |
| The platform paths that these variables contain are locations that |
| typically include installed software. An example being \fB/usr/local\fP for |
| UNIX based platforms. |
| .IP 8. 3 |
| Search paths stored in the CMake System Package Registry\&. |
| This can be skipped if \fBNO_CMAKE_SYSTEM_PACKAGE_REGISTRY\fP is passed |
| or by setting the \fBCMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY\fP |
| variable to \fBFALSE\fP or the deprecated variable |
| \fBCMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY\fP to \fBTRUE\fP\&. |
| .sp |
| See the \fBcmake\-packages(7)\fP manual for details on the system |
| package registry. |
| .IP 9. 3 |
| Search paths specified by the \fBPATHS\fP option. These are typically |
| hard\-coded guesses. |
| .UNINDENT |
| .sp |
| The \fBCMAKE_IGNORE_PATH\fP, \fBCMAKE_IGNORE_PREFIX_PATH\fP, |
| \fBCMAKE_SYSTEM_IGNORE_PATH\fP and |
| \fBCMAKE_SYSTEM_IGNORE_PREFIX_PATH\fP variables can also cause some |
| of the above locations to be ignored. |
| .sp |
| New in version 3.16: Added the \fBCMAKE_FIND_USE_<CATEGORY>\fP variables to globally disable |
| various search locations. |
| |
| .sp |
| The CMake variable \fBCMAKE_FIND_ROOT_PATH\fP specifies one or more |
| directories to be prepended to all other search directories. This |
| effectively "re\-roots" the entire search under given locations. |
| Paths which are descendants of the \fBCMAKE_STAGING_PREFIX\fP are excluded |
| from this re\-rooting, because that variable is always a path on the host system. |
| By default the \fBCMAKE_FIND_ROOT_PATH\fP is empty. |
| .sp |
| The \fBCMAKE_SYSROOT\fP variable can also be used to specify exactly one |
| directory to use as a prefix. Setting \fBCMAKE_SYSROOT\fP also has other |
| effects. See the documentation for that variable for more. |
| .sp |
| These variables are especially useful when cross\-compiling to |
| point to the root directory of the target environment and CMake will |
| search there too. By default at first the directories listed in |
| \fBCMAKE_FIND_ROOT_PATH\fP are searched, then the \fBCMAKE_SYSROOT\fP |
| directory is searched, and then the non\-rooted directories will be |
| searched. The default behavior can be adjusted by setting |
| \fBCMAKE_FIND_ROOT_PATH_MODE_PACKAGE\fP\&. This behavior can be manually |
| overridden on a per\-call basis using options: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_FIND_ROOT_PATH_BOTH\fP |
| Search in the order described above. |
| .TP |
| .B \fBNO_CMAKE_FIND_ROOT_PATH\fP |
| Do not use the \fBCMAKE_FIND_ROOT_PATH\fP variable. |
| .TP |
| .B \fBONLY_CMAKE_FIND_ROOT_PATH\fP |
| Search only the re\-rooted directories and directories below |
| \fBCMAKE_STAGING_PREFIX\fP\&. |
| .UNINDENT |
| .sp |
| The default search order is designed to be most\-specific to |
| least\-specific for common use cases. |
| Projects may override the order by simply calling the command |
| multiple times and using the \fBNO_*\fP options: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_package (<PackageName> PATHS paths... NO_DEFAULT_PATH) |
| find_package (<PackageName>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Once one of the calls succeeds the result variable will be set |
| and stored in the cache so that no call will search again. |
| .sp |
| By default the value stored in the result variable will be the path at |
| which the file is found. The \fBCMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS\fP |
| variable may be set to \fBTRUE\fP before calling \fBfind_package\fP in order |
| to resolve symbolic links and store the real path to the file. |
| .sp |
| Every non\-REQUIRED \fBfind_package\fP call can be disabled or made REQUIRED: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| Setting the \fBCMAKE_DISABLE_FIND_PACKAGE_<PackageName>\fP variable |
| to \fBTRUE\fP disables the package. |
| .IP \(bu 2 |
| Setting the \fBCMAKE_REQUIRE_FIND_PACKAGE_<PackageName>\fP variable |
| to \fBTRUE\fP makes the package REQUIRED. |
| .UNINDENT |
| .sp |
| Setting both variables to \fBTRUE\fP simultaneously is an error. |
| .SS Config Mode Version Selection |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| When Config mode is used, this version selection process is applied |
| regardless of whether the \fI\%full\fP or |
| \fI\%basic\fP signature was given. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| When the \fB[version]\fP argument is given, Config mode will only find a |
| version of the package that claims compatibility with the requested |
| version (see \fI\%format specification\fP). If the |
| \fBEXACT\fP option is given, only a version of the package claiming an exact match |
| of the requested version may be found. CMake does not establish any |
| convention for the meaning of version numbers. Package version |
| numbers are checked by "version" files provided by the packages |
| themselves. For a candidate package configuration file |
| \fB<config\-file>.cmake\fP the corresponding version file is located next |
| to it and named either \fB<config\-file>\-version.cmake\fP or |
| \fB<config\-file>Version.cmake\fP\&. If no such version file is available |
| then the configuration file is assumed to not be compatible with any |
| requested version. A basic version file containing generic version |
| matching code can be created using the |
| \fBCMakePackageConfigHelpers\fP module. When a version file |
| is found it is loaded to check the requested version number. The |
| version file is loaded in a nested scope in which the following |
| variables have been defined: |
| .INDENT 0.0 |
| .TP |
| .B \fBPACKAGE_FIND_NAME\fP |
| The \fB<PackageName>\fP |
| .TP |
| .B \fBPACKAGE_FIND_VERSION\fP |
| Full requested version string |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_MAJOR\fP |
| Major version if requested, else 0 |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_MINOR\fP |
| Minor version if requested, else 0 |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_PATCH\fP |
| Patch version if requested, else 0 |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_TWEAK\fP |
| Tweak version if requested, else 0 |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_COUNT\fP |
| Number of version components, 0 to 4 |
| .UNINDENT |
| .sp |
| When a version range is specified, the above version variables will hold |
| values based on the lower end of the version range. This is to preserve |
| compatibility with packages that have not been implemented to expect version |
| ranges. In addition, the version range will be described by the following |
| variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_RANGE\fP |
| Full requested version range string |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_RANGE_MIN\fP |
| This specifies whether the lower end point of the version range should be |
| included or excluded. Currently, the only supported value for this variable |
| is \fBINCLUDE\fP\&. |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_RANGE_MAX\fP |
| This specifies whether the upper end point of the version range should be |
| included or excluded. The supported values for this variable are |
| \fBINCLUDE\fP and \fBEXCLUDE\fP\&. |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_MIN\fP |
| Full requested version string of the lower end point of the range |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_MIN_MAJOR\fP |
| Major version of the lower end point if requested, else 0 |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_MIN_MINOR\fP |
| Minor version of the lower end point if requested, else 0 |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_MIN_PATCH\fP |
| Patch version of the lower end point if requested, else 0 |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_MIN_TWEAK\fP |
| Tweak version of the lower end point if requested, else 0 |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_MIN_COUNT\fP |
| Number of version components of the lower end point, 0 to 4 |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_MAX\fP |
| Full requested version string of the upper end point of the range |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_MAX_MAJOR\fP |
| Major version of the upper end point if requested, else 0 |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_MAX_MINOR\fP |
| Minor version of the upper end point if requested, else 0 |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_MAX_PATCH\fP |
| Patch version of the upper end point if requested, else 0 |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_MAX_TWEAK\fP |
| Tweak version of the upper end point if requested, else 0 |
| .TP |
| .B \fBPACKAGE_FIND_VERSION_MAX_COUNT\fP |
| Number of version components of the upper end point, 0 to 4 |
| .UNINDENT |
| .sp |
| Regardless of whether a single version or a version range is specified, the |
| variable \fBPACKAGE_FIND_VERSION_COMPLETE\fP will be defined and will hold |
| the full requested version string as specified. |
| .sp |
| The version file checks whether it satisfies the requested version and |
| sets these variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBPACKAGE_VERSION\fP |
| Full provided version string |
| .TP |
| .B \fBPACKAGE_VERSION_EXACT\fP |
| True if version is exact match |
| .TP |
| .B \fBPACKAGE_VERSION_COMPATIBLE\fP |
| True if version is compatible |
| .TP |
| .B \fBPACKAGE_VERSION_UNSUITABLE\fP |
| True if unsuitable as any version |
| .UNINDENT |
| .sp |
| These variables are checked by the \fBfind_package\fP command to determine |
| whether the configuration file provides an acceptable version. They |
| are not available after the \fBfind_package\fP call returns. If the version |
| is acceptable the following variables are set: |
| .INDENT 0.0 |
| .TP |
| .B \fB<PackageName>_VERSION\fP |
| Full provided version string |
| .TP |
| .B \fB<PackageName>_VERSION_MAJOR\fP |
| Major version if provided, else 0 |
| .TP |
| .B \fB<PackageName>_VERSION_MINOR\fP |
| Minor version if provided, else 0 |
| .TP |
| .B \fB<PackageName>_VERSION_PATCH\fP |
| Patch version if provided, else 0 |
| .TP |
| .B \fB<PackageName>_VERSION_TWEAK\fP |
| Tweak version if provided, else 0 |
| .TP |
| .B \fB<PackageName>_VERSION_COUNT\fP |
| Number of version components, 0 to 4 |
| .UNINDENT |
| .sp |
| and the corresponding package configuration file is loaded. |
| When multiple package configuration files are available whose version files |
| claim compatibility with the version requested it is unspecified which |
| one is chosen: unless the variable \fBCMAKE_FIND_PACKAGE_SORT_ORDER\fP |
| is set no attempt is made to choose a highest or closest version number. |
| .sp |
| To control the order in which \fBfind_package\fP checks for compatibility use |
| the two variables \fBCMAKE_FIND_PACKAGE_SORT_ORDER\fP and |
| \fBCMAKE_FIND_PACKAGE_SORT_DIRECTION\fP\&. |
| For instance in order to select the highest version one can set |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) |
| SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| before calling \fBfind_package\fP\&. |
| .SS Package File Interface Variables |
| .sp |
| When loading a find module or package configuration file \fBfind_package\fP |
| defines variables to provide information about the call arguments (and |
| restores their original state before returning): |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_FIND_PACKAGE_NAME\fP |
| The \fB<PackageName>\fP which is searched for |
| .TP |
| .B \fB<PackageName>_FIND_REQUIRED\fP |
| True if \fBREQUIRED\fP option was given |
| .TP |
| .B \fB<PackageName>_FIND_QUIETLY\fP |
| True if \fBQUIET\fP option was given |
| .TP |
| .B \fB<PackageName>_FIND_VERSION\fP |
| Full requested version string |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_MAJOR\fP |
| Major version if requested, else 0 |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_MINOR\fP |
| Minor version if requested, else 0 |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_PATCH\fP |
| Patch version if requested, else 0 |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_TWEAK\fP |
| Tweak version if requested, else 0 |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_COUNT\fP |
| Number of version components, 0 to 4 |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_EXACT\fP |
| True if \fBEXACT\fP option was given |
| .TP |
| .B \fB<PackageName>_FIND_COMPONENTS\fP |
| List of specified components (required and optional) |
| .TP |
| .B \fB<PackageName>_FIND_REQUIRED_<c>\fP |
| True if component \fB<c>\fP is required, |
| false if component \fB<c>\fP is optional |
| .UNINDENT |
| .sp |
| When a version range is specified, the above version variables will hold |
| values based on the lower end of the version range. This is to preserve |
| compatibility with packages that have not been implemented to expect version |
| ranges. In addition, the version range will be described by the following |
| variables: |
| .INDENT 0.0 |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_RANGE\fP |
| Full requested version range string |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_RANGE_MIN\fP |
| This specifies whether the lower end point of the version range is |
| included or excluded. Currently, \fBINCLUDE\fP is the only supported value. |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_RANGE_MAX\fP |
| This specifies whether the upper end point of the version range is |
| included or excluded. The possible values for this variable are |
| \fBINCLUDE\fP or \fBEXCLUDE\fP\&. |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_MIN\fP |
| Full requested version string of the lower end point of the range |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_MIN_MAJOR\fP |
| Major version of the lower end point if requested, else 0 |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_MIN_MINOR\fP |
| Minor version of the lower end point if requested, else 0 |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_MIN_PATCH\fP |
| Patch version of the lower end point if requested, else 0 |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_MIN_TWEAK\fP |
| Tweak version of the lower end point if requested, else 0 |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_MIN_COUNT\fP |
| Number of version components of the lower end point, 0 to 4 |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_MAX\fP |
| Full requested version string of the upper end point of the range |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_MAX_MAJOR\fP |
| Major version of the upper end point if requested, else 0 |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_MAX_MINOR\fP |
| Minor version of the upper end point if requested, else 0 |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_MAX_PATCH\fP |
| Patch version of the upper end point if requested, else 0 |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_MAX_TWEAK\fP |
| Tweak version of the upper end point if requested, else 0 |
| .TP |
| .B \fB<PackageName>_FIND_VERSION_MAX_COUNT\fP |
| Number of version components of the upper end point, 0 to 4 |
| .UNINDENT |
| .sp |
| Regardless of whether a single version or a version range is specified, the |
| variable \fB<PackageName>_FIND_VERSION_COMPLETE\fP will be defined and will hold |
| the full requested version string as specified. |
| .sp |
| In Module mode the loaded find module is responsible to honor the |
| request detailed by these variables; see the find module for details. |
| In Config mode \fBfind_package\fP handles \fBREQUIRED\fP, \fBQUIET\fP, and |
| \fB[version]\fP options automatically but leaves it to the package |
| configuration file to handle components in a way that makes sense |
| for the package. The package configuration file may set |
| \fB<PackageName>_FOUND\fP to false to tell \fBfind_package\fP that component |
| requirements are not satisfied. |
| .SS find_path |
| .sp |
| A short\-hand signature is: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_path (<VAR> name1 [path1 path2 ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The general signature is: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_path ( |
| <VAR> |
| name | NAMES name1 [name2 ...] |
| [HINTS [path | ENV var]... ] |
| [PATHS [path | ENV var]... ] |
| [PATH_SUFFIXES suffix1 [suffix2 ...]] |
| [DOC "cache documentation string"] |
| [NO_CACHE] |
| [REQUIRED] |
| [NO_DEFAULT_PATH] |
| [NO_PACKAGE_ROOT_PATH] |
| [NO_CMAKE_PATH] |
| [NO_CMAKE_ENVIRONMENT_PATH] |
| [NO_SYSTEM_ENVIRONMENT_PATH] |
| [NO_CMAKE_SYSTEM_PATH] |
| [CMAKE_FIND_ROOT_PATH_BOTH | |
| ONLY_CMAKE_FIND_ROOT_PATH | |
| NO_CMAKE_FIND_ROOT_PATH] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command is used to find a directory containing the named file\&. |
| A cache entry, or a normal variable if \fBNO_CACHE\fP is specified, |
| named by \fB<VAR>\fP is created to store the result of this command. |
| If the file in a directory is found the result is stored in the variable |
| and the search will not be repeated unless the variable is cleared. |
| If nothing is found, the result will be \fB<VAR>\-NOTFOUND\fP\&. |
| .sp |
| Options include: |
| .INDENT 0.0 |
| .TP |
| .B \fBNAMES\fP |
| Specify one or more possible names for the file in a directory\&. |
| .sp |
| When using this to specify names with and without a version |
| suffix, we recommend specifying the unversioned name first |
| so that locally\-built packages can be found before those |
| provided by distributions. |
| .TP |
| .B \fBHINTS\fP, \fBPATHS\fP |
| Specify directories to search in addition to the default locations. |
| The \fBENV var\fP sub\-option reads paths from a system environment |
| variable. |
| .TP |
| .B \fBPATH_SUFFIXES\fP |
| Specify additional subdirectories to check below each directory |
| location otherwise considered. |
| .TP |
| .B \fBDOC\fP |
| Specify the documentation string for the \fB<VAR>\fP cache entry. |
| .TP |
| .B \fBNO_CACHE\fP |
| New in version 3.21. |
| |
| .sp |
| The result of the search will be stored in a normal variable rather than |
| a cache entry. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| If the variable is already set before the call (as a normal or cache |
| variable) then the search will not occur. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBWARNING:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| This option should be used with caution because it can greatly increase |
| the cost of repeated configure steps. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBREQUIRED\fP |
| New in version 3.18. |
| |
| .sp |
| Stop processing with an error message if nothing is found, otherwise |
| the search will be attempted again the next time find_path is invoked |
| with the same variable. |
| .UNINDENT |
| .sp |
| If \fBNO_DEFAULT_PATH\fP is specified, then no additional paths are |
| added to the search. |
| If \fBNO_DEFAULT_PATH\fP is not specified, the search process is as follows: |
| .INDENT 0.0 |
| .IP 1. 3 |
| New in version 3.12: If called from within a find module or any other script loaded by a call to |
| \fBfind_package(<PackageName>)\fP, search prefixes unique to the |
| current package being found. Specifically, look in the |
| \fB<PackageName>_ROOT\fP CMake variable and the |
| \fB<PackageName>_ROOT\fP environment variable. |
| The package root variables are maintained as a stack, so if called from |
| nested find modules or config packages, root paths from the parent\(aqs find |
| module or config package will be searched after paths from the current |
| module or package. In other words, the search order would be |
| \fB<CurrentPackage>_ROOT\fP, \fBENV{<CurrentPackage>_ROOT}\fP, |
| \fB<ParentPackage>_ROOT\fP, \fBENV{<ParentPackage>_ROOT}\fP, etc. |
| This can be skipped if \fBNO_PACKAGE_ROOT_PATH\fP is passed or by setting |
| the \fBCMAKE_FIND_USE_PACKAGE_ROOT_PATH\fP to \fBFALSE\fP\&. |
| See policy \fBCMP0074\fP\&. |
| |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>\fP in the |
| \fB<PackageName>_ROOT\fP CMake variable and the |
| \fB<PackageName>_ROOT\fP environment variable if |
| called from within a find module loaded by |
| \fBfind_package(<PackageName>)\fP |
| .UNINDENT |
| .IP 2. 3 |
| Search paths specified in cmake\-specific cache variables. |
| These are intended to be used on the command line with a \fB\-DVAR=value\fP\&. |
| The values are interpreted as semicolon\-separated lists\&. |
| This can be skipped if \fBNO_CMAKE_PATH\fP is passed or by setting the |
| \fBCMAKE_FIND_USE_CMAKE_PATH\fP to \fBFALSE\fP\&. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>\fP in \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_INCLUDE_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_FRAMEWORK_PATH\fP |
| .UNINDENT |
| .IP 3. 3 |
| Search paths specified in cmake\-specific environment variables. |
| These are intended to be set in the user\(aqs shell configuration, |
| and therefore use the host\(aqs native path separator |
| (\fB;\fP on Windows and \fB:\fP on UNIX). |
| This can be skipped if \fBNO_CMAKE_ENVIRONMENT_PATH\fP is passed or |
| by setting the \fBCMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH\fP to \fBFALSE\fP\&. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>\fP in \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_INCLUDE_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_FRAMEWORK_PATH\fP |
| .UNINDENT |
| .IP 4. 3 |
| Search the paths specified by the \fBHINTS\fP option. |
| These should be paths computed by system introspection, such as a |
| hint provided by the location of another item already found. |
| Hard\-coded guesses should be specified with the \fBPATHS\fP option. |
| .IP 5. 3 |
| Search the standard system environment variables. |
| This can be skipped if \fBNO_SYSTEM_ENVIRONMENT_PATH\fP is passed or by |
| setting the \fBCMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH\fP to \fBFALSE\fP\&. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| The directories in \fBINCLUDE\fP |
| and \fBPATH\fP\&. |
| .IP \(bu 2 |
| On Windows hosts: |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>/[s]bin\fP in \fBPATH\fP, and |
| \fB<entry>/include\fP for other entries in \fBPATH\fP\&. |
| .UNINDENT |
| .IP 6. 3 |
| Search cmake variables defined in the Platform files |
| for the current system. This can be skipped if \fBNO_CMAKE_SYSTEM_PATH\fP |
| is passed or by setting the \fBCMAKE_FIND_USE_CMAKE_SYSTEM_PATH\fP |
| to \fBFALSE\fP\&. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>\fP in |
| \fBCMAKE_SYSTEM_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_INCLUDE_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_FRAMEWORK_PATH\fP |
| .UNINDENT |
| .sp |
| The platform paths that these variables contain are locations that |
| typically include installed software. An example being \fB/usr/local\fP for |
| UNIX based platforms. |
| .IP 7. 3 |
| Search the paths specified by the PATHS option |
| or in the short\-hand version of the command. |
| These are typically hard\-coded guesses. |
| .UNINDENT |
| .sp |
| The \fBCMAKE_IGNORE_PATH\fP, \fBCMAKE_IGNORE_PREFIX_PATH\fP, |
| \fBCMAKE_SYSTEM_IGNORE_PATH\fP and |
| \fBCMAKE_SYSTEM_IGNORE_PREFIX_PATH\fP variables can also cause some |
| of the above locations to be ignored. |
| .sp |
| New in version 3.16: Added \fBCMAKE_FIND_USE_<CATEGORY>_PATH\fP variables to globally disable |
| various search locations. |
| |
| .sp |
| On macOS the \fBCMAKE_FIND_FRAMEWORK\fP and |
| \fBCMAKE_FIND_APPBUNDLE\fP variables determine the order of |
| preference between Apple\-style and unix\-style package components. |
| .sp |
| The CMake variable \fBCMAKE_FIND_ROOT_PATH\fP specifies one or more |
| directories to be prepended to all other search directories. This |
| effectively "re\-roots" the entire search under given locations. |
| Paths which are descendants of the \fBCMAKE_STAGING_PREFIX\fP are excluded |
| from this re\-rooting, because that variable is always a path on the host system. |
| By default the \fBCMAKE_FIND_ROOT_PATH\fP is empty. |
| .sp |
| The \fBCMAKE_SYSROOT\fP variable can also be used to specify exactly one |
| directory to use as a prefix. Setting \fBCMAKE_SYSROOT\fP also has other |
| effects. See the documentation for that variable for more. |
| .sp |
| These variables are especially useful when cross\-compiling to |
| point to the root directory of the target environment and CMake will |
| search there too. By default at first the directories listed in |
| \fBCMAKE_FIND_ROOT_PATH\fP are searched, then the \fBCMAKE_SYSROOT\fP |
| directory is searched, and then the non\-rooted directories will be |
| searched. The default behavior can be adjusted by setting |
| \fBCMAKE_FIND_ROOT_PATH_MODE_INCLUDE\fP\&. This behavior can be manually |
| overridden on a per\-call basis using options: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_FIND_ROOT_PATH_BOTH\fP |
| Search in the order described above. |
| .TP |
| .B \fBNO_CMAKE_FIND_ROOT_PATH\fP |
| Do not use the \fBCMAKE_FIND_ROOT_PATH\fP variable. |
| .TP |
| .B \fBONLY_CMAKE_FIND_ROOT_PATH\fP |
| Search only the re\-rooted directories and directories below |
| \fBCMAKE_STAGING_PREFIX\fP\&. |
| .UNINDENT |
| .sp |
| The default search order is designed to be most\-specific to |
| least\-specific for common use cases. |
| Projects may override the order by simply calling the command |
| multiple times and using the \fBNO_*\fP options: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH) |
| find_path (<VAR> NAMES name) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Once one of the calls succeeds the result variable will be set |
| and stored in the cache so that no call will search again. |
| .sp |
| When searching for frameworks, if the file is specified as \fBA/b.h\fP, then |
| the framework search will look for \fBA.framework/Headers/b.h\fP\&. If that |
| is found the path will be set to the path to the framework. CMake |
| will convert this to the correct \fB\-F\fP option to include the file. |
| .SS find_program |
| .sp |
| A short\-hand signature is: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_program (<VAR> name1 [path1 path2 ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The general signature is: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_program ( |
| <VAR> |
| name | NAMES name1 [name2 ...] [NAMES_PER_DIR] |
| [HINTS [path | ENV var]... ] |
| [PATHS [path | ENV var]... ] |
| [PATH_SUFFIXES suffix1 [suffix2 ...]] |
| [DOC "cache documentation string"] |
| [NO_CACHE] |
| [REQUIRED] |
| [NO_DEFAULT_PATH] |
| [NO_PACKAGE_ROOT_PATH] |
| [NO_CMAKE_PATH] |
| [NO_CMAKE_ENVIRONMENT_PATH] |
| [NO_SYSTEM_ENVIRONMENT_PATH] |
| [NO_CMAKE_SYSTEM_PATH] |
| [CMAKE_FIND_ROOT_PATH_BOTH | |
| ONLY_CMAKE_FIND_ROOT_PATH | |
| NO_CMAKE_FIND_ROOT_PATH] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command is used to find a program\&. |
| A cache entry, or a normal variable if \fBNO_CACHE\fP is specified, |
| named by \fB<VAR>\fP is created to store the result of this command. |
| If the program is found the result is stored in the variable |
| and the search will not be repeated unless the variable is cleared. |
| If nothing is found, the result will be \fB<VAR>\-NOTFOUND\fP\&. |
| .sp |
| Options include: |
| .INDENT 0.0 |
| .TP |
| .B \fBNAMES\fP |
| Specify one or more possible names for the program\&. |
| .sp |
| When using this to specify names with and without a version |
| suffix, we recommend specifying the unversioned name first |
| so that locally\-built packages can be found before those |
| provided by distributions. |
| .TP |
| .B \fBHINTS\fP, \fBPATHS\fP |
| Specify directories to search in addition to the default locations. |
| The \fBENV var\fP sub\-option reads paths from a system environment |
| variable. |
| .TP |
| .B \fBPATH_SUFFIXES\fP |
| Specify additional subdirectories to check below each directory |
| location otherwise considered. |
| .TP |
| .B \fBDOC\fP |
| Specify the documentation string for the \fB<VAR>\fP cache entry. |
| .TP |
| .B \fBNO_CACHE\fP |
| New in version 3.21. |
| |
| .sp |
| The result of the search will be stored in a normal variable rather than |
| a cache entry. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| If the variable is already set before the call (as a normal or cache |
| variable) then the search will not occur. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBWARNING:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| This option should be used with caution because it can greatly increase |
| the cost of repeated configure steps. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBREQUIRED\fP |
| New in version 3.18. |
| |
| .sp |
| Stop processing with an error message if nothing is found, otherwise |
| the search will be attempted again the next time find_program is invoked |
| with the same variable. |
| .UNINDENT |
| .sp |
| If \fBNO_DEFAULT_PATH\fP is specified, then no additional paths are |
| added to the search. |
| If \fBNO_DEFAULT_PATH\fP is not specified, the search process is as follows: |
| .INDENT 0.0 |
| .IP 1. 3 |
| New in version 3.12: If called from within a find module or any other script loaded by a call to |
| \fBfind_package(<PackageName>)\fP, search prefixes unique to the |
| current package being found. Specifically, look in the |
| \fB<PackageName>_ROOT\fP CMake variable and the |
| \fB<PackageName>_ROOT\fP environment variable. |
| The package root variables are maintained as a stack, so if called from |
| nested find modules or config packages, root paths from the parent\(aqs find |
| module or config package will be searched after paths from the current |
| module or package. In other words, the search order would be |
| \fB<CurrentPackage>_ROOT\fP, \fBENV{<CurrentPackage>_ROOT}\fP, |
| \fB<ParentPackage>_ROOT\fP, \fBENV{<ParentPackage>_ROOT}\fP, etc. |
| This can be skipped if \fBNO_PACKAGE_ROOT_PATH\fP is passed or by setting |
| the \fBCMAKE_FIND_USE_PACKAGE_ROOT_PATH\fP to \fBFALSE\fP\&. |
| See policy \fBCMP0074\fP\&. |
| |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/[s]bin\fP for each \fB<prefix>\fP in the |
| \fB<PackageName>_ROOT\fP CMake variable and the |
| \fB<PackageName>_ROOT\fP environment variable if |
| called from within a find module loaded by |
| \fBfind_package(<PackageName>)\fP |
| .UNINDENT |
| .IP 2. 3 |
| Search paths specified in cmake\-specific cache variables. |
| These are intended to be used on the command line with a \fB\-DVAR=value\fP\&. |
| The values are interpreted as semicolon\-separated lists\&. |
| This can be skipped if \fBNO_CMAKE_PATH\fP is passed or by setting the |
| \fBCMAKE_FIND_USE_CMAKE_PATH\fP to \fBFALSE\fP\&. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/[s]bin\fP for each \fB<prefix>\fP in \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_PROGRAM_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_APPBUNDLE_PATH\fP |
| .UNINDENT |
| .IP 3. 3 |
| Search paths specified in cmake\-specific environment variables. |
| These are intended to be set in the user\(aqs shell configuration, |
| and therefore use the host\(aqs native path separator |
| (\fB;\fP on Windows and \fB:\fP on UNIX). |
| This can be skipped if \fBNO_CMAKE_ENVIRONMENT_PATH\fP is passed or |
| by setting the \fBCMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH\fP to \fBFALSE\fP\&. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/[s]bin\fP for each \fB<prefix>\fP in \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_PROGRAM_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_APPBUNDLE_PATH\fP |
| .UNINDENT |
| .IP 4. 3 |
| Search the paths specified by the \fBHINTS\fP option. |
| These should be paths computed by system introspection, such as a |
| hint provided by the location of another item already found. |
| Hard\-coded guesses should be specified with the \fBPATHS\fP option. |
| .IP 5. 3 |
| Search the standard system environment variables. |
| This can be skipped if \fBNO_SYSTEM_ENVIRONMENT_PATH\fP is passed or by |
| setting the \fBCMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH\fP to \fBFALSE\fP\&. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| The directories in \fBPATH\fP itself. |
| .IP \(bu 2 |
| On Windows hosts no extra search paths are included |
| .UNINDENT |
| .IP 6. 3 |
| Search cmake variables defined in the Platform files |
| for the current system. This can be skipped if \fBNO_CMAKE_SYSTEM_PATH\fP |
| is passed or by setting the \fBCMAKE_FIND_USE_CMAKE_SYSTEM_PATH\fP |
| to \fBFALSE\fP\&. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/[s]bin\fP for each \fB<prefix>\fP in |
| \fBCMAKE_SYSTEM_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_PROGRAM_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_APPBUNDLE_PATH\fP |
| .UNINDENT |
| .sp |
| The platform paths that these variables contain are locations that |
| typically include installed software. An example being \fB/usr/local\fP for |
| UNIX based platforms. |
| .IP 7. 3 |
| Search the paths specified by the PATHS option |
| or in the short\-hand version of the command. |
| These are typically hard\-coded guesses. |
| .UNINDENT |
| .sp |
| The \fBCMAKE_IGNORE_PATH\fP, \fBCMAKE_IGNORE_PREFIX_PATH\fP, |
| \fBCMAKE_SYSTEM_IGNORE_PATH\fP and |
| \fBCMAKE_SYSTEM_IGNORE_PREFIX_PATH\fP variables can also cause some |
| of the above locations to be ignored. |
| .sp |
| New in version 3.16: Added \fBCMAKE_FIND_USE_<CATEGORY>_PATH\fP variables to globally disable |
| various search locations. |
| |
| .sp |
| On macOS the \fBCMAKE_FIND_FRAMEWORK\fP and |
| \fBCMAKE_FIND_APPBUNDLE\fP variables determine the order of |
| preference between Apple\-style and unix\-style package components. |
| .sp |
| The CMake variable \fBCMAKE_FIND_ROOT_PATH\fP specifies one or more |
| directories to be prepended to all other search directories. This |
| effectively "re\-roots" the entire search under given locations. |
| Paths which are descendants of the \fBCMAKE_STAGING_PREFIX\fP are excluded |
| from this re\-rooting, because that variable is always a path on the host system. |
| By default the \fBCMAKE_FIND_ROOT_PATH\fP is empty. |
| .sp |
| The \fBCMAKE_SYSROOT\fP variable can also be used to specify exactly one |
| directory to use as a prefix. Setting \fBCMAKE_SYSROOT\fP also has other |
| effects. See the documentation for that variable for more. |
| .sp |
| These variables are especially useful when cross\-compiling to |
| point to the root directory of the target environment and CMake will |
| search there too. By default at first the directories listed in |
| \fBCMAKE_FIND_ROOT_PATH\fP are searched, then the \fBCMAKE_SYSROOT\fP |
| directory is searched, and then the non\-rooted directories will be |
| searched. The default behavior can be adjusted by setting |
| \fBCMAKE_FIND_ROOT_PATH_MODE_PROGRAM\fP\&. This behavior can be manually |
| overridden on a per\-call basis using options: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_FIND_ROOT_PATH_BOTH\fP |
| Search in the order described above. |
| .TP |
| .B \fBNO_CMAKE_FIND_ROOT_PATH\fP |
| Do not use the \fBCMAKE_FIND_ROOT_PATH\fP variable. |
| .TP |
| .B \fBONLY_CMAKE_FIND_ROOT_PATH\fP |
| Search only the re\-rooted directories and directories below |
| \fBCMAKE_STAGING_PREFIX\fP\&. |
| .UNINDENT |
| .sp |
| The default search order is designed to be most\-specific to |
| least\-specific for common use cases. |
| Projects may override the order by simply calling the command |
| multiple times and using the \fBNO_*\fP options: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| find_program (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH) |
| find_program (<VAR> NAMES name) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Once one of the calls succeeds the result variable will be set |
| and stored in the cache so that no call will search again. |
| .sp |
| When more than one value is given to the \fBNAMES\fP option this command by |
| default will consider one name at a time and search every directory |
| for it. The \fBNAMES_PER_DIR\fP option tells this command to consider one |
| directory at a time and search for all names in it. |
| .SS foreach |
| .sp |
| Evaluate a group of commands for each value in a list. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| foreach(<loop_var> <items>) |
| <commands> |
| endforeach() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| where \fB<items>\fP is a list of items that are separated by |
| semicolon or whitespace. |
| All commands between \fBforeach\fP and the matching \fBendforeach\fP are recorded |
| without being invoked. Once the \fBendforeach\fP is evaluated, the recorded |
| list of commands is invoked once for each item in \fB<items>\fP\&. |
| At the beginning of each iteration the variable \fB<loop_var>\fP will be set |
| to the value of the current item. |
| .sp |
| The scope of \fB<loop_var>\fP is restricted to the loop scope. See policy |
| \fBCMP0124\fP for details. |
| .sp |
| The commands \fBbreak()\fP and \fBcontinue()\fP provide means to |
| escape from the normal control flow. |
| .sp |
| Per legacy, the \fBendforeach()\fP command admits |
| an optional \fB<loop_var>\fP argument. |
| If used, it must be a verbatim |
| repeat of the argument of the opening |
| \fBforeach\fP command. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| foreach(<loop_var> RANGE <stop>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In this variant, \fBforeach\fP iterates over the numbers |
| 0, 1, ... up to (and including) the nonnegative integer \fB<stop>\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| foreach(<loop_var> RANGE <start> <stop> [<step>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In this variant, \fBforeach\fP iterates over the numbers from |
| \fB<start>\fP up to at most \fB<stop>\fP in steps of \fB<step>\fP\&. |
| If \fB<step>\fP is not specified, then the step size is 1. |
| The three arguments \fB<start>\fP \fB<stop>\fP \fB<step>\fP must |
| all be nonnegative integers, and \fB<stop>\fP must not be |
| smaller than \fB<start>\fP; otherwise you enter the danger zone |
| of undocumented behavior that may change in future releases. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| foreach(<loop_var> IN [LISTS [<lists>]] [ITEMS [<items>]]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In this variant, \fB<lists>\fP is a whitespace or semicolon |
| separated list of list\-valued variables. The \fBforeach\fP |
| command iterates over each item in each given list. |
| The \fB<items>\fP following the \fBITEMS\fP keyword are processed |
| as in the first variant of the \fBforeach\fP command. |
| The forms \fBLISTS A\fP and \fBITEMS ${A}\fP are |
| equivalent. |
| .sp |
| The following example shows how the \fBLISTS\fP option is |
| processed: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(A 0;1) |
| set(B 2 3) |
| set(C "4 5") |
| set(D 6;7 8) |
| set(E "") |
| foreach(X IN LISTS A B C D E) |
| message(STATUS "X=${X}") |
| endforeach() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| yields |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \-\- X=0 |
| \-\- X=1 |
| \-\- X=2 |
| \-\- X=3 |
| \-\- X=4 5 |
| \-\- X=6 |
| \-\- X=7 |
| \-\- X=8 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| foreach(<loop_var>... IN ZIP_LISTS <lists>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.17. |
| |
| .sp |
| In this variant, \fB<lists>\fP is a whitespace or semicolon |
| separated list of list\-valued variables. The \fBforeach\fP |
| command iterates over each list simultaneously setting the |
| iteration variables as follows: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| if the only \fBloop_var\fP given, then it sets a series of |
| \fBloop_var_N\fP variables to the current item from the |
| corresponding list; |
| .IP \(bu 2 |
| if multiple variable names passed, their count should match |
| the lists variables count; |
| .IP \(bu 2 |
| if any of the lists are shorter, the corresponding iteration |
| variable is not defined for the current iteration. |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(APPEND English one two three four) |
| list(APPEND Bahasa satu dua tiga) |
| |
| foreach(num IN ZIP_LISTS English Bahasa) |
| message(STATUS "num_0=${num_0}, num_1=${num_1}") |
| endforeach() |
| |
| foreach(en ba IN ZIP_LISTS English Bahasa) |
| message(STATUS "en=${en}, ba=${ba}") |
| endforeach() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| yields |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \-\- num_0=one, num_1=satu |
| \-\- num_0=two, num_1=dua |
| \-\- num_0=three, num_1=tiga |
| \-\- num_0=four, num_1= |
| \-\- en=one, ba=satu |
| \-\- en=two, ba=dua |
| \-\- en=three, ba=tiga |
| \-\- en=four, ba= |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS function |
| .sp |
| Start recording a function for later invocation as a command. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| function(<name> [<arg1> ...]) |
| <commands> |
| endfunction() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Defines a function named \fB<name>\fP that takes arguments named |
| \fB<arg1>\fP, ... The \fB<commands>\fP in the function definition |
| are recorded; they are not executed until the function is invoked. |
| .sp |
| Per legacy, the \fBendfunction()\fP command admits an optional |
| \fB<name>\fP argument. If used, it must be a verbatim repeat of the |
| argument of the opening \fBfunction\fP command. |
| .sp |
| A function opens a new scope: see \fBset(var PARENT_SCOPE)\fP for |
| details. |
| .sp |
| See the \fBcmake_policy()\fP command documentation for the behavior |
| of policies inside functions. |
| .sp |
| See the \fBmacro()\fP command documentation for differences |
| between CMake functions and macros. |
| .SS Invocation |
| .sp |
| The function invocation is case\-insensitive. A function defined as |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| function(foo) |
| <commands> |
| endfunction() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| can be invoked through any of |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| foo() |
| Foo() |
| FOO() |
| cmake_language(CALL foo) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| and so on. However, it is strongly recommended to stay with the |
| case chosen in the function definition. Typically functions use |
| all\-lowercase names. |
| .sp |
| New in version 3.18: The \fBcmake_language(CALL ...)\fP command can also be used to |
| invoke the function. |
| |
| .SS Arguments |
| .sp |
| When the function is invoked, the recorded \fB<commands>\fP are first |
| modified by replacing formal parameters (\fB${arg1}\fP, ...) with the |
| arguments passed, and then invoked as normal commands. |
| .sp |
| In addition to referencing the formal parameters you can reference the |
| \fBARGC\fP variable which will be set to the number of arguments passed |
| into the function as well as \fBARGV0\fP, \fBARGV1\fP, \fBARGV2\fP, ... which |
| will have the actual values of the arguments passed in. This facilitates |
| creating functions with optional arguments. |
| .sp |
| Furthermore, \fBARGV\fP holds the list of all arguments given to the |
| function and \fBARGN\fP holds the list of arguments past the last expected |
| argument. Referencing to \fBARGV#\fP arguments beyond \fBARGC\fP have |
| undefined behavior. Checking that \fBARGC\fP is greater than \fB#\fP is |
| the only way to ensure that \fBARGV#\fP was passed to the function as an |
| extra argument. |
| .SS get_cmake_property |
| .sp |
| Get a global property of the CMake instance. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_cmake_property(<var> <property>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Gets a global property from the CMake instance. The value of |
| the \fB<property>\fP is stored in the variable \fB<var>\fP\&. |
| If the property is not found, \fB<var>\fP will be set to \fBNOTFOUND\fP\&. |
| See the \fBcmake\-properties(7)\fP manual for available properties. |
| .sp |
| See also the \fBget_property()\fP command \fBGLOBAL\fP option. |
| .sp |
| In addition to global properties, this command (for historical reasons) |
| also supports the \fBVARIABLES\fP and \fBMACROS\fP directory |
| properties. It also supports a special \fBCOMPONENTS\fP global property that |
| lists the components given to the \fBinstall()\fP command. |
| .SS get_directory_property |
| .sp |
| Get a property of \fBDIRECTORY\fP scope. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_directory_property(<variable> [DIRECTORY <dir>] <prop\-name>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Stores a property of directory scope in the named \fB<variable>\fP\&. |
| .sp |
| The \fBDIRECTORY\fP argument specifies another directory from which |
| to retrieve the property value instead of the current directory. |
| Relative paths are treated as relative to the |
| current source directory. CMake must already know about the directory, |
| either by having added it through a call to \fBadd_subdirectory()\fP |
| or being the top level directory. |
| .sp |
| New in version 3.19: \fB<dir>\fP may reference a binary directory. |
| |
| .sp |
| If the property is not defined for the nominated directory scope, |
| an empty string is returned. In the case of \fBINHERITED\fP properties, |
| if the property is not found for the nominated directory scope, |
| the search will chain to a parent scope as described for the |
| \fBdefine_property()\fP command. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_directory_property(<variable> [DIRECTORY <dir>] |
| DEFINITION <var\-name>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Get a variable definition from a directory. This form is useful to |
| get a variable definition from another directory. |
| .sp |
| See also the more general \fBget_property()\fP command. |
| .SS get_filename_component |
| .sp |
| Get a specific component of a full filename. |
| .sp |
| Changed in version 3.20: This command been superseded by \fBcmake_path()\fP command, except |
| \fBREALPATH\fP now offered by file(REAL_PATH) command and |
| \fBPROGRAM\fP now available in \fBseparate_arguments(PROGRAM)\fP command. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_filename_component(<var> <FileName> <mode> [CACHE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets \fB<var>\fP to a component of \fB<FileName>\fP, where \fB<mode>\fP is one of: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| DIRECTORY = Directory without file name |
| NAME = File name without directory |
| EXT = File name longest extension (.b.c from d/a.b.c) |
| NAME_WE = File name with neither the directory nor the longest extension |
| LAST_EXT = File name last extension (.c from d/a.b.c) |
| NAME_WLE = File name with neither the directory nor the last extension |
| PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.14: Added the \fBLAST_EXT\fP and \fBNAME_WLE\fP modes. |
| |
| .sp |
| Paths are returned with forward slashes and have no trailing slashes. |
| If the optional \fBCACHE\fP argument is specified, the result variable is |
| added to the cache. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Sets \fB<var>\fP to the absolute path of \fB<FileName>\fP, where \fB<mode>\fP is one |
| of: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ABSOLUTE = Full path to file |
| REALPATH = Full path to existing file with symlinks resolved |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If the provided \fB<FileName>\fP is a relative path, it is evaluated relative |
| to the given base directory \fB<dir>\fP\&. If no base directory is |
| provided, the default base directory will be |
| \fBCMAKE_CURRENT_SOURCE_DIR\fP\&. |
| .sp |
| Paths are returned with forward slashes and have no trailing slashes. If the |
| optional \fBCACHE\fP argument is specified, the result variable is added to the |
| cache. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The program in \fB<FileName>\fP will be found in the system search path or |
| left as a full path. If \fBPROGRAM_ARGS\fP is present with \fBPROGRAM\fP, then |
| any command\-line arguments present in the \fB<FileName>\fP string are split |
| from the program name and stored in \fB<arg_var>\fP\&. This is used to |
| separate a program name from its arguments in a command line string. |
| .SS get_property |
| .sp |
| Get a property. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_property(<variable> |
| <GLOBAL | |
| DIRECTORY [<dir>] | |
| TARGET <target> | |
| SOURCE <source> |
| [DIRECTORY <dir> | TARGET_DIRECTORY <target>] | |
| INSTALL <file> | |
| TEST <test> | |
| CACHE <entry> | |
| VARIABLE > |
| PROPERTY <name> |
| [SET | DEFINED | BRIEF_DOCS | FULL_DOCS]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Gets one property from one object in a scope. |
| .sp |
| The first argument specifies the variable in which to store the result. |
| The second argument determines the scope from which to get the property. |
| It must be one of the following: |
| .INDENT 0.0 |
| .TP |
| .B \fBGLOBAL\fP |
| Scope is unique and does not accept a name. |
| .TP |
| .B \fBDIRECTORY\fP |
| Scope defaults to the current directory but another |
| directory (already processed by CMake) may be named by the |
| full or relative path \fB<dir>\fP\&. |
| Relative paths are treated as relative to the current source directory. |
| See also the \fBget_directory_property()\fP command. |
| .sp |
| New in version 3.19: \fB<dir>\fP may reference a binary directory. |
| |
| .TP |
| .B \fBTARGET\fP |
| Scope must name one existing target. |
| See also the \fBget_target_property()\fP command. |
| .TP |
| .B \fBSOURCE\fP |
| Scope must name one source file. By default, the source file\(aqs property |
| will be read from the current source directory\(aqs scope. |
| .sp |
| New in version 3.18: Directory scope can be overridden with one of the following sub\-options: |
| .INDENT 7.0 |
| .TP |
| .B \fBDIRECTORY <dir>\fP |
| The source file property will be read from the \fB<dir>\fP directory\(aqs |
| scope. CMake must already know about |
| the directory, either by having added it through a call |
| to \fBadd_subdirectory()\fP or \fB<dir>\fP being the top level directory. |
| Relative paths are treated as relative to the current source directory. |
| .sp |
| New in version 3.19: \fB<dir>\fP may reference a binary directory. |
| |
| .TP |
| .B \fBTARGET_DIRECTORY <target>\fP |
| The source file property will be read from the directory scope in which |
| \fB<target>\fP was created (\fB<target>\fP must therefore already exist). |
| .UNINDENT |
| |
| .sp |
| See also the \fBget_source_file_property()\fP command. |
| .TP |
| .B \fBINSTALL\fP |
| New in version 3.1. |
| |
| .sp |
| Scope must name one installed file path. |
| .TP |
| .B \fBTEST\fP |
| Scope must name one existing test. |
| See also the \fBget_test_property()\fP command. |
| .TP |
| .B \fBCACHE\fP |
| Scope must name one cache entry. |
| .TP |
| .B \fBVARIABLE\fP |
| Scope is unique and does not accept a name. |
| .UNINDENT |
| .sp |
| The required \fBPROPERTY\fP option is immediately followed by the name of |
| the property to get. If the property is not set an empty value is |
| returned, although some properties support inheriting from a parent scope |
| if defined to behave that way (see \fBdefine_property()\fP). |
| .sp |
| If the \fBSET\fP option is given the variable is set to a boolean |
| value indicating whether the property has been set. If the \fBDEFINED\fP |
| option is given the variable is set to a boolean value indicating |
| whether the property has been defined such as with the |
| \fBdefine_property()\fP command. |
| .sp |
| If \fBBRIEF_DOCS\fP or \fBFULL_DOCS\fP is given then the variable is set to a |
| string containing documentation for the requested property. If |
| documentation is requested for a property that has not been defined |
| \fBNOTFOUND\fP is returned. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The \fBGENERATED\fP source file property may be globally visible. |
| See its documentation for details. |
| .UNINDENT |
| .UNINDENT |
| .SS if |
| .sp |
| Conditionally execute a group of commands. |
| .SS Synopsis |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| if(<condition>) |
| <commands> |
| elseif(<condition>) # optional block, can be repeated |
| <commands> |
| else() # optional block |
| <commands> |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Evaluates the \fBcondition\fP argument of the \fBif\fP clause according to the |
| \fI\%Condition syntax\fP described below. If the result is true, then the |
| \fBcommands\fP in the \fBif\fP block are executed. |
| Otherwise, optional \fBelseif\fP blocks are processed in the same way. |
| Finally, if no \fBcondition\fP is true, \fBcommands\fP in the optional \fBelse\fP |
| block are executed. |
| .sp |
| Per legacy, the \fBelse()\fP and \fBendif()\fP commands admit |
| an optional \fB<condition>\fP argument. |
| If used, it must be a verbatim |
| repeat of the argument of the opening |
| \fBif\fP command. |
| .SS Condition Syntax |
| .sp |
| The following syntax applies to the \fBcondition\fP argument of |
| the \fBif\fP, \fBelseif\fP and \fBwhile()\fP clauses. |
| .sp |
| Compound conditions are evaluated in the following order of precedence: |
| .INDENT 0.0 |
| .IP 1. 3 |
| Parentheses. |
| .IP 2. 3 |
| Unary tests such as \fI\%EXISTS\fP, \fI\%COMMAND\fP, and \fI\%DEFINED\fP\&. |
| .IP 3. 3 |
| Binary tests such as \fI\%EQUAL\fP, \fI\%LESS\fP, \fI\%LESS_EQUAL\fP, \fI\%GREATER\fP, |
| \fI\%GREATER_EQUAL\fP, \fI\%STREQUAL\fP, \fI\%STRLESS\fP, \fI\%STRLESS_EQUAL\fP, |
| \fI\%STRGREATER\fP, \fI\%STRGREATER_EQUAL\fP, \fI\%VERSION_EQUAL\fP, \fI\%VERSION_LESS\fP, |
| \fI\%VERSION_LESS_EQUAL\fP, \fI\%VERSION_GREATER\fP, \fI\%VERSION_GREATER_EQUAL\fP, |
| and \fI\%MATCHES\fP\&. |
| .IP 4. 3 |
| Unary logical operator \fI\%NOT\fP\&. |
| .IP 5. 3 |
| Binary logical operators \fI\%AND\fP and \fI\%OR\fP, from left to right, |
| without any short\-circuit. |
| .UNINDENT |
| .SS Basic Expressions |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<constant>)\fP |
| True if the constant is \fB1\fP, \fBON\fP, \fBYES\fP, \fBTRUE\fP, \fBY\fP, |
| or a non\-zero number (including floating point numbers). |
| False if the constant is \fB0\fP, \fBOFF\fP, |
| \fBNO\fP, \fBFALSE\fP, \fBN\fP, \fBIGNORE\fP, \fBNOTFOUND\fP, the empty string, |
| or ends in the suffix \fB\-NOTFOUND\fP\&. Named boolean constants are |
| case\-insensitive. If the argument is not one of these specific |
| constants, it is treated as a variable or string (see \fI\%Variable Expansion\fP |
| further below) and one of the following two forms applies. |
| .TP |
| .B \fBif(<variable>)\fP |
| True if given a variable that is defined to a value that is not a false |
| constant. False otherwise, including if the variable is undefined. |
| Note that macro arguments are not variables. |
| Environment variables also cannot be tested this way, e.g. |
| \fBif(ENV{some_var})\fP will always evaluate to false. |
| .TP |
| .B \fBif(<string>)\fP |
| A quoted string always evaluates to false unless: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| The string\(aqs value is one of the true constants, or |
| .IP \(bu 2 |
| Policy \fBCMP0054\fP is not set to \fBNEW\fP and the string\(aqs value |
| happens to be a variable name that is affected by \fBCMP0054\fP\(aqs |
| behavior. |
| .UNINDENT |
| .UNINDENT |
| .SS Logic Operators |
| .INDENT 0.0 |
| .TP |
| .B \fBif(NOT <condition>)\fP |
| True if the condition is not true. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<cond1> AND <cond2>)\fP |
| True if both conditions would be considered true individually. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<cond1> OR <cond2>)\fP |
| True if either condition would be considered true individually. |
| .TP |
| .B \fBif((condition) AND (condition OR (condition)))\fP |
| The conditions inside the parenthesis are evaluated first and then |
| the remaining condition is evaluated as in the other examples. |
| Where there are nested parenthesis the innermost are evaluated as part |
| of evaluating the condition that contains them. |
| .UNINDENT |
| .SS Existence Checks |
| .INDENT 0.0 |
| .TP |
| .B \fBif(COMMAND command\-name)\fP |
| True if the given name is a command, macro or function that can be |
| invoked. |
| .TP |
| .B \fBif(POLICY policy\-id)\fP |
| True if the given name is an existing policy (of the form \fBCMP<NNNN>\fP). |
| .TP |
| .B \fBif(TARGET target\-name)\fP |
| True if the given name is an existing logical target name created |
| by a call to the \fBadd_executable()\fP, \fBadd_library()\fP, |
| or \fBadd_custom_target()\fP command that has already been invoked |
| (in any directory). |
| .TP |
| .B \fBif(TEST test\-name)\fP |
| New in version 3.3: True if the given name is an existing test name created by the |
| \fBadd_test()\fP command. |
| |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(DEFINED <name>|CACHE{<name>}|ENV{<name>})\fP |
| True if a variable, cache variable or environment variable |
| with given \fB<name>\fP is defined. The value of the variable |
| does not matter. Note the following caveats: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| Macro arguments are not variables. |
| .IP \(bu 2 |
| It is not possible to test directly whether a \fI<name>\fP is a non\-cache |
| variable. The expression \fBif(DEFINED someName)\fP will evaluate to true |
| if either a cache or non\-cache variable \fBsomeName\fP exists. In |
| comparison, the expression \fBif(DEFINED CACHE{someName})\fP will only |
| evaluate to true if a cache variable \fBsomeName\fP exists. Both expressions |
| need to be tested if you need to know whether a non\-cache variable exists: |
| \fBif(DEFINED someName AND NOT DEFINED CACHE{someName})\fP\&. |
| .UNINDENT |
| .sp |
| New in version 3.14: Added support for \fBCACHE{<name>}\fP variables. |
| |
| .TP |
| .B \fBif(<variable|string> IN_LIST <variable>)\fP |
| New in version 3.3: True if the given element is contained in the named list variable. |
| |
| .UNINDENT |
| .SS File Operations |
| .INDENT 0.0 |
| .TP |
| .B \fBif(EXISTS path\-to\-file\-or\-directory)\fP |
| True if the named file or directory exists. Behavior is well\-defined |
| only for explicit full paths (a leading \fB~/\fP is not expanded as |
| a home directory and is considered a relative path). |
| Resolves symbolic links, i.e. if the named file or directory is a |
| symbolic link, returns true if the target of the symbolic link exists. |
| .TP |
| .B \fBif(file1 IS_NEWER_THAN file2)\fP |
| True if \fBfile1\fP is newer than \fBfile2\fP or if one of the two files doesn\(aqt |
| exist. Behavior is well\-defined only for full paths. If the file |
| time stamps are exactly the same, an \fBIS_NEWER_THAN\fP comparison returns |
| true, so that any dependent build operations will occur in the event |
| of a tie. This includes the case of passing the same file name for |
| both file1 and file2. |
| .TP |
| .B \fBif(IS_DIRECTORY path\-to\-directory)\fP |
| True if the given name is a directory. Behavior is well\-defined only |
| for full paths. |
| .TP |
| .B \fBif(IS_SYMLINK file\-name)\fP |
| True if the given name is a symbolic link. Behavior is well\-defined |
| only for full paths. |
| .TP |
| .B \fBif(IS_ABSOLUTE path)\fP |
| True if the given path is an absolute path. Note the following special |
| cases: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| An empty \fBpath\fP evaluates to false. |
| .IP \(bu 2 |
| On Windows hosts, any \fBpath\fP that begins with a drive letter and colon |
| (e.g. \fBC:\fP), a forward slash or a backslash will evaluate to true. |
| This means a path like \fBC:no\ebase\edir\fP will evaluate to true, even |
| though the non\-drive part of the path is relative. |
| .IP \(bu 2 |
| On non\-Windows hosts, any \fBpath\fP that begins with a tilde (\fB~\fP) |
| evaluates to true. |
| .UNINDENT |
| .UNINDENT |
| .SS Comparisons |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<variable|string> MATCHES regex)\fP |
| True if the given string or variable\(aqs value matches the given regular |
| expression. See Regex Specification for regex format. |
| .sp |
| New in version 3.9: \fB()\fP groups are captured in \fBCMAKE_MATCH_<n>\fP variables. |
| |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<variable|string> LESS <variable|string>)\fP |
| True if the given string or variable\(aqs value is a valid number and less |
| than that on the right. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<variable|string> GREATER <variable|string>)\fP |
| True if the given string or variable\(aqs value is a valid number and greater |
| than that on the right. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<variable|string> EQUAL <variable|string>)\fP |
| True if the given string or variable\(aqs value is a valid number and equal |
| to that on the right. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<variable|string> LESS_EQUAL <variable|string>)\fP |
| New in version 3.7: True if the given string or variable\(aqs value is a valid number and less |
| than or equal to that on the right. |
| |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<variable|string> GREATER_EQUAL <variable|string>)\fP |
| New in version 3.7: True if the given string or variable\(aqs value is a valid number and greater |
| than or equal to that on the right. |
| |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<variable|string> STRLESS <variable|string>)\fP |
| True if the given string or variable\(aqs value is lexicographically less |
| than the string or variable on the right. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<variable|string> STRGREATER <variable|string>)\fP |
| True if the given string or variable\(aqs value is lexicographically greater |
| than the string or variable on the right. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<variable|string> STREQUAL <variable|string>)\fP |
| True if the given string or variable\(aqs value is lexicographically equal |
| to the string or variable on the right. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<variable|string> STRLESS_EQUAL <variable|string>)\fP |
| New in version 3.7: True if the given string or variable\(aqs value is lexicographically less |
| than or equal to the string or variable on the right. |
| |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<variable|string> STRGREATER_EQUAL <variable|string>)\fP |
| New in version 3.7: True if the given string or variable\(aqs value is lexicographically greater |
| than or equal to the string or variable on the right. |
| |
| .UNINDENT |
| .SS Version Comparisons |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<variable|string> VERSION_LESS <variable|string>)\fP |
| Component\-wise integer version number comparison (version format is |
| \fBmajor[.minor[.patch[.tweak]]]\fP, omitted components are treated as zero). |
| Any non\-integer version component or non\-integer trailing part of a version |
| component effectively truncates the string at that point. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<variable|string> VERSION_GREATER <variable|string>)\fP |
| Component\-wise integer version number comparison (version format is |
| \fBmajor[.minor[.patch[.tweak]]]\fP, omitted components are treated as zero). |
| Any non\-integer version component or non\-integer trailing part of a version |
| component effectively truncates the string at that point. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<variable|string> VERSION_EQUAL <variable|string>)\fP |
| Component\-wise integer version number comparison (version format is |
| \fBmajor[.minor[.patch[.tweak]]]\fP, omitted components are treated as zero). |
| Any non\-integer version component or non\-integer trailing part of a version |
| component effectively truncates the string at that point. |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<variable|string> VERSION_LESS_EQUAL <variable|string>)\fP |
| New in version 3.7: Component\-wise integer version number comparison (version format is |
| \fBmajor[.minor[.patch[.tweak]]]\fP, omitted components are treated as zero). |
| Any non\-integer version component or non\-integer trailing part of a version |
| component effectively truncates the string at that point. |
| |
| .UNINDENT |
| .INDENT 0.0 |
| .TP |
| .B \fBif(<variable|string> VERSION_GREATER_EQUAL <variable|string>)\fP |
| New in version 3.7: Component\-wise integer version number comparison (version format is |
| \fBmajor[.minor[.patch[.tweak]]]\fP, omitted components are treated as zero). |
| Any non\-integer version component or non\-integer trailing part of a version |
| component effectively truncates the string at that point. |
| |
| .UNINDENT |
| .SS Variable Expansion |
| .sp |
| The if command was written very early in CMake\(aqs history, predating |
| the \fB${}\fP variable evaluation syntax, and for convenience evaluates |
| variables named by its arguments as shown in the above signatures. |
| Note that normal variable evaluation with \fB${}\fP applies before the if |
| command even receives the arguments. Therefore code like |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(var1 OFF) |
| set(var2 "var1") |
| if(${var2}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| appears to the if command as |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| if(var1) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| and is evaluated according to the \fBif(<variable>)\fP case documented |
| above. The result is \fBOFF\fP which is false. However, if we remove the |
| \fB${}\fP from the example then the command sees |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| if(var2) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| which is true because \fBvar2\fP is defined to \fBvar1\fP which is not a false |
| constant. |
| .sp |
| Automatic evaluation applies in the other cases whenever the |
| above\-documented condition syntax accepts \fB<variable|string>\fP: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| The left hand argument to \fBMATCHES\fP is first checked to see if it is |
| a defined variable, if so the variable\(aqs value is used, otherwise the |
| original value is used. |
| .IP \(bu 2 |
| If the left hand argument to \fBMATCHES\fP is missing it returns false |
| without error |
| .IP \(bu 2 |
| Both left and right hand arguments to \fBLESS\fP, \fBGREATER\fP, \fBEQUAL\fP, |
| \fBLESS_EQUAL\fP, and \fBGREATER_EQUAL\fP, are independently tested to see if |
| they are defined variables, if so their defined values are used otherwise |
| the original value is used. |
| .IP \(bu 2 |
| Both left and right hand arguments to \fBSTRLESS\fP, \fBSTRGREATER\fP, |
| \fBSTREQUAL\fP, \fBSTRLESS_EQUAL\fP, and \fBSTRGREATER_EQUAL\fP are independently |
| tested to see if they are defined variables, if so their defined values are |
| used otherwise the original value is used. |
| .IP \(bu 2 |
| Both left and right hand arguments to \fBVERSION_LESS\fP, |
| \fBVERSION_GREATER\fP, \fBVERSION_EQUAL\fP, \fBVERSION_LESS_EQUAL\fP, and |
| \fBVERSION_GREATER_EQUAL\fP are independently tested to see if they are defined |
| variables, if so their defined values are used otherwise the original value |
| is used. |
| .IP \(bu 2 |
| The right hand argument to \fBNOT\fP is tested to see if it is a boolean |
| constant, if so the value is used, otherwise it is assumed to be a |
| variable and it is dereferenced. |
| .IP \(bu 2 |
| The left and right hand arguments to \fBAND\fP and \fBOR\fP are independently |
| tested to see if they are boolean constants, if so they are used as |
| such, otherwise they are assumed to be variables and are dereferenced. |
| .UNINDENT |
| .sp |
| Changed in version 3.1: To prevent ambiguity, potential variable or keyword names can be |
| specified in a Quoted Argument or a Bracket Argument\&. |
| A quoted or bracketed variable or keyword will be interpreted as a |
| string and not dereferenced or interpreted. |
| See policy \fBCMP0054\fP\&. |
| |
| .sp |
| There is no automatic evaluation for environment or cache |
| Variable References\&. Their values must be referenced as |
| \fB$ENV{<name>}\fP or \fB$CACHE{<name>}\fP wherever the above\-documented |
| condition syntax accepts \fB<variable|string>\fP\&. |
| .SS include |
| .sp |
| Load and run CMake code from a file or module. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>] |
| [NO_POLICY_SCOPE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Loads and runs CMake code from the file given. Variable reads and |
| writes access the scope of the caller (dynamic scoping). If \fBOPTIONAL\fP |
| is present, then no error is raised if the file does not exist. If |
| \fBRESULT_VARIABLE\fP is given the variable \fB<var>\fP will be set to the |
| full filename which has been included or \fBNOTFOUND\fP if it failed. |
| .sp |
| If a module is specified instead of a file, the file with name |
| \fB<modulename>.cmake\fP is searched first in \fBCMAKE_MODULE_PATH\fP, |
| then in the CMake module directory. There is one exception to this: if |
| the file which calls \fBinclude()\fP is located itself in the CMake builtin |
| module directory, then first the CMake builtin module directory is searched and |
| \fBCMAKE_MODULE_PATH\fP afterwards. See also policy \fBCMP0017\fP\&. |
| .sp |
| See the \fBcmake_policy()\fP command documentation for discussion of the |
| \fBNO_POLICY_SCOPE\fP option. |
| .SS include_guard |
| .sp |
| New in version 3.10. |
| |
| .sp |
| Provides an include guard for the file currently being processed by CMake. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include_guard([DIRECTORY|GLOBAL]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets up an include guard for the current CMake file (see the |
| \fBCMAKE_CURRENT_LIST_FILE\fP variable documentation). |
| .sp |
| CMake will end its processing of the current file at the location of the |
| \fI\%include_guard()\fP command if the current file has already been |
| processed for the applicable scope (see below). This provides functionality |
| similar to the include guards commonly used in source headers or to the |
| \fB#pragma once\fP directive. If the current file has been processed previously |
| for the applicable scope, the effect is as though \fBreturn()\fP had been |
| called. Do not call this command from inside a function being defined within |
| the current file. |
| .sp |
| An optional argument specifying the scope of the guard may be provided. |
| Possible values for the option are: |
| .INDENT 0.0 |
| .TP |
| .B \fBDIRECTORY\fP |
| The include guard applies within the current directory and below. The file |
| will only be included once within this directory scope, but may be included |
| again by other files outside of this directory (i.e. a parent directory or |
| another directory not pulled in by \fBadd_subdirectory()\fP or |
| \fBinclude()\fP from the current file or its children). |
| .TP |
| .B \fBGLOBAL\fP |
| The include guard applies globally to the whole build. The current file |
| will only be included once regardless of the scope. |
| .UNINDENT |
| .sp |
| If no arguments given, \fBinclude_guard\fP has the same scope as a variable, |
| meaning that the include guard effect is isolated by the most recent |
| function scope or current directory if no inner function scopes exist. |
| In this case the command behavior is the same as: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| if(__CURRENT_FILE_VAR__) |
| return() |
| endif() |
| set(__CURRENT_FILE_VAR__ TRUE) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS list |
| .sp |
| List operations. |
| .SS Synopsis |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \fI\%Reading\fP |
| list(\fI\%LENGTH\fP <list> <out\-var>) |
| list(\fI\%GET\fP <list> <element index> [<index> ...] <out\-var>) |
| list(\fI\%JOIN\fP <list> <glue> <out\-var>) |
| list(\fI\%SUBLIST\fP <list> <begin> <length> <out\-var>) |
| |
| \fI\%Search\fP |
| list(\fI\%FIND\fP <list> <value> <out\-var>) |
| |
| \fI\%Modification\fP |
| list(\fI\%APPEND\fP <list> [<element>...]) |
| list(\fI\%FILTER\fP <list> {INCLUDE | EXCLUDE} REGEX <regex>) |
| list(\fI\%INSERT\fP <list> <index> [<element>...]) |
| list(\fI\%POP_BACK\fP <list> [<out\-var>...]) |
| list(\fI\%POP_FRONT\fP <list> [<out\-var>...]) |
| list(\fI\%PREPEND\fP <list> [<element>...]) |
| list(\fI\%REMOVE_ITEM\fP <list> <value>...) |
| list(\fI\%REMOVE_AT\fP <list> <index>...) |
| list(\fI\%REMOVE_DUPLICATES\fP <list>) |
| list(\fI\%TRANSFORM\fP <list> <ACTION> [...]) |
| |
| \fI\%Ordering\fP |
| list(\fI\%REVERSE\fP <list>) |
| list(\fI\%SORT\fP <list> [...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Introduction |
| .sp |
| The list subcommands \fBAPPEND\fP, \fBINSERT\fP, \fBFILTER\fP, \fBPREPEND\fP, |
| \fBPOP_BACK\fP, \fBPOP_FRONT\fP, \fBREMOVE_AT\fP, \fBREMOVE_ITEM\fP, |
| \fBREMOVE_DUPLICATES\fP, \fBREVERSE\fP and \fBSORT\fP may create |
| new values for the list within the current CMake variable scope. Similar to |
| the \fBset()\fP command, the LIST command creates new variable values in |
| the current scope, even if the list itself is actually defined in a parent |
| scope. To propagate the results of these operations upwards, use |
| \fBset()\fP with \fBPARENT_SCOPE\fP, \fBset()\fP with |
| \fBCACHE INTERNAL\fP, or some other means of value propagation. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| A list in cmake is a \fB;\fP separated group of strings. To create a |
| list the set command can be used. For example, \fBset(var a b c d e)\fP |
| creates a list with \fBa;b;c;d;e\fP, and \fBset(var "a b c d e")\fP creates a |
| string or a list with one item in it. (Note macro arguments are not |
| variables, and therefore cannot be used in LIST commands.) |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| When specifying index values, if \fB<element index>\fP is 0 or greater, it |
| is indexed from the beginning of the list, with 0 representing the |
| first list element. If \fB<element index>\fP is \-1 or lesser, it is indexed |
| from the end of the list, with \-1 representing the last list element. |
| Be careful when counting with negative indices: they do not start from |
| 0. \-0 is equivalent to 0, the first list element. |
| .UNINDENT |
| .UNINDENT |
| .SS Reading |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(LENGTH <list> <output variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Returns the list\(aqs length. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(GET <list> <element index> [<element index> ...] <output variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Returns the list of elements specified by indices from the list. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(JOIN <list> <glue> <output variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Returns a string joining all list\(aqs elements using the glue string. |
| To join multiple strings, which are not part of a list, use \fBJOIN\fP operator |
| from \fBstring()\fP command. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(SUBLIST <list> <begin> <length> <output variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Returns a sublist of the given list. |
| If \fB<length>\fP is 0, an empty list will be returned. |
| If \fB<length>\fP is \-1 or the list is smaller than \fB<begin>+<length>\fP then |
| the remaining elements of the list starting at \fB<begin>\fP will be returned. |
| .SS Search |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(FIND <list> <value> <output variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Returns the index of the element specified in the list or \-1 |
| if it wasn\(aqt found. |
| .SS Modification |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(APPEND <list> [<element> ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Appends elements to the list. If no variable named \fB<list>\fP exists in the |
| current scope its value is treated as empty and the elements are appended to |
| that empty list. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.6. |
| |
| .sp |
| Includes or removes items from the list that match the mode\(aqs pattern. |
| In \fBREGEX\fP mode, items will be matched against the given regular expression. |
| .sp |
| For more information on regular expressions look under |
| string(REGEX)\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(INSERT <list> <element_index> <element> [<element> ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Inserts elements to the list to the specified index. It is an |
| error to specify an out\-of\-range index. Valid indexes are 0 to \fIN\fP |
| where \fIN\fP is the length of the list, inclusive. An empty list |
| has length 0. If no variable named \fB<list>\fP exists in the |
| current scope its value is treated as empty and the elements are |
| inserted in that empty list. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(POP_BACK <list> [<out\-var>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.15. |
| |
| .sp |
| If no variable name is given, removes exactly one element. Otherwise, |
| with \fIN\fP variable names provided, assign the last \fIN\fP elements\(aq values |
| to the given variables and then remove the last \fIN\fP values from |
| \fB<list>\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(POP_FRONT <list> [<out\-var>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.15. |
| |
| .sp |
| If no variable name is given, removes exactly one element. Otherwise, |
| with \fIN\fP variable names provided, assign the first \fIN\fP elements\(aq values |
| to the given variables and then remove the first \fIN\fP values from |
| \fB<list>\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(PREPEND <list> [<element> ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.15. |
| |
| .sp |
| Insert elements to the 0th position in the list. If no variable named |
| \fB<list>\fP exists in the current scope its value is treated as empty and |
| the elements are prepended to that empty list. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(REMOVE_ITEM <list> <value> [<value> ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Removes all instances of the given items from the list. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(REMOVE_AT <list> <index> [<index> ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Removes items at given indices from the list. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(REMOVE_DUPLICATES <list>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Removes duplicated items in the list. The relative order of items is preserved, |
| but if duplicates are encountered, only the first instance is preserved. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(TRANSFORM <list> <ACTION> [<SELECTOR>] |
| [OUTPUT_VARIABLE <output variable>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Transforms the list by applying an action to all or, by specifying a |
| \fB<SELECTOR>\fP, to the selected elements of the list, storing the result |
| in\-place or in the specified output variable. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The \fBTRANSFORM\fP sub\-command does not change the number of elements in the |
| list. If a \fB<SELECTOR>\fP is specified, only some elements will be changed, |
| the other ones will remain the same as before the transformation. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fB<ACTION>\fP specifies the action to apply to the elements of the list. |
| The actions have exactly the same semantics as sub\-commands of the |
| \fBstring()\fP command. \fB<ACTION>\fP must be one of the following: |
| .sp |
| \fBAPPEND\fP, \fBPREPEND\fP: Append, prepend specified value to each element of |
| the list. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBTOUPPER\fP, \fBTOLOWER\fP: Convert each element of the list to upper, lower |
| characters. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBSTRIP\fP: Remove leading and trailing spaces from each element of the |
| list. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(TRANSFORM <list> STRIP ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBGENEX_STRIP\fP: Strip any |
| \fBgenerator expressions\fP from each |
| element of the list. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(TRANSFORM <list> GENEX_STRIP ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBREPLACE\fP: Match the regular expression as many times as possible and |
| substitute the replacement expression for the match for each element |
| of the list |
| (Same semantic as \fBREGEX REPLACE\fP from \fBstring()\fP command). |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(TRANSFORM <list> REPLACE <regular_expression> |
| <replace_expression> ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fB<SELECTOR>\fP determines which elements of the list will be transformed. |
| Only one type of selector can be specified at a time. When given, |
| \fB<SELECTOR>\fP must be one of the following: |
| .sp |
| \fBAT\fP: Specify a list of indexes. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBFOR\fP: Specify a range with, optionally, an increment used to iterate over |
| the range. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBREGEX\fP: Specify a regular expression. Only elements matching the regular |
| expression will be transformed. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS Ordering |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(REVERSE <list>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Reverses the contents of the list in\-place. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sorts the list in\-place alphabetically. |
| .sp |
| New in version 3.13: Added the \fBCOMPARE\fP, \fBCASE\fP, and \fBORDER\fP options. |
| |
| .sp |
| New in version 3.18: Added the \fBCOMPARE NATURAL\fP option. |
| |
| .sp |
| Use the \fBCOMPARE\fP keyword to select the comparison method for sorting. |
| The \fB<compare>\fP option should be one of: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBSTRING\fP: Sorts a list of strings alphabetically. This is the |
| default behavior if the \fBCOMPARE\fP option is not given. |
| .IP \(bu 2 |
| \fBFILE_BASENAME\fP: Sorts a list of pathnames of files by their basenames. |
| .IP \(bu 2 |
| \fBNATURAL\fP: Sorts a list of strings using natural order |
| (see \fBstrverscmp(3)\fP manual), i.e. such that contiguous digits |
| are compared as whole numbers. |
| For example: the following list \fI10.0 1.1 2.1 8.0 2.0 3.1\fP |
| will be sorted as \fI1.1 2.0 2.1 3.1 8.0 10.0\fP if the \fBNATURAL\fP |
| comparison is selected where it will be sorted as |
| \fI1.1 10.0 2.0 2.1 3.1 8.0\fP with the \fBSTRING\fP comparison. |
| .UNINDENT |
| .sp |
| Use the \fBCASE\fP keyword to select a case sensitive or case insensitive |
| sort mode. The \fB<case>\fP option should be one of: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBSENSITIVE\fP: List items are sorted in a case\-sensitive manner. This is |
| the default behavior if the \fBCASE\fP option is not given. |
| .IP \(bu 2 |
| \fBINSENSITIVE\fP: List items are sorted case insensitively. The order of |
| items which differ only by upper/lowercase is not specified. |
| .UNINDENT |
| .sp |
| To control the sort order, the \fBORDER\fP keyword can be given. |
| The \fB<order>\fP option should be one of: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBASCENDING\fP: Sorts the list in ascending order. This is the default |
| behavior when the \fBORDER\fP option is not given. |
| .IP \(bu 2 |
| \fBDESCENDING\fP: Sorts the list in descending order. |
| .UNINDENT |
| .SS macro |
| .sp |
| Start recording a macro for later invocation as a command |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| macro(<name> [<arg1> ...]) |
| <commands> |
| endmacro() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Defines a macro named \fB<name>\fP that takes arguments named |
| \fB<arg1>\fP, ... Commands listed after macro, but before the |
| matching \fBendmacro()\fP, are not executed until the macro |
| is invoked. |
| .sp |
| Per legacy, the \fBendmacro()\fP command admits an optional |
| \fB<name>\fP argument. If used, it must be a verbatim repeat of the |
| argument of the opening \fBmacro\fP command. |
| .sp |
| See the \fBcmake_policy()\fP command documentation for the behavior |
| of policies inside macros. |
| .sp |
| See the \fI\%Macro vs Function\fP section below for differences |
| between CMake macros and \fBfunctions\fP\&. |
| .SS Invocation |
| .sp |
| The macro invocation is case\-insensitive. A macro defined as |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| macro(foo) |
| <commands> |
| endmacro() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| can be invoked through any of |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| foo() |
| Foo() |
| FOO() |
| cmake_language(CALL foo) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| and so on. However, it is strongly recommended to stay with the |
| case chosen in the macro definition. Typically macros use |
| all\-lowercase names. |
| .sp |
| New in version 3.18: The \fBcmake_language(CALL ...)\fP command can also be used to |
| invoke the macro. |
| |
| .SS Arguments |
| .sp |
| When a macro is invoked, the commands recorded in the macro are |
| first modified by replacing formal parameters (\fB${arg1}\fP, ...) |
| with the arguments passed, and then invoked as normal commands. |
| .sp |
| In addition to referencing the formal parameters you can reference the |
| values \fB${ARGC}\fP which will be set to the number of arguments passed |
| into the function as well as \fB${ARGV0}\fP, \fB${ARGV1}\fP, \fB${ARGV2}\fP, |
| \&... which will have the actual values of the arguments passed in. |
| This facilitates creating macros with optional arguments. |
| .sp |
| Furthermore, \fB${ARGV}\fP holds the list of all arguments given to the |
| macro and \fB${ARGN}\fP holds the list of arguments past the last expected |
| argument. |
| Referencing to \fB${ARGV#}\fP arguments beyond \fB${ARGC}\fP have undefined |
| behavior. Checking that \fB${ARGC}\fP is greater than \fB#\fP is the only |
| way to ensure that \fB${ARGV#}\fP was passed to the function as an extra |
| argument. |
| .SS Macro vs Function |
| .sp |
| The \fBmacro\fP command is very similar to the \fBfunction()\fP command. |
| Nonetheless, there are a few important differences. |
| .sp |
| In a function, \fBARGN\fP, \fBARGC\fP, \fBARGV\fP and \fBARGV0\fP, \fBARGV1\fP, ... |
| are true variables in the usual CMake sense. In a macro, they are not, |
| they are string replacements much like the C preprocessor would do |
| with a macro. This has a number of consequences, as explained in |
| the \fI\%Argument Caveats\fP section below. |
| .sp |
| Another difference between macros and functions is the control flow. |
| A function is executed by transferring control from the calling |
| statement to the function body. A macro is executed as if the macro |
| body were pasted in place of the calling statement. This has the |
| consequence that a \fBreturn()\fP in a macro body does not |
| just terminate execution of the macro; rather, control is returned |
| from the scope of the macro call. To avoid confusion, it is recommended |
| to avoid \fBreturn()\fP in macros altogether. |
| .sp |
| Unlike a function, the \fBCMAKE_CURRENT_FUNCTION\fP, |
| \fBCMAKE_CURRENT_FUNCTION_LIST_DIR\fP, |
| \fBCMAKE_CURRENT_FUNCTION_LIST_FILE\fP, |
| \fBCMAKE_CURRENT_FUNCTION_LIST_LINE\fP variables are not |
| set for a macro. |
| .SS Argument Caveats |
| .sp |
| Since \fBARGN\fP, \fBARGC\fP, \fBARGV\fP, \fBARGV0\fP etc. are not variables, |
| you will NOT be able to use commands like |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| if(ARGV1) # ARGV1 is not a variable |
| if(DEFINED ARGV2) # ARGV2 is not a variable |
| if(ARGC GREATER 2) # ARGC is not a variable |
| foreach(loop_var IN LISTS ARGN) # ARGN is not a variable |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In the first case, you can use \fBif(${ARGV1})\fP\&. In the second and |
| third case, the proper way to check if an optional variable was |
| passed to the macro is to use \fBif(${ARGC} GREATER 2)\fP\&. In the |
| last case, you can use \fBforeach(loop_var ${ARGN})\fP but this will |
| skip empty arguments. If you need to include them, you can use |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(list_var "${ARGN}") |
| foreach(loop_var IN LISTS list_var) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Note that if you have a variable with the same name in the scope from |
| which the macro is called, using unreferenced names will use the |
| existing variable instead of the arguments. For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| macro(bar) |
| foreach(arg IN LISTS ARGN) |
| <commands> |
| endforeach() |
| endmacro() |
| |
| function(foo) |
| bar(x y z) |
| endfunction() |
| |
| foo(a b c) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Will loop over \fBa;b;c\fP and not over \fBx;y;z\fP as one might have expected. |
| If you want true CMake variables and/or better CMake scope control you |
| should look at the function command. |
| .SS mark_as_advanced |
| .sp |
| Mark cmake cached variables as advanced. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| mark_as_advanced([CLEAR|FORCE] <var1> ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets the advanced/non\-advanced state of the named |
| cached variables. |
| .sp |
| An advanced variable will not be displayed in any |
| of the cmake GUIs unless the \fBshow advanced\fP option is on. |
| In script mode, the advanced/non\-advanced state has no effect. |
| .sp |
| If the keyword \fBCLEAR\fP is given |
| then advanced variables are changed back to unadvanced. |
| If the keyword \fBFORCE\fP is given |
| then the variables are made advanced. |
| If neither \fBFORCE\fP nor \fBCLEAR\fP is specified, |
| new values will be marked as advanced, but if a |
| variable already has an advanced/non\-advanced state, |
| it will not be changed. |
| .sp |
| Changed in version 3.17: Variables passed to this command which are not already in the cache |
| are ignored. See policy \fBCMP0102\fP\&. |
| |
| .SS math |
| .sp |
| Evaluate a mathematical expression. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Evaluates a mathematical \fB<expression>\fP and sets \fB<variable>\fP to the |
| resulting value. The result of the expression must be representable as a |
| 64\-bit signed integer. |
| .sp |
| The mathematical expression must be given as a string (i.e. enclosed in |
| double quotation marks). An example is \fB"5 * (10 + 13)"\fP\&. |
| Supported operators are \fB+\fP, \fB\-\fP, \fB*\fP, \fB/\fP, \fB%\fP, \fB|\fP, \fB&\fP, |
| \fB^\fP, \fB~\fP, \fB<<\fP, \fB>>\fP, and \fB(...)\fP; they have the same meaning |
| as in C code. |
| .sp |
| New in version 3.13: Hexadecimal numbers are recognized when prefixed with \fB0x\fP, as in C code. |
| |
| .sp |
| New in version 3.13: The result is formatted according to the option \fBOUTPUT_FORMAT\fP, |
| where \fB<format>\fP is one of |
| .INDENT 0.0 |
| .TP |
| .B \fBHEXADECIMAL\fP |
| Hexadecimal notation as in C code, i. e. starting with "0x". |
| .TP |
| .B \fBDECIMAL\fP |
| Decimal notation. Which is also used if no \fBOUTPUT_FORMAT\fP option |
| is specified. |
| .UNINDENT |
| |
| .sp |
| For example |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL) # value is set to "1000" |
| math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL) # value is set to "0x3e8" |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS message |
| .sp |
| Log a message. |
| .SS Synopsis |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \fI\%General messages\fP |
| message([<mode>] "message text" ...) |
| |
| \fI\%Reporting checks\fP |
| message(<checkState> "message text" ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS General messages |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| message([<mode>] "message text" ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Record the specified message text in the log. If more than one message |
| string is given, they are concatenated into a single message with no |
| separator between the strings. |
| .sp |
| The optional \fB<mode>\fP keyword determines the type of message, which |
| influences the way the message is handled: |
| .INDENT 0.0 |
| .TP |
| .B \fBFATAL_ERROR\fP |
| CMake Error, stop processing and generation. |
| .TP |
| .B \fBSEND_ERROR\fP |
| CMake Error, continue processing, but skip generation. |
| .TP |
| .B \fBWARNING\fP |
| CMake Warning, continue processing. |
| .TP |
| .B \fBAUTHOR_WARNING\fP |
| CMake Warning (dev), continue processing. |
| .TP |
| .B \fBDEPRECATION\fP |
| CMake Deprecation Error or Warning if variable |
| \fBCMAKE_ERROR_DEPRECATED\fP or \fBCMAKE_WARN_DEPRECATED\fP |
| is enabled, respectively, else no message. |
| .TP |
| .B (none) or \fBNOTICE\fP |
| Important message printed to stderr to attract user\(aqs attention. |
| .TP |
| .B \fBSTATUS\fP |
| The main interesting messages that project users might be interested in. |
| Ideally these should be concise, no more than a single line, but still |
| informative. |
| .TP |
| .B \fBVERBOSE\fP |
| Detailed informational messages intended for project users. These messages |
| should provide additional details that won\(aqt be of interest in most cases, |
| but which may be useful to those building the project when they want deeper |
| insight into what\(aqs happening. |
| .TP |
| .B \fBDEBUG\fP |
| Detailed informational messages intended for developers working on the |
| project itself as opposed to users who just want to build it. These messages |
| will not typically be of interest to other users building the project and |
| will often be closely related to internal implementation details. |
| .TP |
| .B \fBTRACE\fP |
| Fine\-grained messages with very low\-level implementation details. Messages |
| using this log level would normally only be temporary and would expect to be |
| removed before releasing the project, packaging up the files, etc. |
| .UNINDENT |
| .sp |
| New in version 3.15: Added the \fBNOTICE\fP, \fBVERBOSE\fP, \fBDEBUG\fP, and \fBTRACE\fP levels. |
| |
| .sp |
| The CMake command\-line tool displays \fBSTATUS\fP to \fBTRACE\fP messages on stdout |
| with the message preceded by two hyphens and a space. All other message types |
| are sent to stderr and are not prefixed with hyphens. The |
| \fBCMake GUI\fP displays all messages in its log area. |
| The \fBcurses interface\fP shows \fBSTATUS\fP to \fBTRACE\fP |
| messages one at a time on a status line and other messages in an |
| interactive pop\-up box. The \fB\-\-log\-level\fP command\-line option to each of |
| these tools can be used to control which messages will be shown. |
| .sp |
| New in version 3.17: To make a log level persist between CMake runs, the |
| \fBCMAKE_MESSAGE_LOG_LEVEL\fP variable can be set instead. |
| Note that the command line option takes precedence over the cache variable. |
| |
| .sp |
| New in version 3.16: Messages of log levels \fBNOTICE\fP and below will have each line preceded |
| by the content of the \fBCMAKE_MESSAGE_INDENT\fP variable (converted to |
| a single string by concatenating its list items). For \fBSTATUS\fP to \fBTRACE\fP |
| messages, this indenting content will be inserted after the hyphens. |
| |
| .sp |
| New in version 3.17: Messages of log levels \fBNOTICE\fP and below can also have each line preceded |
| with context of the form \fB[some.context.example]\fP\&. The content between the |
| square brackets is obtained by converting the \fBCMAKE_MESSAGE_CONTEXT\fP |
| list variable to a dot\-separated string. The message context will always |
| appear before any indenting content but after any automatically added leading |
| hyphens. By default, message context is not shown, it has to be explicitly |
| enabled by giving the \fBcmake\fP \fB\-\-log\-context\fP |
| command\-line option or by setting the \fBCMAKE_MESSAGE_CONTEXT_SHOW\fP |
| variable to true. See the \fBCMAKE_MESSAGE_CONTEXT\fP documentation for |
| usage examples. |
| |
| .sp |
| CMake Warning and Error message text displays using a simple markup |
| language. Non\-indented text is formatted in line\-wrapped paragraphs |
| delimited by newlines. Indented text is considered pre\-formatted. |
| .SS Reporting checks |
| .sp |
| New in version 3.17. |
| |
| .sp |
| A common pattern in CMake output is a message indicating the start of some |
| sort of check, followed by another message reporting the result of that check. |
| For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| message(STATUS "Looking for someheader.h") |
| #... do the checks, set checkSuccess with the result |
| if(checkSuccess) |
| message(STATUS "Looking for someheader.h \- found") |
| else() |
| message(STATUS "Looking for someheader.h \- not found") |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This can be more robustly and conveniently expressed using the \fBCHECK_...\fP |
| keyword form of the \fBmessage()\fP command: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| message(<checkState> "message" ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| where \fB<checkState>\fP must be one of the following: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .TP |
| .B \fBCHECK_START\fP |
| Record a concise message about the check about to be performed. |
| .TP |
| .B \fBCHECK_PASS\fP |
| Record a successful result for a check. |
| .TP |
| .B \fBCHECK_FAIL\fP |
| Record an unsuccessful result for a check. |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| When recording a check result, the command repeats the message from the most |
| recently started check for which no result has yet been reported, then some |
| separator characters and then the message text provided after the |
| \fBCHECK_PASS\fP or \fBCHECK_FAIL\fP keyword. Check messages are always reported |
| at \fBSTATUS\fP log level. |
| .sp |
| Checks may be nested and every \fBCHECK_START\fP should have exactly one |
| matching \fBCHECK_PASS\fP or \fBCHECK_FAIL\fP\&. |
| The \fBCMAKE_MESSAGE_INDENT\fP variable can also be used to add |
| indenting to nested checks if desired. For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| message(CHECK_START "Finding my things") |
| list(APPEND CMAKE_MESSAGE_INDENT " ") |
| unset(missingComponents) |
| |
| message(CHECK_START "Finding partA") |
| # ... do check, assume we find A |
| message(CHECK_PASS "found") |
| |
| message(CHECK_START "Finding partB") |
| # ... do check, assume we don\(aqt find B |
| list(APPEND missingComponents B) |
| message(CHECK_FAIL "not found") |
| |
| list(POP_BACK CMAKE_MESSAGE_INDENT) |
| if(missingComponents) |
| message(CHECK_FAIL "missing components: ${missingComponents}") |
| else() |
| message(CHECK_PASS "all components found") |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Output from the above would appear something like the following: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \-\- Finding my things |
| \-\- Finding partA |
| \-\- Finding partA \- found |
| \-\- Finding partB |
| \-\- Finding partB \- not found |
| \-\- Finding my things \- missing components: B |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS option |
| .sp |
| Provide an option that the user can optionally select. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| option(<variable> "<help_text>" [value]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Provides an option for the user to select as \fBON\fP or \fBOFF\fP\&. |
| If no initial \fB<value>\fP is provided, \fBOFF\fP is used. |
| If \fB<variable>\fP is already set as a normal or cache variable, |
| then the command does nothing (see policy \fBCMP0077\fP). |
| .sp |
| If you have options that depend on the values of other options, see |
| the module help for \fBCMakeDependentOption\fP\&. |
| .SS return |
| .sp |
| Return from a file, directory or function. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| return() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Returns from a file, directory or function. When this command is |
| encountered in an included file (via \fBinclude()\fP or |
| \fBfind_package()\fP), it causes processing of the current file to stop |
| and control is returned to the including file. If it is encountered in a |
| file which is not included by another file, e.g. a \fBCMakeLists.txt\fP, |
| deferred calls scheduled by \fBcmake_language(DEFER)\fP are invoked and |
| control is returned to the parent directory if there is one. If return is |
| called in a function, control is returned to the caller of the function. |
| .sp |
| Note that a \fBmacro\fP, unlike a \fBfunction\fP, |
| is expanded in place and therefore cannot handle \fBreturn()\fP\&. |
| .SS separate_arguments |
| .sp |
| Parse command\-line arguments into a semicolon\-separated list. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| separate_arguments(<variable> <mode> [PROGRAM [SEPARATE_ARGS]] <args>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Parses a space\-separated string \fB<args>\fP into a list of items, |
| and stores this list in semicolon\-separated standard form in \fB<variable>\fP\&. |
| .sp |
| This function is intended for parsing command\-line arguments. |
| The entire command line must be passed as one string in the |
| argument \fB<args>\fP\&. |
| .sp |
| The exact parsing rules depend on the operating system. |
| They are specified by the \fB<mode>\fP argument which must |
| be one of the following keywords: |
| .INDENT 0.0 |
| .TP |
| .B \fBUNIX_COMMAND\fP |
| Arguments are separated by unquoted whitespace. |
| Both single\-quote and double\-quote pairs are respected. |
| A backslash escapes the next literal character (\fB\e"\fP is \fB"\fP); |
| there are no special escapes (\fB\en\fP is just \fBn\fP). |
| .TP |
| .B \fBWINDOWS_COMMAND\fP |
| A Windows command\-line is parsed using the same |
| syntax the runtime library uses to construct argv at startup. It |
| separates arguments by whitespace that is not double\-quoted. |
| Backslashes are literal unless they precede double\-quotes. See the |
| MSDN article \fI\%Parsing C Command\-Line Arguments\fP for details. |
| .TP |
| .B \fBNATIVE_COMMAND\fP |
| New in version 3.9. |
| |
| .sp |
| Proceeds as in \fBWINDOWS_COMMAND\fP mode if the host system is Windows. |
| Otherwise proceeds as in \fBUNIX_COMMAND\fP mode. |
| .TP |
| .B \fBPROGRAM\fP |
| New in version 3.19. |
| |
| .sp |
| The first item in \fB<args>\fP is assumed to be an executable and will be |
| searched in the system search path or left as a full path. If not found, |
| \fB<variable>\fP will be empty. Otherwise, \fB<variable>\fP is a list of 2 |
| elements: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .IP 0. 4 |
| Absolute path of the program |
| .IP 1. 4 |
| Any command\-line arguments present in \fB<args>\fP as a string |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| For example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| separate_arguments (out UNIX_COMMAND PROGRAM "cc \-c main.c") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .INDENT 7.0 |
| .IP \(bu 2 |
| First element of the list: \fB/path/to/cc\fP |
| .IP \(bu 2 |
| Second element of the list: \fB" \-c main.c"\fP |
| .UNINDENT |
| .TP |
| .B \fBSEPARATE_ARGS\fP |
| When this sub\-option of \fBPROGRAM\fP option is specified, command\-line |
| arguments will be split as well and stored in \fB<variable>\fP\&. |
| .sp |
| For example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| separate_arguments (out UNIX_COMMAND PROGRAM SEPARATE_ARGS "cc \-c main.c") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The contents of \fBout\fP will be: \fB/path/to/cc;\-c;main.c\fP |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| separate_arguments(<var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Convert the value of \fB<var>\fP to a semi\-colon separated list. All |
| spaces are replaced with \(aq;\(aq. This helps with generating command |
| lines. |
| .SS set |
| .sp |
| Set a normal, cache, or environment variable to a given value. |
| See the cmake\-language(7) variables |
| documentation for the scopes and interaction of normal variables |
| and cache entries. |
| .sp |
| Signatures of this command that specify a \fB<value>...\fP placeholder |
| expect zero or more arguments. Multiple arguments will be joined as |
| a semicolon\-separated list to form the actual variable |
| value to be set. Zero arguments will cause normal variables to be |
| unset. See the \fBunset()\fP command to unset variables explicitly. |
| .SS Set Normal Variable |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(<variable> <value>... [PARENT_SCOPE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets the given \fB<variable>\fP in the current function or directory scope. |
| .sp |
| If the \fBPARENT_SCOPE\fP option is given the variable will be set in |
| the scope above the current scope. Each new directory or function |
| creates a new scope. This command will set the value of a variable |
| into the parent directory or calling function (whichever is applicable |
| to the case at hand). The previous state of the variable\(aqs value stays the |
| same in the current scope (e.g., if it was undefined before, it is still |
| undefined and if it had a value, it is still that value). |
| .SS Set Cache Entry |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(<variable> <value>... CACHE <type> <docstring> [FORCE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets the given cache \fB<variable>\fP (cache entry). Since cache entries |
| are meant to provide user\-settable values this does not overwrite |
| existing cache entries by default. Use the \fBFORCE\fP option to |
| overwrite existing entries. |
| .sp |
| The \fB<type>\fP must be specified as one of: |
| .INDENT 0.0 |
| .TP |
| .B \fBBOOL\fP |
| Boolean \fBON/OFF\fP value. \fBcmake\-gui(1)\fP offers a checkbox. |
| .TP |
| .B \fBFILEPATH\fP |
| Path to a file on disk. \fBcmake\-gui(1)\fP offers a file dialog. |
| .TP |
| .B \fBPATH\fP |
| Path to a directory on disk. \fBcmake\-gui(1)\fP offers a file dialog. |
| .TP |
| .B \fBSTRING\fP |
| A line of text. \fBcmake\-gui(1)\fP offers a text field or a |
| drop\-down selection if the \fBSTRINGS\fP cache entry |
| property is set. |
| .TP |
| .B \fBINTERNAL\fP |
| A line of text. \fBcmake\-gui(1)\fP does not show internal entries. |
| They may be used to store variables persistently across runs. |
| Use of this type implies \fBFORCE\fP\&. |
| .UNINDENT |
| .sp |
| The \fB<docstring>\fP must be specified as a line of text providing |
| a quick summary of the option for presentation to \fBcmake\-gui(1)\fP |
| users. |
| .sp |
| If the cache entry does not exist prior to the call or the \fBFORCE\fP |
| option is given then the cache entry will be set to the given value. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The content of the cache variable will not be directly accessible if a normal |
| variable of the same name already exists (see rules of variable |
| evaluation). If policy \fBCMP0126\fP is set |
| to \fBOLD\fP, any normal variable binding in the current scope will be removed. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| It is possible for the cache entry to exist prior to the call but |
| have no type set if it was created on the \fBcmake(1)\fP command |
| line by a user through the \fB\-D<var>=<value>\fP option without |
| specifying a type. In this case the \fBset\fP command will add the |
| type. Furthermore, if the \fB<type>\fP is \fBPATH\fP or \fBFILEPATH\fP |
| and the \fB<value>\fP provided on the command line is a relative path, |
| then the \fBset\fP command will treat the path as relative to the |
| current working directory and convert it to an absolute path. |
| .SS Set Environment Variable |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set(ENV{<variable>} [<value>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets an \fBEnvironment Variable\fP |
| to the given value. |
| Subsequent calls of \fB$ENV{<variable>}\fP will return this new value. |
| .sp |
| This command affects only the current CMake process, not the process |
| from which CMake was called, nor the system environment at large, |
| nor the environment of subsequent build or test processes. |
| .sp |
| If no argument is given after \fBENV{<variable>}\fP or if \fB<value>\fP is |
| an empty string, then this command will clear any existing value of the |
| environment variable. |
| .sp |
| Arguments after \fB<value>\fP are ignored. If extra arguments are found, |
| then an author warning is issued. |
| .SS set_directory_properties |
| .sp |
| Set properties of the current directory and subdirectories. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets properties of the current directory and its subdirectories in key\-value pairs. |
| .sp |
| See also the \fBset_property(DIRECTORY)\fP command. |
| .sp |
| See Directory Properties for the list of properties known to CMake |
| and their individual documentation for the behavior of each property. |
| .SS set_property |
| .sp |
| Set a named property in a given scope. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_property(<GLOBAL | |
| DIRECTORY [<dir>] | |
| TARGET [<target1> ...] | |
| SOURCE [<src1> ...] |
| [DIRECTORY <dirs> ...] |
| [TARGET_DIRECTORY <targets> ...] | |
| INSTALL [<file1> ...] | |
| TEST [<test1> ...] | |
| CACHE [<entry1> ...] > |
| [APPEND] [APPEND_STRING] |
| PROPERTY <name> [<value1> ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets one property on zero or more objects of a scope. |
| .sp |
| The first argument determines the scope in which the property is set. |
| It must be one of the following: |
| .INDENT 0.0 |
| .TP |
| .B \fBGLOBAL\fP |
| Scope is unique and does not accept a name. |
| .TP |
| .B \fBDIRECTORY\fP |
| Scope defaults to the current directory but other directories |
| (already processed by CMake) may be named by full or relative path. |
| Relative paths are treated as relative to the current source directory. |
| See also the \fBset_directory_properties()\fP command. |
| .sp |
| New in version 3.19: \fB<dir>\fP may reference a binary directory. |
| |
| .TP |
| .B \fBTARGET\fP |
| Scope may name zero or more existing targets. |
| See also the \fBset_target_properties()\fP command. |
| .TP |
| .B \fBSOURCE\fP |
| Scope may name zero or more source files. By default, source file properties |
| are only visible to targets added in the same directory (\fBCMakeLists.txt\fP). |
| .sp |
| New in version 3.18: Visibility can be set in other directory scopes using one or both of the |
| following sub\-options: |
| .INDENT 7.0 |
| .TP |
| .B \fBDIRECTORY <dirs>...\fP |
| The source file property will be set in each of the \fB<dirs>\fP |
| directories\(aq scopes. CMake must already know about |
| each of these directories, either by having added them through a call to |
| \fBadd_subdirectory()\fP or it being the top level source directory. |
| Relative paths are treated as relative to the current source directory. |
| .sp |
| New in version 3.19: \fB<dirs>\fP may reference a binary directory. |
| |
| .TP |
| .B \fBTARGET_DIRECTORY <targets>...\fP |
| The source file property will be set in each of the directory scopes |
| where any of the specified \fB<targets>\fP were created (the \fB<targets>\fP |
| must therefore already exist). |
| .UNINDENT |
| |
| .sp |
| See also the \fBset_source_files_properties()\fP command. |
| .TP |
| .B \fBINSTALL\fP |
| New in version 3.1. |
| |
| .sp |
| Scope may name zero or more installed file paths. |
| These are made available to CPack to influence deployment. |
| .sp |
| Both the property key and value may use generator expressions. |
| Specific properties may apply to installed files and/or directories. |
| .sp |
| Path components have to be separated by forward slashes, |
| must be normalized and are case sensitive. |
| .sp |
| To reference the installation prefix itself with a relative path use \fB\&.\fP\&. |
| .sp |
| Currently installed file properties are only defined for |
| the WIX generator where the given paths are relative |
| to the installation prefix. |
| .TP |
| .B \fBTEST\fP |
| Scope may name zero or more existing tests. |
| See also the \fBset_tests_properties()\fP command. |
| .sp |
| Test property values may be specified using |
| \fBgenerator expressions\fP |
| for tests created by the \fBadd_test(NAME)\fP signature. |
| .TP |
| .B \fBCACHE\fP |
| Scope must name zero or more cache existing entries. |
| .UNINDENT |
| .sp |
| The required \fBPROPERTY\fP option is immediately followed by the name of |
| the property to set. Remaining arguments are used to compose the |
| property value in the form of a semicolon\-separated list. |
| .sp |
| If the \fBAPPEND\fP option is given the list is appended to any existing |
| property value (except that empty values are ignored and not appended). |
| If the \fBAPPEND_STRING\fP option is given the string is |
| appended to any existing property value as string, i.e. it results in a |
| longer string and not a list of strings. When using \fBAPPEND\fP or |
| \fBAPPEND_STRING\fP with a property defined to support \fBINHERITED\fP |
| behavior (see \fBdefine_property()\fP), no inheriting occurs when |
| finding the initial value to append to. If the property is not already |
| directly set in the nominated scope, the command will behave as though |
| \fBAPPEND\fP or \fBAPPEND_STRING\fP had not been given. |
| .sp |
| See the \fBcmake\-properties(7)\fP manual for a list of properties |
| in each scope. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The \fBGENERATED\fP source file property may be globally visible. |
| See its documentation for details. |
| .UNINDENT |
| .UNINDENT |
| .SS site_name |
| .sp |
| Set the given variable to the name of the computer. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| site_name(variable) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| On UNIX\-like platforms, if the variable \fBHOSTNAME\fP is set, its value |
| will be executed as a command expected to print out the host name, |
| much like the \fBhostname\fP command\-line tool. |
| .SS string |
| .sp |
| String operations. |
| .SS Synopsis |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| \fI\%Search and Replace\fP |
| string(\fI\%FIND\fP <string> <substring> <out\-var> [...]) |
| string(\fI\%REPLACE\fP <match\-string> <replace\-string> <out\-var> <input>...) |
| string(\fI\%REGEX MATCH\fP <match\-regex> <out\-var> <input>...) |
| string(\fI\%REGEX MATCHALL\fP <match\-regex> <out\-var> <input>...) |
| string(\fI\%REGEX REPLACE\fP <match\-regex> <replace\-expr> <out\-var> <input>...) |
| |
| \fI\%Manipulation\fP |
| string(\fI\%APPEND\fP <string\-var> [<input>...]) |
| string(\fI\%PREPEND\fP <string\-var> [<input>...]) |
| string(\fI\%CONCAT\fP <out\-var> [<input>...]) |
| string(\fI\%JOIN\fP <glue> <out\-var> [<input>...]) |
| string(\fI\%TOLOWER\fP <string> <out\-var>) |
| string(\fI\%TOUPPER\fP <string> <out\-var>) |
| string(\fI\%LENGTH\fP <string> <out\-var>) |
| string(\fI\%SUBSTRING\fP <string> <begin> <length> <out\-var>) |
| string(\fI\%STRIP\fP <string> <out\-var>) |
| string(\fI\%GENEX_STRIP\fP <string> <out\-var>) |
| string(\fI\%REPEAT\fP <string> <count> <out\-var>) |
| |
| \fI\%Comparison\fP |
| string(\fI\%COMPARE\fP <op> <string1> <string2> <out\-var>) |
| |
| \fI\%Hashing\fP |
| string(\fI\%<HASH>\fP <out\-var> <input>) |
| |
| \fI\%Generation\fP |
| string(\fI\%ASCII\fP <number>... <out\-var>) |
| string(\fI\%HEX\fP <string> <out\-var>) |
| string(\fI\%CONFIGURE\fP <string> <out\-var> [...]) |
| string(\fI\%MAKE_C_IDENTIFIER\fP <string> <out\-var>) |
| string(\fI\%RANDOM\fP [<option>...] <out\-var>) |
| string(\fI\%TIMESTAMP\fP <out\-var> [<format string>] [UTC]) |
| string(\fI\%UUID\fP <out\-var> ...) |
| |
| \fI\%JSON\fP |
| string(JSON <out\-var> [ERROR_VARIABLE <error\-var>] |
| {\fI\%GET\fP | \fI\%TYPE\fP | \fI\%LENGTH\fP | \fI\%REMOVE\fP} |
| <json\-string> <member|index> [<member|index> ...]) |
| string(JSON <out\-var> [ERROR_VARIABLE <error\-var>] |
| \fI\%MEMBER\fP <json\-string> |
| [<member|index> ...] <index>) |
| string(JSON <out\-var> [ERROR_VARIABLE <error\-var>] |
| \fI\%SET\fP <json\-string> |
| <member|index> [<member|index> ...] <value>) |
| string(JSON <out\-var> [ERROR_VARIABLE <error\-var>] |
| \fI\%EQUAL\fP <json\-string1> <json\-string2>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Search and Replace |
| .SS Search and Replace With Plain Strings |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(FIND <string> <substring> <output_variable> [REVERSE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Return the position where the given \fB<substring>\fP was found in |
| the supplied \fB<string>\fP\&. If the \fBREVERSE\fP flag was used, the command will |
| search for the position of the last occurrence of the specified |
| \fB<substring>\fP\&. If the \fB<substring>\fP is not found, a position of \-1 is |
| returned. |
| .sp |
| The \fBstring(FIND)\fP subcommand treats all strings as ASCII\-only characters. |
| The index stored in \fB<output_variable>\fP will also be counted in bytes, |
| so strings containing multi\-byte characters may lead to unexpected results. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(REPLACE <match_string> |
| <replace_string> <output_variable> |
| <input> [<input>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Replace all occurrences of \fB<match_string>\fP in the \fB<input>\fP |
| with \fB<replace_string>\fP and store the result in the \fB<output_variable>\fP\&. |
| .SS Search and Replace With Regular Expressions |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(REGEX MATCH <regular_expression> |
| <output_variable> <input> [<input>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Match the \fB<regular_expression>\fP once and store the match in the |
| \fB<output_variable>\fP\&. |
| All \fB<input>\fP arguments are concatenated before matching. |
| Regular expressions are specified in the subsection just below. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(REGEX MATCHALL <regular_expression> |
| <output_variable> <input> [<input>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Match the \fB<regular_expression>\fP as many times as possible and store the |
| matches in the \fB<output_variable>\fP as a list. |
| All \fB<input>\fP arguments are concatenated before matching. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(REGEX REPLACE <regular_expression> |
| <replacement_expression> <output_variable> |
| <input> [<input>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Match the \fB<regular_expression>\fP as many times as possible and substitute |
| the \fB<replacement_expression>\fP for the match in the output. |
| All \fB<input>\fP arguments are concatenated before matching. |
| .sp |
| The \fB<replacement_expression>\fP may refer to parenthesis\-delimited |
| subexpressions of the match using \fB\e1\fP, \fB\e2\fP, ..., \fB\e9\fP\&. Note that |
| two backslashes (\fB\e\e1\fP) are required in CMake code to get a backslash |
| through argument parsing. |
| .SS Regex Specification |
| .sp |
| The following characters have special meaning in regular expressions: |
| .INDENT 0.0 |
| .TP |
| .B \fB^\fP |
| Matches at beginning of input |
| .TP |
| .B \fB$\fP |
| Matches at end of input |
| .TP |
| .B \fB\&.\fP |
| Matches any single character |
| .TP |
| .B \fB\e<char>\fP |
| Matches the single character specified by \fB<char>\fP\&. Use this to |
| match special regex characters, e.g. \fB\e.\fP for a literal \fB\&.\fP |
| or \fB\e\e\fP for a literal backslash \fB\e\fP\&. Escaping a non\-special |
| character is unnecessary but allowed, e.g. \fB\ea\fP matches \fBa\fP\&. |
| .TP |
| .B \fB[ ]\fP |
| Matches any character(s) inside the brackets |
| .TP |
| .B \fB[^ ]\fP |
| Matches any character(s) not inside the brackets |
| .TP |
| .B \fB\-\fP |
| Inside brackets, specifies an inclusive range between |
| characters on either side e.g. \fB[a\-f]\fP is \fB[abcdef]\fP |
| To match a literal \fB\-\fP using brackets, make it the first |
| or the last character e.g. \fB[+*/\-]\fP matches basic |
| mathematical operators. |
| .TP |
| .B \fB*\fP |
| Matches preceding pattern zero or more times |
| .TP |
| .B \fB+\fP |
| Matches preceding pattern one or more times |
| .TP |
| .B \fB?\fP |
| Matches preceding pattern zero or once only |
| .TP |
| .B \fB|\fP |
| Matches a pattern on either side of the \fB|\fP |
| .TP |
| .B \fB()\fP |
| Saves a matched subexpression, which can be referenced |
| in the \fBREGEX REPLACE\fP operation. |
| .sp |
| New in version 3.9: All regular expression\-related commands, including e.g. |
| \fBif(MATCHES)\fP, save subgroup matches in the variables |
| \fBCMAKE_MATCH_<n>\fP for \fB<n>\fP 0..9. |
| |
| .UNINDENT |
| .sp |
| \fB*\fP, \fB+\fP and \fB?\fP have higher precedence than concatenation. \fB|\fP |
| has lower precedence than concatenation. This means that the regular |
| expression \fB^ab+d$\fP matches \fBabbd\fP but not \fBababd\fP, and the regular |
| expression \fB^(ab|cd)$\fP matches \fBab\fP but not \fBabd\fP\&. |
| .sp |
| CMake language Escape Sequences such as \fB\et\fP, \fB\er\fP, \fB\en\fP, |
| and \fB\e\e\fP may be used to construct literal tabs, carriage returns, |
| newlines, and backslashes (respectively) to pass in a regex. For example: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| The quoted argument \fB"[ \et\er\en]"\fP specifies a regex that matches |
| any single whitespace character. |
| .IP \(bu 2 |
| The quoted argument \fB"[/\e\e]"\fP specifies a regex that matches |
| a single forward slash \fB/\fP or backslash \fB\e\fP\&. |
| .IP \(bu 2 |
| The quoted argument \fB"[A\-Za\-z0\-9_]"\fP specifies a regex that matches |
| any single "word" character in the C locale. |
| .IP \(bu 2 |
| The quoted argument \fB"\e\e(\e\ea\e\e+b\e\e)"\fP specifies a regex that matches |
| the exact string \fB(a+b)\fP\&. Each \fB\e\e\fP is parsed in a quoted argument |
| as just \fB\e\fP, so the regex itself is actually \fB\e(\ea\e+\eb\e)\fP\&. This |
| can alternatively be specified in a bracket argument without |
| having to escape the backslashes, e.g. \fB[[\e(\ea\e+\eb\e)]]\fP\&. |
| .UNINDENT |
| .SS Manipulation |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(APPEND <string_variable> [<input>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.4. |
| |
| .sp |
| Append all the \fB<input>\fP arguments to the string. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(PREPEND <string_variable> [<input>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.10. |
| |
| .sp |
| Prepend all the \fB<input>\fP arguments to the string. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(CONCAT <output_variable> [<input>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Concatenate all the \fB<input>\fP arguments together and store |
| the result in the named \fB<output_variable>\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(JOIN <glue> <output_variable> [<input>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Join all the \fB<input>\fP arguments together using the \fB<glue>\fP |
| string and store the result in the named \fB<output_variable>\fP\&. |
| .sp |
| To join a list\(aqs elements, prefer to use the \fBJOIN\fP operator |
| from the \fBlist()\fP command. This allows for the elements to have |
| special characters like \fB;\fP in them. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(TOLOWER <string> <output_variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Convert \fB<string>\fP to lower characters. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(TOUPPER <string> <output_variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Convert \fB<string>\fP to upper characters. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(LENGTH <string> <output_variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Store in an \fB<output_variable>\fP a given string\(aqs length in bytes. |
| Note that this means if \fB<string>\fP contains multi\-byte characters, the |
| result stored in \fB<output_variable>\fP will \fInot\fP be the number of characters. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(SUBSTRING <string> <begin> <length> <output_variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Store in an \fB<output_variable>\fP a substring of a given \fB<string>\fP\&. If |
| \fB<length>\fP is \fB\-1\fP the remainder of the string starting at \fB<begin>\fP |
| will be returned. |
| .sp |
| Changed in version 3.2: If \fB<string>\fP is shorter than \fB<length>\fP then the end of the string |
| is used instead. Previous versions of CMake reported an error in this case. |
| |
| .sp |
| Both \fB<begin>\fP and \fB<length>\fP are counted in bytes, so care must |
| be exercised if \fB<string>\fP could contain multi\-byte characters. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(STRIP <string> <output_variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Store in an \fB<output_variable>\fP a substring of a given \fB<string>\fP with |
| leading and trailing spaces removed. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(GENEX_STRIP <string> <output_variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Strip any \fBgenerator expressions\fP |
| from the input \fB<string>\fP and store the result in the \fB<output_variable>\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(REPEAT <string> <count> <output_variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.15. |
| |
| .sp |
| Produce the output string as the input \fB<string>\fP repeated \fB<count>\fP times. |
| .SS Comparison |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(COMPARE LESS <string1> <string2> <output_variable>) |
| string(COMPARE GREATER <string1> <string2> <output_variable>) |
| string(COMPARE EQUAL <string1> <string2> <output_variable>) |
| string(COMPARE NOTEQUAL <string1> <string2> <output_variable>) |
| string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>) |
| string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Compare the strings and store true or false in the \fB<output_variable>\fP\&. |
| .sp |
| New in version 3.7: Added the \fBLESS_EQUAL\fP and \fBGREATER_EQUAL\fP options. |
| |
| .SS Hashing |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(<HASH> <output_variable> <input>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Compute a cryptographic hash of the \fB<input>\fP string. |
| The supported \fB<HASH>\fP algorithm names are: |
| .INDENT 0.0 |
| .TP |
| .B \fBMD5\fP |
| Message\-Digest Algorithm 5, RFC 1321. |
| .TP |
| .B \fBSHA1\fP |
| US Secure Hash Algorithm 1, RFC 3174. |
| .TP |
| .B \fBSHA224\fP |
| US Secure Hash Algorithms, RFC 4634. |
| .TP |
| .B \fBSHA256\fP |
| US Secure Hash Algorithms, RFC 4634. |
| .TP |
| .B \fBSHA384\fP |
| US Secure Hash Algorithms, RFC 4634. |
| .TP |
| .B \fBSHA512\fP |
| US Secure Hash Algorithms, RFC 4634. |
| .TP |
| .B \fBSHA3_224\fP |
| Keccak SHA\-3. |
| .TP |
| .B \fBSHA3_256\fP |
| Keccak SHA\-3. |
| .TP |
| .B \fBSHA3_384\fP |
| Keccak SHA\-3. |
| .TP |
| .B \fBSHA3_512\fP |
| Keccak SHA\-3. |
| .UNINDENT |
| .sp |
| New in version 3.8: Added the \fBSHA3_*\fP hash algorithms. |
| |
| .SS Generation |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(ASCII <number> [<number> ...] <output_variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Convert all numbers into corresponding ASCII characters. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(HEX <string> <output_variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.18. |
| |
| .sp |
| Convert each byte in the input \fB<string>\fP to its hexadecimal representation |
| and store the concatenated hex digits in the \fB<output_variable>\fP\&. Letters in |
| the output (\fBa\fP through \fBf\fP) are in lowercase. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(CONFIGURE <string> <output_variable> |
| [@ONLY] [ESCAPE_QUOTES]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Transform a \fB<string>\fP like \fBconfigure_file()\fP transforms a file. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(MAKE_C_IDENTIFIER <string> <output_variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Convert each non\-alphanumeric character in the input \fB<string>\fP to an |
| underscore and store the result in the \fB<output_variable>\fP\&. If the first |
| character of the \fB<string>\fP is a digit, an underscore will also be prepended |
| to the result. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] |
| [RANDOM_SEED <seed>] <output_variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Return a random string of given \fB<length>\fP consisting of |
| characters from the given \fB<alphabet>\fP\&. Default length is 5 characters |
| and default alphabet is all numbers and upper and lower case letters. |
| If an integer \fBRANDOM_SEED\fP is given, its value will be used to seed the |
| random number generator. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(TIMESTAMP <output_variable> [<format_string>] [UTC]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Write a string representation of the current date |
| and/or time to the \fB<output_variable>\fP\&. |
| .sp |
| If the command is unable to obtain a timestamp, the \fB<output_variable>\fP |
| will be set to the empty string \fB""\fP\&. |
| .sp |
| The optional \fBUTC\fP flag requests the current date/time representation to |
| be in Coordinated Universal Time (UTC) rather than local time. |
| .sp |
| The optional \fB<format_string>\fP may contain the following format |
| specifiers: |
| .INDENT 0.0 |
| .TP |
| .B \fB%%\fP |
| New in version 3.8. |
| |
| .sp |
| A literal percent sign (%). |
| .TP |
| .B \fB%d\fP |
| The day of the current month (01\-31). |
| .TP |
| .B \fB%H\fP |
| The hour on a 24\-hour clock (00\-23). |
| .TP |
| .B \fB%I\fP |
| The hour on a 12\-hour clock (01\-12). |
| .TP |
| .B \fB%j\fP |
| The day of the current year (001\-366). |
| .TP |
| .B \fB%m\fP |
| The month of the current year (01\-12). |
| .TP |
| .B \fB%b\fP |
| New in version 3.7. |
| |
| .sp |
| Abbreviated month name (e.g. Oct). |
| .TP |
| .B \fB%B\fP |
| New in version 3.10. |
| |
| .sp |
| Full month name (e.g. October). |
| .TP |
| .B \fB%M\fP |
| The minute of the current hour (00\-59). |
| .TP |
| .B \fB%s\fP |
| New in version 3.6. |
| |
| .sp |
| Seconds since midnight (UTC) 1\-Jan\-1970 (UNIX time). |
| .TP |
| .B \fB%S\fP |
| The second of the current minute. 60 represents a leap second. (00\-60) |
| .TP |
| .B \fB%f\fP |
| The microsecond of the current second (000000\-999999). |
| .TP |
| .B \fB%U\fP |
| The week number of the current year (00\-53). |
| .TP |
| .B \fB%V\fP |
| New in version 3.22. |
| |
| .sp |
| The ISO 8601 week number of the current year (01\-53). |
| .TP |
| .B \fB%w\fP |
| The day of the current week. 0 is Sunday. (0\-6) |
| .TP |
| .B \fB%a\fP |
| New in version 3.7. |
| |
| .sp |
| Abbreviated weekday name (e.g. Fri). |
| .TP |
| .B \fB%A\fP |
| New in version 3.10. |
| |
| .sp |
| Full weekday name (e.g. Friday). |
| .TP |
| .B \fB%y\fP |
| The last two digits of the current year (00\-99). |
| .TP |
| .B \fB%Y\fP |
| The current year. |
| .UNINDENT |
| .sp |
| Unknown format specifiers will be ignored and copied to the output |
| as\-is. |
| .sp |
| If no explicit \fB<format_string>\fP is given, it will default to: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| %Y\-%m\-%dT%H:%M:%S for local time. |
| %Y\-%m\-%dT%H:%M:%SZ for UTC. |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.8: If the \fBSOURCE_DATE_EPOCH\fP environment variable is set, |
| its value will be used instead of the current time. |
| See \fI\%https://reproducible\-builds.org/specs/source\-date\-epoch/\fP for details. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(UUID <output_variable> NAMESPACE <namespace> NAME <name> |
| TYPE <MD5|SHA1> [UPPER]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Create a universally unique identifier (aka GUID) as per RFC4122 |
| based on the hash of the combined values of \fB<namespace>\fP |
| (which itself has to be a valid UUID) and \fB<name>\fP\&. |
| The hash algorithm can be either \fBMD5\fP (Version 3 UUID) or |
| \fBSHA1\fP (Version 5 UUID). |
| A UUID has the format \fBxxxxxxxx\-xxxx\-xxxx\-xxxx\-xxxxxxxxxxxx\fP |
| where each \fBx\fP represents a lower case hexadecimal character. |
| Where required, an uppercase representation can be requested |
| with the optional \fBUPPER\fP flag. |
| .SS JSON |
| .sp |
| New in version 3.19. |
| |
| .sp |
| Functionality for querying a JSON string. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| In each of the following JSON\-related subcommands, if the optional |
| \fBERROR_VARIABLE\fP argument is given, errors will be reported in |
| \fB<error\-variable>\fP and the \fB<out\-var>\fP will be set to |
| \fB<member|index>\-[<member|index>...]\-NOTFOUND\fP with the path elements |
| up to the point where the error occurred, or just \fBNOTFOUND\fP if there |
| is no relevant path. If an error occurs but the \fBERROR_VARIABLE\fP |
| option is not present, a fatal error message is generated. If no error |
| occurs, the \fB<error\-variable>\fP will be set to \fBNOTFOUND\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(JSON <out\-var> [ERROR_VARIABLE <error\-variable>] |
| GET <json\-string> <member|index> [<member|index> ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Get an element from \fB<json\-string>\fP at the location given |
| by the list of \fB<member|index>\fP arguments. |
| Array and object elements will be returned as a JSON string. |
| Boolean elements will be returned as \fBON\fP or \fBOFF\fP\&. |
| Null elements will be returned as an empty string. |
| Number and string types will be returned as strings. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(JSON <out\-var> [ERROR_VARIABLE <error\-variable>] |
| TYPE <json\-string> <member|index> [<member|index> ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Get the type of an element in \fB<json\-string>\fP at the location |
| given by the list of \fB<member|index>\fP arguments. The \fB<out\-var>\fP |
| will be set to one of \fBNULL\fP, \fBNUMBER\fP, \fBSTRING\fP, \fBBOOLEAN\fP, |
| \fBARRAY\fP, or \fBOBJECT\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(JSON <out\-var> [ERROR_VARIABLE <error\-var>] |
| MEMBER <json\-string> |
| [<member|index> ...] <index>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Get the name of the \fB<index>\fP\-th member in \fB<json\-string>\fP at the location |
| given by the list of \fB<member|index>\fP arguments. |
| Requires an element of object type. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(JSON <out\-var> [ERROR_VARIABLE <error\-variable>] |
| LENGTH <json\-string> [<member|index> ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Get the length of an element in \fB<json\-string>\fP at the location |
| given by the list of \fB<member|index>\fP arguments. |
| Requires an element of array or object type. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(JSON <out\-var> [ERROR_VARIABLE <error\-variable>] |
| REMOVE <json\-string> <member|index> [<member|index> ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Remove an element from \fB<json\-string>\fP at the location |
| given by the list of \fB<member|index>\fP arguments. The JSON string |
| without the removed element will be stored in \fB<out\-var>\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(JSON <out\-var> [ERROR_VARIABLE <error\-variable>] |
| SET <json\-string> <member|index> [<member|index> ...] <value>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Set an element in \fB<json\-string>\fP at the location |
| given by the list of \fB<member|index>\fP arguments to \fB<value>\fP\&. |
| The contents of \fB<value>\fP should be valid JSON. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(JSON <out\-var> [ERROR_VARIABLE <error\-var>] |
| EQUAL <json\-string1> <json\-string2>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Compare the two JSON objects given by \fB<json\-string1>\fP and \fB<json\-string2>\fP |
| for equality. The contents of \fB<json\-string1>\fP and \fB<json\-string2>\fP |
| should be valid JSON. The \fB<out\-var>\fP will be set to a true value if the |
| JSON objects are considered equal, or a false value otherwise. |
| .SS unset |
| .sp |
| Unset a variable, cache variable, or environment variable. |
| .SS Unset Normal Variable or Cache Entry |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| unset(<variable> [CACHE | PARENT_SCOPE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Removes a normal variable from the current scope, causing it |
| to become undefined. If \fBCACHE\fP is present, then a cache variable |
| is removed instead of a normal variable. Note that when evaluating |
| Variable References of the form \fB${VAR}\fP, CMake first searches |
| for a normal variable with that name. If no such normal variable exists, |
| CMake will then search for a cache entry with that name. Because of this |
| unsetting a normal variable can expose a cache variable that was previously |
| hidden. To force a variable reference of the form \fB${VAR}\fP to return an |
| empty string, use \fBset(<variable> "")\fP, which clears the normal variable |
| but leaves it defined. |
| .sp |
| If \fBPARENT_SCOPE\fP is present then the variable is removed from the scope |
| above the current scope. See the same option in the \fBset()\fP command |
| for further details. |
| .SS Unset Environment Variable |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| unset(ENV{<variable>}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Removes \fB<variable>\fP from the currently available |
| \fBEnvironment Variables\fP\&. |
| Subsequent calls of \fB$ENV{<variable>}\fP will return the empty string. |
| .sp |
| This command affects only the current CMake process, not the process |
| from which CMake was called, nor the system environment at large, |
| nor the environment of subsequent build or test processes. |
| .SS variable_watch |
| .sp |
| Watch the CMake variable for change. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| variable_watch(<variable> [<command>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If the specified \fB<variable>\fP changes and no \fB<command>\fP is given, |
| a message will be printed to inform about the change. |
| .sp |
| If \fB<command>\fP is given, this command will be executed instead. |
| The command will receive the following arguments: |
| \fBCOMMAND(<variable> <access> <value> <current_list_file> <stack>)\fP |
| .INDENT 0.0 |
| .TP |
| .B \fB<variable>\fP |
| Name of the variable being accessed. |
| .TP |
| .B \fB<access>\fP |
| One of \fBREAD_ACCESS\fP, \fBUNKNOWN_READ_ACCESS\fP, \fBMODIFIED_ACCESS\fP, |
| \fBUNKNOWN_MODIFIED_ACCESS\fP, or \fBREMOVED_ACCESS\fP\&. The \fBUNKNOWN_\fP |
| values are only used when the variable has never been set. Once set, |
| they are never used again during the same CMake run, even if the |
| variable is later unset. |
| .TP |
| .B \fB<value>\fP |
| The value of the variable. On a modification, this is the new |
| (modified) value of the variable. On removal, the value is empty. |
| .TP |
| .B \fB<current_list_file>\fP |
| Full path to the file doing the access. |
| .TP |
| .B \fB<stack>\fP |
| List of absolute paths of all files currently on the stack of file |
| inclusion, with the bottom\-most file first and the currently |
| processed file (that is, \fBcurrent_list_file\fP) last. |
| .UNINDENT |
| .sp |
| Note that for some accesses such as \fBlist(APPEND)\fP, the watcher |
| is executed twice, first with a read access and then with a write one. |
| Also note that an \fBif(DEFINED)\fP query on the variable does not |
| register as an access and the watcher is not executed. |
| .sp |
| Only non\-cache variables can be watched using this command. Access to |
| cache variables is never watched. However, the existence of a cache |
| variable \fBvar\fP causes accesses to the non\-cache variable \fBvar\fP to |
| not use the \fBUNKNOWN_\fP prefix, even if a non\-cache variable \fBvar\fP |
| has never existed. |
| .SS while |
| .sp |
| Evaluate a group of commands while a condition is true |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| while(<condition>) |
| <commands> |
| endwhile() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| All commands between while and the matching \fBendwhile()\fP are recorded |
| without being invoked. Once the \fBendwhile()\fP is evaluated, the |
| recorded list of commands is invoked as long as the \fB<condition>\fP is true. |
| .sp |
| The \fB<condition>\fP has the same syntax and is evaluated using the same logic |
| as described at length for the \fBif()\fP command. |
| .sp |
| The commands \fBbreak()\fP and \fBcontinue()\fP provide means to |
| escape from the normal control flow. |
| .sp |
| Per legacy, the \fBendwhile()\fP command admits |
| an optional \fB<condition>\fP argument. |
| If used, it must be a verbatim repeat of the argument of the opening |
| \fBwhile\fP command. |
| .SH PROJECT COMMANDS |
| .sp |
| These commands are available only in CMake projects. |
| .SS add_compile_definitions |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Add preprocessor definitions to the compilation of source files. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_compile_definitions(<definition> ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Adds preprocessor definitions to the compiler command line. |
| .sp |
| The preprocessor definitions are added to the \fBCOMPILE_DEFINITIONS\fP |
| directory property for the current \fBCMakeLists\fP file. They are also added to |
| the \fBCOMPILE_DEFINITIONS\fP target property for each target in the |
| current \fBCMakeLists\fP file. |
| .sp |
| Definitions are specified using the syntax \fBVAR\fP or \fBVAR=value\fP\&. |
| Function\-style definitions are not supported. CMake will automatically |
| escape the value correctly for the native build system (note that CMake |
| language syntax may require escapes to specify some values). |
| .sp |
| Arguments to \fBadd_compile_definitions\fP may use "generator expressions" with |
| the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .SS add_compile_options |
| .sp |
| Add options to the compilation of source files. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_compile_options(<option> ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Adds options to the \fBCOMPILE_OPTIONS\fP directory property. |
| These options are used when compiling targets from the current |
| directory and below. |
| .SS Arguments |
| .sp |
| Arguments to \fBadd_compile_options\fP may use "generator expressions" with |
| the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .SS Option De\-duplication |
| .sp |
| The final set of options used for a target is constructed by |
| accumulating options from the current target and the usage requirements of |
| its dependencies. The set of options is de\-duplicated to avoid repetition. |
| .sp |
| New in version 3.12: While beneficial for individual options, the de\-duplication step can break |
| up option groups. For example, \fB\-option A \-option B\fP becomes |
| \fB\-option A B\fP\&. One may specify a group of options using shell\-like |
| quoting along with a \fBSHELL:\fP prefix. The \fBSHELL:\fP prefix is dropped, |
| and the rest of the option string is parsed using the |
| \fBseparate_arguments()\fP \fBUNIX_COMMAND\fP mode. For example, |
| \fB"SHELL:\-option A" "SHELL:\-option B"\fP becomes \fB\-option A \-option B\fP\&. |
| |
| .SS Example |
| .sp |
| Since different compilers support different options, a typical use of |
| this command is in a compiler\-specific conditional clause: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| if (MSVC) |
| # warning level 4 and all warnings as errors |
| add_compile_options(/W4 /WX) |
| else() |
| # lots of warnings and all warnings as errors |
| add_compile_options(\-Wall \-Wextra \-pedantic \-Werror) |
| endif() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS See Also |
| .sp |
| This command can be used to add any options. However, for |
| adding preprocessor definitions and include directories it is recommended |
| to use the more specific commands \fBadd_compile_definitions()\fP |
| and \fBinclude_directories()\fP\&. |
| .sp |
| The command \fBtarget_compile_options()\fP adds target\-specific options. |
| .sp |
| The source file property \fBCOMPILE_OPTIONS\fP adds options to one |
| source file. |
| .SS add_custom_command |
| .sp |
| Add a custom build rule to the generated build system. |
| .sp |
| There are two main signatures for \fBadd_custom_command\fP\&. |
| .SS Generating Files |
| .sp |
| The first signature is for adding a custom command to produce an output: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_custom_command(OUTPUT output1 [output2 ...] |
| COMMAND command1 [ARGS] [args1...] |
| [COMMAND command2 [ARGS] [args2...] ...] |
| [MAIN_DEPENDENCY depend] |
| [DEPENDS [depends...]] |
| [BYPRODUCTS [files...]] |
| [IMPLICIT_DEPENDS <lang1> depend1 |
| [<lang2> depend2] ...] |
| [WORKING_DIRECTORY dir] |
| [COMMENT comment] |
| [DEPFILE depfile] |
| [JOB_POOL job_pool] |
| [VERBATIM] [APPEND] [USES_TERMINAL] |
| [COMMAND_EXPAND_LISTS]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This defines a command to generate specified \fBOUTPUT\fP file(s). |
| A target created in the same directory (\fBCMakeLists.txt\fP file) |
| that specifies any output of the custom command as a source file |
| is given a rule to generate the file using the command at build time. |
| Do not list the output in more than one independent target that |
| may build in parallel or the two instances of the rule may conflict |
| (instead use the \fBadd_custom_target()\fP command to drive the |
| command and make the other targets depend on that one). |
| In makefile terms this creates a new target in the following form: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| OUTPUT: MAIN_DEPENDENCY DEPENDS |
| COMMAND |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBAPPEND\fP |
| Append the \fBCOMMAND\fP and \fBDEPENDS\fP option values to the custom |
| command for the first output specified. There must have already |
| been a previous call to this command with the same output. |
| .sp |
| If the previous call specified the output via a generator expression, |
| the output specified by the current call must match in at least one |
| configuration after evaluating generator expressions. In this case, |
| the appended commands and dependencies apply to all configurations. |
| .sp |
| The \fBCOMMENT\fP, \fBMAIN_DEPENDENCY\fP, and \fBWORKING_DIRECTORY\fP |
| options are currently ignored when APPEND is given, but may be |
| used in the future. |
| .TP |
| .B \fBBYPRODUCTS\fP |
| New in version 3.2. |
| |
| .sp |
| Specify the files the command is expected to produce but whose |
| modification time may or may not be newer than the dependencies. |
| If a byproduct name is a relative path it will be interpreted |
| relative to the build tree directory corresponding to the |
| current source directory. |
| Each byproduct file will be marked with the \fBGENERATED\fP |
| source file property automatically. |
| .sp |
| Explicit specification of byproducts is supported by the |
| \fBNinja\fP generator to tell the \fBninja\fP build tool |
| how to regenerate byproducts when they are missing. It is |
| also useful when other build rules (e.g. custom commands) |
| depend on the byproducts. Ninja requires a build rule for any |
| generated file on which another rule depends even if there are |
| order\-only dependencies to ensure the byproducts will be |
| available before their dependents build. |
| .sp |
| The Makefile Generators will remove \fBBYPRODUCTS\fP and other |
| \fBGENERATED\fP files during \fBmake clean\fP\&. |
| .sp |
| New in version 3.20: Arguments to \fBBYPRODUCTS\fP may use a restricted set of |
| \fBgenerator expressions\fP\&. |
| Target\-dependent expressions are not |
| permitted. |
| |
| .TP |
| .B \fBCOMMAND\fP |
| Specify the command\-line(s) to execute at build time. |
| If more than one \fBCOMMAND\fP is specified they will be executed in order, |
| but \fInot\fP necessarily composed into a stateful shell or batch script. |
| (To run a full script, use the \fBconfigure_file()\fP command or the |
| \fBfile(GENERATE)\fP command to create it, and then specify |
| a \fBCOMMAND\fP to launch it.) |
| The optional \fBARGS\fP argument is for backward compatibility and |
| will be ignored. |
| .sp |
| If \fBCOMMAND\fP specifies an executable target name (created by the |
| \fBadd_executable()\fP command), it will automatically be replaced |
| by the location of the executable created at build time if either of |
| the following is true: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| The target is not being cross\-compiled (i.e. the |
| \fBCMAKE_CROSSCOMPILING\fP variable is not set to true). |
| .IP \(bu 2 |
| New in version 3.6: The target is being cross\-compiled and an emulator is provided (i.e. |
| its \fBCROSSCOMPILING_EMULATOR\fP target property is set). |
| In this case, the contents of \fBCROSSCOMPILING_EMULATOR\fP will be |
| prepended to the command before the location of the target executable. |
| |
| .UNINDENT |
| .sp |
| If neither of the above conditions are met, it is assumed that the |
| command name is a program to be found on the \fBPATH\fP at build time. |
| .sp |
| Arguments to \fBCOMMAND\fP may use |
| \fBgenerator expressions\fP\&. |
| Use the \fBTARGET_FILE\fP generator expression to refer to the location |
| of a target later in the command line (i.e. as a command argument rather |
| than as the command to execute). |
| .sp |
| Whenever one of the following target based generator expressions are used as |
| a command to execute or is mentioned in a command argument, a target\-level |
| dependency will be added automatically so that the mentioned target will be |
| built before any target using this custom command |
| (see policy \fBCMP0112\fP). |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBTARGET_FILE\fP |
| .IP \(bu 2 |
| \fBTARGET_LINKER_FILE\fP |
| .IP \(bu 2 |
| \fBTARGET_SONAME_FILE\fP |
| .IP \(bu 2 |
| \fBTARGET_PDB_FILE\fP |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This target\-level dependency does NOT add a file\-level dependency that would |
| cause the custom command to re\-run whenever the executable is recompiled. |
| List target names with the \fBDEPENDS\fP option to add such file\-level |
| dependencies. |
| .TP |
| .B \fBCOMMENT\fP |
| Display the given message before the commands are executed at |
| build time. |
| .TP |
| .B \fBDEPENDS\fP |
| Specify files on which the command depends. Each argument is converted |
| to a dependency as follows: |
| .INDENT 7.0 |
| .IP 1. 3 |
| If the argument is the name of a target (created by the |
| \fBadd_custom_target()\fP, \fBadd_executable()\fP, or |
| \fBadd_library()\fP command) a target\-level dependency is |
| created to make sure the target is built before any target |
| using this custom command. Additionally, if the target is an |
| executable or library, a file\-level dependency is created to |
| cause the custom command to re\-run whenever the target is |
| recompiled. |
| .IP 2. 3 |
| If the argument is an absolute path, a file\-level dependency |
| is created on that path. |
| .IP 3. 3 |
| If the argument is the name of a source file that has been |
| added to a target or on which a source file property has been set, |
| a file\-level dependency is created on that source file. |
| .IP 4. 3 |
| If the argument is a relative path and it exists in the current |
| source directory, a file\-level dependency is created on that |
| file in the current source directory. |
| .IP 5. 3 |
| Otherwise, a file\-level dependency is created on that path relative |
| to the current binary directory. |
| .UNINDENT |
| .sp |
| If any dependency is an \fBOUTPUT\fP of another custom command in the same |
| directory (\fBCMakeLists.txt\fP file), CMake automatically brings the other |
| custom command into the target in which this command is built. |
| .sp |
| New in version 3.16: A target\-level dependency is added if any dependency is listed as |
| \fBBYPRODUCTS\fP of a target or any of its build events in the same |
| directory to ensure the byproducts will be available. |
| |
| .sp |
| If \fBDEPENDS\fP is not specified, the command will run whenever |
| the \fBOUTPUT\fP is missing; if the command does not actually |
| create the \fBOUTPUT\fP, the rule will always run. |
| .sp |
| New in version 3.1: Arguments to \fBDEPENDS\fP may use |
| \fBgenerator expressions\fP\&. |
| |
| .TP |
| .B \fBCOMMAND_EXPAND_LISTS\fP |
| New in version 3.8. |
| |
| .sp |
| Lists in \fBCOMMAND\fP arguments will be expanded, including those |
| created with |
| \fBgenerator expressions\fP, |
| allowing \fBCOMMAND\fP arguments such as |
| \fB${CC} "\-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;\-I>" foo.cc\fP |
| to be properly expanded. |
| .TP |
| .B \fBIMPLICIT_DEPENDS\fP |
| Request scanning of implicit dependencies of an input file. |
| The language given specifies the programming language whose |
| corresponding dependency scanner should be used. |
| Currently only \fBC\fP and \fBCXX\fP language scanners are supported. |
| The language has to be specified for every file in the |
| \fBIMPLICIT_DEPENDS\fP list. Dependencies discovered from the |
| scanning are added to those of the custom command at build time. |
| Note that the \fBIMPLICIT_DEPENDS\fP option is currently supported |
| only for Makefile generators and will be ignored by other generators. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| This option cannot be specified at the same time as \fBDEPFILE\fP option. |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBJOB_POOL\fP |
| New in version 3.15. |
| |
| .sp |
| Specify a \fBpool\fP for the \fBNinja\fP |
| generator. Incompatible with \fBUSES_TERMINAL\fP, which implies |
| the \fBconsole\fP pool. |
| Using a pool that is not defined by \fBJOB_POOLS\fP causes |
| an error by ninja at build time. |
| .TP |
| .B \fBMAIN_DEPENDENCY\fP |
| Specify the primary input source file to the command. This is |
| treated just like any value given to the \fBDEPENDS\fP option |
| but also suggests to Visual Studio generators where to hang |
| the custom command. Each source file may have at most one command |
| specifying it as its main dependency. A compile command (i.e. for a |
| library or an executable) counts as an implicit main dependency which |
| gets silently overwritten by a custom command specification. |
| .TP |
| .B \fBOUTPUT\fP |
| Specify the output files the command is expected to produce. |
| If an output name is a relative path it will be interpreted |
| relative to the build tree directory corresponding to the |
| current source directory. |
| Each output file will be marked with the \fBGENERATED\fP |
| source file property automatically. |
| If the output of the custom command is not actually created |
| as a file on disk it should be marked with the \fBSYMBOLIC\fP |
| source file property. |
| .sp |
| New in version 3.20: Arguments to \fBOUTPUT\fP may use a restricted set of |
| \fBgenerator expressions\fP\&. |
| Target\-dependent expressions are not |
| permitted. |
| |
| .TP |
| .B \fBUSES_TERMINAL\fP |
| New in version 3.2. |
| |
| .sp |
| The command will be given direct access to the terminal if possible. |
| With the \fBNinja\fP generator, this places the command in |
| the \fBconsole\fP \fBpool\fP\&. |
| .TP |
| .B \fBVERBATIM\fP |
| All arguments to the commands will be escaped properly for the |
| build tool so that the invoked command receives each argument |
| unchanged. Note that one level of escapes is still used by the |
| CMake language processor before add_custom_command even sees the |
| arguments. Use of \fBVERBATIM\fP is recommended as it enables |
| correct behavior. When \fBVERBATIM\fP is not given the behavior |
| is platform specific because there is no protection of |
| tool\-specific special characters. |
| .TP |
| .B \fBWORKING_DIRECTORY\fP |
| Execute the command with the given current working directory. |
| If it is a relative path it will be interpreted relative to the |
| build tree directory corresponding to the current source directory. |
| .sp |
| New in version 3.13: Arguments to \fBWORKING_DIRECTORY\fP may use |
| \fBgenerator expressions\fP\&. |
| |
| .TP |
| .B \fBDEPFILE\fP |
| New in version 3.7. |
| |
| .sp |
| Specify a depfile which holds dependencies for the custom command. It is |
| usually emitted by the custom command itself. This keyword may only be used |
| if the generator supports it, as detailed below. |
| .sp |
| The expected format, compatible with what is generated by \fBgcc\fP with the |
| option \fB\-M\fP, is independent of the generator or platform. |
| .sp |
| The formal syntax, as specified using |
| \fI\%BNF\fP notation with |
| the regular extensions, is the following: |
| .sp |
| .nf |
| \fBdepfile \fP ::= \fBrule\fP* |
| \fBrule \fP ::= \fBtargets\fP (\(ga:\(ga (\fBseparator\fP \fBdependencies\fP?)?)? \fBeol\fP |
| \fBtargets \fP ::= \fBtarget\fP (\fBseparator\fP \fBtarget\fP)* \fBseparator\fP* |
| \fBtarget \fP ::= \fBpathname\fP |
| \fBdependencies \fP ::= \fBdependency\fP (\fBseparator\fP \fBdependency\fP)* \fBseparator\fP* |
| \fBdependency \fP ::= \fBpathname\fP |
| \fBseparator \fP ::= (space | line_continue)+ |
| \fBline_continue\fP ::= \(aq\e\(aq \fBeol\fP |
| \fBspace \fP ::= \(aq \(aq | \(aq\et\(aq |
| \fBpathname \fP ::= \fBcharacter\fP+ |
| \fBcharacter \fP ::= \fBstd_character\fP | \fBdollar\fP | \fBhash\fP | \fBwhitespace\fP |
| \fBstd_character\fP ::= <any character except \(aq$\(aq, \(aq#\(aq or \(aq \(aq> |
| \fBdollar \fP ::= \(aq$$\(aq |
| \fBhash \fP ::= \(aq\e#\(aq |
| \fBwhitespace \fP ::= \(aq\e \(aq |
| \fBeol \fP ::= \(aq\er\(aq? \(aq\en\(aq |
| |
| .fi |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| As part of \fBpathname\fP, any slash and backslash is interpreted as |
| a directory separator. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.7: The \fBNinja\fP generator supports \fBDEPFILE\fP since the keyword |
| was first added. |
| |
| .sp |
| New in version 3.17: Added the \fBNinja Multi\-Config\fP generator, which included |
| support for the \fBDEPFILE\fP keyword. |
| |
| .sp |
| New in version 3.20: Added support for Makefile Generators\&. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 7.0 |
| .INDENT 3.5 |
| \fBDEPFILE\fP cannot be specified at the same time as the |
| \fBIMPLICIT_DEPENDS\fP option for Makefile Generators\&. |
| .UNINDENT |
| .UNINDENT |
| |
| .sp |
| New in version 3.21: Added support for Visual Studio Generators with VS 2012 and above, |
| and for the \fBXcode\fP generator. Support for |
| \fBgenerator expressions\fP was also |
| added. |
| |
| .sp |
| Using \fBDEPFILE\fP with generators other than those listed above is an error. |
| .sp |
| If the \fBDEPFILE\fP argument is relative, it should be relative to |
| \fBCMAKE_CURRENT_BINARY_DIR\fP, and any relative paths inside the |
| \fBDEPFILE\fP should also be relative to \fBCMAKE_CURRENT_BINARY_DIR\fP\&. |
| See policy \fBCMP0116\fP, which is always \fBNEW\fP for |
| Makefile Generators, Visual Studio Generators, |
| and the \fBXcode\fP generator. |
| .UNINDENT |
| .SS Examples: Generating Files |
| .sp |
| Custom commands may be used to generate source files. |
| For example, the code: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_custom_command( |
| OUTPUT out.c |
| COMMAND someTool \-i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt |
| \-o out.c |
| DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt |
| VERBATIM) |
| add_library(myLib out.c) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| adds a custom command to run \fBsomeTool\fP to generate \fBout.c\fP and then |
| compile the generated source as part of a library. The generation rule |
| will re\-run whenever \fBin.txt\fP changes. |
| .sp |
| New in version 3.20: One may use generator expressions to specify per\-configuration outputs. |
| For example, the code: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_custom_command( |
| OUTPUT "out\-$<CONFIG>.c" |
| COMMAND someTool \-i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt |
| \-o "out\-$<CONFIG>.c" |
| \-c "$<CONFIG>" |
| DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt |
| VERBATIM) |
| add_library(myLib "out\-$<CONFIG>.c") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| adds a custom command to run \fBsomeTool\fP to generate \fBout\-<config>.c\fP, |
| where \fB<config>\fP is the build configuration, and then compile the generated |
| source as part of a library. |
| |
| .SS Build Events |
| .sp |
| The second signature adds a custom command to a target such as a |
| library or executable. This is useful for performing an operation |
| before or after building the target. The command becomes part of the |
| target and will only execute when the target itself is built. If the |
| target is already built, the command will not execute. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_custom_command(TARGET <target> |
| PRE_BUILD | PRE_LINK | POST_BUILD |
| COMMAND command1 [ARGS] [args1...] |
| [COMMAND command2 [ARGS] [args2...] ...] |
| [BYPRODUCTS [files...]] |
| [WORKING_DIRECTORY dir] |
| [COMMENT comment] |
| [VERBATIM] [USES_TERMINAL] |
| [COMMAND_EXPAND_LISTS]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This defines a new command that will be associated with building the |
| specified \fB<target>\fP\&. The \fB<target>\fP must be defined in the current |
| directory; targets defined in other directories may not be specified. |
| .sp |
| When the command will happen is determined by which |
| of the following is specified: |
| .INDENT 0.0 |
| .TP |
| .B \fBPRE_BUILD\fP |
| On Visual Studio Generators, run before any other rules are |
| executed within the target. |
| On other generators, run just before \fBPRE_LINK\fP commands. |
| .TP |
| .B \fBPRE_LINK\fP |
| Run after sources have been compiled but before linking the binary |
| or running the librarian or archiver tool of a static library. |
| This is not defined for targets created by the |
| \fBadd_custom_target()\fP command. |
| .TP |
| .B \fBPOST_BUILD\fP |
| Run after all other rules within the target have been executed. |
| .UNINDENT |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Because generator expressions can be used in custom commands, |
| it is possible to define \fBCOMMAND\fP lines or whole custom commands |
| which evaluate to empty strings for certain configurations. |
| For \fBVisual Studio 2010 (and newer)\fP generators these command |
| lines or custom commands will be omitted for the specific |
| configuration and no "empty\-string\-command" will be added. |
| .sp |
| This allows to add individual build events for every configuration. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.21: Support for target\-dependent generator expressions. |
| |
| .SS Examples: Build Events |
| .sp |
| A \fBPOST_BUILD\fP event may be used to post\-process a binary after linking. |
| For example, the code: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_executable(myExe myExe.c) |
| add_custom_command( |
| TARGET myExe POST_BUILD |
| COMMAND someHasher \-i "$<TARGET_FILE:myExe>" |
| \-o "$<TARGET_FILE:myExe>.hash" |
| VERBATIM) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will run \fBsomeHasher\fP to produce a \fB\&.hash\fP file next to the executable |
| after linking. |
| .sp |
| New in version 3.20: One may use generator expressions to specify per\-configuration byproducts. |
| For example, the code: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(myPlugin MODULE myPlugin.c) |
| add_custom_command( |
| TARGET myPlugin POST_BUILD |
| COMMAND someHasher \-i "$<TARGET_FILE:myPlugin>" |
| \-\-as\-code "myPlugin\-hash\-$<CONFIG>.c" |
| BYPRODUCTS "myPlugin\-hash\-$<CONFIG>.c" |
| VERBATIM) |
| add_executable(myExe myExe.c "myPlugin\-hash\-$<CONFIG>.c") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will run \fBsomeHasher\fP after linking \fBmyPlugin\fP, e.g. to produce a \fB\&.c\fP |
| file containing code to check the hash of \fBmyPlugin\fP that the \fBmyExe\fP |
| executable can use to verify it before loading. |
| |
| .SS Ninja Multi\-Config |
| .sp |
| New in version 3.20: \fBadd_custom_command\fP supports the \fBNinja Multi\-Config\fP |
| generator\(aqs cross\-config capabilities. See the generator documentation |
| for more information. |
| |
| .SS add_custom_target |
| .sp |
| Add a target with no output so it will always be built. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_custom_target(Name [ALL] [command1 [args1...]] |
| [COMMAND command2 [args2...] ...] |
| [DEPENDS depend depend depend ... ] |
| [BYPRODUCTS [files...]] |
| [WORKING_DIRECTORY dir] |
| [COMMENT comment] |
| [JOB_POOL job_pool] |
| [VERBATIM] [USES_TERMINAL] |
| [COMMAND_EXPAND_LISTS] |
| [SOURCES src1 [src2...]]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Adds a target with the given name that executes the given commands. |
| The target has no output file and is \fIalways considered out of date\fP |
| even if the commands try to create a file with the name of the target. |
| Use the \fBadd_custom_command()\fP command to generate a file with |
| dependencies. By default nothing depends on the custom target. Use |
| the \fBadd_dependencies()\fP command to add dependencies to or |
| from other targets. |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBALL\fP |
| Indicate that this target should be added to the default build |
| target so that it will be run every time (the command cannot be |
| called \fBALL\fP). |
| .TP |
| .B \fBBYPRODUCTS\fP |
| New in version 3.2. |
| |
| .sp |
| Specify the files the command is expected to produce but whose |
| modification time may or may not be updated on subsequent builds. |
| If a byproduct name is a relative path it will be interpreted |
| relative to the build tree directory corresponding to the |
| current source directory. |
| Each byproduct file will be marked with the \fBGENERATED\fP |
| source file property automatically. |
| .sp |
| Explicit specification of byproducts is supported by the |
| \fBNinja\fP generator to tell the \fBninja\fP build tool |
| how to regenerate byproducts when they are missing. It is |
| also useful when other build rules (e.g. custom commands) |
| depend on the byproducts. Ninja requires a build rule for any |
| generated file on which another rule depends even if there are |
| order\-only dependencies to ensure the byproducts will be |
| available before their dependents build. |
| .sp |
| The Makefile Generators will remove \fBBYPRODUCTS\fP and other |
| \fBGENERATED\fP files during \fBmake clean\fP\&. |
| .sp |
| New in version 3.20: Arguments to \fBBYPRODUCTS\fP may use a restricted set of |
| \fBgenerator expressions\fP\&. |
| Target\-dependent expressions are not |
| permitted. |
| |
| .TP |
| .B \fBCOMMAND\fP |
| Specify the command\-line(s) to execute at build time. |
| If more than one \fBCOMMAND\fP is specified they will be executed in order, |
| but \fInot\fP necessarily composed into a stateful shell or batch script. |
| (To run a full script, use the \fBconfigure_file()\fP command or the |
| \fBfile(GENERATE)\fP command to create it, and then specify |
| a \fBCOMMAND\fP to launch it.) |
| .sp |
| If \fBCOMMAND\fP specifies an executable target name (created by the |
| \fBadd_executable()\fP command), it will automatically be replaced |
| by the location of the executable created at build time if either of |
| the following is true: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| The target is not being cross\-compiled (i.e. the |
| \fBCMAKE_CROSSCOMPILING\fP variable is not set to true). |
| .IP \(bu 2 |
| New in version 3.6: The target is being cross\-compiled and an emulator is provided (i.e. |
| its \fBCROSSCOMPILING_EMULATOR\fP target property is set). |
| In this case, the contents of \fBCROSSCOMPILING_EMULATOR\fP will be |
| prepended to the command before the location of the target executable. |
| |
| .UNINDENT |
| .sp |
| If neither of the above conditions are met, it is assumed that the |
| command name is a program to be found on the \fBPATH\fP at build time. |
| .sp |
| Arguments to \fBCOMMAND\fP may use |
| \fBgenerator expressions\fP\&. |
| Use the \fBTARGET_FILE\fP generator expression to refer to the location |
| of a target later in the command line (i.e. as a command argument rather |
| than as the command to execute). |
| .sp |
| Whenever one of the following target based generator expressions are used as |
| a command to execute or is mentioned in a command argument, a target\-level |
| dependency will be added automatically so that the mentioned target will be |
| built before this custom target (see policy \fBCMP0112\fP). |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBTARGET_FILE\fP |
| .IP \(bu 2 |
| \fBTARGET_LINKER_FILE\fP |
| .IP \(bu 2 |
| \fBTARGET_SONAME_FILE\fP |
| .IP \(bu 2 |
| \fBTARGET_PDB_FILE\fP |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The command and arguments are optional and if not specified an empty |
| target will be created. |
| .TP |
| .B \fBCOMMENT\fP |
| Display the given message before the commands are executed at |
| build time. |
| .TP |
| .B \fBDEPENDS\fP |
| Reference files and outputs of custom commands created with |
| \fBadd_custom_command()\fP command calls in the same directory |
| (\fBCMakeLists.txt\fP file). They will be brought up to date when |
| the target is built. |
| .sp |
| Changed in version 3.16: A target\-level dependency is added if any dependency is a byproduct |
| of a target or any of its build events in the same directory to ensure |
| the byproducts will be available before this target is built. |
| |
| .sp |
| Use the \fBadd_dependencies()\fP command to add dependencies |
| on other targets. |
| .TP |
| .B \fBCOMMAND_EXPAND_LISTS\fP |
| New in version 3.8. |
| |
| .sp |
| Lists in \fBCOMMAND\fP arguments will be expanded, including those |
| created with |
| \fBgenerator expressions\fP, |
| allowing \fBCOMMAND\fP arguments such as |
| \fB${CC} "\-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;\-I>" foo.cc\fP |
| to be properly expanded. |
| .TP |
| .B \fBJOB_POOL\fP |
| New in version 3.15. |
| |
| .sp |
| Specify a \fBpool\fP for the \fBNinja\fP |
| generator. Incompatible with \fBUSES_TERMINAL\fP, which implies |
| the \fBconsole\fP pool. |
| Using a pool that is not defined by \fBJOB_POOLS\fP causes |
| an error by ninja at build time. |
| .TP |
| .B \fBSOURCES\fP |
| Specify additional source files to be included in the custom target. |
| Specified source files will be added to IDE project files for |
| convenience in editing even if they have no build rules. |
| .TP |
| .B \fBVERBATIM\fP |
| All arguments to the commands will be escaped properly for the |
| build tool so that the invoked command receives each argument |
| unchanged. Note that one level of escapes is still used by the |
| CMake language processor before \fBadd_custom_target\fP even sees |
| the arguments. Use of \fBVERBATIM\fP is recommended as it enables |
| correct behavior. When \fBVERBATIM\fP is not given the behavior |
| is platform specific because there is no protection of |
| tool\-specific special characters. |
| .TP |
| .B \fBUSES_TERMINAL\fP |
| New in version 3.2. |
| |
| .sp |
| The command will be given direct access to the terminal if possible. |
| With the \fBNinja\fP generator, this places the command in |
| the \fBconsole\fP \fBpool\fP\&. |
| .TP |
| .B \fBWORKING_DIRECTORY\fP |
| Execute the command with the given current working directory. |
| If it is a relative path it will be interpreted relative to the |
| build tree directory corresponding to the current source directory. |
| .sp |
| New in version 3.13: Arguments to \fBWORKING_DIRECTORY\fP may use |
| \fBgenerator expressions\fP\&. |
| |
| .UNINDENT |
| .SS Ninja Multi\-Config |
| .sp |
| New in version 3.20: \fBadd_custom_target\fP supports the \fBNinja Multi\-Config\fP |
| generator\(aqs cross\-config capabilities. See the generator documentation |
| for more information. |
| |
| .SS add_definitions |
| .sp |
| Add \-D define flags to the compilation of source files. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_definitions(\-DFOO \-DBAR ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Adds definitions to the compiler command line for targets in the current |
| directory, whether added before or after this command is invoked, and for |
| the ones in sub\-directories added after. This command can be used to add any |
| flags, but it is intended to add preprocessor definitions. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This command has been superseded by alternatives: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| Use \fBadd_compile_definitions()\fP to add preprocessor definitions. |
| .IP \(bu 2 |
| Use \fBinclude_directories()\fP to add include directories. |
| .IP \(bu 2 |
| Use \fBadd_compile_options()\fP to add other options. |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Flags beginning in \fB\-D\fP or \fB/D\fP that look like preprocessor definitions are |
| automatically added to the \fBCOMPILE_DEFINITIONS\fP directory |
| property for the current directory. Definitions with non\-trivial values |
| may be left in the set of flags instead of being converted for reasons of |
| backwards compatibility. See documentation of the |
| \fBdirectory\fP, |
| \fBtarget\fP, |
| \fBsource file\fP \fBCOMPILE_DEFINITIONS\fP |
| properties for details on adding preprocessor definitions to specific |
| scopes and configurations. |
| .sp |
| See the \fBcmake\-buildsystem(7)\fP manual for more on defining |
| buildsystem properties. |
| .SS add_dependencies |
| .sp |
| Add a dependency between top\-level targets. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_dependencies(<target> [<target\-dependency>]...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Makes a top\-level \fB<target>\fP depend on other top\-level targets to |
| ensure that they build before \fB<target>\fP does. A top\-level target |
| is one created by one of the \fBadd_executable()\fP, |
| \fBadd_library()\fP, or \fBadd_custom_target()\fP commands |
| (but not targets generated by CMake like \fBinstall\fP). |
| .sp |
| Dependencies added to an imported target |
| or an interface library are followed |
| transitively in its place since the target itself does not build. |
| .sp |
| New in version 3.3: Allow adding dependencies to interface libraries. |
| |
| .sp |
| See the \fBDEPENDS\fP option of \fBadd_custom_target()\fP and |
| \fBadd_custom_command()\fP commands for adding file\-level |
| dependencies in custom rules. See the \fBOBJECT_DEPENDS\fP |
| source file property to add file\-level dependencies to object files. |
| .SS add_executable |
| .sp |
| Add an executable to the project using the specified source files. |
| .SS Normal Executables |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_executable(<name> [WIN32] [MACOSX_BUNDLE] |
| [EXCLUDE_FROM_ALL] |
| [source1] [source2 ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Adds an executable target called \fB<name>\fP to be built from the source |
| files listed in the command invocation. The |
| \fB<name>\fP corresponds to the logical target name and must be globally |
| unique within a project. The actual file name of the executable built is |
| constructed based on conventions of the native platform (such as |
| \fB<name>.exe\fP or just \fB<name>\fP). |
| .sp |
| New in version 3.1: Source arguments to \fBadd_executable\fP may use "generator expressions" with |
| the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. |
| |
| .sp |
| New in version 3.11: The source files can be omitted if they are added later using |
| \fBtarget_sources()\fP\&. |
| |
| .sp |
| By default the executable file will be created in the build tree |
| directory corresponding to the source tree directory in which the |
| command was invoked. See documentation of the |
| \fBRUNTIME_OUTPUT_DIRECTORY\fP target property to change this |
| location. See documentation of the \fBOUTPUT_NAME\fP target property |
| to change the \fB<name>\fP part of the final file name. |
| .sp |
| If \fBWIN32\fP is given the property \fBWIN32_EXECUTABLE\fP will be |
| set on the target created. See documentation of that target property for |
| details. |
| .sp |
| If \fBMACOSX_BUNDLE\fP is given the corresponding property will be set on |
| the created target. See documentation of the \fBMACOSX_BUNDLE\fP |
| target property for details. |
| .sp |
| If \fBEXCLUDE_FROM_ALL\fP is given the corresponding property will be set on |
| the created target. See documentation of the \fBEXCLUDE_FROM_ALL\fP |
| target property for details. |
| .sp |
| See the \fBcmake\-buildsystem(7)\fP manual for more on defining |
| buildsystem properties. |
| .sp |
| See also \fBHEADER_FILE_ONLY\fP on what to do if some sources are |
| pre\-processed, and you want to have the original sources reachable from |
| within IDE. |
| .SS Imported Executables |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_executable(<name> IMPORTED [GLOBAL]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| An IMPORTED executable target references an |
| executable file located outside the project. No rules are generated to |
| build it, and the \fBIMPORTED\fP target property is \fBTrue\fP\&. The |
| target name has scope in the directory in which it is created and below, but |
| the \fBGLOBAL\fP option extends visibility. It may be referenced like any |
| target built within the project. \fBIMPORTED\fP executables are useful |
| for convenient reference from commands like \fBadd_custom_command()\fP\&. |
| Details about the imported executable are specified by setting properties |
| whose names begin in \fBIMPORTED_\fP\&. The most important such property is |
| \fBIMPORTED_LOCATION\fP (and its per\-configuration version |
| \fBIMPORTED_LOCATION_<CONFIG>\fP) which specifies the location of |
| the main executable file on disk. See documentation of the \fBIMPORTED_*\fP |
| properties for more information. |
| .SS Alias Executables |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_executable(<name> ALIAS <target>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Creates an Alias Target, such that \fB<name>\fP can |
| be used to refer to \fB<target>\fP in subsequent commands. The \fB<name>\fP |
| does not appear in the generated buildsystem as a make target. The |
| \fB<target>\fP may not be an \fBALIAS\fP\&. |
| .sp |
| New in version 3.11: An \fBALIAS\fP can target a \fBGLOBAL\fP Imported Target |
| |
| .sp |
| New in version 3.18: An \fBALIAS\fP can target a non\-\fBGLOBAL\fP Imported Target. Such alias is |
| scoped to the directory in which it is created and subdirectories. |
| The \fBALIAS_GLOBAL\fP target property can be used to check if the |
| alias is global or not. |
| |
| .sp |
| \fBALIAS\fP targets can be used as targets to read properties |
| from, executables for custom commands and custom targets. They can also be |
| tested for existence with the regular \fBif(TARGET)\fP subcommand. |
| The \fB<name>\fP may not be used to modify properties of \fB<target>\fP, that |
| is, it may not be used as the operand of \fBset_property()\fP, |
| \fBset_target_properties()\fP, \fBtarget_link_libraries()\fP etc. |
| An \fBALIAS\fP target may not be installed or exported. |
| .SS add_library |
| .sp |
| Add a library to the project using the specified source files. |
| .SS Normal Libraries |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(<name> [STATIC | SHARED | MODULE] |
| [EXCLUDE_FROM_ALL] |
| [<source>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Adds a library target called \fB<name>\fP to be built from the source files |
| listed in the command invocation. The \fB<name>\fP |
| corresponds to the logical target name and must be globally unique within |
| a project. The actual file name of the library built is constructed based |
| on conventions of the native platform (such as \fBlib<name>.a\fP or |
| \fB<name>.lib\fP). |
| .sp |
| New in version 3.1: Source arguments to \fBadd_library\fP may use "generator expressions" with |
| the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. |
| |
| .sp |
| New in version 3.11: The source files can be omitted if they are added later using |
| \fBtarget_sources()\fP\&. |
| |
| .sp |
| \fBSTATIC\fP, \fBSHARED\fP, or \fBMODULE\fP may be given to specify the type of |
| library to be created. \fBSTATIC\fP libraries are archives of object files |
| for use when linking other targets. \fBSHARED\fP libraries are linked |
| dynamically and loaded at runtime. \fBMODULE\fP libraries are plugins that |
| are not linked into other targets but may be loaded dynamically at runtime |
| using dlopen\-like functionality. If no type is given explicitly the |
| type is \fBSTATIC\fP or \fBSHARED\fP based on whether the current value of the |
| variable \fBBUILD_SHARED_LIBS\fP is \fBON\fP\&. For \fBSHARED\fP and |
| \fBMODULE\fP libraries the \fBPOSITION_INDEPENDENT_CODE\fP target |
| property is set to \fBON\fP automatically. |
| A \fBSHARED\fP library may be marked with the \fBFRAMEWORK\fP |
| target property to create an macOS Framework. |
| .sp |
| New in version 3.8: A \fBSTATIC\fP library may be marked with the \fBFRAMEWORK\fP |
| target property to create a static Framework. |
| |
| .sp |
| If a library does not export any symbols, it must not be declared as a |
| \fBSHARED\fP library. For example, a Windows resource DLL or a managed C++/CLI |
| DLL that exports no unmanaged symbols would need to be a \fBMODULE\fP library. |
| This is because CMake expects a \fBSHARED\fP library to always have an |
| associated import library on Windows. |
| .sp |
| By default the library file will be created in the build tree directory |
| corresponding to the source tree directory in which the command was |
| invoked. See documentation of the \fBARCHIVE_OUTPUT_DIRECTORY\fP, |
| \fBLIBRARY_OUTPUT_DIRECTORY\fP, and |
| \fBRUNTIME_OUTPUT_DIRECTORY\fP target properties to change this |
| location. See documentation of the \fBOUTPUT_NAME\fP target |
| property to change the \fB<name>\fP part of the final file name. |
| .sp |
| If \fBEXCLUDE_FROM_ALL\fP is given the corresponding property will be set on |
| the created target. See documentation of the \fBEXCLUDE_FROM_ALL\fP |
| target property for details. |
| .sp |
| See the \fBcmake\-buildsystem(7)\fP manual for more on defining |
| buildsystem properties. |
| .sp |
| See also \fBHEADER_FILE_ONLY\fP on what to do if some sources are |
| pre\-processed, and you want to have the original sources reachable from |
| within IDE. |
| .SS Object Libraries |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(<name> OBJECT [<source>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Creates an Object Library\&. An object library |
| compiles source files but does not archive or link their object files into a |
| library. Instead other targets created by \fI\%add_library()\fP or |
| \fBadd_executable()\fP may reference the objects using an expression of the |
| form \fB$<TARGET_OBJECTS:objlib>\fP as a source, where \fBobjlib\fP is the |
| object library name. For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(... $<TARGET_OBJECTS:objlib> ...) |
| add_executable(... $<TARGET_OBJECTS:objlib> ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will include objlib\(aqs object files in a library and an executable |
| along with those compiled from their own sources. Object libraries |
| may contain only sources that compile, header files, and other files |
| that would not affect linking of a normal library (e.g. \fB\&.txt\fP). |
| They may contain custom commands generating such sources, but not |
| \fBPRE_BUILD\fP, \fBPRE_LINK\fP, or \fBPOST_BUILD\fP commands. Some native build |
| systems (such as Xcode) may not like targets that have only object files, so |
| consider adding at least one real source file to any target that references |
| \fB$<TARGET_OBJECTS:objlib>\fP\&. |
| .sp |
| New in version 3.12: Object libraries can be linked to with \fBtarget_link_libraries()\fP\&. |
| |
| .SS Interface Libraries |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(<name> INTERFACE) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Creates an Interface Library\&. |
| An \fBINTERFACE\fP library target does not compile sources and does |
| not produce a library artifact on disk. However, it may have |
| properties set on it and it may be installed and exported. |
| Typically, \fBINTERFACE_*\fP properties are populated on an interface |
| target using the commands: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBset_property()\fP, |
| .IP \(bu 2 |
| \fBtarget_link_libraries(INTERFACE)\fP, |
| .IP \(bu 2 |
| \fBtarget_link_options(INTERFACE)\fP, |
| .IP \(bu 2 |
| \fBtarget_include_directories(INTERFACE)\fP, |
| .IP \(bu 2 |
| \fBtarget_compile_options(INTERFACE)\fP, |
| .IP \(bu 2 |
| \fBtarget_compile_definitions(INTERFACE)\fP, and |
| .IP \(bu 2 |
| \fBtarget_sources(INTERFACE)\fP, |
| .UNINDENT |
| .sp |
| and then it is used as an argument to \fBtarget_link_libraries()\fP |
| like any other target. |
| .sp |
| An interface library created with the above signature has no source files |
| itself and is not included as a target in the generated buildsystem. |
| .sp |
| New in version 3.15: An interface library can have \fBPUBLIC_HEADER\fP and |
| \fBPRIVATE_HEADER\fP properties. The headers specified by those |
| properties can be installed using the \fBinstall(TARGETS)\fP command. |
| |
| .sp |
| New in version 3.19: An interface library target may be created with source files: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Source files may be listed directly in the \fBadd_library\fP call or added |
| later by calls to \fBtarget_sources()\fP with the \fBPRIVATE\fP or |
| \fBPUBLIC\fP keywords. |
| .sp |
| If an interface library has source files (i.e. the \fBSOURCES\fP |
| target property is set), it will appear in the generated buildsystem |
| as a build target much like a target defined by the |
| \fBadd_custom_target()\fP command. It does not compile any sources, |
| but does contain build rules for custom commands created by the |
| \fBadd_custom_command()\fP command. |
| |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| In most command signatures where the \fBINTERFACE\fP keyword appears, |
| the items listed after it only become part of that target\(aqs usage |
| requirements and are not part of the target\(aqs own settings. However, |
| in this signature of \fBadd_library\fP, the \fBINTERFACE\fP keyword refers |
| to the library type only. Sources listed after it in the \fBadd_library\fP |
| call are \fBPRIVATE\fP to the interface library and do not appear in its |
| \fBINTERFACE_SOURCES\fP target property. |
| .UNINDENT |
| .UNINDENT |
| .SS Imported Libraries |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(<name> <type> IMPORTED [GLOBAL]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Creates an IMPORTED library target called \fB<name>\fP\&. |
| No rules are generated to build it, and the \fBIMPORTED\fP target |
| property is \fBTrue\fP\&. The target name has scope in the directory in which |
| it is created and below, but the \fBGLOBAL\fP option extends visibility. |
| It may be referenced like any target built within the project. |
| \fBIMPORTED\fP libraries are useful for convenient reference from commands |
| like \fBtarget_link_libraries()\fP\&. Details about the imported library |
| are specified by setting properties whose names begin in \fBIMPORTED_\fP and |
| \fBINTERFACE_\fP\&. |
| .sp |
| The \fB<type>\fP must be one of: |
| .INDENT 0.0 |
| .TP |
| .B \fBSTATIC\fP, \fBSHARED\fP, \fBMODULE\fP, \fBUNKNOWN\fP |
| References a library file located outside the project. The |
| \fBIMPORTED_LOCATION\fP target property (or its per\-configuration |
| variant \fBIMPORTED_LOCATION_<CONFIG>\fP) specifies the |
| location of the main library file on disk: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| For a \fBSHARED\fP library on most non\-Windows platforms, the main library |
| file is the \fB\&.so\fP or \fB\&.dylib\fP file used by both linkers and dynamic |
| loaders. If the referenced library file has a \fBSONAME\fP (or on macOS, |
| has a \fBLC_ID_DYLIB\fP starting in \fB@rpath/\fP), the value of that field |
| should be set in the \fBIMPORTED_SONAME\fP target property. |
| If the referenced library file does not have a \fBSONAME\fP, but the |
| platform supports it, then the \fBIMPORTED_NO_SONAME\fP target |
| property should be set. |
| .IP \(bu 2 |
| For a \fBSHARED\fP library on Windows, the \fBIMPORTED_IMPLIB\fP |
| target property (or its per\-configuration variant |
| \fBIMPORTED_IMPLIB_<CONFIG>\fP) specifies the location of the |
| DLL import library file (\fB\&.lib\fP or \fB\&.dll.a\fP) on disk, and the |
| \fBIMPORTED_LOCATION\fP is the location of the \fB\&.dll\fP runtime |
| library (and is optional, but needed by the \fBTARGET_RUNTIME_DLLS\fP |
| generator expression). |
| .UNINDENT |
| .sp |
| Additional usage requirements may be specified in \fBINTERFACE_*\fP properties. |
| .sp |
| An \fBUNKNOWN\fP library type is typically only used in the implementation of |
| Find Modules\&. It allows the path to an imported library (often found |
| using the \fBfind_library()\fP command) to be used without having to know |
| what type of library it is. This is especially useful on Windows where a |
| static library and a DLL\(aqs import library both have the same file extension. |
| .TP |
| .B \fBOBJECT\fP |
| References a set of object files located outside the project. |
| The \fBIMPORTED_OBJECTS\fP target property (or its per\-configuration |
| variant \fBIMPORTED_OBJECTS_<CONFIG>\fP) specifies the locations of |
| object files on disk. |
| Additional usage requirements may be specified in \fBINTERFACE_*\fP properties. |
| .TP |
| .B \fBINTERFACE\fP |
| Does not reference any library or object files on disk, but may |
| specify usage requirements in \fBINTERFACE_*\fP properties. |
| .UNINDENT |
| .sp |
| See documentation of the \fBIMPORTED_*\fP and \fBINTERFACE_*\fP properties |
| for more information. |
| .SS Alias Libraries |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(<name> ALIAS <target>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Creates an Alias Target, such that \fB<name>\fP can be |
| used to refer to \fB<target>\fP in subsequent commands. The \fB<name>\fP does |
| not appear in the generated buildsystem as a make target. The \fB<target>\fP |
| may not be an \fBALIAS\fP\&. |
| .sp |
| New in version 3.11: An \fBALIAS\fP can target a \fBGLOBAL\fP Imported Target |
| |
| .sp |
| New in version 3.18: An \fBALIAS\fP can target a non\-\fBGLOBAL\fP Imported Target. Such alias is |
| scoped to the directory in which it is created and below. |
| The \fBALIAS_GLOBAL\fP target property can be used to check if the |
| alias is global or not. |
| |
| .sp |
| \fBALIAS\fP targets can be used as linkable targets and as targets to |
| read properties from. They can also be tested for existence with the |
| regular \fBif(TARGET)\fP subcommand. The \fB<name>\fP may not be used |
| to modify properties of \fB<target>\fP, that is, it may not be used as the |
| operand of \fBset_property()\fP, \fBset_target_properties()\fP, |
| \fBtarget_link_libraries()\fP etc. An \fBALIAS\fP target may not be |
| installed or exported. |
| .SS add_link_options |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Add options to the link step for executable, shared library or module |
| library targets in the current directory and below that are added after |
| this command is invoked. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_link_options(<option> ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This command can be used to add any link options, but alternative commands |
| exist to add libraries (\fBtarget_link_libraries()\fP or |
| \fBlink_libraries()\fP). See documentation of the |
| \fBdirectory\fP and |
| \fBtarget\fP \fBLINK_OPTIONS\fP properties. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This command cannot be used to add options for static library targets, |
| since they do not use a linker. To add archiver or MSVC librarian flags, |
| see the \fBSTATIC_LIBRARY_OPTIONS\fP target property. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Arguments to \fBadd_link_options\fP may use "generator expressions" with |
| the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .SS Host And Device Specific Link Options |
| .sp |
| New in version 3.18: When a device link step is involved, which is controlled by |
| \fBCUDA_SEPARABLE_COMPILATION\fP and |
| \fBCUDA_RESOLVE_DEVICE_SYMBOLS\fP properties and policy \fBCMP0105\fP, |
| the raw options will be delivered to the host and device link steps (wrapped in |
| \fB\-Xcompiler\fP or equivalent for device link). Options wrapped with |
| \fB$<DEVICE_LINK:...>\fP |
| \fBgenerator expression\fP will be used |
| only for the device link step. Options wrapped with \fB$<HOST_LINK:...>\fP |
| \fBgenerator expression\fP will be used |
| only for the host link step. |
| |
| .SS Option De\-duplication |
| .sp |
| The final set of options used for a target is constructed by |
| accumulating options from the current target and the usage requirements of |
| its dependencies. The set of options is de\-duplicated to avoid repetition. |
| .sp |
| New in version 3.12: While beneficial for individual options, the de\-duplication step can break |
| up option groups. For example, \fB\-option A \-option B\fP becomes |
| \fB\-option A B\fP\&. One may specify a group of options using shell\-like |
| quoting along with a \fBSHELL:\fP prefix. The \fBSHELL:\fP prefix is dropped, |
| and the rest of the option string is parsed using the |
| \fBseparate_arguments()\fP \fBUNIX_COMMAND\fP mode. For example, |
| \fB"SHELL:\-option A" "SHELL:\-option B"\fP becomes \fB\-option A \-option B\fP\&. |
| |
| .SS Handling Compiler Driver Differences |
| .sp |
| To pass options to the linker tool, each compiler driver has its own syntax. |
| The \fBLINKER:\fP prefix and \fB,\fP separator can be used to specify, in a portable |
| way, options to pass to the linker tool. \fBLINKER:\fP is replaced by the |
| appropriate driver option and \fB,\fP by the appropriate driver separator. |
| The driver prefix and driver separator are given by the values of the |
| \fBCMAKE_<LANG>_LINKER_WRAPPER_FLAG\fP and |
| \fBCMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP\fP variables. |
| .sp |
| For example, \fB"LINKER:\-z,defs"\fP becomes \fB\-Xlinker \-z \-Xlinker defs\fP for |
| \fBClang\fP and \fB\-Wl,\-z,defs\fP for \fBGNU GCC\fP\&. |
| .sp |
| The \fBLINKER:\fP prefix can be specified as part of a \fBSHELL:\fP prefix |
| expression. |
| .sp |
| The \fBLINKER:\fP prefix supports, as an alternative syntax, specification of |
| arguments using the \fBSHELL:\fP prefix and space as separator. The previous |
| example then becomes \fB"LINKER:SHELL:\-z defs"\fP\&. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Specifying the \fBSHELL:\fP prefix anywhere other than at the beginning of the |
| \fBLINKER:\fP prefix is not supported. |
| .UNINDENT |
| .UNINDENT |
| .SS add_subdirectory |
| .sp |
| Add a subdirectory to the build. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Adds a subdirectory to the build. The source_dir specifies the |
| directory in which the source CMakeLists.txt and code files are |
| located. If it is a relative path it will be evaluated with respect |
| to the current directory (the typical usage), but it may also be an |
| absolute path. The \fBbinary_dir\fP specifies the directory in which to |
| place the output files. If it is a relative path it will be evaluated |
| with respect to the current output directory, but it may also be an |
| absolute path. If \fBbinary_dir\fP is not specified, the value of |
| \fBsource_dir\fP, before expanding any relative path, will be used (the |
| typical usage). The CMakeLists.txt file in the specified source |
| directory will be processed immediately by CMake before processing in |
| the current input file continues beyond this command. |
| .sp |
| If the \fBEXCLUDE_FROM_ALL\fP argument is provided then targets in the |
| subdirectory will not be included in the \fBALL\fP target of the parent |
| directory by default, and will be excluded from IDE project files. |
| Users must explicitly build targets in the subdirectory. This is |
| meant for use when the subdirectory contains a separate part of the |
| project that is useful but not necessary, such as a set of examples. |
| Typically the subdirectory should contain its own \fBproject()\fP |
| command invocation so that a full build system will be generated in the |
| subdirectory (such as a VS IDE solution file). Note that inter\-target |
| dependencies supersede this exclusion. If a target built by the |
| parent project depends on a target in the subdirectory, the dependee |
| target will be included in the parent project build system to satisfy |
| the dependency. |
| .SS add_test |
| .sp |
| Add a test to the project to be run by \fBctest(1)\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_test(NAME <name> COMMAND <command> [<arg>...] |
| [CONFIGURATIONS <config>...] |
| [WORKING_DIRECTORY <dir>] |
| [COMMAND_EXPAND_LISTS]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Adds a test called \fB<name>\fP\&. The test name may contain arbitrary |
| characters, expressed as a Quoted Argument or Bracket Argument |
| if necessary. See policy \fBCMP0110\fP\&. The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBCOMMAND\fP |
| Specify the test command\-line. If \fB<command>\fP specifies an |
| executable target (created by \fBadd_executable()\fP) it will |
| automatically be replaced by the location of the executable created |
| at build time. |
| .sp |
| The command may be specified using |
| \fBgenerator expressions\fP\&. |
| .TP |
| .B \fBCONFIGURATIONS\fP |
| Restrict execution of the test only to the named configurations. |
| .TP |
| .B \fBWORKING_DIRECTORY\fP |
| Set the \fBWORKING_DIRECTORY\fP test property to |
| specify the working directory in which to execute the test. |
| If not specified the test will be run with the current working |
| directory set to the build directory corresponding to the |
| current source directory. |
| .sp |
| The working directory may be specified using |
| \fBgenerator expressions\fP\&. |
| .TP |
| .B \fBCOMMAND_EXPAND_LISTS\fP |
| New in version 3.16. |
| |
| .sp |
| Lists in \fBCOMMAND\fP arguments will be expanded, including those |
| created with |
| \fBgenerator expressions\fP\&. |
| .UNINDENT |
| .sp |
| The given test command is expected to exit with code \fB0\fP to pass and |
| non\-zero to fail, or vice\-versa if the \fBWILL_FAIL\fP test |
| property is set. Any output written to stdout or stderr will be |
| captured by \fBctest(1)\fP but does not affect the pass/fail status |
| unless the \fBPASS_REGULAR_EXPRESSION\fP, |
| \fBFAIL_REGULAR_EXPRESSION\fP or |
| \fBSKIP_REGULAR_EXPRESSION\fP test property is used. |
| .sp |
| New in version 3.16: Added \fBSKIP_REGULAR_EXPRESSION\fP property. |
| |
| .sp |
| Tests added with the \fBadd_test(NAME)\fP signature support using |
| \fBgenerator expressions\fP |
| in test properties set by \fBset_property(TEST)\fP or |
| \fBset_tests_properties()\fP\&. |
| .sp |
| Example usage: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_test(NAME mytest |
| COMMAND testDriver \-\-config $<CONFIG> |
| \-\-exe $<TARGET_FILE:myexe>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This creates a test \fBmytest\fP whose command runs a \fBtestDriver\fP tool |
| passing the configuration name and the full path to the executable |
| file produced by target \fBmyexe\fP\&. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| CMake will generate tests only if the \fBenable_testing()\fP |
| command has been invoked. The \fBCTest\fP module invokes the |
| command automatically unless the \fBBUILD_TESTING\fP option is turned |
| \fBOFF\fP\&. |
| .UNINDENT |
| .UNINDENT |
| |
| .sp |
| .ce |
| ---- |
| |
| .ce 0 |
| .sp |
| .sp |
| This command also supports a simpler, but less flexible, signature: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_test(<name> <command> [<arg>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Add a test called \fB<name>\fP with the given command\-line. |
| .sp |
| Unlike the above \fBNAME\fP signature, target names are not supported |
| in the command\-line. Furthermore, tests added with this signature do not |
| support \fBgenerator expressions\fP |
| in the command\-line or test properties. |
| .SS aux_source_directory |
| .sp |
| Find all source files in a directory. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| aux_source_directory(<dir> <variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Collects the names of all the source files in the specified directory |
| and stores the list in the \fB<variable>\fP provided. This command is |
| intended to be used by projects that use explicit template |
| instantiation. Template instantiation files can be stored in a |
| \fBTemplates\fP subdirectory and collected automatically using this |
| command to avoid manually listing all instantiations. |
| .sp |
| It is tempting to use this command to avoid writing the list of source |
| files for a library or executable target. While this seems to work, |
| there is no way for CMake to generate a build system that knows when a |
| new source file has been added. Normally the generated build system |
| knows when it needs to rerun CMake because the \fBCMakeLists.txt\fP file is |
| modified to add a new source. When the source is just added to the |
| directory without modifying this file, one would have to manually |
| rerun CMake to generate a build system incorporating the new file. |
| .SS build_command |
| .sp |
| Get a command line to build the current project. |
| This is mainly intended for internal use by the \fBCTest\fP module. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| build_command(<variable> |
| [CONFIGURATION <config>] |
| [PARALLEL_LEVEL <parallel>] |
| [TARGET <target>] |
| [PROJECT_NAME <projname>] # legacy, causes warning |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets the given \fB<variable>\fP to a command\-line string of the form: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| <cmake> \-\-build . [\-\-config <config>] [\-\-parallel <parallel>] [\-\-target <target>...] [\-\- \-i] |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| where \fB<cmake>\fP is the location of the \fBcmake(1)\fP command\-line |
| tool, and \fB<config>\fP, \fB<parallel>\fP and \fB<target>\fP are the values |
| provided to the \fBCONFIGURATION\fP, \fBPARALLEL_LEVEL\fP and \fBTARGET\fP |
| options, if any. The trailing \fB\-\- \-i\fP option is added for |
| Makefile Generators if policy \fBCMP0061\fP is not set to |
| \fBNEW\fP\&. |
| .sp |
| When invoked, this \fBcmake \-\-build\fP command line will launch the |
| underlying build system tool. |
| .sp |
| New in version 3.21: The \fBPARALLEL_LEVEL\fP argument can be used to set the \fB\-\-parallel\fP |
| flag. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| build_command(<cachevariable> <makecommand>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This second signature is deprecated, but still available for backwards |
| compatibility. Use the first signature instead. |
| .sp |
| It sets the given \fB<cachevariable>\fP to a command\-line string as |
| above but without the \fB\-\-target\fP option. |
| The \fB<makecommand>\fP is ignored but should be the full path to |
| devenv, nmake, make or one of the end user build tools |
| for legacy invocations. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| In CMake versions prior to 3.0 this command returned a command |
| line that directly invokes the native build tool for the current |
| generator. Their implementation of the \fBPROJECT_NAME\fP option |
| had no useful effects, so CMake now warns on use of the option. |
| .UNINDENT |
| .UNINDENT |
| .SS create_test_sourcelist |
| .sp |
| Create a test driver and source list for building test programs. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| create_test_sourcelist(sourceListName driverName |
| test1 test2 test3 |
| EXTRA_INCLUDE include.h |
| FUNCTION function) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| A test driver is a program that links together many small tests into a |
| single executable. This is useful when building static executables |
| with large libraries to shrink the total required size. The list of |
| source files needed to build the test driver will be in |
| \fBsourceListName\fP\&. \fBdriverName\fP is the name of the test driver program. |
| The rest of the arguments consist of a list of test source files, can |
| be semicolon separated. Each test source file should have a function |
| in it that is the same name as the file with no extension (foo.cxx |
| should have int foo(int, char*[]);) \fBdriverName\fP will be able to call |
| each of the tests by name on the command line. If \fBEXTRA_INCLUDE\fP is |
| specified, then the next argument is included into the generated file. |
| If \fBFUNCTION\fP is specified, then the next argument is taken as a |
| function name that is passed a pointer to ac and av. This can be used |
| to add extra command line processing to each test. The |
| \fBCMAKE_TESTDRIVER_BEFORE_TESTMAIN\fP cmake variable can be set to |
| have code that will be placed directly before calling the test main function. |
| \fBCMAKE_TESTDRIVER_AFTER_TESTMAIN\fP can be set to have code that |
| will be placed directly after the call to the test main function. |
| .SS define_property |
| .sp |
| Define and document custom properties. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE | |
| TEST | VARIABLE | CACHED_VARIABLE> |
| PROPERTY <name> [INHERITED] |
| [BRIEF_DOCS <brief\-doc> [docs...]] |
| [FULL_DOCS <full\-doc> [docs...]] |
| [INITIALIZE_FROM_VARIABLE <variable>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Defines one property in a scope for use with the \fBset_property()\fP and |
| \fBget_property()\fP commands. It is mainly useful for defining the way |
| a property is initialized or inherited. Historically, the command also |
| associated documentation with a property, but that is no longer considered a |
| primary use case. |
| .sp |
| The first argument determines the kind of scope in which the property should |
| be used. It must be one of the following: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| GLOBAL = associated with the global namespace |
| DIRECTORY = associated with one directory |
| TARGET = associated with one target |
| SOURCE = associated with one source file |
| TEST = associated with a test named with add_test |
| VARIABLE = documents a CMake language variable |
| CACHED_VARIABLE = documents a CMake cache variable |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Note that unlike \fBset_property()\fP and \fBget_property()\fP no |
| actual scope needs to be given; only the kind of scope is important. |
| .sp |
| The required \fBPROPERTY\fP option is immediately followed by the name of |
| the property being defined. |
| .sp |
| If the \fBINHERITED\fP option is given, then the \fBget_property()\fP command |
| will chain up to the next higher scope when the requested property is not set |
| in the scope given to the command. |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBDIRECTORY\fP scope chains to its parent directory\(aqs scope, continuing the |
| walk up parent directories until a directory has the property set or there |
| are no more parents. If still not found at the top level directory, it |
| chains to the \fBGLOBAL\fP scope. |
| .IP \(bu 2 |
| \fBTARGET\fP, \fBSOURCE\fP and \fBTEST\fP properties chain to \fBDIRECTORY\fP scope, |
| including further chaining up the directories, etc. as needed. |
| .UNINDENT |
| .sp |
| Note that this scope chaining behavior only applies to calls to |
| \fBget_property()\fP, \fBget_directory_property()\fP, |
| \fBget_target_property()\fP, \fBget_source_file_property()\fP and |
| \fBget_test_property()\fP\&. There is no inheriting behavior when \fIsetting\fP |
| properties, so using \fBAPPEND\fP or \fBAPPEND_STRING\fP with the |
| \fBset_property()\fP command will not consider inherited values when working |
| out the contents to append to. |
| .sp |
| The \fBBRIEF_DOCS\fP and \fBFULL_DOCS\fP options are followed by strings to be |
| associated with the property as its brief and full documentation. |
| CMake does not use this documentation other than making it available to the |
| project via corresponding options to the \fBget_property()\fP command. |
| .sp |
| Changed in version 3.23: The \fBBRIEF_DOCS\fP and \fBFULL_DOCS\fP options are optional. |
| |
| .sp |
| New in version 3.23: The \fBINITIALIZE_FROM_VARIABLE\fP option specifies a variable from which the |
| property should be initialized. It can only be used with target properties. |
| The \fB<variable>\fP name must end with the property name and must not begin |
| with \fBCMAKE_\fP or \fB_CMAKE_\fP\&. The property name must contain at least one |
| underscore. It is recommended that the property name have a prefix specific |
| to the project. |
| |
| .SS enable_language |
| .sp |
| Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| enable_language(<lang> [OPTIONAL] ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Enables support for the named language in CMake. This is |
| the same as the \fBproject()\fP command but does not create any of the extra |
| variables that are created by the project command. Example languages |
| are \fBCXX\fP, \fBC\fP, \fBCUDA\fP, \fBOBJC\fP, \fBOBJCXX\fP, \fBFortran\fP, |
| \fBHIP\fP, \fBISPC\fP, and \fBASM\fP\&. |
| .sp |
| New in version 3.8: Added \fBCUDA\fP support. |
| |
| .sp |
| New in version 3.16: Added \fBOBJC\fP and \fBOBJCXX\fP support. |
| |
| .sp |
| New in version 3.18: Added \fBISPC\fP support. |
| |
| .sp |
| New in version 3.21: Added \fBHIP\fP support. |
| |
| .sp |
| If enabling \fBASM\fP, enable it last so that CMake can check whether |
| compilers for other languages like \fBC\fP work for assembly too. |
| .sp |
| This command must be called in file scope, not in a function call. |
| Furthermore, it must be called in the highest directory common to all |
| targets using the named language directly for compiling sources or |
| indirectly through link dependencies. It is simplest to enable all |
| needed languages in the top\-level directory of a project. |
| .sp |
| The \fBOPTIONAL\fP keyword is a placeholder for future implementation and |
| does not currently work. Instead you can use the \fBCheckLanguage\fP |
| module to verify support before enabling. |
| .SS enable_testing |
| .sp |
| Enable testing for current directory and below. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| enable_testing() |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Enables testing for this directory and below. |
| .sp |
| This command should be in the source directory root |
| because ctest expects to find a test file in the build |
| directory root. |
| .sp |
| This command is automatically invoked when the \fBCTest\fP |
| module is included, except if the \fBBUILD_TESTING\fP option is |
| turned off. |
| .sp |
| See also the \fBadd_test()\fP command. |
| .SS export |
| .sp |
| Export targets or packages for outside projects to use them directly |
| from the current project\(aqs build tree, without installation. |
| .sp |
| See the \fBinstall(EXPORT)\fP command to export targets from an |
| install tree. |
| .SS Synopsis |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| export(\fI\%TARGETS\fP <target>... [...]) |
| export(\fI\%EXPORT\fP <export\-name> [...]) |
| export(\fI\%PACKAGE\fP <PackageName>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Exporting Targets |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| export(TARGETS <target>... [NAMESPACE <namespace>] |
| [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Creates a file \fB<filename>\fP that may be included by outside projects to |
| import targets named by \fB<target>...\fP from the current project\(aqs build tree. |
| This is useful during cross\-compiling to build utility executables that can |
| run on the host platform in one project and then import them into another |
| project being compiled for the target platform. |
| .sp |
| The file created by this command is specific to the build tree and |
| should never be installed. See the \fBinstall(EXPORT)\fP command to |
| export targets from an install tree. |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBNAMESPACE <namespace>\fP |
| Prepend the \fB<namespace>\fP string to all target names written to the file. |
| .TP |
| .B \fBAPPEND\fP |
| Append to the file instead of overwriting it. This can be used to |
| incrementally export multiple targets to the same file. |
| .TP |
| .B \fBEXPORT_LINK_INTERFACE_LIBRARIES\fP |
| Include the contents of the properties named with the pattern |
| \fB(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?\fP |
| in the export, even when policy \fBCMP0022\fP is NEW. This is useful |
| to support consumers using CMake versions older than 2.8.12. |
| .UNINDENT |
| .sp |
| This signature requires all targets to be listed explicitly. If a library |
| target is included in the export, but a target to which it links is not |
| included, the behavior is unspecified. See the \fI\%export(EXPORT)\fP signature |
| to automatically export the same targets from the build tree as |
| \fBinstall(EXPORT)\fP would from an install tree. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Object Libraries under \fBXcode\fP have special handling if |
| multiple architectures are listed in \fBCMAKE_OSX_ARCHITECTURES\fP\&. |
| In this case they will be exported as Interface Libraries with |
| no object files available to clients. This is sufficient to satisfy |
| transitive usage requirements of other targets that link to the |
| object libraries in their implementation. |
| .UNINDENT |
| .UNINDENT |
| .SS Exporting Targets to Android.mk |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| export(TARGETS <target>... ANDROID_MK <filename>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.7. |
| |
| .sp |
| This signature exports cmake built targets to the android ndk build system |
| by creating an \fBAndroid.mk\fP file that references the prebuilt targets. The |
| Android NDK supports the use of prebuilt libraries, both static and shared. |
| This allows cmake to build the libraries of a project and make them available |
| to an ndk build system complete with transitive dependencies, include flags |
| and defines required to use the libraries. The signature takes a list of |
| targets and puts them in the \fBAndroid.mk\fP file specified by the |
| \fB<filename>\fP given. This signature can only be used if policy |
| \fBCMP0022\fP is NEW for all targets given. A error will be issued if |
| that policy is set to OLD for one of the targets. |
| .SS Exporting Targets matching install(EXPORT) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| export(EXPORT <export\-name> [NAMESPACE <namespace>] [FILE <filename>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Creates a file \fB<filename>\fP that may be included by outside projects to |
| import targets from the current project\(aqs build tree. This is the same |
| as the \fI\%export(TARGETS)\fP signature, except that the targets are not |
| explicitly listed. Instead, it exports the targets associated with |
| the installation export \fB<export\-name>\fP\&. Target installations may be |
| associated with the export \fB<export\-name>\fP using the \fBEXPORT\fP option |
| of the \fBinstall(TARGETS)\fP command. |
| .SS Exporting Packages |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| export(PACKAGE <PackageName>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Store the current build directory in the CMake user package registry |
| for package \fB<PackageName>\fP\&. The \fBfind_package()\fP command may consider the |
| directory while searching for package \fB<PackageName>\fP\&. This helps dependent |
| projects find and use a package from the current project\(aqs build tree |
| without help from the user. Note that the entry in the package |
| registry that this command creates works only in conjunction with a |
| package configuration file (\fB<PackageName>Config.cmake\fP) that works with the |
| build tree. In some cases, for example for packaging and for system |
| wide installations, it is not desirable to write the user package |
| registry. |
| .sp |
| Changed in version 3.1: If the \fBCMAKE_EXPORT_NO_PACKAGE_REGISTRY\fP variable |
| is enabled, the \fBexport(PACKAGE)\fP command will do nothing. |
| |
| .sp |
| Changed in version 3.15: By default the \fBexport(PACKAGE)\fP command does nothing (see policy |
| \fBCMP0090\fP) because populating the user package registry has effects |
| outside the source and build trees. Set the |
| \fBCMAKE_EXPORT_PACKAGE_REGISTRY\fP variable to add build directories |
| to the CMake user package registry. |
| |
| .SS fltk_wrap_ui |
| .sp |
| Create FLTK user interfaces Wrappers. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| fltk_wrap_ui(resultingLibraryName source1 |
| source2 ... sourceN ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Produce .h and .cxx files for all the .fl and .fld files listed. The |
| resulting .h and .cxx files will be added to a variable named |
| \fBresultingLibraryName_FLTK_UI_SRCS\fP which should be added to your |
| library. |
| .SS get_source_file_property |
| .sp |
| Get a property for a source file. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_source_file_property(<variable> <file> |
| [DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
| <property>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Gets a property from a source file. The value of the property is |
| stored in the specified \fB<variable>\fP\&. If the source property is not found, |
| the behavior depends on whether it has been defined to be an \fBINHERITED\fP |
| property or not (see \fBdefine_property()\fP). Non\-inherited properties |
| will set \fBvariable\fP to \fBNOTFOUND\fP, whereas inherited properties will search |
| the relevant parent scope as described for the \fBdefine_property()\fP |
| command and if still unable to find the property, \fBvariable\fP will be set to |
| an empty string. |
| .sp |
| By default, the source file\(aqs property will be read from the current source |
| directory\(aqs scope. |
| .sp |
| New in version 3.18: Directory scope can be overridden with one of the following sub\-options: |
| .INDENT 0.0 |
| .TP |
| .B \fBDIRECTORY <dir>\fP |
| The source file property will be read from the \fB<dir>\fP directory\(aqs |
| scope. CMake must already know about that source directory, either by |
| having added it through a call to \fBadd_subdirectory()\fP or \fB<dir>\fP |
| being the top level source directory. Relative paths are treated as |
| relative to the current source directory. |
| .TP |
| .B \fBTARGET_DIRECTORY <target>\fP |
| The source file property will be read from the directory scope in which |
| \fB<target>\fP was created (\fB<target>\fP must therefore already exist). |
| .UNINDENT |
| |
| .sp |
| Use \fBset_source_files_properties()\fP to set property values. Source |
| file properties usually control how the file is built. One property that is |
| always there is \fBLOCATION\fP\&. |
| .sp |
| See also the more general \fBget_property()\fP command. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The \fBGENERATED\fP source file property may be globally visible. |
| See its documentation for details. |
| .UNINDENT |
| .UNINDENT |
| .SS get_target_property |
| .sp |
| Get a property from a target. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_target_property(<VAR> target property) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Get a property from a target. The value of the property is stored in |
| the variable \fB<VAR>\fP\&. If the target property is not found, the behavior |
| depends on whether it has been defined to be an \fBINHERITED\fP property |
| or not (see \fBdefine_property()\fP). Non\-inherited properties will |
| set \fB<VAR>\fP to \fB<VAR>\-NOTFOUND\fP, whereas inherited properties will search |
| the relevant parent scope as described for the \fBdefine_property()\fP |
| command and if still unable to find the property, \fB<VAR>\fP will be set to |
| an empty string. |
| .sp |
| Use \fBset_target_properties()\fP to set target property values. |
| Properties are usually used to control how a target is built, but some |
| query the target instead. This command can get properties for any |
| target so far created. The targets do not need to be in the current |
| \fBCMakeLists.txt\fP file. |
| .sp |
| See also the more general \fBget_property()\fP command. |
| .sp |
| See Target Properties for the list of properties known to CMake. |
| .SS get_test_property |
| .sp |
| Get a property of the test. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_test_property(test property VAR) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Get a property from the test. The value of the property is stored in |
| the variable \fBVAR\fP\&. If the test property is not found, the behavior |
| depends on whether it has been defined to be an \fBINHERITED\fP property |
| or not (see \fBdefine_property()\fP). Non\-inherited properties will |
| set \fBVAR\fP to "NOTFOUND", whereas inherited properties will search the |
| relevant parent scope as described for the \fBdefine_property()\fP |
| command and if still unable to find the property, \fBVAR\fP will be set to |
| an empty string. |
| .sp |
| For a list of standard properties you can type \fBcmake \-\-help\-property\-list\fP\&. |
| .sp |
| See also the more general \fBget_property()\fP command. |
| .SS include_directories |
| .sp |
| Add include directories to the build. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Add the given directories to those the compiler uses to search for |
| include files. Relative paths are interpreted as relative to the |
| current source directory. |
| .sp |
| The include directories are added to the \fBINCLUDE_DIRECTORIES\fP |
| directory property for the current \fBCMakeLists\fP file. They are also |
| added to the \fBINCLUDE_DIRECTORIES\fP target property for each |
| target in the current \fBCMakeLists\fP file. The target property values |
| are the ones used by the generators. |
| .sp |
| By default the directories specified are appended onto the current list of |
| directories. This default behavior can be changed by setting |
| \fBCMAKE_INCLUDE_DIRECTORIES_BEFORE\fP to \fBON\fP\&. By using |
| \fBAFTER\fP or \fBBEFORE\fP explicitly, you can select between appending and |
| prepending, independent of the default. |
| .sp |
| If the \fBSYSTEM\fP option is given, the compiler will be told the |
| directories are meant as system include directories on some platforms. |
| Signalling this setting might achieve effects such as the compiler |
| skipping warnings, or these fixed\-install system files not being |
| considered in dependency calculations \- see compiler docs. |
| .sp |
| Arguments to \fBinclude_directories\fP may use "generator expressions" with |
| the syntax "$<...>". See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Prefer the \fBtarget_include_directories()\fP command to add include |
| directories to individual targets and optionally propagate/export them |
| to dependents. |
| .UNINDENT |
| .UNINDENT |
| .SS include_external_msproject |
| .sp |
| Include an external Microsoft project file in a workspace. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include_external_msproject(projectname location |
| [TYPE projectTypeGUID] |
| [GUID projectGUID] |
| [PLATFORM platformName] |
| dep1 dep2 ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Includes an external Microsoft project in the generated workspace |
| file. Currently does nothing on UNIX. This will create a target |
| named \fB[projectname]\fP\&. This can be used in the \fBadd_dependencies()\fP |
| command to make things depend on the external project. |
| .sp |
| \fBTYPE\fP, \fBGUID\fP and \fBPLATFORM\fP are optional parameters that allow one to |
| specify the type of project, id (\fBGUID\fP) of the project and the name of |
| the target platform. This is useful for projects requiring values |
| other than the default (e.g. WIX projects). |
| .sp |
| New in version 3.9: If the imported project has different configuration names than the |
| current project, set the \fBMAP_IMPORTED_CONFIG_<CONFIG>\fP |
| target property to specify the mapping. |
| |
| .SS include_regular_expression |
| .sp |
| Set the regular expression used for dependency checking. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include_regular_expression(regex_match [regex_complain]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets the regular expressions used in dependency checking. Only files |
| matching \fBregex_match\fP will be traced as dependencies. Only files |
| matching \fBregex_complain\fP will generate warnings if they cannot be found |
| (standard header paths are not searched). The defaults are: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| regex_match = "^.*$" (match everything) |
| regex_complain = "^$" (match empty string only) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS install |
| .sp |
| Specify rules to run at install time. |
| .SS Synopsis |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install(\fI\%TARGETS\fP <target>... [...]) |
| install(\fI\%IMPORTED_RUNTIME_ARTIFACTS\fP <target>... [...]) |
| install({\fI\%FILES\fP | \fI\%PROGRAMS\fP} <file>... [...]) |
| install(\fI\%DIRECTORY\fP <dir>... [...]) |
| install(\fI\%SCRIPT\fP <file> [...]) |
| install(\fI\%CODE\fP <code> [...]) |
| install(\fI\%EXPORT\fP <export\-name> [...]) |
| install(\fI\%RUNTIME_DEPENDENCY_SET\fP <set\-name> [...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Introduction |
| .sp |
| This command generates installation rules for a project. Install rules |
| specified by calls to the \fBinstall()\fP command within a source directory |
| are executed in order during installation. |
| .sp |
| Changed in version 3.14: Install rules in subdirectories |
| added by calls to the \fBadd_subdirectory()\fP command are interleaved |
| with those in the parent directory to run in the order declared (see |
| policy \fBCMP0082\fP). |
| |
| .sp |
| Changed in version 3.22: The environment variable \fBCMAKE_INSTALL_MODE\fP can override the |
| default copying behavior of \fI\%install()\fP\&. |
| |
| .sp |
| There are multiple signatures for this command. Some of them define |
| installation options for files and targets. Options common to |
| multiple signatures are covered here but they are valid only for |
| signatures that specify them. The common options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBDESTINATION\fP |
| Specify the directory on disk to which a file will be installed. |
| Arguments can be relative or absolute paths. |
| .sp |
| If a relative path is given it is interpreted relative to the value |
| of the \fBCMAKE_INSTALL_PREFIX\fP variable. |
| The prefix can be relocated at install time using the \fBDESTDIR\fP |
| mechanism explained in the \fBCMAKE_INSTALL_PREFIX\fP variable |
| documentation. |
| .sp |
| If an absolute path (with a leading slash or drive letter) is given |
| it is used verbatim. |
| .sp |
| As absolute paths are not supported by \fBcpack\fP installer |
| generators, it is preferable to use relative paths throughout. |
| In particular, there is no need to make paths absolute by prepending |
| \fBCMAKE_INSTALL_PREFIX\fP; this prefix is used by default if |
| the DESTINATION is a relative path. |
| .TP |
| .B \fBPERMISSIONS\fP |
| Specify permissions for installed files. Valid permissions are |
| \fBOWNER_READ\fP, \fBOWNER_WRITE\fP, \fBOWNER_EXECUTE\fP, \fBGROUP_READ\fP, |
| \fBGROUP_WRITE\fP, \fBGROUP_EXECUTE\fP, \fBWORLD_READ\fP, \fBWORLD_WRITE\fP, |
| \fBWORLD_EXECUTE\fP, \fBSETUID\fP, and \fBSETGID\fP\&. Permissions that do |
| not make sense on certain platforms are ignored on those platforms. |
| .TP |
| .B \fBCONFIGURATIONS\fP |
| Specify a list of build configurations for which the install rule |
| applies (Debug, Release, etc.). Note that the values specified for |
| this option only apply to options listed AFTER the \fBCONFIGURATIONS\fP |
| option. For example, to set separate install paths for the Debug and |
| Release configurations, do the following: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install(TARGETS target |
| CONFIGURATIONS Debug |
| RUNTIME DESTINATION Debug/bin) |
| install(TARGETS target |
| CONFIGURATIONS Release |
| RUNTIME DESTINATION Release/bin) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Note that \fBCONFIGURATIONS\fP appears BEFORE \fBRUNTIME DESTINATION\fP\&. |
| .TP |
| .B \fBCOMPONENT\fP |
| Specify an installation component name with which the install rule |
| is associated, such as "runtime" or "development". During |
| component\-specific installation only install rules associated with |
| the given component name will be executed. During a full installation |
| all components are installed unless marked with \fBEXCLUDE_FROM_ALL\fP\&. |
| If \fBCOMPONENT\fP is not provided a default component "Unspecified" is |
| created. The default component name may be controlled with the |
| \fBCMAKE_INSTALL_DEFAULT_COMPONENT_NAME\fP variable. |
| .TP |
| .B \fBEXCLUDE_FROM_ALL\fP |
| New in version 3.6. |
| |
| .sp |
| Specify that the file is excluded from a full installation and only |
| installed as part of a component\-specific installation |
| .TP |
| .B \fBRENAME\fP |
| Specify a name for an installed file that may be different from the |
| original file. Renaming is allowed only when a single file is |
| installed by the command. |
| .TP |
| .B \fBOPTIONAL\fP |
| Specify that it is not an error if the file to be installed does |
| not exist. |
| .UNINDENT |
| .sp |
| New in version 3.1: Command signatures that install files may print messages during |
| installation. Use the \fBCMAKE_INSTALL_MESSAGE\fP variable |
| to control which messages are printed. |
| |
| .sp |
| New in version 3.11: Many of the \fBinstall()\fP variants implicitly create the directories |
| containing the installed files. If |
| \fBCMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS\fP is set, these |
| directories will be created with the permissions specified. Otherwise, |
| they will be created according to the uname rules on Unix\-like platforms. |
| Windows platforms are unaffected. |
| |
| .SS Installing Targets |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install(TARGETS targets... [EXPORT <export\-name>] |
| [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set\-name>] |
| [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE| |
| PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set\-name>] |
| [DESTINATION <dir>] |
| [PERMISSIONS permissions...] |
| [CONFIGURATIONS [Debug|Release|...]] |
| [COMPONENT <component>] |
| [NAMELINK_COMPONENT <component>] |
| [OPTIONAL] [EXCLUDE_FROM_ALL] |
| [NAMELINK_ONLY|NAMELINK_SKIP] |
| ] [...] |
| [INCLUDES DESTINATION [<dir> ...]] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBTARGETS\fP form specifies rules for installing targets from a |
| project. There are several kinds of target Output Artifacts |
| that may be installed: |
| .INDENT 0.0 |
| .TP |
| .B \fBARCHIVE\fP |
| Target artifacts of this kind include: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fIStatic libraries\fP |
| (except on macOS when marked as \fBFRAMEWORK\fP, see below); |
| .IP \(bu 2 |
| \fIDLL import libraries\fP |
| (on all Windows\-based systems including Cygwin; they have extension |
| \fB\&.lib\fP, in contrast to the \fB\&.dll\fP libraries that go to \fBRUNTIME\fP); |
| .IP \(bu 2 |
| On AIX, the \fIlinker import file\fP created for executables with |
| \fBENABLE_EXPORTS\fP enabled. |
| .UNINDENT |
| .TP |
| .B \fBLIBRARY\fP |
| Target artifacts of this kind include: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fIShared libraries\fP, except |
| .INDENT 2.0 |
| .IP \(bu 2 |
| DLLs (these go to \fBRUNTIME\fP, see below), |
| .IP \(bu 2 |
| on macOS when marked as \fBFRAMEWORK\fP (see below). |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBRUNTIME\fP |
| Target artifacts of this kind include: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fIExecutables\fP |
| (except on macOS when marked as \fBMACOSX_BUNDLE\fP, see \fBBUNDLE\fP below); |
| .IP \(bu 2 |
| DLLs (on all Windows\-based systems including Cygwin; note that the |
| accompanying import libraries are of kind \fBARCHIVE\fP). |
| .UNINDENT |
| .TP |
| .B \fBOBJECTS\fP |
| New in version 3.9. |
| |
| .sp |
| Object files associated with \fIobject libraries\fP\&. |
| .TP |
| .B \fBFRAMEWORK\fP |
| Both static and shared libraries marked with the \fBFRAMEWORK\fP |
| property are treated as \fBFRAMEWORK\fP targets on macOS. |
| .TP |
| .B \fBBUNDLE\fP |
| Executables marked with the \fBMACOSX_BUNDLE\fP property are treated as |
| \fBBUNDLE\fP targets on macOS. |
| .TP |
| .B \fBPUBLIC_HEADER\fP |
| Any \fBPUBLIC_HEADER\fP files associated with a library are installed in |
| the destination specified by the \fBPUBLIC_HEADER\fP argument on non\-Apple |
| platforms. Rules defined by this argument are ignored for \fBFRAMEWORK\fP |
| libraries on Apple platforms because the associated files are installed |
| into the appropriate locations inside the framework folder. See |
| \fBPUBLIC_HEADER\fP for details. |
| .TP |
| .B \fBPRIVATE_HEADER\fP |
| Similar to \fBPUBLIC_HEADER\fP, but for \fBPRIVATE_HEADER\fP files. See |
| \fBPRIVATE_HEADER\fP for details. |
| .TP |
| .B \fBRESOURCE\fP |
| Similar to \fBPUBLIC_HEADER\fP and \fBPRIVATE_HEADER\fP, but for |
| \fBRESOURCE\fP files. See \fBRESOURCE\fP for details. |
| .TP |
| .B \fBFILE_SET <set>\fP |
| New in version 3.23. |
| |
| .sp |
| File sets are defined by the \fBtarget_sources(FILE_SET)\fP command. |
| If the file set \fB<set>\fP exists and is \fBPUBLIC\fP or \fBINTERFACE\fP, any |
| files in the set are installed under the destination (see below). |
| The directory structure relative to the file set\(aqs base directories is |
| preserved. For example, a file added to the file set as |
| \fB/blah/include/myproj/here.h\fP with a base directory \fB/blah/include\fP |
| would be installed to \fBmyproj/here.h\fP below the destination. |
| .UNINDENT |
| .sp |
| For each of these arguments given, the arguments following them only apply |
| to the target or file type specified in the argument. If none is given, the |
| installation properties apply to all target types. If only one is given then |
| only targets of that type will be installed (which can be used to install |
| just a DLL or just an import library.) |
| .sp |
| For regular executables, static libraries and shared libraries, the |
| \fBDESTINATION\fP argument is not required. For these target types, when |
| \fBDESTINATION\fP is omitted, a default destination will be taken from the |
| appropriate variable from \fBGNUInstallDirs\fP, or set to a built\-in |
| default value if that variable is not defined. The same is true for file |
| sets, and the public and private headers associated with the installed |
| targets through the \fBPUBLIC_HEADER\fP and \fBPRIVATE_HEADER\fP |
| target properties. A destination must always be provided for module libraries, |
| Apple bundles and frameworks. A destination can be omitted for interface and |
| object libraries, but they are handled differently (see the discussion of this |
| topic toward the end of this section). |
| .sp |
| The following table shows the target types with their associated variables and |
| built\-in defaults that apply when no destination is given: |
| .TS |
| center; |
| |l|l|l|. |
| _ |
| T{ |
| Target Type |
| T} T{ |
| GNUInstallDirs Variable |
| T} T{ |
| Built\-In Default |
| T} |
| _ |
| T{ |
| \fBRUNTIME\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_BINDIR}\fP |
| T} T{ |
| \fBbin\fP |
| T} |
| _ |
| T{ |
| \fBLIBRARY\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_LIBDIR}\fP |
| T} T{ |
| \fBlib\fP |
| T} |
| _ |
| T{ |
| \fBARCHIVE\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_LIBDIR}\fP |
| T} T{ |
| \fBlib\fP |
| T} |
| _ |
| T{ |
| \fBPRIVATE_HEADER\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_INCLUDEDIR}\fP |
| T} T{ |
| \fBinclude\fP |
| T} |
| _ |
| T{ |
| \fBPUBLIC_HEADER\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_INCLUDEDIR}\fP |
| T} T{ |
| \fBinclude\fP |
| T} |
| _ |
| T{ |
| \fBFILE_SET\fP (type \fBHEADERS\fP) |
| T} T{ |
| \fB${CMAKE_INSTALL_INCLUDEDIR}\fP |
| T} T{ |
| \fBinclude\fP |
| T} |
| _ |
| .TE |
| .sp |
| Projects wishing to follow the common practice of installing headers into a |
| project\-specific subdirectory may prefer using file sets with appropriate |
| paths and base directories. Otherwise, they must provide a \fBDESTINATION\fP |
| instead of being able to rely on the above (see next example below). |
| .sp |
| To make packages compliant with distribution filesystem layout policies, if |
| projects must specify a \fBDESTINATION\fP, it is recommended that they use a |
| path that begins with the appropriate \fBGNUInstallDirs\fP variable. |
| This allows package maintainers to control the install destination by setting |
| the appropriate cache variables. The following example shows a static library |
| being installed to the default destination provided by |
| \fBGNUInstallDirs\fP, but with its headers installed to a project\-specific |
| subdirectory without using file sets: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(mylib STATIC ...) |
| set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h) |
| include(GNUInstallDirs) |
| install(TARGETS mylib |
| PUBLIC_HEADER |
| DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In addition to the common options listed above, each target can accept |
| the following additional arguments: |
| .INDENT 0.0 |
| .TP |
| .B \fBNAMELINK_COMPONENT\fP |
| New in version 3.12. |
| |
| .sp |
| On some platforms a versioned shared library has a symbolic link such |
| as: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| lib<name>.so \-> lib<name>.so.1 |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| where \fBlib<name>.so.1\fP is the soname of the library and \fBlib<name>.so\fP |
| is a "namelink" allowing linkers to find the library when given |
| \fB\-l<name>\fP\&. The \fBNAMELINK_COMPONENT\fP option is similar to the |
| \fBCOMPONENT\fP option, but it changes the installation component of a shared |
| library namelink if one is generated. If not specified, this defaults to the |
| value of \fBCOMPONENT\fP\&. It is an error to use this parameter outside of a |
| \fBLIBRARY\fP block. |
| .sp |
| Consider the following example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install(TARGETS mylib |
| LIBRARY |
| COMPONENT Libraries |
| NAMELINK_COMPONENT Development |
| PUBLIC_HEADER |
| COMPONENT Development |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In this scenario, if you choose to install only the \fBDevelopment\fP |
| component, both the headers and namelink will be installed without the |
| library. (If you don\(aqt also install the \fBLibraries\fP component, the |
| namelink will be a dangling symlink, and projects that link to the library |
| will have build errors.) If you install only the \fBLibraries\fP component, |
| only the library will be installed, without the headers and namelink. |
| .sp |
| This option is typically used for package managers that have separate |
| runtime and development packages. For example, on Debian systems, the |
| library is expected to be in the runtime package, and the headers and |
| namelink are expected to be in the development package. |
| .sp |
| See the \fBVERSION\fP and \fBSOVERSION\fP target properties for |
| details on creating versioned shared libraries. |
| .TP |
| .B \fBNAMELINK_ONLY\fP |
| This option causes the installation of only the namelink when a library |
| target is installed. On platforms where versioned shared libraries do not |
| have namelinks or when a library is not versioned, the \fBNAMELINK_ONLY\fP |
| option installs nothing. It is an error to use this parameter outside of a |
| \fBLIBRARY\fP block. |
| .sp |
| When \fBNAMELINK_ONLY\fP is given, either \fBNAMELINK_COMPONENT\fP or |
| \fBCOMPONENT\fP may be used to specify the installation component of the |
| namelink, but \fBCOMPONENT\fP should generally be preferred. |
| .TP |
| .B \fBNAMELINK_SKIP\fP |
| Similar to \fBNAMELINK_ONLY\fP, but it has the opposite effect: it causes the |
| installation of library files other than the namelink when a library target |
| is installed. When neither \fBNAMELINK_ONLY\fP or \fBNAMELINK_SKIP\fP are given, |
| both portions are installed. On platforms where versioned shared libraries |
| do not have symlinks or when a library is not versioned, \fBNAMELINK_SKIP\fP |
| installs the library. It is an error to use this parameter outside of a |
| \fBLIBRARY\fP block. |
| .sp |
| If \fBNAMELINK_SKIP\fP is specified, \fBNAMELINK_COMPONENT\fP has no effect. It |
| is not recommended to use \fBNAMELINK_SKIP\fP in conjunction with |
| \fBNAMELINK_COMPONENT\fP\&. |
| .UNINDENT |
| .sp |
| The \fI\%install(TARGETS)\fP command can also accept the following options at the |
| top level: |
| .INDENT 0.0 |
| .TP |
| .B \fBEXPORT\fP |
| This option associates the installed target files with an export called |
| \fB<export\-name>\fP\&. It must appear before any target options. To actually |
| install the export file itself, call \fI\%install(EXPORT)\fP, documented below. |
| See documentation of the \fBEXPORT_NAME\fP target property to change |
| the name of the exported target. |
| .sp |
| If \fBEXPORT\fP is used and the targets include \fBPUBLIC\fP or \fBINTERFACE\fP |
| file sets, all of them must be specified with \fBFILE_SET\fP arguments. All |
| \fBPUBLIC\fP or \fBINTERFACE\fP file sets associated with a target are included |
| in the export. |
| .TP |
| .B \fBINCLUDES DESTINATION\fP |
| This option specifies a list of directories which will be added to the |
| \fBINTERFACE_INCLUDE_DIRECTORIES\fP target property of the |
| \fB<targets>\fP when exported by the \fI\%install(EXPORT)\fP command. If a |
| relative path is specified, it is treated as relative to the |
| \fB$<INSTALL_PREFIX>\fP\&. |
| .TP |
| .B \fBRUNTIME_DEPENDENCY_SET\fP |
| New in version 3.21. |
| |
| .sp |
| This option causes all runtime dependencies of installed executable, shared |
| library, and module targets to be added to the specified runtime dependency |
| set. This set can then be installed with an |
| \fI\%install(RUNTIME_DEPENDENCY_SET)\fP command. |
| .sp |
| This keyword and the \fBRUNTIME_DEPENDENCIES\fP keyword are mutually |
| exclusive. |
| .TP |
| .B \fBRUNTIME_DEPENDENCIES\fP |
| New in version 3.21. |
| |
| .sp |
| This option causes all runtime dependencies of installed executable, shared |
| library, and module targets to be installed along with the targets |
| themselves. The \fBRUNTIME\fP, \fBLIBRARY\fP, \fBFRAMEWORK\fP, and generic |
| arguments are used to determine the properties (\fBDESTINATION\fP, |
| \fBCOMPONENT\fP, etc.) of the installation of these dependencies. |
| .sp |
| \fBRUNTIME_DEPENDENCIES\fP is semantically equivalent to the following pair |
| of calls: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install(TARGETS ... RUNTIME_DEPENDENCY_SET <set\-name>) |
| install(RUNTIME_DEPENDENCY_SET <set\-name> args...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| where \fB<set\-name>\fP will be a randomly generated set name. |
| The \fBargs...\fP may include any of the following keywords supported by |
| the \fI\%install(RUNTIME_DEPENDENCY_SET)\fP command: |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBDIRECTORIES\fP |
| .IP \(bu 2 |
| \fBPRE_INCLUDE_REGEXES\fP |
| .IP \(bu 2 |
| \fBPRE_EXCLUDE_REGEXES\fP |
| .IP \(bu 2 |
| \fBPOST_INCLUDE_REGEXES\fP |
| .IP \(bu 2 |
| \fBPOST_EXCLUDE_REGEXES\fP |
| .IP \(bu 2 |
| \fBPOST_INCLUDE_FILES\fP |
| .IP \(bu 2 |
| \fBPOST_EXCLUDE_FILES\fP |
| .UNINDENT |
| .sp |
| The \fBRUNTIME_DEPENDENCIES\fP and \fBRUNTIME_DEPENDENCY_SET\fP keywords are |
| mutually exclusive. |
| .UNINDENT |
| .sp |
| One or more groups of properties may be specified in a single call to |
| the \fBTARGETS\fP form of this command. A target may be installed more than |
| once to different locations. Consider hypothetical targets \fBmyExe\fP, |
| \fBmySharedLib\fP, and \fBmyStaticLib\fP\&. The code: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install(TARGETS myExe mySharedLib myStaticLib |
| RUNTIME DESTINATION bin |
| LIBRARY DESTINATION lib |
| ARCHIVE DESTINATION lib/static) |
| install(TARGETS mySharedLib DESTINATION /some/full/path) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will install \fBmyExe\fP to \fB<prefix>/bin\fP and \fBmyStaticLib\fP to |
| \fB<prefix>/lib/static\fP\&. On non\-DLL platforms \fBmySharedLib\fP will be |
| installed to \fB<prefix>/lib\fP and \fB/some/full/path\fP\&. On DLL platforms |
| the \fBmySharedLib\fP DLL will be installed to \fB<prefix>/bin\fP and |
| \fB/some/full/path\fP and its import library will be installed to |
| \fB<prefix>/lib/static\fP and \fB/some/full/path\fP\&. |
| .sp |
| Interface Libraries may be listed among the targets to install. |
| They install no artifacts but will be included in an associated \fBEXPORT\fP\&. |
| If Object Libraries are listed but given no destination for their |
| object files, they will be exported as Interface Libraries\&. |
| This is sufficient to satisfy transitive usage requirements of other |
| targets that link to the object libraries in their implementation. |
| .sp |
| Installing a target with the \fBEXCLUDE_FROM_ALL\fP target property |
| set to \fBTRUE\fP has undefined behavior. |
| .sp |
| New in version 3.3: An install destination given as a \fBDESTINATION\fP argument may |
| use "generator expressions" with the syntax \fB$<...>\fP\&. See the |
| \fBcmake\-generator\-expressions(7)\fP manual for available expressions. |
| |
| .sp |
| New in version 3.13: \fI\%install(TARGETS)\fP can install targets that were created in |
| other directories. When using such cross\-directory install rules, running |
| \fBmake install\fP (or similar) from a subdirectory will not guarantee that |
| targets from other directories are up\-to\-date. You can use |
| \fBtarget_link_libraries()\fP or \fBadd_dependencies()\fP |
| to ensure that such out\-of\-directory targets are built before the |
| subdirectory\-specific install rules are run. |
| |
| .SS Installing Imported Runtime Artifacts |
| .sp |
| New in version 3.21. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install(IMPORTED_RUNTIME_ARTIFACTS targets... |
| [RUNTIME_DEPENDENCY_SET <set\-name>] |
| [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE] |
| [DESTINATION <dir>] |
| [PERMISSIONS permissions...] |
| [CONFIGURATIONS [Debug|Release|...]] |
| [COMPONENT <component>] |
| [OPTIONAL] [EXCLUDE_FROM_ALL] |
| ] [...] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBIMPORTED_RUNTIME_ARTIFACTS\fP form specifies rules for installing the |
| runtime artifacts of imported targets. Projects may do this if they want to |
| bundle outside executables or modules inside their installation. The |
| \fBLIBRARY\fP, \fBRUNTIME\fP, \fBFRAMEWORK\fP, and \fBBUNDLE\fP arguments have the |
| same semantics that they do in the \fI\%TARGETS\fP mode. Only the runtime artifacts |
| of imported targets are installed (except in the case of \fBFRAMEWORK\fP |
| libraries, \fBMACOSX_BUNDLE\fP executables, and \fBBUNDLE\fP |
| CFBundles.) For example, headers and import libraries associated with DLLs are |
| not installed. In the case of \fBFRAMEWORK\fP libraries, |
| \fBMACOSX_BUNDLE\fP executables, and \fBBUNDLE\fP CFBundles, the |
| entire directory is installed. |
| .sp |
| The \fBRUNTIME_DEPENDENCY_SET\fP option causes the runtime artifacts of the |
| imported executable, shared library, and module library \fBtargets\fP to be |
| added to the \fB<set\-name>\fP runtime dependency set. This set can then be |
| installed with an \fI\%install(RUNTIME_DEPENDENCY_SET)\fP command. |
| .SS Installing Files |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| If installing header files, consider using file sets defined by |
| \fBtarget_sources(FILE_SET)\fP instead. File sets associate |
| headers with a target and they install as part of the target. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install(<FILES|PROGRAMS> files... |
| TYPE <type> | DESTINATION <dir> |
| [PERMISSIONS permissions...] |
| [CONFIGURATIONS [Debug|Release|...]] |
| [COMPONENT <component>] |
| [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBFILES\fP form specifies rules for installing files for a project. |
| File names given as relative paths are interpreted with respect to the |
| current source directory. Files installed by this form are by default |
| given permissions \fBOWNER_WRITE\fP, \fBOWNER_READ\fP, \fBGROUP_READ\fP, and |
| \fBWORLD_READ\fP if no \fBPERMISSIONS\fP argument is given. |
| .sp |
| The \fBPROGRAMS\fP form is identical to the \fBFILES\fP form except that the |
| default permissions for the installed file also include \fBOWNER_EXECUTE\fP, |
| \fBGROUP_EXECUTE\fP, and \fBWORLD_EXECUTE\fP\&. This form is intended to install |
| programs that are not targets, such as shell scripts. Use the \fBTARGETS\fP |
| form to install targets built within the project. |
| .sp |
| The list of \fBfiles...\fP given to \fBFILES\fP or \fBPROGRAMS\fP may use |
| "generator expressions" with the syntax \fB$<...>\fP\&. See the |
| \fBcmake\-generator\-expressions(7)\fP manual for available expressions. |
| However, if any item begins in a generator expression it must evaluate |
| to a full path. |
| .sp |
| Either a \fBTYPE\fP or a \fBDESTINATION\fP must be provided, but not both. |
| A \fBTYPE\fP argument specifies the generic file type of the files being |
| installed. A destination will then be set automatically by taking the |
| corresponding variable from \fBGNUInstallDirs\fP, or by using a |
| built\-in default if that variable is not defined. See the table below for |
| the supported file types and their corresponding variables and built\-in |
| defaults. Projects can provide a \fBDESTINATION\fP argument instead of a |
| file type if they wish to explicitly define the install destination. |
| .TS |
| center; |
| |l|l|l|. |
| _ |
| T{ |
| \fBTYPE\fP Argument |
| T} T{ |
| GNUInstallDirs Variable |
| T} T{ |
| Built\-In Default |
| T} |
| _ |
| T{ |
| \fBBIN\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_BINDIR}\fP |
| T} T{ |
| \fBbin\fP |
| T} |
| _ |
| T{ |
| \fBSBIN\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_SBINDIR}\fP |
| T} T{ |
| \fBsbin\fP |
| T} |
| _ |
| T{ |
| \fBLIB\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_LIBDIR}\fP |
| T} T{ |
| \fBlib\fP |
| T} |
| _ |
| T{ |
| \fBINCLUDE\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_INCLUDEDIR}\fP |
| T} T{ |
| \fBinclude\fP |
| T} |
| _ |
| T{ |
| \fBSYSCONF\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_SYSCONFDIR}\fP |
| T} T{ |
| \fBetc\fP |
| T} |
| _ |
| T{ |
| \fBSHAREDSTATE\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_SHARESTATEDIR}\fP |
| T} T{ |
| \fBcom\fP |
| T} |
| _ |
| T{ |
| \fBLOCALSTATE\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_LOCALSTATEDIR}\fP |
| T} T{ |
| \fBvar\fP |
| T} |
| _ |
| T{ |
| \fBRUNSTATE\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_RUNSTATEDIR}\fP |
| T} T{ |
| \fB<LOCALSTATE dir>/run\fP |
| T} |
| _ |
| T{ |
| \fBDATA\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_DATADIR}\fP |
| T} T{ |
| \fB<DATAROOT dir>\fP |
| T} |
| _ |
| T{ |
| \fBINFO\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_INFODIR}\fP |
| T} T{ |
| \fB<DATAROOT dir>/info\fP |
| T} |
| _ |
| T{ |
| \fBLOCALE\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_LOCALEDIR}\fP |
| T} T{ |
| \fB<DATAROOT dir>/locale\fP |
| T} |
| _ |
| T{ |
| \fBMAN\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_MANDIR}\fP |
| T} T{ |
| \fB<DATAROOT dir>/man\fP |
| T} |
| _ |
| T{ |
| \fBDOC\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_DOCDIR}\fP |
| T} T{ |
| \fB<DATAROOT dir>/doc\fP |
| T} |
| _ |
| .TE |
| .sp |
| Projects wishing to follow the common practice of installing headers into a |
| project\-specific subdirectory will need to provide a destination rather than |
| rely on the above. Using file sets for headers instead of \fBinstall(FILES)\fP |
| would be even better (see \fBtarget_sources(FILE_SET)\fP). |
| .sp |
| Note that some of the types\(aq built\-in defaults use the \fBDATAROOT\fP directory as |
| a prefix. The \fBDATAROOT\fP prefix is calculated similarly to the types, with |
| \fBCMAKE_INSTALL_DATAROOTDIR\fP as the variable and \fBshare\fP as the built\-in |
| default. You cannot use \fBDATAROOT\fP as a \fBTYPE\fP parameter; please use |
| \fBDATA\fP instead. |
| .sp |
| To make packages compliant with distribution filesystem layout policies, if |
| projects must specify a \fBDESTINATION\fP, it is recommended that they use a |
| path that begins with the appropriate \fBGNUInstallDirs\fP variable. |
| This allows package maintainers to control the install destination by setting |
| the appropriate cache variables. The following example shows how to follow |
| this advice while installing an image to a project\-specific documentation |
| subdirectory: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| include(GNUInstallDirs) |
| install(FILES logo.png |
| DESTINATION ${CMAKE_INSTALL_DOCDIR}/myproj |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.4: An install destination given as a \fBDESTINATION\fP argument may |
| use "generator expressions" with the syntax \fB$<...>\fP\&. See the |
| \fBcmake\-generator\-expressions(7)\fP manual for available expressions. |
| |
| .sp |
| New in version 3.20: An install rename given as a \fBRENAME\fP argument may |
| use "generator expressions" with the syntax \fB$<...>\fP\&. See the |
| \fBcmake\-generator\-expressions(7)\fP manual for available expressions. |
| |
| .SS Installing Directories |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| To install a directory sub\-tree of headers, consider using file sets |
| defined by \fBtarget_sources(FILE_SET)\fP instead. File sets not only |
| preserve directory structure, they also associate headers with a target |
| and install as part of the target. |
| .UNINDENT |
| .UNINDENT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install(DIRECTORY dirs... |
| TYPE <type> | DESTINATION <dir> |
| [FILE_PERMISSIONS permissions...] |
| [DIRECTORY_PERMISSIONS permissions...] |
| [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER] |
| [CONFIGURATIONS [Debug|Release|...]] |
| [COMPONENT <component>] [EXCLUDE_FROM_ALL] |
| [FILES_MATCHING] |
| [[PATTERN <pattern> | REGEX <regex>] |
| [EXCLUDE] [PERMISSIONS permissions...]] [...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBDIRECTORY\fP form installs contents of one or more directories to a |
| given destination. The directory structure is copied verbatim to the |
| destination. The last component of each directory name is appended to |
| the destination directory but a trailing slash may be used to avoid |
| this because it leaves the last component empty. Directory names |
| given as relative paths are interpreted with respect to the current |
| source directory. If no input directory names are given the |
| destination directory will be created but nothing will be installed |
| into it. The \fBFILE_PERMISSIONS\fP and \fBDIRECTORY_PERMISSIONS\fP options |
| specify permissions given to files and directories in the destination. |
| If \fBUSE_SOURCE_PERMISSIONS\fP is specified and \fBFILE_PERMISSIONS\fP is not, |
| file permissions will be copied from the source directory structure. |
| If no permissions are specified files will be given the default |
| permissions specified in the \fBFILES\fP form of the command, and the |
| directories will be given the default permissions specified in the |
| \fBPROGRAMS\fP form of the command. |
| .sp |
| New in version 3.1: The \fBMESSAGE_NEVER\fP option disables file installation status output. |
| |
| .sp |
| Installation of directories may be controlled with fine granularity |
| using the \fBPATTERN\fP or \fBREGEX\fP options. These "match" options specify a |
| globbing pattern or regular expression to match directories or files |
| encountered within input directories. They may be used to apply |
| certain options (see below) to a subset of the files and directories |
| encountered. The full path to each input file or directory (with |
| forward slashes) is matched against the expression. A \fBPATTERN\fP will |
| match only complete file names: the portion of the full path matching |
| the pattern must occur at the end of the file name and be preceded by |
| a slash. A \fBREGEX\fP will match any portion of the full path but it may |
| use \fB/\fP and \fB$\fP to simulate the \fBPATTERN\fP behavior. By default all |
| files and directories are installed whether or not they are matched. |
| The \fBFILES_MATCHING\fP option may be given before the first match option |
| to disable installation of files (but not directories) not matched by |
| any expression. For example, the code |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install(DIRECTORY src/ DESTINATION doc/myproj |
| FILES_MATCHING PATTERN "*.png") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will extract and install images from a source tree. |
| .sp |
| Some options may follow a \fBPATTERN\fP or \fBREGEX\fP expression as described |
| under string(REGEX) and are applied |
| only to files or directories matching them. The \fBEXCLUDE\fP option will |
| skip the matched file or directory. The \fBPERMISSIONS\fP option overrides |
| the permissions setting for the matched file or directory. For |
| example the code |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install(DIRECTORY icons scripts/ DESTINATION share/myproj |
| PATTERN "CVS" EXCLUDE |
| PATTERN "scripts/*" |
| PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ |
| GROUP_EXECUTE GROUP_READ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will install the \fBicons\fP directory to \fBshare/myproj/icons\fP and the |
| \fBscripts\fP directory to \fBshare/myproj\fP\&. The icons will get default |
| file permissions, the scripts will be given specific permissions, and any |
| \fBCVS\fP directories will be excluded. |
| .sp |
| Either a \fBTYPE\fP or a \fBDESTINATION\fP must be provided, but not both. |
| A \fBTYPE\fP argument specifies the generic file type of the files within the |
| listed directories being installed. A destination will then be set |
| automatically by taking the corresponding variable from |
| \fBGNUInstallDirs\fP, or by using a built\-in default if that variable |
| is not defined. See the table below for the supported file types and their |
| corresponding variables and built\-in defaults. Projects can provide a |
| \fBDESTINATION\fP argument instead of a file type if they wish to explicitly |
| define the install destination. |
| .TS |
| center; |
| |l|l|l|. |
| _ |
| T{ |
| \fBTYPE\fP Argument |
| T} T{ |
| GNUInstallDirs Variable |
| T} T{ |
| Built\-In Default |
| T} |
| _ |
| T{ |
| \fBBIN\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_BINDIR}\fP |
| T} T{ |
| \fBbin\fP |
| T} |
| _ |
| T{ |
| \fBSBIN\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_SBINDIR}\fP |
| T} T{ |
| \fBsbin\fP |
| T} |
| _ |
| T{ |
| \fBLIB\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_LIBDIR}\fP |
| T} T{ |
| \fBlib\fP |
| T} |
| _ |
| T{ |
| \fBINCLUDE\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_INCLUDEDIR}\fP |
| T} T{ |
| \fBinclude\fP |
| T} |
| _ |
| T{ |
| \fBSYSCONF\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_SYSCONFDIR}\fP |
| T} T{ |
| \fBetc\fP |
| T} |
| _ |
| T{ |
| \fBSHAREDSTATE\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_SHARESTATEDIR}\fP |
| T} T{ |
| \fBcom\fP |
| T} |
| _ |
| T{ |
| \fBLOCALSTATE\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_LOCALSTATEDIR}\fP |
| T} T{ |
| \fBvar\fP |
| T} |
| _ |
| T{ |
| \fBRUNSTATE\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_RUNSTATEDIR}\fP |
| T} T{ |
| \fB<LOCALSTATE dir>/run\fP |
| T} |
| _ |
| T{ |
| \fBDATA\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_DATADIR}\fP |
| T} T{ |
| \fB<DATAROOT dir>\fP |
| T} |
| _ |
| T{ |
| \fBINFO\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_INFODIR}\fP |
| T} T{ |
| \fB<DATAROOT dir>/info\fP |
| T} |
| _ |
| T{ |
| \fBLOCALE\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_LOCALEDIR}\fP |
| T} T{ |
| \fB<DATAROOT dir>/locale\fP |
| T} |
| _ |
| T{ |
| \fBMAN\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_MANDIR}\fP |
| T} T{ |
| \fB<DATAROOT dir>/man\fP |
| T} |
| _ |
| T{ |
| \fBDOC\fP |
| T} T{ |
| \fB${CMAKE_INSTALL_DOCDIR}\fP |
| T} T{ |
| \fB<DATAROOT dir>/doc\fP |
| T} |
| _ |
| .TE |
| .sp |
| Note that some of the types\(aq built\-in defaults use the \fBDATAROOT\fP directory as |
| a prefix. The \fBDATAROOT\fP prefix is calculated similarly to the types, with |
| \fBCMAKE_INSTALL_DATAROOTDIR\fP as the variable and \fBshare\fP as the built\-in |
| default. You cannot use \fBDATAROOT\fP as a \fBTYPE\fP parameter; please use |
| \fBDATA\fP instead. |
| .sp |
| To make packages compliant with distribution filesystem layout policies, if |
| projects must specify a \fBDESTINATION\fP, it is recommended that they use a |
| path that begins with the appropriate \fBGNUInstallDirs\fP variable. |
| This allows package maintainers to control the install destination by setting |
| the appropriate cache variables. |
| .sp |
| New in version 3.4: An install destination given as a \fBDESTINATION\fP argument may |
| use "generator expressions" with the syntax \fB$<...>\fP\&. See the |
| \fBcmake\-generator\-expressions(7)\fP manual for available expressions. |
| |
| .sp |
| New in version 3.5: The list of \fBdirs...\fP given to \fBDIRECTORY\fP may use |
| "generator expressions" too. |
| |
| .SS Custom Installation Logic |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install([[SCRIPT <file>] [CODE <code>]] |
| [ALL_COMPONENTS | COMPONENT <component>] |
| [EXCLUDE_FROM_ALL] [...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBSCRIPT\fP form will invoke the given CMake script files during |
| installation. If the script file name is a relative path it will be |
| interpreted with respect to the current source directory. The \fBCODE\fP |
| form will invoke the given CMake code during installation. Code is |
| specified as a single argument inside a double\-quoted string. For |
| example, the code |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install(CODE "MESSAGE(\e"Sample install message.\e")") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will print a message during installation. |
| .sp |
| New in version 3.21: When the \fBALL_COMPONENTS\fP option is given, the custom installation |
| script code will be executed for every component of a component\-specific |
| installation. This option is mutually exclusive with the \fBCOMPONENT\fP |
| option. |
| |
| .sp |
| New in version 3.14: \fB<file>\fP or \fB<code>\fP may use "generator expressions" with the syntax |
| \fB$<...>\fP (in the case of \fB<file>\fP, this refers to their use in the file |
| name, not the file\(aqs contents). See the |
| \fBcmake\-generator\-expressions(7)\fP manual for available expressions. |
| |
| .SS Installing Exports |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install(EXPORT <export\-name> DESTINATION <dir> |
| [NAMESPACE <namespace>] [[FILE <name>.cmake]| |
| [PERMISSIONS permissions...] |
| [CONFIGURATIONS [Debug|Release|...]] |
| [EXPORT_LINK_INTERFACE_LIBRARIES] |
| [COMPONENT <component>] |
| [EXCLUDE_FROM_ALL]) |
| install(EXPORT_ANDROID_MK <export\-name> DESTINATION <dir> [...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBEXPORT\fP form generates and installs a CMake file containing code to |
| import targets from the installation tree into another project. |
| Target installations are associated with the export \fB<export\-name>\fP |
| using the \fBEXPORT\fP option of the \fI\%install(TARGETS)\fP signature |
| documented above. The \fBNAMESPACE\fP option will prepend \fB<namespace>\fP to |
| the target names as they are written to the import file. By default |
| the generated file will be called \fB<export\-name>.cmake\fP but the \fBFILE\fP |
| option may be used to specify a different name. The value given to |
| the \fBFILE\fP option must be a file name with the \fB\&.cmake\fP extension. |
| If a \fBCONFIGURATIONS\fP option is given then the file will only be installed |
| when one of the named configurations is installed. Additionally, the |
| generated import file will reference only the matching target |
| configurations. The \fBEXPORT_LINK_INTERFACE_LIBRARIES\fP keyword, if |
| present, causes the contents of the properties matching |
| \fB(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?\fP to be exported, when |
| policy \fBCMP0022\fP is \fBNEW\fP\&. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The installed \fB<export\-name>.cmake\fP file may come with additional |
| per\-configuration \fB<export\-name>\-*.cmake\fP files to be loaded by |
| globbing. Do not use an export name that is the same as the package |
| name in combination with installing a \fB<package\-name>\-config.cmake\fP |
| file or the latter may be incorrectly matched by the glob and loaded. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| When a \fBCOMPONENT\fP option is given, the listed \fB<component>\fP implicitly |
| depends on all components mentioned in the export set. The exported |
| \fB<name>.cmake\fP file will require each of the exported components to be |
| present in order for dependent projects to build properly. For example, a |
| project may define components \fBRuntime\fP and \fBDevelopment\fP, with shared |
| libraries going into the \fBRuntime\fP component and static libraries and |
| headers going into the \fBDevelopment\fP component. The export set would also |
| typically be part of the \fBDevelopment\fP component, but it would export |
| targets from both the \fBRuntime\fP and \fBDevelopment\fP components. Therefore, |
| the \fBRuntime\fP component would need to be installed if the \fBDevelopment\fP |
| component was installed, but not vice versa. If the \fBDevelopment\fP component |
| was installed without the \fBRuntime\fP component, dependent projects that try |
| to link against it would have build errors. Package managers, such as APT and |
| RPM, typically handle this by listing the \fBRuntime\fP component as a dependency |
| of the \fBDevelopment\fP component in the package metadata, ensuring that the |
| library is always installed if the headers and CMake export file are present. |
| .sp |
| New in version 3.7: In addition to cmake language files, the \fBEXPORT_ANDROID_MK\fP mode may be |
| used to specify an export to the android ndk build system. This mode |
| accepts the same options as the normal export mode. The Android |
| NDK supports the use of prebuilt libraries, both static and shared. This |
| allows cmake to build the libraries of a project and make them available |
| to an ndk build system complete with transitive dependencies, include flags |
| and defines required to use the libraries. |
| |
| .sp |
| The \fBEXPORT\fP form is useful to help outside projects use targets built |
| and installed by the current project. For example, the code |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install(TARGETS myexe EXPORT myproj DESTINATION bin) |
| install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj) |
| install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk\-modules) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will install the executable \fBmyexe\fP to \fB<prefix>/bin\fP and code to import |
| it in the file \fB<prefix>/lib/myproj/myproj.cmake\fP and |
| \fB<prefix>/share/ndk\-modules/Android.mk\fP\&. An outside project |
| may load this file with the include command and reference the \fBmyexe\fP |
| executable from the installation tree using the imported target name |
| \fBmp_myexe\fP as if the target were built in its own tree. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This command supersedes the \fBinstall_targets()\fP command and |
| the \fBPRE_INSTALL_SCRIPT\fP and \fBPOST_INSTALL_SCRIPT\fP |
| target properties. It also replaces the \fBFILES\fP forms of the |
| \fBinstall_files()\fP and \fBinstall_programs()\fP commands. |
| The processing order of these install rules relative to |
| those generated by \fBinstall_targets()\fP, |
| \fBinstall_files()\fP, and \fBinstall_programs()\fP commands |
| is not defined. |
| .UNINDENT |
| .UNINDENT |
| .SS Installing Runtime Dependencies |
| .sp |
| New in version 3.21. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install(RUNTIME_DEPENDENCY_SET <set\-name> |
| [[LIBRARY|RUNTIME|FRAMEWORK] |
| [DESTINATION <dir>] |
| [PERMISSIONS permissions...] |
| [CONFIGURATIONS [Debug|Release|...]] |
| [COMPONENT <component>] |
| [NAMELINK_COMPONENT <component>] |
| [OPTIONAL] [EXCLUDE_FROM_ALL] |
| ] [...] |
| [PRE_INCLUDE_REGEXES regexes...] |
| [PRE_EXCLUDE_REGEXES regexes...] |
| [POST_INCLUDE_REGEXES regexes...] |
| [POST_EXCLUDE_REGEXES regexes...] |
| [POST_INCLUDE_FILES files...] |
| [POST_EXCLUDE_FILES files...] |
| [DIRECTORIES directories...] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Installs a runtime dependency set previously created by one or more |
| \fI\%install(TARGETS)\fP or \fI\%install(IMPORTED_RUNTIME_ARTIFACTS)\fP commands. The |
| dependencies of targets belonging to a runtime dependency set are installed in |
| the \fBRUNTIME\fP destination and component on DLL platforms, and in the |
| \fBLIBRARY\fP destination and component on non\-DLL platforms. macOS frameworks |
| are installed in the \fBFRAMEWORK\fP destination and component. |
| Targets built within the build tree will never be installed as runtime |
| dependencies, nor will their own dependencies, unless the targets themselves |
| are installed with \fI\%install(TARGETS)\fP\&. |
| .sp |
| The generated install script calls \fBfile(GET_RUNTIME_DEPENDENCIES)\fP |
| on the build\-tree files to calculate the runtime dependencies. The build\-tree |
| executable files are passed as the \fBEXECUTABLES\fP argument, the build\-tree |
| shared libraries as the \fBLIBRARIES\fP argument, and the build\-tree modules as |
| the \fBMODULES\fP argument. On macOS, if one of the executables is a |
| \fBMACOSX_BUNDLE\fP, that executable is passed as the |
| \fBBUNDLE_EXECUTABLE\fP argument. At most one such bundle executable may be in |
| the runtime dependency set on macOS. The \fBMACOSX_BUNDLE\fP property |
| has no effect on other platforms. Note that |
| \fBfile(GET_RUNTIME_DEPENDENCIES)\fP only supports collecting the runtime |
| dependencies for Windows, Linux and macOS platforms, so |
| \fBinstall(RUNTIME_DEPENDENCY_SET)\fP has the same limitation. |
| .sp |
| The following sub\-arguments are forwarded through as the corresponding |
| arguments to \fBfile(GET_RUNTIME_DEPENDENCIES)\fP (for those that provide |
| a non\-empty list of directories, regular expressions or files). They all |
| support \fBgenerator expressions\fP\&. |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBDIRECTORIES <directories>\fP |
| .IP \(bu 2 |
| \fBPRE_INCLUDE_REGEXES <regexes>\fP |
| .IP \(bu 2 |
| \fBPRE_EXCLUDE_REGEXES <regexes>\fP |
| .IP \(bu 2 |
| \fBPOST_INCLUDE_REGEXES <regexes>\fP |
| .IP \(bu 2 |
| \fBPOST_EXCLUDE_REGEXES <regexes>\fP |
| .IP \(bu 2 |
| \fBPOST_INCLUDE_FILES <files>\fP |
| .IP \(bu 2 |
| \fBPOST_EXCLUDE_FILES <files>\fP |
| .UNINDENT |
| .SS Generated Installation Script |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Use of this feature is not recommended. Please consider using the |
| \fB\-\-install\fP argument of \fBcmake(1)\fP instead. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBinstall()\fP command generates a file, \fBcmake_install.cmake\fP, inside |
| the build directory, which is used internally by the generated install target |
| and by CPack. You can also invoke this script manually with \fBcmake \-P\fP\&. This |
| script accepts several variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBCOMPONENT\fP |
| Set this variable to install only a single CPack component as opposed to all |
| of them. For example, if you only want to install the \fBDevelopment\fP |
| component, run \fBcmake \-DCOMPONENT=Development \-P cmake_install.cmake\fP\&. |
| .TP |
| .B \fBBUILD_TYPE\fP |
| Set this variable to change the build type if you are using a multi\-config |
| generator. For example, to install with the \fBDebug\fP configuration, run |
| \fBcmake \-DBUILD_TYPE=Debug \-P cmake_install.cmake\fP\&. |
| .TP |
| .B \fBDESTDIR\fP |
| This is an environment variable rather than a CMake variable. It allows you |
| to change the installation prefix on UNIX systems. See \fBDESTDIR\fP for |
| details. |
| .UNINDENT |
| .SS link_directories |
| .sp |
| Add directories in which the linker will look for libraries. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| link_directories([AFTER|BEFORE] directory1 [directory2 ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Adds the paths in which the linker should search for libraries. |
| Relative paths given to this command are interpreted as relative to |
| the current source directory, see \fBCMP0015\fP\&. |
| .sp |
| The command will apply only to targets created after it is called. |
| .sp |
| New in version 3.13: The directories are added to the \fBLINK_DIRECTORIES\fP directory |
| property for the current \fBCMakeLists.txt\fP file, converting relative |
| paths to absolute as needed. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| |
| .sp |
| New in version 3.13: By default the directories specified are appended onto the current list of |
| directories. This default behavior can be changed by setting |
| \fBCMAKE_LINK_DIRECTORIES_BEFORE\fP to \fBON\fP\&. By using |
| \fBAFTER\fP or \fBBEFORE\fP explicitly, you can select between appending and |
| prepending, independent of the default. |
| |
| .sp |
| New in version 3.13: Arguments to \fBlink_directories\fP may use "generator expressions" with |
| the syntax "$<...>". See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. |
| |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This command is rarely necessary and should be avoided where there are |
| other choices. Prefer to pass full absolute paths to libraries where |
| possible, since this ensures the correct library will always be linked. |
| The \fBfind_library()\fP command provides the full path, which can |
| generally be used directly in calls to \fBtarget_link_libraries()\fP\&. |
| Situations where a library search path may be needed include: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| Project generators like Xcode where the user can switch target |
| architecture at build time, but a full path to a library cannot |
| be used because it only provides one architecture (i.e. it is not |
| a universal binary). |
| .IP \(bu 2 |
| Libraries may themselves have other private library dependencies |
| that expect to be found via \fBRPATH\fP mechanisms, but some linkers |
| are not able to fully decode those paths (e.g. due to the presence |
| of things like \fB$ORIGIN\fP). |
| .UNINDENT |
| .sp |
| If a library search path must be provided, prefer to localize the effect |
| where possible by using the \fBtarget_link_directories()\fP command |
| rather than \fBlink_directories()\fP\&. The target\-specific command can also |
| control how the search directories propagate to other dependent targets. |
| .UNINDENT |
| .UNINDENT |
| .SS link_libraries |
| .sp |
| Link libraries to all targets added later. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| link_libraries([item1 [item2 [...]]] |
| [[debug|optimized|general] <item>] ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Specify libraries or flags to use when linking any targets created later in |
| the current directory or below by commands such as \fBadd_executable()\fP |
| or \fBadd_library()\fP\&. See the \fBtarget_link_libraries()\fP command |
| for meaning of arguments. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The \fBtarget_link_libraries()\fP command should be preferred whenever |
| possible. Library dependencies are chained automatically, so directory\-wide |
| specification of link libraries is rarely needed. |
| .UNINDENT |
| .UNINDENT |
| .SS load_cache |
| .sp |
| Load in the values from another project\(aqs CMake cache. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Reads the cache and store the requested entries in variables with their |
| name prefixed with the given prefix. This only reads the values, and |
| does not create entries in the local project\(aqs cache. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| load_cache(pathToBuildDirectory [EXCLUDE entry1...] |
| [INCLUDE_INTERNALS entry1...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Loads in the values from another cache and store them in the local |
| project\(aqs cache as internal entries. This is useful for a project |
| that depends on another project built in a different tree. \fBEXCLUDE\fP |
| option can be used to provide a list of entries to be excluded. |
| \fBINCLUDE_INTERNALS\fP can be used to provide a list of internal entries to |
| be included. Normally, no internal entries are brought in. Use of |
| this form of the command is strongly discouraged, but it is provided |
| for backward compatibility. |
| .SS project |
| .sp |
| Set the name of the project. |
| .SS Synopsis |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| project(<PROJECT\-NAME> [<language\-name>...]) |
| project(<PROJECT\-NAME> |
| [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]] |
| [DESCRIPTION <project\-description\-string>] |
| [HOMEPAGE_URL <url\-string>] |
| [LANGUAGES <language\-name>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets the name of the project, and stores it in the variable |
| \fBPROJECT_NAME\fP\&. When called from the top\-level |
| \fBCMakeLists.txt\fP also stores the project name in the |
| variable \fBCMAKE_PROJECT_NAME\fP\&. |
| .sp |
| Also sets the variables: |
| .INDENT 0.0 |
| .TP |
| .B \fBPROJECT_SOURCE_DIR\fP, \fB<PROJECT\-NAME>_SOURCE_DIR\fP |
| Absolute path to the source directory for the project. |
| .TP |
| .B \fBPROJECT_BINARY_DIR\fP, \fB<PROJECT\-NAME>_BINARY_DIR\fP |
| Absolute path to the binary directory for the project. |
| .TP |
| .B \fBPROJECT_IS_TOP_LEVEL\fP, \fB<PROJECT\-NAME>_IS_TOP_LEVEL\fP |
| New in version 3.21. |
| |
| .sp |
| Boolean value indicating whether the project is top\-level. |
| .UNINDENT |
| .sp |
| Further variables are set by the optional arguments described in the following. |
| If any of these arguments is not used, then the corresponding variables are |
| set to the empty string. |
| .SS Options |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBVERSION <version>\fP |
| Optional; may not be used unless policy \fBCMP0048\fP is |
| set to \fBNEW\fP\&. |
| .sp |
| Takes a \fB<version>\fP argument composed of non\-negative integer components, |
| i.e. \fB<major>[.<minor>[.<patch>[.<tweak>]]]\fP, |
| and sets the variables |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBPROJECT_VERSION\fP, |
| \fB<PROJECT\-NAME>_VERSION\fP |
| .IP \(bu 2 |
| \fBPROJECT_VERSION_MAJOR\fP, |
| \fB<PROJECT\-NAME>_VERSION_MAJOR\fP |
| .IP \(bu 2 |
| \fBPROJECT_VERSION_MINOR\fP, |
| \fB<PROJECT\-NAME>_VERSION_MINOR\fP |
| .IP \(bu 2 |
| \fBPROJECT_VERSION_PATCH\fP, |
| \fB<PROJECT\-NAME>_VERSION_PATCH\fP |
| .IP \(bu 2 |
| \fBPROJECT_VERSION_TWEAK\fP, |
| \fB<PROJECT\-NAME>_VERSION_TWEAK\fP\&. |
| .UNINDENT |
| .sp |
| New in version 3.12: When the \fBproject()\fP command is called from the top\-level |
| \fBCMakeLists.txt\fP, then the version is also stored in the variable |
| \fBCMAKE_PROJECT_VERSION\fP\&. |
| |
| .TP |
| .B \fBDESCRIPTION <project\-description\-string>\fP |
| New in version 3.9. |
| |
| .sp |
| Optional. |
| Sets the variables |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBPROJECT_DESCRIPTION\fP, \fB<PROJECT\-NAME>_DESCRIPTION\fP |
| .UNINDENT |
| .sp |
| to \fB<project\-description\-string>\fP\&. |
| It is recommended that this description is a relatively short string, |
| usually no more than a few words. |
| .sp |
| When the \fBproject()\fP command is called from the top\-level \fBCMakeLists.txt\fP, |
| then the description is also stored in the variable \fBCMAKE_PROJECT_DESCRIPTION\fP\&. |
| .sp |
| New in version 3.12: Added the \fB<PROJECT\-NAME>_DESCRIPTION\fP variable. |
| |
| .TP |
| .B \fBHOMEPAGE_URL <url\-string>\fP |
| New in version 3.12. |
| |
| .sp |
| Optional. |
| Sets the variables |
| .INDENT 7.0 |
| .IP \(bu 2 |
| \fBPROJECT_HOMEPAGE_URL\fP, \fB<PROJECT\-NAME>_HOMEPAGE_URL\fP |
| .UNINDENT |
| .sp |
| to \fB<url\-string>\fP, which should be the canonical home URL for the project. |
| .sp |
| When the \fBproject()\fP command is called from the top\-level \fBCMakeLists.txt\fP, |
| then the URL also is stored in the variable \fBCMAKE_PROJECT_HOMEPAGE_URL\fP\&. |
| .TP |
| .B \fBLANGUAGES <language\-name>...\fP |
| Optional. |
| Can also be specified without \fBLANGUAGES\fP keyword per the first, short signature. |
| .sp |
| Selects which programming languages are needed to build the project. |
| Supported languages include \fBC\fP, \fBCXX\fP (i.e. C++), \fBCUDA\fP, |
| \fBOBJC\fP (i.e. Objective\-C), \fBOBJCXX\fP, \fBFortran\fP, \fBHIP\fP, \fBISPC\fP, and \fBASM\fP\&. |
| By default \fBC\fP and \fBCXX\fP are enabled if no language options are given. |
| Specify language \fBNONE\fP, or use the \fBLANGUAGES\fP keyword and list no languages, |
| to skip enabling any languages. |
| .sp |
| New in version 3.8: Added \fBCUDA\fP support. |
| |
| .sp |
| New in version 3.16: Added \fBOBJC\fP and \fBOBJCXX\fP support. |
| |
| .sp |
| New in version 3.18: Added \fBISPC\fP support. |
| |
| .sp |
| If enabling \fBASM\fP, list it last so that CMake can check whether |
| compilers for other languages like \fBC\fP work for assembly too. |
| .UNINDENT |
| .sp |
| The variables set through the \fBVERSION\fP, \fBDESCRIPTION\fP and \fBHOMEPAGE_URL\fP |
| options are intended for use as default values in package metadata and documentation. |
| .SS Code Injection |
| .sp |
| If the \fBCMAKE_PROJECT_INCLUDE_BEFORE\fP or |
| \fBCMAKE_PROJECT_<PROJECT\-NAME>_INCLUDE_BEFORE\fP variables are set, |
| the files they point to will be included as the first step of the |
| \fBproject()\fP command. |
| If both are set, then \fBCMAKE_PROJECT_INCLUDE_BEFORE\fP will be |
| included before \fBCMAKE_PROJECT_<PROJECT\-NAME>_INCLUDE_BEFORE\fP\&. |
| .sp |
| If the \fBCMAKE_PROJECT_INCLUDE\fP or |
| \fBCMAKE_PROJECT_<PROJECT\-NAME>_INCLUDE\fP variables are set, the files |
| they point to will be included as the last step of the \fBproject()\fP command. |
| If both are set, then \fBCMAKE_PROJECT_INCLUDE\fP will be included before |
| \fBCMAKE_PROJECT_<PROJECT\-NAME>_INCLUDE\fP\&. |
| .sp |
| New in version 3.15: Added the \fBCMAKE_PROJECT_INCLUDE\fP and \fBCMAKE_PROJECT_INCLUDE_BEFORE\fP |
| variables. |
| |
| .sp |
| New in version 3.17: Added the \fBCMAKE_PROJECT_<PROJECT\-NAME>_INCLUDE_BEFORE\fP variable. |
| |
| .SS Usage |
| .sp |
| The top\-level \fBCMakeLists.txt\fP file for a project must contain a |
| literal, direct call to the \fBproject()\fP command; loading one |
| through the \fBinclude()\fP command is not sufficient. If no such |
| call exists, CMake will issue a warning and pretend there is a |
| \fBproject(Project)\fP at the top to enable the default languages |
| (\fBC\fP and \fBCXX\fP). |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Call the \fBproject()\fP command near the top of the top\-level |
| \fBCMakeLists.txt\fP, but \fIafter\fP calling \fBcmake_minimum_required()\fP\&. |
| It is important to establish version and policy settings before invoking |
| other commands whose behavior they may affect. |
| See also policy \fBCMP0000\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .SS remove_definitions |
| .sp |
| Remove \-D define flags added by \fBadd_definitions()\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| remove_definitions(\-DFOO \-DBAR ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Removes flags (added by \fBadd_definitions()\fP) from the compiler |
| command line for sources in the current directory and below. |
| .SS set_source_files_properties |
| .sp |
| Source files can have properties that affect how they are built. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_source_files_properties(<files> ... |
| [DIRECTORY <dirs> ...] |
| [TARGET_DIRECTORY <targets> ...] |
| PROPERTIES <prop1> <value1> |
| [<prop2> <value2>] ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets properties associated with source files using a key/value paired |
| list. |
| .sp |
| New in version 3.18: By default, source file properties are only visible to targets added in the |
| same directory (\fBCMakeLists.txt\fP). Visibility can be set in other directory |
| scopes using one or both of the following options: |
| |
| .INDENT 0.0 |
| .TP |
| .B \fBDIRECTORY <dirs>...\fP |
| The source file properties will be set in each of the \fB<dirs>\fP |
| directories\(aq scopes. CMake must already know about each of these |
| source directories, either by having added them through a call to |
| \fBadd_subdirectory()\fP or it being the top level source directory. |
| Relative paths are treated as relative to the current source directory. |
| .TP |
| .B \fBTARGET_DIRECTORY <targets>...\fP |
| The source file properties will be set in each of the directory scopes |
| where any of the specified \fB<targets>\fP were created (the \fB<targets>\fP |
| must therefore already exist). |
| .UNINDENT |
| .sp |
| Use \fBget_source_file_property()\fP to get property values. |
| See also the \fBset_property(SOURCE)\fP command. |
| .sp |
| See Source File Properties for the list of properties known |
| to CMake. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The \fBGENERATED\fP source file property may be globally visible. |
| See its documentation for details. |
| .UNINDENT |
| .UNINDENT |
| .SS set_target_properties |
| .sp |
| Targets can have properties that affect how they are built. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_target_properties(target1 target2 ... |
| PROPERTIES prop1 value1 |
| prop2 value2 ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets properties on targets. The syntax for the command is to list all |
| the targets you want to change, and then provide the values you want to |
| set next. You can use any prop value pair you want and extract it |
| later with the \fBget_property()\fP or \fBget_target_property()\fP |
| command. |
| .sp |
| See also the \fBset_property(TARGET)\fP command. |
| .sp |
| See Target Properties for the list of properties known to CMake. |
| .SS set_tests_properties |
| .sp |
| Set a property of the tests. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets a property for the tests. If the test is not found, CMake |
| will report an error. |
| .sp |
| Test property values may be specified using |
| \fBgenerator expressions\fP |
| for tests created by the \fBadd_test(NAME)\fP signature. |
| .sp |
| See also the \fBset_property(TEST)\fP command. |
| .sp |
| See Test Properties for the list of properties known to CMake. |
| .SS source_group |
| .sp |
| Define a grouping for source files in IDE project generation. |
| There are two different signatures to create source groups. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>]) |
| source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Defines a group into which sources will be placed in project files. |
| This is intended to set up file tabs in Visual Studio. |
| The group is scoped in the directory where the command is called, |
| and applies to sources in targets created in that directory. |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBTREE\fP |
| New in version 3.8. |
| |
| .sp |
| CMake will automatically detect, from \fB<src>\fP files paths, source groups |
| it needs to create, to keep structure of source groups analogically to the |
| actual files and directories structure in the project. Paths of \fB<src>\fP |
| files will be cut to be relative to \fB<root>\fP\&. The command fails if the |
| paths within \fBsrc\fP do not start with \fBroot\fP\&. |
| .TP |
| .B \fBPREFIX\fP |
| New in version 3.8. |
| |
| .sp |
| Source group and files located directly in \fB<root>\fP path, will be placed |
| in \fB<prefix>\fP source groups. |
| .TP |
| .B \fBFILES\fP |
| Any source file specified explicitly will be placed in group |
| \fB<name>\fP\&. Relative paths are interpreted with respect to the |
| current source directory. |
| .TP |
| .B \fBREGULAR_EXPRESSION\fP |
| Any source file whose name matches the regular expression will |
| be placed in group \fB<name>\fP\&. |
| .UNINDENT |
| .sp |
| If a source file matches multiple groups, the \fIlast\fP group that |
| explicitly lists the file with \fBFILES\fP will be favored, if any. |
| If no group explicitly lists the file, the \fIlast\fP group whose |
| regular expression matches the file will be favored. |
| .sp |
| The \fB<name>\fP of the group and \fB<prefix>\fP argument may contain forward |
| slashes or backslashes to specify subgroups. Backslashes need to be escaped |
| appropriately: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| source_group(base/subdir ...) |
| source_group(outer\e\einner ...) |
| source_group(TREE <root> PREFIX sources\e\einc ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| New in version 3.18: Allow using forward slashes (\fB/\fP) to specify subgroups. |
| |
| .sp |
| For backwards compatibility, the short\-hand signature |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| source_group(<name> <regex>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| is equivalent to |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| source_group(<name> REGULAR_EXPRESSION <regex>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS target_compile_definitions |
| .sp |
| Add compile definitions to a target. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_compile_definitions(<target> |
| <INTERFACE|PUBLIC|PRIVATE> [items1...] |
| [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Specifies compile definitions to use when compiling a given \fB<target>\fP\&. The |
| named \fB<target>\fP must have been created by a command such as |
| \fBadd_executable()\fP or \fBadd_library()\fP and must not be an |
| ALIAS target\&. |
| .sp |
| The \fBINTERFACE\fP, \fBPUBLIC\fP and \fBPRIVATE\fP keywords are required to |
| specify the scope of the following arguments. \fBPRIVATE\fP and \fBPUBLIC\fP |
| items will populate the \fBCOMPILE_DEFINITIONS\fP property of |
| \fB<target>\fP\&. \fBPUBLIC\fP and \fBINTERFACE\fP items will populate the |
| \fBINTERFACE_COMPILE_DEFINITIONS\fP property of \fB<target>\fP\&. |
| The following arguments specify compile definitions. Repeated calls for the |
| same \fB<target>\fP append items in the order called. |
| .sp |
| New in version 3.11: Allow setting \fBINTERFACE\fP items on IMPORTED targets\&. |
| |
| .sp |
| Arguments to \fBtarget_compile_definitions\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .sp |
| Any leading \fB\-D\fP on an item will be removed. Empty items are ignored. |
| For example, the following are all equivalent: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_compile_definitions(foo PUBLIC FOO) |
| target_compile_definitions(foo PUBLIC \-DFOO) # \-D removed |
| target_compile_definitions(foo PUBLIC "" FOO) # "" ignored |
| target_compile_definitions(foo PUBLIC \-D FOO) # \-D becomes "", then ignored |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Definitions may optionally have values: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_compile_definitions(foo PUBLIC FOO=1) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Note that many compilers treat \fB\-DFOO\fP as equivalent to \fB\-DFOO=1\fP, but |
| other tools may not recognize this in all circumstances (e.g. IntelliSense). |
| .SS target_compile_features |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Add expected compiler features to a target. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Specifies compiler features required when compiling a given target. If the |
| feature is not listed in the \fBCMAKE_C_COMPILE_FEATURES\fP, |
| \fBCMAKE_CUDA_COMPILE_FEATURES\fP, or \fBCMAKE_CXX_COMPILE_FEATURES\fP |
| variables, then an error will be reported by CMake. If the use of the feature requires |
| an additional compiler flag, such as \fB\-std=gnu++11\fP, the flag will be added |
| automatically. |
| .sp |
| The \fBINTERFACE\fP, \fBPUBLIC\fP and \fBPRIVATE\fP keywords are required to |
| specify the scope of the features. \fBPRIVATE\fP and \fBPUBLIC\fP items will |
| populate the \fBCOMPILE_FEATURES\fP property of \fB<target>\fP\&. |
| \fBPUBLIC\fP and \fBINTERFACE\fP items will populate the |
| \fBINTERFACE_COMPILE_FEATURES\fP property of \fB<target>\fP\&. |
| Repeated calls for the same \fB<target>\fP append items. |
| .sp |
| New in version 3.11: Allow setting \fBINTERFACE\fP items on IMPORTED targets\&. |
| |
| .sp |
| The named \fB<target>\fP must have been created by a command such as |
| \fBadd_executable()\fP or \fBadd_library()\fP and must not be an |
| ALIAS target\&. |
| .sp |
| Arguments to \fBtarget_compile_features\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. |
| See the \fBcmake\-generator\-expressions(7)\fP manual for available |
| expressions. See the \fBcmake\-compile\-features(7)\fP manual for |
| information on compile features and a list of supported compilers. |
| .SS target_compile_options |
| .sp |
| Add compile options to a target. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_compile_options(<target> [BEFORE] |
| <INTERFACE|PUBLIC|PRIVATE> [items1...] |
| [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Adds options to the \fBCOMPILE_OPTIONS\fP or |
| \fBINTERFACE_COMPILE_OPTIONS\fP target properties. These options |
| are used when compiling the given \fB<target>\fP, which must have been |
| created by a command such as \fBadd_executable()\fP or |
| \fBadd_library()\fP and must not be an ALIAS target\&. |
| .SS Arguments |
| .sp |
| If \fBBEFORE\fP is specified, the content will be prepended to the property |
| instead of being appended. |
| .sp |
| The \fBINTERFACE\fP, \fBPUBLIC\fP and \fBPRIVATE\fP keywords are required to |
| specify the scope of the following arguments. \fBPRIVATE\fP and \fBPUBLIC\fP |
| items will populate the \fBCOMPILE_OPTIONS\fP property of |
| \fB<target>\fP\&. \fBPUBLIC\fP and \fBINTERFACE\fP items will populate the |
| \fBINTERFACE_COMPILE_OPTIONS\fP property of \fB<target>\fP\&. |
| The following arguments specify compile options. Repeated calls for the same |
| \fB<target>\fP append items in the order called. |
| .sp |
| New in version 3.11: Allow setting \fBINTERFACE\fP items on IMPORTED targets\&. |
| |
| .sp |
| Arguments to \fBtarget_compile_options\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .SS Option De\-duplication |
| .sp |
| The final set of options used for a target is constructed by |
| accumulating options from the current target and the usage requirements of |
| its dependencies. The set of options is de\-duplicated to avoid repetition. |
| .sp |
| New in version 3.12: While beneficial for individual options, the de\-duplication step can break |
| up option groups. For example, \fB\-option A \-option B\fP becomes |
| \fB\-option A B\fP\&. One may specify a group of options using shell\-like |
| quoting along with a \fBSHELL:\fP prefix. The \fBSHELL:\fP prefix is dropped, |
| and the rest of the option string is parsed using the |
| \fBseparate_arguments()\fP \fBUNIX_COMMAND\fP mode. For example, |
| \fB"SHELL:\-option A" "SHELL:\-option B"\fP becomes \fB\-option A \-option B\fP\&. |
| |
| .SS See Also |
| .sp |
| This command can be used to add any options. However, for adding |
| preprocessor definitions and include directories it is recommended |
| to use the more specific commands \fBtarget_compile_definitions()\fP |
| and \fBtarget_include_directories()\fP\&. |
| .sp |
| For directory\-wide settings, there is the command \fBadd_compile_options()\fP\&. |
| .sp |
| For file\-specific settings, there is the source file property \fBCOMPILE_OPTIONS\fP\&. |
| .SS target_include_directories |
| .sp |
| Add include directories to a target. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_include_directories(<target> [SYSTEM] [AFTER|BEFORE] |
| <INTERFACE|PUBLIC|PRIVATE> [items1...] |
| [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Specifies include directories to use when compiling a given target. |
| The named \fB<target>\fP must have been created by a command such |
| as \fBadd_executable()\fP or \fBadd_library()\fP and must not be an |
| ALIAS target\&. |
| .sp |
| By using \fBAFTER\fP or \fBBEFORE\fP explicitly, you can select between appending |
| and prepending, independent of the default. |
| .sp |
| The \fBINTERFACE\fP, \fBPUBLIC\fP and \fBPRIVATE\fP keywords are required to specify |
| the scope of the following arguments. \fBPRIVATE\fP and \fBPUBLIC\fP items will |
| populate the \fBINCLUDE_DIRECTORIES\fP property of \fB<target>\fP\&. |
| \fBPUBLIC\fP and \fBINTERFACE\fP items will populate the |
| \fBINTERFACE_INCLUDE_DIRECTORIES\fP property of \fB<target>\fP\&. |
| The following arguments specify include directories. |
| .sp |
| New in version 3.11: Allow setting \fBINTERFACE\fP items on IMPORTED targets\&. |
| |
| .sp |
| Repeated calls for the same \fB<target>\fP append items in the order called. |
| .sp |
| If \fBSYSTEM\fP is specified, the compiler will be told the directories |
| are meant as system include directories on some platforms. This may |
| have effects such as suppressing warnings or skipping the contained |
| headers in dependency calculations (see compiler documentation). |
| Additionally, system include directories are searched after normal |
| include directories regardless of the order specified. |
| .sp |
| If \fBSYSTEM\fP is used together with \fBPUBLIC\fP or \fBINTERFACE\fP, the |
| \fBINTERFACE_SYSTEM_INCLUDE_DIRECTORIES\fP target property will be |
| populated with the specified directories. |
| .sp |
| Arguments to \fBtarget_include_directories\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .sp |
| Specified include directories may be absolute paths or relative paths. |
| A relative path will be interpreted as relative to the current source |
| directory (i.e. \fBCMAKE_CURRENT_SOURCE_DIR\fP) and converted to an |
| absolute path before storing it in the associated target property. |
| If the path starts with a generator expression, it will always be assumed |
| to be an absolute path (with one exception noted below) and will be used |
| unmodified. |
| .sp |
| Include directories usage requirements commonly differ between the build\-tree |
| and the install\-tree. The \fBBUILD_INTERFACE\fP and |
| \fBINSTALL_INTERFACE\fP generator expressions can be used to describe |
| separate usage requirements based on the usage location. Relative paths |
| are allowed within the \fBINSTALL_INTERFACE\fP expression and are |
| interpreted as relative to the installation prefix. Relative paths should not |
| be used in \fBBUILD_INTERFACE\fP expressions because they will not be |
| converted to absolute. For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_include_directories(mylib PUBLIC |
| $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib> |
| $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Creating Relocatable Packages |
| .sp |
| Note that it is not advisable to populate the \fBINSTALL_INTERFACE\fP of |
| the \fBINTERFACE_INCLUDE_DIRECTORIES\fP of a target with absolute paths to the include |
| directories of dependencies. That would hard\-code into installed packages |
| the include directory paths for dependencies |
| \fBas found on the machine the package was made on\fP\&. |
| .sp |
| The \fBINSTALL_INTERFACE\fP of the \fBINTERFACE_INCLUDE_DIRECTORIES\fP is only |
| suitable for specifying the required include directories for headers |
| provided with the target itself, not those provided by the transitive |
| dependencies listed in its \fBINTERFACE_LINK_LIBRARIES\fP target |
| property. Those dependencies should themselves be targets that specify |
| their own header locations in \fBINTERFACE_INCLUDE_DIRECTORIES\fP\&. |
| .sp |
| See the Creating Relocatable Packages section of the |
| \fBcmake\-packages(7)\fP manual for discussion of additional care |
| that must be taken when specifying usage requirements while creating |
| packages for redistribution. |
| .SS target_link_directories |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Add link directories to a target. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_link_directories(<target> [BEFORE] |
| <INTERFACE|PUBLIC|PRIVATE> [items1...] |
| [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Specifies the paths in which the linker should search for libraries when |
| linking a given target. Each item can be an absolute or relative path, |
| with the latter being interpreted as relative to the current source |
| directory. These items will be added to the link command. |
| .sp |
| The named \fB<target>\fP must have been created by a command such as |
| \fBadd_executable()\fP or \fBadd_library()\fP and must not be an |
| ALIAS target\&. |
| .sp |
| The \fBINTERFACE\fP, \fBPUBLIC\fP and \fBPRIVATE\fP keywords are required to |
| specify the scope of the items that follow them. \fBPRIVATE\fP and |
| \fBPUBLIC\fP items will populate the \fBLINK_DIRECTORIES\fP property |
| of \fB<target>\fP\&. \fBPUBLIC\fP and \fBINTERFACE\fP items will populate the |
| \fBINTERFACE_LINK_DIRECTORIES\fP property of \fB<target>\fP |
| (IMPORTED targets only support \fBINTERFACE\fP items). |
| Each item specifies a link directory and will be converted to an absolute |
| path if necessary before adding it to the relevant property. Repeated |
| calls for the same \fB<target>\fP append items in the order called. |
| .sp |
| If \fBBEFORE\fP is specified, the content will be prepended to the relevant |
| property instead of being appended. |
| .sp |
| Arguments to \fBtarget_link_directories\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This command is rarely necessary and should be avoided where there are |
| other choices. Prefer to pass full absolute paths to libraries where |
| possible, since this ensures the correct library will always be linked. |
| The \fBfind_library()\fP command provides the full path, which can |
| generally be used directly in calls to \fBtarget_link_libraries()\fP\&. |
| Situations where a library search path may be needed include: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| Project generators like Xcode where the user can switch target |
| architecture at build time, but a full path to a library cannot |
| be used because it only provides one architecture (i.e. it is not |
| a universal binary). |
| .IP \(bu 2 |
| Libraries may themselves have other private library dependencies |
| that expect to be found via \fBRPATH\fP mechanisms, but some linkers |
| are not able to fully decode those paths (e.g. due to the presence |
| of things like \fB$ORIGIN\fP). |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS target_link_libraries |
| .sp |
| Specify libraries or flags to use when linking a given target and/or |
| its dependents. Usage requirements |
| from linked library targets will be propagated. Usage requirements |
| of a target\(aqs dependencies affect compilation of its own sources. |
| .SS Overview |
| .sp |
| This command has several signatures as detailed in subsections below. |
| All of them have the general form |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_link_libraries(<target> ... <item>... ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The named \fB<target>\fP must have been created by a command such as |
| \fBadd_executable()\fP or \fBadd_library()\fP and must not be an |
| ALIAS target\&. If policy \fBCMP0079\fP is not |
| set to \fBNEW\fP then the target must have been created in the current |
| directory. Repeated calls for the same \fB<target>\fP append items in |
| the order called. |
| .sp |
| New in version 3.13: The \fB<target>\fP doesn\(aqt have to be defined in the same directory as the |
| \fBtarget_link_libraries\fP call. |
| |
| .sp |
| Each \fB<item>\fP may be: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBA library target name\fP: The generated link line will have the |
| full path to the linkable library file associated with the target. |
| The buildsystem will have a dependency to re\-link \fB<target>\fP if |
| the library file changes. |
| .sp |
| The named target must be created by \fBadd_library()\fP within |
| the project or as an IMPORTED library\&. |
| If it is created within the project an ordering dependency will |
| automatically be added in the build system to make sure the named |
| library target is up\-to\-date before the \fB<target>\fP links. |
| .sp |
| If an imported library has the \fBIMPORTED_NO_SONAME\fP |
| target property set, CMake may ask the linker to search for |
| the library instead of using the full path |
| (e.g. \fB/usr/lib/libfoo.so\fP becomes \fB\-lfoo\fP). |
| .sp |
| The full path to the target\(aqs artifact will be quoted/escaped for |
| the shell automatically. |
| .IP \(bu 2 |
| \fBA full path to a library file\fP: The generated link line will |
| normally preserve the full path to the file. The buildsystem will |
| have a dependency to re\-link \fB<target>\fP if the library file changes. |
| .sp |
| There are some cases where CMake may ask the linker to search for |
| the library (e.g. \fB/usr/lib/libfoo.so\fP becomes \fB\-lfoo\fP), such |
| as when a shared library is detected to have no \fBSONAME\fP field. |
| See policy \fBCMP0060\fP for discussion of another case. |
| .sp |
| If the library file is in a macOS framework, the \fBHeaders\fP directory |
| of the framework will also be processed as a |
| usage requirement\&. This has the same |
| effect as passing the framework directory as an include directory. |
| .sp |
| New in version 3.8: On Visual Studio Generators for VS 2010 and above, library files |
| ending in \fB\&.targets\fP will be treated as MSBuild targets files and |
| imported into generated project files. This is not supported by other |
| generators. |
| |
| .sp |
| The full path to the library file will be quoted/escaped for |
| the shell automatically. |
| .IP \(bu 2 |
| \fBA plain library name\fP: The generated link line will ask the linker |
| to search for the library (e.g. \fBfoo\fP becomes \fB\-lfoo\fP or \fBfoo.lib\fP). |
| .sp |
| The library name/flag is treated as a command\-line string fragment and |
| will be used with no extra quoting or escaping. |
| .IP \(bu 2 |
| \fBA link flag\fP: Item names starting with \fB\-\fP, but not \fB\-l\fP or |
| \fB\-framework\fP, are treated as linker flags. Note that such flags will |
| be treated like any other library link item for purposes of transitive |
| dependencies, so they are generally safe to specify only as private link |
| items that will not propagate to dependents. |
| .sp |
| Link flags specified here are inserted into the link command in the same |
| place as the link libraries. This might not be correct, depending on |
| the linker. Use the \fBLINK_OPTIONS\fP target property or |
| \fBtarget_link_options()\fP command to add link |
| flags explicitly. The flags will then be placed at the toolchain\-defined |
| flag position in the link command. |
| .sp |
| New in version 3.13: \fBLINK_OPTIONS\fP target property and \fBtarget_link_options()\fP |
| command. For earlier versions of CMake, use \fBLINK_FLAGS\fP |
| property instead. |
| |
| .sp |
| The link flag is treated as a command\-line string fragment and |
| will be used with no extra quoting or escaping. |
| .IP \(bu 2 |
| \fBA generator expression\fP: A \fB$<...>\fP \fBgenerator expression\fP may evaluate to any of the above |
| items or to a semicolon\-separated list of them. |
| If the \fB\&...\fP contains any \fB;\fP characters, e.g. after evaluation |
| of a \fB${list}\fP variable, be sure to use an explicitly quoted |
| argument \fB"$<...>"\fP so that this command receives it as a |
| single \fB<item>\fP\&. |
| .sp |
| Additionally, a generator expression may be used as a fragment of |
| any of the above items, e.g. \fBfoo$<1:_d>\fP\&. |
| .sp |
| Note that generator expressions will not be used in OLD handling of |
| policy \fBCMP0003\fP or policy \fBCMP0004\fP\&. |
| .IP \(bu 2 |
| A \fBdebug\fP, \fBoptimized\fP, or \fBgeneral\fP keyword immediately followed |
| by another \fB<item>\fP\&. The item following such a keyword will be used |
| only for the corresponding build configuration. The \fBdebug\fP keyword |
| corresponds to the \fBDebug\fP configuration (or to configurations named |
| in the \fBDEBUG_CONFIGURATIONS\fP global property if it is set). |
| The \fBoptimized\fP keyword corresponds to all other configurations. The |
| \fBgeneral\fP keyword corresponds to all configurations, and is purely |
| optional. Higher granularity may be achieved for per\-configuration |
| rules by creating and linking to |
| IMPORTED library targets\&. |
| These keywords are interpreted immediately by this command and therefore |
| have no special meaning when produced by a generator expression. |
| .UNINDENT |
| .sp |
| Items containing \fB::\fP, such as \fBFoo::Bar\fP, are assumed to be |
| IMPORTED or ALIAS library |
| target names and will cause an error if no such target exists. |
| See policy \fBCMP0028\fP\&. |
| .sp |
| See the \fBcmake\-buildsystem(7)\fP manual for more on defining |
| buildsystem properties. |
| .SS Libraries for a Target and/or its Dependents |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_link_libraries(<target> |
| <PRIVATE|PUBLIC|INTERFACE> <item>... |
| [<PRIVATE|PUBLIC|INTERFACE> <item>...]...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBPUBLIC\fP, \fBPRIVATE\fP and \fBINTERFACE\fP keywords can be used to |
| specify both the link dependencies and the link interface in one command. |
| Libraries and targets following \fBPUBLIC\fP are linked to, and are made |
| part of the link interface. Libraries and targets following \fBPRIVATE\fP |
| are linked to, but are not made part of the link interface. Libraries |
| following \fBINTERFACE\fP are appended to the link interface and are not |
| used for linking \fB<target>\fP\&. |
| .SS Libraries for both a Target and its Dependents |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_link_libraries(<target> <item>...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Library dependencies are transitive by default with this signature. |
| When this target is linked into another target then the libraries |
| linked to this target will appear on the link line for the other |
| target too. This transitive "link interface" is stored in the |
| \fBINTERFACE_LINK_LIBRARIES\fP target property and may be overridden |
| by setting the property directly. When \fBCMP0022\fP is not set to |
| \fBNEW\fP, transitive linking is built in but may be overridden by the |
| \fBLINK_INTERFACE_LIBRARIES\fP property. Calls to other signatures |
| of this command may set the property making any libraries linked |
| exclusively by this signature private. |
| .SS Libraries for a Target and/or its Dependents (Legacy) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_link_libraries(<target> |
| <LINK_PRIVATE|LINK_PUBLIC> <lib>... |
| [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBLINK_PUBLIC\fP and \fBLINK_PRIVATE\fP modes can be used to specify both |
| the link dependencies and the link interface in one command. |
| .sp |
| This signature is for compatibility only. Prefer the \fBPUBLIC\fP or |
| \fBPRIVATE\fP keywords instead. |
| .sp |
| Libraries and targets following \fBLINK_PUBLIC\fP are linked to, and are |
| made part of the \fBINTERFACE_LINK_LIBRARIES\fP\&. If policy |
| \fBCMP0022\fP is not \fBNEW\fP, they are also made part of the |
| \fBLINK_INTERFACE_LIBRARIES\fP\&. Libraries and targets following |
| \fBLINK_PRIVATE\fP are linked to, but are not made part of the |
| \fBINTERFACE_LINK_LIBRARIES\fP (or \fBLINK_INTERFACE_LIBRARIES\fP). |
| .SS Libraries for Dependents Only (Legacy) |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The \fBLINK_INTERFACE_LIBRARIES\fP mode appends the libraries to the |
| \fBINTERFACE_LINK_LIBRARIES\fP target property instead of using them |
| for linking. If policy \fBCMP0022\fP is not \fBNEW\fP, then this mode |
| also appends libraries to the \fBLINK_INTERFACE_LIBRARIES\fP and its |
| per\-configuration equivalent. |
| .sp |
| This signature is for compatibility only. Prefer the \fBINTERFACE\fP mode |
| instead. |
| .sp |
| Libraries specified as \fBdebug\fP are wrapped in a generator expression to |
| correspond to debug builds. If policy \fBCMP0022\fP is |
| not \fBNEW\fP, the libraries are also appended to the |
| \fBLINK_INTERFACE_LIBRARIES_DEBUG\fP |
| property (or to the properties corresponding to configurations listed in |
| the \fBDEBUG_CONFIGURATIONS\fP global property if it is set). |
| Libraries specified as \fBoptimized\fP are appended to the |
| \fBINTERFACE_LINK_LIBRARIES\fP property. If policy \fBCMP0022\fP |
| is not \fBNEW\fP, they are also appended to the |
| \fBLINK_INTERFACE_LIBRARIES\fP property. Libraries specified as |
| \fBgeneral\fP (or without any keyword) are treated as if specified for both |
| \fBdebug\fP and \fBoptimized\fP\&. |
| .SS Linking Object Libraries |
| .sp |
| New in version 3.12. |
| |
| .sp |
| Object Libraries may be used as the \fB<target>\fP (first) argument |
| of \fBtarget_link_libraries\fP to specify dependencies of their sources |
| on other libraries. For example, the code |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(A SHARED a.c) |
| target_compile_definitions(A PUBLIC A) |
| |
| add_library(obj OBJECT obj.c) |
| target_compile_definitions(obj PUBLIC OBJ) |
| target_link_libraries(obj PUBLIC A) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| compiles \fBobj.c\fP with \fB\-DA \-DOBJ\fP and establishes usage requirements |
| for \fBobj\fP that propagate to its dependents. |
| .sp |
| Normal libraries and executables may link to Object Libraries |
| to get their objects and usage requirements. Continuing the above |
| example, the code |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(B SHARED b.c) |
| target_link_libraries(B PUBLIC obj) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| compiles \fBb.c\fP with \fB\-DA \-DOBJ\fP, creates shared library \fBB\fP |
| with object files from \fBb.c\fP and \fBobj.c\fP, and links \fBB\fP to \fBA\fP\&. |
| Furthermore, the code |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_executable(main main.c) |
| target_link_libraries(main B) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| compiles \fBmain.c\fP with \fB\-DA \-DOBJ\fP and links executable \fBmain\fP |
| to \fBB\fP and \fBA\fP\&. The object library\(aqs usage requirements are |
| propagated transitively through \fBB\fP, but its object files are not. |
| .sp |
| Object Libraries may "link" to other object libraries to get |
| usage requirements, but since they do not have a link step nothing |
| is done with their object files. Continuing from the above example, |
| the code: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(obj2 OBJECT obj2.c) |
| target_link_libraries(obj2 PUBLIC obj) |
| |
| add_executable(main2 main2.c) |
| target_link_libraries(main2 obj2) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| compiles \fBobj2.c\fP with \fB\-DA \-DOBJ\fP, creates executable \fBmain2\fP |
| with object files from \fBmain2.c\fP and \fBobj2.c\fP, and links \fBmain2\fP |
| to \fBA\fP\&. |
| .sp |
| In other words, when Object Libraries appear in a target\(aqs |
| \fBINTERFACE_LINK_LIBRARIES\fP property they will be |
| treated as Interface Libraries, but when they appear in |
| a target\(aqs \fBLINK_LIBRARIES\fP property their object files |
| will be included in the link too. |
| .SS Linking Object Libraries via $<TARGET_OBJECTS> |
| .sp |
| New in version 3.21. |
| |
| .sp |
| The object files associated with an object library may be referenced |
| by the \fB$<TARGET_OBJECTS>\fP generator expression. Such object |
| files are placed on the link line \fIbefore\fP all libraries, regardless |
| of their relative order. Additionally, an ordering dependency will be |
| added to the build system to make sure the object library is up\-to\-date |
| before the dependent target links. For example, the code |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(obj3 OBJECT obj3.c) |
| target_compile_definitions(obj3 PUBLIC OBJ3) |
| |
| add_executable(main3 main3.c) |
| target_link_libraries(main3 PRIVATE a3 $<TARGET_OBJECTS:obj3> b3) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| links executable \fBmain3\fP with object files from \fBmain3.c\fP |
| and \fBobj3.c\fP followed by the \fBa3\fP and \fBb3\fP libraries. |
| \fBmain3.c\fP is \fInot\fP compiled with usage requirements from \fBobj3\fP, |
| such as \fB\-DOBJ3\fP\&. |
| .sp |
| This approach can be used to achieve transitive inclusion of object |
| files in link lines as usage requirements. Continuing the above |
| example, the code |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(iface_obj3 INTERFACE) |
| target_link_libraries(iface_obj3 INTERFACE obj3 $<TARGET_OBJECTS:obj3>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| creates an interface library \fBiface_obj3\fP that forwards the \fBobj3\fP |
| usage requirements and adds the \fBobj3\fP object files to dependents\(aq |
| link lines. The code |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_executable(use_obj3 use_obj3.c) |
| target_link_libraries(use_obj3 PRIVATE iface_obj3) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| compiles \fBuse_obj3.c\fP with \fB\-DOBJ3\fP and links executable \fBuse_obj3\fP |
| with object files from \fBuse_obj3.c\fP and \fBobj3.c\fP\&. |
| .sp |
| This also works transitively through a static library. Since a static |
| library does not link, it does not consume the object files from |
| object libraries referenced this way. Instead, the object files |
| become transitive link dependencies of the static library. |
| Continuing the above example, the code |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(static3 STATIC static3.c) |
| target_link_libraries(static3 PRIVATE iface_obj3) |
| |
| add_executable(use_static3 use_static3.c) |
| target_link_libraries(use_static3 PRIVATE static3) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| compiles \fBstatic3.c\fP with \fB\-DOBJ3\fP and creates \fBlibstatic3.a\fP |
| using only its own object file. \fBuse_static3.c\fP is compiled \fIwithout\fP |
| \fB\-DOBJ3\fP because the usage requirement is not transitive through |
| the private dependency of \fBstatic3\fP\&. However, the link dependencies |
| of \fBstatic3\fP are propagated, including the \fBiface_obj3\fP reference |
| to \fB$<TARGET_OBJECTS:obj3>\fP\&. The \fBuse_static3\fP executable is |
| created with object files from \fBuse_static3.c\fP and \fBobj3.c\fP, and |
| linked to library \fBlibstatic3.a\fP\&. |
| .sp |
| When using this approach, it is the project\(aqs responsibility to avoid |
| linking multiple dependent binaries to \fBiface_obj3\fP, because they will |
| all get the \fBobj3\fP object files on their link lines. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Referencing \fB$<TARGET_OBJECTS>\fP in \fBtarget_link_libraries\fP |
| calls worked in versions of CMake prior to 3.21 for some cases, |
| but was not fully supported: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| It did not place the object files before libraries on link lines. |
| .IP \(bu 2 |
| It did not add an ordering dependency on the object library. |
| .IP \(bu 2 |
| It did not work in Xcode with multiple architectures. |
| .UNINDENT |
| .UNINDENT |
| .UNINDENT |
| .SS Cyclic Dependencies of Static Libraries |
| .sp |
| The library dependency graph is normally acyclic (a DAG), but in the case |
| of mutually\-dependent \fBSTATIC\fP libraries CMake allows the graph to |
| contain cycles (strongly connected components). When another target links |
| to one of the libraries, CMake repeats the entire connected component. |
| For example, the code |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_library(A STATIC a.c) |
| add_library(B STATIC b.c) |
| target_link_libraries(A B) |
| target_link_libraries(B A) |
| add_executable(main main.c) |
| target_link_libraries(main A) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| links \fBmain\fP to \fBA B A B\fP\&. While one repetition is usually |
| sufficient, pathological object file and symbol arrangements can require |
| more. One may handle such cases by using the |
| \fBLINK_INTERFACE_MULTIPLICITY\fP target property or by manually |
| repeating the component in the last \fBtarget_link_libraries\fP call. |
| However, if two archives are really so interdependent they should probably |
| be combined into a single archive, perhaps by using Object Libraries\&. |
| .SS Creating Relocatable Packages |
| .sp |
| Note that it is not advisable to populate the |
| \fBINTERFACE_LINK_LIBRARIES\fP of a target with absolute paths to dependencies. |
| That would hard\-code into installed packages the library file paths |
| for dependencies \fBas found on the machine the package was made on\fP\&. |
| .sp |
| See the Creating Relocatable Packages section of the |
| \fBcmake\-packages(7)\fP manual for discussion of additional care |
| that must be taken when specifying usage requirements while creating |
| packages for redistribution. |
| .SS target_link_options |
| .sp |
| New in version 3.13. |
| |
| .sp |
| Add options to the link step for an executable, shared library or module |
| library target. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_link_options(<target> [BEFORE] |
| <INTERFACE|PUBLIC|PRIVATE> [items1...] |
| [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The named \fB<target>\fP must have been created by a command such as |
| \fBadd_executable()\fP or \fBadd_library()\fP and must not be an |
| ALIAS target\&. |
| .sp |
| This command can be used to add any link options, but alternative commands |
| exist to add libraries (\fBtarget_link_libraries()\fP or |
| \fBlink_libraries()\fP). See documentation of the |
| \fBdirectory\fP and |
| \fBtarget\fP \fBLINK_OPTIONS\fP properties. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| This command cannot be used to add options for static library targets, |
| since they do not use a linker. To add archiver or MSVC librarian flags, |
| see the \fBSTATIC_LIBRARY_OPTIONS\fP target property. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If \fBBEFORE\fP is specified, the content will be prepended to the property |
| instead of being appended. |
| .sp |
| The \fBINTERFACE\fP, \fBPUBLIC\fP and \fBPRIVATE\fP keywords are required to |
| specify the scope of the following arguments. \fBPRIVATE\fP and \fBPUBLIC\fP |
| items will populate the \fBLINK_OPTIONS\fP property of |
| \fB<target>\fP\&. \fBPUBLIC\fP and \fBINTERFACE\fP items will populate the |
| \fBINTERFACE_LINK_OPTIONS\fP property of \fB<target>\fP\&. |
| The following arguments specify link options. Repeated calls for the same |
| \fB<target>\fP append items in the order called. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| IMPORTED targets only support \fBINTERFACE\fP items. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Arguments to \fBtarget_link_options\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. See the \fBcmake\-buildsystem(7)\fP |
| manual for more on defining buildsystem properties. |
| .SS Host And Device Specific Link Options |
| .sp |
| New in version 3.18: When a device link step is involved, which is controlled by |
| \fBCUDA_SEPARABLE_COMPILATION\fP and |
| \fBCUDA_RESOLVE_DEVICE_SYMBOLS\fP properties and policy \fBCMP0105\fP, |
| the raw options will be delivered to the host and device link steps (wrapped in |
| \fB\-Xcompiler\fP or equivalent for device link). Options wrapped with |
| \fB$<DEVICE_LINK:...>\fP |
| \fBgenerator expression\fP will be used |
| only for the device link step. Options wrapped with \fB$<HOST_LINK:...>\fP |
| \fBgenerator expression\fP will be used |
| only for the host link step. |
| |
| .SS Option De\-duplication |
| .sp |
| The final set of options used for a target is constructed by |
| accumulating options from the current target and the usage requirements of |
| its dependencies. The set of options is de\-duplicated to avoid repetition. |
| .sp |
| New in version 3.12: While beneficial for individual options, the de\-duplication step can break |
| up option groups. For example, \fB\-option A \-option B\fP becomes |
| \fB\-option A B\fP\&. One may specify a group of options using shell\-like |
| quoting along with a \fBSHELL:\fP prefix. The \fBSHELL:\fP prefix is dropped, |
| and the rest of the option string is parsed using the |
| \fBseparate_arguments()\fP \fBUNIX_COMMAND\fP mode. For example, |
| \fB"SHELL:\-option A" "SHELL:\-option B"\fP becomes \fB\-option A \-option B\fP\&. |
| |
| .SS Handling Compiler Driver Differences |
| .sp |
| To pass options to the linker tool, each compiler driver has its own syntax. |
| The \fBLINKER:\fP prefix and \fB,\fP separator can be used to specify, in a portable |
| way, options to pass to the linker tool. \fBLINKER:\fP is replaced by the |
| appropriate driver option and \fB,\fP by the appropriate driver separator. |
| The driver prefix and driver separator are given by the values of the |
| \fBCMAKE_<LANG>_LINKER_WRAPPER_FLAG\fP and |
| \fBCMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP\fP variables. |
| .sp |
| For example, \fB"LINKER:\-z,defs"\fP becomes \fB\-Xlinker \-z \-Xlinker defs\fP for |
| \fBClang\fP and \fB\-Wl,\-z,defs\fP for \fBGNU GCC\fP\&. |
| .sp |
| The \fBLINKER:\fP prefix can be specified as part of a \fBSHELL:\fP prefix |
| expression. |
| .sp |
| The \fBLINKER:\fP prefix supports, as an alternative syntax, specification of |
| arguments using the \fBSHELL:\fP prefix and space as separator. The previous |
| example then becomes \fB"LINKER:SHELL:\-z defs"\fP\&. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Specifying the \fBSHELL:\fP prefix anywhere other than at the beginning of the |
| \fBLINKER:\fP prefix is not supported. |
| .UNINDENT |
| .UNINDENT |
| .SS target_precompile_headers |
| .sp |
| New in version 3.16. |
| |
| .sp |
| Add a list of header files to precompile. |
| .sp |
| Precompiling header files can speed up compilation by creating a partially |
| processed version of some header files, and then using that version during |
| compilations rather than repeatedly parsing the original headers. |
| .SS Main Form |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_precompile_headers(<target> |
| <INTERFACE|PUBLIC|PRIVATE> [header1...] |
| [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The command adds header files to the \fBPRECOMPILE_HEADERS\fP and/or |
| \fBINTERFACE_PRECOMPILE_HEADERS\fP target properties of \fB<target>\fP\&. |
| The named \fB<target>\fP must have been created by a command such as |
| \fBadd_executable()\fP or \fBadd_library()\fP and must not be an |
| ALIAS target\&. |
| .sp |
| The \fBINTERFACE\fP, \fBPUBLIC\fP and \fBPRIVATE\fP keywords are required to |
| specify the scope of the following arguments. \fBPRIVATE\fP and \fBPUBLIC\fP |
| items will populate the \fBPRECOMPILE_HEADERS\fP property of |
| \fB<target>\fP\&. \fBPUBLIC\fP and \fBINTERFACE\fP items will populate the |
| \fBINTERFACE_PRECOMPILE_HEADERS\fP property of \fB<target>\fP |
| (IMPORTED targets only support \fBINTERFACE\fP items). |
| Repeated calls for the same \fB<target>\fP will append items in the order called. |
| .sp |
| Projects should generally avoid using \fBPUBLIC\fP or \fBINTERFACE\fP for targets |
| that will be exported, or they should at least use |
| the \fB$<BUILD_INTERFACE:...>\fP generator expression to prevent precompile |
| headers from appearing in an installed exported target. Consumers of a target |
| should typically be in control of what precompile headers they use, not have |
| precompile headers forced on them by the targets being consumed (since |
| precompile headers are not typically usage requirements). A notable exception |
| to this is where an interface library is created |
| to define a commonly used set of precompile headers in one place and then other |
| targets link to that interface library privately. In this case, the interface |
| library exists specifically to propagate the precompile headers to its |
| consumers and the consumer is effectively still in control, since it decides |
| whether to link to the interface library or not. |
| .sp |
| The list of header files is used to generate a header file named |
| \fBcmake_pch.h|xx\fP which is used to generate the precompiled header file |
| (\fB\&.pch\fP, \fB\&.gch\fP, \fB\&.pchi\fP) artifact. The \fBcmake_pch.h|xx\fP header |
| file will be force included (\fB\-include\fP for GCC, \fB/FI\fP for MSVC) to |
| all source files, so sources do not need to have \fB#include "pch.h"\fP\&. |
| .sp |
| Header file names specified with angle brackets (e.g. \fB<unordered_map>\fP) or |
| explicit double quotes (escaped for the \fBcmake\-language(7)\fP, |
| e.g. \fB[["other_header.h"]]\fP) will be treated as is, and include directories |
| must be available for the compiler to find them. Other header file names |
| (e.g. \fBproject_header.h\fP) are interpreted as being relative to the current |
| source directory (e.g. \fBCMAKE_CURRENT_SOURCE_DIR\fP) and will be |
| included by absolute path. For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_precompile_headers(myTarget |
| PUBLIC |
| project_header.h |
| PRIVATE |
| [["other_header.h"]] |
| <unordered_map> |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Arguments to \fBtarget_precompile_headers()\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. |
| See the \fBcmake\-generator\-expressions(7)\fP manual for available |
| expressions. |
| The \fB$<COMPILE_LANGUAGE:...>\fP generator expression is particularly |
| useful for specifying a language\-specific header to precompile for |
| only one language (e.g. \fBCXX\fP and not \fBC\fP). In this case, header |
| file names that are not explicitly in double quotes or angle brackets |
| must be specified by absolute path. Also, when specifying angle brackets |
| inside a generator expression, be sure to encode the closing \fB>\fP as |
| \fB$<ANGLE\-R>\fP\&. For example: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_precompile_headers(mylib PRIVATE |
| "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/cxx_only.h>" |
| "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE\-R>>" |
| "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE\-R>>" |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Reusing Precompile Headers |
| .sp |
| The command also supports a second signature which can be used to specify that |
| one target re\-uses a precompiled header file artifact from another target |
| instead of generating its own: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_precompile_headers(<target> REUSE_FROM <other_target>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This form sets the \fBPRECOMPILE_HEADERS_REUSE_FROM\fP property to |
| \fB<other_target>\fP and adds a dependency such that \fB<target>\fP will depend |
| on \fB<other_target>\fP\&. CMake will halt with an error if the |
| \fBPRECOMPILE_HEADERS\fP property of \fB<target>\fP is already set when |
| the \fBREUSE_FROM\fP form is used. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The \fBREUSE_FROM\fP form requires the same set of compiler options, |
| compiler flags and compiler definitions for both \fB<target>\fP and |
| \fB<other_target>\fP\&. Some compilers (e.g. GCC) may issue a warning if the |
| precompiled header file cannot be used (\fB\-Winvalid\-pch\fP). |
| .UNINDENT |
| .UNINDENT |
| .SS See Also |
| .sp |
| To disable precompile headers for specific targets, see the |
| \fBDISABLE_PRECOMPILE_HEADERS\fP target property. |
| .sp |
| To prevent precompile headers from being used when compiling a specific |
| source file, see the \fBSKIP_PRECOMPILE_HEADERS\fP source file property. |
| .SS target_sources |
| .sp |
| New in version 3.1. |
| |
| .sp |
| Add sources to a target. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_sources(<target> |
| <INTERFACE|PUBLIC|PRIVATE> [items1...] |
| [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Specifies sources to use when building a target and/or its dependents. |
| The named \fB<target>\fP must have been created by a command such as |
| \fBadd_executable()\fP or \fBadd_library()\fP or |
| \fBadd_custom_target()\fP and must not be an |
| ALIAS target\&. The \fB<items>\fP may use |
| \fBgenerator expressions\fP\&. |
| .sp |
| New in version 3.20: \fB<target>\fP can be a custom target. |
| |
| .sp |
| The \fBINTERFACE\fP, \fBPUBLIC\fP and \fBPRIVATE\fP keywords are required to |
| specify the scope of the source file paths (\fB<items>\fP) that follow |
| them. \fBPRIVATE\fP and \fBPUBLIC\fP items will populate the \fBSOURCES\fP |
| property of \fB<target>\fP, which are used when building the target itself. |
| \fBPUBLIC\fP and \fBINTERFACE\fP items will populate the |
| \fBINTERFACE_SOURCES\fP property of \fB<target>\fP, which are used |
| when building dependents. A target created by \fBadd_custom_target()\fP |
| can only have \fBPRIVATE\fP scope. |
| .sp |
| Repeated calls for the same \fB<target>\fP append items in the order called. |
| .sp |
| New in version 3.3: Allow exporting targets with \fBINTERFACE_SOURCES\fP\&. |
| |
| .sp |
| New in version 3.11: Allow setting \fBINTERFACE\fP items on |
| IMPORTED targets\&. |
| |
| .sp |
| Changed in version 3.13: Relative source file paths are interpreted as being relative to the current |
| source directory (i.e. \fBCMAKE_CURRENT_SOURCE_DIR\fP). |
| See policy \fBCMP0076\fP\&. |
| |
| .sp |
| A path that begins with a generator expression is left unmodified. |
| When a target\(aqs \fBSOURCE_DIR\fP property differs from |
| \fBCMAKE_CURRENT_SOURCE_DIR\fP, use absolute paths in generator |
| expressions to ensure the sources are correctly assigned to the target. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| # WRONG: starts with generator expression, but relative path used |
| target_sources(MyTarget "$<$<CONFIG:Debug>:dbgsrc.cpp>") |
| |
| # CORRECT: absolute path used inside the generator expression |
| target_sources(MyTarget "$<$<CONFIG:Debug>:${CMAKE_CURRENT_SOURCE_DIR}/dbgsrc.cpp>") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| See the \fBcmake\-buildsystem(7)\fP manual for more on defining |
| buildsystem properties. |
| .SS File Sets |
| .sp |
| New in version 3.23. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| target_sources(<target> |
| [<INTERFACE|PUBLIC|PRIVATE> |
| [FILE_SET <set> [TYPE <type>] [BASE_DIRS <dirs>...] [FILES <files>...]]... |
| ]...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Adds a file set to a target, or adds files to an existing file set. Targets |
| have zero or more named file sets. Each file set has a name, a type, a scope of |
| \fBINTERFACE\fP, \fBPUBLIC\fP, or \fBPRIVATE\fP, one or more base directories, and |
| files within those directories. The only acceptable type is \fBHEADERS\fP\&. The |
| optional default file sets are named after their type. The target may not be a |
| custom target or \fBFRAMEWORK\fP target. |
| .sp |
| Files in a \fBPRIVATE\fP or \fBPUBLIC\fP file set are marked as source files for |
| the purposes of IDE integration. Additionally, files in \fBHEADERS\fP file sets |
| have their \fBHEADER_FILE_ONLY\fP property set to \fBTRUE\fP\&. Files in an |
| \fBINTERFACE\fP or \fBPUBLIC\fP file set can be installed with the |
| \fBinstall(TARGETS)\fP command, and exported with the |
| \fBinstall(EXPORT)\fP and \fBexport()\fP commands. |
| .sp |
| Each \fBtarget_sources(FILE_SET)\fP entry starts with \fBINTERFACE\fP, \fBPUBLIC\fP, or |
| \fBPRIVATE\fP and accepts the following arguments: |
| .sp |
| \fBFILE_SET <set>\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| The name of the file set to create or add to. It must contain only letters, |
| numbers and underscores. Names starting with a capital letter are reserved |
| for built\-in file sets predefined by CMake. The only predefined set name is |
| \fBHEADERS\fP\&. All other set names must not start with a capital letter or |
| underscore. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBTYPE <type>\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| Every file set is associated with a particular type of file. \fBHEADERS\fP |
| is currently the only defined type and it is an error to specify anything |
| else. As a special case, if the name of the file set is \fBHEADERS\fP, the |
| type does not need to be specified and the \fBTYPE <type>\fP arguments can be |
| omitted. For all other file set names, \fBTYPE\fP is required. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBBASE_DIRS <dirs>...\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| An optional list of base directories of the file set. Any relative path |
| is treated as relative to the current source directory |
| (i.e. \fBCMAKE_CURRENT_SOURCE_DIR\fP). If no \fBBASE_DIRS\fP are |
| specified when the file set is first created, the value of |
| \fBCMAKE_CURRENT_SOURCE_DIR\fP is added. This argument supports |
| \fBgenerator expressions\fP\&. |
| .sp |
| No two base directories for a file set may be sub\-directories of each other. |
| This requirement must be met across all base directories added to a file set, |
| not just those within a single call to \fBtarget_sources()\fP\&. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBFILES <files>...\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| An optional list of files to add to the file set. Each file must be in |
| one of the base directories, or a subdirectory of one of the base |
| directories. This argument supports |
| \fBgenerator expressions\fP\&. |
| .sp |
| If relative paths are specified, they are considered relative to |
| \fBCMAKE_CURRENT_SOURCE_DIR\fP at the time \fBtarget_sources()\fP is |
| called. An exception to this is a path starting with \fB$<\fP\&. Such paths |
| are treated as relative to the target\(aqs source directory after evaluation |
| of generator expressions. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The following target properties are set by \fBtarget_sources(FILE_SET)\fP, |
| but they should not generally be manipulated directly: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBHEADER_SETS\fP |
| .IP \(bu 2 |
| \fBINTERFACE_HEADER_SETS\fP |
| .IP \(bu 2 |
| \fBHEADER_SET\fP |
| .IP \(bu 2 |
| \fBHEADER_SET_<NAME>\fP |
| .IP \(bu 2 |
| \fBHEADER_DIRS\fP |
| .IP \(bu 2 |
| \fBHEADER_DIRS_<NAME>\fP |
| .UNINDENT |
| .sp |
| Target properties related to include directories are also modified by |
| \fBtarget_sources(FILE_SET)\fP as follows: |
| .sp |
| \fBINCLUDE_DIRECTORIES\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| If the \fBTYPE\fP is \fBHEADERS\fP, and the scope of the file set is \fBPRIVATE\fP |
| or \fBPUBLIC\fP, all of the \fBBASE_DIRS\fP of the file set are wrapped in |
| \fB$<BUILD_INTERFACE>\fP and appended to this property. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| \fBINTERFACE_INCLUDE_DIRECTORIES\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| If the \fBTYPE\fP is \fBHEADERS\fP, and the scope of the file set is |
| \fBINTERFACE\fP or \fBPUBLIC\fP, all of the \fBBASE_DIRS\fP of the file set are |
| wrapped in \fB$<BUILD_INTERFACE>\fP and appended to this property. |
| .UNINDENT |
| .UNINDENT |
| .SS try_compile |
| .sp |
| Try building some code. |
| .SS Try Compiling Whole Projects |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| try_compile(<resultVar> <bindir> <srcdir> |
| <projectName> [<targetName>] [CMAKE_FLAGS <flags>...] |
| [OUTPUT_VARIABLE <var>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Try building a project. The success or failure of the \fBtry_compile\fP, |
| i.e. \fBTRUE\fP or \fBFALSE\fP respectively, is returned in \fB<resultVar>\fP\&. |
| .sp |
| In this form, \fB<srcdir>\fP should contain a complete CMake project with a |
| \fBCMakeLists.txt\fP file and all sources. The \fB<bindir>\fP and \fB<srcdir>\fP |
| will not be deleted after this command is run. Specify \fB<targetName>\fP to |
| build a specific target instead of the \fBall\fP or \fBALL_BUILD\fP target. See |
| below for the meaning of other options. |
| .SS Try Compiling Source Files |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...> |
| [CMAKE_FLAGS <flags>...] |
| [COMPILE_DEFINITIONS <defs>...] |
| [LINK_OPTIONS <options>...] |
| [LINK_LIBRARIES <libs>...] |
| [OUTPUT_VARIABLE <var>] |
| [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]] |
| [<LANG>_STANDARD <std>] |
| [<LANG>_STANDARD_REQUIRED <bool>] |
| [<LANG>_EXTENSIONS <bool>] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Try building an executable or static library from one or more source files |
| (which one is determined by the \fBCMAKE_TRY_COMPILE_TARGET_TYPE\fP |
| variable). The success or failure of the \fBtry_compile\fP, i.e. \fBTRUE\fP or |
| \fBFALSE\fP respectively, is returned in \fB<resultVar>\fP\&. |
| .sp |
| In this form, one or more source files must be provided. If |
| \fBCMAKE_TRY_COMPILE_TARGET_TYPE\fP is unset or is set to \fBEXECUTABLE\fP, |
| the sources must include a definition for \fBmain\fP and CMake will create a |
| \fBCMakeLists.txt\fP file to build the source(s) as an executable. |
| If \fBCMAKE_TRY_COMPILE_TARGET_TYPE\fP is set to \fBSTATIC_LIBRARY\fP, |
| a static library will be built instead and no definition for \fBmain\fP is |
| required. For an executable, the generated \fBCMakeLists.txt\fP file would |
| contain something like the following: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| add_definitions(<expanded COMPILE_DEFINITIONS from caller>) |
| include_directories(${INCLUDE_DIRECTORIES}) |
| link_directories(${LINK_DIRECTORIES}) |
| add_executable(cmTryCompileExec <srcfile>...) |
| target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>) |
| target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES}) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_FLAGS <flags>...\fP |
| Specify flags of the form \fB\-DVAR:TYPE=VALUE\fP to be passed to |
| the \fBcmake\fP command\-line used to drive the test build. |
| The above example shows how values for variables |
| \fBINCLUDE_DIRECTORIES\fP, \fBLINK_DIRECTORIES\fP, and \fBLINK_LIBRARIES\fP |
| are used. |
| .TP |
| .B \fBCOMPILE_DEFINITIONS <defs>...\fP |
| Specify \fB\-Ddefinition\fP arguments to pass to \fBadd_definitions()\fP |
| in the generated test project. |
| .TP |
| .B \fBCOPY_FILE <fileName>\fP |
| Copy the built executable or static library to the given \fB<fileName>\fP\&. |
| .TP |
| .B \fBCOPY_FILE_ERROR <var>\fP |
| Use after \fBCOPY_FILE\fP to capture into variable \fB<var>\fP any error |
| message encountered while trying to copy the file. |
| .TP |
| .B \fBLINK_LIBRARIES <libs>...\fP |
| Specify libraries to be linked in the generated project. |
| The list of libraries may refer to system libraries and to |
| Imported Targets from the calling project. |
| .sp |
| If this option is specified, any \fB\-DLINK_LIBRARIES=...\fP value |
| given to the \fBCMAKE_FLAGS\fP option will be ignored. |
| .TP |
| .B \fBLINK_OPTIONS <options>...\fP |
| New in version 3.14. |
| |
| .sp |
| Specify link step options to pass to \fBtarget_link_options()\fP or to |
| set the \fBSTATIC_LIBRARY_OPTIONS\fP target property in the generated |
| project, depending on the \fBCMAKE_TRY_COMPILE_TARGET_TYPE\fP variable. |
| .TP |
| .B \fBOUTPUT_VARIABLE <var>\fP |
| Store the output from the build process in the given variable. |
| .TP |
| .B \fB<LANG>_STANDARD <std>\fP |
| New in version 3.8. |
| |
| .sp |
| Specify the \fBC_STANDARD\fP, \fBCXX_STANDARD\fP, |
| \fBOBJC_STANDARD\fP, \fBOBJCXX_STANDARD\fP, |
| or \fBCUDA_STANDARD\fP target property of the generated project. |
| .TP |
| .B \fB<LANG>_STANDARD_REQUIRED <bool>\fP |
| New in version 3.8. |
| |
| .sp |
| Specify the \fBC_STANDARD_REQUIRED\fP, |
| \fBCXX_STANDARD_REQUIRED\fP, \fBOBJC_STANDARD_REQUIRED\fP, |
| \fBOBJCXX_STANDARD_REQUIRED\fP,or \fBCUDA_STANDARD_REQUIRED\fP |
| target property of the generated project. |
| .TP |
| .B \fB<LANG>_EXTENSIONS <bool>\fP |
| New in version 3.8. |
| |
| .sp |
| Specify the \fBC_EXTENSIONS\fP, \fBCXX_EXTENSIONS\fP, |
| \fBOBJC_EXTENSIONS\fP, \fBOBJCXX_EXTENSIONS\fP, |
| or \fBCUDA_EXTENSIONS\fP target property of the generated project. |
| .UNINDENT |
| .sp |
| In this version all files in \fB<bindir>/CMakeFiles/CMakeTmp\fP will be |
| cleaned automatically. For debugging, \fB\-\-debug\-trycompile\fP can be |
| passed to \fBcmake\fP to avoid this clean. However, multiple sequential |
| \fBtry_compile\fP operations reuse this single output directory. If you use |
| \fB\-\-debug\-trycompile\fP, you can only debug one \fBtry_compile\fP call at a time. |
| The recommended procedure is to protect all \fBtry_compile\fP calls in your |
| project by \fBif(NOT DEFINED <resultVar>)\fP logic, configure with cmake |
| all the way through once, then delete the cache entry associated with |
| the try_compile call of interest, and then re\-run cmake again with |
| \fB\-\-debug\-trycompile\fP\&. |
| .SS Other Behavior Settings |
| .sp |
| New in version 3.4: If set, the following variables are passed in to the generated |
| try_compile CMakeLists.txt to initialize compile target properties with |
| default values: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCMAKE_CUDA_RUNTIME_LIBRARY\fP |
| .IP \(bu 2 |
| \fBCMAKE_ENABLE_EXPORTS\fP |
| .IP \(bu 2 |
| \fBCMAKE_LINK_SEARCH_START_STATIC\fP |
| .IP \(bu 2 |
| \fBCMAKE_LINK_SEARCH_END_STATIC\fP |
| .IP \(bu 2 |
| \fBCMAKE_MSVC_RUNTIME_LIBRARY\fP |
| .IP \(bu 2 |
| \fBCMAKE_POSITION_INDEPENDENT_CODE\fP |
| .UNINDENT |
| .sp |
| If \fBCMP0056\fP is set to \fBNEW\fP, then |
| \fBCMAKE_EXE_LINKER_FLAGS\fP is passed in as well. |
| |
| .sp |
| Changed in version 3.14: If \fBCMP0083\fP is set to \fBNEW\fP, then in order to obtain correct |
| behavior at link time, the \fBcheck_pie_supported()\fP command from the |
| \fBCheckPIESupported\fP module must be called before using the |
| \fI\%try_compile()\fP command. |
| |
| .sp |
| The current settings of \fBCMP0065\fP and \fBCMP0083\fP are propagated |
| through to the generated test project. |
| .sp |
| Set the \fBCMAKE_TRY_COMPILE_CONFIGURATION\fP variable to choose |
| a build configuration. |
| .sp |
| New in version 3.6: Set the \fBCMAKE_TRY_COMPILE_TARGET_TYPE\fP variable to specify |
| the type of target used for the source file signature. |
| |
| .sp |
| New in version 3.6: Set the \fBCMAKE_TRY_COMPILE_PLATFORM_VARIABLES\fP variable to specify |
| variables that must be propagated into the test project. This variable is |
| meant for use only in toolchain files and is only honored by the |
| \fBtry_compile()\fP command for the source files form, not when given a whole |
| project. |
| |
| .sp |
| Changed in version 3.8: If \fBCMP0067\fP is set to \fBNEW\fP, or any of the \fB<LANG>_STANDARD\fP, |
| \fB<LANG>_STANDARD_REQUIRED\fP, or \fB<LANG>_EXTENSIONS\fP options are used, |
| then the language standard variables are honored: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCMAKE_C_STANDARD\fP |
| .IP \(bu 2 |
| \fBCMAKE_C_STANDARD_REQUIRED\fP |
| .IP \(bu 2 |
| \fBCMAKE_C_EXTENSIONS\fP |
| .IP \(bu 2 |
| \fBCMAKE_CXX_STANDARD\fP |
| .IP \(bu 2 |
| \fBCMAKE_CXX_STANDARD_REQUIRED\fP |
| .IP \(bu 2 |
| \fBCMAKE_CXX_EXTENSIONS\fP |
| .IP \(bu 2 |
| \fBCMAKE_OBJC_STANDARD\fP |
| .IP \(bu 2 |
| \fBCMAKE_OBJC_STANDARD_REQUIRED\fP |
| .IP \(bu 2 |
| \fBCMAKE_OBJC_EXTENSIONS\fP |
| .IP \(bu 2 |
| \fBCMAKE_OBJCXX_STANDARD\fP |
| .IP \(bu 2 |
| \fBCMAKE_OBJCXX_STANDARD_REQUIRED\fP |
| .IP \(bu 2 |
| \fBCMAKE_OBJCXX_EXTENSIONS\fP |
| .IP \(bu 2 |
| \fBCMAKE_CUDA_STANDARD\fP |
| .IP \(bu 2 |
| \fBCMAKE_CUDA_STANDARD_REQUIRED\fP |
| .IP \(bu 2 |
| \fBCMAKE_CUDA_EXTENSIONS\fP |
| .UNINDENT |
| .sp |
| Their values are used to set the corresponding target properties in |
| the generated project (unless overridden by an explicit option). |
| |
| .sp |
| Changed in version 3.14: For the \fBGreen Hills MULTI\fP generator the GHS toolset and target |
| system customization cache variables are also propagated into the test project. |
| |
| .SS try_run |
| .sp |
| Try compiling and then running some code. |
| .SS Try Compiling and Running Source Files |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| try_run(<runResultVar> <compileResultVar> |
| <bindir> <srcfile> [CMAKE_FLAGS <flags>...] |
| [COMPILE_DEFINITIONS <defs>...] |
| [LINK_OPTIONS <options>...] |
| [LINK_LIBRARIES <libs>...] |
| [COMPILE_OUTPUT_VARIABLE <var>] |
| [RUN_OUTPUT_VARIABLE <var>] |
| [OUTPUT_VARIABLE <var>] |
| [WORKING_DIRECTORY <var>] |
| [ARGS <args>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Try compiling a \fB<srcfile>\fP\&. Returns \fBTRUE\fP or \fBFALSE\fP for success |
| or failure in \fB<compileResultVar>\fP\&. If the compile succeeded, runs the |
| executable and returns its exit code in \fB<runResultVar>\fP\&. If the |
| executable was built, but failed to run, then \fB<runResultVar>\fP will be |
| set to \fBFAILED_TO_RUN\fP\&. See the \fBtry_compile()\fP command for |
| information on how the test project is constructed to build the source file. |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_FLAGS <flags>...\fP |
| Specify flags of the form \fB\-DVAR:TYPE=VALUE\fP to be passed to |
| the \fBcmake\fP command\-line used to drive the test build. |
| The example in \fBtry_compile()\fP shows how values for variables |
| \fBINCLUDE_DIRECTORIES\fP, \fBLINK_DIRECTORIES\fP, and \fBLINK_LIBRARIES\fP |
| are used. |
| .TP |
| .B \fBCOMPILE_DEFINITIONS <defs>...\fP |
| Specify \fB\-Ddefinition\fP arguments to pass to \fBadd_definitions()\fP |
| in the generated test project. |
| .TP |
| .B \fBCOMPILE_OUTPUT_VARIABLE <var>\fP |
| Report the compile step build output in a given variable. |
| .TP |
| .B \fBLINK_LIBRARIES <libs>...\fP |
| New in version 3.2. |
| |
| .sp |
| Specify libraries to be linked in the generated project. |
| The list of libraries may refer to system libraries and to |
| Imported Targets from the calling project. |
| .sp |
| If this option is specified, any \fB\-DLINK_LIBRARIES=...\fP value |
| given to the \fBCMAKE_FLAGS\fP option will be ignored. |
| .TP |
| .B \fBLINK_OPTIONS <options>...\fP |
| New in version 3.14. |
| |
| .sp |
| Specify link step options to pass to \fBtarget_link_options()\fP in the |
| generated project. |
| .TP |
| .B \fBOUTPUT_VARIABLE <var>\fP |
| Report the compile build output and the output from running the executable |
| in the given variable. This option exists for legacy reasons. Prefer |
| \fBCOMPILE_OUTPUT_VARIABLE\fP and \fBRUN_OUTPUT_VARIABLE\fP instead. |
| .TP |
| .B \fBRUN_OUTPUT_VARIABLE <var>\fP |
| Report the output from running the executable in a given variable. |
| .TP |
| .B \fBWORKING_DIRECTORY <var>\fP |
| New in version 3.20. |
| |
| .sp |
| Run the executable in the given directory. If no \fBWORKING_DIRECTORY\fP is |
| specified, the executable will run in \fB<bindir>\fP\&. |
| .UNINDENT |
| .SS Other Behavior Settings |
| .sp |
| Set the \fBCMAKE_TRY_COMPILE_CONFIGURATION\fP variable to choose |
| a build configuration. |
| .SS Behavior when Cross Compiling |
| .sp |
| New in version 3.3: Use \fBCMAKE_CROSSCOMPILING_EMULATOR\fP when running cross\-compiled |
| binaries. |
| |
| .sp |
| When cross compiling, the executable compiled in the first step |
| usually cannot be run on the build host. The \fBtry_run\fP command checks |
| the \fBCMAKE_CROSSCOMPILING\fP variable to detect whether CMake is in |
| cross\-compiling mode. If that is the case, it will still try to compile |
| the executable, but it will not try to run the executable unless the |
| \fBCMAKE_CROSSCOMPILING_EMULATOR\fP variable is set. Instead it |
| will create cache variables which must be filled by the user or by |
| presetting them in some CMake script file to the values the executable |
| would have produced if it had been run on its actual target platform. |
| These cache entries are: |
| .INDENT 0.0 |
| .TP |
| .B \fB<runResultVar>\fP |
| Exit code if the executable were to be run on the target platform. |
| .TP |
| .B \fB<runResultVar>__TRYRUN_OUTPUT\fP |
| Output from stdout and stderr if the executable were to be run on |
| the target platform. This is created only if the |
| \fBRUN_OUTPUT_VARIABLE\fP or \fBOUTPUT_VARIABLE\fP option was used. |
| .UNINDENT |
| .sp |
| In order to make cross compiling your project easier, use \fBtry_run\fP |
| only if really required. If you use \fBtry_run\fP, use the |
| \fBRUN_OUTPUT_VARIABLE\fP or \fBOUTPUT_VARIABLE\fP options only if really |
| required. Using them will require that when cross\-compiling, the cache |
| variables will have to be set manually to the output of the executable. |
| You can also "guard" the calls to \fBtry_run\fP with an \fBif()\fP |
| block checking the \fBCMAKE_CROSSCOMPILING\fP variable and |
| provide an easy\-to\-preset alternative for this case. |
| .SH CTEST COMMANDS |
| .sp |
| These commands are available only in CTest scripts. |
| .SS ctest_build |
| .sp |
| Perform the CTest Build Step as a Dashboard Client\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_build([BUILD <build\-dir>] [APPEND] |
| [CONFIGURATION <config>] |
| [PARALLEL_LEVEL <parallel>] |
| [FLAGS <flags>] |
| [PROJECT_NAME <project\-name>] |
| [TARGET <target\-name>] |
| [NUMBER_ERRORS <num\-err\-var>] |
| [NUMBER_WARNINGS <num\-warn\-var>] |
| [RETURN_VALUE <result\-var>] |
| [CAPTURE_CMAKE_ERROR <result\-var>] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Build the project and store results in \fBBuild.xml\fP |
| for submission with the \fBctest_submit()\fP command. |
| .sp |
| The \fBCTEST_BUILD_COMMAND\fP variable may be set to explicitly |
| specify the build command line. Otherwise the build command line is |
| computed automatically based on the options given. |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBBUILD <build\-dir>\fP |
| Specify the top\-level build directory. If not given, the |
| \fBCTEST_BINARY_DIRECTORY\fP variable is used. |
| .TP |
| .B \fBAPPEND\fP |
| Mark \fBBuild.xml\fP for append to results previously submitted to a |
| dashboard server since the last \fBctest_start()\fP call. |
| Append semantics are defined by the dashboard server in use. |
| This does \fInot\fP cause results to be appended to a \fB\&.xml\fP file |
| produced by a previous call to this command. |
| .TP |
| .B \fBCONFIGURATION <config>\fP |
| Specify the build configuration (e.g. \fBDebug\fP). If not |
| specified the \fBCTEST_BUILD_CONFIGURATION\fP variable will be checked. |
| Otherwise the \fB\-C <cfg>\fP option given to the \fBctest(1)\fP |
| command will be used, if any. |
| .TP |
| .B \fBPARALLEL_LEVEL <parallel>\fP |
| New in version 3.21. |
| |
| .sp |
| Specify the parallel level of the underlying build system. If not |
| specified, the \fBCMAKE_BUILD_PARALLEL_LEVEL\fP environment |
| variable will be checked. |
| .TP |
| .B \fBFLAGS <flags>\fP |
| Pass additional arguments to the underlying build command. |
| If not specified the \fBCTEST_BUILD_FLAGS\fP variable will be checked. |
| This can, e.g., be used to trigger a parallel build using the |
| \fB\-j\fP option of make. See the \fBProcessorCount\fP module |
| for an example. |
| .TP |
| .B \fBPROJECT_NAME <project\-name>\fP |
| Ignored since CMake 3.0. |
| .sp |
| Changed in version 3.14: This value is no longer required. |
| |
| .TP |
| .B \fBTARGET <target\-name>\fP |
| Specify the name of a target to build. If not specified the |
| \fBCTEST_BUILD_TARGET\fP variable will be checked. Otherwise the |
| default target will be built. This is the "all" target |
| (called \fBALL_BUILD\fP in Visual Studio Generators). |
| .TP |
| .B \fBNUMBER_ERRORS <num\-err\-var>\fP |
| Store the number of build errors detected in the given variable. |
| .TP |
| .B \fBNUMBER_WARNINGS <num\-warn\-var>\fP |
| Store the number of build warnings detected in the given variable. |
| .TP |
| .B \fBRETURN_VALUE <result\-var>\fP |
| Store the return value of the native build tool in the given variable. |
| .TP |
| .B \fBCAPTURE_CMAKE_ERROR <result\-var>\fP |
| New in version 3.7. |
| |
| .sp |
| Store in the \fB<result\-var>\fP variable \-1 if there are any errors running |
| the command and prevent ctest from returning non\-zero if an error occurs. |
| .TP |
| .B \fBQUIET\fP |
| New in version 3.3. |
| |
| .sp |
| Suppress any CTest\-specific non\-error output that would have been |
| printed to the console otherwise. The summary of warnings / errors, |
| as well as the output from the native build tool is unaffected by |
| this option. |
| .UNINDENT |
| .SS ctest_configure |
| .sp |
| Perform the CTest Configure Step as a Dashboard Client\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_configure([BUILD <build\-dir>] [SOURCE <source\-dir>] [APPEND] |
| [OPTIONS <options>] [RETURN_VALUE <result\-var>] [QUIET] |
| [CAPTURE_CMAKE_ERROR <result\-var>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Configure the project build tree and record results in \fBConfigure.xml\fP |
| for submission with the \fBctest_submit()\fP command. |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBBUILD <build\-dir>\fP |
| Specify the top\-level build directory. If not given, the |
| \fBCTEST_BINARY_DIRECTORY\fP variable is used. |
| .TP |
| .B \fBSOURCE <source\-dir>\fP |
| Specify the source directory. If not given, the |
| \fBCTEST_SOURCE_DIRECTORY\fP variable is used. |
| .TP |
| .B \fBAPPEND\fP |
| Mark \fBConfigure.xml\fP for append to results previously submitted to a |
| dashboard server since the last \fBctest_start()\fP call. |
| Append semantics are defined by the dashboard server in use. |
| This does \fInot\fP cause results to be appended to a \fB\&.xml\fP file |
| produced by a previous call to this command. |
| .TP |
| .B \fBOPTIONS <options>\fP |
| Specify command\-line arguments to pass to the configuration tool. |
| .TP |
| .B \fBRETURN_VALUE <result\-var>\fP |
| Store in the \fB<result\-var>\fP variable the return value of the native |
| configuration tool. |
| .TP |
| .B \fBCAPTURE_CMAKE_ERROR <result\-var>\fP |
| New in version 3.7. |
| |
| .sp |
| Store in the \fB<result\-var>\fP variable \-1 if there are any errors running |
| the command and prevent ctest from returning non\-zero if an error occurs. |
| .TP |
| .B \fBQUIET\fP |
| New in version 3.3. |
| |
| .sp |
| Suppress any CTest\-specific non\-error messages that would have |
| otherwise been printed to the console. Output from the underlying |
| configure command is not affected. |
| .UNINDENT |
| .SS ctest_coverage |
| .sp |
| Perform the CTest Coverage Step as a Dashboard Client\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_coverage([BUILD <build\-dir>] [APPEND] |
| [LABELS <label>...] |
| [RETURN_VALUE <result\-var>] |
| [CAPTURE_CMAKE_ERROR <result\-var>] |
| [QUIET] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Collect coverage tool results and stores them in \fBCoverage.xml\fP |
| for submission with the \fBctest_submit()\fP command. |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBBUILD <build\-dir>\fP |
| Specify the top\-level build directory. If not given, the |
| \fBCTEST_BINARY_DIRECTORY\fP variable is used. |
| .TP |
| .B \fBAPPEND\fP |
| Mark \fBCoverage.xml\fP for append to results previously submitted to a |
| dashboard server since the last \fBctest_start()\fP call. |
| Append semantics are defined by the dashboard server in use. |
| This does \fInot\fP cause results to be appended to a \fB\&.xml\fP file |
| produced by a previous call to this command. |
| .TP |
| .B \fBLABELS\fP |
| Filter the coverage report to include only source files labeled |
| with at least one of the labels specified. |
| .TP |
| .B \fBRETURN_VALUE <result\-var>\fP |
| Store in the \fB<result\-var>\fP variable \fB0\fP if coverage tools |
| ran without error and non\-zero otherwise. |
| .TP |
| .B \fBCAPTURE_CMAKE_ERROR <result\-var>\fP |
| New in version 3.7. |
| |
| .sp |
| Store in the \fB<result\-var>\fP variable \-1 if there are any errors running |
| the command and prevent ctest from returning non\-zero if an error occurs. |
| .TP |
| .B \fBQUIET\fP |
| New in version 3.3. |
| |
| .sp |
| Suppress any CTest\-specific non\-error output that would have been |
| printed to the console otherwise. The summary indicating how many |
| lines of code were covered is unaffected by this option. |
| .UNINDENT |
| .SS ctest_empty_binary_directory |
| .sp |
| empties the binary directory |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_empty_binary_directory( directory ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Removes a binary directory. This command will perform some checks |
| prior to deleting the directory in an attempt to avoid malicious or |
| accidental directory deletion. |
| .SS ctest_memcheck |
| .sp |
| Perform the CTest MemCheck Step as a Dashboard Client\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_memcheck([BUILD <build\-dir>] [APPEND] |
| [START <start\-number>] |
| [END <end\-number>] |
| [STRIDE <stride\-number>] |
| [EXCLUDE <exclude\-regex>] |
| [INCLUDE <include\-regex>] |
| [EXCLUDE_LABEL <label\-exclude\-regex>] |
| [INCLUDE_LABEL <label\-include\-regex>] |
| [EXCLUDE_FIXTURE <regex>] |
| [EXCLUDE_FIXTURE_SETUP <regex>] |
| [EXCLUDE_FIXTURE_CLEANUP <regex>] |
| [PARALLEL_LEVEL <level>] |
| [RESOURCE_SPEC_FILE <file>] |
| [TEST_LOAD <threshold>] |
| [SCHEDULE_RANDOM <ON|OFF>] |
| [STOP_ON_FAILURE] |
| [STOP_TIME <time\-of\-day>] |
| [RETURN_VALUE <result\-var>] |
| [CAPTURE_CMAKE_ERROR <result\-var>] |
| [REPEAT <mode>:<n>] |
| [OUTPUT_JUNIT <file>] |
| [DEFECT_COUNT <defect\-count\-var>] |
| [QUIET] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Run tests with a dynamic analysis tool and store results in |
| \fBMemCheck.xml\fP for submission with the \fBctest_submit()\fP |
| command. |
| .sp |
| Most options are the same as those for the \fBctest_test()\fP command. |
| .sp |
| The options unique to this command are: |
| .INDENT 0.0 |
| .TP |
| .B \fBDEFECT_COUNT <defect\-count\-var>\fP |
| New in version 3.8. |
| |
| .sp |
| Store in the \fB<defect\-count\-var>\fP the number of defects found. |
| .UNINDENT |
| .SS ctest_read_custom_files |
| .sp |
| read CTestCustom files. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_read_custom_files( directory ... ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Read all the CTestCustom.ctest or CTestCustom.cmake files from the |
| given directory. |
| .sp |
| By default, invoking \fBctest(1)\fP without a script will read custom |
| files from the binary directory. |
| .SS ctest_run_script |
| .sp |
| runs a ctest \-S script |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_run_script([NEW_PROCESS] script_file_name script_file_name1 |
| script_file_name2 ... [RETURN_VALUE var]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Runs a script or scripts much like if it was run from ctest \-S. If no |
| argument is provided then the current script is run using the current |
| settings of the variables. If \fBNEW_PROCESS\fP is specified then each |
| script will be run in a separate process.If \fBRETURN_VALUE\fP is specified |
| the return value of the last script run will be put into \fBvar\fP\&. |
| .SS ctest_sleep |
| .sp |
| sleeps for some amount of time |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_sleep(<seconds>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sleep for given number of seconds. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_sleep(<time1> <duration> <time2>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sleep for t=(time1 + duration \- time2) seconds if t > 0. |
| .SS ctest_start |
| .sp |
| Starts the testing for a given model |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET]) |
| |
| ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Starts the testing for a given model. The command should be called |
| after the binary directory is initialized. |
| .sp |
| The parameters are as follows: |
| .INDENT 0.0 |
| .TP |
| .B \fB<model>\fP |
| Set the dashboard model. Must be one of \fBExperimental\fP, \fBContinuous\fP, or |
| \fBNightly\fP\&. This parameter is required unless \fBAPPEND\fP is specified. |
| .TP |
| .B \fB<source>\fP |
| Set the source directory. If not specified, the value of |
| \fBCTEST_SOURCE_DIRECTORY\fP is used instead. |
| .TP |
| .B \fB<binary>\fP |
| Set the binary directory. If not specified, the value of |
| \fBCTEST_BINARY_DIRECTORY\fP is used instead. |
| .TP |
| .B \fBGROUP <group>\fP |
| If \fBGROUP\fP is used, the submissions will go to the specified group on the |
| CDash server. If no \fBGROUP\fP is specified, the name of the model is used by |
| default. |
| .sp |
| Changed in version 3.16: This replaces the deprecated option \fBTRACK\fP\&. Despite the name |
| change its behavior is unchanged. |
| |
| .TP |
| .B \fBAPPEND\fP |
| If \fBAPPEND\fP is used, the existing \fBTAG\fP is used rather than creating a new |
| one based on the current time stamp. If you use \fBAPPEND\fP, you can omit the |
| \fB<model>\fP and \fBGROUP <group>\fP parameters, because they will be read from |
| the generated \fBTAG\fP file. For example: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_start(Experimental GROUP GroupExperimental) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Later, in another \fBctest \-S\fP script: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_start(APPEND) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| When the second script runs \fBctest_start(APPEND)\fP, it will read the |
| \fBExperimental\fP model and \fBGroupExperimental\fP group from the \fBTAG\fP file |
| generated by the first \fBctest_start()\fP command. Please note that if you |
| call \fBctest_start(APPEND)\fP and specify a different model or group than |
| in the first \fBctest_start()\fP command, a warning will be issued, and the |
| new model and group will be used. |
| .TP |
| .B \fBQUIET\fP |
| New in version 3.3. |
| |
| .sp |
| If \fBQUIET\fP is used, CTest will suppress any non\-error messages that it |
| otherwise would have printed to the console. |
| .UNINDENT |
| .sp |
| The parameters for \fBctest_start()\fP can be issued in any order, with the |
| exception that \fB<model>\fP, \fB<source>\fP, and \fB<binary>\fP have to appear |
| in that order with respect to each other. The following are all valid and |
| equivalent: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND) |
| |
| ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary) |
| |
| ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| However, for the sake of readability, it is recommended that you order your |
| parameters in the order listed at the top of this page. |
| .sp |
| If the \fBCTEST_CHECKOUT_COMMAND\fP variable (or the |
| \fBCTEST_CVS_CHECKOUT\fP variable) is set, its content is treated as |
| command\-line. The command is invoked with the current working directory set |
| to the parent of the source directory, even if the source directory already |
| exists. This can be used to create the source tree from a version control |
| repository. |
| .SS ctest_submit |
| .sp |
| Perform the CTest Submit Step as a Dashboard Client\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_submit([PARTS <part>...] [FILES <file>...] |
| [SUBMIT_URL <url>] |
| [BUILD_ID <result\-var>] |
| [HTTPHEADER <header>] |
| [RETRY_COUNT <count>] |
| [RETRY_DELAY <delay>] |
| [RETURN_VALUE <result\-var>] |
| [CAPTURE_CMAKE_ERROR <result\-var>] |
| [QUIET] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Submit results to a dashboard server. |
| By default all available parts are submitted. |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBPARTS <part>...\fP |
| Specify a subset of parts to submit. Valid part names are: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| Start = nothing |
| Update = ctest_update results, in Update.xml |
| Configure = ctest_configure results, in Configure.xml |
| Build = ctest_build results, in Build.xml |
| Test = ctest_test results, in Test.xml |
| Coverage = ctest_coverage results, in Coverage.xml |
| MemCheck = ctest_memcheck results, in DynamicAnalysis.xml and |
| DynamicAnalysis\-Test.xml |
| Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml |
| ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES |
| Upload = Files prepared for upload by ctest_upload(), in Upload.xml |
| Submit = nothing |
| Done = Build is complete, in Done.xml |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .TP |
| .B \fBFILES <file>...\fP |
| Specify an explicit list of specific files to be submitted. |
| Each individual file must exist at the time of the call. |
| .TP |
| .B \fBSUBMIT_URL <url>\fP |
| New in version 3.14. |
| |
| .sp |
| The \fBhttp\fP or \fBhttps\fP URL of the dashboard server to send the submission |
| to. If not given, the \fBCTEST_SUBMIT_URL\fP variable is used. |
| .TP |
| .B \fBBUILD_ID <result\-var>\fP |
| New in version 3.15. |
| |
| .sp |
| Store in the \fB<result\-var>\fP variable the ID assigned to this build by |
| CDash. |
| .TP |
| .B \fBHTTPHEADER <HTTP\-header>\fP |
| New in version 3.9. |
| |
| .sp |
| Specify HTTP header to be included in the request to CDash during submission. |
| For example, CDash can be configured to only accept submissions from |
| authenticated clients. In this case, you should provide a bearer token in your |
| header: |
| .INDENT 7.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_submit(HTTPHEADER "Authorization: Bearer <auth\-token>") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This suboption can be repeated several times for multiple headers. |
| .TP |
| .B \fBRETRY_COUNT <count>\fP |
| Specify how many times to retry a timed\-out submission. |
| .TP |
| .B \fBRETRY_DELAY <delay>\fP |
| Specify how long (in seconds) to wait after a timed\-out submission |
| before attempting to re\-submit. |
| .TP |
| .B \fBRETURN_VALUE <result\-var>\fP |
| Store in the \fB<result\-var>\fP variable \fB0\fP for success and |
| non\-zero on failure. |
| .TP |
| .B \fBCAPTURE_CMAKE_ERROR <result\-var>\fP |
| New in version 3.13. |
| |
| .sp |
| Store in the \fB<result\-var>\fP variable \-1 if there are any errors running |
| the command and prevent ctest from returning non\-zero if an error occurs. |
| .TP |
| .B \fBQUIET\fP |
| New in version 3.3. |
| |
| .sp |
| Suppress all non\-error messages that would have otherwise been |
| printed to the console. |
| .UNINDENT |
| .SS Submit to CDash Upload API |
| .sp |
| New in version 3.2. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>] |
| [SUBMIT_URL <url>] |
| [BUILD_ID <result\-var>] |
| [HTTPHEADER <header>] |
| [RETRY_COUNT <count>] |
| [RETRY_DELAY <delay>] |
| [RETURN_VALUE <result\-var>] |
| [QUIET]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This second signature is used to upload files to CDash via the CDash |
| file upload API. The API first sends a request to upload to CDash along |
| with a content hash of the file. If CDash does not already have the file, |
| then it is uploaded. Along with the file, a CDash type string is specified |
| to tell CDash which handler to use to process the data. |
| .sp |
| This signature interprets options in the same way as the first one. |
| .sp |
| New in version 3.8: Added the \fBRETRY_COUNT\fP, \fBRETRY_DELAY\fP, \fBQUIET\fP options. |
| |
| .sp |
| New in version 3.9: Added the \fBHTTPHEADER\fP option. |
| |
| .sp |
| New in version 3.13: Added the \fBRETURN_VALUE\fP option. |
| |
| .sp |
| New in version 3.14: Added the \fBSUBMIT_URL\fP option. |
| |
| .sp |
| New in version 3.15: Added the \fBBUILD_ID\fP option. |
| |
| .SS ctest_test |
| .sp |
| Perform the CTest Test Step as a Dashboard Client\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_test([BUILD <build\-dir>] [APPEND] |
| [START <start\-number>] |
| [END <end\-number>] |
| [STRIDE <stride\-number>] |
| [EXCLUDE <exclude\-regex>] |
| [INCLUDE <include\-regex>] |
| [EXCLUDE_LABEL <label\-exclude\-regex>] |
| [INCLUDE_LABEL <label\-include\-regex>] |
| [EXCLUDE_FIXTURE <regex>] |
| [EXCLUDE_FIXTURE_SETUP <regex>] |
| [EXCLUDE_FIXTURE_CLEANUP <regex>] |
| [PARALLEL_LEVEL <level>] |
| [RESOURCE_SPEC_FILE <file>] |
| [TEST_LOAD <threshold>] |
| [SCHEDULE_RANDOM <ON|OFF>] |
| [STOP_ON_FAILURE] |
| [STOP_TIME <time\-of\-day>] |
| [RETURN_VALUE <result\-var>] |
| [CAPTURE_CMAKE_ERROR <result\-var>] |
| [REPEAT <mode>:<n>] |
| [OUTPUT_JUNIT <file>] |
| [QUIET] |
| ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Run tests in the project build tree and store results in |
| \fBTest.xml\fP for submission with the \fBctest_submit()\fP command. |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBBUILD <build\-dir>\fP |
| Specify the top\-level build directory. If not given, the |
| \fBCTEST_BINARY_DIRECTORY\fP variable is used. |
| .TP |
| .B \fBAPPEND\fP |
| Mark \fBTest.xml\fP for append to results previously submitted to a |
| dashboard server since the last \fBctest_start()\fP call. |
| Append semantics are defined by the dashboard server in use. |
| This does \fInot\fP cause results to be appended to a \fB\&.xml\fP file |
| produced by a previous call to this command. |
| .TP |
| .B \fBSTART <start\-number>\fP |
| Specify the beginning of a range of test numbers. |
| .TP |
| .B \fBEND <end\-number>\fP |
| Specify the end of a range of test numbers. |
| .TP |
| .B \fBSTRIDE <stride\-number>\fP |
| Specify the stride by which to step across a range of test numbers. |
| .TP |
| .B \fBEXCLUDE <exclude\-regex>\fP |
| Specify a regular expression matching test names to exclude. |
| .TP |
| .B \fBINCLUDE <include\-regex>\fP |
| Specify a regular expression matching test names to include. |
| Tests not matching this expression are excluded. |
| .TP |
| .B \fBEXCLUDE_LABEL <label\-exclude\-regex>\fP |
| Specify a regular expression matching test labels to exclude. |
| .TP |
| .B \fBINCLUDE_LABEL <label\-include\-regex>\fP |
| Specify a regular expression matching test labels to include. |
| Tests not matching this expression are excluded. |
| .TP |
| .B \fBEXCLUDE_FIXTURE <regex>\fP |
| New in version 3.7. |
| |
| .sp |
| If a test in the set of tests to be executed requires a particular fixture, |
| that fixture\(aqs setup and cleanup tests would normally be added to the test |
| set automatically. This option prevents adding setup or cleanup tests for |
| fixtures matching the \fB<regex>\fP\&. Note that all other fixture behavior is |
| retained, including test dependencies and skipping tests that have fixture |
| setup tests that fail. |
| .TP |
| .B \fBEXCLUDE_FIXTURE_SETUP <regex>\fP |
| New in version 3.7. |
| |
| .sp |
| Same as \fBEXCLUDE_FIXTURE\fP except only matching setup tests are excluded. |
| .TP |
| .B \fBEXCLUDE_FIXTURE_CLEANUP <regex>\fP |
| New in version 3.7. |
| |
| .sp |
| Same as \fBEXCLUDE_FIXTURE\fP except only matching cleanup tests are excluded. |
| .TP |
| .B \fBPARALLEL_LEVEL <level>\fP |
| Specify a positive number representing the number of tests to |
| be run in parallel. |
| .TP |
| .B \fBRESOURCE_SPEC_FILE <file>\fP |
| New in version 3.16. |
| |
| .sp |
| Specify a |
| resource specification file\&. See |
| ctest\-resource\-allocation for more information. |
| .TP |
| .B \fBTEST_LOAD <threshold>\fP |
| New in version 3.4. |
| |
| .sp |
| While running tests in parallel, try not to start tests when they |
| may cause the CPU load to pass above a given threshold. If not |
| specified the \fBCTEST_TEST_LOAD\fP variable will be checked, |
| and then the \fB\-\-test\-load\fP command\-line argument to \fBctest(1)\fP\&. |
| See also the \fBTestLoad\fP setting in the CTest Test Step\&. |
| .TP |
| .B \fBREPEAT <mode>:<n>\fP |
| New in version 3.17. |
| |
| .sp |
| Run tests repeatedly based on the given \fB<mode>\fP up to \fB<n>\fP times. |
| The modes are: |
| .INDENT 7.0 |
| .TP |
| .B \fBUNTIL_FAIL\fP |
| Require each test to run \fB<n>\fP times without failing in order to pass. |
| This is useful in finding sporadic failures in test cases. |
| .TP |
| .B \fBUNTIL_PASS\fP |
| Allow each test to run up to \fB<n>\fP times in order to pass. |
| Repeats tests if they fail for any reason. |
| This is useful in tolerating sporadic failures in test cases. |
| .TP |
| .B \fBAFTER_TIMEOUT\fP |
| Allow each test to run up to \fB<n>\fP times in order to pass. |
| Repeats tests only if they timeout. |
| This is useful in tolerating sporadic timeouts in test cases |
| on busy machines. |
| .UNINDENT |
| .TP |
| .B \fBSCHEDULE_RANDOM <ON|OFF>\fP |
| Launch tests in a random order. This may be useful for detecting |
| implicit test dependencies. |
| .TP |
| .B \fBSTOP_ON_FAILURE\fP |
| New in version 3.18. |
| |
| .sp |
| Stop the execution of the tests once one has failed. |
| .TP |
| .B \fBSTOP_TIME <time\-of\-day>\fP |
| Specify a time of day at which the tests should all stop running. |
| .TP |
| .B \fBRETURN_VALUE <result\-var>\fP |
| Store in the \fB<result\-var>\fP variable \fB0\fP if all tests passed. |
| Store non\-zero if anything went wrong. |
| .TP |
| .B \fBCAPTURE_CMAKE_ERROR <result\-var>\fP |
| New in version 3.7. |
| |
| .sp |
| Store in the \fB<result\-var>\fP variable \-1 if there are any errors running |
| the command and prevent ctest from returning non\-zero if an error occurs. |
| .TP |
| .B \fBOUTPUT_JUNIT <file>\fP |
| New in version 3.21. |
| |
| .sp |
| Write test results to \fB<file>\fP in JUnit XML format. If \fB<file>\fP is a |
| relative path, it will be placed in the build directory. If \fB<file>\fP |
| already exists, it will be overwritten. Note that the resulting JUnit XML |
| file is \fBnot\fP uploaded to CDash because it would be redundant with |
| CTest\(aqs \fBTest.xml\fP file. |
| .TP |
| .B \fBQUIET\fP |
| New in version 3.3. |
| |
| .sp |
| Suppress any CTest\-specific non\-error messages that would have otherwise |
| been printed to the console. Output from the underlying test command is not |
| affected. Summary info detailing the percentage of passing tests is also |
| unaffected by the \fBQUIET\fP option. |
| .UNINDENT |
| .sp |
| See also the \fBCTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE\fP |
| and \fBCTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE\fP variables. |
| .SS Additional Test Measurements |
| .sp |
| CTest can parse the output of your tests for extra measurements to report |
| to CDash. |
| .sp |
| When run as a Dashboard Client, CTest will include these custom |
| measurements in the \fBTest.xml\fP file that gets uploaded to CDash. |
| .sp |
| Check the \fI\%CDash test measurement documentation\fP |
| for more information on the types of test measurements that CDash recognizes. |
| .sp |
| The following example demonstrates how to output a variety of custom test |
| measurements. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| std::cout << |
| "<CTestMeasurement type=\e"numeric/double\e" name=\e"score\e">28.3</CTestMeasurement>" |
| << std::endl; |
| |
| std::cout << |
| "<CTestMeasurement type=\e"text/string\e" name=\e"color\e">red</CTestMeasurement>" |
| << std::endl; |
| |
| std::cout << |
| "<CTestMeasurement type=\e"text/link\e" name=\e"CMake URL\e">https://cmake.org</CTestMeasurement>" |
| << std::endl; |
| |
| std::cout << |
| "<CTestMeasurement type=\e"text/preformatted\e" name=\e"Console Output\e">" << |
| "line 1.\en" << |
| " \e033[31;1m line 2. Bold red, and indented!\e033[0;0ml\en" << |
| "line 3. Not bold or indented...\en" << |
| "</CTestMeasurement>" << std::endl; |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Image Measurements |
| .sp |
| The following example demonstrates how to upload test images to CDash. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| std::cout << |
| "<CTestMeasurementFile type=\e"image/jpg\e" name=\e"TestImage\e">" << |
| "/dir/to/test_img.jpg</CTestMeasurementFile>" << std::endl; |
| |
| std::cout << |
| "<CTestMeasurementFile type=\e"image/gif\e" name=\e"ValidImage\e">" << |
| "/dir/to/valid_img.gif</CTestMeasurementFile>" << std::endl; |
| |
| std::cout << |
| "<CTestMeasurementFile type=\e"image/png\e" name=\e"AlgoResult\e"> << |
| "/dir/to/img.png</CTestMeasurementFile>" |
| << std::endl; |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Images will be displayed together in an interactive comparison mode on CDash |
| if they are provided with two or more of the following names. |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBTestImage\fP |
| .IP \(bu 2 |
| \fBValidImage\fP |
| .IP \(bu 2 |
| \fBBaselineImage\fP |
| .IP \(bu 2 |
| \fBDifferenceImage2\fP |
| .UNINDENT |
| .sp |
| By convention, \fBTestImage\fP is the image generated by your test, and |
| \fBValidImage\fP (or \fBBaselineImage\fP) is basis of comparison used to determine |
| if the test passed or failed. |
| .sp |
| If another image name is used it will be displayed by CDash as a static image |
| separate from the interactive comparison UI. |
| .SS Attached Files |
| .sp |
| New in version 3.21. |
| |
| .sp |
| The following example demonstrates how to upload non\-image files to CDash. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| std::cout << |
| "<CTestMeasurementFile type=\e"file\e" name=\e"TestInputData1\e">" << |
| "/dir/to/data1.csv</CTestMeasurementFile>\en" << |
| "<CTestMeasurementFile type=\e"file\e" name=\e"TestInputData2\e">" << |
| "/dir/to/data2.csv</CTestMeasurementFile>" << std::endl; |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If the name of the file to upload is known at configure time, you can use the |
| \fBATTACHED_FILES\fP or \fBATTACHED_FILES_ON_FAIL\fP test |
| properties instead. |
| .SS Custom Details |
| .sp |
| New in version 3.21. |
| |
| .sp |
| The following example demonstrates how to specify a custom value for the |
| \fBTest Details\fP field displayed on CDash. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| std::cout << |
| "<CTestDetails>My Custom Details Value</CTestDetails>" << std::endl; |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .SS Additional Labels |
| .sp |
| New in version 3.22. |
| |
| .sp |
| The following example demonstrates how to add additional labels to a test |
| at runtime. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| std::cout << |
| "<CTestLabel>Custom Label 1</CTestLabel>\en" << |
| "<CTestLabel>Custom Label 2</CTestLabel>" << std::endl; |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Use the \fBLABELS\fP test property instead for labels that can be |
| determined at configure time. |
| .SS ctest_update |
| .sp |
| Perform the CTest Update Step as a Dashboard Client\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_update([SOURCE <source\-dir>] |
| [RETURN_VALUE <result\-var>] |
| [CAPTURE_CMAKE_ERROR <result\-var>] |
| [QUIET]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Update the source tree from version control and record results in |
| \fBUpdate.xml\fP for submission with the \fBctest_submit()\fP command. |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBSOURCE <source\-dir>\fP |
| Specify the source directory. If not given, the |
| \fBCTEST_SOURCE_DIRECTORY\fP variable is used. |
| .TP |
| .B \fBRETURN_VALUE <result\-var>\fP |
| Store in the \fB<result\-var>\fP variable the number of files |
| updated or \fB\-1\fP on error. |
| .TP |
| .B \fBCAPTURE_CMAKE_ERROR <result\-var>\fP |
| New in version 3.13. |
| |
| .sp |
| Store in the \fB<result\-var>\fP variable \-1 if there are any errors running |
| the command and prevent ctest from returning non\-zero if an error occurs. |
| .TP |
| .B \fBQUIET\fP |
| New in version 3.3. |
| |
| .sp |
| Tell CTest to suppress most non\-error messages that it would |
| have otherwise printed to the console. CTest will still report |
| the new revision of the repository and any conflicting files |
| that were found. |
| .UNINDENT |
| .sp |
| The update always follows the version control branch currently checked |
| out in the source directory. See the CTest Update Step |
| documentation for information about variables that change the behavior |
| of \fBctest_update()\fP\&. |
| .SS ctest_upload |
| .sp |
| Upload files to a dashboard server as a Dashboard Client\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result\-var>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The options are: |
| .INDENT 0.0 |
| .TP |
| .B \fBFILES <file>...\fP |
| Specify a list of files to be sent along with the build results to the |
| dashboard server. |
| .TP |
| .B \fBQUIET\fP |
| New in version 3.3. |
| |
| .sp |
| Suppress any CTest\-specific non\-error output that would have been |
| printed to the console otherwise. |
| .TP |
| .B \fBCAPTURE_CMAKE_ERROR <result\-var>\fP |
| New in version 3.7. |
| |
| .sp |
| Store in the \fB<result\-var>\fP variable \-1 if there are any errors running |
| the command and prevent ctest from returning non\-zero if an error occurs. |
| .UNINDENT |
| .SH DEPRECATED COMMANDS |
| .sp |
| These commands are deprecated and are only made available to maintain |
| backward compatibility. The documentation of each command states the |
| CMake version in which it was deprecated. Do not use these commands |
| in new code. |
| .SS build_name |
| .sp |
| Disallowed since version 3.0. See CMake Policy \fBCMP0036\fP\&. |
| .sp |
| Use \fB${CMAKE_SYSTEM}\fP and \fB${CMAKE_CXX_COMPILER}\fP instead. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| build_name(variable) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Sets the specified variable to a string representing the platform and |
| compiler settings. These values are now available through the |
| \fBCMAKE_SYSTEM\fP and |
| \fBCMAKE_CXX_COMPILER\fP variables. |
| .SS exec_program |
| .sp |
| Deprecated since version 3.0: Use the \fBexecute_process()\fP command instead. |
| |
| .sp |
| Run an executable program during the processing of the CMakeList.txt |
| file. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| exec_program(Executable [directory in which to run] |
| [ARGS <arguments to executable>] |
| [OUTPUT_VARIABLE <var>] |
| [RETURN_VALUE <var>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The executable is run in the optionally specified directory. The |
| executable can include arguments if it is double quoted, but it is |
| better to use the optional \fBARGS\fP argument to specify arguments to the |
| program. This is because cmake will then be able to escape spaces in |
| the executable path. An optional argument \fBOUTPUT_VARIABLE\fP specifies a |
| variable in which to store the output. To capture the return value of |
| the execution, provide a \fBRETURN_VALUE\fP\&. If \fBOUTPUT_VARIABLE\fP is |
| specified, then no output will go to the stdout/stderr of the console |
| running cmake. |
| .SS export_library_dependencies |
| .sp |
| Disallowed since version 3.0. See CMake Policy \fBCMP0033\fP\&. |
| .sp |
| Use \fBinstall(EXPORT)\fP or \fBexport()\fP command. |
| .sp |
| This command generates an old\-style library dependencies file. |
| Projects requiring CMake 2.6 or later should not use the command. Use |
| instead the \fBinstall(EXPORT)\fP command to help export targets from an |
| installation tree and the \fBexport()\fP command to export targets from a |
| build tree. |
| .sp |
| The old\-style library dependencies file does not take into account |
| per\-configuration names of libraries or the |
| \fBLINK_INTERFACE_LIBRARIES\fP target property. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| export_library_dependencies(<file> [APPEND]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Create a file named \fB<file>\fP that can be included into a CMake listfile |
| with the INCLUDE command. The file will contain a number of SET |
| commands that will set all the variables needed for library dependency |
| information. This should be the last command in the top level |
| CMakeLists.txt file of the project. If the \fBAPPEND\fP option is |
| specified, the SET commands will be appended to the given file instead |
| of replacing it. |
| .SS install_files |
| .sp |
| Deprecated since version 3.0: Use the \fBinstall(FILES)\fP command instead. |
| |
| .sp |
| This command has been superseded by the \fBinstall()\fP command. It is |
| provided for compatibility with older CMake code. The \fBFILES\fP form is |
| directly replaced by the \fBFILES\fP form of the \fBinstall()\fP |
| command. The regexp form can be expressed more clearly using the \fBGLOB\fP |
| form of the \fBfile()\fP command. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install_files(<dir> extension file file ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Create rules to install the listed files with the given extension into |
| the given directory. Only files existing in the current source tree |
| or its corresponding location in the binary tree may be listed. If a |
| file specified already has an extension, that extension will be |
| removed first. This is useful for providing lists of source files |
| such as foo.cxx when you want the corresponding foo.h to be installed. |
| A typical extension is \fB\&.h\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install_files(<dir> regexp) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Any files in the current source directory that match the regular |
| expression will be installed. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install_files(<dir> FILES file file ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Any files listed after the \fBFILES\fP keyword will be installed explicitly |
| from the names given. Full paths are allowed in this form. |
| .sp |
| The directory \fB<dir>\fP is relative to the installation prefix, which is |
| stored in the variable \fBCMAKE_INSTALL_PREFIX\fP\&. |
| .SS install_programs |
| .sp |
| Deprecated since version 3.0: Use the \fBinstall(PROGRAMS)\fP command instead. |
| |
| .sp |
| This command has been superseded by the \fBinstall()\fP command. It is |
| provided for compatibility with older CMake code. The \fBFILES\fP form is |
| directly replaced by the \fBPROGRAMS\fP form of the \fBinstall()\fP |
| command. The regexp form can be expressed more clearly using the \fBGLOB\fP |
| form of the \fBfile()\fP command. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install_programs(<dir> file1 file2 [file3 ...]) |
| install_programs(<dir> FILES file1 [file2 ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Create rules to install the listed programs into the given directory. |
| Use the \fBFILES\fP argument to guarantee that the file list version of the |
| command will be used even when there is only one argument. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install_programs(<dir> regexp) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| In the second form any program in the current source directory that |
| matches the regular expression will be installed. |
| .sp |
| This command is intended to install programs that are not built by |
| cmake, such as shell scripts. See the \fBTARGETS\fP form of the |
| \fBinstall()\fP command to create installation rules for targets built |
| by cmake. |
| .sp |
| The directory \fB<dir>\fP is relative to the installation prefix, which is |
| stored in the variable \fBCMAKE_INSTALL_PREFIX\fP\&. |
| .SS install_targets |
| .sp |
| Deprecated since version 3.0: Use the \fBinstall(TARGETS)\fP command instead. |
| |
| .sp |
| This command has been superseded by the \fBinstall()\fP command. It is |
| provided for compatibility with older CMake code. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install_targets(<dir> [RUNTIME_DIRECTORY dir] target target) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Create rules to install the listed targets into the given directory. |
| The directory \fB<dir>\fP is relative to the installation prefix, which is |
| stored in the variable \fBCMAKE_INSTALL_PREFIX\fP\&. If |
| \fBRUNTIME_DIRECTORY\fP is specified, then on systems with special runtime |
| files (Windows DLL), the files will be copied to that directory. |
| .SS load_command |
| .sp |
| Disallowed since version 3.0. See CMake Policy \fBCMP0031\fP\&. |
| .sp |
| Load a command into a running CMake. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| load_command(COMMAND_NAME <loc1> [loc2 ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The given locations are searched for a library whose name is |
| cmCOMMAND_NAME. If found, it is loaded as a module and the command is |
| added to the set of available CMake commands. Usually, |
| \fBtry_compile()\fP is used before this command to compile the |
| module. If the command is successfully loaded a variable named |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| CMAKE_LOADED_COMMAND_<COMMAND_NAME> |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| will be set to the full path of the module that was loaded. Otherwise |
| the variable will not be set. |
| .SS make_directory |
| .sp |
| Deprecated since version 3.0: Use the \fBfile(MAKE_DIRECTORY)\fP command instead. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| make_directory(directory) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Creates the specified directory. Full paths should be given. Any |
| parent directories that do not exist will also be created. Use with |
| care. |
| .SS output_required_files |
| .sp |
| Disallowed since version 3.0. See CMake Policy \fBCMP0032\fP\&. |
| .sp |
| Approximate C preprocessor dependency scanning. |
| .sp |
| This command exists only because ancient CMake versions provided it. |
| CMake handles preprocessor dependency scanning automatically using a |
| more advanced scanner. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| output_required_files(srcfile outputfile) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Outputs a list of all the source files that are required by the |
| specified \fBsrcfile\fP\&. This list is written into \fBoutputfile\fP\&. This is |
| similar to writing out the dependencies for \fBsrcfile\fP except that it |
| jumps from \fB\&.h\fP files into \fB\&.cxx\fP, \fB\&.c\fP and \fB\&.cpp\fP files if possible. |
| .SS qt_wrap_cpp |
| .sp |
| Deprecated since version 3.14: This command was originally added to support Qt 3 before the |
| \fBadd_custom_command()\fP command was sufficiently mature. The |
| \fBFindQt4\fP module provides the \fBqt4_wrap_cpp()\fP macro, which |
| should be used instead for Qt 4 projects. For projects using Qt 5 or |
| later, use the equivalent macro provided by Qt itself (e.g. Qt 5 provides |
| \fBqt5_wrap_cpp()\fP). |
| |
| .sp |
| Manually create Qt Wrappers. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| qt_wrap_cpp(resultingLibraryName DestName SourceLists ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Produces moc files for all the .h files listed in the SourceLists. The |
| moc files will be added to the library using the \fBDestName\fP source list. |
| .sp |
| Consider updating the project to use the \fBAUTOMOC\fP target property |
| instead for a more automated way of invoking the \fBmoc\fP tool. |
| .SS qt_wrap_ui |
| .sp |
| Deprecated since version 3.14: This command was originally added to support Qt 3 before the |
| \fBadd_custom_command()\fP command was sufficiently mature. The |
| \fBFindQt4\fP module provides the \fBqt4_wrap_ui()\fP macro, which |
| should be used instead for Qt 4 projects. For projects using Qt 5 or |
| later, use the equivalent macro provided by Qt itself (e.g. Qt 5 provides |
| \fBqt5_wrap_ui()\fP). |
| |
| .sp |
| Manually create Qt user interfaces Wrappers. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| qt_wrap_ui(resultingLibraryName HeadersDestName |
| SourcesDestName SourceLists ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Produces .h and .cxx files for all the .ui files listed in the |
| \fBSourceLists\fP\&. The .h files will be added to the library using the |
| \fBHeadersDestNamesource\fP list. The .cxx files will be added to the |
| library using the \fBSourcesDestNamesource\fP list. |
| .sp |
| Consider updating the project to use the \fBAUTOUIC\fP target property |
| instead for a more automated way of invoking the \fBuic\fP tool. |
| .SS remove |
| .sp |
| Deprecated since version 3.0: Use the \fBlist(REMOVE_ITEM)\fP command instead. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| remove(VAR VALUE VALUE ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Removes \fBVALUE\fP from the variable \fBVAR\fP\&. This is typically used to |
| remove entries from a vector (e.g. semicolon separated list). \fBVALUE\fP |
| is expanded. |
| .SS subdir_depends |
| .sp |
| Disallowed since version 3.0. See CMake Policy \fBCMP0029\fP\&. |
| .sp |
| Does nothing. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| subdir_depends(subdir dep1 dep2 ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Does not do anything. This command used to help projects order |
| parallel builds correctly. This functionality is now automatic. |
| .SS subdirs |
| .sp |
| Deprecated since version 3.0: Use the \fBadd_subdirectory()\fP command instead. |
| |
| .sp |
| Add a list of subdirectories to the build. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...] |
| [PREORDER] ) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Add a list of subdirectories to the build. The \fBadd_subdirectory()\fP |
| command should be used instead of \fBsubdirs\fP although \fBsubdirs\fP will still |
| work. This will cause any CMakeLists.txt files in the sub directories |
| to be processed by CMake. Any directories after the \fBPREORDER\fP flag are |
| traversed first by makefile builds, the \fBPREORDER\fP flag has no effect on |
| IDE projects. Any directories after the \fBEXCLUDE_FROM_ALL\fP marker will |
| not be included in the top level makefile or project file. This is |
| useful for having CMake create makefiles or projects for a set of |
| examples in a project. You would want CMake to generate makefiles or |
| project files for all the examples at the same time, but you would not |
| want them to show up in the top level project or be built each time |
| make is run from the top. |
| .SS use_mangled_mesa |
| .sp |
| Disallowed since version 3.0. See CMake Policy \fBCMP0030\fP\&. |
| .sp |
| Copy mesa headers for use in combination with system GL. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The path to mesa includes, should contain \fBgl_mangle.h\fP\&. The mesa |
| headers are copied to the specified output directory. This allows |
| mangled mesa headers to override other GL headers by being added to |
| the include directory path earlier. |
| .SS utility_source |
| .sp |
| Disallowed since version 3.0. See CMake Policy \fBCMP0034\fP\&. |
| .sp |
| Specify the source tree of a third\-party utility. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| utility_source(cache_entry executable_name |
| path_to_source [file1 file2 ...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| When a third\-party utility\(aqs source is included in the distribution, |
| this command specifies its location and name. The cache entry will |
| not be set unless the \fBpath_to_source\fP and all listed files exist. It |
| is assumed that the source tree of the utility will have been built |
| before it is needed. |
| .sp |
| When cross compiling CMake will print a warning if a \fButility_source()\fP |
| command is executed, because in many cases it is used to build an |
| executable which is executed later on. This doesn\(aqt work when cross |
| compiling, since the executable can run only on their target platform. |
| So in this case the cache entry has to be adjusted manually so it |
| points to an executable which is runnable on the build host. |
| .SS variable_requires |
| .sp |
| Disallowed since version 3.0. See CMake Policy \fBCMP0035\fP\&. |
| .sp |
| Use the \fBif()\fP command instead. |
| .sp |
| Assert satisfaction of an option\(aqs required variables. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| variable_requires(TEST_VARIABLE RESULT_VARIABLE |
| REQUIRED_VARIABLE1 |
| REQUIRED_VARIABLE2 ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The first argument (\fBTEST_VARIABLE\fP) is the name of the variable to be |
| tested, if that variable is false nothing else is done. If |
| \fBTEST_VARIABLE\fP is true, then the next argument (\fBRESULT_VARIABLE\fP) |
| is a variable that is set to true if all the required variables are set. |
| The rest of the arguments are variables that must be true or not set |
| to \fBNOTFOUND\fP to avoid an error. If any are not true, an error is |
| reported. |
| .SS write_file |
| .sp |
| Deprecated since version 3.0: Use the \fBfile(WRITE)\fP command instead. |
| |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| write_file(filename "message to write"... [APPEND]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The first argument is the file name, the rest of the arguments are |
| messages to write. If the argument \fBAPPEND\fP is specified, then the |
| message will be appended. |
| .sp |
| NOTE 1: \fBfile(WRITE)\fP and \fBfile(APPEND)\fP do exactly |
| the same as this one but add some more functionality. |
| .sp |
| NOTE 2: When using \fBwrite_file\fP the produced file cannot be used as an |
| input to CMake (CONFIGURE_FILE, source file ...) because it will lead |
| to an infinite loop. Use \fBconfigure_file()\fP if you want to |
| generate input files to CMake. |
| .SH COPYRIGHT |
| 2000-2022 Kitware, Inc. and Contributors |
| .\" Generated by docutils manpage writer. |
| . |