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 │IS_64BIT │ One if processor is 64Bit │
56 ├──────────────────────────┼────────────────────────────┤
57 │HAS_FPU │ One if processor has │
58 │ │ floating point unit │
59 ├──────────────────────────┼────────────────────────────┤
60 │HAS_MMX │ One if processor supports │
61 │ │ MMX instructions │
62 ├──────────────────────────┼────────────────────────────┤
63 │HAS_MMX_PLUS │ One if processor supports │
64 │ │ Ext. MMX instructions │
65 └──────────────────────────┴────────────────────────────┘
66 │HAS_SSE │ One if processor supports │
68 │ │ SSE instructions │
69 ├──────────────────────────┼────────────────────────────┤
70 │HAS_SSE2 │ One if processor supports │
71 │ │ SSE2 instructions │
72 ├──────────────────────────┼────────────────────────────┤
73 │HAS_SSE_FP │ One if processor supports │
74 │ │ SSE FP instructions │
75 ├──────────────────────────┼────────────────────────────┤
76 │HAS_SSE_MMX │ One if processor supports │
77 │ │ SSE MMX instructions │
78 ├──────────────────────────┼────────────────────────────┤
79 │HAS_AMD_3DNOW │ One if processor supports │
80 │ │ 3DNow instructions │
81 ├──────────────────────────┼────────────────────────────┤
82 │HAS_AMD_3DNOW_PLUS │ One if processor supports │
83 │ │ 3DNow+ instructions │
84 ├──────────────────────────┼────────────────────────────┤
85 │HAS_IA64 │ One if IA64 processor emu‐ │
86 │ │ lating x86 │
87 ├──────────────────────────┼────────────────────────────┤
88 │HAS_SERIAL_NUMBER │ One if processor has │
89 │ │ serial number │
90 ├──────────────────────────┼────────────────────────────┤
91 │PROCESSOR_SERIAL_NUMBER │ Processor serial number │
92 ├──────────────────────────┼────────────────────────────┤
93 │PROCESSOR_NAME │ Human readable processor │
94 │ │ name │
95 ├──────────────────────────┼────────────────────────────┤
96 │PROCESSOR_DESCRIPTION │ Human readable full pro‐ │
97 │ │ cessor description │
98 ├──────────────────────────┼────────────────────────────┤
99 │OS_NAME │ See CMAKE_HOST_SYSTEM_NAME │
100 ├──────────────────────────┼────────────────────────────┤
101 │OS_RELEASE │ The OS sub-type e.g. on │
102 │ │ Windows Professional │
103 ├──────────────────────────┼────────────────────────────┤
104 │OS_VERSION │ The OS build ID │
105 ├──────────────────────────┼────────────────────────────┤
106 │OS_PLATFORM │ See CMAKE_HOST_SYSTEM_PRO‐ │
107 │ │ CESSOR │
108 └──────────────────────────┴────────────────────────────┘
109
111 [1] One MiB (mebibyte) is equal to 1024x1024 bytes.
112 cmake_language
114 New in version 3.18.
115 Call meta-operations on CMake commands.
118 Synopsis
120 cmake_language(CALL <command> [<arg>...])
121 cmake_language(EVAL CODE <code>...)
122 cmake_language(DEFER <options>... CALL <command> [<arg>...])
123 Introduction
125 This command will call meta-operations on built-in CMake commands or
126 those created via the macro() or function() commands.
127 cmake_language does not introduce a new variable or policy scope.
129 Calling Commands
131 cmake_language(CALL <command> [<arg>...])
132 Calls the named <command> with the given arguments (if any). For exam‐
134 ple, the code:
135 set(message_command "message")
137 cmake_language(CALL ${message_command} STATUS "Hello World!")
138 is equivalent to
140 message(STATUS "Hello World!")
142 NOTE:
144 To ensure consistency of the code, the following commands are not
145 allowed:
146 · if / elseif / else / endif
148 · while / endwhile
150 · foreach / endforeach
152 · function / endfunction
154 · macro / endmacro
156 Evaluating Code
158 cmake_language(EVAL CODE <code>...)
159 Evaluates the <code>... as CMake code.
161 For example, the code:
163 set(A TRUE)
165 set(B TRUE)
166 set(C TRUE)
167 set(condition "(A AND B) OR C")
168 cmake_language(EVAL CODE "
170 if (${condition})
171 message(STATUS TRUE)
172 else()
173 message(STATUS FALSE)
174 endif()"
175 )
176 is equivalent to
178 set(A TRUE)
180 set(B TRUE)
181 set(C TRUE)
182 set(condition "(A AND B) OR C")
183 file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
185 if (${condition})
186 message(STATUS TRUE)
187 else()
188 message(STATUS FALSE)
189 endif()"
190 )
191 include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)
193 Deferring Calls
195 New in version 3.19.
196 cmake_language(DEFER <options>... CALL <command> [<arg>...])
199 Schedules a call to the named <command> with the given arguments (if
201 any) to occur at a later time. By default, deferred calls are executed
202 as if written at the end of the current directory’s CMakeLists.txt
203 file, except that they run even after a return() call. Variable refer‐
204 ences in arguments are evaluated at the time the deferred call is exe‐
205 cuted.
206 The options are:
208 DIRECTORY <dir>
210 Schedule the call for the end of the given directory instead of
211 the current directory. The <dir> may reference either a source
212 directory or its corresponding binary directory. Relative paths
213 are treated as relative to the current source directory.
214 The given directory must be known to CMake, being either the
216 top-level directory or one added by add_subdirectory(). Fur‐
217 thermore, the given directory must not yet be finished process‐
218 ing. This means it can be the current directory or one of its
219 ancestors.
220 ID <id>
222 Specify an identification for the deferred call. The <id> may
223 not be empty and may not begin with a capital letter A-Z. The
224 <id> may begin with an underscore (_) only if it was generated
225 automatically by an earlier call that used ID_VAR to get the id.
226 ID_VAR <var>
228 Specify a variable in which to store the identification for the
229 deferred call. If ID <id> is not given, a new identification
230 will be generated and the generated id will start with an under‐
231 score (_).
232 The currently scheduled list of deferred calls may be retrieved:
234 cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)
236 This will store in <var> a semicolon-separated list of deferred call
238 ids. The ids are for the directory scope in which the calls have been
239 deferred to (i.e. where they will be executed), which can be different
240 to the scope in which they were created. The DIRECTORY option can be
241 used to specify the scope for which to retrieve the call ids. If that
242 option is not given, the call ids for the current directory scope will
243 be returned.
244 Details of a specific call may be retrieved from its id:
246 cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)
248 This will store in <var> a semicolon-separated list in which the first
250 element is the name of the command to be called, and the remaining ele‐
251 ments are its unevaluated arguments (any contained ; characters are
252 included literally and cannot be distinguished from multiple argu‐
253 ments). If multiple calls are scheduled with the same id, this
254 retrieves the first one. If no call is scheduled with the given id in
255 the specified DIRECTORY scope (or the current directory scope if no
256 DIRECTORY option is given), this stores an empty string in the vari‐
257 able.
258 Deferred calls may be canceled by their id:
260 cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)
262 This cancels all deferred calls matching any of the given ids in the
264 specified DIRECTORY scope (or the current directory scope if no DIREC‐
265 TORY option is given). Unknown ids are silently ignored.
266 Deferred Call Examples
268 For example, the code:
269 cmake_language(DEFER CALL message "${deferred_message}")
271 cmake_language(DEFER ID_VAR id CALL message "Cancelled Message")
272 cmake_language(DEFER CANCEL_CALL ${id})
273 message("Immediate Message")
274 set(deferred_message "Deferred Message")
275 prints:
277 Immediate Message
279 Deferred Message
280 The Cancelled Message is never printed because its command is can‐
282 celled. The deferred_message variable reference is not evaluated until
283 the call site, so it can be set after the deferred call is scheduled.
284 In order to evaluate variable references immediately when scheduling a
286 deferred call, wrap it using cmake_language(EVAL). However, note that
287 arguments will be re-evaluated in the deferred call, though that can be
288 avoided by using bracket arguments. For example:
289 set(deferred_message "Deferred Message 1")
291 set(re_evaluated [[${deferred_message}]])
292 cmake_language(EVAL CODE "
293 cmake_language(DEFER CALL message [[${deferred_message}]])
294 cmake_language(DEFER CALL message \"${re_evaluated}\")
295 ")
296 message("Immediate Message")
297 set(deferred_message "Deferred Message 2")
298 also prints:
300 Immediate Message
302 Deferred Message 1
303 Deferred Message 2
304 cmake_minimum_required
306 Require a minimum version of cmake.
307 cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR])
309 Sets the minimum required version of cmake for a project. Also updates
311 the policy settings as explained below.
312 <min> and the optional <max> are each CMake versions of the form
314 major.minor[.patch[.tweak]], and the ... is literal.
315 If the running version of CMake is lower than the <min> required ver‐
317 sion it will stop processing the project and report an error. The
318 optional <max> version, if specified, must be at least the <min> ver‐
319 sion and affects policy settings as described below. If the running
320 version of CMake is older than 3.12, the extra ... dots will be seen
321 as version component separators, resulting in the ...<max> part being
322 ignored and preserving the pre-3.12 behavior of basing policies on
323 <min>.
324 This command will set the value of the CMAKE_MINIMUM_REQUIRED_VERSION
326 variable to <min>.
327 The FATAL_ERROR option is accepted but ignored by CMake 2.6 and higher.
329 It should be specified so CMake versions 2.4 and lower fail with an
330 error instead of just a warning.
331 NOTE:
333 Call the cmake_minimum_required() command at the beginning of the
334 top-level CMakeLists.txt file even before calling the project() com‐
335 mand. It is important to establish version and policy settings
336 before invoking other commands whose behavior they may affect. See
337 also policy CMP0000.
338 Calling cmake_minimum_required() inside a function() limits some
340 effects to the function scope when invoked. Such calls should not
341 be made with the intention of having global effects.
342 Policy Settings
344 The cmake_minimum_required(VERSION) command implicitly invokes the
345 cmake_policy(VERSION) command to specify that the current project code
346 is written for the given range of CMake versions. All policies known
347 to the running version of CMake and introduced in the <min> (or <max>,
348 if specified) version or earlier will be set to use NEW behavior. All
349 policies introduced in later versions will be unset. This effectively
350 requests behavior preferred as of a given CMake version and tells newer
351 CMake versions to warn about their new policies.
352 When a <min> version higher than 2.4 is specified the command implic‐
354 itly invokes
355 cmake_policy(VERSION <min>[...<max>])
357 which sets CMake policies based on the range of versions specified.
359 When a <min> version 2.4 or lower is given the command implicitly
360 invokes
361 cmake_policy(VERSION 2.4[...<max>])
363 which enables compatibility features for CMake 2.4 and lower.
365 cmake_parse_arguments
367 New in version 3.5.
368 Parse function or macro arguments.
371 cmake_parse_arguments(<prefix> <options> <one_value_keywords>
373 <multi_value_keywords> <args>...)
374 cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
376 <one_value_keywords> <multi_value_keywords>)
377 This command is for use in macros or functions. It processes the argu‐
379 ments given to that macro or function, and defines a set of variables
380 which hold the values of the respective options.
381 The first signature reads processes arguments passed in the <args>....
383 This may be used in either a macro() or a function().
384 The PARSE_ARGV signature is only for use in a function() body. In this
386 case the arguments that are parsed come from the ARGV# variables of the
387 calling function. The parsing starts with the <N>-th argument, where
388 <N> is an unsigned integer. This allows for the values to have special
389 characters like ; in them.
390 The <options> argument contains all options for the respective macro,
392 i.e. keywords which can be used when calling the macro without any
393 value following, like e.g. the OPTIONAL keyword of the install() com‐
394 mand.
395 The <one_value_keywords> argument contains all keywords for this macro
397 which are followed by one value, like e.g. DESTINATION keyword of the
398 install() command.
399 The <multi_value_keywords> argument contains all keywords for this
401 macro which can be followed by more than one value, like e.g. the TAR‐
402 GETS or FILES keywords of the install() command.
403 NOTE:
405 All keywords shall be unique. I.e. every keyword shall only be spec‐
406 ified once in either <options>, <one_value_keywords> or
407 <multi_value_keywords>. A warning will be emitted if uniqueness is
408 violated.
409 When done, cmake_parse_arguments will consider for each of the keywords
411 listed in <options>, <one_value_keywords> and <multi_value_keywords> a
412 variable composed of the given <prefix> followed by "_" and the name of
413 the respective keyword. These variables will then hold the respective
414 value from the argument list or be undefined if the associated option
415 could not be found. For the <options> keywords, these will always be
416 defined, to TRUE or FALSE, whether the option is in the argument list
417 or not.
418 All remaining arguments are collected in a variable <pre‐
420 fix>_UNPARSED_ARGUMENTS that will be undefined if all arguments were
421 recognized. This can be checked afterwards to see whether your macro
422 was called with unrecognized parameters.
423 <one_value_keywords> and <multi_value_keywords> that were given no val‐
425 ues at all are collected in a variable <prefix>_KEYWORDS_MISSING_VALUES
426 that will be undefined if all keywords received values. This can be
427 checked to see if there were keywords without any values given.
428 Consider the following example macro, my_install(), which takes similar
430 arguments to the real install() command:
431 macro(my_install)
433 set(options OPTIONAL FAST)
434 set(oneValueArgs DESTINATION RENAME)
435 set(multiValueArgs TARGETS CONFIGURATIONS)
436 cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
437 "${multiValueArgs}" ${ARGN} )
438 # ...
440 Assume my_install() has been called like this:
442 my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)
444 After the cmake_parse_arguments call the macro will have set or unde‐
446 fined the following variables:
447 MY_INSTALL_OPTIONAL = TRUE
449 MY_INSTALL_FAST = FALSE # was not used in call to my_install
450 MY_INSTALL_DESTINATION = "bin"
451 MY_INSTALL_RENAME <UNDEFINED> # was not used
452 MY_INSTALL_TARGETS = "foo;bar"
453 MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
454 MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
455 MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS"
456 # No value for "CONFIGURATIONS" given
457 You can then continue and process these variables.
459 Keywords terminate lists of values, e.g. if directly after a
461 one_value_keyword another recognized keyword follows, this is inter‐
462 preted as the beginning of the new option. E.g. my_install(TARGETS
463 foo DESTINATION OPTIONAL) would result in MY_INSTALL_DESTINATION set to
464 "OPTIONAL", but as OPTIONAL is a keyword itself MY_INSTALL_DESTINATION
465 will be empty (but added to MY_INSTALL_KEYWORDS_MISSING_VALUES) and
466 MY_INSTALL_OPTIONAL will therefore be set to TRUE.
467 cmake_policy
469 Manage CMake Policy settings. See the cmake-policies(7) manual for
470 defined policies.
471 As CMake evolves it is sometimes necessary to change existing behavior
473 in order to fix bugs or improve implementations of existing features.
474 The CMake Policy mechanism is designed to help keep existing projects
475 building as new versions of CMake introduce changes in behavior. Each
476 new policy (behavioral change) is given an identifier of the form
477 CMP<NNNN> where <NNNN> is an integer index. Documentation associated
478 with each policy describes the OLD and NEW behavior and the reason the
479 policy was introduced. Projects may set each policy to select the
480 desired behavior. When CMake needs to know which behavior to use it
481 checks for a setting specified by the project. If no setting is avail‐
482 able the OLD behavior is assumed and a warning is produced requesting
483 that the policy be set.
484 Setting Policies by CMake Version
486 The cmake_policy command is used to set policies to OLD or NEW behav‐
487 ior. While setting policies individually is supported, we encourage
488 projects to set policies based on CMake versions:
489 cmake_policy(VERSION <min>[...<max>])
491 <min> and the optional <max> are each CMake versions of the form
493 major.minor[.patch[.tweak]], and the ... is literal. The <min> version
494 must be at least 2.4 and at most the running version of CMake. The
495 <max> version, if specified, must be at least the <min> version but may
496 exceed the running version of CMake. If the running version of CMake
497 is older than 3.12, the extra ... dots will be seen as version compo‐
498 nent separators, resulting in the ...<max> part being ignored and pre‐
499 serving the pre-3.12 behavior of basing policies on <min>.
500 This specifies that the current CMake code is written for the given
502 range of CMake versions. All policies known to the running version of
503 CMake and introduced in the <min> (or <max>, if specified) version or
504 earlier will be set to use NEW behavior. All policies introduced in
505 later versions will be unset (unless the CMAKE_POLICY_DEFAULT_CMP<NNNN>
506 variable sets a default). This effectively requests behavior preferred
507 as of a given CMake version and tells newer CMake versions to warn
508 about their new policies.
509 Note that the cmake_minimum_required(VERSION) command implicitly calls
511 cmake_policy(VERSION) too.
512 Setting Policies Explicitly
514 cmake_policy(SET CMP<NNNN> NEW)
515 cmake_policy(SET CMP<NNNN> OLD)
516 Tell CMake to use the OLD or NEW behavior for a given policy. Projects
518 depending on the old behavior of a given policy may silence a policy
519 warning by setting the policy state to OLD. Alternatively one may fix
520 the project to work with the new behavior and set the policy state to
521 NEW.
522 NOTE:
524 The OLD behavior of a policy is deprecated by definition and may be
525 removed in a future version of CMake.
526 Checking Policy Settings
528 cmake_policy(GET CMP<NNNN> <variable>)
529 Check whether a given policy is set to OLD or NEW behavior. The output
531 <variable> value will be OLD or NEW if the policy is set, and empty
532 otherwise.
533 CMake Policy Stack
535 CMake keeps policy settings on a stack, so changes made by the
536 cmake_policy command affect only the top of the stack. A new entry on
537 the policy stack is managed automatically for each subdirectory to pro‐
538 tect its parents and siblings. CMake also manages a new entry for
539 scripts loaded by include() and find_package() commands except when
540 invoked with the NO_POLICY_SCOPE option (see also policy CMP0011). The
541 cmake_policy command provides an interface to manage custom entries on
542 the policy stack:
543 cmake_policy(PUSH)
545 cmake_policy(POP)
546 Each PUSH must have a matching POP to erase any changes. This is use‐
548 ful to make temporary changes to policy settings. Calls to the
549 cmake_minimum_required(VERSION), cmake_policy(VERSION), or cmake_pol‐
550 icy(SET) commands influence only the current top of the policy stack.
551 Commands created by the function() and macro() commands record policy
553 settings when they are created and use the pre-record policies when
554 they are invoked. If the function or macro implementation sets poli‐
555 cies, the changes automatically propagate up through callers until they
556 reach the closest nested policy stack entry.
557 configure_file
559 Copy a file to another location and modify its contents.
560 configure_file(<input> <output>
562 [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
563 [NO_SOURCE_PERMISSIONS]
564 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
565 Copies an <input> file to an <output> file and substitutes variable
567 values referenced as @VAR@ or ${VAR} in the input file content. Each
568 variable reference will be replaced with the current value of the vari‐
569 able, or the empty string if the variable is not defined. Furthermore,
570 input lines of the form
571 #cmakedefine VAR ...
573 will be replaced with either
575 #define VAR ...
577 or
579 /* #undef VAR */
581 depending on whether VAR is set in CMake to any value not considered a
583 false constant by the if() command. The “…” content on the line after
584 the variable name, if any, is processed as above. Input file lines of
585 the form #cmakedefine01 VAR will be replaced with either #define VAR 1
586 or #define VAR 0 similarly. The result lines (with the exception of
587 the #undef comments) can be indented using spaces and/or tabs between
588 the # character and the cmakedefine or cmakedefine01 words. This white‐
589 space indentation will be preserved in the output lines:
590 # cmakedefine VAR
592 # cmakedefine01 VAR
593 will be replaced, if VAR is defined, with
595 # define VAR
597 # define VAR 1
598 If the input file is modified the build system will re-run CMake to
600 re-configure the file and generate the build system again. The gener‐
601 ated file is modified and its timestamp updated on subsequent cmake
602 runs only if its content is changed.
603 The arguments are:
605 <input>
607 Path to the input file. A relative path is treated with respect
608 to the value of CMAKE_CURRENT_SOURCE_DIR. The input path must
609 be a file, not a directory.
610 <output>
612 Path to the output file or directory. A relative path is
613 treated with respect to the value of CMAKE_CURRENT_BINARY_DIR.
614 If the path names an existing directory the output file is
615 placed in that directory with the same file name as the input
616 file.
617 COPYONLY
619 Copy the file without replacing any variable references or other
620 content. This option may not be used with NEWLINE_STYLE.
621 ESCAPE_QUOTES
623 Escape any substituted quotes with backslashes (C-style).
624 @ONLY Restrict variable replacement to references of the form @VAR@.
626 This is useful for configuring scripts that use ${VAR} syntax.
627 NO_SOURCE_PERMISSIONS
629 Does not transfer the file permissions of the original file to
630 the copy. The copied file permissions default to the standard
631 644 value (-rw-r–r–).
632 NEWLINE_STYLE <style>
634 Specify the newline style for the output file. Specify UNIX or
635 LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n new‐
636 lines. This option may not be used with COPYONLY.
637 Example
639 Consider a source tree containing a foo.h.in file:
640 #cmakedefine FOO_ENABLE
642 #cmakedefine FOO_STRING "@FOO_STRING@"
643 An adjacent CMakeLists.txt may use configure_file to configure the
645 header:
646 option(FOO_ENABLE "Enable Foo" ON)
648 if(FOO_ENABLE)
649 set(FOO_STRING "foo")
650 endif()
651 configure_file(foo.h.in foo.h @ONLY)
652 This creates a foo.h in the build directory corresponding to this
654 source directory. If the FOO_ENABLE option is on, the configured file
655 will contain:
656 #define FOO_ENABLE
658 #define FOO_STRING "foo"
659 Otherwise it will contain:
661 /* #undef FOO_ENABLE */
663 /* #undef FOO_STRING */
664 One may then use the include_directories() command to specify the out‐
666 put directory as an include directory:
667 include_directories(${CMAKE_CURRENT_BINARY_DIR})
669 so that sources may include the header as #include <foo.h>.
671 continue
673 New in version 3.2.
674 Continue to the top of enclosing foreach or while loop.
677 continue()
679 The continue command allows a cmake script to abort the rest of a block
681 in a foreach() or while() loop, and start at the top of the next itera‐
682 tion.
683 See also the break() command.
685 else
687 Starts the else portion of an if block.
688 else([<condition>])
690 See the if() command.
692 elseif
694 Starts an elseif portion of an if block.
695 elseif(<condition>)
697 See the if() command, especially for the syntax and logic of the <con‐
699 dition>.
700 endforeach
702 Ends a list of commands in a foreach block.
703 endforeach([<loop_var>])
705 See the foreach() command.
707 The optional <loop_var> argument is supported for backward compatibil‐
709 ity only. If used it must be a verbatim repeat of the <loop_var> argu‐
710 ment of the opening foreach clause.
711 endfunction
713 Ends a list of commands in a function block.
714 endfunction([<name>])
716 See the function() command.
718 The optional <name> argument is supported for backward compatibility
720 only. If used it must be a verbatim repeat of the <name> argument of
721 the opening function command.
722 endif
724 Ends a list of commands in an if block.
725 endif([<condition>])
727 See the if() command.
729 The optional <condition> argument is supported for backward compatibil‐
731 ity only. If used it must be a verbatim repeat of the argument of the
732 opening if clause.
733 endmacro
735 Ends a list of commands in a macro block.
736 endmacro([<name>])
738 See the macro() command.
740 The optional <name> argument is supported for backward compatibility
742 only. If used it must be a verbatim repeat of the <name> argument of
743 the opening macro command.
744 endwhile
746 Ends a list of commands in a while block.
747 endwhile([<condition>])
749 See the while() command.
751 The optional <condition> argument is supported for backward compatibil‐
753 ity only. If used it must be a verbatim repeat of the argument of the
754 opening while clause.
755 execute_process
757 Execute one or more child processes.
758 execute_process(COMMAND <cmd1> [<arguments>]
760 [COMMAND <cmd2> [<arguments>]]...
761 [WORKING_DIRECTORY <directory>]
762 [TIMEOUT <seconds>]
763 [RESULT_VARIABLE <variable>]
764 [RESULTS_VARIABLE <variable>]
765 [OUTPUT_VARIABLE <variable>]
766 [ERROR_VARIABLE <variable>]
767 [INPUT_FILE <file>]
768 [OUTPUT_FILE <file>]
769 [ERROR_FILE <file>]
770 [OUTPUT_QUIET]
771 [ERROR_QUIET]
772 [COMMAND_ECHO <where>]
773 [OUTPUT_STRIP_TRAILING_WHITESPACE]
774 [ERROR_STRIP_TRAILING_WHITESPACE]
775 [ENCODING <name>]
776 [ECHO_OUTPUT_VARIABLE]
777 [ECHO_ERROR_VARIABLE]
778 [COMMAND_ERROR_IS_FATAL <ANY|LAST>])
779 Runs the given sequence of one or more commands.
781 Commands are executed concurrently as a pipeline, with the standard
783 output of each process piped to the standard input of the next. A sin‐
784 gle standard error pipe is used for all processes.
785 Options:
787 COMMAND
789 A child process command line.
790 CMake executes the child process using operating system APIs
792 directly. All arguments are passed VERBATIM to the child
793 process. No intermediate shell is used, so shell operators such
794 as > are treated as normal arguments. (Use the INPUT_*, OUT‐
795 PUT_*, and ERROR_* options to redirect stdin, stdout, and
796 stderr.)
797 If a sequential execution of multiple commands is required, use
799 multiple execute_process() calls with a single COMMAND argument.
800 WORKING_DIRECTORY
802 The named directory will be set as the current working directory
803 of the child processes.
804 TIMEOUT
806 After the specified number of seconds (fractions allowed), all
807 unfinished child processes will be terminated, and the
808 RESULT_VARIABLE will be set to a string mentioning the “time‐
809 out”.
810 RESULT_VARIABLE
812 The variable will be set to contain the result of last child
813 process. This will be an integer return code from the last
814 child or a string describing an error condition.
815 RESULTS_VARIABLE <variable>
817 The variable will be set to contain the result of all processes
818 as a semicolon-separated list, in order of the given COMMAND
819 arguments. Each entry will be an integer return code from the
820 corresponding child or a string describing an error condition.
821 OUTPUT_VARIABLE, ERROR_VARIABLE
823 The variable named will be set with the contents of the standard
824 output and standard error pipes, respectively. If the same
825 variable is named for both pipes their output will be merged in
826 the order produced.
827 INPUT_FILE, OUTPUT_FILE, ERROR_FILE
829 The file named will be attached to the standard input of the
830 first process, standard output of the last process, or standard
831 error of all processes, respectively. If the same file is named
832 for both output and error then it will be used for both.
833 OUTPUT_QUIET, ERROR_QUIET
835 The standard output or standard error results will be quietly
836 ignored.
837 COMMAND_ECHO <where>
839 The command being run will be echo’ed to <where> with <where>
840 being set to one of STDERR, STDOUT or NONE. See the CMAKE_EXE‐
841 CUTE_PROCESS_COMMAND_ECHO variable for a way to control the
842 default behavior when this option is not present.
843 ENCODING <name>
845 On Windows, the encoding that is used to decode output from the
846 process. Ignored on other platforms. Valid encoding names are:
847 NONE Perform no decoding. This assumes that the process out‐
849 put is encoded in the same way as CMake’s internal encod‐
850 ing (UTF-8). This is the default.
851 AUTO Use the current active console’s codepage or if that
853 isn’t available then use ANSI.
854 ANSI Use the ANSI codepage.
856 OEM Use the original equipment manufacturer (OEM) code page.
858 UTF8 or UTF-8
860 Use the UTF-8 codepage. Prior to CMake 3.11.0, only UTF8
861 was accepted for this encoding. In CMake 3.11.0, UTF-8
862 was added for consistency with the UTF-8 RFC naming con‐
863 vention.
864 ECHO_OUTPUT_VARIABLE, ECHO_ERROR_VARIABLE
866 The standard output or standard error will not be exclusively
867 redirected to the configured variables.
868 The output will be duplicated, it will be sent into the config‐
870 ured variables and also on standard output or standard error.
871 This is analogous to the tee Unix command.
873 COMMAND_ERROR_IS_FATAL <ANY|LAST>
875 The option following COMMAND_ERROR_IS_FATAL determines the
876 behavior when an error is encountered:
877 ANY If any of the commands in the list of commands fail, the
878 execute_process() command halts with an error.
879 LAST If the last command in the list of commands fails, the
881 execute_process() command halts with an error. Commands ear‐
882 lier in the list will not cause a fatal error.
883 If more than one OUTPUT_* or ERROR_* option is given for the same pipe
885 the precedence is not specified. If no OUTPUT_* or ERROR_* options are
886 given the output will be shared with the corresponding pipes of the
887 CMake process itself.
888 The execute_process() command is a newer more powerful version of
890 exec_program(), but the old command has been kept for compatibility.
891 Both commands run while CMake is processing the project prior to build
892 system generation. Use add_custom_target() and add_custom_command() to
893 create custom commands that run at build time.
894 file
896 File manipulation command.
897 Synopsis
899 Reading
900 file(READ <filename> <out-var> [...])
901 file(STRINGS <filename> <out-var> [...])
902 file(<HASH> <filename> <out-var>)
903 file(TIMESTAMP <filename> <out-var> [...])
904 file(GET_RUNTIME_DEPENDENCIES [...])
905 Writing
907 file({WRITE | APPEND} <filename> <content>...)
908 file({TOUCH | TOUCH_NOCREATE} [<file>...])
909 file(GENERATE OUTPUT <output-file> [...])
910 file(CONFIGURE OUTPUT <output-file> CONTENT <content> [...])
911 Filesystem
913 file({GLOB | GLOB_RECURSE} <out-var> [...] [<globbing-expr>...])
914 file(RENAME <oldname> <newname>)
915 file({REMOVE | REMOVE_RECURSE } [<files>...])
916 file(MAKE_DIRECTORY [<dir>...])
917 file({COPY | INSTALL} <file>... DESTINATION <dir> [...])
918 file(SIZE <filename> <out-var>)
919 file(READ_SYMLINK <linkname> <out-var>)
920 file(CREATE_LINK <original> <linkname> [...])
921 file(CHMOD <files>... <directories>... PERMISSIONS <permissions>... [...])
922 file(CHMOD_RECURSE <files>... <directories>... PERMISSIONS <permissions>... [...])
923 Path Conversion
925 file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>])
926 file(RELATIVE_PATH <out-var> <directory> <file>)
927 file({TO_CMAKE_PATH | TO_NATIVE_PATH} <path> <out-var>)
928 Transfer
930 file(DOWNLOAD <url> [<file>] [...])
931 file(UPLOAD <file> <url> [...])
932 Locking
934 file(LOCK <path> [...])
935 Archiving
937 file(ARCHIVE_CREATE OUTPUT <archive> PATHS <paths>... [...])
938 file(ARCHIVE_EXTRACT INPUT <archive> [...])
939 Reading
941 file(READ <filename> <variable>
942 [OFFSET <offset>] [LIMIT <max-in>] [HEX])
943 Read content from a file called <filename> and store it in a <vari‐
945 able>. Optionally start from the given <offset> and read at most
946 <max-in> bytes. The HEX option causes data to be converted to a hexa‐
947 decimal representation (useful for binary data). If the HEX option is
948 specified, letters in the output (a through f) are in lowercase.
949 file(STRINGS <filename> <variable> [<options>...])
951 Parse a list of ASCII strings from <filename> and store it in <vari‐
953 able>. Binary data in the file are ignored. Carriage return (\r, CR)
954 characters are ignored. The options are:
955 LENGTH_MAXIMUM <max-len>
957 Consider only strings of at most a given length.
958 LENGTH_MINIMUM <min-len>
960 Consider only strings of at least a given length.
961 LIMIT_COUNT <max-num>
963 Limit the number of distinct strings to be extracted.
964 LIMIT_INPUT <max-in>
966 Limit the number of input bytes to read from the file.
967 LIMIT_OUTPUT <max-out>
969 Limit the number of total bytes to store in the <variable>.
970 NEWLINE_CONSUME
972 Treat newline characters (\n, LF) as part of string content
973 instead of terminating at them.
974 NO_HEX_CONVERSION
976 Intel Hex and Motorola S-record files are automatically con‐
977 verted to binary while reading unless this option is given.
978 REGEX <regex>
980 Consider only strings that match the given regular expression.
981 ENCODING <encoding-type>
983 Consider strings of a given encoding. Currently supported
984 encodings are: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE.
985 If the ENCODING option is not provided and the file has a Byte
986 Order Mark, the ENCODING option will be defaulted to respect the
987 Byte Order Mark.
988 For example, the code
990 file(STRINGS myfile.txt myfile)
992 stores a list in the variable myfile in which each item is a line from
994 the input file.
995 file(<HASH> <filename> <variable>)
997 Compute a cryptographic hash of the content of <filename> and store it
999 in a <variable>. The supported <HASH> algorithm names are those listed
1000 by the string(<HASH>) command.
1001 file(TIMESTAMP <filename> <variable> [<format>] [UTC])
1003 Compute a string representation of the modification time of <filename>
1005 and store it in <variable>. Should the command be unable to obtain a
1006 timestamp variable will be set to the empty string (“”).
1007 See the string(TIMESTAMP) command for documentation of the <format> and
1009 UTC options.
1010 file(GET_RUNTIME_DEPENDENCIES
1012 [RESOLVED_DEPENDENCIES_VAR <deps_var>]
1013 [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
1014 [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
1015 [EXECUTABLES [<executable_files>...]]
1016 [LIBRARIES [<library_files>...]]
1017 [MODULES [<module_files>...]]
1018 [DIRECTORIES [<directories>...]]
1019 [BUNDLE_EXECUTABLE <bundle_executable_file>]
1020 [PRE_INCLUDE_REGEXES [<regexes>...]]
1021 [PRE_EXCLUDE_REGEXES [<regexes>...]]
1022 [POST_INCLUDE_REGEXES [<regexes>...]]
1023 [POST_EXCLUDE_REGEXES [<regexes>...]]
1024 )
1025 Recursively get the list of libraries depended on by the given files.
1027 Please note that this sub-command is not intended to be used in project
1029 mode. Instead, use it in an install(CODE) or install(SCRIPT) block.
1030 For example:
1031 install(CODE [[
1033 file(GET_RUNTIME_DEPENDENCIES
1034 # ...
1035 )
1036 ]])
1037 The arguments are as follows:
1039 RESOLVED_DEPENDENCIES_VAR <deps_var>
1041 Name of the variable in which to store the list of resolved
1042 dependencies.
1043 UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>
1045 Name of the variable in which to store the list of unresolved
1046 dependencies. If this variable is not specified, and there are
1047 any unresolved dependencies, an error is issued.
1048 CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>
1050 Variable prefix in which to store conflicting dependency infor‐
1051 mation. Dependencies are conflicting if two files with the same
1052 name are found in two different directories. The list of file‐
1053 names that conflict are stored in <conflicting_deps_pre‐
1054 fix>_FILENAMES. For each filename, the list of paths that were
1055 found for that filename are stored in <conflicting_deps_pre‐
1056 fix>_<filename>.
1057 EXECUTABLES <executable_files>
1059 List of executable files to read for dependencies. These are
1060 executables that are typically created with add_executable(),
1061 but they do not have to be created by CMake. On Apple platforms,
1062 the paths to these files determine the value of @executable_path
1063 when recursively resolving the libraries. Specifying any kind
1064 of library (STATIC, MODULE, or SHARED) here will result in unde‐
1065 fined behavior.
1066 LIBRARIES <library_files>
1068 List of library files to read for dependencies. These are
1069 libraries that are typically created with add_library(SHARED),
1070 but they do not have to be created by CMake. Specifying STATIC
1071 libraries, MODULE libraries, or executables here will result in
1072 undefined behavior.
1073 MODULES <module_files>
1075 List of loadable module files to read for dependencies. These
1076 are modules that are typically created with add_library(MODULE),
1077 but they do not have to be created by CMake. They are typically
1078 used by calling dlopen() at runtime rather than linked at link
1079 time with ld -l. Specifying STATIC libraries, SHARED libraries,
1080 or executables here will result in undefined behavior.
1081 DIRECTORIES <directories>
1083 List of additional directories to search for dependencies. On
1084 Linux platforms, these directories are searched if the depen‐
1085 dency is not found in any of the other usual paths. If it is
1086 found in such a directory, a warning is issued, because it means
1087 that the file is incomplete (it does not list all of the direc‐
1088 tories that contain its dependencies). On Windows platforms,
1089 these directories are searched if the dependency is not found in
1090 any of the other search paths, but no warning is issued, because
1091 searching other paths is a normal part of Windows dependency
1092 resolution. On Apple platforms, this argument has no effect.
1093 BUNDLE_EXECUTABLE <bundle_executable_file>
1095 Executable to treat as the “bundle executable” when resolving
1096 libraries. On Apple platforms, this argument determines the
1097 value of @executable_path when recursively resolving libraries
1098 for LIBRARIES and MODULES files. It has no effect on EXECUTA‐
1099 BLES files. On other platforms, it has no effect. This is typi‐
1100 cally (but not always) one of the executables in the EXECUTABLES
1101 argument which designates the “main” executable of the package.
1102 The following arguments specify filters for including or excluding
1104 libraries to be resolved. See below for a full description of how they
1105 work.
1106 PRE_INCLUDE_REGEXES <regexes>
1108 List of pre-include regexes through which to filter the names of
1109 not-yet-resolved dependencies.
1110 PRE_EXCLUDE_REGEXES <regexes>
1112 List of pre-exclude regexes through which to filter the names of
1113 not-yet-resolved dependencies.
1114 POST_INCLUDE_REGEXES <regexes>
1116 List of post-include regexes through which to filter the names
1117 of resolved dependencies.
1118 POST_EXCLUDE_REGEXES <regexes>
1120 List of post-exclude regexes through which to filter the names
1121 of resolved dependencies.
1122 These arguments can be used to exclude unwanted system libraries when
1124 resolving the dependencies, or to include libraries from a specific
1125 directory. The filtering works as follows:
1126 1. If the not-yet-resolved dependency matches any of the
1128 PRE_INCLUDE_REGEXES, steps 2 and 3 are skipped, and the dependency
1129 resolution proceeds to step 4.
1130 2. If the not-yet-resolved dependency matches any of the
1132 PRE_EXCLUDE_REGEXES, dependency resolution stops for that depen‐
1133 dency.
1134 3. Otherwise, dependency resolution proceeds.
1136 4. file(GET_RUNTIME_DEPENDENCIES) searches for the dependency according
1138 to the linking rules of the platform (see below).
1139 5. If the dependency is found, and its full path matches one of the
1141 POST_INCLUDE_REGEXES, the full path is added to the resolved depen‐
1142 dencies, and file(GET_RUNTIME_DEPENDENCIES) recursively resolves
1143 that library’s own dependencies. Otherwise, resolution proceeds to
1144 step 6.
1145 6. If the dependency is found, but its full path matches one of the
1147 POST_EXCLUDE_REGEXES, it is not added to the resolved dependencies,
1148 and dependency resolution stops for that dependency.
1149 7. If the dependency is found, and its full path does not match either
1151 POST_INCLUDE_REGEXES or POST_EXCLUDE_REGEXES, the full path is added
1152 to the resolved dependencies, and file(GET_RUNTIME_DEPENDENCIES)
1153 recursively resolves that library’s own dependencies.
1154 Different platforms have different rules for how dependencies are
1156 resolved. These specifics are described here.
1157 On Linux platforms, library resolution works as follows:
1159 1. If the depending file does not have any RUNPATH entries, and the
1161 library exists in one of the depending file’s RPATH entries, or its
1162 parents’, in that order, the dependency is resolved to that file.
1163 2. Otherwise, if the depending file has any RUNPATH entries, and the
1165 library exists in one of those entries, the dependency is resolved
1166 to that file.
1167 3. Otherwise, if the library exists in one of the directories listed by
1169 ldconfig, the dependency is resolved to that file.
1170 4. Otherwise, if the library exists in one of the DIRECTORIES entries,
1172 the dependency is resolved to that file. In this case, a warning is
1173 issued, because finding a file in one of the DIRECTORIES means that
1174 the depending file is not complete (it does not list all the direc‐
1175 tories from which it pulls dependencies).
1176 5. Otherwise, the dependency is unresolved.
1178 On Windows platforms, library resolution works as follows:
1180 1. The dependent DLL name is converted to lowercase. Windows DLL names
1182 are case-insensitive, and some linkers mangle the case of the DLL
1183 dependency names. However, this makes it more difficult for
1184 PRE_INCLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, and
1185 POST_EXCLUDE_REGEXES to properly filter DLL names - every regex
1186 would have to check for both uppercase and lowercase letters. For
1187 example:
1188 file(GET_RUNTIME_DEPENDENCIES
1190 # ...
1191 PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
1192 )
1193 Converting the DLL name to lowercase allows the regexes to only
1195 match lowercase names, thus simplifying the regex. For example:
1196 file(GET_RUNTIME_DEPENDENCIES
1198 # ...
1199 PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
1200 )
1201 This regex will match mylibrary.dll regardless of how it is cased,
1203 either on disk or in the depending file. (For example, it will match
1204 mylibrary.dll, MyLibrary.dll, and MYLIBRARY.DLL.)
1205 Please note that the directory portion of any resolved DLLs retains
1207 its casing and is not converted to lowercase. Only the filename por‐
1208 tion is converted.
1209 2. (Not yet implemented) If the depending file is a Windows Store app,
1211 and the dependency is listed as a dependency in the application’s
1212 package manifest, the dependency is resolved to that file.
1213 3. Otherwise, if the library exists in the same directory as the
1215 depending file, the dependency is resolved to that file.
1216 4. Otherwise, if the library exists in either the operating system’s
1218 system32 directory or the Windows directory, in that order, the
1219 dependency is resolved to that file.
1220 5. Otherwise, if the library exists in one of the directories specified
1222 by DIRECTORIES, in the order they are listed, the dependency is
1223 resolved to that file. In this case, a warning is not issued,
1224 because searching other directories is a normal part of Windows
1225 library resolution.
1226 6. Otherwise, the dependency is unresolved.
1228 On Apple platforms, library resolution works as follows:
1230 1. If the dependency starts with @executable_path/, and an EXECUTABLES
1232 argument is in the process of being resolved, and replacing @exe‐
1233 cutable_path/ with the directory of the executable yields an exist‐
1234 ing file, the dependency is resolved to that file.
1235 2. Otherwise, if the dependency starts with @executable_path/, and
1237 there is a BUNDLE_EXECUTABLE argument, and replacing @exe‐
1238 cutable_path/ with the directory of the bundle executable yields an
1239 existing file, the dependency is resolved to that file.
1240 3. Otherwise, if the dependency starts with @loader_path/, and replac‐
1242 ing @loader_path/ with the directory of the depending file yields an
1243 existing file, the dependency is resolved to that file.
1244 4. Otherwise, if the dependency starts with @rpath/, and replacing
1246 @rpath/ with one of the RPATH entries of the depending file yields
1247 an existing file, the dependency is resolved to that file. Note that
1248 RPATH entries that start with @executable_path/ or @loader_path/
1249 also have these items replaced with the appropriate path.
1250 5. Otherwise, if the dependency is an absolute file that exists, the
1252 dependency is resolved to that file.
1253 6. Otherwise, the dependency is unresolved.
1255 This function accepts several variables that determine which tool is
1257 used for dependency resolution:
1258 CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM
1260 Determines which operating system and executable format the
1261 files are built for. This could be one of several values:
1262 · linux+elf
1264 · windows+pe
1266 · macos+macho
1268 If this variable is not specified, it is determined automati‐
1270 cally by system introspection.
1271 CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
1273 Determines the tool to use for dependency resolution. It could
1274 be one of several values, depending on the value of
1275 CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM:
1276 ┌─────────────────────────┬──────────────────────────┐
1278 │CMAKE_GET_RUNTIME_DEPEN‐ │ CMAKE_GET_RUNTIME_DEPEN‐ │
1279 │DENCIES_PLATFORM │ DENCIES_TOOL │
1280 ├─────────────────────────┼──────────────────────────┤
1281 │linux+elf │ objdump │
1282 ├─────────────────────────┼──────────────────────────┤
1283 │windows+pe │ dumpbin │
1284 ├─────────────────────────┼──────────────────────────┤
1285 │windows+pe │ objdump │
1286 ├─────────────────────────┼──────────────────────────┤
1287 │macos+macho │ otool │
1288 └─────────────────────────┴──────────────────────────┘
1289 If this variable is not specified, it is determined automati‐
1291 cally by system introspection.
1292 CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND
1294 Determines the path to the tool to use for dependency resolu‐
1295 tion. This is the actual path to objdump, dumpbin, or otool.
1296 If this variable is not specified, it is determined by the value
1298 of CMAKE_OBJDUMP if set, else by system introspection.
1299 Writing
1301 file(WRITE <filename> <content>...)
1302 file(APPEND <filename> <content>...)
1303 Write <content> into a file called <filename>. If the file does not
1305 exist, it will be created. If the file already exists, WRITE mode will
1306 overwrite it and APPEND mode will append to the end. Any directories
1307 in the path specified by <filename> that do not exist will be created.
1308 If the file is a build input, use the configure_file() command to
1310 update the file only when its content changes.
1311 file(TOUCH [<files>...])
1313 file(TOUCH_NOCREATE [<files>...])
1314 Create a file with no content if it does not yet exist. If the file
1316 already exists, its access and/or modification will be updated to the
1317 time when the function call is executed.
1318 Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a
1320 file does not exist it will be silently ignored.
1321 With TOUCH and TOUCH_NOCREATE the contents of an existing file will not
1323 be modified.
1324 file(GENERATE OUTPUT output-file
1326 <INPUT input-file|CONTENT content>
1327 [CONDITION expression] [TARGET target])
1328 Generate an output file for each build configuration supported by the
1330 current CMake Generator. Evaluate generator expressions from the input
1331 content to produce the output content. The options are:
1332 CONDITION <condition>
1334 Generate the output file for a particular configuration only if
1335 the condition is true. The condition must be either 0 or 1
1336 after evaluating generator expressions.
1337 CONTENT <content>
1339 Use the content given explicitly as input.
1340 INPUT <input-file>
1342 Use the content from a given file as input. A relative path is
1343 treated with respect to the value of CMAKE_CURRENT_SOURCE_DIR.
1344 See policy CMP0070.
1345 OUTPUT <output-file>
1347 Specify the output file name to generate. Use generator expres‐
1348 sions such as $<CONFIG> to specify a configuration-specific out‐
1349 put file name. Multiple configurations may generate the same
1350 output file only if the generated content is identical. Other‐
1351 wise, the <output-file> must evaluate to an unique name for each
1352 configuration. A relative path (after evaluating generator
1353 expressions) is treated with respect to the value of CMAKE_CUR‐
1354 RENT_BINARY_DIR. See policy CMP0070.
1355 TARGET <target>
1357 Specify which target to use when evaluating generator expres‐
1358 sions that require a target for evaluation (e.g. $<COMPILE_FEA‐
1359 TURES:...>, $<TARGET_PROPERTY:prop>).
1360 Exactly one CONTENT or INPUT option must be given. A specific OUTPUT
1362 file may be named by at most one invocation of file(GENERATE). Gener‐
1363 ated files are modified and their timestamp updated on subsequent cmake
1364 runs only if their content is changed.
1365 Note also that file(GENERATE) does not create the output file until the
1367 generation phase. The output file will not yet have been written when
1368 the file(GENERATE) command returns, it is written only after processing
1369 all of a project’s CMakeLists.txt files.
1370 file(CONFIGURE OUTPUT output-file
1372 CONTENT content
1373 [ESCAPE_QUOTES] [@ONLY]
1374 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
1375 Generate an output file using the input given by CONTENT and substitute
1377 variable values referenced as @VAR@ or ${VAR} contained therein. The
1378 substitution rules behave the same as the configure_file() command. In
1379 order to match configure_file()’s behavior, generator expressions are
1380 not supported for both OUTPUT and CONTENT.
1381 The arguments are:
1383 OUTPUT <output-file>
1385 Specify the output file name to generate. A relative path is
1386 treated with respect to the value of CMAKE_CURRENT_BINARY_DIR.
1387 <output-file> does not support generator expressions.
1388 CONTENT <content>
1390 Use the content given explicitly as input. <content> does not
1391 support generator expressions.
1392 ESCAPE_QUOTES
1394 Escape any substituted quotes with backslashes (C-style).
1395 @ONLY Restrict variable replacement to references of the form @VAR@.
1397 This is useful for configuring scripts that use ${VAR} syntax.
1398 NEWLINE_STYLE <style>
1400 Specify the newline style for the output file. Specify UNIX or
1401 LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n new‐
1402 lines.
1403 Filesystem
1405 file(GLOB <variable>
1406 [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
1407 [<globbing-expressions>...])
1408 file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
1409 [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
1410 [<globbing-expressions>...])
1411 Generate a list of files that match the <globbing-expressions> and
1413 store it into the <variable>. Globbing expressions are similar to reg‐
1414 ular expressions, but much simpler. If RELATIVE flag is specified, the
1415 results will be returned as relative paths to the given path. The
1416 results will be ordered lexicographically.
1417 On Windows and macOS, globbing is case-insensitive even if the underly‐
1419 ing filesystem is case-sensitive (both filenames and globbing expres‐
1420 sions are converted to lowercase before matching). On other platforms,
1421 globbing is case-sensitive.
1422 If the CONFIGURE_DEPENDS flag is specified, CMake will add logic to the
1424 main build system check target to rerun the flagged GLOB commands at
1425 build time. If any of the outputs change, CMake will regenerate the
1426 build system.
1427 By default GLOB lists directories - directories are omitted in result
1429 if LIST_DIRECTORIES is set to false.
1430 NOTE:
1432 We do not recommend using GLOB to collect a list of source files
1433 from your source tree. If no CMakeLists.txt file changes when a
1434 source is added or removed then the generated build system cannot
1435 know when to ask CMake to regenerate. The CONFIGURE_DEPENDS flag
1436 may not work reliably on all generators, or if a new generator is
1437 added in the future that cannot support it, projects using it will
1438 be stuck. Even if CONFIGURE_DEPENDS works reliably, there is still a
1439 cost to perform the check on every rebuild.
1440 Examples of globbing expressions include:
1442 *.cxx - match all files with extension cxx
1444 *.vt? - match all files with extension vta,...,vtz
1445 f[3-5].txt - match files f3.txt, f4.txt, f5.txt
1446 The GLOB_RECURSE mode will traverse all the subdirectories of the
1448 matched directory and match the files. Subdirectories that are sym‐
1449 links are only traversed if FOLLOW_SYMLINKS is given or policy CMP0009
1450 is not set to NEW.
1451 By default GLOB_RECURSE omits directories from result list - setting
1453 LIST_DIRECTORIES to true adds directories to result list. If FOL‐
1454 LOW_SYMLINKS is given or policy CMP0009 is not set to NEW then
1455 LIST_DIRECTORIES treats symlinks as directories.
1456 Examples of recursive globbing include:
1458 /dir/*.py - match all python files in /dir and subdirectories
1460 file(RENAME <oldname> <newname>)
1462 Move a file or directory within a filesystem from <oldname> to <new‐
1464 name>, replacing the destination atomically.
1465 file(REMOVE [<files>...])
1467 file(REMOVE_RECURSE [<files>...])
1468 Remove the given files. The REMOVE_RECURSE mode will remove the given
1470 files and directories, also non-empty directories. No error is emitted
1471 if a given file does not exist. Relative input paths are evaluated
1472 with respect to the current source directory. Empty input paths are
1473 ignored with a warning.
1474 file(MAKE_DIRECTORY [<directories>...])
1476 Create the given directories and their parents as needed.
1478 file(<COPY|INSTALL> <files>... DESTINATION <dir>
1480 [FILE_PERMISSIONS <permissions>...]
1481 [DIRECTORY_PERMISSIONS <permissions>...]
1482 [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
1483 [FOLLOW_SYMLINK_CHAIN]
1484 [FILES_MATCHING]
1485 [[PATTERN <pattern> | REGEX <regex>]
1486 [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
1487 The COPY signature copies files, directories, and symlinks to a desti‐
1489 nation folder. Relative input paths are evaluated with respect to the
1490 current source directory, and a relative destination is evaluated with
1491 respect to the current build directory. Copying preserves input file
1492 timestamps, and optimizes out a file if it exists at the destination
1493 with the same timestamp. Copying preserves input permissions unless
1494 explicit permissions or NO_SOURCE_PERMISSIONS are given (default is
1495 USE_SOURCE_PERMISSIONS).
1496 If FOLLOW_SYMLINK_CHAIN is specified, COPY will recursively resolve the
1498 symlinks at the paths given until a real file is found, and install a
1499 corresponding symlink in the destination for each symlink encountered.
1500 For each symlink that is installed, the resolution is stripped of the
1501 directory, leaving only the filename, meaning that the new symlink
1502 points to a file in the same directory as the symlink. This feature is
1503 useful on some Unix systems, where libraries are installed as a chain
1504 of symlinks with version numbers, with less specific versions pointing
1505 to more specific versions. FOLLOW_SYMLINK_CHAIN will install all of
1506 these symlinks and the library itself into the destination directory.
1507 For example, if you have the following directory structure:
1508 · /opt/foo/lib/libfoo.so.1.2.3
1510 · /opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3
1512 · /opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2
1514 · /opt/foo/lib/libfoo.so -> libfoo.so.1
1516 and you do:
1518 file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)
1520 This will install all of the symlinks and libfoo.so.1.2.3 itself into
1522 lib.
1523 See the install(DIRECTORY) command for documentation of permissions,
1525 FILES_MATCHING, PATTERN, REGEX, and EXCLUDE options. Copying directo‐
1526 ries preserves the structure of their content even if options are used
1527 to select a subset of files.
1528 The INSTALL signature differs slightly from COPY: it prints status mes‐
1530 sages (subject to the CMAKE_INSTALL_MESSAGE variable), and
1531 NO_SOURCE_PERMISSIONS is default. Installation scripts generated by
1532 the install() command use this signature (with some undocumented
1533 options for internal use).
1534 file(SIZE <filename> <variable>)
1536 Determine the file size of the <filename> and put the result in <vari‐
1538 able> variable. Requires that <filename> is a valid path pointing to a
1539 file and is readable.
1540 file(READ_SYMLINK <linkname> <variable>)
1542 This subcommand queries the symlink <linkname> and stores the path it
1544 points to in the result <variable>. If <linkname> does not exist or is
1545 not a symlink, CMake issues a fatal error.
1546 Note that this command returns the raw symlink path and does not
1548 resolve a relative path. The following is an example of how to ensure
1549 that an absolute path is obtained:
1550 set(linkname "/path/to/foo.sym")
1552 file(READ_SYMLINK "${linkname}" result)
1553 if(NOT IS_ABSOLUTE "${result}")
1554 get_filename_component(dir "${linkname}" DIRECTORY)
1555 set(result "${dir}/${result}")
1556 endif()
1557 file(CREATE_LINK <original> <linkname>
1559 [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])
1560 Create a link <linkname> that points to <original>. It will be a hard
1562 link by default, but providing the SYMBOLIC option results in a sym‐
1563 bolic link instead. Hard links require that original exists and is a
1564 file, not a directory. If <linkname> already exists, it will be over‐
1565 written.
1566 The <result> variable, if specified, receives the status of the opera‐
1568 tion. It is set to 0 upon success or an error message otherwise. If
1569 RESULT is not specified and the operation fails, a fatal error is emit‐
1570 ted.
1571 Specifying COPY_ON_ERROR enables copying the file as a fallback if cre‐
1573 ating the link fails. It can be useful for handling situations such as
1574 <original> and <linkname> being on different drives or mount points,
1575 which would make them unable to support a hard link.
1576 file(CHMOD <files>... <directories>...
1578 [PERMISSIONS <permissions>...]
1579 [FILE_PERMISSIONS <permissions>...]
1580 [DIRECTORY_PERMISSIONS <permissions>...])
1581 Set the permissions for the <files>... and <directories>... specified.
1583 Valid permissions are OWNER_READ, OWNER_WRITE, OWNER_EXECUTE,
1584 GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE,
1585 WORLD_EXECUTE.
1586 Valid combination of keywords are:
1588 PERMISSIONS
1590 All items are changed.
1591 FILE_PERMISSIONS
1593 Only files are changed.
1594 DIRECTORY_PERMISSIONS
1596 Only directories are changed.
1597 PERMISSIONS and FILE_PERMISSIONS
1599 FILE_PERMISSIONS overrides PERMISSIONS for files.
1600 PERMISSIONS and DIRECTORY_PERMISSIONS
1602 DIRECTORY_PERMISSIONS overrides PERMISSIONS for directories.
1603 FILE_PERMISSIONS and DIRECTORY_PERMISSIONS
1605 Use FILE_PERMISSIONS for files and DIRECTORY_PERMISSIONS for
1606 directories.
1607 file(CHMOD_RECURSE <files>... <directories>...
1609 [PERMISSIONS <permissions>...]
1610 [FILE_PERMISSIONS <permissions>...]
1611 [DIRECTORY_PERMISSIONS <permissions>...])
1612 Same as CHMOD, but change the permissions of files and directories
1614 present in the <directories>... recursively.
1615 Path Conversion
1617 file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>])
1618 Compute the absolute path to an existing file or directory with sym‐
1620 links resolved.
1621 If the provided <path> is a relative path, it is evaluated relative to
1623 the given base directory <dir>. If no base directory is provided, the
1624 default base directory will be CMAKE_CURRENT_SOURCE_DIR.
1625 file(RELATIVE_PATH <variable> <directory> <file>)
1627 Compute the relative path from a <directory> to a <file> and store it
1629 in the <variable>.
1630 file(TO_CMAKE_PATH "<path>" <variable>)
1632 file(TO_NATIVE_PATH "<path>" <variable>)
1633 The TO_CMAKE_PATH mode converts a native <path> into a cmake-style path
1635 with forward-slashes (/). The input can be a single path or a system
1636 search path like $ENV{PATH}. A search path will be converted to a
1637 cmake-style list separated by ; characters.
1638 The TO_NATIVE_PATH mode converts a cmake-style <path> into a native
1640 path with platform-specific slashes (\ on Windows and / elsewhere).
1641 Always use double quotes around the <path> to be sure it is treated as
1643 a single argument to this command.
1644 Transfer
1646 file(DOWNLOAD <url> [<file>] [<options>...])
1647 file(UPLOAD <file> <url> [<options>...])
1648 The DOWNLOAD subcommand downloads the given <url> to a local <file>.
1650 If <file> is not specified for file(DOWNLOAD), the file is not saved.
1651 This can be useful if you want to know if a file can be downloaded (for
1652 example, to check that it exists) without actually saving it anywhere.
1653 The UPLOAD mode uploads a local <file> to a given <url>.
1654 Options to both DOWNLOAD and UPLOAD are:
1656 INACTIVITY_TIMEOUT <seconds>
1658 Terminate the operation after a period of inactivity.
1659 LOG <variable>
1661 Store a human-readable log of the operation in a variable.
1662 SHOW_PROGRESS
1664 Print progress information as status messages until the opera‐
1665 tion is complete.
1666 STATUS <variable>
1668 Store the resulting status of the operation in a variable. The
1669 status is a ; separated list of length 2. The first element is
1670 the numeric return value for the operation, and the second ele‐
1671 ment is a string value for the error. A 0 numeric error means
1672 no error in the operation.
1673 TIMEOUT <seconds>
1675 Terminate the operation after a given total time has elapsed.
1676 USERPWD <username>:<password>
1678 Set username and password for operation.
1679 HTTPHEADER <HTTP-header>
1681 HTTP header for operation. Suboption can be repeated several
1682 times.
1683 NETRC <level>
1685 Specify whether the .netrc file is to be used for operation. If
1686 this option is not specified, the value of the CMAKE_NETRC vari‐
1687 able will be used instead. Valid levels are:
1688 IGNORED
1690 The .netrc file is ignored. This is the default.
1691 OPTIONAL
1693 The .netrc file is optional, and information in the URL
1694 is preferred. The file will be scanned to find which
1695 ever information is not specified in the URL.
1696 REQUIRED
1698 The .netrc file is required, and information in the URL
1699 is ignored.
1700 NETRC_FILE <file>
1702 Specify an alternative .netrc file to the one in your home
1703 directory, if the NETRC level is OPTIONAL or REQUIRED. If this
1704 option is not specified, the value of the CMAKE_NETRC_FILE vari‐
1705 able will be used instead.
1706 If neither NETRC option is given CMake will check variables CMAKE_NETRC
1708 and CMAKE_NETRC_FILE, respectively.
1709 TLS_VERIFY <ON|OFF>
1711 Specify whether to verify the server certificate for https://
1712 URLs. The default is to not verify.
1713 TLS_CAINFO <file>
1715 Specify a custom Certificate Authority file for https:// URLs.
1716 For https:// URLs CMake must be built with OpenSSL support. TLS/SSL
1718 certificates are not checked by default. Set TLS_VERIFY to ON to check
1719 certificates. If neither TLS option is given CMake will check variables
1720 CMAKE_TLS_VERIFY and CMAKE_TLS_CAINFO, respectively.
1721 Additional options to DOWNLOAD are:
1723 EXPECTED_HASH ALGO=<value>
1725 Verify that the downloaded content hash matches the expected value,
1726 where ALGO is one of the algorithms supported by file(<HASH>). If
1727 it does not match, the operation fails with an error. It is an error
1728 to specify this if DOWNLOAD is not given a <file>.
1729 EXPECTED_MD5 <value>
1731 Historical short-hand for EXPECTED_HASH MD5=<value>. It is an
1732 error to specify this if DOWNLOAD is not given a <file>.
1733 Locking
1735 file(LOCK <path> [DIRECTORY] [RELEASE]
1736 [GUARD <FUNCTION|FILE|PROCESS>]
1737 [RESULT_VARIABLE <variable>]
1738 [TIMEOUT <seconds>])
1739 Lock a file specified by <path> if no DIRECTORY option present and file
1741 <path>/cmake.lock otherwise. File will be locked for scope defined by
1742 GUARD option (default value is PROCESS). RELEASE option can be used to
1743 unlock file explicitly. If option TIMEOUT is not specified CMake will
1744 wait until lock succeed or until fatal error occurs. If TIMEOUT is set
1745 to 0 lock will be tried once and result will be reported immediately.
1746 If TIMEOUT is not 0 CMake will try to lock file for the period speci‐
1747 fied by <seconds> value. Any errors will be interpreted as fatal if
1748 there is no RESULT_VARIABLE option. Otherwise result will be stored in
1749 <variable> and will be 0 on success or error message on failure.
1750 Note that lock is advisory - there is no guarantee that other processes
1752 will respect this lock, i.e. lock synchronize two or more CMake
1753 instances sharing some modifiable resources. Similar logic applied to
1754 DIRECTORY option - locking parent directory doesn’t prevent other LOCK
1755 commands to lock any child directory or file.
1756 Trying to lock file twice is not allowed. Any intermediate directories
1758 and file itself will be created if they not exist. GUARD and TIMEOUT
1759 options ignored on RELEASE operation.
1760 Archiving
1762 file(ARCHIVE_CREATE OUTPUT <archive>
1763 PATHS <paths>...
1764 [FORMAT <format>]
1765 [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]]
1766 [MTIME <mtime>]
1767 [VERBOSE])
1768 Creates the specified <archive> file with the files and directories
1770 listed in <paths>. Note that <paths> must list actual files or direc‐
1771 tories, wildcards are not supported.
1772 Use the FORMAT option to specify the archive format. Supported values
1774 for <format> are 7zip, gnutar, pax, paxr, raw and zip. If FORMAT is
1775 not given, the default format is paxr.
1776 Some archive formats allow the type of compression to be specified.
1778 The 7zip and zip archive formats already imply a specific type of com‐
1779 pression. The other formats use no compression by default, but can be
1780 directed to do so with the COMPRESSION option. Valid values for <com‐
1781 pression> are None, BZip2, GZip, XZ, and Zstd.
1782 The compression level can be specified with the COMPRESSION_LEVEL
1784 option. The <compression-level> should be between 0-9, with the
1785 default being 0. The COMPRESSION option must be present when COMPRES‐
1786 SION_LEVEL is given.
1787 NOTE:
1789 With FORMAT set to raw only one file will be compressed with the
1790 compression type specified by COMPRESSION.
1791 The VERBOSE option enables verbose output for the archive operation.
1793 To specify the modification time recorded in tarball entries, use the
1795 MTIME option.
1796 file(ARCHIVE_EXTRACT INPUT <archive>
1798 [DESTINATION <dir>]
1799 [PATTERNS <patterns>...]
1800 [LIST_ONLY]
1801 [VERBOSE])
1802 Extracts or lists the content of the specified <archive>.
1804 The directory where the content of the archive will be extracted to can
1806 be specified using the DESTINATION option. If the directory does not
1807 exist, it will be created. If DESTINATION is not given, the current
1808 binary directory will be used.
1809 If required, you may select which files and directories to list or
1811 extract from the archive using the specified <patterns>. Wildcards are
1812 supported. If the PATTERNS option is not given, the entire archive
1813 will be listed or extracted.
1814 LIST_ONLY will list the files in the archive rather than extract them.
1816 With VERBOSE, the command will produce verbose output.
1818 find_file
1820 A short-hand signature is:
1821 find_file (<VAR> name1 [path1 path2 ...])
1823 The general signature is:
1825 find_file (
1827 <VAR>
1828 name | NAMES name1 [name2 ...]
1829 [HINTS path1 [path2 ... ENV var]]
1830 [PATHS path1 [path2 ... ENV var]]
1831 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1832 [DOC "cache documentation string"]
1833 [REQUIRED]
1834 [NO_DEFAULT_PATH]
1835 [NO_PACKAGE_ROOT_PATH]
1836 [NO_CMAKE_PATH]
1837 [NO_CMAKE_ENVIRONMENT_PATH]
1838 [NO_SYSTEM_ENVIRONMENT_PATH]
1839 [NO_CMAKE_SYSTEM_PATH]
1840 [CMAKE_FIND_ROOT_PATH_BOTH |
1841 ONLY_CMAKE_FIND_ROOT_PATH |
1842 NO_CMAKE_FIND_ROOT_PATH]
1843 )
1844 This command is used to find a full path to named file. A cache entry
1846 named by <VAR> is created to store the result of this command. If the
1847 full path to a file is found the result is stored in the variable and
1848 the search will not be repeated unless the variable is cleared. If
1849 nothing is found, the result will be <VAR>-NOTFOUND. The REQUIRED
1850 option stops processing with an error message if nothing is found, oth‐
1851 erwise the search will be attempted again the next time find_file is
1852 invoked with the same variable.
1853 Options include:
1855 NAMES Specify one or more possible names for the full path to a file.
1857 When using this to specify names with and without a version suf‐
1859 fix, we recommend specifying the unversioned name first so that
1860 locally-built packages can be found before those provided by
1861 distributions.
1862 HINTS, PATHS
1864 Specify directories to search in addition to the default loca‐
1865 tions. The ENV var sub-option reads paths from a system envi‐
1866 ronment variable.
1867 PATH_SUFFIXES
1869 Specify additional subdirectories to check below each directory
1870 location otherwise considered.
1871 DOC Specify the documentation string for the <VAR> cache entry.
1873 REQUIRED
1875 Stop processing with an error message if nothing is found.
1876 If NO_DEFAULT_PATH is specified, then no additional paths are added to
1878 the search. If NO_DEFAULT_PATH is not specified, the search process is
1879 as follows:
1880 1. If called from within a find module or any other script loaded by a
1882 call to find_package(<PackageName>), search prefixes unique to the
1883 current package being found. Specifically, look in the <Package‐
1884 Name>_ROOT CMake variable and the <PackageName>_ROOT environment
1885 variable. The package root variables are maintained as a stack, so
1886 if called from nested find modules or config packages, root paths
1887 from the parent’s find module or config package will be searched
1888 after paths from the current module or package. In other words, the
1889 search order would be <CurrentPackage>_ROOT, ENV{<CurrentPack‐
1890 age>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
1891 This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
1892 the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
1893 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1895 <prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
1896 variable and the <PackageName>_ROOT environment variable if called
1897 from within a find module loaded by find_package(<PackageName>)
1898 2. Search paths specified in cmake-specific cache variables. These are
1900 intended to be used on the command line with a -DVAR=value. The
1901 values are interpreted as semicolon-separated lists. This can be
1902 skipped if NO_CMAKE_PATH is passed or by setting the
1903 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
1904 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1906 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1907 · CMAKE_INCLUDE_PATH
1909 · CMAKE_FRAMEWORK_PATH
1911 3. Search paths specified in cmake-specific environment variables.
1913 These are intended to be set in the user’s shell configuration, and
1914 therefore use the host’s native path separator (; on Windows and :
1915 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1916 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
1917 FALSE.
1918 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1920 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1921 · CMAKE_INCLUDE_PATH
1923 · CMAKE_FRAMEWORK_PATH
1925 4. Search the paths specified by the HINTS option. These should be
1927 paths computed by system introspection, such as a hint provided by
1928 the location of another item already found. Hard-coded guesses
1929 should be specified with the PATHS option.
1930 5. Search the standard system environment variables. This can be
1932 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
1933 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
1934 · The directories in INCLUDE and PATH.
1936 · On Windows hosts: <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHI‐
1938 TECTURE is set, and <prefix>/include for each <prefix>/[s]bin in
1939 PATH, and <entry>/include for other entries in PATH.
1940 6. Search cmake variables defined in the Platform files for the current
1942 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
1943 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
1944 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1946 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1947 · CMAKE_SYSTEM_INCLUDE_PATH
1949 · CMAKE_SYSTEM_FRAMEWORK_PATH
1951 The platform paths that these variables contain are locations that
1953 typically include installed software. An example being /usr/local
1954 for UNIX based platforms.
1955 7. Search the paths specified by the PATHS option or in the short-hand
1957 version of the command. These are typically hard-coded guesses.
1958 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
1960 determine the order of preference between Apple-style and unix-style
1961 package components.
1962 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
1964 ries to be prepended to all other search directories. This effectively
1965 “re-roots” the entire search under given locations. Paths which are
1966 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
1967 ing, because that variable is always a path on the host system. By
1968 default the CMAKE_FIND_ROOT_PATH is empty.
1969 The CMAKE_SYSROOT variable can also be used to specify exactly one
1971 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
1972 effects. See the documentation for that variable for more.
1973 These variables are especially useful when cross-compiling to point to
1975 the root directory of the target environment and CMake will search
1976 there too. By default at first the directories listed in
1977 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
1978 searched, and then the non-rooted directories will be searched. The
1979 default behavior can be adjusted by setting
1980 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually over‐
1981 ridden on a per-call basis using options:
1982 CMAKE_FIND_ROOT_PATH_BOTH
1984 Search in the order described above.
1985 NO_CMAKE_FIND_ROOT_PATH
1987 Do not use the CMAKE_FIND_ROOT_PATH variable.
1988 ONLY_CMAKE_FIND_ROOT_PATH
1990 Search only the re-rooted directories and directories below
1991 CMAKE_STAGING_PREFIX.
1992 The default search order is designed to be most-specific to least-spe‐
1994 cific for common use cases. Projects may override the order by simply
1995 calling the command multiple times and using the NO_* options:
1996 find_file (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1998 find_file (<VAR> NAMES name)
1999 Once one of the calls succeeds the result variable will be set and
2001 stored in the cache so that no call will search again.
2002 find_library
2004 A short-hand signature is:
2005 find_library (<VAR> name1 [path1 path2 ...])
2007 The general signature is:
2009 find_library (
2011 <VAR>
2012 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
2013 [HINTS path1 [path2 ... ENV var]]
2014 [PATHS path1 [path2 ... ENV var]]
2015 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2016 [DOC "cache documentation string"]
2017 [REQUIRED]
2018 [NO_DEFAULT_PATH]
2019 [NO_PACKAGE_ROOT_PATH]
2020 [NO_CMAKE_PATH]
2021 [NO_CMAKE_ENVIRONMENT_PATH]
2022 [NO_SYSTEM_ENVIRONMENT_PATH]
2023 [NO_CMAKE_SYSTEM_PATH]
2024 [CMAKE_FIND_ROOT_PATH_BOTH |
2025 ONLY_CMAKE_FIND_ROOT_PATH |
2026 NO_CMAKE_FIND_ROOT_PATH]
2027 )
2028 This command is used to find a library. A cache entry named by <VAR>
2030 is created to store the result of this command. If the library is
2031 found the result is stored in the variable and the search will not be
2032 repeated unless the variable is cleared. If nothing is found, the
2033 result will be <VAR>-NOTFOUND. The REQUIRED option stops processing
2034 with an error message if nothing is found, otherwise the search will be
2035 attempted again the next time find_library is invoked with the same
2036 variable.
2037 Options include:
2039 NAMES Specify one or more possible names for the library.
2041 When using this to specify names with and without a version suf‐
2043 fix, we recommend specifying the unversioned name first so that
2044 locally-built packages can be found before those provided by
2045 distributions.
2046 HINTS, PATHS
2048 Specify directories to search in addition to the default loca‐
2049 tions. The ENV var sub-option reads paths from a system envi‐
2050 ronment variable.
2051 PATH_SUFFIXES
2053 Specify additional subdirectories to check below each directory
2054 location otherwise considered.
2055 DOC Specify the documentation string for the <VAR> cache entry.
2057 REQUIRED
2059 Stop processing with an error message if nothing is found.
2060 If NO_DEFAULT_PATH is specified, then no additional paths are added to
2062 the search. If NO_DEFAULT_PATH is not specified, the search process is
2063 as follows:
2064 1. If called from within a find module or any other script loaded by a
2066 call to find_package(<PackageName>), search prefixes unique to the
2067 current package being found. Specifically, look in the <Package‐
2068 Name>_ROOT CMake variable and the <PackageName>_ROOT environment
2069 variable. The package root variables are maintained as a stack, so
2070 if called from nested find modules or config packages, root paths
2071 from the parent’s find module or config package will be searched
2072 after paths from the current module or package. In other words, the
2073 search order would be <CurrentPackage>_ROOT, ENV{<CurrentPack‐
2074 age>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
2075 This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
2076 the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
2077 · <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2079 <prefix>/lib for each <prefix> in the <PackageName>_ROOT CMake
2080 variable and the <PackageName>_ROOT environment variable if called
2081 from within a find module loaded by find_package(<PackageName>)
2082 2. Search paths specified in cmake-specific cache variables. These are
2084 intended to be used on the command line with a -DVAR=value. The
2085 values are interpreted as semicolon-separated lists. This can be
2086 skipped if NO_CMAKE_PATH is passed or by setting the
2087 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
2088 · <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2090 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
2091 · CMAKE_LIBRARY_PATH
2093 · CMAKE_FRAMEWORK_PATH
2095 3. Search paths specified in cmake-specific environment variables.
2097 These are intended to be set in the user’s shell configuration, and
2098 therefore use the host’s native path separator (; on Windows and :
2099 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2100 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
2101 FALSE.
2102 · <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2104 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
2105 · CMAKE_LIBRARY_PATH
2107 · CMAKE_FRAMEWORK_PATH
2109 4. Search the paths specified by the HINTS option. These should be
2111 paths computed by system introspection, such as a hint provided by
2112 the location of another item already found. Hard-coded guesses
2113 should be specified with the PATHS option.
2114 5. Search the standard system environment variables. This can be
2116 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
2117 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
2118 · The directories in LIB and PATH.
2120 · On Windows hosts: <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITEC‐
2122 TURE is set, and <prefix>/lib for each <prefix>/[s]bin in PATH,
2123 and <entry>/lib for other entries in PATH.
2124 6. Search cmake variables defined in the Platform files for the current
2126 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
2127 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
2128 · <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2130 <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2131 · CMAKE_SYSTEM_LIBRARY_PATH
2133 · CMAKE_SYSTEM_FRAMEWORK_PATH
2135 The platform paths that these variables contain are locations that
2137 typically include installed software. An example being /usr/local
2138 for UNIX based platforms.
2139 7. Search the paths specified by the PATHS option or in the short-hand
2141 version of the command. These are typically hard-coded guesses.
2142 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
2144 determine the order of preference between Apple-style and unix-style
2145 package components.
2146 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
2148 ries to be prepended to all other search directories. This effectively
2149 “re-roots” the entire search under given locations. Paths which are
2150 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
2151 ing, because that variable is always a path on the host system. By
2152 default the CMAKE_FIND_ROOT_PATH is empty.
2153 The CMAKE_SYSROOT variable can also be used to specify exactly one
2155 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
2156 effects. See the documentation for that variable for more.
2157 These variables are especially useful when cross-compiling to point to
2159 the root directory of the target environment and CMake will search
2160 there too. By default at first the directories listed in
2161 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
2162 searched, and then the non-rooted directories will be searched. The
2163 default behavior can be adjusted by setting
2164 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY. This behavior can be manually over‐
2165 ridden on a per-call basis using options:
2166 CMAKE_FIND_ROOT_PATH_BOTH
2168 Search in the order described above.
2169 NO_CMAKE_FIND_ROOT_PATH
2171 Do not use the CMAKE_FIND_ROOT_PATH variable.
2172 ONLY_CMAKE_FIND_ROOT_PATH
2174 Search only the re-rooted directories and directories below
2175 CMAKE_STAGING_PREFIX.
2176 The default search order is designed to be most-specific to least-spe‐
2178 cific for common use cases. Projects may override the order by simply
2179 calling the command multiple times and using the NO_* options:
2180 find_library (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2182 find_library (<VAR> NAMES name)
2183 Once one of the calls succeeds the result variable will be set and
2185 stored in the cache so that no call will search again.
2186 When more than one value is given to the NAMES option this command by
2188 default will consider one name at a time and search every directory for
2189 it. The NAMES_PER_DIR option tells this command to consider one direc‐
2190 tory at a time and search for all names in it.
2191 Each library name given to the NAMES option is first considered as a
2193 library file name and then considered with platform-specific prefixes
2194 (e.g. lib) and suffixes (e.g. .so). Therefore one may specify library
2195 file names such as libfoo.a directly. This can be used to locate
2196 static libraries on UNIX-like systems.
2197 If the library found is a framework, then <VAR> will be set to the full
2199 path to the framework <fullPath>/A.framework. When a full path to a
2200 framework is used as a library, CMake will use a -framework A, and a
2201 -F<fullPath> to link the framework to the target.
2202 If the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable is set all search
2204 paths will be tested as normal, with the suffix appended, and with all
2205 matches of lib/ replaced with lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUF‐
2206 FIX}/. This variable overrides the FIND_LIBRARY_USE_LIB32_PATHS,
2207 FIND_LIBRARY_USE_LIBX32_PATHS, and FIND_LIBRARY_USE_LIB64_PATHS global
2208 properties.
2209 If the FIND_LIBRARY_USE_LIB32_PATHS global property is set all search
2211 paths will be tested as normal, with 32/ appended, and with all matches
2212 of lib/ replaced with lib32/. This property is automatically set for
2213 the platforms that are known to need it if at least one of the lan‐
2214 guages supported by the project() command is enabled.
2215 If the FIND_LIBRARY_USE_LIBX32_PATHS global property is set all search
2217 paths will be tested as normal, with x32/ appended, and with all
2218 matches of lib/ replaced with libx32/. This property is automatically
2219 set for the platforms that are known to need it if at least one of the
2220 languages supported by the project() command is enabled.
2221 If the FIND_LIBRARY_USE_LIB64_PATHS global property is set all search
2223 paths will be tested as normal, with 64/ appended, and with all matches
2224 of lib/ replaced with lib64/. This property is automatically set for
2225 the platforms that are known to need it if at least one of the lan‐
2226 guages supported by the project() command is enabled.
2227 find_package
2229 Find an external project, and load its settings.
2230 Basic Signature and Module Mode
2232 find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
2233 [REQUIRED] [[COMPONENTS] [components...]]
2234 [OPTIONAL_COMPONENTS components...]
2235 [NO_POLICY_SCOPE])
2236 Finds and loads settings from an external project. <PackageName>_FOUND
2238 will be set to indicate whether the package was found. When the pack‐
2239 age is found package-specific information is provided through variables
2240 and Imported Targets documented by the package itself. The QUIET
2241 option disables informational messages, including those indicating that
2242 the package cannot be found if it is not REQUIRED. The REQUIRED option
2243 stops processing with an error message if the package cannot be found.
2244 A package-specific list of required components may be listed after the
2246 COMPONENTS option (or after the REQUIRED option if present). Addi‐
2247 tional optional components may be listed after OPTIONAL_COMPONENTS.
2248 Available components and their influence on whether a package is con‐
2249 sidered to be found are defined by the target package.
2250 The [version] argument requests a version with which the package found
2252 should be compatible. There are two possible forms in which it may be
2253 specified:
2254 · A single version with the format major[.minor[.patch[.tweak]]].
2256 · A version range with the format versionMin...[<]versionMax where
2258 versionMin and versionMax have the same format as the single ver‐
2259 sion. By default, both end points are included. By specifying <,
2260 the upper end point will be excluded. Version ranges are only
2261 supported with CMake 3.19 or later.
2262 The EXACT option requests that the version be matched exactly. This
2264 option is incompatible with the specification of a version range.
2265 If no [version] and/or component list is given to a recursive invoca‐
2267 tion inside a find-module, the corresponding arguments are forwarded
2268 automatically from the outer call (including the EXACT flag for [ver‐
2269 sion]). Version support is currently provided only on a pack‐
2270 age-by-package basis (see the Version Selection section below). When a
2271 version range is specified but the package is only designed to expect a
2272 single version, the package will ignore the upper end point of the
2273 range and only take the single version at the lower end of the range
2274 into account.
2275 See the cmake_policy() command documentation for discussion of the
2277 NO_POLICY_SCOPE option.
2278 The command has two modes by which it searches for packages: “Module”
2280 mode and “Config” mode. The above signature selects Module mode. If
2281 no module is found the command falls back to Config mode, described
2282 below. This fall back is disabled if the MODULE option is given.
2283 In Module mode, CMake searches for a file called Find<Package‐
2285 Name>.cmake. The file is first searched in the CMAKE_MODULE_PATH, then
2286 among the Find Modules provided by the CMake installation. If the file
2287 is found, it is read and processed by CMake. It is responsible for
2288 finding the package, checking the version, and producing any needed
2289 messages. Some find-modules provide limited or no support for version‐
2290 ing; check the module documentation.
2291 If the MODULE option is not specified in the above signature, CMake
2293 first searches for the package using Module mode. Then, if the package
2294 is not found, it searches again using Config mode. A user may set the
2295 variable CMAKE_FIND_PACKAGE_PREFER_CONFIG to TRUE to direct CMake first
2296 search using Config mode before falling back to Module mode.
2297 Full Signature and Config Mode
2299 User code should generally look for packages using the above basic sig‐
2300 nature. The remainder of this command documentation specifies the full
2301 command signature and details of the search process. Project maintain‐
2302 ers wishing to provide a package to be found by this command are
2303 encouraged to read on.
2304 The complete Config mode command signature is
2306 find_package(<PackageName> [version] [EXACT] [QUIET]
2308 [REQUIRED] [[COMPONENTS] [components...]]
2309 [OPTIONAL_COMPONENTS components...]
2310 [CONFIG|NO_MODULE]
2311 [NO_POLICY_SCOPE]
2312 [NAMES name1 [name2 ...]]
2313 [CONFIGS config1 [config2 ...]]
2314 [HINTS path1 [path2 ... ]]
2315 [PATHS path1 [path2 ... ]]
2316 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2317 [NO_DEFAULT_PATH]
2318 [NO_PACKAGE_ROOT_PATH]
2319 [NO_CMAKE_PATH]
2320 [NO_CMAKE_ENVIRONMENT_PATH]
2321 [NO_SYSTEM_ENVIRONMENT_PATH]
2322 [NO_CMAKE_PACKAGE_REGISTRY]
2323 [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
2324 [NO_CMAKE_SYSTEM_PATH]
2325 [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
2326 [CMAKE_FIND_ROOT_PATH_BOTH |
2327 ONLY_CMAKE_FIND_ROOT_PATH |
2328 NO_CMAKE_FIND_ROOT_PATH])
2329 The CONFIG option, the synonymous NO_MODULE option, or the use of
2331 options not specified in the basic signature all enforce pure Config
2332 mode. In pure Config mode, the command skips Module mode search and
2333 proceeds at once with Config mode search.
2334 Config mode search attempts to locate a configuration file provided by
2336 the package to be found. A cache entry called <PackageName>_DIR is
2337 created to hold the directory containing the file. By default the com‐
2338 mand searches for a package with the name <PackageName>. If the NAMES
2339 option is given the names following it are used instead of <Package‐
2340 Name>. The command searches for a file called <PackageName>Con‐
2341 fig.cmake or <lower-case-package-name>-config.cmake for each name spec‐
2342 ified. A replacement set of possible configuration file names may be
2343 given using the CONFIGS option. The search procedure is specified
2344 below. Once found, the configuration file is read and processed by
2345 CMake. Since the file is provided by the package it already knows the
2346 location of package contents. The full path to the configuration file
2347 is stored in the cmake variable <PackageName>_CONFIG.
2348 All configuration files which have been considered by CMake while
2350 searching for an installation of the package with an appropriate ver‐
2351 sion are stored in the cmake variable <PackageName>_CONSIDERED_CONFIGS,
2352 the associated versions in <PackageName>_CONSIDERED_VERSIONS.
2353 If the package configuration file cannot be found CMake will generate
2355 an error describing the problem unless the QUIET argument is specified.
2356 If REQUIRED is specified and the package is not found a fatal error is
2357 generated and the configure step stops executing. If <PackageName>_DIR
2358 has been set to a directory not containing a configuration file CMake
2359 will ignore it and search from scratch.
2360 Package maintainers providing CMake package configuration files are
2362 encouraged to name and install them such that the Search Procedure out‐
2363 lined below will find them without requiring use of additional options.
2364 Version Selection
2366 When the [version] argument is given, Config mode will only find a ver‐
2367 sion of the package that claims compatibility with the requested ver‐
2368 sion (see format specification). If the EXACT option is given, only a
2369 version of the package claiming an exact match of the requested version
2370 may be found. CMake does not establish any convention for the meaning
2371 of version numbers. Package version numbers are checked by “version”
2372 files provided by the packages themselves. For a candidate package
2373 configuration file <config-file>.cmake the corresponding version file
2374 is located next to it and named either <config-file>-version.cmake or
2375 <config-file>Version.cmake. If no such version file is available then
2376 the configuration file is assumed to not be compatible with any
2377 requested version. A basic version file containing generic version
2378 matching code can be created using the CMakePackageConfigHelpers mod‐
2379 ule. When a version file is found it is loaded to check the requested
2380 version number. The version file is loaded in a nested scope in which
2381 the following variables have been defined:
2382 PACKAGE_FIND_NAME
2384 The <PackageName>
2385 PACKAGE_FIND_VERSION
2387 Full requested version string
2388 PACKAGE_FIND_VERSION_MAJOR
2390 Major version if requested, else 0
2391 PACKAGE_FIND_VERSION_MINOR
2393 Minor version if requested, else 0
2394 PACKAGE_FIND_VERSION_PATCH
2396 Patch version if requested, else 0
2397 PACKAGE_FIND_VERSION_TWEAK
2399 Tweak version if requested, else 0
2400 PACKAGE_FIND_VERSION_COUNT
2402 Number of version components, 0 to 4
2403 When a version range is specified, the above version variables will
2405 hold values based on the lower end of the version range. This is to
2406 preserve compatibility with packages that have not been implemented to
2407 expect version ranges. In addition, the version range will be
2408 described by the following variables:
2409 PACKAGE_FIND_VERSION_RANGE
2411 Full requested version range string
2412 PACKAGE_FIND_VERSION_RANGE_MIN
2414 This specifies whether the lower end point of the version range
2415 should be included or excluded. Currently, the only supported
2416 value for this variable is INCLUDE.
2417 PACKAGE_FIND_VERSION_RANGE_MAX
2419 This specifies whether the upper end point of the version range
2420 should be included or excluded. The supported values for this
2421 variable are INCLUDE and EXCLUDE.
2422 PACKAGE_FIND_VERSION_MIN
2424 Full requested version string of the lower end point of the
2425 range
2426 PACKAGE_FIND_VERSION_MIN_MAJOR
2428 Major version of the lower end point if requested, else 0
2429 PACKAGE_FIND_VERSION_MIN_MINOR
2431 Minor version of the lower end point if requested, else 0
2432 PACKAGE_FIND_VERSION_MIN_PATCH
2434 Patch version of the lower end point if requested, else 0
2435 PACKAGE_FIND_VERSION_MIN_TWEAK
2437 Tweak version of the lower end point if requested, else 0
2438 PACKAGE_FIND_VERSION_MIN_COUNT
2440 Number of version components of the lower end point, 0 to 4
2441 PACKAGE_FIND_VERSION_MAX
2443 Full requested version string of the upper end point of the
2444 range
2445 PACKAGE_FIND_VERSION_MAX_MAJOR
2447 Major version of the upper end point if requested, else 0
2448 PACKAGE_FIND_VERSION_MAX_MINOR
2450 Minor version of the upper end point if requested, else 0
2451 PACKAGE_FIND_VERSION_MAX_PATCH
2453 Patch version of the upper end point if requested, else 0
2454 PACKAGE_FIND_VERSION_MAX_TWEAK
2456 Tweak version of the upper end point if requested, else 0
2457 PACKAGE_FIND_VERSION_MAX_COUNT
2459 Number of version components of the upper end point, 0 to 4
2460 Regardless of whether a single version or a version range is specified,
2462 the variable PACKAGE_FIND_VERSION_COMPLETE will be defined and will
2463 hold the full requested version string as specified.
2464 The version file checks whether it satisfies the requested version and
2466 sets these variables:
2467 PACKAGE_VERSION
2469 Full provided version string
2470 PACKAGE_VERSION_EXACT
2472 True if version is exact match
2473 PACKAGE_VERSION_COMPATIBLE
2475 True if version is compatible
2476 PACKAGE_VERSION_UNSUITABLE
2478 True if unsuitable as any version
2479 These variables are checked by the find_package command to determine
2481 whether the configuration file provides an acceptable version. They
2482 are not available after the find_package call returns. If the version
2483 is acceptable the following variables are set:
2484 <PackageName>_VERSION
2486 Full provided version string
2487 <PackageName>_VERSION_MAJOR
2489 Major version if provided, else 0
2490 <PackageName>_VERSION_MINOR
2492 Minor version if provided, else 0
2493 <PackageName>_VERSION_PATCH
2495 Patch version if provided, else 0
2496 <PackageName>_VERSION_TWEAK
2498 Tweak version if provided, else 0
2499 <PackageName>_VERSION_COUNT
2501 Number of version components, 0 to 4
2502 and the corresponding package configuration file is loaded. When mul‐
2504 tiple package configuration files are available whose version files
2505 claim compatibility with the version requested it is unspecified which
2506 one is chosen: unless the variable CMAKE_FIND_PACKAGE_SORT_ORDER is set
2507 no attempt is made to choose a highest or closest version number.
2508 To control the order in which find_package checks for compatibility use
2510 the two variables CMAKE_FIND_PACKAGE_SORT_ORDER and CMAKE_FIND_PACK‐
2511 AGE_SORT_DIRECTION. For instance in order to select the highest ver‐
2512 sion one can set
2513 SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
2515 SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
2516 before calling find_package.
2518 Search Procedure
2520 CMake constructs a set of possible installation prefixes for the pack‐
2521 age. Under each prefix several directories are searched for a configu‐
2522 ration file. The tables below show the directories searched. Each
2523 entry is meant for installation trees following Windows (W), UNIX (U),
2524 or Apple (A) conventions:
2525 <prefix>/ (W)
2527 <prefix>/(cmake|CMake)/ (W)
2528 <prefix>/<name>*/ (W)
2529 <prefix>/<name>*/(cmake|CMake)/ (W)
2530 <prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/ (U)
2531 <prefix>/(lib/<arch>|lib*|share)/<name>*/ (U)
2532 <prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (U)
2533 <prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/ (W/U)
2534 <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ (W/U)
2535 <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U)
2536 On systems supporting macOS FRAMEWORK and BUNDLE, the following direc‐
2538 tories are searched for Frameworks or Application Bundles containing a
2539 configuration file:
2540 <prefix>/<name>.framework/Resources/ (A)
2542 <prefix>/<name>.framework/Resources/CMake/ (A)
2543 <prefix>/<name>.framework/Versions/*/Resources/ (A)
2544 <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A)
2545 <prefix>/<name>.app/Contents/Resources/ (A)
2546 <prefix>/<name>.app/Contents/Resources/CMake/ (A)
2547 In all cases the <name> is treated as case-insensitive and corresponds
2549 to any of the names specified (<PackageName> or names given by NAMES).
2550 Paths with lib/<arch> are enabled if the CMAKE_LIBRARY_ARCHITECTURE
2552 variable is set. lib* includes one or more of the values lib64, lib32,
2553 libx32 or lib (searched in that order).
2554 · Paths with lib64 are searched on 64 bit platforms if the
2556 FIND_LIBRARY_USE_LIB64_PATHS property is set to TRUE.
2557 · Paths with lib32 are searched on 32 bit platforms if the
2559 FIND_LIBRARY_USE_LIB32_PATHS property is set to TRUE.
2560 · Paths with libx32 are searched on platforms using the x32 ABI if the
2562 FIND_LIBRARY_USE_LIBX32_PATHS property is set to TRUE.
2563 · The lib path is always searched.
2565 If PATH_SUFFIXES is specified, the suffixes are appended to each (W) or
2567 (U) directory entry one-by-one.
2568 This set of directories is intended to work in cooperation with
2570 projects that provide configuration files in their installation trees.
2571 Directories above marked with (W) are intended for installations on
2572 Windows where the prefix may point at the top of an application’s
2573 installation directory. Those marked with (U) are intended for instal‐
2574 lations on UNIX platforms where the prefix is shared by multiple pack‐
2575 ages. This is merely a convention, so all (W) and (U) directories are
2576 still searched on all platforms. Directories marked with (A) are
2577 intended for installations on Apple platforms. The CMAKE_FIND_FRAME‐
2578 WORK and CMAKE_FIND_APPBUNDLE variables determine the order of prefer‐
2579 ence.
2580 The set of installation prefixes is constructed using the following
2582 steps. If NO_DEFAULT_PATH is specified all NO_* options are enabled.
2583 1. Search paths specified in the <PackageName>_ROOT CMake variable and
2585 the <PackageName>_ROOT environment variable, where <PackageName> is
2586 the package to be found. The package root variables are maintained
2587 as a stack so if called from within a find module, root paths from
2588 the parent’s find module will also be searched after paths for the
2589 current package. This can be skipped if NO_PACKAGE_ROOT_PATH is
2590 passed or by setting the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE.
2591 See policy CMP0074.
2592 2. Search paths specified in cmake-specific cache variables. These are
2594 intended to be used on the command line with a -DVAR=value. The
2595 values are interpreted as semicolon-separated lists. This can be
2596 skipped if NO_CMAKE_PATH is passed or by setting the
2597 CMAKE_FIND_USE_CMAKE_PATH to FALSE:
2598 · CMAKE_PREFIX_PATH
2600 · CMAKE_FRAMEWORK_PATH
2602 · CMAKE_APPBUNDLE_PATH
2604 3. Search paths specified in cmake-specific environment variables.
2606 These are intended to be set in the user’s shell configuration, and
2607 therefore use the host’s native path separator (; on Windows and :
2608 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2609 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
2610 FALSE:
2611 · <PackageName>_DIR
2613 · CMAKE_PREFIX_PATH
2615 · CMAKE_FRAMEWORK_PATH
2617 · CMAKE_APPBUNDLE_PATH
2619 4. Search paths specified by the HINTS option. These should be paths
2621 computed by system introspection, such as a hint provided by the
2622 location of another item already found. Hard-coded guesses should
2623 be specified with the PATHS option.
2624 5. Search the standard system environment variables. This can be
2626 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
2627 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE. Path entries ending
2628 in /bin or /sbin are automatically converted to their parent direc‐
2629 tories:
2630 · PATH
2632 6. Search paths stored in the CMake User Package Registry. This can be
2634 skipped if NO_CMAKE_PACKAGE_REGISTRY is passed or by setting the
2635 variable CMAKE_FIND_USE_PACKAGE_REGISTRY to FALSE or the deprecated
2636 variable CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY to TRUE.
2637 See the cmake-packages(7) manual for details on the user package
2639 registry.
2640 7. Search cmake variables defined in the Platform files for the current
2642 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
2643 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE:
2644 · CMAKE_SYSTEM_PREFIX_PATH
2646 · CMAKE_SYSTEM_FRAMEWORK_PATH
2648 · CMAKE_SYSTEM_APPBUNDLE_PATH
2650 The platform paths that these variables contain are locations that
2652 typically include installed software. An example being /usr/local
2653 for UNIX based platforms.
2654 8. Search paths stored in the CMake System Package Registry. This can
2656 be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is passed or by set‐
2657 ting the CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variable to FALSE or
2658 the deprecated variable CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REG‐
2659 ISTRY to TRUE.
2660 See the cmake-packages(7) manual for details on the system package
2662 registry.
2663 9. Search paths specified by the PATHS option. These are typically
2665 hard-coded guesses.
2666 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
2668 ries to be prepended to all other search directories. This effectively
2669 “re-roots” the entire search under given locations. Paths which are
2670 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
2671 ing, because that variable is always a path on the host system. By
2672 default the CMAKE_FIND_ROOT_PATH is empty.
2673 The CMAKE_SYSROOT variable can also be used to specify exactly one
2675 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
2676 effects. See the documentation for that variable for more.
2677 These variables are especially useful when cross-compiling to point to
2679 the root directory of the target environment and CMake will search
2680 there too. By default at first the directories listed in
2681 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
2682 searched, and then the non-rooted directories will be searched. The
2683 default behavior can be adjusted by setting
2684 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE. This behavior can be manually over‐
2685 ridden on a per-call basis using options:
2686 CMAKE_FIND_ROOT_PATH_BOTH
2688 Search in the order described above.
2689 NO_CMAKE_FIND_ROOT_PATH
2691 Do not use the CMAKE_FIND_ROOT_PATH variable.
2692 ONLY_CMAKE_FIND_ROOT_PATH
2694 Search only the re-rooted directories and directories below
2695 CMAKE_STAGING_PREFIX.
2696 The default search order is designed to be most-specific to least-spe‐
2698 cific for common use cases. Projects may override the order by simply
2699 calling the command multiple times and using the NO_* options:
2700 find_package (<PackageName> PATHS paths... NO_DEFAULT_PATH)
2702 find_package (<PackageName>)
2703 Once one of the calls succeeds the result variable will be set and
2705 stored in the cache so that no call will search again.
2706 By default the value stored in the result variable will be the path at
2708 which the file is found. The CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS vari‐
2709 able may be set to TRUE before calling find_package in order to resolve
2710 symbolic links and store the real path to the file.
2711 Every non-REQUIRED find_package call can be disabled by setting the
2713 CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable to TRUE.
2714 Package File Interface Variables
2716 When loading a find module or package configuration file find_package
2717 defines variables to provide information about the call arguments (and
2718 restores their original state before returning):
2719 CMAKE_FIND_PACKAGE_NAME
2721 The <PackageName> which is searched for
2722 <PackageName>_FIND_REQUIRED
2724 True if REQUIRED option was given
2725 <PackageName>_FIND_QUIETLY
2727 True if QUIET option was given
2728 <PackageName>_FIND_VERSION
2730 Full requested version string
2731 <PackageName>_FIND_VERSION_MAJOR
2733 Major version if requested, else 0
2734 <PackageName>_FIND_VERSION_MINOR
2736 Minor version if requested, else 0
2737 <PackageName>_FIND_VERSION_PATCH
2739 Patch version if requested, else 0
2740 <PackageName>_FIND_VERSION_TWEAK
2742 Tweak version if requested, else 0
2743 <PackageName>_FIND_VERSION_COUNT
2745 Number of version components, 0 to 4
2746 <PackageName>_FIND_VERSION_EXACT
2748 True if EXACT option was given
2749 <PackageName>_FIND_COMPONENTS
2751 List of requested components
2752 <PackageName>_FIND_REQUIRED_<c>
2754 True if component <c> is required, false if component <c> is
2755 optional
2756 When a version range is specified, the above version variables will
2758 hold values based on the lower end of the version range. This is to
2759 preserve compatibility with packages that have not been implemented to
2760 expect version ranges. In addition, the version range will be
2761 described by the following variables:
2762 <PackageName>_FIND_VERSION_RANGE
2764 Full requested version range string
2765 <PackageName>_FIND_VERSION_RANGE_MIN
2767 This specifies whether the lower end point of the version range
2768 is included or excluded. Currently, INCLUDE is the only sup‐
2769 ported value.
2770 <PackageName>_FIND_VERSION_RANGE_MAX
2772 This specifies whether the upper end point of the version range
2773 is included or excluded. The possible values for this variable
2774 are INCLUDE or EXCLUDE.
2775 <PackageName>_FIND_VERSION_MIN
2777 Full requested version string of the lower end point of the
2778 range
2779 <PackageName>_FIND_VERSION_MIN_MAJOR
2781 Major version of the lower end point if requested, else 0
2782 <PackageName>_FIND_VERSION_MIN_MINOR
2784 Minor version of the lower end point if requested, else 0
2785 <PackageName>_FIND_VERSION_MIN_PATCH
2787 Patch version of the lower end point if requested, else 0
2788 <PackageName>_FIND_VERSION_MIN_TWEAK
2790 Tweak version of the lower end point if requested, else 0
2791 <PackageName>_FIND_VERSION_MIN_COUNT
2793 Number of version components of the lower end point, 0 to 4
2794 <PackageName>_FIND_VERSION_MAX
2796 Full requested version string of the upper end point of the
2797 range
2798 <PackageName>_FIND_VERSION_MAX_MAJOR
2800 Major version of the upper end point if requested, else 0
2801 <PackageName>_FIND_VERSION_MAX_MINOR
2803 Minor version of the upper end point if requested, else 0
2804 <PackageName>_FIND_VERSION_MAX_PATCH
2806 Patch version of the upper end point if requested, else 0
2807 <PackageName>_FIND_VERSION_MAX_TWEAK
2809 Tweak version of the upper end point if requested, else 0
2810 <PackageName>_FIND_VERSION_MAX_COUNT
2812 Number of version components of the upper end point, 0 to 4
2813 Regardless of whether a single version or a version range is specified,
2815 the variable <PackageName>_FIND_VERSION_COMPLETE will be defined and
2816 will hold the full requested version string as specified.
2817 In Module mode the loaded find module is responsible to honor the
2819 request detailed by these variables; see the find module for details.
2820 In Config mode find_package handles REQUIRED, QUIET, and [version]
2821 options automatically but leaves it to the package configuration file
2822 to handle components in a way that makes sense for the package. The
2823 package configuration file may set <PackageName>_FOUND to false to tell
2824 find_package that component requirements are not satisfied.
2825 find_path
2827 A short-hand signature is:
2828 find_path (<VAR> name1 [path1 path2 ...])
2830 The general signature is:
2832 find_path (
2834 <VAR>
2835 name | NAMES name1 [name2 ...]
2836 [HINTS path1 [path2 ... ENV var]]
2837 [PATHS path1 [path2 ... ENV var]]
2838 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2839 [DOC "cache documentation string"]
2840 [REQUIRED]
2841 [NO_DEFAULT_PATH]
2842 [NO_PACKAGE_ROOT_PATH]
2843 [NO_CMAKE_PATH]
2844 [NO_CMAKE_ENVIRONMENT_PATH]
2845 [NO_SYSTEM_ENVIRONMENT_PATH]
2846 [NO_CMAKE_SYSTEM_PATH]
2847 [CMAKE_FIND_ROOT_PATH_BOTH |
2848 ONLY_CMAKE_FIND_ROOT_PATH |
2849 NO_CMAKE_FIND_ROOT_PATH]
2850 )
2851 This command is used to find a directory containing the named file. A
2853 cache entry named by <VAR> is created to store the result of this com‐
2854 mand. If the file in a directory is found the result is stored in the
2855 variable and the search will not be repeated unless the variable is
2856 cleared. If nothing is found, the result will be <VAR>-NOTFOUND. The
2857 REQUIRED option stops processing with an error message if nothing is
2858 found, otherwise the search will be attempted again the next time
2859 find_path is invoked with the same variable.
2860 Options include:
2862 NAMES Specify one or more possible names for the file in a directory.
2864 When using this to specify names with and without a version suf‐
2866 fix, we recommend specifying the unversioned name first so that
2867 locally-built packages can be found before those provided by
2868 distributions.
2869 HINTS, PATHS
2871 Specify directories to search in addition to the default loca‐
2872 tions. The ENV var sub-option reads paths from a system envi‐
2873 ronment variable.
2874 PATH_SUFFIXES
2876 Specify additional subdirectories to check below each directory
2877 location otherwise considered.
2878 DOC Specify the documentation string for the <VAR> cache entry.
2880 REQUIRED
2882 Stop processing with an error message if nothing is found.
2883 If NO_DEFAULT_PATH is specified, then no additional paths are added to
2885 the search. If NO_DEFAULT_PATH is not specified, the search process is
2886 as follows:
2887 1. If called from within a find module or any other script loaded by a
2889 call to find_package(<PackageName>), search prefixes unique to the
2890 current package being found. Specifically, look in the <Package‐
2891 Name>_ROOT CMake variable and the <PackageName>_ROOT environment
2892 variable. The package root variables are maintained as a stack, so
2893 if called from nested find modules or config packages, root paths
2894 from the parent’s find module or config package will be searched
2895 after paths from the current module or package. In other words, the
2896 search order would be <CurrentPackage>_ROOT, ENV{<CurrentPack‐
2897 age>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
2898 This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
2899 the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
2900 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2902 <prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
2903 variable and the <PackageName>_ROOT environment variable if called
2904 from within a find module loaded by find_package(<PackageName>)
2905 2. Search paths specified in cmake-specific cache variables. These are
2907 intended to be used on the command line with a -DVAR=value. The
2908 values are interpreted as semicolon-separated lists. This can be
2909 skipped if NO_CMAKE_PATH is passed or by setting the
2910 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
2911 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2913 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2914 · CMAKE_INCLUDE_PATH
2916 · CMAKE_FRAMEWORK_PATH
2918 3. Search paths specified in cmake-specific environment variables.
2920 These are intended to be set in the user’s shell configuration, and
2921 therefore use the host’s native path separator (; on Windows and :
2922 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2923 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
2924 FALSE.
2925 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2927 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2928 · CMAKE_INCLUDE_PATH
2930 · CMAKE_FRAMEWORK_PATH
2932 4. Search the paths specified by the HINTS option. These should be
2934 paths computed by system introspection, such as a hint provided by
2935 the location of another item already found. Hard-coded guesses
2936 should be specified with the PATHS option.
2937 5. Search the standard system environment variables. This can be
2939 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
2940 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
2941 · The directories in INCLUDE and PATH.
2943 · On Windows hosts: <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHI‐
2945 TECTURE is set, and <prefix>/include for each <prefix>/[s]bin in
2946 PATH, and <entry>/include for other entries in PATH.
2947 6. Search cmake variables defined in the Platform files for the current
2949 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
2950 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
2951 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2953 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2954 · CMAKE_SYSTEM_INCLUDE_PATH
2956 · CMAKE_SYSTEM_FRAMEWORK_PATH
2958 The platform paths that these variables contain are locations that
2960 typically include installed software. An example being /usr/local
2961 for UNIX based platforms.
2962 7. Search the paths specified by the PATHS option or in the short-hand
2964 version of the command. These are typically hard-coded guesses.
2965 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
2967 determine the order of preference between Apple-style and unix-style
2968 package components.
2969 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
2971 ries to be prepended to all other search directories. This effectively
2972 “re-roots” the entire search under given locations. Paths which are
2973 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
2974 ing, because that variable is always a path on the host system. By
2975 default the CMAKE_FIND_ROOT_PATH is empty.
2976 The CMAKE_SYSROOT variable can also be used to specify exactly one
2978 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
2979 effects. See the documentation for that variable for more.
2980 These variables are especially useful when cross-compiling to point to
2982 the root directory of the target environment and CMake will search
2983 there too. By default at first the directories listed in
2984 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
2985 searched, and then the non-rooted directories will be searched. The
2986 default behavior can be adjusted by setting
2987 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually over‐
2988 ridden on a per-call basis using options:
2989 CMAKE_FIND_ROOT_PATH_BOTH
2991 Search in the order described above.
2992 NO_CMAKE_FIND_ROOT_PATH
2994 Do not use the CMAKE_FIND_ROOT_PATH variable.
2995 ONLY_CMAKE_FIND_ROOT_PATH
2997 Search only the re-rooted directories and directories below
2998 CMAKE_STAGING_PREFIX.
2999 The default search order is designed to be most-specific to least-spe‐
3001 cific for common use cases. Projects may override the order by simply
3002 calling the command multiple times and using the NO_* options:
3003 find_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
3005 find_path (<VAR> NAMES name)
3006 Once one of the calls succeeds the result variable will be set and
3008 stored in the cache so that no call will search again.
3009 When searching for frameworks, if the file is specified as A/b.h, then
3011 the framework search will look for A.framework/Headers/b.h. If that is
3012 found the path will be set to the path to the framework. CMake will
3013 convert this to the correct -F option to include the file.
3014 find_program
3016 A short-hand signature is:
3017 find_program (<VAR> name1 [path1 path2 ...])
3019 The general signature is:
3021 find_program (
3023 <VAR>
3024 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
3025 [HINTS path1 [path2 ... ENV var]]
3026 [PATHS path1 [path2 ... ENV var]]
3027 [PATH_SUFFIXES suffix1 [suffix2 ...]]
3028 [DOC "cache documentation string"]
3029 [REQUIRED]
3030 [NO_DEFAULT_PATH]
3031 [NO_PACKAGE_ROOT_PATH]
3032 [NO_CMAKE_PATH]
3033 [NO_CMAKE_ENVIRONMENT_PATH]
3034 [NO_SYSTEM_ENVIRONMENT_PATH]
3035 [NO_CMAKE_SYSTEM_PATH]
3036 [CMAKE_FIND_ROOT_PATH_BOTH |
3037 ONLY_CMAKE_FIND_ROOT_PATH |
3038 NO_CMAKE_FIND_ROOT_PATH]
3039 )
3040 This command is used to find a program. A cache entry named by <VAR>
3042 is created to store the result of this command. If the program is
3043 found the result is stored in the variable and the search will not be
3044 repeated unless the variable is cleared. If nothing is found, the
3045 result will be <VAR>-NOTFOUND. The REQUIRED option stops processing
3046 with an error message if nothing is found, otherwise the search will be
3047 attempted again the next time find_program is invoked with the same
3048 variable.
3049 Options include:
3051 NAMES Specify one or more possible names for the program.
3053 When using this to specify names with and without a version suf‐
3055 fix, we recommend specifying the unversioned name first so that
3056 locally-built packages can be found before those provided by
3057 distributions.
3058 HINTS, PATHS
3060 Specify directories to search in addition to the default loca‐
3061 tions. The ENV var sub-option reads paths from a system envi‐
3062 ronment variable.
3063 PATH_SUFFIXES
3065 Specify additional subdirectories to check below each directory
3066 location otherwise considered.
3067 DOC Specify the documentation string for the <VAR> cache entry.
3069 REQUIRED
3071 Stop processing with an error message if nothing is found.
3072 If NO_DEFAULT_PATH is specified, then no additional paths are added to
3074 the search. If NO_DEFAULT_PATH is not specified, the search process is
3075 as follows:
3076 1. If called from within a find module or any other script loaded by a
3078 call to find_package(<PackageName>), search prefixes unique to the
3079 current package being found. Specifically, look in the <Package‐
3080 Name>_ROOT CMake variable and the <PackageName>_ROOT environment
3081 variable. The package root variables are maintained as a stack, so
3082 if called from nested find modules or config packages, root paths
3083 from the parent’s find module or config package will be searched
3084 after paths from the current module or package. In other words, the
3085 search order would be <CurrentPackage>_ROOT, ENV{<CurrentPack‐
3086 age>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
3087 This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
3088 the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
3089 · <prefix>/[s]bin for each <prefix> in the <PackageName>_ROOT CMake
3091 variable and the <PackageName>_ROOT environment variable if called
3092 from within a find module loaded by find_package(<PackageName>)
3093 2. Search paths specified in cmake-specific cache variables. These are
3095 intended to be used on the command line with a -DVAR=value. The
3096 values are interpreted as semicolon-separated lists. This can be
3097 skipped if NO_CMAKE_PATH is passed or by setting the
3098 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
3099 · <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
3101 · CMAKE_PROGRAM_PATH
3103 · CMAKE_APPBUNDLE_PATH
3105 3. Search paths specified in cmake-specific environment variables.
3107 These are intended to be set in the user’s shell configuration, and
3108 therefore use the host’s native path separator (; on Windows and :
3109 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
3110 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
3111 FALSE.
3112 · <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
3114 · CMAKE_PROGRAM_PATH
3116 · CMAKE_APPBUNDLE_PATH
3118 4. Search the paths specified by the HINTS option. These should be
3120 paths computed by system introspection, such as a hint provided by
3121 the location of another item already found. Hard-coded guesses
3122 should be specified with the PATHS option.
3123 5. Search the standard system environment variables. This can be
3125 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
3126 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
3127 · The directories in PATH itself.
3129 · On Windows hosts no extra search paths are included
3131 6. Search cmake variables defined in the Platform files for the current
3133 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
3134 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
3135 · <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
3137 · CMAKE_SYSTEM_PROGRAM_PATH
3139 · CMAKE_SYSTEM_APPBUNDLE_PATH
3141 The platform paths that these variables contain are locations that
3143 typically include installed software. An example being /usr/local
3144 for UNIX based platforms.
3145 7. Search the paths specified by the PATHS option or in the short-hand
3147 version of the command. These are typically hard-coded guesses.
3148 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
3150 determine the order of preference between Apple-style and unix-style
3151 package components.
3152 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
3154 ries to be prepended to all other search directories. This effectively
3155 “re-roots” the entire search under given locations. Paths which are
3156 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
3157 ing, because that variable is always a path on the host system. By
3158 default the CMAKE_FIND_ROOT_PATH is empty.
3159 The CMAKE_SYSROOT variable can also be used to specify exactly one
3161 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
3162 effects. See the documentation for that variable for more.
3163 These variables are especially useful when cross-compiling to point to
3165 the root directory of the target environment and CMake will search
3166 there too. By default at first the directories listed in
3167 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
3168 searched, and then the non-rooted directories will be searched. The
3169 default behavior can be adjusted by setting
3170 CMAKE_FIND_ROOT_PATH_MODE_PROGRAM. This behavior can be manually over‐
3171 ridden on a per-call basis using options:
3172 CMAKE_FIND_ROOT_PATH_BOTH
3174 Search in the order described above.
3175 NO_CMAKE_FIND_ROOT_PATH
3177 Do not use the CMAKE_FIND_ROOT_PATH variable.
3178 ONLY_CMAKE_FIND_ROOT_PATH
3180 Search only the re-rooted directories and directories below
3181 CMAKE_STAGING_PREFIX.
3182 The default search order is designed to be most-specific to least-spe‐
3184 cific for common use cases. Projects may override the order by simply
3185 calling the command multiple times and using the NO_* options:
3186 find_program (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
3188 find_program (<VAR> NAMES name)
3189 Once one of the calls succeeds the result variable will be set and
3191 stored in the cache so that no call will search again.
3192 When more than one value is given to the NAMES option this command by
3194 default will consider one name at a time and search every directory for
3195 it. The NAMES_PER_DIR option tells this command to consider one direc‐
3196 tory at a time and search for all names in it.
3197 foreach
3199 Evaluate a group of commands for each value in a list.
3200 foreach(<loop_var> <items>)
3202 <commands>
3203 endforeach()
3204 where <items> is a list of items that are separated by semicolon or
3206 whitespace. All commands between foreach and the matching endforeach
3207 are recorded without being invoked. Once the endforeach is evaluated,
3208 the recorded list of commands is invoked once for each item in <items>.
3209 At the beginning of each iteration the variable loop_var will be set to
3210 the value of the current item.
3211 The commands break() and continue() provide means to escape from the
3213 normal control flow.
3214 Per legacy, the endforeach() command admits an optional <loop_var>
3216 argument. If used, it must be a verbatim repeat of the argument of the
3217 opening foreach command.
3218 foreach(<loop_var> RANGE <stop>)
3220 In this variant, foreach iterates over the numbers 0, 1, … up to (and
3222 including) the nonnegative integer <stop>.
3223 foreach(<loop_var> RANGE <start> <stop> [<step>])
3225 In this variant, foreach iterates over the numbers from <start> up to
3227 at most <stop> in steps of <step>. If <step> is not specified, then
3228 the step size is 1. The three arguments <start> <stop> <step> must all
3229 be nonnegative integers, and <stop> must not be smaller than <start>;
3230 otherwise you enter the danger zone of undocumented behavior that may
3231 change in future releases.
3232 foreach(<loop_var> IN [LISTS [<lists>]] [ITEMS [<items>]])
3234 In this variant, <lists> is a whitespace or semicolon separated list of
3236 list-valued variables. The foreach command iterates over each item in
3237 each given list. The <items> following the ITEMS keyword are processed
3238 as in the first variant of the foreach command. The forms LISTS A and
3239 ITEMS ${A} are equivalent.
3240 The following example shows how the LISTS option is processed:
3242 set(A 0;1)
3244 set(B 2 3)
3245 set(C "4 5")
3246 set(D 6;7 8)
3247 set(E "")
3248 foreach(X IN LISTS A B C D E)
3249 message(STATUS "X=${X}")
3250 endforeach()
3251 yields
3253 -- X=0
3255 -- X=1
3256 -- X=2
3257 -- X=3
3258 -- X=4 5
3259 -- X=6
3260 -- X=7
3261 -- X=8
3262 foreach(<loop_var>... IN ZIP_LISTS <lists>)
3264 In this variant, <lists> is a whitespace or semicolon separated list of
3266 list-valued variables. The foreach command iterates over each list
3267 simultaneously setting the iteration variables as follows:
3268 · if the only loop_var given, then it sets a series of loop_var_N vari‐
3270 ables to the current item from the corresponding list;
3271 · if multiple variable names passed, their count should match the lists
3273 variables count;
3274 · if any of the lists are shorter, the corresponding iteration variable
3276 is not defined for the current iteration.
3277 list(APPEND English one two three four)
3279 list(APPEND Bahasa satu dua tiga)
3280 foreach(num IN ZIP_LISTS English Bahasa)
3282 message(STATUS "num_0=${num_0}, num_1=${num_1}")
3283 endforeach()
3284 foreach(en ba IN ZIP_LISTS English Bahasa)
3286 message(STATUS "en=${en}, ba=${ba}")
3287 endforeach()
3288 yields
3290 -- num_0=one, num_1=satu
3292 -- num_0=two, num_1=dua
3293 -- num_0=three, num_1=tiga
3294 -- num_0=four, num_1=
3295 -- en=one, ba=satu
3296 -- en=two, ba=dua
3297 -- en=three, ba=tiga
3298 -- en=four, ba=
3299 function
3301 Start recording a function for later invocation as a command.
3302 function(<name> [<arg1> ...])
3304 <commands>
3305 endfunction()
3306 Defines a function named <name> that takes arguments named <arg1>, …
3308 The <commands> in the function definition are recorded; they are not
3309 executed until the function is invoked.
3310 Per legacy, the endfunction() command admits an optional <name> argu‐
3312 ment. If used, it must be a verbatim repeat of the argument of the
3313 opening function command.
3314 A function opens a new scope: see set(var PARENT_SCOPE) for details.
3316 See the cmake_policy() command documentation for the behavior of poli‐
3318 cies inside functions.
3319 See the macro() command documentation for differences between CMake
3321 functions and macros.
3322 Invocation
3324 The function invocation is case-insensitive. A function defined as
3325 function(foo)
3327 <commands>
3328 endfunction()
3329 can be invoked through any of
3331 foo()
3333 Foo()
3334 FOO()
3335 cmake_language(CALL foo)
3336 and so on. However, it is strongly recommended to stay with the case
3338 chosen in the function definition. Typically functions use all-lower‐
3339 case names.
3340 The cmake_language(CALL ...) command can also be used to invoke the
3342 function.
3343 Arguments
3345 When the function is invoked, the recorded <commands> are first modi‐
3346 fied by replacing formal parameters (${arg1}, …) with the arguments
3347 passed, and then invoked as normal commands.
3348 In addition to referencing the formal parameters you can reference the
3350 ARGC variable which will be set to the number of arguments passed into
3351 the function as well as ARGV0, ARGV1, ARGV2, … which will have the
3352 actual values of the arguments passed in. This facilitates creating
3353 functions with optional arguments.
3354 Furthermore, ARGV holds the list of all arguments given to the function
3356 and ARGN holds the list of arguments past the last expected argument.
3357 Referencing to ARGV# arguments beyond ARGC have undefined behavior.
3358 Checking that ARGC is greater than # is the only way to ensure that
3359 ARGV# was passed to the function as an extra argument.
3360 get_cmake_property
3362 Get a global property of the CMake instance.
3363 get_cmake_property(<var> <property>)
3365 Gets a global property from the CMake instance. The value of the
3367 <property> is stored in the variable <var>. If the property is not
3368 found, <var> will be set to NOTFOUND. See the cmake-properties(7) man‐
3369 ual for available properties.
3370 See also the get_property() command GLOBAL option.
3372 In addition to global properties, this command (for historical reasons)
3374 also supports the VARIABLES and MACROS directory properties. It also
3375 supports a special COMPONENTS global property that lists the components
3376 given to the install() command.
3377 get_directory_property
3379 Get a property of DIRECTORY scope.
3380 get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
3382 Stores a property of directory scope in the named <variable>.
3384 The DIRECTORY argument specifies another directory from which to
3386 retrieve the property value instead of the current directory. It may
3387 reference either a source directory, or since CMake 3.19, a binary
3388 directory. Relative paths are treated as relative to the current
3389 source directory. CMake must already know about the directory, either
3390 by having added it through a call to add_subdirectory() or being the
3391 top level directory.
3392 If the property is not defined for the nominated directory scope, an
3394 empty string is returned. In the case of INHERITED properties, if the
3395 property is not found for the nominated directory scope, the search
3396 will chain to a parent scope as described for the define_property()
3397 command.
3398 get_directory_property(<variable> [DIRECTORY <dir>]
3400 DEFINITION <var-name>)
3401 Get a variable definition from a directory. This form is useful to get
3403 a variable definition from another directory.
3404 See also the more general get_property() command.
3406 get_filename_component
3408 Get a specific component of a full filename.
3409 get_filename_component(<var> <FileName> <mode> [CACHE])
3411 Sets <var> to a component of <FileName>, where <mode> is one of:
3413 DIRECTORY = Directory without file name
3415 NAME = File name without directory
3416 EXT = File name longest extension (.b.c from d/a.b.c)
3417 NAME_WE = File name with neither the directory nor the longest extension
3418 LAST_EXT = File name last extension (.c from d/a.b.c)
3419 NAME_WLE = File name with neither the directory nor the last extension
3420 PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
3421 Paths are returned with forward slashes and have no trailing slashes.
3423 If the optional CACHE argument is specified, the result variable is
3424 added to the cache.
3425 get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
3427 Sets <var> to the absolute path of <FileName>, where <mode> is one of:
3429 ABSOLUTE = Full path to file
3431 REALPATH = Full path to existing file with symlinks resolved
3432 If the provided <FileName> is a relative path, it is evaluated relative
3434 to the given base directory <dir>. If no base directory is provided,
3435 the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
3436 Paths are returned with forward slashes and have no trailing slashes.
3438 If the optional CACHE argument is specified, the result variable is
3439 added to the cache.
3440 get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
3442 The program in <FileName> will be found in the system search path or
3444 left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
3445 command-line arguments present in the <FileName> string are split from
3446 the program name and stored in <arg_var>. This is used to separate a
3447 program name from its arguments in a command line string.
3448 NOTE:
3450 The REALPATH and PROGRAM subcommands had been superseded, respec‐
3451 tively, by file(REAL_PATH) and separate_arguments(PROGRAM) commands.
3452 get_property
3454 Get a property.
3455 get_property(<variable>
3457 <GLOBAL |
3458 DIRECTORY [<dir>] |
3459 TARGET <target> |
3460 SOURCE <source> |
3461 [DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
3462 INSTALL <file> |
3463 TEST <test> |
3464 CACHE <entry> |
3465 VARIABLE >
3466 PROPERTY <name>
3467 [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
3468 Gets one property from one object in a scope.
3470 The first argument specifies the variable in which to store the result.
3472 The second argument determines the scope from which to get the prop‐
3473 erty. It must be one of the following:
3474 GLOBAL Scope is unique and does not accept a name.
3476 DIRECTORY
3478 Scope defaults to the current directory but another directory
3479 (already processed by CMake) may be named by the full or rela‐
3480 tive path <dir>. The <dir> may reference either a source direc‐
3481 tory, or since CMake 3.19, a binary directory. Relative paths
3482 are treated as relative to the current source directory. See
3483 also the get_directory_property() command.
3484 TARGET Scope must name one existing target. See also the get_tar‐
3486 get_property() command.
3487 SOURCE Scope must name one source file. By default, the source file’s
3489 property will be read from the current source directory’s scope,
3490 but this can be overridden with one of the following
3491 sub-options:
3492 DIRECTORY <dir>
3494 The source file property will be read from the <dir>
3495 directory’s scope. The <dir> may reference either a
3496 source directory, or since CMake 3.19, a binary direc‐
3497 tory. CMake must already know about the directory,
3498 either by having added it through a call to add_subdirec‐
3499 tory() or <dir> being the top level directory. Relative
3500 paths are treated as relative to the current source
3501 directory.
3502 TARGET_DIRECTORY <target>
3504 The source file property will be read from the directory
3505 scope in which <target> was created (<target> must there‐
3506 fore already exist).
3507 See also the get_source_file_property() command.
3509 INSTALL
3511 Scope must name one installed file path.
3512 TEST Scope must name one existing test. See also the get_test_prop‐
3514 erty() command.
3515 CACHE Scope must name one cache entry.
3517 VARIABLE
3519 Scope is unique and does not accept a name.
3520 The required PROPERTY option is immediately followed by the name of the
3522 property to get. If the property is not set an empty value is
3523 returned, although some properties support inheriting from a parent
3524 scope if defined to behave that way (see define_property()).
3525 If the SET option is given the variable is set to a boolean value indi‐
3527 cating whether the property has been set. If the DEFINED option is
3528 given the variable is set to a boolean value indicating whether the
3529 property has been defined such as with the define_property() command.
3530 If BRIEF_DOCS or FULL_DOCS is given then the variable is set to a
3532 string containing documentation for the requested property. If docu‐
3533 mentation is requested for a property that has not been defined NOT‐
3534 FOUND is returned.
3535 if
3537 Conditionally execute a group of commands.
3538 Synopsis
3540 if(<condition>)
3541 <commands>
3542 elseif(<condition>) # optional block, can be repeated
3543 <commands>
3544 else() # optional block
3545 <commands>
3546 endif()
3547 Evaluates the condition argument of the if clause according to the
3549 Condition syntax described below. If the result is true, then the com‐
3550 mands in the if block are executed. Otherwise, optional elseif blocks
3551 are processed in the same way. Finally, if no condition is true, com‐
3552 mands in the optional else block are executed.
3553 Per legacy, the else() and endif() commands admit an optional <condi‐
3555 tion> argument. If used, it must be a verbatim repeat of the argument
3556 of the opening if command.
3557 Condition Syntax
3559 The following syntax applies to the condition argument of the if,
3560 elseif and while() clauses.
3561 Compound conditions are evaluated in the following order of precedence:
3563 Innermost parentheses are evaluated first. Next come unary tests such
3564 as EXISTS, COMMAND, and DEFINED. Then binary tests such as EQUAL,
3565 LESS, LESS_EQUAL, GREATER, GREATER_EQUAL, STREQUAL, STRLESS, STR‐
3566 LESS_EQUAL, STRGREATER, STRGREATER_EQUAL, VERSION_EQUAL, VERSION_LESS,
3567 VERSION_LESS_EQUAL, VERSION_GREATER, VERSION_GREATER_EQUAL, and
3568 MATCHES. Then the boolean operators in the order NOT, AND, and
3569 finally OR.
3570 Possible conditions are:
3572 if(<constant>)
3574 True if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
3575 ber. False if the constant is 0, OFF, NO, FALSE, N, IGNORE,
3576 NOTFOUND, the empty string, or ends in the suffix -NOTFOUND.
3577 Named boolean constants are case-insensitive. If the argument
3578 is not one of these specific constants, it is treated as a vari‐
3579 able or string and the following signature is used.
3580 if(<variable|string>)
3582 True if given a variable that is defined to a value that is not
3583 a false constant. False otherwise. (Note macro arguments are
3584 not variables.)
3585 if(NOT <condition>)
3587 True if the condition is not true.
3588 if(<cond1> AND <cond2>)
3590 True if both conditions would be considered true individually.
3591 if(<cond1> OR <cond2>)
3593 True if either condition would be considered true individually.
3594 if(COMMAND command-name)
3596 True if the given name is a command, macro or function that can
3597 be invoked.
3598 if(POLICY policy-id)
3600 True if the given name is an existing policy (of the form
3601 CMP<NNNN>).
3602 if(TARGET target-name)
3604 True if the given name is an existing logical target name cre‐
3605 ated by a call to the add_executable(), add_library(), or
3606 add_custom_target() command that has already been invoked (in
3607 any directory).
3608 if(TEST test-name)
3610 True if the given name is an existing test name created by the
3611 add_test() command.
3612 if(EXISTS path-to-file-or-directory)
3614 True if the named file or directory exists. Behavior is
3615 well-defined only for full paths. Resolves symbolic links, i.e.
3616 if the named file or directory is a symbolic link, returns true
3617 if the target of the symbolic link exists.
3618 if(file1 IS_NEWER_THAN file2)
3620 True if file1 is newer than file2 or if one of the two files
3621 doesn’t exist. Behavior is well-defined only for full paths.
3622 If the file time stamps are exactly the same, an IS_NEWER_THAN
3623 comparison returns true, so that any dependent build operations
3624 will occur in the event of a tie. This includes the case of
3625 passing the same file name for both file1 and file2.
3626 if(IS_DIRECTORY path-to-directory)
3628 True if the given name is a directory. Behavior is well-defined
3629 only for full paths.
3630 if(IS_SYMLINK file-name)
3632 True if the given name is a symbolic link. Behavior is
3633 well-defined only for full paths.
3634 if(IS_ABSOLUTE path)
3636 True if the given path is an absolute path.
3637 if(<variable|string> MATCHES regex)
3639 True if the given string or variable’s value matches the given
3640 regular condition. See Regex Specification for regex format.
3641 () groups are captured in CMAKE_MATCH_<n> variables.
3642 if(<variable|string> LESS <variable|string>)
3644 True if the given string or variable’s value is a valid number
3645 and less than that on the right.
3646 if(<variable|string> GREATER <variable|string>)
3648 True if the given string or variable’s value is a valid number
3649 and greater than that on the right.
3650 if(<variable|string> EQUAL <variable|string>)
3652 True if the given string or variable’s value is a valid number
3653 and equal to that on the right.
3654 if(<variable|string> LESS_EQUAL <variable|string>)
3656 True if the given string or variable’s value is a valid number
3657 and less than or equal to that on the right.
3658 if(<variable|string> GREATER_EQUAL <variable|string>)
3660 True if the given string or variable’s value is a valid number
3661 and greater than or equal to that on the right.
3662 if(<variable|string> STRLESS <variable|string>)
3664 True if the given string or variable’s value is lexicographi‐
3665 cally less than the string or variable on the right.
3666 if(<variable|string> STRGREATER <variable|string>)
3668 True if the given string or variable’s value is lexicographi‐
3669 cally greater than the string or variable on the right.
3670 if(<variable|string> STREQUAL <variable|string>)
3672 True if the given string or variable’s value is lexicographi‐
3673 cally equal to the string or variable on the right.
3674 if(<variable|string> STRLESS_EQUAL <variable|string>)
3676 True if the given string or variable’s value is lexicographi‐
3677 cally less than or equal to the string or variable on the right.
3678 if(<variable|string> STRGREATER_EQUAL <variable|string>)
3680 True if the given string or variable’s value is lexicographi‐
3681 cally greater than or equal to the string or variable on the
3682 right.
3683 if(<variable|string> VERSION_LESS <variable|string>)
3685 Component-wise integer version number comparison (version format
3686 is major[.minor[.patch[.tweak]]], omitted components are treated
3687 as zero). Any non-integer version component or non-integer
3688 trailing part of a version component effectively truncates the
3689 string at that point.
3690 if(<variable|string> VERSION_GREATER <variable|string>)
3692 Component-wise integer version number comparison (version format
3693 is major[.minor[.patch[.tweak]]], omitted components are treated
3694 as zero). Any non-integer version component or non-integer
3695 trailing part of a version component effectively truncates the
3696 string at that point.
3697 if(<variable|string> VERSION_EQUAL <variable|string>)
3699 Component-wise integer version number comparison (version format
3700 is major[.minor[.patch[.tweak]]], omitted components are treated
3701 as zero). Any non-integer version component or non-integer
3702 trailing part of a version component effectively truncates the
3703 string at that point.
3704 if(<variable|string> VERSION_LESS_EQUAL <variable|string>)
3706 Component-wise integer version number comparison (version format
3707 is major[.minor[.patch[.tweak]]], omitted components are treated
3708 as zero). Any non-integer version component or non-integer
3709 trailing part of a version component effectively truncates the
3710 string at that point.
3711 if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)
3713 Component-wise integer version number comparison (version format
3714 is major[.minor[.patch[.tweak]]], omitted components are treated
3715 as zero). Any non-integer version component or non-integer
3716 trailing part of a version component effectively truncates the
3717 string at that point.
3718 if(<variable|string> IN_LIST <variable>)
3720 True if the given element is contained in the named list vari‐
3721 able.
3722 if(DEFINED <name>|CACHE{<name>}|ENV{<name>})
3724 True if a variable, cache variable or environment variable with
3725 given <name> is defined. The value of the variable does not mat‐
3726 ter. Note that macro arguments are not variables.
3727 if((condition) AND (condition OR (condition)))
3729 The conditions inside the parenthesis are evaluated first and
3730 then the remaining condition is evaluated as in the previous
3731 examples. Where there are nested parenthesis the innermost are
3732 evaluated as part of evaluating the condition that contains
3733 them.
3734 Variable Expansion
3736 The if command was written very early in CMake’s history, predating the
3737 ${} variable evaluation syntax, and for convenience evaluates variables
3738 named by its arguments as shown in the above signatures. Note that
3739 normal variable evaluation with ${} applies before the if command even
3740 receives the arguments. Therefore code like
3741 set(var1 OFF)
3743 set(var2 "var1")
3744 if(${var2})
3745 appears to the if command as
3747 if(var1)
3749 and is evaluated according to the if(<variable>) case documented above.
3751 The result is OFF which is false. However, if we remove the ${} from
3752 the example then the command sees
3753 if(var2)
3755 which is true because var2 is defined to var1 which is not a false con‐
3757 stant.
3758 Automatic evaluation applies in the other cases whenever the above-doc‐
3760 umented condition syntax accepts <variable|string>:
3761 · The left hand argument to MATCHES is first checked to see if it is a
3763 defined variable, if so the variable’s value is used, otherwise the
3764 original value is used.
3765 · If the left hand argument to MATCHES is missing it returns false
3767 without error
3768 · Both left and right hand arguments to LESS, GREATER, EQUAL,
3770 LESS_EQUAL, and GREATER_EQUAL, are independently tested to see if
3771 they are defined variables, if so their defined values are used oth‐
3772 erwise the original value is used.
3773 · Both left and right hand arguments to STRLESS, STRGREATER, STREQUAL,
3775 STRLESS_EQUAL, and STRGREATER_EQUAL are independently tested to see
3776 if they are defined variables, if so their defined values are used
3777 otherwise the original value is used.
3778 · Both left and right hand arguments to VERSION_LESS, VERSION_GREATER,
3780 VERSION_EQUAL, VERSION_LESS_EQUAL, and VERSION_GREATER_EQUAL are
3781 independently tested to see if they are defined variables, if so
3782 their defined values are used otherwise the original value is used.
3783 · The right hand argument to NOT is tested to see if it is a boolean
3785 constant, if so the value is used, otherwise it is assumed to be a
3786 variable and it is dereferenced.
3787 · The left and right hand arguments to AND and OR are independently
3789 tested to see if they are boolean constants, if so they are used as
3790 such, otherwise they are assumed to be variables and are derefer‐
3791 enced.
3792 To prevent ambiguity, potential variable or keyword names can be speci‐
3794 fied in a Quoted Argument or a Bracket Argument. A quoted or bracketed
3795 variable or keyword will be interpreted as a string and not derefer‐
3796 enced or interpreted. See policy CMP0054.
3797 There is no automatic evaluation for environment or cache Variable Ref‐
3799 erences. Their values must be referenced as $ENV{<name>} or
3800 $CACHE{<name>} wherever the above-documented condition syntax accepts
3801 <variable|string>.
3802 include
3804 Load and run CMake code from a file or module.
3805 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
3807 [NO_POLICY_SCOPE])
3808 Loads and runs CMake code from the file given. Variable reads and
3810 writes access the scope of the caller (dynamic scoping). If OPTIONAL
3811 is present, then no error is raised if the file does not exist. If
3812 RESULT_VARIABLE is given the variable <var> will be set to the full
3813 filename which has been included or NOTFOUND if it failed.
3814 If a module is specified instead of a file, the file with name <module‐
3816 name>.cmake is searched first in CMAKE_MODULE_PATH, then in the CMake
3817 module directory. There is one exception to this: if the file which
3818 calls include() is located itself in the CMake builtin module direc‐
3819 tory, then first the CMake builtin module directory is searched and
3820 CMAKE_MODULE_PATH afterwards. See also policy CMP0017.
3821 See the cmake_policy() command documentation for discussion of the
3823 NO_POLICY_SCOPE option.
3824 include_guard
3826 New in version 3.10.
3827 Provides an include guard for the file currently being processed by
3830 CMake.
3831 include_guard([DIRECTORY|GLOBAL])
3833 Sets up an include guard for the current CMake file (see the CMAKE_CUR‐
3835 RENT_LIST_FILE variable documentation).
3836 CMake will end its processing of the current file at the location of
3838 the include_guard() command if the current file has already been pro‐
3839 cessed for the applicable scope (see below). This provides functional‐
3840 ity similar to the include guards commonly used in source headers or to
3841 the #pragma once directive. If the current file has been processed pre‐
3842 viously for the applicable scope, the effect is as though return() had
3843 been called. Do not call this command from inside a function being
3844 defined within the current file.
3845 An optional argument specifying the scope of the guard may be provided.
3847 Possible values for the option are:
3848 DIRECTORY
3850 The include guard applies within the current directory and
3851 below. The file will only be included once within this directory
3852 scope, but may be included again by other files outside of this
3853 directory (i.e. a parent directory or another directory not
3854 pulled in by add_subdirectory() or include() from the current
3855 file or its children).
3856 GLOBAL The include guard applies globally to the whole build. The cur‐
3858 rent file will only be included once regardless of the scope.
3859 If no arguments given, include_guard has the same scope as a variable,
3861 meaning that the include guard effect is isolated by the most recent
3862 function scope or current directory if no inner function scopes exist.
3863 In this case the command behavior is the same as:
3864 if(__CURRENT_FILE_VAR__)
3866 return()
3867 endif()
3868 set(__CURRENT_FILE_VAR__ TRUE)
3869 list
3871 List operations.
3872 Synopsis
3874 Reading
3875 list(LENGTH <list> <out-var>)
3876 list(GET <list> <element index> [<index> ...] <out-var>)
3877 list(JOIN <list> <glue> <out-var>)
3878 list(SUBLIST <list> <begin> <length> <out-var>)
3879 Search
3881 list(FIND <list> <value> <out-var>)
3882 Modification
3884 list(APPEND <list> [<element>...])
3885 list(FILTER <list> {INCLUDE | EXCLUDE} REGEX <regex>)
3886 list(INSERT <list> <index> [<element>...])
3887 list(POP_BACK <list> [<out-var>...])
3888 list(POP_FRONT <list> [<out-var>...])
3889 list(PREPEND <list> [<element>...])
3890 list(REMOVE_ITEM <list> <value>...)
3891 list(REMOVE_AT <list> <index>...)
3892 list(REMOVE_DUPLICATES <list>)
3893 list(TRANSFORM <list> <ACTION> [...])
3894 Ordering
3896 list(REVERSE <list>)
3897 list(SORT <list> [...])
3898 Introduction
3900 The list subcommands APPEND, INSERT, FILTER, PREPEND, POP_BACK,
3901 POP_FRONT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, REVERSE and SORT
3902 may create new values for the list within the current CMake variable
3903 scope. Similar to the set() command, the LIST command creates new
3904 variable values in the current scope, even if the list itself is actu‐
3905 ally defined in a parent scope. To propagate the results of these
3906 operations upwards, use set() with PARENT_SCOPE, set() with CACHE
3907 INTERNAL, or some other means of value propagation.
3908 NOTE:
3910 A list in cmake is a ; separated group of strings. To create a list
3911 the set command can be used. For example, set(var a b c d e) cre‐
3912 ates a list with a;b;c;d;e, and set(var "a b c d e") creates a
3913 string or a list with one item in it. (Note macro arguments are
3914 not variables, and therefore cannot be used in LIST commands.)
3915 NOTE:
3917 When specifying index values, if <element index> is 0 or greater, it
3918 is indexed from the beginning of the list, with 0 representing the
3919 first list element. If <element index> is -1 or lesser, it is
3920 indexed from the end of the list, with -1 representing the last list
3921 element. Be careful when counting with negative indices: they do
3922 not start from 0. -0 is equivalent to 0, the first list element.
3923 Reading
3925 list(LENGTH <list> <output variable>)
3926 Returns the list’s length.
3928 list(GET <list> <element index> [<element index> ...] <output variable>)
3930 Returns the list of elements specified by indices from the list.
3932 list(JOIN <list> <glue> <output variable>)
3934 Returns a string joining all list’s elements using the glue string. To
3936 join multiple strings, which are not part of a list, use JOIN operator
3937 from string() command.
3938 list(SUBLIST <list> <begin> <length> <output variable>)
3940 Returns a sublist of the given list. If <length> is 0, an empty list
3942 will be returned. If <length> is -1 or the list is smaller than
3943 <begin>+<length> then the remaining elements of the list starting at
3944 <begin> will be returned.
3945 Search
3947 list(FIND <list> <value> <output variable>)
3948 Returns the index of the element specified in the list or -1 if it
3950 wasn’t found.
3951 Modification
3953 list(APPEND <list> [<element> ...])
3954 Appends elements to the list.
3956 list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
3958 Includes or removes items from the list that match the mode’s pattern.
3960 In REGEX mode, items will be matched against the given regular expres‐
3961 sion.
3962 For more information on regular expressions see also the string() com‐
3964 mand.
3965 list(INSERT <list> <element_index> <element> [<element> ...])
3967 Inserts elements to the list to the specified location.
3969 list(POP_BACK <list> [<out-var>...])
3971 If no variable name is given, removes exactly one element. Otherwise,
3973 assign the last element’s value to the given variable and removes it,
3974 up to the last variable name given.
3975 list(POP_FRONT <list> [<out-var>...])
3977 If no variable name is given, removes exactly one element. Otherwise,
3979 assign the first element’s value to the given variable and removes it,
3980 up to the last variable name given.
3981 list(PREPEND <list> [<element> ...])
3983 Insert elements to the 0th position in the list.
3985 list(REMOVE_ITEM <list> <value> [<value> ...])
3987 Removes all instances of the given items from the list.
3989 list(REMOVE_AT <list> <index> [<index> ...])
3991 Removes items at given indices from the list.
3993 list(REMOVE_DUPLICATES <list>)
3995 Removes duplicated items in the list. The relative order of items is
3997 preserved, but if duplicates are encountered, only the first instance
3998 is preserved.
3999 list(TRANSFORM <list> <ACTION> [<SELECTOR>]
4001 [OUTPUT_VARIABLE <output variable>])
4002 Transforms the list by applying an action to all or, by specifying a
4004 <SELECTOR>, to the selected elements of the list, storing the result
4005 in-place or in the specified output variable.
4006 NOTE:
4008 The TRANSFORM sub-command does not change the number of elements in
4009 the list. If a <SELECTOR> is specified, only some elements will be
4010 changed, the other ones will remain the same as before the transfor‐
4011 mation.
4012 <ACTION> specifies the action to apply to the elements of the list.
4014 The actions have exactly the same semantics as sub-commands of the
4015 string() command. <ACTION> must be one of the following:
4016 APPEND, PREPEND: Append, prepend specified value to each element of the
4018 list.
4019 list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
4021 TOUPPER, TOLOWER: Convert each element of the list to upper, lower
4023 characters.
4024 list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
4026 STRIP: Remove leading and trailing spaces from each element of the
4028 list.
4029 list(TRANSFORM <list> STRIP ...)
4031 GENEX_STRIP: Strip any generator expressions from each element of the
4033 list.
4034 list(TRANSFORM <list> GENEX_STRIP ...)
4036 REPLACE: Match the regular expression as many times as possible and
4038 substitute the replacement expression for the match for each element of
4039 the list (Same semantic as REGEX REPLACE from string() command).
4040 list(TRANSFORM <list> REPLACE <regular_expression>
4042 <replace_expression> ...)
4043 <SELECTOR> determines which elements of the list will be transformed.
4045 Only one type of selector can be specified at a time. When given,
4046 <SELECTOR> must be one of the following:
4047 AT: Specify a list of indexes.
4049 list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
4051 FOR: Specify a range with, optionally, an increment used to iterate
4053 over the range.
4054 list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
4056 REGEX: Specify a regular expression. Only elements matching the regular
4058 expression will be transformed.
4059 list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
4061 Ordering
4063 list(REVERSE <list>)
4064 Reverses the contents of the list in-place.
4066 list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
4068 Sorts the list in-place alphabetically. Use the COMPARE keyword to
4070 select the comparison method for sorting. The <compare> option should
4071 be one of:
4072 · STRING: Sorts a list of strings alphabetically. This is the default
4074 behavior if the COMPARE option is not given.
4075 · FILE_BASENAME: Sorts a list of pathnames of files by their basenames.
4077 · NATURAL: Sorts a list of strings using natural order (see strver‐
4079 scmp(3) manual), i.e. such that contiguous digits are compared as
4080 whole numbers. For example: the following list 10.0 1.1 2.1 8.0 2.0
4081 3.1 will be sorted as 1.1 2.0 2.1 3.1 8.0 10.0 if the NATURAL compar‐
4082 ison is selected where it will be sorted as 1.1 10.0 2.0 2.1 3.1 8.0
4083 with the STRING comparison.
4084 Use the CASE keyword to select a case sensitive or case insensitive
4086 sort mode. The <case> option should be one of:
4087 · SENSITIVE: List items are sorted in a case-sensitive manner. This is
4089 the default behavior if the CASE option is not given.
4090 · INSENSITIVE: List items are sorted case insensitively. The order of
4092 items which differ only by upper/lowercase is not specified.
4093 To control the sort order, the ORDER keyword can be given. The <order>
4095 option should be one of:
4096 · ASCENDING: Sorts the list in ascending order. This is the default
4098 behavior when the ORDER option is not given.
4099 · DESCENDING: Sorts the list in descending order.
4101 macro
4103 Start recording a macro for later invocation as a command
4104 macro(<name> [<arg1> ...])
4106 <commands>
4107 endmacro()
4108 Defines a macro named <name> that takes arguments named <arg1>, … Com‐
4110 mands listed after macro, but before the matching endmacro(), are not
4111 executed until the macro is invoked.
4112 Per legacy, the endmacro() command admits an optional <name> argument.
4114 If used, it must be a verbatim repeat of the argument of the opening
4115 macro command.
4116 See the cmake_policy() command documentation for the behavior of poli‐
4118 cies inside macros.
4119 See the Macro vs Function section below for differences between CMake
4121 macros and functions.
4122 Invocation
4124 The macro invocation is case-insensitive. A macro defined as
4125 macro(foo)
4127 <commands>
4128 endmacro()
4129 can be invoked through any of
4131 foo()
4133 Foo()
4134 FOO()
4135 cmake_language(CALL foo)
4136 and so on. However, it is strongly recommended to stay with the case
4138 chosen in the macro definition. Typically macros use all-lowercase
4139 names.
4140 The cmake_language(CALL ...) command can also be used to invoke the
4142 macro.
4143 Arguments
4145 When a macro is invoked, the commands recorded in the macro are first
4146 modified by replacing formal parameters (${arg1}, …) with the arguments
4147 passed, and then invoked as normal commands.
4148 In addition to referencing the formal parameters you can reference the
4150 values ${ARGC} which will be set to the number of arguments passed into
4151 the function as well as ${ARGV0}, ${ARGV1}, ${ARGV2}, … which will
4152 have the actual values of the arguments passed in. This facilitates
4153 creating macros with optional arguments.
4154 Furthermore, ${ARGV} holds the list of all arguments given to the macro
4156 and ${ARGN} holds the list of arguments past the last expected argu‐
4157 ment. Referencing to ${ARGV#} arguments beyond ${ARGC} have undefined
4158 behavior. Checking that ${ARGC} is greater than # is the only way to
4159 ensure that ${ARGV#} was passed to the function as an extra argument.
4160 Macro vs Function
4162 The macro command is very similar to the function() command. Nonethe‐
4163 less, there are a few important differences.
4164 In a function, ARGN, ARGC, ARGV and ARGV0, ARGV1, … are true variables
4166 in the usual CMake sense. In a macro, they are not, they are string
4167 replacements much like the C preprocessor would do with a macro. This
4168 has a number of consequences, as explained in the Argument Caveats sec‐
4169 tion below.
4170 Another difference between macros and functions is the control flow. A
4172 function is executed by transferring control from the calling statement
4173 to the function body. A macro is executed as if the macro body were
4174 pasted in place of the calling statement. This has the consequence
4175 that a return() in a macro body does not just terminate execution of
4176 the macro; rather, control is returned from the scope of the macro
4177 call. To avoid confusion, it is recommended to avoid return() in
4178 macros altogether.
4179 Unlike a function, the CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNC‐
4181 TION_LIST_DIR, CMAKE_CURRENT_FUNCTION_LIST_FILE, CMAKE_CURRENT_FUNC‐
4182 TION_LIST_LINE variables are not set for a macro.
4183 Argument Caveats
4185 Since ARGN, ARGC, ARGV, ARGV0 etc. are not variables, you will NOT be
4186 able to use commands like
4187 if(ARGV1) # ARGV1 is not a variable
4189 if(DEFINED ARGV2) # ARGV2 is not a variable
4190 if(ARGC GREATER 2) # ARGC is not a variable
4191 foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
4192 In the first case, you can use if(${ARGV1}). In the second and third
4194 case, the proper way to check if an optional variable was passed to the
4195 macro is to use if(${ARGC} GREATER 2). In the last case, you can use
4196 foreach(loop_var ${ARGN}) but this will skip empty arguments. If you
4197 need to include them, you can use
4198 set(list_var "${ARGN}")
4200 foreach(loop_var IN LISTS list_var)
4201 Note that if you have a variable with the same name in the scope from
4203 which the macro is called, using unreferenced names will use the exist‐
4204 ing variable instead of the arguments. For example:
4205 macro(bar)
4207 foreach(arg IN LISTS ARGN)
4208 <commands>
4209 endforeach()
4210 endmacro()
4211 function(foo)
4213 bar(x y z)
4214 endfunction()
4215 foo(a b c)
4217 Will loop over a;b;c and not over x;y;z as one might have expected. If
4219 you want true CMake variables and/or better CMake scope control you
4220 should look at the function command.
4221 mark_as_advanced
4223 Mark cmake cached variables as advanced.
4224 mark_as_advanced([CLEAR|FORCE] <var1> ...)
4226 Sets the advanced/non-advanced state of the named cached variables.
4228 An advanced variable will not be displayed in any of the cmake GUIs
4230 unless the show advanced option is on. In script mode, the
4231 advanced/non-advanced state has no effect.
4232 If the keyword CLEAR is given then advanced variables are changed back
4234 to unadvanced. If the keyword FORCE is given then the variables are
4235 made advanced. If neither FORCE nor CLEAR is specified, new values
4236 will be marked as advanced, but if a variable already has an
4237 advanced/non-advanced state, it will not be changed.
4238 NOTE:
4240 Policy CMP0102 affects the behavior of the mark_as_advanced call.
4241 When set to NEW, variables passed to this command which are not
4242 already in the cache are ignored. See policy CMP0102.
4243 math
4245 Evaluate a mathematical expression.
4246 math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])
4248 Evaluates a mathematical <expression> and sets <variable> to the
4250 resulting value. The result of the expression must be representable as
4251 a 64-bit signed integer.
4252 The mathematical expression must be given as a string (i.e. enclosed in
4254 double quotation marks). An example is "5 * (10 + 13)". Supported
4255 operators are +, -, *, /, %, |, &, ^, ~, <<, >>, and (...); they have
4256 the same meaning as in C code.
4257 Hexadecimal numbers are recognized when prefixed with 0x, as in C code.
4259 The result is formatted according to the option OUTPUT_FORMAT, where
4261 <format> is one of
4262 HEXADECIMAL
4264 Hexadecimal notation as in C code, i. e. starting with “0x”.
4265 DECIMAL
4267 Decimal notation. Which is also used if no OUTPUT_FORMAT option
4268 is specified.
4269 For example
4271 math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL) # value is set to "1000"
4273 math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL) # value is set to "0x3e8"
4274 message
4276 Log a message.
4277 Synopsis
4279 General messages
4280 message([<mode>] "message text" ...)
4281 Reporting checks
4283 message(<checkState> "message text" ...)
4284 General messages
4286 message([<mode>] "message text" ...)
4287 Record the specified message text in the log. If more than one message
4289 string is given, they are concatenated into a single message with no
4290 separator between the strings.
4291 The optional <mode> keyword determines the type of message, which
4293 influences the way the message is handled:
4294 FATAL_ERROR
4296 CMake Error, stop processing and generation.
4297 SEND_ERROR
4299 CMake Error, continue processing, but skip generation.
4300 WARNING
4302 CMake Warning, continue processing.
4303 AUTHOR_WARNING
4305 CMake Warning (dev), continue processing.
4306 DEPRECATION
4308 CMake Deprecation Error or Warning if variable CMAKE_ERROR_DEP‐
4309 RECATED or CMAKE_WARN_DEPRECATED is enabled, respectively, else
4310 no message.
4311 (none) or NOTICE
4313 Important message printed to stderr to attract user’s attention.
4314 STATUS The main interesting messages that project users might be inter‐
4316 ested in. Ideally these should be concise, no more than a sin‐
4317 gle line, but still informative.
4318 VERBOSE
4320 Detailed informational messages intended for project users.
4321 These messages should provide additional details that won’t be
4322 of interest in most cases, but which may be useful to those
4323 building the project when they want deeper insight into what’s
4324 happening.
4325 DEBUG Detailed informational messages intended for developers working
4327 on the project itself as opposed to users who just want to build
4328 it. These messages will not typically be of interest to other
4329 users building the project and will often be closely related to
4330 internal implementation details.
4331 TRACE Fine-grained messages with very low-level implementation
4333 details. Messages using this log level would normally only be
4334 temporary and would expect to be removed before releasing the
4335 project, packaging up the files, etc.
4336 The CMake command-line tool displays STATUS to TRACE messages on stdout
4338 with the message preceded by two hyphens and a space. All other mes‐
4339 sage types are sent to stderr and are not prefixed with hyphens. The
4340 CMake GUI displays all messages in its log area. The curses interface
4341 shows STATUS to TRACE messages one at a time on a status line and other
4342 messages in an interactive pop-up box. The --log-level command-line
4343 option to each of these tools can be used to control which messages
4344 will be shown. To make a log level persist between CMake runs, the
4345 CMAKE_MESSAGE_LOG_LEVEL variable can be set instead. Note that the
4346 command line option takes precedence over the cache variable.
4347 Messages of log levels NOTICE and below will have each line preceded by
4349 the content of the CMAKE_MESSAGE_INDENT variable (converted to a single
4350 string by concatenating its list items). For STATUS to TRACE messages,
4351 this indenting content will be inserted after the hyphens.
4352 Messages of log levels NOTICE and below can also have each line pre‐
4354 ceded with context of the form [some.context.example]. The content
4355 between the square brackets is obtained by converting the CMAKE_MES‐
4356 SAGE_CONTEXT list variable to a dot-separated string. The message con‐
4357 text will always appear before any indenting content but after any
4358 automatically added leading hyphens. By default, message context is not
4359 shown, it has to be explicitly enabled by giving the cmake --log-con‐
4360 text command-line option or by setting the CMAKE_MESSAGE_CONTEXT_SHOW
4361 variable to true. See the CMAKE_MESSAGE_CONTEXT documentation for
4362 usage examples.
4363 CMake Warning and Error message text displays using a simple markup
4365 language. Non-indented text is formatted in line-wrapped paragraphs
4366 delimited by newlines. Indented text is considered pre-formatted.
4367 Reporting checks
4369 A common pattern in CMake output is a message indicating the start of
4370 some sort of check, followed by another message reporting the result of
4371 that check. For example:
4372 message(STATUS "Looking for someheader.h")
4374 #... do the checks, set checkSuccess with the result
4375 if(checkSuccess)
4376 message(STATUS "Looking for someheader.h - found")
4377 else()
4378 message(STATUS "Looking for someheader.h - not found")
4379 endif()
4380 This can be more robustly and conveniently expressed using the
4382 CHECK_... keyword form of the message() command:
4383 message(<checkState> "message" ...)
4385 where <checkState> must be one of the following:
4387 CHECK_START
4389 Record a concise message about the check about to be per‐
4390 formed.
4391 CHECK_PASS
4393 Record a successful result for a check.
4394 CHECK_FAIL
4396 Record an unsuccessful result for a check.
4397 When recording a check result, the command repeats the message from the
4399 most recently started check for which no result has yet been reported,
4400 then some separator characters and then the message text provided after
4401 the CHECK_PASS or CHECK_FAIL keyword. Check messages are always
4402 reported at STATUS log level.
4403 Checks may be nested and every CHECK_START should have exactly one
4405 matching CHECK_PASS or CHECK_FAIL. The CMAKE_MESSAGE_INDENT variable
4406 can also be used to add indenting to nested checks if desired. For
4407 example:
4408 message(CHECK_START "Finding my things")
4410 list(APPEND CMAKE_MESSAGE_INDENT " ")
4411 unset(missingComponents)
4412 message(CHECK_START "Finding partA")
4414 # ... do check, assume we find A
4415 message(CHECK_PASS "found")
4416 message(CHECK_START "Finding partB")
4418 # ... do check, assume we don't find B
4419 list(APPEND missingComponents B)
4420 message(CHECK_FAIL "not found")
4421 list(POP_BACK CMAKE_MESSAGE_INDENT)
4423 if(missingComponents)
4424 message(CHECK_FAIL "missing components: ${missingComponents}")
4425 else()
4426 message(CHECK_PASS "all components found")
4427 endif()
4428 Output from the above would appear something like the following:
4430 -- Finding my things
4432 -- Finding partA
4433 -- Finding partA - found
4434 -- Finding partB
4435 -- Finding partB - not found
4436 -- Finding my things - missing components: B
4437 option
4439 Provide an option that the user can optionally select.
4440 option(<variable> "<help_text>" [value])
4442 Provides an option for the user to select as ON or OFF. If no initial
4444 <value> is provided, OFF is used. If <variable> is already set as a
4445 normal or cache variable, then the command does nothing (see policy
4446 CMP0077).
4447 If you have options that depend on the values of other options, see the
4449 module help for CMakeDependentOption.
4450 return
4452 Return from a file, directory or function.
4453 return()
4455 Returns from a file, directory or function. When this command is
4457 encountered in an included file (via include() or find_package()), it
4458 causes processing of the current file to stop and control is returned
4459 to the including file. If it is encountered in a file which is not
4460 included by another file, e.g. a CMakeLists.txt, deferred calls sched‐
4461 uled by cmake_language(DEFER) are invoked and control is returned to
4462 the parent directory if there is one. If return is called in a func‐
4463 tion, control is returned to the caller of the function.
4464 Note that a macro, unlike a function, is expanded in place and there‐
4466 fore cannot handle return().
4467 separate_arguments
4469 Parse command-line arguments into a semicolon-separated list.
4470 separate_arguments(<variable> <mode> [PROGRAM [SEPARATE_ARGS]] <args>)
4472 Parses a space-separated string <args> into a list of items, and stores
4474 this list in semicolon-separated standard form in <variable>.
4475 This function is intended for parsing command-line arguments. The
4477 entire command line must be passed as one string in the argument
4478 <args>.
4479 The exact parsing rules depend on the operating system. They are spec‐
4481 ified by the <mode> argument which must be one of the following key‐
4482 words:
4483 UNIX_COMMAND
4485 Arguments are separated by unquoted whitespace. Both sin‐
4486 gle-quote and double-quote pairs are respected. A backslash
4487 escapes the next literal character (\" is "); there are no spe‐
4488 cial escapes (\n is just n).
4489 WINDOWS_COMMAND
4491 A Windows command-line is parsed using the same syntax the run‐
4492 time library uses to construct argv at startup. It separates
4493 arguments by whitespace that is not double-quoted. Backslashes
4494 are literal unless they precede double-quotes. See the MSDN
4495 article Parsing C Command-Line Arguments for details.
4496 NATIVE_COMMAND
4498 Proceeds as in WINDOWS_COMMAND mode if the host system is Win‐
4499 dows. Otherwise proceeds as in UNIX_COMMAND mode.
4500 PROGRAM
4502 The first item in <args> is assumed to be an executable and will
4503 be searched in the system search path or left as a full path. If
4504 not found, <variable> will be empty. Otherwise, <variable> is a
4505 list of 2 elements:
4506 0. Absolute path of the program
4508 1. Any command-line arguments present in <args> as a string
4510 For example:
4512 separate_arguments (out UNIX_COMMAND PROGRAM "cc -c main.c")
4514 · First element of the list: /path/to/cc
4516 · Second element of the list: " -c main.c"
4518 SEPARATE_ARGS
4520 When this sub-option of PROGRAM option is specified, com‐
4521 mand-line arguments will be split as well and stored in <vari‐
4522 able>.
4523 For example:
4525 separate_arguments (out UNIX_COMMAND PROGRAM SEPARATE_ARGS "cc -c main.c")
4527 The contents of out will be: /path/to/cc;-c;main.c
4529 separate_arguments(<var>)
4531 Convert the value of <var> to a semi-colon separated list. All spaces
4533 are replaced with ‘;’. This helps with generating command lines.
4534 set
4536 Set a normal, cache, or environment variable to a given value. See the
4537 cmake-language(7) variables documentation for the scopes and interac‐
4538 tion of normal variables and cache entries.
4539 Signatures of this command that specify a <value>... placeholder expect
4541 zero or more arguments. Multiple arguments will be joined as a semi‐
4542 colon-separated list to form the actual variable value to be set. Zero
4543 arguments will cause normal variables to be unset. See the unset()
4544 command to unset variables explicitly.
4545 Set Normal Variable
4547 set(<variable> <value>... [PARENT_SCOPE])
4548 Sets the given <variable> in the current function or directory scope.
4550 If the PARENT_SCOPE option is given the variable will be set in the
4552 scope above the current scope. Each new directory or function creates
4553 a new scope. This command will set the value of a variable into the
4554 parent directory or calling function (whichever is applicable to the
4555 case at hand). The previous state of the variable’s value stays the
4556 same in the current scope (e.g., if it was undefined before, it is
4557 still undefined and if it had a value, it is still that value).
4558 Set Cache Entry
4560 set(<variable> <value>... CACHE <type> <docstring> [FORCE])
4561 Sets the given cache <variable> (cache entry). Since cache entries are
4563 meant to provide user-settable values this does not overwrite existing
4564 cache entries by default. Use the FORCE option to overwrite existing
4565 entries.
4566 The <type> must be specified as one of:
4568 BOOL Boolean ON/OFF value. cmake-gui(1) offers a checkbox.
4570 FILEPATH
4572 Path to a file on disk. cmake-gui(1) offers a file dialog.
4573 PATH Path to a directory on disk. cmake-gui(1) offers a file dialog.
4575 STRING A line of text. cmake-gui(1) offers a text field or a drop-down
4577 selection if the STRINGS cache entry property is set.
4578 INTERNAL
4580 A line of text. cmake-gui(1) does not show internal entries.
4581 They may be used to store variables persistently across runs.
4582 Use of this type implies FORCE.
4583 The <docstring> must be specified as a line of text providing a quick
4585 summary of the option for presentation to cmake-gui(1) users.
4586 If the cache entry does not exist prior to the call or the FORCE option
4588 is given then the cache entry will be set to the given value. Further‐
4589 more, any normal variable binding in the current scope will be removed
4590 to expose the newly cached value to any immediately following evalua‐
4591 tion.
4592 It is possible for the cache entry to exist prior to the call but have
4594 no type set if it was created on the cmake(1) command line by a user
4595 through the -D<var>=<value> option without specifying a type. In this
4596 case the set command will add the type. Furthermore, if the <type> is
4597 PATH or FILEPATH and the <value> provided on the command line is a rel‐
4598 ative path, then the set command will treat the path as relative to the
4599 current working directory and convert it to an absolute path.
4600 Set Environment Variable
4602 set(ENV{<variable>} [<value>])
4603 Sets an Environment Variable to the given value. Subsequent calls of
4605 $ENV{<variable>} will return this new value.
4606 This command affects only the current CMake process, not the process
4608 from which CMake was called, nor the system environment at large, nor
4609 the environment of subsequent build or test processes.
4610 If no argument is given after ENV{<variable>} or if <value> is an empty
4612 string, then this command will clear any existing value of the environ‐
4613 ment variable.
4614 Arguments after <value> are ignored. If extra arguments are found, then
4616 an author warning is issued.
4617 set_directory_properties
4619 Set properties of the current directory and subdirectories.
4620 set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...)
4622 Sets properties of the current directory and its subdirectories in
4624 key-value pairs.
4625 See also the set_property(DIRECTORY) command.
4627 See Directory Properties for the list of properties known to CMake and
4629 their individual documentation for the behavior of each property.
4630 set_property
4632 Set a named property in a given scope.
4633 set_property(<GLOBAL |
4635 DIRECTORY [<dir>] |
4636 TARGET [<target1> ...] |
4637 SOURCE [<src1> ...]
4638 [DIRECTORY <dirs> ...] |
4639 [TARGET_DIRECTORY <targets> ...]
4640 INSTALL [<file1> ...] |
4641 TEST [<test1> ...] |
4642 CACHE [<entry1> ...] >
4643 [APPEND] [APPEND_STRING]
4644 PROPERTY <name> [<value1> ...])
4645 Sets one property on zero or more objects of a scope.
4647 The first argument determines the scope in which the property is set.
4649 It must be one of the following:
4650 GLOBAL Scope is unique and does not accept a name.
4652 DIRECTORY
4654 Scope defaults to the current directory but other directories
4655 (already processed by CMake) may be named by full or relative
4656 path. Each path may reference either a source directory, or
4657 since CMake 3.19, a binary directory. Relative paths are
4658 treated as relative to the current source directory. See also
4659 the set_directory_properties() command.
4660 TARGET Scope may name zero or more existing targets. See also the
4662 set_target_properties() command.
4663 SOURCE Scope may name zero or more source files. By default, source
4665 file properties are only visible to targets added in the same
4666 directory (CMakeLists.txt). Visibility can be set in other
4667 directory scopes using one or both of the following sub-options:
4668 DIRECTORY <dirs>...
4670 The source file property will be set in each of the
4671 <dirs> directories’ scopes. Each path may reference
4672 either a source directory, or since CMake 3.19, a binary
4673 directory. CMake must already know about each of these
4674 directories, either by having added them through a call
4675 to add_subdirectory() or it being the top level source
4676 directory. Relative paths are treated as relative to the
4677 current source directory.
4678 TARGET_DIRECTORY <targets>...
4680 The source file property will be set in each of the
4681 directory scopes where any of the specified <targets>
4682 were created (the <targets> must therefore already
4683 exist).
4684 See also the set_source_files_properties() command.
4686 INSTALL
4688 Scope may name zero or more installed file paths. These are
4689 made available to CPack to influence deployment.
4690 Both the property key and value may use generator expressions.
4692 Specific properties may apply to installed files and/or directo‐
4693 ries.
4694 Path components have to be separated by forward slashes, must be
4696 normalized and are case sensitive.
4697 To reference the installation prefix itself with a relative path
4699 use ..
4700 Currently installed file properties are only defined for the WIX
4702 generator where the given paths are relative to the installation
4703 prefix.
4704 TEST Scope may name zero or more existing tests. See also the
4706 set_tests_properties() command.
4707 CACHE Scope must name zero or more cache existing entries.
4709 The required PROPERTY option is immediately followed by the name of the
4711 property to set. Remaining arguments are used to compose the property
4712 value in the form of a semicolon-separated list.
4713 If the APPEND option is given the list is appended to any existing
4715 property value (except that empty values are ignored and not appended).
4716 If the APPEND_STRING option is given the string is appended to any
4717 existing property value as string, i.e. it results in a longer string
4718 and not a list of strings. When using APPEND or APPEND_STRING with a
4719 property defined to support INHERITED behavior (see define_property()),
4720 no inheriting occurs when finding the initial value to append to. If
4721 the property is not already directly set in the nominated scope, the
4722 command will behave as though APPEND or APPEND_STRING had not been
4723 given.
4724 See the cmake-properties(7) manual for a list of properties in each
4726 scope.
4727 site_name
4729 Set the given variable to the name of the computer.
4730 site_name(variable)
4732 string
4734 String operations.
4735 Synopsis
4737 Search and Replace
4738 string(FIND <string> <substring> <out-var> [...])
4739 string(REPLACE <match-string> <replace-string> <out-var> <input>...)
4740 string(REGEX MATCH <match-regex> <out-var> <input>...)
4741 string(REGEX MATCHALL <match-regex> <out-var> <input>...)
4742 string(REGEX REPLACE <match-regex> <replace-expr> <out-var> <input>...)
4743 Manipulation
4745 string(APPEND <string-var> [<input>...])
4746 string(PREPEND <string-var> [<input>...])
4747 string(CONCAT <out-var> [<input>...])
4748 string(JOIN <glue> <out-var> [<input>...])
4749 string(TOLOWER <string> <out-var>)
4750 string(TOUPPER <string> <out-var>)
4751 string(LENGTH <string> <out-var>)
4752 string(SUBSTRING <string> <begin> <length> <out-var>)
4753 string(STRIP <string> <out-var>)
4754 string(GENEX_STRIP <string> <out-var>)
4755 string(REPEAT <string> <count> <out-var>)
4756 Comparison
4758 string(COMPARE <op> <string1> <string2> <out-var>)
4759 Hashing
4761 string(<HASH> <out-var> <input>)
4762 Generation
4764 string(ASCII <number>... <out-var>)
4765 string(HEX <string> <out-var>)
4766 string(CONFIGURE <string> <out-var> [...])
4767 string(MAKE_C_IDENTIFIER <string> <out-var>)
4768 string(RANDOM [<option>...] <out-var>)
4769 string(TIMESTAMP <out-var> [<format string>] [UTC])
4770 string(UUID <out-var> ...)
4771 JSON
4773 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
4774 {GET | TYPE | LENGTH | REMOVE}
4775 <json-string> <member|index> [<member|index> ...])
4776 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
4777 MEMBER <json-string>
4778 [<member|index> ...] <index>)
4779 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
4780 SET <json-string>
4781 <member|index> [<member|index> ...] <value>)
4782 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
4783 EQUAL <json-string1> <json-string2>)
4784 Search and Replace
4786 Search and Replace With Plain Strings
4787 string(FIND <string> <substring> <output_variable> [REVERSE])
4788 Return the position where the given <substring> was found in the sup‐
4790 plied <string>. If the REVERSE flag was used, the command will search
4791 for the position of the last occurrence of the specified <substring>.
4792 If the <substring> is not found, a position of -1 is returned.
4793 The string(FIND) subcommand treats all strings as ASCII-only charac‐
4795 ters. The index stored in <output_variable> will also be counted in
4796 bytes, so strings containing multi-byte characters may lead to unex‐
4797 pected results.
4798 string(REPLACE <match_string>
4800 <replace_string> <output_variable>
4801 <input> [<input>...])
4802 Replace all occurrences of <match_string> in the <input> with
4804 <replace_string> and store the result in the <output_variable>.
4805 Search and Replace With Regular Expressions
4807 string(REGEX MATCH <regular_expression>
4808 <output_variable> <input> [<input>...])
4809 Match the <regular_expression> once and store the match in the <out‐
4811 put_variable>. All <input> arguments are concatenated before matching.
4812 Regular expressions are specified in the subsection just below.
4813 string(REGEX MATCHALL <regular_expression>
4815 <output_variable> <input> [<input>...])
4816 Match the <regular_expression> as many times as possible and store the
4818 matches in the <output_variable> as a list. All <input> arguments are
4819 concatenated before matching.
4820 string(REGEX REPLACE <regular_expression>
4822 <replacement_expression> <output_variable>
4823 <input> [<input>...])
4824 Match the <regular_expression> as many times as possible and substitute
4826 the <replacement_expression> for the match in the output. All <input>
4827 arguments are concatenated before matching.
4828 The <replacement_expression> may refer to parenthesis-delimited subex‐
4830 pressions of the match using \1, \2, …, \9. Note that two backslashes
4831 (\\1) are required in CMake code to get a backslash through argument
4832 parsing.
4833 Regex Specification
4835 The following characters have special meaning in regular expressions:
4836 ^ Matches at beginning of input
4838 $ Matches at end of input
4840 . Matches any single character
4842 \<char>
4844 Matches the single character specified by <char>. Use this to
4845 match special regex characters, e.g. \. for a literal . or \\
4846 for a literal backslash \. Escaping a non-special character is
4847 unnecessary but allowed, e.g. \a matches a.
4848 [ ] Matches any character(s) inside the brackets
4850 [^ ] Matches any character(s) not inside the brackets
4852 - Inside brackets, specifies an inclusive range between characters
4854 on either side e.g. [a-f] is [abcdef] To match a literal - using
4855 brackets, make it the first or the last character e.g. [+*/-]
4856 matches basic mathematical operators.
4857 * Matches preceding pattern zero or more times
4859 + Matches preceding pattern one or more times
4861 ? Matches preceding pattern zero or once only
4863 | Matches a pattern on either side of the |
4865 () Saves a matched subexpression, which can be referenced in the
4867 REGEX REPLACE operation. Additionally it is saved by all regular
4868 expression-related commands, including e.g. if(MATCHES), in the
4869 variables CMAKE_MATCH_<n> for <n> 0..9.
4870 *, + and ? have higher precedence than concatenation. | has lower
4872 precedence than concatenation. This means that the regular expression
4873 ^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
4874 matches ab but not abd.
4875 CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
4877 to construct literal tabs, carriage returns, newlines, and backslashes
4878 (respectively) to pass in a regex. For example:
4879 · The quoted argument "[ \t\r\n]" specifies a regex that matches any
4881 single whitespace character.
4882 · The quoted argument "[/\\]" specifies a regex that matches a single
4884 forward slash / or backslash \.
4885 · The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
4887 single “word” character in the C locale.
4888 · The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
4890 the exact string (a+b). Each \\ is parsed in a quoted argument as
4891 just \, so the regex itself is actually \(\a\+\b\). This can alter‐
4892 natively be specified in a bracket argument without having to escape
4893 the backslashes, e.g. [[\(\a\+\b\)]].
4894 Manipulation
4896 string(APPEND <string_variable> [<input>...])
4897 Append all the <input> arguments to the string.
4899 string(PREPEND <string_variable> [<input>...])
4901 Prepend all the <input> arguments to the string.
4903 string(CONCAT <output_variable> [<input>...])
4905 Concatenate all the <input> arguments together and store the result in
4907 the named <output_variable>.
4908 string(JOIN <glue> <output_variable> [<input>...])
4910 Join all the <input> arguments together using the <glue> string and
4912 store the result in the named <output_variable>.
4913 To join a list’s elements, prefer to use the JOIN operator from the
4915 list() command. This allows for the elements to have special charac‐
4916 ters like ; in them.
4917 string(TOLOWER <string> <output_variable>)
4919 Convert <string> to lower characters.
4921 string(TOUPPER <string> <output_variable>)
4923 Convert <string> to upper characters.
4925 string(LENGTH <string> <output_variable>)
4927 Store in an <output_variable> a given string’s length in bytes. Note
4929 that this means if <string> contains multi-byte characters, the result
4930 stored in <output_variable> will not be the number of characters.
4931 string(SUBSTRING <string> <begin> <length> <output_variable>)
4933 Store in an <output_variable> a substring of a given <string>. If
4935 <length> is -1 the remainder of the string starting at <begin> will be
4936 returned. If <string> is shorter than <length> then the end of the
4937 string is used instead.
4938 Both <begin> and <length> are counted in bytes, so care must be exer‐
4940 cised if <string> could contain multi-byte characters.
4941 NOTE:
4943 CMake 3.1 and below reported an error if <length> pointed past the
4944 end of <string>.
4945 string(STRIP <string> <output_variable>)
4947 Store in an <output_variable> a substring of a given <string> with
4949 leading and trailing spaces removed.
4950 string(GENEX_STRIP <string> <output_variable>)
4952 Strip any generator expressions from the input <string> and store the
4954 result in the <output_variable>.
4955 string(REPEAT <string> <count> <output_variable>)
4957 Produce the output string as the input <string> repeated <count> times.
4959 Comparison
4961 string(COMPARE LESS <string1> <string2> <output_variable>)
4962 string(COMPARE GREATER <string1> <string2> <output_variable>)
4963 string(COMPARE EQUAL <string1> <string2> <output_variable>)
4964 string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
4965 string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
4966 string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
4967 Compare the strings and store true or false in the <output_variable>.
4969 Hashing
4971 string(<HASH> <output_variable> <input>)
4972 Compute a cryptographic hash of the <input> string. The supported
4974 <HASH> algorithm names are:
4975 MD5 Message-Digest Algorithm 5, RFC 1321.
4977 SHA1 US Secure Hash Algorithm 1, RFC 3174.
4979 SHA224 US Secure Hash Algorithms, RFC 4634.
4981 SHA256 US Secure Hash Algorithms, RFC 4634.
4983 SHA384 US Secure Hash Algorithms, RFC 4634.
4985 SHA512 US Secure Hash Algorithms, RFC 4634.
4987 SHA3_224
4989 Keccak SHA-3.
4990 SHA3_256
4992 Keccak SHA-3.
4993 SHA3_384
4995 Keccak SHA-3.
4996 SHA3_512
4998 Keccak SHA-3.
4999 Generation
5001 string(ASCII <number> [<number> ...] <output_variable>)
5002 Convert all numbers into corresponding ASCII characters.
5004 string(HEX <string> <output_variable>)
5006 Convert each byte in the input <string> to its hexadecimal representa‐
5008 tion and store the concatenated hex digits in the <output_variable>.
5009 Letters in the output (a through f) are in lowercase.
5010 string(CONFIGURE <string> <output_variable>
5012 [@ONLY] [ESCAPE_QUOTES])
5013 Transform a <string> like configure_file() transforms a file.
5015 string(MAKE_C_IDENTIFIER <string> <output_variable>)
5017 Convert each non-alphanumeric character in the input <string> to an
5019 underscore and store the result in the <output_variable>. If the first
5020 character of the <string> is a digit, an underscore will also be
5021 prepended to the result.
5022 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
5024 [RANDOM_SEED <seed>] <output_variable>)
5025 Return a random string of given <length> consisting of characters from
5027 the given <alphabet>. Default length is 5 characters and default
5028 alphabet is all numbers and upper and lower case letters. If an inte‐
5029 ger RANDOM_SEED is given, its value will be used to seed the random
5030 number generator.
5031 string(TIMESTAMP <output_variable> [<format_string>] [UTC])
5033 Write a string representation of the current date and/or time to the
5035 <output_variable>.
5036 If the command is unable to obtain a timestamp, the <output_variable>
5038 will be set to the empty string "".
5039 The optional UTC flag requests the current date/time representation to
5041 be in Coordinated Universal Time (UTC) rather than local time.
5042 The optional <format_string> may contain the following format speci‐
5044 fiers:
5045 %% A literal percent sign (%).
5047 %d The day of the current month (01-31).
5048 %H The hour on a 24-hour clock (00-23).
5049 %I The hour on a 12-hour clock (01-12).
5050 %j The day of the current year (001-366).
5051 %m The month of the current year (01-12).
5052 %b Abbreviated month name (e.g. Oct).
5053 %B Full month name (e.g. October).
5054 %M The minute of the current hour (00-59).
5055 %s Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
5056 %S The second of the current minute.
5057 60 represents a leap second. (00-60)
5058 %U The week number of the current year (00-53).
5059 %w The day of the current week. 0 is Sunday. (0-6)
5060 %a Abbreviated weekday name (e.g. Fri).
5061 %A Full weekday name (e.g. Friday).
5062 %y The last two digits of the current year (00-99)
5063 %Y The current year.
5064 Unknown format specifiers will be ignored and copied to the output
5066 as-is.
5067 If no explicit <format_string> is given, it will default to:
5069 %Y-%m-%dT%H:%M:%S for local time.
5071 %Y-%m-%dT%H:%M:%SZ for UTC.
5072 NOTE:
5074 If the SOURCE_DATE_EPOCH environment variable is set, its value will
5075 be used instead of the current time. See
5076 https://reproducible-builds.org/specs/source-date-epoch/ for
5077 details.
5078 string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
5080 TYPE <MD5|SHA1> [UPPER])
5081 Create a universally unique identifier (aka GUID) as per RFC4122 based
5083 on the hash of the combined values of <namespace> (which itself has to
5084 be a valid UUID) and <name>. The hash algorithm can be either MD5
5085 (Version 3 UUID) or SHA1 (Version 5 UUID). A UUID has the format
5086 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where each x represents a lower
5087 case hexadecimal character. Where required, an uppercase representa‐
5088 tion can be requested with the optional UPPER flag.
5089 JSON
5091 Functionality for querying a JSON string.
5092 NOTE:
5094 In each of the following JSON-related subcommands, if the optional
5095 ERROR_VARIABLE argument is given, errors will be reported in
5096 <error-variable> and the <out-var> will be set to <mem‐
5097 ber|index>-[<member|index>...]-NOTFOUND with the path elements up to
5098 the point where the error occurred, or just NOTFOUND if there is no
5099 relevant path. If an error occurs but the ERROR_VARIABLE option is
5100 not present, a fatal error message is generated. If no error
5101 occurs, the <error-variable> will be set to NOTFOUND.
5102 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
5104 GET <json-string> <member|index> [<member|index> ...])
5105 Get an element from <json-string> at the location given by the list of
5107 <member|index> arguments. Array and object elements will be returned
5108 as a JSON string. Boolean elements will be returned as ON or OFF.
5109 Null elements will be returned as an empty string. Number and string
5110 types will be returned as strings.
5111 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
5113 TYPE <json-string> <member|index> [<member|index> ...])
5114 Get the type of an element in <json-string> at the location given by
5116 the list of <member|index> arguments. The <out-var> will be set to one
5117 of NULL, NUMBER, STRING, BOOLEAN, ARRAY, or OBJECT.
5118 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
5120 MEMBER <json-string>
5121 [<member|index> ...] <index>)
5122 Get the name of the <index>-th member in <json-string> at the location
5124 given by the list of <member|index> arguments. Requires an element of
5125 object type.
5126 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
5128 LENGTH <json-string> <member|index> [<member|index> ...])
5129 Get the length of an element in <json-string> at the location given by
5131 the list of <member|index> arguments. Requires an element of array or
5132 object type.
5133 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
5135 REMOVE <json-string> <member|index> [<member|index> ...])
5136 Remove an element from <json-string> at the location given by the list
5138 of <member|index> arguments. The JSON string without the removed ele‐
5139 ment will be stored in <out-var>.
5140 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
5142 SET <json-string> <member|index> [<member|index> ...] <value>)
5143 Set an element in <json-string> at the location given by the list of
5145 <member|index> arguments to <value>. The contents of <value> should be
5146 valid JSON.
5147 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
5149 EQUAL <json-string1> <json-string2>)
5150 Compare the two JSON objects given by <json-string1> and <json-string2>
5152 for equality. The contents of <json-string1> and <json-string2> should
5153 be valid JSON. The <out-var> will be set to a true value if the JSON
5154 objects are considered equal, or a false value otherwise.
5155 unset
5157 Unset a variable, cache variable, or environment variable.
5158 Unset Normal Variable or Cache Entry
5160 unset(<variable> [CACHE | PARENT_SCOPE])
5161 Removes a normal variable from the current scope, causing it to become
5163 undefined. If CACHE is present, then a cache variable is removed
5164 instead of a normal variable. Note that when evaluating Variable Ref‐
5165 erences of the form ${VAR}, CMake first searches for a normal variable
5166 with that name. If no such normal variable exists, CMake will then
5167 search for a cache entry with that name. Because of this unsetting a
5168 normal variable can expose a cache variable that was previously hidden.
5169 To force a variable reference of the form ${VAR} to return an empty
5170 string, use set(<variable> ""), which clears the normal variable but
5171 leaves it defined.
5172 If PARENT_SCOPE is present then the variable is removed from the scope
5174 above the current scope. See the same option in the set() command for
5175 further details.
5176 Unset Environment Variable
5178 unset(ENV{<variable>})
5179 Removes <variable> from the currently available Environment Variables.
5181 Subsequent calls of $ENV{<variable>} will return the empty string.
5182 This command affects only the current CMake process, not the process
5184 from which CMake was called, nor the system environment at large, nor
5185 the environment of subsequent build or test processes.
5186 variable_watch
5188 Watch the CMake variable for change.
5189 variable_watch(<variable> [<command>])
5191 If the specified <variable> changes and no <command> is given, a mes‐
5193 sage will be printed to inform about the change.
5194 If <command> is given, this command will be executed instead. The com‐
5196 mand will receive the following arguments: COMMAND(<variable> <access>
5197 <value> <current_list_file> <stack>)
5198 <variable>
5200 Name of the variable being accessed.
5201 <access>
5203 One of READ_ACCESS, UNKNOWN_READ_ACCESS, MODIFIED_ACCESS,
5204 UNKNOWN_MODIFIED_ACCESS, or REMOVED_ACCESS. The UNKNOWN_ values
5205 are only used when the variable has never been set. Once set,
5206 they are never used again during the same CMake run, even if the
5207 variable is later unset.
5208 <value>
5210 The value of the variable. On a modification, this is the new
5211 (modified) value of the variable. On removal, the value is
5212 empty.
5213 <current_list_file>
5215 Full path to the file doing the access.
5216 <stack>
5218 List of absolute paths of all files currently on the stack of
5219 file inclusion, with the bottom-most file first and the cur‐
5220 rently processed file (that is, current_list_file) last.
5221 Note that for some accesses such as list(APPEND), the watcher is exe‐
5223 cuted twice, first with a read access and then with a write one. Also
5224 note that an if(DEFINED) query on the variable does not register as an
5225 access and the watcher is not executed.
5226 Only non-cache variables can be watched using this command. Access to
5228 cache variables is never watched. However, the existence of a cache
5229 variable var causes accesses to the non-cache variable var to not use
5230 the UNKNOWN_ prefix, even if a non-cache variable var has never
5231 existed.
5232 while
5234 Evaluate a group of commands while a condition is true
5235 while(<condition>)
5237 <commands>
5238 endwhile()
5239 All commands between while and the matching endwhile() are recorded
5241 without being invoked. Once the endwhile() is evaluated, the recorded
5242 list of commands is invoked as long as the <condition> is true.
5243 The <condition> has the same syntax and is evaluated using the same
5245 logic as described at length for the if() command.
5246 The commands break() and continue() provide means to escape from the
5248 normal control flow.
5249 Per legacy, the endwhile() command admits an optional <condition> argu‐
5251 ment. If used, it must be a verbatim repeat of the argument of the
5252 opening while command.
5253
5255 These commands are available only in CMake projects.
5256 add_compile_definitions
5258 New in version 3.12.
5259 Add preprocessor definitions to the compilation of source files.
5262 add_compile_definitions(<definition> ...)
5264 Adds preprocessor definitions to the compiler command line.
5266 The preprocessor definitions are added to the COMPILE_DEFINITIONS
5268 directory property for the current CMakeLists file. They are also added
5269 to the COMPILE_DEFINITIONS target property for each target in the cur‐
5270 rent CMakeLists file.
5271 Definitions are specified using the syntax VAR or VAR=value. Func‐
5273 tion-style definitions are not supported. CMake will automatically
5274 escape the value correctly for the native build system (note that CMake
5275 language syntax may require escapes to specify some values).
5276 Arguments to add_compile_definitions may use “generator expressions”
5278 with the syntax $<...>. See the cmake-generator-expressions(7) manual
5279 for available expressions. See the cmake-buildsystem(7) manual for
5280 more on defining buildsystem properties.
5281 add_compile_options
5283 Add options to the compilation of source files.
5284 add_compile_options(<option> ...)
5286 Adds options to the COMPILE_OPTIONS directory property. These options
5288 are used when compiling targets from the current directory and below.
5289 Arguments
5291 Arguments to add_compile_options may use “generator expressions” with
5292 the syntax $<...>. See the cmake-generator-expressions(7) manual for
5293 available expressions. See the cmake-buildsystem(7) manual for more on
5294 defining buildsystem properties.
5295 The final set of compile or link options used for a target is con‐
5297 structed by accumulating options from the current target and the usage
5298 requirements of its dependencies. The set of options is de-duplicated
5299 to avoid repetition. While beneficial for individual options, the
5300 de-duplication step can break up option groups. For example, -D A -D B
5301 becomes -D A B. One may specify a group of options using shell-like
5302 quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and
5303 the rest of the option string is parsed using the separate_arguments()
5304 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
5305 -D B.
5306 Example
5308 Since different compilers support different options, a typical use of
5309 this command is in a compiler-specific conditional clause:
5310 if (MSVC)
5312 # warning level 4 and all warnings as errors
5313 add_compile_options(/W4 /WX)
5314 else()
5315 # lots of warnings and all warnings as errors
5316 add_compile_options(-Wall -Wextra -pedantic -Werror)
5317 endif()
5318 See Also
5320 This command can be used to add any options. However, for adding pre‐
5321 processor definitions and include directories it is recommended to use
5322 the more specific commands add_compile_definitions() and include_direc‐
5323 tories().
5324 The command target_compile_options() adds target-specific options.
5326 The source file property COMPILE_OPTIONS adds options to one source
5328 file.
5329 add_custom_command
5331 Add a custom build rule to the generated build system.
5332 There are two main signatures for add_custom_command.
5334 Generating Files
5336 The first signature is for adding a custom command to produce an out‐
5337 put:
5338 add_custom_command(OUTPUT output1 [output2 ...]
5340 COMMAND command1 [ARGS] [args1...]
5341 [COMMAND command2 [ARGS] [args2...] ...]
5342 [MAIN_DEPENDENCY depend]
5343 [DEPENDS [depends...]]
5344 [BYPRODUCTS [files...]]
5345 [IMPLICIT_DEPENDS <lang1> depend1
5346 [<lang2> depend2] ...]
5347 [WORKING_DIRECTORY dir]
5348 [COMMENT comment]
5349 [DEPFILE depfile]
5350 [JOB_POOL job_pool]
5351 [VERBATIM] [APPEND] [USES_TERMINAL]
5352 [COMMAND_EXPAND_LISTS])
5353 This defines a command to generate specified OUTPUT file(s). A target
5355 created in the same directory (CMakeLists.txt file) that specifies any
5356 output of the custom command as a source file is given a rule to gener‐
5357 ate the file using the command at build time. Do not list the output
5358 in more than one independent target that may build in parallel or the
5359 two instances of the rule may conflict (instead use the add_custom_tar‐
5360 get() command to drive the command and make the other targets depend on
5361 that one). In makefile terms this creates a new target in the follow‐
5362 ing form:
5363 OUTPUT: MAIN_DEPENDENCY DEPENDS
5365 COMMAND
5366 The options are:
5368 APPEND Append the COMMAND and DEPENDS option values to the custom com‐
5370 mand for the first output specified. There must have already
5371 been a previous call to this command with the same output. The
5372 COMMENT, MAIN_DEPENDENCY, and WORKING_DIRECTORY options are cur‐
5373 rently ignored when APPEND is given, but may be used in the
5374 future.
5375 BYPRODUCTS
5377 Specify the files the command is expected to produce but whose
5378 modification time may or may not be newer than the dependencies.
5379 If a byproduct name is a relative path it will be interpreted
5380 relative to the build tree directory corresponding to the cur‐
5381 rent source directory. Each byproduct file will be marked with
5382 the GENERATED source file property automatically.
5383 Explicit specification of byproducts is supported by the Ninja
5385 generator to tell the ninja build tool how to regenerate byprod‐
5386 ucts when they are missing. It is also useful when other build
5387 rules (e.g. custom commands) depend on the byproducts. Ninja
5388 requires a build rule for any generated file on which another
5389 rule depends even if there are order-only dependencies to ensure
5390 the byproducts will be available before their dependents build.
5391 The Makefile Generators will remove BYPRODUCTS and other GENER‐
5393 ATED files during make clean.
5394 COMMAND
5396 Specify the command-line(s) to execute at build time. If more
5397 than one COMMAND is specified they will be executed in order,
5398 but not necessarily composed into a stateful shell or batch
5399 script. (To run a full script, use the configure_file() command
5400 or the file(GENERATE) command to create it, and then specify a
5401 COMMAND to launch it.) The optional ARGS argument is for back‐
5402 ward compatibility and will be ignored.
5403 If COMMAND specifies an executable target name (created by the
5405 add_executable() command), it will automatically be replaced by
5406 the location of the executable created at build time if either
5407 of the following is true:
5408 · The target is not being cross-compiled (i.e. the CMAKE_CROSS‐
5410 COMPILING variable is not set to true).
5411 · The target is being cross-compiled and an emulator is provided
5413 (i.e. its CROSSCOMPILING_EMULATOR target property is set).
5414 In this case, the contents of CROSSCOMPILING_EMULATOR will be
5415 prepended to the command before the location of the target
5416 executable.
5417 If neither of the above conditions are met, it is assumed that
5419 the command name is a program to be found on the PATH at build
5420 time.
5421 Arguments to COMMAND may use generator expressions. Use the
5423 TARGET_FILE generator expression to refer to the location of a
5424 target later in the command line (i.e. as a command argument
5425 rather than as the command to execute).
5426 Whenever one of the following target based generator expressions
5428 are used as a command to execute or is mentioned in a command
5429 argument, a target-level dependency will be added automatically
5430 so that the mentioned target will be built before any target
5431 using this custom command (see policy CMP0112).
5432 · TARGET_FILE
5434 · TARGET_LINKER_FILE
5436 · TARGET_SONAME_FILE
5438 · TARGET_PDB_FILE
5440 This target-level dependency does NOT add a file-level depen‐
5442 dency that would cause the custom command to re-run whenever the
5443 executable is recompiled. List target names with the DEPENDS
5444 option to add such file-level dependencies.
5445 COMMENT
5447 Display the given message before the commands are executed at
5448 build time.
5449 DEPENDS
5451 Specify files on which the command depends. Each argument is
5452 converted to a dependency as follows:
5453 1. If the argument is the name of a target (created by the
5455 add_custom_target(), add_executable(), or add_library() com‐
5456 mand) a target-level dependency is created to make sure the
5457 target is built before any target using this custom command.
5458 Additionally, if the target is an executable or library, a
5459 file-level dependency is created to cause the custom command
5460 to re-run whenever the target is recompiled.
5461 2. If the argument is an absolute path, a file-level dependency
5463 is created on that path.
5464 3. If the argument is the name of a source file that has been
5466 added to a target or on which a source file property has been
5467 set, a file-level dependency is created on that source file.
5468 4. If the argument is a relative path and it exists in the cur‐
5470 rent source directory, a file-level dependency is created on
5471 that file in the current source directory.
5472 5. Otherwise, a file-level dependency is created on that path
5474 relative to the current binary directory.
5475 If any dependency is an OUTPUT of another custom command in the
5477 same directory (CMakeLists.txt file), CMake automatically brings
5478 the other custom command into the target in which this command
5479 is built. A target-level dependency is added if any dependency
5480 is listed as BYPRODUCTS of a target or any of its build events
5481 in the same directory to ensure the byproducts will be avail‐
5482 able.
5483 If DEPENDS is not specified, the command will run whenever the
5485 OUTPUT is missing; if the command does not actually create the
5486 OUTPUT, the rule will always run.
5487 Arguments to DEPENDS may use generator expressions.
5489 COMMAND_EXPAND_LISTS
5491 Lists in COMMAND arguments will be expanded, including those
5492 created with generator expressions, allowing COMMAND arguments
5493 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
5494 RIES>,;-I>" foo.cc to be properly expanded.
5495 IMPLICIT_DEPENDS
5497 Request scanning of implicit dependencies of an input file. The
5498 language given specifies the programming language whose corre‐
5499 sponding dependency scanner should be used. Currently only C
5500 and CXX language scanners are supported. The language has to be
5501 specified for every file in the IMPLICIT_DEPENDS list. Depen‐
5502 dencies discovered from the scanning are added to those of the
5503 custom command at build time. Note that the IMPLICIT_DEPENDS
5504 option is currently supported only for Makefile generators and
5505 will be ignored by other generators.
5506 JOB_POOL
5508 Specify a pool for the Ninja generator. Incompatible with
5509 USES_TERMINAL, which implies the console pool. Using a pool
5510 that is not defined by JOB_POOLS causes an error by ninja at
5511 build time.
5512 MAIN_DEPENDENCY
5514 Specify the primary input source file to the command. This is
5515 treated just like any value given to the DEPENDS option but also
5516 suggests to Visual Studio generators where to hang the custom
5517 command. Each source file may have at most one command specify‐
5518 ing it as its main dependency. A compile command (i.e. for a
5519 library or an executable) counts as an implicit main dependency
5520 which gets silently overwritten by a custom command specifica‐
5521 tion.
5522 OUTPUT Specify the output files the command is expected to produce. If
5524 an output name is a relative path it will be interpreted rela‐
5525 tive to the build tree directory corresponding to the current
5526 source directory. Each output file will be marked with the GEN‐
5527 ERATED source file property automatically. If the output of the
5528 custom command is not actually created as a file on disk it
5529 should be marked with the SYMBOLIC source file property.
5530 USES_TERMINAL
5532 The command will be given direct access to the terminal if pos‐
5533 sible. With the Ninja generator, this places the command in the
5534 console pool.
5535 VERBATIM
5537 All arguments to the commands will be escaped properly for the
5538 build tool so that the invoked command receives each argument
5539 unchanged. Note that one level of escapes is still used by the
5540 CMake language processor before add_custom_command even sees the
5541 arguments. Use of VERBATIM is recommended as it enables correct
5542 behavior. When VERBATIM is not given the behavior is platform
5543 specific because there is no protection of tool-specific special
5544 characters.
5545 WORKING_DIRECTORY
5547 Execute the command with the given current working directory.
5548 If it is a relative path it will be interpreted relative to the
5549 build tree directory corresponding to the current source direc‐
5550 tory.
5551 Arguments to WORKING_DIRECTORY may use generator expressions.
5553 DEPFILE
5555 Specify a .d depfile for the Ninja generator. A .d file holds
5556 dependencies usually emitted by the custom command itself.
5557 Using DEPFILE with other generators than Ninja is an error.
5558 Build Events
5560 The second signature adds a custom command to a target such as a
5561 library or executable. This is useful for performing an operation
5562 before or after building the target. The command becomes part of the
5563 target and will only execute when the target itself is built. If the
5564 target is already built, the command will not execute.
5565 add_custom_command(TARGET <target>
5567 PRE_BUILD | PRE_LINK | POST_BUILD
5568 COMMAND command1 [ARGS] [args1...]
5569 [COMMAND command2 [ARGS] [args2...] ...]
5570 [BYPRODUCTS [files...]]
5571 [WORKING_DIRECTORY dir]
5572 [COMMENT comment]
5573 [VERBATIM] [USES_TERMINAL]
5574 [COMMAND_EXPAND_LISTS])
5575 This defines a new command that will be associated with building the
5577 specified <target>. The <target> must be defined in the current direc‐
5578 tory; targets defined in other directories may not be specified.
5579 When the command will happen is determined by which of the following is
5581 specified:
5582 PRE_BUILD
5584 On Visual Studio Generators, run before any other rules are exe‐
5585 cuted within the target. On other generators, run just before
5586 PRE_LINK commands.
5587 PRE_LINK
5589 Run after sources have been compiled but before linking the
5590 binary or running the librarian or archiver tool of a static
5591 library. This is not defined for targets created by the
5592 add_custom_target() command.
5593 POST_BUILD
5595 Run after all other rules within the target have been executed.
5596 NOTE:
5598 Because generator expressions can be used in custom commands, it is
5599 possible to define COMMAND lines or whole custom commands which
5600 evaluate to empty strings for certain configurations. For Visual
5601 Studio 2010 (and newer) generators these command lines or custom
5602 commands will be omitted for the specific configuration and no
5603 “empty-string-command” will be added.
5604 This allows to add individual build events for every configuration.
5606 add_custom_target
5608 Add a target with no output so it will always be built.
5609 add_custom_target(Name [ALL] [command1 [args1...]]
5611 [COMMAND command2 [args2...] ...]
5612 [DEPENDS depend depend depend ... ]
5613 [BYPRODUCTS [files...]]
5614 [WORKING_DIRECTORY dir]
5615 [COMMENT comment]
5616 [JOB_POOL job_pool]
5617 [VERBATIM] [USES_TERMINAL]
5618 [COMMAND_EXPAND_LISTS]
5619 [SOURCES src1 [src2...]])
5620 Adds a target with the given name that executes the given commands.
5622 The target has no output file and is always considered out of date even
5623 if the commands try to create a file with the name of the target. Use
5624 the add_custom_command() command to generate a file with dependencies.
5625 By default nothing depends on the custom target. Use the add_dependen‐
5626 cies() command to add dependencies to or from other targets.
5627 The options are:
5629 ALL Indicate that this target should be added to the default build
5631 target so that it will be run every time (the command cannot be
5632 called ALL).
5633 BYPRODUCTS
5635 Specify the files the command is expected to produce but whose
5636 modification time may or may not be updated on subsequent
5637 builds. If a byproduct name is a relative path it will be
5638 interpreted relative to the build tree directory corresponding
5639 to the current source directory. Each byproduct file will be
5640 marked with the GENERATED source file property automatically.
5641 Explicit specification of byproducts is supported by the Ninja
5643 generator to tell the ninja build tool how to regenerate byprod‐
5644 ucts when they are missing. It is also useful when other build
5645 rules (e.g. custom commands) depend on the byproducts. Ninja
5646 requires a build rule for any generated file on which another
5647 rule depends even if there are order-only dependencies to ensure
5648 the byproducts will be available before their dependents build.
5649 The Makefile Generators will remove BYPRODUCTS and other GENER‐
5651 ATED files during make clean.
5652 COMMAND
5654 Specify the command-line(s) to execute at build time. If more
5655 than one COMMAND is specified they will be executed in order,
5656 but not necessarily composed into a stateful shell or batch
5657 script. (To run a full script, use the configure_file() command
5658 or the file(GENERATE) command to create it, and then specify a
5659 COMMAND to launch it.)
5660 If COMMAND specifies an executable target name (created by the
5662 add_executable() command), it will automatically be replaced by
5663 the location of the executable created at build time if either
5664 of the following is true:
5665 · The target is not being cross-compiled (i.e. the CMAKE_CROSS‐
5667 COMPILING variable is not set to true).
5668 · The target is being cross-compiled and an emulator is provided
5670 (i.e. its CROSSCOMPILING_EMULATOR target property is set).
5671 In this case, the contents of CROSSCOMPILING_EMULATOR will be
5672 prepended to the command before the location of the target
5673 executable.
5674 If neither of the above conditions are met, it is assumed that
5676 the command name is a program to be found on the PATH at build
5677 time.
5678 Arguments to COMMAND may use generator expressions. Use the
5680 TARGET_FILE generator expression to refer to the location of a
5681 target later in the command line (i.e. as a command argument
5682 rather than as the command to execute).
5683 Whenever one of the following target based generator expressions
5685 are used as a command to execute or is mentioned in a command
5686 argument, a target-level dependency will be added automatically
5687 so that the mentioned target will be built before this custom
5688 target (see policy CMP0112).
5689 · TARGET_FILE
5691 · TARGET_LINKER_FILE
5693 · TARGET_SONAME_FILE
5695 · TARGET_PDB_FILE
5697 The command and arguments are optional and if not specified an
5699 empty target will be created.
5700 COMMENT
5702 Display the given message before the commands are executed at
5703 build time.
5704 DEPENDS
5706 Reference files and outputs of custom commands created with
5707 add_custom_command() command calls in the same directory (CMake‐
5708 Lists.txt file). They will be brought up to date when the tar‐
5709 get is built. A target-level dependency is added if any depen‐
5710 dency is a byproduct of a target or any of its build events in
5711 the same directory to ensure the byproducts will be available
5712 before this target is built.
5713 Use the add_dependencies() command to add dependencies on other
5715 targets.
5716 COMMAND_EXPAND_LISTS
5718 Lists in COMMAND arguments will be expanded, including those
5719 created with generator expressions, allowing COMMAND arguments
5720 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
5721 RIES>,;-I>" foo.cc to be properly expanded.
5722 JOB_POOL
5724 Specify a pool for the Ninja generator. Incompatible with
5725 USES_TERMINAL, which implies the console pool. Using a pool
5726 that is not defined by JOB_POOLS causes an error by ninja at
5727 build time.
5728 SOURCES
5730 Specify additional source files to be included in the custom
5731 target. Specified source files will be added to IDE project
5732 files for convenience in editing even if they have no build
5733 rules.
5734 VERBATIM
5736 All arguments to the commands will be escaped properly for the
5737 build tool so that the invoked command receives each argument
5738 unchanged. Note that one level of escapes is still used by the
5739 CMake language processor before add_custom_target even sees the
5740 arguments. Use of VERBATIM is recommended as it enables correct
5741 behavior. When VERBATIM is not given the behavior is platform
5742 specific because there is no protection of tool-specific special
5743 characters.
5744 USES_TERMINAL
5746 The command will be given direct access to the terminal if pos‐
5747 sible. With the Ninja generator, this places the command in the
5748 console pool.
5749 WORKING_DIRECTORY
5751 Execute the command with the given current working directory.
5752 If it is a relative path it will be interpreted relative to the
5753 build tree directory corresponding to the current source direc‐
5754 tory.
5755 Arguments to WORKING_DIRECTORY may use generator expressions.
5757 add_definitions
5759 Add -D define flags to the compilation of source files.
5760 add_definitions(-DFOO -DBAR ...)
5762 Adds definitions to the compiler command line for targets in the cur‐
5764 rent directory, whether added before or after this command is invoked,
5765 and for the ones in sub-directories added after. This command can be
5766 used to add any flags, but it is intended to add preprocessor defini‐
5767 tions.
5768 NOTE:
5770 This command has been superseded by alternatives:
5771 · Use add_compile_definitions() to add preprocessor definitions.
5773 · Use include_directories() to add include directories.
5775 · Use add_compile_options() to add other options.
5777 Flags beginning in -D or /D that look like preprocessor definitions are
5779 automatically added to the COMPILE_DEFINITIONS directory property for
5780 the current directory. Definitions with non-trivial values may be left
5781 in the set of flags instead of being converted for reasons of backwards
5782 compatibility. See documentation of the directory, target, source file
5783 COMPILE_DEFINITIONS properties for details on adding preprocessor defi‐
5784 nitions to specific scopes and configurations.
5785 See the cmake-buildsystem(7) manual for more on defining buildsystem
5787 properties.
5788 add_dependencies
5790 Add a dependency between top-level targets.
5791 add_dependencies(<target> [<target-dependency>]...)
5793 Makes a top-level <target> depend on other top-level targets to ensure
5795 that they build before <target> does. A top-level target is one cre‐
5796 ated by one of the add_executable(), add_library(), or add_custom_tar‐
5797 get() commands (but not targets generated by CMake like install).
5798 Dependencies added to an imported target or an interface library are
5800 followed transitively in its place since the target itself does not
5801 build.
5802 See the DEPENDS option of add_custom_target() and add_custom_command()
5804 commands for adding file-level dependencies in custom rules. See the
5805 OBJECT_DEPENDS source file property to add file-level dependencies to
5806 object files.
5807 add_executable
5809 Add an executable to the project using the specified source files.
5810 Normal Executables
5812 add_executable(<name> [WIN32] [MACOSX_BUNDLE]
5813 [EXCLUDE_FROM_ALL]
5814 [source1] [source2 ...])
5815 Adds an executable target called <name> to be built from the source
5817 files listed in the command invocation. (The source files can be omit‐
5818 ted here if they are added later using target_sources().) The <name>
5819 corresponds to the logical target name and must be globally unique
5820 within a project. The actual file name of the executable built is con‐
5821 structed based on conventions of the native platform (such as
5822 <name>.exe or just <name>).
5823 By default the executable file will be created in the build tree direc‐
5825 tory corresponding to the source tree directory in which the command
5826 was invoked. See documentation of the RUNTIME_OUTPUT_DIRECTORY target
5827 property to change this location. See documentation of the OUTPUT_NAME
5828 target property to change the <name> part of the final file name.
5829 If WIN32 is given the property WIN32_EXECUTABLE will be set on the tar‐
5831 get created. See documentation of that target property for details.
5832 If MACOSX_BUNDLE is given the corresponding property will be set on the
5834 created target. See documentation of the MACOSX_BUNDLE target property
5835 for details.
5836 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
5838 the created target. See documentation of the EXCLUDE_FROM_ALL target
5839 property for details.
5840 Source arguments to add_executable may use “generator expressions” with
5842 the syntax $<...>. See the cmake-generator-expressions(7) manual for
5843 available expressions. See the cmake-buildsystem(7) manual for more on
5844 defining buildsystem properties.
5845 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
5847 cessed, and you want to have the original sources reachable from within
5848 IDE.
5849 Imported Executables
5851 add_executable(<name> IMPORTED [GLOBAL])
5852 An IMPORTED executable target references an executable file located
5854 outside the project. No rules are generated to build it, and the
5855 IMPORTED target property is True. The target name has scope in the
5856 directory in which it is created and below, but the GLOBAL option
5857 extends visibility. It may be referenced like any target built within
5858 the project. IMPORTED executables are useful for convenient reference
5859 from commands like add_custom_command(). Details about the imported
5860 executable are specified by setting properties whose names begin in
5861 IMPORTED_. The most important such property is IMPORTED_LOCATION (and
5862 its per-configuration version IMPORTED_LOCATION_<CONFIG>) which speci‐
5863 fies the location of the main executable file on disk. See documenta‐
5864 tion of the IMPORTED_* properties for more information.
5865 Alias Executables
5867 add_executable(<name> ALIAS <target>)
5868 Creates an Alias Target, such that <name> can be used to refer to <tar‐
5870 get> in subsequent commands. The <name> does not appear in the gener‐
5871 ated buildsystem as a make target. The <target> may not be an ALIAS.
5872 An ALIAS to a non-GLOBAL Imported Target has scope in the directory in
5874 which the alias is created and below. The ALIAS_GLOBAL target property
5875 can be used to check if the alias is global or not.
5876 ALIAS targets can be used as targets to read properties from, executa‐
5878 bles for custom commands and custom targets. They can also be tested
5879 for existence with the regular if(TARGET) subcommand. The <name> may
5880 not be used to modify properties of <target>, that is, it may not be
5881 used as the operand of set_property(), set_target_properties(), tar‐
5882 get_link_libraries() etc. An ALIAS target may not be installed or
5883 exported.
5884 add_library
5886 Add a library to the project using the specified source files.
5887 Normal Libraries
5889 add_library(<name> [STATIC | SHARED | MODULE]
5890 [EXCLUDE_FROM_ALL]
5891 [<source>...])
5892 Adds a library target called <name> to be built from the source files
5894 listed in the command invocation. (The source files can be omitted
5895 here if they are added later using target_sources().) The <name> cor‐
5896 responds to the logical target name and must be globally unique within
5897 a project. The actual file name of the library built is constructed
5898 based on conventions of the native platform (such as lib<name>.a or
5899 <name>.lib).
5900 STATIC, SHARED, or MODULE may be given to specify the type of library
5902 to be created. STATIC libraries are archives of object files for use
5903 when linking other targets. SHARED libraries are linked dynamically
5904 and loaded at runtime. MODULE libraries are plugins that are not
5905 linked into other targets but may be loaded dynamically at runtime
5906 using dlopen-like functionality. If no type is given explicitly the
5907 type is STATIC or SHARED based on whether the current value of the
5908 variable BUILD_SHARED_LIBS is ON. For SHARED and MODULE libraries the
5909 POSITION_INDEPENDENT_CODE target property is set to ON automatically.
5910 A SHARED or STATIC library may be marked with the FRAMEWORK target
5911 property to create an macOS Framework.
5912 If a library does not export any symbols, it must not be declared as a
5914 SHARED library. For example, a Windows resource DLL or a managed
5915 C++/CLI DLL that exports no unmanaged symbols would need to be a MODULE
5916 library. This is because CMake expects a SHARED library to always have
5917 an associated import library on Windows.
5918 By default the library file will be created in the build tree directory
5920 corresponding to the source tree directory in which the command was
5921 invoked. See documentation of the ARCHIVE_OUTPUT_DIRECTORY,
5922 LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY target proper‐
5923 ties to change this location. See documentation of the OUTPUT_NAME
5924 target property to change the <name> part of the final file name.
5925 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
5927 the created target. See documentation of the EXCLUDE_FROM_ALL target
5928 property for details.
5929 Source arguments to add_library may use “generator expressions” with
5931 the syntax $<...>. See the cmake-generator-expressions(7) manual for
5932 available expressions. See the cmake-buildsystem(7) manual for more on
5933 defining buildsystem properties.
5934 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
5936 cessed, and you want to have the original sources reachable from within
5937 IDE.
5938 Object Libraries
5940 add_library(<name> OBJECT [<source>...])
5941 Creates an Object Library. An object library compiles source files but
5943 does not archive or link their object files into a library. Instead
5944 other targets created by add_library() or add_executable() may refer‐
5945 ence the objects using an expression of the form $<TAR‐
5946 GET_OBJECTS:objlib> as a source, where objlib is the object library
5947 name. For example:
5948 add_library(... $<TARGET_OBJECTS:objlib> ...)
5950 add_executable(... $<TARGET_OBJECTS:objlib> ...)
5951 will include objlib’s object files in a library and an executable along
5953 with those compiled from their own sources. Object libraries may con‐
5954 tain only sources that compile, header files, and other files that
5955 would not affect linking of a normal library (e.g. .txt). They may
5956 contain custom commands generating such sources, but not PRE_BUILD,
5957 PRE_LINK, or POST_BUILD commands. Some native build systems (such as
5958 Xcode) may not like targets that have only object files, so consider
5959 adding at least one real source file to any target that references
5960 $<TARGET_OBJECTS:objlib>.
5961 Interface Libraries
5963 add_library(<name> INTERFACE)
5964 Creates an Interface Library. An INTERFACE library target does not
5966 compile sources and does not produce a library artifact on disk. How‐
5967 ever, it may have properties set on it and it may be installed and
5968 exported. Typically, INTERFACE_* properties are populated on an inter‐
5969 face target using the commands:
5970 · set_property(),
5972 · target_link_libraries(INTERFACE),
5974 · target_link_options(INTERFACE),
5976 · target_include_directories(INTERFACE),
5978 · target_compile_options(INTERFACE),
5980 · target_compile_definitions(INTERFACE), and
5982 · target_sources(INTERFACE),
5984 and then it is used as an argument to target_link_libraries() like any
5986 other target.
5987 An interface library created with the above signature has no source
5989 files itself and is not included as a target in the generated buildsys‐
5990 tem.
5991 Since CMake 3.19, an interface library target may be created with
5993 source files:
5994 add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])
5996 Source files may be listed directly in the add_library call or added
5998 later by calls to target_sources() with the PRIVATE or PUBLIC keywords.
5999 If an interface library has source files (i.e. the SOURCES target prop‐
6001 erty is set), it will appear in the generated buildsystem as a build
6002 target much like a target defined by the add_custom_target() command.
6003 It does not compile any sources, but does contain build rules for cus‐
6004 tom commands created by the add_custom_command() command.
6005 NOTE:
6007 In most command signatures where the INTERFACE keyword appears, the
6008 items listed after it only become part of that target’s usage
6009 requirements and are not part of the target’s own settings. How‐
6010 ever, in this signature of add_library, the INTERFACE keyword refers
6011 to the library type only. Sources listed after it in the
6012 add_library call are PRIVATE to the interface library and do not
6013 appear in its INTERFACE_SOURCES target property.
6014 Imported Libraries
6016 add_library(<name> <type> IMPORTED [GLOBAL])
6017 Creates an IMPORTED library target called <name>. No rules are gener‐
6019 ated to build it, and the IMPORTED target property is True. The target
6020 name has scope in the directory in which it is created and below, but
6021 the GLOBAL option extends visibility. It may be referenced like any
6022 target built within the project. IMPORTED libraries are useful for
6023 convenient reference from commands like target_link_libraries().
6024 Details about the imported library are specified by setting properties
6025 whose names begin in IMPORTED_ and INTERFACE_.
6026 The <type> must be one of:
6028 STATIC, SHARED, MODULE, UNKNOWN
6030 References a library file located outside the project. The
6031 IMPORTED_LOCATION target property (or its per-configuration
6032 variant IMPORTED_LOCATION_<CONFIG>) specifies the location of
6033 the main library file on disk. In the case of a SHARED library
6034 on Windows, the IMPORTED_IMPLIB target property (or its per-con‐
6035 figuration variant IMPORTED_IMPLIB_<CONFIG>) specifies the loca‐
6036 tion of the DLL import library file (.lib or .dll.a) on disk,
6037 and the IMPORTED_LOCATION is the location of the .dll runtime
6038 library (and is optional). Additional usage requirements may be
6039 specified in INTERFACE_* properties.
6040 An UNKNOWN library type is typically only used in the implemen‐
6042 tation of Find Modules. It allows the path to an imported
6043 library (often found using the find_library() command) to be
6044 used without having to know what type of library it is. This is
6045 especially useful on Windows where a static library and a DLL’s
6046 import library both have the same file extension.
6047 OBJECT References a set of object files located outside the project.
6049 The IMPORTED_OBJECTS target property (or its per-configuration
6050 variant IMPORTED_OBJECTS_<CONFIG>) specifies the locations of
6051 object files on disk. Additional usage requirements may be
6052 specified in INTERFACE_* properties.
6053 INTERFACE
6055 Does not reference any library or object files on disk, but may
6056 specify usage requirements in INTERFACE_* properties.
6057 See documentation of the IMPORTED_* and INTERFACE_* properties for more
6059 information.
6060 Alias Libraries
6062 add_library(<name> ALIAS <target>)
6063 Creates an Alias Target, such that <name> can be used to refer to <tar‐
6065 get> in subsequent commands. The <name> does not appear in the gener‐
6066 ated buildsystem as a make target. The <target> may not be an ALIAS.
6067 An ALIAS to a non-GLOBAL Imported Target has scope in the directory in
6069 which the alias is created and below. The ALIAS_GLOBAL target property
6070 can be used to check if the alias is global or not.
6071 ALIAS targets can be used as linkable targets and as targets to read
6073 properties from. They can also be tested for existence with the regu‐
6074 lar if(TARGET) subcommand. The <name> may not be used to modify prop‐
6075 erties of <target>, that is, it may not be used as the operand of
6076 set_property(), set_target_properties(), target_link_libraries() etc.
6077 An ALIAS target may not be installed or exported.
6078 add_link_options
6080 New in version 3.13.
6081 Add options to the link step for executable, shared library or module
6084 library targets in the current directory and below that are added after
6085 this command is invoked.
6086 add_link_options(<option> ...)
6088 This command can be used to add any link options, but alternative com‐
6090 mands exist to add libraries (target_link_libraries() or
6091 link_libraries()). See documentation of the directory and target
6092 LINK_OPTIONS properties.
6093 NOTE:
6095 This command cannot be used to add options for static library tar‐
6096 gets, since they do not use a linker. To add archiver or MSVC
6097 librarian flags, see the STATIC_LIBRARY_OPTIONS target property.
6098 Arguments to add_link_options may use “generator expressions” with the
6100 syntax $<...>. See the cmake-generator-expressions(7) manual for
6101 available expressions. See the cmake-buildsystem(7) manual for more on
6102 defining buildsystem properties.
6103 When a device link step is involved, which is controlled by CUDA_SEPA‐
6105 RABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS properties and policy
6106 CMP0105, the raw options will be delivered to the host and device link
6107 steps (wrapped in -Xcompiler or equivalent for device link). Options
6108 wrapped with $<DEVICE_LINK:...> generator expression will be used only
6109 for the device link step. Options wrapped with $<HOST_LINK:...> genera‐
6110 tor expression will be used only for the host link step.
6111 The final set of compile or link options used for a target is con‐
6113 structed by accumulating options from the current target and the usage
6114 requirements of its dependencies. The set of options is de-duplicated
6115 to avoid repetition. While beneficial for individual options, the
6116 de-duplication step can break up option groups. For example, -D A -D B
6117 becomes -D A B. One may specify a group of options using shell-like
6118 quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and
6119 the rest of the option string is parsed using the separate_arguments()
6120 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
6121 -D B.
6122 To pass options to the linker tool, each compiler driver has its own
6124 syntax. The LINKER: prefix and , separator can be used to specify, in
6125 a portable way, options to pass to the linker tool. LINKER: is replaced
6126 by the appropriate driver option and , by the appropriate driver sepa‐
6127 rator. The driver prefix and driver separator are given by the values
6128 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAP‐
6129 PER_FLAG_SEP variables.
6130 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
6132 Clang and -Wl,-z,defs for GNU GCC.
6133 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
6135 sion.
6136 The LINKER: prefix supports, as an alternative syntax, specification of
6138 arguments using the SHELL: prefix and space as separator. The previous
6139 example then becomes "LINKER:SHELL:-z defs".
6140 NOTE:
6142 Specifying the SHELL: prefix anywhere other than at the beginning of
6143 the LINKER: prefix is not supported.
6144 add_subdirectory
6146 Add a subdirectory to the build.
6147 add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
6149 Adds a subdirectory to the build. The source_dir specifies the direc‐
6151 tory in which the source CMakeLists.txt and code files are located. If
6152 it is a relative path it will be evaluated with respect to the current
6153 directory (the typical usage), but it may also be an absolute path.
6154 The binary_dir specifies the directory in which to place the output
6155 files. If it is a relative path it will be evaluated with respect to
6156 the current output directory, but it may also be an absolute path. If
6157 binary_dir is not specified, the value of source_dir, before expanding
6158 any relative path, will be used (the typical usage). The CMake‐
6159 Lists.txt file in the specified source directory will be processed
6160 immediately by CMake before processing in the current input file con‐
6161 tinues beyond this command.
6162 If the EXCLUDE_FROM_ALL argument is provided then targets in the subdi‐
6164 rectory will not be included in the ALL target of the parent directory
6165 by default, and will be excluded from IDE project files. Users must
6166 explicitly build targets in the subdirectory. This is meant for use
6167 when the subdirectory contains a separate part of the project that is
6168 useful but not necessary, such as a set of examples. Typically the
6169 subdirectory should contain its own project() command invocation so
6170 that a full build system will be generated in the subdirectory (such as
6171 a VS IDE solution file). Note that inter-target dependencies supersede
6172 this exclusion. If a target built by the parent project depends on a
6173 target in the subdirectory, the dependee target will be included in the
6174 parent project build system to satisfy the dependency.
6175 add_test
6177 Add a test to the project to be run by ctest(1).
6178 add_test(NAME <name> COMMAND <command> [<arg>...]
6180 [CONFIGURATIONS <config>...]
6181 [WORKING_DIRECTORY <dir>]
6182 [COMMAND_EXPAND_LISTS])
6183 Adds a test called <name>. The test name may contain arbitrary charac‐
6185 ters, expressed as a Quoted Argument or Bracket Argument if necessary.
6186 See policy CMP0110. The options are:
6187 COMMAND
6189 Specify the test command-line. If <command> specifies an exe‐
6190 cutable target (created by add_executable()) it will automati‐
6191 cally be replaced by the location of the executable created at
6192 build time.
6193 CONFIGURATIONS
6195 Restrict execution of the test only to the named configurations.
6196 WORKING_DIRECTORY
6198 Set the WORKING_DIRECTORY test property to specify the working
6199 directory in which to execute the test. If not specified the
6200 test will be run with the current working directory set to the
6201 build directory corresponding to the current source directory.
6202 COMMAND_EXPAND_LISTS
6204 Lists in COMMAND arguments will be expanded, including those
6205 created with generator expressions.
6206 The given test command is expected to exit with code 0 to pass and
6208 non-zero to fail, or vice-versa if the WILL_FAIL test property is set.
6209 Any output written to stdout or stderr will be captured by ctest(1) but
6210 does not affect the pass/fail status unless the PASS_REGULAR_EXPRES‐
6211 SION, FAIL_REGULAR_EXPRESSION or SKIP_REGULAR_EXPRESSION test property
6212 is used.
6213 The COMMAND and WORKING_DIRECTORY options may use “generator expres‐
6215 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
6216 manual for available expressions.
6217 Example usage:
6219 add_test(NAME mytest
6221 COMMAND testDriver --config $<CONFIGURATION>
6222 --exe $<TARGET_FILE:myexe>)
6223 This creates a test mytest whose command runs a testDriver tool passing
6225 the configuration name and the full path to the executable file pro‐
6226 duced by target myexe.
6227 NOTE:
6229 CMake will generate tests only if the enable_testing() command has
6230 been invoked. The CTest module invokes the command automatically
6231 unless the BUILD_TESTING option is turned OFF.
6232 ----
6235 add_test(<name> <command> [<arg>...])
6239 Add a test called <name> with the given command-line. Unlike the above
6241 NAME signature no transformation is performed on the command-line to
6242 support target names or generator expressions.
6243 aux_source_directory
6245 Find all source files in a directory.
6246 aux_source_directory(<dir> <variable>)
6248 Collects the names of all the source files in the specified directory
6250 and stores the list in the <variable> provided. This command is
6251 intended to be used by projects that use explicit template instantia‐
6252 tion. Template instantiation files can be stored in a Templates subdi‐
6253 rectory and collected automatically using this command to avoid manu‐
6254 ally listing all instantiations.
6255 It is tempting to use this command to avoid writing the list of source
6257 files for a library or executable target. While this seems to work,
6258 there is no way for CMake to generate a build system that knows when a
6259 new source file has been added. Normally the generated build system
6260 knows when it needs to rerun CMake because the CMakeLists.txt file is
6261 modified to add a new source. When the source is just added to the
6262 directory without modifying this file, one would have to manually rerun
6263 CMake to generate a build system incorporating the new file.
6264 build_command
6266 Get a command line to build the current project. This is mainly
6267 intended for internal use by the CTest module.
6268 build_command(<variable>
6270 [CONFIGURATION <config>]
6271 [TARGET <target>]
6272 [PROJECT_NAME <projname>] # legacy, causes warning
6273 )
6274 Sets the given <variable> to a command-line string of the form:
6276 <cmake> --build . [--config <config>] [--target <target>...] [-- -i]
6278 where <cmake> is the location of the cmake(1) command-line tool, and
6280 <config> and <target> are the values provided to the CONFIGURATION and
6281 TARGET options, if any. The trailing -- -i option is added for Make‐
6282 file Generators if policy CMP0061 is not set to NEW.
6283 When invoked, this cmake --build command line will launch the underly‐
6285 ing build system tool.
6286 build_command(<cachevariable> <makecommand>)
6288 This second signature is deprecated, but still available for backwards
6290 compatibility. Use the first signature instead.
6291 It sets the given <cachevariable> to a command-line string as above but
6293 without the --target option. The <makecommand> is ignored but should
6294 be the full path to devenv, nmake, make or one of the end user build
6295 tools for legacy invocations.
6296 NOTE:
6298 In CMake versions prior to 3.0 this command returned a command line
6299 that directly invokes the native build tool for the current genera‐
6300 tor. Their implementation of the PROJECT_NAME option had no useful
6301 effects, so CMake now warns on use of the option.
6302 create_test_sourcelist
6304 Create a test driver and source list for building test programs.
6305 create_test_sourcelist(sourceListName driverName
6307 test1 test2 test3
6308 EXTRA_INCLUDE include.h
6309 FUNCTION function)
6310 A test driver is a program that links together many small tests into a
6312 single executable. This is useful when building static executables
6313 with large libraries to shrink the total required size. The list of
6314 source files needed to build the test driver will be in sourceListName.
6315 driverName is the name of the test driver program. The rest of the
6316 arguments consist of a list of test source files, can be semicolon sep‐
6317 arated. Each test source file should have a function in it that is the
6318 same name as the file with no extension (foo.cxx should have int
6319 foo(int, char*[]);) driverName will be able to call each of the tests
6320 by name on the command line. If EXTRA_INCLUDE is specified, then the
6321 next argument is included into the generated file. If FUNCTION is
6322 specified, then the next argument is taken as a function name that is
6323 passed a pointer to ac and av. This can be used to add extra command
6324 line processing to each test. The CMAKE_TESTDRIVER_BEFORE_TESTMAIN
6325 cmake variable can be set to have code that will be placed directly
6326 before calling the test main function. CMAKE_TESTDRIVER_AFTER_TESTMAIN
6327 can be set to have code that will be placed directly after the call to
6328 the test main function.
6329 define_property
6331 Define and document custom properties.
6332 define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
6334 TEST | VARIABLE | CACHED_VARIABLE>
6335 PROPERTY <name> [INHERITED]
6336 BRIEF_DOCS <brief-doc> [docs...]
6337 FULL_DOCS <full-doc> [docs...])
6338 Defines one property in a scope for use with the set_property() and
6340 get_property() commands. This is primarily useful to associate docu‐
6341 mentation with property names that may be retrieved with the get_prop‐
6342 erty() command. The first argument determines the kind of scope in
6343 which the property should be used. It must be one of the following:
6344 GLOBAL = associated with the global namespace
6346 DIRECTORY = associated with one directory
6347 TARGET = associated with one target
6348 SOURCE = associated with one source file
6349 TEST = associated with a test named with add_test
6350 VARIABLE = documents a CMake language variable
6351 CACHED_VARIABLE = documents a CMake cache variable
6352 Note that unlike set_property() and get_property() no actual scope
6354 needs to be given; only the kind of scope is important.
6355 The required PROPERTY option is immediately followed by the name of the
6357 property being defined.
6358 If the INHERITED option is given, then the get_property() command will
6360 chain up to the next higher scope when the requested property is not
6361 set in the scope given to the command.
6362 · DIRECTORY scope chains to its parent directory’s scope, continuing
6364 the walk up parent directories until a directory has the property set
6365 or there are no more parents. If still not found at the top level
6366 directory, it chains to the GLOBAL scope.
6367 · TARGET, SOURCE and TEST properties chain to DIRECTORY scope, includ‐
6369 ing further chaining up the directories, etc. as needed.
6370 Note that this scope chaining behavior only applies to calls to
6372 get_property(), get_directory_property(), get_target_property(),
6373 get_source_file_property() and get_test_property(). There is no inher‐
6374 iting behavior when setting properties, so using APPEND or
6375 APPEND_STRING with the set_property() command will not consider inher‐
6376 ited values when working out the contents to append to.
6377 The BRIEF_DOCS and FULL_DOCS options are followed by strings to be
6379 associated with the property as its brief and full documentation. Cor‐
6380 responding options to the get_property() command will retrieve the doc‐
6381 umentation.
6382 enable_language
6384 Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
6385 enable_language(<lang> [OPTIONAL] )
6387 Enables support for the named language in CMake. This is the same as
6389 the project() command but does not create any of the extra variables
6390 that are created by the project command. Example languages are CXX, C,
6391 CUDA, OBJC, OBJCXX, Fortran, ISPC, and ASM.
6392 If enabling ASM, enable it last so that CMake can check whether compil‐
6394 ers for other languages like C work for assembly too.
6395 This command must be called in file scope, not in a function call.
6397 Furthermore, it must be called in the highest directory common to all
6398 targets using the named language directly for compiling sources or
6399 indirectly through link dependencies. It is simplest to enable all
6400 needed languages in the top-level directory of a project.
6401 The OPTIONAL keyword is a placeholder for future implementation and
6403 does not currently work. Instead you can use the CheckLanguage module
6404 to verify support before enabling.
6405 enable_testing
6407 Enable testing for current directory and below.
6408 enable_testing()
6410 Enables testing for this directory and below.
6412 This command should be in the source directory root because ctest
6414 expects to find a test file in the build directory root.
6415 This command is automatically invoked when the CTest module is
6417 included, except if the BUILD_TESTING option is turned off.
6418 See also the add_test() command.
6420 export
6422 Export targets from the build tree for use by outside projects.
6423 export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
6425 Creates a file <filename> that may be included by outside projects to
6427 import targets from the current project’s build tree. This is useful
6428 during cross-compiling to build utility executables that can run on the
6429 host platform in one project and then import them into another project
6430 being compiled for the target platform. If the NAMESPACE option is
6431 given the <namespace> string will be prepended to all target names
6432 written to the file.
6433 Target installations are associated with the export <export-name> using
6435 the EXPORT option of the install(TARGETS) command.
6436 The file created by this command is specific to the build tree and
6438 should never be installed. See the install(EXPORT) command to export
6439 targets from an installation tree.
6440 The properties set on the generated IMPORTED targets will have the same
6442 values as the final values of the input TARGETS.
6443 export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
6445 [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
6446 This signature is similar to the EXPORT signature, but targets are
6448 listed explicitly rather than specified as an export-name. If the
6449 APPEND option is given the generated code will be appended to the file
6450 instead of overwriting it. The EXPORT_LINK_INTERFACE_LIBRARIES key‐
6451 word, if present, causes the contents of the properties matching
6452 (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when
6453 policy CMP0022 is NEW. If a library target is included in the export
6454 but a target to which it links is not included the behavior is unspeci‐
6455 fied.
6456 NOTE:
6458 Object Libraries under Xcode have special handling if multiple
6459 architectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
6460 they will be exported as Interface Libraries with no object files
6461 available to clients. This is sufficient to satisfy transitive
6462 usage requirements of other targets that link to the object
6463 libraries in their implementation.
6464 export(PACKAGE <PackageName>)
6466 Store the current build directory in the CMake user package registry
6468 for package <PackageName>. The find_package() command may consider the
6469 directory while searching for package <PackageName>. This helps depen‐
6470 dent projects find and use a package from the current project’s build
6471 tree without help from the user. Note that the entry in the package
6472 registry that this command creates works only in conjunction with a
6473 package configuration file (<PackageName>Config.cmake) that works with
6474 the build tree. In some cases, for example for packaging and for system
6475 wide installations, it is not desirable to write the user package reg‐
6476 istry.
6477 By default the export(PACKAGE) command does nothing (see policy
6479 CMP0090) because populating the user package registry has effects out‐
6480 side the source and build trees. Set the CMAKE_EXPORT_PACKAGE_REGISTRY
6481 variable to add build directories to the CMake user package registry.
6482 export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
6484 This signature exports cmake built targets to the android ndk build
6486 system by creating an Android.mk file that references the prebuilt tar‐
6487 gets. The Android NDK supports the use of prebuilt libraries, both
6488 static and shared. This allows cmake to build the libraries of a
6489 project and make them available to an ndk build system complete with
6490 transitive dependencies, include flags and defines required to use the
6491 libraries. The signature takes a list of targets and puts them in the
6492 Android.mk file specified by the <filename> given. This signature can
6493 only be used if policy CMP0022 is NEW for all targets given. A error
6494 will be issued if that policy is set to OLD for one of the targets.
6495 fltk_wrap_ui
6497 Create FLTK user interfaces Wrappers.
6498 fltk_wrap_ui(resultingLibraryName source1
6500 source2 ... sourceN )
6501 Produce .h and .cxx files for all the .fl and .fld files listed. The
6503 resulting .h and .cxx files will be added to a variable named result‐
6504 ingLibraryName_FLTK_UI_SRCS which should be added to your library.
6505 get_source_file_property
6507 Get a property for a source file.
6508 get_source_file_property(<variable> <file>
6510 [DIRECTORY <dir> | TARGET_DIRECTORY <target>]
6511 <property>)
6512 Gets a property from a source file. The value of the property is
6514 stored in the specified <variable>. If the source property is not
6515 found, the behavior depends on whether it has been defined to be an
6516 INHERITED property or not (see define_property()). Non-inherited prop‐
6517 erties will set variable to NOTFOUND, whereas inherited properties will
6518 search the relevant parent scope as described for the define_property()
6519 command and if still unable to find the property, variable will be set
6520 to an empty string.
6521 By default, the source file’s property will be read from the current
6523 source directory’s scope, but this can be overridden with one of the
6524 following sub-options:
6525 DIRECTORY <dir>
6527 The source file property will be read from the <dir> directory’s
6528 scope. CMake must already know about that source directory,
6529 either by having added it through a call to add_subdirectory()
6530 or <dir> being the top level source directory. Relative paths
6531 are treated as relative to the current source directory.
6532 TARGET_DIRECTORY <target>
6534 The source file property will be read from the directory scope
6535 in which <target> was created (<target> must therefore already
6536 exist).
6537 Use set_source_files_properties() to set property values. Source file
6539 properties usually control how the file is built. One property that is
6540 always there is LOCATION.
6541 See also the more general get_property() command.
6543 get_target_property
6545 Get a property from a target.
6546 get_target_property(<VAR> target property)
6548 Get a property from a target. The value of the property is stored in
6550 the variable <VAR>. If the target property is not found, the behavior
6551 depends on whether it has been defined to be an INHERITED property or
6552 not (see define_property()). Non-inherited properties will set <VAR>
6553 to <VAR>-NOTFOUND, whereas inherited properties will search the rele‐
6554 vant parent scope as described for the define_property() command and if
6555 still unable to find the property, <VAR> will be set to an empty
6556 string.
6557 Use set_target_properties() to set target property values. Properties
6559 are usually used to control how a target is built, but some query the
6560 target instead. This command can get properties for any target so far
6561 created. The targets do not need to be in the current CMakeLists.txt
6562 file.
6563 See also the more general get_property() command.
6565 See Target Properties for the list of properties known to CMake.
6567 get_test_property
6569 Get a property of the test.
6570 get_test_property(test property VAR)
6572 Get a property from the test. The value of the property is stored in
6574 the variable VAR. If the test property is not found, the behavior
6575 depends on whether it has been defined to be an INHERITED property or
6576 not (see define_property()). Non-inherited properties will set VAR to
6577 “NOTFOUND”, whereas inherited properties will search the relevant par‐
6578 ent scope as described for the define_property() command and if still
6579 unable to find the property, VAR will be set to an empty string.
6580 For a list of standard properties you can type cmake --help-prop‐
6582 erty-list.
6583 See also the more general get_property() command.
6585 include_directories
6587 Add include directories to the build.
6588 include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])
6590 Add the given directories to those the compiler uses to search for
6592 include files. Relative paths are interpreted as relative to the cur‐
6593 rent source directory.
6594 The include directories are added to the INCLUDE_DIRECTORIES directory
6596 property for the current CMakeLists file. They are also added to the
6597 INCLUDE_DIRECTORIES target property for each target in the current
6598 CMakeLists file. The target property values are the ones used by the
6599 generators.
6600 By default the directories specified are appended onto the current list
6602 of directories. This default behavior can be changed by setting
6603 CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE
6604 explicitly, you can select between appending and prepending, indepen‐
6605 dent of the default.
6606 If the SYSTEM option is given, the compiler will be told the directo‐
6608 ries are meant as system include directories on some platforms. Sig‐
6609 nalling this setting might achieve effects such as the compiler skip‐
6610 ping warnings, or these fixed-install system files not being considered
6611 in dependency calculations - see compiler docs.
6612 Arguments to include_directories may use “generator expressions” with
6614 the syntax “$<…>”. See the cmake-generator-expressions(7) manual for
6615 available expressions. See the cmake-buildsystem(7) manual for more on
6616 defining buildsystem properties.
6617 NOTE:
6619 Prefer the target_include_directories() command to add include
6620 directories to individual targets and optionally propagate/export
6621 them to dependents.
6622 include_external_msproject
6624 Include an external Microsoft project file in a workspace.
6625 include_external_msproject(projectname location
6627 [TYPE projectTypeGUID]
6628 [GUID projectGUID]
6629 [PLATFORM platformName]
6630 dep1 dep2 ...)
6631 Includes an external Microsoft project in the generated workspace file.
6633 Currently does nothing on UNIX. This will create a target named [pro‐
6634 jectname]. This can be used in the add_dependencies() command to make
6635 things depend on the external project.
6636 TYPE, GUID and PLATFORM are optional parameters that allow one to spec‐
6638 ify the type of project, id (GUID) of the project and the name of the
6639 target platform. This is useful for projects requiring values other
6640 than the default (e.g. WIX projects).
6641 If the imported project has different configuration names than the cur‐
6643 rent project, set the MAP_IMPORTED_CONFIG_<CONFIG> target property to
6644 specify the mapping.
6645 include_regular_expression
6647 Set the regular expression used for dependency checking.
6648 include_regular_expression(regex_match [regex_complain])
6650 Sets the regular expressions used in dependency checking. Only files
6652 matching regex_match will be traced as dependencies. Only files match‐
6653 ing regex_complain will generate warnings if they cannot be found
6654 (standard header paths are not searched). The defaults are:
6655 regex_match = "^.*$" (match everything)
6657 regex_complain = "^$" (match empty string only)
6658 install
6660 Specify rules to run at install time.
6661 Synopsis
6663 install(TARGETS <target>... [...])
6664 install({FILES | PROGRAMS} <file>... [...])
6665 install(DIRECTORY <dir>... [...])
6666 install(SCRIPT <file> [...])
6667 install(CODE <code> [...])
6668 install(EXPORT <export-name> [...])
6669 Introduction
6671 This command generates installation rules for a project. Install rules
6672 specified by calls to the install() command within a source directory
6673 are executed in order during installation. Install rules in subdirec‐
6674 tories added by calls to the add_subdirectory() command are interleaved
6675 with those in the parent directory to run in the order declared (see
6676 policy CMP0082).
6677 There are multiple signatures for this command. Some of them define
6679 installation options for files and targets. Options common to multiple
6680 signatures are covered here but they are valid only for signatures that
6681 specify them. The common options are:
6682 DESTINATION
6684 Specify the directory on disk to which a file will be installed.
6685 Arguments can be relative or absolute paths.
6686 If a relative path is given it is interpreted relative to the
6688 value of the CMAKE_INSTALL_PREFIX variable. The prefix can be
6689 relocated at install time using the DESTDIR mechanism explained
6690 in the CMAKE_INSTALL_PREFIX variable documentation.
6691 If an absolute path (with a leading slash or drive letter) is
6693 given it is used verbatim.
6694 As absolute paths are not supported by cpack installer genera‐
6696 tors, it is preferable to use relative paths throughout. In
6697 particular, there is no need to make paths absolute by prepend‐
6698 ing CMAKE_INSTALL_PREFIX; this prefix is used by default if the
6699 DESTINATION is a relative path.
6700 PERMISSIONS
6702 Specify permissions for installed files. Valid permissions are
6703 OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE,
6704 GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID,
6705 and SETGID. Permissions that do not make sense on certain plat‐
6706 forms are ignored on those platforms.
6707 CONFIGURATIONS
6709 Specify a list of build configurations for which the install
6710 rule applies (Debug, Release, etc.). Note that the values speci‐
6711 fied for this option only apply to options listed AFTER the CON‐
6712 FIGURATIONS option. For example, to set separate install paths
6713 for the Debug and Release configurations, do the following:
6714 install(TARGETS target
6716 CONFIGURATIONS Debug
6717 RUNTIME DESTINATION Debug/bin)
6718 install(TARGETS target
6719 CONFIGURATIONS Release
6720 RUNTIME DESTINATION Release/bin)
6721 Note that CONFIGURATIONS appears BEFORE RUNTIME DESTINATION.
6723 COMPONENT
6725 Specify an installation component name with which the install
6726 rule is associated, such as “runtime” or “development”. During
6727 component-specific installation only install rules associated
6728 with the given component name will be executed. During a full
6729 installation all components are installed unless marked with
6730 EXCLUDE_FROM_ALL. If COMPONENT is not provided a default compo‐
6731 nent “Unspecified” is created. The default component name may
6732 be controlled with the CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
6733 variable.
6734 EXCLUDE_FROM_ALL
6736 Specify that the file is excluded from a full installation and
6737 only installed as part of a component-specific installation
6738 RENAME Specify a name for an installed file that may be different from
6740 the original file. Renaming is allowed only when a single file
6741 is installed by the command.
6742 OPTIONAL
6744 Specify that it is not an error if the file to be installed does
6745 not exist.
6746 Command signatures that install files may print messages during instal‐
6748 lation. Use the CMAKE_INSTALL_MESSAGE variable to control which mes‐
6749 sages are printed.
6750 Many of the install() variants implicitly create the directories con‐
6752 taining the installed files. If CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMIS‐
6753 SIONS is set, these directories will be created with the permissions
6754 specified. Otherwise, they will be created according to the uname rules
6755 on Unix-like platforms. Windows platforms are unaffected.
6756 Installing Targets
6758 install(TARGETS targets... [EXPORT <export-name>]
6759 [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
6760 PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
6761 [DESTINATION <dir>]
6762 [PERMISSIONS permissions...]
6763 [CONFIGURATIONS [Debug|Release|...]]
6764 [COMPONENT <component>]
6765 [NAMELINK_COMPONENT <component>]
6766 [OPTIONAL] [EXCLUDE_FROM_ALL]
6767 [NAMELINK_ONLY|NAMELINK_SKIP]
6768 ] [...]
6769 [INCLUDES DESTINATION [<dir> ...]]
6770 )
6771 The TARGETS form specifies rules for installing targets from a project.
6773 There are several kinds of target Output Artifacts that may be
6774 installed:
6775 ARCHIVE
6777 Target artifacts of this kind include:
6778 · Static libraries (except on macOS when marked as FRAMEWORK,
6780 see below);
6781 · DLL import libraries (on all Windows-based systems including
6783 Cygwin; they have extension .lib, in contrast to the .dll
6784 libraries that go to RUNTIME);
6785 · On AIX, the linker import file created for executables with
6787 ENABLE_EXPORTS enabled.
6788 LIBRARY
6790 Target artifacts of this kind include:
6791 · Shared libraries, except
6793 · DLLs (these go to RUNTIME, see below),
6795 · on macOS when marked as FRAMEWORK (see below).
6797 RUNTIME
6799 Target artifacts of this kind include:
6800 · Executables (except on macOS when marked as MACOSX_BUNDLE, see
6802 BUNDLE below);
6803 · DLLs (on all Windows-based systems including Cygwin; note that
6805 the accompanying import libraries are of kind ARCHIVE).
6806 OBJECTS
6808 Object files associated with object libraries.
6809 FRAMEWORK
6811 Both static and shared libraries marked with the FRAMEWORK prop‐
6812 erty are treated as FRAMEWORK targets on macOS.
6813 BUNDLE Executables marked with the MACOSX_BUNDLE property are treated
6815 as BUNDLE targets on macOS.
6816 PUBLIC_HEADER
6818 Any PUBLIC_HEADER files associated with a library are installed
6819 in the destination specified by the PUBLIC_HEADER argument on
6820 non-Apple platforms. Rules defined by this argument are ignored
6821 for FRAMEWORK libraries on Apple platforms because the associ‐
6822 ated files are installed into the appropriate locations inside
6823 the framework folder. See PUBLIC_HEADER for details.
6824 PRIVATE_HEADER
6826 Similar to PUBLIC_HEADER, but for PRIVATE_HEADER files. See PRI‐
6827 VATE_HEADER for details.
6828 RESOURCE
6830 Similar to PUBLIC_HEADER and PRIVATE_HEADER, but for RESOURCE
6831 files. See RESOURCE for details.
6832 For each of these arguments given, the arguments following them only
6834 apply to the target or file type specified in the argument. If none is
6835 given, the installation properties apply to all target types. If only
6836 one is given then only targets of that type will be installed (which
6837 can be used to install just a DLL or just an import library.)
6838 For regular executables, static libraries and shared libraries, the
6840 DESTINATION argument is not required. For these target types, when
6841 DESTINATION is omitted, a default destination will be taken from the
6842 appropriate variable from GNUInstallDirs, or set to a built-in default
6843 value if that variable is not defined. The same is true for the public
6844 and private headers associated with the installed targets through the
6845 PUBLIC_HEADER and PRIVATE_HEADER target properties. A destination must
6846 always be provided for module libraries, Apple bundles and frameworks.
6847 A destination can be omitted for interface and object libraries, but
6848 they are handled differently (see the discussion of this topic toward
6849 the end of this section).
6850 The following table shows the target types with their associated vari‐
6852 ables and built-in defaults that apply when no destination is given:
6853 ┌───────────────┬─────────────────────────────┬──────────────────┐
6855 │Target Type │ GNUInstallDirs │ Built-In Default │
6856 │ │ Variable │ │
6857 └───────────────┴─────────────────────────────┴──────────────────┘
6858 │RUNTIME │ ${CMAKE_INSTALL_BINDIR} │ bin │
6861 ├───────────────┼─────────────────────────────┼──────────────────┤
6862 │LIBRARY │ ${CMAKE_INSTALL_LIBDIR} │ lib │
6863 ├───────────────┼─────────────────────────────┼──────────────────┤
6864 │ARCHIVE │ ${CMAKE_INSTALL_LIBDIR} │ lib │
6865 ├───────────────┼─────────────────────────────┼──────────────────┤
6866 │PRIVATE_HEADER │ ${CMAKE_INSTALL_INCLUDEDIR} │ include │
6867 ├───────────────┼─────────────────────────────┼──────────────────┤
6868 │PUBLIC_HEADER │ ${CMAKE_INSTALL_INCLUDEDIR} │ include │
6869 └───────────────┴─────────────────────────────┴──────────────────┘
6870 Projects wishing to follow the common practice of installing headers
6872 into a project-specific subdirectory will need to provide a destination
6873 rather than rely on the above.
6874 To make packages compliant with distribution filesystem layout poli‐
6876 cies, if projects must specify a DESTINATION, it is recommended that
6877 they use a path that begins with the appropriate GNUInstallDirs vari‐
6878 able. This allows package maintainers to control the install destina‐
6879 tion by setting the appropriate cache variables. The following example
6880 shows a static library being installed to the default destination pro‐
6881 vided by GNUInstallDirs, but with its headers installed to a
6882 project-specific subdirectory that follows the above recommendation:
6883 add_library(mylib STATIC ...)
6885 set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
6886 include(GNUInstallDirs)
6887 install(TARGETS mylib
6888 PUBLIC_HEADER
6889 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
6890 )
6891 In addition to the common options listed above, each target can accept
6893 the following additional arguments:
6894 NAMELINK_COMPONENT
6896 On some platforms a versioned shared library has a symbolic link
6897 such as:
6898 lib<name>.so -> lib<name>.so.1
6900 where lib<name>.so.1 is the soname of the library and
6902 lib<name>.so is a “namelink” allowing linkers to find the
6903 library when given -l<name>. The NAMELINK_COMPONENT option is
6904 similar to the COMPONENT option, but it changes the installation
6905 component of a shared library namelink if one is generated. If
6906 not specified, this defaults to the value of COMPONENT. It is an
6907 error to use this parameter outside of a LIBRARY block.
6908 Consider the following example:
6910 install(TARGETS mylib
6912 LIBRARY
6913 COMPONENT Libraries
6914 NAMELINK_COMPONENT Development
6915 PUBLIC_HEADER
6916 COMPONENT Development
6917 )
6918 In this scenario, if you choose to install only the Development
6920 component, both the headers and namelink will be installed with‐
6921 out the library. (If you don’t also install the Libraries compo‐
6922 nent, the namelink will be a dangling symlink, and projects that
6923 link to the library will have build errors.) If you install only
6924 the Libraries component, only the library will be installed,
6925 without the headers and namelink.
6926 This option is typically used for package managers that have
6928 separate runtime and development packages. For example, on
6929 Debian systems, the library is expected to be in the runtime
6930 package, and the headers and namelink are expected to be in the
6931 development package.
6932 See the VERSION and SOVERSION target properties for details on
6934 creating versioned shared libraries.
6935 NAMELINK_ONLY
6937 This option causes the installation of only the namelink when a
6938 library target is installed. On platforms where versioned shared
6939 libraries do not have namelinks or when a library is not ver‐
6940 sioned, the NAMELINK_ONLY option installs nothing. It is an
6941 error to use this parameter outside of a LIBRARY block.
6942 When NAMELINK_ONLY is given, either NAMELINK_COMPONENT or COMPO‐
6944 NENT may be used to specify the installation component of the
6945 namelink, but COMPONENT should generally be preferred.
6946 NAMELINK_SKIP
6948 Similar to NAMELINK_ONLY, but it has the opposite effect: it
6949 causes the installation of library files other than the namelink
6950 when a library target is installed. When neither NAMELINK_ONLY
6951 or NAMELINK_SKIP are given, both portions are installed. On
6952 platforms where versioned shared libraries do not have symlinks
6953 or when a library is not versioned, NAMELINK_SKIP installs the
6954 library. It is an error to use this parameter outside of a
6955 LIBRARY block.
6956 If NAMELINK_SKIP is specified, NAMELINK_COMPONENT has no effect.
6958 It is not recommended to use NAMELINK_SKIP in conjunction with
6959 NAMELINK_COMPONENT.
6960 The install(TARGETS) command can also accept the following options at
6962 the top level:
6963 EXPORT This option associates the installed target files with an export
6965 called <export-name>. It must appear before any target options.
6966 To actually install the export file itself, call
6967 install(EXPORT), documented below. See documentation of the
6968 EXPORT_NAME target property to change the name of the exported
6969 target.
6970 INCLUDES DESTINATION
6972 This option specifies a list of directories which will be added
6973 to the INTERFACE_INCLUDE_DIRECTORIES target property of the
6974 <targets> when exported by the install(EXPORT) command. If a
6975 relative path is specified, it is treated as relative to the
6976 $<INSTALL_PREFIX>.
6977 One or more groups of properties may be specified in a single call to
6979 the TARGETS form of this command. A target may be installed more than
6980 once to different locations. Consider hypothetical targets myExe,
6981 mySharedLib, and myStaticLib. The code:
6982 install(TARGETS myExe mySharedLib myStaticLib
6984 RUNTIME DESTINATION bin
6985 LIBRARY DESTINATION lib
6986 ARCHIVE DESTINATION lib/static)
6987 install(TARGETS mySharedLib DESTINATION /some/full/path)
6988 will install myExe to <prefix>/bin and myStaticLib to <pre‐
6990 fix>/lib/static. On non-DLL platforms mySharedLib will be installed to
6991 <prefix>/lib and /some/full/path. On DLL platforms the mySharedLib DLL
6992 will be installed to <prefix>/bin and /some/full/path and its import
6993 library will be installed to <prefix>/lib/static and /some/full/path.
6994 Interface Libraries may be listed among the targets to install. They
6996 install no artifacts but will be included in an associated EXPORT. If
6997 Object Libraries are listed but given no destination for their object
6998 files, they will be exported as Interface Libraries. This is suffi‐
6999 cient to satisfy transitive usage requirements of other targets that
7000 link to the object libraries in their implementation.
7001 Installing a target with the EXCLUDE_FROM_ALL target property set to
7003 TRUE has undefined behavior.
7004 install(TARGETS) can install targets that were created in other direc‐
7006 tories. When using such cross-directory install rules, running make
7007 install (or similar) from a subdirectory will not guarantee that tar‐
7008 gets from other directories are up-to-date. You can use tar‐
7009 get_link_libraries() or add_dependencies() to ensure that such
7010 out-of-directory targets are built before the subdirectory-specific
7011 install rules are run.
7012 An install destination given as a DESTINATION argument may use “genera‐
7014 tor expressions” with the syntax $<...>. See the cmake-genera‐
7015 tor-expressions(7) manual for available expressions.
7016 Installing Files
7018 install(<FILES|PROGRAMS> files...
7019 TYPE <type> | DESTINATION <dir>
7020 [PERMISSIONS permissions...]
7021 [CONFIGURATIONS [Debug|Release|...]]
7022 [COMPONENT <component>]
7023 [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
7024 The FILES form specifies rules for installing files for a project.
7026 File names given as relative paths are interpreted with respect to the
7027 current source directory. Files installed by this form are by default
7028 given permissions OWNER_WRITE, OWNER_READ, GROUP_READ, and WORLD_READ
7029 if no PERMISSIONS argument is given.
7030 The PROGRAMS form is identical to the FILES form except that the
7032 default permissions for the installed file also include OWNER_EXECUTE,
7033 GROUP_EXECUTE, and WORLD_EXECUTE. This form is intended to install
7034 programs that are not targets, such as shell scripts. Use the TARGETS
7035 form to install targets built within the project.
7036 The list of files... given to FILES or PROGRAMS may use “generator
7038 expressions” with the syntax $<...>. See the cmake-generator-expres‐
7039 sions(7) manual for available expressions. However, if any item begins
7040 in a generator expression it must evaluate to a full path.
7041 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
7043 argument specifies the generic file type of the files being installed.
7044 A destination will then be set automatically by taking the correspond‐
7045 ing variable from GNUInstallDirs, or by using a built-in default if
7046 that variable is not defined. See the table below for the supported
7047 file types and their corresponding variables and built-in defaults.
7048 Projects can provide a DESTINATION argument instead of a file type if
7049 they wish to explicitly define the install destination.
7050 ┌──────────────┬─────────────────────────────┬─────────────────────┐
7052 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
7053 │ │ Variable │ │
7054 ├──────────────┼─────────────────────────────┼─────────────────────┤
7055 │BIN │ ${CMAKE_INSTALL_BINDIR} │ bin │
7056 ├──────────────┼─────────────────────────────┼─────────────────────┤
7057 │SBIN │ ${CMAKE_INSTALL_SBINDIR} │ sbin │
7058 ├──────────────┼─────────────────────────────┼─────────────────────┤
7059 │LIB │ ${CMAKE_INSTALL_LIBDIR} │ lib │
7060 ├──────────────┼─────────────────────────────┼─────────────────────┤
7061 │INCLUDE │ ${CMAKE_INSTALL_INCLUDEDIR} │ include │
7062 ├──────────────┼─────────────────────────────┼─────────────────────┤
7063 │SYSCONF │ ${CMAKE_INSTALL_SYSCONFDIR} │ etc │
7064 ├──────────────┼─────────────────────────────┼─────────────────────┤
7065 │SHAREDSTATE │ ${CMAKE_INSTALL_SHARESTATE‐ │ com │
7066 │ │ DIR} │ │
7067 ├──────────────┼─────────────────────────────┼─────────────────────┤
7068 │LOCALSTATE │ ${CMAKE_INSTALL_LOCALSTATE‐ │ var │
7069 │ │ DIR} │ │
7070 ├──────────────┼─────────────────────────────┼─────────────────────┤
7071 │RUNSTATE │ ${CMAKE_INSTALL_RUNSTATE‐ │ <LOCALSTATE │
7072 │ │ DIR} │ dir>/run │
7073 ├──────────────┼─────────────────────────────┼─────────────────────┤
7074 │DATA │ ${CMAKE_INSTALL_DATADIR} │ <DATAROOT dir> │
7075 ├──────────────┼─────────────────────────────┼─────────────────────┤
7076 │INFO │ ${CMAKE_INSTALL_INFODIR} │ <DATAROOT dir>/info │
7077 ├──────────────┼─────────────────────────────┼─────────────────────┤
7078 │LOCALE │ ${CMAKE_INSTALL_LOCALEDIR} │ <DATAROOT │
7079 │ │ │ dir>/locale │
7080 ├──────────────┼─────────────────────────────┼─────────────────────┤
7081 │MAN │ ${CMAKE_INSTALL_MANDIR} │ <DATAROOT dir>/man │
7082 ├──────────────┼─────────────────────────────┼─────────────────────┤
7083 │DOC │ ${CMAKE_INSTALL_DOCDIR} │ <DATAROOT dir>/doc │
7084 └──────────────┴─────────────────────────────┴─────────────────────┘
7085 Projects wishing to follow the common practice of installing headers
7087 into a project-specific subdirectory will need to provide a destination
7088 rather than rely on the above.
7089 Note that some of the types’ built-in defaults use the DATAROOT direc‐
7091 tory as a prefix. The DATAROOT prefix is calculated similarly to the
7092 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
7093 built-in default. You cannot use DATAROOT as a TYPE parameter; please
7094 use DATA instead.
7095 To make packages compliant with distribution filesystem layout poli‐
7097 cies, if projects must specify a DESTINATION, it is recommended that
7098 they use a path that begins with the appropriate GNUInstallDirs vari‐
7099 able. This allows package maintainers to control the install destina‐
7100 tion by setting the appropriate cache variables. The following example
7101 shows how to follow this advice while installing headers to a
7102 project-specific subdirectory:
7103 include(GNUInstallDirs)
7105 install(FILES mylib.h
7106 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
7107 )
7108 An install destination given as a DESTINATION argument may use “genera‐
7110 tor expressions” with the syntax $<...>. See the cmake-genera‐
7111 tor-expressions(7) manual for available expressions.
7112 Installing Directories
7114 install(DIRECTORY dirs...
7115 TYPE <type> | DESTINATION <dir>
7116 [FILE_PERMISSIONS permissions...]
7117 [DIRECTORY_PERMISSIONS permissions...]
7118 [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
7119 [CONFIGURATIONS [Debug|Release|...]]
7120 [COMPONENT <component>] [EXCLUDE_FROM_ALL]
7121 [FILES_MATCHING]
7122 [[PATTERN <pattern> | REGEX <regex>]
7123 [EXCLUDE] [PERMISSIONS permissions...]] [...])
7124 The DIRECTORY form installs contents of one or more directories to a
7126 given destination. The directory structure is copied verbatim to the
7127 destination. The last component of each directory name is appended to
7128 the destination directory but a trailing slash may be used to avoid
7129 this because it leaves the last component empty. Directory names given
7130 as relative paths are interpreted with respect to the current source
7131 directory. If no input directory names are given the destination
7132 directory will be created but nothing will be installed into it. The
7133 FILE_PERMISSIONS and DIRECTORY_PERMISSIONS options specify permissions
7134 given to files and directories in the destination. If USE_SOURCE_PER‐
7135 MISSIONS is specified and FILE_PERMISSIONS is not, file permissions
7136 will be copied from the source directory structure. If no permissions
7137 are specified files will be given the default permissions specified in
7138 the FILES form of the command, and the directories will be given the
7139 default permissions specified in the PROGRAMS form of the command.
7140 The MESSAGE_NEVER option disables file installation status output.
7142 Installation of directories may be controlled with fine granularity
7144 using the PATTERN or REGEX options. These “match” options specify a
7145 globbing pattern or regular expression to match directories or files
7146 encountered within input directories. They may be used to apply cer‐
7147 tain options (see below) to a subset of the files and directories
7148 encountered. The full path to each input file or directory (with for‐
7149 ward slashes) is matched against the expression. A PATTERN will match
7150 only complete file names: the portion of the full path matching the
7151 pattern must occur at the end of the file name and be preceded by a
7152 slash. A REGEX will match any portion of the full path but it may use
7153 / and $ to simulate the PATTERN behavior. By default all files and
7154 directories are installed whether or not they are matched. The
7155 FILES_MATCHING option may be given before the first match option to
7156 disable installation of files (but not directories) not matched by any
7157 expression. For example, the code
7158 install(DIRECTORY src/ DESTINATION include/myproj
7160 FILES_MATCHING PATTERN "*.h")
7161 will extract and install header files from a source tree.
7163 Some options may follow a PATTERN or REGEX expression and are applied
7165 only to files or directories matching them. The EXCLUDE option will
7166 skip the matched file or directory. The PERMISSIONS option overrides
7167 the permissions setting for the matched file or directory. For example
7168 the code
7169 install(DIRECTORY icons scripts/ DESTINATION share/myproj
7171 PATTERN "CVS" EXCLUDE
7172 PATTERN "scripts/*"
7173 PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
7174 GROUP_EXECUTE GROUP_READ)
7175 will install the icons directory to share/myproj/icons and the scripts
7177 directory to share/myproj. The icons will get default file permis‐
7178 sions, the scripts will be given specific permissions, and any CVS
7179 directories will be excluded.
7180 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
7182 argument specifies the generic file type of the files within the listed
7183 directories being installed. A destination will then be set automati‐
7184 cally by taking the corresponding variable from GNUInstallDirs, or by
7185 using a built-in default if that variable is not defined. See the ta‐
7186 ble below for the supported file types and their corresponding vari‐
7187 ables and built-in defaults. Projects can provide a DESTINATION argu‐
7188 ment instead of a file type if they wish to explicitly define the
7189 install destination.
7190 ┌──────────────┬─────────────────────────────┬─────────────────────┐
7192 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
7193 │ │ Variable │ │
7194 ├──────────────┼─────────────────────────────┼─────────────────────┤
7195 │BIN │ ${CMAKE_INSTALL_BINDIR} │ bin │
7196 ├──────────────┼─────────────────────────────┼─────────────────────┤
7197 │SBIN │ ${CMAKE_INSTALL_SBINDIR} │ sbin │
7198 ├──────────────┼─────────────────────────────┼─────────────────────┤
7199 │LIB │ ${CMAKE_INSTALL_LIBDIR} │ lib │
7200 ├──────────────┼─────────────────────────────┼─────────────────────┤
7201 │INCLUDE │ ${CMAKE_INSTALL_INCLUDEDIR} │ include │
7202 ├──────────────┼─────────────────────────────┼─────────────────────┤
7203 │SYSCONF │ ${CMAKE_INSTALL_SYSCONFDIR} │ etc │
7204 └──────────────┴─────────────────────────────┴─────────────────────┘
7205 │SHAREDSTATE │ ${CMAKE_INSTALL_SHARESTATE‐ │ com │
7209 │ │ DIR} │ │
7210 ├──────────────┼─────────────────────────────┼─────────────────────┤
7211 │LOCALSTATE │ ${CMAKE_INSTALL_LOCALSTATE‐ │ var │
7212 │ │ DIR} │ │
7213 ├──────────────┼─────────────────────────────┼─────────────────────┤
7214 │RUNSTATE │ ${CMAKE_INSTALL_RUNSTATE‐ │ <LOCALSTATE │
7215 │ │ DIR} │ dir>/run │
7216 ├──────────────┼─────────────────────────────┼─────────────────────┤
7217 │DATA │ ${CMAKE_INSTALL_DATADIR} │ <DATAROOT dir> │
7218 ├──────────────┼─────────────────────────────┼─────────────────────┤
7219 │INFO │ ${CMAKE_INSTALL_INFODIR} │ <DATAROOT dir>/info │
7220 ├──────────────┼─────────────────────────────┼─────────────────────┤
7221 │LOCALE │ ${CMAKE_INSTALL_LOCALEDIR} │ <DATAROOT │
7222 │ │ │ dir>/locale │
7223 ├──────────────┼─────────────────────────────┼─────────────────────┤
7224 │MAN │ ${CMAKE_INSTALL_MANDIR} │ <DATAROOT dir>/man │
7225 ├──────────────┼─────────────────────────────┼─────────────────────┤
7226 │DOC │ ${CMAKE_INSTALL_DOCDIR} │ <DATAROOT dir>/doc │
7227 └──────────────┴─────────────────────────────┴─────────────────────┘
7228 Note that some of the types’ built-in defaults use the DATAROOT direc‐
7230 tory as a prefix. The DATAROOT prefix is calculated similarly to the
7231 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
7232 built-in default. You cannot use DATAROOT as a TYPE parameter; please
7233 use DATA instead.
7234 To make packages compliant with distribution filesystem layout poli‐
7236 cies, if projects must specify a DESTINATION, it is recommended that
7237 they use a path that begins with the appropriate GNUInstallDirs vari‐
7238 able. This allows package maintainers to control the install destina‐
7239 tion by setting the appropriate cache variables.
7240 The list of dirs... given to DIRECTORY and an install destination given
7242 as a DESTINATION argument may use “generator expressions” with the syn‐
7243 tax $<...>. See the cmake-generator-expressions(7) manual for avail‐
7244 able expressions.
7245 Custom Installation Logic
7247 install([[SCRIPT <file>] [CODE <code>]]
7248 [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])
7249 The SCRIPT form will invoke the given CMake script files during instal‐
7251 lation. If the script file name is a relative path it will be inter‐
7252 preted with respect to the current source directory. The CODE form
7253 will invoke the given CMake code during installation. Code is speci‐
7254 fied as a single argument inside a double-quoted string. For example,
7255 the code
7256 install(CODE "MESSAGE(\"Sample install message.\")")
7258 will print a message during installation.
7260 <file> or <code> may use “generator expressions” with the syntax $<...>
7262 (in the case of <file>, this refers to their use in the file name, not
7263 the file’s contents). See the cmake-generator-expressions(7) manual
7264 for available expressions.
7265 Installing Exports
7267 install(EXPORT <export-name> DESTINATION <dir>
7268 [NAMESPACE <namespace>] [[FILE <name>.cmake]|
7269 [PERMISSIONS permissions...]
7270 [CONFIGURATIONS [Debug|Release|...]]
7271 [EXPORT_LINK_INTERFACE_LIBRARIES]
7272 [COMPONENT <component>]
7273 [EXCLUDE_FROM_ALL])
7274 install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])
7275 The EXPORT form generates and installs a CMake file containing code to
7277 import targets from the installation tree into another project. Target
7278 installations are associated with the export <export-name> using the
7279 EXPORT option of the install(TARGETS) signature documented above. The
7280 NAMESPACE option will prepend <namespace> to the target names as they
7281 are written to the import file. By default the generated file will be
7282 called <export-name>.cmake but the FILE option may be used to specify a
7283 different name. The value given to the FILE option must be a file name
7284 with the .cmake extension. If a CONFIGURATIONS option is given then
7285 the file will only be installed when one of the named configurations is
7286 installed. Additionally, the generated import file will reference only
7287 the matching target configurations. The EXPORT_LINK_INTER‐
7288 FACE_LIBRARIES keyword, if present, causes the contents of the proper‐
7289 ties matching (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be
7290 exported, when policy CMP0022 is NEW.
7291 NOTE:
7293 The installed <export-name>.cmake file may come with additional
7294 per-configuration <export-name>-*.cmake files to be loaded by glob‐
7295 bing. Do not use an export name that is the same as the package
7296 name in combination with installing a <package-name>-config.cmake
7297 file or the latter may be incorrectly matched by the glob and
7298 loaded.
7299 When a COMPONENT option is given, the listed <component> implicitly
7301 depends on all components mentioned in the export set. The exported
7302 <name>.cmake file will require each of the exported components to be
7303 present in order for dependent projects to build properly. For example,
7304 a project may define components Runtime and Development, with shared
7305 libraries going into the Runtime component and static libraries and
7306 headers going into the Development component. The export set would also
7307 typically be part of the Development component, but it would export
7308 targets from both the Runtime and Development components. Therefore,
7309 the Runtime component would need to be installed if the Development
7310 component was installed, but not vice versa. If the Development compo‐
7311 nent was installed without the Runtime component, dependent projects
7312 that try to link against it would have build errors. Package managers,
7313 such as APT and RPM, typically handle this by listing the Runtime com‐
7314 ponent as a dependency of the Development component in the package
7315 metadata, ensuring that the library is always installed if the headers
7316 and CMake export file are present.
7317 In addition to cmake language files, the EXPORT_ANDROID_MK mode maybe
7319 used to specify an export to the android ndk build system. This mode
7320 accepts the same options as the normal export mode. The Android NDK
7321 supports the use of prebuilt libraries, both static and shared. This
7322 allows cmake to build the libraries of a project and make them avail‐
7323 able to an ndk build system complete with transitive dependencies,
7324 include flags and defines required to use the libraries.
7325 The EXPORT form is useful to help outside projects use targets built
7327 and installed by the current project. For example, the code
7328 install(TARGETS myexe EXPORT myproj DESTINATION bin)
7330 install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
7331 install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules)
7332 will install the executable myexe to <prefix>/bin and code to import it
7334 in the file <prefix>/lib/myproj/myproj.cmake and <pre‐
7335 fix>/share/ndk-modules/Android.mk. An outside project may load this
7336 file with the include command and reference the myexe executable from
7337 the installation tree using the imported target name mp_myexe as if the
7338 target were built in its own tree.
7339 NOTE:
7341 This command supercedes the install_targets() command and the
7342 PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT target properties. It
7343 also replaces the FILES forms of the install_files() and
7344 install_programs() commands. The processing order of these install
7345 rules relative to those generated by install_targets(),
7346 install_files(), and install_programs() commands is not defined.
7347 Generated Installation Script
7349 NOTE:
7350 Use of this feature is not recommended. Please consider using the
7351 --install argument of cmake(1) instead.
7352 The install() command generates a file, cmake_install.cmake, inside the
7354 build directory, which is used internally by the generated install tar‐
7355 get and by CPack. You can also invoke this script manually with cmake
7356 -P. This script accepts several variables:
7357 COMPONENT
7359 Set this variable to install only a single CPack component as
7360 opposed to all of them. For example, if you only want to install
7361 the Development component, run cmake -DCOMPONENT=Development -P
7362 cmake_install.cmake.
7363 BUILD_TYPE
7365 Set this variable to change the build type if you are using a
7366 multi-config generator. For example, to install with the Debug
7367 configuration, run cmake -DBUILD_TYPE=Debug -P
7368 cmake_install.cmake.
7369 DESTDIR
7371 This is an environment variable rather than a CMake variable. It
7372 allows you to change the installation prefix on UNIX systems.
7373 See DESTDIR for details.
7374 link_directories
7376 Add directories in which the linker will look for libraries.
7377 link_directories([AFTER|BEFORE] directory1 [directory2 ...])
7379 Adds the paths in which the linker should search for libraries. Rela‐
7381 tive paths given to this command are interpreted as relative to the
7382 current source directory, see CMP0015.
7383 The directories are added to the LINK_DIRECTORIES directory property
7385 for the current CMakeLists.txt file, converting relative paths to abso‐
7386 lute as needed. The command will apply only to targets created after
7387 it is called.
7388 By default the directories specified are appended onto the current list
7390 of directories. This default behavior can be changed by setting
7391 CMAKE_LINK_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE explic‐
7392 itly, you can select between appending and prepending, independent of
7393 the default.
7394 Arguments to link_directories may use “generator expressions” with the
7396 syntax “$<…>”. See the cmake-generator-expressions(7) manual for
7397 available expressions. See the cmake-buildsystem(7) manual for more on
7398 defining buildsystem properties.
7399 NOTE:
7401 This command is rarely necessary and should be avoided where there
7402 are other choices. Prefer to pass full absolute paths to libraries
7403 where possible, since this ensures the correct library will always
7404 be linked. The find_library() command provides the full path, which
7405 can generally be used directly in calls to target_link_libraries().
7406 Situations where a library search path may be needed include:
7407 · Project generators like Xcode where the user can switch target
7409 architecture at build time, but a full path to a library cannot be
7410 used because it only provides one architecture (i.e. it is not a
7411 universal binary).
7412 · Libraries may themselves have other private library dependencies
7414 that expect to be found via RPATH mechanisms, but some linkers are
7415 not able to fully decode those paths (e.g. due to the presence of
7416 things like $ORIGIN).
7417 If a library search path must be provided, prefer to localize the
7419 effect where possible by using the target_link_directories() command
7420 rather than link_directories(). The target-specific command can
7421 also control how the search directories propagate to other dependent
7422 targets.
7423 link_libraries
7425 Link libraries to all targets added later.
7426 link_libraries([item1 [item2 [...]]]
7428 [[debug|optimized|general] <item>] ...)
7429 Specify libraries or flags to use when linking any targets created
7431 later in the current directory or below by commands such as add_exe‐
7432 cutable() or add_library(). See the target_link_libraries() command
7433 for meaning of arguments.
7434 NOTE:
7436 The target_link_libraries() command should be preferred whenever
7437 possible. Library dependencies are chained automatically, so direc‐
7438 tory-wide specification of link libraries is rarely needed.
7439 load_cache
7441 Load in the values from another project’s CMake cache.
7442 load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...)
7444 Reads the cache and store the requested entries in variables with their
7446 name prefixed with the given prefix. This only reads the values, and
7447 does not create entries in the local project’s cache.
7448 load_cache(pathToBuildDirectory [EXCLUDE entry1...]
7450 [INCLUDE_INTERNALS entry1...])
7451 Loads in the values from another cache and store them in the local
7453 project’s cache as internal entries. This is useful for a project that
7454 depends on another project built in a different tree. EXCLUDE option
7455 can be used to provide a list of entries to be excluded.
7456 INCLUDE_INTERNALS can be used to provide a list of internal entries to
7457 be included. Normally, no internal entries are brought in. Use of
7458 this form of the command is strongly discouraged, but it is provided
7459 for backward compatibility.
7460 project
7462 Set the name of the project.
7463 Synopsis
7465 project(<PROJECT-NAME> [<language-name>...])
7466 project(<PROJECT-NAME>
7467 [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
7468 [DESCRIPTION <project-description-string>]
7469 [HOMEPAGE_URL <url-string>]
7470 [LANGUAGES <language-name>...])
7471 Sets the name of the project, and stores it in the variable
7473 PROJECT_NAME. When called from the top-level CMakeLists.txt also stores
7474 the project name in the variable CMAKE_PROJECT_NAME.
7475 Also sets the variables
7477 · PROJECT_SOURCE_DIR, <PROJECT-NAME>_SOURCE_DIR
7479 · PROJECT_BINARY_DIR, <PROJECT-NAME>_BINARY_DIR
7481 Further variables are set by the optional arguments described in the
7483 following. If any of these arguments is not used, then the correspond‐
7484 ing variables are set to the empty string.
7485 Options
7487 The options are:
7488 VERSION <version>
7490 Optional; may not be used unless policy CMP0048 is set to NEW.
7491 Takes a <version> argument composed of non-negative integer com‐
7493 ponents, i.e. <major>[.<minor>[.<patch>[.<tweak>]]], and sets
7494 the variables
7495 · PROJECT_VERSION, <PROJECT-NAME>_VERSION
7497 · PROJECT_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MAJOR
7499 · PROJECT_VERSION_MINOR, <PROJECT-NAME>_VERSION_MINOR
7501 · PROJECT_VERSION_PATCH, <PROJECT-NAME>_VERSION_PATCH
7503 · PROJECT_VERSION_TWEAK, <PROJECT-NAME>_VERSION_TWEAK.
7505 When the project() command is called from the top-level CMake‐
7507 Lists.txt, then the version is also stored in the variable
7508 CMAKE_PROJECT_VERSION.
7509 DESCRIPTION <project-description-string>
7511 Optional. Sets the variables
7512 · PROJECT_DESCRIPTION, <PROJECT-NAME>_DESCRIPTION
7514 to <project-description-string>. It is recommended that this
7516 description is a relatively short string, usually no more than a
7517 few words.
7518 When the project() command is called from the top-level CMake‐
7520 Lists.txt, then the description is also stored in the variable
7521 CMAKE_PROJECT_DESCRIPTION.
7522 HOMEPAGE_URL <url-string>
7524 Optional. Sets the variables
7525 · PROJECT_HOMEPAGE_URL, <PROJECT-NAME>_HOMEPAGE_URL
7527 to <url-string>, which should be the canonical home URL for the
7529 project.
7530 When the project() command is called from the top-level CMake‐
7532 Lists.txt, then the URL also is stored in the variable
7533 CMAKE_PROJECT_HOMEPAGE_URL.
7534 LANGUAGES <language-name>...
7536 Optional. Can also be specified without LANGUAGES keyword per
7537 the first, short signature.
7538 Selects which programming languages are needed to build the
7540 project. Supported languages include C, CXX (i.e. C++), CUDA,
7541 OBJC (i.e. Objective-C), OBJCXX, Fortran, ISPC, and ASM. By
7542 default C and CXX are enabled if no language options are given.
7543 Specify language NONE, or use the LANGUAGES keyword and list no
7544 languages, to skip enabling any languages.
7545 If enabling ASM, list it last so that CMake can check whether
7547 compilers for other languages like C work for assembly too.
7548 The variables set through the VERSION, DESCRIPTION and HOMEPAGE_URL
7550 options are intended for use as default values in package metadata and
7551 documentation.
7552 Code Injection
7554 If the CMAKE_PROJECT_INCLUDE_BEFORE or
7555 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE variables are set, the
7556 files they point to will be included as the first step of the project()
7557 command. If both are set, then CMAKE_PROJECT_INCLUDE_BEFORE will be
7558 included before CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE.
7559 If the CMAKE_PROJECT_INCLUDE or CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE
7561 variables are set, the files they point to will be included as the last
7562 step of the project() command. If both are set, then
7563 CMAKE_PROJECT_INCLUDE will be included before
7564 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE.
7565 Usage
7567 The top-level CMakeLists.txt file for a project must contain a literal,
7568 direct call to the project() command; loading one through the include()
7569 command is not sufficient. If no such call exists, CMake will issue a
7570 warning and pretend there is a project(Project) at the top to enable
7571 the default languages (C and CXX).
7572 NOTE:
7574 Call the project() command near the top of the top-level CMake‐
7575 Lists.txt, but after calling cmake_minimum_required(). It is impor‐
7576 tant to establish version and policy settings before invoking other
7577 commands whose behavior they may affect. See also policy CMP0000.
7578 remove_definitions
7580 Remove -D define flags added by add_definitions().
7581 remove_definitions(-DFOO -DBAR ...)
7583 Removes flags (added by add_definitions()) from the compiler command
7585 line for sources in the current directory and below.
7586 set_source_files_properties
7588 Source files can have properties that affect how they are built.
7589 set_source_files_properties(<files> ...
7591 [DIRECTORY <dirs> ...]
7592 [TARGET_DIRECTORY <targets> ...]
7593 PROPERTIES <prop1> <value1>
7594 [<prop2> <value2>] ...)
7595 Sets properties associated with source files using a key/value paired
7597 list.
7598 By default, source file properties are only visible to targets added in
7600 the same directory (CMakeLists.txt). Visibility can be set in other
7601 directory scopes using one or both of the following options:
7602 DIRECTORY <dirs>...
7604 The source file properties will be set in each of the <dirs>
7605 directories’ scopes. CMake must already know about each of
7606 these source directories, either by having added them through a
7607 call to add_subdirectory() or it being the top level source
7608 directory. Relative paths are treated as relative to the cur‐
7609 rent source directory.
7610 TARGET_DIRECTORY <targets>...
7612 The source file properties will be set in each of the directory
7613 scopes where any of the specified <targets> were created (the
7614 <targets> must therefore already exist).
7615 Use get_source_file_property() to get property values. See also the
7617 set_property(SOURCE) command.
7618 See Source File Properties for the list of properties known to CMake.
7620 set_target_properties
7622 Targets can have properties that affect how they are built.
7623 set_target_properties(target1 target2 ...
7625 PROPERTIES prop1 value1
7626 prop2 value2 ...)
7627 Sets properties on targets. The syntax for the command is to list all
7629 the targets you want to change, and then provide the values you want to
7630 set next. You can use any prop value pair you want and extract it
7631 later with the get_property() or get_target_property() command.
7632 See also the set_property(TARGET) command.
7634 See Target Properties for the list of properties known to CMake.
7636 set_tests_properties
7638 Set a property of the tests.
7639 set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
7641 Sets a property for the tests. If the test is not found, CMake will
7643 report an error. Generator expressions will be expanded the same as
7644 supported by the test’s add_test() call.
7645 See also the set_property(TEST) command.
7647 See Test Properties for the list of properties known to CMake.
7649 source_group
7651 Define a grouping for source files in IDE project generation. There
7652 are two different signatures to create source groups.
7653 source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
7655 source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...])
7656 Defines a group into which sources will be placed in project files.
7658 This is intended to set up file tabs in Visual Studio. The options
7659 are:
7660 TREE CMake will automatically detect, from <src> files paths, source
7662 groups it needs to create, to keep structure of source groups
7663 analogically to the actual files and directories structure in
7664 the project. Paths of <src> files will be cut to be relative to
7665 <root>.
7666 PREFIX Source group and files located directly in <root> path, will be
7668 placed in <prefix> source groups.
7669 FILES Any source file specified explicitly will be placed in group
7671 <name>. Relative paths are interpreted with respect to the cur‐
7672 rent source directory.
7673 REGULAR_EXPRESSION
7675 Any source file whose name matches the regular expression will
7676 be placed in group <name>.
7677 If a source file matches multiple groups, the last group that explic‐
7679 itly lists the file with FILES will be favored, if any. If no group
7680 explicitly lists the file, the last group whose regular expression
7681 matches the file will be favored.
7682 The <name> of the group and <prefix> argument may contain forward
7684 slashes or backslashes to specify subgroups. Backslashes need to be
7685 escaped appropriately:
7686 source_group(base/subdir ...)
7688 source_group(outer\\inner ...)
7689 source_group(TREE <root> PREFIX sources\\inc ...)
7690 For backwards compatibility, the short-hand signature
7692 source_group(<name> <regex>)
7694 is equivalent to
7696 source_group(<name> REGULAR_EXPRESSION <regex>)
7698 target_compile_definitions
7700 Add compile definitions to a target.
7701 target_compile_definitions(<target>
7703 <INTERFACE|PUBLIC|PRIVATE> [items1...]
7704 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
7705 Specifies compile definitions to use when compiling a given <target>.
7707 The named <target> must have been created by a command such as add_exe‐
7708 cutable() or add_library() and must not be an ALIAS target.
7709 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
7711 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
7712 late the COMPILE_DEFINITIONS property of <target>. PUBLIC and INTERFACE
7713 items will populate the INTERFACE_COMPILE_DEFINITIONS property of <tar‐
7714 get>. (IMPORTED targets only support INTERFACE items.) The following
7715 arguments specify compile definitions. Repeated calls for the same
7716 <target> append items in the order called.
7717 Arguments to target_compile_definitions may use “generator expressions”
7719 with the syntax $<...>. See the cmake-generator-expressions(7) manual
7720 for available expressions. See the cmake-buildsystem(7) manual for
7721 more on defining buildsystem properties.
7722 Any leading -D on an item will be removed. Empty items are ignored.
7724 For example, the following are all equivalent:
7725 target_compile_definitions(foo PUBLIC FOO)
7727 target_compile_definitions(foo PUBLIC -DFOO) # -D removed
7728 target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
7729 target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
7730 target_compile_features
7732 New in version 3.1.
7733 Add expected compiler features to a target.
7736 target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
7738 Specifies compiler features required when compiling a given target. If
7740 the feature is not listed in the CMAKE_C_COMPILE_FEATURES,
7741 CMAKE_CUDA_COMPILE_FEATURES, or CMAKE_CXX_COMPILE_FEATURES variables,
7742 then an error will be reported by CMake. If the use of the feature
7743 requires an additional compiler flag, such as -std=gnu++11, the flag
7744 will be added automatically.
7745 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
7747 scope of the features. PRIVATE and PUBLIC items will populate the COM‐
7748 PILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
7749 populate the INTERFACE_COMPILE_FEATURES property of <target>.
7750 (IMPORTED targets only support INTERFACE items.) Repeated calls for
7751 the same <target> append items.
7752 The named <target> must have been created by a command such as add_exe‐
7754 cutable() or add_library() and must not be an ALIAS target.
7755 Arguments to target_compile_features may use “generator expressions”
7757 with the syntax $<...>. See the cmake-generator-expressions(7) manual
7758 for available expressions. See the cmake-compile-features(7) manual
7759 for information on compile features and a list of supported compilers.
7760 target_compile_options
7762 Add compile options to a target.
7763 target_compile_options(<target> [BEFORE]
7765 <INTERFACE|PUBLIC|PRIVATE> [items1...]
7766 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
7767 Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
7769 properties. These options are used when compiling the given <target>,
7770 which must have been created by a command such as add_executable() or
7771 add_library() and must not be an ALIAS target.
7772 Arguments
7774 If BEFORE is specified, the content will be prepended to the property
7775 instead of being appended.
7776 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
7778 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
7779 late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
7780 items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
7781 (IMPORTED targets only support INTERFACE items.) The following argu‐
7782 ments specify compile options. Repeated calls for the same <target>
7783 append items in the order called.
7784 Arguments to target_compile_options may use “generator expressions”
7786 with the syntax $<...>. See the cmake-generator-expressions(7) manual
7787 for available expressions. See the cmake-buildsystem(7) manual for
7788 more on defining buildsystem properties.
7789 The final set of compile or link options used for a target is con‐
7791 structed by accumulating options from the current target and the usage
7792 requirements of its dependencies. The set of options is de-duplicated
7793 to avoid repetition. While beneficial for individual options, the
7794 de-duplication step can break up option groups. For example, -D A -D B
7795 becomes -D A B. One may specify a group of options using shell-like
7796 quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and
7797 the rest of the option string is parsed using the separate_arguments()
7798 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
7799 -D B.
7800 See Also
7802 This command can be used to add any options. However, for adding pre‐
7803 processor definitions and include directories it is recommended to use
7804 the more specific commands target_compile_definitions() and tar‐
7805 get_include_directories().
7806 For directory-wide settings, there is the command add_com‐
7808 pile_options().
7809 For file-specific settings, there is the source file property COM‐
7811 PILE_OPTIONS.
7812 target_include_directories
7814 Add include directories to a target.
7815 target_include_directories(<target> [SYSTEM] [BEFORE]
7817 <INTERFACE|PUBLIC|PRIVATE> [items1...]
7818 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
7819 Specifies include directories to use when compiling a given target.
7821 The named <target> must have been created by a command such as add_exe‐
7822 cutable() or add_library() and must not be an ALIAS target.
7823 If BEFORE is specified, the content will be prepended to the property
7825 instead of being appended.
7826 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
7828 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
7829 late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTER‐
7830 FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
7831 <target>. (IMPORTED targets only support INTERFACE items.) The fol‐
7832 lowing arguments specify include directories.
7833 Specified include directories may be absolute paths or relative paths.
7835 Repeated calls for the same <target> append items in the order called.
7836 If SYSTEM is specified, the compiler will be told the directories are
7837 meant as system include directories on some platforms (signalling this
7838 setting might achieve effects such as the compiler skipping warnings,
7839 or these fixed-install system files not being considered in dependency
7840 calculations - see compiler docs). If SYSTEM is used together with
7841 PUBLIC or INTERFACE, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
7842 property will be populated with the specified directories.
7843 Arguments to target_include_directories may use “generator expressions”
7845 with the syntax $<...>. See the cmake-generator-expressions(7) manual
7846 for available expressions. See the cmake-buildsystem(7) manual for
7847 more on defining buildsystem properties.
7848 Include directories usage requirements commonly differ between the
7850 build-tree and the install-tree. The BUILD_INTERFACE and
7851 INSTALL_INTERFACE generator expressions can be used to describe sepa‐
7852 rate usage requirements based on the usage location. Relative paths
7853 are allowed within the INSTALL_INTERFACE expression and are interpreted
7854 relative to the installation prefix. For example:
7855 target_include_directories(mylib PUBLIC
7857 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
7858 $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
7859 )
7860 Creating Relocatable Packages
7862 Note that it is not advisable to populate the INSTALL_INTERFACE of the
7863 INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
7864 include directories of dependencies. That would hard-code into
7865 installed packages the include directory paths for dependencies as
7866 found on the machine the package was made on.
7867 The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
7869 suitable for specifying the required include directories for headers
7870 provided with the target itself, not those provided by the transitive
7871 dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
7872 Those dependencies should themselves be targets that specify their own
7873 header locations in INTERFACE_INCLUDE_DIRECTORIES.
7874 See the Creating Relocatable Packages section of the cmake-packages(7)
7876 manual for discussion of additional care that must be taken when speci‐
7877 fying usage requirements while creating packages for redistribution.
7878 target_link_directories
7880 New in version 3.13.
7881 Add link directories to a target.
7884 target_link_directories(<target> [BEFORE]
7886 <INTERFACE|PUBLIC|PRIVATE> [items1...]
7887 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
7888 Specifies the paths in which the linker should search for libraries
7890 when linking a given target. Each item can be an absolute or relative
7891 path, with the latter being interpreted as relative to the current
7892 source directory. These items will be added to the link command.
7893 The named <target> must have been created by a command such as add_exe‐
7895 cutable() or add_library() and must not be an ALIAS target.
7896 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
7898 scope of the items that follow them. PRIVATE and PUBLIC items will
7899 populate the LINK_DIRECTORIES property of <target>. PUBLIC and INTER‐
7900 FACE items will populate the INTERFACE_LINK_DIRECTORIES property of
7901 <target> (IMPORTED targets only support INTERFACE items). Each item
7902 specifies a link directory and will be converted to an absolute path if
7903 necessary before adding it to the relevant property. Repeated calls
7904 for the same <target> append items in the order called.
7905 If BEFORE is specified, the content will be prepended to the relevant
7907 property instead of being appended.
7908 Arguments to target_link_directories may use “generator expressions”
7910 with the syntax $<...>. See the cmake-generator-expressions(7) manual
7911 for available expressions. See the cmake-buildsystem(7) manual for
7912 more on defining buildsystem properties.
7913 NOTE:
7915 This command is rarely necessary and should be avoided where there
7916 are other choices. Prefer to pass full absolute paths to libraries
7917 where possible, since this ensures the correct library will always
7918 be linked. The find_library() command provides the full path, which
7919 can generally be used directly in calls to target_link_libraries().
7920 Situations where a library search path may be needed include:
7921 · Project generators like Xcode where the user can switch target
7923 architecture at build time, but a full path to a library cannot be
7924 used because it only provides one architecture (i.e. it is not a
7925 universal binary).
7926 · Libraries may themselves have other private library dependencies
7928 that expect to be found via RPATH mechanisms, but some linkers are
7929 not able to fully decode those paths (e.g. due to the presence of
7930 things like $ORIGIN).
7931 target_link_libraries
7933 Specify libraries or flags to use when linking a given target and/or
7934 its dependents. Usage requirements from linked library targets will be
7935 propagated. Usage requirements of a target’s dependencies affect com‐
7936 pilation of its own sources.
7937 Overview
7939 This command has several signatures as detailed in subsections below.
7940 All of them have the general form
7941 target_link_libraries(<target> ... <item>... ...)
7943 The named <target> must have been created by a command such as add_exe‐
7945 cutable() or add_library() and must not be an ALIAS target. If policy
7946 CMP0079 is not set to NEW then the target must have been created in the
7947 current directory. Repeated calls for the same <target> append items
7948 in the order called.
7949 Each <item> may be:
7951 · A library target name: The generated link line will have the full
7953 path to the linkable library file associated with the target. The
7954 buildsystem will have a dependency to re-link <target> if the library
7955 file changes.
7956 The named target must be created by add_library() within the project
7958 or as an IMPORTED library. If it is created within the project an
7959 ordering dependency will automatically be added in the build system
7960 to make sure the named library target is up-to-date before the <tar‐
7961 get> links.
7962 If an imported library has the IMPORTED_NO_SONAME target property
7964 set, CMake may ask the linker to search for the library instead of
7965 using the full path (e.g. /usr/lib/libfoo.so becomes -lfoo).
7966 The full path to the target’s artifact will be quoted/escaped for the
7968 shell automatically.
7969 · A full path to a library file: The generated link line will normally
7971 preserve the full path to the file. The buildsystem will have a
7972 dependency to re-link <target> if the library file changes.
7973 There are some cases where CMake may ask the linker to search for the
7975 library (e.g. /usr/lib/libfoo.so becomes -lfoo), such as when a
7976 shared library is detected to have no SONAME field. See policy
7977 CMP0060 for discussion of another case.
7978 If the library file is in a macOS framework, the Headers directory of
7980 the framework will also be processed as a usage requirement. This
7981 has the same effect as passing the framework directory as an include
7982 directory.
7983 On Visual Studio Generators for VS 2010 and above, library files end‐
7985 ing in .targets will be treated as MSBuild targets files and imported
7986 into generated project files. This is not supported by other genera‐
7987 tors.
7988 The full path to the library file will be quoted/escaped for the
7990 shell automatically.
7991 · A plain library name: The generated link line will ask the linker to
7993 search for the library (e.g. foo becomes -lfoo or foo.lib).
7994 The library name/flag is treated as a command-line string fragment
7996 and will be used with no extra quoting or escaping.
7997 · A link flag: Item names starting with -, but not -l or -framework,
7999 are treated as linker flags. Note that such flags will be treated
8000 like any other library link item for purposes of transitive dependen‐
8001 cies, so they are generally safe to specify only as private link
8002 items that will not propagate to dependents.
8003 Link flags specified here are inserted into the link command in the
8005 same place as the link libraries. This might not be correct, depend‐
8006 ing on the linker. Use the LINK_OPTIONS target property or tar‐
8007 get_link_options() command to add link flags explicitly. The flags
8008 will then be placed at the toolchain-defined flag position in the
8009 link command.
8010 The link flag is treated as a command-line string fragment and will
8012 be used with no extra quoting or escaping.
8013 · A generator expression: A $<...> generator expression may evaluate to
8015 any of the above items or to a semicolon-separated list of them. If
8016 the ... contains any ; characters, e.g. after evaluation of a ${list}
8017 variable, be sure to use an explicitly quoted argument "$<...>" so
8018 that this command receives it as a single <item>.
8019 Additionally, a generator expression may be used as a fragment of any
8021 of the above items, e.g. foo$<1:_d>.
8022 Note that generator expressions will not be used in OLD handling of
8024 policy CMP0003 or policy CMP0004.
8025 · A debug, optimized, or general keyword immediately followed by
8027 another <item>. The item following such a keyword will be used only
8028 for the corresponding build configuration. The debug keyword corre‐
8029 sponds to the Debug configuration (or to configurations named in the
8030 DEBUG_CONFIGURATIONS global property if it is set). The optimized
8031 keyword corresponds to all other configurations. The general keyword
8032 corresponds to all configurations, and is purely optional. Higher
8033 granularity may be achieved for per-configuration rules by creating
8034 and linking to IMPORTED library targets. These keywords are inter‐
8035 preted immediately by this command and therefore have no special
8036 meaning when produced by a generator expression.
8037 Items containing ::, such as Foo::Bar, are assumed to be IMPORTED or
8039 ALIAS library target names and will cause an error if no such target
8040 exists. See policy CMP0028.
8041 See the cmake-buildsystem(7) manual for more on defining buildsystem
8043 properties.
8044 Libraries for a Target and/or its Dependents
8046 target_link_libraries(<target>
8047 <PRIVATE|PUBLIC|INTERFACE> <item>...
8048 [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
8049 The PUBLIC, PRIVATE and INTERFACE keywords can be used to specify both
8051 the link dependencies and the link interface in one command. Libraries
8052 and targets following PUBLIC are linked to, and are made part of the
8053 link interface. Libraries and targets following PRIVATE are linked to,
8054 but are not made part of the link interface. Libraries following
8055 INTERFACE are appended to the link interface and are not used for link‐
8056 ing <target>.
8057 Libraries for both a Target and its Dependents
8059 target_link_libraries(<target> <item>...)
8060 Library dependencies are transitive by default with this signature.
8062 When this target is linked into another target then the libraries
8063 linked to this target will appear on the link line for the other target
8064 too. This transitive “link interface” is stored in the INTER‐
8065 FACE_LINK_LIBRARIES target property and may be overridden by setting
8066 the property directly. When CMP0022 is not set to NEW, transitive
8067 linking is built in but may be overridden by the LINK_INTER‐
8068 FACE_LIBRARIES property. Calls to other signatures of this command may
8069 set the property making any libraries linked exclusively by this signa‐
8070 ture private.
8071 Libraries for a Target and/or its Dependents (Legacy)
8073 target_link_libraries(<target>
8074 <LINK_PRIVATE|LINK_PUBLIC> <lib>...
8075 [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
8076 The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both the
8078 link dependencies and the link interface in one command.
8079 This signature is for compatibility only. Prefer the PUBLIC or PRIVATE
8081 keywords instead.
8082 Libraries and targets following LINK_PUBLIC are linked to, and are made
8084 part of the INTERFACE_LINK_LIBRARIES. If policy CMP0022 is not NEW,
8085 they are also made part of the LINK_INTERFACE_LIBRARIES. Libraries and
8086 targets following LINK_PRIVATE are linked to, but are not made part of
8087 the INTERFACE_LINK_LIBRARIES (or LINK_INTERFACE_LIBRARIES).
8088 Libraries for Dependents Only (Legacy)
8090 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
8091 The LINK_INTERFACE_LIBRARIES mode appends the libraries to the INTER‐
8093 FACE_LINK_LIBRARIES target property instead of using them for linking.
8094 If policy CMP0022 is not NEW, then this mode also appends libraries to
8095 the LINK_INTERFACE_LIBRARIES and its per-configuration equivalent.
8096 This signature is for compatibility only. Prefer the INTERFACE mode
8098 instead.
8099 Libraries specified as debug are wrapped in a generator expression to
8101 correspond to debug builds. If policy CMP0022 is not NEW, the
8102 libraries are also appended to the LINK_INTERFACE_LIBRARIES_DEBUG prop‐
8103 erty (or to the properties corresponding to configurations listed in
8104 the DEBUG_CONFIGURATIONS global property if it is set). Libraries
8105 specified as optimized are appended to the INTERFACE_LINK_LIBRARIES
8106 property. If policy CMP0022 is not NEW, they are also appended to the
8107 LINK_INTERFACE_LIBRARIES property. Libraries specified as general (or
8108 without any keyword) are treated as if specified for both debug and
8109 optimized.
8110 Linking Object Libraries
8112 Object Libraries may be used as the <target> (first) argument of tar‐
8113 get_link_libraries to specify dependencies of their sources on other
8114 libraries. For example, the code
8115 add_library(A SHARED a.c)
8117 target_compile_definitions(A PUBLIC A)
8118 add_library(obj OBJECT obj.c)
8120 target_compile_definitions(obj PUBLIC OBJ)
8121 target_link_libraries(obj PUBLIC A)
8122 compiles obj.c with -DA -DOBJ and establishes usage requirements for
8124 obj that propagate to its dependents.
8125 Normal libraries and executables may link to Object Libraries to get
8127 their objects and usage requirements. Continuing the above example,
8128 the code
8129 add_library(B SHARED b.c)
8131 target_link_libraries(B PUBLIC obj)
8132 compiles b.c with -DA -DOBJ, creates shared library B with object files
8134 from b.c and obj.c, and links B to A. Furthermore, the code
8135 add_executable(main main.c)
8137 target_link_libraries(main B)
8138 compiles main.c with -DA -DOBJ and links executable main to B and A.
8140 The object library’s usage requirements are propagated transitively
8141 through B, but its object files are not.
8142 Object Libraries may “link” to other object libraries to get usage
8144 requirements, but since they do not have a link step nothing is done
8145 with their object files. Continuing from the above example, the code:
8146 add_library(obj2 OBJECT obj2.c)
8148 target_link_libraries(obj2 PUBLIC obj)
8149 add_executable(main2 main2.c)
8151 target_link_libraries(main2 obj2)
8152 compiles obj2.c with -DA -DOBJ, creates executable main2 with object
8154 files from main2.c and obj2.c, and links main2 to A.
8155 In other words, when Object Libraries appear in a target’s INTER‐
8157 FACE_LINK_LIBRARIES property they will be treated as Interface
8158 Libraries, but when they appear in a target’s LINK_LIBRARIES property
8159 their object files will be included in the link too.
8160 Cyclic Dependencies of Static Libraries
8162 The library dependency graph is normally acyclic (a DAG), but in the
8163 case of mutually-dependent STATIC libraries CMake allows the graph to
8164 contain cycles (strongly connected components). When another target
8165 links to one of the libraries, CMake repeats the entire connected com‐
8166 ponent. For example, the code
8167 add_library(A STATIC a.c)
8169 add_library(B STATIC b.c)
8170 target_link_libraries(A B)
8171 target_link_libraries(B A)
8172 add_executable(main main.c)
8173 target_link_libraries(main A)
8174 links main to A B A B. While one repetition is usually sufficient,
8176 pathological object file and symbol arrangements can require more. One
8177 may handle such cases by using the LINK_INTERFACE_MULTIPLICITY target
8178 property or by manually repeating the component in the last tar‐
8179 get_link_libraries call. However, if two archives are really so inter‐
8180 dependent they should probably be combined into a single archive, per‐
8181 haps by using Object Libraries.
8182 Creating Relocatable Packages
8184 Note that it is not advisable to populate the INTERFACE_LINK_LIBRARIES
8185 of a target with absolute paths to dependencies. That would hard-code
8186 into installed packages the library file paths for dependencies as
8187 found on the machine the package was made on.
8188 See the Creating Relocatable Packages section of the cmake-packages(7)
8190 manual for discussion of additional care that must be taken when speci‐
8191 fying usage requirements while creating packages for redistribution.
8192 target_link_options
8194 New in version 3.13.
8195 Add options to the link step for an executable, shared library or mod‐
8198 ule library target.
8199 target_link_options(<target> [BEFORE]
8201 <INTERFACE|PUBLIC|PRIVATE> [items1...]
8202 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
8203 The named <target> must have been created by a command such as add_exe‐
8205 cutable() or add_library() and must not be an ALIAS target.
8206 This command can be used to add any link options, but alternative com‐
8208 mands exist to add libraries (target_link_libraries() or
8209 link_libraries()). See documentation of the directory and target
8210 LINK_OPTIONS properties.
8211 NOTE:
8213 This command cannot be used to add options for static library tar‐
8214 gets, since they do not use a linker. To add archiver or MSVC
8215 librarian flags, see the STATIC_LIBRARY_OPTIONS target property.
8216 If BEFORE is specified, the content will be prepended to the property
8218 instead of being appended.
8219 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
8221 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
8222 late the LINK_OPTIONS property of <target>. PUBLIC and INTERFACE items
8223 will populate the INTERFACE_LINK_OPTIONS property of <target>.
8224 (IMPORTED targets only support INTERFACE items.) The following argu‐
8225 ments specify link options. Repeated calls for the same <target>
8226 append items in the order called.
8227 Arguments to target_link_options may use “generator expressions” with
8229 the syntax $<...>. See the cmake-generator-expressions(7) manual for
8230 available expressions. See the cmake-buildsystem(7) manual for more on
8231 defining buildsystem properties.
8232 When a device link step is involved, which is controlled by CUDA_SEPA‐
8234 RABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS properties and policy
8235 CMP0105, the raw options will be delivered to the host and device link
8236 steps (wrapped in -Xcompiler or equivalent for device link). Options
8237 wrapped with $<DEVICE_LINK:...> generator expression will be used only
8238 for the device link step. Options wrapped with $<HOST_LINK:...> genera‐
8239 tor expression will be used only for the host link step.
8240 The final set of compile or link options used for a target is con‐
8242 structed by accumulating options from the current target and the usage
8243 requirements of its dependencies. The set of options is de-duplicated
8244 to avoid repetition. While beneficial for individual options, the
8245 de-duplication step can break up option groups. For example, -D A -D B
8246 becomes -D A B. One may specify a group of options using shell-like
8247 quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and
8248 the rest of the option string is parsed using the separate_arguments()
8249 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
8250 -D B.
8251 To pass options to the linker tool, each compiler driver has its own
8253 syntax. The LINKER: prefix and , separator can be used to specify, in
8254 a portable way, options to pass to the linker tool. LINKER: is replaced
8255 by the appropriate driver option and , by the appropriate driver sepa‐
8256 rator. The driver prefix and driver separator are given by the values
8257 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAP‐
8258 PER_FLAG_SEP variables.
8259 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
8261 Clang and -Wl,-z,defs for GNU GCC.
8262 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
8264 sion.
8265 The LINKER: prefix supports, as an alternative syntax, specification of
8267 arguments using the SHELL: prefix and space as separator. The previous
8268 example then becomes "LINKER:SHELL:-z defs".
8269 NOTE:
8271 Specifying the SHELL: prefix anywhere other than at the beginning of
8272 the LINKER: prefix is not supported.
8273 target_precompile_headers
8275 New in version 3.16.
8276 Add a list of header files to precompile.
8279 Precompiling header files can speed up compilation by creating a par‐
8281 tially processed version of some header files, and then using that ver‐
8282 sion during compilations rather than repeatedly parsing the original
8283 headers.
8284 Main Form
8286 target_precompile_headers(<target>
8287 <INTERFACE|PUBLIC|PRIVATE> [header1...]
8288 [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])
8289 The command adds header files to the PRECOMPILE_HEADERS and/or INTER‐
8291 FACE_PRECOMPILE_HEADERS target properties of <target>. The named <tar‐
8292 get> must have been created by a command such as add_executable() or
8293 add_library() and must not be an ALIAS target.
8294 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
8296 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
8297 late the PRECOMPILE_HEADERS property of <target>. PUBLIC and INTERFACE
8298 items will populate the INTERFACE_PRECOMPILE_HEADERS property of <tar‐
8299 get> (IMPORTED targets only support INTERFACE items). Repeated calls
8300 for the same <target> will append items in the order called.
8301 Projects should generally avoid using PUBLIC or INTERFACE for targets
8303 that will be exported, or they should at least use the $<BUILD_INTER‐
8304 FACE:...> generator expression to prevent precompile headers from
8305 appearing in an installed exported target. Consumers of a target
8306 should typically be in control of what precompile headers they use, not
8307 have precompile headers forced on them by the targets being consumed
8308 (since precompile headers are not typically usage requirements). A
8309 notable exception to this is where an interface library is created to
8310 define a commonly used set of precompile headers in one place and then
8311 other targets link to that interface library privately. In this case,
8312 the interface library exists specifically to propagate the precompile
8313 headers to its consumers and the consumer is effectively still in con‐
8314 trol, since it decides whether to link to the interface library or not.
8315 The list of header files is used to generate a header file named
8317 cmake_pch.h|xx which is used to generate the precompiled header file
8318 (.pch, .gch, .pchi) artifact. The cmake_pch.h|xx header file will be
8319 force included (-include for GCC, /FI for MSVC) to all source files, so
8320 sources do not need to have #include "pch.h".
8321 Header file names specified with angle brackets (e.g. <unordered_map>)
8323 or explicit double quotes (escaped for the cmake-language(7), e.g.
8324 [["other_header.h"]]) will be treated as is, and include directories
8325 must be available for the compiler to find them. Other header file
8326 names (e.g. project_header.h) are interpreted as being relative to the
8327 current source directory (e.g. CMAKE_CURRENT_SOURCE_DIR) and will be
8328 included by absolute path. For example:
8329 target_precompile_headers(myTarget
8331 PUBLIC
8332 project_header.h
8333 PRIVATE
8334 [["other_header.h"]]
8335 <unordered_map>
8336 )
8337 Arguments to target_precompile_headers() may use “generator expres‐
8339 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
8340 manual for available expressions. The $<COMPILE_LANGUAGE:...> genera‐
8341 tor expression is particularly useful for specifying a language-spe‐
8342 cific header to precompile for only one language (e.g. CXX and not C).
8343 In this case, header file names that are not explicitly in double
8344 quotes or angle brackets must be specified by absolute path. Also,
8345 when specifying angle brackets inside a generator expression, be sure
8346 to encode the closing > as $<ANGLE-R>. For example:
8347 target_precompile_headers(mylib PRIVATE
8349 "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/cxx_only.h>"
8350 "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
8351 "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
8352 )
8353 Reusing Precompile Headers
8355 The command also supports a second signature which can be used to spec‐
8356 ify that one target re-uses a precompiled header file artifact from
8357 another target instead of generating its own:
8358 target_precompile_headers(<target> REUSE_FROM <other_target>)
8360 This form sets the PRECOMPILE_HEADERS_REUSE_FROM property to
8362 <other_target> and adds a dependency such that <target> will depend on
8363 <other_target>. CMake will halt with an error if the PRECOMPILE_HEAD‐
8364 ERS property of <target> is already set when the REUSE_FROM form is
8365 used.
8366 NOTE:
8368 The REUSE_FROM form requires the same set of compiler options, com‐
8369 piler flags and compiler definitions for both <target> and
8370 <other_target>. Some compilers (e.g. GCC) may issue a warning if
8371 the precompiled header file cannot be used (-Winvalid-pch).
8372 See Also
8374 To disable precompile headers for specific targets, see the DIS‐
8375 ABLE_PRECOMPILE_HEADERS target property.
8376 To prevent precompile headers from being used when compiling a specific
8378 source file, see the SKIP_PRECOMPILE_HEADERS source file property.
8379 target_sources
8381 New in version 3.1.
8382 Add sources to a target.
8385 target_sources(<target>
8387 <INTERFACE|PUBLIC|PRIVATE> [items1...]
8388 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
8389 Specifies sources to use when building a target and/or its dependents.
8391 Relative source file paths are interpreted as being relative to the
8392 current source directory (i.e. CMAKE_CURRENT_SOURCE_DIR). The named
8393 <target> must have been created by a command such as add_executable()
8394 or add_library() and must not be an ALIAS target.
8395 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
8397 scope of the items following them. PRIVATE and PUBLIC items will popu‐
8398 late the SOURCES property of <target>, which are used when building the
8399 target itself. PUBLIC and INTERFACE items will populate the INTER‐
8400 FACE_SOURCES property of <target>, which are used when building depen‐
8401 dents. (IMPORTED targets only support INTERFACE items because they are
8402 not build targets.) The following arguments specify sources. Repeated
8403 calls for the same <target> append items in the order called.
8404 Arguments to target_sources may use “generator expressions” with the
8406 syntax $<...>. See the cmake-generator-expressions(7) manual for avail‐
8407 able expressions. See the cmake-buildsystem(7) manual for more on
8408 defining buildsystem properties.
8409 See also the CMP0076 policy for older behavior related to the handling
8411 of relative source file paths.
8412 try_compile
8414 Try building some code.
8415 Try Compiling Whole Projects
8417 try_compile(<resultVar> <bindir> <srcdir>
8418 <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
8419 [OUTPUT_VARIABLE <var>])
8420 Try building a project. The success or failure of the try_compile,
8422 i.e. TRUE or FALSE respectively, is returned in <resultVar>.
8423 In this form, <srcdir> should contain a complete CMake project with a
8425 CMakeLists.txt file and all sources. The <bindir> and <srcdir> will
8426 not be deleted after this command is run. Specify <targetName> to
8427 build a specific target instead of the all or ALL_BUILD target. See
8428 below for the meaning of other options.
8429 Try Compiling Source Files
8431 try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
8432 [CMAKE_FLAGS <flags>...]
8433 [COMPILE_DEFINITIONS <defs>...]
8434 [LINK_OPTIONS <options>...]
8435 [LINK_LIBRARIES <libs>...]
8436 [OUTPUT_VARIABLE <var>]
8437 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
8438 [<LANG>_STANDARD <std>]
8439 [<LANG>_STANDARD_REQUIRED <bool>]
8440 [<LANG>_EXTENSIONS <bool>]
8441 )
8442 Try building an executable or static library from one or more source
8444 files (which one is determined by the CMAKE_TRY_COMPILE_TARGET_TYPE
8445 variable). The success or failure of the try_compile, i.e. TRUE or
8446 FALSE respectively, is returned in <resultVar>.
8447 In this form, one or more source files must be provided. If
8449 CMAKE_TRY_COMPILE_TARGET_TYPE is unset or is set to EXECUTABLE, the
8450 sources must include a definition for main and CMake will create a
8451 CMakeLists.txt file to build the source(s) as an executable. If
8452 CMAKE_TRY_COMPILE_TARGET_TYPE is set to STATIC_LIBRARY, a static
8453 library will be built instead and no definition for main is required.
8454 For an executable, the generated CMakeLists.txt file would contain
8455 something like the following:
8456 add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
8458 include_directories(${INCLUDE_DIRECTORIES})
8459 link_directories(${LINK_DIRECTORIES})
8460 add_executable(cmTryCompileExec <srcfile>...)
8461 target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
8462 target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
8463 The options are:
8465 CMAKE_FLAGS <flags>...
8467 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
8468 cmake command-line used to drive the test build. The above
8469 example shows how values for variables INCLUDE_DIRECTORIES,
8470 LINK_DIRECTORIES, and LINK_LIBRARIES are used.
8471 COMPILE_DEFINITIONS <defs>...
8473 Specify -Ddefinition arguments to pass to add_definitions() in
8474 the generated test project.
8475 COPY_FILE <fileName>
8477 Copy the built executable or static library to the given <file‐
8478 Name>.
8479 COPY_FILE_ERROR <var>
8481 Use after COPY_FILE to capture into variable <var> any error
8482 message encountered while trying to copy the file.
8483 LINK_LIBRARIES <libs>...
8485 Specify libraries to be linked in the generated project. The
8486 list of libraries may refer to system libraries and to Imported
8487 Targets from the calling project.
8488 If this option is specified, any -DLINK_LIBRARIES=... value
8490 given to the CMAKE_FLAGS option will be ignored.
8491 LINK_OPTIONS <options>...
8493 Specify link step options to pass to target_link_options() or to
8494 set the STATIC_LIBRARY_OPTIONS target property in the generated
8495 project, depending on the CMAKE_TRY_COMPILE_TARGET_TYPE vari‐
8496 able.
8497 OUTPUT_VARIABLE <var>
8499 Store the output from the build process in the given variable.
8500 <LANG>_STANDARD <std>
8502 Specify the C_STANDARD, CXX_STANDARD, OBJC_STANDARD,
8503 OBJCXX_STANDARD, or CUDA_STANDARD target property of the gener‐
8504 ated project.
8505 <LANG>_STANDARD_REQUIRED <bool>
8507 Specify the C_STANDARD_REQUIRED, CXX_STANDARD_REQUIRED,
8508 OBJC_STANDARD_REQUIRED, OBJCXX_STANDARD_REQUIRED,or CUDA_STAN‐
8509 DARD_REQUIRED target property of the generated project.
8510 <LANG>_EXTENSIONS <bool>
8512 Specify the C_EXTENSIONS, CXX_EXTENSIONS, OBJC_EXTENSIONS,
8513 OBJCXX_EXTENSIONS, or CUDA_EXTENSIONS target property of the
8514 generated project.
8515 In this version all files in <bindir>/CMakeFiles/CMakeTmp will be
8517 cleaned automatically. For debugging, --debug-trycompile can be passed
8518 to cmake to avoid this clean. However, multiple sequential try_compile
8519 operations reuse this single output directory. If you use
8520 --debug-trycompile, you can only debug one try_compile call at a time.
8521 The recommended procedure is to protect all try_compile calls in your
8522 project by if(NOT DEFINED <resultVar>) logic, configure with cmake all
8523 the way through once, then delete the cache entry associated with the
8524 try_compile call of interest, and then re-run cmake again with
8525 --debug-trycompile.
8526 Other Behavior Settings
8528 If set, the following variables are passed in to the generated try_com‐
8529 pile CMakeLists.txt to initialize compile target properties with
8530 default values:
8531 · CMAKE_CUDA_RUNTIME_LIBRARY
8533 · CMAKE_ENABLE_EXPORTS
8535 · CMAKE_LINK_SEARCH_START_STATIC
8537 · CMAKE_LINK_SEARCH_END_STATIC
8539 · CMAKE_MSVC_RUNTIME_LIBRARY
8541 · CMAKE_POSITION_INDEPENDENT_CODE
8543 If CMP0056 is set to NEW, then CMAKE_EXE_LINKER_FLAGS is passed in as
8545 well.
8546 If CMP0083 is set to NEW, then in order to obtain correct behavior at
8548 link time, the check_pie_supported() command from the CheckPIESupported
8549 module must be called before using the try_compile() command.
8550 The current settings of CMP0065 and CMP0083 are propagated through to
8552 the generated test project.
8553 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
8555 figuration.
8556 Set the CMAKE_TRY_COMPILE_TARGET_TYPE variable to specify the type of
8558 target used for the source file signature.
8559 Set the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable to specify vari‐
8561 ables that must be propagated into the test project. This variable is
8562 meant for use only in toolchain files and is only honored by the
8563 try_compile() command for the source files form, not when given a whole
8564 project.
8565 If CMP0067 is set to NEW, or any of the <LANG>_STANDARD, <LANG>_STAN‐
8567 DARD_REQUIRED, or <LANG>_EXTENSIONS options are used, then the language
8568 standard variables are honored:
8569 · CMAKE_C_STANDARD
8571 · CMAKE_C_STANDARD_REQUIRED
8573 · CMAKE_C_EXTENSIONS
8575 · CMAKE_CXX_STANDARD
8577 · CMAKE_CXX_STANDARD_REQUIRED
8579 · CMAKE_CXX_EXTENSIONS
8581 · CMAKE_OBJC_STANDARD
8583 · CMAKE_OBJC_STANDARD_REQUIRED
8585 · CMAKE_OBJC_EXTENSIONS
8587 · CMAKE_OBJCXX_STANDARD
8589 · CMAKE_OBJCXX_STANDARD_REQUIRED
8591 · CMAKE_OBJCXX_EXTENSIONS
8593 · CMAKE_CUDA_STANDARD
8595 · CMAKE_CUDA_STANDARD_REQUIRED
8597 · CMAKE_CUDA_EXTENSIONS
8599 Their values are used to set the corresponding target properties in the
8601 generated project (unless overridden by an explicit option).
8602 For the Green Hills MULTI generator the GHS toolset and target system
8604 customization cache variables are also propagated into the test
8605 project.
8606 try_run
8608 Try compiling and then running some code.
8609 Try Compiling and Running Source Files
8611 try_run(<runResultVar> <compileResultVar>
8612 <bindir> <srcfile> [CMAKE_FLAGS <flags>...]
8613 [COMPILE_DEFINITIONS <defs>...]
8614 [LINK_OPTIONS <options>...]
8615 [LINK_LIBRARIES <libs>...]
8616 [COMPILE_OUTPUT_VARIABLE <var>]
8617 [RUN_OUTPUT_VARIABLE <var>]
8618 [OUTPUT_VARIABLE <var>]
8619 [ARGS <args>...])
8620 Try compiling a <srcfile>. Returns TRUE or FALSE for success or fail‐
8622 ure in <compileResultVar>. If the compile succeeded, runs the exe‐
8623 cutable and returns its exit code in <runResultVar>. If the executable
8624 was built, but failed to run, then <runResultVar> will be set to
8625 FAILED_TO_RUN. See the try_compile() command for information on how
8626 the test project is constructed to build the source file.
8627 The options are:
8629 CMAKE_FLAGS <flags>...
8631 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
8632 cmake command-line used to drive the test build. The example in
8633 try_compile() shows how values for variables INCLUDE_DIRECTO‐
8634 RIES, LINK_DIRECTORIES, and LINK_LIBRARIES are used.
8635 COMPILE_DEFINITIONS <defs>...
8637 Specify -Ddefinition arguments to pass to add_definitions() in
8638 the generated test project.
8639 COMPILE_OUTPUT_VARIABLE <var>
8641 Report the compile step build output in a given variable.
8642 LINK_LIBRARIES <libs>...
8644 Specify libraries to be linked in the generated project. The
8645 list of libraries may refer to system libraries and to Imported
8646 Targets from the calling project.
8647 If this option is specified, any -DLINK_LIBRARIES=... value
8649 given to the CMAKE_FLAGS option will be ignored.
8650 LINK_OPTIONS <options>...
8652 Specify link step options to pass to target_link_options() in
8653 the generated project.
8654 OUTPUT_VARIABLE <var>
8656 Report the compile build output and the output from running the
8657 executable in the given variable. This option exists for legacy
8658 reasons. Prefer COMPILE_OUTPUT_VARIABLE and RUN_OUTPUT_VARIABLE
8659 instead.
8660 RUN_OUTPUT_VARIABLE <var>
8662 Report the output from running the executable in a given vari‐
8663 able.
8664 Other Behavior Settings
8666 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
8667 figuration.
8668 Behavior when Cross Compiling
8670 When cross compiling, the executable compiled in the first step usually
8671 cannot be run on the build host. The try_run command checks the
8672 CMAKE_CROSSCOMPILING variable to detect whether CMake is in cross-com‐
8673 piling mode. If that is the case, it will still try to compile the
8674 executable, but it will not try to run the executable unless the
8675 CMAKE_CROSSCOMPILING_EMULATOR variable is set. Instead it will create
8676 cache variables which must be filled by the user or by presetting them
8677 in some CMake script file to the values the executable would have pro‐
8678 duced if it had been run on its actual target platform. These cache
8679 entries are:
8680 <runResultVar>
8682 Exit code if the executable were to be run on the target plat‐
8683 form.
8684 <runResultVar>__TRYRUN_OUTPUT
8686 Output from stdout and stderr if the executable were to be run
8687 on the target platform. This is created only if the RUN_OUT‐
8688 PUT_VARIABLE or OUTPUT_VARIABLE option was used.
8689 In order to make cross compiling your project easier, use try_run only
8691 if really required. If you use try_run, use the RUN_OUTPUT_VARIABLE or
8692 OUTPUT_VARIABLE options only if really required. Using them will
8693 require that when cross-compiling, the cache variables will have to be
8694 set manually to the output of the executable. You can also “guard” the
8695 calls to try_run with an if() block checking the CMAKE_CROSSCOMPILING
8696 variable and provide an easy-to-preset alternative for this case.
8697
8699 These commands are available only in CTest scripts.
8700 ctest_build
8702 Perform the CTest Build Step as a Dashboard Client.
8703 ctest_build([BUILD <build-dir>] [APPEND]
8705 [CONFIGURATION <config>]
8706 [FLAGS <flags>]
8707 [PROJECT_NAME <project-name>]
8708 [TARGET <target-name>]
8709 [NUMBER_ERRORS <num-err-var>]
8710 [NUMBER_WARNINGS <num-warn-var>]
8711 [RETURN_VALUE <result-var>]
8712 [CAPTURE_CMAKE_ERROR <result-var>]
8713 )
8714 Build the project and store results in Build.xml for submission with
8716 the ctest_submit() command.
8717 The CTEST_BUILD_COMMAND variable may be set to explicitly specify the
8719 build command line. Otherwise the build command line is computed auto‐
8720 matically based on the options given.
8721 The options are:
8723 BUILD <build-dir>
8725 Specify the top-level build directory. If not given, the
8726 CTEST_BINARY_DIRECTORY variable is used.
8727 APPEND Mark Build.xml for append to results previously submitted to a
8729 dashboard server since the last ctest_start() call. Append
8730 semantics are defined by the dashboard server in use. This does
8731 not cause results to be appended to a .xml file produced by a
8732 previous call to this command.
8733 CONFIGURATION <config>
8735 Specify the build configuration (e.g. Debug). If not specified
8736 the CTEST_BUILD_CONFIGURATION variable will be checked. Other‐
8737 wise the -C <cfg> option given to the ctest(1) command will be
8738 used, if any.
8739 FLAGS <flags>
8741 Pass additional arguments to the underlying build command. If
8742 not specified the CTEST_BUILD_FLAGS variable will be checked.
8743 This can, e.g., be used to trigger a parallel build using the -j
8744 option of make. See the ProcessorCount module for an example.
8745 PROJECT_NAME <project-name>
8747 Ignored. This was once used but is no longer needed.
8748 TARGET <target-name>
8750 Specify the name of a target to build. If not specified the
8751 CTEST_BUILD_TARGET variable will be checked. Otherwise the
8752 default target will be built. This is the “all” target (called
8753 ALL_BUILD in Visual Studio Generators).
8754 NUMBER_ERRORS <num-err-var>
8756 Store the number of build errors detected in the given variable.
8757 NUMBER_WARNINGS <num-warn-var>
8759 Store the number of build warnings detected in the given vari‐
8760 able.
8761 RETURN_VALUE <result-var>
8763 Store the return value of the native build tool in the given
8764 variable.
8765 CAPTURE_CMAKE_ERROR <result-var>
8767 Store in the <result-var> variable -1 if there are any errors
8768 running the command and prevent ctest from returning non-zero if
8769 an error occurs.
8770 QUIET Suppress any CTest-specific non-error output that would have
8772 been printed to the console otherwise. The summary of warnings
8773 / errors, as well as the output from the native build tool is
8774 unaffected by this option.
8775 ctest_configure
8777 Perform the CTest Configure Step as a Dashboard Client.
8778 ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
8780 [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
8781 [CAPTURE_CMAKE_ERROR <result-var>])
8782 Configure the project build tree and record results in Configure.xml
8784 for submission with the ctest_submit() command.
8785 The options are:
8787 BUILD <build-dir>
8789 Specify the top-level build directory. If not given, the
8790 CTEST_BINARY_DIRECTORY variable is used.
8791 SOURCE <source-dir>
8793 Specify the source directory. If not given, the
8794 CTEST_SOURCE_DIRECTORY variable is used.
8795 APPEND Mark Configure.xml for append to results previously submitted to
8797 a dashboard server since the last ctest_start() call. Append
8798 semantics are defined by the dashboard server in use. This does
8799 not cause results to be appended to a .xml file produced by a
8800 previous call to this command.
8801 OPTIONS <options>
8803 Specify command-line arguments to pass to the configuration
8804 tool.
8805 RETURN_VALUE <result-var>
8807 Store in the <result-var> variable the return value of the
8808 native configuration tool.
8809 CAPTURE_CMAKE_ERROR <result-var>
8811 Store in the <result-var> variable -1 if there are any errors
8812 running the command and prevent ctest from returning non-zero if
8813 an error occurs.
8814 QUIET Suppress any CTest-specific non-error messages that would have
8816 otherwise been printed to the console. Output from the underly‐
8817 ing configure command is not affected.
8818 ctest_coverage
8820 Perform the CTest Coverage Step as a Dashboard Client.
8821 ctest_coverage([BUILD <build-dir>] [APPEND]
8823 [LABELS <label>...]
8824 [RETURN_VALUE <result-var>]
8825 [CAPTURE_CMAKE_ERROR <result-var>]
8826 [QUIET]
8827 )
8828 Collect coverage tool results and stores them in Coverage.xml for sub‐
8830 mission with the ctest_submit() command.
8831 The options are:
8833 BUILD <build-dir>
8835 Specify the top-level build directory. If not given, the
8836 CTEST_BINARY_DIRECTORY variable is used.
8837 APPEND Mark Coverage.xml for append to results previously submitted to
8839 a dashboard server since the last ctest_start() call. Append
8840 semantics are defined by the dashboard server in use. This does
8841 not cause results to be appended to a .xml file produced by a
8842 previous call to this command.
8843 LABELS Filter the coverage report to include only source files labeled
8845 with at least one of the labels specified.
8846 RETURN_VALUE <result-var>
8848 Store in the <result-var> variable 0 if coverage tools ran with‐
8849 out error and non-zero otherwise.
8850 CAPTURE_CMAKE_ERROR <result-var>
8852 Store in the <result-var> variable -1 if there are any errors
8853 running the command and prevent ctest from returning non-zero if
8854 an error occurs.
8855 QUIET Suppress any CTest-specific non-error output that would have
8857 been printed to the console otherwise. The summary indicating
8858 how many lines of code were covered is unaffected by this
8859 option.
8860 ctest_empty_binary_directory
8862 empties the binary directory
8863 ctest_empty_binary_directory( directory )
8865 Removes a binary directory. This command will perform some checks
8867 prior to deleting the directory in an attempt to avoid malicious or
8868 accidental directory deletion.
8869 ctest_memcheck
8871 Perform the CTest MemCheck Step as a Dashboard Client.
8872 ctest_memcheck([BUILD <build-dir>] [APPEND]
8874 [START <start-number>]
8875 [END <end-number>]
8876 [STRIDE <stride-number>]
8877 [EXCLUDE <exclude-regex>]
8878 [INCLUDE <include-regex>]
8879 [EXCLUDE_LABEL <label-exclude-regex>]
8880 [INCLUDE_LABEL <label-include-regex>]
8881 [EXCLUDE_FIXTURE <regex>]
8882 [EXCLUDE_FIXTURE_SETUP <regex>]
8883 [EXCLUDE_FIXTURE_CLEANUP <regex>]
8884 [PARALLEL_LEVEL <level>]
8885 [TEST_LOAD <threshold>]
8886 [SCHEDULE_RANDOM <ON|OFF>]
8887 [STOP_TIME <time-of-day>]
8888 [RETURN_VALUE <result-var>]
8889 [DEFECT_COUNT <defect-count-var>]
8890 [QUIET]
8891 )
8892 Run tests with a dynamic analysis tool and store results in Mem‐
8894 Check.xml for submission with the ctest_submit() command.
8895 Most options are the same as those for the ctest_test() command.
8897 The options unique to this command are:
8899 DEFECT_COUNT <defect-count-var>
8901 Store in the <defect-count-var> the number of defects found.
8902 ctest_read_custom_files
8904 read CTestCustom files.
8905 ctest_read_custom_files( directory ... )
8907 Read all the CTestCustom.ctest or CTestCustom.cmake files from the
8909 given directory.
8910 By default, invoking ctest(1) without a script will read custom files
8912 from the binary directory.
8913 ctest_run_script
8915 runs a ctest -S script
8916 ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
8918 script_file_name2 ... [RETURN_VALUE var])
8919 Runs a script or scripts much like if it was run from ctest -S. If no
8921 argument is provided then the current script is run using the current
8922 settings of the variables. If NEW_PROCESS is specified then each
8923 script will be run in a separate process.If RETURN_VALUE is specified
8924 the return value of the last script run will be put into var.
8925 ctest_sleep
8927 sleeps for some amount of time
8928 ctest_sleep(<seconds>)
8930 Sleep for given number of seconds.
8932 ctest_sleep(<time1> <duration> <time2>)
8934 Sleep for t=(time1 + duration - time2) seconds if t > 0.
8936 ctest_start
8938 Starts the testing for a given model
8939 ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])
8941 ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET])
8943 Starts the testing for a given model. The command should be called
8945 after the binary directory is initialized.
8946 The parameters are as follows:
8948 <model>
8950 Set the dashboard model. Must be one of Experimental, Continu‐
8951 ous, or Nightly. This parameter is required unless APPEND is
8952 specified.
8953 <source>
8955 Set the source directory. If not specified, the value of
8956 CTEST_SOURCE_DIRECTORY is used instead.
8957 <binary>
8959 Set the binary directory. If not specified, the value of
8960 CTEST_BINARY_DIRECTORY is used instead.
8961 GROUP <group>
8963 If GROUP is used, the submissions will go to the specified group
8964 on the CDash server. If no GROUP is specified, the name of the
8965 model is used by default. This replaces the deprecated option
8966 TRACK. Despite the name change its behavior is unchanged.
8967 APPEND If APPEND is used, the existing TAG is used rather than creating
8969 a new one based on the current time stamp. If you use APPEND,
8970 you can omit the <model> and GROUP <group> parameters, because
8971 they will be read from the generated TAG file. For example:
8972 ctest_start(Experimental GROUP GroupExperimental)
8974 Later, in another ctest -S script:
8976 ctest_start(APPEND)
8978 When the second script runs ctest_start(APPEND), it will read
8980 the Experimental model and GroupExperimental group from the TAG
8981 file generated by the first ctest_start() command. Please note
8982 that if you call ctest_start(APPEND) and specify a different
8983 model or group than in the first ctest_start() command, a warn‐
8984 ing will be issued, and the new model and group will be used.
8985 QUIET If QUIET is used, CTest will suppress any non-error messages
8987 that it otherwise would have printed to the console.
8988 The parameters for ctest_start() can be issued in any order, with the
8990 exception that <model>, <source>, and <binary> have to appear in that
8991 order with respect to each other. The following are all valid and
8992 equivalent:
8993 ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND)
8995 ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary)
8997 ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary)
8999 However, for the sake of readability, it is recommended that you order
9001 your parameters in the order listed at the top of this page.
9002 If the CTEST_CHECKOUT_COMMAND variable (or the CTEST_CVS_CHECKOUT vari‐
9004 able) is set, its content is treated as command-line. The command is
9005 invoked with the current working directory set to the parent of the
9006 source directory, even if the source directory already exists. This
9007 can be used to create the source tree from a version control reposi‐
9008 tory.
9009 ctest_submit
9011 Perform the CTest Submit Step as a Dashboard Client.
9012 ctest_submit([PARTS <part>...] [FILES <file>...]
9014 [SUBMIT_URL <url>]
9015 [BUILD_ID <result-var>]
9016 [HTTPHEADER <header>]
9017 [RETRY_COUNT <count>]
9018 [RETRY_DELAY <delay>]
9019 [RETURN_VALUE <result-var>]
9020 [CAPTURE_CMAKE_ERROR <result-var>]
9021 [QUIET]
9022 )
9023 Submit results to a dashboard server. By default all available parts
9025 are submitted.
9026 The options are:
9028 PARTS <part>...
9030 Specify a subset of parts to submit. Valid part names are:
9031 Start = nothing
9033 Update = ctest_update results, in Update.xml
9034 Configure = ctest_configure results, in Configure.xml
9035 Build = ctest_build results, in Build.xml
9036 Test = ctest_test results, in Test.xml
9037 Coverage = ctest_coverage results, in Coverage.xml
9038 MemCheck = ctest_memcheck results, in DynamicAnalysis.xml
9039 Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
9040 ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
9041 Upload = Files prepared for upload by ctest_upload(), in Upload.xml
9042 Submit = nothing
9043 Done = Build is complete, in Done.xml
9044 FILES <file>...
9046 Specify an explicit list of specific files to be submitted.
9047 Each individual file must exist at the time of the call.
9048 SUBMIT_URL <url>
9050 The http or https URL of the dashboard server to send the sub‐
9051 mission to. If not given, the CTEST_SUBMIT_URL variable is
9052 used.
9053 BUILD_ID <result-var>
9055 Store in the <result-var> variable the ID assigned to this build
9056 by CDash.
9057 HTTPHEADER <HTTP-header>
9059 Specify HTTP header to be included in the request to CDash dur‐
9060 ing submission. For example, CDash can be configured to only
9061 accept submissions from authenticated clients. In this case, you
9062 should provide a bearer token in your header:
9063 ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>")
9065 This suboption can be repeated several times for multiple head‐
9067 ers.
9068 RETRY_COUNT <count>
9070 Specify how many times to retry a timed-out submission.
9071 RETRY_DELAY <delay>
9073 Specify how long (in seconds) to wait after a timed-out submis‐
9074 sion before attempting to re-submit.
9075 RETURN_VALUE <result-var>
9077 Store in the <result-var> variable 0 for success and non-zero on
9078 failure.
9079 CAPTURE_CMAKE_ERROR <result-var>
9081 Store in the <result-var> variable -1 if there are any errors
9082 running the command and prevent ctest from returning non-zero if
9083 an error occurs.
9084 QUIET Suppress all non-error messages that would have otherwise been
9086 printed to the console.
9087 Submit to CDash Upload API
9089 ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
9090 [SUBMIT_URL <url>]
9091 [HTTPHEADER <header>]
9092 [RETRY_COUNT <count>]
9093 [RETRY_DELAY <delay>]
9094 [RETURN_VALUE <result-var>]
9095 [QUIET])
9096 This second signature is used to upload files to CDash via the CDash
9098 file upload API. The API first sends a request to upload to CDash along
9099 with a content hash of the file. If CDash does not already have the
9100 file, then it is uploaded. Along with the file, a CDash type string is
9101 specified to tell CDash which handler to use to process the data.
9102 This signature accepts the SUBMIT_URL, BUILD_ID, HTTPHEADER,
9104 RETRY_COUNT, RETRY_DELAY, RETURN_VALUE and QUIET options as described
9105 above.
9106 ctest_test
9108 Perform the CTest Test Step as a Dashboard Client.
9109 ctest_test([BUILD <build-dir>] [APPEND]
9111 [START <start-number>]
9112 [END <end-number>]
9113 [STRIDE <stride-number>]
9114 [EXCLUDE <exclude-regex>]
9115 [INCLUDE <include-regex>]
9116 [EXCLUDE_LABEL <label-exclude-regex>]
9117 [INCLUDE_LABEL <label-include-regex>]
9118 [EXCLUDE_FIXTURE <regex>]
9119 [EXCLUDE_FIXTURE_SETUP <regex>]
9120 [EXCLUDE_FIXTURE_CLEANUP <regex>]
9121 [PARALLEL_LEVEL <level>]
9122 [RESOURCE_SPEC_FILE <file>]
9123 [TEST_LOAD <threshold>]
9124 [SCHEDULE_RANDOM <ON|OFF>]
9125 [STOP_ON_FAILURE]
9126 [STOP_TIME <time-of-day>]
9127 [RETURN_VALUE <result-var>]
9128 [CAPTURE_CMAKE_ERROR <result-var>]
9129 [REPEAT <mode>:<n>]
9130 [QUIET]
9131 )
9132 Run tests in the project build tree and store results in Test.xml for
9134 submission with the ctest_submit() command.
9135 The options are:
9137 BUILD <build-dir>
9139 Specify the top-level build directory. If not given, the
9140 CTEST_BINARY_DIRECTORY variable is used.
9141 APPEND Mark Test.xml for append to results previously submitted to a
9143 dashboard server since the last ctest_start() call. Append
9144 semantics are defined by the dashboard server in use. This does
9145 not cause results to be appended to a .xml file produced by a
9146 previous call to this command.
9147 START <start-number>
9149 Specify the beginning of a range of test numbers.
9150 END <end-number>
9152 Specify the end of a range of test numbers.
9153 STRIDE <stride-number>
9155 Specify the stride by which to step across a range of test num‐
9156 bers.
9157 EXCLUDE <exclude-regex>
9159 Specify a regular expression matching test names to exclude.
9160 INCLUDE <include-regex>
9162 Specify a regular expression matching test names to include.
9163 Tests not matching this expression are excluded.
9164 EXCLUDE_LABEL <label-exclude-regex>
9166 Specify a regular expression matching test labels to exclude.
9167 INCLUDE_LABEL <label-include-regex>
9169 Specify a regular expression matching test labels to include.
9170 Tests not matching this expression are excluded.
9171 EXCLUDE_FIXTURE <regex>
9173 If a test in the set of tests to be executed requires a particu‐
9174 lar fixture, that fixture’s setup and cleanup tests would nor‐
9175 mally be added to the test set automatically. This option pre‐
9176 vents adding setup or cleanup tests for fixtures matching the
9177 <regex>. Note that all other fixture behavior is retained,
9178 including test dependencies and skipping tests that have fixture
9179 setup tests that fail.
9180 EXCLUDE_FIXTURE_SETUP <regex>
9182 Same as EXCLUDE_FIXTURE except only matching setup tests are
9183 excluded.
9184 EXCLUDE_FIXTURE_CLEANUP <regex>
9186 Same as EXCLUDE_FIXTURE except only matching cleanup tests are
9187 excluded.
9188 PARALLEL_LEVEL <level>
9190 Specify a positive number representing the number of tests to be
9191 run in parallel.
9192 RESOURCE_SPEC_FILE <file>
9194 Specify a resource specification file. See ctest-resource-allo‐
9195 cation for more information.
9196 TEST_LOAD <threshold>
9198 While running tests in parallel, try not to start tests when
9199 they may cause the CPU load to pass above a given threshold. If
9200 not specified the CTEST_TEST_LOAD variable will be checked, and
9201 then the --test-load command-line argument to ctest(1). See
9202 also the TestLoad setting in the CTest Test Step.
9203 REPEAT <mode>:<n>
9205 Run tests repeatedly based on the given <mode> up to <n> times.
9206 The modes are:
9207 UNTIL_FAIL
9209 Require each test to run <n> times without failing in
9210 order to pass. This is useful in finding sporadic fail‐
9211 ures in test cases.
9212 UNTIL_PASS
9214 Allow each test to run up to <n> times in order to pass.
9215 Repeats tests if they fail for any reason. This is use‐
9216 ful in tolerating sporadic failures in test cases.
9217 AFTER_TIMEOUT
9219 Allow each test to run up to <n> times in order to pass.
9220 Repeats tests only if they timeout. This is useful in
9221 tolerating sporadic timeouts in test cases on busy
9222 machines.
9223 SCHEDULE_RANDOM <ON|OFF>
9225 Launch tests in a random order. This may be useful for detect‐
9226 ing implicit test dependencies.
9227 STOP_ON_FAILURE
9229 Stop the execution of the tests once one has failed.
9230 STOP_TIME <time-of-day>
9232 Specify a time of day at which the tests should all stop run‐
9233 ning.
9234 RETURN_VALUE <result-var>
9236 Store in the <result-var> variable 0 if all tests passed. Store
9237 non-zero if anything went wrong.
9238 CAPTURE_CMAKE_ERROR <result-var>
9240 Store in the <result-var> variable -1 if there are any errors
9241 running the command and prevent ctest from returning non-zero if
9242 an error occurs.
9243 QUIET Suppress any CTest-specific non-error messages that would have
9245 otherwise been printed to the console. Output from the underly‐
9246 ing test command is not affected. Summary info detailing the
9247 percentage of passing tests is also unaffected by the QUIET
9248 option.
9249 See also the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE and
9251 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables.
9252 ctest_update
9254 Perform the CTest Update Step as a Dashboard Client.
9255 ctest_update([SOURCE <source-dir>]
9257 [RETURN_VALUE <result-var>]
9258 [CAPTURE_CMAKE_ERROR <result-var>]
9259 [QUIET])
9260 Update the source tree from version control and record results in
9262 Update.xml for submission with the ctest_submit() command.
9263 The options are:
9265 SOURCE <source-dir>
9267 Specify the source directory. If not given, the
9268 CTEST_SOURCE_DIRECTORY variable is used.
9269 RETURN_VALUE <result-var>
9271 Store in the <result-var> variable the number of files updated
9272 or -1 on error.
9273 CAPTURE_CMAKE_ERROR <result-var>
9275 Store in the <result-var> variable -1 if there are any errors
9276 running the command and prevent ctest from returning non-zero if
9277 an error occurs.
9278 QUIET Tell CTest to suppress most non-error messages that it would
9280 have otherwise printed to the console. CTest will still report
9281 the new revision of the repository and any conflicting files
9282 that were found.
9283 The update always follows the version control branch currently checked
9285 out in the source directory. See the CTest Update Step documentation
9286 for information about variables that change the behavior of
9287 ctest_update().
9288 ctest_upload
9290 Upload files to a dashboard server as a Dashboard Client.
9291 ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
9293 The options are:
9295 FILES <file>...
9297 Specify a list of files to be sent along with the build results
9298 to the dashboard server.
9299 QUIET Suppress any CTest-specific non-error output that would have
9301 been printed to the console otherwise.
9302 CAPTURE_CMAKE_ERROR <result-var>
9304 Store in the <result-var> variable -1 if there are any errors
9305 running the command and prevent ctest from returning non-zero if
9306 an error occurs.
9307
9309 These commands are deprecated and are only made available to maintain
9310 backward compatibility. The documentation of each command states the
9311 CMake version in which it was deprecated. Do not use these commands in
9312 new code.
9313 build_name
9315 Disallowed since version 3.0. See CMake Policy CMP0036.
9316 Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.
9318 build_name(variable)
9320 Sets the specified variable to a string representing the platform and
9322 compiler settings. These values are now available through the
9323 CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
9324 exec_program
9326 Deprecated since version 3.0: Use the execute_process() command
9327 instead.
9328 Run an executable program during the processing of the CMakeList.txt
9331 file.
9332 exec_program(Executable [directory in which to run]
9334 [ARGS <arguments to executable>]
9335 [OUTPUT_VARIABLE <var>]
9336 [RETURN_VALUE <var>])
9337 The executable is run in the optionally specified directory. The exe‐
9339 cutable can include arguments if it is double quoted, but it is better
9340 to use the optional ARGS argument to specify arguments to the program.
9341 This is because cmake will then be able to escape spaces in the exe‐
9342 cutable path. An optional argument OUTPUT_VARIABLE specifies a vari‐
9343 able in which to store the output. To capture the return value of the
9344 execution, provide a RETURN_VALUE. If OUTPUT_VARIABLE is specified,
9345 then no output will go to the stdout/stderr of the console running
9346 cmake.
9347 export_library_dependencies
9349 Disallowed since version 3.0. See CMake Policy CMP0033.
9350 Use install(EXPORT) or export() command.
9352 This command generates an old-style library dependencies file.
9354 Projects requiring CMake 2.6 or later should not use the command. Use
9355 instead the install(EXPORT) command to help export targets from an
9356 installation tree and the export() command to export targets from a
9357 build tree.
9358 The old-style library dependencies file does not take into account
9360 per-configuration names of libraries or the LINK_INTERFACE_LIBRARIES
9361 target property.
9362 export_library_dependencies(<file> [APPEND])
9364 Create a file named <file> that can be included into a CMake listfile
9366 with the INCLUDE command. The file will contain a number of SET com‐
9367 mands that will set all the variables needed for library dependency
9368 information. This should be the last command in the top level CMake‐
9369 Lists.txt file of the project. If the APPEND option is specified, the
9370 SET commands will be appended to the given file instead of replacing
9371 it.
9372 install_files
9374 Deprecated since version 3.0: Use the install(FILES) command instead.
9375 This command has been superceded by the install() command. It is pro‐
9378 vided for compatibility with older CMake code. The FILES form is
9379 directly replaced by the FILES form of the install() command. The reg‐
9380 exp form can be expressed more clearly using the GLOB form of the
9381 file() command.
9382 install_files(<dir> extension file file ...)
9384 Create rules to install the listed files with the given extension into
9386 the given directory. Only files existing in the current source tree or
9387 its corresponding location in the binary tree may be listed. If a file
9388 specified already has an extension, that extension will be removed
9389 first. This is useful for providing lists of source files such as
9390 foo.cxx when you want the corresponding foo.h to be installed. A typi‐
9391 cal extension is .h.
9392 install_files(<dir> regexp)
9394 Any files in the current source directory that match the regular
9396 expression will be installed.
9397 install_files(<dir> FILES file file ...)
9399 Any files listed after the FILES keyword will be installed explicitly
9401 from the names given. Full paths are allowed in this form.
9402 The directory <dir> is relative to the installation prefix, which is
9404 stored in the variable CMAKE_INSTALL_PREFIX.
9405 install_programs
9407 Deprecated since version 3.0: Use the install(PROGRAMS) command
9408 instead.
9409 This command has been superceded by the install() command. It is pro‐
9412 vided for compatibility with older CMake code. The FILES form is
9413 directly replaced by the PROGRAMS form of the install() command. The
9414 regexp form can be expressed more clearly using the GLOB form of the
9415 file() command.
9416 install_programs(<dir> file1 file2 [file3 ...])
9418 install_programs(<dir> FILES file1 [file2 ...])
9419 Create rules to install the listed programs into the given directory.
9421 Use the FILES argument to guarantee that the file list version of the
9422 command will be used even when there is only one argument.
9423 install_programs(<dir> regexp)
9425 In the second form any program in the current source directory that
9427 matches the regular expression will be installed.
9428 This command is intended to install programs that are not built by
9430 cmake, such as shell scripts. See the TARGETS form of the install()
9431 command to create installation rules for targets built by cmake.
9432 The directory <dir> is relative to the installation prefix, which is
9434 stored in the variable CMAKE_INSTALL_PREFIX.
9435 install_targets
9437 Deprecated since version 3.0: Use the install(TARGETS) command instead.
9438 This command has been superceded by the install() command. It is pro‐
9441 vided for compatibility with older CMake code.
9442 install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
9444 Create rules to install the listed targets into the given directory.
9446 The directory <dir> is relative to the installation prefix, which is
9447 stored in the variable CMAKE_INSTALL_PREFIX. If RUNTIME_DIRECTORY is
9448 specified, then on systems with special runtime files (Windows DLL),
9449 the files will be copied to that directory.
9450 load_command
9452 Disallowed since version 3.0. See CMake Policy CMP0031.
9453 Load a command into a running CMake.
9455 load_command(COMMAND_NAME <loc1> [loc2 ...])
9457 The given locations are searched for a library whose name is cmCOM‐
9459 MAND_NAME. If found, it is loaded as a module and the command is added
9460 to the set of available CMake commands. Usually, try_compile() is used
9461 before this command to compile the module. If the command is success‐
9462 fully loaded a variable named
9463 CMAKE_LOADED_COMMAND_<COMMAND_NAME>
9465 will be set to the full path of the module that was loaded. Otherwise
9467 the variable will not be set.
9468 make_directory
9470 Deprecated since version 3.0: Use the file(MAKE_DIRECTORY) command
9471 instead.
9472 make_directory(directory)
9475 Creates the specified directory. Full paths should be given. Any par‐
9477 ent directories that do not exist will also be created. Use with care.
9478 output_required_files
9480 Disallowed since version 3.0. See CMake Policy CMP0032.
9481 Approximate C preprocessor dependency scanning.
9483 This command exists only because ancient CMake versions provided it.
9485 CMake handles preprocessor dependency scanning automatically using a
9486 more advanced scanner.
9487 output_required_files(srcfile outputfile)
9489 Outputs a list of all the source files that are required by the speci‐
9491 fied srcfile. This list is written into outputfile. This is similar
9492 to writing out the dependencies for srcfile except that it jumps from
9493 .h files into .cxx, .c and .cpp files if possible.
9494 qt_wrap_cpp
9496 Deprecated since version 3.14: This command was originally added to
9497 support Qt 3 before the add_custom_command() command was sufficiently
9498 mature. The FindQt4 module provides the qt4_wrap_cpp() macro, which
9499 should be used instead for Qt 4 projects. For projects using Qt 5 or
9500 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
9501 vides qt5_wrap_cpp()).
9502 Manually create Qt Wrappers.
9505 qt_wrap_cpp(resultingLibraryName DestName SourceLists ...)
9507 Produces moc files for all the .h files listed in the SourceLists. The
9509 moc files will be added to the library using the DestName source list.
9510 Consider updating the project to use the AUTOMOC target property
9512 instead for a more automated way of invoking the moc tool.
9513 qt_wrap_ui
9515 Deprecated since version 3.14: This command was originally added to
9516 support Qt 3 before the add_custom_command() command was sufficiently
9517 mature. The FindQt4 module provides the qt4_wrap_ui() macro, which
9518 should be used instead for Qt 4 projects. For projects using Qt 5 or
9519 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
9520 vides qt5_wrap_ui()).
9521 Manually create Qt user interfaces Wrappers.
9524 qt_wrap_ui(resultingLibraryName HeadersDestName
9526 SourcesDestName SourceLists ...)
9527 Produces .h and .cxx files for all the .ui files listed in the
9529 SourceLists. The .h files will be added to the library using the Head‐
9530 ersDestNamesource list. The .cxx files will be added to the library
9531 using the SourcesDestNamesource list.
9532 Consider updating the project to use the AUTOUIC target property
9534 instead for a more automated way of invoking the uic tool.
9535 remove
9537 Deprecated since version 3.0: Use the list(REMOVE_ITEM) command
9538 instead.
9539 remove(VAR VALUE VALUE ...)
9542 Removes VALUE from the variable VAR. This is typically used to remove
9544 entries from a vector (e.g. semicolon separated list). VALUE is
9545 expanded.
9546 subdir_depends
9548 Disallowed since version 3.0. See CMake Policy CMP0029.
9549 Does nothing.
9551 subdir_depends(subdir dep1 dep2 ...)
9553 Does not do anything. This command used to help projects order paral‐
9555 lel builds correctly. This functionality is now automatic.
9556 subdirs
9558 Deprecated since version 3.0: Use the add_subdirectory() command
9559 instead.
9560 Add a list of subdirectories to the build.
9563 subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
9565 [PREORDER] )
9566 Add a list of subdirectories to the build. The add_subdirectory() com‐
9568 mand should be used instead of subdirs although subdirs will still
9569 work. This will cause any CMakeLists.txt files in the sub directories
9570 to be processed by CMake. Any directories after the PREORDER flag are
9571 traversed first by makefile builds, the PREORDER flag has no effect on
9572 IDE projects. Any directories after the EXCLUDE_FROM_ALL marker will
9573 not be included in the top level makefile or project file. This is
9574 useful for having CMake create makefiles or projects for a set of exam‐
9575 ples in a project. You would want CMake to generate makefiles or
9576 project files for all the examples at the same time, but you would not
9577 want them to show up in the top level project or be built each time
9578 make is run from the top.
9579 use_mangled_mesa
9581 Disallowed since version 3.0. See CMake Policy CMP0030.
9582 Copy mesa headers for use in combination with system GL.
9584 use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
9586 The path to mesa includes, should contain gl_mangle.h. The mesa head‐
9588 ers are copied to the specified output directory. This allows mangled
9589 mesa headers to override other GL headers by being added to the include
9590 directory path earlier.
9591 utility_source
9593 Disallowed since version 3.0. See CMake Policy CMP0034.
9594 Specify the source tree of a third-party utility.
9596 utility_source(cache_entry executable_name
9598 path_to_source [file1 file2 ...])
9599 When a third-party utility’s source is included in the distribution,
9601 this command specifies its location and name. The cache entry will not
9602 be set unless the path_to_source and all listed files exist. It is
9603 assumed that the source tree of the utility will have been built before
9604 it is needed.
9605 When cross compiling CMake will print a warning if a utility_source()
9607 command is executed, because in many cases it is used to build an exe‐
9608 cutable which is executed later on. This doesn’t work when cross com‐
9609 piling, since the executable can run only on their target platform. So
9610 in this case the cache entry has to be adjusted manually so it points
9611 to an executable which is runnable on the build host.
9612 variable_requires
9614 Disallowed since version 3.0. See CMake Policy CMP0035.
9615 Use the if() command instead.
9617 Assert satisfaction of an option’s required variables.
9619 variable_requires(TEST_VARIABLE RESULT_VARIABLE
9621 REQUIRED_VARIABLE1
9622 REQUIRED_VARIABLE2 ...)
9623 The first argument (TEST_VARIABLE) is the name of the variable to be
9625 tested, if that variable is false nothing else is done. If TEST_VARI‐
9626 ABLE is true, then the next argument (RESULT_VARIABLE) is a variable
9627 that is set to true if all the required variables are set. The rest of
9628 the arguments are variables that must be true or not set to NOTFOUND to
9629 avoid an error. If any are not true, an error is reported.
9630 write_file
9632 Deprecated since version 3.0: Use the file(WRITE) command instead.
9633 write_file(filename "message to write"... [APPEND])
9636 The first argument is the file name, the rest of the arguments are mes‐
9638 sages to write. If the argument APPEND is specified, then the message
9639 will be appended.
9640 NOTE 1: file(WRITE) and file(APPEND) do exactly the same as this one
9642 but add some more functionality.
9643 NOTE 2: When using write_file the produced file cannot be used as an
9645 input to CMake (CONFIGURE_FILE, source file …) because it will lead to
9646 an infinite loop. Use configure_file() if you want to generate input
9647 files to CMake.
9648
9650 2000-2021 Kitware, Inc. and Contributors
96513.19.7 Mar 15, 2021 CMAKE-COMMANDS(7)