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 NEW 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 foreach(<loop_var>... IN ZIP_LISTS <lists>)
2691 In this variant, <lists> is a whitespace or semicolon separated list of
2693 list-valued variables. The foreach command iterates over each list
2694 simultaneously setting the iteration variables as follows:
2695 · if the only loop_var given, then it sets a series of loop_var_N vari‐
2697 ables to the current item from the corresponding list;
2698 · if multiple variable names passed, their count should match the lists
2700 variables count;
2701 · if any of the lists are shorter, the corresponding iteration variable
2703 is not defined for the current iteration.
2704 list(APPEND English one two three four)
2706 list(APPEND Bahasa satu dua tiga)
2707 foreach(num IN ZIP_LISTS English Bahasa)
2709 message(STATUS "num_0=${num_0}, num_1=${num_1}")
2710 endforeach()
2711 foreach(en ba IN ZIP_LISTS English Bahasa)
2713 message(STATUS "en=${en}, ba=${ba}")
2714 endforeach()
2715 yields
2717 -- num_0=one, num_1=satu
2719 -- num_0=two, num_1=dua
2720 -- num_0=three, num_1=tiga
2721 -- num_0=four, num_1=
2722 -- en=one, ba=satu
2723 -- en=two, ba=dua
2724 -- en=three, ba=tiga
2725 -- en=four, ba=
2726 function
2728 Start recording a function for later invocation as a command.
2729 function(<name> [<arg1> ...])
2731 <commands>
2732 endfunction()
2733 Defines a function named <name> that takes arguments named <arg1>, …
2735 The <commands> in the function definition are recorded; they are not
2736 executed until the function is invoked.
2737 Per legacy, the endfunction() command admits an optional <name> argu‐
2739 ment. If used, it must be a verbatim repeat of the argument of the
2740 opening function command.
2741 A function opens a new scope: see set(var PARENT_SCOPE) for details.
2743 See the cmake_policy() command documentation for the behavior of poli‐
2745 cies inside functions.
2746 See the macro() command documentation for differences between CMake
2748 functions and macros.
2749 Invocation
2751 The function invocation is case-insensitive. A function defined as
2752 function(foo)
2754 <commands>
2755 endfunction()
2756 can be invoked through any of
2758 foo()
2760 Foo()
2761 FOO()
2762 and so on. However, it is strongly recommended to stay with the case
2764 chosen in the function definition. Typically functions use all-lower‐
2765 case names.
2766 Arguments
2768 When the function is invoked, the recorded <commands> are first modi‐
2769 fied by replacing formal parameters (${arg1}, …) with the arguments
2770 passed, and then invoked as normal commands.
2771 In addition to referencing the formal parameters you can reference the
2773 ARGC variable which will be set to the number of arguments passed into
2774 the function as well as ARGV0, ARGV1, ARGV2, … which will have the
2775 actual values of the arguments passed in. This facilitates creating
2776 functions with optional arguments.
2777 Furthermore, ARGV holds the list of all arguments given to the function
2779 and ARGN holds the list of arguments past the last expected argument.
2780 Referencing to ARGV# arguments beyond ARGC have undefined behavior.
2781 Checking that ARGC is greater than # is the only way to ensure that
2782 ARGV# was passed to the function as an extra argument.
2783 get_cmake_property
2785 Get a global property of the CMake instance.
2786 get_cmake_property(<var> <property>)
2788 Gets a global property from the CMake instance. The value of the
2790 <property> is stored in the variable <var>. If the property is not
2791 found, <var> will be set to NOTFOUND. See the cmake-properties(7) man‐
2792 ual for available properties.
2793 See also the get_property() command GLOBAL option.
2795 In addition to global properties, this command (for historical reasons)
2797 also supports the VARIABLES and MACROS directory properties. It also
2798 supports a special COMPONENTS global property that lists the components
2799 given to the install() command.
2800 get_directory_property
2802 Get a property of DIRECTORY scope.
2803 get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
2805 Stores a property of directory scope in the named <variable>. The
2807 DIRECTORY argument specifies another directory from which to retrieve
2808 the property value instead of the current directory. The specified
2809 directory must have already been traversed by CMake.
2810 If the property is not defined for the nominated directory scope, an
2812 empty string is returned. In the case of INHERITED properties, if the
2813 property is not found for the nominated directory scope, the search
2814 will chain to a parent scope as described for the define_property()
2815 command.
2816 get_directory_property(<variable> [DIRECTORY <dir>]
2818 DEFINITION <var-name>)
2819 Get a variable definition from a directory. This form is useful to get
2821 a variable definition from another directory.
2822 See also the more general get_property() command.
2824 get_filename_component
2826 Get a specific component of a full filename.
2827 get_filename_component(<var> <FileName> <mode> [CACHE])
2829 Sets <var> to a component of <FileName>, where <mode> is one of:
2831 DIRECTORY = Directory without file name
2833 NAME = File name without directory
2834 EXT = File name longest extension (.b.c from d/a.b.c)
2835 NAME_WE = File name without directory or longest extension
2836 LAST_EXT = File name last extension (.c from d/a.b.c)
2837 NAME_WLE = File name without directory or last extension
2838 PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
2839 Paths are returned with forward slashes and have no trailing slashes.
2841 If the optional CACHE argument is specified, the result variable is
2842 added to the cache.
2843 get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
2845 Sets <var> to the absolute path of <FileName>, where <mode> is one of:
2847 ABSOLUTE = Full path to file
2849 REALPATH = Full path to existing file with symlinks resolved
2850 If the provided <FileName> is a relative path, it is evaluated relative
2852 to the given base directory <dir>. If no base directory is provided,
2853 the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
2854 Paths are returned with forward slashes and have no trailing slashes.
2856 If the optional CACHE argument is specified, the result variable is
2857 added to the cache.
2858 get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
2860 The program in <FileName> will be found in the system search path or
2862 left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
2863 command-line arguments present in the <FileName> string are split from
2864 the program name and stored in <arg_var>. This is used to separate a
2865 program name from its arguments in a command line string.
2866 get_property
2868 Get a property.
2869 get_property(<variable>
2871 <GLOBAL |
2872 DIRECTORY [<dir>] |
2873 TARGET <target> |
2874 SOURCE <source> |
2875 INSTALL <file> |
2876 TEST <test> |
2877 CACHE <entry> |
2878 VARIABLE >
2879 PROPERTY <name>
2880 [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
2881 Gets one property from one object in a scope.
2883 The first argument specifies the variable in which to store the result.
2885 The second argument determines the scope from which to get the prop‐
2886 erty. It must be one of the following:
2887 GLOBAL Scope is unique and does not accept a name.
2889 DIRECTORY
2891 Scope defaults to the current directory but another directory
2892 (already processed by CMake) may be named by the full or rela‐
2893 tive path <dir>.
2894 TARGET Scope must name one existing target.
2896 SOURCE Scope must name one source file.
2898 INSTALL
2900 Scope must name one installed file path.
2901 TEST Scope must name one existing test.
2903 CACHE Scope must name one cache entry.
2905 VARIABLE
2907 Scope is unique and does not accept a name.
2908 The required PROPERTY option is immediately followed by the name of the
2910 property to get. If the property is not set an empty value is
2911 returned, although some properties support inheriting from a parent
2912 scope if defined to behave that way (see define_property()).
2913 If the SET option is given the variable is set to a boolean value indi‐
2915 cating whether the property has been set. If the DEFINED option is
2916 given the variable is set to a boolean value indicating whether the
2917 property has been defined such as with the define_property() command.
2918 If BRIEF_DOCS or FULL_DOCS is given then the variable is set to a
2920 string containing documentation for the requested property. If docu‐
2921 mentation is requested for a property that has not been defined NOT‐
2922 FOUND is returned.
2923 if
2925 Conditionally execute a group of commands.
2926 Synopsis
2928 if(<condition>)
2929 <commands>
2930 elseif(<condition>) # optional block, can be repeated
2931 <commands>
2932 else() # optional block
2933 <commands>
2934 endif()
2935 Evaluates the condition argument of the if clause according to the
2937 Condition syntax described below. If the result is true, then the com‐
2938 mands in the if block are executed. Otherwise, optional elseif blocks
2939 are processed in the same way. Finally, if no condition is true, com‐
2940 mands in the optional else block are executed.
2941 Per legacy, the else() and endif() commands admit an optional <condi‐
2943 tion> argument. If used, it must be a verbatim repeat of the argument
2944 of the opening if command.
2945 Condition Syntax
2947 The following syntax applies to the condition argument of the if,
2948 elseif and while() clauses.
2949 Compound conditions are evaluated in the following order of precedence:
2951 Innermost parentheses are evaluated first. Next come unary tests such
2952 as EXISTS, COMMAND, and DEFINED. Then binary tests such as EQUAL,
2953 LESS, LESS_EQUAL, GREATER, GREATER_EQUAL, STREQUAL, STRLESS, STR‐
2954 LESS_EQUAL, STRGREATER, STRGREATER_EQUAL, VERSION_EQUAL, VERSION_LESS,
2955 VERSION_LESS_EQUAL, VERSION_GREATER, VERSION_GREATER_EQUAL, and
2956 MATCHES. Then the boolean operators in the order NOT, AND, and
2957 finally OR.
2958 Possible conditions are:
2960 if(<constant>)
2962 True if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
2963 ber. False if the constant is 0, OFF, NO, FALSE, N, IGNORE,
2964 NOTFOUND, the empty string, or ends in the suffix -NOTFOUND.
2965 Named boolean constants are case-insensitive. If the argument
2966 is not one of these specific constants, it is treated as a vari‐
2967 able or string and the following signature is used.
2968 if(<variable|string>)
2970 True if given a variable that is defined to a value that is not
2971 a false constant. False otherwise. (Note macro arguments are
2972 not variables.)
2973 if(NOT <condition>)
2975 True if the condition is not true.
2976 if(<cond1> AND <cond2>)
2978 True if both conditions would be considered true individually.
2979 if(<cond1> OR <cond2>)
2981 True if either condition would be considered true individually.
2982 if(COMMAND command-name)
2984 True if the given name is a command, macro or function that can
2985 be invoked.
2986 if(POLICY policy-id)
2988 True if the given name is an existing policy (of the form
2989 CMP<NNNN>).
2990 if(TARGET target-name)
2992 True if the given name is an existing logical target name cre‐
2993 ated by a call to the add_executable(), add_library(), or
2994 add_custom_target() command that has already been invoked (in
2995 any directory).
2996 if(TEST test-name)
2998 True if the given name is an existing test name created by the
2999 add_test() command.
3000 if(EXISTS path-to-file-or-directory)
3002 True if the named file or directory exists. Behavior is
3003 well-defined only for full paths. Resolves symbolic links, i.e.
3004 if the named file or directory is a symbolic link, returns true
3005 if the target of the symbolic link exists.
3006 if(file1 IS_NEWER_THAN file2)
3008 True if file1 is newer than file2 or if one of the two files
3009 doesn’t exist. Behavior is well-defined only for full paths.
3010 If the file time stamps are exactly the same, an IS_NEWER_THAN
3011 comparison returns true, so that any dependent build operations
3012 will occur in the event of a tie. This includes the case of
3013 passing the same file name for both file1 and file2.
3014 if(IS_DIRECTORY path-to-directory)
3016 True if the given name is a directory. Behavior is well-defined
3017 only for full paths.
3018 if(IS_SYMLINK file-name)
3020 True if the given name is a symbolic link. Behavior is
3021 well-defined only for full paths.
3022 if(IS_ABSOLUTE path)
3024 True if the given path is an absolute path.
3025 if(<variable|string> MATCHES regex)
3027 True if the given string or variable’s value matches the given
3028 regular condition. See Regex Specification for regex format.
3029 () groups are captured in CMAKE_MATCH_<n> variables.
3030 if(<variable|string> LESS <variable|string>)
3032 True if the given string or variable’s value is a valid number
3033 and less than that on the right.
3034 if(<variable|string> GREATER <variable|string>)
3036 True if the given string or variable’s value is a valid number
3037 and greater than that on the right.
3038 if(<variable|string> EQUAL <variable|string>)
3040 True if the given string or variable’s value is a valid number
3041 and equal to that on the right.
3042 if(<variable|string> LESS_EQUAL <variable|string>)
3044 True if the given string or variable’s value is a valid number
3045 and less than or equal to that on the right.
3046 if(<variable|string> GREATER_EQUAL <variable|string>)
3048 True if the given string or variable’s value is a valid number
3049 and greater than or equal to that on the right.
3050 if(<variable|string> STRLESS <variable|string>)
3052 True if the given string or variable’s value is lexicographi‐
3053 cally less than the string or variable on the right.
3054 if(<variable|string> STRGREATER <variable|string>)
3056 True if the given string or variable’s value is lexicographi‐
3057 cally greater than the string or variable on the right.
3058 if(<variable|string> STREQUAL <variable|string>)
3060 True if the given string or variable’s value is lexicographi‐
3061 cally equal to the string or variable on the right.
3062 if(<variable|string> STRLESS_EQUAL <variable|string>)
3064 True if the given string or variable’s value is lexicographi‐
3065 cally less than or equal to the string or variable on the right.
3066 if(<variable|string> STRGREATER_EQUAL <variable|string>)
3068 True if the given string or variable’s value is lexicographi‐
3069 cally greater than or equal to the string or variable on the
3070 right.
3071 if(<variable|string> VERSION_LESS <variable|string>)
3073 Component-wise integer version number comparison (version format
3074 is major[.minor[.patch[.tweak]]], omitted components are treated
3075 as zero). Any non-integer version component or non-integer
3076 trailing part of a version component effectively truncates the
3077 string at that point.
3078 if(<variable|string> VERSION_GREATER <variable|string>)
3080 Component-wise integer version number comparison (version format
3081 is major[.minor[.patch[.tweak]]], omitted components are treated
3082 as zero). Any non-integer version component or non-integer
3083 trailing part of a version component effectively truncates the
3084 string at that point.
3085 if(<variable|string> VERSION_EQUAL <variable|string>)
3087 Component-wise integer version number comparison (version format
3088 is major[.minor[.patch[.tweak]]], omitted components are treated
3089 as zero). Any non-integer version component or non-integer
3090 trailing part of a version component effectively truncates the
3091 string at that point.
3092 if(<variable|string> VERSION_LESS_EQUAL <variable|string>)
3094 Component-wise integer version number comparison (version format
3095 is major[.minor[.patch[.tweak]]], omitted components are treated
3096 as zero). Any non-integer version component or non-integer
3097 trailing part of a version component effectively truncates the
3098 string at that point.
3099 if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)
3101 Component-wise integer version number comparison (version format
3102 is major[.minor[.patch[.tweak]]], omitted components are treated
3103 as zero). Any non-integer version component or non-integer
3104 trailing part of a version component effectively truncates the
3105 string at that point.
3106 if(<variable|string> IN_LIST <variable>)
3108 True if the given element is contained in the named list vari‐
3109 able.
3110 if(DEFINED <name>|CACHE{<name>}|ENV{<name>})
3112 True if a variable, cache variable or environment variable with
3113 given <name> is defined. The value of the variable does not mat‐
3114 ter. Note that macro arguments are not variables.
3115 if((condition) AND (condition OR (condition)))
3117 The conditions inside the parenthesis are evaluated first and
3118 then the remaining condition is evaluated as in the previous
3119 examples. Where there are nested parenthesis the innermost are
3120 evaluated as part of evaluating the condition that contains
3121 them.
3122 Variable Expansion
3124 The if command was written very early in CMake’s history, predating the
3125 ${} variable evaluation syntax, and for convenience evaluates variables
3126 named by its arguments as shown in the above signatures. Note that
3127 normal variable evaluation with ${} applies before the if command even
3128 receives the arguments. Therefore code like
3129 set(var1 OFF)
3131 set(var2 "var1")
3132 if(${var2})
3133 appears to the if command as
3135 if(var1)
3137 and is evaluated according to the if(<variable>) case documented above.
3139 The result is OFF which is false. However, if we remove the ${} from
3140 the example then the command sees
3141 if(var2)
3143 which is true because var2 is defined to var1 which is not a false con‐
3145 stant.
3146 Automatic evaluation applies in the other cases whenever the above-doc‐
3148 umented condition syntax accepts <variable|string>:
3149 · The left hand argument to MATCHES is first checked to see if it is a
3151 defined variable, if so the variable’s value is used, otherwise the
3152 original value is used.
3153 · If the left hand argument to MATCHES is missing it returns false
3155 without error
3156 · Both left and right hand arguments to LESS, GREATER, EQUAL,
3158 LESS_EQUAL, and GREATER_EQUAL, are independently tested to see if
3159 they are defined variables, if so their defined values are used oth‐
3160 erwise the original value is used.
3161 · Both left and right hand arguments to STRLESS, STRGREATER, STREQUAL,
3163 STRLESS_EQUAL, and STRGREATER_EQUAL are independently tested to see
3164 if they are defined variables, if so their defined values are used
3165 otherwise the original value is used.
3166 · Both left and right hand arguments to VERSION_LESS, VERSION_GREATER,
3168 VERSION_EQUAL, VERSION_LESS_EQUAL, and VERSION_GREATER_EQUAL are
3169 independently tested to see if they are defined variables, if so
3170 their defined values are used otherwise the original value is used.
3171 · The right hand argument to NOT is tested to see if it is a boolean
3173 constant, if so the value is used, otherwise it is assumed to be a
3174 variable and it is dereferenced.
3175 · The left and right hand arguments to AND and OR are independently
3177 tested to see if they are boolean constants, if so they are used as
3178 such, otherwise they are assumed to be variables and are derefer‐
3179 enced.
3180 To prevent ambiguity, potential variable or keyword names can be speci‐
3182 fied in a Quoted Argument or a Bracket Argument. A quoted or bracketed
3183 variable or keyword will be interpreted as a string and not derefer‐
3184 enced or interpreted. See policy CMP0054.
3185 There is no automatic evaluation for environment or cache Variable Ref‐
3187 erences. Their values must be referenced as $ENV{<name>} or
3188 $CACHE{<name>} wherever the above-documented condition syntax accepts
3189 <variable|string>.
3190 include
3192 Load and run CMake code from a file or module.
3193 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
3195 [NO_POLICY_SCOPE])
3196 Loads and runs CMake code from the file given. Variable reads and
3198 writes access the scope of the caller (dynamic scoping). If OPTIONAL
3199 is present, then no error is raised if the file does not exist. If
3200 RESULT_VARIABLE is given the variable <var> will be set to the full
3201 filename which has been included or NOTFOUND if it failed.
3202 If a module is specified instead of a file, the file with name <module‐
3204 name>.cmake is searched first in CMAKE_MODULE_PATH, then in the CMake
3205 module directory. There is one exception to this: if the file which
3206 calls include() is located itself in the CMake builtin module direc‐
3207 tory, then first the CMake builtin module directory is searched and
3208 CMAKE_MODULE_PATH afterwards. See also policy CMP0017.
3209 See the cmake_policy() command documentation for discussion of the
3211 NO_POLICY_SCOPE option.
3212 include_guard
3214 Provides an include guard for the file currently being processed by
3215 CMake.
3216 include_guard([DIRECTORY|GLOBAL])
3218 Sets up an include guard for the current CMake file (see the CMAKE_CUR‐
3220 RENT_LIST_FILE variable documentation).
3221 CMake will end its processing of the current file at the location of
3223 the include_guard() command if the current file has already been pro‐
3224 cessed for the applicable scope (see below). This provides functional‐
3225 ity similar to the include guards commonly used in source headers or to
3226 the #pragma once directive. If the current file has been processed pre‐
3227 viously for the applicable scope, the effect is as though return() had
3228 been called. Do not call this command from inside a function being
3229 defined within the current file.
3230 An optional argument specifying the scope of the guard may be provided.
3232 Possible values for the option are:
3233 DIRECTORY
3235 The include guard applies within the current directory and
3236 below. The file will only be included once within this directory
3237 scope, but may be included again by other files outside of this
3238 directory (i.e. a parent directory or another directory not
3239 pulled in by add_subdirectory() or include() from the current
3240 file or its children).
3241 GLOBAL The include guard applies globally to the whole build. The cur‐
3243 rent file will only be included once regardless of the scope.
3244 If no arguments given, include_guard has the same scope as a variable,
3246 meaning that the include guard effect is isolated by the most recent
3247 function scope or current directory if no inner function scopes exist.
3248 In this case the command behavior is the same as:
3249 if(__CURRENT_FILE_VAR__)
3251 return()
3252 endif()
3253 set(__CURRENT_FILE_VAR__ TRUE)
3254 list
3256 List operations.
3257 Synopsis
3259 Reading
3260 list(LENGTH <list> <out-var>)
3261 list(GET <list> <element index> [<index> ...] <out-var>)
3262 list(JOIN <list> <glue> <out-var>)
3263 list(SUBLIST <list> <begin> <length> <out-var>)
3264 Search
3266 list(FIND <list> <value> <out-var>)
3267 Modification
3269 list(APPEND <list> [<element>...])
3270 list(FILTER <list> {INCLUDE | EXCLUDE} REGEX <regex>)
3271 list(INSERT <list> <index> [<element>...])
3272 list(POP_BACK <list> [<out-var>...])
3273 list(POP_FRONT <list> [<out-var>...])
3274 list(PREPEND <list> [<element>...])
3275 list(REMOVE_ITEM <list> <value>...)
3276 list(REMOVE_AT <list> <index>...)
3277 list(REMOVE_DUPLICATES <list>)
3278 list(TRANSFORM <list> <ACTION> [...])
3279 Ordering
3281 list(REVERSE <list>)
3282 list(SORT <list> [...])
3283 Introduction
3285 The list subcommands APPEND, INSERT, FILTER, PREPEND, POP_BACK,
3286 POP_FRONT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, REVERSE and SORT
3287 may create new values for the list within the current CMake variable
3288 scope. Similar to the set() command, the LIST command creates new
3289 variable values in the current scope, even if the list itself is actu‐
3290 ally defined in a parent scope. To propagate the results of these
3291 operations upwards, use set() with PARENT_SCOPE, set() with CACHE
3292 INTERNAL, or some other means of value propagation.
3293 NOTE:
3295 A list in cmake is a ; separated group of strings. To create a list
3296 the set command can be used. For example, set(var a b c d e) cre‐
3297 ates a list with a;b;c;d;e, and set(var "a b c d e") creates a
3298 string or a list with one item in it. (Note macro arguments are
3299 not variables, and therefore cannot be used in LIST commands.)
3300 NOTE:
3302 When specifying index values, if <element index> is 0 or greater, it
3303 is indexed from the beginning of the list, with 0 representing the
3304 first list element. If <element index> is -1 or lesser, it is
3305 indexed from the end of the list, with -1 representing the last list
3306 element. Be careful when counting with negative indices: they do
3307 not start from 0. -0 is equivalent to 0, the first list element.
3308 Reading
3310 list(LENGTH <list> <output variable>)
3311 Returns the list’s length.
3313 list(GET <list> <element index> [<element index> ...] <output variable>)
3315 Returns the list of elements specified by indices from the list.
3317 list(JOIN <list> <glue> <output variable>)
3319 Returns a string joining all list’s elements using the glue string. To
3321 join multiple strings, which are not part of a list, use JOIN operator
3322 from string() command.
3323 list(SUBLIST <list> <begin> <length> <output variable>)
3325 Returns a sublist of the given list. If <length> is 0, an empty list
3327 will be returned. If <length> is -1 or the list is smaller than
3328 <begin>+<length> then the remaining elements of the list starting at
3329 <begin> will be returned.
3330 Search
3332 list(FIND <list> <value> <output variable>)
3333 Returns the index of the element specified in the list or -1 if it
3335 wasn’t found.
3336 Modification
3338 list(APPEND <list> [<element> ...])
3339 Appends elements to the list.
3341 list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
3343 Includes or removes items from the list that match the mode’s pattern.
3345 In REGEX mode, items will be matched against the given regular expres‐
3346 sion.
3347 For more information on regular expressions see also the string() com‐
3349 mand.
3350 list(INSERT <list> <element_index> <element> [<element> ...])
3352 Inserts elements to the list to the specified location.
3354 list(POP_BACK <list> [<out-var>...])
3356 If no variable name is given, removes exactly one element. Otherwise,
3358 assign the last element’s value to the given variable and removes it,
3359 up to the last variable name given.
3360 list(POP_FRONT <list> [<out-var>...])
3362 If no variable name is given, removes exactly one element. Otherwise,
3364 assign the first element’s value to the given variable and removes it,
3365 up to the last variable name given.
3366 list(PREPEND <list> [<element> ...])
3368 Insert elements to the 0th position in the list.
3370 list(REMOVE_ITEM <list> <value> [<value> ...])
3372 Removes all instances of the given items from the list.
3374 list(REMOVE_AT <list> <index> [<index> ...])
3376 Removes items at given indices from the list.
3378 list(REMOVE_DUPLICATES <list>)
3380 Removes duplicated items in the list. The relative order of items is
3382 preserved, but if duplicates are encountered, only the first instance
3383 is preserved.
3384 list(TRANSFORM <list> <ACTION> [<SELECTOR>]
3386 [OUTPUT_VARIABLE <output variable>])
3387 Transforms the list by applying an action to all or, by specifying a
3389 <SELECTOR>, to the selected elements of the list, storing the result
3390 in-place or in the specified output variable.
3391 NOTE:
3393 The TRANSFORM sub-command does not change the number of elements in
3394 the list. If a <SELECTOR> is specified, only some elements will be
3395 changed, the other ones will remain the same as before the transfor‐
3396 mation.
3397 <ACTION> specifies the action to apply to the elements of the list.
3399 The actions have exactly the same semantics as sub-commands of the
3400 string() command. <ACTION> must be one of the following:
3401 APPEND, PREPEND: Append, prepend specified value to each element of the
3403 list.
3404 list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
3406 TOUPPER, TOLOWER: Convert each element of the list to upper, lower
3408 characters.
3409 list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
3411 STRIP: Remove leading and trailing spaces from each element of the
3413 list.
3414 list(TRANSFORM <list> STRIP ...)
3416 GENEX_STRIP: Strip any generator expressions from each element of the
3418 list.
3419 list(TRANSFORM <list> GENEX_STRIP ...)
3421 REPLACE: Match the regular expression as many times as possible and
3423 substitute the replacement expression for the match for each element of
3424 the list (Same semantic as REGEX REPLACE from string() command).
3425 list(TRANSFORM <list> REPLACE <regular_expression>
3427 <replace_expression> ...)
3428 <SELECTOR> determines which elements of the list will be transformed.
3430 Only one type of selector can be specified at a time. When given,
3431 <SELECTOR> must be one of the following:
3432 AT: Specify a list of indexes.
3434 list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
3436 FOR: Specify a range with, optionally, an increment used to iterate
3438 over the range.
3439 list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
3441 REGEX: Specify a regular expression. Only elements matching the regular
3443 expression will be transformed.
3444 list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
3446 Ordering
3448 list(REVERSE <list>)
3449 Reverses the contents of the list in-place.
3451 list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
3453 Sorts the list in-place alphabetically. Use the COMPARE keyword to
3455 select the comparison method for sorting. The <compare> option should
3456 be one of:
3457 · STRING: Sorts a list of strings alphabetically. This is the default
3459 behavior if the COMPARE option is not given.
3460 · FILE_BASENAME: Sorts a list of pathnames of files by their basenames.
3462 Use the CASE keyword to select a case sensitive or case insensitive
3464 sort mode. The <case> option should be one of:
3465 · SENSITIVE: List items are sorted in a case-sensitive manner. This is
3467 the default behavior if the CASE option is not given.
3468 · INSENSITIVE: List items are sorted case insensitively. The order of
3470 items which differ only by upper/lowercase is not specified.
3471 To control the sort order, the ORDER keyword can be given. The <order>
3473 option should be one of:
3474 · ASCENDING: Sorts the list in ascending order. This is the default
3476 behavior when the ORDER option is not given.
3477 · DESCENDING: Sorts the list in descending order.
3479 macro
3481 Start recording a macro for later invocation as a command
3482 macro(<name> [<arg1> ...])
3484 <commands>
3485 endmacro()
3486 Defines a macro named <name> that takes arguments named <arg1>, … Com‐
3488 mands listed after macro, but before the matching endmacro(), are not
3489 executed until the macro is invoked.
3490 Per legacy, the endmacro() command admits an optional <name> argument.
3492 If used, it must be a verbatim repeat of the argument of the opening
3493 macro command.
3494 See the cmake_policy() command documentation for the behavior of poli‐
3496 cies inside macros.
3497 See the Macro vs Function section below for differences between CMake
3499 macros and functions.
3500 Invocation
3502 The macro invocation is case-insensitive. A macro defined as
3503 macro(foo)
3505 <commands>
3506 endmacro()
3507 can be invoked through any of
3509 foo()
3511 Foo()
3512 FOO()
3513 and so on. However, it is strongly recommended to stay with the case
3515 chosen in the macro definition. Typically macros use all-lowercase
3516 names.
3517 Arguments
3519 When a macro is invoked, the commands recorded in the macro are first
3520 modified by replacing formal parameters (${arg1}, …) with the arguments
3521 passed, and then invoked as normal commands.
3522 In addition to referencing the formal parameters you can reference the
3524 values ${ARGC} which will be set to the number of arguments passed into
3525 the function as well as ${ARGV0}, ${ARGV1}, ${ARGV2}, … which will
3526 have the actual values of the arguments passed in. This facilitates
3527 creating macros with optional arguments.
3528 Furthermore, ${ARGV} holds the list of all arguments given to the macro
3530 and ${ARGN} holds the list of arguments past the last expected argu‐
3531 ment. Referencing to ${ARGV#} arguments beyond ${ARGC} have undefined
3532 behavior. Checking that ${ARGC} is greater than # is the only way to
3533 ensure that ${ARGV#} was passed to the function as an extra argument.
3534 Macro vs Function
3536 The macro command is very similar to the function() command. Nonethe‐
3537 less, there are a few important differences.
3538 In a function, ARGN, ARGC, ARGV and ARGV0, ARGV1, … are true variables
3540 in the usual CMake sense. In a macro, they are not, they are string
3541 replacements much like the C preprocessor would do with a macro. This
3542 has a number of consequences, as explained in the Argument Caveats sec‐
3543 tion below.
3544 Another difference between macros and functions is the control flow. A
3546 function is executed by transferring control from the calling statement
3547 to the function body. A macro is executed as if the macro body were
3548 pasted in place of the calling statement. This has the consequence
3549 that a return() in a macro body does not just terminate execution of
3550 the macro; rather, control is returned from the scope of the macro
3551 call. To avoid confusion, it is recommended to avoid return() in
3552 macros altogether.
3553 Unlike a function, the CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNC‐
3555 TION_LIST_DIR, CMAKE_CURRENT_FUNCTION_LIST_FILE, CMAKE_CURRENT_FUNC‐
3556 TION_LIST_LINE variables are not set for a macro.
3557 Argument Caveats
3559 Since ARGN, ARGC, ARGV, ARGV0 etc. are not variables, you will NOT be
3560 able to use commands like
3561 if(ARGV1) # ARGV1 is not a variable
3563 if(DEFINED ARGV2) # ARGV2 is not a variable
3564 if(ARGC GREATER 2) # ARGC is not a variable
3565 foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
3566 In the first case, you can use if(${ARGV1}). In the second and third
3568 case, the proper way to check if an optional variable was passed to the
3569 macro is to use if(${ARGC} GREATER 2). In the last case, you can use
3570 foreach(loop_var ${ARGN}) but this will skip empty arguments. If you
3571 need to include them, you can use
3572 set(list_var "${ARGN}")
3574 foreach(loop_var IN LISTS list_var)
3575 Note that if you have a variable with the same name in the scope from
3577 which the macro is called, using unreferenced names will use the exist‐
3578 ing variable instead of the arguments. For example:
3579 macro(bar)
3581 foreach(arg IN LISTS ARGN)
3582 <commands>
3583 endforeach()
3584 endmacro()
3585 function(foo)
3587 bar(x y z)
3588 endfunction()
3589 foo(a b c)
3591 Will loop over a;b;c and not over x;y;z as one might have expected. If
3593 you want true CMake variables and/or better CMake scope control you
3594 should look at the function command.
3595 mark_as_advanced
3597 Mark cmake cached variables as advanced.
3598 mark_as_advanced([CLEAR|FORCE] <var1> ...)
3600 Sets the advanced/non-advanced state of the named cached variables.
3602 An advanced variable will not be displayed in any of the cmake GUIs
3604 unless the show advanced option is on. In script mode, the
3605 advanced/non-advanced state has no effect.
3606 If the keyword CLEAR is given then advanced variables are changed back
3608 to unadvanced. If the keyword FORCE is given then the variables are
3609 made advanced. If neither FORCE nor CLEAR is specified, new values
3610 will be marked as advanced, but if a variable already has an
3611 advanced/non-advanced state, it will not be changed.
3612 NOTE:
3614 Policy CMP0102 affects the behavior of the mark_as_advanced call.
3615 When set to NEW, variables passed to this command which are not
3616 already in the cache are ignored. See policy CMP0102.
3617 math
3619 Evaluate a mathematical expression.
3620 math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])
3622 Evaluates a mathematical <expression> and sets <variable> to the
3624 resulting value. The result of the expression must be representable as
3625 a 64-bit signed integer.
3626 The mathematical expression must be given as a string (i.e. enclosed in
3628 double quotation marks). An example is "5 * (10 + 13)". Supported
3629 operators are +, -, *, /, %, |, &, ^, ~, <<, >>, and (...); they have
3630 the same meaning as in C code.
3631 Hexadecimal numbers are recognized when prefixed with 0x, as in C code.
3633 The result is formatted according to the option OUTPUT_FORMAT, where
3635 <format> is one of
3636 HEXADECIMAL
3638 Hexadecimal notation as in C code, i. e. starting with “0x”.
3639 DECIMAL
3641 Decimal notation. Which is also used if no OUTPUT_FORMAT option
3642 is specified.
3643 For example
3645 math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL) # value is set to "1000"
3647 math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL) # value is set to "0x3e8"
3648 message
3650 Log a message.
3651 Synopsis
3653 General messages
3654 message([<mode>] "message text" ...)
3655 Reporting checks
3657 message(<checkState> "message text" ...)
3658 General messages
3660 message([<mode>] "message text" ...)
3661 Record the specified message text in the log. If more than one message
3663 string is given, they are concatenated into a single message with no
3664 separator between the strings.
3665 The optional <mode> keyword determines the type of message, which
3667 influences the way the message is handled:
3668 FATAL_ERROR
3670 CMake Error, stop processing and generation.
3671 SEND_ERROR
3673 CMake Error, continue processing, but skip generation.
3674 WARNING
3676 CMake Warning, continue processing.
3677 AUTHOR_WARNING
3679 CMake Warning (dev), continue processing.
3680 DEPRECATION
3682 CMake Deprecation Error or Warning if variable CMAKE_ERROR_DEP‐
3683 RECATED or CMAKE_WARN_DEPRECATED is enabled, respectively, else
3684 no message.
3685 (none) or NOTICE
3687 Important message printed to stderr to attract user’s attention.
3688 STATUS The main interesting messages that project users might be inter‐
3690 ested in. Ideally these should be concise, no more than a sin‐
3691 gle line, but still informative.
3692 VERBOSE
3694 Detailed informational messages intended for project users.
3695 These messages should provide additional details that won’t be
3696 of interest in most cases, but which may be useful to those
3697 building the project when they want deeper insight into what’s
3698 happening.
3699 DEBUG Detailed informational messages intended for developers working
3701 on the project itself as opposed to users who just want to build
3702 it. These messages will not typically be of interest to other
3703 users building the project and will often be closely related to
3704 internal implementation details.
3705 TRACE Fine-grained messages with very low-level implementation
3707 details. Messages using this log level would normally only be
3708 temporary and would expect to be removed before releasing the
3709 project, packaging up the files, etc.
3710 The CMake command-line tool displays STATUS to TRACE messages on stdout
3712 with the message preceded by two hyphens and a space. All other mes‐
3713 sage types are sent to stderr and are not prefixed with hyphens. The
3714 CMake GUI displays all messages in its log area. The curses interface
3715 shows STATUS to TRACE messages one at a time on a status line and other
3716 messages in an interactive pop-up box. The --log-level command-line
3717 option to each of these tools can be used to control which messages
3718 will be shown. To make a log level persist between CMake runs, the
3719 CMAKE_MESSAGE_LOG_LEVEL variable can be set instead. Note that the
3720 command line option takes precedence over the cache variable.
3721 Messages of log levels NOTICE and below will have each line preceded by
3723 the content of the CMAKE_MESSAGE_INDENT variable (converted to a single
3724 string by concatenating its list items). For STATUS to TRACE messages,
3725 this indenting content will be inserted after the hyphens.
3726 Messages of log levels NOTICE and below can also have each line pre‐
3728 ceded with context of the form [some.context.example]. The content
3729 between the square brackets is obtained by converting the CMAKE_MES‐
3730 SAGE_CONTEXT list variable to a dot-separated string. The message con‐
3731 text will always appear before any indenting content but after any
3732 automatically added leading hyphens. By default, message context is not
3733 shown, it has to be explicitly enabled by giving the cmake --log-con‐
3734 text command-line option or by setting the CMAKE_MESSAGE_CONTEXT_SHOW
3735 variable to true. See the CMAKE_MESSAGE_CONTEXT documentation for
3736 usage examples.
3737 CMake Warning and Error message text displays using a simple markup
3739 language. Non-indented text is formatted in line-wrapped paragraphs
3740 delimited by newlines. Indented text is considered pre-formatted.
3741 Reporting checks
3743 A common pattern in CMake output is a message indicating the start of
3744 some sort of check, followed by another message reporting the result of
3745 that check. For example:
3746 message(STATUS "Looking for someheader.h")
3748 #... do the checks, set checkSuccess with the result
3749 if(checkSuccess)
3750 message(STATUS "Looking for someheader.h - found")
3751 else()
3752 message(STATUS "Looking for someheader.h - not found")
3753 endif()
3754 This can be more robustly and conveniently expressed using the
3756 CHECK_... keyword form of the message() command:
3757 message(<checkState> "message" ...)
3759 where <checkState> must be one of the following:
3761 CHECK_START
3763 Record a concise message about the check about to be per‐
3764 formed.
3765 CHECK_PASS
3767 Record a successful result for a check.
3768 CHECK_FAIL
3770 Record an unsuccessful result for a check.
3771 When recording a check result, the command repeats the message from the
3773 most recently started check for which no result has yet been reported,
3774 then some separator characters and then the message text provided after
3775 the CHECK_PASS or CHECK_FAIL keyword. Check messages are always
3776 reported at STATUS log level.
3777 Checks may be nested and every CHECK_START should have exactly one
3779 matching CHECK_PASS or CHECK_FAIL. The CMAKE_MESSAGE_INDENT variable
3780 can also be used to add indenting to nested checks if desired. For
3781 example:
3782 message(CHECK_START "Finding my things")
3784 list(APPEND CMAKE_MESSAGE_INDENT " ")
3785 unset(missingComponents)
3786 message(CHECK_START "Finding partA")
3788 # ... do check, assume we find A
3789 message(CHECK_PASS "found")
3790 message(CHECK_START "Finding partB")
3792 # ... do check, assume we don't find B
3793 list(APPEND missingComponents B)
3794 message(CHECK_FAIL "not found")
3795 list(POP_BACK CMAKE_MESSAGE_INDENT)
3797 if(missingComponents)
3798 message(CHECK_FAIL "missing components: ${missingComponents}")
3799 else()
3800 message(CHECK_PASS "all components found")
3801 endif()
3802 Output from the above would appear something like the following:
3804 -- Finding my things
3806 -- Finding partA
3807 -- Finding partA - found
3808 -- Finding partB
3809 -- Finding partB - not found
3810 -- Finding my things - missing components: B
3811 option
3813 Provide an option that the user can optionally select.
3814 option(<variable> "<help_text>" [value])
3816 Provides an option for the user to select as ON or OFF. If no initial
3818 <value> is provided, OFF is used. If <variable> is already set as a
3819 normal variable then the command does nothing (see policy CMP0077).
3820 If you have options that depend on the values of other options, see the
3822 module help for CMakeDependentOption.
3823 return
3825 Return from a file, directory or function.
3826 return()
3828 Returns from a file, directory or function. When this command is
3830 encountered in an included file (via include() or find_package()), it
3831 causes processing of the current file to stop and control is returned
3832 to the including file. If it is encountered in a file which is not
3833 included by another file, e.g. a CMakeLists.txt, control is returned
3834 to the parent directory if there is one. If return is called in a
3835 function, control is returned to the caller of the function.
3836 Note that a macro, unlike a function, is expanded in place and there‐
3838 fore cannot handle return().
3839 separate_arguments
3841 Parse command-line arguments into a semicolon-separated list.
3842 separate_arguments(<variable> <mode> <args>)
3844 Parses a space-separated string <args> into a list of items, and stores
3846 this list in semicolon-separated standard form in <variable>.
3847 This function is intended for parsing command-line arguments. The
3849 entire command line must be passed as one string in the argument
3850 <args>.
3851 The exact parsing rules depend on the operating system. They are spec‐
3853 ified by the <mode> argument which must be one of the following key‐
3854 words:
3855 UNIX_COMMAND
3857 Arguments are separated by by unquoted whitespace. Both sin‐
3858 gle-quote and double-quote pairs are respected. A backslash
3859 escapes the next literal character (\" is "); there are no spe‐
3860 cial escapes (\n is just n).
3861 WINDOWS_COMMAND
3863 A Windows command-line is parsed using the same syntax the run‐
3864 time library uses to construct argv at startup. It separates
3865 arguments by whitespace that is not double-quoted. Backslashes
3866 are literal unless they precede double-quotes. See the MSDN
3867 article Parsing C Command-Line Arguments for details.
3868 NATIVE_COMMAND
3870 Proceeds as in WINDOWS_COMMAND mode if the host system is Win‐
3871 dows. Otherwise proceeds as in UNIX_COMMAND mode.
3872 separate_arguments(<var>)
3874 Convert the value of <var> to a semi-colon separated list. All spaces
3876 are replaced with ‘;’. This helps with generating command lines.
3877 set
3879 Set a normal, cache, or environment variable to a given value. See the
3880 cmake-language(7) variables documentation for the scopes and interac‐
3881 tion of normal variables and cache entries.
3882 Signatures of this command that specify a <value>... placeholder expect
3884 zero or more arguments. Multiple arguments will be joined as a semi‐
3885 colon-separated list to form the actual variable value to be set. Zero
3886 arguments will cause normal variables to be unset. See the unset()
3887 command to unset variables explicitly.
3888 Set Normal Variable
3890 set(<variable> <value>... [PARENT_SCOPE])
3891 Sets the given <variable> in the current function or directory scope.
3893 If the PARENT_SCOPE option is given the variable will be set in the
3895 scope above the current scope. Each new directory or function creates
3896 a new scope. This command will set the value of a variable into the
3897 parent directory or calling function (whichever is applicable to the
3898 case at hand). The previous state of the variable’s value stays the
3899 same in the current scope (e.g., if it was undefined before, it is
3900 still undefined and if it had a value, it is still that value).
3901 Set Cache Entry
3903 set(<variable> <value>... CACHE <type> <docstring> [FORCE])
3904 Sets the given cache <variable> (cache entry). Since cache entries are
3906 meant to provide user-settable values this does not overwrite existing
3907 cache entries by default. Use the FORCE option to overwrite existing
3908 entries.
3909 The <type> must be specified as one of:
3911 BOOL Boolean ON/OFF value. cmake-gui(1) offers a checkbox.
3913 FILEPATH
3915 Path to a file on disk. cmake-gui(1) offers a file dialog.
3916 PATH Path to a directory on disk. cmake-gui(1) offers a file dialog.
3918 STRING A line of text. cmake-gui(1) offers a text field or a drop-down
3920 selection if the STRINGS cache entry property is set.
3921 INTERNAL
3923 A line of text. cmake-gui(1) does not show internal entries.
3924 They may be used to store variables persistently across runs.
3925 Use of this type implies FORCE.
3926 The <docstring> must be specified as a line of text providing a quick
3928 summary of the option for presentation to cmake-gui(1) users.
3929 If the cache entry does not exist prior to the call or the FORCE option
3931 is given then the cache entry will be set to the given value. Further‐
3932 more, any normal variable binding in the current scope will be removed
3933 to expose the newly cached value to any immediately following evalua‐
3934 tion.
3935 It is possible for the cache entry to exist prior to the call but have
3937 no type set if it was created on the cmake(1) command line by a user
3938 through the -D<var>=<value> option without specifying a type. In this
3939 case the set command will add the type. Furthermore, if the <type> is
3940 PATH or FILEPATH and the <value> provided on the command line is a rel‐
3941 ative path, then the set command will treat the path as relative to the
3942 current working directory and convert it to an absolute path.
3943 Set Environment Variable
3945 set(ENV{<variable>} [<value>])
3946 Sets an Environment Variable to the given value. Subsequent calls of
3948 $ENV{<variable>} will return this new value.
3949 This command affects only the current CMake process, not the process
3951 from which CMake was called, nor the system environment at large, nor
3952 the environment of subsequent build or test processes.
3953 If no argument is given after ENV{<variable>} or if <value> is an empty
3955 string, then this command will clear any existing value of the environ‐
3956 ment variable.
3957 Arguments after <value> are ignored. If extra arguments are found, then
3959 an author warning is issued.
3960 set_directory_properties
3962 Set properties of the current directory and subdirectories.
3963 set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...)
3965 Sets properties of the current directory and its subdirectories in
3967 key-value pairs.
3968 See also the set_property(DIRECTORY) command.
3970 See Directory Properties for the list of properties known to CMake and
3972 their individual documentation for the behavior of each property.
3973 set_property
3975 Set a named property in a given scope.
3976 set_property(<GLOBAL |
3978 DIRECTORY [<dir>] |
3979 TARGET [<target1> ...] |
3980 SOURCE [<src1> ...] |
3981 INSTALL [<file1> ...] |
3982 TEST [<test1> ...] |
3983 CACHE [<entry1> ...] >
3984 [APPEND] [APPEND_STRING]
3985 PROPERTY <name> [value1 ...])
3986 Sets one property on zero or more objects of a scope.
3988 The first argument determines the scope in which the property is set.
3990 It must be one of the following:
3991 GLOBAL Scope is unique and does not accept a name.
3993 DIRECTORY
3995 Scope defaults to the current directory but another directory
3996 (already processed by CMake) may be named by full or relative
3997 path. See also the set_directory_properties() command.
3998 TARGET Scope may name zero or more existing targets. See also the
4000 set_target_properties() command.
4001 SOURCE Scope may name zero or more source files. Note that source file
4003 properties are visible only to targets added in the same direc‐
4004 tory (CMakeLists.txt). See also the set_source_files_proper‐
4005 ties() command.
4006 INSTALL
4008 Scope may name zero or more installed file paths. These are
4009 made available to CPack to influence deployment.
4010 Both the property key and value may use generator expressions.
4012 Specific properties may apply to installed files and/or directo‐
4013 ries.
4014 Path components have to be separated by forward slashes, must be
4016 normalized and are case sensitive.
4017 To reference the installation prefix itself with a relative path
4019 use ..
4020 Currently installed file properties are only defined for the WIX
4022 generator where the given paths are relative to the installation
4023 prefix.
4024 TEST Scope may name zero or more existing tests. See also the
4026 set_tests_properties() command.
4027 CACHE Scope must name zero or more cache existing entries.
4029 The required PROPERTY option is immediately followed by the name of the
4031 property to set. Remaining arguments are used to compose the property
4032 value in the form of a semicolon-separated list.
4033 If the APPEND option is given the list is appended to any existing
4035 property value. If the APPEND_STRING option is given the string is
4036 appended to any existing property value as string, i.e. it results in a
4037 longer string and not a list of strings. When using APPEND or
4038 APPEND_STRING with a property defined to support INHERITED behavior
4039 (see define_property()), no inheriting occurs when finding the initial
4040 value to append to. If the property is not already directly set in the
4041 nominated scope, the command will behave as though APPEND or
4042 APPEND_STRING had not been given.
4043 See the cmake-properties(7) manual for a list of properties in each
4045 scope.
4046 site_name
4048 Set the given variable to the name of the computer.
4049 site_name(variable)
4051 string
4053 String operations.
4054 Synopsis
4056 Search and Replace
4057 string(FIND <string> <substring> <out-var> [...])
4058 string(REPLACE <match-string> <replace-string> <out-var> <input>...)
4059 Regular Expressions
4061 string(REGEX MATCH <match-regex> <out-var> <input>...)
4062 string(REGEX MATCHALL <match-regex> <out-var> <input>...)
4063 string(REGEX REPLACE <match-regex> <replace-expr> <out-var> <input>...)
4064 Manipulation
4066 string(APPEND <string-var> [<input>...])
4067 string(PREPEND <string-var> [<input>...])
4068 string(CONCAT <out-var> [<input>...])
4069 string(JOIN <glue> <out-var> [<input>...])
4070 string(TOLOWER <string> <out-var>)
4071 string(TOUPPER <string> <out-var>)
4072 string(LENGTH <string> <out-var>)
4073 string(SUBSTRING <string> <begin> <length> <out-var>)
4074 string(STRIP <string> <out-var>)
4075 string(GENEX_STRIP <string> <out-var>)
4076 string(REPEAT <string> <count> <out-var>)
4077 Comparison
4079 string(COMPARE <op> <string1> <string2> <out-var>)
4080 Hashing
4082 string(<HASH> <out-var> <input>)
4083 Generation
4085 string(ASCII <number>... <out-var>)
4086 string(CONFIGURE <string> <out-var> [...])
4087 string(MAKE_C_IDENTIFIER <string> <out-var>)
4088 string(RANDOM [<option>...] <out-var>)
4089 string(TIMESTAMP <out-var> [<format string>] [UTC])
4090 string(UUID <out-var> ...)
4091 Search and Replace
4093 string(FIND <string> <substring> <output_variable> [REVERSE])
4094 Return the position where the given <substring> was found in the sup‐
4096 plied <string>. If the REVERSE flag was used, the command will search
4097 for the position of the last occurrence of the specified <substring>.
4098 If the <substring> is not found, a position of -1 is returned.
4099 The string(FIND) subcommand treats all strings as ASCII-only charac‐
4101 ters. The index stored in <output_variable> will also be counted in
4102 bytes, so strings containing multi-byte characters may lead to unex‐
4103 pected results.
4104 string(REPLACE <match_string>
4106 <replace_string> <output_variable>
4107 <input> [<input>...])
4108 Replace all occurrences of <match_string> in the <input> with
4110 <replace_string> and store the result in the <output_variable>.
4111 Regular Expressions
4113 string(REGEX MATCH <regular_expression>
4114 <output_variable> <input> [<input>...])
4115 Match the <regular_expression> once and store the match in the <out‐
4117 put_variable>. All <input> arguments are concatenated before matching.
4118 string(REGEX MATCHALL <regular_expression>
4120 <output_variable> <input> [<input>...])
4121 Match the <regular_expression> as many times as possible and store the
4123 matches in the <output_variable> as a list. All <input> arguments are
4124 concatenated before matching.
4125 string(REGEX REPLACE <regular_expression>
4127 <replacement_expression> <output_variable>
4128 <input> [<input>...])
4129 Match the <regular_expression> as many times as possible and substitute
4131 the <replacement_expression> for the match in the output. All <input>
4132 arguments are concatenated before matching.
4133 The <replacement_expression> may refer to parenthesis-delimited subex‐
4135 pressions of the match using \1, \2, …, \9. Note that two backslashes
4136 (\\1) are required in CMake code to get a backslash through argument
4137 parsing.
4138 Regex Specification
4140 The following characters have special meaning in regular expressions:
4141 ^ Matches at beginning of input
4143 $ Matches at end of input
4145 . Matches any single character
4147 \<char>
4149 Matches the single character specified by <char>. Use this to
4150 match special regex characters, e.g. \. for a literal . or \\
4151 for a literal backslash \. Escaping a non-special character is
4152 unnecessary but allowed, e.g. \a matches a.
4153 [ ] Matches any character(s) inside the brackets
4155 [^ ] Matches any character(s) not inside the brackets
4157 - Inside brackets, specifies an inclusive range between characters
4159 on either side e.g. [a-f] is [abcdef] To match a literal - using
4160 brackets, make it the first or the last character e.g. [+*/-]
4161 matches basic mathematical operators.
4162 * Matches preceding pattern zero or more times
4164 + Matches preceding pattern one or more times
4166 ? Matches preceding pattern zero or once only
4168 | Matches a pattern on either side of the |
4170 () Saves a matched subexpression, which can be referenced in the
4172 REGEX REPLACE operation. Additionally it is saved by all regular
4173 expression-related commands, including e.g. if(MATCHES), in the
4174 variables CMAKE_MATCH_<n> for <n> 0..9.
4175 *, + and ? have higher precedence than concatenation. | has lower
4177 precedence than concatenation. This means that the regular expression
4178 ^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
4179 matches ab but not abd.
4180 CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
4182 to construct literal tabs, carriage returns, newlines, and backslashes
4183 (respectively) to pass in a regex. For example:
4184 · The quoted argument "[ \t\r\n]" specifies a regex that matches any
4186 single whitespace character.
4187 · The quoted argument "[/\\]" specifies a regex that matches a single
4189 forward slash / or backslash \.
4190 · The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
4192 single “word” character in the C locale.
4193 · The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
4195 the exact string (a+b). Each \\ is parsed in a quoted argument as
4196 just \, so the regex itself is actually \(\a\+\b\). This can alter‐
4197 natively be specified in a bracket argument without having to escape
4198 the backslashes, e.g. [[\(\a\+\b\)]].
4199 Manipulation
4201 string(APPEND <string_variable> [<input>...])
4202 Append all the <input> arguments to the string.
4204 string(PREPEND <string_variable> [<input>...])
4206 Prepend all the <input> arguments to the string.
4208 string(CONCAT <output_variable> [<input>...])
4210 Concatenate all the <input> arguments together and store the result in
4212 the named <output_variable>.
4213 string(JOIN <glue> <output_variable> [<input>...])
4215 Join all the <input> arguments together using the <glue> string and
4217 store the result in the named <output_variable>.
4218 To join a list’s elements, prefer to use the JOIN operator from the
4220 list() command. This allows for the elements to have special charac‐
4221 ters like ; in them.
4222 string(TOLOWER <string> <output_variable>)
4224 Convert <string> to lower characters.
4226 string(TOUPPER <string> <output_variable>)
4228 Convert <string> to upper characters.
4230 string(LENGTH <string> <output_variable>)
4232 Store in an <output_variable> a given string’s length in bytes. Note
4234 that this means if <string> contains multi-byte characters, the result
4235 stored in <output_variable> will not be the number of characters.
4236 string(SUBSTRING <string> <begin> <length> <output_variable>)
4238 Store in an <output_variable> a substring of a given <string>. If
4240 <length> is -1 the remainder of the string starting at <begin> will be
4241 returned. If <string> is shorter than <length> then the end of the
4242 string is used instead.
4243 Both <begin> and <length> are counted in bytes, so care must be exer‐
4245 cised if <string> could contain multi-byte characters.
4246 NOTE:
4248 CMake 3.1 and below reported an error if <length> pointed past the
4249 end of <string>.
4250 string(STRIP <string> <output_variable>)
4252 Store in an <output_variable> a substring of a given <string> with
4254 leading and trailing spaces removed.
4255 string(GENEX_STRIP <string> <output_variable>)
4257 Strip any generator expressions from the input <string> and store the
4259 result in the <output_variable>.
4260 string(REPEAT <string> <count> <output_variable>)
4262 Produce the output string as the input <string> repeated <count> times.
4264 Comparison
4266 string(COMPARE LESS <string1> <string2> <output_variable>)
4267 string(COMPARE GREATER <string1> <string2> <output_variable>)
4268 string(COMPARE EQUAL <string1> <string2> <output_variable>)
4269 string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
4270 string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
4271 string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
4272 Compare the strings and store true or false in the <output_variable>.
4274 Hashing
4276 string(<HASH> <output_variable> <input>)
4277 Compute a cryptographic hash of the <input> string. The supported
4279 <HASH> algorithm names are:
4280 MD5 Message-Digest Algorithm 5, RFC 1321.
4282 SHA1 US Secure Hash Algorithm 1, RFC 3174.
4284 SHA224 US Secure Hash Algorithms, RFC 4634.
4286 SHA256 US Secure Hash Algorithms, RFC 4634.
4288 SHA384 US Secure Hash Algorithms, RFC 4634.
4290 SHA512 US Secure Hash Algorithms, RFC 4634.
4292 SHA3_224
4294 Keccak SHA-3.
4295 SHA3_256
4297 Keccak SHA-3.
4298 SHA3_384
4300 Keccak SHA-3.
4301 SHA3_512
4303 Keccak SHA-3.
4304 Generation
4306 string(ASCII <number> [<number> ...] <output_variable>)
4307 Convert all numbers into corresponding ASCII characters.
4309 string(CONFIGURE <string> <output_variable>
4311 [@ONLY] [ESCAPE_QUOTES])
4312 Transform a <string> like configure_file() transforms a file.
4314 string(MAKE_C_IDENTIFIER <string> <output_variable>)
4316 Convert each non-alphanumeric character in the input <string> to an
4318 underscore and store the result in the <output_variable>. If the first
4319 character of the <string> is a digit, an underscore will also be
4320 prepended to the result.
4321 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
4323 [RANDOM_SEED <seed>] <output_variable>)
4324 Return a random string of given <length> consisting of characters from
4326 the given <alphabet>. Default length is 5 characters and default
4327 alphabet is all numbers and upper and lower case letters. If an inte‐
4328 ger RANDOM_SEED is given, its value will be used to seed the random
4329 number generator.
4330 string(TIMESTAMP <output_variable> [<format_string>] [UTC])
4332 Write a string representation of the current date and/or time to the
4334 <output_variable>.
4335 If the command is unable to obtain a timestamp, the <output_variable>
4337 will be set to the empty string "".
4338 The optional UTC flag requests the current date/time representation to
4340 be in Coordinated Universal Time (UTC) rather than local time.
4341 The optional <format_string> may contain the following format speci‐
4343 fiers:
4344 %% A literal percent sign (%).
4346 %d The day of the current month (01-31).
4347 %H The hour on a 24-hour clock (00-23).
4348 %I The hour on a 12-hour clock (01-12).
4349 %j The day of the current year (001-366).
4350 %m The month of the current year (01-12).
4351 %b Abbreviated month name (e.g. Oct).
4352 %B Full month name (e.g. October).
4353 %M The minute of the current hour (00-59).
4354 %s Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
4355 %S The second of the current minute.
4356 60 represents a leap second. (00-60)
4357 %U The week number of the current year (00-53).
4358 %w The day of the current week. 0 is Sunday. (0-6)
4359 %a Abbreviated weekday name (e.g. Fri).
4360 %A Full weekday name (e.g. Friday).
4361 %y The last two digits of the current year (00-99)
4362 %Y The current year.
4363 Unknown format specifiers will be ignored and copied to the output
4365 as-is.
4366 If no explicit <format_string> is given, it will default to:
4368 %Y-%m-%dT%H:%M:%S for local time.
4370 %Y-%m-%dT%H:%M:%SZ for UTC.
4371 NOTE:
4373 If the SOURCE_DATE_EPOCH environment variable is set, its value will
4374 be used instead of the current time. See
4375 https://reproducible-builds.org/specs/source-date-epoch/ for
4376 details.
4377 string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
4379 TYPE <MD5|SHA1> [UPPER])
4380 Create a universally unique identifier (aka GUID) as per RFC4122 based
4382 on the hash of the combined values of <namespace> (which itself has to
4383 be a valid UUID) and <name>. The hash algorithm can be either MD5
4384 (Version 3 UUID) or SHA1 (Version 5 UUID). A UUID has the format
4385 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where each x represents a lower
4386 case hexadecimal character. Where required, an uppercase representa‐
4387 tion can be requested with the optional UPPER flag.
4388 unset
4390 Unset a variable, cache variable, or environment variable.
4391 Unset Normal Variable or Cache Entry
4393 unset(<variable> [CACHE | PARENT_SCOPE])
4394 Removes a normal variable from the current scope, causing it to become
4396 undefined. If CACHE is present, then a cache variable is removed
4397 instead of a normal variable. Note that when evaluating Variable Ref‐
4398 erences of the form ${VAR}, CMake first searches for a normal variable
4399 with that name. If no such normal variable exists, CMake will then
4400 search for a cache entry with that name. Because of this unsetting a
4401 normal variable can expose a cache variable that was previously hidden.
4402 To force a variable reference of the form ${VAR} to return an empty
4403 string, use set(<variable> ""), which clears the normal variable but
4404 leaves it defined.
4405 If PARENT_SCOPE is present then the variable is removed from the scope
4407 above the current scope. See the same option in the set() command for
4408 further details.
4409 Unset Environment Variable
4411 unset(ENV{<variable>})
4412 Removes <variable> from the currently available Environment Variables.
4414 Subsequent calls of $ENV{<variable>} will return the empty string.
4415 This command affects only the current CMake process, not the process
4417 from which CMake was called, nor the system environment at large, nor
4418 the environment of subsequent build or test processes.
4419 variable_watch
4421 Watch the CMake variable for change.
4422 variable_watch(<variable> [<command>])
4424 If the specified <variable> changes, a message will be printed to
4426 inform about the change.
4427 Additionally, if <command> is given, this command will be executed.
4429 The command will receive the following arguments: COMMAND(<variable>
4430 <access> <value> <current_list_file> <stack>)
4431 while
4433 Evaluate a group of commands while a condition is true
4434 while(<condition>)
4436 <commands>
4437 endwhile()
4438 All commands between while and the matching endwhile() are recorded
4440 without being invoked. Once the endwhile() is evaluated, the recorded
4441 list of commands is invoked as long as the <condition> is true.
4442 The <condition> has the same syntax and is evaluated using the same
4444 logic as described at length for the if() command.
4445 The commands break() and continue() provide means to escape from the
4447 normal control flow.
4448 Per legacy, the endwhile() command admits an optional <condition> argu‐
4450 ment. If used, it must be a verbatim repeat of the argument of the
4451 opening while command.
4452
4454 These commands are available only in CMake projects.
4455 add_compile_definitions
4457 Add preprocessor definitions to the compilation of source files.
4458 add_compile_definitions(<definition> ...)
4460 Adds preprocessor definitions to the compiler command line for targets
4462 in the current directory and below (whether added before or after this
4463 command is invoked). See documentation of the directory and target COM‐
4464 PILE_DEFINITIONS properties.
4465 Definitions are specified using the syntax VAR or VAR=value. Func‐
4467 tion-style definitions are not supported. CMake will automatically
4468 escape the value correctly for the native build system (note that CMake
4469 language syntax may require escapes to specify some values).
4470 Arguments to add_compile_definitions may use “generator expressions”
4472 with the syntax $<...>. See the cmake-generator-expressions(7) manual
4473 for available expressions. See the cmake-buildsystem(7) manual for
4474 more on defining buildsystem properties.
4475 add_compile_options
4477 Add options to the compilation of source files.
4478 add_compile_options(<option> ...)
4480 Adds options to the COMPILE_OPTIONS directory property. These options
4482 are used when compiling targets from the current directory and below.
4483 Arguments
4485 Arguments to add_compile_options may use “generator expressions” with
4486 the syntax $<...>. See the cmake-generator-expressions(7) manual for
4487 available expressions. See the cmake-buildsystem(7) manual for more on
4488 defining buildsystem properties.
4489 The final set of compile or link options used for a target is con‐
4491 structed by accumulating options from the current target and the usage
4492 requirements of its dependencies. The set of options is de-duplicated
4493 to avoid repetition. While beneficial for individual options, the
4494 de-duplication step can break up option groups. For example, -D A -D B
4495 becomes -D A B. One may specify a group of options using shell-like
4496 quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and
4497 the rest of the option string is parsed using the separate_arguments()
4498 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
4499 -D B.
4500 Example
4502 Since different compilers support different options, a typical use of
4503 this command is in a compiler-specific conditional clause:
4504 if (MSVC)
4506 # warning level 4 and all warnings as errors
4507 add_compile_options(/W4 /WX)
4508 else()
4509 # lots of warnings and all warnings as errors
4510 add_compile_options(-Wall -Wextra -pedantic -Werror)
4511 endif()
4512 See Also
4514 This command can be used to add any options. However, for adding pre‐
4515 processor definitions and include directories it is recommended to use
4516 the more specific commands add_compile_definitions() and include_direc‐
4517 tories().
4518 The command target_compile_options() adds target-specific options.
4520 add_custom_command
4522 Add a custom build rule to the generated build system.
4523 There are two main signatures for add_custom_command.
4525 Generating Files
4527 The first signature is for adding a custom command to produce an out‐
4528 put:
4529 add_custom_command(OUTPUT output1 [output2 ...]
4531 COMMAND command1 [ARGS] [args1...]
4532 [COMMAND command2 [ARGS] [args2...] ...]
4533 [MAIN_DEPENDENCY depend]
4534 [DEPENDS [depends...]]
4535 [BYPRODUCTS [files...]]
4536 [IMPLICIT_DEPENDS <lang1> depend1
4537 [<lang2> depend2] ...]
4538 [WORKING_DIRECTORY dir]
4539 [COMMENT comment]
4540 [DEPFILE depfile]
4541 [JOB_POOL job_pool]
4542 [VERBATIM] [APPEND] [USES_TERMINAL]
4543 [COMMAND_EXPAND_LISTS])
4544 This defines a command to generate specified OUTPUT file(s). A target
4546 created in the same directory (CMakeLists.txt file) that specifies any
4547 output of the custom command as a source file is given a rule to gener‐
4548 ate the file using the command at build time. Do not list the output
4549 in more than one independent target that may build in parallel or the
4550 two instances of the rule may conflict (instead use the add_custom_tar‐
4551 get() command to drive the command and make the other targets depend on
4552 that one). In makefile terms this creates a new target in the follow‐
4553 ing form:
4554 OUTPUT: MAIN_DEPENDENCY DEPENDS
4556 COMMAND
4557 The options are:
4559 APPEND Append the COMMAND and DEPENDS option values to the custom com‐
4561 mand for the first output specified. There must have already
4562 been a previous call to this command with the same output. The
4563 COMMENT, MAIN_DEPENDENCY, and WORKING_DIRECTORY options are cur‐
4564 rently ignored when APPEND is given, but may be used in the
4565 future.
4566 BYPRODUCTS
4568 Specify the files the command is expected to produce but whose
4569 modification time may or may not be newer than the dependencies.
4570 If a byproduct name is a relative path it will be interpreted
4571 relative to the build tree directory corresponding to the cur‐
4572 rent source directory. Each byproduct file will be marked with
4573 the GENERATED source file property automatically.
4574 Explicit specification of byproducts is supported by the Ninja
4576 generator to tell the ninja build tool how to regenerate byprod‐
4577 ucts when they are missing. It is also useful when other build
4578 rules (e.g. custom commands) depend on the byproducts. Ninja
4579 requires a build rule for any generated file on which another
4580 rule depends even if there are order-only dependencies to ensure
4581 the byproducts will be available before their dependents build.
4582 The Makefile Generators will remove BYPRODUCTS and other GENER‐
4584 ATED files during make clean.
4585 COMMAND
4587 Specify the command-line(s) to execute at build time. If more
4588 than one COMMAND is specified they will be executed in order,
4589 but not necessarily composed into a stateful shell or batch
4590 script. (To run a full script, use the configure_file() command
4591 or the file(GENERATE) command to create it, and then specify a
4592 COMMAND to launch it.) The optional ARGS argument is for back‐
4593 ward compatibility and will be ignored.
4594 If COMMAND specifies an executable target name (created by the
4596 add_executable() command), it will automatically be replaced by
4597 the location of the executable created at build time if either
4598 of the following is true:
4599 · The target is not being cross-compiled (i.e. the CMAKE_CROSS‐
4601 COMPILING variable is not set to true).
4602 · The target is being cross-compiled and an emulator is provided
4604 (i.e. its CROSSCOMPILING_EMULATOR target property is set).
4605 In this case, the contents of CROSSCOMPILING_EMULATOR will be
4606 prepended to the command before the location of the target
4607 executable.
4608 If neither of the above conditions are met, it is assumed that
4610 the command name is a program to be found on the PATH at build
4611 time.
4612 Arguments to COMMAND may use generator expressions. Use the
4614 TARGET_FILE generator expression to refer to the location of a
4615 target later in the command line (i.e. as a command argument
4616 rather than as the command to execute).
4617 Whenever a target is used as a command to execute or is men‐
4619 tioned in a generator expression as a command argument, a tar‐
4620 get-level dependency will be added automatically so that the
4621 mentioned target will be built before any target using this cus‐
4622 tom command. However this does NOT add a file-level dependency
4623 that would cause the custom command to re-run whenever the exe‐
4624 cutable is recompiled. List target names with the DEPENDS
4625 option to add such file-level dependencies.
4626 COMMENT
4628 Display the given message before the commands are executed at
4629 build time.
4630 DEPENDS
4632 Specify files on which the command depends. Each argument is
4633 converted to a dependency as follows:
4634 1. If the argument is the name of a target (created by the
4636 add_custom_target(), add_executable(), or add_library() com‐
4637 mand) a target-level dependency is created to make sure the
4638 target is built before any target using this custom command.
4639 Additionally, if the target is an executable or library, a
4640 file-level dependency is created to cause the custom command
4641 to re-run whenever the target is recompiled.
4642 2. If the argument is an absolute path, a file-level dependency
4644 is created on that path.
4645 3. If the argument is the name of a source file that has been
4647 added to a target or on which a source file property has been
4648 set, a file-level dependency is created on that source file.
4649 4. If the argument is a relative path and it exists in the cur‐
4651 rent source directory, a file-level dependency is created on
4652 that file in the current source directory.
4653 5. Otherwise, a file-level dependency is created on that path
4655 relative to the current binary directory.
4656 If any dependency is an OUTPUT of another custom command in the
4658 same directory (CMakeLists.txt file), CMake automatically brings
4659 the other custom command into the target in which this command
4660 is built. A target-level dependency is added if any dependency
4661 is listed as BYPRODUCTS of a target or any of its build events
4662 in the same directory to ensure the byproducts will be avail‐
4663 able.
4664 If DEPENDS is not specified, the command will run whenever the
4666 OUTPUT is missing; if the command does not actually create the
4667 OUTPUT, the rule will always run.
4668 Arguments to DEPENDS may use generator expressions.
4670 COMMAND_EXPAND_LISTS
4672 Lists in COMMAND arguments will be expanded, including those
4673 created with generator expressions, allowing COMMAND arguments
4674 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
4675 RIES>,;-I>" foo.cc to be properly expanded.
4676 IMPLICIT_DEPENDS
4678 Request scanning of implicit dependencies of an input file. The
4679 language given specifies the programming language whose corre‐
4680 sponding dependency scanner should be used. Currently only C
4681 and CXX language scanners are supported. The language has to be
4682 specified for every file in the IMPLICIT_DEPENDS list. Depen‐
4683 dencies discovered from the scanning are added to those of the
4684 custom command at build time. Note that the IMPLICIT_DEPENDS
4685 option is currently supported only for Makefile generators and
4686 will be ignored by other generators.
4687 JOB_POOL
4689 Specify a pool for the Ninja generator. Incompatible with
4690 USES_TERMINAL, which implies the console pool. Using a pool
4691 that is not defined by JOB_POOLS causes an error by ninja at
4692 build time.
4693 MAIN_DEPENDENCY
4695 Specify the primary input source file to the command. This is
4696 treated just like any value given to the DEPENDS option but also
4697 suggests to Visual Studio generators where to hang the custom
4698 command. Each source file may have at most one command specify‐
4699 ing it as its main dependency. A compile command (i.e. for a
4700 library or an executable) counts as an implicit main dependency
4701 which gets silently overwritten by a custom command specifica‐
4702 tion.
4703 OUTPUT Specify the output files the command is expected to produce. If
4705 an output name is a relative path it will be interpreted rela‐
4706 tive to the build tree directory corresponding to the current
4707 source directory. Each output file will be marked with the GEN‐
4708 ERATED source file property automatically. If the output of the
4709 custom command is not actually created as a file on disk it
4710 should be marked with the SYMBOLIC source file property.
4711 USES_TERMINAL
4713 The command will be given direct access to the terminal if pos‐
4714 sible. With the Ninja generator, this places the command in the
4715 console pool.
4716 VERBATIM
4718 All arguments to the commands will be escaped properly for the
4719 build tool so that the invoked command receives each argument
4720 unchanged. Note that one level of escapes is still used by the
4721 CMake language processor before add_custom_command even sees the
4722 arguments. Use of VERBATIM is recommended as it enables correct
4723 behavior. When VERBATIM is not given the behavior is platform
4724 specific because there is no protection of tool-specific special
4725 characters.
4726 WORKING_DIRECTORY
4728 Execute the command with the given current working directory.
4729 If it is a relative path it will be interpreted relative to the
4730 build tree directory corresponding to the current source direc‐
4731 tory.
4732 Arguments to WORKING_DIRECTORY may use generator expressions.
4734 DEPFILE
4736 Specify a .d depfile for the Ninja generator. A .d file holds
4737 dependencies usually emitted by the custom command itself.
4738 Using DEPFILE with other generators than Ninja is an error.
4739 Build Events
4741 The second signature adds a custom command to a target such as a
4742 library or executable. This is useful for performing an operation
4743 before or after building the target. The command becomes part of the
4744 target and will only execute when the target itself is built. If the
4745 target is already built, the command will not execute.
4746 add_custom_command(TARGET <target>
4748 PRE_BUILD | PRE_LINK | POST_BUILD
4749 COMMAND command1 [ARGS] [args1...]
4750 [COMMAND command2 [ARGS] [args2...] ...]
4751 [BYPRODUCTS [files...]]
4752 [WORKING_DIRECTORY dir]
4753 [COMMENT comment]
4754 [VERBATIM] [USES_TERMINAL]
4755 [COMMAND_EXPAND_LISTS])
4756 This defines a new command that will be associated with building the
4758 specified <target>. The <target> must be defined in the current direc‐
4759 tory; targets defined in other directories may not be specified.
4760 When the command will happen is determined by which of the following is
4762 specified:
4763 PRE_BUILD
4765 On Visual Studio Generators, run before any other rules are exe‐
4766 cuted within the target. On other generators, run just before
4767 PRE_LINK commands.
4768 PRE_LINK
4770 Run after sources have been compiled but before linking the
4771 binary or running the librarian or archiver tool of a static
4772 library. This is not defined for targets created by the
4773 add_custom_target() command.
4774 POST_BUILD
4776 Run after all other rules within the target have been executed.
4777 NOTE:
4779 Because generator expressions can be used in custom commands, it is
4780 possible to define COMMAND lines or whole custom commands which
4781 evaluate to empty strings for certain configurations. For Visual
4782 Studio 2010 (and newer) generators these command lines or custom
4783 commands will be omitted for the specific configuration and no
4784 “empty-string-command” will be added.
4785 This allows to add individual build events for every configuration.
4787 add_custom_target
4789 Add a target with no output so it will always be built.
4790 add_custom_target(Name [ALL] [command1 [args1...]]
4792 [COMMAND command2 [args2...] ...]
4793 [DEPENDS depend depend depend ... ]
4794 [BYPRODUCTS [files...]]
4795 [WORKING_DIRECTORY dir]
4796 [COMMENT comment]
4797 [JOB_POOL job_pool]
4798 [VERBATIM] [USES_TERMINAL]
4799 [COMMAND_EXPAND_LISTS]
4800 [SOURCES src1 [src2...]])
4801 Adds a target with the given name that executes the given commands.
4803 The target has no output file and is always considered out of date even
4804 if the commands try to create a file with the name of the target. Use
4805 the add_custom_command() command to generate a file with dependencies.
4806 By default nothing depends on the custom target. Use the add_dependen‐
4807 cies() command to add dependencies to or from other targets.
4808 The options are:
4810 ALL Indicate that this target should be added to the default build
4812 target so that it will be run every time (the command cannot be
4813 called ALL).
4814 BYPRODUCTS
4816 Specify the files the command is expected to produce but whose
4817 modification time may or may not be updated on subsequent
4818 builds. If a byproduct name is a relative path it will be
4819 interpreted relative to the build tree directory corresponding
4820 to the current source directory. Each byproduct file will be
4821 marked with the GENERATED source file property automatically.
4822 Explicit specification of byproducts is supported by the Ninja
4824 generator to tell the ninja build tool how to regenerate byprod‐
4825 ucts when they are missing. It is also useful when other build
4826 rules (e.g. custom commands) depend on the byproducts. Ninja
4827 requires a build rule for any generated file on which another
4828 rule depends even if there are order-only dependencies to ensure
4829 the byproducts will be available before their dependents build.
4830 The Makefile Generators will remove BYPRODUCTS and other GENER‐
4832 ATED files during make clean.
4833 COMMAND
4835 Specify the command-line(s) to execute at build time. If more
4836 than one COMMAND is specified they will be executed in order,
4837 but not necessarily composed into a stateful shell or batch
4838 script. (To run a full script, use the configure_file() command
4839 or the file(GENERATE) command to create it, and then specify a
4840 COMMAND to launch it.)
4841 If COMMAND specifies an executable target name (created by the
4843 add_executable() command), it will automatically be replaced by
4844 the location of the executable created at build time if either
4845 of the following is true:
4846 · The target is not being cross-compiled (i.e. the CMAKE_CROSS‐
4848 COMPILING variable is not set to true).
4849 · The target is being cross-compiled and an emulator is provided
4851 (i.e. its CROSSCOMPILING_EMULATOR target property is set).
4852 In this case, the contents of CROSSCOMPILING_EMULATOR will be
4853 prepended to the command before the location of the target
4854 executable.
4855 If neither of the above conditions are met, it is assumed that
4857 the command name is a program to be found on the PATH at build
4858 time.
4859 Arguments to COMMAND may use generator expressions. Use the
4861 TARGET_FILE generator expression to refer to the location of a
4862 target later in the command line (i.e. as a command argument
4863 rather than as the command to execute).
4864 Whenever a target is used as a command to execute or is men‐
4866 tioned in a generator expression as a command argument, a tar‐
4867 get-level dependency will be added automatically so that the
4868 mentioned target will be built before this custom target.
4869 The command and arguments are optional and if not specified an
4871 empty target will be created.
4872 COMMENT
4874 Display the given message before the commands are executed at
4875 build time.
4876 DEPENDS
4878 Reference files and outputs of custom commands created with
4879 add_custom_command() command calls in the same directory (CMake‐
4880 Lists.txt file). They will be brought up to date when the tar‐
4881 get is built. A target-level dependency is added if any depen‐
4882 dency is a byproduct of a target or any of its build events in
4883 the same directory to ensure the byproducts will be available
4884 before this target is built.
4885 Use the add_dependencies() command to add dependencies on other
4887 targets.
4888 COMMAND_EXPAND_LISTS
4890 Lists in COMMAND arguments will be expanded, including those
4891 created with generator expressions, allowing COMMAND arguments
4892 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
4893 RIES>,;-I>" foo.cc to be properly expanded.
4894 JOB_POOL
4896 Specify a pool for the Ninja generator. Incompatible with
4897 USES_TERMINAL, which implies the console pool. Using a pool
4898 that is not defined by JOB_POOLS causes an error by ninja at
4899 build time.
4900 SOURCES
4902 Specify additional source files to be included in the custom
4903 target. Specified source files will be added to IDE project
4904 files for convenience in editing even if they have no build
4905 rules.
4906 VERBATIM
4908 All arguments to the commands will be escaped properly for the
4909 build tool so that the invoked command receives each argument
4910 unchanged. Note that one level of escapes is still used by the
4911 CMake language processor before add_custom_target even sees the
4912 arguments. Use of VERBATIM is recommended as it enables correct
4913 behavior. When VERBATIM is not given the behavior is platform
4914 specific because there is no protection of tool-specific special
4915 characters.
4916 USES_TERMINAL
4918 The command will be given direct access to the terminal if pos‐
4919 sible. With the Ninja generator, this places the command in the
4920 console pool.
4921 WORKING_DIRECTORY
4923 Execute the command with the given current working directory.
4924 If it is a relative path it will be interpreted relative to the
4925 build tree directory corresponding to the current source direc‐
4926 tory.
4927 Arguments to WORKING_DIRECTORY may use generator expressions.
4929 add_definitions
4931 Add -D define flags to the compilation of source files.
4932 add_definitions(-DFOO -DBAR ...)
4934 Adds definitions to the compiler command line for targets in the cur‐
4936 rent directory and below (whether added before or after this command is
4937 invoked). This command can be used to add any flags, but it is
4938 intended to add preprocessor definitions.
4939 NOTE:
4941 This command has been superseded by alternatives:
4942 · Use add_compile_definitions() to add preprocessor definitions.
4944 · Use include_directories() to add include directories.
4946 · Use add_compile_options() to add other options.
4948 Flags beginning in -D or /D that look like preprocessor definitions are
4950 automatically added to the COMPILE_DEFINITIONS directory property for
4951 the current directory. Definitions with non-trivial values may be left
4952 in the set of flags instead of being converted for reasons of backwards
4953 compatibility. See documentation of the directory, target, source file
4954 COMPILE_DEFINITIONS properties for details on adding preprocessor defi‐
4955 nitions to specific scopes and configurations.
4956 See the cmake-buildsystem(7) manual for more on defining buildsystem
4958 properties.
4959 add_dependencies
4961 Add a dependency between top-level targets.
4962 add_dependencies(<target> [<target-dependency>]...)
4964 Makes a top-level <target> depend on other top-level targets to ensure
4966 that they build before <target> does. A top-level target is one cre‐
4967 ated by one of the add_executable(), add_library(), or add_custom_tar‐
4968 get() commands (but not targets generated by CMake like install).
4969 Dependencies added to an imported target or an interface library are
4971 followed transitively in its place since the target itself does not
4972 build.
4973 See the DEPENDS option of add_custom_target() and add_custom_command()
4975 commands for adding file-level dependencies in custom rules. See the
4976 OBJECT_DEPENDS source file property to add file-level dependencies to
4977 object files.
4978 add_executable
4980 Add an executable to the project using the specified source files.
4981 add_executable(<name> [WIN32] [MACOSX_BUNDLE]
4983 [EXCLUDE_FROM_ALL]
4984 [source1] [source2 ...])
4985 Adds an executable target called <name> to be built from the source
4987 files listed in the command invocation. (The source files can be omit‐
4988 ted here if they are added later using target_sources().) The <name>
4989 corresponds to the logical target name and must be globally unique
4990 within a project. The actual file name of the executable built is con‐
4991 structed based on conventions of the native platform (such as
4992 <name>.exe or just <name>).
4993 By default the executable file will be created in the build tree direc‐
4995 tory corresponding to the source tree directory in which the command
4996 was invoked. See documentation of the RUNTIME_OUTPUT_DIRECTORY target
4997 property to change this location. See documentation of the OUTPUT_NAME
4998 target property to change the <name> part of the final file name.
4999 If WIN32 is given the property WIN32_EXECUTABLE will be set on the tar‐
5001 get created. See documentation of that target property for details.
5002 If MACOSX_BUNDLE is given the corresponding property will be set on the
5004 created target. See documentation of the MACOSX_BUNDLE target property
5005 for details.
5006 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
5008 the created target. See documentation of the EXCLUDE_FROM_ALL target
5009 property for details.
5010 Source arguments to add_executable may use “generator expressions” with
5012 the syntax $<...>. See the cmake-generator-expressions(7) manual for
5013 available expressions. See the cmake-buildsystem(7) manual for more on
5014 defining buildsystem properties.
5015 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
5017 cessed, and you want to have the original sources reachable from within
5018 IDE.
5019 ----
5022 add_executable(<name> IMPORTED [GLOBAL])
5026 An IMPORTED executable target references an executable file located
5028 outside the project. No rules are generated to build it, and the
5029 IMPORTED target property is True. The target name has scope in the
5030 directory in which it is created and below, but the GLOBAL option
5031 extends visibility. It may be referenced like any target built within
5032 the project. IMPORTED executables are useful for convenient reference
5033 from commands like add_custom_command(). Details about the imported
5034 executable are specified by setting properties whose names begin in
5035 IMPORTED_. The most important such property is IMPORTED_LOCATION (and
5036 its per-configuration version IMPORTED_LOCATION_<CONFIG>) which speci‐
5037 fies the location of the main executable file on disk. See documenta‐
5038 tion of the IMPORTED_* properties for more information.
5039 ----
5042 add_executable(<name> ALIAS <target>)
5046 Creates an Alias Target, such that <name> can be used to refer to <tar‐
5048 get> in subsequent commands. The <name> does not appear in the gener‐
5049 ated buildsystem as a make target. The <target> may not be a
5050 non-GLOBAL Imported Target or an ALIAS. ALIAS targets can be used as
5051 targets to read properties from, executables for custom commands and
5052 custom targets. They can also be tested for existence with the regular
5053 if(TARGET) subcommand. The <name> may not be used to modify properties
5054 of <target>, that is, it may not be used as the operand of set_prop‐
5055 erty(), set_target_properties(), target_link_libraries() etc. An ALIAS
5056 target may not be installed or exported.
5057 add_library
5059 Add a library to the project using the specified source files.
5060 Normal Libraries
5062 add_library(<name> [STATIC | SHARED | MODULE]
5063 [EXCLUDE_FROM_ALL]
5064 [source1] [source2 ...])
5065 Adds a library target called <name> to be built from the source files
5067 listed in the command invocation. (The source files can be omitted
5068 here if they are added later using target_sources().) The <name> cor‐
5069 responds to the logical target name and must be globally unique within
5070 a project. The actual file name of the library built is constructed
5071 based on conventions of the native platform (such as lib<name>.a or
5072 <name>.lib).
5073 STATIC, SHARED, or MODULE may be given to specify the type of library
5075 to be created. STATIC libraries are archives of object files for use
5076 when linking other targets. SHARED libraries are linked dynamically
5077 and loaded at runtime. MODULE libraries are plugins that are not
5078 linked into other targets but may be loaded dynamically at runtime
5079 using dlopen-like functionality. If no type is given explicitly the
5080 type is STATIC or SHARED based on whether the current value of the
5081 variable BUILD_SHARED_LIBS is ON. For SHARED and MODULE libraries the
5082 POSITION_INDEPENDENT_CODE target property is set to ON automatically.
5083 A SHARED or STATIC library may be marked with the FRAMEWORK target
5084 property to create an macOS Framework.
5085 If a library does not export any symbols, it must not be declared as a
5087 SHARED library. For example, a Windows resource DLL or a managed
5088 C++/CLI DLL that exports no unmanaged symbols would need to be a MODULE
5089 library. This is because CMake expects a SHARED library to always have
5090 an associated import library on Windows.
5091 By default the library file will be created in the build tree directory
5093 corresponding to the source tree directory in which the command was
5094 invoked. See documentation of the ARCHIVE_OUTPUT_DIRECTORY,
5095 LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY target proper‐
5096 ties to change this location. See documentation of the OUTPUT_NAME
5097 target property to change the <name> part of the final file name.
5098 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
5100 the created target. See documentation of the EXCLUDE_FROM_ALL target
5101 property for details.
5102 Source arguments to add_library may use “generator expressions” with
5104 the syntax $<...>. See the cmake-generator-expressions(7) manual for
5105 available expressions. See the cmake-buildsystem(7) manual for more on
5106 defining buildsystem properties.
5107 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
5109 cessed, and you want to have the original sources reachable from within
5110 IDE.
5111 Imported Libraries
5113 add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED
5114 [GLOBAL])
5115 An IMPORTED library target references a library file located outside
5117 the project. No rules are generated to build it, and the IMPORTED tar‐
5118 get property is True. The target name has scope in the directory in
5119 which it is created and below, but the GLOBAL option extends visibil‐
5120 ity. It may be referenced like any target built within the project.
5121 IMPORTED libraries are useful for convenient reference from commands
5122 like target_link_libraries(). Details about the imported library are
5123 specified by setting properties whose names begin in IMPORTED_ and
5124 INTERFACE_.
5125 The most important properties are:
5127 · IMPORTED_LOCATION (and its per-configuration variant IMPORTED_LOCA‐
5129 TION_<CONFIG>) which specifies the location of the main library file
5130 on disk.
5131 · IMPORTED_OBJECTS (and IMPORTED_OBJECTS_<CONFIG>) for object
5133 libraries, specifies the locations of object files on disk.
5134 · PUBLIC_HEADER files to be installed during install() invocation
5136 See documentation of the IMPORTED_* and INTERFACE_* properties for more
5138 information.
5139 An UNKNOWN library type is typically only used in the implementation of
5141 Find Modules. It allows the path to an imported library (often found
5142 using the find_library() command) to be used without having to know
5143 what type of library it is. This is especially useful on Windows where
5144 a static library and a DLL’s import library both have the same file
5145 extension.
5146 Object Libraries
5148 add_library(<name> OBJECT <src>...)
5149 Creates an Object Library. An object library compiles source files but
5151 does not archive or link their object files into a library. Instead
5152 other targets created by add_library() or add_executable() may refer‐
5153 ence the objects using an expression of the form $<TAR‐
5154 GET_OBJECTS:objlib> as a source, where objlib is the object library
5155 name. For example:
5156 add_library(... $<TARGET_OBJECTS:objlib> ...)
5158 add_executable(... $<TARGET_OBJECTS:objlib> ...)
5159 will include objlib’s object files in a library and an executable along
5161 with those compiled from their own sources. Object libraries may con‐
5162 tain only sources that compile, header files, and other files that
5163 would not affect linking of a normal library (e.g. .txt). They may
5164 contain custom commands generating such sources, but not PRE_BUILD,
5165 PRE_LINK, or POST_BUILD commands. Some native build systems (such as
5166 Xcode) may not like targets that have only object files, so consider
5167 adding at least one real source file to any target that references
5168 $<TARGET_OBJECTS:objlib>.
5169 Alias Libraries
5171 add_library(<name> ALIAS <target>)
5172 Creates an Alias Target, such that <name> can be used to refer to <tar‐
5174 get> in subsequent commands. The <name> does not appear in the gener‐
5175 ated buildsystem as a make target. The <target> may not be a
5176 non-GLOBAL Imported Target or an ALIAS. ALIAS targets can be used as
5177 linkable targets and as targets to read properties from. They can also
5178 be tested for existence with the regular if(TARGET) subcommand. The
5179 <name> may not be used to modify properties of <target>, that is, it
5180 may not be used as the operand of set_property(), set_target_proper‐
5181 ties(), target_link_libraries() etc. An ALIAS target may not be
5182 installed or exported.
5183 Interface Libraries
5185 add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
5186 Creates an Interface Library. An INTERFACE library target does not
5188 directly create build output, though it may have properties set on it
5189 and it may be installed, exported and imported. Typically the INTER‐
5190 FACE_* properties are populated on the interface target using the com‐
5191 mands:
5192 · set_property(),
5194 · target_link_libraries(INTERFACE),
5196 · target_link_options(INTERFACE),
5198 · target_include_directories(INTERFACE),
5200 · target_compile_options(INTERFACE),
5202 · target_compile_definitions(INTERFACE), and
5204 · target_sources(INTERFACE),
5206 and then it is used as an argument to target_link_libraries() like any
5208 other target.
5209 An INTERFACE Imported Target may also be created with this signature.
5211 An IMPORTED library target references a library defined outside the
5212 project. The target name has scope in the directory in which it is
5213 created and below, but the GLOBAL option extends visibility. It may be
5214 referenced like any target built within the project. IMPORTED
5215 libraries are useful for convenient reference from commands like tar‐
5216 get_link_libraries().
5217 add_link_options
5219 Add options to the link step for executable, shared library or module
5220 library targets in the current directory and below that are added after
5221 this command is invoked.
5222 add_link_options(<option> ...)
5224 This command can be used to add any link options, but alternative com‐
5226 mands exist to add libraries (target_link_libraries() or
5227 link_libraries()). See documentation of the directory and target
5228 LINK_OPTIONS properties.
5229 NOTE:
5231 This command cannot be used to add options for static library tar‐
5232 gets, since they do not use a linker. To add archiver or MSVC
5233 librarian flags, see the STATIC_LIBRARY_OPTIONS target property.
5234 Arguments to add_link_options may use “generator expressions” with the
5236 syntax $<...>. See the cmake-generator-expressions(7) manual for
5237 available expressions. See the cmake-buildsystem(7) manual for more on
5238 defining buildsystem properties.
5239 The final set of compile or link options used for a target is con‐
5241 structed by accumulating options from the current target and the usage
5242 requirements of its dependencies. The set of options is de-duplicated
5243 to avoid repetition. While beneficial for individual options, the
5244 de-duplication step can break up option groups. For example, -D A -D B
5245 becomes -D A B. One may specify a group of options using shell-like
5246 quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and
5247 the rest of the option string is parsed using the separate_arguments()
5248 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
5249 -D B.
5250 To pass options to the linker tool, each compiler driver has its own
5252 syntax. The LINKER: prefix and , separator can be used to specify, in
5253 a portable way, options to pass to the linker tool. LINKER: is replaced
5254 by the appropriate driver option and , by the appropriate driver sepa‐
5255 rator. The driver prefix and driver separator are given by the values
5256 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAP‐
5257 PER_FLAG_SEP variables.
5258 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
5260 Clang and -Wl,-z,defs for GNU GCC.
5261 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
5263 sion.
5264 The LINKER: prefix supports, as an alternative syntax, specification of
5266 arguments using the SHELL: prefix and space as separator. The previous
5267 example then becomes "LINKER:SHELL:-z defs".
5268 NOTE:
5270 Specifying the SHELL: prefix anywhere other than at the beginning of
5271 the LINKER: prefix is not supported.
5272 add_subdirectory
5274 Add a subdirectory to the build.
5275 add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
5277 Adds a subdirectory to the build. The source_dir specifies the direc‐
5279 tory in which the source CMakeLists.txt and code files are located. If
5280 it is a relative path it will be evaluated with respect to the current
5281 directory (the typical usage), but it may also be an absolute path.
5282 The binary_dir specifies the directory in which to place the output
5283 files. If it is a relative path it will be evaluated with respect to
5284 the current output directory, but it may also be an absolute path. If
5285 binary_dir is not specified, the value of source_dir, before expanding
5286 any relative path, will be used (the typical usage). The CMake‐
5287 Lists.txt file in the specified source directory will be processed
5288 immediately by CMake before processing in the current input file con‐
5289 tinues beyond this command.
5290 If the EXCLUDE_FROM_ALL argument is provided then targets in the subdi‐
5292 rectory will not be included in the ALL target of the parent directory
5293 by default, and will be excluded from IDE project files. Users must
5294 explicitly build targets in the subdirectory. This is meant for use
5295 when the subdirectory contains a separate part of the project that is
5296 useful but not necessary, such as a set of examples. Typically the
5297 subdirectory should contain its own project() command invocation so
5298 that a full build system will be generated in the subdirectory (such as
5299 a VS IDE solution file). Note that inter-target dependencies supersede
5300 this exclusion. If a target built by the parent project depends on a
5301 target in the subdirectory, the dependee target will be included in the
5302 parent project build system to satisfy the dependency.
5303 add_test
5305 Add a test to the project to be run by ctest(1).
5306 add_test(NAME <name> COMMAND <command> [<arg>...]
5308 [CONFIGURATIONS <config>...]
5309 [WORKING_DIRECTORY <dir>]
5310 [COMMAND_EXPAND_LISTS])
5311 Adds a test called <name>. The test name may not contain spaces,
5313 quotes, or other characters special in CMake syntax. The options are:
5314 COMMAND
5316 Specify the test command-line. If <command> specifies an exe‐
5317 cutable target (created by add_executable()) it will automati‐
5318 cally be replaced by the location of the executable created at
5319 build time.
5320 CONFIGURATIONS
5322 Restrict execution of the test only to the named configurations.
5323 WORKING_DIRECTORY
5325 Set the WORKING_DIRECTORY test property to specify the working
5326 directory in which to execute the test. If not specified the
5327 test will be run with the current working directory set to the
5328 build directory corresponding to the current source directory.
5329 COMMAND_EXPAND_LISTS
5331 Lists in COMMAND arguments will be expanded, including those
5332 created with generator expressions.
5333 The given test command is expected to exit with code 0 to pass and
5335 non-zero to fail, or vice-versa if the WILL_FAIL test property is set.
5336 Any output written to stdout or stderr will be captured by ctest(1) but
5337 does not affect the pass/fail status unless the PASS_REGULAR_EXPRES‐
5338 SION, FAIL_REGULAR_EXPRESSION or SKIP_REGULAR_EXPRESSION test property
5339 is used.
5340 The COMMAND and WORKING_DIRECTORY options may use “generator expres‐
5342 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
5343 manual for available expressions.
5344 Example usage:
5346 add_test(NAME mytest
5348 COMMAND testDriver --config $<CONFIGURATION>
5349 --exe $<TARGET_FILE:myexe>)
5350 This creates a test mytest whose command runs a testDriver tool passing
5352 the configuration name and the full path to the executable file pro‐
5353 duced by target myexe.
5354 NOTE:
5356 CMake will generate tests only if the enable_testing() command has
5357 been invoked. The CTest module invokes the command automatically
5358 unless the BUILD_TESTING option is turned OFF.
5359 ----
5362 add_test(<name> <command> [<arg>...])
5366 Add a test called <name> with the given command-line. Unlike the above
5368 NAME signature no transformation is performed on the command-line to
5369 support target names or generator expressions.
5370 aux_source_directory
5372 Find all source files in a directory.
5373 aux_source_directory(<dir> <variable>)
5375 Collects the names of all the source files in the specified directory
5377 and stores the list in the <variable> provided. This command is
5378 intended to be used by projects that use explicit template instantia‐
5379 tion. Template instantiation files can be stored in a Templates subdi‐
5380 rectory and collected automatically using this command to avoid manu‐
5381 ally listing all instantiations.
5382 It is tempting to use this command to avoid writing the list of source
5384 files for a library or executable target. While this seems to work,
5385 there is no way for CMake to generate a build system that knows when a
5386 new source file has been added. Normally the generated build system
5387 knows when it needs to rerun CMake because the CMakeLists.txt file is
5388 modified to add a new source. When the source is just added to the
5389 directory without modifying this file, one would have to manually rerun
5390 CMake to generate a build system incorporating the new file.
5391 build_command
5393 Get a command line to build the current project. This is mainly
5394 intended for internal use by the CTest module.
5395 build_command(<variable>
5397 [CONFIGURATION <config>]
5398 [TARGET <target>]
5399 [PROJECT_NAME <projname>] # legacy, causes warning
5400 )
5401 Sets the given <variable> to a command-line string of the form:
5403 <cmake> --build . [--config <config>] [--target <target>...] [-- -i]
5405 where <cmake> is the location of the cmake(1) command-line tool, and
5407 <config> and <target> are the values provided to the CONFIGURATION and
5408 TARGET options, if any. The trailing -- -i option is added for Make‐
5409 file Generators if policy CMP0061 is not set to NEW.
5410 When invoked, this cmake --build command line will launch the underly‐
5412 ing build system tool.
5413 build_command(<cachevariable> <makecommand>)
5415 This second signature is deprecated, but still available for backwards
5417 compatibility. Use the first signature instead.
5418 It sets the given <cachevariable> to a command-line string as above but
5420 without the --target option. The <makecommand> is ignored but should
5421 be the full path to devenv, nmake, make or one of the end user build
5422 tools for legacy invocations.
5423 NOTE:
5425 In CMake versions prior to 3.0 this command returned a command line
5426 that directly invokes the native build tool for the current genera‐
5427 tor. Their implementation of the PROJECT_NAME option had no useful
5428 effects, so CMake now warns on use of the option.
5429 create_test_sourcelist
5431 Create a test driver and source list for building test programs.
5432 create_test_sourcelist(sourceListName driverName
5434 test1 test2 test3
5435 EXTRA_INCLUDE include.h
5436 FUNCTION function)
5437 A test driver is a program that links together many small tests into a
5439 single executable. This is useful when building static executables
5440 with large libraries to shrink the total required size. The list of
5441 source files needed to build the test driver will be in sourceListName.
5442 driverName is the name of the test driver program. The rest of the
5443 arguments consist of a list of test source files, can be semicolon sep‐
5444 arated. Each test source file should have a function in it that is the
5445 same name as the file with no extension (foo.cxx should have int
5446 foo(int, char*[]);) driverName will be able to call each of the tests
5447 by name on the command line. If EXTRA_INCLUDE is specified, then the
5448 next argument is included into the generated file. If FUNCTION is
5449 specified, then the next argument is taken as a function name that is
5450 passed a pointer to ac and av. This can be used to add extra command
5451 line processing to each test. The CMAKE_TESTDRIVER_BEFORE_TESTMAIN
5452 cmake variable can be set to have code that will be placed directly
5453 before calling the test main function. CMAKE_TESTDRIVER_AFTER_TESTMAIN
5454 can be set to have code that will be placed directly after the call to
5455 the test main function.
5456 define_property
5458 Define and document custom properties.
5459 define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
5461 TEST | VARIABLE | CACHED_VARIABLE>
5462 PROPERTY <name> [INHERITED]
5463 BRIEF_DOCS <brief-doc> [docs...]
5464 FULL_DOCS <full-doc> [docs...])
5465 Defines one property in a scope for use with the set_property() and
5467 get_property() commands. This is primarily useful to associate docu‐
5468 mentation with property names that may be retrieved with the get_prop‐
5469 erty() command. The first argument determines the kind of scope in
5470 which the property should be used. It must be one of the following:
5471 GLOBAL = associated with the global namespace
5473 DIRECTORY = associated with one directory
5474 TARGET = associated with one target
5475 SOURCE = associated with one source file
5476 TEST = associated with a test named with add_test
5477 VARIABLE = documents a CMake language variable
5478 CACHED_VARIABLE = documents a CMake cache variable
5479 Note that unlike set_property() and get_property() no actual scope
5481 needs to be given; only the kind of scope is important.
5482 The required PROPERTY option is immediately followed by the name of the
5484 property being defined.
5485 If the INHERITED option is given, then the get_property() command will
5487 chain up to the next higher scope when the requested property is not
5488 set in the scope given to the command.
5489 · DIRECTORY scope chains to its parent directory’s scope, continuing
5491 the walk up parent directories until a directory has the property set
5492 or there are no more parents. If still not found at the top level
5493 directory, it chains to the GLOBAL scope.
5494 · TARGET, SOURCE and TEST properties chain to DIRECTORY scope, includ‐
5496 ing further chaining up the directories, etc. as needed.
5497 Note that this scope chaining behavior only applies to calls to
5499 get_property(), get_directory_property(), get_target_property(),
5500 get_source_file_property() and get_test_property(). There is no inher‐
5501 iting behavior when setting properties, so using APPEND or
5502 APPEND_STRING with the set_property() command will not consider inher‐
5503 ited values when working out the contents to append to.
5504 The BRIEF_DOCS and FULL_DOCS options are followed by strings to be
5506 associated with the property as its brief and full documentation. Cor‐
5507 responding options to the get_property() command will retrieve the doc‐
5508 umentation.
5509 enable_language
5511 Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc)
5512 enable_language(<lang> [OPTIONAL] )
5514 Enables support for the named language in CMake. This is the same as
5516 the project() command but does not create any of the extra variables
5517 that are created by the project command. Example languages are CXX, C,
5518 CUDA, OBJC, OBJCXX, Fortran, and ASM.
5519 If enabling ASM, enable it last so that CMake can check whether compil‐
5521 ers for other languages like C work for assembly too.
5522 This command must be called in file scope, not in a function call.
5524 Furthermore, it must be called in the highest directory common to all
5525 targets using the named language directly for compiling sources or
5526 indirectly through link dependencies. It is simplest to enable all
5527 needed languages in the top-level directory of a project.
5528 The OPTIONAL keyword is a placeholder for future implementation and
5530 does not currently work. Instead you can use the CheckLanguage module
5531 to verify support before enabling.
5532 enable_testing
5534 Enable testing for current directory and below.
5535 enable_testing()
5537 Enables testing for this directory and below.
5539 This command should be in the source directory root because ctest
5541 expects to find a test file in the build directory root.
5542 This command is automatically invoked when the CTest module is
5544 included, except if the BUILD_TESTING option is turned off.
5545 See also the add_test() command.
5547 export
5549 Export targets from the build tree for use by outside projects.
5550 export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
5552 Creates a file <filename> that may be included by outside projects to
5554 import targets from the current project’s build tree. This is useful
5555 during cross-compiling to build utility executables that can run on the
5556 host platform in one project and then import them into another project
5557 being compiled for the target platform. If the NAMESPACE option is
5558 given the <namespace> string will be prepended to all target names
5559 written to the file.
5560 Target installations are associated with the export <export-name> using
5562 the EXPORT option of the install(TARGETS) command.
5563 The file created by this command is specific to the build tree and
5565 should never be installed. See the install(EXPORT) command to export
5566 targets from an installation tree.
5567 The properties set on the generated IMPORTED targets will have the same
5569 values as the final values of the input TARGETS.
5570 export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
5572 [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
5573 This signature is similar to the EXPORT signature, but targets are
5575 listed explicitly rather than specified as an export-name. If the
5576 APPEND option is given the generated code will be appended to the file
5577 instead of overwriting it. The EXPORT_LINK_INTERFACE_LIBRARIES key‐
5578 word, if present, causes the contents of the properties matching
5579 (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when
5580 policy CMP0022 is NEW. If a library target is included in the export
5581 but a target to which it links is not included the behavior is unspeci‐
5582 fied.
5583 NOTE:
5585 Object Libraries under Xcode have special handling if multiple
5586 architectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
5587 they will be exported as Interface Libraries with no object files
5588 available to clients. This is sufficient to satisfy transitive
5589 usage requirements of other targets that link to the object
5590 libraries in their implementation.
5591 export(PACKAGE <PackageName>)
5593 Store the current build directory in the CMake user package registry
5595 for package <PackageName>. The find_package() command may consider the
5596 directory while searching for package <PackageName>. This helps depen‐
5597 dent projects find and use a package from the current project’s build
5598 tree without help from the user. Note that the entry in the package
5599 registry that this command creates works only in conjunction with a
5600 package configuration file (<PackageName>Config.cmake) that works with
5601 the build tree. In some cases, for example for packaging and for system
5602 wide installations, it is not desirable to write the user package reg‐
5603 istry.
5604 By default the export(PACKAGE) command does nothing (see policy
5606 CMP0090) because populating the user package registry has effects out‐
5607 side the source and build trees. Set the CMAKE_EXPORT_PACKAGE_REGISTRY
5608 variable to add build directories to the CMake user package registry.
5609 export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
5611 This signature exports cmake built targets to the android ndk build
5613 system by creating an Android.mk file that references the prebuilt tar‐
5614 gets. The Android NDK supports the use of prebuilt libraries, both
5615 static and shared. This allows cmake to build the libraries of a
5616 project and make them available to an ndk build system complete with
5617 transitive dependencies, include flags and defines required to use the
5618 libraries. The signature takes a list of targets and puts them in the
5619 Android.mk file specified by the <filename> given. This signature can
5620 only be used if policy CMP0022 is NEW for all targets given. A error
5621 will be issued if that policy is set to OLD for one of the targets.
5622 fltk_wrap_ui
5624 Create FLTK user interfaces Wrappers.
5625 fltk_wrap_ui(resultingLibraryName source1
5627 source2 ... sourceN )
5628 Produce .h and .cxx files for all the .fl and .fld files listed. The
5630 resulting .h and .cxx files will be added to a variable named result‐
5631 ingLibraryName_FLTK_UI_SRCS which should be added to your library.
5632 get_source_file_property
5634 Get a property for a source file.
5635 get_source_file_property(VAR file property)
5637 Gets a property from a source file. The value of the property is
5639 stored in the variable VAR. If the source property is not found, the
5640 behavior depends on whether it has been defined to be an INHERITED
5641 property or not (see define_property()). Non-inherited properties will
5642 set VAR to “NOTFOUND”, whereas inherited properties will search the
5643 relevant parent scope as described for the define_property() command
5644 and if still unable to find the property, VAR will be set to an empty
5645 string.
5646 Use set_source_files_properties() to set property values. Source file
5648 properties usually control how the file is built. One property that is
5649 always there is LOCATION.
5650 See also the more general get_property() command.
5652 get_target_property
5654 Get a property from a target.
5655 get_target_property(VAR target property)
5657 Get a property from a target. The value of the property is stored in
5659 the variable VAR. If the target property is not found, the behavior
5660 depends on whether it has been defined to be an INHERITED property or
5661 not (see define_property()). Non-inherited properties will set VAR to
5662 NOTFOUND, whereas inherited properties will search the relevant parent
5663 scope as described for the define_property() command and if still
5664 unable to find the property, VAR will be set to an empty string.
5665 Use set_target_properties() to set target property values. Properties
5667 are usually used to control how a target is built, but some query the
5668 target instead. This command can get properties for any target so far
5669 created. The targets do not need to be in the current CMakeLists.txt
5670 file.
5671 See also the more general get_property() command.
5673 See Target Properties for the list of properties known to CMake.
5675 get_test_property
5677 Get a property of the test.
5678 get_test_property(test property VAR)
5680 Get a property from the test. The value of the property is stored in
5682 the variable VAR. If the test property is not found, the behavior
5683 depends on whether it has been defined to be an INHERITED property or
5684 not (see define_property()). Non-inherited properties will set VAR to
5685 “NOTFOUND”, whereas inherited properties will search the relevant par‐
5686 ent scope as described for the define_property() command and if still
5687 unable to find the property, VAR will be set to an empty string.
5688 For a list of standard properties you can type cmake --help-prop‐
5690 erty-list.
5691 See also the more general get_property() command.
5693 include_directories
5695 Add include directories to the build.
5696 include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])
5698 Add the given directories to those the compiler uses to search for
5700 include files. Relative paths are interpreted as relative to the cur‐
5701 rent source directory.
5702 The include directories are added to the INCLUDE_DIRECTORIES directory
5704 property for the current CMakeLists file. They are also added to the
5705 INCLUDE_DIRECTORIES target property for each target in the current
5706 CMakeLists file. The target property values are the ones used by the
5707 generators.
5708 By default the directories specified are appended onto the current list
5710 of directories. This default behavior can be changed by setting
5711 CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE
5712 explicitly, you can select between appending and prepending, indepen‐
5713 dent of the default.
5714 If the SYSTEM option is given, the compiler will be told the directo‐
5716 ries are meant as system include directories on some platforms. Sig‐
5717 nalling this setting might achieve effects such as the compiler skip‐
5718 ping warnings, or these fixed-install system files not being considered
5719 in dependency calculations - see compiler docs.
5720 Arguments to include_directories may use “generator expressions” with
5722 the syntax “$<…>”. See the cmake-generator-expressions(7) manual for
5723 available expressions. See the cmake-buildsystem(7) manual for more on
5724 defining buildsystem properties.
5725 NOTE:
5727 Prefer the target_include_directories() command to add include
5728 directories to individual targets and optionally propagate/export
5729 them to dependents.
5730 include_external_msproject
5732 Include an external Microsoft project file in a workspace.
5733 include_external_msproject(projectname location
5735 [TYPE projectTypeGUID]
5736 [GUID projectGUID]
5737 [PLATFORM platformName]
5738 dep1 dep2 ...)
5739 Includes an external Microsoft project in the generated workspace file.
5741 Currently does nothing on UNIX. This will create a target named [pro‐
5742 jectname]. This can be used in the add_dependencies() command to make
5743 things depend on the external project.
5744 TYPE, GUID and PLATFORM are optional parameters that allow one to spec‐
5746 ify the type of project, id (GUID) of the project and the name of the
5747 target platform. This is useful for projects requiring values other
5748 than the default (e.g. WIX projects).
5749 If the imported project has different configuration names than the cur‐
5751 rent project, set the MAP_IMPORTED_CONFIG_<CONFIG> target property to
5752 specify the mapping.
5753 include_regular_expression
5755 Set the regular expression used for dependency checking.
5756 include_regular_expression(regex_match [regex_complain])
5758 Sets the regular expressions used in dependency checking. Only files
5760 matching regex_match will be traced as dependencies. Only files match‐
5761 ing regex_complain will generate warnings if they cannot be found
5762 (standard header paths are not searched). The defaults are:
5763 regex_match = "^.*$" (match everything)
5765 regex_complain = "^$" (match empty string only)
5766 install
5768 Specify rules to run at install time.
5769 Synopsis
5771 install(TARGETS <target>... [...])
5772 install({FILES | PROGRAMS} <file>... [...])
5773 install(DIRECTORY <dir>... [...])
5774 install(SCRIPT <file> [...])
5775 install(CODE <code> [...])
5776 install(EXPORT <export-name> [...])
5777 Introduction
5779 This command generates installation rules for a project. Rules speci‐
5780 fied by calls to this command within a source directory are executed in
5781 order during installation. The order across directories is not
5782 defined.
5783 There are multiple signatures for this command. Some of them define
5785 installation options for files and targets. Options common to multiple
5786 signatures are covered here but they are valid only for signatures that
5787 specify them. The common options are:
5788 DESTINATION
5790 Specify the directory on disk to which a file will be installed.
5791 If a full path (with a leading slash or drive letter) is given
5792 it is used directly. If a relative path is given it is inter‐
5793 preted relative to the value of the CMAKE_INSTALL_PREFIX vari‐
5794 able. The prefix can be relocated at install time using the
5795 DESTDIR mechanism explained in the CMAKE_INSTALL_PREFIX variable
5796 documentation.
5797 PERMISSIONS
5799 Specify permissions for installed files. Valid permissions are
5800 OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE,
5801 GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID,
5802 and SETGID. Permissions that do not make sense on certain plat‐
5803 forms are ignored on those platforms.
5804 CONFIGURATIONS
5806 Specify a list of build configurations for which the install
5807 rule applies (Debug, Release, etc.). Note that the values speci‐
5808 fied for this option only apply to options listed AFTER the CON‐
5809 FIGURATIONS option. For example, to set separate install paths
5810 for the Debug and Release configurations, do the following:
5811 install(TARGETS target
5813 CONFIGURATIONS Debug
5814 RUNTIME DESTINATION Debug/bin)
5815 install(TARGETS target
5816 CONFIGURATIONS Release
5817 RUNTIME DESTINATION Release/bin)
5818 Note that CONFIGURATIONS appears BEFORE RUNTIME DESTINATION.
5820 COMPONENT
5822 Specify an installation component name with which the install
5823 rule is associated, such as “runtime” or “development”. During
5824 component-specific installation only install rules associated
5825 with the given component name will be executed. During a full
5826 installation all components are installed unless marked with
5827 EXCLUDE_FROM_ALL. If COMPONENT is not provided a default compo‐
5828 nent “Unspecified” is created. The default component name may
5829 be controlled with the CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
5830 variable.
5831 EXCLUDE_FROM_ALL
5833 Specify that the file is excluded from a full installation and
5834 only installed as part of a component-specific installation
5835 RENAME Specify a name for an installed file that may be different from
5837 the original file. Renaming is allowed only when a single file
5838 is installed by the command.
5839 OPTIONAL
5841 Specify that it is not an error if the file to be installed does
5842 not exist.
5843 Command signatures that install files may print messages during instal‐
5845 lation. Use the CMAKE_INSTALL_MESSAGE variable to control which mes‐
5846 sages are printed.
5847 Many of the install() variants implicitly create the directories con‐
5849 taining the installed files. If CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMIS‐
5850 SIONS is set, these directories will be created with the permissions
5851 specified. Otherwise, they will be created according to the uname rules
5852 on Unix-like platforms. Windows platforms are unaffected.
5853 Installing Targets
5855 install(TARGETS targets... [EXPORT <export-name>]
5856 [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
5857 PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
5858 [DESTINATION <dir>]
5859 [PERMISSIONS permissions...]
5860 [CONFIGURATIONS [Debug|Release|...]]
5861 [COMPONENT <component>]
5862 [NAMELINK_COMPONENT <component>]
5863 [OPTIONAL] [EXCLUDE_FROM_ALL]
5864 [NAMELINK_ONLY|NAMELINK_SKIP]
5865 ] [...]
5866 [INCLUDES DESTINATION [<dir> ...]]
5867 )
5868 The TARGETS form specifies rules for installing targets from a project.
5870 There are several kinds of target files that may be installed:
5871 ARCHIVE
5873 Static libraries are treated as ARCHIVE targets, except those
5874 marked with the FRAMEWORK property on macOS (see FRAMEWORK
5875 below.) For DLL platforms (all Windows-based systems including
5876 Cygwin), the DLL import library is treated as an ARCHIVE target.
5877 On AIX, the linker import file created for executables with
5878 ENABLE_EXPORTS is treated as an ARCHIVE target.
5879 LIBRARY
5881 Module libraries are always treated as LIBRARY targets. For non-
5882 DLL platforms shared libraries are treated as LIBRARY targets,
5883 except those marked with the FRAMEWORK property on macOS (see
5884 FRAMEWORK below.)
5885 RUNTIME
5887 Executables are treated as RUNTIME objects, except those marked
5888 with the MACOSX_BUNDLE property on macOS (see BUNDLE below.)
5889 For DLL platforms (all Windows-based systems including Cygwin),
5890 the DLL part of a shared library is treated as a RUNTIME target.
5891 OBJECTS
5893 Object libraries (a simple group of object files) are always
5894 treated as OBJECTS targets.
5895 FRAMEWORK
5897 Both static and shared libraries marked with the FRAMEWORK prop‐
5898 erty are treated as FRAMEWORK targets on macOS.
5899 BUNDLE Executables marked with the MACOSX_BUNDLE property are treated
5901 as BUNDLE targets on macOS.
5902 PUBLIC_HEADER
5904 Any PUBLIC_HEADER files associated with a library are installed
5905 in the destination specified by the PUBLIC_HEADER argument on
5906 non-Apple platforms. Rules defined by this argument are ignored
5907 for FRAMEWORK libraries on Apple platforms because the associ‐
5908 ated files are installed into the appropriate locations inside
5909 the framework folder. See PUBLIC_HEADER for details.
5910 PRIVATE_HEADER
5912 Similar to PUBLIC_HEADER, but for PRIVATE_HEADER files. See PRI‐
5913 VATE_HEADER for details.
5914 RESOURCE
5916 Similar to PUBLIC_HEADER and PRIVATE_HEADER, but for RESOURCE
5917 files. See RESOURCE for details.
5918 For each of these arguments given, the arguments following them only
5920 apply to the target or file type specified in the argument. If none is
5921 given, the installation properties apply to all target types. If only
5922 one is given then only targets of that type will be installed (which
5923 can be used to install just a DLL or just an import library.)
5924 For regular executables, static libraries and shared libraries, the
5926 DESTINATION argument is not required. For these target types, when
5927 DESTINATION is omitted, a default destination will be taken from the
5928 appropriate variable from GNUInstallDirs, or set to a built-in default
5929 value if that variable is not defined. The same is true for the public
5930 and private headers associated with the installed targets through the
5931 PUBLIC_HEADER and PRIVATE_HEADER target properties. A destination must
5932 always be provided for module libraries, Apple bundles and frameworks.
5933 A destination can be omitted for interface and object libraries, but
5934 they are handled differently (see the discussion of this topic toward
5935 the end of this section).
5936 The following table shows the target types with their associated vari‐
5938 ables and built-in defaults that apply when no destination is given:
5939 ┌───────────────┬─────────────────────────────┬──────────────────┐
5941 │Target Type │ GNUInstallDirs │ Built-In Default │
5942 │ │ Variable │ │
5943 ├───────────────┼─────────────────────────────┼──────────────────┤
5944 │RUNTIME │ ${CMAKE_INSTALL_BINDIR} │ bin │
5945 ├───────────────┼─────────────────────────────┼──────────────────┤
5946 │LIBRARY │ ${CMAKE_INSTALL_LIBDIR} │ lib │
5947 └───────────────┴─────────────────────────────┴──────────────────┘
5948 │ARCHIVE │ ${CMAKE_INSTALL_LIBDIR} │ lib │
5950 ├───────────────┼─────────────────────────────┼──────────────────┤
5951 │PRIVATE_HEADER │ ${CMAKE_INSTALL_INCLUDEDIR} │ include │
5952 ├───────────────┼─────────────────────────────┼──────────────────┤
5953 │PUBLIC_HEADER │ ${CMAKE_INSTALL_INCLUDEDIR} │ include │
5954 └───────────────┴─────────────────────────────┴──────────────────┘
5955 Projects wishing to follow the common practice of installing headers
5957 into a project-specific subdirectory will need to provide a destination
5958 rather than rely on the above.
5959 To make packages compliant with distribution filesystem layout poli‐
5961 cies, if projects must specify a DESTINATION, it is recommended that
5962 they use a path that begins with the appropriate GNUInstallDirs vari‐
5963 able. This allows package maintainers to control the install destina‐
5964 tion by setting the appropriate cache variables. The following example
5965 shows a static library being installed to the default destination pro‐
5966 vided by GNUInstallDirs, but with its headers installed to a
5967 project-specific subdirectory that follows the above recommendation:
5968 add_library(mylib STATIC ...)
5970 set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
5971 include(GNUInstallDirs)
5972 install(TARGETS mylib
5973 PUBLIC_HEADER
5974 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
5975 )
5976 In addition to the common options listed above, each target can accept
5978 the following additional arguments:
5979 NAMELINK_COMPONENT
5981 On some platforms a versioned shared library has a symbolic link
5982 such as:
5983 lib<name>.so -> lib<name>.so.1
5985 where lib<name>.so.1 is the soname of the library and
5987 lib<name>.so is a “namelink” allowing linkers to find the
5988 library when given -l<name>. The NAMELINK_COMPONENT option is
5989 similar to the COMPONENT option, but it changes the installation
5990 component of a shared library namelink if one is generated. If
5991 not specified, this defaults to the value of COMPONENT. It is an
5992 error to use this parameter outside of a LIBRARY block.
5993 Consider the following example:
5995 install(TARGETS mylib
5997 LIBRARY
5998 COMPONENT Libraries
5999 NAMELINK_COMPONENT Development
6000 PUBLIC_HEADER
6001 COMPONENT Development
6002 )
6003 In this scenario, if you choose to install only the Development
6005 component, both the headers and namelink will be installed with‐
6006 out the library. (If you don’t also install the Libraries compo‐
6007 nent, the namelink will be a dangling symlink, and projects that
6008 link to the library will have build errors.) If you install only
6009 the Libraries component, only the library will be installed,
6010 without the headers and namelink.
6011 This option is typically used for package managers that have
6013 separate runtime and development packages. For example, on
6014 Debian systems, the library is expected to be in the runtime
6015 package, and the headers and namelink are expected to be in the
6016 development package.
6017 See the VERSION and SOVERSION target properties for details on
6019 creating versioned shared libraries.
6020 NAMELINK_ONLY
6022 This option causes the installation of only the namelink when a
6023 library target is installed. On platforms where versioned shared
6024 libraries do not have namelinks or when a library is not ver‐
6025 sioned, the NAMELINK_ONLY option installs nothing. It is an
6026 error to use this parameter outside of a LIBRARY block.
6027 When NAMELINK_ONLY is given, either NAMELINK_COMPONENT or COMPO‐
6029 NENT may be used to specify the installation component of the
6030 namelink, but COMPONENT should generally be preferred.
6031 NAMELINK_SKIP
6033 Similar to NAMELINK_ONLY, but it has the opposite effect: it
6034 causes the installation of library files other than the namelink
6035 when a library target is installed. When neither NAMELINK_ONLY
6036 or NAMELINK_SKIP are given, both portions are installed. On
6037 platforms where versioned shared libraries do not have symlinks
6038 or when a library is not versioned, NAMELINK_SKIP installs the
6039 library. It is an error to use this parameter outside of a
6040 LIBRARY block.
6041 If NAMELINK_SKIP is specified, NAMELINK_COMPONENT has no effect.
6043 It is not recommended to use NAMELINK_SKIP in conjunction with
6044 NAMELINK_COMPONENT.
6045 The install(TARGETS) command can also accept the following options at
6047 the top level:
6048 EXPORT This option associates the installed target files with an export
6050 called <export-name>. It must appear before any target options.
6051 To actually install the export file itself, call
6052 install(EXPORT), documented below. See documentation of the
6053 EXPORT_NAME target property to change the name of the exported
6054 target.
6055 INCLUDES DESTINATION
6057 This option specifies a list of directories which will be added
6058 to the INTERFACE_INCLUDE_DIRECTORIES target property of the
6059 <targets> when exported by the install(EXPORT) command. If a
6060 relative path is specified, it is treated as relative to the
6061 $<INSTALL_PREFIX>.
6062 One or more groups of properties may be specified in a single call to
6064 the TARGETS form of this command. A target may be installed more than
6065 once to different locations. Consider hypothetical targets myExe,
6066 mySharedLib, and myStaticLib. The code:
6067 install(TARGETS myExe mySharedLib myStaticLib
6069 RUNTIME DESTINATION bin
6070 LIBRARY DESTINATION lib
6071 ARCHIVE DESTINATION lib/static)
6072 install(TARGETS mySharedLib DESTINATION /some/full/path)
6073 will install myExe to <prefix>/bin and myStaticLib to <pre‐
6075 fix>/lib/static. On non-DLL platforms mySharedLib will be installed to
6076 <prefix>/lib and /some/full/path. On DLL platforms the mySharedLib DLL
6077 will be installed to <prefix>/bin and /some/full/path and its import
6078 library will be installed to <prefix>/lib/static and /some/full/path.
6079 Interface Libraries may be listed among the targets to install. They
6081 install no artifacts but will be included in an associated EXPORT. If
6082 Object Libraries are listed but given no destination for their object
6083 files, they will be exported as Interface Libraries. This is suffi‐
6084 cient to satisfy transitive usage requirements of other targets that
6085 link to the object libraries in their implementation.
6086 Installing a target with the EXCLUDE_FROM_ALL target property set to
6088 TRUE has undefined behavior.
6089 install(TARGETS) can install targets that were created in other direc‐
6091 tories. When using such cross-directory install rules, running make
6092 install (or similar) from a subdirectory will not guarantee that tar‐
6093 gets from other directories are up-to-date. You can use tar‐
6094 get_link_libraries() or add_dependencies() to ensure that such
6095 out-of-directory targets are built before the subdirectory-specific
6096 install rules are run.
6097 An install destination given as a DESTINATION argument may use “genera‐
6099 tor expressions” with the syntax $<...>. See the cmake-genera‐
6100 tor-expressions(7) manual for available expressions.
6101 Installing Files
6103 install(<FILES|PROGRAMS> files...
6104 TYPE <type> | DESTINATION <dir>
6105 [PERMISSIONS permissions...]
6106 [CONFIGURATIONS [Debug|Release|...]]
6107 [COMPONENT <component>]
6108 [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
6109 The FILES form specifies rules for installing files for a project.
6111 File names given as relative paths are interpreted with respect to the
6112 current source directory. Files installed by this form are by default
6113 given permissions OWNER_WRITE, OWNER_READ, GROUP_READ, and WORLD_READ
6114 if no PERMISSIONS argument is given.
6115 The PROGRAMS form is identical to the FILES form except that the
6117 default permissions for the installed file also include OWNER_EXECUTE,
6118 GROUP_EXECUTE, and WORLD_EXECUTE. This form is intended to install
6119 programs that are not targets, such as shell scripts. Use the TARGETS
6120 form to install targets built within the project.
6121 The list of files... given to FILES or PROGRAMS may use “generator
6123 expressions” with the syntax $<...>. See the cmake-generator-expres‐
6124 sions(7) manual for available expressions. However, if any item begins
6125 in a generator expression it must evaluate to a full path.
6126 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
6128 argument specifies the generic file type of the files being installed.
6129 A destination will then be set automatically by taking the correspond‐
6130 ing variable from GNUInstallDirs, or by using a built-in default if
6131 that variable is not defined. See the table below for the supported
6132 file types and their corresponding variables and built-in defaults.
6133 Projects can provide a DESTINATION argument instead of a file type if
6134 they wish to explicitly define the install destination.
6135 ┌──────────────┬─────────────────────────────┬─────────────────────┐
6137 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
6138 │ │ Variable │ │
6139 ├──────────────┼─────────────────────────────┼─────────────────────┤
6140 │BIN │ ${CMAKE_INSTALL_BINDIR} │ bin │
6141 ├──────────────┼─────────────────────────────┼─────────────────────┤
6142 │SBIN │ ${CMAKE_INSTALL_SBINDIR} │ sbin │
6143 ├──────────────┼─────────────────────────────┼─────────────────────┤
6144 │LIB │ ${CMAKE_INSTALL_LIBDIR} │ lib │
6145 ├──────────────┼─────────────────────────────┼─────────────────────┤
6146 │INCLUDE │ ${CMAKE_INSTALL_INCLUDEDIR} │ include │
6147 ├──────────────┼─────────────────────────────┼─────────────────────┤
6148 │SYSCONF │ ${CMAKE_INSTALL_SYSCONFDIR} │ etc │
6149 ├──────────────┼─────────────────────────────┼─────────────────────┤
6150 │SHAREDSTATE │ ${CMAKE_INSTALL_SHARESTATE‐ │ com │
6151 │ │ DIR} │ │
6152 ├──────────────┼─────────────────────────────┼─────────────────────┤
6153 │LOCALSTATE │ ${CMAKE_INSTALL_LOCALSTATE‐ │ var │
6154 │ │ DIR} │ │
6155 ├──────────────┼─────────────────────────────┼─────────────────────┤
6156 │RUNSTATE │ ${CMAKE_INSTALL_RUNSTATE‐ │ <LOCALSTATE │
6157 │ │ DIR} │ dir>/run │
6158 ├──────────────┼─────────────────────────────┼─────────────────────┤
6159 │DATA │ ${CMAKE_INSTALL_DATADIR} │ <DATAROOT dir> │
6160 ├──────────────┼─────────────────────────────┼─────────────────────┤
6161 │INFO │ ${CMAKE_INSTALL_INFODIR} │ <DATAROOT dir>/info │
6162 ├──────────────┼─────────────────────────────┼─────────────────────┤
6163 │LOCALE │ ${CMAKE_INSTALL_LOCALEDIR} │ <DATAROOT │
6164 │ │ │ dir>/locale │
6165 ├──────────────┼─────────────────────────────┼─────────────────────┤
6166 │MAN │ ${CMAKE_INSTALL_MANDIR} │ <DATAROOT dir>/man │
6167 ├──────────────┼─────────────────────────────┼─────────────────────┤
6168 │DOC │ ${CMAKE_INSTALL_DOCDIR} │ <DATAROOT dir>/doc │
6169 └──────────────┴─────────────────────────────┴─────────────────────┘
6170 Projects wishing to follow the common practice of installing headers
6172 into a project-specific subdirectory will need to provide a destination
6173 rather than rely on the above.
6174 Note that some of the types’ built-in defaults use the DATAROOT direc‐
6176 tory as a prefix. The DATAROOT prefix is calculated similarly to the
6177 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
6178 built-in default. You cannot use DATAROOT as a TYPE parameter; please
6179 use DATA instead.
6180 To make packages compliant with distribution filesystem layout poli‐
6182 cies, if projects must specify a DESTINATION, it is recommended that
6183 they use a path that begins with the appropriate GNUInstallDirs vari‐
6184 able. This allows package maintainers to control the install destina‐
6185 tion by setting the appropriate cache variables. The following example
6186 shows how to follow this advice while installing headers to a
6187 project-specific subdirectory:
6188 include(GNUInstallDirs)
6190 install(FILES mylib.h
6191 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
6192 )
6193 An install destination given as a DESTINATION argument may use “genera‐
6195 tor expressions” with the syntax $<...>. See the cmake-genera‐
6196 tor-expressions(7) manual for available expressions.
6197 Installing Directories
6199 install(DIRECTORY dirs...
6200 TYPE <type> | DESTINATION <dir>
6201 [FILE_PERMISSIONS permissions...]
6202 [DIRECTORY_PERMISSIONS permissions...]
6203 [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
6204 [CONFIGURATIONS [Debug|Release|...]]
6205 [COMPONENT <component>] [EXCLUDE_FROM_ALL]
6206 [FILES_MATCHING]
6207 [[PATTERN <pattern> | REGEX <regex>]
6208 [EXCLUDE] [PERMISSIONS permissions...]] [...])
6209 The DIRECTORY form installs contents of one or more directories to a
6211 given destination. The directory structure is copied verbatim to the
6212 destination. The last component of each directory name is appended to
6213 the destination directory but a trailing slash may be used to avoid
6214 this because it leaves the last component empty. Directory names given
6215 as relative paths are interpreted with respect to the current source
6216 directory. If no input directory names are given the destination
6217 directory will be created but nothing will be installed into it. The
6218 FILE_PERMISSIONS and DIRECTORY_PERMISSIONS options specify permissions
6219 given to files and directories in the destination. If USE_SOURCE_PER‐
6220 MISSIONS is specified and FILE_PERMISSIONS is not, file permissions
6221 will be copied from the source directory structure. If no permissions
6222 are specified files will be given the default permissions specified in
6223 the FILES form of the command, and the directories will be given the
6224 default permissions specified in the PROGRAMS form of the command.
6225 The MESSAGE_NEVER option disables file installation status output.
6227 Installation of directories may be controlled with fine granularity
6229 using the PATTERN or REGEX options. These “match” options specify a
6230 globbing pattern or regular expression to match directories or files
6231 encountered within input directories. They may be used to apply cer‐
6232 tain options (see below) to a subset of the files and directories
6233 encountered. The full path to each input file or directory (with for‐
6234 ward slashes) is matched against the expression. A PATTERN will match
6235 only complete file names: the portion of the full path matching the
6236 pattern must occur at the end of the file name and be preceded by a
6237 slash. A REGEX will match any portion of the full path but it may use
6238 / and $ to simulate the PATTERN behavior. By default all files and
6239 directories are installed whether or not they are matched. The
6240 FILES_MATCHING option may be given before the first match option to
6241 disable installation of files (but not directories) not matched by any
6242 expression. For example, the code
6243 install(DIRECTORY src/ DESTINATION include/myproj
6245 FILES_MATCHING PATTERN "*.h")
6246 will extract and install header files from a source tree.
6248 Some options may follow a PATTERN or REGEX expression and are applied
6250 only to files or directories matching them. The EXCLUDE option will
6251 skip the matched file or directory. The PERMISSIONS option overrides
6252 the permissions setting for the matched file or directory. For example
6253 the code
6254 install(DIRECTORY icons scripts/ DESTINATION share/myproj
6256 PATTERN "CVS" EXCLUDE
6257 PATTERN "scripts/*"
6258 PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
6259 GROUP_EXECUTE GROUP_READ)
6260 will install the icons directory to share/myproj/icons and the scripts
6262 directory to share/myproj. The icons will get default file permis‐
6263 sions, the scripts will be given specific permissions, and any CVS
6264 directories will be excluded.
6265 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
6267 argument specifies the generic file type of the files within the listed
6268 directories being installed. A destination will then be set automati‐
6269 cally by taking the corresponding variable from GNUInstallDirs, or by
6270 using a built-in default if that variable is not defined. See the ta‐
6271 ble below for the supported file types and their corresponding vari‐
6272 ables and built-in defaults. Projects can provide a DESTINATION argu‐
6273 ment instead of a file type if they wish to explicitly define the
6274 install destination.
6275 ┌──────────────┬─────────────────────────────┬─────────────────────┐
6277 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
6278 │ │ Variable │ │
6279 ├──────────────┼─────────────────────────────┼─────────────────────┤
6280 │BIN │ ${CMAKE_INSTALL_BINDIR} │ bin │
6281 ├──────────────┼─────────────────────────────┼─────────────────────┤
6282 │SBIN │ ${CMAKE_INSTALL_SBINDIR} │ sbin │
6283 ├──────────────┼─────────────────────────────┼─────────────────────┤
6284 │LIB │ ${CMAKE_INSTALL_LIBDIR} │ lib │
6285 ├──────────────┼─────────────────────────────┼─────────────────────┤
6286 │INCLUDE │ ${CMAKE_INSTALL_INCLUDEDIR} │ include │
6287 ├──────────────┼─────────────────────────────┼─────────────────────┤
6288 │SYSCONF │ ${CMAKE_INSTALL_SYSCONFDIR} │ etc │
6289 └──────────────┴─────────────────────────────┴─────────────────────┘
6290 │SHAREDSTATE │ ${CMAKE_INSTALL_SHARESTATE‐ │ com │
6294 │ │ DIR} │ │
6295 ├──────────────┼─────────────────────────────┼─────────────────────┤
6296 │LOCALSTATE │ ${CMAKE_INSTALL_LOCALSTATE‐ │ var │
6297 │ │ DIR} │ │
6298 ├──────────────┼─────────────────────────────┼─────────────────────┤
6299 │RUNSTATE │ ${CMAKE_INSTALL_RUNSTATE‐ │ <LOCALSTATE │
6300 │ │ DIR} │ dir>/run │
6301 ├──────────────┼─────────────────────────────┼─────────────────────┤
6302 │DATA │ ${CMAKE_INSTALL_DATADIR} │ <DATAROOT dir> │
6303 ├──────────────┼─────────────────────────────┼─────────────────────┤
6304 │INFO │ ${CMAKE_INSTALL_INFODIR} │ <DATAROOT dir>/info │
6305 ├──────────────┼─────────────────────────────┼─────────────────────┤
6306 │LOCALE │ ${CMAKE_INSTALL_LOCALEDIR} │ <DATAROOT │
6307 │ │ │ dir>/locale │
6308 ├──────────────┼─────────────────────────────┼─────────────────────┤
6309 │MAN │ ${CMAKE_INSTALL_MANDIR} │ <DATAROOT dir>/man │
6310 ├──────────────┼─────────────────────────────┼─────────────────────┤
6311 │DOC │ ${CMAKE_INSTALL_DOCDIR} │ <DATAROOT dir>/doc │
6312 └──────────────┴─────────────────────────────┴─────────────────────┘
6313 Note that some of the types’ built-in defaults use the DATAROOT direc‐
6315 tory as a prefix. The DATAROOT prefix is calculated similarly to the
6316 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
6317 built-in default. You cannot use DATAROOT as a TYPE parameter; please
6318 use DATA instead.
6319 To make packages compliant with distribution filesystem layout poli‐
6321 cies, if projects must specify a DESTINATION, it is recommended that
6322 they use a path that begins with the appropriate GNUInstallDirs vari‐
6323 able. This allows package maintainers to control the install destina‐
6324 tion by setting the appropriate cache variables.
6325 The list of dirs... given to DIRECTORY and an install destination given
6327 as a DESTINATION argument may use “generator expressions” with the syn‐
6328 tax $<...>. See the cmake-generator-expressions(7) manual for avail‐
6329 able expressions.
6330 Custom Installation Logic
6332 install([[SCRIPT <file>] [CODE <code>]]
6333 [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])
6334 The SCRIPT form will invoke the given CMake script files during instal‐
6336 lation. If the script file name is a relative path it will be inter‐
6337 preted with respect to the current source directory. The CODE form
6338 will invoke the given CMake code during installation. Code is speci‐
6339 fied as a single argument inside a double-quoted string. For example,
6340 the code
6341 install(CODE "MESSAGE(\"Sample install message.\")")
6343 will print a message during installation.
6345 <file> or <code> may use “generator expressions” with the syntax $<...>
6347 (in the case of <file>, this refers to their use in the file name, not
6348 the file’s contents). See the cmake-generator-expressions(7) manual
6349 for available expressions.
6350 Installing Exports
6352 install(EXPORT <export-name> DESTINATION <dir>
6353 [NAMESPACE <namespace>] [[FILE <name>.cmake]|
6354 [PERMISSIONS permissions...]
6355 [CONFIGURATIONS [Debug|Release|...]]
6356 [EXPORT_LINK_INTERFACE_LIBRARIES]
6357 [COMPONENT <component>]
6358 [EXCLUDE_FROM_ALL])
6359 install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])
6360 The EXPORT form generates and installs a CMake file containing code to
6362 import targets from the installation tree into another project. Target
6363 installations are associated with the export <export-name> using the
6364 EXPORT option of the install(TARGETS) signature documented above. The
6365 NAMESPACE option will prepend <namespace> to the target names as they
6366 are written to the import file. By default the generated file will be
6367 called <export-name>.cmake but the FILE option may be used to specify a
6368 different name. The value given to the FILE option must be a file name
6369 with the .cmake extension. If a CONFIGURATIONS option is given then
6370 the file will only be installed when one of the named configurations is
6371 installed. Additionally, the generated import file will reference only
6372 the matching target configurations. The EXPORT_LINK_INTER‐
6373 FACE_LIBRARIES keyword, if present, causes the contents of the proper‐
6374 ties matching (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be
6375 exported, when policy CMP0022 is NEW.
6376 When a COMPONENT option is given, the listed <component> implicitly
6378 depends on all components mentioned in the export set. The exported
6379 <name>.cmake file will require each of the exported components to be
6380 present in order for dependent projects to build properly. For example,
6381 a project may define components Runtime and Development, with shared
6382 libraries going into the Runtime component and static libraries and
6383 headers going into the Development component. The export set would also
6384 typically be part of the Development component, but it would export
6385 targets from both the Runtime and Development components. Therefore,
6386 the Runtime component would need to be installed if the Development
6387 component was installed, but not vice versa. If the Development compo‐
6388 nent was installed without the Runtime component, dependent projects
6389 that try to link against it would have build errors. Package managers,
6390 such as APT and RPM, typically handle this by listing the Runtime com‐
6391 ponent as a dependency of the Development component in the package
6392 metadata, ensuring that the library is always installed if the headers
6393 and CMake export file are present.
6394 In addition to cmake language files, the EXPORT_ANDROID_MK mode maybe
6396 used to specify an export to the android ndk build system. This mode
6397 accepts the same options as the normal export mode. The Android NDK
6398 supports the use of prebuilt libraries, both static and shared. This
6399 allows cmake to build the libraries of a project and make them avail‐
6400 able to an ndk build system complete with transitive dependencies,
6401 include flags and defines required to use the libraries.
6402 The EXPORT form is useful to help outside projects use targets built
6404 and installed by the current project. For example, the code
6405 install(TARGETS myexe EXPORT myproj DESTINATION bin)
6407 install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
6408 install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules)
6409 will install the executable myexe to <prefix>/bin and code to import it
6411 in the file <prefix>/lib/myproj/myproj.cmake and <pre‐
6412 fix>/share/ndk-modules/Android.mk. An outside project may load this
6413 file with the include command and reference the myexe executable from
6414 the installation tree using the imported target name mp_myexe as if the
6415 target were built in its own tree.
6416 NOTE:
6418 This command supercedes the install_targets() command and the
6419 PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT target properties. It
6420 also replaces the FILES forms of the install_files() and
6421 install_programs() commands. The processing order of these install
6422 rules relative to those generated by install_targets(),
6423 install_files(), and install_programs() commands is not defined.
6424 Generated Installation Script
6426 The install() command generates a file, cmake_install.cmake, inside the
6427 build directory, which is used internally by the generated install tar‐
6428 get and by CPack. You can also invoke this script manually with cmake
6429 -P. This script accepts several variables:
6430 COMPONENT
6432 Set this variable to install only a single CPack component as
6433 opposed to all of them. For example, if you only want to install
6434 the Development component, run cmake -DCOMPONENT=Development -P
6435 cmake_install.cmake.
6436 BUILD_TYPE
6438 Set this variable to change the build type if you are using a
6439 multi-config generator. For example, to install with the Debug
6440 configuration, run cmake -DBUILD_TYPE=Debug -P
6441 cmake_install.cmake.
6442 DESTDIR
6444 This is an environment variable rather than a CMake variable. It
6445 allows you to change the installation prefix on UNIX systems.
6446 See DESTDIR for details.
6447 link_directories
6449 Add directories in which the linker will look for libraries.
6450 link_directories([AFTER|BEFORE] directory1 [directory2 ...])
6452 Adds the paths in which the linker should search for libraries. Rela‐
6454 tive paths given to this command are interpreted as relative to the
6455 current source directory, see CMP0015.
6456 The directories are added to the LINK_DIRECTORIES directory property
6458 for the current CMakeLists.txt file, converting relative paths to abso‐
6459 lute as needed. The command will apply only to targets created after
6460 it is called.
6461 By default the directories specified are appended onto the current list
6463 of directories. This default behavior can be changed by setting
6464 CMAKE_LINK_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE explic‐
6465 itly, you can select between appending and prepending, independent of
6466 the default.
6467 Arguments to link_directories may use “generator expressions” with the
6469 syntax “$<…>”. See the cmake-generator-expressions(7) manual for
6470 available expressions. See the cmake-buildsystem(7) manual for more on
6471 defining buildsystem properties.
6472 NOTE:
6474 This command is rarely necessary and should be avoided where there
6475 are other choices. Prefer to pass full absolute paths to libraries
6476 where possible, since this ensures the correct library will always
6477 be linked. The find_library() command provides the full path, which
6478 can generally be used directly in calls to target_link_libraries().
6479 Situations where a library search path may be needed include:
6480 · Project generators like Xcode where the user can switch target
6482 architecture at build time, but a full path to a library cannot be
6483 used because it only provides one architecture (i.e. it is not a
6484 universal binary).
6485 · Libraries may themselves have other private library dependencies
6487 that expect to be found via RPATH mechanisms, but some linkers are
6488 not able to fully decode those paths (e.g. due to the presence of
6489 things like $ORIGIN).
6490 If a library search path must be provided, prefer to localize the
6492 effect where possible by using the target_link_directories() command
6493 rather than link_directories(). The target-specific command can
6494 also control how the search directories propagate to other dependent
6495 targets.
6496 link_libraries
6498 Link libraries to all targets added later.
6499 link_libraries([item1 [item2 [...]]]
6501 [[debug|optimized|general] <item>] ...)
6502 Specify libraries or flags to use when linking any targets created
6504 later in the current directory or below by commands such as add_exe‐
6505 cutable() or add_library(). See the target_link_libraries() command
6506 for meaning of arguments.
6507 NOTE:
6509 The target_link_libraries() command should be preferred whenever
6510 possible. Library dependencies are chained automatically, so direc‐
6511 tory-wide specification of link libraries is rarely needed.
6512 load_cache
6514 Load in the values from another project’s CMake cache.
6515 load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...)
6517 Reads the cache and store the requested entries in variables with their
6519 name prefixed with the given prefix. This only reads the values, and
6520 does not create entries in the local project’s cache.
6521 load_cache(pathToBuildDirectory [EXCLUDE entry1...]
6523 [INCLUDE_INTERNALS entry1...])
6524 Loads in the values from another cache and store them in the local
6526 project’s cache as internal entries. This is useful for a project that
6527 depends on another project built in a different tree. EXCLUDE option
6528 can be used to provide a list of entries to be excluded.
6529 INCLUDE_INTERNALS can be used to provide a list of internal entries to
6530 be included. Normally, no internal entries are brought in. Use of
6531 this form of the command is strongly discouraged, but it is provided
6532 for backward compatibility.
6533 project
6535 Set the name of the project.
6536 Synopsis
6538 project(<PROJECT-NAME> [<language-name>...])
6539 project(<PROJECT-NAME>
6540 [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
6541 [DESCRIPTION <project-description-string>]
6542 [HOMEPAGE_URL <url-string>]
6543 [LANGUAGES <language-name>...])
6544 Sets the name of the project, and stores it in the variable
6546 PROJECT_NAME. When called from the top-level CMakeLists.txt also stores
6547 the project name in the variable CMAKE_PROJECT_NAME.
6548 Also sets the variables
6550 · PROJECT_SOURCE_DIR, <PROJECT-NAME>_SOURCE_DIR
6552 · PROJECT_BINARY_DIR, <PROJECT-NAME>_BINARY_DIR
6554 Further variables are set by the optional arguments described in the
6556 following. If any of these arguments is not used, then the correspond‐
6557 ing variables are set to the empty string.
6558 Options
6560 The options are:
6561 VERSION <version>
6563 Optional; may not be used unless policy CMP0048 is set to NEW.
6564 Takes a <version> argument composed of non-negative integer com‐
6566 ponents, i.e. <major>[.<minor>[.<patch>[.<tweak>]]], and sets
6567 the variables
6568 · PROJECT_VERSION, <PROJECT-NAME>_VERSION
6570 · PROJECT_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MAJOR
6572 · PROJECT_VERSION_MINOR, <PROJECT-NAME>_VERSION_MINOR
6574 · PROJECT_VERSION_PATCH, <PROJECT-NAME>_VERSION_PATCH
6576 · PROJECT_VERSION_TWEAK, <PROJECT-NAME>_VERSION_TWEAK.
6578 When the project() command is called from the top-level CMake‐
6580 Lists.txt, then the version is also stored in the variable
6581 CMAKE_PROJECT_VERSION.
6582 DESCRIPTION <project-description-string>
6584 Optional. Sets the variables
6585 · PROJECT_DESCRIPTION, <PROJECT-NAME>_DESCRIPTION
6587 to <project-description-string>. It is recommended that this
6589 description is a relatively short string, usually no more than a
6590 few words.
6591 When the project() command is called from the top-level CMake‐
6593 Lists.txt, then the description is also stored in the variable
6594 CMAKE_PROJECT_DESCRIPTION.
6595 HOMEPAGE_URL <url-string>
6597 Optional. Sets the variables
6598 · PROJECT_HOMEPAGE_URL, <PROJECT-NAME>_HOMEPAGE_URL
6600 to <url-string>, which should be the canonical home URL for the
6602 project.
6603 When the project() command is called from the top-level CMake‐
6605 Lists.txt, then the URL also is stored in the variable
6606 CMAKE_PROJECT_HOMEPAGE_URL.
6607 LANGUAGES <language-name>...
6609 Optional. Can also be specified without LANGUAGES keyword per
6610 the first, short signature.
6611 Selects which programming languages are needed to build the
6613 project. Supported languages include C, CXX (i.e. C++), CUDA,
6614 OBJC (i.e. Objective-C), OBJCXX, Fortran, and ASM. By default C
6615 and CXX are enabled if no language options are given. Specify
6616 language NONE, or use the LANGUAGES keyword and list no lan‐
6617 guages, to skip enabling any languages.
6618 If enabling ASM, list it last so that CMake can check whether
6620 compilers for other languages like C work for assembly too.
6621 The variables set through the VERSION, DESCRIPTION and HOMEPAGE_URL
6623 options are intended for use as default values in package metadata and
6624 documentation.
6625 Code Injection
6627 If the CMAKE_PROJECT_INCLUDE_BEFORE or
6628 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE variables are set, the
6629 files they point to will be included as the first step of the project()
6630 command. If both are set, then CMAKE_PROJECT_INCLUDE_BEFORE will be
6631 included before CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE.
6632 If the CMAKE_PROJECT_INCLUDE or CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE
6634 variables are set, the files they point to will be included as the last
6635 step of the project() command. If both are set, then
6636 CMAKE_PROJECT_INCLUDE will be included before
6637 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE.
6638 Usage
6640 The top-level CMakeLists.txt file for a project must contain a literal,
6641 direct call to the project() command; loading one through the include()
6642 command is not sufficient. If no such call exists, CMake will issue a
6643 warning and pretend there is a project(Project) at the top to enable
6644 the default languages (C and CXX).
6645 NOTE:
6647 Call the project() command near the top of the top-level CMake‐
6648 Lists.txt, but after calling cmake_minimum_required(). It is impor‐
6649 tant to establish version and policy settings before invoking other
6650 commands whose behavior they may affect. See also policy CMP0000.
6651 remove_definitions
6653 Remove -D define flags added by add_definitions().
6654 remove_definitions(-DFOO -DBAR ...)
6656 Removes flags (added by add_definitions()) from the compiler command
6658 line for sources in the current directory and below.
6659 set_source_files_properties
6661 Source files can have properties that affect how they are built.
6662 set_source_files_properties([file1 [file2 [...]]]
6664 PROPERTIES prop1 value1
6665 [prop2 value2 [...]])
6666 Sets properties associated with source files using a key/value paired
6668 list.
6669 See also the set_property(SOURCE) command.
6671 See Source File Properties for the list of properties known to CMake.
6673 Source file properties are visible only to targets added in the same
6674 directory (CMakeLists.txt).
6675 set_target_properties
6677 Targets can have properties that affect how they are built.
6678 set_target_properties(target1 target2 ...
6680 PROPERTIES prop1 value1
6681 prop2 value2 ...)
6682 Sets properties on targets. The syntax for the command is to list all
6684 the targets you want to change, and then provide the values you want to
6685 set next. You can use any prop value pair you want and extract it
6686 later with the get_property() or get_target_property() command.
6687 See also the set_property(TARGET) command.
6689 See Target Properties for the list of properties known to CMake.
6691 set_tests_properties
6693 Set a property of the tests.
6694 set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
6696 Sets a property for the tests. If the test is not found, CMake will
6698 report an error. Generator expressions will be expanded the same as
6699 supported by the test’s add_test() call.
6700 See also the set_property(TEST) command.
6702 See Test Properties for the list of properties known to CMake.
6704 source_group
6706 Define a grouping for source files in IDE project generation. There
6707 are two different signatures to create source groups.
6708 source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
6710 source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...])
6711 Defines a group into which sources will be placed in project files.
6713 This is intended to set up file tabs in Visual Studio. The options
6714 are:
6715 TREE CMake will automatically detect, from <src> files paths, source
6717 groups it needs to create, to keep structure of source groups
6718 analogically to the actual files and directories structure in
6719 the project. Paths of <src> files will be cut to be relative to
6720 <root>.
6721 PREFIX Source group and files located directly in <root> path, will be
6723 placed in <prefix> source groups.
6724 FILES Any source file specified explicitly will be placed in group
6726 <name>. Relative paths are interpreted with respect to the cur‐
6727 rent source directory.
6728 REGULAR_EXPRESSION
6730 Any source file whose name matches the regular expression will
6731 be placed in group <name>.
6732 If a source file matches multiple groups, the last group that explic‐
6734 itly lists the file with FILES will be favored, if any. If no group
6735 explicitly lists the file, the last group whose regular expression
6736 matches the file will be favored.
6737 The <name> of the group and <prefix> argument may contain backslashes
6739 to specify subgroups:
6740 source_group(outer\\inner ...)
6742 source_group(TREE <root> PREFIX sources\\inc ...)
6743 For backwards compatibility, the short-hand signature
6745 source_group(<name> <regex>)
6747 is equivalent to
6749 source_group(<name> REGULAR_EXPRESSION <regex>)
6751 target_compile_definitions
6753 Add compile definitions to a target.
6754 target_compile_definitions(<target>
6756 <INTERFACE|PUBLIC|PRIVATE> [items1...]
6757 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6758 Specifies compile definitions to use when compiling a given <target>.
6760 The named <target> must have been created by a command such as add_exe‐
6761 cutable() or add_library() and must not be an ALIAS target.
6762 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6764 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
6765 late the COMPILE_DEFINITIONS property of <target>. PUBLIC and INTERFACE
6766 items will populate the INTERFACE_COMPILE_DEFINITIONS property of <tar‐
6767 get>. (IMPORTED targets only support INTERFACE items.) The following
6768 arguments specify compile definitions. Repeated calls for the same
6769 <target> append items in the order called.
6770 Arguments to target_compile_definitions may use “generator expressions”
6772 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6773 for available expressions. See the cmake-buildsystem(7) manual for
6774 more on defining buildsystem properties.
6775 Any leading -D on an item will be removed. Empty items are ignored.
6777 For example, the following are all equivalent:
6778 target_compile_definitions(foo PUBLIC FOO)
6780 target_compile_definitions(foo PUBLIC -DFOO) # -D removed
6781 target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
6782 target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
6783 target_compile_features
6785 Add expected compiler features to a target.
6786 target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
6788 Specifies compiler features required when compiling a given target. If
6790 the feature is not listed in the CMAKE_C_COMPILE_FEATURES,
6791 CMAKE_CUDA_COMPILE_FEATURES, or CMAKE_CXX_COMPILE_FEATURES variables,
6792 then an error will be reported by CMake. If the use of the feature
6793 requires an additional compiler flag, such as -std=gnu++11, the flag
6794 will be added automatically.
6795 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6797 scope of the features. PRIVATE and PUBLIC items will populate the COM‐
6798 PILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
6799 populate the INTERFACE_COMPILE_FEATURES property of <target>.
6800 (IMPORTED targets only support INTERFACE items.) Repeated calls for
6801 the same <target> append items.
6802 The named <target> must have been created by a command such as add_exe‐
6804 cutable() or add_library() and must not be an ALIAS target.
6805 Arguments to target_compile_features may use “generator expressions”
6807 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6808 for available expressions. See the cmake-compile-features(7) manual
6809 for information on compile features and a list of supported compilers.
6810 target_compile_options
6812 Add compile options to a target.
6813 target_compile_options(<target> [BEFORE]
6815 <INTERFACE|PUBLIC|PRIVATE> [items1...]
6816 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6817 Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
6819 properties. These options are used when compiling the given <target>,
6820 which must have been created by a command such as add_executable() or
6821 add_library() and must not be an ALIAS target.
6822 Arguments
6824 If BEFORE is specified, the content will be prepended to the property
6825 instead of being appended.
6826 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6828 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
6829 late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
6830 items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
6831 (IMPORTED targets only support INTERFACE items.) The following argu‐
6832 ments specify compile options. Repeated calls for the same <target>
6833 append items in the order called.
6834 Arguments to target_compile_options may use “generator expressions”
6836 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6837 for available expressions. See the cmake-buildsystem(7) manual for
6838 more on defining buildsystem properties.
6839 The final set of compile or link options used for a target is con‐
6841 structed by accumulating options from the current target and the usage
6842 requirements of its dependencies. The set of options is de-duplicated
6843 to avoid repetition. While beneficial for individual options, the
6844 de-duplication step can break up option groups. For example, -D A -D B
6845 becomes -D A B. One may specify a group of options using shell-like
6846 quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and
6847 the rest of the option string is parsed using the separate_arguments()
6848 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
6849 -D B.
6850 See Also
6852 This command can be used to add any options. However, for adding pre‐
6853 processor definitions and include directories it is recommended to use
6854 the more specific commands target_compile_definitions() and tar‐
6855 get_include_directories().
6856 For directory-wide settings, there is the command add_com‐
6858 pile_options().
6859 target_include_directories
6861 Add include directories to a target.
6862 target_include_directories(<target> [SYSTEM] [BEFORE]
6864 <INTERFACE|PUBLIC|PRIVATE> [items1...]
6865 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6866 Specifies include directories to use when compiling a given target.
6868 The named <target> must have been created by a command such as add_exe‐
6869 cutable() or add_library() and must not be an ALIAS target.
6870 If BEFORE is specified, the content will be prepended to the property
6872 instead of being appended.
6873 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6875 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
6876 late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTER‐
6877 FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
6878 <target>. (IMPORTED targets only support INTERFACE items.) The fol‐
6879 lowing arguments specify include directories.
6880 Specified include directories may be absolute paths or relative paths.
6882 Repeated calls for the same <target> append items in the order called.
6883 If SYSTEM is specified, the compiler will be told the directories are
6884 meant as system include directories on some platforms (signalling this
6885 setting might achieve effects such as the compiler skipping warnings,
6886 or these fixed-install system files not being considered in dependency
6887 calculations - see compiler docs). If SYSTEM is used together with
6888 PUBLIC or INTERFACE, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
6889 property will be populated with the specified directories.
6890 Arguments to target_include_directories may use “generator expressions”
6892 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6893 for available expressions. See the cmake-buildsystem(7) manual for
6894 more on defining buildsystem properties.
6895 Include directories usage requirements commonly differ between the
6897 build-tree and the install-tree. The BUILD_INTERFACE and
6898 INSTALL_INTERFACE generator expressions can be used to describe sepa‐
6899 rate usage requirements based on the usage location. Relative paths
6900 are allowed within the INSTALL_INTERFACE expression and are interpreted
6901 relative to the installation prefix. For example:
6902 target_include_directories(mylib PUBLIC
6904 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
6905 $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
6906 )
6907 Creating Relocatable Packages
6909 Note that it is not advisable to populate the INSTALL_INTERFACE of the
6910 INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
6911 include directories of dependencies. That would hard-code into
6912 installed packages the include directory paths for dependencies as
6913 found on the machine the package was made on.
6914 The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
6916 suitable for specifying the required include directories for headers
6917 provided with the target itself, not those provided by the transitive
6918 dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
6919 Those dependencies should themselves be targets that specify their own
6920 header locations in INTERFACE_INCLUDE_DIRECTORIES.
6921 See the Creating Relocatable Packages section of the cmake-packages(7)
6923 manual for discussion of additional care that must be taken when speci‐
6924 fying usage requirements while creating packages for redistribution.
6925 target_link_directories
6927 Add link directories to a target.
6928 target_link_directories(<target> [BEFORE]
6930 <INTERFACE|PUBLIC|PRIVATE> [items1...]
6931 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6932 Specifies the paths in which the linker should search for libraries
6934 when linking a given target. Each item can be an absolute or relative
6935 path, with the latter being interpreted as relative to the current
6936 source directory. These items will be added to the link command.
6937 The named <target> must have been created by a command such as add_exe‐
6939 cutable() or add_library() and must not be an ALIAS target.
6940 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6942 scope of the items that follow them. PRIVATE and PUBLIC items will
6943 populate the LINK_DIRECTORIES property of <target>. PUBLIC and INTER‐
6944 FACE items will populate the INTERFACE_LINK_DIRECTORIES property of
6945 <target> (IMPORTED targets only support INTERFACE items). Each item
6946 specifies a link directory and will be converted to an absolute path if
6947 necessary before adding it to the relevant property. Repeated calls
6948 for the same <target> append items in the order called.
6949 If BEFORE is specified, the content will be prepended to the relevant
6951 property instead of being appended.
6952 Arguments to target_link_directories may use “generator expressions”
6954 with the syntax $<...>. See the cmake-generator-expressions(7) manual
6955 for available expressions. See the cmake-buildsystem(7) manual for
6956 more on defining buildsystem properties.
6957 NOTE:
6959 This command is rarely necessary and should be avoided where there
6960 are other choices. Prefer to pass full absolute paths to libraries
6961 where possible, since this ensures the correct library will always
6962 be linked. The find_library() command provides the full path, which
6963 can generally be used directly in calls to target_link_libraries().
6964 Situations where a library search path may be needed include:
6965 · Project generators like Xcode where the user can switch target
6967 architecture at build time, but a full path to a library cannot be
6968 used because it only provides one architecture (i.e. it is not a
6969 universal binary).
6970 · Libraries may themselves have other private library dependencies
6972 that expect to be found via RPATH mechanisms, but some linkers are
6973 not able to fully decode those paths (e.g. due to the presence of
6974 things like $ORIGIN).
6975 target_link_libraries
6977 Specify libraries or flags to use when linking a given target and/or
6978 its dependents. Usage requirements from linked library targets will be
6979 propagated. Usage requirements of a target’s dependencies affect com‐
6980 pilation of its own sources.
6981 Overview
6983 This command has several signatures as detailed in subsections below.
6984 All of them have the general form
6985 target_link_libraries(<target> ... <item>... ...)
6987 The named <target> must have been created by a command such as add_exe‐
6989 cutable() or add_library() and must not be an ALIAS target. If policy
6990 CMP0079 is not set to NEW then the target must have been created in the
6991 current directory. Repeated calls for the same <target> append items
6992 in the order called.
6993 Each <item> may be:
6995 · A library target name: The generated link line will have the full
6997 path to the linkable library file associated with the target. The
6998 buildsystem will have a dependency to re-link <target> if the library
6999 file changes.
7000 The named target must be created by add_library() within the project
7002 or as an IMPORTED library. If it is created within the project an
7003 ordering dependency will automatically be added in the build system
7004 to make sure the named library target is up-to-date before the <tar‐
7005 get> links.
7006 If an imported library has the IMPORTED_NO_SONAME target property
7008 set, CMake may ask the linker to search for the library instead of
7009 using the full path (e.g. /usr/lib/libfoo.so becomes -lfoo).
7010 The full path to the target’s artifact will be quoted/escaped for the
7012 shell automatically.
7013 · A full path to a library file: The generated link line will normally
7015 preserve the full path to the file. The buildsystem will have a
7016 dependency to re-link <target> if the library file changes.
7017 There are some cases where CMake may ask the linker to search for the
7019 library (e.g. /usr/lib/libfoo.so becomes -lfoo), such as when a
7020 shared library is detected to have no SONAME field. See policy
7021 CMP0060 for discussion of another case.
7022 If the library file is in a macOS framework, the Headers directory of
7024 the framework will also be processed as a usage requirement. This
7025 has the same effect as passing the framework directory as an include
7026 directory.
7027 On Visual Studio Generators for VS 2010 and above, library files end‐
7029 ing in .targets will be treated as MSBuild targets files and imported
7030 into generated project files. This is not supported by other genera‐
7031 tors.
7032 The full path to the library file will be quoted/escaped for the
7034 shell automatically.
7035 · A plain library name: The generated link line will ask the linker to
7037 search for the library (e.g. foo becomes -lfoo or foo.lib).
7038 The library name/flag is treated as a command-line string fragment
7040 and will be used with no extra quoting or escaping.
7041 · A link flag: Item names starting with -, but not -l or -framework,
7043 are treated as linker flags. Note that such flags will be treated
7044 like any other library link item for purposes of transitive dependen‐
7045 cies, so they are generally safe to specify only as private link
7046 items that will not propagate to dependents.
7047 Link flags specified here are inserted into the link command in the
7049 same place as the link libraries. This might not be correct, depend‐
7050 ing on the linker. Use the LINK_OPTIONS target property or tar‐
7051 get_link_options() command to add link flags explicitly. The flags
7052 will then be placed at the toolchain-defined flag position in the
7053 link command.
7054 The link flag is treated as a command-line string fragment and will
7056 be used with no extra quoting or escaping.
7057 · A generator expression: A $<...> generator expression may evaluate to
7059 any of the above items or to a semicolon-separated list of them. If
7060 the ... contains any ; characters, e.g. after evaluation of a ${list}
7061 variable, be sure to use an explicitly quoted argument "$<...>" so
7062 that this command receives it as a single <item>.
7063 Additionally, a generator expression may be used as a fragment of any
7065 of the above items, e.g. foo$<1:_d>.
7066 Note that generator expressions will not be used in OLD handling of
7068 policy CMP0003 or policy CMP0004.
7069 · A debug, optimized, or general keyword immediately followed by
7071 another <item>. The item following such a keyword will be used only
7072 for the corresponding build configuration. The debug keyword corre‐
7073 sponds to the Debug configuration (or to configurations named in the
7074 DEBUG_CONFIGURATIONS global property if it is set). The optimized
7075 keyword corresponds to all other configurations. The general keyword
7076 corresponds to all configurations, and is purely optional. Higher
7077 granularity may be achieved for per-configuration rules by creating
7078 and linking to IMPORTED library targets. These keywords are inter‐
7079 preted immediately by this command and therefore have no special
7080 meaning when produced by a generator expression.
7081 Items containing ::, such as Foo::Bar, are assumed to be IMPORTED or
7083 ALIAS library target names and will cause an error if no such target
7084 exists. See policy CMP0028.
7085 See the cmake-buildsystem(7) manual for more on defining buildsystem
7087 properties.
7088 Libraries for a Target and/or its Dependents
7090 target_link_libraries(<target>
7091 <PRIVATE|PUBLIC|INTERFACE> <item>...
7092 [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
7093 The PUBLIC, PRIVATE and INTERFACE keywords can be used to specify both
7095 the link dependencies and the link interface in one command. Libraries
7096 and targets following PUBLIC are linked to, and are made part of the
7097 link interface. Libraries and targets following PRIVATE are linked to,
7098 but are not made part of the link interface. Libraries following
7099 INTERFACE are appended to the link interface and are not used for link‐
7100 ing <target>.
7101 Libraries for both a Target and its Dependents
7103 target_link_libraries(<target> <item>...)
7104 Library dependencies are transitive by default with this signature.
7106 When this target is linked into another target then the libraries
7107 linked to this target will appear on the link line for the other target
7108 too. This transitive “link interface” is stored in the INTER‐
7109 FACE_LINK_LIBRARIES target property and may be overridden by setting
7110 the property directly. When CMP0022 is not set to NEW, transitive
7111 linking is built in but may be overridden by the LINK_INTER‐
7112 FACE_LIBRARIES property. Calls to other signatures of this command may
7113 set the property making any libraries linked exclusively by this signa‐
7114 ture private.
7115 Libraries for a Target and/or its Dependents (Legacy)
7117 target_link_libraries(<target>
7118 <LINK_PRIVATE|LINK_PUBLIC> <lib>...
7119 [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
7120 The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both the
7122 link dependencies and the link interface in one command.
7123 This signature is for compatibility only. Prefer the PUBLIC or PRIVATE
7125 keywords instead.
7126 Libraries and targets following LINK_PUBLIC are linked to, and are made
7128 part of the INTERFACE_LINK_LIBRARIES. If policy CMP0022 is not NEW,
7129 they are also made part of the LINK_INTERFACE_LIBRARIES. Libraries and
7130 targets following LINK_PRIVATE are linked to, but are not made part of
7131 the INTERFACE_LINK_LIBRARIES (or LINK_INTERFACE_LIBRARIES).
7132 Libraries for Dependents Only (Legacy)
7134 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
7135 The LINK_INTERFACE_LIBRARIES mode appends the libraries to the INTER‐
7137 FACE_LINK_LIBRARIES target property instead of using them for linking.
7138 If policy CMP0022 is not NEW, then this mode also appends libraries to
7139 the LINK_INTERFACE_LIBRARIES and its per-configuration equivalent.
7140 This signature is for compatibility only. Prefer the INTERFACE mode
7142 instead.
7143 Libraries specified as debug are wrapped in a generator expression to
7145 correspond to debug builds. If policy CMP0022 is not NEW, the
7146 libraries are also appended to the LINK_INTERFACE_LIBRARIES_DEBUG prop‐
7147 erty (or to the properties corresponding to configurations listed in
7148 the DEBUG_CONFIGURATIONS global property if it is set). Libraries
7149 specified as optimized are appended to the INTERFACE_LINK_LIBRARIES
7150 property. If policy CMP0022 is not NEW, they are also appended to the
7151 LINK_INTERFACE_LIBRARIES property. Libraries specified as general (or
7152 without any keyword) are treated as if specified for both debug and
7153 optimized.
7154 Linking Object Libraries
7156 Object Libraries may be used as the <target> (first) argument of tar‐
7157 get_link_libraries to specify dependencies of their sources on other
7158 libraries. For example, the code
7159 add_library(A SHARED a.c)
7161 target_compile_definitions(A PUBLIC A)
7162 add_library(obj OBJECT obj.c)
7164 target_compile_definitions(obj PUBLIC OBJ)
7165 target_link_libraries(obj PUBLIC A)
7166 compiles obj.c with -DA -DOBJ and establishes usage requirements for
7168 obj that propagate to its dependents.
7169 Normal libraries and executables may link to Object Libraries to get
7171 their objects and usage requirements. Continuing the above example,
7172 the code
7173 add_library(B SHARED b.c)
7175 target_link_libraries(B PUBLIC obj)
7176 compiles b.c with -DA -DOBJ, creates shared library B with object files
7178 from b.c and obj.c, and links B to A. Furthermore, the code
7179 add_executable(main main.c)
7181 target_link_libraries(main B)
7182 compiles main.c with -DA -DOBJ and links executable main to B and A.
7184 The object library’s usage requirements are propagated transitively
7185 through B, but its object files are not.
7186 Object Libraries may “link” to other object libraries to get usage
7188 requirements, but since they do not have a link step nothing is done
7189 with their object files. Continuing from the above example, the code:
7190 add_library(obj2 OBJECT obj2.c)
7192 target_link_libraries(obj2 PUBLIC obj)
7193 add_executable(main2 main2.c)
7195 target_link_libraries(main2 obj2)
7196 compiles obj2.c with -DA -DOBJ, creates executable main2 with object
7198 files from main2.c and obj2.c, and links main2 to A.
7199 In other words, when Object Libraries appear in a target’s INTER‐
7201 FACE_LINK_LIBRARIES property they will be treated as Interface
7202 Libraries, but when they appear in a target’s LINK_LIBRARIES property
7203 their object files will be included in the link too.
7204 Cyclic Dependencies of Static Libraries
7206 The library dependency graph is normally acyclic (a DAG), but in the
7207 case of mutually-dependent STATIC libraries CMake allows the graph to
7208 contain cycles (strongly connected components). When another target
7209 links to one of the libraries, CMake repeats the entire connected com‐
7210 ponent. For example, the code
7211 add_library(A STATIC a.c)
7213 add_library(B STATIC b.c)
7214 target_link_libraries(A B)
7215 target_link_libraries(B A)
7216 add_executable(main main.c)
7217 target_link_libraries(main A)
7218 links main to A B A B. While one repetition is usually sufficient,
7220 pathological object file and symbol arrangements can require more. One
7221 may handle such cases by using the LINK_INTERFACE_MULTIPLICITY target
7222 property or by manually repeating the component in the last tar‐
7223 get_link_libraries call. However, if two archives are really so inter‐
7224 dependent they should probably be combined into a single archive, per‐
7225 haps by using Object Libraries.
7226 Creating Relocatable Packages
7228 Note that it is not advisable to populate the INTERFACE_LINK_LIBRARIES
7229 of a target with absolute paths to dependencies. That would hard-code
7230 into installed packages the library file paths for dependencies as
7231 found on the machine the package was made on.
7232 See the Creating Relocatable Packages section of the cmake-packages(7)
7234 manual for discussion of additional care that must be taken when speci‐
7235 fying usage requirements while creating packages for redistribution.
7236 target_link_options
7238 Add options to the link step for an executable, shared library or mod‐
7239 ule library target.
7240 target_link_options(<target> [BEFORE]
7242 <INTERFACE|PUBLIC|PRIVATE> [items1...]
7243 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
7244 The named <target> must have been created by a command such as add_exe‐
7246 cutable() or add_library() and must not be an ALIAS target.
7247 This command can be used to add any link options, but alternative com‐
7249 mands exist to add libraries (target_link_libraries() or
7250 link_libraries()). See documentation of the directory and target
7251 LINK_OPTIONS properties.
7252 NOTE:
7254 This command cannot be used to add options for static library tar‐
7255 gets, since they do not use a linker. To add archiver or MSVC
7256 librarian flags, see the STATIC_LIBRARY_OPTIONS target property.
7257 If BEFORE is specified, the content will be prepended to the property
7259 instead of being appended.
7260 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
7262 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
7263 late the LINK_OPTIONS property of <target>. PUBLIC and INTERFACE items
7264 will populate the INTERFACE_LINK_OPTIONS property of <target>.
7265 (IMPORTED targets only support INTERFACE items.) The following argu‐
7266 ments specify link options. Repeated calls for the same <target>
7267 append items in the order called.
7268 Arguments to target_link_options may use “generator expressions” with
7270 the syntax $<...>. See the cmake-generator-expressions(7) manual for
7271 available expressions. See the cmake-buildsystem(7) manual for more on
7272 defining buildsystem properties.
7273 The final set of compile or link options used for a target is con‐
7275 structed by accumulating options from the current target and the usage
7276 requirements of its dependencies. The set of options is de-duplicated
7277 to avoid repetition. While beneficial for individual options, the
7278 de-duplication step can break up option groups. For example, -D A -D B
7279 becomes -D A B. One may specify a group of options using shell-like
7280 quoting along with a SHELL: prefix. The SHELL: prefix is dropped, and
7281 the rest of the option string is parsed using the separate_arguments()
7282 UNIX_COMMAND mode. For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
7283 -D B.
7284 To pass options to the linker tool, each compiler driver has its own
7286 syntax. The LINKER: prefix and , separator can be used to specify, in
7287 a portable way, options to pass to the linker tool. LINKER: is replaced
7288 by the appropriate driver option and , by the appropriate driver sepa‐
7289 rator. The driver prefix and driver separator are given by the values
7290 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and CMAKE_<LANG>_LINKER_WRAP‐
7291 PER_FLAG_SEP variables.
7292 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
7294 Clang and -Wl,-z,defs for GNU GCC.
7295 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
7297 sion.
7298 The LINKER: prefix supports, as an alternative syntax, specification of
7300 arguments using the SHELL: prefix and space as separator. The previous
7301 example then becomes "LINKER:SHELL:-z defs".
7302 NOTE:
7304 Specifying the SHELL: prefix anywhere other than at the beginning of
7305 the LINKER: prefix is not supported.
7306 target_precompile_headers
7308 Add a list of header files to precompile.
7309 Precompiling header files can speed up compilation by creating a par‐
7311 tially processed version of some header files, and then using that ver‐
7312 sion during compilations rather than repeatedly parsing the original
7313 headers.
7314 Main Form
7316 target_precompile_headers(<target>
7317 <INTERFACE|PUBLIC|PRIVATE> [header1...]
7318 [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])
7319 The command adds header files to the PRECOMPILE_HEADERS and/or INTER‐
7321 FACE_PRECOMPILE_HEADERS target properties of <target>. The named <tar‐
7322 get> must have been created by a command such as add_executable() or
7323 add_library() and must not be an ALIAS target.
7324 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
7326 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
7327 late the PRECOMPILE_HEADERS property of <target>. PUBLIC and INTERFACE
7328 items will populate the INTERFACE_PRECOMPILE_HEADERS property of <tar‐
7329 get> (IMPORTED targets only support INTERFACE items). Repeated calls
7330 for the same <target> will append items in the order called.
7331 Projects should generally avoid using PUBLIC or INTERFACE for targets
7333 that will be exported, or they should at least use the $<BUILD_INTER‐
7334 FACE:...> generator expression to prevent precompile headers from
7335 appearing in an installed exported target. Consumers of a target
7336 should typically be in control of what precompile headers they use, not
7337 have precompile headers forced on them by the targets being consumed
7338 (since precompile headers are not typically usage requirements). A
7339 notable exception to this is where an interface library is created to
7340 define a commonly used set of precompile headers in one place and then
7341 other targets link to that interface library privately. In this case,
7342 the interface library exists specifically to propagate the precompile
7343 headers to its consumers and the consumer is effectively still in con‐
7344 trol, since it decides whether to link to the interface library or not.
7345 The list of header files is used to generate a header file named
7347 cmake_pch.h|xx which is used to generate the precompiled header file
7348 (.pch, .gch, .pchi) artifact. The cmake_pch.h|xx header file will be
7349 force included (-include for GCC, /FI for MSVC) to all source files, so
7350 sources do not need to have #include "pch.h".
7351 Header file names specified with angle brackets (e.g. <unordered_map>)
7353 or explicit double quotes (escaped for the cmake-language(7), e.g.
7354 [["other_header.h"]]) will be treated as is, and include directories
7355 must be available for the compiler to find them. Other header file
7356 names (e.g. project_header.h) are interpreted as being relative to the
7357 current source directory (e.g. CMAKE_CURRENT_SOURCE_DIR) and will be
7358 included by absolute path. For example:
7359 target_precompile_headers(myTarget
7361 PUBLIC
7362 project_header.h
7363 PRIVATE
7364 [["other_header.h"]]
7365 <unordered_map>
7366 )
7367 Arguments to target_precompile_headers() may use “generator expres‐
7369 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
7370 manual for available expressions. The $<COMPILE_LANGUAGE:...> genera‐
7371 tor expression is particularly useful for specifying a language-spe‐
7372 cific header to precompile for only one language (e.g. CXX and not C).
7373 In this case, header file names that are not explicitly in double
7374 quotes or angle brackets must be specified by absolute path. Also,
7375 when specifying angle brackets inside a generator expression, be sure
7376 to encode the closing > as $<ANGLE-R>. For example:
7377 target_precompile_headers(mylib PRIVATE
7379 "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/cxx_only.h>"
7380 "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
7381 "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
7382 )
7383 Reusing Precompile Headers
7385 The command also supports a second signature which can be used to spec‐
7386 ify that one target re-uses a precompiled header file artefact from
7387 another target instead of generating its own:
7388 target_precompile_headers(<target> REUSE_FROM <other_target>)
7390 This form sets the PRECOMPILE_HEADERS_REUSE_FROM property to
7392 <other_target> and adds a dependency such that <target> will depend on
7393 <other_target>. CMake will halt with an error if the PRECOMPILE_HEAD‐
7394 ERS property of <target> is already set when the REUSE_FROM form is
7395 used.
7396 NOTE:
7398 The REUSE_FROM form requires the same set of compiler options, com‐
7399 piler flags and compiler definitions for both <target> and
7400 <other_target>. Some compilers (e.g. GCC) may issue a warning if
7401 the precompiled header file cannot be used (-Winvalid-pch).
7402 See Also
7404 To disable precompile headers for specific targets, see the DIS‐
7405 ABLE_PRECOMPILE_HEADERS target property.
7406 To prevent precompile headers from being used when compiling a specific
7408 source file, see the SKIP_PRECOMPILE_HEADERS source file property.
7409 target_sources
7411 Add sources to a target.
7412 target_sources(<target>
7414 <INTERFACE|PUBLIC|PRIVATE> [items1...]
7415 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
7416 Specifies sources to use when compiling a given target. Relative
7418 source file paths are interpreted as being relative to the current
7419 source directory (i.e. CMAKE_CURRENT_SOURCE_DIR). The named <target>
7420 must have been created by a command such as add_executable() or
7421 add_library() and must not be an ALIAS target.
7422 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
7424 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
7425 late the SOURCES property of <target>. PUBLIC and INTERFACE items will
7426 populate the INTERFACE_SOURCES property of <target>. (IMPORTED targets
7427 only support INTERFACE items.) The following arguments specify
7428 sources. Repeated calls for the same <target> append items in the
7429 order called.
7430 Arguments to target_sources may use “generator expressions” with the
7432 syntax $<...>. See the cmake-generator-expressions(7) manual for avail‐
7433 able expressions. See the cmake-buildsystem(7) manual for more on
7434 defining buildsystem properties.
7435 See also the CMP0076 policy for older behavior related to the handling
7437 of relative source file paths.
7438 try_compile
7440 Try building some code.
7441 Try Compiling Whole Projects
7443 try_compile(<resultVar> <bindir> <srcdir>
7444 <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
7445 [OUTPUT_VARIABLE <var>])
7446 Try building a project. The success or failure of the try_compile,
7448 i.e. TRUE or FALSE respectively, is returned in <resultVar>.
7449 In this form, <srcdir> should contain a complete CMake project with a
7451 CMakeLists.txt file and all sources. The <bindir> and <srcdir> will
7452 not be deleted after this command is run. Specify <targetName> to
7453 build a specific target instead of the all or ALL_BUILD target. See
7454 below for the meaning of other options.
7455 Try Compiling Source Files
7457 try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
7458 [CMAKE_FLAGS <flags>...]
7459 [COMPILE_DEFINITIONS <defs>...]
7460 [LINK_OPTIONS <options>...]
7461 [LINK_LIBRARIES <libs>...]
7462 [OUTPUT_VARIABLE <var>]
7463 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
7464 [<LANG>_STANDARD <std>]
7465 [<LANG>_STANDARD_REQUIRED <bool>]
7466 [<LANG>_EXTENSIONS <bool>]
7467 )
7468 Try building an executable or static library from one or more source
7470 files (which one is determined by the CMAKE_TRY_COMPILE_TARGET_TYPE
7471 variable). The success or failure of the try_compile, i.e. TRUE or
7472 FALSE respectively, is returned in <resultVar>.
7473 In this form, one or more source files must be provided. If
7475 CMAKE_TRY_COMPILE_TARGET_TYPE is unset or is set to EXECUTABLE, the
7476 sources must include a definition for main and CMake will create a
7477 CMakeLists.txt file to build the source(s) as an executable. If
7478 CMAKE_TRY_COMPILE_TARGET_TYPE is set to STATIC_LIBRARY, a static
7479 library will be built instead and no definition for main is required.
7480 For an executable, the generated CMakeLists.txt file would contain
7481 something like the following:
7482 add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
7484 include_directories(${INCLUDE_DIRECTORIES})
7485 link_directories(${LINK_DIRECTORIES})
7486 add_executable(cmTryCompileExec <srcfile>...)
7487 target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
7488 target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
7489 The options are:
7491 CMAKE_FLAGS <flags>...
7493 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
7494 cmake command-line used to drive the test build. The above
7495 example shows how values for variables INCLUDE_DIRECTORIES,
7496 LINK_DIRECTORIES, and LINK_LIBRARIES are used.
7497 COMPILE_DEFINITIONS <defs>...
7499 Specify -Ddefinition arguments to pass to add_definitions() in
7500 the generated test project.
7501 COPY_FILE <fileName>
7503 Copy the built executable or static library to the given <file‐
7504 Name>.
7505 COPY_FILE_ERROR <var>
7507 Use after COPY_FILE to capture into variable <var> any error
7508 message encountered while trying to copy the file.
7509 LINK_LIBRARIES <libs>...
7511 Specify libraries to be linked in the generated project. The
7512 list of libraries may refer to system libraries and to Imported
7513 Targets from the calling project.
7514 If this option is specified, any -DLINK_LIBRARIES=... value
7516 given to the CMAKE_FLAGS option will be ignored.
7517 LINK_OPTIONS <options>...
7519 Specify link step options to pass to target_link_options() or to
7520 set the STATIC_LIBRARY_OPTIONS target property in the generated
7521 project, depending on the CMAKE_TRY_COMPILE_TARGET_TYPE vari‐
7522 able.
7523 OUTPUT_VARIABLE <var>
7525 Store the output from the build process in the given variable.
7526 <LANG>_STANDARD <std>
7528 Specify the C_STANDARD, CXX_STANDARD, OBJC_STANDARD,
7529 OBJCXX_STANDARD, or CUDA_STANDARD target property of the gener‐
7530 ated project.
7531 <LANG>_STANDARD_REQUIRED <bool>
7533 Specify the C_STANDARD_REQUIRED, CXX_STANDARD_REQUIRED,
7534 OBJC_STANDARD_REQUIRED, OBJCXX_STANDARD_REQUIRED,or CUDA_STAN‐
7535 DARD_REQUIRED target property of the generated project.
7536 <LANG>_EXTENSIONS <bool>
7538 Specify the C_EXTENSIONS, CXX_EXTENSIONS, OBJC_EXTENSIONS,
7539 OBJCXX_EXTENSIONS, or CUDA_EXTENSIONS target property of the
7540 generated project.
7541 In this version all files in <bindir>/CMakeFiles/CMakeTmp will be
7543 cleaned automatically. For debugging, --debug-trycompile can be passed
7544 to cmake to avoid this clean. However, multiple sequential try_compile
7545 operations reuse this single output directory. If you use
7546 --debug-trycompile, you can only debug one try_compile call at a time.
7547 The recommended procedure is to protect all try_compile calls in your
7548 project by if(NOT DEFINED <resultVar>) logic, configure with cmake all
7549 the way through once, then delete the cache entry associated with the
7550 try_compile call of interest, and then re-run cmake again with
7551 --debug-trycompile.
7552 Other Behavior Settings
7554 If set, the following variables are passed in to the generated try_com‐
7555 pile CMakeLists.txt to initialize compile target properties with
7556 default values:
7557 · CMAKE_ENABLE_EXPORTS
7559 · CMAKE_LINK_SEARCH_START_STATIC
7561 · CMAKE_LINK_SEARCH_END_STATIC
7563 · CMAKE_MSVC_RUNTIME_LIBRARY
7565 · CMAKE_POSITION_INDEPENDENT_CODE
7567 If CMP0056 is set to NEW, then CMAKE_EXE_LINKER_FLAGS is passed in as
7569 well.
7570 If CMP0083 is set to NEW, then in order to obtain correct behavior at
7572 link time, the check_pie_supported() command from the CheckPIESupported
7573 module must be called before using the try_compile() command.
7574 The current settings of CMP0065 and CMP0083 are propagated through to
7576 the generated test project.
7577 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
7579 figuration.
7580 Set the CMAKE_TRY_COMPILE_TARGET_TYPE variable to specify the type of
7582 target used for the source file signature.
7583 Set the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable to specify vari‐
7585 ables that must be propagated into the test project. This variable is
7586 meant for use only in toolchain files and is only honored by the
7587 try_compile() command for the source files form, not when given a whole
7588 project.
7589 If CMP0067 is set to NEW, or any of the <LANG>_STANDARD, <LANG>_STAN‐
7591 DARD_REQUIRED, or <LANG>_EXTENSIONS options are used, then the language
7592 standard variables are honored:
7593 · CMAKE_C_STANDARD
7595 · CMAKE_C_STANDARD_REQUIRED
7597 · CMAKE_C_EXTENSIONS
7599 · CMAKE_CXX_STANDARD
7601 · CMAKE_CXX_STANDARD_REQUIRED
7603 · CMAKE_CXX_EXTENSIONS
7605 · CMAKE_OBJC_STANDARD
7607 · CMAKE_OBJC_STANDARD_REQUIRED
7609 · CMAKE_OBJC_EXTENSIONS
7611 · CMAKE_OBJCXX_STANDARD
7613 · CMAKE_OBJCXX_STANDARD_REQUIRED
7615 · CMAKE_OBJCXX_EXTENSIONS
7617 · CMAKE_CUDA_STANDARD
7619 · CMAKE_CUDA_STANDARD_REQUIRED
7621 · CMAKE_CUDA_EXTENSIONS
7623 Their values are used to set the corresponding target properties in the
7625 generated project (unless overridden by an explicit option).
7626 For the Green Hills MULTI generator the GHS toolset and target system
7628 customization cache variables are also propagated into the test
7629 project.
7630 try_run
7632 Try compiling and then running some code.
7633 Try Compiling and Running Source Files
7635 try_run(<runResultVar> <compileResultVar>
7636 <bindir> <srcfile> [CMAKE_FLAGS <flags>...]
7637 [COMPILE_DEFINITIONS <defs>...]
7638 [LINK_OPTIONS <options>...]
7639 [LINK_LIBRARIES <libs>...]
7640 [COMPILE_OUTPUT_VARIABLE <var>]
7641 [RUN_OUTPUT_VARIABLE <var>]
7642 [OUTPUT_VARIABLE <var>]
7643 [ARGS <args>...])
7644 Try compiling a <srcfile>. Returns TRUE or FALSE for success or fail‐
7646 ure in <compileResultVar>. If the compile succeeded, runs the exe‐
7647 cutable and returns its exit code in <runResultVar>. If the executable
7648 was built, but failed to run, then <runResultVar> will be set to
7649 FAILED_TO_RUN. See the try_compile() command for information on how
7650 the test project is constructed to build the source file.
7651 The options are:
7653 CMAKE_FLAGS <flags>...
7655 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
7656 cmake command-line used to drive the test build. The example in
7657 try_compile() shows how values for variables INCLUDE_DIRECTO‐
7658 RIES, LINK_DIRECTORIES, and LINK_LIBRARIES are used.
7659 COMPILE_DEFINITIONS <defs>...
7661 Specify -Ddefinition arguments to pass to add_definitions() in
7662 the generated test project.
7663 COMPILE_OUTPUT_VARIABLE <var>
7665 Report the compile step build output in a given variable.
7666 LINK_LIBRARIES <libs>...
7668 Specify libraries to be linked in the generated project. The
7669 list of libraries may refer to system libraries and to Imported
7670 Targets from the calling project.
7671 If this option is specified, any -DLINK_LIBRARIES=... value
7673 given to the CMAKE_FLAGS option will be ignored.
7674 LINK_OPTIONS <options>...
7676 Specify link step options to pass to target_link_options() in
7677 the generated project.
7678 OUTPUT_VARIABLE <var>
7680 Report the compile build output and the output from running the
7681 executable in the given variable. This option exists for legacy
7682 reasons. Prefer COMPILE_OUTPUT_VARIABLE and RUN_OUTPUT_VARIABLE
7683 instead.
7684 RUN_OUTPUT_VARIABLE <var>
7686 Report the output from running the executable in a given vari‐
7687 able.
7688 Other Behavior Settings
7690 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
7691 figuration.
7692 Behavior when Cross Compiling
7694 When cross compiling, the executable compiled in the first step usually
7695 cannot be run on the build host. The try_run command checks the
7696 CMAKE_CROSSCOMPILING variable to detect whether CMake is in cross-com‐
7697 piling mode. If that is the case, it will still try to compile the
7698 executable, but it will not try to run the executable unless the
7699 CMAKE_CROSSCOMPILING_EMULATOR variable is set. Instead it will create
7700 cache variables which must be filled by the user or by presetting them
7701 in some CMake script file to the values the executable would have pro‐
7702 duced if it had been run on its actual target platform. These cache
7703 entries are:
7704 <runResultVar>
7706 Exit code if the executable were to be run on the target plat‐
7707 form.
7708 <runResultVar>__TRYRUN_OUTPUT
7710 Output from stdout and stderr if the executable were to be run
7711 on the target platform. This is created only if the RUN_OUT‐
7712 PUT_VARIABLE or OUTPUT_VARIABLE option was used.
7713 In order to make cross compiling your project easier, use try_run only
7715 if really required. If you use try_run, use the RUN_OUTPUT_VARIABLE or
7716 OUTPUT_VARIABLE options only if really required. Using them will
7717 require that when cross-compiling, the cache variables will have to be
7718 set manually to the output of the executable. You can also “guard” the
7719 calls to try_run with an if() block checking the CMAKE_CROSSCOMPILING
7720 variable and provide an easy-to-preset alternative for this case.
7721
7723 These commands are available only in CTest scripts.
7724 ctest_build
7726 Perform the CTest Build Step as a Dashboard Client.
7727 ctest_build([BUILD <build-dir>] [APPEND]
7729 [CONFIGURATION <config>]
7730 [FLAGS <flags>]
7731 [PROJECT_NAME <project-name>]
7732 [TARGET <target-name>]
7733 [NUMBER_ERRORS <num-err-var>]
7734 [NUMBER_WARNINGS <num-warn-var>]
7735 [RETURN_VALUE <result-var>]
7736 [CAPTURE_CMAKE_ERROR <result-var>]
7737 )
7738 Build the project and store results in Build.xml for submission with
7740 the ctest_submit() command.
7741 The CTEST_BUILD_COMMAND variable may be set to explicitly specify the
7743 build command line. Otherwise the build command line is computed auto‐
7744 matically based on the options given.
7745 The options are:
7747 BUILD <build-dir>
7749 Specify the top-level build directory. If not given, the
7750 CTEST_BINARY_DIRECTORY variable is used.
7751 APPEND Mark Build.xml for append to results previously submitted to a
7753 dashboard server since the last ctest_start() call. Append
7754 semantics are defined by the dashboard server in use. This does
7755 not cause results to be appended to a .xml file produced by a
7756 previous call to this command.
7757 CONFIGURATION <config>
7759 Specify the build configuration (e.g. Debug). If not specified
7760 the CTEST_BUILD_CONFIGURATION variable will be checked. Other‐
7761 wise the -C <cfg> option given to the ctest(1) command will be
7762 used, if any.
7763 FLAGS <flags>
7765 Pass additional arguments to the underlying build command. If
7766 not specified the CTEST_BUILD_FLAGS variable will be checked.
7767 This can, e.g., be used to trigger a parallel build using the -j
7768 option of make. See the ProcessorCount module for an example.
7769 PROJECT_NAME <project-name>
7771 Ignored. This was once used but is no longer needed.
7772 TARGET <target-name>
7774 Specify the name of a target to build. If not specified the
7775 CTEST_BUILD_TARGET variable will be checked. Otherwise the
7776 default target will be built. This is the “all” target (called
7777 ALL_BUILD in Visual Studio Generators).
7778 NUMBER_ERRORS <num-err-var>
7780 Store the number of build errors detected in the given variable.
7781 NUMBER_WARNINGS <num-warn-var>
7783 Store the number of build warnings detected in the given vari‐
7784 able.
7785 RETURN_VALUE <result-var>
7787 Store the return value of the native build tool in the given
7788 variable.
7789 CAPTURE_CMAKE_ERROR <result-var>
7791 Store in the <result-var> variable -1 if there are any errors
7792 running the command and prevent ctest from returning non-zero if
7793 an error occurs.
7794 QUIET Suppress any CTest-specific non-error output that would have
7796 been printed to the console otherwise. The summary of warnings
7797 / errors, as well as the output from the native build tool is
7798 unaffected by this option.
7799 ctest_configure
7801 Perform the CTest Configure Step as a Dashboard Client.
7802 ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
7804 [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
7805 [CAPTURE_CMAKE_ERROR <result-var>])
7806 Configure the project build tree and record results in Configure.xml
7808 for submission with the ctest_submit() command.
7809 The options are:
7811 BUILD <build-dir>
7813 Specify the top-level build directory. If not given, the
7814 CTEST_BINARY_DIRECTORY variable is used.
7815 SOURCE <source-dir>
7817 Specify the source directory. If not given, the
7818 CTEST_SOURCE_DIRECTORY variable is used.
7819 APPEND Mark Configure.xml for append to results previously submitted to
7821 a dashboard server since the last ctest_start() call. Append
7822 semantics are defined by the dashboard server in use. This does
7823 not cause results to be appended to a .xml file produced by a
7824 previous call to this command.
7825 OPTIONS <options>
7827 Specify command-line arguments to pass to the configuration
7828 tool.
7829 RETURN_VALUE <result-var>
7831 Store in the <result-var> variable the return value of the
7832 native configuration tool.
7833 CAPTURE_CMAKE_ERROR <result-var>
7835 Store in the <result-var> variable -1 if there are any errors
7836 running the command and prevent ctest from returning non-zero if
7837 an error occurs.
7838 QUIET Suppress any CTest-specific non-error messages that would have
7840 otherwise been printed to the console. Output from the underly‐
7841 ing configure command is not affected.
7842 ctest_coverage
7844 Perform the CTest Coverage Step as a Dashboard Client.
7845 ctest_coverage([BUILD <build-dir>] [APPEND]
7847 [LABELS <label>...]
7848 [RETURN_VALUE <result-var>]
7849 [CAPTURE_CMAKE_ERROR <result-var>]
7850 [QUIET]
7851 )
7852 Collect coverage tool results and stores them in Coverage.xml for sub‐
7854 mission with the ctest_submit() command.
7855 The options are:
7857 BUILD <build-dir>
7859 Specify the top-level build directory. If not given, the
7860 CTEST_BINARY_DIRECTORY variable is used.
7861 APPEND Mark Coverage.xml for append to results previously submitted to
7863 a dashboard server since the last ctest_start() call. Append
7864 semantics are defined by the dashboard server in use. This does
7865 not cause results to be appended to a .xml file produced by a
7866 previous call to this command.
7867 LABELS Filter the coverage report to include only source files labeled
7869 with at least one of the labels specified.
7870 RETURN_VALUE <result-var>
7872 Store in the <result-var> variable 0 if coverage tools ran with‐
7873 out error and non-zero otherwise.
7874 CAPTURE_CMAKE_ERROR <result-var>
7876 Store in the <result-var> variable -1 if there are any errors
7877 running the command and prevent ctest from returning non-zero if
7878 an error occurs.
7879 QUIET Suppress any CTest-specific non-error output that would have
7881 been printed to the console otherwise. The summary indicating
7882 how many lines of code were covered is unaffected by this
7883 option.
7884 ctest_empty_binary_directory
7886 empties the binary directory
7887 ctest_empty_binary_directory( directory )
7889 Removes a binary directory. This command will perform some checks
7891 prior to deleting the directory in an attempt to avoid malicious or
7892 accidental directory deletion.
7893 ctest_memcheck
7895 Perform the CTest MemCheck Step as a Dashboard Client.
7896 ctest_memcheck([BUILD <build-dir>] [APPEND]
7898 [START <start-number>]
7899 [END <end-number>]
7900 [STRIDE <stride-number>]
7901 [EXCLUDE <exclude-regex>]
7902 [INCLUDE <include-regex>]
7903 [EXCLUDE_LABEL <label-exclude-regex>]
7904 [INCLUDE_LABEL <label-include-regex>]
7905 [EXCLUDE_FIXTURE <regex>]
7906 [EXCLUDE_FIXTURE_SETUP <regex>]
7907 [EXCLUDE_FIXTURE_CLEANUP <regex>]
7908 [PARALLEL_LEVEL <level>]
7909 [TEST_LOAD <threshold>]
7910 [SCHEDULE_RANDOM <ON|OFF>]
7911 [STOP_TIME <time-of-day>]
7912 [RETURN_VALUE <result-var>]
7913 [DEFECT_COUNT <defect-count-var>]
7914 [QUIET]
7915 )
7916 Run tests with a dynamic analysis tool and store results in Mem‐
7918 Check.xml for submission with the ctest_submit() command.
7919 Most options are the same as those for the ctest_test() command.
7921 The options unique to this command are:
7923 DEFECT_COUNT <defect-count-var>
7925 Store in the <defect-count-var> the number of defects found.
7926 ctest_read_custom_files
7928 read CTestCustom files.
7929 ctest_read_custom_files( directory ... )
7931 Read all the CTestCustom.ctest or CTestCustom.cmake files from the
7933 given directory.
7934 By default, invoking ctest(1) without a script will read custom files
7936 from the binary directory.
7937 ctest_run_script
7939 runs a ctest -S script
7940 ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
7942 script_file_name2 ... [RETURN_VALUE var])
7943 Runs a script or scripts much like if it was run from ctest -S. If no
7945 argument is provided then the current script is run using the current
7946 settings of the variables. If NEW_PROCESS is specified then each
7947 script will be run in a separate process.If RETURN_VALUE is specified
7948 the return value of the last script run will be put into var.
7949 ctest_sleep
7951 sleeps for some amount of time
7952 ctest_sleep(<seconds>)
7954 Sleep for given number of seconds.
7956 ctest_sleep(<time1> <duration> <time2>)
7958 Sleep for t=(time1 + duration - time2) seconds if t > 0.
7960 ctest_start
7962 Starts the testing for a given model
7963 ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])
7965 ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET])
7967 Starts the testing for a given model. The command should be called
7969 after the binary directory is initialized.
7970 The parameters are as follows:
7972 <model>
7974 Set the dashboard model. Must be one of Experimental, Continu‐
7975 ous, or Nightly. This parameter is required unless APPEND is
7976 specified.
7977 <source>
7979 Set the source directory. If not specified, the value of
7980 CTEST_SOURCE_DIRECTORY is used instead.
7981 <binary>
7983 Set the binary directory. If not specified, the value of
7984 CTEST_BINARY_DIRECTORY is used instead.
7985 GROUP <group>
7987 If GROUP is used, the submissions will go to the specified group
7988 on the CDash server. If no GROUP is specified, the name of the
7989 model is used by default. This replaces the deprecated option
7990 TRACK. Despite the name change its behavior is unchanged.
7991 APPEND If APPEND is used, the existing TAG is used rather than creating
7993 a new one based on the current time stamp. If you use APPEND,
7994 you can omit the <model> and GROUP <group> parameters, because
7995 they will be read from the generated TAG file. For example:
7996 ctest_start(Experimental GROUP GroupExperimental)
7998 Later, in another ctest -S script:
8000 ctest_start(APPEND)
8002 When the second script runs ctest_start(APPEND), it will read
8004 the Experimental model and GroupExperimental group from the TAG
8005 file generated by the first ctest_start() command. Please note
8006 that if you call ctest_start(APPEND) and specify a different
8007 model or group than in the first ctest_start() command, a warn‐
8008 ing will be issued, and the new model and group will be used.
8009 QUIET If QUIET is used, CTest will suppress any non-error messages
8011 that it otherwise would have printed to the console.
8012 The parameters for ctest_start() can be issued in any order, with the
8014 exception that <model>, <source>, and <binary> have to appear in that
8015 order with respect to each other. The following are all valid and
8016 equivalent:
8017 ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND)
8019 ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary)
8021 ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary)
8023 However, for the sake of readability, it is recommended that you order
8025 your parameters in the order listed at the top of this page.
8026 If the CTEST_CHECKOUT_COMMAND variable (or the CTEST_CVS_CHECKOUT vari‐
8028 able) is set, its content is treated as command-line. The command is
8029 invoked with the current working directory set to the parent of the
8030 source directory, even if the source directory already exists. This
8031 can be used to create the source tree from a version control reposi‐
8032 tory.
8033 ctest_submit
8035 Perform the CTest Submit Step as a Dashboard Client.
8036 ctest_submit([PARTS <part>...] [FILES <file>...]
8038 [SUBMIT_URL <url>]
8039 [BUILD_ID <result-var>]
8040 [HTTPHEADER <header>]
8041 [RETRY_COUNT <count>]
8042 [RETRY_DELAY <delay>]
8043 [RETURN_VALUE <result-var>]
8044 [CAPTURE_CMAKE_ERROR <result-var>]
8045 [QUIET]
8046 )
8047 Submit results to a dashboard server. By default all available parts
8049 are submitted.
8050 The options are:
8052 PARTS <part>...
8054 Specify a subset of parts to submit. Valid part names are:
8055 Start = nothing
8057 Update = ctest_update results, in Update.xml
8058 Configure = ctest_configure results, in Configure.xml
8059 Build = ctest_build results, in Build.xml
8060 Test = ctest_test results, in Test.xml
8061 Coverage = ctest_coverage results, in Coverage.xml
8062 MemCheck = ctest_memcheck results, in DynamicAnalysis.xml
8063 Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
8064 ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
8065 Upload = Files prepared for upload by ctest_upload(), in Upload.xml
8066 Submit = nothing
8067 Done = Build is complete, in Done.xml
8068 FILES <file>...
8070 Specify an explicit list of specific files to be submitted.
8071 Each individual file must exist at the time of the call.
8072 SUBMIT_URL <url>
8074 The http or https URL of the dashboard server to send the sub‐
8075 mission to. If not given, the CTEST_SUBMIT_URL variable is
8076 used.
8077 BUILD_ID <result-var>
8079 Store in the <result-var> variable the ID assigned to this build
8080 by CDash.
8081 HTTPHEADER <HTTP-header>
8083 Specify HTTP header to be included in the request to CDash dur‐
8084 ing submission. For example, CDash can be configured to only
8085 accept submissions from authenticated clients. In this case, you
8086 should provide a bearer token in your header:
8087 ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>")
8089 This suboption can be repeated several times for multiple head‐
8091 ers.
8092 RETRY_COUNT <count>
8094 Specify how many times to retry a timed-out submission.
8095 RETRY_DELAY <delay>
8097 Specify how long (in seconds) to wait after a timed-out submis‐
8098 sion before attempting to re-submit.
8099 RETURN_VALUE <result-var>
8101 Store in the <result-var> variable 0 for success and non-zero on
8102 failure.
8103 CAPTURE_CMAKE_ERROR <result-var>
8105 Store in the <result-var> variable -1 if there are any errors
8106 running the command and prevent ctest from returning non-zero if
8107 an error occurs.
8108 QUIET Suppress all non-error messages that would have otherwise been
8110 printed to the console.
8111 Submit to CDash Upload API
8113 ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
8114 [SUBMIT_URL <url>]
8115 [HTTPHEADER <header>]
8116 [RETRY_COUNT <count>]
8117 [RETRY_DELAY <delay>]
8118 [RETURN_VALUE <result-var>]
8119 [QUIET])
8120 This second signature is used to upload files to CDash via the CDash
8122 file upload API. The API first sends a request to upload to CDash along
8123 with a content hash of the file. If CDash does not already have the
8124 file, then it is uploaded. Along with the file, a CDash type string is
8125 specified to tell CDash which handler to use to process the data.
8126 This signature accepts the SUBMIT_URL, BUILD_ID, HTTPHEADER,
8128 RETRY_COUNT, RETRY_DELAY, RETURN_VALUE and QUIET options as described
8129 above.
8130 ctest_test
8132 Perform the CTest Test Step as a Dashboard Client.
8133 ctest_test([BUILD <build-dir>] [APPEND]
8135 [START <start-number>]
8136 [END <end-number>]
8137 [STRIDE <stride-number>]
8138 [EXCLUDE <exclude-regex>]
8139 [INCLUDE <include-regex>]
8140 [EXCLUDE_LABEL <label-exclude-regex>]
8141 [INCLUDE_LABEL <label-include-regex>]
8142 [EXCLUDE_FIXTURE <regex>]
8143 [EXCLUDE_FIXTURE_SETUP <regex>]
8144 [EXCLUDE_FIXTURE_CLEANUP <regex>]
8145 [PARALLEL_LEVEL <level>]
8146 [RESOURCE_SPEC_FILE <file>]
8147 [TEST_LOAD <threshold>]
8148 [SCHEDULE_RANDOM <ON|OFF>]
8149 [STOP_TIME <time-of-day>]
8150 [RETURN_VALUE <result-var>]
8151 [CAPTURE_CMAKE_ERROR <result-var>]
8152 [REPEAT <mode>:<n>]
8153 [QUIET]
8154 )
8155 Run tests in the project build tree and store results in Test.xml for
8157 submission with the ctest_submit() command.
8158 The options are:
8160 BUILD <build-dir>
8162 Specify the top-level build directory. If not given, the
8163 CTEST_BINARY_DIRECTORY variable is used.
8164 APPEND Mark Test.xml for append to results previously submitted to a
8166 dashboard server since the last ctest_start() call. Append
8167 semantics are defined by the dashboard server in use. This does
8168 not cause results to be appended to a .xml file produced by a
8169 previous call to this command.
8170 START <start-number>
8172 Specify the beginning of a range of test numbers.
8173 END <end-number>
8175 Specify the end of a range of test numbers.
8176 STRIDE <stride-number>
8178 Specify the stride by which to step across a range of test num‐
8179 bers.
8180 EXCLUDE <exclude-regex>
8182 Specify a regular expression matching test names to exclude.
8183 INCLUDE <include-regex>
8185 Specify a regular expression matching test names to include.
8186 Tests not matching this expression are excluded.
8187 EXCLUDE_LABEL <label-exclude-regex>
8189 Specify a regular expression matching test labels to exclude.
8190 INCLUDE_LABEL <label-include-regex>
8192 Specify a regular expression matching test labels to include.
8193 Tests not matching this expression are excluded.
8194 EXCLUDE_FIXTURE <regex>
8196 If a test in the set of tests to be executed requires a particu‐
8197 lar fixture, that fixture’s setup and cleanup tests would nor‐
8198 mally be added to the test set automatically. This option pre‐
8199 vents adding setup or cleanup tests for fixtures matching the
8200 <regex>. Note that all other fixture behavior is retained,
8201 including test dependencies and skipping tests that have fixture
8202 setup tests that fail.
8203 EXCLUDE_FIXTURE_SETUP <regex>
8205 Same as EXCLUDE_FIXTURE except only matching setup tests are
8206 excluded.
8207 EXCLUDE_FIXTURE_CLEANUP <regex>
8209 Same as EXCLUDE_FIXTURE except only matching cleanup tests are
8210 excluded.
8211 PARALLEL_LEVEL <level>
8213 Specify a positive number representing the number of tests to be
8214 run in parallel.
8215 RESOURCE_SPEC_FILE <file>
8217 Specify a resource specification file. See ctest-resource-allo‐
8218 cation for more information.
8219 TEST_LOAD <threshold>
8221 While running tests in parallel, try not to start tests when
8222 they may cause the CPU load to pass above a given threshold. If
8223 not specified the CTEST_TEST_LOAD variable will be checked, and
8224 then the --test-load command-line argument to ctest(1). See
8225 also the TestLoad setting in the CTest Test Step.
8226 REPEAT <mode>:<n>
8228 Run tests repeatedly based on the given <mode> up to <n> times.
8229 The modes are:
8230 UNTIL_FAIL
8232 Require each test to run <n> times without failing in
8233 order to pass. This is useful in finding sporadic fail‐
8234 ures in test cases.
8235 UNTIL_PASS
8237 Allow each test to run up to <n> times in order to pass.
8238 Repeats tests if they fail for any reason. This is use‐
8239 ful in tolerating sporadic failures in test cases.
8240 AFTER_TIMEOUT
8242 Allow each test to run up to <n> times in order to pass.
8243 Repeats tests only if they timeout. This is useful in
8244 tolerating sporadic timeouts in test cases on busy
8245 machines.
8246 SCHEDULE_RANDOM <ON|OFF>
8248 Launch tests in a random order. This may be useful for detect‐
8249 ing implicit test dependencies.
8250 STOP_TIME <time-of-day>
8252 Specify a time of day at which the tests should all stop run‐
8253 ning.
8254 RETURN_VALUE <result-var>
8256 Store in the <result-var> variable 0 if all tests passed. Store
8257 non-zero if anything went wrong.
8258 CAPTURE_CMAKE_ERROR <result-var>
8260 Store in the <result-var> variable -1 if there are any errors
8261 running the command and prevent ctest from returning non-zero if
8262 an error occurs.
8263 QUIET Suppress any CTest-specific non-error messages that would have
8265 otherwise been printed to the console. Output from the underly‐
8266 ing test command is not affected. Summary info detailing the
8267 percentage of passing tests is also unaffected by the QUIET
8268 option.
8269 See also the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE and
8271 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables.
8272 ctest_update
8274 Perform the CTest Update Step as a Dashboard Client.
8275 ctest_update([SOURCE <source-dir>]
8277 [RETURN_VALUE <result-var>]
8278 [CAPTURE_CMAKE_ERROR <result-var>]
8279 [QUIET])
8280 Update the source tree from version control and record results in
8282 Update.xml for submission with the ctest_submit() command.
8283 The options are:
8285 SOURCE <source-dir>
8287 Specify the source directory. If not given, the
8288 CTEST_SOURCE_DIRECTORY variable is used.
8289 RETURN_VALUE <result-var>
8291 Store in the <result-var> variable the number of files updated
8292 or -1 on error.
8293 CAPTURE_CMAKE_ERROR <result-var>
8295 Store in the <result-var> variable -1 if there are any errors
8296 running the command and prevent ctest from returning non-zero if
8297 an error occurs.
8298 QUIET Tell CTest to suppress most non-error messages that it would
8300 have otherwise printed to the console. CTest will still report
8301 the new revision of the repository and any conflicting files
8302 that were found.
8303 The update always follows the version control branch currently checked
8305 out in the source directory. See the CTest Update Step documentation
8306 for information about variables that change the behavior of
8307 ctest_update().
8308 ctest_upload
8310 Upload files to a dashboard server as a Dashboard Client.
8311 ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
8313 The options are:
8315 FILES <file>...
8317 Specify a list of files to be sent along with the build results
8318 to the dashboard server.
8319 QUIET Suppress any CTest-specific non-error output that would have
8321 been printed to the console otherwise.
8322 CAPTURE_CMAKE_ERROR <result-var>
8324 Store in the <result-var> variable -1 if there are any errors
8325 running the command and prevent ctest from returning non-zero if
8326 an error occurs.
8327
8329 These commands are deprecated and are only made available to maintain
8330 backward compatibility. The documentation of each command states the
8331 CMake version in which it was deprecated. Do not use these commands in
8332 new code.
8333 build_name
8335 Disallowed since version 3.0. See CMake Policy CMP0036.
8336 Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.
8338 build_name(variable)
8340 Sets the specified variable to a string representing the platform and
8342 compiler settings. These values are now available through the
8343 CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
8344 exec_program
8346 Deprecated since version 3.0: Use the execute_process() command
8347 instead.
8348 Run an executable program during the processing of the CMakeList.txt
8351 file.
8352 exec_program(Executable [directory in which to run]
8354 [ARGS <arguments to executable>]
8355 [OUTPUT_VARIABLE <var>]
8356 [RETURN_VALUE <var>])
8357 The executable is run in the optionally specified directory. The exe‐
8359 cutable can include arguments if it is double quoted, but it is better
8360 to use the optional ARGS argument to specify arguments to the program.
8361 This is because cmake will then be able to escape spaces in the exe‐
8362 cutable path. An optional argument OUTPUT_VARIABLE specifies a vari‐
8363 able in which to store the output. To capture the return value of the
8364 execution, provide a RETURN_VALUE. If OUTPUT_VARIABLE is specified,
8365 then no output will go to the stdout/stderr of the console running
8366 cmake.
8367 export_library_dependencies
8369 Disallowed since version 3.0. See CMake Policy CMP0033.
8370 Use install(EXPORT) or export() command.
8372 This command generates an old-style library dependencies file.
8374 Projects requiring CMake 2.6 or later should not use the command. Use
8375 instead the install(EXPORT) command to help export targets from an
8376 installation tree and the export() command to export targets from a
8377 build tree.
8378 The old-style library dependencies file does not take into account
8380 per-configuration names of libraries or the LINK_INTERFACE_LIBRARIES
8381 target property.
8382 export_library_dependencies(<file> [APPEND])
8384 Create a file named <file> that can be included into a CMake listfile
8386 with the INCLUDE command. The file will contain a number of SET com‐
8387 mands that will set all the variables needed for library dependency
8388 information. This should be the last command in the top level CMake‐
8389 Lists.txt file of the project. If the APPEND option is specified, the
8390 SET commands will be appended to the given file instead of replacing
8391 it.
8392 install_files
8394 Deprecated since version 3.0: Use the install(FILES) command instead.
8395 This command has been superceded by the install() command. It is pro‐
8398 vided for compatibility with older CMake code. The FILES form is
8399 directly replaced by the FILES form of the install() command. The reg‐
8400 exp form can be expressed more clearly using the GLOB form of the
8401 file() command.
8402 install_files(<dir> extension file file ...)
8404 Create rules to install the listed files with the given extension into
8406 the given directory. Only files existing in the current source tree or
8407 its corresponding location in the binary tree may be listed. If a file
8408 specified already has an extension, that extension will be removed
8409 first. This is useful for providing lists of source files such as
8410 foo.cxx when you want the corresponding foo.h to be installed. A typi‐
8411 cal extension is .h.
8412 install_files(<dir> regexp)
8414 Any files in the current source directory that match the regular
8416 expression will be installed.
8417 install_files(<dir> FILES file file ...)
8419 Any files listed after the FILES keyword will be installed explicitly
8421 from the names given. Full paths are allowed in this form.
8422 The directory <dir> is relative to the installation prefix, which is
8424 stored in the variable CMAKE_INSTALL_PREFIX.
8425 install_programs
8427 Deprecated since version 3.0: Use the install(PROGRAMS) command
8428 instead.
8429 This command has been superceded by the install() command. It is pro‐
8432 vided for compatibility with older CMake code. The FILES form is
8433 directly replaced by the PROGRAMS form of the install() command. The
8434 regexp form can be expressed more clearly using the GLOB form of the
8435 file() command.
8436 install_programs(<dir> file1 file2 [file3 ...])
8438 install_programs(<dir> FILES file1 [file2 ...])
8439 Create rules to install the listed programs into the given directory.
8441 Use the FILES argument to guarantee that the file list version of the
8442 command will be used even when there is only one argument.
8443 install_programs(<dir> regexp)
8445 In the second form any program in the current source directory that
8447 matches the regular expression will be installed.
8448 This command is intended to install programs that are not built by
8450 cmake, such as shell scripts. See the TARGETS form of the install()
8451 command to create installation rules for targets built by cmake.
8452 The directory <dir> is relative to the installation prefix, which is
8454 stored in the variable CMAKE_INSTALL_PREFIX.
8455 install_targets
8457 Deprecated since version 3.0: Use the install(TARGETS) command instead.
8458 This command has been superceded by the install() command. It is pro‐
8461 vided for compatibility with older CMake code.
8462 install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
8464 Create rules to install the listed targets into the given directory.
8466 The directory <dir> is relative to the installation prefix, which is
8467 stored in the variable CMAKE_INSTALL_PREFIX. If RUNTIME_DIRECTORY is
8468 specified, then on systems with special runtime files (Windows DLL),
8469 the files will be copied to that directory.
8470 load_command
8472 Disallowed since version 3.0. See CMake Policy CMP0031.
8473 Load a command into a running CMake.
8475 load_command(COMMAND_NAME <loc1> [loc2 ...])
8477 The given locations are searched for a library whose name is cmCOM‐
8479 MAND_NAME. If found, it is loaded as a module and the command is added
8480 to the set of available CMake commands. Usually, try_compile() is used
8481 before this command to compile the module. If the command is success‐
8482 fully loaded a variable named
8483 CMAKE_LOADED_COMMAND_<COMMAND_NAME>
8485 will be set to the full path of the module that was loaded. Otherwise
8487 the variable will not be set.
8488 make_directory
8490 Deprecated since version 3.0: Use the file(MAKE_DIRECTORY) command
8491 instead.
8492 make_directory(directory)
8495 Creates the specified directory. Full paths should be given. Any par‐
8497 ent directories that do not exist will also be created. Use with care.
8498 output_required_files
8500 Disallowed since version 3.0. See CMake Policy CMP0032.
8501 Approximate C preprocessor dependency scanning.
8503 This command exists only because ancient CMake versions provided it.
8505 CMake handles preprocessor dependency scanning automatically using a
8506 more advanced scanner.
8507 output_required_files(srcfile outputfile)
8509 Outputs a list of all the source files that are required by the speci‐
8511 fied srcfile. This list is written into outputfile. This is similar
8512 to writing out the dependencies for srcfile except that it jumps from
8513 .h files into .cxx, .c and .cpp files if possible.
8514 qt_wrap_cpp
8516 Deprecated since version 3.14: This command was originally added to
8517 support Qt 3 before the add_custom_command() command was sufficiently
8518 mature. The FindQt4 module provides the qt4_wrap_cpp() macro, which
8519 should be used instead for Qt 4 projects. For projects using Qt 5 or
8520 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
8521 vides qt5_wrap_cpp()).
8522 Manually create Qt Wrappers.
8525 qt_wrap_cpp(resultingLibraryName DestName SourceLists ...)
8527 Produces moc files for all the .h files listed in the SourceLists. The
8529 moc files will be added to the library using the DestName source list.
8530 Consider updating the project to use the AUTOMOC target property
8532 instead for a more automated way of invoking the moc tool.
8533 qt_wrap_ui
8535 Deprecated since version 3.14: This command was originally added to
8536 support Qt 3 before the add_custom_command() command was sufficiently
8537 mature. The FindQt4 module provides the qt4_wrap_ui() macro, which
8538 should be used instead for Qt 4 projects. For projects using Qt 5 or
8539 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
8540 vides qt5_wrap_ui()).
8541 Manually create Qt user interfaces Wrappers.
8544 qt_wrap_ui(resultingLibraryName HeadersDestName
8546 SourcesDestName SourceLists ...)
8547 Produces .h and .cxx files for all the .ui files listed in the
8549 SourceLists. The .h files will be added to the library using the Head‐
8550 ersDestNamesource list. The .cxx files will be added to the library
8551 using the SourcesDestNamesource list.
8552 Consider updating the project to use the AUTOUIC target property
8554 instead for a more automated way of invoking the uic tool.
8555 remove
8557 Deprecated since version 3.0: Use the list(REMOVE_ITEM) command
8558 instead.
8559 remove(VAR VALUE VALUE ...)
8562 Removes VALUE from the variable VAR. This is typically used to remove
8564 entries from a vector (e.g. semicolon separated list). VALUE is
8565 expanded.
8566 subdir_depends
8568 Disallowed since version 3.0. See CMake Policy CMP0029.
8569 Does nothing.
8571 subdir_depends(subdir dep1 dep2 ...)
8573 Does not do anything. This command used to help projects order paral‐
8575 lel builds correctly. This functionality is now automatic.
8576 subdirs
8578 Deprecated since version 3.0: Use the add_subdirectory() command
8579 instead.
8580 Add a list of subdirectories to the build.
8583 subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
8585 [PREORDER] )
8586 Add a list of subdirectories to the build. The add_subdirectory() com‐
8588 mand should be used instead of subdirs although subdirs will still
8589 work. This will cause any CMakeLists.txt files in the sub directories
8590 to be processed by CMake. Any directories after the PREORDER flag are
8591 traversed first by makefile builds, the PREORDER flag has no effect on
8592 IDE projects. Any directories after the EXCLUDE_FROM_ALL marker will
8593 not be included in the top level makefile or project file. This is
8594 useful for having CMake create makefiles or projects for a set of exam‐
8595 ples in a project. You would want CMake to generate makefiles or
8596 project files for all the examples at the same time, but you would not
8597 want them to show up in the top level project or be built each time
8598 make is run from the top.
8599 use_mangled_mesa
8601 Disallowed since version 3.0. See CMake Policy CMP0030.
8602 Copy mesa headers for use in combination with system GL.
8604 use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
8606 The path to mesa includes, should contain gl_mangle.h. The mesa head‐
8608 ers are copied to the specified output directory. This allows mangled
8609 mesa headers to override other GL headers by being added to the include
8610 directory path earlier.
8611 utility_source
8613 Disallowed since version 3.0. See CMake Policy CMP0034.
8614 Specify the source tree of a third-party utility.
8616 utility_source(cache_entry executable_name
8618 path_to_source [file1 file2 ...])
8619 When a third-party utility’s source is included in the distribution,
8621 this command specifies its location and name. The cache entry will not
8622 be set unless the path_to_source and all listed files exist. It is
8623 assumed that the source tree of the utility will have been built before
8624 it is needed.
8625 When cross compiling CMake will print a warning if a utility_source()
8627 command is executed, because in many cases it is used to build an exe‐
8628 cutable which is executed later on. This doesn’t work when cross com‐
8629 piling, since the executable can run only on their target platform. So
8630 in this case the cache entry has to be adjusted manually so it points
8631 to an executable which is runnable on the build host.
8632 variable_requires
8634 Disallowed since version 3.0. See CMake Policy CMP0035.
8635 Use the if() command instead.
8637 Assert satisfaction of an option’s required variables.
8639 variable_requires(TEST_VARIABLE RESULT_VARIABLE
8641 REQUIRED_VARIABLE1
8642 REQUIRED_VARIABLE2 ...)
8643 The first argument (TEST_VARIABLE) is the name of the variable to be
8645 tested, if that variable is false nothing else is done. If TEST_VARI‐
8646 ABLE is true, then the next argument (RESULT_VARIABLE) is a variable
8647 that is set to true if all the required variables are set. The rest of
8648 the arguments are variables that must be true or not set to NOTFOUND to
8649 avoid an error. If any are not true, an error is reported.
8650 write_file
8652 Deprecated since version 3.0: Use the file(WRITE) command instead.
8653 write_file(filename "message to write"... [APPEND])
8656 The first argument is the file name, the rest of the arguments are mes‐
8658 sages to write. If the argument APPEND is specified, then the message
8659 will be appended.
8660 NOTE 1: file(WRITE) and file(APPEND) do exactly the same as this one
8662 but add some more functionality.
8663 NOTE 2: When using write_file the produced file cannot be used as an
8665 input to CMake (CONFIGURE_FILE, source file …) because it will lead to
8666 an infinite loop. Use configure_file() if you want to generate input
8667 files to CMake.
8668
8670 2000-2020 Kitware, Inc. and Contributors
86713.17.2 Apr 28, 2020 CMAKE-COMMANDS(7)