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 arguments were
223 recognized. This can be checked afterwards to see whether your macro
224 was called with unrecognized parameters.
225 <one_value_keywords> and <multi_value_keywords> that were given no val‐
227 ues at all are collected in a variable <prefix>_KEYWORDS_MISSING_VALUES
228 that will be undefined if all keywords received values. This can be
229 checked to see if there were keywords without any values given.
230 Consider the following example macro, my_install(), which takes similar
232 arguments to the real install() command:
233 macro(my_install)
235 set(options OPTIONAL FAST)
236 set(oneValueArgs DESTINATION RENAME)
237 set(multiValueArgs TARGETS CONFIGURATIONS)
238 cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
239 "${multiValueArgs}" ${ARGN} )
240 # ...
242 Assume my_install() has been called like this:
244 my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)
246 After the cmake_parse_arguments call the macro will have set or unde‐
248 fined the following variables:
249 MY_INSTALL_OPTIONAL = TRUE
251 MY_INSTALL_FAST = FALSE # was not used in call to my_install
252 MY_INSTALL_DESTINATION = "bin"
253 MY_INSTALL_RENAME <UNDEFINED> # was not used
254 MY_INSTALL_TARGETS = "foo;bar"
255 MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
256 MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
257 MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS"
258 # No value for "CONFIGURATIONS" given
259 You can then continue and process these variables.
261 Keywords terminate lists of values, e.g. if directly after a
263 one_value_keyword another recognized keyword follows, this is inter‐
264 preted as the beginning of the new option. E.g. my_install(TARGETS
265 foo DESTINATION OPTIONAL) would result in MY_INSTALL_DESTINATION set to
266 "OPTIONAL", but as OPTIONAL is a keyword itself MY_INSTALL_DESTINATION
267 will be empty (but added to MY_INSTALL_KEYWORDS_MISSING_VALUES) and
268 MY_INSTALL_OPTIONAL will therefore be set to TRUE.
269 cmake_policy
271 Manage CMake Policy settings. See the cmake-policies(7) manual for
272 defined policies.
273 As CMake evolves it is sometimes necessary to change existing behavior
275 in order to fix bugs or improve implementations of existing features.
276 The CMake Policy mechanism is designed to help keep existing projects
277 building as new versions of CMake introduce changes in behavior. Each
278 new policy (behavioral change) is given an identifier of the form
279 CMP<NNNN> where <NNNN> is an integer index. Documentation associated
280 with each policy describes the OLD and NEW behavior and the reason the
281 policy was introduced. Projects may set each policy to select the
282 desired behavior. When CMake needs to know which behavior to use it
283 checks for a setting specified by the project. If no setting is avail‐
284 able the OLD behavior is assumed and a warning is produced requesting
285 that the policy be set.
286 Setting Policies by CMake Version
288 The cmake_policy command is used to set policies to OLD or NEW behav‐
289 ior. While setting policies individually is supported, we encourage
290 projects to set policies based on CMake versions:
291 cmake_policy(VERSION <min>[...<max>])
293 <min> and the optional <max> are each CMake versions of the form
295 major.minor[.patch[.tweak]], and the ... is literal. The <min> version
296 must be at least 2.4 and at most the running version of CMake. The
297 <max> version, if specified, must be at least the <min> version but may
298 exceed the running version of CMake. If the running version of CMake
299 is older than 3.12, the extra ... dots will be seen as version compo‐
300 nent separators, resulting in the ...<max> part being ignored and pre‐
301 serving the pre-3.12 behavior of basing policies on <min>.
302 This specifies that the current CMake code is written for the given
304 range of CMake versions. All policies known to the running version of
305 CMake and introduced in the <min> (or <max>, if specified) version or
306 earlier will be set to use NEW behavior. All policies introduced in
307 later versions will be unset (unless the CMAKE_POLICY_DEFAULT_CMP<NNNN>
308 variable sets a default). This effectively requests behavior preferred
309 as of a given CMake version and tells newer CMake versions to warn
310 about their new policies.
311 Note that the cmake_minimum_required(VERSION) command implicitly calls
313 cmake_policy(VERSION) too.
314 Setting Policies Explicitly
316 cmake_policy(SET CMP<NNNN> NEW)
317 cmake_policy(SET CMP<NNNN> OLD)
318 Tell CMake to use the OLD or NEW behavior for a given policy. Projects
320 depending on the old behavior of a given policy may silence a policy
321 warning by setting the policy state to OLD. Alternatively one may fix
322 the project to work with the new behavior and set the policy state to
323 NEW.
324 NOTE:
326 The OLD behavior of a policy is deprecated by definition and may be
327 removed in a future version of CMake.
328 Checking Policy Settings
330 cmake_policy(GET CMP<NNNN> <variable>)
331 Check whether a given policy is set to OLD or NEW behavior. The output
333 <variable> value will be OLD or NEW if the policy is set, and empty
334 otherwise.
335 CMake Policy Stack
337 CMake keeps policy settings on a stack, so changes made by the
338 cmake_policy command affect only the top of the stack. A new entry on
339 the policy stack is managed automatically for each subdirectory to pro‐
340 tect its parents and siblings. CMake also manages a new entry for
341 scripts loaded by include() and find_package() commands except when
342 invoked with the NO_POLICY_SCOPE option (see also policy CMP0011). The
343 cmake_policy command provides an interface to manage custom entries on
344 the policy stack:
345 cmake_policy(PUSH)
347 cmake_policy(POP)
348 Each PUSH must have a matching POP to erase any changes. This is use‐
350 ful to make temporary changes to policy settings. Calls to the
351 cmake_minimum_required(VERSION), cmake_policy(VERSION), or cmake_pol‐
352 icy(SET) commands influence only the current top of the policy stack.
353 Commands created by the function() and macro() commands record policy
355 settings when they are created and use the pre-record policies when
356 they are invoked. If the function or macro implementation sets poli‐
357 cies, the changes automatically propagate up through callers until they
358 reach the closest nested policy stack entry.
359 configure_file
361 Copy a file to another location and modify its contents.
362 configure_file(<input> <output>
364 [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
365 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
366 Copies an <input> file to an <output> file and substitutes variable
368 values referenced as @VAR@ or ${VAR} in the input file content. Each
369 variable reference will be replaced with the current value of the vari‐
370 able, or the empty string if the variable is not defined. Furthermore,
371 input lines of the form
372 #cmakedefine VAR ...
374 will be replaced with either
376 #define VAR ...
378 or
380 /* #undef VAR */
382 depending on whether VAR is set in CMake to any value not considered a
384 false constant by the if() command. The “…” content on the line after
385 the variable name, if any, is processed as above. Input file lines of
386 the form #cmakedefine01 VAR will be replaced with either #define VAR 1
387 or #define VAR 0 similarly. The result lines (with the exception of
388 the #undef comments) can be indented using spaces and/or tabs between
389 the # character and the cmakedefine or cmakedefine01 words. This white‐
390 space indentation will be preserved in the output lines:
391 # cmakedefine VAR
393 # cmakedefine01 VAR
394 will be replaced, if VAR is defined, with
396 # define VAR
398 # define VAR 1
399 If the input file is modified the build system will re-run CMake to
401 re-configure the file and generate the build system again. The gener‐
402 ated file is modified and its timestamp updated on subsequent cmake
403 runs only if its content is changed.
404 The arguments are:
406 <input>
408 Path to the input file. A relative path is treated with respect
409 to the value of CMAKE_CURRENT_SOURCE_DIR. The input path must
410 be a file, not a directory.
411 <output>
413 Path to the output file or directory. A relative path is
414 treated with respect to the value of CMAKE_CURRENT_BINARY_DIR.
415 If the path names an existing directory the output file is
416 placed in that directory with the same file name as the input
417 file.
418 COPYONLY
420 Copy the file without replacing any variable references or other
421 content. This option may not be used with NEWLINE_STYLE.
422 ESCAPE_QUOTES
424 Escape any substituted quotes with backslashes (C-style).
425 @ONLY Restrict variable replacement to references of the form @VAR@.
427 This is useful for configuring scripts that use ${VAR} syntax.
428 NEWLINE_STYLE <style>
430 Specify the newline style for the output file. Specify UNIX or
431 LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n new‐
432 lines. This option may not be used with COPYONLY.
433 Example
435 Consider a source tree containing a foo.h.in file:
436 #cmakedefine FOO_ENABLE
438 #cmakedefine FOO_STRING "@FOO_STRING@"
439 An adjacent CMakeLists.txt may use configure_file to configure the
441 header:
442 option(FOO_ENABLE "Enable Foo" ON)
444 if(FOO_ENABLE)
445 set(FOO_STRING "foo")
446 endif()
447 configure_file(foo.h.in foo.h @ONLY)
448 This creates a foo.h in the build directory corresponding to this
450 source directory. If the FOO_ENABLE option is on, the configured file
451 will contain:
452 #define FOO_ENABLE
454 #define FOO_STRING "foo"
455 Otherwise it will contain:
457 /* #undef FOO_ENABLE */
459 /* #undef FOO_STRING */
460 One may then use the include_directories() command to specify the out‐
462 put directory as an include directory:
463 include_directories(${CMAKE_CURRENT_BINARY_DIR})
465 so that sources may include the header as #include <foo.h>.
467 continue
469 Continue to the top of enclosing foreach or while loop.
470 continue()
472 The continue command allows a cmake script to abort the rest of a block
474 in a foreach() or while() loop, and start at the top of the next itera‐
475 tion.
476 See also the break() command.
478 else
480 Starts the else portion of an if block.
481 else([<condition>])
483 See the if() command.
485 elseif
487 Starts an elseif portion of an if block.
488 elseif(<condition>)
490 See the if() command, especially for the syntax and logic of the <con‐
492 dition>.
493 endforeach
495 Ends a list of commands in a foreach block.
496 endforeach([<loop_var>])
498 See the foreach() command.
500 The optional <loop_var> argument is supported for backward compatibil‐
502 ity only. If used it must be a verbatim repeat of the <loop_var> argu‐
503 ment of the opening foreach clause.
504 endfunction
506 Ends a list of commands in a function block.
507 endfunction([<name>])
509 See the function() command.
511 The optional <name> argument is supported for backward compatibility
513 only. If used it must be a verbatim repeat of the <name> argument of
514 the opening function command.
515 endif
517 Ends a list of commands in an if block.
518 endif([<condition>])
520 See the if() command.
522 The optional <condition> argument is supported for backward compatibil‐
524 ity only. If used it must be a verbatim repeat of the argument of the
525 opening if clause.
526 endmacro
528 Ends a list of commands in a macro block.
529 endmacro([<name>])
531 See the macro() command.
533 The optional <name> argument is supported for backward compatibility
535 only. If used it must be a verbatim repeat of the <name> argument of
536 the opening macro command.
537 endwhile
539 Ends a list of commands in a while block.
540 endwhile([<condition>])
542 See the while() command.
544 The optional <condition> argument is supported for backward compatibil‐
546 ity only. If used it must be a verbatim repeat of the argument of the
547 opening while clause.
548 execute_process
550 Execute one or more child processes.
551 execute_process(COMMAND <cmd1> [<arguments>]
553 [COMMAND <cmd2> [<arguments>]]...
554 [WORKING_DIRECTORY <directory>]
555 [TIMEOUT <seconds>]
556 [RESULT_VARIABLE <variable>]
557 [RESULTS_VARIABLE <variable>]
558 [OUTPUT_VARIABLE <variable>]
559 [ERROR_VARIABLE <variable>]
560 [INPUT_FILE <file>]
561 [OUTPUT_FILE <file>]
562 [ERROR_FILE <file>]
563 [OUTPUT_QUIET]
564 [ERROR_QUIET]
565 [COMMAND_ECHO <where>]
566 [OUTPUT_STRIP_TRAILING_WHITESPACE]
567 [ERROR_STRIP_TRAILING_WHITESPACE]
568 [ENCODING <name>])
569 Runs the given sequence of one or more commands.
571 Commands are executed concurrently as a pipeline, with the standard
573 output of each process piped to the standard input of the next. A sin‐
574 gle standard error pipe is used for all processes.
575 Options:
577 COMMAND
579 A child process command line.
580 CMake executes the child process using operating system APIs
582 directly. All arguments are passed VERBATIM to the child
583 process. No intermediate shell is used, so shell operators such
584 as > are treated as normal arguments. (Use the INPUT_*, OUT‐
585 PUT_*, and ERROR_* options to redirect stdin, stdout, and
586 stderr.)
587 If a sequential execution of multiple commands is required, use
589 multiple execute_process() calls with a single COMMAND argument.
590 WORKING_DIRECTORY
592 The named directory will be set as the current working directory
593 of the child processes.
594 TIMEOUT
596 After the specified number of seconds (fractions allowed), all
597 unfinished child processes will be terminated, and the
598 RESULT_VARIABLE will be set to a string mentioning the “time‐
599 out”.
600 RESULT_VARIABLE
602 The variable will be set to contain the result of last child
603 process. This will be an integer return code from the last
604 child or a string describing an error condition.
605 RESULTS_VARIABLE <variable>
607 The variable will be set to contain the result of all processes
608 as a semicolon-separated list, in order of the given COMMAND
609 arguments. Each entry will be an integer return code from the
610 corresponding child or a string describing an error condition.
611 OUTPUT_VARIABLE, ERROR_VARIABLE
613 The variable named will be set with the contents of the standard
614 output and standard error pipes, respectively. If the same
615 variable is named for both pipes their output will be merged in
616 the order produced.
617 INPUT_FILE, OUTPUT_FILE, ERROR_FILE
619 The file named will be attached to the standard input of the
620 first process, standard output of the last process, or standard
621 error of all processes, respectively. If the same file is named
622 for both output and error then it will be used for both.
623 OUTPUT_QUIET, ERROR_QUIET
625 The standard output or standard error results will be quietly
626 ignored.
627 COMMAND_ECHO <where>
629 The command being run will be echo’ed to <where> with <where>
630 being set to one of STDERR, STDOUT or NONE. See the CMAKE_EXE‐
631 CUTE_PROCESS_COMMAND_ECHO variable for a way to control the
632 default behavior when this option is not present.
633 ENCODING <name>
635 On Windows, the encoding that is used to decode output from the
636 process. Ignored on other platforms. Valid encoding names are:
637 NONE Perform no decoding. This assumes that the process out‐
639 put is encoded in the same way as CMake’s internal encod‐
640 ing (UTF-8). This is the default.
641 AUTO Use the current active console’s codepage or if that
643 isn’t available then use ANSI.
644 ANSI Use the ANSI codepage.
646 OEM Use the original equipment manufacturer (OEM) code page.
648 UTF8 or UTF-8
650 Use the UTF-8 codepage. Prior to CMake 3.11.0, only UTF8
651 was accepted for this encoding. In CMake 3.11.0, UTF-8
652 was added for consistency with the UTF-8 RFC naming con‐
653 vention.
654 If more than one OUTPUT_* or ERROR_* option is given for the same pipe
656 the precedence is not specified. If no OUTPUT_* or ERROR_* options are
657 given the output will be shared with the corresponding pipes of the
658 CMake process itself.
659 The execute_process() command is a newer more powerful version of
661 exec_program(), but the old command has been kept for compatibility.
662 Both commands run while CMake is processing the project prior to build
663 system generation. Use add_custom_target() and add_custom_command() to
664 create custom commands that run at build time.
665 file
667 File manipulation command.
668 Synopsis
670 Reading
671 file(READ <filename> <out-var> [...])
672 file(STRINGS <filename> <out-var> [...])
673 file(<HASH> <filename> <out-var>)
674 file(TIMESTAMP <filename> <out-var> [...])
675 file(GET_RUNTIME_DEPENDENCIES [...])
676 Writing
678 file({WRITE | APPEND} <filename> <content>...)
679 file({TOUCH | TOUCH_NOCREATE} [<file>...])
680 file(GENERATE OUTPUT <output-file> [...])
681 Filesystem
683 file({GLOB | GLOB_RECURSE} <out-var> [...] [<globbing-expr>...])
684 file(RENAME <oldname> <newname>)
685 file({REMOVE | REMOVE_RECURSE } [<files>...])
686 file(MAKE_DIRECTORY [<dir>...])
687 file({COPY | INSTALL} <file>... DESTINATION <dir> [...])
688 file(SIZE <filename> <out-var>)
689 file(READ_SYMLINK <linkname> <out-var>)
690 file(CREATE_LINK <original> <linkname> [...])
691 Path Conversion
693 file(RELATIVE_PATH <out-var> <directory> <file>)
694 file({TO_CMAKE_PATH | TO_NATIVE_PATH} <path> <out-var>)
695 Transfer
697 file(DOWNLOAD <url> <file> [...])
698 file(UPLOAD <file> <url> [...])
699 Locking
701 file(LOCK <path> [...])
702 Reading
704 file(READ <filename> <variable>
705 [OFFSET <offset>] [LIMIT <max-in>] [HEX])
706 Read content from a file called <filename> and store it in a <vari‐
708 able>. Optionally start from the given <offset> and read at most
709 <max-in> bytes. The HEX option causes data to be converted to a hexa‐
710 decimal representation (useful for binary data).
711 file(STRINGS <filename> <variable> [<options>...])
713 Parse a list of ASCII strings from <filename> and store it in <vari‐
715 able>. Binary data in the file are ignored. Carriage return (\r, CR)
716 characters are ignored. The options are:
717 LENGTH_MAXIMUM <max-len>
719 Consider only strings of at most a given length.
720 LENGTH_MINIMUM <min-len>
722 Consider only strings of at least a given length.
723 LIMIT_COUNT <max-num>
725 Limit the number of distinct strings to be extracted.
726 LIMIT_INPUT <max-in>
728 Limit the number of input bytes to read from the file.
729 LIMIT_OUTPUT <max-out>
731 Limit the number of total bytes to store in the <variable>.
732 NEWLINE_CONSUME
734 Treat newline characters (\n, LF) as part of string content
735 instead of terminating at them.
736 NO_HEX_CONVERSION
738 Intel Hex and Motorola S-record files are automatically con‐
739 verted to binary while reading unless this option is given.
740 REGEX <regex>
742 Consider only strings that match the given regular expression.
743 ENCODING <encoding-type>
745 Consider strings of a given encoding. Currently supported
746 encodings are: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE.
747 If the ENCODING option is not provided and the file has a Byte
748 Order Mark, the ENCODING option will be defaulted to respect the
749 Byte Order Mark.
750 For example, the code
752 file(STRINGS myfile.txt myfile)
754 stores a list in the variable myfile in which each item is a line from
756 the input file.
757 file(<HASH> <filename> <variable>)
759 Compute a cryptographic hash of the content of <filename> and store it
761 in a <variable>. The supported <HASH> algorithm names are those listed
762 by the string(<HASH>) command.
763 file(TIMESTAMP <filename> <variable> [<format>] [UTC])
765 Compute a string representation of the modification time of <filename>
767 and store it in <variable>. Should the command be unable to obtain a
768 timestamp variable will be set to the empty string (“”).
769 See the string(TIMESTAMP) command for documentation of the <format> and
771 UTC options.
772 file(GET_RUNTIME_DEPENDENCIES
774 [RESOLVED_DEPENDENCIES_VAR <deps_var>]
775 [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
776 [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
777 [EXECUTABLES [<executable_files>...]]
778 [LIBRARIES [<library_files>...]]
779 [MODULES [<module_files>...]]
780 [DIRECTORIES [<directories>...]]
781 [BUNDLE_EXECUTABLE <bundle_executable_file>]
782 [PRE_INCLUDE_REGEXES [<regexes>...]]
783 [PRE_EXCLUDE_REGEXES [<regexes>...]]
784 [POST_INCLUDE_REGEXES [<regexes>...]]
785 [POST_EXCLUDE_REGEXES [<regexes>...]]
786 )
787 Recursively get the list of libraries depended on by the given files.
789 Please note that this sub-command is not intended to be used in project
791 mode. Instead, use it in an install(CODE) or install(SCRIPT) block.
792 For example:
793 install(CODE [[
795 file(GET_RUNTIME_DEPENDENCIES
796 # ...
797 )
798 ]])
799 The arguments are as follows:
801 RESOLVED_DEPENDENCIES_VAR <deps_var>
803 Name of the variable in which to store the list of resolved
804 dependencies.
805 UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>
807 Name of the variable in which to store the list of unresolved
808 dependencies. If this variable is not specified, and there are
809 any unresolved dependencies, an error is issued.
810 CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>
812 Variable prefix in which to store conflicting dependency infor‐
813 mation. Dependencies are conflicting if two files with the same
814 name are found in two different directories. The list of file‐
815 names that conflict are stored in <conflicting_deps_pre‐
816 fix>_FILENAMES. For each filename, the list of paths that were
817 found for that filename are stored in <conflicting_deps_pre‐
818 fix>_<filename>.
819 EXECUTABLES <executable_files>
821 List of executable files to read for dependencies. These are
822 executables that are typically created with add_executable(),
823 but they do not have to be created by CMake. On Apple platforms,
824 the paths to these files determine the value of @executable_path
825 when recursively resolving the libraries. Specifying any kind
826 of library (STATIC, MODULE, or SHARED) here will result in unde‐
827 fined behavior.
828 LIBRARIES <library_files>
830 List of library files to read for dependencies. These are
831 libraries that are typically created with add_library(SHARED),
832 but they do not have to be created by CMake. Specifying STATIC
833 libraries, MODULE libraries, or executables here will result in
834 undefined behavior.
835 MODULES <module_files>
837 List of loadable module files to read for dependencies. These
838 are modules that are typically created with add_library(MODULE),
839 but they do not have to be created by CMake. They are typically
840 used by calling dlopen() at runtime rather than linked at link
841 time with ld -l. Specifying STATIC libraries, SHARED libraries,
842 or executables here will result in undefined behavior.
843 DIRECTORIES <directories>
845 List of additional directories to search for dependencies. On
846 Linux platforms, these directories are searched if the depen‐
847 dency is not found in any of the other usual paths. If it is
848 found in such a directory, a warning is issued, because it means
849 that the file is incomplete (it does not list all of the direc‐
850 tories that contain its dependencies). On Windows platforms,
851 these directories are searched if the dependency is not found in
852 any of the other search paths, but no warning is issued, because
853 searching other paths is a normal part of Windows dependency
854 resolution. On Apple platforms, this argument has no effect.
855 BUNDLE_EXECUTABLE <bundle_executable_file>
857 Executable to treat as the “bundle executable” when resolving
858 libraries. On Apple platforms, this argument determines the
859 value of @executable_path when recursively resolving libraries
860 for LIBRARIES and MODULES files. It has no effect on EXECUTA‐
861 BLES files. On other platforms, it has no effect. This is typi‐
862 cally (but not always) one of the executables in the EXECUTABLES
863 argument which designates the “main” executable of the package.
864 The following arguments specify filters for including or excluding
866 libraries to be resolved. See below for a full description of how they
867 work.
868 PRE_INCLUDE_REGEXES <regexes>
870 List of pre-include regexes through which to filter the names of
871 not-yet-resolved dependencies.
872 PRE_EXCLUDE_REGEXES <regexes>
874 List of pre-exclude regexes through which to filter the names of
875 not-yet-resolved dependencies.
876 POST_INCLUDE_REGEXES <regexes>
878 List of post-include regexes through which to filter the names
879 of resolved dependencies.
880 POST_EXCLUDE_REGEXES <regexes>
882 List of post-exclude regexes through which to filter the names
883 of resolved dependencies.
884 These arguments can be used to blacklist unwanted system libraries when
886 resolving the dependencies, or to whitelist libraries from a specific
887 directory. The filtering works as follows:
888 1. If the not-yet-resolved dependency matches any of the
890 PRE_INCLUDE_REGEXES, steps 2 and 3 are skipped, and the dependency
891 resolution proceeds to step 4.
892 2. If the not-yet-resolved dependency matches any of the
894 PRE_EXCLUDE_REGEXES, dependency resolution stops for that depen‐
895 dency.
896 3. Otherwise, dependency resolution proceeds.
898 4. file(GET_RUNTIME_DEPENDENCIES) searches for the dependency according
900 to the linking rules of the platform (see below).
901 5. If the dependency is found, and its full path matches one of the
903 POST_INCLUDE_REGEXES, the full path is added to the resolved depen‐
904 dencies, and file(GET_RUNTIME_DEPENDENCIES) recursively resolves
905 that library’s own dependencies. Otherwise, resolution proceeds to
906 step 6.
907 6. If the dependency is found, but its full path matches one of the
909 POST_EXCLUDE_REGEXES, it is not added to the resolved dependencies,
910 and dependency resolution stops for that dependency.
911 7. If the dependency is found, and its full path does not match either
913 POST_INCLUDE_REGEXES or POST_EXCLUDE_REGEXES, the full path is added
914 to the resolved dependencies, and file(GET_RUNTIME_DEPENDENCIES)
915 recursively resolves that library’s own dependencies.
916 Different platforms have different rules for how dependencies are
918 resolved. These specifics are described here.
919 On Linux platforms, library resolution works as follows:
921 1. If the depending file does not have any RUNPATH entries, and the
923 library exists in one of the depending file’s RPATH entries, or its
924 parents’, in that order, the dependency is resolved to that file.
925 2. Otherwise, if the depending file has any RUNPATH entries, and the
927 library exists in one of those entries, the dependency is resolved
928 to that file.
929 3. Otherwise, if the library exists in one of the directories listed by
931 ldconfig, the dependency is resolved to that file.
932 4. Otherwise, if the library exists in one of the DIRECTORIES entries,
934 the dependency is resolved to that file. In this case, a warning is
935 issued, because finding a file in one of the DIRECTORIES means that
936 the depending file is not complete (it does not list all the direc‐
937 tories from which it pulls dependencies).
938 5. Otherwise, the dependency is unresolved.
940 On Windows platforms, library resolution works as follows:
942 1. The dependent DLL name is converted to lowercase. Windows DLL names
944 are case-insensitive, and some linkers mangle the case of the DLL
945 dependency names. However, this makes it more difficult for
946 PRE_INCLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, and
947 POST_EXCLUDE_REGEXES to properly filter DLL names - every regex
948 would have to check for both uppercase and lowercase letters. For
949 example:
950 file(GET_RUNTIME_DEPENDENCIES
952 # ...
953 PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
954 )
955 Converting the DLL name to lowercase allows the regexes to only
957 match lowercase names, thus simplifying the regex. For example:
958 file(GET_RUNTIME_DEPENDENCIES
960 # ...
961 PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
962 )
963 This regex will match mylibrary.dll regardless of how it is cased,
965 either on disk or in the depending file. (For example, it will match
966 mylibrary.dll, MyLibrary.dll, and MYLIBRARY.DLL.)
967 Please note that the directory portion of any resolved DLLs retains
969 its casing and is not converted to lowercase. Only the filename por‐
970 tion is converted.
971 2. (Not yet implemented) If the depending file is a Windows Store app,
973 and the dependency is listed as a dependency in the application’s
974 package manifest, the dependency is resolved to that file.
975 3. Otherwise, if the library exists in the same directory as the
977 depending file, the dependency is resolved to that file.
978 4. Otherwise, if the library exists in either the operating system’s
980 system32 directory or the Windows directory, in that order, the
981 dependency is resolved to that file.
982 5. Otherwise, if the library exists in one of the directories specified
984 by DIRECTORIES, in the order they are listed, the dependency is
985 resolved to that file. In this case, a warning is not issued,
986 because searching other directories is a normal part of Windows
987 library resolution.
988 6. Otherwise, the dependency is unresolved.
990 On Apple platforms, library resolution works as follows:
992 1. If the dependency starts with @executable_path/, and an EXECUTABLES
994 argument is in the process of being resolved, and replacing @exe‐
995 cutable_path/ with the directory of the executable yields an exist‐
996 ing file, the dependency is resolved to that file.
997 2. Otherwise, if the dependency starts with @executable_path/, and
999 there is a BUNDLE_EXECUTABLE argument, and replacing @exe‐
1000 cutable_path/ with the directory of the bundle executable yields an
1001 existing file, the dependency is resolved to that file.
1002 3. Otherwise, if the dependency starts with @loader_path/, and replac‐
1004 ing @loader_path/ with the directory of the depending file yields an
1005 existing file, the dependency is resolved to that file.
1006 4. Otherwise, if the dependency starts with @rpath/, and replacing
1008 @rpath/ with one of the RPATH entries of the depending file yields
1009 an existing file, the dependency is resolved to that file. Note that
1010 RPATH entries that start with @executable_path/ or @loader_path/
1011 also have these items replaced with the appropriate path.
1012 5. Otherwise, if the dependency is an absolute file that exists, the
1014 dependency is resolved to that file.
1015 6. Otherwise, the dependency is unresolved.
1017 This function accepts several variables that determine which tool is
1019 used for dependency resolution:
1020 CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM
1022 Determines which operating system and executable format the
1023 files are built for. This could be one of several values:
1024 · linux+elf
1026 · windows+pe
1028 · macos+macho
1030 If this variable is not specified, it is determined automati‐
1032 cally by system introspection.
1033 CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
1035 Determines the tool to use for dependency resolution. It could
1036 be one of several values, depending on the value of
1037 CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM:
1038 ┌─────────────────────────┬──────────────────────────┐
1040 │CMAKE_GET_RUNTIME_DEPEN‐ │ CMAKE_GET_RUNTIME_DEPEN‐ │
1041 │DENCIES_PLATFORM │ DENCIES_TOOL │
1042 ├─────────────────────────┼──────────────────────────┤
1043 │linux+elf │ objdump │
1044 ├─────────────────────────┼──────────────────────────┤
1045 │windows+pe │ dumpbin │
1046 ├─────────────────────────┼──────────────────────────┤
1047 │windows+pe │ objdump │
1048 ├─────────────────────────┼──────────────────────────┤
1049 │macos+macho │ otool │
1050 └─────────────────────────┴──────────────────────────┘
1051 If this variable is not specified, it is determined automati‐
1053 cally by system introspection.
1054 CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND
1056 Determines the path to the tool to use for dependency resolu‐
1057 tion. This is the actual path to objdump, dumpbin, or otool.
1058 If this variable is not specified, it is determined automati‐
1060 cally by system introspection.
1061 Writing
1063 file(WRITE <filename> <content>...)
1064 file(APPEND <filename> <content>...)
1065 Write <content> into a file called <filename>. If the file does not
1067 exist, it will be created. If the file already exists, WRITE mode will
1068 overwrite it and APPEND mode will append to the end. Any directories
1069 in the path specified by <filename> that do not exist will be created.
1070 If the file is a build input, use the configure_file() command to
1072 update the file only when its content changes.
1073 file(TOUCH [<files>...])
1075 file(TOUCH_NOCREATE [<files>...])
1076 Create a file with no content if it does not yet exist. If the file
1078 already exists, its access and/or modification will be updated to the
1079 time when the function call is executed.
1080 Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a
1082 file does not exist it will be silently ignored.
1083 With TOUCH and TOUCH_NOCREATE the contents of an existing file will not
1085 be modified.
1086 file(GENERATE OUTPUT output-file
1088 <INPUT input-file|CONTENT content>
1089 [CONDITION expression])
1090 Generate an output file for each build configuration supported by the
1092 current CMake Generator. Evaluate generator expressions from the input
1093 content to produce the output content. The options are:
1094 CONDITION <condition>
1096 Generate the output file for a particular configuration only if
1097 the condition is true. The condition must be either 0 or 1
1098 after evaluating generator expressions.
1099 CONTENT <content>
1101 Use the content given explicitly as input.
1102 INPUT <input-file>
1104 Use the content from a given file as input. A relative path is
1105 treated with respect to the value of CMAKE_CURRENT_SOURCE_DIR.
1106 See policy CMP0070.
1107 OUTPUT <output-file>
1109 Specify the output file name to generate. Use generator expres‐
1110 sions such as $<CONFIG> to specify a configuration-specific out‐
1111 put file name. Multiple configurations may generate the same
1112 output file only if the generated content is identical. Other‐
1113 wise, the <output-file> must evaluate to an unique name for each
1114 configuration. A relative path (after evaluating generator
1115 expressions) is treated with respect to the value of CMAKE_CUR‐
1116 RENT_BINARY_DIR. See policy CMP0070.
1117 Exactly one CONTENT or INPUT option must be given. A specific OUTPUT
1119 file may be named by at most one invocation of file(GENERATE). Gener‐
1120 ated files are modified and their timestamp updated on subsequent cmake
1121 runs only if their content is changed.
1122 Note also that file(GENERATE) does not create the output file until the
1124 generation phase. The output file will not yet have been written when
1125 the file(GENERATE) command returns, it is written only after processing
1126 all of a project’s CMakeLists.txt files.
1127 Filesystem
1129 file(GLOB <variable>
1130 [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
1131 [<globbing-expressions>...])
1132 file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
1133 [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
1134 [<globbing-expressions>...])
1135 Generate a list of files that match the <globbing-expressions> and
1137 store it into the <variable>. Globbing expressions are similar to reg‐
1138 ular expressions, but much simpler. If RELATIVE flag is specified, the
1139 results will be returned as relative paths to the given path. The
1140 results will be ordered lexicographically.
1141 On Windows and macOS, globbing is case-insensitive even if the underly‐
1143 ing filesystem is case-sensitive (both filenames and globbing expres‐
1144 sions are converted to lowercase before matching). On other platforms,
1145 globbing is case-sensitive.
1146 If the CONFIGURE_DEPENDS flag is specified, CMake will add logic to the
1148 main build system check target to rerun the flagged GLOB commands at
1149 build time. If any of the outputs change, CMake will regenerate the
1150 build system.
1151 By default GLOB lists directories - directories are omitted in result
1153 if LIST_DIRECTORIES is set to false.
1154 NOTE:
1156 We do not recommend using GLOB to collect a list of source files
1157 from your source tree. If no CMakeLists.txt file changes when a
1158 source is added or removed then the generated build system cannot
1159 know when to ask CMake to regenerate. The CONFIGURE_DEPENDS flag
1160 may not work reliably on all generators, or if a new generator is
1161 added in the future that cannot support it, projects using it will
1162 be stuck. Even if CONFIGURE_DEPENDS works reliably, there is still a
1163 cost to perform the check on every rebuild.
1164 Examples of globbing expressions include:
1166 *.cxx - match all files with extension cxx
1168 *.vt? - match all files with extension vta,...,vtz
1169 f[3-5].txt - match files f3.txt, f4.txt, f5.txt
1170 The GLOB_RECURSE mode will traverse all the subdirectories of the
1172 matched directory and match the files. Subdirectories that are sym‐
1173 links are only traversed if FOLLOW_SYMLINKS is given or policy CMP0009
1174 is not set to NEW.
1175 By default GLOB_RECURSE omits directories from result list - setting
1177 LIST_DIRECTORIES to true adds directories to result list. If FOL‐
1178 LOW_SYMLINKS is given or policy CMP0009 is not set to OLD then
1179 LIST_DIRECTORIES treats symlinks as directories.
1180 Examples of recursive globbing include:
1182 /dir/*.py - match all python files in /dir and subdirectories
1184 file(RENAME <oldname> <newname>)
1186 Move a file or directory within a filesystem from <oldname> to <new‐
1188 name>, replacing the destination atomically.
1189 file(REMOVE [<files>...])
1191 file(REMOVE_RECURSE [<files>...])
1192 Remove the given files. The REMOVE_RECURSE mode will remove the given
1194 files and directories, also non-empty directories. No error is emitted
1195 if a given file does not exist. Relative input paths are evaluated
1196 with respect to the current source directory. Empty input paths are
1197 ignored with a warning.
1198 file(MAKE_DIRECTORY [<directories>...])
1200 Create the given directories and their parents as needed.
1202 file(<COPY|INSTALL> <files>... DESTINATION <dir>
1204 [FILE_PERMISSIONS <permissions>...]
1205 [DIRECTORY_PERMISSIONS <permissions>...]
1206 [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
1207 [FOLLOW_SYMLINK_CHAIN]
1208 [FILES_MATCHING]
1209 [[PATTERN <pattern> | REGEX <regex>]
1210 [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
1211 The COPY signature copies files, directories, and symlinks to a desti‐
1213 nation folder. Relative input paths are evaluated with respect to the
1214 current source directory, and a relative destination is evaluated with
1215 respect to the current build directory. Copying preserves input file
1216 timestamps, and optimizes out a file if it exists at the destination
1217 with the same timestamp. Copying preserves input permissions unless
1218 explicit permissions or NO_SOURCE_PERMISSIONS are given (default is
1219 USE_SOURCE_PERMISSIONS).
1220 If FOLLOW_SYMLINK_CHAIN is specified, COPY will recursively resolve the
1222 symlinks at the paths given until a real file is found, and install a
1223 corresponding symlink in the destination for each symlink encountered.
1224 For each symlink that is installed, the resolution is stripped of the
1225 directory, leaving only the filename, meaning that the new symlink
1226 points to a file in the same directory as the symlink. This feature is
1227 useful on some Unix systems, where libraries are installed as a chain
1228 of symlinks with version numbers, with less specific versions pointing
1229 to more specific versions. FOLLOW_SYMLINK_CHAIN will install all of
1230 these symlinks and the library itself into the destination directory.
1231 For example, if you have the following directory structure:
1232 · /opt/foo/lib/libfoo.so.1.2.3
1234 · /opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3
1236 · /opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2
1238 · /opt/foo/lib/libfoo.so -> libfoo.so.1
1240 and you do:
1242 file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)
1244 This will install all of the symlinks and libfoo.so.1.2.3 itself into
1246 lib.
1247 See the install(DIRECTORY) command for documentation of permissions,
1249 FILES_MATCHING, PATTERN, REGEX, and EXCLUDE options. Copying directo‐
1250 ries preserves the structure of their content even if options are used
1251 to select a subset of files.
1252 The INSTALL signature differs slightly from COPY: it prints status mes‐
1254 sages (subject to the CMAKE_INSTALL_MESSAGE variable), and
1255 NO_SOURCE_PERMISSIONS is default. Installation scripts generated by
1256 the install() command use this signature (with some undocumented
1257 options for internal use).
1258 file(SIZE <filename> <variable>)
1260 Determine the file size of the <filename> and put the result in <vari‐
1262 able> variable. Requires that <filename> is a valid path pointing to a
1263 file and is readable.
1264 file(READ_SYMLINK <linkname> <variable>)
1266 This subcommand queries the symlink <linkname> and stores the path it
1268 points to in the result <variable>. If <linkname> does not exist or is
1269 not a symlink, CMake issues a fatal error.
1270 Note that this command returns the raw symlink path and does not
1272 resolve a relative path. The following is an example of how to ensure
1273 that an absolute path is obtained:
1274 set(linkname "/path/to/foo.sym")
1276 file(READ_SYMLINK "${linkname}" result)
1277 if(NOT IS_ABSOLUTE "${result}")
1278 get_filename_component(dir "${linkname}" DIRECTORY)
1279 set(result "${dir}/${result}")
1280 endif()
1281 file(CREATE_LINK <original> <linkname>
1283 [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])
1284 Create a link <linkname> that points to <original>. It will be a hard
1286 link by default, but providing the SYMBOLIC option results in a sym‐
1287 bolic link instead. Hard links require that original exists and is a
1288 file, not a directory. If <linkname> already exists, it will be over‐
1289 written.
1290 The <result> variable, if specified, receives the status of the opera‐
1292 tion. It is set to 0 upon success or an error message otherwise. If
1293 RESULT is not specified and the operation fails, a fatal error is emit‐
1294 ted.
1295 Specifying COPY_ON_ERROR enables copying the file as a fallback if cre‐
1297 ating the link fails. It can be useful for handling situations such as
1298 <original> and <linkname> being on different drives or mount points,
1299 which would make them unable to support a hard link.
1300 Path Conversion
1302 file(RELATIVE_PATH <variable> <directory> <file>)
1303 Compute the relative path from a <directory> to a <file> and store it
1305 in the <variable>.
1306 file(TO_CMAKE_PATH "<path>" <variable>)
1308 file(TO_NATIVE_PATH "<path>" <variable>)
1309 The TO_CMAKE_PATH mode converts a native <path> into a cmake-style path
1311 with forward-slashes (/). The input can be a single path or a system
1312 search path like $ENV{PATH}. A search path will be converted to a
1313 cmake-style list separated by ; characters.
1314 The TO_NATIVE_PATH mode converts a cmake-style <path> into a native
1316 path with platform-specific slashes (\ on Windows and / elsewhere).
1317 Always use double quotes around the <path> to be sure it is treated as
1319 a single argument to this command.
1320 Transfer
1322 file(DOWNLOAD <url> <file> [<options>...])
1323 file(UPLOAD <file> <url> [<options>...])
1324 The DOWNLOAD mode downloads the given <url> to a local <file>. The
1326 UPLOAD mode uploads a local <file> to a given <url>.
1327 Options to both DOWNLOAD and UPLOAD are:
1329 INACTIVITY_TIMEOUT <seconds>
1331 Terminate the operation after a period of inactivity.
1332 LOG <variable>
1334 Store a human-readable log of the operation in a variable.
1335 SHOW_PROGRESS
1337 Print progress information as status messages until the opera‐
1338 tion is complete.
1339 STATUS <variable>
1341 Store the resulting status of the operation in a variable. The
1342 status is a ; separated list of length 2. The first element is
1343 the numeric return value for the operation, and the second ele‐
1344 ment is a string value for the error. A 0 numeric error means
1345 no error in the operation.
1346 TIMEOUT <seconds>
1348 Terminate the operation after a given total time has elapsed.
1349 USERPWD <username>:<password>
1351 Set username and password for operation.
1352 HTTPHEADER <HTTP-header>
1354 HTTP header for operation. Suboption can be repeated several
1355 times.
1356 NETRC <level>
1358 Specify whether the .netrc file is to be used for operation. If
1359 this option is not specified, the value of the CMAKE_NETRC vari‐
1360 able will be used instead. Valid levels are:
1361 IGNORED
1363 The .netrc file is ignored. This is the default.
1364 OPTIONAL
1366 The .netrc file is optional, and information in the URL
1367 is preferred. The file will be scanned to find which
1368 ever information is not specified in the URL.
1369 REQUIRED
1371 The .netrc file is required, and information in the URL
1372 is ignored.
1373 NETRC_FILE <file>
1375 Specify an alternative .netrc file to the one in your home
1376 directory, if the NETRC level is OPTIONAL or REQUIRED. If this
1377 option is not specified, the value of the CMAKE_NETRC_FILE vari‐
1378 able will be used instead.
1379 If neither NETRC option is given CMake will check variables CMAKE_NETRC
1381 and CMAKE_NETRC_FILE, respectively.
1382 Additional options to DOWNLOAD are:
1384 EXPECTED_HASH ALGO=<value>
1386 Verify that the downloaded content hash matches the expected value,
1387 where ALGO is one of the algorithms supported by file(<HASH>). If
1388 it does not match, the operation fails with an error.
1389 EXPECTED_MD5 <value>
1391 Historical short-hand for EXPECTED_HASH MD5=<value>.
1392 TLS_VERIFY <ON|OFF>
1394 Specify whether to verify the server certificate for https://
1395 URLs. The default is to not verify.
1396 TLS_CAINFO <file>
1398 Specify a custom Certificate Authority file for https:// URLs.
1399 For https:// URLs CMake must be built with OpenSSL support. TLS/SSL
1401 certificates are not checked by default. Set TLS_VERIFY to ON to check
1402 certificates and/or use EXPECTED_HASH to verify downloaded content. If
1403 neither TLS option is given CMake will check variables CMAKE_TLS_VERIFY
1404 and CMAKE_TLS_CAINFO, respectively.
1405 Locking
1407 file(LOCK <path> [DIRECTORY] [RELEASE]
1408 [GUARD <FUNCTION|FILE|PROCESS>]
1409 [RESULT_VARIABLE <variable>]
1410 [TIMEOUT <seconds>])
1411 Lock a file specified by <path> if no DIRECTORY option present and file
1413 <path>/cmake.lock otherwise. File will be locked for scope defined by
1414 GUARD option (default value is PROCESS). RELEASE option can be used to
1415 unlock file explicitly. If option TIMEOUT is not specified CMake will
1416 wait until lock succeed or until fatal error occurs. If TIMEOUT is set
1417 to 0 lock will be tried once and result will be reported immediately.
1418 If TIMEOUT is not 0 CMake will try to lock file for the period speci‐
1419 fied by <seconds> value. Any errors will be interpreted as fatal if
1420 there is no RESULT_VARIABLE option. Otherwise result will be stored in
1421 <variable> and will be 0 on success or error message on failure.
1422 Note that lock is advisory - there is no guarantee that other processes
1424 will respect this lock, i.e. lock synchronize two or more CMake
1425 instances sharing some modifiable resources. Similar logic applied to
1426 DIRECTORY option - locking parent directory doesn’t prevent other LOCK
1427 commands to lock any child directory or file.
1428 Trying to lock file twice is not allowed. Any intermediate directories
1430 and file itself will be created if they not exist. GUARD and TIMEOUT
1431 options ignored on RELEASE operation.
1432 find_file
1434 A short-hand signature is:
1435 find_file (<VAR> name1 [path1 path2 ...])
1437 The general signature is:
1439 find_file (
1441 <VAR>
1442 name | NAMES name1 [name2 ...]
1443 [HINTS path1 [path2 ... ENV var]]
1444 [PATHS path1 [path2 ... ENV var]]
1445 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1446 [DOC "cache documentation string"]
1447 [NO_DEFAULT_PATH]
1448 [NO_PACKAGE_ROOT_PATH]
1449 [NO_CMAKE_PATH]
1450 [NO_CMAKE_ENVIRONMENT_PATH]
1451 [NO_SYSTEM_ENVIRONMENT_PATH]
1452 [NO_CMAKE_SYSTEM_PATH]
1453 [CMAKE_FIND_ROOT_PATH_BOTH |
1454 ONLY_CMAKE_FIND_ROOT_PATH |
1455 NO_CMAKE_FIND_ROOT_PATH]
1456 )
1457 This command is used to find a full path to named file. A cache entry
1459 named by <VAR> is created to store the result of this command. If the
1460 full path to a file is found the result is stored in the variable and
1461 the search will not be repeated unless the variable is cleared. If
1462 nothing is found, the result will be <VAR>-NOTFOUND, and the search
1463 will be attempted again the next time find_file is invoked with the
1464 same variable.
1465 Options include:
1467 NAMES Specify one or more possible names for the full path to a file.
1469 When using this to specify names with and without a version suf‐
1471 fix, we recommend specifying the unversioned name first so that
1472 locally-built packages can be found before those provided by
1473 distributions.
1474 HINTS, PATHS
1476 Specify directories to search in addition to the default loca‐
1477 tions. The ENV var sub-option reads paths from a system envi‐
1478 ronment variable.
1479 PATH_SUFFIXES
1481 Specify additional subdirectories to check below each directory
1482 location otherwise considered.
1483 DOC Specify the documentation string for the <VAR> cache entry.
1485 If NO_DEFAULT_PATH is specified, then no additional paths are added to
1487 the search. If NO_DEFAULT_PATH is not specified, the search process is
1488 as follows:
1489 1. If called from within a find module or any other script loaded by a
1491 call to find_package(<PackageName>), search prefixes unique to the
1492 current package being found. Specifically, look in the <Package‐
1493 Name>_ROOT CMake variable and the <PackageName>_ROOT environment
1494 variable. The package root variables are maintained as a stack, so
1495 if called from nested find modules or config packages, root paths
1496 from the parent’s find module or config package will be searched
1497 after paths from the current module or package. In other words, the
1498 search order would be <CurrentPackage>_ROOT, ENV{<CurrentPack‐
1499 age>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
1500 This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
1501 the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
1502 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1504 <prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
1505 variable and the <PackageName>_ROOT environment variable if called
1506 from within a find module loaded by find_package(<PackageName>)
1507 2. Search paths specified in cmake-specific cache variables. These are
1509 intended to be used on the command line with a -DVAR=value. The
1510 values are interpreted as semicolon-separated lists. This can be
1511 skipped if NO_CMAKE_PATH is passed or by setting the
1512 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
1513 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1515 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1516 · CMAKE_INCLUDE_PATH
1518 · CMAKE_FRAMEWORK_PATH
1520 3. Search paths specified in cmake-specific environment variables.
1522 These are intended to be set in the user’s shell configuration, and
1523 therefore use the host’s native path separator (; on Windows and :
1524 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1525 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
1526 FALSE.
1527 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1529 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1530 · CMAKE_INCLUDE_PATH
1532 · CMAKE_FRAMEWORK_PATH
1534 4. Search the paths specified by the HINTS option. These should be
1536 paths computed by system introspection, such as a hint provided by
1537 the location of another item already found. Hard-coded guesses
1538 should be specified with the PATHS option.
1539 5. Search the standard system environment variables. This can be
1541 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
1542 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
1543 · The directories in PATH and INCLUDE.
1545 · On Windows hosts: <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHI‐
1547 TECTURE is set, and <prefix>/include for each <prefix>/[s]bin in
1548 PATH, and <entry>/include for other entries in PATH.
1549 6. Search cmake variables defined in the Platform files for the current
1551 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
1552 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
1553 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1555 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1556 · CMAKE_SYSTEM_INCLUDE_PATH
1558 · CMAKE_SYSTEM_FRAMEWORK_PATH
1560 7. Search the paths specified by the PATHS option or in the short-hand
1562 version of the command. These are typically hard-coded guesses.
1563 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
1565 determine the order of preference between Apple-style and unix-style
1566 package components.
1567 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
1569 ries to be prepended to all other search directories. This effectively
1570 “re-roots” the entire search under given locations. Paths which are
1571 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
1572 ing, because that variable is always a path on the host system. By
1573 default the CMAKE_FIND_ROOT_PATH is empty.
1574 The CMAKE_SYSROOT variable can also be used to specify exactly one
1576 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
1577 effects. See the documentation for that variable for more.
1578 These variables are especially useful when cross-compiling to point to
1580 the root directory of the target environment and CMake will search
1581 there too. By default at first the directories listed in
1582 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
1583 searched, and then the non-rooted directories will be searched. The
1584 default behavior can be adjusted by setting
1585 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually over‐
1586 ridden on a per-call basis using options:
1587 CMAKE_FIND_ROOT_PATH_BOTH
1589 Search in the order described above.
1590 NO_CMAKE_FIND_ROOT_PATH
1592 Do not use the CMAKE_FIND_ROOT_PATH variable.
1593 ONLY_CMAKE_FIND_ROOT_PATH
1595 Search only the re-rooted directories and directories below
1596 CMAKE_STAGING_PREFIX.
1597 The default search order is designed to be most-specific to least-spe‐
1599 cific for common use cases. Projects may override the order by simply
1600 calling the command multiple times and using the NO_* options:
1601 find_file (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1603 find_file (<VAR> NAMES name)
1604 Once one of the calls succeeds the result variable will be set and
1606 stored in the cache so that no call will search again.
1607 find_library
1609 A short-hand signature is:
1610 find_library (<VAR> name1 [path1 path2 ...])
1612 The general signature is:
1614 find_library (
1616 <VAR>
1617 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
1618 [HINTS path1 [path2 ... ENV var]]
1619 [PATHS path1 [path2 ... ENV var]]
1620 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1621 [DOC "cache documentation string"]
1622 [NO_DEFAULT_PATH]
1623 [NO_PACKAGE_ROOT_PATH]
1624 [NO_CMAKE_PATH]
1625 [NO_CMAKE_ENVIRONMENT_PATH]
1626 [NO_SYSTEM_ENVIRONMENT_PATH]
1627 [NO_CMAKE_SYSTEM_PATH]
1628 [CMAKE_FIND_ROOT_PATH_BOTH |
1629 ONLY_CMAKE_FIND_ROOT_PATH |
1630 NO_CMAKE_FIND_ROOT_PATH]
1631 )
1632 This command is used to find a library. A cache entry named by <VAR>
1634 is created to store the result of this command. If the library is
1635 found the result is stored in the variable and the search will not be
1636 repeated unless the variable is cleared. If nothing is found, the
1637 result will be <VAR>-NOTFOUND, and the search will be attempted again
1638 the next time find_library is invoked with the same variable.
1639 Options include:
1641 NAMES Specify one or more possible names for the library.
1643 When using this to specify names with and without a version suf‐
1645 fix, we recommend specifying the unversioned name first so that
1646 locally-built packages can be found before those provided by
1647 distributions.
1648 HINTS, PATHS
1650 Specify directories to search in addition to the default loca‐
1651 tions. The ENV var sub-option reads paths from a system envi‐
1652 ronment variable.
1653 PATH_SUFFIXES
1655 Specify additional subdirectories to check below each directory
1656 location otherwise considered.
1657 DOC Specify the documentation string for the <VAR> cache entry.
1659 If NO_DEFAULT_PATH is specified, then no additional paths are added to
1661 the search. If NO_DEFAULT_PATH is not specified, the search process is
1662 as follows:
1663 1. If called from within a find module or any other script loaded by a
1665 call to find_package(<PackageName>), search prefixes unique to the
1666 current package being found. Specifically, look in the <Package‐
1667 Name>_ROOT CMake variable and the <PackageName>_ROOT environment
1668 variable. The package root variables are maintained as a stack, so
1669 if called from nested find modules or config packages, root paths
1670 from the parent’s find module or config package will be searched
1671 after paths from the current module or package. In other words, the
1672 search order would be <CurrentPackage>_ROOT, ENV{<CurrentPack‐
1673 age>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
1674 This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
1675 the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
1676 · <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1678 <prefix>/lib for each <prefix> in the <PackageName>_ROOT CMake
1679 variable and the <PackageName>_ROOT environment variable if called
1680 from within a find module loaded by find_package(<PackageName>)
1681 2. Search paths specified in cmake-specific cache variables. These are
1683 intended to be used on the command line with a -DVAR=value. The
1684 values are interpreted as semicolon-separated lists. This can be
1685 skipped if NO_CMAKE_PATH is passed or by setting the
1686 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
1687 · <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1689 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1690 · CMAKE_LIBRARY_PATH
1692 · CMAKE_FRAMEWORK_PATH
1694 3. Search paths specified in cmake-specific environment variables.
1696 These are intended to be set in the user’s shell configuration, and
1697 therefore use the host’s native path separator (; on Windows and :
1698 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1699 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
1700 FALSE.
1701 · <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1703 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1704 · CMAKE_LIBRARY_PATH
1706 · CMAKE_FRAMEWORK_PATH
1708 4. Search the paths specified by the HINTS option. These should be
1710 paths computed by system introspection, such as a hint provided by
1711 the location of another item already found. Hard-coded guesses
1712 should be specified with the PATHS option.
1713 5. Search the standard system environment variables. This can be
1715 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
1716 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
1717 · The directories in PATH and INCLUDE.
1719 · On Windows hosts: <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITEC‐
1721 TURE is set, and <prefix>/lib for each <prefix>/[s]bin in PATH,
1722 and <entry>/lib for other entries in PATH.
1723 6. Search cmake variables defined in the Platform files for the current
1725 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
1726 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
1727 · <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1729 <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1730 · CMAKE_SYSTEM_LIBRARY_PATH
1732 · CMAKE_SYSTEM_FRAMEWORK_PATH
1734 7. Search the paths specified by the PATHS option or in the short-hand
1736 version of the command. These are typically hard-coded guesses.
1737 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
1739 determine the order of preference between Apple-style and unix-style
1740 package components.
1741 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
1743 ries to be prepended to all other search directories. This effectively
1744 “re-roots” the entire search under given locations. Paths which are
1745 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
1746 ing, because that variable is always a path on the host system. By
1747 default the CMAKE_FIND_ROOT_PATH is empty.
1748 The CMAKE_SYSROOT variable can also be used to specify exactly one
1750 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
1751 effects. See the documentation for that variable for more.
1752 These variables are especially useful when cross-compiling to point to
1754 the root directory of the target environment and CMake will search
1755 there too. By default at first the directories listed in
1756 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
1757 searched, and then the non-rooted directories will be searched. The
1758 default behavior can be adjusted by setting
1759 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY. This behavior can be manually over‐
1760 ridden on a per-call basis using options:
1761 CMAKE_FIND_ROOT_PATH_BOTH
1763 Search in the order described above.
1764 NO_CMAKE_FIND_ROOT_PATH
1766 Do not use the CMAKE_FIND_ROOT_PATH variable.
1767 ONLY_CMAKE_FIND_ROOT_PATH
1769 Search only the re-rooted directories and directories below
1770 CMAKE_STAGING_PREFIX.
1771 The default search order is designed to be most-specific to least-spe‐
1773 cific for common use cases. Projects may override the order by simply
1774 calling the command multiple times and using the NO_* options:
1775 find_library (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1777 find_library (<VAR> NAMES name)
1778 Once one of the calls succeeds the result variable will be set and
1780 stored in the cache so that no call will search again.
1781 When more than one value is given to the NAMES option this command by
1783 default will consider one name at a time and search every directory for
1784 it. The NAMES_PER_DIR option tells this command to consider one direc‐
1785 tory at a time and search for all names in it.
1786 Each library name given to the NAMES option is first considered as a
1788 library file name and then considered with platform-specific prefixes
1789 (e.g. lib) and suffixes (e.g. .so). Therefore one may specify library
1790 file names such as libfoo.a directly. This can be used to locate
1791 static libraries on UNIX-like systems.
1792 If the library found is a framework, then <VAR> will be set to the full
1794 path to the framework <fullPath>/A.framework. When a full path to a
1795 framework is used as a library, CMake will use a -framework A, and a
1796 -F<fullPath> to link the framework to the target.
1797 If the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable is set all search
1799 paths will be tested as normal, with the suffix appended, and with all
1800 matches of lib/ replaced with lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUF‐
1801 FIX}/. This variable overrides the FIND_LIBRARY_USE_LIB32_PATHS,
1802 FIND_LIBRARY_USE_LIBX32_PATHS, and FIND_LIBRARY_USE_LIB64_PATHS global
1803 properties.
1804 If the FIND_LIBRARY_USE_LIB32_PATHS global property is set all search
1806 paths will be tested as normal, with 32/ appended, and with all matches
1807 of lib/ replaced with lib32/. This property is automatically set for
1808 the platforms that are known to need it if at least one of the lan‐
1809 guages supported by the project() command is enabled.
1810 If the FIND_LIBRARY_USE_LIBX32_PATHS global property is set all search
1812 paths will be tested as normal, with x32/ appended, and with all
1813 matches of lib/ replaced with libx32/. This property is automatically
1814 set for the platforms that are known to need it if at least one of the
1815 languages supported by the project() command is enabled.
1816 If the FIND_LIBRARY_USE_LIB64_PATHS global property is set all search
1818 paths will be tested as normal, with 64/ appended, and with all matches
1819 of lib/ replaced with lib64/. This property is automatically set for
1820 the platforms that are known to need it if at least one of the lan‐
1821 guages supported by the project() command is enabled.
1822 find_package
1824 Find an external project, and load its settings.
1825 Basic Signature and Module Mode
1827 find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
1828 [REQUIRED] [[COMPONENTS] [components...]]
1829 [OPTIONAL_COMPONENTS components...]
1830 [NO_POLICY_SCOPE])
1831 Finds and loads settings from an external project. <PackageName>_FOUND
1833 will be set to indicate whether the package was found. When the pack‐
1834 age is found package-specific information is provided through variables
1835 and Imported Targets documented by the package itself. The QUIET
1836 option disables informational messages, including those indicating that
1837 the package cannot be found if it is not REQUIRED. The REQUIRED option
1838 stops processing with an error message if the package cannot be found.
1839 A package-specific list of required components may be listed after the
1841 COMPONENTS option (or after the REQUIRED option if present). Addi‐
1842 tional optional components may be listed after OPTIONAL_COMPONENTS.
1843 Available components and their influence on whether a package is con‐
1844 sidered to be found are defined by the target package.
1845 The [version] argument requests a version with which the package found
1847 should be compatible (format is major[.minor[.patch[.tweak]]]). The
1848 EXACT option requests that the version be matched exactly. If no [ver‐
1849 sion] and/or component list is given to a recursive invocation inside a
1850 find-module, the corresponding arguments are forwarded automatically
1851 from the outer call (including the EXACT flag for [version]). Version
1852 support is currently provided only on a package-by-package basis (see
1853 the Version Selection section below).
1854 See the cmake_policy() command documentation for discussion of the
1856 NO_POLICY_SCOPE option.
1857 The command has two modes by which it searches for packages: “Module”
1859 mode and “Config” mode. The above signature selects Module mode. If
1860 no module is found the command falls back to Config mode, described
1861 below. This fall back is disabled if the MODULE option is given.
1862 In Module mode, CMake searches for a file called Find<Package‐
1864 Name>.cmake. The file is first searched in the CMAKE_MODULE_PATH, then
1865 among the Find Modules provided by the CMake installation. If the file
1866 is found, it is read and processed by CMake. It is responsible for
1867 finding the package, checking the version, and producing any needed
1868 messages. Some find-modules provide limited or no support for version‐
1869 ing; check the module documentation.
1870 If the MODULE option is not specfied in the above signature, CMake
1872 first searches for the package using Module mode. Then, if the package
1873 is not found, it searches again using Config mode. A user may set the
1874 variable CMAKE_FIND_PACKAGE_PREFER_CONFIG to TRUE to direct CMake first
1875 search using Config mode before falling back to Module mode.
1876 Full Signature and Config Mode
1878 User code should generally look for packages using the above basic sig‐
1879 nature. The remainder of this command documentation specifies the full
1880 command signature and details of the search process. Project maintain‐
1881 ers wishing to provide a package to be found by this command are
1882 encouraged to read on.
1883 The complete Config mode command signature is
1885 find_package(<PackageName> [version] [EXACT] [QUIET]
1887 [REQUIRED] [[COMPONENTS] [components...]]
1888 [OPTIONAL_COMPONENTS components...]
1889 [CONFIG|NO_MODULE]
1890 [NO_POLICY_SCOPE]
1891 [NAMES name1 [name2 ...]]
1892 [CONFIGS config1 [config2 ...]]
1893 [HINTS path1 [path2 ... ]]
1894 [PATHS path1 [path2 ... ]]
1895 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1896 [NO_DEFAULT_PATH]
1897 [NO_PACKAGE_ROOT_PATH]
1898 [NO_CMAKE_PATH]
1899 [NO_CMAKE_ENVIRONMENT_PATH]
1900 [NO_SYSTEM_ENVIRONMENT_PATH]
1901 [NO_CMAKE_PACKAGE_REGISTRY]
1902 [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
1903 [NO_CMAKE_SYSTEM_PATH]
1904 [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
1905 [CMAKE_FIND_ROOT_PATH_BOTH |
1906 ONLY_CMAKE_FIND_ROOT_PATH |
1907 NO_CMAKE_FIND_ROOT_PATH])
1908 The CONFIG option, the synonymous NO_MODULE option, or the use of
1910 options not specified in the basic signature all enforce pure Config
1911 mode. In pure Config mode, the command skips Module mode search and
1912 proceeds at once with Config mode search.
1913 Config mode search attempts to locate a configuration file provided by
1915 the package to be found. A cache entry called <PackageName>_DIR is
1916 created to hold the directory containing the file. By default the com‐
1917 mand searches for a package with the name <PackageName>. If the NAMES
1918 option is given the names following it are used instead of <Package‐
1919 Name>. The command searches for a file called <PackageName>Con‐
1920 fig.cmake or <lower-case-package-name>-config.cmake for each name spec‐
1921 ified. A replacement set of possible configuration file names may be
1922 given using the CONFIGS option. The search procedure is specified
1923 below. Once found, the configuration file is read and processed by
1924 CMake. Since the file is provided by the package it already knows the
1925 location of package contents. The full path to the configuration file
1926 is stored in the cmake variable <PackageName>_CONFIG.
1927 All configuration files which have been considered by CMake while
1929 searching for an installation of the package with an appropriate ver‐
1930 sion are stored in the cmake variable <PackageName>_CONSIDERED_CONFIGS,
1931 the associated versions in <PackageName>_CONSIDERED_VERSIONS.
1932 If the package configuration file cannot be found CMake will generate
1934 an error describing the problem unless the QUIET argument is specified.
1935 If REQUIRED is specified and the package is not found a fatal error is
1936 generated and the configure step stops executing. If <PackageName>_DIR
1937 has been set to a directory not containing a configuration file CMake
1938 will ignore it and search from scratch.
1939 Package maintainers providing CMake package configuration files are
1941 encouraged to name and install them such that the Search Procedure out‐
1942 lined below will find them without requiring use of additional options.
1943 Version Selection
1945 When the [version] argument is given Config mode will only find a ver‐
1946 sion of the package that claims compatibility with the requested ver‐
1947 sion (format is major[.minor[.patch[.tweak]]]). If the EXACT option is
1948 given only a version of the package claiming an exact match of the
1949 requested version may be found. CMake does not establish any conven‐
1950 tion for the meaning of version numbers. Package version numbers are
1951 checked by “version” files provided by the packages themselves. For a
1952 candidate package configuration file <config-file>.cmake the corre‐
1953 sponding version file is located next to it and named either <con‐
1954 fig-file>-version.cmake or <config-file>Version.cmake. If no such ver‐
1955 sion file is available then the configuration file is assumed to not be
1956 compatible with any requested version. A basic version file containing
1957 generic version matching code can be created using the CMakePackageCon‐
1958 figHelpers module. When a version file is found it is loaded to check
1959 the requested version number. The version file is loaded in a nested
1960 scope in which the following variables have been defined:
1961 PACKAGE_FIND_NAME
1963 the <PackageName>
1964 PACKAGE_FIND_VERSION
1966 full requested version string
1967 PACKAGE_FIND_VERSION_MAJOR
1969 major version if requested, else 0
1970 PACKAGE_FIND_VERSION_MINOR
1972 minor version if requested, else 0
1973 PACKAGE_FIND_VERSION_PATCH
1975 patch version if requested, else 0
1976 PACKAGE_FIND_VERSION_TWEAK
1978 tweak version if requested, else 0
1979 PACKAGE_FIND_VERSION_COUNT
1981 number of version components, 0 to 4
1982 The version file checks whether it satisfies the requested version and
1984 sets these variables:
1985 PACKAGE_VERSION
1987 full provided version string
1988 PACKAGE_VERSION_EXACT
1990 true if version is exact match
1991 PACKAGE_VERSION_COMPATIBLE
1993 true if version is compatible
1994 PACKAGE_VERSION_UNSUITABLE
1996 true if unsuitable as any version
1997 These variables are checked by the find_package command to determine
1999 whether the configuration file provides an acceptable version. They
2000 are not available after the find_package call returns. If the version
2001 is acceptable the following variables are set:
2002 <PackageName>_VERSION
2004 full provided version string
2005 <PackageName>_VERSION_MAJOR
2007 major version if provided, else 0
2008 <PackageName>_VERSION_MINOR
2010 minor version if provided, else 0
2011 <PackageName>_VERSION_PATCH
2013 patch version if provided, else 0
2014 <PackageName>_VERSION_TWEAK
2016 tweak version if provided, else 0
2017 <PackageName>_VERSION_COUNT
2019 number of version components, 0 to 4
2020 and the corresponding package configuration file is loaded. When mul‐
2022 tiple package configuration files are available whose version files
2023 claim compatibility with the version requested it is unspecified which
2024 one is chosen: unless the variable CMAKE_FIND_PACKAGE_SORT_ORDER is set
2025 no attempt is made to choose a highest or closest version number.
2026 To control the order in which find_package checks for compatibility use
2028 the two variables CMAKE_FIND_PACKAGE_SORT_ORDER and CMAKE_FIND_PACK‐
2029 AGE_SORT_DIRECTION. For instance in order to select the highest ver‐
2030 sion one can set
2031 SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
2033 SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
2034 before calling find_package.
2036 Search Procedure
2038 CMake constructs a set of possible installation prefixes for the pack‐
2039 age. Under each prefix several directories are searched for a configu‐
2040 ration file. The tables below show the directories searched. Each
2041 entry is meant for installation trees following Windows (W), UNIX (U),
2042 or Apple (A) conventions:
2043 <prefix>/ (W)
2045 <prefix>/(cmake|CMake)/ (W)
2046 <prefix>/<name>*/ (W)
2047 <prefix>/<name>*/(cmake|CMake)/ (W)
2048 <prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/ (U)
2049 <prefix>/(lib/<arch>|lib*|share)/<name>*/ (U)
2050 <prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (U)
2051 <prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/ (W/U)
2052 <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ (W/U)
2053 <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U)
2054 On systems supporting macOS FRAMEWORK and BUNDLE, the following direc‐
2056 tories are searched for Frameworks or Application Bundles containing a
2057 configuration file:
2058 <prefix>/<name>.framework/Resources/ (A)
2060 <prefix>/<name>.framework/Resources/CMake/ (A)
2061 <prefix>/<name>.framework/Versions/*/Resources/ (A)
2062 <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A)
2063 <prefix>/<name>.app/Contents/Resources/ (A)
2064 <prefix>/<name>.app/Contents/Resources/CMake/ (A)
2065 In all cases the <name> is treated as case-insensitive and corresponds
2067 to any of the names specified (<PackageName> or names given by NAMES).
2068 Paths with lib/<arch> are enabled if the CMAKE_LIBRARY_ARCHITECTURE
2070 variable is set. lib* includes one or more of the values lib64, lib32,
2071 libx32 or lib (searched in that order).
2072 · Paths with lib64 are searched on 64 bit platforms if the
2074 FIND_LIBRARY_USE_LIB64_PATHS property is set to TRUE.
2075 · Paths with lib32 are searched on 32 bit platforms if the
2077 FIND_LIBRARY_USE_LIB32_PATHS property is set to TRUE.
2078 · Paths with libx32 are searched on platforms using the x32 ABI if the
2080 FIND_LIBRARY_USE_LIBX32_PATHS property is set to TRUE.
2081 · The lib path is always searched.
2083 If PATH_SUFFIXES is specified, the suffixes are appended to each (W) or
2085 (U) directory entry one-by-one.
2086 This set of directories is intended to work in cooperation with
2088 projects that provide configuration files in their installation trees.
2089 Directories above marked with (W) are intended for installations on
2090 Windows where the prefix may point at the top of an application’s
2091 installation directory. Those marked with (U) are intended for instal‐
2092 lations on UNIX platforms where the prefix is shared by multiple pack‐
2093 ages. This is merely a convention, so all (W) and (U) directories are
2094 still searched on all platforms. Directories marked with (A) are
2095 intended for installations on Apple platforms. The CMAKE_FIND_FRAME‐
2096 WORK and CMAKE_FIND_APPBUNDLE variables determine the order of prefer‐
2097 ence.
2098 The set of installation prefixes is constructed using the following
2100 steps. If NO_DEFAULT_PATH is specified all NO_* options are enabled.
2101 1. Search paths specified in the <PackageName>_ROOT CMake variable and
2103 the <PackageName>_ROOT environment variable, where <PackageName> is
2104 the package to be found. The package root variables are maintained
2105 as a stack so if called from within a find module, root paths from
2106 the parent’s find module will also be searched after paths for the
2107 current package. This can be skipped if NO_PACKAGE_ROOT_PATH is
2108 passed or by setting the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE.
2109 See policy CMP0074.
2110 2. Search paths specified in cmake-specific cache variables. These are
2112 intended to be used on the command line with a -DVAR=value. The
2113 values are interpreted as semicolon-separated lists. This can be
2114 skipped if NO_CMAKE_PATH is passed or by setting the
2115 CMAKE_FIND_USE_CMAKE_PATH to FALSE:
2116 CMAKE_PREFIX_PATH
2118 CMAKE_FRAMEWORK_PATH
2119 CMAKE_APPBUNDLE_PATH
2120 3. Search paths specified in cmake-specific environment variables.
2122 These are intended to be set in the user’s shell configuration, and
2123 therefore use the host’s native path separator (; on Windows and :
2124 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2125 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
2126 FALSE:
2127 <PackageName>_DIR
2129 CMAKE_PREFIX_PATH
2130 CMAKE_FRAMEWORK_PATH
2131 CMAKE_APPBUNDLE_PATH
2132 4. Search paths specified by the HINTS option. These should be paths
2134 computed by system introspection, such as a hint provided by the
2135 location of another item already found. Hard-coded guesses should
2136 be specified with the PATHS option.
2137 5. Search the standard system environment variables. This can be
2139 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
2140 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE. Path entries ending
2141 in /bin or /sbin are automatically converted to their parent direc‐
2142 tories:
2143 PATH
2145 6. Search paths stored in the CMake User Package Registry. This can be
2147 skipped if NO_CMAKE_PACKAGE_REGISTRY is passed or by setting the
2148 variable CMAKE_FIND_USE_PACKAGE_REGISTRY to FALSE or the deprecated
2149 variable CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY to TRUE.
2150 See the cmake-packages(7) manual for details on the user package
2152 registry.
2153 7. Search cmake variables defined in the Platform files for the current
2155 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
2156 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE:
2157 CMAKE_SYSTEM_PREFIX_PATH
2159 CMAKE_SYSTEM_FRAMEWORK_PATH
2160 CMAKE_SYSTEM_APPBUNDLE_PATH
2161 8. Search paths stored in the CMake System Package Registry. This can
2163 be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is passed or by set‐
2164 ting the CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variable to FALSE or
2165 the deprecated variable CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REG‐
2166 ISTRY to TRUE.
2167 See the cmake-packages(7) manual for details on the system package
2169 registry.
2170 9. Search paths specified by the PATHS option. These are typically
2172 hard-coded guesses.
2173 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
2175 ries to be prepended to all other search directories. This effectively
2176 “re-roots” the entire search under given locations. Paths which are
2177 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
2178 ing, because that variable is always a path on the host system. By
2179 default the CMAKE_FIND_ROOT_PATH is empty.
2180 The CMAKE_SYSROOT variable can also be used to specify exactly one
2182 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
2183 effects. See the documentation for that variable for more.
2184 These variables are especially useful when cross-compiling to point to
2186 the root directory of the target environment and CMake will search
2187 there too. By default at first the directories listed in
2188 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
2189 searched, and then the non-rooted directories will be searched. The
2190 default behavior can be adjusted by setting
2191 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE. This behavior can be manually over‐
2192 ridden on a per-call basis using options:
2193 CMAKE_FIND_ROOT_PATH_BOTH
2195 Search in the order described above.
2196 NO_CMAKE_FIND_ROOT_PATH
2198 Do not use the CMAKE_FIND_ROOT_PATH variable.
2199 ONLY_CMAKE_FIND_ROOT_PATH
2201 Search only the re-rooted directories and directories below
2202 CMAKE_STAGING_PREFIX.
2203 The default search order is designed to be most-specific to least-spe‐
2205 cific for common use cases. Projects may override the order by simply
2206 calling the command multiple times and using the NO_* options:
2207 find_package (<PackageName> PATHS paths... NO_DEFAULT_PATH)
2209 find_package (<PackageName>)
2210 Once one of the calls succeeds the result variable will be set and
2212 stored in the cache so that no call will search again.
2213 By default the value stored in the result variable will be the path at
2215 which the file is found. The CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS vari‐
2216 able may be set to TRUE before calling find_package in order to resolve
2217 symbolic links and store the real path to the file.
2218 Every non-REQUIRED find_package call can be disabled by setting the
2220 CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable to TRUE.
2221 Package File Interface Variables
2223 When loading a find module or package configuration file find_package
2224 defines variables to provide information about the call arguments (and
2225 restores their original state before returning):
2226 CMAKE_FIND_PACKAGE_NAME
2228 the <PackageName> which is searched for
2229 <PackageName>_FIND_REQUIRED
2231 true if REQUIRED option was given
2232 <PackageName>_FIND_QUIETLY
2234 true if QUIET option was given
2235 <PackageName>_FIND_VERSION
2237 full requested version string
2238 <PackageName>_FIND_VERSION_MAJOR
2240 major version if requested, else 0
2241 <PackageName>_FIND_VERSION_MINOR
2243 minor version if requested, else 0
2244 <PackageName>_FIND_VERSION_PATCH
2246 patch version if requested, else 0
2247 <PackageName>_FIND_VERSION_TWEAK
2249 tweak version if requested, else 0
2250 <PackageName>_FIND_VERSION_COUNT
2252 number of version components, 0 to 4
2253 <PackageName>_FIND_VERSION_EXACT
2255 true if EXACT option was given
2256 <PackageName>_FIND_COMPONENTS
2258 list of requested components
2259 <PackageName>_FIND_REQUIRED_<c>
2261 true if component <c> is required, false if component <c> is
2262 optional
2263 In Module mode the loaded find module is responsible to honor the
2265 request detailed by these variables; see the find module for details.
2266 In Config mode find_package handles REQUIRED, QUIET, and [version]
2267 options automatically but leaves it to the package configuration file
2268 to handle components in a way that makes sense for the package. The
2269 package configuration file may set <PackageName>_FOUND to false to tell
2270 find_package that component requirements are not satisfied.
2271 find_path
2273 A short-hand signature is:
2274 find_path (<VAR> name1 [path1 path2 ...])
2276 The general signature is:
2278 find_path (
2280 <VAR>
2281 name | NAMES name1 [name2 ...]
2282 [HINTS path1 [path2 ... ENV var]]
2283 [PATHS path1 [path2 ... ENV var]]
2284 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2285 [DOC "cache documentation string"]
2286 [NO_DEFAULT_PATH]
2287 [NO_PACKAGE_ROOT_PATH]
2288 [NO_CMAKE_PATH]
2289 [NO_CMAKE_ENVIRONMENT_PATH]
2290 [NO_SYSTEM_ENVIRONMENT_PATH]
2291 [NO_CMAKE_SYSTEM_PATH]
2292 [CMAKE_FIND_ROOT_PATH_BOTH |
2293 ONLY_CMAKE_FIND_ROOT_PATH |
2294 NO_CMAKE_FIND_ROOT_PATH]
2295 )
2296 This command is used to find a directory containing the named file. A
2298 cache entry named by <VAR> is created to store the result of this com‐
2299 mand. If the file in a directory is found the result is stored in the
2300 variable and the search will not be repeated unless the variable is
2301 cleared. If nothing is found, the result will be <VAR>-NOTFOUND, and
2302 the search will be attempted again the next time find_path is invoked
2303 with the same variable.
2304 Options include:
2306 NAMES Specify one or more possible names for the file in a directory.
2308 When using this to specify names with and without a version suf‐
2310 fix, we recommend specifying the unversioned name first so that
2311 locally-built packages can be found before those provided by
2312 distributions.
2313 HINTS, PATHS
2315 Specify directories to search in addition to the default loca‐
2316 tions. The ENV var sub-option reads paths from a system envi‐
2317 ronment variable.
2318 PATH_SUFFIXES
2320 Specify additional subdirectories to check below each directory
2321 location otherwise considered.
2322 DOC Specify the documentation string for the <VAR> cache entry.
2324 If NO_DEFAULT_PATH is specified, then no additional paths are added to
2326 the search. If NO_DEFAULT_PATH is not specified, the search process is
2327 as follows:
2328 1. If called from within a find module or any other script loaded by a
2330 call to find_package(<PackageName>), search prefixes unique to the
2331 current package being found. Specifically, look in the <Package‐
2332 Name>_ROOT CMake variable and the <PackageName>_ROOT environment
2333 variable. The package root variables are maintained as a stack, so
2334 if called from nested find modules or config packages, root paths
2335 from the parent’s find module or config package will be searched
2336 after paths from the current module or package. In other words, the
2337 search order would be <CurrentPackage>_ROOT, ENV{<CurrentPack‐
2338 age>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
2339 This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
2340 the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
2341 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2343 <prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
2344 variable and the <PackageName>_ROOT environment variable if called
2345 from within a find module loaded by find_package(<PackageName>)
2346 2. Search paths specified in cmake-specific cache variables. These are
2348 intended to be used on the command line with a -DVAR=value. The
2349 values are interpreted as semicolon-separated lists. This can be
2350 skipped if NO_CMAKE_PATH is passed or by setting the
2351 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
2352 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2354 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2355 · CMAKE_INCLUDE_PATH
2357 · CMAKE_FRAMEWORK_PATH
2359 3. Search paths specified in cmake-specific environment variables.
2361 These are intended to be set in the user’s shell configuration, and
2362 therefore use the host’s native path separator (; on Windows and :
2363 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2364 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
2365 FALSE.
2366 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2368 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2369 · CMAKE_INCLUDE_PATH
2371 · CMAKE_FRAMEWORK_PATH
2373 4. Search the paths specified by the HINTS option. These should be
2375 paths computed by system introspection, such as a hint provided by
2376 the location of another item already found. Hard-coded guesses
2377 should be specified with the PATHS option.
2378 5. Search the standard system environment variables. This can be
2380 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
2381 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
2382 · The directories in PATH and INCLUDE.
2384 · On Windows hosts: <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHI‐
2386 TECTURE is set, and <prefix>/include for each <prefix>/[s]bin in
2387 PATH, and <entry>/include for other entries in PATH.
2388 6. Search cmake variables defined in the Platform files for the current
2390 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
2391 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
2392 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2394 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2395 · CMAKE_SYSTEM_INCLUDE_PATH
2397 · CMAKE_SYSTEM_FRAMEWORK_PATH
2399 7. Search the paths specified by the PATHS option or in the short-hand
2401 version of the command. These are typically hard-coded guesses.
2402 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
2404 determine the order of preference between Apple-style and unix-style
2405 package components.
2406 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
2408 ries to be prepended to all other search directories. This effectively
2409 “re-roots” the entire search under given locations. Paths which are
2410 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
2411 ing, because that variable is always a path on the host system. By
2412 default the CMAKE_FIND_ROOT_PATH is empty.
2413 The CMAKE_SYSROOT variable can also be used to specify exactly one
2415 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
2416 effects. See the documentation for that variable for more.
2417 These variables are especially useful when cross-compiling to point to
2419 the root directory of the target environment and CMake will search
2420 there too. By default at first the directories listed in
2421 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
2422 searched, and then the non-rooted directories will be searched. The
2423 default behavior can be adjusted by setting
2424 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually over‐
2425 ridden on a per-call basis using options:
2426 CMAKE_FIND_ROOT_PATH_BOTH
2428 Search in the order described above.
2429 NO_CMAKE_FIND_ROOT_PATH
2431 Do not use the CMAKE_FIND_ROOT_PATH variable.
2432 ONLY_CMAKE_FIND_ROOT_PATH
2434 Search only the re-rooted directories and directories below
2435 CMAKE_STAGING_PREFIX.
2436 The default search order is designed to be most-specific to least-spe‐
2438 cific for common use cases. Projects may override the order by simply
2439 calling the command multiple times and using the NO_* options:
2440 find_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2442 find_path (<VAR> NAMES name)
2443 Once one of the calls succeeds the result variable will be set and
2445 stored in the cache so that no call will search again.
2446 When searching for frameworks, if the file is specified as A/b.h, then
2448 the framework search will look for A.framework/Headers/b.h. If that is
2449 found the path will be set to the path to the framework. CMake will
2450 convert this to the correct -F option to include the file.
2451 find_program
2453 A short-hand signature is:
2454 find_program (<VAR> name1 [path1 path2 ...])
2456 The general signature is:
2458 find_program (
2460 <VAR>
2461 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
2462 [HINTS path1 [path2 ... ENV var]]
2463 [PATHS path1 [path2 ... ENV var]]
2464 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2465 [DOC "cache documentation string"]
2466 [NO_DEFAULT_PATH]
2467 [NO_PACKAGE_ROOT_PATH]
2468 [NO_CMAKE_PATH]
2469 [NO_CMAKE_ENVIRONMENT_PATH]
2470 [NO_SYSTEM_ENVIRONMENT_PATH]
2471 [NO_CMAKE_SYSTEM_PATH]
2472 [CMAKE_FIND_ROOT_PATH_BOTH |
2473 ONLY_CMAKE_FIND_ROOT_PATH |
2474 NO_CMAKE_FIND_ROOT_PATH]
2475 )
2476 This command is used to find a program. A cache entry named by <VAR>
2478 is created to store the result of this command. If the program is
2479 found the result is stored in the variable and the search will not be
2480 repeated unless the variable is cleared. If nothing is found, the
2481 result will be <VAR>-NOTFOUND, and the search will be attempted again
2482 the next time find_program is invoked with the same variable.
2483 Options include:
2485 NAMES Specify one or more possible names for the program.
2487 When using this to specify names with and without a version suf‐
2489 fix, we recommend specifying the unversioned name first so that
2490 locally-built packages can be found before those provided by
2491 distributions.
2492 HINTS, PATHS
2494 Specify directories to search in addition to the default loca‐
2495 tions. The ENV var sub-option reads paths from a system envi‐
2496 ronment variable.
2497 PATH_SUFFIXES
2499 Specify additional subdirectories to check below each directory
2500 location otherwise considered.
2501 DOC Specify the documentation string for the <VAR> cache entry.
2503 If NO_DEFAULT_PATH is specified, then no additional paths are added to
2505 the search. If NO_DEFAULT_PATH is not specified, the search process is
2506 as follows:
2507 1. If called from within a find module or any other script loaded by a
2509 call to find_package(<PackageName>), search prefixes unique to the
2510 current package being found. Specifically, look in the <Package‐
2511 Name>_ROOT CMake variable and the <PackageName>_ROOT environment
2512 variable. The package root variables are maintained as a stack, so
2513 if called from nested find modules or config packages, root paths
2514 from the parent’s find module or config package will be searched
2515 after paths from the current module or package. In other words, the
2516 search order would be <CurrentPackage>_ROOT, ENV{<CurrentPack‐
2517 age>_ROOT}, <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc.
2518 This can be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting
2519 the CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
2520 · <prefix>/[s]bin for each <prefix> in the <PackageName>_ROOT CMake
2522 variable and the <PackageName>_ROOT environment variable if called
2523 from within a find module loaded by find_package(<PackageName>)
2524 2. Search paths specified in cmake-specific cache variables. These are
2526 intended to be used on the command line with a -DVAR=value. The
2527 values are interpreted as semicolon-separated lists. This can be
2528 skipped if NO_CMAKE_PATH is passed or by setting the
2529 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
2530 · <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2532 · CMAKE_PROGRAM_PATH
2534 · CMAKE_APPBUNDLE_PATH
2536 3. Search paths specified in cmake-specific environment variables.
2538 These are intended to be set in the user’s shell configuration, and
2539 therefore use the host’s native path separator (; on Windows and :
2540 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2541 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
2542 FALSE.
2543 · <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2545 · CMAKE_PROGRAM_PATH
2547 · CMAKE_APPBUNDLE_PATH
2549 4. Search the paths specified by the HINTS option. These should be
2551 paths computed by system introspection, such as a hint provided by
2552 the location of another item already found. Hard-coded guesses
2553 should be specified with the PATHS option.
2554 5. Search the standard system environment variables. This can be
2556 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
2557 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
2558 · The directories in PATH itself.
2560 · On Windows hosts no extra search paths are included
2562 6. Search cmake variables defined in the Platform files for the current
2564 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by
2565 setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
2566 · <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2568 · CMAKE_SYSTEM_PROGRAM_PATH
2570 · CMAKE_SYSTEM_APPBUNDLE_PATH
2572 7. Search the paths specified by the PATHS option or in the short-hand
2574 version of the command. These are typically hard-coded guesses.
2575 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
2577 determine the order of preference between Apple-style and unix-style
2578 package components.
2579 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
2581 ries to be prepended to all other search directories. This effectively
2582 “re-roots” the entire search under given locations. Paths which are
2583 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
2584 ing, because that variable is always a path on the host system. By
2585 default the CMAKE_FIND_ROOT_PATH is empty.
2586 The CMAKE_SYSROOT variable can also be used to specify exactly one
2588 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
2589 effects. See the documentation for that variable for more.
2590 These variables are especially useful when cross-compiling to point to
2592 the root directory of the target environment and CMake will search
2593 there too. By default at first the directories listed in
2594 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
2595 searched, and then the non-rooted directories will be searched. The
2596 default behavior can be adjusted by setting
2597 CMAKE_FIND_ROOT_PATH_MODE_PROGRAM. This behavior can be manually over‐
2598 ridden on a per-call basis using options:
2599 CMAKE_FIND_ROOT_PATH_BOTH
2601 Search in the order described above.
2602 NO_CMAKE_FIND_ROOT_PATH
2604 Do not use the CMAKE_FIND_ROOT_PATH variable.
2605 ONLY_CMAKE_FIND_ROOT_PATH
2607 Search only the re-rooted directories and directories below
2608 CMAKE_STAGING_PREFIX.
2609 The default search order is designed to be most-specific to least-spe‐
2611 cific for common use cases. Projects may override the order by simply
2612 calling the command multiple times and using the NO_* options:
2613 find_program (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2615 find_program (<VAR> NAMES name)
2616 Once one of the calls succeeds the result variable will be set and
2618 stored in the cache so that no call will search again.
2619 When more than one value is given to the NAMES option this command by
2621 default will consider one name at a time and search every directory for
2622 it. The NAMES_PER_DIR option tells this command to consider one direc‐
2623 tory at a time and search for all names in it.
2624 foreach
2626 Evaluate a group of commands for each value in a list.
2627 foreach(<loop_var> <items>)
2629 <commands>
2630 endforeach()
2631 where <items> is a list of items that are separated by semicolon or
2633 whitespace. All commands between foreach and the matching endforeach
2634 are recorded without being invoked. Once the endforeach is evaluated,
2635 the recorded list of commands is invoked once for each item in <items>.
2636 At the beginning of each iteration the variable loop_var will be set to
2637 the value of the current item.
2638 The commands break() and continue() provide means to escape from the
2640 normal control flow.
2641 Per legacy, the endforeach() command admits an optional <loop_var>
2643 argument. If used, it must be a verbatim repeat of the argument of the
2644 opening foreach command.
2645 foreach(<loop_var> RANGE <stop>)
2647 In this variant, foreach iterates over the numbers 0, 1, … up to (and
2649 including) the nonnegative integer <stop>.
2650 foreach(<loop_var> RANGE <start> <stop> [<step>])
2652 In this variant, foreach iterates over the numbers from <start> up to
2654 at most <stop> in steps of <step>. If <step> is not specified, then
2655 the step size is 1. The three arguments <start> <stop> <step> must all
2656 be nonnegative integers, and <stop> must not be smaller than <start>;
2657 otherwise you enter the danger zone of undocumented behavior that may
2658 change in future releases.
2659 foreach(loop_var IN [LISTS [<lists>]] [ITEMS [<items>]])
2661 In this variant, <lists> is a whitespace or semicolon separated list of
2663 list-valued variables. The foreach command iterates over each item in
2664 each given list. The <items> following the ITEMS keyword are processed
2665 as in the first variant of the foreach command. The forms LISTS A and
2666 ITEMS ${A} are equivalent.
2667 The following example shows how the LISTS option is processed:
2669 set(A 0;1)
2671 set(B 2 3)
2672 set(C "4 5")
2673 set(D 6;7 8)
2674 set(E "")
2675 foreach(X IN LISTS A B C D E)
2676 message(STATUS "X=${X}")
2677 endforeach()
2678 yields
2680 -- X=0
2682 -- X=1
2683 -- X=2
2684 -- X=3
2685 -- X=4 5
2686 -- X=6
2687 -- X=7
2688 -- X=8
2689 function
2691 Start recording a function for later invocation as a command.
2692 function(<name> [<arg1> ...])
2694 <commands>
2695 endfunction()
2696 Defines a function named <name> that takes arguments named <arg1>, …
2698 The <commands> in the function definition are recorded; they are not
2699 executed until the function is invoked.
2700 Per legacy, the endfunction() command admits an optional <name> argu‐
2702 ment. If used, it must be a verbatim repeat of the argument of the
2703 opening function command.
2704 A function opens a new scope: see set(var PARENT_SCOPE) for details.
2706 See the cmake_policy() command documentation for the behavior of poli‐
2708 cies inside functions.
2709 See the macro() command documentation for differences between CMake
2711 functions and macros.
2712 Invocation
2714 The function invocation is case-insensitive. A function defined as
2715 function(foo)
2717 <commands>
2718 endfunction()
2719 can be invoked through any of
2721 foo()
2723 Foo()
2724 FOO()
2725 and so on. However, it is strongly recommended to stay with the case
2727 chosen in the function definition. Typically functions use all-lower‐
2728 case names.
2729 Arguments
2731 When the function is invoked, the recorded <commands> are first modi‐
2732 fied by replacing formal parameters (${arg1}, …) with the arguments
2733 passed, and then invoked as normal commands.
2734 In addition to referencing the formal parameters you can reference the
2736 ARGC variable which will be set to the number of arguments passed into
2737 the function as well as ARGV0, ARGV1, ARGV2, … which will have the
2738 actual values of the arguments passed in. This facilitates creating
2739 functions with optional arguments.
2740 Furthermore, ARGV holds the list of all arguments given to the function
2742 and ARGN holds the list of arguments past the last expected argument.
2743 Referencing to ARGV# arguments beyond ARGC have undefined behavior.
2744 Checking that ARGC is greater than # is the only way to ensure that
2745 ARGV# was passed to the function as an extra argument.
2746 get_cmake_property
2748 Get a global property of the CMake instance.
2749 get_cmake_property(<var> <property>)
2751 Gets a global property from the CMake instance. The value of the
2753 <property> is stored in the variable <var>. If the property is not
2754 found, <var> will be set to NOTFOUND. See the cmake-properties(7) man‐
2755 ual for available properties.
2756 See also the get_property() command GLOBAL option.
2758 In addition to global properties, this command (for historical reasons)
2760 also supports the VARIABLES and MACROS directory properties. It also
2761 supports a special COMPONENTS global property that lists the components
2762 given to the install() command.
2763 get_directory_property
2765 Get a property of DIRECTORY scope.
2766 get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
2768 Stores a property of directory scope in the named <variable>. The
2770 DIRECTORY argument specifies another directory from which to retrieve
2771 the property value instead of the current directory. The specified
2772 directory must have already been traversed by CMake.
2773 If the property is not defined for the nominated directory scope, an
2775 empty string is returned. In the case of INHERITED properties, if the
2776 property is not found for the nominated directory scope, the search
2777 will chain to a parent scope as described for the define_property()
2778 command.
2779 get_directory_property(<variable> [DIRECTORY <dir>]
2781 DEFINITION <var-name>)
2782 Get a variable definition from a directory. This form is useful to get
2784 a variable definition from another directory.
2785 See also the more general get_property() command.
2787 get_filename_component
2789 Get a specific component of a full filename.
2790 get_filename_component(<var> <FileName> <mode> [CACHE])
2792 Sets <var> to a component of <FileName>, where <mode> is one of:
2794 DIRECTORY = Directory without file name
2796 NAME = File name without directory
2797 EXT = File name longest extension (.b.c from d/a.b.c)
2798 NAME_WE = File name without directory or longest extension
2799 LAST_EXT = File name last extension (.c from d/a.b.c)
2800 NAME_WLE = File name without directory or last extension
2801 PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
2802 Paths are returned with forward slashes and have no trailing slashes.
2804 If the optional CACHE argument is specified, the result variable is
2805 added to the cache.
2806 get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
2808 Sets <var> to the absolute path of <FileName>, where <mode> is one of:
2810 ABSOLUTE = Full path to file
2812 REALPATH = Full path to existing file with symlinks resolved
2813 If the provided <FileName> is a relative path, it is evaluated relative
2815 to the given base directory <dir>. If no base directory is provided,
2816 the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
2817 Paths are returned with forward slashes and have no trailing slashes.
2819 If the optional CACHE argument is specified, the result variable is
2820 added to the cache.
2821 get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
2823 The program in <FileName> will be found in the system search path or
2825 left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
2826 command-line arguments present in the <FileName> string are split from
2827 the program name and stored in <arg_var>. This is used to separate a
2828 program name from its arguments in a command line string.
2829 get_property
2831 Get a property.
2832 get_property(<variable>
2834 <GLOBAL |
2835 DIRECTORY [<dir>] |
2836 TARGET <target> |
2837 SOURCE <source> |
2838 INSTALL <file> |
2839 TEST <test> |
2840 CACHE <entry> |
2841 VARIABLE >
2842 PROPERTY <name>
2843 [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
2844 Gets one property from one object in a scope.
2846 The first argument specifies the variable in which to store the result.
2848 The second argument determines the scope from which to get the prop‐
2849 erty. It must be one of the following:
2850 GLOBAL Scope is unique and does not accept a name.
2852 DIRECTORY
2854 Scope defaults to the current directory but another directory
2855 (already processed by CMake) may be named by the full or rela‐
2856 tive path <dir>.
2857 TARGET Scope must name one existing target.
2859 SOURCE Scope must name one source file.
2861 INSTALL
2863 Scope must name one installed file path.
2864 TEST Scope must name one existing test.
2866 CACHE Scope must name one cache entry.
2868 VARIABLE
2870 Scope is unique and does not accept a name.
2871 The required PROPERTY option is immediately followed by the name of the
2873 property to get. If the property is not set an empty value is
2874 returned, although some properties support inheriting from a parent
2875 scope if defined to behave that way (see define_property()).
2876 If the SET option is given the variable is set to a boolean value indi‐
2878 cating whether the property has been set. If the DEFINED option is
2879 given the variable is set to a boolean value indicating whether the
2880 property has been defined such as with the define_property() command.
2881 If BRIEF_DOCS or FULL_DOCS is given then the variable is set to a
2883 string containing documentation for the requested property. If docu‐
2884 mentation is requested for a property that has not been defined NOT‐
2885 FOUND is returned.
2886 if
2888 Conditionally execute a group of commands.
2889 Synopsis
2891 if(<condition>)
2892 <commands>
2893 elseif(<condition>) # optional block, can be repeated
2894 <commands>
2895 else() # optional block
2896 <commands>
2897 endif()
2898 Evaluates the condition argument of the if clause according to the
2900 Condition syntax described below. If the result is true, then the com‐
2901 mands in the if block are executed. Otherwise, optional elseif blocks
2902 are processed in the same way. Finally, if no condition is true, com‐
2903 mands in the optional else block are executed.
2904 Per legacy, the else() and endif() commands admit an optional <condi‐
2906 tion> argument. If used, it must be a verbatim repeat of the argument
2907 of the opening if command.
2908 Condition Syntax
2910 The following syntax applies to the condition argument of the if,
2911 elseif and while() clauses.
2912 Compound conditions are evaluated in the following order of precedence:
2914 Innermost parentheses are evaluated first. Next come unary tests such
2915 as EXISTS, COMMAND, and DEFINED. Then binary tests such as EQUAL,
2916 LESS, LESS_EQUAL, GREATER, GREATER_EQUAL, STREQUAL, STRLESS, STR‐
2917 LESS_EQUAL, STRGREATER, STRGREATER_EQUAL, VERSION_EQUAL, VERSION_LESS,
2918 VERSION_LESS_EQUAL, VERSION_GREATER, VERSION_GREATER_EQUAL, and
2919 MATCHES. Then the boolean operators in the order NOT, AND, and
2920 finally OR.
2921 Possible conditions are:
2923 if(<constant>)
2925 True if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
2926 ber. False if the constant is 0, OFF, NO, FALSE, N, IGNORE,
2927 NOTFOUND, the empty string, or ends in the suffix -NOTFOUND.
2928 Named boolean constants are case-insensitive. If the argument
2929 is not one of these specific constants, it is treated as a vari‐
2930 able or string and the following signature is used.
2931 if(<variable|string>)
2933 True if given a variable that is defined to a value that is not
2934 a false constant. False otherwise. (Note macro arguments are
2935 not variables.)
2936 if(NOT <condition>)
2938 True if the condition is not true.
2939 if(<cond1> AND <cond2>)
2941 True if both conditions would be considered true individually.
2942 if(<cond1> OR <cond2>)
2944 True if either condition would be considered true individually.
2945 if(COMMAND command-name)
2947 True if the given name is a command, macro or function that can
2948 be invoked.
2949 if(POLICY policy-id)
2951 True if the given name is an existing policy (of the form
2952 CMP<NNNN>).
2953 if(TARGET target-name)
2955 True if the given name is an existing logical target name cre‐
2956 ated by a call to the add_executable(), add_library(), or
2957 add_custom_target() command that has already been invoked (in
2958 any directory).
2959 if(TEST test-name)
2961 True if the given name is an existing test name created by the
2962 add_test() command.
2963 if(EXISTS path-to-file-or-directory)
2965 True if the named file or directory exists. Behavior is
2966 well-defined only for full paths. Resolves symbolic links, i.e.
2967 if the named file or directory is a symbolic link, returns true
2968 if the target of the symbolic link exists.
2969 if(file1 IS_NEWER_THAN file2)
2971 True if file1 is newer than file2 or if one of the two files
2972 doesn’t exist. Behavior is well-defined only for full paths.
2973 If the file time stamps are exactly the same, an IS_NEWER_THAN
2974 comparison returns true, so that any dependent build operations
2975 will occur in the event of a tie. This includes the case of
2976 passing the same file name for both file1 and file2.
2977 if(IS_DIRECTORY path-to-directory)
2979 True if the given name is a directory. Behavior is well-defined
2980 only for full paths.
2981 if(IS_SYMLINK file-name)
2983 True if the given name is a symbolic link. Behavior is
2984 well-defined only for full paths.
2985 if(IS_ABSOLUTE path)
2987 True if the given path is an absolute path.
2988 if(<variable|string> MATCHES regex)
2990 True if the given string or variable’s value matches the given
2991 regular condition. See Regex Specification for regex format.
2992 () groups are captured in CMAKE_MATCH_<n> variables.
2993 if(<variable|string> LESS <variable|string>)
2995 True if the given string or variable’s value is a valid number
2996 and less than that on the right.
2997 if(<variable|string> GREATER <variable|string>)
2999 True if the given string or variable’s value is a valid number
3000 and greater than that on the right.
3001 if(<variable|string> EQUAL <variable|string>)
3003 True if the given string or variable’s value is a valid number
3004 and equal to that on the right.
3005 if(<variable|string> LESS_EQUAL <variable|string>)
3007 True if the given string or variable’s value is a valid number
3008 and less than or equal to that on the right.
3009 if(<variable|string> GREATER_EQUAL <variable|string>)
3011 True if the given string or variable’s value is a valid number
3012 and greater than or equal to that on the right.
3013 if(<variable|string> STRLESS <variable|string>)
3015 True if the given string or variable’s value is lexicographi‐
3016 cally less than the string or variable on the right.
3017 if(<variable|string> STRGREATER <variable|string>)
3019 True if the given string or variable’s value is lexicographi‐
3020 cally greater than the string or variable on the right.
3021 if(<variable|string> STREQUAL <variable|string>)
3023 True if the given string or variable’s value is lexicographi‐
3024 cally equal to the string or variable on the right.
3025 if(<variable|string> STRLESS_EQUAL <variable|string>)
3027 True if the given string or variable’s value is lexicographi‐
3028 cally less than or equal to the string or variable on the right.
3029 if(<variable|string> STRGREATER_EQUAL <variable|string>)
3031 True if the given string or variable’s value is lexicographi‐
3032 cally greater than or equal to the string or variable on the
3033 right.
3034 if(<variable|string> VERSION_LESS <variable|string>)
3036 Component-wise integer version number comparison (version format
3037 is major[.minor[.patch[.tweak]]], omitted components are treated
3038 as zero). Any non-integer version component or non-integer
3039 trailing part of a version component effectively truncates the
3040 string at that point.
3041 if(<variable|string> VERSION_GREATER <variable|string>)
3043 Component-wise integer version number comparison (version format
3044 is major[.minor[.patch[.tweak]]], omitted components are treated
3045 as zero). Any non-integer version component or non-integer
3046 trailing part of a version component effectively truncates the
3047 string at that point.
3048 if(<variable|string> VERSION_EQUAL <variable|string>)
3050 Component-wise integer version number comparison (version format
3051 is major[.minor[.patch[.tweak]]], omitted components are treated
3052 as zero). Any non-integer version component or non-integer
3053 trailing part of a version component effectively truncates the
3054 string at that point.
3055 if(<variable|string> VERSION_LESS_EQUAL <variable|string>)
3057 Component-wise integer version number comparison (version format
3058 is major[.minor[.patch[.tweak]]], omitted components are treated
3059 as zero). Any non-integer version component or non-integer
3060 trailing part of a version component effectively truncates the
3061 string at that point.
3062 if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)
3064 Component-wise integer version number comparison (version format
3065 is major[.minor[.patch[.tweak]]], omitted components are treated
3066 as zero). Any non-integer version component or non-integer
3067 trailing part of a version component effectively truncates the
3068 string at that point.
3069 if(<variable|string> IN_LIST <variable>)
3071 True if the given element is contained in the named list vari‐
3072 able.
3073 if(DEFINED <name>|CACHE{<name>}|ENV{<name>})
3075 True if a variable, cache variable or environment variable with
3076 given <name> is defined. The value of the variable does not mat‐
3077 ter. Note that macro arguments are not variables.
3078 if((condition) AND (condition OR (condition)))
3080 The conditions inside the parenthesis are evaluated first and
3081 then the remaining condition is evaluated as in the previous
3082 examples. Where there are nested parenthesis the innermost are
3083 evaluated as part of evaluating the condition that contains
3084 them.
3085 Variable Expansion
3087 The if command was written very early in CMake’s history, predating the
3088 ${} variable evaluation syntax, and for convenience evaluates variables
3089 named by its arguments as shown in the above signatures. Note that
3090 normal variable evaluation with ${} applies before the if command even
3091 receives the arguments. Therefore code like
3092 set(var1 OFF)
3094 set(var2 "var1")
3095 if(${var2})
3096 appears to the if command as
3098 if(var1)
3100 and is evaluated according to the if(<variable>) case documented above.
3102 The result is OFF which is false. However, if we remove the ${} from
3103 the example then the command sees
3104 if(var2)
3106 which is true because var2 is defined to var1 which is not a false con‐
3108 stant.
3109 Automatic evaluation applies in the other cases whenever the above-doc‐
3111 umented condition syntax accepts <variable|string>:
3112 · The left hand argument to MATCHES is first checked to see if it is a
3114 defined variable, if so the variable’s value is used, otherwise the
3115 original value is used.
3116 · If the left hand argument to MATCHES is missing it returns false
3118 without error
3119 · Both left and right hand arguments to LESS, GREATER, EQUAL,
3121 LESS_EQUAL, and GREATER_EQUAL, are independently tested to see if
3122 they are defined variables, if so their defined values are used oth‐
3123 erwise the original value is used.
3124 · Both left and right hand arguments to STRLESS, STRGREATER, STREQUAL,
3126 STRLESS_EQUAL, and STRGREATER_EQUAL are independently tested to see
3127 if they are defined variables, if so their defined values are used
3128 otherwise the original value is used.
3129 · Both left and right hand arguments to VERSION_LESS, VERSION_GREATER,
3131 VERSION_EQUAL, VERSION_LESS_EQUAL, and VERSION_GREATER_EQUAL are
3132 independently tested to see if they are defined variables, if so
3133 their defined values are used otherwise the original value is used.
3134 · The right hand argument to NOT is tested to see if it is a boolean
3136 constant, if so the value is used, otherwise it is assumed to be a
3137 variable and it is dereferenced.
3138 · The left and right hand arguments to AND and OR are independently
3140 tested to see if they are boolean constants, if so they are used as
3141 such, otherwise they are assumed to be variables and are derefer‐
3142 enced.
3143 To prevent ambiguity, potential variable or keyword names can be speci‐
3145 fied in a Quoted Argument or a Bracket Argument. A quoted or bracketed
3146 variable or keyword will be interpreted as a string and not derefer‐
3147 enced or interpreted. See policy CMP0054.
3148 There is no automatic evaluation for environment or cache Variable Ref‐
3150 erences. Their values must be referenced as $ENV{<name>} or
3151 $CACHE{<name>} wherever the above-documented condition syntax accepts
3152 <variable|string>.
3153 include
3155 Load and run CMake code from a file or module.
3156 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
3158 [NO_POLICY_SCOPE])
3159 Loads and runs CMake code from the file given. Variable reads and
3161 writes access the scope of the caller (dynamic scoping). If OPTIONAL
3162 is present, then no error is raised if the file does not exist. If
3163 RESULT_VARIABLE is given the variable <var> will be set to the full
3164 filename which has been included or NOTFOUND if it failed.
3165 If a module is specified instead of a file, the file with name <module‐
3167 name>.cmake is searched first in CMAKE_MODULE_PATH, then in the CMake
3168 module directory. There is one exception to this: if the file which
3169 calls include() is located itself in the CMake builtin module direc‐
3170 tory, then first the CMake builtin module directory is searched and
3171 CMAKE_MODULE_PATH afterwards. See also policy CMP0017.
3172 See the cmake_policy() command documentation for discussion of the
3174 NO_POLICY_SCOPE option.
3175 include_guard
3177 Provides an include guard for the file currently being processed by
3178 CMake.
3179 include_guard([DIRECTORY|GLOBAL])
3181 Sets up an include guard for the current CMake file (see the CMAKE_CUR‐
3183 RENT_LIST_FILE variable documentation).
3184 CMake will end its processing of the current file at the location of
3186 the include_guard() command if the current file has already been pro‐
3187 cessed for the applicable scope (see below). This provides functional‐
3188 ity similar to the include guards commonly used in source headers or to
3189 the #pragma once directive. If the current file has been processed pre‐
3190 viously for the applicable scope, the effect is as though return() had
3191 been called. Do not call this command from inside a function being
3192 defined within the current file.
3193 An optional argument specifying the scope of the guard may be provided.
3195 Possible values for the option are:
3196 DIRECTORY
3198 The include guard applies within the current directory and
3199 below. The file will only be included once within this directory
3200 scope, but may be included again by other files outside of this
3201 directory (i.e. a parent directory or another directory not
3202 pulled in by add_subdirectory() or include() from the current
3203 file or its children).
3204 GLOBAL The include guard applies globally to the whole build. The cur‐
3206 rent file will only be included once regardless of the scope.
3207 If no arguments given, include_guard has the same scope as a variable,
3209 meaning that the include guard effect is isolated by the most recent
3210 function scope or current directory if no inner function scopes exist.
3211 In this case the command behavior is the same as:
3212 if(__CURRENT_FILE_VAR__)
3214 return()
3215 endif()
3216 set(__CURRENT_FILE_VAR__ TRUE)
3217 list
3219 List operations.
3220 Synopsis
3222 Reading
3223 list(LENGTH <list> <out-var>)
3224 list(GET <list> <element index> [<index> ...] <out-var>)
3225 list(JOIN <list> <glue> <out-var>)
3226 list(SUBLIST <list> <begin> <length> <out-var>)
3227 Search
3229 list(FIND <list> <value> <out-var>)
3230 Modification
3232 list(APPEND <list> [<element>...])
3233 list(FILTER <list> {INCLUDE | EXCLUDE} REGEX <regex>)
3234 list(INSERT <list> <index> [<element>...])
3235 list(POP_BACK <list> [<out-var>...])
3236 list(POP_FRONT <list> [<out-var>...])
3237 list(PREPEND <list> [<element>...])
3238 list(REMOVE_ITEM <list> <value>...)
3239 list(REMOVE_AT <list> <index>...)
3240 list(REMOVE_DUPLICATES <list>)
3241 list(TRANSFORM <list> <ACTION> [...])
3242 Ordering
3244 list(REVERSE <list>)
3245 list(SORT <list> [...])
3246 Introduction
3248 The list subcommands APPEND, INSERT, FILTER, PREPEND, POP_BACK,
3249 POP_FRONT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, REVERSE and SORT
3250 may create new values for the list within the current CMake variable
3251 scope. Similar to the set() command, the LIST command creates new
3252 variable values in the current scope, even if the list itself is actu‐
3253 ally defined in a parent scope. To propagate the results of these
3254 operations upwards, use set() with PARENT_SCOPE, set() with CACHE
3255 INTERNAL, or some other means of value propagation.
3256 NOTE:
3258 A list in cmake is a ; separated group of strings. To create a list
3259 the set command can be used. For example, set(var a b c d e) cre‐
3260 ates a list with a;b;c;d;e, and set(var "a b c d e") creates a
3261 string or a list with one item in it. (Note macro arguments are
3262 not variables, and therefore cannot be used in LIST commands.)
3263 NOTE:
3265 When specifying index values, if <element index> is 0 or greater, it
3266 is indexed from the beginning of the list, with 0 representing the
3267 first list element. If <element index> is -1 or lesser, it is
3268 indexed from the end of the list, with -1 representing the last list
3269 element. Be careful when counting with negative indices: they do
3270 not start from 0. -0 is equivalent to 0, the first list element.
3271 Reading
3273 list(LENGTH <list> <output variable>)
3274 Returns the list’s length.
3276 list(GET <list> <element index> [<element index> ...] <output variable>)
3278 Returns the list of elements specified by indices from the list.
3280 list(JOIN <list> <glue> <output variable>)
3282 Returns a string joining all list’s elements using the glue string. To
3284 join multiple strings, which are not part of a list, use JOIN operator
3285 from string() command.
3286 list(SUBLIST <list> <begin> <length> <output variable>)
3288 Returns a sublist of the given list. If <length> is 0, an empty list
3290 will be returned. If <length> is -1 or the list is smaller than
3291 <begin>+<length> then the remaining elements of the list starting at
3292 <begin> will be returned.
3293 Search
3295 list(FIND <list> <value> <output variable>)
3296 Returns the index of the element specified in the list or -1 if it
3298 wasn’t found.
3299 Modification
3301 list(APPEND <list> [<element> ...])
3302 Appends elements to the list.
3304 list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
3306 Includes or removes items from the list that match the mode’s pattern.
3308 In REGEX mode, items will be matched against the given regular expres‐
3309 sion.
3310 For more information on regular expressions see also the string() com‐
3312 mand.
3313 list(INSERT <list> <element_index> <element> [<element> ...])
3315 Inserts elements to the list to the specified location.
3317 list(POP_BACK <list> [<out-var>...])
3319 If no variable name is given, removes exactly one element. Otherwise,
3321 assign the last element’s value to the given variable and removes it,
3322 up to the last variable name given.
3323 list(POP_FRONT <list> [<out-var>...])
3325 If no variable name is given, removes exactly one element. Otherwise,
3327 assign the first element’s value to the given variable and removes it,
3328 up to the last variable name given.
3329 list(PREPEND <list> [<element> ...])
3331 Insert elements to the 0th position in the list.
3333 list(REMOVE_ITEM <list> <value> [<value> ...])
3335 Removes all instances of the given items from the list.
3337 list(REMOVE_AT <list> <index> [<index> ...])
3339 Removes items at given indices from the list.
3341 list(REMOVE_DUPLICATES <list>)
3343 Removes duplicated items in the list. The relative order of items is
3345 preserved, but if duplicates are encountered, only the first instance
3346 is preserved.
3347 list(TRANSFORM <list> <ACTION> [<SELECTOR>]
3349 [OUTPUT_VARIABLE <output variable>])
3350 Transforms the list by applying an action to all or, by specifying a
3352 <SELECTOR>, to the selected elements of the list, storing the result
3353 in-place or in the specified output variable.
3354 NOTE:
3356 The TRANSFORM sub-command does not change the number of elements in
3357 the list. If a <SELECTOR> is specified, only some elements will be
3358 changed, the other ones will remain the same as before the transfor‐
3359 mation.
3360 <ACTION> specifies the action to apply to the elements of the list.
3362 The actions have exactly the same semantics as sub-commands of the
3363 string() command. <ACTION> must be one of the following:
3364 APPEND, PREPEND: Append, prepend specified value to each element of the
3366 list.
3367 list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
3369 TOUPPER, TOLOWER: Convert each element of the list to upper, lower
3371 characters.
3372 list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
3374 STRIP: Remove leading and trailing spaces from each element of the
3376 list.
3377 list(TRANSFORM <list> STRIP ...)
3379 GENEX_STRIP: Strip any generator expressions from each element of the
3381 list.
3382 list(TRANSFORM <list> GENEX_STRIP ...)
3384 REPLACE: Match the regular expression as many times as possible and
3386 substitute the replacement expression for the match for each element of
3387 the list (Same semantic as REGEX REPLACE from string() command).
3388 list(TRANSFORM <list> REPLACE <regular_expression>
3390 <replace_expression> ...)
3391 <SELECTOR> determines which elements of the list will be transformed.
3393 Only one type of selector can be specified at a time. When given,
3394 <SELECTOR> must be one of the following:
3395 AT: Specify a list of indexes.
3397 list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
3399 FOR: Specify a range with, optionally, an increment used to iterate
3401 over the range.
3402 list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
3404 REGEX: Specify a regular expression. Only elements matching the regular
3406 expression will be transformed.
3407 list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
3409 Ordering
3411 list(REVERSE <list>)
3412 Reverses the contents of the list in-place.
3414 list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
3416 Sorts the list in-place alphabetically. Use the COMPARE keyword to
3418 select the comparison method for sorting. The <compare> option should
3419 be one of:
3420 · STRING: Sorts a list of strings alphabetically. This is the default
3422 behavior if the COMPARE option is not given.
3423 · FILE_BASENAME: Sorts a list of pathnames of files by their basenames.
3425 Use the CASE keyword to select a case sensitive or case insensitive
3427 sort mode. The <case> option should be one of:
3428 · SENSITIVE: List items are sorted in a case-sensitive manner. This is
3430 the default behavior if the CASE option is not given.
3431 · INSENSITIVE: List items are sorted case insensitively. The order of
3433 items which differ only by upper/lowercase is not specified.
3434 To control the sort order, the ORDER keyword can be given. The <order>
3436 option should be one of:
3437 · ASCENDING: Sorts the list in ascending order. This is the default
3439 behavior when the ORDER option is not given.
3440 · DESCENDING: Sorts the list in descending order.
3442 macro
3444 Start recording a macro for later invocation as a command
3445 macro(<name> [<arg1> ...])
3447 <commands>
3448 endmacro()
3449 Defines a macro named <name> that takes arguments named <arg1>, … Com‐
3451 mands listed after macro, but before the matching endmacro(), are not
3452 executed until the macro is invoked.
3453 Per legacy, the endmacro() command admits an optional <name> argument.
3455 If used, it must be a verbatim repeat of the argument of the opening
3456 macro command.
3457 See the cmake_policy() command documentation for the behavior of poli‐
3459 cies inside macros.
3460 See the Macro vs Function section below for differences between CMake
3462 macros and functions.
3463 Invocation
3465 The macro invocation is case-insensitive. A macro defined as
3466 macro(foo)
3468 <commands>
3469 endmacro()
3470 can be invoked through any of
3472 foo()
3474 Foo()
3475 FOO()
3476 and so on. However, it is strongly recommended to stay with the case
3478 chosen in the macro definition. Typically macros use all-lowercase
3479 names.
3480 Arguments
3482 When a macro is invoked, the commands recorded in the macro are first
3483 modified by replacing formal parameters (${arg1}, …) with the arguments
3484 passed, and then invoked as normal commands.
3485 In addition to referencing the formal parameters you can reference the
3487 values ${ARGC} which will be set to the number of arguments passed into
3488 the function as well as ${ARGV0}, ${ARGV1}, ${ARGV2}, … which will
3489 have the actual values of the arguments passed in. This facilitates
3490 creating macros with optional arguments.
3491 Furthermore, ${ARGV} holds the list of all arguments given to the macro
3493 and ${ARGN} holds the list of arguments past the last expected argu‐
3494 ment. Referencing to ${ARGV#} arguments beyond ${ARGC} have undefined
3495 behavior. Checking that ${ARGC} is greater than # is the only way to
3496 ensure that ${ARGV#} was passed to the function as an extra argument.
3497 Macro vs Function
3499 The macro command is very similar to the function() command. Nonethe‐
3500 less, there are a few important differences.
3501 In a function, ARGN, ARGC, ARGV and ARGV0, ARGV1, … are true variables
3503 in the usual CMake sense. In a macro, they are not, they are string
3504 replacements much like the C preprocessor would do with a macro. This
3505 has a number of consequences, as explained in the Argument Caveats sec‐
3506 tion below.
3507 Another difference between macros and functions is the control flow. A
3509 function is executed by transferring control from the calling statement
3510 to the function body. A macro is executed as if the macro body were
3511 pasted in place of the calling statement. This has the consequence
3512 that a return() in a macro body does not just terminate execution of
3513 the macro; rather, control is returned from the scope of the macro
3514 call. To avoid confusion, it is recommended to avoid return() in
3515 macros altogether.
3516 Argument Caveats
3518 Since ARGN, ARGC, ARGV, ARGV0 etc. are not variables, you will NOT be
3519 able to use commands like
3520 if(ARGV1) # ARGV1 is not a variable
3522 if(DEFINED ARGV2) # ARGV2 is not a variable
3523 if(ARGC GREATER 2) # ARGC is not a variable
3524 foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
3525 In the first case, you can use if(${ARGV1}). In the second and third
3527 case, the proper way to check if an optional variable was passed to the
3528 macro is to use if(${ARGC} GREATER 2). In the last case, you can use
3529 foreach(loop_var ${ARGN}) but this will skip empty arguments. If you
3530 need to include them, you can use
3531 set(list_var "${ARGN}")
3533 foreach(loop_var IN LISTS list_var)
3534 Note that if you have a variable with the same name in the scope from
3536 which the macro is called, using unreferenced names will use the exist‐
3537 ing variable instead of the arguments. For example:
3538 macro(bar)
3540 foreach(arg IN LISTS ARGN)
3541 <commands>
3542 endforeach()
3543 endmacro()
3544 function(foo)
3546 bar(x y z)
3547 endfunction()
3548 foo(a b c)
3550 Will loop over a;b;c and not over x;y;z as one might have expected. If
3552 you want true CMake variables and/or better CMake scope control you
3553 should look at the function command.
3554 mark_as_advanced
3556 Mark cmake cached variables as advanced.
3557 mark_as_advanced([CLEAR|FORCE] <var1> ...)
3559 Sets the advanced/non-advanced state of the named cached variables.
3561 An advanced variable will not be displayed in any of the cmake GUIs
3563 unless the show advanced option is on. In script mode, the
3564 advanced/non-advanced state has no effect.
3565 If the keyword CLEAR is given then advanced variables are changed back
3567 to unadvanced. If the keyword FORCE is given then the variables are
3568 made advanced. If neither FORCE nor CLEAR is specified, new values
3569 will be marked as advanced, but if a variable already has an
3570 advanced/non-advanced state, it will not be changed.
3571 math
3573 Evaluate a mathematical expression.
3574 math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])
3576 Evaluates a mathematical <expression> and sets <variable> to the
3578 resulting value. The result of the expression must be representable as
3579 a 64-bit signed integer.
3580 The mathematical expression must be given as a string (i.e. enclosed in
3582 double quotation marks). An example is "5 * (10 + 13)". Supported
3583 operators are +, -, *, /, %, |, &, ^, ~, <<, >>, and (...); they have
3584 the same meaning as in C code.
3585 Hexadecimal numbers are recognized when prefixed with 0x, as in C code.
3587 The result is formatted according to the option OUTPUT_FORMAT, where
3589 <format> is one of
3590 HEXADECIMAL
3592 Hexadecimal notation as in C code, i. e. starting with “0x”.
3593 DECIMAL
3595 Decimal notation. Which is also used if no OUTPUT_FORMAT option
3596 is specified.
3597 For example
3599 math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL) # value is set to "1000"
3601 math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL) # value is set to "0x3e8"
3602 message
3604 Display a message to the user.
3605 message([<mode>] "message to display" ...)
3607 The optional <mode> keyword determines the type of message:
3609 FATAL_ERROR
3611 CMake Error, stop processing and generation.
3612 SEND_ERROR
3614 CMake Error, continue processing, but skip generation.
3615 WARNING
3617 CMake Warning, continue processing.
3618 AUTHOR_WARNING
3620 CMake Warning (dev), continue processing.
3621 DEPRECATION
3623 CMake Deprecation Error or Warning if variable CMAKE_ERROR_DEP‐
3624 RECATED or CMAKE_WARN_DEPRECATED is enabled, respectively, else
3625 no message.
3626 (none) or NOTICE
3628 Important message printed to stderr to attract user’s attention.
3629 STATUS The main interesting messages that project users might be inter‐
3631 ested in. Ideally these should be concise, no more than a sin‐
3632 gle line, but still informative.
3633 VERBOSE
3635 Detailed informational messages intended for project users.
3636 These messages should provide additional details that won’t be
3637 of interest in most cases, but which may be useful to those
3638 building the project when they want deeper insight into what’s
3639 happening.
3640 DEBUG Detailed informational messages intended for developers working
3642 on the project itself as opposed to users who just want to build
3643 it. These messages will not typically be of interest to other
3644 users building the project and will often be closely related to
3645 internal implementation details.
3646 TRACE Fine-grained messages with very low-level implementation
3648 details. Messages using this log level would normally only be
3649 temporary and would expect to be removed before releasing the
3650 project, packaging up the files, etc.
3651 The CMake command-line tool displays STATUS to TRACE messages on stdout
3653 with the message preceded by two hyphens and a space. All other mes‐
3654 sage types are sent to stderr and are not prefixed with hyphens. The
3655 CMake GUI displays all messages in its log area. The curses interface
3656 shows STATUS to TRACE messages one at a time on a status line and other
3657 messages in an interactive pop-up box. The --log-level command-line
3658 option to each of these tools can be used to control which messages
3659 will be shown.
3660 Messages of log levels NOTICE and below will also have each line pre‐
3662 ceded by the content of the CMAKE_MESSAGE_INDENT variable (converted to
3663 a single string by concatenating its list items). For STATUS to TRACE
3664 messages, this indenting content will be inserted after the hyphens.
3665 CMake Warning and Error message text displays using a simple markup
3667 language. Non-indented text is formatted in line-wrapped paragraphs
3668 delimited by newlines. Indented text is considered pre-formatted.
3669 option
3671 Provide an option that the user can optionally select.
3672 option(<variable> "<help_text>" [value])
3674 Provides an option for the user to select as ON or OFF. If no initial
3676 <value> is provided, OFF is used. If <variable> is already set as a
3677 normal variable then the command does nothing (see policy CMP0077).
3678 If you have options that depend on the values of other options, see the
3680 module help for CMakeDependentOption.
3681 return
3683 Return from a file, directory or function.
3684 return()
3686 Returns from a file, directory or function. When this command is
3688 encountered in an included file (via include() or find_package()), it
3689 causes processing of the current file to stop and control is returned
3690 to the including file. If it is encountered in a file which is not
3691 included by another file, e.g. a CMakeLists.txt, control is returned
3692 to the parent directory if there is one. If return is called in a
3693 function, control is returned to the caller of the function.
3694 Note that a macro, unlike a function, is expanded in place and there‐
3696 fore cannot handle return().
3697 separate_arguments
3699 Parse command-line arguments into a semicolon-separated list.
3700 separate_arguments(<variable> <mode> <args>)
3702 Parses a space-separated string <args> into a list of items, and stores
3704 this list in semicolon-separated standard form in <variable>.
3705 This function is intended for parsing command-line arguments. The
3707 entire command line must be passed as one string in the argument
3708 <args>.
3709 The exact parsing rules depend on the operating system. They are spec‐
3711 ified by the <mode> argument which must be one of the following key‐
3712 words:
3713 UNIX_COMMAND
3715 Arguments are separated by by unquoted whitespace. Both sin‐
3716 gle-quote and double-quote pairs are respected. A backslash
3717 escapes the next literal character (\" is "); there are no spe‐
3718 cial escapes (\n is just n).
3719 WINDOWS_COMMAND
3721 A Windows command-line is parsed using the same syntax the run‐
3722 time library uses to construct argv at startup. It separates
3723 arguments by whitespace that is not double-quoted. Backslashes
3724 are literal unless they precede double-quotes. See the MSDN
3725 article Parsing C Command-Line Arguments for details.
3726 NATIVE_COMMAND
3728 Proceeds as in WINDOWS_COMMAND mode if the host system is Win‐
3729 dows. Otherwise proceeds as in UNIX_COMMAND mode.
3730 separate_arguments(<var>)
3732 Convert the value of <var> to a semi-colon separated list. All spaces
3734 are replaced with ‘;’. This helps with generating command lines.
3735 set
3737 Set a normal, cache, or environment variable to a given value. See the
3738 cmake-language(7) variables documentation for the scopes and interac‐
3739 tion of normal variables and cache entries.
3740 Signatures of this command that specify a <value>... placeholder expect
3742 zero or more arguments. Multiple arguments will be joined as a semi‐
3743 colon-separated list to form the actual variable value to be set. Zero
3744 arguments will cause normal variables to be unset. See the unset()
3745 command to unset variables explicitly.
3746 Set Normal Variable
3748 set(<variable> <value>... [PARENT_SCOPE])
3749 Sets the given <variable> in the current function or directory scope.
3751 If the PARENT_SCOPE option is given the variable will be set in the
3753 scope above the current scope. Each new directory or function creates
3754 a new scope. This command will set the value of a variable into the
3755 parent directory or calling function (whichever is applicable to the
3756 case at hand). The previous state of the variable’s value stays the
3757 same in the current scope (e.g., if it was undefined before, it is
3758 still undefined and if it had a value, it is still that value).
3759 Set Cache Entry
3761 set(<variable> <value>... CACHE <type> <docstring> [FORCE])
3762 Sets the given cache <variable> (cache entry). Since cache entries are
3764 meant to provide user-settable values this does not overwrite existing
3765 cache entries by default. Use the FORCE option to overwrite existing
3766 entries.
3767 The <type> must be specified as one of:
3769 BOOL Boolean ON/OFF value. cmake-gui(1) offers a checkbox.
3771 FILEPATH
3773 Path to a file on disk. cmake-gui(1) offers a file dialog.
3774 PATH Path to a directory on disk. cmake-gui(1) offers a file dialog.
3776 STRING A line of text. cmake-gui(1) offers a text field or a drop-down
3778 selection if the STRINGS cache entry property is set.
3779 INTERNAL
3781 A line of text. cmake-gui(1) does not show internal entries.
3782 They may be used to store variables persistently across runs.
3783 Use of this type implies FORCE.
3784 The <docstring> must be specified as a line of text providing a quick
3786 summary of the option for presentation to cmake-gui(1) users.
3787 If the cache entry does not exist prior to the call or the FORCE option
3789 is given then the cache entry will be set to the given value. Further‐
3790 more, any normal variable binding in the current scope will be removed
3791 to expose the newly cached value to any immediately following evalua‐
3792 tion.
3793 It is possible for the cache entry to exist prior to the call but have
3795 no type set if it was created on the cmake(1) command line by a user
3796 through the -D<var>=<value> option without specifying a type. In this
3797 case the set command will add the type. Furthermore, if the <type> is
3798 PATH or FILEPATH and the <value> provided on the command line is a rel‐
3799 ative path, then the set command will treat the path as relative to the
3800 current working directory and convert it to an absolute path.
3801 Set Environment Variable
3803 set(ENV{<variable>} [<value>])
3804 Sets an Environment Variable to the given value. Subsequent calls of
3806 $ENV{<variable>} will return this new value.
3807 This command affects only the current CMake process, not the process
3809 from which CMake was called, nor the system environment at large, nor
3810 the environment of subsequent build or test processes.
3811 If no argument is given after ENV{<variable>} or if <value> is an empty
3813 string, then this command will clear any existing value of the environ‐
3814 ment variable.
3815 Arguments after <value> are ignored. If extra arguments are found, then
3817 an author warning is issued.
3818 set_directory_properties
3820 Set properties of the current directory and subdirectories.
3821 set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...)
3823 Sets properties of the current directory and its subdirectories in
3825 key-value pairs.
3826 See also the set_property(DIRECTORY) command.
3828 See Directory Properties for the list of properties known to CMake and
3830 their individual documentation for the behavior of each property.
3831 set_property
3833 Set a named property in a given scope.
3834 set_property(<GLOBAL |
3836 DIRECTORY [<dir>] |
3837 TARGET [<target1> ...] |
3838 SOURCE [<src1> ...] |
3839 INSTALL [<file1> ...] |
3840 TEST [<test1> ...] |
3841 CACHE [<entry1> ...] >
3842 [APPEND] [APPEND_STRING]
3843 PROPERTY <name> [value1 ...])
3844 Sets one property on zero or more objects of a scope.
3846 The first argument determines the scope in which the property is set.
3848 It must be one of the following:
3849 GLOBAL Scope is unique and does not accept a name.
3851 DIRECTORY
3853 Scope defaults to the current directory but another directory
3854 (already processed by CMake) may be named by full or relative
3855 path. See also the set_directory_properties() command.
3856 TARGET Scope may name zero or more existing targets. See also the
3858 set_target_properties() command.
3859 SOURCE Scope may name zero or more source files. Note that source file
3861 properties are visible only to targets added in the same direc‐
3862 tory (CMakeLists.txt). See also the set_source_files_proper‐
3863 ties() command.
3864 INSTALL
3866 Scope may name zero or more installed file paths. These are
3867 made available to CPack to influence deployment.
3868 Both the property key and value may use generator expressions.
3870 Specific properties may apply to installed files and/or directo‐
3871 ries.
3872 Path components have to be separated by forward slashes, must be
3874 normalized and are case sensitive.
3875 To reference the installation prefix itself with a relative path
3877 use ..
3878 Currently installed file properties are only defined for the WIX
3880 generator where the given paths are relative to the installation
3881 prefix.
3882 TEST Scope may name zero or more existing tests. See also the
3884 set_tests_properties() command.
3885 CACHE Scope must name zero or more cache existing entries.
3887 The required PROPERTY option is immediately followed by the name of the
3889 property to set. Remaining arguments are used to compose the property
3890 value in the form of a semicolon-separated list.
3891 If the APPEND option is given the list is appended to any existing
3893 property value. If the APPEND_STRING option is given the string is
3894 appended to any existing property value as string, i.e. it results in a
3895 longer string and not a list of strings. When using APPEND or
3896 APPEND_STRING with a property defined to support INHERITED behavior
3897 (see define_property()), no inheriting occurs when finding the initial
3898 value to append to. If the property is not already directly set in the
3899 nominated scope, the command will behave as though APPEND or
3900 APPEND_STRING had not been given.
3901 See the cmake-properties(7) manual for a list of properties in each
3903 scope.
3904 site_name
3906 Set the given variable to the name of the computer.
3907 site_name(variable)
3909 string
3911 String operations.
3912 Synopsis
3914 Search and Replace
3915 string(FIND <string> <substring> <out-var> [...])
3916 string(REPLACE <match-string> <replace-string> <out-var> <input>...)
3917 Regular Expressions
3919 string(REGEX MATCH <match-regex> <out-var> <input>...)
3920 string(REGEX MATCHALL <match-regex> <out-var> <input>...)
3921 string(REGEX REPLACE <match-regex> <replace-expr> <out-var> <input>...)
3922 Manipulation
3924 string(APPEND <string-var> [<input>...])
3925 string(PREPEND <string-var> [<input>...])
3926 string(CONCAT <out-var> [<input>...])
3927 string(JOIN <glue> <out-var> [<input>...])
3928 string(TOLOWER <string> <out-var>)
3929 string(TOUPPER <string> <out-var>)
3930 string(LENGTH <string> <out-var>)
3931 string(SUBSTRING <string> <begin> <length> <out-var>)
3932 string(STRIP <string> <out-var>)
3933 string(GENEX_STRIP <string> <out-var>)
3934 string(REPEAT <string> <count> <out-var>)
3935 Comparison
3937 string(COMPARE <op> <string1> <string2> <out-var>)
3938 Hashing
3940 string(<HASH> <out-var> <input>)
3941 Generation
3943 string(ASCII <number>... <out-var>)
3944 string(CONFIGURE <string> <out-var> [...])
3945 string(MAKE_C_IDENTIFIER <string> <out-var>)
3946 string(RANDOM [<option>...] <out-var>)
3947 string(TIMESTAMP <out-var> [<format string>] [UTC])
3948 string(UUID <out-var> ...)
3949 Search and Replace
3951 string(FIND <string> <substring> <output_variable> [REVERSE])
3952 Return the position where the given <substring> was found in the sup‐
3954 plied <string>. If the REVERSE flag was used, the command will search
3955 for the position of the last occurrence of the specified <substring>.
3956 If the <substring> is not found, a position of -1 is returned.
3957 The string(FIND) subcommand treats all strings as ASCII-only charac‐
3959 ters. The index stored in <output_variable> will also be counted in
3960 bytes, so strings containing multi-byte characters may lead to unex‐
3961 pected results.
3962 string(REPLACE <match_string>
3964 <replace_string> <output_variable>
3965 <input> [<input>...])
3966 Replace all occurrences of <match_string> in the <input> with
3968 <replace_string> and store the result in the <output_variable>.
3969 Regular Expressions
3971 string(REGEX MATCH <regular_expression>
3972 <output_variable> <input> [<input>...])
3973 Match the <regular_expression> once and store the match in the <out‐
3975 put_variable>. All <input> arguments are concatenated before matching.
3976 string(REGEX MATCHALL <regular_expression>
3978 <output_variable> <input> [<input>...])
3979 Match the <regular_expression> as many times as possible and store the
3981 matches in the <output_variable> as a list. All <input> arguments are
3982 concatenated before matching.
3983 string(REGEX REPLACE <regular_expression>
3985 <replacement_expression> <output_variable>
3986 <input> [<input>...])
3987 Match the <regular_expression> as many times as possible and substitute
3989 the <replacement_expression> for the match in the output. All <input>
3990 arguments are concatenated before matching.
3991 The <replacement_expression> may refer to parenthesis-delimited subex‐
3993 pressions of the match using \1, \2, …, \9. Note that two backslashes
3994 (\\1) are required in CMake code to get a backslash through argument
3995 parsing.
3996 Regex Specification
3998 The following characters have special meaning in regular expressions:
3999 ^ Matches at beginning of input
4001 $ Matches at end of input
4003 . Matches any single character
4005 \<char>
4007 Matches the single character specified by <char>. Use this to
4008 match special regex characters, e.g. \. for a literal . or \\
4009 for a literal backslash \. Escaping a non-special character is
4010 unnecessary but allowed, e.g. \a matches a.
4011 [ ] Matches any character(s) inside the brackets
4013 [^ ] Matches any character(s) not inside the brackets
4015 - Inside brackets, specifies an inclusive range between characters
4017 on either side e.g. [a-f] is [abcdef] To match a literal - using
4018 brackets, make it the first or the last character e.g. [+*/-]
4019 matches basic mathematical operators.
4020 * Matches preceding pattern zero or more times
4022 + Matches preceding pattern one or more times
4024 ? Matches preceding pattern zero or once only
4026 | Matches a pattern on either side of the |
4028 () Saves a matched subexpression, which can be referenced in the
4030 REGEX REPLACE operation. Additionally it is saved by all regular
4031 expression-related commands, including e.g. if(MATCHES), in the
4032 variables CMAKE_MATCH_<n> for <n> 0..9.
4033 *, + and ? have higher precedence than concatenation. | has lower
4035 precedence than concatenation. This means that the regular expression
4036 ^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
4037 matches ab but not abd.
4038 CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
4040 to construct literal tabs, carriage returns, newlines, and backslashes
4041 (respectively) to pass in a regex. For example:
4042 · The quoted argument "[ \t\r\n]" specifies a regex that matches any
4044 single whitespace character.
4045 · The quoted argument "[/\\]" specifies a regex that matches a single
4047 forward slash / or backslash \.
4048 · The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
4050 single “word” character in the C locale.
4051 · The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
4053 the exact string (a+b). Each \\ is parsed in a quoted argument as
4054 just \, so the regex itself is actually \(\a\+\b\). This can alter‐
4055 natively be specified in a bracket argument without having to escape
4056 the backslashes, e.g. [[\(\a\+\b\)]].
4057 Manipulation
4059 string(APPEND <string_variable> [<input>...])
4060 Append all the <input> arguments to the string.
4062 string(PREPEND <string_variable> [<input>...])
4064 Prepend all the <input> arguments to the string.
4066 string(CONCAT <output_variable> [<input>...])
4068 Concatenate all the <input> arguments together and store the result in
4070 the named <output_variable>.
4071 string(JOIN <glue> <output_variable> [<input>...])
4073 Join all the <input> arguments together using the <glue> string and
4075 store the result in the named <output_variable>.
4076 To join a list’s elements, prefer to use the JOIN operator from the
4078 list() command. This allows for the elements to have special charac‐
4079 ters like ; in them.
4080 string(TOLOWER <string> <output_variable>)
4082 Convert <string> to lower characters.
4084 string(TOUPPER <string> <output_variable>)
4086 Convert <string> to upper characters.
4088 string(LENGTH <string> <output_variable>)
4090 Store in an <output_variable> a given string’s length in bytes. Note
4092 that this means if <string> contains multi-byte characters, the result
4093 stored in <output_variable> will not be the number of characters.
4094 string(SUBSTRING <string> <begin> <length> <output_variable>)
4096 Store in an <output_variable> a substring of a given <string>. If
4098 <length> is -1 the remainder of the string starting at <begin> will be
4099 returned. If <string> is shorter than <length> then the end of the
4100 string is used instead.
4101 Both <begin> and <length> are counted in bytes, so care must be exer‐
4103 cised if <string> could contain multi-byte characters.
4104 NOTE:
4106 CMake 3.1 and below reported an error if <length> pointed past the
4107 end of <string>.
4108 string(STRIP <string> <output_variable>)
4110 Store in an <output_variable> a substring of a given <string> with
4112 leading and trailing spaces removed.
4113 string(GENEX_STRIP <string> <output_variable>)
4115 Strip any generator expressions from the input <string> and store the
4117 result in the <output_variable>.
4118 string(REPEAT <string> <count> <output_variable>)
4120 Produce the output string as the input <string> repeated <count> times.
4122 Comparison
4124 string(COMPARE LESS <string1> <string2> <output_variable>)
4125 string(COMPARE GREATER <string1> <string2> <output_variable>)
4126 string(COMPARE EQUAL <string1> <string2> <output_variable>)
4127 string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
4128 string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
4129 string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
4130 Compare the strings and store true or false in the <output_variable>.
4132 Hashing
4134 string(<HASH> <output_variable> <input>)
4135 Compute a cryptographic hash of the <input> string. The supported
4137 <HASH> algorithm names are:
4138 MD5 Message-Digest Algorithm 5, RFC 1321.
4140 SHA1 US Secure Hash Algorithm 1, RFC 3174.
4142 SHA224 US Secure Hash Algorithms, RFC 4634.
4144 SHA256 US Secure Hash Algorithms, RFC 4634.
4146 SHA384 US Secure Hash Algorithms, RFC 4634.
4148 SHA512 US Secure Hash Algorithms, RFC 4634.
4150 SHA3_224
4152 Keccak SHA-3.
4153 SHA3_256
4155 Keccak SHA-3.
4156 SHA3_384
4158 Keccak SHA-3.
4159 SHA3_512
4161 Keccak SHA-3.
4162 Generation
4164 string(ASCII <number> [<number> ...] <output_variable>)
4165 Convert all numbers into corresponding ASCII characters.
4167 string(CONFIGURE <string> <output_variable>
4169 [@ONLY] [ESCAPE_QUOTES])
4170 Transform a <string> like configure_file() transforms a file.
4172 string(MAKE_C_IDENTIFIER <string> <output_variable>)
4174 Convert each non-alphanumeric character in the input <string> to an
4176 underscore and store the result in the <output_variable>. If the first
4177 character of the <string> is a digit, an underscore will also be
4178 prepended to the result.
4179 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
4181 [RANDOM_SEED <seed>] <output_variable>)
4182 Return a random string of given <length> consisting of characters from
4184 the given <alphabet>. Default length is 5 characters and default
4185 alphabet is all numbers and upper and lower case letters. If an inte‐
4186 ger RANDOM_SEED is given, its value will be used to seed the random
4187 number generator.
4188 string(TIMESTAMP <output_variable> [<format_string>] [UTC])
4190 Write a string representation of the current date and/or time to the
4192 <output_variable>.
4193 If the command is unable to obtain a timestamp, the <output_variable>
4195 will be set to the empty string "".
4196 The optional UTC flag requests the current date/time representation to
4198 be in Coordinated Universal Time (UTC) rather than local time.
4199 The optional <format_string> may contain the following format speci‐
4201 fiers:
4202 %% A literal percent sign (%).
4204 %d The day of the current month (01-31).
4205 %H The hour on a 24-hour clock (00-23).
4206 %I The hour on a 12-hour clock (01-12).
4207 %j The day of the current year (001-366).
4208 %m The month of the current year (01-12).
4209 %b Abbreviated month name (e.g. Oct).
4210 %B Full month name (e.g. October).
4211 %M The minute of the current hour (00-59).
4212 %s Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
4213 %S The second of the current minute.
4214 60 represents a leap second. (00-60)
4215 %U The week number of the current year (00-53).
4216 %w The day of the current week. 0 is Sunday. (0-6)
4217 %a Abbreviated weekday name (e.g. Fri).
4218 %A Full weekday name (e.g. Friday).
4219 %y The last two digits of the current year (00-99)
4220 %Y The current year.
4221 Unknown format specifiers will be ignored and copied to the output
4223 as-is.
4224 If no explicit <format_string> is given, it will default to:
4226 %Y-%m-%dT%H:%M:%S for local time.
4228 %Y-%m-%dT%H:%M:%SZ for UTC.
4229 NOTE:
4231 If the SOURCE_DATE_EPOCH environment variable is set, its value will
4232 be used instead of the current time. See
4233 https://reproducible-builds.org/specs/source-date-epoch/ for
4234 details.
4235 string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
4237 TYPE <MD5|SHA1> [UPPER])
4238 Create a universally unique identifier (aka GUID) as per RFC4122 based
4240 on the hash of the combined values of <namespace> (which itself has to
4241 be a valid UUID) and <name>. The hash algorithm can be either MD5
4242 (Version 3 UUID) or SHA1 (Version 5 UUID). A UUID has the format
4243 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where each x represents a lower
4244 case hexadecimal character. Where required, an uppercase representa‐
4245 tion can be requested with the optional UPPER flag.
4246 unset
4248 Unset a variable, cache variable, or environment variable.
4249 Unset Normal Variable or Cache Entry
4251 unset(<variable> [CACHE | PARENT_SCOPE])
4252 Removes a normal variable from the current scope, causing it to become
4254 undefined. If CACHE is present, then a cache variable is removed
4255 instead of a normal variable. Note that when evaluating Variable Ref‐
4256 erences of the form ${VAR}, CMake first searches for a normal variable
4257 with that name. If no such normal variable exists, CMake will then
4258 search for a cache entry with that name. Because of this unsetting a
4259 normal variable can expose a cache variable that was previously hidden.
4260 To force a variable reference of the form ${VAR} to return an empty
4261 string, use set(<variable> ""), which clears the normal variable but
4262 leaves it defined.
4263 If PARENT_SCOPE is present then the variable is removed from the scope
4265 above the current scope. See the same option in the set() command for
4266 further details.
4267 Unset Environment Variable
4269 unset(ENV{<variable>})
4270 Removes <variable> from the currently available Environment Variables.
4272 Subsequent calls of $ENV{<variable>} will return the empty string.
4273 This command affects only the current CMake process, not the process
4275 from which CMake was called, nor the system environment at large, nor
4276 the environment of subsequent build or test processes.
4277 variable_watch
4279 Watch the CMake variable for change.
4280 variable_watch(<variable> [<command>])
4282 If the specified <variable> changes, a message will be printed to
4284 inform about the change.
4285 Additionally, if <command> is given, this command will be executed.
4287 The command will receive the following arguments: COMMAND(<variable>
4288 <access> <value> <current_list_file> <stack>)
4289 while
4291 Evaluate a group of commands while a condition is true
4292 while(<condition>)
4294 <commands>
4295 endwhile()
4296 All commands between while and the matching endwhile() are recorded
4298 without being invoked. Once the endwhile() is evaluated, the recorded
4299 list of commands is invoked as long as the <condition> is true.
4300 The <condition> has the same syntax and is evaluated using the same
4302 logic as described at length for the if() command.
4303 The commands break() and continue() provide means to escape from the
4305 normal control flow.
4306 Per legacy, the endwhile() command admits an optional <condition> argu‐
4308 ment. If used, it must be a verbatim repeat of the argument of the
4309 opening while command.
4310
4312 These commands are available only in CMake projects.
4313 add_compile_definitions
4315 Add preprocessor definitions to the compilation of source files.
4316 add_compile_definitions(<definition> ...)
4318 Adds preprocessor definitions to the compiler command line for targets
4320 in the current directory and below (whether added before or after this
4321 command is invoked). See documentation of the directory and target COM‐
4322 PILE_DEFINITIONS properties.
4323 Definitions are specified using the syntax VAR or VAR=value. Func‐
4325 tion-style definitions are not supported. CMake will automatically
4326 escape the value correctly for the native build system (note that CMake
4327 language syntax may require escapes to specify some values).
4328 Arguments to add_compile_definitions may use “generator expressions”
4330 with the syntax $<...>. See the cmake-generator-expressions(7) manual
4331 for available expressions. See the cmake-buildsystem(7) manual for
4332 more on defining buildsystem properties.
4333 add_compile_options
4335 Add options to the compilation of source files.
4336 add_compile_options(<option> ...)
4338 Adds options to the COMPILE_OPTIONS directory property. These options
4340 are used when compiling targets from the current directory and below.
4341 Arguments
4343 Arguments to add_compile_options may use “generator expressions” with
4344 the syntax $<...>. See the cmake-generator-expressions(7) manual for
4345 available expressions. See the cmake-buildsystem(7) manual for more on
4346 defining buildsystem properties.
4347 The final set of compile or link options used for a target is con‐
4349 structed by accumulating options from the current target and the usage
4350 requirements of its dependencies. The set of options is de-duplicated
4351 to avoid repetition. While beneficial for individual options, the
4352 de-duplication step can break up option groups. For example, -D A -D B
4353 becomes -D A B. One may specify a group of options using shell-like
4354 quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and
4355 the rest of the option string is parsed using the separate_arguments()
4356 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
4357 -D B.
4358 Example
4360 Since different compilers support different options, a typical use of
4361 this command is in a compiler-specific conditional clause:
4362 if (MSVC)
4364 # warning level 4 and all warnings as errors
4365 add_compile_options(/W4 /WX)
4366 else()
4367 # lots of warnings and all warnings as errors
4368 add_compile_options(-Wall -Wextra -pedantic -Werror)
4369 endif()
4370 See Also
4372 This command can be used to add any options. However, for adding pre‐
4373 processor definitions and include directories it is recommended to use
4374 the more specific commands add_compile_definitions() and include_direc‐
4375 tories().
4376 The command target_compile_options() adds target-specific options.
4378 add_custom_command
4380 Add a custom build rule to the generated build system.
4381 There are two main signatures for add_custom_command.
4383 Generating Files
4385 The first signature is for adding a custom command to produce an out‐
4386 put:
4387 add_custom_command(OUTPUT output1 [output2 ...]
4389 COMMAND command1 [ARGS] [args1...]
4390 [COMMAND command2 [ARGS] [args2...] ...]
4391 [MAIN_DEPENDENCY depend]
4392 [DEPENDS [depends...]]
4393 [BYPRODUCTS [files...]]
4394 [IMPLICIT_DEPENDS <lang1> depend1
4395 [<lang2> depend2] ...]
4396 [WORKING_DIRECTORY dir]
4397 [COMMENT comment]
4398 [DEPFILE depfile]
4399 [JOB_POOL job_pool]
4400 [VERBATIM] [APPEND] [USES_TERMINAL]
4401 [COMMAND_EXPAND_LISTS])
4402 This defines a command to generate specified OUTPUT file(s). A target
4404 created in the same directory (CMakeLists.txt file) that specifies any
4405 output of the custom command as a source file is given a rule to gener‐
4406 ate the file using the command at build time. Do not list the output
4407 in more than one independent target that may build in parallel or the
4408 two instances of the rule may conflict (instead use the add_custom_tar‐
4409 get() command to drive the command and make the other targets depend on
4410 that one). In makefile terms this creates a new target in the follow‐
4411 ing form:
4412 OUTPUT: MAIN_DEPENDENCY DEPENDS
4414 COMMAND
4415 The options are:
4417 APPEND Append the COMMAND and DEPENDS option values to the custom com‐
4419 mand for the first output specified. There must have already
4420 been a previous call to this command with the same output. The
4421 COMMENT, MAIN_DEPENDENCY, and WORKING_DIRECTORY options are cur‐
4422 rently ignored when APPEND is given, but may be used in the
4423 future.
4424 BYPRODUCTS
4426 Specify the files the command is expected to produce but whose
4427 modification time may or may not be newer than the dependencies.
4428 If a byproduct name is a relative path it will be interpreted
4429 relative to the build tree directory corresponding to the cur‐
4430 rent source directory. Each byproduct file will be marked with
4431 the GENERATED source file property automatically.
4432 Explicit specification of byproducts is supported by the Ninja
4434 generator to tell the ninja build tool how to regenerate byprod‐
4435 ucts when they are missing. It is also useful when other build
4436 rules (e.g. custom commands) depend on the byproducts. Ninja
4437 requires a build rule for any generated file on which another
4438 rule depends even if there are order-only dependencies to ensure
4439 the byproducts will be available before their dependents build.
4440 COMMAND
4442 Specify the command-line(s) to execute at build time. If more
4443 than one COMMAND is specified they will be executed in order,
4444 but not necessarily composed into a stateful shell or batch
4445 script. (To run a full script, use the configure_file() command
4446 or the file(GENERATE) command to create it, and then specify a
4447 COMMAND to launch it.) The optional ARGS argument is for back‐
4448 ward compatibility and will be ignored.
4449 If COMMAND specifies an executable target name (created by the
4451 add_executable() command), it will automatically be replaced by
4452 the location of the executable created at build time if either
4453 of the following is true:
4454 · The target is not being cross-compiled (i.e. the CMAKE_CROSS‐
4456 COMPILING variable is not set to true).
4457 · The target is being cross-compiled and an emulator is provided
4459 (i.e. its CROSSCOMPILING_EMULATOR target property is set).
4460 In this case, the contents of CROSSCOMPILING_EMULATOR will be
4461 prepended to the command before the location of the target
4462 executable.
4463 If neither of the above conditions are met, it is assumed that
4465 the command name is a program to be found on the PATH at build
4466 time.
4467 Arguments to COMMAND may use generator expressions. Use the
4469 TARGET_FILE generator expression to refer to the location of a
4470 target later in the command line (i.e. as a command argument
4471 rather than as the command to execute).
4472 Whenever a target is used as a command to execute or is men‐
4474 tioned in a generator expression as a command argument, a tar‐
4475 get-level dependency will be added automatically so that the
4476 mentioned target will be built before any target using this cus‐
4477 tom command. However this does NOT add a file-level dependency
4478 that would cause the custom command to re-run whenever the exe‐
4479 cutable is recompiled. List target names with the DEPENDS
4480 option to add such file-level dependencies.
4481 COMMENT
4483 Display the given message before the commands are executed at
4484 build time.
4485 DEPENDS
4487 Specify files on which the command depends. If any dependency
4488 is an OUTPUT of another custom command in the same directory
4489 (CMakeLists.txt file) CMake automatically brings the other cus‐
4490 tom command into the target in which this command is built. A
4491 target-level dependency is added if any dependency is listed as
4492 BYPRODUCTS of a target or any of its build events in the same
4493 directory to ensure the byproducts will be available. If
4494 DEPENDS is not specified the command will run whenever the OUT‐
4495 PUT is missing; if the command does not actually create the OUT‐
4496 PUT then the rule will always run. If DEPENDS specifies any
4497 target (created by the add_custom_target(), add_executable(), or
4498 add_library() command) a target-level dependency is created to
4499 make sure the target is built before any target using this cus‐
4500 tom command. Additionally, if the target is an executable or
4501 library a file-level dependency is created to cause the custom
4502 command to re-run whenever the target is recompiled.
4503 Arguments to DEPENDS may use generator expressions.
4505 COMMAND_EXPAND_LISTS
4507 Lists in COMMAND arguments will be expanded, including those
4508 created with generator expressions, allowing COMMAND arguments
4509 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
4510 RIES>,;-I>" foo.cc to be properly expanded.
4511 IMPLICIT_DEPENDS
4513 Request scanning of implicit dependencies of an input file. The
4514 language given specifies the programming language whose corre‐
4515 sponding dependency scanner should be used. Currently only C
4516 and CXX language scanners are supported. The language has to be
4517 specified for every file in the IMPLICIT_DEPENDS list. Depen‐
4518 dencies discovered from the scanning are added to those of the
4519 custom command at build time. Note that the IMPLICIT_DEPENDS
4520 option is currently supported only for Makefile generators and
4521 will be ignored by other generators.
4522 JOB_POOL
4524 Specify a pool for the Ninja generator. Incompatible with
4525 USES_TERMINAL, which implies the console pool. Using a pool
4526 that is not defined by JOB_POOLS causes an error by ninja at
4527 build time.
4528 MAIN_DEPENDENCY
4530 Specify the primary input source file to the command. This is
4531 treated just like any value given to the DEPENDS option but also
4532 suggests to Visual Studio generators where to hang the custom
4533 command. Each source file may have at most one command specify‐
4534 ing it as its main dependency. A compile command (i.e. for a
4535 library or an executable) counts as an implicit main dependency
4536 which gets silently overwritten by a custom command specifica‐
4537 tion.
4538 OUTPUT Specify the output files the command is expected to produce. If
4540 an output name is a relative path it will be interpreted rela‐
4541 tive to the build tree directory corresponding to the current
4542 source directory. Each output file will be marked with the GEN‐
4543 ERATED source file property automatically. If the output of the
4544 custom command is not actually created as a file on disk it
4545 should be marked with the SYMBOLIC source file property.
4546 USES_TERMINAL
4548 The command will be given direct access to the terminal if pos‐
4549 sible. With the Ninja generator, this places the command in the
4550 console pool.
4551 VERBATIM
4553 All arguments to the commands will be escaped properly for the
4554 build tool so that the invoked command receives each argument
4555 unchanged. Note that one level of escapes is still used by the
4556 CMake language processor before add_custom_command even sees the
4557 arguments. Use of VERBATIM is recommended as it enables correct
4558 behavior. When VERBATIM is not given the behavior is platform
4559 specific because there is no protection of tool-specific special
4560 characters.
4561 WORKING_DIRECTORY
4563 Execute the command with the given current working directory.
4564 If it is a relative path it will be interpreted relative to the
4565 build tree directory corresponding to the current source direc‐
4566 tory.
4567 Arguments to WORKING_DIRECTORY may use generator expressions.
4569 DEPFILE
4571 Specify a .d depfile for the Ninja generator. A .d file holds
4572 dependencies usually emitted by the custom command itself.
4573 Using DEPFILE with other generators than Ninja is an error.
4574 Build Events
4576 The second signature adds a custom command to a target such as a
4577 library or executable. This is useful for performing an operation
4578 before or after building the target. The command becomes part of the
4579 target and will only execute when the target itself is built. If the
4580 target is already built, the command will not execute.
4581 add_custom_command(TARGET <target>
4583 PRE_BUILD | PRE_LINK | POST_BUILD
4584 COMMAND command1 [ARGS] [args1...]
4585 [COMMAND command2 [ARGS] [args2...] ...]
4586 [BYPRODUCTS [files...]]
4587 [WORKING_DIRECTORY dir]
4588 [COMMENT comment]
4589 [VERBATIM] [USES_TERMINAL]
4590 [COMMAND_EXPAND_LISTS])
4591 This defines a new command that will be associated with building the
4593 specified <target>. The <target> must be defined in the current direc‐
4594 tory; targets defined in other directories may not be specified.
4595 When the command will happen is determined by which of the following is
4597 specified:
4598 PRE_BUILD
4600 On Visual Studio Generators, run before any other rules are exe‐
4601 cuted within the target. On other generators, run just before
4602 PRE_LINK commands.
4603 PRE_LINK
4605 Run after sources have been compiled but before linking the
4606 binary or running the librarian or archiver tool of a static
4607 library. This is not defined for targets created by the
4608 add_custom_target() command.
4609 POST_BUILD
4611 Run after all other rules within the target have been executed.
4612 NOTE:
4614 Because generator expressions can be used in custom commands, it is
4615 possible to define COMMAND lines or whole custom commands which
4616 evaluate to empty strings for certain configurations. For Visual
4617 Studio 2010 (and newer) generators these command lines or custom
4618 commands will be omitted for the specific configuration and no
4619 “empty-string-command” will be added.
4620 This allows to add individual build events for every configuration.
4622 add_custom_target
4624 Add a target with no output so it will always be built.
4625 add_custom_target(Name [ALL] [command1 [args1...]]
4627 [COMMAND command2 [args2...] ...]
4628 [DEPENDS depend depend depend ... ]
4629 [BYPRODUCTS [files...]]
4630 [WORKING_DIRECTORY dir]
4631 [COMMENT comment]
4632 [JOB_POOL job_pool]
4633 [VERBATIM] [USES_TERMINAL]
4634 [COMMAND_EXPAND_LISTS]
4635 [SOURCES src1 [src2...]])
4636 Adds a target with the given name that executes the given commands.
4638 The target has no output file and is always considered out of date even
4639 if the commands try to create a file with the name of the target. Use
4640 the add_custom_command() command to generate a file with dependencies.
4641 By default nothing depends on the custom target. Use the add_dependen‐
4642 cies() command to add dependencies to or from other targets.
4643 The options are:
4645 ALL Indicate that this target should be added to the default build
4647 target so that it will be run every time (the command cannot be
4648 called ALL).
4649 BYPRODUCTS
4651 Specify the files the command is expected to produce but whose
4652 modification time may or may not be updated on subsequent
4653 builds. If a byproduct name is a relative path it will be
4654 interpreted relative to the build tree directory corresponding
4655 to the current source directory. Each byproduct file will be
4656 marked with the GENERATED source file property automatically.
4657 Explicit specification of byproducts is supported by the Ninja
4659 generator to tell the ninja build tool how to regenerate byprod‐
4660 ucts when they are missing. It is also useful when other build
4661 rules (e.g. custom commands) depend on the byproducts. Ninja
4662 requires a build rule for any generated file on which another
4663 rule depends even if there are order-only dependencies to ensure
4664 the byproducts will be available before their dependents build.
4665 COMMAND
4667 Specify the command-line(s) to execute at build time. If more
4668 than one COMMAND is specified they will be executed in order,
4669 but not necessarily composed into a stateful shell or batch
4670 script. (To run a full script, use the configure_file() command
4671 or the file(GENERATE) command to create it, and then specify a
4672 COMMAND to launch it.)
4673 If COMMAND specifies an executable target name (created by the
4675 add_executable() command), it will automatically be replaced by
4676 the location of the executable created at build time if either
4677 of the following is true:
4678 · The target is not being cross-compiled (i.e. the CMAKE_CROSS‐
4680 COMPILING variable is not set to true).
4681 · The target is being cross-compiled and an emulator is provided
4683 (i.e. its CROSSCOMPILING_EMULATOR target property is set).
4684 In this case, the contents of CROSSCOMPILING_EMULATOR will be
4685 prepended to the command before the location of the target
4686 executable.
4687 If neither of the above conditions are met, it is assumed that
4689 the command name is a program to be found on the PATH at build
4690 time.
4691 Arguments to COMMAND may use generator expressions. Use the
4693 TARGET_FILE generator expression to refer to the location of a
4694 target later in the command line (i.e. as a command argument
4695 rather than as the command to execute).
4696 Whenever a target is used as a command to execute or is men‐
4698 tioned in a generator expression as a command argument, a tar‐
4699 get-level dependency will be added automatically so that the
4700 mentioned target will be built before this custom target.
4701 The command and arguments are optional and if not specified an
4703 empty target will be created.
4704 COMMENT
4706 Display the given message before the commands are executed at
4707 build time.
4708 DEPENDS
4710 Reference files and outputs of custom commands created with
4711 add_custom_command() command calls in the same directory (CMake‐
4712 Lists.txt file). They will be brought up to date when the tar‐
4713 get is built. A target-level dependency is added if any depen‐
4714 dency is a byproduct of a target or any of its build events in
4715 the same directory to ensure the byproducts will be available
4716 before this target is built.
4717 Use the add_dependencies() command to add dependencies on other
4719 targets.
4720 COMMAND_EXPAND_LISTS
4722 Lists in COMMAND arguments will be expanded, including those
4723 created with generator expressions, allowing COMMAND arguments
4724 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
4725 RIES>,;-I>" foo.cc to be properly expanded.
4726 JOB_POOL
4728 Specify a pool for the Ninja generator. Incompatible with
4729 USES_TERMINAL, which implies the console pool. Using a pool
4730 that is not defined by JOB_POOLS causes an error by ninja at
4731 build time.
4732 SOURCES
4734 Specify additional source files to be included in the custom
4735 target. Specified source files will be added to IDE project
4736 files for convenience in editing even if they have no build
4737 rules.
4738 VERBATIM
4740 All arguments to the commands will be escaped properly for the
4741 build tool so that the invoked command receives each argument
4742 unchanged. Note that one level of escapes is still used by the
4743 CMake language processor before add_custom_target even sees the
4744 arguments. Use of VERBATIM is recommended as it enables correct
4745 behavior. When VERBATIM is not given the behavior is platform
4746 specific because there is no protection of tool-specific special
4747 characters.
4748 USES_TERMINAL
4750 The command will be given direct access to the terminal if pos‐
4751 sible. With the Ninja generator, this places the command in the
4752 console pool.
4753 WORKING_DIRECTORY
4755 Execute the command with the given current working directory.
4756 If it is a relative path it will be interpreted relative to the
4757 build tree directory corresponding to the current source direc‐
4758 tory.
4759 Arguments to WORKING_DIRECTORY may use generator expressions.
4761 add_definitions
4763 Add -D define flags to the compilation of source files.
4764 add_definitions(-DFOO -DBAR ...)
4766 Adds definitions to the compiler command line for targets in the cur‐
4768 rent directory and below (whether added before or after this command is
4769 invoked). This command can be used to add any flags, but it is
4770 intended to add preprocessor definitions.
4771 NOTE:
4773 This command has been superseded by alternatives:
4774 · Use add_compile_definitions() to add preprocessor definitions.
4776 · Use include_directories() to add include directories.
4778 · Use add_compile_options() to add other options.
4780 Flags beginning in -D or /D that look like preprocessor definitions are
4782 automatically added to the COMPILE_DEFINITIONS directory property for
4783 the current directory. Definitions with non-trivial values may be left
4784 in the set of flags instead of being converted for reasons of backwards
4785 compatibility. See documentation of the directory, target, source file
4786 COMPILE_DEFINITIONS properties for details on adding preprocessor defi‐
4787 nitions to specific scopes and configurations.
4788 See the cmake-buildsystem(7) manual for more on defining buildsystem
4790 properties.
4791 add_dependencies
4793 Add a dependency between top-level targets.
4794 add_dependencies(<target> [<target-dependency>]...)
4796 Makes a top-level <target> depend on other top-level targets to ensure
4798 that they build before <target> does. A top-level target is one cre‐
4799 ated by one of the add_executable(), add_library(), or add_custom_tar‐
4800 get() commands (but not targets generated by CMake like install).
4801 Dependencies added to an imported target or an interface library are
4803 followed transitively in its place since the target itself does not
4804 build.
4805 See the DEPENDS option of add_custom_target() and add_custom_command()
4807 commands for adding file-level dependencies in custom rules. See the
4808 OBJECT_DEPENDS source file property to add file-level dependencies to
4809 object files.
4810 add_executable
4812 Add an executable to the project using the specified source files.
4813 add_executable(<name> [WIN32] [MACOSX_BUNDLE]
4815 [EXCLUDE_FROM_ALL]
4816 [source1] [source2 ...])
4817 Adds an executable target called <name> to be built from the source
4819 files listed in the command invocation. (The source files can be omit‐
4820 ted here if they are added later using target_sources().) The <name>
4821 corresponds to the logical target name and must be globally unique
4822 within a project. The actual file name of the executable built is con‐
4823 structed based on conventions of the native platform (such as
4824 <name>.exe or just <name>).
4825 By default the executable file will be created in the build tree direc‐
4827 tory corresponding to the source tree directory in which the command
4828 was invoked. See documentation of the RUNTIME_OUTPUT_DIRECTORY target
4829 property to change this location. See documentation of the OUTPUT_NAME
4830 target property to change the <name> part of the final file name.
4831 If WIN32 is given the property WIN32_EXECUTABLE will be set on the tar‐
4833 get created. See documentation of that target property for details.
4834 If MACOSX_BUNDLE is given the corresponding property will be set on the
4836 created target. See documentation of the MACOSX_BUNDLE target property
4837 for details.
4838 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
4840 the created target. See documentation of the EXCLUDE_FROM_ALL target
4841 property for details.
4842 Source arguments to add_executable may use “generator expressions” with
4844 the syntax $<...>. See the cmake-generator-expressions(7) manual for
4845 available expressions. See the cmake-buildsystem(7) manual for more on
4846 defining buildsystem properties.
4847 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
4849 cessed, and you want to have the original sources reachable from within
4850 IDE.
4851 ----
4854 add_executable(<name> IMPORTED [GLOBAL])
4858 An IMPORTED executable target references an executable file located
4860 outside the project. No rules are generated to build it, and the
4861 IMPORTED target property is True. The target name has scope in the
4862 directory in which it is created and below, but the GLOBAL option
4863 extends visibility. It may be referenced like any target built within
4864 the project. IMPORTED executables are useful for convenient reference
4865 from commands like add_custom_command(). Details about the imported
4866 executable are specified by setting properties whose names begin in
4867 IMPORTED_. The most important such property is IMPORTED_LOCATION (and
4868 its per-configuration version IMPORTED_LOCATION_<CONFIG>) which speci‐
4869 fies the location of the main executable file on disk. See documenta‐
4870 tion of the IMPORTED_* properties for more information.
4871 ----
4874 add_executable(<name> ALIAS <target>)
4878 Creates an Alias Target, such that <name> can be used to refer to <tar‐
4880 get> in subsequent commands. The <name> does not appear in the gener‐
4881 ated buildsystem as a make target. The <target> may not be a
4882 non-GLOBAL Imported Target or an ALIAS. ALIAS targets can be used as
4883 targets to read properties from, executables for custom commands and
4884 custom targets. They can also be tested for existence with the regular
4885 if(TARGET) subcommand. The <name> may not be used to modify properties
4886 of <target>, that is, it may not be used as the operand of set_prop‐
4887 erty(), set_target_properties(), target_link_libraries() etc. An ALIAS
4888 target may not be installed or exported.
4889 add_library
4891 Add a library to the project using the specified source files.
4892 Normal Libraries
4894 add_library(<name> [STATIC | SHARED | MODULE]
4895 [EXCLUDE_FROM_ALL]
4896 [source1] [source2 ...])
4897 Adds a library target called <name> to be built from the source files
4899 listed in the command invocation. (The source files can be omitted
4900 here if they are added later using target_sources().) The <name> cor‐
4901 responds to the logical target name and must be globally unique within
4902 a project. The actual file name of the library built is constructed
4903 based on conventions of the native platform (such as lib<name>.a or
4904 <name>.lib).
4905 STATIC, SHARED, or MODULE may be given to specify the type of library
4907 to be created. STATIC libraries are archives of object files for use
4908 when linking other targets. SHARED libraries are linked dynamically
4909 and loaded at runtime. MODULE libraries are plugins that are not
4910 linked into other targets but may be loaded dynamically at runtime
4911 using dlopen-like functionality. If no type is given explicitly the
4912 type is STATIC or SHARED based on whether the current value of the
4913 variable BUILD_SHARED_LIBS is ON. For SHARED and MODULE libraries the
4914 POSITION_INDEPENDENT_CODE target property is set to ON automatically.
4915 A SHARED or STATIC library may be marked with the FRAMEWORK target
4916 property to create an macOS Framework.
4917 If a library does not export any symbols, it must not be declared as a
4919 SHARED library. For example, a Windows resource DLL or a managed
4920 C++/CLI DLL that exports no unmanaged symbols would need to be a MODULE
4921 library. This is because CMake expects a SHARED library to always have
4922 an associated import library on Windows.
4923 By default the library file will be created in the build tree directory
4925 corresponding to the source tree directory in which the command was
4926 invoked. See documentation of the ARCHIVE_OUTPUT_DIRECTORY,
4927 LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY target proper‐
4928 ties to change this location. See documentation of the OUTPUT_NAME
4929 target property to change the <name> part of the final file name.
4930 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
4932 the created target. See documentation of the EXCLUDE_FROM_ALL target
4933 property for details.
4934 Source arguments to add_library may use “generator expressions” with
4936 the syntax $<...>. See the cmake-generator-expressions(7) manual for
4937 available expressions. See the cmake-buildsystem(7) manual for more on
4938 defining buildsystem properties.
4939 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
4941 cessed, and you want to have the original sources reachable from within
4942 IDE.
4943 Imported Libraries
4945 add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED
4946 [GLOBAL])
4947 An IMPORTED library target references a library file located outside
4949 the project. No rules are generated to build it, and the IMPORTED tar‐
4950 get property is True. The target name has scope in the directory in
4951 which it is created and below, but the GLOBAL option extends visibil‐
4952 ity. It may be referenced like any target built within the project.
4953 IMPORTED libraries are useful for convenient reference from commands
4954 like target_link_libraries(). Details about the imported library are
4955 specified by setting properties whose names begin in IMPORTED_ and
4956 INTERFACE_.
4957 The most important properties are:
4959 · IMPORTED_LOCATION (and its per-configuration variant IMPORTED_LOCA‐
4961 TION_<CONFIG>) which specifies the location of the main library file
4962 on disk.
4963 · IMPORTED_OBJECTS (and IMPORTED_OBJECTS_<CONFIG>) for object
4965 libraries, specifies the locations of object files on disk.
4966 · PUBLIC_HEADER files to be installed during install() invocation
4968 See documentation of the IMPORTED_* and INTERFACE_* properties for more
4970 information.
4971 An UNKNOWN library type is typically only used in the implementation of
4973 Find Modules. It allows the path to an imported library (often found
4974 using the find_library() command) to be used without having to know
4975 what type of library it is. This is especially useful on Windows where
4976 a static library and a DLL’s import library both have the same file
4977 extension.
4978 Object Libraries
4980 add_library(<name> OBJECT <src>...)
4981 Creates an Object Library. An object library compiles source files but
4983 does not archive or link their object files into a library. Instead
4984 other targets created by add_library() or add_executable() may refer‐
4985 ence the objects using an expression of the form $<TAR‐
4986 GET_OBJECTS:objlib> as a source, where objlib is the object library
4987 name. For example:
4988 add_library(... $<TARGET_OBJECTS:objlib> ...)
4990 add_executable(... $<TARGET_OBJECTS:objlib> ...)
4991 will include objlib’s object files in a library and an executable along
4993 with those compiled from their own sources. Object libraries may con‐
4994 tain only sources that compile, header files, and other files that
4995 would not affect linking of a normal library (e.g. .txt). They may
4996 contain custom commands generating such sources, but not PRE_BUILD,
4997 PRE_LINK, or POST_BUILD commands. Some native build systems (such as
4998 Xcode) may not like targets that have only object files, so consider
4999 adding at least one real source file to any target that references
5000 $<TARGET_OBJECTS:objlib>.
5001 Alias Libraries
5003 add_library(<name> ALIAS <target>)
5004 Creates an Alias Target, such that <name> can be used to refer to <tar‐
5006 get> in subsequent commands. The <name> does not appear in the gener‐
5007 ated buildsystem as a make target. The <target> may not be a
5008 non-GLOBAL Imported Target or an ALIAS. ALIAS targets can be used as
5009 linkable targets and as targets to read properties from. They can also
5010 be tested for existence with the regular if(TARGET) subcommand. The
5011 <name> may not be used to modify properties of <target>, that is, it
5012 may not be used as the operand of set_property(), set_target_proper‐
5013 ties(), target_link_libraries() etc. An ALIAS target may not be
5014 installed or exported.
5015 Interface Libraries
5017 add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
5018 Creates an Interface Library. An INTERFACE library target does not
5020 directly create build output, though it may have properties set on it
5021 and it may be installed, exported and imported. Typically the INTER‐
5022 FACE_* properties are populated on the interface target using the com‐
5023 mands:
5024 · set_property(),
5026 · target_link_libraries(INTERFACE),
5028 · target_link_options(INTERFACE),
5030 · target_include_directories(INTERFACE),
5032 · target_compile_options(INTERFACE),
5034 · target_compile_definitions(INTERFACE), and
5036 · target_sources(INTERFACE),
5038 and then it is used as an argument to target_link_libraries() like any
5040 other target.
5041 An INTERFACE Imported Target may also be created with this signature.
5043 An IMPORTED library target references a library defined outside the
5044 project. The target name has scope in the directory in which it is
5045 created and below, but the GLOBAL option extends visibility. It may be
5046 referenced like any target built within the project. IMPORTED
5047 libraries are useful for convenient reference from commands like tar‐
5048 get_link_libraries().
5049 add_link_options
5051 Add options to the link step for executable, shared library or module
5052 library targets in the current directory and below that are added after
5053 this command is invoked.
5054 add_link_options(<option> ...)
5056 This command can be used to add any link options, but alternative com‐
5058 mands exist to add libraries (target_link_libraries() or
5059 link_libraries()). See documentation of the directory and target
5060 LINK_OPTIONS properties.
5061 NOTE:
5063 This command cannot be used to add options for static library tar‐
5064 gets, since they do not use a linker. To add archiver or MSVC
5065 librarian flags, see the STATIC_LIBRARY_OPTIONS target property.
5066 Arguments to add_link_options may use “generator expressions” with the
5068 syntax $<...>. See the cmake-generator-expressions(7) manual for
5069 available expressions. See the cmake-buildsystem(7) manual for more on
5070 defining buildsystem properties.
5071 The final set of compile or link options used for a target is con‐
5073 structed by accumulating options from the current target and the usage
5074 requirements of its dependencies. The set of options is de-duplicated
5075 to avoid repetition. While beneficial for individual options, the
5076 de-duplication step can break up option groups. For example, -D A -D B
5077 becomes -D A B. One may specify a group of options using shell-like
5078 quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and
5079 the rest of the option string is parsed using the separate_arguments()
5080 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
5081 -D B.
5082 To pass options to the linker tool, each compiler driver has its own
5084 syntax. The LINKER: prefix and , separator can be used to specify, in
5085 a portable way, options to pass to the linker tool. LINKER: is replaced
5086 by the appropriate driver option and , by the appropriate driver sepa‐
5087 rator. The driver prefix and driver separator are given by the values
5088 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAP‐
5089 PER_FLAG_SEP variables.
5090 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
5092 Clang and -Wl,-z,defs for GNU GCC.
5093 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
5095 sion.
5096 The LINKER: prefix supports, as an alternative syntax, specification of
5098 arguments using the SHELL: prefix and space as separator. The previous
5099 example then becomes "LINKER:SHELL:-z defs".
5100 NOTE:
5102 Specifying the SHELL: prefix anywhere other than at the beginning of
5103 the LINKER: prefix is not supported.
5104 add_subdirectory
5106 Add a subdirectory to the build.
5107 add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
5109 Adds a subdirectory to the build. The source_dir specifies the direc‐
5111 tory in which the source CMakeLists.txt and code files are located. If
5112 it is a relative path it will be evaluated with respect to the current
5113 directory (the typical usage), but it may also be an absolute path.
5114 The binary_dir specifies the directory in which to place the output
5115 files. If it is a relative path it will be evaluated with respect to
5116 the current output directory, but it may also be an absolute path. If
5117 binary_dir is not specified, the value of source_dir, before expanding
5118 any relative path, will be used (the typical usage). The CMake‐
5119 Lists.txt file in the specified source directory will be processed
5120 immediately by CMake before processing in the current input file con‐
5121 tinues beyond this command.
5122 If the EXCLUDE_FROM_ALL argument is provided then targets in the subdi‐
5124 rectory will not be included in the ALL target of the parent directory
5125 by default, and will be excluded from IDE project files. Users must
5126 explicitly build targets in the subdirectory. This is meant for use
5127 when the subdirectory contains a separate part of the project that is
5128 useful but not necessary, such as a set of examples. Typically the
5129 subdirectory should contain its own project() command invocation so
5130 that a full build system will be generated in the subdirectory (such as
5131 a VS IDE solution file). Note that inter-target dependencies supersede
5132 this exclusion. If a target built by the parent project depends on a
5133 target in the subdirectory, the dependee target will be included in the
5134 parent project build system to satisfy the dependency.
5135 add_test
5137 Add a test to the project to be run by ctest(1).
5138 add_test(NAME <name> COMMAND <command> [<arg>...]
5140 [CONFIGURATIONS <config>...]
5141 [WORKING_DIRECTORY <dir>]
5142 [COMMAND_EXPAND_LISTS])
5143 Adds a test called <name>. The test name may not contain spaces,
5145 quotes, or other characters special in CMake syntax. The options are:
5146 COMMAND
5148 Specify the test command-line. If <command> specifies an exe‐
5149 cutable target (created by add_executable()) it will automati‐
5150 cally be replaced by the location of the executable created at
5151 build time.
5152 CONFIGURATIONS
5154 Restrict execution of the test only to the named configurations.
5155 WORKING_DIRECTORY
5157 Set the WORKING_DIRECTORY test property to specify the working
5158 directory in which to execute the test. If not specified the
5159 test will be run with the current working directory set to the
5160 build directory corresponding to the current source directory.
5161 COMMAND_EXPAND_LISTS
5163 Lists in COMMAND arguments will be expanded, including those
5164 created with generator expressions.
5165 The given test command is expected to exit with code 0 to pass and
5167 non-zero to fail, or vice-versa if the WILL_FAIL test property is set.
5168 Any output written to stdout or stderr will be captured by ctest(1) but
5169 does not affect the pass/fail status unless the PASS_REGULAR_EXPRES‐
5170 SION, FAIL_REGULAR_EXPRESSION or SKIP_REGULAR_EXPRESSION test property
5171 is used.
5172 The COMMAND and WORKING_DIRECTORY options may use “generator expres‐
5174 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
5175 manual for available expressions.
5176 Example usage:
5178 add_test(NAME mytest
5180 COMMAND testDriver --config $<CONFIGURATION>
5181 --exe $<TARGET_FILE:myexe>)
5182 This creates a test mytest whose command runs a testDriver tool passing
5184 the configuration name and the full path to the executable file pro‐
5185 duced by target myexe.
5186 NOTE:
5188 CMake will generate tests only if the enable_testing() command has
5189 been invoked. The CTest module invokes the command automatically
5190 unless the BUILD_TESTING option is turned OFF.
5191 ----
5194 add_test(<name> <command> [<arg>...])
5198 Add a test called <name> with the given command-line. Unlike the above
5200 NAME signature no transformation is performed on the command-line to
5201 support target names or generator expressions.
5202 aux_source_directory
5204 Find all source files in a directory.
5205 aux_source_directory(<dir> <variable>)
5207 Collects the names of all the source files in the specified directory
5209 and stores the list in the <variable> provided. This command is
5210 intended to be used by projects that use explicit template instantia‐
5211 tion. Template instantiation files can be stored in a Templates subdi‐
5212 rectory and collected automatically using this command to avoid manu‐
5213 ally listing all instantiations.
5214 It is tempting to use this command to avoid writing the list of source
5216 files for a library or executable target. While this seems to work,
5217 there is no way for CMake to generate a build system that knows when a
5218 new source file has been added. Normally the generated build system
5219 knows when it needs to rerun CMake because the CMakeLists.txt file is
5220 modified to add a new source. When the source is just added to the
5221 directory without modifying this file, one would have to manually rerun
5222 CMake to generate a build system incorporating the new file.
5223 build_command
5225 Get a command line to build the current project. This is mainly
5226 intended for internal use by the CTest module.
5227 build_command(<variable>
5229 [CONFIGURATION <config>]
5230 [TARGET <target>]
5231 [PROJECT_NAME <projname>] # legacy, causes warning
5232 )
5233 Sets the given <variable> to a command-line string of the form:
5235 <cmake> --build . [--config <config>] [--target <target>...] [-- -i]
5237 where <cmake> is the location of the cmake(1) command-line tool, and
5239 <config> and <target> are the values provided to the CONFIGURATION and
5240 TARGET options, if any. The trailing -- -i option is added for Make‐
5241 file Generators if policy CMP0061 is not set to NEW.
5242 When invoked, this cmake --build command line will launch the underly‐
5244 ing build system tool.
5245 build_command(<cachevariable> <makecommand>)
5247 This second signature is deprecated, but still available for backwards
5249 compatibility. Use the first signature instead.
5250 It sets the given <cachevariable> to a command-line string as above but
5252 without the --target option. The <makecommand> is ignored but should
5253 be the full path to devenv, nmake, make or one of the end user build
5254 tools for legacy invocations.
5255 NOTE:
5257 In CMake versions prior to 3.0 this command returned a command line
5258 that directly invokes the native build tool for the current genera‐
5259 tor. Their implementation of the PROJECT_NAME option had no useful
5260 effects, so CMake now warns on use of the option.
5261 create_test_sourcelist
5263 Create a test driver and source list for building test programs.
5264 create_test_sourcelist(sourceListName driverName
5266 test1 test2 test3
5267 EXTRA_INCLUDE include.h
5268 FUNCTION function)
5269 A test driver is a program that links together many small tests into a
5271 single executable. This is useful when building static executables
5272 with large libraries to shrink the total required size. The list of
5273 source files needed to build the test driver will be in sourceListName.
5274 driverName is the name of the test driver program. The rest of the
5275 arguments consist of a list of test source files, can be semicolon sep‐
5276 arated. Each test source file should have a function in it that is the
5277 same name as the file with no extension (foo.cxx should have int
5278 foo(int, char*[]);) driverName will be able to call each of the tests
5279 by name on the command line. If EXTRA_INCLUDE is specified, then the
5280 next argument is included into the generated file. If FUNCTION is
5281 specified, then the next argument is taken as a function name that is
5282 passed a pointer to ac and av. This can be used to add extra command
5283 line processing to each test. The CMAKE_TESTDRIVER_BEFORE_TESTMAIN
5284 cmake variable can be set to have code that will be placed directly
5285 before calling the test main function. CMAKE_TESTDRIVER_AFTER_TESTMAIN
5286 can be set to have code that will be placed directly after the call to
5287 the test main function.
5288 define_property
5290 Define and document custom properties.
5291 define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
5293 TEST | VARIABLE | CACHED_VARIABLE>
5294 PROPERTY <name> [INHERITED]
5295 BRIEF_DOCS <brief-doc> [docs...]
5296 FULL_DOCS <full-doc> [docs...])
5297 Defines one property in a scope for use with the set_property() and
5299 get_property() commands. This is primarily useful to associate docu‐
5300 mentation with property names that may be retrieved with the get_prop‐
5301 erty() command. The first argument determines the kind of scope in
5302 which the property should be used. It must be one of the following:
5303 GLOBAL = associated with the global namespace
5305 DIRECTORY = associated with one directory
5306 TARGET = associated with one target
5307 SOURCE = associated with one source file
5308 TEST = associated with a test named with add_test
5309 VARIABLE = documents a CMake language variable
5310 CACHED_VARIABLE = documents a CMake cache variable
5311 Note that unlike set_property() and get_property() no actual scope
5313 needs to be given; only the kind of scope is important.
5314 The required PROPERTY option is immediately followed by the name of the
5316 property being defined.
5317 If the INHERITED option is given, then the get_property() command will
5319 chain up to the next higher scope when the requested property is not
5320 set in the scope given to the command.
5321 · DIRECTORY scope chains to its parent directory’s scope, continuing
5323 the walk up parent directories until a directory has the property set
5324 or there are no more parents. If still not found at the top level
5325 directory, it chains to the GLOBAL scope.
5326 · TARGET, SOURCE and TEST properties chain to DIRECTORY scope, includ‐
5328 ing further chaining up the directories, etc. as needed.
5329 Note that this scope chaining behavior only applies to calls to
5331 get_property(), get_directory_property(), get_target_property(),
5332 get_source_file_property() and get_test_property(). There is no inher‐
5333 iting behavior when setting properties, so using APPEND or
5334 APPEND_STRING with the set_property() command will not consider inher‐
5335 ited values when working out the contents to append to.
5336 The BRIEF_DOCS and FULL_DOCS options are followed by strings to be
5338 associated with the property as its brief and full documentation. Cor‐
5339 responding options to the get_property() command will retrieve the doc‐
5340 umentation.
5341 enable_language
5343 Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
5344 enable_language(<lang> [OPTIONAL] )
5346 Enables support for the named language in CMake. This is the same as
5348 the project() command but does not create any of the extra variables
5349 that are created by the project command. Example languages are CXX, C,
5350 CUDA, OBJC, OBJCXX, Fortran, and ASM.
5351 If enabling ASM, enable it last so that CMake can check whether compil‐
5353 ers for other languages like C work for assembly too.
5354 This command must be called in file scope, not in a function call.
5356 Furthermore, it must be called in the highest directory common to all
5357 targets using the named language directly for compiling sources or
5358 indirectly through link dependencies. It is simplest to enable all
5359 needed languages in the top-level directory of a project.
5360 The OPTIONAL keyword is a placeholder for future implementation and
5362 does not currently work. Instead you can use the CheckLanguage module
5363 to verify support before enabling.
5364 enable_testing
5366 Enable testing for current directory and below.
5367 enable_testing()
5369 Enables testing for this directory and below.
5371 This command should be in the source directory root because ctest
5373 expects to find a test file in the build directory root.
5374 This command is automatically invoked when the CTest module is
5376 included, except if the BUILD_TESTING option is turned off.
5377 See also the add_test() command.
5379 export
5381 Export targets from the build tree for use by outside projects.
5382 export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
5384 Creates a file <filename> that may be included by outside projects to
5386 import targets from the current project’s build tree. This is useful
5387 during cross-compiling to build utility executables that can run on the
5388 host platform in one project and then import them into another project
5389 being compiled for the target platform. If the NAMESPACE option is
5390 given the <namespace> string will be prepended to all target names
5391 written to the file.
5392 Target installations are associated with the export <export-name> using
5394 the EXPORT option of the install(TARGETS) command.
5395 The file created by this command is specific to the build tree and
5397 should never be installed. See the install(EXPORT) command to export
5398 targets from an installation tree.
5399 The properties set on the generated IMPORTED targets will have the same
5401 values as the final values of the input TARGETS.
5402 export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
5404 [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
5405 This signature is similar to the EXPORT signature, but targets are
5407 listed explicitly rather than specified as an export-name. If the
5408 APPEND option is given the generated code will be appended to the file
5409 instead of overwriting it. The EXPORT_LINK_INTERFACE_LIBRARIES key‐
5410 word, if present, causes the contents of the properties matching
5411 (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when
5412 policy CMP0022 is NEW. If a library target is included in the export
5413 but a target to which it links is not included the behavior is unspeci‐
5414 fied.
5415 NOTE:
5417 Object Libraries under Xcode have special handling if multiple
5418 architectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
5419 they will be exported as Interface Libraries with no object files
5420 available to clients. This is sufficient to satisfy transitive
5421 usage requirements of other targets that link to the object
5422 libraries in their implementation.
5423 export(PACKAGE <PackageName>)
5425 Store the current build directory in the CMake user package registry
5427 for package <PackageName>. The find_package() command may consider the
5428 directory while searching for package <PackageName>. This helps depen‐
5429 dent projects find and use a package from the current project’s build
5430 tree without help from the user. Note that the entry in the package
5431 registry that this command creates works only in conjunction with a
5432 package configuration file (<PackageName>Config.cmake) that works with
5433 the build tree. In some cases, for example for packaging and for system
5434 wide installations, it is not desirable to write the user package reg‐
5435 istry.
5436 By default the export(PACKAGE) command does nothing (see policy
5438 CMP0090) because populating the user package registry has effects out‐
5439 side the source and build trees. Set the CMAKE_EXPORT_PACKAGE_REGISTRY
5440 variable to add build directories to the CMake user package registry.
5441 export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
5443 This signature exports cmake built targets to the android ndk build
5445 system by creating an Android.mk file that references the prebuilt tar‐
5446 gets. The Android NDK supports the use of prebuilt libraries, both
5447 static and shared. This allows cmake to build the libraries of a
5448 project and make them available to an ndk build system complete with
5449 transitive dependencies, include flags and defines required to use the
5450 libraries. The signature takes a list of targets and puts them in the
5451 Android.mk file specified by the <filename> given. This signature can
5452 only be used if policy CMP0022 is NEW for all targets given. A error
5453 will be issued if that policy is set to OLD for one of the targets.
5454 fltk_wrap_ui
5456 Create FLTK user interfaces Wrappers.
5457 fltk_wrap_ui(resultingLibraryName source1
5459 source2 ... sourceN )
5460 Produce .h and .cxx files for all the .fl and .fld files listed. The
5462 resulting .h and .cxx files will be added to a variable named result‐
5463 ingLibraryName_FLTK_UI_SRCS which should be added to your library.
5464 get_source_file_property
5466 Get a property for a source file.
5467 get_source_file_property(VAR file property)
5469 Gets a property from a source file. The value of the property is
5471 stored in the variable VAR. If the source property is not found, the
5472 behavior depends on whether it has been defined to be an INHERITED
5473 property or not (see define_property()). Non-inherited properties will
5474 set VAR to “NOTFOUND”, whereas inherited properties will search the
5475 relevant parent scope as described for the define_property() command
5476 and if still unable to find the property, VAR will be set to an empty
5477 string.
5478 Use set_source_files_properties() to set property values. Source file
5480 properties usually control how the file is built. One property that is
5481 always there is LOCATION.
5482 See also the more general get_property() command.
5484 get_target_property
5486 Get a property from a target.
5487 get_target_property(VAR target property)
5489 Get a property from a target. The value of the property is stored in
5491 the variable VAR. If the target property is not found, the behavior
5492 depends on whether it has been defined to be an INHERITED property or
5493 not (see define_property()). Non-inherited properties will set VAR to
5494 NOTFOUND, whereas inherited properties will search the relevant parent
5495 scope as described for the define_property() command and if still
5496 unable to find the property, VAR will be set to an empty string.
5497 Use set_target_properties() to set target property values. Properties
5499 are usually used to control how a target is built, but some query the
5500 target instead. This command can get properties for any target so far
5501 created. The targets do not need to be in the current CMakeLists.txt
5502 file.
5503 See also the more general get_property() command.
5505 See Target Properties for the list of properties known to CMake.
5507 get_test_property
5509 Get a property of the test.
5510 get_test_property(test property VAR)
5512 Get a property from the test. The value of the property is stored in
5514 the variable VAR. If the test property is not found, the behavior
5515 depends on whether it has been defined to be an INHERITED property or
5516 not (see define_property()). Non-inherited properties will set VAR to
5517 “NOTFOUND”, whereas inherited properties will search the relevant par‐
5518 ent scope as described for the define_property() command and if still
5519 unable to find the property, VAR will be set to an empty string.
5520 For a list of standard properties you can type cmake --help-prop‐
5522 erty-list.
5523 See also the more general get_property() command.
5525 include_directories
5527 Add include directories to the build.
5528 include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])
5530 Add the given directories to those the compiler uses to search for
5532 include files. Relative paths are interpreted as relative to the cur‐
5533 rent source directory.
5534 The include directories are added to the INCLUDE_DIRECTORIES directory
5536 property for the current CMakeLists file. They are also added to the
5537 INCLUDE_DIRECTORIES target property for each target in the current
5538 CMakeLists file. The target property values are the ones used by the
5539 generators.
5540 By default the directories specified are appended onto the current list
5542 of directories. This default behavior can be changed by setting
5543 CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE
5544 explicitly, you can select between appending and prepending, indepen‐
5545 dent of the default.
5546 If the SYSTEM option is given, the compiler will be told the directo‐
5548 ries are meant as system include directories on some platforms. Sig‐
5549 nalling this setting might achieve effects such as the compiler skip‐
5550 ping warnings, or these fixed-install system files not being considered
5551 in dependency calculations - see compiler docs.
5552 Arguments to include_directories may use “generator expressions” with
5554 the syntax “$<…>”. See the cmake-generator-expressions(7) manual for
5555 available expressions. See the cmake-buildsystem(7) manual for more on
5556 defining buildsystem properties.
5557 NOTE:
5559 Prefer the target_include_directories() command to add include
5560 directories to individual targets and optionally propagate/export
5561 them to dependents.
5562 include_external_msproject
5564 Include an external Microsoft project file in a workspace.
5565 include_external_msproject(projectname location
5567 [TYPE projectTypeGUID]
5568 [GUID projectGUID]
5569 [PLATFORM platformName]
5570 dep1 dep2 ...)
5571 Includes an external Microsoft project in the generated workspace file.
5573 Currently does nothing on UNIX. This will create a target named [pro‐
5574 jectname]. This can be used in the add_dependencies() command to make
5575 things depend on the external project.
5576 TYPE, GUID and PLATFORM are optional parameters that allow one to spec‐
5578 ify the type of project, id (GUID) of the project and the name of the
5579 target platform. This is useful for projects requiring values other
5580 than the default (e.g. WIX projects).
5581 If the imported project has different configuration names than the cur‐
5583 rent project, set the MAP_IMPORTED_CONFIG_<CONFIG> target property to
5584 specify the mapping.
5585 include_regular_expression
5587 Set the regular expression used for dependency checking.
5588 include_regular_expression(regex_match [regex_complain])
5590 Sets the regular expressions used in dependency checking. Only files
5592 matching regex_match will be traced as dependencies. Only files match‐
5593 ing regex_complain will generate warnings if they cannot be found
5594 (standard header paths are not searched). The defaults are:
5595 regex_match = "^.*$" (match everything)
5597 regex_complain = "^$" (match empty string only)
5598 install
5600 Specify rules to run at install time.
5601 Synopsis
5603 install(TARGETS <target>... [...])
5604 install({FILES | PROGRAMS} <file>... [...])
5605 install(DIRECTORY <dir>... [...])
5606 install(SCRIPT <file> [...])
5607 install(CODE <code> [...])
5608 install(EXPORT <export-name> [...])
5609 Introduction
5611 This command generates installation rules for a project. Rules speci‐
5612 fied by calls to this command within a source directory are executed in
5613 order during installation. The order across directories is not
5614 defined.
5615 There are multiple signatures for this command. Some of them define
5617 installation options for files and targets. Options common to multiple
5618 signatures are covered here but they are valid only for signatures that
5619 specify them. The common options are:
5620 DESTINATION
5622 Specify the directory on disk to which a file will be installed.
5623 If a full path (with a leading slash or drive letter) is given
5624 it is used directly. If a relative path is given it is inter‐
5625 preted relative to the value of the CMAKE_INSTALL_PREFIX vari‐
5626 able. The prefix can be relocated at install time using the
5627 DESTDIR mechanism explained in the CMAKE_INSTALL_PREFIX variable
5628 documentation.
5629 PERMISSIONS
5631 Specify permissions for installed files. Valid permissions are
5632 OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE,
5633 GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID,
5634 and SETGID. Permissions that do not make sense on certain plat‐
5635 forms are ignored on those platforms.
5636 CONFIGURATIONS
5638 Specify a list of build configurations for which the install
5639 rule applies (Debug, Release, etc.). Note that the values speci‐
5640 fied for this option only apply to options listed AFTER the CON‐
5641 FIGURATIONS option. For example, to set separate install paths
5642 for the Debug and Release configurations, do the following:
5643 install(TARGETS target
5645 CONFIGURATIONS Debug
5646 RUNTIME DESTINATION Debug/bin)
5647 install(TARGETS target
5648 CONFIGURATIONS Release
5649 RUNTIME DESTINATION Release/bin)
5650 Note that CONFIGURATIONS appears BEFORE RUNTIME DESTINATION.
5652 COMPONENT
5654 Specify an installation component name with which the install
5655 rule is associated, such as “runtime” or “development”. During
5656 component-specific installation only install rules associated
5657 with the given component name will be executed. During a full
5658 installation all components are installed unless marked with
5659 EXCLUDE_FROM_ALL. If COMPONENT is not provided a default compo‐
5660 nent “Unspecified” is created. The default component name may
5661 be controlled with the CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
5662 variable.
5663 EXCLUDE_FROM_ALL
5665 Specify that the file is excluded from a full installation and
5666 only installed as part of a component-specific installation
5667 RENAME Specify a name for an installed file that may be different from
5669 the original file. Renaming is allowed only when a single file
5670 is installed by the command.
5671 OPTIONAL
5673 Specify that it is not an error if the file to be installed does
5674 not exist.
5675 Command signatures that install files may print messages during instal‐
5677 lation. Use the CMAKE_INSTALL_MESSAGE variable to control which mes‐
5678 sages are printed.
5679 Many of the install() variants implicitly create the directories con‐
5681 taining the installed files. If CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMIS‐
5682 SIONS is set, these directories will be created with the permissions
5683 specified. Otherwise, they will be created according to the uname rules
5684 on Unix-like platforms. Windows platforms are unaffected.
5685 Installing Targets
5687 install(TARGETS targets... [EXPORT <export-name>]
5688 [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
5689 PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
5690 [DESTINATION <dir>]
5691 [PERMISSIONS permissions...]
5692 [CONFIGURATIONS [Debug|Release|...]]
5693 [COMPONENT <component>]
5694 [NAMELINK_COMPONENT <component>]
5695 [OPTIONAL] [EXCLUDE_FROM_ALL]
5696 [NAMELINK_ONLY|NAMELINK_SKIP]
5697 ] [...]
5698 [INCLUDES DESTINATION [<dir> ...]]
5699 )
5700 The TARGETS form specifies rules for installing targets from a project.
5702 There are several kinds of target files that may be installed:
5703 ARCHIVE
5705 Static libraries are treated as ARCHIVE targets, except those
5706 marked with the FRAMEWORK property on macOS (see FRAMEWORK
5707 below.) For DLL platforms (all Windows-based systems including
5708 Cygwin), the DLL import library is treated as an ARCHIVE target.
5709 On AIX, the linker import file created for executables with
5710 ENABLE_EXPORTS is treated as an ARCHIVE target.
5711 LIBRARY
5713 Module libraries are always treated as LIBRARY targets. For non-
5714 DLL platforms shared libraries are treated as LIBRARY targets,
5715 except those marked with the FRAMEWORK property on macOS (see
5716 FRAMEWORK below.)
5717 RUNTIME
5719 Executables are treated as RUNTIME objects, except those marked
5720 with the MACOSX_BUNDLE property on macOS (see BUNDLE below.)
5721 For DLL platforms (all Windows-based systems including Cygwin),
5722 the DLL part of a shared library is treated as a RUNTIME target.
5723 OBJECTS
5725 Object libraries (a simple group of object files) are always
5726 treated as OBJECTS targets.
5727 FRAMEWORK
5729 Both static and shared libraries marked with the FRAMEWORK prop‐
5730 erty are treated as FRAMEWORK targets on macOS.
5731 BUNDLE Executables marked with the MACOSX_BUNDLE property are treated
5733 as BUNDLE targets on macOS.
5734 PUBLIC_HEADER
5736 Any PUBLIC_HEADER files associated with a library are installed
5737 in the destination specified by the PUBLIC_HEADER argument on
5738 non-Apple platforms. Rules defined by this argument are ignored
5739 for FRAMEWORK libraries on Apple platforms because the associ‐
5740 ated files are installed into the appropriate locations inside
5741 the framework folder. See PUBLIC_HEADER for details.
5742 PRIVATE_HEADER
5744 Similar to PUBLIC_HEADER, but for PRIVATE_HEADER files. See PRI‐
5745 VATE_HEADER for details.
5746 RESOURCE
5748 Similar to PUBLIC_HEADER and PRIVATE_HEADER, but for RESOURCE
5749 files. See RESOURCE for details.
5750 For each of these arguments given, the arguments following them only
5752 apply to the target or file type specified in the argument. If none is
5753 given, the installation properties apply to all target types. If only
5754 one is given then only targets of that type will be installed (which
5755 can be used to install just a DLL or just an import library.)
5756 For regular executables, static libraries and shared libraries, the
5758 DESTINATION argument is not required. For these target types, when
5759 DESTINATION is omitted, a default destination will be taken from the
5760 appropriate variable from GNUInstallDirs, or set to a built-in default
5761 value if that variable is not defined. The same is true for the public
5762 and private headers associated with the installed targets through the
5763 PUBLIC_HEADER and PRIVATE_HEADER target properties. A destination must
5764 always be provided for module libraries, Apple bundles and frameworks.
5765 A destination can be omitted for interface and object libraries, but
5766 they are handled differently (see the discussion of this topic toward
5767 the end of this section).
5768 The following table shows the target types with their associated vari‐
5770 ables and built-in defaults that apply when no destination is given:
5771 ┌───────────────┬─────────────────────────────┬──────────────────┐
5773 │Target Type │ GNUInstallDirs │ Built-In Default │
5774 │ │ Variable │ │
5775 ├───────────────┼─────────────────────────────┼──────────────────┤
5776 │RUNTIME │ ${CMAKE_INSTALL_BINDIR} │ bin │
5777 ├───────────────┼─────────────────────────────┼──────────────────┤
5778 │LIBRARY │ ${CMAKE_INSTALL_LIBDIR} │ lib │
5779 ├───────────────┼─────────────────────────────┼──────────────────┤
5780 │ARCHIVE │ ${CMAKE_INSTALL_LIBDIR} │ lib │
5781 ├───────────────┼─────────────────────────────┼──────────────────┤
5782 │PRIVATE_HEADER │ ${CMAKE_INSTALL_INCLUDEDIR} │ include │
5783 ├───────────────┼─────────────────────────────┼──────────────────┤
5784 │PUBLIC_HEADER │ ${CMAKE_INSTALL_INCLUDEDIR} │ include │
5785 └───────────────┴─────────────────────────────┴──────────────────┘
5786 Projects wishing to follow the common practice of installing headers
5788 into a project-specific subdirectory will need to provide a destination
5789 rather than rely on the above.
5790 To make packages compliant with distribution filesystem layout poli‐
5792 cies, if projects must specify a DESTINATION, it is recommended that
5793 they use a path that begins with the appropriate GNUInstallDirs vari‐
5794 able. This allows package maintainers to control the install destina‐
5795 tion by setting the appropriate cache variables. The following example
5796 shows a static library being installed to the default destination pro‐
5797 vided by GNUInstallDirs, but with its headers installed to a
5798 project-specific subdirectory that follows the above recommendation:
5799 add_library(mylib STATIC ...)
5801 set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
5802 include(GNUInstallDirs)
5803 install(TARGETS mylib
5804 PUBLIC_HEADER
5805 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
5806 )
5807 In addition to the common options listed above, each target can accept
5809 the following additional arguments:
5810 NAMELINK_COMPONENT
5812 On some platforms a versioned shared library has a symbolic link
5813 such as:
5814 lib<name>.so -> lib<name>.so.1
5816 where lib<name>.so.1 is the soname of the library and
5818 lib<name>.so is a “namelink” allowing linkers to find the
5819 library when given -l<name>. The NAMELINK_COMPONENT option is
5820 similar to the COMPONENT option, but it changes the installation
5821 component of a shared library namelink if one is generated. If
5822 not specified, this defaults to the value of COMPONENT. It is an
5823 error to use this parameter outside of a LIBRARY block.
5824 Consider the following example:
5826 install(TARGETS mylib
5828 LIBRARY
5829 COMPONENT Libraries
5830 NAMELINK_COMPONENT Development
5831 PUBLIC_HEADER
5832 COMPONENT Development
5833 )
5834 In this scenario, if you choose to install only the Development
5836 component, both the headers and namelink will be installed with‐
5837 out the library. (If you don’t also install the Libraries compo‐
5838 nent, the namelink will be a dangling symlink, and projects that
5839 link to the library will have build errors.) If you install only
5840 the Libraries component, only the library will be installed,
5841 without the headers and namelink.
5842 This option is typically used for package managers that have
5844 separate runtime and development packages. For example, on
5845 Debian systems, the library is expected to be in the runtime
5846 package, and the headers and namelink are expected to be in the
5847 development package.
5848 See the VERSION and SOVERSION target properties for details on
5850 creating versioned shared libraries.
5851 NAMELINK_ONLY
5853 This option causes the installation of only the namelink when a
5854 library target is installed. On platforms where versioned shared
5855 libraries do not have namelinks or when a library is not ver‐
5856 sioned, the NAMELINK_ONLY option installs nothing. It is an
5857 error to use this parameter outside of a LIBRARY block.
5858 When NAMELINK_ONLY is given, either NAMELINK_COMPONENT or COMPO‐
5860 NENT may be used to specify the installation component of the
5861 namelink, but COMPONENT should generally be preferred.
5862 NAMELINK_SKIP
5864 Similar to NAMELINK_ONLY, but it has the opposite effect: it
5865 causes the installation of library files other than the namelink
5866 when a library target is installed. When neither NAMELINK_ONLY
5867 or NAMELINK_SKIP are given, both portions are installed. On
5868 platforms where versioned shared libraries do not have symlinks
5869 or when a library is not versioned, NAMELINK_SKIP installs the
5870 library. It is an error to use this parameter outside of a
5871 LIBRARY block.
5872 If NAMELINK_SKIP is specified, NAMELINK_COMPONENT has no effect.
5874 It is not recommended to use NAMELINK_SKIP in conjunction with
5875 NAMELINK_COMPONENT.
5876 The install(TARGETS) command can also accept the following options at
5878 the top level:
5879 EXPORT This option associates the installed target files with an export
5881 called <export-name>. It must appear before any target options.
5882 To actually install the export file itself, call
5883 install(EXPORT), documented below. See documentation of the
5884 EXPORT_NAME target property to change the name of the exported
5885 target.
5886 INCLUDES DESTINATION
5888 This option specifies a list of directories which will be added
5889 to the INTERFACE_INCLUDE_DIRECTORIES target property of the
5890 <targets> when exported by the install(EXPORT) command. If a
5891 relative path is specified, it is treated as relative to the
5892 $<INSTALL_PREFIX>.
5893 One or more groups of properties may be specified in a single call to
5895 the TARGETS form of this command. A target may be installed more than
5896 once to different locations. Consider hypothetical targets myExe,
5897 mySharedLib, and myStaticLib. The code:
5898 install(TARGETS myExe mySharedLib myStaticLib
5900 RUNTIME DESTINATION bin
5901 LIBRARY DESTINATION lib
5902 ARCHIVE DESTINATION lib/static)
5903 install(TARGETS mySharedLib DESTINATION /some/full/path)
5904 will install myExe to <prefix>/bin and myStaticLib to <pre‐
5906 fix>/lib/static. On non-DLL platforms mySharedLib will be installed to
5907 <prefix>/lib and /some/full/path. On DLL platforms the mySharedLib DLL
5908 will be installed to <prefix>/bin and /some/full/path and its import
5909 library will be installed to <prefix>/lib/static and /some/full/path.
5910 Interface Libraries may be listed among the targets to install. They
5912 install no artifacts but will be included in an associated EXPORT. If
5913 Object Libraries are listed but given no destination for their object
5914 files, they will be exported as Interface Libraries. This is suffi‐
5915 cient to satisfy transitive usage requirements of other targets that
5916 link to the object libraries in their implementation.
5917 Installing a target with the EXCLUDE_FROM_ALL target property set to
5919 TRUE has undefined behavior.
5920 install(TARGETS) can install targets that were created in other direc‐
5922 tories. When using such cross-directory install rules, running make
5923 install (or similar) from a subdirectory will not guarantee that tar‐
5924 gets from other directories are up-to-date. You can use tar‐
5925 get_link_libraries() or add_dependencies() to ensure that such
5926 out-of-directory targets are built before the subdirectory-specific
5927 install rules are run.
5928 An install destination given as a DESTINATION argument may use “genera‐
5930 tor expressions” with the syntax $<...>. See the cmake-genera‐
5931 tor-expressions(7) manual for available expressions.
5932 Installing Files
5934 install(<FILES|PROGRAMS> files...
5935 TYPE <type> | DESTINATION <dir>
5936 [PERMISSIONS permissions...]
5937 [CONFIGURATIONS [Debug|Release|...]]
5938 [COMPONENT <component>]
5939 [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
5940 The FILES form specifies rules for installing files for a project.
5942 File names given as relative paths are interpreted with respect to the
5943 current source directory. Files installed by this form are by default
5944 given permissions OWNER_WRITE, OWNER_READ, GROUP_READ, and WORLD_READ
5945 if no PERMISSIONS argument is given.
5946 The PROGRAMS form is identical to the FILES form except that the
5948 default permissions for the installed file also include OWNER_EXECUTE,
5949 GROUP_EXECUTE, and WORLD_EXECUTE. This form is intended to install
5950 programs that are not targets, such as shell scripts. Use the TARGETS
5951 form to install targets built within the project.
5952 The list of files... given to FILES or PROGRAMS may use “generator
5954 expressions” with the syntax $<...>. See the cmake-generator-expres‐
5955 sions(7) manual for available expressions. However, if any item begins
5956 in a generator expression it must evaluate to a full path.
5957 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
5959 argument specifies the generic file type of the files being installed.
5960 A destination will then be set automatically by taking the correspond‐
5961 ing variable from GNUInstallDirs, or by using a built-in default if
5962 that variable is not defined. See the table below for the supported
5963 file types and their corresponding variables and built-in defaults.
5964 Projects can provide a DESTINATION argument instead of a file type if
5965 they wish to explicitly define the install destination.
5966 ┌──────────────┬─────────────────────────────┬─────────────────────┐
5968 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
5969 │ │ Variable │ │
5970 ├──────────────┼─────────────────────────────┼─────────────────────┤
5971 │BIN │ ${CMAKE_INSTALL_BINDIR} │ bin │
5972 ├──────────────┼─────────────────────────────┼─────────────────────┤
5973 │SBIN │ ${CMAKE_INSTALL_SBINDIR} │ sbin │
5974 ├──────────────┼─────────────────────────────┼─────────────────────┤
5975 │LIB │ ${CMAKE_INSTALL_LIBDIR} │ lib │
5976 ├──────────────┼─────────────────────────────┼─────────────────────┤
5977 │INCLUDE │ ${CMAKE_INSTALL_INCLUDEDIR} │ include │
5978 ├──────────────┼─────────────────────────────┼─────────────────────┤
5979 │SYSCONF │ ${CMAKE_INSTALL_SYSCONFDIR} │ etc │
5980 ├──────────────┼─────────────────────────────┼─────────────────────┤
5981 │SHAREDSTATE │ ${CMAKE_INSTALL_SHARESTATE‐ │ com │
5982 │ │ DIR} │ │
5983 ├──────────────┼─────────────────────────────┼─────────────────────┤
5984 │LOCALSTATE │ ${CMAKE_INSTALL_LOCALSTATE‐ │ var │
5985 │ │ DIR} │ │
5986 ├──────────────┼─────────────────────────────┼─────────────────────┤
5987 │RUNSTATE │ ${CMAKE_INSTALL_RUNSTATE‐ │ <LOCALSTATE │
5988 │ │ DIR} │ dir>/run │
5989 ├──────────────┼─────────────────────────────┼─────────────────────┤
5990 │DATA │ ${CMAKE_INSTALL_DATADIR} │ <DATAROOT dir> │
5991 ├──────────────┼─────────────────────────────┼─────────────────────┤
5992 │INFO │ ${CMAKE_INSTALL_INFODIR} │ <DATAROOT dir>/info │
5993 ├──────────────┼─────────────────────────────┼─────────────────────┤
5994 │LOCALE │ ${CMAKE_INSTALL_LOCALEDIR} │ <DATAROOT │
5995 │ │ │ dir>/locale │
5996 ├──────────────┼─────────────────────────────┼─────────────────────┤
5997 │MAN │ ${CMAKE_INSTALL_MANDIR} │ <DATAROOT dir>/man │
5998 ├──────────────┼─────────────────────────────┼─────────────────────┤
5999 │DOC │ ${CMAKE_INSTALL_DOCDIR} │ <DATAROOT dir>/doc │
6000 └──────────────┴─────────────────────────────┴─────────────────────┘
6001 Projects wishing to follow the common practice of installing headers
6003 into a project-specific subdirectory will need to provide a destination
6004 rather than rely on the above.
6005 Note that some of the types’ built-in defaults use the DATAROOT direc‐
6007 tory as a prefix. The DATAROOT prefix is calculated similarly to the
6008 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
6009 built-in default. You cannot use DATAROOT as a TYPE parameter; please
6010 use DATA instead.
6011 To make packages compliant with distribution filesystem layout poli‐
6013 cies, if projects must specify a DESTINATION, it is recommended that
6014 they use a path that begins with the appropriate GNUInstallDirs vari‐
6015 able. This allows package maintainers to control the install destina‐
6016 tion by setting the appropriate cache variables. The following example
6017 shows how to follow this advice while installing headers to a
6018 project-specific subdirectory:
6019 include(GNUInstallDirs)
6021 install(FILES mylib.h
6022 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
6023 )
6024 An install destination given as a DESTINATION argument may use “genera‐
6026 tor expressions” with the syntax $<...>. See the cmake-genera‐
6027 tor-expressions(7) manual for available expressions.
6028 Installing Directories
6030 install(DIRECTORY dirs...
6031 TYPE <type> | DESTINATION <dir>
6032 [FILE_PERMISSIONS permissions...]
6033 [DIRECTORY_PERMISSIONS permissions...]
6034 [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
6035 [CONFIGURATIONS [Debug|Release|...]]
6036 [COMPONENT <component>] [EXCLUDE_FROM_ALL]
6037 [FILES_MATCHING]
6038 [[PATTERN <pattern> | REGEX <regex>]
6039 [EXCLUDE] [PERMISSIONS permissions...]] [...])
6040 The DIRECTORY form installs contents of one or more directories to a
6042 given destination. The directory structure is copied verbatim to the
6043 destination. The last component of each directory name is appended to
6044 the destination directory but a trailing slash may be used to avoid
6045 this because it leaves the last component empty. Directory names given
6046 as relative paths are interpreted with respect to the current source
6047 directory. If no input directory names are given the destination
6048 directory will be created but nothing will be installed into it. The
6049 FILE_PERMISSIONS and DIRECTORY_PERMISSIONS options specify permissions
6050 given to files and directories in the destination. If USE_SOURCE_PER‐
6051 MISSIONS is specified and FILE_PERMISSIONS is not, file permissions
6052 will be copied from the source directory structure. If no permissions
6053 are specified files will be given the default permissions specified in
6054 the FILES form of the command, and the directories will be given the
6055 default permissions specified in the PROGRAMS form of the command.
6056 The MESSAGE_NEVER option disables file installation status output.
6058 Installation of directories may be controlled with fine granularity
6060 using the PATTERN or REGEX options. These “match” options specify a
6061 globbing pattern or regular expression to match directories or files
6062 encountered within input directories. They may be used to apply cer‐
6063 tain options (see below) to a subset of the files and directories
6064 encountered. The full path to each input file or directory (with for‐
6065 ward slashes) is matched against the expression. A PATTERN will match
6066 only complete file names: the portion of the full path matching the
6067 pattern must occur at the end of the file name and be preceded by a
6068 slash. A REGEX will match any portion of the full path but it may use
6069 / and $ to simulate the PATTERN behavior. By default all files and
6070 directories are installed whether or not they are matched. The
6071 FILES_MATCHING option may be given before the first match option to
6072 disable installation of files (but not directories) not matched by any
6073 expression. For example, the code
6074 install(DIRECTORY src/ DESTINATION include/myproj
6076 FILES_MATCHING PATTERN "*.h")
6077 will extract and install header files from a source tree.
6079 Some options may follow a PATTERN or REGEX expression and are applied
6081 only to files or directories matching them. The EXCLUDE option will
6082 skip the matched file or directory. The PERMISSIONS option overrides
6083 the permissions setting for the matched file or directory. For example
6084 the code
6085 install(DIRECTORY icons scripts/ DESTINATION share/myproj
6087 PATTERN "CVS" EXCLUDE
6088 PATTERN "scripts/*"
6089 PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
6090 GROUP_EXECUTE GROUP_READ)
6091 will install the icons directory to share/myproj/icons and the scripts
6093 directory to share/myproj. The icons will get default file permis‐
6094 sions, the scripts will be given specific permissions, and any CVS
6095 directories will be excluded.
6096 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
6098 argument specifies the generic file type of the files within the listed
6099 directories being installed. A destination will then be set automati‐
6100 cally by taking the corresponding variable from GNUInstallDirs, or by
6101 using a built-in default if that variable is not defined. See the ta‐
6102 ble below for the supported file types and their corresponding vari‐
6103 ables and built-in defaults. Projects can provide a DESTINATION argu‐
6104 ment instead of a file type if they wish to explicitly define the
6105 install destination.
6106 ┌──────────────┬─────────────────────────────┬─────────────────────┐
6108 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
6109 │ │ Variable │ │
6110 ├──────────────┼─────────────────────────────┼─────────────────────┤
6111 │BIN │ ${CMAKE_INSTALL_BINDIR} │ bin │
6112 ├──────────────┼─────────────────────────────┼─────────────────────┤
6113 │SBIN │ ${CMAKE_INSTALL_SBINDIR} │ sbin │
6114 ├──────────────┼─────────────────────────────┼─────────────────────┤
6115 │LIB │ ${CMAKE_INSTALL_LIBDIR} │ lib │
6116 ├──────────────┼─────────────────────────────┼─────────────────────┤
6117 │INCLUDE │ ${CMAKE_INSTALL_INCLUDEDIR} │ include │
6118 ├──────────────┼─────────────────────────────┼─────────────────────┤
6119 │SYSCONF │ ${CMAKE_INSTALL_SYSCONFDIR} │ etc │
6120 └──────────────┴─────────────────────────────┴─────────────────────┘
6121 │SHAREDSTATE │ ${CMAKE_INSTALL_SHARESTATE‐ │ com │
6123 │ │ DIR} │ │
6124 ├──────────────┼─────────────────────────────┼─────────────────────┤
6125 │LOCALSTATE │ ${CMAKE_INSTALL_LOCALSTATE‐ │ var │
6126 │ │ DIR} │ │
6127 ├──────────────┼─────────────────────────────┼─────────────────────┤
6128 │RUNSTATE │ ${CMAKE_INSTALL_RUNSTATE‐ │ <LOCALSTATE │
6129 │ │ DIR} │ dir>/run │
6130 ├──────────────┼─────────────────────────────┼─────────────────────┤
6131 │DATA │ ${CMAKE_INSTALL_DATADIR} │ <DATAROOT dir> │
6132 ├──────────────┼─────────────────────────────┼─────────────────────┤
6133 │INFO │ ${CMAKE_INSTALL_INFODIR} │ <DATAROOT dir>/info │
6134 ├──────────────┼─────────────────────────────┼─────────────────────┤
6135 │LOCALE │ ${CMAKE_INSTALL_LOCALEDIR} │ <DATAROOT │
6136 │ │ │ dir>/locale │
6137 ├──────────────┼─────────────────────────────┼─────────────────────┤
6138 │MAN │ ${CMAKE_INSTALL_MANDIR} │ <DATAROOT dir>/man │
6139 ├──────────────┼─────────────────────────────┼─────────────────────┤
6140 │DOC │ ${CMAKE_INSTALL_DOCDIR} │ <DATAROOT dir>/doc │
6141 └──────────────┴─────────────────────────────┴─────────────────────┘
6142 Note that some of the types’ built-in defaults use the DATAROOT direc‐
6144 tory as a prefix. The DATAROOT prefix is calculated similarly to the
6145 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
6146 built-in default. You cannot use DATAROOT as a TYPE parameter; please
6147 use DATA instead.
6148 To make packages compliant with distribution filesystem layout poli‐
6150 cies, if projects must specify a DESTINATION, it is recommended that
6151 they use a path that begins with the appropriate GNUInstallDirs vari‐
6152 able. This allows package maintainers to control the install destina‐
6153 tion by setting the appropriate cache variables.
6154 The list of dirs... given to DIRECTORY and an install destination given
6156 as a DESTINATION argument may use “generator expressions” with the syn‐
6157 tax $<...>. See the cmake-generator-expressions(7) manual for avail‐
6158 able expressions.
6159 Custom Installation Logic
6161 install([[SCRIPT <file>] [CODE <code>]]
6162 [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])
6163 The SCRIPT form will invoke the given CMake script files during instal‐
6165 lation. If the script file name is a relative path it will be inter‐
6166 preted with respect to the current source directory. The CODE form
6167 will invoke the given CMake code during installation. Code is speci‐
6168 fied as a single argument inside a double-quoted string. For example,
6169 the code
6170 install(CODE "MESSAGE(\"Sample install message.\")")
6172 will print a message during installation.
6174 <file> or <code> may use “generator expressions” with the syntax $<...>
6176 (in the case of <file>, this refers to their use in the file name, not
6177 the file’s contents). See the cmake-generator-expressions(7) manual
6178 for available expressions.
6179 Installing Exports
6181 install(EXPORT <export-name> DESTINATION <dir>
6182 [NAMESPACE <namespace>] [[FILE <name>.cmake]|
6183 [PERMISSIONS permissions...]
6184 [CONFIGURATIONS [Debug|Release|...]]
6185 [EXPORT_LINK_INTERFACE_LIBRARIES]
6186 [COMPONENT <component>]
6187 [EXCLUDE_FROM_ALL])
6188 install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])
6189 The EXPORT form generates and installs a CMake file containing code to
6191 import targets from the installation tree into another project. Target
6192 installations are associated with the export <export-name> using the
6193 EXPORT option of the install(TARGETS) signature documented above. The
6194 NAMESPACE option will prepend <namespace> to the target names as they
6195 are written to the import file. By default the generated file will be
6196 called <export-name>.cmake but the FILE option may be used to specify a
6197 different name. The value given to the FILE option must be a file name
6198 with the .cmake extension. If a CONFIGURATIONS option is given then
6199 the file will only be installed when one of the named configurations is
6200 installed. Additionally, the generated import file will reference only
6201 the matching target configurations. The EXPORT_LINK_INTER‐
6202 FACE_LIBRARIES keyword, if present, causes the contents of the proper‐
6203 ties matching (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be
6204 exported, when policy CMP0022 is NEW.
6205 When a COMPONENT option is given, the listed <component> implicitly
6207 depends on all components mentioned in the export set. The exported
6208 <name>.cmake file will require each of the exported components to be
6209 present in order for dependent projects to build properly. For example,
6210 a project may define components Runtime and Development, with shared
6211 libraries going into the Runtime component and static libraries and
6212 headers going into the Development component. The export set would also
6213 typically be part of the Development component, but it would export
6214 targets from both the Runtime and Development components. Therefore,
6215 the Runtime component would need to be installed if the Development
6216 component was installed, but not vice versa. If the Development compo‐
6217 nent was installed without the Runtime component, dependent projects
6218 that try to link against it would have build errors. Package managers,
6219 such as APT and RPM, typically handle this by listing the Runtime com‐
6220 ponent as a dependency of the Development component in the package
6221 metadata, ensuring that the library is always installed if the headers
6222 and CMake export file are present.
6223 In addition to cmake language files, the EXPORT_ANDROID_MK mode maybe
6225 used to specify an export to the android ndk build system. This mode
6226 accepts the same options as the normal export mode. The Android NDK
6227 supports the use of prebuilt libraries, both static and shared. This
6228 allows cmake to build the libraries of a project and make them avail‐
6229 able to an ndk build system complete with transitive dependencies,
6230 include flags and defines required to use the libraries.
6231 The EXPORT form is useful to help outside projects use targets built
6233 and installed by the current project. For example, the code
6234 install(TARGETS myexe EXPORT myproj DESTINATION bin)
6236 install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
6237 install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules)
6238 will install the executable myexe to <prefix>/bin and code to import it
6240 in the file <prefix>/lib/myproj/myproj.cmake and <pre‐
6241 fix>/share/ndk-modules/Android.mk. An outside project may load this
6242 file with the include command and reference the myexe executable from
6243 the installation tree using the imported target name mp_myexe as if the
6244 target were built in its own tree.
6245 NOTE:
6247 This command supercedes the install_targets() command and the
6248 PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT target properties. It
6249 also replaces the FILES forms of the install_files() and
6250 install_programs() commands. The processing order of these install
6251 rules relative to those generated by install_targets(),
6252 install_files(), and install_programs() commands is not defined.
6253 Generated Installation Script
6255 The install() command generates a file, cmake_install.cmake, inside the
6256 build directory, which is used internally by the generated install tar‐
6257 get and by CPack. You can also invoke this script manually with cmake
6258 -P. This script accepts several variables:
6259 COMPONENT
6261 Set this variable to install only a single CPack component as
6262 opposed to all of them. For example, if you only want to install
6263 the Development component, run cmake -DCOMPONENT=Development -P
6264 cmake_install.cmake.
6265 BUILD_TYPE
6267 Set this variable to change the build type if you are using a
6268 multi-config generator. For example, to install with the Debug
6269 configuration, run cmake -DBUILD_TYPE=Debug -P
6270 cmake_install.cmake.
6271 DESTDIR
6273 This is an environment variable rather than a CMake variable. It
6274 allows you to change the installation prefix on UNIX systems.
6275 See DESTDIR for details.
6276 link_directories
6278 Add directories in which the linker will look for libraries.
6279 link_directories([AFTER|BEFORE] directory1 [directory2 ...])
6281 Adds the paths in which the linker should search for libraries. Rela‐
6283 tive paths given to this command are interpreted as relative to the
6284 current source directory, see CMP0015.
6285 The directories are added to the LINK_DIRECTORIES directory property
6287 for the current CMakeLists.txt file, converting relative paths to abso‐
6288 lute as needed. The command will apply only to targets created after
6289 it is called.
6290 By default the directories specified are appended onto the current list
6292 of directories. This default behavior can be changed by setting
6293 CMAKE_LINK_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE explic‐
6294 itly, you can select between appending and prepending, independent of
6295 the default.
6296 Arguments to link_directories may use “generator expressions” with the
6298 syntax “$<…>”. See the cmake-generator-expressions(7) manual for
6299 available expressions. See the cmake-buildsystem(7) manual for more on
6300 defining buildsystem properties.
6301 NOTE:
6303 This command is rarely necessary and should be avoided where there
6304 are other choices. Prefer to pass full absolute paths to libraries
6305 where possible, since this ensures the correct library will always
6306 be linked. The find_library() command provides the full path, which
6307 can generally be used directly in calls to target_link_libraries().
6308 Situations where a library search path may be needed include:
6309 · Project generators like Xcode where the user can switch target
6311 architecture at build time, but a full path to a library cannot be
6312 used because it only provides one architecture (i.e. it is not a
6313 universal binary).
6314 · Libraries may themselves have other private library dependencies
6316 that expect to be found via RPATH mechanisms, but some linkers are
6317 not able to fully decode those paths (e.g. due to the presence of
6318 things like $ORIGIN).
6319 If a library search path must be provided, prefer to localize the
6321 effect where possible by using the target_link_directories() command
6322 rather than link_directories(). The target-specific command can
6323 also control how the search directories propagate to other dependent
6324 targets.
6325 link_libraries
6327 Link libraries to all targets added later.
6328 link_libraries([item1 [item2 [...]]]
6330 [[debug|optimized|general] <item>] ...)
6331 Specify libraries or flags to use when linking any targets created
6333 later in the current directory or below by commands such as add_exe‐
6334 cutable() or add_library(). See the target_link_libraries() command
6335 for meaning of arguments.
6336 NOTE:
6338 The target_link_libraries() command should be preferred whenever
6339 possible. Library dependencies are chained automatically, so direc‐
6340 tory-wide specification of link libraries is rarely needed.
6341 load_cache
6343 Load in the values from another project’s CMake cache.
6344 load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...)
6346 Reads the cache and store the requested entries in variables with their
6348 name prefixed with the given prefix. This only reads the values, and
6349 does not create entries in the local project’s cache.
6350 load_cache(pathToBuildDirectory [EXCLUDE entry1...]
6352 [INCLUDE_INTERNALS entry1...])
6353 Loads in the values from another cache and store them in the local
6355 project’s cache as internal entries. This is useful for a project that
6356 depends on another project built in a different tree. EXCLUDE option
6357 can be used to provide a list of entries to be excluded.
6358 INCLUDE_INTERNALS can be used to provide a list of internal entries to
6359 be included. Normally, no internal entries are brought in. Use of
6360 this form of the command is strongly discouraged, but it is provided
6361 for backward compatibility.
6362 project
6364 Set the name of the project.
6365 Synopsis
6367 project(<PROJECT-NAME> [<language-name>...])
6368 project(<PROJECT-NAME>
6369 [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
6370 [DESCRIPTION <project-description-string>]
6371 [HOMEPAGE_URL <url-string>]
6372 [LANGUAGES <language-name>...])
6373 Sets the name of the project, and stores it in the variable
6375 PROJECT_NAME. When called from the top-level CMakeLists.txt also stores
6376 the project name in the variable CMAKE_PROJECT_NAME.
6377 Also sets the variables
6379 · PROJECT_SOURCE_DIR, <PROJECT-NAME>_SOURCE_DIR
6381 · PROJECT_BINARY_DIR, <PROJECT-NAME>_BINARY_DIR
6383 Further variables are set by the optional arguments described in the
6385 following. If any of these arguments is not used, then the correspond‐
6386 ing variables are set to the empty string.
6387 Options
6389 The options are:
6390 VERSION <version>
6392 Optional; may not be used unless policy CMP0048 is set to NEW.
6393 Takes a <version> argument composed of non-negative integer com‐
6395 ponents, i.e. <major>[.<minor>[.<patch>[.<tweak>]]], and sets
6396 the variables
6397 · PROJECT_VERSION, <PROJECT-NAME>_VERSION
6399 · PROJECT_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MAJOR
6401 · PROJECT_VERSION_MINOR, <PROJECT-NAME>_VERSION_MINOR
6403 · PROJECT_VERSION_PATCH, <PROJECT-NAME>_VERSION_PATCH
6405 · PROJECT_VERSION_TWEAK, <PROJECT-NAME>_VERSION_TWEAK.
6407 When the project() command is called from the top-level CMake‐
6409 Lists.txt, then the version is also stored in the variable
6410 CMAKE_PROJECT_VERSION.
6411 DESCRIPTION <project-description-string>
6413 Optional. Sets the variables
6414 · PROJECT_DESCRIPTION, <PROJECT-NAME>_DESCRIPTION
6416 to <project-description-string>. It is recommended that this
6418 description is a relatively short string, usually no more than a
6419 few words.
6420 When the project() command is called from the top-level CMake‐
6422 Lists.txt, then the description is also stored in the variable
6423 CMAKE_PROJECT_DESCRIPTION.
6424 HOMEPAGE_URL <url-string>
6426 Optional. Sets the variables
6427 · PROJECT_HOMEPAGE_URL, <PROJECT-NAME>_HOMEPAGE_URL
6429 to <url-string>, which should be the canonical home URL for the
6431 project.
6432 When the project() command is called from the top-level CMake‐
6434 Lists.txt, then the URL also is stored in the variable
6435 CMAKE_PROJECT_HOMEPAGE_URL.
6436 LANGUAGES <language-name>...
6438 Optional. Can also be specified without LANGUAGES keyword per
6439 the first, short signature.
6440 Selects which programming languages are needed to build the
6442 project. Supported languages include C, CXX (i.e. C++), CUDA,
6443 OBJC (i.e. Objective-C), OBJCXX, Fortran, and ASM. By default C
6444 and CXX are enabled if no language options are given. Specify
6445 language NONE, or use the LANGUAGES keyword and list no lan‐
6446 guages, to skip enabling any languages.
6447 If enabling ASM, list it last so that CMake can check whether
6449 compilers for other languages like C work for assembly too.
6450 The variables set through the VERSION, DESCRIPTION and HOMEPAGE_URL
6452 options are intended for use as default values in package metadata and
6453 documentation.
6454 Code Injection
6456 If the CMAKE_PROJECT_INCLUDE_BEFORE variable is set, the file pointed
6457 to by that variable will be included as the first step of the project()
6458 command.
6459 If the CMAKE_PROJECT_INCLUDE or CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE
6461 variables are set, the files they point to will be included as the last
6462 step of the project() command. If both are set, then
6463 CMAKE_PROJECT_INCLUDE will be included before
6464 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE.
6465 Usage
6467 The top-level CMakeLists.txt file for a project must contain a literal,
6468 direct call to the project() command; loading one through the include()
6469 command is not sufficient. If no such call exists, CMake will issue a
6470 warning and pretend there is a project(Project) at the top to enable
6471 the default languages (C and CXX).
6472 NOTE:
6474 Call the project() command near the top of the top-level CMake‐
6475 Lists.txt, but after calling cmake_minimum_required(). It is impor‐
6476 tant to establish version and policy settings before invoking other
6477 commands whose behavior they may affect. See also policy CMP0000.
6478 remove_definitions
6480 Remove -D define flags added by add_definitions().
6481 remove_definitions(-DFOO -DBAR ...)
6483 Removes flags (added by add_definitions()) from the compiler command
6485 line for sources in the current directory and below.
6486 set_source_files_properties
6488 Source files can have properties that affect how they are built.
6489 set_source_files_properties([file1 [file2 [...]]]
6491 PROPERTIES prop1 value1
6492 [prop2 value2 [...]])
6493 Sets properties associated with source files using a key/value paired
6495 list.
6496 See also the set_property(SOURCE) command.
6498 See Source File Properties for the list of properties known to CMake.
6500 Source file properties are visible only to targets added in the same
6501 directory (CMakeLists.txt).
6502 set_target_properties
6504 Targets can have properties that affect how they are built.
6505 set_target_properties(target1 target2 ...
6507 PROPERTIES prop1 value1
6508 prop2 value2 ...)
6509 Sets properties on targets. The syntax for the command is to list all
6511 the targets you want to change, and then provide the values you want to
6512 set next. You can use any prop value pair you want and extract it
6513 later with the get_property() or get_target_property() command.
6514 See also the set_property(TARGET) command.
6516 See Target Properties for the list of properties known to CMake.
6518 set_tests_properties
6520 Set a property of the tests.
6521 set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
6523 Sets a property for the tests. If the test is not found, CMake will
6525 report an error. Generator expressions will be expanded the same as
6526 supported by the test’s add_test() call.
6527 See also the set_property(TEST) command.
6529 See Test Properties for the list of properties known to CMake.
6531 source_group
6533 Define a grouping for source files in IDE project generation. There
6534 are two different signatures to create source groups.
6535 source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
6537 source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...])
6538 Defines a group into which sources will be placed in project files.
6540 This is intended to set up file tabs in Visual Studio. The options
6541 are:
6542 TREE CMake will automatically detect, from <src> files paths, source
6544 groups it needs to create, to keep structure of source groups
6545 analogically to the actual files and directories structure in
6546 the project. Paths of <src> files will be cut to be relative to
6547 <root>.
6548 PREFIX Source group and files located directly in <root> path, will be
6550 placed in <prefix> source groups.
6551 FILES Any source file specified explicitly will be placed in group
6553 <name>. Relative paths are interpreted with respect to the cur‐
6554 rent source directory.
6555 REGULAR_EXPRESSION
6557 Any source file whose name matches the regular expression will
6558 be placed in group <name>.
6559 If a source file matches multiple groups, the last group that explic‐
6561 itly lists the file with FILES will be favored, if any. If no group
6562 explicitly lists the file, the last group whose regular expression
6563 matches the file will be favored.
6564 The <name> of the group and <prefix> argument may contain backslashes
6566 to specify subgroups:
6567 source_group(outer\\inner ...)
6569 source_group(TREE <root> PREFIX sources\\inc ...)
6570 For backwards compatibility, the short-hand signature
6572 source_group(<name> <regex>)
6574 is equivalent to
6576 source_group(<name> REGULAR_EXPRESSION <regex>)
6578 target_compile_definitions
6580 Add compile definitions to a target.
6581 target_compile_definitions(<target>
6583 <INTERFACE|PUBLIC|PRIVATE> [items1...]
6584 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6585 Specifies compile definitions to use when compiling a given <target>.
6587 The named <target> must have been created by a command such as add_exe‐
6588 cutable() or add_library() and must not be an ALIAS target.
6589 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6591 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
6592 late the COMPILE_DEFINITIONS property of <target>. PUBLIC and INTERFACE
6593 items will populate the INTERFACE_COMPILE_DEFINITIONS property of <tar‐
6594 get>. (IMPORTED targets only support INTERFACE items.) The following
6595 arguments specify compile definitions. Repeated calls for the same
6596 <target> append items in the order called.
6597 Arguments to target_compile_definitions may use “generator expressions”
6599 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6600 for available expressions. See the cmake-buildsystem(7) manual for
6601 more on defining buildsystem properties.
6602 Any leading -D on an item will be removed. Empty items are ignored.
6604 For example, the following are all equivalent:
6605 target_compile_definitions(foo PUBLIC FOO)
6607 target_compile_definitions(foo PUBLIC -DFOO) # -D removed
6608 target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
6609 target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
6610 target_compile_features
6612 Add expected compiler features to a target.
6613 target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
6615 Specifies compiler features required when compiling a given target. If
6617 the feature is not listed in the CMAKE_C_COMPILE_FEATURES variable or
6618 CMAKE_CXX_COMPILE_FEATURES variable, then an error will be reported by
6619 CMake. If the use of the feature requires an additional compiler flag,
6620 such as -std=gnu++11, the flag will be added automatically.
6621 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6623 scope of the features. PRIVATE and PUBLIC items will populate the COM‐
6624 PILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
6625 populate the INTERFACE_COMPILE_FEATURES property of <target>.
6626 (IMPORTED targets only support INTERFACE items.) Repeated calls for
6627 the same <target> append items.
6628 The named <target> must have been created by a command such as add_exe‐
6630 cutable() or add_library() and must not be an ALIAS target.
6631 Arguments to target_compile_features may use “generator expressions”
6633 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6634 for available expressions. See the cmake-compile-features(7) manual
6635 for information on compile features and a list of supported compilers.
6636 target_compile_options
6638 Add compile options to a target.
6639 target_compile_options(<target> [BEFORE]
6641 <INTERFACE|PUBLIC|PRIVATE> [items1...]
6642 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6643 Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
6645 properties. These options are used when compiling the given <target>,
6646 which must have been created by a command such as add_executable() or
6647 add_library() and must not be an ALIAS target.
6648 Arguments
6650 If BEFORE is specified, the content will be prepended to the property
6651 instead of being appended.
6652 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6654 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
6655 late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
6656 items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
6657 (IMPORTED targets only support INTERFACE items.) The following argu‐
6658 ments specify compile options. Repeated calls for the same <target>
6659 append items in the order called.
6660 Arguments to target_compile_options may use “generator expressions”
6662 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6663 for available expressions. See the cmake-buildsystem(7) manual for
6664 more on defining buildsystem properties.
6665 The final set of compile or link options used for a target is con‐
6667 structed by accumulating options from the current target and the usage
6668 requirements of its dependencies. The set of options is de-duplicated
6669 to avoid repetition. While beneficial for individual options, the
6670 de-duplication step can break up option groups. For example, -D A -D B
6671 becomes -D A B. One may specify a group of options using shell-like
6672 quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and
6673 the rest of the option string is parsed using the separate_arguments()
6674 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
6675 -D B.
6676 See Also
6678 This command can be used to add any options. However, for adding pre‐
6679 processor definitions and include directories it is recommended to use
6680 the more specific commands target_compile_definitions() and tar‐
6681 get_include_directories().
6682 For directory-wide settings, there is the command add_com‐
6684 pile_options().
6685 target_include_directories
6687 Add include directories to a target.
6688 target_include_directories(<target> [SYSTEM] [BEFORE]
6690 <INTERFACE|PUBLIC|PRIVATE> [items1...]
6691 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6692 Specifies include directories to use when compiling a given target.
6694 The named <target> must have been created by a command such as add_exe‐
6695 cutable() or add_library() and must not be an ALIAS target.
6696 If BEFORE is specified, the content will be prepended to the property
6698 instead of being appended.
6699 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6701 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
6702 late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTER‐
6703 FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
6704 <target>. (IMPORTED targets only support INTERFACE items.) The fol‐
6705 lowing arguments specify include directories.
6706 Specified include directories may be absolute paths or relative paths.
6708 Repeated calls for the same <target> append items in the order called.
6709 If SYSTEM is specified, the compiler will be told the directories are
6710 meant as system include directories on some platforms (signalling this
6711 setting might achieve effects such as the compiler skipping warnings,
6712 or these fixed-install system files not being considered in dependency
6713 calculations - see compiler docs). If SYSTEM is used together with
6714 PUBLIC or INTERFACE, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
6715 property will be populated with the specified directories.
6716 Arguments to target_include_directories may use “generator expressions”
6718 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6719 for available expressions. See the cmake-buildsystem(7) manual for
6720 more on defining buildsystem properties.
6721 Include directories usage requirements commonly differ between the
6723 build-tree and the install-tree. The BUILD_INTERFACE and
6724 INSTALL_INTERFACE generator expressions can be used to describe sepa‐
6725 rate usage requirements based on the usage location. Relative paths
6726 are allowed within the INSTALL_INTERFACE expression and are interpreted
6727 relative to the installation prefix. For example:
6728 target_include_directories(mylib PUBLIC
6730 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
6731 $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
6732 )
6733 Creating Relocatable Packages
6735 Note that it is not advisable to populate the INSTALL_INTERFACE of the
6736 INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
6737 include directories of dependencies. That would hard-code into
6738 installed packages the include directory paths for dependencies as
6739 found on the machine the package was made on.
6740 The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
6742 suitable for specifying the required include directories for headers
6743 provided with the target itself, not those provided by the transitive
6744 dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
6745 Those dependencies should themselves be targets that specify their own
6746 header locations in INTERFACE_INCLUDE_DIRECTORIES.
6747 See the Creating Relocatable Packages section of the cmake-packages(7)
6749 manual for discussion of additional care that must be taken when speci‐
6750 fying usage requirements while creating packages for redistribution.
6751 target_link_directories
6753 Add link directories to a target.
6754 target_link_directories(<target> [BEFORE]
6756 <INTERFACE|PUBLIC|PRIVATE> [items1...]
6757 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6758 Specifies the paths in which the linker should search for libraries
6760 when linking a given target. Each item can be an absolute or relative
6761 path, with the latter being interpreted as relative to the current
6762 source directory. These items will be added to the link command.
6763 The named <target> must have been created by a command such as add_exe‐
6765 cutable() or add_library() and must not be an ALIAS target.
6766 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6768 scope of the items that follow them. PRIVATE and PUBLIC items will
6769 populate the LINK_DIRECTORIES property of <target>. PUBLIC and INTER‐
6770 FACE items will populate the INTERFACE_LINK_DIRECTORIES property of
6771 <target> (IMPORTED targets only support INTERFACE items). Each item
6772 specifies a link directory and will be converted to an absolute path if
6773 necessary before adding it to the relevant property. Repeated calls
6774 for the same <target> append items in the order called.
6775 If BEFORE is specified, the content will be prepended to the relevant
6777 property instead of being appended.
6778 Arguments to target_link_directories may use “generator expressions”
6780 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6781 for available expressions. See the cmake-buildsystem(7) manual for
6782 more on defining buildsystem properties.
6783 NOTE:
6785 This command is rarely necessary and should be avoided where there
6786 are other choices. Prefer to pass full absolute paths to libraries
6787 where possible, since this ensures the correct library will always
6788 be linked. The find_library() command provides the full path, which
6789 can generally be used directly in calls to target_link_libraries().
6790 Situations where a library search path may be needed include:
6791 · Project generators like Xcode where the user can switch target
6793 architecture at build time, but a full path to a library cannot be
6794 used because it only provides one architecture (i.e. it is not a
6795 universal binary).
6796 · Libraries may themselves have other private library dependencies
6798 that expect to be found via RPATH mechanisms, but some linkers are
6799 not able to fully decode those paths (e.g. due to the presence of
6800 things like $ORIGIN).
6801 target_link_libraries
6803 Specify libraries or flags to use when linking a given target and/or
6804 its dependents. Usage requirements from linked library targets will be
6805 propagated. Usage requirements of a target’s dependencies affect com‐
6806 pilation of its own sources.
6807 Overview
6809 This command has several signatures as detailed in subsections below.
6810 All of them have the general form
6811 target_link_libraries(<target> ... <item>... ...)
6813 The named <target> must have been created by a command such as add_exe‐
6815 cutable() or add_library() and must not be an ALIAS target. If policy
6816 CMP0079 is not set to NEW then the target must have been created in the
6817 current directory. Repeated calls for the same <target> append items
6818 in the order called.
6819 Each <item> may be:
6821 · A library target name: The generated link line will have the full
6823 path to the linkable library file associated with the target. The
6824 buildsystem will have a dependency to re-link <target> if the library
6825 file changes.
6826 The named target must be created by add_library() within the project
6828 or as an IMPORTED library. If it is created within the project an
6829 ordering dependency will automatically be added in the build system
6830 to make sure the named library target is up-to-date before the <tar‐
6831 get> links.
6832 If an imported library has the IMPORTED_NO_SONAME target property
6834 set, CMake may ask the linker to search for the library instead of
6835 using the full path (e.g. /usr/lib/libfoo.so becomes -lfoo).
6836 The full path to the target’s artifact will be quoted/escaped for the
6838 shell automatically.
6839 · A full path to a library file: The generated link line will normally
6841 preserve the full path to the file. The buildsystem will have a
6842 dependency to re-link <target> if the library file changes.
6843 There are some cases where CMake may ask the linker to search for the
6845 library (e.g. /usr/lib/libfoo.so becomes -lfoo), such as when a
6846 shared library is detected to have no SONAME field. See policy
6847 CMP0060 for discussion of another case.
6848 If the library file is in a macOS framework, the Headers directory of
6850 the framework will also be processed as a usage requirement. This
6851 has the same effect as passing the framework directory as an include
6852 directory.
6853 On Visual Studio Generators for VS 2010 and above, library files end‐
6855 ing in .targets will be treated as MSBuild targets files and imported
6856 into generated project files. This is not supported by other genera‐
6857 tors.
6858 The full path to the library file will be quoted/escaped for the
6860 shell automatically.
6861 · A plain library name: The generated link line will ask the linker to
6863 search for the library (e.g. foo becomes -lfoo or foo.lib).
6864 The library name/flag is treated as a command-line string fragment
6866 and will be used with no extra quoting or escaping.
6867 · A link flag: Item names starting with -, but not -l or -framework,
6869 are treated as linker flags. Note that such flags will be treated
6870 like any other library link item for purposes of transitive dependen‐
6871 cies, so they are generally safe to specify only as private link
6872 items that will not propagate to dependents.
6873 Link flags specified here are inserted into the link command in the
6875 same place as the link libraries. This might not be correct, depend‐
6876 ing on the linker. Use the LINK_OPTIONS target property or tar‐
6877 get_link_options() command to add link flags explicitly. The flags
6878 will then be placed at the toolchain-defined flag position in the
6879 link command.
6880 The link flag is treated as a command-line string fragment and will
6882 be used with no extra quoting or escaping.
6883 · A generator expression: A $<...> generator expression may evaluate to
6885 any of the above items or to a semicolon-separated list of them. If
6886 the ... contains any ; characters, e.g. after evaluation of a ${list}
6887 variable, be sure to use an explicitly quoted argument "$<...>" so
6888 that this command receives it as a single <item>.
6889 Additionally, a generator expression may be used as a fragment of any
6891 of the above items, e.g. foo$<1:_d>.
6892 Note that generator expressions will not be used in OLD handling of
6894 policy CMP0003 or policy CMP0004.
6895 · A debug, optimized, or general keyword immediately followed by
6897 another <item>. The item following such a keyword will be used only
6898 for the corresponding build configuration. The debug keyword corre‐
6899 sponds to the Debug configuration (or to configurations named in the
6900 DEBUG_CONFIGURATIONS global property if it is set). The optimized
6901 keyword corresponds to all other configurations. The general keyword
6902 corresponds to all configurations, and is purely optional. Higher
6903 granularity may be achieved for per-configuration rules by creating
6904 and linking to IMPORTED library targets. These keywords are inter‐
6905 preted immediately by this command and therefore have no special
6906 meaning when produced by a generator expression.
6907 Items containing ::, such as Foo::Bar, are assumed to be IMPORTED or
6909 ALIAS library target names and will cause an error if no such target
6910 exists. See policy CMP0028.
6911 See the cmake-buildsystem(7) manual for more on defining buildsystem
6913 properties.
6914 Libraries for a Target and/or its Dependents
6916 target_link_libraries(<target>
6917 <PRIVATE|PUBLIC|INTERFACE> <item>...
6918 [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
6919 The PUBLIC, PRIVATE and INTERFACE keywords can be used to specify both
6921 the link dependencies and the link interface in one command. Libraries
6922 and targets following PUBLIC are linked to, and are made part of the
6923 link interface. Libraries and targets following PRIVATE are linked to,
6924 but are not made part of the link interface. Libraries following
6925 INTERFACE are appended to the link interface and are not used for link‐
6926 ing <target>.
6927 Libraries for both a Target and its Dependents
6929 target_link_libraries(<target> <item>...)
6930 Library dependencies are transitive by default with this signature.
6932 When this target is linked into another target then the libraries
6933 linked to this target will appear on the link line for the other target
6934 too. This transitive “link interface” is stored in the INTER‐
6935 FACE_LINK_LIBRARIES target property and may be overridden by setting
6936 the property directly. When CMP0022 is not set to NEW, transitive
6937 linking is built in but may be overridden by the LINK_INTER‐
6938 FACE_LIBRARIES property. Calls to other signatures of this command may
6939 set the property making any libraries linked exclusively by this signa‐
6940 ture private.
6941 Libraries for a Target and/or its Dependents (Legacy)
6943 target_link_libraries(<target>
6944 <LINK_PRIVATE|LINK_PUBLIC> <lib>...
6945 [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
6946 The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both the
6948 link dependencies and the link interface in one command.
6949 This signature is for compatibility only. Prefer the PUBLIC or PRIVATE
6951 keywords instead.
6952 Libraries and targets following LINK_PUBLIC are linked to, and are made
6954 part of the INTERFACE_LINK_LIBRARIES. If policy CMP0022 is not NEW,
6955 they are also made part of the LINK_INTERFACE_LIBRARIES. Libraries and
6956 targets following LINK_PRIVATE are linked to, but are not made part of
6957 the INTERFACE_LINK_LIBRARIES (or LINK_INTERFACE_LIBRARIES).
6958 Libraries for Dependents Only (Legacy)
6960 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
6961 The LINK_INTERFACE_LIBRARIES mode appends the libraries to the INTER‐
6963 FACE_LINK_LIBRARIES target property instead of using them for linking.
6964 If policy CMP0022 is not NEW, then this mode also appends libraries to
6965 the LINK_INTERFACE_LIBRARIES and its per-configuration equivalent.
6966 This signature is for compatibility only. Prefer the INTERFACE mode
6968 instead.
6969 Libraries specified as debug are wrapped in a generator expression to
6971 correspond to debug builds. If policy CMP0022 is not NEW, the
6972 libraries are also appended to the LINK_INTERFACE_LIBRARIES_DEBUG prop‐
6973 erty (or to the properties corresponding to configurations listed in
6974 the DEBUG_CONFIGURATIONS global property if it is set). Libraries
6975 specified as optimized are appended to the INTERFACE_LINK_LIBRARIES
6976 property. If policy CMP0022 is not NEW, they are also appended to the
6977 LINK_INTERFACE_LIBRARIES property. Libraries specified as general (or
6978 without any keyword) are treated as if specified for both debug and
6979 optimized.
6980 Linking Object Libraries
6982 Object Libraries may be used as the <target> (first) argument of tar‐
6983 get_link_libraries to specify dependencies of their sources on other
6984 libraries. For example, the code
6985 add_library(A SHARED a.c)
6987 target_compile_definitions(A PUBLIC A)
6988 add_library(obj OBJECT obj.c)
6990 target_compile_definitions(obj PUBLIC OBJ)
6991 target_link_libraries(obj PUBLIC A)
6992 compiles obj.c with -DA -DOBJ and establishes usage requirements for
6994 obj that propagate to its dependents.
6995 Normal libraries and executables may link to Object Libraries to get
6997 their objects and usage requirements. Continuing the above example,
6998 the code
6999 add_library(B SHARED b.c)
7001 target_link_libraries(B PUBLIC obj)
7002 compiles b.c with -DA -DOBJ, creates shared library B with object files
7004 from b.c and obj.c, and links B to A. Furthermore, the code
7005 add_executable(main main.c)
7007 target_link_libraries(main B)
7008 compiles main.c with -DA -DOBJ and links executable main to B and A.
7010 The object library’s usage requirements are propagated transitively
7011 through B, but its object files are not.
7012 Object Libraries may “link” to other object libraries to get usage
7014 requirements, but since they do not have a link step nothing is done
7015 with their object files. Continuing from the above example, the code:
7016 add_library(obj2 OBJECT obj2.c)
7018 target_link_libraries(obj2 PUBLIC obj)
7019 add_executable(main2 main2.c)
7021 target_link_libraries(main2 obj2)
7022 compiles obj2.c with -DA -DOBJ, creates executable main2 with object
7024 files from main2.c and obj2.c, and links main2 to A.
7025 In other words, when Object Libraries appear in a target’s INTER‐
7027 FACE_LINK_LIBRARIES property they will be treated as Interface
7028 Libraries, but when they appear in a target’s LINK_LIBRARIES property
7029 their object files will be included in the link too.
7030 Cyclic Dependencies of Static Libraries
7032 The library dependency graph is normally acyclic (a DAG), but in the
7033 case of mutually-dependent STATIC libraries CMake allows the graph to
7034 contain cycles (strongly connected components). When another target
7035 links to one of the libraries, CMake repeats the entire connected com‐
7036 ponent. For example, the code
7037 add_library(A STATIC a.c)
7039 add_library(B STATIC b.c)
7040 target_link_libraries(A B)
7041 target_link_libraries(B A)
7042 add_executable(main main.c)
7043 target_link_libraries(main A)
7044 links main to A B A B. While one repetition is usually sufficient,
7046 pathological object file and symbol arrangements can require more. One
7047 may handle such cases by using the LINK_INTERFACE_MULTIPLICITY target
7048 property or by manually repeating the component in the last tar‐
7049 get_link_libraries call. However, if two archives are really so inter‐
7050 dependent they should probably be combined into a single archive, per‐
7051 haps by using Object Libraries.
7052 Creating Relocatable Packages
7054 Note that it is not advisable to populate the INTERFACE_LINK_LIBRARIES
7055 of a target with absolute paths to dependencies. That would hard-code
7056 into installed packages the library file paths for dependencies as
7057 found on the machine the package was made on.
7058 See the Creating Relocatable Packages section of the cmake-packages(7)
7060 manual for discussion of additional care that must be taken when speci‐
7061 fying usage requirements while creating packages for redistribution.
7062 target_link_options
7064 Add options to the link step for an executable, shared library or mod‐
7065 ule library target.
7066 target_link_options(<target> [BEFORE]
7068 <INTERFACE|PUBLIC|PRIVATE> [items1...]
7069 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
7070 The named <target> must have been created by a command such as add_exe‐
7072 cutable() or add_library() and must not be an ALIAS target.
7073 This command can be used to add any link options, but alternative com‐
7075 mands exist to add libraries (target_link_libraries() or
7076 link_libraries()). See documentation of the directory and target
7077 LINK_OPTIONS properties.
7078 NOTE:
7080 This command cannot be used to add options for static library tar‐
7081 gets, since they do not use a linker. To add archiver or MSVC
7082 librarian flags, see the STATIC_LIBRARY_OPTIONS target property.
7083 If BEFORE is specified, the content will be prepended to the property
7085 instead of being appended.
7086 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
7088 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
7089 late the LINK_OPTIONS property of <target>. PUBLIC and INTERFACE items
7090 will populate the INTERFACE_LINK_OPTIONS property of <target>.
7091 (IMPORTED targets only support INTERFACE items.) The following argu‐
7092 ments specify link options. Repeated calls for the same <target>
7093 append items in the order called.
7094 Arguments to target_link_options may use “generator expressions” with
7096 the syntax $<...>. See the cmake-generator-expressions(7) manual for
7097 available expressions. See the cmake-buildsystem(7) manual for more on
7098 defining buildsystem properties.
7099 The final set of compile or link options used for a target is con‐
7101 structed by accumulating options from the current target and the usage
7102 requirements of its dependencies. The set of options is de-duplicated
7103 to avoid repetition. While beneficial for individual options, the
7104 de-duplication step can break up option groups. For example, -D A -D B
7105 becomes -D A B. One may specify a group of options using shell-like
7106 quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and
7107 the rest of the option string is parsed using the separate_arguments()
7108 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
7109 -D B.
7110 To pass options to the linker tool, each compiler driver has its own
7112 syntax. The LINKER: prefix and , separator can be used to specify, in
7113 a portable way, options to pass to the linker tool. LINKER: is replaced
7114 by the appropriate driver option and , by the appropriate driver sepa‐
7115 rator. The driver prefix and driver separator are given by the values
7116 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAP‐
7117 PER_FLAG_SEP variables.
7118 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
7120 Clang and -Wl,-z,defs for GNU GCC.
7121 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
7123 sion.
7124 The LINKER: prefix supports, as an alternative syntax, specification of
7126 arguments using the SHELL: prefix and space as separator. The previous
7127 example then becomes "LINKER:SHELL:-z defs".
7128 NOTE:
7130 Specifying the SHELL: prefix anywhere other than at the beginning of
7131 the LINKER: prefix is not supported.
7132 target_precompile_headers
7134 Add a list of header files to precompile.
7135 Precompiling header files can speed up compilation by creating a par‐
7137 tially processed version of some header files, and then using that ver‐
7138 sion during compilations rather than repeatedly parsing the original
7139 headers.
7140 Main Form
7142 target_precompile_headers(<target>
7143 <INTERFACE|PUBLIC|PRIVATE> [header1...]
7144 [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])
7145 The command adds header files to the PRECOMPILE_HEADERS and/or INTER‐
7147 FACE_PRECOMPILE_HEADERS target properties of <target>. The named <tar‐
7148 get> must have been created by a command such as add_executable() or
7149 add_library() and must not be an ALIAS target.
7150 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
7152 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
7153 late the PRECOMPILE_HEADERS property of <target>. PUBLIC and INTERFACE
7154 items will populate the INTERFACE_PRECOMPILE_HEADERS property of <tar‐
7155 get> (IMPORTED targets only support INTERFACE items). Repeated calls
7156 for the same <target> will append items in the order called.
7157 Projects should generally avoid using PUBLIC or INTERFACE for targets
7159 that will be exported, or they should at least use the $<BUILD_INTER‐
7160 FACE:...> generator expression to prevent precompile headers from
7161 appearing in an installed exported target. Consumers of a target
7162 should typically be in control of what precompile headers they use, not
7163 have precompile headers forced on them by the targets being consumed
7164 (since precompile headers are not typically usage requirements). A
7165 notable exception to this is where an interface library is created to
7166 define a commonly used set of precompile headers in one place and then
7167 other targets link to that interface library privately. In this case,
7168 the interface library exists specifically to propagate the precompile
7169 headers to its consumers and the consumer is effectively still in con‐
7170 trol, since it decides whether to link to the interface library or not.
7171 The list of header files is used to generate a header file named
7173 cmake_pch.h|xx which is used to generate the precompiled header file
7174 (.pch, .gch, .pchi) artifact. The cmake_pch.h|xx header file will be
7175 force included (-include for GCC, /FI for MSVC) to all source files, so
7176 sources do not need to have #include "pch.h".
7177 Header file names specified with angle brackets (e.g. <unordered_map>)
7179 or explicit double quotes (escaped for the cmake-language(7), e.g.
7180 [["other_header.h"]]) will be treated as is, and include directories
7181 must be available for the compiler to find them. Other header file
7182 names (e.g. project_header.h) are interpreted as being relative to the
7183 current source directory (e.g. CMAKE_CURRENT_SOURCE_DIR) and will be
7184 included by absolute path.
7185 Arguments to target_precompile_headers() may use “generator expres‐
7187 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
7188 manual for available expressions. See the cmake-compile-features(7)
7189 manual for information on compile features and a list of supported com‐
7190 pilers. The $<COMPILE_LANGUAGE:...> generator expression is particu‐
7191 larly useful for specifying a language-specific header to precompile
7192 for only one language (e.g. CXX and not C). For example:
7193 target_precompile_headers(myTarget
7195 PUBLIC
7196 project_header.h
7197 "$<$<COMPILE_LANGUAGE:CXX>:cxx_only.h>"
7198 PRIVATE
7199 [["other_header.h"]]
7200 <unordered_map>
7201 )
7202 When specifying angle brackets inside a generator expression, be sure
7204 to encode the closing > as $<ANGLE-R>. For example:
7205 target_precompile_headers(mylib PRIVATE
7207 "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
7208 "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
7209 )
7210 Reusing Precompile Headers
7212 The command also supports a second signature which can be used to spec‐
7213 ify that one target re-uses a precompiled header file artefact from
7214 another target instead of generating its own:
7215 target_precompile_headers(<target> REUSE_FROM <other_target>)
7217 This form sets the PRECOMPILE_HEADERS_REUSE_FROM property to
7219 <other_target> and adds a dependency such that <target> will depend on
7220 <other_target>. CMake will halt with an error if the PRECOMPILE_HEAD‐
7221 ERS property of <target> is already set when the REUSE_FROM form is
7222 used.
7223 NOTE:
7225 The REUSE_FROM form requires the same set of compiler options, com‐
7226 piler flags and compiler definitions for both <target> and
7227 <other_target>. Some compilers (e.g. GCC) may issue a warning if
7228 the precompiled header file cannot be used (-Winvalid-pch).
7229 See Also
7231 To disable precompile headers for specific targets, see the DIS‐
7232 ABLE_PRECOMPILE_HEADERS target property.
7233 To prevent precompile headers from being used when compiling a specific
7235 source file, see the SKIP_PRECOMPILE_HEADERS source file property.
7236 target_sources
7238 Add sources to a target.
7239 target_sources(<target>
7241 <INTERFACE|PUBLIC|PRIVATE> [items1...]
7242 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
7243 Specifies sources to use when compiling a given target. Relative
7245 source file paths are interpreted as being relative to the current
7246 source directory (i.e. CMAKE_CURRENT_SOURCE_DIR). The named <target>
7247 must have been created by a command such as add_executable() or
7248 add_library() and must not be an ALIAS target.
7249 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
7251 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
7252 late the SOURCES property of <target>. PUBLIC and INTERFACE items will
7253 populate the INTERFACE_SOURCES property of <target>. (IMPORTED targets
7254 only support INTERFACE items.) The following arguments specify
7255 sources. Repeated calls for the same <target> append items in the
7256 order called.
7257 Arguments to target_sources may use “generator expressions” with the
7259 syntax $<...>. See the cmake-generator-expressions(7) manual for avail‐
7260 able expressions. See the cmake-buildsystem(7) manual for more on
7261 defining buildsystem properties.
7262 See also the CMP0076 policy for older behavior related to the handling
7264 of relative source file paths.
7265 try_compile
7267 Try building some code.
7268 Try Compiling Whole Projects
7270 try_compile(<resultVar> <bindir> <srcdir>
7271 <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
7272 [OUTPUT_VARIABLE <var>])
7273 Try building a project. The success or failure of the try_compile,
7275 i.e. TRUE or FALSE respectively, is returned in <resultVar>.
7276 In this form, <srcdir> should contain a complete CMake project with a
7278 CMakeLists.txt file and all sources. The <bindir> and <srcdir> will
7279 not be deleted after this command is run. Specify <targetName> to
7280 build a specific target instead of the all or ALL_BUILD target. See
7281 below for the meaning of other options.
7282 Try Compiling Source Files
7284 try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
7285 [CMAKE_FLAGS <flags>...]
7286 [COMPILE_DEFINITIONS <defs>...]
7287 [LINK_OPTIONS <options>...]
7288 [LINK_LIBRARIES <libs>...]
7289 [OUTPUT_VARIABLE <var>]
7290 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
7291 [<LANG>_STANDARD <std>]
7292 [<LANG>_STANDARD_REQUIRED <bool>]
7293 [<LANG>_EXTENSIONS <bool>]
7294 )
7295 Try building an executable or static library from one or more source
7297 files (which one is determined by the CMAKE_TRY_COMPILE_TARGET_TYPE
7298 variable). The success or failure of the try_compile, i.e. TRUE or
7299 FALSE respectively, is returned in <resultVar>.
7300 In this form, one or more source files must be provided. If
7302 CMAKE_TRY_COMPILE_TARGET_TYPE is unset or is set to EXECUTABLE, the
7303 sources must include a definition for main and CMake will create a
7304 CMakeLists.txt file to build the source(s) as an executable. If
7305 CMAKE_TRY_COMPILE_TARGET_TYPE is set to STATIC_LIBRARY, a static
7306 library will be built instead and no definition for main is required.
7307 For an executable, the generated CMakeLists.txt file would contain
7308 something like the following:
7309 add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
7311 include_directories(${INCLUDE_DIRECTORIES})
7312 link_directories(${LINK_DIRECTORIES})
7313 add_executable(cmTryCompileExec <srcfile>...)
7314 target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
7315 target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
7316 The options are:
7318 CMAKE_FLAGS <flags>...
7320 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
7321 cmake command-line used to drive the test build. The above
7322 example shows how values for variables INCLUDE_DIRECTORIES,
7323 LINK_DIRECTORIES, and LINK_LIBRARIES are used.
7324 COMPILE_DEFINITIONS <defs>...
7326 Specify -Ddefinition arguments to pass to add_definitions() in
7327 the generated test project.
7328 COPY_FILE <fileName>
7330 Copy the built executable or static library to the given <file‐
7331 Name>.
7332 COPY_FILE_ERROR <var>
7334 Use after COPY_FILE to capture into variable <var> any error
7335 message encountered while trying to copy the file.
7336 LINK_LIBRARIES <libs>...
7338 Specify libraries to be linked in the generated project. The
7339 list of libraries may refer to system libraries and to Imported
7340 Targets from the calling project.
7341 If this option is specified, any -DLINK_LIBRARIES=... value
7343 given to the CMAKE_FLAGS option will be ignored.
7344 LINK_OPTIONS <options>...
7346 Specify link step options to pass to target_link_options() or to
7347 set the STATIC_LIBRARY_OPTIONS target property in the generated
7348 project, depending on the CMAKE_TRY_COMPILE_TARGET_TYPE vari‐
7349 able.
7350 OUTPUT_VARIABLE <var>
7352 Store the output from the build process in the given variable.
7353 <LANG>_STANDARD <std>
7355 Specify the C_STANDARD, CXX_STANDARD, OBJC_STANDARD,
7356 OBJCXX_STANDARD, or CUDA_STANDARD target property of the gener‐
7357 ated project.
7358 <LANG>_STANDARD_REQUIRED <bool>
7360 Specify the C_STANDARD_REQUIRED, CXX_STANDARD_REQUIRED,
7361 OBJC_STANDARD_REQUIRED, OBJCXX_STANDARD_REQUIRED,or CUDA_STAN‐
7362 DARD_REQUIRED target property of the generated project.
7363 <LANG>_EXTENSIONS <bool>
7365 Specify the C_EXTENSIONS, CXX_EXTENSIONS, OBJC_EXTENSIONS,
7366 OBJCXX_EXTENSIONS, or CUDA_EXTENSIONS target property of the
7367 generated project.
7368 In this version all files in <bindir>/CMakeFiles/CMakeTmp will be
7370 cleaned automatically. For debugging, --debug-trycompile can be passed
7371 to cmake to avoid this clean. However, multiple sequential try_compile
7372 operations reuse this single output directory. If you use
7373 --debug-trycompile, you can only debug one try_compile call at a time.
7374 The recommended procedure is to protect all try_compile calls in your
7375 project by if(NOT DEFINED <resultVar>) logic, configure with cmake all
7376 the way through once, then delete the cache entry associated with the
7377 try_compile call of interest, and then re-run cmake again with
7378 --debug-trycompile.
7379 Other Behavior Settings
7381 If set, the following variables are passed in to the generated try_com‐
7382 pile CMakeLists.txt to initialize compile target properties with
7383 default values:
7384 · CMAKE_ENABLE_EXPORTS
7386 · CMAKE_LINK_SEARCH_START_STATIC
7388 · CMAKE_LINK_SEARCH_END_STATIC
7390 · CMAKE_MSVC_RUNTIME_LIBRARY
7392 · CMAKE_POSITION_INDEPENDENT_CODE
7394 If CMP0056 is set to NEW, then CMAKE_EXE_LINKER_FLAGS is passed in as
7396 well.
7397 If CMP0083 is set to NEW, then in order to obtain correct behavior at
7399 link time, the check_pie_supported() command from the CheckPIESupported
7400 module must be called before using the try_compile() command.
7401 The current settings of CMP0065 and CMP0083 are propagated through to
7403 the generated test project.
7404 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
7406 figuration.
7407 Set the CMAKE_TRY_COMPILE_TARGET_TYPE variable to specify the type of
7409 target used for the source file signature.
7410 Set the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable to specify vari‐
7412 ables that must be propagated into the test project. This variable is
7413 meant for use only in toolchain files and is only honored by the
7414 try_compile() command for the source files form, not when given a whole
7415 project.
7416 If CMP0067 is set to NEW, or any of the <LANG>_STANDARD, <LANG>_STAN‐
7418 DARD_REQUIRED, or <LANG>_EXTENSIONS options are used, then the language
7419 standard variables are honored:
7420 · CMAKE_C_STANDARD
7422 · CMAKE_C_STANDARD_REQUIRED
7424 · CMAKE_C_EXTENSIONS
7426 · CMAKE_CXX_STANDARD
7428 · CMAKE_CXX_STANDARD_REQUIRED
7430 · CMAKE_CXX_EXTENSIONS
7432 · CMAKE_OBJC_STANDARD
7434 · CMAKE_OBJC_STANDARD_REQUIRED
7436 · CMAKE_OBJC_EXTENSIONS
7438 · CMAKE_OBJCXX_STANDARD
7440 · CMAKE_OBJCXX_STANDARD_REQUIRED
7442 · CMAKE_OBJCXX_EXTENSIONS
7444 · CMAKE_CUDA_STANDARD
7446 · CMAKE_CUDA_STANDARD_REQUIRED
7448 · CMAKE_CUDA_EXTENSIONS
7450 Their values are used to set the corresponding target properties in the
7452 generated project (unless overridden by an explicit option).
7453 For the Green Hills MULTI generator the GHS toolset and target system
7455 customization cache variables are also propagated into the test
7456 project.
7457 try_run
7459 Try compiling and then running some code.
7460 Try Compiling and Running Source Files
7462 try_run(<runResultVar> <compileResultVar>
7463 <bindir> <srcfile> [CMAKE_FLAGS <flags>...]
7464 [COMPILE_DEFINITIONS <defs>...]
7465 [LINK_OPTIONS <options>...]
7466 [LINK_LIBRARIES <libs>...]
7467 [COMPILE_OUTPUT_VARIABLE <var>]
7468 [RUN_OUTPUT_VARIABLE <var>]
7469 [OUTPUT_VARIABLE <var>]
7470 [ARGS <args>...])
7471 Try compiling a <srcfile>. Returns TRUE or FALSE for success or fail‐
7473 ure in <compileResultVar>. If the compile succeeded, runs the exe‐
7474 cutable and returns its exit code in <runResultVar>. If the executable
7475 was built, but failed to run, then <runResultVar> will be set to
7476 FAILED_TO_RUN. See the try_compile() command for information on how
7477 the test project is constructed to build the source file.
7478 The options are:
7480 CMAKE_FLAGS <flags>...
7482 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
7483 cmake command-line used to drive the test build. The example in
7484 try_compile() shows how values for variables INCLUDE_DIRECTO‐
7485 RIES, LINK_DIRECTORIES, and LINK_LIBRARIES are used.
7486 COMPILE_DEFINITIONS <defs>...
7488 Specify -Ddefinition arguments to pass to add_definitions() in
7489 the generated test project.
7490 COMPILE_OUTPUT_VARIABLE <var>
7492 Report the compile step build output in a given variable.
7493 LINK_LIBRARIES <libs>...
7495 Specify libraries to be linked in the generated project. The
7496 list of libraries may refer to system libraries and to Imported
7497 Targets from the calling project.
7498 If this option is specified, any -DLINK_LIBRARIES=... value
7500 given to the CMAKE_FLAGS option will be ignored.
7501 LINK_OPTIONS <options>...
7503 Specify link step options to pass to target_link_options() in
7504 the generated project.
7505 OUTPUT_VARIABLE <var>
7507 Report the compile build output and the output from running the
7508 executable in the given variable. This option exists for legacy
7509 reasons. Prefer COMPILE_OUTPUT_VARIABLE and RUN_OUTPUT_VARIABLE
7510 instead.
7511 RUN_OUTPUT_VARIABLE <var>
7513 Report the output from running the executable in a given vari‐
7514 able.
7515 Other Behavior Settings
7517 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
7518 figuration.
7519 Behavior when Cross Compiling
7521 When cross compiling, the executable compiled in the first step usually
7522 cannot be run on the build host. The try_run command checks the
7523 CMAKE_CROSSCOMPILING variable to detect whether CMake is in cross-com‐
7524 piling mode. If that is the case, it will still try to compile the
7525 executable, but it will not try to run the executable unless the
7526 CMAKE_CROSSCOMPILING_EMULATOR variable is set. Instead it will create
7527 cache variables which must be filled by the user or by presetting them
7528 in some CMake script file to the values the executable would have pro‐
7529 duced if it had been run on its actual target platform. These cache
7530 entries are:
7531 <runResultVar>
7533 Exit code if the executable were to be run on the target plat‐
7534 form.
7535 <runResultVar>__TRYRUN_OUTPUT
7537 Output from stdout and stderr if the executable were to be run
7538 on the target platform. This is created only if the RUN_OUT‐
7539 PUT_VARIABLE or OUTPUT_VARIABLE option was used.
7540 In order to make cross compiling your project easier, use try_run only
7542 if really required. If you use try_run, use the RUN_OUTPUT_VARIABLE or
7543 OUTPUT_VARIABLE options only if really required. Using them will
7544 require that when cross-compiling, the cache variables will have to be
7545 set manually to the output of the executable. You can also “guard” the
7546 calls to try_run with an if() block checking the CMAKE_CROSSCOMPILING
7547 variable and provide an easy-to-preset alternative for this case.
7548
7550 These commands are available only in CTest scripts.
7551 ctest_build
7553 Perform the CTest Build Step as a Dashboard Client.
7554 ctest_build([BUILD <build-dir>] [APPEND]
7556 [CONFIGURATION <config>]
7557 [FLAGS <flags>]
7558 [PROJECT_NAME <project-name>]
7559 [TARGET <target-name>]
7560 [NUMBER_ERRORS <num-err-var>]
7561 [NUMBER_WARNINGS <num-warn-var>]
7562 [RETURN_VALUE <result-var>]
7563 [CAPTURE_CMAKE_ERROR <result-var>]
7564 )
7565 Build the project and store results in Build.xml for submission with
7567 the ctest_submit() command.
7568 The CTEST_BUILD_COMMAND variable may be set to explicitly specify the
7570 build command line. Otherwise the build command line is computed auto‐
7571 matically based on the options given.
7572 The options are:
7574 BUILD <build-dir>
7576 Specify the top-level build directory. If not given, the
7577 CTEST_BINARY_DIRECTORY variable is used.
7578 APPEND Mark Build.xml for append to results previously submitted to a
7580 dashboard server since the last ctest_start() call. Append
7581 semantics are defined by the dashboard server in use. This does
7582 not cause results to be appended to a .xml file produced by a
7583 previous call to this command.
7584 CONFIGURATION <config>
7586 Specify the build configuration (e.g. Debug). If not specified
7587 the CTEST_BUILD_CONFIGURATION variable will be checked. Other‐
7588 wise the -C <cfg> option given to the ctest(1) command will be
7589 used, if any.
7590 FLAGS <flags>
7592 Pass additional arguments to the underlying build command. If
7593 not specified the CTEST_BUILD_FLAGS variable will be checked.
7594 This can, e.g., be used to trigger a parallel build using the -j
7595 option of make. See the ProcessorCount module for an example.
7596 PROJECT_NAME <project-name>
7598 Ignored. This was once used but is no longer needed.
7599 TARGET <target-name>
7601 Specify the name of a target to build. If not specified the
7602 CTEST_BUILD_TARGET variable will be checked. Otherwise the
7603 default target will be built. This is the “all” target (called
7604 ALL_BUILD in Visual Studio Generators).
7605 NUMBER_ERRORS <num-err-var>
7607 Store the number of build errors detected in the given variable.
7608 NUMBER_WARNINGS <num-warn-var>
7610 Store the number of build warnings detected in the given vari‐
7611 able.
7612 RETURN_VALUE <result-var>
7614 Store the return value of the native build tool in the given
7615 variable.
7616 CAPTURE_CMAKE_ERROR <result-var>
7618 Store in the <result-var> variable -1 if there are any errors
7619 running the command and prevent ctest from returning non-zero if
7620 an error occurs.
7621 QUIET Suppress any CTest-specific non-error output that would have
7623 been printed to the console otherwise. The summary of warnings
7624 / errors, as well as the output from the native build tool is
7625 unaffected by this option.
7626 ctest_configure
7628 Perform the CTest Configure Step as a Dashboard Client.
7629 ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
7631 [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
7632 [CAPTURE_CMAKE_ERROR <result-var>])
7633 Configure the project build tree and record results in Configure.xml
7635 for submission with the ctest_submit() command.
7636 The options are:
7638 BUILD <build-dir>
7640 Specify the top-level build directory. If not given, the
7641 CTEST_BINARY_DIRECTORY variable is used.
7642 SOURCE <source-dir>
7644 Specify the source directory. If not given, the
7645 CTEST_SOURCE_DIRECTORY variable is used.
7646 APPEND Mark Configure.xml for append to results previously submitted to
7648 a dashboard server since the last ctest_start() call. Append
7649 semantics are defined by the dashboard server in use. This does
7650 not cause results to be appended to a .xml file produced by a
7651 previous call to this command.
7652 OPTIONS <options>
7654 Specify command-line arguments to pass to the configuration
7655 tool.
7656 RETURN_VALUE <result-var>
7658 Store in the <result-var> variable the return value of the
7659 native configuration tool.
7660 CAPTURE_CMAKE_ERROR <result-var>
7662 Store in the <result-var> variable -1 if there are any errors
7663 running the command and prevent ctest from returning non-zero if
7664 an error occurs.
7665 QUIET Suppress any CTest-specific non-error messages that would have
7667 otherwise been printed to the console. Output from the underly‐
7668 ing configure command is not affected.
7669 ctest_coverage
7671 Perform the CTest Coverage Step as a Dashboard Client.
7672 ctest_coverage([BUILD <build-dir>] [APPEND]
7674 [LABELS <label>...]
7675 [RETURN_VALUE <result-var>]
7676 [CAPTURE_CMAKE_ERROR <result-var>]
7677 [QUIET]
7678 )
7679 Collect coverage tool results and stores them in Coverage.xml for sub‐
7681 mission with the ctest_submit() command.
7682 The options are:
7684 BUILD <build-dir>
7686 Specify the top-level build directory. If not given, the
7687 CTEST_BINARY_DIRECTORY variable is used.
7688 APPEND Mark Coverage.xml for append to results previously submitted to
7690 a dashboard server since the last ctest_start() call. Append
7691 semantics are defined by the dashboard server in use. This does
7692 not cause results to be appended to a .xml file produced by a
7693 previous call to this command.
7694 LABELS Filter the coverage report to include only source files labeled
7696 with at least one of the labels specified.
7697 RETURN_VALUE <result-var>
7699 Store in the <result-var> variable 0 if coverage tools ran with‐
7700 out error and non-zero otherwise.
7701 CAPTURE_CMAKE_ERROR <result-var>
7703 Store in the <result-var> variable -1 if there are any errors
7704 running the command and prevent ctest from returning non-zero if
7705 an error occurs.
7706 QUIET Suppress any CTest-specific non-error output that would have
7708 been printed to the console otherwise. The summary indicating
7709 how many lines of code were covered is unaffected by this
7710 option.
7711 ctest_empty_binary_directory
7713 empties the binary directory
7714 ctest_empty_binary_directory( directory )
7716 Removes a binary directory. This command will perform some checks
7718 prior to deleting the directory in an attempt to avoid malicious or
7719 accidental directory deletion.
7720 ctest_memcheck
7722 Perform the CTest MemCheck Step as a Dashboard Client.
7723 ctest_memcheck([BUILD <build-dir>] [APPEND]
7725 [START <start-number>]
7726 [END <end-number>]
7727 [STRIDE <stride-number>]
7728 [EXCLUDE <exclude-regex>]
7729 [INCLUDE <include-regex>]
7730 [EXCLUDE_LABEL <label-exclude-regex>]
7731 [INCLUDE_LABEL <label-include-regex>]
7732 [EXCLUDE_FIXTURE <regex>]
7733 [EXCLUDE_FIXTURE_SETUP <regex>]
7734 [EXCLUDE_FIXTURE_CLEANUP <regex>]
7735 [PARALLEL_LEVEL <level>]
7736 [TEST_LOAD <threshold>]
7737 [SCHEDULE_RANDOM <ON|OFF>]
7738 [STOP_TIME <time-of-day>]
7739 [RETURN_VALUE <result-var>]
7740 [DEFECT_COUNT <defect-count-var>]
7741 [QUIET]
7742 )
7743 Run tests with a dynamic analysis tool and store results in Mem‐
7745 Check.xml for submission with the ctest_submit() command.
7746 Most options are the same as those for the ctest_test() command.
7748 The options unique to this command are:
7750 DEFECT_COUNT <defect-count-var>
7752 Store in the <defect-count-var> the number of defects found.
7753 ctest_read_custom_files
7755 read CTestCustom files.
7756 ctest_read_custom_files( directory ... )
7758 Read all the CTestCustom.ctest or CTestCustom.cmake files from the
7760 given directory.
7761 By default, invoking ctest(1) without a script will read custom files
7763 from the binary directory.
7764 ctest_run_script
7766 runs a ctest -S script
7767 ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
7769 script_file_name2 ... [RETURN_VALUE var])
7770 Runs a script or scripts much like if it was run from ctest -S. If no
7772 argument is provided then the current script is run using the current
7773 settings of the variables. If NEW_PROCESS is specified then each
7774 script will be run in a separate process.If RETURN_VALUE is specified
7775 the return value of the last script run will be put into var.
7776 ctest_sleep
7778 sleeps for some amount of time
7779 ctest_sleep(<seconds>)
7781 Sleep for given number of seconds.
7783 ctest_sleep(<time1> <duration> <time2>)
7785 Sleep for t=(time1 + duration - time2) seconds if t > 0.
7787 ctest_start
7789 Starts the testing for a given model
7790 ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])
7792 ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET])
7794 Starts the testing for a given model. The command should be called
7796 after the binary directory is initialized.
7797 The parameters are as follows:
7799 <model>
7801 Set the dashboard model. Must be one of Experimental, Continu‐
7802 ous, or Nightly. This parameter is required unless APPEND is
7803 specified.
7804 <source>
7806 Set the source directory. If not specified, the value of
7807 CTEST_SOURCE_DIRECTORY is used instead.
7808 <binary>
7810 Set the binary directory. If not specified, the value of
7811 CTEST_BINARY_DIRECTORY is used instead.
7812 GROUP <group>
7814 If GROUP is used, the submissions will go to the specified group
7815 on the CDash server. If no GROUP is specified, the name of the
7816 model is used by default. This replaces the deprecated option
7817 TRACK. Despite the name change its behavior is unchanged.
7818 APPEND If APPEND is used, the existing TAG is used rather than creating
7820 a new one based on the current time stamp. If you use APPEND,
7821 you can omit the <model> and GROUP <group> parameters, because
7822 they will be read from the generated TAG file. For example:
7823 ctest_start(Experimental GROUP GroupExperimental)
7825 Later, in another ctest -S script:
7827 ctest_start(APPEND)
7829 When the second script runs ctest_start(APPEND), it will read
7831 the Experimental model and GroupExperimental group from the TAG
7832 file generated by the first ctest_start() command. Please note
7833 that if you call ctest_start(APPEND) and specify a different
7834 model or group than in the first ctest_start() command, a warn‐
7835 ing will be issued, and the new model and group will be used.
7836 QUIET If QUIET is used, CTest will suppress any non-error messages
7838 that it otherwise would have printed to the console.
7839 The parameters for ctest_start() can be issued in any order, with the
7841 exception that <model>, <source>, and <binary> have to appear in that
7842 order with respect to each other. The following are all valid and
7843 equivalent:
7844 ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND)
7846 ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary)
7848 ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary)
7850 However, for the sake of readability, it is recommended that you order
7852 your parameters in the order listed at the top of this page.
7853 If the CTEST_CHECKOUT_COMMAND variable (or the CTEST_CVS_CHECKOUT vari‐
7855 able) is set, its content is treated as command-line. The command is
7856 invoked with the current working directory set to the parent of the
7857 source directory, even if the source directory already exists. This
7858 can be used to create the source tree from a version control reposi‐
7859 tory.
7860 ctest_submit
7862 Perform the CTest Submit Step as a Dashboard Client.
7863 ctest_submit([PARTS <part>...] [FILES <file>...]
7865 [SUBMIT_URL <url>]
7866 [BUILD_ID <result-var>]
7867 [HTTPHEADER <header>]
7868 [RETRY_COUNT <count>]
7869 [RETRY_DELAY <delay>]
7870 [RETURN_VALUE <result-var>]
7871 [CAPTURE_CMAKE_ERROR <result-var>]
7872 [QUIET]
7873 )
7874 Submit results to a dashboard server. By default all available parts
7876 are submitted.
7877 The options are:
7879 PARTS <part>...
7881 Specify a subset of parts to submit. Valid part names are:
7882 Start = nothing
7884 Update = ctest_update results, in Update.xml
7885 Configure = ctest_configure results, in Configure.xml
7886 Build = ctest_build results, in Build.xml
7887 Test = ctest_test results, in Test.xml
7888 Coverage = ctest_coverage results, in Coverage.xml
7889 MemCheck = ctest_memcheck results, in DynamicAnalysis.xml
7890 Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
7891 ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
7892 Upload = Files prepared for upload by ctest_upload(), in Upload.xml
7893 Submit = nothing
7894 Done = Build is complete, in Done.xml
7895 FILES <file>...
7897 Specify an explicit list of specific files to be submitted.
7898 Each individual file must exist at the time of the call.
7899 SUBMIT_URL <url>
7901 The http or https URL of the dashboard server to send the sub‐
7902 mission to. If not given, the CTEST_SUBMIT_URL variable is
7903 used.
7904 BUILD_ID <result-var>
7906 Store in the <result-var> variable the ID assigned to this build
7907 by CDash.
7908 HTTPHEADER <HTTP-header>
7910 Specify HTTP header to be included in the request to CDash dur‐
7911 ing submission. For example, CDash can be configured to only
7912 accept submissions from authenticated clients. In this case, you
7913 should provide a bearer token in your header:
7914 ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>")
7916 This suboption can be repeated several times for multiple head‐
7918 ers.
7919 RETRY_COUNT <count>
7921 Specify how many times to retry a timed-out submission.
7922 RETRY_DELAY <delay>
7924 Specify how long (in seconds) to wait after a timed-out submis‐
7925 sion before attempting to re-submit.
7926 RETURN_VALUE <result-var>
7928 Store in the <result-var> variable 0 for success and non-zero on
7929 failure.
7930 CAPTURE_CMAKE_ERROR <result-var>
7932 Store in the <result-var> variable -1 if there are any errors
7933 running the command and prevent ctest from returning non-zero if
7934 an error occurs.
7935 QUIET Suppress all non-error messages that would have otherwise been
7937 printed to the console.
7938 Submit to CDash Upload API
7940 ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
7941 [SUBMIT_URL <url>]
7942 [HTTPHEADER <header>]
7943 [RETRY_COUNT <count>]
7944 [RETRY_DELAY <delay>]
7945 [RETURN_VALUE <result-var>]
7946 [QUIET])
7947 This second signature is used to upload files to CDash via the CDash
7949 file upload API. The API first sends a request to upload to CDash along
7950 with a content hash of the file. If CDash does not already have the
7951 file, then it is uploaded. Along with the file, a CDash type string is
7952 specified to tell CDash which handler to use to process the data.
7953 This signature accepts the SUBMIT_URL, BUILD_ID, HTTPHEADER,
7955 RETRY_COUNT, RETRY_DELAY, RETURN_VALUE and QUIET options as described
7956 above.
7957 ctest_test
7959 Perform the CTest Test Step as a Dashboard Client.
7960 ctest_test([BUILD <build-dir>] [APPEND]
7962 [START <start-number>]
7963 [END <end-number>]
7964 [STRIDE <stride-number>]
7965 [EXCLUDE <exclude-regex>]
7966 [INCLUDE <include-regex>]
7967 [EXCLUDE_LABEL <label-exclude-regex>]
7968 [INCLUDE_LABEL <label-include-regex>]
7969 [EXCLUDE_FIXTURE <regex>]
7970 [EXCLUDE_FIXTURE_SETUP <regex>]
7971 [EXCLUDE_FIXTURE_CLEANUP <regex>]
7972 [PARALLEL_LEVEL <level>]
7973 [RESOURCE_SPEC_FILE <file>]
7974 [TEST_LOAD <threshold>]
7975 [SCHEDULE_RANDOM <ON|OFF>]
7976 [STOP_TIME <time-of-day>]
7977 [RETURN_VALUE <result-var>]
7978 [CAPTURE_CMAKE_ERROR <result-var>]
7979 [QUIET]
7980 )
7981 Run tests in the project build tree and store results in Test.xml for
7983 submission with the ctest_submit() command.
7984 The options are:
7986 BUILD <build-dir>
7988 Specify the top-level build directory. If not given, the
7989 CTEST_BINARY_DIRECTORY variable is used.
7990 APPEND Mark Test.xml for append to results previously submitted to a
7992 dashboard server since the last ctest_start() call. Append
7993 semantics are defined by the dashboard server in use. This does
7994 not cause results to be appended to a .xml file produced by a
7995 previous call to this command.
7996 START <start-number>
7998 Specify the beginning of a range of test numbers.
7999 END <end-number>
8001 Specify the end of a range of test numbers.
8002 STRIDE <stride-number>
8004 Specify the stride by which to step across a range of test num‐
8005 bers.
8006 EXCLUDE <exclude-regex>
8008 Specify a regular expression matching test names to exclude.
8009 INCLUDE <include-regex>
8011 Specify a regular expression matching test names to include.
8012 Tests not matching this expression are excluded.
8013 EXCLUDE_LABEL <label-exclude-regex>
8015 Specify a regular expression matching test labels to exclude.
8016 INCLUDE_LABEL <label-include-regex>
8018 Specify a regular expression matching test labels to include.
8019 Tests not matching this expression are excluded.
8020 EXCLUDE_FIXTURE <regex>
8022 If a test in the set of tests to be executed requires a particu‐
8023 lar fixture, that fixture’s setup and cleanup tests would nor‐
8024 mally be added to the test set automatically. This option pre‐
8025 vents adding setup or cleanup tests for fixtures matching the
8026 <regex>. Note that all other fixture behavior is retained,
8027 including test dependencies and skipping tests that have fixture
8028 setup tests that fail.
8029 EXCLUDE_FIXTURE_SETUP <regex>
8031 Same as EXCLUDE_FIXTURE except only matching setup tests are
8032 excluded.
8033 EXCLUDE_FIXTURE_CLEANUP <regex>
8035 Same as EXCLUDE_FIXTURE except only matching cleanup tests are
8036 excluded.
8037 PARALLEL_LEVEL <level>
8039 Specify a positive number representing the number of tests to be
8040 run in parallel.
8041 RESOURCE_SPEC_FILE <file>
8043 Specify a resource specification file. See ctest-resource-allo‐
8044 cation for more information.
8045 TEST_LOAD <threshold>
8047 While running tests in parallel, try not to start tests when
8048 they may cause the CPU load to pass above a given threshold. If
8049 not specified the CTEST_TEST_LOAD variable will be checked, and
8050 then the --test-load command-line argument to ctest(1). See
8051 also the TestLoad setting in the CTest Test Step.
8052 SCHEDULE_RANDOM <ON|OFF>
8054 Launch tests in a random order. This may be useful for detect‐
8055 ing implicit test dependencies.
8056 STOP_TIME <time-of-day>
8058 Specify a time of day at which the tests should all stop run‐
8059 ning.
8060 RETURN_VALUE <result-var>
8062 Store in the <result-var> variable 0 if all tests passed. Store
8063 non-zero if anything went wrong.
8064 CAPTURE_CMAKE_ERROR <result-var>
8066 Store in the <result-var> variable -1 if there are any errors
8067 running the command and prevent ctest from returning non-zero if
8068 an error occurs.
8069 QUIET Suppress any CTest-specific non-error messages that would have
8071 otherwise been printed to the console. Output from the underly‐
8072 ing test command is not affected. Summary info detailing the
8073 percentage of passing tests is also unaffected by the QUIET
8074 option.
8075 See also the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE and
8077 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables.
8078 ctest_update
8080 Perform the CTest Update Step as a Dashboard Client.
8081 ctest_update([SOURCE <source-dir>]
8083 [RETURN_VALUE <result-var>]
8084 [CAPTURE_CMAKE_ERROR <result-var>]
8085 [QUIET])
8086 Update the source tree from version control and record results in
8088 Update.xml for submission with the ctest_submit() command.
8089 The options are:
8091 SOURCE <source-dir>
8093 Specify the source directory. If not given, the
8094 CTEST_SOURCE_DIRECTORY variable is used.
8095 RETURN_VALUE <result-var>
8097 Store in the <result-var> variable the number of files updated
8098 or -1 on error.
8099 CAPTURE_CMAKE_ERROR <result-var>
8101 Store in the <result-var> variable -1 if there are any errors
8102 running the command and prevent ctest from returning non-zero if
8103 an error occurs.
8104 QUIET Tell CTest to suppress most non-error messages that it would
8106 have otherwise printed to the console. CTest will still report
8107 the new revision of the repository and any conflicting files
8108 that were found.
8109 The update always follows the version control branch currently checked
8111 out in the source directory. See the CTest Update Step documentation
8112 for information about variables that change the behavior of
8113 ctest_update().
8114 ctest_upload
8116 Upload files to a dashboard server as a Dashboard Client.
8117 ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
8119 The options are:
8121 FILES <file>...
8123 Specify a list of files to be sent along with the build results
8124 to the dashboard server.
8125 QUIET Suppress any CTest-specific non-error output that would have
8127 been printed to the console otherwise.
8128 CAPTURE_CMAKE_ERROR <result-var>
8130 Store in the <result-var> variable -1 if there are any errors
8131 running the command and prevent ctest from returning non-zero if
8132 an error occurs.
8133
8135 These commands are deprecated and are only made available to maintain
8136 backward compatibility. The documentation of each command states the
8137 CMake version in which it was deprecated. Do not use these commands in
8138 new code.
8139 build_name
8141 Disallowed since version 3.0. See CMake Policy CMP0036.
8142 Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.
8144 build_name(variable)
8146 Sets the specified variable to a string representing the platform and
8148 compiler settings. These values are now available through the
8149 CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
8150 exec_program
8152 Deprecated since version 3.0: Use the execute_process() command
8153 instead.
8154 Run an executable program during the processing of the CMakeList.txt
8157 file.
8158 exec_program(Executable [directory in which to run]
8160 [ARGS <arguments to executable>]
8161 [OUTPUT_VARIABLE <var>]
8162 [RETURN_VALUE <var>])
8163 The executable is run in the optionally specified directory. The exe‐
8165 cutable can include arguments if it is double quoted, but it is better
8166 to use the optional ARGS argument to specify arguments to the program.
8167 This is because cmake will then be able to escape spaces in the exe‐
8168 cutable path. An optional argument OUTPUT_VARIABLE specifies a vari‐
8169 able in which to store the output. To capture the return value of the
8170 execution, provide a RETURN_VALUE. If OUTPUT_VARIABLE is specified,
8171 then no output will go to the stdout/stderr of the console running
8172 cmake.
8173 export_library_dependencies
8175 Disallowed since version 3.0. See CMake Policy CMP0033.
8176 Use install(EXPORT) or export() command.
8178 This command generates an old-style library dependencies file.
8180 Projects requiring CMake 2.6 or later should not use the command. Use
8181 instead the install(EXPORT) command to help export targets from an
8182 installation tree and the export() command to export targets from a
8183 build tree.
8184 The old-style library dependencies file does not take into account
8186 per-configuration names of libraries or the LINK_INTERFACE_LIBRARIES
8187 target property.
8188 export_library_dependencies(<file> [APPEND])
8190 Create a file named <file> that can be included into a CMake listfile
8192 with the INCLUDE command. The file will contain a number of SET com‐
8193 mands that will set all the variables needed for library dependency
8194 information. This should be the last command in the top level CMake‐
8195 Lists.txt file of the project. If the APPEND option is specified, the
8196 SET commands will be appended to the given file instead of replacing
8197 it.
8198 install_files
8200 Deprecated since version 3.0: Use the install(FILES) command instead.
8201 This command has been superceded by the install() command. It is pro‐
8204 vided for compatibility with older CMake code. The FILES form is
8205 directly replaced by the FILES form of the install() command. The reg‐
8206 exp form can be expressed more clearly using the GLOB form of the
8207 file() command.
8208 install_files(<dir> extension file file ...)
8210 Create rules to install the listed files with the given extension into
8212 the given directory. Only files existing in the current source tree or
8213 its corresponding location in the binary tree may be listed. If a file
8214 specified already has an extension, that extension will be removed
8215 first. This is useful for providing lists of source files such as
8216 foo.cxx when you want the corresponding foo.h to be installed. A typi‐
8217 cal extension is .h.
8218 install_files(<dir> regexp)
8220 Any files in the current source directory that match the regular
8222 expression will be installed.
8223 install_files(<dir> FILES file file ...)
8225 Any files listed after the FILES keyword will be installed explicitly
8227 from the names given. Full paths are allowed in this form.
8228 The directory <dir> is relative to the installation prefix, which is
8230 stored in the variable CMAKE_INSTALL_PREFIX.
8231 install_programs
8233 Deprecated since version 3.0: Use the install(PROGRAMS) command
8234 instead.
8235 This command has been superceded by the install() command. It is pro‐
8238 vided for compatibility with older CMake code. The FILES form is
8239 directly replaced by the PROGRAMS form of the install() command. The
8240 regexp form can be expressed more clearly using the GLOB form of the
8241 file() command.
8242 install_programs(<dir> file1 file2 [file3 ...])
8244 install_programs(<dir> FILES file1 [file2 ...])
8245 Create rules to install the listed programs into the given directory.
8247 Use the FILES argument to guarantee that the file list version of the
8248 command will be used even when there is only one argument.
8249 install_programs(<dir> regexp)
8251 In the second form any program in the current source directory that
8253 matches the regular expression will be installed.
8254 This command is intended to install programs that are not built by
8256 cmake, such as shell scripts. See the TARGETS form of the install()
8257 command to create installation rules for targets built by cmake.
8258 The directory <dir> is relative to the installation prefix, which is
8260 stored in the variable CMAKE_INSTALL_PREFIX.
8261 install_targets
8263 Deprecated since version 3.0: Use the install(TARGETS) command instead.
8264 This command has been superceded by the install() command. It is pro‐
8267 vided for compatibility with older CMake code.
8268 install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
8270 Create rules to install the listed targets into the given directory.
8272 The directory <dir> is relative to the installation prefix, which is
8273 stored in the variable CMAKE_INSTALL_PREFIX. If RUNTIME_DIRECTORY is
8274 specified, then on systems with special runtime files (Windows DLL),
8275 the files will be copied to that directory.
8276 load_command
8278 Disallowed since version 3.0. See CMake Policy CMP0031.
8279 Load a command into a running CMake.
8281 load_command(COMMAND_NAME <loc1> [loc2 ...])
8283 The given locations are searched for a library whose name is cmCOM‐
8285 MAND_NAME. If found, it is loaded as a module and the command is added
8286 to the set of available CMake commands. Usually, try_compile() is used
8287 before this command to compile the module. If the command is success‐
8288 fully loaded a variable named
8289 CMAKE_LOADED_COMMAND_<COMMAND_NAME>
8291 will be set to the full path of the module that was loaded. Otherwise
8293 the variable will not be set.
8294 make_directory
8296 Deprecated since version 3.0: Use the file(MAKE_DIRECTORY) command
8297 instead.
8298 make_directory(directory)
8301 Creates the specified directory. Full paths should be given. Any par‐
8303 ent directories that do not exist will also be created. Use with care.
8304 output_required_files
8306 Disallowed since version 3.0. See CMake Policy CMP0032.
8307 Approximate C preprocessor dependency scanning.
8309 This command exists only because ancient CMake versions provided it.
8311 CMake handles preprocessor dependency scanning automatically using a
8312 more advanced scanner.
8313 output_required_files(srcfile outputfile)
8315 Outputs a list of all the source files that are required by the speci‐
8317 fied srcfile. This list is written into outputfile. This is similar
8318 to writing out the dependencies for srcfile except that it jumps from
8319 .h files into .cxx, .c and .cpp files if possible.
8320 qt_wrap_cpp
8322 Deprecated since version 3.14: This command was originally added to
8323 support Qt 3 before the add_custom_command() command was sufficiently
8324 mature. The FindQt4 module provides the qt4_wrap_cpp() macro, which
8325 should be used instead for Qt 4 projects. For projects using Qt 5 or
8326 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
8327 vides qt5_wrap_cpp()).
8328 Manually create Qt Wrappers.
8331 qt_wrap_cpp(resultingLibraryName DestName SourceLists ...)
8333 Produces moc files for all the .h files listed in the SourceLists. The
8335 moc files will be added to the library using the DestName source list.
8336 Consider updating the project to use the AUTOMOC target property
8338 instead for a more automated way of invoking the moc tool.
8339 qt_wrap_ui
8341 Deprecated since version 3.14: This command was originally added to
8342 support Qt 3 before the add_custom_command() command was sufficiently
8343 mature. The FindQt4 module provides the qt4_wrap_ui() macro, which
8344 should be used instead for Qt 4 projects. For projects using Qt 5 or
8345 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
8346 vides qt5_wrap_ui()).
8347 Manually create Qt user interfaces Wrappers.
8350 qt_wrap_ui(resultingLibraryName HeadersDestName
8352 SourcesDestName SourceLists ...)
8353 Produces .h and .cxx files for all the .ui files listed in the
8355 SourceLists. The .h files will be added to the library using the Head‐
8356 ersDestNamesource list. The .cxx files will be added to the library
8357 using the SourcesDestNamesource list.
8358 Consider updating the project to use the AUTOUIC target property
8360 instead for a more automated way of invoking the uic tool.
8361 remove
8363 Deprecated since version 3.0: Use the list(REMOVE_ITEM) command
8364 instead.
8365 remove(VAR VALUE VALUE ...)
8368 Removes VALUE from the variable VAR. This is typically used to remove
8370 entries from a vector (e.g. semicolon separated list). VALUE is
8371 expanded.
8372 subdir_depends
8374 Disallowed since version 3.0. See CMake Policy CMP0029.
8375 Does nothing.
8377 subdir_depends(subdir dep1 dep2 ...)
8379 Does not do anything. This command used to help projects order paral‐
8381 lel builds correctly. This functionality is now automatic.
8382 subdirs
8384 Deprecated since version 3.0: Use the add_subdirectory() command
8385 instead.
8386 Add a list of subdirectories to the build.
8389 subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
8391 [PREORDER] )
8392 Add a list of subdirectories to the build. The add_subdirectory() com‐
8394 mand should be used instead of subdirs although subdirs will still
8395 work. This will cause any CMakeLists.txt files in the sub directories
8396 to be processed by CMake. Any directories after the PREORDER flag are
8397 traversed first by makefile builds, the PREORDER flag has no effect on
8398 IDE projects. Any directories after the EXCLUDE_FROM_ALL marker will
8399 not be included in the top level makefile or project file. This is
8400 useful for having CMake create makefiles or projects for a set of exam‐
8401 ples in a project. You would want CMake to generate makefiles or
8402 project files for all the examples at the same time, but you would not
8403 want them to show up in the top level project or be built each time
8404 make is run from the top.
8405 use_mangled_mesa
8407 Disallowed since version 3.0. See CMake Policy CMP0030.
8408 Copy mesa headers for use in combination with system GL.
8410 use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
8412 The path to mesa includes, should contain gl_mangle.h. The mesa head‐
8414 ers are copied to the specified output directory. This allows mangled
8415 mesa headers to override other GL headers by being added to the include
8416 directory path earlier.
8417 utility_source
8419 Disallowed since version 3.0. See CMake Policy CMP0034.
8420 Specify the source tree of a third-party utility.
8422 utility_source(cache_entry executable_name
8424 path_to_source [file1 file2 ...])
8425 When a third-party utility’s source is included in the distribution,
8427 this command specifies its location and name. The cache entry will not
8428 be set unless the path_to_source and all listed files exist. It is
8429 assumed that the source tree of the utility will have been built before
8430 it is needed.
8431 When cross compiling CMake will print a warning if a utility_source()
8433 command is executed, because in many cases it is used to build an exe‐
8434 cutable which is executed later on. This doesn’t work when cross com‐
8435 piling, since the executable can run only on their target platform. So
8436 in this case the cache entry has to be adjusted manually so it points
8437 to an executable which is runnable on the build host.
8438 variable_requires
8440 Disallowed since version 3.0. See CMake Policy CMP0035.
8441 Use the if() command instead.
8443 Assert satisfaction of an option’s required variables.
8445 variable_requires(TEST_VARIABLE RESULT_VARIABLE
8447 REQUIRED_VARIABLE1
8448 REQUIRED_VARIABLE2 ...)
8449 The first argument (TEST_VARIABLE) is the name of the variable to be
8451 tested, if that variable is false nothing else is done. If TEST_VARI‐
8452 ABLE is true, then the next argument (RESULT_VARIABLE) is a variable
8453 that is set to true if all the required variables are set. The rest of
8454 the arguments are variables that must be true or not set to NOTFOUND to
8455 avoid an error. If any are not true, an error is reported.
8456 write_file
8458 Deprecated since version 3.0: Use the file(WRITE) command instead.
8459 write_file(filename "message to write"... [APPEND])
8462 The first argument is the file name, the rest of the arguments are mes‐
8464 sages to write. If the argument APPEND is specified, then the message
8465 will be appended.
8466 NOTE 1: file(WRITE) and file(APPEND) do exactly the same as this one
8468 but add some more functionality.
8469 NOTE 2: When using write_file the produced file cannot be used as an
8471 input to CMake (CONFIGURE_FILE, source file …) because it will lead to
8472 an infinite loop. Use configure_file() if you want to generate input
8473 files to CMake.
8474
8476 2000-2019 Kitware, Inc. and Contributors
84773.16.1 Dec 14, 2019 CMAKE-COMMANDS(7)