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_minimum_required
114 Require a minimum version of cmake.
115 cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR])
117 Sets the minimum required version of cmake for a project. Also updates
119 the policy settings as explained below.
120 <min> and the optional <max> are each CMake versions of the form
122 major.minor[.patch[.tweak]], and the ... is literal.
123 If the running version of CMake is lower than the <min> required ver‐
125 sion it will stop processing the project and report an error. The
126 optional <max> version, if specified, must be at least the <min> ver‐
127 sion and affects policy settings as described below. If the running
128 version of CMake is older than 3.12, the extra ... dots will be seen
129 as version component separators, resulting in the ...<max> part being
130 ignored and preserving the pre-3.12 behavior of basing policies on
131 <min>.
132 The FATAL_ERROR option is accepted but ignored by CMake 2.6 and higher.
134 It should be specified so CMake versions 2.4 and lower fail with an
135 error instead of just a warning.
136 NOTE:
138 Call the cmake_minimum_required() command at the beginning of the
139 top-level CMakeLists.txt file even before calling the project() com‐
140 mand. It is important to establish version and policy settings
141 before invoking other commands whose behavior they may affect. See
142 also policy CMP0000.
143 Calling cmake_minimum_required() inside a function() limits some
145 effects to the function scope when invoked. Such calls should not
146 be made with the intention of having global effects.
147 Policy Settings
149 The cmake_minimum_required(VERSION) command implicitly invokes the
150 cmake_policy(VERSION) command to specify that the current project code
151 is written for the given range of CMake versions. All policies known
152 to the running version of CMake and introduced in the <min> (or <max>,
153 if specified) version or earlier will be set to use NEW behavior. All
154 policies introduced in later versions will be unset. This effectively
155 requests behavior preferred as of a given CMake version and tells newer
156 CMake versions to warn about their new policies.
157 When a <min> version higher than 2.4 is specified the command implic‐
159 itly invokes
160 cmake_policy(VERSION <min>[...<max>])
162 which sets CMake policies based on the range of versions specified.
164 When a <min> version 2.4 or lower is given the command implicitly
165 invokes
166 cmake_policy(VERSION 2.4[...<max>])
168 which enables compatibility features for CMake 2.4 and lower.
170 cmake_parse_arguments
172 Parse function or macro arguments.
173 cmake_parse_arguments(<prefix> <options> <one_value_keywords>
175 <multi_value_keywords> <args>...)
176 cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
178 <one_value_keywords> <multi_value_keywords>)
179 This command is for use in macros or functions. It processes the argu‐
181 ments given to that macro or function, and defines a set of variables
182 which hold the values of the respective options.
183 The first signature reads processes arguments passed in the <args>....
185 This may be used in either a macro() or a function().
186 The PARSE_ARGV signature is only for use in a function() body. In this
188 case the arguments that are parsed come from the ARGV# variables of the
189 calling function. The parsing starts with the <N>-th argument, where
190 <N> is an unsigned integer. This allows for the values to have special
191 characters like ; in them.
192 The <options> argument contains all options for the respective macro,
194 i.e. keywords which can be used when calling the macro without any
195 value following, like e.g. the OPTIONAL keyword of the install() com‐
196 mand.
197 The <one_value_keywords> argument contains all keywords for this macro
199 which are followed by one value, like e.g. DESTINATION keyword of the
200 install() command.
201 The <multi_value_keywords> argument contains all keywords for this
203 macro which can be followed by more than one value, like e.g. the TAR‐
204 GETS or FILES keywords of the install() command.
205 NOTE:
207 All keywords shall be unique. I.e. every keyword shall only be spec‐
208 ified once in either <options>, <one_value_keywords> or
209 <multi_value_keywords>. A warning will be emitted if uniqueness is
210 violated.
211 When done, cmake_parse_arguments will consider for each of the keywords
213 listed in <options>, <one_value_keywords> and <multi_value_keywords> a
214 variable composed of the given <prefix> followed by "_" and the name of
215 the respective keyword. These variables will then hold the respective
216 value from the argument list or be undefined if the associated option
217 could not be found. For the <options> keywords, these will always be
218 defined, to TRUE or FALSE, whether the option is in the argument list
219 or not.
220 All remaining arguments are collected in a variable <pre‐
222 fix>_UNPARSED_ARGUMENTS that will be undefined if all argument where
223 recognized. This can be checked afterwards to see whether your macro
224 was called with unrecognized parameters.
225 As an example here a my_install() macro, which takes similar arguments
227 as the real install() command:
228 macro(my_install)
230 set(options OPTIONAL FAST)
231 set(oneValueArgs DESTINATION RENAME)
232 set(multiValueArgs TARGETS CONFIGURATIONS)
233 cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
234 "${multiValueArgs}" ${ARGN} )
235 # ...
237 Assume my_install() has been called like this:
239 my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub)
241 After the cmake_parse_arguments call the macro will have set or unde‐
243 fined the following variables:
244 MY_INSTALL_OPTIONAL = TRUE
246 MY_INSTALL_FAST = FALSE # was not used in call to my_install
247 MY_INSTALL_DESTINATION = "bin"
248 MY_INSTALL_RENAME <UNDEFINED> # was not used
249 MY_INSTALL_TARGETS = "foo;bar"
250 MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
251 MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
252 You can then continue and process these variables.
254 Keywords terminate lists of values, e.g. if directly after a
256 one_value_keyword another recognized keyword follows, this is inter‐
257 preted as the beginning of the new option. E.g. my_install(TARGETS
258 foo DESTINATION OPTIONAL) would result in MY_INSTALL_DESTINATION set to
259 "OPTIONAL", but as OPTIONAL is a keyword itself MY_INSTALL_DESTINATION
260 will be empty and MY_INSTALL_OPTIONAL will therefore be set to TRUE.
261 cmake_policy
263 Manage CMake Policy settings. See the cmake-policies(7) manual for
264 defined policies.
265 As CMake evolves it is sometimes necessary to change existing behavior
267 in order to fix bugs or improve implementations of existing features.
268 The CMake Policy mechanism is designed to help keep existing projects
269 building as new versions of CMake introduce changes in behavior. Each
270 new policy (behavioral change) is given an identifier of the form
271 CMP<NNNN> where <NNNN> is an integer index. Documentation associated
272 with each policy describes the OLD and NEW behavior and the reason the
273 policy was introduced. Projects may set each policy to select the
274 desired behavior. When CMake needs to know which behavior to use it
275 checks for a setting specified by the project. If no setting is avail‐
276 able the OLD behavior is assumed and a warning is produced requesting
277 that the policy be set.
278 Setting Policies by CMake Version
280 The cmake_policy command is used to set policies to OLD or NEW behav‐
281 ior. While setting policies individually is supported, we encourage
282 projects to set policies based on CMake versions:
283 cmake_policy(VERSION <min>[...<max>])
285 <min> and the optional <max> are each CMake versions of the form
287 major.minor[.patch[.tweak]], and the ... is literal. The <min> version
288 must be at least 2.4 and at most the running version of CMake. The
289 <max> version, if specified, must be at least the <min> version but may
290 exceed the running version of CMake. If the running version of CMake
291 is older than 3.12, the extra ... dots will be seen as version compo‐
292 nent separators, resulting in the ...<max> part being ignored and pre‐
293 serving the pre-3.12 behavior of basing policies on <min>.
294 This specifies that the current CMake code is written for the given
296 range of CMake versions. All policies known to the running version of
297 CMake and introduced in the <min> (or <max>, if specified) version or
298 earlier will be set to use NEW behavior. All policies introduced in
299 later versions will be unset (unless the CMAKE_POLICY_DEFAULT_CMP<NNNN>
300 variable sets a default). This effectively requests behavior preferred
301 as of a given CMake version and tells newer CMake versions to warn
302 about their new policies.
303 Note that the cmake_minimum_required(VERSION) command implicitly calls
305 cmake_policy(VERSION) too.
306 Setting Policies Explicitly
308 cmake_policy(SET CMP<NNNN> NEW)
309 cmake_policy(SET CMP<NNNN> OLD)
310 Tell CMake to use the OLD or NEW behavior for a given policy. Projects
312 depending on the old behavior of a given policy may silence a policy
313 warning by setting the policy state to OLD. Alternatively one may fix
314 the project to work with the new behavior and set the policy state to
315 NEW.
316 NOTE:
318 The OLD behavior of a policy is deprecated by definition and may be
319 removed in a future version of CMake.
320 Checking Policy Settings
322 cmake_policy(GET CMP<NNNN> <variable>)
323 Check whether a given policy is set to OLD or NEW behavior. The output
325 <variable> value will be OLD or NEW if the policy is set, and empty
326 otherwise.
327 CMake Policy Stack
329 CMake keeps policy settings on a stack, so changes made by the
330 cmake_policy command affect only the top of the stack. A new entry on
331 the policy stack is managed automatically for each subdirectory to pro‐
332 tect its parents and siblings. CMake also manages a new entry for
333 scripts loaded by include() and find_package() commands except when
334 invoked with the NO_POLICY_SCOPE option (see also policy CMP0011). The
335 cmake_policy command provides an interface to manage custom entries on
336 the policy stack:
337 cmake_policy(PUSH)
339 cmake_policy(POP)
340 Each PUSH must have a matching POP to erase any changes. This is use‐
342 ful to make temporary changes to policy settings. Calls to the
343 cmake_minimum_required(VERSION), cmake_policy(VERSION), or cmake_pol‐
344 icy(SET) commands influence only the current top of the policy stack.
345 Commands created by the function() and macro() commands record policy
347 settings when they are created and use the pre-record policies when
348 they are invoked. If the function or macro implementation sets poli‐
349 cies, the changes automatically propagate up through callers until they
350 reach the closest nested policy stack entry.
351 configure_file
353 Copy a file to another location and modify its contents.
354 configure_file(<input> <output>
356 [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
357 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
358 Copies an <input> file to an <output> file and substitutes variable
360 values referenced as @VAR@ or ${VAR} in the input file content. Each
361 variable reference will be replaced with the current value of the vari‐
362 able, or the empty string if the variable is not defined. Furthermore,
363 input lines of the form
364 #cmakedefine VAR ...
366 will be replaced with either
368 #define VAR ...
370 or
372 /* #undef VAR */
374 depending on whether VAR is set in CMake to any value not considered a
376 false constant by the if() command. The “…” content on the line after
377 the variable name, if any, is processed as above. Input file lines of
378 the form #cmakedefine01 VAR will be replaced with either #define VAR 1
379 or #define VAR 0 similarly. The result lines (with the exception of
380 the #undef comments) can be indented using spaces and/or tabs between
381 the # character and the cmakedefine or cmakedefine01 words. This white‐
382 space indentation will be preserved in the output lines:
383 # cmakedefine VAR
385 # cmakedefine01 VAR
386 will be replaced, if VAR is defined, with
388 # define VAR
390 # define VAR 1
391 If the input file is modified the build system will re-run CMake to
393 re-configure the file and generate the build system again. The gener‐
394 ated file is modified and its timestamp updated on subsequent cmake
395 runs only if its content is changed.
396 The arguments are:
398 <input>
400 Path to the input file. A relative path is treated with respect
401 to the value of CMAKE_CURRENT_SOURCE_DIR. The input path must
402 be a file, not a directory.
403 <output>
405 Path to the output file or directory. A relative path is
406 treated with respect to the value of CMAKE_CURRENT_BINARY_DIR.
407 If the path names an existing directory the output file is
408 placed in that directory with the same file name as the input
409 file.
410 COPYONLY
412 Copy the file without replacing any variable references or other
413 content. This option may not be used with NEWLINE_STYLE.
414 ESCAPE_QUOTES
416 Escape any substituted quotes with backslashes (C-style).
417 @ONLY Restrict variable replacement to references of the form @VAR@.
419 This is useful for configuring scripts that use ${VAR} syntax.
420 NEWLINE_STYLE <style>
422 Specify the newline style for the output file. Specify UNIX or
423 LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n new‐
424 lines. This option may not be used with COPYONLY.
425 Example
427 Consider a source tree containing a foo.h.in file:
428 #cmakedefine FOO_ENABLE
430 #cmakedefine FOO_STRING "@FOO_STRING@"
431 An adjacent CMakeLists.txt may use configure_file to configure the
433 header:
434 option(FOO_ENABLE "Enable Foo" ON)
436 if(FOO_ENABLE)
437 set(FOO_STRING "foo")
438 endif()
439 configure_file(foo.h.in foo.h @ONLY)
440 This creates a foo.h in the build directory corresponding to this
442 source directory. If the FOO_ENABLE option is on, the configured file
443 will contain:
444 #define FOO_ENABLE
446 #define FOO_STRING "foo"
447 Otherwise it will contain:
449 /* #undef FOO_ENABLE */
451 /* #undef FOO_STRING */
452 One may then use the include_directories() command to specify the out‐
454 put directory as an include directory:
455 include_directories(${CMAKE_CURRENT_BINARY_DIR})
457 so that sources may include the header as #include <foo.h>.
459 continue
461 Continue to the top of enclosing foreach or while loop.
462 continue()
464 The continue command allows a cmake script to abort the rest of a block
466 in a foreach() or while() loop, and start at the top of the next itera‐
467 tion.
468 See also the break() command.
470 else
472 Starts the else portion of an if block.
473 else([<condition>])
475 See the if() command.
477 elseif
479 Starts an elseif portion of an if block.
480 elseif(<condition>)
482 See the if() command, especially for the syntax and logic of the <con‐
484 dition>.
485 endforeach
487 Ends a list of commands in a foreach block.
488 endforeach([<loop_var>])
490 See the foreach() command.
492 The optional <loop_var> argument is supported for backward compatibil‐
494 ity only. If used it must be a verbatim repeat of the <loop_var> argu‐
495 ment of the opening foreach clause.
496 endfunction
498 Ends a list of commands in a function block.
499 endfunction([<name>])
501 See the function() command.
503 The optional <name> argument is supported for backward compatibility
505 only. If used it must be a verbatim repeat of the <name> argument of
506 the opening function command.
507 endif
509 Ends a list of commands in an if block.
510 endif([<condition>])
512 See the if() command.
514 The optional <condition> argument is supported for backward compatibil‐
516 ity only. If used it must be a verbatim repeat of the argument of the
517 opening if clause.
518 endmacro
520 Ends a list of commands in a macro block.
521 endmacro([<name>])
523 See the macro() command.
525 The optional <name> argument is supported for backward compatibility
527 only. If used it must be a verbatim repeat of the <name> argument of
528 the opening macro command.
529 endwhile
531 Ends a list of commands in a while block.
532 endwhile([<condition>])
534 See the while() command.
536 The optional <condition> argument is supported for backward compatibil‐
538 ity only. If used it must be a verbatim repeat of the argument of the
539 opening while clause.
540 execute_process
542 Execute one or more child processes.
543 execute_process(COMMAND <cmd1> [<arguments>]
545 [COMMAND <cmd2> [<arguments>]]...
546 [WORKING_DIRECTORY <directory>]
547 [TIMEOUT <seconds>]
548 [RESULT_VARIABLE <variable>]
549 [RESULTS_VARIABLE <variable>]
550 [OUTPUT_VARIABLE <variable>]
551 [ERROR_VARIABLE <variable>]
552 [INPUT_FILE <file>]
553 [OUTPUT_FILE <file>]
554 [ERROR_FILE <file>]
555 [OUTPUT_QUIET]
556 [ERROR_QUIET]
557 [OUTPUT_STRIP_TRAILING_WHITESPACE]
558 [ERROR_STRIP_TRAILING_WHITESPACE]
559 [ENCODING <name>])
560 Runs the given sequence of one or more commands in parallel with the
562 standard output of each process piped to the standard input of the
563 next. A single standard error pipe is used for all processes.
564 Options:
566 COMMAND
568 A child process command line.
569 CMake executes the child process using operating system APIs
571 directly. All arguments are passed VERBATIM to the child
572 process. No intermediate shell is used, so shell operators such
573 as > are treated as normal arguments. (Use the INPUT_*, OUT‐
574 PUT_*, and ERROR_* options to redirect stdin, stdout, and
575 stderr.)
576 If a sequential execution of multiple commands is required, use
578 multiple execute_process() calls with a single COMMAND argument.
579 WORKING_DIRECTORY
581 The named directory will be set as the current working directory
582 of the child processes.
583 TIMEOUT
585 The child processes will be terminated if they do not finish in
586 the specified number of seconds (fractions are allowed).
587 RESULT_VARIABLE
589 The variable will be set to contain the result of last child
590 process. This will be an integer return code from the last
591 child or a string describing an error condition.
592 RESULTS_VARIABLE <variable>
594 The variable will be set to contain the result of all processes
595 as a semicolon-separated list, in order of the given COMMAND
596 arguments. Each entry will be an integer return code from the
597 corresponding child or a string describing an error condition.
598 OUTPUT_VARIABLE, ERROR_VARIABLE
600 The variable named will be set with the contents of the standard
601 output and standard error pipes, respectively. If the same
602 variable is named for both pipes their output will be merged in
603 the order produced.
604 INPUT_FILE, OUTPUT_FILE, ERROR_FILE
606 The file named will be attached to the standard input of the
607 first process, standard output of the last process, or standard
608 error of all processes, respectively. If the same file is named
609 for both output and error then it will be used for both.
610 OUTPUT_QUIET, ERROR_QUIET
612 The standard output or standard error results will be quietly
613 ignored.
614 ENCODING <name>
616 On Windows, the encoding that is used to decode output from the
617 process. Ignored on other platforms. Valid encoding names are:
618 NONE Perform no decoding. This assumes that the process out‐
620 put is encoded in the same way as CMake’s internal encod‐
621 ing (UTF-8). This is the default.
622 AUTO Use the current active console’s codepage or if that
624 isn’t available then use ANSI.
625 ANSI Use the ANSI codepage.
627 OEM Use the original equipment manufacturer (OEM) code page.
629 UTF8 or UTF-8
631 Use the UTF-8 codepage. Prior to CMake 3.11.0, only UTF8
632 was accepted for this encoding. In CMake 3.11.0, UTF-8
633 was added for consistency with the UTF-8 RFC naming con‐
634 vention.
635 If more than one OUTPUT_* or ERROR_* option is given for the same pipe
637 the precedence is not specified. If no OUTPUT_* or ERROR_* options are
638 given the output will be shared with the corresponding pipes of the
639 CMake process itself.
640 The execute_process() command is a newer more powerful version of
642 exec_program(), but the old command has been kept for compatibility.
643 Both commands run while CMake is processing the project prior to build
644 system generation. Use add_custom_target() and add_custom_command() to
645 create custom commands that run at build time.
646 file
648 File manipulation command.
649 Synopsis
651 Reading
652 file(READ <filename> <out-var> [...])
653 file(STRINGS <filename> <out-var> [...])
654 file(<HASH> <filename> <out-var>)
655 file(TIMESTAMP <filename> <out-var> [...])
656 Writing
658 file({WRITE | APPEND} <filename> <content>...)
659 file({TOUCH | TOUCH_NOCREATE} [<file>...])
660 file(GENERATE OUTPUT <output-file> [...])
661 Filesystem
663 file({GLOB | GLOB_RECURSE} <out-var> [...] [<globbing-expr>...])
664 file(RENAME <oldname> <newname>)
665 file({REMOVE | REMOVE_RECURSE } [<files>...])
666 file(MAKE_DIRECTORY [<dir>...])
667 file({COPY | INSTALL} <file>... DESTINATION <dir> [...])
668 file(SIZE <filename> <out-var>)
669 file(READ_SYMLINK <linkname> <out-var>)
670 file(CREATE_LINK <original> <linkname> [...])
671 Path Conversion
673 file(RELATIVE_PATH <out-var> <directory> <file>)
674 file({TO_CMAKE_PATH | TO_NATIVE_PATH} <path> <out-var>)
675 Transfer
677 file(DOWNLOAD <url> <file> [...])
678 file(UPLOAD <file> <url> [...])
679 Locking
681 file(LOCK <path> [...])
682 Reading
684 file(READ <filename> <variable>
685 [OFFSET <offset>] [LIMIT <max-in>] [HEX])
686 Read content from a file called <filename> and store it in a <vari‐
688 able>. Optionally start from the given <offset> and read at most
689 <max-in> bytes. The HEX option causes data to be converted to a hexa‐
690 decimal representation (useful for binary data).
691 file(STRINGS <filename> <variable> [<options>...])
693 Parse a list of ASCII strings from <filename> and store it in <vari‐
695 able>. Binary data in the file are ignored. Carriage return (\r, CR)
696 characters are ignored. The options are:
697 LENGTH_MAXIMUM <max-len>
699 Consider only strings of at most a given length.
700 LENGTH_MINIMUM <min-len>
702 Consider only strings of at least a given length.
703 LIMIT_COUNT <max-num>
705 Limit the number of distinct strings to be extracted.
706 LIMIT_INPUT <max-in>
708 Limit the number of input bytes to read from the file.
709 LIMIT_OUTPUT <max-out>
711 Limit the number of total bytes to store in the <variable>.
712 NEWLINE_CONSUME
714 Treat newline characters (\n, LF) as part of string content
715 instead of terminating at them.
716 NO_HEX_CONVERSION
718 Intel Hex and Motorola S-record files are automatically con‐
719 verted to binary while reading unless this option is given.
720 REGEX <regex>
722 Consider only strings that match the given regular expression.
723 ENCODING <encoding-type>
725 Consider strings of a given encoding. Currently supported
726 encodings are: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE.
727 If the ENCODING option is not provided and the file has a Byte
728 Order Mark, the ENCODING option will be defaulted to respect the
729 Byte Order Mark.
730 For example, the code
732 file(STRINGS myfile.txt myfile)
734 stores a list in the variable myfile in which each item is a line from
736 the input file.
737 file(<HASH> <filename> <variable>)
739 Compute a cryptographic hash of the content of <filename> and store it
741 in a <variable>. The supported <HASH> algorithm names are those listed
742 by the string(<HASH>) command.
743 file(TIMESTAMP <filename> <variable> [<format>] [UTC])
745 Compute a string representation of the modification time of <filename>
747 and store it in <variable>. Should the command be unable to obtain a
748 timestamp variable will be set to the empty string (“”).
749 See the string(TIMESTAMP) command for documentation of the <format> and
751 UTC options.
752 Writing
754 file(WRITE <filename> <content>...)
755 file(APPEND <filename> <content>...)
756 Write <content> into a file called <filename>. If the file does not
758 exist, it will be created. If the file already exists, WRITE mode will
759 overwrite it and APPEND mode will append to the end. Any directories
760 in the path specified by <filename> that do not exist will be created.
761 If the file is a build input, use the configure_file() command to
763 update the file only when its content changes.
764 file(TOUCH [<files>...])
766 file(TOUCH_NOCREATE [<files>...])
767 Create a file with no content if it does not yet exist. If the file
769 already exists, its access and/or modification will be updated to the
770 time when the function call is executed.
771 Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a
773 file does not exist it will be silently ignored.
774 With TOUCH and TOUCH_NOCREATE the contents of an existing file will not
776 be modified.
777 file(GENERATE OUTPUT output-file
779 <INPUT input-file|CONTENT content>
780 [CONDITION expression])
781 Generate an output file for each build configuration supported by the
783 current CMake Generator. Evaluate generator expressions from the input
784 content to produce the output content. The options are:
785 CONDITION <condition>
787 Generate the output file for a particular configuration only if
788 the condition is true. The condition must be either 0 or 1
789 after evaluating generator expressions.
790 CONTENT <content>
792 Use the content given explicitly as input.
793 INPUT <input-file>
795 Use the content from a given file as input. A relative path is
796 treated with respect to the value of CMAKE_CURRENT_SOURCE_DIR.
797 See policy CMP0070.
798 OUTPUT <output-file>
800 Specify the output file name to generate. Use generator expres‐
801 sions such as $<CONFIG> to specify a configuration-specific out‐
802 put file name. Multiple configurations may generate the same
803 output file only if the generated content is identical. Other‐
804 wise, the <output-file> must evaluate to an unique name for each
805 configuration. A relative path (after evaluating generator
806 expressions) is treated with respect to the value of CMAKE_CUR‐
807 RENT_BINARY_DIR. See policy CMP0070.
808 Exactly one CONTENT or INPUT option must be given. A specific OUTPUT
810 file may be named by at most one invocation of file(GENERATE). Gener‐
811 ated files are modified and their timestamp updated on subsequent cmake
812 runs only if their content is changed.
813 Note also that file(GENERATE) does not create the output file until the
815 generation phase. The output file will not yet have been written when
816 the file(GENERATE) command returns, it is written only after processing
817 all of a project’s CMakeLists.txt files.
818 Filesystem
820 file(GLOB <variable>
821 [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
822 [<globbing-expressions>...])
823 file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
824 [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
825 [<globbing-expressions>...])
826 Generate a list of files that match the <globbing-expressions> and
828 store it into the <variable>. Globbing expressions are similar to reg‐
829 ular expressions, but much simpler. If RELATIVE flag is specified, the
830 results will be returned as relative paths to the given path. The
831 results will be ordered lexicographically.
832 If the CONFIGURE_DEPENDS flag is specified, CMake will add logic to the
834 main build system check target to rerun the flagged GLOB commands at
835 build time. If any of the outputs change, CMake will regenerate the
836 build system.
837 By default GLOB lists directories - directories are omitted in result
839 if LIST_DIRECTORIES is set to false.
840 NOTE:
842 We do not recommend using GLOB to collect a list of source files
843 from your source tree. If no CMakeLists.txt file changes when a
844 source is added or removed then the generated build system cannot
845 know when to ask CMake to regenerate. The CONFIGURE_DEPENDS flag
846 may not work reliably on all generators, or if a new generator is
847 added in the future that cannot support it, projects using it will
848 be stuck. Even if CONFIGURE_DEPENDS works reliably, there is still a
849 cost to perform the check on every rebuild.
850 Examples of globbing expressions include:
852 *.cxx - match all files with extension cxx
854 *.vt? - match all files with extension vta,...,vtz
855 f[3-5].txt - match files f3.txt, f4.txt, f5.txt
856 The GLOB_RECURSE mode will traverse all the subdirectories of the
858 matched directory and match the files. Subdirectories that are sym‐
859 links are only traversed if FOLLOW_SYMLINKS is given or policy CMP0009
860 is not set to NEW.
861 By default GLOB_RECURSE omits directories from result list - setting
863 LIST_DIRECTORIES to true adds directories to result list. If FOL‐
864 LOW_SYMLINKS is given or policy CMP0009 is not set to OLD then
865 LIST_DIRECTORIES treats symlinks as directories.
866 Examples of recursive globbing include:
868 /dir/*.py - match all python files in /dir and subdirectories
870 file(RENAME <oldname> <newname>)
872 Move a file or directory within a filesystem from <oldname> to <new‐
874 name>, replacing the destination atomically.
875 file(REMOVE [<files>...])
877 file(REMOVE_RECURSE [<files>...])
878 Remove the given files. The REMOVE_RECURSE mode will remove the given
880 files and directories, also non-empty directories. No error is emitted
881 if a given file does not exist.
882 file(MAKE_DIRECTORY [<directories>...])
884 Create the given directories and their parents as needed.
886 file(<COPY|INSTALL> <files>... DESTINATION <dir>
888 [FILE_PERMISSIONS <permissions>...]
889 [DIRECTORY_PERMISSIONS <permissions>...]
890 [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
891 [FILES_MATCHING]
892 [[PATTERN <pattern> | REGEX <regex>]
893 [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
894 The COPY signature copies files, directories, and symlinks to a desti‐
896 nation folder. Relative input paths are evaluated with respect to the
897 current source directory, and a relative destination is evaluated with
898 respect to the current build directory. Copying preserves input file
899 timestamps, and optimizes out a file if it exists at the destination
900 with the same timestamp. Copying preserves input permissions unless
901 explicit permissions or NO_SOURCE_PERMISSIONS are given (default is
902 USE_SOURCE_PERMISSIONS).
903 See the install(DIRECTORY) command for documentation of permissions,
905 FILES_MATCHING, PATTERN, REGEX, and EXCLUDE options. Copying directo‐
906 ries preserves the structure of their content even if options are used
907 to select a subset of files.
908 The INSTALL signature differs slightly from COPY: it prints status mes‐
910 sages (subject to the CMAKE_INSTALL_MESSAGE variable), and
911 NO_SOURCE_PERMISSIONS is default. Installation scripts generated by
912 the install() command use this signature (with some undocumented
913 options for internal use).
914 file(SIZE <filename> <variable>)
916 Determine the file size of the <filename> and put the result in <vari‐
918 able> variable. Requires that <filename> is a valid path pointing to a
919 file and is readable.
920 file(READ_SYMLINK <linkname> <variable>)
922 This subcommand queries the symlink <linkname> and stores the path it
924 points to in the result <variable>. If <linkname> does not exist or is
925 not a symlink, CMake issues a fatal error.
926 Note that this command returns the raw symlink path and does not
928 resolve a relative path. The following is an example of how to ensure
929 that an absolute path is obtained:
930 set(linkname "/path/to/foo.sym")
932 file(READ_SYMLINK "${linkname}" result)
933 if(NOT IS_ABSOLUTE "${result}")
934 get_filename_component(dir "${linkname}" DIRECTORY)
935 set(result "${dir}/${result}")
936 endif()
937 file(CREATE_LINK <original> <linkname>
939 [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])
940 Create a link <linkname> that points to <original>. It will be a hard
942 link by default, but providing the SYMBOLIC option results in a sym‐
943 bolic link instead. Hard links require that original exists and is a
944 file, not a directory. If <linkname> already exists, it will be over‐
945 written.
946 The <result> variable, if specified, receives the status of the opera‐
948 tion. It is set to 0 upon success or an error message otherwise. If
949 RESULT is not specified and the operation fails, a fatal error is emit‐
950 ted.
951 Specifying COPY_ON_ERROR enables copying the file as a fallback if cre‐
953 ating the link fails. It can be useful for handling situations such as
954 <original> and <linkname> being on different drives or mount points,
955 which would make them unable to support a hard link.
956 Path Conversion
958 file(RELATIVE_PATH <variable> <directory> <file>)
959 Compute the relative path from a <directory> to a <file> and store it
961 in the <variable>.
962 file(TO_CMAKE_PATH "<path>" <variable>)
964 file(TO_NATIVE_PATH "<path>" <variable>)
965 The TO_CMAKE_PATH mode converts a native <path> into a cmake-style path
967 with forward-slashes (/). The input can be a single path or a system
968 search path like $ENV{PATH}. A search path will be converted to a
969 cmake-style list separated by ; characters.
970 The TO_NATIVE_PATH mode converts a cmake-style <path> into a native
972 path with platform-specific slashes (\ on Windows and / elsewhere).
973 Always use double quotes around the <path> to be sure it is treated as
975 a single argument to this command.
976 Transfer
978 file(DOWNLOAD <url> <file> [<options>...])
979 file(UPLOAD <file> <url> [<options>...])
980 The DOWNLOAD mode downloads the given <url> to a local <file>. The
982 UPLOAD mode uploads a local <file> to a given <url>.
983 Options to both DOWNLOAD and UPLOAD are:
985 INACTIVITY_TIMEOUT <seconds>
987 Terminate the operation after a period of inactivity.
988 LOG <variable>
990 Store a human-readable log of the operation in a variable.
991 SHOW_PROGRESS
993 Print progress information as status messages until the opera‐
994 tion is complete.
995 STATUS <variable>
997 Store the resulting status of the operation in a variable. The
998 status is a ; separated list of length 2. The first element is
999 the numeric return value for the operation, and the second ele‐
1000 ment is a string value for the error. A 0 numeric error means
1001 no error in the operation.
1002 TIMEOUT <seconds>
1004 Terminate the operation after a given total time has elapsed.
1005 USERPWD <username>:<password>
1007 Set username and password for operation.
1008 HTTPHEADER <HTTP-header>
1010 HTTP header for operation. Suboption can be repeated several
1011 times.
1012 NETRC <level>
1014 Specify whether the .netrc file is to be used for operation. If
1015 this option is not specified, the value of the CMAKE_NETRC vari‐
1016 able will be used instead. Valid levels are:
1017 IGNORED
1019 The .netrc file is ignored. This is the default.
1020 OPTIONAL
1022 The .netrc file is optional, and information in the URL
1023 is preferred. The file will be scanned to find which
1024 ever information is not specified in the URL.
1025 REQUIRED
1027 The .netrc file is required, and information in the URL
1028 is ignored.
1029 NETRC_FILE <file>
1031 Specify an alternative .netrc file to the one in your home
1032 directory, if the NETRC level is OPTIONAL or REQUIRED. If this
1033 option is not specified, the value of the CMAKE_NETRC_FILE vari‐
1034 able will be used instead.
1035 If neither NETRC option is given CMake will check variables CMAKE_NETRC
1037 and CMAKE_NETRC_FILE, respectively.
1038 Additional options to DOWNLOAD are:
1040 EXPECTED_HASH ALGO=<value>
1042 Verify that the downloaded content hash matches the expected value,
1043 where ALGO is one of the algorithms supported by file(<HASH>). If
1044 it does not match, the operation fails with an error.
1045 EXPECTED_MD5 <value>
1047 Historical short-hand for EXPECTED_HASH MD5=<value>.
1048 TLS_VERIFY <ON|OFF>
1050 Specify whether to verify the server certificate for https://
1051 URLs. The default is to not verify.
1052 TLS_CAINFO <file>
1054 Specify a custom Certificate Authority file for https:// URLs.
1055 For https:// URLs CMake must be built with OpenSSL support. TLS/SSL
1057 certificates are not checked by default. Set TLS_VERIFY to ON to check
1058 certificates and/or use EXPECTED_HASH to verify downloaded content. If
1059 neither TLS option is given CMake will check variables CMAKE_TLS_VERIFY
1060 and CMAKE_TLS_CAINFO, respectively.
1061 Locking
1063 file(LOCK <path> [DIRECTORY] [RELEASE]
1064 [GUARD <FUNCTION|FILE|PROCESS>]
1065 [RESULT_VARIABLE <variable>]
1066 [TIMEOUT <seconds>])
1067 Lock a file specified by <path> if no DIRECTORY option present and file
1069 <path>/cmake.lock otherwise. File will be locked for scope defined by
1070 GUARD option (default value is PROCESS). RELEASE option can be used to
1071 unlock file explicitly. If option TIMEOUT is not specified CMake will
1072 wait until lock succeed or until fatal error occurs. If TIMEOUT is set
1073 to 0 lock will be tried once and result will be reported immediately.
1074 If TIMEOUT is not 0 CMake will try to lock file for the period speci‐
1075 fied by <seconds> value. Any errors will be interpreted as fatal if
1076 there is no RESULT_VARIABLE option. Otherwise result will be stored in
1077 <variable> and will be 0 on success or error message on failure.
1078 Note that lock is advisory - there is no guarantee that other processes
1080 will respect this lock, i.e. lock synchronize two or more CMake
1081 instances sharing some modifiable resources. Similar logic applied to
1082 DIRECTORY option - locking parent directory doesn’t prevent other LOCK
1083 commands to lock any child directory or file.
1084 Trying to lock file twice is not allowed. Any intermediate directories
1086 and file itself will be created if they not exist. GUARD and TIMEOUT
1087 options ignored on RELEASE operation.
1088 find_file
1090 A short-hand signature is:
1091 find_file (<VAR> name1 [path1 path2 ...])
1093 The general signature is:
1095 find_file (
1097 <VAR>
1098 name | NAMES name1 [name2 ...]
1099 [HINTS path1 [path2 ... ENV var]]
1100 [PATHS path1 [path2 ... ENV var]]
1101 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1102 [DOC "cache documentation string"]
1103 [NO_DEFAULT_PATH]
1104 [NO_PACKAGE_ROOT_PATH]
1105 [NO_CMAKE_PATH]
1106 [NO_CMAKE_ENVIRONMENT_PATH]
1107 [NO_SYSTEM_ENVIRONMENT_PATH]
1108 [NO_CMAKE_SYSTEM_PATH]
1109 [CMAKE_FIND_ROOT_PATH_BOTH |
1110 ONLY_CMAKE_FIND_ROOT_PATH |
1111 NO_CMAKE_FIND_ROOT_PATH]
1112 )
1113 This command is used to find a full path to named file. A cache entry
1115 named by <VAR> is created to store the result of this command. If the
1116 full path to a file is found the result is stored in the variable and
1117 the search will not be repeated unless the variable is cleared. If
1118 nothing is found, the result will be <VAR>-NOTFOUND, and the search
1119 will be attempted again the next time find_file is invoked with the
1120 same variable.
1121 Options include:
1123 NAMES Specify one or more possible names for the full path to a file.
1125 When using this to specify names with and without a version suf‐
1127 fix, we recommend specifying the unversioned name first so that
1128 locally-built packages can be found before those provided by
1129 distributions.
1130 HINTS, PATHS
1132 Specify directories to search in addition to the default loca‐
1133 tions. The ENV var sub-option reads paths from a system envi‐
1134 ronment variable.
1135 PATH_SUFFIXES
1137 Specify additional subdirectories to check below each directory
1138 location otherwise considered.
1139 DOC Specify the documentation string for the <VAR> cache entry.
1141 If NO_DEFAULT_PATH is specified, then no additional paths are added to
1143 the search. If NO_DEFAULT_PATH is not specified, the search process is
1144 as follows:
1145 1. If called from within a find module loaded by find_package(<Package‐
1147 Name>), search prefixes unique to the current package being found.
1148 Specifically look in the <PackageName>_ROOT CMake variable and the
1149 <PackageName>_ROOT environment variable. The package root variables
1150 are maintained as a stack so if called from nested find modules,
1151 root paths from the parent’s find module will be searched after
1152 paths from the current module, i.e. <CurrentPackage>_ROOT, ENV{<Cur‐
1153 rentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT},
1154 etc. This can be skipped if NO_PACKAGE_ROOT_PATH is passed. See
1155 policy CMP0074.
1156 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1158 <prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
1159 variable and the <PackageName>_ROOT environment variable if called
1160 from within a find module loaded by find_package(<PackageName>)
1161 2. Search paths specified in cmake-specific cache variables. These are
1163 intended to be used on the command line with a -DVAR=value. The
1164 values are interpreted as semicolon-separated lists. This can be
1165 skipped if NO_CMAKE_PATH is passed.
1166 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1168 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1169 · CMAKE_INCLUDE_PATH
1171 · CMAKE_FRAMEWORK_PATH
1173 3. Search paths specified in cmake-specific environment variables.
1175 These are intended to be set in the user’s shell configuration, and
1176 therefore use the host’s native path separator (; on Windows and :
1177 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1178 passed.
1179 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1181 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1182 · CMAKE_INCLUDE_PATH
1184 · CMAKE_FRAMEWORK_PATH
1186 4. Search the paths specified by the HINTS option. These should be
1188 paths computed by system introspection, such as a hint provided by
1189 the location of another item already found. Hard-coded guesses
1190 should be specified with the PATHS option.
1191 5. Search the standard system environment variables. This can be
1193 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1194 · Directories in INCLUDE. On Windows hosts: <prefix>/include/<arch>
1196 if CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/include for
1197 each <prefix>/[s]bin in PATH, and <entry>/include for other
1198 entries in PATH, and the directories in PATH itself.
1199 6. Search cmake variables defined in the Platform files for the current
1201 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed.
1202 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1204 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1205 · CMAKE_SYSTEM_INCLUDE_PATH
1207 · CMAKE_SYSTEM_FRAMEWORK_PATH
1209 7. Search the paths specified by the PATHS option or in the short-hand
1211 version of the command. These are typically hard-coded guesses.
1212 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
1214 determine the order of preference between Apple-style and unix-style
1215 package components.
1216 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
1218 ries to be prepended to all other search directories. This effectively
1219 “re-roots” the entire search under given locations. Paths which are
1220 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
1221 ing, because that variable is always a path on the host system. By
1222 default the CMAKE_FIND_ROOT_PATH is empty.
1223 The CMAKE_SYSROOT variable can also be used to specify exactly one
1225 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
1226 effects. See the documentation for that variable for more.
1227 These variables are especially useful when cross-compiling to point to
1229 the root directory of the target environment and CMake will search
1230 there too. By default at first the directories listed in
1231 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
1232 searched, and then the non-rooted directories will be searched. The
1233 default behavior can be adjusted by setting
1234 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually over‐
1235 ridden on a per-call basis using options:
1236 CMAKE_FIND_ROOT_PATH_BOTH
1238 Search in the order described above.
1239 NO_CMAKE_FIND_ROOT_PATH
1241 Do not use the CMAKE_FIND_ROOT_PATH variable.
1242 ONLY_CMAKE_FIND_ROOT_PATH
1244 Search only the re-rooted directories and directories below
1245 CMAKE_STAGING_PREFIX.
1246 The default search order is designed to be most-specific to least-spe‐
1248 cific for common use cases. Projects may override the order by simply
1249 calling the command multiple times and using the NO_* options:
1250 find_file (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1252 find_file (<VAR> NAMES name)
1253 Once one of the calls succeeds the result variable will be set and
1255 stored in the cache so that no call will search again.
1256 find_library
1258 A short-hand signature is:
1259 find_library (<VAR> name1 [path1 path2 ...])
1261 The general signature is:
1263 find_library (
1265 <VAR>
1266 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
1267 [HINTS path1 [path2 ... ENV var]]
1268 [PATHS path1 [path2 ... ENV var]]
1269 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1270 [DOC "cache documentation string"]
1271 [NO_DEFAULT_PATH]
1272 [NO_PACKAGE_ROOT_PATH]
1273 [NO_CMAKE_PATH]
1274 [NO_CMAKE_ENVIRONMENT_PATH]
1275 [NO_SYSTEM_ENVIRONMENT_PATH]
1276 [NO_CMAKE_SYSTEM_PATH]
1277 [CMAKE_FIND_ROOT_PATH_BOTH |
1278 ONLY_CMAKE_FIND_ROOT_PATH |
1279 NO_CMAKE_FIND_ROOT_PATH]
1280 )
1281 This command is used to find a library. A cache entry named by <VAR>
1283 is created to store the result of this command. If the library is
1284 found the result is stored in the variable and the search will not be
1285 repeated unless the variable is cleared. If nothing is found, the
1286 result will be <VAR>-NOTFOUND, and the search will be attempted again
1287 the next time find_library is invoked with the same variable.
1288 Options include:
1290 NAMES Specify one or more possible names for the library.
1292 When using this to specify names with and without a version suf‐
1294 fix, we recommend specifying the unversioned name first so that
1295 locally-built packages can be found before those provided by
1296 distributions.
1297 HINTS, PATHS
1299 Specify directories to search in addition to the default loca‐
1300 tions. The ENV var sub-option reads paths from a system envi‐
1301 ronment variable.
1302 PATH_SUFFIXES
1304 Specify additional subdirectories to check below each directory
1305 location otherwise considered.
1306 DOC Specify the documentation string for the <VAR> cache entry.
1308 If NO_DEFAULT_PATH is specified, then no additional paths are added to
1310 the search. If NO_DEFAULT_PATH is not specified, the search process is
1311 as follows:
1312 1. If called from within a find module loaded by find_package(<Package‐
1314 Name>), search prefixes unique to the current package being found.
1315 Specifically look in the <PackageName>_ROOT CMake variable and the
1316 <PackageName>_ROOT environment variable. The package root variables
1317 are maintained as a stack so if called from nested find modules,
1318 root paths from the parent’s find module will be searched after
1319 paths from the current module, i.e. <CurrentPackage>_ROOT, ENV{<Cur‐
1320 rentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT},
1321 etc. This can be skipped if NO_PACKAGE_ROOT_PATH is passed. See
1322 policy CMP0074.
1323 · <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1325 <prefix>/lib for each <prefix> in the <PackageName>_ROOT CMake
1326 variable and the <PackageName>_ROOT environment variable if called
1327 from within a find module loaded by find_package(<PackageName>)
1328 2. Search paths specified in cmake-specific cache variables. These are
1330 intended to be used on the command line with a -DVAR=value. The
1331 values are interpreted as semicolon-separated lists. This can be
1332 skipped if NO_CMAKE_PATH is passed.
1333 · <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1335 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1336 · CMAKE_LIBRARY_PATH
1338 · CMAKE_FRAMEWORK_PATH
1340 3. Search paths specified in cmake-specific environment variables.
1342 These are intended to be set in the user’s shell configuration, and
1343 therefore use the host’s native path separator (; on Windows and :
1344 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1345 passed.
1346 · <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1348 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1349 · CMAKE_LIBRARY_PATH
1351 · CMAKE_FRAMEWORK_PATH
1353 4. Search the paths specified by the HINTS option. These should be
1355 paths computed by system introspection, such as a hint provided by
1356 the location of another item already found. Hard-coded guesses
1357 should be specified with the PATHS option.
1358 5. Search the standard system environment variables. This can be
1360 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1361 · Directories in LIB. On Windows hosts: <prefix>/lib/<arch> if
1363 CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/lib for each <pre‐
1364 fix>/[s]bin in PATH, and <entry>/lib for other entries in PATH,
1365 and the directories in PATH itself.
1366 6. Search cmake variables defined in the Platform files for the current
1368 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed.
1369 · <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1371 <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1372 · CMAKE_SYSTEM_LIBRARY_PATH
1374 · CMAKE_SYSTEM_FRAMEWORK_PATH
1376 7. Search the paths specified by the PATHS option or in the short-hand
1378 version of the command. These are typically hard-coded guesses.
1379 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
1381 determine the order of preference between Apple-style and unix-style
1382 package components.
1383 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
1385 ries to be prepended to all other search directories. This effectively
1386 “re-roots” the entire search under given locations. Paths which are
1387 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
1388 ing, because that variable is always a path on the host system. By
1389 default the CMAKE_FIND_ROOT_PATH is empty.
1390 The CMAKE_SYSROOT variable can also be used to specify exactly one
1392 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
1393 effects. See the documentation for that variable for more.
1394 These variables are especially useful when cross-compiling to point to
1396 the root directory of the target environment and CMake will search
1397 there too. By default at first the directories listed in
1398 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
1399 searched, and then the non-rooted directories will be searched. The
1400 default behavior can be adjusted by setting
1401 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY. This behavior can be manually over‐
1402 ridden on a per-call basis using options:
1403 CMAKE_FIND_ROOT_PATH_BOTH
1405 Search in the order described above.
1406 NO_CMAKE_FIND_ROOT_PATH
1408 Do not use the CMAKE_FIND_ROOT_PATH variable.
1409 ONLY_CMAKE_FIND_ROOT_PATH
1411 Search only the re-rooted directories and directories below
1412 CMAKE_STAGING_PREFIX.
1413 The default search order is designed to be most-specific to least-spe‐
1415 cific for common use cases. Projects may override the order by simply
1416 calling the command multiple times and using the NO_* options:
1417 find_library (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1419 find_library (<VAR> NAMES name)
1420 Once one of the calls succeeds the result variable will be set and
1422 stored in the cache so that no call will search again.
1423 When more than one value is given to the NAMES option this command by
1425 default will consider one name at a time and search every directory for
1426 it. The NAMES_PER_DIR option tells this command to consider one direc‐
1427 tory at a time and search for all names in it.
1428 Each library name given to the NAMES option is first considered as a
1430 library file name and then considered with platform-specific prefixes
1431 (e.g. lib) and suffixes (e.g. .so). Therefore one may specify library
1432 file names such as libfoo.a directly. This can be used to locate
1433 static libraries on UNIX-like systems.
1434 If the library found is a framework, then <VAR> will be set to the full
1436 path to the framework <fullPath>/A.framework. When a full path to a
1437 framework is used as a library, CMake will use a -framework A, and a
1438 -F<fullPath> to link the framework to the target.
1439 If the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable is set all search
1441 paths will be tested as normal, with the suffix appended, and with all
1442 matches of lib/ replaced with lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUF‐
1443 FIX}/. This variable overrides the FIND_LIBRARY_USE_LIB32_PATHS,
1444 FIND_LIBRARY_USE_LIBX32_PATHS, and FIND_LIBRARY_USE_LIB64_PATHS global
1445 properties.
1446 If the FIND_LIBRARY_USE_LIB32_PATHS global property is set all search
1448 paths will be tested as normal, with 32/ appended, and with all matches
1449 of lib/ replaced with lib32/. This property is automatically set for
1450 the platforms that are known to need it if at least one of the lan‐
1451 guages supported by the project() command is enabled.
1452 If the FIND_LIBRARY_USE_LIBX32_PATHS global property is set all search
1454 paths will be tested as normal, with x32/ appended, and with all
1455 matches of lib/ replaced with libx32/. This property is automatically
1456 set for the platforms that are known to need it if at least one of the
1457 languages supported by the project() command is enabled.
1458 If the FIND_LIBRARY_USE_LIB64_PATHS global property is set all search
1460 paths will be tested as normal, with 64/ appended, and with all matches
1461 of lib/ replaced with lib64/. This property is automatically set for
1462 the platforms that are known to need it if at least one of the lan‐
1463 guages supported by the project() command is enabled.
1464 find_package
1466 Find an external project, and load its settings.
1467 Basic Signature and Module Mode
1469 find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
1470 [REQUIRED] [[COMPONENTS] [components...]]
1471 [OPTIONAL_COMPONENTS components...]
1472 [NO_POLICY_SCOPE])
1473 Finds and loads settings from an external project. <PackageName>_FOUND
1475 will be set to indicate whether the package was found. When the pack‐
1476 age is found package-specific information is provided through variables
1477 and Imported Targets documented by the package itself. The QUIET
1478 option disables informational messages, including those indicating that
1479 the package cannot be found if it is not REQUIRED. The REQUIRED option
1480 stops processing with an error message if the package cannot be found.
1481 A package-specific list of required components may be listed after the
1483 COMPONENTS option (or after the REQUIRED option if present). Addi‐
1484 tional optional components may be listed after OPTIONAL_COMPONENTS.
1485 Available components and their influence on whether a package is con‐
1486 sidered to be found are defined by the target package.
1487 The [version] argument requests a version with which the package found
1489 should be compatible (format is major[.minor[.patch[.tweak]]]). The
1490 EXACT option requests that the version be matched exactly. If no [ver‐
1491 sion] and/or component list is given to a recursive invocation inside a
1492 find-module, the corresponding arguments are forwarded automatically
1493 from the outer call (including the EXACT flag for [version]). Version
1494 support is currently provided only on a package-by-package basis (see
1495 the Version Selection section below).
1496 See the cmake_policy() command documentation for discussion of the
1498 NO_POLICY_SCOPE option.
1499 The command has two modes by which it searches for packages: “Module”
1501 mode and “Config” mode. The above signature selects Module mode. If
1502 no module is found the command falls back to Config mode, described
1503 below. This fall back is disabled if the MODULE option is given.
1504 In Module mode, CMake searches for a file called Find<Package‐
1506 Name>.cmake. The file is first searched in the CMAKE_MODULE_PATH, then
1507 among the Find Modules provided by the CMake installation. If the file
1508 is found, it is read and processed by CMake. It is responsible for
1509 finding the package, checking the version, and producing any needed
1510 messages. Some find-modules provide limited or no support for version‐
1511 ing; check the module documentation.
1512 Full Signature and Config Mode
1514 User code should generally look for packages using the above basic sig‐
1515 nature. The remainder of this command documentation specifies the full
1516 command signature and details of the search process. Project maintain‐
1517 ers wishing to provide a package to be found by this command are
1518 encouraged to read on.
1519 The complete Config mode command signature is
1521 find_package(<PackageName> [version] [EXACT] [QUIET]
1523 [REQUIRED] [[COMPONENTS] [components...]]
1524 [CONFIG|NO_MODULE]
1525 [NO_POLICY_SCOPE]
1526 [NAMES name1 [name2 ...]]
1527 [CONFIGS config1 [config2 ...]]
1528 [HINTS path1 [path2 ... ]]
1529 [PATHS path1 [path2 ... ]]
1530 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1531 [NO_DEFAULT_PATH]
1532 [NO_PACKAGE_ROOT_PATH]
1533 [NO_CMAKE_PATH]
1534 [NO_CMAKE_ENVIRONMENT_PATH]
1535 [NO_SYSTEM_ENVIRONMENT_PATH]
1536 [NO_CMAKE_PACKAGE_REGISTRY]
1537 [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
1538 [NO_CMAKE_SYSTEM_PATH]
1539 [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
1540 [CMAKE_FIND_ROOT_PATH_BOTH |
1541 ONLY_CMAKE_FIND_ROOT_PATH |
1542 NO_CMAKE_FIND_ROOT_PATH])
1543 The CONFIG option, the synonymous NO_MODULE option, or the use of
1545 options not specified in the basic signature all enforce pure Config
1546 mode. In pure Config mode, the command skips Module mode search and
1547 proceeds at once with Config mode search.
1548 Config mode search attempts to locate a configuration file provided by
1550 the package to be found. A cache entry called <PackageName>_DIR is
1551 created to hold the directory containing the file. By default the com‐
1552 mand searches for a package with the name <PackageName>. If the NAMES
1553 option is given the names following it are used instead of <Package‐
1554 Name>. The command searches for a file called <PackageName>Con‐
1555 fig.cmake or <lower-case-package-name>-config.cmake for each name spec‐
1556 ified. A replacement set of possible configuration file names may be
1557 given using the CONFIGS option. The search procedure is specified
1558 below. Once found, the configuration file is read and processed by
1559 CMake. Since the file is provided by the package it already knows the
1560 location of package contents. The full path to the configuration file
1561 is stored in the cmake variable <PackageName>_CONFIG.
1562 All configuration files which have been considered by CMake while
1564 searching for an installation of the package with an appropriate ver‐
1565 sion are stored in the cmake variable <PackageName>_CONSIDERED_CONFIGS,
1566 the associated versions in <PackageName>_CONSIDERED_VERSIONS.
1567 If the package configuration file cannot be found CMake will generate
1569 an error describing the problem unless the QUIET argument is specified.
1570 If REQUIRED is specified and the package is not found a fatal error is
1571 generated and the configure step stops executing. If <PackageName>_DIR
1572 has been set to a directory not containing a configuration file CMake
1573 will ignore it and search from scratch.
1574 Package maintainers providing CMake package configuration files are
1576 encouraged to name and install them such that the Search Procedure out‐
1577 lined below will find them without requiring use of additional options.
1578 Version Selection
1580 When the [version] argument is given Config mode will only find a ver‐
1581 sion of the package that claims compatibility with the requested ver‐
1582 sion (format is major[.minor[.patch[.tweak]]]). If the EXACT option is
1583 given only a version of the package claiming an exact match of the
1584 requested version may be found. CMake does not establish any conven‐
1585 tion for the meaning of version numbers. Package version numbers are
1586 checked by “version” files provided by the packages themselves. For a
1587 candidate package configuration file <config-file>.cmake the corre‐
1588 sponding version file is located next to it and named either <con‐
1589 fig-file>-version.cmake or <config-file>Version.cmake. If no such ver‐
1590 sion file is available then the configuration file is assumed to not be
1591 compatible with any requested version. A basic version file containing
1592 generic version matching code can be created using the CMakePackageCon‐
1593 figHelpers module. When a version file is found it is loaded to check
1594 the requested version number. The version file is loaded in a nested
1595 scope in which the following variables have been defined:
1596 PACKAGE_FIND_NAME
1598 the <PackageName>
1599 PACKAGE_FIND_VERSION
1601 full requested version string
1602 PACKAGE_FIND_VERSION_MAJOR
1604 major version if requested, else 0
1605 PACKAGE_FIND_VERSION_MINOR
1607 minor version if requested, else 0
1608 PACKAGE_FIND_VERSION_PATCH
1610 patch version if requested, else 0
1611 PACKAGE_FIND_VERSION_TWEAK
1613 tweak version if requested, else 0
1614 PACKAGE_FIND_VERSION_COUNT
1616 number of version components, 0 to 4
1617 The version file checks whether it satisfies the requested version and
1619 sets these variables:
1620 PACKAGE_VERSION
1622 full provided version string
1623 PACKAGE_VERSION_EXACT
1625 true if version is exact match
1626 PACKAGE_VERSION_COMPATIBLE
1628 true if version is compatible
1629 PACKAGE_VERSION_UNSUITABLE
1631 true if unsuitable as any version
1632 These variables are checked by the find_package command to determine
1634 whether the configuration file provides an acceptable version. They
1635 are not available after the find_package call returns. If the version
1636 is acceptable the following variables are set:
1637 <PackageName>_VERSION
1639 full provided version string
1640 <PackageName>_VERSION_MAJOR
1642 major version if provided, else 0
1643 <PackageName>_VERSION_MINOR
1645 minor version if provided, else 0
1646 <PackageName>_VERSION_PATCH
1648 patch version if provided, else 0
1649 <PackageName>_VERSION_TWEAK
1651 tweak version if provided, else 0
1652 <PackageName>_VERSION_COUNT
1654 number of version components, 0 to 4
1655 and the corresponding package configuration file is loaded. When mul‐
1657 tiple package configuration files are available whose version files
1658 claim compatibility with the version requested it is unspecified which
1659 one is chosen: unless the variable CMAKE_FIND_PACKAGE_SORT_ORDER is set
1660 no attempt is made to choose a highest or closest version number.
1661 To control the order in which find_package checks for compatibility use
1663 the two variables CMAKE_FIND_PACKAGE_SORT_ORDER and CMAKE_FIND_PACK‐
1664 AGE_SORT_DIRECTION. For instance in order to select the highest ver‐
1665 sion one can set
1666 SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
1668 SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
1669 before calling find_package.
1671 Search Procedure
1673 CMake constructs a set of possible installation prefixes for the pack‐
1674 age. Under each prefix several directories are searched for a configu‐
1675 ration file. The tables below show the directories searched. Each
1676 entry is meant for installation trees following Windows (W), UNIX (U),
1677 or Apple (A) conventions:
1678 <prefix>/ (W)
1680 <prefix>/(cmake|CMake)/ (W)
1681 <prefix>/<name>*/ (W)
1682 <prefix>/<name>*/(cmake|CMake)/ (W)
1683 <prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/ (U)
1684 <prefix>/(lib/<arch>|lib*|share)/<name>*/ (U)
1685 <prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (U)
1686 <prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/ (W/U)
1687 <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ (W/U)
1688 <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U)
1689 On systems supporting macOS Frameworks and Application Bundles the fol‐
1691 lowing directories are searched for frameworks or bundles containing a
1692 configuration file:
1693 <prefix>/<name>.framework/Resources/ (A)
1695 <prefix>/<name>.framework/Resources/CMake/ (A)
1696 <prefix>/<name>.framework/Versions/*/Resources/ (A)
1697 <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A)
1698 <prefix>/<name>.app/Contents/Resources/ (A)
1699 <prefix>/<name>.app/Contents/Resources/CMake/ (A)
1700 In all cases the <name> is treated as case-insensitive and corresponds
1702 to any of the names specified (<PackageName> or names given by NAMES).
1703 Paths with lib/<arch> are enabled if the CMAKE_LIBRARY_ARCHITECTURE
1705 variable is set. lib* includes one or more of the values lib64, lib32,
1706 libx32 or lib (searched in that order).
1707 · Paths with lib64 are searched on 64 bit platforms if the
1709 FIND_LIBRARY_USE_LIB64_PATHS property is set to TRUE.
1710 · Paths with lib32 are searched on 32 bit platforms if the
1712 FIND_LIBRARY_USE_LIB32_PATHS property is set to TRUE.
1713 · Paths with libx32 are searched on platforms using the x32 ABI if the
1715 FIND_LIBRARY_USE_LIBX32_PATHS property is set to TRUE.
1716 · The lib path is always searched.
1718 If PATH_SUFFIXES is specified, the suffixes are appended to each (W) or
1720 (U) directory entry one-by-one.
1721 This set of directories is intended to work in cooperation with
1723 projects that provide configuration files in their installation trees.
1724 Directories above marked with (W) are intended for installations on
1725 Windows where the prefix may point at the top of an application’s
1726 installation directory. Those marked with (U) are intended for instal‐
1727 lations on UNIX platforms where the prefix is shared by multiple pack‐
1728 ages. This is merely a convention, so all (W) and (U) directories are
1729 still searched on all platforms. Directories marked with (A) are
1730 intended for installations on Apple platforms. The CMAKE_FIND_FRAME‐
1731 WORK and CMAKE_FIND_APPBUNDLE variables determine the order of prefer‐
1732 ence.
1733 The set of installation prefixes is constructed using the following
1735 steps. If NO_DEFAULT_PATH is specified all NO_* options are enabled.
1736 1. Search paths specified in the <PackageName>_ROOT CMake variable and
1738 the <PackageName>_ROOT environment variable, where <PackageName> is
1739 the package to be found. The package root variables are maintained
1740 as a stack so if called from within a find module, root paths from
1741 the parent’s find module will also be searched after paths for the
1742 current package. This can be skipped if NO_PACKAGE_ROOT_PATH is
1743 passed. See policy CMP0074.
1744 2. Search paths specified in cmake-specific cache variables. These are
1746 intended to be used on the command line with a -DVAR=value. The
1747 values are interpreted as semicolon-separated lists. This can be
1748 skipped if NO_CMAKE_PATH is passed:
1749 CMAKE_PREFIX_PATH
1751 CMAKE_FRAMEWORK_PATH
1752 CMAKE_APPBUNDLE_PATH
1753 3. Search paths specified in cmake-specific environment variables.
1755 These are intended to be set in the user’s shell configuration, and
1756 therefore use the host’s native path separator (; on Windows and :
1757 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1758 passed:
1759 <PackageName>_DIR
1761 CMAKE_PREFIX_PATH
1762 CMAKE_FRAMEWORK_PATH
1763 CMAKE_APPBUNDLE_PATH
1764 4. Search paths specified by the HINTS option. These should be paths
1766 computed by system introspection, such as a hint provided by the
1767 location of another item already found. Hard-coded guesses should
1768 be specified with the PATHS option.
1769 5. Search the standard system environment variables. This can be
1771 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed. Path entries end‐
1772 ing in /bin or /sbin are automatically converted to their parent
1773 directories:
1774 PATH
1776 6. Search paths stored in the CMake User Package Registry. This can be
1778 skipped if NO_CMAKE_PACKAGE_REGISTRY is passed or by setting the
1779 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY to TRUE. See the cmake-pack‐
1780 ages(7) manual for details on the user package registry.
1781 7. Search cmake variables defined in the Platform files for the current
1783 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed:
1784 CMAKE_SYSTEM_PREFIX_PATH
1786 CMAKE_SYSTEM_FRAMEWORK_PATH
1787 CMAKE_SYSTEM_APPBUNDLE_PATH
1788 8. Search paths stored in the CMake System Package Registry. This can
1790 be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is passed or by set‐
1791 ting the CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY to TRUE. See
1792 the cmake-packages(7) manual for details on the system package reg‐
1793 istry.
1794 9. Search paths specified by the PATHS option. These are typically
1796 hard-coded guesses.
1797 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
1799 ries to be prepended to all other search directories. This effectively
1800 “re-roots” the entire search under given locations. Paths which are
1801 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
1802 ing, because that variable is always a path on the host system. By
1803 default the CMAKE_FIND_ROOT_PATH is empty.
1804 The CMAKE_SYSROOT variable can also be used to specify exactly one
1806 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
1807 effects. See the documentation for that variable for more.
1808 These variables are especially useful when cross-compiling to point to
1810 the root directory of the target environment and CMake will search
1811 there too. By default at first the directories listed in
1812 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
1813 searched, and then the non-rooted directories will be searched. The
1814 default behavior can be adjusted by setting
1815 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE. This behavior can be manually over‐
1816 ridden on a per-call basis using options:
1817 CMAKE_FIND_ROOT_PATH_BOTH
1819 Search in the order described above.
1820 NO_CMAKE_FIND_ROOT_PATH
1822 Do not use the CMAKE_FIND_ROOT_PATH variable.
1823 ONLY_CMAKE_FIND_ROOT_PATH
1825 Search only the re-rooted directories and directories below
1826 CMAKE_STAGING_PREFIX.
1827 The default search order is designed to be most-specific to least-spe‐
1829 cific for common use cases. Projects may override the order by simply
1830 calling the command multiple times and using the NO_* options:
1831 find_package (<PackageName> PATHS paths... NO_DEFAULT_PATH)
1833 find_package (<PackageName>)
1834 Once one of the calls succeeds the result variable will be set and
1836 stored in the cache so that no call will search again.
1837 By default the value stored in the result variable will be the path at
1839 which the file is found. The CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS vari‐
1840 able may be set to TRUE before calling find_package in order to resolve
1841 symbolic links and store the real path to the file.
1842 Every non-REQUIRED find_package call can be disabled by setting the
1844 CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable to TRUE.
1845 Package File Interface Variables
1847 When loading a find module or package configuration file find_package
1848 defines variables to provide information about the call arguments (and
1849 restores their original state before returning):
1850 CMAKE_FIND_PACKAGE_NAME
1852 the <PackageName> which is searched for
1853 <PackageName>_FIND_REQUIRED
1855 true if REQUIRED option was given
1856 <PackageName>_FIND_QUIETLY
1858 true if QUIET option was given
1859 <PackageName>_FIND_VERSION
1861 full requested version string
1862 <PackageName>_FIND_VERSION_MAJOR
1864 major version if requested, else 0
1865 <PackageName>_FIND_VERSION_MINOR
1867 minor version if requested, else 0
1868 <PackageName>_FIND_VERSION_PATCH
1870 patch version if requested, else 0
1871 <PackageName>_FIND_VERSION_TWEAK
1873 tweak version if requested, else 0
1874 <PackageName>_FIND_VERSION_COUNT
1876 number of version components, 0 to 4
1877 <PackageName>_FIND_VERSION_EXACT
1879 true if EXACT option was given
1880 <PackageName>_FIND_COMPONENTS
1882 list of requested components
1883 <PackageName>_FIND_REQUIRED_<c>
1885 true if component <c> is required, false if component <c> is
1886 optional
1887 In Module mode the loaded find module is responsible to honor the
1889 request detailed by these variables; see the find module for details.
1890 In Config mode find_package handles REQUIRED, QUIET, and [version]
1891 options automatically but leaves it to the package configuration file
1892 to handle components in a way that makes sense for the package. The
1893 package configuration file may set <PackageName>_FOUND to false to tell
1894 find_package that component requirements are not satisfied.
1895 find_path
1897 A short-hand signature is:
1898 find_path (<VAR> name1 [path1 path2 ...])
1900 The general signature is:
1902 find_path (
1904 <VAR>
1905 name | NAMES name1 [name2 ...]
1906 [HINTS path1 [path2 ... ENV var]]
1907 [PATHS path1 [path2 ... ENV var]]
1908 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1909 [DOC "cache documentation string"]
1910 [NO_DEFAULT_PATH]
1911 [NO_PACKAGE_ROOT_PATH]
1912 [NO_CMAKE_PATH]
1913 [NO_CMAKE_ENVIRONMENT_PATH]
1914 [NO_SYSTEM_ENVIRONMENT_PATH]
1915 [NO_CMAKE_SYSTEM_PATH]
1916 [CMAKE_FIND_ROOT_PATH_BOTH |
1917 ONLY_CMAKE_FIND_ROOT_PATH |
1918 NO_CMAKE_FIND_ROOT_PATH]
1919 )
1920 This command is used to find a directory containing the named file. A
1922 cache entry named by <VAR> is created to store the result of this com‐
1923 mand. If the file in a directory is found the result is stored in the
1924 variable and the search will not be repeated unless the variable is
1925 cleared. If nothing is found, the result will be <VAR>-NOTFOUND, and
1926 the search will be attempted again the next time find_path is invoked
1927 with the same variable.
1928 Options include:
1930 NAMES Specify one or more possible names for the file in a directory.
1932 When using this to specify names with and without a version suf‐
1934 fix, we recommend specifying the unversioned name first so that
1935 locally-built packages can be found before those provided by
1936 distributions.
1937 HINTS, PATHS
1939 Specify directories to search in addition to the default loca‐
1940 tions. The ENV var sub-option reads paths from a system envi‐
1941 ronment variable.
1942 PATH_SUFFIXES
1944 Specify additional subdirectories to check below each directory
1945 location otherwise considered.
1946 DOC Specify the documentation string for the <VAR> cache entry.
1948 If NO_DEFAULT_PATH is specified, then no additional paths are added to
1950 the search. If NO_DEFAULT_PATH is not specified, the search process is
1951 as follows:
1952 1. If called from within a find module loaded by find_package(<Package‐
1954 Name>), search prefixes unique to the current package being found.
1955 Specifically look in the <PackageName>_ROOT CMake variable and the
1956 <PackageName>_ROOT environment variable. The package root variables
1957 are maintained as a stack so if called from nested find modules,
1958 root paths from the parent’s find module will be searched after
1959 paths from the current module, i.e. <CurrentPackage>_ROOT, ENV{<Cur‐
1960 rentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT},
1961 etc. This can be skipped if NO_PACKAGE_ROOT_PATH is passed. See
1962 policy CMP0074.
1963 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1965 <prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
1966 variable and the <PackageName>_ROOT environment variable if called
1967 from within a find module loaded by find_package(<PackageName>)
1968 2. Search paths specified in cmake-specific cache variables. These are
1970 intended to be used on the command line with a -DVAR=value. The
1971 values are interpreted as semicolon-separated lists. This can be
1972 skipped if NO_CMAKE_PATH is passed.
1973 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1975 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1976 · CMAKE_INCLUDE_PATH
1978 · CMAKE_FRAMEWORK_PATH
1980 3. Search paths specified in cmake-specific environment variables.
1982 These are intended to be set in the user’s shell configuration, and
1983 therefore use the host’s native path separator (; on Windows and :
1984 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1985 passed.
1986 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1988 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1989 · CMAKE_INCLUDE_PATH
1991 · CMAKE_FRAMEWORK_PATH
1993 4. Search the paths specified by the HINTS option. These should be
1995 paths computed by system introspection, such as a hint provided by
1996 the location of another item already found. Hard-coded guesses
1997 should be specified with the PATHS option.
1998 5. Search the standard system environment variables. This can be
2000 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
2001 · Directories in INCLUDE. On Windows hosts: <prefix>/include/<arch>
2003 if CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/include for
2004 each <prefix>/[s]bin in PATH, and <entry>/include for other
2005 entries in PATH, and the directories in PATH itself.
2006 6. Search cmake variables defined in the Platform files for the current
2008 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed.
2009 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2011 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2012 · CMAKE_SYSTEM_INCLUDE_PATH
2014 · CMAKE_SYSTEM_FRAMEWORK_PATH
2016 7. Search the paths specified by the PATHS option or in the short-hand
2018 version of the command. These are typically hard-coded guesses.
2019 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
2021 determine the order of preference between Apple-style and unix-style
2022 package components.
2023 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
2025 ries to be prepended to all other search directories. This effectively
2026 “re-roots” the entire search under given locations. Paths which are
2027 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
2028 ing, because that variable is always a path on the host system. By
2029 default the CMAKE_FIND_ROOT_PATH is empty.
2030 The CMAKE_SYSROOT variable can also be used to specify exactly one
2032 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
2033 effects. See the documentation for that variable for more.
2034 These variables are especially useful when cross-compiling to point to
2036 the root directory of the target environment and CMake will search
2037 there too. By default at first the directories listed in
2038 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
2039 searched, and then the non-rooted directories will be searched. The
2040 default behavior can be adjusted by setting
2041 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually over‐
2042 ridden on a per-call basis using options:
2043 CMAKE_FIND_ROOT_PATH_BOTH
2045 Search in the order described above.
2046 NO_CMAKE_FIND_ROOT_PATH
2048 Do not use the CMAKE_FIND_ROOT_PATH variable.
2049 ONLY_CMAKE_FIND_ROOT_PATH
2051 Search only the re-rooted directories and directories below
2052 CMAKE_STAGING_PREFIX.
2053 The default search order is designed to be most-specific to least-spe‐
2055 cific for common use cases. Projects may override the order by simply
2056 calling the command multiple times and using the NO_* options:
2057 find_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2059 find_path (<VAR> NAMES name)
2060 Once one of the calls succeeds the result variable will be set and
2062 stored in the cache so that no call will search again.
2063 When searching for frameworks, if the file is specified as A/b.h, then
2065 the framework search will look for A.framework/Headers/b.h. If that is
2066 found the path will be set to the path to the framework. CMake will
2067 convert this to the correct -F option to include the file.
2068 find_program
2070 A short-hand signature is:
2071 find_program (<VAR> name1 [path1 path2 ...])
2073 The general signature is:
2075 find_program (
2077 <VAR>
2078 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
2079 [HINTS path1 [path2 ... ENV var]]
2080 [PATHS path1 [path2 ... ENV var]]
2081 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2082 [DOC "cache documentation string"]
2083 [NO_DEFAULT_PATH]
2084 [NO_PACKAGE_ROOT_PATH]
2085 [NO_CMAKE_PATH]
2086 [NO_CMAKE_ENVIRONMENT_PATH]
2087 [NO_SYSTEM_ENVIRONMENT_PATH]
2088 [NO_CMAKE_SYSTEM_PATH]
2089 [CMAKE_FIND_ROOT_PATH_BOTH |
2090 ONLY_CMAKE_FIND_ROOT_PATH |
2091 NO_CMAKE_FIND_ROOT_PATH]
2092 )
2093 This command is used to find a program. A cache entry named by <VAR>
2095 is created to store the result of this command. If the program is
2096 found the result is stored in the variable and the search will not be
2097 repeated unless the variable is cleared. If nothing is found, the
2098 result will be <VAR>-NOTFOUND, and the search will be attempted again
2099 the next time find_program is invoked with the same variable.
2100 Options include:
2102 NAMES Specify one or more possible names for the program.
2104 When using this to specify names with and without a version suf‐
2106 fix, we recommend specifying the unversioned name first so that
2107 locally-built packages can be found before those provided by
2108 distributions.
2109 HINTS, PATHS
2111 Specify directories to search in addition to the default loca‐
2112 tions. The ENV var sub-option reads paths from a system envi‐
2113 ronment variable.
2114 PATH_SUFFIXES
2116 Specify additional subdirectories to check below each directory
2117 location otherwise considered.
2118 DOC Specify the documentation string for the <VAR> cache entry.
2120 If NO_DEFAULT_PATH is specified, then no additional paths are added to
2122 the search. If NO_DEFAULT_PATH is not specified, the search process is
2123 as follows:
2124 1. If called from within a find module loaded by find_package(<Package‐
2126 Name>), search prefixes unique to the current package being found.
2127 Specifically look in the <PackageName>_ROOT CMake variable and the
2128 <PackageName>_ROOT environment variable. The package root variables
2129 are maintained as a stack so if called from nested find modules,
2130 root paths from the parent’s find module will be searched after
2131 paths from the current module, i.e. <CurrentPackage>_ROOT, ENV{<Cur‐
2132 rentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT},
2133 etc. This can be skipped if NO_PACKAGE_ROOT_PATH is passed. See
2134 policy CMP0074.
2135 · <prefix>/[s]bin for each <prefix> in the <PackageName>_ROOT CMake
2137 variable and the <PackageName>_ROOT environment variable if called
2138 from within a find module loaded by find_package(<PackageName>)
2139 2. Search paths specified in cmake-specific cache variables. These are
2141 intended to be used on the command line with a -DVAR=value. The
2142 values are interpreted as semicolon-separated lists. This can be
2143 skipped if NO_CMAKE_PATH is passed.
2144 · <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2146 · CMAKE_PROGRAM_PATH
2148 · CMAKE_APPBUNDLE_PATH
2150 3. Search paths specified in cmake-specific environment variables.
2152 These are intended to be set in the user’s shell configuration, and
2153 therefore use the host’s native path separator (; on Windows and :
2154 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2155 passed.
2156 · <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2158 · CMAKE_PROGRAM_PATH
2160 · CMAKE_APPBUNDLE_PATH
2162 4. Search the paths specified by the HINTS option. These should be
2164 paths computed by system introspection, such as a hint provided by
2165 the location of another item already found. Hard-coded guesses
2166 should be specified with the PATHS option.
2167 5. Search the standard system environment variables. This can be
2169 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
2170 · PATH
2172 6. Search cmake variables defined in the Platform files for the current
2174 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed.
2175 · <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2177 · CMAKE_SYSTEM_PROGRAM_PATH
2179 · CMAKE_SYSTEM_APPBUNDLE_PATH
2181 7. Search the paths specified by the PATHS option or in the short-hand
2183 version of the command. These are typically hard-coded guesses.
2184 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
2186 determine the order of preference between Apple-style and unix-style
2187 package components.
2188 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
2190 ries to be prepended to all other search directories. This effectively
2191 “re-roots” the entire search under given locations. Paths which are
2192 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
2193 ing, because that variable is always a path on the host system. By
2194 default the CMAKE_FIND_ROOT_PATH is empty.
2195 The CMAKE_SYSROOT variable can also be used to specify exactly one
2197 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
2198 effects. See the documentation for that variable for more.
2199 These variables are especially useful when cross-compiling to point to
2201 the root directory of the target environment and CMake will search
2202 there too. By default at first the directories listed in
2203 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
2204 searched, and then the non-rooted directories will be searched. The
2205 default behavior can be adjusted by setting
2206 CMAKE_FIND_ROOT_PATH_MODE_PROGRAM. This behavior can be manually over‐
2207 ridden on a per-call basis using options:
2208 CMAKE_FIND_ROOT_PATH_BOTH
2210 Search in the order described above.
2211 NO_CMAKE_FIND_ROOT_PATH
2213 Do not use the CMAKE_FIND_ROOT_PATH variable.
2214 ONLY_CMAKE_FIND_ROOT_PATH
2216 Search only the re-rooted directories and directories below
2217 CMAKE_STAGING_PREFIX.
2218 The default search order is designed to be most-specific to least-spe‐
2220 cific for common use cases. Projects may override the order by simply
2221 calling the command multiple times and using the NO_* options:
2222 find_program (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2224 find_program (<VAR> NAMES name)
2225 Once one of the calls succeeds the result variable will be set and
2227 stored in the cache so that no call will search again.
2228 When more than one value is given to the NAMES option this command by
2230 default will consider one name at a time and search every directory for
2231 it. The NAMES_PER_DIR option tells this command to consider one direc‐
2232 tory at a time and search for all names in it.
2233 foreach
2235 Evaluate a group of commands for each value in a list.
2236 foreach(<loop_var> <items>)
2238 <commands>
2239 endforeach()
2240 where <items> is a list of items that are separated by semicolon or
2242 whitespace. All commands between foreach and the matching endforeach
2243 are recorded without being invoked. Once the endforeach is evaluated,
2244 the recorded list of commands is invoked once for each item in <items>.
2245 At the beginning of each iteration the variable loop_var will be set to
2246 the value of the current item.
2247 The commands break() and continue() provide means to escape from the
2249 normal control flow.
2250 Per legacy, the endforeach() command admits an optional <loop_var>
2252 argument. If used, it must be a verbatim repeat of the argument of the
2253 opening foreach command.
2254 foreach(<loop_var> RANGE <stop>)
2256 In this variant, foreach iterates over the numbers 0, 1, … up to (and
2258 including) the nonnegative integer <stop>.
2259 foreach(<loop_var> RANGE <start> <stop> [<step>])
2261 In this variant, foreach iterates over the numbers from <start> up to
2263 at most <stop> in steps of <step>. If <step> is not specified, then
2264 the step size is 1. The three arguments <start> <stop> <step> must all
2265 be nonnegative integers, and <stop> must not be smaller than <start>;
2266 otherwise you enter the danger zone of undocumented behavior that may
2267 change in future releases.
2268 foreach(loop_var IN [LISTS [<lists>]] [ITEMS [<items>]])
2270 In this variant, <lists> is a whitespace or semicolon separated list of
2272 list-valued variables. The foreach command iterates over each item in
2273 each given list. The <items> following the ITEMS keyword are processed
2274 as in the first variant of the foreach command. The forms LISTS A and
2275 ITEMS ${A} are equivalent.
2276 The following example shows how the LISTS option is processed:
2278 set(A 0;1)
2280 set(B 2 3)
2281 set(C "4 5")
2282 set(D 6;7 8)
2283 set(E "")
2284 foreach(X IN LISTS A B C D E)
2285 message(STATUS "X=${X}")
2286 endforeach()
2287 yields
2289 -- X=0
2291 -- X=1
2292 -- X=2
2293 -- X=3
2294 -- X=4 5
2295 -- X=6
2296 -- X=7
2297 -- X=8
2298 function
2300 Start recording a function for later invocation as a command.
2301 function(<name> [<arg1> ...])
2303 <commands>
2304 endfunction()
2305 Defines a function named <name> that takes arguments named <arg1>, …
2307 The <commands> in the function definition are recorded; they are not
2308 executed until the function is invoked.
2309 Per legacy, the endfunction() command admits an optional <name> argu‐
2311 ment. If used, it must be a verbatim repeat of the argument of the
2312 opening function command.
2313 A function opens a new scope: see set(var PARENT_SCOPE) for details.
2315 See the cmake_policy() command documentation for the behavior of poli‐
2317 cies inside functions.
2318 See the macro() command documentation for differences between CMake
2320 functions and macros.
2321 Invocation
2323 The function invocation is case-insensitive. A function defined as
2324 function(foo)
2326 <commands>
2327 endfunction()
2328 can be invoked through any of
2330 foo()
2332 Foo()
2333 FOO()
2334 and so on. However, it is strongly recommended to stay with the case
2336 chosen in the function definition. Typically functions use all-lower‐
2337 case names.
2338 Arguments
2340 When the function is invoked, the recorded <commands> are first modi‐
2341 fied by replacing formal parameters (${arg1}, …) with the arguments
2342 passed, and then invoked as normal commands.
2343 In addition to referencing the formal parameters you can reference the
2345 ARGC variable which will be set to the number of arguments passed into
2346 the function as well as ARGV0, ARGV1, ARGV2, … which will have the
2347 actual values of the arguments passed in. This facilitates creating
2348 functions with optional arguments.
2349 Furthermore, ARGV holds the list of all arguments given to the function
2351 and ARGN holds the list of arguments past the last expected argument.
2352 Referencing to ARGV# arguments beyond ARGC have undefined behavior.
2353 Checking that ARGC is greater than # is the only way to ensure that
2354 ARGV# was passed to the function as an extra argument.
2355 get_cmake_property
2357 Get a global property of the CMake instance.
2358 get_cmake_property(<var> <property>)
2360 Gets a global property from the CMake instance. The value of the
2362 <property> is stored in the variable <var>. If the property is not
2363 found, <var> will be set to "NOTFOUND". See the cmake-properties(7)
2364 manual for available properties.
2365 See also the get_property() command GLOBAL option.
2367 In addition to global properties, this command (for historical reasons)
2369 also supports the VARIABLES and MACROS directory properties. It also
2370 supports a special COMPONENTS global property that lists the components
2371 given to the install() command.
2372 get_directory_property
2374 Get a property of DIRECTORY scope.
2375 get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
2377 Stores a property of directory scope in the named <variable>. The
2379 DIRECTORY argument specifies another directory from which to retrieve
2380 the property value instead of the current directory. The specified
2381 directory must have already been traversed by CMake.
2382 If the property is not defined for the nominated directory scope, an
2384 empty string is returned. In the case of INHERITED properties, if the
2385 property is not found for the nominated directory scope, the search
2386 will chain to a parent scope as described for the define_property()
2387 command.
2388 get_directory_property(<variable> [DIRECTORY <dir>]
2390 DEFINITION <var-name>)
2391 Get a variable definition from a directory. This form is useful to get
2393 a variable definition from another directory.
2394 See also the more general get_property() command.
2396 get_filename_component
2398 Get a specific component of a full filename.
2399 get_filename_component(<var> <FileName> <mode> [CACHE])
2401 Sets <var> to a component of <FileName>, where <mode> is one of:
2403 DIRECTORY = Directory without file name
2405 NAME = File name without directory
2406 EXT = File name longest extension (.b.c from d/a.b.c)
2407 NAME_WE = File name without directory or longest extension
2408 LAST_EXT = File name last extension (.c from d/a.b.c)
2409 NAME_WLE = File name without directory or last extension
2410 PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
2411 Paths are returned with forward slashes and have no trailing slashes.
2413 If the optional CACHE argument is specified, the result variable is
2414 added to the cache.
2415 get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
2417 Sets <var> to the absolute path of <FileName>, where <mode> is one of:
2419 ABSOLUTE = Full path to file
2421 REALPATH = Full path to existing file with symlinks resolved
2422 If the provided <FileName> is a relative path, it is evaluated relative
2424 to the given base directory <dir>. If no base directory is provided,
2425 the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
2426 Paths are returned with forward slashes and have no trailing slashes.
2428 If the optional CACHE argument is specified, the result variable is
2429 added to the cache.
2430 get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
2432 The program in <FileName> will be found in the system search path or
2434 left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
2435 command-line arguments present in the <FileName> string are split from
2436 the program name and stored in <arg_var>. This is used to separate a
2437 program name from its arguments in a command line string.
2438 get_property
2440 Get a property.
2441 get_property(<variable>
2443 <GLOBAL |
2444 DIRECTORY [<dir>] |
2445 TARGET <target> |
2446 SOURCE <source> |
2447 INSTALL <file> |
2448 TEST <test> |
2449 CACHE <entry> |
2450 VARIABLE >
2451 PROPERTY <name>
2452 [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
2453 Gets one property from one object in a scope.
2455 The first argument specifies the variable in which to store the result.
2457 The second argument determines the scope from which to get the prop‐
2458 erty. It must be one of the following:
2459 GLOBAL Scope is unique and does not accept a name.
2461 DIRECTORY
2463 Scope defaults to the current directory but another directory
2464 (already processed by CMake) may be named by the full or rela‐
2465 tive path <dir>.
2466 TARGET Scope must name one existing target.
2468 SOURCE Scope must name one source file.
2470 INSTALL
2472 Scope must name one installed file path.
2473 TEST Scope must name one existing test.
2475 CACHE Scope must name one cache entry.
2477 VARIABLE
2479 Scope is unique and does not accept a name.
2480 The required PROPERTY option is immediately followed by the name of the
2482 property to get. If the property is not set an empty value is
2483 returned, although some properties support inheriting from a parent
2484 scope if defined to behave that way (see define_property()).
2485 If the SET option is given the variable is set to a boolean value indi‐
2487 cating whether the property has been set. If the DEFINED option is
2488 given the variable is set to a boolean value indicating whether the
2489 property has been defined such as with the define_property() command.
2490 If BRIEF_DOCS or FULL_DOCS is given then the variable is set to a
2492 string containing documentation for the requested property. If docu‐
2493 mentation is requested for a property that has not been defined NOT‐
2494 FOUND is returned.
2495 if
2497 Conditionally execute a group of commands.
2498 Synopsis
2500 if(<condition>)
2501 <commands>
2502 elseif(<condition>) # optional block, can be repeated
2503 <commands>
2504 else() # optional block
2505 <commands>
2506 endif()
2507 Evaluates the condition argument of the if clause according to the
2509 Condition syntax described below. If the result is true, then the com‐
2510 mands in the if block are executed. Otherwise, optional elseif blocks
2511 are processed in the same way. Finally, if no condition is true, com‐
2512 mands in the optional else block are executed.
2513 Per legacy, the else() and endif() commands admit an optional <condi‐
2515 tion> argument. If used, it must be a verbatim repeat of the argument
2516 of the opening if command.
2517 Condition Syntax
2519 The following syntax applies to the condition argument of the if,
2520 elseif and while() clauses.
2521 Compound conditions are evaluated in the following order of precedence:
2523 Innermost parentheses are evaluated first. Next come unary tests such
2524 as EXISTS, COMMAND, and DEFINED. Then binary tests such as EQUAL,
2525 LESS, LESS_EQUAL, GREATER, GREATER_EQUAL, STREQUAL, STRLESS, STR‐
2526 LESS_EQUAL, STRGREATER, STRGREATER_EQUAL, VERSION_EQUAL, VERSION_LESS,
2527 VERSION_LESS_EQUAL, VERSION_GREATER, VERSION_GREATER_EQUAL, and
2528 MATCHES. Then the boolean operators in the order NOT, AND, and
2529 finally OR.
2530 Possible conditions are:
2532 if(<constant>)
2534 True if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
2535 ber. False if the constant is 0, OFF, NO, FALSE, N, IGNORE,
2536 NOTFOUND, the empty string, or ends in the suffix -NOTFOUND.
2537 Named boolean constants are case-insensitive. If the argument
2538 is not one of these specific constants, it is treated as a vari‐
2539 able or string and the following signature is used.
2540 if(<variable|string>)
2542 True if given a variable that is defined to a value that is not
2543 a false constant. False otherwise. (Note macro arguments are
2544 not variables.)
2545 if(NOT <condition>)
2547 True if the condition is not true.
2548 if(<cond1> AND <cond2>)
2550 True if both conditions would be considered true individually.
2551 if(<cond1> OR <cond2>)
2553 True if either condition would be considered true individually.
2554 if(COMMAND command-name)
2556 True if the given name is a command, macro or function that can
2557 be invoked.
2558 if(POLICY policy-id)
2560 True if the given name is an existing policy (of the form
2561 CMP<NNNN>).
2562 if(TARGET target-name)
2564 True if the given name is an existing logical target name cre‐
2565 ated by a call to the add_executable(), add_library(), or
2566 add_custom_target() command that has already been invoked (in
2567 any directory).
2568 if(TEST test-name)
2570 True if the given name is an existing test name created by the
2571 add_test() command.
2572 if(EXISTS path-to-file-or-directory)
2574 True if the named file or directory exists. Behavior is
2575 well-defined only for full paths.
2576 if(file1 IS_NEWER_THAN file2)
2578 True if file1 is newer than file2 or if one of the two files
2579 doesn’t exist. Behavior is well-defined only for full paths.
2580 If the file time stamps are exactly the same, an IS_NEWER_THAN
2581 comparison returns true, so that any dependent build operations
2582 will occur in the event of a tie. This includes the case of
2583 passing the same file name for both file1 and file2.
2584 if(IS_DIRECTORY path-to-directory)
2586 True if the given name is a directory. Behavior is well-defined
2587 only for full paths.
2588 if(IS_SYMLINK file-name)
2590 True if the given name is a symbolic link. Behavior is
2591 well-defined only for full paths.
2592 if(IS_ABSOLUTE path)
2594 True if the given path is an absolute path.
2595 if(<variable|string> MATCHES regex)
2597 True if the given string or variable’s value matches the given
2598 regular condition. See Regex Specification for regex format.
2599 () groups are captured in CMAKE_MATCH_<n> variables.
2600 if(<variable|string> LESS <variable|string>)
2602 True if the given string or variable’s value is a valid number
2603 and less than that on the right.
2604 if(<variable|string> GREATER <variable|string>)
2606 True if the given string or variable’s value is a valid number
2607 and greater than that on the right.
2608 if(<variable|string> EQUAL <variable|string>)
2610 True if the given string or variable’s value is a valid number
2611 and equal to that on the right.
2612 if(<variable|string> LESS_EQUAL <variable|string>)
2614 True if the given string or variable’s value is a valid number
2615 and less than or equal to that on the right.
2616 if(<variable|string> GREATER_EQUAL <variable|string>)
2618 True if the given string or variable’s value is a valid number
2619 and greater than or equal to that on the right.
2620 if(<variable|string> STRLESS <variable|string>)
2622 True if the given string or variable’s value is lexicographi‐
2623 cally less than the string or variable on the right.
2624 if(<variable|string> STRGREATER <variable|string>)
2626 True if the given string or variable’s value is lexicographi‐
2627 cally greater than the string or variable on the right.
2628 if(<variable|string> STREQUAL <variable|string>)
2630 True if the given string or variable’s value is lexicographi‐
2631 cally equal to the string or variable on the right.
2632 if(<variable|string> STRLESS_EQUAL <variable|string>)
2634 True if the given string or variable’s value is lexicographi‐
2635 cally less than or equal to the string or variable on the right.
2636 if(<variable|string> STRGREATER_EQUAL <variable|string>)
2638 True if the given string or variable’s value is lexicographi‐
2639 cally greater than or equal to the string or variable on the
2640 right.
2641 if(<variable|string> VERSION_LESS <variable|string>)
2643 Component-wise integer version number comparison (version format
2644 is major[.minor[.patch[.tweak]]], omitted components are treated
2645 as zero). Any non-integer version component or non-integer
2646 trailing part of a version component effectively truncates the
2647 string at that point.
2648 if(<variable|string> VERSION_GREATER <variable|string>)
2650 Component-wise integer version number comparison (version format
2651 is major[.minor[.patch[.tweak]]], omitted components are treated
2652 as zero). Any non-integer version component or non-integer
2653 trailing part of a version component effectively truncates the
2654 string at that point.
2655 if(<variable|string> VERSION_EQUAL <variable|string>)
2657 Component-wise integer version number comparison (version format
2658 is major[.minor[.patch[.tweak]]], omitted components are treated
2659 as zero). Any non-integer version component or non-integer
2660 trailing part of a version component effectively truncates the
2661 string at that point.
2662 if(<variable|string> VERSION_LESS_EQUAL <variable|string>)
2664 Component-wise integer version number comparison (version format
2665 is major[.minor[.patch[.tweak]]], omitted components are treated
2666 as zero). Any non-integer version component or non-integer
2667 trailing part of a version component effectively truncates the
2668 string at that point.
2669 if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)
2671 Component-wise integer version number comparison (version format
2672 is major[.minor[.patch[.tweak]]], omitted components are treated
2673 as zero). Any non-integer version component or non-integer
2674 trailing part of a version component effectively truncates the
2675 string at that point.
2676 if(<variable|string> IN_LIST <variable>)
2678 True if the given element is contained in the named list vari‐
2679 able.
2680 if(DEFINED <name>|CACHE{<name>}|ENV{<name>})
2682 True if a variable, cache variable or environment variable with
2683 given <name> is defined. The value of the variable does not mat‐
2684 ter. Note that macro arguments are not variables.
2685 if((condition) AND (condition OR (condition)))
2687 The conditions inside the parenthesis are evaluated first and
2688 then the remaining condition is evaluated as in the previous
2689 examples. Where there are nested parenthesis the innermost are
2690 evaluated as part of evaluating the condition that contains
2691 them.
2692 Variable Expansion
2694 The if command was written very early in CMake’s history, predating the
2695 ${} variable evaluation syntax, and for convenience evaluates variables
2696 named by its arguments as shown in the above signatures. Note that
2697 normal variable evaluation with ${} applies before the if command even
2698 receives the arguments. Therefore code like
2699 set(var1 OFF)
2701 set(var2 "var1")
2702 if(${var2})
2703 appears to the if command as
2705 if(var1)
2707 and is evaluated according to the if(<variable>) case documented above.
2709 The result is OFF which is false. However, if we remove the ${} from
2710 the example then the command sees
2711 if(var2)
2713 which is true because var2 is defined to “var1” which is not a false
2715 constant.
2716 Automatic evaluation applies in the other cases whenever the above-doc‐
2718 umented condition syntax accepts <variable|string>:
2719 · The left hand argument to MATCHES is first checked to see if it is a
2721 defined variable, if so the variable’s value is used, otherwise the
2722 original value is used.
2723 · If the left hand argument to MATCHES is missing it returns false
2725 without error
2726 · Both left and right hand arguments to LESS, GREATER, EQUAL,
2728 LESS_EQUAL, and GREATER_EQUAL, are independently tested to see if
2729 they are defined variables, if so their defined values are used oth‐
2730 erwise the original value is used.
2731 · Both left and right hand arguments to STRLESS, STRGREATER, STREQUAL,
2733 STRLESS_EQUAL, and STRGREATER_EQUAL are independently tested to see
2734 if they are defined variables, if so their defined values are used
2735 otherwise the original value is used.
2736 · Both left and right hand arguments to VERSION_LESS, VERSION_GREATER,
2738 VERSION_EQUAL, VERSION_LESS_EQUAL, and VERSION_GREATER_EQUAL are
2739 independently tested to see if they are defined variables, if so
2740 their defined values are used otherwise the original value is used.
2741 · The right hand argument to NOT is tested to see if it is a boolean
2743 constant, if so the value is used, otherwise it is assumed to be a
2744 variable and it is dereferenced.
2745 · The left and right hand arguments to AND and OR are independently
2747 tested to see if they are boolean constants, if so they are used as
2748 such, otherwise they are assumed to be variables and are derefer‐
2749 enced.
2750 To prevent ambiguity, potential variable or keyword names can be speci‐
2752 fied in a Quoted Argument or a Bracket Argument. A quoted or bracketed
2753 variable or keyword will be interpreted as a string and not derefer‐
2754 enced or interpreted. See policy CMP0054.
2755 There is no automatic evaluation for environment or cache Variable Ref‐
2757 erences. Their values must be referenced as $ENV{<name>} or
2758 $CACHE{<name>} wherever the above-documented condition syntax accepts
2759 <variable|string>.
2760 include
2762 Load and run CMake code from a file or module.
2763 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
2765 [NO_POLICY_SCOPE])
2766 Loads and runs CMake code from the file given. Variable reads and
2768 writes access the scope of the caller (dynamic scoping). If OPTIONAL
2769 is present, then no error is raised if the file does not exist. If
2770 RESULT_VARIABLE is given the variable <var> will be set to the full
2771 filename which has been included or NOTFOUND if it failed.
2772 If a module is specified instead of a file, the file with name <module‐
2774 name>.cmake is searched first in CMAKE_MODULE_PATH, then in the CMake
2775 module directory. There is one exception to this: if the file which
2776 calls include() is located itself in the CMake builtin module direc‐
2777 tory, then first the CMake builtin module directory is searched and
2778 CMAKE_MODULE_PATH afterwards. See also policy CMP0017.
2779 See the cmake_policy() command documentation for discussion of the
2781 NO_POLICY_SCOPE option.
2782 include_guard
2784 Provides an include guard for the file currently being processed by
2785 CMake.
2786 include_guard([DIRECTORY|GLOBAL])
2788 Sets up an include guard for the current CMake file (see the CMAKE_CUR‐
2790 RENT_LIST_FILE variable documentation).
2791 CMake will end its processing of the current file at the location of
2793 the include_guard() command if the current file has already been pro‐
2794 cessed for the applicable scope (see below). This provides functional‐
2795 ity similar to the include guards commonly used in source headers or to
2796 the #pragma once directive. If the current file has been processed pre‐
2797 viously for the applicable scope, the effect is as though return() had
2798 been called. Do not call this command from inside a function being
2799 defined within the current file.
2800 An optional argument specifying the scope of the guard may be provided.
2802 Possible values for the option are:
2803 DIRECTORY
2805 The include guard applies within the current directory and
2806 below. The file will only be included once within this directory
2807 scope, but may be included again by other files outside of this
2808 directory (i.e. a parent directory or another directory not
2809 pulled in by add_subdirectory() or include() from the current
2810 file or its children).
2811 GLOBAL The include guard applies globally to the whole build. The cur‐
2813 rent file will only be included once regardless of the scope.
2814 If no arguments given, include_guard has the same scope as a variable,
2816 meaning that the include guard effect is isolated by the most recent
2817 function scope or current directory if no inner function scopes exist.
2818 In this case the command behavior is the same as:
2819 if(__CURRENT_FILE_VAR__)
2821 return()
2822 endif()
2823 set(__CURRENT_FILE_VAR__ TRUE)
2824 list
2826 List operations.
2827 Synopsis
2829 Reading
2830 list(LENGTH <list> <out-var>)
2831 list(GET <list> <element index> [<index> ...] <out-var>)
2832 list(JOIN <list> <glue> <out-var>)
2833 list(SUBLIST <list> <begin> <length> <out-var>)
2834 Search
2836 list(FIND <list> <value> <out-var>)
2837 Modification
2839 list(APPEND <list> [<element>...])
2840 list(FILTER <list> {INCLUDE | EXCLUDE} REGEX <regex>)
2841 list(INSERT <list> <index> [<element>...])
2842 list(REMOVE_ITEM <list> <value>...)
2843 list(REMOVE_AT <list> <index>...)
2844 list(REMOVE_DUPLICATES <list>)
2845 list(TRANSFORM <list> <ACTION> [...])
2846 Ordering
2848 list(REVERSE <list>)
2849 list(SORT <list> [...])
2850 Introduction
2852 The list subcommands APPEND, INSERT, FILTER, REMOVE_AT, REMOVE_ITEM,
2853 REMOVE_DUPLICATES, REVERSE and SORT may create new values for the list
2854 within the current CMake variable scope. Similar to the set() command,
2855 the LIST command creates new variable values in the current scope, even
2856 if the list itself is actually defined in a parent scope. To propagate
2857 the results of these operations upwards, use set() with PARENT_SCOPE,
2858 set() with CACHE INTERNAL, or some other means of value propagation.
2859 NOTE:
2861 A list in cmake is a ; separated group of strings. To create a list
2862 the set command can be used. For example, set(var a b c d e) cre‐
2863 ates a list with a;b;c;d;e, and set(var "a b c d e") creates a
2864 string or a list with one item in it. (Note macro arguments are
2865 not variables, and therefore cannot be used in LIST commands.)
2866 NOTE:
2868 When specifying index values, if <element index> is 0 or greater, it
2869 is indexed from the beginning of the list, with 0 representing the
2870 first list element. If <element index> is -1 or lesser, it is
2871 indexed from the end of the list, with -1 representing the last list
2872 element. Be careful when counting with negative indices: they do
2873 not start from 0. -0 is equivalent to 0, the first list element.
2874 Reading
2876 list(LENGTH <list> <output variable>)
2877 Returns the list’s length.
2879 list(GET <list> <element index> [<element index> ...] <output variable>)
2881 Returns the list of elements specified by indices from the list.
2883 list(JOIN <list> <glue> <output variable>)
2885 Returns a string joining all list’s elements using the glue string. To
2887 join multiple strings, which are not part of a list, use JOIN operator
2888 from string() command.
2889 list(SUBLIST <list> <begin> <length> <output variable>)
2891 Returns a sublist of the given list. If <length> is 0, an empty list
2893 will be returned. If <length> is -1 or the list is smaller than
2894 <begin>+<length> then the remaining elements of the list starting at
2895 <begin> will be returned.
2896 Search
2898 list(FIND <list> <value> <output variable>)
2899 Returns the index of the element specified in the list or -1 if it
2901 wasn’t found.
2902 Modification
2904 list(APPEND <list> [<element> ...])
2905 Appends elements to the list.
2907 list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
2909 Includes or removes items from the list that match the mode’s pattern.
2911 In REGEX mode, items will be matched against the given regular expres‐
2912 sion.
2913 For more information on regular expressions see also the string() com‐
2915 mand.
2916 list(INSERT <list> <element_index> <element> [<element> ...])
2918 Inserts elements to the list to the specified location.
2920 list(REMOVE_ITEM <list> <value> [<value> ...])
2922 Removes the given items from the list.
2924 list(REMOVE_AT <list> <index> [<index> ...])
2926 Removes items at given indices from the list.
2928 list(REMOVE_DUPLICATES <list>)
2930 Removes duplicated items in the list.
2932 list(TRANSFORM <list> <ACTION> [<SELECTOR>]
2934 [OUTPUT_VARIABLE <output variable>])
2935 Transforms the list by applying an action to all or, by specifying a
2937 <SELECTOR>, to the selected elements of the list, storing result
2938 in-place or in the specified output variable.
2939 NOTE:
2941 TRANSFORM sub-command does not change the number of elements of the
2942 list. If a <SELECTOR> is specified, only some elements will be
2943 changed, the other ones will remain same as before the transforma‐
2944 tion.
2945 <ACTION> specify the action to apply to the elements of list. The
2947 actions have exactly the same semantics as sub-commands of string()
2948 command.
2949 The <ACTION> may be one of:
2951 APPEND, PREPEND: Append, prepend specified value to each element of the
2953 list.
2954 list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
2956 TOUPPER, TOLOWER: Convert each element of the list to upper, lower
2958 characters.
2959 list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
2961 STRIP: Remove leading and trailing spaces from each element of the
2963 list.
2964 list(TRANSFORM <list> STRIP ...)
2966 GENEX_STRIP: Strip any generator expressions from each element of the
2968 list.
2969 list(TRANSFORM <list> GENEX_STRIP ...)
2971 REPLACE: Match the regular expression as many times as possible and
2973 substitute the replacement expression for the match for each element of
2974 the list (Same semantic as REGEX REPLACE from string() command).
2975 list(TRANSFORM <list> REPLACE <regular_expression>
2977 <replace_expression> ...)
2978 <SELECTOR> select which elements of the list will be transformed. Only
2980 one type of selector can be specified at a time.
2981 The <SELECTOR> may be one of:
2983 AT: Specify a list of indexes.
2985 list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
2987 FOR: Specify a range with, optionally, an increment used to iterate
2989 over the range.
2990 list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
2992 REGEX: Specify a regular expression. Only elements matching the regular
2994 expression will be transformed.
2995 list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
2997 Ordering
2999 list(REVERSE <list>)
3000 Reverses the contents of the list in-place.
3002 list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
3004 Sorts the list in-place alphabetically. Use the COMPARE keyword to
3006 select the comparison method for sorting. The <compare> option should
3007 be one of:
3008 · STRING: Sorts a list of strings alphabetically. This is the default
3010 behavior if the COMPARE option is not given.
3011 · FILE_BASENAME: Sorts a list of pathnames of files by their basenames.
3013 Use the CASE keyword to select a case sensitive or case insensitive
3015 sort mode. The <case> option should be one of:
3016 · SENSITIVE: List items are sorted in a case-sensitive manner. This is
3018 the default behavior if the CASE option is not given.
3019 · INSENSITIVE: List items are sorted case insensitively. The order of
3021 items which differ only by upper/lowercase is not specified.
3022 To control the sort order, the ORDER keyword can be given. The <order>
3024 option should be one of:
3025 · ASCENDING: Sorts the list in ascending order. This is the default
3027 behavior when the ORDER option is not given.
3028 · DESCENDING: Sorts the list in descending order.
3030 macro
3032 Start recording a macro for later invocation as a command
3033 macro(<name> [<arg1> ...])
3035 <commands>
3036 endmacro()
3037 Defines a macro named <name> that takes arguments named <arg1>, … Com‐
3039 mands listed after macro, but before the matching endmacro(), are not
3040 executed until the macro is invoked.
3041 Per legacy, the endmacro() command admits an optional <name> argument.
3043 If used, it must be a verbatim repeat of the argument of the opening
3044 macro command.
3045 See the cmake_policy() command documentation for the behavior of poli‐
3047 cies inside macros.
3048 See the Macro vs Function section below for differences between CMake
3050 macros and functions.
3051 Invocation
3053 The macro invocation is case-insensitive. A macro defined as
3054 macro(foo)
3056 <commands>
3057 endmacro()
3058 can be invoked through any of
3060 foo()
3062 Foo()
3063 FOO()
3064 and so on. However, it is strongly recommended to stay with the case
3066 chosen in the macro definition. Typically macros use all-lowercase
3067 names.
3068 Arguments
3070 When a macro is invoked, the commands recorded in the macro are first
3071 modified by replacing formal parameters (${arg1}, …) with the arguments
3072 passed, and then invoked as normal commands.
3073 In addition to referencing the formal parameters you can reference the
3075 values ${ARGC} which will be set to the number of arguments passed into
3076 the function as well as ${ARGV0}, ${ARGV1}, ${ARGV2}, … which will
3077 have the actual values of the arguments passed in. This facilitates
3078 creating macros with optional arguments.
3079 Furthermore, ${ARGV} holds the list of all arguments given to the macro
3081 and ${ARGN} holds the list of arguments past the last expected argu‐
3082 ment. Referencing to ${ARGV#} arguments beyond ${ARGC} have undefined
3083 behavior. Checking that ${ARGC} is greater than # is the only way to
3084 ensure that ${ARGV#} was passed to the function as an extra argument.
3085 Macro vs Function
3087 The macro command is very similar to the function() command. Nonethe‐
3088 less, there are a few important differences.
3089 In a function, ARGN, ARGC, ARGV and ARGV0, ARGV1, … are true variables
3091 in the usual CMake sense. In a macro, they are not, they are string
3092 replacements much like the C preprocessor would do with a macro. This
3093 has a number of consequences, as explained in the Argument Caveats sec‐
3094 tion below.
3095 Another difference between macros and functions is the control flow. A
3097 function is executed by transferring control from the calling statement
3098 to the function body. A macro is executed as if the macro body were
3099 pasted in place of the calling statement. This has the consequence
3100 that a return() in a macro body does not just terminate execution of
3101 the macro; rather, control is returned from the scope of the macro
3102 call. To avoid confusion, it is recommended to avoid return() in
3103 macros altogether.
3104 Argument Caveats
3106 Since ARGN, ARGC, ARGV, ARGV0 etc. are not variables, you will NOT be
3107 able to use commands like
3108 if(ARGV1) # ARGV1 is not a variable
3110 if(DEFINED ARGV2) # ARGV2 is not a variable
3111 if(ARGC GREATER 2) # ARGC is not a variable
3112 foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
3113 In the first case, you can use if(${ARGV1}). In the second and third
3115 case, the proper way to check if an optional variable was passed to the
3116 macro is to use if(${ARGC} GREATER 2). In the last case, you can use
3117 foreach(loop_var ${ARGN}) but this will skip empty arguments. If you
3118 need to include them, you can use
3119 set(list_var "${ARGN}")
3121 foreach(loop_var IN LISTS list_var)
3122 Note that if you have a variable with the same name in the scope from
3124 which the macro is called, using unreferenced names will use the exist‐
3125 ing variable instead of the arguments. For example:
3126 macro(bar)
3128 foreach(arg IN LISTS ARGN)
3129 <commands>
3130 endforeach()
3131 endmacro()
3132 function(foo)
3134 bar(x y z)
3135 endfunction()
3136 foo(a b c)
3138 Will loop over a;b;c and not over x;y;z as one might have expected. If
3140 you want true CMake variables and/or better CMake scope control you
3141 should look at the function command.
3142 mark_as_advanced
3144 Mark cmake cached variables as advanced.
3145 mark_as_advanced([CLEAR|FORCE] <var1> ...)
3147 Sets the advanced/non-advanced state of the named cached variables.
3149 An advanced variable will not be displayed in any of the cmake GUIs
3151 unless the show advanced option is on. In script mode, the
3152 advanced/non-advanced state has no effect.
3153 If the keyword CLEAR is given then advanced variables are changed back
3155 to unadvanced. If the keyword FORCE is given then the variables are
3156 made advanced. If neither FORCE nor CLEAR is specified, new values
3157 will be marked as advanced, but if a variable already has an
3158 advanced/non-advanced state, it will not be changed.
3159 math
3161 Evaluate a mathematical expression.
3162 math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])
3164 Evaluates a mathematical <expression> and sets <variable> to the
3166 resulting value.
3167 The mathematical expression must be given as a string (i.e. enclosed in
3169 double quotation marks). An example is "5 * (10 + 13)". Supported
3170 operators are +, -, *, /, %, |, &, ^, ~, <<, >>, and (...); they have
3171 the same meaning as in C code.
3172 Hexadecimal numbers are recognized when prefixed with “0x”, as in C
3174 code.
3175 The result is formatted according to the option OUTPUT_FORMAT, where
3177 <format> is one of
3178 HEXADECIMAL
3180 Hexadecimal notation as in C code, i. e. starting with “0x”.
3181 DECIMAL
3183 Decimal notation. Which is also used if no OUTPUT_FORMAT option
3184 is specified.
3185 For example
3187 math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL) # value is set to "1000"
3189 math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL) # value is set to "0x3e8"
3190 message
3192 Display a message to the user.
3193 message([<mode>] "message to display" ...)
3195 The optional <mode> keyword determines the type of message:
3197 (none) = Important information
3199 STATUS = Incidental information
3200 WARNING = CMake Warning, continue processing
3201 AUTHOR_WARNING = CMake Warning (dev), continue processing
3202 SEND_ERROR = CMake Error, continue processing,
3203 but skip generation
3204 FATAL_ERROR = CMake Error, stop processing and generation
3205 DEPRECATION = CMake Deprecation Error or Warning if variable
3206 CMAKE_ERROR_DEPRECATED or CMAKE_WARN_DEPRECATED
3207 is enabled, respectively, else no message.
3208 The CMake command-line tool displays STATUS messages on stdout and all
3210 other message types on stderr. The CMake GUI displays all messages in
3211 its log area. The interactive dialogs (ccmake and CMakeSetup) show
3212 STATUS messages one at a time on a status line and other messages in
3213 interactive pop-up boxes.
3214 CMake Warning and Error message text displays using a simple markup
3216 language. Non-indented text is formatted in line-wrapped paragraphs
3217 delimited by newlines. Indented text is considered pre-formatted.
3218 option
3220 Provide an option that the user can optionally select.
3221 option(<variable> "<help_text>" [value])
3223 Provides an option for the user to select as ON or OFF. If no initial
3225 <value> is provided, OFF is used. If <variable> is already set as a
3226 normal variable then the command does nothing (see policy CMP0077).
3227 If you have options that depend on the values of other options, see the
3229 module help for CMakeDependentOption.
3230 return
3232 Return from a file, directory or function.
3233 return()
3235 Returns from a file, directory or function. When this command is
3237 encountered in an included file (via include() or find_package()), it
3238 causes processing of the current file to stop and control is returned
3239 to the including file. If it is encountered in a file which is not
3240 included by another file, e.g. a CMakeLists.txt, control is returned
3241 to the parent directory if there is one. If return is called in a
3242 function, control is returned to the caller of the function.
3243 Note that a macro, unlike a function, is expanded in place and there‐
3245 fore cannot handle return().
3246 separate_arguments
3248 Parse command-line arguments into a semicolon-separated list.
3249 separate_arguments(<variable> <mode> <args>)
3251 Parses a space-separated string <args> into a list of items, and stores
3253 this list in semicolon-separated standard form in <variable>.
3254 This function is intended for parsing command-line arguments. The
3256 entire command line must be passed as one string in the argument
3257 <args>.
3258 The exact parsing rules depend on the operating system. They are spec‐
3260 ified by the <mode> argument which must be one of the following key‐
3261 words:
3262 UNIX_COMMAND
3264 Arguments are separated by by unquoted whitespace. Both sin‐
3265 gle-quote and double-quote pairs are respected. A backslash
3266 escapes the next literal character (\" is "); there are no spe‐
3267 cial escapes (\n is just n).
3268 WINDOWS_COMMAND
3270 A Windows command-line is parsed using the same syntax the run‐
3271 time library uses to construct argv at startup. It separates
3272 arguments by whitespace that is not double-quoted. Backslashes
3273 are literal unless they precede double-quotes. See the MSDN
3274 article Parsing C Command-Line Arguments for details.
3275 NATIVE_COMMAND
3277 Proceeds as in WINDOWS_COMMAND mode if the host system is Win‐
3278 dows. Otherwise proceeds as in UNIX_COMMAND mode.
3279 separate_arguments(<var>)
3281 Convert the value of <var> to a semi-colon separated list. All spaces
3283 are replaced with ‘;’. This helps with generating command lines.
3284 set
3286 Set a normal, cache, or environment variable to a given value. See the
3287 cmake-language(7) variables documentation for the scopes and interac‐
3288 tion of normal variables and cache entries.
3289 Signatures of this command that specify a <value>... placeholder expect
3291 zero or more arguments. Multiple arguments will be joined as a semi‐
3292 colon-separated list to form the actual variable value to be set. Zero
3293 arguments will cause normal variables to be unset. See the unset()
3294 command to unset variables explicitly.
3295 Set Normal Variable
3297 set(<variable> <value>... [PARENT_SCOPE])
3298 Sets the given <variable> in the current function or directory scope.
3300 If the PARENT_SCOPE option is given the variable will be set in the
3302 scope above the current scope. Each new directory or function creates
3303 a new scope. This command will set the value of a variable into the
3304 parent directory or calling function (whichever is applicable to the
3305 case at hand). The previous state of the variable’s value stays the
3306 same in the current scope (e.g., if it was undefined before, it is
3307 still undefined and if it had a value, it is still that value).
3308 Set Cache Entry
3310 set(<variable> <value>... CACHE <type> <docstring> [FORCE])
3311 Sets the given cache <variable> (cache entry). Since cache entries are
3313 meant to provide user-settable values this does not overwrite existing
3314 cache entries by default. Use the FORCE option to overwrite existing
3315 entries.
3316 The <type> must be specified as one of:
3318 BOOL Boolean ON/OFF value. cmake-gui(1) offers a checkbox.
3320 FILEPATH
3322 Path to a file on disk. cmake-gui(1) offers a file dialog.
3323 PATH Path to a directory on disk. cmake-gui(1) offers a file dialog.
3325 STRING A line of text. cmake-gui(1) offers a text field or a drop-down
3327 selection if the STRINGS cache entry property is set.
3328 INTERNAL
3330 A line of text. cmake-gui(1) does not show internal entries.
3331 They may be used to store variables persistently across runs.
3332 Use of this type implies FORCE.
3333 The <docstring> must be specified as a line of text providing a quick
3335 summary of the option for presentation to cmake-gui(1) users.
3336 If the cache entry does not exist prior to the call or the FORCE option
3338 is given then the cache entry will be set to the given value. Further‐
3339 more, any normal variable binding in the current scope will be removed
3340 to expose the newly cached value to any immediately following evalua‐
3341 tion.
3342 It is possible for the cache entry to exist prior to the call but have
3344 no type set if it was created on the cmake(1) command line by a user
3345 through the -D<var>=<value> option without specifying a type. In this
3346 case the set command will add the type. Furthermore, if the <type> is
3347 PATH or FILEPATH and the <value> provided on the command line is a rel‐
3348 ative path, then the set command will treat the path as relative to the
3349 current working directory and convert it to an absolute path.
3350 Set Environment Variable
3352 set(ENV{<variable>} [<value>])
3353 Sets an Environment Variable to the given value. Subsequent calls of
3355 $ENV{<variable>} will return this new value.
3356 This command affects only the current CMake process, not the process
3358 from which CMake was called, nor the system environment at large, nor
3359 the environment of subsequent build or test processes.
3360 If no argument is given after ENV{<variable>} or if <value> is an empty
3362 string, then this command will clear any existing value of the environ‐
3363 ment variable.
3364 Arguments after <value> are ignored. If extra arguments are found, then
3366 an author warning is issued.
3367 set_directory_properties
3369 Set properties of the current directory and subdirectories.
3370 set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...)
3372 Sets properties of the current directory and its subdirectories in
3374 key-value pairs.
3375 See also the set_property(DIRECTORY) command.
3377 See Directory Properties for the list of properties known to CMake and
3379 their individual documentation for the behavior of each property.
3380 set_property
3382 Set a named property in a given scope.
3383 set_property(<GLOBAL |
3385 DIRECTORY [<dir>] |
3386 TARGET [<target1> ...] |
3387 SOURCE [<src1> ...] |
3388 INSTALL [<file1> ...] |
3389 TEST [<test1> ...] |
3390 CACHE [<entry1> ...] >
3391 [APPEND] [APPEND_STRING]
3392 PROPERTY <name> [value1 ...])
3393 Sets one property on zero or more objects of a scope.
3395 The first argument determines the scope in which the property is set.
3397 It must be one of the following:
3398 GLOBAL Scope is unique and does not accept a name.
3400 DIRECTORY
3402 Scope defaults to the current directory but another directory
3403 (already processed by CMake) may be named by full or relative
3404 path. See also the set_directory_properties() command.
3405 TARGET Scope may name zero or more existing targets. See also the
3407 set_target_properties() command.
3408 SOURCE Scope may name zero or more source files. Note that source file
3410 properties are visible only to targets added in the same direc‐
3411 tory (CMakeLists.txt). See also the set_source_files_proper‐
3412 ties() command.
3413 INSTALL
3415 Scope may name zero or more installed file paths. These are
3416 made available to CPack to influence deployment.
3417 Both the property key and value may use generator expressions.
3419 Specific properties may apply to installed files and/or directo‐
3420 ries.
3421 Path components have to be separated by forward slashes, must be
3423 normalized and are case sensitive.
3424 To reference the installation prefix itself with a relative path
3426 use “.”.
3427 Currently installed file properties are only defined for the WIX
3429 generator where the given paths are relative to the installation
3430 prefix.
3431 TEST Scope may name zero or more existing tests. See also the
3433 set_tests_properties() command.
3434 CACHE Scope must name zero or more cache existing entries.
3436 The required PROPERTY option is immediately followed by the name of the
3438 property to set. Remaining arguments are used to compose the property
3439 value in the form of a semicolon-separated list.
3440 If the APPEND option is given the list is appended to any existing
3442 property value. If the APPEND_STRING option is given the string is
3443 appended to any existing property value as string, i.e. it results in a
3444 longer string and not a list of strings. When using APPEND or
3445 APPEND_STRING with a property defined to support INHERITED behavior
3446 (see define_property()), no inheriting occurs when finding the initial
3447 value to append to. If the property is not already directly set in the
3448 nominated scope, the command will behave as though APPEND or
3449 APPEND_STRING had not been given.
3450 See the cmake-properties(7) manual for a list of properties in each
3452 scope.
3453 site_name
3455 Set the given variable to the name of the computer.
3456 site_name(variable)
3458 string
3460 String operations.
3461 Synopsis
3463 Search and Replace
3464 string(FIND <string> <substring> <out-var> [...])
3465 string(REPLACE <match-string> <replace-string> <out-var> <input>...)
3466 Regular Expressions
3468 string(REGEX MATCH <match-regex> <out-var> <input>...)
3469 string(REGEX MATCHALL <match-regex> <out-var> <input>...)
3470 string(REGEX REPLACE <match-regex> <replace-expr> <out-var> <input>...)
3471 Manipulation
3473 string(APPEND <string-var> [<input>...])
3474 string(PREPEND <string-var> [<input>...])
3475 string(CONCAT <out-var> [<input>...])
3476 string(JOIN <glue> <out-var> [<input>...])
3477 string(TOLOWER <string1> <out-var>)
3478 string(TOUPPER <string1> <out-var>)
3479 string(LENGTH <string> <out-var>)
3480 string(SUBSTRING <string> <begin> <length> <out-var>)
3481 string(STRIP <string> <out-var>)
3482 string(GENEX_STRIP <string> <out-var>)
3483 Comparison
3485 string(COMPARE <op> <string1> <string2> <out-var>)
3486 Hashing
3488 string(<HASH> <out-var> <input>)
3489 Generation
3491 string(ASCII <number>... <out-var>)
3492 string(CONFIGURE <string1> <out-var> [...])
3493 string(MAKE_C_IDENTIFIER <string> <out-var>)
3494 string(RANDOM [<option>...] <out-var>)
3495 string(TIMESTAMP <out-var> [<format string>] [UTC])
3496 string(UUID <out-var> ...)
3497 Search and Replace
3499 string(FIND <string> <substring> <output variable> [REVERSE])
3500 Return the position where the given substring was found in the supplied
3502 string. If the REVERSE flag was used, the command will search for the
3503 position of the last occurrence of the specified substring. If the
3504 substring is not found, a position of -1 is returned.
3505 string(REPLACE <match_string>
3507 <replace_string> <output variable>
3508 <input> [<input>...])
3509 Replace all occurrences of match_string in the input with
3511 replace_string and store the result in the output.
3512 Regular Expressions
3514 string(REGEX MATCH <regular_expression>
3515 <output variable> <input> [<input>...])
3516 Match the regular expression once and store the match in the output
3518 variable. All <input> arguments are concatenated before matching.
3519 string(REGEX MATCHALL <regular_expression>
3521 <output variable> <input> [<input>...])
3522 Match the regular expression as many times as possible and store the
3524 matches in the output variable as a list. All <input> arguments are
3525 concatenated before matching.
3526 string(REGEX REPLACE <regular_expression>
3528 <replace_expression> <output variable>
3529 <input> [<input>...])
3530 Match the regular expression as many times as possible and substitute
3532 the replacement expression for the match in the output. All <input>
3533 arguments are concatenated before matching.
3534 The replace expression may refer to paren-delimited subexpressions of
3536 the match using \1, \2, …, \9. Note that two backslashes (\\1) are
3537 required in CMake code to get a backslash through argument parsing.
3538 Regex Specification
3540 The following characters have special meaning in regular expressions:
3541 ^ Matches at beginning of input
3543 $ Matches at end of input
3545 . Matches any single character
3547 \<char>
3549 Matches the single character specified by <char>. Use this to
3550 match special regex characters, e.g. \. for a literal . or \\
3551 for a literal backslash \. Escaping a non-special character is
3552 unnecessary but allowed, e.g. \a matches a.
3553 [ ] Matches any character(s) inside the brackets
3555 [^ ] Matches any character(s) not inside the brackets
3557 - Inside brackets, specifies an inclusive range between characters
3559 on either side e.g. [a-f] is [abcdef] To match a literal - using
3560 brackets, make it the first or the last character e.g. [+*/-]
3561 matches basic mathematical operators.
3562 * Matches preceding pattern zero or more times
3564 + Matches preceding pattern one or more times
3566 ? Matches preceding pattern zero or once only
3568 | Matches a pattern on either side of the |
3570 () Saves a matched subexpression, which can be referenced in the
3572 REGEX REPLACE operation. Additionally it is saved by all regular
3573 expression-related commands, including e.g. if(MATCHES), in the
3574 variables CMAKE_MATCH_<n> for <n> 0..9.
3575 *, + and ? have higher precedence than concatenation. | has lower
3577 precedence than concatenation. This means that the regular expression
3578 ^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
3579 matches ab but not abd.
3580 CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
3582 to construct literal tabs, carriage returns, newlines, and backslashes
3583 (respectively) to pass in a regex. For example:
3584 · The quoted argument "[ \t\r\n]" specifies a regex that matches any
3586 single whitespace character.
3587 · The quoted argument "[/\\]" specifies a regex that matches a single
3589 forward slash / or backslash \.
3590 · The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
3592 single “word” character in the C locale.
3593 · The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
3595 the exact string (a+b). Each \\ is parsed in a quoted argument as
3596 just \, so the regex itself is actually \(\a\+\b\). This can alter‐
3597 natively be specified in a bracket argument without having to escape
3598 the backslashes, e.g. [[\(\a\+\b\)]].
3599 Manipulation
3601 string(APPEND <string variable> [<input>...])
3602 Append all the input arguments to the string.
3604 string(PREPEND <string variable> [<input>...])
3606 Prepend all the input arguments to the string.
3608 string(CONCAT <output variable> [<input>...])
3610 Concatenate all the input arguments together and store the result in
3612 the named output variable.
3613 string(JOIN <glue> <output variable> [<input>...])
3615 Join all the input arguments together using the glue string and store
3617 the result in the named output variable.
3618 To join list’s elements, use preferably the JOIN operator from list()
3620 command. This allows for the elements to have special characters like ;
3621 in them.
3622 string(TOLOWER <string1> <output variable>)
3624 Convert string to lower characters.
3626 string(TOUPPER <string1> <output variable>)
3628 Convert string to upper characters.
3630 string(LENGTH <string> <output variable>)
3632 Store in an output variable a given string’s length.
3634 string(SUBSTRING <string> <begin> <length> <output variable>)
3636 Store in an output variable a substring of a given string. If length
3638 is -1 the remainder of the string starting at begin will be returned.
3639 If string is shorter than length then end of string is used instead.
3640 NOTE:
3642 CMake 3.1 and below reported an error if length pointed past the end
3643 of string.
3644 string(STRIP <string> <output variable>)
3646 Store in an output variable a substring of a given string with leading
3648 and trailing spaces removed.
3649 string(GENEX_STRIP <input string> <output variable>)
3651 Strip any generator expressions from the input string and store the
3653 result in the output variable.
3654 Comparison
3656 string(COMPARE LESS <string1> <string2> <output variable>)
3657 string(COMPARE GREATER <string1> <string2> <output variable>)
3658 string(COMPARE EQUAL <string1> <string2> <output variable>)
3659 string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
3660 string(COMPARE LESS_EQUAL <string1> <string2> <output variable>)
3661 string(COMPARE GREATER_EQUAL <string1> <string2> <output variable>)
3662 Compare the strings and store true or false in the output variable.
3664 Hashing
3666 string(<HASH> <output variable> <input>)
3667 Compute a cryptographic hash of the input string. The supported <HASH>
3669 algorithm names are:
3670 MD5 Message-Digest Algorithm 5, RFC 1321.
3672 SHA1 US Secure Hash Algorithm 1, RFC 3174.
3674 SHA224 US Secure Hash Algorithms, RFC 4634.
3676 SHA256 US Secure Hash Algorithms, RFC 4634.
3678 SHA384 US Secure Hash Algorithms, RFC 4634.
3680 SHA512 US Secure Hash Algorithms, RFC 4634.
3682 SHA3_224
3684 Keccak SHA-3.
3685 SHA3_256
3687 Keccak SHA-3.
3688 SHA3_384
3690 Keccak SHA-3.
3691 SHA3_512
3693 Keccak SHA-3.
3694 Generation
3696 string(ASCII <number> [<number> ...] <output variable>)
3697 Convert all numbers into corresponding ASCII characters.
3699 string(CONFIGURE <string1> <output variable>
3701 [@ONLY] [ESCAPE_QUOTES])
3702 Transform a string like configure_file() transforms a file.
3704 string(MAKE_C_IDENTIFIER <input string> <output variable>)
3706 Convert each non-alphanumeric character in the <input string> to an
3708 underscore and store the result in the <output variable>. If the first
3709 character of the string is a digit, an underscore will also be
3710 prepended to the result.
3711 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
3713 [RANDOM_SEED <seed>] <output variable>)
3714 Return a random string of given length consisting of characters from
3716 the given alphabet. Default length is 5 characters and default alpha‐
3717 bet is all numbers and upper and lower case letters. If an integer
3718 RANDOM_SEED is given, its value will be used to seed the random number
3719 generator.
3720 string(TIMESTAMP <output variable> [<format string>] [UTC])
3722 Write a string representation of the current date and/or time to the
3724 output variable.
3725 Should the command be unable to obtain a timestamp the output variable
3727 will be set to the empty string “”.
3728 The optional UTC flag requests the current date/time representation to
3730 be in Coordinated Universal Time (UTC) rather than local time.
3731 The optional <format string> may contain the following format speci‐
3733 fiers:
3734 %% A literal percent sign (%).
3736 %d The day of the current month (01-31).
3737 %H The hour on a 24-hour clock (00-23).
3738 %I The hour on a 12-hour clock (01-12).
3739 %j The day of the current year (001-366).
3740 %m The month of the current year (01-12).
3741 %b Abbreviated month name (e.g. Oct).
3742 %B Full month name (e.g. October).
3743 %M The minute of the current hour (00-59).
3744 %s Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
3745 %S The second of the current minute.
3746 60 represents a leap second. (00-60)
3747 %U The week number of the current year (00-53).
3748 %w The day of the current week. 0 is Sunday. (0-6)
3749 %a Abbreviated weekday name (e.g. Fri).
3750 %A Full weekday name (e.g. Friday).
3751 %y The last two digits of the current year (00-99)
3752 %Y The current year.
3753 Unknown format specifiers will be ignored and copied to the output
3755 as-is.
3756 If no explicit <format string> is given it will default to:
3758 %Y-%m-%dT%H:%M:%S for local time.
3760 %Y-%m-%dT%H:%M:%SZ for UTC.
3761 NOTE:
3763 If the SOURCE_DATE_EPOCH environment variable is set, its value will
3764 be used instead of the current time. See
3765 https://reproducible-builds.org/specs/source-date-epoch/ for
3766 details.
3767 string(UUID <output variable> NAMESPACE <namespace> NAME <name>
3769 TYPE <MD5|SHA1> [UPPER])
3770 Create a universally unique identifier (aka GUID) as per RFC4122 based
3772 on the hash of the combined values of <namespace> (which itself has to
3773 be a valid UUID) and <name>. The hash algorithm can be either MD5
3774 (Version 3 UUID) or SHA1 (Version 5 UUID). A UUID has the format
3775 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where each x represents a lower
3776 case hexadecimal character. Where required an uppercase representation
3777 can be requested with the optional UPPER flag.
3778 unset
3780 Unset a variable, cache variable, or environment variable.
3781 Unset Normal Variable or Cache Entry
3783 unset(<variable> [CACHE | PARENT_SCOPE])
3784 Removes a normal variable from the current scope, causing it to become
3786 undefined. If CACHE is present, then a cache variable is removed
3787 instead of a normal variable. Note that when evaluating Variable Ref‐
3788 erences of the form ${VAR}, CMake first searches for a normal variable
3789 with that name. If no such normal variable exists, CMake will then
3790 search for a cache entry with that name. Because of this unsetting a
3791 normal variable can expose a cache variable that was previously hidden.
3792 To force a variable reference of the form ${VAR} to return an empty
3793 string, use set(<variable> ""), which clears the normal variable but
3794 leaves it defined.
3795 If PARENT_SCOPE is present then the variable is removed from the scope
3797 above the current scope. See the same option in the set() command for
3798 further details.
3799 Unset Environment Variable
3801 unset(ENV{<variable>})
3802 Removes <variable> from the currently available Environment Variables.
3804 Subsequent calls of $ENV{<variable>} will return the empty string.
3805 This command affects only the current CMake process, not the process
3807 from which CMake was called, nor the system environment at large, nor
3808 the environment of subsequent build or test processes.
3809 variable_watch
3811 Watch the CMake variable for change.
3812 variable_watch(<variable> [<command>])
3814 If the specified <variable> changes, a message will be printed to
3816 inform about the change.
3817 Additionally, if <command> is given, this command will be executed.
3819 The command will receive the following arguments: COMMAND(<variable>
3820 <access> <value> <current_list_file> <stack>)
3821 while
3823 Evaluate a group of commands while a condition is true
3824 while(<condition>)
3826 <commands>
3827 endwhile()
3828 All commands between while and the matching endwhile() are recorded
3830 without being invoked. Once the endwhile() is evaluated, the recorded
3831 list of commands is invoked as long as the <condition> is true.
3832 The <condition> has the same syntax and is evaluated using the same
3834 logic as described at length for the if() command.
3835 The commands break() and continue() provide means to escape from the
3837 normal control flow.
3838 Per legacy, the endwhile() command admits an optional <condition> argu‐
3840 ment. If used, it must be a verbatim repeat of the argument of the
3841 opening while command.
3842
3844 These commands are available only in CMake projects.
3845 add_compile_definitions
3847 Add preprocessor definitions to the compilation of source files.
3848 add_compile_definitions(<definition> ...)
3850 Adds preprocessor definitions to the compiler command line for targets
3852 in the current directory and below (whether added before or after this
3853 command is invoked). See documentation of the directory and target COM‐
3854 PILE_DEFINITIONS properties.
3855 Definitions are specified using the syntax VAR or VAR=value. Func‐
3857 tion-style definitions are not supported. CMake will automatically
3858 escape the value correctly for the native build system (note that CMake
3859 language syntax may require escapes to specify some values).
3860 Arguments to add_compile_definitions may use “generator expressions”
3862 with the syntax $<...>. See the cmake-generator-expressions(7) manual
3863 for available expressions. See the cmake-buildsystem(7) manual for
3864 more on defining buildsystem properties.
3865 add_compile_options
3867 Add options to the compilation of source files.
3868 add_compile_options(<option> ...)
3870 Adds options to the COMPILE_OPTIONS directory property. These options
3872 are used when compiling targets from the current directory and below.
3873 Arguments
3875 Arguments to add_compile_options may use “generator expressions” with
3876 the syntax $<...>. See the cmake-generator-expressions(7) manual for
3877 available expressions. See the cmake-buildsystem(7) manual for more on
3878 defining buildsystem properties.
3879 The final set of compile or link options used for a target is con‐
3881 structed by accumulating options from the current target and the usage
3882 requirements of it dependencies. The set of options is de-duplicated
3883 to avoid repetition. While beneficial for individual options, the
3884 de-duplication step can break up option groups. For example, -D A -D B
3885 becomes -D A B. One may specify a group of options using shell-like
3886 quoting along with a SHELL: prefix. The SHELL: prefix is dropped and
3887 the rest of the option string is parsed using the separate_arguments()
3888 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
3889 -D B.
3890 Example
3892 Since different compilers support different options, a typical use of
3893 this command is in a compiler-specific conditional clause:
3894 if (MSVC)
3896 # warning level 4 and all warnings as errors
3897 add_compile_options(/W4 /WX)
3898 else()
3899 # lots of warnings and all warnings as errors
3900 add_compile_options(-Wall -Wextra -pedantic -Werror)
3901 endif()
3902 See Also
3904 This command can be used to add any options. However, for adding pre‐
3905 processor definitions and include directories it is recommended to use
3906 the more specific commands add_compile_definitions() and include_direc‐
3907 tories().
3908 The command target_compile_options() adds target-specific options.
3910 add_custom_command
3912 Add a custom build rule to the generated build system.
3913 There are two main signatures for add_custom_command.
3915 Generating Files
3917 The first signature is for adding a custom command to produce an out‐
3918 put:
3919 add_custom_command(OUTPUT output1 [output2 ...]
3921 COMMAND command1 [ARGS] [args1...]
3922 [COMMAND command2 [ARGS] [args2...] ...]
3923 [MAIN_DEPENDENCY depend]
3924 [DEPENDS [depends...]]
3925 [BYPRODUCTS [files...]]
3926 [IMPLICIT_DEPENDS <lang1> depend1
3927 [<lang2> depend2] ...]
3928 [WORKING_DIRECTORY dir]
3929 [COMMENT comment]
3930 [DEPFILE depfile]
3931 [VERBATIM] [APPEND] [USES_TERMINAL]
3932 [COMMAND_EXPAND_LISTS])
3933 This defines a command to generate specified OUTPUT file(s). A target
3935 created in the same directory (CMakeLists.txt file) that specifies any
3936 output of the custom command as a source file is given a rule to gener‐
3937 ate the file using the command at build time. Do not list the output
3938 in more than one independent target that may build in parallel or the
3939 two instances of the rule may conflict (instead use the add_custom_tar‐
3940 get() command to drive the command and make the other targets depend on
3941 that one). In makefile terms this creates a new target in the follow‐
3942 ing form:
3943 OUTPUT: MAIN_DEPENDENCY DEPENDS
3945 COMMAND
3946 The options are:
3948 APPEND Append the COMMAND and DEPENDS option values to the custom com‐
3950 mand for the first output specified. There must have already
3951 been a previous call to this command with the same output. The
3952 COMMENT, MAIN_DEPENDENCY, and WORKING_DIRECTORY options are cur‐
3953 rently ignored when APPEND is given, but may be used in the
3954 future.
3955 BYPRODUCTS
3957 Specify the files the command is expected to produce but whose
3958 modification time may or may not be newer than the dependencies.
3959 If a byproduct name is a relative path it will be interpreted
3960 relative to the build tree directory corresponding to the cur‐
3961 rent source directory. Each byproduct file will be marked with
3962 the GENERATED source file property automatically.
3963 Explicit specification of byproducts is supported by the Ninja
3965 generator to tell the ninja build tool how to regenerate byprod‐
3966 ucts when they are missing. It is also useful when other build
3967 rules (e.g. custom commands) depend on the byproducts. Ninja
3968 requires a build rule for any generated file on which another
3969 rule depends even if there are order-only dependencies to ensure
3970 the byproducts will be available before their dependents build.
3971 The BYPRODUCTS option is ignored on non-Ninja generators except
3973 to mark byproducts GENERATED.
3974 COMMAND
3976 Specify the command-line(s) to execute at build time. If more
3977 than one COMMAND is specified they will be executed in order,
3978 but not necessarily composed into a stateful shell or batch
3979 script. (To run a full script, use the configure_file() command
3980 or the file(GENERATE) command to create it, and then specify a
3981 COMMAND to launch it.) The optional ARGS argument is for back‐
3982 ward compatibility and will be ignored.
3983 If COMMAND specifies an executable target name (created by the
3985 add_executable() command) it will automatically be replaced by
3986 the location of the executable created at build time. If set,
3987 the CROSSCOMPILING_EMULATOR executable target property will also
3988 be prepended to the command to allow the executable to run on
3989 the host. (Use the TARGET_FILE generator expression to refer‐
3990 ence an executable later in the command line.) Additionally a
3991 target-level dependency will be added so that the executable
3992 target will be built before any target using this custom com‐
3993 mand. However this does NOT add a file-level dependency that
3994 would cause the custom command to re-run whenever the executable
3995 is recompiled.
3996 Arguments to COMMAND may use generator expressions. References
3998 to target names in generator expressions imply target-level
3999 dependencies, but NOT file-level dependencies. List target
4000 names with the DEPENDS option to add file-level dependencies.
4001 COMMENT
4003 Display the given message before the commands are executed at
4004 build time.
4005 DEPENDS
4007 Specify files on which the command depends. If any dependency
4008 is an OUTPUT of another custom command in the same directory
4009 (CMakeLists.txt file) CMake automatically brings the other cus‐
4010 tom command into the target in which this command is built. If
4011 DEPENDS is not specified the command will run whenever the OUT‐
4012 PUT is missing; if the command does not actually create the OUT‐
4013 PUT then the rule will always run. If DEPENDS specifies any
4014 target (created by the add_custom_target(), add_executable(), or
4015 add_library() command) a target-level dependency is created to
4016 make sure the target is built before any target using this cus‐
4017 tom command. Additionally, if the target is an executable or
4018 library a file-level dependency is created to cause the custom
4019 command to re-run whenever the target is recompiled.
4020 Arguments to DEPENDS may use generator expressions.
4022 COMMAND_EXPAND_LISTS
4024 Lists in COMMAND arguments will be expanded, including those
4025 created with generator expressions, allowing COMMAND arguments
4026 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
4027 RIES>,;-I>" foo.cc to be properly expanded.
4028 IMPLICIT_DEPENDS
4030 Request scanning of implicit dependencies of an input file. The
4031 language given specifies the programming language whose corre‐
4032 sponding dependency scanner should be used. Currently only C
4033 and CXX language scanners are supported. The language has to be
4034 specified for every file in the IMPLICIT_DEPENDS list. Depen‐
4035 dencies discovered from the scanning are added to those of the
4036 custom command at build time. Note that the IMPLICIT_DEPENDS
4037 option is currently supported only for Makefile generators and
4038 will be ignored by other generators.
4039 MAIN_DEPENDENCY
4041 Specify the primary input source file to the command. This is
4042 treated just like any value given to the DEPENDS option but also
4043 suggests to Visual Studio generators where to hang the custom
4044 command. Each source file may have at most one command specify‐
4045 ing it as its main dependency. A compile command (i.e. for a
4046 library or an executable) counts as an implicit main dependency
4047 which gets silently overwritten by a custom command specifica‐
4048 tion.
4049 OUTPUT Specify the output files the command is expected to produce. If
4051 an output name is a relative path it will be interpreted rela‐
4052 tive to the build tree directory corresponding to the current
4053 source directory. Each output file will be marked with the GEN‐
4054 ERATED source file property automatically. If the output of the
4055 custom command is not actually created as a file on disk it
4056 should be marked with the SYMBOLIC source file property.
4057 USES_TERMINAL
4059 The command will be given direct access to the terminal if pos‐
4060 sible. With the Ninja generator, this places the command in the
4061 console pool.
4062 VERBATIM
4064 All arguments to the commands will be escaped properly for the
4065 build tool so that the invoked command receives each argument
4066 unchanged. Note that one level of escapes is still used by the
4067 CMake language processor before add_custom_command even sees the
4068 arguments. Use of VERBATIM is recommended as it enables correct
4069 behavior. When VERBATIM is not given the behavior is platform
4070 specific because there is no protection of tool-specific special
4071 characters.
4072 WORKING_DIRECTORY
4074 Execute the command with the given current working directory.
4075 If it is a relative path it will be interpreted relative to the
4076 build tree directory corresponding to the current source direc‐
4077 tory.
4078 Arguments to WORKING_DIRECTORY may use generator expressions.
4080 DEPFILE
4082 Specify a .d depfile for the Ninja generator. A .d file holds
4083 dependencies usually emitted by the custom command itself.
4084 Using DEPFILE with other generators than Ninja is an error.
4085 Build Events
4087 The second signature adds a custom command to a target such as a
4088 library or executable. This is useful for performing an operation
4089 before or after building the target. The command becomes part of the
4090 target and will only execute when the target itself is built. If the
4091 target is already built, the command will not execute.
4092 add_custom_command(TARGET <target>
4094 PRE_BUILD | PRE_LINK | POST_BUILD
4095 COMMAND command1 [ARGS] [args1...]
4096 [COMMAND command2 [ARGS] [args2...] ...]
4097 [BYPRODUCTS [files...]]
4098 [WORKING_DIRECTORY dir]
4099 [COMMENT comment]
4100 [VERBATIM] [USES_TERMINAL])
4101 This defines a new command that will be associated with building the
4103 specified <target>. The <target> must be defined in the current direc‐
4104 tory; targets defined in other directories may not be specified.
4105 When the command will happen is determined by which of the following is
4107 specified:
4108 PRE_BUILD
4110 On Visual Studio Generators, run before any other rules are exe‐
4111 cuted within the target. On other generators, run just before
4112 PRE_LINK commands.
4113 PRE_LINK
4115 Run after sources have been compiled but before linking the
4116 binary or running the librarian or archiver tool of a static
4117 library. This is not defined for targets created by the
4118 add_custom_target() command.
4119 POST_BUILD
4121 Run after all other rules within the target have been executed.
4122 NOTE:
4124 Because generator expressions can be used in custom commands, it is
4125 possible to define COMMAND lines or whole custom commands which
4126 evaluate to empty strings for certain configurations. For Visual
4127 Studio 2010 (and newer) generators these command lines or custom
4128 commands will be omitted for the specific configuration and no
4129 “empty-string-command” will be added.
4130 This allows to add individual build events for every configuration.
4132 add_custom_target
4134 Add a target with no output so it will always be built.
4135 add_custom_target(Name [ALL] [command1 [args1...]]
4137 [COMMAND command2 [args2...] ...]
4138 [DEPENDS depend depend depend ... ]
4139 [BYPRODUCTS [files...]]
4140 [WORKING_DIRECTORY dir]
4141 [COMMENT comment]
4142 [VERBATIM] [USES_TERMINAL]
4143 [COMMAND_EXPAND_LISTS]
4144 [SOURCES src1 [src2...]])
4145 Adds a target with the given name that executes the given commands.
4147 The target has no output file and is always considered out of date even
4148 if the commands try to create a file with the name of the target. Use
4149 the add_custom_command() command to generate a file with dependencies.
4150 By default nothing depends on the custom target. Use the add_dependen‐
4151 cies() command to add dependencies to or from other targets.
4152 The options are:
4154 ALL Indicate that this target should be added to the default build
4156 target so that it will be run every time (the command cannot be
4157 called ALL).
4158 BYPRODUCTS
4160 Specify the files the command is expected to produce but whose
4161 modification time may or may not be updated on subsequent
4162 builds. If a byproduct name is a relative path it will be
4163 interpreted relative to the build tree directory corresponding
4164 to the current source directory. Each byproduct file will be
4165 marked with the GENERATED source file property automatically.
4166 Explicit specification of byproducts is supported by the Ninja
4168 generator to tell the ninja build tool how to regenerate byprod‐
4169 ucts when they are missing. It is also useful when other build
4170 rules (e.g. custom commands) depend on the byproducts. Ninja
4171 requires a build rule for any generated file on which another
4172 rule depends even if there are order-only dependencies to ensure
4173 the byproducts will be available before their dependents build.
4174 The BYPRODUCTS option is ignored on non-Ninja generators except
4176 to mark byproducts GENERATED.
4177 COMMAND
4179 Specify the command-line(s) to execute at build time. If more
4180 than one COMMAND is specified they will be executed in order,
4181 but not necessarily composed into a stateful shell or batch
4182 script. (To run a full script, use the configure_file() command
4183 or the file(GENERATE) command to create it, and then specify a
4184 COMMAND to launch it.)
4185 If COMMAND specifies an executable target name (created by the
4187 add_executable() command) it will automatically be replaced by
4188 the location of the executable created at build time. If set,
4189 the CROSSCOMPILING_EMULATOR executable target property will also
4190 be prepended to the command to allow the executable to run on
4191 the host. Additionally a target-level dependency will be added
4192 so that the executable target will be built before this custom
4193 target.
4194 Arguments to COMMAND may use generator expressions. References
4196 to target names in generator expressions imply target-level
4197 dependencies.
4198 The command and arguments are optional and if not specified an
4200 empty target will be created.
4201 COMMENT
4203 Display the given message before the commands are executed at
4204 build time.
4205 DEPENDS
4207 Reference files and outputs of custom commands created with
4208 add_custom_command() command calls in the same directory (CMake‐
4209 Lists.txt file). They will be brought up to date when the tar‐
4210 get is built.
4211 Use the add_dependencies() command to add dependencies on other
4213 targets.
4214 COMMAND_EXPAND_LISTS
4216 Lists in COMMAND arguments will be expanded, including those
4217 created with generator expressions, allowing COMMAND arguments
4218 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
4219 RIES>,;-I>" foo.cc to be properly expanded.
4220 SOURCES
4222 Specify additional source files to be included in the custom
4223 target. Specified source files will be added to IDE project
4224 files for convenience in editing even if they have no build
4225 rules.
4226 VERBATIM
4228 All arguments to the commands will be escaped properly for the
4229 build tool so that the invoked command receives each argument
4230 unchanged. Note that one level of escapes is still used by the
4231 CMake language processor before add_custom_target even sees the
4232 arguments. Use of VERBATIM is recommended as it enables correct
4233 behavior. When VERBATIM is not given the behavior is platform
4234 specific because there is no protection of tool-specific special
4235 characters.
4236 USES_TERMINAL
4238 The command will be given direct access to the terminal if pos‐
4239 sible. With the Ninja generator, this places the command in the
4240 console pool.
4241 WORKING_DIRECTORY
4243 Execute the command with the given current working directory.
4244 If it is a relative path it will be interpreted relative to the
4245 build tree directory corresponding to the current source direc‐
4246 tory.
4247 Arguments to WORKING_DIRECTORY may use generator expressions.
4249 add_definitions
4251 Add -D define flags to the compilation of source files.
4252 add_definitions(-DFOO -DBAR ...)
4254 Adds definitions to the compiler command line for targets in the cur‐
4256 rent directory and below (whether added before or after this command is
4257 invoked). This command can be used to add any flags, but it is
4258 intended to add preprocessor definitions.
4259 NOTE:
4261 This command has been superseded by alternatives:
4262 · Use add_compile_definitions() to add preprocessor definitions.
4264 · Use include_directories() to add include directories.
4266 · Use add_compile_options() to add other options.
4268 Flags beginning in -D or /D that look like preprocessor definitions are
4270 automatically added to the COMPILE_DEFINITIONS directory property for
4271 the current directory. Definitions with non-trivial values may be left
4272 in the set of flags instead of being converted for reasons of backwards
4273 compatibility. See documentation of the directory, target, source file
4274 COMPILE_DEFINITIONS properties for details on adding preprocessor defi‐
4275 nitions to specific scopes and configurations.
4276 See the cmake-buildsystem(7) manual for more on defining buildsystem
4278 properties.
4279 add_dependencies
4281 Add a dependency between top-level targets.
4282 add_dependencies(<target> [<target-dependency>]...)
4284 Makes a top-level <target> depend on other top-level targets to ensure
4286 that they build before <target> does. A top-level target is one cre‐
4287 ated by one of the add_executable(), add_library(), or add_custom_tar‐
4288 get() commands (but not targets generated by CMake like install).
4289 Dependencies added to an imported target or an interface library are
4291 followed transitively in its place since the target itself does not
4292 build.
4293 See the DEPENDS option of add_custom_target() and add_custom_command()
4295 commands for adding file-level dependencies in custom rules. See the
4296 OBJECT_DEPENDS source file property to add file-level dependencies to
4297 object files.
4298 add_executable
4300 Add an executable to the project using the specified source files.
4301 add_executable(<name> [WIN32] [MACOSX_BUNDLE]
4303 [EXCLUDE_FROM_ALL]
4304 [source1] [source2 ...])
4305 Adds an executable target called <name> to be built from the source
4307 files listed in the command invocation. (The source files can be omit‐
4308 ted here if they are added later using target_sources().) The <name>
4309 corresponds to the logical target name and must be globally unique
4310 within a project. The actual file name of the executable built is con‐
4311 structed based on conventions of the native platform (such as
4312 <name>.exe or just <name>).
4313 By default the executable file will be created in the build tree direc‐
4315 tory corresponding to the source tree directory in which the command
4316 was invoked. See documentation of the RUNTIME_OUTPUT_DIRECTORY target
4317 property to change this location. See documentation of the OUTPUT_NAME
4318 target property to change the <name> part of the final file name.
4319 If WIN32 is given the property WIN32_EXECUTABLE will be set on the tar‐
4321 get created. See documentation of that target property for details.
4322 If MACOSX_BUNDLE is given the corresponding property will be set on the
4324 created target. See documentation of the MACOSX_BUNDLE target property
4325 for details.
4326 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
4328 the created target. See documentation of the EXCLUDE_FROM_ALL target
4329 property for details.
4330 Source arguments to add_executable may use “generator expressions” with
4332 the syntax $<...>. See the cmake-generator-expressions(7) manual for
4333 available expressions. See the cmake-buildsystem(7) manual for more on
4334 defining buildsystem properties.
4335 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
4337 cessed, and you want to have the original sources reachable from within
4338 IDE.
4339 ----
4342 add_executable(<name> IMPORTED [GLOBAL])
4346 An IMPORTED executable target references an executable file located
4348 outside the project. No rules are generated to build it, and the
4349 IMPORTED target property is True. The target name has scope in the
4350 directory in which it is created and below, but the GLOBAL option
4351 extends visibility. It may be referenced like any target built within
4352 the project. IMPORTED executables are useful for convenient reference
4353 from commands like add_custom_command(). Details about the imported
4354 executable are specified by setting properties whose names begin in
4355 IMPORTED_. The most important such property is IMPORTED_LOCATION (and
4356 its per-configuration version IMPORTED_LOCATION_<CONFIG>) which speci‐
4357 fies the location of the main executable file on disk. See documenta‐
4358 tion of the IMPORTED_* properties for more information.
4359 ----
4362 add_executable(<name> ALIAS <target>)
4366 Creates an Alias Target, such that <name> can be used to refer to <tar‐
4368 get> in subsequent commands. The <name> does not appear in the gener‐
4369 ated buildsystem as a make target. The <target> may not be a
4370 non-GLOBAL Imported Target or an ALIAS. ALIAS targets can be used as
4371 targets to read properties from, executables for custom commands and
4372 custom targets. They can also be tested for existence with the regular
4373 if(TARGET) subcommand. The <name> may not be used to modify properties
4374 of <target>, that is, it may not be used as the operand of set_prop‐
4375 erty(), set_target_properties(), target_link_libraries() etc. An ALIAS
4376 target may not be installed or exported.
4377 add_library
4379 Add a library to the project using the specified source files.
4380 Normal Libraries
4382 add_library(<name> [STATIC | SHARED | MODULE]
4383 [EXCLUDE_FROM_ALL]
4384 [source1] [source2 ...])
4385 Adds a library target called <name> to be built from the source files
4387 listed in the command invocation. (The source files can be omitted
4388 here if they are added later using target_sources().) The <name> cor‐
4389 responds to the logical target name and must be globally unique within
4390 a project. The actual file name of the library built is constructed
4391 based on conventions of the native platform (such as lib<name>.a or
4392 <name>.lib).
4393 STATIC, SHARED, or MODULE may be given to specify the type of library
4395 to be created. STATIC libraries are archives of object files for use
4396 when linking other targets. SHARED libraries are linked dynamically
4397 and loaded at runtime. MODULE libraries are plugins that are not
4398 linked into other targets but may be loaded dynamically at runtime
4399 using dlopen-like functionality. If no type is given explicitly the
4400 type is STATIC or SHARED based on whether the current value of the
4401 variable BUILD_SHARED_LIBS is ON. For SHARED and MODULE libraries the
4402 POSITION_INDEPENDENT_CODE target property is set to ON automatically.
4403 A SHARED or STATIC library may be marked with the FRAMEWORK target
4404 property to create an macOS Framework.
4405 If a library does not export any symbols, it must not be declared as a
4407 SHARED library. For example, a Windows resource DLL or a managed
4408 C++/CLI DLL that exports no unmanaged symbols would need to be a MODULE
4409 library. This is because CMake expects a SHARED library to always have
4410 an associated import library on Windows.
4411 By default the library file will be created in the build tree directory
4413 corresponding to the source tree directory in which the command was
4414 invoked. See documentation of the ARCHIVE_OUTPUT_DIRECTORY,
4415 LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY target proper‐
4416 ties to change this location. See documentation of the OUTPUT_NAME
4417 target property to change the <name> part of the final file name.
4418 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
4420 the created target. See documentation of the EXCLUDE_FROM_ALL target
4421 property for details.
4422 Source arguments to add_library may use “generator expressions” with
4424 the syntax $<...>. See the cmake-generator-expressions(7) manual for
4425 available expressions. See the cmake-buildsystem(7) manual for more on
4426 defining buildsystem properties.
4427 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
4429 cessed, and you want to have the original sources reachable from within
4430 IDE.
4431 Imported Libraries
4433 add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED
4434 [GLOBAL])
4435 An IMPORTED library target references a library file located outside
4437 the project. No rules are generated to build it, and the IMPORTED tar‐
4438 get property is True. The target name has scope in the directory in
4439 which it is created and below, but the GLOBAL option extends visibil‐
4440 ity. It may be referenced like any target built within the project.
4441 IMPORTED libraries are useful for convenient reference from commands
4442 like target_link_libraries(). Details about the imported library are
4443 specified by setting properties whose names begin in IMPORTED_ and
4444 INTERFACE_. The most important such property is IMPORTED_LOCATION (and
4445 its per-configuration variant IMPORTED_LOCATION_<CONFIG>) which speci‐
4446 fies the location of the main library file on disk. Or, for object
4447 libraries, IMPORTED_OBJECTS (and IMPORTED_OBJECTS_<CONFIG>) specifies
4448 the locations of object files on disk. See documentation of the
4449 IMPORTED_* and INTERFACE_* properties for more information.
4450 Object Libraries
4452 add_library(<name> OBJECT <src>...)
4453 Creates an Object Library. An object library compiles source files but
4455 does not archive or link their object files into a library. Instead
4456 other targets created by add_library() or add_executable() may refer‐
4457 ence the objects using an expression of the form $<TAR‐
4458 GET_OBJECTS:objlib> as a source, where objlib is the object library
4459 name. For example:
4460 add_library(... $<TARGET_OBJECTS:objlib> ...)
4462 add_executable(... $<TARGET_OBJECTS:objlib> ...)
4463 will include objlib’s object files in a library and an executable along
4465 with those compiled from their own sources. Object libraries may con‐
4466 tain only sources that compile, header files, and other files that
4467 would not affect linking of a normal library (e.g. .txt). They may
4468 contain custom commands generating such sources, but not PRE_BUILD,
4469 PRE_LINK, or POST_BUILD commands. Some native build systems (such as
4470 Xcode) may not like targets that have only object files, so consider
4471 adding at least one real source file to any target that references
4472 $<TARGET_OBJECTS:objlib>.
4473 Alias Libraries
4475 add_library(<name> ALIAS <target>)
4476 Creates an Alias Target, such that <name> can be used to refer to <tar‐
4478 get> in subsequent commands. The <name> does not appear in the gener‐
4479 ated buildsystem as a make target. The <target> may not be a
4480 non-GLOBAL Imported Target or an ALIAS. ALIAS targets can be used as
4481 linkable targets and as targets to read properties from. They can also
4482 be tested for existence with the regular if(TARGET) subcommand. The
4483 <name> may not be used to modify properties of <target>, that is, it
4484 may not be used as the operand of set_property(), set_target_proper‐
4485 ties(), target_link_libraries() etc. An ALIAS target may not be
4486 installed or exported.
4487 Interface Libraries
4489 add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
4490 Creates an Interface Library. An INTERFACE library target does not
4492 directly create build output, though it may have properties set on it
4493 and it may be installed, exported and imported. Typically the INTER‐
4494 FACE_* properties are populated on the interface target using the com‐
4495 mands:
4496 · set_property(),
4498 · target_link_libraries(INTERFACE),
4500 · target_link_options(INTERFACE),
4502 · target_include_directories(INTERFACE),
4504 · target_compile_options(INTERFACE),
4506 · target_compile_definitions(INTERFACE), and
4508 · target_sources(INTERFACE),
4510 and then it is used as an argument to target_link_libraries() like any
4512 other target.
4513 An INTERFACE Imported Target may also be created with this signature.
4515 An IMPORTED library target references a library defined outside the
4516 project. The target name has scope in the directory in which it is
4517 created and below, but the GLOBAL option extends visibility. It may be
4518 referenced like any target built within the project. IMPORTED
4519 libraries are useful for convenient reference from commands like tar‐
4520 get_link_libraries().
4521 add_link_options
4523 Add options to the link of shared library, module and executable tar‐
4524 gets.
4525 add_link_options(<option> ...)
4527 Adds options to the link step for targets in the current directory and
4529 below that are added after this command is invoked. See documentation
4530 of the directory and target LINK_OPTIONS properties.
4531 This command can be used to add any options, but alternative commands
4533 exist to add libraries (target_link_libraries() or link_libraries()).
4534 Arguments to add_link_options may use “generator expressions” with the
4536 syntax $<...>. See the cmake-generator-expressions(7) manual for
4537 available expressions. See the cmake-buildsystem(7) manual for more on
4538 defining buildsystem properties.
4539 The final set of compile or link options used for a target is con‐
4541 structed by accumulating options from the current target and the usage
4542 requirements of it dependencies. The set of options is de-duplicated
4543 to avoid repetition. While beneficial for individual options, the
4544 de-duplication step can break up option groups. For example, -D A -D B
4545 becomes -D A B. One may specify a group of options using shell-like
4546 quoting along with a SHELL: prefix. The SHELL: prefix is dropped and
4547 the rest of the option string is parsed using the separate_arguments()
4548 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
4549 -D B.
4550 To pass options to the linker tool, each compiler driver has is own
4552 syntax. The LINKER: prefix can be used to specify, in a portable way,
4553 options to pass to the linker tool. The LINKER: prefix is replaced by
4554 the required driver option and the rest of the option string defines
4555 linker arguments using , as separator. These arguments will be format‐
4556 ted according to the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
4557 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
4558 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
4560 Clang and -Wl,-z,defs for GNU GCC.
4561 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
4563 sion.
4564 The LINKER: prefix supports, as alternate syntax, specification of
4566 arguments using SHELL: prefix and space as separator. Previous example
4567 becomes "LINKER:SHELL:-z defs".
4568 NOTE:
4570 Specifying SHELL: prefix elsewhere than at the beginning of the
4571 LINKER: prefix is not supported.
4572 add_subdirectory
4574 Add a subdirectory to the build.
4575 add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
4577 Adds a subdirectory to the build. The source_dir specifies the direc‐
4579 tory in which the source CMakeLists.txt and code files are located. If
4580 it is a relative path it will be evaluated with respect to the current
4581 directory (the typical usage), but it may also be an absolute path.
4582 The binary_dir specifies the directory in which to place the output
4583 files. If it is a relative path it will be evaluated with respect to
4584 the current output directory, but it may also be an absolute path. If
4585 binary_dir is not specified, the value of source_dir, before expanding
4586 any relative path, will be used (the typical usage). The CMake‐
4587 Lists.txt file in the specified source directory will be processed
4588 immediately by CMake before processing in the current input file con‐
4589 tinues beyond this command.
4590 If the EXCLUDE_FROM_ALL argument is provided then targets in the subdi‐
4592 rectory will not be included in the ALL target of the parent directory
4593 by default, and will be excluded from IDE project files. Users must
4594 explicitly build targets in the subdirectory. This is meant for use
4595 when the subdirectory contains a separate part of the project that is
4596 useful but not necessary, such as a set of examples. Typically the
4597 subdirectory should contain its own project() command invocation so
4598 that a full build system will be generated in the subdirectory (such as
4599 a VS IDE solution file). Note that inter-target dependencies supersede
4600 this exclusion. If a target built by the parent project depends on a
4601 target in the subdirectory, the dependee target will be included in the
4602 parent project build system to satisfy the dependency.
4603 add_test
4605 Add a test to the project to be run by ctest(1).
4606 add_test(NAME <name> COMMAND <command> [<arg>...]
4608 [CONFIGURATIONS <config>...]
4609 [WORKING_DIRECTORY <dir>])
4610 Adds a test called <name>. The test name may not contain spaces,
4612 quotes, or other characters special in CMake syntax. The options are:
4613 COMMAND
4615 Specify the test command-line. If <command> specifies an exe‐
4616 cutable target (created by add_executable()) it will automati‐
4617 cally be replaced by the location of the executable created at
4618 build time.
4619 CONFIGURATIONS
4621 Restrict execution of the test only to the named configurations.
4622 WORKING_DIRECTORY
4624 Set the WORKING_DIRECTORY test property to specify the working
4625 directory in which to execute the test. If not specified the
4626 test will be run with the current working directory set to the
4627 build directory corresponding to the current source directory.
4628 The given test command is expected to exit with code 0 to pass and
4630 non-zero to fail, or vice-versa if the WILL_FAIL test property is set.
4631 Any output written to stdout or stderr will be captured by ctest(1) but
4632 does not affect the pass/fail status unless the PASS_REGULAR_EXPRESSION
4633 or FAIL_REGULAR_EXPRESSION test property is used.
4634 The COMMAND and WORKING_DIRECTORY options may use “generator expres‐
4636 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
4637 manual for available expressions.
4638 Example usage:
4640 add_test(NAME mytest
4642 COMMAND testDriver --config $<CONFIGURATION>
4643 --exe $<TARGET_FILE:myexe>)
4644 This creates a test mytest whose command runs a testDriver tool passing
4646 the configuration name and the full path to the executable file pro‐
4647 duced by target myexe.
4648 NOTE:
4650 CMake will generate tests only if the enable_testing() command has
4651 been invoked. The CTest module invokes the command automatically
4652 when the BUILD_TESTING option is ON.
4653 ----
4656 add_test(<name> <command> [<arg>...])
4660 Add a test called <name> with the given command-line. Unlike the above
4662 NAME signature no transformation is performed on the command-line to
4663 support target names or generator expressions.
4664 aux_source_directory
4666 Find all source files in a directory.
4667 aux_source_directory(<dir> <variable>)
4669 Collects the names of all the source files in the specified directory
4671 and stores the list in the <variable> provided. This command is
4672 intended to be used by projects that use explicit template instantia‐
4673 tion. Template instantiation files can be stored in a “Templates” sub‐
4674 directory and collected automatically using this command to avoid manu‐
4675 ally listing all instantiations.
4676 It is tempting to use this command to avoid writing the list of source
4678 files for a library or executable target. While this seems to work,
4679 there is no way for CMake to generate a build system that knows when a
4680 new source file has been added. Normally the generated build system
4681 knows when it needs to rerun CMake because the CMakeLists.txt file is
4682 modified to add a new source. When the source is just added to the
4683 directory without modifying this file, one would have to manually rerun
4684 CMake to generate a build system incorporating the new file.
4685 build_command
4687 Get a command line to build the current project. This is mainly
4688 intended for internal use by the CTest module.
4689 build_command(<variable>
4691 [CONFIGURATION <config>]
4692 [TARGET <target>]
4693 [PROJECT_NAME <projname>] # legacy, causes warning
4694 )
4695 Sets the given <variable> to a command-line string of the form:
4697 <cmake> --build . [--config <config>] [--target <target>] [-- -i]
4699 where <cmake> is the location of the cmake(1) command-line tool, and
4701 <config> and <target> are the values provided to the CONFIGURATION and
4702 TARGET options, if any. The trailing -- -i option is added for Make‐
4703 file Generators if policy CMP0061 is not set to NEW.
4704 When invoked, this cmake --build command line will launch the underly‐
4706 ing build system tool.
4707 build_command(<cachevariable> <makecommand>)
4709 This second signature is deprecated, but still available for backwards
4711 compatibility. Use the first signature instead.
4712 It sets the given <cachevariable> to a command-line string as above but
4714 without the --target option. The <makecommand> is ignored but should
4715 be the full path to devenv, nmake, make or one of the end user build
4716 tools for legacy invocations.
4717 NOTE:
4719 In CMake versions prior to 3.0 this command returned a command line
4720 that directly invokes the native build tool for the current genera‐
4721 tor. Their implementation of the PROJECT_NAME option had no useful
4722 effects, so CMake now warns on use of the option.
4723 create_test_sourcelist
4725 Create a test driver and source list for building test programs.
4726 create_test_sourcelist(sourceListName driverName
4728 test1 test2 test3
4729 EXTRA_INCLUDE include.h
4730 FUNCTION function)
4731 A test driver is a program that links together many small tests into a
4733 single executable. This is useful when building static executables
4734 with large libraries to shrink the total required size. The list of
4735 source files needed to build the test driver will be in sourceListName.
4736 driverName is the name of the test driver program. The rest of the
4737 arguments consist of a list of test source files, can be semicolon sep‐
4738 arated. Each test source file should have a function in it that is the
4739 same name as the file with no extension (foo.cxx should have int
4740 foo(int, char*[]);) driverName will be able to call each of the tests
4741 by name on the command line. If EXTRA_INCLUDE is specified, then the
4742 next argument is included into the generated file. If FUNCTION is
4743 specified, then the next argument is taken as a function name that is
4744 passed a pointer to ac and av. This can be used to add extra command
4745 line processing to each test. The CMAKE_TESTDRIVER_BEFORE_TESTMAIN
4746 cmake variable can be set to have code that will be placed directly
4747 before calling the test main function. CMAKE_TESTDRIVER_AFTER_TESTMAIN
4748 can be set to have code that will be placed directly after the call to
4749 the test main function.
4750 define_property
4752 Define and document custom properties.
4753 define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
4755 TEST | VARIABLE | CACHED_VARIABLE>
4756 PROPERTY <name> [INHERITED]
4757 BRIEF_DOCS <brief-doc> [docs...]
4758 FULL_DOCS <full-doc> [docs...])
4759 Defines one property in a scope for use with the set_property() and
4761 get_property() commands. This is primarily useful to associate docu‐
4762 mentation with property names that may be retrieved with the get_prop‐
4763 erty() command. The first argument determines the kind of scope in
4764 which the property should be used. It must be one of the following:
4765 GLOBAL = associated with the global namespace
4767 DIRECTORY = associated with one directory
4768 TARGET = associated with one target
4769 SOURCE = associated with one source file
4770 TEST = associated with a test named with add_test
4771 VARIABLE = documents a CMake language variable
4772 CACHED_VARIABLE = documents a CMake cache variable
4773 Note that unlike set_property() and get_property() no actual scope
4775 needs to be given; only the kind of scope is important.
4776 The required PROPERTY option is immediately followed by the name of the
4778 property being defined.
4779 If the INHERITED option is given, then the get_property() command will
4781 chain up to the next higher scope when the requested property is not
4782 set in the scope given to the command.
4783 · DIRECTORY scope chains to its parent directory’s scope, continuing
4785 the walk up parent directories until a directory has the property set
4786 or there are no more parents. If still not found at the top level
4787 directory, it chains to the GLOBAL scope.
4788 · TARGET, SOURCE and TEST properties chain to DIRECTORY scope, includ‐
4790 ing further chaining up the directories, etc. as needed.
4791 Note that this scope chaining behavior only applies to calls to
4793 get_property(), get_directory_property(), get_target_property(),
4794 get_source_file_property() and get_test_property(). There is no inher‐
4795 iting behavior when setting properties, so using APPEND or
4796 APPEND_STRING with the set_property() command will not consider inher‐
4797 ited values when working out the contents to append to.
4798 The BRIEF_DOCS and FULL_DOCS options are followed by strings to be
4800 associated with the property as its brief and full documentation. Cor‐
4801 responding options to the get_property() command will retrieve the doc‐
4802 umentation.
4803 enable_language
4805 Enable a language (CXX/C/Fortran/etc)
4806 enable_language(<lang> [OPTIONAL] )
4808 Enables support for the named language in CMake. This is the same as
4810 the project() command but does not create any of the extra variables
4811 that are created by the project command. Example languages are CXX, C,
4812 CUDA, Fortran, and ASM.
4813 If enabling ASM, enable it last so that CMake can check whether compil‐
4815 ers for other languages like C work for assembly too.
4816 This command must be called in file scope, not in a function call.
4818 Furthermore, it must be called in the highest directory common to all
4819 targets using the named language directly for compiling sources or
4820 indirectly through link dependencies. It is simplest to enable all
4821 needed languages in the top-level directory of a project.
4822 The OPTIONAL keyword is a placeholder for future implementation and
4824 does not currently work. Instead you can use the CheckLanguage module
4825 to verify support before enabling.
4826 enable_testing
4828 Enable testing for current directory and below.
4829 enable_testing()
4831 Enables testing for this directory and below. See also the add_test()
4833 command. Note that ctest expects to find a test file in the build
4834 directory root. Therefore, this command should be in the source direc‐
4835 tory root.
4836 export
4838 Export targets from the build tree for use by outside projects.
4839 export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
4841 Creates a file <filename> that may be included by outside projects to
4843 import targets from the current project’s build tree. This is useful
4844 during cross-compiling to build utility executables that can run on the
4845 host platform in one project and then import them into another project
4846 being compiled for the target platform. If the NAMESPACE option is
4847 given the <namespace> string will be prepended to all target names
4848 written to the file.
4849 Target installations are associated with the export <export-name> using
4851 the EXPORT option of the install(TARGETS) command.
4852 The file created by this command is specific to the build tree and
4854 should never be installed. See the install(EXPORT) command to export
4855 targets from an installation tree.
4856 The properties set on the generated IMPORTED targets will have the same
4858 values as the final values of the input TARGETS.
4859 export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
4861 [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
4862 This signature is similar to the EXPORT signature, but targets are
4864 listed explicitly rather than specified as an export-name. If the
4865 APPEND option is given the generated code will be appended to the file
4866 instead of overwriting it. The EXPORT_LINK_INTERFACE_LIBRARIES key‐
4867 word, if present, causes the contents of the properties matching
4868 (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when
4869 policy CMP0022 is NEW. If a library target is included in the export
4870 but a target to which it links is not included the behavior is unspeci‐
4871 fied.
4872 NOTE:
4874 Object Libraries under Xcode have special handling if multiple
4875 architectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
4876 they will be exported as Interface Libraries with no object files
4877 available to clients. This is sufficient to satisfy transitive
4878 usage requirements of other targets that link to the object
4879 libraries in their implementation.
4880 export(PACKAGE <PackageName>)
4882 Store the current build directory in the CMake user package registry
4884 for package <PackageName>. The find_package command may consider the
4885 directory while searching for package <PackageName>. This helps depen‐
4886 dent projects find and use a package from the current project’s build
4887 tree without help from the user. Note that the entry in the package
4888 registry that this command creates works only in conjunction with a
4889 package configuration file (<PackageName>Config.cmake) that works with
4890 the build tree. In some cases, for example for packaging and for system
4891 wide installations, it is not desirable to write the user package reg‐
4892 istry. If the CMAKE_EXPORT_NO_PACKAGE_REGISTRY variable is enabled, the
4893 export(PACKAGE) command will do nothing.
4894 export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
4896 This signature exports cmake built targets to the android ndk build
4898 system by creating an Android.mk file that references the prebuilt tar‐
4899 gets. The Android NDK supports the use of prebuilt libraries, both
4900 static and shared. This allows cmake to build the libraries of a
4901 project and make them available to an ndk build system complete with
4902 transitive dependencies, include flags and defines required to use the
4903 libraries. The signature takes a list of targets and puts them in the
4904 Android.mk file specified by the <filename> given. This signature can
4905 only be used if policy CMP0022 is NEW for all targets given. A error
4906 will be issued if that policy is set to OLD for one of the targets.
4907 fltk_wrap_ui
4909 Create FLTK user interfaces Wrappers.
4910 fltk_wrap_ui(resultingLibraryName source1
4912 source2 ... sourceN )
4913 Produce .h and .cxx files for all the .fl and .fld files listed. The
4915 resulting .h and .cxx files will be added to a variable named result‐
4916 ingLibraryName_FLTK_UI_SRCS which should be added to your library.
4917 get_source_file_property
4919 Get a property for a source file.
4920 get_source_file_property(VAR file property)
4922 Gets a property from a source file. The value of the property is
4924 stored in the variable VAR. If the source property is not found, the
4925 behavior depends on whether it has been defined to be an INHERITED
4926 property or not (see define_property()). Non-inherited properties will
4927 set VAR to “NOTFOUND”, whereas inherited properties will search the
4928 relevant parent scope as described for the define_property() command
4929 and if still unable to find the property, VAR will be set to an empty
4930 string.
4931 Use set_source_files_properties() to set property values. Source file
4933 properties usually control how the file is built. One property that is
4934 always there is LOCATION.
4935 See also the more general get_property() command.
4937 get_target_property
4939 Get a property from a target.
4940 get_target_property(VAR target property)
4942 Get a property from a target. The value of the property is stored in
4944 the variable VAR. If the target property is not found, the behavior
4945 depends on whether it has been defined to be an INHERITED property or
4946 not (see define_property()). Non-inherited properties will set VAR to
4947 “NOTFOUND”, whereas inherited properties will search the relevant par‐
4948 ent scope as described for the define_property() command and if still
4949 unable to find the property, VAR will be set to an empty string.
4950 Use set_target_properties() to set target property values. Properties
4952 are usually used to control how a target is built, but some query the
4953 target instead. This command can get properties for any target so far
4954 created. The targets do not need to be in the current CMakeLists.txt
4955 file.
4956 See also the more general get_property() command.
4958 See Target Properties for the list of properties known to CMake.
4960 get_test_property
4962 Get a property of the test.
4963 get_test_property(test property VAR)
4965 Get a property from the test. The value of the property is stored in
4967 the variable VAR. If the test property is not found, the behavior
4968 depends on whether it has been defined to be an INHERITED property or
4969 not (see define_property()). Non-inherited properties will set VAR to
4970 “NOTFOUND”, whereas inherited properties will search the relevant par‐
4971 ent scope as described for the define_property() command and if still
4972 unable to find the property, VAR will be set to an empty string.
4973 For a list of standard properties you can type cmake --help-prop‐
4975 erty-list.
4976 See also the more general get_property() command.
4978 include_directories
4980 Add include directories to the build.
4981 include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])
4983 Add the given directories to those the compiler uses to search for
4985 include files. Relative paths are interpreted as relative to the cur‐
4986 rent source directory.
4987 The include directories are added to the INCLUDE_DIRECTORIES directory
4989 property for the current CMakeLists file. They are also added to the
4990 INCLUDE_DIRECTORIES target property for each target in the current
4991 CMakeLists file. The target property values are the ones used by the
4992 generators.
4993 By default the directories specified are appended onto the current list
4995 of directories. This default behavior can be changed by setting
4996 CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE
4997 explicitly, you can select between appending and prepending, indepen‐
4998 dent of the default.
4999 If the SYSTEM option is given, the compiler will be told the directo‐
5001 ries are meant as system include directories on some platforms. Sig‐
5002 nalling this setting might achieve effects such as the compiler skip‐
5003 ping warnings, or these fixed-install system files not being considered
5004 in dependency calculations - see compiler docs.
5005 Arguments to include_directories may use “generator expressions” with
5007 the syntax “$<…>”. See the cmake-generator-expressions(7) manual for
5008 available expressions. See the cmake-buildsystem(7) manual for more on
5009 defining buildsystem properties.
5010 NOTE:
5012 Prefer the target_include_directories() command to add include
5013 directories to individual targets and optionally propagate/export
5014 them to dependents.
5015 include_external_msproject
5017 Include an external Microsoft project file in a workspace.
5018 include_external_msproject(projectname location
5020 [TYPE projectTypeGUID]
5021 [GUID projectGUID]
5022 [PLATFORM platformName]
5023 dep1 dep2 ...)
5024 Includes an external Microsoft project in the generated workspace file.
5026 Currently does nothing on UNIX. This will create a target named [pro‐
5027 jectname]. This can be used in the add_dependencies() command to make
5028 things depend on the external project.
5029 TYPE, GUID and PLATFORM are optional parameters that allow one to spec‐
5031 ify the type of project, id (GUID) of the project and the name of the
5032 target platform. This is useful for projects requiring values other
5033 than the default (e.g. WIX projects).
5034 If the imported project has different configuration names than the cur‐
5036 rent project, set the MAP_IMPORTED_CONFIG_<CONFIG> target property to
5037 specify the mapping.
5038 include_regular_expression
5040 Set the regular expression used for dependency checking.
5041 include_regular_expression(regex_match [regex_complain])
5043 Sets the regular expressions used in dependency checking. Only files
5045 matching regex_match will be traced as dependencies. Only files match‐
5046 ing regex_complain will generate warnings if they cannot be found
5047 (standard header paths are not searched). The defaults are:
5048 regex_match = "^.*$" (match everything)
5050 regex_complain = "^$" (match empty string only)
5051 install
5053 Specify rules to run at install time.
5054 Synopsis
5056 install(TARGETS <target>... [...])
5057 install({FILES | PROGRAMS} <file>... [...])
5058 install(DIRECTORY <dir>... [...])
5059 install(SCRIPT <file> [...])
5060 install(CODE <code> [...])
5061 install(EXPORT <export-name> [...])
5062 Introduction
5064 This command generates installation rules for a project. Rules speci‐
5065 fied by calls to this command within a source directory are executed in
5066 order during installation. The order across directories is not
5067 defined.
5068 There are multiple signatures for this command. Some of them define
5070 installation options for files and targets. Options common to multiple
5071 signatures are covered here but they are valid only for signatures that
5072 specify them. The common options are:
5073 DESTINATION
5075 Specify the directory on disk to which a file will be installed.
5076 If a full path (with a leading slash or drive letter) is given
5077 it is used directly. If a relative path is given it is inter‐
5078 preted relative to the value of the CMAKE_INSTALL_PREFIX vari‐
5079 able. The prefix can be relocated at install time using the
5080 DESTDIR mechanism explained in the CMAKE_INSTALL_PREFIX variable
5081 documentation.
5082 PERMISSIONS
5084 Specify permissions for installed files. Valid permissions are
5085 OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE,
5086 GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID,
5087 and SETGID. Permissions that do not make sense on certain plat‐
5088 forms are ignored on those platforms.
5089 CONFIGURATIONS
5091 Specify a list of build configurations for which the install
5092 rule applies (Debug, Release, etc.). Note that the values speci‐
5093 fied for this option only apply to options listed AFTER the CON‐
5094 FIGURATIONS option. For example, to set separate install paths
5095 for the Debug and Release configurations, do the following:
5096 install(TARGETS target
5098 CONFIGURATIONS Debug
5099 RUNTIME DESTINATION Debug/bin)
5100 install(TARGETS target
5101 CONFIGURATIONS Release
5102 RUNTIME DESTINATION Release/bin)
5103 Note that CONFIGURATIONS appears BEFORE RUNTIME DESTINATION.
5105 COMPONENT
5107 Specify an installation component name with which the install
5108 rule is associated, such as “runtime” or “development”. During
5109 component-specific installation only install rules associated
5110 with the given component name will be executed. During a full
5111 installation all components are installed unless marked with
5112 EXCLUDE_FROM_ALL. If COMPONENT is not provided a default compo‐
5113 nent “Unspecified” is created. The default component name may
5114 be controlled with the CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
5115 variable.
5116 EXCLUDE_FROM_ALL
5118 Specify that the file is excluded from a full installation and
5119 only installed as part of a component-specific installation
5120 RENAME Specify a name for an installed file that may be different from
5122 the original file. Renaming is allowed only when a single file
5123 is installed by the command.
5124 OPTIONAL
5126 Specify that it is not an error if the file to be installed does
5127 not exist.
5128 Command signatures that install files may print messages during instal‐
5130 lation. Use the CMAKE_INSTALL_MESSAGE variable to control which mes‐
5131 sages are printed.
5132 Many of the install() variants implicitly create the directories con‐
5134 taining the installed files. If CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMIS‐
5135 SIONS is set, these directories will be created with the permissions
5136 specified. Otherwise, they will be created according to the uname rules
5137 on Unix-like platforms. Windows platforms are unaffected.
5138 Installing Targets
5140 install(TARGETS targets... [EXPORT <export-name>]
5141 [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
5142 PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
5143 [DESTINATION <dir>]
5144 [PERMISSIONS permissions...]
5145 [CONFIGURATIONS [Debug|Release|...]]
5146 [COMPONENT <component>]
5147 [NAMELINK_COMPONENT <component>]
5148 [OPTIONAL] [EXCLUDE_FROM_ALL]
5149 [NAMELINK_ONLY|NAMELINK_SKIP]
5150 ] [...]
5151 [INCLUDES DESTINATION [<dir> ...]]
5152 )
5153 The TARGETS form specifies rules for installing targets from a project.
5155 There are several kinds of target files that may be installed:
5156 ARCHIVE
5158 Static libraries are treated as ARCHIVE targets, except those
5159 marked with the FRAMEWORK property on macOS (see FRAMEWORK
5160 below.) For DLL platforms (all Windows-based systems including
5161 Cygwin), the DLL import library is treated as an ARCHIVE target.
5162 LIBRARY
5164 Module libraries are always treated as LIBRARY targets. For non-
5165 DLL platforms shared libraries are treated as LIBRARY targets,
5166 except those marked with the FRAMEWORK property on macOS (see
5167 FRAMEWORK below.)
5168 RUNTIME
5170 Executables are treated as RUNTIME objects, except those marked
5171 with the MACOSX_BUNDLE property on macOS (see BUNDLE below.)
5172 For DLL platforms (all Windows-based systems including Cygwin),
5173 the DLL part of a shared library is treated as a RUNTIME target.
5174 OBJECTS
5176 Object libraries (a simple group of object files) are always
5177 treated as OBJECTS targets.
5178 FRAMEWORK
5180 Both static and shared libraries marked with the FRAMEWORK prop‐
5181 erty are treated as FRAMEWORK targets on macOS.
5182 BUNDLE Executables marked with the MACOSX_BUNDLE property are treated
5184 as BUNDLE targets on macOS.
5185 PUBLIC_HEADER
5187 Any PUBLIC_HEADER files associated with a library are installed
5188 in the destination specified by the PUBLIC_HEADER argument on
5189 non-Apple platforms. Rules defined by this argument are ignored
5190 for FRAMEWORK libraries on Apple platforms because the associ‐
5191 ated files are installed into the appropriate locations inside
5192 the framework folder. See PUBLIC_HEADER for details.
5193 PRIVATE_HEADER
5195 Similar to PUBLIC_HEADER, but for PRIVATE_HEADER files. See PRI‐
5196 VATE_HEADER for details.
5197 RESOURCE
5199 Similar to PUBLIC_HEADER and PRIVATE_HEADER, but for RESOURCE
5200 files. See RESOURCE for details.
5201 For each of these arguments given, the arguments following them only
5203 apply to the target or file type specified in the argument. If none is
5204 given, the installation properties apply to all target types. If only
5205 one is given then only targets of that type will be installed (which
5206 can be used to install just a DLL or just an import library.)
5207 For regular executables, static libraries and shared libraries, the
5209 DESTINATION argument is not required. For these target types, when
5210 DESTINATION is omitted, a default destination will be taken from the
5211 appropriate variable from GNUInstallDirs, or set to a built-in default
5212 value if that variable is not defined. The same is true for the public
5213 and private headers associated with the installed targets through the
5214 PUBLIC_HEADER and PRIVATE_HEADER target properties. A destination must
5215 always be provided for module libraries, Apple bundles and frameworks.
5216 A destination can be omitted for interface and object libraries, but
5217 they are handled differently (see the discussion of this topic toward
5218 the end of this section).
5219 The following table shows the target types with their associated vari‐
5221 ables and built-in defaults that apply when no destination is given:
5222 ┌───────────────┬─────────────────────────────┬──────────────────┐
5224 │Target Type │ GNUInstallDirs │ Built-In Default │
5225 │ │ Variable │ │
5226 ├───────────────┼─────────────────────────────┼──────────────────┤
5227 │RUNTIME │ ${CMAKE_INSTALL_BINDIR} │ bin │
5228 ├───────────────┼─────────────────────────────┼──────────────────┤
5229 │LIBRARY │ ${CMAKE_INSTALL_LIBDIR} │ lib │
5230 ├───────────────┼─────────────────────────────┼──────────────────┤
5231 │ARCHIVE │ ${CMAKE_INSTALL_LIBDIR} │ lib │
5232 ├───────────────┼─────────────────────────────┼──────────────────┤
5233 │PRIVATE_HEADER │ ${CMAKE_INSTALL_INCLUDEDIR} │ include │
5234 ├───────────────┼─────────────────────────────┼──────────────────┤
5235 │PUBLIC_HEADER │ ${CMAKE_INSTALL_INCLUDEDIR} │ include │
5236 └───────────────┴─────────────────────────────┴──────────────────┘
5237 Projects wishing to follow the common practice of installing headers
5239 into a project-specific subdirectory will need to provide a destination
5240 rather than rely on the above.
5241 To make packages compliant with distribution filesystem layout poli‐
5243 cies, if projects must specify a DESTINATION, it is recommended that
5244 they use a path that begins with the appropriate GNUInstallDirs vari‐
5245 able. This allows package maintainers to control the install destina‐
5246 tion by setting the appropriate cache variables. The following example
5247 shows a static library being installed to the default destination pro‐
5248 vided by GNUInstallDirs, but with its headers installed to a
5249 project-specific subdirectory that follows the above recommendation:
5250 add_library(mylib STATIC ...)
5252 set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
5253 include(GNUInstallDirs)
5254 install(TARGETS mylib
5255 PUBLIC_HEADER
5256 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
5257 )
5258 In addition to the common options listed above, each target can accept
5260 the following additional arguments:
5261 NAMELINK_COMPONENT
5263 On some platforms a versioned shared library has a symbolic link
5264 such as:
5265 lib<name>.so -> lib<name>.so.1
5267 where lib<name>.so.1 is the soname of the library and
5269 lib<name>.so is a “namelink” allowing linkers to find the
5270 library when given -l<name>. The NAMELINK_COMPONENT option is
5271 similar to the COMPONENT option, but it changes the installation
5272 component of a shared library namelink if one is generated. If
5273 not specified, this defaults to the value of COMPONENT. It is an
5274 error to use this parameter outside of a LIBRARY block.
5275 Consider the following example:
5277 install(TARGETS mylib
5279 LIBRARY
5280 COMPONENT Libraries
5281 NAMELINK_COMPONENT Development
5282 PUBLIC_HEADER
5283 COMPONENT Development
5284 )
5285 In this scenario, if you choose to install only the Development
5287 component, both the headers and namelink will be installed with‐
5288 out the library. (If you don’t also install the Libraries compo‐
5289 nent, the namelink will be a dangling symlink, and projects that
5290 link to the library will have build errors.) If you install only
5291 the Libraries component, only the library will be installed,
5292 without the headers and namelink.
5293 This option is typically used for package managers that have
5295 separate runtime and development packages. For example, on
5296 Debian systems, the library is expected to be in the runtime
5297 package, and the headers and namelink are expected to be in the
5298 development package.
5299 See the VERSION and SOVERSION target properties for details on
5301 creating versioned shared libraries.
5302 NAMELINK_ONLY
5304 This option causes the installation of only the namelink when a
5305 library target is installed. On platforms where versioned shared
5306 libraries do not have namelinks or when a library is not ver‐
5307 sioned, the NAMELINK_ONLY option installs nothing. It is an
5308 error to use this parameter outside of a LIBRARY block.
5309 When NAMELINK_ONLY is given, either NAMELINK_COMPONENT or COMPO‐
5311 NENT may be used to specify the installation component of the
5312 namelink, but COMPONENT should generally be preferred.
5313 NAMELINK_SKIP
5315 Similar to NAMELINK_ONLY, but it has the opposite effect: it
5316 causes the installation of library files other than the namelink
5317 when a library target is installed. When neither NAMELINK_ONLY
5318 or NAMELINK_SKIP are given, both portions are installed. On
5319 platforms where versioned shared libraries do not have symlinks
5320 or when a library is not versioned, NAMELINK_SKIP installs the
5321 library. It is an error to use this parameter outside of a
5322 LIBRARY block.
5323 If NAMELINK_SKIP is specified, NAMELINK_COMPONENT has no effect.
5325 It is not recommended to use NAMELINK_SKIP in conjunction with
5326 NAMELINK_COMPONENT.
5327 The install(TARGETS) command can also accept the following options at
5329 the top level:
5330 EXPORT This option associates the installed target files with an export
5332 called <export-name>. It must appear before any target options.
5333 To actually install the export file itself, call
5334 install(EXPORT), documented below.
5335 INCLUDES DESTINATION
5337 This option specifies a list of directories which will be added
5338 to the INTERFACE_INCLUDE_DIRECTORIES target property of the
5339 <targets> when exported by the install(EXPORT) command. If a
5340 relative path is specified, it is treated as relative to the
5341 $<INSTALL_PREFIX>.
5342 One or more groups of properties may be specified in a single call to
5344 the TARGETS form of this command. A target may be installed more than
5345 once to different locations. Consider hypothetical targets myExe,
5346 mySharedLib, and myStaticLib. The code:
5347 install(TARGETS myExe mySharedLib myStaticLib
5349 RUNTIME DESTINATION bin
5350 LIBRARY DESTINATION lib
5351 ARCHIVE DESTINATION lib/static)
5352 install(TARGETS mySharedLib DESTINATION /some/full/path)
5353 will install myExe to <prefix>/bin and myStaticLib to <pre‐
5355 fix>/lib/static. On non-DLL platforms mySharedLib will be installed to
5356 <prefix>/lib and /some/full/path. On DLL platforms the mySharedLib DLL
5357 will be installed to <prefix>/bin and /some/full/path and its import
5358 library will be installed to <prefix>/lib/static and /some/full/path.
5359 Interface Libraries may be listed among the targets to install. They
5361 install no artifacts but will be included in an associated EXPORT. If
5362 Object Libraries are listed but given no destination for their object
5363 files, they will be exported as Interface Libraries. This is suffi‐
5364 cient to satisfy transitive usage requirements of other targets that
5365 link to the object libraries in their implementation.
5366 Installing a target with the EXCLUDE_FROM_ALL target property set to
5368 TRUE has undefined behavior.
5369 install(TARGETS) can install targets that were created in other direc‐
5371 tories. When using such cross-directory install rules, running make
5372 install (or similar) from a subdirectory will not guarantee that tar‐
5373 gets from other directories are up-to-date. You can use tar‐
5374 get_link_libraries() or add_dependencies() to ensure that such
5375 out-of-directory targets are built before the subdirectory-specific
5376 install rules are run.
5377 An install destination given as a DESTINATION argument may use “genera‐
5379 tor expressions” with the syntax $<...>. See the cmake-genera‐
5380 tor-expressions(7) manual for available expressions.
5381 Installing Files
5383 install(<FILES|PROGRAMS> files...
5384 TYPE <type> | DESTINATION <dir>
5385 [PERMISSIONS permissions...]
5386 [CONFIGURATIONS [Debug|Release|...]]
5387 [COMPONENT <component>]
5388 [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
5389 The FILES form specifies rules for installing files for a project.
5391 File names given as relative paths are interpreted with respect to the
5392 current source directory. Files installed by this form are by default
5393 given permissions OWNER_WRITE, OWNER_READ, GROUP_READ, and WORLD_READ
5394 if no PERMISSIONS argument is given.
5395 The PROGRAMS form is identical to the FILES form except that the
5397 default permissions for the installed file also include OWNER_EXECUTE,
5398 GROUP_EXECUTE, and WORLD_EXECUTE. This form is intended to install
5399 programs that are not targets, such as shell scripts. Use the TARGETS
5400 form to install targets built within the project.
5401 The list of files... given to FILES or PROGRAMS may use “generator
5403 expressions” with the syntax $<...>. See the cmake-generator-expres‐
5404 sions(7) manual for available expressions. However, if any item begins
5405 in a generator expression it must evaluate to a full path.
5406 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
5408 argument specifies the generic file type of the files being installed.
5409 A destination will then be set automatically by taking the correspond‐
5410 ing variable from GNUInstallDirs, or by using a built-in default if
5411 that variable is not defined. See the table below for the supported
5412 file types and their corresponding variables and built-in defaults.
5413 Projects can provide a DESTINATION argument instead of a file type if
5414 they wish to explicitly define the install destination.
5415 ┌──────────────┬─────────────────────────────┬─────────────────────┐
5417 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
5418 │ │ Variable │ │
5419 ├──────────────┼─────────────────────────────┼─────────────────────┤
5420 │BIN │ ${CMAKE_INSTALL_BINDIR} │ bin │
5421 ├──────────────┼─────────────────────────────┼─────────────────────┤
5422 │SBIN │ ${CMAKE_INSTALL_SBINDIR} │ sbin │
5423 ├──────────────┼─────────────────────────────┼─────────────────────┤
5424 │LIB │ ${CMAKE_INSTALL_LIBDIR} │ lib │
5425 ├──────────────┼─────────────────────────────┼─────────────────────┤
5426 │INCLUDE │ ${CMAKE_INSTALL_INCLUDEDIR} │ include │
5427 ├──────────────┼─────────────────────────────┼─────────────────────┤
5428 │SYSCONF │ ${CMAKE_INSTALL_SYSCONFDIR} │ etc │
5429 ├──────────────┼─────────────────────────────┼─────────────────────┤
5430 │SHAREDSTATE │ ${CMAKE_INSTALL_SHARESTATE‐ │ com │
5431 │ │ DIR} │ │
5432 ├──────────────┼─────────────────────────────┼─────────────────────┤
5433 │LOCALSTATE │ ${CMAKE_INSTALL_LOCALSTATE‐ │ var │
5434 │ │ DIR} │ │
5435 ├──────────────┼─────────────────────────────┼─────────────────────┤
5436 │RUNSTATE │ ${CMAKE_INSTALL_RUNSTATE‐ │ <LOCALSTATE │
5437 │ │ DIR} │ dir>/run │
5438 ├──────────────┼─────────────────────────────┼─────────────────────┤
5439 │DATA │ ${CMAKE_INSTALL_DATADIR} │ <DATAROOT dir> │
5440 ├──────────────┼─────────────────────────────┼─────────────────────┤
5441 │INFO │ ${CMAKE_INSTALL_INFODIR} │ <DATAROOT dir>/info │
5442 ├──────────────┼─────────────────────────────┼─────────────────────┤
5443 │LOCALE │ ${CMAKE_INSTALL_LOCALEDIR} │ <DATAROOT │
5444 │ │ │ dir>/locale │
5445 ├──────────────┼─────────────────────────────┼─────────────────────┤
5446 │MAN │ ${CMAKE_INSTALL_MANDIR} │ <DATAROOT dir>/man │
5447 ├──────────────┼─────────────────────────────┼─────────────────────┤
5448 │DOC │ ${CMAKE_INSTALL_DOCDIR} │ <DATAROOT dir>/doc │
5449 └──────────────┴─────────────────────────────┴─────────────────────┘
5450 Projects wishing to follow the common practice of installing headers
5452 into a project-specific subdirectory will need to provide a destination
5453 rather than rely on the above.
5454 Note that some of the types’ built-in defaults use the DATAROOT direc‐
5456 tory as a prefix. The DATAROOT prefix is calculated similarly to the
5457 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
5458 built-in default. You cannot use DATAROOT as a TYPE parameter; please
5459 use DATA instead.
5460 To make packages compliant with distribution filesystem layout poli‐
5462 cies, if projects must specify a DESTINATION, it is recommended that
5463 they use a path that begins with the appropriate GNUInstallDirs vari‐
5464 able. This allows package maintainers to control the install destina‐
5465 tion by setting the appropriate cache variables. The following example
5466 shows how to follow this advice while installing headers to a
5467 project-specific subdirectory:
5468 include(GNUInstallDirs)
5470 install(FILES mylib.h
5471 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
5472 )
5473 An install destination given as a DESTINATION argument may use “genera‐
5475 tor expressions” with the syntax $<...>. See the cmake-genera‐
5476 tor-expressions(7) manual for available expressions.
5477 Installing Directories
5479 install(DIRECTORY dirs...
5480 TYPE <type> | DESTINATION <dir>
5481 [FILE_PERMISSIONS permissions...]
5482 [DIRECTORY_PERMISSIONS permissions...]
5483 [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
5484 [CONFIGURATIONS [Debug|Release|...]]
5485 [COMPONENT <component>] [EXCLUDE_FROM_ALL]
5486 [FILES_MATCHING]
5487 [[PATTERN <pattern> | REGEX <regex>]
5488 [EXCLUDE] [PERMISSIONS permissions...]] [...])
5489 The DIRECTORY form installs contents of one or more directories to a
5491 given destination. The directory structure is copied verbatim to the
5492 destination. The last component of each directory name is appended to
5493 the destination directory but a trailing slash may be used to avoid
5494 this because it leaves the last component empty. Directory names given
5495 as relative paths are interpreted with respect to the current source
5496 directory. If no input directory names are given the destination
5497 directory will be created but nothing will be installed into it. The
5498 FILE_PERMISSIONS and DIRECTORY_PERMISSIONS options specify permissions
5499 given to files and directories in the destination. If USE_SOURCE_PER‐
5500 MISSIONS is specified and FILE_PERMISSIONS is not, file permissions
5501 will be copied from the source directory structure. If no permissions
5502 are specified files will be given the default permissions specified in
5503 the FILES form of the command, and the directories will be given the
5504 default permissions specified in the PROGRAMS form of the command.
5505 The MESSAGE_NEVER option disables file installation status output.
5507 Installation of directories may be controlled with fine granularity
5509 using the PATTERN or REGEX options. These “match” options specify a
5510 globbing pattern or regular expression to match directories or files
5511 encountered within input directories. They may be used to apply cer‐
5512 tain options (see below) to a subset of the files and directories
5513 encountered. The full path to each input file or directory (with for‐
5514 ward slashes) is matched against the expression. A PATTERN will match
5515 only complete file names: the portion of the full path matching the
5516 pattern must occur at the end of the file name and be preceded by a
5517 slash. A REGEX will match any portion of the full path but it may use
5518 / and $ to simulate the PATTERN behavior. By default all files and
5519 directories are installed whether or not they are matched. The
5520 FILES_MATCHING option may be given before the first match option to
5521 disable installation of files (but not directories) not matched by any
5522 expression. For example, the code
5523 install(DIRECTORY src/ DESTINATION include/myproj
5525 FILES_MATCHING PATTERN "*.h")
5526 will extract and install header files from a source tree.
5528 Some options may follow a PATTERN or REGEX expression and are applied
5530 only to files or directories matching them. The EXCLUDE option will
5531 skip the matched file or directory. The PERMISSIONS option overrides
5532 the permissions setting for the matched file or directory. For example
5533 the code
5534 install(DIRECTORY icons scripts/ DESTINATION share/myproj
5536 PATTERN "CVS" EXCLUDE
5537 PATTERN "scripts/*"
5538 PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
5539 GROUP_EXECUTE GROUP_READ)
5540 will install the icons directory to share/myproj/icons and the scripts
5542 directory to share/myproj. The icons will get default file permis‐
5543 sions, the scripts will be given specific permissions, and any CVS
5544 directories will be excluded.
5545 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
5547 argument specifies the generic file type of the files within the listed
5548 directories being installed. A destination will then be set automati‐
5549 cally by taking the corresponding variable from GNUInstallDirs, or by
5550 using a built-in default if that variable is not defined. See the ta‐
5551 ble below for the supported file types and their corresponding vari‐
5552 ables and built-in defaults. Projects can provide a DESTINATION argu‐
5553 ment instead of a file type if they wish to explicitly define the
5554 install destination.
5555 ┌──────────────┬─────────────────────────────┬─────────────────────┐
5557 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
5558 │ │ Variable │ │
5559 ├──────────────┼─────────────────────────────┼─────────────────────┤
5560 │BIN │ ${CMAKE_INSTALL_BINDIR} │ bin │
5561 ├──────────────┼─────────────────────────────┼─────────────────────┤
5562 │SBIN │ ${CMAKE_INSTALL_SBINDIR} │ sbin │
5563 ├──────────────┼─────────────────────────────┼─────────────────────┤
5564 │LIB │ ${CMAKE_INSTALL_LIBDIR} │ lib │
5565 ├──────────────┼─────────────────────────────┼─────────────────────┤
5566 │INCLUDE │ ${CMAKE_INSTALL_INCLUDEDIR} │ include │
5567 ├──────────────┼─────────────────────────────┼─────────────────────┤
5568 │SYSCONF │ ${CMAKE_INSTALL_SYSCONFDIR} │ etc │
5569 ├──────────────┼─────────────────────────────┼─────────────────────┤
5570 │SHAREDSTATE │ ${CMAKE_INSTALL_SHARESTATE‐ │ com │
5571 │ │ DIR} │ │
5572 ├──────────────┼─────────────────────────────┼─────────────────────┤
5573 │LOCALSTATE │ ${CMAKE_INSTALL_LOCALSTATE‐ │ var │
5574 │ │ DIR} │ │
5575 ├──────────────┼─────────────────────────────┼─────────────────────┤
5576 │RUNSTATE │ ${CMAKE_INSTALL_RUNSTATE‐ │ <LOCALSTATE │
5577 │ │ DIR} │ dir>/run │
5578 ├──────────────┼─────────────────────────────┼─────────────────────┤
5579 │DATA │ ${CMAKE_INSTALL_DATADIR} │ <DATAROOT dir> │
5580 ├──────────────┼─────────────────────────────┼─────────────────────┤
5581 │INFO │ ${CMAKE_INSTALL_INFODIR} │ <DATAROOT dir>/info │
5582 ├──────────────┼─────────────────────────────┼─────────────────────┤
5583 │LOCALE │ ${CMAKE_INSTALL_LOCALEDIR} │ <DATAROOT │
5584 │ │ │ dir>/locale │
5585 ├──────────────┼─────────────────────────────┼─────────────────────┤
5586 │MAN │ ${CMAKE_INSTALL_MANDIR} │ <DATAROOT dir>/man │
5587 ├──────────────┼─────────────────────────────┼─────────────────────┤
5588 │DOC │ ${CMAKE_INSTALL_DOCDIR} │ <DATAROOT dir>/doc │
5589 └──────────────┴─────────────────────────────┴─────────────────────┘
5590 Note that some of the types’ built-in defaults use the DATAROOT direc‐
5592 tory as a prefix. The DATAROOT prefix is calculated similarly to the
5593 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
5594 built-in default. You cannot use DATAROOT as a TYPE parameter; please
5595 use DATA instead.
5596 To make packages compliant with distribution filesystem layout poli‐
5598 cies, if projects must specify a DESTINATION, it is recommended that
5599 they use a path that begins with the appropriate GNUInstallDirs vari‐
5600 able. This allows package maintainers to control the install destina‐
5601 tion by setting the appropriate cache variables.
5602 The list of dirs... given to DIRECTORY and an install destination given
5604 as a DESTINATION argument may use “generator expressions” with the syn‐
5605 tax $<...>. See the cmake-generator-expressions(7) manual for avail‐
5606 able expressions.
5607 Custom Installation Logic
5609 install([[SCRIPT <file>] [CODE <code>]]
5610 [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])
5611 The SCRIPT form will invoke the given CMake script files during instal‐
5613 lation. If the script file name is a relative path it will be inter‐
5614 preted with respect to the current source directory. The CODE form
5615 will invoke the given CMake code during installation. Code is speci‐
5616 fied as a single argument inside a double-quoted string. For example,
5617 the code
5618 install(CODE "MESSAGE(\"Sample install message.\")")
5620 will print a message during installation.
5622 <file> or <code> may use “generator expressions” with the syntax $<...>
5624 (in the case of <file>, this refers to their use in the file name, not
5625 the file’s contents). See the cmake-generator-expressions(7) manual
5626 for available expressions.
5627 Installing Exports
5629 install(EXPORT <export-name> DESTINATION <dir>
5630 [NAMESPACE <namespace>] [[FILE <name>.cmake]|
5631 [PERMISSIONS permissions...]
5632 [CONFIGURATIONS [Debug|Release|...]]
5633 [EXPORT_LINK_INTERFACE_LIBRARIES]
5634 [COMPONENT <component>]
5635 [EXCLUDE_FROM_ALL])
5636 install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])
5637 The EXPORT form generates and installs a CMake file containing code to
5639 import targets from the installation tree into another project. Target
5640 installations are associated with the export <export-name> using the
5641 EXPORT option of the install(TARGETS) signature documented above. The
5642 NAMESPACE option will prepend <namespace> to the target names as they
5643 are written to the import file. By default the generated file will be
5644 called <export-name>.cmake but the FILE option may be used to specify a
5645 different name. The value given to the FILE option must be a file name
5646 with the .cmake extension. If a CONFIGURATIONS option is given then
5647 the file will only be installed when one of the named configurations is
5648 installed. Additionally, the generated import file will reference only
5649 the matching target configurations. The EXPORT_LINK_INTER‐
5650 FACE_LIBRARIES keyword, if present, causes the contents of the proper‐
5651 ties matching (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be
5652 exported, when policy CMP0022 is NEW.
5653 When a COMPONENT option is given, the listed <component> implicitly
5655 depends on all components mentioned in the export set. The exported
5656 <name>.cmake file will require each of the exported components to be
5657 present in order for dependent projects to build properly. For example,
5658 a project may define components Runtime and Development, with shared
5659 libraries going into the Runtime component and static libraries and
5660 headers going into the Development component. The export set would also
5661 typically be part of the Development component, but it would export
5662 targets from both the Runtime and Development components. Therefore,
5663 the Runtime component would need to be installed if the Development
5664 component was installed, but not vice versa. If the Development compo‐
5665 nent was installed without the Runtime component, dependent projects
5666 that try to link against it would have build errors. Package managers,
5667 such as APT and RPM, typically handle this by listing the Runtime com‐
5668 ponent as a dependency of the Development component in the package
5669 metadata, ensuring that the library is always installed if the headers
5670 and CMake export file are present.
5671 In addition to cmake language files, the EXPORT_ANDROID_MK mode maybe
5673 used to specify an export to the android ndk build system. This mode
5674 accepts the same options as the normal export mode. The Android NDK
5675 supports the use of prebuilt libraries, both static and shared. This
5676 allows cmake to build the libraries of a project and make them avail‐
5677 able to an ndk build system complete with transitive dependencies,
5678 include flags and defines required to use the libraries.
5679 The EXPORT form is useful to help outside projects use targets built
5681 and installed by the current project. For example, the code
5682 install(TARGETS myexe EXPORT myproj DESTINATION bin)
5684 install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
5685 install(EXPORT_ANDROID_MK myexp DESTINATION share/ndk-modules)
5686 will install the executable myexe to <prefix>/bin and code to import it
5688 in the file <prefix>/lib/myproj/myproj.cmake and <pre‐
5689 fix>/share/ndk-modules/Android.mk. An outside project may load this
5690 file with the include command and reference the myexe executable from
5691 the installation tree using the imported target name mp_myexe as if the
5692 target were built in its own tree.
5693 NOTE:
5695 This command supercedes the install_targets() command and the
5696 PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT target properties. It
5697 also replaces the FILES forms of the install_files() and
5698 install_programs() commands. The processing order of these install
5699 rules relative to those generated by install_targets(),
5700 install_files(), and install_programs() commands is not defined.
5701 Generated Installation Script
5703 The install() command generates a file, cmake_install.cmake, inside the
5704 build directory, which is used internally by the generated install tar‐
5705 get and by CPack. You can also invoke this script manually with cmake
5706 -P. This script accepts several variables:
5707 COMPONENT
5709 Set this variable to install only a single CPack component as
5710 opposed to all of them. For example, if you only want to install
5711 the Development component, run cmake -DCOMPONENT=Development -P
5712 cmake_install.cmake.
5713 BUILD_TYPE
5715 Set this variable to change the build type if you are using a
5716 multi-config generator. For example, to install with the Debug
5717 configuration, run cmake -DBUILD_TYPE=Debug -P
5718 cmake_install.cmake.
5719 DESTDIR
5721 This is an environment variable rather than a CMake variable. It
5722 allows you to change the installation prefix on UNIX systems.
5723 See DESTDIR for details.
5724 link_directories
5726 Add directories in which the linker will look for libraries.
5727 link_directories([AFTER|BEFORE] directory1 [directory2 ...])
5729 Adds the paths in which the linker should search for libraries. Rela‐
5731 tive paths given to this command are interpreted as relative to the
5732 current source directory, see CMP0015.
5733 The directories are added to the LINK_DIRECTORIES directory property
5735 for the current CMakeLists.txt file, converting relative paths to abso‐
5736 lute as needed. The command will apply only to targets created after
5737 it is called.
5738 By default the directories specified are appended onto the current list
5740 of directories. This default behavior can be changed by setting
5741 CMAKE_LINK_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE explic‐
5742 itly, you can select between appending and prepending, independent of
5743 the default.
5744 Arguments to link_directories may use “generator expressions” with the
5746 syntax “$<…>”. See the cmake-generator-expressions(7) manual for
5747 available expressions. See the cmake-buildsystem(7) manual for more on
5748 defining buildsystem properties.
5749 NOTE:
5751 This command is rarely necessary and should be avoided where there
5752 are other choices. Prefer to pass full absolute paths to libraries
5753 where possible, since this ensures the correct library will always
5754 be linked. The find_library() command provides the full path, which
5755 can generally be used directly in calls to target_link_libraries().
5756 Situations where a library search path may be needed include:
5757 · Project generators like Xcode where the user can switch target
5759 architecture at build time, but a full path to a library cannot be
5760 used because it only provides one architecture (i.e. it is not a
5761 universal binary).
5762 · Libraries may themselves have other private library dependencies
5764 that expect to be found via RPATH mechanisms, but some linkers are
5765 not able to fully decode those paths (e.g. due to the presence of
5766 things like $ORIGIN).
5767 If a library search path must be provided, prefer to localize the
5769 effect where possible by using the target_link_directories() command
5770 rather than link_directories(). The target-specific command can
5771 also control how the search directories propagate to other dependent
5772 targets.
5773 link_libraries
5775 Link libraries to all targets added later.
5776 link_libraries([item1 [item2 [...]]]
5778 [[debug|optimized|general] <item>] ...)
5779 Specify libraries or flags to use when linking any targets created
5781 later in the current directory or below by commands such as add_exe‐
5782 cutable() or add_library(). See the target_link_libraries() command
5783 for meaning of arguments.
5784 NOTE:
5786 The target_link_libraries() command should be preferred whenever
5787 possible. Library dependencies are chained automatically, so direc‐
5788 tory-wide specification of link libraries is rarely needed.
5789 load_cache
5791 Load in the values from another project’s CMake cache.
5792 load_cache(pathToCacheFile READ_WITH_PREFIX prefix entry1...)
5794 Reads the cache and store the requested entries in variables with their
5796 name prefixed with the given prefix. This only reads the values, and
5797 does not create entries in the local project’s cache.
5798 load_cache(pathToCacheFile [EXCLUDE entry1...]
5800 [INCLUDE_INTERNALS entry1...])
5801 Loads in the values from another cache and store them in the local
5803 project’s cache as internal entries. This is useful for a project that
5804 depends on another project built in a different tree. EXCLUDE option
5805 can be used to provide a list of entries to be excluded.
5806 INCLUDE_INTERNALS can be used to provide a list of internal entries to
5807 be included. Normally, no internal entries are brought in. Use of
5808 this form of the command is strongly discouraged, but it is provided
5809 for backward compatibility.
5810 project
5812 Set the name of the project.
5813 Synopsis
5815 project(<PROJECT-NAME> [<language-name>...])
5816 project(<PROJECT-NAME>
5817 [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
5818 [DESCRIPTION <project-description-string>]
5819 [HOMEPAGE_URL <url-string>]
5820 [LANGUAGES <language-name>...])
5821 Sets the name of the project, and stores it in the variable
5823 PROJECT_NAME. When called from the top-level CMakeLists.txt also stores
5824 the project name in the variable CMAKE_PROJECT_NAME.
5825 Also sets the variables
5827 · PROJECT_SOURCE_DIR, <PROJECT-NAME>_SOURCE_DIR
5829 · PROJECT_BINARY_DIR, <PROJECT-NAME>_BINARY_DIR
5831 Further variables are set by the optional arguments described in the
5833 following. If any of these arguments is not used, then the correspond‐
5834 ing variables are set to the empty string.
5835 If the variable CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE exists, the file
5837 pointed to by that variable will be included as the last step of the
5838 project command.
5839 Options
5841 The options are:
5842 VERSION <version>
5844 Optional; may not be used unless policy CMP0048 is set to NEW.
5845 Takes a <version> argument composed of non-negative integer com‐
5847 ponents, i.e. <major>[.<minor>[.<patch>[.<tweak>]]], and sets
5848 the variables
5849 · PROJECT_VERSION, <PROJECT-NAME>_VERSION
5851 · PROJECT_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MAJOR
5853 · PROJECT_VERSION_MINOR, <PROJECT-NAME>_VERSION_MINOR
5855 · PROJECT_VERSION_PATCH, <PROJECT-NAME>_VERSION_PATCH
5857 · PROJECT_VERSION_TWEAK, <PROJECT-NAME>_VERSION_TWEAK.
5859 When the project() command is called from the top-level CMake‐
5861 Lists.txt, then the version is also stored in the variable
5862 CMAKE_PROJECT_VERSION.
5863 DESCRIPTION <project-description-string>
5865 Optional. Sets the variables
5866 · PROJECT_DESCRIPTION, <PROJECT-NAME>_DESCRIPTION
5868 to <project-description-string>. It is recommended that this
5870 description is a relatively short string, usually no more than a
5871 few words.
5872 When the project() command is called from the top-level CMake‐
5874 Lists.txt, then the description is also stored in the variable
5875 CMAKE_PROJECT_DESCRIPTION.
5876 HOMEPAGE_URL <url-string>
5878 Optional. Sets the variables
5879 · PROJECT_HOMEPAGE_URL, <PROJECT-NAME>_HOMEPAGE_URL
5881 to <url-string>, which should be the canonical home URL for the
5883 project.
5884 When the project() command is called from the top-level CMake‐
5886 Lists.txt, then the URL also is stored in the variable
5887 CMAKE_PROJECT_HOMEPAGE_URL.
5888 LANGUAGES <language-name>...
5890 Optional. Can also be specified without LANGUAGES keyword per
5891 the first, short signature.
5892 Selects which programming languages are needed to build the
5894 project. Supported languages include C, CXX (i.e. C++), CUDA,
5895 Fortran, and ASM. By default C and CXX are enabled if no lan‐
5896 guage options are given. Specify language NONE, or use the LAN‐
5897 GUAGES keyword and list no languages, to skip enabling any lan‐
5898 guages.
5899 If enabling ASM, list it last so that CMake can check whether
5901 compilers for other languages like C work for assembly too.
5902 The variables set through the VERSION, DESCRIPTION and HOMEPAGE_URL
5904 options are intended for use as default values in package metadata and
5905 documentation.
5906 Usage
5908 The top-level CMakeLists.txt file for a project must contain a literal,
5909 direct call to the project() command; loading one through the include()
5910 command is not sufficient. If no such call exists CMake will implic‐
5911 itly add one to the top that enables the default languages (C and CXX).
5912 NOTE:
5914 Call the cmake_minimum_required() command at the beginning of the
5915 top-level CMakeLists.txt file even before calling the project() com‐
5916 mand. It is important to establish version and policy settings
5917 before invoking other commands whose behavior they may affect. See
5918 also policy CMP0000.
5919 remove_definitions
5921 Remove -D define flags added by add_definitions().
5922 remove_definitions(-DFOO -DBAR ...)
5924 Removes flags (added by add_definitions()) from the compiler command
5926 line for sources in the current directory and below.
5927 set_source_files_properties
5929 Source files can have properties that affect how they are built.
5930 set_source_files_properties([file1 [file2 [...]]]
5932 PROPERTIES prop1 value1
5933 [prop2 value2 [...]])
5934 Sets properties associated with source files using a key/value paired
5936 list.
5937 See also the set_property(SOURCE) command.
5939 See Source File Properties for the list of properties known to CMake.
5941 Source file properties are visible only to targets added in the same
5942 directory (CMakeLists.txt).
5943 set_target_properties
5945 Targets can have properties that affect how they are built.
5946 set_target_properties(target1 target2 ...
5948 PROPERTIES prop1 value1
5949 prop2 value2 ...)
5950 Sets properties on targets. The syntax for the command is to list all
5952 the targets you want to change, and then provide the values you want to
5953 set next. You can use any prop value pair you want and extract it
5954 later with the get_property() or get_target_property() command.
5955 See also the set_property(TARGET) command.
5957 See Target Properties for the list of properties known to CMake.
5959 set_tests_properties
5961 Set a property of the tests.
5962 set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
5964 Sets a property for the tests. If the test is not found, CMake will
5966 report an error. Generator expressions will be expanded the same as
5967 supported by the test’s add_test() call.
5968 See also the set_property(TEST) command.
5970 See Test Properties for the list of properties known to CMake.
5972 source_group
5974 Define a grouping for source files in IDE project generation. There
5975 are two different signatures to create source groups.
5976 source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
5978 source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...])
5979 Defines a group into which sources will be placed in project files.
5981 This is intended to set up file tabs in Visual Studio. The options
5982 are:
5983 TREE CMake will automatically detect, from <src> files paths, source
5985 groups it needs to create, to keep structure of source groups
5986 analogically to the actual files and directories structure in
5987 the project. Paths of <src> files will be cut to be relative to
5988 <root>.
5989 PREFIX Source group and files located directly in <root> path, will be
5991 placed in <prefix> source groups.
5992 FILES Any source file specified explicitly will be placed in group
5994 <name>. Relative paths are interpreted with respect to the cur‐
5995 rent source directory.
5996 REGULAR_EXPRESSION
5998 Any source file whose name matches the regular expression will
5999 be placed in group <name>.
6000 If a source file matches multiple groups, the last group that explic‐
6002 itly lists the file with FILES will be favored, if any. If no group
6003 explicitly lists the file, the last group whose regular expression
6004 matches the file will be favored.
6005 The <name> of the group and <prefix> argument may contain backslashes
6007 to specify subgroups:
6008 source_group(outer\\inner ...)
6010 source_group(TREE <root> PREFIX sources\\inc ...)
6011 For backwards compatibility, the short-hand signature
6013 source_group(<name> <regex>)
6015 is equivalent to
6017 source_group(<name> REGULAR_EXPRESSION <regex>)
6019 target_compile_definitions
6021 Add compile definitions to a target.
6022 target_compile_definitions(<target>
6024 <INTERFACE|PUBLIC|PRIVATE> [items1...]
6025 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6026 Specifies compile definitions to use when compiling a given <target>.
6028 The named <target> must have been created by a command such as add_exe‐
6029 cutable() or add_library() and must not be an ALIAS target.
6030 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6032 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
6033 late the COMPILE_DEFINITIONS property of <target>. PUBLIC and INTERFACE
6034 items will populate the INTERFACE_COMPILE_DEFINITIONS property of <tar‐
6035 get>. (IMPORTED targets only support INTERFACE items.) The following
6036 arguments specify compile definitions. Repeated calls for the same
6037 <target> append items in the order called.
6038 Arguments to target_compile_definitions may use “generator expressions”
6040 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6041 for available expressions. See the cmake-buildsystem(7) manual for
6042 more on defining buildsystem properties.
6043 Any leading -D on an item will be removed. Empty items are ignored.
6045 For example, the following are all equivalent:
6046 target_compile_definitions(foo PUBLIC FOO)
6048 target_compile_definitions(foo PUBLIC -DFOO) # -D removed
6049 target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
6050 target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
6051 target_compile_features
6053 Add expected compiler features to a target.
6054 target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
6056 Specifies compiler features required when compiling a given target. If
6058 the feature is not listed in the CMAKE_C_COMPILE_FEATURES variable or
6059 CMAKE_CXX_COMPILE_FEATURES variable, then an error will be reported by
6060 CMake. If the use of the feature requires an additional compiler flag,
6061 such as -std=gnu++11, the flag will be added automatically.
6062 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6064 scope of the features. PRIVATE and PUBLIC items will populate the COM‐
6065 PILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
6066 populate the INTERFACE_COMPILE_FEATURES property of <target>.
6067 (IMPORTED targets only support INTERFACE items.) Repeated calls for
6068 the same <target> append items.
6069 The named <target> must have been created by a command such as add_exe‐
6071 cutable() or add_library() and must not be an ALIAS target.
6072 Arguments to target_compile_features may use “generator expressions”
6074 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6075 for available expressions. See the cmake-compile-features(7) manual
6076 for information on compile features and a list of supported compilers.
6077 target_compile_options
6079 Add compile options to a target.
6080 target_compile_options(<target> [BEFORE]
6082 <INTERFACE|PUBLIC|PRIVATE> [items1...]
6083 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6084 Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
6086 properties. These options are used when compiling the given <target>,
6087 which must have been created by a command such as add_executable() or
6088 add_library() and must not be an ALIAS target.
6089 Arguments
6091 If BEFORE is specified, the content will be prepended to the property
6092 instead of being appended.
6093 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6095 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
6096 late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
6097 items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
6098 (IMPORTED targets only support INTERFACE items.) The following argu‐
6099 ments specify compile options. Repeated calls for the same <target>
6100 append items in the order called.
6101 Arguments to target_compile_options may use “generator expressions”
6103 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6104 for available expressions. See the cmake-buildsystem(7) manual for
6105 more on defining buildsystem properties.
6106 The final set of compile or link options used for a target is con‐
6108 structed by accumulating options from the current target and the usage
6109 requirements of it dependencies. The set of options is de-duplicated
6110 to avoid repetition. While beneficial for individual options, the
6111 de-duplication step can break up option groups. For example, -D A -D B
6112 becomes -D A B. One may specify a group of options using shell-like
6113 quoting along with a SHELL: prefix. The SHELL: prefix is dropped and
6114 the rest of the option string is parsed using the separate_arguments()
6115 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
6116 -D B.
6117 See Also
6119 This command can be used to add any options. However, for adding pre‐
6120 processor definitions and include directories it is recommended to use
6121 the more specific commands target_compile_definitions() and tar‐
6122 get_include_directories().
6123 For directory-wide settings, there is the command add_com‐
6125 pile_options().
6126 target_include_directories
6128 Add include directories to a target.
6129 target_include_directories(<target> [SYSTEM] [BEFORE]
6131 <INTERFACE|PUBLIC|PRIVATE> [items1...]
6132 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6133 Specifies include directories to use when compiling a given target.
6135 The named <target> must have been created by a command such as add_exe‐
6136 cutable() or add_library() and must not be an ALIAS target.
6137 If BEFORE is specified, the content will be prepended to the property
6139 instead of being appended.
6140 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6142 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
6143 late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTER‐
6144 FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
6145 <target>. (IMPORTED targets only support INTERFACE items.) The fol‐
6146 lowing arguments specify include directories.
6147 Specified include directories may be absolute paths or relative paths.
6149 Repeated calls for the same <target> append items in the order called.
6150 If SYSTEM is specified, the compiler will be told the directories are
6151 meant as system include directories on some platforms (signalling this
6152 setting might achieve effects such as the compiler skipping warnings,
6153 or these fixed-install system files not being considered in dependency
6154 calculations - see compiler docs). If SYSTEM is used together with
6155 PUBLIC or INTERFACE, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
6156 property will be populated with the specified directories.
6157 Arguments to target_include_directories may use “generator expressions”
6159 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6160 for available expressions. See the cmake-buildsystem(7) manual for
6161 more on defining buildsystem properties.
6162 Include directories usage requirements commonly differ between the
6164 build-tree and the install-tree. The BUILD_INTERFACE and
6165 INSTALL_INTERFACE generator expressions can be used to describe sepa‐
6166 rate usage requirements based on the usage location. Relative paths
6167 are allowed within the INSTALL_INTERFACE expression and are interpreted
6168 relative to the installation prefix. For example:
6169 target_include_directories(mylib PUBLIC
6171 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
6172 $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
6173 )
6174 Creating Relocatable Packages
6176 Note that it is not advisable to populate the INSTALL_INTERFACE of the
6177 INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
6178 include directories of dependencies. That would hard-code into
6179 installed packages the include directory paths for dependencies as
6180 found on the machine the package was made on.
6181 The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
6183 suitable for specifying the required include directories for headers
6184 provided with the target itself, not those provided by the transitive
6185 dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
6186 Those dependencies should themselves be targets that specify their own
6187 header locations in INTERFACE_INCLUDE_DIRECTORIES.
6188 See the Creating Relocatable Packages section of the cmake-packages(7)
6190 manual for discussion of additional care that must be taken when speci‐
6191 fying usage requirements while creating packages for redistribution.
6192 target_link_directories
6194 Add link directories to a target.
6195 target_link_directories(<target> [BEFORE]
6197 <INTERFACE|PUBLIC|PRIVATE> [items1...]
6198 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6199 Specifies the paths in which the linker should search for libraries
6201 when linking a given target. Each item can be an absolute or relative
6202 path, with the latter being interpreted as relative to the current
6203 source directory. These items will be added to the link command.
6204 The named <target> must have been created by a command such as add_exe‐
6206 cutable() or add_library() and must not be an ALIAS target.
6207 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6209 scope of the items that follow them. PRIVATE and PUBLIC items will
6210 populate the LINK_DIRECTORIES property of <target>. PUBLIC and INTER‐
6211 FACE items will populate the INTERFACE_LINK_DIRECTORIES property of
6212 <target> (IMPORTED targets only support INTERFACE items). Each item
6213 specifies a link directory and will be converted to an absolute path if
6214 necessary before adding it to the relevant property. Repeated calls
6215 for the same <target> append items in the order called.
6216 If BEFORE is specified, the content will be prepended to the relevant
6218 property instead of being appended.
6219 Arguments to target_link_directories may use “generator expressions”
6221 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6222 for available expressions. See the cmake-buildsystem(7) manual for
6223 more on defining buildsystem properties.
6224 NOTE:
6226 This command is rarely necessary and should be avoided where there
6227 are other choices. Prefer to pass full absolute paths to libraries
6228 where possible, since this ensures the correct library will always
6229 be linked. The find_library() command provides the full path, which
6230 can generally be used directly in calls to target_link_libraries().
6231 Situations where a library search path may be needed include:
6232 · Project generators like Xcode where the user can switch target
6234 architecture at build time, but a full path to a library cannot be
6235 used because it only provides one architecture (i.e. it is not a
6236 universal binary).
6237 · Libraries may themselves have other private library dependencies
6239 that expect to be found via RPATH mechanisms, but some linkers are
6240 not able to fully decode those paths (e.g. due to the presence of
6241 things like $ORIGIN).
6242 target_link_libraries
6244 Specify libraries or flags to use when linking a given target and/or
6245 its dependents. Usage requirements from linked library targets will be
6246 propagated. Usage requirements of a target’s dependencies affect com‐
6247 pilation of its own sources.
6248 Overview
6250 This command has several signatures as detailed in subsections below.
6251 All of them have the general form
6252 target_link_libraries(<target> ... <item>... ...)
6254 The named <target> must have been created by a command such as add_exe‐
6256 cutable() or add_library() and must not be an ALIAS target. If policy
6257 CMP0079 is not set to NEW then the target must have been created in the
6258 current directory. Repeated calls for the same <target> append items
6259 in the order called.
6260 Each <item> may be:
6262 · A library target name: The generated link line will have the full
6264 path to the linkable library file associated with the target. The
6265 buildsystem will have a dependency to re-link <target> if the library
6266 file changes.
6267 The named target must be created by add_library() within the project
6269 or as an IMPORTED library. If it is created within the project an
6270 ordering dependency will automatically be added in the build system
6271 to make sure the named library target is up-to-date before the <tar‐
6272 get> links.
6273 If an imported library has the IMPORTED_NO_SONAME target property
6275 set, CMake may ask the linker to search for the library instead of
6276 using the full path (e.g. /usr/lib/libfoo.so becomes -lfoo).
6277 The full path to the target’s artifact will be quoted/escaped for the
6279 shell automatically.
6280 · A full path to a library file: The generated link line will normally
6282 preserve the full path to the file. The buildsystem will have a
6283 dependency to re-link <target> if the library file changes.
6284 There are some cases where CMake may ask the linker to search for the
6286 library (e.g. /usr/lib/libfoo.so becomes -lfoo), such as when a
6287 shared library is detected to have no SONAME field. See policy
6288 CMP0060 for discussion of another case.
6289 If the library file is in a Mac OSX framework, the Headers directory
6291 of the framework will also be processed as a usage requirement. This
6292 has the same effect as passing the framework directory as an include
6293 directory.
6294 On Visual Studio Generators for VS 2010 and above, library files end‐
6296 ing in .targets will be treated as MSBuild targets files and imported
6297 into generated project files. This is not supported by other genera‐
6298 tors.
6299 The full path to the library file will be quoted/escaped for the
6301 shell automatically.
6302 · A plain library name: The generated link line will ask the linker to
6304 search for the library (e.g. foo becomes -lfoo or foo.lib).
6305 The library name/flag is treated as a command-line string fragment
6307 and will be used with no extra quoting or escaping.
6308 · A link flag: Item names starting with -, but not -l or -framework,
6310 are treated as linker flags. Note that such flags will be treated
6311 like any other library link item for purposes of transitive dependen‐
6312 cies, so they are generally safe to specify only as private link
6313 items that will not propagate to dependents.
6314 Link flags specified here are inserted into the link command in the
6316 same place as the link libraries. This might not be correct, depend‐
6317 ing on the linker. Use the LINK_OPTIONS target property or tar‐
6318 get_link_options() command to add link flags explicitly. The flags
6319 will then be placed at the toolchain-defined flag position in the
6320 link command.
6321 The link flag is treated as a command-line string fragment and will
6323 be used with no extra quoting or escaping.
6324 · A generator expression: A $<...> generator expression may evaluate to
6326 any of the above items or to a semicolon-separated list of them. If
6327 the ... contains any ; characters, e.g. after evaluation of a ${list}
6328 variable, be sure to use an explicitly quoted argument "$<...>" so
6329 that this command receives it as a single <item>.
6330 Additionally, a generator expression may be used as a fragment of any
6332 of the above items, e.g. foo$<1:_d>.
6333 Note that generator expressions will not be used in OLD handling of
6335 policy CMP0003 or policy CMP0004.
6336 · A debug, optimized, or general keyword immediately followed by
6338 another <item>. The item following such a keyword will be used only
6339 for the corresponding build configuration. The debug keyword corre‐
6340 sponds to the Debug configuration (or to configurations named in the
6341 DEBUG_CONFIGURATIONS global property if it is set). The optimized
6342 keyword corresponds to all other configurations. The general keyword
6343 corresponds to all configurations, and is purely optional. Higher
6344 granularity may be achieved for per-configuration rules by creating
6345 and linking to IMPORTED library targets. These keywords are inter‐
6346 preted immediately by this command and therefore have no special
6347 meaning when produced by a generator expression.
6348 Items containing ::, such as Foo::Bar, are assumed to be IMPORTED or
6350 ALIAS library target names and will cause an error if no such target
6351 exists. See policy CMP0028.
6352 See the cmake-buildsystem(7) manual for more on defining buildsystem
6354 properties.
6355 Libraries for a Target and/or its Dependents
6357 target_link_libraries(<target>
6358 <PRIVATE|PUBLIC|INTERFACE> <item>...
6359 [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
6360 The PUBLIC, PRIVATE and INTERFACE keywords can be used to specify both
6362 the link dependencies and the link interface in one command. Libraries
6363 and targets following PUBLIC are linked to, and are made part of the
6364 link interface. Libraries and targets following PRIVATE are linked to,
6365 but are not made part of the link interface. Libraries following
6366 INTERFACE are appended to the link interface and are not used for link‐
6367 ing <target>.
6368 Libraries for both a Target and its Dependents
6370 target_link_libraries(<target> <item>...)
6371 Library dependencies are transitive by default with this signature.
6373 When this target is linked into another target then the libraries
6374 linked to this target will appear on the link line for the other target
6375 too. This transitive “link interface” is stored in the INTER‐
6376 FACE_LINK_LIBRARIES target property and may be overridden by setting
6377 the property directly. When CMP0022 is not set to NEW, transitive
6378 linking is built in but may be overridden by the LINK_INTER‐
6379 FACE_LIBRARIES property. Calls to other signatures of this command may
6380 set the property making any libraries linked exclusively by this signa‐
6381 ture private.
6382 Libraries for a Target and/or its Dependents (Legacy)
6384 target_link_libraries(<target>
6385 <LINK_PRIVATE|LINK_PUBLIC> <lib>...
6386 [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
6387 The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both the
6389 link dependencies and the link interface in one command.
6390 This signature is for compatibility only. Prefer the PUBLIC or PRIVATE
6392 keywords instead.
6393 Libraries and targets following LINK_PUBLIC are linked to, and are made
6395 part of the INTERFACE_LINK_LIBRARIES. If policy CMP0022 is not NEW,
6396 they are also made part of the LINK_INTERFACE_LIBRARIES. Libraries and
6397 targets following LINK_PRIVATE are linked to, but are not made part of
6398 the INTERFACE_LINK_LIBRARIES (or LINK_INTERFACE_LIBRARIES).
6399 Libraries for Dependents Only (Legacy)
6401 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
6402 The LINK_INTERFACE_LIBRARIES mode appends the libraries to the INTER‐
6404 FACE_LINK_LIBRARIES target property instead of using them for linking.
6405 If policy CMP0022 is not NEW, then this mode also appends libraries to
6406 the LINK_INTERFACE_LIBRARIES and its per-configuration equivalent.
6407 This signature is for compatibility only. Prefer the INTERFACE mode
6409 instead.
6410 Libraries specified as debug are wrapped in a generator expression to
6412 correspond to debug builds. If policy CMP0022 is not NEW, the
6413 libraries are also appended to the LINK_INTERFACE_LIBRARIES_DEBUG prop‐
6414 erty (or to the properties corresponding to configurations listed in
6415 the DEBUG_CONFIGURATIONS global property if it is set). Libraries
6416 specified as optimized are appended to the INTERFACE_LINK_LIBRARIES
6417 property. If policy CMP0022 is not NEW, they are also appended to the
6418 LINK_INTERFACE_LIBRARIES property. Libraries specified as general (or
6419 without any keyword) are treated as if specified for both debug and
6420 optimized.
6421 Linking Object Libraries
6423 Object Libraries may be used as the <target> (first) argument of tar‐
6424 get_link_libraries to specify dependencies of their sources on other
6425 libraries. For example, the code
6426 add_library(A SHARED a.c)
6428 target_compile_definitions(A PUBLIC A)
6429 add_library(obj OBJECT obj.c)
6431 target_compile_definitions(obj PUBLIC OBJ)
6432 target_link_libraries(obj PUBLIC A)
6433 compiles obj.c with -DA -DOBJ and establishes usage requirements for
6435 obj that propagate to its dependents.
6436 Normal libraries and executables may link to Object Libraries to get
6438 their objects and usage requirements. Continuing the above example,
6439 the code
6440 add_library(B SHARED b.c)
6442 target_link_libraries(B PUBLIC obj)
6443 compiles b.c with -DA -DOBJ, creates shared library B with object files
6445 from b.c and obj.c, and links B to A. Furthermore, the code
6446 add_executable(main main.c)
6448 target_link_libraries(main B)
6449 compiles main.c with -DA -DOBJ and links executable main to B and A.
6451 The object library’s usage requirements are propagated transitively
6452 through B, but its object files are not.
6453 Object Libraries may “link” to other object libraries to get usage
6455 requirements, but since they do not have a link step nothing is done
6456 with their object files. Continuing from the above example, the code:
6457 add_library(obj2 OBJECT obj2.c)
6459 target_link_libraries(obj2 PUBLIC obj)
6460 add_executable(main2 main2.c)
6462 target_link_libraries(main2 obj2)
6463 compiles obj2.c with -DA -DOBJ, creates executable main2 with object
6465 files from main2.c and obj2.c, and links main2 to A.
6466 In other words, when Object Libraries appear in a target’s INTER‐
6468 FACE_LINK_LIBRARIES property they will be treated as Interface
6469 Libraries, but when they appear in a target’s LINK_LIBRARIES property
6470 their object files will be included in the link too.
6471 Cyclic Dependencies of Static Libraries
6473 The library dependency graph is normally acyclic (a DAG), but in the
6474 case of mutually-dependent STATIC libraries CMake allows the graph to
6475 contain cycles (strongly connected components). When another target
6476 links to one of the libraries, CMake repeats the entire connected com‐
6477 ponent. For example, the code
6478 add_library(A STATIC a.c)
6480 add_library(B STATIC b.c)
6481 target_link_libraries(A B)
6482 target_link_libraries(B A)
6483 add_executable(main main.c)
6484 target_link_libraries(main A)
6485 links main to A B A B. While one repetition is usually sufficient,
6487 pathological object file and symbol arrangements can require more. One
6488 may handle such cases by using the LINK_INTERFACE_MULTIPLICITY target
6489 property or by manually repeating the component in the last tar‐
6490 get_link_libraries call. However, if two archives are really so inter‐
6491 dependent they should probably be combined into a single archive, per‐
6492 haps by using Object Libraries.
6493 Creating Relocatable Packages
6495 Note that it is not advisable to populate the INTERFACE_LINK_LIBRARIES
6496 of a target with absolute paths to dependencies. That would hard-code
6497 into installed packages the library file paths for dependencies as
6498 found on the machine the package was made on.
6499 See the Creating Relocatable Packages section of the cmake-packages(7)
6501 manual for discussion of additional care that must be taken when speci‐
6502 fying usage requirements while creating packages for redistribution.
6503 target_link_options
6505 Add link options to a target.
6506 target_link_options(<target> [BEFORE]
6508 <INTERFACE|PUBLIC|PRIVATE> [items1...]
6509 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6510 Specifies link options to use when linking a given target. The named
6512 <target> must have been created by a command such as add_executable()
6513 or add_library() and must not be an ALIAS target.
6514 If BEFORE is specified, the content will be prepended to the property
6516 instead of being appended.
6517 This command can be used to add any options, but alternative commands
6519 exist to add libraries (target_link_libraries() and link_libraries()).
6520 See documentation of the directory and target LINK_OPTIONS properties.
6521 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6523 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
6524 late the LINK_OPTIONS property of <target>. PUBLIC and INTERFACE items
6525 will populate the INTERFACE_LINK_OPTIONS property of <target>.
6526 (IMPORTED targets only support INTERFACE items.) The following argu‐
6527 ments specify link options. Repeated calls for the same <target>
6528 append items in the order called.
6529 Arguments to target_link_options may use “generator expressions” with
6531 the syntax $<...>. See the cmake-generator-expressions(7) manual for
6532 available expressions. See the cmake-buildsystem(7) manual for more on
6533 defining buildsystem properties.
6534 The final set of compile or link options used for a target is con‐
6536 structed by accumulating options from the current target and the usage
6537 requirements of it dependencies. The set of options is de-duplicated
6538 to avoid repetition. While beneficial for individual options, the
6539 de-duplication step can break up option groups. For example, -D A -D B
6540 becomes -D A B. One may specify a group of options using shell-like
6541 quoting along with a SHELL: prefix. The SHELL: prefix is dropped and
6542 the rest of the option string is parsed using the separate_arguments()
6543 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
6544 -D B.
6545 To pass options to the linker tool, each compiler driver has is own
6547 syntax. The LINKER: prefix can be used to specify, in a portable way,
6548 options to pass to the linker tool. The LINKER: prefix is replaced by
6549 the required driver option and the rest of the option string defines
6550 linker arguments using , as separator. These arguments will be format‐
6551 ted according to the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
6552 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
6553 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
6555 Clang and -Wl,-z,defs for GNU GCC.
6556 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
6558 sion.
6559 The LINKER: prefix supports, as alternate syntax, specification of
6561 arguments using SHELL: prefix and space as separator. Previous example
6562 becomes "LINKER:SHELL:-z defs".
6563 NOTE:
6565 Specifying SHELL: prefix elsewhere than at the beginning of the
6566 LINKER: prefix is not supported.
6567 target_sources
6569 Add sources to a target.
6570 target_sources(<target>
6572 <INTERFACE|PUBLIC|PRIVATE> [items1...]
6573 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6574 Specifies sources to use when compiling a given target. Relative
6576 source file paths are interpreted as being relative to the current
6577 source directory (i.e. CMAKE_CURRENT_SOURCE_DIR). The named <target>
6578 must have been created by a command such as add_executable() or
6579 add_library() and must not be an ALIAS target.
6580 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6582 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
6583 late the SOURCES property of <target>. PUBLIC and INTERFACE items will
6584 populate the INTERFACE_SOURCES property of <target>. (IMPORTED targets
6585 only support INTERFACE items.) The following arguments specify
6586 sources. Repeated calls for the same <target> append items in the
6587 order called.
6588 Arguments to target_sources may use “generator expressions” with the
6590 syntax $<...>. See the cmake-generator-expressions(7) manual for avail‐
6591 able expressions. See the cmake-buildsystem(7) manual for more on
6592 defining buildsystem properties.
6593 See also the CMP0076 policy for older behavior related to the handling
6595 of relative source file paths.
6596 try_compile
6598 Try building some code.
6599 Try Compiling Whole Projects
6601 try_compile(<resultVar> <bindir> <srcdir>
6602 <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
6603 [OUTPUT_VARIABLE <var>])
6604 Try building a project. The success or failure of the try_compile,
6606 i.e. TRUE or FALSE respectively, is returned in <resultVar>.
6607 In this form, <srcdir> should contain a complete CMake project with a
6609 CMakeLists.txt file and all sources. The <bindir> and <srcdir> will
6610 not be deleted after this command is run. Specify <targetName> to
6611 build a specific target instead of the all or ALL_BUILD target. See
6612 below for the meaning of other options.
6613 Try Compiling Source Files
6615 try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
6616 [CMAKE_FLAGS <flags>...]
6617 [COMPILE_DEFINITIONS <defs>...]
6618 [LINK_OPTIONS <options>...]
6619 [LINK_LIBRARIES <libs>...]
6620 [OUTPUT_VARIABLE <var>]
6621 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
6622 [<LANG>_STANDARD <std>]
6623 [<LANG>_STANDARD_REQUIRED <bool>]
6624 [<LANG>_EXTENSIONS <bool>]
6625 )
6626 Try building an executable or static library from one or more source
6628 files (which one is determined by the CMAKE_TRY_COMPILE_TARGET_TYPE
6629 variable). The success or failure of the try_compile, i.e. TRUE or
6630 FALSE respectively, is returned in <resultVar>.
6631 In this form, one or more source files must be provided. If
6633 CMAKE_TRY_COMPILE_TARGET_TYPE is unset or is set to EXECUTABLE, the
6634 sources must include a definition for main and CMake will create a
6635 CMakeLists.txt file to build the source(s) as an executable. If
6636 CMAKE_TRY_COMPILE_TARGET_TYPE is set to STATIC_LIBRARY, a static
6637 library will be built instead and no definition for main is required.
6638 For an executable, the generated CMakeLists.txt file would contain
6639 something like the following:
6640 add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
6642 include_directories(${INCLUDE_DIRECTORIES})
6643 link_directories(${LINK_DIRECTORIES})
6644 add_executable(cmTryCompileExec <srcfile>...)
6645 target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
6646 target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
6647 The options are:
6649 CMAKE_FLAGS <flags>...
6651 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
6652 cmake command-line used to drive the test build. The above
6653 example shows how values for variables INCLUDE_DIRECTORIES,
6654 LINK_DIRECTORIES, and LINK_LIBRARIES are used.
6655 COMPILE_DEFINITIONS <defs>...
6657 Specify -Ddefinition arguments to pass to add_definitions() in
6658 the generated test project.
6659 COPY_FILE <fileName>
6661 Copy the built executable or static library to the given <file‐
6662 Name>.
6663 COPY_FILE_ERROR <var>
6665 Use after COPY_FILE to capture into variable <var> any error
6666 message encountered while trying to copy the file.
6667 LINK_LIBRARIES <libs>...
6669 Specify libraries to be linked in the generated project. The
6670 list of libraries may refer to system libraries and to Imported
6671 Targets from the calling project.
6672 If this option is specified, any -DLINK_LIBRARIES=... value
6674 given to the CMAKE_FLAGS option will be ignored.
6675 LINK_OPTIONS <options>...
6677 Specify link step options to pass to target_link_options() or to
6678 set the STATIC_LIBRARY_OPTIONS target property in the generated
6679 project, depending on the CMAKE_TRY_COMPILE_TARGET_TYPE vari‐
6680 able.
6681 OUTPUT_VARIABLE <var>
6683 Store the output from the build process in the given variable.
6684 <LANG>_STANDARD <std>
6686 Specify the C_STANDARD, CXX_STANDARD, or CUDA_STANDARD target
6687 property of the generated project.
6688 <LANG>_STANDARD_REQUIRED <bool>
6690 Specify the C_STANDARD_REQUIRED, CXX_STANDARD_REQUIRED, or
6691 CUDA_STANDARD_REQUIRED target property of the generated project.
6692 <LANG>_EXTENSIONS <bool>
6694 Specify the C_EXTENSIONS, CXX_EXTENSIONS, or CUDA_EXTENSIONS
6695 target property of the generated project.
6696 In this version all files in <bindir>/CMakeFiles/CMakeTmp will be
6698 cleaned automatically. For debugging, --debug-trycompile can be passed
6699 to cmake to avoid this clean. However, multiple sequential try_compile
6700 operations reuse this single output directory. If you use
6701 --debug-trycompile, you can only debug one try_compile call at a time.
6702 The recommended procedure is to protect all try_compile calls in your
6703 project by if(NOT DEFINED <resultVar>) logic, configure with cmake all
6704 the way through once, then delete the cache entry associated with the
6705 try_compile call of interest, and then re-run cmake again with
6706 --debug-trycompile.
6707 Other Behavior Settings
6709 If set, the following variables are passed in to the generated try_com‐
6710 pile CMakeLists.txt to initialize compile target properties with
6711 default values:
6712 · CMAKE_ENABLE_EXPORTS
6714 · CMAKE_LINK_SEARCH_START_STATIC
6716 · CMAKE_LINK_SEARCH_END_STATIC
6718 · CMAKE_POSITION_INDEPENDENT_CODE
6720 If CMP0056 is set to NEW, then CMAKE_EXE_LINKER_FLAGS is passed in as
6722 well.
6723 If CMP0083 is set to NEW, then in order to obtain correct behavior at
6725 link time, the check_pie_supported() command from the CheckPIESupported
6726 module must be called before using the try_compile() command.
6727 The current settings of CMP0065 and CMP0083 are propagated through to
6729 the generated test project.
6730 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
6732 figuration.
6733 Set the CMAKE_TRY_COMPILE_TARGET_TYPE variable to specify the type of
6735 target used for the source file signature.
6736 Set the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable to specify vari‐
6738 ables that must be propagated into the test project. This variable is
6739 meant for use only in toolchain files and is only honored by the
6740 try_compile() command for the source files form, not when given a whole
6741 project.
6742 If CMP0067 is set to NEW, or any of the <LANG>_STANDARD, <LANG>_STAN‐
6744 DARD_REQUIRED, or <LANG>_EXTENSIONS options are used, then the language
6745 standard variables are honored:
6746 · CMAKE_C_STANDARD
6748 · CMAKE_C_STANDARD_REQUIRED
6750 · CMAKE_C_EXTENSIONS
6752 · CMAKE_CXX_STANDARD
6754 · CMAKE_CXX_STANDARD_REQUIRED
6756 · CMAKE_CXX_EXTENSIONS
6758 · CMAKE_CUDA_STANDARD
6760 · CMAKE_CUDA_STANDARD_REQUIRED
6762 · CMAKE_CUDA_EXTENSIONS
6764 Their values are used to set the corresponding target properties in the
6766 generated project (unless overridden by an explicit option).
6767 For the Green Hills MULTI generator the GHS toolset and target system
6769 customization cache variables are also propagated into the test
6770 project.
6771 try_run
6773 Try compiling and then running some code.
6774 Try Compiling and Running Source Files
6776 try_run(<runResultVar> <compileResultVar>
6777 <bindir> <srcfile> [CMAKE_FLAGS <flags>...]
6778 [COMPILE_DEFINITIONS <defs>...]
6779 [LINK_OPTIONS <options>...]
6780 [LINK_LIBRARIES <libs>...]
6781 [COMPILE_OUTPUT_VARIABLE <var>]
6782 [RUN_OUTPUT_VARIABLE <var>]
6783 [OUTPUT_VARIABLE <var>]
6784 [ARGS <args>...])
6785 Try compiling a <srcfile>. Returns TRUE or FALSE for success or fail‐
6787 ure in <compileResultVar>. If the compile succeeded, runs the exe‐
6788 cutable and returns its exit code in <runResultVar>. If the executable
6789 was built, but failed to run, then <runResultVar> will be set to
6790 FAILED_TO_RUN. See the try_compile() command for information on how
6791 the test project is constructed to build the source file.
6792 The options are:
6794 CMAKE_FLAGS <flags>...
6796 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
6797 cmake command-line used to drive the test build. The example in
6798 try_compile() shows how values for variables INCLUDE_DIRECTO‐
6799 RIES, LINK_DIRECTORIES, and LINK_LIBRARIES are used.
6800 COMPILE_DEFINITIONS <defs>...
6802 Specify -Ddefinition arguments to pass to add_definitions() in
6803 the generated test project.
6804 COMPILE_OUTPUT_VARIABLE <var>
6806 Report the compile step build output in a given variable.
6807 LINK_LIBRARIES <libs>...
6809 Specify libraries to be linked in the generated project. The
6810 list of libraries may refer to system libraries and to Imported
6811 Targets from the calling project.
6812 If this option is specified, any -DLINK_LIBRARIES=... value
6814 given to the CMAKE_FLAGS option will be ignored.
6815 LINK_OPTIONS <options>...
6817 Specify link step options to pass to target_link_options() in
6818 the generated project.
6819 OUTPUT_VARIABLE <var>
6821 Report the compile build output and the output from running the
6822 executable in the given variable. This option exists for legacy
6823 reasons. Prefer COMPILE_OUTPUT_VARIABLE and RUN_OUTPUT_VARIABLE
6824 instead.
6825 RUN_OUTPUT_VARIABLE <var>
6827 Report the output from running the executable in a given vari‐
6828 able.
6829 Other Behavior Settings
6831 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
6832 figuration.
6833 Behavior when Cross Compiling
6835 When cross compiling, the executable compiled in the first step usually
6836 cannot be run on the build host. The try_run command checks the
6837 CMAKE_CROSSCOMPILING variable to detect whether CMake is in cross-com‐
6838 piling mode. If that is the case, it will still try to compile the
6839 executable, but it will not try to run the executable unless the
6840 CMAKE_CROSSCOMPILING_EMULATOR variable is set. Instead it will create
6841 cache variables which must be filled by the user or by presetting them
6842 in some CMake script file to the values the executable would have pro‐
6843 duced if it had been run on its actual target platform. These cache
6844 entries are:
6845 <runResultVar>
6847 Exit code if the executable were to be run on the target plat‐
6848 form.
6849 <runResultVar>__TRYRUN_OUTPUT
6851 Output from stdout and stderr if the executable were to be run
6852 on the target platform. This is created only if the RUN_OUT‐
6853 PUT_VARIABLE or OUTPUT_VARIABLE option was used.
6854 In order to make cross compiling your project easier, use try_run only
6856 if really required. If you use try_run, use the RUN_OUTPUT_VARIABLE or
6857 OUTPUT_VARIABLE options only if really required. Using them will
6858 require that when cross-compiling, the cache variables will have to be
6859 set manually to the output of the executable. You can also “guard” the
6860 calls to try_run with an if() block checking the CMAKE_CROSSCOMPILING
6861 variable and provide an easy-to-preset alternative for this case.
6862
6864 These commands are available only in CTest scripts.
6865 ctest_build
6867 Perform the CTest Build Step as a Dashboard Client.
6868 ctest_build([BUILD <build-dir>] [APPEND]
6870 [CONFIGURATION <config>]
6871 [FLAGS <flags>]
6872 [PROJECT_NAME <project-name>]
6873 [TARGET <target-name>]
6874 [NUMBER_ERRORS <num-err-var>]
6875 [NUMBER_WARNINGS <num-warn-var>]
6876 [RETURN_VALUE <result-var>]
6877 [CAPTURE_CMAKE_ERROR <result-var>]
6878 )
6879 Build the project and store results in Build.xml for submission with
6881 the ctest_submit() command.
6882 The CTEST_BUILD_COMMAND variable may be set to explicitly specify the
6884 build command line. Otherwise the build command line is computed auto‐
6885 matically based on the options given.
6886 The options are:
6888 BUILD <build-dir>
6890 Specify the top-level build directory. If not given, the
6891 CTEST_BINARY_DIRECTORY variable is used.
6892 APPEND Mark Build.xml for append to results previously submitted to a
6894 dashboard server since the last ctest_start() call. Append
6895 semantics are defined by the dashboard server in use. This does
6896 not cause results to be appended to a .xml file produced by a
6897 previous call to this command.
6898 CONFIGURATION <config>
6900 Specify the build configuration (e.g. Debug). If not specified
6901 the CTEST_BUILD_CONFIGURATION variable will be checked. Other‐
6902 wise the -C <cfg> option given to the ctest(1) command will be
6903 used, if any.
6904 FLAGS <flags>
6906 Pass additional arguments to the underlying build command. If
6907 not specified the CTEST_BUILD_FLAGS variable will be checked.
6908 This can, e.g., be used to trigger a parallel build using the -j
6909 option of make. See the ProcessorCount module for an example.
6910 PROJECT_NAME <project-name>
6912 Ignored. This was once used but is no longer needed.
6913 TARGET <target-name>
6915 Specify the name of a target to build. If not specified the
6916 CTEST_BUILD_TARGET variable will be checked. Otherwise the
6917 default target will be built. This is the “all” target (called
6918 ALL_BUILD in Visual Studio Generators).
6919 NUMBER_ERRORS <num-err-var>
6921 Store the number of build errors detected in the given variable.
6922 NUMBER_WARNINGS <num-warn-var>
6924 Store the number of build warnings detected in the given vari‐
6925 able.
6926 RETURN_VALUE <result-var>
6928 Store the return value of the native build tool in the given
6929 variable.
6930 CAPTURE_CMAKE_ERROR <result-var>
6932 Store in the <result-var> variable -1 if there are any errors
6933 running the command and prevent ctest from returning non-zero if
6934 an error occurs.
6935 QUIET Suppress any CTest-specific non-error output that would have
6937 been printed to the console otherwise. The summary of warnings
6938 / errors, as well as the output from the native build tool is
6939 unaffected by this option.
6940 ctest_configure
6942 Perform the CTest Configure Step as a Dashboard Client.
6943 ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
6945 [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
6946 [CAPTURE_CMAKE_ERROR <result-var>])
6947 Configure the project build tree and record results in Configure.xml
6949 for submission with the ctest_submit() command.
6950 The options are:
6952 BUILD <build-dir>
6954 Specify the top-level build directory. If not given, the
6955 CTEST_BINARY_DIRECTORY variable is used.
6956 SOURCE <source-dir>
6958 Specify the source directory. If not given, the
6959 CTEST_SOURCE_DIRECTORY variable is used.
6960 APPEND Mark Configure.xml for append to results previously submitted to
6962 a dashboard server since the last ctest_start() call. Append
6963 semantics are defined by the dashboard server in use. This does
6964 not cause results to be appended to a .xml file produced by a
6965 previous call to this command.
6966 OPTIONS <options>
6968 Specify command-line arguments to pass to the configuration
6969 tool.
6970 RETURN_VALUE <result-var>
6972 Store in the <result-var> variable the return value of the
6973 native configuration tool.
6974 CAPTURE_CMAKE_ERROR <result-var>
6976 Store in the <result-var> variable -1 if there are any errors
6977 running the command and prevent ctest from returning non-zero if
6978 an error occurs.
6979 QUIET Suppress any CTest-specific non-error messages that would have
6981 otherwise been printed to the console. Output from the underly‐
6982 ing configure command is not affected.
6983 ctest_coverage
6985 Perform the CTest Coverage Step as a Dashboard Client.
6986 ctest_coverage([BUILD <build-dir>] [APPEND]
6988 [LABELS <label>...]
6989 [RETURN_VALUE <result-var>]
6990 [CAPTURE_CMAKE_ERROR <result-var]
6991 [QUIET]
6992 )
6993 Collect coverage tool results and stores them in Coverage.xml for sub‐
6995 mission with the ctest_submit() command.
6996 The options are:
6998 BUILD <build-dir>
7000 Specify the top-level build directory. If not given, the
7001 CTEST_BINARY_DIRECTORY variable is used.
7002 APPEND Mark Coverage.xml for append to results previously submitted to
7004 a dashboard server since the last ctest_start() call. Append
7005 semantics are defined by the dashboard server in use. This does
7006 not cause results to be appended to a .xml file produced by a
7007 previous call to this command.
7008 LABELS Filter the coverage report to include only source files labeled
7010 with at least one of the labels specified.
7011 RETURN_VALUE <result-var>
7013 Store in the <result-var> variable 0 if coverage tools ran with‐
7014 out error and non-zero otherwise.
7015 CAPTURE_CMAKE_ERROR <result-var>
7017 Store in the <result-var> variable -1 if there are any errors
7018 running the command and prevent ctest from returning non-zero if
7019 an error occurs.
7020 QUIET Suppress any CTest-specific non-error output that would have
7022 been printed to the console otherwise. The summary indicating
7023 how many lines of code were covered is unaffected by this
7024 option.
7025 ctest_empty_binary_directory
7027 empties the binary directory
7028 ctest_empty_binary_directory( directory )
7030 Removes a binary directory. This command will perform some checks
7032 prior to deleting the directory in an attempt to avoid malicious or
7033 accidental directory deletion.
7034 ctest_memcheck
7036 Perform the CTest MemCheck Step as a Dashboard Client.
7037 ctest_memcheck([BUILD <build-dir>] [APPEND]
7039 [START <start-number>]
7040 [END <end-number>]
7041 [STRIDE <stride-number>]
7042 [EXCLUDE <exclude-regex>]
7043 [INCLUDE <include-regex>]
7044 [EXCLUDE_LABEL <label-exclude-regex>]
7045 [INCLUDE_LABEL <label-include-regex>]
7046 [EXCLUDE_FIXTURE <regex>]
7047 [EXCLUDE_FIXTURE_SETUP <regex>]
7048 [EXCLUDE_FIXTURE_CLEANUP <regex>]
7049 [PARALLEL_LEVEL <level>]
7050 [TEST_LOAD <threshold>]
7051 [SCHEDULE_RANDOM <ON|OFF>]
7052 [STOP_TIME <time-of-day>]
7053 [RETURN_VALUE <result-var>]
7054 [DEFECT_COUNT <defect-count-var>]
7055 [QUIET]
7056 )
7057 Run tests with a dynamic analysis tool and store results in Mem‐
7059 Check.xml for submission with the ctest_submit() command.
7060 Most options are the same as those for the ctest_test() command.
7062 The options unique to this command are:
7064 DEFECT_COUNT <defect-count-var>
7066 Store in the <defect-count-var> the number of defects found.
7067 ctest_read_custom_files
7069 read CTestCustom files.
7070 ctest_read_custom_files( directory ... )
7072 Read all the CTestCustom.ctest or CTestCustom.cmake files from the
7074 given directory.
7075 By default, invoking ctest(1) without a script will read custom files
7077 from the binary directory.
7078 ctest_run_script
7080 runs a ctest -S script
7081 ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
7083 script_file_name2 ... [RETURN_VALUE var])
7084 Runs a script or scripts much like if it was run from ctest -S. If no
7086 argument is provided then the current script is run using the current
7087 settings of the variables. If NEW_PROCESS is specified then each
7088 script will be run in a separate process.If RETURN_VALUE is specified
7089 the return value of the last script run will be put into var.
7090 ctest_sleep
7092 sleeps for some amount of time
7093 ctest_sleep(<seconds>)
7095 Sleep for given number of seconds.
7097 ctest_sleep(<time1> <duration> <time2>)
7099 Sleep for t=(time1 + duration - time2) seconds if t > 0.
7101 ctest_start
7103 Starts the testing for a given model
7104 ctest_start(<model> [<source> [<binary>]] [TRACK <track>] [QUIET])
7106 ctest_start([<model> [<source> [<binary>]]] [TRACK <track>] APPEND [QUIET])
7108 Starts the testing for a given model. The command should be called
7110 after the binary directory is initialized.
7111 The parameters are as follows:
7113 <model>
7115 Set the dashboard model. Must be one of Experimental, Continu‐
7116 ous, or Nightly. This parameter is required unless APPEND is
7117 specified.
7118 <source>
7120 Set the source directory. If not specified, the value of
7121 CTEST_SOURCE_DIRECTORY is used instead.
7122 <binary>
7124 Set the binary directory. If not specified, the value of
7125 CTEST_BINARY_DIRECTORY is used instead.
7126 TRACK <track>
7128 If TRACK is used, the submissions will go to the specified track
7129 on the CDash server. If no TRACK is specified, the name of the
7130 model is used by default.
7131 APPEND If APPEND is used, the existing TAG is used rather than creating
7133 a new one based on the current time stamp. If you use APPEND,
7134 you can omit the <model> and TRACK <track> parameters, because
7135 they will be read from the generated TAG file. For example:
7136 ctest_start(Experimental TRACK TrackExperimental)
7138 Later, in another ctest -S script:
7140 ctest_start(APPEND)
7142 When the second script runs ctest_start(APPEND), it will read
7144 the Experimental model and TrackExperimental track from the TAG
7145 file generated by the first ctest_start() command. Please note
7146 that if you call ctest_start(APPEND) and specify a different
7147 model or track than in the first ctest_start() command, a warn‐
7148 ing will be issued, and the new model and track will be used.
7149 QUIET If QUIET is used, CTest will suppress any non-error messages
7151 that it otherwise would have printed to the console.
7152 The parameters for ctest_start() can be issued in any order, with the
7154 exception that <model>, <source>, and <binary> have to appear in that
7155 order with respect to each other. The following are all valid and
7156 equivalent:
7157 ctest_start(Experimental path/to/source path/to/binary TRACK SomeTrack QUIET APPEND)
7159 ctest_start(TRACK SomeTrack Experimental QUIET path/to/source APPEND path/to/binary)
7161 ctest_start(APPEND QUIET Experimental path/to/source TRACK SomeTrack path/to/binary)
7163 However, for the sake of readability, it is recommended that you order
7165 your parameters in the order listed at the top of this page.
7166 If the CTEST_CHECKOUT_COMMAND variable (or the CTEST_CVS_CHECKOUT vari‐
7168 able) is set, its content is treated as command-line. The command is
7169 invoked with the current working directory set to the parent of the
7170 source directory, even if the source directory already exists. This
7171 can be used to create the source tree from a version control reposi‐
7172 tory.
7173 ctest_submit
7175 Perform the CTest Submit Step as a Dashboard Client.
7176 ctest_submit([PARTS <part>...] [FILES <file>...]
7178 [SUBMIT_URL <url>]
7179 [HTTPHEADER <header>]
7180 [RETRY_COUNT <count>]
7181 [RETRY_DELAY <delay>]
7182 [RETURN_VALUE <result-var>]
7183 [CAPTURE_CMAKE_ERROR <result-var>]
7184 [QUIET]
7185 )
7186 Submit results to a dashboard server. By default all available parts
7188 are submitted.
7189 The options are:
7191 PARTS <part>...
7193 Specify a subset of parts to submit. Valid part names are:
7194 Start = nothing
7196 Update = ctest_update results, in Update.xml
7197 Configure = ctest_configure results, in Configure.xml
7198 Build = ctest_build results, in Build.xml
7199 Test = ctest_test results, in Test.xml
7200 Coverage = ctest_coverage results, in Coverage.xml
7201 MemCheck = ctest_memcheck results, in DynamicAnalysis.xml
7202 Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
7203 ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
7204 Upload = Files prepared for upload by ctest_upload(), in Upload.xml
7205 Submit = nothing
7206 Done = Build is complete, in Done.xml
7207 FILES <file>...
7209 Specify an explicit list of specific files to be submitted.
7210 Each individual file must exist at the time of the call.
7211 SUBMIT_URL <url>
7213 The http or https URL of the dashboard server to send the sub‐
7214 mission to. If not given, the CTEST_SUBMIT_URL variable is
7215 used.
7216 HTTPHEADER <HTTP-header>
7218 Specify HTTP header to be included in the request to CDash dur‐
7219 ing submission. This suboption can be repeated several times.
7220 RETRY_COUNT <count>
7222 Specify how many times to retry a timed-out submission.
7223 RETRY_DELAY <delay>
7225 Specify how long (in seconds) to wait after a timed-out submis‐
7226 sion before attempting to re-submit.
7227 RETURN_VALUE <result-var>
7229 Store in the <result-var> variable 0 for success and non-zero on
7230 failure.
7231 CAPTURE_CMAKE_ERROR <result-var>
7233 Store in the <result-var> variable -1 if there are any errors
7234 running the command and prevent ctest from returning non-zero if
7235 an error occurs.
7236 QUIET Suppress all non-error messages that would have otherwise been
7238 printed to the console.
7239 Submit to CDash Upload API
7241 ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
7242 [SUBMIT_URL <url>]
7243 [HTTPHEADER <header>]
7244 [RETRY_COUNT <count>]
7245 [RETRY_DELAY <delay>]
7246 [RETURN_VALUE <result-var>]
7247 [QUIET])
7248 This second signature is used to upload files to CDash via the CDash
7250 file upload API. The API first sends a request to upload to CDash along
7251 with a content hash of the file. If CDash does not already have the
7252 file, then it is uploaded. Along with the file, a CDash type string is
7253 specified to tell CDash which handler to use to process the data.
7254 This signature accepts the SUBMIT_URL, HTTPHEADER, RETRY_COUNT,
7256 RETRY_DELAY, RETURN_VALUE and QUIET options as described above.
7257 ctest_test
7259 Perform the CTest Test Step as a Dashboard Client.
7260 ctest_test([BUILD <build-dir>] [APPEND]
7262 [START <start-number>]
7263 [END <end-number>]
7264 [STRIDE <stride-number>]
7265 [EXCLUDE <exclude-regex>]
7266 [INCLUDE <include-regex>]
7267 [EXCLUDE_LABEL <label-exclude-regex>]
7268 [INCLUDE_LABEL <label-include-regex>]
7269 [EXCLUDE_FIXTURE <regex>]
7270 [EXCLUDE_FIXTURE_SETUP <regex>]
7271 [EXCLUDE_FIXTURE_CLEANUP <regex>]
7272 [PARALLEL_LEVEL <level>]
7273 [TEST_LOAD <threshold>]
7274 [SCHEDULE_RANDOM <ON|OFF>]
7275 [STOP_TIME <time-of-day>]
7276 [RETURN_VALUE <result-var>]
7277 [CAPTURE_CMAKE_ERROR <result-var>]
7278 [QUIET]
7279 )
7280 Run tests in the project build tree and store results in Test.xml for
7282 submission with the ctest_submit() command.
7283 The options are:
7285 BUILD <build-dir>
7287 Specify the top-level build directory. If not given, the
7288 CTEST_BINARY_DIRECTORY variable is used.
7289 APPEND Mark Test.xml for append to results previously submitted to a
7291 dashboard server since the last ctest_start() call. Append
7292 semantics are defined by the dashboard server in use. This does
7293 not cause results to be appended to a .xml file produced by a
7294 previous call to this command.
7295 START <start-number>
7297 Specify the beginning of a range of test numbers.
7298 END <end-number>
7300 Specify the end of a range of test numbers.
7301 STRIDE <stride-number>
7303 Specify the stride by which to step across a range of test num‐
7304 bers.
7305 EXCLUDE <exclude-regex>
7307 Specify a regular expression matching test names to exclude.
7308 INCLUDE <include-regex>
7310 Specify a regular expression matching test names to include.
7311 Tests not matching this expression are excluded.
7312 EXCLUDE_LABEL <label-exclude-regex>
7314 Specify a regular expression matching test labels to exclude.
7315 INCLUDE_LABEL <label-include-regex>
7317 Specify a regular expression matching test labels to include.
7318 Tests not matching this expression are excluded.
7319 EXCLUDE_FIXTURE <regex>
7321 If a test in the set of tests to be executed requires a particu‐
7322 lar fixture, that fixture’s setup and cleanup tests would nor‐
7323 mally be added to the test set automatically. This option pre‐
7324 vents adding setup or cleanup tests for fixtures matching the
7325 <regex>. Note that all other fixture behavior is retained,
7326 including test dependencies and skipping tests that have fixture
7327 setup tests that fail.
7328 EXCLUDE_FIXTURE_SETUP <regex>
7330 Same as EXCLUDE_FIXTURE except only matching setup tests are
7331 excluded.
7332 EXCLUDE_FIXTURE_CLEANUP <regex>
7334 Same as EXCLUDE_FIXTURE except only matching cleanup tests are
7335 excluded.
7336 PARALLEL_LEVEL <level>
7338 Specify a positive number representing the number of tests to be
7339 run in parallel.
7340 TEST_LOAD <threshold>
7342 While running tests in parallel, try not to start tests when
7343 they may cause the CPU load to pass above a given threshold. If
7344 not specified the CTEST_TEST_LOAD variable will be checked, and
7345 then the --test-load command-line argument to ctest(1). See
7346 also the TestLoad setting in the CTest Test Step.
7347 SCHEDULE_RANDOM <ON|OFF>
7349 Launch tests in a random order. This may be useful for detect‐
7350 ing implicit test dependencies.
7351 STOP_TIME <time-of-day>
7353 Specify a time of day at which the tests should all stop run‐
7354 ning.
7355 RETURN_VALUE <result-var>
7357 Store in the <result-var> variable 0 if all tests passed. Store
7358 non-zero if anything went wrong.
7359 CAPTURE_CMAKE_ERROR <result-var>
7361 Store in the <result-var> variable -1 if there are any errors
7362 running the command and prevent ctest from returning non-zero if
7363 an error occurs.
7364 QUIET Suppress any CTest-specific non-error messages that would have
7366 otherwise been printed to the console. Output from the underly‐
7367 ing test command is not affected. Summary info detailing the
7368 percentage of passing tests is also unaffected by the QUIET
7369 option.
7370 See also the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE and
7372 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables.
7373 ctest_update
7375 Perform the CTest Update Step as a Dashboard Client.
7376 ctest_update([SOURCE <source-dir>]
7378 [RETURN_VALUE <result-var>]
7379 [CAPTURE_CMAKE_ERROR <result-var>]
7380 [QUIET])
7381 Update the source tree from version control and record results in
7383 Update.xml for submission with the ctest_submit() command.
7384 The options are:
7386 SOURCE <source-dir>
7388 Specify the source directory. If not given, the
7389 CTEST_SOURCE_DIRECTORY variable is used.
7390 RETURN_VALUE <result-var>
7392 Store in the <result-var> variable the number of files updated
7393 or -1 on error.
7394 CAPTURE_CMAKE_ERROR <result-var>
7396 Store in the <result-var> variable -1 if there are any errors
7397 running the command and prevent ctest from returning non-zero if
7398 an error occurs.
7399 QUIET Tell CTest to suppress most non-error messages that it would
7401 have otherwise printed to the console. CTest will still report
7402 the new revision of the repository and any conflicting files
7403 that were found.
7404 The update always follows the version control branch currently checked
7406 out in the source directory. See the CTest Update Step documentation
7407 for more information.
7408 ctest_upload
7410 Upload files to a dashboard server as a Dashboard Client.
7411 ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
7413 The options are:
7415 FILES <file>...
7417 Specify a list of files to be sent along with the build results
7418 to the dashboard server.
7419 QUIET Suppress any CTest-specific non-error output that would have
7421 been printed to the console otherwise.
7422 CAPTURE_CMAKE_ERROR <result-var>
7424 Store in the <result-var> variable -1 if there are any errors
7425 running the command and prevent ctest from returning non-zero if
7426 an error occurs.
7427
7429 These commands are deprecated and are only made available to maintain
7430 backward compatibility. The documentation of each command states the
7431 CMake version in which it was deprecated. Do not use these commands in
7432 new code.
7433 build_name
7435 Disallowed since version 3.0. See CMake Policy CMP0036.
7436 Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.
7438 build_name(variable)
7440 Sets the specified variable to a string representing the platform and
7442 compiler settings. These values are now available through the
7443 CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
7444 exec_program
7446 Deprecated since version 3.0: Use the execute_process() command
7447 instead.
7448 Run an executable program during the processing of the CMakeList.txt
7451 file.
7452 exec_program(Executable [directory in which to run]
7454 [ARGS <arguments to executable>]
7455 [OUTPUT_VARIABLE <var>]
7456 [RETURN_VALUE <var>])
7457 The executable is run in the optionally specified directory. The exe‐
7459 cutable can include arguments if it is double quoted, but it is better
7460 to use the optional ARGS argument to specify arguments to the program.
7461 This is because cmake will then be able to escape spaces in the exe‐
7462 cutable path. An optional argument OUTPUT_VARIABLE specifies a vari‐
7463 able in which to store the output. To capture the return value of the
7464 execution, provide a RETURN_VALUE. If OUTPUT_VARIABLE is specified,
7465 then no output will go to the stdout/stderr of the console running
7466 cmake.
7467 export_library_dependencies
7469 Disallowed since version 3.0. See CMake Policy CMP0033.
7470 Use install(EXPORT) or export() command.
7472 This command generates an old-style library dependencies file.
7474 Projects requiring CMake 2.6 or later should not use the command. Use
7475 instead the install(EXPORT) command to help export targets from an
7476 installation tree and the export() command to export targets from a
7477 build tree.
7478 The old-style library dependencies file does not take into account
7480 per-configuration names of libraries or the LINK_INTERFACE_LIBRARIES
7481 target property.
7482 export_library_dependencies(<file> [APPEND])
7484 Create a file named <file> that can be included into a CMake listfile
7486 with the INCLUDE command. The file will contain a number of SET com‐
7487 mands that will set all the variables needed for library dependency
7488 information. This should be the last command in the top level CMake‐
7489 Lists.txt file of the project. If the APPEND option is specified, the
7490 SET commands will be appended to the given file instead of replacing
7491 it.
7492 install_files
7494 Deprecated since version 3.0: Use the install(FILES) command instead.
7495 This command has been superceded by the install() command. It is pro‐
7498 vided for compatibility with older CMake code. The FILES form is
7499 directly replaced by the FILES form of the install() command. The reg‐
7500 exp form can be expressed more clearly using the GLOB form of the
7501 file() command.
7502 install_files(<dir> extension file file ...)
7504 Create rules to install the listed files with the given extension into
7506 the given directory. Only files existing in the current source tree or
7507 its corresponding location in the binary tree may be listed. If a file
7508 specified already has an extension, that extension will be removed
7509 first. This is useful for providing lists of source files such as
7510 foo.cxx when you want the corresponding foo.h to be installed. A typi‐
7511 cal extension is ‘.h’.
7512 install_files(<dir> regexp)
7514 Any files in the current source directory that match the regular
7516 expression will be installed.
7517 install_files(<dir> FILES file file ...)
7519 Any files listed after the FILES keyword will be installed explicitly
7521 from the names given. Full paths are allowed in this form.
7522 The directory <dir> is relative to the installation prefix, which is
7524 stored in the variable CMAKE_INSTALL_PREFIX.
7525 install_programs
7527 Deprecated since version 3.0: Use the install(PROGRAMS) command
7528 instead.
7529 This command has been superceded by the install() command. It is pro‐
7532 vided for compatibility with older CMake code. The FILES form is
7533 directly replaced by the PROGRAMS form of the install() command. The
7534 regexp form can be expressed more clearly using the GLOB form of the
7535 file() command.
7536 install_programs(<dir> file1 file2 [file3 ...])
7538 install_programs(<dir> FILES file1 [file2 ...])
7539 Create rules to install the listed programs into the given directory.
7541 Use the FILES argument to guarantee that the file list version of the
7542 command will be used even when there is only one argument.
7543 install_programs(<dir> regexp)
7545 In the second form any program in the current source directory that
7547 matches the regular expression will be installed.
7548 This command is intended to install programs that are not built by
7550 cmake, such as shell scripts. See the TARGETS form of the install()
7551 command to create installation rules for targets built by cmake.
7552 The directory <dir> is relative to the installation prefix, which is
7554 stored in the variable CMAKE_INSTALL_PREFIX.
7555 install_targets
7557 Deprecated since version 3.0: Use the install(TARGETS) command instead.
7558 This command has been superceded by the install() command. It is pro‐
7561 vided for compatibility with older CMake code.
7562 install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
7564 Create rules to install the listed targets into the given directory.
7566 The directory <dir> is relative to the installation prefix, which is
7567 stored in the variable CMAKE_INSTALL_PREFIX. If RUNTIME_DIRECTORY is
7568 specified, then on systems with special runtime files (Windows DLL),
7569 the files will be copied to that directory.
7570 load_command
7572 Disallowed since version 3.0. See CMake Policy CMP0031.
7573 Load a command into a running CMake.
7575 load_command(COMMAND_NAME <loc1> [loc2 ...])
7577 The given locations are searched for a library whose name is cmCOM‐
7579 MAND_NAME. If found, it is loaded as a module and the command is added
7580 to the set of available CMake commands. Usually, try_compile() is used
7581 before this command to compile the module. If the command is success‐
7582 fully loaded a variable named
7583 CMAKE_LOADED_COMMAND_<COMMAND_NAME>
7585 will be set to the full path of the module that was loaded. Otherwise
7587 the variable will not be set.
7588 make_directory
7590 Deprecated since version 3.0: Use the file(MAKE_DIRECTORY) command
7591 instead.
7592 make_directory(directory)
7595 Creates the specified directory. Full paths should be given. Any par‐
7597 ent directories that do not exist will also be created. Use with care.
7598 output_required_files
7600 Disallowed since version 3.0. See CMake Policy CMP0032.
7601 Approximate C preprocessor dependency scanning.
7603 This command exists only because ancient CMake versions provided it.
7605 CMake handles preprocessor dependency scanning automatically using a
7606 more advanced scanner.
7607 output_required_files(srcfile outputfile)
7609 Outputs a list of all the source files that are required by the speci‐
7611 fied srcfile. This list is written into outputfile. This is similar
7612 to writing out the dependencies for srcfile except that it jumps from
7613 .h files into .cxx, .c and .cpp files if possible.
7614 qt_wrap_cpp
7616 Deprecated since version 3.14: This command was originally added to
7617 support Qt 3 before the add_custom_command() command was sufficiently
7618 mature. The FindQt4 module provides the qt4_wrap_cpp() macro, which
7619 should be used instead for Qt 4 projects. For projects using Qt 5 or
7620 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
7621 vides qt5_wrap_cpp()).
7622 Manually create Qt Wrappers.
7625 qt_wrap_cpp(resultingLibraryName DestName SourceLists ...)
7627 Produces moc files for all the .h files listed in the SourceLists. The
7629 moc files will be added to the library using the DestName source list.
7630 Consider updating the project to use the AUTOMOC target property
7632 instead for a more automated way of invoking the moc tool.
7633 qt_wrap_ui
7635 Deprecated since version 3.14: This command was originally added to
7636 support Qt 3 before the add_custom_command() command was sufficiently
7637 mature. The FindQt4 module provides the qt4_wrap_ui() macro, which
7638 should be used instead for Qt 4 projects. For projects using Qt 5 or
7639 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
7640 vides qt5_wrap_ui()).
7641 Manually create Qt user interfaces Wrappers.
7644 qt_wrap_ui(resultingLibraryName HeadersDestName
7646 SourcesDestName SourceLists ...)
7647 Produces .h and .cxx files for all the .ui files listed in the
7649 SourceLists. The .h files will be added to the library using the Head‐
7650 ersDestNamesource list. The .cxx files will be added to the library
7651 using the SourcesDestNamesource list.
7652 Consider updating the project to use the AUTOUIC target property
7654 instead for a more automated way of invoking the uic tool.
7655 remove
7657 Deprecated since version 3.0: Use the list(REMOVE_ITEM) command
7658 instead.
7659 remove(VAR VALUE VALUE ...)
7662 Removes VALUE from the variable VAR. This is typically used to remove
7664 entries from a vector (e.g. semicolon separated list). VALUE is
7665 expanded.
7666 subdir_depends
7668 Disallowed since version 3.0. See CMake Policy CMP0029.
7669 Does nothing.
7671 subdir_depends(subdir dep1 dep2 ...)
7673 Does not do anything. This command used to help projects order paral‐
7675 lel builds correctly. This functionality is now automatic.
7676 subdirs
7678 Deprecated since version 3.0: Use the add_subdirectory() command
7679 instead.
7680 Add a list of subdirectories to the build.
7683 subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
7685 [PREORDER] )
7686 Add a list of subdirectories to the build. The add_subdirectory() com‐
7688 mand should be used instead of subdirs although subdirs will still
7689 work. This will cause any CMakeLists.txt files in the sub directories
7690 to be processed by CMake. Any directories after the PREORDER flag are
7691 traversed first by makefile builds, the PREORDER flag has no effect on
7692 IDE projects. Any directories after the EXCLUDE_FROM_ALL marker will
7693 not be included in the top level makefile or project file. This is
7694 useful for having CMake create makefiles or projects for a set of exam‐
7695 ples in a project. You would want CMake to generate makefiles or
7696 project files for all the examples at the same time, but you would not
7697 want them to show up in the top level project or be built each time
7698 make is run from the top.
7699 use_mangled_mesa
7701 Disallowed since version 3.0. See CMake Policy CMP0030.
7702 Copy mesa headers for use in combination with system GL.
7704 use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
7706 The path to mesa includes, should contain gl_mangle.h. The mesa head‐
7708 ers are copied to the specified output directory. This allows mangled
7709 mesa headers to override other GL headers by being added to the include
7710 directory path earlier.
7711 utility_source
7713 Disallowed since version 3.0. See CMake Policy CMP0034.
7714 Specify the source tree of a third-party utility.
7716 utility_source(cache_entry executable_name
7718 path_to_source [file1 file2 ...])
7719 When a third-party utility’s source is included in the distribution,
7721 this command specifies its location and name. The cache entry will not
7722 be set unless the path_to_source and all listed files exist. It is
7723 assumed that the source tree of the utility will have been built before
7724 it is needed.
7725 When cross compiling CMake will print a warning if a utility_source()
7727 command is executed, because in many cases it is used to build an exe‐
7728 cutable which is executed later on. This doesn’t work when cross com‐
7729 piling, since the executable can run only on their target platform. So
7730 in this case the cache entry has to be adjusted manually so it points
7731 to an executable which is runnable on the build host.
7732 variable_requires
7734 Disallowed since version 3.0. See CMake Policy CMP0035.
7735 Use the if() command instead.
7737 Assert satisfaction of an option’s required variables.
7739 variable_requires(TEST_VARIABLE RESULT_VARIABLE
7741 REQUIRED_VARIABLE1
7742 REQUIRED_VARIABLE2 ...)
7743 The first argument (TEST_VARIABLE) is the name of the variable to be
7745 tested, if that variable is false nothing else is done. If TEST_VARI‐
7746 ABLE is true, then the next argument (RESULT_VARIABLE) is a variable
7747 that is set to true if all the required variables are set. The rest of
7748 the arguments are variables that must be true or not set to NOTFOUND to
7749 avoid an error. If any are not true, an error is reported.
7750 write_file
7752 Deprecated since version 3.0: Use the file(WRITE) command instead.
7753 write_file(filename "message to write"... [APPEND])
7756 The first argument is the file name, the rest of the arguments are mes‐
7758 sages to write. If the argument APPEND is specified, then the message
7759 will be appended.
7760 NOTE 1: file(WRITE) and file(APPEND) do exactly the same as this one
7762 but add some more functionality.
7763 NOTE 2: When using write_file the produced file cannot be used as an
7765 input to CMake (CONFIGURE_FILE, source file …) because it will lead to
7766 an infinite loop. Use configure_file() if you want to generate input
7767 files to CMake.
7768
7770 2000-2019 Kitware, Inc. and Contributors
77713.14.5 Jun 01, 2019 CMAKE-COMMANDS(7)