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 ┌──────────────────────────┬────────────────────────────┐
32 │Key │ Description │
33 ├──────────────────────────┼────────────────────────────┤
34 │NUMBER_OF_LOGICAL_CORES │ Number of logical cores │
35 ├──────────────────────────┼────────────────────────────┤
36 │NUMBER_OF_PHYSICAL_CORES │ Number of physical cores │
37 ├──────────────────────────┼────────────────────────────┤
38 │HOSTNAME │ Hostname │
39 ├──────────────────────────┼────────────────────────────┤
40 │FQDN │ Fully qualified domain │
41 │ │ name │
42 ├──────────────────────────┼────────────────────────────┤
43 │TOTAL_VIRTUAL_MEMORY │ Total virtual memory in │
44 │ │ MiB [1] │
45 ├──────────────────────────┼────────────────────────────┤
46 │AVAILABLE_VIRTUAL_MEMORY │ Available virtual memory │
47 │ │ in MiB [1] │
48 ├──────────────────────────┼────────────────────────────┤
49 │TOTAL_PHYSICAL_MEMORY │ Total physical memory in │
50 │ │ MiB [1] │
51 ├──────────────────────────┼────────────────────────────┤
52 │AVAILABLE_PHYSICAL_MEMORY │ Available physical memory │
53 │ │ in MiB [1] │
54 └──────────────────────────┴────────────────────────────┘
55 New in version 3.10: Additional <key> values are available:
57 ┌────────────────────────┬────────────────────────────┐
60 │Key │ Description │
61 ├────────────────────────┼────────────────────────────┤
62 │IS_64BIT │ One if processor is 64Bit │
63 └────────────────────────┴────────────────────────────┘
64 │HAS_FPU │ One if processor has │
68 │ │ floating point unit │
69 ├────────────────────────┼────────────────────────────┤
70 │HAS_MMX │ One if processor supports │
71 │ │ MMX instructions │
72 ├────────────────────────┼────────────────────────────┤
73 │HAS_MMX_PLUS │ One if processor supports │
74 │ │ Ext. MMX instructions │
75 ├────────────────────────┼────────────────────────────┤
76 │HAS_SSE │ One if processor supports │
77 │ │ SSE instructions │
78 ├────────────────────────┼────────────────────────────┤
79 │HAS_SSE2 │ One if processor supports │
80 │ │ SSE2 instructions │
81 ├────────────────────────┼────────────────────────────┤
82 │HAS_SSE_FP │ One if processor supports │
83 │ │ SSE FP instructions │
84 ├────────────────────────┼────────────────────────────┤
85 │HAS_SSE_MMX │ One if processor supports │
86 │ │ SSE MMX instructions │
87 ├────────────────────────┼────────────────────────────┤
88 │HAS_AMD_3DNOW │ One if processor supports │
89 │ │ 3DNow instructions │
90 ├────────────────────────┼────────────────────────────┤
91 │HAS_AMD_3DNOW_PLUS │ One if processor supports │
92 │ │ 3DNow+ instructions │
93 ├────────────────────────┼────────────────────────────┤
94 │HAS_IA64 │ One if IA64 processor emu‐ │
95 │ │ lating x86 │
96 ├────────────────────────┼────────────────────────────┤
97 │HAS_SERIAL_NUMBER │ One if processor has se‐ │
98 │ │ rial number │
99 ├────────────────────────┼────────────────────────────┤
100 │PROCESSOR_SERIAL_NUMBER │ Processor serial number │
101 ├────────────────────────┼────────────────────────────┤
102 │PROCESSOR_NAME │ Human readable processor │
103 │ │ name │
104 ├────────────────────────┼────────────────────────────┤
105 │PROCESSOR_DESCRIPTION │ Human readable full pro‐ │
106 │ │ cessor description │
107 ├────────────────────────┼────────────────────────────┤
108 │OS_NAME │ See CMAKE_HOST_SYSTEM_NAME │
109 ├────────────────────────┼────────────────────────────┤
110 │OS_RELEASE │ The OS sub-type e.g. on │
111 │ │ Windows Professional │
112 ├────────────────────────┼────────────────────────────┤
113 │OS_VERSION │ The OS build ID │
114 ├────────────────────────┼────────────────────────────┤
115 │OS_PLATFORM │ See CMAKE_HOST_SYSTEM_PRO‐ │
116 │ │ CESSOR │
117 └────────────────────────┴────────────────────────────┘
118
120 [1] One MiB (mebibyte) is equal to 1024x1024 bytes.
121 cmake_language
123 New in version 3.18.
124 Call meta-operations on CMake commands.
127 Synopsis
129 cmake_language(CALL <command> [<arg>...])
130 cmake_language(EVAL CODE <code>...)
131 cmake_language(DEFER <options>... CALL <command> [<arg>...])
132 Introduction
134 This command will call meta-operations on built-in CMake commands or
135 those created via the macro() or function() commands.
136 cmake_language does not introduce a new variable or policy scope.
138 Calling Commands
140 cmake_language(CALL <command> [<arg>...])
141 Calls the named <command> with the given arguments (if any). For exam‐
143 ple, the code:
144 set(message_command "message")
146 cmake_language(CALL ${message_command} STATUS "Hello World!")
147 is equivalent to
149 message(STATUS "Hello World!")
151 NOTE:
153 To ensure consistency of the code, the following commands are not
154 allowed:
155 • if / elseif / else / endif
157 • while / endwhile
159 • foreach / endforeach
161 • function / endfunction
163 • macro / endmacro
165 Evaluating Code
167 cmake_language(EVAL CODE <code>...)
168 Evaluates the <code>... as CMake code.
170 For example, the code:
172 set(A TRUE)
174 set(B TRUE)
175 set(C TRUE)
176 set(condition "(A AND B) OR C")
177 cmake_language(EVAL CODE "
179 if (${condition})
180 message(STATUS TRUE)
181 else()
182 message(STATUS FALSE)
183 endif()"
184 )
185 is equivalent to
187 set(A TRUE)
189 set(B TRUE)
190 set(C TRUE)
191 set(condition "(A AND B) OR C")
192 file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
194 if (${condition})
195 message(STATUS TRUE)
196 else()
197 message(STATUS FALSE)
198 endif()"
199 )
200 include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)
202 Deferring Calls
204 New in version 3.19.
205 cmake_language(DEFER <options>... CALL <command> [<arg>...])
208 Schedules a call to the named <command> with the given arguments (if
210 any) to occur at a later time. By default, deferred calls are executed
211 as if written at the end of the current directory's CMakeLists.txt
212 file, except that they run even after a return() call. Variable refer‐
213 ences in arguments are evaluated at the time the deferred call is exe‐
214 cuted.
215 The options are:
217 DIRECTORY <dir>
219 Schedule the call for the end of the given directory instead of
220 the current directory. The <dir> may reference either a source
221 directory or its corresponding binary directory. Relative paths
222 are treated as relative to the current source directory.
223 The given directory must be known to CMake, being either the
225 top-level directory or one added by add_subdirectory(). Fur‐
226 thermore, the given directory must not yet be finished process‐
227 ing. This means it can be the current directory or one of its
228 ancestors.
229 ID <id>
231 Specify an identification for the deferred call. The <id> may
232 not be empty and may not begin with a capital letter A-Z. The
233 <id> may begin with an underscore (_) only if it was generated
234 automatically by an earlier call that used ID_VAR to get the id.
235 ID_VAR <var>
237 Specify a variable in which to store the identification for the
238 deferred call. If ID <id> is not given, a new identification
239 will be generated and the generated id will start with an under‐
240 score (_).
241 The currently scheduled list of deferred calls may be retrieved:
243 cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)
245 This will store in <var> a semicolon-separated list of deferred call
247 ids. The ids are for the directory scope in which the calls have been
248 deferred to (i.e. where they will be executed), which can be different
249 to the scope in which they were created. The DIRECTORY option can be
250 used to specify the scope for which to retrieve the call ids. If that
251 option is not given, the call ids for the current directory scope will
252 be returned.
253 Details of a specific call may be retrieved from its id:
255 cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)
257 This will store in <var> a semicolon-separated list in which the first
259 element is the name of the command to be called, and the remaining ele‐
260 ments are its unevaluated arguments (any contained ; characters are in‐
261 cluded literally and cannot be distinguished from multiple arguments).
262 If multiple calls are scheduled with the same id, this retrieves the
263 first one. If no call is scheduled with the given id in the specified
264 DIRECTORY scope (or the current directory scope if no DIRECTORY option
265 is given), this stores an empty string in the variable.
266 Deferred calls may be canceled by their id:
268 cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)
270 This cancels all deferred calls matching any of the given ids in the
272 specified DIRECTORY scope (or the current directory scope if no DIREC‐
273 TORY option is given). Unknown ids are silently ignored.
274 Deferred Call Examples
276 For example, the code:
277 cmake_language(DEFER CALL message "${deferred_message}")
279 cmake_language(DEFER ID_VAR id CALL message "Cancelled Message")
280 cmake_language(DEFER CANCEL_CALL ${id})
281 message("Immediate Message")
282 set(deferred_message "Deferred Message")
283 prints:
285 Immediate Message
287 Deferred Message
288 The Cancelled Message is never printed because its command is can‐
290 celled. The deferred_message variable reference is not evaluated until
291 the call site, so it can be set after the deferred call is scheduled.
292 In order to evaluate variable references immediately when scheduling a
294 deferred call, wrap it using cmake_language(EVAL). However, note that
295 arguments will be re-evaluated in the deferred call, though that can be
296 avoided by using bracket arguments. For example:
297 set(deferred_message "Deferred Message 1")
299 set(re_evaluated [[${deferred_message}]])
300 cmake_language(EVAL CODE "
301 cmake_language(DEFER CALL message [[${deferred_message}]])
302 cmake_language(DEFER CALL message \"${re_evaluated}\")
303 ")
304 message("Immediate Message")
305 set(deferred_message "Deferred Message 2")
306 also prints:
308 Immediate Message
310 Deferred Message 1
311 Deferred Message 2
312 cmake_minimum_required
314 Require a minimum version of cmake.
315 cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR])
317 New in version 3.12: The optional <max> version.
319 Sets the minimum required version of cmake for a project. Also updates
322 the policy settings as explained below.
323 <min> and the optional <max> are each CMake versions of the form ma‐
325 jor.minor[.patch[.tweak]], and the ... is literal.
326 If the running version of CMake is lower than the <min> required ver‐
328 sion it will stop processing the project and report an error. The op‐
329 tional <max> version, if specified, must be at least the <min> version
330 and affects policy settings as described below. If the running version
331 of CMake is older than 3.12, the extra ... dots will be seen as ver‐
332 sion component separators, resulting in the ...<max> part being ignored
333 and preserving the pre-3.12 behavior of basing policies on <min>.
334 This command will set the value of the CMAKE_MINIMUM_REQUIRED_VERSION
336 variable to <min>.
337 The FATAL_ERROR option is accepted but ignored by CMake 2.6 and higher.
339 It should be specified so CMake versions 2.4 and lower fail with an er‐
340 ror instead of just a warning.
341 NOTE:
343 Call the cmake_minimum_required() command at the beginning of the
344 top-level CMakeLists.txt file even before calling the project() com‐
345 mand. It is important to establish version and policy settings be‐
346 fore invoking other commands whose behavior they may affect. See
347 also policy CMP0000.
348 Calling cmake_minimum_required() inside a function() limits some ef‐
350 fects to the function scope when invoked. Such calls should not be
351 made with the intention of having global effects.
352 Policy Settings
354 The cmake_minimum_required(VERSION) command implicitly invokes the
355 cmake_policy(VERSION) command to specify that the current project code
356 is written for the given range of CMake versions. All policies known
357 to the running version of CMake and introduced in the <min> (or <max>,
358 if specified) version or earlier will be set to use NEW behavior. All
359 policies introduced in later versions will be unset. This effectively
360 requests behavior preferred as of a given CMake version and tells newer
361 CMake versions to warn about their new policies.
362 When a <min> version higher than 2.4 is specified the command implic‐
364 itly invokes
365 cmake_policy(VERSION <min>[...<max>])
367 which sets CMake policies based on the range of versions specified.
369 When a <min> version 2.4 or lower is given the command implicitly in‐
370 vokes
371 cmake_policy(VERSION 2.4[...<max>])
373 which enables compatibility features for CMake 2.4 and lower.
375 cmake_parse_arguments
377 Parse function or macro arguments.
378 cmake_parse_arguments(<prefix> <options> <one_value_keywords>
380 <multi_value_keywords> <args>...)
381 cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
383 <one_value_keywords> <multi_value_keywords>)
384 New in version 3.5: This command is implemented natively. Previously,
386 it has been defined in the module CMakeParseArguments.
387 This command is for use in macros or functions. It processes the argu‐
390 ments given to that macro or function, and defines a set of variables
391 which hold the values of the respective options.
392 The first signature reads processes arguments passed in the <args>....
394 This may be used in either a macro() or a function().
395 New in version 3.7: The PARSE_ARGV signature is only for use in a func‐
397 tion() body. In this case the arguments that are parsed come from the
398 ARGV# variables of the calling function. The parsing starts with the
399 <N>-th argument, where <N> is an unsigned integer. This allows for the
400 values to have special characters like ; in them.
401 The <options> argument contains all options for the respective macro,
404 i.e. keywords which can be used when calling the macro without any
405 value following, like e.g. the OPTIONAL keyword of the install() com‐
406 mand.
407 The <one_value_keywords> argument contains all keywords for this macro
409 which are followed by one value, like e.g. DESTINATION keyword of the
410 install() command.
411 The <multi_value_keywords> argument contains all keywords for this
413 macro which can be followed by more than one value, like e.g. the TAR‐
414 GETS or FILES keywords of the install() command.
415 Changed in version 3.5: All keywords shall be unique. I.e. every key‐
417 word shall only be specified once in either <options>, <one_value_key‐
418 words> or <multi_value_keywords>. A warning will be emitted if unique‐
419 ness is violated.
420 When done, cmake_parse_arguments will consider for each of the keywords
423 listed in <options>, <one_value_keywords> and <multi_value_keywords> a
424 variable composed of the given <prefix> followed by "_" and the name of
425 the respective keyword. These variables will then hold the respective
426 value from the argument list or be undefined if the associated option
427 could not be found. For the <options> keywords, these will always be
428 defined, to TRUE or FALSE, whether the option is in the argument list
429 or not.
430 All remaining arguments are collected in a variable <prefix>_UN‐
432 PARSED_ARGUMENTS that will be undefined if all arguments were recog‐
433 nized. This can be checked afterwards to see whether your macro was
434 called with unrecognized parameters.
435 New in version 3.15: <one_value_keywords> and <multi_value_keywords>
437 that were given no values at all are collected in a variable <pre‐
438 fix>_KEYWORDS_MISSING_VALUES that will be undefined if all keywords re‐
439 ceived values. This can be checked to see if there were keywords with‐
440 out any values given.
441 Consider the following example macro, my_install(), which takes similar
444 arguments to the real install() command:
445 macro(my_install)
447 set(options OPTIONAL FAST)
448 set(oneValueArgs DESTINATION RENAME)
449 set(multiValueArgs TARGETS CONFIGURATIONS)
450 cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
451 "${multiValueArgs}" ${ARGN} )
452 # ...
454 Assume my_install() has been called like this:
456 my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)
458 After the cmake_parse_arguments call the macro will have set or unde‐
460 fined the following variables:
461 MY_INSTALL_OPTIONAL = TRUE
463 MY_INSTALL_FAST = FALSE # was not used in call to my_install
464 MY_INSTALL_DESTINATION = "bin"
465 MY_INSTALL_RENAME <UNDEFINED> # was not used
466 MY_INSTALL_TARGETS = "foo;bar"
467 MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
468 MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
469 MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS"
470 # No value for "CONFIGURATIONS" given
471 You can then continue and process these variables.
473 Keywords terminate lists of values, e.g. if directly after a
475 one_value_keyword another recognized keyword follows, this is inter‐
476 preted as the beginning of the new option. E.g. my_install(TARGETS
477 foo DESTINATION OPTIONAL) would result in MY_INSTALL_DESTINATION set to
478 "OPTIONAL", but as OPTIONAL is a keyword itself MY_INSTALL_DESTINATION
479 will be empty (but added to MY_INSTALL_KEYWORDS_MISSING_VALUES) and
480 MY_INSTALL_OPTIONAL will therefore be set to TRUE.
481 cmake_path
483 New in version 3.20.
484 This command is for the manipulation of paths. Only syntactic aspects
487 of paths are handled, there is no interaction of any kind with any un‐
488 derlying file system. The path may represent a non-existing path or
489 even one that is not allowed to exist on the current file system or
490 platform. For operations that do interact with the filesystem, see the
491 file() command.
492 NOTE:
494 The cmake_path command handles paths in the format of the build sys‐
495 tem (i.e. the host platform), not the target system. When
496 cross-compiling, if the path contains elements that are not repre‐
497 sentable on the host platform (e.g. a drive letter when the host is
498 not Windows), the results will be unpredictable.
499 Synopsis
501 Conventions
502 Path Structure And Terminology
504 Normalization
506 Decomposition
508 cmake_path(GET <path-var> ROOT_NAME <out-var>)
509 cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
510 cmake_path(GET <path-var> ROOT_PATH <out-var>)
511 cmake_path(GET <path-var> FILENAME <out-var>)
512 cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>)
513 cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)
514 cmake_path(GET <path-var> RELATIVE_PART <out-var>)
515 cmake_path(GET <path-var> PARENT_PATH <out-var>)
516 Query
518 cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
519 cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
520 cmake_path(HAS_ROOT_PATH <path-var> <out-var>)
521 cmake_path(HAS_FILENAME <path-var> <out-var>)
522 cmake_path(HAS_EXTENSION <path-var> <out-var>)
523 cmake_path(HAS_STEM <path-var> <out-var>)
524 cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)
525 cmake_path(HAS_PARENT_PATH <path-var> <out-var>)
526 cmake_path(IS_ABSOLUTE <path-var> <out-var>)
527 cmake_path(IS_RELATIVE <path-var> <out-var>)
528 cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)
529 cmake_path(COMPARE <input1> <OP> <input2> <out-var>)
530 Modification
532 cmake_path(SET <path-var> [NORMALIZE] <input>)
533 cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
534 cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
535 cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])
536 cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])
537 cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY] [OUTPUT_VARIABLE <out-var>])
538 cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input> [OUTPUT_VARIABLE <out-var>])
539 Generation
541 cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])
542 cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>] [OUTPUT_VARIABLE <out-var>])
543 cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE] [OUTPUT_VARIABLE <out-var>])
544 Native Conversion
546 cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)
547 cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var>)
548 cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var>)
549 Hashing
551 cmake_path(HASH <path-var> <out-var>)
552 Conventions
554 The following conventions are used in this command's documentation:
555 <path-var>
557 Always the name of a variable. For commands that expect a
558 <path-var> as input, the variable must exist and it is expected
559 to hold a single path.
560 <input>
562 A string literal which may contain a path, path fragment, or
563 multiple paths with a special separator depending on the com‐
564 mand. See the description of each command to see how this is
565 interpreted.
566 <input>...
568 Zero or more string literal arguments.
569 <out-var>
571 The name of a variable into which the result of a command will
572 be written.
573 Path Structure And Terminology
575 A path has the following structure (all components are optional, with
576 some constraints):
577 root-name root-directory-separator (item-name directory-separator)* filename
579 root-name
581 Identifies the root on a filesystem with multiple roots (such as
582 "C:" or "//myserver"). It is optional.
583 root-directory-separator
585 A directory separator that, if present, indicates that this path
586 is absolute. If it is missing and the first element other than
587 the root-name is an item-name, then the path is relative.
588 item-name
590 A sequence of characters that aren't directory separators. This
591 name may identify a file, a hard link, a symbolic link, or a di‐
592 rectory. Two special cases are recognized:
593 • The item name consisting of a single dot character . is a
595 directory name that refers to the current directory.
596 • The item name consisting of two dot characters .. is a di‐
598 rectory name that refers to the parent directory.
599 The (...)* pattern shown above is to indicate that there can be
601 zero or more item names, with multiple items separated by a di‐
602 rectory-separator. The ()* characters are not part of the path.
603 directory-separator
605 The only recognized directory separator is a forward slash char‐
606 acter /. If this character is repeated, it is treated as a sin‐
607 gle directory separator. In other words, /usr///////lib is the
608 same as /usr/lib.
609 filename
611 A path has a filename if it does not end with a directory-sepa‐
612 rator. The filename is effectively the last item-name of the
613 path, so it can also be a hard link, symbolic link or a direc‐
614 tory.
615 A filename can have an extension. By default, the extension is
617 defined as the sub-string beginning at the left-most period (in‐
618 cluding the period) and until the end of the filename. In com‐
619 mands that accept a LAST_ONLY keyword, LAST_ONLY changes the in‐
620 terpretation to the sub-string beginning at the right-most pe‐
621 riod.
622 The following exceptions apply to the above interpretation:
624 • If the first character in the filename is a period, that
626 period is ignored (i.e. a filename like ".profile" is
627 treated as having no extension).
628 • If the filename is either . or .., it has no extension.
630 The stem is the part of the filename before the extension.
632 Some commands refer to a root-path. This is the concatenation of
634 root-name and root-directory-separator, either or both of which can be
635 empty. A relative-part refers to the full path with any root-path re‐
636 moved.
637 Creating A Path Variable
639 While a path can be created with care using an ordinary set() command,
640 it is recommended to use cmake_path(SET) instead, as it automatically
641 converts the path to the required form where required. The
642 cmake_path(APPEND) subcommand may be another suitable alternative where
643 a path needs to be constructed by joining fragments. The following ex‐
644 ample compares the three methods for constructing the same path:
645 set(path1 "${CMAKE_CURRENT_SOURCE_DIR}/data")
647 cmake_path(SET path2 "${CMAKE_CURRENT_SOURCE_DIR}/data")
649 cmake_path(APPEND path3 "${CMAKE_CURRENT_SOURCE_DIR}" "data")
651 Modification and Generation sub-commands can either store the result
653 in-place, or in a separate variable named after an OUTPUT_VARIABLE key‐
654 word. All other sub-commands store the result in a mandatory <out-var>
655 variable.
656 Normalization
658 Some sub-commands support normalizing a path. The algorithm used to
659 normalize a path is as follows:
660 1. If the path is empty, stop (the normalized form of an empty path is
662 also an empty path).
663 2. Replace each directory-separator, which may consist of multiple sep‐
665 arators, with a single / (/a///b --> /a/b).
666 3. Remove each solitary period (.) and any immediately following direc‐
668 tory-separator (/a/./b/. --> /a/b).
669 4. Remove each item-name (other than ..) that is immediately followed
671 by a directory-separator and a .., along with any immediately fol‐
672 lowing directory-separator (/a/b/../c --> a/c).
673 5. If there is a root-directory, remove any .. and any directory-sepa‐
675 rators immediately following them. The parent of the root directory
676 is treated as still the root directory (/../a --> /a).
677 6. If the last item-name is .., remove any trailing directory-separator
679 (../ --> ..).
680 7. If the path is empty by this stage, add a dot (normal form of ./ is
682 .).
683 Decomposition
685 The following forms of the GET subcommand each retrieve a different
686 component or group of components from a path. See Path Structure And
687 Terminology for the meaning of each path component.
688 cmake_path(GET <path-var> ROOT_NAME <out-var>)
690 cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
691 cmake_path(GET <path-var> ROOT_PATH <out-var>)
692 cmake_path(GET <path-var> FILENAME <out-var>)
693 cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>)
694 cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)
695 cmake_path(GET <path-var> RELATIVE_PART <out-var>)
696 cmake_path(GET <path-var> PARENT_PATH <out-var>)
697 If a requested component is not present in the path, an empty string
699 will be stored in <out-var>. For example, only Windows systems have
700 the concept of a root-name, so when the host machine is non-Windows,
701 the ROOT_NAME subcommand will always return an empty string.
702 For PARENT_PATH, if the HAS_RELATIVE_PART subcommand returns false, the
704 result is a copy of <path-var>. Note that this implies that a root di‐
705 rectory is considered to have a parent, with that parent being itself.
706 Where HAS_RELATIVE_PART returns true, the result will essentially be
707 <path-var> with one less element.
708 Root examples
710 set(path "c:/a")
711 cmake_path(GET path ROOT_NAME rootName)
713 cmake_path(GET path ROOT_DIRECTORY rootDir)
714 cmake_path(GET path ROOT_PATH rootPath)
715 message("Root name is \"${rootName}\"")
717 message("Root directory is \"${rootDir}\"")
718 message("Root path is \"${rootPath}\"")
719 Root name is "c:"
721 Root directory is "/"
722 Root path is "c:/"
723 Filename examples
725 set(path "/a/b")
726 cmake_path(GET path FILENAME filename)
727 message("First filename is \"${filename}\"")
728 # Trailing slash means filename is empty
730 set(path "/a/b/")
731 cmake_path(GET path FILENAME filename)
732 message("Second filename is \"${filename}\"")
733 First filename is "b"
735 Second filename is ""
736 Extension and stem examples
738 set(path "name.ext1.ext2")
739 cmake_path(GET path EXTENSION fullExt)
741 cmake_path(GET path STEM fullStem)
742 message("Full extension is \"${fullExt}\"")
743 message("Full stem is \"${fullStem}\"")
744 # Effect of LAST_ONLY
746 cmake_path(GET path EXTENSION LAST_ONLY lastExt)
747 cmake_path(GET path STEM LAST_ONLY lastStem)
748 message("Last extension is \"${lastExt}\"")
749 message("Last stem is \"${lastStem}\"")
750 # Special cases
752 set(dotPath "/a/.")
753 set(dotDotPath "/a/..")
754 set(someMorePath "/a/.some.more")
755 cmake_path(GET dotPath EXTENSION dotExt)
756 cmake_path(GET dotPath STEM dotStem)
757 cmake_path(GET dotDotPath EXTENSION dotDotExt)
758 cmake_path(GET dotDotPath STEM dotDotStem)
759 cmake_path(GET dotMorePath EXTENSION someMoreExt)
760 cmake_path(GET dotMorePath STEM someMoreStem)
761 message("Dot extension is \"${dotExt}\"")
762 message("Dot stem is \"${dotStem}\"")
763 message("Dot-dot extension is \"${dotDotExt}\"")
764 message("Dot-dot stem is \"${dotDotStem}\"")
765 message(".some.more extension is \"${someMoreExt}\"")
766 message(".some.more stem is \"${someMoreStem}\"")
767 Full extension is ".ext1.ext2"
769 Full stem is "name"
770 Last extension is ".ext2"
771 Last stem is "name.ext1"
772 Dot extension is ""
773 Dot stem is "."
774 Dot-dot extension is ""
775 Dot-dot stem is ".."
776 .some.more extension is ".more"
777 .some.more stem is ".some"
778 Relative part examples
780 set(path "c:/a/b")
781 cmake_path(GET path RELATIVE_PART result)
782 message("Relative part is \"${result}\"")
783 set(path "c/d")
785 cmake_path(GET path RELATIVE_PART result)
786 message("Relative part is \"${result}\"")
787 set(path "/")
789 cmake_path(GET path RELATIVE_PART result)
790 message("Relative part is \"${result}\"")
791 Relative part is "a/b"
793 Relative part is "c/d"
794 Relative part is ""
795 Path traversal examples
797 set(path "c:/a/b")
798 cmake_path(GET path PARENT_PATH result)
799 message("Parent path is \"${result}\"")
800 set(path "c:/")
802 cmake_path(GET path PARENT_PATH result)
803 message("Parent path is \"${result}\"")
804 Parent path is "c:/a"
806 Parent path is "c:/"
807 Query
809 Each of the GET subcommands has a corresponding HAS_... subcommand
810 which can be used to discover whether a particular path component is
811 present. See Path Structure And Terminology for the meaning of each
812 path component.
813 cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
815 cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
816 cmake_path(HAS_ROOT_PATH <path-var> <out-var>)
817 cmake_path(HAS_FILENAME <path-var> <out-var>)
818 cmake_path(HAS_EXTENSION <path-var> <out-var>)
819 cmake_path(HAS_STEM <path-var> <out-var>)
820 cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)
821 cmake_path(HAS_PARENT_PATH <path-var> <out-var>)
822 Each of the above follows the predictable pattern of setting <out-var>
824 to true if the path has the associated component, or false otherwise.
825 Note the following special cases:
826 • For HAS_ROOT_PATH, a true result will only be returned if at least
828 one of root-name or root-directory is non-empty.
829 • For HAS_PARENT_PATH, the root directory is also considered to have a
831 parent, which will be itself. The result is true except if the path
832 consists of just a filename.
833 cmake_path(IS_ABSOLUTE <path-var> <out-var>)
835 Sets <out-var> to true if <path-var> is absolute. An absolute path is
837 a path that unambiguously identifies the location of a file without
838 reference to an additional starting location. On Windows, this means
839 the path must have both a root-name and a root-directory-separator to
840 be considered absolute. On other platforms, just a root-directory-sep‐
841 arator is sufficient. Note that this means on Windows, IS_ABSOLUTE can
842 be false while HAS_ROOT_DIRECTORY can be true.
843 cmake_path(IS_RELATIVE <path-var> <out-var>)
845 This will store the opposite of IS_ABSOLUTE in <out-var>.
847 cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)
849 Checks if <path-var> is the prefix of <input>.
851 When the NORMALIZE option is specified, <path-var> and <input> are
853 normalized before the check.
854 set(path "/a/b/c/d")
856 cmake_path(IS_PREFIX path "/a/b" result) # result = true
857 cmake_path(IS_PREFIX path "/x/y/z" result) # result = false
858 set(path "/a/b")
860 cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result) # result = true
861 cmake_path(COMPARE <input1> EQUAL <input2> <out-var>)
863 cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>)
864 Compares the lexical representations of two paths provided as string
866 literals. No normalization is performed on either path. Equality is
867 determined according to the following pseudo-code logic:
868 if(NOT <input1>.root_name() STREQUAL <input2>.root_name())
870 return FALSE
871 if(<input1>.has_root_directory() XOR <input2>.has_root_directory())
873 return FALSE
874 Return FALSE if a relative portion of <input1> is not lexicographically
876 equal to the relative portion of <input2>. This comparison is performed path
877 component-wise. If all of the components compare equal, then return TRUE.
878 NOTE:
880 Unlike most other cmake_path() subcommands, the COMPARE subcommand
881 takes literal strings as input, not the names of variables.
882 Modification
884 cmake_path(SET <path-var> [NORMALIZE] <input>)
885 Assign the <input> path to <path-var>. If <input> is a native path, it
887 is converted into a cmake-style path with forward-slashes (/). On Win‐
888 dows, the long filename marker is taken into account.
889 When the NORMALIZE option is specified, the path is normalized before
891 the conversion.
892 For example:
894 set(native_path "c:\\a\\b/..\\c")
896 cmake_path(SET path "${native_path}")
897 message("CMake path is \"${path}\"")
898 cmake_path(SET path NORMALIZE "${native_path}")
900 message("Normalized CMake path is \"${path}\"")
901 Output:
903 CMake path is "c:/a/b/../c"
905 Normalized CMake path is "c:/a/c"
906 cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
908 Append all the <input> arguments to the <path-var> using / as the di‐
910 rectory-separator. Depending on the <input>, the previous contents of
911 <path-var> may be discarded. For each <input> argument, the following
912 algorithm (pseudo-code) applies:
913 # <path> is the contents of <path-var>
915 if(<input>.is_absolute() OR
917 (<input>.has_root_name() AND
918 NOT <input>.root_name() STREQUAL <path>.root_name()))
919 replace <path> with <input>
920 return()
921 endif()
922 if(<input>.has_root_directory())
924 remove any root-directory and the entire relative path from <path>
925 elseif(<path>.has_filename() OR
926 (NOT <path-var>.has_root_directory() OR <path>.is_absolute()))
927 append directory-separator to <path>
928 endif()
929 append <input> omitting any root-name to <path>
931 cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
933 Append all the <input> arguments to the <path-var> without adding any
935 directory-separator.
936 cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])
938 Removes the filename component (as returned by GET ... FILENAME) from
940 <path-var>. After removal, any trailing directory-separator is left
941 alone, if present.
942 If OUTPUT_VARIABLE is not given, then after this function returns,
944 HAS_FILENAME returns false for <path-var>.
945 For example:
947 set(path "/a/b")
949 cmake_path(REMOVE_FILENAME path)
950 message("First path is \"${path}\"")
951 # filename is now already empty, the following removes nothing
953 cmake_path(REMOVE_FILENAME path)
954 message("Second path is \"${result}\"")
955 Output:
957 First path is "/a/"
959 Second path is "/a/"
960 cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])
962 Replaces the filename component from <path-var> with <input>. If
964 <path-var> has no filename component (i.e. HAS_FILENAME returns
965 false), the path is unchanged. The operation is equivalent to the fol‐
966 lowing:
967 cmake_path(HAS_FILENAME path has_filename)
969 if(has_filename)
970 cmake_path(REMOVE_FILENAME path)
971 cmake_path(APPEND path input);
972 endif()
973 cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY]
975 [OUTPUT_VARIABLE <out-var>])
976 Removes the extension, if any, from <path-var>.
978 cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input>
980 [OUTPUT_VARIABLE <out-var>])
981 Replaces the extension with <input>. Its effect is equivalent to the
983 following:
984 cmake_path(REMOVE_EXTENSION path)
986 if(NOT "input" MATCHES "^\\.")
987 cmake_path(APPEND_STRING path ".")
988 endif()
989 cmake_path(APPEND_STRING path "input")
990 Generation
992 cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])
993 Normalize <path-var> according the steps described in Normalization.
995 cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>]
997 [OUTPUT_VARIABLE <out-var>])
998 Modifies <path-var> to make it relative to the BASE_DIRECTORY argument.
1000 If BASE_DIRECTORY is not specified, the default base directory will be
1001 CMAKE_CURRENT_SOURCE_DIR.
1002 For reference, the algorithm used to compute the relative path is the
1004 same as that used by C++ std::filesystem::path::lexically_relative.
1005 cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE]
1007 [OUTPUT_VARIABLE <out-var>])
1008 If <path-var> is a relative path (IS_RELATIVE is true), it is evaluated
1010 relative to the given base directory specified by BASE_DIRECTORY op‐
1011 tion. If BASE_DIRECTORY is not specified, the default base directory
1012 will be CMAKE_CURRENT_SOURCE_DIR.
1013 When the NORMALIZE option is specified, the path is normalized after
1015 the path computation.
1016 Because cmake_path() does not access the filesystem, symbolic links are
1018 not resolved. To compute a real path with symbolic links resolved, use
1019 the file(REAL_PATH) command instead.
1020 Native Conversion
1022 For commands in this section, native refers to the host platform, not
1023 the target platform when cross-compiling.
1024 cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)
1026 Converts a cmake-style <path-var> into a native path with platform-spe‐
1028 cific slashes (\ on Windows hosts and / elsewhere).
1029 When the NORMALIZE option is specified, the path is normalized before
1031 the conversion.
1032 cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])
1034 Converts a native <input> path into a cmake-style path with forward
1036 slashes (/). On Windows hosts, the long filename marker is taken into
1037 account. The input can be a single path or a system search path like
1038 $ENV{PATH}. A search path will be converted to a cmake-style list sep‐
1039 arated by ; characters (on non-Windows platforms, this essentially
1040 means : separators are replaced with ;). The result of the conversion
1041 is stored in the <out-var> variable.
1042 When the NORMALIZE option is specified, the path is normalized before
1044 the conversion.
1045 NOTE:
1047 Unlike most other cmake_path() subcommands, the CONVERT subcommand
1048 takes a literal string as input, not the name of a variable.
1049 cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])
1051 Converts a cmake-style <input> path into a native path with plat‐
1053 form-specific slashes (\ on Windows hosts and / elsewhere). The input
1054 can be a single path or a cmake-style list. A list will be converted
1055 into a native search path (;-separated on Windows, :-separated on other
1056 platforms). The result of the conversion is stored in the <out-var>
1057 variable.
1058 When the NORMALIZE option is specified, the path is normalized before
1060 the conversion.
1061 NOTE:
1063 Unlike most other cmake_path() subcommands, the CONVERT subcommand
1064 takes a literal string as input, not the name of a variable.
1065 For example:
1067 set(paths "/a/b/c" "/x/y/z")
1069 cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths)
1070 message("Native path list is \"${native_paths}\"")
1071 Output on Windows:
1073 Native path list is "\a\b\c;\x\y\z"
1075 Output on all other platforms:
1077 Native path list is "/a/b/c:/x/y/z"
1079 Hashing
1081 cmake_path(HASH <path-var> <out-var>)
1082 Compute a hash value of <path-var> such that for two paths p1 and p2
1084 that compare equal (COMPARE ... EQUAL), the hash value of p1 is equal
1085 to the hash value of p2. The path is always normalized before the hash
1086 is computed.
1087 cmake_policy
1089 Manage CMake Policy settings. See the cmake-policies(7) manual for de‐
1090 fined policies.
1091 As CMake evolves it is sometimes necessary to change existing behavior
1093 in order to fix bugs or improve implementations of existing features.
1094 The CMake Policy mechanism is designed to help keep existing projects
1095 building as new versions of CMake introduce changes in behavior. Each
1096 new policy (behavioral change) is given an identifier of the form
1097 CMP<NNNN> where <NNNN> is an integer index. Documentation associated
1098 with each policy describes the OLD and NEW behavior and the reason the
1099 policy was introduced. Projects may set each policy to select the de‐
1100 sired behavior. When CMake needs to know which behavior to use it
1101 checks for a setting specified by the project. If no setting is avail‐
1102 able the OLD behavior is assumed and a warning is produced requesting
1103 that the policy be set.
1104 Setting Policies by CMake Version
1106 The cmake_policy command is used to set policies to OLD or NEW behav‐
1107 ior. While setting policies individually is supported, we encourage
1108 projects to set policies based on CMake versions:
1109 cmake_policy(VERSION <min>[...<max>])
1111 New in version 3.12: The optional <max> version.
1113 <min> and the optional <max> are each CMake versions of the form ma‐
1116 jor.minor[.patch[.tweak]], and the ... is literal. The <min> version
1117 must be at least 2.4 and at most the running version of CMake. The
1118 <max> version, if specified, must be at least the <min> version but may
1119 exceed the running version of CMake. If the running version of CMake
1120 is older than 3.12, the extra ... dots will be seen as version compo‐
1121 nent separators, resulting in the ...<max> part being ignored and pre‐
1122 serving the pre-3.12 behavior of basing policies on <min>.
1123 This specifies that the current CMake code is written for the given
1125 range of CMake versions. All policies known to the running version of
1126 CMake and introduced in the <min> (or <max>, if specified) version or
1127 earlier will be set to use NEW behavior. All policies introduced in
1128 later versions will be unset (unless the CMAKE_POLICY_DEFAULT_CMP<NNNN>
1129 variable sets a default). This effectively requests behavior preferred
1130 as of a given CMake version and tells newer CMake versions to warn
1131 about their new policies.
1132 Note that the cmake_minimum_required(VERSION) command implicitly calls
1134 cmake_policy(VERSION) too.
1135 Setting Policies Explicitly
1137 cmake_policy(SET CMP<NNNN> NEW)
1138 cmake_policy(SET CMP<NNNN> OLD)
1139 Tell CMake to use the OLD or NEW behavior for a given policy. Projects
1141 depending on the old behavior of a given policy may silence a policy
1142 warning by setting the policy state to OLD. Alternatively one may fix
1143 the project to work with the new behavior and set the policy state to
1144 NEW.
1145 NOTE:
1147 The OLD behavior of a policy is deprecated by definition and may be
1148 removed in a future version of CMake.
1149 Checking Policy Settings
1151 cmake_policy(GET CMP<NNNN> <variable>)
1152 Check whether a given policy is set to OLD or NEW behavior. The output
1154 <variable> value will be OLD or NEW if the policy is set, and empty
1155 otherwise.
1156 CMake Policy Stack
1158 CMake keeps policy settings on a stack, so changes made by the
1159 cmake_policy command affect only the top of the stack. A new entry on
1160 the policy stack is managed automatically for each subdirectory to pro‐
1161 tect its parents and siblings. CMake also manages a new entry for
1162 scripts loaded by include() and find_package() commands except when in‐
1163 voked with the NO_POLICY_SCOPE option (see also policy CMP0011). The
1164 cmake_policy command provides an interface to manage custom entries on
1165 the policy stack:
1166 cmake_policy(PUSH)
1168 cmake_policy(POP)
1169 Each PUSH must have a matching POP to erase any changes. This is use‐
1171 ful to make temporary changes to policy settings. Calls to the
1172 cmake_minimum_required(VERSION), cmake_policy(VERSION), or cmake_pol‐
1173 icy(SET) commands influence only the current top of the policy stack.
1174 Commands created by the function() and macro() commands record policy
1176 settings when they are created and use the pre-record policies when
1177 they are invoked. If the function or macro implementation sets poli‐
1178 cies, the changes automatically propagate up through callers until they
1179 reach the closest nested policy stack entry.
1180 configure_file
1182 Copy a file to another location and modify its contents.
1183 configure_file(<input> <output>
1185 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
1186 FILE_PERMISSIONS <permissions>...]
1187 [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
1188 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
1189 Copies an <input> file to an <output> file and substitutes variable
1191 values referenced as @VAR@ or ${VAR} in the input file content. Each
1192 variable reference will be replaced with the current value of the vari‐
1193 able, or the empty string if the variable is not defined. Furthermore,
1194 input lines of the form
1195 #cmakedefine VAR ...
1197 will be replaced with either
1199 #define VAR ...
1201 or
1203 /* #undef VAR */
1205 depending on whether VAR is set in CMake to any value not considered a
1207 false constant by the if() command. The "..." content on the line af‐
1208 ter the variable name, if any, is processed as above. Input file lines
1209 of the form #cmakedefine01 VAR will be replaced with either #define VAR
1210 1 or #define VAR 0 similarly.
1211 New in version 3.10: The result lines (with the exception of the #undef
1213 comments) can be indented using spaces and/or tabs between the # char‐
1214 acter and the cmakedefine or cmakedefine01 words. This whitespace in‐
1215 dentation will be preserved in the output lines:
1216 # cmakedefine VAR
1218 # cmakedefine01 VAR
1219 will be replaced, if VAR is defined, with
1221 # define VAR
1223 # define VAR 1
1224 If the input file is modified the build system will re-run CMake to
1227 re-configure the file and generate the build system again. The gener‐
1228 ated file is modified and its timestamp updated on subsequent cmake
1229 runs only if its content is changed.
1230 The arguments are:
1232 <input>
1234 Path to the input file. A relative path is treated with respect
1235 to the value of CMAKE_CURRENT_SOURCE_DIR. The input path must
1236 be a file, not a directory.
1237 <output>
1239 Path to the output file or directory. A relative path is
1240 treated with respect to the value of CMAKE_CURRENT_BINARY_DIR.
1241 If the path names an existing directory the output file is
1242 placed in that directory with the same file name as the input
1243 file.
1244 NO_SOURCE_PERMISSIONS
1246 New in version 3.19.
1247 Do not transfer the permissions of the input file to the output
1250 file. The copied file permissions default to the standard 644
1251 value (-rw-r--r--).
1252 USE_SOURCE_PERMISSIONS
1254 New in version 3.20.
1255 Transfer the permissions of the input file to the output file.
1258 This is already the default behavior if none of the three per‐
1259 missions-related keywords are given (NO_SOURCE_PERMISSIONS,
1260 USE_SOURCE_PERMISSIONS or FILE_PERMISSIONS). The
1261 USE_SOURCE_PERMISSIONS keyword mostly serves as a way of making
1262 the intended behavior clearer at the call site.
1263 FILE_PERMISSIONS <permissions>...
1265 New in version 3.20.
1266 Ignore the input file's permissions and use the specified <per‐
1269 missions> for the output file instead.
1270 COPYONLY
1272 Copy the file without replacing any variable references or other
1273 content. This option may not be used with NEWLINE_STYLE.
1274 ESCAPE_QUOTES
1276 Escape any substituted quotes with backslashes (C-style).
1277 @ONLY Restrict variable replacement to references of the form @VAR@.
1279 This is useful for configuring scripts that use ${VAR} syntax.
1280 NEWLINE_STYLE <style>
1282 Specify the newline style for the output file. Specify UNIX or
1283 LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n new‐
1284 lines. This option may not be used with COPYONLY.
1285 Example
1287 Consider a source tree containing a foo.h.in file:
1288 #cmakedefine FOO_ENABLE
1290 #cmakedefine FOO_STRING "@FOO_STRING@"
1291 An adjacent CMakeLists.txt may use configure_file to configure the
1293 header:
1294 option(FOO_ENABLE "Enable Foo" ON)
1296 if(FOO_ENABLE)
1297 set(FOO_STRING "foo")
1298 endif()
1299 configure_file(foo.h.in foo.h @ONLY)
1300 This creates a foo.h in the build directory corresponding to this
1302 source directory. If the FOO_ENABLE option is on, the configured file
1303 will contain:
1304 #define FOO_ENABLE
1306 #define FOO_STRING "foo"
1307 Otherwise it will contain:
1309 /* #undef FOO_ENABLE */
1311 /* #undef FOO_STRING */
1312 One may then use the include_directories() command to specify the out‐
1314 put directory as an include directory:
1315 include_directories(${CMAKE_CURRENT_BINARY_DIR})
1317 so that sources may include the header as #include <foo.h>.
1319 continue
1321 New in version 3.2.
1322 Continue to the top of enclosing foreach or while loop.
1325 continue()
1327 The continue command allows a cmake script to abort the rest of a block
1329 in a foreach() or while() loop, and start at the top of the next itera‐
1330 tion.
1331 See also the break() command.
1333 else
1335 Starts the else portion of an if block.
1336 else([<condition>])
1338 See the if() command.
1340 elseif
1342 Starts an elseif portion of an if block.
1343 elseif(<condition>)
1345 See the if() command, especially for the syntax and logic of the <con‐
1347 dition>.
1348 endforeach
1350 Ends a list of commands in a foreach block.
1351 endforeach([<loop_var>])
1353 See the foreach() command.
1355 The optional <loop_var> argument is supported for backward compatibil‐
1357 ity only. If used it must be a verbatim repeat of the <loop_var> argu‐
1358 ment of the opening foreach clause.
1359 endfunction
1361 Ends a list of commands in a function block.
1362 endfunction([<name>])
1364 See the function() command.
1366 The optional <name> argument is supported for backward compatibility
1368 only. If used it must be a verbatim repeat of the <name> argument of
1369 the opening function command.
1370 endif
1372 Ends a list of commands in an if block.
1373 endif([<condition>])
1375 See the if() command.
1377 The optional <condition> argument is supported for backward compatibil‐
1379 ity only. If used it must be a verbatim repeat of the argument of the
1380 opening if clause.
1381 endmacro
1383 Ends a list of commands in a macro block.
1384 endmacro([<name>])
1386 See the macro() command.
1388 The optional <name> argument is supported for backward compatibility
1390 only. If used it must be a verbatim repeat of the <name> argument of
1391 the opening macro command.
1392 endwhile
1394 Ends a list of commands in a while block.
1395 endwhile([<condition>])
1397 See the while() command.
1399 The optional <condition> argument is supported for backward compatibil‐
1401 ity only. If used it must be a verbatim repeat of the argument of the
1402 opening while clause.
1403 execute_process
1405 Execute one or more child processes.
1406 execute_process(COMMAND <cmd1> [<arguments>]
1408 [COMMAND <cmd2> [<arguments>]]...
1409 [WORKING_DIRECTORY <directory>]
1410 [TIMEOUT <seconds>]
1411 [RESULT_VARIABLE <variable>]
1412 [RESULTS_VARIABLE <variable>]
1413 [OUTPUT_VARIABLE <variable>]
1414 [ERROR_VARIABLE <variable>]
1415 [INPUT_FILE <file>]
1416 [OUTPUT_FILE <file>]
1417 [ERROR_FILE <file>]
1418 [OUTPUT_QUIET]
1419 [ERROR_QUIET]
1420 [COMMAND_ECHO <where>]
1421 [OUTPUT_STRIP_TRAILING_WHITESPACE]
1422 [ERROR_STRIP_TRAILING_WHITESPACE]
1423 [ENCODING <name>]
1424 [ECHO_OUTPUT_VARIABLE]
1425 [ECHO_ERROR_VARIABLE]
1426 [COMMAND_ERROR_IS_FATAL <ANY|LAST>])
1427 Runs the given sequence of one or more commands.
1429 Commands are executed concurrently as a pipeline, with the standard
1431 output of each process piped to the standard input of the next. A sin‐
1432 gle standard error pipe is used for all processes.
1433 Options:
1435 COMMAND
1437 A child process command line.
1438 CMake executes the child process using operating system APIs di‐
1440 rectly. All arguments are passed VERBATIM to the child process.
1441 No intermediate shell is used, so shell operators such as > are
1442 treated as normal arguments. (Use the INPUT_*, OUTPUT_*, and
1443 ERROR_* options to redirect stdin, stdout, and stderr.)
1444 If a sequential execution of multiple commands is required, use
1446 multiple execute_process() calls with a single COMMAND argument.
1447 WORKING_DIRECTORY
1449 The named directory will be set as the current working directory
1450 of the child processes.
1451 TIMEOUT
1453 After the specified number of seconds (fractions allowed), all
1454 unfinished child processes will be terminated, and the RE‐
1455 SULT_VARIABLE will be set to a string mentioning the "timeout".
1456 RESULT_VARIABLE
1458 The variable will be set to contain the result of last child
1459 process. This will be an integer return code from the last
1460 child or a string describing an error condition.
1461 RESULTS_VARIABLE <variable>
1463 New in version 3.10.
1464 The variable will be set to contain the result of all processes
1467 as a semicolon-separated list, in order of the given COMMAND ar‐
1468 guments. Each entry will be an integer return code from the
1469 corresponding child or a string describing an error condition.
1470 OUTPUT_VARIABLE, ERROR_VARIABLE
1472 The variable named will be set with the contents of the standard
1473 output and standard error pipes, respectively. If the same
1474 variable is named for both pipes their output will be merged in
1475 the order produced.
1476 INPUT_FILE, OUTPUT_FILE, ERROR_FILE
1478 The file named will be attached to the standard input of the
1479 first process, standard output of the last process, or standard
1480 error of all processes, respectively.
1481 New in version 3.3: If the same file is named for both output
1483 and error then it will be used for both.
1484 OUTPUT_QUIET, ERROR_QUIET
1487 The standard output or standard error results will be quietly
1488 ignored.
1489 COMMAND_ECHO <where>
1491 New in version 3.15.
1492 The command being run will be echo'ed to <where> with <where>
1495 being set to one of STDERR, STDOUT or NONE. See the CMAKE_EXE‐
1496 CUTE_PROCESS_COMMAND_ECHO variable for a way to control the de‐
1497 fault behavior when this option is not present.
1498 ENCODING <name>
1500 New in version 3.8.
1501 On Windows, the encoding that is used to decode output from the
1504 process. Ignored on other platforms. Valid encoding names are:
1505 NONE Perform no decoding. This assumes that the process out‐
1507 put is encoded in the same way as CMake's internal encod‐
1508 ing (UTF-8). This is the default.
1509 AUTO Use the current active console's codepage or if that
1511 isn't available then use ANSI.
1512 ANSI Use the ANSI codepage.
1514 OEM Use the original equipment manufacturer (OEM) code page.
1516 UTF8 or UTF-8
1518 Use the UTF-8 codepage.
1519 New in version 3.11: Accept UTF-8 spelling for consis‐
1521 tency with the UTF-8 RFC naming convention.
1522 ECHO_OUTPUT_VARIABLE, ECHO_ERROR_VARIABLE
1525 New in version 3.18.
1526 The standard output or standard error will not be exclusively
1529 redirected to the configured variables.
1530 The output will be duplicated, it will be sent into the config‐
1532 ured variables and also on standard output or standard error.
1533 This is analogous to the tee Unix command.
1535 COMMAND_ERROR_IS_FATAL <ANY|LAST>
1537 New in version 3.19.
1538 The option following COMMAND_ERROR_IS_FATAL determines the be‐
1541 havior when an error is encountered:
1542 ANY If any of the commands in the list of commands fail, the
1543 execute_process() command halts with an error.
1544 LAST If the last command in the list of commands fails, the
1546 execute_process() command halts with an error. Commands ear‐
1547 lier in the list will not cause a fatal error.
1548 If more than one OUTPUT_* or ERROR_* option is given for the same pipe
1550 the precedence is not specified. If no OUTPUT_* or ERROR_* options are
1551 given the output will be shared with the corresponding pipes of the
1552 CMake process itself.
1553 The execute_process() command is a newer more powerful version of
1555 exec_program(), but the old command has been kept for compatibility.
1556 Both commands run while CMake is processing the project prior to build
1557 system generation. Use add_custom_target() and add_custom_command() to
1558 create custom commands that run at build time.
1559 file
1561 File manipulation command.
1562 This command is dedicated to file and path manipulation requiring ac‐
1564 cess to the filesystem.
1565 For other path manipulation, handling only syntactic aspects, have a
1567 look at cmake_path() command.
1568 NOTE:
1570 The sub-commands RELATIVE_PATH, TO_CMAKE_PATH and TO_NATIVE_PATH has
1571 been superseded, respectively, by sub-commands RELATIVE_PATH, CON‐
1572 VERT ... TO_CMAKE_PATH_LIST and CONVERT ... TO_NATIVE_PATH_LIST of
1573 cmake_path() command.
1574 Synopsis
1576 Reading
1577 file(READ <filename> <out-var> [...])
1578 file(STRINGS <filename> <out-var> [...])
1579 file(<HASH> <filename> <out-var>)
1580 file(TIMESTAMP <filename> <out-var> [...])
1581 file(GET_RUNTIME_DEPENDENCIES [...])
1582 Writing
1584 file({WRITE | APPEND} <filename> <content>...)
1585 file({TOUCH | TOUCH_NOCREATE} [<file>...])
1586 file(GENERATE OUTPUT <output-file> [...])
1587 file(CONFIGURE OUTPUT <output-file> CONTENT <content> [...])
1588 Filesystem
1590 file({GLOB | GLOB_RECURSE} <out-var> [...] [<globbing-expr>...])
1591 file(RENAME <oldname> <newname>)
1592 file({REMOVE | REMOVE_RECURSE } [<files>...])
1593 file(MAKE_DIRECTORY [<dir>...])
1594 file({COPY | INSTALL} <file>... DESTINATION <dir> [...])
1595 file(SIZE <filename> <out-var>)
1596 file(READ_SYMLINK <linkname> <out-var>)
1597 file(CREATE_LINK <original> <linkname> [...])
1598 file(CHMOD <files>... <directories>... PERMISSIONS <permissions>... [...])
1599 file(CHMOD_RECURSE <files>... <directories>... PERMISSIONS <permissions>... [...])
1600 Path Conversion
1602 file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>])
1603 file(RELATIVE_PATH <out-var> <directory> <file>)
1604 file({TO_CMAKE_PATH | TO_NATIVE_PATH} <path> <out-var>)
1605 Transfer
1607 file(DOWNLOAD <url> [<file>] [...])
1608 file(UPLOAD <file> <url> [...])
1609 Locking
1611 file(LOCK <path> [...])
1612 Archiving
1614 file(ARCHIVE_CREATE OUTPUT <archive> PATHS <paths>... [...])
1615 file(ARCHIVE_EXTRACT INPUT <archive> [...])
1616 Reading
1618 file(READ <filename> <variable>
1619 [OFFSET <offset>] [LIMIT <max-in>] [HEX])
1620 Read content from a file called <filename> and store it in a <vari‐
1622 able>. Optionally start from the given <offset> and read at most
1623 <max-in> bytes. The HEX option causes data to be converted to a hexa‐
1624 decimal representation (useful for binary data). If the HEX option is
1625 specified, letters in the output (a through f) are in lowercase.
1626 file(STRINGS <filename> <variable> [<options>...])
1628 Parse a list of ASCII strings from <filename> and store it in <vari‐
1630 able>. Binary data in the file are ignored. Carriage return (\r, CR)
1631 characters are ignored. The options are:
1632 LENGTH_MAXIMUM <max-len>
1634 Consider only strings of at most a given length.
1635 LENGTH_MINIMUM <min-len>
1637 Consider only strings of at least a given length.
1638 LIMIT_COUNT <max-num>
1640 Limit the number of distinct strings to be extracted.
1641 LIMIT_INPUT <max-in>
1643 Limit the number of input bytes to read from the file.
1644 LIMIT_OUTPUT <max-out>
1646 Limit the number of total bytes to store in the <variable>.
1647 NEWLINE_CONSUME
1649 Treat newline characters (\n, LF) as part of string content in‐
1650 stead of terminating at them.
1651 NO_HEX_CONVERSION
1653 Intel Hex and Motorola S-record files are automatically con‐
1654 verted to binary while reading unless this option is given.
1655 REGEX <regex>
1657 Consider only strings that match the given regular expression.
1658 ENCODING <encoding-type>
1660 New in version 3.1.
1661 Consider strings of a given encoding. Currently supported en‐
1664 codings are: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. If
1665 the ENCODING option is not provided and the file has a Byte Or‐
1666 der Mark, the ENCODING option will be defaulted to respect the
1667 Byte Order Mark.
1668 New in version 3.2: Added the UTF-16LE, UTF-16BE, UTF-32LE,
1670 UTF-32BE encodings.
1671 For example, the code
1674 file(STRINGS myfile.txt myfile)
1676 stores a list in the variable myfile in which each item is a line from
1678 the input file.
1679 file(<HASH> <filename> <variable>)
1681 Compute a cryptographic hash of the content of <filename> and store it
1683 in a <variable>. The supported <HASH> algorithm names are those listed
1684 by the string(<HASH>) command.
1685 file(TIMESTAMP <filename> <variable> [<format>] [UTC])
1687 Compute a string representation of the modification time of <filename>
1689 and store it in <variable>. Should the command be unable to obtain a
1690 timestamp variable will be set to the empty string ("").
1691 See the string(TIMESTAMP) command for documentation of the <format> and
1693 UTC options.
1694 file(GET_RUNTIME_DEPENDENCIES
1696 [RESOLVED_DEPENDENCIES_VAR <deps_var>]
1697 [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
1698 [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
1699 [EXECUTABLES [<executable_files>...]]
1700 [LIBRARIES [<library_files>...]]
1701 [MODULES [<module_files>...]]
1702 [DIRECTORIES [<directories>...]]
1703 [BUNDLE_EXECUTABLE <bundle_executable_file>]
1704 [PRE_INCLUDE_REGEXES [<regexes>...]]
1705 [PRE_EXCLUDE_REGEXES [<regexes>...]]
1706 [POST_INCLUDE_REGEXES [<regexes>...]]
1707 [POST_EXCLUDE_REGEXES [<regexes>...]]
1708 )
1709 New in version 3.16.
1711 Recursively get the list of libraries depended on by the given files.
1714 Please note that this sub-command is not intended to be used in project
1716 mode. Instead, use it in an install(CODE) or install(SCRIPT) block.
1717 For example:
1718 install(CODE [[
1720 file(GET_RUNTIME_DEPENDENCIES
1721 # ...
1722 )
1723 ]])
1724 The arguments are as follows:
1726 RESOLVED_DEPENDENCIES_VAR <deps_var>
1728 Name of the variable in which to store the list of resolved de‐
1729 pendencies.
1730 UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>
1732 Name of the variable in which to store the list of unresolved
1733 dependencies. If this variable is not specified, and there are
1734 any unresolved dependencies, an error is issued.
1735 CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>
1737 Variable prefix in which to store conflicting dependency infor‐
1738 mation. Dependencies are conflicting if two files with the same
1739 name are found in two different directories. The list of file‐
1740 names that conflict are stored in <conflicting_deps_pre‐
1741 fix>_FILENAMES. For each filename, the list of paths that were
1742 found for that filename are stored in <conflicting_deps_pre‐
1743 fix>_<filename>.
1744 EXECUTABLES <executable_files>
1746 List of executable files to read for dependencies. These are ex‐
1747 ecutables that are typically created with add_executable(), but
1748 they do not have to be created by CMake. On Apple platforms, the
1749 paths to these files determine the value of @executable_path
1750 when recursively resolving the libraries. Specifying any kind
1751 of library (STATIC, MODULE, or SHARED) here will result in unde‐
1752 fined behavior.
1753 LIBRARIES <library_files>
1755 List of library files to read for dependencies. These are li‐
1756 braries that are typically created with add_library(SHARED), but
1757 they do not have to be created by CMake. Specifying STATIC li‐
1758 braries, MODULE libraries, or executables here will result in
1759 undefined behavior.
1760 MODULES <module_files>
1762 List of loadable module files to read for dependencies. These
1763 are modules that are typically created with add_library(MODULE),
1764 but they do not have to be created by CMake. They are typically
1765 used by calling dlopen() at runtime rather than linked at link
1766 time with ld -l. Specifying STATIC libraries, SHARED libraries,
1767 or executables here will result in undefined behavior.
1768 DIRECTORIES <directories>
1770 List of additional directories to search for dependencies. On
1771 Linux platforms, these directories are searched if the depen‐
1772 dency is not found in any of the other usual paths. If it is
1773 found in such a directory, a warning is issued, because it means
1774 that the file is incomplete (it does not list all of the direc‐
1775 tories that contain its dependencies). On Windows platforms,
1776 these directories are searched if the dependency is not found in
1777 any of the other search paths, but no warning is issued, because
1778 searching other paths is a normal part of Windows dependency
1779 resolution. On Apple platforms, this argument has no effect.
1780 BUNDLE_EXECUTABLE <bundle_executable_file>
1782 Executable to treat as the "bundle executable" when resolving
1783 libraries. On Apple platforms, this argument determines the
1784 value of @executable_path when recursively resolving libraries
1785 for LIBRARIES and MODULES files. It has no effect on EXECUTA‐
1786 BLES files. On other platforms, it has no effect. This is typi‐
1787 cally (but not always) one of the executables in the EXECUTABLES
1788 argument which designates the "main" executable of the package.
1789 The following arguments specify filters for including or excluding li‐
1791 braries to be resolved. See below for a full description of how they
1792 work.
1793 PRE_INCLUDE_REGEXES <regexes>
1795 List of pre-include regexes through which to filter the names of
1796 not-yet-resolved dependencies.
1797 PRE_EXCLUDE_REGEXES <regexes>
1799 List of pre-exclude regexes through which to filter the names of
1800 not-yet-resolved dependencies.
1801 POST_INCLUDE_REGEXES <regexes>
1803 List of post-include regexes through which to filter the names
1804 of resolved dependencies.
1805 POST_EXCLUDE_REGEXES <regexes>
1807 List of post-exclude regexes through which to filter the names
1808 of resolved dependencies.
1809 These arguments can be used to exclude unwanted system libraries when
1811 resolving the dependencies, or to include libraries from a specific di‐
1812 rectory. The filtering works as follows:
1813 1. If the not-yet-resolved dependency matches any of the PRE_IN‐
1815 CLUDE_REGEXES, steps 2 and 3 are skipped, and the dependency resolu‐
1816 tion proceeds to step 4.
1817 2. If the not-yet-resolved dependency matches any of the PRE_EX‐
1819 CLUDE_REGEXES, dependency resolution stops for that dependency.
1820 3. Otherwise, dependency resolution proceeds.
1822 4. file(GET_RUNTIME_DEPENDENCIES) searches for the dependency according
1824 to the linking rules of the platform (see below).
1825 5. If the dependency is found, and its full path matches one of the
1827 POST_INCLUDE_REGEXES, the full path is added to the resolved depen‐
1828 dencies, and file(GET_RUNTIME_DEPENDENCIES) recursively resolves
1829 that library's own dependencies. Otherwise, resolution proceeds to
1830 step 6.
1831 6. If the dependency is found, but its full path matches one of the
1833 POST_EXCLUDE_REGEXES, it is not added to the resolved dependencies,
1834 and dependency resolution stops for that dependency.
1835 7. If the dependency is found, and its full path does not match either
1837 POST_INCLUDE_REGEXES or POST_EXCLUDE_REGEXES, the full path is added
1838 to the resolved dependencies, and file(GET_RUNTIME_DEPENDENCIES) re‐
1839 cursively resolves that library's own dependencies.
1840 Different platforms have different rules for how dependencies are re‐
1842 solved. These specifics are described here.
1843 On Linux platforms, library resolution works as follows:
1845 1. If the depending file does not have any RUNPATH entries, and the li‐
1847 brary exists in one of the depending file's RPATH entries, or its
1848 parents', in that order, the dependency is resolved to that file.
1849 2. Otherwise, if the depending file has any RUNPATH entries, and the
1851 library exists in one of those entries, the dependency is resolved
1852 to that file.
1853 3. Otherwise, if the library exists in one of the directories listed by
1855 ldconfig, the dependency is resolved to that file.
1856 4. Otherwise, if the library exists in one of the DIRECTORIES entries,
1858 the dependency is resolved to that file. In this case, a warning is
1859 issued, because finding a file in one of the DIRECTORIES means that
1860 the depending file is not complete (it does not list all the direc‐
1861 tories from which it pulls dependencies).
1862 5. Otherwise, the dependency is unresolved.
1864 On Windows platforms, library resolution works as follows:
1866 1. The dependent DLL name is converted to lowercase. Windows DLL names
1868 are case-insensitive, and some linkers mangle the case of the DLL
1869 dependency names. However, this makes it more difficult for PRE_IN‐
1870 CLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, and
1871 POST_EXCLUDE_REGEXES to properly filter DLL names - every regex
1872 would have to check for both uppercase and lowercase letters. For
1873 example:
1874 file(GET_RUNTIME_DEPENDENCIES
1876 # ...
1877 PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
1878 )
1879 Converting the DLL name to lowercase allows the regexes to only
1881 match lowercase names, thus simplifying the regex. For example:
1882 file(GET_RUNTIME_DEPENDENCIES
1884 # ...
1885 PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
1886 )
1887 This regex will match mylibrary.dll regardless of how it is cased,
1889 either on disk or in the depending file. (For example, it will match
1890 mylibrary.dll, MyLibrary.dll, and MYLIBRARY.DLL.)
1891 Please note that the directory portion of any resolved DLLs retains
1893 its casing and is not converted to lowercase. Only the filename por‐
1894 tion is converted.
1895 2. (Not yet implemented) If the depending file is a Windows Store app,
1897 and the dependency is listed as a dependency in the application's
1898 package manifest, the dependency is resolved to that file.
1899 3. Otherwise, if the library exists in the same directory as the de‐
1901 pending file, the dependency is resolved to that file.
1902 4. Otherwise, if the library exists in either the operating system's
1904 system32 directory or the Windows directory, in that order, the de‐
1905 pendency is resolved to that file.
1906 5. Otherwise, if the library exists in one of the directories specified
1908 by DIRECTORIES, in the order they are listed, the dependency is re‐
1909 solved to that file. In this case, a warning is not issued, because
1910 searching other directories is a normal part of Windows library res‐
1911 olution.
1912 6. Otherwise, the dependency is unresolved.
1914 On Apple platforms, library resolution works as follows:
1916 1. If the dependency starts with @executable_path/, and an EXECUTABLES
1918 argument is in the process of being resolved, and replacing @exe‐
1919 cutable_path/ with the directory of the executable yields an exist‐
1920 ing file, the dependency is resolved to that file.
1921 2. Otherwise, if the dependency starts with @executable_path/, and
1923 there is a BUNDLE_EXECUTABLE argument, and replacing @exe‐
1924 cutable_path/ with the directory of the bundle executable yields an
1925 existing file, the dependency is resolved to that file.
1926 3. Otherwise, if the dependency starts with @loader_path/, and replac‐
1928 ing @loader_path/ with the directory of the depending file yields an
1929 existing file, the dependency is resolved to that file.
1930 4. Otherwise, if the dependency starts with @rpath/, and replacing
1932 @rpath/ with one of the RPATH entries of the depending file yields
1933 an existing file, the dependency is resolved to that file. Note that
1934 RPATH entries that start with @executable_path/ or @loader_path/
1935 also have these items replaced with the appropriate path.
1936 5. Otherwise, if the dependency is an absolute file that exists, the
1938 dependency is resolved to that file.
1939 6. Otherwise, the dependency is unresolved.
1941 This function accepts several variables that determine which tool is
1943 used for dependency resolution:
1944 CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM
1946 Determines which operating system and executable format the
1947 files are built for. This could be one of several values:
1948 • linux+elf
1950 • windows+pe
1952 • macos+macho
1954 If this variable is not specified, it is determined automati‐
1956 cally by system introspection.
1957 CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
1959 Determines the tool to use for dependency resolution. It could
1960 be one of several values, depending on the value of
1961 CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM:
1962 ┌─────────────────────────┬──────────────────────────┐
1964 │CMAKE_GET_RUNTIME_DEPEN‐ │ CMAKE_GET_RUNTIME_DEPEN‐ │
1965 │DENCIES_PLATFORM │ DENCIES_TOOL │
1966 ├─────────────────────────┼──────────────────────────┤
1967 │linux+elf │ objdump │
1968 ├─────────────────────────┼──────────────────────────┤
1969 │windows+pe │ dumpbin │
1970 ├─────────────────────────┼──────────────────────────┤
1971 │windows+pe │ objdump │
1972 ├─────────────────────────┼──────────────────────────┤
1973 │macos+macho │ otool │
1974 └─────────────────────────┴──────────────────────────┘
1975 If this variable is not specified, it is determined automati‐
1977 cally by system introspection.
1978 CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND
1980 Determines the path to the tool to use for dependency resolu‐
1981 tion. This is the actual path to objdump, dumpbin, or otool.
1982 If this variable is not specified, it is determined by the value
1984 of CMAKE_OBJDUMP if set, else by system introspection.
1985 New in version 3.18: Use CMAKE_OBJDUMP if set.
1987 Writing
1990 file(WRITE <filename> <content>...)
1991 file(APPEND <filename> <content>...)
1992 Write <content> into a file called <filename>. If the file does not
1994 exist, it will be created. If the file already exists, WRITE mode will
1995 overwrite it and APPEND mode will append to the end. Any directories
1996 in the path specified by <filename> that do not exist will be created.
1997 If the file is a build input, use the configure_file() command to up‐
1999 date the file only when its content changes.
2000 file(TOUCH [<files>...])
2002 file(TOUCH_NOCREATE [<files>...])
2003 New in version 3.12.
2005 Create a file with no content if it does not yet exist. If the file al‐
2008 ready exists, its access and/or modification will be updated to the
2009 time when the function call is executed.
2010 Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a
2012 file does not exist it will be silently ignored.
2013 With TOUCH and TOUCH_NOCREATE the contents of an existing file will not
2015 be modified.
2016 file(GENERATE OUTPUT output-file
2018 <INPUT input-file|CONTENT content>
2019 [CONDITION expression] [TARGET target]
2020 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
2021 FILE_PERMISSIONS <permissions>...]
2022 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
2023 Generate an output file for each build configuration supported by the
2025 current CMake Generator. Evaluate generator expressions from the input
2026 content to produce the output content. The options are:
2027 CONDITION <condition>
2029 Generate the output file for a particular configuration only if
2030 the condition is true. The condition must be either 0 or 1 af‐
2031 ter evaluating generator expressions.
2032 CONTENT <content>
2034 Use the content given explicitly as input.
2035 INPUT <input-file>
2037 Use the content from a given file as input.
2038 Changed in version 3.10: A relative path is treated with respect
2040 to the value of CMAKE_CURRENT_SOURCE_DIR. See policy CMP0070.
2041 OUTPUT <output-file>
2044 Specify the output file name to generate. Use generator expres‐
2045 sions such as $<CONFIG> to specify a configuration-specific out‐
2046 put file name. Multiple configurations may generate the same
2047 output file only if the generated content is identical. Other‐
2048 wise, the <output-file> must evaluate to an unique name for each
2049 configuration.
2050 Changed in version 3.10: A relative path (after evaluating gen‐
2052 erator expressions) is treated with respect to the value of
2053 CMAKE_CURRENT_BINARY_DIR. See policy CMP0070.
2054 TARGET <target>
2057 New in version 3.19.
2058 Specify which target to use when evaluating generator expres‐
2061 sions that require a target for evaluation (e.g. $<COMPILE_FEA‐
2062 TURES:...>, $<TARGET_PROPERTY:prop>).
2063 NO_SOURCE_PERMISSIONS
2065 New in version 3.20.
2066 The generated file permissions default to the standard 644 value
2069 (-rw-r--r--).
2070 USE_SOURCE_PERMISSIONS
2072 New in version 3.20.
2073 Transfer the file permissions of the INPUT file to the generated
2076 file. This is already the default behavior if none of the three
2077 permissions-related keywords are given (NO_SOURCE_PERMISSIONS,
2078 USE_SOURCE_PERMISSIONS or FILE_PERMISSIONS). The
2079 USE_SOURCE_PERMISSIONS keyword mostly serves as a way of making
2080 the intended behavior clearer at the call site. It is an error
2081 to specify this option without INPUT.
2082 FILE_PERMISSIONS <permissions>...
2084 New in version 3.20.
2085 Use the specified permissions for the generated file.
2088 NEWLINE_STYLE <style>
2090 New in version 3.20.
2091 Specify the newline style for the generated file. Specify UNIX
2094 or LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n
2095 newlines.
2096 Exactly one CONTENT or INPUT option must be given. A specific OUTPUT
2098 file may be named by at most one invocation of file(GENERATE). Gener‐
2099 ated files are modified and their timestamp updated on subsequent cmake
2100 runs only if their content is changed.
2101 Note also that file(GENERATE) does not create the output file until the
2103 generation phase. The output file will not yet have been written when
2104 the file(GENERATE) command returns, it is written only after processing
2105 all of a project's CMakeLists.txt files.
2106 file(CONFIGURE OUTPUT output-file
2108 CONTENT content
2109 [ESCAPE_QUOTES] [@ONLY]
2110 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
2111 New in version 3.18.
2113 Generate an output file using the input given by CONTENT and substitute
2116 variable values referenced as @VAR@ or ${VAR} contained therein. The
2117 substitution rules behave the same as the configure_file() command. In
2118 order to match configure_file()'s behavior, generator expressions are
2119 not supported for both OUTPUT and CONTENT.
2120 The arguments are:
2122 OUTPUT <output-file>
2124 Specify the output file name to generate. A relative path is
2125 treated with respect to the value of CMAKE_CURRENT_BINARY_DIR.
2126 <output-file> does not support generator expressions.
2127 CONTENT <content>
2129 Use the content given explicitly as input. <content> does not
2130 support generator expressions.
2131 ESCAPE_QUOTES
2133 Escape any substituted quotes with backslashes (C-style).
2134 @ONLY Restrict variable replacement to references of the form @VAR@.
2136 This is useful for configuring scripts that use ${VAR} syntax.
2137 NEWLINE_STYLE <style>
2139 Specify the newline style for the output file. Specify UNIX or
2140 LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n new‐
2141 lines.
2142 Filesystem
2144 file(GLOB <variable>
2145 [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
2146 [<globbing-expressions>...])
2147 file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
2148 [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
2149 [<globbing-expressions>...])
2150 Generate a list of files that match the <globbing-expressions> and
2152 store it into the <variable>. Globbing expressions are similar to reg‐
2153 ular expressions, but much simpler. If RELATIVE flag is specified, the
2154 results will be returned as relative paths to the given path.
2155 Changed in version 3.6: The results will be ordered lexicographically.
2157 On Windows and macOS, globbing is case-insensitive even if the underly‐
2160 ing filesystem is case-sensitive (both filenames and globbing expres‐
2161 sions are converted to lowercase before matching). On other platforms,
2162 globbing is case-sensitive.
2163 New in version 3.3: By default GLOB lists directories - directories are
2165 omitted in result if LIST_DIRECTORIES is set to false.
2166 New in version 3.12: If the CONFIGURE_DEPENDS flag is specified, CMake
2169 will add logic to the main build system check target to rerun the
2170 flagged GLOB commands at build time. If any of the outputs change,
2171 CMake will regenerate the build system.
2172 NOTE:
2175 We do not recommend using GLOB to collect a list of source files
2176 from your source tree. If no CMakeLists.txt file changes when a
2177 source is added or removed then the generated build system cannot
2178 know when to ask CMake to regenerate. The CONFIGURE_DEPENDS flag
2179 may not work reliably on all generators, or if a new generator is
2180 added in the future that cannot support it, projects using it will
2181 be stuck. Even if CONFIGURE_DEPENDS works reliably, there is still a
2182 cost to perform the check on every rebuild.
2183 Examples of globbing expressions include:
2185 *.cxx - match all files with extension cxx
2187 *.vt? - match all files with extension vta,...,vtz
2188 f[3-5].txt - match files f3.txt, f4.txt, f5.txt
2189 The GLOB_RECURSE mode will traverse all the subdirectories of the
2191 matched directory and match the files. Subdirectories that are sym‐
2192 links are only traversed if FOLLOW_SYMLINKS is given or policy CMP0009
2193 is not set to NEW.
2194 New in version 3.3: By default GLOB_RECURSE omits directories from re‐
2196 sult list - setting LIST_DIRECTORIES to true adds directories to result
2197 list. If FOLLOW_SYMLINKS is given or policy CMP0009 is not set to NEW
2198 then LIST_DIRECTORIES treats symlinks as directories.
2199 Examples of recursive globbing include:
2202 /dir/*.py - match all python files in /dir and subdirectories
2204 file(RENAME <oldname> <newname>)
2206 Move a file or directory within a filesystem from <oldname> to <new‐
2208 name>, replacing the destination atomically.
2209 file(REMOVE [<files>...])
2211 file(REMOVE_RECURSE [<files>...])
2212 Remove the given files. The REMOVE_RECURSE mode will remove the given
2214 files and directories, also non-empty directories. No error is emitted
2215 if a given file does not exist. Relative input paths are evaluated
2216 with respect to the current source directory.
2217 Changed in version 3.15: Empty input paths are ignored with a warning.
2219 Previous versions of CMake interpreted empty string as a relative path
2220 with respect to the current directory and removed its contents.
2221 file(MAKE_DIRECTORY [<directories>...])
2224 Create the given directories and their parents as needed.
2226 file(<COPY|INSTALL> <files>... DESTINATION <dir>
2228 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS]
2229 [FILE_PERMISSIONS <permissions>...]
2230 [DIRECTORY_PERMISSIONS <permissions>...]
2231 [FOLLOW_SYMLINK_CHAIN]
2232 [FILES_MATCHING]
2233 [[PATTERN <pattern> | REGEX <regex>]
2234 [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
2235 The COPY signature copies files, directories, and symlinks to a desti‐
2237 nation folder. Relative input paths are evaluated with respect to the
2238 current source directory, and a relative destination is evaluated with
2239 respect to the current build directory. Copying preserves input file
2240 timestamps, and optimizes out a file if it exists at the destination
2241 with the same timestamp. Copying preserves input permissions unless
2242 explicit permissions or NO_SOURCE_PERMISSIONS are given (default is
2243 USE_SOURCE_PERMISSIONS).
2244 New in version 3.15: If FOLLOW_SYMLINK_CHAIN is specified, COPY will
2246 recursively resolve the symlinks at the paths given until a real file
2247 is found, and install a corresponding symlink in the destination for
2248 each symlink encountered. For each symlink that is installed, the reso‐
2249 lution is stripped of the directory, leaving only the filename, meaning
2250 that the new symlink points to a file in the same directory as the sym‐
2251 link. This feature is useful on some Unix systems, where libraries are
2252 installed as a chain of symlinks with version numbers, with less spe‐
2253 cific versions pointing to more specific versions. FOLLOW_SYM‐
2254 LINK_CHAIN will install all of these symlinks and the library itself
2255 into the destination directory. For example, if you have the following
2256 directory structure:
2257 • /opt/foo/lib/libfoo.so.1.2.3
2260 • /opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3
2262 • /opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2
2264 • /opt/foo/lib/libfoo.so -> libfoo.so.1
2266 and you do:
2268 file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)
2270 This will install all of the symlinks and libfoo.so.1.2.3 itself into
2272 lib.
2273 See the install(DIRECTORY) command for documentation of permissions,
2275 FILES_MATCHING, PATTERN, REGEX, and EXCLUDE options. Copying directo‐
2276 ries preserves the structure of their content even if options are used
2277 to select a subset of files.
2278 The INSTALL signature differs slightly from COPY: it prints status mes‐
2280 sages (subject to the CMAKE_INSTALL_MESSAGE variable), and
2281 NO_SOURCE_PERMISSIONS is default. Installation scripts generated by
2282 the install() command use this signature (with some undocumented op‐
2283 tions for internal use).
2284 file(SIZE <filename> <variable>)
2286 New in version 3.14.
2288 Determine the file size of the <filename> and put the result in <vari‐
2291 able> variable. Requires that <filename> is a valid path pointing to a
2292 file and is readable.
2293 file(READ_SYMLINK <linkname> <variable>)
2295 New in version 3.14.
2297 This subcommand queries the symlink <linkname> and stores the path it
2300 points to in the result <variable>. If <linkname> does not exist or is
2301 not a symlink, CMake issues a fatal error.
2302 Note that this command returns the raw symlink path and does not re‐
2304 solve a relative path. The following is an example of how to ensure
2305 that an absolute path is obtained:
2306 set(linkname "/path/to/foo.sym")
2308 file(READ_SYMLINK "${linkname}" result)
2309 if(NOT IS_ABSOLUTE "${result}")
2310 get_filename_component(dir "${linkname}" DIRECTORY)
2311 set(result "${dir}/${result}")
2312 endif()
2313 file(CREATE_LINK <original> <linkname>
2315 [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])
2316 New in version 3.14.
2318 Create a link <linkname> that points to <original>. It will be a hard
2321 link by default, but providing the SYMBOLIC option results in a sym‐
2322 bolic link instead. Hard links require that original exists and is a
2323 file, not a directory. If <linkname> already exists, it will be over‐
2324 written.
2325 The <result> variable, if specified, receives the status of the opera‐
2327 tion. It is set to 0 upon success or an error message otherwise. If
2328 RESULT is not specified and the operation fails, a fatal error is emit‐
2329 ted.
2330 Specifying COPY_ON_ERROR enables copying the file as a fallback if cre‐
2332 ating the link fails. It can be useful for handling situations such as
2333 <original> and <linkname> being on different drives or mount points,
2334 which would make them unable to support a hard link.
2335 file(CHMOD <files>... <directories>...
2337 [PERMISSIONS <permissions>...]
2338 [FILE_PERMISSIONS <permissions>...]
2339 [DIRECTORY_PERMISSIONS <permissions>...])
2340 New in version 3.19.
2342 Set the permissions for the <files>... and <directories>... specified.
2345 Valid permissions are OWNER_READ, OWNER_WRITE, OWNER_EXECUTE,
2346 GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE,
2347 WORLD_EXECUTE, SETUID, SETGID.
2348 Valid combination of keywords are:
2350 PERMISSIONS
2352 All items are changed.
2353 FILE_PERMISSIONS
2355 Only files are changed.
2356 DIRECTORY_PERMISSIONS
2358 Only directories are changed.
2359 PERMISSIONS and FILE_PERMISSIONS
2361 FILE_PERMISSIONS overrides PERMISSIONS for files.
2362 PERMISSIONS and DIRECTORY_PERMISSIONS
2364 DIRECTORY_PERMISSIONS overrides PERMISSIONS for directories.
2365 FILE_PERMISSIONS and DIRECTORY_PERMISSIONS
2367 Use FILE_PERMISSIONS for files and DIRECTORY_PERMISSIONS for di‐
2368 rectories.
2369 file(CHMOD_RECURSE <files>... <directories>...
2371 [PERMISSIONS <permissions>...]
2372 [FILE_PERMISSIONS <permissions>...]
2373 [DIRECTORY_PERMISSIONS <permissions>...])
2374 New in version 3.19.
2376 Same as CHMOD, but change the permissions of files and directories
2379 present in the <directories>... recursively.
2380 Path Conversion
2382 file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>])
2383 New in version 3.19.
2385 Compute the absolute path to an existing file or directory with sym‐
2388 links resolved.
2389 If the provided <path> is a relative path, it is evaluated relative to
2391 the given base directory <dir>. If no base directory is provided, the
2392 default base directory will be CMAKE_CURRENT_SOURCE_DIR.
2393 file(RELATIVE_PATH <variable> <directory> <file>)
2395 Compute the relative path from a <directory> to a <file> and store it
2397 in the <variable>.
2398 file(TO_CMAKE_PATH "<path>" <variable>)
2400 file(TO_NATIVE_PATH "<path>" <variable>)
2401 The TO_CMAKE_PATH mode converts a native <path> into a cmake-style path
2403 with forward-slashes (/). The input can be a single path or a system
2404 search path like $ENV{PATH}. A search path will be converted to a
2405 cmake-style list separated by ; characters.
2406 The TO_NATIVE_PATH mode converts a cmake-style <path> into a native
2408 path with platform-specific slashes (\ on Windows hosts and / else‐
2409 where).
2410 Always use double quotes around the <path> to be sure it is treated as
2412 a single argument to this command.
2413 Transfer
2415 file(DOWNLOAD <url> [<file>] [<options>...])
2416 file(UPLOAD <file> <url> [<options>...])
2417 The DOWNLOAD subcommand downloads the given <url> to a local <file>.
2419 The UPLOAD mode uploads a local <file> to a given <url>.
2420 New in version 3.19: If <file> is not specified for file(DOWNLOAD), the
2422 file is not saved. This can be useful if you want to know if a file
2423 can be downloaded (for example, to check that it exists) without actu‐
2424 ally saving it anywhere.
2425 Options to both DOWNLOAD and UPLOAD are:
2428 INACTIVITY_TIMEOUT <seconds>
2430 Terminate the operation after a period of inactivity.
2431 LOG <variable>
2433 Store a human-readable log of the operation in a variable.
2434 SHOW_PROGRESS
2436 Print progress information as status messages until the opera‐
2437 tion is complete.
2438 STATUS <variable>
2440 Store the resulting status of the operation in a variable. The
2441 status is a ; separated list of length 2. The first element is
2442 the numeric return value for the operation, and the second ele‐
2443 ment is a string value for the error. A 0 numeric error means
2444 no error in the operation.
2445 TIMEOUT <seconds>
2447 Terminate the operation after a given total time has elapsed.
2448 USERPWD <username>:<password>
2450 New in version 3.7.
2451 Set username and password for operation.
2454 HTTPHEADER <HTTP-header>
2456 New in version 3.7.
2457 HTTP header for operation. Suboption can be repeated several
2460 times.
2461 NETRC <level>
2463 New in version 3.11.
2464 Specify whether the .netrc file is to be used for operation. If
2467 this option is not specified, the value of the CMAKE_NETRC vari‐
2468 able will be used instead. Valid levels are:
2469 IGNORED
2471 The .netrc file is ignored. This is the default.
2472 OPTIONAL
2474 The .netrc file is optional, and information in the URL
2475 is preferred. The file will be scanned to find which
2476 ever information is not specified in the URL.
2477 REQUIRED
2479 The .netrc file is required, and information in the URL
2480 is ignored.
2481 NETRC_FILE <file>
2483 New in version 3.11.
2484 Specify an alternative .netrc file to the one in your home di‐
2487 rectory, if the NETRC level is OPTIONAL or REQUIRED. If this op‐
2488 tion is not specified, the value of the CMAKE_NETRC_FILE vari‐
2489 able will be used instead.
2490 If neither NETRC option is given CMake will check variables CMAKE_NETRC
2492 and CMAKE_NETRC_FILE, respectively.
2493 TLS_VERIFY <ON|OFF>
2495 Specify whether to verify the server certificate for https://
2496 URLs. The default is to not verify.
2497 New in version 3.18: Added support to file(UPLOAD).
2499 TLS_CAINFO <file>
2502 Specify a custom Certificate Authority file for https:// URLs.
2503 New in version 3.18: Added support to file(UPLOAD).
2505 For https:// URLs CMake must be built with OpenSSL support. TLS/SSL
2508 certificates are not checked by default. Set TLS_VERIFY to ON to check
2509 certificates. If neither TLS option is given CMake will check variables
2510 CMAKE_TLS_VERIFY and CMAKE_TLS_CAINFO, respectively.
2511 Additional options to DOWNLOAD are:
2513 EXPECTED_HASH ALGO=<value>
2515 Verify that the downloaded content hash matches the expected value,
2516 where ALGO is one of the algorithms supported by file(<HASH>). If
2517 it does not match, the operation fails with an error. It is an error
2518 to specify this if DOWNLOAD is not given a <file>.
2519 EXPECTED_MD5 <value>
2521 Historical short-hand for EXPECTED_HASH MD5=<value>. It is an
2522 error to specify this if DOWNLOAD is not given a <file>.
2523 Locking
2525 file(LOCK <path> [DIRECTORY] [RELEASE]
2526 [GUARD <FUNCTION|FILE|PROCESS>]
2527 [RESULT_VARIABLE <variable>]
2528 [TIMEOUT <seconds>])
2529 New in version 3.2.
2531 Lock a file specified by <path> if no DIRECTORY option present and file
2534 <path>/cmake.lock otherwise. File will be locked for scope defined by
2535 GUARD option (default value is PROCESS). RELEASE option can be used to
2536 unlock file explicitly. If option TIMEOUT is not specified CMake will
2537 wait until lock succeed or until fatal error occurs. If TIMEOUT is set
2538 to 0 lock will be tried once and result will be reported immediately.
2539 If TIMEOUT is not 0 CMake will try to lock file for the period speci‐
2540 fied by <seconds> value. Any errors will be interpreted as fatal if
2541 there is no RESULT_VARIABLE option. Otherwise result will be stored in
2542 <variable> and will be 0 on success or error message on failure.
2543 Note that lock is advisory - there is no guarantee that other processes
2545 will respect this lock, i.e. lock synchronize two or more CMake in‐
2546 stances sharing some modifiable resources. Similar logic applied to DI‐
2547 RECTORY option - locking parent directory doesn't prevent other LOCK
2548 commands to lock any child directory or file.
2549 Trying to lock file twice is not allowed. Any intermediate directories
2551 and file itself will be created if they not exist. GUARD and TIMEOUT
2552 options ignored on RELEASE operation.
2553 Archiving
2555 file(ARCHIVE_CREATE OUTPUT <archive>
2556 PATHS <paths>...
2557 [FORMAT <format>]
2558 [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]]
2559 [MTIME <mtime>]
2560 [VERBOSE])
2561 New in version 3.18.
2563 Creates the specified <archive> file with the files and directories
2566 listed in <paths>. Note that <paths> must list actual files or direc‐
2567 tories, wildcards are not supported.
2568 Use the FORMAT option to specify the archive format. Supported values
2570 for <format> are 7zip, gnutar, pax, paxr, raw and zip. If FORMAT is
2571 not given, the default format is paxr.
2572 Some archive formats allow the type of compression to be specified.
2574 The 7zip and zip archive formats already imply a specific type of com‐
2575 pression. The other formats use no compression by default, but can be
2576 directed to do so with the COMPRESSION option. Valid values for <com‐
2577 pression> are None, BZip2, GZip, XZ, and Zstd.
2578 New in version 3.19: The compression level can be specified with the
2580 COMPRESSION_LEVEL option. The <compression-level> should be between
2581 0-9, with the default being 0. The COMPRESSION option must be present
2582 when COMPRESSION_LEVEL is given.
2583 NOTE:
2586 With FORMAT set to raw only one file will be compressed with the
2587 compression type specified by COMPRESSION.
2588 The VERBOSE option enables verbose output for the archive operation.
2590 To specify the modification time recorded in tarball entries, use the
2592 MTIME option.
2593 file(ARCHIVE_EXTRACT INPUT <archive>
2595 [DESTINATION <dir>]
2596 [PATTERNS <patterns>...]
2597 [LIST_ONLY]
2598 [VERBOSE])
2599 New in version 3.18.
2601 Extracts or lists the content of the specified <archive>.
2604 The directory where the content of the archive will be extracted to can
2606 be specified using the DESTINATION option. If the directory does not
2607 exist, it will be created. If DESTINATION is not given, the current
2608 binary directory will be used.
2609 If required, you may select which files and directories to list or ex‐
2611 tract from the archive using the specified <patterns>. Wildcards are
2612 supported. If the PATTERNS option is not given, the entire archive
2613 will be listed or extracted.
2614 LIST_ONLY will list the files in the archive rather than extract them.
2616 With VERBOSE, the command will produce verbose output.
2618 find_file
2620 A short-hand signature is:
2621 find_file (<VAR> name1 [path1 path2 ...])
2623 The general signature is:
2625 find_file (
2627 <VAR>
2628 name | NAMES name1 [name2 ...]
2629 [HINTS path1 [path2 ... ENV var]]
2630 [PATHS path1 [path2 ... ENV var]]
2631 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2632 [DOC "cache documentation string"]
2633 [REQUIRED]
2634 [NO_DEFAULT_PATH]
2635 [NO_PACKAGE_ROOT_PATH]
2636 [NO_CMAKE_PATH]
2637 [NO_CMAKE_ENVIRONMENT_PATH]
2638 [NO_SYSTEM_ENVIRONMENT_PATH]
2639 [NO_CMAKE_SYSTEM_PATH]
2640 [CMAKE_FIND_ROOT_PATH_BOTH |
2641 ONLY_CMAKE_FIND_ROOT_PATH |
2642 NO_CMAKE_FIND_ROOT_PATH]
2643 )
2644 This command is used to find a full path to named file. A cache entry
2646 named by <VAR> is created to store the result of this command. If the
2647 full path to a file is found the result is stored in the variable and
2648 the search will not be repeated unless the variable is cleared. If
2649 nothing is found, the result will be <VAR>-NOTFOUND.
2650 Options include:
2652 NAMES Specify one or more possible names for the full path to a file.
2654 When using this to specify names with and without a version suf‐
2656 fix, we recommend specifying the unversioned name first so that
2657 locally-built packages can be found before those provided by
2658 distributions.
2659 HINTS, PATHS
2661 Specify directories to search in addition to the default loca‐
2662 tions. The ENV var sub-option reads paths from a system envi‐
2663 ronment variable.
2664 PATH_SUFFIXES
2666 Specify additional subdirectories to check below each directory
2667 location otherwise considered.
2668 DOC Specify the documentation string for the <VAR> cache entry.
2670 REQUIRED
2672 New in version 3.18.
2673 Stop processing with an error message if nothing is found, oth‐
2676 erwise the search will be attempted again the next time
2677 find_file is invoked with the same variable.
2678 If NO_DEFAULT_PATH is specified, then no additional paths are added to
2680 the search. If NO_DEFAULT_PATH is not specified, the search process is
2681 as follows:
2682 1. New in version 3.12: If called from within a find module or any
2684 other script loaded by a call to find_package(<PackageName>), search
2685 prefixes unique to the current package being found. Specifically,
2686 look in the <PackageName>_ROOT CMake variable and the <Package‐
2687 Name>_ROOT environment variable. The package root variables are
2688 maintained as a stack, so if called from nested find modules or con‐
2689 fig packages, root paths from the parent's find module or config
2690 package will be searched after paths from the current module or
2691 package. In other words, the search order would be <CurrentPack‐
2692 age>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT,
2693 ENV{<ParentPackage>_ROOT}, etc. This can be skipped if NO_PACK‐
2694 AGE_ROOT_PATH is passed or by setting the CMAKE_FIND_USE_PACK‐
2695 AGE_ROOT_PATH to FALSE. See policy CMP0074.
2696 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2699 <prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
2700 variable and the <PackageName>_ROOT environment variable if called
2701 from within a find module loaded by find_package(<PackageName>)
2702 2. Search paths specified in cmake-specific cache variables. These are
2704 intended to be used on the command line with a -DVAR=value. The
2705 values are interpreted as semicolon-separated lists. This can be
2706 skipped if NO_CMAKE_PATH is passed or by setting the
2707 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
2708 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2710 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2711 • CMAKE_INCLUDE_PATH
2713 • CMAKE_FRAMEWORK_PATH
2715 3. Search paths specified in cmake-specific environment variables.
2717 These are intended to be set in the user's shell configuration, and
2718 therefore use the host's native path separator (; on Windows and :
2719 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2720 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
2721 FALSE.
2722 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2724 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2725 • CMAKE_INCLUDE_PATH
2727 • CMAKE_FRAMEWORK_PATH
2729 4. Search the paths specified by the HINTS option. These should be
2731 paths computed by system introspection, such as a hint provided by
2732 the location of another item already found. Hard-coded guesses
2733 should be specified with the PATHS option.
2734 5. Search the standard system environment variables. This can be
2736 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
2737 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
2738 • The directories in INCLUDE and PATH.
2740 • On Windows hosts: <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHI‐
2742 TECTURE is set, and <prefix>/include for each <prefix>/[s]bin in
2743 PATH, and <entry>/include for other entries in PATH.
2744 6. Search cmake variables defined in the Platform files for the current
2746 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
2747 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
2748 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2750 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2751 • CMAKE_SYSTEM_INCLUDE_PATH
2753 • CMAKE_SYSTEM_FRAMEWORK_PATH
2755 The platform paths that these variables contain are locations that
2757 typically include installed software. An example being /usr/local
2758 for UNIX based platforms.
2759 7. Search the paths specified by the PATHS option or in the short-hand
2761 version of the command. These are typically hard-coded guesses.
2762 New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to
2764 globally disable various search locations.
2765 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
2768 determine the order of preference between Apple-style and unix-style
2769 package components.
2770 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
2772 ries to be prepended to all other search directories. This effectively
2773 "re-roots" the entire search under given locations. Paths which are
2774 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
2775 ing, because that variable is always a path on the host system. By de‐
2776 fault the CMAKE_FIND_ROOT_PATH is empty.
2777 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
2779 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
2780 fects. See the documentation for that variable for more.
2781 These variables are especially useful when cross-compiling to point to
2783 the root directory of the target environment and CMake will search
2784 there too. By default at first the directories listed in
2785 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
2786 searched, and then the non-rooted directories will be searched. The
2787 default behavior can be adjusted by setting
2788 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually over‐
2789 ridden on a per-call basis using options:
2790 CMAKE_FIND_ROOT_PATH_BOTH
2792 Search in the order described above.
2793 NO_CMAKE_FIND_ROOT_PATH
2795 Do not use the CMAKE_FIND_ROOT_PATH variable.
2796 ONLY_CMAKE_FIND_ROOT_PATH
2798 Search only the re-rooted directories and directories below
2799 CMAKE_STAGING_PREFIX.
2800 The default search order is designed to be most-specific to least-spe‐
2802 cific for common use cases. Projects may override the order by simply
2803 calling the command multiple times and using the NO_* options:
2804 find_file (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2806 find_file (<VAR> NAMES name)
2807 Once one of the calls succeeds the result variable will be set and
2809 stored in the cache so that no call will search again.
2810 find_library
2812 A short-hand signature is:
2813 find_library (<VAR> name1 [path1 path2 ...])
2815 The general signature is:
2817 find_library (
2819 <VAR>
2820 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
2821 [HINTS path1 [path2 ... ENV var]]
2822 [PATHS path1 [path2 ... ENV var]]
2823 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2824 [DOC "cache documentation string"]
2825 [REQUIRED]
2826 [NO_DEFAULT_PATH]
2827 [NO_PACKAGE_ROOT_PATH]
2828 [NO_CMAKE_PATH]
2829 [NO_CMAKE_ENVIRONMENT_PATH]
2830 [NO_SYSTEM_ENVIRONMENT_PATH]
2831 [NO_CMAKE_SYSTEM_PATH]
2832 [CMAKE_FIND_ROOT_PATH_BOTH |
2833 ONLY_CMAKE_FIND_ROOT_PATH |
2834 NO_CMAKE_FIND_ROOT_PATH]
2835 )
2836 This command is used to find a library. A cache entry named by <VAR>
2838 is created to store the result of this command. If the library is
2839 found the result is stored in the variable and the search will not be
2840 repeated unless the variable is cleared. If nothing is found, the re‐
2841 sult will be <VAR>-NOTFOUND.
2842 Options include:
2844 NAMES Specify one or more possible names for the library.
2846 When using this to specify names with and without a version suf‐
2848 fix, we recommend specifying the unversioned name first so that
2849 locally-built packages can be found before those provided by
2850 distributions.
2851 HINTS, PATHS
2853 Specify directories to search in addition to the default loca‐
2854 tions. The ENV var sub-option reads paths from a system envi‐
2855 ronment variable.
2856 PATH_SUFFIXES
2858 Specify additional subdirectories to check below each directory
2859 location otherwise considered.
2860 DOC Specify the documentation string for the <VAR> cache entry.
2862 REQUIRED
2864 New in version 3.18.
2865 Stop processing with an error message if nothing is found, oth‐
2868 erwise the search will be attempted again the next time find_li‐
2869 brary is invoked with the same variable.
2870 If NO_DEFAULT_PATH is specified, then no additional paths are added to
2872 the search. If NO_DEFAULT_PATH is not specified, the search process is
2873 as follows:
2874 1. New in version 3.12: If called from within a find module or any
2876 other script loaded by a call to find_package(<PackageName>), search
2877 prefixes unique to the current package being found. Specifically,
2878 look in the <PackageName>_ROOT CMake variable and the <Package‐
2879 Name>_ROOT environment variable. The package root variables are
2880 maintained as a stack, so if called from nested find modules or con‐
2881 fig packages, root paths from the parent's find module or config
2882 package will be searched after paths from the current module or
2883 package. In other words, the search order would be <CurrentPack‐
2884 age>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT,
2885 ENV{<ParentPackage>_ROOT}, etc. This can be skipped if NO_PACK‐
2886 AGE_ROOT_PATH is passed or by setting the CMAKE_FIND_USE_PACK‐
2887 AGE_ROOT_PATH to FALSE. See policy CMP0074.
2888 • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2891 <prefix>/lib for each <prefix> in the <PackageName>_ROOT CMake
2892 variable and the <PackageName>_ROOT environment variable if called
2893 from within a find module loaded by find_package(<PackageName>)
2894 2. Search paths specified in cmake-specific cache variables. These are
2896 intended to be used on the command line with a -DVAR=value. The
2897 values are interpreted as semicolon-separated lists. This can be
2898 skipped if NO_CMAKE_PATH is passed or by setting the
2899 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
2900 • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2902 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
2903 • CMAKE_LIBRARY_PATH
2905 • CMAKE_FRAMEWORK_PATH
2907 3. Search paths specified in cmake-specific environment variables.
2909 These are intended to be set in the user's shell configuration, and
2910 therefore use the host's native path separator (; on Windows and :
2911 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2912 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
2913 FALSE.
2914 • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2916 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
2917 • CMAKE_LIBRARY_PATH
2919 • CMAKE_FRAMEWORK_PATH
2921 4. Search the paths specified by the HINTS option. These should be
2923 paths computed by system introspection, such as a hint provided by
2924 the location of another item already found. Hard-coded guesses
2925 should be specified with the PATHS option.
2926 5. Search the standard system environment variables. This can be
2928 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
2929 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
2930 • The directories in LIB and PATH.
2932 • On Windows hosts: <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITEC‐
2934 TURE is set, and <prefix>/lib for each <prefix>/[s]bin in PATH,
2935 and <entry>/lib for other entries in PATH.
2936 6. Search cmake variables defined in the Platform files for the current
2938 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
2939 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
2940 • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2942 <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2943 • CMAKE_SYSTEM_LIBRARY_PATH
2945 • CMAKE_SYSTEM_FRAMEWORK_PATH
2947 The platform paths that these variables contain are locations that
2949 typically include installed software. An example being /usr/local
2950 for UNIX based platforms.
2951 7. Search the paths specified by the PATHS option or in the short-hand
2953 version of the command. These are typically hard-coded guesses.
2954 New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to
2956 globally disable various search locations.
2957 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
2960 determine the order of preference between Apple-style and unix-style
2961 package components.
2962 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
2964 ries to be prepended to all other search directories. This effectively
2965 "re-roots" the entire search under given locations. Paths which are
2966 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
2967 ing, because that variable is always a path on the host system. By de‐
2968 fault the CMAKE_FIND_ROOT_PATH is empty.
2969 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
2971 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
2972 fects. See the documentation for that variable for more.
2973 These variables are especially useful when cross-compiling to point to
2975 the root directory of the target environment and CMake will search
2976 there too. By default at first the directories listed in
2977 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
2978 searched, and then the non-rooted directories will be searched. The
2979 default behavior can be adjusted by setting
2980 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY. This behavior can be manually over‐
2981 ridden on a per-call basis using options:
2982 CMAKE_FIND_ROOT_PATH_BOTH
2984 Search in the order described above.
2985 NO_CMAKE_FIND_ROOT_PATH
2987 Do not use the CMAKE_FIND_ROOT_PATH variable.
2988 ONLY_CMAKE_FIND_ROOT_PATH
2990 Search only the re-rooted directories and directories below
2991 CMAKE_STAGING_PREFIX.
2992 The default search order is designed to be most-specific to least-spe‐
2994 cific for common use cases. Projects may override the order by simply
2995 calling the command multiple times and using the NO_* options:
2996 find_library (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2998 find_library (<VAR> NAMES name)
2999 Once one of the calls succeeds the result variable will be set and
3001 stored in the cache so that no call will search again.
3002 When more than one value is given to the NAMES option this command by
3004 default will consider one name at a time and search every directory for
3005 it. The NAMES_PER_DIR option tells this command to consider one direc‐
3006 tory at a time and search for all names in it.
3007 Each library name given to the NAMES option is first considered as a
3009 library file name and then considered with platform-specific prefixes
3010 (e.g. lib) and suffixes (e.g. .so). Therefore one may specify library
3011 file names such as libfoo.a directly. This can be used to locate
3012 static libraries on UNIX-like systems.
3013 If the library found is a framework, then <VAR> will be set to the full
3015 path to the framework <fullPath>/A.framework. When a full path to a
3016 framework is used as a library, CMake will use a -framework A, and a
3017 -F<fullPath> to link the framework to the target.
3018 If the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable is set all search
3020 paths will be tested as normal, with the suffix appended, and with all
3021 matches of lib/ replaced with lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUF‐
3022 FIX}/. This variable overrides the FIND_LIBRARY_USE_LIB32_PATHS,
3023 FIND_LIBRARY_USE_LIBX32_PATHS, and FIND_LIBRARY_USE_LIB64_PATHS global
3024 properties.
3025 If the FIND_LIBRARY_USE_LIB32_PATHS global property is set all search
3027 paths will be tested as normal, with 32/ appended, and with all matches
3028 of lib/ replaced with lib32/. This property is automatically set for
3029 the platforms that are known to need it if at least one of the lan‐
3030 guages supported by the project() command is enabled.
3031 If the FIND_LIBRARY_USE_LIBX32_PATHS global property is set all search
3033 paths will be tested as normal, with x32/ appended, and with all
3034 matches of lib/ replaced with libx32/. This property is automatically
3035 set for the platforms that are known to need it if at least one of the
3036 languages supported by the project() command is enabled.
3037 If the FIND_LIBRARY_USE_LIB64_PATHS global property is set all search
3039 paths will be tested as normal, with 64/ appended, and with all matches
3040 of lib/ replaced with lib64/. This property is automatically set for
3041 the platforms that are known to need it if at least one of the lan‐
3042 guages supported by the project() command is enabled.
3043 find_package
3045 Find an external project, and load its settings.
3046 Basic Signature and Module Mode
3048 find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
3049 [REQUIRED] [[COMPONENTS] [components...]]
3050 [OPTIONAL_COMPONENTS components...]
3051 [NO_POLICY_SCOPE])
3052 Finds and loads settings from an external project. <PackageName>_FOUND
3054 will be set to indicate whether the package was found. When the pack‐
3055 age is found package-specific information is provided through variables
3056 and Imported Targets documented by the package itself. The QUIET op‐
3057 tion disables informational messages, including those indicating that
3058 the package cannot be found if it is not REQUIRED. The REQUIRED option
3059 stops processing with an error message if the package cannot be found.
3060 A package-specific list of required components may be listed after the
3062 COMPONENTS option (or after the REQUIRED option if present). Addi‐
3063 tional optional components may be listed after OPTIONAL_COMPONENTS.
3064 Available components and their influence on whether a package is con‐
3065 sidered to be found are defined by the target package.
3066 The [version] argument requests a version with which the package found
3068 should be compatible. There are two possible forms in which it may be
3069 specified:
3070 • A single version with the format major[.minor[.patch[.tweak]]].
3072 • A version range with the format versionMin...[<]versionMax where
3074 versionMin and versionMax have the same format as the single ver‐
3075 sion. By default, both end points are included. By specifying <,
3076 the upper end point will be excluded. Version ranges are only
3077 supported with CMake 3.19 or later.
3078 The EXACT option requests that the version be matched exactly. This op‐
3080 tion is incompatible with the specification of a version range.
3081 If no [version] and/or component list is given to a recursive invoca‐
3083 tion inside a find-module, the corresponding arguments are forwarded
3084 automatically from the outer call (including the EXACT flag for [ver‐
3085 sion]). Version support is currently provided only on a pack‐
3086 age-by-package basis (see the Version Selection section below). When a
3087 version range is specified but the package is only designed to expect a
3088 single version, the package will ignore the upper end point of the
3089 range and only take the single version at the lower end of the range
3090 into account.
3091 See the cmake_policy() command documentation for discussion of the
3093 NO_POLICY_SCOPE option.
3094 The command has two modes by which it searches for packages: "Module"
3096 mode and "Config" mode. The above signature selects Module mode. If
3097 no module is found the command falls back to Config mode, described be‐
3098 low. This fall back is disabled if the MODULE option is given.
3099 In Module mode, CMake searches for a file called Find<Package‐
3101 Name>.cmake. The file is first searched in the CMAKE_MODULE_PATH, then
3102 among the Find Modules provided by the CMake installation. If the file
3103 is found, it is read and processed by CMake. It is responsible for
3104 finding the package, checking the version, and producing any needed
3105 messages. Some find-modules provide limited or no support for version‐
3106 ing; check the module documentation.
3107 If the MODULE option is not specified in the above signature, CMake
3109 first searches for the package using Module mode. Then, if the package
3110 is not found, it searches again using Config mode. A user may set the
3111 variable CMAKE_FIND_PACKAGE_PREFER_CONFIG to TRUE to direct CMake first
3112 search using Config mode before falling back to Module mode.
3113 Full Signature and Config Mode
3115 User code should generally look for packages using the above basic sig‐
3116 nature. The remainder of this command documentation specifies the full
3117 command signature and details of the search process. Project maintain‐
3118 ers wishing to provide a package to be found by this command are en‐
3119 couraged to read on.
3120 The complete Config mode command signature is
3122 find_package(<PackageName> [version] [EXACT] [QUIET]
3124 [REQUIRED] [[COMPONENTS] [components...]]
3125 [OPTIONAL_COMPONENTS components...]
3126 [CONFIG|NO_MODULE]
3127 [NO_POLICY_SCOPE]
3128 [NAMES name1 [name2 ...]]
3129 [CONFIGS config1 [config2 ...]]
3130 [HINTS path1 [path2 ... ]]
3131 [PATHS path1 [path2 ... ]]
3132 [PATH_SUFFIXES suffix1 [suffix2 ...]]
3133 [NO_DEFAULT_PATH]
3134 [NO_PACKAGE_ROOT_PATH]
3135 [NO_CMAKE_PATH]
3136 [NO_CMAKE_ENVIRONMENT_PATH]
3137 [NO_SYSTEM_ENVIRONMENT_PATH]
3138 [NO_CMAKE_PACKAGE_REGISTRY]
3139 [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
3140 [NO_CMAKE_SYSTEM_PATH]
3141 [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
3142 [CMAKE_FIND_ROOT_PATH_BOTH |
3143 ONLY_CMAKE_FIND_ROOT_PATH |
3144 NO_CMAKE_FIND_ROOT_PATH])
3145 The CONFIG option, the synonymous NO_MODULE option, or the use of op‐
3147 tions not specified in the basic signature all enforce pure Config
3148 mode. In pure Config mode, the command skips Module mode search and
3149 proceeds at once with Config mode search.
3150 Config mode search attempts to locate a configuration file provided by
3152 the package to be found. A cache entry called <PackageName>_DIR is
3153 created to hold the directory containing the file. By default the com‐
3154 mand searches for a package with the name <PackageName>. If the NAMES
3155 option is given the names following it are used instead of <Package‐
3156 Name>. The command searches for a file called <PackageName>Con‐
3157 fig.cmake or <lower-case-package-name>-config.cmake for each name spec‐
3158 ified. A replacement set of possible configuration file names may be
3159 given using the CONFIGS option. The search procedure is specified be‐
3160 low. Once found, the configuration file is read and processed by
3161 CMake. Since the file is provided by the package it already knows the
3162 location of package contents. The full path to the configuration file
3163 is stored in the cmake variable <PackageName>_CONFIG.
3164 All configuration files which have been considered by CMake while
3166 searching for an installation of the package with an appropriate ver‐
3167 sion are stored in the cmake variable <PackageName>_CONSIDERED_CONFIGS,
3168 the associated versions in <PackageName>_CONSIDERED_VERSIONS.
3169 If the package configuration file cannot be found CMake will generate
3171 an error describing the problem unless the QUIET argument is specified.
3172 If REQUIRED is specified and the package is not found a fatal error is
3173 generated and the configure step stops executing. If <PackageName>_DIR
3174 has been set to a directory not containing a configuration file CMake
3175 will ignore it and search from scratch.
3176 Package maintainers providing CMake package configuration files are en‐
3178 couraged to name and install them such that the Search Procedure out‐
3179 lined below will find them without requiring use of additional options.
3180 Version Selection
3182 When the [version] argument is given, Config mode will only find a ver‐
3183 sion of the package that claims compatibility with the requested ver‐
3184 sion (see format specification). If the EXACT option is given, only a
3185 version of the package claiming an exact match of the requested version
3186 may be found. CMake does not establish any convention for the meaning
3187 of version numbers. Package version numbers are checked by "version"
3188 files provided by the packages themselves. For a candidate package
3189 configuration file <config-file>.cmake the corresponding version file
3190 is located next to it and named either <config-file>-version.cmake or
3191 <config-file>Version.cmake. If no such version file is available then
3192 the configuration file is assumed to not be compatible with any re‐
3193 quested version. A basic version file containing generic version
3194 matching code can be created using the CMakePackageConfigHelpers mod‐
3195 ule. When a version file is found it is loaded to check the requested
3196 version number. The version file is loaded in a nested scope in which
3197 the following variables have been defined:
3198 PACKAGE_FIND_NAME
3200 The <PackageName>
3201 PACKAGE_FIND_VERSION
3203 Full requested version string
3204 PACKAGE_FIND_VERSION_MAJOR
3206 Major version if requested, else 0
3207 PACKAGE_FIND_VERSION_MINOR
3209 Minor version if requested, else 0
3210 PACKAGE_FIND_VERSION_PATCH
3212 Patch version if requested, else 0
3213 PACKAGE_FIND_VERSION_TWEAK
3215 Tweak version if requested, else 0
3216 PACKAGE_FIND_VERSION_COUNT
3218 Number of version components, 0 to 4
3219 When a version range is specified, the above version variables will
3221 hold values based on the lower end of the version range. This is to
3222 preserve compatibility with packages that have not been implemented to
3223 expect version ranges. In addition, the version range will be de‐
3224 scribed by the following variables:
3225 PACKAGE_FIND_VERSION_RANGE
3227 Full requested version range string
3228 PACKAGE_FIND_VERSION_RANGE_MIN
3230 This specifies whether the lower end point of the version range
3231 should be included or excluded. Currently, the only supported
3232 value for this variable is INCLUDE.
3233 PACKAGE_FIND_VERSION_RANGE_MAX
3235 This specifies whether the upper end point of the version range
3236 should be included or excluded. The supported values for this
3237 variable are INCLUDE and EXCLUDE.
3238 PACKAGE_FIND_VERSION_MIN
3240 Full requested version string of the lower end point of the
3241 range
3242 PACKAGE_FIND_VERSION_MIN_MAJOR
3244 Major version of the lower end point if requested, else 0
3245 PACKAGE_FIND_VERSION_MIN_MINOR
3247 Minor version of the lower end point if requested, else 0
3248 PACKAGE_FIND_VERSION_MIN_PATCH
3250 Patch version of the lower end point if requested, else 0
3251 PACKAGE_FIND_VERSION_MIN_TWEAK
3253 Tweak version of the lower end point if requested, else 0
3254 PACKAGE_FIND_VERSION_MIN_COUNT
3256 Number of version components of the lower end point, 0 to 4
3257 PACKAGE_FIND_VERSION_MAX
3259 Full requested version string of the upper end point of the
3260 range
3261 PACKAGE_FIND_VERSION_MAX_MAJOR
3263 Major version of the upper end point if requested, else 0
3264 PACKAGE_FIND_VERSION_MAX_MINOR
3266 Minor version of the upper end point if requested, else 0
3267 PACKAGE_FIND_VERSION_MAX_PATCH
3269 Patch version of the upper end point if requested, else 0
3270 PACKAGE_FIND_VERSION_MAX_TWEAK
3272 Tweak version of the upper end point if requested, else 0
3273 PACKAGE_FIND_VERSION_MAX_COUNT
3275 Number of version components of the upper end point, 0 to 4
3276 Regardless of whether a single version or a version range is specified,
3278 the variable PACKAGE_FIND_VERSION_COMPLETE will be defined and will
3279 hold the full requested version string as specified.
3280 The version file checks whether it satisfies the requested version and
3282 sets these variables:
3283 PACKAGE_VERSION
3285 Full provided version string
3286 PACKAGE_VERSION_EXACT
3288 True if version is exact match
3289 PACKAGE_VERSION_COMPATIBLE
3291 True if version is compatible
3292 PACKAGE_VERSION_UNSUITABLE
3294 True if unsuitable as any version
3295 These variables are checked by the find_package command to determine
3297 whether the configuration file provides an acceptable version. They
3298 are not available after the find_package call returns. If the version
3299 is acceptable the following variables are set:
3300 <PackageName>_VERSION
3302 Full provided version string
3303 <PackageName>_VERSION_MAJOR
3305 Major version if provided, else 0
3306 <PackageName>_VERSION_MINOR
3308 Minor version if provided, else 0
3309 <PackageName>_VERSION_PATCH
3311 Patch version if provided, else 0
3312 <PackageName>_VERSION_TWEAK
3314 Tweak version if provided, else 0
3315 <PackageName>_VERSION_COUNT
3317 Number of version components, 0 to 4
3318 and the corresponding package configuration file is loaded. When mul‐
3320 tiple package configuration files are available whose version files
3321 claim compatibility with the version requested it is unspecified which
3322 one is chosen: unless the variable CMAKE_FIND_PACKAGE_SORT_ORDER is set
3323 no attempt is made to choose a highest or closest version number.
3324 To control the order in which find_package checks for compatibility use
3326 the two variables CMAKE_FIND_PACKAGE_SORT_ORDER and CMAKE_FIND_PACK‐
3327 AGE_SORT_DIRECTION. For instance in order to select the highest ver‐
3328 sion one can set
3329 SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
3331 SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
3332 before calling find_package.
3334 Search Procedure
3336 CMake constructs a set of possible installation prefixes for the pack‐
3337 age. Under each prefix several directories are searched for a configu‐
3338 ration file. The tables below show the directories searched. Each en‐
3339 try is meant for installation trees following Windows (W), UNIX (U), or
3340 Apple (A) conventions:
3341 <prefix>/ (W)
3343 <prefix>/(cmake|CMake)/ (W)
3344 <prefix>/<name>*/ (W)
3345 <prefix>/<name>*/(cmake|CMake)/ (W)
3346 <prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/ (U)
3347 <prefix>/(lib/<arch>|lib*|share)/<name>*/ (U)
3348 <prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (U)
3349 <prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/ (W/U)
3350 <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ (W/U)
3351 <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U)
3352 On systems supporting macOS FRAMEWORK and BUNDLE, the following direc‐
3354 tories are searched for Frameworks or Application Bundles containing a
3355 configuration file:
3356 <prefix>/<name>.framework/Resources/ (A)
3358 <prefix>/<name>.framework/Resources/CMake/ (A)
3359 <prefix>/<name>.framework/Versions/*/Resources/ (A)
3360 <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A)
3361 <prefix>/<name>.app/Contents/Resources/ (A)
3362 <prefix>/<name>.app/Contents/Resources/CMake/ (A)
3363 In all cases the <name> is treated as case-insensitive and corresponds
3365 to any of the names specified (<PackageName> or names given by NAMES).
3366 Paths with lib/<arch> are enabled if the CMAKE_LIBRARY_ARCHITECTURE
3368 variable is set. lib* includes one or more of the values lib64, lib32,
3369 libx32 or lib (searched in that order).
3370 • Paths with lib64 are searched on 64 bit platforms if the FIND_LI‐
3372 BRARY_USE_LIB64_PATHS property is set to TRUE.
3373 • Paths with lib32 are searched on 32 bit platforms if the FIND_LI‐
3375 BRARY_USE_LIB32_PATHS property is set to TRUE.
3376 • Paths with libx32 are searched on platforms using the x32 ABI if the
3378 FIND_LIBRARY_USE_LIBX32_PATHS property is set to TRUE.
3379 • The lib path is always searched.
3381 If PATH_SUFFIXES is specified, the suffixes are appended to each (W) or
3383 (U) directory entry one-by-one.
3384 This set of directories is intended to work in cooperation with
3386 projects that provide configuration files in their installation trees.
3387 Directories above marked with (W) are intended for installations on
3388 Windows where the prefix may point at the top of an application's in‐
3389 stallation directory. Those marked with (U) are intended for installa‐
3390 tions on UNIX platforms where the prefix is shared by multiple pack‐
3391 ages. This is merely a convention, so all (W) and (U) directories are
3392 still searched on all platforms. Directories marked with (A) are in‐
3393 tended for installations on Apple platforms. The CMAKE_FIND_FRAMEWORK
3394 and CMAKE_FIND_APPBUNDLE variables determine the order of preference.
3395 The set of installation prefixes is constructed using the following
3397 steps. If NO_DEFAULT_PATH is specified all NO_* options are enabled.
3398 1. New in version 3.12: Search paths specified in the <Package‐
3400 Name>_ROOT CMake variable and the <PackageName>_ROOT environment
3401 variable, where <PackageName> is the package to be found. The pack‐
3402 age root variables are maintained as a stack so if called from
3403 within a find module, root paths from the parent's find module will
3404 also be searched after paths for the current package. This can be
3405 skipped if NO_PACKAGE_ROOT_PATH is passed or by setting the
3406 CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
3407 2. Search paths specified in cmake-specific cache variables. These are
3410 intended to be used on the command line with a -DVAR=value. The
3411 values are interpreted as semicolon-separated lists. This can be
3412 skipped if NO_CMAKE_PATH is passed or by setting the
3413 CMAKE_FIND_USE_CMAKE_PATH to FALSE:
3414 • CMAKE_PREFIX_PATH
3416 • CMAKE_FRAMEWORK_PATH
3418 • CMAKE_APPBUNDLE_PATH
3420 3. Search paths specified in cmake-specific environment variables.
3422 These are intended to be set in the user's shell configuration, and
3423 therefore use the host's native path separator (; on Windows and :
3424 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
3425 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
3426 FALSE:
3427 • <PackageName>_DIR
3429 • CMAKE_PREFIX_PATH
3431 • CMAKE_FRAMEWORK_PATH
3433 • CMAKE_APPBUNDLE_PATH
3435 4. Search paths specified by the HINTS option. These should be paths
3437 computed by system introspection, such as a hint provided by the lo‐
3438 cation of another item already found. Hard-coded guesses should be
3439 specified with the PATHS option.
3440 5. Search the standard system environment variables. This can be
3442 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
3443 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE. Path entries ending
3444 in /bin or /sbin are automatically converted to their parent direc‐
3445 tories:
3446 • PATH
3448 6. Search paths stored in the CMake User Package Registry. This can be
3450 skipped if NO_CMAKE_PACKAGE_REGISTRY is passed or by setting the
3451 variable CMAKE_FIND_USE_PACKAGE_REGISTRY to FALSE or the deprecated
3452 variable CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY to TRUE.
3453 See the cmake-packages(7) manual for details on the user package
3455 registry.
3456 7. Search cmake variables defined in the Platform files for the current
3458 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
3459 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE:
3460 • CMAKE_SYSTEM_PREFIX_PATH
3462 • CMAKE_SYSTEM_FRAMEWORK_PATH
3464 • CMAKE_SYSTEM_APPBUNDLE_PATH
3466 The platform paths that these variables contain are locations that
3468 typically include installed software. An example being /usr/local
3469 for UNIX based platforms.
3470 8. Search paths stored in the CMake System Package Registry. This can
3472 be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is passed or by set‐
3473 ting the CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variable to FALSE or
3474 the deprecated variable CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REG‐
3475 ISTRY to TRUE.
3476 See the cmake-packages(7) manual for details on the system package
3478 registry.
3479 9. Search paths specified by the PATHS option. These are typically
3481 hard-coded guesses.
3482 New in version 3.16: Added the CMAKE_FIND_USE_<CATEGORY>_PATH variables
3484 to globally disable various search locations.
3485 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
3488 ries to be prepended to all other search directories. This effectively
3489 "re-roots" the entire search under given locations. Paths which are
3490 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
3491 ing, because that variable is always a path on the host system. By de‐
3492 fault the CMAKE_FIND_ROOT_PATH is empty.
3493 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
3495 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
3496 fects. See the documentation for that variable for more.
3497 These variables are especially useful when cross-compiling to point to
3499 the root directory of the target environment and CMake will search
3500 there too. By default at first the directories listed in
3501 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
3502 searched, and then the non-rooted directories will be searched. The
3503 default behavior can be adjusted by setting
3504 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE. This behavior can be manually over‐
3505 ridden on a per-call basis using options:
3506 CMAKE_FIND_ROOT_PATH_BOTH
3508 Search in the order described above.
3509 NO_CMAKE_FIND_ROOT_PATH
3511 Do not use the CMAKE_FIND_ROOT_PATH variable.
3512 ONLY_CMAKE_FIND_ROOT_PATH
3514 Search only the re-rooted directories and directories below
3515 CMAKE_STAGING_PREFIX.
3516 The default search order is designed to be most-specific to least-spe‐
3518 cific for common use cases. Projects may override the order by simply
3519 calling the command multiple times and using the NO_* options:
3520 find_package (<PackageName> PATHS paths... NO_DEFAULT_PATH)
3522 find_package (<PackageName>)
3523 Once one of the calls succeeds the result variable will be set and
3525 stored in the cache so that no call will search again.
3526 By default the value stored in the result variable will be the path at
3528 which the file is found. The CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS vari‐
3529 able may be set to TRUE before calling find_package in order to resolve
3530 symbolic links and store the real path to the file.
3531 Every non-REQUIRED find_package call can be disabled by setting the
3533 CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable to TRUE.
3534 Package File Interface Variables
3536 When loading a find module or package configuration file find_package
3537 defines variables to provide information about the call arguments (and
3538 restores their original state before returning):
3539 CMAKE_FIND_PACKAGE_NAME
3541 The <PackageName> which is searched for
3542 <PackageName>_FIND_REQUIRED
3544 True if REQUIRED option was given
3545 <PackageName>_FIND_QUIETLY
3547 True if QUIET option was given
3548 <PackageName>_FIND_VERSION
3550 Full requested version string
3551 <PackageName>_FIND_VERSION_MAJOR
3553 Major version if requested, else 0
3554 <PackageName>_FIND_VERSION_MINOR
3556 Minor version if requested, else 0
3557 <PackageName>_FIND_VERSION_PATCH
3559 Patch version if requested, else 0
3560 <PackageName>_FIND_VERSION_TWEAK
3562 Tweak version if requested, else 0
3563 <PackageName>_FIND_VERSION_COUNT
3565 Number of version components, 0 to 4
3566 <PackageName>_FIND_VERSION_EXACT
3568 True if EXACT option was given
3569 <PackageName>_FIND_COMPONENTS
3571 List of requested components
3572 <PackageName>_FIND_REQUIRED_<c>
3574 True if component <c> is required, false if component <c> is op‐
3575 tional
3576 When a version range is specified, the above version variables will
3578 hold values based on the lower end of the version range. This is to
3579 preserve compatibility with packages that have not been implemented to
3580 expect version ranges. In addition, the version range will be de‐
3581 scribed by the following variables:
3582 <PackageName>_FIND_VERSION_RANGE
3584 Full requested version range string
3585 <PackageName>_FIND_VERSION_RANGE_MIN
3587 This specifies whether the lower end point of the version range
3588 is included or excluded. Currently, INCLUDE is the only sup‐
3589 ported value.
3590 <PackageName>_FIND_VERSION_RANGE_MAX
3592 This specifies whether the upper end point of the version range
3593 is included or excluded. The possible values for this variable
3594 are INCLUDE or EXCLUDE.
3595 <PackageName>_FIND_VERSION_MIN
3597 Full requested version string of the lower end point of the
3598 range
3599 <PackageName>_FIND_VERSION_MIN_MAJOR
3601 Major version of the lower end point if requested, else 0
3602 <PackageName>_FIND_VERSION_MIN_MINOR
3604 Minor version of the lower end point if requested, else 0
3605 <PackageName>_FIND_VERSION_MIN_PATCH
3607 Patch version of the lower end point if requested, else 0
3608 <PackageName>_FIND_VERSION_MIN_TWEAK
3610 Tweak version of the lower end point if requested, else 0
3611 <PackageName>_FIND_VERSION_MIN_COUNT
3613 Number of version components of the lower end point, 0 to 4
3614 <PackageName>_FIND_VERSION_MAX
3616 Full requested version string of the upper end point of the
3617 range
3618 <PackageName>_FIND_VERSION_MAX_MAJOR
3620 Major version of the upper end point if requested, else 0
3621 <PackageName>_FIND_VERSION_MAX_MINOR
3623 Minor version of the upper end point if requested, else 0
3624 <PackageName>_FIND_VERSION_MAX_PATCH
3626 Patch version of the upper end point if requested, else 0
3627 <PackageName>_FIND_VERSION_MAX_TWEAK
3629 Tweak version of the upper end point if requested, else 0
3630 <PackageName>_FIND_VERSION_MAX_COUNT
3632 Number of version components of the upper end point, 0 to 4
3633 Regardless of whether a single version or a version range is specified,
3635 the variable <PackageName>_FIND_VERSION_COMPLETE will be defined and
3636 will hold the full requested version string as specified.
3637 In Module mode the loaded find module is responsible to honor the re‐
3639 quest detailed by these variables; see the find module for details. In
3640 Config mode find_package handles REQUIRED, QUIET, and [version] options
3641 automatically but leaves it to the package configuration file to handle
3642 components in a way that makes sense for the package. The package con‐
3643 figuration file may set <PackageName>_FOUND to false to tell find_pack‐
3644 age that component requirements are not satisfied.
3645 find_path
3647 A short-hand signature is:
3648 find_path (<VAR> name1 [path1 path2 ...])
3650 The general signature is:
3652 find_path (
3654 <VAR>
3655 name | NAMES name1 [name2 ...]
3656 [HINTS path1 [path2 ... ENV var]]
3657 [PATHS path1 [path2 ... ENV var]]
3658 [PATH_SUFFIXES suffix1 [suffix2 ...]]
3659 [DOC "cache documentation string"]
3660 [REQUIRED]
3661 [NO_DEFAULT_PATH]
3662 [NO_PACKAGE_ROOT_PATH]
3663 [NO_CMAKE_PATH]
3664 [NO_CMAKE_ENVIRONMENT_PATH]
3665 [NO_SYSTEM_ENVIRONMENT_PATH]
3666 [NO_CMAKE_SYSTEM_PATH]
3667 [CMAKE_FIND_ROOT_PATH_BOTH |
3668 ONLY_CMAKE_FIND_ROOT_PATH |
3669 NO_CMAKE_FIND_ROOT_PATH]
3670 )
3671 This command is used to find a directory containing the named file. A
3673 cache entry named by <VAR> is created to store the result of this com‐
3674 mand. If the file in a directory is found the result is stored in the
3675 variable and the search will not be repeated unless the variable is
3676 cleared. If nothing is found, the result will be <VAR>-NOTFOUND.
3677 Options include:
3679 NAMES Specify one or more possible names for the file in a directory.
3681 When using this to specify names with and without a version suf‐
3683 fix, we recommend specifying the unversioned name first so that
3684 locally-built packages can be found before those provided by
3685 distributions.
3686 HINTS, PATHS
3688 Specify directories to search in addition to the default loca‐
3689 tions. The ENV var sub-option reads paths from a system envi‐
3690 ronment variable.
3691 PATH_SUFFIXES
3693 Specify additional subdirectories to check below each directory
3694 location otherwise considered.
3695 DOC Specify the documentation string for the <VAR> cache entry.
3697 REQUIRED
3699 New in version 3.18.
3700 Stop processing with an error message if nothing is found, oth‐
3703 erwise the search will be attempted again the next time
3704 find_path is invoked with the same variable.
3705 If NO_DEFAULT_PATH is specified, then no additional paths are added to
3707 the search. If NO_DEFAULT_PATH is not specified, the search process is
3708 as follows:
3709 1. New in version 3.12: If called from within a find module or any
3711 other script loaded by a call to find_package(<PackageName>), search
3712 prefixes unique to the current package being found. Specifically,
3713 look in the <PackageName>_ROOT CMake variable and the <Package‐
3714 Name>_ROOT environment variable. The package root variables are
3715 maintained as a stack, so if called from nested find modules or con‐
3716 fig packages, root paths from the parent's find module or config
3717 package will be searched after paths from the current module or
3718 package. In other words, the search order would be <CurrentPack‐
3719 age>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT,
3720 ENV{<ParentPackage>_ROOT}, etc. This can be skipped if NO_PACK‐
3721 AGE_ROOT_PATH is passed or by setting the CMAKE_FIND_USE_PACK‐
3722 AGE_ROOT_PATH to FALSE. See policy CMP0074.
3723 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3726 <prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
3727 variable and the <PackageName>_ROOT environment variable if called
3728 from within a find module loaded by find_package(<PackageName>)
3729 2. Search paths specified in cmake-specific cache variables. These are
3731 intended to be used on the command line with a -DVAR=value. The
3732 values are interpreted as semicolon-separated lists. This can be
3733 skipped if NO_CMAKE_PATH is passed or by setting the
3734 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
3735 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3737 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
3738 • CMAKE_INCLUDE_PATH
3740 • CMAKE_FRAMEWORK_PATH
3742 3. Search paths specified in cmake-specific environment variables.
3744 These are intended to be set in the user's shell configuration, and
3745 therefore use the host's native path separator (; on Windows and :
3746 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
3747 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
3748 FALSE.
3749 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3751 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
3752 • CMAKE_INCLUDE_PATH
3754 • CMAKE_FRAMEWORK_PATH
3756 4. Search the paths specified by the HINTS option. These should be
3758 paths computed by system introspection, such as a hint provided by
3759 the location of another item already found. Hard-coded guesses
3760 should be specified with the PATHS option.
3761 5. Search the standard system environment variables. This can be
3763 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
3764 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
3765 • The directories in INCLUDE and PATH.
3767 • On Windows hosts: <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHI‐
3769 TECTURE is set, and <prefix>/include for each <prefix>/[s]bin in
3770 PATH, and <entry>/include for other entries in PATH.
3771 6. Search cmake variables defined in the Platform files for the current
3773 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
3774 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
3775 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3777 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
3778 • CMAKE_SYSTEM_INCLUDE_PATH
3780 • CMAKE_SYSTEM_FRAMEWORK_PATH
3782 The platform paths that these variables contain are locations that
3784 typically include installed software. An example being /usr/local
3785 for UNIX based platforms.
3786 7. Search the paths specified by the PATHS option or in the short-hand
3788 version of the command. These are typically hard-coded guesses.
3789 New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to
3791 globally disable various search locations.
3792 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
3795 determine the order of preference between Apple-style and unix-style
3796 package components.
3797 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
3799 ries to be prepended to all other search directories. This effectively
3800 "re-roots" the entire search under given locations. Paths which are
3801 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
3802 ing, because that variable is always a path on the host system. By de‐
3803 fault the CMAKE_FIND_ROOT_PATH is empty.
3804 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
3806 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
3807 fects. See the documentation for that variable for more.
3808 These variables are especially useful when cross-compiling to point to
3810 the root directory of the target environment and CMake will search
3811 there too. By default at first the directories listed in
3812 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
3813 searched, and then the non-rooted directories will be searched. The
3814 default behavior can be adjusted by setting
3815 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually over‐
3816 ridden on a per-call basis using options:
3817 CMAKE_FIND_ROOT_PATH_BOTH
3819 Search in the order described above.
3820 NO_CMAKE_FIND_ROOT_PATH
3822 Do not use the CMAKE_FIND_ROOT_PATH variable.
3823 ONLY_CMAKE_FIND_ROOT_PATH
3825 Search only the re-rooted directories and directories below
3826 CMAKE_STAGING_PREFIX.
3827 The default search order is designed to be most-specific to least-spe‐
3829 cific for common use cases. Projects may override the order by simply
3830 calling the command multiple times and using the NO_* options:
3831 find_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
3833 find_path (<VAR> NAMES name)
3834 Once one of the calls succeeds the result variable will be set and
3836 stored in the cache so that no call will search again.
3837 When searching for frameworks, if the file is specified as A/b.h, then
3839 the framework search will look for A.framework/Headers/b.h. If that is
3840 found the path will be set to the path to the framework. CMake will
3841 convert this to the correct -F option to include the file.
3842 find_program
3844 A short-hand signature is:
3845 find_program (<VAR> name1 [path1 path2 ...])
3847 The general signature is:
3849 find_program (
3851 <VAR>
3852 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
3853 [HINTS path1 [path2 ... ENV var]]
3854 [PATHS path1 [path2 ... ENV var]]
3855 [PATH_SUFFIXES suffix1 [suffix2 ...]]
3856 [DOC "cache documentation string"]
3857 [REQUIRED]
3858 [NO_DEFAULT_PATH]
3859 [NO_PACKAGE_ROOT_PATH]
3860 [NO_CMAKE_PATH]
3861 [NO_CMAKE_ENVIRONMENT_PATH]
3862 [NO_SYSTEM_ENVIRONMENT_PATH]
3863 [NO_CMAKE_SYSTEM_PATH]
3864 [CMAKE_FIND_ROOT_PATH_BOTH |
3865 ONLY_CMAKE_FIND_ROOT_PATH |
3866 NO_CMAKE_FIND_ROOT_PATH]
3867 )
3868 This command is used to find a program. A cache entry named by <VAR>
3870 is created to store the result of this command. If the program is
3871 found the result is stored in the variable and the search will not be
3872 repeated unless the variable is cleared. If nothing is found, the re‐
3873 sult will be <VAR>-NOTFOUND.
3874 Options include:
3876 NAMES Specify one or more possible names for the program.
3878 When using this to specify names with and without a version suf‐
3880 fix, we recommend specifying the unversioned name first so that
3881 locally-built packages can be found before those provided by
3882 distributions.
3883 HINTS, PATHS
3885 Specify directories to search in addition to the default loca‐
3886 tions. The ENV var sub-option reads paths from a system envi‐
3887 ronment variable.
3888 PATH_SUFFIXES
3890 Specify additional subdirectories to check below each directory
3891 location otherwise considered.
3892 DOC Specify the documentation string for the <VAR> cache entry.
3894 REQUIRED
3896 New in version 3.18.
3897 Stop processing with an error message if nothing is found, oth‐
3900 erwise the search will be attempted again the next time
3901 find_program is invoked with the same variable.
3902 If NO_DEFAULT_PATH is specified, then no additional paths are added to
3904 the search. If NO_DEFAULT_PATH is not specified, the search process is
3905 as follows:
3906 1. New in version 3.12: If called from within a find module or any
3908 other script loaded by a call to find_package(<PackageName>), search
3909 prefixes unique to the current package being found. Specifically,
3910 look in the <PackageName>_ROOT CMake variable and the <Package‐
3911 Name>_ROOT environment variable. The package root variables are
3912 maintained as a stack, so if called from nested find modules or con‐
3913 fig packages, root paths from the parent's find module or config
3914 package will be searched after paths from the current module or
3915 package. In other words, the search order would be <CurrentPack‐
3916 age>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT,
3917 ENV{<ParentPackage>_ROOT}, etc. This can be skipped if NO_PACK‐
3918 AGE_ROOT_PATH is passed or by setting the CMAKE_FIND_USE_PACK‐
3919 AGE_ROOT_PATH to FALSE. See policy CMP0074.
3920 • <prefix>/[s]bin for each <prefix> in the <PackageName>_ROOT CMake
3923 variable and the <PackageName>_ROOT environment variable if called
3924 from within a find module loaded by find_package(<PackageName>)
3925 2. Search paths specified in cmake-specific cache variables. These are
3927 intended to be used on the command line with a -DVAR=value. The
3928 values are interpreted as semicolon-separated lists. This can be
3929 skipped if NO_CMAKE_PATH is passed or by setting the
3930 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
3931 • <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
3933 • CMAKE_PROGRAM_PATH
3935 • CMAKE_APPBUNDLE_PATH
3937 3. Search paths specified in cmake-specific environment variables.
3939 These are intended to be set in the user's shell configuration, and
3940 therefore use the host's native path separator (; on Windows and :
3941 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
3942 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
3943 FALSE.
3944 • <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
3946 • CMAKE_PROGRAM_PATH
3948 • CMAKE_APPBUNDLE_PATH
3950 4. Search the paths specified by the HINTS option. These should be
3952 paths computed by system introspection, such as a hint provided by
3953 the location of another item already found. Hard-coded guesses
3954 should be specified with the PATHS option.
3955 5. Search the standard system environment variables. This can be
3957 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
3958 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
3959 • The directories in PATH itself.
3961 • On Windows hosts no extra search paths are included
3963 6. Search cmake variables defined in the Platform files for the current
3965 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
3966 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
3967 • <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
3969 • CMAKE_SYSTEM_PROGRAM_PATH
3971 • CMAKE_SYSTEM_APPBUNDLE_PATH
3973 The platform paths that these variables contain are locations that
3975 typically include installed software. An example being /usr/local
3976 for UNIX based platforms.
3977 7. Search the paths specified by the PATHS option or in the short-hand
3979 version of the command. These are typically hard-coded guesses.
3980 New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to
3982 globally disable various search locations.
3983 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
3986 determine the order of preference between Apple-style and unix-style
3987 package components.
3988 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
3990 ries to be prepended to all other search directories. This effectively
3991 "re-roots" the entire search under given locations. Paths which are
3992 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
3993 ing, because that variable is always a path on the host system. By de‐
3994 fault the CMAKE_FIND_ROOT_PATH is empty.
3995 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
3997 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
3998 fects. See the documentation for that variable for more.
3999 These variables are especially useful when cross-compiling to point to
4001 the root directory of the target environment and CMake will search
4002 there too. By default at first the directories listed in
4003 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
4004 searched, and then the non-rooted directories will be searched. The
4005 default behavior can be adjusted by setting
4006 CMAKE_FIND_ROOT_PATH_MODE_PROGRAM. This behavior can be manually over‐
4007 ridden on a per-call basis using options:
4008 CMAKE_FIND_ROOT_PATH_BOTH
4010 Search in the order described above.
4011 NO_CMAKE_FIND_ROOT_PATH
4013 Do not use the CMAKE_FIND_ROOT_PATH variable.
4014 ONLY_CMAKE_FIND_ROOT_PATH
4016 Search only the re-rooted directories and directories below
4017 CMAKE_STAGING_PREFIX.
4018 The default search order is designed to be most-specific to least-spe‐
4020 cific for common use cases. Projects may override the order by simply
4021 calling the command multiple times and using the NO_* options:
4022 find_program (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
4024 find_program (<VAR> NAMES name)
4025 Once one of the calls succeeds the result variable will be set and
4027 stored in the cache so that no call will search again.
4028 When more than one value is given to the NAMES option this command by
4030 default will consider one name at a time and search every directory for
4031 it. The NAMES_PER_DIR option tells this command to consider one direc‐
4032 tory at a time and search for all names in it.
4033 foreach
4035 Evaluate a group of commands for each value in a list.
4036 foreach(<loop_var> <items>)
4038 <commands>
4039 endforeach()
4040 where <items> is a list of items that are separated by semicolon or
4042 whitespace. All commands between foreach and the matching endforeach
4043 are recorded without being invoked. Once the endforeach is evaluated,
4044 the recorded list of commands is invoked once for each item in <items>.
4045 At the beginning of each iteration the variable loop_var will be set to
4046 the value of the current item.
4047 The commands break() and continue() provide means to escape from the
4049 normal control flow.
4050 Per legacy, the endforeach() command admits an optional <loop_var> ar‐
4052 gument. If used, it must be a verbatim repeat of the argument of the
4053 opening foreach command.
4054 foreach(<loop_var> RANGE <stop>)
4056 In this variant, foreach iterates over the numbers 0, 1, ... up to (and
4058 including) the nonnegative integer <stop>.
4059 foreach(<loop_var> RANGE <start> <stop> [<step>])
4061 In this variant, foreach iterates over the numbers from <start> up to
4063 at most <stop> in steps of <step>. If <step> is not specified, then
4064 the step size is 1. The three arguments <start> <stop> <step> must all
4065 be nonnegative integers, and <stop> must not be smaller than <start>;
4066 otherwise you enter the danger zone of undocumented behavior that may
4067 change in future releases.
4068 foreach(<loop_var> IN [LISTS [<lists>]] [ITEMS [<items>]])
4070 In this variant, <lists> is a whitespace or semicolon separated list of
4072 list-valued variables. The foreach command iterates over each item in
4073 each given list. The <items> following the ITEMS keyword are processed
4074 as in the first variant of the foreach command. The forms LISTS A and
4075 ITEMS ${A} are equivalent.
4076 The following example shows how the LISTS option is processed:
4078 set(A 0;1)
4080 set(B 2 3)
4081 set(C "4 5")
4082 set(D 6;7 8)
4083 set(E "")
4084 foreach(X IN LISTS A B C D E)
4085 message(STATUS "X=${X}")
4086 endforeach()
4087 yields
4089 -- X=0
4091 -- X=1
4092 -- X=2
4093 -- X=3
4094 -- X=4 5
4095 -- X=6
4096 -- X=7
4097 -- X=8
4098 foreach(<loop_var>... IN ZIP_LISTS <lists>)
4100 New in version 3.17.
4102 In this variant, <lists> is a whitespace or semicolon separated list of
4105 list-valued variables. The foreach command iterates over each list si‐
4106 multaneously setting the iteration variables as follows:
4107 • if the only loop_var given, then it sets a series of loop_var_N vari‐
4109 ables to the current item from the corresponding list;
4110 • if multiple variable names passed, their count should match the lists
4112 variables count;
4113 • if any of the lists are shorter, the corresponding iteration variable
4115 is not defined for the current iteration.
4116 list(APPEND English one two three four)
4118 list(APPEND Bahasa satu dua tiga)
4119 foreach(num IN ZIP_LISTS English Bahasa)
4121 message(STATUS "num_0=${num_0}, num_1=${num_1}")
4122 endforeach()
4123 foreach(en ba IN ZIP_LISTS English Bahasa)
4125 message(STATUS "en=${en}, ba=${ba}")
4126 endforeach()
4127 yields
4129 -- num_0=one, num_1=satu
4131 -- num_0=two, num_1=dua
4132 -- num_0=three, num_1=tiga
4133 -- num_0=four, num_1=
4134 -- en=one, ba=satu
4135 -- en=two, ba=dua
4136 -- en=three, ba=tiga
4137 -- en=four, ba=
4138 function
4140 Start recording a function for later invocation as a command.
4141 function(<name> [<arg1> ...])
4143 <commands>
4144 endfunction()
4145 Defines a function named <name> that takes arguments named <arg1>, ...
4147 The <commands> in the function definition are recorded; they are not
4148 executed until the function is invoked.
4149 Per legacy, the endfunction() command admits an optional <name> argu‐
4151 ment. If used, it must be a verbatim repeat of the argument of the
4152 opening function command.
4153 A function opens a new scope: see set(var PARENT_SCOPE) for details.
4155 See the cmake_policy() command documentation for the behavior of poli‐
4157 cies inside functions.
4158 See the macro() command documentation for differences between CMake
4160 functions and macros.
4161 Invocation
4163 The function invocation is case-insensitive. A function defined as
4164 function(foo)
4166 <commands>
4167 endfunction()
4168 can be invoked through any of
4170 foo()
4172 Foo()
4173 FOO()
4174 cmake_language(CALL foo)
4175 and so on. However, it is strongly recommended to stay with the case
4177 chosen in the function definition. Typically functions use all-lower‐
4178 case names.
4179 New in version 3.18: The cmake_language(CALL ...) command can also be
4181 used to invoke the function.
4182 Arguments
4185 When the function is invoked, the recorded <commands> are first modi‐
4186 fied by replacing formal parameters (${arg1}, ...) with the arguments
4187 passed, and then invoked as normal commands.
4188 In addition to referencing the formal parameters you can reference the
4190 ARGC variable which will be set to the number of arguments passed into
4191 the function as well as ARGV0, ARGV1, ARGV2, ... which will have the
4192 actual values of the arguments passed in. This facilitates creating
4193 functions with optional arguments.
4194 Furthermore, ARGV holds the list of all arguments given to the function
4196 and ARGN holds the list of arguments past the last expected argument.
4197 Referencing to ARGV# arguments beyond ARGC have undefined behavior.
4198 Checking that ARGC is greater than # is the only way to ensure that
4199 ARGV# was passed to the function as an extra argument.
4200 get_cmake_property
4202 Get a global property of the CMake instance.
4203 get_cmake_property(<var> <property>)
4205 Gets a global property from the CMake instance. The value of the
4207 <property> is stored in the variable <var>. If the property is not
4208 found, <var> will be set to NOTFOUND. See the cmake-properties(7) man‐
4209 ual for available properties.
4210 See also the get_property() command GLOBAL option.
4212 In addition to global properties, this command (for historical reasons)
4214 also supports the VARIABLES and MACROS directory properties. It also
4215 supports a special COMPONENTS global property that lists the components
4216 given to the install() command.
4217 get_directory_property
4219 Get a property of DIRECTORY scope.
4220 get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
4222 Stores a property of directory scope in the named <variable>.
4224 The DIRECTORY argument specifies another directory from which to re‐
4226 trieve the property value instead of the current directory. Relative
4227 paths are treated as relative to the current source directory. CMake
4228 must already know about the directory, either by having added it
4229 through a call to add_subdirectory() or being the top level directory.
4230 New in version 3.19: <dir> may reference a binary directory.
4232 If the property is not defined for the nominated directory scope, an
4235 empty string is returned. In the case of INHERITED properties, if the
4236 property is not found for the nominated directory scope, the search
4237 will chain to a parent scope as described for the define_property()
4238 command.
4239 get_directory_property(<variable> [DIRECTORY <dir>]
4241 DEFINITION <var-name>)
4242 Get a variable definition from a directory. This form is useful to get
4244 a variable definition from another directory.
4245 See also the more general get_property() command.
4247 get_filename_component
4249 Get a specific component of a full filename.
4250 Changed in version 3.19: This command been superseded by cmake_path()
4252 command, except REALPATH now offered by file(REAL_PATH) command and
4253 PROGRAM now available in separate_arguments(PROGRAM) command.
4254 get_filename_component(<var> <FileName> <mode> [CACHE])
4257 Sets <var> to a component of <FileName>, where <mode> is one of:
4259 DIRECTORY = Directory without file name
4261 NAME = File name without directory
4262 EXT = File name longest extension (.b.c from d/a.b.c)
4263 NAME_WE = File name with neither the directory nor the longest extension
4264 LAST_EXT = File name last extension (.c from d/a.b.c)
4265 NAME_WLE = File name with neither the directory nor the last extension
4266 PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
4267 New in version 3.14: Added the LAST_EXT and NAME_WLE modes.
4269 Paths are returned with forward slashes and have no trailing slashes.
4272 If the optional CACHE argument is specified, the result variable is
4273 added to the cache.
4274 get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
4276 New in version 3.4.
4278 Sets <var> to the absolute path of <FileName>, where <mode> is one of:
4281 ABSOLUTE = Full path to file
4283 REALPATH = Full path to existing file with symlinks resolved
4284 If the provided <FileName> is a relative path, it is evaluated relative
4286 to the given base directory <dir>. If no base directory is provided,
4287 the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
4288 Paths are returned with forward slashes and have no trailing slashes.
4290 If the optional CACHE argument is specified, the result variable is
4291 added to the cache.
4292 get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
4294 The program in <FileName> will be found in the system search path or
4296 left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
4297 command-line arguments present in the <FileName> string are split from
4298 the program name and stored in <arg_var>. This is used to separate a
4299 program name from its arguments in a command line string.
4300 get_property
4302 Get a property.
4303 get_property(<variable>
4305 <GLOBAL |
4306 DIRECTORY [<dir>] |
4307 TARGET <target> |
4308 SOURCE <source> |
4309 [DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
4310 INSTALL <file> |
4311 TEST <test> |
4312 CACHE <entry> |
4313 VARIABLE >
4314 PROPERTY <name>
4315 [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
4316 Gets one property from one object in a scope.
4318 The first argument specifies the variable in which to store the result.
4320 The second argument determines the scope from which to get the prop‐
4321 erty. It must be one of the following:
4322 GLOBAL Scope is unique and does not accept a name.
4324 DIRECTORY
4326 Scope defaults to the current directory but another directory
4327 (already processed by CMake) may be named by the full or rela‐
4328 tive path <dir>. Relative paths are treated as relative to the
4329 current source directory. See also the get_directory_property()
4330 command.
4331 New in version 3.19: <dir> may reference a binary directory.
4333 TARGET Scope must name one existing target. See also the get_tar‐
4336 get_property() command.
4337 SOURCE Scope must name one source file. By default, the source file's
4339 property will be read from the current source directory's scope.
4340 New in version 3.18: Directory scope can be overridden with one
4342 of the following sub-options:
4343 DIRECTORY <dir>
4345 The source file property will be read from the <dir> di‐
4346 rectory's scope. CMake must already know about the di‐
4347 rectory, either by having added it through a call to
4348 add_subdirectory() or <dir> being the top level direc‐
4349 tory. Relative paths are treated as relative to the cur‐
4350 rent source directory.
4351 New in version 3.19: <dir> may reference a binary direc‐
4353 tory.
4354 TARGET_DIRECTORY <target>
4357 The source file property will be read from the directory
4358 scope in which <target> was created (<target> must there‐
4359 fore already exist).
4360 See also the get_source_file_property() command.
4363 INSTALL
4365 New in version 3.1.
4366 Scope must name one installed file path.
4369 TEST Scope must name one existing test. See also the get_test_prop‐
4371 erty() command.
4372 CACHE Scope must name one cache entry.
4374 VARIABLE
4376 Scope is unique and does not accept a name.
4377 The required PROPERTY option is immediately followed by the name of the
4379 property to get. If the property is not set an empty value is re‐
4380 turned, although some properties support inheriting from a parent scope
4381 if defined to behave that way (see define_property()).
4382 If the SET option is given the variable is set to a boolean value indi‐
4384 cating whether the property has been set. If the DEFINED option is
4385 given the variable is set to a boolean value indicating whether the
4386 property has been defined such as with the define_property() command.
4387 If BRIEF_DOCS or FULL_DOCS is given then the variable is set to a
4389 string containing documentation for the requested property. If docu‐
4390 mentation is requested for a property that has not been defined NOT‐
4391 FOUND is returned.
4392 NOTE:
4394 The GENERATED source file property may be globally visible. See its
4395 documentation for details.
4396 if
4398 Conditionally execute a group of commands.
4399 Synopsis
4401 if(<condition>)
4402 <commands>
4403 elseif(<condition>) # optional block, can be repeated
4404 <commands>
4405 else() # optional block
4406 <commands>
4407 endif()
4408 Evaluates the condition argument of the if clause according to the
4410 Condition syntax described below. If the result is true, then the com‐
4411 mands in the if block are executed. Otherwise, optional elseif blocks
4412 are processed in the same way. Finally, if no condition is true, com‐
4413 mands in the optional else block are executed.
4414 Per legacy, the else() and endif() commands admit an optional <condi‐
4416 tion> argument. If used, it must be a verbatim repeat of the argument
4417 of the opening if command.
4418 Condition Syntax
4420 The following syntax applies to the condition argument of the if, el‐
4421 seif and while() clauses.
4422 Compound conditions are evaluated in the following order of precedence:
4424 Innermost parentheses are evaluated first. Next come unary tests such
4425 as EXISTS, COMMAND, and DEFINED. Then binary tests such as EQUAL,
4426 LESS, LESS_EQUAL, GREATER, GREATER_EQUAL, STREQUAL, STRLESS,
4427 STRLESS_EQUAL, STRGREATER, STRGREATER_EQUAL, VERSION_EQUAL,
4428 VERSION_LESS, VERSION_LESS_EQUAL, VERSION_GREATER,
4429 VERSION_GREATER_EQUAL, and MATCHES. Then the boolean operators in the
4430 order NOT, AND, and finally OR.
4431 Basic Expressions
4433 if(<constant>)
4434 True if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
4435 ber. False if the constant is 0, OFF, NO, FALSE, N, IGNORE,
4436 NOTFOUND, the empty string, or ends in the suffix -NOTFOUND.
4437 Named boolean constants are case-insensitive. If the argument
4438 is not one of these specific constants, it is treated as a vari‐
4439 able or string and the following signature is used.
4440 if(<variable|string>)
4442 True if given a variable that is defined to a value that is not
4443 a false constant. False otherwise. (Note macro arguments are
4444 not variables.)
4445 Logic Operators
4447 if(NOT <condition>)
4448 True if the condition is not true.
4449 if(<cond1> AND <cond2>)
4451 True if both conditions would be considered true individually.
4452 if(<cond1> OR <cond2>)
4454 True if either condition would be considered true individually.
4455 if((condition) AND (condition OR (condition)))
4457 The conditions inside the parenthesis are evaluated first and
4458 then the remaining condition is evaluated as in the other exam‐
4459 ples. Where there are nested parenthesis the innermost are
4460 evaluated as part of evaluating the condition that contains
4461 them.
4462 Existence Checks
4464 if(COMMAND command-name)
4465 True if the given name is a command, macro or function that can
4466 be invoked.
4467 if(POLICY policy-id)
4469 True if the given name is an existing policy (of the form
4470 CMP<NNNN>).
4471 if(TARGET target-name)
4473 True if the given name is an existing logical target name cre‐
4474 ated by a call to the add_executable(), add_library(), or
4475 add_custom_target() command that has already been invoked (in
4476 any directory).
4477 if(TEST test-name)
4479 New in version 3.3: True if the given name is an existing test
4480 name created by the add_test() command.
4481 if(DEFINED <name>|CACHE{<name>}|ENV{<name>})
4484 True if a variable, cache variable or environment variable with
4485 given <name> is defined. The value of the variable does not mat‐
4486 ter. Note that macro arguments are not variables.
4487 New in version 3.14: Added support for CACHE{<name>} variables.
4489 if(<variable|string> IN_LIST <variable>)
4492 New in version 3.3: True if the given element is contained in
4493 the named list variable.
4494 File Operations
4497 if(EXISTS path-to-file-or-directory)
4498 True if the named file or directory exists. Behavior is
4499 well-defined only for explicit full paths (a leading ~/ is not
4500 expanded as a home directory and is considered a relative path).
4501 Resolves symbolic links, i.e. if the named file or directory is
4502 a symbolic link, returns true if the target of the symbolic link
4503 exists.
4504 if(file1 IS_NEWER_THAN file2)
4506 True if file1 is newer than file2 or if one of the two files
4507 doesn't exist. Behavior is well-defined only for full paths.
4508 If the file time stamps are exactly the same, an IS_NEWER_THAN
4509 comparison returns true, so that any dependent build operations
4510 will occur in the event of a tie. This includes the case of
4511 passing the same file name for both file1 and file2.
4512 if(IS_DIRECTORY path-to-directory)
4514 True if the given name is a directory. Behavior is well-defined
4515 only for full paths.
4516 if(IS_SYMLINK file-name)
4518 True if the given name is a symbolic link. Behavior is well-de‐
4519 fined only for full paths.
4520 if(IS_ABSOLUTE path)
4522 True if the given path is an absolute path. Note the following
4523 special cases:
4524 • An empty path evaluates to false.
4526 • On Windows hosts, any path that begins with a drive letter and
4528 colon (e.g. C:), a forward slash or a backslash will evaluate
4529 to true. This means a path like C:no\base\dir will evaluate
4530 to true, even though the non-drive part of the path is rela‐
4531 tive.
4532 • On non-Windows hosts, any path that begins with a tilde (~)
4534 evaluates to true.
4535 Comparisons
4537 if(<variable|string> MATCHES regex)
4538 True if the given string or variable's value matches the given
4539 regular condition. See Regex Specification for regex format.
4540 New in version 3.9: () groups are captured in CMAKE_MATCH_<n>
4542 variables.
4543 if(<variable|string> LESS <variable|string>)
4546 True if the given string or variable's value is a valid number
4547 and less than that on the right.
4548 if(<variable|string> GREATER <variable|string>)
4550 True if the given string or variable's value is a valid number
4551 and greater than that on the right.
4552 if(<variable|string> EQUAL <variable|string>)
4554 True if the given string or variable's value is a valid number
4555 and equal to that on the right.
4556 if(<variable|string> LESS_EQUAL <variable|string>)
4558 New in version 3.7: True if the given string or variable's value
4559 is a valid number and less than or equal to that on the right.
4560 if(<variable|string> GREATER_EQUAL <variable|string>)
4563 New in version 3.7: True if the given string or variable's value
4564 is a valid number and greater than or equal to that on the
4565 right.
4566 if(<variable|string> STRLESS <variable|string>)
4569 True if the given string or variable's value is lexicographi‐
4570 cally less than the string or variable on the right.
4571 if(<variable|string> STRGREATER <variable|string>)
4573 True if the given string or variable's value is lexicographi‐
4574 cally greater than the string or variable on the right.
4575 if(<variable|string> STREQUAL <variable|string>)
4577 True if the given string or variable's value is lexicographi‐
4578 cally equal to the string or variable on the right.
4579 if(<variable|string> STRLESS_EQUAL <variable|string>)
4581 New in version 3.7: True if the given string or variable's value
4582 is lexicographically less than or equal to the string or vari‐
4583 able on the right.
4584 if(<variable|string> STRGREATER_EQUAL <variable|string>)
4587 New in version 3.7: True if the given string or variable's value
4588 is lexicographically greater than or equal to the string or
4589 variable on the right.
4590 Version Comparisons
4593 if(<variable|string> VERSION_LESS <variable|string>)
4594 Component-wise integer version number comparison (version format
4595 is major[.minor[.patch[.tweak]]], omitted components are treated
4596 as zero). Any non-integer version component or non-integer
4597 trailing part of a version component effectively truncates the
4598 string at that point.
4599 if(<variable|string> VERSION_GREATER <variable|string>)
4601 Component-wise integer version number comparison (version format
4602 is major[.minor[.patch[.tweak]]], omitted components are treated
4603 as zero). Any non-integer version component or non-integer
4604 trailing part of a version component effectively truncates the
4605 string at that point.
4606 if(<variable|string> VERSION_EQUAL <variable|string>)
4608 Component-wise integer version number comparison (version format
4609 is major[.minor[.patch[.tweak]]], omitted components are treated
4610 as zero). Any non-integer version component or non-integer
4611 trailing part of a version component effectively truncates the
4612 string at that point.
4613 if(<variable|string> VERSION_LESS_EQUAL <variable|string>)
4615 New in version 3.7: Component-wise integer version number com‐
4616 parison (version format is major[.minor[.patch[.tweak]]], omit‐
4617 ted components are treated as zero). Any non-integer version
4618 component or non-integer trailing part of a version component
4619 effectively truncates the string at that point.
4620 if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)
4623 New in version 3.7: Component-wise integer version number com‐
4624 parison (version format is major[.minor[.patch[.tweak]]], omit‐
4625 ted components are treated as zero). Any non-integer version
4626 component or non-integer trailing part of a version component
4627 effectively truncates the string at that point.
4628 Variable Expansion
4631 The if command was written very early in CMake's history, predating the
4632 ${} variable evaluation syntax, and for convenience evaluates variables
4633 named by its arguments as shown in the above signatures. Note that
4634 normal variable evaluation with ${} applies before the if command even
4635 receives the arguments. Therefore code like
4636 set(var1 OFF)
4638 set(var2 "var1")
4639 if(${var2})
4640 appears to the if command as
4642 if(var1)
4644 and is evaluated according to the if(<variable>) case documented above.
4646 The result is OFF which is false. However, if we remove the ${} from
4647 the example then the command sees
4648 if(var2)
4650 which is true because var2 is defined to var1 which is not a false con‐
4652 stant.
4653 Automatic evaluation applies in the other cases whenever the above-doc‐
4655 umented condition syntax accepts <variable|string>:
4656 • The left hand argument to MATCHES is first checked to see if it is a
4658 defined variable, if so the variable's value is used, otherwise the
4659 original value is used.
4660 • If the left hand argument to MATCHES is missing it returns false
4662 without error
4663 • Both left and right hand arguments to LESS, GREATER, EQUAL,
4665 LESS_EQUAL, and GREATER_EQUAL, are independently tested to see if
4666 they are defined variables, if so their defined values are used oth‐
4667 erwise the original value is used.
4668 • Both left and right hand arguments to STRLESS, STRGREATER, STREQUAL,
4670 STRLESS_EQUAL, and STRGREATER_EQUAL are independently tested to see
4671 if they are defined variables, if so their defined values are used
4672 otherwise the original value is used.
4673 • Both left and right hand arguments to VERSION_LESS, VERSION_GREATER,
4675 VERSION_EQUAL, VERSION_LESS_EQUAL, and VERSION_GREATER_EQUAL are in‐
4676 dependently tested to see if they are defined variables, if so their
4677 defined values are used otherwise the original value is used.
4678 • The right hand argument to NOT is tested to see if it is a boolean
4680 constant, if so the value is used, otherwise it is assumed to be a
4681 variable and it is dereferenced.
4682 • The left and right hand arguments to AND and OR are independently
4684 tested to see if they are boolean constants, if so they are used as
4685 such, otherwise they are assumed to be variables and are derefer‐
4686 enced.
4687 Changed in version 3.1: To prevent ambiguity, potential variable or
4689 keyword names can be specified in a Quoted Argument or a Bracket Argu‐
4690 ment. A quoted or bracketed variable or keyword will be interpreted as
4691 a string and not dereferenced or interpreted. See policy CMP0054.
4692 There is no automatic evaluation for environment or cache Variable Ref‐
4695 erences. Their values must be referenced as $ENV{<name>} or
4696 $CACHE{<name>} wherever the above-documented condition syntax accepts
4697 <variable|string>.
4698 include
4700 Load and run CMake code from a file or module.
4701 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
4703 [NO_POLICY_SCOPE])
4704 Loads and runs CMake code from the file given. Variable reads and
4706 writes access the scope of the caller (dynamic scoping). If OPTIONAL
4707 is present, then no error is raised if the file does not exist. If RE‐
4708 SULT_VARIABLE is given the variable <var> will be set to the full file‐
4709 name which has been included or NOTFOUND if it failed.
4710 If a module is specified instead of a file, the file with name <module‐
4712 name>.cmake is searched first in CMAKE_MODULE_PATH, then in the CMake
4713 module directory. There is one exception to this: if the file which
4714 calls include() is located itself in the CMake builtin module direc‐
4715 tory, then first the CMake builtin module directory is searched and
4716 CMAKE_MODULE_PATH afterwards. See also policy CMP0017.
4717 See the cmake_policy() command documentation for discussion of the
4719 NO_POLICY_SCOPE option.
4720 include_guard
4722 New in version 3.10.
4723 Provides an include guard for the file currently being processed by
4726 CMake.
4727 include_guard([DIRECTORY|GLOBAL])
4729 Sets up an include guard for the current CMake file (see the CMAKE_CUR‐
4731 RENT_LIST_FILE variable documentation).
4732 CMake will end its processing of the current file at the location of
4734 the include_guard() command if the current file has already been pro‐
4735 cessed for the applicable scope (see below). This provides functional‐
4736 ity similar to the include guards commonly used in source headers or to
4737 the #pragma once directive. If the current file has been processed pre‐
4738 viously for the applicable scope, the effect is as though return() had
4739 been called. Do not call this command from inside a function being de‐
4740 fined within the current file.
4741 An optional argument specifying the scope of the guard may be provided.
4743 Possible values for the option are:
4744 DIRECTORY
4746 The include guard applies within the current directory and be‐
4747 low. The file will only be included once within this directory
4748 scope, but may be included again by other files outside of this
4749 directory (i.e. a parent directory or another directory not
4750 pulled in by add_subdirectory() or include() from the current
4751 file or its children).
4752 GLOBAL The include guard applies globally to the whole build. The cur‐
4754 rent file will only be included once regardless of the scope.
4755 If no arguments given, include_guard has the same scope as a variable,
4757 meaning that the include guard effect is isolated by the most recent
4758 function scope or current directory if no inner function scopes exist.
4759 In this case the command behavior is the same as:
4760 if(__CURRENT_FILE_VAR__)
4762 return()
4763 endif()
4764 set(__CURRENT_FILE_VAR__ TRUE)
4765 list
4767 List operations.
4768 Synopsis
4770 Reading
4771 list(LENGTH <list> <out-var>)
4772 list(GET <list> <element index> [<index> ...] <out-var>)
4773 list(JOIN <list> <glue> <out-var>)
4774 list(SUBLIST <list> <begin> <length> <out-var>)
4775 Search
4777 list(FIND <list> <value> <out-var>)
4778 Modification
4780 list(APPEND <list> [<element>...])
4781 list(FILTER <list> {INCLUDE | EXCLUDE} REGEX <regex>)
4782 list(INSERT <list> <index> [<element>...])
4783 list(POP_BACK <list> [<out-var>...])
4784 list(POP_FRONT <list> [<out-var>...])
4785 list(PREPEND <list> [<element>...])
4786 list(REMOVE_ITEM <list> <value>...)
4787 list(REMOVE_AT <list> <index>...)
4788 list(REMOVE_DUPLICATES <list>)
4789 list(TRANSFORM <list> <ACTION> [...])
4790 Ordering
4792 list(REVERSE <list>)
4793 list(SORT <list> [...])
4794 Introduction
4796 The list subcommands APPEND, INSERT, FILTER, PREPEND, POP_BACK,
4797 POP_FRONT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, REVERSE and SORT
4798 may create new values for the list within the current CMake variable
4799 scope. Similar to the set() command, the LIST command creates new
4800 variable values in the current scope, even if the list itself is actu‐
4801 ally defined in a parent scope. To propagate the results of these op‐
4802 erations upwards, use set() with PARENT_SCOPE, set() with CACHE INTER‐
4803 NAL, or some other means of value propagation.
4804 NOTE:
4806 A list in cmake is a ; separated group of strings. To create a list
4807 the set command can be used. For example, set(var a b c d e) cre‐
4808 ates a list with a;b;c;d;e, and set(var "a b c d e") creates a
4809 string or a list with one item in it. (Note macro arguments are
4810 not variables, and therefore cannot be used in LIST commands.)
4811 NOTE:
4813 When specifying index values, if <element index> is 0 or greater, it
4814 is indexed from the beginning of the list, with 0 representing the
4815 first list element. If <element index> is -1 or lesser, it is in‐
4816 dexed from the end of the list, with -1 representing the last list
4817 element. Be careful when counting with negative indices: they do
4818 not start from 0. -0 is equivalent to 0, the first list element.
4819 Reading
4821 list(LENGTH <list> <output variable>)
4822 Returns the list's length.
4824 list(GET <list> <element index> [<element index> ...] <output variable>)
4826 Returns the list of elements specified by indices from the list.
4828 list(JOIN <list> <glue> <output variable>)
4830 New in version 3.12.
4832 Returns a string joining all list's elements using the glue string. To
4835 join multiple strings, which are not part of a list, use JOIN operator
4836 from string() command.
4837 list(SUBLIST <list> <begin> <length> <output variable>)
4839 New in version 3.12.
4841 Returns a sublist of the given list. If <length> is 0, an empty list
4844 will be returned. If <length> is -1 or the list is smaller than <be‐
4845 gin>+<length> then the remaining elements of the list starting at <be‐
4846 gin> will be returned.
4847 Search
4849 list(FIND <list> <value> <output variable>)
4850 Returns the index of the element specified in the list or -1 if it
4852 wasn't found.
4853 Modification
4855 list(APPEND <list> [<element> ...])
4856 Appends elements to the list.
4858 list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
4860 New in version 3.6.
4862 Includes or removes items from the list that match the mode's pattern.
4865 In REGEX mode, items will be matched against the given regular expres‐
4866 sion.
4867 For more information on regular expressions see also the string() com‐
4869 mand.
4870 list(INSERT <list> <element_index> <element> [<element> ...])
4872 Inserts elements to the list to the specified location.
4874 list(POP_BACK <list> [<out-var>...])
4876 New in version 3.15.
4878 If no variable name is given, removes exactly one element. Otherwise,
4881 assign the last element's value to the given variable and removes it,
4882 up to the last variable name given.
4883 list(POP_FRONT <list> [<out-var>...])
4885 New in version 3.15.
4887 If no variable name is given, removes exactly one element. Otherwise,
4890 assign the first element's value to the given variable and removes it,
4891 up to the last variable name given.
4892 list(PREPEND <list> [<element> ...])
4894 New in version 3.15.
4896 Insert elements to the 0th position in the list.
4899 list(REMOVE_ITEM <list> <value> [<value> ...])
4901 Removes all instances of the given items from the list.
4903 list(REMOVE_AT <list> <index> [<index> ...])
4905 Removes items at given indices from the list.
4907 list(REMOVE_DUPLICATES <list>)
4909 Removes duplicated items in the list. The relative order of items is
4911 preserved, but if duplicates are encountered, only the first instance
4912 is preserved.
4913 list(TRANSFORM <list> <ACTION> [<SELECTOR>]
4915 [OUTPUT_VARIABLE <output variable>])
4916 New in version 3.12.
4918 Transforms the list by applying an action to all or, by specifying a
4921 <SELECTOR>, to the selected elements of the list, storing the result
4922 in-place or in the specified output variable.
4923 NOTE:
4925 The TRANSFORM sub-command does not change the number of elements in
4926 the list. If a <SELECTOR> is specified, only some elements will be
4927 changed, the other ones will remain the same as before the transfor‐
4928 mation.
4929 <ACTION> specifies the action to apply to the elements of the list.
4931 The actions have exactly the same semantics as sub-commands of the
4932 string() command. <ACTION> must be one of the following:
4933 APPEND, PREPEND: Append, prepend specified value to each element of the
4935 list.
4936 list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
4938 TOUPPER, TOLOWER: Convert each element of the list to upper, lower
4940 characters.
4941 list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
4943 STRIP: Remove leading and trailing spaces from each element of the
4945 list.
4946 list(TRANSFORM <list> STRIP ...)
4948 GENEX_STRIP: Strip any generator expressions from each element of the
4950 list.
4951 list(TRANSFORM <list> GENEX_STRIP ...)
4953 REPLACE: Match the regular expression as many times as possible and
4955 substitute the replacement expression for the match for each element of
4956 the list (Same semantic as REGEX REPLACE from string() command).
4957 list(TRANSFORM <list> REPLACE <regular_expression>
4959 <replace_expression> ...)
4960 <SELECTOR> determines which elements of the list will be transformed.
4962 Only one type of selector can be specified at a time. When given, <SE‐
4963 LECTOR> must be one of the following:
4964 AT: Specify a list of indexes.
4966 list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
4968 FOR: Specify a range with, optionally, an increment used to iterate
4970 over the range.
4971 list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
4973 REGEX: Specify a regular expression. Only elements matching the regular
4975 expression will be transformed.
4976 list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
4978 Ordering
4980 list(REVERSE <list>)
4981 Reverses the contents of the list in-place.
4983 list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
4985 Sorts the list in-place alphabetically.
4987 New in version 3.13: Added the COMPARE, CASE, and ORDER options.
4989 New in version 3.18: Added the COMPARE NATURAL option.
4992 Use the COMPARE keyword to select the comparison method for sorting.
4995 The <compare> option should be one of:
4996 • STRING: Sorts a list of strings alphabetically. This is the default
4998 behavior if the COMPARE option is not given.
4999 • FILE_BASENAME: Sorts a list of pathnames of files by their basenames.
5001 • NATURAL: Sorts a list of strings using natural order (see strver‐
5003 scmp(3) manual), i.e. such that contiguous digits are compared as
5004 whole numbers. For example: the following list 10.0 1.1 2.1 8.0 2.0
5005 3.1 will be sorted as 1.1 2.0 2.1 3.1 8.0 10.0 if the NATURAL compar‐
5006 ison is selected where it will be sorted as 1.1 10.0 2.0 2.1 3.1 8.0
5007 with the STRING comparison.
5008 Use the CASE keyword to select a case sensitive or case insensitive
5010 sort mode. The <case> option should be one of:
5011 • SENSITIVE: List items are sorted in a case-sensitive manner. This is
5013 the default behavior if the CASE option is not given.
5014 • INSENSITIVE: List items are sorted case insensitively. The order of
5016 items which differ only by upper/lowercase is not specified.
5017 To control the sort order, the ORDER keyword can be given. The <order>
5019 option should be one of:
5020 • ASCENDING: Sorts the list in ascending order. This is the default
5022 behavior when the ORDER option is not given.
5023 • DESCENDING: Sorts the list in descending order.
5025 macro
5027 Start recording a macro for later invocation as a command
5028 macro(<name> [<arg1> ...])
5030 <commands>
5031 endmacro()
5032 Defines a macro named <name> that takes arguments named <arg1>, ...
5034 Commands listed after macro, but before the matching endmacro(), are
5035 not executed until the macro is invoked.
5036 Per legacy, the endmacro() command admits an optional <name> argument.
5038 If used, it must be a verbatim repeat of the argument of the opening
5039 macro command.
5040 See the cmake_policy() command documentation for the behavior of poli‐
5042 cies inside macros.
5043 See the Macro vs Function section below for differences between CMake
5045 macros and functions.
5046 Invocation
5048 The macro invocation is case-insensitive. A macro defined as
5049 macro(foo)
5051 <commands>
5052 endmacro()
5053 can be invoked through any of
5055 foo()
5057 Foo()
5058 FOO()
5059 cmake_language(CALL foo)
5060 and so on. However, it is strongly recommended to stay with the case
5062 chosen in the macro definition. Typically macros use all-lowercase
5063 names.
5064 New in version 3.18: The cmake_language(CALL ...) command can also be
5066 used to invoke the macro.
5067 Arguments
5070 When a macro is invoked, the commands recorded in the macro are first
5071 modified by replacing formal parameters (${arg1}, ...) with the argu‐
5072 ments passed, and then invoked as normal commands.
5073 In addition to referencing the formal parameters you can reference the
5075 values ${ARGC} which will be set to the number of arguments passed into
5076 the function as well as ${ARGV0}, ${ARGV1}, ${ARGV2}, ... which will
5077 have the actual values of the arguments passed in. This facilitates
5078 creating macros with optional arguments.
5079 Furthermore, ${ARGV} holds the list of all arguments given to the macro
5081 and ${ARGN} holds the list of arguments past the last expected argu‐
5082 ment. Referencing to ${ARGV#} arguments beyond ${ARGC} have undefined
5083 behavior. Checking that ${ARGC} is greater than # is the only way to
5084 ensure that ${ARGV#} was passed to the function as an extra argument.
5085 Macro vs Function
5087 The macro command is very similar to the function() command. Nonethe‐
5088 less, there are a few important differences.
5089 In a function, ARGN, ARGC, ARGV and ARGV0, ARGV1, ... are true vari‐
5091 ables in the usual CMake sense. In a macro, they are not, they are
5092 string replacements much like the C preprocessor would do with a macro.
5093 This has a number of consequences, as explained in the Argument Caveats
5094 section below.
5095 Another difference between macros and functions is the control flow. A
5097 function is executed by transferring control from the calling statement
5098 to the function body. A macro is executed as if the macro body were
5099 pasted in place of the calling statement. This has the consequence
5100 that a return() in a macro body does not just terminate execution of
5101 the macro; rather, control is returned from the scope of the macro
5102 call. To avoid confusion, it is recommended to avoid return() in
5103 macros altogether.
5104 Unlike a function, the CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNC‐
5106 TION_LIST_DIR, CMAKE_CURRENT_FUNCTION_LIST_FILE, CMAKE_CURRENT_FUNC‐
5107 TION_LIST_LINE variables are not set for a macro.
5108 Argument Caveats
5110 Since ARGN, ARGC, ARGV, ARGV0 etc. are not variables, you will NOT be
5111 able to use commands like
5112 if(ARGV1) # ARGV1 is not a variable
5114 if(DEFINED ARGV2) # ARGV2 is not a variable
5115 if(ARGC GREATER 2) # ARGC is not a variable
5116 foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
5117 In the first case, you can use if(${ARGV1}). In the second and third
5119 case, the proper way to check if an optional variable was passed to the
5120 macro is to use if(${ARGC} GREATER 2). In the last case, you can use
5121 foreach(loop_var ${ARGN}) but this will skip empty arguments. If you
5122 need to include them, you can use
5123 set(list_var "${ARGN}")
5125 foreach(loop_var IN LISTS list_var)
5126 Note that if you have a variable with the same name in the scope from
5128 which the macro is called, using unreferenced names will use the exist‐
5129 ing variable instead of the arguments. For example:
5130 macro(bar)
5132 foreach(arg IN LISTS ARGN)
5133 <commands>
5134 endforeach()
5135 endmacro()
5136 function(foo)
5138 bar(x y z)
5139 endfunction()
5140 foo(a b c)
5142 Will loop over a;b;c and not over x;y;z as one might have expected. If
5144 you want true CMake variables and/or better CMake scope control you
5145 should look at the function command.
5146 mark_as_advanced
5148 Mark cmake cached variables as advanced.
5149 mark_as_advanced([CLEAR|FORCE] <var1> ...)
5151 Sets the advanced/non-advanced state of the named cached variables.
5153 An advanced variable will not be displayed in any of the cmake GUIs un‐
5155 less the show advanced option is on. In script mode, the ad‐
5156 vanced/non-advanced state has no effect.
5157 If the keyword CLEAR is given then advanced variables are changed back
5159 to unadvanced. If the keyword FORCE is given then the variables are
5160 made advanced. If neither FORCE nor CLEAR is specified, new values
5161 will be marked as advanced, but if a variable already has an ad‐
5162 vanced/non-advanced state, it will not be changed.
5163 Changed in version 3.17: Variables passed to this command which are not
5165 already in the cache are ignored. See policy CMP0102.
5166 math
5169 Evaluate a mathematical expression.
5170 math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])
5172 Evaluates a mathematical <expression> and sets <variable> to the re‐
5174 sulting value. The result of the expression must be representable as a
5175 64-bit signed integer.
5176 The mathematical expression must be given as a string (i.e. enclosed in
5178 double quotation marks). An example is "5 * (10 + 13)". Supported op‐
5179 erators are +, -, *, /, %, |, &, ^, ~, <<, >>, and (...); they have the
5180 same meaning as in C code.
5181 New in version 3.13: Hexadecimal numbers are recognized when prefixed
5183 with 0x, as in C code.
5184 New in version 3.13: The result is formatted according to the option
5187 OUTPUT_FORMAT, where <format> is one of
5188 HEXADECIMAL
5190 Hexadecimal notation as in C code, i. e. starting with "0x".
5191 DECIMAL
5193 Decimal notation. Which is also used if no OUTPUT_FORMAT option
5194 is specified.
5195 For example
5198 math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL) # value is set to "1000"
5200 math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL) # value is set to "0x3e8"
5201 message
5203 Log a message.
5204 Synopsis
5206 General messages
5207 message([<mode>] "message text" ...)
5208 Reporting checks
5210 message(<checkState> "message text" ...)
5211 General messages
5213 message([<mode>] "message text" ...)
5214 Record the specified message text in the log. If more than one message
5216 string is given, they are concatenated into a single message with no
5217 separator between the strings.
5218 The optional <mode> keyword determines the type of message, which in‐
5220 fluences the way the message is handled:
5221 FATAL_ERROR
5223 CMake Error, stop processing and generation.
5224 SEND_ERROR
5226 CMake Error, continue processing, but skip generation.
5227 WARNING
5229 CMake Warning, continue processing.
5230 AUTHOR_WARNING
5232 CMake Warning (dev), continue processing.
5233 DEPRECATION
5235 CMake Deprecation Error or Warning if variable CMAKE_ERROR_DEP‐
5236 RECATED or CMAKE_WARN_DEPRECATED is enabled, respectively, else
5237 no message.
5238 (none) or NOTICE
5240 Important message printed to stderr to attract user's attention.
5241 STATUS The main interesting messages that project users might be inter‐
5243 ested in. Ideally these should be concise, no more than a sin‐
5244 gle line, but still informative.
5245 VERBOSE
5247 Detailed informational messages intended for project users.
5248 These messages should provide additional details that won't be
5249 of interest in most cases, but which may be useful to those
5250 building the project when they want deeper insight into what's
5251 happening.
5252 DEBUG Detailed informational messages intended for developers working
5254 on the project itself as opposed to users who just want to build
5255 it. These messages will not typically be of interest to other
5256 users building the project and will often be closely related to
5257 internal implementation details.
5258 TRACE Fine-grained messages with very low-level implementation de‐
5260 tails. Messages using this log level would normally only be
5261 temporary and would expect to be removed before releasing the
5262 project, packaging up the files, etc.
5263 New in version 3.15: Added the NOTICE, VERBOSE, DEBUG, and TRACE lev‐
5265 els.
5266 The CMake command-line tool displays STATUS to TRACE messages on stdout
5269 with the message preceded by two hyphens and a space. All other mes‐
5270 sage types are sent to stderr and are not prefixed with hyphens. The
5271 CMake GUI displays all messages in its log area. The curses interface
5272 shows STATUS to TRACE messages one at a time on a status line and other
5273 messages in an interactive pop-up box. The --log-level command-line
5274 option to each of these tools can be used to control which messages
5275 will be shown.
5276 New in version 3.17: To make a log level persist between CMake runs,
5278 the CMAKE_MESSAGE_LOG_LEVEL variable can be set instead. Note that the
5279 command line option takes precedence over the cache variable.
5280 New in version 3.16: Messages of log levels NOTICE and below will have
5283 each line preceded by the content of the CMAKE_MESSAGE_INDENT variable
5284 (converted to a single string by concatenating its list items). For
5285 STATUS to TRACE messages, this indenting content will be inserted after
5286 the hyphens.
5287 New in version 3.17: Messages of log levels NOTICE and below can also
5290 have each line preceded with context of the form [some.context.exam‐
5291 ple]. The content between the square brackets is obtained by convert‐
5292 ing the CMAKE_MESSAGE_CONTEXT list variable to a dot-separated string.
5293 The message context will always appear before any indenting content but
5294 after any automatically added leading hyphens. By default, message con‐
5295 text is not shown, it has to be explicitly enabled by giving the cmake
5296 --log-context command-line option or by setting the CMAKE_MESSAGE_CON‐
5297 TEXT_SHOW variable to true. See the CMAKE_MESSAGE_CONTEXT documenta‐
5298 tion for usage examples.
5299 CMake Warning and Error message text displays using a simple markup
5302 language. Non-indented text is formatted in line-wrapped paragraphs
5303 delimited by newlines. Indented text is considered pre-formatted.
5304 Reporting checks
5306 New in version 3.17.
5307 A common pattern in CMake output is a message indicating the start of
5310 some sort of check, followed by another message reporting the result of
5311 that check. For example:
5312 message(STATUS "Looking for someheader.h")
5314 #... do the checks, set checkSuccess with the result
5315 if(checkSuccess)
5316 message(STATUS "Looking for someheader.h - found")
5317 else()
5318 message(STATUS "Looking for someheader.h - not found")
5319 endif()
5320 This can be more robustly and conveniently expressed using the
5322 CHECK_... keyword form of the message() command:
5323 message(<checkState> "message" ...)
5325 where <checkState> must be one of the following:
5327 CHECK_START
5329 Record a concise message about the check about to be per‐
5330 formed.
5331 CHECK_PASS
5333 Record a successful result for a check.
5334 CHECK_FAIL
5336 Record an unsuccessful result for a check.
5337 When recording a check result, the command repeats the message from the
5339 most recently started check for which no result has yet been reported,
5340 then some separator characters and then the message text provided after
5341 the CHECK_PASS or CHECK_FAIL keyword. Check messages are always re‐
5342 ported at STATUS log level.
5343 Checks may be nested and every CHECK_START should have exactly one
5345 matching CHECK_PASS or CHECK_FAIL. The CMAKE_MESSAGE_INDENT variable
5346 can also be used to add indenting to nested checks if desired. For ex‐
5347 ample:
5348 message(CHECK_START "Finding my things")
5350 list(APPEND CMAKE_MESSAGE_INDENT " ")
5351 unset(missingComponents)
5352 message(CHECK_START "Finding partA")
5354 # ... do check, assume we find A
5355 message(CHECK_PASS "found")
5356 message(CHECK_START "Finding partB")
5358 # ... do check, assume we don't find B
5359 list(APPEND missingComponents B)
5360 message(CHECK_FAIL "not found")
5361 list(POP_BACK CMAKE_MESSAGE_INDENT)
5363 if(missingComponents)
5364 message(CHECK_FAIL "missing components: ${missingComponents}")
5365 else()
5366 message(CHECK_PASS "all components found")
5367 endif()
5368 Output from the above would appear something like the following:
5370 -- Finding my things
5372 -- Finding partA
5373 -- Finding partA - found
5374 -- Finding partB
5375 -- Finding partB - not found
5376 -- Finding my things - missing components: B
5377 option
5379 Provide an option that the user can optionally select.
5380 option(<variable> "<help_text>" [value])
5382 Provides an option for the user to select as ON or OFF. If no initial
5384 <value> is provided, OFF is used. If <variable> is already set as a
5385 normal or cache variable, then the command does nothing (see policy
5386 CMP0077).
5387 If you have options that depend on the values of other options, see the
5389 module help for CMakeDependentOption.
5390 return
5392 Return from a file, directory or function.
5393 return()
5395 Returns from a file, directory or function. When this command is en‐
5397 countered in an included file (via include() or find_package()), it
5398 causes processing of the current file to stop and control is returned
5399 to the including file. If it is encountered in a file which is not in‐
5400 cluded by another file, e.g. a CMakeLists.txt, deferred calls sched‐
5401 uled by cmake_language(DEFER) are invoked and control is returned to
5402 the parent directory if there is one. If return is called in a func‐
5403 tion, control is returned to the caller of the function.
5404 Note that a macro, unlike a function, is expanded in place and there‐
5406 fore cannot handle return().
5407 separate_arguments
5409 Parse command-line arguments into a semicolon-separated list.
5410 separate_arguments(<variable> <mode> [PROGRAM [SEPARATE_ARGS]] <args>)
5412 Parses a space-separated string <args> into a list of items, and stores
5414 this list in semicolon-separated standard form in <variable>.
5415 This function is intended for parsing command-line arguments. The en‐
5417 tire command line must be passed as one string in the argument <args>.
5418 The exact parsing rules depend on the operating system. They are spec‐
5420 ified by the <mode> argument which must be one of the following key‐
5421 words:
5422 UNIX_COMMAND
5424 Arguments are separated by unquoted whitespace. Both sin‐
5425 gle-quote and double-quote pairs are respected. A backslash es‐
5426 capes the next literal character (\" is "); there are no special
5427 escapes (\n is just n).
5428 WINDOWS_COMMAND
5430 A Windows command-line is parsed using the same syntax the run‐
5431 time library uses to construct argv at startup. It separates
5432 arguments by whitespace that is not double-quoted. Backslashes
5433 are literal unless they precede double-quotes. See the MSDN ar‐
5434 ticle Parsing C Command-Line Arguments for details.
5435 NATIVE_COMMAND
5437 New in version 3.9.
5438 Proceeds as in WINDOWS_COMMAND mode if the host system is Win‐
5441 dows. Otherwise proceeds as in UNIX_COMMAND mode.
5442 PROGRAM
5444 New in version 3.19.
5445 The first item in <args> is assumed to be an executable and will
5448 be searched in the system search path or left as a full path. If
5449 not found, <variable> will be empty. Otherwise, <variable> is a
5450 list of 2 elements:
5451 0. Absolute path of the program
5453 1. Any command-line arguments present in <args> as a string
5455 For example:
5457 separate_arguments (out UNIX_COMMAND PROGRAM "cc -c main.c")
5459 • First element of the list: /path/to/cc
5461 • Second element of the list: " -c main.c"
5463 SEPARATE_ARGS
5465 When this sub-option of PROGRAM option is specified, com‐
5466 mand-line arguments will be split as well and stored in <vari‐
5467 able>.
5468 For example:
5470 separate_arguments (out UNIX_COMMAND PROGRAM SEPARATE_ARGS "cc -c main.c")
5472 The contents of out will be: /path/to/cc;-c;main.c
5474 separate_arguments(<var>)
5476 Convert the value of <var> to a semi-colon separated list. All spaces
5478 are replaced with ';'. This helps with generating command lines.
5479 set
5481 Set a normal, cache, or environment variable to a given value. See the
5482 cmake-language(7) variables documentation for the scopes and interac‐
5483 tion of normal variables and cache entries.
5484 Signatures of this command that specify a <value>... placeholder expect
5486 zero or more arguments. Multiple arguments will be joined as a semi‐
5487 colon-separated list to form the actual variable value to be set. Zero
5488 arguments will cause normal variables to be unset. See the unset()
5489 command to unset variables explicitly.
5490 Set Normal Variable
5492 set(<variable> <value>... [PARENT_SCOPE])
5493 Sets the given <variable> in the current function or directory scope.
5495 If the PARENT_SCOPE option is given the variable will be set in the
5497 scope above the current scope. Each new directory or function creates
5498 a new scope. This command will set the value of a variable into the
5499 parent directory or calling function (whichever is applicable to the
5500 case at hand). The previous state of the variable's value stays the
5501 same in the current scope (e.g., if it was undefined before, it is
5502 still undefined and if it had a value, it is still that value).
5503 Set Cache Entry
5505 set(<variable> <value>... CACHE <type> <docstring> [FORCE])
5506 Sets the given cache <variable> (cache entry). Since cache entries are
5508 meant to provide user-settable values this does not overwrite existing
5509 cache entries by default. Use the FORCE option to overwrite existing
5510 entries.
5511 The <type> must be specified as one of:
5513 BOOL Boolean ON/OFF value. cmake-gui(1) offers a checkbox.
5515 FILEPATH
5517 Path to a file on disk. cmake-gui(1) offers a file dialog.
5518 PATH Path to a directory on disk. cmake-gui(1) offers a file dialog.
5520 STRING A line of text. cmake-gui(1) offers a text field or a drop-down
5522 selection if the STRINGS cache entry property is set.
5523 INTERNAL
5525 A line of text. cmake-gui(1) does not show internal entries.
5526 They may be used to store variables persistently across runs.
5527 Use of this type implies FORCE.
5528 The <docstring> must be specified as a line of text providing a quick
5530 summary of the option for presentation to cmake-gui(1) users.
5531 If the cache entry does not exist prior to the call or the FORCE option
5533 is given then the cache entry will be set to the given value. Further‐
5534 more, any normal variable binding in the current scope will be removed
5535 to expose the newly cached value to any immediately following evalua‐
5536 tion.
5537 It is possible for the cache entry to exist prior to the call but have
5539 no type set if it was created on the cmake(1) command line by a user
5540 through the -D<var>=<value> option without specifying a type. In this
5541 case the set command will add the type. Furthermore, if the <type> is
5542 PATH or FILEPATH and the <value> provided on the command line is a rel‐
5543 ative path, then the set command will treat the path as relative to the
5544 current working directory and convert it to an absolute path.
5545 Set Environment Variable
5547 set(ENV{<variable>} [<value>])
5548 Sets an Environment Variable to the given value. Subsequent calls of
5550 $ENV{<variable>} will return this new value.
5551 This command affects only the current CMake process, not the process
5553 from which CMake was called, nor the system environment at large, nor
5554 the environment of subsequent build or test processes.
5555 If no argument is given after ENV{<variable>} or if <value> is an empty
5557 string, then this command will clear any existing value of the environ‐
5558 ment variable.
5559 Arguments after <value> are ignored. If extra arguments are found, then
5561 an author warning is issued.
5562 set_directory_properties
5564 Set properties of the current directory and subdirectories.
5565 set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...)
5567 Sets properties of the current directory and its subdirectories in
5569 key-value pairs.
5570 See also the set_property(DIRECTORY) command.
5572 See Directory Properties for the list of properties known to CMake and
5574 their individual documentation for the behavior of each property.
5575 set_property
5577 Set a named property in a given scope.
5578 set_property(<GLOBAL |
5580 DIRECTORY [<dir>] |
5581 TARGET [<target1> ...] |
5582 SOURCE [<src1> ...]
5583 [DIRECTORY <dirs> ...] |
5584 [TARGET_DIRECTORY <targets> ...]
5585 INSTALL [<file1> ...] |
5586 TEST [<test1> ...] |
5587 CACHE [<entry1> ...] >
5588 [APPEND] [APPEND_STRING]
5589 PROPERTY <name> [<value1> ...])
5590 Sets one property on zero or more objects of a scope.
5592 The first argument determines the scope in which the property is set.
5594 It must be one of the following:
5595 GLOBAL Scope is unique and does not accept a name.
5597 DIRECTORY
5599 Scope defaults to the current directory but other directories
5600 (already processed by CMake) may be named by full or relative
5601 path. Relative paths are treated as relative to the current
5602 source directory. See also the set_directory_properties() com‐
5603 mand.
5604 New in version 3.19: <dir> may reference a binary directory.
5606 TARGET Scope may name zero or more existing targets. See also the
5609 set_target_properties() command.
5610 SOURCE Scope may name zero or more source files. By default, source
5612 file properties are only visible to targets added in the same
5613 directory (CMakeLists.txt).
5614 New in version 3.18: Visibility can be set in other directory
5616 scopes using one or both of the following sub-options:
5617 DIRECTORY <dirs>...
5619 The source file property will be set in each of the
5620 <dirs> directories' scopes. CMake must already know
5621 about each of these directories, either by having added
5622 them through a call to add_subdirectory() or it being the
5623 top level source directory. Relative paths are treated
5624 as relative to the current source directory.
5625 New in version 3.19: <dirs> may reference a binary direc‐
5627 tory.
5628 TARGET_DIRECTORY <targets>...
5631 The source file property will be set in each of the di‐
5632 rectory scopes where any of the specified <targets> were
5633 created (the <targets> must therefore already exist).
5634 See also the set_source_files_properties() command.
5637 INSTALL
5639 New in version 3.1.
5640 Scope may name zero or more installed file paths. These are
5643 made available to CPack to influence deployment.
5644 Both the property key and value may use generator expressions.
5646 Specific properties may apply to installed files and/or directo‐
5647 ries.
5648 Path components have to be separated by forward slashes, must be
5650 normalized and are case sensitive.
5651 To reference the installation prefix itself with a relative path
5653 use ..
5654 Currently installed file properties are only defined for the WIX
5656 generator where the given paths are relative to the installation
5657 prefix.
5658 TEST Scope may name zero or more existing tests. See also the
5660 set_tests_properties() command.
5661 CACHE Scope must name zero or more cache existing entries.
5663 The required PROPERTY option is immediately followed by the name of the
5665 property to set. Remaining arguments are used to compose the property
5666 value in the form of a semicolon-separated list.
5667 If the APPEND option is given the list is appended to any existing
5669 property value (except that empty values are ignored and not appended).
5670 If the APPEND_STRING option is given the string is appended to any ex‐
5671 isting property value as string, i.e. it results in a longer string and
5672 not a list of strings. When using APPEND or APPEND_STRING with a prop‐
5673 erty defined to support INHERITED behavior (see define_property()), no
5674 inheriting occurs when finding the initial value to append to. If the
5675 property is not already directly set in the nominated scope, the com‐
5676 mand will behave as though APPEND or APPEND_STRING had not been given.
5677 See the cmake-properties(7) manual for a list of properties in each
5679 scope.
5680 NOTE:
5682 The GENERATED source file property may be globally visible. See its
5683 documentation for details.
5684 site_name
5686 Set the given variable to the name of the computer.
5687 site_name(variable)
5689 On UNIX-like platforms, if the variable HOSTNAME is set, its value will
5691 be executed as a command expected to print out the host name, much like
5692 the hostname command-line tool.
5693 string
5695 String operations.
5696 Synopsis
5698 Search and Replace
5699 string(FIND <string> <substring> <out-var> [...])
5700 string(REPLACE <match-string> <replace-string> <out-var> <input>...)
5701 string(REGEX MATCH <match-regex> <out-var> <input>...)
5702 string(REGEX MATCHALL <match-regex> <out-var> <input>...)
5703 string(REGEX REPLACE <match-regex> <replace-expr> <out-var> <input>...)
5704 Manipulation
5706 string(APPEND <string-var> [<input>...])
5707 string(PREPEND <string-var> [<input>...])
5708 string(CONCAT <out-var> [<input>...])
5709 string(JOIN <glue> <out-var> [<input>...])
5710 string(TOLOWER <string> <out-var>)
5711 string(TOUPPER <string> <out-var>)
5712 string(LENGTH <string> <out-var>)
5713 string(SUBSTRING <string> <begin> <length> <out-var>)
5714 string(STRIP <string> <out-var>)
5715 string(GENEX_STRIP <string> <out-var>)
5716 string(REPEAT <string> <count> <out-var>)
5717 Comparison
5719 string(COMPARE <op> <string1> <string2> <out-var>)
5720 Hashing
5722 string(<HASH> <out-var> <input>)
5723 Generation
5725 string(ASCII <number>... <out-var>)
5726 string(HEX <string> <out-var>)
5727 string(CONFIGURE <string> <out-var> [...])
5728 string(MAKE_C_IDENTIFIER <string> <out-var>)
5729 string(RANDOM [<option>...] <out-var>)
5730 string(TIMESTAMP <out-var> [<format string>] [UTC])
5731 string(UUID <out-var> ...)
5732 JSON
5734 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
5735 {GET | TYPE | LENGTH | REMOVE}
5736 <json-string> <member|index> [<member|index> ...])
5737 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
5738 MEMBER <json-string>
5739 [<member|index> ...] <index>)
5740 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
5741 SET <json-string>
5742 <member|index> [<member|index> ...] <value>)
5743 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
5744 EQUAL <json-string1> <json-string2>)
5745 Search and Replace
5747 Search and Replace With Plain Strings
5748 string(FIND <string> <substring> <output_variable> [REVERSE])
5749 Return the position where the given <substring> was found in the sup‐
5751 plied <string>. If the REVERSE flag was used, the command will search
5752 for the position of the last occurrence of the specified <substring>.
5753 If the <substring> is not found, a position of -1 is returned.
5754 The string(FIND) subcommand treats all strings as ASCII-only charac‐
5756 ters. The index stored in <output_variable> will also be counted in
5757 bytes, so strings containing multi-byte characters may lead to unex‐
5758 pected results.
5759 string(REPLACE <match_string>
5761 <replace_string> <output_variable>
5762 <input> [<input>...])
5763 Replace all occurrences of <match_string> in the <input> with <re‐
5765 place_string> and store the result in the <output_variable>.
5766 Search and Replace With Regular Expressions
5768 string(REGEX MATCH <regular_expression>
5769 <output_variable> <input> [<input>...])
5770 Match the <regular_expression> once and store the match in the <out‐
5772 put_variable>. All <input> arguments are concatenated before matching.
5773 Regular expressions are specified in the subsection just below.
5774 string(REGEX MATCHALL <regular_expression>
5776 <output_variable> <input> [<input>...])
5777 Match the <regular_expression> as many times as possible and store the
5779 matches in the <output_variable> as a list. All <input> arguments are
5780 concatenated before matching.
5781 string(REGEX REPLACE <regular_expression>
5783 <replacement_expression> <output_variable>
5784 <input> [<input>...])
5785 Match the <regular_expression> as many times as possible and substitute
5787 the <replacement_expression> for the match in the output. All <input>
5788 arguments are concatenated before matching.
5789 The <replacement_expression> may refer to parenthesis-delimited subex‐
5791 pressions of the match using \1, \2, ..., \9. Note that two back‐
5792 slashes (\\1) are required in CMake code to get a backslash through ar‐
5793 gument parsing.
5794 Regex Specification
5796 The following characters have special meaning in regular expressions:
5797 ^ Matches at beginning of input
5799 $ Matches at end of input
5801 . Matches any single character
5803 \<char>
5805 Matches the single character specified by <char>. Use this to
5806 match special regex characters, e.g. \. for a literal . or \\
5807 for a literal backslash \. Escaping a non-special character is
5808 unnecessary but allowed, e.g. \a matches a.
5809 [ ] Matches any character(s) inside the brackets
5811 [^ ] Matches any character(s) not inside the brackets
5813 - Inside brackets, specifies an inclusive range between characters
5815 on either side e.g. [a-f] is [abcdef] To match a literal - using
5816 brackets, make it the first or the last character e.g. [+*/-]
5817 matches basic mathematical operators.
5818 * Matches preceding pattern zero or more times
5820 + Matches preceding pattern one or more times
5822 ? Matches preceding pattern zero or once only
5824 | Matches a pattern on either side of the |
5826 () Saves a matched subexpression, which can be referenced in the
5828 REGEX REPLACE operation.
5829 New in version 3.9: All regular expression-related commands, in‐
5831 cluding e.g. if(MATCHES), save subgroup matches in the vari‐
5832 ables CMAKE_MATCH_<n> for <n> 0..9.
5833 *, + and ? have higher precedence than concatenation. | has lower
5836 precedence than concatenation. This means that the regular expression
5837 ^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
5838 matches ab but not abd.
5839 CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
5841 to construct literal tabs, carriage returns, newlines, and backslashes
5842 (respectively) to pass in a regex. For example:
5843 • The quoted argument "[ \t\r\n]" specifies a regex that matches any
5845 single whitespace character.
5846 • The quoted argument "[/\\]" specifies a regex that matches a single
5848 forward slash / or backslash \.
5849 • The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
5851 single "word" character in the C locale.
5852 • The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
5854 the exact string (a+b). Each \\ is parsed in a quoted argument as
5855 just \, so the regex itself is actually \(\a\+\b\). This can alter‐
5856 natively be specified in a bracket argument without having to escape
5857 the backslashes, e.g. [[\(\a\+\b\)]].
5858 Manipulation
5860 string(APPEND <string_variable> [<input>...])
5861 New in version 3.4.
5863 Append all the <input> arguments to the string.
5866 string(PREPEND <string_variable> [<input>...])
5868 New in version 3.10.
5870 Prepend all the <input> arguments to the string.
5873 string(CONCAT <output_variable> [<input>...])
5875 Concatenate all the <input> arguments together and store the result in
5877 the named <output_variable>.
5878 string(JOIN <glue> <output_variable> [<input>...])
5880 New in version 3.12.
5882 Join all the <input> arguments together using the <glue> string and
5885 store the result in the named <output_variable>.
5886 To join a list's elements, prefer to use the JOIN operator from the
5888 list() command. This allows for the elements to have special charac‐
5889 ters like ; in them.
5890 string(TOLOWER <string> <output_variable>)
5892 Convert <string> to lower characters.
5894 string(TOUPPER <string> <output_variable>)
5896 Convert <string> to upper characters.
5898 string(LENGTH <string> <output_variable>)
5900 Store in an <output_variable> a given string's length in bytes. Note
5902 that this means if <string> contains multi-byte characters, the result
5903 stored in <output_variable> will not be the number of characters.
5904 string(SUBSTRING <string> <begin> <length> <output_variable>)
5906 Store in an <output_variable> a substring of a given <string>. If
5908 <length> is -1 the remainder of the string starting at <begin> will be
5909 returned.
5910 Changed in version 3.2: If <string> is shorter than <length> then the
5912 end of the string is used instead. Previous versions of CMake reported
5913 an error in this case.
5914 Both <begin> and <length> are counted in bytes, so care must be exer‐
5917 cised if <string> could contain multi-byte characters.
5918 string(STRIP <string> <output_variable>)
5920 Store in an <output_variable> a substring of a given <string> with
5922 leading and trailing spaces removed.
5923 string(GENEX_STRIP <string> <output_variable>)
5925 New in version 3.1.
5927 Strip any generator expressions from the input <string> and store the
5930 result in the <output_variable>.
5931 string(REPEAT <string> <count> <output_variable>)
5933 New in version 3.15.
5935 Produce the output string as the input <string> repeated <count> times.
5938 Comparison
5940 string(COMPARE LESS <string1> <string2> <output_variable>)
5941 string(COMPARE GREATER <string1> <string2> <output_variable>)
5942 string(COMPARE EQUAL <string1> <string2> <output_variable>)
5943 string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
5944 string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
5945 string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
5946 Compare the strings and store true or false in the <output_variable>.
5948 New in version 3.7: Added the LESS_EQUAL and GREATER_EQUAL options.
5950 Hashing
5953 string(<HASH> <output_variable> <input>)
5954 Compute a cryptographic hash of the <input> string. The supported
5956 <HASH> algorithm names are:
5957 MD5 Message-Digest Algorithm 5, RFC 1321.
5959 SHA1 US Secure Hash Algorithm 1, RFC 3174.
5961 SHA224 US Secure Hash Algorithms, RFC 4634.
5963 SHA256 US Secure Hash Algorithms, RFC 4634.
5965 SHA384 US Secure Hash Algorithms, RFC 4634.
5967 SHA512 US Secure Hash Algorithms, RFC 4634.
5969 SHA3_224
5971 Keccak SHA-3.
5972 SHA3_256
5974 Keccak SHA-3.
5975 SHA3_384
5977 Keccak SHA-3.
5978 SHA3_512
5980 Keccak SHA-3.
5981 New in version 3.8: Added the SHA3_* hash algorithms.
5983 Generation
5986 string(ASCII <number> [<number> ...] <output_variable>)
5987 Convert all numbers into corresponding ASCII characters.
5989 string(HEX <string> <output_variable>)
5991 New in version 3.18.
5993 Convert each byte in the input <string> to its hexadecimal representa‐
5996 tion and store the concatenated hex digits in the <output_variable>.
5997 Letters in the output (a through f) are in lowercase.
5998 string(CONFIGURE <string> <output_variable>
6000 [@ONLY] [ESCAPE_QUOTES])
6001 Transform a <string> like configure_file() transforms a file.
6003 string(MAKE_C_IDENTIFIER <string> <output_variable>)
6005 Convert each non-alphanumeric character in the input <string> to an un‐
6007 derscore and store the result in the <output_variable>. If the first
6008 character of the <string> is a digit, an underscore will also be
6009 prepended to the result.
6010 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
6012 [RANDOM_SEED <seed>] <output_variable>)
6013 Return a random string of given <length> consisting of characters from
6015 the given <alphabet>. Default length is 5 characters and default al‐
6016 phabet is all numbers and upper and lower case letters. If an integer
6017 RANDOM_SEED is given, its value will be used to seed the random number
6018 generator.
6019 string(TIMESTAMP <output_variable> [<format_string>] [UTC])
6021 Write a string representation of the current date and/or time to the
6023 <output_variable>.
6024 If the command is unable to obtain a timestamp, the <output_variable>
6026 will be set to the empty string "".
6027 The optional UTC flag requests the current date/time representation to
6029 be in Coordinated Universal Time (UTC) rather than local time.
6030 The optional <format_string> may contain the following format speci‐
6032 fiers:
6033 %% A literal percent sign (%).
6035 %d The day of the current month (01-31).
6036 %H The hour on a 24-hour clock (00-23).
6037 %I The hour on a 12-hour clock (01-12).
6038 %j The day of the current year (001-366).
6039 %m The month of the current year (01-12).
6040 %b Abbreviated month name (e.g. Oct).
6041 %B Full month name (e.g. October).
6042 %M The minute of the current hour (00-59).
6043 %s Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
6044 %S The second of the current minute.
6045 60 represents a leap second. (00-60)
6046 %U The week number of the current year (00-53).
6047 %w The day of the current week. 0 is Sunday. (0-6)
6048 %a Abbreviated weekday name (e.g. Fri).
6049 %A Full weekday name (e.g. Friday).
6050 %y The last two digits of the current year (00-99)
6051 %Y The current year.
6052 New in version 3.6: %s format specifier (UNIX time).
6054 New in version 3.7: %a and %b format specifiers (abbreviated month and
6057 weekday names).
6058 New in version 3.8: %% specifier (literal %).
6061 New in version 3.7: %A and %B format specifiers (full month and weekday
6064 names).
6065 Unknown format specifiers will be ignored and copied to the output
6068 as-is.
6069 If no explicit <format_string> is given, it will default to:
6071 %Y-%m-%dT%H:%M:%S for local time.
6073 %Y-%m-%dT%H:%M:%SZ for UTC.
6074 New in version 3.8: If the SOURCE_DATE_EPOCH environment variable is
6076 set, its value will be used instead of the current time. See
6077 https://reproducible-builds.org/specs/source-date-epoch/ for details.
6078 string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
6081 TYPE <MD5|SHA1> [UPPER])
6082 New in version 3.1.
6084 Create a universally unique identifier (aka GUID) as per RFC4122 based
6087 on the hash of the combined values of <namespace> (which itself has to
6088 be a valid UUID) and <name>. The hash algorithm can be either MD5
6089 (Version 3 UUID) or SHA1 (Version 5 UUID). A UUID has the format
6090 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where each x represents a lower
6091 case hexadecimal character. Where required, an uppercase representa‐
6092 tion can be requested with the optional UPPER flag.
6093 JSON
6095 New in version 3.19.
6096 Functionality for querying a JSON string.
6099 NOTE:
6101 In each of the following JSON-related subcommands, if the optional
6102 ERROR_VARIABLE argument is given, errors will be reported in <er‐
6103 ror-variable> and the <out-var> will be set to <member|index>-[<mem‐
6104 ber|index>...]-NOTFOUND with the path elements up to the point where
6105 the error occurred, or just NOTFOUND if there is no relevant path.
6106 If an error occurs but the ERROR_VARIABLE option is not present, a
6107 fatal error message is generated. If no error occurs, the <er‐
6108 ror-variable> will be set to NOTFOUND.
6109 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
6111 GET <json-string> <member|index> [<member|index> ...])
6112 Get an element from <json-string> at the location given by the list of
6114 <member|index> arguments. Array and object elements will be returned
6115 as a JSON string. Boolean elements will be returned as ON or OFF.
6116 Null elements will be returned as an empty string. Number and string
6117 types will be returned as strings.
6118 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
6120 TYPE <json-string> <member|index> [<member|index> ...])
6121 Get the type of an element in <json-string> at the location given by
6123 the list of <member|index> arguments. The <out-var> will be set to one
6124 of NULL, NUMBER, STRING, BOOLEAN, ARRAY, or OBJECT.
6125 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
6127 MEMBER <json-string>
6128 [<member|index> ...] <index>)
6129 Get the name of the <index>-th member in <json-string> at the location
6131 given by the list of <member|index> arguments. Requires an element of
6132 object type.
6133 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
6135 LENGTH <json-string> <member|index> [<member|index> ...])
6136 Get the length of an element in <json-string> at the location given by
6138 the list of <member|index> arguments. Requires an element of array or
6139 object type.
6140 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
6142 REMOVE <json-string> <member|index> [<member|index> ...])
6143 Remove an element from <json-string> at the location given by the list
6145 of <member|index> arguments. The JSON string without the removed ele‐
6146 ment will be stored in <out-var>.
6147 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
6149 SET <json-string> <member|index> [<member|index> ...] <value>)
6150 Set an element in <json-string> at the location given by the list of
6152 <member|index> arguments to <value>. The contents of <value> should be
6153 valid JSON.
6154 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
6156 EQUAL <json-string1> <json-string2>)
6157 Compare the two JSON objects given by <json-string1> and <json-string2>
6159 for equality. The contents of <json-string1> and <json-string2> should
6160 be valid JSON. The <out-var> will be set to a true value if the JSON
6161 objects are considered equal, or a false value otherwise.
6162 unset
6164 Unset a variable, cache variable, or environment variable.
6165 Unset Normal Variable or Cache Entry
6167 unset(<variable> [CACHE | PARENT_SCOPE])
6168 Removes a normal variable from the current scope, causing it to become
6170 undefined. If CACHE is present, then a cache variable is removed in‐
6171 stead of a normal variable. Note that when evaluating Variable Refer‐
6172 ences of the form ${VAR}, CMake first searches for a normal variable
6173 with that name. If no such normal variable exists, CMake will then
6174 search for a cache entry with that name. Because of this unsetting a
6175 normal variable can expose a cache variable that was previously hidden.
6176 To force a variable reference of the form ${VAR} to return an empty
6177 string, use set(<variable> ""), which clears the normal variable but
6178 leaves it defined.
6179 If PARENT_SCOPE is present then the variable is removed from the scope
6181 above the current scope. See the same option in the set() command for
6182 further details.
6183 Unset Environment Variable
6185 unset(ENV{<variable>})
6186 Removes <variable> from the currently available Environment Variables.
6188 Subsequent calls of $ENV{<variable>} will return the empty string.
6189 This command affects only the current CMake process, not the process
6191 from which CMake was called, nor the system environment at large, nor
6192 the environment of subsequent build or test processes.
6193 variable_watch
6195 Watch the CMake variable for change.
6196 variable_watch(<variable> [<command>])
6198 If the specified <variable> changes and no <command> is given, a mes‐
6200 sage will be printed to inform about the change.
6201 If <command> is given, this command will be executed instead. The com‐
6203 mand will receive the following arguments: COMMAND(<variable> <access>
6204 <value> <current_list_file> <stack>)
6205 <variable>
6207 Name of the variable being accessed.
6208 <access>
6210 One of READ_ACCESS, UNKNOWN_READ_ACCESS, MODIFIED_ACCESS, UN‐
6211 KNOWN_MODIFIED_ACCESS, or REMOVED_ACCESS. The UNKNOWN_ values
6212 are only used when the variable has never been set. Once set,
6213 they are never used again during the same CMake run, even if the
6214 variable is later unset.
6215 <value>
6217 The value of the variable. On a modification, this is the new
6218 (modified) value of the variable. On removal, the value is
6219 empty.
6220 <current_list_file>
6222 Full path to the file doing the access.
6223 <stack>
6225 List of absolute paths of all files currently on the stack of
6226 file inclusion, with the bottom-most file first and the cur‐
6227 rently processed file (that is, current_list_file) last.
6228 Note that for some accesses such as list(APPEND), the watcher is exe‐
6230 cuted twice, first with a read access and then with a write one. Also
6231 note that an if(DEFINED) query on the variable does not register as an
6232 access and the watcher is not executed.
6233 Only non-cache variables can be watched using this command. Access to
6235 cache variables is never watched. However, the existence of a cache
6236 variable var causes accesses to the non-cache variable var to not use
6237 the UNKNOWN_ prefix, even if a non-cache variable var has never ex‐
6238 isted.
6239 while
6241 Evaluate a group of commands while a condition is true
6242 while(<condition>)
6244 <commands>
6245 endwhile()
6246 All commands between while and the matching endwhile() are recorded
6248 without being invoked. Once the endwhile() is evaluated, the recorded
6249 list of commands is invoked as long as the <condition> is true.
6250 The <condition> has the same syntax and is evaluated using the same
6252 logic as described at length for the if() command.
6253 The commands break() and continue() provide means to escape from the
6255 normal control flow.
6256 Per legacy, the endwhile() command admits an optional <condition> argu‐
6258 ment. If used, it must be a verbatim repeat of the argument of the
6259 opening while command.
6260
6262 These commands are available only in CMake projects.
6263 add_compile_definitions
6265 New in version 3.12.
6266 Add preprocessor definitions to the compilation of source files.
6269 add_compile_definitions(<definition> ...)
6271 Adds preprocessor definitions to the compiler command line.
6273 The preprocessor definitions are added to the COMPILE_DEFINITIONS di‐
6275 rectory property for the current CMakeLists file. They are also added
6276 to the COMPILE_DEFINITIONS target property for each target in the cur‐
6277 rent CMakeLists file.
6278 Definitions are specified using the syntax VAR or VAR=value. Func‐
6280 tion-style definitions are not supported. CMake will automatically es‐
6281 cape the value correctly for the native build system (note that CMake
6282 language syntax may require escapes to specify some values).
6283 Arguments to add_compile_definitions may use "generator expressions"
6285 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6286 for available expressions. See the cmake-buildsystem(7) manual for
6287 more on defining buildsystem properties.
6288 add_compile_options
6290 Add options to the compilation of source files.
6291 add_compile_options(<option> ...)
6293 Adds options to the COMPILE_OPTIONS directory property. These options
6295 are used when compiling targets from the current directory and below.
6296 Arguments
6298 Arguments to add_compile_options may use "generator expressions" with
6299 the syntax $<...>. See the cmake-generator-expressions(7) manual for
6300 available expressions. See the cmake-buildsystem(7) manual for more on
6301 defining buildsystem properties.
6302 The final set of compile or link options used for a target is construc‐
6304 ted by accumulating options from the current target and the usage re‐
6305 quirements of its dependencies. The set of options is de-duplicated to
6306 avoid repetition.
6307 New in version 3.12: While beneficial for individual options, the
6309 de-duplication step can break up option groups. For example, -D A -D B
6310 becomes -D A B. One may specify a group of options using shell-like
6311 quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and
6312 the rest of the option string is parsed using the separate_arguments()
6313 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
6314 -D B.
6315 Example
6318 Since different compilers support different options, a typical use of
6319 this command is in a compiler-specific conditional clause:
6320 if (MSVC)
6322 # warning level 4 and all warnings as errors
6323 add_compile_options(/W4 /WX)
6324 else()
6325 # lots of warnings and all warnings as errors
6326 add_compile_options(-Wall -Wextra -pedantic -Werror)
6327 endif()
6328 See Also
6330 This command can be used to add any options. However, for adding pre‐
6331 processor definitions and include directories it is recommended to use
6332 the more specific commands add_compile_definitions() and include_direc‐
6333 tories().
6334 The command target_compile_options() adds target-specific options.
6336 The source file property COMPILE_OPTIONS adds options to one source
6338 file.
6339 add_custom_command
6341 Add a custom build rule to the generated build system.
6342 There are two main signatures for add_custom_command.
6344 Generating Files
6346 The first signature is for adding a custom command to produce an out‐
6347 put:
6348 add_custom_command(OUTPUT output1 [output2 ...]
6350 COMMAND command1 [ARGS] [args1...]
6351 [COMMAND command2 [ARGS] [args2...] ...]
6352 [MAIN_DEPENDENCY depend]
6353 [DEPENDS [depends...]]
6354 [BYPRODUCTS [files...]]
6355 [IMPLICIT_DEPENDS <lang1> depend1
6356 [<lang2> depend2] ...]
6357 [WORKING_DIRECTORY dir]
6358 [COMMENT comment]
6359 [DEPFILE depfile]
6360 [JOB_POOL job_pool]
6361 [VERBATIM] [APPEND] [USES_TERMINAL]
6362 [COMMAND_EXPAND_LISTS])
6363 This defines a command to generate specified OUTPUT file(s). A target
6365 created in the same directory (CMakeLists.txt file) that specifies any
6366 output of the custom command as a source file is given a rule to gener‐
6367 ate the file using the command at build time. Do not list the output
6368 in more than one independent target that may build in parallel or the
6369 two instances of the rule may conflict (instead use the add_custom_tar‐
6370 get() command to drive the command and make the other targets depend on
6371 that one). In makefile terms this creates a new target in the follow‐
6372 ing form:
6373 OUTPUT: MAIN_DEPENDENCY DEPENDS
6375 COMMAND
6376 The options are:
6378 APPEND Append the COMMAND and DEPENDS option values to the custom com‐
6380 mand for the first output specified. There must have already
6381 been a previous call to this command with the same output.
6382 If the previous call specified the output via a generator ex‐
6384 pression, the output specified by the current call must match in
6385 at least one configuration after evaluating generator expres‐
6386 sions. In this case, the appended commands and dependencies ap‐
6387 ply to all configurations.
6388 The COMMENT, MAIN_DEPENDENCY, and WORKING_DIRECTORY options are
6390 currently ignored when APPEND is given, but may be used in the
6391 future.
6392 BYPRODUCTS
6394 New in version 3.2.
6395 Specify the files the command is expected to produce but whose
6398 modification time may or may not be newer than the dependencies.
6399 If a byproduct name is a relative path it will be interpreted
6400 relative to the build tree directory corresponding to the cur‐
6401 rent source directory. Each byproduct file will be marked with
6402 the GENERATED source file property automatically.
6403 Explicit specification of byproducts is supported by the Ninja
6405 generator to tell the ninja build tool how to regenerate byprod‐
6406 ucts when they are missing. It is also useful when other build
6407 rules (e.g. custom commands) depend on the byproducts. Ninja
6408 requires a build rule for any generated file on which another
6409 rule depends even if there are order-only dependencies to ensure
6410 the byproducts will be available before their dependents build.
6411 The Makefile Generators will remove BYPRODUCTS and other GENER‐
6413 ATED files during make clean.
6414 New in version 3.20: Arguments to BYPRODUCTS may use a re‐
6416 stricted set of generator expressions. Target-dependent expres‐
6417 sions are not permitted.
6418 COMMAND
6421 Specify the command-line(s) to execute at build time. If more
6422 than one COMMAND is specified they will be executed in order,
6423 but not necessarily composed into a stateful shell or batch
6424 script. (To run a full script, use the configure_file() command
6425 or the file(GENERATE) command to create it, and then specify a
6426 COMMAND to launch it.) The optional ARGS argument is for back‐
6427 ward compatibility and will be ignored.
6428 If COMMAND specifies an executable target name (created by the
6430 add_executable() command), it will automatically be replaced by
6431 the location of the executable created at build time if either
6432 of the following is true:
6433 • The target is not being cross-compiled (i.e. the CMAKE_CROSS‐
6435 COMPILING variable is not set to true).
6436 • New in version 3.6: The target is being cross-compiled and an
6438 emulator is provided (i.e. its CROSSCOMPILING_EMULATOR target
6439 property is set). In this case, the contents of CROSSCOMPIL‐
6440 ING_EMULATOR will be prepended to the command before the loca‐
6441 tion of the target executable.
6442 If neither of the above conditions are met, it is assumed that
6445 the command name is a program to be found on the PATH at build
6446 time.
6447 Arguments to COMMAND may use generator expressions. Use the
6449 TARGET_FILE generator expression to refer to the location of a
6450 target later in the command line (i.e. as a command argument
6451 rather than as the command to execute).
6452 Whenever one of the following target based generator expressions
6454 are used as a command to execute or is mentioned in a command
6455 argument, a target-level dependency will be added automatically
6456 so that the mentioned target will be built before any target us‐
6457 ing this custom command (see policy CMP0112).
6458 • TARGET_FILE
6460 • TARGET_LINKER_FILE
6462 • TARGET_SONAME_FILE
6464 • TARGET_PDB_FILE
6466 This target-level dependency does NOT add a file-level depen‐
6468 dency that would cause the custom command to re-run whenever the
6469 executable is recompiled. List target names with the DEPENDS
6470 option to add such file-level dependencies.
6471 COMMENT
6473 Display the given message before the commands are executed at
6474 build time.
6475 DEPENDS
6477 Specify files on which the command depends. Each argument is
6478 converted to a dependency as follows:
6479 1. If the argument is the name of a target (created by the
6481 add_custom_target(), add_executable(), or add_library() com‐
6482 mand) a target-level dependency is created to make sure the
6483 target is built before any target using this custom command.
6484 Additionally, if the target is an executable or library, a
6485 file-level dependency is created to cause the custom command
6486 to re-run whenever the target is recompiled.
6487 2. If the argument is an absolute path, a file-level dependency
6489 is created on that path.
6490 3. If the argument is the name of a source file that has been
6492 added to a target or on which a source file property has been
6493 set, a file-level dependency is created on that source file.
6494 4. If the argument is a relative path and it exists in the cur‐
6496 rent source directory, a file-level dependency is created on
6497 that file in the current source directory.
6498 5. Otherwise, a file-level dependency is created on that path
6500 relative to the current binary directory.
6501 If any dependency is an OUTPUT of another custom command in the
6503 same directory (CMakeLists.txt file), CMake automatically brings
6504 the other custom command into the target in which this command
6505 is built.
6506 New in version 3.16: A target-level dependency is added if any
6508 dependency is listed as BYPRODUCTS of a target or any of its
6509 build events in the same directory to ensure the byproducts will
6510 be available.
6511 If DEPENDS is not specified, the command will run whenever the
6514 OUTPUT is missing; if the command does not actually create the
6515 OUTPUT, the rule will always run.
6516 New in version 3.1: Arguments to DEPENDS may use generator ex‐
6518 pressions.
6519 COMMAND_EXPAND_LISTS
6522 New in version 3.8.
6523 Lists in COMMAND arguments will be expanded, including those
6526 created with generator expressions, allowing COMMAND arguments
6527 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
6528 RIES>,;-I>" foo.cc to be properly expanded.
6529 IMPLICIT_DEPENDS
6531 Request scanning of implicit dependencies of an input file. The
6532 language given specifies the programming language whose corre‐
6533 sponding dependency scanner should be used. Currently only C
6534 and CXX language scanners are supported. The language has to be
6535 specified for every file in the IMPLICIT_DEPENDS list. Depen‐
6536 dencies discovered from the scanning are added to those of the
6537 custom command at build time. Note that the IMPLICIT_DEPENDS
6538 option is currently supported only for Makefile generators and
6539 will be ignored by other generators.
6540 NOTE:
6542 This option cannot be specified at the same time as DEPFILE
6543 option.
6544 JOB_POOL
6546 New in version 3.15.
6547 Specify a pool for the Ninja generator. Incompatible with
6550 USES_TERMINAL, which implies the console pool. Using a pool
6551 that is not defined by JOB_POOLS causes an error by ninja at
6552 build time.
6553 MAIN_DEPENDENCY
6555 Specify the primary input source file to the command. This is
6556 treated just like any value given to the DEPENDS option but also
6557 suggests to Visual Studio generators where to hang the custom
6558 command. Each source file may have at most one command specify‐
6559 ing it as its main dependency. A compile command (i.e. for a li‐
6560 brary or an executable) counts as an implicit main dependency
6561 which gets silently overwritten by a custom command specifica‐
6562 tion.
6563 OUTPUT Specify the output files the command is expected to produce. If
6565 an output name is a relative path it will be interpreted rela‐
6566 tive to the build tree directory corresponding to the current
6567 source directory. Each output file will be marked with the GEN‐
6568 ERATED source file property automatically. If the output of the
6569 custom command is not actually created as a file on disk it
6570 should be marked with the SYMBOLIC source file property.
6571 New in version 3.20: Arguments to OUTPUT may use a restricted
6573 set of generator expressions. Target-dependent expressions are
6574 not permitted.
6575 USES_TERMINAL
6578 New in version 3.2.
6579 The command will be given direct access to the terminal if pos‐
6582 sible. With the Ninja generator, this places the command in the
6583 console pool.
6584 VERBATIM
6586 All arguments to the commands will be escaped properly for the
6587 build tool so that the invoked command receives each argument
6588 unchanged. Note that one level of escapes is still used by the
6589 CMake language processor before add_custom_command even sees the
6590 arguments. Use of VERBATIM is recommended as it enables correct
6591 behavior. When VERBATIM is not given the behavior is platform
6592 specific because there is no protection of tool-specific special
6593 characters.
6594 WORKING_DIRECTORY
6596 Execute the command with the given current working directory.
6597 If it is a relative path it will be interpreted relative to the
6598 build tree directory corresponding to the current source direc‐
6599 tory.
6600 New in version 3.13: Arguments to WORKING_DIRECTORY may use gen‐
6602 erator expressions.
6603 DEPFILE
6606 New in version 3.7.
6607 Specify a .d depfile for the Ninja generator and Makefile Gener‐
6610 ators. A .d file holds dependencies usually emitted by the cus‐
6611 tom command itself. Using DEPFILE with other generators than
6612 Ninja or Makefile Generators is an error.
6613 New in version 3.20: Added the support of Makefile Generators.
6615 If the DEPFILE argument is relative, it should be relative to
6618 CMAKE_CURRENT_BINARY_DIR, and any relative paths inside the DEP‐
6619 FILE should also be relative to CMAKE_CURRENT_BINARY_DIR (see
6620 policy CMP0116. This policy is always NEW for Makefile Genera‐
6621 tors).
6622 NOTE:
6624 For Makefile Generators, this option cannot be specified at
6625 the same time as IMPLICIT_DEPENDS option.
6626 Examples: Generating Files
6628 Custom commands may be used to generate source files. For example, the
6629 code:
6630 add_custom_command(
6632 OUTPUT out.c
6633 COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
6634 -o out.c
6635 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
6636 VERBATIM)
6637 add_library(myLib out.c)
6638 adds a custom command to run someTool to generate out.c and then com‐
6640 pile the generated source as part of a library. The generation rule
6641 will re-run whenever in.txt changes.
6642 New in version 3.20: One may use generator expressions to specify
6644 per-configuration outputs. For example, the code:
6645 add_custom_command(
6647 OUTPUT "out-$<CONFIG>.c"
6648 COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
6649 -o "out-$<CONFIG>.c"
6650 -c "$<CONFIG>"
6651 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
6652 VERBATIM)
6653 add_library(myLib "out-$<CONFIG>.c")
6654 adds a custom command to run someTool to generate out-<config>.c, where
6656 <config> is the build configuration, and then compile the generated
6657 source as part of a library.
6658 Build Events
6661 The second signature adds a custom command to a target such as a li‐
6662 brary or executable. This is useful for performing an operation before
6663 or after building the target. The command becomes part of the target
6664 and will only execute when the target itself is built. If the target
6665 is already built, the command will not execute.
6666 add_custom_command(TARGET <target>
6668 PRE_BUILD | PRE_LINK | POST_BUILD
6669 COMMAND command1 [ARGS] [args1...]
6670 [COMMAND command2 [ARGS] [args2...] ...]
6671 [BYPRODUCTS [files...]]
6672 [WORKING_DIRECTORY dir]
6673 [COMMENT comment]
6674 [VERBATIM] [USES_TERMINAL]
6675 [COMMAND_EXPAND_LISTS])
6676 This defines a new command that will be associated with building the
6678 specified <target>. The <target> must be defined in the current direc‐
6679 tory; targets defined in other directories may not be specified.
6680 When the command will happen is determined by which of the following is
6682 specified:
6683 PRE_BUILD
6685 On Visual Studio Generators, run before any other rules are exe‐
6686 cuted within the target. On other generators, run just before
6687 PRE_LINK commands.
6688 PRE_LINK
6690 Run after sources have been compiled but before linking the bi‐
6691 nary or running the librarian or archiver tool of a static li‐
6692 brary. This is not defined for targets created by the add_cus‐
6693 tom_target() command.
6694 POST_BUILD
6696 Run after all other rules within the target have been executed.
6697 NOTE:
6699 Because generator expressions can be used in custom commands, it is
6700 possible to define COMMAND lines or whole custom commands which
6701 evaluate to empty strings for certain configurations. For Visual
6702 Studio 2010 (and newer) generators these command lines or custom
6703 commands will be omitted for the specific configuration and no
6704 "empty-string-command" will be added.
6705 This allows to add individual build events for every configuration.
6707 Examples: Build Events
6709 A POST_BUILD event may be used to post-process a binary after linking.
6710 For example, the code:
6711 add_executable(myExe myExe.c)
6713 add_custom_command(
6714 TARGET myExe POST_BUILD
6715 COMMAND someHasher -i "$<TARGET_FILE:myExe>"
6716 -o "$<TARGET_FILE:myExe>.hash"
6717 VERBATIM)
6718 will run someHasher to produce a .hash file next to the executable af‐
6720 ter linking.
6721 New in version 3.20: One may use generator expressions to specify
6723 per-configuration byproducts. For example, the code:
6724 add_library(myPlugin MODULE myPlugin.c)
6726 add_custom_command(
6727 TARGET myPlugin POST_BUILD
6728 COMMAND someHasher -i "$<TARGET_FILE:myPlugin>"
6729 --as-code "myPlugin-hash-$<CONFIG>.c"
6730 BYPRODUCTS "myPlugin-hash-$<CONFIG>.c"
6731 VERBATIM)
6732 add_executable(myExe myExe.c "myPlugin-hash-$<CONFIG>.c")
6733 will run someHasher after linking myPlugin, e.g. to produce a .c file
6735 containing code to check the hash of myPlugin that the myExe executable
6736 can use to verify it before loading.
6737 Ninja Multi-Config
6740 New in version 3.20: add_custom_command supports the Ninja Multi-Config
6741 generator's cross-config capabilities. See the generator documentation
6742 for more information.
6743 add_custom_target
6746 Add a target with no output so it will always be built.
6747 add_custom_target(Name [ALL] [command1 [args1...]]
6749 [COMMAND command2 [args2...] ...]
6750 [DEPENDS depend depend depend ... ]
6751 [BYPRODUCTS [files...]]
6752 [WORKING_DIRECTORY dir]
6753 [COMMENT comment]
6754 [JOB_POOL job_pool]
6755 [VERBATIM] [USES_TERMINAL]
6756 [COMMAND_EXPAND_LISTS]
6757 [SOURCES src1 [src2...]])
6758 Adds a target with the given name that executes the given commands.
6760 The target has no output file and is always considered out of date even
6761 if the commands try to create a file with the name of the target. Use
6762 the add_custom_command() command to generate a file with dependencies.
6763 By default nothing depends on the custom target. Use the add_dependen‐
6764 cies() command to add dependencies to or from other targets.
6765 The options are:
6767 ALL Indicate that this target should be added to the default build
6769 target so that it will be run every time (the command cannot be
6770 called ALL).
6771 BYPRODUCTS
6773 New in version 3.2.
6774 Specify the files the command is expected to produce but whose
6777 modification time may or may not be updated on subsequent
6778 builds. If a byproduct name is a relative path it will be in‐
6779 terpreted relative to the build tree directory corresponding to
6780 the current source directory. Each byproduct file will be
6781 marked with the GENERATED source file property automatically.
6782 Explicit specification of byproducts is supported by the Ninja
6784 generator to tell the ninja build tool how to regenerate byprod‐
6785 ucts when they are missing. It is also useful when other build
6786 rules (e.g. custom commands) depend on the byproducts. Ninja
6787 requires a build rule for any generated file on which another
6788 rule depends even if there are order-only dependencies to ensure
6789 the byproducts will be available before their dependents build.
6790 The Makefile Generators will remove BYPRODUCTS and other GENER‐
6792 ATED files during make clean.
6793 New in version 3.20: Arguments to BYPRODUCTS may use a re‐
6795 stricted set of generator expressions. Target-dependent expres‐
6796 sions are not permitted.
6797 COMMAND
6800 Specify the command-line(s) to execute at build time. If more
6801 than one COMMAND is specified they will be executed in order,
6802 but not necessarily composed into a stateful shell or batch
6803 script. (To run a full script, use the configure_file() command
6804 or the file(GENERATE) command to create it, and then specify a
6805 COMMAND to launch it.)
6806 If COMMAND specifies an executable target name (created by the
6808 add_executable() command), it will automatically be replaced by
6809 the location of the executable created at build time if either
6810 of the following is true:
6811 • The target is not being cross-compiled (i.e. the CMAKE_CROSS‐
6813 COMPILING variable is not set to true).
6814 • New in version 3.6: The target is being cross-compiled and an
6816 emulator is provided (i.e. its CROSSCOMPILING_EMULATOR target
6817 property is set). In this case, the contents of CROSSCOMPIL‐
6818 ING_EMULATOR will be prepended to the command before the loca‐
6819 tion of the target executable.
6820 If neither of the above conditions are met, it is assumed that
6823 the command name is a program to be found on the PATH at build
6824 time.
6825 Arguments to COMMAND may use generator expressions. Use the
6827 TARGET_FILE generator expression to refer to the location of a
6828 target later in the command line (i.e. as a command argument
6829 rather than as the command to execute).
6830 Whenever one of the following target based generator expressions
6832 are used as a command to execute or is mentioned in a command
6833 argument, a target-level dependency will be added automatically
6834 so that the mentioned target will be built before this custom
6835 target (see policy CMP0112).
6836 • TARGET_FILE
6838 • TARGET_LINKER_FILE
6840 • TARGET_SONAME_FILE
6842 • TARGET_PDB_FILE
6844 The command and arguments are optional and if not specified an
6846 empty target will be created.
6847 COMMENT
6849 Display the given message before the commands are executed at
6850 build time.
6851 DEPENDS
6853 Reference files and outputs of custom commands created with
6854 add_custom_command() command calls in the same directory (CMake‐
6855 Lists.txt file). They will be brought up to date when the tar‐
6856 get is built.
6857 Changed in version 3.16: A target-level dependency is added if
6859 any dependency is a byproduct of a target or any of its build
6860 events in the same directory to ensure the byproducts will be
6861 available before this target is built.
6862 Use the add_dependencies() command to add dependencies on other
6865 targets.
6866 COMMAND_EXPAND_LISTS
6868 New in version 3.8.
6869 Lists in COMMAND arguments will be expanded, including those
6872 created with generator expressions, allowing COMMAND arguments
6873 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
6874 RIES>,;-I>" foo.cc to be properly expanded.
6875 JOB_POOL
6877 New in version 3.15.
6878 Specify a pool for the Ninja generator. Incompatible with
6881 USES_TERMINAL, which implies the console pool. Using a pool
6882 that is not defined by JOB_POOLS causes an error by ninja at
6883 build time.
6884 SOURCES
6886 Specify additional source files to be included in the custom
6887 target. Specified source files will be added to IDE project
6888 files for convenience in editing even if they have no build
6889 rules.
6890 VERBATIM
6892 All arguments to the commands will be escaped properly for the
6893 build tool so that the invoked command receives each argument
6894 unchanged. Note that one level of escapes is still used by the
6895 CMake language processor before add_custom_target even sees the
6896 arguments. Use of VERBATIM is recommended as it enables correct
6897 behavior. When VERBATIM is not given the behavior is platform
6898 specific because there is no protection of tool-specific special
6899 characters.
6900 USES_TERMINAL
6902 New in version 3.2.
6903 The command will be given direct access to the terminal if pos‐
6906 sible. With the Ninja generator, this places the command in the
6907 console pool.
6908 WORKING_DIRECTORY
6910 Execute the command with the given current working directory.
6911 If it is a relative path it will be interpreted relative to the
6912 build tree directory corresponding to the current source direc‐
6913 tory.
6914 New in version 3.13: Arguments to WORKING_DIRECTORY may use gen‐
6916 erator expressions.
6917 Ninja Multi-Config
6920 New in version 3.20: add_custom_target supports the Ninja Multi-Config
6921 generator's cross-config capabilities. See the generator documentation
6922 for more information.
6923 add_definitions
6926 Add -D define flags to the compilation of source files.
6927 add_definitions(-DFOO -DBAR ...)
6929 Adds definitions to the compiler command line for targets in the cur‐
6931 rent directory, whether added before or after this command is invoked,
6932 and for the ones in sub-directories added after. This command can be
6933 used to add any flags, but it is intended to add preprocessor defini‐
6934 tions.
6935 NOTE:
6937 This command has been superseded by alternatives:
6938 • Use add_compile_definitions() to add preprocessor definitions.
6940 • Use include_directories() to add include directories.
6942 • Use add_compile_options() to add other options.
6944 Flags beginning in -D or /D that look like preprocessor definitions are
6946 automatically added to the COMPILE_DEFINITIONS directory property for
6947 the current directory. Definitions with non-trivial values may be left
6948 in the set of flags instead of being converted for reasons of backwards
6949 compatibility. See documentation of the directory, target, source file
6950 COMPILE_DEFINITIONS properties for details on adding preprocessor defi‐
6951 nitions to specific scopes and configurations.
6952 See the cmake-buildsystem(7) manual for more on defining buildsystem
6954 properties.
6955 add_dependencies
6957 Add a dependency between top-level targets.
6958 add_dependencies(<target> [<target-dependency>]...)
6960 Makes a top-level <target> depend on other top-level targets to ensure
6962 that they build before <target> does. A top-level target is one cre‐
6963 ated by one of the add_executable(), add_library(), or add_custom_tar‐
6964 get() commands (but not targets generated by CMake like install).
6965 Dependencies added to an imported target or an interface library are
6967 followed transitively in its place since the target itself does not
6968 build.
6969 New in version 3.3: Allow adding dependencies to interface libraries.
6971 See the DEPENDS option of add_custom_target() and add_custom_command()
6974 commands for adding file-level dependencies in custom rules. See the
6975 OBJECT_DEPENDS source file property to add file-level dependencies to
6976 object files.
6977 add_executable
6979 Add an executable to the project using the specified source files.
6980 Normal Executables
6982 add_executable(<name> [WIN32] [MACOSX_BUNDLE]
6983 [EXCLUDE_FROM_ALL]
6984 [source1] [source2 ...])
6985 Adds an executable target called <name> to be built from the source
6987 files listed in the command invocation. The <name> corresponds to the
6988 logical target name and must be globally unique within a project. The
6989 actual file name of the executable built is constructed based on con‐
6990 ventions of the native platform (such as <name>.exe or just <name>).
6991 New in version 3.1: Source arguments to add_executable may use "genera‐
6993 tor expressions" with the syntax $<...>. See the cmake-generator-ex‐
6994 pressions(7) manual for available expressions.
6995 New in version 3.11: The source files can be omitted if they are added
6998 later using target_sources().
6999 By default the executable file will be created in the build tree direc‐
7002 tory corresponding to the source tree directory in which the command
7003 was invoked. See documentation of the RUNTIME_OUTPUT_DIRECTORY target
7004 property to change this location. See documentation of the OUTPUT_NAME
7005 target property to change the <name> part of the final file name.
7006 If WIN32 is given the property WIN32_EXECUTABLE will be set on the tar‐
7008 get created. See documentation of that target property for details.
7009 If MACOSX_BUNDLE is given the corresponding property will be set on the
7011 created target. See documentation of the MACOSX_BUNDLE target property
7012 for details.
7013 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
7015 the created target. See documentation of the EXCLUDE_FROM_ALL target
7016 property for details.
7017 See the cmake-buildsystem(7) manual for more on defining buildsystem
7019 properties.
7020 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
7022 cessed, and you want to have the original sources reachable from within
7023 IDE.
7024 Imported Executables
7026 add_executable(<name> IMPORTED [GLOBAL])
7027 An IMPORTED executable target references an executable file located
7029 outside the project. No rules are generated to build it, and the IM‐
7030 PORTED target property is True. The target name has scope in the di‐
7031 rectory in which it is created and below, but the GLOBAL option extends
7032 visibility. It may be referenced like any target built within the
7033 project. IMPORTED executables are useful for convenient reference from
7034 commands like add_custom_command(). Details about the imported exe‐
7035 cutable are specified by setting properties whose names begin in IM‐
7036 PORTED_. The most important such property is IMPORTED_LOCATION (and
7037 its per-configuration version IMPORTED_LOCATION_<CONFIG>) which speci‐
7038 fies the location of the main executable file on disk. See documenta‐
7039 tion of the IMPORTED_* properties for more information.
7040 Alias Executables
7042 add_executable(<name> ALIAS <target>)
7043 Creates an Alias Target, such that <name> can be used to refer to <tar‐
7045 get> in subsequent commands. The <name> does not appear in the gener‐
7046 ated buildsystem as a make target. The <target> may not be an ALIAS.
7047 New in version 3.11: An ALIAS can target a GLOBAL Imported Target
7049 New in version 3.18: An ALIAS can target a non-GLOBAL Imported Target.
7052 Such alias is scoped to the directory in which it is created and subdi‐
7053 rectories. The ALIAS_GLOBAL target property can be used to check if
7054 the alias is global or not.
7055 ALIAS targets can be used as targets to read properties from, executa‐
7058 bles for custom commands and custom targets. They can also be tested
7059 for existence with the regular if(TARGET) subcommand. The <name> may
7060 not be used to modify properties of <target>, that is, it may not be
7061 used as the operand of set_property(), set_target_properties(), tar‐
7062 get_link_libraries() etc. An ALIAS target may not be installed or ex‐
7063 ported.
7064 add_library
7066 Add a library to the project using the specified source files.
7067 Normal Libraries
7069 add_library(<name> [STATIC | SHARED | MODULE]
7070 [EXCLUDE_FROM_ALL]
7071 [<source>...])
7072 Adds a library target called <name> to be built from the source files
7074 listed in the command invocation. The <name> corresponds to the logi‐
7075 cal target name and must be globally unique within a project. The ac‐
7076 tual file name of the library built is constructed based on conventions
7077 of the native platform (such as lib<name>.a or <name>.lib).
7078 New in version 3.1: Source arguments to add_library may use "generator
7080 expressions" with the syntax $<...>. See the cmake-generator-expres‐
7081 sions(7) manual for available expressions.
7082 New in version 3.11: The source files can be omitted if they are added
7085 later using target_sources().
7086 STATIC, SHARED, or MODULE may be given to specify the type of library
7089 to be created. STATIC libraries are archives of object files for use
7090 when linking other targets. SHARED libraries are linked dynamically
7091 and loaded at runtime. MODULE libraries are plugins that are not
7092 linked into other targets but may be loaded dynamically at runtime us‐
7093 ing dlopen-like functionality. If no type is given explicitly the type
7094 is STATIC or SHARED based on whether the current value of the variable
7095 BUILD_SHARED_LIBS is ON. For SHARED and MODULE libraries the POSI‐
7096 TION_INDEPENDENT_CODE target property is set to ON automatically. A
7097 SHARED library may be marked with the FRAMEWORK target property to cre‐
7098 ate an macOS Framework.
7099 New in version 3.8: A STATIC library may be marked with the FRAMEWORK
7101 target property to create a static Framework.
7102 If a library does not export any symbols, it must not be declared as a
7105 SHARED library. For example, a Windows resource DLL or a managed
7106 C++/CLI DLL that exports no unmanaged symbols would need to be a MODULE
7107 library. This is because CMake expects a SHARED library to always have
7108 an associated import library on Windows.
7109 By default the library file will be created in the build tree directory
7111 corresponding to the source tree directory in which the command was in‐
7112 voked. See documentation of the ARCHIVE_OUTPUT_DIRECTORY, LIBRARY_OUT‐
7113 PUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY target properties to change
7114 this location. See documentation of the OUTPUT_NAME target property to
7115 change the <name> part of the final file name.
7116 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
7118 the created target. See documentation of the EXCLUDE_FROM_ALL target
7119 property for details.
7120 See the cmake-buildsystem(7) manual for more on defining buildsystem
7122 properties.
7123 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
7125 cessed, and you want to have the original sources reachable from within
7126 IDE.
7127 Object Libraries
7129 add_library(<name> OBJECT [<source>...])
7130 Creates an Object Library. An object library compiles source files but
7132 does not archive or link their object files into a library. Instead
7133 other targets created by add_library() or add_executable() may refer‐
7134 ence the objects using an expression of the form $<TARGET_OBJECTS:ob‐
7135 jlib> as a source, where objlib is the object library name. For exam‐
7136 ple:
7137 add_library(... $<TARGET_OBJECTS:objlib> ...)
7139 add_executable(... $<TARGET_OBJECTS:objlib> ...)
7140 will include objlib's object files in a library and an executable along
7142 with those compiled from their own sources. Object libraries may con‐
7143 tain only sources that compile, header files, and other files that
7144 would not affect linking of a normal library (e.g. .txt). They may
7145 contain custom commands generating such sources, but not PRE_BUILD,
7146 PRE_LINK, or POST_BUILD commands. Some native build systems (such as
7147 Xcode) may not like targets that have only object files, so consider
7148 adding at least one real source file to any target that references
7149 $<TARGET_OBJECTS:objlib>.
7150 New in version 3.12: Object libraries can be linked to with tar‐
7152 get_link_libraries().
7153 Interface Libraries
7156 add_library(<name> INTERFACE)
7157 Creates an Interface Library. An INTERFACE library target does not
7159 compile sources and does not produce a library artifact on disk. How‐
7160 ever, it may have properties set on it and it may be installed and ex‐
7161 ported. Typically, INTERFACE_* properties are populated on an inter‐
7162 face target using the commands:
7163 • set_property(),
7165 • target_link_libraries(INTERFACE),
7167 • target_link_options(INTERFACE),
7169 • target_include_directories(INTERFACE),
7171 • target_compile_options(INTERFACE),
7173 • target_compile_definitions(INTERFACE), and
7175 • target_sources(INTERFACE),
7177 and then it is used as an argument to target_link_libraries() like any
7179 other target.
7180 An interface library created with the above signature has no source
7182 files itself and is not included as a target in the generated buildsys‐
7183 tem.
7184 New in version 3.15: An interface library can have PUBLIC_HEADER and
7186 PRIVATE_HEADER properties. The headers specified by those properties
7187 can be installed using the install(TARGETS) command.
7188 New in version 3.19: An interface library target may be created with
7191 source files:
7192 add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])
7194 Source files may be listed directly in the add_library call or added
7196 later by calls to target_sources() with the PRIVATE or PUBLIC keywords.
7197 If an interface library has source files (i.e. the SOURCES target prop‐
7199 erty is set), it will appear in the generated buildsystem as a build
7200 target much like a target defined by the add_custom_target() command.
7201 It does not compile any sources, but does contain build rules for cus‐
7202 tom commands created by the add_custom_command() command.
7203 NOTE:
7206 In most command signatures where the INTERFACE keyword appears, the
7207 items listed after it only become part of that target's usage re‐
7208 quirements and are not part of the target's own settings. However,
7209 in this signature of add_library, the INTERFACE keyword refers to
7210 the library type only. Sources listed after it in the add_library
7211 call are PRIVATE to the interface library and do not appear in its
7212 INTERFACE_SOURCES target property.
7213 Imported Libraries
7215 add_library(<name> <type> IMPORTED [GLOBAL])
7216 Creates an IMPORTED library target called <name>. No rules are gener‐
7218 ated to build it, and the IMPORTED target property is True. The target
7219 name has scope in the directory in which it is created and below, but
7220 the GLOBAL option extends visibility. It may be referenced like any
7221 target built within the project. IMPORTED libraries are useful for
7222 convenient reference from commands like target_link_libraries(). De‐
7223 tails about the imported library are specified by setting properties
7224 whose names begin in IMPORTED_ and INTERFACE_.
7225 The <type> must be one of:
7227 STATIC, SHARED, MODULE, UNKNOWN
7229 References a library file located outside the project. The IM‐
7230 PORTED_LOCATION target property (or its per-configuration vari‐
7231 ant IMPORTED_LOCATION_<CONFIG>) specifies the location of the
7232 main library file on disk:
7233 • For a SHARED library on most non-Windows platforms, the main
7235 library file is the .so or .dylib file used by both linkers
7236 and dynamic loaders. If the referenced library file has a
7237 SONAME (or on macOS, has a LC_ID_DYLIB starting in @rpath/),
7238 the value of that field should be set in the IMPORTED_SONAME
7239 target property. If the referenced library file does not have
7240 a SONAME, but the platform supports it, then the IM‐
7241 PORTED_NO_SONAME target property should be set.
7242 • For a SHARED library on Windows, the IMPORTED_IMPLIB target
7244 property (or its per-configuration variant IMPORTED_IM‐
7245 PLIB_<CONFIG>) specifies the location of the DLL import li‐
7246 brary file (.lib or .dll.a) on disk, and the IMPORTED_LOCATION
7247 is the location of the .dll runtime library (and is optional).
7248 Additional usage requirements may be specified in INTERFACE_*
7250 properties.
7251 An UNKNOWN library type is typically only used in the implemen‐
7253 tation of Find Modules. It allows the path to an imported li‐
7254 brary (often found using the find_library() command) to be used
7255 without having to know what type of library it is. This is es‐
7256 pecially useful on Windows where a static library and a DLL's
7257 import library both have the same file extension.
7258 OBJECT References a set of object files located outside the project.
7260 The IMPORTED_OBJECTS target property (or its per-configuration
7261 variant IMPORTED_OBJECTS_<CONFIG>) specifies the locations of
7262 object files on disk. Additional usage requirements may be
7263 specified in INTERFACE_* properties.
7264 INTERFACE
7266 Does not reference any library or object files on disk, but may
7267 specify usage requirements in INTERFACE_* properties.
7268 See documentation of the IMPORTED_* and INTERFACE_* properties for more
7270 information.
7271 Alias Libraries
7273 add_library(<name> ALIAS <target>)
7274 Creates an Alias Target, such that <name> can be used to refer to <tar‐
7276 get> in subsequent commands. The <name> does not appear in the gener‐
7277 ated buildsystem as a make target. The <target> may not be an ALIAS.
7278 New in version 3.11: An ALIAS can target a GLOBAL Imported Target
7280 New in version 3.18: An ALIAS can target a non-GLOBAL Imported Target.
7283 Such alias is scoped to the directory in which it is created and below.
7284 The ALIAS_GLOBAL target property can be used to check if the alias is
7285 global or not.
7286 ALIAS targets can be used as linkable targets and as targets to read
7289 properties from. They can also be tested for existence with the regu‐
7290 lar if(TARGET) subcommand. The <name> may not be used to modify prop‐
7291 erties of <target>, that is, it may not be used as the operand of
7292 set_property(), set_target_properties(), target_link_libraries() etc.
7293 An ALIAS target may not be installed or exported.
7294 add_link_options
7296 New in version 3.13.
7297 Add options to the link step for executable, shared library or module
7300 library targets in the current directory and below that are added after
7301 this command is invoked.
7302 add_link_options(<option> ...)
7304 This command can be used to add any link options, but alternative com‐
7306 mands exist to add libraries (target_link_libraries() or link_li‐
7307 braries()). See documentation of the directory and target LINK_OPTIONS
7308 properties.
7309 NOTE:
7311 This command cannot be used to add options for static library tar‐
7312 gets, since they do not use a linker. To add archiver or MSVC li‐
7313 brarian flags, see the STATIC_LIBRARY_OPTIONS target property.
7314 Arguments to add_link_options may use "generator expressions" with the
7316 syntax $<...>. See the cmake-generator-expressions(7) manual for
7317 available expressions. See the cmake-buildsystem(7) manual for more on
7318 defining buildsystem properties.
7319 New in version 3.18: When a device link step is involved, which is con‐
7321 trolled by CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS
7322 properties and policy CMP0105, the raw options will be delivered to the
7323 host and device link steps (wrapped in -Xcompiler or equivalent for de‐
7324 vice link). Options wrapped with $<DEVICE_LINK:...> generator expres‐
7325 sion will be used only for the device link step. Options wrapped with
7326 $<HOST_LINK:...> generator expression will be used only for the host
7327 link step.
7328 The final set of compile or link options used for a target is construc‐
7331 ted by accumulating options from the current target and the usage re‐
7332 quirements of its dependencies. The set of options is de-duplicated to
7333 avoid repetition.
7334 New in version 3.12: While beneficial for individual options, the
7336 de-duplication step can break up option groups. For example, -D A -D B
7337 becomes -D A B. One may specify a group of options using shell-like
7338 quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and
7339 the rest of the option string is parsed using the separate_arguments()
7340 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
7341 -D B.
7342 To pass options to the linker tool, each compiler driver has its own
7345 syntax. The LINKER: prefix and , separator can be used to specify, in
7346 a portable way, options to pass to the linker tool. LINKER: is replaced
7347 by the appropriate driver option and , by the appropriate driver sepa‐
7348 rator. The driver prefix and driver separator are given by the values
7349 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAP‐
7350 PER_FLAG_SEP variables.
7351 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
7353 Clang and -Wl,-z,defs for GNU GCC.
7354 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
7356 sion.
7357 The LINKER: prefix supports, as an alternative syntax, specification of
7359 arguments using the SHELL: prefix and space as separator. The previous
7360 example then becomes "LINKER:SHELL:-z defs".
7361 NOTE:
7363 Specifying the SHELL: prefix anywhere other than at the beginning of
7364 the LINKER: prefix is not supported.
7365 add_subdirectory
7367 Add a subdirectory to the build.
7368 add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
7370 Adds a subdirectory to the build. The source_dir specifies the direc‐
7372 tory in which the source CMakeLists.txt and code files are located. If
7373 it is a relative path it will be evaluated with respect to the current
7374 directory (the typical usage), but it may also be an absolute path.
7375 The binary_dir specifies the directory in which to place the output
7376 files. If it is a relative path it will be evaluated with respect to
7377 the current output directory, but it may also be an absolute path. If
7378 binary_dir is not specified, the value of source_dir, before expanding
7379 any relative path, will be used (the typical usage). The CMake‐
7380 Lists.txt file in the specified source directory will be processed im‐
7381 mediately by CMake before processing in the current input file contin‐
7382 ues beyond this command.
7383 If the EXCLUDE_FROM_ALL argument is provided then targets in the subdi‐
7385 rectory will not be included in the ALL target of the parent directory
7386 by default, and will be excluded from IDE project files. Users must
7387 explicitly build targets in the subdirectory. This is meant for use
7388 when the subdirectory contains a separate part of the project that is
7389 useful but not necessary, such as a set of examples. Typically the
7390 subdirectory should contain its own project() command invocation so
7391 that a full build system will be generated in the subdirectory (such as
7392 a VS IDE solution file). Note that inter-target dependencies supersede
7393 this exclusion. If a target built by the parent project depends on a
7394 target in the subdirectory, the dependee target will be included in the
7395 parent project build system to satisfy the dependency.
7396 add_test
7398 Add a test to the project to be run by ctest(1).
7399 add_test(NAME <name> COMMAND <command> [<arg>...]
7401 [CONFIGURATIONS <config>...]
7402 [WORKING_DIRECTORY <dir>]
7403 [COMMAND_EXPAND_LISTS])
7404 Adds a test called <name>. The test name may contain arbitrary charac‐
7406 ters, expressed as a Quoted Argument or Bracket Argument if necessary.
7407 See policy CMP0110. The options are:
7408 COMMAND
7410 Specify the test command-line. If <command> specifies an exe‐
7411 cutable target (created by add_executable()) it will automati‐
7412 cally be replaced by the location of the executable created at
7413 build time.
7414 CONFIGURATIONS
7416 Restrict execution of the test only to the named configurations.
7417 WORKING_DIRECTORY
7419 Set the WORKING_DIRECTORY test property to specify the working
7420 directory in which to execute the test. If not specified the
7421 test will be run with the current working directory set to the
7422 build directory corresponding to the current source directory.
7423 COMMAND_EXPAND_LISTS
7425 New in version 3.16.
7426 Lists in COMMAND arguments will be expanded, including those
7429 created with generator expressions.
7430 The given test command is expected to exit with code 0 to pass and
7432 non-zero to fail, or vice-versa if the WILL_FAIL test property is set.
7433 Any output written to stdout or stderr will be captured by ctest(1) but
7434 does not affect the pass/fail status unless the PASS_REGULAR_EXPRES‐
7435 SION, FAIL_REGULAR_EXPRESSION or SKIP_REGULAR_EXPRESSION test property
7436 is used.
7437 New in version 3.16: Added SKIP_REGULAR_EXPRESSION property.
7439 The COMMAND and WORKING_DIRECTORY options may use "generator expres‐
7442 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
7443 manual for available expressions.
7444 Example usage:
7446 add_test(NAME mytest
7448 COMMAND testDriver --config $<CONFIG>
7449 --exe $<TARGET_FILE:myexe>)
7450 This creates a test mytest whose command runs a testDriver tool passing
7452 the configuration name and the full path to the executable file pro‐
7453 duced by target myexe.
7454 NOTE:
7456 CMake will generate tests only if the enable_testing() command has
7457 been invoked. The CTest module invokes the command automatically
7458 unless the BUILD_TESTING option is turned OFF.
7459 ----
7462 add_test(<name> <command> [<arg>...])
7466 Add a test called <name> with the given command-line. Unlike the above
7468 NAME signature no transformation is performed on the command-line to
7469 support target names or generator expressions.
7470 aux_source_directory
7472 Find all source files in a directory.
7473 aux_source_directory(<dir> <variable>)
7475 Collects the names of all the source files in the specified directory
7477 and stores the list in the <variable> provided. This command is in‐
7478 tended to be used by projects that use explicit template instantiation.
7479 Template instantiation files can be stored in a Templates subdirectory
7480 and collected automatically using this command to avoid manually list‐
7481 ing all instantiations.
7482 It is tempting to use this command to avoid writing the list of source
7484 files for a library or executable target. While this seems to work,
7485 there is no way for CMake to generate a build system that knows when a
7486 new source file has been added. Normally the generated build system
7487 knows when it needs to rerun CMake because the CMakeLists.txt file is
7488 modified to add a new source. When the source is just added to the di‐
7489 rectory without modifying this file, one would have to manually rerun
7490 CMake to generate a build system incorporating the new file.
7491 build_command
7493 Get a command line to build the current project. This is mainly in‐
7494 tended for internal use by the CTest module.
7495 build_command(<variable>
7497 [CONFIGURATION <config>]
7498 [TARGET <target>]
7499 [PROJECT_NAME <projname>] # legacy, causes warning
7500 )
7501 Sets the given <variable> to a command-line string of the form:
7503 <cmake> --build . [--config <config>] [--target <target>...] [-- -i]
7505 where <cmake> is the location of the cmake(1) command-line tool, and
7507 <config> and <target> are the values provided to the CONFIGURATION and
7508 TARGET options, if any. The trailing -- -i option is added for Make‐
7509 file Generators if policy CMP0061 is not set to NEW.
7510 When invoked, this cmake --build command line will launch the underly‐
7512 ing build system tool.
7513 build_command(<cachevariable> <makecommand>)
7515 This second signature is deprecated, but still available for backwards
7517 compatibility. Use the first signature instead.
7518 It sets the given <cachevariable> to a command-line string as above but
7520 without the --target option. The <makecommand> is ignored but should
7521 be the full path to devenv, nmake, make or one of the end user build
7522 tools for legacy invocations.
7523 NOTE:
7525 In CMake versions prior to 3.0 this command returned a command line
7526 that directly invokes the native build tool for the current genera‐
7527 tor. Their implementation of the PROJECT_NAME option had no useful
7528 effects, so CMake now warns on use of the option.
7529 create_test_sourcelist
7531 Create a test driver and source list for building test programs.
7532 create_test_sourcelist(sourceListName driverName
7534 test1 test2 test3
7535 EXTRA_INCLUDE include.h
7536 FUNCTION function)
7537 A test driver is a program that links together many small tests into a
7539 single executable. This is useful when building static executables
7540 with large libraries to shrink the total required size. The list of
7541 source files needed to build the test driver will be in sourceListName.
7542 driverName is the name of the test driver program. The rest of the ar‐
7543 guments consist of a list of test source files, can be semicolon sepa‐
7544 rated. Each test source file should have a function in it that is the
7545 same name as the file with no extension (foo.cxx should have int
7546 foo(int, char*[]);) driverName will be able to call each of the tests
7547 by name on the command line. If EXTRA_INCLUDE is specified, then the
7548 next argument is included into the generated file. If FUNCTION is
7549 specified, then the next argument is taken as a function name that is
7550 passed a pointer to ac and av. This can be used to add extra command
7551 line processing to each test. The CMAKE_TESTDRIVER_BEFORE_TESTMAIN
7552 cmake variable can be set to have code that will be placed directly be‐
7553 fore calling the test main function. CMAKE_TESTDRIVER_AFTER_TESTMAIN
7554 can be set to have code that will be placed directly after the call to
7555 the test main function.
7556 define_property
7558 Define and document custom properties.
7559 define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
7561 TEST | VARIABLE | CACHED_VARIABLE>
7562 PROPERTY <name> [INHERITED]
7563 BRIEF_DOCS <brief-doc> [docs...]
7564 FULL_DOCS <full-doc> [docs...])
7565 Defines one property in a scope for use with the set_property() and
7567 get_property() commands. This is primarily useful to associate docu‐
7568 mentation with property names that may be retrieved with the get_prop‐
7569 erty() command. The first argument determines the kind of scope in
7570 which the property should be used. It must be one of the following:
7571 GLOBAL = associated with the global namespace
7573 DIRECTORY = associated with one directory
7574 TARGET = associated with one target
7575 SOURCE = associated with one source file
7576 TEST = associated with a test named with add_test
7577 VARIABLE = documents a CMake language variable
7578 CACHED_VARIABLE = documents a CMake cache variable
7579 Note that unlike set_property() and get_property() no actual scope
7581 needs to be given; only the kind of scope is important.
7582 The required PROPERTY option is immediately followed by the name of the
7584 property being defined.
7585 If the INHERITED option is given, then the get_property() command will
7587 chain up to the next higher scope when the requested property is not
7588 set in the scope given to the command.
7589 • DIRECTORY scope chains to its parent directory's scope, continuing
7591 the walk up parent directories until a directory has the property set
7592 or there are no more parents. If still not found at the top level
7593 directory, it chains to the GLOBAL scope.
7594 • TARGET, SOURCE and TEST properties chain to DIRECTORY scope, includ‐
7596 ing further chaining up the directories, etc. as needed.
7597 Note that this scope chaining behavior only applies to calls to
7599 get_property(), get_directory_property(), get_target_property(),
7600 get_source_file_property() and get_test_property(). There is no inher‐
7601 iting behavior when setting properties, so using APPEND or AP‐
7602 PEND_STRING with the set_property() command will not consider inherited
7603 values when working out the contents to append to.
7604 The BRIEF_DOCS and FULL_DOCS options are followed by strings to be as‐
7606 sociated with the property as its brief and full documentation. Corre‐
7607 sponding options to the get_property() command will retrieve the docu‐
7608 mentation.
7609 enable_language
7611 Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
7612 enable_language(<lang> [OPTIONAL] )
7614 Enables support for the named language in CMake. This is the same as
7616 the project() command but does not create any of the extra variables
7617 that are created by the project command. Example languages are CXX, C,
7618 CUDA, OBJC, OBJCXX, Fortran, ISPC, and ASM.
7619 New in version 3.8: Added CUDA support.
7621 New in version 3.16: Added OBJC and OBJCXX support.
7624 New in version 3.18: Added ISPC support.
7627 If enabling ASM, enable it last so that CMake can check whether compil‐
7630 ers for other languages like C work for assembly too.
7631 This command must be called in file scope, not in a function call.
7633 Furthermore, it must be called in the highest directory common to all
7634 targets using the named language directly for compiling sources or in‐
7635 directly through link dependencies. It is simplest to enable all
7636 needed languages in the top-level directory of a project.
7637 The OPTIONAL keyword is a placeholder for future implementation and
7639 does not currently work. Instead you can use the CheckLanguage module
7640 to verify support before enabling.
7641 enable_testing
7643 Enable testing for current directory and below.
7644 enable_testing()
7646 Enables testing for this directory and below.
7648 This command should be in the source directory root because ctest ex‐
7650 pects to find a test file in the build directory root.
7651 This command is automatically invoked when the CTest module is in‐
7653 cluded, except if the BUILD_TESTING option is turned off.
7654 See also the add_test() command.
7656 export
7658 Export targets from the build tree for use by outside projects.
7659 export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
7661 Creates a file <filename> that may be included by outside projects to
7663 import targets from the current project's build tree. This is useful
7664 during cross-compiling to build utility executables that can run on the
7665 host platform in one project and then import them into another project
7666 being compiled for the target platform. If the NAMESPACE option is
7667 given the <namespace> string will be prepended to all target names
7668 written to the file.
7669 Target installations are associated with the export <export-name> using
7671 the EXPORT option of the install(TARGETS) command.
7672 The file created by this command is specific to the build tree and
7674 should never be installed. See the install(EXPORT) command to export
7675 targets from an installation tree.
7676 The properties set on the generated IMPORTED targets will have the same
7678 values as the final values of the input TARGETS.
7679 export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
7681 [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
7682 This signature is similar to the EXPORT signature, but targets are
7684 listed explicitly rather than specified as an export-name. If the AP‐
7685 PEND option is given the generated code will be appended to the file
7686 instead of overwriting it. The EXPORT_LINK_INTERFACE_LIBRARIES key‐
7687 word, if present, causes the contents of the properties matching (IM‐
7688 PORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when pol‐
7689 icy CMP0022 is NEW. If a library target is included in the export but
7690 a target to which it links is not included the behavior is unspecified.
7691 NOTE:
7693 Object Libraries under Xcode have special handling if multiple ar‐
7694 chitectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
7695 they will be exported as Interface Libraries with no object files
7696 available to clients. This is sufficient to satisfy transitive us‐
7697 age requirements of other targets that link to the object libraries
7698 in their implementation.
7699 export(PACKAGE <PackageName>)
7701 Store the current build directory in the CMake user package registry
7703 for package <PackageName>. The find_package() command may consider the
7704 directory while searching for package <PackageName>. This helps depen‐
7705 dent projects find and use a package from the current project's build
7706 tree without help from the user. Note that the entry in the package
7707 registry that this command creates works only in conjunction with a
7708 package configuration file (<PackageName>Config.cmake) that works with
7709 the build tree. In some cases, for example for packaging and for system
7710 wide installations, it is not desirable to write the user package reg‐
7711 istry.
7712 Changed in version 3.1: If the CMAKE_EXPORT_NO_PACKAGE_REGISTRY vari‐
7714 able is enabled, the export(PACKAGE) command will do nothing.
7715 Changed in version 3.15: By default the export(PACKAGE) command does
7718 nothing (see policy CMP0090) because populating the user package reg‐
7719 istry has effects outside the source and build trees. Set the
7720 CMAKE_EXPORT_PACKAGE_REGISTRY variable to add build directories to the
7721 CMake user package registry.
7722 export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
7725 New in version 3.7.
7727 This signature exports cmake built targets to the android ndk build
7730 system by creating an Android.mk file that references the prebuilt tar‐
7731 gets. The Android NDK supports the use of prebuilt libraries, both
7732 static and shared. This allows cmake to build the libraries of a
7733 project and make them available to an ndk build system complete with
7734 transitive dependencies, include flags and defines required to use the
7735 libraries. The signature takes a list of targets and puts them in the
7736 Android.mk file specified by the <filename> given. This signature can
7737 only be used if policy CMP0022 is NEW for all targets given. A error
7738 will be issued if that policy is set to OLD for one of the targets.
7739 fltk_wrap_ui
7741 Create FLTK user interfaces Wrappers.
7742 fltk_wrap_ui(resultingLibraryName source1
7744 source2 ... sourceN )
7745 Produce .h and .cxx files for all the .fl and .fld files listed. The
7747 resulting .h and .cxx files will be added to a variable named result‐
7748 ingLibraryName_FLTK_UI_SRCS which should be added to your library.
7749 get_source_file_property
7751 Get a property for a source file.
7752 get_source_file_property(<variable> <file>
7754 [DIRECTORY <dir> | TARGET_DIRECTORY <target>]
7755 <property>)
7756 Gets a property from a source file. The value of the property is
7758 stored in the specified <variable>. If the source property is not
7759 found, the behavior depends on whether it has been defined to be an IN‐
7760 HERITED property or not (see define_property()). Non-inherited proper‐
7761 ties will set variable to NOTFOUND, whereas inherited properties will
7762 search the relevant parent scope as described for the define_property()
7763 command and if still unable to find the property, variable will be set
7764 to an empty string.
7765 By default, the source file's property will be read from the current
7767 source directory's scope.
7768 New in version 3.18: Directory scope can be overridden with one of the
7770 following sub-options:
7771 DIRECTORY <dir>
7773 The source file property will be read from the <dir> directory's
7774 scope. CMake must already know about that source directory, ei‐
7775 ther by having added it through a call to add_subdirectory() or
7776 <dir> being the top level source directory. Relative paths are
7777 treated as relative to the current source directory.
7778 TARGET_DIRECTORY <target>
7780 The source file property will be read from the directory scope
7781 in which <target> was created (<target> must therefore already
7782 exist).
7783 Use set_source_files_properties() to set property values. Source file
7786 properties usually control how the file is built. One property that is
7787 always there is LOCATION.
7788 See also the more general get_property() command.
7790 NOTE:
7792 The GENERATED source file property may be globally visible. See its
7793 documentation for details.
7794 get_target_property
7796 Get a property from a target.
7797 get_target_property(<VAR> target property)
7799 Get a property from a target. The value of the property is stored in
7801 the variable <VAR>. If the target property is not found, the behavior
7802 depends on whether it has been defined to be an INHERITED property or
7803 not (see define_property()). Non-inherited properties will set <VAR>
7804 to <VAR>-NOTFOUND, whereas inherited properties will search the rele‐
7805 vant parent scope as described for the define_property() command and if
7806 still unable to find the property, <VAR> will be set to an empty
7807 string.
7808 Use set_target_properties() to set target property values. Properties
7810 are usually used to control how a target is built, but some query the
7811 target instead. This command can get properties for any target so far
7812 created. The targets do not need to be in the current CMakeLists.txt
7813 file.
7814 See also the more general get_property() command.
7816 See Target Properties for the list of properties known to CMake.
7818 get_test_property
7820 Get a property of the test.
7821 get_test_property(test property VAR)
7823 Get a property from the test. The value of the property is stored in
7825 the variable VAR. If the test property is not found, the behavior de‐
7826 pends on whether it has been defined to be an INHERITED property or not
7827 (see define_property()). Non-inherited properties will set VAR to
7828 "NOTFOUND", whereas inherited properties will search the relevant par‐
7829 ent scope as described for the define_property() command and if still
7830 unable to find the property, VAR will be set to an empty string.
7831 For a list of standard properties you can type cmake --help-prop‐
7833 erty-list.
7834 See also the more general get_property() command.
7836 include_directories
7838 Add include directories to the build.
7839 include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])
7841 Add the given directories to those the compiler uses to search for in‐
7843 clude files. Relative paths are interpreted as relative to the current
7844 source directory.
7845 The include directories are added to the INCLUDE_DIRECTORIES directory
7847 property for the current CMakeLists file. They are also added to the
7848 INCLUDE_DIRECTORIES target property for each target in the current
7849 CMakeLists file. The target property values are the ones used by the
7850 generators.
7851 By default the directories specified are appended onto the current list
7853 of directories. This default behavior can be changed by setting
7854 CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE ex‐
7855 plicitly, you can select between appending and prepending, independent
7856 of the default.
7857 If the SYSTEM option is given, the compiler will be told the directo‐
7859 ries are meant as system include directories on some platforms. Sig‐
7860 nalling this setting might achieve effects such as the compiler skip‐
7861 ping warnings, or these fixed-install system files not being considered
7862 in dependency calculations - see compiler docs.
7863 Arguments to include_directories may use "generator expressions" with
7865 the syntax "$<...>". See the cmake-generator-expressions(7) manual for
7866 available expressions. See the cmake-buildsystem(7) manual for more on
7867 defining buildsystem properties.
7868 NOTE:
7870 Prefer the target_include_directories() command to add include di‐
7871 rectories to individual targets and optionally propagate/export them
7872 to dependents.
7873 include_external_msproject
7875 Include an external Microsoft project file in a workspace.
7876 include_external_msproject(projectname location
7878 [TYPE projectTypeGUID]
7879 [GUID projectGUID]
7880 [PLATFORM platformName]
7881 dep1 dep2 ...)
7882 Includes an external Microsoft project in the generated workspace file.
7884 Currently does nothing on UNIX. This will create a target named [pro‐
7885 jectname]. This can be used in the add_dependencies() command to make
7886 things depend on the external project.
7887 TYPE, GUID and PLATFORM are optional parameters that allow one to spec‐
7889 ify the type of project, id (GUID) of the project and the name of the
7890 target platform. This is useful for projects requiring values other
7891 than the default (e.g. WIX projects).
7892 New in version 3.9: If the imported project has different configuration
7894 names than the current project, set the MAP_IMPORTED_CONFIG_<CONFIG>
7895 target property to specify the mapping.
7896 include_regular_expression
7899 Set the regular expression used for dependency checking.
7900 include_regular_expression(regex_match [regex_complain])
7902 Sets the regular expressions used in dependency checking. Only files
7904 matching regex_match will be traced as dependencies. Only files match‐
7905 ing regex_complain will generate warnings if they cannot be found
7906 (standard header paths are not searched). The defaults are:
7907 regex_match = "^.*$" (match everything)
7909 regex_complain = "^$" (match empty string only)
7910 install
7912 Specify rules to run at install time.
7913 Synopsis
7915 install(TARGETS <target>... [...])
7916 install({FILES | PROGRAMS} <file>... [...])
7917 install(DIRECTORY <dir>... [...])
7918 install(SCRIPT <file> [...])
7919 install(CODE <code> [...])
7920 install(EXPORT <export-name> [...])
7921 Introduction
7923 This command generates installation rules for a project. Install rules
7924 specified by calls to the install() command within a source directory
7925 are executed in order during installation.
7926 Changed in version 3.14: Install rules in subdirectories added by calls
7928 to the add_subdirectory() command are interleaved with those in the
7929 parent directory to run in the order declared (see policy CMP0082).
7930 There are multiple signatures for this command. Some of them define
7933 installation options for files and targets. Options common to multiple
7934 signatures are covered here but they are valid only for signatures that
7935 specify them. The common options are:
7936 DESTINATION
7938 Specify the directory on disk to which a file will be installed.
7939 Arguments can be relative or absolute paths.
7940 If a relative path is given it is interpreted relative to the
7942 value of the CMAKE_INSTALL_PREFIX variable. The prefix can be
7943 relocated at install time using the DESTDIR mechanism explained
7944 in the CMAKE_INSTALL_PREFIX variable documentation.
7945 If an absolute path (with a leading slash or drive letter) is
7947 given it is used verbatim.
7948 As absolute paths are not supported by cpack installer genera‐
7950 tors, it is preferable to use relative paths throughout. In
7951 particular, there is no need to make paths absolute by prepend‐
7952 ing CMAKE_INSTALL_PREFIX; this prefix is used by default if the
7953 DESTINATION is a relative path.
7954 PERMISSIONS
7956 Specify permissions for installed files. Valid permissions are
7957 OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE,
7958 GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID,
7959 and SETGID. Permissions that do not make sense on certain plat‐
7960 forms are ignored on those platforms.
7961 CONFIGURATIONS
7963 Specify a list of build configurations for which the install
7964 rule applies (Debug, Release, etc.). Note that the values speci‐
7965 fied for this option only apply to options listed AFTER the CON‐
7966 FIGURATIONS option. For example, to set separate install paths
7967 for the Debug and Release configurations, do the following:
7968 install(TARGETS target
7970 CONFIGURATIONS Debug
7971 RUNTIME DESTINATION Debug/bin)
7972 install(TARGETS target
7973 CONFIGURATIONS Release
7974 RUNTIME DESTINATION Release/bin)
7975 Note that CONFIGURATIONS appears BEFORE RUNTIME DESTINATION.
7977 COMPONENT
7979 Specify an installation component name with which the install
7980 rule is associated, such as "runtime" or "development". During
7981 component-specific installation only install rules associated
7982 with the given component name will be executed. During a full
7983 installation all components are installed unless marked with EX‐
7984 CLUDE_FROM_ALL. If COMPONENT is not provided a default compo‐
7985 nent "Unspecified" is created. The default component name may
7986 be controlled with the CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
7987 variable.
7988 EXCLUDE_FROM_ALL
7990 New in version 3.6.
7991 Specify that the file is excluded from a full installation and
7994 only installed as part of a component-specific installation
7995 RENAME Specify a name for an installed file that may be different from
7997 the original file. Renaming is allowed only when a single file
7998 is installed by the command.
7999 OPTIONAL
8001 Specify that it is not an error if the file to be installed does
8002 not exist.
8003 New in version 3.1: Command signatures that install files may print
8005 messages during installation. Use the CMAKE_INSTALL_MESSAGE variable
8006 to control which messages are printed.
8007 New in version 3.11: Many of the install() variants implicitly create
8010 the directories containing the installed files. If CMAKE_INSTALL_DE‐
8011 FAULT_DIRECTORY_PERMISSIONS is set, these directories will be created
8012 with the permissions specified. Otherwise, they will be created accord‐
8013 ing to the uname rules on Unix-like platforms. Windows platforms are
8014 unaffected.
8015 Installing Targets
8018 install(TARGETS targets... [EXPORT <export-name>]
8019 [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
8020 PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
8021 [DESTINATION <dir>]
8022 [PERMISSIONS permissions...]
8023 [CONFIGURATIONS [Debug|Release|...]]
8024 [COMPONENT <component>]
8025 [NAMELINK_COMPONENT <component>]
8026 [OPTIONAL] [EXCLUDE_FROM_ALL]
8027 [NAMELINK_ONLY|NAMELINK_SKIP]
8028 ] [...]
8029 [INCLUDES DESTINATION [<dir> ...]]
8030 )
8031 The TARGETS form specifies rules for installing targets from a project.
8033 There are several kinds of target Output Artifacts that may be in‐
8034 stalled:
8035 ARCHIVE
8037 Target artifacts of this kind include:
8038 • Static libraries (except on macOS when marked as FRAMEWORK,
8040 see below);
8041 • DLL import libraries (on all Windows-based systems including
8043 Cygwin; they have extension .lib, in contrast to the .dll li‐
8044 braries that go to RUNTIME);
8045 • On AIX, the linker import file created for executables with
8047 ENABLE_EXPORTS enabled.
8048 LIBRARY
8050 Target artifacts of this kind include:
8051 • Shared libraries, except
8053 • DLLs (these go to RUNTIME, see below),
8055 • on macOS when marked as FRAMEWORK (see below).
8057 RUNTIME
8059 Target artifacts of this kind include:
8060 • Executables (except on macOS when marked as MACOSX_BUNDLE, see
8062 BUNDLE below);
8063 • DLLs (on all Windows-based systems including Cygwin; note that
8065 the accompanying import libraries are of kind ARCHIVE).
8066 OBJECTS
8068 New in version 3.9.
8069 Object files associated with object libraries.
8072 FRAMEWORK
8074 Both static and shared libraries marked with the FRAMEWORK prop‐
8075 erty are treated as FRAMEWORK targets on macOS.
8076 BUNDLE Executables marked with the MACOSX_BUNDLE property are treated
8078 as BUNDLE targets on macOS.
8079 PUBLIC_HEADER
8081 Any PUBLIC_HEADER files associated with a library are installed
8082 in the destination specified by the PUBLIC_HEADER argument on
8083 non-Apple platforms. Rules defined by this argument are ignored
8084 for FRAMEWORK libraries on Apple platforms because the associ‐
8085 ated files are installed into the appropriate locations inside
8086 the framework folder. See PUBLIC_HEADER for details.
8087 PRIVATE_HEADER
8089 Similar to PUBLIC_HEADER, but for PRIVATE_HEADER files. See PRI‐
8090 VATE_HEADER for details.
8091 RESOURCE
8093 Similar to PUBLIC_HEADER and PRIVATE_HEADER, but for RESOURCE
8094 files. See RESOURCE for details.
8095 For each of these arguments given, the arguments following them only
8097 apply to the target or file type specified in the argument. If none is
8098 given, the installation properties apply to all target types. If only
8099 one is given then only targets of that type will be installed (which
8100 can be used to install just a DLL or just an import library.)
8101 For regular executables, static libraries and shared libraries, the
8103 DESTINATION argument is not required. For these target types, when
8104 DESTINATION is omitted, a default destination will be taken from the
8105 appropriate variable from GNUInstallDirs, or set to a built-in default
8106 value if that variable is not defined. The same is true for the public
8107 and private headers associated with the installed targets through the
8108 PUBLIC_HEADER and PRIVATE_HEADER target properties. A destination must
8109 always be provided for module libraries, Apple bundles and frameworks.
8110 A destination can be omitted for interface and object libraries, but
8111 they are handled differently (see the discussion of this topic toward
8112 the end of this section).
8113 The following table shows the target types with their associated vari‐
8115 ables and built-in defaults that apply when no destination is given:
8116 ┌───────────────┬─────────────────────┬──────────────────┐
8122 │Target Type │ GNUInstallDirs │ Built-In Default │
8123 │ │ Variable │ │
8124 ├───────────────┼─────────────────────┼──────────────────┤
8125 │RUNTIME │ ${CMAKE_IN‐ │ bin │
8126 │ │ STALL_BINDIR} │ │
8127 ├───────────────┼─────────────────────┼──────────────────┤
8128 │LIBRARY │ ${CMAKE_IN‐ │ lib │
8129 │ │ STALL_LIBDIR} │ │
8130 ├───────────────┼─────────────────────┼──────────────────┤
8131 │ARCHIVE │ ${CMAKE_IN‐ │ lib │
8132 │ │ STALL_LIBDIR} │ │
8133 ├───────────────┼─────────────────────┼──────────────────┤
8134 │PRIVATE_HEADER │ ${CMAKE_INSTALL_IN‐ │ include │
8135 │ │ CLUDEDIR} │ │
8136 ├───────────────┼─────────────────────┼──────────────────┤
8137 │PUBLIC_HEADER │ ${CMAKE_INSTALL_IN‐ │ include │
8138 │ │ CLUDEDIR} │ │
8139 └───────────────┴─────────────────────┴──────────────────┘
8140 Projects wishing to follow the common practice of installing headers
8142 into a project-specific subdirectory will need to provide a destination
8143 rather than rely on the above.
8144 To make packages compliant with distribution filesystem layout poli‐
8146 cies, if projects must specify a DESTINATION, it is recommended that
8147 they use a path that begins with the appropriate GNUInstallDirs vari‐
8148 able. This allows package maintainers to control the install destina‐
8149 tion by setting the appropriate cache variables. The following example
8150 shows a static library being installed to the default destination pro‐
8151 vided by GNUInstallDirs, but with its headers installed to a
8152 project-specific subdirectory that follows the above recommendation:
8153 add_library(mylib STATIC ...)
8155 set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
8156 include(GNUInstallDirs)
8157 install(TARGETS mylib
8158 PUBLIC_HEADER
8159 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
8160 )
8161 In addition to the common options listed above, each target can accept
8163 the following additional arguments:
8164 NAMELINK_COMPONENT
8166 New in version 3.12.
8167 On some platforms a versioned shared library has a symbolic link
8170 such as:
8171 lib<name>.so -> lib<name>.so.1
8173 where lib<name>.so.1 is the soname of the library and
8175 lib<name>.so is a "namelink" allowing linkers to find the li‐
8176 brary when given -l<name>. The NAMELINK_COMPONENT option is sim‐
8177 ilar to the COMPONENT option, but it changes the installation
8178 component of a shared library namelink if one is generated. If
8179 not specified, this defaults to the value of COMPONENT. It is an
8180 error to use this parameter outside of a LIBRARY block.
8181 Consider the following example:
8183 install(TARGETS mylib
8185 LIBRARY
8186 COMPONENT Libraries
8187 NAMELINK_COMPONENT Development
8188 PUBLIC_HEADER
8189 COMPONENT Development
8190 )
8191 In this scenario, if you choose to install only the Development
8193 component, both the headers and namelink will be installed with‐
8194 out the library. (If you don't also install the Libraries compo‐
8195 nent, the namelink will be a dangling symlink, and projects that
8196 link to the library will have build errors.) If you install only
8197 the Libraries component, only the library will be installed,
8198 without the headers and namelink.
8199 This option is typically used for package managers that have
8201 separate runtime and development packages. For example, on De‐
8202 bian systems, the library is expected to be in the runtime pack‐
8203 age, and the headers and namelink are expected to be in the de‐
8204 velopment package.
8205 See the VERSION and SOVERSION target properties for details on
8207 creating versioned shared libraries.
8208 NAMELINK_ONLY
8210 This option causes the installation of only the namelink when a
8211 library target is installed. On platforms where versioned shared
8212 libraries do not have namelinks or when a library is not ver‐
8213 sioned, the NAMELINK_ONLY option installs nothing. It is an er‐
8214 ror to use this parameter outside of a LIBRARY block.
8215 When NAMELINK_ONLY is given, either NAMELINK_COMPONENT or COMPO‐
8217 NENT may be used to specify the installation component of the
8218 namelink, but COMPONENT should generally be preferred.
8219 NAMELINK_SKIP
8221 Similar to NAMELINK_ONLY, but it has the opposite effect: it
8222 causes the installation of library files other than the namelink
8223 when a library target is installed. When neither NAMELINK_ONLY
8224 or NAMELINK_SKIP are given, both portions are installed. On
8225 platforms where versioned shared libraries do not have symlinks
8226 or when a library is not versioned, NAMELINK_SKIP installs the
8227 library. It is an error to use this parameter outside of a LI‐
8228 BRARY block.
8229 If NAMELINK_SKIP is specified, NAMELINK_COMPONENT has no effect.
8231 It is not recommended to use NAMELINK_SKIP in conjunction with
8232 NAMELINK_COMPONENT.
8233 The install(TARGETS) command can also accept the following options at
8235 the top level:
8236 EXPORT This option associates the installed target files with an export
8238 called <export-name>. It must appear before any target options.
8239 To actually install the export file itself, call
8240 install(EXPORT), documented below. See documentation of the EX‐
8241 PORT_NAME target property to change the name of the exported
8242 target.
8243 INCLUDES DESTINATION
8245 This option specifies a list of directories which will be added
8246 to the INTERFACE_INCLUDE_DIRECTORIES target property of the
8247 <targets> when exported by the install(EXPORT) command. If a
8248 relative path is specified, it is treated as relative to the
8249 $<INSTALL_PREFIX>.
8250 One or more groups of properties may be specified in a single call to
8252 the TARGETS form of this command. A target may be installed more than
8253 once to different locations. Consider hypothetical targets myExe,
8254 mySharedLib, and myStaticLib. The code:
8255 install(TARGETS myExe mySharedLib myStaticLib
8257 RUNTIME DESTINATION bin
8258 LIBRARY DESTINATION lib
8259 ARCHIVE DESTINATION lib/static)
8260 install(TARGETS mySharedLib DESTINATION /some/full/path)
8261 will install myExe to <prefix>/bin and myStaticLib to <pre‐
8263 fix>/lib/static. On non-DLL platforms mySharedLib will be installed to
8264 <prefix>/lib and /some/full/path. On DLL platforms the mySharedLib DLL
8265 will be installed to <prefix>/bin and /some/full/path and its import
8266 library will be installed to <prefix>/lib/static and /some/full/path.
8267 Interface Libraries may be listed among the targets to install. They
8269 install no artifacts but will be included in an associated EXPORT. If
8270 Object Libraries are listed but given no destination for their object
8271 files, they will be exported as Interface Libraries. This is suffi‐
8272 cient to satisfy transitive usage requirements of other targets that
8273 link to the object libraries in their implementation.
8274 Installing a target with the EXCLUDE_FROM_ALL target property set to
8276 TRUE has undefined behavior.
8277 New in version 3.3: An install destination given as a DESTINATION argu‐
8279 ment may use "generator expressions" with the syntax $<...>. See the
8280 cmake-generator-expressions(7) manual for available expressions.
8281 New in version 3.13: install(TARGETS) can install targets that were
8284 created in other directories. When using such cross-directory install
8285 rules, running make install (or similar) from a subdirectory will not
8286 guarantee that targets from other directories are up-to-date. You can
8287 use target_link_libraries() or add_dependencies() to ensure that such
8288 out-of-directory targets are built before the subdirectory-specific in‐
8289 stall rules are run.
8290 Installing Files
8293 install(<FILES|PROGRAMS> files...
8294 TYPE <type> | DESTINATION <dir>
8295 [PERMISSIONS permissions...]
8296 [CONFIGURATIONS [Debug|Release|...]]
8297 [COMPONENT <component>]
8298 [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
8299 The FILES form specifies rules for installing files for a project.
8301 File names given as relative paths are interpreted with respect to the
8302 current source directory. Files installed by this form are by default
8303 given permissions OWNER_WRITE, OWNER_READ, GROUP_READ, and WORLD_READ
8304 if no PERMISSIONS argument is given.
8305 The PROGRAMS form is identical to the FILES form except that the de‐
8307 fault permissions for the installed file also include OWNER_EXECUTE,
8308 GROUP_EXECUTE, and WORLD_EXECUTE. This form is intended to install
8309 programs that are not targets, such as shell scripts. Use the TARGETS
8310 form to install targets built within the project.
8311 The list of files... given to FILES or PROGRAMS may use "generator ex‐
8313 pressions" with the syntax $<...>. See the cmake-generator-expres‐
8314 sions(7) manual for available expressions. However, if any item begins
8315 in a generator expression it must evaluate to a full path.
8316 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
8318 argument specifies the generic file type of the files being installed.
8319 A destination will then be set automatically by taking the correspond‐
8320 ing variable from GNUInstallDirs, or by using a built-in default if
8321 that variable is not defined. See the table below for the supported
8322 file types and their corresponding variables and built-in defaults.
8323 Projects can provide a DESTINATION argument instead of a file type if
8324 they wish to explicitly define the install destination.
8325 ┌──────────────┬─────────────────────┬─────────────────────┐
8327 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
8328 │ │ Variable │ │
8329 ├──────────────┼─────────────────────┼─────────────────────┤
8330 │BIN │ ${CMAKE_IN‐ │ bin │
8331 │ │ STALL_BINDIR} │ │
8332 ├──────────────┼─────────────────────┼─────────────────────┤
8333 │SBIN │ ${CMAKE_IN‐ │ sbin │
8334 │ │ STALL_SBINDIR} │ │
8335 ├──────────────┼─────────────────────┼─────────────────────┤
8336 │LIB │ ${CMAKE_IN‐ │ lib │
8337 │ │ STALL_LIBDIR} │ │
8338 ├──────────────┼─────────────────────┼─────────────────────┤
8339 │INCLUDE │ ${CMAKE_INSTALL_IN‐ │ include │
8340 │ │ CLUDEDIR} │ │
8341 ├──────────────┼─────────────────────┼─────────────────────┤
8342 │SYSCONF │ ${CMAKE_IN‐ │ etc │
8343 │ │ STALL_SYSCONFDIR} │ │
8344 ├──────────────┼─────────────────────┼─────────────────────┤
8345 │SHAREDSTATE │ ${CMAKE_IN‐ │ com │
8346 │ │ STALL_SHARESTATE‐ │ │
8347 │ │ DIR} │ │
8348 ├──────────────┼─────────────────────┼─────────────────────┤
8349 │LOCALSTATE │ ${CMAKE_INSTALL_LO‐ │ var │
8350 │ │ CALSTATEDIR} │ │
8351 ├──────────────┼─────────────────────┼─────────────────────┤
8352 │RUNSTATE │ ${CMAKE_IN‐ │ <LOCALSTATE │
8353 │ │ STALL_RUNSTATEDIR} │ dir>/run │
8354 ├──────────────┼─────────────────────┼─────────────────────┤
8355 │DATA │ ${CMAKE_IN‐ │ <DATAROOT dir> │
8356 │ │ STALL_DATADIR} │ │
8357 ├──────────────┼─────────────────────┼─────────────────────┤
8358 │INFO │ ${CMAKE_INSTALL_IN‐ │ <DATAROOT dir>/info │
8359 │ │ FODIR} │ │
8360 ├──────────────┼─────────────────────┼─────────────────────┤
8361 │LOCALE │ ${CMAKE_INSTALL_LO‐ │ <DATAROOT dir>/lo‐ │
8362 │ │ CALEDIR} │ cale │
8363 ├──────────────┼─────────────────────┼─────────────────────┤
8364 │MAN │ ${CMAKE_IN‐ │ <DATAROOT dir>/man │
8365 │ │ STALL_MANDIR} │ │
8366 ├──────────────┼─────────────────────┼─────────────────────┤
8367 │DOC │ ${CMAKE_IN‐ │ <DATAROOT dir>/doc │
8368 │ │ STALL_DOCDIR} │ │
8369 └──────────────┴─────────────────────┴─────────────────────┘
8370 Projects wishing to follow the common practice of installing headers
8372 into a project-specific subdirectory will need to provide a destination
8373 rather than rely on the above.
8374 Note that some of the types' built-in defaults use the DATAROOT direc‐
8376 tory as a prefix. The DATAROOT prefix is calculated similarly to the
8377 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
8378 built-in default. You cannot use DATAROOT as a TYPE parameter; please
8379 use DATA instead.
8380 To make packages compliant with distribution filesystem layout poli‐
8382 cies, if projects must specify a DESTINATION, it is recommended that
8383 they use a path that begins with the appropriate GNUInstallDirs vari‐
8384 able. This allows package maintainers to control the install destina‐
8385 tion by setting the appropriate cache variables. The following example
8386 shows how to follow this advice while installing headers to a
8387 project-specific subdirectory:
8388 include(GNUInstallDirs)
8390 install(FILES mylib.h
8391 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
8392 )
8393 New in version 3.4: An install destination given as a DESTINATION argu‐
8395 ment may use "generator expressions" with the syntax $<...>. See the
8396 cmake-generator-expressions(7) manual for available expressions.
8397 New in version 3.20: An install rename given as a RENAME argument may
8400 use "generator expressions" with the syntax $<...>. See the cmake-gen‐
8401 erator-expressions(7) manual for available expressions.
8402 Installing Directories
8405 install(DIRECTORY dirs...
8406 TYPE <type> | DESTINATION <dir>
8407 [FILE_PERMISSIONS permissions...]
8408 [DIRECTORY_PERMISSIONS permissions...]
8409 [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
8410 [CONFIGURATIONS [Debug|Release|...]]
8411 [COMPONENT <component>] [EXCLUDE_FROM_ALL]
8412 [FILES_MATCHING]
8413 [[PATTERN <pattern> | REGEX <regex>]
8414 [EXCLUDE] [PERMISSIONS permissions...]] [...])
8415 The DIRECTORY form installs contents of one or more directories to a
8417 given destination. The directory structure is copied verbatim to the
8418 destination. The last component of each directory name is appended to
8419 the destination directory but a trailing slash may be used to avoid
8420 this because it leaves the last component empty. Directory names given
8421 as relative paths are interpreted with respect to the current source
8422 directory. If no input directory names are given the destination di‐
8423 rectory will be created but nothing will be installed into it. The
8424 FILE_PERMISSIONS and DIRECTORY_PERMISSIONS options specify permissions
8425 given to files and directories in the destination. If USE_SOURCE_PER‐
8426 MISSIONS is specified and FILE_PERMISSIONS is not, file permissions
8427 will be copied from the source directory structure. If no permissions
8428 are specified files will be given the default permissions specified in
8429 the FILES form of the command, and the directories will be given the
8430 default permissions specified in the PROGRAMS form of the command.
8431 New in version 3.1: The MESSAGE_NEVER option disables file installation
8433 status output.
8434 Installation of directories may be controlled with fine granularity us‐
8437 ing the PATTERN or REGEX options. These "match" options specify a
8438 globbing pattern or regular expression to match directories or files
8439 encountered within input directories. They may be used to apply cer‐
8440 tain options (see below) to a subset of the files and directories en‐
8441 countered. The full path to each input file or directory (with forward
8442 slashes) is matched against the expression. A PATTERN will match only
8443 complete file names: the portion of the full path matching the pattern
8444 must occur at the end of the file name and be preceded by a slash. A
8445 REGEX will match any portion of the full path but it may use / and $ to
8446 simulate the PATTERN behavior. By default all files and directories
8447 are installed whether or not they are matched. The FILES_MATCHING op‐
8448 tion may be given before the first match option to disable installation
8449 of files (but not directories) not matched by any expression. For ex‐
8450 ample, the code
8451 install(DIRECTORY src/ DESTINATION include/myproj
8453 FILES_MATCHING PATTERN "*.h")
8454 will extract and install header files from a source tree.
8456 Some options may follow a PATTERN or REGEX expression and are applied
8458 only to files or directories matching them. The EXCLUDE option will
8459 skip the matched file or directory. The PERMISSIONS option overrides
8460 the permissions setting for the matched file or directory. For example
8461 the code
8462 install(DIRECTORY icons scripts/ DESTINATION share/myproj
8464 PATTERN "CVS" EXCLUDE
8465 PATTERN "scripts/*"
8466 PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
8467 GROUP_EXECUTE GROUP_READ)
8468 will install the icons directory to share/myproj/icons and the scripts
8470 directory to share/myproj. The icons will get default file permis‐
8471 sions, the scripts will be given specific permissions, and any CVS di‐
8472 rectories will be excluded.
8473 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
8475 argument specifies the generic file type of the files within the listed
8476 directories being installed. A destination will then be set automati‐
8477 cally by taking the corresponding variable from GNUInstallDirs, or by
8478 using a built-in default if that variable is not defined. See the ta‐
8479 ble below for the supported file types and their corresponding vari‐
8480 ables and built-in defaults. Projects can provide a DESTINATION argu‐
8481 ment instead of a file type if they wish to explicitly define the in‐
8482 stall destination.
8483 ┌──────────────┬─────────────────────┬─────────────────────┐
8485 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
8486 │ │ Variable │ │
8487 └──────────────┴─────────────────────┴─────────────────────┘
8488 │BIN │ ${CMAKE_IN‐ │ bin │
8490 │ │ STALL_BINDIR} │ │
8491 ├──────────────┼─────────────────────┼─────────────────────┤
8492 │SBIN │ ${CMAKE_IN‐ │ sbin │
8493 │ │ STALL_SBINDIR} │ │
8494 ├──────────────┼─────────────────────┼─────────────────────┤
8495 │LIB │ ${CMAKE_IN‐ │ lib │
8496 │ │ STALL_LIBDIR} │ │
8497 ├──────────────┼─────────────────────┼─────────────────────┤
8498 │INCLUDE │ ${CMAKE_INSTALL_IN‐ │ include │
8499 │ │ CLUDEDIR} │ │
8500 ├──────────────┼─────────────────────┼─────────────────────┤
8501 │SYSCONF │ ${CMAKE_IN‐ │ etc │
8502 │ │ STALL_SYSCONFDIR} │ │
8503 ├──────────────┼─────────────────────┼─────────────────────┤
8504 │SHAREDSTATE │ ${CMAKE_IN‐ │ com │
8505 │ │ STALL_SHARESTATE‐ │ │
8506 │ │ DIR} │ │
8507 ├──────────────┼─────────────────────┼─────────────────────┤
8508 │LOCALSTATE │ ${CMAKE_INSTALL_LO‐ │ var │
8509 │ │ CALSTATEDIR} │ │
8510 ├──────────────┼─────────────────────┼─────────────────────┤
8511 │RUNSTATE │ ${CMAKE_IN‐ │ <LOCALSTATE │
8512 │ │ STALL_RUNSTATEDIR} │ dir>/run │
8513 ├──────────────┼─────────────────────┼─────────────────────┤
8514 │DATA │ ${CMAKE_IN‐ │ <DATAROOT dir> │
8515 │ │ STALL_DATADIR} │ │
8516 ├──────────────┼─────────────────────┼─────────────────────┤
8517 │INFO │ ${CMAKE_INSTALL_IN‐ │ <DATAROOT dir>/info │
8518 │ │ FODIR} │ │
8519 ├──────────────┼─────────────────────┼─────────────────────┤
8520 │LOCALE │ ${CMAKE_INSTALL_LO‐ │ <DATAROOT dir>/lo‐ │
8521 │ │ CALEDIR} │ cale │
8522 ├──────────────┼─────────────────────┼─────────────────────┤
8523 │MAN │ ${CMAKE_IN‐ │ <DATAROOT dir>/man │
8524 │ │ STALL_MANDIR} │ │
8525 ├──────────────┼─────────────────────┼─────────────────────┤
8526 │DOC │ ${CMAKE_IN‐ │ <DATAROOT dir>/doc │
8527 │ │ STALL_DOCDIR} │ │
8528 └──────────────┴─────────────────────┴─────────────────────┘
8529 Note that some of the types' built-in defaults use the DATAROOT direc‐
8531 tory as a prefix. The DATAROOT prefix is calculated similarly to the
8532 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
8533 built-in default. You cannot use DATAROOT as a TYPE parameter; please
8534 use DATA instead.
8535 To make packages compliant with distribution filesystem layout poli‐
8537 cies, if projects must specify a DESTINATION, it is recommended that
8538 they use a path that begins with the appropriate GNUInstallDirs vari‐
8539 able. This allows package maintainers to control the install destina‐
8540 tion by setting the appropriate cache variables.
8541 New in version 3.4: An install destination given as a DESTINATION argu‐
8543 ment may use "generator expressions" with the syntax $<...>. See the
8544 cmake-generator-expressions(7) manual for available expressions.
8545 New in version 3.5: The list of dirs... given to DIRECTORY may use
8548 "generator expressions" too.
8549 Custom Installation Logic
8552 install([[SCRIPT <file>] [CODE <code>]]
8553 [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])
8554 The SCRIPT form will invoke the given CMake script files during instal‐
8556 lation. If the script file name is a relative path it will be inter‐
8557 preted with respect to the current source directory. The CODE form
8558 will invoke the given CMake code during installation. Code is speci‐
8559 fied as a single argument inside a double-quoted string. For example,
8560 the code
8561 install(CODE "MESSAGE(\"Sample install message.\")")
8563 will print a message during installation.
8565 New in version 3.14: <file> or <code> may use "generator expressions"
8567 with the syntax $<...> (in the case of <file>, this refers to their use
8568 in the file name, not the file's contents). See the cmake-genera‐
8569 tor-expressions(7) manual for available expressions.
8570 Installing Exports
8573 install(EXPORT <export-name> DESTINATION <dir>
8574 [NAMESPACE <namespace>] [[FILE <name>.cmake]|
8575 [PERMISSIONS permissions...]
8576 [CONFIGURATIONS [Debug|Release|...]]
8577 [EXPORT_LINK_INTERFACE_LIBRARIES]
8578 [COMPONENT <component>]
8579 [EXCLUDE_FROM_ALL])
8580 install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])
8581 The EXPORT form generates and installs a CMake file containing code to
8583 import targets from the installation tree into another project. Target
8584 installations are associated with the export <export-name> using the
8585 EXPORT option of the install(TARGETS) signature documented above. The
8586 NAMESPACE option will prepend <namespace> to the target names as they
8587 are written to the import file. By default the generated file will be
8588 called <export-name>.cmake but the FILE option may be used to specify a
8589 different name. The value given to the FILE option must be a file name
8590 with the .cmake extension. If a CONFIGURATIONS option is given then
8591 the file will only be installed when one of the named configurations is
8592 installed. Additionally, the generated import file will reference only
8593 the matching target configurations. The EXPORT_LINK_INTERFACE_LI‐
8594 BRARIES keyword, if present, causes the contents of the properties
8595 matching (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be ex‐
8596 ported, when policy CMP0022 is NEW.
8597 NOTE:
8599 The installed <export-name>.cmake file may come with additional
8600 per-configuration <export-name>-*.cmake files to be loaded by glob‐
8601 bing. Do not use an export name that is the same as the package
8602 name in combination with installing a <package-name>-config.cmake
8603 file or the latter may be incorrectly matched by the glob and
8604 loaded.
8605 When a COMPONENT option is given, the listed <component> implicitly de‐
8607 pends on all components mentioned in the export set. The exported
8608 <name>.cmake file will require each of the exported components to be
8609 present in order for dependent projects to build properly. For example,
8610 a project may define components Runtime and Development, with shared
8611 libraries going into the Runtime component and static libraries and
8612 headers going into the Development component. The export set would also
8613 typically be part of the Development component, but it would export
8614 targets from both the Runtime and Development components. Therefore,
8615 the Runtime component would need to be installed if the Development
8616 component was installed, but not vice versa. If the Development compo‐
8617 nent was installed without the Runtime component, dependent projects
8618 that try to link against it would have build errors. Package managers,
8619 such as APT and RPM, typically handle this by listing the Runtime com‐
8620 ponent as a dependency of the Development component in the package
8621 metadata, ensuring that the library is always installed if the headers
8622 and CMake export file are present.
8623 New in version 3.7: In addition to cmake language files, the EXPORT_AN‐
8625 DROID_MK mode maybe used to specify an export to the android ndk build
8626 system. This mode accepts the same options as the normal export mode.
8627 The Android NDK supports the use of prebuilt libraries, both static and
8628 shared. This allows cmake to build the libraries of a project and make
8629 them available to an ndk build system complete with transitive depen‐
8630 dencies, include flags and defines required to use the libraries.
8631 The EXPORT form is useful to help outside projects use targets built
8634 and installed by the current project. For example, the code
8635 install(TARGETS myexe EXPORT myproj DESTINATION bin)
8637 install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
8638 install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules)
8639 will install the executable myexe to <prefix>/bin and code to import it
8641 in the file <prefix>/lib/myproj/myproj.cmake and <pre‐
8642 fix>/share/ndk-modules/Android.mk. An outside project may load this
8643 file with the include command and reference the myexe executable from
8644 the installation tree using the imported target name mp_myexe as if the
8645 target were built in its own tree.
8646 NOTE:
8648 This command supercedes the install_targets() command and the
8649 PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT target properties. It
8650 also replaces the FILES forms of the install_files() and in‐
8651 stall_programs() commands. The processing order of these install
8652 rules relative to those generated by install_targets(), in‐
8653 stall_files(), and install_programs() commands is not defined.
8654 Generated Installation Script
8656 NOTE:
8657 Use of this feature is not recommended. Please consider using the
8658 --install argument of cmake(1) instead.
8659 The install() command generates a file, cmake_install.cmake, inside the
8661 build directory, which is used internally by the generated install tar‐
8662 get and by CPack. You can also invoke this script manually with cmake
8663 -P. This script accepts several variables:
8664 COMPONENT
8666 Set this variable to install only a single CPack component as
8667 opposed to all of them. For example, if you only want to install
8668 the Development component, run cmake -DCOMPONENT=Development -P
8669 cmake_install.cmake.
8670 BUILD_TYPE
8672 Set this variable to change the build type if you are using a
8673 multi-config generator. For example, to install with the Debug
8674 configuration, run cmake -DBUILD_TYPE=Debug -P cmake_in‐
8675 stall.cmake.
8676 DESTDIR
8678 This is an environment variable rather than a CMake variable. It
8679 allows you to change the installation prefix on UNIX systems.
8680 See DESTDIR for details.
8681 link_directories
8683 Add directories in which the linker will look for libraries.
8684 link_directories([AFTER|BEFORE] directory1 [directory2 ...])
8686 Adds the paths in which the linker should search for libraries. Rela‐
8688 tive paths given to this command are interpreted as relative to the
8689 current source directory, see CMP0015.
8690 The command will apply only to targets created after it is called.
8692 New in version 3.13: The directories are added to the LINK_DIRECTORIES
8694 directory property for the current CMakeLists.txt file, converting rel‐
8695 ative paths to absolute as needed. See the cmake-buildsystem(7) manual
8696 for more on defining buildsystem properties.
8697 New in version 3.13: By default the directories specified are appended
8700 onto the current list of directories. This default behavior can be
8701 changed by setting CMAKE_LINK_DIRECTORIES_BEFORE to ON. By using AFTER
8702 or BEFORE explicitly, you can select between appending and prepending,
8703 independent of the default.
8704 New in version 3.13: Arguments to link_directories may use "generator
8707 expressions" with the syntax "$<...>". See the cmake-generator-expres‐
8708 sions(7) manual for available expressions.
8709 NOTE:
8712 This command is rarely necessary and should be avoided where there
8713 are other choices. Prefer to pass full absolute paths to libraries
8714 where possible, since this ensures the correct library will always
8715 be linked. The find_library() command provides the full path, which
8716 can generally be used directly in calls to target_link_libraries().
8717 Situations where a library search path may be needed include:
8718 • Project generators like Xcode where the user can switch target ar‐
8720 chitecture at build time, but a full path to a library cannot be
8721 used because it only provides one architecture (i.e. it is not a
8722 universal binary).
8723 • Libraries may themselves have other private library dependencies
8725 that expect to be found via RPATH mechanisms, but some linkers are
8726 not able to fully decode those paths (e.g. due to the presence of
8727 things like $ORIGIN).
8728 If a library search path must be provided, prefer to localize the
8730 effect where possible by using the target_link_directories() command
8731 rather than link_directories(). The target-specific command can
8732 also control how the search directories propagate to other dependent
8733 targets.
8734 link_libraries
8736 Link libraries to all targets added later.
8737 link_libraries([item1 [item2 [...]]]
8739 [[debug|optimized|general] <item>] ...)
8740 Specify libraries or flags to use when linking any targets created
8742 later in the current directory or below by commands such as add_exe‐
8743 cutable() or add_library(). See the target_link_libraries() command
8744 for meaning of arguments.
8745 NOTE:
8747 The target_link_libraries() command should be preferred whenever
8748 possible. Library dependencies are chained automatically, so direc‐
8749 tory-wide specification of link libraries is rarely needed.
8750 load_cache
8752 Load in the values from another project's CMake cache.
8753 load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...)
8755 Reads the cache and store the requested entries in variables with their
8757 name prefixed with the given prefix. This only reads the values, and
8758 does not create entries in the local project's cache.
8759 load_cache(pathToBuildDirectory [EXCLUDE entry1...]
8761 [INCLUDE_INTERNALS entry1...])
8762 Loads in the values from another cache and store them in the local
8764 project's cache as internal entries. This is useful for a project that
8765 depends on another project built in a different tree. EXCLUDE option
8766 can be used to provide a list of entries to be excluded. INCLUDE_IN‐
8767 TERNALS can be used to provide a list of internal entries to be in‐
8768 cluded. Normally, no internal entries are brought in. Use of this
8769 form of the command is strongly discouraged, but it is provided for
8770 backward compatibility.
8771 project
8773 Set the name of the project.
8774 Synopsis
8776 project(<PROJECT-NAME> [<language-name>...])
8777 project(<PROJECT-NAME>
8778 [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
8779 [DESCRIPTION <project-description-string>]
8780 [HOMEPAGE_URL <url-string>]
8781 [LANGUAGES <language-name>...])
8782 Sets the name of the project, and stores it in the variable
8784 PROJECT_NAME. When called from the top-level CMakeLists.txt also stores
8785 the project name in the variable CMAKE_PROJECT_NAME.
8786 Also sets the variables
8788 • PROJECT_SOURCE_DIR, <PROJECT-NAME>_SOURCE_DIR
8790 • PROJECT_BINARY_DIR, <PROJECT-NAME>_BINARY_DIR
8792 Further variables are set by the optional arguments described in the
8794 following. If any of these arguments is not used, then the correspond‐
8795 ing variables are set to the empty string.
8796 Options
8798 The options are:
8799 VERSION <version>
8801 Optional; may not be used unless policy CMP0048 is set to NEW.
8802 Takes a <version> argument composed of non-negative integer com‐
8804 ponents, i.e. <major>[.<minor>[.<patch>[.<tweak>]]], and sets
8805 the variables
8806 • PROJECT_VERSION, <PROJECT-NAME>_VERSION
8808 • PROJECT_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MAJOR
8810 • PROJECT_VERSION_MINOR, <PROJECT-NAME>_VERSION_MINOR
8812 • PROJECT_VERSION_PATCH, <PROJECT-NAME>_VERSION_PATCH
8814 • PROJECT_VERSION_TWEAK, <PROJECT-NAME>_VERSION_TWEAK.
8816 New in version 3.12: When the project() command is called from
8818 the top-level CMakeLists.txt, then the version is also stored in
8819 the variable CMAKE_PROJECT_VERSION.
8820 DESCRIPTION <project-description-string>
8823 New in version 3.9.
8824 Optional. Sets the variables
8827 • PROJECT_DESCRIPTION, <PROJECT-NAME>_DESCRIPTION
8829 to <project-description-string>. It is recommended that this
8831 description is a relatively short string, usually no more than a
8832 few words.
8833 When the project() command is called from the top-level CMake‐
8835 Lists.txt, then the description is also stored in the variable
8836 CMAKE_PROJECT_DESCRIPTION.
8837 New in version 3.12: Added the <PROJECT-NAME>_DESCRIPTION vari‐
8839 able.
8840 HOMEPAGE_URL <url-string>
8843 New in version 3.12.
8844 Optional. Sets the variables
8847 • PROJECT_HOMEPAGE_URL, <PROJECT-NAME>_HOMEPAGE_URL
8849 to <url-string>, which should be the canonical home URL for the
8851 project.
8852 When the project() command is called from the top-level CMake‐
8854 Lists.txt, then the URL also is stored in the variable
8855 CMAKE_PROJECT_HOMEPAGE_URL.
8856 LANGUAGES <language-name>...
8858 Optional. Can also be specified without LANGUAGES keyword per
8859 the first, short signature.
8860 Selects which programming languages are needed to build the
8862 project. Supported languages include C, CXX (i.e. C++), CUDA,
8863 OBJC (i.e. Objective-C), OBJCXX, Fortran, ISPC, and ASM. By de‐
8864 fault C and CXX are enabled if no language options are given.
8865 Specify language NONE, or use the LANGUAGES keyword and list no
8866 languages, to skip enabling any languages.
8867 New in version 3.8: Added CUDA support.
8869 New in version 3.16: Added OBJC and OBJCXX support.
8872 New in version 3.18: Added ISPC support.
8875 If enabling ASM, list it last so that CMake can check whether
8878 compilers for other languages like C work for assembly too.
8879 The variables set through the VERSION, DESCRIPTION and HOMEPAGE_URL op‐
8881 tions are intended for use as default values in package metadata and
8882 documentation.
8883 Code Injection
8885 If the CMAKE_PROJECT_INCLUDE_BEFORE or CMAKE_PROJECT_<PROJECT-NAME>_IN‐
8886 CLUDE_BEFORE variables are set, the files they point to will be in‐
8887 cluded as the first step of the project() command. If both are set,
8888 then CMAKE_PROJECT_INCLUDE_BEFORE will be included before
8889 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE.
8890 If the CMAKE_PROJECT_INCLUDE or CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE
8892 variables are set, the files they point to will be included as the last
8893 step of the project() command. If both are set, then CMAKE_PROJECT_IN‐
8894 CLUDE will be included before CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE.
8895 New in version 3.15: Added the CMAKE_PROJECT_INCLUDE and
8897 CMAKE_PROJECT_INCLUDE_BEFORE variables.
8898 New in version 3.17: Added the CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BE‐
8901 FORE variable.
8902 Usage
8905 The top-level CMakeLists.txt file for a project must contain a literal,
8906 direct call to the project() command; loading one through the include()
8907 command is not sufficient. If no such call exists, CMake will issue a
8908 warning and pretend there is a project(Project) at the top to enable
8909 the default languages (C and CXX).
8910 NOTE:
8912 Call the project() command near the top of the top-level CMake‐
8913 Lists.txt, but after calling cmake_minimum_required(). It is impor‐
8914 tant to establish version and policy settings before invoking other
8915 commands whose behavior they may affect. See also policy CMP0000.
8916 remove_definitions
8918 Remove -D define flags added by add_definitions().
8919 remove_definitions(-DFOO -DBAR ...)
8921 Removes flags (added by add_definitions()) from the compiler command
8923 line for sources in the current directory and below.
8924 set_source_files_properties
8926 Source files can have properties that affect how they are built.
8927 set_source_files_properties(<files> ...
8929 [DIRECTORY <dirs> ...]
8930 [TARGET_DIRECTORY <targets> ...]
8931 PROPERTIES <prop1> <value1>
8932 [<prop2> <value2>] ...)
8933 Sets properties associated with source files using a key/value paired
8935 list.
8936 New in version 3.18: By default, source file properties are only visi‐
8938 ble to targets added in the same directory (CMakeLists.txt). Visibil‐
8939 ity can be set in other directory scopes using one or both of the fol‐
8940 lowing options:
8941 DIRECTORY <dirs>...
8944 The source file properties will be set in each of the <dirs> di‐
8945 rectories' scopes. CMake must already know about each of these
8946 source directories, either by having added them through a call
8947 to add_subdirectory() or it being the top level source direc‐
8948 tory. Relative paths are treated as relative to the current
8949 source directory.
8950 TARGET_DIRECTORY <targets>...
8952 The source file properties will be set in each of the directory
8953 scopes where any of the specified <targets> were created (the
8954 <targets> must therefore already exist).
8955 Use get_source_file_property() to get property values. See also the
8957 set_property(SOURCE) command.
8958 See Source File Properties for the list of properties known to CMake.
8960 NOTE:
8962 The GENERATED source file property may be globally visible. See its
8963 documentation for details.
8964 set_target_properties
8966 Targets can have properties that affect how they are built.
8967 set_target_properties(target1 target2 ...
8969 PROPERTIES prop1 value1
8970 prop2 value2 ...)
8971 Sets properties on targets. The syntax for the command is to list all
8973 the targets you want to change, and then provide the values you want to
8974 set next. You can use any prop value pair you want and extract it
8975 later with the get_property() or get_target_property() command.
8976 See also the set_property(TARGET) command.
8978 See Target Properties for the list of properties known to CMake.
8980 set_tests_properties
8982 Set a property of the tests.
8983 set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
8985 Sets a property for the tests. If the test is not found, CMake will
8987 report an error. Generator expressions will be expanded the same as
8988 supported by the test's add_test() call.
8989 See also the set_property(TEST) command.
8991 See Test Properties for the list of properties known to CMake.
8993 source_group
8995 Define a grouping for source files in IDE project generation. There
8996 are two different signatures to create source groups.
8997 source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
8999 source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...])
9000 Defines a group into which sources will be placed in project files.
9002 This is intended to set up file tabs in Visual Studio. The options
9003 are:
9004 TREE New in version 3.8.
9006 CMake will automatically detect, from <src> files paths, source
9009 groups it needs to create, to keep structure of source groups
9010 analogically to the actual files and directories structure in
9011 the project. Paths of <src> files will be cut to be relative to
9012 <root>.
9013 PREFIX New in version 3.8.
9015 Source group and files located directly in <root> path, will be
9018 placed in <prefix> source groups.
9019 FILES Any source file specified explicitly will be placed in group
9021 <name>. Relative paths are interpreted with respect to the cur‐
9022 rent source directory.
9023 REGULAR_EXPRESSION
9025 Any source file whose name matches the regular expression will
9026 be placed in group <name>.
9027 If a source file matches multiple groups, the last group that explic‐
9029 itly lists the file with FILES will be favored, if any. If no group
9030 explicitly lists the file, the last group whose regular expression
9031 matches the file will be favored.
9032 The <name> of the group and <prefix> argument may contain forward
9034 slashes or backslashes to specify subgroups. Backslashes need to be
9035 escaped appropriately:
9036 source_group(base/subdir ...)
9038 source_group(outer\\inner ...)
9039 source_group(TREE <root> PREFIX sources\\inc ...)
9040 New in version 3.18: Allow using forward slashes (/) to specify sub‐
9042 groups.
9043 For backwards compatibility, the short-hand signature
9046 source_group(<name> <regex>)
9048 is equivalent to
9050 source_group(<name> REGULAR_EXPRESSION <regex>)
9052 target_compile_definitions
9054 Add compile definitions to a target.
9055 target_compile_definitions(<target>
9057 <INTERFACE|PUBLIC|PRIVATE> [items1...]
9058 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
9059 Specifies compile definitions to use when compiling a given <target>.
9061 The named <target> must have been created by a command such as add_exe‐
9062 cutable() or add_library() and must not be an ALIAS target.
9063 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9065 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
9066 late the COMPILE_DEFINITIONS property of <target>. PUBLIC and INTERFACE
9067 items will populate the INTERFACE_COMPILE_DEFINITIONS property of <tar‐
9068 get>. The following arguments specify compile definitions. Repeated
9069 calls for the same <target> append items in the order called.
9070 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
9072 Arguments to target_compile_definitions may use "generator expressions"
9075 with the syntax $<...>. See the cmake-generator-expressions(7) manual
9076 for available expressions. See the cmake-buildsystem(7) manual for
9077 more on defining buildsystem properties.
9078 Any leading -D on an item will be removed. Empty items are ignored.
9080 For example, the following are all equivalent:
9081 target_compile_definitions(foo PUBLIC FOO)
9083 target_compile_definitions(foo PUBLIC -DFOO) # -D removed
9084 target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
9085 target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
9086 Definitions may optionally have values:
9088 target_compile_definitions(foo PUBLIC FOO=1)
9090 Note that many compilers treat -DFOO as equivalent to -DFOO=1, but
9092 other tools may not recognize this in all circumstances (e.g. Intel‐
9093 liSense).
9094 target_compile_features
9096 New in version 3.1.
9097 Add expected compiler features to a target.
9100 target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
9102 Specifies compiler features required when compiling a given target. If
9104 the feature is not listed in the CMAKE_C_COMPILE_FEATURES,
9105 CMAKE_CUDA_COMPILE_FEATURES, or CMAKE_CXX_COMPILE_FEATURES variables,
9106 then an error will be reported by CMake. If the use of the feature re‐
9107 quires an additional compiler flag, such as -std=gnu++11, the flag will
9108 be added automatically.
9109 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9111 scope of the features. PRIVATE and PUBLIC items will populate the COM‐
9112 PILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
9113 populate the INTERFACE_COMPILE_FEATURES property of <target>. Repeated
9114 calls for the same <target> append items.
9115 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
9117 The named <target> must have been created by a command such as add_exe‐
9120 cutable() or add_library() and must not be an ALIAS target.
9121 Arguments to target_compile_features may use "generator expressions"
9123 with the syntax $<...>. See the cmake-generator-expressions(7) manual
9124 for available expressions. See the cmake-compile-features(7) manual
9125 for information on compile features and a list of supported compilers.
9126 target_compile_options
9128 Add compile options to a target.
9129 target_compile_options(<target> [BEFORE]
9131 <INTERFACE|PUBLIC|PRIVATE> [items1...]
9132 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
9133 Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
9135 properties. These options are used when compiling the given <target>,
9136 which must have been created by a command such as add_executable() or
9137 add_library() and must not be an ALIAS target.
9138 Arguments
9140 If BEFORE is specified, the content will be prepended to the property
9141 instead of being appended.
9142 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9144 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
9145 late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
9146 items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
9147 The following arguments specify compile options. Repeated calls for
9148 the same <target> append items in the order called.
9149 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
9151 Arguments to target_compile_options may use "generator expressions"
9154 with the syntax $<...>. See the cmake-generator-expressions(7) manual
9155 for available expressions. See the cmake-buildsystem(7) manual for
9156 more on defining buildsystem properties.
9157 The final set of compile or link options used for a target is construc‐
9159 ted by accumulating options from the current target and the usage re‐
9160 quirements of its dependencies. The set of options is de-duplicated to
9161 avoid repetition.
9162 New in version 3.12: While beneficial for individual options, the
9164 de-duplication step can break up option groups. For example, -D A -D B
9165 becomes -D A B. One may specify a group of options using shell-like
9166 quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and
9167 the rest of the option string is parsed using the separate_arguments()
9168 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
9169 -D B.
9170 See Also
9173 This command can be used to add any options. However, for adding pre‐
9174 processor definitions and include directories it is recommended to use
9175 the more specific commands target_compile_definitions() and target_in‐
9176 clude_directories().
9177 For directory-wide settings, there is the command add_compile_op‐
9179 tions().
9180 For file-specific settings, there is the source file property COM‐
9182 PILE_OPTIONS.
9183 target_include_directories
9185 Add include directories to a target.
9186 target_include_directories(<target> [SYSTEM] [AFTER|BEFORE]
9188 <INTERFACE|PUBLIC|PRIVATE> [items1...]
9189 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
9190 Specifies include directories to use when compiling a given target.
9192 The named <target> must have been created by a command such as add_exe‐
9193 cutable() or add_library() and must not be an ALIAS target.
9194 By using AFTER or BEFORE explicitly, you can select between appending
9196 and prepending, independent of the default.
9197 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9199 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
9200 late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTER‐
9201 FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
9202 <target>. The following arguments specify include directories.
9203 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
9205 Specified include directories may be absolute paths or relative paths.
9208 Repeated calls for the same <target> append items in the order called.
9209 If SYSTEM is specified, the compiler will be told the directories are
9210 meant as system include directories on some platforms (signalling this
9211 setting might achieve effects such as the compiler skipping warnings,
9212 or these fixed-install system files not being considered in dependency
9213 calculations - see compiler docs). If SYSTEM is used together with
9214 PUBLIC or INTERFACE, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
9215 property will be populated with the specified directories.
9216 Arguments to target_include_directories may use "generator expressions"
9218 with the syntax $<...>. See the cmake-generator-expressions(7) manual
9219 for available expressions. See the cmake-buildsystem(7) manual for
9220 more on defining buildsystem properties.
9221 Include directories usage requirements commonly differ between the
9223 build-tree and the install-tree. The BUILD_INTERFACE and INSTALL_IN‐
9224 TERFACE generator expressions can be used to describe separate usage
9225 requirements based on the usage location. Relative paths are allowed
9226 within the INSTALL_INTERFACE expression and are interpreted relative to
9227 the installation prefix. For example:
9228 target_include_directories(mylib PUBLIC
9230 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
9231 $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
9232 )
9233 Creating Relocatable Packages
9235 Note that it is not advisable to populate the INSTALL_INTERFACE of the
9236 INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
9237 include directories of dependencies. That would hard-code into in‐
9238 stalled packages the include directory paths for dependencies as found
9239 on the machine the package was made on.
9240 The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
9242 suitable for specifying the required include directories for headers
9243 provided with the target itself, not those provided by the transitive
9244 dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
9245 Those dependencies should themselves be targets that specify their own
9246 header locations in INTERFACE_INCLUDE_DIRECTORIES.
9247 See the Creating Relocatable Packages section of the cmake-packages(7)
9249 manual for discussion of additional care that must be taken when speci‐
9250 fying usage requirements while creating packages for redistribution.
9251 target_link_directories
9253 New in version 3.13.
9254 Add link directories to a target.
9257 target_link_directories(<target> [BEFORE]
9259 <INTERFACE|PUBLIC|PRIVATE> [items1...]
9260 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
9261 Specifies the paths in which the linker should search for libraries
9263 when linking a given target. Each item can be an absolute or relative
9264 path, with the latter being interpreted as relative to the current
9265 source directory. These items will be added to the link command.
9266 The named <target> must have been created by a command such as add_exe‐
9268 cutable() or add_library() and must not be an ALIAS target.
9269 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9271 scope of the items that follow them. PRIVATE and PUBLIC items will
9272 populate the LINK_DIRECTORIES property of <target>. PUBLIC and INTER‐
9273 FACE items will populate the INTERFACE_LINK_DIRECTORIES property of
9274 <target> (IMPORTED targets only support INTERFACE items). Each item
9275 specifies a link directory and will be converted to an absolute path if
9276 necessary before adding it to the relevant property. Repeated calls
9277 for the same <target> append items in the order called.
9278 If BEFORE is specified, the content will be prepended to the relevant
9280 property instead of being appended.
9281 Arguments to target_link_directories may use "generator expressions"
9283 with the syntax $<...>. See the cmake-generator-expressions(7) manual
9284 for available expressions. See the cmake-buildsystem(7) manual for
9285 more on defining buildsystem properties.
9286 NOTE:
9288 This command is rarely necessary and should be avoided where there
9289 are other choices. Prefer to pass full absolute paths to libraries
9290 where possible, since this ensures the correct library will always
9291 be linked. The find_library() command provides the full path, which
9292 can generally be used directly in calls to target_link_libraries().
9293 Situations where a library search path may be needed include:
9294 • Project generators like Xcode where the user can switch target ar‐
9296 chitecture at build time, but a full path to a library cannot be
9297 used because it only provides one architecture (i.e. it is not a
9298 universal binary).
9299 • Libraries may themselves have other private library dependencies
9301 that expect to be found via RPATH mechanisms, but some linkers are
9302 not able to fully decode those paths (e.g. due to the presence of
9303 things like $ORIGIN).
9304 target_link_libraries
9306 Specify libraries or flags to use when linking a given target and/or
9307 its dependents. Usage requirements from linked library targets will be
9308 propagated. Usage requirements of a target's dependencies affect com‐
9309 pilation of its own sources.
9310 Overview
9312 This command has several signatures as detailed in subsections below.
9313 All of them have the general form
9314 target_link_libraries(<target> ... <item>... ...)
9316 The named <target> must have been created by a command such as add_exe‐
9318 cutable() or add_library() and must not be an ALIAS target. If policy
9319 CMP0079 is not set to NEW then the target must have been created in the
9320 current directory. Repeated calls for the same <target> append items
9321 in the order called.
9322 New in version 3.13: The <target> doesn't have to be defined in the
9324 same directory as the target_link_libraries call.
9325 Each <item> may be:
9328 • A library target name: The generated link line will have the full
9330 path to the linkable library file associated with the target. The
9331 buildsystem will have a dependency to re-link <target> if the library
9332 file changes.
9333 The named target must be created by add_library() within the project
9335 or as an IMPORTED library. If it is created within the project an
9336 ordering dependency will automatically be added in the build system
9337 to make sure the named library target is up-to-date before the <tar‐
9338 get> links.
9339 If an imported library has the IMPORTED_NO_SONAME target property
9341 set, CMake may ask the linker to search for the library instead of
9342 using the full path (e.g. /usr/lib/libfoo.so becomes -lfoo).
9343 The full path to the target's artifact will be quoted/escaped for the
9345 shell automatically.
9346 • A full path to a library file: The generated link line will normally
9348 preserve the full path to the file. The buildsystem will have a de‐
9349 pendency to re-link <target> if the library file changes.
9350 There are some cases where CMake may ask the linker to search for the
9352 library (e.g. /usr/lib/libfoo.so becomes -lfoo), such as when a
9353 shared library is detected to have no SONAME field. See policy
9354 CMP0060 for discussion of another case.
9355 If the library file is in a macOS framework, the Headers directory of
9357 the framework will also be processed as a usage requirement. This
9358 has the same effect as passing the framework directory as an include
9359 directory.
9360 New in version 3.8: On Visual Studio Generators for VS 2010 and
9362 above, library files ending in .targets will be treated as MSBuild
9363 targets files and imported into generated project files. This is not
9364 supported by other generators.
9365 The full path to the library file will be quoted/escaped for the
9368 shell automatically.
9369 • A plain library name: The generated link line will ask the linker to
9371 search for the library (e.g. foo becomes -lfoo or foo.lib).
9372 The library name/flag is treated as a command-line string fragment
9374 and will be used with no extra quoting or escaping.
9375 • A link flag: Item names starting with -, but not -l or -framework,
9377 are treated as linker flags. Note that such flags will be treated
9378 like any other library link item for purposes of transitive dependen‐
9379 cies, so they are generally safe to specify only as private link
9380 items that will not propagate to dependents.
9381 Link flags specified here are inserted into the link command in the
9383 same place as the link libraries. This might not be correct, depend‐
9384 ing on the linker. Use the LINK_OPTIONS target property or tar‐
9385 get_link_options() command to add link flags explicitly. The flags
9386 will then be placed at the toolchain-defined flag position in the
9387 link command.
9388 New in version 3.13: LINK_OPTIONS target property and target_link_op‐
9390 tions() command. For earlier versions of CMake, use LINK_FLAGS prop‐
9391 erty instead.
9392 The link flag is treated as a command-line string fragment and will
9395 be used with no extra quoting or escaping.
9396 • A generator expression: A $<...> generator expression may evaluate to
9398 any of the above items or to a semicolon-separated list of them. If
9399 the ... contains any ; characters, e.g. after evaluation of a ${list}
9400 variable, be sure to use an explicitly quoted argument "$<...>" so
9401 that this command receives it as a single <item>.
9402 Additionally, a generator expression may be used as a fragment of any
9404 of the above items, e.g. foo$<1:_d>.
9405 Note that generator expressions will not be used in OLD handling of
9407 policy CMP0003 or policy CMP0004.
9408 • A debug, optimized, or general keyword immediately followed by an‐
9410 other <item>. The item following such a keyword will be used only
9411 for the corresponding build configuration. The debug keyword corre‐
9412 sponds to the Debug configuration (or to configurations named in the
9413 DEBUG_CONFIGURATIONS global property if it is set). The optimized
9414 keyword corresponds to all other configurations. The general keyword
9415 corresponds to all configurations, and is purely optional. Higher
9416 granularity may be achieved for per-configuration rules by creating
9417 and linking to IMPORTED library targets. These keywords are inter‐
9418 preted immediately by this command and therefore have no special
9419 meaning when produced by a generator expression.
9420 Items containing ::, such as Foo::Bar, are assumed to be IMPORTED or
9422 ALIAS library target names and will cause an error if no such target
9423 exists. See policy CMP0028.
9424 See the cmake-buildsystem(7) manual for more on defining buildsystem
9426 properties.
9427 Libraries for a Target and/or its Dependents
9429 target_link_libraries(<target>
9430 <PRIVATE|PUBLIC|INTERFACE> <item>...
9431 [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
9432 The PUBLIC, PRIVATE and INTERFACE keywords can be used to specify both
9434 the link dependencies and the link interface in one command. Libraries
9435 and targets following PUBLIC are linked to, and are made part of the
9436 link interface. Libraries and targets following PRIVATE are linked to,
9437 but are not made part of the link interface. Libraries following IN‐
9438 TERFACE are appended to the link interface and are not used for linking
9439 <target>.
9440 Libraries for both a Target and its Dependents
9442 target_link_libraries(<target> <item>...)
9443 Library dependencies are transitive by default with this signature.
9445 When this target is linked into another target then the libraries
9446 linked to this target will appear on the link line for the other target
9447 too. This transitive "link interface" is stored in the INTER‐
9448 FACE_LINK_LIBRARIES target property and may be overridden by setting
9449 the property directly. When CMP0022 is not set to NEW, transitive
9450 linking is built in but may be overridden by the LINK_INTERFACE_LI‐
9451 BRARIES property. Calls to other signatures of this command may set
9452 the property making any libraries linked exclusively by this signature
9453 private.
9454 Libraries for a Target and/or its Dependents (Legacy)
9456 target_link_libraries(<target>
9457 <LINK_PRIVATE|LINK_PUBLIC> <lib>...
9458 [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
9459 The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both the
9461 link dependencies and the link interface in one command.
9462 This signature is for compatibility only. Prefer the PUBLIC or PRIVATE
9464 keywords instead.
9465 Libraries and targets following LINK_PUBLIC are linked to, and are made
9467 part of the INTERFACE_LINK_LIBRARIES. If policy CMP0022 is not NEW,
9468 they are also made part of the LINK_INTERFACE_LIBRARIES. Libraries and
9469 targets following LINK_PRIVATE are linked to, but are not made part of
9470 the INTERFACE_LINK_LIBRARIES (or LINK_INTERFACE_LIBRARIES).
9471 Libraries for Dependents Only (Legacy)
9473 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
9474 The LINK_INTERFACE_LIBRARIES mode appends the libraries to the INTER‐
9476 FACE_LINK_LIBRARIES target property instead of using them for linking.
9477 If policy CMP0022 is not NEW, then this mode also appends libraries to
9478 the LINK_INTERFACE_LIBRARIES and its per-configuration equivalent.
9479 This signature is for compatibility only. Prefer the INTERFACE mode
9481 instead.
9482 Libraries specified as debug are wrapped in a generator expression to
9484 correspond to debug builds. If policy CMP0022 is not NEW, the li‐
9485 braries are also appended to the LINK_INTERFACE_LIBRARIES_DEBUG prop‐
9486 erty (or to the properties corresponding to configurations listed in
9487 the DEBUG_CONFIGURATIONS global property if it is set). Libraries
9488 specified as optimized are appended to the INTERFACE_LINK_LIBRARIES
9489 property. If policy CMP0022 is not NEW, they are also appended to the
9490 LINK_INTERFACE_LIBRARIES property. Libraries specified as general (or
9491 without any keyword) are treated as if specified for both debug and op‐
9492 timized.
9493 Linking Object Libraries
9495 New in version 3.12.
9496 Object Libraries may be used as the <target> (first) argument of tar‐
9499 get_link_libraries to specify dependencies of their sources on other
9500 libraries. For example, the code
9501 add_library(A SHARED a.c)
9503 target_compile_definitions(A PUBLIC A)
9504 add_library(obj OBJECT obj.c)
9506 target_compile_definitions(obj PUBLIC OBJ)
9507 target_link_libraries(obj PUBLIC A)
9508 compiles obj.c with -DA -DOBJ and establishes usage requirements for
9510 obj that propagate to its dependents.
9511 Normal libraries and executables may link to Object Libraries to get
9513 their objects and usage requirements. Continuing the above example,
9514 the code
9515 add_library(B SHARED b.c)
9517 target_link_libraries(B PUBLIC obj)
9518 compiles b.c with -DA -DOBJ, creates shared library B with object files
9520 from b.c and obj.c, and links B to A. Furthermore, the code
9521 add_executable(main main.c)
9523 target_link_libraries(main B)
9524 compiles main.c with -DA -DOBJ and links executable main to B and A.
9526 The object library's usage requirements are propagated transitively
9527 through B, but its object files are not.
9528 Object Libraries may "link" to other object libraries to get usage re‐
9530 quirements, but since they do not have a link step nothing is done with
9531 their object files. Continuing from the above example, the code:
9532 add_library(obj2 OBJECT obj2.c)
9534 target_link_libraries(obj2 PUBLIC obj)
9535 add_executable(main2 main2.c)
9537 target_link_libraries(main2 obj2)
9538 compiles obj2.c with -DA -DOBJ, creates executable main2 with object
9540 files from main2.c and obj2.c, and links main2 to A.
9541 In other words, when Object Libraries appear in a target's INTER‐
9543 FACE_LINK_LIBRARIES property they will be treated as Interface Li‐
9544 braries, but when they appear in a target's LINK_LIBRARIES property
9545 their object files will be included in the link too.
9546 Cyclic Dependencies of Static Libraries
9548 The library dependency graph is normally acyclic (a DAG), but in the
9549 case of mutually-dependent STATIC libraries CMake allows the graph to
9550 contain cycles (strongly connected components). When another target
9551 links to one of the libraries, CMake repeats the entire connected com‐
9552 ponent. For example, the code
9553 add_library(A STATIC a.c)
9555 add_library(B STATIC b.c)
9556 target_link_libraries(A B)
9557 target_link_libraries(B A)
9558 add_executable(main main.c)
9559 target_link_libraries(main A)
9560 links main to A B A B. While one repetition is usually sufficient,
9562 pathological object file and symbol arrangements can require more. One
9563 may handle such cases by using the LINK_INTERFACE_MULTIPLICITY target
9564 property or by manually repeating the component in the last tar‐
9565 get_link_libraries call. However, if two archives are really so inter‐
9566 dependent they should probably be combined into a single archive, per‐
9567 haps by using Object Libraries.
9568 Creating Relocatable Packages
9570 Note that it is not advisable to populate the INTERFACE_LINK_LIBRARIES
9571 of a target with absolute paths to dependencies. That would hard-code
9572 into installed packages the library file paths for dependencies as
9573 found on the machine the package was made on.
9574 See the Creating Relocatable Packages section of the cmake-packages(7)
9576 manual for discussion of additional care that must be taken when speci‐
9577 fying usage requirements while creating packages for redistribution.
9578 target_link_options
9580 New in version 3.13.
9581 Add options to the link step for an executable, shared library or mod‐
9584 ule library target.
9585 target_link_options(<target> [BEFORE]
9587 <INTERFACE|PUBLIC|PRIVATE> [items1...]
9588 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
9589 The named <target> must have been created by a command such as add_exe‐
9591 cutable() or add_library() and must not be an ALIAS target.
9592 This command can be used to add any link options, but alternative com‐
9594 mands exist to add libraries (target_link_libraries() or link_li‐
9595 braries()). See documentation of the directory and target LINK_OPTIONS
9596 properties.
9597 NOTE:
9599 This command cannot be used to add options for static library tar‐
9600 gets, since they do not use a linker. To add archiver or MSVC li‐
9601 brarian flags, see the STATIC_LIBRARY_OPTIONS target property.
9602 If BEFORE is specified, the content will be prepended to the property
9604 instead of being appended.
9605 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9607 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
9608 late the LINK_OPTIONS property of <target>. PUBLIC and INTERFACE items
9609 will populate the INTERFACE_LINK_OPTIONS property of <target>. The
9610 following arguments specify link options. Repeated calls for the same
9611 <target> append items in the order called.
9612 NOTE:
9614 IMPORTED targets only support INTERFACE items.
9615 Arguments to target_link_options may use "generator expressions" with
9617 the syntax $<...>. See the cmake-generator-expressions(7) manual for
9618 available expressions. See the cmake-buildsystem(7) manual for more on
9619 defining buildsystem properties.
9620 New in version 3.18: When a device link step is involved, which is con‐
9622 trolled by CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS
9623 properties and policy CMP0105, the raw options will be delivered to the
9624 host and device link steps (wrapped in -Xcompiler or equivalent for de‐
9625 vice link). Options wrapped with $<DEVICE_LINK:...> generator expres‐
9626 sion will be used only for the device link step. Options wrapped with
9627 $<HOST_LINK:...> generator expression will be used only for the host
9628 link step.
9629 The final set of compile or link options used for a target is construc‐
9632 ted by accumulating options from the current target and the usage re‐
9633 quirements of its dependencies. The set of options is de-duplicated to
9634 avoid repetition.
9635 New in version 3.12: While beneficial for individual options, the
9637 de-duplication step can break up option groups. For example, -D A -D B
9638 becomes -D A B. One may specify a group of options using shell-like
9639 quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and
9640 the rest of the option string is parsed using the separate_arguments()
9641 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
9642 -D B.
9643 To pass options to the linker tool, each compiler driver has its own
9646 syntax. The LINKER: prefix and , separator can be used to specify, in
9647 a portable way, options to pass to the linker tool. LINKER: is replaced
9648 by the appropriate driver option and , by the appropriate driver sepa‐
9649 rator. The driver prefix and driver separator are given by the values
9650 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAP‐
9651 PER_FLAG_SEP variables.
9652 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
9654 Clang and -Wl,-z,defs for GNU GCC.
9655 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
9657 sion.
9658 The LINKER: prefix supports, as an alternative syntax, specification of
9660 arguments using the SHELL: prefix and space as separator. The previous
9661 example then becomes "LINKER:SHELL:-z defs".
9662 NOTE:
9664 Specifying the SHELL: prefix anywhere other than at the beginning of
9665 the LINKER: prefix is not supported.
9666 target_precompile_headers
9668 New in version 3.16.
9669 Add a list of header files to precompile.
9672 Precompiling header files can speed up compilation by creating a par‐
9674 tially processed version of some header files, and then using that ver‐
9675 sion during compilations rather than repeatedly parsing the original
9676 headers.
9677 Main Form
9679 target_precompile_headers(<target>
9680 <INTERFACE|PUBLIC|PRIVATE> [header1...]
9681 [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])
9682 The command adds header files to the PRECOMPILE_HEADERS and/or INTER‐
9684 FACE_PRECOMPILE_HEADERS target properties of <target>. The named <tar‐
9685 get> must have been created by a command such as add_executable() or
9686 add_library() and must not be an ALIAS target.
9687 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9689 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
9690 late the PRECOMPILE_HEADERS property of <target>. PUBLIC and INTERFACE
9691 items will populate the INTERFACE_PRECOMPILE_HEADERS property of <tar‐
9692 get> (IMPORTED targets only support INTERFACE items). Repeated calls
9693 for the same <target> will append items in the order called.
9694 Projects should generally avoid using PUBLIC or INTERFACE for targets
9696 that will be exported, or they should at least use the $<BUILD_INTER‐
9697 FACE:...> generator expression to prevent precompile headers from ap‐
9698 pearing in an installed exported target. Consumers of a target should
9699 typically be in control of what precompile headers they use, not have
9700 precompile headers forced on them by the targets being consumed (since
9701 precompile headers are not typically usage requirements). A notable
9702 exception to this is where an interface library is created to define a
9703 commonly used set of precompile headers in one place and then other
9704 targets link to that interface library privately. In this case, the
9705 interface library exists specifically to propagate the precompile head‐
9706 ers to its consumers and the consumer is effectively still in control,
9707 since it decides whether to link to the interface library or not.
9708 The list of header files is used to generate a header file named
9710 cmake_pch.h|xx which is used to generate the precompiled header file
9711 (.pch, .gch, .pchi) artifact. The cmake_pch.h|xx header file will be
9712 force included (-include for GCC, /FI for MSVC) to all source files, so
9713 sources do not need to have #include "pch.h".
9714 Header file names specified with angle brackets (e.g. <unordered_map>)
9716 or explicit double quotes (escaped for the cmake-language(7), e.g.
9717 [["other_header.h"]]) will be treated as is, and include directories
9718 must be available for the compiler to find them. Other header file
9719 names (e.g. project_header.h) are interpreted as being relative to the
9720 current source directory (e.g. CMAKE_CURRENT_SOURCE_DIR) and will be
9721 included by absolute path. For example:
9722 target_precompile_headers(myTarget
9724 PUBLIC
9725 project_header.h
9726 PRIVATE
9727 [["other_header.h"]]
9728 <unordered_map>
9729 )
9730 Arguments to target_precompile_headers() may use "generator expres‐
9732 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
9733 manual for available expressions. The $<COMPILE_LANGUAGE:...> genera‐
9734 tor expression is particularly useful for specifying a language-spe‐
9735 cific header to precompile for only one language (e.g. CXX and not C).
9736 In this case, header file names that are not explicitly in double
9737 quotes or angle brackets must be specified by absolute path. Also,
9738 when specifying angle brackets inside a generator expression, be sure
9739 to encode the closing > as $<ANGLE-R>. For example:
9740 target_precompile_headers(mylib PRIVATE
9742 "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/cxx_only.h>"
9743 "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
9744 "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
9745 )
9746 Reusing Precompile Headers
9748 The command also supports a second signature which can be used to spec‐
9749 ify that one target re-uses a precompiled header file artifact from an‐
9750 other target instead of generating its own:
9751 target_precompile_headers(<target> REUSE_FROM <other_target>)
9753 This form sets the PRECOMPILE_HEADERS_REUSE_FROM property to
9755 <other_target> and adds a dependency such that <target> will depend on
9756 <other_target>. CMake will halt with an error if the PRECOMPILE_HEAD‐
9757 ERS property of <target> is already set when the REUSE_FROM form is
9758 used.
9759 NOTE:
9761 The REUSE_FROM form requires the same set of compiler options, com‐
9762 piler flags and compiler definitions for both <target> and
9763 <other_target>. Some compilers (e.g. GCC) may issue a warning if
9764 the precompiled header file cannot be used (-Winvalid-pch).
9765 See Also
9767 To disable precompile headers for specific targets, see the DIS‐
9768 ABLE_PRECOMPILE_HEADERS target property.
9769 To prevent precompile headers from being used when compiling a specific
9771 source file, see the SKIP_PRECOMPILE_HEADERS source file property.
9772 target_sources
9774 New in version 3.1.
9775 Add sources to a target.
9778 target_sources(<target>
9780 <INTERFACE|PUBLIC|PRIVATE> [items1...]
9781 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
9782 Specifies sources to use when building a target and/or its dependents.
9784 The named <target> must have been created by a command such as add_exe‐
9785 cutable() or add_library() or add_custom_target() and must not be an
9786 ALIAS target.
9787 Changed in version 3.13: Relative source file paths are interpreted as
9789 being relative to the current source directory (i.e. CMAKE_CUR‐
9790 RENT_SOURCE_DIR). See policy CMP0076.
9791 New in version 3.20: <target> can be a custom target.
9794 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
9797 scope of the items following them. PRIVATE and PUBLIC items will popu‐
9798 late the SOURCES property of <target>, which are used when building the
9799 target itself. PUBLIC and INTERFACE items will populate the INTER‐
9800 FACE_SOURCES property of <target>, which are used when building depen‐
9801 dents. The following arguments specify sources. Repeated calls for
9802 the same <target> append items in the order called. The targets created
9803 by add_custom_target() can only have PRIVATE scope.
9804 New in version 3.3: Allow exporting targets with INTERFACE_SOURCES.
9806 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
9809 Arguments to target_sources may use "generator expressions" with the
9812 syntax $<...>. See the cmake-generator-expressions(7) manual for avail‐
9813 able expressions. See the cmake-buildsystem(7) manual for more on
9814 defining buildsystem properties.
9815 try_compile
9817 Try building some code.
9818 Try Compiling Whole Projects
9820 try_compile(<resultVar> <bindir> <srcdir>
9821 <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
9822 [OUTPUT_VARIABLE <var>])
9823 Try building a project. The success or failure of the try_compile,
9825 i.e. TRUE or FALSE respectively, is returned in <resultVar>.
9826 New in version 3.14: The name of the <resultVar> is defined by the
9828 user. Previously, it had a fixed name RESULT_VAR.
9829 In this form, <srcdir> should contain a complete CMake project with a
9832 CMakeLists.txt file and all sources. The <bindir> and <srcdir> will
9833 not be deleted after this command is run. Specify <targetName> to
9834 build a specific target instead of the all or ALL_BUILD target. See
9835 below for the meaning of other options.
9836 Try Compiling Source Files
9838 try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
9839 [CMAKE_FLAGS <flags>...]
9840 [COMPILE_DEFINITIONS <defs>...]
9841 [LINK_OPTIONS <options>...]
9842 [LINK_LIBRARIES <libs>...]
9843 [OUTPUT_VARIABLE <var>]
9844 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
9845 [<LANG>_STANDARD <std>]
9846 [<LANG>_STANDARD_REQUIRED <bool>]
9847 [<LANG>_EXTENSIONS <bool>]
9848 )
9849 Try building an executable or static library from one or more source
9851 files (which one is determined by the CMAKE_TRY_COMPILE_TARGET_TYPE
9852 variable). The success or failure of the try_compile, i.e. TRUE or
9853 FALSE respectively, is returned in <resultVar>.
9854 New in version 3.14: The name of the <resultVar> is defined by the
9856 user. Previously, it had a fixed name RESULT_VAR.
9857 In this form, one or more source files must be provided. If
9860 CMAKE_TRY_COMPILE_TARGET_TYPE is unset or is set to EXECUTABLE, the
9861 sources must include a definition for main and CMake will create a
9862 CMakeLists.txt file to build the source(s) as an executable. If
9863 CMAKE_TRY_COMPILE_TARGET_TYPE is set to STATIC_LIBRARY, a static li‐
9864 brary will be built instead and no definition for main is required.
9865 For an executable, the generated CMakeLists.txt file would contain
9866 something like the following:
9867 add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
9869 include_directories(${INCLUDE_DIRECTORIES})
9870 link_directories(${LINK_DIRECTORIES})
9871 add_executable(cmTryCompileExec <srcfile>...)
9872 target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
9873 target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
9874 The options are:
9876 CMAKE_FLAGS <flags>...
9878 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
9879 cmake command-line used to drive the test build. The above ex‐
9880 ample shows how values for variables INCLUDE_DIRECTORIES,
9881 LINK_DIRECTORIES, and LINK_LIBRARIES are used.
9882 COMPILE_DEFINITIONS <defs>...
9884 Specify -Ddefinition arguments to pass to add_definitions() in
9885 the generated test project.
9886 COPY_FILE <fileName>
9888 Copy the built executable or static library to the given <file‐
9889 Name>.
9890 COPY_FILE_ERROR <var>
9892 Use after COPY_FILE to capture into variable <var> any error
9893 message encountered while trying to copy the file.
9894 LINK_LIBRARIES <libs>...
9896 Specify libraries to be linked in the generated project. The
9897 list of libraries may refer to system libraries and to Imported
9898 Targets from the calling project.
9899 If this option is specified, any -DLINK_LIBRARIES=... value
9901 given to the CMAKE_FLAGS option will be ignored.
9902 LINK_OPTIONS <options>...
9904 New in version 3.14.
9905 Specify link step options to pass to target_link_options() or to
9908 set the STATIC_LIBRARY_OPTIONS target property in the generated
9909 project, depending on the CMAKE_TRY_COMPILE_TARGET_TYPE vari‐
9910 able.
9911 OUTPUT_VARIABLE <var>
9913 Store the output from the build process in the given variable.
9914 <LANG>_STANDARD <std>
9916 New in version 3.8.
9917 Specify the C_STANDARD, CXX_STANDARD, OBJC_STANDARD, OB‐
9920 JCXX_STANDARD, or CUDA_STANDARD target property of the generated
9921 project.
9922 <LANG>_STANDARD_REQUIRED <bool>
9924 New in version 3.8.
9925 Specify the C_STANDARD_REQUIRED, CXX_STANDARD_REQUIRED,
9928 OBJC_STANDARD_REQUIRED, OBJCXX_STANDARD_REQUIRED,or CUDA_STAN‐
9929 DARD_REQUIRED target property of the generated project.
9930 <LANG>_EXTENSIONS <bool>
9932 New in version 3.8.
9933 Specify the C_EXTENSIONS, CXX_EXTENSIONS, OBJC_EXTENSIONS, OB‐
9936 JCXX_EXTENSIONS, or CUDA_EXTENSIONS target property of the gen‐
9937 erated project.
9938 In this version all files in <bindir>/CMakeFiles/CMakeTmp will be
9940 cleaned automatically. For debugging, --debug-trycompile can be passed
9941 to cmake to avoid this clean. However, multiple sequential try_compile
9942 operations reuse this single output directory. If you use --de‐
9943 bug-trycompile, you can only debug one try_compile call at a time. The
9944 recommended procedure is to protect all try_compile calls in your
9945 project by if(NOT DEFINED <resultVar>) logic, configure with cmake all
9946 the way through once, then delete the cache entry associated with the
9947 try_compile call of interest, and then re-run cmake again with --de‐
9948 bug-trycompile.
9949 Other Behavior Settings
9951 New in version 3.4: If set, the following variables are passed in to
9952 the generated try_compile CMakeLists.txt to initialize compile target
9953 properties with default values:
9954 • CMAKE_CUDA_RUNTIME_LIBRARY
9956 • CMAKE_ENABLE_EXPORTS
9958 • CMAKE_LINK_SEARCH_START_STATIC
9960 • CMAKE_LINK_SEARCH_END_STATIC
9962 • CMAKE_MSVC_RUNTIME_LIBRARY
9964 • CMAKE_POSITION_INDEPENDENT_CODE
9966 If CMP0056 is set to NEW, then CMAKE_EXE_LINKER_FLAGS is passed in as
9968 well.
9969 Changed in version 3.14: If CMP0083 is set to NEW, then in order to ob‐
9972 tain correct behavior at link time, the check_pie_supported() command
9973 from the CheckPIESupported module must be called before using the
9974 try_compile() command.
9975 The current settings of CMP0065 and CMP0083 are propagated through to
9978 the generated test project.
9979 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
9981 figuration.
9982 New in version 3.6: Set the CMAKE_TRY_COMPILE_TARGET_TYPE variable to
9984 specify the type of target used for the source file signature.
9985 New in version 3.6: Set the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES vari‐
9988 able to specify variables that must be propagated into the test
9989 project. This variable is meant for use only in toolchain files and is
9990 only honored by the try_compile() command for the source files form,
9991 not when given a whole project.
9992 Changed in version 3.8: If CMP0067 is set to NEW, or any of the
9995 <LANG>_STANDARD, <LANG>_STANDARD_REQUIRED, or <LANG>_EXTENSIONS options
9996 are used, then the language standard variables are honored:
9997 • CMAKE_C_STANDARD
9999 • CMAKE_C_STANDARD_REQUIRED
10001 • CMAKE_C_EXTENSIONS
10003 • CMAKE_CXX_STANDARD
10005 • CMAKE_CXX_STANDARD_REQUIRED
10007 • CMAKE_CXX_EXTENSIONS
10009 • CMAKE_OBJC_STANDARD
10011 • CMAKE_OBJC_STANDARD_REQUIRED
10013 • CMAKE_OBJC_EXTENSIONS
10015 • CMAKE_OBJCXX_STANDARD
10017 • CMAKE_OBJCXX_STANDARD_REQUIRED
10019 • CMAKE_OBJCXX_EXTENSIONS
10021 • CMAKE_CUDA_STANDARD
10023 • CMAKE_CUDA_STANDARD_REQUIRED
10025 • CMAKE_CUDA_EXTENSIONS
10027 Their values are used to set the corresponding target properties in the
10029 generated project (unless overridden by an explicit option).
10030 Changed in version 3.14: For the Green Hills MULTI generator the GHS
10033 toolset and target system customization cache variables are also propa‐
10034 gated into the test project.
10035 try_run
10038 Try compiling and then running some code.
10039 Try Compiling and Running Source Files
10041 try_run(<runResultVar> <compileResultVar>
10042 <bindir> <srcfile> [CMAKE_FLAGS <flags>...]
10043 [COMPILE_DEFINITIONS <defs>...]
10044 [LINK_OPTIONS <options>...]
10045 [LINK_LIBRARIES <libs>...]
10046 [COMPILE_OUTPUT_VARIABLE <var>]
10047 [RUN_OUTPUT_VARIABLE <var>]
10048 [OUTPUT_VARIABLE <var>]
10049 [WORKING_DIRECTORY <var>]
10050 [ARGS <args>...])
10051 Try compiling a <srcfile>. Returns TRUE or FALSE for success or fail‐
10053 ure in <compileResultVar>. If the compile succeeded, runs the exe‐
10054 cutable and returns its exit code in <runResultVar>. If the executable
10055 was built, but failed to run, then <runResultVar> will be set to
10056 FAILED_TO_RUN. See the try_compile() command for information on how
10057 the test project is constructed to build the source file.
10058 New in version 3.14: The names of the result variables <runResultVar>
10060 and <compileResultVar> are defined by the user. Previously, they had
10061 fixed names RUN_RESULT_VAR and COMPILE_RESULT_VAR.
10062 The options are:
10065 CMAKE_FLAGS <flags>...
10067 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
10068 cmake command-line used to drive the test build. The example in
10069 try_compile() shows how values for variables INCLUDE_DIRECTO‐
10070 RIES, LINK_DIRECTORIES, and LINK_LIBRARIES are used.
10071 COMPILE_DEFINITIONS <defs>...
10073 Specify -Ddefinition arguments to pass to add_definitions() in
10074 the generated test project.
10075 COMPILE_OUTPUT_VARIABLE <var>
10077 Report the compile step build output in a given variable.
10078 LINK_LIBRARIES <libs>...
10080 New in version 3.2.
10081 Specify libraries to be linked in the generated project. The
10084 list of libraries may refer to system libraries and to Imported
10085 Targets from the calling project.
10086 If this option is specified, any -DLINK_LIBRARIES=... value
10088 given to the CMAKE_FLAGS option will be ignored.
10089 LINK_OPTIONS <options>...
10091 New in version 3.14.
10092 Specify link step options to pass to target_link_options() in
10095 the generated project.
10096 OUTPUT_VARIABLE <var>
10098 Report the compile build output and the output from running the
10099 executable in the given variable. This option exists for legacy
10100 reasons. Prefer COMPILE_OUTPUT_VARIABLE and RUN_OUTPUT_VARIABLE
10101 instead.
10102 RUN_OUTPUT_VARIABLE <var>
10104 Report the output from running the executable in a given vari‐
10105 able.
10106 WORKING_DIRECTORY <var>
10108 New in version 3.20.
10109 Run the executable in the given directory. If no WORKING_DIREC‐
10112 TORY is specified, the executable will run in <bindir>.
10113 Other Behavior Settings
10115 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
10116 figuration.
10117 Behavior when Cross Compiling
10119 New in version 3.3: Use CMAKE_CROSSCOMPILING_EMULATOR when running
10120 cross-compiled binaries.
10121 When cross compiling, the executable compiled in the first step usually
10124 cannot be run on the build host. The try_run command checks the
10125 CMAKE_CROSSCOMPILING variable to detect whether CMake is in cross-com‐
10126 piling mode. If that is the case, it will still try to compile the ex‐
10127 ecutable, but it will not try to run the executable unless the
10128 CMAKE_CROSSCOMPILING_EMULATOR variable is set. Instead it will create
10129 cache variables which must be filled by the user or by presetting them
10130 in some CMake script file to the values the executable would have pro‐
10131 duced if it had been run on its actual target platform. These cache
10132 entries are:
10133 <runResultVar>
10135 Exit code if the executable were to be run on the target plat‐
10136 form.
10137 <runResultVar>__TRYRUN_OUTPUT
10139 Output from stdout and stderr if the executable were to be run
10140 on the target platform. This is created only if the RUN_OUT‐
10141 PUT_VARIABLE or OUTPUT_VARIABLE option was used.
10142 In order to make cross compiling your project easier, use try_run only
10144 if really required. If you use try_run, use the RUN_OUTPUT_VARIABLE or
10145 OUTPUT_VARIABLE options only if really required. Using them will re‐
10146 quire that when cross-compiling, the cache variables will have to be
10147 set manually to the output of the executable. You can also "guard" the
10148 calls to try_run with an if() block checking the CMAKE_CROSSCOMPILING
10149 variable and provide an easy-to-preset alternative for this case.
10150
10152 These commands are available only in CTest scripts.
10153 ctest_build
10155 Perform the CTest Build Step as a Dashboard Client.
10156 ctest_build([BUILD <build-dir>] [APPEND]
10158 [CONFIGURATION <config>]
10159 [FLAGS <flags>]
10160 [PROJECT_NAME <project-name>]
10161 [TARGET <target-name>]
10162 [NUMBER_ERRORS <num-err-var>]
10163 [NUMBER_WARNINGS <num-warn-var>]
10164 [RETURN_VALUE <result-var>]
10165 [CAPTURE_CMAKE_ERROR <result-var>]
10166 )
10167 Build the project and store results in Build.xml for submission with
10169 the ctest_submit() command.
10170 The CTEST_BUILD_COMMAND variable may be set to explicitly specify the
10172 build command line. Otherwise the build command line is computed auto‐
10173 matically based on the options given.
10174 The options are:
10176 BUILD <build-dir>
10178 Specify the top-level build directory. If not given, the
10179 CTEST_BINARY_DIRECTORY variable is used.
10180 APPEND Mark Build.xml for append to results previously submitted to a
10182 dashboard server since the last ctest_start() call. Append se‐
10183 mantics are defined by the dashboard server in use. This does
10184 not cause results to be appended to a .xml file produced by a
10185 previous call to this command.
10186 CONFIGURATION <config>
10188 Specify the build configuration (e.g. Debug). If not specified
10189 the CTEST_BUILD_CONFIGURATION variable will be checked. Other‐
10190 wise the -C <cfg> option given to the ctest(1) command will be
10191 used, if any.
10192 FLAGS <flags>
10194 Pass additional arguments to the underlying build command. If
10195 not specified the CTEST_BUILD_FLAGS variable will be checked.
10196 This can, e.g., be used to trigger a parallel build using the -j
10197 option of make. See the ProcessorCount module for an example.
10198 PROJECT_NAME <project-name>
10200 Ignored since CMake 3.0.
10201 Changed in version 3.14: This value is no longer required.
10203 TARGET <target-name>
10206 Specify the name of a target to build. If not specified the
10207 CTEST_BUILD_TARGET variable will be checked. Otherwise the de‐
10208 fault target will be built. This is the "all" target (called
10209 ALL_BUILD in Visual Studio Generators).
10210 NUMBER_ERRORS <num-err-var>
10212 Store the number of build errors detected in the given variable.
10213 NUMBER_WARNINGS <num-warn-var>
10215 Store the number of build warnings detected in the given vari‐
10216 able.
10217 RETURN_VALUE <result-var>
10219 Store the return value of the native build tool in the given
10220 variable.
10221 CAPTURE_CMAKE_ERROR <result-var>
10223 New in version 3.7.
10224 Store in the <result-var> variable -1 if there are any errors
10227 running the command and prevent ctest from returning non-zero if
10228 an error occurs.
10229 QUIET New in version 3.3.
10231 Suppress any CTest-specific non-error output that would have
10234 been printed to the console otherwise. The summary of warnings
10235 / errors, as well as the output from the native build tool is
10236 unaffected by this option.
10237 ctest_configure
10239 Perform the CTest Configure Step as a Dashboard Client.
10240 ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
10242 [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
10243 [CAPTURE_CMAKE_ERROR <result-var>])
10244 Configure the project build tree and record results in Configure.xml
10246 for submission with the ctest_submit() command.
10247 The options are:
10249 BUILD <build-dir>
10251 Specify the top-level build directory. If not given, the
10252 CTEST_BINARY_DIRECTORY variable is used.
10253 SOURCE <source-dir>
10255 Specify the source directory. If not given, the
10256 CTEST_SOURCE_DIRECTORY variable is used.
10257 APPEND Mark Configure.xml for append to results previously submitted to
10259 a dashboard server since the last ctest_start() call. Append
10260 semantics are defined by the dashboard server in use. This does
10261 not cause results to be appended to a .xml file produced by a
10262 previous call to this command.
10263 OPTIONS <options>
10265 Specify command-line arguments to pass to the configuration
10266 tool.
10267 RETURN_VALUE <result-var>
10269 Store in the <result-var> variable the return value of the na‐
10270 tive configuration tool.
10271 CAPTURE_CMAKE_ERROR <result-var>
10273 New in version 3.7.
10274 Store in the <result-var> variable -1 if there are any errors
10277 running the command and prevent ctest from returning non-zero if
10278 an error occurs.
10279 QUIET New in version 3.3.
10281 Suppress any CTest-specific non-error messages that would have
10284 otherwise been printed to the console. Output from the underly‐
10285 ing configure command is not affected.
10286 ctest_coverage
10288 Perform the CTest Coverage Step as a Dashboard Client.
10289 ctest_coverage([BUILD <build-dir>] [APPEND]
10291 [LABELS <label>...]
10292 [RETURN_VALUE <result-var>]
10293 [CAPTURE_CMAKE_ERROR <result-var>]
10294 [QUIET]
10295 )
10296 Collect coverage tool results and stores them in Coverage.xml for sub‐
10298 mission with the ctest_submit() command.
10299 The options are:
10301 BUILD <build-dir>
10303 Specify the top-level build directory. If not given, the
10304 CTEST_BINARY_DIRECTORY variable is used.
10305 APPEND Mark Coverage.xml for append to results previously submitted to
10307 a dashboard server since the last ctest_start() call. Append
10308 semantics are defined by the dashboard server in use. This does
10309 not cause results to be appended to a .xml file produced by a
10310 previous call to this command.
10311 LABELS Filter the coverage report to include only source files labeled
10313 with at least one of the labels specified.
10314 RETURN_VALUE <result-var>
10316 Store in the <result-var> variable 0 if coverage tools ran with‐
10317 out error and non-zero otherwise.
10318 CAPTURE_CMAKE_ERROR <result-var>
10320 New in version 3.7.
10321 Store in the <result-var> variable -1 if there are any errors
10324 running the command and prevent ctest from returning non-zero if
10325 an error occurs.
10326 QUIET New in version 3.3.
10328 Suppress any CTest-specific non-error output that would have
10331 been printed to the console otherwise. The summary indicating
10332 how many lines of code were covered is unaffected by this op‐
10333 tion.
10334 ctest_empty_binary_directory
10336 empties the binary directory
10337 ctest_empty_binary_directory( directory )
10339 Removes a binary directory. This command will perform some checks
10341 prior to deleting the directory in an attempt to avoid malicious or ac‐
10342 cidental directory deletion.
10343 ctest_memcheck
10345 Perform the CTest MemCheck Step as a Dashboard Client.
10346 ctest_memcheck([BUILD <build-dir>] [APPEND]
10348 [START <start-number>]
10349 [END <end-number>]
10350 [STRIDE <stride-number>]
10351 [EXCLUDE <exclude-regex>]
10352 [INCLUDE <include-regex>]
10353 [EXCLUDE_LABEL <label-exclude-regex>]
10354 [INCLUDE_LABEL <label-include-regex>]
10355 [EXCLUDE_FIXTURE <regex>]
10356 [EXCLUDE_FIXTURE_SETUP <regex>]
10357 [EXCLUDE_FIXTURE_CLEANUP <regex>]
10358 [PARALLEL_LEVEL <level>]
10359 [TEST_LOAD <threshold>]
10360 [SCHEDULE_RANDOM <ON|OFF>]
10361 [STOP_TIME <time-of-day>]
10362 [RETURN_VALUE <result-var>]
10363 [DEFECT_COUNT <defect-count-var>]
10364 [QUIET]
10365 )
10366 Run tests with a dynamic analysis tool and store results in Mem‐
10368 Check.xml for submission with the ctest_submit() command.
10369 Most options are the same as those for the ctest_test() command.
10371 The options unique to this command are:
10373 DEFECT_COUNT <defect-count-var>
10375 New in version 3.8.
10376 Store in the <defect-count-var> the number of defects found.
10379 ctest_read_custom_files
10381 read CTestCustom files.
10382 ctest_read_custom_files( directory ... )
10384 Read all the CTestCustom.ctest or CTestCustom.cmake files from the
10386 given directory.
10387 By default, invoking ctest(1) without a script will read custom files
10389 from the binary directory.
10390 ctest_run_script
10392 runs a ctest -S script
10393 ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
10395 script_file_name2 ... [RETURN_VALUE var])
10396 Runs a script or scripts much like if it was run from ctest -S. If no
10398 argument is provided then the current script is run using the current
10399 settings of the variables. If NEW_PROCESS is specified then each
10400 script will be run in a separate process.If RETURN_VALUE is specified
10401 the return value of the last script run will be put into var.
10402 ctest_sleep
10404 sleeps for some amount of time
10405 ctest_sleep(<seconds>)
10407 Sleep for given number of seconds.
10409 ctest_sleep(<time1> <duration> <time2>)
10411 Sleep for t=(time1 + duration - time2) seconds if t > 0.
10413 ctest_start
10415 Starts the testing for a given model
10416 ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])
10418 ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET])
10420 Starts the testing for a given model. The command should be called af‐
10422 ter the binary directory is initialized.
10423 The parameters are as follows:
10425 <model>
10427 Set the dashboard model. Must be one of Experimental, Continu‐
10428 ous, or Nightly. This parameter is required unless APPEND is
10429 specified.
10430 <source>
10432 Set the source directory. If not specified, the value of
10433 CTEST_SOURCE_DIRECTORY is used instead.
10434 <binary>
10436 Set the binary directory. If not specified, the value of
10437 CTEST_BINARY_DIRECTORY is used instead.
10438 GROUP <group>
10440 If GROUP is used, the submissions will go to the specified group
10441 on the CDash server. If no GROUP is specified, the name of the
10442 model is used by default.
10443 Changed in version 3.16: This replaces the deprecated option
10445 TRACK. Despite the name change its behavior is unchanged.
10446 APPEND If APPEND is used, the existing TAG is used rather than creating
10449 a new one based on the current time stamp. If you use APPEND,
10450 you can omit the <model> and GROUP <group> parameters, because
10451 they will be read from the generated TAG file. For example:
10452 ctest_start(Experimental GROUP GroupExperimental)
10454 Later, in another ctest -S script:
10456 ctest_start(APPEND)
10458 When the second script runs ctest_start(APPEND), it will read
10460 the Experimental model and GroupExperimental group from the TAG
10461 file generated by the first ctest_start() command. Please note
10462 that if you call ctest_start(APPEND) and specify a different
10463 model or group than in the first ctest_start() command, a warn‐
10464 ing will be issued, and the new model and group will be used.
10465 QUIET New in version 3.3.
10467 If QUIET is used, CTest will suppress any non-error messages
10470 that it otherwise would have printed to the console.
10471 The parameters for ctest_start() can be issued in any order, with the
10473 exception that <model>, <source>, and <binary> have to appear in that
10474 order with respect to each other. The following are all valid and
10475 equivalent:
10476 ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND)
10478 ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary)
10480 ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary)
10482 However, for the sake of readability, it is recommended that you order
10484 your parameters in the order listed at the top of this page.
10485 If the CTEST_CHECKOUT_COMMAND variable (or the CTEST_CVS_CHECKOUT vari‐
10487 able) is set, its content is treated as command-line. The command is
10488 invoked with the current working directory set to the parent of the
10489 source directory, even if the source directory already exists. This
10490 can be used to create the source tree from a version control reposi‐
10491 tory.
10492 ctest_submit
10494 Perform the CTest Submit Step as a Dashboard Client.
10495 ctest_submit([PARTS <part>...] [FILES <file>...]
10497 [SUBMIT_URL <url>]
10498 [BUILD_ID <result-var>]
10499 [HTTPHEADER <header>]
10500 [RETRY_COUNT <count>]
10501 [RETRY_DELAY <delay>]
10502 [RETURN_VALUE <result-var>]
10503 [CAPTURE_CMAKE_ERROR <result-var>]
10504 [QUIET]
10505 )
10506 Submit results to a dashboard server. By default all available parts
10508 are submitted.
10509 The options are:
10511 PARTS <part>...
10513 Specify a subset of parts to submit. Valid part names are:
10514 Start = nothing
10516 Update = ctest_update results, in Update.xml
10517 Configure = ctest_configure results, in Configure.xml
10518 Build = ctest_build results, in Build.xml
10519 Test = ctest_test results, in Test.xml
10520 Coverage = ctest_coverage results, in Coverage.xml
10521 MemCheck = ctest_memcheck results, in DynamicAnalysis.xml
10522 Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
10523 ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
10524 Upload = Files prepared for upload by ctest_upload(), in Upload.xml
10525 Submit = nothing
10526 Done = Build is complete, in Done.xml
10527 FILES <file>...
10529 Specify an explicit list of specific files to be submitted.
10530 Each individual file must exist at the time of the call.
10531 SUBMIT_URL <url>
10533 New in version 3.14.
10534 The http or https URL of the dashboard server to send the sub‐
10537 mission to. If not given, the CTEST_SUBMIT_URL variable is
10538 used.
10539 BUILD_ID <result-var>
10541 New in version 3.15.
10542 Store in the <result-var> variable the ID assigned to this build
10545 by CDash.
10546 HTTPHEADER <HTTP-header>
10548 New in version 3.9.
10549 Specify HTTP header to be included in the request to CDash dur‐
10552 ing submission. For example, CDash can be configured to only
10553 accept submissions from authenticated clients. In this case, you
10554 should provide a bearer token in your header:
10555 ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>")
10557 This suboption can be repeated several times for multiple head‐
10559 ers.
10560 RETRY_COUNT <count>
10562 Specify how many times to retry a timed-out submission.
10563 RETRY_DELAY <delay>
10565 Specify how long (in seconds) to wait after a timed-out submis‐
10566 sion before attempting to re-submit.
10567 RETURN_VALUE <result-var>
10569 Store in the <result-var> variable 0 for success and non-zero on
10570 failure.
10571 CAPTURE_CMAKE_ERROR <result-var>
10573 New in version 3.13.
10574 Store in the <result-var> variable -1 if there are any errors
10577 running the command and prevent ctest from returning non-zero if
10578 an error occurs.
10579 QUIET New in version 3.3.
10581 Suppress all non-error messages that would have otherwise been
10584 printed to the console.
10585 Submit to CDash Upload API
10587 New in version 3.2.
10588 ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
10591 [SUBMIT_URL <url>]
10592 [BUILD_ID <result-var>]
10593 [HTTPHEADER <header>]
10594 [RETRY_COUNT <count>]
10595 [RETRY_DELAY <delay>]
10596 [RETURN_VALUE <result-var>]
10597 [QUIET])
10598 This second signature is used to upload files to CDash via the CDash
10600 file upload API. The API first sends a request to upload to CDash along
10601 with a content hash of the file. If CDash does not already have the
10602 file, then it is uploaded. Along with the file, a CDash type string is
10603 specified to tell CDash which handler to use to process the data.
10604 This signature interprets options in the same way as the first one.
10606 New in version 3.8: Added the RETRY_COUNT, RETRY_DELAY, QUIET options.
10608 New in version 3.9: Added the HTTPHEADER option.
10611 New in version 3.13: Added the RETURN_VALUE option.
10614 New in version 3.14: Added the SUBMIT_URL option.
10617 New in version 3.15: Added the BUILD_ID option.
10620 ctest_test
10623 Perform the CTest Test Step as a Dashboard Client.
10624 ctest_test([BUILD <build-dir>] [APPEND]
10626 [START <start-number>]
10627 [END <end-number>]
10628 [STRIDE <stride-number>]
10629 [EXCLUDE <exclude-regex>]
10630 [INCLUDE <include-regex>]
10631 [EXCLUDE_LABEL <label-exclude-regex>]
10632 [INCLUDE_LABEL <label-include-regex>]
10633 [EXCLUDE_FIXTURE <regex>]
10634 [EXCLUDE_FIXTURE_SETUP <regex>]
10635 [EXCLUDE_FIXTURE_CLEANUP <regex>]
10636 [PARALLEL_LEVEL <level>]
10637 [RESOURCE_SPEC_FILE <file>]
10638 [TEST_LOAD <threshold>]
10639 [SCHEDULE_RANDOM <ON|OFF>]
10640 [STOP_ON_FAILURE]
10641 [STOP_TIME <time-of-day>]
10642 [RETURN_VALUE <result-var>]
10643 [CAPTURE_CMAKE_ERROR <result-var>]
10644 [REPEAT <mode>:<n>]
10645 [QUIET]
10646 )
10647 Run tests in the project build tree and store results in Test.xml for
10649 submission with the ctest_submit() command.
10650 The options are:
10652 BUILD <build-dir>
10654 Specify the top-level build directory. If not given, the
10655 CTEST_BINARY_DIRECTORY variable is used.
10656 APPEND Mark Test.xml for append to results previously submitted to a
10658 dashboard server since the last ctest_start() call. Append se‐
10659 mantics are defined by the dashboard server in use. This does
10660 not cause results to be appended to a .xml file produced by a
10661 previous call to this command.
10662 START <start-number>
10664 Specify the beginning of a range of test numbers.
10665 END <end-number>
10667 Specify the end of a range of test numbers.
10668 STRIDE <stride-number>
10670 Specify the stride by which to step across a range of test num‐
10671 bers.
10672 EXCLUDE <exclude-regex>
10674 Specify a regular expression matching test names to exclude.
10675 INCLUDE <include-regex>
10677 Specify a regular expression matching test names to include.
10678 Tests not matching this expression are excluded.
10679 EXCLUDE_LABEL <label-exclude-regex>
10681 Specify a regular expression matching test labels to exclude.
10682 INCLUDE_LABEL <label-include-regex>
10684 Specify a regular expression matching test labels to include.
10685 Tests not matching this expression are excluded.
10686 EXCLUDE_FIXTURE <regex>
10688 New in version 3.7.
10689 If a test in the set of tests to be executed requires a particu‐
10692 lar fixture, that fixture's setup and cleanup tests would nor‐
10693 mally be added to the test set automatically. This option pre‐
10694 vents adding setup or cleanup tests for fixtures matching the
10695 <regex>. Note that all other fixture behavior is retained, in‐
10696 cluding test dependencies and skipping tests that have fixture
10697 setup tests that fail.
10698 EXCLUDE_FIXTURE_SETUP <regex>
10700 New in version 3.7.
10701 Same as EXCLUDE_FIXTURE except only matching setup tests are ex‐
10704 cluded.
10705 EXCLUDE_FIXTURE_CLEANUP <regex>
10707 New in version 3.7.
10708 Same as EXCLUDE_FIXTURE except only matching cleanup tests are
10711 excluded.
10712 PARALLEL_LEVEL <level>
10714 Specify a positive number representing the number of tests to be
10715 run in parallel.
10716 RESOURCE_SPEC_FILE <file>
10718 New in version 3.16.
10719 Specify a resource specification file. See ctest-resource-allo‐
10722 cation for more information.
10723 TEST_LOAD <threshold>
10725 New in version 3.4.
10726 While running tests in parallel, try not to start tests when
10729 they may cause the CPU load to pass above a given threshold. If
10730 not specified the CTEST_TEST_LOAD variable will be checked, and
10731 then the --test-load command-line argument to ctest(1). See
10732 also the TestLoad setting in the CTest Test Step.
10733 REPEAT <mode>:<n>
10735 New in version 3.17.
10736 Run tests repeatedly based on the given <mode> up to <n> times.
10739 The modes are:
10740 UNTIL_FAIL
10742 Require each test to run <n> times without failing in or‐
10743 der to pass. This is useful in finding sporadic failures
10744 in test cases.
10745 UNTIL_PASS
10747 Allow each test to run up to <n> times in order to pass.
10748 Repeats tests if they fail for any reason. This is use‐
10749 ful in tolerating sporadic failures in test cases.
10750 AFTER_TIMEOUT
10752 Allow each test to run up to <n> times in order to pass.
10753 Repeats tests only if they timeout. This is useful in
10754 tolerating sporadic timeouts in test cases on busy ma‐
10755 chines.
10756 SCHEDULE_RANDOM <ON|OFF>
10758 Launch tests in a random order. This may be useful for detect‐
10759 ing implicit test dependencies.
10760 STOP_ON_FAILURE
10762 New in version 3.18.
10763 Stop the execution of the tests once one has failed.
10766 STOP_TIME <time-of-day>
10768 Specify a time of day at which the tests should all stop run‐
10769 ning.
10770 RETURN_VALUE <result-var>
10772 Store in the <result-var> variable 0 if all tests passed. Store
10773 non-zero if anything went wrong.
10774 CAPTURE_CMAKE_ERROR <result-var>
10776 New in version 3.7.
10777 Store in the <result-var> variable -1 if there are any errors
10780 running the command and prevent ctest from returning non-zero if
10781 an error occurs.
10782 QUIET New in version 3.3.
10784 Suppress any CTest-specific non-error messages that would have
10787 otherwise been printed to the console. Output from the underly‐
10788 ing test command is not affected. Summary info detailing the
10789 percentage of passing tests is also unaffected by the QUIET op‐
10790 tion.
10791 See also the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE and
10793 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables.
10794 ctest_update
10796 Perform the CTest Update Step as a Dashboard Client.
10797 ctest_update([SOURCE <source-dir>]
10799 [RETURN_VALUE <result-var>]
10800 [CAPTURE_CMAKE_ERROR <result-var>]
10801 [QUIET])
10802 Update the source tree from version control and record results in Up‐
10804 date.xml for submission with the ctest_submit() command.
10805 The options are:
10807 SOURCE <source-dir>
10809 Specify the source directory. If not given, the
10810 CTEST_SOURCE_DIRECTORY variable is used.
10811 RETURN_VALUE <result-var>
10813 Store in the <result-var> variable the number of files updated
10814 or -1 on error.
10815 CAPTURE_CMAKE_ERROR <result-var>
10817 New in version 3.13.
10818 Store in the <result-var> variable -1 if there are any errors
10821 running the command and prevent ctest from returning non-zero if
10822 an error occurs.
10823 QUIET New in version 3.3.
10825 Tell CTest to suppress most non-error messages that it would
10828 have otherwise printed to the console. CTest will still report
10829 the new revision of the repository and any conflicting files
10830 that were found.
10831 The update always follows the version control branch currently checked
10833 out in the source directory. See the CTest Update Step documentation
10834 for information about variables that change the behavior of ctest_up‐
10835 date().
10836 ctest_upload
10838 Upload files to a dashboard server as a Dashboard Client.
10839 ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
10841 The options are:
10843 FILES <file>...
10845 Specify a list of files to be sent along with the build results
10846 to the dashboard server.
10847 QUIET New in version 3.3.
10849 Suppress any CTest-specific non-error output that would have
10852 been printed to the console otherwise.
10853 CAPTURE_CMAKE_ERROR <result-var>
10855 New in version 3.7.
10856 Store in the <result-var> variable -1 if there are any errors
10859 running the command and prevent ctest from returning non-zero if
10860 an error occurs.
10861
10863 These commands are deprecated and are only made available to maintain
10864 backward compatibility. The documentation of each command states the
10865 CMake version in which it was deprecated. Do not use these commands in
10866 new code.
10867 build_name
10869 Disallowed since version 3.0. See CMake Policy CMP0036.
10870 Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.
10872 build_name(variable)
10874 Sets the specified variable to a string representing the platform and
10876 compiler settings. These values are now available through the
10877 CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
10878 exec_program
10880 Deprecated since version 3.0: Use the execute_process() command in‐
10881 stead.
10882 Run an executable program during the processing of the CMakeList.txt
10885 file.
10886 exec_program(Executable [directory in which to run]
10888 [ARGS <arguments to executable>]
10889 [OUTPUT_VARIABLE <var>]
10890 [RETURN_VALUE <var>])
10891 The executable is run in the optionally specified directory. The exe‐
10893 cutable can include arguments if it is double quoted, but it is better
10894 to use the optional ARGS argument to specify arguments to the program.
10895 This is because cmake will then be able to escape spaces in the exe‐
10896 cutable path. An optional argument OUTPUT_VARIABLE specifies a vari‐
10897 able in which to store the output. To capture the return value of the
10898 execution, provide a RETURN_VALUE. If OUTPUT_VARIABLE is specified,
10899 then no output will go to the stdout/stderr of the console running
10900 cmake.
10901 export_library_dependencies
10903 Disallowed since version 3.0. See CMake Policy CMP0033.
10904 Use install(EXPORT) or export() command.
10906 This command generates an old-style library dependencies file.
10908 Projects requiring CMake 2.6 or later should not use the command. Use
10909 instead the install(EXPORT) command to help export targets from an in‐
10910 stallation tree and the export() command to export targets from a build
10911 tree.
10912 The old-style library dependencies file does not take into account
10914 per-configuration names of libraries or the LINK_INTERFACE_LIBRARIES
10915 target property.
10916 export_library_dependencies(<file> [APPEND])
10918 Create a file named <file> that can be included into a CMake listfile
10920 with the INCLUDE command. The file will contain a number of SET com‐
10921 mands that will set all the variables needed for library dependency in‐
10922 formation. This should be the last command in the top level CMake‐
10923 Lists.txt file of the project. If the APPEND option is specified, the
10924 SET commands will be appended to the given file instead of replacing
10925 it.
10926 install_files
10928 Deprecated since version 3.0: Use the install(FILES) command instead.
10929 This command has been superceded by the install() command. It is pro‐
10932 vided for compatibility with older CMake code. The FILES form is di‐
10933 rectly replaced by the FILES form of the install() command. The regexp
10934 form can be expressed more clearly using the GLOB form of the file()
10935 command.
10936 install_files(<dir> extension file file ...)
10938 Create rules to install the listed files with the given extension into
10940 the given directory. Only files existing in the current source tree or
10941 its corresponding location in the binary tree may be listed. If a file
10942 specified already has an extension, that extension will be removed
10943 first. This is useful for providing lists of source files such as
10944 foo.cxx when you want the corresponding foo.h to be installed. A typi‐
10945 cal extension is .h.
10946 install_files(<dir> regexp)
10948 Any files in the current source directory that match the regular ex‐
10950 pression will be installed.
10951 install_files(<dir> FILES file file ...)
10953 Any files listed after the FILES keyword will be installed explicitly
10955 from the names given. Full paths are allowed in this form.
10956 The directory <dir> is relative to the installation prefix, which is
10958 stored in the variable CMAKE_INSTALL_PREFIX.
10959 install_programs
10961 Deprecated since version 3.0: Use the install(PROGRAMS) command in‐
10962 stead.
10963 This command has been superceded by the install() command. It is pro‐
10966 vided for compatibility with older CMake code. The FILES form is di‐
10967 rectly replaced by the PROGRAMS form of the install() command. The
10968 regexp form can be expressed more clearly using the GLOB form of the
10969 file() command.
10970 install_programs(<dir> file1 file2 [file3 ...])
10972 install_programs(<dir> FILES file1 [file2 ...])
10973 Create rules to install the listed programs into the given directory.
10975 Use the FILES argument to guarantee that the file list version of the
10976 command will be used even when there is only one argument.
10977 install_programs(<dir> regexp)
10979 In the second form any program in the current source directory that
10981 matches the regular expression will be installed.
10982 This command is intended to install programs that are not built by
10984 cmake, such as shell scripts. See the TARGETS form of the install()
10985 command to create installation rules for targets built by cmake.
10986 The directory <dir> is relative to the installation prefix, which is
10988 stored in the variable CMAKE_INSTALL_PREFIX.
10989 install_targets
10991 Deprecated since version 3.0: Use the install(TARGETS) command instead.
10992 This command has been superceded by the install() command. It is pro‐
10995 vided for compatibility with older CMake code.
10996 install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
10998 Create rules to install the listed targets into the given directory.
11000 The directory <dir> is relative to the installation prefix, which is
11001 stored in the variable CMAKE_INSTALL_PREFIX. If RUNTIME_DIRECTORY is
11002 specified, then on systems with special runtime files (Windows DLL),
11003 the files will be copied to that directory.
11004 load_command
11006 Disallowed since version 3.0. See CMake Policy CMP0031.
11007 Load a command into a running CMake.
11009 load_command(COMMAND_NAME <loc1> [loc2 ...])
11011 The given locations are searched for a library whose name is cmCOM‐
11013 MAND_NAME. If found, it is loaded as a module and the command is added
11014 to the set of available CMake commands. Usually, try_compile() is used
11015 before this command to compile the module. If the command is success‐
11016 fully loaded a variable named
11017 CMAKE_LOADED_COMMAND_<COMMAND_NAME>
11019 will be set to the full path of the module that was loaded. Otherwise
11021 the variable will not be set.
11022 make_directory
11024 Deprecated since version 3.0: Use the file(MAKE_DIRECTORY) command in‐
11025 stead.
11026 make_directory(directory)
11029 Creates the specified directory. Full paths should be given. Any par‐
11031 ent directories that do not exist will also be created. Use with care.
11032 output_required_files
11034 Disallowed since version 3.0. See CMake Policy CMP0032.
11035 Approximate C preprocessor dependency scanning.
11037 This command exists only because ancient CMake versions provided it.
11039 CMake handles preprocessor dependency scanning automatically using a
11040 more advanced scanner.
11041 output_required_files(srcfile outputfile)
11043 Outputs a list of all the source files that are required by the speci‐
11045 fied srcfile. This list is written into outputfile. This is similar
11046 to writing out the dependencies for srcfile except that it jumps from
11047 .h files into .cxx, .c and .cpp files if possible.
11048 qt_wrap_cpp
11050 Deprecated since version 3.14: This command was originally added to
11051 support Qt 3 before the add_custom_command() command was sufficiently
11052 mature. The FindQt4 module provides the qt4_wrap_cpp() macro, which
11053 should be used instead for Qt 4 projects. For projects using Qt 5 or
11054 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
11055 vides qt5_wrap_cpp()).
11056 Manually create Qt Wrappers.
11059 qt_wrap_cpp(resultingLibraryName DestName SourceLists ...)
11061 Produces moc files for all the .h files listed in the SourceLists. The
11063 moc files will be added to the library using the DestName source list.
11064 Consider updating the project to use the AUTOMOC target property in‐
11066 stead for a more automated way of invoking the moc tool.
11067 qt_wrap_ui
11069 Deprecated since version 3.14: This command was originally added to
11070 support Qt 3 before the add_custom_command() command was sufficiently
11071 mature. The FindQt4 module provides the qt4_wrap_ui() macro, which
11072 should be used instead for Qt 4 projects. For projects using Qt 5 or
11073 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
11074 vides qt5_wrap_ui()).
11075 Manually create Qt user interfaces Wrappers.
11078 qt_wrap_ui(resultingLibraryName HeadersDestName
11080 SourcesDestName SourceLists ...)
11081 Produces .h and .cxx files for all the .ui files listed in the
11083 SourceLists. The .h files will be added to the library using the Head‐
11084 ersDestNamesource list. The .cxx files will be added to the library
11085 using the SourcesDestNamesource list.
11086 Consider updating the project to use the AUTOUIC target property in‐
11088 stead for a more automated way of invoking the uic tool.
11089 remove
11091 Deprecated since version 3.0: Use the list(REMOVE_ITEM) command in‐
11092 stead.
11093 remove(VAR VALUE VALUE ...)
11096 Removes VALUE from the variable VAR. This is typically used to remove
11098 entries from a vector (e.g. semicolon separated list). VALUE is ex‐
11099 panded.
11100 subdir_depends
11102 Disallowed since version 3.0. See CMake Policy CMP0029.
11103 Does nothing.
11105 subdir_depends(subdir dep1 dep2 ...)
11107 Does not do anything. This command used to help projects order paral‐
11109 lel builds correctly. This functionality is now automatic.
11110 subdirs
11112 Deprecated since version 3.0: Use the add_subdirectory() command in‐
11113 stead.
11114 Add a list of subdirectories to the build.
11117 subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
11119 [PREORDER] )
11120 Add a list of subdirectories to the build. The add_subdirectory() com‐
11122 mand should be used instead of subdirs although subdirs will still
11123 work. This will cause any CMakeLists.txt files in the sub directories
11124 to be processed by CMake. Any directories after the PREORDER flag are
11125 traversed first by makefile builds, the PREORDER flag has no effect on
11126 IDE projects. Any directories after the EXCLUDE_FROM_ALL marker will
11127 not be included in the top level makefile or project file. This is
11128 useful for having CMake create makefiles or projects for a set of exam‐
11129 ples in a project. You would want CMake to generate makefiles or
11130 project files for all the examples at the same time, but you would not
11131 want them to show up in the top level project or be built each time
11132 make is run from the top.
11133 use_mangled_mesa
11135 Disallowed since version 3.0. See CMake Policy CMP0030.
11136 Copy mesa headers for use in combination with system GL.
11138 use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
11140 The path to mesa includes, should contain gl_mangle.h. The mesa head‐
11142 ers are copied to the specified output directory. This allows mangled
11143 mesa headers to override other GL headers by being added to the include
11144 directory path earlier.
11145 utility_source
11147 Disallowed since version 3.0. See CMake Policy CMP0034.
11148 Specify the source tree of a third-party utility.
11150 utility_source(cache_entry executable_name
11152 path_to_source [file1 file2 ...])
11153 When a third-party utility's source is included in the distribution,
11155 this command specifies its location and name. The cache entry will not
11156 be set unless the path_to_source and all listed files exist. It is as‐
11157 sumed that the source tree of the utility will have been built before
11158 it is needed.
11159 When cross compiling CMake will print a warning if a utility_source()
11161 command is executed, because in many cases it is used to build an exe‐
11162 cutable which is executed later on. This doesn't work when cross com‐
11163 piling, since the executable can run only on their target platform. So
11164 in this case the cache entry has to be adjusted manually so it points
11165 to an executable which is runnable on the build host.
11166 variable_requires
11168 Disallowed since version 3.0. See CMake Policy CMP0035.
11169 Use the if() command instead.
11171 Assert satisfaction of an option's required variables.
11173 variable_requires(TEST_VARIABLE RESULT_VARIABLE
11175 REQUIRED_VARIABLE1
11176 REQUIRED_VARIABLE2 ...)
11177 The first argument (TEST_VARIABLE) is the name of the variable to be
11179 tested, if that variable is false nothing else is done. If TEST_VARI‐
11180 ABLE is true, then the next argument (RESULT_VARIABLE) is a variable
11181 that is set to true if all the required variables are set. The rest of
11182 the arguments are variables that must be true or not set to NOTFOUND to
11183 avoid an error. If any are not true, an error is reported.
11184 write_file
11186 Deprecated since version 3.0: Use the file(WRITE) command instead.
11187 write_file(filename "message to write"... [APPEND])
11190 The first argument is the file name, the rest of the arguments are mes‐
11192 sages to write. If the argument APPEND is specified, then the message
11193 will be appended.
11194 NOTE 1: file(WRITE) and file(APPEND) do exactly the same as this one
11196 but add some more functionality.
11197 NOTE 2: When using write_file the produced file cannot be used as an
11199 input to CMake (CONFIGURE_FILE, source file ...) because it will lead
11200 to an infinite loop. Use configure_file() if you want to generate in‐
11201 put files to CMake.
11202
11204 2000-2021 Kitware, Inc. and Contributors
112053.20.3 May 30, 2021 CMAKE-COMMANDS(7)