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 and the following signature is used.
4856 if(<variable|string>)
4858 True if given a variable that is defined to a value that is not
4859 a false constant. False otherwise. (Note macro arguments are
4860 not variables.)
4861 Logic Operators
4863 if(NOT <condition>)
4864 True if the condition is not true.
4865 if(<cond1> AND <cond2>)
4867 True if both conditions would be considered true individually.
4868 if(<cond1> OR <cond2>)
4870 True if either condition would be considered true individually.
4871 if((condition) AND (condition OR (condition)))
4873 The conditions inside the parenthesis are evaluated first and
4874 then the remaining condition is evaluated as in the other exam‐
4875 ples. Where there are nested parenthesis the innermost are
4876 evaluated as part of evaluating the condition that contains
4877 them.
4878 Existence Checks
4880 if(COMMAND command-name)
4881 True if the given name is a command, macro or function that can
4882 be invoked.
4883 if(POLICY policy-id)
4885 True if the given name is an existing policy (of the form
4886 CMP<NNNN>).
4887 if(TARGET target-name)
4889 True if the given name is an existing logical target name cre‐
4890 ated by a call to the add_executable(), add_library(), or
4891 add_custom_target() command that has already been invoked (in
4892 any directory).
4893 if(TEST test-name)
4895 New in version 3.3: True if the given name is an existing test
4896 name created by the add_test() command.
4897 if(DEFINED <name>|CACHE{<name>}|ENV{<name>})
4900 True if a variable, cache variable or environment variable with
4901 given <name> is defined. The value of the variable does not mat‐
4902 ter. Note that macro arguments are not variables.
4903 New in version 3.14: Added support for CACHE{<name>} variables.
4905 if(<variable|string> IN_LIST <variable>)
4908 New in version 3.3: True if the given element is contained in
4909 the named list variable.
4910 File Operations
4913 if(EXISTS path-to-file-or-directory)
4914 True if the named file or directory exists. Behavior is
4915 well-defined only for explicit full paths (a leading ~/ is not
4916 expanded as a home directory and is considered a relative path).
4917 Resolves symbolic links, i.e. if the named file or directory is
4918 a symbolic link, returns true if the target of the symbolic link
4919 exists.
4920 if(file1 IS_NEWER_THAN file2)
4922 True if file1 is newer than file2 or if one of the two files
4923 doesn't exist. Behavior is well-defined only for full paths.
4924 If the file time stamps are exactly the same, an IS_NEWER_THAN
4925 comparison returns true, so that any dependent build operations
4926 will occur in the event of a tie. This includes the case of
4927 passing the same file name for both file1 and file2.
4928 if(IS_DIRECTORY path-to-directory)
4930 True if the given name is a directory. Behavior is well-defined
4931 only for full paths.
4932 if(IS_SYMLINK file-name)
4934 True if the given name is a symbolic link. Behavior is well-de‐
4935 fined only for full paths.
4936 if(IS_ABSOLUTE path)
4938 True if the given path is an absolute path. Note the following
4939 special cases:
4940 • An empty path evaluates to false.
4942 • On Windows hosts, any path that begins with a drive letter and
4944 colon (e.g. C:), a forward slash or a backslash will evaluate
4945 to true. This means a path like C:no\base\dir will evaluate
4946 to true, even though the non-drive part of the path is rela‐
4947 tive.
4948 • On non-Windows hosts, any path that begins with a tilde (~)
4950 evaluates to true.
4951 Comparisons
4953 if(<variable|string> MATCHES regex)
4954 True if the given string or variable's value matches the given
4955 regular expression. See Regex Specification for regex format.
4956 New in version 3.9: () groups are captured in CMAKE_MATCH_<n>
4958 variables.
4959 if(<variable|string> LESS <variable|string>)
4962 True if the given string or variable's value is a valid number
4963 and less than that on the right.
4964 if(<variable|string> GREATER <variable|string>)
4966 True if the given string or variable's value is a valid number
4967 and greater than that on the right.
4968 if(<variable|string> EQUAL <variable|string>)
4970 True if the given string or variable's value is a valid number
4971 and equal to that on the right.
4972 if(<variable|string> LESS_EQUAL <variable|string>)
4974 New in version 3.7: True if the given string or variable's value
4975 is a valid number and less than or equal to that on the right.
4976 if(<variable|string> GREATER_EQUAL <variable|string>)
4979 New in version 3.7: True if the given string or variable's value
4980 is a valid number and greater than or equal to that on the
4981 right.
4982 if(<variable|string> STRLESS <variable|string>)
4985 True if the given string or variable's value is lexicographi‐
4986 cally less than the string or variable on the right.
4987 if(<variable|string> STRGREATER <variable|string>)
4989 True if the given string or variable's value is lexicographi‐
4990 cally greater than the string or variable on the right.
4991 if(<variable|string> STREQUAL <variable|string>)
4993 True if the given string or variable's value is lexicographi‐
4994 cally equal to the string or variable on the right.
4995 if(<variable|string> STRLESS_EQUAL <variable|string>)
4997 New in version 3.7: True if the given string or variable's value
4998 is lexicographically less than or equal to the string or vari‐
4999 able on the right.
5000 if(<variable|string> STRGREATER_EQUAL <variable|string>)
5003 New in version 3.7: True if the given string or variable's value
5004 is lexicographically greater than or equal to the string or
5005 variable on the right.
5006 Version Comparisons
5009 if(<variable|string> VERSION_LESS <variable|string>)
5010 Component-wise integer version number comparison (version format
5011 is major[.minor[.patch[.tweak]]], omitted components are treated
5012 as zero). Any non-integer version component or non-integer
5013 trailing part of a version component effectively truncates the
5014 string at that point.
5015 if(<variable|string> VERSION_GREATER <variable|string>)
5017 Component-wise integer version number comparison (version format
5018 is major[.minor[.patch[.tweak]]], omitted components are treated
5019 as zero). Any non-integer version component or non-integer
5020 trailing part of a version component effectively truncates the
5021 string at that point.
5022 if(<variable|string> VERSION_EQUAL <variable|string>)
5024 Component-wise integer version number comparison (version format
5025 is major[.minor[.patch[.tweak]]], omitted components are treated
5026 as zero). Any non-integer version component or non-integer
5027 trailing part of a version component effectively truncates the
5028 string at that point.
5029 if(<variable|string> VERSION_LESS_EQUAL <variable|string>)
5031 New in version 3.7: Component-wise integer version number com‐
5032 parison (version format is major[.minor[.patch[.tweak]]], omit‐
5033 ted components are treated as zero). Any non-integer version
5034 component or non-integer trailing part of a version component
5035 effectively truncates the string at that point.
5036 if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)
5039 New in version 3.7: Component-wise integer version number com‐
5040 parison (version format is major[.minor[.patch[.tweak]]], omit‐
5041 ted components are treated as zero). Any non-integer version
5042 component or non-integer trailing part of a version component
5043 effectively truncates the string at that point.
5044 Variable Expansion
5047 The if command was written very early in CMake's history, predating the
5048 ${} variable evaluation syntax, and for convenience evaluates variables
5049 named by its arguments as shown in the above signatures. Note that
5050 normal variable evaluation with ${} applies before the if command even
5051 receives the arguments. Therefore code like
5052 set(var1 OFF)
5054 set(var2 "var1")
5055 if(${var2})
5056 appears to the if command as
5058 if(var1)
5060 and is evaluated according to the if(<variable>) case documented above.
5062 The result is OFF which is false. However, if we remove the ${} from
5063 the example then the command sees
5064 if(var2)
5066 which is true because var2 is defined to var1 which is not a false con‐
5068 stant.
5069 Automatic evaluation applies in the other cases whenever the above-doc‐
5071 umented condition syntax accepts <variable|string>:
5072 • The left hand argument to MATCHES is first checked to see if it is a
5074 defined variable, if so the variable's value is used, otherwise the
5075 original value is used.
5076 • If the left hand argument to MATCHES is missing it returns false
5078 without error
5079 • Both left and right hand arguments to LESS, GREATER, EQUAL,
5081 LESS_EQUAL, and GREATER_EQUAL, are independently tested to see if
5082 they are defined variables, if so their defined values are used oth‐
5083 erwise the original value is used.
5084 • Both left and right hand arguments to STRLESS, STRGREATER, STREQUAL,
5086 STRLESS_EQUAL, and STRGREATER_EQUAL are independently tested to see
5087 if they are defined variables, if so their defined values are used
5088 otherwise the original value is used.
5089 • Both left and right hand arguments to VERSION_LESS, VERSION_GREATER,
5091 VERSION_EQUAL, VERSION_LESS_EQUAL, and VERSION_GREATER_EQUAL are in‐
5092 dependently tested to see if they are defined variables, if so their
5093 defined values are used otherwise the original value is used.
5094 • The right hand argument to NOT is tested to see if it is a boolean
5096 constant, if so the value is used, otherwise it is assumed to be a
5097 variable and it is dereferenced.
5098 • The left and right hand arguments to AND and OR are independently
5100 tested to see if they are boolean constants, if so they are used as
5101 such, otherwise they are assumed to be variables and are derefer‐
5102 enced.
5103 Changed in version 3.1: To prevent ambiguity, potential variable or
5105 keyword names can be specified in a Quoted Argument or a Bracket Argu‐
5106 ment. A quoted or bracketed variable or keyword will be interpreted as
5107 a string and not dereferenced or interpreted. See policy CMP0054.
5108 There is no automatic evaluation for environment or cache Variable Ref‐
5111 erences. Their values must be referenced as $ENV{<name>} or
5112 $CACHE{<name>} wherever the above-documented condition syntax accepts
5113 <variable|string>.
5114 include
5116 Load and run CMake code from a file or module.
5117 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
5119 [NO_POLICY_SCOPE])
5120 Loads and runs CMake code from the file given. Variable reads and
5122 writes access the scope of the caller (dynamic scoping). If OPTIONAL
5123 is present, then no error is raised if the file does not exist. If RE‐
5124 SULT_VARIABLE is given the variable <var> will be set to the full file‐
5125 name which has been included or NOTFOUND if it failed.
5126 If a module is specified instead of a file, the file with name <module‐
5128 name>.cmake is searched first in CMAKE_MODULE_PATH, then in the CMake
5129 module directory. There is one exception to this: if the file which
5130 calls include() is located itself in the CMake builtin module direc‐
5131 tory, then first the CMake builtin module directory is searched and
5132 CMAKE_MODULE_PATH afterwards. See also policy CMP0017.
5133 See the cmake_policy() command documentation for discussion of the
5135 NO_POLICY_SCOPE option.
5136 include_guard
5138 New in version 3.10.
5139 Provides an include guard for the file currently being processed by
5142 CMake.
5143 include_guard([DIRECTORY|GLOBAL])
5145 Sets up an include guard for the current CMake file (see the CMAKE_CUR‐
5147 RENT_LIST_FILE variable documentation).
5148 CMake will end its processing of the current file at the location of
5150 the include_guard() command if the current file has already been pro‐
5151 cessed for the applicable scope (see below). This provides functional‐
5152 ity similar to the include guards commonly used in source headers or to
5153 the #pragma once directive. If the current file has been processed pre‐
5154 viously for the applicable scope, the effect is as though return() had
5155 been called. Do not call this command from inside a function being de‐
5156 fined within the current file.
5157 An optional argument specifying the scope of the guard may be provided.
5159 Possible values for the option are:
5160 DIRECTORY
5162 The include guard applies within the current directory and be‐
5163 low. The file will only be included once within this directory
5164 scope, but may be included again by other files outside of this
5165 directory (i.e. a parent directory or another directory not
5166 pulled in by add_subdirectory() or include() from the current
5167 file or its children).
5168 GLOBAL The include guard applies globally to the whole build. The cur‐
5170 rent file will only be included once regardless of the scope.
5171 If no arguments given, include_guard has the same scope as a variable,
5173 meaning that the include guard effect is isolated by the most recent
5174 function scope or current directory if no inner function scopes exist.
5175 In this case the command behavior is the same as:
5176 if(__CURRENT_FILE_VAR__)
5178 return()
5179 endif()
5180 set(__CURRENT_FILE_VAR__ TRUE)
5181 list
5183 List operations.
5184 Synopsis
5186 Reading
5187 list(LENGTH <list> <out-var>)
5188 list(GET <list> <element index> [<index> ...] <out-var>)
5189 list(JOIN <list> <glue> <out-var>)
5190 list(SUBLIST <list> <begin> <length> <out-var>)
5191 Search
5193 list(FIND <list> <value> <out-var>)
5194 Modification
5196 list(APPEND <list> [<element>...])
5197 list(FILTER <list> {INCLUDE | EXCLUDE} REGEX <regex>)
5198 list(INSERT <list> <index> [<element>...])
5199 list(POP_BACK <list> [<out-var>...])
5200 list(POP_FRONT <list> [<out-var>...])
5201 list(PREPEND <list> [<element>...])
5202 list(REMOVE_ITEM <list> <value>...)
5203 list(REMOVE_AT <list> <index>...)
5204 list(REMOVE_DUPLICATES <list>)
5205 list(TRANSFORM <list> <ACTION> [...])
5206 Ordering
5208 list(REVERSE <list>)
5209 list(SORT <list> [...])
5210 Introduction
5212 The list subcommands APPEND, INSERT, FILTER, PREPEND, POP_BACK,
5213 POP_FRONT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, REVERSE and SORT
5214 may create new values for the list within the current CMake variable
5215 scope. Similar to the set() command, the LIST command creates new
5216 variable values in the current scope, even if the list itself is actu‐
5217 ally defined in a parent scope. To propagate the results of these op‐
5218 erations upwards, use set() with PARENT_SCOPE, set() with CACHE INTER‐
5219 NAL, or some other means of value propagation.
5220 NOTE:
5222 A list in cmake is a ; separated group of strings. To create a list
5223 the set command can be used. For example, set(var a b c d e) cre‐
5224 ates a list with a;b;c;d;e, and set(var "a b c d e") creates a
5225 string or a list with one item in it. (Note macro arguments are
5226 not variables, and therefore cannot be used in LIST commands.)
5227 NOTE:
5229 When specifying index values, if <element index> is 0 or greater, it
5230 is indexed from the beginning of the list, with 0 representing the
5231 first list element. If <element index> is -1 or lesser, it is in‐
5232 dexed from the end of the list, with -1 representing the last list
5233 element. Be careful when counting with negative indices: they do
5234 not start from 0. -0 is equivalent to 0, the first list element.
5235 Reading
5237 list(LENGTH <list> <output variable>)
5238 Returns the list's length.
5240 list(GET <list> <element index> [<element index> ...] <output variable>)
5242 Returns the list of elements specified by indices from the list.
5244 list(JOIN <list> <glue> <output variable>)
5246 New in version 3.12.
5248 Returns a string joining all list's elements using the glue string. To
5251 join multiple strings, which are not part of a list, use JOIN operator
5252 from string() command.
5253 list(SUBLIST <list> <begin> <length> <output variable>)
5255 New in version 3.12.
5257 Returns a sublist of the given list. If <length> is 0, an empty list
5260 will be returned. If <length> is -1 or the list is smaller than <be‐
5261 gin>+<length> then the remaining elements of the list starting at <be‐
5262 gin> will be returned.
5263 Search
5265 list(FIND <list> <value> <output variable>)
5266 Returns the index of the element specified in the list or -1 if it
5268 wasn't found.
5269 Modification
5271 list(APPEND <list> [<element> ...])
5272 Appends elements to the list.
5274 list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
5276 New in version 3.6.
5278 Includes or removes items from the list that match the mode's pattern.
5281 In REGEX mode, items will be matched against the given regular expres‐
5282 sion.
5283 For more information on regular expressions look under string(REGEX).
5285 list(INSERT <list> <element_index> <element> [<element> ...])
5287 Inserts elements to the list to the specified location.
5289 list(POP_BACK <list> [<out-var>...])
5291 New in version 3.15.
5293 If no variable name is given, removes exactly one element. Otherwise,
5296 with N variable names provided, assign the last N elements' values to
5297 the given variables and then remove the last N values from <list>.
5298 list(POP_FRONT <list> [<out-var>...])
5300 New in version 3.15.
5302 If no variable name is given, removes exactly one element. Otherwise,
5305 with N variable names provided, assign the first N elements' values to
5306 the given variables and then remove the first N values from <list>.
5307 list(PREPEND <list> [<element> ...])
5309 New in version 3.15.
5311 Insert elements to the 0th position in the list.
5314 list(REMOVE_ITEM <list> <value> [<value> ...])
5316 Removes all instances of the given items from the list.
5318 list(REMOVE_AT <list> <index> [<index> ...])
5320 Removes items at given indices from the list.
5322 list(REMOVE_DUPLICATES <list>)
5324 Removes duplicated items in the list. The relative order of items is
5326 preserved, but if duplicates are encountered, only the first instance
5327 is preserved.
5328 list(TRANSFORM <list> <ACTION> [<SELECTOR>]
5330 [OUTPUT_VARIABLE <output variable>])
5331 New in version 3.12.
5333 Transforms the list by applying an action to all or, by specifying a
5336 <SELECTOR>, to the selected elements of the list, storing the result
5337 in-place or in the specified output variable.
5338 NOTE:
5340 The TRANSFORM sub-command does not change the number of elements in
5341 the list. If a <SELECTOR> is specified, only some elements will be
5342 changed, the other ones will remain the same as before the transfor‐
5343 mation.
5344 <ACTION> specifies the action to apply to the elements of the list.
5346 The actions have exactly the same semantics as sub-commands of the
5347 string() command. <ACTION> must be one of the following:
5348 APPEND, PREPEND: Append, prepend specified value to each element of the
5350 list.
5351 list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
5353 TOUPPER, TOLOWER: Convert each element of the list to upper, lower
5355 characters.
5356 list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
5358 STRIP: Remove leading and trailing spaces from each element of the
5360 list.
5361 list(TRANSFORM <list> STRIP ...)
5363 GENEX_STRIP: Strip any generator expressions from each element of the
5365 list.
5366 list(TRANSFORM <list> GENEX_STRIP ...)
5368 REPLACE: Match the regular expression as many times as possible and
5370 substitute the replacement expression for the match for each element of
5371 the list (Same semantic as REGEX REPLACE from string() command).
5372 list(TRANSFORM <list> REPLACE <regular_expression>
5374 <replace_expression> ...)
5375 <SELECTOR> determines which elements of the list will be transformed.
5377 Only one type of selector can be specified at a time. When given, <SE‐
5378 LECTOR> must be one of the following:
5379 AT: Specify a list of indexes.
5381 list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
5383 FOR: Specify a range with, optionally, an increment used to iterate
5385 over the range.
5386 list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
5388 REGEX: Specify a regular expression. Only elements matching the regular
5390 expression will be transformed.
5391 list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
5393 Ordering
5395 list(REVERSE <list>)
5396 Reverses the contents of the list in-place.
5398 list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
5400 Sorts the list in-place alphabetically.
5402 New in version 3.13: Added the COMPARE, CASE, and ORDER options.
5404 New in version 3.18: Added the COMPARE NATURAL option.
5407 Use the COMPARE keyword to select the comparison method for sorting.
5410 The <compare> option should be one of:
5411 • STRING: Sorts a list of strings alphabetically. This is the default
5413 behavior if the COMPARE option is not given.
5414 • FILE_BASENAME: Sorts a list of pathnames of files by their basenames.
5416 • NATURAL: Sorts a list of strings using natural order (see strver‐
5418 scmp(3) manual), i.e. such that contiguous digits are compared as
5419 whole numbers. For example: the following list 10.0 1.1 2.1 8.0 2.0
5420 3.1 will be sorted as 1.1 2.0 2.1 3.1 8.0 10.0 if the NATURAL compar‐
5421 ison is selected where it will be sorted as 1.1 10.0 2.0 2.1 3.1 8.0
5422 with the STRING comparison.
5423 Use the CASE keyword to select a case sensitive or case insensitive
5425 sort mode. The <case> option should be one of:
5426 • SENSITIVE: List items are sorted in a case-sensitive manner. This is
5428 the default behavior if the CASE option is not given.
5429 • INSENSITIVE: List items are sorted case insensitively. The order of
5431 items which differ only by upper/lowercase is not specified.
5432 To control the sort order, the ORDER keyword can be given. The <order>
5434 option should be one of:
5435 • ASCENDING: Sorts the list in ascending order. This is the default
5437 behavior when the ORDER option is not given.
5438 • DESCENDING: Sorts the list in descending order.
5440 macro
5442 Start recording a macro for later invocation as a command
5443 macro(<name> [<arg1> ...])
5445 <commands>
5446 endmacro()
5447 Defines a macro named <name> that takes arguments named <arg1>, ...
5449 Commands listed after macro, but before the matching endmacro(), are
5450 not executed until the macro is invoked.
5451 Per legacy, the endmacro() command admits an optional <name> argument.
5453 If used, it must be a verbatim repeat of the argument of the opening
5454 macro command.
5455 See the cmake_policy() command documentation for the behavior of poli‐
5457 cies inside macros.
5458 See the Macro vs Function section below for differences between CMake
5460 macros and functions.
5461 Invocation
5463 The macro invocation is case-insensitive. A macro defined as
5464 macro(foo)
5466 <commands>
5467 endmacro()
5468 can be invoked through any of
5470 foo()
5472 Foo()
5473 FOO()
5474 cmake_language(CALL foo)
5475 and so on. However, it is strongly recommended to stay with the case
5477 chosen in the macro definition. Typically macros use all-lowercase
5478 names.
5479 New in version 3.18: The cmake_language(CALL ...) command can also be
5481 used to invoke the macro.
5482 Arguments
5485 When a macro is invoked, the commands recorded in the macro are first
5486 modified by replacing formal parameters (${arg1}, ...) with the argu‐
5487 ments passed, and then invoked as normal commands.
5488 In addition to referencing the formal parameters you can reference the
5490 values ${ARGC} which will be set to the number of arguments passed into
5491 the function as well as ${ARGV0}, ${ARGV1}, ${ARGV2}, ... which will
5492 have the actual values of the arguments passed in. This facilitates
5493 creating macros with optional arguments.
5494 Furthermore, ${ARGV} holds the list of all arguments given to the macro
5496 and ${ARGN} holds the list of arguments past the last expected argu‐
5497 ment. Referencing to ${ARGV#} arguments beyond ${ARGC} have undefined
5498 behavior. Checking that ${ARGC} is greater than # is the only way to
5499 ensure that ${ARGV#} was passed to the function as an extra argument.
5500 Macro vs Function
5502 The macro command is very similar to the function() command. Nonethe‐
5503 less, there are a few important differences.
5504 In a function, ARGN, ARGC, ARGV and ARGV0, ARGV1, ... are true vari‐
5506 ables in the usual CMake sense. In a macro, they are not, they are
5507 string replacements much like the C preprocessor would do with a macro.
5508 This has a number of consequences, as explained in the Argument Caveats
5509 section below.
5510 Another difference between macros and functions is the control flow. A
5512 function is executed by transferring control from the calling statement
5513 to the function body. A macro is executed as if the macro body were
5514 pasted in place of the calling statement. This has the consequence
5515 that a return() in a macro body does not just terminate execution of
5516 the macro; rather, control is returned from the scope of the macro
5517 call. To avoid confusion, it is recommended to avoid return() in
5518 macros altogether.
5519 Unlike a function, the CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNC‐
5521 TION_LIST_DIR, CMAKE_CURRENT_FUNCTION_LIST_FILE, CMAKE_CURRENT_FUNC‐
5522 TION_LIST_LINE variables are not set for a macro.
5523 Argument Caveats
5525 Since ARGN, ARGC, ARGV, ARGV0 etc. are not variables, you will NOT be
5526 able to use commands like
5527 if(ARGV1) # ARGV1 is not a variable
5529 if(DEFINED ARGV2) # ARGV2 is not a variable
5530 if(ARGC GREATER 2) # ARGC is not a variable
5531 foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
5532 In the first case, you can use if(${ARGV1}). In the second and third
5534 case, the proper way to check if an optional variable was passed to the
5535 macro is to use if(${ARGC} GREATER 2). In the last case, you can use
5536 foreach(loop_var ${ARGN}) but this will skip empty arguments. If you
5537 need to include them, you can use
5538 set(list_var "${ARGN}")
5540 foreach(loop_var IN LISTS list_var)
5541 Note that if you have a variable with the same name in the scope from
5543 which the macro is called, using unreferenced names will use the exist‐
5544 ing variable instead of the arguments. For example:
5545 macro(bar)
5547 foreach(arg IN LISTS ARGN)
5548 <commands>
5549 endforeach()
5550 endmacro()
5551 function(foo)
5553 bar(x y z)
5554 endfunction()
5555 foo(a b c)
5557 Will loop over a;b;c and not over x;y;z as one might have expected. If
5559 you want true CMake variables and/or better CMake scope control you
5560 should look at the function command.
5561 mark_as_advanced
5563 Mark cmake cached variables as advanced.
5564 mark_as_advanced([CLEAR|FORCE] <var1> ...)
5566 Sets the advanced/non-advanced state of the named cached variables.
5568 An advanced variable will not be displayed in any of the cmake GUIs un‐
5570 less the show advanced option is on. In script mode, the ad‐
5571 vanced/non-advanced state has no effect.
5572 If the keyword CLEAR is given then advanced variables are changed back
5574 to unadvanced. If the keyword FORCE is given then the variables are
5575 made advanced. If neither FORCE nor CLEAR is specified, new values
5576 will be marked as advanced, but if a variable already has an ad‐
5577 vanced/non-advanced state, it will not be changed.
5578 Changed in version 3.17: Variables passed to this command which are not
5580 already in the cache are ignored. See policy CMP0102.
5581 math
5584 Evaluate a mathematical expression.
5585 math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])
5587 Evaluates a mathematical <expression> and sets <variable> to the re‐
5589 sulting value. The result of the expression must be representable as a
5590 64-bit signed integer.
5591 The mathematical expression must be given as a string (i.e. enclosed in
5593 double quotation marks). An example is "5 * (10 + 13)". Supported op‐
5594 erators are +, -, *, /, %, |, &, ^, ~, <<, >>, and (...); they have the
5595 same meaning as in C code.
5596 New in version 3.13: Hexadecimal numbers are recognized when prefixed
5598 with 0x, as in C code.
5599 New in version 3.13: The result is formatted according to the option
5602 OUTPUT_FORMAT, where <format> is one of
5603 HEXADECIMAL
5605 Hexadecimal notation as in C code, i. e. starting with "0x".
5606 DECIMAL
5608 Decimal notation. Which is also used if no OUTPUT_FORMAT option
5609 is specified.
5610 For example
5613 math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL) # value is set to "1000"
5615 math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL) # value is set to "0x3e8"
5616 message
5618 Log a message.
5619 Synopsis
5621 General messages
5622 message([<mode>] "message text" ...)
5623 Reporting checks
5625 message(<checkState> "message text" ...)
5626 General messages
5628 message([<mode>] "message text" ...)
5629 Record the specified message text in the log. If more than one message
5631 string is given, they are concatenated into a single message with no
5632 separator between the strings.
5633 The optional <mode> keyword determines the type of message, which in‐
5635 fluences the way the message is handled:
5636 FATAL_ERROR
5638 CMake Error, stop processing and generation.
5639 SEND_ERROR
5641 CMake Error, continue processing, but skip generation.
5642 WARNING
5644 CMake Warning, continue processing.
5645 AUTHOR_WARNING
5647 CMake Warning (dev), continue processing.
5648 DEPRECATION
5650 CMake Deprecation Error or Warning if variable CMAKE_ERROR_DEP‐
5651 RECATED or CMAKE_WARN_DEPRECATED is enabled, respectively, else
5652 no message.
5653 (none) or NOTICE
5655 Important message printed to stderr to attract user's attention.
5656 STATUS The main interesting messages that project users might be inter‐
5658 ested in. Ideally these should be concise, no more than a sin‐
5659 gle line, but still informative.
5660 VERBOSE
5662 Detailed informational messages intended for project users.
5663 These messages should provide additional details that won't be
5664 of interest in most cases, but which may be useful to those
5665 building the project when they want deeper insight into what's
5666 happening.
5667 DEBUG Detailed informational messages intended for developers working
5669 on the project itself as opposed to users who just want to build
5670 it. These messages will not typically be of interest to other
5671 users building the project and will often be closely related to
5672 internal implementation details.
5673 TRACE Fine-grained messages with very low-level implementation de‐
5675 tails. Messages using this log level would normally only be
5676 temporary and would expect to be removed before releasing the
5677 project, packaging up the files, etc.
5678 New in version 3.15: Added the NOTICE, VERBOSE, DEBUG, and TRACE lev‐
5680 els.
5681 The CMake command-line tool displays STATUS to TRACE messages on stdout
5684 with the message preceded by two hyphens and a space. All other mes‐
5685 sage types are sent to stderr and are not prefixed with hyphens. The
5686 CMake GUI displays all messages in its log area. The curses interface
5687 shows STATUS to TRACE messages one at a time on a status line and other
5688 messages in an interactive pop-up box. The --log-level command-line
5689 option to each of these tools can be used to control which messages
5690 will be shown.
5691 New in version 3.17: To make a log level persist between CMake runs,
5693 the CMAKE_MESSAGE_LOG_LEVEL variable can be set instead. Note that the
5694 command line option takes precedence over the cache variable.
5695 New in version 3.16: Messages of log levels NOTICE and below will have
5698 each line preceded by the content of the CMAKE_MESSAGE_INDENT variable
5699 (converted to a single string by concatenating its list items). For
5700 STATUS to TRACE messages, this indenting content will be inserted after
5701 the hyphens.
5702 New in version 3.17: Messages of log levels NOTICE and below can also
5705 have each line preceded with context of the form [some.context.exam‐
5706 ple]. The content between the square brackets is obtained by convert‐
5707 ing the CMAKE_MESSAGE_CONTEXT list variable to a dot-separated string.
5708 The message context will always appear before any indenting content but
5709 after any automatically added leading hyphens. By default, message con‐
5710 text is not shown, it has to be explicitly enabled by giving the cmake
5711 --log-context command-line option or by setting the CMAKE_MESSAGE_CON‐
5712 TEXT_SHOW variable to true. See the CMAKE_MESSAGE_CONTEXT documenta‐
5713 tion for usage examples.
5714 CMake Warning and Error message text displays using a simple markup
5717 language. Non-indented text is formatted in line-wrapped paragraphs
5718 delimited by newlines. Indented text is considered pre-formatted.
5719 Reporting checks
5721 New in version 3.17.
5722 A common pattern in CMake output is a message indicating the start of
5725 some sort of check, followed by another message reporting the result of
5726 that check. For example:
5727 message(STATUS "Looking for someheader.h")
5729 #... do the checks, set checkSuccess with the result
5730 if(checkSuccess)
5731 message(STATUS "Looking for someheader.h - found")
5732 else()
5733 message(STATUS "Looking for someheader.h - not found")
5734 endif()
5735 This can be more robustly and conveniently expressed using the
5737 CHECK_... keyword form of the message() command:
5738 message(<checkState> "message" ...)
5740 where <checkState> must be one of the following:
5742 CHECK_START
5744 Record a concise message about the check about to be per‐
5745 formed.
5746 CHECK_PASS
5748 Record a successful result for a check.
5749 CHECK_FAIL
5751 Record an unsuccessful result for a check.
5752 When recording a check result, the command repeats the message from the
5754 most recently started check for which no result has yet been reported,
5755 then some separator characters and then the message text provided after
5756 the CHECK_PASS or CHECK_FAIL keyword. Check messages are always re‐
5757 ported at STATUS log level.
5758 Checks may be nested and every CHECK_START should have exactly one
5760 matching CHECK_PASS or CHECK_FAIL. The CMAKE_MESSAGE_INDENT variable
5761 can also be used to add indenting to nested checks if desired. For ex‐
5762 ample:
5763 message(CHECK_START "Finding my things")
5765 list(APPEND CMAKE_MESSAGE_INDENT " ")
5766 unset(missingComponents)
5767 message(CHECK_START "Finding partA")
5769 # ... do check, assume we find A
5770 message(CHECK_PASS "found")
5771 message(CHECK_START "Finding partB")
5773 # ... do check, assume we don't find B
5774 list(APPEND missingComponents B)
5775 message(CHECK_FAIL "not found")
5776 list(POP_BACK CMAKE_MESSAGE_INDENT)
5778 if(missingComponents)
5779 message(CHECK_FAIL "missing components: ${missingComponents}")
5780 else()
5781 message(CHECK_PASS "all components found")
5782 endif()
5783 Output from the above would appear something like the following:
5785 -- Finding my things
5787 -- Finding partA
5788 -- Finding partA - found
5789 -- Finding partB
5790 -- Finding partB - not found
5791 -- Finding my things - missing components: B
5792 option
5794 Provide an option that the user can optionally select.
5795 option(<variable> "<help_text>" [value])
5797 Provides an option for the user to select as ON or OFF. If no initial
5799 <value> is provided, OFF is used. If <variable> is already set as a
5800 normal or cache variable, then the command does nothing (see policy
5801 CMP0077).
5802 If you have options that depend on the values of other options, see the
5804 module help for CMakeDependentOption.
5805 return
5807 Return from a file, directory or function.
5808 return()
5810 Returns from a file, directory or function. When this command is en‐
5812 countered in an included file (via include() or find_package()), it
5813 causes processing of the current file to stop and control is returned
5814 to the including file. If it is encountered in a file which is not in‐
5815 cluded by another file, e.g. a CMakeLists.txt, deferred calls sched‐
5816 uled by cmake_language(DEFER) are invoked and control is returned to
5817 the parent directory if there is one. If return is called in a func‐
5818 tion, control is returned to the caller of the function.
5819 Note that a macro, unlike a function, is expanded in place and there‐
5821 fore cannot handle return().
5822 separate_arguments
5824 Parse command-line arguments into a semicolon-separated list.
5825 separate_arguments(<variable> <mode> [PROGRAM [SEPARATE_ARGS]] <args>)
5827 Parses a space-separated string <args> into a list of items, and stores
5829 this list in semicolon-separated standard form in <variable>.
5830 This function is intended for parsing command-line arguments. The en‐
5832 tire command line must be passed as one string in the argument <args>.
5833 The exact parsing rules depend on the operating system. They are spec‐
5835 ified by the <mode> argument which must be one of the following key‐
5836 words:
5837 UNIX_COMMAND
5839 Arguments are separated by unquoted whitespace. Both sin‐
5840 gle-quote and double-quote pairs are respected. A backslash es‐
5841 capes the next literal character (\" is "); there are no special
5842 escapes (\n is just n).
5843 WINDOWS_COMMAND
5845 A Windows command-line is parsed using the same syntax the run‐
5846 time library uses to construct argv at startup. It separates
5847 arguments by whitespace that is not double-quoted. Backslashes
5848 are literal unless they precede double-quotes. See the MSDN ar‐
5849 ticle Parsing C Command-Line Arguments for details.
5850 NATIVE_COMMAND
5852 New in version 3.9.
5853 Proceeds as in WINDOWS_COMMAND mode if the host system is Win‐
5856 dows. Otherwise proceeds as in UNIX_COMMAND mode.
5857 PROGRAM
5859 New in version 3.19.
5860 The first item in <args> is assumed to be an executable and will
5863 be searched in the system search path or left as a full path. If
5864 not found, <variable> will be empty. Otherwise, <variable> is a
5865 list of 2 elements:
5866 0. Absolute path of the program
5868 1. Any command-line arguments present in <args> as a string
5870 For example:
5872 separate_arguments (out UNIX_COMMAND PROGRAM "cc -c main.c")
5874 • First element of the list: /path/to/cc
5876 • Second element of the list: " -c main.c"
5878 SEPARATE_ARGS
5880 When this sub-option of PROGRAM option is specified, com‐
5881 mand-line arguments will be split as well and stored in <vari‐
5882 able>.
5883 For example:
5885 separate_arguments (out UNIX_COMMAND PROGRAM SEPARATE_ARGS "cc -c main.c")
5887 The contents of out will be: /path/to/cc;-c;main.c
5889 separate_arguments(<var>)
5891 Convert the value of <var> to a semi-colon separated list. All spaces
5893 are replaced with ';'. This helps with generating command lines.
5894 set
5896 Set a normal, cache, or environment variable to a given value. See the
5897 cmake-language(7) variables documentation for the scopes and interac‐
5898 tion of normal variables and cache entries.
5899 Signatures of this command that specify a <value>... placeholder expect
5901 zero or more arguments. Multiple arguments will be joined as a semi‐
5902 colon-separated list to form the actual variable value to be set. Zero
5903 arguments will cause normal variables to be unset. See the unset()
5904 command to unset variables explicitly.
5905 Set Normal Variable
5907 set(<variable> <value>... [PARENT_SCOPE])
5908 Sets the given <variable> in the current function or directory scope.
5910 If the PARENT_SCOPE option is given the variable will be set in the
5912 scope above the current scope. Each new directory or function creates
5913 a new scope. This command will set the value of a variable into the
5914 parent directory or calling function (whichever is applicable to the
5915 case at hand). The previous state of the variable's value stays the
5916 same in the current scope (e.g., if it was undefined before, it is
5917 still undefined and if it had a value, it is still that value).
5918 Set Cache Entry
5920 set(<variable> <value>... CACHE <type> <docstring> [FORCE])
5921 Sets the given cache <variable> (cache entry). Since cache entries are
5923 meant to provide user-settable values this does not overwrite existing
5924 cache entries by default. Use the FORCE option to overwrite existing
5925 entries.
5926 The <type> must be specified as one of:
5928 BOOL Boolean ON/OFF value. cmake-gui(1) offers a checkbox.
5930 FILEPATH
5932 Path to a file on disk. cmake-gui(1) offers a file dialog.
5933 PATH Path to a directory on disk. cmake-gui(1) offers a file dialog.
5935 STRING A line of text. cmake-gui(1) offers a text field or a drop-down
5937 selection if the STRINGS cache entry property is set.
5938 INTERNAL
5940 A line of text. cmake-gui(1) does not show internal entries.
5941 They may be used to store variables persistently across runs.
5942 Use of this type implies FORCE.
5943 The <docstring> must be specified as a line of text providing a quick
5945 summary of the option for presentation to cmake-gui(1) users.
5946 If the cache entry does not exist prior to the call or the FORCE option
5948 is given then the cache entry will be set to the given value.
5949 NOTE:
5951 The content of the cache variable will not be directly accessible if
5952 a normal variable of the same name already exists (see rules of
5953 variable evaluation). If policy CMP0126 is set to OLD, any normal
5954 variable binding in the current scope will be removed.
5955 It is possible for the cache entry to exist prior to the call but have
5957 no type set if it was created on the cmake(1) command line by a user
5958 through the -D<var>=<value> option without specifying a type. In this
5959 case the set command will add the type. Furthermore, if the <type> is
5960 PATH or FILEPATH and the <value> provided on the command line is a rel‐
5961 ative path, then the set command will treat the path as relative to the
5962 current working directory and convert it to an absolute path.
5963 Set Environment Variable
5965 set(ENV{<variable>} [<value>])
5966 Sets an Environment Variable to the given value. Subsequent calls of
5968 $ENV{<variable>} will return this new value.
5969 This command affects only the current CMake process, not the process
5971 from which CMake was called, nor the system environment at large, nor
5972 the environment of subsequent build or test processes.
5973 If no argument is given after ENV{<variable>} or if <value> is an empty
5975 string, then this command will clear any existing value of the environ‐
5976 ment variable.
5977 Arguments after <value> are ignored. If extra arguments are found, then
5979 an author warning is issued.
5980 set_directory_properties
5982 Set properties of the current directory and subdirectories.
5983 set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...)
5985 Sets properties of the current directory and its subdirectories in
5987 key-value pairs.
5988 See also the set_property(DIRECTORY) command.
5990 See Directory Properties for the list of properties known to CMake and
5992 their individual documentation for the behavior of each property.
5993 set_property
5995 Set a named property in a given scope.
5996 set_property(<GLOBAL |
5998 DIRECTORY [<dir>] |
5999 TARGET [<target1> ...] |
6000 SOURCE [<src1> ...]
6001 [DIRECTORY <dirs> ...]
6002 [TARGET_DIRECTORY <targets> ...] |
6003 INSTALL [<file1> ...] |
6004 TEST [<test1> ...] |
6005 CACHE [<entry1> ...] >
6006 [APPEND] [APPEND_STRING]
6007 PROPERTY <name> [<value1> ...])
6008 Sets one property on zero or more objects of a scope.
6010 The first argument determines the scope in which the property is set.
6012 It must be one of the following:
6013 GLOBAL Scope is unique and does not accept a name.
6015 DIRECTORY
6017 Scope defaults to the current directory but other directories
6018 (already processed by CMake) may be named by full or relative
6019 path. Relative paths are treated as relative to the current
6020 source directory. See also the set_directory_properties() com‐
6021 mand.
6022 New in version 3.19: <dir> may reference a binary directory.
6024 TARGET Scope may name zero or more existing targets. See also the
6027 set_target_properties() command.
6028 SOURCE Scope may name zero or more source files. By default, source
6030 file properties are only visible to targets added in the same
6031 directory (CMakeLists.txt).
6032 New in version 3.18: Visibility can be set in other directory
6034 scopes using one or both of the following sub-options:
6035 DIRECTORY <dirs>...
6037 The source file property will be set in each of the
6038 <dirs> directories' scopes. CMake must already know
6039 about each of these directories, either by having added
6040 them through a call to add_subdirectory() or it being the
6041 top level source directory. Relative paths are treated
6042 as relative to the current source directory.
6043 New in version 3.19: <dirs> may reference a binary direc‐
6045 tory.
6046 TARGET_DIRECTORY <targets>...
6049 The source file property will be set in each of the di‐
6050 rectory scopes where any of the specified <targets> were
6051 created (the <targets> must therefore already exist).
6052 See also the set_source_files_properties() command.
6055 INSTALL
6057 New in version 3.1.
6058 Scope may name zero or more installed file paths. These are
6061 made available to CPack to influence deployment.
6062 Both the property key and value may use generator expressions.
6064 Specific properties may apply to installed files and/or directo‐
6065 ries.
6066 Path components have to be separated by forward slashes, must be
6068 normalized and are case sensitive.
6069 To reference the installation prefix itself with a relative path
6071 use ..
6072 Currently installed file properties are only defined for the WIX
6074 generator where the given paths are relative to the installation
6075 prefix.
6076 TEST Scope may name zero or more existing tests. See also the
6078 set_tests_properties() command.
6079 CACHE Scope must name zero or more cache existing entries.
6081 The required PROPERTY option is immediately followed by the name of the
6083 property to set. Remaining arguments are used to compose the property
6084 value in the form of a semicolon-separated list.
6085 If the APPEND option is given the list is appended to any existing
6087 property value (except that empty values are ignored and not appended).
6088 If the APPEND_STRING option is given the string is appended to any ex‐
6089 isting property value as string, i.e. it results in a longer string and
6090 not a list of strings. When using APPEND or APPEND_STRING with a prop‐
6091 erty defined to support INHERITED behavior (see define_property()), no
6092 inheriting occurs when finding the initial value to append to. If the
6093 property is not already directly set in the nominated scope, the com‐
6094 mand will behave as though APPEND or APPEND_STRING had not been given.
6095 See the cmake-properties(7) manual for a list of properties in each
6097 scope.
6098 NOTE:
6100 The GENERATED source file property may be globally visible. See its
6101 documentation for details.
6102 site_name
6104 Set the given variable to the name of the computer.
6105 site_name(variable)
6107 On UNIX-like platforms, if the variable HOSTNAME is set, its value will
6109 be executed as a command expected to print out the host name, much like
6110 the hostname command-line tool.
6111 string
6113 String operations.
6114 Synopsis
6116 Search and Replace
6117 string(FIND <string> <substring> <out-var> [...])
6118 string(REPLACE <match-string> <replace-string> <out-var> <input>...)
6119 string(REGEX MATCH <match-regex> <out-var> <input>...)
6120 string(REGEX MATCHALL <match-regex> <out-var> <input>...)
6121 string(REGEX REPLACE <match-regex> <replace-expr> <out-var> <input>...)
6122 Manipulation
6124 string(APPEND <string-var> [<input>...])
6125 string(PREPEND <string-var> [<input>...])
6126 string(CONCAT <out-var> [<input>...])
6127 string(JOIN <glue> <out-var> [<input>...])
6128 string(TOLOWER <string> <out-var>)
6129 string(TOUPPER <string> <out-var>)
6130 string(LENGTH <string> <out-var>)
6131 string(SUBSTRING <string> <begin> <length> <out-var>)
6132 string(STRIP <string> <out-var>)
6133 string(GENEX_STRIP <string> <out-var>)
6134 string(REPEAT <string> <count> <out-var>)
6135 Comparison
6137 string(COMPARE <op> <string1> <string2> <out-var>)
6138 Hashing
6140 string(<HASH> <out-var> <input>)
6141 Generation
6143 string(ASCII <number>... <out-var>)
6144 string(HEX <string> <out-var>)
6145 string(CONFIGURE <string> <out-var> [...])
6146 string(MAKE_C_IDENTIFIER <string> <out-var>)
6147 string(RANDOM [<option>...] <out-var>)
6148 string(TIMESTAMP <out-var> [<format string>] [UTC])
6149 string(UUID <out-var> ...)
6150 JSON
6152 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
6153 {GET | TYPE | LENGTH | REMOVE}
6154 <json-string> <member|index> [<member|index> ...])
6155 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
6156 MEMBER <json-string>
6157 [<member|index> ...] <index>)
6158 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
6159 SET <json-string>
6160 <member|index> [<member|index> ...] <value>)
6161 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
6162 EQUAL <json-string1> <json-string2>)
6163 Search and Replace
6165 Search and Replace With Plain Strings
6166 string(FIND <string> <substring> <output_variable> [REVERSE])
6167 Return the position where the given <substring> was found in the sup‐
6169 plied <string>. If the REVERSE flag was used, the command will search
6170 for the position of the last occurrence of the specified <substring>.
6171 If the <substring> is not found, a position of -1 is returned.
6172 The string(FIND) subcommand treats all strings as ASCII-only charac‐
6174 ters. The index stored in <output_variable> will also be counted in
6175 bytes, so strings containing multi-byte characters may lead to unex‐
6176 pected results.
6177 string(REPLACE <match_string>
6179 <replace_string> <output_variable>
6180 <input> [<input>...])
6181 Replace all occurrences of <match_string> in the <input> with <re‐
6183 place_string> and store the result in the <output_variable>.
6184 Search and Replace With Regular Expressions
6186 string(REGEX MATCH <regular_expression>
6187 <output_variable> <input> [<input>...])
6188 Match the <regular_expression> once and store the match in the <out‐
6190 put_variable>. All <input> arguments are concatenated before matching.
6191 Regular expressions are specified in the subsection just below.
6192 string(REGEX MATCHALL <regular_expression>
6194 <output_variable> <input> [<input>...])
6195 Match the <regular_expression> as many times as possible and store the
6197 matches in the <output_variable> as a list. All <input> arguments are
6198 concatenated before matching.
6199 string(REGEX REPLACE <regular_expression>
6201 <replacement_expression> <output_variable>
6202 <input> [<input>...])
6203 Match the <regular_expression> as many times as possible and substitute
6205 the <replacement_expression> for the match in the output. All <input>
6206 arguments are concatenated before matching.
6207 The <replacement_expression> may refer to parenthesis-delimited subex‐
6209 pressions of the match using \1, \2, ..., \9. Note that two back‐
6210 slashes (\\1) are required in CMake code to get a backslash through ar‐
6211 gument parsing.
6212 Regex Specification
6214 The following characters have special meaning in regular expressions:
6215 ^ Matches at beginning of input
6217 $ Matches at end of input
6219 . Matches any single character
6221 \<char>
6223 Matches the single character specified by <char>. Use this to
6224 match special regex characters, e.g. \. for a literal . or \\
6225 for a literal backslash \. Escaping a non-special character is
6226 unnecessary but allowed, e.g. \a matches a.
6227 [ ] Matches any character(s) inside the brackets
6229 [^ ] Matches any character(s) not inside the brackets
6231 - Inside brackets, specifies an inclusive range between characters
6233 on either side e.g. [a-f] is [abcdef] To match a literal - using
6234 brackets, make it the first or the last character e.g. [+*/-]
6235 matches basic mathematical operators.
6236 * Matches preceding pattern zero or more times
6238 + Matches preceding pattern one or more times
6240 ? Matches preceding pattern zero or once only
6242 | Matches a pattern on either side of the |
6244 () Saves a matched subexpression, which can be referenced in the
6246 REGEX REPLACE operation.
6247 New in version 3.9: All regular expression-related commands, in‐
6249 cluding e.g. if(MATCHES), save subgroup matches in the vari‐
6250 ables CMAKE_MATCH_<n> for <n> 0..9.
6251 *, + and ? have higher precedence than concatenation. | has lower
6254 precedence than concatenation. This means that the regular expression
6255 ^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
6256 matches ab but not abd.
6257 CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
6259 to construct literal tabs, carriage returns, newlines, and backslashes
6260 (respectively) to pass in a regex. For example:
6261 • The quoted argument "[ \t\r\n]" specifies a regex that matches any
6263 single whitespace character.
6264 • The quoted argument "[/\\]" specifies a regex that matches a single
6266 forward slash / or backslash \.
6267 • The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
6269 single "word" character in the C locale.
6270 • The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
6272 the exact string (a+b). Each \\ is parsed in a quoted argument as
6273 just \, so the regex itself is actually \(\a\+\b\). This can alter‐
6274 natively be specified in a bracket argument without having to escape
6275 the backslashes, e.g. [[\(\a\+\b\)]].
6276 Manipulation
6278 string(APPEND <string_variable> [<input>...])
6279 New in version 3.4.
6281 Append all the <input> arguments to the string.
6284 string(PREPEND <string_variable> [<input>...])
6286 New in version 3.10.
6288 Prepend all the <input> arguments to the string.
6291 string(CONCAT <output_variable> [<input>...])
6293 Concatenate all the <input> arguments together and store the result in
6295 the named <output_variable>.
6296 string(JOIN <glue> <output_variable> [<input>...])
6298 New in version 3.12.
6300 Join all the <input> arguments together using the <glue> string and
6303 store the result in the named <output_variable>.
6304 To join a list's elements, prefer to use the JOIN operator from the
6306 list() command. This allows for the elements to have special charac‐
6307 ters like ; in them.
6308 string(TOLOWER <string> <output_variable>)
6310 Convert <string> to lower characters.
6312 string(TOUPPER <string> <output_variable>)
6314 Convert <string> to upper characters.
6316 string(LENGTH <string> <output_variable>)
6318 Store in an <output_variable> a given string's length in bytes. Note
6320 that this means if <string> contains multi-byte characters, the result
6321 stored in <output_variable> will not be the number of characters.
6322 string(SUBSTRING <string> <begin> <length> <output_variable>)
6324 Store in an <output_variable> a substring of a given <string>. If
6326 <length> is -1 the remainder of the string starting at <begin> will be
6327 returned.
6328 Changed in version 3.2: If <string> is shorter than <length> then the
6330 end of the string is used instead. Previous versions of CMake reported
6331 an error in this case.
6332 Both <begin> and <length> are counted in bytes, so care must be exer‐
6335 cised if <string> could contain multi-byte characters.
6336 string(STRIP <string> <output_variable>)
6338 Store in an <output_variable> a substring of a given <string> with
6340 leading and trailing spaces removed.
6341 string(GENEX_STRIP <string> <output_variable>)
6343 New in version 3.1.
6345 Strip any generator expressions from the input <string> and store the
6348 result in the <output_variable>.
6349 string(REPEAT <string> <count> <output_variable>)
6351 New in version 3.15.
6353 Produce the output string as the input <string> repeated <count> times.
6356 Comparison
6358 string(COMPARE LESS <string1> <string2> <output_variable>)
6359 string(COMPARE GREATER <string1> <string2> <output_variable>)
6360 string(COMPARE EQUAL <string1> <string2> <output_variable>)
6361 string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
6362 string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
6363 string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
6364 Compare the strings and store true or false in the <output_variable>.
6366 New in version 3.7: Added the LESS_EQUAL and GREATER_EQUAL options.
6368 Hashing
6371 string(<HASH> <output_variable> <input>)
6372 Compute a cryptographic hash of the <input> string. The supported
6374 <HASH> algorithm names are:
6375 MD5 Message-Digest Algorithm 5, RFC 1321.
6377 SHA1 US Secure Hash Algorithm 1, RFC 3174.
6379 SHA224 US Secure Hash Algorithms, RFC 4634.
6381 SHA256 US Secure Hash Algorithms, RFC 4634.
6383 SHA384 US Secure Hash Algorithms, RFC 4634.
6385 SHA512 US Secure Hash Algorithms, RFC 4634.
6387 SHA3_224
6389 Keccak SHA-3.
6390 SHA3_256
6392 Keccak SHA-3.
6393 SHA3_384
6395 Keccak SHA-3.
6396 SHA3_512
6398 Keccak SHA-3.
6399 New in version 3.8: Added the SHA3_* hash algorithms.
6401 Generation
6404 string(ASCII <number> [<number> ...] <output_variable>)
6405 Convert all numbers into corresponding ASCII characters.
6407 string(HEX <string> <output_variable>)
6409 New in version 3.18.
6411 Convert each byte in the input <string> to its hexadecimal representa‐
6414 tion and store the concatenated hex digits in the <output_variable>.
6415 Letters in the output (a through f) are in lowercase.
6416 string(CONFIGURE <string> <output_variable>
6418 [@ONLY] [ESCAPE_QUOTES])
6419 Transform a <string> like configure_file() transforms a file.
6421 string(MAKE_C_IDENTIFIER <string> <output_variable>)
6423 Convert each non-alphanumeric character in the input <string> to an un‐
6425 derscore and store the result in the <output_variable>. If the first
6426 character of the <string> is a digit, an underscore will also be
6427 prepended to the result.
6428 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
6430 [RANDOM_SEED <seed>] <output_variable>)
6431 Return a random string of given <length> consisting of characters from
6433 the given <alphabet>. Default length is 5 characters and default al‐
6434 phabet is all numbers and upper and lower case letters. If an integer
6435 RANDOM_SEED is given, its value will be used to seed the random number
6436 generator.
6437 string(TIMESTAMP <output_variable> [<format_string>] [UTC])
6439 Write a string representation of the current date and/or time to the
6441 <output_variable>.
6442 If the command is unable to obtain a timestamp, the <output_variable>
6444 will be set to the empty string "".
6445 The optional UTC flag requests the current date/time representation to
6447 be in Coordinated Universal Time (UTC) rather than local time.
6448 The optional <format_string> may contain the following format speci‐
6450 fiers:
6451 %% New in version 3.8.
6453 A literal percent sign (%).
6456 %d The day of the current month (01-31).
6458 %H The hour on a 24-hour clock (00-23).
6460 %I The hour on a 12-hour clock (01-12).
6462 %j The day of the current year (001-366).
6464 %m The month of the current year (01-12).
6466 %b New in version 3.7.
6468 Abbreviated month name (e.g. Oct).
6471 %B New in version 3.10.
6473 Full month name (e.g. October).
6476 %M The minute of the current hour (00-59).
6478 %s New in version 3.6.
6480 Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
6483 %S The second of the current minute. 60 represents a leap second.
6485 (00-60)
6486 %U The week number of the current year (00-53).
6488 %V New in version 3.22.
6490 The ISO 8601 week number of the current year (01-53).
6493 %w The day of the current week. 0 is Sunday. (0-6)
6495 %a New in version 3.7.
6497 Abbreviated weekday name (e.g. Fri).
6500 %A New in version 3.10.
6502 Full weekday name (e.g. Friday).
6505 %y The last two digits of the current year (00-99).
6507 %Y The current year.
6509 Unknown format specifiers will be ignored and copied to the output
6511 as-is.
6512 If no explicit <format_string> is given, it will default to:
6514 %Y-%m-%dT%H:%M:%S for local time.
6516 %Y-%m-%dT%H:%M:%SZ for UTC.
6517 New in version 3.8: If the SOURCE_DATE_EPOCH environment variable is
6519 set, its value will be used instead of the current time. See
6520 https://reproducible-builds.org/specs/source-date-epoch/ for details.
6521 string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
6524 TYPE <MD5|SHA1> [UPPER])
6525 New in version 3.1.
6527 Create a universally unique identifier (aka GUID) as per RFC4122 based
6530 on the hash of the combined values of <namespace> (which itself has to
6531 be a valid UUID) and <name>. The hash algorithm can be either MD5
6532 (Version 3 UUID) or SHA1 (Version 5 UUID). A UUID has the format
6533 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where each x represents a lower
6534 case hexadecimal character. Where required, an uppercase representa‐
6535 tion can be requested with the optional UPPER flag.
6536 JSON
6538 New in version 3.19.
6539 Functionality for querying a JSON string.
6542 NOTE:
6544 In each of the following JSON-related subcommands, if the optional
6545 ERROR_VARIABLE argument is given, errors will be reported in <er‐
6546 ror-variable> and the <out-var> will be set to <member|index>-[<mem‐
6547 ber|index>...]-NOTFOUND with the path elements up to the point where
6548 the error occurred, or just NOTFOUND if there is no relevant path.
6549 If an error occurs but the ERROR_VARIABLE option is not present, a
6550 fatal error message is generated. If no error occurs, the <er‐
6551 ror-variable> will be set to NOTFOUND.
6552 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
6554 GET <json-string> <member|index> [<member|index> ...])
6555 Get an element from <json-string> at the location given by the list of
6557 <member|index> arguments. Array and object elements will be returned
6558 as a JSON string. Boolean elements will be returned as ON or OFF.
6559 Null elements will be returned as an empty string. Number and string
6560 types will be returned as strings.
6561 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
6563 TYPE <json-string> <member|index> [<member|index> ...])
6564 Get the type of an element in <json-string> at the location given by
6566 the list of <member|index> arguments. The <out-var> will be set to one
6567 of NULL, NUMBER, STRING, BOOLEAN, ARRAY, or OBJECT.
6568 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
6570 MEMBER <json-string>
6571 [<member|index> ...] <index>)
6572 Get the name of the <index>-th member in <json-string> at the location
6574 given by the list of <member|index> arguments. Requires an element of
6575 object type.
6576 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
6578 LENGTH <json-string> <member|index> [<member|index> ...])
6579 Get the length of an element in <json-string> at the location given by
6581 the list of <member|index> arguments. Requires an element of array or
6582 object type.
6583 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
6585 REMOVE <json-string> <member|index> [<member|index> ...])
6586 Remove an element from <json-string> at the location given by the list
6588 of <member|index> arguments. The JSON string without the removed ele‐
6589 ment will be stored in <out-var>.
6590 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
6592 SET <json-string> <member|index> [<member|index> ...] <value>)
6593 Set an element in <json-string> at the location given by the list of
6595 <member|index> arguments to <value>. The contents of <value> should be
6596 valid JSON.
6597 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
6599 EQUAL <json-string1> <json-string2>)
6600 Compare the two JSON objects given by <json-string1> and <json-string2>
6602 for equality. The contents of <json-string1> and <json-string2> should
6603 be valid JSON. The <out-var> will be set to a true value if the JSON
6604 objects are considered equal, or a false value otherwise.
6605 unset
6607 Unset a variable, cache variable, or environment variable.
6608 Unset Normal Variable or Cache Entry
6610 unset(<variable> [CACHE | PARENT_SCOPE])
6611 Removes a normal variable from the current scope, causing it to become
6613 undefined. If CACHE is present, then a cache variable is removed in‐
6614 stead of a normal variable. Note that when evaluating Variable Refer‐
6615 ences of the form ${VAR}, CMake first searches for a normal variable
6616 with that name. If no such normal variable exists, CMake will then
6617 search for a cache entry with that name. Because of this unsetting a
6618 normal variable can expose a cache variable that was previously hidden.
6619 To force a variable reference of the form ${VAR} to return an empty
6620 string, use set(<variable> ""), which clears the normal variable but
6621 leaves it defined.
6622 If PARENT_SCOPE is present then the variable is removed from the scope
6624 above the current scope. See the same option in the set() command for
6625 further details.
6626 Unset Environment Variable
6628 unset(ENV{<variable>})
6629 Removes <variable> from the currently available Environment Variables.
6631 Subsequent calls of $ENV{<variable>} will return the empty string.
6632 This command affects only the current CMake process, not the process
6634 from which CMake was called, nor the system environment at large, nor
6635 the environment of subsequent build or test processes.
6636 variable_watch
6638 Watch the CMake variable for change.
6639 variable_watch(<variable> [<command>])
6641 If the specified <variable> changes and no <command> is given, a mes‐
6643 sage will be printed to inform about the change.
6644 If <command> is given, this command will be executed instead. The com‐
6646 mand will receive the following arguments: COMMAND(<variable> <access>
6647 <value> <current_list_file> <stack>)
6648 <variable>
6650 Name of the variable being accessed.
6651 <access>
6653 One of READ_ACCESS, UNKNOWN_READ_ACCESS, MODIFIED_ACCESS, UN‐
6654 KNOWN_MODIFIED_ACCESS, or REMOVED_ACCESS. The UNKNOWN_ values
6655 are only used when the variable has never been set. Once set,
6656 they are never used again during the same CMake run, even if the
6657 variable is later unset.
6658 <value>
6660 The value of the variable. On a modification, this is the new
6661 (modified) value of the variable. On removal, the value is
6662 empty.
6663 <current_list_file>
6665 Full path to the file doing the access.
6666 <stack>
6668 List of absolute paths of all files currently on the stack of
6669 file inclusion, with the bottom-most file first and the cur‐
6670 rently processed file (that is, current_list_file) last.
6671 Note that for some accesses such as list(APPEND), the watcher is exe‐
6673 cuted twice, first with a read access and then with a write one. Also
6674 note that an if(DEFINED) query on the variable does not register as an
6675 access and the watcher is not executed.
6676 Only non-cache variables can be watched using this command. Access to
6678 cache variables is never watched. However, the existence of a cache
6679 variable var causes accesses to the non-cache variable var to not use
6680 the UNKNOWN_ prefix, even if a non-cache variable var has never ex‐
6681 isted.
6682 while
6684 Evaluate a group of commands while a condition is true
6685 while(<condition>)
6687 <commands>
6688 endwhile()
6689 All commands between while and the matching endwhile() are recorded
6691 without being invoked. Once the endwhile() is evaluated, the recorded
6692 list of commands is invoked as long as the <condition> is true.
6693 The <condition> has the same syntax and is evaluated using the same
6695 logic as described at length for the if() command.
6696 The commands break() and continue() provide means to escape from the
6698 normal control flow.
6699 Per legacy, the endwhile() command admits an optional <condition> argu‐
6701 ment. If used, it must be a verbatim repeat of the argument of the
6702 opening while command.
6703
6705 These commands are available only in CMake projects.
6706 add_compile_definitions
6708 New in version 3.12.
6709 Add preprocessor definitions to the compilation of source files.
6712 add_compile_definitions(<definition> ...)
6714 Adds preprocessor definitions to the compiler command line.
6716 The preprocessor definitions are added to the COMPILE_DEFINITIONS di‐
6718 rectory property for the current CMakeLists file. They are also added
6719 to the COMPILE_DEFINITIONS target property for each target in the cur‐
6720 rent CMakeLists file.
6721 Definitions are specified using the syntax VAR or VAR=value. Func‐
6723 tion-style definitions are not supported. CMake will automatically es‐
6724 cape the value correctly for the native build system (note that CMake
6725 language syntax may require escapes to specify some values).
6726 Arguments to add_compile_definitions may use "generator expressions"
6728 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6729 for available expressions. See the cmake-buildsystem(7) manual for
6730 more on defining buildsystem properties.
6731 add_compile_options
6733 Add options to the compilation of source files.
6734 add_compile_options(<option> ...)
6736 Adds options to the COMPILE_OPTIONS directory property. These options
6738 are used when compiling targets from the current directory and below.
6739 Arguments
6741 Arguments to add_compile_options may use "generator expressions" with
6742 the syntax $<...>. See the cmake-generator-expressions(7) manual for
6743 available expressions. See the cmake-buildsystem(7) manual for more on
6744 defining buildsystem properties.
6745 Option De-duplication
6747 The final set of options used for a target is constructed by accumulat‐
6748 ing options from the current target and the usage requirements of its
6749 dependencies. The set of options is de-duplicated to avoid repetition.
6750 New in version 3.12: While beneficial for individual options, the
6752 de-duplication step can break up option groups. For example, -option A
6753 -option B becomes -option A B. One may specify a group of options us‐
6754 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
6755 is dropped, and the rest of the option string is parsed using the sepa‐
6756 rate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
6757 "SHELL:-option B" becomes -option A -option B.
6758 Example
6761 Since different compilers support different options, a typical use of
6762 this command is in a compiler-specific conditional clause:
6763 if (MSVC)
6765 # warning level 4 and all warnings as errors
6766 add_compile_options(/W4 /WX)
6767 else()
6768 # lots of warnings and all warnings as errors
6769 add_compile_options(-Wall -Wextra -pedantic -Werror)
6770 endif()
6771 See Also
6773 This command can be used to add any options. However, for adding pre‐
6774 processor definitions and include directories it is recommended to use
6775 the more specific commands add_compile_definitions() and include_direc‐
6776 tories().
6777 The command target_compile_options() adds target-specific options.
6779 The source file property COMPILE_OPTIONS adds options to one source
6781 file.
6782 add_custom_command
6784 Add a custom build rule to the generated build system.
6785 There are two main signatures for add_custom_command.
6787 Generating Files
6789 The first signature is for adding a custom command to produce an out‐
6790 put:
6791 add_custom_command(OUTPUT output1 [output2 ...]
6793 COMMAND command1 [ARGS] [args1...]
6794 [COMMAND command2 [ARGS] [args2...] ...]
6795 [MAIN_DEPENDENCY depend]
6796 [DEPENDS [depends...]]
6797 [BYPRODUCTS [files...]]
6798 [IMPLICIT_DEPENDS <lang1> depend1
6799 [<lang2> depend2] ...]
6800 [WORKING_DIRECTORY dir]
6801 [COMMENT comment]
6802 [DEPFILE depfile]
6803 [JOB_POOL job_pool]
6804 [VERBATIM] [APPEND] [USES_TERMINAL]
6805 [COMMAND_EXPAND_LISTS])
6806 This defines a command to generate specified OUTPUT file(s). A target
6808 created in the same directory (CMakeLists.txt file) that specifies any
6809 output of the custom command as a source file is given a rule to gener‐
6810 ate the file using the command at build time. Do not list the output
6811 in more than one independent target that may build in parallel or the
6812 two instances of the rule may conflict (instead use the add_custom_tar‐
6813 get() command to drive the command and make the other targets depend on
6814 that one). In makefile terms this creates a new target in the follow‐
6815 ing form:
6816 OUTPUT: MAIN_DEPENDENCY DEPENDS
6818 COMMAND
6819 The options are:
6821 APPEND Append the COMMAND and DEPENDS option values to the custom com‐
6823 mand for the first output specified. There must have already
6824 been a previous call to this command with the same output.
6825 If the previous call specified the output via a generator ex‐
6827 pression, the output specified by the current call must match in
6828 at least one configuration after evaluating generator expres‐
6829 sions. In this case, the appended commands and dependencies ap‐
6830 ply to all configurations.
6831 The COMMENT, MAIN_DEPENDENCY, and WORKING_DIRECTORY options are
6833 currently ignored when APPEND is given, but may be used in the
6834 future.
6835 BYPRODUCTS
6837 New in version 3.2.
6838 Specify the files the command is expected to produce but whose
6841 modification time may or may not be newer than the dependencies.
6842 If a byproduct name is a relative path it will be interpreted
6843 relative to the build tree directory corresponding to the cur‐
6844 rent source directory. Each byproduct file will be marked with
6845 the GENERATED source file property automatically.
6846 Explicit specification of byproducts is supported by the Ninja
6848 generator to tell the ninja build tool how to regenerate byprod‐
6849 ucts when they are missing. It is also useful when other build
6850 rules (e.g. custom commands) depend on the byproducts. Ninja
6851 requires a build rule for any generated file on which another
6852 rule depends even if there are order-only dependencies to ensure
6853 the byproducts will be available before their dependents build.
6854 The Makefile Generators will remove BYPRODUCTS and other GENER‐
6856 ATED files during make clean.
6857 New in version 3.20: Arguments to BYPRODUCTS may use a re‐
6859 stricted set of generator expressions. Target-dependent expres‐
6860 sions are not permitted.
6861 COMMAND
6864 Specify the command-line(s) to execute at build time. If more
6865 than one COMMAND is specified they will be executed in order,
6866 but not necessarily composed into a stateful shell or batch
6867 script. (To run a full script, use the configure_file() command
6868 or the file(GENERATE) command to create it, and then specify a
6869 COMMAND to launch it.) The optional ARGS argument is for back‐
6870 ward compatibility and will be ignored.
6871 If COMMAND specifies an executable target name (created by the
6873 add_executable() command), it will automatically be replaced by
6874 the location of the executable created at build time if either
6875 of the following is true:
6876 • The target is not being cross-compiled (i.e. the CMAKE_CROSS‐
6878 COMPILING variable is not set to true).
6879 • New in version 3.6: The target is being cross-compiled and an
6881 emulator is provided (i.e. its CROSSCOMPILING_EMULATOR target
6882 property is set). In this case, the contents of CROSSCOMPIL‐
6883 ING_EMULATOR will be prepended to the command before the loca‐
6884 tion of the target executable.
6885 If neither of the above conditions are met, it is assumed that
6888 the command name is a program to be found on the PATH at build
6889 time.
6890 Arguments to COMMAND may use generator expressions. Use the
6892 TARGET_FILE generator expression to refer to the location of a
6893 target later in the command line (i.e. as a command argument
6894 rather than as the command to execute).
6895 Whenever one of the following target based generator expressions
6897 are used as a command to execute or is mentioned in a command
6898 argument, a target-level dependency will be added automatically
6899 so that the mentioned target will be built before any target us‐
6900 ing this custom command (see policy CMP0112).
6901 • TARGET_FILE
6903 • TARGET_LINKER_FILE
6905 • TARGET_SONAME_FILE
6907 • TARGET_PDB_FILE
6909 This target-level dependency does NOT add a file-level depen‐
6911 dency that would cause the custom command to re-run whenever the
6912 executable is recompiled. List target names with the DEPENDS
6913 option to add such file-level dependencies.
6914 COMMENT
6916 Display the given message before the commands are executed at
6917 build time.
6918 DEPENDS
6920 Specify files on which the command depends. Each argument is
6921 converted to a dependency as follows:
6922 1. If the argument is the name of a target (created by the
6924 add_custom_target(), add_executable(), or add_library() com‐
6925 mand) a target-level dependency is created to make sure the
6926 target is built before any target using this custom command.
6927 Additionally, if the target is an executable or library, a
6928 file-level dependency is created to cause the custom command
6929 to re-run whenever the target is recompiled.
6930 2. If the argument is an absolute path, a file-level dependency
6932 is created on that path.
6933 3. If the argument is the name of a source file that has been
6935 added to a target or on which a source file property has been
6936 set, a file-level dependency is created on that source file.
6937 4. If the argument is a relative path and it exists in the cur‐
6939 rent source directory, a file-level dependency is created on
6940 that file in the current source directory.
6941 5. Otherwise, a file-level dependency is created on that path
6943 relative to the current binary directory.
6944 If any dependency is an OUTPUT of another custom command in the
6946 same directory (CMakeLists.txt file), CMake automatically brings
6947 the other custom command into the target in which this command
6948 is built.
6949 New in version 3.16: A target-level dependency is added if any
6951 dependency is listed as BYPRODUCTS of a target or any of its
6952 build events in the same directory to ensure the byproducts will
6953 be available.
6954 If DEPENDS is not specified, the command will run whenever the
6957 OUTPUT is missing; if the command does not actually create the
6958 OUTPUT, the rule will always run.
6959 New in version 3.1: Arguments to DEPENDS may use generator ex‐
6961 pressions.
6962 COMMAND_EXPAND_LISTS
6965 New in version 3.8.
6966 Lists in COMMAND arguments will be expanded, including those
6969 created with generator expressions, allowing COMMAND arguments
6970 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
6971 RIES>,;-I>" foo.cc to be properly expanded.
6972 IMPLICIT_DEPENDS
6974 Request scanning of implicit dependencies of an input file. The
6975 language given specifies the programming language whose corre‐
6976 sponding dependency scanner should be used. Currently only C
6977 and CXX language scanners are supported. The language has to be
6978 specified for every file in the IMPLICIT_DEPENDS list. Depen‐
6979 dencies discovered from the scanning are added to those of the
6980 custom command at build time. Note that the IMPLICIT_DEPENDS
6981 option is currently supported only for Makefile generators and
6982 will be ignored by other generators.
6983 NOTE:
6985 This option cannot be specified at the same time as DEPFILE
6986 option.
6987 JOB_POOL
6989 New in version 3.15.
6990 Specify a pool for the Ninja generator. Incompatible with
6993 USES_TERMINAL, which implies the console pool. Using a pool
6994 that is not defined by JOB_POOLS causes an error by ninja at
6995 build time.
6996 MAIN_DEPENDENCY
6998 Specify the primary input source file to the command. This is
6999 treated just like any value given to the DEPENDS option but also
7000 suggests to Visual Studio generators where to hang the custom
7001 command. Each source file may have at most one command specify‐
7002 ing it as its main dependency. A compile command (i.e. for a li‐
7003 brary or an executable) counts as an implicit main dependency
7004 which gets silently overwritten by a custom command specifica‐
7005 tion.
7006 OUTPUT Specify the output files the command is expected to produce. If
7008 an output name is a relative path it will be interpreted rela‐
7009 tive to the build tree directory corresponding to the current
7010 source directory. Each output file will be marked with the GEN‐
7011 ERATED source file property automatically. If the output of the
7012 custom command is not actually created as a file on disk it
7013 should be marked with the SYMBOLIC source file property.
7014 New in version 3.20: Arguments to OUTPUT may use a restricted
7016 set of generator expressions. Target-dependent expressions are
7017 not permitted.
7018 USES_TERMINAL
7021 New in version 3.2.
7022 The command will be given direct access to the terminal if pos‐
7025 sible. With the Ninja generator, this places the command in the
7026 console pool.
7027 VERBATIM
7029 All arguments to the commands will be escaped properly for the
7030 build tool so that the invoked command receives each argument
7031 unchanged. Note that one level of escapes is still used by the
7032 CMake language processor before add_custom_command even sees the
7033 arguments. Use of VERBATIM is recommended as it enables correct
7034 behavior. When VERBATIM is not given the behavior is platform
7035 specific because there is no protection of tool-specific special
7036 characters.
7037 WORKING_DIRECTORY
7039 Execute the command with the given current working directory.
7040 If it is a relative path it will be interpreted relative to the
7041 build tree directory corresponding to the current source direc‐
7042 tory.
7043 New in version 3.13: Arguments to WORKING_DIRECTORY may use gen‐
7045 erator expressions.
7046 DEPFILE
7049 New in version 3.7.
7050 Specify a .d depfile which holds dependencies for the custom
7053 command. It is usually emitted by the custom command itself.
7054 This keyword may only be used if the generator supports it, as
7055 detailed below.
7056 New in version 3.7: The Ninja generator supports DEPFILE since
7058 the keyword was first added.
7059 New in version 3.17: Added the Ninja Multi-Config generator,
7062 which included support for the DEPFILE keyword.
7063 New in version 3.20: Added support for Makefile Generators.
7066 NOTE:
7068 DEPFILE cannot be specified at the same time as the IM‐
7069 PLICIT_DEPENDS option for Makefile Generators.
7070 New in version 3.21: Added support for Visual Studio Generators
7073 with VS 2012 and above, and for the Xcode generator. Support
7074 for generator expressions was also added.
7075 Using DEPFILE with generators other than those listed above is
7078 an error.
7079 If the DEPFILE argument is relative, it should be relative to
7081 CMAKE_CURRENT_BINARY_DIR, and any relative paths inside the DEP‐
7082 FILE should also be relative to CMAKE_CURRENT_BINARY_DIR. See
7083 policy CMP0116, which is always NEW for Makefile Generators,
7084 Visual Studio Generators, and the Xcode generator.
7085 Examples: Generating Files
7087 Custom commands may be used to generate source files. For example, the
7088 code:
7089 add_custom_command(
7091 OUTPUT out.c
7092 COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
7093 -o out.c
7094 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
7095 VERBATIM)
7096 add_library(myLib out.c)
7097 adds a custom command to run someTool to generate out.c and then com‐
7099 pile the generated source as part of a library. The generation rule
7100 will re-run whenever in.txt changes.
7101 New in version 3.20: One may use generator expressions to specify
7103 per-configuration outputs. For example, the code:
7104 add_custom_command(
7106 OUTPUT "out-$<CONFIG>.c"
7107 COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
7108 -o "out-$<CONFIG>.c"
7109 -c "$<CONFIG>"
7110 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
7111 VERBATIM)
7112 add_library(myLib "out-$<CONFIG>.c")
7113 adds a custom command to run someTool to generate out-<config>.c, where
7115 <config> is the build configuration, and then compile the generated
7116 source as part of a library.
7117 Build Events
7120 The second signature adds a custom command to a target such as a li‐
7121 brary or executable. This is useful for performing an operation before
7122 or after building the target. The command becomes part of the target
7123 and will only execute when the target itself is built. If the target
7124 is already built, the command will not execute.
7125 add_custom_command(TARGET <target>
7127 PRE_BUILD | PRE_LINK | POST_BUILD
7128 COMMAND command1 [ARGS] [args1...]
7129 [COMMAND command2 [ARGS] [args2...] ...]
7130 [BYPRODUCTS [files...]]
7131 [WORKING_DIRECTORY dir]
7132 [COMMENT comment]
7133 [VERBATIM] [USES_TERMINAL]
7134 [COMMAND_EXPAND_LISTS])
7135 This defines a new command that will be associated with building the
7137 specified <target>. The <target> must be defined in the current direc‐
7138 tory; targets defined in other directories may not be specified.
7139 When the command will happen is determined by which of the following is
7141 specified:
7142 PRE_BUILD
7144 On Visual Studio Generators, run before any other rules are exe‐
7145 cuted within the target. On other generators, run just before
7146 PRE_LINK commands.
7147 PRE_LINK
7149 Run after sources have been compiled but before linking the bi‐
7150 nary or running the librarian or archiver tool of a static li‐
7151 brary. This is not defined for targets created by the add_cus‐
7152 tom_target() command.
7153 POST_BUILD
7155 Run after all other rules within the target have been executed.
7156 NOTE:
7158 Because generator expressions can be used in custom commands, it is
7159 possible to define COMMAND lines or whole custom commands which
7160 evaluate to empty strings for certain configurations. For Visual
7161 Studio 2010 (and newer) generators these command lines or custom
7162 commands will be omitted for the specific configuration and no
7163 "empty-string-command" will be added.
7164 This allows to add individual build events for every configuration.
7166 New in version 3.21: Support for target-dependent generator expres‐
7168 sions.
7169 Examples: Build Events
7172 A POST_BUILD event may be used to post-process a binary after linking.
7173 For example, the code:
7174 add_executable(myExe myExe.c)
7176 add_custom_command(
7177 TARGET myExe POST_BUILD
7178 COMMAND someHasher -i "$<TARGET_FILE:myExe>"
7179 -o "$<TARGET_FILE:myExe>.hash"
7180 VERBATIM)
7181 will run someHasher to produce a .hash file next to the executable af‐
7183 ter linking.
7184 New in version 3.20: One may use generator expressions to specify
7186 per-configuration byproducts. For example, the code:
7187 add_library(myPlugin MODULE myPlugin.c)
7189 add_custom_command(
7190 TARGET myPlugin POST_BUILD
7191 COMMAND someHasher -i "$<TARGET_FILE:myPlugin>"
7192 --as-code "myPlugin-hash-$<CONFIG>.c"
7193 BYPRODUCTS "myPlugin-hash-$<CONFIG>.c"
7194 VERBATIM)
7195 add_executable(myExe myExe.c "myPlugin-hash-$<CONFIG>.c")
7196 will run someHasher after linking myPlugin, e.g. to produce a .c file
7198 containing code to check the hash of myPlugin that the myExe executable
7199 can use to verify it before loading.
7200 Ninja Multi-Config
7203 New in version 3.20: add_custom_command supports the Ninja Multi-Config
7204 generator's cross-config capabilities. See the generator documentation
7205 for more information.
7206 add_custom_target
7209 Add a target with no output so it will always be built.
7210 add_custom_target(Name [ALL] [command1 [args1...]]
7212 [COMMAND command2 [args2...] ...]
7213 [DEPENDS depend depend depend ... ]
7214 [BYPRODUCTS [files...]]
7215 [WORKING_DIRECTORY dir]
7216 [COMMENT comment]
7217 [JOB_POOL job_pool]
7218 [VERBATIM] [USES_TERMINAL]
7219 [COMMAND_EXPAND_LISTS]
7220 [SOURCES src1 [src2...]])
7221 Adds a target with the given name that executes the given commands.
7223 The target has no output file and is always considered out of date even
7224 if the commands try to create a file with the name of the target. Use
7225 the add_custom_command() command to generate a file with dependencies.
7226 By default nothing depends on the custom target. Use the add_dependen‐
7227 cies() command to add dependencies to or from other targets.
7228 The options are:
7230 ALL Indicate that this target should be added to the default build
7232 target so that it will be run every time (the command cannot be
7233 called ALL).
7234 BYPRODUCTS
7236 New in version 3.2.
7237 Specify the files the command is expected to produce but whose
7240 modification time may or may not be updated on subsequent
7241 builds. If a byproduct name is a relative path it will be in‐
7242 terpreted relative to the build tree directory corresponding to
7243 the current source directory. Each byproduct file will be
7244 marked with the GENERATED source file property automatically.
7245 Explicit specification of byproducts is supported by the Ninja
7247 generator to tell the ninja build tool how to regenerate byprod‐
7248 ucts when they are missing. It is also useful when other build
7249 rules (e.g. custom commands) depend on the byproducts. Ninja
7250 requires a build rule for any generated file on which another
7251 rule depends even if there are order-only dependencies to ensure
7252 the byproducts will be available before their dependents build.
7253 The Makefile Generators will remove BYPRODUCTS and other GENER‐
7255 ATED files during make clean.
7256 New in version 3.20: Arguments to BYPRODUCTS may use a re‐
7258 stricted set of generator expressions. Target-dependent expres‐
7259 sions are not permitted.
7260 COMMAND
7263 Specify the command-line(s) to execute at build time. If more
7264 than one COMMAND is specified they will be executed in order,
7265 but not necessarily composed into a stateful shell or batch
7266 script. (To run a full script, use the configure_file() command
7267 or the file(GENERATE) command to create it, and then specify a
7268 COMMAND to launch it.)
7269 If COMMAND specifies an executable target name (created by the
7271 add_executable() command), it will automatically be replaced by
7272 the location of the executable created at build time if either
7273 of the following is true:
7274 • The target is not being cross-compiled (i.e. the CMAKE_CROSS‐
7276 COMPILING variable is not set to true).
7277 • New in version 3.6: The target is being cross-compiled and an
7279 emulator is provided (i.e. its CROSSCOMPILING_EMULATOR target
7280 property is set). In this case, the contents of CROSSCOMPIL‐
7281 ING_EMULATOR will be prepended to the command before the loca‐
7282 tion of the target executable.
7283 If neither of the above conditions are met, it is assumed that
7286 the command name is a program to be found on the PATH at build
7287 time.
7288 Arguments to COMMAND may use generator expressions. Use the
7290 TARGET_FILE generator expression to refer to the location of a
7291 target later in the command line (i.e. as a command argument
7292 rather than as the command to execute).
7293 Whenever one of the following target based generator expressions
7295 are used as a command to execute or is mentioned in a command
7296 argument, a target-level dependency will be added automatically
7297 so that the mentioned target will be built before this custom
7298 target (see policy CMP0112).
7299 • TARGET_FILE
7301 • TARGET_LINKER_FILE
7303 • TARGET_SONAME_FILE
7305 • TARGET_PDB_FILE
7307 The command and arguments are optional and if not specified an
7309 empty target will be created.
7310 COMMENT
7312 Display the given message before the commands are executed at
7313 build time.
7314 DEPENDS
7316 Reference files and outputs of custom commands created with
7317 add_custom_command() command calls in the same directory (CMake‐
7318 Lists.txt file). They will be brought up to date when the tar‐
7319 get is built.
7320 Changed in version 3.16: A target-level dependency is added if
7322 any dependency is a byproduct of a target or any of its build
7323 events in the same directory to ensure the byproducts will be
7324 available before this target is built.
7325 Use the add_dependencies() command to add dependencies on other
7328 targets.
7329 COMMAND_EXPAND_LISTS
7331 New in version 3.8.
7332 Lists in COMMAND arguments will be expanded, including those
7335 created with generator expressions, allowing COMMAND arguments
7336 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
7337 RIES>,;-I>" foo.cc to be properly expanded.
7338 JOB_POOL
7340 New in version 3.15.
7341 Specify a pool for the Ninja generator. Incompatible with
7344 USES_TERMINAL, which implies the console pool. Using a pool
7345 that is not defined by JOB_POOLS causes an error by ninja at
7346 build time.
7347 SOURCES
7349 Specify additional source files to be included in the custom
7350 target. Specified source files will be added to IDE project
7351 files for convenience in editing even if they have no build
7352 rules.
7353 VERBATIM
7355 All arguments to the commands will be escaped properly for the
7356 build tool so that the invoked command receives each argument
7357 unchanged. Note that one level of escapes is still used by the
7358 CMake language processor before add_custom_target even sees the
7359 arguments. Use of VERBATIM is recommended as it enables correct
7360 behavior. When VERBATIM is not given the behavior is platform
7361 specific because there is no protection of tool-specific special
7362 characters.
7363 USES_TERMINAL
7365 New in version 3.2.
7366 The command will be given direct access to the terminal if pos‐
7369 sible. With the Ninja generator, this places the command in the
7370 console pool.
7371 WORKING_DIRECTORY
7373 Execute the command with the given current working directory.
7374 If it is a relative path it will be interpreted relative to the
7375 build tree directory corresponding to the current source direc‐
7376 tory.
7377 New in version 3.13: Arguments to WORKING_DIRECTORY may use gen‐
7379 erator expressions.
7380 Ninja Multi-Config
7383 New in version 3.20: add_custom_target supports the Ninja Multi-Config
7384 generator's cross-config capabilities. See the generator documentation
7385 for more information.
7386 add_definitions
7389 Add -D define flags to the compilation of source files.
7390 add_definitions(-DFOO -DBAR ...)
7392 Adds definitions to the compiler command line for targets in the cur‐
7394 rent directory, whether added before or after this command is invoked,
7395 and for the ones in sub-directories added after. This command can be
7396 used to add any flags, but it is intended to add preprocessor defini‐
7397 tions.
7398 NOTE:
7400 This command has been superseded by alternatives:
7401 • Use add_compile_definitions() to add preprocessor definitions.
7403 • Use include_directories() to add include directories.
7405 • Use add_compile_options() to add other options.
7407 Flags beginning in -D or /D that look like preprocessor definitions are
7409 automatically added to the COMPILE_DEFINITIONS directory property for
7410 the current directory. Definitions with non-trivial values may be left
7411 in the set of flags instead of being converted for reasons of backwards
7412 compatibility. See documentation of the directory, target, source file
7413 COMPILE_DEFINITIONS properties for details on adding preprocessor defi‐
7414 nitions to specific scopes and configurations.
7415 See the cmake-buildsystem(7) manual for more on defining buildsystem
7417 properties.
7418 add_dependencies
7420 Add a dependency between top-level targets.
7421 add_dependencies(<target> [<target-dependency>]...)
7423 Makes a top-level <target> depend on other top-level targets to ensure
7425 that they build before <target> does. A top-level target is one cre‐
7426 ated by one of the add_executable(), add_library(), or add_custom_tar‐
7427 get() commands (but not targets generated by CMake like install).
7428 Dependencies added to an imported target or an interface library are
7430 followed transitively in its place since the target itself does not
7431 build.
7432 New in version 3.3: Allow adding dependencies to interface libraries.
7434 See the DEPENDS option of add_custom_target() and add_custom_command()
7437 commands for adding file-level dependencies in custom rules. See the
7438 OBJECT_DEPENDS source file property to add file-level dependencies to
7439 object files.
7440 add_executable
7442 Add an executable to the project using the specified source files.
7443 Normal Executables
7445 add_executable(<name> [WIN32] [MACOSX_BUNDLE]
7446 [EXCLUDE_FROM_ALL]
7447 [source1] [source2 ...])
7448 Adds an executable target called <name> to be built from the source
7450 files listed in the command invocation. The <name> corresponds to the
7451 logical target name and must be globally unique within a project. The
7452 actual file name of the executable built is constructed based on con‐
7453 ventions of the native platform (such as <name>.exe or just <name>).
7454 New in version 3.1: Source arguments to add_executable may use "genera‐
7456 tor expressions" with the syntax $<...>. See the cmake-generator-ex‐
7457 pressions(7) manual for available expressions.
7458 New in version 3.11: The source files can be omitted if they are added
7461 later using target_sources().
7462 By default the executable file will be created in the build tree direc‐
7465 tory corresponding to the source tree directory in which the command
7466 was invoked. See documentation of the RUNTIME_OUTPUT_DIRECTORY target
7467 property to change this location. See documentation of the OUTPUT_NAME
7468 target property to change the <name> part of the final file name.
7469 If WIN32 is given the property WIN32_EXECUTABLE will be set on the tar‐
7471 get created. See documentation of that target property for details.
7472 If MACOSX_BUNDLE is given the corresponding property will be set on the
7474 created target. See documentation of the MACOSX_BUNDLE target property
7475 for details.
7476 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
7478 the created target. See documentation of the EXCLUDE_FROM_ALL target
7479 property for details.
7480 See the cmake-buildsystem(7) manual for more on defining buildsystem
7482 properties.
7483 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
7485 cessed, and you want to have the original sources reachable from within
7486 IDE.
7487 Imported Executables
7489 add_executable(<name> IMPORTED [GLOBAL])
7490 An IMPORTED executable target references an executable file located
7492 outside the project. No rules are generated to build it, and the IM‐
7493 PORTED target property is True. The target name has scope in the di‐
7494 rectory in which it is created and below, but the GLOBAL option extends
7495 visibility. It may be referenced like any target built within the
7496 project. IMPORTED executables are useful for convenient reference from
7497 commands like add_custom_command(). Details about the imported exe‐
7498 cutable are specified by setting properties whose names begin in IM‐
7499 PORTED_. The most important such property is IMPORTED_LOCATION (and
7500 its per-configuration version IMPORTED_LOCATION_<CONFIG>) which speci‐
7501 fies the location of the main executable file on disk. See documenta‐
7502 tion of the IMPORTED_* properties for more information.
7503 Alias Executables
7505 add_executable(<name> ALIAS <target>)
7506 Creates an Alias Target, such that <name> can be used to refer to <tar‐
7508 get> in subsequent commands. The <name> does not appear in the gener‐
7509 ated buildsystem as a make target. The <target> may not be an ALIAS.
7510 New in version 3.11: An ALIAS can target a GLOBAL Imported Target
7512 New in version 3.18: An ALIAS can target a non-GLOBAL Imported Target.
7515 Such alias is scoped to the directory in which it is created and subdi‐
7516 rectories. The ALIAS_GLOBAL target property can be used to check if
7517 the alias is global or not.
7518 ALIAS targets can be used as targets to read properties from, executa‐
7521 bles for custom commands and custom targets. They can also be tested
7522 for existence with the regular if(TARGET) subcommand. The <name> may
7523 not be used to modify properties of <target>, that is, it may not be
7524 used as the operand of set_property(), set_target_properties(), tar‐
7525 get_link_libraries() etc. An ALIAS target may not be installed or ex‐
7526 ported.
7527 add_library
7529 Add a library to the project using the specified source files.
7530 Normal Libraries
7532 add_library(<name> [STATIC | SHARED | MODULE]
7533 [EXCLUDE_FROM_ALL]
7534 [<source>...])
7535 Adds a library target called <name> to be built from the source files
7537 listed in the command invocation. The <name> corresponds to the logi‐
7538 cal target name and must be globally unique within a project. The ac‐
7539 tual file name of the library built is constructed based on conventions
7540 of the native platform (such as lib<name>.a or <name>.lib).
7541 New in version 3.1: Source arguments to add_library may use "generator
7543 expressions" with the syntax $<...>. See the cmake-generator-expres‐
7544 sions(7) manual for available expressions.
7545 New in version 3.11: The source files can be omitted if they are added
7548 later using target_sources().
7549 STATIC, SHARED, or MODULE may be given to specify the type of library
7552 to be created. STATIC libraries are archives of object files for use
7553 when linking other targets. SHARED libraries are linked dynamically
7554 and loaded at runtime. MODULE libraries are plugins that are not
7555 linked into other targets but may be loaded dynamically at runtime us‐
7556 ing dlopen-like functionality. If no type is given explicitly the type
7557 is STATIC or SHARED based on whether the current value of the variable
7558 BUILD_SHARED_LIBS is ON. For SHARED and MODULE libraries the POSI‐
7559 TION_INDEPENDENT_CODE target property is set to ON automatically. A
7560 SHARED library may be marked with the FRAMEWORK target property to cre‐
7561 ate an macOS Framework.
7562 New in version 3.8: A STATIC library may be marked with the FRAMEWORK
7564 target property to create a static Framework.
7565 If a library does not export any symbols, it must not be declared as a
7568 SHARED library. For example, a Windows resource DLL or a managed
7569 C++/CLI DLL that exports no unmanaged symbols would need to be a MODULE
7570 library. This is because CMake expects a SHARED library to always have
7571 an associated import library on Windows.
7572 By default the library file will be created in the build tree directory
7574 corresponding to the source tree directory in which the command was in‐
7575 voked. See documentation of the ARCHIVE_OUTPUT_DIRECTORY, LIBRARY_OUT‐
7576 PUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY target properties to change
7577 this location. See documentation of the OUTPUT_NAME target property to
7578 change the <name> part of the final file name.
7579 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
7581 the created target. See documentation of the EXCLUDE_FROM_ALL target
7582 property for details.
7583 See the cmake-buildsystem(7) manual for more on defining buildsystem
7585 properties.
7586 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
7588 cessed, and you want to have the original sources reachable from within
7589 IDE.
7590 Object Libraries
7592 add_library(<name> OBJECT [<source>...])
7593 Creates an Object Library. An object library compiles source files but
7595 does not archive or link their object files into a library. Instead
7596 other targets created by add_library() or add_executable() may refer‐
7597 ence the objects using an expression of the form $<TARGET_OBJECTS:ob‐
7598 jlib> as a source, where objlib is the object library name. For exam‐
7599 ple:
7600 add_library(... $<TARGET_OBJECTS:objlib> ...)
7602 add_executable(... $<TARGET_OBJECTS:objlib> ...)
7603 will include objlib's object files in a library and an executable along
7605 with those compiled from their own sources. Object libraries may con‐
7606 tain only sources that compile, header files, and other files that
7607 would not affect linking of a normal library (e.g. .txt). They may
7608 contain custom commands generating such sources, but not PRE_BUILD,
7609 PRE_LINK, or POST_BUILD commands. Some native build systems (such as
7610 Xcode) may not like targets that have only object files, so consider
7611 adding at least one real source file to any target that references
7612 $<TARGET_OBJECTS:objlib>.
7613 New in version 3.12: Object libraries can be linked to with tar‐
7615 get_link_libraries().
7616 Interface Libraries
7619 add_library(<name> INTERFACE)
7620 Creates an Interface Library. An INTERFACE library target does not
7622 compile sources and does not produce a library artifact on disk. How‐
7623 ever, it may have properties set on it and it may be installed and ex‐
7624 ported. Typically, INTERFACE_* properties are populated on an inter‐
7625 face target using the commands:
7626 • set_property(),
7628 • target_link_libraries(INTERFACE),
7630 • target_link_options(INTERFACE),
7632 • target_include_directories(INTERFACE),
7634 • target_compile_options(INTERFACE),
7636 • target_compile_definitions(INTERFACE), and
7638 • target_sources(INTERFACE),
7640 and then it is used as an argument to target_link_libraries() like any
7642 other target.
7643 An interface library created with the above signature has no source
7645 files itself and is not included as a target in the generated buildsys‐
7646 tem.
7647 New in version 3.15: An interface library can have PUBLIC_HEADER and
7649 PRIVATE_HEADER properties. The headers specified by those properties
7650 can be installed using the install(TARGETS) command.
7651 New in version 3.19: An interface library target may be created with
7654 source files:
7655 add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])
7657 Source files may be listed directly in the add_library call or added
7659 later by calls to target_sources() with the PRIVATE or PUBLIC keywords.
7660 If an interface library has source files (i.e. the SOURCES target prop‐
7662 erty is set), it will appear in the generated buildsystem as a build
7663 target much like a target defined by the add_custom_target() command.
7664 It does not compile any sources, but does contain build rules for cus‐
7665 tom commands created by the add_custom_command() command.
7666 NOTE:
7669 In most command signatures where the INTERFACE keyword appears, the
7670 items listed after it only become part of that target's usage re‐
7671 quirements and are not part of the target's own settings. However,
7672 in this signature of add_library, the INTERFACE keyword refers to
7673 the library type only. Sources listed after it in the add_library
7674 call are PRIVATE to the interface library and do not appear in its
7675 INTERFACE_SOURCES target property.
7676 Imported Libraries
7678 add_library(<name> <type> IMPORTED [GLOBAL])
7679 Creates an IMPORTED library target called <name>. No rules are gener‐
7681 ated to build it, and the IMPORTED target property is True. The target
7682 name has scope in the directory in which it is created and below, but
7683 the GLOBAL option extends visibility. It may be referenced like any
7684 target built within the project. IMPORTED libraries are useful for
7685 convenient reference from commands like target_link_libraries(). De‐
7686 tails about the imported library are specified by setting properties
7687 whose names begin in IMPORTED_ and INTERFACE_.
7688 The <type> must be one of:
7690 STATIC, SHARED, MODULE, UNKNOWN
7692 References a library file located outside the project. The IM‐
7693 PORTED_LOCATION target property (or its per-configuration vari‐
7694 ant IMPORTED_LOCATION_<CONFIG>) specifies the location of the
7695 main library file on disk:
7696 • For a SHARED library on most non-Windows platforms, the main
7698 library file is the .so or .dylib file used by both linkers
7699 and dynamic loaders. If the referenced library file has a
7700 SONAME (or on macOS, has a LC_ID_DYLIB starting in @rpath/),
7701 the value of that field should be set in the IMPORTED_SONAME
7702 target property. If the referenced library file does not have
7703 a SONAME, but the platform supports it, then the IM‐
7704 PORTED_NO_SONAME target property should be set.
7705 • For a SHARED library on Windows, the IMPORTED_IMPLIB target
7707 property (or its per-configuration variant IMPORTED_IM‐
7708 PLIB_<CONFIG>) specifies the location of the DLL import li‐
7709 brary file (.lib or .dll.a) on disk, and the IMPORTED_LOCATION
7710 is the location of the .dll runtime library (and is optional,
7711 but needed by the TARGET_RUNTIME_DLLS generator expression).
7712 Additional usage requirements may be specified in INTERFACE_*
7714 properties.
7715 An UNKNOWN library type is typically only used in the implemen‐
7717 tation of Find Modules. It allows the path to an imported li‐
7718 brary (often found using the find_library() command) to be used
7719 without having to know what type of library it is. This is es‐
7720 pecially useful on Windows where a static library and a DLL's
7721 import library both have the same file extension.
7722 OBJECT References a set of object files located outside the project.
7724 The IMPORTED_OBJECTS target property (or its per-configuration
7725 variant IMPORTED_OBJECTS_<CONFIG>) specifies the locations of
7726 object files on disk. Additional usage requirements may be
7727 specified in INTERFACE_* properties.
7728 INTERFACE
7730 Does not reference any library or object files on disk, but may
7731 specify usage requirements in INTERFACE_* properties.
7732 See documentation of the IMPORTED_* and INTERFACE_* properties for more
7734 information.
7735 Alias Libraries
7737 add_library(<name> ALIAS <target>)
7738 Creates an Alias Target, such that <name> can be used to refer to <tar‐
7740 get> in subsequent commands. The <name> does not appear in the gener‐
7741 ated buildsystem as a make target. The <target> may not be an ALIAS.
7742 New in version 3.11: An ALIAS can target a GLOBAL Imported Target
7744 New in version 3.18: An ALIAS can target a non-GLOBAL Imported Target.
7747 Such alias is scoped to the directory in which it is created and below.
7748 The ALIAS_GLOBAL target property can be used to check if the alias is
7749 global or not.
7750 ALIAS targets can be used as linkable targets and as targets to read
7753 properties from. They can also be tested for existence with the regu‐
7754 lar if(TARGET) subcommand. The <name> may not be used to modify prop‐
7755 erties of <target>, that is, it may not be used as the operand of
7756 set_property(), set_target_properties(), target_link_libraries() etc.
7757 An ALIAS target may not be installed or exported.
7758 add_link_options
7760 New in version 3.13.
7761 Add options to the link step for executable, shared library or module
7764 library targets in the current directory and below that are added after
7765 this command is invoked.
7766 add_link_options(<option> ...)
7768 This command can be used to add any link options, but alternative com‐
7770 mands exist to add libraries (target_link_libraries() or link_li‐
7771 braries()). See documentation of the directory and target LINK_OPTIONS
7772 properties.
7773 NOTE:
7775 This command cannot be used to add options for static library tar‐
7776 gets, since they do not use a linker. To add archiver or MSVC li‐
7777 brarian flags, see the STATIC_LIBRARY_OPTIONS target property.
7778 Arguments to add_link_options may use "generator expressions" with the
7780 syntax $<...>. See the cmake-generator-expressions(7) manual for
7781 available expressions. See the cmake-buildsystem(7) manual for more on
7782 defining buildsystem properties.
7783 Host And Device Specific Link Options
7785 New in version 3.18: When a device link step is involved, which is con‐
7786 trolled by CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS
7787 properties and policy CMP0105, the raw options will be delivered to the
7788 host and device link steps (wrapped in -Xcompiler or equivalent for de‐
7789 vice link). Options wrapped with $<DEVICE_LINK:...> generator expres‐
7790 sion will be used only for the device link step. Options wrapped with
7791 $<HOST_LINK:...> generator expression will be used only for the host
7792 link step.
7793 Option De-duplication
7796 The final set of options used for a target is constructed by accumulat‐
7797 ing options from the current target and the usage requirements of its
7798 dependencies. The set of options is de-duplicated to avoid repetition.
7799 New in version 3.12: While beneficial for individual options, the
7801 de-duplication step can break up option groups. For example, -option A
7802 -option B becomes -option A B. One may specify a group of options us‐
7803 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
7804 is dropped, and the rest of the option string is parsed using the sepa‐
7805 rate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
7806 "SHELL:-option B" becomes -option A -option B.
7807 Handling Compiler Driver Differences
7810 To pass options to the linker tool, each compiler driver has its own
7811 syntax. The LINKER: prefix and , separator can be used to specify, in
7812 a portable way, options to pass to the linker tool. LINKER: is replaced
7813 by the appropriate driver option and , by the appropriate driver sepa‐
7814 rator. The driver prefix and driver separator are given by the values
7815 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAP‐
7816 PER_FLAG_SEP variables.
7817 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
7819 Clang and -Wl,-z,defs for GNU GCC.
7820 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
7822 sion.
7823 The LINKER: prefix supports, as an alternative syntax, specification of
7825 arguments using the SHELL: prefix and space as separator. The previous
7826 example then becomes "LINKER:SHELL:-z defs".
7827 NOTE:
7829 Specifying the SHELL: prefix anywhere other than at the beginning of
7830 the LINKER: prefix is not supported.
7831 add_subdirectory
7833 Add a subdirectory to the build.
7834 add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
7836 Adds a subdirectory to the build. The source_dir specifies the direc‐
7838 tory in which the source CMakeLists.txt and code files are located. If
7839 it is a relative path it will be evaluated with respect to the current
7840 directory (the typical usage), but it may also be an absolute path.
7841 The binary_dir specifies the directory in which to place the output
7842 files. If it is a relative path it will be evaluated with respect to
7843 the current output directory, but it may also be an absolute path. If
7844 binary_dir is not specified, the value of source_dir, before expanding
7845 any relative path, will be used (the typical usage). The CMake‐
7846 Lists.txt file in the specified source directory will be processed im‐
7847 mediately by CMake before processing in the current input file contin‐
7848 ues beyond this command.
7849 If the EXCLUDE_FROM_ALL argument is provided then targets in the subdi‐
7851 rectory will not be included in the ALL target of the parent directory
7852 by default, and will be excluded from IDE project files. Users must
7853 explicitly build targets in the subdirectory. This is meant for use
7854 when the subdirectory contains a separate part of the project that is
7855 useful but not necessary, such as a set of examples. Typically the
7856 subdirectory should contain its own project() command invocation so
7857 that a full build system will be generated in the subdirectory (such as
7858 a VS IDE solution file). Note that inter-target dependencies supersede
7859 this exclusion. If a target built by the parent project depends on a
7860 target in the subdirectory, the dependee target will be included in the
7861 parent project build system to satisfy the dependency.
7862 add_test
7864 Add a test to the project to be run by ctest(1).
7865 add_test(NAME <name> COMMAND <command> [<arg>...]
7867 [CONFIGURATIONS <config>...]
7868 [WORKING_DIRECTORY <dir>]
7869 [COMMAND_EXPAND_LISTS])
7870 Adds a test called <name>. The test name may contain arbitrary charac‐
7872 ters, expressed as a Quoted Argument or Bracket Argument if necessary.
7873 See policy CMP0110. The options are:
7874 COMMAND
7876 Specify the test command-line. If <command> specifies an exe‐
7877 cutable target (created by add_executable()) it will automati‐
7878 cally be replaced by the location of the executable created at
7879 build time.
7880 CONFIGURATIONS
7882 Restrict execution of the test only to the named configurations.
7883 WORKING_DIRECTORY
7885 Set the WORKING_DIRECTORY test property to specify the working
7886 directory in which to execute the test. If not specified the
7887 test will be run with the current working directory set to the
7888 build directory corresponding to the current source directory.
7889 COMMAND_EXPAND_LISTS
7891 New in version 3.16.
7892 Lists in COMMAND arguments will be expanded, including those
7895 created with generator expressions.
7896 The given test command is expected to exit with code 0 to pass and
7898 non-zero to fail, or vice-versa if the WILL_FAIL test property is set.
7899 Any output written to stdout or stderr will be captured by ctest(1) but
7900 does not affect the pass/fail status unless the PASS_REGULAR_EXPRES‐
7901 SION, FAIL_REGULAR_EXPRESSION or SKIP_REGULAR_EXPRESSION test property
7902 is used.
7903 New in version 3.16: Added SKIP_REGULAR_EXPRESSION property.
7905 The COMMAND and WORKING_DIRECTORY options may use "generator expres‐
7908 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
7909 manual for available expressions.
7910 Example usage:
7912 add_test(NAME mytest
7914 COMMAND testDriver --config $<CONFIG>
7915 --exe $<TARGET_FILE:myexe>)
7916 This creates a test mytest whose command runs a testDriver tool passing
7918 the configuration name and the full path to the executable file pro‐
7919 duced by target myexe.
7920 NOTE:
7922 CMake will generate tests only if the enable_testing() command has
7923 been invoked. The CTest module invokes the command automatically
7924 unless the BUILD_TESTING option is turned OFF.
7925 ----
7928 add_test(<name> <command> [<arg>...])
7932 Add a test called <name> with the given command-line. Unlike the above
7934 NAME signature no transformation is performed on the command-line to
7935 support target names or generator expressions.
7936 aux_source_directory
7938 Find all source files in a directory.
7939 aux_source_directory(<dir> <variable>)
7941 Collects the names of all the source files in the specified directory
7943 and stores the list in the <variable> provided. This command is in‐
7944 tended to be used by projects that use explicit template instantiation.
7945 Template instantiation files can be stored in a Templates subdirectory
7946 and collected automatically using this command to avoid manually list‐
7947 ing all instantiations.
7948 It is tempting to use this command to avoid writing the list of source
7950 files for a library or executable target. While this seems to work,
7951 there is no way for CMake to generate a build system that knows when a
7952 new source file has been added. Normally the generated build system
7953 knows when it needs to rerun CMake because the CMakeLists.txt file is
7954 modified to add a new source. When the source is just added to the di‐
7955 rectory without modifying this file, one would have to manually rerun
7956 CMake to generate a build system incorporating the new file.
7957 build_command
7959 Get a command line to build the current project. This is mainly in‐
7960 tended for internal use by the CTest module.
7961 build_command(<variable>
7963 [CONFIGURATION <config>]
7964 [PARALLEL_LEVEL <parallel>]
7965 [TARGET <target>]
7966 [PROJECT_NAME <projname>] # legacy, causes warning
7967 )
7968 Sets the given <variable> to a command-line string of the form:
7970 <cmake> --build . [--config <config>] [--parallel <parallel>] [--target <target>...] [-- -i]
7972 where <cmake> is the location of the cmake(1) command-line tool, and
7974 <config>, <parallel> and <target> are the values provided to the CON‐
7975 FIGURATION, PARALLEL_LEVEL and TARGET options, if any. The trailing --
7976 -i option is added for Makefile Generators if policy CMP0061 is not set
7977 to NEW.
7978 When invoked, this cmake --build command line will launch the underly‐
7980 ing build system tool.
7981 New in version 3.21: The PARALLEL_LEVEL argument can be used to set the
7983 --parallel flag.
7984 build_command(<cachevariable> <makecommand>)
7987 This second signature is deprecated, but still available for backwards
7989 compatibility. Use the first signature instead.
7990 It sets the given <cachevariable> to a command-line string as above but
7992 without the --target option. The <makecommand> is ignored but should
7993 be the full path to devenv, nmake, make or one of the end user build
7994 tools for legacy invocations.
7995 NOTE:
7997 In CMake versions prior to 3.0 this command returned a command line
7998 that directly invokes the native build tool for the current genera‐
7999 tor. Their implementation of the PROJECT_NAME option had no useful
8000 effects, so CMake now warns on use of the option.
8001 create_test_sourcelist
8003 Create a test driver and source list for building test programs.
8004 create_test_sourcelist(sourceListName driverName
8006 test1 test2 test3
8007 EXTRA_INCLUDE include.h
8008 FUNCTION function)
8009 A test driver is a program that links together many small tests into a
8011 single executable. This is useful when building static executables
8012 with large libraries to shrink the total required size. The list of
8013 source files needed to build the test driver will be in sourceListName.
8014 driverName is the name of the test driver program. The rest of the ar‐
8015 guments consist of a list of test source files, can be semicolon sepa‐
8016 rated. Each test source file should have a function in it that is the
8017 same name as the file with no extension (foo.cxx should have int
8018 foo(int, char*[]);) driverName will be able to call each of the tests
8019 by name on the command line. If EXTRA_INCLUDE is specified, then the
8020 next argument is included into the generated file. If FUNCTION is
8021 specified, then the next argument is taken as a function name that is
8022 passed a pointer to ac and av. This can be used to add extra command
8023 line processing to each test. The CMAKE_TESTDRIVER_BEFORE_TESTMAIN
8024 cmake variable can be set to have code that will be placed directly be‐
8025 fore calling the test main function. CMAKE_TESTDRIVER_AFTER_TESTMAIN
8026 can be set to have code that will be placed directly after the call to
8027 the test main function.
8028 define_property
8030 Define and document custom properties.
8031 define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
8033 TEST | VARIABLE | CACHED_VARIABLE>
8034 PROPERTY <name> [INHERITED]
8035 BRIEF_DOCS <brief-doc> [docs...]
8036 FULL_DOCS <full-doc> [docs...])
8037 Defines one property in a scope for use with the set_property() and
8039 get_property() commands. This is primarily useful to associate docu‐
8040 mentation with property names that may be retrieved with the get_prop‐
8041 erty() command. The first argument determines the kind of scope in
8042 which the property should be used. It must be one of the following:
8043 GLOBAL = associated with the global namespace
8045 DIRECTORY = associated with one directory
8046 TARGET = associated with one target
8047 SOURCE = associated with one source file
8048 TEST = associated with a test named with add_test
8049 VARIABLE = documents a CMake language variable
8050 CACHED_VARIABLE = documents a CMake cache variable
8051 Note that unlike set_property() and get_property() no actual scope
8053 needs to be given; only the kind of scope is important.
8054 The required PROPERTY option is immediately followed by the name of the
8056 property being defined.
8057 If the INHERITED option is given, then the get_property() command will
8059 chain up to the next higher scope when the requested property is not
8060 set in the scope given to the command.
8061 • DIRECTORY scope chains to its parent directory's scope, continuing
8063 the walk up parent directories until a directory has the property set
8064 or there are no more parents. If still not found at the top level
8065 directory, it chains to the GLOBAL scope.
8066 • TARGET, SOURCE and TEST properties chain to DIRECTORY scope, includ‐
8068 ing further chaining up the directories, etc. as needed.
8069 Note that this scope chaining behavior only applies to calls to
8071 get_property(), get_directory_property(), get_target_property(),
8072 get_source_file_property() and get_test_property(). There is no inher‐
8073 iting behavior when setting properties, so using APPEND or AP‐
8074 PEND_STRING with the set_property() command will not consider inherited
8075 values when working out the contents to append to.
8076 The BRIEF_DOCS and FULL_DOCS options are followed by strings to be as‐
8078 sociated with the property as its brief and full documentation. Corre‐
8079 sponding options to the get_property() command will retrieve the docu‐
8080 mentation.
8081 enable_language
8083 Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
8084 enable_language(<lang> [OPTIONAL] )
8086 Enables support for the named language in CMake. This is the same as
8088 the project() command but does not create any of the extra variables
8089 that are created by the project command. Example languages are CXX, C,
8090 CUDA, OBJC, OBJCXX, Fortran, HIP, ISPC, and ASM.
8091 New in version 3.8: Added CUDA support.
8093 New in version 3.16: Added OBJC and OBJCXX support.
8096 New in version 3.18: Added ISPC support.
8099 New in version 3.21: Added HIP support.
8102 If enabling ASM, enable it last so that CMake can check whether compil‐
8105 ers for other languages like C work for assembly too.
8106 This command must be called in file scope, not in a function call.
8108 Furthermore, it must be called in the highest directory common to all
8109 targets using the named language directly for compiling sources or in‐
8110 directly through link dependencies. It is simplest to enable all
8111 needed languages in the top-level directory of a project.
8112 The OPTIONAL keyword is a placeholder for future implementation and
8114 does not currently work. Instead you can use the CheckLanguage module
8115 to verify support before enabling.
8116 enable_testing
8118 Enable testing for current directory and below.
8119 enable_testing()
8121 Enables testing for this directory and below.
8123 This command should be in the source directory root because ctest ex‐
8125 pects to find a test file in the build directory root.
8126 This command is automatically invoked when the CTest module is in‐
8128 cluded, except if the BUILD_TESTING option is turned off.
8129 See also the add_test() command.
8131 export
8133 Export targets from the build tree for use by outside projects.
8134 export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
8136 Creates a file <filename> that may be included by outside projects to
8138 import targets from the current project's build tree. This is useful
8139 during cross-compiling to build utility executables that can run on the
8140 host platform in one project and then import them into another project
8141 being compiled for the target platform. If the NAMESPACE option is
8142 given the <namespace> string will be prepended to all target names
8143 written to the file.
8144 Target installations are associated with the export <export-name> using
8146 the EXPORT option of the install(TARGETS) command.
8147 The file created by this command is specific to the build tree and
8149 should never be installed. See the install(EXPORT) command to export
8150 targets from an installation tree.
8151 The properties set on the generated IMPORTED targets will have the same
8153 values as the final values of the input TARGETS.
8154 export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
8156 [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
8157 This signature is similar to the EXPORT signature, but targets are
8159 listed explicitly rather than specified as an export-name. If the AP‐
8160 PEND option is given the generated code will be appended to the file
8161 instead of overwriting it. The EXPORT_LINK_INTERFACE_LIBRARIES key‐
8162 word, if present, causes the contents of the properties matching (IM‐
8163 PORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when pol‐
8164 icy CMP0022 is NEW. If a library target is included in the export but
8165 a target to which it links is not included the behavior is unspecified.
8166 NOTE:
8168 Object Libraries under Xcode have special handling if multiple ar‐
8169 chitectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
8170 they will be exported as Interface Libraries with no object files
8171 available to clients. This is sufficient to satisfy transitive us‐
8172 age requirements of other targets that link to the object libraries
8173 in their implementation.
8174 export(PACKAGE <PackageName>)
8176 Store the current build directory in the CMake user package registry
8178 for package <PackageName>. The find_package() command may consider the
8179 directory while searching for package <PackageName>. This helps depen‐
8180 dent projects find and use a package from the current project's build
8181 tree without help from the user. Note that the entry in the package
8182 registry that this command creates works only in conjunction with a
8183 package configuration file (<PackageName>Config.cmake) that works with
8184 the build tree. In some cases, for example for packaging and for system
8185 wide installations, it is not desirable to write the user package reg‐
8186 istry.
8187 Changed in version 3.1: If the CMAKE_EXPORT_NO_PACKAGE_REGISTRY vari‐
8189 able is enabled, the export(PACKAGE) command will do nothing.
8190 Changed in version 3.15: By default the export(PACKAGE) command does
8193 nothing (see policy CMP0090) because populating the user package reg‐
8194 istry has effects outside the source and build trees. Set the
8195 CMAKE_EXPORT_PACKAGE_REGISTRY variable to add build directories to the
8196 CMake user package registry.
8197 export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
8200 New in version 3.7.
8202 This signature exports cmake built targets to the android ndk build
8205 system by creating an Android.mk file that references the prebuilt tar‐
8206 gets. The Android NDK supports the use of prebuilt libraries, both
8207 static and shared. This allows cmake to build the libraries of a
8208 project and make them available to an ndk build system complete with
8209 transitive dependencies, include flags and defines required to use the
8210 libraries. The signature takes a list of targets and puts them in the
8211 Android.mk file specified by the <filename> given. This signature can
8212 only be used if policy CMP0022 is NEW for all targets given. A error
8213 will be issued if that policy is set to OLD for one of the targets.
8214 fltk_wrap_ui
8216 Create FLTK user interfaces Wrappers.
8217 fltk_wrap_ui(resultingLibraryName source1
8219 source2 ... sourceN )
8220 Produce .h and .cxx files for all the .fl and .fld files listed. The
8222 resulting .h and .cxx files will be added to a variable named result‐
8223 ingLibraryName_FLTK_UI_SRCS which should be added to your library.
8224 get_source_file_property
8226 Get a property for a source file.
8227 get_source_file_property(<variable> <file>
8229 [DIRECTORY <dir> | TARGET_DIRECTORY <target>]
8230 <property>)
8231 Gets a property from a source file. The value of the property is
8233 stored in the specified <variable>. If the source property is not
8234 found, the behavior depends on whether it has been defined to be an IN‐
8235 HERITED property or not (see define_property()). Non-inherited proper‐
8236 ties will set variable to NOTFOUND, whereas inherited properties will
8237 search the relevant parent scope as described for the define_property()
8238 command and if still unable to find the property, variable will be set
8239 to an empty string.
8240 By default, the source file's property will be read from the current
8242 source directory's scope.
8243 New in version 3.18: Directory scope can be overridden with one of the
8245 following sub-options:
8246 DIRECTORY <dir>
8248 The source file property will be read from the <dir> directory's
8249 scope. CMake must already know about that source directory, ei‐
8250 ther by having added it through a call to add_subdirectory() or
8251 <dir> being the top level source directory. Relative paths are
8252 treated as relative to the current source directory.
8253 TARGET_DIRECTORY <target>
8255 The source file property will be read from the directory scope
8256 in which <target> was created (<target> must therefore already
8257 exist).
8258 Use set_source_files_properties() to set property values. Source file
8261 properties usually control how the file is built. One property that is
8262 always there is LOCATION.
8263 See also the more general get_property() command.
8265 NOTE:
8267 The GENERATED source file property may be globally visible. See its
8268 documentation for details.
8269 get_target_property
8271 Get a property from a target.
8272 get_target_property(<VAR> target property)
8274 Get a property from a target. The value of the property is stored in
8276 the variable <VAR>. If the target property is not found, the behavior
8277 depends on whether it has been defined to be an INHERITED property or
8278 not (see define_property()). Non-inherited properties will set <VAR>
8279 to <VAR>-NOTFOUND, whereas inherited properties will search the rele‐
8280 vant parent scope as described for the define_property() command and if
8281 still unable to find the property, <VAR> will be set to an empty
8282 string.
8283 Use set_target_properties() to set target property values. Properties
8285 are usually used to control how a target is built, but some query the
8286 target instead. This command can get properties for any target so far
8287 created. The targets do not need to be in the current CMakeLists.txt
8288 file.
8289 See also the more general get_property() command.
8291 See Target Properties for the list of properties known to CMake.
8293 get_test_property
8295 Get a property of the test.
8296 get_test_property(test property VAR)
8298 Get a property from the test. The value of the property is stored in
8300 the variable VAR. If the test property is not found, the behavior de‐
8301 pends on whether it has been defined to be an INHERITED property or not
8302 (see define_property()). Non-inherited properties will set VAR to
8303 "NOTFOUND", whereas inherited properties will search the relevant par‐
8304 ent scope as described for the define_property() command and if still
8305 unable to find the property, VAR will be set to an empty string.
8306 For a list of standard properties you can type cmake --help-prop‐
8308 erty-list.
8309 See also the more general get_property() command.
8311 include_directories
8313 Add include directories to the build.
8314 include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])
8316 Add the given directories to those the compiler uses to search for in‐
8318 clude files. Relative paths are interpreted as relative to the current
8319 source directory.
8320 The include directories are added to the INCLUDE_DIRECTORIES directory
8322 property for the current CMakeLists file. They are also added to the
8323 INCLUDE_DIRECTORIES target property for each target in the current
8324 CMakeLists file. The target property values are the ones used by the
8325 generators.
8326 By default the directories specified are appended onto the current list
8328 of directories. This default behavior can be changed by setting
8329 CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE ex‐
8330 plicitly, you can select between appending and prepending, independent
8331 of the default.
8332 If the SYSTEM option is given, the compiler will be told the directo‐
8334 ries are meant as system include directories on some platforms. Sig‐
8335 nalling this setting might achieve effects such as the compiler skip‐
8336 ping warnings, or these fixed-install system files not being considered
8337 in dependency calculations - see compiler docs.
8338 Arguments to include_directories may use "generator expressions" with
8340 the syntax "$<...>". See the cmake-generator-expressions(7) manual for
8341 available expressions. See the cmake-buildsystem(7) manual for more on
8342 defining buildsystem properties.
8343 NOTE:
8345 Prefer the target_include_directories() command to add include di‐
8346 rectories to individual targets and optionally propagate/export them
8347 to dependents.
8348 include_external_msproject
8350 Include an external Microsoft project file in a workspace.
8351 include_external_msproject(projectname location
8353 [TYPE projectTypeGUID]
8354 [GUID projectGUID]
8355 [PLATFORM platformName]
8356 dep1 dep2 ...)
8357 Includes an external Microsoft project in the generated workspace file.
8359 Currently does nothing on UNIX. This will create a target named [pro‐
8360 jectname]. This can be used in the add_dependencies() command to make
8361 things depend on the external project.
8362 TYPE, GUID and PLATFORM are optional parameters that allow one to spec‐
8364 ify the type of project, id (GUID) of the project and the name of the
8365 target platform. This is useful for projects requiring values other
8366 than the default (e.g. WIX projects).
8367 New in version 3.9: If the imported project has different configuration
8369 names than the current project, set the MAP_IMPORTED_CONFIG_<CONFIG>
8370 target property to specify the mapping.
8371 include_regular_expression
8374 Set the regular expression used for dependency checking.
8375 include_regular_expression(regex_match [regex_complain])
8377 Sets the regular expressions used in dependency checking. Only files
8379 matching regex_match will be traced as dependencies. Only files match‐
8380 ing regex_complain will generate warnings if they cannot be found
8381 (standard header paths are not searched). The defaults are:
8382 regex_match = "^.*$" (match everything)
8384 regex_complain = "^$" (match empty string only)
8385 install
8387 Specify rules to run at install time.
8388 Synopsis
8390 install(TARGETS <target>... [...])
8391 install(IMPORTED_RUNTIME_ARTIFACTS <target>... [...])
8392 install({FILES | PROGRAMS} <file>... [...])
8393 install(DIRECTORY <dir>... [...])
8394 install(SCRIPT <file> [...])
8395 install(CODE <code> [...])
8396 install(EXPORT <export-name> [...])
8397 install(RUNTIME_DEPENDENCY_SET <set-name> [...])
8398 Introduction
8400 This command generates installation rules for a project. Install rules
8401 specified by calls to the install() command within a source directory
8402 are executed in order during installation.
8403 Changed in version 3.14: Install rules in subdirectories added by calls
8405 to the add_subdirectory() command are interleaved with those in the
8406 parent directory to run in the order declared (see policy CMP0082).
8407 Changed in version 3.22: The environment variable CMAKE_INSTALL_MODE
8410 can override the default copying behavior of install().
8411 There are multiple signatures for this command. Some of them define
8414 installation options for files and targets. Options common to multiple
8415 signatures are covered here but they are valid only for signatures that
8416 specify them. The common options are:
8417 DESTINATION
8419 Specify the directory on disk to which a file will be installed.
8420 Arguments can be relative or absolute paths.
8421 If a relative path is given it is interpreted relative to the
8423 value of the CMAKE_INSTALL_PREFIX variable. The prefix can be
8424 relocated at install time using the DESTDIR mechanism explained
8425 in the CMAKE_INSTALL_PREFIX variable documentation.
8426 If an absolute path (with a leading slash or drive letter) is
8428 given it is used verbatim.
8429 As absolute paths are not supported by cpack installer genera‐
8431 tors, it is preferable to use relative paths throughout. In
8432 particular, there is no need to make paths absolute by prepend‐
8433 ing CMAKE_INSTALL_PREFIX; this prefix is used by default if the
8434 DESTINATION is a relative path.
8435 PERMISSIONS
8437 Specify permissions for installed files. Valid permissions are
8438 OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE,
8439 GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID,
8440 and SETGID. Permissions that do not make sense on certain plat‐
8441 forms are ignored on those platforms.
8442 CONFIGURATIONS
8444 Specify a list of build configurations for which the install
8445 rule applies (Debug, Release, etc.). Note that the values speci‐
8446 fied for this option only apply to options listed AFTER the CON‐
8447 FIGURATIONS option. For example, to set separate install paths
8448 for the Debug and Release configurations, do the following:
8449 install(TARGETS target
8451 CONFIGURATIONS Debug
8452 RUNTIME DESTINATION Debug/bin)
8453 install(TARGETS target
8454 CONFIGURATIONS Release
8455 RUNTIME DESTINATION Release/bin)
8456 Note that CONFIGURATIONS appears BEFORE RUNTIME DESTINATION.
8458 COMPONENT
8460 Specify an installation component name with which the install
8461 rule is associated, such as "runtime" or "development". During
8462 component-specific installation only install rules associated
8463 with the given component name will be executed. During a full
8464 installation all components are installed unless marked with EX‐
8465 CLUDE_FROM_ALL. If COMPONENT is not provided a default compo‐
8466 nent "Unspecified" is created. The default component name may
8467 be controlled with the CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
8468 variable.
8469 EXCLUDE_FROM_ALL
8471 New in version 3.6.
8472 Specify that the file is excluded from a full installation and
8475 only installed as part of a component-specific installation
8476 RENAME Specify a name for an installed file that may be different from
8478 the original file. Renaming is allowed only when a single file
8479 is installed by the command.
8480 OPTIONAL
8482 Specify that it is not an error if the file to be installed does
8483 not exist.
8484 New in version 3.1: Command signatures that install files may print
8486 messages during installation. Use the CMAKE_INSTALL_MESSAGE variable
8487 to control which messages are printed.
8488 New in version 3.11: Many of the install() variants implicitly create
8491 the directories containing the installed files. If CMAKE_INSTALL_DE‐
8492 FAULT_DIRECTORY_PERMISSIONS is set, these directories will be created
8493 with the permissions specified. Otherwise, they will be created accord‐
8494 ing to the uname rules on Unix-like platforms. Windows platforms are
8495 unaffected.
8496 Installing Targets
8499 install(TARGETS targets... [EXPORT <export-name>]
8500 [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>]
8501 [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
8502 PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
8503 [DESTINATION <dir>]
8504 [PERMISSIONS permissions...]
8505 [CONFIGURATIONS [Debug|Release|...]]
8506 [COMPONENT <component>]
8507 [NAMELINK_COMPONENT <component>]
8508 [OPTIONAL] [EXCLUDE_FROM_ALL]
8509 [NAMELINK_ONLY|NAMELINK_SKIP]
8510 ] [...]
8511 [INCLUDES DESTINATION [<dir> ...]]
8512 )
8513 The TARGETS form specifies rules for installing targets from a project.
8515 There are several kinds of target Output Artifacts that may be in‐
8516 stalled:
8517 ARCHIVE
8519 Target artifacts of this kind include:
8520 • Static libraries (except on macOS when marked as FRAMEWORK,
8522 see below);
8523 • DLL import libraries (on all Windows-based systems including
8525 Cygwin; they have extension .lib, in contrast to the .dll li‐
8526 braries that go to RUNTIME);
8527 • On AIX, the linker import file created for executables with
8529 ENABLE_EXPORTS enabled.
8530 LIBRARY
8532 Target artifacts of this kind include:
8533 • Shared libraries, except
8535 • DLLs (these go to RUNTIME, see below),
8537 • on macOS when marked as FRAMEWORK (see below).
8539 RUNTIME
8541 Target artifacts of this kind include:
8542 • Executables (except on macOS when marked as MACOSX_BUNDLE, see
8544 BUNDLE below);
8545 • DLLs (on all Windows-based systems including Cygwin; note that
8547 the accompanying import libraries are of kind ARCHIVE).
8548 OBJECTS
8550 New in version 3.9.
8551 Object files associated with object libraries.
8554 FRAMEWORK
8556 Both static and shared libraries marked with the FRAMEWORK prop‐
8557 erty are treated as FRAMEWORK targets on macOS.
8558 BUNDLE Executables marked with the MACOSX_BUNDLE property are treated
8560 as BUNDLE targets on macOS.
8561 PUBLIC_HEADER
8563 Any PUBLIC_HEADER files associated with a library are installed
8564 in the destination specified by the PUBLIC_HEADER argument on
8565 non-Apple platforms. Rules defined by this argument are ignored
8566 for FRAMEWORK libraries on Apple platforms because the associ‐
8567 ated files are installed into the appropriate locations inside
8568 the framework folder. See PUBLIC_HEADER for details.
8569 PRIVATE_HEADER
8571 Similar to PUBLIC_HEADER, but for PRIVATE_HEADER files. See PRI‐
8572 VATE_HEADER for details.
8573 RESOURCE
8575 Similar to PUBLIC_HEADER and PRIVATE_HEADER, but for RESOURCE
8576 files. See RESOURCE for details.
8577 For each of these arguments given, the arguments following them only
8579 apply to the target or file type specified in the argument. If none is
8580 given, the installation properties apply to all target types. If only
8581 one is given then only targets of that type will be installed (which
8582 can be used to install just a DLL or just an import library.)
8583 For regular executables, static libraries and shared libraries, the
8585 DESTINATION argument is not required. For these target types, when
8586 DESTINATION is omitted, a default destination will be taken from the
8587 appropriate variable from GNUInstallDirs, or set to a built-in default
8588 value if that variable is not defined. The same is true for the public
8589 and private headers associated with the installed targets through the
8590 PUBLIC_HEADER and PRIVATE_HEADER target properties. A destination must
8591 always be provided for module libraries, Apple bundles and frameworks.
8592 A destination can be omitted for interface and object libraries, but
8593 they are handled differently (see the discussion of this topic toward
8594 the end of this section).
8595 The following table shows the target types with their associated vari‐
8597 ables and built-in defaults that apply when no destination is given:
8598 ┌───────────────┬─────────────────────┬──────────────────┐
8600 │Target Type │ GNUInstallDirs │ Built-In Default │
8601 │ │ Variable │ │
8602 ├───────────────┼─────────────────────┼──────────────────┤
8603 │RUNTIME │ ${CMAKE_IN‐ │ bin │
8604 │ │ STALL_BINDIR} │ │
8605 ├───────────────┼─────────────────────┼──────────────────┤
8606 │LIBRARY │ ${CMAKE_IN‐ │ lib │
8607 │ │ STALL_LIBDIR} │ │
8608 ├───────────────┼─────────────────────┼──────────────────┤
8609 │ARCHIVE │ ${CMAKE_IN‐ │ lib │
8610 │ │ STALL_LIBDIR} │ │
8611 ├───────────────┼─────────────────────┼──────────────────┤
8612 │PRIVATE_HEADER │ ${CMAKE_INSTALL_IN‐ │ include │
8613 │ │ CLUDEDIR} │ │
8614 ├───────────────┼─────────────────────┼──────────────────┤
8615 │PUBLIC_HEADER │ ${CMAKE_INSTALL_IN‐ │ include │
8616 │ │ CLUDEDIR} │ │
8617 └───────────────┴─────────────────────┴──────────────────┘
8618 Projects wishing to follow the common practice of installing headers
8620 into a project-specific subdirectory will need to provide a destination
8621 rather than rely on the above.
8622 To make packages compliant with distribution filesystem layout poli‐
8624 cies, if projects must specify a DESTINATION, it is recommended that
8625 they use a path that begins with the appropriate GNUInstallDirs vari‐
8626 able. This allows package maintainers to control the install destina‐
8627 tion by setting the appropriate cache variables. The following example
8628 shows a static library being installed to the default destination pro‐
8629 vided by GNUInstallDirs, but with its headers installed to a
8630 project-specific subdirectory that follows the above recommendation:
8631 add_library(mylib STATIC ...)
8633 set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
8634 include(GNUInstallDirs)
8635 install(TARGETS mylib
8636 PUBLIC_HEADER
8637 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
8638 )
8639 In addition to the common options listed above, each target can accept
8641 the following additional arguments:
8642 NAMELINK_COMPONENT
8644 New in version 3.12.
8645 On some platforms a versioned shared library has a symbolic link
8648 such as:
8649 lib<name>.so -> lib<name>.so.1
8651 where lib<name>.so.1 is the soname of the library and
8653 lib<name>.so is a "namelink" allowing linkers to find the li‐
8654 brary when given -l<name>. The NAMELINK_COMPONENT option is sim‐
8655 ilar to the COMPONENT option, but it changes the installation
8656 component of a shared library namelink if one is generated. If
8657 not specified, this defaults to the value of COMPONENT. It is an
8658 error to use this parameter outside of a LIBRARY block.
8659 Consider the following example:
8661 install(TARGETS mylib
8663 LIBRARY
8664 COMPONENT Libraries
8665 NAMELINK_COMPONENT Development
8666 PUBLIC_HEADER
8667 COMPONENT Development
8668 )
8669 In this scenario, if you choose to install only the Development
8671 component, both the headers and namelink will be installed with‐
8672 out the library. (If you don't also install the Libraries compo‐
8673 nent, the namelink will be a dangling symlink, and projects that
8674 link to the library will have build errors.) If you install only
8675 the Libraries component, only the library will be installed,
8676 without the headers and namelink.
8677 This option is typically used for package managers that have
8679 separate runtime and development packages. For example, on De‐
8680 bian systems, the library is expected to be in the runtime pack‐
8681 age, and the headers and namelink are expected to be in the de‐
8682 velopment package.
8683 See the VERSION and SOVERSION target properties for details on
8685 creating versioned shared libraries.
8686 NAMELINK_ONLY
8688 This option causes the installation of only the namelink when a
8689 library target is installed. On platforms where versioned shared
8690 libraries do not have namelinks or when a library is not ver‐
8691 sioned, the NAMELINK_ONLY option installs nothing. It is an er‐
8692 ror to use this parameter outside of a LIBRARY block.
8693 When NAMELINK_ONLY is given, either NAMELINK_COMPONENT or COMPO‐
8695 NENT may be used to specify the installation component of the
8696 namelink, but COMPONENT should generally be preferred.
8697 NAMELINK_SKIP
8699 Similar to NAMELINK_ONLY, but it has the opposite effect: it
8700 causes the installation of library files other than the namelink
8701 when a library target is installed. When neither NAMELINK_ONLY
8702 or NAMELINK_SKIP are given, both portions are installed. On
8703 platforms where versioned shared libraries do not have symlinks
8704 or when a library is not versioned, NAMELINK_SKIP installs the
8705 library. It is an error to use this parameter outside of a LI‐
8706 BRARY block.
8707 If NAMELINK_SKIP is specified, NAMELINK_COMPONENT has no effect.
8709 It is not recommended to use NAMELINK_SKIP in conjunction with
8710 NAMELINK_COMPONENT.
8711 The install(TARGETS) command can also accept the following options at
8713 the top level:
8714 EXPORT This option associates the installed target files with an export
8716 called <export-name>. It must appear before any target options.
8717 To actually install the export file itself, call
8718 install(EXPORT), documented below. See documentation of the EX‐
8719 PORT_NAME target property to change the name of the exported
8720 target.
8721 INCLUDES DESTINATION
8723 This option specifies a list of directories which will be added
8724 to the INTERFACE_INCLUDE_DIRECTORIES target property of the
8725 <targets> when exported by the install(EXPORT) command. If a
8726 relative path is specified, it is treated as relative to the
8727 $<INSTALL_PREFIX>.
8728 RUNTIME_DEPENDENCY_SET
8730 New in version 3.21.
8731 This option causes all runtime dependencies of installed exe‐
8734 cutable, shared library, and module targets to be added to the
8735 specified runtime dependency set. This set can then be installed
8736 with an install(RUNTIME_DEPENDENCY_SET) command.
8737 This keyword and the RUNTIME_DEPENDENCIES keyword are mutually
8739 exclusive.
8740 RUNTIME_DEPENDENCIES
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 installed
8747 along with the targets themselves. The RUNTIME, LIBRARY, FRAME‐
8748 WORK, and generic arguments are used to determine the properties
8749 (DESTINATION, COMPONENT, etc.) of the installation of these de‐
8750 pendencies.
8751 RUNTIME_DEPENDENCIES is semantically equivalent to the following
8753 pair of calls:
8754 install(TARGETS ... RUNTIME_DEPENDENCY_SET <set-name>)
8756 install(RUNTIME_DEPENDENCY_SET <set-name> args...)
8757 where <set-name> will be a randomly generated set name. The
8759 args... may include any of the following keywords supported by
8760 the install(RUNTIME_DEPENDENCY_SET) command:
8761 • DIRECTORIES
8763 • PRE_INCLUDE_REGEXES
8765 • PRE_EXCLUDE_REGEXES
8767 • POST_INCLUDE_REGEXES
8769 • POST_EXCLUDE_REGEXES
8771 • POST_INCLUDE_FILES
8773 • POST_EXCLUDE_FILES
8775 The RUNTIME_DEPENDENCIES and RUNTIME_DEPENDENCY_SET keywords are
8777 mutually exclusive.
8778 One or more groups of properties may be specified in a single call to
8780 the TARGETS form of this command. A target may be installed more than
8781 once to different locations. Consider hypothetical targets myExe,
8782 mySharedLib, and myStaticLib. The code:
8783 install(TARGETS myExe mySharedLib myStaticLib
8785 RUNTIME DESTINATION bin
8786 LIBRARY DESTINATION lib
8787 ARCHIVE DESTINATION lib/static)
8788 install(TARGETS mySharedLib DESTINATION /some/full/path)
8789 will install myExe to <prefix>/bin and myStaticLib to <pre‐
8791 fix>/lib/static. On non-DLL platforms mySharedLib will be installed to
8792 <prefix>/lib and /some/full/path. On DLL platforms the mySharedLib DLL
8793 will be installed to <prefix>/bin and /some/full/path and its import
8794 library will be installed to <prefix>/lib/static and /some/full/path.
8795 Interface Libraries may be listed among the targets to install. They
8797 install no artifacts but will be included in an associated EXPORT. If
8798 Object Libraries are listed but given no destination for their object
8799 files, they will be exported as Interface Libraries. This is suffi‐
8800 cient to satisfy transitive usage requirements of other targets that
8801 link to the object libraries in their implementation.
8802 Installing a target with the EXCLUDE_FROM_ALL target property set to
8804 TRUE has undefined behavior.
8805 New in version 3.3: An install destination given as a DESTINATION argu‐
8807 ment may use "generator expressions" with the syntax $<...>. See the
8808 cmake-generator-expressions(7) manual for available expressions.
8809 New in version 3.13: install(TARGETS) can install targets that were
8812 created in other directories. When using such cross-directory install
8813 rules, running make install (or similar) from a subdirectory will not
8814 guarantee that targets from other directories are up-to-date. You can
8815 use target_link_libraries() or add_dependencies() to ensure that such
8816 out-of-directory targets are built before the subdirectory-specific in‐
8817 stall rules are run.
8818 Installing Imported Runtime Artifacts
8821 New in version 3.21.
8822 install(IMPORTED_RUNTIME_ARTIFACTS targets...
8825 [RUNTIME_DEPENDENCY_SET <set-name>]
8826 [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE]
8827 [DESTINATION <dir>]
8828 [PERMISSIONS permissions...]
8829 [CONFIGURATIONS [Debug|Release|...]]
8830 [COMPONENT <component>]
8831 [OPTIONAL] [EXCLUDE_FROM_ALL]
8832 ] [...]
8833 )
8834 The IMPORTED_RUNTIME_ARTIFACTS form specifies rules for installing the
8836 runtime artifacts of imported targets. Projects may do this if they
8837 want to bundle outside executables or modules inside their installa‐
8838 tion. The LIBRARY, RUNTIME, FRAMEWORK, and BUNDLE arguments have the
8839 same semantics that they do in the TARGETS mode. Only the runtime arti‐
8840 facts of imported targets are installed (except in the case of FRAME‐
8841 WORK libraries, MACOSX_BUNDLE executables, and BUNDLE CFBundles.) For
8842 example, headers and import libraries associated with DLLs are not in‐
8843 stalled. In the case of FRAMEWORK libraries, MACOSX_BUNDLE executables,
8844 and BUNDLE CFBundles, the entire directory is installed.
8845 The RUNTIME_DEPENDENCY_SET option causes the runtime artifacts of the
8847 imported executable, shared library, and module library targets to be
8848 added to the <set-name> runtime dependency set. This set can then be
8849 installed with an install(RUNTIME_DEPENDENCY_SET) command.
8850 Installing Files
8852 install(<FILES|PROGRAMS> files...
8853 TYPE <type> | DESTINATION <dir>
8854 [PERMISSIONS permissions...]
8855 [CONFIGURATIONS [Debug|Release|...]]
8856 [COMPONENT <component>]
8857 [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
8858 The FILES form specifies rules for installing files for a project.
8860 File names given as relative paths are interpreted with respect to the
8861 current source directory. Files installed by this form are by default
8862 given permissions OWNER_WRITE, OWNER_READ, GROUP_READ, and WORLD_READ
8863 if no PERMISSIONS argument is given.
8864 The PROGRAMS form is identical to the FILES form except that the de‐
8866 fault permissions for the installed file also include OWNER_EXECUTE,
8867 GROUP_EXECUTE, and WORLD_EXECUTE. This form is intended to install
8868 programs that are not targets, such as shell scripts. Use the TARGETS
8869 form to install targets built within the project.
8870 The list of files... given to FILES or PROGRAMS may use "generator ex‐
8872 pressions" with the syntax $<...>. See the cmake-generator-expres‐
8873 sions(7) manual for available expressions. However, if any item begins
8874 in a generator expression it must evaluate to a full path.
8875 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
8877 argument specifies the generic file type of the files being installed.
8878 A destination will then be set automatically by taking the correspond‐
8879 ing variable from GNUInstallDirs, or by using a built-in default if
8880 that variable is not defined. See the table below for the supported
8881 file types and their corresponding variables and built-in defaults.
8882 Projects can provide a DESTINATION argument instead of a file type if
8883 they wish to explicitly define the install destination.
8884 ┌──────────────┬─────────────────────┬─────────────────────┐
8886 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
8887 │ │ Variable │ │
8888 ├──────────────┼─────────────────────┼─────────────────────┤
8889 │BIN │ ${CMAKE_IN‐ │ bin │
8890 │ │ STALL_BINDIR} │ │
8891 ├──────────────┼─────────────────────┼─────────────────────┤
8892 │SBIN │ ${CMAKE_IN‐ │ sbin │
8893 │ │ STALL_SBINDIR} │ │
8894 ├──────────────┼─────────────────────┼─────────────────────┤
8895 │LIB │ ${CMAKE_IN‐ │ lib │
8896 │ │ STALL_LIBDIR} │ │
8897 ├──────────────┼─────────────────────┼─────────────────────┤
8898 │INCLUDE │ ${CMAKE_INSTALL_IN‐ │ include │
8899 │ │ CLUDEDIR} │ │
8900 ├──────────────┼─────────────────────┼─────────────────────┤
8901 │SYSCONF │ ${CMAKE_IN‐ │ etc │
8902 │ │ STALL_SYSCONFDIR} │ │
8903 ├──────────────┼─────────────────────┼─────────────────────┤
8904 │SHAREDSTATE │ ${CMAKE_IN‐ │ com │
8905 │ │ STALL_SHARESTATE‐ │ │
8906 │ │ DIR} │ │
8907 ├──────────────┼─────────────────────┼─────────────────────┤
8908 │LOCALSTATE │ ${CMAKE_INSTALL_LO‐ │ var │
8909 │ │ CALSTATEDIR} │ │
8910 ├──────────────┼─────────────────────┼─────────────────────┤
8911 │RUNSTATE │ ${CMAKE_IN‐ │ <LOCALSTATE │
8912 │ │ STALL_RUNSTATEDIR} │ dir>/run │
8913 ├──────────────┼─────────────────────┼─────────────────────┤
8914 │DATA │ ${CMAKE_IN‐ │ <DATAROOT dir> │
8915 │ │ STALL_DATADIR} │ │
8916 ├──────────────┼─────────────────────┼─────────────────────┤
8917 │INFO │ ${CMAKE_INSTALL_IN‐ │ <DATAROOT dir>/info │
8918 │ │ FODIR} │ │
8919 ├──────────────┼─────────────────────┼─────────────────────┤
8920 │LOCALE │ ${CMAKE_INSTALL_LO‐ │ <DATAROOT dir>/lo‐ │
8921 │ │ CALEDIR} │ cale │
8922 └──────────────┴─────────────────────┴─────────────────────┘
8923 │MAN │ ${CMAKE_IN‐ │ <DATAROOT dir>/man │
8926 │ │ STALL_MANDIR} │ │
8927 ├──────────────┼─────────────────────┼─────────────────────┤
8928 │DOC │ ${CMAKE_IN‐ │ <DATAROOT dir>/doc │
8929 │ │ STALL_DOCDIR} │ │
8930 └──────────────┴─────────────────────┴─────────────────────┘
8931 Projects wishing to follow the common practice of installing headers
8933 into a project-specific subdirectory will need to provide a destination
8934 rather than rely on the above.
8935 Note that some of the types' built-in defaults use the DATAROOT direc‐
8937 tory as a prefix. The DATAROOT prefix is calculated similarly to the
8938 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
8939 built-in default. You cannot use DATAROOT as a TYPE parameter; please
8940 use DATA instead.
8941 To make packages compliant with distribution filesystem layout poli‐
8943 cies, if projects must specify a DESTINATION, it is recommended that
8944 they use a path that begins with the appropriate GNUInstallDirs vari‐
8945 able. This allows package maintainers to control the install destina‐
8946 tion by setting the appropriate cache variables. The following example
8947 shows how to follow this advice while installing headers to a
8948 project-specific subdirectory:
8949 include(GNUInstallDirs)
8951 install(FILES mylib.h
8952 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
8953 )
8954 New in version 3.4: An install destination given as a DESTINATION argu‐
8956 ment may use "generator expressions" with the syntax $<...>. See the
8957 cmake-generator-expressions(7) manual for available expressions.
8958 New in version 3.20: An install rename given as a RENAME argument may
8961 use "generator expressions" with the syntax $<...>. See the cmake-gen‐
8962 erator-expressions(7) manual for available expressions.
8963 Installing Directories
8966 install(DIRECTORY dirs...
8967 TYPE <type> | DESTINATION <dir>
8968 [FILE_PERMISSIONS permissions...]
8969 [DIRECTORY_PERMISSIONS permissions...]
8970 [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
8971 [CONFIGURATIONS [Debug|Release|...]]
8972 [COMPONENT <component>] [EXCLUDE_FROM_ALL]
8973 [FILES_MATCHING]
8974 [[PATTERN <pattern> | REGEX <regex>]
8975 [EXCLUDE] [PERMISSIONS permissions...]] [...])
8976 The DIRECTORY form installs contents of one or more directories to a
8978 given destination. The directory structure is copied verbatim to the
8979 destination. The last component of each directory name is appended to
8980 the destination directory but a trailing slash may be used to avoid
8981 this because it leaves the last component empty. Directory names given
8982 as relative paths are interpreted with respect to the current source
8983 directory. If no input directory names are given the destination di‐
8984 rectory will be created but nothing will be installed into it. The
8985 FILE_PERMISSIONS and DIRECTORY_PERMISSIONS options specify permissions
8986 given to files and directories in the destination. If USE_SOURCE_PER‐
8987 MISSIONS is specified and FILE_PERMISSIONS is not, file permissions
8988 will be copied from the source directory structure. If no permissions
8989 are specified files will be given the default permissions specified in
8990 the FILES form of the command, and the directories will be given the
8991 default permissions specified in the PROGRAMS form of the command.
8992 New in version 3.1: The MESSAGE_NEVER option disables file installation
8994 status output.
8995 Installation of directories may be controlled with fine granularity us‐
8998 ing the PATTERN or REGEX options. These "match" options specify a
8999 globbing pattern or regular expression to match directories or files
9000 encountered within input directories. They may be used to apply cer‐
9001 tain options (see below) to a subset of the files and directories en‐
9002 countered. The full path to each input file or directory (with forward
9003 slashes) is matched against the expression. A PATTERN will match only
9004 complete file names: the portion of the full path matching the pattern
9005 must occur at the end of the file name and be preceded by a slash. A
9006 REGEX will match any portion of the full path but it may use / and $ to
9007 simulate the PATTERN behavior. By default all files and directories
9008 are installed whether or not they are matched. The FILES_MATCHING op‐
9009 tion may be given before the first match option to disable installation
9010 of files (but not directories) not matched by any expression. For ex‐
9011 ample, the code
9012 install(DIRECTORY src/ DESTINATION include/myproj
9014 FILES_MATCHING PATTERN "*.h")
9015 will extract and install header files from a source tree.
9017 Some options may follow a PATTERN or REGEX expression as described un‐
9019 der string(REGEX) and are applied only to files or directories matching
9020 them. The EXCLUDE option will skip the matched file or directory. The
9021 PERMISSIONS option overrides the permissions setting for the matched
9022 file or directory. For example the code
9023 install(DIRECTORY icons scripts/ DESTINATION share/myproj
9025 PATTERN "CVS" EXCLUDE
9026 PATTERN "scripts/*"
9027 PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
9028 GROUP_EXECUTE GROUP_READ)
9029 will install the icons directory to share/myproj/icons and the scripts
9031 directory to share/myproj. The icons will get default file permis‐
9032 sions, the scripts will be given specific permissions, and any CVS di‐
9033 rectories will be excluded.
9034 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
9036 argument specifies the generic file type of the files within the listed
9037 directories being installed. A destination will then be set automati‐
9038 cally by taking the corresponding variable from GNUInstallDirs, or by
9039 using a built-in default if that variable is not defined. See the ta‐
9040 ble below for the supported file types and their corresponding vari‐
9041 ables and built-in defaults. Projects can provide a DESTINATION argu‐
9042 ment instead of a file type if they wish to explicitly define the in‐
9043 stall destination.
9044 ┌──────────────┬─────────────────────┬─────────────────────┐
9046 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
9047 │ │ Variable │ │
9048 ├──────────────┼─────────────────────┼─────────────────────┤
9049 │BIN │ ${CMAKE_IN‐ │ bin │
9050 │ │ STALL_BINDIR} │ │
9051 ├──────────────┼─────────────────────┼─────────────────────┤
9052 │SBIN │ ${CMAKE_IN‐ │ sbin │
9053 │ │ STALL_SBINDIR} │ │
9054 ├──────────────┼─────────────────────┼─────────────────────┤
9055 │LIB │ ${CMAKE_IN‐ │ lib │
9056 │ │ STALL_LIBDIR} │ │
9057 ├──────────────┼─────────────────────┼─────────────────────┤
9058 │INCLUDE │ ${CMAKE_INSTALL_IN‐ │ include │
9059 │ │ CLUDEDIR} │ │
9060 ├──────────────┼─────────────────────┼─────────────────────┤
9061 │SYSCONF │ ${CMAKE_IN‐ │ etc │
9062 │ │ STALL_SYSCONFDIR} │ │
9063 ├──────────────┼─────────────────────┼─────────────────────┤
9064 │SHAREDSTATE │ ${CMAKE_IN‐ │ com │
9065 │ │ STALL_SHARESTATE‐ │ │
9066 │ │ DIR} │ │
9067 ├──────────────┼─────────────────────┼─────────────────────┤
9068 │LOCALSTATE │ ${CMAKE_INSTALL_LO‐ │ var │
9069 │ │ CALSTATEDIR} │ │
9070 ├──────────────┼─────────────────────┼─────────────────────┤
9071 │RUNSTATE │ ${CMAKE_IN‐ │ <LOCALSTATE │
9072 │ │ STALL_RUNSTATEDIR} │ dir>/run │
9073 ├──────────────┼─────────────────────┼─────────────────────┤
9074 │DATA │ ${CMAKE_IN‐ │ <DATAROOT dir> │
9075 │ │ STALL_DATADIR} │ │
9076 ├──────────────┼─────────────────────┼─────────────────────┤
9077 │INFO │ ${CMAKE_INSTALL_IN‐ │ <DATAROOT dir>/info │
9078 │ │ FODIR} │ │
9079 ├──────────────┼─────────────────────┼─────────────────────┤
9080 │LOCALE │ ${CMAKE_INSTALL_LO‐ │ <DATAROOT dir>/lo‐ │
9081 │ │ CALEDIR} │ cale │
9082 ├──────────────┼─────────────────────┼─────────────────────┤
9083 │MAN │ ${CMAKE_IN‐ │ <DATAROOT dir>/man │
9084 │ │ STALL_MANDIR} │ │
9085 ├──────────────┼─────────────────────┼─────────────────────┤
9086 │DOC │ ${CMAKE_IN‐ │ <DATAROOT dir>/doc │
9087 │ │ STALL_DOCDIR} │ │
9088 └──────────────┴─────────────────────┴─────────────────────┘
9089 Note that some of the types' built-in defaults use the DATAROOT direc‐
9091 tory as a prefix. The DATAROOT prefix is calculated similarly to the
9092 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
9093 built-in default. You cannot use DATAROOT as a TYPE parameter; please
9094 use DATA instead.
9095 To make packages compliant with distribution filesystem layout poli‐
9097 cies, if projects must specify a DESTINATION, it is recommended that
9098 they use a path that begins with the appropriate GNUInstallDirs vari‐
9099 able. This allows package maintainers to control the install destina‐
9100 tion by setting the appropriate cache variables.
9101 New in version 3.4: An install destination given as a DESTINATION argu‐
9103 ment may use "generator expressions" with the syntax $<...>. See the
9104 cmake-generator-expressions(7) manual for available expressions.
9105 New in version 3.5: The list of dirs... given to DIRECTORY may use
9108 "generator expressions" too.
9109 Custom Installation Logic
9112 install([[SCRIPT <file>] [CODE <code>]]
9113 [ALL_COMPONENTS | COMPONENT <component>]
9114 [EXCLUDE_FROM_ALL] [...])
9115 The SCRIPT form will invoke the given CMake script files during instal‐
9117 lation. If the script file name is a relative path it will be inter‐
9118 preted with respect to the current source directory. The CODE form
9119 will invoke the given CMake code during installation. Code is speci‐
9120 fied as a single argument inside a double-quoted string. For example,
9121 the code
9122 install(CODE "MESSAGE(\"Sample install message.\")")
9124 will print a message during installation.
9126 New in version 3.21: When the ALL_COMPONENTS option is given, the cus‐
9128 tom installation script code will be executed for every component of a
9129 component-specific installation. This option is mutually exclusive
9130 with the COMPONENT option.
9131 New in version 3.14: <file> or <code> may use "generator expressions"
9134 with the syntax $<...> (in the case of <file>, this refers to their use
9135 in the file name, not the file's contents). See the cmake-genera‐
9136 tor-expressions(7) manual for available expressions.
9137 Installing Exports
9140 install(EXPORT <export-name> DESTINATION <dir>
9141 [NAMESPACE <namespace>] [[FILE <name>.cmake]|
9142 [PERMISSIONS permissions...]
9143 [CONFIGURATIONS [Debug|Release|...]]
9144 [EXPORT_LINK_INTERFACE_LIBRARIES]
9145 [COMPONENT <component>]
9146 [EXCLUDE_FROM_ALL])
9147 install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])
9148 The EXPORT form generates and installs a CMake file containing code to
9150 import targets from the installation tree into another project. Target
9151 installations are associated with the export <export-name> using the
9152 EXPORT option of the install(TARGETS) signature documented above. The
9153 NAMESPACE option will prepend <namespace> to the target names as they
9154 are written to the import file. By default the generated file will be
9155 called <export-name>.cmake but the FILE option may be used to specify a
9156 different name. The value given to the FILE option must be a file name
9157 with the .cmake extension. If a CONFIGURATIONS option is given then
9158 the file will only be installed when one of the named configurations is
9159 installed. Additionally, the generated import file will reference only
9160 the matching target configurations. The EXPORT_LINK_INTERFACE_LI‐
9161 BRARIES keyword, if present, causes the contents of the properties
9162 matching (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be ex‐
9163 ported, when policy CMP0022 is NEW.
9164 NOTE:
9166 The installed <export-name>.cmake file may come with additional
9167 per-configuration <export-name>-*.cmake files to be loaded by glob‐
9168 bing. Do not use an export name that is the same as the package
9169 name in combination with installing a <package-name>-config.cmake
9170 file or the latter may be incorrectly matched by the glob and
9171 loaded.
9172 When a COMPONENT option is given, the listed <component> implicitly de‐
9174 pends on all components mentioned in the export set. The exported
9175 <name>.cmake file will require each of the exported components to be
9176 present in order for dependent projects to build properly. For example,
9177 a project may define components Runtime and Development, with shared
9178 libraries going into the Runtime component and static libraries and
9179 headers going into the Development component. The export set would also
9180 typically be part of the Development component, but it would export
9181 targets from both the Runtime and Development components. Therefore,
9182 the Runtime component would need to be installed if the Development
9183 component was installed, but not vice versa. If the Development compo‐
9184 nent was installed without the Runtime component, dependent projects
9185 that try to link against it would have build errors. Package managers,
9186 such as APT and RPM, typically handle this by listing the Runtime com‐
9187 ponent as a dependency of the Development component in the package
9188 metadata, ensuring that the library is always installed if the headers
9189 and CMake export file are present.
9190 New in version 3.7: In addition to cmake language files, the EXPORT_AN‐
9192 DROID_MK mode maybe used to specify an export to the android ndk build
9193 system. This mode accepts the same options as the normal export mode.
9194 The Android NDK supports the use of prebuilt libraries, both static and
9195 shared. This allows cmake to build the libraries of a project and make
9196 them available to an ndk build system complete with transitive depen‐
9197 dencies, include flags and defines required to use the libraries.
9198 The EXPORT form is useful to help outside projects use targets built
9201 and installed by the current project. For example, the code
9202 install(TARGETS myexe EXPORT myproj DESTINATION bin)
9204 install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
9205 install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules)
9206 will install the executable myexe to <prefix>/bin and code to import it
9208 in the file <prefix>/lib/myproj/myproj.cmake and <pre‐
9209 fix>/share/ndk-modules/Android.mk. An outside project may load this
9210 file with the include command and reference the myexe executable from
9211 the installation tree using the imported target name mp_myexe as if the
9212 target were built in its own tree.
9213 NOTE:
9215 This command supersedes the install_targets() command and the
9216 PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT target properties. It
9217 also replaces the FILES forms of the install_files() and in‐
9218 stall_programs() commands. The processing order of these install
9219 rules relative to those generated by install_targets(), in‐
9220 stall_files(), and install_programs() commands is not defined.
9221 Installing Runtime Dependencies
9223 New in version 3.21.
9224 install(RUNTIME_DEPENDENCY_SET <set-name>
9227 [[LIBRARY|RUNTIME|FRAMEWORK]
9228 [DESTINATION <dir>]
9229 [PERMISSIONS permissions...]
9230 [CONFIGURATIONS [Debug|Release|...]]
9231 [COMPONENT <component>]
9232 [NAMELINK_COMPONENT <component>]
9233 [OPTIONAL] [EXCLUDE_FROM_ALL]
9234 ] [...]
9235 [PRE_INCLUDE_REGEXES regexes...]
9236 [PRE_EXCLUDE_REGEXES regexes...]
9237 [POST_INCLUDE_REGEXES regexes...]
9238 [POST_EXCLUDE_REGEXES regexes...]
9239 [POST_INCLUDE_FILES files...]
9240 [POST_EXCLUDE_FILES files...]
9241 [DIRECTORIES directories...]
9242 )
9243 Installs a runtime dependency set previously created by one or more
9245 install(TARGETS) or install(IMPORTED_RUNTIME_ARTIFACTS) commands. The
9246 dependencies of targets belonging to a runtime dependency set are in‐
9247 stalled in the RUNTIME destination and component on DLL platforms, and
9248 in the LIBRARY destination and component on non-DLL platforms. macOS
9249 frameworks are installed in the FRAMEWORK destination and component.
9250 Targets built within the build tree will never be installed as runtime
9251 dependencies, nor will their own dependencies, unless the targets them‐
9252 selves are installed with install(TARGETS).
9253 The generated install script calls file(GET_RUNTIME_DEPENDENCIES) on
9255 the build-tree files to calculate the runtime dependencies. The
9256 build-tree executable files are passed as the EXECUTABLES argument, the
9257 build-tree shared libraries as the LIBRARIES argument, and the
9258 build-tree modules as the MODULES argument. On macOS, if one of the ex‐
9259 ecutables is a MACOSX_BUNDLE, that executable is passed as the BUN‐
9260 DLE_EXECUTABLE argument. At most one such bundle executable may be in
9261 the runtime dependency set on macOS. The MACOSX_BUNDLE property has no
9262 effect on other platforms. Note that file(GET_RUNTIME_DEPENDENCIES)
9263 only supports collecting the runtime dependencies for Windows, Linux
9264 and macOS platforms, so install(RUNTIME_DEPENDENCY_SET) has the same
9265 limitation.
9266 The following sub-arguments are forwarded through as the corresponding
9268 arguments to file(GET_RUNTIME_DEPENDENCIES) (for those that provide a
9269 non-empty list of directories, regular expressions or files). They all
9270 support generator expressions.
9271 • DIRECTORIES <directories>
9273 • PRE_INCLUDE_REGEXES <regexes>
9275 • PRE_EXCLUDE_REGEXES <regexes>
9277 • POST_INCLUDE_REGEXES <regexes>
9279 • POST_EXCLUDE_REGEXES <regexes>
9281 • POST_INCLUDE_FILES <files>
9283 • POST_EXCLUDE_FILES <files>
9285 Generated Installation Script
9287 NOTE:
9288 Use of this feature is not recommended. Please consider using the
9289 --install argument of cmake(1) instead.
9290 The install() command generates a file, cmake_install.cmake, inside the
9292 build directory, which is used internally by the generated install tar‐
9293 get and by CPack. You can also invoke this script manually with cmake
9294 -P. This script accepts several variables:
9295 COMPONENT
9297 Set this variable to install only a single CPack component as
9298 opposed to all of them. For example, if you only want to install
9299 the Development component, run cmake -DCOMPONENT=Development -P
9300 cmake_install.cmake.
9301 BUILD_TYPE
9303 Set this variable to change the build type if you are using a
9304 multi-config generator. For example, to install with the Debug
9305 configuration, run cmake -DBUILD_TYPE=Debug -P cmake_in‐
9306 stall.cmake.
9307 DESTDIR
9309 This is an environment variable rather than a CMake variable. It
9310 allows you to change the installation prefix on UNIX systems.
9311 See DESTDIR for details.
9312 link_directories
9314 Add directories in which the linker will look for libraries.
9315 link_directories([AFTER|BEFORE] directory1 [directory2 ...])
9317 Adds the paths in which the linker should search for libraries. Rela‐
9319 tive paths given to this command are interpreted as relative to the
9320 current source directory, see CMP0015.
9321 The command will apply only to targets created after it is called.
9323 New in version 3.13: The directories are added to the LINK_DIRECTORIES
9325 directory property for the current CMakeLists.txt file, converting rel‐
9326 ative paths to absolute as needed. See the cmake-buildsystem(7) manual
9327 for more on defining buildsystem properties.
9328 New in version 3.13: By default the directories specified are appended
9331 onto the current list of directories. This default behavior can be
9332 changed by setting CMAKE_LINK_DIRECTORIES_BEFORE to ON. By using AFTER
9333 or BEFORE explicitly, you can select between appending and prepending,
9334 independent of the default.
9335 New in version 3.13: Arguments to link_directories may use "generator
9338 expressions" with the syntax "$<...>". See the cmake-generator-expres‐
9339 sions(7) manual for available expressions.
9340 NOTE:
9343 This command is rarely necessary and should be avoided where there
9344 are other choices. Prefer to pass full absolute paths to libraries
9345 where possible, since this ensures the correct library will always
9346 be linked. The find_library() command provides the full path, which
9347 can generally be used directly in calls to target_link_libraries().
9348 Situations where a library search path may be needed include:
9349 • Project generators like Xcode where the user can switch target ar‐
9351 chitecture at build time, but a full path to a library cannot be
9352 used because it only provides one architecture (i.e. it is not a
9353 universal binary).
9354 • Libraries may themselves have other private library dependencies
9356 that expect to be found via RPATH mechanisms, but some linkers are
9357 not able to fully decode those paths (e.g. due to the presence of
9358 things like $ORIGIN).
9359 If a library search path must be provided, prefer to localize the
9361 effect where possible by using the target_link_directories() command
9362 rather than link_directories(). The target-specific command can
9363 also control how the search directories propagate to other dependent
9364 targets.
9365 link_libraries
9367 Link libraries to all targets added later.
9368 link_libraries([item1 [item2 [...]]]
9370 [[debug|optimized|general] <item>] ...)
9371 Specify libraries or flags to use when linking any targets created
9373 later in the current directory or below by commands such as add_exe‐
9374 cutable() or add_library(). See the target_link_libraries() command
9375 for meaning of arguments.
9376 NOTE:
9378 The target_link_libraries() command should be preferred whenever
9379 possible. Library dependencies are chained automatically, so direc‐
9380 tory-wide specification of link libraries is rarely needed.
9381 load_cache
9383 Load in the values from another project's CMake cache.
9384 load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...)
9386 Reads the cache and store the requested entries in variables with their
9388 name prefixed with the given prefix. This only reads the values, and
9389 does not create entries in the local project's cache.
9390 load_cache(pathToBuildDirectory [EXCLUDE entry1...]
9392 [INCLUDE_INTERNALS entry1...])
9393 Loads in the values from another cache and store them in the local
9395 project's cache as internal entries. This is useful for a project that
9396 depends on another project built in a different tree. EXCLUDE option
9397 can be used to provide a list of entries to be excluded. INCLUDE_IN‐
9398 TERNALS can be used to provide a list of internal entries to be in‐
9399 cluded. Normally, no internal entries are brought in. Use of this
9400 form of the command is strongly discouraged, but it is provided for
9401 backward compatibility.
9402 project
9404 Set the name of the project.
9405 Synopsis
9407 project(<PROJECT-NAME> [<language-name>...])
9408 project(<PROJECT-NAME>
9409 [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
9410 [DESCRIPTION <project-description-string>]
9411 [HOMEPAGE_URL <url-string>]
9412 [LANGUAGES <language-name>...])
9413 Sets the name of the project, and stores it in the variable
9415 PROJECT_NAME. When called from the top-level CMakeLists.txt also stores
9416 the project name in the variable CMAKE_PROJECT_NAME.
9417 Also sets the variables:
9419 PROJECT_SOURCE_DIR, <PROJECT-NAME>_SOURCE_DIR
9421 Absolute path to the source directory for the project.
9422 PROJECT_BINARY_DIR, <PROJECT-NAME>_BINARY_DIR
9424 Absolute path to the binary directory for the project.
9425 PROJECT_IS_TOP_LEVEL, <PROJECT-NAME>_IS_TOP_LEVEL
9427 New in version 3.21.
9428 Boolean value indicating whether the project is top-level.
9431 Further variables are set by the optional arguments described in the
9433 following. If any of these arguments is not used, then the correspond‐
9434 ing variables are set to the empty string.
9435 Options
9437 The options are:
9438 VERSION <version>
9440 Optional; may not be used unless policy CMP0048 is set to NEW.
9441 Takes a <version> argument composed of non-negative integer com‐
9443 ponents, i.e. <major>[.<minor>[.<patch>[.<tweak>]]], and sets
9444 the variables
9445 • PROJECT_VERSION, <PROJECT-NAME>_VERSION
9447 • PROJECT_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MAJOR
9449 • PROJECT_VERSION_MINOR, <PROJECT-NAME>_VERSION_MINOR
9451 • PROJECT_VERSION_PATCH, <PROJECT-NAME>_VERSION_PATCH
9453 • PROJECT_VERSION_TWEAK, <PROJECT-NAME>_VERSION_TWEAK.
9455 New in version 3.12: When the project() command is called from
9457 the top-level CMakeLists.txt, then the version is also stored in
9458 the variable CMAKE_PROJECT_VERSION.
9459 DESCRIPTION <project-description-string>
9462 New in version 3.9.
9463 Optional. Sets the variables
9466 • PROJECT_DESCRIPTION, <PROJECT-NAME>_DESCRIPTION
9468 to <project-description-string>. It is recommended that this
9470 description is a relatively short string, usually no more than a
9471 few words.
9472 When the project() command is called from the top-level CMake‐
9474 Lists.txt, then the description is also stored in the variable
9475 CMAKE_PROJECT_DESCRIPTION.
9476 New in version 3.12: Added the <PROJECT-NAME>_DESCRIPTION vari‐
9478 able.
9479 HOMEPAGE_URL <url-string>
9482 New in version 3.12.
9483 Optional. Sets the variables
9486 • PROJECT_HOMEPAGE_URL, <PROJECT-NAME>_HOMEPAGE_URL
9488 to <url-string>, which should be the canonical home URL for the
9490 project.
9491 When the project() command is called from the top-level CMake‐
9493 Lists.txt, then the URL also is stored in the variable
9494 CMAKE_PROJECT_HOMEPAGE_URL.
9495 LANGUAGES <language-name>...
9497 Optional. Can also be specified without LANGUAGES keyword per
9498 the first, short signature.
9499 Selects which programming languages are needed to build the
9501 project. Supported languages include C, CXX (i.e. C++), CUDA,
9502 OBJC (i.e. Objective-C), OBJCXX, Fortran, HIP, ISPC, and ASM.
9503 By default C and CXX are enabled if no language options are
9504 given. Specify language NONE, or use the LANGUAGES keyword and
9505 list no languages, to skip enabling any languages.
9506 New in version 3.8: Added CUDA support.
9508 New in version 3.16: Added OBJC and OBJCXX support.
9511 New in version 3.18: Added ISPC support.
9514 If enabling ASM, list it last so that CMake can check whether
9517 compilers for other languages like C work for assembly too.
9518 The variables set through the VERSION, DESCRIPTION and HOMEPAGE_URL op‐
9520 tions are intended for use as default values in package metadata and
9521 documentation.
9522 Code Injection
9524 If the CMAKE_PROJECT_INCLUDE_BEFORE or CMAKE_PROJECT_<PROJECT-NAME>_IN‐
9525 CLUDE_BEFORE variables are set, the files they point to will be in‐
9526 cluded as the first step of the project() command. If both are set,
9527 then CMAKE_PROJECT_INCLUDE_BEFORE will be included before
9528 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE.
9529 If the CMAKE_PROJECT_INCLUDE or CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE
9531 variables are set, the files they point to will be included as the last
9532 step of the project() command. If both are set, then CMAKE_PROJECT_IN‐
9533 CLUDE will be included before CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE.
9534 New in version 3.15: Added the CMAKE_PROJECT_INCLUDE and
9536 CMAKE_PROJECT_INCLUDE_BEFORE variables.
9537 New in version 3.17: Added the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BE‐
9540 FORE variable.
9541 Usage
9544 The top-level CMakeLists.txt file for a project must contain a literal,
9545 direct call to the project() command; loading one through the include()
9546 command is not sufficient. If no such call exists, CMake will issue a
9547 warning and pretend there is a project(Project) at the top to enable
9548 the default languages (C and CXX).
9549 NOTE:
9551 Call the project() command near the top of the top-level CMake‐
9552 Lists.txt, but after calling cmake_minimum_required(). It is impor‐
9553 tant to establish version and policy settings before invoking other
9554 commands whose behavior they may affect. See also policy CMP0000.
9555 remove_definitions
9557 Remove -D define flags added by add_definitions().
9558 remove_definitions(-DFOO -DBAR ...)
9560 Removes flags (added by add_definitions()) from the compiler command
9562 line for sources in the current directory and below.
9563 set_source_files_properties
9565 Source files can have properties that affect how they are built.
9566 set_source_files_properties(<files> ...
9568 [DIRECTORY <dirs> ...]
9569 [TARGET_DIRECTORY <targets> ...]
9570 PROPERTIES <prop1> <value1>
9571 [<prop2> <value2>] ...)
9572 Sets properties associated with source files using a key/value paired
9574 list.
9575 New in version 3.18: By default, source file properties are only visi‐
9577 ble to targets added in the same directory (CMakeLists.txt). Visibil‐
9578 ity can be set in other directory scopes using one or both of the fol‐
9579 lowing options:
9580 DIRECTORY <dirs>...
9583 The source file properties will be set in each of the <dirs> di‐
9584 rectories' scopes. CMake must already know about each of these
9585 source directories, either by having added them through a call
9586 to add_subdirectory() or it being the top level source direc‐
9587 tory. Relative paths are treated as relative to the current
9588 source directory.
9589 TARGET_DIRECTORY <targets>...
9591 The source file properties will be set in each of the directory
9592 scopes where any of the specified <targets> were created (the
9593 <targets> must therefore already exist).
9594 Use get_source_file_property() to get property values. See also the
9596 set_property(SOURCE) command.
9597 See Source File Properties for the list of properties known to CMake.
9599 NOTE:
9601 The GENERATED source file property may be globally visible. See its
9602 documentation for details.
9603 set_target_properties
9605 Targets can have properties that affect how they are built.
9606 set_target_properties(target1 target2 ...
9608 PROPERTIES prop1 value1
9609 prop2 value2 ...)
9610 Sets properties on targets. The syntax for the command is to list all
9612 the targets you want to change, and then provide the values you want to
9613 set next. You can use any prop value pair you want and extract it
9614 later with the get_property() or get_target_property() command.
9615 See also the set_property(TARGET) command.
9617 See Target Properties for the list of properties known to CMake.
9619 set_tests_properties
9621 Set a property of the tests.
9622 set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
9624 Sets a property for the tests. If the test is not found, CMake will
9626 report an error. Generator expressions will be expanded the same as
9627 supported by the test's add_test() call.
9628 See also the set_property(TEST) command.
9630 See Test Properties for the list of properties known to CMake.
9632 source_group
9634 Define a grouping for source files in IDE project generation. There
9635 are two different signatures to create source groups.
9636 source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
9638 source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...])
9639 Defines a group into which sources will be placed in project files.
9641 This is intended to set up file tabs in Visual Studio. The group is
9642 scoped in the directory where the command is called, and applies to
9643 sources in targets created in that directory.
9644 The options are:
9646 TREE New in version 3.8.
9648 CMake will automatically detect, from <src> files paths, source
9651 groups it needs to create, to keep structure of source groups
9652 analogically to the actual files and directories structure in
9653 the project. Paths of <src> files will be cut to be relative to
9654 <root>. The command fails if the paths within src do not start
9655 with root.
9656 PREFIX New in version 3.8.
9658 Source group and files located directly in <root> path, will be
9661 placed in <prefix> source groups.
9662 FILES Any source file specified explicitly will be placed in group
9664 <name>. Relative paths are interpreted with respect to the cur‐
9665 rent source directory.
9666 REGULAR_EXPRESSION
9668 Any source file whose name matches the regular expression will
9669 be placed in group <name>.
9670 If a source file matches multiple groups, the last group that explic‐
9672 itly lists the file with FILES will be favored, if any. If no group
9673 explicitly lists the file, the last group whose regular expression
9674 matches the file will be favored.
9675 The <name> of the group and <prefix> argument may contain forward
9677 slashes or backslashes to specify subgroups. Backslashes need to be
9678 escaped appropriately:
9679 source_group(base/subdir ...)
9681 source_group(outer\\inner ...)
9682 source_group(TREE <root> PREFIX sources\\inc ...)
9683 New in version 3.18: Allow using forward slashes (/) to specify sub‐
9685 groups.
9686 For backwards compatibility, the short-hand signature
9689 source_group(<name> <regex>)
9691 is equivalent to
9693 source_group(<name> REGULAR_EXPRESSION <regex>)
9695 target_compile_definitions
9697 Add compile definitions to a target.
9698 target_compile_definitions(<target>
9700 <INTERFACE|PUBLIC|PRIVATE> [items1...]
9701 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
9702 Specifies compile definitions to use when compiling a given <target>.
9704 The named <target> must have been created by a command such as add_exe‐
9705 cutable() or add_library() and must not be an ALIAS target.
9706 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9708 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
9709 late the COMPILE_DEFINITIONS property of <target>. PUBLIC and INTERFACE
9710 items will populate the INTERFACE_COMPILE_DEFINITIONS property of <tar‐
9711 get>. The following arguments specify compile definitions. Repeated
9712 calls for the same <target> append items in the order called.
9713 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
9715 Arguments to target_compile_definitions may use "generator expressions"
9718 with the syntax $<...>. See the cmake-generator-expressions(7) manual
9719 for available expressions. See the cmake-buildsystem(7) manual for
9720 more on defining buildsystem properties.
9721 Any leading -D on an item will be removed. Empty items are ignored.
9723 For example, the following are all equivalent:
9724 target_compile_definitions(foo PUBLIC FOO)
9726 target_compile_definitions(foo PUBLIC -DFOO) # -D removed
9727 target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
9728 target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
9729 Definitions may optionally have values:
9731 target_compile_definitions(foo PUBLIC FOO=1)
9733 Note that many compilers treat -DFOO as equivalent to -DFOO=1, but
9735 other tools may not recognize this in all circumstances (e.g. Intel‐
9736 liSense).
9737 target_compile_features
9739 New in version 3.1.
9740 Add expected compiler features to a target.
9743 target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
9745 Specifies compiler features required when compiling a given target. If
9747 the feature is not listed in the CMAKE_C_COMPILE_FEATURES,
9748 CMAKE_CUDA_COMPILE_FEATURES, or CMAKE_CXX_COMPILE_FEATURES variables,
9749 then an error will be reported by CMake. If the use of the feature re‐
9750 quires an additional compiler flag, such as -std=gnu++11, the flag will
9751 be added automatically.
9752 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9754 scope of the features. PRIVATE and PUBLIC items will populate the COM‐
9755 PILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
9756 populate the INTERFACE_COMPILE_FEATURES property of <target>. Repeated
9757 calls for the same <target> append items.
9758 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
9760 The named <target> must have been created by a command such as add_exe‐
9763 cutable() or add_library() and must not be an ALIAS target.
9764 Arguments to target_compile_features may use "generator expressions"
9766 with the syntax $<...>. See the cmake-generator-expressions(7) manual
9767 for available expressions. See the cmake-compile-features(7) manual
9768 for information on compile features and a list of supported compilers.
9769 target_compile_options
9771 Add compile options to a target.
9772 target_compile_options(<target> [BEFORE]
9774 <INTERFACE|PUBLIC|PRIVATE> [items1...]
9775 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
9776 Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
9778 properties. These options are used when compiling the given <target>,
9779 which must have been created by a command such as add_executable() or
9780 add_library() and must not be an ALIAS target.
9781 Arguments
9783 If BEFORE is specified, the content will be prepended to the property
9784 instead of being appended.
9785 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9787 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
9788 late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
9789 items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
9790 The following arguments specify compile options. Repeated calls for
9791 the same <target> append items in the order called.
9792 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
9794 Arguments to target_compile_options may use "generator expressions"
9797 with the syntax $<...>. See the cmake-generator-expressions(7) manual
9798 for available expressions. See the cmake-buildsystem(7) manual for
9799 more on defining buildsystem properties.
9800 Option De-duplication
9802 The final set of options used for a target is constructed by accumulat‐
9803 ing options from the current target and the usage requirements of its
9804 dependencies. The set of options is de-duplicated to avoid repetition.
9805 New in version 3.12: While beneficial for individual options, the
9807 de-duplication step can break up option groups. For example, -option A
9808 -option B becomes -option A B. One may specify a group of options us‐
9809 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
9810 is dropped, and the rest of the option string is parsed using the sepa‐
9811 rate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
9812 "SHELL:-option B" becomes -option A -option B.
9813 See Also
9816 This command can be used to add any options. However, for adding pre‐
9817 processor definitions and include directories it is recommended to use
9818 the more specific commands target_compile_definitions() and target_in‐
9819 clude_directories().
9820 For directory-wide settings, there is the command add_compile_op‐
9822 tions().
9823 For file-specific settings, there is the source file property COM‐
9825 PILE_OPTIONS.
9826 target_include_directories
9828 Add include directories to a target.
9829 target_include_directories(<target> [SYSTEM] [AFTER|BEFORE]
9831 <INTERFACE|PUBLIC|PRIVATE> [items1...]
9832 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
9833 Specifies include directories to use when compiling a given target.
9835 The named <target> must have been created by a command such as add_exe‐
9836 cutable() or add_library() and must not be an ALIAS target.
9837 By using AFTER or BEFORE explicitly, you can select between appending
9839 and prepending, independent of the default.
9840 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9842 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
9843 late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTER‐
9844 FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
9845 <target>. The following arguments specify include directories.
9846 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
9848 Specified include directories may be absolute paths or relative paths.
9851 Repeated calls for the same <target> append items in the order called.
9852 If SYSTEM is specified, the compiler will be told the directories are
9853 meant as system include directories on some platforms (signalling this
9854 setting might achieve effects such as the compiler skipping warnings,
9855 or these fixed-install system files not being considered in dependency
9856 calculations - see compiler docs). If SYSTEM is used together with
9857 PUBLIC or INTERFACE, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
9858 property will be populated with the specified directories.
9859 Arguments to target_include_directories may use "generator expressions"
9861 with the syntax $<...>. See the cmake-generator-expressions(7) manual
9862 for available expressions. See the cmake-buildsystem(7) manual for
9863 more on defining buildsystem properties.
9864 Include directories usage requirements commonly differ between the
9866 build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN‐
9867 TERFACE generator expressions can be used to describe separate usage
9868 requirements based on the usage location. Relative paths are allowed
9869 within the INSTALL_INTERFACE expression and are interpreted relative to
9870 the installation prefix. For example:
9871 target_include_directories(mylib PUBLIC
9873 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
9874 $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
9875 )
9876 Creating Relocatable Packages
9878 Note that it is not advisable to populate the INSTALL_INTERFACE of the
9879 INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
9880 include directories of dependencies. That would hard-code into in‐
9881 stalled packages the include directory paths for dependencies as found
9882 on the machine the package was made on.
9883 The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
9885 suitable for specifying the required include directories for headers
9886 provided with the target itself, not those provided by the transitive
9887 dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
9888 Those dependencies should themselves be targets that specify their own
9889 header locations in INTERFACE_INCLUDE_DIRECTORIES.
9890 See the Creating Relocatable Packages section of the cmake-packages(7)
9892 manual for discussion of additional care that must be taken when speci‐
9893 fying usage requirements while creating packages for redistribution.
9894 target_link_directories
9896 New in version 3.13.
9897 Add link directories to a target.
9900 target_link_directories(<target> [BEFORE]
9902 <INTERFACE|PUBLIC|PRIVATE> [items1...]
9903 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
9904 Specifies the paths in which the linker should search for libraries
9906 when linking a given target. Each item can be an absolute or relative
9907 path, with the latter being interpreted as relative to the current
9908 source directory. These items will be added to the link command.
9909 The named <target> must have been created by a command such as add_exe‐
9911 cutable() or add_library() and must not be an ALIAS target.
9912 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9914 scope of the items that follow them. PRIVATE and PUBLIC items will
9915 populate the LINK_DIRECTORIES property of <target>. PUBLIC and INTER‐
9916 FACE items will populate the INTERFACE_LINK_DIRECTORIES property of
9917 <target> (IMPORTED targets only support INTERFACE items). Each item
9918 specifies a link directory and will be converted to an absolute path if
9919 necessary before adding it to the relevant property. Repeated calls
9920 for the same <target> append items in the order called.
9921 If BEFORE is specified, the content will be prepended to the relevant
9923 property instead of being appended.
9924 Arguments to target_link_directories may use "generator expressions"
9926 with the syntax $<...>. See the cmake-generator-expressions(7) manual
9927 for available expressions. See the cmake-buildsystem(7) manual for
9928 more on defining buildsystem properties.
9929 NOTE:
9931 This command is rarely necessary and should be avoided where there
9932 are other choices. Prefer to pass full absolute paths to libraries
9933 where possible, since this ensures the correct library will always
9934 be linked. The find_library() command provides the full path, which
9935 can generally be used directly in calls to target_link_libraries().
9936 Situations where a library search path may be needed include:
9937 • Project generators like Xcode where the user can switch target ar‐
9939 chitecture at build time, but a full path to a library cannot be
9940 used because it only provides one architecture (i.e. it is not a
9941 universal binary).
9942 • Libraries may themselves have other private library dependencies
9944 that expect to be found via RPATH mechanisms, but some linkers are
9945 not able to fully decode those paths (e.g. due to the presence of
9946 things like $ORIGIN).
9947 target_link_libraries
9949 Specify libraries or flags to use when linking a given target and/or
9950 its dependents. Usage requirements from linked library targets will be
9951 propagated. Usage requirements of a target's dependencies affect com‐
9952 pilation of its own sources.
9953 Overview
9955 This command has several signatures as detailed in subsections below.
9956 All of them have the general form
9957 target_link_libraries(<target> ... <item>... ...)
9959 The named <target> must have been created by a command such as add_exe‐
9961 cutable() or add_library() and must not be an ALIAS target. If policy
9962 CMP0079 is not set to NEW then the target must have been created in the
9963 current directory. Repeated calls for the same <target> append items
9964 in the order called.
9965 New in version 3.13: The <target> doesn't have to be defined in the
9967 same directory as the target_link_libraries call.
9968 Each <item> may be:
9971 • A library target name: The generated link line will have the full
9973 path to the linkable library file associated with the target. The
9974 buildsystem will have a dependency to re-link <target> if the library
9975 file changes.
9976 The named target must be created by add_library() within the project
9978 or as an IMPORTED library. If it is created within the project an
9979 ordering dependency will automatically be added in the build system
9980 to make sure the named library target is up-to-date before the <tar‐
9981 get> links.
9982 If an imported library has the IMPORTED_NO_SONAME target property
9984 set, CMake may ask the linker to search for the library instead of
9985 using the full path (e.g. /usr/lib/libfoo.so becomes -lfoo).
9986 The full path to the target's artifact will be quoted/escaped for the
9988 shell automatically.
9989 • A full path to a library file: The generated link line will normally
9991 preserve the full path to the file. The buildsystem will have a de‐
9992 pendency to re-link <target> if the library file changes.
9993 There are some cases where CMake may ask the linker to search for the
9995 library (e.g. /usr/lib/libfoo.so becomes -lfoo), such as when a
9996 shared library is detected to have no SONAME field. See policy
9997 CMP0060 for discussion of another case.
9998 If the library file is in a macOS framework, the Headers directory of
10000 the framework will also be processed as a usage requirement. This
10001 has the same effect as passing the framework directory as an include
10002 directory.
10003 New in version 3.8: On Visual Studio Generators for VS 2010 and
10005 above, library files ending in .targets will be treated as MSBuild
10006 targets files and imported into generated project files. This is not
10007 supported by other generators.
10008 The full path to the library file will be quoted/escaped for the
10011 shell automatically.
10012 • A plain library name: The generated link line will ask the linker to
10014 search for the library (e.g. foo becomes -lfoo or foo.lib).
10015 The library name/flag is treated as a command-line string fragment
10017 and will be used with no extra quoting or escaping.
10018 • A link flag: Item names starting with -, but not -l or -framework,
10020 are treated as linker flags. Note that such flags will be treated
10021 like any other library link item for purposes of transitive dependen‐
10022 cies, so they are generally safe to specify only as private link
10023 items that will not propagate to dependents.
10024 Link flags specified here are inserted into the link command in the
10026 same place as the link libraries. This might not be correct, depend‐
10027 ing on the linker. Use the LINK_OPTIONS target property or tar‐
10028 get_link_options() command to add link flags explicitly. The flags
10029 will then be placed at the toolchain-defined flag position in the
10030 link command.
10031 New in version 3.13: LINK_OPTIONS target property and target_link_op‐
10033 tions() command. For earlier versions of CMake, use LINK_FLAGS prop‐
10034 erty instead.
10035 The link flag is treated as a command-line string fragment and will
10038 be used with no extra quoting or escaping.
10039 • A generator expression: A $<...> generator expression may evaluate to
10041 any of the above items or to a semicolon-separated list of them. If
10042 the ... contains any ; characters, e.g. after evaluation of a ${list}
10043 variable, be sure to use an explicitly quoted argument "$<...>" so
10044 that this command receives it as a single <item>.
10045 Additionally, a generator expression may be used as a fragment of any
10047 of the above items, e.g. foo$<1:_d>.
10048 Note that generator expressions will not be used in OLD handling of
10050 policy CMP0003 or policy CMP0004.
10051 • A debug, optimized, or general keyword immediately followed by an‐
10053 other <item>. The item following such a keyword will be used only
10054 for the corresponding build configuration. The debug keyword corre‐
10055 sponds to the Debug configuration (or to configurations named in the
10056 DEBUG_CONFIGURATIONS global property if it is set). The optimized
10057 keyword corresponds to all other configurations. The general keyword
10058 corresponds to all configurations, and is purely optional. Higher
10059 granularity may be achieved for per-configuration rules by creating
10060 and linking to IMPORTED library targets. These keywords are inter‐
10061 preted immediately by this command and therefore have no special
10062 meaning when produced by a generator expression.
10063 Items containing ::, such as Foo::Bar, are assumed to be IMPORTED or
10065 ALIAS library target names and will cause an error if no such target
10066 exists. See policy CMP0028.
10067 See the cmake-buildsystem(7) manual for more on defining buildsystem
10069 properties.
10070 Libraries for a Target and/or its Dependents
10072 target_link_libraries(<target>
10073 <PRIVATE|PUBLIC|INTERFACE> <item>...
10074 [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
10075 The PUBLIC, PRIVATE and INTERFACE keywords can be used to specify both
10077 the link dependencies and the link interface in one command. Libraries
10078 and targets following PUBLIC are linked to, and are made part of the
10079 link interface. Libraries and targets following PRIVATE are linked to,
10080 but are not made part of the link interface. Libraries following IN‐
10081 TERFACE are appended to the link interface and are not used for linking
10082 <target>.
10083 Libraries for both a Target and its Dependents
10085 target_link_libraries(<target> <item>...)
10086 Library dependencies are transitive by default with this signature.
10088 When this target is linked into another target then the libraries
10089 linked to this target will appear on the link line for the other target
10090 too. This transitive "link interface" is stored in the INTER‐
10091 FACE_LINK_LIBRARIES target property and may be overridden by setting
10092 the property directly. When CMP0022 is not set to NEW, transitive
10093 linking is built in but may be overridden by the LINK_INTERFACE_LI‐
10094 BRARIES property. Calls to other signatures of this command may set
10095 the property making any libraries linked exclusively by this signature
10096 private.
10097 Libraries for a Target and/or its Dependents (Legacy)
10099 target_link_libraries(<target>
10100 <LINK_PRIVATE|LINK_PUBLIC> <lib>...
10101 [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
10102 The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both the
10104 link dependencies and the link interface in one command.
10105 This signature is for compatibility only. Prefer the PUBLIC or PRIVATE
10107 keywords instead.
10108 Libraries and targets following LINK_PUBLIC are linked to, and are made
10110 part of the INTERFACE_LINK_LIBRARIES. If policy CMP0022 is not NEW,
10111 they are also made part of the LINK_INTERFACE_LIBRARIES. Libraries and
10112 targets following LINK_PRIVATE are linked to, but are not made part of
10113 the INTERFACE_LINK_LIBRARIES (or LINK_INTERFACE_LIBRARIES).
10114 Libraries for Dependents Only (Legacy)
10116 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
10117 The LINK_INTERFACE_LIBRARIES mode appends the libraries to the INTER‐
10119 FACE_LINK_LIBRARIES target property instead of using them for linking.
10120 If policy CMP0022 is not NEW, then this mode also appends libraries to
10121 the LINK_INTERFACE_LIBRARIES and its per-configuration equivalent.
10122 This signature is for compatibility only. Prefer the INTERFACE mode
10124 instead.
10125 Libraries specified as debug are wrapped in a generator expression to
10127 correspond to debug builds. If policy CMP0022 is not NEW, the li‐
10128 braries are also appended to the LINK_INTERFACE_LIBRARIES_DEBUG prop‐
10129 erty (or to the properties corresponding to configurations listed in
10130 the DEBUG_CONFIGURATIONS global property if it is set). Libraries
10131 specified as optimized are appended to the INTERFACE_LINK_LIBRARIES
10132 property. If policy CMP0022 is not NEW, they are also appended to the
10133 LINK_INTERFACE_LIBRARIES property. Libraries specified as general (or
10134 without any keyword) are treated as if specified for both debug and op‐
10135 timized.
10136 Linking Object Libraries
10138 New in version 3.12.
10139 Object Libraries may be used as the <target> (first) argument of tar‐
10142 get_link_libraries to specify dependencies of their sources on other
10143 libraries. For example, the code
10144 add_library(A SHARED a.c)
10146 target_compile_definitions(A PUBLIC A)
10147 add_library(obj OBJECT obj.c)
10149 target_compile_definitions(obj PUBLIC OBJ)
10150 target_link_libraries(obj PUBLIC A)
10151 compiles obj.c with -DA -DOBJ and establishes usage requirements for
10153 obj that propagate to its dependents.
10154 Normal libraries and executables may link to Object Libraries to get
10156 their objects and usage requirements. Continuing the above example,
10157 the code
10158 add_library(B SHARED b.c)
10160 target_link_libraries(B PUBLIC obj)
10161 compiles b.c with -DA -DOBJ, creates shared library B with object files
10163 from b.c and obj.c, and links B to A. Furthermore, the code
10164 add_executable(main main.c)
10166 target_link_libraries(main B)
10167 compiles main.c with -DA -DOBJ and links executable main to B and A.
10169 The object library's usage requirements are propagated transitively
10170 through B, but its object files are not.
10171 Object Libraries may "link" to other object libraries to get usage re‐
10173 quirements, but since they do not have a link step nothing is done with
10174 their object files. Continuing from the above example, the code:
10175 add_library(obj2 OBJECT obj2.c)
10177 target_link_libraries(obj2 PUBLIC obj)
10178 add_executable(main2 main2.c)
10180 target_link_libraries(main2 obj2)
10181 compiles obj2.c with -DA -DOBJ, creates executable main2 with object
10183 files from main2.c and obj2.c, and links main2 to A.
10184 In other words, when Object Libraries appear in a target's INTER‐
10186 FACE_LINK_LIBRARIES property they will be treated as Interface Li‐
10187 braries, but when they appear in a target's LINK_LIBRARIES property
10188 their object files will be included in the link too.
10189 Linking Object Libraries via $<TARGET_OBJECTS>
10191 New in version 3.21.
10192 The object files associated with an object library may be referenced by
10195 the $<TARGET_OBJECTS> generator expression. Such object files are
10196 placed on the link line before all libraries, regardless of their rela‐
10197 tive order. Additionally, an ordering dependency will be added to the
10198 build system to make sure the object library is up-to-date before the
10199 dependent target links. For example, the code
10200 add_library(obj3 OBJECT obj3.c)
10202 target_compile_definitions(obj3 PUBLIC OBJ3)
10203 add_executable(main3 main3.c)
10205 target_link_libraries(main3 PRIVATE a3 $<TARGET_OBJECTS:obj3> b3)
10206 links executable main3 with object files from main3.c and obj3.c fol‐
10208 lowed by the a3 and b3 libraries. main3.c is not compiled with usage
10209 requirements from obj3, such as -DOBJ3.
10210 This approach can be used to achieve transitive inclusion of object
10212 files in link lines as usage requirements. Continuing the above exam‐
10213 ple, the code
10214 add_library(iface_obj3 INTERFACE)
10216 target_link_libraries(iface_obj3 INTERFACE obj3 $<TARGET_OBJECTS:obj3>)
10217 creates an interface library iface_obj3 that forwards the obj3 usage
10219 requirements and adds the obj3 object files to dependents' link lines.
10220 The code
10221 add_executable(use_obj3 use_obj3.c)
10223 target_link_libraries(use_obj3 PRIVATE iface_obj3)
10224 compiles use_obj3.c with -DOBJ3 and links executable use_obj3 with ob‐
10226 ject files from use_obj3.c and obj3.c.
10227 This also works transitively through a static library. Since a static
10229 library does not link, it does not consume the object files from object
10230 libraries referenced this way. Instead, the object files become tran‐
10231 sitive link dependencies of the static library. Continuing the above
10232 example, the code
10233 add_library(static3 STATIC static3.c)
10235 target_link_libraries(static3 PRIVATE iface_obj3)
10236 add_executable(use_static3 use_static3.c)
10238 target_link_libraries(use_static3 PRIVATE static3)
10239 compiles static3.c with -DOBJ3 and creates libstatic3.a using only its
10241 own object file. use_static3.c is compiled without -DOBJ3 because the
10242 usage requirement is not transitive through the private dependency of
10243 static3. However, the link dependencies of static3 are propagated, in‐
10244 cluding the iface_obj3 reference to $<TARGET_OBJECTS:obj3>. The
10245 use_static3 executable is created with object files from use_static3.c
10246 and obj3.c, and linked to library libstatic3.a.
10247 When using this approach, it is the project's responsibility to avoid
10249 linking multiple dependent binaries to iface_obj3, because they will
10250 all get the obj3 object files on their link lines.
10251 NOTE:
10253 Referencing $<TARGET_OBJECTS> in target_link_libraries calls worked
10254 in versions of CMake prior to 3.21 for some cases, but was not fully
10255 supported:
10256 • It did not place the object files before libraries on link lines.
10258 • It did not add an ordering dependency on the object library.
10260 • It did not work in Xcode with multiple architectures.
10262 Cyclic Dependencies of Static Libraries
10264 The library dependency graph is normally acyclic (a DAG), but in the
10265 case of mutually-dependent STATIC libraries CMake allows the graph to
10266 contain cycles (strongly connected components). When another target
10267 links to one of the libraries, CMake repeats the entire connected com‐
10268 ponent. For example, the code
10269 add_library(A STATIC a.c)
10271 add_library(B STATIC b.c)
10272 target_link_libraries(A B)
10273 target_link_libraries(B A)
10274 add_executable(main main.c)
10275 target_link_libraries(main A)
10276 links main to A B A B. While one repetition is usually sufficient,
10278 pathological object file and symbol arrangements can require more. One
10279 may handle such cases by using the LINK_INTERFACE_MULTIPLICITY target
10280 property or by manually repeating the component in the last tar‐
10281 get_link_libraries call. However, if two archives are really so inter‐
10282 dependent they should probably be combined into a single archive, per‐
10283 haps by using Object Libraries.
10284 Creating Relocatable Packages
10286 Note that it is not advisable to populate the INTERFACE_LINK_LIBRARIES
10287 of a target with absolute paths to dependencies. That would hard-code
10288 into installed packages the library file paths for dependencies as
10289 found on the machine the package was made on.
10290 See the Creating Relocatable Packages section of the cmake-packages(7)
10292 manual for discussion of additional care that must be taken when speci‐
10293 fying usage requirements while creating packages for redistribution.
10294 target_link_options
10296 New in version 3.13.
10297 Add options to the link step for an executable, shared library or mod‐
10300 ule library target.
10301 target_link_options(<target> [BEFORE]
10303 <INTERFACE|PUBLIC|PRIVATE> [items1...]
10304 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
10305 The named <target> must have been created by a command such as add_exe‐
10307 cutable() or add_library() and must not be an ALIAS target.
10308 This command can be used to add any link options, but alternative com‐
10310 mands exist to add libraries (target_link_libraries() or link_li‐
10311 braries()). See documentation of the directory and target LINK_OPTIONS
10312 properties.
10313 NOTE:
10315 This command cannot be used to add options for static library tar‐
10316 gets, since they do not use a linker. To add archiver or MSVC li‐
10317 brarian flags, see the STATIC_LIBRARY_OPTIONS target property.
10318 If BEFORE is specified, the content will be prepended to the property
10320 instead of being appended.
10321 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
10323 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
10324 late the LINK_OPTIONS property of <target>. PUBLIC and INTERFACE items
10325 will populate the INTERFACE_LINK_OPTIONS property of <target>. The
10326 following arguments specify link options. Repeated calls for the same
10327 <target> append items in the order called.
10328 NOTE:
10330 IMPORTED targets only support INTERFACE items.
10331 Arguments to target_link_options may use "generator expressions" with
10333 the syntax $<...>. See the cmake-generator-expressions(7) manual for
10334 available expressions. See the cmake-buildsystem(7) manual for more on
10335 defining buildsystem properties.
10336 Host And Device Specific Link Options
10338 New in version 3.18: When a device link step is involved, which is con‐
10339 trolled by CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS
10340 properties and policy CMP0105, the raw options will be delivered to the
10341 host and device link steps (wrapped in -Xcompiler or equivalent for de‐
10342 vice link). Options wrapped with $<DEVICE_LINK:...> generator expres‐
10343 sion will be used only for the device link step. Options wrapped with
10344 $<HOST_LINK:...> generator expression will be used only for the host
10345 link step.
10346 Option De-duplication
10349 The final set of options used for a target is constructed by accumulat‐
10350 ing options from the current target and the usage requirements of its
10351 dependencies. The set of options is de-duplicated to avoid repetition.
10352 New in version 3.12: While beneficial for individual options, the
10354 de-duplication step can break up option groups. For example, -option A
10355 -option B becomes -option A B. One may specify a group of options us‐
10356 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
10357 is dropped, and the rest of the option string is parsed using the sepa‐
10358 rate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
10359 "SHELL:-option B" becomes -option A -option B.
10360 Handling Compiler Driver Differences
10363 To pass options to the linker tool, each compiler driver has its own
10364 syntax. The LINKER: prefix and , separator can be used to specify, in
10365 a portable way, options to pass to the linker tool. LINKER: is replaced
10366 by the appropriate driver option and , by the appropriate driver sepa‐
10367 rator. The driver prefix and driver separator are given by the values
10368 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAP‐
10369 PER_FLAG_SEP variables.
10370 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
10372 Clang and -Wl,-z,defs for GNU GCC.
10373 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
10375 sion.
10376 The LINKER: prefix supports, as an alternative syntax, specification of
10378 arguments using the SHELL: prefix and space as separator. The previous
10379 example then becomes "LINKER:SHELL:-z defs".
10380 NOTE:
10382 Specifying the SHELL: prefix anywhere other than at the beginning of
10383 the LINKER: prefix is not supported.
10384 target_precompile_headers
10386 New in version 3.16.
10387 Add a list of header files to precompile.
10390 Precompiling header files can speed up compilation by creating a par‐
10392 tially processed version of some header files, and then using that ver‐
10393 sion during compilations rather than repeatedly parsing the original
10394 headers.
10395 Main Form
10397 target_precompile_headers(<target>
10398 <INTERFACE|PUBLIC|PRIVATE> [header1...]
10399 [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])
10400 The command adds header files to the PRECOMPILE_HEADERS and/or INTER‐
10402 FACE_PRECOMPILE_HEADERS target properties of <target>. The named <tar‐
10403 get> must have been created by a command such as add_executable() or
10404 add_library() and must not be an ALIAS target.
10405 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
10407 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
10408 late the PRECOMPILE_HEADERS property of <target>. PUBLIC and INTERFACE
10409 items will populate the INTERFACE_PRECOMPILE_HEADERS property of <tar‐
10410 get> (IMPORTED targets only support INTERFACE items). Repeated calls
10411 for the same <target> will append items in the order called.
10412 Projects should generally avoid using PUBLIC or INTERFACE for targets
10414 that will be exported, or they should at least use the $<BUILD_INTER‐
10415 FACE:...> generator expression to prevent precompile headers from ap‐
10416 pearing in an installed exported target. Consumers of a target should
10417 typically be in control of what precompile headers they use, not have
10418 precompile headers forced on them by the targets being consumed (since
10419 precompile headers are not typically usage requirements). A notable
10420 exception to this is where an interface library is created to define a
10421 commonly used set of precompile headers in one place and then other
10422 targets link to that interface library privately. In this case, the
10423 interface library exists specifically to propagate the precompile head‐
10424 ers to its consumers and the consumer is effectively still in control,
10425 since it decides whether to link to the interface library or not.
10426 The list of header files is used to generate a header file named
10428 cmake_pch.h|xx which is used to generate the precompiled header file
10429 (.pch, .gch, .pchi) artifact. The cmake_pch.h|xx header file will be
10430 force included (-include for GCC, /FI for MSVC) to all source files, so
10431 sources do not need to have #include "pch.h".
10432 Header file names specified with angle brackets (e.g. <unordered_map>)
10434 or explicit double quotes (escaped for the cmake-language(7), e.g.
10435 [["other_header.h"]]) will be treated as is, and include directories
10436 must be available for the compiler to find them. Other header file
10437 names (e.g. project_header.h) are interpreted as being relative to the
10438 current source directory (e.g. CMAKE_CURRENT_SOURCE_DIR) and will be
10439 included by absolute path. For example:
10440 target_precompile_headers(myTarget
10442 PUBLIC
10443 project_header.h
10444 PRIVATE
10445 [["other_header.h"]]
10446 <unordered_map>
10447 )
10448 Arguments to target_precompile_headers() may use "generator expres‐
10450 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
10451 manual for available expressions. The $<COMPILE_LANGUAGE:...> genera‐
10452 tor expression is particularly useful for specifying a language-spe‐
10453 cific header to precompile for only one language (e.g. CXX and not C).
10454 In this case, header file names that are not explicitly in double
10455 quotes or angle brackets must be specified by absolute path. Also,
10456 when specifying angle brackets inside a generator expression, be sure
10457 to encode the closing > as $<ANGLE-R>. For example:
10458 target_precompile_headers(mylib PRIVATE
10460 "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/cxx_only.h>"
10461 "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
10462 "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
10463 )
10464 Reusing Precompile Headers
10466 The command also supports a second signature which can be used to spec‐
10467 ify that one target re-uses a precompiled header file artifact from an‐
10468 other target instead of generating its own:
10469 target_precompile_headers(<target> REUSE_FROM <other_target>)
10471 This form sets the PRECOMPILE_HEADERS_REUSE_FROM property to
10473 <other_target> and adds a dependency such that <target> will depend on
10474 <other_target>. CMake will halt with an error if the PRECOMPILE_HEAD‐
10475 ERS property of <target> is already set when the REUSE_FROM form is
10476 used.
10477 NOTE:
10479 The REUSE_FROM form requires the same set of compiler options, com‐
10480 piler flags and compiler definitions for both <target> and
10481 <other_target>. Some compilers (e.g. GCC) may issue a warning if
10482 the precompiled header file cannot be used (-Winvalid-pch).
10483 See Also
10485 To disable precompile headers for specific targets, see the DIS‐
10486 ABLE_PRECOMPILE_HEADERS target property.
10487 To prevent precompile headers from being used when compiling a specific
10489 source file, see the SKIP_PRECOMPILE_HEADERS source file property.
10490 target_sources
10492 New in version 3.1.
10493 Add sources to a target.
10496 target_sources(<target>
10498 <INTERFACE|PUBLIC|PRIVATE> [items1...]
10499 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
10500 Specifies sources to use when building a target and/or its dependents.
10502 The named <target> must have been created by a command such as add_exe‐
10503 cutable() or add_library() or add_custom_target() and must not be an
10504 ALIAS target.
10505 Changed in version 3.13: Relative source file paths are interpreted as
10507 being relative to the current source directory (i.e. CMAKE_CUR‐
10508 RENT_SOURCE_DIR). See policy CMP0076.
10509 New in version 3.20: <target> can be a custom target.
10512 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
10515 scope of the items following them. PRIVATE and PUBLIC items will popu‐
10516 late the SOURCES property of <target>, which are used when building the
10517 target itself. PUBLIC and INTERFACE items will populate the INTER‐
10518 FACE_SOURCES property of <target>, which are used when building depen‐
10519 dents. The following arguments specify sources. Repeated calls for
10520 the same <target> append items in the order called. The targets created
10521 by add_custom_target() can only have PRIVATE scope.
10522 New in version 3.3: Allow exporting targets with INTERFACE_SOURCES.
10524 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
10527 Arguments to target_sources may use "generator expressions" with the
10530 syntax $<...>. See the cmake-generator-expressions(7) manual for avail‐
10531 able expressions. See the cmake-buildsystem(7) manual for more on
10532 defining buildsystem properties.
10533 try_compile
10535 Try building some code.
10536 Try Compiling Whole Projects
10538 try_compile(<resultVar> <bindir> <srcdir>
10539 <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
10540 [OUTPUT_VARIABLE <var>])
10541 Try building a project. The success or failure of the try_compile,
10543 i.e. TRUE or FALSE respectively, is returned in <resultVar>.
10544 New in version 3.14: The name of the <resultVar> is defined by the
10546 user. Previously, it had a fixed name RESULT_VAR.
10547 In this form, <srcdir> should contain a complete CMake project with a
10550 CMakeLists.txt file and all sources. The <bindir> and <srcdir> will
10551 not be deleted after this command is run. Specify <targetName> to
10552 build a specific target instead of the all or ALL_BUILD target. See
10553 below for the meaning of other options.
10554 Try Compiling Source Files
10556 try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
10557 [CMAKE_FLAGS <flags>...]
10558 [COMPILE_DEFINITIONS <defs>...]
10559 [LINK_OPTIONS <options>...]
10560 [LINK_LIBRARIES <libs>...]
10561 [OUTPUT_VARIABLE <var>]
10562 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
10563 [<LANG>_STANDARD <std>]
10564 [<LANG>_STANDARD_REQUIRED <bool>]
10565 [<LANG>_EXTENSIONS <bool>]
10566 )
10567 Try building an executable or static library from one or more source
10569 files (which one is determined by the CMAKE_TRY_COMPILE_TARGET_TYPE
10570 variable). The success or failure of the try_compile, i.e. TRUE or
10571 FALSE respectively, is returned in <resultVar>.
10572 New in version 3.14: The name of the <resultVar> is defined by the
10574 user. Previously, it had a fixed name RESULT_VAR.
10575 In this form, one or more source files must be provided. If
10578 CMAKE_TRY_COMPILE_TARGET_TYPE is unset or is set to EXECUTABLE, the
10579 sources must include a definition for main and CMake will create a
10580 CMakeLists.txt file to build the source(s) as an executable. If
10581 CMAKE_TRY_COMPILE_TARGET_TYPE is set to STATIC_LIBRARY, a static li‐
10582 brary will be built instead and no definition for main is required.
10583 For an executable, the generated CMakeLists.txt file would contain
10584 something like the following:
10585 add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
10587 include_directories(${INCLUDE_DIRECTORIES})
10588 link_directories(${LINK_DIRECTORIES})
10589 add_executable(cmTryCompileExec <srcfile>...)
10590 target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
10591 target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
10592 The options are:
10594 CMAKE_FLAGS <flags>...
10596 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
10597 cmake command-line used to drive the test build. The above ex‐
10598 ample shows how values for variables INCLUDE_DIRECTORIES,
10599 LINK_DIRECTORIES, and LINK_LIBRARIES are used.
10600 COMPILE_DEFINITIONS <defs>...
10602 Specify -Ddefinition arguments to pass to add_definitions() in
10603 the generated test project.
10604 COPY_FILE <fileName>
10606 Copy the built executable or static library to the given <file‐
10607 Name>.
10608 COPY_FILE_ERROR <var>
10610 Use after COPY_FILE to capture into variable <var> any error
10611 message encountered while trying to copy the file.
10612 LINK_LIBRARIES <libs>...
10614 Specify libraries to be linked in the generated project. The
10615 list of libraries may refer to system libraries and to Imported
10616 Targets from the calling project.
10617 If this option is specified, any -DLINK_LIBRARIES=... value
10619 given to the CMAKE_FLAGS option will be ignored.
10620 LINK_OPTIONS <options>...
10622 New in version 3.14.
10623 Specify link step options to pass to target_link_options() or to
10626 set the STATIC_LIBRARY_OPTIONS target property in the generated
10627 project, depending on the CMAKE_TRY_COMPILE_TARGET_TYPE vari‐
10628 able.
10629 OUTPUT_VARIABLE <var>
10631 Store the output from the build process in the given variable.
10632 <LANG>_STANDARD <std>
10634 New in version 3.8.
10635 Specify the C_STANDARD, CXX_STANDARD, OBJC_STANDARD, OB‐
10638 JCXX_STANDARD, or CUDA_STANDARD target property of the generated
10639 project.
10640 <LANG>_STANDARD_REQUIRED <bool>
10642 New in version 3.8.
10643 Specify the C_STANDARD_REQUIRED, CXX_STANDARD_REQUIRED,
10646 OBJC_STANDARD_REQUIRED, OBJCXX_STANDARD_REQUIRED,or CUDA_STAN‐
10647 DARD_REQUIRED target property of the generated project.
10648 <LANG>_EXTENSIONS <bool>
10650 New in version 3.8.
10651 Specify the C_EXTENSIONS, CXX_EXTENSIONS, OBJC_EXTENSIONS, OB‐
10654 JCXX_EXTENSIONS, or CUDA_EXTENSIONS target property of the gen‐
10655 erated project.
10656 In this version all files in <bindir>/CMakeFiles/CMakeTmp will be
10658 cleaned automatically. For debugging, --debug-trycompile can be passed
10659 to cmake to avoid this clean. However, multiple sequential try_compile
10660 operations reuse this single output directory. If you use --de‐
10661 bug-trycompile, you can only debug one try_compile call at a time. The
10662 recommended procedure is to protect all try_compile calls in your
10663 project by if(NOT DEFINED <resultVar>) logic, configure with cmake all
10664 the way through once, then delete the cache entry associated with the
10665 try_compile call of interest, and then re-run cmake again with --de‐
10666 bug-trycompile.
10667 Other Behavior Settings
10669 New in version 3.4: If set, the following variables are passed in to
10670 the generated try_compile CMakeLists.txt to initialize compile target
10671 properties with default values:
10672 • CMAKE_CUDA_RUNTIME_LIBRARY
10674 • CMAKE_ENABLE_EXPORTS
10676 • CMAKE_LINK_SEARCH_START_STATIC
10678 • CMAKE_LINK_SEARCH_END_STATIC
10680 • CMAKE_MSVC_RUNTIME_LIBRARY
10682 • CMAKE_POSITION_INDEPENDENT_CODE
10684 If CMP0056 is set to NEW, then CMAKE_EXE_LINKER_FLAGS is passed in as
10686 well.
10687 Changed in version 3.14: If CMP0083 is set to NEW, then in order to ob‐
10690 tain correct behavior at link time, the check_pie_supported() command
10691 from the CheckPIESupported module must be called before using the
10692 try_compile() command.
10693 The current settings of CMP0065 and CMP0083 are propagated through to
10696 the generated test project.
10697 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
10699 figuration.
10700 New in version 3.6: Set the CMAKE_TRY_COMPILE_TARGET_TYPE variable to
10702 specify the type of target used for the source file signature.
10703 New in version 3.6: Set the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES vari‐
10706 able to specify variables that must be propagated into the test
10707 project. This variable is meant for use only in toolchain files and is
10708 only honored by the try_compile() command for the source files form,
10709 not when given a whole project.
10710 Changed in version 3.8: If CMP0067 is set to NEW, or any of the
10713 <LANG>_STANDARD, <LANG>_STANDARD_REQUIRED, or <LANG>_EXTENSIONS options
10714 are used, then the language standard variables are honored:
10715 • CMAKE_C_STANDARD
10717 • CMAKE_C_STANDARD_REQUIRED
10719 • CMAKE_C_EXTENSIONS
10721 • CMAKE_CXX_STANDARD
10723 • CMAKE_CXX_STANDARD_REQUIRED
10725 • CMAKE_CXX_EXTENSIONS
10727 • CMAKE_OBJC_STANDARD
10729 • CMAKE_OBJC_STANDARD_REQUIRED
10731 • CMAKE_OBJC_EXTENSIONS
10733 • CMAKE_OBJCXX_STANDARD
10735 • CMAKE_OBJCXX_STANDARD_REQUIRED
10737 • CMAKE_OBJCXX_EXTENSIONS
10739 • CMAKE_CUDA_STANDARD
10741 • CMAKE_CUDA_STANDARD_REQUIRED
10743 • CMAKE_CUDA_EXTENSIONS
10745 Their values are used to set the corresponding target properties in the
10747 generated project (unless overridden by an explicit option).
10748 Changed in version 3.14: For the Green Hills MULTI generator the GHS
10751 toolset and target system customization cache variables are also propa‐
10752 gated into the test project.
10753 try_run
10756 Try compiling and then running some code.
10757 Try Compiling and Running Source Files
10759 try_run(<runResultVar> <compileResultVar>
10760 <bindir> <srcfile> [CMAKE_FLAGS <flags>...]
10761 [COMPILE_DEFINITIONS <defs>...]
10762 [LINK_OPTIONS <options>...]
10763 [LINK_LIBRARIES <libs>...]
10764 [COMPILE_OUTPUT_VARIABLE <var>]
10765 [RUN_OUTPUT_VARIABLE <var>]
10766 [OUTPUT_VARIABLE <var>]
10767 [WORKING_DIRECTORY <var>]
10768 [ARGS <args>...])
10769 Try compiling a <srcfile>. Returns TRUE or FALSE for success or fail‐
10771 ure in <compileResultVar>. If the compile succeeded, runs the exe‐
10772 cutable and returns its exit code in <runResultVar>. If the executable
10773 was built, but failed to run, then <runResultVar> will be set to
10774 FAILED_TO_RUN. See the try_compile() command for information on how
10775 the test project is constructed to build the source file.
10776 New in version 3.14: The names of the result variables <runResultVar>
10778 and <compileResultVar> are defined by the user. Previously, they had
10779 fixed names RUN_RESULT_VAR and COMPILE_RESULT_VAR.
10780 The options are:
10783 CMAKE_FLAGS <flags>...
10785 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
10786 cmake command-line used to drive the test build. The example in
10787 try_compile() shows how values for variables INCLUDE_DIRECTO‐
10788 RIES, LINK_DIRECTORIES, and LINK_LIBRARIES are used.
10789 COMPILE_DEFINITIONS <defs>...
10791 Specify -Ddefinition arguments to pass to add_definitions() in
10792 the generated test project.
10793 COMPILE_OUTPUT_VARIABLE <var>
10795 Report the compile step build output in a given variable.
10796 LINK_LIBRARIES <libs>...
10798 New in version 3.2.
10799 Specify libraries to be linked in the generated project. The
10802 list of libraries may refer to system libraries and to Imported
10803 Targets from the calling project.
10804 If this option is specified, any -DLINK_LIBRARIES=... value
10806 given to the CMAKE_FLAGS option will be ignored.
10807 LINK_OPTIONS <options>...
10809 New in version 3.14.
10810 Specify link step options to pass to target_link_options() in
10813 the generated project.
10814 OUTPUT_VARIABLE <var>
10816 Report the compile build output and the output from running the
10817 executable in the given variable. This option exists for legacy
10818 reasons. Prefer COMPILE_OUTPUT_VARIABLE and RUN_OUTPUT_VARIABLE
10819 instead.
10820 RUN_OUTPUT_VARIABLE <var>
10822 Report the output from running the executable in a given vari‐
10823 able.
10824 WORKING_DIRECTORY <var>
10826 New in version 3.20.
10827 Run the executable in the given directory. If no WORKING_DIREC‐
10830 TORY is specified, the executable will run in <bindir>.
10831 Other Behavior Settings
10833 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
10834 figuration.
10835 Behavior when Cross Compiling
10837 New in version 3.3: Use CMAKE_CROSSCOMPILING_EMULATOR when running
10838 cross-compiled binaries.
10839 When cross compiling, the executable compiled in the first step usually
10842 cannot be run on the build host. The try_run command checks the
10843 CMAKE_CROSSCOMPILING variable to detect whether CMake is in cross-com‐
10844 piling mode. If that is the case, it will still try to compile the ex‐
10845 ecutable, but it will not try to run the executable unless the
10846 CMAKE_CROSSCOMPILING_EMULATOR variable is set. Instead it will create
10847 cache variables which must be filled by the user or by presetting them
10848 in some CMake script file to the values the executable would have pro‐
10849 duced if it had been run on its actual target platform. These cache
10850 entries are:
10851 <runResultVar>
10853 Exit code if the executable were to be run on the target plat‐
10854 form.
10855 <runResultVar>__TRYRUN_OUTPUT
10857 Output from stdout and stderr if the executable were to be run
10858 on the target platform. This is created only if the RUN_OUT‐
10859 PUT_VARIABLE or OUTPUT_VARIABLE option was used.
10860 In order to make cross compiling your project easier, use try_run only
10862 if really required. If you use try_run, use the RUN_OUTPUT_VARIABLE or
10863 OUTPUT_VARIABLE options only if really required. Using them will re‐
10864 quire that when cross-compiling, the cache variables will have to be
10865 set manually to the output of the executable. You can also "guard" the
10866 calls to try_run with an if() block checking the CMAKE_CROSSCOMPILING
10867 variable and provide an easy-to-preset alternative for this case.
10868
10870 These commands are available only in CTest scripts.
10871 ctest_build
10873 Perform the CTest Build Step as a Dashboard Client.
10874 ctest_build([BUILD <build-dir>] [APPEND]
10876 [CONFIGURATION <config>]
10877 [PARALLEL_LEVEL <parallel>]
10878 [FLAGS <flags>]
10879 [PROJECT_NAME <project-name>]
10880 [TARGET <target-name>]
10881 [NUMBER_ERRORS <num-err-var>]
10882 [NUMBER_WARNINGS <num-warn-var>]
10883 [RETURN_VALUE <result-var>]
10884 [CAPTURE_CMAKE_ERROR <result-var>]
10885 )
10886 Build the project and store results in Build.xml for submission with
10888 the ctest_submit() command.
10889 The CTEST_BUILD_COMMAND variable may be set to explicitly specify the
10891 build command line. Otherwise the build command line is computed auto‐
10892 matically based on the options given.
10893 The options are:
10895 BUILD <build-dir>
10897 Specify the top-level build directory. If not given, the
10898 CTEST_BINARY_DIRECTORY variable is used.
10899 APPEND Mark Build.xml for append to results previously submitted to a
10901 dashboard server since the last ctest_start() call. Append se‐
10902 mantics are defined by the dashboard server in use. This does
10903 not cause results to be appended to a .xml file produced by a
10904 previous call to this command.
10905 CONFIGURATION <config>
10907 Specify the build configuration (e.g. Debug). If not specified
10908 the CTEST_BUILD_CONFIGURATION variable will be checked. Other‐
10909 wise the -C <cfg> option given to the ctest(1) command will be
10910 used, if any.
10911 PARALLEL_LEVEL <parallel>
10913 New in version 3.21.
10914 Specify the parallel level of the underlying build system. If
10917 not specified, the CMAKE_BUILD_PARALLEL_LEVEL environment vari‐
10918 able will be checked.
10919 FLAGS <flags>
10921 Pass additional arguments to the underlying build command. If
10922 not specified the CTEST_BUILD_FLAGS variable will be checked.
10923 This can, e.g., be used to trigger a parallel build using the -j
10924 option of make. See the ProcessorCount module for an example.
10925 PROJECT_NAME <project-name>
10927 Ignored since CMake 3.0.
10928 Changed in version 3.14: This value is no longer required.
10930 TARGET <target-name>
10933 Specify the name of a target to build. If not specified the
10934 CTEST_BUILD_TARGET variable will be checked. Otherwise the de‐
10935 fault target will be built. This is the "all" target (called
10936 ALL_BUILD in Visual Studio Generators).
10937 NUMBER_ERRORS <num-err-var>
10939 Store the number of build errors detected in the given variable.
10940 NUMBER_WARNINGS <num-warn-var>
10942 Store the number of build warnings detected in the given vari‐
10943 able.
10944 RETURN_VALUE <result-var>
10946 Store the return value of the native build tool in the given
10947 variable.
10948 CAPTURE_CMAKE_ERROR <result-var>
10950 New in version 3.7.
10951 Store in the <result-var> variable -1 if there are any errors
10954 running the command and prevent ctest from returning non-zero if
10955 an error occurs.
10956 QUIET New in version 3.3.
10958 Suppress any CTest-specific non-error output that would have
10961 been printed to the console otherwise. The summary of warnings
10962 / errors, as well as the output from the native build tool is
10963 unaffected by this option.
10964 ctest_configure
10966 Perform the CTest Configure Step as a Dashboard Client.
10967 ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
10969 [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
10970 [CAPTURE_CMAKE_ERROR <result-var>])
10971 Configure the project build tree and record results in Configure.xml
10973 for submission with the ctest_submit() command.
10974 The options are:
10976 BUILD <build-dir>
10978 Specify the top-level build directory. If not given, the
10979 CTEST_BINARY_DIRECTORY variable is used.
10980 SOURCE <source-dir>
10982 Specify the source directory. If not given, the
10983 CTEST_SOURCE_DIRECTORY variable is used.
10984 APPEND Mark Configure.xml for append to results previously submitted to
10986 a dashboard server since the last ctest_start() call. Append
10987 semantics are defined by the dashboard server in use. This does
10988 not cause results to be appended to a .xml file produced by a
10989 previous call to this command.
10990 OPTIONS <options>
10992 Specify command-line arguments to pass to the configuration
10993 tool.
10994 RETURN_VALUE <result-var>
10996 Store in the <result-var> variable the return value of the na‐
10997 tive configuration tool.
10998 CAPTURE_CMAKE_ERROR <result-var>
11000 New in version 3.7.
11001 Store in the <result-var> variable -1 if there are any errors
11004 running the command and prevent ctest from returning non-zero if
11005 an error occurs.
11006 QUIET New in version 3.3.
11008 Suppress any CTest-specific non-error messages that would have
11011 otherwise been printed to the console. Output from the underly‐
11012 ing configure command is not affected.
11013 ctest_coverage
11015 Perform the CTest Coverage Step as a Dashboard Client.
11016 ctest_coverage([BUILD <build-dir>] [APPEND]
11018 [LABELS <label>...]
11019 [RETURN_VALUE <result-var>]
11020 [CAPTURE_CMAKE_ERROR <result-var>]
11021 [QUIET]
11022 )
11023 Collect coverage tool results and stores them in Coverage.xml for sub‐
11025 mission with the ctest_submit() command.
11026 The options are:
11028 BUILD <build-dir>
11030 Specify the top-level build directory. If not given, the
11031 CTEST_BINARY_DIRECTORY variable is used.
11032 APPEND Mark Coverage.xml for append to results previously submitted to
11034 a dashboard server since the last ctest_start() call. Append
11035 semantics are defined by the dashboard server in use. This does
11036 not cause results to be appended to a .xml file produced by a
11037 previous call to this command.
11038 LABELS Filter the coverage report to include only source files labeled
11040 with at least one of the labels specified.
11041 RETURN_VALUE <result-var>
11043 Store in the <result-var> variable 0 if coverage tools ran with‐
11044 out error and non-zero otherwise.
11045 CAPTURE_CMAKE_ERROR <result-var>
11047 New in version 3.7.
11048 Store in the <result-var> variable -1 if there are any errors
11051 running the command and prevent ctest from returning non-zero if
11052 an error occurs.
11053 QUIET New in version 3.3.
11055 Suppress any CTest-specific non-error output that would have
11058 been printed to the console otherwise. The summary indicating
11059 how many lines of code were covered is unaffected by this op‐
11060 tion.
11061 ctest_empty_binary_directory
11063 empties the binary directory
11064 ctest_empty_binary_directory( directory )
11066 Removes a binary directory. This command will perform some checks
11068 prior to deleting the directory in an attempt to avoid malicious or ac‐
11069 cidental directory deletion.
11070 ctest_memcheck
11072 Perform the CTest MemCheck Step as a Dashboard Client.
11073 ctest_memcheck([BUILD <build-dir>] [APPEND]
11075 [START <start-number>]
11076 [END <end-number>]
11077 [STRIDE <stride-number>]
11078 [EXCLUDE <exclude-regex>]
11079 [INCLUDE <include-regex>]
11080 [EXCLUDE_LABEL <label-exclude-regex>]
11081 [INCLUDE_LABEL <label-include-regex>]
11082 [EXCLUDE_FIXTURE <regex>]
11083 [EXCLUDE_FIXTURE_SETUP <regex>]
11084 [EXCLUDE_FIXTURE_CLEANUP <regex>]
11085 [PARALLEL_LEVEL <level>]
11086 [RESOURCE_SPEC_FILE <file>]
11087 [TEST_LOAD <threshold>]
11088 [SCHEDULE_RANDOM <ON|OFF>]
11089 [STOP_ON_FAILURE]
11090 [STOP_TIME <time-of-day>]
11091 [RETURN_VALUE <result-var>]
11092 [CAPTURE_CMAKE_ERROR <result-var>]
11093 [REPEAT <mode>:<n>]
11094 [OUTPUT_JUNIT <file>]
11095 [DEFECT_COUNT <defect-count-var>]
11096 [QUIET]
11097 )
11098 Run tests with a dynamic analysis tool and store results in Mem‐
11100 Check.xml for submission with the ctest_submit() command.
11101 Most options are the same as those for the ctest_test() command.
11103 The options unique to this command are:
11105 DEFECT_COUNT <defect-count-var>
11107 New in version 3.8.
11108 Store in the <defect-count-var> the number of defects found.
11111 ctest_read_custom_files
11113 read CTestCustom files.
11114 ctest_read_custom_files( directory ... )
11116 Read all the CTestCustom.ctest or CTestCustom.cmake files from the
11118 given directory.
11119 By default, invoking ctest(1) without a script will read custom files
11121 from the binary directory.
11122 ctest_run_script
11124 runs a ctest -S script
11125 ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
11127 script_file_name2 ... [RETURN_VALUE var])
11128 Runs a script or scripts much like if it was run from ctest -S. If no
11130 argument is provided then the current script is run using the current
11131 settings of the variables. If NEW_PROCESS is specified then each
11132 script will be run in a separate process.If RETURN_VALUE is specified
11133 the return value of the last script run will be put into var.
11134 ctest_sleep
11136 sleeps for some amount of time
11137 ctest_sleep(<seconds>)
11139 Sleep for given number of seconds.
11141 ctest_sleep(<time1> <duration> <time2>)
11143 Sleep for t=(time1 + duration - time2) seconds if t > 0.
11145 ctest_start
11147 Starts the testing for a given model
11148 ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])
11150 ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET])
11152 Starts the testing for a given model. The command should be called af‐
11154 ter the binary directory is initialized.
11155 The parameters are as follows:
11157 <model>
11159 Set the dashboard model. Must be one of Experimental, Continu‐
11160 ous, or Nightly. This parameter is required unless APPEND is
11161 specified.
11162 <source>
11164 Set the source directory. If not specified, the value of
11165 CTEST_SOURCE_DIRECTORY is used instead.
11166 <binary>
11168 Set the binary directory. If not specified, the value of
11169 CTEST_BINARY_DIRECTORY is used instead.
11170 GROUP <group>
11172 If GROUP is used, the submissions will go to the specified group
11173 on the CDash server. If no GROUP is specified, the name of the
11174 model is used by default.
11175 Changed in version 3.16: This replaces the deprecated option
11177 TRACK. Despite the name change its behavior is unchanged.
11178 APPEND If APPEND is used, the existing TAG is used rather than creating
11181 a new one based on the current time stamp. If you use APPEND,
11182 you can omit the <model> and GROUP <group> parameters, because
11183 they will be read from the generated TAG file. For example:
11184 ctest_start(Experimental GROUP GroupExperimental)
11186 Later, in another ctest -S script:
11188 ctest_start(APPEND)
11190 When the second script runs ctest_start(APPEND), it will read
11192 the Experimental model and GroupExperimental group from the TAG
11193 file generated by the first ctest_start() command. Please note
11194 that if you call ctest_start(APPEND) and specify a different
11195 model or group than in the first ctest_start() command, a warn‐
11196 ing will be issued, and the new model and group will be used.
11197 QUIET New in version 3.3.
11199 If QUIET is used, CTest will suppress any non-error messages
11202 that it otherwise would have printed to the console.
11203 The parameters for ctest_start() can be issued in any order, with the
11205 exception that <model>, <source>, and <binary> have to appear in that
11206 order with respect to each other. The following are all valid and
11207 equivalent:
11208 ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND)
11210 ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary)
11212 ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary)
11214 However, for the sake of readability, it is recommended that you order
11216 your parameters in the order listed at the top of this page.
11217 If the CTEST_CHECKOUT_COMMAND variable (or the CTEST_CVS_CHECKOUT vari‐
11219 able) is set, its content is treated as command-line. The command is
11220 invoked with the current working directory set to the parent of the
11221 source directory, even if the source directory already exists. This
11222 can be used to create the source tree from a version control reposi‐
11223 tory.
11224 ctest_submit
11226 Perform the CTest Submit Step as a Dashboard Client.
11227 ctest_submit([PARTS <part>...] [FILES <file>...]
11229 [SUBMIT_URL <url>]
11230 [BUILD_ID <result-var>]
11231 [HTTPHEADER <header>]
11232 [RETRY_COUNT <count>]
11233 [RETRY_DELAY <delay>]
11234 [RETURN_VALUE <result-var>]
11235 [CAPTURE_CMAKE_ERROR <result-var>]
11236 [QUIET]
11237 )
11238 Submit results to a dashboard server. By default all available parts
11240 are submitted.
11241 The options are:
11243 PARTS <part>...
11245 Specify a subset of parts to submit. Valid part names are:
11246 Start = nothing
11248 Update = ctest_update results, in Update.xml
11249 Configure = ctest_configure results, in Configure.xml
11250 Build = ctest_build results, in Build.xml
11251 Test = ctest_test results, in Test.xml
11252 Coverage = ctest_coverage results, in Coverage.xml
11253 MemCheck = ctest_memcheck results, in DynamicAnalysis.xml and
11254 DynamicAnalysis-Test.xml
11255 Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
11256 ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
11257 Upload = Files prepared for upload by ctest_upload(), in Upload.xml
11258 Submit = nothing
11259 Done = Build is complete, in Done.xml
11260 FILES <file>...
11262 Specify an explicit list of specific files to be submitted.
11263 Each individual file must exist at the time of the call.
11264 SUBMIT_URL <url>
11266 New in version 3.14.
11267 The http or https URL of the dashboard server to send the sub‐
11270 mission to. If not given, the CTEST_SUBMIT_URL variable is
11271 used.
11272 BUILD_ID <result-var>
11274 New in version 3.15.
11275 Store in the <result-var> variable the ID assigned to this build
11278 by CDash.
11279 HTTPHEADER <HTTP-header>
11281 New in version 3.9.
11282 Specify HTTP header to be included in the request to CDash dur‐
11285 ing submission. For example, CDash can be configured to only
11286 accept submissions from authenticated clients. In this case, you
11287 should provide a bearer token in your header:
11288 ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>")
11290 This suboption can be repeated several times for multiple head‐
11292 ers.
11293 RETRY_COUNT <count>
11295 Specify how many times to retry a timed-out submission.
11296 RETRY_DELAY <delay>
11298 Specify how long (in seconds) to wait after a timed-out submis‐
11299 sion before attempting to re-submit.
11300 RETURN_VALUE <result-var>
11302 Store in the <result-var> variable 0 for success and non-zero on
11303 failure.
11304 CAPTURE_CMAKE_ERROR <result-var>
11306 New in version 3.13.
11307 Store in the <result-var> variable -1 if there are any errors
11310 running the command and prevent ctest from returning non-zero if
11311 an error occurs.
11312 QUIET New in version 3.3.
11314 Suppress all non-error messages that would have otherwise been
11317 printed to the console.
11318 Submit to CDash Upload API
11320 New in version 3.2.
11321 ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
11324 [SUBMIT_URL <url>]
11325 [BUILD_ID <result-var>]
11326 [HTTPHEADER <header>]
11327 [RETRY_COUNT <count>]
11328 [RETRY_DELAY <delay>]
11329 [RETURN_VALUE <result-var>]
11330 [QUIET])
11331 This second signature is used to upload files to CDash via the CDash
11333 file upload API. The API first sends a request to upload to CDash along
11334 with a content hash of the file. If CDash does not already have the
11335 file, then it is uploaded. Along with the file, a CDash type string is
11336 specified to tell CDash which handler to use to process the data.
11337 This signature interprets options in the same way as the first one.
11339 New in version 3.8: Added the RETRY_COUNT, RETRY_DELAY, QUIET options.
11341 New in version 3.9: Added the HTTPHEADER option.
11344 New in version 3.13: Added the RETURN_VALUE option.
11347 New in version 3.14: Added the SUBMIT_URL option.
11350 New in version 3.15: Added the BUILD_ID option.
11353 ctest_test
11356 Perform the CTest Test Step as a Dashboard Client.
11357 ctest_test([BUILD <build-dir>] [APPEND]
11359 [START <start-number>]
11360 [END <end-number>]
11361 [STRIDE <stride-number>]
11362 [EXCLUDE <exclude-regex>]
11363 [INCLUDE <include-regex>]
11364 [EXCLUDE_LABEL <label-exclude-regex>]
11365 [INCLUDE_LABEL <label-include-regex>]
11366 [EXCLUDE_FIXTURE <regex>]
11367 [EXCLUDE_FIXTURE_SETUP <regex>]
11368 [EXCLUDE_FIXTURE_CLEANUP <regex>]
11369 [PARALLEL_LEVEL <level>]
11370 [RESOURCE_SPEC_FILE <file>]
11371 [TEST_LOAD <threshold>]
11372 [SCHEDULE_RANDOM <ON|OFF>]
11373 [STOP_ON_FAILURE]
11374 [STOP_TIME <time-of-day>]
11375 [RETURN_VALUE <result-var>]
11376 [CAPTURE_CMAKE_ERROR <result-var>]
11377 [REPEAT <mode>:<n>]
11378 [OUTPUT_JUNIT <file>]
11379 [QUIET]
11380 )
11381 Run tests in the project build tree and store results in Test.xml for
11383 submission with the ctest_submit() command.
11384 The options are:
11386 BUILD <build-dir>
11388 Specify the top-level build directory. If not given, the
11389 CTEST_BINARY_DIRECTORY variable is used.
11390 APPEND Mark Test.xml for append to results previously submitted to a
11392 dashboard server since the last ctest_start() call. Append se‐
11393 mantics are defined by the dashboard server in use. This does
11394 not cause results to be appended to a .xml file produced by a
11395 previous call to this command.
11396 START <start-number>
11398 Specify the beginning of a range of test numbers.
11399 END <end-number>
11401 Specify the end of a range of test numbers.
11402 STRIDE <stride-number>
11404 Specify the stride by which to step across a range of test num‐
11405 bers.
11406 EXCLUDE <exclude-regex>
11408 Specify a regular expression matching test names to exclude.
11409 INCLUDE <include-regex>
11411 Specify a regular expression matching test names to include.
11412 Tests not matching this expression are excluded.
11413 EXCLUDE_LABEL <label-exclude-regex>
11415 Specify a regular expression matching test labels to exclude.
11416 INCLUDE_LABEL <label-include-regex>
11418 Specify a regular expression matching test labels to include.
11419 Tests not matching this expression are excluded.
11420 EXCLUDE_FIXTURE <regex>
11422 New in version 3.7.
11423 If a test in the set of tests to be executed requires a particu‐
11426 lar fixture, that fixture's setup and cleanup tests would nor‐
11427 mally be added to the test set automatically. This option pre‐
11428 vents adding setup or cleanup tests for fixtures matching the
11429 <regex>. Note that all other fixture behavior is retained, in‐
11430 cluding test dependencies and skipping tests that have fixture
11431 setup tests that fail.
11432 EXCLUDE_FIXTURE_SETUP <regex>
11434 New in version 3.7.
11435 Same as EXCLUDE_FIXTURE except only matching setup tests are ex‐
11438 cluded.
11439 EXCLUDE_FIXTURE_CLEANUP <regex>
11441 New in version 3.7.
11442 Same as EXCLUDE_FIXTURE except only matching cleanup tests are
11445 excluded.
11446 PARALLEL_LEVEL <level>
11448 Specify a positive number representing the number of tests to be
11449 run in parallel.
11450 RESOURCE_SPEC_FILE <file>
11452 New in version 3.16.
11453 Specify a resource specification file. See ctest-resource-allo‐
11456 cation for more information.
11457 TEST_LOAD <threshold>
11459 New in version 3.4.
11460 While running tests in parallel, try not to start tests when
11463 they may cause the CPU load to pass above a given threshold. If
11464 not specified the CTEST_TEST_LOAD variable will be checked, and
11465 then the --test-load command-line argument to ctest(1). See
11466 also the TestLoad setting in the CTest Test Step.
11467 REPEAT <mode>:<n>
11469 New in version 3.17.
11470 Run tests repeatedly based on the given <mode> up to <n> times.
11473 The modes are:
11474 UNTIL_FAIL
11476 Require each test to run <n> times without failing in or‐
11477 der to pass. This is useful in finding sporadic failures
11478 in test cases.
11479 UNTIL_PASS
11481 Allow each test to run up to <n> times in order to pass.
11482 Repeats tests if they fail for any reason. This is use‐
11483 ful in tolerating sporadic failures in test cases.
11484 AFTER_TIMEOUT
11486 Allow each test to run up to <n> times in order to pass.
11487 Repeats tests only if they timeout. This is useful in
11488 tolerating sporadic timeouts in test cases on busy ma‐
11489 chines.
11490 SCHEDULE_RANDOM <ON|OFF>
11492 Launch tests in a random order. This may be useful for detect‐
11493 ing implicit test dependencies.
11494 STOP_ON_FAILURE
11496 New in version 3.18.
11497 Stop the execution of the tests once one has failed.
11500 STOP_TIME <time-of-day>
11502 Specify a time of day at which the tests should all stop run‐
11503 ning.
11504 RETURN_VALUE <result-var>
11506 Store in the <result-var> variable 0 if all tests passed. Store
11507 non-zero if anything went wrong.
11508 CAPTURE_CMAKE_ERROR <result-var>
11510 New in version 3.7.
11511 Store in the <result-var> variable -1 if there are any errors
11514 running the command and prevent ctest from returning non-zero if
11515 an error occurs.
11516 OUTPUT_JUNIT <file>
11518 New in version 3.21.
11519 Write test results to <file> in JUnit XML format. If <file> is a
11522 relative path, it will be placed in the build directory. If
11523 <file> already exists, it will be overwritten. Note that the re‐
11524 sulting JUnit XML file is not uploaded to CDash because it would
11525 be redundant with CTest's Test.xml file.
11526 QUIET New in version 3.3.
11528 Suppress any CTest-specific non-error messages that would have
11531 otherwise been printed to the console. Output from the underly‐
11532 ing test command is not affected. Summary info detailing the
11533 percentage of passing tests is also unaffected by the QUIET op‐
11534 tion.
11535 See also the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE and
11537 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables.
11538 Additional Test Measurements
11540 CTest can parse the output of your tests for extra measurements to re‐
11541 port to CDash.
11542 When run as a Dashboard Client, CTest will include these custom mea‐
11544 surements in the Test.xml file that gets uploaded to CDash.
11545 Check the CDash test measurement documentation for more information on
11547 the types of test measurements that CDash recognizes.
11548 The following example demonstrates how to output a variety of custom
11550 test measurements.
11551 std::cout <<
11553 "<CTestMeasurement type=\"numeric/double\" name=\"score\">28.3</CTestMeasurement>"
11554 << std::endl;
11555 std::cout <<
11557 "<CTestMeasurement type=\"text/string\" name=\"color\">red</CTestMeasurement>"
11558 << std::endl;
11559 std::cout <<
11561 "<CTestMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.org</CTestMeasurement>"
11562 << std::endl;
11563 std::cout <<
11565 "<CTestMeasurement type=\"text/preformatted\" name=\"Console Output\">" <<
11566 "line 1.\n" <<
11567 " \033[31;1m line 2. Bold red, and indented!\033[0;0ml\n" <<
11568 "line 3. Not bold or indented...\n" <<
11569 "</CTestMeasurement>" << std::endl;
11570 Image Measurements
11572 The following example demonstrates how to upload test images to CDash.
11573 std::cout <<
11575 "<CTestMeasurementFile type=\"image/jpg\" name=\"TestImage\">" <<
11576 "/dir/to/test_img.jpg</CTestMeasurementFile>" << std::endl;
11577 std::cout <<
11579 "<CTestMeasurementFile type=\"image/gif\" name=\"ValidImage\">" <<
11580 "/dir/to/valid_img.gif</CTestMeasurementFile>" << std::endl;
11581 std::cout <<
11583 "<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\"> <<
11584 "/dir/to/img.png</CTestMeasurementFile>"
11585 << std::endl;
11586 Images will be displayed together in an interactive comparison mode on
11588 CDash if they are provided with two or more of the following names.
11589 • TestImage
11591 • ValidImage
11593 • BaselineImage
11595 • DifferenceImage2
11597 By convention, TestImage is the image generated by your test, and Va‐
11599 lidImage (or BaselineImage) is basis of comparison used to determine if
11600 the test passed or failed.
11601 If another image name is used it will be displayed by CDash as a static
11603 image separate from the interactive comparison UI.
11604 Attached Files
11606 New in version 3.21.
11607 The following example demonstrates how to upload non-image files to
11610 CDash.
11611 std::cout <<
11613 "<CTestMeasurementFile type=\"file\" name=\"TestInputData1\">" <<
11614 "/dir/to/data1.csv</CTestMeasurementFile>\n" <<
11615 "<CTestMeasurementFile type=\"file\" name=\"TestInputData2\">" <<
11616 "/dir/to/data2.csv</CTestMeasurementFile>" << std::endl;
11617 If the name of the file to upload is known at configure time, you can
11619 use the ATTACHED_FILES or ATTACHED_FILES_ON_FAIL test properties in‐
11620 stead.
11621 Custom Details
11623 New in version 3.21.
11624 The following example demonstrates how to specify a custom value for
11627 the Test Details field displayed on CDash.
11628 std::cout <<
11630 "<CTestDetails>My Custom Details Value</CTestDetails>" << std::endl;
11631 Additional Labels
11633 New in version 3.22.
11634 The following example demonstrates how to add additional labels to a
11637 test at runtime.
11638 std::cout <<
11640 "<CTestLabel>Custom Label 1</CTestLabel>\n" <<
11641 "<CTestLabel>Custom Label 2</CTestLabel>" << std::endl;
11642 Use the LABELS test property instead for labels that can be determined
11644 at configure time.
11645 ctest_update
11647 Perform the CTest Update Step as a Dashboard Client.
11648 ctest_update([SOURCE <source-dir>]
11650 [RETURN_VALUE <result-var>]
11651 [CAPTURE_CMAKE_ERROR <result-var>]
11652 [QUIET])
11653 Update the source tree from version control and record results in Up‐
11655 date.xml for submission with the ctest_submit() command.
11656 The options are:
11658 SOURCE <source-dir>
11660 Specify the source directory. If not given, the
11661 CTEST_SOURCE_DIRECTORY variable is used.
11662 RETURN_VALUE <result-var>
11664 Store in the <result-var> variable the number of files updated
11665 or -1 on error.
11666 CAPTURE_CMAKE_ERROR <result-var>
11668 New in version 3.13.
11669 Store in the <result-var> variable -1 if there are any errors
11672 running the command and prevent ctest from returning non-zero if
11673 an error occurs.
11674 QUIET New in version 3.3.
11676 Tell CTest to suppress most non-error messages that it would
11679 have otherwise printed to the console. CTest will still report
11680 the new revision of the repository and any conflicting files
11681 that were found.
11682 The update always follows the version control branch currently checked
11684 out in the source directory. See the CTest Update Step documentation
11685 for information about variables that change the behavior of ctest_up‐
11686 date().
11687 ctest_upload
11689 Upload files to a dashboard server as a Dashboard Client.
11690 ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
11692 The options are:
11694 FILES <file>...
11696 Specify a list of files to be sent along with the build results
11697 to the dashboard server.
11698 QUIET New in version 3.3.
11700 Suppress any CTest-specific non-error output that would have
11703 been printed to the console otherwise.
11704 CAPTURE_CMAKE_ERROR <result-var>
11706 New in version 3.7.
11707 Store in the <result-var> variable -1 if there are any errors
11710 running the command and prevent ctest from returning non-zero if
11711 an error occurs.
11712
11714 These commands are deprecated and are only made available to maintain
11715 backward compatibility. The documentation of each command states the
11716 CMake version in which it was deprecated. Do not use these commands in
11717 new code.
11718 build_name
11720 Disallowed since version 3.0. See CMake Policy CMP0036.
11721 Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.
11723 build_name(variable)
11725 Sets the specified variable to a string representing the platform and
11727 compiler settings. These values are now available through the
11728 CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
11729 exec_program
11731 Deprecated since version 3.0: Use the execute_process() command in‐
11732 stead.
11733 Run an executable program during the processing of the CMakeList.txt
11736 file.
11737 exec_program(Executable [directory in which to run]
11739 [ARGS <arguments to executable>]
11740 [OUTPUT_VARIABLE <var>]
11741 [RETURN_VALUE <var>])
11742 The executable is run in the optionally specified directory. The exe‐
11744 cutable can include arguments if it is double quoted, but it is better
11745 to use the optional ARGS argument to specify arguments to the program.
11746 This is because cmake will then be able to escape spaces in the exe‐
11747 cutable path. An optional argument OUTPUT_VARIABLE specifies a vari‐
11748 able in which to store the output. To capture the return value of the
11749 execution, provide a RETURN_VALUE. If OUTPUT_VARIABLE is specified,
11750 then no output will go to the stdout/stderr of the console running
11751 cmake.
11752 export_library_dependencies
11754 Disallowed since version 3.0. See CMake Policy CMP0033.
11755 Use install(EXPORT) or export() command.
11757 This command generates an old-style library dependencies file.
11759 Projects requiring CMake 2.6 or later should not use the command. Use
11760 instead the install(EXPORT) command to help export targets from an in‐
11761 stallation tree and the export() command to export targets from a build
11762 tree.
11763 The old-style library dependencies file does not take into account
11765 per-configuration names of libraries or the LINK_INTERFACE_LIBRARIES
11766 target property.
11767 export_library_dependencies(<file> [APPEND])
11769 Create a file named <file> that can be included into a CMake listfile
11771 with the INCLUDE command. The file will contain a number of SET com‐
11772 mands that will set all the variables needed for library dependency in‐
11773 formation. This should be the last command in the top level CMake‐
11774 Lists.txt file of the project. If the APPEND option is specified, the
11775 SET commands will be appended to the given file instead of replacing
11776 it.
11777 install_files
11779 Deprecated since version 3.0: Use the install(FILES) command instead.
11780 This command has been superseded by the install() command. It is pro‐
11783 vided for compatibility with older CMake code. The FILES form is di‐
11784 rectly replaced by the FILES form of the install() command. The regexp
11785 form can be expressed more clearly using the GLOB form of the file()
11786 command.
11787 install_files(<dir> extension file file ...)
11789 Create rules to install the listed files with the given extension into
11791 the given directory. Only files existing in the current source tree or
11792 its corresponding location in the binary tree may be listed. If a file
11793 specified already has an extension, that extension will be removed
11794 first. This is useful for providing lists of source files such as
11795 foo.cxx when you want the corresponding foo.h to be installed. A typi‐
11796 cal extension is .h.
11797 install_files(<dir> regexp)
11799 Any files in the current source directory that match the regular ex‐
11801 pression will be installed.
11802 install_files(<dir> FILES file file ...)
11804 Any files listed after the FILES keyword will be installed explicitly
11806 from the names given. Full paths are allowed in this form.
11807 The directory <dir> is relative to the installation prefix, which is
11809 stored in the variable CMAKE_INSTALL_PREFIX.
11810 install_programs
11812 Deprecated since version 3.0: Use the install(PROGRAMS) command in‐
11813 stead.
11814 This command has been superseded by the install() command. It is pro‐
11817 vided for compatibility with older CMake code. The FILES form is di‐
11818 rectly replaced by the PROGRAMS form of the install() command. The
11819 regexp form can be expressed more clearly using the GLOB form of the
11820 file() command.
11821 install_programs(<dir> file1 file2 [file3 ...])
11823 install_programs(<dir> FILES file1 [file2 ...])
11824 Create rules to install the listed programs into the given directory.
11826 Use the FILES argument to guarantee that the file list version of the
11827 command will be used even when there is only one argument.
11828 install_programs(<dir> regexp)
11830 In the second form any program in the current source directory that
11832 matches the regular expression will be installed.
11833 This command is intended to install programs that are not built by
11835 cmake, such as shell scripts. See the TARGETS form of the install()
11836 command to create installation rules for targets built by cmake.
11837 The directory <dir> is relative to the installation prefix, which is
11839 stored in the variable CMAKE_INSTALL_PREFIX.
11840 install_targets
11842 Deprecated since version 3.0: Use the install(TARGETS) command instead.
11843 This command has been superseded by the install() command. It is pro‐
11846 vided for compatibility with older CMake code.
11847 install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
11849 Create rules to install the listed targets into the given directory.
11851 The directory <dir> is relative to the installation prefix, which is
11852 stored in the variable CMAKE_INSTALL_PREFIX. If RUNTIME_DIRECTORY is
11853 specified, then on systems with special runtime files (Windows DLL),
11854 the files will be copied to that directory.
11855 load_command
11857 Disallowed since version 3.0. See CMake Policy CMP0031.
11858 Load a command into a running CMake.
11860 load_command(COMMAND_NAME <loc1> [loc2 ...])
11862 The given locations are searched for a library whose name is cmCOM‐
11864 MAND_NAME. If found, it is loaded as a module and the command is added
11865 to the set of available CMake commands. Usually, try_compile() is used
11866 before this command to compile the module. If the command is success‐
11867 fully loaded a variable named
11868 CMAKE_LOADED_COMMAND_<COMMAND_NAME>
11870 will be set to the full path of the module that was loaded. Otherwise
11872 the variable will not be set.
11873 make_directory
11875 Deprecated since version 3.0: Use the file(MAKE_DIRECTORY) command in‐
11876 stead.
11877 make_directory(directory)
11880 Creates the specified directory. Full paths should be given. Any par‐
11882 ent directories that do not exist will also be created. Use with care.
11883 output_required_files
11885 Disallowed since version 3.0. See CMake Policy CMP0032.
11886 Approximate C preprocessor dependency scanning.
11888 This command exists only because ancient CMake versions provided it.
11890 CMake handles preprocessor dependency scanning automatically using a
11891 more advanced scanner.
11892 output_required_files(srcfile outputfile)
11894 Outputs a list of all the source files that are required by the speci‐
11896 fied srcfile. This list is written into outputfile. This is similar
11897 to writing out the dependencies for srcfile except that it jumps from
11898 .h files into .cxx, .c and .cpp files if possible.
11899 qt_wrap_cpp
11901 Deprecated since version 3.14: This command was originally added to
11902 support Qt 3 before the add_custom_command() command was sufficiently
11903 mature. The FindQt4 module provides the qt4_wrap_cpp() macro, which
11904 should be used instead for Qt 4 projects. For projects using Qt 5 or
11905 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
11906 vides qt5_wrap_cpp()).
11907 Manually create Qt Wrappers.
11910 qt_wrap_cpp(resultingLibraryName DestName SourceLists ...)
11912 Produces moc files for all the .h files listed in the SourceLists. The
11914 moc files will be added to the library using the DestName source list.
11915 Consider updating the project to use the AUTOMOC target property in‐
11917 stead for a more automated way of invoking the moc tool.
11918 qt_wrap_ui
11920 Deprecated since version 3.14: This command was originally added to
11921 support Qt 3 before the add_custom_command() command was sufficiently
11922 mature. The FindQt4 module provides the qt4_wrap_ui() macro, which
11923 should be used instead for Qt 4 projects. For projects using Qt 5 or
11924 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
11925 vides qt5_wrap_ui()).
11926 Manually create Qt user interfaces Wrappers.
11929 qt_wrap_ui(resultingLibraryName HeadersDestName
11931 SourcesDestName SourceLists ...)
11932 Produces .h and .cxx files for all the .ui files listed in the
11934 SourceLists. The .h files will be added to the library using the Head‐
11935 ersDestNamesource list. The .cxx files will be added to the library
11936 using the SourcesDestNamesource list.
11937 Consider updating the project to use the AUTOUIC target property in‐
11939 stead for a more automated way of invoking the uic tool.
11940 remove
11942 Deprecated since version 3.0: Use the list(REMOVE_ITEM) command in‐
11943 stead.
11944 remove(VAR VALUE VALUE ...)
11947 Removes VALUE from the variable VAR. This is typically used to remove
11949 entries from a vector (e.g. semicolon separated list). VALUE is ex‐
11950 panded.
11951 subdir_depends
11953 Disallowed since version 3.0. See CMake Policy CMP0029.
11954 Does nothing.
11956 subdir_depends(subdir dep1 dep2 ...)
11958 Does not do anything. This command used to help projects order paral‐
11960 lel builds correctly. This functionality is now automatic.
11961 subdirs
11963 Deprecated since version 3.0: Use the add_subdirectory() command in‐
11964 stead.
11965 Add a list of subdirectories to the build.
11968 subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
11970 [PREORDER] )
11971 Add a list of subdirectories to the build. The add_subdirectory() com‐
11973 mand should be used instead of subdirs although subdirs will still
11974 work. This will cause any CMakeLists.txt files in the sub directories
11975 to be processed by CMake. Any directories after the PREORDER flag are
11976 traversed first by makefile builds, the PREORDER flag has no effect on
11977 IDE projects. Any directories after the EXCLUDE_FROM_ALL marker will
11978 not be included in the top level makefile or project file. This is
11979 useful for having CMake create makefiles or projects for a set of exam‐
11980 ples in a project. You would want CMake to generate makefiles or
11981 project files for all the examples at the same time, but you would not
11982 want them to show up in the top level project or be built each time
11983 make is run from the top.
11984 use_mangled_mesa
11986 Disallowed since version 3.0. See CMake Policy CMP0030.
11987 Copy mesa headers for use in combination with system GL.
11989 use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
11991 The path to mesa includes, should contain gl_mangle.h. The mesa head‐
11993 ers are copied to the specified output directory. This allows mangled
11994 mesa headers to override other GL headers by being added to the include
11995 directory path earlier.
11996 utility_source
11998 Disallowed since version 3.0. See CMake Policy CMP0034.
11999 Specify the source tree of a third-party utility.
12001 utility_source(cache_entry executable_name
12003 path_to_source [file1 file2 ...])
12004 When a third-party utility's source is included in the distribution,
12006 this command specifies its location and name. The cache entry will not
12007 be set unless the path_to_source and all listed files exist. It is as‐
12008 sumed that the source tree of the utility will have been built before
12009 it is needed.
12010 When cross compiling CMake will print a warning if a utility_source()
12012 command is executed, because in many cases it is used to build an exe‐
12013 cutable which is executed later on. This doesn't work when cross com‐
12014 piling, since the executable can run only on their target platform. So
12015 in this case the cache entry has to be adjusted manually so it points
12016 to an executable which is runnable on the build host.
12017 variable_requires
12019 Disallowed since version 3.0. See CMake Policy CMP0035.
12020 Use the if() command instead.
12022 Assert satisfaction of an option's required variables.
12024 variable_requires(TEST_VARIABLE RESULT_VARIABLE
12026 REQUIRED_VARIABLE1
12027 REQUIRED_VARIABLE2 ...)
12028 The first argument (TEST_VARIABLE) is the name of the variable to be
12030 tested, if that variable is false nothing else is done. If TEST_VARI‐
12031 ABLE is true, then the next argument (RESULT_VARIABLE) is a variable
12032 that is set to true if all the required variables are set. The rest of
12033 the arguments are variables that must be true or not set to NOTFOUND to
12034 avoid an error. If any are not true, an error is reported.
12035 write_file
12037 Deprecated since version 3.0: Use the file(WRITE) command instead.
12038 write_file(filename "message to write"... [APPEND])
12041 The first argument is the file name, the rest of the arguments are mes‐
12043 sages to write. If the argument APPEND is specified, then the message
12044 will be appended.
12045 NOTE 1: file(WRITE) and file(APPEND) do exactly the same as this one
12047 but add some more functionality.
12048 NOTE 2: When using write_file the produced file cannot be used as an
12050 input to CMake (CONFIGURE_FILE, source file ...) because it will lead
12051 to an infinite loop. Use configure_file() if you want to generate in‐
12052 put files to CMake.
12053
12055 2000-2021 Kitware, Inc. and Contributors
120563.22.0 Dec 02, 2021 CMAKE-COMMANDS(7)