1CMAKE-COMMANDS(7) CMake CMAKE-COMMANDS(7)
2
6 cmake-commands - CMake Language Command Reference
7
9 These commands are always available.
10 break
12 Break from an enclosing foreach or while loop.
13 break()
15 Breaks from an enclosing foreach() or while() loop.
17 See also the continue() command.
19 cmake_host_system_information
21 Query host system specific information.
22 cmake_host_system_information(RESULT <variable> QUERY <key> ...)
24 Queries system information of the host system on which cmake runs. One
26 or more <key> can be provided to select the information to be queried.
27 The list of queried values is stored in <variable>.
28 <key> can be one of the following values:
30 NUMBER_OF_LOGICAL_CORES
32 Number of logical cores
33 NUMBER_OF_PHYSICAL_CORES
35 Number of physical cores
36 HOSTNAME
38 Hostname
39 FQDN Fully qualified domain name
41 TOTAL_VIRTUAL_MEMORY
43 Total virtual memory in MiB [1]
44 AVAILABLE_VIRTUAL_MEMORY
46 Available virtual memory in MiB [1]
47 TOTAL_PHYSICAL_MEMORY
49 Total physical memory in MiB [1]
50 AVAILABLE_PHYSICAL_MEMORY
52 Available physical memory in MiB [1]
53 IS_64BIT
55 New in version 3.10.
56 One if processor is 64Bit
59 HAS_FPU
61 New in version 3.10.
62 One if processor has floating point unit
65 HAS_MMX
67 New in version 3.10.
68 One if processor supports MMX instructions
71 HAS_MMX_PLUS
73 New in version 3.10.
74 One if processor supports Ext. MMX instructions
77 HAS_SSE
79 New in version 3.10.
80 One if processor supports SSE instructions
83 HAS_SSE2
85 New in version 3.10.
86 One if processor supports SSE2 instructions
89 HAS_SSE_FP
91 New in version 3.10.
92 One if processor supports SSE FP instructions
95 HAS_SSE_MMX
97 New in version 3.10.
98 One if processor supports SSE MMX instructions
101 HAS_AMD_3DNOW
103 New in version 3.10.
104 One if processor supports 3DNow instructions
107 HAS_AMD_3DNOW_PLUS
109 New in version 3.10.
110 One if processor supports 3DNow+ instructions
113 HAS_IA64
115 New in version 3.10.
116 One if IA64 processor emulating x86
119 HAS_SERIAL_NUMBER
121 New in version 3.10.
122 One if processor has serial number
125 PROCESSOR_SERIAL_NUMBER
127 New in version 3.10.
128 Processor serial number
131 PROCESSOR_NAME
133 New in version 3.10.
134 Human readable processor name
137 PROCESSOR_DESCRIPTION
139 New in version 3.10.
140 Human readable full processor description
143 OS_NAME
145 New in version 3.10.
146 See CMAKE_HOST_SYSTEM_NAME
149 OS_RELEASE
151 New in version 3.10.
152 The OS sub-type e.g. on Windows Professional
155 OS_VERSION
157 New in version 3.10.
158 The OS build ID
161 OS_PLATFORM
163 New in version 3.10.
164 See CMAKE_HOST_SYSTEM_PROCESSOR
167 DISTRIB_INFO
169 New in version 3.22.
170 Read /etc/os-release file and define the given <variable> into a
173 list of read variables
174 DISTRIB_<name>
176 New in version 3.22.
177 Get the <name> variable (see man 5 os-release) if it exists in
180 the /etc/os-release file
181 Example:
183 cmake_host_system_information(RESULT PRETTY_NAME QUERY DISTRIB_PRETTY_NAME)
185 message(STATUS "${PRETTY_NAME}")
186 cmake_host_system_information(RESULT DISTRO QUERY DISTRIB_INFO)
188 foreach(VAR IN LISTS DISTRO)
190 message(STATUS "${VAR}=`${${VAR}}`")
191 endforeach()
192 Output:
194 -- Ubuntu 20.04.2 LTS
196 -- DISTRO_BUG_REPORT_URL=`https://bugs.launchpad.net/ubuntu/`
197 -- DISTRO_HOME_URL=`https://www.ubuntu.com/`
198 -- DISTRO_ID=`ubuntu`
199 -- DISTRO_ID_LIKE=`debian`
200 -- DISTRO_NAME=`Ubuntu`
201 -- DISTRO_PRETTY_NAME=`Ubuntu 20.04.2 LTS`
202 -- DISTRO_PRIVACY_POLICY_URL=`https://www.ubuntu.com/legal/terms-and-policies/privacy-policy`
203 -- DISTRO_SUPPORT_URL=`https://help.ubuntu.com/`
204 -- DISTRO_UBUNTU_CODENAME=`focal`
205 -- DISTRO_VERSION=`20.04.2 LTS (Focal Fossa)`
206 -- DISTRO_VERSION_CODENAME=`focal`
207 -- DISTRO_VERSION_ID=`20.04`
208 If /etc/os-release file is not found, the command tries to gather OS
210 identification via fallback scripts. The fallback script can use
211 various distribution-specific files to collect OS identification data
212 and map it into man 5 os-release variables.
213 Fallback Interface Variables
215 CMAKE_GET_OS_RELEASE_FALLBACK_SCRIPTS
216 In addition to the scripts shipped with CMake, a user may append
217 full paths to his script(s) to the this list. The script file‐
218 name has the following format: NNN-<name>.cmake, where NNN is
219 three digits used to apply collected scripts in a specific or‐
220 der.
221 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname>
223 Variables collected by the user provided fallback script ought
224 to be assigned to CMake variables using this naming convention.
225 Example, the ID variable from the manual becomes
226 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID.
227 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT
229 The fallback script ought to store names of all assigned
230 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname> variables in this
231 list.
232 Example:
234 # Try to detect some old distribution
236 # See also
237 # - http://linuxmafia.com/faq/Admin/release-files.html
238 #
239 if(NOT EXISTS "${CMAKE_SYSROOT}/etc/foobar-release")
240 return()
241 endif()
242 # Get the first string only
243 file(
244 STRINGS "${CMAKE_SYSROOT}/etc/foobar-release" CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT
245 LIMIT_COUNT 1
246 )
247 #
248 # Example:
249 #
250 # Foobar distribution release 1.2.3 (server)
251 #
252 if(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT MATCHES "Foobar distribution release ([0-9\.]+) .*")
253 set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME Foobar)
254 set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME "${CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT}")
255 set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID foobar)
256 set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION ${CMAKE_MATCH_1})
257 set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID ${CMAKE_MATCH_1})
258 list(
259 APPEND CMAKE_GET_OS_RELEASE_FALLBACK_RESULT
260 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME
261 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME
262 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID
263 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION
264 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID
265 )
266 endif()
267 unset(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT)
268
270 [1] One MiB (mebibyte) is equal to 1024x1024 bytes.
271 cmake_language
273 New in version 3.18.
274 Call meta-operations on CMake commands.
277 Synopsis
279 cmake_language(CALL <command> [<arg>...])
280 cmake_language(EVAL CODE <code>...)
281 cmake_language(DEFER <options>... CALL <command> [<arg>...])
282 Introduction
284 This command will call meta-operations on built-in CMake commands or
285 those created via the macro() or function() commands.
286 cmake_language does not introduce a new variable or policy scope.
288 Calling Commands
290 cmake_language(CALL <command> [<arg>...])
291 Calls the named <command> with the given arguments (if any). For exam‐
293 ple, the code:
294 set(message_command "message")
296 cmake_language(CALL ${message_command} STATUS "Hello World!")
297 is equivalent to
299 message(STATUS "Hello World!")
301 NOTE:
303 To ensure consistency of the code, the following commands are not
304 allowed:
305 • if / elseif / else / endif
307 • while / endwhile
309 • foreach / endforeach
311 • function / endfunction
313 • macro / endmacro
315 Evaluating Code
317 cmake_language(EVAL CODE <code>...)
318 Evaluates the <code>... as CMake code.
320 For example, the code:
322 set(A TRUE)
324 set(B TRUE)
325 set(C TRUE)
326 set(condition "(A AND B) OR C")
327 cmake_language(EVAL CODE "
329 if (${condition})
330 message(STATUS TRUE)
331 else()
332 message(STATUS FALSE)
333 endif()"
334 )
335 is equivalent to
337 set(A TRUE)
339 set(B TRUE)
340 set(C TRUE)
341 set(condition "(A AND B) OR C")
342 file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
344 if (${condition})
345 message(STATUS TRUE)
346 else()
347 message(STATUS FALSE)
348 endif()"
349 )
350 include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)
352 Deferring Calls
354 New in version 3.19.
355 cmake_language(DEFER <options>... CALL <command> [<arg>...])
358 Schedules a call to the named <command> with the given arguments (if
360 any) to occur at a later time. By default, deferred calls are executed
361 as if written at the end of the current directory's CMakeLists.txt
362 file, except that they run even after a return() call. Variable refer‐
363 ences in arguments are evaluated at the time the deferred call is exe‐
364 cuted.
365 The options are:
367 DIRECTORY <dir>
369 Schedule the call for the end of the given directory instead of
370 the current directory. The <dir> may reference either a source
371 directory or its corresponding binary directory. Relative paths
372 are treated as relative to the current source directory.
373 The given directory must be known to CMake, being either the
375 top-level directory or one added by add_subdirectory(). Fur‐
376 thermore, the given directory must not yet be finished process‐
377 ing. This means it can be the current directory or one of its
378 ancestors.
379 ID <id>
381 Specify an identification for the deferred call. The <id> may
382 not be empty and may not begin with a capital letter A-Z. The
383 <id> may begin with an underscore (_) only if it was generated
384 automatically by an earlier call that used ID_VAR to get the id.
385 ID_VAR <var>
387 Specify a variable in which to store the identification for the
388 deferred call. If ID <id> is not given, a new identification
389 will be generated and the generated id will start with an under‐
390 score (_).
391 The currently scheduled list of deferred calls may be retrieved:
393 cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)
395 This will store in <var> a semicolon-separated list of deferred call
397 ids. The ids are for the directory scope in which the calls have been
398 deferred to (i.e. where they will be executed), which can be different
399 to the scope in which they were created. The DIRECTORY option can be
400 used to specify the scope for which to retrieve the call ids. If that
401 option is not given, the call ids for the current directory scope will
402 be returned.
403 Details of a specific call may be retrieved from its id:
405 cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)
407 This will store in <var> a semicolon-separated list in which the first
409 element is the name of the command to be called, and the remaining ele‐
410 ments are its unevaluated arguments (any contained ; characters are in‐
411 cluded literally and cannot be distinguished from multiple arguments).
412 If multiple calls are scheduled with the same id, this retrieves the
413 first one. If no call is scheduled with the given id in the specified
414 DIRECTORY scope (or the current directory scope if no DIRECTORY option
415 is given), this stores an empty string in the variable.
416 Deferred calls may be canceled by their id:
418 cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)
420 This cancels all deferred calls matching any of the given ids in the
422 specified DIRECTORY scope (or the current directory scope if no DIREC‐
423 TORY option is given). Unknown ids are silently ignored.
424 Deferred Call Examples
426 For example, the code:
427 cmake_language(DEFER CALL message "${deferred_message}")
429 cmake_language(DEFER ID_VAR id CALL message "Canceled Message")
430 cmake_language(DEFER CANCEL_CALL ${id})
431 message("Immediate Message")
432 set(deferred_message "Deferred Message")
433 prints:
435 Immediate Message
437 Deferred Message
438 The Cancelled Message is never printed because its command is canceled.
440 The deferred_message variable reference is not evaluated until the call
441 site, so it can be set after the deferred call is scheduled.
442 In order to evaluate variable references immediately when scheduling a
444 deferred call, wrap it using cmake_language(EVAL). However, note that
445 arguments will be re-evaluated in the deferred call, though that can be
446 avoided by using bracket arguments. For example:
447 set(deferred_message "Deferred Message 1")
449 set(re_evaluated [[${deferred_message}]])
450 cmake_language(EVAL CODE "
451 cmake_language(DEFER CALL message [[${deferred_message}]])
452 cmake_language(DEFER CALL message \"${re_evaluated}\")
453 ")
454 message("Immediate Message")
455 set(deferred_message "Deferred Message 2")
456 also prints:
458 Immediate Message
460 Deferred Message 1
461 Deferred Message 2
462 cmake_minimum_required
464 Require a minimum version of cmake.
465 cmake_minimum_required(VERSION <min>[...<policy_max>] [FATAL_ERROR])
467 New in version 3.12: The optional <policy_max> version.
469 Sets the minimum required version of cmake for a project. Also updates
472 the policy settings as explained below.
473 <min> and the optional <policy_max> are each CMake versions of the form
475 major.minor[.patch[.tweak]], and the ... is literal.
476 If the running version of CMake is lower than the <min> required ver‐
478 sion it will stop processing the project and report an error. The op‐
479 tional <policy_max> version, if specified, must be at least the <min>
480 version and affects policy settings as described in Policy Settings.
481 If the running version of CMake is older than 3.12, the extra ... dots
482 will be seen as version component separators, resulting in the ...<max>
483 part being ignored and preserving the pre-3.12 behavior of basing poli‐
484 cies on <min>.
485 This command will set the value of the CMAKE_MINIMUM_REQUIRED_VERSION
487 variable to <min>.
488 The FATAL_ERROR option is accepted but ignored by CMake 2.6 and higher.
490 It should be specified so CMake versions 2.4 and lower fail with an er‐
491 ror instead of just a warning.
492 NOTE:
494 Call the cmake_minimum_required() command at the beginning of the
495 top-level CMakeLists.txt file even before calling the project() com‐
496 mand. It is important to establish version and policy settings be‐
497 fore invoking other commands whose behavior they may affect. See
498 also policy CMP0000.
499 Calling cmake_minimum_required() inside a function() limits some ef‐
501 fects to the function scope when invoked. For example, the
502 CMAKE_MINIMUM_REQUIRED_VERSION variable won't be set in the calling
503 scope. Functions do not introduce their own policy scope though, so
504 policy settings of the caller will be affected (see below). Due to
505 this mix of things that do and do not affect the calling scope,
506 calling cmake_minimum_required() inside a function is generally dis‐
507 couraged.
508 Policy Settings
510 The cmake_minimum_required(VERSION) command implicitly invokes the
511 cmake_policy(VERSION) command to specify that the current project code
512 is written for the given range of CMake versions. All policies known
513 to the running version of CMake and introduced in the <min> (or <max>,
514 if specified) version or earlier will be set to use NEW behavior. All
515 policies introduced in later versions will be unset. This effectively
516 requests behavior preferred as of a given CMake version and tells newer
517 CMake versions to warn about their new policies.
518 When a <min> version higher than 2.4 is specified the command implic‐
520 itly invokes
521 cmake_policy(VERSION <min>[...<max>])
523 which sets CMake policies based on the range of versions specified.
525 When a <min> version 2.4 or lower is given the command implicitly in‐
526 vokes
527 cmake_policy(VERSION 2.4[...<max>])
529 which enables compatibility features for CMake 2.4 and lower.
531 cmake_parse_arguments
533 Parse function or macro arguments.
534 cmake_parse_arguments(<prefix> <options> <one_value_keywords>
536 <multi_value_keywords> <args>...)
537 cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
539 <one_value_keywords> <multi_value_keywords>)
540 New in version 3.5: This command is implemented natively. Previously,
542 it has been defined in the module CMakeParseArguments.
543 This command is for use in macros or functions. It processes the argu‐
546 ments given to that macro or function, and defines a set of variables
547 which hold the values of the respective options.
548 The first signature reads processes arguments passed in the <args>....
550 This may be used in either a macro() or a function().
551 New in version 3.7: The PARSE_ARGV signature is only for use in a func‐
553 tion() body. In this case the arguments that are parsed come from the
554 ARGV# variables of the calling function. The parsing starts with the
555 <N>-th argument, where <N> is an unsigned integer. This allows for the
556 values to have special characters like ; in them.
557 The <options> argument contains all options for the respective macro,
560 i.e. keywords which can be used when calling the macro without any
561 value following, like e.g. the OPTIONAL keyword of the install() com‐
562 mand.
563 The <one_value_keywords> argument contains all keywords for this macro
565 which are followed by one value, like e.g. DESTINATION keyword of the
566 install() command.
567 The <multi_value_keywords> argument contains all keywords for this
569 macro which can be followed by more than one value, like e.g. the TAR‐
570 GETS or FILES keywords of the install() command.
571 Changed in version 3.5: All keywords shall be unique. I.e. every key‐
573 word shall only be specified once in either <options>, <one_value_key‐
574 words> or <multi_value_keywords>. A warning will be emitted if unique‐
575 ness is violated.
576 When done, cmake_parse_arguments will consider for each of the keywords
579 listed in <options>, <one_value_keywords> and <multi_value_keywords> a
580 variable composed of the given <prefix> followed by "_" and the name of
581 the respective keyword. These variables will then hold the respective
582 value from the argument list or be undefined if the associated option
583 could not be found. For the <options> keywords, these will always be
584 defined, to TRUE or FALSE, whether the option is in the argument list
585 or not.
586 All remaining arguments are collected in a variable <prefix>_UN‐
588 PARSED_ARGUMENTS that will be undefined if all arguments were recog‐
589 nized. This can be checked afterwards to see whether your macro was
590 called with unrecognized parameters.
591 New in version 3.15: <one_value_keywords> and <multi_value_keywords>
593 that were given no values at all are collected in a variable <pre‐
594 fix>_KEYWORDS_MISSING_VALUES that will be undefined if all keywords re‐
595 ceived values. This can be checked to see if there were keywords with‐
596 out any values given.
597 Consider the following example macro, my_install(), which takes similar
600 arguments to the real install() command:
601 macro(my_install)
603 set(options OPTIONAL FAST)
604 set(oneValueArgs DESTINATION RENAME)
605 set(multiValueArgs TARGETS CONFIGURATIONS)
606 cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
607 "${multiValueArgs}" ${ARGN} )
608 # ...
610 Assume my_install() has been called like this:
612 my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)
614 After the cmake_parse_arguments call the macro will have set or unde‐
616 fined the following variables:
617 MY_INSTALL_OPTIONAL = TRUE
619 MY_INSTALL_FAST = FALSE # was not used in call to my_install
620 MY_INSTALL_DESTINATION = "bin"
621 MY_INSTALL_RENAME <UNDEFINED> # was not used
622 MY_INSTALL_TARGETS = "foo;bar"
623 MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
624 MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
625 MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS"
626 # No value for "CONFIGURATIONS" given
627 You can then continue and process these variables.
629 Keywords terminate lists of values, e.g. if directly after a
631 one_value_keyword another recognized keyword follows, this is inter‐
632 preted as the beginning of the new option. E.g. my_install(TARGETS
633 foo DESTINATION OPTIONAL) would result in MY_INSTALL_DESTINATION set to
634 "OPTIONAL", but as OPTIONAL is a keyword itself MY_INSTALL_DESTINATION
635 will be empty (but added to MY_INSTALL_KEYWORDS_MISSING_VALUES) and
636 MY_INSTALL_OPTIONAL will therefore be set to TRUE.
637 cmake_path
639 New in version 3.20.
640 This command is for the manipulation of paths. Only syntactic aspects
643 of paths are handled, there is no interaction of any kind with any un‐
644 derlying file system. The path may represent a non-existing path or
645 even one that is not allowed to exist on the current file system or
646 platform. For operations that do interact with the filesystem, see the
647 file() command.
648 NOTE:
650 The cmake_path command handles paths in the format of the build sys‐
651 tem (i.e. the host platform), not the target system. When
652 cross-compiling, if the path contains elements that are not repre‐
653 sentable on the host platform (e.g. a drive letter when the host is
654 not Windows), the results will be unpredictable.
655 Synopsis
657 Conventions
658 Path Structure And Terminology
660 Normalization
662 Decomposition
664 cmake_path(GET <path-var> ROOT_NAME <out-var>)
665 cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
666 cmake_path(GET <path-var> ROOT_PATH <out-var>)
667 cmake_path(GET <path-var> FILENAME <out-var>)
668 cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>)
669 cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)
670 cmake_path(GET <path-var> RELATIVE_PART <out-var>)
671 cmake_path(GET <path-var> PARENT_PATH <out-var>)
672 Query
674 cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
675 cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
676 cmake_path(HAS_ROOT_PATH <path-var> <out-var>)
677 cmake_path(HAS_FILENAME <path-var> <out-var>)
678 cmake_path(HAS_EXTENSION <path-var> <out-var>)
679 cmake_path(HAS_STEM <path-var> <out-var>)
680 cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)
681 cmake_path(HAS_PARENT_PATH <path-var> <out-var>)
682 cmake_path(IS_ABSOLUTE <path-var> <out-var>)
683 cmake_path(IS_RELATIVE <path-var> <out-var>)
684 cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)
685 cmake_path(COMPARE <input1> <OP> <input2> <out-var>)
686 Modification
688 cmake_path(SET <path-var> [NORMALIZE] <input>)
689 cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
690 cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
691 cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])
692 cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])
693 cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY] [OUTPUT_VARIABLE <out-var>])
694 cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input> [OUTPUT_VARIABLE <out-var>])
695 Generation
697 cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])
698 cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>] [OUTPUT_VARIABLE <out-var>])
699 cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE] [OUTPUT_VARIABLE <out-var>])
700 Native Conversion
702 cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)
703 cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])
704 cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])
705 Hashing
707 cmake_path(HASH <path-var> <out-var>)
708 Conventions
710 The following conventions are used in this command's documentation:
711 <path-var>
713 Always the name of a variable. For commands that expect a
714 <path-var> as input, the variable must exist and it is expected
715 to hold a single path.
716 <input>
718 A string literal which may contain a path, path fragment, or
719 multiple paths with a special separator depending on the com‐
720 mand. See the description of each command to see how this is
721 interpreted.
722 <input>...
724 Zero or more string literal arguments.
725 <out-var>
727 The name of a variable into which the result of a command will
728 be written.
729 Path Structure And Terminology
731 A path has the following structure (all components are optional, with
732 some constraints):
733 root-name root-directory-separator (item-name directory-separator)* filename
735 root-name
737 Identifies the root on a filesystem with multiple roots (such as
738 "C:" or "//myserver"). It is optional.
739 root-directory-separator
741 A directory separator that, if present, indicates that this path
742 is absolute. If it is missing and the first element other than
743 the root-name is an item-name, then the path is relative.
744 item-name
746 A sequence of characters that aren't directory separators. This
747 name may identify a file, a hard link, a symbolic link, or a di‐
748 rectory. Two special cases are recognized:
749 • The item name consisting of a single dot character . is a
751 directory name that refers to the current directory.
752 • The item name consisting of two dot characters .. is a di‐
754 rectory name that refers to the parent directory.
755 The (...)* pattern shown above is to indicate that there can be
757 zero or more item names, with multiple items separated by a di‐
758 rectory-separator. The ()* characters are not part of the path.
759 directory-separator
761 The only recognized directory separator is a forward slash char‐
762 acter /. If this character is repeated, it is treated as a sin‐
763 gle directory separator. In other words, /usr///////lib is the
764 same as /usr/lib.
765 filename
767 A path has a filename if it does not end with a directory-sepa‐
768 rator. The filename is effectively the last item-name of the
769 path, so it can also be a hard link, symbolic link or a direc‐
770 tory.
771 A filename can have an extension. By default, the extension is
773 defined as the sub-string beginning at the left-most period (in‐
774 cluding the period) and until the end of the filename. In com‐
775 mands that accept a LAST_ONLY keyword, LAST_ONLY changes the in‐
776 terpretation to the sub-string beginning at the right-most pe‐
777 riod.
778 The following exceptions apply to the above interpretation:
780 • If the first character in the filename is a period, that
782 period is ignored (i.e. a filename like ".profile" is
783 treated as having no extension).
784 • If the filename is either . or .., it has no extension.
786 The stem is the part of the filename before the extension.
788 Some commands refer to a root-path. This is the concatenation of
790 root-name and root-directory-separator, either or both of which can be
791 empty. A relative-part refers to the full path with any root-path re‐
792 moved.
793 Creating A Path Variable
795 While a path can be created with care using an ordinary set() command,
796 it is recommended to use cmake_path(SET) instead, as it automatically
797 converts the path to the required form where required. The
798 cmake_path(APPEND) subcommand may be another suitable alternative where
799 a path needs to be constructed by joining fragments. The following ex‐
800 ample compares the three methods for constructing the same path:
801 set(path1 "${CMAKE_CURRENT_SOURCE_DIR}/data")
803 cmake_path(SET path2 "${CMAKE_CURRENT_SOURCE_DIR}/data")
805 cmake_path(APPEND path3 "${CMAKE_CURRENT_SOURCE_DIR}" "data")
807 Modification and Generation sub-commands can either store the result
809 in-place, or in a separate variable named after an OUTPUT_VARIABLE key‐
810 word. All other sub-commands store the result in a mandatory <out-var>
811 variable.
812 Normalization
814 Some sub-commands support normalizing a path. The algorithm used to
815 normalize a path is as follows:
816 1. If the path is empty, stop (the normalized form of an empty path is
818 also an empty path).
819 2. Replace each directory-separator, which may consist of multiple sep‐
821 arators, with a single / (/a///b --> /a/b).
822 3. Remove each solitary period (.) and any immediately following direc‐
824 tory-separator (/a/./b/. --> /a/b).
825 4. Remove each item-name (other than ..) that is immediately followed
827 by a directory-separator and a .., along with any immediately fol‐
828 lowing directory-separator (/a/b/../c --> a/c).
829 5. If there is a root-directory, remove any .. and any directory-sepa‐
831 rators immediately following them. The parent of the root directory
832 is treated as still the root directory (/../a --> /a).
833 6. If the last item-name is .., remove any trailing directory-separator
835 (../ --> ..).
836 7. If the path is empty by this stage, add a dot (normal form of ./ is
838 .).
839 Decomposition
841 The following forms of the GET subcommand each retrieve a different
842 component or group of components from a path. See Path Structure And
843 Terminology for the meaning of each path component.
844 cmake_path(GET <path-var> ROOT_NAME <out-var>)
846 cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
847 cmake_path(GET <path-var> ROOT_PATH <out-var>)
848 cmake_path(GET <path-var> FILENAME <out-var>)
849 cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>)
850 cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)
851 cmake_path(GET <path-var> RELATIVE_PART <out-var>)
852 cmake_path(GET <path-var> PARENT_PATH <out-var>)
853 If a requested component is not present in the path, an empty string
855 will be stored in <out-var>. For example, only Windows systems have
856 the concept of a root-name, so when the host machine is non-Windows,
857 the ROOT_NAME subcommand will always return an empty string.
858 For PARENT_PATH, if the HAS_RELATIVE_PART subcommand returns false, the
860 result is a copy of <path-var>. Note that this implies that a root di‐
861 rectory is considered to have a parent, with that parent being itself.
862 Where HAS_RELATIVE_PART returns true, the result will essentially be
863 <path-var> with one less element.
864 Root examples
866 set(path "c:/a")
867 cmake_path(GET path ROOT_NAME rootName)
869 cmake_path(GET path ROOT_DIRECTORY rootDir)
870 cmake_path(GET path ROOT_PATH rootPath)
871 message("Root name is \"${rootName}\"")
873 message("Root directory is \"${rootDir}\"")
874 message("Root path is \"${rootPath}\"")
875 Root name is "c:"
877 Root directory is "/"
878 Root path is "c:/"
879 Filename examples
881 set(path "/a/b")
882 cmake_path(GET path FILENAME filename)
883 message("First filename is \"${filename}\"")
884 # Trailing slash means filename is empty
886 set(path "/a/b/")
887 cmake_path(GET path FILENAME filename)
888 message("Second filename is \"${filename}\"")
889 First filename is "b"
891 Second filename is ""
892 Extension and stem examples
894 set(path "name.ext1.ext2")
895 cmake_path(GET path EXTENSION fullExt)
897 cmake_path(GET path STEM fullStem)
898 message("Full extension is \"${fullExt}\"")
899 message("Full stem is \"${fullStem}\"")
900 # Effect of LAST_ONLY
902 cmake_path(GET path EXTENSION LAST_ONLY lastExt)
903 cmake_path(GET path STEM LAST_ONLY lastStem)
904 message("Last extension is \"${lastExt}\"")
905 message("Last stem is \"${lastStem}\"")
906 # Special cases
908 set(dotPath "/a/.")
909 set(dotDotPath "/a/..")
910 set(someMorePath "/a/.some.more")
911 cmake_path(GET dotPath EXTENSION dotExt)
912 cmake_path(GET dotPath STEM dotStem)
913 cmake_path(GET dotDotPath EXTENSION dotDotExt)
914 cmake_path(GET dotDotPath STEM dotDotStem)
915 cmake_path(GET dotMorePath EXTENSION someMoreExt)
916 cmake_path(GET dotMorePath STEM someMoreStem)
917 message("Dot extension is \"${dotExt}\"")
918 message("Dot stem is \"${dotStem}\"")
919 message("Dot-dot extension is \"${dotDotExt}\"")
920 message("Dot-dot stem is \"${dotDotStem}\"")
921 message(".some.more extension is \"${someMoreExt}\"")
922 message(".some.more stem is \"${someMoreStem}\"")
923 Full extension is ".ext1.ext2"
925 Full stem is "name"
926 Last extension is ".ext2"
927 Last stem is "name.ext1"
928 Dot extension is ""
929 Dot stem is "."
930 Dot-dot extension is ""
931 Dot-dot stem is ".."
932 .some.more extension is ".more"
933 .some.more stem is ".some"
934 Relative part examples
936 set(path "c:/a/b")
937 cmake_path(GET path RELATIVE_PART result)
938 message("Relative part is \"${result}\"")
939 set(path "c/d")
941 cmake_path(GET path RELATIVE_PART result)
942 message("Relative part is \"${result}\"")
943 set(path "/")
945 cmake_path(GET path RELATIVE_PART result)
946 message("Relative part is \"${result}\"")
947 Relative part is "a/b"
949 Relative part is "c/d"
950 Relative part is ""
951 Path traversal examples
953 set(path "c:/a/b")
954 cmake_path(GET path PARENT_PATH result)
955 message("Parent path is \"${result}\"")
956 set(path "c:/")
958 cmake_path(GET path PARENT_PATH result)
959 message("Parent path is \"${result}\"")
960 Parent path is "c:/a"
962 Parent path is "c:/"
963 Query
965 Each of the GET subcommands has a corresponding HAS_... subcommand
966 which can be used to discover whether a particular path component is
967 present. See Path Structure And Terminology for the meaning of each
968 path component.
969 cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
971 cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
972 cmake_path(HAS_ROOT_PATH <path-var> <out-var>)
973 cmake_path(HAS_FILENAME <path-var> <out-var>)
974 cmake_path(HAS_EXTENSION <path-var> <out-var>)
975 cmake_path(HAS_STEM <path-var> <out-var>)
976 cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)
977 cmake_path(HAS_PARENT_PATH <path-var> <out-var>)
978 Each of the above follows the predictable pattern of setting <out-var>
980 to true if the path has the associated component, or false otherwise.
981 Note the following special cases:
982 • For HAS_ROOT_PATH, a true result will only be returned if at least
984 one of root-name or root-directory is non-empty.
985 • For HAS_PARENT_PATH, the root directory is also considered to have a
987 parent, which will be itself. The result is true except if the path
988 consists of just a filename.
989 cmake_path(IS_ABSOLUTE <path-var> <out-var>)
991 Sets <out-var> to true if <path-var> is absolute. An absolute path is
993 a path that unambiguously identifies the location of a file without
994 reference to an additional starting location. On Windows, this means
995 the path must have both a root-name and a root-directory-separator to
996 be considered absolute. On other platforms, just a root-directory-sep‐
997 arator is sufficient. Note that this means on Windows, IS_ABSOLUTE can
998 be false while HAS_ROOT_DIRECTORY can be true.
999 cmake_path(IS_RELATIVE <path-var> <out-var>)
1001 This will store the opposite of IS_ABSOLUTE in <out-var>.
1003 cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)
1005 Checks if <path-var> is the prefix of <input>.
1007 When the NORMALIZE option is specified, <path-var> and <input> are
1009 normalized before the check.
1010 set(path "/a/b/c")
1012 cmake_path(IS_PREFIX path "/a/b/c/d" result) # result = true
1013 cmake_path(IS_PREFIX path "/a/b" result) # result = false
1014 cmake_path(IS_PREFIX path "/x/y/z" result) # result = false
1015 set(path "/a/b")
1017 cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result) # result = true
1018 cmake_path(COMPARE <input1> EQUAL <input2> <out-var>)
1020 cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>)
1021 Compares the lexical representations of two paths provided as string
1023 literals. No normalization is performed on either path. Equality is
1024 determined according to the following pseudo-code logic:
1025 if(NOT <input1>.root_name() STREQUAL <input2>.root_name())
1027 return FALSE
1028 if(<input1>.has_root_directory() XOR <input2>.has_root_directory())
1030 return FALSE
1031 Return FALSE if a relative portion of <input1> is not lexicographically
1033 equal to the relative portion of <input2>. This comparison is performed path
1034 component-wise. If all of the components compare equal, then return TRUE.
1035 NOTE:
1037 Unlike most other cmake_path() subcommands, the COMPARE subcommand
1038 takes literal strings as input, not the names of variables.
1039 Modification
1041 cmake_path(SET <path-var> [NORMALIZE] <input>)
1042 Assign the <input> path to <path-var>. If <input> is a native path, it
1044 is converted into a cmake-style path with forward-slashes (/). On Win‐
1045 dows, the long filename marker is taken into account.
1046 When the NORMALIZE option is specified, the path is normalized before
1048 the conversion.
1049 For example:
1051 set(native_path "c:\\a\\b/..\\c")
1053 cmake_path(SET path "${native_path}")
1054 message("CMake path is \"${path}\"")
1055 cmake_path(SET path NORMALIZE "${native_path}")
1057 message("Normalized CMake path is \"${path}\"")
1058 Output:
1060 CMake path is "c:/a/b/../c"
1062 Normalized CMake path is "c:/a/c"
1063 cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
1065 Append all the <input> arguments to the <path-var> using / as the di‐
1067 rectory-separator. Depending on the <input>, the previous contents of
1068 <path-var> may be discarded. For each <input> argument, the following
1069 algorithm (pseudo-code) applies:
1070 # <path> is the contents of <path-var>
1072 if(<input>.is_absolute() OR
1074 (<input>.has_root_name() AND
1075 NOT <input>.root_name() STREQUAL <path>.root_name()))
1076 replace <path> with <input>
1077 return()
1078 endif()
1079 if(<input>.has_root_directory())
1081 remove any root-directory and the entire relative path from <path>
1082 elseif(<path>.has_filename() OR
1083 (NOT <path-var>.has_root_directory() OR <path>.is_absolute()))
1084 append directory-separator to <path>
1085 endif()
1086 append <input> omitting any root-name to <path>
1088 cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
1090 Append all the <input> arguments to the <path-var> without adding any
1092 directory-separator.
1093 cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])
1095 Removes the filename component (as returned by GET ... FILENAME) from
1097 <path-var>. After removal, any trailing directory-separator is left
1098 alone, if present.
1099 If OUTPUT_VARIABLE is not given, then after this function returns,
1101 HAS_FILENAME returns false for <path-var>.
1102 For example:
1104 set(path "/a/b")
1106 cmake_path(REMOVE_FILENAME path)
1107 message("First path is \"${path}\"")
1108 # filename is now already empty, the following removes nothing
1110 cmake_path(REMOVE_FILENAME path)
1111 message("Second path is \"${result}\"")
1112 Output:
1114 First path is "/a/"
1116 Second path is "/a/"
1117 cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])
1119 Replaces the filename component from <path-var> with <input>. If
1121 <path-var> has no filename component (i.e. HAS_FILENAME returns
1122 false), the path is unchanged. The operation is equivalent to the fol‐
1123 lowing:
1124 cmake_path(HAS_FILENAME path has_filename)
1126 if(has_filename)
1127 cmake_path(REMOVE_FILENAME path)
1128 cmake_path(APPEND path input);
1129 endif()
1130 cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY]
1132 [OUTPUT_VARIABLE <out-var>])
1133 Removes the extension, if any, from <path-var>.
1135 cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input>
1137 [OUTPUT_VARIABLE <out-var>])
1138 Replaces the extension with <input>. Its effect is equivalent to the
1140 following:
1141 cmake_path(REMOVE_EXTENSION path)
1143 if(NOT "input" MATCHES "^\\.")
1144 cmake_path(APPEND_STRING path ".")
1145 endif()
1146 cmake_path(APPEND_STRING path "input")
1147 Generation
1149 cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])
1150 Normalize <path-var> according the steps described in Normalization.
1152 cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>]
1154 [OUTPUT_VARIABLE <out-var>])
1155 Modifies <path-var> to make it relative to the BASE_DIRECTORY argument.
1157 If BASE_DIRECTORY is not specified, the default base directory will be
1158 CMAKE_CURRENT_SOURCE_DIR.
1159 For reference, the algorithm used to compute the relative path is the
1161 same as that used by C++ std::filesystem::path::lexically_relative.
1162 cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE]
1164 [OUTPUT_VARIABLE <out-var>])
1165 If <path-var> is a relative path (IS_RELATIVE is true), it is evaluated
1167 relative to the given base directory specified by BASE_DIRECTORY op‐
1168 tion. If BASE_DIRECTORY is not specified, the default base directory
1169 will be CMAKE_CURRENT_SOURCE_DIR.
1170 When the NORMALIZE option is specified, the path is normalized after
1172 the path computation.
1173 Because cmake_path() does not access the filesystem, symbolic links are
1175 not resolved and any leading tilde is not expanded. To compute a real
1176 path with symbolic links resolved and leading tildes expanded, use the
1177 file(REAL_PATH) command instead.
1178 Native Conversion
1180 For commands in this section, native refers to the host platform, not
1181 the target platform when cross-compiling.
1182 cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)
1184 Converts a cmake-style <path-var> into a native path with platform-spe‐
1186 cific slashes (\ on Windows hosts and / elsewhere).
1187 When the NORMALIZE option is specified, the path is normalized before
1189 the conversion.
1190 cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])
1192 Converts a native <input> path into a cmake-style path with forward
1194 slashes (/). On Windows hosts, the long filename marker is taken into
1195 account. The input can be a single path or a system search path like
1196 $ENV{PATH}. A search path will be converted to a cmake-style list sep‐
1197 arated by ; characters (on non-Windows platforms, this essentially
1198 means : separators are replaced with ;). The result of the conversion
1199 is stored in the <out-var> variable.
1200 When the NORMALIZE option is specified, the path is normalized before
1202 the conversion.
1203 NOTE:
1205 Unlike most other cmake_path() subcommands, the CONVERT subcommand
1206 takes a literal string as input, not the name of a variable.
1207 cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])
1209 Converts a cmake-style <input> path into a native path with plat‐
1211 form-specific slashes (\ on Windows hosts and / elsewhere). The input
1212 can be a single path or a cmake-style list. A list will be converted
1213 into a native search path (;-separated on Windows, :-separated on other
1214 platforms). The result of the conversion is stored in the <out-var>
1215 variable.
1216 When the NORMALIZE option is specified, the path is normalized before
1218 the conversion.
1219 NOTE:
1221 Unlike most other cmake_path() subcommands, the CONVERT subcommand
1222 takes a literal string as input, not the name of a variable.
1223 For example:
1225 set(paths "/a/b/c" "/x/y/z")
1227 cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths)
1228 message("Native path list is \"${native_paths}\"")
1229 Output on Windows:
1231 Native path list is "\a\b\c;\x\y\z"
1233 Output on all other platforms:
1235 Native path list is "/a/b/c:/x/y/z"
1237 Hashing
1239 cmake_path(HASH <path-var> <out-var>)
1240 Compute a hash value of <path-var> such that for two paths p1 and p2
1242 that compare equal (COMPARE ... EQUAL), the hash value of p1 is equal
1243 to the hash value of p2. The path is always normalized before the hash
1244 is computed.
1245 cmake_policy
1247 Manage CMake Policy settings. See the cmake-policies(7) manual for de‐
1248 fined policies.
1249 As CMake evolves it is sometimes necessary to change existing behavior
1251 in order to fix bugs or improve implementations of existing features.
1252 The CMake Policy mechanism is designed to help keep existing projects
1253 building as new versions of CMake introduce changes in behavior. Each
1254 new policy (behavioral change) is given an identifier of the form
1255 CMP<NNNN> where <NNNN> is an integer index. Documentation associated
1256 with each policy describes the OLD and NEW behavior and the reason the
1257 policy was introduced. Projects may set each policy to select the de‐
1258 sired behavior. When CMake needs to know which behavior to use it
1259 checks for a setting specified by the project. If no setting is avail‐
1260 able the OLD behavior is assumed and a warning is produced requesting
1261 that the policy be set.
1262 Setting Policies by CMake Version
1264 The cmake_policy command is used to set policies to OLD or NEW behav‐
1265 ior. While setting policies individually is supported, we encourage
1266 projects to set policies based on CMake versions:
1267 cmake_policy(VERSION <min>[...<max>])
1269 New in version 3.12: The optional <max> version.
1271 <min> and the optional <max> are each CMake versions of the form ma‐
1274 jor.minor[.patch[.tweak]], and the ... is literal. The <min> version
1275 must be at least 2.4 and at most the running version of CMake. The
1276 <max> version, if specified, must be at least the <min> version but may
1277 exceed the running version of CMake. If the running version of CMake
1278 is older than 3.12, the extra ... dots will be seen as version compo‐
1279 nent separators, resulting in the ...<max> part being ignored and pre‐
1280 serving the pre-3.12 behavior of basing policies on <min>.
1281 This specifies that the current CMake code is written for the given
1283 range of CMake versions. All policies known to the running version of
1284 CMake and introduced in the <min> (or <max>, if specified) version or
1285 earlier will be set to use NEW behavior. All policies introduced in
1286 later versions will be unset (unless the CMAKE_POLICY_DEFAULT_CMP<NNNN>
1287 variable sets a default). This effectively requests behavior preferred
1288 as of a given CMake version and tells newer CMake versions to warn
1289 about their new policies.
1290 Note that the cmake_minimum_required(VERSION) command implicitly calls
1292 cmake_policy(VERSION) too.
1293 Setting Policies Explicitly
1295 cmake_policy(SET CMP<NNNN> NEW)
1296 cmake_policy(SET CMP<NNNN> OLD)
1297 Tell CMake to use the OLD or NEW behavior for a given policy. Projects
1299 depending on the old behavior of a given policy may silence a policy
1300 warning by setting the policy state to OLD. Alternatively one may fix
1301 the project to work with the new behavior and set the policy state to
1302 NEW.
1303 NOTE:
1305 The OLD behavior of a policy is deprecated by definition and may be
1306 removed in a future version of CMake.
1307 Checking Policy Settings
1309 cmake_policy(GET CMP<NNNN> <variable>)
1310 Check whether a given policy is set to OLD or NEW behavior. The output
1312 <variable> value will be OLD or NEW if the policy is set, and empty
1313 otherwise.
1314 CMake Policy Stack
1316 CMake keeps policy settings on a stack, so changes made by the
1317 cmake_policy command affect only the top of the stack. A new entry on
1318 the policy stack is managed automatically for each subdirectory to pro‐
1319 tect its parents and siblings. CMake also manages a new entry for
1320 scripts loaded by include() and find_package() commands except when in‐
1321 voked with the NO_POLICY_SCOPE option (see also policy CMP0011). The
1322 cmake_policy command provides an interface to manage custom entries on
1323 the policy stack:
1324 cmake_policy(PUSH)
1326 cmake_policy(POP)
1327 Each PUSH must have a matching POP to erase any changes. This is use‐
1329 ful to make temporary changes to policy settings. Calls to the
1330 cmake_minimum_required(VERSION), cmake_policy(VERSION), or cmake_pol‐
1331 icy(SET) commands influence only the current top of the policy stack.
1332 Commands created by the function() and macro() commands record policy
1334 settings when they are created and use the pre-record policies when
1335 they are invoked. If the function or macro implementation sets poli‐
1336 cies, the changes automatically propagate up through callers until they
1337 reach the closest nested policy stack entry.
1338 configure_file
1340 Copy a file to another location and modify its contents.
1341 configure_file(<input> <output>
1343 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
1344 FILE_PERMISSIONS <permissions>...]
1345 [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
1346 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
1347 Copies an <input> file to an <output> file and substitutes variable
1349 values referenced as @VAR@ or ${VAR} in the input file content. Each
1350 variable reference will be replaced with the current value of the vari‐
1351 able, or the empty string if the variable is not defined. Furthermore,
1352 input lines of the form
1353 #cmakedefine VAR ...
1355 will be replaced with either
1357 #define VAR ...
1359 or
1361 /* #undef VAR */
1363 depending on whether VAR is set in CMake to any value not considered a
1365 false constant by the if() command. The "..." content on the line af‐
1366 ter the variable name, if any, is processed as above.
1367 Unlike lines of the form #cmakedefine VAR ..., in lines of the form
1369 #cmakedefine01 VAR, VAR itself will expand to VAR 0 or VAR 1 rather
1370 than being assigned the value .... Therefore, input lines of the form
1371 #cmakedefine01 VAR
1373 will be replaced with either
1375 #define VAR 0
1377 or
1379 #define VAR 1
1381 Input lines of the form #cmakedefine01 VAR ... will expand as #cmakede‐
1383 fine01 VAR ... 0 or #cmakedefine01 VAR ... 0, which may lead to unde‐
1384 fined behavior.
1385 New in version 3.10: The result lines (with the exception of the #undef
1387 comments) can be indented using spaces and/or tabs between the # char‐
1388 acter and the cmakedefine or cmakedefine01 words. This whitespace in‐
1389 dentation will be preserved in the output lines:
1390 # cmakedefine VAR
1392 # cmakedefine01 VAR
1393 will be replaced, if VAR is defined, with
1395 # define VAR
1397 # define VAR 1
1398 If the input file is modified the build system will re-run CMake to
1401 re-configure the file and generate the build system again. The gener‐
1402 ated file is modified and its timestamp updated on subsequent cmake
1403 runs only if its content is changed.
1404 The arguments are:
1406 <input>
1408 Path to the input file. A relative path is treated with respect
1409 to the value of CMAKE_CURRENT_SOURCE_DIR. The input path must
1410 be a file, not a directory.
1411 <output>
1413 Path to the output file or directory. A relative path is
1414 treated with respect to the value of CMAKE_CURRENT_BINARY_DIR.
1415 If the path names an existing directory the output file is
1416 placed in that directory with the same file name as the input
1417 file. If the path contains non-existent directories, they are
1418 created.
1419 NO_SOURCE_PERMISSIONS
1421 New in version 3.19.
1422 Do not transfer the permissions of the input file to the output
1425 file. The copied file permissions default to the standard 644
1426 value (-rw-r--r--).
1427 USE_SOURCE_PERMISSIONS
1429 New in version 3.20.
1430 Transfer the permissions of the input file to the output file.
1433 This is already the default behavior if none of the three per‐
1434 missions-related keywords are given (NO_SOURCE_PERMISSIONS,
1435 USE_SOURCE_PERMISSIONS or FILE_PERMISSIONS). The
1436 USE_SOURCE_PERMISSIONS keyword mostly serves as a way of making
1437 the intended behavior clearer at the call site.
1438 FILE_PERMISSIONS <permissions>...
1440 New in version 3.20.
1441 Ignore the input file's permissions and use the specified <per‐
1444 missions> for the output file instead.
1445 COPYONLY
1447 Copy the file without replacing any variable references or other
1448 content. This option may not be used with NEWLINE_STYLE.
1449 ESCAPE_QUOTES
1451 Escape any substituted quotes with backslashes (C-style).
1452 @ONLY Restrict variable replacement to references of the form @VAR@.
1454 This is useful for configuring scripts that use ${VAR} syntax.
1455 NEWLINE_STYLE <style>
1457 Specify the newline style for the output file. Specify UNIX or
1458 LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n new‐
1459 lines. This option may not be used with COPYONLY.
1460 Example
1462 Consider a source tree containing a foo.h.in file:
1463 #cmakedefine FOO_ENABLE
1465 #cmakedefine FOO_STRING "@FOO_STRING@"
1466 An adjacent CMakeLists.txt may use configure_file to configure the
1468 header:
1469 option(FOO_ENABLE "Enable Foo" ON)
1471 if(FOO_ENABLE)
1472 set(FOO_STRING "foo")
1473 endif()
1474 configure_file(foo.h.in foo.h @ONLY)
1475 This creates a foo.h in the build directory corresponding to this
1477 source directory. If the FOO_ENABLE option is on, the configured file
1478 will contain:
1479 #define FOO_ENABLE
1481 #define FOO_STRING "foo"
1482 Otherwise it will contain:
1484 /* #undef FOO_ENABLE */
1486 /* #undef FOO_STRING */
1487 One may then use the include_directories() command to specify the out‐
1489 put directory as an include directory:
1490 include_directories(${CMAKE_CURRENT_BINARY_DIR})
1492 so that sources may include the header as #include <foo.h>.
1494 continue
1496 New in version 3.2.
1497 Continue to the top of enclosing foreach or while loop.
1500 continue()
1502 The continue command allows a cmake script to abort the rest of a block
1504 in a foreach() or while() loop, and start at the top of the next itera‐
1505 tion.
1506 See also the break() command.
1508 else
1510 Starts the else portion of an if block.
1511 else([<condition>])
1513 See the if() command.
1515 elseif
1517 Starts an elseif portion of an if block.
1518 elseif(<condition>)
1520 See the if() command, especially for the syntax and logic of the <con‐
1522 dition>.
1523 endforeach
1525 Ends a list of commands in a foreach block.
1526 endforeach([<loop_var>])
1528 See the foreach() command.
1530 The optional <loop_var> argument is supported for backward compatibil‐
1532 ity only. If used it must be a verbatim repeat of the <loop_var> argu‐
1533 ment of the opening foreach clause.
1534 endfunction
1536 Ends a list of commands in a function block.
1537 endfunction([<name>])
1539 See the function() command.
1541 The optional <name> argument is supported for backward compatibility
1543 only. If used it must be a verbatim repeat of the <name> argument of
1544 the opening function command.
1545 endif
1547 Ends a list of commands in an if block.
1548 endif([<condition>])
1550 See the if() command.
1552 The optional <condition> argument is supported for backward compatibil‐
1554 ity only. If used it must be a verbatim repeat of the argument of the
1555 opening if clause.
1556 endmacro
1558 Ends a list of commands in a macro block.
1559 endmacro([<name>])
1561 See the macro() command.
1563 The optional <name> argument is supported for backward compatibility
1565 only. If used it must be a verbatim repeat of the <name> argument of
1566 the opening macro command.
1567 endwhile
1569 Ends a list of commands in a while block.
1570 endwhile([<condition>])
1572 See the while() command.
1574 The optional <condition> argument is supported for backward compatibil‐
1576 ity only. If used it must be a verbatim repeat of the argument of the
1577 opening while clause.
1578 execute_process
1580 Execute one or more child processes.
1581 execute_process(COMMAND <cmd1> [<arguments>]
1583 [COMMAND <cmd2> [<arguments>]]...
1584 [WORKING_DIRECTORY <directory>]
1585 [TIMEOUT <seconds>]
1586 [RESULT_VARIABLE <variable>]
1587 [RESULTS_VARIABLE <variable>]
1588 [OUTPUT_VARIABLE <variable>]
1589 [ERROR_VARIABLE <variable>]
1590 [INPUT_FILE <file>]
1591 [OUTPUT_FILE <file>]
1592 [ERROR_FILE <file>]
1593 [OUTPUT_QUIET]
1594 [ERROR_QUIET]
1595 [COMMAND_ECHO <where>]
1596 [OUTPUT_STRIP_TRAILING_WHITESPACE]
1597 [ERROR_STRIP_TRAILING_WHITESPACE]
1598 [ENCODING <name>]
1599 [ECHO_OUTPUT_VARIABLE]
1600 [ECHO_ERROR_VARIABLE]
1601 [COMMAND_ERROR_IS_FATAL <ANY|LAST>])
1602 Runs the given sequence of one or more commands.
1604 Commands are executed concurrently as a pipeline, with the standard
1606 output of each process piped to the standard input of the next. A sin‐
1607 gle standard error pipe is used for all processes.
1608 Options:
1610 COMMAND
1612 A child process command line.
1613 CMake executes the child process using operating system APIs di‐
1615 rectly. All arguments are passed VERBATIM to the child process.
1616 No intermediate shell is used, so shell operators such as > are
1617 treated as normal arguments. (Use the INPUT_*, OUTPUT_*, and
1618 ERROR_* options to redirect stdin, stdout, and stderr.)
1619 If a sequential execution of multiple commands is required, use
1621 multiple execute_process() calls with a single COMMAND argument.
1622 WORKING_DIRECTORY
1624 The named directory will be set as the current working directory
1625 of the child processes.
1626 TIMEOUT
1628 After the specified number of seconds (fractions allowed), all
1629 unfinished child processes will be terminated, and the RE‐
1630 SULT_VARIABLE will be set to a string mentioning the "timeout".
1631 RESULT_VARIABLE
1633 The variable will be set to contain the result of last child
1634 process. This will be an integer return code from the last
1635 child or a string describing an error condition.
1636 RESULTS_VARIABLE <variable>
1638 New in version 3.10.
1639 The variable will be set to contain the result of all processes
1642 as a semicolon-separated list, in order of the given COMMAND ar‐
1643 guments. Each entry will be an integer return code from the
1644 corresponding child or a string describing an error condition.
1645 OUTPUT_VARIABLE, ERROR_VARIABLE
1647 The variable named will be set with the contents of the standard
1648 output and standard error pipes, respectively. If the same
1649 variable is named for both pipes their output will be merged in
1650 the order produced.
1651 INPUT_FILE, OUTPUT_FILE, ERROR_FILE
1653 The file named will be attached to the standard input of the
1654 first process, standard output of the last process, or standard
1655 error of all processes, respectively.
1656 New in version 3.3: If the same file is named for both output
1658 and error then it will be used for both.
1659 OUTPUT_QUIET, ERROR_QUIET
1662 The standard output or standard error results will be quietly
1663 ignored.
1664 COMMAND_ECHO <where>
1666 New in version 3.15.
1667 The command being run will be echo'ed to <where> with <where>
1670 being set to one of STDERR, STDOUT or NONE. See the CMAKE_EXE‐
1671 CUTE_PROCESS_COMMAND_ECHO variable for a way to control the de‐
1672 fault behavior when this option is not present.
1673 ENCODING <name>
1675 New in version 3.8.
1676 On Windows, the encoding that is used to decode output from the
1679 process. Ignored on other platforms. Valid encoding names are:
1680 NONE Perform no decoding. This assumes that the process out‐
1682 put is encoded in the same way as CMake's internal encod‐
1683 ing (UTF-8). This is the default.
1684 AUTO Use the current active console's codepage or if that
1686 isn't available then use ANSI.
1687 ANSI Use the ANSI codepage.
1689 OEM Use the original equipment manufacturer (OEM) code page.
1691 UTF8 or UTF-8
1693 Use the UTF-8 codepage.
1694 New in version 3.11: Accept UTF-8 spelling for consis‐
1696 tency with the UTF-8 RFC naming convention.
1697 ECHO_OUTPUT_VARIABLE, ECHO_ERROR_VARIABLE
1700 New in version 3.18.
1701 The standard output or standard error will not be exclusively
1704 redirected to the configured variables.
1705 The output will be duplicated, it will be sent into the config‐
1707 ured variables and also on standard output or standard error.
1708 This is analogous to the tee Unix command.
1710 COMMAND_ERROR_IS_FATAL <ANY|LAST>
1712 New in version 3.19.
1713 The option following COMMAND_ERROR_IS_FATAL determines the be‐
1716 havior when an error is encountered:
1717 ANY If any of the commands in the list of commands fail, the
1718 execute_process() command halts with an error.
1719 LAST If the last command in the list of commands fails, the
1721 execute_process() command halts with an error. Commands ear‐
1722 lier in the list will not cause a fatal error.
1723 If more than one OUTPUT_* or ERROR_* option is given for the same pipe
1725 the precedence is not specified. If no OUTPUT_* or ERROR_* options are
1726 given the output will be shared with the corresponding pipes of the
1727 CMake process itself.
1728 The execute_process() command is a newer more powerful version of
1730 exec_program(), but the old command has been kept for compatibility.
1731 Both commands run while CMake is processing the project prior to build
1732 system generation. Use add_custom_target() and add_custom_command() to
1733 create custom commands that run at build time.
1734 file
1736 File manipulation command.
1737 This command is dedicated to file and path manipulation requiring ac‐
1739 cess to the filesystem.
1740 For other path manipulation, handling only syntactic aspects, have a
1742 look at cmake_path() command.
1743 NOTE:
1745 The sub-commands RELATIVE_PATH, TO_CMAKE_PATH and TO_NATIVE_PATH has
1746 been superseded, respectively, by sub-commands RELATIVE_PATH, CON‐
1747 VERT ... TO_CMAKE_PATH_LIST and CONVERT ... TO_NATIVE_PATH_LIST of
1748 cmake_path() command.
1749 Synopsis
1751 Reading
1752 file(READ <filename> <out-var> [...])
1753 file(STRINGS <filename> <out-var> [...])
1754 file(<HASH> <filename> <out-var>)
1755 file(TIMESTAMP <filename> <out-var> [...])
1756 file(GET_RUNTIME_DEPENDENCIES [...])
1757 Writing
1759 file({WRITE | APPEND} <filename> <content>...)
1760 file({TOUCH | TOUCH_NOCREATE} [<file>...])
1761 file(GENERATE OUTPUT <output-file> [...])
1762 file(CONFIGURE OUTPUT <output-file> CONTENT <content> [...])
1763 Filesystem
1765 file({GLOB | GLOB_RECURSE} <out-var> [...] [<globbing-expr>...])
1766 file(MAKE_DIRECTORY [<dir>...])
1767 file({REMOVE | REMOVE_RECURSE } [<files>...])
1768 file(RENAME <oldname> <newname> [...])
1769 file(COPY_FILE <oldname> <newname> [...])
1770 file({COPY | INSTALL} <file>... DESTINATION <dir> [...])
1771 file(SIZE <filename> <out-var>)
1772 file(READ_SYMLINK <linkname> <out-var>)
1773 file(CREATE_LINK <original> <linkname> [...])
1774 file(CHMOD <files>... <directories>... PERMISSIONS <permissions>... [...])
1775 file(CHMOD_RECURSE <files>... <directories>... PERMISSIONS <permissions>... [...])
1776 Path Conversion
1778 file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])
1779 file(RELATIVE_PATH <out-var> <directory> <file>)
1780 file({TO_CMAKE_PATH | TO_NATIVE_PATH} <path> <out-var>)
1781 Transfer
1783 file(DOWNLOAD <url> [<file>] [...])
1784 file(UPLOAD <file> <url> [...])
1785 Locking
1787 file(LOCK <path> [...])
1788 Archiving
1790 file(ARCHIVE_CREATE OUTPUT <archive> PATHS <paths>... [...])
1791 file(ARCHIVE_EXTRACT INPUT <archive> [...])
1792 Reading
1794 file(READ <filename> <variable>
1795 [OFFSET <offset>] [LIMIT <max-in>] [HEX])
1796 Read content from a file called <filename> and store it in a <vari‐
1798 able>. Optionally start from the given <offset> and read at most
1799 <max-in> bytes. The HEX option causes data to be converted to a hexa‐
1800 decimal representation (useful for binary data). If the HEX option is
1801 specified, letters in the output (a through f) are in lowercase.
1802 file(STRINGS <filename> <variable> [<options>...])
1804 Parse a list of ASCII strings from <filename> and store it in <vari‐
1806 able>. Binary data in the file are ignored. Carriage return (\r, CR)
1807 characters are ignored. The options are:
1808 LENGTH_MAXIMUM <max-len>
1810 Consider only strings of at most a given length.
1811 LENGTH_MINIMUM <min-len>
1813 Consider only strings of at least a given length.
1814 LIMIT_COUNT <max-num>
1816 Limit the number of distinct strings to be extracted.
1817 LIMIT_INPUT <max-in>
1819 Limit the number of input bytes to read from the file.
1820 LIMIT_OUTPUT <max-out>
1822 Limit the number of total bytes to store in the <variable>.
1823 NEWLINE_CONSUME
1825 Treat newline characters (\n, LF) as part of string content in‐
1826 stead of terminating at them.
1827 NO_HEX_CONVERSION
1829 Intel Hex and Motorola S-record files are automatically con‐
1830 verted to binary while reading unless this option is given.
1831 REGEX <regex>
1833 Consider only strings that match the given regular expression,
1834 as described under string(REGEX).
1835 ENCODING <encoding-type>
1837 New in version 3.1.
1838 Consider strings of a given encoding. Currently supported en‐
1841 codings are: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. If
1842 the ENCODING option is not provided and the file has a Byte Or‐
1843 der Mark, the ENCODING option will be defaulted to respect the
1844 Byte Order Mark.
1845 New in version 3.2: Added the UTF-16LE, UTF-16BE, UTF-32LE,
1847 UTF-32BE encodings.
1848 For example, the code
1851 file(STRINGS myfile.txt myfile)
1853 stores a list in the variable myfile in which each item is a line from
1855 the input file.
1856 file(<HASH> <filename> <variable>)
1858 Compute a cryptographic hash of the content of <filename> and store it
1860 in a <variable>. The supported <HASH> algorithm names are those listed
1861 by the string(<HASH>) command.
1862 file(TIMESTAMP <filename> <variable> [<format>] [UTC])
1864 Compute a string representation of the modification time of <filename>
1866 and store it in <variable>. Should the command be unable to obtain a
1867 timestamp variable will be set to the empty string ("").
1868 See the string(TIMESTAMP) command for documentation of the <format> and
1870 UTC options.
1871 file(GET_RUNTIME_DEPENDENCIES
1873 [RESOLVED_DEPENDENCIES_VAR <deps_var>]
1874 [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
1875 [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
1876 [EXECUTABLES [<executable_files>...]]
1877 [LIBRARIES [<library_files>...]]
1878 [MODULES [<module_files>...]]
1879 [DIRECTORIES [<directories>...]]
1880 [BUNDLE_EXECUTABLE <bundle_executable_file>]
1881 [PRE_INCLUDE_REGEXES [<regexes>...]]
1882 [PRE_EXCLUDE_REGEXES [<regexes>...]]
1883 [POST_INCLUDE_REGEXES [<regexes>...]]
1884 [POST_EXCLUDE_REGEXES [<regexes>...]]
1885 [POST_INCLUDE_FILES [<files>...]]
1886 [POST_EXCLUDE_FILES [<files>...]]
1887 )
1888 New in version 3.16.
1890 Recursively get the list of libraries depended on by the given files.
1893 Please note that this sub-command is not intended to be used in project
1895 mode. It is intended for use at install time, either from code gener‐
1896 ated by the install(RUNTIME_DEPENDENCY_SET) command, or from code pro‐
1897 vided by the project via install(CODE) or install(SCRIPT). For exam‐
1898 ple:
1899 install(CODE [[
1901 file(GET_RUNTIME_DEPENDENCIES
1902 # ...
1903 )
1904 ]])
1905 The arguments are as follows:
1907 RESOLVED_DEPENDENCIES_VAR <deps_var>
1909 Name of the variable in which to store the list of resolved de‐
1910 pendencies.
1911 UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>
1913 Name of the variable in which to store the list of unresolved
1914 dependencies. If this variable is not specified, and there are
1915 any unresolved dependencies, an error is issued.
1916 CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>
1918 Variable prefix in which to store conflicting dependency infor‐
1919 mation. Dependencies are conflicting if two files with the same
1920 name are found in two different directories. The list of file‐
1921 names that conflict are stored in <conflicting_deps_pre‐
1922 fix>_FILENAMES. For each filename, the list of paths that were
1923 found for that filename are stored in <conflicting_deps_pre‐
1924 fix>_<filename>.
1925 EXECUTABLES <executable_files>
1927 List of executable files to read for dependencies. These are ex‐
1928 ecutables that are typically created with add_executable(), but
1929 they do not have to be created by CMake. On Apple platforms, the
1930 paths to these files determine the value of @executable_path
1931 when recursively resolving the libraries. Specifying any kind
1932 of library (STATIC, MODULE, or SHARED) here will result in unde‐
1933 fined behavior.
1934 LIBRARIES <library_files>
1936 List of library files to read for dependencies. These are li‐
1937 braries that are typically created with add_library(SHARED), but
1938 they do not have to be created by CMake. Specifying STATIC li‐
1939 braries, MODULE libraries, or executables here will result in
1940 undefined behavior.
1941 MODULES <module_files>
1943 List of loadable module files to read for dependencies. These
1944 are modules that are typically created with add_library(MODULE),
1945 but they do not have to be created by CMake. They are typically
1946 used by calling dlopen() at runtime rather than linked at link
1947 time with ld -l. Specifying STATIC libraries, SHARED libraries,
1948 or executables here will result in undefined behavior.
1949 DIRECTORIES <directories>
1951 List of additional directories to search for dependencies. On
1952 Linux platforms, these directories are searched if the depen‐
1953 dency is not found in any of the other usual paths. If it is
1954 found in such a directory, a warning is issued, because it means
1955 that the file is incomplete (it does not list all of the direc‐
1956 tories that contain its dependencies). On Windows platforms,
1957 these directories are searched if the dependency is not found in
1958 any of the other search paths, but no warning is issued, because
1959 searching other paths is a normal part of Windows dependency
1960 resolution. On Apple platforms, this argument has no effect.
1961 BUNDLE_EXECUTABLE <bundle_executable_file>
1963 Executable to treat as the "bundle executable" when resolving
1964 libraries. On Apple platforms, this argument determines the
1965 value of @executable_path when recursively resolving libraries
1966 for LIBRARIES and MODULES files. It has no effect on EXECUTA‐
1967 BLES files. On other platforms, it has no effect. This is typi‐
1968 cally (but not always) one of the executables in the EXECUTABLES
1969 argument which designates the "main" executable of the package.
1970 The following arguments specify filters for including or excluding li‐
1972 braries to be resolved. See below for a full description of how they
1973 work.
1974 PRE_INCLUDE_REGEXES <regexes>
1976 List of pre-include regexes through which to filter the names of
1977 not-yet-resolved dependencies.
1978 PRE_EXCLUDE_REGEXES <regexes>
1980 List of pre-exclude regexes through which to filter the names of
1981 not-yet-resolved dependencies.
1982 POST_INCLUDE_REGEXES <regexes>
1984 List of post-include regexes through which to filter the names
1985 of resolved dependencies.
1986 POST_EXCLUDE_REGEXES <regexes>
1988 List of post-exclude regexes through which to filter the names
1989 of resolved dependencies.
1990 POST_INCLUDE_FILES <files>
1992 New in version 3.21.
1993 List of post-include filenames through which to filter the names
1996 of resolved dependencies. Symlinks are resolved when attempting
1997 to match these filenames.
1998 POST_EXCLUDE_FILES <files>
2000 New in version 3.21.
2001 List of post-exclude filenames through which to filter the names
2004 of resolved dependencies. Symlinks are resolved when attempting
2005 to match these filenames.
2006 These arguments can be used to exclude unwanted system libraries when
2008 resolving the dependencies, or to include libraries from a specific di‐
2009 rectory. The filtering works as follows:
2010 1. If the not-yet-resolved dependency matches any of the PRE_IN‐
2012 CLUDE_REGEXES, steps 2 and 3 are skipped, and the dependency resolu‐
2013 tion proceeds to step 4.
2014 2. If the not-yet-resolved dependency matches any of the PRE_EX‐
2016 CLUDE_REGEXES, dependency resolution stops for that dependency.
2017 3. Otherwise, dependency resolution proceeds.
2019 4. file(GET_RUNTIME_DEPENDENCIES) searches for the dependency according
2021 to the linking rules of the platform (see below).
2022 5. If the dependency is found, and its full path matches one of the
2024 POST_INCLUDE_REGEXES or POST_INCLUDE_FILES, the full path is added
2025 to the resolved dependencies, and file(GET_RUNTIME_DEPENDENCIES) re‐
2026 cursively resolves that library's own dependencies. Otherwise, reso‐
2027 lution proceeds to step 6.
2028 6. If the dependency is found, but its full path matches one of the
2030 POST_EXCLUDE_REGEXES or POST_EXCLUDE_FILES, it is not added to the
2031 resolved dependencies, and dependency resolution stops for that de‐
2032 pendency.
2033 7. If the dependency is found, and its full path does not match either
2035 POST_INCLUDE_REGEXES, POST_INCLUDE_FILES, POST_EXCLUDE_REGEXES, or
2036 POST_EXCLUDE_FILES, the full path is added to the resolved dependen‐
2037 cies, and file(GET_RUNTIME_DEPENDENCIES) recursively resolves that
2038 library's own dependencies.
2039 Different platforms have different rules for how dependencies are re‐
2041 solved. These specifics are described here.
2042 On Linux platforms, library resolution works as follows:
2044 1. If the depending file does not have any RUNPATH entries, and the li‐
2046 brary exists in one of the depending file's RPATH entries, or its
2047 parents', in that order, the dependency is resolved to that file.
2048 2. Otherwise, if the depending file has any RUNPATH entries, and the
2050 library exists in one of those entries, the dependency is resolved
2051 to that file.
2052 3. Otherwise, if the library exists in one of the directories listed by
2054 ldconfig, the dependency is resolved to that file.
2055 4. Otherwise, if the library exists in one of the DIRECTORIES entries,
2057 the dependency is resolved to that file. In this case, a warning is
2058 issued, because finding a file in one of the DIRECTORIES means that
2059 the depending file is not complete (it does not list all the direc‐
2060 tories from which it pulls dependencies).
2061 5. Otherwise, the dependency is unresolved.
2063 On Windows platforms, library resolution works as follows:
2065 1. The dependent DLL name is converted to lowercase. Windows DLL names
2067 are case-insensitive, and some linkers mangle the case of the DLL
2068 dependency names. However, this makes it more difficult for PRE_IN‐
2069 CLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, and
2070 POST_EXCLUDE_REGEXES to properly filter DLL names - every regex
2071 would have to check for both uppercase and lowercase letters. For
2072 example:
2073 file(GET_RUNTIME_DEPENDENCIES
2075 # ...
2076 PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
2077 )
2078 Converting the DLL name to lowercase allows the regexes to only
2080 match lowercase names, thus simplifying the regex. For example:
2081 file(GET_RUNTIME_DEPENDENCIES
2083 # ...
2084 PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
2085 )
2086 This regex will match mylibrary.dll regardless of how it is cased,
2088 either on disk or in the depending file. (For example, it will match
2089 mylibrary.dll, MyLibrary.dll, and MYLIBRARY.DLL.)
2090 Please note that the directory portion of any resolved DLLs retains
2092 its casing and is not converted to lowercase. Only the filename por‐
2093 tion is converted.
2094 2. (Not yet implemented) If the depending file is a Windows Store app,
2096 and the dependency is listed as a dependency in the application's
2097 package manifest, the dependency is resolved to that file.
2098 3. Otherwise, if the library exists in the same directory as the de‐
2100 pending file, the dependency is resolved to that file.
2101 4. Otherwise, if the library exists in either the operating system's
2103 system32 directory or the Windows directory, in that order, the de‐
2104 pendency is resolved to that file.
2105 5. Otherwise, if the library exists in one of the directories specified
2107 by DIRECTORIES, in the order they are listed, the dependency is re‐
2108 solved to that file. In this case, a warning is not issued, because
2109 searching other directories is a normal part of Windows library res‐
2110 olution.
2111 6. Otherwise, the dependency is unresolved.
2113 On Apple platforms, library resolution works as follows:
2115 1. If the dependency starts with @executable_path/, and an EXECUTABLES
2117 argument is in the process of being resolved, and replacing @exe‐
2118 cutable_path/ with the directory of the executable yields an exist‐
2119 ing file, the dependency is resolved to that file.
2120 2. Otherwise, if the dependency starts with @executable_path/, and
2122 there is a BUNDLE_EXECUTABLE argument, and replacing @exe‐
2123 cutable_path/ with the directory of the bundle executable yields an
2124 existing file, the dependency is resolved to that file.
2125 3. Otherwise, if the dependency starts with @loader_path/, and replac‐
2127 ing @loader_path/ with the directory of the depending file yields an
2128 existing file, the dependency is resolved to that file.
2129 4. Otherwise, if the dependency starts with @rpath/, and replacing
2131 @rpath/ with one of the RPATH entries of the depending file yields
2132 an existing file, the dependency is resolved to that file. Note that
2133 RPATH entries that start with @executable_path/ or @loader_path/
2134 also have these items replaced with the appropriate path.
2135 5. Otherwise, if the dependency is an absolute file that exists, the
2137 dependency is resolved to that file.
2138 6. Otherwise, the dependency is unresolved.
2140 This function accepts several variables that determine which tool is
2142 used for dependency resolution:
2143 CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM
2145 Determines which operating system and executable format the
2146 files are built for. This could be one of several values:
2147 • linux+elf
2149 • windows+pe
2151 • macos+macho
2153 If this variable is not specified, it is determined automati‐
2155 cally by system introspection.
2156 CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
2158 Determines the tool to use for dependency resolution. It could
2159 be one of several values, depending on the value of
2160 CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM:
2161 ┌─────────────────────────┬──────────────────────────┐
2163 │CMAKE_GET_RUNTIME_DEPEN‐ │ CMAKE_GET_RUNTIME_DEPEN‐ │
2164 │DENCIES_PLATFORM │ DENCIES_TOOL │
2165 ├─────────────────────────┼──────────────────────────┤
2166 │linux+elf │ objdump │
2167 ├─────────────────────────┼──────────────────────────┤
2168 │windows+pe │ dumpbin │
2169 ├─────────────────────────┼──────────────────────────┤
2170 │windows+pe │ objdump │
2171 ├─────────────────────────┼──────────────────────────┤
2172 │macos+macho │ otool │
2173 └─────────────────────────┴──────────────────────────┘
2174 If this variable is not specified, it is determined automati‐
2176 cally by system introspection.
2177 CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND
2179 Determines the path to the tool to use for dependency resolu‐
2180 tion. This is the actual path to objdump, dumpbin, or otool.
2181 If this variable is not specified, it is determined by the value
2183 of CMAKE_OBJDUMP if set, else by system introspection.
2184 New in version 3.18: Use CMAKE_OBJDUMP if set.
2186 Writing
2189 file(WRITE <filename> <content>...)
2190 file(APPEND <filename> <content>...)
2191 Write <content> into a file called <filename>. If the file does not
2193 exist, it will be created. If the file already exists, WRITE mode will
2194 overwrite it and APPEND mode will append to the end. Any directories
2195 in the path specified by <filename> that do not exist will be created.
2196 If the file is a build input, use the configure_file() command to up‐
2198 date the file only when its content changes.
2199 file(TOUCH [<files>...])
2201 file(TOUCH_NOCREATE [<files>...])
2202 New in version 3.12.
2204 Create a file with no content if it does not yet exist. If the file al‐
2207 ready exists, its access and/or modification will be updated to the
2208 time when the function call is executed.
2209 Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a
2211 file does not exist it will be silently ignored.
2212 With TOUCH and TOUCH_NOCREATE the contents of an existing file will not
2214 be modified.
2215 file(GENERATE OUTPUT output-file
2217 <INPUT input-file|CONTENT content>
2218 [CONDITION expression] [TARGET target]
2219 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
2220 FILE_PERMISSIONS <permissions>...]
2221 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
2222 Generate an output file for each build configuration supported by the
2224 current CMake Generator. Evaluate generator expressions from the input
2225 content to produce the output content. The options are:
2226 CONDITION <condition>
2228 Generate the output file for a particular configuration only if
2229 the condition is true. The condition must be either 0 or 1 af‐
2230 ter evaluating generator expressions.
2231 CONTENT <content>
2233 Use the content given explicitly as input.
2234 INPUT <input-file>
2236 Use the content from a given file as input.
2237 Changed in version 3.10: A relative path is treated with respect
2239 to the value of CMAKE_CURRENT_SOURCE_DIR. See policy CMP0070.
2240 OUTPUT <output-file>
2243 Specify the output file name to generate. Use generator expres‐
2244 sions such as $<CONFIG> to specify a configuration-specific out‐
2245 put file name. Multiple configurations may generate the same
2246 output file only if the generated content is identical. Other‐
2247 wise, the <output-file> must evaluate to an unique name for each
2248 configuration.
2249 Changed in version 3.10: A relative path (after evaluating gen‐
2251 erator expressions) is treated with respect to the value of
2252 CMAKE_CURRENT_BINARY_DIR. See policy CMP0070.
2253 TARGET <target>
2256 New in version 3.19.
2257 Specify which target to use when evaluating generator expres‐
2260 sions that require a target for evaluation (e.g. $<COMPILE_FEA‐
2261 TURES:...>, $<TARGET_PROPERTY:prop>).
2262 NO_SOURCE_PERMISSIONS
2264 New in version 3.20.
2265 The generated file permissions default to the standard 644 value
2268 (-rw-r--r--).
2269 USE_SOURCE_PERMISSIONS
2271 New in version 3.20.
2272 Transfer the file permissions of the INPUT file to the generated
2275 file. This is already the default behavior if none of the three
2276 permissions-related keywords are given (NO_SOURCE_PERMISSIONS,
2277 USE_SOURCE_PERMISSIONS or FILE_PERMISSIONS). The
2278 USE_SOURCE_PERMISSIONS keyword mostly serves as a way of making
2279 the intended behavior clearer at the call site. It is an error
2280 to specify this option without INPUT.
2281 FILE_PERMISSIONS <permissions>...
2283 New in version 3.20.
2284 Use the specified permissions for the generated file.
2287 NEWLINE_STYLE <style>
2289 New in version 3.20.
2290 Specify the newline style for the generated file. Specify UNIX
2293 or LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n
2294 newlines.
2295 Exactly one CONTENT or INPUT option must be given. A specific OUTPUT
2297 file may be named by at most one invocation of file(GENERATE). Gener‐
2298 ated files are modified and their timestamp updated on subsequent cmake
2299 runs only if their content is changed.
2300 Note also that file(GENERATE) does not create the output file until the
2302 generation phase. The output file will not yet have been written when
2303 the file(GENERATE) command returns, it is written only after processing
2304 all of a project's CMakeLists.txt files.
2305 file(CONFIGURE OUTPUT output-file
2307 CONTENT content
2308 [ESCAPE_QUOTES] [@ONLY]
2309 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
2310 New in version 3.18.
2312 Generate an output file using the input given by CONTENT and substitute
2315 variable values referenced as @VAR@ or ${VAR} contained therein. The
2316 substitution rules behave the same as the configure_file() command. In
2317 order to match configure_file()'s behavior, generator expressions are
2318 not supported for both OUTPUT and CONTENT.
2319 The arguments are:
2321 OUTPUT <output-file>
2323 Specify the output file name to generate. A relative path is
2324 treated with respect to the value of CMAKE_CURRENT_BINARY_DIR.
2325 <output-file> does not support generator expressions.
2326 CONTENT <content>
2328 Use the content given explicitly as input. <content> does not
2329 support generator expressions.
2330 ESCAPE_QUOTES
2332 Escape any substituted quotes with backslashes (C-style).
2333 @ONLY Restrict variable replacement to references of the form @VAR@.
2335 This is useful for configuring scripts that use ${VAR} syntax.
2336 NEWLINE_STYLE <style>
2338 Specify the newline style for the output file. Specify UNIX or
2339 LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n new‐
2340 lines.
2341 Filesystem
2343 file(GLOB <variable>
2344 [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
2345 [<globbing-expressions>...])
2346 file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
2347 [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
2348 [<globbing-expressions>...])
2349 Generate a list of files that match the <globbing-expressions> and
2351 store it into the <variable>. Globbing expressions are similar to reg‐
2352 ular expressions, but much simpler. If RELATIVE flag is specified, the
2353 results will be returned as relative paths to the given path.
2354 Changed in version 3.6: The results will be ordered lexicographically.
2356 On Windows and macOS, globbing is case-insensitive even if the underly‐
2359 ing filesystem is case-sensitive (both filenames and globbing expres‐
2360 sions are converted to lowercase before matching). On other platforms,
2361 globbing is case-sensitive.
2362 New in version 3.3: By default GLOB lists directories - directories are
2364 omitted in result if LIST_DIRECTORIES is set to false.
2365 New in version 3.12: If the CONFIGURE_DEPENDS flag is specified, CMake
2368 will add logic to the main build system check target to rerun the
2369 flagged GLOB commands at build time. If any of the outputs change,
2370 CMake will regenerate the build system.
2371 NOTE:
2374 We do not recommend using GLOB to collect a list of source files
2375 from your source tree. If no CMakeLists.txt file changes when a
2376 source is added or removed then the generated build system cannot
2377 know when to ask CMake to regenerate. The CONFIGURE_DEPENDS flag
2378 may not work reliably on all generators, or if a new generator is
2379 added in the future that cannot support it, projects using it will
2380 be stuck. Even if CONFIGURE_DEPENDS works reliably, there is still a
2381 cost to perform the check on every rebuild.
2382 Examples of globbing expressions include:
2384 *.cxx - match all files with extension cxx
2386 *.vt? - match all files with extension vta,...,vtz
2387 f[3-5].txt - match files f3.txt, f4.txt, f5.txt
2388 The GLOB_RECURSE mode will traverse all the subdirectories of the
2390 matched directory and match the files. Subdirectories that are sym‐
2391 links are only traversed if FOLLOW_SYMLINKS is given or policy CMP0009
2392 is not set to NEW.
2393 New in version 3.3: By default GLOB_RECURSE omits directories from re‐
2395 sult list - setting LIST_DIRECTORIES to true adds directories to result
2396 list. If FOLLOW_SYMLINKS is given or policy CMP0009 is not set to NEW
2397 then LIST_DIRECTORIES treats symlinks as directories.
2398 Examples of recursive globbing include:
2401 /dir/*.py - match all python files in /dir and subdirectories
2403 file(MAKE_DIRECTORY [<directories>...])
2405 Create the given directories and their parents as needed.
2407 file(REMOVE [<files>...])
2409 file(REMOVE_RECURSE [<files>...])
2410 Remove the given files. The REMOVE_RECURSE mode will remove the given
2412 files and directories, also non-empty directories. No error is emitted
2413 if a given file does not exist. Relative input paths are evaluated
2414 with respect to the current source directory.
2415 Changed in version 3.15: Empty input paths are ignored with a warning.
2417 Previous versions of CMake interpreted empty strings as a relative path
2418 with respect to the current directory and removed its contents.
2419 file(RENAME <oldname> <newname>
2422 [RESULT <result>]
2423 [NO_REPLACE])
2424 Move a file or directory within a filesystem from <oldname> to <new‐
2426 name>, replacing the destination atomically.
2427 The options are:
2429 RESULT <result>
2431 New in version 3.21.
2432 Set <result> variable to 0 on success or an error message other‐
2435 wise. If RESULT is not specified and the operation fails, an
2436 error is emitted.
2437 NO_REPLACE
2439 New in version 3.21.
2440 If the <newname> path already exists, do not replace it. If RE‐
2443 SULT <result> is used, the result variable will be set to NO_RE‐
2444 PLACE. Otherwise, an error is emitted.
2445 file(COPY_FILE <oldname> <newname>
2447 [RESULT <result>]
2448 [ONLY_IF_DIFFERENT])
2449 New in version 3.21.
2451 Copy a file from <oldname> to <newname>. Directories are not supported.
2454 Symlinks are ignored and <oldfile>'s content is read and written to
2455 <newname> as a new file.
2456 The options are:
2458 RESULT <result>
2460 Set <result> variable to 0 on success or an error message other‐
2461 wise. If RESULT is not specified and the operation fails, an
2462 error is emitted.
2463 ONLY_IF_DIFFERENT
2465 If the <newname> path already exists, do not replace it if the
2466 file's contents are already the same as <oldname> (this avoids
2467 updating <newname>'s timestamp).
2468 This sub-command has some similarities to configure_file() with the
2470 COPYONLY option. An important difference is that configure_file() cre‐
2471 ates a dependency on the source file, so CMake will be re-run if it
2472 changes. The file(COPY_FILE) sub-command does not create such a depen‐
2473 dency.
2474 See also the file(COPY) sub-command just below which provides further
2476 file-copying capabilities.
2477 file(<COPY|INSTALL> <files>... DESTINATION <dir>
2479 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS]
2480 [FILE_PERMISSIONS <permissions>...]
2481 [DIRECTORY_PERMISSIONS <permissions>...]
2482 [FOLLOW_SYMLINK_CHAIN]
2483 [FILES_MATCHING]
2484 [[PATTERN <pattern> | REGEX <regex>]
2485 [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
2486 NOTE:
2488 For a simple file copying operation, the file(COPY_FILE) sub-command
2489 just above may be easier to use.
2490 The COPY signature copies files, directories, and symlinks to a desti‐
2492 nation folder. Relative input paths are evaluated with respect to the
2493 current source directory, and a relative destination is evaluated with
2494 respect to the current build directory. Copying preserves input file
2495 timestamps, and optimizes out a file if it exists at the destination
2496 with the same timestamp. Copying preserves input permissions unless
2497 explicit permissions or NO_SOURCE_PERMISSIONS are given (default is
2498 USE_SOURCE_PERMISSIONS).
2499 New in version 3.15: If FOLLOW_SYMLINK_CHAIN is specified, COPY will
2501 recursively resolve the symlinks at the paths given until a real file
2502 is found, and install a corresponding symlink in the destination for
2503 each symlink encountered. For each symlink that is installed, the reso‐
2504 lution is stripped of the directory, leaving only the filename, meaning
2505 that the new symlink points to a file in the same directory as the sym‐
2506 link. This feature is useful on some Unix systems, where libraries are
2507 installed as a chain of symlinks with version numbers, with less spe‐
2508 cific versions pointing to more specific versions. FOLLOW_SYM‐
2509 LINK_CHAIN will install all of these symlinks and the library itself
2510 into the destination directory. For example, if you have the following
2511 directory structure:
2512 • /opt/foo/lib/libfoo.so.1.2.3
2515 • /opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3
2517 • /opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2
2519 • /opt/foo/lib/libfoo.so -> libfoo.so.1
2521 and you do:
2523 file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)
2525 This will install all of the symlinks and libfoo.so.1.2.3 itself into
2527 lib.
2528 See the install(DIRECTORY) command for documentation of permissions,
2530 FILES_MATCHING, PATTERN, REGEX, and EXCLUDE options. Copying directo‐
2531 ries preserves the structure of their content even if options are used
2532 to select a subset of files.
2533 The INSTALL signature differs slightly from COPY: it prints status mes‐
2535 sages, and NO_SOURCE_PERMISSIONS is default.
2536 Installation scripts generated by the install() command use this signa‐
2538 ture (with some undocumented options for internal use).
2539 Changed in version 3.22: The environment variable CMAKE_INSTALL_MODE
2541 can override the default copying behavior of file(INSTALL).
2542 file(SIZE <filename> <variable>)
2545 New in version 3.14.
2547 Determine the file size of the <filename> and put the result in <vari‐
2550 able> variable. Requires that <filename> is a valid path pointing to a
2551 file and is readable.
2552 file(READ_SYMLINK <linkname> <variable>)
2554 New in version 3.14.
2556 This subcommand queries the symlink <linkname> and stores the path it
2559 points to in the result <variable>. If <linkname> does not exist or is
2560 not a symlink, CMake issues a fatal error.
2561 Note that this command returns the raw symlink path and does not re‐
2563 solve a relative path. The following is an example of how to ensure
2564 that an absolute path is obtained:
2565 set(linkname "/path/to/foo.sym")
2567 file(READ_SYMLINK "${linkname}" result)
2568 if(NOT IS_ABSOLUTE "${result}")
2569 get_filename_component(dir "${linkname}" DIRECTORY)
2570 set(result "${dir}/${result}")
2571 endif()
2572 file(CREATE_LINK <original> <linkname>
2574 [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])
2575 New in version 3.14.
2577 Create a link <linkname> that points to <original>. It will be a hard
2580 link by default, but providing the SYMBOLIC option results in a sym‐
2581 bolic link instead. Hard links require that original exists and is a
2582 file, not a directory. If <linkname> already exists, it will be over‐
2583 written.
2584 The <result> variable, if specified, receives the status of the opera‐
2586 tion. It is set to 0 upon success or an error message otherwise. If
2587 RESULT is not specified and the operation fails, a fatal error is emit‐
2588 ted.
2589 Specifying COPY_ON_ERROR enables copying the file as a fallback if cre‐
2591 ating the link fails. It can be useful for handling situations such as
2592 <original> and <linkname> being on different drives or mount points,
2593 which would make them unable to support a hard link.
2594 file(CHMOD <files>... <directories>...
2596 [PERMISSIONS <permissions>...]
2597 [FILE_PERMISSIONS <permissions>...]
2598 [DIRECTORY_PERMISSIONS <permissions>...])
2599 New in version 3.19.
2601 Set the permissions for the <files>... and <directories>... specified.
2604 Valid permissions are OWNER_READ, OWNER_WRITE, OWNER_EXECUTE,
2605 GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE,
2606 WORLD_EXECUTE, SETUID, SETGID.
2607 Valid combination of keywords are:
2609 PERMISSIONS
2611 All items are changed.
2612 FILE_PERMISSIONS
2614 Only files are changed.
2615 DIRECTORY_PERMISSIONS
2617 Only directories are changed.
2618 PERMISSIONS and FILE_PERMISSIONS
2620 FILE_PERMISSIONS overrides PERMISSIONS for files.
2621 PERMISSIONS and DIRECTORY_PERMISSIONS
2623 DIRECTORY_PERMISSIONS overrides PERMISSIONS for directories.
2624 FILE_PERMISSIONS and DIRECTORY_PERMISSIONS
2626 Use FILE_PERMISSIONS for files and DIRECTORY_PERMISSIONS for di‐
2627 rectories.
2628 file(CHMOD_RECURSE <files>... <directories>...
2630 [PERMISSIONS <permissions>...]
2631 [FILE_PERMISSIONS <permissions>...]
2632 [DIRECTORY_PERMISSIONS <permissions>...])
2633 New in version 3.19.
2635 Same as CHMOD, but change the permissions of files and directories
2638 present in the <directories>... recursively.
2639 Path Conversion
2641 file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])
2642 New in version 3.19.
2644 Compute the absolute path to an existing file or directory with sym‐
2647 links resolved.
2648 BASE_DIRECTORY <dir>
2650 If the provided <path> is a relative path, it is evaluated rela‐
2651 tive to the given base directory <dir>. If no base directory is
2652 provided, the default base directory will be CMAKE_CUR‐
2653 RENT_SOURCE_DIR.
2654 EXPAND_TILDE
2656 New in version 3.21.
2657 If the <path> is ~ or starts with ~/, the ~ is replaced by the
2660 user's home directory. The path to the home directory is ob‐
2661 tained from environment variables. On Windows, the USERPROFILE
2662 environment variable is used, falling back to the HOME environ‐
2663 ment variable if USERPROFILE is not defined. On all other plat‐
2664 forms, only HOME is used.
2665 file(RELATIVE_PATH <variable> <directory> <file>)
2667 Compute the relative path from a <directory> to a <file> and store it
2669 in the <variable>.
2670 file(TO_CMAKE_PATH "<path>" <variable>)
2672 file(TO_NATIVE_PATH "<path>" <variable>)
2673 The TO_CMAKE_PATH mode converts a native <path> into a cmake-style path
2675 with forward-slashes (/). The input can be a single path or a system
2676 search path like $ENV{PATH}. A search path will be converted to a
2677 cmake-style list separated by ; characters.
2678 The TO_NATIVE_PATH mode converts a cmake-style <path> into a native
2680 path with platform-specific slashes (\ on Windows hosts and / else‐
2681 where).
2682 Always use double quotes around the <path> to be sure it is treated as
2684 a single argument to this command.
2685 Transfer
2687 file(DOWNLOAD <url> [<file>] [<options>...])
2688 file(UPLOAD <file> <url> [<options>...])
2689 The DOWNLOAD subcommand downloads the given <url> to a local <file>.
2691 The UPLOAD mode uploads a local <file> to a given <url>.
2692 New in version 3.19: If <file> is not specified for file(DOWNLOAD), the
2694 file is not saved. This can be useful if you want to know if a file
2695 can be downloaded (for example, to check that it exists) without actu‐
2696 ally saving it anywhere.
2697 Options to both DOWNLOAD and UPLOAD are:
2700 INACTIVITY_TIMEOUT <seconds>
2702 Terminate the operation after a period of inactivity.
2703 LOG <variable>
2705 Store a human-readable log of the operation in a variable.
2706 SHOW_PROGRESS
2708 Print progress information as status messages until the opera‐
2709 tion is complete.
2710 STATUS <variable>
2712 Store the resulting status of the operation in a variable. The
2713 status is a ; separated list of length 2. The first element is
2714 the numeric return value for the operation, and the second ele‐
2715 ment is a string value for the error. A 0 numeric error means
2716 no error in the operation.
2717 TIMEOUT <seconds>
2719 Terminate the operation after a given total time has elapsed.
2720 USERPWD <username>:<password>
2722 New in version 3.7.
2723 Set username and password for operation.
2726 HTTPHEADER <HTTP-header>
2728 New in version 3.7.
2729 HTTP header for operation. Suboption can be repeated several
2732 times.
2733 NETRC <level>
2735 New in version 3.11.
2736 Specify whether the .netrc file is to be used for operation. If
2739 this option is not specified, the value of the CMAKE_NETRC vari‐
2740 able will be used instead. Valid levels are:
2741 IGNORED
2743 The .netrc file is ignored. This is the default.
2744 OPTIONAL
2746 The .netrc file is optional, and information in the URL
2747 is preferred. The file will be scanned to find which
2748 ever information is not specified in the URL.
2749 REQUIRED
2751 The .netrc file is required, and information in the URL
2752 is ignored.
2753 NETRC_FILE <file>
2755 New in version 3.11.
2756 Specify an alternative .netrc file to the one in your home di‐
2759 rectory, if the NETRC level is OPTIONAL or REQUIRED. If this op‐
2760 tion is not specified, the value of the CMAKE_NETRC_FILE vari‐
2761 able will be used instead.
2762 TLS_VERIFY <ON|OFF>
2764 Specify whether to verify the server certificate for https://
2765 URLs. The default is to not verify. If this option is not spec‐
2766 ified, the value of the CMAKE_TLS_VERIFY variable will be used
2767 instead.
2768 New in version 3.18: Added support to file(UPLOAD).
2770 TLS_CAINFO <file>
2773 Specify a custom Certificate Authority file for https:// URLs.
2774 If this option is not specified, the value of the
2775 CMAKE_TLS_CAINFO variable will be used instead.
2776 New in version 3.18: Added support to file(UPLOAD).
2778 For https:// URLs CMake must be built with OpenSSL support. TLS/SSL
2781 certificates are not checked by default. Set TLS_VERIFY to ON to check
2782 certificates.
2783 Additional options to DOWNLOAD are:
2785 EXPECTED_HASH ALGO=<value>
2787 Verify that the downloaded content hash matches the expected value,
2788 where ALGO is one of the algorithms supported by file(<HASH>). If
2789 it does not match, the operation fails with an error. It is an error
2790 to specify this if DOWNLOAD is not given a <file>.
2791 EXPECTED_MD5 <value>
2793 Historical short-hand for EXPECTED_HASH MD5=<value>. It is an
2794 error to specify this if DOWNLOAD is not given a <file>.
2795 Locking
2797 file(LOCK <path> [DIRECTORY] [RELEASE]
2798 [GUARD <FUNCTION|FILE|PROCESS>]
2799 [RESULT_VARIABLE <variable>]
2800 [TIMEOUT <seconds>])
2801 New in version 3.2.
2803 Lock a file specified by <path> if no DIRECTORY option present and file
2806 <path>/cmake.lock otherwise. File will be locked for scope defined by
2807 GUARD option (default value is PROCESS). RELEASE option can be used to
2808 unlock file explicitly. If option TIMEOUT is not specified CMake will
2809 wait until lock succeed or until fatal error occurs. If TIMEOUT is set
2810 to 0 lock will be tried once and result will be reported immediately.
2811 If TIMEOUT is not 0 CMake will try to lock file for the period speci‐
2812 fied by <seconds> value. Any errors will be interpreted as fatal if
2813 there is no RESULT_VARIABLE option. Otherwise result will be stored in
2814 <variable> and will be 0 on success or error message on failure.
2815 Note that lock is advisory - there is no guarantee that other processes
2817 will respect this lock, i.e. lock synchronize two or more CMake in‐
2818 stances sharing some modifiable resources. Similar logic applied to DI‐
2819 RECTORY option - locking parent directory doesn't prevent other LOCK
2820 commands to lock any child directory or file.
2821 Trying to lock file twice is not allowed. Any intermediate directories
2823 and file itself will be created if they not exist. GUARD and TIMEOUT
2824 options ignored on RELEASE operation.
2825 Archiving
2827 file(ARCHIVE_CREATE OUTPUT <archive>
2828 PATHS <paths>...
2829 [FORMAT <format>]
2830 [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]]
2831 [MTIME <mtime>]
2832 [VERBOSE])
2833 New in version 3.18.
2835 Creates the specified <archive> file with the files and directories
2838 listed in <paths>. Note that <paths> must list actual files or direc‐
2839 tories, wildcards are not supported.
2840 Use the FORMAT option to specify the archive format. Supported values
2842 for <format> are 7zip, gnutar, pax, paxr, raw and zip. If FORMAT is
2843 not given, the default format is paxr.
2844 Some archive formats allow the type of compression to be specified.
2846 The 7zip and zip archive formats already imply a specific type of com‐
2847 pression. The other formats use no compression by default, but can be
2848 directed to do so with the COMPRESSION option. Valid values for <com‐
2849 pression> are None, BZip2, GZip, XZ, and Zstd.
2850 New in version 3.19: The compression level can be specified with the
2852 COMPRESSION_LEVEL option. The <compression-level> should be between
2853 0-9, with the default being 0. The COMPRESSION option must be present
2854 when COMPRESSION_LEVEL is given.
2855 NOTE:
2858 With FORMAT set to raw only one file will be compressed with the
2859 compression type specified by COMPRESSION.
2860 The VERBOSE option enables verbose output for the archive operation.
2862 To specify the modification time recorded in tarball entries, use the
2864 MTIME option.
2865 file(ARCHIVE_EXTRACT INPUT <archive>
2867 [DESTINATION <dir>]
2868 [PATTERNS <patterns>...]
2869 [LIST_ONLY]
2870 [VERBOSE])
2871 New in version 3.18.
2873 Extracts or lists the content of the specified <archive>.
2876 The directory where the content of the archive will be extracted to can
2878 be specified using the DESTINATION option. If the directory does not
2879 exist, it will be created. If DESTINATION is not given, the current
2880 binary directory will be used.
2881 If required, you may select which files and directories to list or ex‐
2883 tract from the archive using the specified <patterns>. Wildcards are
2884 supported. If the PATTERNS option is not given, the entire archive
2885 will be listed or extracted.
2886 LIST_ONLY will list the files in the archive rather than extract them.
2888 With VERBOSE, the command will produce verbose output.
2890 find_file
2892 A short-hand signature is:
2893 find_file (<VAR> name1 [path1 path2 ...])
2895 The general signature is:
2897 find_file (
2899 <VAR>
2900 name | NAMES name1 [name2 ...]
2901 [HINTS [path | ENV var]... ]
2902 [PATHS [path | ENV var]... ]
2903 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2904 [DOC "cache documentation string"]
2905 [NO_CACHE]
2906 [REQUIRED]
2907 [NO_DEFAULT_PATH]
2908 [NO_PACKAGE_ROOT_PATH]
2909 [NO_CMAKE_PATH]
2910 [NO_CMAKE_ENVIRONMENT_PATH]
2911 [NO_SYSTEM_ENVIRONMENT_PATH]
2912 [NO_CMAKE_SYSTEM_PATH]
2913 [CMAKE_FIND_ROOT_PATH_BOTH |
2914 ONLY_CMAKE_FIND_ROOT_PATH |
2915 NO_CMAKE_FIND_ROOT_PATH]
2916 )
2917 This command is used to find a full path to named file. A cache entry,
2919 or a normal variable if NO_CACHE is specified, named by <VAR> is cre‐
2920 ated to store the result of this command. If the full path to a file
2921 is found the result is stored in the variable and the search will not
2922 be repeated unless the variable is cleared. If nothing is found, the
2923 result will be <VAR>-NOTFOUND.
2924 Options include:
2926 NAMES Specify one or more possible names for the full path to a file.
2928 When using this to specify names with and without a version suf‐
2930 fix, we recommend specifying the unversioned name first so that
2931 locally-built packages can be found before those provided by
2932 distributions.
2933 HINTS, PATHS
2935 Specify directories to search in addition to the default loca‐
2936 tions. The ENV var sub-option reads paths from a system envi‐
2937 ronment variable.
2938 PATH_SUFFIXES
2940 Specify additional subdirectories to check below each directory
2941 location otherwise considered.
2942 DOC Specify the documentation string for the <VAR> cache entry.
2944 NO_CACHE
2946 New in version 3.21.
2947 The result of the search will be stored in a normal variable
2950 rather than a cache entry.
2951 NOTE:
2953 If the variable is already set before the call (as a normal
2954 or cache variable) then the search will not occur.
2955 WARNING:
2957 This option should be used with caution because it can
2958 greatly increase the cost of repeated configure steps.
2959 REQUIRED
2961 New in version 3.18.
2962 Stop processing with an error message if nothing is found, oth‐
2965 erwise the search will be attempted again the next time
2966 find_file is invoked with the same variable.
2967 If NO_DEFAULT_PATH is specified, then no additional paths are added to
2969 the search. If NO_DEFAULT_PATH is not specified, the search process is
2970 as follows:
2971 1. New in version 3.12: If called from within a find module or any
2973 other script loaded by a call to find_package(<PackageName>), search
2974 prefixes unique to the current package being found. Specifically,
2975 look in the <PackageName>_ROOT CMake variable and the <Package‐
2976 Name>_ROOT environment variable. The package root variables are
2977 maintained as a stack, so if called from nested find modules or con‐
2978 fig packages, root paths from the parent's find module or config
2979 package will be searched after paths from the current module or
2980 package. In other words, the search order would be <CurrentPack‐
2981 age>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT,
2982 ENV{<ParentPackage>_ROOT}, etc. This can be skipped if NO_PACK‐
2983 AGE_ROOT_PATH is passed or by setting the CMAKE_FIND_USE_PACK‐
2984 AGE_ROOT_PATH to FALSE. See policy CMP0074.
2985 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2988 <prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
2989 variable and the <PackageName>_ROOT environment variable if called
2990 from within a find module loaded by find_package(<PackageName>)
2991 2. Search paths specified in cmake-specific cache variables. These are
2993 intended to be used on the command line with a -DVAR=value. The
2994 values are interpreted as semicolon-separated lists. This can be
2995 skipped if NO_CMAKE_PATH is passed or by setting the
2996 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
2997 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2999 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
3000 • CMAKE_INCLUDE_PATH
3002 • CMAKE_FRAMEWORK_PATH
3004 3. Search paths specified in cmake-specific environment variables.
3006 These are intended to be set in the user's shell configuration, and
3007 therefore use the host's native path separator (; on Windows and :
3008 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
3009 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
3010 FALSE.
3011 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3013 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
3014 • CMAKE_INCLUDE_PATH
3016 • CMAKE_FRAMEWORK_PATH
3018 4. Search the paths specified by the HINTS option. These should be
3020 paths computed by system introspection, such as a hint provided by
3021 the location of another item already found. Hard-coded guesses
3022 should be specified with the PATHS option.
3023 5. Search the standard system environment variables. This can be
3025 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
3026 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
3027 • The directories in INCLUDE and PATH.
3029 • On Windows hosts: <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHI‐
3031 TECTURE is set, and <prefix>/include for each <prefix>/[s]bin in
3032 PATH, and <entry>/include for other entries in PATH.
3033 6. Search cmake variables defined in the Platform files for the current
3035 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
3036 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
3037 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3039 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
3040 • CMAKE_SYSTEM_INCLUDE_PATH
3042 • CMAKE_SYSTEM_FRAMEWORK_PATH
3044 The platform paths that these variables contain are locations that
3046 typically include installed software. An example being /usr/local
3047 for UNIX based platforms.
3048 7. Search the paths specified by the PATHS option or in the short-hand
3050 version of the command. These are typically hard-coded guesses.
3051 New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to
3053 globally disable various search locations.
3054 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
3057 determine the order of preference between Apple-style and unix-style
3058 package components.
3059 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
3061 ries to be prepended to all other search directories. This effectively
3062 "re-roots" the entire search under given locations. Paths which are
3063 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
3064 ing, because that variable is always a path on the host system. By de‐
3065 fault the CMAKE_FIND_ROOT_PATH is empty.
3066 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
3068 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
3069 fects. See the documentation for that variable for more.
3070 These variables are especially useful when cross-compiling to point to
3072 the root directory of the target environment and CMake will search
3073 there too. By default at first the directories listed in
3074 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
3075 searched, and then the non-rooted directories will be searched. The
3076 default behavior can be adjusted by setting
3077 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually over‐
3078 ridden on a per-call basis using options:
3079 CMAKE_FIND_ROOT_PATH_BOTH
3081 Search in the order described above.
3082 NO_CMAKE_FIND_ROOT_PATH
3084 Do not use the CMAKE_FIND_ROOT_PATH variable.
3085 ONLY_CMAKE_FIND_ROOT_PATH
3087 Search only the re-rooted directories and directories below
3088 CMAKE_STAGING_PREFIX.
3089 The default search order is designed to be most-specific to least-spe‐
3091 cific for common use cases. Projects may override the order by simply
3092 calling the command multiple times and using the NO_* options:
3093 find_file (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
3095 find_file (<VAR> NAMES name)
3096 Once one of the calls succeeds the result variable will be set and
3098 stored in the cache so that no call will search again.
3099 find_library
3101 A short-hand signature is:
3102 find_library (<VAR> name1 [path1 path2 ...])
3104 The general signature is:
3106 find_library (
3108 <VAR>
3109 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
3110 [HINTS [path | ENV var]... ]
3111 [PATHS [path | ENV var]... ]
3112 [PATH_SUFFIXES suffix1 [suffix2 ...]]
3113 [DOC "cache documentation string"]
3114 [NO_CACHE]
3115 [REQUIRED]
3116 [NO_DEFAULT_PATH]
3117 [NO_PACKAGE_ROOT_PATH]
3118 [NO_CMAKE_PATH]
3119 [NO_CMAKE_ENVIRONMENT_PATH]
3120 [NO_SYSTEM_ENVIRONMENT_PATH]
3121 [NO_CMAKE_SYSTEM_PATH]
3122 [CMAKE_FIND_ROOT_PATH_BOTH |
3123 ONLY_CMAKE_FIND_ROOT_PATH |
3124 NO_CMAKE_FIND_ROOT_PATH]
3125 )
3126 This command is used to find a library. A cache entry, or a normal
3128 variable if NO_CACHE is specified, named by <VAR> is created to store
3129 the result of this command. If the library is found the result is
3130 stored in the variable and the search will not be repeated unless the
3131 variable is cleared. If nothing is found, the result will be
3132 <VAR>-NOTFOUND.
3133 Options include:
3135 NAMES Specify one or more possible names for the library.
3137 When using this to specify names with and without a version suf‐
3139 fix, we recommend specifying the unversioned name first so that
3140 locally-built packages can be found before those provided by
3141 distributions.
3142 HINTS, PATHS
3144 Specify directories to search in addition to the default loca‐
3145 tions. The ENV var sub-option reads paths from a system envi‐
3146 ronment variable.
3147 PATH_SUFFIXES
3149 Specify additional subdirectories to check below each directory
3150 location otherwise considered.
3151 DOC Specify the documentation string for the <VAR> cache entry.
3153 NO_CACHE
3155 New in version 3.21.
3156 The result of the search will be stored in a normal variable
3159 rather than a cache entry.
3160 NOTE:
3162 If the variable is already set before the call (as a normal
3163 or cache variable) then the search will not occur.
3164 WARNING:
3166 This option should be used with caution because it can
3167 greatly increase the cost of repeated configure steps.
3168 REQUIRED
3170 New in version 3.18.
3171 Stop processing with an error message if nothing is found, oth‐
3174 erwise the search will be attempted again the next time find_li‐
3175 brary is invoked with the same variable.
3176 If NO_DEFAULT_PATH is specified, then no additional paths are added to
3178 the search. If NO_DEFAULT_PATH is not specified, the search process is
3179 as follows:
3180 1. New in version 3.12: If called from within a find module or any
3182 other script loaded by a call to find_package(<PackageName>), search
3183 prefixes unique to the current package being found. Specifically,
3184 look in the <PackageName>_ROOT CMake variable and the <Package‐
3185 Name>_ROOT environment variable. The package root variables are
3186 maintained as a stack, so if called from nested find modules or con‐
3187 fig packages, root paths from the parent's find module or config
3188 package will be searched after paths from the current module or
3189 package. In other words, the search order would be <CurrentPack‐
3190 age>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT,
3191 ENV{<ParentPackage>_ROOT}, etc. This can be skipped if NO_PACK‐
3192 AGE_ROOT_PATH is passed or by setting the CMAKE_FIND_USE_PACK‐
3193 AGE_ROOT_PATH to FALSE. See policy CMP0074.
3194 • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3197 <prefix>/lib for each <prefix> in the <PackageName>_ROOT CMake
3198 variable and the <PackageName>_ROOT environment variable if called
3199 from within a find module loaded by find_package(<PackageName>)
3200 2. Search paths specified in cmake-specific cache variables. These are
3202 intended to be used on the command line with a -DVAR=value. The
3203 values are interpreted as semicolon-separated lists. This can be
3204 skipped if NO_CMAKE_PATH is passed or by setting the
3205 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
3206 • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3208 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
3209 • CMAKE_LIBRARY_PATH
3211 • CMAKE_FRAMEWORK_PATH
3213 3. Search paths specified in cmake-specific environment variables.
3215 These are intended to be set in the user's shell configuration, and
3216 therefore use the host's native path separator (; on Windows and :
3217 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
3218 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
3219 FALSE.
3220 • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3222 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
3223 • CMAKE_LIBRARY_PATH
3225 • CMAKE_FRAMEWORK_PATH
3227 4. Search the paths specified by the HINTS option. These should be
3229 paths computed by system introspection, such as a hint provided by
3230 the location of another item already found. Hard-coded guesses
3231 should be specified with the PATHS option.
3232 5. Search the standard system environment variables. This can be
3234 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
3235 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
3236 • The directories in LIB and PATH.
3238 • On Windows hosts: <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITEC‐
3240 TURE is set, and <prefix>/lib for each <prefix>/[s]bin in PATH,
3241 and <entry>/lib for other entries in PATH.
3242 6. Search cmake variables defined in the Platform files for the current
3244 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
3245 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
3246 • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3248 <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
3249 • CMAKE_SYSTEM_LIBRARY_PATH
3251 • CMAKE_SYSTEM_FRAMEWORK_PATH
3253 The platform paths that these variables contain are locations that
3255 typically include installed software. An example being /usr/local
3256 for UNIX based platforms.
3257 7. Search the paths specified by the PATHS option or in the short-hand
3259 version of the command. These are typically hard-coded guesses.
3260 New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to
3262 globally disable various search locations.
3263 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
3266 determine the order of preference between Apple-style and unix-style
3267 package components.
3268 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
3270 ries to be prepended to all other search directories. This effectively
3271 "re-roots" the entire search under given locations. Paths which are
3272 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
3273 ing, because that variable is always a path on the host system. By de‐
3274 fault the CMAKE_FIND_ROOT_PATH is empty.
3275 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
3277 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
3278 fects. See the documentation for that variable for more.
3279 These variables are especially useful when cross-compiling to point to
3281 the root directory of the target environment and CMake will search
3282 there too. By default at first the directories listed in
3283 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
3284 searched, and then the non-rooted directories will be searched. The
3285 default behavior can be adjusted by setting
3286 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY. This behavior can be manually over‐
3287 ridden on a per-call basis using options:
3288 CMAKE_FIND_ROOT_PATH_BOTH
3290 Search in the order described above.
3291 NO_CMAKE_FIND_ROOT_PATH
3293 Do not use the CMAKE_FIND_ROOT_PATH variable.
3294 ONLY_CMAKE_FIND_ROOT_PATH
3296 Search only the re-rooted directories and directories below
3297 CMAKE_STAGING_PREFIX.
3298 The default search order is designed to be most-specific to least-spe‐
3300 cific for common use cases. Projects may override the order by simply
3301 calling the command multiple times and using the NO_* options:
3302 find_library (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
3304 find_library (<VAR> NAMES name)
3305 Once one of the calls succeeds the result variable will be set and
3307 stored in the cache so that no call will search again.
3308 When more than one value is given to the NAMES option this command by
3310 default will consider one name at a time and search every directory for
3311 it. The NAMES_PER_DIR option tells this command to consider one direc‐
3312 tory at a time and search for all names in it.
3313 Each library name given to the NAMES option is first considered as a
3315 library file name and then considered with platform-specific prefixes
3316 (e.g. lib) and suffixes (e.g. .so). Therefore one may specify library
3317 file names such as libfoo.a directly. This can be used to locate
3318 static libraries on UNIX-like systems.
3319 If the library found is a framework, then <VAR> will be set to the full
3321 path to the framework <fullPath>/A.framework. When a full path to a
3322 framework is used as a library, CMake will use a -framework A, and a
3323 -F<fullPath> to link the framework to the target.
3324 If the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable is set all search
3326 paths will be tested as normal, with the suffix appended, and with all
3327 matches of lib/ replaced with lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUF‐
3328 FIX}/. This variable overrides the FIND_LIBRARY_USE_LIB32_PATHS,
3329 FIND_LIBRARY_USE_LIBX32_PATHS, and FIND_LIBRARY_USE_LIB64_PATHS global
3330 properties.
3331 If the FIND_LIBRARY_USE_LIB32_PATHS global property is set all search
3333 paths will be tested as normal, with 32/ appended, and with all matches
3334 of lib/ replaced with lib32/. This property is automatically set for
3335 the platforms that are known to need it if at least one of the lan‐
3336 guages supported by the project() command is enabled.
3337 If the FIND_LIBRARY_USE_LIBX32_PATHS global property is set all search
3339 paths will be tested as normal, with x32/ appended, and with all
3340 matches of lib/ replaced with libx32/. This property is automatically
3341 set for the platforms that are known to need it if at least one of the
3342 languages supported by the project() command is enabled.
3343 If the FIND_LIBRARY_USE_LIB64_PATHS global property is set all search
3345 paths will be tested as normal, with 64/ appended, and with all matches
3346 of lib/ replaced with lib64/. This property is automatically set for
3347 the platforms that are known to need it if at least one of the lan‐
3348 guages supported by the project() command is enabled.
3349 find_package
3351 Find a package (usually provided by something external to the project),
3352 and load its package-specific details.
3353 Search Modes
3355 The command has two very distinct ways of conducting the search:
3356 Module mode
3358 In this mode, CMake searches for a file called Find<Package‐
3359 Name>.cmake, looking first in the locations listed in the
3360 CMAKE_MODULE_PATH, then among the Find Modules provided by the
3361 CMake installation. If the file is found, it is read and pro‐
3362 cessed by CMake. It is responsible for finding the package,
3363 checking the version, and producing any needed messages. Some
3364 Find modules provide limited or no support for versioning; check
3365 the Find module's documentation.
3366 The Find<PackageName>.cmake file is not typically provided by
3368 the package itself. Rather, it is normally provided by some‐
3369 thing external to the package, such as the operating system,
3370 CMake itself, or even the project from which the find_package()
3371 command was called. Being externally provided, Find Modules
3372 tend to be heuristic in nature and are susceptible to becoming
3373 out-of-date. They typically search for certain libraries, files
3374 and other package artifacts.
3375 Module mode is only supported by the basic command signature.
3377 Config mode
3379 In this mode, CMake searches for a file called <lowercasePacka‐
3380 geName>-config.cmake or <PackageName>Config.cmake. It will also
3381 look for <lowercasePackageName>-config-version.cmake or <Packa‐
3382 geName>ConfigVersion.cmake if version details were specified
3383 (see Config Mode Version Selection for an explanation of how
3384 these separate version files are used).
3385 In config mode, the command can be given a list of names to
3387 search for as package names. The locations where CMake searches
3388 for the config and version files is considerably more compli‐
3389 cated than for Module mode (see Config Mode Search Procedure).
3390 The config and version files are typically installed as part of
3392 the package, so they tend to be more reliable than Find modules.
3393 They usually contain direct knowledge of the package contents,
3394 so no searching or heuristics are needed within the config or
3395 version files themselves.
3396 Config mode is supported by both the basic and full command sig‐
3398 natures.
3399 The command arguments determine which of the above modes is used. When
3401 the basic signature is used, the command searches in Module mode first.
3402 If the package is not found, the search falls back to Config mode. A
3403 user may set the CMAKE_FIND_PACKAGE_PREFER_CONFIG variable to true to
3404 reverse the priority and direct CMake to search using Config mode first
3405 before falling back to Module mode. The basic signature can also be
3406 forced to use only Module mode with a MODULE keyword. If the full sig‐
3407 nature is used, the command only searches in Config mode.
3408 Where possible, user code should generally look for packages using the
3410 basic signature, since that allows the package to be found with either
3411 mode. Project maintainers wishing to provide a config package should
3412 understand the bigger picture, as explained in Full Signature and all
3413 subsequent sections on this page.
3414 Basic Signature
3416 find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
3417 [REQUIRED] [[COMPONENTS] [components...]]
3418 [OPTIONAL_COMPONENTS components...]
3419 [NO_POLICY_SCOPE])
3420 The basic signature is supported by both Module and Config modes. The
3422 MODULE keyword implies that only Module mode can be used to find the
3423 package, with no fallback to Config mode.
3424 Regardless of the mode used, a <PackageName>_FOUND variable will be set
3426 to indicate whether the package was found. When the package is found,
3427 package-specific information may be provided through other variables
3428 and Imported Targets documented by the package itself. The QUIET op‐
3429 tion disables informational messages, including those indicating that
3430 the package cannot be found if it is not REQUIRED. The REQUIRED option
3431 stops processing with an error message if the package cannot be found.
3432 A package-specific list of required components may be listed after the
3434 COMPONENTS keyword. If any of these components are not able to be sat‐
3435 isfied, the package overall is considered to be not found. If the RE‐
3436 QUIRED option is also present, this is treated as a fatal error, other‐
3437 wise execution still continues. As a form of shorthand, if the RE‐
3438 QUIRED option is present, the COMPONENTS keyword can be omitted and the
3439 required components can be listed directly after REQUIRED.
3440 Additional optional components may be listed after OPTIONAL_COMPONENTS.
3442 If these cannot be satisfied, the package overall can still be consid‐
3443 ered found, as long as all required components are satisfied.
3444 The set of available components and their meaning are defined by the
3446 target package. Formally, it is up to the target package how to inter‐
3447 pret the component information given to it, but it should follow the
3448 expectations stated above. For calls where no components are speci‐
3449 fied, there is no single expected behavior and target packages should
3450 clearly define what occurs in such cases. Common arrangements include
3451 assuming it should find all components, no components or some well-de‐
3452 fined subset of the available components.
3453 The [version] argument requests a version with which the package found
3455 should be compatible. There are two possible forms in which it may be
3456 specified:
3457 • A single version with the format major[.minor[.patch[.tweak]]],
3459 where each component is a numeric value.
3460 • A version range with the format versionMin...[<]versionMax where
3462 versionMin and versionMax have the same format and constraints on
3463 components being integers as the single version. By default, both
3464 end points are included. By specifying <, the upper end point
3465 will be excluded. Version ranges are only supported with CMake
3466 3.19 or later.
3467 The EXACT option requests that the version be matched exactly. This op‐
3469 tion is incompatible with the specification of a version range.
3470 If no [version] and/or component list is given to a recursive invoca‐
3472 tion inside a find-module, the corresponding arguments are forwarded
3473 automatically from the outer call (including the EXACT flag for [ver‐
3474 sion]). Version support is currently provided only on a pack‐
3475 age-by-package basis (see the Version Selection section below). When a
3476 version range is specified but the package is only designed to expect a
3477 single version, the package will ignore the upper end point of the
3478 range and only take the single version at the lower end of the range
3479 into account.
3480 See the cmake_policy() command documentation for discussion of the
3482 NO_POLICY_SCOPE option.
3483 Full Signature
3485 find_package(<PackageName> [version] [EXACT] [QUIET]
3486 [REQUIRED] [[COMPONENTS] [components...]]
3487 [OPTIONAL_COMPONENTS components...]
3488 [CONFIG|NO_MODULE]
3489 [NO_POLICY_SCOPE]
3490 [NAMES name1 [name2 ...]]
3491 [CONFIGS config1 [config2 ...]]
3492 [HINTS path1 [path2 ... ]]
3493 [PATHS path1 [path2 ... ]]
3494 [PATH_SUFFIXES suffix1 [suffix2 ...]]
3495 [NO_DEFAULT_PATH]
3496 [NO_PACKAGE_ROOT_PATH]
3497 [NO_CMAKE_PATH]
3498 [NO_CMAKE_ENVIRONMENT_PATH]
3499 [NO_SYSTEM_ENVIRONMENT_PATH]
3500 [NO_CMAKE_PACKAGE_REGISTRY]
3501 [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
3502 [NO_CMAKE_SYSTEM_PATH]
3503 [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
3504 [CMAKE_FIND_ROOT_PATH_BOTH |
3505 ONLY_CMAKE_FIND_ROOT_PATH |
3506 NO_CMAKE_FIND_ROOT_PATH])
3507 The CONFIG option, the synonymous NO_MODULE option, or the use of op‐
3509 tions not specified in the basic signature all enforce pure Config
3510 mode. In pure Config mode, the command skips Module mode search and
3511 proceeds at once with Config mode search.
3512 Config mode search attempts to locate a configuration file provided by
3514 the package to be found. A cache entry called <PackageName>_DIR is
3515 created to hold the directory containing the file. By default the com‐
3516 mand searches for a package with the name <PackageName>. If the NAMES
3517 option is given the names following it are used instead of <Package‐
3518 Name>. The command searches for a file called <PackageName>Con‐
3519 fig.cmake or <lowercasePackageName>-config.cmake for each name speci‐
3520 fied. A replacement set of possible configuration file names may be
3521 given using the CONFIGS option. The Config Mode Search Procedure is
3522 specified below. Once found, any version constraint is checked, and if
3523 satisfied, the configuration file is read and processed by CMake.
3524 Since the file is provided by the package it already knows the location
3525 of package contents. The full path to the configuration file is stored
3526 in the cmake variable <PackageName>_CONFIG.
3527 All configuration files which have been considered by CMake while
3529 searching for the package with an appropriate version are stored in the
3530 <PackageName>_CONSIDERED_CONFIGS variable, and the associated versions
3531 in the <PackageName>_CONSIDERED_VERSIONS variable.
3532 If the package configuration file cannot be found CMake will generate
3534 an error describing the problem unless the QUIET argument is specified.
3535 If REQUIRED is specified and the package is not found a fatal error is
3536 generated and the configure step stops executing. If <PackageName>_DIR
3537 has been set to a directory not containing a configuration file CMake
3538 will ignore it and search from scratch.
3539 Package maintainers providing CMake package configuration files are en‐
3541 couraged to name and install them such that the Config Mode Search Pro‐
3542 cedure outlined below will find them without requiring use of addi‐
3543 tional options.
3544 Config Mode Search Procedure
3546 NOTE:
3547 When Config mode is used, this search procedure is applied regard‐
3548 less of whether the full or basic signature was given.
3549 CMake constructs a set of possible installation prefixes for the pack‐
3551 age. Under each prefix several directories are searched for a configu‐
3552 ration file. The tables below show the directories searched. Each en‐
3553 try is meant for installation trees following Windows (W), UNIX (U), or
3554 Apple (A) conventions:
3555 <prefix>/ (W)
3557 <prefix>/(cmake|CMake)/ (W)
3558 <prefix>/<name>*/ (W)
3559 <prefix>/<name>*/(cmake|CMake)/ (W)
3560 <prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/ (U)
3561 <prefix>/(lib/<arch>|lib*|share)/<name>*/ (U)
3562 <prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (U)
3563 <prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/ (W/U)
3564 <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ (W/U)
3565 <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U)
3566 On systems supporting macOS FRAMEWORK and BUNDLE, the following direc‐
3568 tories are searched for Frameworks or Application Bundles containing a
3569 configuration file:
3570 <prefix>/<name>.framework/Resources/ (A)
3572 <prefix>/<name>.framework/Resources/CMake/ (A)
3573 <prefix>/<name>.framework/Versions/*/Resources/ (A)
3574 <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A)
3575 <prefix>/<name>.app/Contents/Resources/ (A)
3576 <prefix>/<name>.app/Contents/Resources/CMake/ (A)
3577 In all cases the <name> is treated as case-insensitive and corresponds
3579 to any of the names specified (<PackageName> or names given by NAMES).
3580 Paths with lib/<arch> are enabled if the CMAKE_LIBRARY_ARCHITECTURE
3582 variable is set. lib* includes one or more of the values lib64, lib32,
3583 libx32 or lib (searched in that order).
3584 • Paths with lib64 are searched on 64 bit platforms if the FIND_LI‐
3586 BRARY_USE_LIB64_PATHS property is set to TRUE.
3587 • Paths with lib32 are searched on 32 bit platforms if the FIND_LI‐
3589 BRARY_USE_LIB32_PATHS property is set to TRUE.
3590 • Paths with libx32 are searched on platforms using the x32 ABI if the
3592 FIND_LIBRARY_USE_LIBX32_PATHS property is set to TRUE.
3593 • The lib path is always searched.
3595 If PATH_SUFFIXES is specified, the suffixes are appended to each (W) or
3597 (U) directory entry one-by-one.
3598 This set of directories is intended to work in cooperation with
3600 projects that provide configuration files in their installation trees.
3601 Directories above marked with (W) are intended for installations on
3602 Windows where the prefix may point at the top of an application's in‐
3603 stallation directory. Those marked with (U) are intended for installa‐
3604 tions on UNIX platforms where the prefix is shared by multiple pack‐
3605 ages. This is merely a convention, so all (W) and (U) directories are
3606 still searched on all platforms. Directories marked with (A) are in‐
3607 tended for installations on Apple platforms. The CMAKE_FIND_FRAMEWORK
3608 and CMAKE_FIND_APPBUNDLE variables determine the order of preference.
3609 The set of installation prefixes is constructed using the following
3611 steps. If NO_DEFAULT_PATH is specified all NO_* options are enabled.
3612 1. New in version 3.12: Search paths specified in the <Package‐
3614 Name>_ROOT CMake variable and the <PackageName>_ROOT environment
3615 variable, where <PackageName> is the package to be found. The pack‐
3616 age root variables are maintained as a stack so if called from
3617 within a find module, root paths from the parent's find module will
3618 also be searched after paths for the current package. This can be
3619 skipped if NO_PACKAGE_ROOT_PATH is passed or by setting the
3620 CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
3621 2. Search paths specified in cmake-specific cache variables. These are
3624 intended to be used on the command line with a -DVAR=value. The
3625 values are interpreted as semicolon-separated lists. This can be
3626 skipped if NO_CMAKE_PATH is passed or by setting the
3627 CMAKE_FIND_USE_CMAKE_PATH to FALSE:
3628 • CMAKE_PREFIX_PATH
3630 • CMAKE_FRAMEWORK_PATH
3632 • CMAKE_APPBUNDLE_PATH
3634 3. Search paths specified in cmake-specific environment variables.
3636 These are intended to be set in the user's shell configuration, and
3637 therefore use the host's native path separator (; on Windows and :
3638 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
3639 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
3640 FALSE:
3641 • <PackageName>_DIR
3643 • CMAKE_PREFIX_PATH
3645 • CMAKE_FRAMEWORK_PATH
3647 • CMAKE_APPBUNDLE_PATH
3649 4. Search paths specified by the HINTS option. These should be paths
3651 computed by system introspection, such as a hint provided by the lo‐
3652 cation of another item already found. Hard-coded guesses should be
3653 specified with the PATHS option.
3654 5. Search the standard system environment variables. This can be
3656 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
3657 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE. Path entries ending
3658 in /bin or /sbin are automatically converted to their parent direc‐
3659 tories:
3660 • PATH
3662 6. Search paths stored in the CMake User Package Registry. This can be
3664 skipped if NO_CMAKE_PACKAGE_REGISTRY is passed or by setting the
3665 variable CMAKE_FIND_USE_PACKAGE_REGISTRY to FALSE or the deprecated
3666 variable CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY to TRUE.
3667 See the cmake-packages(7) manual for details on the user package
3669 registry.
3670 7. Search cmake variables defined in the Platform files for the current
3672 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
3673 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE:
3674 • CMAKE_SYSTEM_PREFIX_PATH
3676 • CMAKE_SYSTEM_FRAMEWORK_PATH
3678 • CMAKE_SYSTEM_APPBUNDLE_PATH
3680 The platform paths that these variables contain are locations that
3682 typically include installed software. An example being /usr/local
3683 for UNIX based platforms.
3684 8. Search paths stored in the CMake System Package Registry. This can
3686 be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is passed or by set‐
3687 ting the CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variable to FALSE or
3688 the deprecated variable CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REG‐
3689 ISTRY to TRUE.
3690 See the cmake-packages(7) manual for details on the system package
3692 registry.
3693 9. Search paths specified by the PATHS option. These are typically
3695 hard-coded guesses.
3696 New in version 3.16: Added the CMAKE_FIND_USE_<CATEGORY> variables to
3698 globally disable various search locations.
3699 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
3702 ries to be prepended to all other search directories. This effectively
3703 "re-roots" the entire search under given locations. Paths which are
3704 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
3705 ing, because that variable is always a path on the host system. By de‐
3706 fault the CMAKE_FIND_ROOT_PATH is empty.
3707 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
3709 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
3710 fects. See the documentation for that variable for more.
3711 These variables are especially useful when cross-compiling to point to
3713 the root directory of the target environment and CMake will search
3714 there too. By default at first the directories listed in
3715 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
3716 searched, and then the non-rooted directories will be searched. The
3717 default behavior can be adjusted by setting
3718 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE. This behavior can be manually over‐
3719 ridden on a per-call basis using options:
3720 CMAKE_FIND_ROOT_PATH_BOTH
3722 Search in the order described above.
3723 NO_CMAKE_FIND_ROOT_PATH
3725 Do not use the CMAKE_FIND_ROOT_PATH variable.
3726 ONLY_CMAKE_FIND_ROOT_PATH
3728 Search only the re-rooted directories and directories below
3729 CMAKE_STAGING_PREFIX.
3730 The default search order is designed to be most-specific to least-spe‐
3732 cific for common use cases. Projects may override the order by simply
3733 calling the command multiple times and using the NO_* options:
3734 find_package (<PackageName> PATHS paths... NO_DEFAULT_PATH)
3736 find_package (<PackageName>)
3737 Once one of the calls succeeds the result variable will be set and
3739 stored in the cache so that no call will search again.
3740 By default the value stored in the result variable will be the path at
3742 which the file is found. The CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS vari‐
3743 able may be set to TRUE before calling find_package in order to resolve
3744 symbolic links and store the real path to the file.
3745 Every non-REQUIRED find_package call can be disabled or made REQUIRED:
3747 • Setting the CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable to TRUE
3749 disables the package.
3750 • Setting the CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> variable to TRUE
3752 makes the package REQUIRED.
3753 Setting both variables to TRUE simultaneously is an error.
3755 Config Mode Version Selection
3757 NOTE:
3758 When Config mode is used, this version selection process is applied
3759 regardless of whether the full or basic signature was given.
3760 When the [version] argument is given, Config mode will only find a ver‐
3762 sion of the package that claims compatibility with the requested ver‐
3763 sion (see format specification). If the EXACT option is given, only a
3764 version of the package claiming an exact match of the requested version
3765 may be found. CMake does not establish any convention for the meaning
3766 of version numbers. Package version numbers are checked by "version"
3767 files provided by the packages themselves. For a candidate package
3768 configuration file <config-file>.cmake the corresponding version file
3769 is located next to it and named either <config-file>-version.cmake or
3770 <config-file>Version.cmake. If no such version file is available then
3771 the configuration file is assumed to not be compatible with any re‐
3772 quested version. A basic version file containing generic version
3773 matching code can be created using the CMakePackageConfigHelpers mod‐
3774 ule. When a version file is found it is loaded to check the requested
3775 version number. The version file is loaded in a nested scope in which
3776 the following variables have been defined:
3777 PACKAGE_FIND_NAME
3779 The <PackageName>
3780 PACKAGE_FIND_VERSION
3782 Full requested version string
3783 PACKAGE_FIND_VERSION_MAJOR
3785 Major version if requested, else 0
3786 PACKAGE_FIND_VERSION_MINOR
3788 Minor version if requested, else 0
3789 PACKAGE_FIND_VERSION_PATCH
3791 Patch version if requested, else 0
3792 PACKAGE_FIND_VERSION_TWEAK
3794 Tweak version if requested, else 0
3795 PACKAGE_FIND_VERSION_COUNT
3797 Number of version components, 0 to 4
3798 When a version range is specified, the above version variables will
3800 hold values based on the lower end of the version range. This is to
3801 preserve compatibility with packages that have not been implemented to
3802 expect version ranges. In addition, the version range will be de‐
3803 scribed by the following variables:
3804 PACKAGE_FIND_VERSION_RANGE
3806 Full requested version range string
3807 PACKAGE_FIND_VERSION_RANGE_MIN
3809 This specifies whether the lower end point of the version range
3810 should be included or excluded. Currently, the only supported
3811 value for this variable is INCLUDE.
3812 PACKAGE_FIND_VERSION_RANGE_MAX
3814 This specifies whether the upper end point of the version range
3815 should be included or excluded. The supported values for this
3816 variable are INCLUDE and EXCLUDE.
3817 PACKAGE_FIND_VERSION_MIN
3819 Full requested version string of the lower end point of the
3820 range
3821 PACKAGE_FIND_VERSION_MIN_MAJOR
3823 Major version of the lower end point if requested, else 0
3824 PACKAGE_FIND_VERSION_MIN_MINOR
3826 Minor version of the lower end point if requested, else 0
3827 PACKAGE_FIND_VERSION_MIN_PATCH
3829 Patch version of the lower end point if requested, else 0
3830 PACKAGE_FIND_VERSION_MIN_TWEAK
3832 Tweak version of the lower end point if requested, else 0
3833 PACKAGE_FIND_VERSION_MIN_COUNT
3835 Number of version components of the lower end point, 0 to 4
3836 PACKAGE_FIND_VERSION_MAX
3838 Full requested version string of the upper end point of the
3839 range
3840 PACKAGE_FIND_VERSION_MAX_MAJOR
3842 Major version of the upper end point if requested, else 0
3843 PACKAGE_FIND_VERSION_MAX_MINOR
3845 Minor version of the upper end point if requested, else 0
3846 PACKAGE_FIND_VERSION_MAX_PATCH
3848 Patch version of the upper end point if requested, else 0
3849 PACKAGE_FIND_VERSION_MAX_TWEAK
3851 Tweak version of the upper end point if requested, else 0
3852 PACKAGE_FIND_VERSION_MAX_COUNT
3854 Number of version components of the upper end point, 0 to 4
3855 Regardless of whether a single version or a version range is specified,
3857 the variable PACKAGE_FIND_VERSION_COMPLETE will be defined and will
3858 hold the full requested version string as specified.
3859 The version file checks whether it satisfies the requested version and
3861 sets these variables:
3862 PACKAGE_VERSION
3864 Full provided version string
3865 PACKAGE_VERSION_EXACT
3867 True if version is exact match
3868 PACKAGE_VERSION_COMPATIBLE
3870 True if version is compatible
3871 PACKAGE_VERSION_UNSUITABLE
3873 True if unsuitable as any version
3874 These variables are checked by the find_package command to determine
3876 whether the configuration file provides an acceptable version. They
3877 are not available after the find_package call returns. If the version
3878 is acceptable the following variables are set:
3879 <PackageName>_VERSION
3881 Full provided version string
3882 <PackageName>_VERSION_MAJOR
3884 Major version if provided, else 0
3885 <PackageName>_VERSION_MINOR
3887 Minor version if provided, else 0
3888 <PackageName>_VERSION_PATCH
3890 Patch version if provided, else 0
3891 <PackageName>_VERSION_TWEAK
3893 Tweak version if provided, else 0
3894 <PackageName>_VERSION_COUNT
3896 Number of version components, 0 to 4
3897 and the corresponding package configuration file is loaded. When mul‐
3899 tiple package configuration files are available whose version files
3900 claim compatibility with the version requested it is unspecified which
3901 one is chosen: unless the variable CMAKE_FIND_PACKAGE_SORT_ORDER is set
3902 no attempt is made to choose a highest or closest version number.
3903 To control the order in which find_package checks for compatibility use
3905 the two variables CMAKE_FIND_PACKAGE_SORT_ORDER and CMAKE_FIND_PACK‐
3906 AGE_SORT_DIRECTION. For instance in order to select the highest ver‐
3907 sion one can set
3908 SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
3910 SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
3911 before calling find_package.
3913 Package File Interface Variables
3915 When loading a find module or package configuration file find_package
3916 defines variables to provide information about the call arguments (and
3917 restores their original state before returning):
3918 CMAKE_FIND_PACKAGE_NAME
3920 The <PackageName> which is searched for
3921 <PackageName>_FIND_REQUIRED
3923 True if REQUIRED option was given
3924 <PackageName>_FIND_QUIETLY
3926 True if QUIET option was given
3927 <PackageName>_FIND_VERSION
3929 Full requested version string
3930 <PackageName>_FIND_VERSION_MAJOR
3932 Major version if requested, else 0
3933 <PackageName>_FIND_VERSION_MINOR
3935 Minor version if requested, else 0
3936 <PackageName>_FIND_VERSION_PATCH
3938 Patch version if requested, else 0
3939 <PackageName>_FIND_VERSION_TWEAK
3941 Tweak version if requested, else 0
3942 <PackageName>_FIND_VERSION_COUNT
3944 Number of version components, 0 to 4
3945 <PackageName>_FIND_VERSION_EXACT
3947 True if EXACT option was given
3948 <PackageName>_FIND_COMPONENTS
3950 List of specified components (required and optional)
3951 <PackageName>_FIND_REQUIRED_<c>
3953 True if component <c> is required, false if component <c> is op‐
3954 tional
3955 When a version range is specified, the above version variables will
3957 hold values based on the lower end of the version range. This is to
3958 preserve compatibility with packages that have not been implemented to
3959 expect version ranges. In addition, the version range will be de‐
3960 scribed by the following variables:
3961 <PackageName>_FIND_VERSION_RANGE
3963 Full requested version range string
3964 <PackageName>_FIND_VERSION_RANGE_MIN
3966 This specifies whether the lower end point of the version range
3967 is included or excluded. Currently, INCLUDE is the only sup‐
3968 ported value.
3969 <PackageName>_FIND_VERSION_RANGE_MAX
3971 This specifies whether the upper end point of the version range
3972 is included or excluded. The possible values for this variable
3973 are INCLUDE or EXCLUDE.
3974 <PackageName>_FIND_VERSION_MIN
3976 Full requested version string of the lower end point of the
3977 range
3978 <PackageName>_FIND_VERSION_MIN_MAJOR
3980 Major version of the lower end point if requested, else 0
3981 <PackageName>_FIND_VERSION_MIN_MINOR
3983 Minor version of the lower end point if requested, else 0
3984 <PackageName>_FIND_VERSION_MIN_PATCH
3986 Patch version of the lower end point if requested, else 0
3987 <PackageName>_FIND_VERSION_MIN_TWEAK
3989 Tweak version of the lower end point if requested, else 0
3990 <PackageName>_FIND_VERSION_MIN_COUNT
3992 Number of version components of the lower end point, 0 to 4
3993 <PackageName>_FIND_VERSION_MAX
3995 Full requested version string of the upper end point of the
3996 range
3997 <PackageName>_FIND_VERSION_MAX_MAJOR
3999 Major version of the upper end point if requested, else 0
4000 <PackageName>_FIND_VERSION_MAX_MINOR
4002 Minor version of the upper end point if requested, else 0
4003 <PackageName>_FIND_VERSION_MAX_PATCH
4005 Patch version of the upper end point if requested, else 0
4006 <PackageName>_FIND_VERSION_MAX_TWEAK
4008 Tweak version of the upper end point if requested, else 0
4009 <PackageName>_FIND_VERSION_MAX_COUNT
4011 Number of version components of the upper end point, 0 to 4
4012 Regardless of whether a single version or a version range is specified,
4014 the variable <PackageName>_FIND_VERSION_COMPLETE will be defined and
4015 will hold the full requested version string as specified.
4016 In Module mode the loaded find module is responsible to honor the re‐
4018 quest detailed by these variables; see the find module for details. In
4019 Config mode find_package handles REQUIRED, QUIET, and [version] options
4020 automatically but leaves it to the package configuration file to handle
4021 components in a way that makes sense for the package. The package con‐
4022 figuration file may set <PackageName>_FOUND to false to tell find_pack‐
4023 age that component requirements are not satisfied.
4024 find_path
4026 A short-hand signature is:
4027 find_path (<VAR> name1 [path1 path2 ...])
4029 The general signature is:
4031 find_path (
4033 <VAR>
4034 name | NAMES name1 [name2 ...]
4035 [HINTS [path | ENV var]... ]
4036 [PATHS [path | ENV var]... ]
4037 [PATH_SUFFIXES suffix1 [suffix2 ...]]
4038 [DOC "cache documentation string"]
4039 [NO_CACHE]
4040 [REQUIRED]
4041 [NO_DEFAULT_PATH]
4042 [NO_PACKAGE_ROOT_PATH]
4043 [NO_CMAKE_PATH]
4044 [NO_CMAKE_ENVIRONMENT_PATH]
4045 [NO_SYSTEM_ENVIRONMENT_PATH]
4046 [NO_CMAKE_SYSTEM_PATH]
4047 [CMAKE_FIND_ROOT_PATH_BOTH |
4048 ONLY_CMAKE_FIND_ROOT_PATH |
4049 NO_CMAKE_FIND_ROOT_PATH]
4050 )
4051 This command is used to find a directory containing the named file. A
4053 cache entry, or a normal variable if NO_CACHE is specified, named by
4054 <VAR> is created to store the result of this command. If the file in a
4055 directory is found the result is stored in the variable and the search
4056 will not be repeated unless the variable is cleared. If nothing is
4057 found, the result will be <VAR>-NOTFOUND.
4058 Options include:
4060 NAMES Specify one or more possible names for the file in a directory.
4062 When using this to specify names with and without a version suf‐
4064 fix, we recommend specifying the unversioned name first so that
4065 locally-built packages can be found before those provided by
4066 distributions.
4067 HINTS, PATHS
4069 Specify directories to search in addition to the default loca‐
4070 tions. The ENV var sub-option reads paths from a system envi‐
4071 ronment variable.
4072 PATH_SUFFIXES
4074 Specify additional subdirectories to check below each directory
4075 location otherwise considered.
4076 DOC Specify the documentation string for the <VAR> cache entry.
4078 NO_CACHE
4080 New in version 3.21.
4081 The result of the search will be stored in a normal variable
4084 rather than a cache entry.
4085 NOTE:
4087 If the variable is already set before the call (as a normal
4088 or cache variable) then the search will not occur.
4089 WARNING:
4091 This option should be used with caution because it can
4092 greatly increase the cost of repeated configure steps.
4093 REQUIRED
4095 New in version 3.18.
4096 Stop processing with an error message if nothing is found, oth‐
4099 erwise the search will be attempted again the next time
4100 find_path is invoked with the same variable.
4101 If NO_DEFAULT_PATH is specified, then no additional paths are added to
4103 the search. If NO_DEFAULT_PATH is not specified, the search process is
4104 as follows:
4105 1. New in version 3.12: If called from within a find module or any
4107 other script loaded by a call to find_package(<PackageName>), search
4108 prefixes unique to the current package being found. Specifically,
4109 look in the <PackageName>_ROOT CMake variable and the <Package‐
4110 Name>_ROOT environment variable. The package root variables are
4111 maintained as a stack, so if called from nested find modules or con‐
4112 fig packages, root paths from the parent's find module or config
4113 package will be searched after paths from the current module or
4114 package. In other words, the search order would be <CurrentPack‐
4115 age>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT,
4116 ENV{<ParentPackage>_ROOT}, etc. This can be skipped if NO_PACK‐
4117 AGE_ROOT_PATH is passed or by setting the CMAKE_FIND_USE_PACK‐
4118 AGE_ROOT_PATH to FALSE. See policy CMP0074.
4119 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
4122 <prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
4123 variable and the <PackageName>_ROOT environment variable if called
4124 from within a find module loaded by find_package(<PackageName>)
4125 2. Search paths specified in cmake-specific cache variables. These are
4127 intended to be used on the command line with a -DVAR=value. The
4128 values are interpreted as semicolon-separated lists. This can be
4129 skipped if NO_CMAKE_PATH is passed or by setting the
4130 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
4131 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
4133 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
4134 • CMAKE_INCLUDE_PATH
4136 • CMAKE_FRAMEWORK_PATH
4138 3. Search paths specified in cmake-specific environment variables.
4140 These are intended to be set in the user's shell configuration, and
4141 therefore use the host's native path separator (; on Windows and :
4142 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
4143 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
4144 FALSE.
4145 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
4147 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
4148 • CMAKE_INCLUDE_PATH
4150 • CMAKE_FRAMEWORK_PATH
4152 4. Search the paths specified by the HINTS option. These should be
4154 paths computed by system introspection, such as a hint provided by
4155 the location of another item already found. Hard-coded guesses
4156 should be specified with the PATHS option.
4157 5. Search the standard system environment variables. This can be
4159 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
4160 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
4161 • The directories in INCLUDE and PATH.
4163 • On Windows hosts: <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHI‐
4165 TECTURE is set, and <prefix>/include for each <prefix>/[s]bin in
4166 PATH, and <entry>/include for other entries in PATH.
4167 6. Search cmake variables defined in the Platform files for the current
4169 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
4170 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
4171 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
4173 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
4174 • CMAKE_SYSTEM_INCLUDE_PATH
4176 • CMAKE_SYSTEM_FRAMEWORK_PATH
4178 The platform paths that these variables contain are locations that
4180 typically include installed software. An example being /usr/local
4181 for UNIX based platforms.
4182 7. Search the paths specified by the PATHS option or in the short-hand
4184 version of the command. These are typically hard-coded guesses.
4185 New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to
4187 globally disable various search locations.
4188 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
4191 determine the order of preference between Apple-style and unix-style
4192 package components.
4193 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
4195 ries to be prepended to all other search directories. This effectively
4196 "re-roots" the entire search under given locations. Paths which are
4197 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
4198 ing, because that variable is always a path on the host system. By de‐
4199 fault the CMAKE_FIND_ROOT_PATH is empty.
4200 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
4202 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
4203 fects. See the documentation for that variable for more.
4204 These variables are especially useful when cross-compiling to point to
4206 the root directory of the target environment and CMake will search
4207 there too. By default at first the directories listed in
4208 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
4209 searched, and then the non-rooted directories will be searched. The
4210 default behavior can be adjusted by setting
4211 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually over‐
4212 ridden on a per-call basis using options:
4213 CMAKE_FIND_ROOT_PATH_BOTH
4215 Search in the order described above.
4216 NO_CMAKE_FIND_ROOT_PATH
4218 Do not use the CMAKE_FIND_ROOT_PATH variable.
4219 ONLY_CMAKE_FIND_ROOT_PATH
4221 Search only the re-rooted directories and directories below
4222 CMAKE_STAGING_PREFIX.
4223 The default search order is designed to be most-specific to least-spe‐
4225 cific for common use cases. Projects may override the order by simply
4226 calling the command multiple times and using the NO_* options:
4227 find_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
4229 find_path (<VAR> NAMES name)
4230 Once one of the calls succeeds the result variable will be set and
4232 stored in the cache so that no call will search again.
4233 When searching for frameworks, if the file is specified as A/b.h, then
4235 the framework search will look for A.framework/Headers/b.h. If that is
4236 found the path will be set to the path to the framework. CMake will
4237 convert this to the correct -F option to include the file.
4238 find_program
4240 A short-hand signature is:
4241 find_program (<VAR> name1 [path1 path2 ...])
4243 The general signature is:
4245 find_program (
4247 <VAR>
4248 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
4249 [HINTS [path | ENV var]... ]
4250 [PATHS [path | ENV var]... ]
4251 [PATH_SUFFIXES suffix1 [suffix2 ...]]
4252 [DOC "cache documentation string"]
4253 [NO_CACHE]
4254 [REQUIRED]
4255 [NO_DEFAULT_PATH]
4256 [NO_PACKAGE_ROOT_PATH]
4257 [NO_CMAKE_PATH]
4258 [NO_CMAKE_ENVIRONMENT_PATH]
4259 [NO_SYSTEM_ENVIRONMENT_PATH]
4260 [NO_CMAKE_SYSTEM_PATH]
4261 [CMAKE_FIND_ROOT_PATH_BOTH |
4262 ONLY_CMAKE_FIND_ROOT_PATH |
4263 NO_CMAKE_FIND_ROOT_PATH]
4264 )
4265 This command is used to find a program. A cache entry, or a normal
4267 variable if NO_CACHE is specified, named by <VAR> is created to store
4268 the result of this command. If the program is found the result is
4269 stored in the variable and the search will not be repeated unless the
4270 variable is cleared. If nothing is found, the result will be
4271 <VAR>-NOTFOUND.
4272 Options include:
4274 NAMES Specify one or more possible names for the program.
4276 When using this to specify names with and without a version suf‐
4278 fix, we recommend specifying the unversioned name first so that
4279 locally-built packages can be found before those provided by
4280 distributions.
4281 HINTS, PATHS
4283 Specify directories to search in addition to the default loca‐
4284 tions. The ENV var sub-option reads paths from a system envi‐
4285 ronment variable.
4286 PATH_SUFFIXES
4288 Specify additional subdirectories to check below each directory
4289 location otherwise considered.
4290 DOC Specify the documentation string for the <VAR> cache entry.
4292 NO_CACHE
4294 New in version 3.21.
4295 The result of the search will be stored in a normal variable
4298 rather than a cache entry.
4299 NOTE:
4301 If the variable is already set before the call (as a normal
4302 or cache variable) then the search will not occur.
4303 WARNING:
4305 This option should be used with caution because it can
4306 greatly increase the cost of repeated configure steps.
4307 REQUIRED
4309 New in version 3.18.
4310 Stop processing with an error message if nothing is found, oth‐
4313 erwise the search will be attempted again the next time
4314 find_program is invoked with the same variable.
4315 If NO_DEFAULT_PATH is specified, then no additional paths are added to
4317 the search. If NO_DEFAULT_PATH is not specified, the search process is
4318 as follows:
4319 1. New in version 3.12: If called from within a find module or any
4321 other script loaded by a call to find_package(<PackageName>), search
4322 prefixes unique to the current package being found. Specifically,
4323 look in the <PackageName>_ROOT CMake variable and the <Package‐
4324 Name>_ROOT environment variable. The package root variables are
4325 maintained as a stack, so if called from nested find modules or con‐
4326 fig packages, root paths from the parent's find module or config
4327 package will be searched after paths from the current module or
4328 package. In other words, the search order would be <CurrentPack‐
4329 age>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT,
4330 ENV{<ParentPackage>_ROOT}, etc. This can be skipped if NO_PACK‐
4331 AGE_ROOT_PATH is passed or by setting the CMAKE_FIND_USE_PACK‐
4332 AGE_ROOT_PATH to FALSE. See policy CMP0074.
4333 • <prefix>/[s]bin for each <prefix> in the <PackageName>_ROOT CMake
4336 variable and the <PackageName>_ROOT environment variable if called
4337 from within a find module loaded by find_package(<PackageName>)
4338 2. Search paths specified in cmake-specific cache variables. These are
4340 intended to be used on the command line with a -DVAR=value. The
4341 values are interpreted as semicolon-separated lists. This can be
4342 skipped if NO_CMAKE_PATH is passed or by setting the
4343 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
4344 • <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
4346 • CMAKE_PROGRAM_PATH
4348 • CMAKE_APPBUNDLE_PATH
4350 3. Search paths specified in cmake-specific environment variables.
4352 These are intended to be set in the user's shell configuration, and
4353 therefore use the host's native path separator (; on Windows and :
4354 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
4355 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
4356 FALSE.
4357 • <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
4359 • CMAKE_PROGRAM_PATH
4361 • CMAKE_APPBUNDLE_PATH
4363 4. Search the paths specified by the HINTS option. These should be
4365 paths computed by system introspection, such as a hint provided by
4366 the location of another item already found. Hard-coded guesses
4367 should be specified with the PATHS option.
4368 5. Search the standard system environment variables. This can be
4370 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
4371 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
4372 • The directories in PATH itself.
4374 • On Windows hosts no extra search paths are included
4376 6. Search cmake variables defined in the Platform files for the current
4378 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
4379 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
4380 • <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
4382 • CMAKE_SYSTEM_PROGRAM_PATH
4384 • CMAKE_SYSTEM_APPBUNDLE_PATH
4386 The platform paths that these variables contain are locations that
4388 typically include installed software. An example being /usr/local
4389 for UNIX based platforms.
4390 7. Search the paths specified by the PATHS option or in the short-hand
4392 version of the command. These are typically hard-coded guesses.
4393 New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to
4395 globally disable various search locations.
4396 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
4399 determine the order of preference between Apple-style and unix-style
4400 package components.
4401 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
4403 ries to be prepended to all other search directories. This effectively
4404 "re-roots" the entire search under given locations. Paths which are
4405 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
4406 ing, because that variable is always a path on the host system. By de‐
4407 fault the CMAKE_FIND_ROOT_PATH is empty.
4408 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
4410 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
4411 fects. See the documentation for that variable for more.
4412 These variables are especially useful when cross-compiling to point to
4414 the root directory of the target environment and CMake will search
4415 there too. By default at first the directories listed in
4416 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
4417 searched, and then the non-rooted directories will be searched. The
4418 default behavior can be adjusted by setting
4419 CMAKE_FIND_ROOT_PATH_MODE_PROGRAM. This behavior can be manually over‐
4420 ridden on a per-call basis using options:
4421 CMAKE_FIND_ROOT_PATH_BOTH
4423 Search in the order described above.
4424 NO_CMAKE_FIND_ROOT_PATH
4426 Do not use the CMAKE_FIND_ROOT_PATH variable.
4427 ONLY_CMAKE_FIND_ROOT_PATH
4429 Search only the re-rooted directories and directories below
4430 CMAKE_STAGING_PREFIX.
4431 The default search order is designed to be most-specific to least-spe‐
4433 cific for common use cases. Projects may override the order by simply
4434 calling the command multiple times and using the NO_* options:
4435 find_program (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
4437 find_program (<VAR> NAMES name)
4438 Once one of the calls succeeds the result variable will be set and
4440 stored in the cache so that no call will search again.
4441 When more than one value is given to the NAMES option this command by
4443 default will consider one name at a time and search every directory for
4444 it. The NAMES_PER_DIR option tells this command to consider one direc‐
4445 tory at a time and search for all names in it.
4446 foreach
4448 Evaluate a group of commands for each value in a list.
4449 foreach(<loop_var> <items>)
4451 <commands>
4452 endforeach()
4453 where <items> is a list of items that are separated by semicolon or
4455 whitespace. All commands between foreach and the matching endforeach
4456 are recorded without being invoked. Once the endforeach is evaluated,
4457 the recorded list of commands is invoked once for each item in <items>.
4458 At the beginning of each iteration the variable <loop_var> will be set
4459 to the value of the current item.
4460 The scope of <loop_var> is restricted to the loop scope. See policy
4462 CMP0124 for details.
4463 The commands break() and continue() provide means to escape from the
4465 normal control flow.
4466 Per legacy, the endforeach() command admits an optional <loop_var> ar‐
4468 gument. If used, it must be a verbatim repeat of the argument of the
4469 opening foreach command.
4470 foreach(<loop_var> RANGE <stop>)
4472 In this variant, foreach iterates over the numbers 0, 1, ... up to (and
4474 including) the nonnegative integer <stop>.
4475 foreach(<loop_var> RANGE <start> <stop> [<step>])
4477 In this variant, foreach iterates over the numbers from <start> up to
4479 at most <stop> in steps of <step>. If <step> is not specified, then
4480 the step size is 1. The three arguments <start> <stop> <step> must all
4481 be nonnegative integers, and <stop> must not be smaller than <start>;
4482 otherwise you enter the danger zone of undocumented behavior that may
4483 change in future releases.
4484 foreach(<loop_var> IN [LISTS [<lists>]] [ITEMS [<items>]])
4486 In this variant, <lists> is a whitespace or semicolon separated list of
4488 list-valued variables. The foreach command iterates over each item in
4489 each given list. The <items> following the ITEMS keyword are processed
4490 as in the first variant of the foreach command. The forms LISTS A and
4491 ITEMS ${A} are equivalent.
4492 The following example shows how the LISTS option is processed:
4494 set(A 0;1)
4496 set(B 2 3)
4497 set(C "4 5")
4498 set(D 6;7 8)
4499 set(E "")
4500 foreach(X IN LISTS A B C D E)
4501 message(STATUS "X=${X}")
4502 endforeach()
4503 yields
4505 -- X=0
4507 -- X=1
4508 -- X=2
4509 -- X=3
4510 -- X=4 5
4511 -- X=6
4512 -- X=7
4513 -- X=8
4514 foreach(<loop_var>... IN ZIP_LISTS <lists>)
4516 New in version 3.17.
4518 In this variant, <lists> is a whitespace or semicolon separated list of
4521 list-valued variables. The foreach command iterates over each list si‐
4522 multaneously setting the iteration variables as follows:
4523 • if the only loop_var given, then it sets a series of loop_var_N vari‐
4525 ables to the current item from the corresponding list;
4526 • if multiple variable names passed, their count should match the lists
4528 variables count;
4529 • if any of the lists are shorter, the corresponding iteration variable
4531 is not defined for the current iteration.
4532 list(APPEND English one two three four)
4534 list(APPEND Bahasa satu dua tiga)
4535 foreach(num IN ZIP_LISTS English Bahasa)
4537 message(STATUS "num_0=${num_0}, num_1=${num_1}")
4538 endforeach()
4539 foreach(en ba IN ZIP_LISTS English Bahasa)
4541 message(STATUS "en=${en}, ba=${ba}")
4542 endforeach()
4543 yields
4545 -- num_0=one, num_1=satu
4547 -- num_0=two, num_1=dua
4548 -- num_0=three, num_1=tiga
4549 -- num_0=four, num_1=
4550 -- en=one, ba=satu
4551 -- en=two, ba=dua
4552 -- en=three, ba=tiga
4553 -- en=four, ba=
4554 function
4556 Start recording a function for later invocation as a command.
4557 function(<name> [<arg1> ...])
4559 <commands>
4560 endfunction()
4561 Defines a function named <name> that takes arguments named <arg1>, ...
4563 The <commands> in the function definition are recorded; they are not
4564 executed until the function is invoked.
4565 Per legacy, the endfunction() command admits an optional <name> argu‐
4567 ment. If used, it must be a verbatim repeat of the argument of the
4568 opening function command.
4569 A function opens a new scope: see set(var PARENT_SCOPE) for details.
4571 See the cmake_policy() command documentation for the behavior of poli‐
4573 cies inside functions.
4574 See the macro() command documentation for differences between CMake
4576 functions and macros.
4577 Invocation
4579 The function invocation is case-insensitive. A function defined as
4580 function(foo)
4582 <commands>
4583 endfunction()
4584 can be invoked through any of
4586 foo()
4588 Foo()
4589 FOO()
4590 cmake_language(CALL foo)
4591 and so on. However, it is strongly recommended to stay with the case
4593 chosen in the function definition. Typically functions use all-lower‐
4594 case names.
4595 New in version 3.18: The cmake_language(CALL ...) command can also be
4597 used to invoke the function.
4598 Arguments
4601 When the function is invoked, the recorded <commands> are first modi‐
4602 fied by replacing formal parameters (${arg1}, ...) with the arguments
4603 passed, and then invoked as normal commands.
4604 In addition to referencing the formal parameters you can reference the
4606 ARGC variable which will be set to the number of arguments passed into
4607 the function as well as ARGV0, ARGV1, ARGV2, ... which will have the
4608 actual values of the arguments passed in. This facilitates creating
4609 functions with optional arguments.
4610 Furthermore, ARGV holds the list of all arguments given to the function
4612 and ARGN holds the list of arguments past the last expected argument.
4613 Referencing to ARGV# arguments beyond ARGC have undefined behavior.
4614 Checking that ARGC is greater than # is the only way to ensure that
4615 ARGV# was passed to the function as an extra argument.
4616 get_cmake_property
4618 Get a global property of the CMake instance.
4619 get_cmake_property(<var> <property>)
4621 Gets a global property from the CMake instance. The value of the
4623 <property> is stored in the variable <var>. If the property is not
4624 found, <var> will be set to NOTFOUND. See the cmake-properties(7) man‐
4625 ual for available properties.
4626 See also the get_property() command GLOBAL option.
4628 In addition to global properties, this command (for historical reasons)
4630 also supports the VARIABLES and MACROS directory properties. It also
4631 supports a special COMPONENTS global property that lists the components
4632 given to the install() command.
4633 get_directory_property
4635 Get a property of DIRECTORY scope.
4636 get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
4638 Stores a property of directory scope in the named <variable>.
4640 The DIRECTORY argument specifies another directory from which to re‐
4642 trieve the property value instead of the current directory. Relative
4643 paths are treated as relative to the current source directory. CMake
4644 must already know about the directory, either by having added it
4645 through a call to add_subdirectory() or being the top level directory.
4646 New in version 3.19: <dir> may reference a binary directory.
4648 If the property is not defined for the nominated directory scope, an
4651 empty string is returned. In the case of INHERITED properties, if the
4652 property is not found for the nominated directory scope, the search
4653 will chain to a parent scope as described for the define_property()
4654 command.
4655 get_directory_property(<variable> [DIRECTORY <dir>]
4657 DEFINITION <var-name>)
4658 Get a variable definition from a directory. This form is useful to get
4660 a variable definition from another directory.
4661 See also the more general get_property() command.
4663 get_filename_component
4665 Get a specific component of a full filename.
4666 Changed in version 3.20: This command been superseded by cmake_path()
4668 command, except REALPATH now offered by file(REAL_PATH) command and
4669 PROGRAM now available in separate_arguments(PROGRAM) command.
4670 get_filename_component(<var> <FileName> <mode> [CACHE])
4673 Sets <var> to a component of <FileName>, where <mode> is one of:
4675 DIRECTORY = Directory without file name
4677 NAME = File name without directory
4678 EXT = File name longest extension (.b.c from d/a.b.c)
4679 NAME_WE = File name with neither the directory nor the longest extension
4680 LAST_EXT = File name last extension (.c from d/a.b.c)
4681 NAME_WLE = File name with neither the directory nor the last extension
4682 PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
4683 New in version 3.14: Added the LAST_EXT and NAME_WLE modes.
4685 Paths are returned with forward slashes and have no trailing slashes.
4688 If the optional CACHE argument is specified, the result variable is
4689 added to the cache.
4690 get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
4692 New in version 3.4.
4694 Sets <var> to the absolute path of <FileName>, where <mode> is one of:
4697 ABSOLUTE = Full path to file
4699 REALPATH = Full path to existing file with symlinks resolved
4700 If the provided <FileName> is a relative path, it is evaluated relative
4702 to the given base directory <dir>. If no base directory is provided,
4703 the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
4704 Paths are returned with forward slashes and have no trailing slashes.
4706 If the optional CACHE argument is specified, the result variable is
4707 added to the cache.
4708 get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
4710 The program in <FileName> will be found in the system search path or
4712 left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
4713 command-line arguments present in the <FileName> string are split from
4714 the program name and stored in <arg_var>. This is used to separate a
4715 program name from its arguments in a command line string.
4716 get_property
4718 Get a property.
4719 get_property(<variable>
4721 <GLOBAL |
4722 DIRECTORY [<dir>] |
4723 TARGET <target> |
4724 SOURCE <source>
4725 [DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
4726 INSTALL <file> |
4727 TEST <test> |
4728 CACHE <entry> |
4729 VARIABLE >
4730 PROPERTY <name>
4731 [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
4732 Gets one property from one object in a scope.
4734 The first argument specifies the variable in which to store the result.
4736 The second argument determines the scope from which to get the prop‐
4737 erty. It must be one of the following:
4738 GLOBAL Scope is unique and does not accept a name.
4740 DIRECTORY
4742 Scope defaults to the current directory but another directory
4743 (already processed by CMake) may be named by the full or rela‐
4744 tive path <dir>. Relative paths are treated as relative to the
4745 current source directory. See also the get_directory_property()
4746 command.
4747 New in version 3.19: <dir> may reference a binary directory.
4749 TARGET Scope must name one existing target. See also the get_tar‐
4752 get_property() command.
4753 SOURCE Scope must name one source file. By default, the source file's
4755 property will be read from the current source directory's scope.
4756 New in version 3.18: Directory scope can be overridden with one
4758 of the following sub-options:
4759 DIRECTORY <dir>
4761 The source file property will be read from the <dir> di‐
4762 rectory's scope. CMake must already know about the di‐
4763 rectory, either by having added it through a call to
4764 add_subdirectory() or <dir> being the top level direc‐
4765 tory. Relative paths are treated as relative to the cur‐
4766 rent source directory.
4767 New in version 3.19: <dir> may reference a binary direc‐
4769 tory.
4770 TARGET_DIRECTORY <target>
4773 The source file property will be read from the directory
4774 scope in which <target> was created (<target> must there‐
4775 fore already exist).
4776 See also the get_source_file_property() command.
4779 INSTALL
4781 New in version 3.1.
4782 Scope must name one installed file path.
4785 TEST Scope must name one existing test. See also the get_test_prop‐
4787 erty() command.
4788 CACHE Scope must name one cache entry.
4790 VARIABLE
4792 Scope is unique and does not accept a name.
4793 The required PROPERTY option is immediately followed by the name of the
4795 property to get. If the property is not set an empty value is re‐
4796 turned, although some properties support inheriting from a parent scope
4797 if defined to behave that way (see define_property()).
4798 If the SET option is given the variable is set to a boolean value indi‐
4800 cating whether the property has been set. If the DEFINED option is
4801 given the variable is set to a boolean value indicating whether the
4802 property has been defined such as with the define_property() command.
4803 If BRIEF_DOCS or FULL_DOCS is given then the variable is set to a
4805 string containing documentation for the requested property. If docu‐
4806 mentation is requested for a property that has not been defined NOT‐
4807 FOUND is returned.
4808 NOTE:
4810 The GENERATED source file property may be globally visible. See its
4811 documentation for details.
4812 if
4814 Conditionally execute a group of commands.
4815 Synopsis
4817 if(<condition>)
4818 <commands>
4819 elseif(<condition>) # optional block, can be repeated
4820 <commands>
4821 else() # optional block
4822 <commands>
4823 endif()
4824 Evaluates the condition argument of the if clause according to the
4826 Condition syntax described below. If the result is true, then the com‐
4827 mands in the if block are executed. Otherwise, optional elseif blocks
4828 are processed in the same way. Finally, if no condition is true, com‐
4829 mands in the optional else block are executed.
4830 Per legacy, the else() and endif() commands admit an optional <condi‐
4832 tion> argument. If used, it must be a verbatim repeat of the argument
4833 of the opening if command.
4834 Condition Syntax
4836 The following syntax applies to the condition argument of the if, el‐
4837 seif and while() clauses.
4838 Compound conditions are evaluated in the following order of precedence:
4840 Innermost parentheses are evaluated first. Next come unary tests such
4841 as EXISTS, COMMAND, and DEFINED. Then binary tests such as EQUAL,
4842 LESS, LESS_EQUAL, GREATER, GREATER_EQUAL, STREQUAL, STRLESS,
4843 STRLESS_EQUAL, STRGREATER, STRGREATER_EQUAL, VERSION_EQUAL,
4844 VERSION_LESS, VERSION_LESS_EQUAL, VERSION_GREATER,
4845 VERSION_GREATER_EQUAL, and MATCHES. Then the boolean operators in the
4846 order NOT, AND, and finally OR.
4847 Basic Expressions
4849 if(<constant>)
4850 True if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
4851 ber. False if the constant is 0, OFF, NO, FALSE, N, IGNORE,
4852 NOTFOUND, the empty string, or ends in the suffix -NOTFOUND.
4853 Named boolean constants are case-insensitive. If the argument
4854 is not one of these specific constants, it is treated as a vari‐
4855 able or string (see Variable Expansion further below) and one of
4856 the following two forms applies.
4857 if(<variable>)
4859 True if given a variable that is defined to a value that is not
4860 a false constant. False otherwise, including if the variable is
4861 undefined. Note that macro arguments are not variables. Envi‐
4862 ronment variables also cannot be tested this way, e.g.
4863 if(ENV{some_var}) will always evaluate to false.
4864 if(<string>)
4866 A quoted string always evaluates to false unless:
4867 • The string's value is one of the true constants, or
4869 • Policy CMP0054 is not set to NEW and the string's value hap‐
4871 pens to be a variable name that is affected by CMP0054's be‐
4872 havior.
4873 Logic Operators
4875 if(NOT <condition>)
4876 True if the condition is not true.
4877 if(<cond1> AND <cond2>)
4879 True if both conditions would be considered true individually.
4880 if(<cond1> OR <cond2>)
4882 True if either condition would be considered true individually.
4883 if((condition) AND (condition OR (condition)))
4885 The conditions inside the parenthesis are evaluated first and
4886 then the remaining condition is evaluated as in the other exam‐
4887 ples. Where there are nested parenthesis the innermost are
4888 evaluated as part of evaluating the condition that contains
4889 them.
4890 Existence Checks
4892 if(COMMAND command-name)
4893 True if the given name is a command, macro or function that can
4894 be invoked.
4895 if(POLICY policy-id)
4897 True if the given name is an existing policy (of the form
4898 CMP<NNNN>).
4899 if(TARGET target-name)
4901 True if the given name is an existing logical target name cre‐
4902 ated by a call to the add_executable(), add_library(), or
4903 add_custom_target() command that has already been invoked (in
4904 any directory).
4905 if(TEST test-name)
4907 New in version 3.3: True if the given name is an existing test
4908 name created by the add_test() command.
4909 if(DEFINED <name>|CACHE{<name>}|ENV{<name>})
4912 True if a variable, cache variable or environment variable with
4913 given <name> is defined. The value of the variable does not mat‐
4914 ter. Note that macro arguments are not variables.
4915 New in version 3.14: Added support for CACHE{<name>} variables.
4917 if(<variable|string> IN_LIST <variable>)
4920 New in version 3.3: True if the given element is contained in
4921 the named list variable.
4922 File Operations
4925 if(EXISTS path-to-file-or-directory)
4926 True if the named file or directory exists. Behavior is
4927 well-defined only for explicit full paths (a leading ~/ is not
4928 expanded as a home directory and is considered a relative path).
4929 Resolves symbolic links, i.e. if the named file or directory is
4930 a symbolic link, returns true if the target of the symbolic link
4931 exists.
4932 if(file1 IS_NEWER_THAN file2)
4934 True if file1 is newer than file2 or if one of the two files
4935 doesn't exist. Behavior is well-defined only for full paths.
4936 If the file time stamps are exactly the same, an IS_NEWER_THAN
4937 comparison returns true, so that any dependent build operations
4938 will occur in the event of a tie. This includes the case of
4939 passing the same file name for both file1 and file2.
4940 if(IS_DIRECTORY path-to-directory)
4942 True if the given name is a directory. Behavior is well-defined
4943 only for full paths.
4944 if(IS_SYMLINK file-name)
4946 True if the given name is a symbolic link. Behavior is well-de‐
4947 fined only for full paths.
4948 if(IS_ABSOLUTE path)
4950 True if the given path is an absolute path. Note the following
4951 special cases:
4952 • An empty path evaluates to false.
4954 • On Windows hosts, any path that begins with a drive letter and
4956 colon (e.g. C:), a forward slash or a backslash will evaluate
4957 to true. This means a path like C:no\base\dir will evaluate
4958 to true, even though the non-drive part of the path is rela‐
4959 tive.
4960 • On non-Windows hosts, any path that begins with a tilde (~)
4962 evaluates to true.
4963 Comparisons
4965 if(<variable|string> MATCHES regex)
4966 True if the given string or variable's value matches the given
4967 regular expression. See Regex Specification for regex format.
4968 New in version 3.9: () groups are captured in CMAKE_MATCH_<n>
4970 variables.
4971 if(<variable|string> LESS <variable|string>)
4974 True if the given string or variable's value is a valid number
4975 and less than that on the right.
4976 if(<variable|string> GREATER <variable|string>)
4978 True if the given string or variable's value is a valid number
4979 and greater than that on the right.
4980 if(<variable|string> EQUAL <variable|string>)
4982 True if the given string or variable's value is a valid number
4983 and equal to that on the right.
4984 if(<variable|string> LESS_EQUAL <variable|string>)
4986 New in version 3.7: True if the given string or variable's value
4987 is a valid number and less than or equal to that on the right.
4988 if(<variable|string> GREATER_EQUAL <variable|string>)
4991 New in version 3.7: True if the given string or variable's value
4992 is a valid number and greater than or equal to that on the
4993 right.
4994 if(<variable|string> STRLESS <variable|string>)
4997 True if the given string or variable's value is lexicographi‐
4998 cally less than the string or variable on the right.
4999 if(<variable|string> STRGREATER <variable|string>)
5001 True if the given string or variable's value is lexicographi‐
5002 cally greater than the string or variable on the right.
5003 if(<variable|string> STREQUAL <variable|string>)
5005 True if the given string or variable's value is lexicographi‐
5006 cally equal to the string or variable on the right.
5007 if(<variable|string> STRLESS_EQUAL <variable|string>)
5009 New in version 3.7: True if the given string or variable's value
5010 is lexicographically less than or equal to the string or vari‐
5011 able on the right.
5012 if(<variable|string> STRGREATER_EQUAL <variable|string>)
5015 New in version 3.7: True if the given string or variable's value
5016 is lexicographically greater than or equal to the string or
5017 variable on the right.
5018 Version Comparisons
5021 if(<variable|string> VERSION_LESS <variable|string>)
5022 Component-wise integer version number comparison (version format
5023 is major[.minor[.patch[.tweak]]], omitted components are treated
5024 as zero). Any non-integer version component or non-integer
5025 trailing part of a version component effectively truncates the
5026 string at that point.
5027 if(<variable|string> VERSION_GREATER <variable|string>)
5029 Component-wise integer version number comparison (version format
5030 is major[.minor[.patch[.tweak]]], omitted components are treated
5031 as zero). Any non-integer version component or non-integer
5032 trailing part of a version component effectively truncates the
5033 string at that point.
5034 if(<variable|string> VERSION_EQUAL <variable|string>)
5036 Component-wise integer version number comparison (version format
5037 is major[.minor[.patch[.tweak]]], omitted components are treated
5038 as zero). Any non-integer version component or non-integer
5039 trailing part of a version component effectively truncates the
5040 string at that point.
5041 if(<variable|string> VERSION_LESS_EQUAL <variable|string>)
5043 New in version 3.7: Component-wise integer version number com‐
5044 parison (version format is major[.minor[.patch[.tweak]]], omit‐
5045 ted components are treated as zero). Any non-integer version
5046 component or non-integer trailing part of a version component
5047 effectively truncates the string at that point.
5048 if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)
5051 New in version 3.7: Component-wise integer version number com‐
5052 parison (version format is major[.minor[.patch[.tweak]]], omit‐
5053 ted components are treated as zero). Any non-integer version
5054 component or non-integer trailing part of a version component
5055 effectively truncates the string at that point.
5056 Variable Expansion
5059 The if command was written very early in CMake's history, predating the
5060 ${} variable evaluation syntax, and for convenience evaluates variables
5061 named by its arguments as shown in the above signatures. Note that
5062 normal variable evaluation with ${} applies before the if command even
5063 receives the arguments. Therefore code like
5064 set(var1 OFF)
5066 set(var2 "var1")
5067 if(${var2})
5068 appears to the if command as
5070 if(var1)
5072 and is evaluated according to the if(<variable>) case documented above.
5074 The result is OFF which is false. However, if we remove the ${} from
5075 the example then the command sees
5076 if(var2)
5078 which is true because var2 is defined to var1 which is not a false con‐
5080 stant.
5081 Automatic evaluation applies in the other cases whenever the above-doc‐
5083 umented condition syntax accepts <variable|string>:
5084 • The left hand argument to MATCHES is first checked to see if it is a
5086 defined variable, if so the variable's value is used, otherwise the
5087 original value is used.
5088 • If the left hand argument to MATCHES is missing it returns false
5090 without error
5091 • Both left and right hand arguments to LESS, GREATER, EQUAL,
5093 LESS_EQUAL, and GREATER_EQUAL, are independently tested to see if
5094 they are defined variables, if so their defined values are used oth‐
5095 erwise the original value is used.
5096 • Both left and right hand arguments to STRLESS, STRGREATER, STREQUAL,
5098 STRLESS_EQUAL, and STRGREATER_EQUAL are independently tested to see
5099 if they are defined variables, if so their defined values are used
5100 otherwise the original value is used.
5101 • Both left and right hand arguments to VERSION_LESS, VERSION_GREATER,
5103 VERSION_EQUAL, VERSION_LESS_EQUAL, and VERSION_GREATER_EQUAL are in‐
5104 dependently tested to see if they are defined variables, if so their
5105 defined values are used otherwise the original value is used.
5106 • The right hand argument to NOT is tested to see if it is a boolean
5108 constant, if so the value is used, otherwise it is assumed to be a
5109 variable and it is dereferenced.
5110 • The left and right hand arguments to AND and OR are independently
5112 tested to see if they are boolean constants, if so they are used as
5113 such, otherwise they are assumed to be variables and are derefer‐
5114 enced.
5115 Changed in version 3.1: To prevent ambiguity, potential variable or
5117 keyword names can be specified in a Quoted Argument or a Bracket Argu‐
5118 ment. A quoted or bracketed variable or keyword will be interpreted as
5119 a string and not dereferenced or interpreted. See policy CMP0054.
5120 There is no automatic evaluation for environment or cache Variable Ref‐
5123 erences. Their values must be referenced as $ENV{<name>} or
5124 $CACHE{<name>} wherever the above-documented condition syntax accepts
5125 <variable|string>.
5126 include
5128 Load and run CMake code from a file or module.
5129 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
5131 [NO_POLICY_SCOPE])
5132 Loads and runs CMake code from the file given. Variable reads and
5134 writes access the scope of the caller (dynamic scoping). If OPTIONAL
5135 is present, then no error is raised if the file does not exist. If RE‐
5136 SULT_VARIABLE is given the variable <var> will be set to the full file‐
5137 name which has been included or NOTFOUND if it failed.
5138 If a module is specified instead of a file, the file with name <module‐
5140 name>.cmake is searched first in CMAKE_MODULE_PATH, then in the CMake
5141 module directory. There is one exception to this: if the file which
5142 calls include() is located itself in the CMake builtin module direc‐
5143 tory, then first the CMake builtin module directory is searched and
5144 CMAKE_MODULE_PATH afterwards. See also policy CMP0017.
5145 See the cmake_policy() command documentation for discussion of the
5147 NO_POLICY_SCOPE option.
5148 include_guard
5150 New in version 3.10.
5151 Provides an include guard for the file currently being processed by
5154 CMake.
5155 include_guard([DIRECTORY|GLOBAL])
5157 Sets up an include guard for the current CMake file (see the CMAKE_CUR‐
5159 RENT_LIST_FILE variable documentation).
5160 CMake will end its processing of the current file at the location of
5162 the include_guard() command if the current file has already been pro‐
5163 cessed for the applicable scope (see below). This provides functional‐
5164 ity similar to the include guards commonly used in source headers or to
5165 the #pragma once directive. If the current file has been processed pre‐
5166 viously for the applicable scope, the effect is as though return() had
5167 been called. Do not call this command from inside a function being de‐
5168 fined within the current file.
5169 An optional argument specifying the scope of the guard may be provided.
5171 Possible values for the option are:
5172 DIRECTORY
5174 The include guard applies within the current directory and be‐
5175 low. The file will only be included once within this directory
5176 scope, but may be included again by other files outside of this
5177 directory (i.e. a parent directory or another directory not
5178 pulled in by add_subdirectory() or include() from the current
5179 file or its children).
5180 GLOBAL The include guard applies globally to the whole build. The cur‐
5182 rent file will only be included once regardless of the scope.
5183 If no arguments given, include_guard has the same scope as a variable,
5185 meaning that the include guard effect is isolated by the most recent
5186 function scope or current directory if no inner function scopes exist.
5187 In this case the command behavior is the same as:
5188 if(__CURRENT_FILE_VAR__)
5190 return()
5191 endif()
5192 set(__CURRENT_FILE_VAR__ TRUE)
5193 list
5195 List operations.
5196 Synopsis
5198 Reading
5199 list(LENGTH <list> <out-var>)
5200 list(GET <list> <element index> [<index> ...] <out-var>)
5201 list(JOIN <list> <glue> <out-var>)
5202 list(SUBLIST <list> <begin> <length> <out-var>)
5203 Search
5205 list(FIND <list> <value> <out-var>)
5206 Modification
5208 list(APPEND <list> [<element>...])
5209 list(FILTER <list> {INCLUDE | EXCLUDE} REGEX <regex>)
5210 list(INSERT <list> <index> [<element>...])
5211 list(POP_BACK <list> [<out-var>...])
5212 list(POP_FRONT <list> [<out-var>...])
5213 list(PREPEND <list> [<element>...])
5214 list(REMOVE_ITEM <list> <value>...)
5215 list(REMOVE_AT <list> <index>...)
5216 list(REMOVE_DUPLICATES <list>)
5217 list(TRANSFORM <list> <ACTION> [...])
5218 Ordering
5220 list(REVERSE <list>)
5221 list(SORT <list> [...])
5222 Introduction
5224 The list subcommands APPEND, INSERT, FILTER, PREPEND, POP_BACK,
5225 POP_FRONT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, REVERSE and SORT
5226 may create new values for the list within the current CMake variable
5227 scope. Similar to the set() command, the LIST command creates new
5228 variable values in the current scope, even if the list itself is actu‐
5229 ally defined in a parent scope. To propagate the results of these op‐
5230 erations upwards, use set() with PARENT_SCOPE, set() with CACHE INTER‐
5231 NAL, or some other means of value propagation.
5232 NOTE:
5234 A list in cmake is a ; separated group of strings. To create a list
5235 the set command can be used. For example, set(var a b c d e) cre‐
5236 ates a list with a;b;c;d;e, and set(var "a b c d e") creates a
5237 string or a list with one item in it. (Note macro arguments are
5238 not variables, and therefore cannot be used in LIST commands.)
5239 NOTE:
5241 When specifying index values, if <element index> is 0 or greater, it
5242 is indexed from the beginning of the list, with 0 representing the
5243 first list element. If <element index> is -1 or lesser, it is in‐
5244 dexed from the end of the list, with -1 representing the last list
5245 element. Be careful when counting with negative indices: they do
5246 not start from 0. -0 is equivalent to 0, the first list element.
5247 Reading
5249 list(LENGTH <list> <output variable>)
5250 Returns the list's length.
5252 list(GET <list> <element index> [<element index> ...] <output variable>)
5254 Returns the list of elements specified by indices from the list.
5256 list(JOIN <list> <glue> <output variable>)
5258 New in version 3.12.
5260 Returns a string joining all list's elements using the glue string. To
5263 join multiple strings, which are not part of a list, use JOIN operator
5264 from string() command.
5265 list(SUBLIST <list> <begin> <length> <output variable>)
5267 New in version 3.12.
5269 Returns a sublist of the given list. If <length> is 0, an empty list
5272 will be returned. If <length> is -1 or the list is smaller than <be‐
5273 gin>+<length> then the remaining elements of the list starting at <be‐
5274 gin> will be returned.
5275 Search
5277 list(FIND <list> <value> <output variable>)
5278 Returns the index of the element specified in the list or -1 if it
5280 wasn't found.
5281 Modification
5283 list(APPEND <list> [<element> ...])
5284 Appends elements to the list.
5286 list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
5288 New in version 3.6.
5290 Includes or removes items from the list that match the mode's pattern.
5293 In REGEX mode, items will be matched against the given regular expres‐
5294 sion.
5295 For more information on regular expressions look under string(REGEX).
5297 list(INSERT <list> <element_index> <element> [<element> ...])
5299 Inserts elements to the list to the specified location.
5301 list(POP_BACK <list> [<out-var>...])
5303 New in version 3.15.
5305 If no variable name is given, removes exactly one element. Otherwise,
5308 with N variable names provided, assign the last N elements' values to
5309 the given variables and then remove the last N values from <list>.
5310 list(POP_FRONT <list> [<out-var>...])
5312 New in version 3.15.
5314 If no variable name is given, removes exactly one element. Otherwise,
5317 with N variable names provided, assign the first N elements' values to
5318 the given variables and then remove the first N values from <list>.
5319 list(PREPEND <list> [<element> ...])
5321 New in version 3.15.
5323 Insert elements to the 0th position in the list.
5326 list(REMOVE_ITEM <list> <value> [<value> ...])
5328 Removes all instances of the given items from the list.
5330 list(REMOVE_AT <list> <index> [<index> ...])
5332 Removes items at given indices from the list.
5334 list(REMOVE_DUPLICATES <list>)
5336 Removes duplicated items in the list. The relative order of items is
5338 preserved, but if duplicates are encountered, only the first instance
5339 is preserved.
5340 list(TRANSFORM <list> <ACTION> [<SELECTOR>]
5342 [OUTPUT_VARIABLE <output variable>])
5343 New in version 3.12.
5345 Transforms the list by applying an action to all or, by specifying a
5348 <SELECTOR>, to the selected elements of the list, storing the result
5349 in-place or in the specified output variable.
5350 NOTE:
5352 The TRANSFORM sub-command does not change the number of elements in
5353 the list. If a <SELECTOR> is specified, only some elements will be
5354 changed, the other ones will remain the same as before the transfor‐
5355 mation.
5356 <ACTION> specifies the action to apply to the elements of the list.
5358 The actions have exactly the same semantics as sub-commands of the
5359 string() command. <ACTION> must be one of the following:
5360 APPEND, PREPEND: Append, prepend specified value to each element of the
5362 list.
5363 list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
5365 TOUPPER, TOLOWER: Convert each element of the list to upper, lower
5367 characters.
5368 list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
5370 STRIP: Remove leading and trailing spaces from each element of the
5372 list.
5373 list(TRANSFORM <list> STRIP ...)
5375 GENEX_STRIP: Strip any generator expressions from each element of the
5377 list.
5378 list(TRANSFORM <list> GENEX_STRIP ...)
5380 REPLACE: Match the regular expression as many times as possible and
5382 substitute the replacement expression for the match for each element of
5383 the list (Same semantic as REGEX REPLACE from string() command).
5384 list(TRANSFORM <list> REPLACE <regular_expression>
5386 <replace_expression> ...)
5387 <SELECTOR> determines which elements of the list will be transformed.
5389 Only one type of selector can be specified at a time. When given, <SE‐
5390 LECTOR> must be one of the following:
5391 AT: Specify a list of indexes.
5393 list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
5395 FOR: Specify a range with, optionally, an increment used to iterate
5397 over the range.
5398 list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
5400 REGEX: Specify a regular expression. Only elements matching the regular
5402 expression will be transformed.
5403 list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
5405 Ordering
5407 list(REVERSE <list>)
5408 Reverses the contents of the list in-place.
5410 list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
5412 Sorts the list in-place alphabetically.
5414 New in version 3.13: Added the COMPARE, CASE, and ORDER options.
5416 New in version 3.18: Added the COMPARE NATURAL option.
5419 Use the COMPARE keyword to select the comparison method for sorting.
5422 The <compare> option should be one of:
5423 • STRING: Sorts a list of strings alphabetically. This is the default
5425 behavior if the COMPARE option is not given.
5426 • FILE_BASENAME: Sorts a list of pathnames of files by their basenames.
5428 • NATURAL: Sorts a list of strings using natural order (see strver‐
5430 scmp(3) manual), i.e. such that contiguous digits are compared as
5431 whole numbers. For example: the following list 10.0 1.1 2.1 8.0 2.0
5432 3.1 will be sorted as 1.1 2.0 2.1 3.1 8.0 10.0 if the NATURAL compar‐
5433 ison is selected where it will be sorted as 1.1 10.0 2.0 2.1 3.1 8.0
5434 with the STRING comparison.
5435 Use the CASE keyword to select a case sensitive or case insensitive
5437 sort mode. The <case> option should be one of:
5438 • SENSITIVE: List items are sorted in a case-sensitive manner. This is
5440 the default behavior if the CASE option is not given.
5441 • INSENSITIVE: List items are sorted case insensitively. The order of
5443 items which differ only by upper/lowercase is not specified.
5444 To control the sort order, the ORDER keyword can be given. The <order>
5446 option should be one of:
5447 • ASCENDING: Sorts the list in ascending order. This is the default
5449 behavior when the ORDER option is not given.
5450 • DESCENDING: Sorts the list in descending order.
5452 macro
5454 Start recording a macro for later invocation as a command
5455 macro(<name> [<arg1> ...])
5457 <commands>
5458 endmacro()
5459 Defines a macro named <name> that takes arguments named <arg1>, ...
5461 Commands listed after macro, but before the matching endmacro(), are
5462 not executed until the macro is invoked.
5463 Per legacy, the endmacro() command admits an optional <name> argument.
5465 If used, it must be a verbatim repeat of the argument of the opening
5466 macro command.
5467 See the cmake_policy() command documentation for the behavior of poli‐
5469 cies inside macros.
5470 See the Macro vs Function section below for differences between CMake
5472 macros and functions.
5473 Invocation
5475 The macro invocation is case-insensitive. A macro defined as
5476 macro(foo)
5478 <commands>
5479 endmacro()
5480 can be invoked through any of
5482 foo()
5484 Foo()
5485 FOO()
5486 cmake_language(CALL foo)
5487 and so on. However, it is strongly recommended to stay with the case
5489 chosen in the macro definition. Typically macros use all-lowercase
5490 names.
5491 New in version 3.18: The cmake_language(CALL ...) command can also be
5493 used to invoke the macro.
5494 Arguments
5497 When a macro is invoked, the commands recorded in the macro are first
5498 modified by replacing formal parameters (${arg1}, ...) with the argu‐
5499 ments passed, and then invoked as normal commands.
5500 In addition to referencing the formal parameters you can reference the
5502 values ${ARGC} which will be set to the number of arguments passed into
5503 the function as well as ${ARGV0}, ${ARGV1}, ${ARGV2}, ... which will
5504 have the actual values of the arguments passed in. This facilitates
5505 creating macros with optional arguments.
5506 Furthermore, ${ARGV} holds the list of all arguments given to the macro
5508 and ${ARGN} holds the list of arguments past the last expected argu‐
5509 ment. Referencing to ${ARGV#} arguments beyond ${ARGC} have undefined
5510 behavior. Checking that ${ARGC} is greater than # is the only way to
5511 ensure that ${ARGV#} was passed to the function as an extra argument.
5512 Macro vs Function
5514 The macro command is very similar to the function() command. Nonethe‐
5515 less, there are a few important differences.
5516 In a function, ARGN, ARGC, ARGV and ARGV0, ARGV1, ... are true vari‐
5518 ables in the usual CMake sense. In a macro, they are not, they are
5519 string replacements much like the C preprocessor would do with a macro.
5520 This has a number of consequences, as explained in the Argument Caveats
5521 section below.
5522 Another difference between macros and functions is the control flow. A
5524 function is executed by transferring control from the calling statement
5525 to the function body. A macro is executed as if the macro body were
5526 pasted in place of the calling statement. This has the consequence
5527 that a return() in a macro body does not just terminate execution of
5528 the macro; rather, control is returned from the scope of the macro
5529 call. To avoid confusion, it is recommended to avoid return() in
5530 macros altogether.
5531 Unlike a function, the CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNC‐
5533 TION_LIST_DIR, CMAKE_CURRENT_FUNCTION_LIST_FILE, CMAKE_CURRENT_FUNC‐
5534 TION_LIST_LINE variables are not set for a macro.
5535 Argument Caveats
5537 Since ARGN, ARGC, ARGV, ARGV0 etc. are not variables, you will NOT be
5538 able to use commands like
5539 if(ARGV1) # ARGV1 is not a variable
5541 if(DEFINED ARGV2) # ARGV2 is not a variable
5542 if(ARGC GREATER 2) # ARGC is not a variable
5543 foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
5544 In the first case, you can use if(${ARGV1}). In the second and third
5546 case, the proper way to check if an optional variable was passed to the
5547 macro is to use if(${ARGC} GREATER 2). In the last case, you can use
5548 foreach(loop_var ${ARGN}) but this will skip empty arguments. If you
5549 need to include them, you can use
5550 set(list_var "${ARGN}")
5552 foreach(loop_var IN LISTS list_var)
5553 Note that if you have a variable with the same name in the scope from
5555 which the macro is called, using unreferenced names will use the exist‐
5556 ing variable instead of the arguments. For example:
5557 macro(bar)
5559 foreach(arg IN LISTS ARGN)
5560 <commands>
5561 endforeach()
5562 endmacro()
5563 function(foo)
5565 bar(x y z)
5566 endfunction()
5567 foo(a b c)
5569 Will loop over a;b;c and not over x;y;z as one might have expected. If
5571 you want true CMake variables and/or better CMake scope control you
5572 should look at the function command.
5573 mark_as_advanced
5575 Mark cmake cached variables as advanced.
5576 mark_as_advanced([CLEAR|FORCE] <var1> ...)
5578 Sets the advanced/non-advanced state of the named cached variables.
5580 An advanced variable will not be displayed in any of the cmake GUIs un‐
5582 less the show advanced option is on. In script mode, the ad‐
5583 vanced/non-advanced state has no effect.
5584 If the keyword CLEAR is given then advanced variables are changed back
5586 to unadvanced. If the keyword FORCE is given then the variables are
5587 made advanced. If neither FORCE nor CLEAR is specified, new values
5588 will be marked as advanced, but if a variable already has an ad‐
5589 vanced/non-advanced state, it will not be changed.
5590 Changed in version 3.17: Variables passed to this command which are not
5592 already in the cache are ignored. See policy CMP0102.
5593 math
5596 Evaluate a mathematical expression.
5597 math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])
5599 Evaluates a mathematical <expression> and sets <variable> to the re‐
5601 sulting value. The result of the expression must be representable as a
5602 64-bit signed integer.
5603 The mathematical expression must be given as a string (i.e. enclosed in
5605 double quotation marks). An example is "5 * (10 + 13)". Supported op‐
5606 erators are +, -, *, /, %, |, &, ^, ~, <<, >>, and (...); they have the
5607 same meaning as in C code.
5608 New in version 3.13: Hexadecimal numbers are recognized when prefixed
5610 with 0x, as in C code.
5611 New in version 3.13: The result is formatted according to the option
5614 OUTPUT_FORMAT, where <format> is one of
5615 HEXADECIMAL
5617 Hexadecimal notation as in C code, i. e. starting with "0x".
5618 DECIMAL
5620 Decimal notation. Which is also used if no OUTPUT_FORMAT option
5621 is specified.
5622 For example
5625 math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL) # value is set to "1000"
5627 math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL) # value is set to "0x3e8"
5628 message
5630 Log a message.
5631 Synopsis
5633 General messages
5634 message([<mode>] "message text" ...)
5635 Reporting checks
5637 message(<checkState> "message text" ...)
5638 General messages
5640 message([<mode>] "message text" ...)
5641 Record the specified message text in the log. If more than one message
5643 string is given, they are concatenated into a single message with no
5644 separator between the strings.
5645 The optional <mode> keyword determines the type of message, which in‐
5647 fluences the way the message is handled:
5648 FATAL_ERROR
5650 CMake Error, stop processing and generation.
5651 SEND_ERROR
5653 CMake Error, continue processing, but skip generation.
5654 WARNING
5656 CMake Warning, continue processing.
5657 AUTHOR_WARNING
5659 CMake Warning (dev), continue processing.
5660 DEPRECATION
5662 CMake Deprecation Error or Warning if variable CMAKE_ERROR_DEP‐
5663 RECATED or CMAKE_WARN_DEPRECATED is enabled, respectively, else
5664 no message.
5665 (none) or NOTICE
5667 Important message printed to stderr to attract user's attention.
5668 STATUS The main interesting messages that project users might be inter‐
5670 ested in. Ideally these should be concise, no more than a sin‐
5671 gle line, but still informative.
5672 VERBOSE
5674 Detailed informational messages intended for project users.
5675 These messages should provide additional details that won't be
5676 of interest in most cases, but which may be useful to those
5677 building the project when they want deeper insight into what's
5678 happening.
5679 DEBUG Detailed informational messages intended for developers working
5681 on the project itself as opposed to users who just want to build
5682 it. These messages will not typically be of interest to other
5683 users building the project and will often be closely related to
5684 internal implementation details.
5685 TRACE Fine-grained messages with very low-level implementation de‐
5687 tails. Messages using this log level would normally only be
5688 temporary and would expect to be removed before releasing the
5689 project, packaging up the files, etc.
5690 New in version 3.15: Added the NOTICE, VERBOSE, DEBUG, and TRACE lev‐
5692 els.
5693 The CMake command-line tool displays STATUS to TRACE messages on stdout
5696 with the message preceded by two hyphens and a space. All other mes‐
5697 sage types are sent to stderr and are not prefixed with hyphens. The
5698 CMake GUI displays all messages in its log area. The curses interface
5699 shows STATUS to TRACE messages one at a time on a status line and other
5700 messages in an interactive pop-up box. The --log-level command-line
5701 option to each of these tools can be used to control which messages
5702 will be shown.
5703 New in version 3.17: To make a log level persist between CMake runs,
5705 the CMAKE_MESSAGE_LOG_LEVEL variable can be set instead. Note that the
5706 command line option takes precedence over the cache variable.
5707 New in version 3.16: Messages of log levels NOTICE and below will have
5710 each line preceded by the content of the CMAKE_MESSAGE_INDENT variable
5711 (converted to a single string by concatenating its list items). For
5712 STATUS to TRACE messages, this indenting content will be inserted after
5713 the hyphens.
5714 New in version 3.17: Messages of log levels NOTICE and below can also
5717 have each line preceded with context of the form [some.context.exam‐
5718 ple]. The content between the square brackets is obtained by convert‐
5719 ing the CMAKE_MESSAGE_CONTEXT list variable to a dot-separated string.
5720 The message context will always appear before any indenting content but
5721 after any automatically added leading hyphens. By default, message con‐
5722 text is not shown, it has to be explicitly enabled by giving the cmake
5723 --log-context command-line option or by setting the CMAKE_MESSAGE_CON‐
5724 TEXT_SHOW variable to true. See the CMAKE_MESSAGE_CONTEXT documenta‐
5725 tion for usage examples.
5726 CMake Warning and Error message text displays using a simple markup
5729 language. Non-indented text is formatted in line-wrapped paragraphs
5730 delimited by newlines. Indented text is considered pre-formatted.
5731 Reporting checks
5733 New in version 3.17.
5734 A common pattern in CMake output is a message indicating the start of
5737 some sort of check, followed by another message reporting the result of
5738 that check. For example:
5739 message(STATUS "Looking for someheader.h")
5741 #... do the checks, set checkSuccess with the result
5742 if(checkSuccess)
5743 message(STATUS "Looking for someheader.h - found")
5744 else()
5745 message(STATUS "Looking for someheader.h - not found")
5746 endif()
5747 This can be more robustly and conveniently expressed using the
5749 CHECK_... keyword form of the message() command:
5750 message(<checkState> "message" ...)
5752 where <checkState> must be one of the following:
5754 CHECK_START
5756 Record a concise message about the check about to be per‐
5757 formed.
5758 CHECK_PASS
5760 Record a successful result for a check.
5761 CHECK_FAIL
5763 Record an unsuccessful result for a check.
5764 When recording a check result, the command repeats the message from the
5766 most recently started check for which no result has yet been reported,
5767 then some separator characters and then the message text provided after
5768 the CHECK_PASS or CHECK_FAIL keyword. Check messages are always re‐
5769 ported at STATUS log level.
5770 Checks may be nested and every CHECK_START should have exactly one
5772 matching CHECK_PASS or CHECK_FAIL. The CMAKE_MESSAGE_INDENT variable
5773 can also be used to add indenting to nested checks if desired. For ex‐
5774 ample:
5775 message(CHECK_START "Finding my things")
5777 list(APPEND CMAKE_MESSAGE_INDENT " ")
5778 unset(missingComponents)
5779 message(CHECK_START "Finding partA")
5781 # ... do check, assume we find A
5782 message(CHECK_PASS "found")
5783 message(CHECK_START "Finding partB")
5785 # ... do check, assume we don't find B
5786 list(APPEND missingComponents B)
5787 message(CHECK_FAIL "not found")
5788 list(POP_BACK CMAKE_MESSAGE_INDENT)
5790 if(missingComponents)
5791 message(CHECK_FAIL "missing components: ${missingComponents}")
5792 else()
5793 message(CHECK_PASS "all components found")
5794 endif()
5795 Output from the above would appear something like the following:
5797 -- Finding my things
5799 -- Finding partA
5800 -- Finding partA - found
5801 -- Finding partB
5802 -- Finding partB - not found
5803 -- Finding my things - missing components: B
5804 option
5806 Provide an option that the user can optionally select.
5807 option(<variable> "<help_text>" [value])
5809 Provides an option for the user to select as ON or OFF. If no initial
5811 <value> is provided, OFF is used. If <variable> is already set as a
5812 normal or cache variable, then the command does nothing (see policy
5813 CMP0077).
5814 If you have options that depend on the values of other options, see the
5816 module help for CMakeDependentOption.
5817 return
5819 Return from a file, directory or function.
5820 return()
5822 Returns from a file, directory or function. When this command is en‐
5824 countered in an included file (via include() or find_package()), it
5825 causes processing of the current file to stop and control is returned
5826 to the including file. If it is encountered in a file which is not in‐
5827 cluded by another file, e.g. a CMakeLists.txt, deferred calls sched‐
5828 uled by cmake_language(DEFER) are invoked and control is returned to
5829 the parent directory if there is one. If return is called in a func‐
5830 tion, control is returned to the caller of the function.
5831 Note that a macro, unlike a function, is expanded in place and there‐
5833 fore cannot handle return().
5834 separate_arguments
5836 Parse command-line arguments into a semicolon-separated list.
5837 separate_arguments(<variable> <mode> [PROGRAM [SEPARATE_ARGS]] <args>)
5839 Parses a space-separated string <args> into a list of items, and stores
5841 this list in semicolon-separated standard form in <variable>.
5842 This function is intended for parsing command-line arguments. The en‐
5844 tire command line must be passed as one string in the argument <args>.
5845 The exact parsing rules depend on the operating system. They are spec‐
5847 ified by the <mode> argument which must be one of the following key‐
5848 words:
5849 UNIX_COMMAND
5851 Arguments are separated by unquoted whitespace. Both sin‐
5852 gle-quote and double-quote pairs are respected. A backslash es‐
5853 capes the next literal character (\" is "); there are no special
5854 escapes (\n is just n).
5855 WINDOWS_COMMAND
5857 A Windows command-line is parsed using the same syntax the run‐
5858 time library uses to construct argv at startup. It separates
5859 arguments by whitespace that is not double-quoted. Backslashes
5860 are literal unless they precede double-quotes. See the MSDN ar‐
5861 ticle Parsing C Command-Line Arguments for details.
5862 NATIVE_COMMAND
5864 New in version 3.9.
5865 Proceeds as in WINDOWS_COMMAND mode if the host system is Win‐
5868 dows. Otherwise proceeds as in UNIX_COMMAND mode.
5869 PROGRAM
5871 New in version 3.19.
5872 The first item in <args> is assumed to be an executable and will
5875 be searched in the system search path or left as a full path. If
5876 not found, <variable> will be empty. Otherwise, <variable> is a
5877 list of 2 elements:
5878 0. Absolute path of the program
5880 1. Any command-line arguments present in <args> as a string
5882 For example:
5884 separate_arguments (out UNIX_COMMAND PROGRAM "cc -c main.c")
5886 • First element of the list: /path/to/cc
5888 • Second element of the list: " -c main.c"
5890 SEPARATE_ARGS
5892 When this sub-option of PROGRAM option is specified, com‐
5893 mand-line arguments will be split as well and stored in <vari‐
5894 able>.
5895 For example:
5897 separate_arguments (out UNIX_COMMAND PROGRAM SEPARATE_ARGS "cc -c main.c")
5899 The contents of out will be: /path/to/cc;-c;main.c
5901 separate_arguments(<var>)
5903 Convert the value of <var> to a semi-colon separated list. All spaces
5905 are replaced with ';'. This helps with generating command lines.
5906 set
5908 Set a normal, cache, or environment variable to a given value. See the
5909 cmake-language(7) variables documentation for the scopes and interac‐
5910 tion of normal variables and cache entries.
5911 Signatures of this command that specify a <value>... placeholder expect
5913 zero or more arguments. Multiple arguments will be joined as a semi‐
5914 colon-separated list to form the actual variable value to be set. Zero
5915 arguments will cause normal variables to be unset. See the unset()
5916 command to unset variables explicitly.
5917 Set Normal Variable
5919 set(<variable> <value>... [PARENT_SCOPE])
5920 Sets the given <variable> in the current function or directory scope.
5922 If the PARENT_SCOPE option is given the variable will be set in the
5924 scope above the current scope. Each new directory or function creates
5925 a new scope. This command will set the value of a variable into the
5926 parent directory or calling function (whichever is applicable to the
5927 case at hand). The previous state of the variable's value stays the
5928 same in the current scope (e.g., if it was undefined before, it is
5929 still undefined and if it had a value, it is still that value).
5930 Set Cache Entry
5932 set(<variable> <value>... CACHE <type> <docstring> [FORCE])
5933 Sets the given cache <variable> (cache entry). Since cache entries are
5935 meant to provide user-settable values this does not overwrite existing
5936 cache entries by default. Use the FORCE option to overwrite existing
5937 entries.
5938 The <type> must be specified as one of:
5940 BOOL Boolean ON/OFF value. cmake-gui(1) offers a checkbox.
5942 FILEPATH
5944 Path to a file on disk. cmake-gui(1) offers a file dialog.
5945 PATH Path to a directory on disk. cmake-gui(1) offers a file dialog.
5947 STRING A line of text. cmake-gui(1) offers a text field or a drop-down
5949 selection if the STRINGS cache entry property is set.
5950 INTERNAL
5952 A line of text. cmake-gui(1) does not show internal entries.
5953 They may be used to store variables persistently across runs.
5954 Use of this type implies FORCE.
5955 The <docstring> must be specified as a line of text providing a quick
5957 summary of the option for presentation to cmake-gui(1) users.
5958 If the cache entry does not exist prior to the call or the FORCE option
5960 is given then the cache entry will be set to the given value.
5961 NOTE:
5963 The content of the cache variable will not be directly accessible if
5964 a normal variable of the same name already exists (see rules of
5965 variable evaluation). If policy CMP0126 is set to OLD, any normal
5966 variable binding in the current scope will be removed.
5967 It is possible for the cache entry to exist prior to the call but have
5969 no type set if it was created on the cmake(1) command line by a user
5970 through the -D<var>=<value> option without specifying a type. In this
5971 case the set command will add the type. Furthermore, if the <type> is
5972 PATH or FILEPATH and the <value> provided on the command line is a rel‐
5973 ative path, then the set command will treat the path as relative to the
5974 current working directory and convert it to an absolute path.
5975 Set Environment Variable
5977 set(ENV{<variable>} [<value>])
5978 Sets an Environment Variable to the given value. Subsequent calls of
5980 $ENV{<variable>} will return this new value.
5981 This command affects only the current CMake process, not the process
5983 from which CMake was called, nor the system environment at large, nor
5984 the environment of subsequent build or test processes.
5985 If no argument is given after ENV{<variable>} or if <value> is an empty
5987 string, then this command will clear any existing value of the environ‐
5988 ment variable.
5989 Arguments after <value> are ignored. If extra arguments are found, then
5991 an author warning is issued.
5992 set_directory_properties
5994 Set properties of the current directory and subdirectories.
5995 set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...)
5997 Sets properties of the current directory and its subdirectories in
5999 key-value pairs.
6000 See also the set_property(DIRECTORY) command.
6002 See Directory Properties for the list of properties known to CMake and
6004 their individual documentation for the behavior of each property.
6005 set_property
6007 Set a named property in a given scope.
6008 set_property(<GLOBAL |
6010 DIRECTORY [<dir>] |
6011 TARGET [<target1> ...] |
6012 SOURCE [<src1> ...]
6013 [DIRECTORY <dirs> ...]
6014 [TARGET_DIRECTORY <targets> ...] |
6015 INSTALL [<file1> ...] |
6016 TEST [<test1> ...] |
6017 CACHE [<entry1> ...] >
6018 [APPEND] [APPEND_STRING]
6019 PROPERTY <name> [<value1> ...])
6020 Sets one property on zero or more objects of a scope.
6022 The first argument determines the scope in which the property is set.
6024 It must be one of the following:
6025 GLOBAL Scope is unique and does not accept a name.
6027 DIRECTORY
6029 Scope defaults to the current directory but other directories
6030 (already processed by CMake) may be named by full or relative
6031 path. Relative paths are treated as relative to the current
6032 source directory. See also the set_directory_properties() com‐
6033 mand.
6034 New in version 3.19: <dir> may reference a binary directory.
6036 TARGET Scope may name zero or more existing targets. See also the
6039 set_target_properties() command.
6040 SOURCE Scope may name zero or more source files. By default, source
6042 file properties are only visible to targets added in the same
6043 directory (CMakeLists.txt).
6044 New in version 3.18: Visibility can be set in other directory
6046 scopes using one or both of the following sub-options:
6047 DIRECTORY <dirs>...
6049 The source file property will be set in each of the
6050 <dirs> directories' scopes. CMake must already know
6051 about each of these directories, either by having added
6052 them through a call to add_subdirectory() or it being the
6053 top level source directory. Relative paths are treated
6054 as relative to the current source directory.
6055 New in version 3.19: <dirs> may reference a binary direc‐
6057 tory.
6058 TARGET_DIRECTORY <targets>...
6061 The source file property will be set in each of the di‐
6062 rectory scopes where any of the specified <targets> were
6063 created (the <targets> must therefore already exist).
6064 See also the set_source_files_properties() command.
6067 INSTALL
6069 New in version 3.1.
6070 Scope may name zero or more installed file paths. These are
6073 made available to CPack to influence deployment.
6074 Both the property key and value may use generator expressions.
6076 Specific properties may apply to installed files and/or directo‐
6077 ries.
6078 Path components have to be separated by forward slashes, must be
6080 normalized and are case sensitive.
6081 To reference the installation prefix itself with a relative path
6083 use ..
6084 Currently installed file properties are only defined for the WIX
6086 generator where the given paths are relative to the installation
6087 prefix.
6088 TEST Scope may name zero or more existing tests. See also the
6090 set_tests_properties() command.
6091 CACHE Scope must name zero or more cache existing entries.
6093 The required PROPERTY option is immediately followed by the name of the
6095 property to set. Remaining arguments are used to compose the property
6096 value in the form of a semicolon-separated list.
6097 If the APPEND option is given the list is appended to any existing
6099 property value (except that empty values are ignored and not appended).
6100 If the APPEND_STRING option is given the string is appended to any ex‐
6101 isting property value as string, i.e. it results in a longer string and
6102 not a list of strings. When using APPEND or APPEND_STRING with a prop‐
6103 erty defined to support INHERITED behavior (see define_property()), no
6104 inheriting occurs when finding the initial value to append to. If the
6105 property is not already directly set in the nominated scope, the com‐
6106 mand will behave as though APPEND or APPEND_STRING had not been given.
6107 See the cmake-properties(7) manual for a list of properties in each
6109 scope.
6110 NOTE:
6112 The GENERATED source file property may be globally visible. See its
6113 documentation for details.
6114 site_name
6116 Set the given variable to the name of the computer.
6117 site_name(variable)
6119 On UNIX-like platforms, if the variable HOSTNAME is set, its value will
6121 be executed as a command expected to print out the host name, much like
6122 the hostname command-line tool.
6123 string
6125 String operations.
6126 Synopsis
6128 Search and Replace
6129 string(FIND <string> <substring> <out-var> [...])
6130 string(REPLACE <match-string> <replace-string> <out-var> <input>...)
6131 string(REGEX MATCH <match-regex> <out-var> <input>...)
6132 string(REGEX MATCHALL <match-regex> <out-var> <input>...)
6133 string(REGEX REPLACE <match-regex> <replace-expr> <out-var> <input>...)
6134 Manipulation
6136 string(APPEND <string-var> [<input>...])
6137 string(PREPEND <string-var> [<input>...])
6138 string(CONCAT <out-var> [<input>...])
6139 string(JOIN <glue> <out-var> [<input>...])
6140 string(TOLOWER <string> <out-var>)
6141 string(TOUPPER <string> <out-var>)
6142 string(LENGTH <string> <out-var>)
6143 string(SUBSTRING <string> <begin> <length> <out-var>)
6144 string(STRIP <string> <out-var>)
6145 string(GENEX_STRIP <string> <out-var>)
6146 string(REPEAT <string> <count> <out-var>)
6147 Comparison
6149 string(COMPARE <op> <string1> <string2> <out-var>)
6150 Hashing
6152 string(<HASH> <out-var> <input>)
6153 Generation
6155 string(ASCII <number>... <out-var>)
6156 string(HEX <string> <out-var>)
6157 string(CONFIGURE <string> <out-var> [...])
6158 string(MAKE_C_IDENTIFIER <string> <out-var>)
6159 string(RANDOM [<option>...] <out-var>)
6160 string(TIMESTAMP <out-var> [<format string>] [UTC])
6161 string(UUID <out-var> ...)
6162 JSON
6164 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
6165 {GET | TYPE | LENGTH | REMOVE}
6166 <json-string> <member|index> [<member|index> ...])
6167 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
6168 MEMBER <json-string>
6169 [<member|index> ...] <index>)
6170 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
6171 SET <json-string>
6172 <member|index> [<member|index> ...] <value>)
6173 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
6174 EQUAL <json-string1> <json-string2>)
6175 Search and Replace
6177 Search and Replace With Plain Strings
6178 string(FIND <string> <substring> <output_variable> [REVERSE])
6179 Return the position where the given <substring> was found in the sup‐
6181 plied <string>. If the REVERSE flag was used, the command will search
6182 for the position of the last occurrence of the specified <substring>.
6183 If the <substring> is not found, a position of -1 is returned.
6184 The string(FIND) subcommand treats all strings as ASCII-only charac‐
6186 ters. The index stored in <output_variable> will also be counted in
6187 bytes, so strings containing multi-byte characters may lead to unex‐
6188 pected results.
6189 string(REPLACE <match_string>
6191 <replace_string> <output_variable>
6192 <input> [<input>...])
6193 Replace all occurrences of <match_string> in the <input> with <re‐
6195 place_string> and store the result in the <output_variable>.
6196 Search and Replace With Regular Expressions
6198 string(REGEX MATCH <regular_expression>
6199 <output_variable> <input> [<input>...])
6200 Match the <regular_expression> once and store the match in the <out‐
6202 put_variable>. All <input> arguments are concatenated before matching.
6203 Regular expressions are specified in the subsection just below.
6204 string(REGEX MATCHALL <regular_expression>
6206 <output_variable> <input> [<input>...])
6207 Match the <regular_expression> as many times as possible and store the
6209 matches in the <output_variable> as a list. All <input> arguments are
6210 concatenated before matching.
6211 string(REGEX REPLACE <regular_expression>
6213 <replacement_expression> <output_variable>
6214 <input> [<input>...])
6215 Match the <regular_expression> as many times as possible and substitute
6217 the <replacement_expression> for the match in the output. All <input>
6218 arguments are concatenated before matching.
6219 The <replacement_expression> may refer to parenthesis-delimited subex‐
6221 pressions of the match using \1, \2, ..., \9. Note that two back‐
6222 slashes (\\1) are required in CMake code to get a backslash through ar‐
6223 gument parsing.
6224 Regex Specification
6226 The following characters have special meaning in regular expressions:
6227 ^ Matches at beginning of input
6229 $ Matches at end of input
6231 . Matches any single character
6233 \<char>
6235 Matches the single character specified by <char>. Use this to
6236 match special regex characters, e.g. \. for a literal . or \\
6237 for a literal backslash \. Escaping a non-special character is
6238 unnecessary but allowed, e.g. \a matches a.
6239 [ ] Matches any character(s) inside the brackets
6241 [^ ] Matches any character(s) not inside the brackets
6243 - Inside brackets, specifies an inclusive range between characters
6245 on either side e.g. [a-f] is [abcdef] To match a literal - using
6246 brackets, make it the first or the last character e.g. [+*/-]
6247 matches basic mathematical operators.
6248 * Matches preceding pattern zero or more times
6250 + Matches preceding pattern one or more times
6252 ? Matches preceding pattern zero or once only
6254 | Matches a pattern on either side of the |
6256 () Saves a matched subexpression, which can be referenced in the
6258 REGEX REPLACE operation.
6259 New in version 3.9: All regular expression-related commands, in‐
6261 cluding e.g. if(MATCHES), save subgroup matches in the vari‐
6262 ables CMAKE_MATCH_<n> for <n> 0..9.
6263 *, + and ? have higher precedence than concatenation. | has lower
6266 precedence than concatenation. This means that the regular expression
6267 ^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
6268 matches ab but not abd.
6269 CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
6271 to construct literal tabs, carriage returns, newlines, and backslashes
6272 (respectively) to pass in a regex. For example:
6273 • The quoted argument "[ \t\r\n]" specifies a regex that matches any
6275 single whitespace character.
6276 • The quoted argument "[/\\]" specifies a regex that matches a single
6278 forward slash / or backslash \.
6279 • The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
6281 single "word" character in the C locale.
6282 • The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
6284 the exact string (a+b). Each \\ is parsed in a quoted argument as
6285 just \, so the regex itself is actually \(\a\+\b\). This can alter‐
6286 natively be specified in a bracket argument without having to escape
6287 the backslashes, e.g. [[\(\a\+\b\)]].
6288 Manipulation
6290 string(APPEND <string_variable> [<input>...])
6291 New in version 3.4.
6293 Append all the <input> arguments to the string.
6296 string(PREPEND <string_variable> [<input>...])
6298 New in version 3.10.
6300 Prepend all the <input> arguments to the string.
6303 string(CONCAT <output_variable> [<input>...])
6305 Concatenate all the <input> arguments together and store the result in
6307 the named <output_variable>.
6308 string(JOIN <glue> <output_variable> [<input>...])
6310 New in version 3.12.
6312 Join all the <input> arguments together using the <glue> string and
6315 store the result in the named <output_variable>.
6316 To join a list's elements, prefer to use the JOIN operator from the
6318 list() command. This allows for the elements to have special charac‐
6319 ters like ; in them.
6320 string(TOLOWER <string> <output_variable>)
6322 Convert <string> to lower characters.
6324 string(TOUPPER <string> <output_variable>)
6326 Convert <string> to upper characters.
6328 string(LENGTH <string> <output_variable>)
6330 Store in an <output_variable> a given string's length in bytes. Note
6332 that this means if <string> contains multi-byte characters, the result
6333 stored in <output_variable> will not be the number of characters.
6334 string(SUBSTRING <string> <begin> <length> <output_variable>)
6336 Store in an <output_variable> a substring of a given <string>. If
6338 <length> is -1 the remainder of the string starting at <begin> will be
6339 returned.
6340 Changed in version 3.2: If <string> is shorter than <length> then the
6342 end of the string is used instead. Previous versions of CMake reported
6343 an error in this case.
6344 Both <begin> and <length> are counted in bytes, so care must be exer‐
6347 cised if <string> could contain multi-byte characters.
6348 string(STRIP <string> <output_variable>)
6350 Store in an <output_variable> a substring of a given <string> with
6352 leading and trailing spaces removed.
6353 string(GENEX_STRIP <string> <output_variable>)
6355 New in version 3.1.
6357 Strip any generator expressions from the input <string> and store the
6360 result in the <output_variable>.
6361 string(REPEAT <string> <count> <output_variable>)
6363 New in version 3.15.
6365 Produce the output string as the input <string> repeated <count> times.
6368 Comparison
6370 string(COMPARE LESS <string1> <string2> <output_variable>)
6371 string(COMPARE GREATER <string1> <string2> <output_variable>)
6372 string(COMPARE EQUAL <string1> <string2> <output_variable>)
6373 string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
6374 string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
6375 string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
6376 Compare the strings and store true or false in the <output_variable>.
6378 New in version 3.7: Added the LESS_EQUAL and GREATER_EQUAL options.
6380 Hashing
6383 string(<HASH> <output_variable> <input>)
6384 Compute a cryptographic hash of the <input> string. The supported
6386 <HASH> algorithm names are:
6387 MD5 Message-Digest Algorithm 5, RFC 1321.
6389 SHA1 US Secure Hash Algorithm 1, RFC 3174.
6391 SHA224 US Secure Hash Algorithms, RFC 4634.
6393 SHA256 US Secure Hash Algorithms, RFC 4634.
6395 SHA384 US Secure Hash Algorithms, RFC 4634.
6397 SHA512 US Secure Hash Algorithms, RFC 4634.
6399 SHA3_224
6401 Keccak SHA-3.
6402 SHA3_256
6404 Keccak SHA-3.
6405 SHA3_384
6407 Keccak SHA-3.
6408 SHA3_512
6410 Keccak SHA-3.
6411 New in version 3.8: Added the SHA3_* hash algorithms.
6413 Generation
6416 string(ASCII <number> [<number> ...] <output_variable>)
6417 Convert all numbers into corresponding ASCII characters.
6419 string(HEX <string> <output_variable>)
6421 New in version 3.18.
6423 Convert each byte in the input <string> to its hexadecimal representa‐
6426 tion and store the concatenated hex digits in the <output_variable>.
6427 Letters in the output (a through f) are in lowercase.
6428 string(CONFIGURE <string> <output_variable>
6430 [@ONLY] [ESCAPE_QUOTES])
6431 Transform a <string> like configure_file() transforms a file.
6433 string(MAKE_C_IDENTIFIER <string> <output_variable>)
6435 Convert each non-alphanumeric character in the input <string> to an un‐
6437 derscore and store the result in the <output_variable>. If the first
6438 character of the <string> is a digit, an underscore will also be
6439 prepended to the result.
6440 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
6442 [RANDOM_SEED <seed>] <output_variable>)
6443 Return a random string of given <length> consisting of characters from
6445 the given <alphabet>. Default length is 5 characters and default al‐
6446 phabet is all numbers and upper and lower case letters. If an integer
6447 RANDOM_SEED is given, its value will be used to seed the random number
6448 generator.
6449 string(TIMESTAMP <output_variable> [<format_string>] [UTC])
6451 Write a string representation of the current date and/or time to the
6453 <output_variable>.
6454 If the command is unable to obtain a timestamp, the <output_variable>
6456 will be set to the empty string "".
6457 The optional UTC flag requests the current date/time representation to
6459 be in Coordinated Universal Time (UTC) rather than local time.
6460 The optional <format_string> may contain the following format speci‐
6462 fiers:
6463 %% New in version 3.8.
6465 A literal percent sign (%).
6468 %d The day of the current month (01-31).
6470 %H The hour on a 24-hour clock (00-23).
6472 %I The hour on a 12-hour clock (01-12).
6474 %j The day of the current year (001-366).
6476 %m The month of the current year (01-12).
6478 %b New in version 3.7.
6480 Abbreviated month name (e.g. Oct).
6483 %B New in version 3.10.
6485 Full month name (e.g. October).
6488 %M The minute of the current hour (00-59).
6490 %s New in version 3.6.
6492 Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
6495 %S The second of the current minute. 60 represents a leap second.
6497 (00-60)
6498 %U The week number of the current year (00-53).
6500 %V New in version 3.22.
6502 The ISO 8601 week number of the current year (01-53).
6505 %w The day of the current week. 0 is Sunday. (0-6)
6507 %a New in version 3.7.
6509 Abbreviated weekday name (e.g. Fri).
6512 %A New in version 3.10.
6514 Full weekday name (e.g. Friday).
6517 %y The last two digits of the current year (00-99).
6519 %Y The current year.
6521 Unknown format specifiers will be ignored and copied to the output
6523 as-is.
6524 If no explicit <format_string> is given, it will default to:
6526 %Y-%m-%dT%H:%M:%S for local time.
6528 %Y-%m-%dT%H:%M:%SZ for UTC.
6529 New in version 3.8: If the SOURCE_DATE_EPOCH environment variable is
6531 set, its value will be used instead of the current time. See
6532 https://reproducible-builds.org/specs/source-date-epoch/ for details.
6533 string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
6536 TYPE <MD5|SHA1> [UPPER])
6537 New in version 3.1.
6539 Create a universally unique identifier (aka GUID) as per RFC4122 based
6542 on the hash of the combined values of <namespace> (which itself has to
6543 be a valid UUID) and <name>. The hash algorithm can be either MD5
6544 (Version 3 UUID) or SHA1 (Version 5 UUID). A UUID has the format
6545 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where each x represents a lower
6546 case hexadecimal character. Where required, an uppercase representa‐
6547 tion can be requested with the optional UPPER flag.
6548 JSON
6550 New in version 3.19.
6551 Functionality for querying a JSON string.
6554 NOTE:
6556 In each of the following JSON-related subcommands, if the optional
6557 ERROR_VARIABLE argument is given, errors will be reported in <er‐
6558 ror-variable> and the <out-var> will be set to <member|index>-[<mem‐
6559 ber|index>...]-NOTFOUND with the path elements up to the point where
6560 the error occurred, or just NOTFOUND if there is no relevant path.
6561 If an error occurs but the ERROR_VARIABLE option is not present, a
6562 fatal error message is generated. If no error occurs, the <er‐
6563 ror-variable> will be set to NOTFOUND.
6564 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
6566 GET <json-string> <member|index> [<member|index> ...])
6567 Get an element from <json-string> at the location given by the list of
6569 <member|index> arguments. Array and object elements will be returned
6570 as a JSON string. Boolean elements will be returned as ON or OFF.
6571 Null elements will be returned as an empty string. Number and string
6572 types will be returned as strings.
6573 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
6575 TYPE <json-string> <member|index> [<member|index> ...])
6576 Get the type of an element in <json-string> at the location given by
6578 the list of <member|index> arguments. The <out-var> will be set to one
6579 of NULL, NUMBER, STRING, BOOLEAN, ARRAY, or OBJECT.
6580 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
6582 MEMBER <json-string>
6583 [<member|index> ...] <index>)
6584 Get the name of the <index>-th member in <json-string> at the location
6586 given by the list of <member|index> arguments. Requires an element of
6587 object type.
6588 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
6590 LENGTH <json-string> <member|index> [<member|index> ...])
6591 Get the length of an element in <json-string> at the location given by
6593 the list of <member|index> arguments. Requires an element of array or
6594 object type.
6595 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
6597 REMOVE <json-string> <member|index> [<member|index> ...])
6598 Remove an element from <json-string> at the location given by the list
6600 of <member|index> arguments. The JSON string without the removed ele‐
6601 ment will be stored in <out-var>.
6602 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
6604 SET <json-string> <member|index> [<member|index> ...] <value>)
6605 Set an element in <json-string> at the location given by the list of
6607 <member|index> arguments to <value>. The contents of <value> should be
6608 valid JSON.
6609 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
6611 EQUAL <json-string1> <json-string2>)
6612 Compare the two JSON objects given by <json-string1> and <json-string2>
6614 for equality. The contents of <json-string1> and <json-string2> should
6615 be valid JSON. The <out-var> will be set to a true value if the JSON
6616 objects are considered equal, or a false value otherwise.
6617 unset
6619 Unset a variable, cache variable, or environment variable.
6620 Unset Normal Variable or Cache Entry
6622 unset(<variable> [CACHE | PARENT_SCOPE])
6623 Removes a normal variable from the current scope, causing it to become
6625 undefined. If CACHE is present, then a cache variable is removed in‐
6626 stead of a normal variable. Note that when evaluating Variable Refer‐
6627 ences of the form ${VAR}, CMake first searches for a normal variable
6628 with that name. If no such normal variable exists, CMake will then
6629 search for a cache entry with that name. Because of this unsetting a
6630 normal variable can expose a cache variable that was previously hidden.
6631 To force a variable reference of the form ${VAR} to return an empty
6632 string, use set(<variable> ""), which clears the normal variable but
6633 leaves it defined.
6634 If PARENT_SCOPE is present then the variable is removed from the scope
6636 above the current scope. See the same option in the set() command for
6637 further details.
6638 Unset Environment Variable
6640 unset(ENV{<variable>})
6641 Removes <variable> from the currently available Environment Variables.
6643 Subsequent calls of $ENV{<variable>} will return the empty string.
6644 This command affects only the current CMake process, not the process
6646 from which CMake was called, nor the system environment at large, nor
6647 the environment of subsequent build or test processes.
6648 variable_watch
6650 Watch the CMake variable for change.
6651 variable_watch(<variable> [<command>])
6653 If the specified <variable> changes and no <command> is given, a mes‐
6655 sage will be printed to inform about the change.
6656 If <command> is given, this command will be executed instead. The com‐
6658 mand will receive the following arguments: COMMAND(<variable> <access>
6659 <value> <current_list_file> <stack>)
6660 <variable>
6662 Name of the variable being accessed.
6663 <access>
6665 One of READ_ACCESS, UNKNOWN_READ_ACCESS, MODIFIED_ACCESS, UN‐
6666 KNOWN_MODIFIED_ACCESS, or REMOVED_ACCESS. The UNKNOWN_ values
6667 are only used when the variable has never been set. Once set,
6668 they are never used again during the same CMake run, even if the
6669 variable is later unset.
6670 <value>
6672 The value of the variable. On a modification, this is the new
6673 (modified) value of the variable. On removal, the value is
6674 empty.
6675 <current_list_file>
6677 Full path to the file doing the access.
6678 <stack>
6680 List of absolute paths of all files currently on the stack of
6681 file inclusion, with the bottom-most file first and the cur‐
6682 rently processed file (that is, current_list_file) last.
6683 Note that for some accesses such as list(APPEND), the watcher is exe‐
6685 cuted twice, first with a read access and then with a write one. Also
6686 note that an if(DEFINED) query on the variable does not register as an
6687 access and the watcher is not executed.
6688 Only non-cache variables can be watched using this command. Access to
6690 cache variables is never watched. However, the existence of a cache
6691 variable var causes accesses to the non-cache variable var to not use
6692 the UNKNOWN_ prefix, even if a non-cache variable var has never ex‐
6693 isted.
6694 while
6696 Evaluate a group of commands while a condition is true
6697 while(<condition>)
6699 <commands>
6700 endwhile()
6701 All commands between while and the matching endwhile() are recorded
6703 without being invoked. Once the endwhile() is evaluated, the recorded
6704 list of commands is invoked as long as the <condition> is true.
6705 The <condition> has the same syntax and is evaluated using the same
6707 logic as described at length for the if() command.
6708 The commands break() and continue() provide means to escape from the
6710 normal control flow.
6711 Per legacy, the endwhile() command admits an optional <condition> argu‐
6713 ment. If used, it must be a verbatim repeat of the argument of the
6714 opening while command.
6715
6717 These commands are available only in CMake projects.
6718 add_compile_definitions
6720 New in version 3.12.
6721 Add preprocessor definitions to the compilation of source files.
6724 add_compile_definitions(<definition> ...)
6726 Adds preprocessor definitions to the compiler command line.
6728 The preprocessor definitions are added to the COMPILE_DEFINITIONS di‐
6730 rectory property for the current CMakeLists file. They are also added
6731 to the COMPILE_DEFINITIONS target property for each target in the cur‐
6732 rent CMakeLists file.
6733 Definitions are specified using the syntax VAR or VAR=value. Func‐
6735 tion-style definitions are not supported. CMake will automatically es‐
6736 cape the value correctly for the native build system (note that CMake
6737 language syntax may require escapes to specify some values).
6738 Arguments to add_compile_definitions may use "generator expressions"
6740 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6741 for available expressions. See the cmake-buildsystem(7) manual for
6742 more on defining buildsystem properties.
6743 add_compile_options
6745 Add options to the compilation of source files.
6746 add_compile_options(<option> ...)
6748 Adds options to the COMPILE_OPTIONS directory property. These options
6750 are used when compiling targets from the current directory and below.
6751 Arguments
6753 Arguments to add_compile_options may use "generator expressions" with
6754 the syntax $<...>. See the cmake-generator-expressions(7) manual for
6755 available expressions. See the cmake-buildsystem(7) manual for more on
6756 defining buildsystem properties.
6757 Option De-duplication
6759 The final set of options used for a target is constructed by accumulat‐
6760 ing options from the current target and the usage requirements of its
6761 dependencies. The set of options is de-duplicated to avoid repetition.
6762 New in version 3.12: While beneficial for individual options, the
6764 de-duplication step can break up option groups. For example, -option A
6765 -option B becomes -option A B. One may specify a group of options us‐
6766 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
6767 is dropped, and the rest of the option string is parsed using the sepa‐
6768 rate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
6769 "SHELL:-option B" becomes -option A -option B.
6770 Example
6773 Since different compilers support different options, a typical use of
6774 this command is in a compiler-specific conditional clause:
6775 if (MSVC)
6777 # warning level 4 and all warnings as errors
6778 add_compile_options(/W4 /WX)
6779 else()
6780 # lots of warnings and all warnings as errors
6781 add_compile_options(-Wall -Wextra -pedantic -Werror)
6782 endif()
6783 See Also
6785 This command can be used to add any options. However, for adding pre‐
6786 processor definitions and include directories it is recommended to use
6787 the more specific commands add_compile_definitions() and include_direc‐
6788 tories().
6789 The command target_compile_options() adds target-specific options.
6791 The source file property COMPILE_OPTIONS adds options to one source
6793 file.
6794 add_custom_command
6796 Add a custom build rule to the generated build system.
6797 There are two main signatures for add_custom_command.
6799 Generating Files
6801 The first signature is for adding a custom command to produce an out‐
6802 put:
6803 add_custom_command(OUTPUT output1 [output2 ...]
6805 COMMAND command1 [ARGS] [args1...]
6806 [COMMAND command2 [ARGS] [args2...] ...]
6807 [MAIN_DEPENDENCY depend]
6808 [DEPENDS [depends...]]
6809 [BYPRODUCTS [files...]]
6810 [IMPLICIT_DEPENDS <lang1> depend1
6811 [<lang2> depend2] ...]
6812 [WORKING_DIRECTORY dir]
6813 [COMMENT comment]
6814 [DEPFILE depfile]
6815 [JOB_POOL job_pool]
6816 [VERBATIM] [APPEND] [USES_TERMINAL]
6817 [COMMAND_EXPAND_LISTS])
6818 This defines a command to generate specified OUTPUT file(s). A target
6820 created in the same directory (CMakeLists.txt file) that specifies any
6821 output of the custom command as a source file is given a rule to gener‐
6822 ate the file using the command at build time. Do not list the output
6823 in more than one independent target that may build in parallel or the
6824 two instances of the rule may conflict (instead use the add_custom_tar‐
6825 get() command to drive the command and make the other targets depend on
6826 that one). In makefile terms this creates a new target in the follow‐
6827 ing form:
6828 OUTPUT: MAIN_DEPENDENCY DEPENDS
6830 COMMAND
6831 The options are:
6833 APPEND Append the COMMAND and DEPENDS option values to the custom com‐
6835 mand for the first output specified. There must have already
6836 been a previous call to this command with the same output.
6837 If the previous call specified the output via a generator ex‐
6839 pression, the output specified by the current call must match in
6840 at least one configuration after evaluating generator expres‐
6841 sions. In this case, the appended commands and dependencies ap‐
6842 ply to all configurations.
6843 The COMMENT, MAIN_DEPENDENCY, and WORKING_DIRECTORY options are
6845 currently ignored when APPEND is given, but may be used in the
6846 future.
6847 BYPRODUCTS
6849 New in version 3.2.
6850 Specify the files the command is expected to produce but whose
6853 modification time may or may not be newer than the dependencies.
6854 If a byproduct name is a relative path it will be interpreted
6855 relative to the build tree directory corresponding to the cur‐
6856 rent source directory. Each byproduct file will be marked with
6857 the GENERATED source file property automatically.
6858 Explicit specification of byproducts is supported by the Ninja
6860 generator to tell the ninja build tool how to regenerate byprod‐
6861 ucts when they are missing. It is also useful when other build
6862 rules (e.g. custom commands) depend on the byproducts. Ninja
6863 requires a build rule for any generated file on which another
6864 rule depends even if there are order-only dependencies to ensure
6865 the byproducts will be available before their dependents build.
6866 The Makefile Generators will remove BYPRODUCTS and other GENER‐
6868 ATED files during make clean.
6869 New in version 3.20: Arguments to BYPRODUCTS may use a re‐
6871 stricted set of generator expressions. Target-dependent expres‐
6872 sions are not permitted.
6873 COMMAND
6876 Specify the command-line(s) to execute at build time. If more
6877 than one COMMAND is specified they will be executed in order,
6878 but not necessarily composed into a stateful shell or batch
6879 script. (To run a full script, use the configure_file() command
6880 or the file(GENERATE) command to create it, and then specify a
6881 COMMAND to launch it.) The optional ARGS argument is for back‐
6882 ward compatibility and will be ignored.
6883 If COMMAND specifies an executable target name (created by the
6885 add_executable() command), it will automatically be replaced by
6886 the location of the executable created at build time if either
6887 of the following is true:
6888 • The target is not being cross-compiled (i.e. the CMAKE_CROSS‐
6890 COMPILING variable is not set to true).
6891 • New in version 3.6: The target is being cross-compiled and an
6893 emulator is provided (i.e. its CROSSCOMPILING_EMULATOR target
6894 property is set). In this case, the contents of CROSSCOMPIL‐
6895 ING_EMULATOR will be prepended to the command before the loca‐
6896 tion of the target executable.
6897 If neither of the above conditions are met, it is assumed that
6900 the command name is a program to be found on the PATH at build
6901 time.
6902 Arguments to COMMAND may use generator expressions. Use the
6904 TARGET_FILE generator expression to refer to the location of a
6905 target later in the command line (i.e. as a command argument
6906 rather than as the command to execute).
6907 Whenever one of the following target based generator expressions
6909 are used as a command to execute or is mentioned in a command
6910 argument, a target-level dependency will be added automatically
6911 so that the mentioned target will be built before any target us‐
6912 ing this custom command (see policy CMP0112).
6913 • TARGET_FILE
6915 • TARGET_LINKER_FILE
6917 • TARGET_SONAME_FILE
6919 • TARGET_PDB_FILE
6921 This target-level dependency does NOT add a file-level depen‐
6923 dency that would cause the custom command to re-run whenever the
6924 executable is recompiled. List target names with the DEPENDS
6925 option to add such file-level dependencies.
6926 COMMENT
6928 Display the given message before the commands are executed at
6929 build time.
6930 DEPENDS
6932 Specify files on which the command depends. Each argument is
6933 converted to a dependency as follows:
6934 1. If the argument is the name of a target (created by the
6936 add_custom_target(), add_executable(), or add_library() com‐
6937 mand) a target-level dependency is created to make sure the
6938 target is built before any target using this custom command.
6939 Additionally, if the target is an executable or library, a
6940 file-level dependency is created to cause the custom command
6941 to re-run whenever the target is recompiled.
6942 2. If the argument is an absolute path, a file-level dependency
6944 is created on that path.
6945 3. If the argument is the name of a source file that has been
6947 added to a target or on which a source file property has been
6948 set, a file-level dependency is created on that source file.
6949 4. If the argument is a relative path and it exists in the cur‐
6951 rent source directory, a file-level dependency is created on
6952 that file in the current source directory.
6953 5. Otherwise, a file-level dependency is created on that path
6955 relative to the current binary directory.
6956 If any dependency is an OUTPUT of another custom command in the
6958 same directory (CMakeLists.txt file), CMake automatically brings
6959 the other custom command into the target in which this command
6960 is built.
6961 New in version 3.16: A target-level dependency is added if any
6963 dependency is listed as BYPRODUCTS of a target or any of its
6964 build events in the same directory to ensure the byproducts will
6965 be available.
6966 If DEPENDS is not specified, the command will run whenever the
6969 OUTPUT is missing; if the command does not actually create the
6970 OUTPUT, the rule will always run.
6971 New in version 3.1: Arguments to DEPENDS may use generator ex‐
6973 pressions.
6974 COMMAND_EXPAND_LISTS
6977 New in version 3.8.
6978 Lists in COMMAND arguments will be expanded, including those
6981 created with generator expressions, allowing COMMAND arguments
6982 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
6983 RIES>,;-I>" foo.cc to be properly expanded.
6984 IMPLICIT_DEPENDS
6986 Request scanning of implicit dependencies of an input file. The
6987 language given specifies the programming language whose corre‐
6988 sponding dependency scanner should be used. Currently only C
6989 and CXX language scanners are supported. The language has to be
6990 specified for every file in the IMPLICIT_DEPENDS list. Depen‐
6991 dencies discovered from the scanning are added to those of the
6992 custom command at build time. Note that the IMPLICIT_DEPENDS
6993 option is currently supported only for Makefile generators and
6994 will be ignored by other generators.
6995 NOTE:
6997 This option cannot be specified at the same time as DEPFILE
6998 option.
6999 JOB_POOL
7001 New in version 3.15.
7002 Specify a pool for the Ninja generator. Incompatible with
7005 USES_TERMINAL, which implies the console pool. Using a pool
7006 that is not defined by JOB_POOLS causes an error by ninja at
7007 build time.
7008 MAIN_DEPENDENCY
7010 Specify the primary input source file to the command. This is
7011 treated just like any value given to the DEPENDS option but also
7012 suggests to Visual Studio generators where to hang the custom
7013 command. Each source file may have at most one command specify‐
7014 ing it as its main dependency. A compile command (i.e. for a li‐
7015 brary or an executable) counts as an implicit main dependency
7016 which gets silently overwritten by a custom command specifica‐
7017 tion.
7018 OUTPUT Specify the output files the command is expected to produce. If
7020 an output name is a relative path it will be interpreted rela‐
7021 tive to the build tree directory corresponding to the current
7022 source directory. Each output file will be marked with the GEN‐
7023 ERATED source file property automatically. If the output of the
7024 custom command is not actually created as a file on disk it
7025 should be marked with the SYMBOLIC source file property.
7026 New in version 3.20: Arguments to OUTPUT may use a restricted
7028 set of generator expressions. Target-dependent expressions are
7029 not permitted.
7030 USES_TERMINAL
7033 New in version 3.2.
7034 The command will be given direct access to the terminal if pos‐
7037 sible. With the Ninja generator, this places the command in the
7038 console pool.
7039 VERBATIM
7041 All arguments to the commands will be escaped properly for the
7042 build tool so that the invoked command receives each argument
7043 unchanged. Note that one level of escapes is still used by the
7044 CMake language processor before add_custom_command even sees the
7045 arguments. Use of VERBATIM is recommended as it enables correct
7046 behavior. When VERBATIM is not given the behavior is platform
7047 specific because there is no protection of tool-specific special
7048 characters.
7049 WORKING_DIRECTORY
7051 Execute the command with the given current working directory.
7052 If it is a relative path it will be interpreted relative to the
7053 build tree directory corresponding to the current source direc‐
7054 tory.
7055 New in version 3.13: Arguments to WORKING_DIRECTORY may use gen‐
7057 erator expressions.
7058 DEPFILE
7061 New in version 3.7.
7062 Specify a .d depfile which holds dependencies for the custom
7065 command. It is usually emitted by the custom command itself.
7066 This keyword may only be used if the generator supports it, as
7067 detailed below.
7068 New in version 3.7: The Ninja generator supports DEPFILE since
7070 the keyword was first added.
7071 New in version 3.17: Added the Ninja Multi-Config generator,
7074 which included support for the DEPFILE keyword.
7075 New in version 3.20: Added support for Makefile Generators.
7078 NOTE:
7080 DEPFILE cannot be specified at the same time as the IM‐
7081 PLICIT_DEPENDS option for Makefile Generators.
7082 New in version 3.21: Added support for Visual Studio Generators
7085 with VS 2012 and above, and for the Xcode generator. Support
7086 for generator expressions was also added.
7087 Using DEPFILE with generators other than those listed above is
7090 an error.
7091 If the DEPFILE argument is relative, it should be relative to
7093 CMAKE_CURRENT_BINARY_DIR, and any relative paths inside the DEP‐
7094 FILE should also be relative to CMAKE_CURRENT_BINARY_DIR. See
7095 policy CMP0116, which is always NEW for Makefile Generators,
7096 Visual Studio Generators, and the Xcode generator.
7097 Examples: Generating Files
7099 Custom commands may be used to generate source files. For example, the
7100 code:
7101 add_custom_command(
7103 OUTPUT out.c
7104 COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
7105 -o out.c
7106 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
7107 VERBATIM)
7108 add_library(myLib out.c)
7109 adds a custom command to run someTool to generate out.c and then com‐
7111 pile the generated source as part of a library. The generation rule
7112 will re-run whenever in.txt changes.
7113 New in version 3.20: One may use generator expressions to specify
7115 per-configuration outputs. For example, the code:
7116 add_custom_command(
7118 OUTPUT "out-$<CONFIG>.c"
7119 COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
7120 -o "out-$<CONFIG>.c"
7121 -c "$<CONFIG>"
7122 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
7123 VERBATIM)
7124 add_library(myLib "out-$<CONFIG>.c")
7125 adds a custom command to run someTool to generate out-<config>.c, where
7127 <config> is the build configuration, and then compile the generated
7128 source as part of a library.
7129 Build Events
7132 The second signature adds a custom command to a target such as a li‐
7133 brary or executable. This is useful for performing an operation before
7134 or after building the target. The command becomes part of the target
7135 and will only execute when the target itself is built. If the target
7136 is already built, the command will not execute.
7137 add_custom_command(TARGET <target>
7139 PRE_BUILD | PRE_LINK | POST_BUILD
7140 COMMAND command1 [ARGS] [args1...]
7141 [COMMAND command2 [ARGS] [args2...] ...]
7142 [BYPRODUCTS [files...]]
7143 [WORKING_DIRECTORY dir]
7144 [COMMENT comment]
7145 [VERBATIM] [USES_TERMINAL]
7146 [COMMAND_EXPAND_LISTS])
7147 This defines a new command that will be associated with building the
7149 specified <target>. The <target> must be defined in the current direc‐
7150 tory; targets defined in other directories may not be specified.
7151 When the command will happen is determined by which of the following is
7153 specified:
7154 PRE_BUILD
7156 On Visual Studio Generators, run before any other rules are exe‐
7157 cuted within the target. On other generators, run just before
7158 PRE_LINK commands.
7159 PRE_LINK
7161 Run after sources have been compiled but before linking the bi‐
7162 nary or running the librarian or archiver tool of a static li‐
7163 brary. This is not defined for targets created by the add_cus‐
7164 tom_target() command.
7165 POST_BUILD
7167 Run after all other rules within the target have been executed.
7168 NOTE:
7170 Because generator expressions can be used in custom commands, it is
7171 possible to define COMMAND lines or whole custom commands which
7172 evaluate to empty strings for certain configurations. For Visual
7173 Studio 2010 (and newer) generators these command lines or custom
7174 commands will be omitted for the specific configuration and no
7175 "empty-string-command" will be added.
7176 This allows to add individual build events for every configuration.
7178 New in version 3.21: Support for target-dependent generator expres‐
7180 sions.
7181 Examples: Build Events
7184 A POST_BUILD event may be used to post-process a binary after linking.
7185 For example, the code:
7186 add_executable(myExe myExe.c)
7188 add_custom_command(
7189 TARGET myExe POST_BUILD
7190 COMMAND someHasher -i "$<TARGET_FILE:myExe>"
7191 -o "$<TARGET_FILE:myExe>.hash"
7192 VERBATIM)
7193 will run someHasher to produce a .hash file next to the executable af‐
7195 ter linking.
7196 New in version 3.20: One may use generator expressions to specify
7198 per-configuration byproducts. For example, the code:
7199 add_library(myPlugin MODULE myPlugin.c)
7201 add_custom_command(
7202 TARGET myPlugin POST_BUILD
7203 COMMAND someHasher -i "$<TARGET_FILE:myPlugin>"
7204 --as-code "myPlugin-hash-$<CONFIG>.c"
7205 BYPRODUCTS "myPlugin-hash-$<CONFIG>.c"
7206 VERBATIM)
7207 add_executable(myExe myExe.c "myPlugin-hash-$<CONFIG>.c")
7208 will run someHasher after linking myPlugin, e.g. to produce a .c file
7210 containing code to check the hash of myPlugin that the myExe executable
7211 can use to verify it before loading.
7212 Ninja Multi-Config
7215 New in version 3.20: add_custom_command supports the Ninja Multi-Config
7216 generator's cross-config capabilities. See the generator documentation
7217 for more information.
7218 add_custom_target
7221 Add a target with no output so it will always be built.
7222 add_custom_target(Name [ALL] [command1 [args1...]]
7224 [COMMAND command2 [args2...] ...]
7225 [DEPENDS depend depend depend ... ]
7226 [BYPRODUCTS [files...]]
7227 [WORKING_DIRECTORY dir]
7228 [COMMENT comment]
7229 [JOB_POOL job_pool]
7230 [VERBATIM] [USES_TERMINAL]
7231 [COMMAND_EXPAND_LISTS]
7232 [SOURCES src1 [src2...]])
7233 Adds a target with the given name that executes the given commands.
7235 The target has no output file and is always considered out of date even
7236 if the commands try to create a file with the name of the target. Use
7237 the add_custom_command() command to generate a file with dependencies.
7238 By default nothing depends on the custom target. Use the add_dependen‐
7239 cies() command to add dependencies to or from other targets.
7240 The options are:
7242 ALL Indicate that this target should be added to the default build
7244 target so that it will be run every time (the command cannot be
7245 called ALL).
7246 BYPRODUCTS
7248 New in version 3.2.
7249 Specify the files the command is expected to produce but whose
7252 modification time may or may not be updated on subsequent
7253 builds. If a byproduct name is a relative path it will be in‐
7254 terpreted relative to the build tree directory corresponding to
7255 the current source directory. Each byproduct file will be
7256 marked with the GENERATED source file property automatically.
7257 Explicit specification of byproducts is supported by the Ninja
7259 generator to tell the ninja build tool how to regenerate byprod‐
7260 ucts when they are missing. It is also useful when other build
7261 rules (e.g. custom commands) depend on the byproducts. Ninja
7262 requires a build rule for any generated file on which another
7263 rule depends even if there are order-only dependencies to ensure
7264 the byproducts will be available before their dependents build.
7265 The Makefile Generators will remove BYPRODUCTS and other GENER‐
7267 ATED files during make clean.
7268 New in version 3.20: Arguments to BYPRODUCTS may use a re‐
7270 stricted set of generator expressions. Target-dependent expres‐
7271 sions are not permitted.
7272 COMMAND
7275 Specify the command-line(s) to execute at build time. If more
7276 than one COMMAND is specified they will be executed in order,
7277 but not necessarily composed into a stateful shell or batch
7278 script. (To run a full script, use the configure_file() command
7279 or the file(GENERATE) command to create it, and then specify a
7280 COMMAND to launch it.)
7281 If COMMAND specifies an executable target name (created by the
7283 add_executable() command), it will automatically be replaced by
7284 the location of the executable created at build time if either
7285 of the following is true:
7286 • The target is not being cross-compiled (i.e. the CMAKE_CROSS‐
7288 COMPILING variable is not set to true).
7289 • New in version 3.6: The target is being cross-compiled and an
7291 emulator is provided (i.e. its CROSSCOMPILING_EMULATOR target
7292 property is set). In this case, the contents of CROSSCOMPIL‐
7293 ING_EMULATOR will be prepended to the command before the loca‐
7294 tion of the target executable.
7295 If neither of the above conditions are met, it is assumed that
7298 the command name is a program to be found on the PATH at build
7299 time.
7300 Arguments to COMMAND may use generator expressions. Use the
7302 TARGET_FILE generator expression to refer to the location of a
7303 target later in the command line (i.e. as a command argument
7304 rather than as the command to execute).
7305 Whenever one of the following target based generator expressions
7307 are used as a command to execute or is mentioned in a command
7308 argument, a target-level dependency will be added automatically
7309 so that the mentioned target will be built before this custom
7310 target (see policy CMP0112).
7311 • TARGET_FILE
7313 • TARGET_LINKER_FILE
7315 • TARGET_SONAME_FILE
7317 • TARGET_PDB_FILE
7319 The command and arguments are optional and if not specified an
7321 empty target will be created.
7322 COMMENT
7324 Display the given message before the commands are executed at
7325 build time.
7326 DEPENDS
7328 Reference files and outputs of custom commands created with
7329 add_custom_command() command calls in the same directory (CMake‐
7330 Lists.txt file). They will be brought up to date when the tar‐
7331 get is built.
7332 Changed in version 3.16: A target-level dependency is added if
7334 any dependency is a byproduct of a target or any of its build
7335 events in the same directory to ensure the byproducts will be
7336 available before this target is built.
7337 Use the add_dependencies() command to add dependencies on other
7340 targets.
7341 COMMAND_EXPAND_LISTS
7343 New in version 3.8.
7344 Lists in COMMAND arguments will be expanded, including those
7347 created with generator expressions, allowing COMMAND arguments
7348 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
7349 RIES>,;-I>" foo.cc to be properly expanded.
7350 JOB_POOL
7352 New in version 3.15.
7353 Specify a pool for the Ninja generator. Incompatible with
7356 USES_TERMINAL, which implies the console pool. Using a pool
7357 that is not defined by JOB_POOLS causes an error by ninja at
7358 build time.
7359 SOURCES
7361 Specify additional source files to be included in the custom
7362 target. Specified source files will be added to IDE project
7363 files for convenience in editing even if they have no build
7364 rules.
7365 VERBATIM
7367 All arguments to the commands will be escaped properly for the
7368 build tool so that the invoked command receives each argument
7369 unchanged. Note that one level of escapes is still used by the
7370 CMake language processor before add_custom_target even sees the
7371 arguments. Use of VERBATIM is recommended as it enables correct
7372 behavior. When VERBATIM is not given the behavior is platform
7373 specific because there is no protection of tool-specific special
7374 characters.
7375 USES_TERMINAL
7377 New in version 3.2.
7378 The command will be given direct access to the terminal if pos‐
7381 sible. With the Ninja generator, this places the command in the
7382 console pool.
7383 WORKING_DIRECTORY
7385 Execute the command with the given current working directory.
7386 If it is a relative path it will be interpreted relative to the
7387 build tree directory corresponding to the current source direc‐
7388 tory.
7389 New in version 3.13: Arguments to WORKING_DIRECTORY may use gen‐
7391 erator expressions.
7392 Ninja Multi-Config
7395 New in version 3.20: add_custom_target supports the Ninja Multi-Config
7396 generator's cross-config capabilities. See the generator documentation
7397 for more information.
7398 add_definitions
7401 Add -D define flags to the compilation of source files.
7402 add_definitions(-DFOO -DBAR ...)
7404 Adds definitions to the compiler command line for targets in the cur‐
7406 rent directory, whether added before or after this command is invoked,
7407 and for the ones in sub-directories added after. This command can be
7408 used to add any flags, but it is intended to add preprocessor defini‐
7409 tions.
7410 NOTE:
7412 This command has been superseded by alternatives:
7413 • Use add_compile_definitions() to add preprocessor definitions.
7415 • Use include_directories() to add include directories.
7417 • Use add_compile_options() to add other options.
7419 Flags beginning in -D or /D that look like preprocessor definitions are
7421 automatically added to the COMPILE_DEFINITIONS directory property for
7422 the current directory. Definitions with non-trivial values may be left
7423 in the set of flags instead of being converted for reasons of backwards
7424 compatibility. See documentation of the directory, target, source file
7425 COMPILE_DEFINITIONS properties for details on adding preprocessor defi‐
7426 nitions to specific scopes and configurations.
7427 See the cmake-buildsystem(7) manual for more on defining buildsystem
7429 properties.
7430 add_dependencies
7432 Add a dependency between top-level targets.
7433 add_dependencies(<target> [<target-dependency>]...)
7435 Makes a top-level <target> depend on other top-level targets to ensure
7437 that they build before <target> does. A top-level target is one cre‐
7438 ated by one of the add_executable(), add_library(), or add_custom_tar‐
7439 get() commands (but not targets generated by CMake like install).
7440 Dependencies added to an imported target or an interface library are
7442 followed transitively in its place since the target itself does not
7443 build.
7444 New in version 3.3: Allow adding dependencies to interface libraries.
7446 See the DEPENDS option of add_custom_target() and add_custom_command()
7449 commands for adding file-level dependencies in custom rules. See the
7450 OBJECT_DEPENDS source file property to add file-level dependencies to
7451 object files.
7452 add_executable
7454 Add an executable to the project using the specified source files.
7455 Normal Executables
7457 add_executable(<name> [WIN32] [MACOSX_BUNDLE]
7458 [EXCLUDE_FROM_ALL]
7459 [source1] [source2 ...])
7460 Adds an executable target called <name> to be built from the source
7462 files listed in the command invocation. The <name> corresponds to the
7463 logical target name and must be globally unique within a project. The
7464 actual file name of the executable built is constructed based on con‐
7465 ventions of the native platform (such as <name>.exe or just <name>).
7466 New in version 3.1: Source arguments to add_executable may use "genera‐
7468 tor expressions" with the syntax $<...>. See the cmake-generator-ex‐
7469 pressions(7) manual for available expressions.
7470 New in version 3.11: The source files can be omitted if they are added
7473 later using target_sources().
7474 By default the executable file will be created in the build tree direc‐
7477 tory corresponding to the source tree directory in which the command
7478 was invoked. See documentation of the RUNTIME_OUTPUT_DIRECTORY target
7479 property to change this location. See documentation of the OUTPUT_NAME
7480 target property to change the <name> part of the final file name.
7481 If WIN32 is given the property WIN32_EXECUTABLE will be set on the tar‐
7483 get created. See documentation of that target property for details.
7484 If MACOSX_BUNDLE is given the corresponding property will be set on the
7486 created target. See documentation of the MACOSX_BUNDLE target property
7487 for details.
7488 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
7490 the created target. See documentation of the EXCLUDE_FROM_ALL target
7491 property for details.
7492 See the cmake-buildsystem(7) manual for more on defining buildsystem
7494 properties.
7495 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
7497 cessed, and you want to have the original sources reachable from within
7498 IDE.
7499 Imported Executables
7501 add_executable(<name> IMPORTED [GLOBAL])
7502 An IMPORTED executable target references an executable file located
7504 outside the project. No rules are generated to build it, and the IM‐
7505 PORTED target property is True. The target name has scope in the di‐
7506 rectory in which it is created and below, but the GLOBAL option extends
7507 visibility. It may be referenced like any target built within the
7508 project. IMPORTED executables are useful for convenient reference from
7509 commands like add_custom_command(). Details about the imported exe‐
7510 cutable are specified by setting properties whose names begin in IM‐
7511 PORTED_. The most important such property is IMPORTED_LOCATION (and
7512 its per-configuration version IMPORTED_LOCATION_<CONFIG>) which speci‐
7513 fies the location of the main executable file on disk. See documenta‐
7514 tion of the IMPORTED_* properties for more information.
7515 Alias Executables
7517 add_executable(<name> ALIAS <target>)
7518 Creates an Alias Target, such that <name> can be used to refer to <tar‐
7520 get> in subsequent commands. The <name> does not appear in the gener‐
7521 ated buildsystem as a make target. The <target> may not be an ALIAS.
7522 New in version 3.11: An ALIAS can target a GLOBAL Imported Target
7524 New in version 3.18: An ALIAS can target a non-GLOBAL Imported Target.
7527 Such alias is scoped to the directory in which it is created and subdi‐
7528 rectories. The ALIAS_GLOBAL target property can be used to check if
7529 the alias is global or not.
7530 ALIAS targets can be used as targets to read properties from, executa‐
7533 bles for custom commands and custom targets. They can also be tested
7534 for existence with the regular if(TARGET) subcommand. The <name> may
7535 not be used to modify properties of <target>, that is, it may not be
7536 used as the operand of set_property(), set_target_properties(), tar‐
7537 get_link_libraries() etc. An ALIAS target may not be installed or ex‐
7538 ported.
7539 add_library
7541 Add a library to the project using the specified source files.
7542 Normal Libraries
7544 add_library(<name> [STATIC | SHARED | MODULE]
7545 [EXCLUDE_FROM_ALL]
7546 [<source>...])
7547 Adds a library target called <name> to be built from the source files
7549 listed in the command invocation. The <name> corresponds to the logi‐
7550 cal target name and must be globally unique within a project. The ac‐
7551 tual file name of the library built is constructed based on conventions
7552 of the native platform (such as lib<name>.a or <name>.lib).
7553 New in version 3.1: Source arguments to add_library may use "generator
7555 expressions" with the syntax $<...>. See the cmake-generator-expres‐
7556 sions(7) manual for available expressions.
7557 New in version 3.11: The source files can be omitted if they are added
7560 later using target_sources().
7561 STATIC, SHARED, or MODULE may be given to specify the type of library
7564 to be created. STATIC libraries are archives of object files for use
7565 when linking other targets. SHARED libraries are linked dynamically
7566 and loaded at runtime. MODULE libraries are plugins that are not
7567 linked into other targets but may be loaded dynamically at runtime us‐
7568 ing dlopen-like functionality. If no type is given explicitly the type
7569 is STATIC or SHARED based on whether the current value of the variable
7570 BUILD_SHARED_LIBS is ON. For SHARED and MODULE libraries the POSI‐
7571 TION_INDEPENDENT_CODE target property is set to ON automatically. A
7572 SHARED library may be marked with the FRAMEWORK target property to cre‐
7573 ate an macOS Framework.
7574 New in version 3.8: A STATIC library may be marked with the FRAMEWORK
7576 target property to create a static Framework.
7577 If a library does not export any symbols, it must not be declared as a
7580 SHARED library. For example, a Windows resource DLL or a managed
7581 C++/CLI DLL that exports no unmanaged symbols would need to be a MODULE
7582 library. This is because CMake expects a SHARED library to always have
7583 an associated import library on Windows.
7584 By default the library file will be created in the build tree directory
7586 corresponding to the source tree directory in which the command was in‐
7587 voked. See documentation of the ARCHIVE_OUTPUT_DIRECTORY, LIBRARY_OUT‐
7588 PUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY target properties to change
7589 this location. See documentation of the OUTPUT_NAME target property to
7590 change the <name> part of the final file name.
7591 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
7593 the created target. See documentation of the EXCLUDE_FROM_ALL target
7594 property for details.
7595 See the cmake-buildsystem(7) manual for more on defining buildsystem
7597 properties.
7598 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
7600 cessed, and you want to have the original sources reachable from within
7601 IDE.
7602 Object Libraries
7604 add_library(<name> OBJECT [<source>...])
7605 Creates an Object Library. An object library compiles source files but
7607 does not archive or link their object files into a library. Instead
7608 other targets created by add_library() or add_executable() may refer‐
7609 ence the objects using an expression of the form $<TARGET_OBJECTS:ob‐
7610 jlib> as a source, where objlib is the object library name. For exam‐
7611 ple:
7612 add_library(... $<TARGET_OBJECTS:objlib> ...)
7614 add_executable(... $<TARGET_OBJECTS:objlib> ...)
7615 will include objlib's object files in a library and an executable along
7617 with those compiled from their own sources. Object libraries may con‐
7618 tain only sources that compile, header files, and other files that
7619 would not affect linking of a normal library (e.g. .txt). They may
7620 contain custom commands generating such sources, but not PRE_BUILD,
7621 PRE_LINK, or POST_BUILD commands. Some native build systems (such as
7622 Xcode) may not like targets that have only object files, so consider
7623 adding at least one real source file to any target that references
7624 $<TARGET_OBJECTS:objlib>.
7625 New in version 3.12: Object libraries can be linked to with tar‐
7627 get_link_libraries().
7628 Interface Libraries
7631 add_library(<name> INTERFACE)
7632 Creates an Interface Library. An INTERFACE library target does not
7634 compile sources and does not produce a library artifact on disk. How‐
7635 ever, it may have properties set on it and it may be installed and ex‐
7636 ported. Typically, INTERFACE_* properties are populated on an inter‐
7637 face target using the commands:
7638 • set_property(),
7640 • target_link_libraries(INTERFACE),
7642 • target_link_options(INTERFACE),
7644 • target_include_directories(INTERFACE),
7646 • target_compile_options(INTERFACE),
7648 • target_compile_definitions(INTERFACE), and
7650 • target_sources(INTERFACE),
7652 and then it is used as an argument to target_link_libraries() like any
7654 other target.
7655 An interface library created with the above signature has no source
7657 files itself and is not included as a target in the generated buildsys‐
7658 tem.
7659 New in version 3.15: An interface library can have PUBLIC_HEADER and
7661 PRIVATE_HEADER properties. The headers specified by those properties
7662 can be installed using the install(TARGETS) command.
7663 New in version 3.19: An interface library target may be created with
7666 source files:
7667 add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])
7669 Source files may be listed directly in the add_library call or added
7671 later by calls to target_sources() with the PRIVATE or PUBLIC keywords.
7672 If an interface library has source files (i.e. the SOURCES target prop‐
7674 erty is set), it will appear in the generated buildsystem as a build
7675 target much like a target defined by the add_custom_target() command.
7676 It does not compile any sources, but does contain build rules for cus‐
7677 tom commands created by the add_custom_command() command.
7678 NOTE:
7681 In most command signatures where the INTERFACE keyword appears, the
7682 items listed after it only become part of that target's usage re‐
7683 quirements and are not part of the target's own settings. However,
7684 in this signature of add_library, the INTERFACE keyword refers to
7685 the library type only. Sources listed after it in the add_library
7686 call are PRIVATE to the interface library and do not appear in its
7687 INTERFACE_SOURCES target property.
7688 Imported Libraries
7690 add_library(<name> <type> IMPORTED [GLOBAL])
7691 Creates an IMPORTED library target called <name>. No rules are gener‐
7693 ated to build it, and the IMPORTED target property is True. The target
7694 name has scope in the directory in which it is created and below, but
7695 the GLOBAL option extends visibility. It may be referenced like any
7696 target built within the project. IMPORTED libraries are useful for
7697 convenient reference from commands like target_link_libraries(). De‐
7698 tails about the imported library are specified by setting properties
7699 whose names begin in IMPORTED_ and INTERFACE_.
7700 The <type> must be one of:
7702 STATIC, SHARED, MODULE, UNKNOWN
7704 References a library file located outside the project. The IM‐
7705 PORTED_LOCATION target property (or its per-configuration vari‐
7706 ant IMPORTED_LOCATION_<CONFIG>) specifies the location of the
7707 main library file on disk:
7708 • For a SHARED library on most non-Windows platforms, the main
7710 library file is the .so or .dylib file used by both linkers
7711 and dynamic loaders. If the referenced library file has a
7712 SONAME (or on macOS, has a LC_ID_DYLIB starting in @rpath/),
7713 the value of that field should be set in the IMPORTED_SONAME
7714 target property. If the referenced library file does not have
7715 a SONAME, but the platform supports it, then the IM‐
7716 PORTED_NO_SONAME target property should be set.
7717 • For a SHARED library on Windows, the IMPORTED_IMPLIB target
7719 property (or its per-configuration variant IMPORTED_IM‐
7720 PLIB_<CONFIG>) specifies the location of the DLL import li‐
7721 brary file (.lib or .dll.a) on disk, and the IMPORTED_LOCATION
7722 is the location of the .dll runtime library (and is optional,
7723 but needed by the TARGET_RUNTIME_DLLS generator expression).
7724 Additional usage requirements may be specified in INTERFACE_*
7726 properties.
7727 An UNKNOWN library type is typically only used in the implemen‐
7729 tation of Find Modules. It allows the path to an imported li‐
7730 brary (often found using the find_library() command) to be used
7731 without having to know what type of library it is. This is es‐
7732 pecially useful on Windows where a static library and a DLL's
7733 import library both have the same file extension.
7734 OBJECT References a set of object files located outside the project.
7736 The IMPORTED_OBJECTS target property (or its per-configuration
7737 variant IMPORTED_OBJECTS_<CONFIG>) specifies the locations of
7738 object files on disk. Additional usage requirements may be
7739 specified in INTERFACE_* properties.
7740 INTERFACE
7742 Does not reference any library or object files on disk, but may
7743 specify usage requirements in INTERFACE_* properties.
7744 See documentation of the IMPORTED_* and INTERFACE_* properties for more
7746 information.
7747 Alias Libraries
7749 add_library(<name> ALIAS <target>)
7750 Creates an Alias Target, such that <name> can be used to refer to <tar‐
7752 get> in subsequent commands. The <name> does not appear in the gener‐
7753 ated buildsystem as a make target. The <target> may not be an ALIAS.
7754 New in version 3.11: An ALIAS can target a GLOBAL Imported Target
7756 New in version 3.18: An ALIAS can target a non-GLOBAL Imported Target.
7759 Such alias is scoped to the directory in which it is created and below.
7760 The ALIAS_GLOBAL target property can be used to check if the alias is
7761 global or not.
7762 ALIAS targets can be used as linkable targets and as targets to read
7765 properties from. They can also be tested for existence with the regu‐
7766 lar if(TARGET) subcommand. The <name> may not be used to modify prop‐
7767 erties of <target>, that is, it may not be used as the operand of
7768 set_property(), set_target_properties(), target_link_libraries() etc.
7769 An ALIAS target may not be installed or exported.
7770 add_link_options
7772 New in version 3.13.
7773 Add options to the link step for executable, shared library or module
7776 library targets in the current directory and below that are added after
7777 this command is invoked.
7778 add_link_options(<option> ...)
7780 This command can be used to add any link options, but alternative com‐
7782 mands exist to add libraries (target_link_libraries() or link_li‐
7783 braries()). See documentation of the directory and target LINK_OPTIONS
7784 properties.
7785 NOTE:
7787 This command cannot be used to add options for static library tar‐
7788 gets, since they do not use a linker. To add archiver or MSVC li‐
7789 brarian flags, see the STATIC_LIBRARY_OPTIONS target property.
7790 Arguments to add_link_options may use "generator expressions" with the
7792 syntax $<...>. See the cmake-generator-expressions(7) manual for
7793 available expressions. See the cmake-buildsystem(7) manual for more on
7794 defining buildsystem properties.
7795 Host And Device Specific Link Options
7797 New in version 3.18: When a device link step is involved, which is con‐
7798 trolled by CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS
7799 properties and policy CMP0105, the raw options will be delivered to the
7800 host and device link steps (wrapped in -Xcompiler or equivalent for de‐
7801 vice link). Options wrapped with $<DEVICE_LINK:...> generator expres‐
7802 sion will be used only for the device link step. Options wrapped with
7803 $<HOST_LINK:...> generator expression will be used only for the host
7804 link step.
7805 Option De-duplication
7808 The final set of options used for a target is constructed by accumulat‐
7809 ing options from the current target and the usage requirements of its
7810 dependencies. The set of options is de-duplicated to avoid repetition.
7811 New in version 3.12: While beneficial for individual options, the
7813 de-duplication step can break up option groups. For example, -option A
7814 -option B becomes -option A B. One may specify a group of options us‐
7815 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
7816 is dropped, and the rest of the option string is parsed using the sepa‐
7817 rate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
7818 "SHELL:-option B" becomes -option A -option B.
7819 Handling Compiler Driver Differences
7822 To pass options to the linker tool, each compiler driver has its own
7823 syntax. The LINKER: prefix and , separator can be used to specify, in
7824 a portable way, options to pass to the linker tool. LINKER: is replaced
7825 by the appropriate driver option and , by the appropriate driver sepa‐
7826 rator. The driver prefix and driver separator are given by the values
7827 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAP‐
7828 PER_FLAG_SEP variables.
7829 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
7831 Clang and -Wl,-z,defs for GNU GCC.
7832 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
7834 sion.
7835 The LINKER: prefix supports, as an alternative syntax, specification of
7837 arguments using the SHELL: prefix and space as separator. The previous
7838 example then becomes "LINKER:SHELL:-z defs".
7839 NOTE:
7841 Specifying the SHELL: prefix anywhere other than at the beginning of
7842 the LINKER: prefix is not supported.
7843 add_subdirectory
7845 Add a subdirectory to the build.
7846 add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
7848 Adds a subdirectory to the build. The source_dir specifies the direc‐
7850 tory in which the source CMakeLists.txt and code files are located. If
7851 it is a relative path it will be evaluated with respect to the current
7852 directory (the typical usage), but it may also be an absolute path.
7853 The binary_dir specifies the directory in which to place the output
7854 files. If it is a relative path it will be evaluated with respect to
7855 the current output directory, but it may also be an absolute path. If
7856 binary_dir is not specified, the value of source_dir, before expanding
7857 any relative path, will be used (the typical usage). The CMake‐
7858 Lists.txt file in the specified source directory will be processed im‐
7859 mediately by CMake before processing in the current input file contin‐
7860 ues beyond this command.
7861 If the EXCLUDE_FROM_ALL argument is provided then targets in the subdi‐
7863 rectory will not be included in the ALL target of the parent directory
7864 by default, and will be excluded from IDE project files. Users must
7865 explicitly build targets in the subdirectory. This is meant for use
7866 when the subdirectory contains a separate part of the project that is
7867 useful but not necessary, such as a set of examples. Typically the
7868 subdirectory should contain its own project() command invocation so
7869 that a full build system will be generated in the subdirectory (such as
7870 a VS IDE solution file). Note that inter-target dependencies supersede
7871 this exclusion. If a target built by the parent project depends on a
7872 target in the subdirectory, the dependee target will be included in the
7873 parent project build system to satisfy the dependency.
7874 add_test
7876 Add a test to the project to be run by ctest(1).
7877 add_test(NAME <name> COMMAND <command> [<arg>...]
7879 [CONFIGURATIONS <config>...]
7880 [WORKING_DIRECTORY <dir>]
7881 [COMMAND_EXPAND_LISTS])
7882 Adds a test called <name>. The test name may contain arbitrary charac‐
7884 ters, expressed as a Quoted Argument or Bracket Argument if necessary.
7885 See policy CMP0110. The options are:
7886 COMMAND
7888 Specify the test command-line. If <command> specifies an exe‐
7889 cutable target (created by add_executable()) it will automati‐
7890 cally be replaced by the location of the executable created at
7891 build time.
7892 CONFIGURATIONS
7894 Restrict execution of the test only to the named configurations.
7895 WORKING_DIRECTORY
7897 Set the WORKING_DIRECTORY test property to specify the working
7898 directory in which to execute the test. If not specified the
7899 test will be run with the current working directory set to the
7900 build directory corresponding to the current source directory.
7901 COMMAND_EXPAND_LISTS
7903 New in version 3.16.
7904 Lists in COMMAND arguments will be expanded, including those
7907 created with generator expressions.
7908 The given test command is expected to exit with code 0 to pass and
7910 non-zero to fail, or vice-versa if the WILL_FAIL test property is set.
7911 Any output written to stdout or stderr will be captured by ctest(1) but
7912 does not affect the pass/fail status unless the PASS_REGULAR_EXPRES‐
7913 SION, FAIL_REGULAR_EXPRESSION or SKIP_REGULAR_EXPRESSION test property
7914 is used.
7915 New in version 3.16: Added SKIP_REGULAR_EXPRESSION property.
7917 The COMMAND and WORKING_DIRECTORY options may use "generator expres‐
7920 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
7921 manual for available expressions.
7922 Example usage:
7924 add_test(NAME mytest
7926 COMMAND testDriver --config $<CONFIG>
7927 --exe $<TARGET_FILE:myexe>)
7928 This creates a test mytest whose command runs a testDriver tool passing
7930 the configuration name and the full path to the executable file pro‐
7931 duced by target myexe.
7932 NOTE:
7934 CMake will generate tests only if the enable_testing() command has
7935 been invoked. The CTest module invokes the command automatically
7936 unless the BUILD_TESTING option is turned OFF.
7937 ----
7940 add_test(<name> <command> [<arg>...])
7944 Add a test called <name> with the given command-line. Unlike the above
7946 NAME signature no transformation is performed on the command-line to
7947 support target names or generator expressions.
7948 aux_source_directory
7950 Find all source files in a directory.
7951 aux_source_directory(<dir> <variable>)
7953 Collects the names of all the source files in the specified directory
7955 and stores the list in the <variable> provided. This command is in‐
7956 tended to be used by projects that use explicit template instantiation.
7957 Template instantiation files can be stored in a Templates subdirectory
7958 and collected automatically using this command to avoid manually list‐
7959 ing all instantiations.
7960 It is tempting to use this command to avoid writing the list of source
7962 files for a library or executable target. While this seems to work,
7963 there is no way for CMake to generate a build system that knows when a
7964 new source file has been added. Normally the generated build system
7965 knows when it needs to rerun CMake because the CMakeLists.txt file is
7966 modified to add a new source. When the source is just added to the di‐
7967 rectory without modifying this file, one would have to manually rerun
7968 CMake to generate a build system incorporating the new file.
7969 build_command
7971 Get a command line to build the current project. This is mainly in‐
7972 tended for internal use by the CTest module.
7973 build_command(<variable>
7975 [CONFIGURATION <config>]
7976 [PARALLEL_LEVEL <parallel>]
7977 [TARGET <target>]
7978 [PROJECT_NAME <projname>] # legacy, causes warning
7979 )
7980 Sets the given <variable> to a command-line string of the form:
7982 <cmake> --build . [--config <config>] [--parallel <parallel>] [--target <target>...] [-- -i]
7984 where <cmake> is the location of the cmake(1) command-line tool, and
7986 <config>, <parallel> and <target> are the values provided to the CON‐
7987 FIGURATION, PARALLEL_LEVEL and TARGET options, if any. The trailing --
7988 -i option is added for Makefile Generators if policy CMP0061 is not set
7989 to NEW.
7990 When invoked, this cmake --build command line will launch the underly‐
7992 ing build system tool.
7993 New in version 3.21: The PARALLEL_LEVEL argument can be used to set the
7995 --parallel flag.
7996 build_command(<cachevariable> <makecommand>)
7999 This second signature is deprecated, but still available for backwards
8001 compatibility. Use the first signature instead.
8002 It sets the given <cachevariable> to a command-line string as above but
8004 without the --target option. The <makecommand> is ignored but should
8005 be the full path to devenv, nmake, make or one of the end user build
8006 tools for legacy invocations.
8007 NOTE:
8009 In CMake versions prior to 3.0 this command returned a command line
8010 that directly invokes the native build tool for the current genera‐
8011 tor. Their implementation of the PROJECT_NAME option had no useful
8012 effects, so CMake now warns on use of the option.
8013 create_test_sourcelist
8015 Create a test driver and source list for building test programs.
8016 create_test_sourcelist(sourceListName driverName
8018 test1 test2 test3
8019 EXTRA_INCLUDE include.h
8020 FUNCTION function)
8021 A test driver is a program that links together many small tests into a
8023 single executable. This is useful when building static executables
8024 with large libraries to shrink the total required size. The list of
8025 source files needed to build the test driver will be in sourceListName.
8026 driverName is the name of the test driver program. The rest of the ar‐
8027 guments consist of a list of test source files, can be semicolon sepa‐
8028 rated. Each test source file should have a function in it that is the
8029 same name as the file with no extension (foo.cxx should have int
8030 foo(int, char*[]);) driverName will be able to call each of the tests
8031 by name on the command line. If EXTRA_INCLUDE is specified, then the
8032 next argument is included into the generated file. If FUNCTION is
8033 specified, then the next argument is taken as a function name that is
8034 passed a pointer to ac and av. This can be used to add extra command
8035 line processing to each test. The CMAKE_TESTDRIVER_BEFORE_TESTMAIN
8036 cmake variable can be set to have code that will be placed directly be‐
8037 fore calling the test main function. CMAKE_TESTDRIVER_AFTER_TESTMAIN
8038 can be set to have code that will be placed directly after the call to
8039 the test main function.
8040 define_property
8042 Define and document custom properties.
8043 define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
8045 TEST | VARIABLE | CACHED_VARIABLE>
8046 PROPERTY <name> [INHERITED]
8047 BRIEF_DOCS <brief-doc> [docs...]
8048 FULL_DOCS <full-doc> [docs...])
8049 Defines one property in a scope for use with the set_property() and
8051 get_property() commands. This is primarily useful to associate docu‐
8052 mentation with property names that may be retrieved with the get_prop‐
8053 erty() command. The first argument determines the kind of scope in
8054 which the property should be used. It must be one of the following:
8055 GLOBAL = associated with the global namespace
8057 DIRECTORY = associated with one directory
8058 TARGET = associated with one target
8059 SOURCE = associated with one source file
8060 TEST = associated with a test named with add_test
8061 VARIABLE = documents a CMake language variable
8062 CACHED_VARIABLE = documents a CMake cache variable
8063 Note that unlike set_property() and get_property() no actual scope
8065 needs to be given; only the kind of scope is important.
8066 The required PROPERTY option is immediately followed by the name of the
8068 property being defined.
8069 If the INHERITED option is given, then the get_property() command will
8071 chain up to the next higher scope when the requested property is not
8072 set in the scope given to the command.
8073 • DIRECTORY scope chains to its parent directory's scope, continuing
8075 the walk up parent directories until a directory has the property set
8076 or there are no more parents. If still not found at the top level
8077 directory, it chains to the GLOBAL scope.
8078 • TARGET, SOURCE and TEST properties chain to DIRECTORY scope, includ‐
8080 ing further chaining up the directories, etc. as needed.
8081 Note that this scope chaining behavior only applies to calls to
8083 get_property(), get_directory_property(), get_target_property(),
8084 get_source_file_property() and get_test_property(). There is no inher‐
8085 iting behavior when setting properties, so using APPEND or AP‐
8086 PEND_STRING with the set_property() command will not consider inherited
8087 values when working out the contents to append to.
8088 The BRIEF_DOCS and FULL_DOCS options are followed by strings to be as‐
8090 sociated with the property as its brief and full documentation. Corre‐
8091 sponding options to the get_property() command will retrieve the docu‐
8092 mentation.
8093 enable_language
8095 Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
8096 enable_language(<lang> [OPTIONAL] )
8098 Enables support for the named language in CMake. This is the same as
8100 the project() command but does not create any of the extra variables
8101 that are created by the project command. Example languages are CXX, C,
8102 CUDA, OBJC, OBJCXX, Fortran, HIP, ISPC, and ASM.
8103 New in version 3.8: Added CUDA support.
8105 New in version 3.16: Added OBJC and OBJCXX support.
8108 New in version 3.18: Added ISPC support.
8111 New in version 3.21: Added HIP support.
8114 If enabling ASM, enable it last so that CMake can check whether compil‐
8117 ers for other languages like C work for assembly too.
8118 This command must be called in file scope, not in a function call.
8120 Furthermore, it must be called in the highest directory common to all
8121 targets using the named language directly for compiling sources or in‐
8122 directly through link dependencies. It is simplest to enable all
8123 needed languages in the top-level directory of a project.
8124 The OPTIONAL keyword is a placeholder for future implementation and
8126 does not currently work. Instead you can use the CheckLanguage module
8127 to verify support before enabling.
8128 enable_testing
8130 Enable testing for current directory and below.
8131 enable_testing()
8133 Enables testing for this directory and below.
8135 This command should be in the source directory root because ctest ex‐
8137 pects to find a test file in the build directory root.
8138 This command is automatically invoked when the CTest module is in‐
8140 cluded, except if the BUILD_TESTING option is turned off.
8141 See also the add_test() command.
8143 export
8145 Export targets from the build tree for use by outside projects.
8146 export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
8148 Creates a file <filename> that may be included by outside projects to
8150 import targets from the current project's build tree. This is useful
8151 during cross-compiling to build utility executables that can run on the
8152 host platform in one project and then import them into another project
8153 being compiled for the target platform. If the NAMESPACE option is
8154 given the <namespace> string will be prepended to all target names
8155 written to the file.
8156 Target installations are associated with the export <export-name> using
8158 the EXPORT option of the install(TARGETS) command.
8159 The file created by this command is specific to the build tree and
8161 should never be installed. See the install(EXPORT) command to export
8162 targets from an installation tree.
8163 The properties set on the generated IMPORTED targets will have the same
8165 values as the final values of the input TARGETS.
8166 export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
8168 [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
8169 This signature is similar to the EXPORT signature, but targets are
8171 listed explicitly rather than specified as an export-name. If the AP‐
8172 PEND option is given the generated code will be appended to the file
8173 instead of overwriting it. The EXPORT_LINK_INTERFACE_LIBRARIES key‐
8174 word, if present, causes the contents of the properties matching (IM‐
8175 PORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when pol‐
8176 icy CMP0022 is NEW. If a library target is included in the export but
8177 a target to which it links is not included the behavior is unspecified.
8178 NOTE:
8180 Object Libraries under Xcode have special handling if multiple ar‐
8181 chitectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
8182 they will be exported as Interface Libraries with no object files
8183 available to clients. This is sufficient to satisfy transitive us‐
8184 age requirements of other targets that link to the object libraries
8185 in their implementation.
8186 export(PACKAGE <PackageName>)
8188 Store the current build directory in the CMake user package registry
8190 for package <PackageName>. The find_package() command may consider the
8191 directory while searching for package <PackageName>. This helps depen‐
8192 dent projects find and use a package from the current project's build
8193 tree without help from the user. Note that the entry in the package
8194 registry that this command creates works only in conjunction with a
8195 package configuration file (<PackageName>Config.cmake) that works with
8196 the build tree. In some cases, for example for packaging and for system
8197 wide installations, it is not desirable to write the user package reg‐
8198 istry.
8199 Changed in version 3.1: If the CMAKE_EXPORT_NO_PACKAGE_REGISTRY vari‐
8201 able is enabled, the export(PACKAGE) command will do nothing.
8202 Changed in version 3.15: By default the export(PACKAGE) command does
8205 nothing (see policy CMP0090) because populating the user package reg‐
8206 istry has effects outside the source and build trees. Set the
8207 CMAKE_EXPORT_PACKAGE_REGISTRY variable to add build directories to the
8208 CMake user package registry.
8209 export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
8212 New in version 3.7.
8214 This signature exports cmake built targets to the android ndk build
8217 system by creating an Android.mk file that references the prebuilt tar‐
8218 gets. The Android NDK supports the use of prebuilt libraries, both
8219 static and shared. This allows cmake to build the libraries of a
8220 project and make them available to an ndk build system complete with
8221 transitive dependencies, include flags and defines required to use the
8222 libraries. The signature takes a list of targets and puts them in the
8223 Android.mk file specified by the <filename> given. This signature can
8224 only be used if policy CMP0022 is NEW for all targets given. A error
8225 will be issued if that policy is set to OLD for one of the targets.
8226 fltk_wrap_ui
8228 Create FLTK user interfaces Wrappers.
8229 fltk_wrap_ui(resultingLibraryName source1
8231 source2 ... sourceN )
8232 Produce .h and .cxx files for all the .fl and .fld files listed. The
8234 resulting .h and .cxx files will be added to a variable named result‐
8235 ingLibraryName_FLTK_UI_SRCS which should be added to your library.
8236 get_source_file_property
8238 Get a property for a source file.
8239 get_source_file_property(<variable> <file>
8241 [DIRECTORY <dir> | TARGET_DIRECTORY <target>]
8242 <property>)
8243 Gets a property from a source file. The value of the property is
8245 stored in the specified <variable>. If the source property is not
8246 found, the behavior depends on whether it has been defined to be an IN‐
8247 HERITED property or not (see define_property()). Non-inherited proper‐
8248 ties will set variable to NOTFOUND, whereas inherited properties will
8249 search the relevant parent scope as described for the define_property()
8250 command and if still unable to find the property, variable will be set
8251 to an empty string.
8252 By default, the source file's property will be read from the current
8254 source directory's scope.
8255 New in version 3.18: Directory scope can be overridden with one of the
8257 following sub-options:
8258 DIRECTORY <dir>
8260 The source file property will be read from the <dir> directory's
8261 scope. CMake must already know about that source directory, ei‐
8262 ther by having added it through a call to add_subdirectory() or
8263 <dir> being the top level source directory. Relative paths are
8264 treated as relative to the current source directory.
8265 TARGET_DIRECTORY <target>
8267 The source file property will be read from the directory scope
8268 in which <target> was created (<target> must therefore already
8269 exist).
8270 Use set_source_files_properties() to set property values. Source file
8273 properties usually control how the file is built. One property that is
8274 always there is LOCATION.
8275 See also the more general get_property() command.
8277 NOTE:
8279 The GENERATED source file property may be globally visible. See its
8280 documentation for details.
8281 get_target_property
8283 Get a property from a target.
8284 get_target_property(<VAR> target property)
8286 Get a property from a target. The value of the property is stored in
8288 the variable <VAR>. If the target property is not found, the behavior
8289 depends on whether it has been defined to be an INHERITED property or
8290 not (see define_property()). Non-inherited properties will set <VAR>
8291 to <VAR>-NOTFOUND, whereas inherited properties will search the rele‐
8292 vant parent scope as described for the define_property() command and if
8293 still unable to find the property, <VAR> will be set to an empty
8294 string.
8295 Use set_target_properties() to set target property values. Properties
8297 are usually used to control how a target is built, but some query the
8298 target instead. This command can get properties for any target so far
8299 created. The targets do not need to be in the current CMakeLists.txt
8300 file.
8301 See also the more general get_property() command.
8303 See Target Properties for the list of properties known to CMake.
8305 get_test_property
8307 Get a property of the test.
8308 get_test_property(test property VAR)
8310 Get a property from the test. The value of the property is stored in
8312 the variable VAR. If the test property is not found, the behavior de‐
8313 pends on whether it has been defined to be an INHERITED property or not
8314 (see define_property()). Non-inherited properties will set VAR to
8315 "NOTFOUND", whereas inherited properties will search the relevant par‐
8316 ent scope as described for the define_property() command and if still
8317 unable to find the property, VAR will be set to an empty string.
8318 For a list of standard properties you can type cmake --help-prop‐
8320 erty-list.
8321 See also the more general get_property() command.
8323 include_directories
8325 Add include directories to the build.
8326 include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])
8328 Add the given directories to those the compiler uses to search for in‐
8330 clude files. Relative paths are interpreted as relative to the current
8331 source directory.
8332 The include directories are added to the INCLUDE_DIRECTORIES directory
8334 property for the current CMakeLists file. They are also added to the
8335 INCLUDE_DIRECTORIES target property for each target in the current
8336 CMakeLists file. The target property values are the ones used by the
8337 generators.
8338 By default the directories specified are appended onto the current list
8340 of directories. This default behavior can be changed by setting
8341 CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE ex‐
8342 plicitly, you can select between appending and prepending, independent
8343 of the default.
8344 If the SYSTEM option is given, the compiler will be told the directo‐
8346 ries are meant as system include directories on some platforms. Sig‐
8347 nalling this setting might achieve effects such as the compiler skip‐
8348 ping warnings, or these fixed-install system files not being considered
8349 in dependency calculations - see compiler docs.
8350 Arguments to include_directories may use "generator expressions" with
8352 the syntax "$<...>". See the cmake-generator-expressions(7) manual for
8353 available expressions. See the cmake-buildsystem(7) manual for more on
8354 defining buildsystem properties.
8355 NOTE:
8357 Prefer the target_include_directories() command to add include di‐
8358 rectories to individual targets and optionally propagate/export them
8359 to dependents.
8360 include_external_msproject
8362 Include an external Microsoft project file in a workspace.
8363 include_external_msproject(projectname location
8365 [TYPE projectTypeGUID]
8366 [GUID projectGUID]
8367 [PLATFORM platformName]
8368 dep1 dep2 ...)
8369 Includes an external Microsoft project in the generated workspace file.
8371 Currently does nothing on UNIX. This will create a target named [pro‐
8372 jectname]. This can be used in the add_dependencies() command to make
8373 things depend on the external project.
8374 TYPE, GUID and PLATFORM are optional parameters that allow one to spec‐
8376 ify the type of project, id (GUID) of the project and the name of the
8377 target platform. This is useful for projects requiring values other
8378 than the default (e.g. WIX projects).
8379 New in version 3.9: If the imported project has different configuration
8381 names than the current project, set the MAP_IMPORTED_CONFIG_<CONFIG>
8382 target property to specify the mapping.
8383 include_regular_expression
8386 Set the regular expression used for dependency checking.
8387 include_regular_expression(regex_match [regex_complain])
8389 Sets the regular expressions used in dependency checking. Only files
8391 matching regex_match will be traced as dependencies. Only files match‐
8392 ing regex_complain will generate warnings if they cannot be found
8393 (standard header paths are not searched). The defaults are:
8394 regex_match = "^.*$" (match everything)
8396 regex_complain = "^$" (match empty string only)
8397 install
8399 Specify rules to run at install time.
8400 Synopsis
8402 install(TARGETS <target>... [...])
8403 install(IMPORTED_RUNTIME_ARTIFACTS <target>... [...])
8404 install({FILES | PROGRAMS} <file>... [...])
8405 install(DIRECTORY <dir>... [...])
8406 install(SCRIPT <file> [...])
8407 install(CODE <code> [...])
8408 install(EXPORT <export-name> [...])
8409 install(RUNTIME_DEPENDENCY_SET <set-name> [...])
8410 Introduction
8412 This command generates installation rules for a project. Install rules
8413 specified by calls to the install() command within a source directory
8414 are executed in order during installation.
8415 Changed in version 3.14: Install rules in subdirectories added by calls
8417 to the add_subdirectory() command are interleaved with those in the
8418 parent directory to run in the order declared (see policy CMP0082).
8419 Changed in version 3.22: The environment variable CMAKE_INSTALL_MODE
8422 can override the default copying behavior of install().
8423 There are multiple signatures for this command. Some of them define
8426 installation options for files and targets. Options common to multiple
8427 signatures are covered here but they are valid only for signatures that
8428 specify them. The common options are:
8429 DESTINATION
8431 Specify the directory on disk to which a file will be installed.
8432 Arguments can be relative or absolute paths.
8433 If a relative path is given it is interpreted relative to the
8435 value of the CMAKE_INSTALL_PREFIX variable. The prefix can be
8436 relocated at install time using the DESTDIR mechanism explained
8437 in the CMAKE_INSTALL_PREFIX variable documentation.
8438 If an absolute path (with a leading slash or drive letter) is
8440 given it is used verbatim.
8441 As absolute paths are not supported by cpack installer genera‐
8443 tors, it is preferable to use relative paths throughout. In
8444 particular, there is no need to make paths absolute by prepend‐
8445 ing CMAKE_INSTALL_PREFIX; this prefix is used by default if the
8446 DESTINATION is a relative path.
8447 PERMISSIONS
8449 Specify permissions for installed files. Valid permissions are
8450 OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE,
8451 GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID,
8452 and SETGID. Permissions that do not make sense on certain plat‐
8453 forms are ignored on those platforms.
8454 CONFIGURATIONS
8456 Specify a list of build configurations for which the install
8457 rule applies (Debug, Release, etc.). Note that the values speci‐
8458 fied for this option only apply to options listed AFTER the CON‐
8459 FIGURATIONS option. For example, to set separate install paths
8460 for the Debug and Release configurations, do the following:
8461 install(TARGETS target
8463 CONFIGURATIONS Debug
8464 RUNTIME DESTINATION Debug/bin)
8465 install(TARGETS target
8466 CONFIGURATIONS Release
8467 RUNTIME DESTINATION Release/bin)
8468 Note that CONFIGURATIONS appears BEFORE RUNTIME DESTINATION.
8470 COMPONENT
8472 Specify an installation component name with which the install
8473 rule is associated, such as "runtime" or "development". During
8474 component-specific installation only install rules associated
8475 with the given component name will be executed. During a full
8476 installation all components are installed unless marked with EX‐
8477 CLUDE_FROM_ALL. If COMPONENT is not provided a default compo‐
8478 nent "Unspecified" is created. The default component name may
8479 be controlled with the CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
8480 variable.
8481 EXCLUDE_FROM_ALL
8483 New in version 3.6.
8484 Specify that the file is excluded from a full installation and
8487 only installed as part of a component-specific installation
8488 RENAME Specify a name for an installed file that may be different from
8490 the original file. Renaming is allowed only when a single file
8491 is installed by the command.
8492 OPTIONAL
8494 Specify that it is not an error if the file to be installed does
8495 not exist.
8496 New in version 3.1: Command signatures that install files may print
8498 messages during installation. Use the CMAKE_INSTALL_MESSAGE variable
8499 to control which messages are printed.
8500 New in version 3.11: Many of the install() variants implicitly create
8503 the directories containing the installed files. If CMAKE_INSTALL_DE‐
8504 FAULT_DIRECTORY_PERMISSIONS is set, these directories will be created
8505 with the permissions specified. Otherwise, they will be created accord‐
8506 ing to the uname rules on Unix-like platforms. Windows platforms are
8507 unaffected.
8508 Installing Targets
8511 install(TARGETS targets... [EXPORT <export-name>]
8512 [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>]
8513 [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
8514 PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
8515 [DESTINATION <dir>]
8516 [PERMISSIONS permissions...]
8517 [CONFIGURATIONS [Debug|Release|...]]
8518 [COMPONENT <component>]
8519 [NAMELINK_COMPONENT <component>]
8520 [OPTIONAL] [EXCLUDE_FROM_ALL]
8521 [NAMELINK_ONLY|NAMELINK_SKIP]
8522 ] [...]
8523 [INCLUDES DESTINATION [<dir> ...]]
8524 )
8525 The TARGETS form specifies rules for installing targets from a project.
8527 There are several kinds of target Output Artifacts that may be in‐
8528 stalled:
8529 ARCHIVE
8531 Target artifacts of this kind include:
8532 • Static libraries (except on macOS when marked as FRAMEWORK,
8534 see below);
8535 • DLL import libraries (on all Windows-based systems including
8537 Cygwin; they have extension .lib, in contrast to the .dll li‐
8538 braries that go to RUNTIME);
8539 • On AIX, the linker import file created for executables with
8541 ENABLE_EXPORTS enabled.
8542 LIBRARY
8544 Target artifacts of this kind include:
8545 • Shared libraries, except
8547 • DLLs (these go to RUNTIME, see below),
8549 • on macOS when marked as FRAMEWORK (see below).
8551 RUNTIME
8553 Target artifacts of this kind include:
8554 • Executables (except on macOS when marked as MACOSX_BUNDLE, see
8556 BUNDLE below);
8557 • DLLs (on all Windows-based systems including Cygwin; note that
8559 the accompanying import libraries are of kind ARCHIVE).
8560 OBJECTS
8562 New in version 3.9.
8563 Object files associated with object libraries.
8566 FRAMEWORK
8568 Both static and shared libraries marked with the FRAMEWORK prop‐
8569 erty are treated as FRAMEWORK targets on macOS.
8570 BUNDLE Executables marked with the MACOSX_BUNDLE property are treated
8572 as BUNDLE targets on macOS.
8573 PUBLIC_HEADER
8575 Any PUBLIC_HEADER files associated with a library are installed
8576 in the destination specified by the PUBLIC_HEADER argument on
8577 non-Apple platforms. Rules defined by this argument are ignored
8578 for FRAMEWORK libraries on Apple platforms because the associ‐
8579 ated files are installed into the appropriate locations inside
8580 the framework folder. See PUBLIC_HEADER for details.
8581 PRIVATE_HEADER
8583 Similar to PUBLIC_HEADER, but for PRIVATE_HEADER files. See PRI‐
8584 VATE_HEADER for details.
8585 RESOURCE
8587 Similar to PUBLIC_HEADER and PRIVATE_HEADER, but for RESOURCE
8588 files. See RESOURCE for details.
8589 For each of these arguments given, the arguments following them only
8591 apply to the target or file type specified in the argument. If none is
8592 given, the installation properties apply to all target types. If only
8593 one is given then only targets of that type will be installed (which
8594 can be used to install just a DLL or just an import library.)
8595 For regular executables, static libraries and shared libraries, the
8597 DESTINATION argument is not required. For these target types, when
8598 DESTINATION is omitted, a default destination will be taken from the
8599 appropriate variable from GNUInstallDirs, or set to a built-in default
8600 value if that variable is not defined. The same is true for the public
8601 and private headers associated with the installed targets through the
8602 PUBLIC_HEADER and PRIVATE_HEADER target properties. A destination must
8603 always be provided for module libraries, Apple bundles and frameworks.
8604 A destination can be omitted for interface and object libraries, but
8605 they are handled differently (see the discussion of this topic toward
8606 the end of this section).
8607 The following table shows the target types with their associated vari‐
8609 ables and built-in defaults that apply when no destination is given:
8610 ┌───────────────┬─────────────────────┬──────────────────┐
8612 │Target Type │ GNUInstallDirs │ Built-In Default │
8613 │ │ Variable │ │
8614 ├───────────────┼─────────────────────┼──────────────────┤
8615 │RUNTIME │ ${CMAKE_IN‐ │ bin │
8616 │ │ STALL_BINDIR} │ │
8617 ├───────────────┼─────────────────────┼──────────────────┤
8618 │LIBRARY │ ${CMAKE_IN‐ │ lib │
8619 │ │ STALL_LIBDIR} │ │
8620 ├───────────────┼─────────────────────┼──────────────────┤
8621 │ARCHIVE │ ${CMAKE_IN‐ │ lib │
8622 │ │ STALL_LIBDIR} │ │
8623 ├───────────────┼─────────────────────┼──────────────────┤
8624 │PRIVATE_HEADER │ ${CMAKE_INSTALL_IN‐ │ include │
8625 │ │ CLUDEDIR} │ │
8626 ├───────────────┼─────────────────────┼──────────────────┤
8627 │PUBLIC_HEADER │ ${CMAKE_INSTALL_IN‐ │ include │
8628 │ │ CLUDEDIR} │ │
8629 └───────────────┴─────────────────────┴──────────────────┘
8630 Projects wishing to follow the common practice of installing headers
8632 into a project-specific subdirectory will need to provide a destination
8633 rather than rely on the above.
8634 To make packages compliant with distribution filesystem layout poli‐
8636 cies, if projects must specify a DESTINATION, it is recommended that
8637 they use a path that begins with the appropriate GNUInstallDirs vari‐
8638 able. This allows package maintainers to control the install destina‐
8639 tion by setting the appropriate cache variables. The following example
8640 shows a static library being installed to the default destination pro‐
8641 vided by GNUInstallDirs, but with its headers installed to a
8642 project-specific subdirectory that follows the above recommendation:
8643 add_library(mylib STATIC ...)
8645 set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
8646 include(GNUInstallDirs)
8647 install(TARGETS mylib
8648 PUBLIC_HEADER
8649 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
8650 )
8651 In addition to the common options listed above, each target can accept
8653 the following additional arguments:
8654 NAMELINK_COMPONENT
8656 New in version 3.12.
8657 On some platforms a versioned shared library has a symbolic link
8660 such as:
8661 lib<name>.so -> lib<name>.so.1
8663 where lib<name>.so.1 is the soname of the library and
8665 lib<name>.so is a "namelink" allowing linkers to find the li‐
8666 brary when given -l<name>. The NAMELINK_COMPONENT option is sim‐
8667 ilar to the COMPONENT option, but it changes the installation
8668 component of a shared library namelink if one is generated. If
8669 not specified, this defaults to the value of COMPONENT. It is an
8670 error to use this parameter outside of a LIBRARY block.
8671 Consider the following example:
8673 install(TARGETS mylib
8675 LIBRARY
8676 COMPONENT Libraries
8677 NAMELINK_COMPONENT Development
8678 PUBLIC_HEADER
8679 COMPONENT Development
8680 )
8681 In this scenario, if you choose to install only the Development
8683 component, both the headers and namelink will be installed with‐
8684 out the library. (If you don't also install the Libraries compo‐
8685 nent, the namelink will be a dangling symlink, and projects that
8686 link to the library will have build errors.) If you install only
8687 the Libraries component, only the library will be installed,
8688 without the headers and namelink.
8689 This option is typically used for package managers that have
8691 separate runtime and development packages. For example, on De‐
8692 bian systems, the library is expected to be in the runtime pack‐
8693 age, and the headers and namelink are expected to be in the de‐
8694 velopment package.
8695 See the VERSION and SOVERSION target properties for details on
8697 creating versioned shared libraries.
8698 NAMELINK_ONLY
8700 This option causes the installation of only the namelink when a
8701 library target is installed. On platforms where versioned shared
8702 libraries do not have namelinks or when a library is not ver‐
8703 sioned, the NAMELINK_ONLY option installs nothing. It is an er‐
8704 ror to use this parameter outside of a LIBRARY block.
8705 When NAMELINK_ONLY is given, either NAMELINK_COMPONENT or COMPO‐
8707 NENT may be used to specify the installation component of the
8708 namelink, but COMPONENT should generally be preferred.
8709 NAMELINK_SKIP
8711 Similar to NAMELINK_ONLY, but it has the opposite effect: it
8712 causes the installation of library files other than the namelink
8713 when a library target is installed. When neither NAMELINK_ONLY
8714 or NAMELINK_SKIP are given, both portions are installed. On
8715 platforms where versioned shared libraries do not have symlinks
8716 or when a library is not versioned, NAMELINK_SKIP installs the
8717 library. It is an error to use this parameter outside of a LI‐
8718 BRARY block.
8719 If NAMELINK_SKIP is specified, NAMELINK_COMPONENT has no effect.
8721 It is not recommended to use NAMELINK_SKIP in conjunction with
8722 NAMELINK_COMPONENT.
8723 The install(TARGETS) command can also accept the following options at
8725 the top level:
8726 EXPORT This option associates the installed target files with an export
8728 called <export-name>. It must appear before any target options.
8729 To actually install the export file itself, call
8730 install(EXPORT), documented below. See documentation of the EX‐
8731 PORT_NAME target property to change the name of the exported
8732 target.
8733 INCLUDES DESTINATION
8735 This option specifies a list of directories which will be added
8736 to the INTERFACE_INCLUDE_DIRECTORIES target property of the
8737 <targets> when exported by the install(EXPORT) command. If a
8738 relative path is specified, it is treated as relative to the
8739 $<INSTALL_PREFIX>.
8740 RUNTIME_DEPENDENCY_SET
8742 New in version 3.21.
8743 This option causes all runtime dependencies of installed exe‐
8746 cutable, shared library, and module targets to be added to the
8747 specified runtime dependency set. This set can then be installed
8748 with an install(RUNTIME_DEPENDENCY_SET) command.
8749 This keyword and the RUNTIME_DEPENDENCIES keyword are mutually
8751 exclusive.
8752 RUNTIME_DEPENDENCIES
8754 New in version 3.21.
8755 This option causes all runtime dependencies of installed exe‐
8758 cutable, shared library, and module targets to be installed
8759 along with the targets themselves. The RUNTIME, LIBRARY, FRAME‐
8760 WORK, and generic arguments are used to determine the properties
8761 (DESTINATION, COMPONENT, etc.) of the installation of these de‐
8762 pendencies.
8763 RUNTIME_DEPENDENCIES is semantically equivalent to the following
8765 pair of calls:
8766 install(TARGETS ... RUNTIME_DEPENDENCY_SET <set-name>)
8768 install(RUNTIME_DEPENDENCY_SET <set-name> args...)
8769 where <set-name> will be a randomly generated set name. The
8771 args... may include any of the following keywords supported by
8772 the install(RUNTIME_DEPENDENCY_SET) command:
8773 • DIRECTORIES
8775 • PRE_INCLUDE_REGEXES
8777 • PRE_EXCLUDE_REGEXES
8779 • POST_INCLUDE_REGEXES
8781 • POST_EXCLUDE_REGEXES
8783 • POST_INCLUDE_FILES
8785 • POST_EXCLUDE_FILES
8787 The RUNTIME_DEPENDENCIES and RUNTIME_DEPENDENCY_SET keywords are
8789 mutually exclusive.
8790 One or more groups of properties may be specified in a single call to
8792 the TARGETS form of this command. A target may be installed more than
8793 once to different locations. Consider hypothetical targets myExe,
8794 mySharedLib, and myStaticLib. The code:
8795 install(TARGETS myExe mySharedLib myStaticLib
8797 RUNTIME DESTINATION bin
8798 LIBRARY DESTINATION lib
8799 ARCHIVE DESTINATION lib/static)
8800 install(TARGETS mySharedLib DESTINATION /some/full/path)
8801 will install myExe to <prefix>/bin and myStaticLib to <pre‐
8803 fix>/lib/static. On non-DLL platforms mySharedLib will be installed to
8804 <prefix>/lib and /some/full/path. On DLL platforms the mySharedLib DLL
8805 will be installed to <prefix>/bin and /some/full/path and its import
8806 library will be installed to <prefix>/lib/static and /some/full/path.
8807 Interface Libraries may be listed among the targets to install. They
8809 install no artifacts but will be included in an associated EXPORT. If
8810 Object Libraries are listed but given no destination for their object
8811 files, they will be exported as Interface Libraries. This is suffi‐
8812 cient to satisfy transitive usage requirements of other targets that
8813 link to the object libraries in their implementation.
8814 Installing a target with the EXCLUDE_FROM_ALL target property set to
8816 TRUE has undefined behavior.
8817 New in version 3.3: An install destination given as a DESTINATION argu‐
8819 ment may use "generator expressions" with the syntax $<...>. See the
8820 cmake-generator-expressions(7) manual for available expressions.
8821 New in version 3.13: install(TARGETS) can install targets that were
8824 created in other directories. When using such cross-directory install
8825 rules, running make install (or similar) from a subdirectory will not
8826 guarantee that targets from other directories are up-to-date. You can
8827 use target_link_libraries() or add_dependencies() to ensure that such
8828 out-of-directory targets are built before the subdirectory-specific in‐
8829 stall rules are run.
8830 Installing Imported Runtime Artifacts
8833 New in version 3.21.
8834 install(IMPORTED_RUNTIME_ARTIFACTS targets...
8837 [RUNTIME_DEPENDENCY_SET <set-name>]
8838 [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE]
8839 [DESTINATION <dir>]
8840 [PERMISSIONS permissions...]
8841 [CONFIGURATIONS [Debug|Release|...]]
8842 [COMPONENT <component>]
8843 [OPTIONAL] [EXCLUDE_FROM_ALL]
8844 ] [...]
8845 )
8846 The IMPORTED_RUNTIME_ARTIFACTS form specifies rules for installing the
8848 runtime artifacts of imported targets. Projects may do this if they
8849 want to bundle outside executables or modules inside their installa‐
8850 tion. The LIBRARY, RUNTIME, FRAMEWORK, and BUNDLE arguments have the
8851 same semantics that they do in the TARGETS mode. Only the runtime arti‐
8852 facts of imported targets are installed (except in the case of FRAME‐
8853 WORK libraries, MACOSX_BUNDLE executables, and BUNDLE CFBundles.) For
8854 example, headers and import libraries associated with DLLs are not in‐
8855 stalled. In the case of FRAMEWORK libraries, MACOSX_BUNDLE executables,
8856 and BUNDLE CFBundles, the entire directory is installed.
8857 The RUNTIME_DEPENDENCY_SET option causes the runtime artifacts of the
8859 imported executable, shared library, and module library targets to be
8860 added to the <set-name> runtime dependency set. This set can then be
8861 installed with an install(RUNTIME_DEPENDENCY_SET) command.
8862 Installing Files
8864 install(<FILES|PROGRAMS> files...
8865 TYPE <type> | DESTINATION <dir>
8866 [PERMISSIONS permissions...]
8867 [CONFIGURATIONS [Debug|Release|...]]
8868 [COMPONENT <component>]
8869 [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
8870 The FILES form specifies rules for installing files for a project.
8872 File names given as relative paths are interpreted with respect to the
8873 current source directory. Files installed by this form are by default
8874 given permissions OWNER_WRITE, OWNER_READ, GROUP_READ, and WORLD_READ
8875 if no PERMISSIONS argument is given.
8876 The PROGRAMS form is identical to the FILES form except that the de‐
8878 fault permissions for the installed file also include OWNER_EXECUTE,
8879 GROUP_EXECUTE, and WORLD_EXECUTE. This form is intended to install
8880 programs that are not targets, such as shell scripts. Use the TARGETS
8881 form to install targets built within the project.
8882 The list of files... given to FILES or PROGRAMS may use "generator ex‐
8884 pressions" with the syntax $<...>. See the cmake-generator-expres‐
8885 sions(7) manual for available expressions. However, if any item begins
8886 in a generator expression it must evaluate to a full path.
8887 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
8889 argument specifies the generic file type of the files being installed.
8890 A destination will then be set automatically by taking the correspond‐
8891 ing variable from GNUInstallDirs, or by using a built-in default if
8892 that variable is not defined. See the table below for the supported
8893 file types and their corresponding variables and built-in defaults.
8894 Projects can provide a DESTINATION argument instead of a file type if
8895 they wish to explicitly define the install destination.
8896 ┌──────────────┬─────────────────────┬─────────────────────┐
8898 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
8899 │ │ Variable │ │
8900 ├──────────────┼─────────────────────┼─────────────────────┤
8901 │BIN │ ${CMAKE_IN‐ │ bin │
8902 │ │ STALL_BINDIR} │ │
8903 ├──────────────┼─────────────────────┼─────────────────────┤
8904 │SBIN │ ${CMAKE_IN‐ │ sbin │
8905 │ │ STALL_SBINDIR} │ │
8906 ├──────────────┼─────────────────────┼─────────────────────┤
8907 │LIB │ ${CMAKE_IN‐ │ lib │
8908 │ │ STALL_LIBDIR} │ │
8909 ├──────────────┼─────────────────────┼─────────────────────┤
8910 │INCLUDE │ ${CMAKE_INSTALL_IN‐ │ include │
8911 │ │ CLUDEDIR} │ │
8912 ├──────────────┼─────────────────────┼─────────────────────┤
8913 │SYSCONF │ ${CMAKE_IN‐ │ etc │
8914 │ │ STALL_SYSCONFDIR} │ │
8915 ├──────────────┼─────────────────────┼─────────────────────┤
8916 │SHAREDSTATE │ ${CMAKE_IN‐ │ com │
8917 │ │ STALL_SHARESTATE‐ │ │
8918 │ │ DIR} │ │
8919 ├──────────────┼─────────────────────┼─────────────────────┤
8920 │LOCALSTATE │ ${CMAKE_INSTALL_LO‐ │ var │
8921 │ │ CALSTATEDIR} │ │
8922 ├──────────────┼─────────────────────┼─────────────────────┤
8923 │RUNSTATE │ ${CMAKE_IN‐ │ <LOCALSTATE │
8924 │ │ STALL_RUNSTATEDIR} │ dir>/run │
8925 ├──────────────┼─────────────────────┼─────────────────────┤
8926 │DATA │ ${CMAKE_IN‐ │ <DATAROOT dir> │
8927 │ │ STALL_DATADIR} │ │
8928 └──────────────┴─────────────────────┴─────────────────────┘
8929 │INFO │ ${CMAKE_INSTALL_IN‐ │ <DATAROOT dir>/info │
8931 │ │ FODIR} │ │
8932 ├──────────────┼─────────────────────┼─────────────────────┤
8933 │LOCALE │ ${CMAKE_INSTALL_LO‐ │ <DATAROOT dir>/lo‐ │
8934 │ │ CALEDIR} │ cale │
8935 ├──────────────┼─────────────────────┼─────────────────────┤
8936 │MAN │ ${CMAKE_IN‐ │ <DATAROOT dir>/man │
8937 │ │ STALL_MANDIR} │ │
8938 ├──────────────┼─────────────────────┼─────────────────────┤
8939 │DOC │ ${CMAKE_IN‐ │ <DATAROOT dir>/doc │
8940 │ │ STALL_DOCDIR} │ │
8941 └──────────────┴─────────────────────┴─────────────────────┘
8942 Projects wishing to follow the common practice of installing headers
8944 into a project-specific subdirectory will need to provide a destination
8945 rather than rely on the above.
8946 Note that some of the types' built-in defaults use the DATAROOT direc‐
8948 tory as a prefix. The DATAROOT prefix is calculated similarly to the
8949 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
8950 built-in default. You cannot use DATAROOT as a TYPE parameter; please
8951 use DATA instead.
8952 To make packages compliant with distribution filesystem layout poli‐
8954 cies, if projects must specify a DESTINATION, it is recommended that
8955 they use a path that begins with the appropriate GNUInstallDirs vari‐
8956 able. This allows package maintainers to control the install destina‐
8957 tion by setting the appropriate cache variables. The following example
8958 shows how to follow this advice while installing headers to a
8959 project-specific subdirectory:
8960 include(GNUInstallDirs)
8962 install(FILES mylib.h
8963 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
8964 )
8965 New in version 3.4: An install destination given as a DESTINATION argu‐
8967 ment may use "generator expressions" with the syntax $<...>. See the
8968 cmake-generator-expressions(7) manual for available expressions.
8969 New in version 3.20: An install rename given as a RENAME argument may
8972 use "generator expressions" with the syntax $<...>. See the cmake-gen‐
8973 erator-expressions(7) manual for available expressions.
8974 Installing Directories
8977 install(DIRECTORY dirs...
8978 TYPE <type> | DESTINATION <dir>
8979 [FILE_PERMISSIONS permissions...]
8980 [DIRECTORY_PERMISSIONS permissions...]
8981 [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
8982 [CONFIGURATIONS [Debug|Release|...]]
8983 [COMPONENT <component>] [EXCLUDE_FROM_ALL]
8984 [FILES_MATCHING]
8985 [[PATTERN <pattern> | REGEX <regex>]
8986 [EXCLUDE] [PERMISSIONS permissions...]] [...])
8987 The DIRECTORY form installs contents of one or more directories to a
8989 given destination. The directory structure is copied verbatim to the
8990 destination. The last component of each directory name is appended to
8991 the destination directory but a trailing slash may be used to avoid
8992 this because it leaves the last component empty. Directory names given
8993 as relative paths are interpreted with respect to the current source
8994 directory. If no input directory names are given the destination di‐
8995 rectory will be created but nothing will be installed into it. The
8996 FILE_PERMISSIONS and DIRECTORY_PERMISSIONS options specify permissions
8997 given to files and directories in the destination. If USE_SOURCE_PER‐
8998 MISSIONS is specified and FILE_PERMISSIONS is not, file permissions
8999 will be copied from the source directory structure. If no permissions
9000 are specified files will be given the default permissions specified in
9001 the FILES form of the command, and the directories will be given the
9002 default permissions specified in the PROGRAMS form of the command.
9003 New in version 3.1: The MESSAGE_NEVER option disables file installation
9005 status output.
9006 Installation of directories may be controlled with fine granularity us‐
9009 ing the PATTERN or REGEX options. These "match" options specify a
9010 globbing pattern or regular expression to match directories or files
9011 encountered within input directories. They may be used to apply cer‐
9012 tain options (see below) to a subset of the files and directories en‐
9013 countered. The full path to each input file or directory (with forward
9014 slashes) is matched against the expression. A PATTERN will match only
9015 complete file names: the portion of the full path matching the pattern
9016 must occur at the end of the file name and be preceded by a slash. A
9017 REGEX will match any portion of the full path but it may use / and $ to
9018 simulate the PATTERN behavior. By default all files and directories
9019 are installed whether or not they are matched. The FILES_MATCHING op‐
9020 tion may be given before the first match option to disable installation
9021 of files (but not directories) not matched by any expression. For ex‐
9022 ample, the code
9023 install(DIRECTORY src/ DESTINATION include/myproj
9025 FILES_MATCHING PATTERN "*.h")
9026 will extract and install header files from a source tree.
9028 Some options may follow a PATTERN or REGEX expression as described un‐
9030 der string(REGEX) and are applied only to files or directories matching
9031 them. The EXCLUDE option will skip the matched file or directory. The
9032 PERMISSIONS option overrides the permissions setting for the matched
9033 file or directory. For example the code
9034 install(DIRECTORY icons scripts/ DESTINATION share/myproj
9036 PATTERN "CVS" EXCLUDE
9037 PATTERN "scripts/*"
9038 PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
9039 GROUP_EXECUTE GROUP_READ)
9040 will install the icons directory to share/myproj/icons and the scripts
9042 directory to share/myproj. The icons will get default file permis‐
9043 sions, the scripts will be given specific permissions, and any CVS di‐
9044 rectories will be excluded.
9045 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
9047 argument specifies the generic file type of the files within the listed
9048 directories being installed. A destination will then be set automati‐
9049 cally by taking the corresponding variable from GNUInstallDirs, or by
9050 using a built-in default if that variable is not defined. See the ta‐
9051 ble below for the supported file types and their corresponding vari‐
9052 ables and built-in defaults. Projects can provide a DESTINATION argu‐
9053 ment instead of a file type if they wish to explicitly define the in‐
9054 stall destination.
9055 ┌──────────────┬─────────────────────┬─────────────────────┐
9057 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
9058 │ │ Variable │ │
9059 ├──────────────┼─────────────────────┼─────────────────────┤
9060 │BIN │ ${CMAKE_IN‐ │ bin │
9061 │ │ STALL_BINDIR} │ │
9062 ├──────────────┼─────────────────────┼─────────────────────┤
9063 │SBIN │ ${CMAKE_IN‐ │ sbin │
9064 │ │ STALL_SBINDIR} │ │
9065 ├──────────────┼─────────────────────┼─────────────────────┤
9066 │LIB │ ${CMAKE_IN‐ │ lib │
9067 │ │ STALL_LIBDIR} │ │
9068 ├──────────────┼─────────────────────┼─────────────────────┤
9069 │INCLUDE │ ${CMAKE_INSTALL_IN‐ │ include │
9070 │ │ CLUDEDIR} │ │
9071 ├──────────────┼─────────────────────┼─────────────────────┤
9072 │SYSCONF │ ${CMAKE_IN‐ │ etc │
9073 │ │ STALL_SYSCONFDIR} │ │
9074 ├──────────────┼─────────────────────┼─────────────────────┤
9075 │SHAREDSTATE │ ${CMAKE_IN‐ │ com │
9076 │ │ STALL_SHARESTATE‐ │ │
9077 │ │ DIR} │ │
9078 ├──────────────┼─────────────────────┼─────────────────────┤
9079 │LOCALSTATE │ ${CMAKE_INSTALL_LO‐ │ var │
9080 │ │ CALSTATEDIR} │ │
9081 ├──────────────┼─────────────────────┼─────────────────────┤
9082 │RUNSTATE │ ${CMAKE_IN‐ │ <LOCALSTATE │
9083 │ │ STALL_RUNSTATEDIR} │ dir>/run │
9084 ├──────────────┼─────────────────────┼─────────────────────┤
9085 │DATA │ ${CMAKE_IN‐ │ <DATAROOT dir> │
9086 │ │ STALL_DATADIR} │ │
9087 ├──────────────┼─────────────────────┼─────────────────────┤
9088 │INFO │ ${CMAKE_INSTALL_IN‐ │ <DATAROOT dir>/info │
9089 │ │ FODIR} │ │
9090 ├──────────────┼─────────────────────┼─────────────────────┤
9091 │LOCALE │ ${CMAKE_INSTALL_LO‐ │ <DATAROOT dir>/lo‐ │
9092 │ │ CALEDIR} │ cale │
9093 ├──────────────┼─────────────────────┼─────────────────────┤
9094 │MAN │ ${CMAKE_IN‐ │ <DATAROOT dir>/man │
9095 │ │ STALL_MANDIR} │ │
9096 ├──────────────┼─────────────────────┼─────────────────────┤
9097 │DOC │ ${CMAKE_IN‐ │ <DATAROOT dir>/doc │
9098 │ │ STALL_DOCDIR} │ │
9099 └──────────────┴─────────────────────┴─────────────────────┘
9100 Note that some of the types' built-in defaults use the DATAROOT direc‐
9102 tory as a prefix. The DATAROOT prefix is calculated similarly to the
9103 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
9104 built-in default. You cannot use DATAROOT as a TYPE parameter; please
9105 use DATA instead.
9106 To make packages compliant with distribution filesystem layout poli‐
9108 cies, if projects must specify a DESTINATION, it is recommended that
9109 they use a path that begins with the appropriate GNUInstallDirs vari‐
9110 able. This allows package maintainers to control the install destina‐
9111 tion by setting the appropriate cache variables.
9112 New in version 3.4: An install destination given as a DESTINATION argu‐
9114 ment may use "generator expressions" with the syntax $<...>. See the
9115 cmake-generator-expressions(7) manual for available expressions.
9116 New in version 3.5: The list of dirs... given to DIRECTORY may use
9119 "generator expressions" too.
9120 Custom Installation Logic
9123 install([[SCRIPT <file>] [CODE <code>]]
9124 [ALL_COMPONENTS | COMPONENT <component>]
9125 [EXCLUDE_FROM_ALL] [...])
9126 The SCRIPT form will invoke the given CMake script files during instal‐
9128 lation. If the script file name is a relative path it will be inter‐
9129 preted with respect to the current source directory. The CODE form
9130 will invoke the given CMake code during installation. Code is speci‐
9131 fied as a single argument inside a double-quoted string. For example,
9132 the code
9133 install(CODE "MESSAGE(\"Sample install message.\")")
9135 will print a message during installation.
9137 New in version 3.21: When the ALL_COMPONENTS option is given, the cus‐
9139 tom installation script code will be executed for every component of a
9140 component-specific installation. This option is mutually exclusive
9141 with the COMPONENT option.
9142 New in version 3.14: <file> or <code> may use "generator expressions"
9145 with the syntax $<...> (in the case of <file>, this refers to their use
9146 in the file name, not the file's contents). See the cmake-genera‐
9147 tor-expressions(7) manual for available expressions.
9148 Installing Exports
9151 install(EXPORT <export-name> DESTINATION <dir>
9152 [NAMESPACE <namespace>] [[FILE <name>.cmake]|
9153 [PERMISSIONS permissions...]
9154 [CONFIGURATIONS [Debug|Release|...]]
9155 [EXPORT_LINK_INTERFACE_LIBRARIES]
9156 [COMPONENT <component>]
9157 [EXCLUDE_FROM_ALL])
9158 install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])
9159 The EXPORT form generates and installs a CMake file containing code to
9161 import targets from the installation tree into another project. Target
9162 installations are associated with the export <export-name> using the
9163 EXPORT option of the install(TARGETS) signature documented above. The
9164 NAMESPACE option will prepend <namespace> to the target names as they
9165 are written to the import file. By default the generated file will be
9166 called <export-name>.cmake but the FILE option may be used to specify a
9167 different name. The value given to the FILE option must be a file name
9168 with the .cmake extension. If a CONFIGURATIONS option is given then
9169 the file will only be installed when one of the named configurations is
9170 installed. Additionally, the generated import file will reference only
9171 the matching target configurations. The EXPORT_LINK_INTERFACE_LI‐
9172 BRARIES keyword, if present, causes the contents of the properties
9173 matching (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be ex‐
9174 ported, when policy CMP0022 is NEW.
9175 NOTE:
9177 The installed <export-name>.cmake file may come with additional
9178 per-configuration <export-name>-*.cmake files to be loaded by glob‐
9179 bing. Do not use an export name that is the same as the package
9180 name in combination with installing a <package-name>-config.cmake
9181 file or the latter may be incorrectly matched by the glob and
9182 loaded.
9183 When a COMPONENT option is given, the listed <component> implicitly de‐
9185 pends on all components mentioned in the export set. The exported
9186 <name>.cmake file will require each of the exported components to be
9187 present in order for dependent projects to build properly. For example,
9188 a project may define components Runtime and Development, with shared
9189 libraries going into the Runtime component and static libraries and
9190 headers going into the Development component. The export set would also
9191 typically be part of the Development component, but it would export
9192 targets from both the Runtime and Development components. Therefore,
9193 the Runtime component would need to be installed if the Development
9194 component was installed, but not vice versa. If the Development compo‐
9195 nent was installed without the Runtime component, dependent projects
9196 that try to link against it would have build errors. Package managers,
9197 such as APT and RPM, typically handle this by listing the Runtime com‐
9198 ponent as a dependency of the Development component in the package
9199 metadata, ensuring that the library is always installed if the headers
9200 and CMake export file are present.
9201 New in version 3.7: In addition to cmake language files, the EXPORT_AN‐
9203 DROID_MK mode maybe used to specify an export to the android ndk build
9204 system. This mode accepts the same options as the normal export mode.
9205 The Android NDK supports the use of prebuilt libraries, both static and
9206 shared. This allows cmake to build the libraries of a project and make
9207 them available to an ndk build system complete with transitive depen‐
9208 dencies, include flags and defines required to use the libraries.
9209 The EXPORT form is useful to help outside projects use targets built
9212 and installed by the current project. For example, the code
9213 install(TARGETS myexe EXPORT myproj DESTINATION bin)
9215 install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
9216 install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules)
9217 will install the executable myexe to <prefix>/bin and code to import it
9219 in the file <prefix>/lib/myproj/myproj.cmake and <pre‐
9220 fix>/share/ndk-modules/Android.mk. An outside project may load this
9221 file with the include command and reference the myexe executable from
9222 the installation tree using the imported target name mp_myexe as if the
9223 target were built in its own tree.
9224 NOTE:
9226 This command supersedes the install_targets() command and the
9227 PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT target properties. It
9228 also replaces the FILES forms of the install_files() and in‐
9229 stall_programs() commands. The processing order of these install
9230 rules relative to those generated by install_targets(), in‐
9231 stall_files(), and install_programs() commands is not defined.
9232 Installing Runtime Dependencies
9234 New in version 3.21.
9235 install(RUNTIME_DEPENDENCY_SET <set-name>
9238 [[LIBRARY|RUNTIME|FRAMEWORK]
9239 [DESTINATION <dir>]
9240 [PERMISSIONS permissions...]
9241 [CONFIGURATIONS [Debug|Release|...]]
9242 [COMPONENT <component>]
9243 [NAMELINK_COMPONENT <component>]
9244 [OPTIONAL] [EXCLUDE_FROM_ALL]
9245 ] [...]
9246 [PRE_INCLUDE_REGEXES regexes...]
9247 [PRE_EXCLUDE_REGEXES regexes...]
9248 [POST_INCLUDE_REGEXES regexes...]
9249 [POST_EXCLUDE_REGEXES regexes...]
9250 [POST_INCLUDE_FILES files...]
9251 [POST_EXCLUDE_FILES files...]
9252 [DIRECTORIES directories...]
9253 )
9254 Installs a runtime dependency set previously created by one or more
9256 install(TARGETS) or install(IMPORTED_RUNTIME_ARTIFACTS) commands. The
9257 dependencies of targets belonging to a runtime dependency set are in‐
9258 stalled in the RUNTIME destination and component on DLL platforms, and
9259 in the LIBRARY destination and component on non-DLL platforms. macOS
9260 frameworks are installed in the FRAMEWORK destination and component.
9261 Targets built within the build tree will never be installed as runtime
9262 dependencies, nor will their own dependencies, unless the targets them‐
9263 selves are installed with install(TARGETS).
9264 The generated install script calls file(GET_RUNTIME_DEPENDENCIES) on
9266 the build-tree files to calculate the runtime dependencies. The
9267 build-tree executable files are passed as the EXECUTABLES argument, the
9268 build-tree shared libraries as the LIBRARIES argument, and the
9269 build-tree modules as the MODULES argument. On macOS, if one of the ex‐
9270 ecutables is a MACOSX_BUNDLE, that executable is passed as the BUN‐
9271 DLE_EXECUTABLE argument. At most one such bundle executable may be in
9272 the runtime dependency set on macOS. The MACOSX_BUNDLE property has no
9273 effect on other platforms. Note that file(GET_RUNTIME_DEPENDENCIES)
9274 only supports collecting the runtime dependencies for Windows, Linux
9275 and macOS platforms, so install(RUNTIME_DEPENDENCY_SET) has the same
9276 limitation.
9277 The following sub-arguments are forwarded through as the corresponding
9279 arguments to file(GET_RUNTIME_DEPENDENCIES) (for those that provide a
9280 non-empty list of directories, regular expressions or files). They all
9281 support generator expressions.
9282 • DIRECTORIES <directories>
9284 • PRE_INCLUDE_REGEXES <regexes>
9286 • PRE_EXCLUDE_REGEXES <regexes>
9288 • POST_INCLUDE_REGEXES <regexes>
9290 • POST_EXCLUDE_REGEXES <regexes>
9292 • POST_INCLUDE_FILES <files>
9294 • POST_EXCLUDE_FILES <files>
9296 Generated Installation Script
9298 NOTE:
9299 Use of this feature is not recommended. Please consider using the
9300 --install argument of cmake(1) instead.
9301 The install() command generates a file, cmake_install.cmake, inside the
9303 build directory, which is used internally by the generated install tar‐
9304 get and by CPack. You can also invoke this script manually with cmake
9305 -P. This script accepts several variables:
9306 COMPONENT
9308 Set this variable to install only a single CPack component as
9309 opposed to all of them. For example, if you only want to install
9310 the Development component, run cmake -DCOMPONENT=Development -P
9311 cmake_install.cmake.
9312 BUILD_TYPE
9314 Set this variable to change the build type if you are using a
9315 multi-config generator. For example, to install with the Debug
9316 configuration, run cmake -DBUILD_TYPE=Debug -P cmake_in‐
9317 stall.cmake.
9318 DESTDIR
9320 This is an environment variable rather than a CMake variable. It
9321 allows you to change the installation prefix on UNIX systems.
9322 See DESTDIR for details.
9323 link_directories
9325 Add directories in which the linker will look for libraries.
9326 link_directories([AFTER|BEFORE] directory1 [directory2 ...])
9328 Adds the paths in which the linker should search for libraries. Rela‐
9330 tive paths given to this command are interpreted as relative to the
9331 current source directory, see CMP0015.
9332 The command will apply only to targets created after it is called.
9334 New in version 3.13: The directories are added to the LINK_DIRECTORIES
9336 directory property for the current CMakeLists.txt file, converting rel‐
9337 ative paths to absolute as needed. See the cmake-buildsystem(7) manual
9338 for more on defining buildsystem properties.
9339 New in version 3.13: By default the directories specified are appended
9342 onto the current list of directories. This default behavior can be
9343 changed by setting CMAKE_LINK_DIRECTORIES_BEFORE to ON. By using AFTER
9344 or BEFORE explicitly, you can select between appending and prepending,
9345 independent of the default.
9346 New in version 3.13: Arguments to link_directories may use "generator
9349 expressions" with the syntax "$<...>". See the cmake-generator-expres‐
9350 sions(7) manual for available expressions.
9351 NOTE:
9354 This command is rarely necessary and should be avoided where there
9355 are other choices. Prefer to pass full absolute paths to libraries
9356 where possible, since this ensures the correct library will always
9357 be linked. The find_library() command provides the full path, which
9358 can generally be used directly in calls to target_link_libraries().
9359 Situations where a library search path may be needed include:
9360 • Project generators like Xcode where the user can switch target ar‐
9362 chitecture at build time, but a full path to a library cannot be
9363 used because it only provides one architecture (i.e. it is not a
9364 universal binary).
9365 • Libraries may themselves have other private library dependencies
9367 that expect to be found via RPATH mechanisms, but some linkers are
9368 not able to fully decode those paths (e.g. due to the presence of
9369 things like $ORIGIN).
9370 If a library search path must be provided, prefer to localize the
9372 effect where possible by using the target_link_directories() command
9373 rather than link_directories(). The target-specific command can
9374 also control how the search directories propagate to other dependent
9375 targets.
9376 link_libraries
9378 Link libraries to all targets added later.
9379 link_libraries([item1 [item2 [...]]]
9381 [[debug|optimized|general] <item>] ...)
9382 Specify libraries or flags to use when linking any targets created
9384 later in the current directory or below by commands such as add_exe‐
9385 cutable() or add_library(). See the target_link_libraries() command
9386 for meaning of arguments.
9387 NOTE:
9389 The target_link_libraries() command should be preferred whenever
9390 possible. Library dependencies are chained automatically, so direc‐
9391 tory-wide specification of link libraries is rarely needed.
9392 load_cache
9394 Load in the values from another project's CMake cache.
9395 load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...)
9397 Reads the cache and store the requested entries in variables with their
9399 name prefixed with the given prefix. This only reads the values, and
9400 does not create entries in the local project's cache.
9401 load_cache(pathToBuildDirectory [EXCLUDE entry1...]
9403 [INCLUDE_INTERNALS entry1...])
9404 Loads in the values from another cache and store them in the local
9406 project's cache as internal entries. This is useful for a project that
9407 depends on another project built in a different tree. EXCLUDE option
9408 can be used to provide a list of entries to be excluded. INCLUDE_IN‐
9409 TERNALS can be used to provide a list of internal entries to be in‐
9410 cluded. Normally, no internal entries are brought in. Use of this
9411 form of the command is strongly discouraged, but it is provided for
9412 backward compatibility.
9413 project
9415 Set the name of the project.
9416 Synopsis
9418 project(<PROJECT-NAME> [<language-name>...])
9419 project(<PROJECT-NAME>
9420 [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
9421 [DESCRIPTION <project-description-string>]
9422 [HOMEPAGE_URL <url-string>]
9423 [LANGUAGES <language-name>...])
9424 Sets the name of the project, and stores it in the variable
9426 PROJECT_NAME. When called from the top-level CMakeLists.txt also stores
9427 the project name in the variable CMAKE_PROJECT_NAME.
9428 Also sets the variables:
9430 PROJECT_SOURCE_DIR, <PROJECT-NAME>_SOURCE_DIR
9432 Absolute path to the source directory for the project.
9433 PROJECT_BINARY_DIR, <PROJECT-NAME>_BINARY_DIR
9435 Absolute path to the binary directory for the project.
9436 PROJECT_IS_TOP_LEVEL, <PROJECT-NAME>_IS_TOP_LEVEL
9438 New in version 3.21.
9439 Boolean value indicating whether the project is top-level.
9442 Further variables are set by the optional arguments described in the
9444 following. If any of these arguments is not used, then the correspond‐
9445 ing variables are set to the empty string.
9446 Options
9448 The options are:
9449 VERSION <version>
9451 Optional; may not be used unless policy CMP0048 is set to NEW.
9452 Takes a <version> argument composed of non-negative integer com‐
9454 ponents, i.e. <major>[.<minor>[.<patch>[.<tweak>]]], and sets
9455 the variables
9456 • PROJECT_VERSION, <PROJECT-NAME>_VERSION
9458 • PROJECT_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MAJOR
9460 • PROJECT_VERSION_MINOR, <PROJECT-NAME>_VERSION_MINOR
9462 • PROJECT_VERSION_PATCH, <PROJECT-NAME>_VERSION_PATCH
9464 • PROJECT_VERSION_TWEAK, <PROJECT-NAME>_VERSION_TWEAK.
9466 New in version 3.12: When the project() command is called from
9468 the top-level CMakeLists.txt, then the version is also stored in
9469 the variable CMAKE_PROJECT_VERSION.
9470 DESCRIPTION <project-description-string>
9473 New in version 3.9.
9474 Optional. Sets the variables
9477 • PROJECT_DESCRIPTION, <PROJECT-NAME>_DESCRIPTION
9479 to <project-description-string>. It is recommended that this
9481 description is a relatively short string, usually no more than a
9482 few words.
9483 When the project() command is called from the top-level CMake‐
9485 Lists.txt, then the description is also stored in the variable
9486 CMAKE_PROJECT_DESCRIPTION.
9487 New in version 3.12: Added the <PROJECT-NAME>_DESCRIPTION vari‐
9489 able.
9490 HOMEPAGE_URL <url-string>
9493 New in version 3.12.
9494 Optional. Sets the variables
9497 • PROJECT_HOMEPAGE_URL, <PROJECT-NAME>_HOMEPAGE_URL
9499 to <url-string>, which should be the canonical home URL for the
9501 project.
9502 When the project() command is called from the top-level CMake‐
9504 Lists.txt, then the URL also is stored in the variable
9505 CMAKE_PROJECT_HOMEPAGE_URL.
9506 LANGUAGES <language-name>...
9508 Optional. Can also be specified without LANGUAGES keyword per
9509 the first, short signature.
9510 Selects which programming languages are needed to build the
9512 project. Supported languages include C, CXX (i.e. C++), CUDA,
9513 OBJC (i.e. Objective-C), OBJCXX, Fortran, HIP, ISPC, and ASM.
9514 By default C and CXX are enabled if no language options are
9515 given. Specify language NONE, or use the LANGUAGES keyword and
9516 list no languages, to skip enabling any languages.
9517 New in version 3.8: Added CUDA support.
9519 New in version 3.16: Added OBJC and OBJCXX support.
9522 New in version 3.18: Added ISPC support.
9525 If enabling ASM, list it last so that CMake can check whether
9528 compilers for other languages like C work for assembly too.
9529 The variables set through the VERSION, DESCRIPTION and HOMEPAGE_URL op‐
9531 tions are intended for use as default values in package metadata and
9532 documentation.
9533 Code Injection
9535 If the CMAKE_PROJECT_INCLUDE_BEFORE or CMAKE_PROJECT_<PROJECT-NAME>_IN‐
9536 CLUDE_BEFORE variables are set, the files they point to will be in‐
9537 cluded as the first step of the project() command. If both are set,
9538 then CMAKE_PROJECT_INCLUDE_BEFORE will be included before
9539 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE.
9540 If the CMAKE_PROJECT_INCLUDE or CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE
9542 variables are set, the files they point to will be included as the last
9543 step of the project() command. If both are set, then CMAKE_PROJECT_IN‐
9544 CLUDE will be included before CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE.
9545 New in version 3.15: Added the CMAKE_PROJECT_INCLUDE and
9547 CMAKE_PROJECT_INCLUDE_BEFORE variables.
9548 New in version 3.17: Added the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BE‐
9551 FORE variable.
9552 Usage
9555 The top-level CMakeLists.txt file for a project must contain a literal,
9556 direct call to the project() command; loading one through the include()
9557 command is not sufficient. If no such call exists, CMake will issue a
9558 warning and pretend there is a project(Project) at the top to enable
9559 the default languages (C and CXX).
9560 NOTE:
9562 Call the project() command near the top of the top-level CMake‐
9563 Lists.txt, but after calling cmake_minimum_required(). It is impor‐
9564 tant to establish version and policy settings before invoking other
9565 commands whose behavior they may affect. See also policy CMP0000.
9566 remove_definitions
9568 Remove -D define flags added by add_definitions().
9569 remove_definitions(-DFOO -DBAR ...)
9571 Removes flags (added by add_definitions()) from the compiler command
9573 line for sources in the current directory and below.
9574 set_source_files_properties
9576 Source files can have properties that affect how they are built.
9577 set_source_files_properties(<files> ...
9579 [DIRECTORY <dirs> ...]
9580 [TARGET_DIRECTORY <targets> ...]
9581 PROPERTIES <prop1> <value1>
9582 [<prop2> <value2>] ...)
9583 Sets properties associated with source files using a key/value paired
9585 list.
9586 New in version 3.18: By default, source file properties are only visi‐
9588 ble to targets added in the same directory (CMakeLists.txt). Visibil‐
9589 ity can be set in other directory scopes using one or both of the fol‐
9590 lowing options:
9591 DIRECTORY <dirs>...
9594 The source file properties will be set in each of the <dirs> di‐
9595 rectories' scopes. CMake must already know about each of these
9596 source directories, either by having added them through a call
9597 to add_subdirectory() or it being the top level source direc‐
9598 tory. Relative paths are treated as relative to the current
9599 source directory.
9600 TARGET_DIRECTORY <targets>...
9602 The source file properties will be set in each of the directory
9603 scopes where any of the specified <targets> were created (the
9604 <targets> must therefore already exist).
9605 Use get_source_file_property() to get property values. See also the
9607 set_property(SOURCE) command.
9608 See Source File Properties for the list of properties known to CMake.
9610 NOTE:
9612 The GENERATED source file property may be globally visible. See its
9613 documentation for details.
9614 set_target_properties
9616 Targets can have properties that affect how they are built.
9617 set_target_properties(target1 target2 ...
9619 PROPERTIES prop1 value1
9620 prop2 value2 ...)
9621 Sets properties on targets. The syntax for the command is to list all
9623 the targets you want to change, and then provide the values you want to
9624 set next. You can use any prop value pair you want and extract it
9625 later with the get_property() or get_target_property() command.
9626 See also the set_property(TARGET) command.
9628 See Target Properties for the list of properties known to CMake.
9630 set_tests_properties
9632 Set a property of the tests.
9633 set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
9635 Sets a property for the tests. If the test is not found, CMake will
9637 report an error. Generator expressions will be expanded the same as
9638 supported by the test's add_test() call.
9639 See also the set_property(TEST) command.
9641 See Test Properties for the list of properties known to CMake.
9643 source_group
9645 Define a grouping for source files in IDE project generation. There
9646 are two different signatures to create source groups.
9647 source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
9649 source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...])
9650 Defines a group into which sources will be placed in project files.
9652 This is intended to set up file tabs in Visual Studio. The group is
9653 scoped in the directory where the command is called, and applies to
9654 sources in targets created in that directory.
9655 The options are:
9657 TREE New in version 3.8.
9659 CMake will automatically detect, from <src> files paths, source
9662 groups it needs to create, to keep structure of source groups
9663 analogically to the actual files and directories structure in
9664 the project. Paths of <src> files will be cut to be relative to
9665 <root>. The command fails if the paths within src do not start
9666 with root.
9667 PREFIX New in version 3.8.
9669 Source group and files located directly in <root> path, will be
9672 placed in <prefix> source groups.
9673 FILES Any source file specified explicitly will be placed in group
9675 <name>. Relative paths are interpreted with respect to the cur‐
9676 rent source directory.
9677 REGULAR_EXPRESSION
9679 Any source file whose name matches the regular expression will
9680 be placed in group <name>.
9681 If a source file matches multiple groups, the last group that explic‐
9683 itly lists the file with FILES will be favored, if any. If no group
9684 explicitly lists the file, the last group whose regular expression
9685 matches the file will be favored.
9686 The <name> of the group and <prefix> argument may contain forward
9688 slashes or backslashes to specify subgroups. Backslashes need to be
9689 escaped appropriately:
9690 source_group(base/subdir ...)
9692 source_group(outer\\inner ...)
9693 source_group(TREE <root> PREFIX sources\\inc ...)
9694 New in version 3.18: Allow using forward slashes (/) to specify sub‐
9696 groups.
9697 For backwards compatibility, the short-hand signature
9700 source_group(<name> <regex>)
9702 is equivalent to
9704 source_group(<name> REGULAR_EXPRESSION <regex>)
9706 target_compile_definitions
9708 Add compile definitions to a target.
9709 target_compile_definitions(<target>
9711 <INTERFACE|PUBLIC|PRIVATE> [items1...]
9712 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
9713 Specifies compile definitions to use when compiling a given <target>.
9715 The named <target> must have been created by a command such as add_exe‐
9716 cutable() or add_library() and must not be an ALIAS target.
9717 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9719 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
9720 late the COMPILE_DEFINITIONS property of <target>. PUBLIC and INTERFACE
9721 items will populate the INTERFACE_COMPILE_DEFINITIONS property of <tar‐
9722 get>. The following arguments specify compile definitions. Repeated
9723 calls for the same <target> append items in the order called.
9724 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
9726 Arguments to target_compile_definitions may use "generator expressions"
9729 with the syntax $<...>. See the cmake-generator-expressions(7) manual
9730 for available expressions. See the cmake-buildsystem(7) manual for
9731 more on defining buildsystem properties.
9732 Any leading -D on an item will be removed. Empty items are ignored.
9734 For example, the following are all equivalent:
9735 target_compile_definitions(foo PUBLIC FOO)
9737 target_compile_definitions(foo PUBLIC -DFOO) # -D removed
9738 target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
9739 target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
9740 Definitions may optionally have values:
9742 target_compile_definitions(foo PUBLIC FOO=1)
9744 Note that many compilers treat -DFOO as equivalent to -DFOO=1, but
9746 other tools may not recognize this in all circumstances (e.g. Intel‐
9747 liSense).
9748 target_compile_features
9750 New in version 3.1.
9751 Add expected compiler features to a target.
9754 target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
9756 Specifies compiler features required when compiling a given target. If
9758 the feature is not listed in the CMAKE_C_COMPILE_FEATURES,
9759 CMAKE_CUDA_COMPILE_FEATURES, or CMAKE_CXX_COMPILE_FEATURES variables,
9760 then an error will be reported by CMake. If the use of the feature re‐
9761 quires an additional compiler flag, such as -std=gnu++11, the flag will
9762 be added automatically.
9763 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9765 scope of the features. PRIVATE and PUBLIC items will populate the COM‐
9766 PILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
9767 populate the INTERFACE_COMPILE_FEATURES property of <target>. Repeated
9768 calls for the same <target> append items.
9769 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
9771 The named <target> must have been created by a command such as add_exe‐
9774 cutable() or add_library() and must not be an ALIAS target.
9775 Arguments to target_compile_features may use "generator expressions"
9777 with the syntax $<...>. See the cmake-generator-expressions(7) manual
9778 for available expressions. See the cmake-compile-features(7) manual
9779 for information on compile features and a list of supported compilers.
9780 target_compile_options
9782 Add compile options to a target.
9783 target_compile_options(<target> [BEFORE]
9785 <INTERFACE|PUBLIC|PRIVATE> [items1...]
9786 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
9787 Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
9789 properties. These options are used when compiling the given <target>,
9790 which must have been created by a command such as add_executable() or
9791 add_library() and must not be an ALIAS target.
9792 Arguments
9794 If BEFORE is specified, the content will be prepended to the property
9795 instead of being appended.
9796 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9798 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
9799 late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
9800 items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
9801 The following arguments specify compile options. Repeated calls for
9802 the same <target> append items in the order called.
9803 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
9805 Arguments to target_compile_options may use "generator expressions"
9808 with the syntax $<...>. See the cmake-generator-expressions(7) manual
9809 for available expressions. See the cmake-buildsystem(7) manual for
9810 more on defining buildsystem properties.
9811 Option De-duplication
9813 The final set of options used for a target is constructed by accumulat‐
9814 ing options from the current target and the usage requirements of its
9815 dependencies. The set of options is de-duplicated to avoid repetition.
9816 New in version 3.12: While beneficial for individual options, the
9818 de-duplication step can break up option groups. For example, -option A
9819 -option B becomes -option A B. One may specify a group of options us‐
9820 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
9821 is dropped, and the rest of the option string is parsed using the sepa‐
9822 rate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
9823 "SHELL:-option B" becomes -option A -option B.
9824 See Also
9827 This command can be used to add any options. However, for adding pre‐
9828 processor definitions and include directories it is recommended to use
9829 the more specific commands target_compile_definitions() and target_in‐
9830 clude_directories().
9831 For directory-wide settings, there is the command add_compile_op‐
9833 tions().
9834 For file-specific settings, there is the source file property COM‐
9836 PILE_OPTIONS.
9837 target_include_directories
9839 Add include directories to a target.
9840 target_include_directories(<target> [SYSTEM] [AFTER|BEFORE]
9842 <INTERFACE|PUBLIC|PRIVATE> [items1...]
9843 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
9844 Specifies include directories to use when compiling a given target.
9846 The named <target> must have been created by a command such as add_exe‐
9847 cutable() or add_library() and must not be an ALIAS target.
9848 By using AFTER or BEFORE explicitly, you can select between appending
9850 and prepending, independent of the default.
9851 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9853 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
9854 late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTER‐
9855 FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
9856 <target>. The following arguments specify include directories.
9857 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
9859 Specified include directories may be absolute paths or relative paths.
9862 Repeated calls for the same <target> append items in the order called.
9863 If SYSTEM is specified, the compiler will be told the directories are
9864 meant as system include directories on some platforms (signalling this
9865 setting might achieve effects such as the compiler skipping warnings,
9866 or these fixed-install system files not being considered in dependency
9867 calculations - see compiler docs). If SYSTEM is used together with
9868 PUBLIC or INTERFACE, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
9869 property will be populated with the specified directories.
9870 Arguments to target_include_directories may use "generator expressions"
9872 with the syntax $<...>. See the cmake-generator-expressions(7) manual
9873 for available expressions. See the cmake-buildsystem(7) manual for
9874 more on defining buildsystem properties.
9875 Include directories usage requirements commonly differ between the
9877 build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN‐
9878 TERFACE generator expressions can be used to describe separate usage
9879 requirements based on the usage location. Relative paths are allowed
9880 within the INSTALL_INTERFACE expression and are interpreted relative to
9881 the installation prefix. For example:
9882 target_include_directories(mylib PUBLIC
9884 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
9885 $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
9886 )
9887 Creating Relocatable Packages
9889 Note that it is not advisable to populate the INSTALL_INTERFACE of the
9890 INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
9891 include directories of dependencies. That would hard-code into in‐
9892 stalled packages the include directory paths for dependencies as found
9893 on the machine the package was made on.
9894 The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
9896 suitable for specifying the required include directories for headers
9897 provided with the target itself, not those provided by the transitive
9898 dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
9899 Those dependencies should themselves be targets that specify their own
9900 header locations in INTERFACE_INCLUDE_DIRECTORIES.
9901 See the Creating Relocatable Packages section of the cmake-packages(7)
9903 manual for discussion of additional care that must be taken when speci‐
9904 fying usage requirements while creating packages for redistribution.
9905 target_link_directories
9907 New in version 3.13.
9908 Add link directories to a target.
9911 target_link_directories(<target> [BEFORE]
9913 <INTERFACE|PUBLIC|PRIVATE> [items1...]
9914 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
9915 Specifies the paths in which the linker should search for libraries
9917 when linking a given target. Each item can be an absolute or relative
9918 path, with the latter being interpreted as relative to the current
9919 source directory. These items will be added to the link command.
9920 The named <target> must have been created by a command such as add_exe‐
9922 cutable() or add_library() and must not be an ALIAS target.
9923 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9925 scope of the items that follow them. PRIVATE and PUBLIC items will
9926 populate the LINK_DIRECTORIES property of <target>. PUBLIC and INTER‐
9927 FACE items will populate the INTERFACE_LINK_DIRECTORIES property of
9928 <target> (IMPORTED targets only support INTERFACE items). Each item
9929 specifies a link directory and will be converted to an absolute path if
9930 necessary before adding it to the relevant property. Repeated calls
9931 for the same <target> append items in the order called.
9932 If BEFORE is specified, the content will be prepended to the relevant
9934 property instead of being appended.
9935 Arguments to target_link_directories may use "generator expressions"
9937 with the syntax $<...>. See the cmake-generator-expressions(7) manual
9938 for available expressions. See the cmake-buildsystem(7) manual for
9939 more on defining buildsystem properties.
9940 NOTE:
9942 This command is rarely necessary and should be avoided where there
9943 are other choices. Prefer to pass full absolute paths to libraries
9944 where possible, since this ensures the correct library will always
9945 be linked. The find_library() command provides the full path, which
9946 can generally be used directly in calls to target_link_libraries().
9947 Situations where a library search path may be needed include:
9948 • Project generators like Xcode where the user can switch target ar‐
9950 chitecture at build time, but a full path to a library cannot be
9951 used because it only provides one architecture (i.e. it is not a
9952 universal binary).
9953 • Libraries may themselves have other private library dependencies
9955 that expect to be found via RPATH mechanisms, but some linkers are
9956 not able to fully decode those paths (e.g. due to the presence of
9957 things like $ORIGIN).
9958 target_link_libraries
9960 Specify libraries or flags to use when linking a given target and/or
9961 its dependents. Usage requirements from linked library targets will be
9962 propagated. Usage requirements of a target's dependencies affect com‐
9963 pilation of its own sources.
9964 Overview
9966 This command has several signatures as detailed in subsections below.
9967 All of them have the general form
9968 target_link_libraries(<target> ... <item>... ...)
9970 The named <target> must have been created by a command such as add_exe‐
9972 cutable() or add_library() and must not be an ALIAS target. If policy
9973 CMP0079 is not set to NEW then the target must have been created in the
9974 current directory. Repeated calls for the same <target> append items
9975 in the order called.
9976 New in version 3.13: The <target> doesn't have to be defined in the
9978 same directory as the target_link_libraries call.
9979 Each <item> may be:
9982 • A library target name: The generated link line will have the full
9984 path to the linkable library file associated with the target. The
9985 buildsystem will have a dependency to re-link <target> if the library
9986 file changes.
9987 The named target must be created by add_library() within the project
9989 or as an IMPORTED library. If it is created within the project an
9990 ordering dependency will automatically be added in the build system
9991 to make sure the named library target is up-to-date before the <tar‐
9992 get> links.
9993 If an imported library has the IMPORTED_NO_SONAME target property
9995 set, CMake may ask the linker to search for the library instead of
9996 using the full path (e.g. /usr/lib/libfoo.so becomes -lfoo).
9997 The full path to the target's artifact will be quoted/escaped for the
9999 shell automatically.
10000 • A full path to a library file: The generated link line will normally
10002 preserve the full path to the file. The buildsystem will have a de‐
10003 pendency to re-link <target> if the library file changes.
10004 There are some cases where CMake may ask the linker to search for the
10006 library (e.g. /usr/lib/libfoo.so becomes -lfoo), such as when a
10007 shared library is detected to have no SONAME field. See policy
10008 CMP0060 for discussion of another case.
10009 If the library file is in a macOS framework, the Headers directory of
10011 the framework will also be processed as a usage requirement. This
10012 has the same effect as passing the framework directory as an include
10013 directory.
10014 New in version 3.8: On Visual Studio Generators for VS 2010 and
10016 above, library files ending in .targets will be treated as MSBuild
10017 targets files and imported into generated project files. This is not
10018 supported by other generators.
10019 The full path to the library file will be quoted/escaped for the
10022 shell automatically.
10023 • A plain library name: The generated link line will ask the linker to
10025 search for the library (e.g. foo becomes -lfoo or foo.lib).
10026 The library name/flag is treated as a command-line string fragment
10028 and will be used with no extra quoting or escaping.
10029 • A link flag: Item names starting with -, but not -l or -framework,
10031 are treated as linker flags. Note that such flags will be treated
10032 like any other library link item for purposes of transitive dependen‐
10033 cies, so they are generally safe to specify only as private link
10034 items that will not propagate to dependents.
10035 Link flags specified here are inserted into the link command in the
10037 same place as the link libraries. This might not be correct, depend‐
10038 ing on the linker. Use the LINK_OPTIONS target property or tar‐
10039 get_link_options() command to add link flags explicitly. The flags
10040 will then be placed at the toolchain-defined flag position in the
10041 link command.
10042 New in version 3.13: LINK_OPTIONS target property and target_link_op‐
10044 tions() command. For earlier versions of CMake, use LINK_FLAGS prop‐
10045 erty instead.
10046 The link flag is treated as a command-line string fragment and will
10049 be used with no extra quoting or escaping.
10050 • A generator expression: A $<...> generator expression may evaluate to
10052 any of the above items or to a semicolon-separated list of them. If
10053 the ... contains any ; characters, e.g. after evaluation of a ${list}
10054 variable, be sure to use an explicitly quoted argument "$<...>" so
10055 that this command receives it as a single <item>.
10056 Additionally, a generator expression may be used as a fragment of any
10058 of the above items, e.g. foo$<1:_d>.
10059 Note that generator expressions will not be used in OLD handling of
10061 policy CMP0003 or policy CMP0004.
10062 • A debug, optimized, or general keyword immediately followed by an‐
10064 other <item>. The item following such a keyword will be used only
10065 for the corresponding build configuration. The debug keyword corre‐
10066 sponds to the Debug configuration (or to configurations named in the
10067 DEBUG_CONFIGURATIONS global property if it is set). The optimized
10068 keyword corresponds to all other configurations. The general keyword
10069 corresponds to all configurations, and is purely optional. Higher
10070 granularity may be achieved for per-configuration rules by creating
10071 and linking to IMPORTED library targets. These keywords are inter‐
10072 preted immediately by this command and therefore have no special
10073 meaning when produced by a generator expression.
10074 Items containing ::, such as Foo::Bar, are assumed to be IMPORTED or
10076 ALIAS library target names and will cause an error if no such target
10077 exists. See policy CMP0028.
10078 See the cmake-buildsystem(7) manual for more on defining buildsystem
10080 properties.
10081 Libraries for a Target and/or its Dependents
10083 target_link_libraries(<target>
10084 <PRIVATE|PUBLIC|INTERFACE> <item>...
10085 [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
10086 The PUBLIC, PRIVATE and INTERFACE keywords can be used to specify both
10088 the link dependencies and the link interface in one command. Libraries
10089 and targets following PUBLIC are linked to, and are made part of the
10090 link interface. Libraries and targets following PRIVATE are linked to,
10091 but are not made part of the link interface. Libraries following IN‐
10092 TERFACE are appended to the link interface and are not used for linking
10093 <target>.
10094 Libraries for both a Target and its Dependents
10096 target_link_libraries(<target> <item>...)
10097 Library dependencies are transitive by default with this signature.
10099 When this target is linked into another target then the libraries
10100 linked to this target will appear on the link line for the other target
10101 too. This transitive "link interface" is stored in the INTER‐
10102 FACE_LINK_LIBRARIES target property and may be overridden by setting
10103 the property directly. When CMP0022 is not set to NEW, transitive
10104 linking is built in but may be overridden by the LINK_INTERFACE_LI‐
10105 BRARIES property. Calls to other signatures of this command may set
10106 the property making any libraries linked exclusively by this signature
10107 private.
10108 Libraries for a Target and/or its Dependents (Legacy)
10110 target_link_libraries(<target>
10111 <LINK_PRIVATE|LINK_PUBLIC> <lib>...
10112 [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
10113 The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both the
10115 link dependencies and the link interface in one command.
10116 This signature is for compatibility only. Prefer the PUBLIC or PRIVATE
10118 keywords instead.
10119 Libraries and targets following LINK_PUBLIC are linked to, and are made
10121 part of the INTERFACE_LINK_LIBRARIES. If policy CMP0022 is not NEW,
10122 they are also made part of the LINK_INTERFACE_LIBRARIES. Libraries and
10123 targets following LINK_PRIVATE are linked to, but are not made part of
10124 the INTERFACE_LINK_LIBRARIES (or LINK_INTERFACE_LIBRARIES).
10125 Libraries for Dependents Only (Legacy)
10127 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
10128 The LINK_INTERFACE_LIBRARIES mode appends the libraries to the INTER‐
10130 FACE_LINK_LIBRARIES target property instead of using them for linking.
10131 If policy CMP0022 is not NEW, then this mode also appends libraries to
10132 the LINK_INTERFACE_LIBRARIES and its per-configuration equivalent.
10133 This signature is for compatibility only. Prefer the INTERFACE mode
10135 instead.
10136 Libraries specified as debug are wrapped in a generator expression to
10138 correspond to debug builds. If policy CMP0022 is not NEW, the li‐
10139 braries are also appended to the LINK_INTERFACE_LIBRARIES_DEBUG prop‐
10140 erty (or to the properties corresponding to configurations listed in
10141 the DEBUG_CONFIGURATIONS global property if it is set). Libraries
10142 specified as optimized are appended to the INTERFACE_LINK_LIBRARIES
10143 property. If policy CMP0022 is not NEW, they are also appended to the
10144 LINK_INTERFACE_LIBRARIES property. Libraries specified as general (or
10145 without any keyword) are treated as if specified for both debug and op‐
10146 timized.
10147 Linking Object Libraries
10149 New in version 3.12.
10150 Object Libraries may be used as the <target> (first) argument of tar‐
10153 get_link_libraries to specify dependencies of their sources on other
10154 libraries. For example, the code
10155 add_library(A SHARED a.c)
10157 target_compile_definitions(A PUBLIC A)
10158 add_library(obj OBJECT obj.c)
10160 target_compile_definitions(obj PUBLIC OBJ)
10161 target_link_libraries(obj PUBLIC A)
10162 compiles obj.c with -DA -DOBJ and establishes usage requirements for
10164 obj that propagate to its dependents.
10165 Normal libraries and executables may link to Object Libraries to get
10167 their objects and usage requirements. Continuing the above example,
10168 the code
10169 add_library(B SHARED b.c)
10171 target_link_libraries(B PUBLIC obj)
10172 compiles b.c with -DA -DOBJ, creates shared library B with object files
10174 from b.c and obj.c, and links B to A. Furthermore, the code
10175 add_executable(main main.c)
10177 target_link_libraries(main B)
10178 compiles main.c with -DA -DOBJ and links executable main to B and A.
10180 The object library's usage requirements are propagated transitively
10181 through B, but its object files are not.
10182 Object Libraries may "link" to other object libraries to get usage re‐
10184 quirements, but since they do not have a link step nothing is done with
10185 their object files. Continuing from the above example, the code:
10186 add_library(obj2 OBJECT obj2.c)
10188 target_link_libraries(obj2 PUBLIC obj)
10189 add_executable(main2 main2.c)
10191 target_link_libraries(main2 obj2)
10192 compiles obj2.c with -DA -DOBJ, creates executable main2 with object
10194 files from main2.c and obj2.c, and links main2 to A.
10195 In other words, when Object Libraries appear in a target's INTER‐
10197 FACE_LINK_LIBRARIES property they will be treated as Interface Li‐
10198 braries, but when they appear in a target's LINK_LIBRARIES property
10199 their object files will be included in the link too.
10200 Linking Object Libraries via $<TARGET_OBJECTS>
10202 New in version 3.21.
10203 The object files associated with an object library may be referenced by
10206 the $<TARGET_OBJECTS> generator expression. Such object files are
10207 placed on the link line before all libraries, regardless of their rela‐
10208 tive order. Additionally, an ordering dependency will be added to the
10209 build system to make sure the object library is up-to-date before the
10210 dependent target links. For example, the code
10211 add_library(obj3 OBJECT obj3.c)
10213 target_compile_definitions(obj3 PUBLIC OBJ3)
10214 add_executable(main3 main3.c)
10216 target_link_libraries(main3 PRIVATE a3 $<TARGET_OBJECTS:obj3> b3)
10217 links executable main3 with object files from main3.c and obj3.c fol‐
10219 lowed by the a3 and b3 libraries. main3.c is not compiled with usage
10220 requirements from obj3, such as -DOBJ3.
10221 This approach can be used to achieve transitive inclusion of object
10223 files in link lines as usage requirements. Continuing the above exam‐
10224 ple, the code
10225 add_library(iface_obj3 INTERFACE)
10227 target_link_libraries(iface_obj3 INTERFACE obj3 $<TARGET_OBJECTS:obj3>)
10228 creates an interface library iface_obj3 that forwards the obj3 usage
10230 requirements and adds the obj3 object files to dependents' link lines.
10231 The code
10232 add_executable(use_obj3 use_obj3.c)
10234 target_link_libraries(use_obj3 PRIVATE iface_obj3)
10235 compiles use_obj3.c with -DOBJ3 and links executable use_obj3 with ob‐
10237 ject files from use_obj3.c and obj3.c.
10238 This also works transitively through a static library. Since a static
10240 library does not link, it does not consume the object files from object
10241 libraries referenced this way. Instead, the object files become tran‐
10242 sitive link dependencies of the static library. Continuing the above
10243 example, the code
10244 add_library(static3 STATIC static3.c)
10246 target_link_libraries(static3 PRIVATE iface_obj3)
10247 add_executable(use_static3 use_static3.c)
10249 target_link_libraries(use_static3 PRIVATE static3)
10250 compiles static3.c with -DOBJ3 and creates libstatic3.a using only its
10252 own object file. use_static3.c is compiled without -DOBJ3 because the
10253 usage requirement is not transitive through the private dependency of
10254 static3. However, the link dependencies of static3 are propagated, in‐
10255 cluding the iface_obj3 reference to $<TARGET_OBJECTS:obj3>. The
10256 use_static3 executable is created with object files from use_static3.c
10257 and obj3.c, and linked to library libstatic3.a.
10258 When using this approach, it is the project's responsibility to avoid
10260 linking multiple dependent binaries to iface_obj3, because they will
10261 all get the obj3 object files on their link lines.
10262 NOTE:
10264 Referencing $<TARGET_OBJECTS> in target_link_libraries calls worked
10265 in versions of CMake prior to 3.21 for some cases, but was not fully
10266 supported:
10267 • It did not place the object files before libraries on link lines.
10269 • It did not add an ordering dependency on the object library.
10271 • It did not work in Xcode with multiple architectures.
10273 Cyclic Dependencies of Static Libraries
10275 The library dependency graph is normally acyclic (a DAG), but in the
10276 case of mutually-dependent STATIC libraries CMake allows the graph to
10277 contain cycles (strongly connected components). When another target
10278 links to one of the libraries, CMake repeats the entire connected com‐
10279 ponent. For example, the code
10280 add_library(A STATIC a.c)
10282 add_library(B STATIC b.c)
10283 target_link_libraries(A B)
10284 target_link_libraries(B A)
10285 add_executable(main main.c)
10286 target_link_libraries(main A)
10287 links main to A B A B. While one repetition is usually sufficient,
10289 pathological object file and symbol arrangements can require more. One
10290 may handle such cases by using the LINK_INTERFACE_MULTIPLICITY target
10291 property or by manually repeating the component in the last tar‐
10292 get_link_libraries call. However, if two archives are really so inter‐
10293 dependent they should probably be combined into a single archive, per‐
10294 haps by using Object Libraries.
10295 Creating Relocatable Packages
10297 Note that it is not advisable to populate the INTERFACE_LINK_LIBRARIES
10298 of a target with absolute paths to dependencies. That would hard-code
10299 into installed packages the library file paths for dependencies as
10300 found on the machine the package was made on.
10301 See the Creating Relocatable Packages section of the cmake-packages(7)
10303 manual for discussion of additional care that must be taken when speci‐
10304 fying usage requirements while creating packages for redistribution.
10305 target_link_options
10307 New in version 3.13.
10308 Add options to the link step for an executable, shared library or mod‐
10311 ule library target.
10312 target_link_options(<target> [BEFORE]
10314 <INTERFACE|PUBLIC|PRIVATE> [items1...]
10315 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
10316 The named <target> must have been created by a command such as add_exe‐
10318 cutable() or add_library() and must not be an ALIAS target.
10319 This command can be used to add any link options, but alternative com‐
10321 mands exist to add libraries (target_link_libraries() or link_li‐
10322 braries()). See documentation of the directory and target LINK_OPTIONS
10323 properties.
10324 NOTE:
10326 This command cannot be used to add options for static library tar‐
10327 gets, since they do not use a linker. To add archiver or MSVC li‐
10328 brarian flags, see the STATIC_LIBRARY_OPTIONS target property.
10329 If BEFORE is specified, the content will be prepended to the property
10331 instead of being appended.
10332 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
10334 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
10335 late the LINK_OPTIONS property of <target>. PUBLIC and INTERFACE items
10336 will populate the INTERFACE_LINK_OPTIONS property of <target>. The
10337 following arguments specify link options. Repeated calls for the same
10338 <target> append items in the order called.
10339 NOTE:
10341 IMPORTED targets only support INTERFACE items.
10342 Arguments to target_link_options may use "generator expressions" with
10344 the syntax $<...>. See the cmake-generator-expressions(7) manual for
10345 available expressions. See the cmake-buildsystem(7) manual for more on
10346 defining buildsystem properties.
10347 Host And Device Specific Link Options
10349 New in version 3.18: When a device link step is involved, which is con‐
10350 trolled by CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS
10351 properties and policy CMP0105, the raw options will be delivered to the
10352 host and device link steps (wrapped in -Xcompiler or equivalent for de‐
10353 vice link). Options wrapped with $<DEVICE_LINK:...> generator expres‐
10354 sion will be used only for the device link step. Options wrapped with
10355 $<HOST_LINK:...> generator expression will be used only for the host
10356 link step.
10357 Option De-duplication
10360 The final set of options used for a target is constructed by accumulat‐
10361 ing options from the current target and the usage requirements of its
10362 dependencies. The set of options is de-duplicated to avoid repetition.
10363 New in version 3.12: While beneficial for individual options, the
10365 de-duplication step can break up option groups. For example, -option A
10366 -option B becomes -option A B. One may specify a group of options us‐
10367 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
10368 is dropped, and the rest of the option string is parsed using the sepa‐
10369 rate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
10370 "SHELL:-option B" becomes -option A -option B.
10371 Handling Compiler Driver Differences
10374 To pass options to the linker tool, each compiler driver has its own
10375 syntax. The LINKER: prefix and , separator can be used to specify, in
10376 a portable way, options to pass to the linker tool. LINKER: is replaced
10377 by the appropriate driver option and , by the appropriate driver sepa‐
10378 rator. The driver prefix and driver separator are given by the values
10379 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAP‐
10380 PER_FLAG_SEP variables.
10381 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
10383 Clang and -Wl,-z,defs for GNU GCC.
10384 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
10386 sion.
10387 The LINKER: prefix supports, as an alternative syntax, specification of
10389 arguments using the SHELL: prefix and space as separator. The previous
10390 example then becomes "LINKER:SHELL:-z defs".
10391 NOTE:
10393 Specifying the SHELL: prefix anywhere other than at the beginning of
10394 the LINKER: prefix is not supported.
10395 target_precompile_headers
10397 New in version 3.16.
10398 Add a list of header files to precompile.
10401 Precompiling header files can speed up compilation by creating a par‐
10403 tially processed version of some header files, and then using that ver‐
10404 sion during compilations rather than repeatedly parsing the original
10405 headers.
10406 Main Form
10408 target_precompile_headers(<target>
10409 <INTERFACE|PUBLIC|PRIVATE> [header1...]
10410 [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])
10411 The command adds header files to the PRECOMPILE_HEADERS and/or INTER‐
10413 FACE_PRECOMPILE_HEADERS target properties of <target>. The named <tar‐
10414 get> must have been created by a command such as add_executable() or
10415 add_library() and must not be an ALIAS target.
10416 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
10418 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
10419 late the PRECOMPILE_HEADERS property of <target>. PUBLIC and INTERFACE
10420 items will populate the INTERFACE_PRECOMPILE_HEADERS property of <tar‐
10421 get> (IMPORTED targets only support INTERFACE items). Repeated calls
10422 for the same <target> will append items in the order called.
10423 Projects should generally avoid using PUBLIC or INTERFACE for targets
10425 that will be exported, or they should at least use the $<BUILD_INTER‐
10426 FACE:...> generator expression to prevent precompile headers from ap‐
10427 pearing in an installed exported target. Consumers of a target should
10428 typically be in control of what precompile headers they use, not have
10429 precompile headers forced on them by the targets being consumed (since
10430 precompile headers are not typically usage requirements). A notable
10431 exception to this is where an interface library is created to define a
10432 commonly used set of precompile headers in one place and then other
10433 targets link to that interface library privately. In this case, the
10434 interface library exists specifically to propagate the precompile head‐
10435 ers to its consumers and the consumer is effectively still in control,
10436 since it decides whether to link to the interface library or not.
10437 The list of header files is used to generate a header file named
10439 cmake_pch.h|xx which is used to generate the precompiled header file
10440 (.pch, .gch, .pchi) artifact. The cmake_pch.h|xx header file will be
10441 force included (-include for GCC, /FI for MSVC) to all source files, so
10442 sources do not need to have #include "pch.h".
10443 Header file names specified with angle brackets (e.g. <unordered_map>)
10445 or explicit double quotes (escaped for the cmake-language(7), e.g.
10446 [["other_header.h"]]) will be treated as is, and include directories
10447 must be available for the compiler to find them. Other header file
10448 names (e.g. project_header.h) are interpreted as being relative to the
10449 current source directory (e.g. CMAKE_CURRENT_SOURCE_DIR) and will be
10450 included by absolute path. For example:
10451 target_precompile_headers(myTarget
10453 PUBLIC
10454 project_header.h
10455 PRIVATE
10456 [["other_header.h"]]
10457 <unordered_map>
10458 )
10459 Arguments to target_precompile_headers() may use "generator expres‐
10461 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
10462 manual for available expressions. The $<COMPILE_LANGUAGE:...> genera‐
10463 tor expression is particularly useful for specifying a language-spe‐
10464 cific header to precompile for only one language (e.g. CXX and not C).
10465 In this case, header file names that are not explicitly in double
10466 quotes or angle brackets must be specified by absolute path. Also,
10467 when specifying angle brackets inside a generator expression, be sure
10468 to encode the closing > as $<ANGLE-R>. For example:
10469 target_precompile_headers(mylib PRIVATE
10471 "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/cxx_only.h>"
10472 "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
10473 "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
10474 )
10475 Reusing Precompile Headers
10477 The command also supports a second signature which can be used to spec‐
10478 ify that one target re-uses a precompiled header file artifact from an‐
10479 other target instead of generating its own:
10480 target_precompile_headers(<target> REUSE_FROM <other_target>)
10482 This form sets the PRECOMPILE_HEADERS_REUSE_FROM property to
10484 <other_target> and adds a dependency such that <target> will depend on
10485 <other_target>. CMake will halt with an error if the PRECOMPILE_HEAD‐
10486 ERS property of <target> is already set when the REUSE_FROM form is
10487 used.
10488 NOTE:
10490 The REUSE_FROM form requires the same set of compiler options, com‐
10491 piler flags and compiler definitions for both <target> and
10492 <other_target>. Some compilers (e.g. GCC) may issue a warning if
10493 the precompiled header file cannot be used (-Winvalid-pch).
10494 See Also
10496 To disable precompile headers for specific targets, see the DIS‐
10497 ABLE_PRECOMPILE_HEADERS target property.
10498 To prevent precompile headers from being used when compiling a specific
10500 source file, see the SKIP_PRECOMPILE_HEADERS source file property.
10501 target_sources
10503 New in version 3.1.
10504 Add sources to a target.
10507 target_sources(<target>
10509 <INTERFACE|PUBLIC|PRIVATE> [items1...]
10510 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
10511 Specifies sources to use when building a target and/or its dependents.
10513 The named <target> must have been created by a command such as add_exe‐
10514 cutable() or add_library() or add_custom_target() and must not be an
10515 ALIAS target.
10516 Changed in version 3.13: Relative source file paths are interpreted as
10518 being relative to the current source directory (i.e. CMAKE_CUR‐
10519 RENT_SOURCE_DIR). See policy CMP0076.
10520 New in version 3.20: <target> can be a custom target.
10523 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
10526 scope of the items following them. PRIVATE and PUBLIC items will popu‐
10527 late the SOURCES property of <target>, which are used when building the
10528 target itself. PUBLIC and INTERFACE items will populate the INTER‐
10529 FACE_SOURCES property of <target>, which are used when building depen‐
10530 dents. The following arguments specify sources. Repeated calls for
10531 the same <target> append items in the order called. The targets created
10532 by add_custom_target() can only have PRIVATE scope.
10533 New in version 3.3: Allow exporting targets with INTERFACE_SOURCES.
10535 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
10538 Arguments to target_sources may use "generator expressions" with the
10541 syntax $<...>. See the cmake-generator-expressions(7) manual for avail‐
10542 able expressions. See the cmake-buildsystem(7) manual for more on
10543 defining buildsystem properties.
10544 try_compile
10546 Try building some code.
10547 Try Compiling Whole Projects
10549 try_compile(<resultVar> <bindir> <srcdir>
10550 <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
10551 [OUTPUT_VARIABLE <var>])
10552 Try building a project. The success or failure of the try_compile,
10554 i.e. TRUE or FALSE respectively, is returned in <resultVar>.
10555 New in version 3.14: The name of the <resultVar> is defined by the
10557 user. Previously, it had a fixed name RESULT_VAR.
10558 In this form, <srcdir> should contain a complete CMake project with a
10561 CMakeLists.txt file and all sources. The <bindir> and <srcdir> will
10562 not be deleted after this command is run. Specify <targetName> to
10563 build a specific target instead of the all or ALL_BUILD target. See
10564 below for the meaning of other options.
10565 Try Compiling Source Files
10567 try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
10568 [CMAKE_FLAGS <flags>...]
10569 [COMPILE_DEFINITIONS <defs>...]
10570 [LINK_OPTIONS <options>...]
10571 [LINK_LIBRARIES <libs>...]
10572 [OUTPUT_VARIABLE <var>]
10573 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
10574 [<LANG>_STANDARD <std>]
10575 [<LANG>_STANDARD_REQUIRED <bool>]
10576 [<LANG>_EXTENSIONS <bool>]
10577 )
10578 Try building an executable or static library from one or more source
10580 files (which one is determined by the CMAKE_TRY_COMPILE_TARGET_TYPE
10581 variable). The success or failure of the try_compile, i.e. TRUE or
10582 FALSE respectively, is returned in <resultVar>.
10583 New in version 3.14: The name of the <resultVar> is defined by the
10585 user. Previously, it had a fixed name RESULT_VAR.
10586 In this form, one or more source files must be provided. If
10589 CMAKE_TRY_COMPILE_TARGET_TYPE is unset or is set to EXECUTABLE, the
10590 sources must include a definition for main and CMake will create a
10591 CMakeLists.txt file to build the source(s) as an executable. If
10592 CMAKE_TRY_COMPILE_TARGET_TYPE is set to STATIC_LIBRARY, a static li‐
10593 brary will be built instead and no definition for main is required.
10594 For an executable, the generated CMakeLists.txt file would contain
10595 something like the following:
10596 add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
10598 include_directories(${INCLUDE_DIRECTORIES})
10599 link_directories(${LINK_DIRECTORIES})
10600 add_executable(cmTryCompileExec <srcfile>...)
10601 target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
10602 target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
10603 The options are:
10605 CMAKE_FLAGS <flags>...
10607 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
10608 cmake command-line used to drive the test build. The above ex‐
10609 ample shows how values for variables INCLUDE_DIRECTORIES,
10610 LINK_DIRECTORIES, and LINK_LIBRARIES are used.
10611 COMPILE_DEFINITIONS <defs>...
10613 Specify -Ddefinition arguments to pass to add_definitions() in
10614 the generated test project.
10615 COPY_FILE <fileName>
10617 Copy the built executable or static library to the given <file‐
10618 Name>.
10619 COPY_FILE_ERROR <var>
10621 Use after COPY_FILE to capture into variable <var> any error
10622 message encountered while trying to copy the file.
10623 LINK_LIBRARIES <libs>...
10625 Specify libraries to be linked in the generated project. The
10626 list of libraries may refer to system libraries and to Imported
10627 Targets from the calling project.
10628 If this option is specified, any -DLINK_LIBRARIES=... value
10630 given to the CMAKE_FLAGS option will be ignored.
10631 LINK_OPTIONS <options>...
10633 New in version 3.14.
10634 Specify link step options to pass to target_link_options() or to
10637 set the STATIC_LIBRARY_OPTIONS target property in the generated
10638 project, depending on the CMAKE_TRY_COMPILE_TARGET_TYPE vari‐
10639 able.
10640 OUTPUT_VARIABLE <var>
10642 Store the output from the build process in the given variable.
10643 <LANG>_STANDARD <std>
10645 New in version 3.8.
10646 Specify the C_STANDARD, CXX_STANDARD, OBJC_STANDARD, OB‐
10649 JCXX_STANDARD, or CUDA_STANDARD target property of the generated
10650 project.
10651 <LANG>_STANDARD_REQUIRED <bool>
10653 New in version 3.8.
10654 Specify the C_STANDARD_REQUIRED, CXX_STANDARD_REQUIRED,
10657 OBJC_STANDARD_REQUIRED, OBJCXX_STANDARD_REQUIRED,or CUDA_STAN‐
10658 DARD_REQUIRED target property of the generated project.
10659 <LANG>_EXTENSIONS <bool>
10661 New in version 3.8.
10662 Specify the C_EXTENSIONS, CXX_EXTENSIONS, OBJC_EXTENSIONS, OB‐
10665 JCXX_EXTENSIONS, or CUDA_EXTENSIONS target property of the gen‐
10666 erated project.
10667 In this version all files in <bindir>/CMakeFiles/CMakeTmp will be
10669 cleaned automatically. For debugging, --debug-trycompile can be passed
10670 to cmake to avoid this clean. However, multiple sequential try_compile
10671 operations reuse this single output directory. If you use --de‐
10672 bug-trycompile, you can only debug one try_compile call at a time. The
10673 recommended procedure is to protect all try_compile calls in your
10674 project by if(NOT DEFINED <resultVar>) logic, configure with cmake all
10675 the way through once, then delete the cache entry associated with the
10676 try_compile call of interest, and then re-run cmake again with --de‐
10677 bug-trycompile.
10678 Other Behavior Settings
10680 New in version 3.4: If set, the following variables are passed in to
10681 the generated try_compile CMakeLists.txt to initialize compile target
10682 properties with default values:
10683 • CMAKE_CUDA_RUNTIME_LIBRARY
10685 • CMAKE_ENABLE_EXPORTS
10687 • CMAKE_LINK_SEARCH_START_STATIC
10689 • CMAKE_LINK_SEARCH_END_STATIC
10691 • CMAKE_MSVC_RUNTIME_LIBRARY
10693 • CMAKE_POSITION_INDEPENDENT_CODE
10695 If CMP0056 is set to NEW, then CMAKE_EXE_LINKER_FLAGS is passed in as
10697 well.
10698 Changed in version 3.14: If CMP0083 is set to NEW, then in order to ob‐
10701 tain correct behavior at link time, the check_pie_supported() command
10702 from the CheckPIESupported module must be called before using the
10703 try_compile() command.
10704 The current settings of CMP0065 and CMP0083 are propagated through to
10707 the generated test project.
10708 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
10710 figuration.
10711 New in version 3.6: Set the CMAKE_TRY_COMPILE_TARGET_TYPE variable to
10713 specify the type of target used for the source file signature.
10714 New in version 3.6: Set the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES vari‐
10717 able to specify variables that must be propagated into the test
10718 project. This variable is meant for use only in toolchain files and is
10719 only honored by the try_compile() command for the source files form,
10720 not when given a whole project.
10721 Changed in version 3.8: If CMP0067 is set to NEW, or any of the
10724 <LANG>_STANDARD, <LANG>_STANDARD_REQUIRED, or <LANG>_EXTENSIONS options
10725 are used, then the language standard variables are honored:
10726 • CMAKE_C_STANDARD
10728 • CMAKE_C_STANDARD_REQUIRED
10730 • CMAKE_C_EXTENSIONS
10732 • CMAKE_CXX_STANDARD
10734 • CMAKE_CXX_STANDARD_REQUIRED
10736 • CMAKE_CXX_EXTENSIONS
10738 • CMAKE_OBJC_STANDARD
10740 • CMAKE_OBJC_STANDARD_REQUIRED
10742 • CMAKE_OBJC_EXTENSIONS
10744 • CMAKE_OBJCXX_STANDARD
10746 • CMAKE_OBJCXX_STANDARD_REQUIRED
10748 • CMAKE_OBJCXX_EXTENSIONS
10750 • CMAKE_CUDA_STANDARD
10752 • CMAKE_CUDA_STANDARD_REQUIRED
10754 • CMAKE_CUDA_EXTENSIONS
10756 Their values are used to set the corresponding target properties in the
10758 generated project (unless overridden by an explicit option).
10759 Changed in version 3.14: For the Green Hills MULTI generator the GHS
10762 toolset and target system customization cache variables are also propa‐
10763 gated into the test project.
10764 try_run
10767 Try compiling and then running some code.
10768 Try Compiling and Running Source Files
10770 try_run(<runResultVar> <compileResultVar>
10771 <bindir> <srcfile> [CMAKE_FLAGS <flags>...]
10772 [COMPILE_DEFINITIONS <defs>...]
10773 [LINK_OPTIONS <options>...]
10774 [LINK_LIBRARIES <libs>...]
10775 [COMPILE_OUTPUT_VARIABLE <var>]
10776 [RUN_OUTPUT_VARIABLE <var>]
10777 [OUTPUT_VARIABLE <var>]
10778 [WORKING_DIRECTORY <var>]
10779 [ARGS <args>...])
10780 Try compiling a <srcfile>. Returns TRUE or FALSE for success or fail‐
10782 ure in <compileResultVar>. If the compile succeeded, runs the exe‐
10783 cutable and returns its exit code in <runResultVar>. If the executable
10784 was built, but failed to run, then <runResultVar> will be set to
10785 FAILED_TO_RUN. See the try_compile() command for information on how
10786 the test project is constructed to build the source file.
10787 New in version 3.14: The names of the result variables <runResultVar>
10789 and <compileResultVar> are defined by the user. Previously, they had
10790 fixed names RUN_RESULT_VAR and COMPILE_RESULT_VAR.
10791 The options are:
10794 CMAKE_FLAGS <flags>...
10796 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
10797 cmake command-line used to drive the test build. The example in
10798 try_compile() shows how values for variables INCLUDE_DIRECTO‐
10799 RIES, LINK_DIRECTORIES, and LINK_LIBRARIES are used.
10800 COMPILE_DEFINITIONS <defs>...
10802 Specify -Ddefinition arguments to pass to add_definitions() in
10803 the generated test project.
10804 COMPILE_OUTPUT_VARIABLE <var>
10806 Report the compile step build output in a given variable.
10807 LINK_LIBRARIES <libs>...
10809 New in version 3.2.
10810 Specify libraries to be linked in the generated project. The
10813 list of libraries may refer to system libraries and to Imported
10814 Targets from the calling project.
10815 If this option is specified, any -DLINK_LIBRARIES=... value
10817 given to the CMAKE_FLAGS option will be ignored.
10818 LINK_OPTIONS <options>...
10820 New in version 3.14.
10821 Specify link step options to pass to target_link_options() in
10824 the generated project.
10825 OUTPUT_VARIABLE <var>
10827 Report the compile build output and the output from running the
10828 executable in the given variable. This option exists for legacy
10829 reasons. Prefer COMPILE_OUTPUT_VARIABLE and RUN_OUTPUT_VARIABLE
10830 instead.
10831 RUN_OUTPUT_VARIABLE <var>
10833 Report the output from running the executable in a given vari‐
10834 able.
10835 WORKING_DIRECTORY <var>
10837 New in version 3.20.
10838 Run the executable in the given directory. If no WORKING_DIREC‐
10841 TORY is specified, the executable will run in <bindir>.
10842 Other Behavior Settings
10844 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
10845 figuration.
10846 Behavior when Cross Compiling
10848 New in version 3.3: Use CMAKE_CROSSCOMPILING_EMULATOR when running
10849 cross-compiled binaries.
10850 When cross compiling, the executable compiled in the first step usually
10853 cannot be run on the build host. The try_run command checks the
10854 CMAKE_CROSSCOMPILING variable to detect whether CMake is in cross-com‐
10855 piling mode. If that is the case, it will still try to compile the ex‐
10856 ecutable, but it will not try to run the executable unless the
10857 CMAKE_CROSSCOMPILING_EMULATOR variable is set. Instead it will create
10858 cache variables which must be filled by the user or by presetting them
10859 in some CMake script file to the values the executable would have pro‐
10860 duced if it had been run on its actual target platform. These cache
10861 entries are:
10862 <runResultVar>
10864 Exit code if the executable were to be run on the target plat‐
10865 form.
10866 <runResultVar>__TRYRUN_OUTPUT
10868 Output from stdout and stderr if the executable were to be run
10869 on the target platform. This is created only if the RUN_OUT‐
10870 PUT_VARIABLE or OUTPUT_VARIABLE option was used.
10871 In order to make cross compiling your project easier, use try_run only
10873 if really required. If you use try_run, use the RUN_OUTPUT_VARIABLE or
10874 OUTPUT_VARIABLE options only if really required. Using them will re‐
10875 quire that when cross-compiling, the cache variables will have to be
10876 set manually to the output of the executable. You can also "guard" the
10877 calls to try_run with an if() block checking the CMAKE_CROSSCOMPILING
10878 variable and provide an easy-to-preset alternative for this case.
10879
10881 These commands are available only in CTest scripts.
10882 ctest_build
10884 Perform the CTest Build Step as a Dashboard Client.
10885 ctest_build([BUILD <build-dir>] [APPEND]
10887 [CONFIGURATION <config>]
10888 [PARALLEL_LEVEL <parallel>]
10889 [FLAGS <flags>]
10890 [PROJECT_NAME <project-name>]
10891 [TARGET <target-name>]
10892 [NUMBER_ERRORS <num-err-var>]
10893 [NUMBER_WARNINGS <num-warn-var>]
10894 [RETURN_VALUE <result-var>]
10895 [CAPTURE_CMAKE_ERROR <result-var>]
10896 )
10897 Build the project and store results in Build.xml for submission with
10899 the ctest_submit() command.
10900 The CTEST_BUILD_COMMAND variable may be set to explicitly specify the
10902 build command line. Otherwise the build command line is computed auto‐
10903 matically based on the options given.
10904 The options are:
10906 BUILD <build-dir>
10908 Specify the top-level build directory. If not given, the
10909 CTEST_BINARY_DIRECTORY variable is used.
10910 APPEND Mark Build.xml for append to results previously submitted to a
10912 dashboard server since the last ctest_start() call. Append se‐
10913 mantics are defined by the dashboard server in use. This does
10914 not cause results to be appended to a .xml file produced by a
10915 previous call to this command.
10916 CONFIGURATION <config>
10918 Specify the build configuration (e.g. Debug). If not specified
10919 the CTEST_BUILD_CONFIGURATION variable will be checked. Other‐
10920 wise the -C <cfg> option given to the ctest(1) command will be
10921 used, if any.
10922 PARALLEL_LEVEL <parallel>
10924 New in version 3.21.
10925 Specify the parallel level of the underlying build system. If
10928 not specified, the CMAKE_BUILD_PARALLEL_LEVEL environment vari‐
10929 able will be checked.
10930 FLAGS <flags>
10932 Pass additional arguments to the underlying build command. If
10933 not specified the CTEST_BUILD_FLAGS variable will be checked.
10934 This can, e.g., be used to trigger a parallel build using the -j
10935 option of make. See the ProcessorCount module for an example.
10936 PROJECT_NAME <project-name>
10938 Ignored since CMake 3.0.
10939 Changed in version 3.14: This value is no longer required.
10941 TARGET <target-name>
10944 Specify the name of a target to build. If not specified the
10945 CTEST_BUILD_TARGET variable will be checked. Otherwise the de‐
10946 fault target will be built. This is the "all" target (called
10947 ALL_BUILD in Visual Studio Generators).
10948 NUMBER_ERRORS <num-err-var>
10950 Store the number of build errors detected in the given variable.
10951 NUMBER_WARNINGS <num-warn-var>
10953 Store the number of build warnings detected in the given vari‐
10954 able.
10955 RETURN_VALUE <result-var>
10957 Store the return value of the native build tool in the given
10958 variable.
10959 CAPTURE_CMAKE_ERROR <result-var>
10961 New in version 3.7.
10962 Store in the <result-var> variable -1 if there are any errors
10965 running the command and prevent ctest from returning non-zero if
10966 an error occurs.
10967 QUIET New in version 3.3.
10969 Suppress any CTest-specific non-error output that would have
10972 been printed to the console otherwise. The summary of warnings
10973 / errors, as well as the output from the native build tool is
10974 unaffected by this option.
10975 ctest_configure
10977 Perform the CTest Configure Step as a Dashboard Client.
10978 ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
10980 [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
10981 [CAPTURE_CMAKE_ERROR <result-var>])
10982 Configure the project build tree and record results in Configure.xml
10984 for submission with the ctest_submit() command.
10985 The options are:
10987 BUILD <build-dir>
10989 Specify the top-level build directory. If not given, the
10990 CTEST_BINARY_DIRECTORY variable is used.
10991 SOURCE <source-dir>
10993 Specify the source directory. If not given, the
10994 CTEST_SOURCE_DIRECTORY variable is used.
10995 APPEND Mark Configure.xml for append to results previously submitted to
10997 a dashboard server since the last ctest_start() call. Append
10998 semantics are defined by the dashboard server in use. This does
10999 not cause results to be appended to a .xml file produced by a
11000 previous call to this command.
11001 OPTIONS <options>
11003 Specify command-line arguments to pass to the configuration
11004 tool.
11005 RETURN_VALUE <result-var>
11007 Store in the <result-var> variable the return value of the na‐
11008 tive configuration tool.
11009 CAPTURE_CMAKE_ERROR <result-var>
11011 New in version 3.7.
11012 Store in the <result-var> variable -1 if there are any errors
11015 running the command and prevent ctest from returning non-zero if
11016 an error occurs.
11017 QUIET New in version 3.3.
11019 Suppress any CTest-specific non-error messages that would have
11022 otherwise been printed to the console. Output from the underly‐
11023 ing configure command is not affected.
11024 ctest_coverage
11026 Perform the CTest Coverage Step as a Dashboard Client.
11027 ctest_coverage([BUILD <build-dir>] [APPEND]
11029 [LABELS <label>...]
11030 [RETURN_VALUE <result-var>]
11031 [CAPTURE_CMAKE_ERROR <result-var>]
11032 [QUIET]
11033 )
11034 Collect coverage tool results and stores them in Coverage.xml for sub‐
11036 mission with the ctest_submit() command.
11037 The options are:
11039 BUILD <build-dir>
11041 Specify the top-level build directory. If not given, the
11042 CTEST_BINARY_DIRECTORY variable is used.
11043 APPEND Mark Coverage.xml for append to results previously submitted to
11045 a dashboard server since the last ctest_start() call. Append
11046 semantics are defined by the dashboard server in use. This does
11047 not cause results to be appended to a .xml file produced by a
11048 previous call to this command.
11049 LABELS Filter the coverage report to include only source files labeled
11051 with at least one of the labels specified.
11052 RETURN_VALUE <result-var>
11054 Store in the <result-var> variable 0 if coverage tools ran with‐
11055 out error and non-zero otherwise.
11056 CAPTURE_CMAKE_ERROR <result-var>
11058 New in version 3.7.
11059 Store in the <result-var> variable -1 if there are any errors
11062 running the command and prevent ctest from returning non-zero if
11063 an error occurs.
11064 QUIET New in version 3.3.
11066 Suppress any CTest-specific non-error output that would have
11069 been printed to the console otherwise. The summary indicating
11070 how many lines of code were covered is unaffected by this op‐
11071 tion.
11072 ctest_empty_binary_directory
11074 empties the binary directory
11075 ctest_empty_binary_directory( directory )
11077 Removes a binary directory. This command will perform some checks
11079 prior to deleting the directory in an attempt to avoid malicious or ac‐
11080 cidental directory deletion.
11081 ctest_memcheck
11083 Perform the CTest MemCheck Step as a Dashboard Client.
11084 ctest_memcheck([BUILD <build-dir>] [APPEND]
11086 [START <start-number>]
11087 [END <end-number>]
11088 [STRIDE <stride-number>]
11089 [EXCLUDE <exclude-regex>]
11090 [INCLUDE <include-regex>]
11091 [EXCLUDE_LABEL <label-exclude-regex>]
11092 [INCLUDE_LABEL <label-include-regex>]
11093 [EXCLUDE_FIXTURE <regex>]
11094 [EXCLUDE_FIXTURE_SETUP <regex>]
11095 [EXCLUDE_FIXTURE_CLEANUP <regex>]
11096 [PARALLEL_LEVEL <level>]
11097 [RESOURCE_SPEC_FILE <file>]
11098 [TEST_LOAD <threshold>]
11099 [SCHEDULE_RANDOM <ON|OFF>]
11100 [STOP_ON_FAILURE]
11101 [STOP_TIME <time-of-day>]
11102 [RETURN_VALUE <result-var>]
11103 [CAPTURE_CMAKE_ERROR <result-var>]
11104 [REPEAT <mode>:<n>]
11105 [OUTPUT_JUNIT <file>]
11106 [DEFECT_COUNT <defect-count-var>]
11107 [QUIET]
11108 )
11109 Run tests with a dynamic analysis tool and store results in Mem‐
11111 Check.xml for submission with the ctest_submit() command.
11112 Most options are the same as those for the ctest_test() command.
11114 The options unique to this command are:
11116 DEFECT_COUNT <defect-count-var>
11118 New in version 3.8.
11119 Store in the <defect-count-var> the number of defects found.
11122 ctest_read_custom_files
11124 read CTestCustom files.
11125 ctest_read_custom_files( directory ... )
11127 Read all the CTestCustom.ctest or CTestCustom.cmake files from the
11129 given directory.
11130 By default, invoking ctest(1) without a script will read custom files
11132 from the binary directory.
11133 ctest_run_script
11135 runs a ctest -S script
11136 ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
11138 script_file_name2 ... [RETURN_VALUE var])
11139 Runs a script or scripts much like if it was run from ctest -S. If no
11141 argument is provided then the current script is run using the current
11142 settings of the variables. If NEW_PROCESS is specified then each
11143 script will be run in a separate process.If RETURN_VALUE is specified
11144 the return value of the last script run will be put into var.
11145 ctest_sleep
11147 sleeps for some amount of time
11148 ctest_sleep(<seconds>)
11150 Sleep for given number of seconds.
11152 ctest_sleep(<time1> <duration> <time2>)
11154 Sleep for t=(time1 + duration - time2) seconds if t > 0.
11156 ctest_start
11158 Starts the testing for a given model
11159 ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])
11161 ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET])
11163 Starts the testing for a given model. The command should be called af‐
11165 ter the binary directory is initialized.
11166 The parameters are as follows:
11168 <model>
11170 Set the dashboard model. Must be one of Experimental, Continu‐
11171 ous, or Nightly. This parameter is required unless APPEND is
11172 specified.
11173 <source>
11175 Set the source directory. If not specified, the value of
11176 CTEST_SOURCE_DIRECTORY is used instead.
11177 <binary>
11179 Set the binary directory. If not specified, the value of
11180 CTEST_BINARY_DIRECTORY is used instead.
11181 GROUP <group>
11183 If GROUP is used, the submissions will go to the specified group
11184 on the CDash server. If no GROUP is specified, the name of the
11185 model is used by default.
11186 Changed in version 3.16: This replaces the deprecated option
11188 TRACK. Despite the name change its behavior is unchanged.
11189 APPEND If APPEND is used, the existing TAG is used rather than creating
11192 a new one based on the current time stamp. If you use APPEND,
11193 you can omit the <model> and GROUP <group> parameters, because
11194 they will be read from the generated TAG file. For example:
11195 ctest_start(Experimental GROUP GroupExperimental)
11197 Later, in another ctest -S script:
11199 ctest_start(APPEND)
11201 When the second script runs ctest_start(APPEND), it will read
11203 the Experimental model and GroupExperimental group from the TAG
11204 file generated by the first ctest_start() command. Please note
11205 that if you call ctest_start(APPEND) and specify a different
11206 model or group than in the first ctest_start() command, a warn‐
11207 ing will be issued, and the new model and group will be used.
11208 QUIET New in version 3.3.
11210 If QUIET is used, CTest will suppress any non-error messages
11213 that it otherwise would have printed to the console.
11214 The parameters for ctest_start() can be issued in any order, with the
11216 exception that <model>, <source>, and <binary> have to appear in that
11217 order with respect to each other. The following are all valid and
11218 equivalent:
11219 ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND)
11221 ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary)
11223 ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary)
11225 However, for the sake of readability, it is recommended that you order
11227 your parameters in the order listed at the top of this page.
11228 If the CTEST_CHECKOUT_COMMAND variable (or the CTEST_CVS_CHECKOUT vari‐
11230 able) is set, its content is treated as command-line. The command is
11231 invoked with the current working directory set to the parent of the
11232 source directory, even if the source directory already exists. This
11233 can be used to create the source tree from a version control reposi‐
11234 tory.
11235 ctest_submit
11237 Perform the CTest Submit Step as a Dashboard Client.
11238 ctest_submit([PARTS <part>...] [FILES <file>...]
11240 [SUBMIT_URL <url>]
11241 [BUILD_ID <result-var>]
11242 [HTTPHEADER <header>]
11243 [RETRY_COUNT <count>]
11244 [RETRY_DELAY <delay>]
11245 [RETURN_VALUE <result-var>]
11246 [CAPTURE_CMAKE_ERROR <result-var>]
11247 [QUIET]
11248 )
11249 Submit results to a dashboard server. By default all available parts
11251 are submitted.
11252 The options are:
11254 PARTS <part>...
11256 Specify a subset of parts to submit. Valid part names are:
11257 Start = nothing
11259 Update = ctest_update results, in Update.xml
11260 Configure = ctest_configure results, in Configure.xml
11261 Build = ctest_build results, in Build.xml
11262 Test = ctest_test results, in Test.xml
11263 Coverage = ctest_coverage results, in Coverage.xml
11264 MemCheck = ctest_memcheck results, in DynamicAnalysis.xml and
11265 DynamicAnalysis-Test.xml
11266 Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
11267 ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
11268 Upload = Files prepared for upload by ctest_upload(), in Upload.xml
11269 Submit = nothing
11270 Done = Build is complete, in Done.xml
11271 FILES <file>...
11273 Specify an explicit list of specific files to be submitted.
11274 Each individual file must exist at the time of the call.
11275 SUBMIT_URL <url>
11277 New in version 3.14.
11278 The http or https URL of the dashboard server to send the sub‐
11281 mission to. If not given, the CTEST_SUBMIT_URL variable is
11282 used.
11283 BUILD_ID <result-var>
11285 New in version 3.15.
11286 Store in the <result-var> variable the ID assigned to this build
11289 by CDash.
11290 HTTPHEADER <HTTP-header>
11292 New in version 3.9.
11293 Specify HTTP header to be included in the request to CDash dur‐
11296 ing submission. For example, CDash can be configured to only
11297 accept submissions from authenticated clients. In this case, you
11298 should provide a bearer token in your header:
11299 ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>")
11301 This suboption can be repeated several times for multiple head‐
11303 ers.
11304 RETRY_COUNT <count>
11306 Specify how many times to retry a timed-out submission.
11307 RETRY_DELAY <delay>
11309 Specify how long (in seconds) to wait after a timed-out submis‐
11310 sion before attempting to re-submit.
11311 RETURN_VALUE <result-var>
11313 Store in the <result-var> variable 0 for success and non-zero on
11314 failure.
11315 CAPTURE_CMAKE_ERROR <result-var>
11317 New in version 3.13.
11318 Store in the <result-var> variable -1 if there are any errors
11321 running the command and prevent ctest from returning non-zero if
11322 an error occurs.
11323 QUIET New in version 3.3.
11325 Suppress all non-error messages that would have otherwise been
11328 printed to the console.
11329 Submit to CDash Upload API
11331 New in version 3.2.
11332 ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
11335 [SUBMIT_URL <url>]
11336 [BUILD_ID <result-var>]
11337 [HTTPHEADER <header>]
11338 [RETRY_COUNT <count>]
11339 [RETRY_DELAY <delay>]
11340 [RETURN_VALUE <result-var>]
11341 [QUIET])
11342 This second signature is used to upload files to CDash via the CDash
11344 file upload API. The API first sends a request to upload to CDash along
11345 with a content hash of the file. If CDash does not already have the
11346 file, then it is uploaded. Along with the file, a CDash type string is
11347 specified to tell CDash which handler to use to process the data.
11348 This signature interprets options in the same way as the first one.
11350 New in version 3.8: Added the RETRY_COUNT, RETRY_DELAY, QUIET options.
11352 New in version 3.9: Added the HTTPHEADER option.
11355 New in version 3.13: Added the RETURN_VALUE option.
11358 New in version 3.14: Added the SUBMIT_URL option.
11361 New in version 3.15: Added the BUILD_ID option.
11364 ctest_test
11367 Perform the CTest Test Step as a Dashboard Client.
11368 ctest_test([BUILD <build-dir>] [APPEND]
11370 [START <start-number>]
11371 [END <end-number>]
11372 [STRIDE <stride-number>]
11373 [EXCLUDE <exclude-regex>]
11374 [INCLUDE <include-regex>]
11375 [EXCLUDE_LABEL <label-exclude-regex>]
11376 [INCLUDE_LABEL <label-include-regex>]
11377 [EXCLUDE_FIXTURE <regex>]
11378 [EXCLUDE_FIXTURE_SETUP <regex>]
11379 [EXCLUDE_FIXTURE_CLEANUP <regex>]
11380 [PARALLEL_LEVEL <level>]
11381 [RESOURCE_SPEC_FILE <file>]
11382 [TEST_LOAD <threshold>]
11383 [SCHEDULE_RANDOM <ON|OFF>]
11384 [STOP_ON_FAILURE]
11385 [STOP_TIME <time-of-day>]
11386 [RETURN_VALUE <result-var>]
11387 [CAPTURE_CMAKE_ERROR <result-var>]
11388 [REPEAT <mode>:<n>]
11389 [OUTPUT_JUNIT <file>]
11390 [QUIET]
11391 )
11392 Run tests in the project build tree and store results in Test.xml for
11394 submission with the ctest_submit() command.
11395 The options are:
11397 BUILD <build-dir>
11399 Specify the top-level build directory. If not given, the
11400 CTEST_BINARY_DIRECTORY variable is used.
11401 APPEND Mark Test.xml for append to results previously submitted to a
11403 dashboard server since the last ctest_start() call. Append se‐
11404 mantics are defined by the dashboard server in use. This does
11405 not cause results to be appended to a .xml file produced by a
11406 previous call to this command.
11407 START <start-number>
11409 Specify the beginning of a range of test numbers.
11410 END <end-number>
11412 Specify the end of a range of test numbers.
11413 STRIDE <stride-number>
11415 Specify the stride by which to step across a range of test num‐
11416 bers.
11417 EXCLUDE <exclude-regex>
11419 Specify a regular expression matching test names to exclude.
11420 INCLUDE <include-regex>
11422 Specify a regular expression matching test names to include.
11423 Tests not matching this expression are excluded.
11424 EXCLUDE_LABEL <label-exclude-regex>
11426 Specify a regular expression matching test labels to exclude.
11427 INCLUDE_LABEL <label-include-regex>
11429 Specify a regular expression matching test labels to include.
11430 Tests not matching this expression are excluded.
11431 EXCLUDE_FIXTURE <regex>
11433 New in version 3.7.
11434 If a test in the set of tests to be executed requires a particu‐
11437 lar fixture, that fixture's setup and cleanup tests would nor‐
11438 mally be added to the test set automatically. This option pre‐
11439 vents adding setup or cleanup tests for fixtures matching the
11440 <regex>. Note that all other fixture behavior is retained, in‐
11441 cluding test dependencies and skipping tests that have fixture
11442 setup tests that fail.
11443 EXCLUDE_FIXTURE_SETUP <regex>
11445 New in version 3.7.
11446 Same as EXCLUDE_FIXTURE except only matching setup tests are ex‐
11449 cluded.
11450 EXCLUDE_FIXTURE_CLEANUP <regex>
11452 New in version 3.7.
11453 Same as EXCLUDE_FIXTURE except only matching cleanup tests are
11456 excluded.
11457 PARALLEL_LEVEL <level>
11459 Specify a positive number representing the number of tests to be
11460 run in parallel.
11461 RESOURCE_SPEC_FILE <file>
11463 New in version 3.16.
11464 Specify a resource specification file. See ctest-resource-allo‐
11467 cation for more information.
11468 TEST_LOAD <threshold>
11470 New in version 3.4.
11471 While running tests in parallel, try not to start tests when
11474 they may cause the CPU load to pass above a given threshold. If
11475 not specified the CTEST_TEST_LOAD variable will be checked, and
11476 then the --test-load command-line argument to ctest(1). See
11477 also the TestLoad setting in the CTest Test Step.
11478 REPEAT <mode>:<n>
11480 New in version 3.17.
11481 Run tests repeatedly based on the given <mode> up to <n> times.
11484 The modes are:
11485 UNTIL_FAIL
11487 Require each test to run <n> times without failing in or‐
11488 der to pass. This is useful in finding sporadic failures
11489 in test cases.
11490 UNTIL_PASS
11492 Allow each test to run up to <n> times in order to pass.
11493 Repeats tests if they fail for any reason. This is use‐
11494 ful in tolerating sporadic failures in test cases.
11495 AFTER_TIMEOUT
11497 Allow each test to run up to <n> times in order to pass.
11498 Repeats tests only if they timeout. This is useful in
11499 tolerating sporadic timeouts in test cases on busy ma‐
11500 chines.
11501 SCHEDULE_RANDOM <ON|OFF>
11503 Launch tests in a random order. This may be useful for detect‐
11504 ing implicit test dependencies.
11505 STOP_ON_FAILURE
11507 New in version 3.18.
11508 Stop the execution of the tests once one has failed.
11511 STOP_TIME <time-of-day>
11513 Specify a time of day at which the tests should all stop run‐
11514 ning.
11515 RETURN_VALUE <result-var>
11517 Store in the <result-var> variable 0 if all tests passed. Store
11518 non-zero if anything went wrong.
11519 CAPTURE_CMAKE_ERROR <result-var>
11521 New in version 3.7.
11522 Store in the <result-var> variable -1 if there are any errors
11525 running the command and prevent ctest from returning non-zero if
11526 an error occurs.
11527 OUTPUT_JUNIT <file>
11529 New in version 3.21.
11530 Write test results to <file> in JUnit XML format. If <file> is a
11533 relative path, it will be placed in the build directory. If
11534 <file> already exists, it will be overwritten. Note that the re‐
11535 sulting JUnit XML file is not uploaded to CDash because it would
11536 be redundant with CTest's Test.xml file.
11537 QUIET New in version 3.3.
11539 Suppress any CTest-specific non-error messages that would have
11542 otherwise been printed to the console. Output from the underly‐
11543 ing test command is not affected. Summary info detailing the
11544 percentage of passing tests is also unaffected by the QUIET op‐
11545 tion.
11546 See also the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE and
11548 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables.
11549 Additional Test Measurements
11551 CTest can parse the output of your tests for extra measurements to re‐
11552 port to CDash.
11553 When run as a Dashboard Client, CTest will include these custom mea‐
11555 surements in the Test.xml file that gets uploaded to CDash.
11556 Check the CDash test measurement documentation for more information on
11558 the types of test measurements that CDash recognizes.
11559 The following example demonstrates how to output a variety of custom
11561 test measurements.
11562 std::cout <<
11564 "<CTestMeasurement type=\"numeric/double\" name=\"score\">28.3</CTestMeasurement>"
11565 << std::endl;
11566 std::cout <<
11568 "<CTestMeasurement type=\"text/string\" name=\"color\">red</CTestMeasurement>"
11569 << std::endl;
11570 std::cout <<
11572 "<CTestMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.org</CTestMeasurement>"
11573 << std::endl;
11574 std::cout <<
11576 "<CTestMeasurement type=\"text/preformatted\" name=\"Console Output\">" <<
11577 "line 1.\n" <<
11578 " \033[31;1m line 2. Bold red, and indented!\033[0;0ml\n" <<
11579 "line 3. Not bold or indented...\n" <<
11580 "</CTestMeasurement>" << std::endl;
11581 Image Measurements
11583 The following example demonstrates how to upload test images to CDash.
11584 std::cout <<
11586 "<CTestMeasurementFile type=\"image/jpg\" name=\"TestImage\">" <<
11587 "/dir/to/test_img.jpg</CTestMeasurementFile>" << std::endl;
11588 std::cout <<
11590 "<CTestMeasurementFile type=\"image/gif\" name=\"ValidImage\">" <<
11591 "/dir/to/valid_img.gif</CTestMeasurementFile>" << std::endl;
11592 std::cout <<
11594 "<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\"> <<
11595 "/dir/to/img.png</CTestMeasurementFile>"
11596 << std::endl;
11597 Images will be displayed together in an interactive comparison mode on
11599 CDash if they are provided with two or more of the following names.
11600 • TestImage
11602 • ValidImage
11604 • BaselineImage
11606 • DifferenceImage2
11608 By convention, TestImage is the image generated by your test, and Va‐
11610 lidImage (or BaselineImage) is basis of comparison used to determine if
11611 the test passed or failed.
11612 If another image name is used it will be displayed by CDash as a static
11614 image separate from the interactive comparison UI.
11615 Attached Files
11617 New in version 3.21.
11618 The following example demonstrates how to upload non-image files to
11621 CDash.
11622 std::cout <<
11624 "<CTestMeasurementFile type=\"file\" name=\"TestInputData1\">" <<
11625 "/dir/to/data1.csv</CTestMeasurementFile>\n" <<
11626 "<CTestMeasurementFile type=\"file\" name=\"TestInputData2\">" <<
11627 "/dir/to/data2.csv</CTestMeasurementFile>" << std::endl;
11628 If the name of the file to upload is known at configure time, you can
11630 use the ATTACHED_FILES or ATTACHED_FILES_ON_FAIL test properties in‐
11631 stead.
11632 Custom Details
11634 New in version 3.21.
11635 The following example demonstrates how to specify a custom value for
11638 the Test Details field displayed on CDash.
11639 std::cout <<
11641 "<CTestDetails>My Custom Details Value</CTestDetails>" << std::endl;
11642 Additional Labels
11644 New in version 3.22.
11645 The following example demonstrates how to add additional labels to a
11648 test at runtime.
11649 std::cout <<
11651 "<CTestLabel>Custom Label 1</CTestLabel>\n" <<
11652 "<CTestLabel>Custom Label 2</CTestLabel>" << std::endl;
11653 Use the LABELS test property instead for labels that can be determined
11655 at configure time.
11656 ctest_update
11658 Perform the CTest Update Step as a Dashboard Client.
11659 ctest_update([SOURCE <source-dir>]
11661 [RETURN_VALUE <result-var>]
11662 [CAPTURE_CMAKE_ERROR <result-var>]
11663 [QUIET])
11664 Update the source tree from version control and record results in Up‐
11666 date.xml for submission with the ctest_submit() command.
11667 The options are:
11669 SOURCE <source-dir>
11671 Specify the source directory. If not given, the
11672 CTEST_SOURCE_DIRECTORY variable is used.
11673 RETURN_VALUE <result-var>
11675 Store in the <result-var> variable the number of files updated
11676 or -1 on error.
11677 CAPTURE_CMAKE_ERROR <result-var>
11679 New in version 3.13.
11680 Store in the <result-var> variable -1 if there are any errors
11683 running the command and prevent ctest from returning non-zero if
11684 an error occurs.
11685 QUIET New in version 3.3.
11687 Tell CTest to suppress most non-error messages that it would
11690 have otherwise printed to the console. CTest will still report
11691 the new revision of the repository and any conflicting files
11692 that were found.
11693 The update always follows the version control branch currently checked
11695 out in the source directory. See the CTest Update Step documentation
11696 for information about variables that change the behavior of ctest_up‐
11697 date().
11698 ctest_upload
11700 Upload files to a dashboard server as a Dashboard Client.
11701 ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
11703 The options are:
11705 FILES <file>...
11707 Specify a list of files to be sent along with the build results
11708 to the dashboard server.
11709 QUIET New in version 3.3.
11711 Suppress any CTest-specific non-error output that would have
11714 been printed to the console otherwise.
11715 CAPTURE_CMAKE_ERROR <result-var>
11717 New in version 3.7.
11718 Store in the <result-var> variable -1 if there are any errors
11721 running the command and prevent ctest from returning non-zero if
11722 an error occurs.
11723
11725 These commands are deprecated and are only made available to maintain
11726 backward compatibility. The documentation of each command states the
11727 CMake version in which it was deprecated. Do not use these commands in
11728 new code.
11729 build_name
11731 Disallowed since version 3.0. See CMake Policy CMP0036.
11732 Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.
11734 build_name(variable)
11736 Sets the specified variable to a string representing the platform and
11738 compiler settings. These values are now available through the
11739 CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
11740 exec_program
11742 Deprecated since version 3.0: Use the execute_process() command in‐
11743 stead.
11744 Run an executable program during the processing of the CMakeList.txt
11747 file.
11748 exec_program(Executable [directory in which to run]
11750 [ARGS <arguments to executable>]
11751 [OUTPUT_VARIABLE <var>]
11752 [RETURN_VALUE <var>])
11753 The executable is run in the optionally specified directory. The exe‐
11755 cutable can include arguments if it is double quoted, but it is better
11756 to use the optional ARGS argument to specify arguments to the program.
11757 This is because cmake will then be able to escape spaces in the exe‐
11758 cutable path. An optional argument OUTPUT_VARIABLE specifies a vari‐
11759 able in which to store the output. To capture the return value of the
11760 execution, provide a RETURN_VALUE. If OUTPUT_VARIABLE is specified,
11761 then no output will go to the stdout/stderr of the console running
11762 cmake.
11763 export_library_dependencies
11765 Disallowed since version 3.0. See CMake Policy CMP0033.
11766 Use install(EXPORT) or export() command.
11768 This command generates an old-style library dependencies file.
11770 Projects requiring CMake 2.6 or later should not use the command. Use
11771 instead the install(EXPORT) command to help export targets from an in‐
11772 stallation tree and the export() command to export targets from a build
11773 tree.
11774 The old-style library dependencies file does not take into account
11776 per-configuration names of libraries or the LINK_INTERFACE_LIBRARIES
11777 target property.
11778 export_library_dependencies(<file> [APPEND])
11780 Create a file named <file> that can be included into a CMake listfile
11782 with the INCLUDE command. The file will contain a number of SET com‐
11783 mands that will set all the variables needed for library dependency in‐
11784 formation. This should be the last command in the top level CMake‐
11785 Lists.txt file of the project. If the APPEND option is specified, the
11786 SET commands will be appended to the given file instead of replacing
11787 it.
11788 install_files
11790 Deprecated since version 3.0: Use the install(FILES) command instead.
11791 This command has been superseded by the install() command. It is pro‐
11794 vided for compatibility with older CMake code. The FILES form is di‐
11795 rectly replaced by the FILES form of the install() command. The regexp
11796 form can be expressed more clearly using the GLOB form of the file()
11797 command.
11798 install_files(<dir> extension file file ...)
11800 Create rules to install the listed files with the given extension into
11802 the given directory. Only files existing in the current source tree or
11803 its corresponding location in the binary tree may be listed. If a file
11804 specified already has an extension, that extension will be removed
11805 first. This is useful for providing lists of source files such as
11806 foo.cxx when you want the corresponding foo.h to be installed. A typi‐
11807 cal extension is .h.
11808 install_files(<dir> regexp)
11810 Any files in the current source directory that match the regular ex‐
11812 pression will be installed.
11813 install_files(<dir> FILES file file ...)
11815 Any files listed after the FILES keyword will be installed explicitly
11817 from the names given. Full paths are allowed in this form.
11818 The directory <dir> is relative to the installation prefix, which is
11820 stored in the variable CMAKE_INSTALL_PREFIX.
11821 install_programs
11823 Deprecated since version 3.0: Use the install(PROGRAMS) command in‐
11824 stead.
11825 This command has been superseded by the install() command. It is pro‐
11828 vided for compatibility with older CMake code. The FILES form is di‐
11829 rectly replaced by the PROGRAMS form of the install() command. The
11830 regexp form can be expressed more clearly using the GLOB form of the
11831 file() command.
11832 install_programs(<dir> file1 file2 [file3 ...])
11834 install_programs(<dir> FILES file1 [file2 ...])
11835 Create rules to install the listed programs into the given directory.
11837 Use the FILES argument to guarantee that the file list version of the
11838 command will be used even when there is only one argument.
11839 install_programs(<dir> regexp)
11841 In the second form any program in the current source directory that
11843 matches the regular expression will be installed.
11844 This command is intended to install programs that are not built by
11846 cmake, such as shell scripts. See the TARGETS form of the install()
11847 command to create installation rules for targets built by cmake.
11848 The directory <dir> is relative to the installation prefix, which is
11850 stored in the variable CMAKE_INSTALL_PREFIX.
11851 install_targets
11853 Deprecated since version 3.0: Use the install(TARGETS) command instead.
11854 This command has been superseded by the install() command. It is pro‐
11857 vided for compatibility with older CMake code.
11858 install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
11860 Create rules to install the listed targets into the given directory.
11862 The directory <dir> is relative to the installation prefix, which is
11863 stored in the variable CMAKE_INSTALL_PREFIX. If RUNTIME_DIRECTORY is
11864 specified, then on systems with special runtime files (Windows DLL),
11865 the files will be copied to that directory.
11866 load_command
11868 Disallowed since version 3.0. See CMake Policy CMP0031.
11869 Load a command into a running CMake.
11871 load_command(COMMAND_NAME <loc1> [loc2 ...])
11873 The given locations are searched for a library whose name is cmCOM‐
11875 MAND_NAME. If found, it is loaded as a module and the command is added
11876 to the set of available CMake commands. Usually, try_compile() is used
11877 before this command to compile the module. If the command is success‐
11878 fully loaded a variable named
11879 CMAKE_LOADED_COMMAND_<COMMAND_NAME>
11881 will be set to the full path of the module that was loaded. Otherwise
11883 the variable will not be set.
11884 make_directory
11886 Deprecated since version 3.0: Use the file(MAKE_DIRECTORY) command in‐
11887 stead.
11888 make_directory(directory)
11891 Creates the specified directory. Full paths should be given. Any par‐
11893 ent directories that do not exist will also be created. Use with care.
11894 output_required_files
11896 Disallowed since version 3.0. See CMake Policy CMP0032.
11897 Approximate C preprocessor dependency scanning.
11899 This command exists only because ancient CMake versions provided it.
11901 CMake handles preprocessor dependency scanning automatically using a
11902 more advanced scanner.
11903 output_required_files(srcfile outputfile)
11905 Outputs a list of all the source files that are required by the speci‐
11907 fied srcfile. This list is written into outputfile. This is similar
11908 to writing out the dependencies for srcfile except that it jumps from
11909 .h files into .cxx, .c and .cpp files if possible.
11910 qt_wrap_cpp
11912 Deprecated since version 3.14: This command was originally added to
11913 support Qt 3 before the add_custom_command() command was sufficiently
11914 mature. The FindQt4 module provides the qt4_wrap_cpp() macro, which
11915 should be used instead for Qt 4 projects. For projects using Qt 5 or
11916 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
11917 vides qt5_wrap_cpp()).
11918 Manually create Qt Wrappers.
11921 qt_wrap_cpp(resultingLibraryName DestName SourceLists ...)
11923 Produces moc files for all the .h files listed in the SourceLists. The
11925 moc files will be added to the library using the DestName source list.
11926 Consider updating the project to use the AUTOMOC target property in‐
11928 stead for a more automated way of invoking the moc tool.
11929 qt_wrap_ui
11931 Deprecated since version 3.14: This command was originally added to
11932 support Qt 3 before the add_custom_command() command was sufficiently
11933 mature. The FindQt4 module provides the qt4_wrap_ui() macro, which
11934 should be used instead for Qt 4 projects. For projects using Qt 5 or
11935 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
11936 vides qt5_wrap_ui()).
11937 Manually create Qt user interfaces Wrappers.
11940 qt_wrap_ui(resultingLibraryName HeadersDestName
11942 SourcesDestName SourceLists ...)
11943 Produces .h and .cxx files for all the .ui files listed in the
11945 SourceLists. The .h files will be added to the library using the Head‐
11946 ersDestNamesource list. The .cxx files will be added to the library
11947 using the SourcesDestNamesource list.
11948 Consider updating the project to use the AUTOUIC target property in‐
11950 stead for a more automated way of invoking the uic tool.
11951 remove
11953 Deprecated since version 3.0: Use the list(REMOVE_ITEM) command in‐
11954 stead.
11955 remove(VAR VALUE VALUE ...)
11958 Removes VALUE from the variable VAR. This is typically used to remove
11960 entries from a vector (e.g. semicolon separated list). VALUE is ex‐
11961 panded.
11962 subdir_depends
11964 Disallowed since version 3.0. See CMake Policy CMP0029.
11965 Does nothing.
11967 subdir_depends(subdir dep1 dep2 ...)
11969 Does not do anything. This command used to help projects order paral‐
11971 lel builds correctly. This functionality is now automatic.
11972 subdirs
11974 Deprecated since version 3.0: Use the add_subdirectory() command in‐
11975 stead.
11976 Add a list of subdirectories to the build.
11979 subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
11981 [PREORDER] )
11982 Add a list of subdirectories to the build. The add_subdirectory() com‐
11984 mand should be used instead of subdirs although subdirs will still
11985 work. This will cause any CMakeLists.txt files in the sub directories
11986 to be processed by CMake. Any directories after the PREORDER flag are
11987 traversed first by makefile builds, the PREORDER flag has no effect on
11988 IDE projects. Any directories after the EXCLUDE_FROM_ALL marker will
11989 not be included in the top level makefile or project file. This is
11990 useful for having CMake create makefiles or projects for a set of exam‐
11991 ples in a project. You would want CMake to generate makefiles or
11992 project files for all the examples at the same time, but you would not
11993 want them to show up in the top level project or be built each time
11994 make is run from the top.
11995 use_mangled_mesa
11997 Disallowed since version 3.0. See CMake Policy CMP0030.
11998 Copy mesa headers for use in combination with system GL.
12000 use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
12002 The path to mesa includes, should contain gl_mangle.h. The mesa head‐
12004 ers are copied to the specified output directory. This allows mangled
12005 mesa headers to override other GL headers by being added to the include
12006 directory path earlier.
12007 utility_source
12009 Disallowed since version 3.0. See CMake Policy CMP0034.
12010 Specify the source tree of a third-party utility.
12012 utility_source(cache_entry executable_name
12014 path_to_source [file1 file2 ...])
12015 When a third-party utility's source is included in the distribution,
12017 this command specifies its location and name. The cache entry will not
12018 be set unless the path_to_source and all listed files exist. It is as‐
12019 sumed that the source tree of the utility will have been built before
12020 it is needed.
12021 When cross compiling CMake will print a warning if a utility_source()
12023 command is executed, because in many cases it is used to build an exe‐
12024 cutable which is executed later on. This doesn't work when cross com‐
12025 piling, since the executable can run only on their target platform. So
12026 in this case the cache entry has to be adjusted manually so it points
12027 to an executable which is runnable on the build host.
12028 variable_requires
12030 Disallowed since version 3.0. See CMake Policy CMP0035.
12031 Use the if() command instead.
12033 Assert satisfaction of an option's required variables.
12035 variable_requires(TEST_VARIABLE RESULT_VARIABLE
12037 REQUIRED_VARIABLE1
12038 REQUIRED_VARIABLE2 ...)
12039 The first argument (TEST_VARIABLE) is the name of the variable to be
12041 tested, if that variable is false nothing else is done. If TEST_VARI‐
12042 ABLE is true, then the next argument (RESULT_VARIABLE) is a variable
12043 that is set to true if all the required variables are set. The rest of
12044 the arguments are variables that must be true or not set to NOTFOUND to
12045 avoid an error. If any are not true, an error is reported.
12046 write_file
12048 Deprecated since version 3.0: Use the file(WRITE) command instead.
12049 write_file(filename "message to write"... [APPEND])
12052 The first argument is the file name, the rest of the arguments are mes‐
12054 sages to write. If the argument APPEND is specified, then the message
12055 will be appended.
12056 NOTE 1: file(WRITE) and file(APPEND) do exactly the same as this one
12058 but add some more functionality.
12059 NOTE 2: When using write_file the produced file cannot be used as an
12061 input to CMake (CONFIGURE_FILE, source file ...) because it will lead
12062 to an infinite loop. Use configure_file() if you want to generate in‐
12063 put files to CMake.
12064
12066 2000-2022 Kitware, Inc. and Contributors
120673.22.2 Jan 25, 2022 CMAKE-COMMANDS(7)