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 loop 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 │ │ megabytes │
45 ├──────────────────────────┼────────────────────────────┤
46 │AVAILABLE_VIRTUAL_MEMORY │ Available virtual memory │
47 │ │ in megabytes │
48 ├──────────────────────────┼────────────────────────────┤
49 │TOTAL_PHYSICAL_MEMORY │ Total physical memory in │
50 │ │ megabytes │
51 ├──────────────────────────┼────────────────────────────┤
52 │AVAILABLE_PHYSICAL_MEMORY │ Available physical memory │
53 │ │ in megabytes │
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 porcessor supports │
64 │ │ Ext. MMX instructions │
65 └──────────────────────────┴────────────────────────────┘
66 │HAS_SSE │ One if porcessor supports │
68 │ │ SSE instructions │
69 ├──────────────────────────┼────────────────────────────┤
70 │HAS_SSE2 │ One if porcessor supports │
71 │ │ SSE2 instructions │
72 ├──────────────────────────┼────────────────────────────┤
73 │HAS_SSE_FP │ One if porcessor supports │
74 │ │ SSE FP instructions │
75 ├──────────────────────────┼────────────────────────────┤
76 │HAS_SSE_MMX │ One if porcessor supports │
77 │ │ SSE MMX instructions │
78 ├──────────────────────────┼────────────────────────────┤
79 │HAS_AMD_3DNOW │ One if porcessor supports │
80 │ │ 3DNow instructions │
81 ├──────────────────────────┼────────────────────────────┤
82 │HAS_AMD_3DNOW_PLUS │ One if porcessor 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 cmake_minimum_required
111 Set the minimum required version of cmake for a project and update
112 Policy Settings to match the version given:
113 cmake_minimum_required(VERSION major.minor[.patch[.tweak]]
115 [FATAL_ERROR])
116 If the current version of CMake is lower than that required it will
118 stop processing the project and report an error.
119 The FATAL_ERROR option is accepted but ignored by CMake 2.6 and higher.
121 It should be specified so CMake versions 2.4 and lower fail with an
122 error instead of just a warning.
123 NOTE:
125 Call the cmake_minimum_required() command at the beginning of the
126 top-level CMakeLists.txt file even before calling the project() com‐
127 mand. It is important to establish version and policy settings
128 before invoking other commands whose behavior they may affect. See
129 also policy CMP0000.
130 Calling cmake_minimum_required() inside a function() limits some
132 effects to the function scope when invoked. Such calls should not
133 be made with the intention of having global effects.
134 Policy Settings
136 The cmake_minimum_required(VERSION) command implicitly invokes the
137 cmake_policy(VERSION) command to specify that the current project code
138 is written for the given version of CMake. All policies introduced in
139 the specified version or earlier will be set to use NEW behavior. All
140 policies introduced after the specified version will be unset. This
141 effectively requests behavior preferred as of a given CMake version and
142 tells newer CMake versions to warn about their new policies.
143 When a version higher than 2.4 is specified the command implicitly
145 invokes:
146 cmake_policy(VERSION major[.minor[.patch[.tweak]]])
148 which sets the cmake policy version level to the version specified.
150 When version 2.4 or lower is given the command implicitly invokes:
151 cmake_policy(VERSION 2.4)
153 which enables compatibility features for CMake 2.4 and lower.
155 cmake_parse_arguments
157 cmake_parse_arguments is intended to be used in macros or functions for
158 parsing the arguments given to that macro or function. It processes
159 the arguments and defines a set of variables which hold the values of
160 the respective options.
161 cmake_parse_arguments(<prefix> <options> <one_value_keywords>
163 <multi_value_keywords> args...)
164 cmake_parse_arguments(PARSE_ARGV N <prefix> <options> <one_value_keywords>
166 <multi_value_keywords>)
167 The first signature reads processes arguments passed in the args....
169 This may be used in either a macro() or a function().
170 The PARSE_ARGV signature is only for use in a function() body. In this
172 case the arguments that are parsed come from the ARGV# variables of the
173 calling function. The parsing starts with the Nth argument, where N is
174 an unsigned integer. This allows for the values to have special char‐
175 acters like ; in them.
176 The <options> argument contains all options for the respective macro,
178 i.e. keywords which can be used when calling the macro without any
179 value following, like e.g. the OPTIONAL keyword of the install() com‐
180 mand.
181 The <one_value_keywords> argument contains all keywords for this macro
183 which are followed by one value, like e.g. DESTINATION keyword of the
184 install() command.
185 The <multi_value_keywords> argument contains all keywords for this
187 macro which can be followed by more than one value, like e.g. the TAR‐
188 GETS or FILES keywords of the install() command.
189 NOTE:
191 All keywords shall be unique. I.e. every keyword shall only be spec‐
192 ified once in either <options>, <one_value_keywords> or
193 <multi_value_keywords>. A warning will be emitted if uniqueness is
194 violated.
195 When done, cmake_parse_arguments will consider for each of the keywords
197 listed in <options>, <one_value_keywords> and <multi_value_keywords> a
198 variable composed of the given <prefix> followed by "_" and the name of
199 the respective keyword. These variables will then hold the respective
200 value from the argument list or be undefined if the associated option
201 could not be found. For the <options> keywords, these will always be
202 defined, to TRUE or FALSE, whether the option is in the argument list
203 or not.
204 All remaining arguments are collected in a variable <pre‐
206 fix>_UNPARSED_ARGUMENTS that will be undefined if all argument where
207 recognized. This can be checked afterwards to see whether your macro
208 was called with unrecognized parameters.
209 As an example here a my_install() macro, which takes similar arguments
211 as the real install() command:
212 macro(my_install)
214 set(options OPTIONAL FAST)
215 set(oneValueArgs DESTINATION RENAME)
216 set(multiValueArgs TARGETS CONFIGURATIONS)
217 cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
218 "${multiValueArgs}" ${ARGN} )
219 # ...
221 Assume my_install() has been called like this:
223 my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub)
225 After the cmake_parse_arguments call the macro will have set or unde‐
227 fined the following variables:
228 MY_INSTALL_OPTIONAL = TRUE
230 MY_INSTALL_FAST = FALSE # was not used in call to my_install
231 MY_INSTALL_DESTINATION = "bin"
232 MY_INSTALL_RENAME <UNDEFINED> # was not used
233 MY_INSTALL_TARGETS = "foo;bar"
234 MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
235 MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
236 You can then continue and process these variables.
238 Keywords terminate lists of values, e.g. if directly after a
240 one_value_keyword another recognized keyword follows, this is inter‐
241 preted as the beginning of the new option. E.g. my_install(TARGETS
242 foo DESTINATION OPTIONAL) would result in MY_INSTALL_DESTINATION set to
243 "OPTIONAL", but as OPTIONAL is a keyword itself MY_INSTALL_DESTINATION
244 will be empty and MY_INSTALL_OPTIONAL will therefore be set to TRUE.
245 cmake_policy
247 Manage CMake Policy settings. See the cmake-policies(7) manual for
248 defined policies.
249 As CMake evolves it is sometimes necessary to change existing behavior
251 in order to fix bugs or improve implementations of existing features.
252 The CMake Policy mechanism is designed to help keep existing projects
253 building as new versions of CMake introduce changes in behavior. Each
254 new policy (behavioral change) is given an identifier of the form
255 CMP<NNNN> where <NNNN> is an integer index. Documentation associated
256 with each policy describes the OLD and NEW behavior and the reason the
257 policy was introduced. Projects may set each policy to select the
258 desired behavior. When CMake needs to know which behavior to use it
259 checks for a setting specified by the project. If no setting is avail‐
260 able the OLD behavior is assumed and a warning is produced requesting
261 that the policy be set.
262 Setting Policies by CMake Version
264 The cmake_policy command is used to set policies to OLD or NEW behav‐
265 ior. While setting policies individually is supported, we encourage
266 projects to set policies based on CMake versions:
267 cmake_policy(VERSION major.minor[.patch[.tweak]])
269 Specify that the current CMake code is written for the given version of
271 CMake. All policies introduced in the specified version or earlier
272 will be set to use NEW behavior. All policies introduced after the
273 specified version will be unset (unless the CMAKE_POL‐
274 ICY_DEFAULT_CMP<NNNN> variable sets a default). This effectively
275 requests behavior preferred as of a given CMake version and tells newer
276 CMake versions to warn about their new policies. The policy version
277 specified must be at least 2.4 or the command will report an error.
278 Note that the cmake_minimum_required(VERSION) command implicitly calls
280 cmake_policy(VERSION) too.
281 Setting Policies Explicitly
283 cmake_policy(SET CMP<NNNN> NEW)
284 cmake_policy(SET CMP<NNNN> OLD)
285 Tell CMake to use the OLD or NEW behavior for a given policy. Projects
287 depending on the old behavior of a given policy may silence a policy
288 warning by setting the policy state to OLD. Alternatively one may fix
289 the project to work with the new behavior and set the policy state to
290 NEW.
291 NOTE:
293 The OLD behavior of a policy is deprecated by definition and may be
294 removed in a future version of CMake.
295 Checking Policy Settings
297 cmake_policy(GET CMP<NNNN> <variable>)
298 Check whether a given policy is set to OLD or NEW behavior. The output
300 <variable> value will be OLD or NEW if the policy is set, and empty
301 otherwise.
302 CMake Policy Stack
304 CMake keeps policy settings on a stack, so changes made by the
305 cmake_policy command affect only the top of the stack. A new entry on
306 the policy stack is managed automatically for each subdirectory to pro‐
307 tect its parents and siblings. CMake also manages a new entry for
308 scripts loaded by include() and find_package() commands except when
309 invoked with the NO_POLICY_SCOPE option (see also policy CMP0011). The
310 cmake_policy command provides an interface to manage custom entries on
311 the policy stack:
312 cmake_policy(PUSH)
314 cmake_policy(POP)
315 Each PUSH must have a matching POP to erase any changes. This is use‐
317 ful to make temporary changes to policy settings. Calls to the
318 cmake_minimum_required(VERSION), cmake_policy(VERSION), or cmake_pol‐
319 icy(SET) commands influence only the current top of the policy stack.
320 Commands created by the function() and macro() commands record policy
322 settings when they are created and use the pre-record policies when
323 they are invoked. If the function or macro implementation sets poli‐
324 cies, the changes automatically propagate up through callers until they
325 reach the closest nested policy stack entry.
326 configure_file
328 Copy a file to another location and modify its contents.
329 configure_file(<input> <output>
331 [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
332 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
333 Copies an <input> file to an <output> file and substitutes variable
335 values referenced as @VAR@ or ${VAR} in the input file content. Each
336 variable reference will be replaced with the current value of the vari‐
337 able, or the empty string if the variable is not defined. Furthermore,
338 input lines of the form:
339 #cmakedefine VAR ...
341 will be replaced with either:
343 #define VAR ...
345 or:
347 /* #undef VAR */
349 depending on whether VAR is set in CMake to any value not considered a
351 false constant by the if() command. The “…” content on the line after
352 the variable name, if any, is processed as above. Input file lines of
353 the form #cmakedefine01 VAR will be replaced with either #define VAR 1
354 or #define VAR 0 similarly. The result lines (with the exception of
355 the #undef comments) can be indented using spaces and/or tabs between
356 the # character and the cmakedefine or cmakedefine01 words. This white‐
357 space indentation will be preserved in the output lines:
358 # cmakedefine VAR
360 # cmakedefine01 VAR
361 will be replaced, if VAR is defined, with:
363 # define VAR
365 # define VAR 1
366 If the input file is modified the build system will re-run CMake to
368 re-configure the file and generate the build system again. The gener‐
369 ated file is modified and its timestamp updated on subsequent cmake
370 runs only if its content is changed.
371 The arguments are:
373 <input>
375 Path to the input file. A relative path is treated with respect
376 to the value of CMAKE_CURRENT_SOURCE_DIR. The input path must
377 be a file, not a directory.
378 <output>
380 Path to the output file or directory. A relative path is
381 treated with respect to the value of CMAKE_CURRENT_BINARY_DIR.
382 If the path names an existing directory the output file is
383 placed in that directory with the same file name as the input
384 file.
385 COPYONLY
387 Copy the file without replacing any variable references or other
388 content. This option may not be used with NEWLINE_STYLE.
389 ESCAPE_QUOTES
391 Escape any substituted quotes with backslashes (C-style).
392 @ONLY Restrict variable replacement to references of the form @VAR@.
394 This is useful for configuring scripts that use ${VAR} syntax.
395 NEWLINE_STYLE <style>
397 Specify the newline style for the output file. Specify UNIX or
398 LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n new‐
399 lines. This option may not be used with COPYONLY.
400 Example
402 Consider a source tree containing a foo.h.in file:
403 #cmakedefine FOO_ENABLE
405 #cmakedefine FOO_STRING "@FOO_STRING@"
406 An adjacent CMakeLists.txt may use configure_file to configure the
408 header:
409 option(FOO_ENABLE "Enable Foo" ON)
411 if(FOO_ENABLE)
412 set(FOO_STRING "foo")
413 endif()
414 configure_file(foo.h.in foo.h @ONLY)
415 This creates a foo.h in the build directory corresponding to this
417 source directory. If the FOO_ENABLE option is on, the configured file
418 will contain:
419 #define FOO_ENABLE
421 #define FOO_STRING "foo"
422 Otherwise it will contain:
424 /* #undef FOO_ENABLE */
426 /* #undef FOO_STRING */
427 One may then use the include_directories() command to specify the out‐
429 put directory as an include directory:
430 include_directories(${CMAKE_CURRENT_BINARY_DIR})
432 so that sources may include the header as #include <foo.h>.
434 continue
436 Continue to the top of enclosing foreach or while loop.
437 continue()
439 The continue command allows a cmake script to abort the rest of a block
441 in a foreach() or while() loop, and start at the top of the next itera‐
442 tion. See also the break() command.
443 elseif
445 Starts the elseif portion of an if block.
446 elseif(expression)
448 See the if() command.
450 else
452 Starts the else portion of an if block.
453 else(expression)
455 See the if() command.
457 endforeach
459 Ends a list of commands in a foreach block.
460 endforeach(expression)
462 See the foreach() command.
464 endfunction
466 Ends a list of commands in a function block.
467 endfunction(expression)
469 See the function() command.
471 endif
473 Ends a list of commands in an if block.
474 endif(expression)
476 See the if() command.
478 endmacro
480 Ends a list of commands in a macro block.
481 endmacro(expression)
483 See the macro() command.
485 endwhile
487 Ends a list of commands in a while block.
488 endwhile(expression)
490 See the while() command.
492 execute_process
494 Execute one or more child processes.
495 execute_process(COMMAND <cmd1> [args1...]]
497 [COMMAND <cmd2> [args2...] [...]]
498 [WORKING_DIRECTORY <directory>]
499 [TIMEOUT <seconds>]
500 [RESULT_VARIABLE <variable>]
501 [RESULTS_VARIABLE <variable>]
502 [OUTPUT_VARIABLE <variable>]
503 [ERROR_VARIABLE <variable>]
504 [INPUT_FILE <file>]
505 [OUTPUT_FILE <file>]
506 [ERROR_FILE <file>]
507 [OUTPUT_QUIET]
508 [ERROR_QUIET]
509 [OUTPUT_STRIP_TRAILING_WHITESPACE]
510 [ERROR_STRIP_TRAILING_WHITESPACE]
511 [ENCODING <name>])
512 Runs the given sequence of one or more commands in parallel with the
514 standard output of each process piped to the standard input of the
515 next. A single standard error pipe is used for all processes.
516 Options:
518 COMMAND
520 A child process command line.
521 CMake executes the child process using operating system APIs
523 directly. All arguments are passed VERBATIM to the child
524 process. No intermediate shell is used, so shell operators such
525 as > are treated as normal arguments. (Use the INPUT_*, OUT‐
526 PUT_*, and ERROR_* options to redirect stdin, stdout, and
527 stderr.)
528 If a sequential execution of multiple commands is required, use
530 multiple execute_process() calls with a single COMMAND argument.
531 WORKING_DIRECTORY
533 The named directory will be set as the current working directory
534 of the child processes.
535 TIMEOUT
537 The child processes will be terminated if they do not finish in
538 the specified number of seconds (fractions are allowed).
539 RESULT_VARIABLE
541 The variable will be set to contain the result of last child
542 process. This will be an integer return code from the last
543 child or a string describing an error condition.
544 RESULTS_VARIABLE <variable>
546 The variable will be set to contain the result of all processes
547 as a ;-list, in order of the given COMMAND arguments. Each
548 entry will be an integer return code from the corresponding
549 child or a string describing an error condition.
550 OUTPUT_VARIABLE, ERROR_VARIABLE
552 The variable named will be set with the contents of the standard
553 output and standard error pipes, respectively. If the same
554 variable is named for both pipes their output will be merged in
555 the order produced.
556 INPUT_FILE, OUTPUT_FILE, ERROR_FILE
558 The file named will be attached to the standard input of the
559 first process, standard output of the last process, or standard
560 error of all processes, respectively. If the same file is named
561 for both output and error then it will be used for both.
562 OUTPUT_QUIET, ERROR_QUIET
564 The standard output or standard error results will be quietly
565 ignored.
566 ENCODING <name>
568 On Windows, the encoding that is used to decode output from the
569 process. Ignored on other platforms. Valid encoding names are:
570 NONE Perform no decoding. This assumes that the process out‐
572 put is encoded in the same way as CMake’s internal encod‐
573 ing (UTF-8). This is the default.
574 AUTO Use the current active console’s codepage or if that
576 isn’t available then use ANSI.
577 ANSI Use the ANSI codepage.
579 OEM Use the original equipment manufacturer (OEM) code page.
581 UTF8 or UTF-8
583 Use the UTF-8 codepage. Prior to CMake 3.11.0, only UTF8
584 was accepted for this encoding. In CMake 3.11.0, UTF-8
585 was added for consistency with the UTF-8 RFC naming con‐
586 vention.
587 If more than one OUTPUT_* or ERROR_* option is given for the same pipe
589 the precedence is not specified. If no OUTPUT_* or ERROR_* options are
590 given the output will be shared with the corresponding pipes of the
591 CMake process itself.
592 The execute_process() command is a newer more powerful version of
594 exec_program(), but the old command has been kept for compatibility.
595 Both commands run while CMake is processing the project prior to build
596 system generation. Use add_custom_target() and add_custom_command() to
597 create custom commands that run at build time.
598 file
600 File manipulation command.
601 ----
604 file(WRITE <filename> <content>...)
608 file(APPEND <filename> <content>...)
609 Write <content> into a file called <filename>. If the file does not
611 exist, it will be created. If the file already exists, WRITE mode will
612 overwrite it and APPEND mode will append to the end. Any directories
613 in the path specified by <filename> that do not exist will be created.
614 If the file is a build input, use the configure_file() command to
616 update the file only when its content changes.
617 ----
620 file(READ <filename> <variable>
624 [OFFSET <offset>] [LIMIT <max-in>] [HEX])
625 Read content from a file called <filename> and store it in a <vari‐
627 able>. Optionally start from the given <offset> and read at most
628 <max-in> bytes. The HEX option causes data to be converted to a hexa‐
629 decimal representation (useful for binary data).
630 ----
633 file(STRINGS <filename> <variable> [<options>...])
637 Parse a list of ASCII strings from <filename> and store it in <vari‐
639 able>. Binary data in the file are ignored. Carriage return (\r, CR)
640 characters are ignored. The options are:
641 LENGTH_MAXIMUM <max-len>
643 Consider only strings of at most a given length.
644 LENGTH_MINIMUM <min-len>
646 Consider only strings of at least a given length.
647 LIMIT_COUNT <max-num>
649 Limit the number of distinct strings to be extracted.
650 LIMIT_INPUT <max-in>
652 Limit the number of input bytes to read from the file.
653 LIMIT_OUTPUT <max-out>
655 Limit the number of total bytes to store in the <variable>.
656 NEWLINE_CONSUME
658 Treat newline characters (\n, LF) as part of string content
659 instead of terminating at them.
660 NO_HEX_CONVERSION
662 Intel Hex and Motorola S-record files are automatically con‐
663 verted to binary while reading unless this option is given.
664 REGEX <regex>
666 Consider only strings that match the given regular expression.
667 ENCODING <encoding-type>
669 Consider strings of a given encoding. Currently supported
670 encodings are: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE.
671 If the ENCODING option is not provided and the file has a Byte
672 Order Mark, the ENCODING option will be defaulted to respect the
673 Byte Order Mark.
674 For example, the code
676 file(STRINGS myfile.txt myfile)
678 stores a list in the variable myfile in which each item is a line from
680 the input file.
681 ----
684 file(<HASH> <filename> <variable>)
688 Compute a cryptographic hash of the content of <filename> and store it
690 in a <variable>. The supported <HASH> algorithm names are those listed
691 by the string(<HASH>) command.
692 ----
695 file(GLOB <variable>
699 [LIST_DIRECTORIES true|false] [RELATIVE <path>]
700 [<globbing-expressions>...])
701 file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
702 [LIST_DIRECTORIES true|false] [RELATIVE <path>]
703 [<globbing-expressions>...])
704 Generate a list of files that match the <globbing-expressions> and
706 store it into the <variable>. Globbing expressions are similar to reg‐
707 ular expressions, but much simpler. If RELATIVE flag is specified, the
708 results will be returned as relative paths to the given path. The
709 results will be ordered lexicographically.
710 By default GLOB lists directories - directories are omitted in result
712 if LIST_DIRECTORIES is set to false.
713 NOTE:
715 We do not recommend using GLOB to collect a list of source files
716 from your source tree. If no CMakeLists.txt file changes when a
717 source is added or removed then the generated build system cannot
718 know when to ask CMake to regenerate.
719 Examples of globbing expressions include:
721 *.cxx - match all files with extension cxx
723 *.vt? - match all files with extension vta,...,vtz
724 f[3-5].txt - match files f3.txt, f4.txt, f5.txt
725 The GLOB_RECURSE mode will traverse all the subdirectories of the
727 matched directory and match the files. Subdirectories that are sym‐
728 links are only traversed if FOLLOW_SYMLINKS is given or policy CMP0009
729 is not set to NEW.
730 By default GLOB_RECURSE omits directories from result list - setting
732 LIST_DIRECTORIES to true adds directories to result list. If FOL‐
733 LOW_SYMLINKS is given or policy CMP0009 is not set to OLD then
734 LIST_DIRECTORIES treats symlinks as directories.
735 Examples of recursive globbing include:
737 /dir/*.py - match all python files in /dir and subdirectories
739 ----
742 file(RENAME <oldname> <newname>)
746 Move a file or directory within a filesystem from <oldname> to <new‐
748 name>, replacing the destination atomically.
749 ----
752 file(REMOVE [<files>...])
756 file(REMOVE_RECURSE [<files>...])
757 Remove the given files. The REMOVE_RECURSE mode will remove the given
759 files and directories, also non-empty directories. No error is emitted
760 if a given file does not exist.
761 ----
764 file(MAKE_DIRECTORY [<directories>...])
768 Create the given directories and their parents as needed.
770 ----
773 file(RELATIVE_PATH <variable> <directory> <file>)
777 Compute the relative path from a <directory> to a <file> and store it
779 in the <variable>.
780 ----
783 file(TO_CMAKE_PATH "<path>" <variable>)
787 file(TO_NATIVE_PATH "<path>" <variable>)
788 The TO_CMAKE_PATH mode converts a native <path> into a cmake-style path
790 with forward-slashes (/). The input can be a single path or a system
791 search path like $ENV{PATH}. A search path will be converted to a
792 cmake-style list separated by ; characters.
793 The TO_NATIVE_PATH mode converts a cmake-style <path> into a native
795 path with platform-specific slashes (\ on Windows and / elsewhere).
796 Always use double quotes around the <path> to be sure it is treated as
798 a single argument to this command.
799 ----
802 file(DOWNLOAD <url> <file> [<options>...])
806 file(UPLOAD <file> <url> [<options>...])
807 The DOWNLOAD mode downloads the given <url> to a local <file>. The
809 UPLOAD mode uploads a local <file> to a given <url>.
810 Options to both DOWNLOAD and UPLOAD are:
812 INACTIVITY_TIMEOUT <seconds>
814 Terminate the operation after a period of inactivity.
815 LOG <variable>
817 Store a human-readable log of the operation in a variable.
818 SHOW_PROGRESS
820 Print progress information as status messages until the opera‐
821 tion is complete.
822 STATUS <variable>
824 Store the resulting status of the operation in a variable. The
825 status is a ; separated list of length 2. The first element is
826 the numeric return value for the operation, and the second ele‐
827 ment is a string value for the error. A 0 numeric error means
828 no error in the operation.
829 TIMEOUT <seconds>
831 Terminate the operation after a given total time has elapsed.
832 USERPWD <username>:<password>
834 Set username and password for operation.
835 HTTPHEADER <HTTP-header>
837 HTTP header for operation. Suboption can be repeated several
838 times.
839 NETRC <level>
841 Specify whether the .netrc file is to be used for operation. If
842 this option is not specified, the value of the CMAKE_NETRC vari‐
843 able will be used instead. Valid levels are:
844 IGNORED
846 The .netrc file is ignored. This is the default.
847 OPTIONAL
849 The .netrc file is optional, and information in the URL
850 is preferred. The file will be scanned to find which
851 ever information is not specified in the URL.
852 REQUIRED
854 The .netrc file is required, and information in the URL
855 is ignored.
856 NETRC_FILE <file>
858 Specify an alternative .netrc file to the one in your home
859 directory, if the NETRC level is OPTIONAL or REQUIRED. If this
860 option is not specified, the value of the CMAKE_NETRC_FILE vari‐
861 able will be used instead.
862 If neither NETRC option is given CMake will check variables CMAKE_NETRC
864 and CMAKE_NETRC_FILE, respectively.
865 Additional options to DOWNLOAD are:
867 EXPECTED_HASH ALGO=<value>
869 Verify that the downloaded content hash matches the expected value,
870 where ALGO is one of the algorithms supported by file(<HASH>). If
871 it does not match, the operation fails with an error.
872 EXPECTED_MD5 <value>
874 Historical short-hand for EXPECTED_HASH MD5=<value>.
875 TLS_VERIFY <ON|OFF>
877 Specify whether to verify the server certificate for https://
878 URLs. The default is to not verify.
879 TLS_CAINFO <file>
881 Specify a custom Certificate Authority file for https:// URLs.
882 For https:// URLs CMake must be built with OpenSSL support. TLS/SSL
884 certificates are not checked by default. Set TLS_VERIFY to ON to check
885 certificates and/or use EXPECTED_HASH to verify downloaded content. If
886 neither TLS option is given CMake will check variables CMAKE_TLS_VERIFY
887 and CMAKE_TLS_CAINFO, respectively.
888 ----
891 file(TIMESTAMP <filename> <variable> [<format>] [UTC])
895 Compute a string representation of the modification time of <filename>
897 and store it in <variable>. Should the command be unable to obtain a
898 timestamp variable will be set to the empty string (“”).
899 See the string(TIMESTAMP) command for documentation of the <format> and
901 UTC options.
902 ----
905 file(GENERATE OUTPUT output-file
909 <INPUT input-file|CONTENT content>
910 [CONDITION expression])
911 Generate an output file for each build configuration supported by the
913 current CMake Generator. Evaluate generator expressions from the input
914 content to produce the output content. The options are:
915 CONDITION <condition>
917 Generate the output file for a particular configuration only if
918 the condition is true. The condition must be either 0 or 1
919 after evaluating generator expressions.
920 CONTENT <content>
922 Use the content given explicitly as input.
923 INPUT <input-file>
925 Use the content from a given file as input. A relative path is
926 treated with respect to the value of CMAKE_CURRENT_SOURCE_DIR.
927 See policy CMP0070.
928 OUTPUT <output-file>
930 Specify the output file name to generate. Use generator expres‐
931 sions such as $<CONFIG> to specify a configuration-specific out‐
932 put file name. Multiple configurations may generate the same
933 output file only if the generated content is identical. Other‐
934 wise, the <output-file> must evaluate to an unique name for each
935 configuration. A relative path (after evaluating generator
936 expressions) is treated with respect to the value of CMAKE_CUR‐
937 RENT_BINARY_DIR. See policy CMP0070.
938 Exactly one CONTENT or INPUT option must be given. A specific OUTPUT
940 file may be named by at most one invocation of file(GENERATE). Gener‐
941 ated files are modified and their timestamp updated on subsequent cmake
942 runs only if their content is changed.
943 Note also that file(GENERATE) does not create the output file until the
945 generation phase. The output file will not yet have been written when
946 the file(GENERATE) command returns, it is written only after processing
947 all of a project’s CMakeLists.txt files.
948 ----
951 file(<COPY|INSTALL> <files>... DESTINATION <dir>
955 [FILE_PERMISSIONS <permissions>...]
956 [DIRECTORY_PERMISSIONS <permissions>...]
957 [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
958 [FILES_MATCHING]
959 [[PATTERN <pattern> | REGEX <regex>]
960 [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
961 The COPY signature copies files, directories, and symlinks to a desti‐
963 nation folder. Relative input paths are evaluated with respect to the
964 current source directory, and a relative destination is evaluated with
965 respect to the current build directory. Copying preserves input file
966 timestamps, and optimizes out a file if it exists at the destination
967 with the same timestamp. Copying preserves input permissions unless
968 explicit permissions or NO_SOURCE_PERMISSIONS are given (default is
969 USE_SOURCE_PERMISSIONS).
970 See the install(DIRECTORY) command for documentation of permissions,
972 FILES_MATCHING, PATTERN, REGEX, and EXCLUDE options. Copying directo‐
973 ries preserves the structure of their content even if options are used
974 to select a subset of files.
975 The INSTALL signature differs slightly from COPY: it prints status mes‐
977 sages (subject to the CMAKE_INSTALL_MESSAGE variable), and
978 NO_SOURCE_PERMISSIONS is default. Installation scripts generated by
979 the install() command use this signature (with some undocumented
980 options for internal use).
981 ----
984 file(LOCK <path> [DIRECTORY] [RELEASE]
988 [GUARD <FUNCTION|FILE|PROCESS>]
989 [RESULT_VARIABLE <variable>]
990 [TIMEOUT <seconds>])
991 Lock a file specified by <path> if no DIRECTORY option present and file
993 <path>/cmake.lock otherwise. File will be locked for scope defined by
994 GUARD option (default value is PROCESS). RELEASE option can be used to
995 unlock file explicitly. If option TIMEOUT is not specified CMake will
996 wait until lock succeed or until fatal error occurs. If TIMEOUT is set
997 to 0 lock will be tried once and result will be reported immediately.
998 If TIMEOUT is not 0 CMake will try to lock file for the period speci‐
999 fied by <seconds> value. Any errors will be interpreted as fatal if
1000 there is no RESULT_VARIABLE option. Otherwise result will be stored in
1001 <variable> and will be 0 on success or error message on failure.
1002 Note that lock is advisory - there is no guarantee that other processes
1004 will respect this lock, i.e. lock synchronize two or more CMake
1005 instances sharing some modifiable resources. Similar logic applied to
1006 DIRECTORY option - locking parent directory doesn’t prevent other LOCK
1007 commands to lock any child directory or file.
1008 Trying to lock file twice is not allowed. Any intermediate directories
1010 and file itself will be created if they not exist. GUARD and TIMEOUT
1011 options ignored on RELEASE operation.
1012 find_file
1014 A short-hand signature is:
1015 find_file (<VAR> name1 [path1 path2 ...])
1017 The general signature is:
1019 find_file (
1021 <VAR>
1022 name | NAMES name1 [name2 ...]
1023 [HINTS path1 [path2 ... ENV var]]
1024 [PATHS path1 [path2 ... ENV var]]
1025 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1026 [DOC "cache documentation string"]
1027 [NO_DEFAULT_PATH]
1028 [NO_CMAKE_PATH]
1029 [NO_CMAKE_ENVIRONMENT_PATH]
1030 [NO_SYSTEM_ENVIRONMENT_PATH]
1031 [NO_CMAKE_SYSTEM_PATH]
1032 [CMAKE_FIND_ROOT_PATH_BOTH |
1033 ONLY_CMAKE_FIND_ROOT_PATH |
1034 NO_CMAKE_FIND_ROOT_PATH]
1035 )
1036 This command is used to find a full path to named file. A cache entry
1038 named by <VAR> is created to store the result of this command. If the
1039 full path to a file is found the result is stored in the variable and
1040 the search will not be repeated unless the variable is cleared. If
1041 nothing is found, the result will be <VAR>-NOTFOUND, and the search
1042 will be attempted again the next time find_file is invoked with the
1043 same variable.
1044 Options include:
1046 NAMES Specify one or more possible names for the full path to a file.
1048 When using this to specify names with and without a version suf‐
1050 fix, we recommend specifying the unversioned name first so that
1051 locally-built packages can be found before those provided by
1052 distributions.
1053 HINTS, PATHS
1055 Specify directories to search in addition to the default loca‐
1056 tions. The ENV var sub-option reads paths from a system envi‐
1057 ronment variable.
1058 PATH_SUFFIXES
1060 Specify additional subdirectories to check below each directory
1061 location otherwise considered.
1062 DOC Specify the documentation string for the <VAR> cache entry.
1064 If NO_DEFAULT_PATH is specified, then no additional paths are added to
1066 the search. If NO_DEFAULT_PATH is not specified, the search process is
1067 as follows:
1068 1. Search paths specified in cmake-specific cache variables. These are
1070 intended to be used on the command line with a -DVAR=value. The
1071 values are interpreted as ;-lists. This can be skipped if
1072 NO_CMAKE_PATH is passed.
1073 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1075 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1076 · CMAKE_INCLUDE_PATH
1078 · CMAKE_FRAMEWORK_PATH
1080 2. Search paths specified in cmake-specific environment variables.
1082 These are intended to be set in the user’s shell configuration, and
1083 therefore use the host’s native path separator (; on Windows and :
1084 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1085 passed.
1086 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1088 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1089 · CMAKE_INCLUDE_PATH
1091 · CMAKE_FRAMEWORK_PATH
1093 3. Search the paths specified by the HINTS option. These should be
1095 paths computed by system introspection, such as a hint provided by
1096 the location of another item already found. Hard-coded guesses
1097 should be specified with the PATHS option.
1098 4. Search the standard system environment variables. This can be
1100 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1101 · Directories in INCLUDE. On Windows hosts: <prefix>/include/<arch>
1103 if CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/include for
1104 each <prefix>/[s]bin in PATH, and <entry>/include for other
1105 entries in PATH, and the directories in PATH itself.
1106 5. Search cmake variables defined in the Platform files for the current
1108 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed.
1109 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1111 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1112 · CMAKE_SYSTEM_INCLUDE_PATH
1114 · CMAKE_SYSTEM_FRAMEWORK_PATH
1116 6. Search the paths specified by the PATHS option or in the short-hand
1118 version of the command. These are typically hard-coded guesses.
1119 On OS X the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
1121 determine the order of preference between Apple-style and unix-style
1122 package components.
1123 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
1125 ries to be prepended to all other search directories. This effectively
1126 “re-roots” the entire search under given locations. Paths which are
1127 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
1128 ing, because that variable is always a path on the host system. By
1129 default the CMAKE_FIND_ROOT_PATH is empty.
1130 The CMAKE_SYSROOT variable can also be used to specify exactly one
1132 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
1133 effects. See the documentation for that variable for more.
1134 These variables are especially useful when cross-compiling to point to
1136 the root directory of the target environment and CMake will search
1137 there too. By default at first the directories listed in
1138 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
1139 searched, and then the non-rooted directories will be searched. The
1140 default behavior can be adjusted by setting
1141 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually over‐
1142 ridden on a per-call basis using options:
1143 CMAKE_FIND_ROOT_PATH_BOTH
1145 Search in the order described above.
1146 NO_CMAKE_FIND_ROOT_PATH
1148 Do not use the CMAKE_FIND_ROOT_PATH variable.
1149 ONLY_CMAKE_FIND_ROOT_PATH
1151 Search only the re-rooted directories and directories below
1152 CMAKE_STAGING_PREFIX.
1153 The default search order is designed to be most-specific to least-spe‐
1155 cific for common use cases. Projects may override the order by simply
1156 calling the command multiple times and using the NO_* options:
1157 find_file (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1159 find_file (<VAR> NAMES name)
1160 Once one of the calls succeeds the result variable will be set and
1162 stored in the cache so that no call will search again.
1163 find_library
1165 A short-hand signature is:
1166 find_library (<VAR> name1 [path1 path2 ...])
1168 The general signature is:
1170 find_library (
1172 <VAR>
1173 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
1174 [HINTS path1 [path2 ... ENV var]]
1175 [PATHS path1 [path2 ... ENV var]]
1176 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1177 [DOC "cache documentation string"]
1178 [NO_DEFAULT_PATH]
1179 [NO_CMAKE_PATH]
1180 [NO_CMAKE_ENVIRONMENT_PATH]
1181 [NO_SYSTEM_ENVIRONMENT_PATH]
1182 [NO_CMAKE_SYSTEM_PATH]
1183 [CMAKE_FIND_ROOT_PATH_BOTH |
1184 ONLY_CMAKE_FIND_ROOT_PATH |
1185 NO_CMAKE_FIND_ROOT_PATH]
1186 )
1187 This command is used to find a library. A cache entry named by <VAR>
1189 is created to store the result of this command. If the library is
1190 found the result is stored in the variable and the search will not be
1191 repeated unless the variable is cleared. If nothing is found, the
1192 result will be <VAR>-NOTFOUND, and the search will be attempted again
1193 the next time find_library is invoked with the same variable.
1194 Options include:
1196 NAMES Specify one or more possible names for the library.
1198 When using this to specify names with and without a version suf‐
1200 fix, we recommend specifying the unversioned name first so that
1201 locally-built packages can be found before those provided by
1202 distributions.
1203 HINTS, PATHS
1205 Specify directories to search in addition to the default loca‐
1206 tions. The ENV var sub-option reads paths from a system envi‐
1207 ronment variable.
1208 PATH_SUFFIXES
1210 Specify additional subdirectories to check below each directory
1211 location otherwise considered.
1212 DOC Specify the documentation string for the <VAR> cache entry.
1214 If NO_DEFAULT_PATH is specified, then no additional paths are added to
1216 the search. If NO_DEFAULT_PATH is not specified, the search process is
1217 as follows:
1218 1. Search paths specified in cmake-specific cache variables. These are
1220 intended to be used on the command line with a -DVAR=value. The
1221 values are interpreted as ;-lists. This can be skipped if
1222 NO_CMAKE_PATH is passed.
1223 · <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1225 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1226 · CMAKE_LIBRARY_PATH
1228 · CMAKE_FRAMEWORK_PATH
1230 2. Search paths specified in cmake-specific environment variables.
1232 These are intended to be set in the user’s shell configuration, and
1233 therefore use the host’s native path separator (; on Windows and :
1234 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1235 passed.
1236 · <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1238 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1239 · CMAKE_LIBRARY_PATH
1241 · CMAKE_FRAMEWORK_PATH
1243 3. Search the paths specified by the HINTS option. These should be
1245 paths computed by system introspection, such as a hint provided by
1246 the location of another item already found. Hard-coded guesses
1247 should be specified with the PATHS option.
1248 4. Search the standard system environment variables. This can be
1250 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1251 · Directories in LIB. On Windows hosts: <prefix>/lib/<arch> if
1253 CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/lib for each <pre‐
1254 fix>/[s]bin in PATH, and <entry>/lib for other entries in PATH,
1255 and the directories in PATH itself.
1256 5. Search cmake variables defined in the Platform files for the current
1258 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed.
1259 · <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1261 <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1262 · CMAKE_SYSTEM_LIBRARY_PATH
1264 · CMAKE_SYSTEM_FRAMEWORK_PATH
1266 6. Search the paths specified by the PATHS option or in the short-hand
1268 version of the command. These are typically hard-coded guesses.
1269 On OS X the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
1271 determine the order of preference between Apple-style and unix-style
1272 package components.
1273 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
1275 ries to be prepended to all other search directories. This effectively
1276 “re-roots” the entire search under given locations. Paths which are
1277 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
1278 ing, because that variable is always a path on the host system. By
1279 default the CMAKE_FIND_ROOT_PATH is empty.
1280 The CMAKE_SYSROOT variable can also be used to specify exactly one
1282 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
1283 effects. See the documentation for that variable for more.
1284 These variables are especially useful when cross-compiling to point to
1286 the root directory of the target environment and CMake will search
1287 there too. By default at first the directories listed in
1288 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
1289 searched, and then the non-rooted directories will be searched. The
1290 default behavior can be adjusted by setting
1291 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY. This behavior can be manually over‐
1292 ridden on a per-call basis using options:
1293 CMAKE_FIND_ROOT_PATH_BOTH
1295 Search in the order described above.
1296 NO_CMAKE_FIND_ROOT_PATH
1298 Do not use the CMAKE_FIND_ROOT_PATH variable.
1299 ONLY_CMAKE_FIND_ROOT_PATH
1301 Search only the re-rooted directories and directories below
1302 CMAKE_STAGING_PREFIX.
1303 The default search order is designed to be most-specific to least-spe‐
1305 cific for common use cases. Projects may override the order by simply
1306 calling the command multiple times and using the NO_* options:
1307 find_library (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1309 find_library (<VAR> NAMES name)
1310 Once one of the calls succeeds the result variable will be set and
1312 stored in the cache so that no call will search again.
1313 When more than one value is given to the NAMES option this command by
1315 default will consider one name at a time and search every directory for
1316 it. The NAMES_PER_DIR option tells this command to consider one direc‐
1317 tory at a time and search for all names in it.
1318 Each library name given to the NAMES option is first considered as a
1320 library file name and then considered with platform-specific prefixes
1321 (e.g. lib) and suffixes (e.g. .so). Therefore one may specify library
1322 file names such as libfoo.a directly. This can be used to locate
1323 static libraries on UNIX-like systems.
1324 If the library found is a framework, then <VAR> will be set to the full
1326 path to the framework <fullPath>/A.framework. When a full path to a
1327 framework is used as a library, CMake will use a -framework A, and a
1328 -F<fullPath> to link the framework to the target.
1329 If the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable is set all search
1331 paths will be tested as normal, with the suffix appended, and with all
1332 matches of lib/ replaced with lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUF‐
1333 FIX}/. This variable overrides the FIND_LIBRARY_USE_LIB32_PATHS,
1334 FIND_LIBRARY_USE_LIBX32_PATHS, and FIND_LIBRARY_USE_LIB64_PATHS global
1335 properties.
1336 If the FIND_LIBRARY_USE_LIB32_PATHS global property is set all search
1338 paths will be tested as normal, with 32/ appended, and with all matches
1339 of lib/ replaced with lib32/. This property is automatically set for
1340 the platforms that are known to need it if at least one of the lan‐
1341 guages supported by the project() command is enabled.
1342 If the FIND_LIBRARY_USE_LIBX32_PATHS global property is set all search
1344 paths will be tested as normal, with x32/ appended, and with all
1345 matches of lib/ replaced with libx32/. This property is automatically
1346 set for the platforms that are known to need it if at least one of the
1347 languages supported by the project() command is enabled.
1348 If the FIND_LIBRARY_USE_LIB64_PATHS global property is set all search
1350 paths will be tested as normal, with 64/ appended, and with all matches
1351 of lib/ replaced with lib64/. This property is automatically set for
1352 the platforms that are known to need it if at least one of the lan‐
1353 guages supported by the project() command is enabled.
1354 find_package
1356 Load settings for an external project.
1357 find_package(<package> [version] [EXACT] [QUIET] [MODULE]
1359 [REQUIRED] [[COMPONENTS] [components...]]
1360 [OPTIONAL_COMPONENTS components...]
1361 [NO_POLICY_SCOPE])
1362 Finds and loads settings from an external project. <package>_FOUND
1364 will be set to indicate whether the package was found. When the pack‐
1365 age is found package-specific information is provided through variables
1366 and Imported Targets documented by the package itself. The QUIET
1367 option disables messages if the package cannot be found. The MODULE
1368 option disables the second signature documented below. The REQUIRED
1369 option stops processing with an error message if the package cannot be
1370 found.
1371 A package-specific list of required components may be listed after the
1373 COMPONENTS option (or after the REQUIRED option if present). Addi‐
1374 tional optional components may be listed after OPTIONAL_COMPONENTS.
1375 Available components and their influence on whether a package is con‐
1376 sidered to be found are defined by the target package.
1377 The [version] argument requests a version with which the package found
1379 should be compatible (format is major[.minor[.patch[.tweak]]]). The
1380 EXACT option requests that the version be matched exactly. If no [ver‐
1381 sion] and/or component list is given to a recursive invocation inside a
1382 find-module, the corresponding arguments are forwarded automatically
1383 from the outer call (including the EXACT flag for [version]). Version
1384 support is currently provided only on a package-by-package basis
1385 (details below).
1386 User code should generally look for packages using the above simple
1388 signature. The remainder of this command documentation specifies the
1389 full command signature and details of the search process. Project
1390 maintainers wishing to provide a package to be found by this command
1391 are encouraged to read on.
1392 The command has two modes by which it searches for packages: “Module”
1394 mode and “Config” mode. Module mode is available when the command is
1395 invoked with the above reduced signature. CMake searches for a file
1396 called Find<package>.cmake in the CMAKE_MODULE_PATH followed by the
1397 CMake installation. If the file is found, it is read and processed by
1398 CMake. It is responsible for finding the package, checking the ver‐
1399 sion, and producing any needed messages. Many find-modules provide
1400 limited or no support for versioning; check the module documentation.
1401 If no module is found and the MODULE option is not given the command
1402 proceeds to Config mode.
1403 The complete Config mode command signature is:
1405 find_package(<package> [version] [EXACT] [QUIET]
1407 [REQUIRED] [[COMPONENTS] [components...]]
1408 [CONFIG|NO_MODULE]
1409 [NO_POLICY_SCOPE]
1410 [NAMES name1 [name2 ...]]
1411 [CONFIGS config1 [config2 ...]]
1412 [HINTS path1 [path2 ... ]]
1413 [PATHS path1 [path2 ... ]]
1414 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1415 [NO_DEFAULT_PATH]
1416 [NO_CMAKE_PATH]
1417 [NO_CMAKE_ENVIRONMENT_PATH]
1418 [NO_SYSTEM_ENVIRONMENT_PATH]
1419 [NO_CMAKE_PACKAGE_REGISTRY]
1420 [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
1421 [NO_CMAKE_SYSTEM_PATH]
1422 [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
1423 [CMAKE_FIND_ROOT_PATH_BOTH |
1424 ONLY_CMAKE_FIND_ROOT_PATH |
1425 NO_CMAKE_FIND_ROOT_PATH])
1426 The CONFIG option may be used to skip Module mode explicitly and switch
1428 to Config mode. It is synonymous to using NO_MODULE. Config mode is
1429 also implied by use of options not specified in the reduced signature.
1430 Config mode attempts to locate a configuration file provided by the
1432 package to be found. A cache entry called <package>_DIR is created to
1433 hold the directory containing the file. By default the command
1434 searches for a package with the name <package>. If the NAMES option is
1435 given the names following it are used instead of <package>. The com‐
1436 mand searches for a file called <name>Config.cmake or
1437 <lower-case-name>-config.cmake for each name specified. A replacement
1438 set of possible configuration file names may be given using the CONFIGS
1439 option. The search procedure is specified below. Once found, the con‐
1440 figuration file is read and processed by CMake. Since the file is pro‐
1441 vided by the package it already knows the location of package contents.
1442 The full path to the configuration file is stored in the cmake variable
1443 <package>_CONFIG.
1444 All configuration files which have been considered by CMake while
1446 searching for an installation of the package with an appropriate ver‐
1447 sion are stored in the cmake variable <package>_CONSIDERED_CONFIGS, the
1448 associated versions in <package>_CONSIDERED_VERSIONS.
1449 If the package configuration file cannot be found CMake will generate
1451 an error describing the problem unless the QUIET argument is specified.
1452 If REQUIRED is specified and the package is not found a fatal error is
1453 generated and the configure step stops executing. If <package>_DIR has
1454 been set to a directory not containing a configuration file CMake will
1455 ignore it and search from scratch.
1456 When the [version] argument is given Config mode will only find a ver‐
1458 sion of the package that claims compatibility with the requested ver‐
1459 sion (format is major[.minor[.patch[.tweak]]]). If the EXACT option is
1460 given only a version of the package claiming an exact match of the
1461 requested version may be found. CMake does not establish any conven‐
1462 tion for the meaning of version numbers. Package version numbers are
1463 checked by “version” files provided by the packages themselves. For a
1464 candidate package configuration file <config-file>.cmake the corre‐
1465 sponding version file is located next to it and named either <con‐
1466 fig-file>-version.cmake or <config-file>Version.cmake. If no such ver‐
1467 sion file is available then the configuration file is assumed to not be
1468 compatible with any requested version. A basic version file containing
1469 generic version matching code can be created using the CMakePackageCon‐
1470 figHelpers module. When a version file is found it is loaded to check
1471 the requested version number. The version file is loaded in a nested
1472 scope in which the following variables have been defined:
1473 PACKAGE_FIND_NAME
1475 the <package> name
1476 PACKAGE_FIND_VERSION
1478 full requested version string
1479 PACKAGE_FIND_VERSION_MAJOR
1481 major version if requested, else 0
1482 PACKAGE_FIND_VERSION_MINOR
1484 minor version if requested, else 0
1485 PACKAGE_FIND_VERSION_PATCH
1487 patch version if requested, else 0
1488 PACKAGE_FIND_VERSION_TWEAK
1490 tweak version if requested, else 0
1491 PACKAGE_FIND_VERSION_COUNT
1493 number of version components, 0 to 4
1494 The version file checks whether it satisfies the requested version and
1496 sets these variables:
1497 PACKAGE_VERSION
1499 full provided version string
1500 PACKAGE_VERSION_EXACT
1502 true if version is exact match
1503 PACKAGE_VERSION_COMPATIBLE
1505 true if version is compatible
1506 PACKAGE_VERSION_UNSUITABLE
1508 true if unsuitable as any version
1509 These variables are checked by the find_package command to determine
1511 whether the configuration file provides an acceptable version. They
1512 are not available after the find_package call returns. If the version
1513 is acceptable the following variables are set:
1514 <package>_VERSION
1516 full provided version string
1517 <package>_VERSION_MAJOR
1519 major version if provided, else 0
1520 <package>_VERSION_MINOR
1522 minor version if provided, else 0
1523 <package>_VERSION_PATCH
1525 patch version if provided, else 0
1526 <package>_VERSION_TWEAK
1528 tweak version if provided, else 0
1529 <package>_VERSION_COUNT
1531 number of version components, 0 to 4
1532 and the corresponding package configuration file is loaded. When mul‐
1534 tiple package configuration files are available whose version files
1535 claim compatibility with the version requested it is unspecified which
1536 one is chosen: unless the variable CMAKE_FIND_PACKAGE_SORT_ORDER is set
1537 no attempt is made to choose a highest or closest version number.
1538 To control the order in which find_package checks for compatibility use
1540 the two variables CMAKE_FIND_PACKAGE_SORT_ORDER and CMAKE_FIND_PACK‐
1541 AGE_SORT_DIRECTION. For instance in order to select the highest ver‐
1542 sion one can set:
1543 SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
1545 SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
1546 before calling find_package.
1548 Config mode provides an elaborate interface and search procedure. Much
1550 of the interface is provided for completeness and for use internally by
1551 find-modules loaded by Module mode. Most user code should simply call:
1552 find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
1554 in order to find a package. Package maintainers providing CMake pack‐
1556 age configuration files are encouraged to name and install them such
1557 that the procedure outlined below will find them without requiring use
1558 of additional options.
1559 CMake constructs a set of possible installation prefixes for the pack‐
1561 age. Under each prefix several directories are searched for a configu‐
1562 ration file. The tables below show the directories searched. Each
1563 entry is meant for installation trees following Windows (W), UNIX (U),
1564 or Apple (A) conventions:
1565 <prefix>/ (W)
1567 <prefix>/(cmake|CMake)/ (W)
1568 <prefix>/<name>*/ (W)
1569 <prefix>/<name>*/(cmake|CMake)/ (W)
1570 <prefix>/(lib/<arch>|lib|share)/cmake/<name>*/ (U)
1571 <prefix>/(lib/<arch>|lib|share)/<name>*/ (U)
1572 <prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/ (U)
1573 <prefix>/<name>*/(lib/<arch>|lib|share)/cmake/<name>*/ (W/U)
1574 <prefix>/<name>*/(lib/<arch>|lib|share)/<name>*/ (W/U)
1575 <prefix>/<name>*/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/ (W/U)
1576 On systems supporting OS X Frameworks and Application Bundles the fol‐
1578 lowing directories are searched for frameworks or bundles containing a
1579 configuration file:
1580 <prefix>/<name>.framework/Resources/ (A)
1582 <prefix>/<name>.framework/Resources/CMake/ (A)
1583 <prefix>/<name>.framework/Versions/*/Resources/ (A)
1584 <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A)
1585 <prefix>/<name>.app/Contents/Resources/ (A)
1586 <prefix>/<name>.app/Contents/Resources/CMake/ (A)
1587 In all cases the <name> is treated as case-insensitive and corresponds
1589 to any of the names specified (<package> or names given by NAMES).
1590 Paths with lib/<arch> are enabled if the CMAKE_LIBRARY_ARCHITECTURE
1591 variable is set. If PATH_SUFFIXES is specified the suffixes are
1592 appended to each (W) or (U) directory entry one-by-one.
1593 This set of directories is intended to work in cooperation with
1595 projects that provide configuration files in their installation trees.
1596 Directories above marked with (W) are intended for installations on
1597 Windows where the prefix may point at the top of an application’s
1598 installation directory. Those marked with (U) are intended for instal‐
1599 lations on UNIX platforms where the prefix is shared by multiple pack‐
1600 ages. This is merely a convention, so all (W) and (U) directories are
1601 still searched on all platforms. Directories marked with (A) are
1602 intended for installations on Apple platforms. The CMAKE_FIND_FRAME‐
1603 WORK and CMAKE_FIND_APPBUNDLE variables determine the order of prefer‐
1604 ence.
1605 The set of installation prefixes is constructed using the following
1607 steps. If NO_DEFAULT_PATH is specified all NO_* options are enabled.
1608 1. Search paths specified in cmake-specific cache variables. These are
1610 intended to be used on the command line with a -DVAR=value. The
1611 values are interpreted as ;-lists. This can be skipped if
1612 NO_CMAKE_PATH is passed:
1613 CMAKE_PREFIX_PATH
1615 CMAKE_FRAMEWORK_PATH
1616 CMAKE_APPBUNDLE_PATH
1617 2. Search paths specified in cmake-specific environment variables.
1619 These are intended to be set in the user’s shell configuration, and
1620 therefore use the host’s native path separator (; on Windows and :
1621 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1622 passed:
1623 <package>_DIR
1625 CMAKE_PREFIX_PATH
1626 CMAKE_FRAMEWORK_PATH
1627 CMAKE_APPBUNDLE_PATH
1628 3. Search paths specified by the HINTS option. These should be paths
1630 computed by system introspection, such as a hint provided by the
1631 location of another item already found. Hard-coded guesses should
1632 be specified with the PATHS option.
1633 4. Search the standard system environment variables. This can be
1635 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed. Path entries end‐
1636 ing in /bin or /sbin are automatically converted to their parent
1637 directories:
1638 PATH
1640 5. Search paths stored in the CMake User Package Registry. This can be
1642 skipped if NO_CMAKE_PACKAGE_REGISTRY is passed or by setting the
1643 CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY to TRUE. See the cmake-pack‐
1644 ages(7) manual for details on the user package registry.
1645 6. Search cmake variables defined in the Platform files for the current
1647 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed:
1648 CMAKE_SYSTEM_PREFIX_PATH
1650 CMAKE_SYSTEM_FRAMEWORK_PATH
1651 CMAKE_SYSTEM_APPBUNDLE_PATH
1652 7. Search paths stored in the CMake System Package Registry. This can
1654 be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is passed or by set‐
1655 ting the CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY to TRUE. See
1656 the cmake-packages(7) manual for details on the system package reg‐
1657 istry.
1658 8. Search paths specified by the PATHS option. These are typically
1660 hard-coded guesses.
1661 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
1663 ries to be prepended to all other search directories. This effectively
1664 “re-roots” the entire search under given locations. Paths which are
1665 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
1666 ing, because that variable is always a path on the host system. By
1667 default the CMAKE_FIND_ROOT_PATH is empty.
1668 The CMAKE_SYSROOT variable can also be used to specify exactly one
1670 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
1671 effects. See the documentation for that variable for more.
1672 These variables are especially useful when cross-compiling to point to
1674 the root directory of the target environment and CMake will search
1675 there too. By default at first the directories listed in
1676 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
1677 searched, and then the non-rooted directories will be searched. The
1678 default behavior can be adjusted by setting
1679 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE. This behavior can be manually over‐
1680 ridden on a per-call basis using options:
1681 CMAKE_FIND_ROOT_PATH_BOTH
1683 Search in the order described above.
1684 NO_CMAKE_FIND_ROOT_PATH
1686 Do not use the CMAKE_FIND_ROOT_PATH variable.
1687 ONLY_CMAKE_FIND_ROOT_PATH
1689 Search only the re-rooted directories and directories below
1690 CMAKE_STAGING_PREFIX.
1691 The default search order is designed to be most-specific to least-spe‐
1693 cific for common use cases. Projects may override the order by simply
1694 calling the command multiple times and using the NO_* options:
1695 find_package (<package> PATHS paths... NO_DEFAULT_PATH)
1697 find_package (<package>)
1698 Once one of the calls succeeds the result variable will be set and
1700 stored in the cache so that no call will search again.
1701 Every non-REQUIRED find_package call can be disabled by setting the
1703 CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable to TRUE.
1704 When loading a find module or package configuration file find_package
1706 defines variables to provide information about the call arguments (and
1707 restores their original state before returning):
1708 CMAKE_FIND_PACKAGE_NAME
1710 the <package> name which is searched for
1711 <package>_FIND_REQUIRED
1713 true if REQUIRED option was given
1714 <package>_FIND_QUIETLY
1716 true if QUIET option was given
1717 <package>_FIND_VERSION
1719 full requested version string
1720 <package>_FIND_VERSION_MAJOR
1722 major version if requested, else 0
1723 <package>_FIND_VERSION_MINOR
1725 minor version if requested, else 0
1726 <package>_FIND_VERSION_PATCH
1728 patch version if requested, else 0
1729 <package>_FIND_VERSION_TWEAK
1731 tweak version if requested, else 0
1732 <package>_FIND_VERSION_COUNT
1734 number of version components, 0 to 4
1735 <package>_FIND_VERSION_EXACT
1737 true if EXACT option was given
1738 <package>_FIND_COMPONENTS
1740 list of requested components
1741 <package>_FIND_REQUIRED_<c>
1743 true if component <c> is required, false if component <c> is
1744 optional
1745 In Module mode the loaded find module is responsible to honor the
1747 request detailed by these variables; see the find module for details.
1748 In Config mode find_package handles REQUIRED, QUIET, and [version]
1749 options automatically but leaves it to the package configuration file
1750 to handle components in a way that makes sense for the package. The
1751 package configuration file may set <package>_FOUND to false to tell
1752 find_package that component requirements are not satisfied.
1753 See the cmake_policy() command documentation for discussion of the
1755 NO_POLICY_SCOPE option.
1756 find_path
1758 A short-hand signature is:
1759 find_path (<VAR> name1 [path1 path2 ...])
1761 The general signature is:
1763 find_path (
1765 <VAR>
1766 name | NAMES name1 [name2 ...]
1767 [HINTS path1 [path2 ... ENV var]]
1768 [PATHS path1 [path2 ... ENV var]]
1769 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1770 [DOC "cache documentation string"]
1771 [NO_DEFAULT_PATH]
1772 [NO_CMAKE_PATH]
1773 [NO_CMAKE_ENVIRONMENT_PATH]
1774 [NO_SYSTEM_ENVIRONMENT_PATH]
1775 [NO_CMAKE_SYSTEM_PATH]
1776 [CMAKE_FIND_ROOT_PATH_BOTH |
1777 ONLY_CMAKE_FIND_ROOT_PATH |
1778 NO_CMAKE_FIND_ROOT_PATH]
1779 )
1780 This command is used to find a directory containing the named file. A
1782 cache entry named by <VAR> is created to store the result of this com‐
1783 mand. If the file in a directory is found the result is stored in the
1784 variable and the search will not be repeated unless the variable is
1785 cleared. If nothing is found, the result will be <VAR>-NOTFOUND, and
1786 the search will be attempted again the next time find_path is invoked
1787 with the same variable.
1788 Options include:
1790 NAMES Specify one or more possible names for the file in a directory.
1792 When using this to specify names with and without a version suf‐
1794 fix, we recommend specifying the unversioned name first so that
1795 locally-built packages can be found before those provided by
1796 distributions.
1797 HINTS, PATHS
1799 Specify directories to search in addition to the default loca‐
1800 tions. The ENV var sub-option reads paths from a system envi‐
1801 ronment variable.
1802 PATH_SUFFIXES
1804 Specify additional subdirectories to check below each directory
1805 location otherwise considered.
1806 DOC Specify the documentation string for the <VAR> cache entry.
1808 If NO_DEFAULT_PATH is specified, then no additional paths are added to
1810 the search. If NO_DEFAULT_PATH is not specified, the search process is
1811 as follows:
1812 1. Search paths specified in cmake-specific cache variables. These are
1814 intended to be used on the command line with a -DVAR=value. The
1815 values are interpreted as ;-lists. This can be skipped if
1816 NO_CMAKE_PATH is passed.
1817 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1819 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1820 · CMAKE_INCLUDE_PATH
1822 · CMAKE_FRAMEWORK_PATH
1824 2. Search paths specified in cmake-specific environment variables.
1826 These are intended to be set in the user’s shell configuration, and
1827 therefore use the host’s native path separator (; on Windows and :
1828 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1829 passed.
1830 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1832 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1833 · CMAKE_INCLUDE_PATH
1835 · CMAKE_FRAMEWORK_PATH
1837 3. Search the paths specified by the HINTS option. These should be
1839 paths computed by system introspection, such as a hint provided by
1840 the location of another item already found. Hard-coded guesses
1841 should be specified with the PATHS option.
1842 4. Search the standard system environment variables. This can be
1844 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1845 · Directories in INCLUDE. On Windows hosts: <prefix>/include/<arch>
1847 if CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/include for
1848 each <prefix>/[s]bin in PATH, and <entry>/include for other
1849 entries in PATH, and the directories in PATH itself.
1850 5. Search cmake variables defined in the Platform files for the current
1852 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed.
1853 · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1855 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1856 · CMAKE_SYSTEM_INCLUDE_PATH
1858 · CMAKE_SYSTEM_FRAMEWORK_PATH
1860 6. Search the paths specified by the PATHS option or in the short-hand
1862 version of the command. These are typically hard-coded guesses.
1863 On OS X the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
1865 determine the order of preference between Apple-style and unix-style
1866 package components.
1867 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
1869 ries to be prepended to all other search directories. This effectively
1870 “re-roots” the entire search under given locations. Paths which are
1871 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
1872 ing, because that variable is always a path on the host system. By
1873 default the CMAKE_FIND_ROOT_PATH is empty.
1874 The CMAKE_SYSROOT variable can also be used to specify exactly one
1876 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
1877 effects. See the documentation for that variable for more.
1878 These variables are especially useful when cross-compiling to point to
1880 the root directory of the target environment and CMake will search
1881 there too. By default at first the directories listed in
1882 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
1883 searched, and then the non-rooted directories will be searched. The
1884 default behavior can be adjusted by setting
1885 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually over‐
1886 ridden on a per-call basis using options:
1887 CMAKE_FIND_ROOT_PATH_BOTH
1889 Search in the order described above.
1890 NO_CMAKE_FIND_ROOT_PATH
1892 Do not use the CMAKE_FIND_ROOT_PATH variable.
1893 ONLY_CMAKE_FIND_ROOT_PATH
1895 Search only the re-rooted directories and directories below
1896 CMAKE_STAGING_PREFIX.
1897 The default search order is designed to be most-specific to least-spe‐
1899 cific for common use cases. Projects may override the order by simply
1900 calling the command multiple times and using the NO_* options:
1901 find_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1903 find_path (<VAR> NAMES name)
1904 Once one of the calls succeeds the result variable will be set and
1906 stored in the cache so that no call will search again.
1907 When searching for frameworks, if the file is specified as A/b.h, then
1909 the framework search will look for A.framework/Headers/b.h. If that is
1910 found the path will be set to the path to the framework. CMake will
1911 convert this to the correct -F option to include the file.
1912 find_program
1914 A short-hand signature is:
1915 find_program (<VAR> name1 [path1 path2 ...])
1917 The general signature is:
1919 find_program (
1921 <VAR>
1922 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
1923 [HINTS path1 [path2 ... ENV var]]
1924 [PATHS path1 [path2 ... ENV var]]
1925 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1926 [DOC "cache documentation string"]
1927 [NO_DEFAULT_PATH]
1928 [NO_CMAKE_PATH]
1929 [NO_CMAKE_ENVIRONMENT_PATH]
1930 [NO_SYSTEM_ENVIRONMENT_PATH]
1931 [NO_CMAKE_SYSTEM_PATH]
1932 [CMAKE_FIND_ROOT_PATH_BOTH |
1933 ONLY_CMAKE_FIND_ROOT_PATH |
1934 NO_CMAKE_FIND_ROOT_PATH]
1935 )
1936 This command is used to find a program. A cache entry named by <VAR>
1938 is created to store the result of this command. If the program is
1939 found the result is stored in the variable and the search will not be
1940 repeated unless the variable is cleared. If nothing is found, the
1941 result will be <VAR>-NOTFOUND, and the search will be attempted again
1942 the next time find_program is invoked with the same variable.
1943 Options include:
1945 NAMES Specify one or more possible names for the program.
1947 When using this to specify names with and without a version suf‐
1949 fix, we recommend specifying the unversioned name first so that
1950 locally-built packages can be found before those provided by
1951 distributions.
1952 HINTS, PATHS
1954 Specify directories to search in addition to the default loca‐
1955 tions. The ENV var sub-option reads paths from a system envi‐
1956 ronment variable.
1957 PATH_SUFFIXES
1959 Specify additional subdirectories to check below each directory
1960 location otherwise considered.
1961 DOC Specify the documentation string for the <VAR> cache entry.
1963 If NO_DEFAULT_PATH is specified, then no additional paths are added to
1965 the search. If NO_DEFAULT_PATH is not specified, the search process is
1966 as follows:
1967 1. Search paths specified in cmake-specific cache variables. These are
1969 intended to be used on the command line with a -DVAR=value. The
1970 values are interpreted as ;-lists. This can be skipped if
1971 NO_CMAKE_PATH is passed.
1972 · <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
1974 · CMAKE_PROGRAM_PATH
1976 · CMAKE_APPBUNDLE_PATH
1978 2. Search paths specified in cmake-specific environment variables.
1980 These are intended to be set in the user’s shell configuration, and
1981 therefore use the host’s native path separator (; on Windows and :
1982 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1983 passed.
1984 · <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
1986 · CMAKE_PROGRAM_PATH
1988 · CMAKE_APPBUNDLE_PATH
1990 3. Search the paths specified by the HINTS option. These should be
1992 paths computed by system introspection, such as a hint provided by
1993 the location of another item already found. Hard-coded guesses
1994 should be specified with the PATHS option.
1995 4. Search the standard system environment variables. This can be
1997 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1998 · PATH
2000 5. Search cmake variables defined in the Platform files for the current
2002 system. This can be skipped if NO_CMAKE_SYSTEM_PATH is passed.
2003 · <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2005 · CMAKE_SYSTEM_PROGRAM_PATH
2007 · CMAKE_SYSTEM_APPBUNDLE_PATH
2009 6. Search the paths specified by the PATHS option or in the short-hand
2011 version of the command. These are typically hard-coded guesses.
2012 On OS X the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
2014 determine the order of preference between Apple-style and unix-style
2015 package components.
2016 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
2018 ries to be prepended to all other search directories. This effectively
2019 “re-roots” the entire search under given locations. Paths which are
2020 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
2021 ing, because that variable is always a path on the host system. By
2022 default the CMAKE_FIND_ROOT_PATH is empty.
2023 The CMAKE_SYSROOT variable can also be used to specify exactly one
2025 directory to use as a prefix. Setting CMAKE_SYSROOT also has other
2026 effects. See the documentation for that variable for more.
2027 These variables are especially useful when cross-compiling to point to
2029 the root directory of the target environment and CMake will search
2030 there too. By default at first the directories listed in
2031 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
2032 searched, and then the non-rooted directories will be searched. The
2033 default behavior can be adjusted by setting
2034 CMAKE_FIND_ROOT_PATH_MODE_PROGRAM. This behavior can be manually over‐
2035 ridden on a per-call basis using options:
2036 CMAKE_FIND_ROOT_PATH_BOTH
2038 Search in the order described above.
2039 NO_CMAKE_FIND_ROOT_PATH
2041 Do not use the CMAKE_FIND_ROOT_PATH variable.
2042 ONLY_CMAKE_FIND_ROOT_PATH
2044 Search only the re-rooted directories and directories below
2045 CMAKE_STAGING_PREFIX.
2046 The default search order is designed to be most-specific to least-spe‐
2048 cific for common use cases. Projects may override the order by simply
2049 calling the command multiple times and using the NO_* options:
2050 find_program (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2052 find_program (<VAR> NAMES name)
2053 Once one of the calls succeeds the result variable will be set and
2055 stored in the cache so that no call will search again.
2056 When more than one value is given to the NAMES option this command by
2058 default will consider one name at a time and search every directory for
2059 it. The NAMES_PER_DIR option tells this command to consider one direc‐
2060 tory at a time and search for all names in it.
2061 foreach
2063 Evaluate a group of commands for each value in a list.
2064 foreach(loop_var arg1 arg2 ...)
2066 COMMAND1(ARGS ...)
2067 COMMAND2(ARGS ...)
2068 ...
2069 endforeach(loop_var)
2070 All commands between foreach and the matching endforeach are recorded
2072 without being invoked. Once the endforeach is evaluated, the recorded
2073 list of commands is invoked once for each argument listed in the origi‐
2074 nal foreach command. Before each iteration of the loop ${loop_var}
2075 will be set as a variable with the current value in the list.
2076 foreach(loop_var RANGE total)
2078 foreach(loop_var RANGE start stop [step])
2079 Foreach can also iterate over a generated range of numbers. There are
2081 three types of this iteration:
2082 · When specifying single number, the range will have elements [0, … to
2084 “total”] (inclusive).
2085 · When specifying two numbers, the range will have elements from the
2087 first number to the second number (inclusive).
2088 · The third optional number is the increment used to iterate from the
2090 first number to the second number (inclusive).
2091 foreach(loop_var IN [LISTS [list1 [...]]]
2093 [ITEMS [item1 [...]]])
2094 Iterates over a precise list of items. The LISTS option names
2096 list-valued variables to be traversed, including empty elements (an
2097 empty string is a zero-length list). (Note macro arguments are not
2098 variables.) The ITEMS option ends argument parsing and includes all
2099 arguments following it in the iteration.
2100 function
2102 Start recording a function for later invocation as a command:
2103 function(<name> [arg1 [arg2 [arg3 ...]]])
2105 COMMAND1(ARGS ...)
2106 COMMAND2(ARGS ...)
2107 ...
2108 endfunction(<name>)
2109 Define a function named <name> that takes arguments named arg1, arg2,
2111 arg3, (…). Commands listed after function, but before the matching
2112 endfunction(), are not invoked until the function is invoked. When it
2113 is invoked, the commands recorded in the function are first modified by
2114 replacing formal parameters (${arg1}) with the arguments passed, and
2115 then invoked as normal commands. In addition to referencing the formal
2116 parameters you can reference the ARGC variable which will be set to the
2117 number of arguments passed into the function as well as ARGV0, ARGV1,
2118 ARGV2, … which will have the actual values of the arguments passed in.
2119 This facilitates creating functions with optional arguments. Addition‐
2120 ally ARGV holds the list of all arguments given to the function and
2121 ARGN holds the list of arguments past the last expected argument. Ref‐
2122 erencing to ARGV# arguments beyond ARGC have undefined behavior. Check‐
2123 ing that ARGC is greater than # is the only way to ensure that ARGV#
2124 was passed to the function as an extra argument.
2125 A function opens a new scope: see set(var PARENT_SCOPE) for details.
2127 See the cmake_policy() command documentation for the behavior of poli‐
2129 cies inside functions.
2130 get_cmake_property
2132 Get a global property of the CMake instance.
2133 get_cmake_property(VAR property)
2135 Get a global property from the CMake instance. The value of the prop‐
2137 erty is stored in the variable VAR. If the property is not found, VAR
2138 will be set to “NOTFOUND”. See the cmake-properties(7) manual for
2139 available properties.
2140 See also the get_property() command GLOBAL option.
2142 In addition to global properties, this command (for historical reasons)
2144 also supports the VARIABLES and MACROS directory properties. It also
2145 supports a special COMPONENTS global property that lists the components
2146 given to the install() command.
2147 get_directory_property
2149 Get a property of DIRECTORY scope.
2150 get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
2152 Store a property of directory scope in the named variable. If the
2154 property is not defined the empty-string is returned. The DIRECTORY
2155 argument specifies another directory from which to retrieve the prop‐
2156 erty value. The specified directory must have already been traversed
2157 by CMake.
2158 get_directory_property(<variable> [DIRECTORY <dir>]
2160 DEFINITION <var-name>)
2161 Get a variable definition from a directory. This form is useful to get
2163 a variable definition from another directory.
2164 See also the more general get_property() command.
2166 get_filename_component
2168 Get a specific component of a full filename.
2169 ----
2172 get_filename_component(<VAR> <FileName> <COMP> [CACHE])
2176 Set <VAR> to a component of <FileName>, where <COMP> is one of:
2178 DIRECTORY = Directory without file name
2180 NAME = File name without directory
2181 EXT = File name longest extension (.b.c from d/a.b.c)
2182 NAME_WE = File name without directory or longest extension
2183 PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
2184 Paths are returned with forward slashes and have no trailing slashes.
2186 The longest file extension is always considered. If the optional CACHE
2187 argument is specified, the result variable is added to the cache.
2188 ----
2191 get_filename_component(<VAR> <FileName>
2195 <COMP> [BASE_DIR <BASE_DIR>]
2196 [CACHE])
2197 Set <VAR> to the absolute path of <FileName>, where <COMP> is one of:
2199 ABSOLUTE = Full path to file
2201 REALPATH = Full path to existing file with symlinks resolved
2202 If the provided <FileName> is a relative path, it is evaluated relative
2204 to the given base directory <BASE_DIR>. If no base directory is pro‐
2205 vided, the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
2206 Paths are returned with forward slashes and have no trailing slahes.
2208 If the optional CACHE argument is specified, the result variable is
2209 added to the cache.
2210 ----
2213 get_filename_component(<VAR> <FileName>
2217 PROGRAM [PROGRAM_ARGS <ARG_VAR>]
2218 [CACHE])
2219 The program in <FileName> will be found in the system search path or
2221 left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
2222 command-line arguments present in the <FileName> string are split from
2223 the program name and stored in <ARG_VAR>. This is used to separate a
2224 program name from its arguments in a command line string.
2225 get_property
2227 Get a property.
2228 get_property(<variable>
2230 <GLOBAL |
2231 DIRECTORY [dir] |
2232 TARGET <target> |
2233 SOURCE <source> |
2234 INSTALL <file> |
2235 TEST <test> |
2236 CACHE <entry> |
2237 VARIABLE>
2238 PROPERTY <name>
2239 [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
2240 Get one property from one object in a scope. The first argument speci‐
2242 fies the variable in which to store the result. The second argument
2243 determines the scope from which to get the property. It must be one of
2244 the following:
2245 GLOBAL Scope is unique and does not accept a name.
2247 DIRECTORY
2249 Scope defaults to the current directory but another directory
2250 (already processed by CMake) may be named by full or relative
2251 path.
2252 TARGET Scope must name one existing target.
2254 SOURCE Scope must name one source file.
2256 INSTALL
2258 Scope must name one installed file path.
2259 TEST Scope must name one existing test.
2261 CACHE Scope must name one cache entry.
2263 VARIABLE
2265 Scope is unique and does not accept a name.
2266 The required PROPERTY option is immediately followed by the name of the
2268 property to get. If the property is not set an empty value is
2269 returned. If the SET option is given the variable is set to a boolean
2270 value indicating whether the property has been set. If the DEFINED
2271 option is given the variable is set to a boolean value indicating
2272 whether the property has been defined such as with the define_prop‐
2273 erty() command. If BRIEF_DOCS or FULL_DOCS is given then the variable
2274 is set to a string containing documentation for the requested property.
2275 If documentation is requested for a property that has not been defined
2276 NOTFOUND is returned.
2277 if
2279 Conditionally execute a group of commands.
2280 if(expression)
2282 # then section.
2283 COMMAND1(ARGS ...)
2284 COMMAND2(ARGS ...)
2285 #...
2286 elseif(expression2)
2287 # elseif section.
2288 COMMAND1(ARGS ...)
2289 COMMAND2(ARGS ...)
2290 #...
2291 else(expression)
2292 # else section.
2293 COMMAND1(ARGS ...)
2294 COMMAND2(ARGS ...)
2295 #...
2296 endif(expression)
2297 Evaluates the given expression. If the result is true, the commands in
2299 the THEN section are invoked. Otherwise, the commands in the else sec‐
2300 tion are invoked. The elseif and else sections are optional. You may
2301 have multiple elseif clauses. Note that the expression in the else and
2302 endif clause is optional. Long expressions can be used and there is a
2303 traditional order of precedence. Parenthetical expressions are evalu‐
2304 ated first followed by unary tests such as EXISTS, COMMAND, and
2305 DEFINED. Then any binary tests such as EQUAL, LESS, LESS_EQUAL,
2306 GREATER, GREATER_EQUAL, STREQUAL, STRLESS, STRLESS_EQUAL, STRGREATER,
2307 STRGREATER_EQUAL, VERSION_EQUAL, VERSION_LESS, VERSION_LESS_EQUAL, VER‐
2308 SION_GREATER, VERSION_GREATER_EQUAL, and MATCHES will be evaluated.
2309 Then boolean NOT operators and finally boolean AND and then OR opera‐
2310 tors will be evaluated.
2311 Possible expressions are:
2313 if(<constant>)
2315 True if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
2316 ber. False if the constant is 0, OFF, NO, FALSE, N, IGNORE,
2317 NOTFOUND, the empty string, or ends in the suffix -NOTFOUND.
2318 Named boolean constants are case-insensitive. If the argument
2319 is not one of these specific constants, it is treated as a vari‐
2320 able or string and the following signature is used.
2321 if(<variable|string>)
2323 True if given a variable that is defined to a value that is not
2324 a false constant. False otherwise. (Note macro arguments are
2325 not variables.)
2326 if(NOT <expression>)
2328 True if the expression is not true.
2329 if(<expr1> AND <expr2>)
2331 True if both expressions would be considered true individually.
2332 if(<expr1> OR <expr2>)
2334 True if either expression would be considered true individually.
2335 if(COMMAND command-name)
2337 True if the given name is a command, macro or function that can
2338 be invoked.
2339 if(POLICY policy-id)
2341 True if the given name is an existing policy (of the form
2342 CMP<NNNN>).
2343 if(TARGET target-name)
2345 True if the given name is an existing logical target name cre‐
2346 ated by a call to the add_executable(), add_library(), or
2347 add_custom_target() command that has already been invoked (in
2348 any directory).
2349 if(TEST test-name)
2351 True if the given name is an existing test name created by the
2352 add_test() command.
2353 if(EXISTS path-to-file-or-directory)
2355 True if the named file or directory exists. Behavior is
2356 well-defined only for full paths.
2357 if(file1 IS_NEWER_THAN file2)
2359 True if file1 is newer than file2 or if one of the two files
2360 doesn’t exist. Behavior is well-defined only for full paths.
2361 If the file time stamps are exactly the same, an IS_NEWER_THAN
2362 comparison returns true, so that any dependent build operations
2363 will occur in the event of a tie. This includes the case of
2364 passing the same file name for both file1 and file2.
2365 if(IS_DIRECTORY path-to-directory)
2367 True if the given name is a directory. Behavior is well-defined
2368 only for full paths.
2369 if(IS_SYMLINK file-name)
2371 True if the given name is a symbolic link. Behavior is
2372 well-defined only for full paths.
2373 if(IS_ABSOLUTE path)
2375 True if the given path is an absolute path.
2376 if(<variable|string> MATCHES regex)
2378 True if the given string or variable’s value matches the given
2379 regular expression. See Regex Specification for regex format.
2380 () groups are captured in CMAKE_MATCH_<n> variables.
2381 if(<variable|string> LESS <variable|string>)
2383 True if the given string or variable’s value is a valid number
2384 and less than that on the right.
2385 if(<variable|string> GREATER <variable|string>)
2387 True if the given string or variable’s value is a valid number
2388 and greater than that on the right.
2389 if(<variable|string> EQUAL <variable|string>)
2391 True if the given string or variable’s value is a valid number
2392 and equal to that on the right.
2393 if(<variable|string> LESS_EQUAL <variable|string>)
2395 True if the given string or variable’s value is a valid number
2396 and less than or equal to that on the right.
2397 if(<variable|string> GREATER_EQUAL <variable|string>)
2399 True if the given string or variable’s value is a valid number
2400 and greater than or equal to that on the right.
2401 if(<variable|string> STRLESS <variable|string>)
2403 True if the given string or variable’s value is lexicographi‐
2404 cally less than the string or variable on the right.
2405 if(<variable|string> STRGREATER <variable|string>)
2407 True if the given string or variable’s value is lexicographi‐
2408 cally greater than the string or variable on the right.
2409 if(<variable|string> STREQUAL <variable|string>)
2411 True if the given string or variable’s value is lexicographi‐
2412 cally equal to the string or variable on the right.
2413 if(<variable|string> STRLESS_EQUAL <variable|string>)
2415 True if the given string or variable’s value is lexicographi‐
2416 cally less than or equal to the string or variable on the right.
2417 if(<variable|string> STRGREATER_EQUAL <variable|string>)
2419 True if the given string or variable’s value is lexicographi‐
2420 cally greater than or equal to the string or variable on the
2421 right.
2422 if(<variable|string> VERSION_LESS <variable|string>)
2424 Component-wise integer version number comparison (version format
2425 is major[.minor[.patch[.tweak]]]).
2426 if(<variable|string> VERSION_GREATER <variable|string>)
2428 Component-wise integer version number comparison (version format
2429 is major[.minor[.patch[.tweak]]]).
2430 if(<variable|string> VERSION_EQUAL <variable|string>)
2432 Component-wise integer version number comparison (version format
2433 is major[.minor[.patch[.tweak]]]).
2434 if(<variable|string> VERSION_LESS_EQUAL <variable|string>)
2436 Component-wise integer version number comparison (version format
2437 is major[.minor[.patch[.tweak]]]).
2438 if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)
2440 Component-wise integer version number comparison (version format
2441 is major[.minor[.patch[.tweak]]]).
2442 if(<variable|string> IN_LIST <variable>)
2444 True if the given element is contained in the named list vari‐
2445 able.
2446 if(DEFINED <variable>)
2448 True if the given variable is defined. It does not matter if
2449 the variable is true or false just if it has been set. (Note
2450 macro arguments are not variables.)
2451 if((expression) AND (expression OR (expression)))
2453 The expressions inside the parenthesis are evaluated first and
2454 then the remaining expression is evaluated as in the previous
2455 examples. Where there are nested parenthesis the innermost are
2456 evaluated as part of evaluating the expression that contains
2457 them.
2458 The if command was written very early in CMake’s history, predating the
2460 ${} variable evaluation syntax, and for convenience evaluates variables
2461 named by its arguments as shown in the above signatures. Note that
2462 normal variable evaluation with ${} applies before the if command even
2463 receives the arguments. Therefore code like:
2464 set(var1 OFF)
2466 set(var2 "var1")
2467 if(${var2})
2468 appears to the if command as:
2470 if(var1)
2472 and is evaluated according to the if(<variable>) case documented above.
2474 The result is OFF which is false. However, if we remove the ${} from
2475 the example then the command sees:
2476 if(var2)
2478 which is true because var2 is defined to “var1” which is not a false
2480 constant.
2481 Automatic evaluation applies in the other cases whenever the above-doc‐
2483 umented signature accepts <variable|string>:
2484 · The left hand argument to MATCHES is first checked to see if it is a
2486 defined variable, if so the variable’s value is used, otherwise the
2487 original value is used.
2488 · If the left hand argument to MATCHES is missing it returns false
2490 without error
2491 · Both left and right hand arguments to LESS, GREATER, EQUAL,
2493 LESS_EQUAL, and GREATER_EQUAL, are independently tested to see if
2494 they are defined variables, if so their defined values are used oth‐
2495 erwise the original value is used.
2496 · Both left and right hand arguments to STRLESS, STRGREATER, STREQUAL,
2498 STRLESS_EQUAL, and STRGREATER_EQUAL are independently tested to see
2499 if they are defined variables, if so their defined values are used
2500 otherwise the original value is used.
2501 · Both left and right hand arguments to VERSION_LESS, VERSION_GREATER,
2503 VERSION_EQUAL, VERSION_LESS_EQUAL, and VERSION_GREATER_EQUAL are
2504 independently tested to see if they are defined variables, if so
2505 their defined values are used otherwise the original value is used.
2506 · The right hand argument to NOT is tested to see if it is a boolean
2508 constant, if so the value is used, otherwise it is assumed to be a
2509 variable and it is dereferenced.
2510 · The left and right hand arguments to AND and OR are independently
2512 tested to see if they are boolean constants, if so they are used as
2513 such, otherwise they are assumed to be variables and are derefer‐
2514 enced.
2515 To prevent ambiguity, potential variable or keyword names can be speci‐
2517 fied in a Quoted Argument or a Bracket Argument. A quoted or bracketed
2518 variable or keyword will be interpreted as a string and not derefer‐
2519 enced or interpreted. See policy CMP0054.
2520 include
2522 Load and run CMake code from a file or module.
2523 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
2525 [NO_POLICY_SCOPE])
2526 Load and run CMake code from the file given. Variable reads and writes
2528 access the scope of the caller (dynamic scoping). If OPTIONAL is
2529 present, then no error is raised if the file does not exist. If
2530 RESULT_VARIABLE is given the variable will be set to the full filename
2531 which has been included or NOTFOUND if it failed.
2532 If a module is specified instead of a file, the file with name <module‐
2534 name>.cmake is searched first in CMAKE_MODULE_PATH, then in the CMake
2535 module directory. There is one exception to this: if the file which
2536 calls include() is located itself in the CMake builtin module direc‐
2537 tory, then first the CMake builtin module directory is searched and
2538 CMAKE_MODULE_PATH afterwards. See also policy CMP0017.
2539 See the cmake_policy() command documentation for discussion of the
2541 NO_POLICY_SCOPE option.
2542 include_guard
2544 Provides an include guard for the file currently being processed by
2545 CMake.
2546 include_guard([DIRECTORY|GLOBAL])
2548 Sets up an include guard for the current CMake file (see the CMAKE_CUR‐
2550 RENT_LIST_FILE variable documentation).
2551 CMake will end its processing of the current file at the location of
2553 the include_guard() command if the current file has already been pro‐
2554 cessed for the applicable scope (see below). This provides functional‐
2555 ity similar to the include guards commonly used in source headers or to
2556 the #pragma once directive. If the current file has been processed pre‐
2557 viously for the applicable scope, the effect is as though return() had
2558 been called. Do not call this command from inside a function being
2559 defined within the current file.
2560 An optional argument specifying the scope of the guard may be provided.
2562 Possible values for the option are:
2563 DIRECTORY
2565 The include guard applies within the current directory and
2566 below. The file will only be included once within this directory
2567 scope, but may be included again by other files outside of this
2568 directory (i.e. a parent directory or another directory not
2569 pulled in by add_subdirectory() or include() from the current
2570 file or its children).
2571 GLOBAL The include guard applies globally to the whole build. The cur‐
2573 rent file will only be included once regardless of the scope.
2574 If no arguments given, include_guard has the same scope as a variable,
2576 meaning that the include guard effect is isolated by the most recent
2577 function scope or current directory if no inner function scopes exist.
2578 In this case the command behavior is the same as:
2579 if(__CURRENT_FILE_VAR__)
2581 return()
2582 endif()
2583 set(__CURRENT_FILE_VAR__ TRUE)
2584 list
2586 List operations.
2587 list(LENGTH <list> <output variable>)
2589 list(GET <list> <element index> [<element index> ...]
2590 <output variable>)
2591 list(APPEND <list> [<element> ...])
2592 list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
2593 list(FIND <list> <value> <output variable>)
2594 list(INSERT <list> <element_index> <element> [<element> ...])
2595 list(REMOVE_ITEM <list> <value> [<value> ...])
2596 list(REMOVE_AT <list> <index> [<index> ...])
2597 list(REMOVE_DUPLICATES <list>)
2598 list(REVERSE <list>)
2599 list(SORT <list>)
2600 LENGTH will return a given list’s length.
2602 GET will return list of elements specified by indices from the list.
2604 APPEND will append elements to the list.
2606 FILTER will include or remove items from the list that match the mode’s
2608 pattern. In REGEX mode, items will be matched against the given regu‐
2609 lar expression. For more information on regular expressions see also
2610 the string() command.
2611 FIND will return the index of the element specified in the list or -1
2613 if it wasn’t found.
2614 INSERT will insert elements to the list to the specified location.
2616 REMOVE_AT and REMOVE_ITEM will remove items from the list. The differ‐
2618 ence is that REMOVE_ITEM will remove the given items, while REMOVE_AT
2619 will remove the items at the given indices.
2620 REMOVE_DUPLICATES will remove duplicated items in the list.
2622 REVERSE reverses the contents of the list in-place.
2624 SORT sorts the list in-place alphabetically.
2626 The list subcommands APPEND, INSERT, FILTER, REMOVE_AT, REMOVE_ITEM,
2628 REMOVE_DUPLICATES, REVERSE and SORT may create new values for the list
2629 within the current CMake variable scope. Similar to the set() command,
2630 the LIST command creates new variable values in the current scope, even
2631 if the list itself is actually defined in a parent scope. To propagate
2632 the results of these operations upwards, use set() with PARENT_SCOPE,
2633 set() with CACHE INTERNAL, or some other means of value propagation.
2634 NOTES: A list in cmake is a ; separated group of strings. To create a
2636 list the set command can be used. For example, set(var a b c d e) cre‐
2637 ates a list with a;b;c;d;e, and set(var "a b c d e") creates a string
2638 or a list with one item in it. (Note macro arguments are not vari‐
2639 ables, and therefore cannot be used in LIST commands.)
2640 When specifying index values, if <element index> is 0 or greater, it is
2642 indexed from the beginning of the list, with 0 representing the first
2643 list element. If <element index> is -1 or lesser, it is indexed from
2644 the end of the list, with -1 representing the last list element. Be
2645 careful when counting with negative indices: they do not start from 0.
2646 -0 is equivalent to 0, the first list element.
2647 macro
2649 Start recording a macro for later invocation as a command:
2650 macro(<name> [arg1 [arg2 [arg3 ...]]])
2652 COMMAND1(ARGS ...)
2653 COMMAND2(ARGS ...)
2654 ...
2655 endmacro(<name>)
2656 Define a macro named <name> that takes arguments named arg1, arg2,
2658 arg3, (…). Commands listed after macro, but before the matching end‐
2659 macro(), are not invoked until the macro is invoked. When it is
2660 invoked, the commands recorded in the macro are first modified by
2661 replacing formal parameters (${arg1}) with the arguments passed, and
2662 then invoked as normal commands. In addition to referencing the formal
2663 parameters you can reference the values ${ARGC} which will be set to
2664 the number of arguments passed into the function as well as ${ARGV0},
2665 ${ARGV1}, ${ARGV2}, … which will have the actual values of the argu‐
2666 ments passed in. This facilitates creating macros with optional argu‐
2667 ments. Additionally ${ARGV} holds the list of all arguments given to
2668 the macro and ${ARGN} holds the list of arguments past the last
2669 expected argument. Referencing to ${ARGV#} arguments beyond ${ARGC}
2670 have undefined behavior. Checking that ${ARGC} is greater than # is the
2671 only way to ensure that ${ARGV#} was passed to the function as an extra
2672 argument.
2673 See the cmake_policy() command documentation for the behavior of poli‐
2675 cies inside macros.
2676 Macro Argument Caveats
2678 Note that the parameters to a macro and values such as ARGN are not
2679 variables in the usual CMake sense. They are string replacements much
2680 like the C preprocessor would do with a macro. Therefore you will NOT
2681 be able to use commands like:
2682 if(ARGV1) # ARGV1 is not a variable
2684 if(DEFINED ARGV2) # ARGV2 is not a variable
2685 if(ARGC GREATER 2) # ARGC is not a variable
2686 foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
2687 In the first case, you can use if(${ARGV1}). In the second and third
2689 case, the proper way to check if an optional variable was passed to the
2690 macro is to use if(${ARGC} GREATER 2). In the last case, you can use
2691 foreach(loop_var ${ARGN}) but this will skip empty arguments. If you
2692 need to include them, you can use:
2693 set(list_var "${ARGN}")
2695 foreach(loop_var IN LISTS list_var)
2696 Note that if you have a variable with the same name in the scope from
2698 which the macro is called, using unreferenced names will use the exist‐
2699 ing variable instead of the arguments. For example:
2700 macro(_BAR)
2702 foreach(arg IN LISTS ARGN)
2703 [...]
2704 endforeach()
2705 endmacro()
2706 function(_FOO)
2708 _bar(x y z)
2709 endfunction()
2710 _foo(a b c)
2712 Will loop over a;b;c and not over x;y;z as one might be expecting. If
2714 you want true CMake variables and/or better CMake scope control you
2715 should look at the function command.
2716 mark_as_advanced
2718 Mark cmake cached variables as advanced.
2719 mark_as_advanced([CLEAR|FORCE] VAR [VAR2 ...])
2721 Mark the named cached variables as advanced. An advanced variable will
2723 not be displayed in any of the cmake GUIs unless the show advanced
2724 option is on. If CLEAR is the first argument advanced variables are
2725 changed back to unadvanced. If FORCE is the first argument, then the
2726 variable is made advanced. If neither FORCE nor CLEAR is specified,
2727 new values will be marked as advanced, but if the variable already has
2728 an advanced/non-advanced state, it will not be changed.
2729 It does nothing in script mode.
2731 math
2733 Mathematical expressions.
2734 math(EXPR <output-variable> <math-expression>)
2736 EXPR evaluates mathematical expression and returns result in the output
2738 variable. Example mathematical expression is 5 * (10 + 13). Supported
2739 operators are +, -, *, /, %, |, &, ^, ~, <<, >>, and (...). They have
2740 the same meaning as they do in C code.
2741 message
2743 Display a message to the user.
2744 message([<mode>] "message to display" ...)
2746 The optional <mode> keyword determines the type of message:
2748 (none) = Important information
2750 STATUS = Incidental information
2751 WARNING = CMake Warning, continue processing
2752 AUTHOR_WARNING = CMake Warning (dev), continue processing
2753 SEND_ERROR = CMake Error, continue processing,
2754 but skip generation
2755 FATAL_ERROR = CMake Error, stop processing and generation
2756 DEPRECATION = CMake Deprecation Error or Warning if variable
2757 CMAKE_ERROR_DEPRECATED or CMAKE_WARN_DEPRECATED
2758 is enabled, respectively, else no message.
2759 The CMake command-line tool displays STATUS messages on stdout and all
2761 other message types on stderr. The CMake GUI displays all messages in
2762 its log area. The interactive dialogs (ccmake and CMakeSetup) show
2763 STATUS messages one at a time on a status line and other messages in
2764 interactive pop-up boxes.
2765 CMake Warning and Error message text displays using a simple markup
2767 language. Non-indented text is formatted in line-wrapped paragraphs
2768 delimited by newlines. Indented text is considered pre-formatted.
2769 option
2771 Provides an option that the user can optionally select.
2772 option(<option_variable> "help string describing option"
2774 [initial value])
2775 Provide an option for the user to select as ON or OFF. If no initial
2777 value is provided, OFF is used.
2778 If you have options that depend on the values of other options, see the
2780 module help for CMakeDependentOption.
2781 return
2783 Return from a file, directory or function.
2784 return()
2786 Returns from a file, directory or function. When this command is
2788 encountered in an included file (via include() or find_package()), it
2789 causes processing of the current file to stop and control is returned
2790 to the including file. If it is encountered in a file which is not
2791 included by another file, e.g. a CMakeLists.txt, control is returned
2792 to the parent directory if there is one. If return is called in a
2793 function, control is returned to the caller of the function. Note that
2794 a macro is not a function and does not handle return like a function
2795 does.
2796 separate_arguments
2798 Parse space-separated arguments into a semicolon-separated list.
2799 separate_arguments(<var> <NATIVE|UNIX|WINDOWS>_COMMAND "<args>")
2801 Parses a UNIX- or Windows-style command-line string “<args>” and stores
2803 a semicolon-separated list of the arguments in <var>. The entire com‐
2804 mand line must be given in one “<args>” argument.
2805 The UNIX_COMMAND mode separates arguments by unquoted whitespace. It
2807 recognizes both single-quote and double-quote pairs. A backslash
2808 escapes the next literal character (\" is "); there are no special
2809 escapes (\n is just n).
2810 The WINDOWS_COMMAND mode parses a Windows command-line using the same
2812 syntax the runtime library uses to construct argv at startup. It sepa‐
2813 rates arguments by whitespace that is not double-quoted. Backslashes
2814 are literal unless they precede double-quotes. See the MSDN article
2815 Parsing C Command-Line Arguments for details.
2816 The NATIVE_COMMAND mode parses a Windows command-line if the host sys‐
2818 tem is Windows, and a UNIX command-line otherwise.
2819 separate_arguments(<var>)
2821 Convert the value of <var> to a semi-colon separated list. All spaces
2823 are replaced with ‘;’. This helps with generating command lines.
2824 set_directory_properties
2826 Set a property of the directory.
2827 set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
2829 Set a property for the current directory and subdirectories. See Direc‐
2831 tory Properties for the list of properties known to CMake.
2832 set_property
2834 Set a named property in a given scope.
2835 set_property(<GLOBAL |
2837 DIRECTORY [dir] |
2838 TARGET [target1 [target2 ...]] |
2839 SOURCE [src1 [src2 ...]] |
2840 INSTALL [file1 [file2 ...]] |
2841 TEST [test1 [test2 ...]] |
2842 CACHE [entry1 [entry2 ...]]>
2843 [APPEND] [APPEND_STRING]
2844 PROPERTY <name> [value1 [value2 ...]])
2845 Set one property on zero or more objects of a scope. The first argu‐
2847 ment determines the scope in which the property is set. It must be one
2848 of the following:
2849 GLOBAL Scope is unique and does not accept a name.
2851 DIRECTORY
2853 Scope defaults to the current directory but another directory
2854 (already processed by CMake) may be named by full or relative
2855 path.
2856 TARGET Scope may name zero or more existing targets.
2858 SOURCE Scope may name zero or more source files. Note that source file
2860 properties are visible only to targets added in the same direc‐
2861 tory (CMakeLists.txt).
2862 INSTALL
2864 Scope may name zero or more installed file paths. These are
2865 made available to CPack to influence deployment.
2866 Both the property key and value may use generator expressions.
2868 Specific properties may apply to installed files and/or directo‐
2869 ries.
2870 Path components have to be separated by forward slashes, must be
2872 normalized and are case sensitive.
2873 To reference the installation prefix itself with a relative path
2875 use “.”.
2876 Currently installed file properties are only defined for the WIX
2878 generator where the given paths are relative to the installation
2879 prefix.
2880 TEST Scope may name zero or more existing tests.
2882 CACHE Scope must name zero or more cache existing entries.
2884 The required PROPERTY option is immediately followed by the name of the
2886 property to set. Remaining arguments are used to compose the property
2887 value in the form of a semicolon-separated list. If the APPEND option
2888 is given the list is appended to any existing property value. If the
2889 APPEND_STRING option is given the string is append to any existing
2890 property value as string, i.e. it results in a longer string and not a
2891 list of strings.
2892 See the cmake-properties(7) manual for a list of properties in each
2894 scope.
2895 set
2897 Set a normal, cache, or environment variable to a given value. See the
2898 cmake-language(7) variables documentation for the scopes and interac‐
2899 tion of normal variables and cache entries.
2900 Signatures of this command that specify a <value>... placeholder expect
2902 zero or more arguments. Multiple arguments will be joined as a ;-list
2903 to form the actual variable value to be set. Zero arguments will cause
2904 normal variables to be unset. See the unset() command to unset vari‐
2905 ables explicitly.
2906 Set Normal Variable
2908 set(<variable> <value>... [PARENT_SCOPE])
2909 Set the given <variable> in the current function or directory scope.
2911 If the PARENT_SCOPE option is given the variable will be set in the
2913 scope above the current scope. Each new directory or function creates
2914 a new scope. This command will set the value of a variable into the
2915 parent directory or calling function (whichever is applicable to the
2916 case at hand). The previous state of the variable’s value stays the
2917 same in the current scope (e.g., if it was undefined before, it is
2918 still undefined and if it had a value, it is still that value).
2919 Set Cache Entry
2921 set(<variable> <value>... CACHE <type> <docstring> [FORCE])
2922 Set the given cache <variable> (cache entry). Since cache entries are
2924 meant to provide user-settable values this does not overwrite existing
2925 cache entries by default. Use the FORCE option to overwrite existing
2926 entries.
2927 The <type> must be specified as one of:
2929 BOOL Boolean ON/OFF value. cmake-gui(1) offers a checkbox.
2931 FILEPATH
2933 Path to a file on disk. cmake-gui(1) offers a file dialog.
2934 PATH Path to a directory on disk. cmake-gui(1) offers a file dialog.
2936 STRING A line of text. cmake-gui(1) offers a text field or a drop-down
2938 selection if the STRINGS cache entry property is set.
2939 INTERNAL
2941 A line of text. cmake-gui(1) does not show internal entries.
2942 They may be used to store variables persistently across runs.
2943 Use of this type implies FORCE.
2944 The <docstring> must be specified as a line of text providing a quick
2946 summary of the option for presentation to cmake-gui(1) users.
2947 If the cache entry does not exist prior to the call or the FORCE option
2949 is given then the cache entry will be set to the given value. Further‐
2950 more, any normal variable binding in the current scope will be removed
2951 to expose the newly cached value to any immediately following evalua‐
2952 tion.
2953 It is possible for the cache entry to exist prior to the call but have
2955 no type set if it was created on the cmake(1) command line by a user
2956 through the -D<var>=<value> option without specifying a type. In this
2957 case the set command will add the type. Furthermore, if the <type> is
2958 PATH or FILEPATH and the <value> provided on the command line is a rel‐
2959 ative path, then the set command will treat the path as relative to the
2960 current working directory and convert it to an absolute path.
2961 Set Environment Variable
2963 set(ENV{<variable>} <value>...)
2964 Set the current process environment <variable> to the given value.
2966 site_name
2968 Set the given variable to the name of the computer.
2969 site_name(variable)
2971 string
2973 String operations.
2974 Search and Replace
2976 FIND
2977 string(FIND <string> <substring> <output variable> [REVERSE])
2978 Return the position where the given substring was found in the supplied
2980 string. If the REVERSE flag was used, the command will search for the
2981 position of the last occurrence of the specified substring. If the
2982 substring is not found, a position of -1 is returned.
2983 REPLACE
2985 string(REPLACE <match_string>
2986 <replace_string> <output variable>
2987 <input> [<input>...])
2988 Replace all occurrences of match_string in the input with
2990 replace_string and store the result in the output.
2991 Regular Expressions
2993 REGEX MATCH
2994 string(REGEX MATCH <regular_expression>
2995 <output variable> <input> [<input>...])
2996 Match the regular expression once and store the match in the output
2998 variable. All <input> arguments are concatenated before matching.
2999 REGEX MATCHALL
3001 string(REGEX MATCHALL <regular_expression>
3002 <output variable> <input> [<input>...])
3003 Match the regular expression as many times as possible and store the
3005 matches in the output variable as a list. All <input> arguments are
3006 concatenated before matching.
3007 REGEX REPLACE
3009 string(REGEX REPLACE <regular_expression>
3010 <replace_expression> <output variable>
3011 <input> [<input>...])
3012 Match the regular expression as many times as possible and substitute
3014 the replacement expression for the match in the output. All <input>
3015 arguments are concatenated before matching.
3016 The replace expression may refer to paren-delimited subexpressions of
3018 the match using \1, \2, …, \9. Note that two backslashes (\\1) are
3019 required in CMake code to get a backslash through argument parsing.
3020 Regex Specification
3022 The following characters have special meaning in regular expressions:
3023 ^ Matches at beginning of input
3025 $ Matches at end of input
3027 . Matches any single character
3029 [ ] Matches any character(s) inside the brackets
3031 [^ ] Matches any character(s) not inside the brackets
3033 - Inside brackets, specifies an inclusive range between characters
3035 on either side e.g. [a-f] is [abcdef] To match a literal - using
3036 brackets, make it the first or the last character e.g. [+*/-]
3037 matches basic mathematical operators.
3038 * Matches preceding pattern zero or more times
3040 + Matches preceding pattern one or more times
3042 ? Matches preceding pattern zero or once only
3044 | Matches a pattern on either side of the |
3046 () Saves a matched subexpression, which can be referenced in the
3048 REGEX REPLACE operation. Additionally it is saved by all regular
3049 expression-related commands, including e.g. if(MATCHES), in the
3050 variables CMAKE_MATCH_<n> for <n> 0..9.
3051 *, + and ? have higher precedence than concatenation. | has lower
3053 precedence than concatenation. This means that the regular expression
3054 ^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
3055 matches ab but not abd.
3056 Manipulation
3058 APPEND
3059 string(APPEND <string variable> [<input>...])
3060 Append all the input arguments to the string.
3062 PREPEND
3064 string(PREPEND <string variable> [<input>...])
3065 Prepend all the input arguments to the string.
3067 CONCAT
3069 string(CONCAT <output variable> [<input>...])
3070 Concatenate all the input arguments together and store the result in
3072 the named output variable.
3073 TOLOWER
3075 string(TOLOWER <string1> <output variable>)
3076 Convert string to lower characters.
3078 TOUPPER
3080 string(TOUPPER <string1> <output variable>)
3081 Convert string to upper characters.
3083 LENGTH
3085 string(LENGTH <string> <output variable>)
3086 Store in an output variable a given string’s length.
3088 SUBSTRING
3090 string(SUBSTRING <string> <begin> <length> <output variable>)
3091 Store in an output variable a substring of a given string. If length
3093 is -1 the remainder of the string starting at begin will be returned.
3094 If string is shorter than length then end of string is used instead.
3095 NOTE:
3097 CMake 3.1 and below reported an error if length pointed past the end
3098 of string.
3099 STRIP
3101 string(STRIP <string> <output variable>)
3102 Store in an output variable a substring of a given string with leading
3104 and trailing spaces removed.
3105 GENEX_STRIP
3107 string(GENEX_STRIP <input string> <output variable>)
3108 Strip any generator expressions from the input string and store the
3110 result in the output variable.
3111 Comparison
3113 string(COMPARE LESS <string1> <string2> <output variable>)
3114 string(COMPARE GREATER <string1> <string2> <output variable>)
3115 string(COMPARE EQUAL <string1> <string2> <output variable>)
3116 string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
3117 string(COMPARE LESS_EQUAL <string1> <string2> <output variable>)
3118 string(COMPARE GREATER_EQUAL <string1> <string2> <output variable>)
3119 Compare the strings and store true or false in the output variable.
3121 Hashing
3123 string(<HASH> <output variable> <input>)
3124 Compute a cryptographic hash of the input string. The supported <HASH>
3126 algorithm names are:
3127 MD5 Message-Digest Algorithm 5, RFC 1321.
3129 SHA1 US Secure Hash Algorithm 1, RFC 3174.
3131 SHA224 US Secure Hash Algorithms, RFC 4634.
3133 SHA256 US Secure Hash Algorithms, RFC 4634.
3135 SHA384 US Secure Hash Algorithms, RFC 4634.
3137 SHA512 US Secure Hash Algorithms, RFC 4634.
3139 SHA3_224
3141 Keccak SHA-3.
3142 SHA3_256
3144 Keccak SHA-3.
3145 SHA3_384
3147 Keccak SHA-3.
3148 SHA3_512
3150 Keccak SHA-3.
3151 Generation
3153 ASCII
3154 string(ASCII <number> [<number> ...] <output variable>)
3155 Convert all numbers into corresponding ASCII characters.
3157 CONFIGURE
3159 string(CONFIGURE <string1> <output variable>
3160 [@ONLY] [ESCAPE_QUOTES])
3161 Transform a string like configure_file() transforms a file.
3163 RANDOM
3165 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
3166 [RANDOM_SEED <seed>] <output variable>)
3167 Return a random string of given length consisting of characters from
3169 the given alphabet. Default length is 5 characters and default alpha‐
3170 bet is all numbers and upper and lower case letters. If an integer
3171 RANDOM_SEED is given, its value will be used to seed the random number
3172 generator.
3173 TIMESTAMP
3175 string(TIMESTAMP <output variable> [<format string>] [UTC])
3176 Write a string representation of the current date and/or time to the
3178 output variable.
3179 Should the command be unable to obtain a timestamp the output variable
3181 will be set to the empty string “”.
3182 The optional UTC flag requests the current date/time representation to
3184 be in Coordinated Universal Time (UTC) rather than local time.
3185 The optional <format string> may contain the following format speci‐
3187 fiers:
3188 %% A literal percent sign (%).
3190 %d The day of the current month (01-31).
3191 %H The hour on a 24-hour clock (00-23).
3192 %I The hour on a 12-hour clock (01-12).
3193 %j The day of the current year (001-366).
3194 %m The month of the current year (01-12).
3195 %b Abbreviated month name (e.g. Oct).
3196 %B Full month name (e.g. October).
3197 %M The minute of the current hour (00-59).
3198 %s Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
3199 %S The second of the current minute.
3200 60 represents a leap second. (00-60)
3201 %U The week number of the current year (00-53).
3202 %w The day of the current week. 0 is Sunday. (0-6)
3203 %a Abbreviated weekday name (e.g. Fri).
3204 %A Full weekday name (e.g. Friday).
3205 %y The last two digits of the current year (00-99)
3206 %Y The current year.
3207 Unknown format specifiers will be ignored and copied to the output
3209 as-is.
3210 If no explicit <format string> is given it will default to:
3212 %Y-%m-%dT%H:%M:%S for local time.
3214 %Y-%m-%dT%H:%M:%SZ for UTC.
3215 string(MAKE_C_IDENTIFIER <input string> <output variable>)
3217 Write a string which can be used as an identifier in C.
3219 NOTE:
3221 If the SOURCE_DATE_EPOCH environment variable is set, its value will
3222 be used instead of the current time. See
3223 https://reproducible-builds.org/specs/source-date-epoch/ for
3224 details.
3225 UUID
3227 string(UUID <output variable> NAMESPACE <namespace> NAME <name>
3228 TYPE <MD5|SHA1> [UPPER])
3229 Create a univerally unique identifier (aka GUID) as per RFC4122 based
3231 on the hash of the combined values of <namespace> (which itself has to
3232 be a valid UUID) and <name>. The hash algorithm can be either MD5
3233 (Version 3 UUID) or SHA1 (Version 5 UUID). A UUID has the format
3234 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where each x represents a lower
3235 case hexadecimal character. Where required an uppercase representation
3236 can be requested with the optional UPPER flag.
3237 unset
3239 Unset a variable, cache variable, or environment variable.
3240 unset(<variable> [CACHE | PARENT_SCOPE])
3242 Removes the specified variable causing it to become undefined. If
3244 CACHE is present then the variable is removed from the cache instead of
3245 the current scope.
3246 If PARENT_SCOPE is present then the variable is removed from the scope
3248 above the current scope. See the same option in the set() command for
3249 further details.
3250 <variable> can be an environment variable such as:
3252 unset(ENV{LD_LIBRARY_PATH})
3254 in which case the variable will be removed from the current environ‐
3256 ment.
3257 variable_watch
3259 Watch the CMake variable for change.
3260 variable_watch(<variable name> [<command to execute>])
3262 If the specified variable changes, the message will be printed about
3264 the variable being changed. If the command is specified, the command
3265 will be executed. The command will receive the following arguments:
3266 COMMAND(<variable> <access> <value> <current list file> <stack>)
3267 while
3269 Evaluate a group of commands while a condition is true
3270 while(condition)
3272 COMMAND1(ARGS ...)
3273 COMMAND2(ARGS ...)
3274 ...
3275 endwhile(condition)
3276 All commands between while and the matching endwhile() are recorded
3278 without being invoked. Once the endwhile() is evaluated, the recorded
3279 list of commands is invoked as long as the condition is true. The con‐
3280 dition is evaluated using the same logic as the if() command.
3281
3283 These commands are available only in CMake projects.
3284 add_compile_options
3286 Adds options to the compilation of source files.
3287 add_compile_options(<option> ...)
3289 Adds options to the compiler command line for targets in the current
3291 directory and below that are added after this command is invoked. See
3292 documentation of the directory and target COMPILE_OPTIONS properties.
3293 This command can be used to add any options, but alternative commands
3295 exist to add preprocessor definitions (target_compile_definitions() and
3296 add_definitions()) or include directories (target_include_directories()
3297 and include_directories()).
3298 Arguments to add_compile_options may use “generator expressions” with
3300 the syntax $<...>. See the cmake-generator-expressions(7) manual for
3301 available expressions. See the cmake-buildsystem(7) manual for more on
3302 defining buildsystem properties.
3303 add_custom_command
3305 Add a custom build rule to the generated build system.
3306 There are two main signatures for add_custom_command.
3308 Generating Files
3310 The first signature is for adding a custom command to produce an out‐
3311 put:
3312 add_custom_command(OUTPUT output1 [output2 ...]
3314 COMMAND command1 [ARGS] [args1...]
3315 [COMMAND command2 [ARGS] [args2...] ...]
3316 [MAIN_DEPENDENCY depend]
3317 [DEPENDS [depends...]]
3318 [BYPRODUCTS [files...]]
3319 [IMPLICIT_DEPENDS <lang1> depend1
3320 [<lang2> depend2] ...]
3321 [WORKING_DIRECTORY dir]
3322 [COMMENT comment]
3323 [DEPFILE depfile]
3324 [VERBATIM] [APPEND] [USES_TERMINAL]
3325 [COMMAND_EXPAND_LISTS])
3326 This defines a command to generate specified OUTPUT file(s). A target
3328 created in the same directory (CMakeLists.txt file) that specifies any
3329 output of the custom command as a source file is given a rule to gener‐
3330 ate the file using the command at build time. Do not list the output
3331 in more than one independent target that may build in parallel or the
3332 two instances of the rule may conflict (instead use the add_custom_tar‐
3333 get() command to drive the command and make the other targets depend on
3334 that one). In makefile terms this creates a new target in the follow‐
3335 ing form:
3336 OUTPUT: MAIN_DEPENDENCY DEPENDS
3338 COMMAND
3339 The options are:
3341 APPEND Append the COMMAND and DEPENDS option values to the custom com‐
3343 mand for the first output specified. There must have already
3344 been a previous call to this command with the same output. The
3345 COMMENT, MAIN_DEPENDENCY, and WORKING_DIRECTORY options are cur‐
3346 rently ignored when APPEND is given, but may be used in the
3347 future.
3348 BYPRODUCTS
3350 Specify the files the command is expected to produce but whose
3351 modification time may or may not be newer than the dependencies.
3352 If a byproduct name is a relative path it will be interpreted
3353 relative to the build tree directory corresponding to the cur‐
3354 rent source directory. Each byproduct file will be marked with
3355 the GENERATED source file property automatically.
3356 Explicit specification of byproducts is supported by the Ninja
3358 generator to tell the ninja build tool how to regenerate byprod‐
3359 ucts when they are missing. It is also useful when other build
3360 rules (e.g. custom commands) depend on the byproducts. Ninja
3361 requires a build rule for any generated file on which another
3362 rule depends even if there are order-only dependencies to ensure
3363 the byproducts will be available before their dependents build.
3364 The BYPRODUCTS option is ignored on non-Ninja generators except
3366 to mark byproducts GENERATED.
3367 COMMAND
3369 Specify the command-line(s) to execute at build time. If more
3370 than one COMMAND is specified they will be executed in order,
3371 but not necessarily composed into a stateful shell or batch
3372 script. (To run a full script, use the configure_file() command
3373 or the file(GENERATE) command to create it, and then specify a
3374 COMMAND to launch it.) The optional ARGS argument is for back‐
3375 ward compatibility and will be ignored.
3376 If COMMAND specifies an executable target name (created by the
3378 add_executable() command) it will automatically be replaced by
3379 the location of the executable created at build time. If set,
3380 the CROSSCOMPILING_EMULATOR executable target property will also
3381 be prepended to the command to allow the executable to run on
3382 the host. (Use the TARGET_FILE generator expression to refer‐
3383 ence an executable later in the command line.) Additionally a
3384 target-level dependency will be added so that the executable
3385 target will be built before any target using this custom com‐
3386 mand. However this does NOT add a file-level dependency that
3387 would cause the custom command to re-run whenever the executable
3388 is recompiled.
3389 Arguments to COMMAND may use generator expressions. References
3391 to target names in generator expressions imply target-level
3392 dependencies, but NOT file-level dependencies. List target
3393 names with the DEPENDS option to add file-level dependencies.
3394 COMMENT
3396 Display the given message before the commands are executed at
3397 build time.
3398 DEPENDS
3400 Specify files on which the command depends. If any dependency
3401 is an OUTPUT of another custom command in the same directory
3402 (CMakeLists.txt file) CMake automatically brings the other cus‐
3403 tom command into the target in which this command is built. If
3404 DEPENDS is not specified the command will run whenever the OUT‐
3405 PUT is missing; if the command does not actually create the OUT‐
3406 PUT then the rule will always run. If DEPENDS specifies any
3407 target (created by the add_custom_target(), add_executable(), or
3408 add_library() command) a target-level dependency is created to
3409 make sure the target is built before any target using this cus‐
3410 tom command. Additionally, if the target is an executable or
3411 library a file-level dependency is created to cause the custom
3412 command to re-run whenever the target is recompiled.
3413 Arguments to DEPENDS may use generator expressions.
3415 COMMAND_EXPAND_LISTS
3417 Lists in COMMAND arguments will be expanded, including those
3418 created with generator expressions, allowing COMMAND arguments
3419 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
3420 RIES>,;-I>" foo.cc to be properly expanded.
3421 IMPLICIT_DEPENDS
3423 Request scanning of implicit dependencies of an input file. The
3424 language given specifies the programming language whose corre‐
3425 sponding dependency scanner should be used. Currently only C
3426 and CXX language scanners are supported. The language has to be
3427 specified for every file in the IMPLICIT_DEPENDS list. Depen‐
3428 dencies discovered from the scanning are added to those of the
3429 custom command at build time. Note that the IMPLICIT_DEPENDS
3430 option is currently supported only for Makefile generators and
3431 will be ignored by other generators.
3432 MAIN_DEPENDENCY
3434 Specify the primary input source file to the command. This is
3435 treated just like any value given to the DEPENDS option but also
3436 suggests to Visual Studio generators where to hang the custom
3437 command. Each source file may have at most one command specify‐
3438 ing it as its main dependency. A compile command (i.e. for a
3439 library or an executable) counts as an implicit main dependency
3440 which gets silently overwritten by a custom command specifica‐
3441 tion.
3442 OUTPUT Specify the output files the command is expected to produce. If
3444 an output name is a relative path it will be interpreted rela‐
3445 tive to the build tree directory corresponding to the current
3446 source directory. Each output file will be marked with the GEN‐
3447 ERATED source file property automatically. If the output of the
3448 custom command is not actually created as a file on disk it
3449 should be marked with the SYMBOLIC source file property.
3450 USES_TERMINAL
3452 The command will be given direct access to the terminal if pos‐
3453 sible. With the Ninja generator, this places the command in the
3454 console pool.
3455 VERBATIM
3457 All arguments to the commands will be escaped properly for the
3458 build tool so that the invoked command receives each argument
3459 unchanged. Note that one level of escapes is still used by the
3460 CMake language processor before add_custom_command even sees the
3461 arguments. Use of VERBATIM is recommended as it enables correct
3462 behavior. When VERBATIM is not given the behavior is platform
3463 specific because there is no protection of tool-specific special
3464 characters.
3465 WORKING_DIRECTORY
3467 Execute the command with the given current working directory.
3468 If it is a relative path it will be interpreted relative to the
3469 build tree directory corresponding to the current source direc‐
3470 tory.
3471 DEPFILE
3473 Specify a .d depfile for the Ninja generator. A .d file holds
3474 dependencies usually emitted by the custom command itself.
3475 Using DEPFILE with other generators than Ninja is an error.
3476 Build Events
3478 The second signature adds a custom command to a target such as a
3479 library or executable. This is useful for performing an operation
3480 before or after building the target. The command becomes part of the
3481 target and will only execute when the target itself is built. If the
3482 target is already built, the command will not execute.
3483 add_custom_command(TARGET <target>
3485 PRE_BUILD | PRE_LINK | POST_BUILD
3486 COMMAND command1 [ARGS] [args1...]
3487 [COMMAND command2 [ARGS] [args2...] ...]
3488 [BYPRODUCTS [files...]]
3489 [WORKING_DIRECTORY dir]
3490 [COMMENT comment]
3491 [VERBATIM] [USES_TERMINAL])
3492 This defines a new command that will be associated with building the
3494 specified <target>. The <target> must be defined in the current direc‐
3495 tory; targets defined in other directories may not be specified.
3496 When the command will happen is determined by which of the following is
3498 specified:
3499 PRE_BUILD
3501 Run before any other rules are executed within the target. This
3502 is supported only on Visual Studio 8 or later. For all other
3503 generators PRE_BUILD will be treated as PRE_LINK.
3504 PRE_LINK
3506 Run after sources have been compiled but before linking the
3507 binary or running the librarian or archiver tool of a static
3508 library. This is not defined for targets created by the
3509 add_custom_target() command.
3510 POST_BUILD
3512 Run after all other rules within the target have been executed.
3513 NOTE:
3515 Because generator expressions can be used in custom commands, it is
3516 possible to define COMMAND lines or whole custom commands which
3517 evaluate to empty strings for certain configurations. For Visual
3518 Studio 2010 (and newer) generators these command lines or custom
3519 commands will be omitted for the specific configuration and no
3520 “empty-string-command” will be added.
3521 This allows to add individual build events for every configuration.
3523 add_custom_target
3525 Add a target with no output so it will always be built.
3526 add_custom_target(Name [ALL] [command1 [args1...]]
3528 [COMMAND command2 [args2...] ...]
3529 [DEPENDS depend depend depend ... ]
3530 [BYPRODUCTS [files...]]
3531 [WORKING_DIRECTORY dir]
3532 [COMMENT comment]
3533 [VERBATIM] [USES_TERMINAL]
3534 [COMMAND_EXPAND_LISTS]
3535 [SOURCES src1 [src2...]])
3536 Adds a target with the given name that executes the given commands.
3538 The target has no output file and is always considered out of date even
3539 if the commands try to create a file with the name of the target. Use
3540 the add_custom_command() command to generate a file with dependencies.
3541 By default nothing depends on the custom target. Use the add_dependen‐
3542 cies() command to add dependencies to or from other targets.
3543 The options are:
3545 ALL Indicate that this target should be added to the default build
3547 target so that it will be run every time (the command cannot be
3548 called ALL).
3549 BYPRODUCTS
3551 Specify the files the command is expected to produce but whose
3552 modification time may or may not be updated on subsequent
3553 builds. If a byproduct name is a relative path it will be
3554 interpreted relative to the build tree directory corresponding
3555 to the current source directory. Each byproduct file will be
3556 marked with the GENERATED source file property automatically.
3557 Explicit specification of byproducts is supported by the Ninja
3559 generator to tell the ninja build tool how to regenerate byprod‐
3560 ucts when they are missing. It is also useful when other build
3561 rules (e.g. custom commands) depend on the byproducts. Ninja
3562 requires a build rule for any generated file on which another
3563 rule depends even if there are order-only dependencies to ensure
3564 the byproducts will be available before their dependents build.
3565 The BYPRODUCTS option is ignored on non-Ninja generators except
3567 to mark byproducts GENERATED.
3568 COMMAND
3570 Specify the command-line(s) to execute at build time. If more
3571 than one COMMAND is specified they will be executed in order,
3572 but not necessarily composed into a stateful shell or batch
3573 script. (To run a full script, use the configure_file() command
3574 or the file(GENERATE) command to create it, and then specify a
3575 COMMAND to launch it.)
3576 If COMMAND specifies an executable target name (created by the
3578 add_executable() command) it will automatically be replaced by
3579 the location of the executable created at build time. If set,
3580 the CROSSCOMPILING_EMULATOR executable target property will also
3581 be prepended to the command to allow the executable to run on
3582 the host. Additionally a target-level dependency will be added
3583 so that the executable target will be built before this custom
3584 target.
3585 Arguments to COMMAND may use generator expressions. References
3587 to target names in generator expressions imply target-level
3588 dependencies.
3589 The command and arguments are optional and if not specified an
3591 empty target will be created.
3592 COMMENT
3594 Display the given message before the commands are executed at
3595 build time.
3596 DEPENDS
3598 Reference files and outputs of custom commands created with
3599 add_custom_command() command calls in the same directory (CMake‐
3600 Lists.txt file). They will be brought up to date when the tar‐
3601 get is built.
3602 Use the add_dependencies() command to add dependencies on other
3604 targets.
3605 COMMAND_EXPAND_LISTS
3607 Lists in COMMAND arguments will be expanded, including those
3608 created with generator expressions, allowing COMMAND arguments
3609 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
3610 RIES>,;-I>" foo.cc to be properly expanded.
3611 SOURCES
3613 Specify additional source files to be included in the custom
3614 target. Specified source files will be added to IDE project
3615 files for convenience in editing even if they have no build
3616 rules.
3617 VERBATIM
3619 All arguments to the commands will be escaped properly for the
3620 build tool so that the invoked command receives each argument
3621 unchanged. Note that one level of escapes is still used by the
3622 CMake language processor before add_custom_target even sees the
3623 arguments. Use of VERBATIM is recommended as it enables correct
3624 behavior. When VERBATIM is not given the behavior is platform
3625 specific because there is no protection of tool-specific special
3626 characters.
3627 USES_TERMINAL
3629 The command will be given direct access to the terminal if pos‐
3630 sible. With the Ninja generator, this places the command in the
3631 console pool.
3632 WORKING_DIRECTORY
3634 Execute the command with the given current working directory.
3635 If it is a relative path it will be interpreted relative to the
3636 build tree directory corresponding to the current source direc‐
3637 tory.
3638 add_definitions
3640 Adds -D define flags to the compilation of source files.
3641 add_definitions(-DFOO -DBAR ...)
3643 Adds definitions to the compiler command line for targets in the cur‐
3645 rent directory and below (whether added before or after this command is
3646 invoked). This command can be used to add any flags, but it is
3647 intended to add preprocessor definitions (see the add_compile_options()
3648 command to add other flags). Flags beginning in -D or /D that look
3649 like preprocessor definitions are automatically added to the COM‐
3650 PILE_DEFINITIONS directory property for the current directory. Defini‐
3651 tions with non-trivial values may be left in the set of flags instead
3652 of being converted for reasons of backwards compatibility. See docu‐
3653 mentation of the directory, target, source file COMPILE_DEFINITIONS
3654 properties for details on adding preprocessor definitions to specific
3655 scopes and configurations.
3656 See the cmake-buildsystem(7) manual for more on defining buildsystem
3658 properties.
3659 add_dependencies
3661 Add a dependency between top-level targets.
3662 add_dependencies(<target> [<target-dependency>]...)
3664 Make a top-level <target> depend on other top-level targets to ensure
3666 that they build before <target> does. A top-level target is one cre‐
3667 ated by one of the add_executable(), add_library(), or add_custom_tar‐
3668 get() commands (but not targets generated by CMake like install).
3669 Dependencies added to an imported target or an interface library are
3671 followed transitively in its place since the target itself does not
3672 build.
3673 See the DEPENDS option of add_custom_target() and add_custom_command()
3675 commands for adding file-level dependencies in custom rules. See the
3676 OBJECT_DEPENDS source file property to add file-level dependencies to
3677 object files.
3678 add_executable
3680 Add an executable to the project using the specified source files.
3681 add_executable(<name> [WIN32] [MACOSX_BUNDLE]
3683 [EXCLUDE_FROM_ALL]
3684 [source1] [source2 ...])
3685 Adds an executable target called <name> to be built from the source
3687 files listed in the command invocation. (The source files can be omit‐
3688 ted here if they are added later using target_sources().) The <name>
3689 corresponds to the logical target name and must be globally unique
3690 within a project. The actual file name of the executable built is con‐
3691 structed based on conventions of the native platform (such as
3692 <name>.exe or just <name>).
3693 By default the executable file will be created in the build tree direc‐
3695 tory corresponding to the source tree directory in which the command
3696 was invoked. See documentation of the RUNTIME_OUTPUT_DIRECTORY target
3697 property to change this location. See documentation of the OUTPUT_NAME
3698 target property to change the <name> part of the final file name.
3699 If WIN32 is given the property WIN32_EXECUTABLE will be set on the tar‐
3701 get created. See documentation of that target property for details.
3702 If MACOSX_BUNDLE is given the corresponding property will be set on the
3704 created target. See documentation of the MACOSX_BUNDLE target property
3705 for details.
3706 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
3708 the created target. See documentation of the EXCLUDE_FROM_ALL target
3709 property for details.
3710 Source arguments to add_executable may use “generator expressions” with
3712 the syntax $<...>. See the cmake-generator-expressions(7) manual for
3713 available expressions. See the cmake-buildsystem(7) manual for more on
3714 defining buildsystem properties.
3715 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
3717 cessed, and you want to have the original sources reachable from within
3718 IDE.
3719 ----
3722 add_executable(<name> IMPORTED [GLOBAL])
3726 An IMPORTED executable target references an executable file located
3728 outside the project. No rules are generated to build it, and the
3729 IMPORTED target property is True. The target name has scope in the
3730 directory in which it is created and below, but the GLOBAL option
3731 extends visibility. It may be referenced like any target built within
3732 the project. IMPORTED executables are useful for convenient reference
3733 from commands like add_custom_command(). Details about the imported
3734 executable are specified by setting properties whose names begin in
3735 IMPORTED_. The most important such property is IMPORTED_LOCATION (and
3736 its per-configuration version IMPORTED_LOCATION_<CONFIG>) which speci‐
3737 fies the location of the main executable file on disk. See documenta‐
3738 tion of the IMPORTED_* properties for more information.
3739 ----
3742 add_executable(<name> ALIAS <target>)
3746 Creates an Alias Target, such that <name> can be used to refer to <tar‐
3748 get> in subsequent commands. The <name> does not appear in the gener‐
3749 ated buildsystem as a make target. The <target> may not be a
3750 non-GLOBAL Imported Target or an ALIAS. ALIAS targets can be used as
3751 targets to read properties from, executables for custom commands and
3752 custom targets. They can also be tested for existence with the regular
3753 if(TARGET) subcommand. The <name> may not be used to modify properties
3754 of <target>, that is, it may not be used as the operand of set_prop‐
3755 erty(), set_target_properties(), target_link_libraries() etc. An ALIAS
3756 target may not be installed or exported.
3757 add_library
3759 Add a library to the project using the specified source files.
3760 Normal Libraries
3762 add_library(<name> [STATIC | SHARED | MODULE]
3763 [EXCLUDE_FROM_ALL]
3764 [source1] [source2 ...])
3765 Adds a library target called <name> to be built from the source files
3767 listed in the command invocation. (The source files can be omitted
3768 here if they are added later using target_sources().) The <name> cor‐
3769 responds to the logical target name and must be globally unique within
3770 a project. The actual file name of the library built is constructed
3771 based on conventions of the native platform (such as lib<name>.a or
3772 <name>.lib).
3773 STATIC, SHARED, or MODULE may be given to specify the type of library
3775 to be created. STATIC libraries are archives of object files for use
3776 when linking other targets. SHARED libraries are linked dynamically
3777 and loaded at runtime. MODULE libraries are plugins that are not
3778 linked into other targets but may be loaded dynamically at runtime
3779 using dlopen-like functionality. If no type is given explicitly the
3780 type is STATIC or SHARED based on whether the current value of the
3781 variable BUILD_SHARED_LIBS is ON. For SHARED and MODULE libraries the
3782 POSITION_INDEPENDENT_CODE target property is set to ON automatically.
3783 A SHARED or STATIC library may be marked with the FRAMEWORK target
3784 property to create an OS X Framework.
3785 If a library does not export any symbols, it must not be declared as a
3787 SHARED library. For example, a Windows resource DLL or a managed
3788 C++/CLI DLL that exports no unmanaged symbols would need to be a MODULE
3789 library. This is because CMake expects a SHARED library to always have
3790 an associated import library on Windows.
3791 By default the library file will be created in the build tree directory
3793 corresponding to the source tree directory in which the command was
3794 invoked. See documentation of the ARCHIVE_OUTPUT_DIRECTORY,
3795 LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY target proper‐
3796 ties to change this location. See documentation of the OUTPUT_NAME
3797 target property to change the <name> part of the final file name.
3798 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
3800 the created target. See documentation of the EXCLUDE_FROM_ALL target
3801 property for details.
3802 Source arguments to add_library may use “generator expressions” with
3804 the syntax $<...>. See the cmake-generator-expressions(7) manual for
3805 available expressions. See the cmake-buildsystem(7) manual for more on
3806 defining buildsystem properties.
3807 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
3809 cessed, and you want to have the original sources reachable from within
3810 IDE.
3811 Imported Libraries
3813 add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED
3814 [GLOBAL])
3815 An IMPORTED library target references a library file located outside
3817 the project. No rules are generated to build it, and the IMPORTED tar‐
3818 get property is True. The target name has scope in the directory in
3819 which it is created and below, but the GLOBAL option extends visibil‐
3820 ity. It may be referenced like any target built within the project.
3821 IMPORTED libraries are useful for convenient reference from commands
3822 like target_link_libraries(). Details about the imported library are
3823 specified by setting properties whose names begin in IMPORTED_ and
3824 INTERFACE_. The most important such property is IMPORTED_LOCATION (and
3825 its per-configuration variant IMPORTED_LOCATION_<CONFIG>) which speci‐
3826 fies the location of the main library file on disk. See documentation
3827 of the IMPORTED_* and INTERFACE_* properties for more information.
3828 Object Libraries
3830 add_library(<name> OBJECT <src>...)
3831 Creates an Object Library. An object library compiles source files but
3833 does not archive or link their object files into a library. Instead
3834 other targets created by add_library() or add_executable() may refer‐
3835 ence the objects using an expression of the form $<TAR‐
3836 GET_OBJECTS:objlib> as a source, where objlib is the object library
3837 name. For example:
3838 add_library(... $<TARGET_OBJECTS:objlib> ...)
3840 add_executable(... $<TARGET_OBJECTS:objlib> ...)
3841 will include objlib’s object files in a library and an executable along
3843 with those compiled from their own sources. Object libraries may con‐
3844 tain only sources that compile, header files, and other files that
3845 would not affect linking of a normal library (e.g. .txt). They may
3846 contain custom commands generating such sources, but not PRE_BUILD,
3847 PRE_LINK, or POST_BUILD commands. Object libraries cannot be linked.
3848 Some native build systems (such as Xcode) may not like targets that
3849 have only object files, so consider adding at least one real source
3850 file to any target that references $<TARGET_OBJECTS:objlib>.
3851 Alias Libraries
3853 add_library(<name> ALIAS <target>)
3854 Creates an Alias Target, such that <name> can be used to refer to <tar‐
3856 get> in subsequent commands. The <name> does not appear in the gener‐
3857 ated buildsystem as a make target. The <target> may not be a
3858 non-GLOBAL Imported Target or an ALIAS. ALIAS targets can be used as
3859 linkable targets and as targets to read properties from. They can also
3860 be tested for existence with the regular if(TARGET) subcommand. The
3861 <name> may not be used to modify properties of <target>, that is, it
3862 may not be used as the operand of set_property(), set_target_proper‐
3863 ties(), target_link_libraries() etc. An ALIAS target may not be
3864 installed or exported.
3865 Interface Libraries
3867 add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
3868 Creates an Interface Library. An INTERFACE library target does not
3870 directly create build output, though it may have properties set on it
3871 and it may be installed, exported and imported. Typically the INTER‐
3872 FACE_* properties are populated on the interface target using the com‐
3873 mands:
3874 · set_property(),
3876 · target_link_libraries(INTERFACE),
3878 · target_include_directories(INTERFACE),
3880 · target_compile_options(INTERFACE),
3882 · target_compile_definitions(INTERFACE), and
3884 · target_sources(INTERFACE),
3886 and then it is used as an argument to target_link_libraries() like any
3888 other target.
3889 An INTERFACE Imported Target may also be created with this signature.
3891 An IMPORTED library target references a library defined outside the
3892 project. The target name has scope in the directory in which it is
3893 created and below, but the GLOBAL option extends visibility. It may be
3894 referenced like any target built within the project. IMPORTED
3895 libraries are useful for convenient reference from commands like tar‐
3896 get_link_libraries().
3897 add_subdirectory
3899 Add a subdirectory to the build.
3900 add_subdirectory(source_dir [binary_dir]
3902 [EXCLUDE_FROM_ALL])
3903 Add a subdirectory to the build. The source_dir specifies the direc‐
3905 tory in which the source CMakeLists.txt and code files are located. If
3906 it is a relative path it will be evaluated with respect to the current
3907 directory (the typical usage), but it may also be an absolute path.
3908 The binary_dir specifies the directory in which to place the output
3909 files. If it is a relative path it will be evaluated with respect to
3910 the current output directory, but it may also be an absolute path. If
3911 binary_dir is not specified, the value of source_dir, before expanding
3912 any relative path, will be used (the typical usage). The CMake‐
3913 Lists.txt file in the specified source directory will be processed
3914 immediately by CMake before processing in the current input file con‐
3915 tinues beyond this command.
3916 If the EXCLUDE_FROM_ALL argument is provided then targets in the subdi‐
3918 rectory will not be included in the ALL target of the parent directory
3919 by default, and will be excluded from IDE project files. Users must
3920 explicitly build targets in the subdirectory. This is meant for use
3921 when the subdirectory contains a separate part of the project that is
3922 useful but not necessary, such as a set of examples. Typically the
3923 subdirectory should contain its own project() command invocation so
3924 that a full build system will be generated in the subdirectory (such as
3925 a VS IDE solution file). Note that inter-target dependencies supersede
3926 this exclusion. If a target built by the parent project depends on a
3927 target in the subdirectory, the dependee target will be included in the
3928 parent project build system to satisfy the dependency.
3929 add_test
3931 Add a test to the project to be run by ctest(1).
3932 add_test(NAME <name> COMMAND <command> [<arg>...]
3934 [CONFIGURATIONS <config>...]
3935 [WORKING_DIRECTORY <dir>])
3936 Add a test called <name>. The test name may not contain spaces,
3938 quotes, or other characters special in CMake syntax. The options are:
3939 COMMAND
3941 Specify the test command-line. If <command> specifies an exe‐
3942 cutable target (created by add_executable()) it will automati‐
3943 cally be replaced by the location of the executable created at
3944 build time.
3945 CONFIGURATIONS
3947 Restrict execution of the test only to the named configurations.
3948 WORKING_DIRECTORY
3950 Set the WORKING_DIRECTORY test property to specify the working
3951 directory in which to execute the test. If not specified the
3952 test will be run with the current working directory set to the
3953 build directory corresponding to the current source directory.
3954 The given test command is expected to exit with code 0 to pass and
3956 non-zero to fail, or vice-versa if the WILL_FAIL test property is set.
3957 Any output written to stdout or stderr will be captured by ctest(1) but
3958 does not affect the pass/fail status unless the PASS_REGULAR_EXPRESSION
3959 or FAIL_REGULAR_EXPRESSION test property is used.
3960 The COMMAND and WORKING_DIRECTORY options may use “generator expres‐
3962 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
3963 manual for available expressions.
3964 Example usage:
3966 add_test(NAME mytest
3968 COMMAND testDriver --config $<CONFIGURATION>
3969 --exe $<TARGET_FILE:myexe>)
3970 This creates a test mytest whose command runs a testDriver tool passing
3972 the configuration name and the full path to the executable file pro‐
3973 duced by target myexe.
3974 NOTE:
3976 CMake will generate tests only if the enable_testing() command has
3977 been invoked. The CTest module invokes the command automatically
3978 when the BUILD_TESTING option is ON.
3979 ----
3982 add_test(<name> <command> [<arg>...])
3986 Add a test called <name> with the given command-line. Unlike the above
3988 NAME signature no transformation is performed on the command-line to
3989 support target names or generator expressions.
3990 aux_source_directory
3992 Find all source files in a directory.
3993 aux_source_directory(<dir> <variable>)
3995 Collects the names of all the source files in the specified directory
3997 and stores the list in the <variable> provided. This command is
3998 intended to be used by projects that use explicit template instantia‐
3999 tion. Template instantiation files can be stored in a “Templates” sub‐
4000 directory and collected automatically using this command to avoid manu‐
4001 ally listing all instantiations.
4002 It is tempting to use this command to avoid writing the list of source
4004 files for a library or executable target. While this seems to work,
4005 there is no way for CMake to generate a build system that knows when a
4006 new source file has been added. Normally the generated build system
4007 knows when it needs to rerun CMake because the CMakeLists.txt file is
4008 modified to add a new source. When the source is just added to the
4009 directory without modifying this file, one would have to manually rerun
4010 CMake to generate a build system incorporating the new file.
4011 build_command
4013 Get a command line to build the current project. This is mainly
4014 intended for internal use by the CTest module.
4015 build_command(<variable>
4017 [CONFIGURATION <config>]
4018 [TARGET <target>]
4019 [PROJECT_NAME <projname>] # legacy, causes warning
4020 )
4021 Sets the given <variable> to a command-line string of the form:
4023 <cmake> --build . [--config <config>] [--target <target>] [-- -i]
4025 where <cmake> is the location of the cmake(1) command-line tool, and
4027 <config> and <target> are the values provided to the CONFIGURATION and
4028 TARGET options, if any. The trailing -- -i option is added for Make‐
4029 file Generators if policy CMP0061 is not set to NEW.
4030 When invoked, this cmake --build command line will launch the underly‐
4032 ing build system tool.
4033 build_command(<cachevariable> <makecommand>)
4035 This second signature is deprecated, but still available for backwards
4037 compatibility. Use the first signature instead.
4038 It sets the given <cachevariable> to a command-line string as above but
4040 without the --target option. The <makecommand> is ignored but should
4041 be the full path to devenv, nmake, make or one of the end user build
4042 tools for legacy invocations.
4043 NOTE:
4045 In CMake versions prior to 3.0 this command returned a command line
4046 that directly invokes the native build tool for the current genera‐
4047 tor. Their implementation of the PROJECT_NAME option had no useful
4048 effects, so CMake now warns on use of the option.
4049 create_test_sourcelist
4051 Create a test driver and source list for building test programs.
4052 create_test_sourcelist(sourceListName driverName
4054 test1 test2 test3
4055 EXTRA_INCLUDE include.h
4056 FUNCTION function)
4057 A test driver is a program that links together many small tests into a
4059 single executable. This is useful when building static executables
4060 with large libraries to shrink the total required size. The list of
4061 source files needed to build the test driver will be in sourceListName.
4062 driverName is the name of the test driver program. The rest of the
4063 arguments consist of a list of test source files, can be semicolon sep‐
4064 arated. Each test source file should have a function in it that is the
4065 same name as the file with no extension (foo.cxx should have int
4066 foo(int, char*[]);) driverName will be able to call each of the tests
4067 by name on the command line. If EXTRA_INCLUDE is specified, then the
4068 next argument is included into the generated file. If FUNCTION is
4069 specified, then the next argument is taken as a function name that is
4070 passed a pointer to ac and av. This can be used to add extra command
4071 line processing to each test. The CMAKE_TESTDRIVER_BEFORE_TESTMAIN
4072 cmake variable can be set to have code that will be placed directly
4073 before calling the test main function. CMAKE_TESTDRIVER_AFTER_TESTMAIN
4074 can be set to have code that will be placed directly after the call to
4075 the test main function.
4076 define_property
4078 Define and document custom properties.
4079 define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
4081 TEST | VARIABLE | CACHED_VARIABLE>
4082 PROPERTY <name> [INHERITED]
4083 BRIEF_DOCS <brief-doc> [docs...]
4084 FULL_DOCS <full-doc> [docs...])
4085 Define one property in a scope for use with the set_property() and
4087 get_property() commands. This is primarily useful to associate docu‐
4088 mentation with property names that may be retrieved with the get_prop‐
4089 erty() command. The first argument determines the kind of scope in
4090 which the property should be used. It must be one of the following:
4091 GLOBAL = associated with the global namespace
4093 DIRECTORY = associated with one directory
4094 TARGET = associated with one target
4095 SOURCE = associated with one source file
4096 TEST = associated with a test named with add_test
4097 VARIABLE = documents a CMake language variable
4098 CACHED_VARIABLE = documents a CMake cache variable
4099 Note that unlike set_property() and get_property() no actual scope
4101 needs to be given; only the kind of scope is important.
4102 The required PROPERTY option is immediately followed by the name of the
4104 property being defined.
4105 If the INHERITED option then the get_property() command will chain up
4107 to the next higher scope when the requested property is not set in the
4108 scope given to the command. DIRECTORY scope chains to GLOBAL. TARGET,
4109 SOURCE, and TEST chain to DIRECTORY.
4110 The BRIEF_DOCS and FULL_DOCS options are followed by strings to be
4112 associated with the property as its brief and full documentation. Cor‐
4113 responding options to the get_property() command will retrieve the doc‐
4114 umentation.
4115 enable_language
4117 Enable a language (CXX/C/Fortran/etc)
4118 enable_language(<lang> [OPTIONAL] )
4120 This command enables support for the named language in CMake. This is
4122 the same as the project command but does not create any of the extra
4123 variables that are created by the project command. Example languages
4124 are CXX, C, CUDA, Fortran, and ASM.
4125 If enabling ASM, enable it last so that CMake can check whether compil‐
4127 ers for other languages like C work for assembly too.
4128 This command must be called in file scope, not in a function call.
4130 Furthermore, it must be called in the highest directory common to all
4131 targets using the named language directly for compiling sources or
4132 indirectly through link dependencies. It is simplest to enable all
4133 needed languages in the top-level directory of a project.
4134 The OPTIONAL keyword is a placeholder for future implementation and
4136 does not currently work. Instead you can use the CheckLanguage module
4137 to verify support before enabling.
4138 enable_testing
4140 Enable testing for current directory and below.
4141 enable_testing()
4143 Enables testing for this directory and below. See also the add_test()
4145 command. Note that ctest expects to find a test file in the build
4146 directory root. Therefore, this command should be in the source direc‐
4147 tory root.
4148 export
4150 Export targets from the build tree for use by outside projects.
4151 export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
4153 Create a file <filename> that may be included by outside projects to
4155 import targets from the current project’s build tree. This is useful
4156 during cross-compiling to build utility executables that can run on the
4157 host platform in one project and then import them into another project
4158 being compiled for the target platform. If the NAMESPACE option is
4159 given the <namespace> string will be prepended to all target names
4160 written to the file.
4161 Target installations are associated with the export <export-name> using
4163 the EXPORT option of the install(TARGETS) command.
4164 The file created by this command is specific to the build tree and
4166 should never be installed. See the install(EXPORT) command to export
4167 targets from an installation tree.
4168 The properties set on the generated IMPORTED targets will have the same
4170 values as the final values of the input TARGETS.
4171 export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
4173 [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
4174 This signature is similar to the EXPORT signature, but targets are
4176 listed explicitly rather than specified as an export-name. If the
4177 APPEND option is given the generated code will be appended to the file
4178 instead of overwriting it. The EXPORT_LINK_INTERFACE_LIBRARIES key‐
4179 word, if present, causes the contents of the properties matching
4180 (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported, when
4181 policy CMP0022 is NEW. If a library target is included in the export
4182 but a target to which it links is not included the behavior is unspeci‐
4183 fied.
4184 export(PACKAGE <name>)
4186 Store the current build directory in the CMake user package registry
4188 for package <name>. The find_package command may consider the direc‐
4189 tory while searching for package <name>. This helps dependent projects
4190 find and use a package from the current project’s build tree without
4191 help from the user. Note that the entry in the package registry that
4192 this command creates works only in conjunction with a package configu‐
4193 ration file (<name>Config.cmake) that works with the build tree. In
4194 some cases, for example for packaging and for system wide installa‐
4195 tions, it is not desirable to write the user package registry. If the
4196 CMAKE_EXPORT_NO_PACKAGE_REGISTRY variable is enabled, the export(PACK‐
4197 AGE) command will do nothing.
4198 export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>])
4200 This signature exports cmake built targets to the android ndk build
4202 system by creating an Android.mk file that references the prebuilt tar‐
4203 gets. The Android NDK supports the use of prebuilt libraries, both
4204 static and shared. This allows cmake to build the libraries of a
4205 project and make them available to an ndk build system complete with
4206 transitive dependencies, include flags and defines required to use the
4207 libraries. The signature takes a list of targets and puts them in the
4208 Android.mk file specified by the <filename> given. This signature can
4209 only be used if policy CMP0022 is NEW for all targets given. A error
4210 will be issued if that policy is set to OLD for one of the targets.
4211 fltk_wrap_ui
4213 Create FLTK user interfaces Wrappers.
4214 fltk_wrap_ui(resultingLibraryName source1
4216 source2 ... sourceN )
4217 Produce .h and .cxx files for all the .fl and .fld files listed. The
4219 resulting .h and .cxx files will be added to a variable named result‐
4220 ingLibraryName_FLTK_UI_SRCS which should be added to your library.
4221 get_source_file_property
4223 Get a property for a source file.
4224 get_source_file_property(VAR file property)
4226 Get a property from a source file. The value of the property is stored
4228 in the variable VAR. If the property is not found, VAR will be set to
4229 “NOTFOUND”. Use set_source_files_properties() to set property values.
4230 Source file properties usually control how the file is built. One prop‐
4231 erty that is always there is LOCATION
4232 See also the more general get_property() command.
4234 get_target_property
4236 Get a property from a target.
4237 get_target_property(VAR target property)
4239 Get a property from a target. The value of the property is stored in
4241 the variable VAR. If the property is not found, VAR will be set to
4242 “NOTFOUND”. Use set_target_properties() to set property values. Prop‐
4243 erties are usually used to control how a target is built, but some
4244 query the target instead. This command can get properties for any tar‐
4245 get so far created. The targets do not need to be in the current
4246 CMakeLists.txt file.
4247 See also the more general get_property() command.
4249 get_test_property
4251 Get a property of the test.
4252 get_test_property(test property VAR)
4254 Get a property from the test. The value of the property is stored in
4256 the variable VAR. If the test or property is not found, VAR will be
4257 set to “NOTFOUND”. For a list of standard properties you can type
4258 cmake --help-property-list.
4259 See also the more general get_property() command.
4261 include_directories
4263 Add include directories to the build.
4264 include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])
4266 Add the given directories to those the compiler uses to search for
4268 include files. Relative paths are interpreted as relative to the cur‐
4269 rent source directory.
4270 The include directories are added to the INCLUDE_DIRECTORIES directory
4272 property for the current CMakeLists file. They are also added to the
4273 INCLUDE_DIRECTORIES target property for each target in the current
4274 CMakeLists file. The target property values are the ones used by the
4275 generators.
4276 By default the directories specified are appended onto the current list
4278 of directories. This default behavior can be changed by setting
4279 CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE
4280 explicitly, you can select between appending and prepending, indepen‐
4281 dent of the default.
4282 If the SYSTEM option is given, the compiler will be told the directo‐
4284 ries are meant as system include directories on some platforms. Sig‐
4285 nalling this setting might achieve effects such as the compiler skip‐
4286 ping warnings, or these fixed-install system files not being considered
4287 in dependency calculations - see compiler docs.
4288 Arguments to include_directories may use “generator expressions” with
4290 the syntax “$<…>”. See the cmake-generator-expressions(7) manual for
4291 available expressions. See the cmake-buildsystem(7) manual for more on
4292 defining buildsystem properties.
4293 include_external_msproject
4295 Include an external Microsoft project file in a workspace.
4296 include_external_msproject(projectname location
4298 [TYPE projectTypeGUID]
4299 [GUID projectGUID]
4300 [PLATFORM platformName]
4301 dep1 dep2 ...)
4302 Includes an external Microsoft project in the generated workspace file.
4304 Currently does nothing on UNIX. This will create a target named [pro‐
4305 jectname]. This can be used in the add_dependencies() command to make
4306 things depend on the external project.
4307 TYPE, GUID and PLATFORM are optional parameters that allow one to spec‐
4309 ify the type of project, id (GUID) of the project and the name of the
4310 target platform. This is useful for projects requiring values other
4311 than the default (e.g. WIX projects).
4312 If the imported project has different configuration names than the cur‐
4314 rent project, set the MAP_IMPORTED_CONFIG_<CONFIG> target property to
4315 specify the mapping.
4316 include_regular_expression
4318 Set the regular expression used for dependency checking.
4319 include_regular_expression(regex_match [regex_complain])
4321 Set the regular expressions used in dependency checking. Only files
4323 matching regex_match will be traced as dependencies. Only files match‐
4324 ing regex_complain will generate warnings if they cannot be found
4325 (standard header paths are not searched). The defaults are:
4326 regex_match = "^.*$" (match everything)
4328 regex_complain = "^$" (match empty string only)
4329 install
4331 Specify rules to run at install time.
4332 Introduction
4334 This command generates installation rules for a project. Rules speci‐
4335 fied by calls to this command within a source directory are executed in
4336 order during installation. The order across directories is not
4337 defined.
4338 There are multiple signatures for this command. Some of them define
4340 installation options for files and targets. Options common to multiple
4341 signatures are covered here but they are valid only for signatures that
4342 specify them. The common options are:
4343 DESTINATION
4345 Specify the directory on disk to which a file will be installed.
4346 If a full path (with a leading slash or drive letter) is given
4347 it is used directly. If a relative path is given it is inter‐
4348 preted relative to the value of the CMAKE_INSTALL_PREFIX vari‐
4349 able. The prefix can be relocated at install time using the
4350 DESTDIR mechanism explained in the CMAKE_INSTALL_PREFIX variable
4351 documentation.
4352 PERMISSIONS
4354 Specify permissions for installed files. Valid permissions are
4355 OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE,
4356 GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID,
4357 and SETGID. Permissions that do not make sense on certain plat‐
4358 forms are ignored on those platforms.
4359 CONFIGURATIONS
4361 Specify a list of build configurations for which the install
4362 rule applies (Debug, Release, etc.). Note that the values speci‐
4363 fied for this option only apply to options listed AFTER the CON‐
4364 FIGURATIONS option. For example, to set separate install paths
4365 for the Debug and Release configurations, do the following:
4366 install(TARGETS target
4368 CONFIGURATIONS Debug
4369 RUNTIME DESTINATION Debug/bin)
4370 install(TARGETS target
4371 CONFIGURATIONS Release
4372 RUNTIME DESTINATION Release/bin)
4373 Note that CONFIGURATIONS appears BEFORE RUNTIME DESTINATION.
4375 COMPONENT
4377 Specify an installation component name with which the install
4378 rule is associated, such as “runtime” or “development”. During
4379 component-specific installation only install rules associated
4380 with the given component name will be executed. During a full
4381 installation all components are installed unless marked with
4382 EXCLUDE_FROM_ALL. If COMPONENT is not provided a default compo‐
4383 nent “Unspecified” is created. The default component name may
4384 be controlled with the CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
4385 variable.
4386 EXCLUDE_FROM_ALL
4388 Specify that the file is excluded from a full installation and
4389 only installed as part of a component-specific installation
4390 RENAME Specify a name for an installed file that may be different from
4392 the original file. Renaming is allowed only when a single file
4393 is installed by the command.
4394 OPTIONAL
4396 Specify that it is not an error if the file to be installed does
4397 not exist.
4398 Command signatures that install files may print messages during instal‐
4400 lation. Use the CMAKE_INSTALL_MESSAGE variable to control which mes‐
4401 sages are printed.
4402 Installing Targets
4404 install(TARGETS targets... [EXPORT <export-name>]
4405 [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
4406 PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
4407 [DESTINATION <dir>]
4408 [PERMISSIONS permissions...]
4409 [CONFIGURATIONS [Debug|Release|...]]
4410 [COMPONENT <component>]
4411 [OPTIONAL] [EXCLUDE_FROM_ALL]
4412 [NAMELINK_ONLY|NAMELINK_SKIP]
4413 ] [...]
4414 [INCLUDES DESTINATION [<dir> ...]]
4415 )
4416 The TARGETS form specifies rules for installing targets from a project.
4418 There are six kinds of target files that may be installed: ARCHIVE,
4419 LIBRARY, RUNTIME, OBJECTS, FRAMEWORK, and BUNDLE. Executables are
4420 treated as RUNTIME targets, except that those marked with the
4421 MACOSX_BUNDLE property are treated as BUNDLE targets on OS X. Static
4422 libraries are treated as ARCHIVE targets, except that those marked with
4423 the FRAMEWORK property are treated as FRAMEWORK targets on OS X. Mod‐
4424 ule libraries are always treated as LIBRARY targets. For non-DLL plat‐
4425 forms shared libraries are treated as LIBRARY targets, except that
4426 those marked with the FRAMEWORK property are treated as FRAMEWORK tar‐
4427 gets on OS X. For DLL platforms the DLL part of a shared library is
4428 treated as a RUNTIME target and the corresponding import library is
4429 treated as an ARCHIVE target. All Windows-based systems including Cyg‐
4430 win are DLL platforms. Object libraries are always treated as OBJECTS
4431 targets. The ARCHIVE, LIBRARY, RUNTIME, OBJECTS, and FRAMEWORK argu‐
4432 ments change the type of target to which the subsequent properties
4433 apply. If none is given the installation properties apply to all target
4434 types. If only one is given then only targets of that type will be
4435 installed (which can be used to install just a DLL or just an import
4436 library).
4437 The PRIVATE_HEADER, PUBLIC_HEADER, and RESOURCE arguments cause subse‐
4439 quent properties to be applied to installing a FRAMEWORK shared library
4440 target’s associated files on non-Apple platforms. Rules defined by
4441 these arguments are ignored on Apple platforms because the associated
4442 files are installed into the appropriate locations inside the framework
4443 folder. See documentation of the PRIVATE_HEADER, PUBLIC_HEADER, and
4444 RESOURCE target properties for details.
4445 Either NAMELINK_ONLY or NAMELINK_SKIP may be specified as a LIBRARY
4447 option. On some platforms a versioned shared library has a symbolic
4448 link such as:
4449 lib<name>.so -> lib<name>.so.1
4451 where lib<name>.so.1 is the soname of the library and lib<name>.so is a
4453 “namelink” allowing linkers to find the library when given -l<name>.
4454 The NAMELINK_ONLY option causes installation of only the namelink when
4455 a library target is installed. The NAMELINK_SKIP option causes instal‐
4456 lation of library files other than the namelink when a library target
4457 is installed. When neither option is given both portions are
4458 installed. On platforms where versioned shared libraries do not have
4459 namelinks or when a library is not versioned the NAMELINK_SKIP option
4460 installs the library and the NAMELINK_ONLY option installs nothing.
4461 See the VERSION and SOVERSION target properties for details on creating
4462 versioned shared libraries.
4463 The INCLUDES DESTINATION specifies a list of directories which will be
4465 added to the INTERFACE_INCLUDE_DIRECTORIES target property of the <tar‐
4466 gets> when exported by the install(EXPORT) command. If a relative path
4467 is specified, it is treated as relative to the $<INSTALL_PREFIX>. This
4468 is independent of the rest of the argument groups and does not actually
4469 install anything.
4470 One or more groups of properties may be specified in a single call to
4472 the TARGETS form of this command. A target may be installed more than
4473 once to different locations. Consider hypothetical targets myExe,
4474 mySharedLib, and myStaticLib. The code:
4475 install(TARGETS myExe mySharedLib myStaticLib
4477 RUNTIME DESTINATION bin
4478 LIBRARY DESTINATION lib
4479 ARCHIVE DESTINATION lib/static)
4480 install(TARGETS mySharedLib DESTINATION /some/full/path)
4481 will install myExe to <prefix>/bin and myStaticLib to <pre‐
4483 fix>/lib/static. On non-DLL platforms mySharedLib will be installed to
4484 <prefix>/lib and /some/full/path. On DLL platforms the mySharedLib DLL
4485 will be installed to <prefix>/bin and /some/full/path and its import
4486 library will be installed to <prefix>/lib/static and /some/full/path.
4487 The EXPORT option associates the installed target files with an export
4489 called <export-name>. It must appear before any RUNTIME, LIBRARY, AR‐
4490 CHIVE, or OBJECTS options. To actually install the export file itself,
4491 call install(EXPORT), documented below.
4492 Installing a target with the EXCLUDE_FROM_ALL target property set to
4494 TRUE has undefined behavior.
4495 The install destination given to the target install DESTINATION may use
4497 “generator expressions” with the syntax $<...>. See the cmake-genera‐
4498 tor-expressions(7) manual for available expressions.
4499 Installing Files
4501 install(<FILES|PROGRAMS> files... DESTINATION <dir>
4502 [PERMISSIONS permissions...]
4503 [CONFIGURATIONS [Debug|Release|...]]
4504 [COMPONENT <component>]
4505 [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
4506 The FILES form specifies rules for installing files for a project.
4508 File names given as relative paths are interpreted with respect to the
4509 current source directory. Files installed by this form are by default
4510 given permissions OWNER_WRITE, OWNER_READ, GROUP_READ, and WORLD_READ
4511 if no PERMISSIONS argument is given.
4512 The PROGRAMS form is identical to the FILES form except that the
4514 default permissions for the installed file also include OWNER_EXECUTE,
4515 GROUP_EXECUTE, and WORLD_EXECUTE. This form is intended to install
4516 programs that are not targets, such as shell scripts. Use the TARGETS
4517 form to install targets built within the project.
4518 The list of files... given to FILES or PROGRAMS may use “generator
4520 expressions” with the syntax $<...>. See the cmake-generator-expres‐
4521 sions(7) manual for available expressions. However, if any item begins
4522 in a generator expression it must evaluate to a full path.
4523 The install destination given to the files install DESTINATION may use
4525 “generator expressions” with the syntax $<...>. See the cmake-genera‐
4526 tor-expressions(7) manual for available expressions.
4527 Installing Directories
4529 install(DIRECTORY dirs... DESTINATION <dir>
4530 [FILE_PERMISSIONS permissions...]
4531 [DIRECTORY_PERMISSIONS permissions...]
4532 [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
4533 [CONFIGURATIONS [Debug|Release|...]]
4534 [COMPONENT <component>] [EXCLUDE_FROM_ALL]
4535 [FILES_MATCHING]
4536 [[PATTERN <pattern> | REGEX <regex>]
4537 [EXCLUDE] [PERMISSIONS permissions...]] [...])
4538 The DIRECTORY form installs contents of one or more directories to a
4540 given destination. The directory structure is copied verbatim to the
4541 destination. The last component of each directory name is appended to
4542 the destination directory but a trailing slash may be used to avoid
4543 this because it leaves the last component empty. Directory names given
4544 as relative paths are interpreted with respect to the current source
4545 directory. If no input directory names are given the destination
4546 directory will be created but nothing will be installed into it. The
4547 FILE_PERMISSIONS and DIRECTORY_PERMISSIONS options specify permissions
4548 given to files and directories in the destination. If USE_SOURCE_PER‐
4549 MISSIONS is specified and FILE_PERMISSIONS is not, file permissions
4550 will be copied from the source directory structure. If no permissions
4551 are specified files will be given the default permissions specified in
4552 the FILES form of the command, and the directories will be given the
4553 default permissions specified in the PROGRAMS form of the command.
4554 The MESSAGE_NEVER option disables file installation status output.
4556 Installation of directories may be controlled with fine granularity
4558 using the PATTERN or REGEX options. These “match” options specify a
4559 globbing pattern or regular expression to match directories or files
4560 encountered within input directories. They may be used to apply cer‐
4561 tain options (see below) to a subset of the files and directories
4562 encountered. The full path to each input file or directory (with for‐
4563 ward slashes) is matched against the expression. A PATTERN will match
4564 only complete file names: the portion of the full path matching the
4565 pattern must occur at the end of the file name and be preceded by a
4566 slash. A REGEX will match any portion of the full path but it may use
4567 / and $ to simulate the PATTERN behavior. By default all files and
4568 directories are installed whether or not they are matched. The
4569 FILES_MATCHING option may be given before the first match option to
4570 disable installation of files (but not directories) not matched by any
4571 expression. For example, the code
4572 install(DIRECTORY src/ DESTINATION include/myproj
4574 FILES_MATCHING PATTERN "*.h")
4575 will extract and install header files from a source tree.
4577 Some options may follow a PATTERN or REGEX expression and are applied
4579 only to files or directories matching them. The EXCLUDE option will
4580 skip the matched file or directory. The PERMISSIONS option overrides
4581 the permissions setting for the matched file or directory. For example
4582 the code
4583 install(DIRECTORY icons scripts/ DESTINATION share/myproj
4585 PATTERN "CVS" EXCLUDE
4586 PATTERN "scripts/*"
4587 PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
4588 GROUP_EXECUTE GROUP_READ)
4589 will install the icons directory to share/myproj/icons and the scripts
4591 directory to share/myproj. The icons will get default file permis‐
4592 sions, the scripts will be given specific permissions, and any CVS
4593 directories will be excluded.
4594 The list of dirs... given to DIRECTORY and the install destination
4596 given to the directory install DESTINATION may use “generator expres‐
4597 sions” with the syntax $<...>. See the cmake-generator-expressions(7)
4598 manual for available expressions.
4599 Custom Installation Logic
4601 install([[SCRIPT <file>] [CODE <code>]]
4602 [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])
4603 The SCRIPT form will invoke the given CMake script files during instal‐
4605 lation. If the script file name is a relative path it will be inter‐
4606 preted with respect to the current source directory. The CODE form
4607 will invoke the given CMake code during installation. Code is speci‐
4608 fied as a single argument inside a double-quoted string. For example,
4609 the code
4610 install(CODE "MESSAGE(\"Sample install message.\")")
4612 will print a message during installation.
4614 Installing Exports
4616 install(EXPORT <export-name> DESTINATION <dir>
4617 [NAMESPACE <namespace>] [[FILE <name>.cmake]|
4618 [EXPORT_ANDROID_MK <name>.mk]]
4619 [PERMISSIONS permissions...]
4620 [CONFIGURATIONS [Debug|Release|...]]
4621 [EXPORT_LINK_INTERFACE_LIBRARIES]
4622 [COMPONENT <component>]
4623 [EXCLUDE_FROM_ALL])
4624 The EXPORT form generates and installs a CMake file containing code to
4626 import targets from the installation tree into another project. Target
4627 installations are associated with the export <export-name> using the
4628 EXPORT option of the install(TARGETS) signature documented above. The
4629 NAMESPACE option will prepend <namespace> to the target names as they
4630 are written to the import file. By default the generated file will be
4631 called <export-name>.cmake but the FILE option may be used to specify a
4632 different name. The value given to the FILE option must be a file name
4633 with the .cmake extension. If a CONFIGURATIONS option is given then
4634 the file will only be installed when one of the named configurations is
4635 installed. Additionally, the generated import file will reference only
4636 the matching target configurations. The EXPORT_LINK_INTER‐
4637 FACE_LIBRARIES keyword, if present, causes the contents of the proper‐
4638 ties matching (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be
4639 exported, when policy CMP0022 is NEW. If a COMPONENT option is speci‐
4640 fied that does not match that given to the targets associated with
4641 <export-name> the behavior is undefined. If a library target is
4642 included in the export but a target to which it links is not included
4643 the behavior is unspecified.
4644 In addition to cmake language files, the EXPORT_ANDROID_MK option maybe
4646 used to specify an export to the android ndk build system. The Android
4647 NDK supports the use of prebuilt libraries, both static and shared.
4648 This allows cmake to build the libraries of a project and make them
4649 available to an ndk build system complete with transitive dependencies,
4650 include flags and defines required to use the libraries.
4651 The EXPORT form is useful to help outside projects use targets built
4653 and installed by the current project. For example, the code
4654 install(TARGETS myexe EXPORT myproj DESTINATION bin)
4656 install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
4657 install(EXPORT_ANDROID_MK myexp DESTINATION share/ndk-modules)
4658 will install the executable myexe to <prefix>/bin and code to import it
4660 in the file <prefix>/lib/myproj/myproj.cmake and <pre‐
4661 fix>/lib/share/ndk-modules/Android.mk. An outside project may load
4662 this file with the include command and reference the myexe executable
4663 from the installation tree using the imported target name mp_myexe as
4664 if the target were built in its own tree.
4665 NOTE:
4667 This command supercedes the install_targets() command and the
4668 PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT target properties. It
4669 also replaces the FILES forms of the install_files() and
4670 install_programs() commands. The processing order of these install
4671 rules relative to those generated by install_targets(),
4672 install_files(), and install_programs() commands is not defined.
4673 link_directories
4675 Specify directories in which the linker will look for libraries.
4676 link_directories(directory1 directory2 ...)
4678 Specify the paths in which the linker should search for libraries. The
4680 command will apply only to targets created after it is called. Rela‐
4681 tive paths given to this command are interpreted as relative to the
4682 current source directory, see CMP0015.
4683 Note that this command is rarely necessary. Library locations returned
4685 by find_package() and find_library() are absolute paths. Pass these
4686 absolute library file paths directly to the target_link_libraries()
4687 command. CMake will ensure the linker finds them.
4688 link_libraries
4690 Link libraries to all targets added later.
4691 link_libraries([item1 [item2 [...]]]
4693 [[debug|optimized|general] <item>] ...)
4694 Specify libraries or flags to use when linking any targets created
4696 later in the current directory or below by commands such as add_exe‐
4697 cutable() or add_library(). See the target_link_libraries() command
4698 for meaning of arguments.
4699 NOTE:
4701 The target_link_libraries() command should be preferred whenever
4702 possible. Library dependencies are chained automatically, so direc‐
4703 tory-wide specification of link libraries is rarely needed.
4704 load_cache
4706 Load in the values from another project’s CMake cache.
4707 load_cache(pathToCacheFile READ_WITH_PREFIX
4709 prefix entry1...)
4710 Read the cache and store the requested entries in variables with their
4712 name prefixed with the given prefix. This only reads the values, and
4713 does not create entries in the local project’s cache.
4714 load_cache(pathToCacheFile [EXCLUDE entry1...]
4716 [INCLUDE_INTERNALS entry1...])
4717 Load in the values from another cache and store them in the local
4719 project’s cache as internal entries. This is useful for a project that
4720 depends on another project built in a different tree. EXCLUDE option
4721 can be used to provide a list of entries to be excluded.
4722 INCLUDE_INTERNALS can be used to provide a list of internal entries to
4723 be included. Normally, no internal entries are brought in. Use of
4724 this form of the command is strongly discouraged, but it is provided
4725 for backward compatibility.
4726 project
4728 Set a name, version, and enable languages for the entire project.
4729 project(<PROJECT-NAME> [LANGUAGES] [<language-name>...])
4731 project(<PROJECT-NAME>
4732 [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
4733 [DESCRIPTION <project-description-string>]
4734 [LANGUAGES <language-name>...])
4735 Sets the name of the project and stores the name in the PROJECT_NAME
4737 variable. Additionally this sets variables
4738 · PROJECT_SOURCE_DIR, <PROJECT-NAME>_SOURCE_DIR
4740 · PROJECT_BINARY_DIR, <PROJECT-NAME>_BINARY_DIR
4742 If VERSION is specified, given components must be non-negative inte‐
4744 gers. If VERSION is not specified, the default version is the empty
4745 string. The VERSION option may not be used unless policy CMP0048 is
4746 set to NEW.
4747 The project() command stores the version number and its components in
4749 variables
4750 · PROJECT_VERSION, <PROJECT-NAME>_VERSION
4752 · PROJECT_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MAJOR
4754 · PROJECT_VERSION_MINOR, <PROJECT-NAME>_VERSION_MINOR
4756 · PROJECT_VERSION_PATCH, <PROJECT-NAME>_VERSION_PATCH
4758 · PROJECT_VERSION_TWEAK, <PROJECT-NAME>_VERSION_TWEAK
4760 Variables corresponding to unspecified versions are set to the empty
4762 string (if policy CMP0048 is set to NEW).
4763 If optional DESCRIPTION is given, then additional PROJECT_DESCRIPTION
4765 variable will be set to its argument. The argument must be a string
4766 with short description of the project (only a few words).
4767 Optionally you can specify which languages your project supports.
4769 Example languages include C, CXX (i.e. C++), CUDA, Fortran, and ASM.
4770 By default C and CXX are enabled if no language options are given.
4771 Specify language NONE, or use the LANGUAGES keyword and list no lan‐
4772 guages, to skip enabling any languages.
4773 If enabling ASM, list it last so that CMake can check whether compilers
4775 for other languages like C work for assembly too.
4776 If a variable exists called CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE, the
4778 file pointed to by that variable will be included as the last step of
4779 the project command.
4780 The top-level CMakeLists.txt file for a project must contain a literal,
4782 direct call to the project() command; loading one through the include()
4783 command is not sufficient. If no such call exists CMake will implic‐
4784 itly add one to the top that enables the default languages (C and CXX).
4785 NOTE:
4787 Call the cmake_minimum_required() command at the beginning of the
4788 top-level CMakeLists.txt file even before calling the project() com‐
4789 mand. It is important to establish version and policy settings
4790 before invoking other commands whose behavior they may affect. See
4791 also policy CMP0000.
4792 qt_wrap_cpp
4794 Create Qt Wrappers.
4795 qt_wrap_cpp(resultingLibraryName DestName
4797 SourceLists ...)
4798 Produce moc files for all the .h files listed in the SourceLists. The
4800 moc files will be added to the library using the DestName source list.
4801 qt_wrap_ui
4803 Create Qt user interfaces Wrappers.
4804 qt_wrap_ui(resultingLibraryName HeadersDestName
4806 SourcesDestName SourceLists ...)
4807 Produce .h and .cxx files for all the .ui files listed in the
4809 SourceLists. The .h files will be added to the library using the Head‐
4810 ersDestNamesource list. The .cxx files will be added to the library
4811 using the SourcesDestNamesource list.
4812 remove_definitions
4814 Removes -D define flags added by add_definitions().
4815 remove_definitions(-DFOO -DBAR ...)
4817 Removes flags (added by add_definitions()) from the compiler command
4819 line for sources in the current directory and below.
4820 set_source_files_properties
4822 Source files can have properties that affect how they are built.
4823 set_source_files_properties([file1 [file2 [...]]]
4825 PROPERTIES prop1 value1
4826 [prop2 value2 [...]])
4827 Set properties associated with source files using a key/value paired
4829 list. See Source File Properties for the list of properties known to
4830 CMake. Source file properties are visible only to targets added in the
4831 same directory (CMakeLists.txt).
4832 set_target_properties
4834 Targets can have properties that affect how they are built.
4835 set_target_properties(target1 target2 ...
4837 PROPERTIES prop1 value1
4838 prop2 value2 ...)
4839 Set properties on a target. The syntax for the command is to list all
4841 the files you want to change, and then provide the values you want to
4842 set next. You can use any prop value pair you want and extract it
4843 later with the get_property() or get_target_property() command.
4844 See Target Properties for the list of properties known to CMake.
4846 set_tests_properties
4848 Set a property of the tests.
4849 set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
4851 Set a property for the tests. If the test is not found, CMake will
4853 report an error. Generator expressions will be expanded the same as
4854 supported by the test’s add_test() call. See Test Properties for the
4855 list of properties known to CMake.
4856 source_group
4858 Define a grouping for source files in IDE project generation. There
4859 are two different signatures to create source groups.
4860 source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
4862 source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...])
4863 Defines a group into which sources will be placed in project files.
4865 This is intended to set up file tabs in Visual Studio. The options
4866 are:
4867 TREE CMake will automatically detect, from <src> files paths, source
4869 groups it needs to create, to keep structure of source groups
4870 analogically to the actual files and directories structure in
4871 the project. Paths of <src> files will be cut to be relative to
4872 <root>.
4873 PREFIX Source group and files located directly in <root> path, will be
4875 placed in <prefix> source groups.
4876 FILES Any source file specified explicitly will be placed in group
4878 <name>. Relative paths are interpreted with respect to the cur‐
4879 rent source directory.
4880 REGULAR_EXPRESSION
4882 Any source file whose name matches the regular expression will
4883 be placed in group <name>.
4884 If a source file matches multiple groups, the last group that explic‐
4886 itly lists the file with FILES will be favored, if any. If no group
4887 explicitly lists the file, the last group whose regular expression
4888 matches the file will be favored.
4889 The <name> of the group and <prefix> argument may contain backslashes
4891 to specify subgroups:
4892 source_group(outer\\inner ...)
4894 source_group(TREE <root> PREFIX sources\\inc ...)
4895 For backwards compatibility, the short-hand signature
4897 source_group(<name> <regex>)
4899 is equivalent to
4901 source_group(<name> REGULAR_EXPRESSION <regex>)
4903 target_compile_definitions
4905 Add compile definitions to a target.
4906 target_compile_definitions(<target>
4908 <INTERFACE|PUBLIC|PRIVATE> [items1...]
4909 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
4910 Specify compile definitions to use when compiling a given <target>.
4912 The named <target> must have been created by a command such as add_exe‐
4913 cutable() or add_library() and must not be an ALIAS target.
4914 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
4916 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
4917 late the COMPILE_DEFINITIONS property of <target>. PUBLIC and INTERFACE
4918 items will populate the INTERFACE_COMPILE_DEFINITIONS property of <tar‐
4919 get>. (IMPORTED targets only support INTERFACE items.) The following
4920 arguments specify compile definitions. Repeated calls for the same
4921 <target> append items in the order called.
4922 Arguments to target_compile_definitions may use “generator expressions”
4924 with the syntax $<...>. See the cmake-generator-expressions(7) manual
4925 for available expressions. See the cmake-buildsystem(7) manual for
4926 more on defining buildsystem properties.
4927 target_compile_features
4929 Add expected compiler features to a target.
4930 target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
4932 Specify compiler features required when compiling a given target. If
4934 the feature is not listed in the CMAKE_C_COMPILE_FEATURES variable or
4935 CMAKE_CXX_COMPILE_FEATURES variable, then an error will be reported by
4936 CMake. If the use of the feature requires an additional compiler flag,
4937 such as -std=gnu++11, the flag will be added automatically.
4938 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
4940 scope of the features. PRIVATE and PUBLIC items will populate the COM‐
4941 PILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
4942 populate the INTERFACE_COMPILE_FEATURES property of <target>.
4943 (IMPORTED targets only support INTERFACE items.) Repeated calls for
4944 the same <target> append items.
4945 The named <target> must have been created by a command such as add_exe‐
4947 cutable() or add_library() and must not be an ALIAS target.
4948 Arguments to target_compile_features may use “generator expressions”
4950 with the syntax $<...>. See the cmake-generator-expressions(7) manual
4951 for available expressions. See the cmake-compile-features(7) manual
4952 for information on compile features and a list of supported compilers.
4953 target_compile_options
4955 Add compile options to a target.
4956 target_compile_options(<target> [BEFORE]
4958 <INTERFACE|PUBLIC|PRIVATE> [items1...]
4959 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
4960 Specify compile options to use when compiling a given target. The
4962 named <target> must have been created by a command such as add_exe‐
4963 cutable() or add_library() and must not be an ALIAS target.
4964 If BEFORE is specified, the content will be prepended to the property
4966 instead of being appended.
4967 This command can be used to add any options, but alternative commands
4969 exist to add preprocessor definitions (target_compile_definitions() and
4970 add_definitions()) or include directories (target_include_directories()
4971 and include_directories()). See documentation of the directory and
4972 target COMPILE_OPTIONS properties.
4973 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
4975 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
4976 late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
4977 items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
4978 (IMPORTED targets only support INTERFACE items.) The following argu‐
4979 ments specify compile options. Repeated calls for the same <target>
4980 append items in the order called.
4981 Arguments to target_compile_options may use “generator expressions”
4983 with the syntax $<...>. See the cmake-generator-expressions(7) manual
4984 for available expressions. See the cmake-buildsystem(7) manual for
4985 more on defining buildsystem properties.
4986 target_include_directories
4988 Add include directories to a target.
4989 target_include_directories(<target> [SYSTEM] [BEFORE]
4991 <INTERFACE|PUBLIC|PRIVATE> [items1...]
4992 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
4993 Specify include directories to use when compiling a given target. The
4995 named <target> must have been created by a command such as add_exe‐
4996 cutable() or add_library() and must not be an ALIAS target.
4997 If BEFORE is specified, the content will be prepended to the property
4999 instead of being appended.
5000 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
5002 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
5003 late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTER‐
5004 FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
5005 <target>. (IMPORTED targets only support INTERFACE items.) The fol‐
5006 lowing arguments specify include directories.
5007 Specified include directories may be absolute paths or relative paths.
5009 Repeated calls for the same <target> append items in the order called.
5010 If SYSTEM is specified, the compiler will be told the directories are
5011 meant as system include directories on some platforms (signalling this
5012 setting might achieve effects such as the compiler skipping warnings,
5013 or these fixed-install system files not being considered in dependency
5014 calculations - see compiler docs). If SYSTEM is used together with
5015 PUBLIC or INTERFACE, the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
5016 property will be populated with the specified directories.
5017 Arguments to target_include_directories may use “generator expressions”
5019 with the syntax $<...>. See the cmake-generator-expressions(7) manual
5020 for available expressions. See the cmake-buildsystem(7) manual for
5021 more on defining buildsystem properties.
5022 Include directories usage requirements commonly differ between the
5024 build-tree and the install-tree. The BUILD_INTERFACE and
5025 INSTALL_INTERFACE generator expressions can be used to describe sepa‐
5026 rate usage requirements based on the usage location. Relative paths
5027 are allowed within the INSTALL_INTERFACE expression and are interpreted
5028 relative to the installation prefix. For example:
5029 target_include_directories(mylib PUBLIC
5031 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
5032 $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
5033 )
5034 Creating Relocatable Packages
5036 Note that it is not advisable to populate the INSTALL_INTERFACE of the
5037 INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
5038 include directories of dependencies. That would hard-code into
5039 installed packages the include directory paths for dependencies as
5040 found on the machine the package was made on.
5041 The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
5043 suitable for specifying the required include directories for headers
5044 provided with the target itself, not those provided by the transitive
5045 dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
5046 Those dependencies should themselves be targets that specify their own
5047 header locations in INTERFACE_INCLUDE_DIRECTORIES.
5048 See the Creating Relocatable Packages section of the cmake-packages(7)
5050 manual for discussion of additional care that must be taken when speci‐
5051 fying usage requirements while creating packages for redistribution.
5052 target_link_libraries
5054 Specify libraries or flags to use when linking a given target and/or
5055 its dependents. Usage requirements from linked library targets will be
5056 propagated. Usage requirements of a target’s dependencies affect com‐
5057 pilation of its own sources.
5058 Overview
5060 This command has several signatures as detailed in subsections below.
5061 All of them have the general form:
5062 target_link_libraries(<target> ... <item>... ...)
5064 The named <target> must have been created in the current directory by a
5066 command such as add_executable() or add_library() and must not be an
5067 ALIAS target. Repeated calls for the same <target> append items in the
5068 order called. Each <item> may be:
5069 · A library target name: The generated link line will have the full
5071 path to the linkable library file associated with the target. The
5072 buildsystem will have a dependency to re-link <target> if the library
5073 file changes.
5074 The named target must be created by add_library() within the project
5076 or as an IMPORTED library. If it is created within the project an
5077 ordering dependency will automatically be added in the build system
5078 to make sure the named library target is up-to-date before the <tar‐
5079 get> links.
5080 If an imported library has the IMPORTED_NO_SONAME target property
5082 set, CMake may ask the linker to search for the library instead of
5083 using the full path (e.g. /usr/lib/libfoo.so becomes -lfoo).
5084 · A full path to a library file: The generated link line will normally
5086 preserve the full path to the file. The buildsystem will have a
5087 dependency to re-link <target> if the library file changes.
5088 There are some cases where CMake may ask the linker to search for the
5090 library (e.g. /usr/lib/libfoo.so becomes -lfoo), such as when a
5091 shared library is detected to have no SONAME field. See policy
5092 CMP0060 for discussion of another case.
5093 If the library file is in a Mac OSX framework, the Headers directory
5095 of the framework will also be processed as a usage requirement. This
5096 has the same effect as passing the framework directory as an include
5097 directory.
5098 On Visual Studio Generators for VS 2010 and above, library files end‐
5100 ing in .targets will be treated as MSBuild targets files and imported
5101 into generated project files. This is not supported by other genera‐
5102 tors.
5103 · A plain library name: The generated link line will ask the linker to
5105 search for the library (e.g. foo becomes -lfoo or foo.lib).
5106 · A link flag: Item names starting with -, but not -l or -framework,
5108 are treated as linker flags. Note that such flags will be treated
5109 like any other library link item for purposes of transitive dependen‐
5110 cies, so they are generally safe to specify only as private link
5111 items that will not propagate to dependents.
5112 Link flags specified here are inserted into the link command in the
5114 same place as the link libraries. This might not be correct, depend‐
5115 ing on the linker. Use the LINK_FLAGS target property to add link
5116 flags explicitly. The flags will then be placed at the
5117 toolchain-defined flag position in the link command.
5118 · A debug, optimized, or general keyword immediately followed by
5120 another <item>. The item following such a keyword will be used only
5121 for the corresponding build configuration. The debug keyword corre‐
5122 sponds to the Debug configuration (or to configurations named in the
5123 DEBUG_CONFIGURATIONS global property if it is set). The optimized
5124 keyword corresponds to all other configurations. The general keyword
5125 corresponds to all configurations, and is purely optional. Higher
5126 granularity may be achieved for per-configuration rules by creating
5127 and linking to IMPORTED library targets.
5128 Items containing ::, such as Foo::Bar, are assumed to be IMPORTED or
5130 ALIAS library target names and will cause an error if no such target
5131 exists. See policy CMP0028.
5132 Arguments to target_link_libraries may use “generator expressions” with
5134 the syntax $<...>. Note however, that generator expressions will not
5135 be used in OLD handling of CMP0003 or CMP0004. See the cmake-genera‐
5136 tor-expressions(7) manual for available expressions. See the
5137 cmake-buildsystem(7) manual for more on defining buildsystem proper‐
5138 ties.
5139 Libraries for a Target and/or its Dependents
5141 target_link_libraries(<target>
5142 <PRIVATE|PUBLIC|INTERFACE> <item>...
5143 [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
5144 The PUBLIC, PRIVATE and INTERFACE keywords can be used to specify both
5146 the link dependencies and the link interface in one command. Libraries
5147 and targets following PUBLIC are linked to, and are made part of the
5148 link interface. Libraries and targets following PRIVATE are linked to,
5149 but are not made part of the link interface. Libraries following
5150 INTERFACE are appended to the link interface and are not used for link‐
5151 ing <target>.
5152 Libraries for both a Target and its Dependents
5154 target_link_libraries(<target> <item>...)
5155 Library dependencies are transitive by default with this signature.
5157 When this target is linked into another target then the libraries
5158 linked to this target will appear on the link line for the other target
5159 too. This transitive “link interface” is stored in the INTER‐
5160 FACE_LINK_LIBRARIES target property and may be overridden by setting
5161 the property directly. When CMP0022 is not set to NEW, transitive
5162 linking is built in but may be overridden by the LINK_INTER‐
5163 FACE_LIBRARIES property. Calls to other signatures of this command may
5164 set the property making any libraries linked exclusively by this signa‐
5165 ture private.
5166 Libraries for a Target and/or its Dependents (Legacy)
5168 target_link_libraries(<target>
5169 <LINK_PRIVATE|LINK_PUBLIC> <lib>...
5170 [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
5171 The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both the
5173 link dependencies and the link interface in one command.
5174 This signature is for compatibility only. Prefer the PUBLIC or PRIVATE
5176 keywords instead.
5177 Libraries and targets following LINK_PUBLIC are linked to, and are made
5179 part of the INTERFACE_LINK_LIBRARIES. If policy CMP0022 is not NEW,
5180 they are also made part of the LINK_INTERFACE_LIBRARIES. Libraries and
5181 targets following LINK_PRIVATE are linked to, but are not made part of
5182 the INTERFACE_LINK_LIBRARIES (or LINK_INTERFACE_LIBRARIES).
5183 Libraries for Dependents Only (Legacy)
5185 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
5186 The LINK_INTERFACE_LIBRARIES mode appends the libraries to the INTER‐
5188 FACE_LINK_LIBRARIES target property instead of using them for linking.
5189 If policy CMP0022 is not NEW, then this mode also appends libraries to
5190 the LINK_INTERFACE_LIBRARIES and its per-configuration equivalent.
5191 This signature is for compatibility only. Prefer the INTERFACE mode
5193 instead.
5194 Libraries specified as debug are wrapped in a generator expression to
5196 correspond to debug builds. If policy CMP0022 is not NEW, the
5197 libraries are also appended to the LINK_INTERFACE_LIBRARIES_DEBUG prop‐
5198 erty (or to the properties corresponding to configurations listed in
5199 the DEBUG_CONFIGURATIONS global property if it is set). Libraries
5200 specified as optimized are appended to the INTERFACE_LINK_LIBRARIES
5201 property. If policy CMP0022 is not NEW, they are also appended to the
5202 LINK_INTERFACE_LIBRARIES property. Libraries specified as general (or
5203 without any keyword) are treated as if specified for both debug and
5204 optimized.
5205 Cyclic Dependencies of Static Libraries
5207 The library dependency graph is normally acyclic (a DAG), but in the
5208 case of mutually-dependent STATIC libraries CMake allows the graph to
5209 contain cycles (strongly connected components). When another target
5210 links to one of the libraries, CMake repeats the entire connected com‐
5211 ponent. For example, the code
5212 add_library(A STATIC a.c)
5214 add_library(B STATIC b.c)
5215 target_link_libraries(A B)
5216 target_link_libraries(B A)
5217 add_executable(main main.c)
5218 target_link_libraries(main A)
5219 links main to A B A B. While one repetition is usually sufficient,
5221 pathological object file and symbol arrangements can require more. One
5222 may handle such cases by using the LINK_INTERFACE_MULTIPLICITY target
5223 property or by manually repeating the component in the last tar‐
5224 get_link_libraries call. However, if two archives are really so inter‐
5225 dependent they should probably be combined into a single archive, per‐
5226 haps by using Object Libraries.
5227 Creating Relocatable Packages
5229 Note that it is not advisable to populate the INTERFACE_LINK_LIBRARIES
5230 of a target with absolute paths to dependencies. That would hard-code
5231 into installed packages the library file paths for dependencies as
5232 found on the machine the package was made on.
5233 See the Creating Relocatable Packages section of the cmake-packages(7)
5235 manual for discussion of additional care that must be taken when speci‐
5236 fying usage requirements while creating packages for redistribution.
5237 target_sources
5239 Add sources to a target.
5240 target_sources(<target>
5242 <INTERFACE|PUBLIC|PRIVATE> [items1...]
5243 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
5244 Specify sources to use when compiling a given target. The named <tar‐
5246 get> must have been created by a command such as add_executable() or
5247 add_library() and must not be an ALIAS target.
5248 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
5250 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
5251 late the SOURCES property of <target>. PUBLIC and INTERFACE items will
5252 populate the INTERFACE_SOURCES property of <target>. (IMPORTED targets
5253 only support INTERFACE items.) The following arguments specify
5254 sources. Repeated calls for the same <target> append items in the
5255 order called.
5256 Arguments to target_sources may use “generator expressions” with the
5258 syntax $<...>. See the cmake-generator-expressions(7) manual for avail‐
5259 able expressions. See the cmake-buildsystem(7) manual for more on
5260 defining buildsystem properties.
5261 try_compile
5263 Try building some code.
5264 Try Compiling Whole Projects
5266 try_compile(RESULT_VAR <bindir> <srcdir>
5267 <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
5268 [OUTPUT_VARIABLE <var>])
5269 Try building a project. The success or failure of the try_compile,
5271 i.e. TRUE or FALSE respectively, is returned in RESULT_VAR.
5272 In this form, <srcdir> should contain a complete CMake project with a
5274 CMakeLists.txt file and all sources. The <bindir> and <srcdir> will
5275 not be deleted after this command is run. Specify <targetName> to
5276 build a specific target instead of the all or ALL_BUILD target. See
5277 below for the meaning of other options.
5278 Try Compiling Source Files
5280 try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...>
5281 [CMAKE_FLAGS <flags>...]
5282 [COMPILE_DEFINITIONS <defs>...]
5283 [LINK_LIBRARIES <libs>...]
5284 [OUTPUT_VARIABLE <var>]
5285 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
5286 [<LANG>_STANDARD <std>]
5287 [<LANG>_STANDARD_REQUIRED <bool>]
5288 [<LANG>_EXTENSIONS <bool>]
5289 )
5290 Try building an executable from one or more source files. The success
5292 or failure of the try_compile, i.e. TRUE or FALSE respectively, is
5293 returned in RESULT_VAR.
5294 In this form the user need only supply one or more source files that
5296 include a definition for main. CMake will create a CMakeLists.txt file
5297 to build the source(s) as an executable that looks something like this:
5298 add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
5300 include_directories(${INCLUDE_DIRECTORIES})
5301 link_directories(${LINK_DIRECTORIES})
5302 add_executable(cmTryCompileExec <srcfile>...)
5303 target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
5304 The options are:
5306 CMAKE_FLAGS <flags>...
5308 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
5309 cmake command-line used to drive the test build. The above
5310 example shows how values for variables INCLUDE_DIRECTORIES,
5311 LINK_DIRECTORIES, and LINK_LIBRARIES are used.
5312 COMPILE_DEFINITIONS <defs>...
5314 Specify -Ddefinition arguments to pass to add_definitions in the
5315 generated test project.
5316 COPY_FILE <fileName>
5318 Copy the linked executable to the given <fileName>.
5319 COPY_FILE_ERROR <var>
5321 Use after COPY_FILE to capture into variable <var> any error
5322 message encountered while trying to copy the file.
5323 LINK_LIBRARIES <libs>...
5325 Specify libraries to be linked in the generated project. The
5326 list of libraries may refer to system libraries and to Imported
5327 Targets from the calling project.
5328 If this option is specified, any -DLINK_LIBRARIES=... value
5330 given to the CMAKE_FLAGS option will be ignored.
5331 OUTPUT_VARIABLE <var>
5333 Store the output from the build process the given variable.
5334 <LANG>_STANDARD <std>
5336 Specify the C_STANDARD, CXX_STANDARD, or CUDA_STANDARD target
5337 property of the generated project.
5338 <LANG>_STANDARD_REQUIRED <bool>
5340 Specify the C_STANDARD_REQUIRED, CXX_STANDARD_REQUIRED, or
5341 CUDA_STANDARD_REQUIRED target property of the generated project.
5342 <LANG>_EXTENSIONS <bool>
5344 Specify the C_EXTENSIONS, CXX_EXTENSIONS, or CUDA_EXTENSIONS
5345 target property of the generated project.
5346 In this version all files in <bindir>/CMakeFiles/CMakeTmp will be
5348 cleaned automatically. For debugging, --debug-trycompile can be passed
5349 to cmake to avoid this clean. However, multiple sequential try_compile
5350 operations reuse this single output directory. If you use
5351 --debug-trycompile, you can only debug one try_compile call at a time.
5352 The recommended procedure is to protect all try_compile calls in your
5353 project by if(NOT DEFINED RESULT_VAR) logic, configure with cmake all
5354 the way through once, then delete the cache entry associated with the
5355 try_compile call of interest, and then re-run cmake again with
5356 --debug-trycompile.
5357 Other Behavior Settings
5359 If set, the following variables are passed in to the generated try_com‐
5360 pile CMakeLists.txt to initialize compile target properties with
5361 default values:
5362 · CMAKE_ENABLE_EXPORTS
5364 · CMAKE_LINK_SEARCH_START_STATIC
5366 · CMAKE_LINK_SEARCH_END_STATIC
5368 · CMAKE_POSITION_INDEPENDENT_CODE
5370 If CMP0056 is set to NEW, then CMAKE_EXE_LINKER_FLAGS is passed in as
5372 well.
5373 The current setting of CMP0065 is set in the generated project.
5375 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
5377 figuration.
5378 Set the CMAKE_TRY_COMPILE_TARGET_TYPE variable to specify the type of
5380 target used for the source file signature.
5381 Set the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable to specify vari‐
5383 ables that must be propagated into the test project. This variable is
5384 meant for use only in toolchain files.
5385 If CMP0067 is set to NEW, or any of the <LANG>_STANDARD, <LANG>_STAN‐
5387 DARD_REQUIRED, or <LANG>_EXTENSIONS options are used, then the language
5388 standard variables are honored:
5389 · CMAKE_C_STANDARD
5391 · CMAKE_C_STANDARD_REQUIRED
5393 · CMAKE_C_EXTENSIONS
5395 · CMAKE_CXX_STANDARD
5397 · CMAKE_CXX_STANDARD_REQUIRED
5399 · CMAKE_CXX_EXTENSIONS
5401 · CMAKE_CUDA_STANDARD
5403 · CMAKE_CUDA_STANDARD_REQUIRED
5405 · CMAKE_CUDA_EXTENSIONS
5407 Their values are used to set the corresponding target properties in the
5409 generated project (unless overridden by an explicit option).
5410 try_run
5412 Try compiling and then running some code.
5413 Try Compiling and Running Source Files
5415 try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR
5416 bindir srcfile [CMAKE_FLAGS <flags>...]
5417 [COMPILE_DEFINITIONS <defs>...]
5418 [LINK_LIBRARIES <libs>...]
5419 [COMPILE_OUTPUT_VARIABLE <var>]
5420 [RUN_OUTPUT_VARIABLE <var>]
5421 [OUTPUT_VARIABLE <var>]
5422 [ARGS <args>...])
5423 Try compiling a <srcfile>. Returns TRUE or FALSE for success or fail‐
5425 ure in COMPILE_RESULT_VAR. If the compile succeeded, runs the exe‐
5426 cutable and returns its exit code in RUN_RESULT_VAR. If the executable
5427 was built, but failed to run, then RUN_RESULT_VAR will be set to
5428 FAILED_TO_RUN. See the try_compile() command for information on how
5429 the test project is constructed to build the source file.
5430 The options are:
5432 CMAKE_FLAGS <flags>...
5434 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
5435 cmake command-line used to drive the test build. The example in
5436 try_compile() shows how values for variables INCLUDE_DIRECTO‐
5437 RIES, LINK_DIRECTORIES, and LINK_LIBRARIES are used.
5438 COMPILE_DEFINITIONS <defs>...
5440 Specify -Ddefinition arguments to pass to add_definitions in the
5441 generated test project.
5442 COMPILE_OUTPUT_VARIABLE <var>
5444 Report the compile step build output in a given variable.
5445 LINK_LIBRARIES <libs>...
5447 Specify libraries to be linked in the generated project. The
5448 list of libraries may refer to system libraries and to Imported
5449 Targets from the calling project.
5450 If this option is specified, any -DLINK_LIBRARIES=... value
5452 given to the CMAKE_FLAGS option will be ignored.
5453 OUTPUT_VARIABLE <var>
5455 Report the compile build output and the output from running the
5456 executable in the given variable. This option exists for legacy
5457 reasons. Prefer COMPILE_OUTPUT_VARIABLE and RUN_OUTPUT_VARIABLE
5458 instead.
5459 RUN_OUTPUT_VARIABLE <var>
5461 Report the output from running the executable in a given vari‐
5462 able.
5463 Other Behavior Settings
5465 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
5466 figuration.
5467 Behavior when Cross Compiling
5469 When cross compiling, the executable compiled in the first step usually
5470 cannot be run on the build host. The try_run command checks the
5471 CMAKE_CROSSCOMPILING variable to detect whether CMake is in cross-com‐
5472 piling mode. If that is the case, it will still try to compile the
5473 executable, but it will not try to run the executable unless the
5474 CMAKE_CROSSCOMPILING_EMULATOR variable is set. Instead it will create
5475 cache variables which must be filled by the user or by presetting them
5476 in some CMake script file to the values the executable would have pro‐
5477 duced if it had been run on its actual target platform. These cache
5478 entries are:
5479 <RUN_RESULT_VAR>
5481 Exit code if the executable were to be run on the target plat‐
5482 form.
5483 <RUN_RESULT_VAR>__TRYRUN_OUTPUT
5485 Output from stdout and stderr if the executable were to be run
5486 on the target platform. This is created only if the RUN_OUT‐
5487 PUT_VARIABLE or OUTPUT_VARIABLE option was used.
5488 In order to make cross compiling your project easier, use try_run only
5490 if really required. If you use try_run, use the RUN_OUTPUT_VARIABLE or
5491 OUTPUT_VARIABLE options only if really required. Using them will
5492 require that when cross-compiling, the cache variables will have to be
5493 set manually to the output of the executable. You can also “guard” the
5494 calls to try_run with an if() block checking the CMAKE_CROSSCOMPILING
5495 variable and provide an easy-to-preset alternative for this case.
5496
5498 These commands are available only in CTest scripts.
5499 ctest_build
5501 Perform the CTest Build Step as a Dashboard Client.
5502 ctest_build([BUILD <build-dir>] [APPEND]
5504 [CONFIGURATION <config>]
5505 [FLAGS <flags>]
5506 [PROJECT_NAME <project-name>]
5507 [TARGET <target-name>]
5508 [NUMBER_ERRORS <num-err-var>]
5509 [NUMBER_WARNINGS <num-warn-var>]
5510 [RETURN_VALUE <result-var>]
5511 [CAPTURE_CMAKE_ERROR <result-var>]
5512 )
5513 Build the project and store results in Build.xml for submission with
5515 the ctest_submit() command.
5516 The CTEST_BUILD_COMMAND variable may be set to explicitly specify the
5518 build command line. Otherwise the build command line is computed auto‐
5519 matically based on the options given.
5520 The options are:
5522 BUILD <build-dir>
5524 Specify the top-level build directory. If not given, the
5525 CTEST_BINARY_DIRECTORY variable is used.
5526 APPEND Mark Build.xml for append to results previously submitted to a
5528 dashboard server since the last ctest_start() call. Append
5529 semantics are defined by the dashboard server in use. This does
5530 not cause results to be appended to a .xml file produced by a
5531 previous call to this command.
5532 CONFIGURATION <config>
5534 Specify the build configuration (e.g. Debug). If not specified
5535 the CTEST_BUILD_CONFIGURATION variable will be checked. Other‐
5536 wise the -C <cfg> option given to the ctest(1) command will be
5537 used, if any.
5538 FLAGS <flags>
5540 Pass additional arguments to the underlying build command. If
5541 not specified the CTEST_BUILD_FLAGS variable will be checked.
5542 This can, e.g., be used to trigger a parallel build using the -j
5543 option of make. See the ProcessorCount module for an example.
5544 PROJECT_NAME <project-name>
5546 Set the name of the project to build. This should correspond to
5547 the top-level call to the project() command. If not specified
5548 the CTEST_PROJECT_NAME variable will be checked.
5549 TARGET <target-name>
5551 Specify the name of a target to build. If not specified the
5552 CTEST_BUILD_TARGET variable will be checked. Otherwise the
5553 default target will be built. This is the “all” target (called
5554 ALL_BUILD in Visual Studio Generators).
5555 NUMBER_ERRORS <num-err-var>
5557 Store the number of build errors detected in the given variable.
5558 NUMBER_WARNINGS <num-warn-var>
5560 Store the number of build warnings detected in the given vari‐
5561 able.
5562 RETURN_VALUE <result-var>
5564 Store the return value of the native build tool in the given
5565 variable.
5566 CAPTURE_CMAKE_ERROR <result-var>
5568 Store in the <result-var> variable -1 if there are any errors
5569 running the command and prevent ctest from returning non-zero if
5570 an error occurs.
5571 QUIET Suppress any CTest-specific non-error output that would have
5573 been printed to the console otherwise. The summary of warnings
5574 / errors, as well as the output from the native build tool is
5575 unaffected by this option.
5576 ctest_configure
5578 Perform the CTest Configure Step as a Dashboard Client.
5579 ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
5581 [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
5582 [CAPTURE_CMAKE_ERROR <result-var>])
5583 Configure the project build tree and record results in Configure.xml
5585 for submission with the ctest_submit() command.
5586 The options are:
5588 BUILD <build-dir>
5590 Specify the top-level build directory. If not given, the
5591 CTEST_BINARY_DIRECTORY variable is used.
5592 SOURCE <source-dir>
5594 Specify the source directory. If not given, the
5595 CTEST_SOURCE_DIRECTORY variable is used.
5596 APPEND Mark Configure.xml for append to results previously submitted to
5598 a dashboard server since the last ctest_start() call. Append
5599 semantics are defined by the dashboard server in use. This does
5600 not cause results to be appended to a .xml file produced by a
5601 previous call to this command.
5602 OPTIONS <options>
5604 Specify command-line arguments to pass to the configuration
5605 tool.
5606 RETURN_VALUE <result-var>
5608 Store in the <result-var> variable the return value of the
5609 native configuration tool.
5610 CAPTURE_CMAKE_ERROR <result-var>
5612 Store in the <result-var> variable -1 if there are any errors
5613 running the command and prevent ctest from returning non-zero if
5614 an error occurs.
5615 QUIET Suppress any CTest-specific non-error messages that would have
5617 otherwise been printed to the console. Output from the underly‐
5618 ing configure command is not affected.
5619 ctest_coverage
5621 Perform the CTest Coverage Step as a Dashboard Client.
5622 ctest_coverage([BUILD <build-dir>] [APPEND]
5624 [LABELS <label>...]
5625 [RETURN_VALUE <result-var>]
5626 [CAPTURE_CMAKE_ERROR <result-var]
5627 [QUIET]
5628 )
5629 Collect coverage tool results and stores them in Coverage.xml for sub‐
5631 mission with the ctest_submit() command.
5632 The options are:
5634 BUILD <build-dir>
5636 Specify the top-level build directory. If not given, the
5637 CTEST_BINARY_DIRECTORY variable is used.
5638 APPEND Mark Coverage.xml for append to results previously submitted to
5640 a dashboard server since the last ctest_start() call. Append
5641 semantics are defined by the dashboard server in use. This does
5642 not cause results to be appended to a .xml file produced by a
5643 previous call to this command.
5644 LABELS Filter the coverage report to include only source files labeled
5646 with at least one of the labels specified.
5647 RETURN_VALUE <result-var>
5649 Store in the <result-var> variable 0 if coverage tools ran with‐
5650 out error and non-zero otherwise.
5651 CAPTURE_CMAKE_ERROR <result-var>
5653 Store in the <result-var> variable -1 if there are any errors
5654 running the command and prevent ctest from returning non-zero if
5655 an error occurs.
5656 QUIET Suppress any CTest-specific non-error output that would have
5658 been printed to the console otherwise. The summary indicating
5659 how many lines of code were covered is unaffected by this
5660 option.
5661 ctest_empty_binary_directory
5663 empties the binary directory
5664 ctest_empty_binary_directory( directory )
5666 Removes a binary directory. This command will perform some checks
5668 prior to deleting the directory in an attempt to avoid malicious or
5669 accidental directory deletion.
5670 ctest_memcheck
5672 Perform the CTest MemCheck Step as a Dashboard Client.
5673 ctest_memcheck([BUILD <build-dir>] [APPEND]
5675 [START <start-number>]
5676 [END <end-number>]
5677 [STRIDE <stride-number>]
5678 [EXCLUDE <exclude-regex>]
5679 [INCLUDE <include-regex>]
5680 [EXCLUDE_LABEL <label-exclude-regex>]
5681 [INCLUDE_LABEL <label-include-regex>]
5682 [EXCLUDE_FIXTURE <regex>]
5683 [EXCLUDE_FIXTURE_SETUP <regex>]
5684 [EXCLUDE_FIXTURE_CLEANUP <regex>]
5685 [PARALLEL_LEVEL <level>]
5686 [TEST_LOAD <threshold>]
5687 [SCHEDULE_RANDOM <ON|OFF>]
5688 [STOP_TIME <time-of-day>]
5689 [RETURN_VALUE <result-var>]
5690 [DEFECT_COUNT <defect-count-var>]
5691 [QUIET]
5692 )
5693 Run tests with a dynamic analysis tool and store results in Mem‐
5695 Check.xml for submission with the ctest_submit() command.
5696 Most options are the same as those for the ctest_test() command.
5698 The options unique to this command are:
5700 DEFECT_COUNT <defect-count-var>
5702 Store in the <defect-count-var> the number of defects found.
5703 ctest_read_custom_files
5705 read CTestCustom files.
5706 ctest_read_custom_files( directory ... )
5708 Read all the CTestCustom.ctest or CTestCustom.cmake files from the
5710 given directory.
5711 By default, invoking ctest(1) without a script will read custom files
5713 from the binary directory.
5714 ctest_run_script
5716 runs a ctest -S script
5717 ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
5719 script_file_name2 ... [RETURN_VALUE var])
5720 Runs a script or scripts much like if it was run from ctest -S. If no
5722 argument is provided then the current script is run using the current
5723 settings of the variables. If NEW_PROCESS is specified then each
5724 script will be run in a separate process.If RETURN_VALUE is specified
5725 the return value of the last script run will be put into var.
5726 ctest_sleep
5728 sleeps for some amount of time
5729 ctest_sleep(<seconds>)
5731 Sleep for given number of seconds.
5733 ctest_sleep(<time1> <duration> <time2>)
5735 Sleep for t=(time1 + duration - time2) seconds if t > 0.
5737 ctest_start
5739 Starts the testing for a given model
5740 ctest_start(Model [TRACK <track>] [APPEND] [source [binary]] [QUIET])
5742 Starts the testing for a given model. The command should be called
5744 after the binary directory is initialized. If the ‘source’ and
5745 ‘binary’ directory are not specified, it reads the CTEST_SOURCE_DIREC‐
5746 TORY and CTEST_BINARY_DIRECTORY. If the track is specified, the sub‐
5747 missions will go to the specified track. If APPEND is used, the exist‐
5748 ing TAG is used rather than creating a new one based on the current
5749 time stamp. If QUIET is used, CTest will suppress any non-error mes‐
5750 sages that it otherwise would have printed to the console.
5751 If the CTEST_CHECKOUT_COMMAND variable (or the CTEST_CVS_CHECKOUT vari‐
5753 able) is set, its content is treated as command-line. The command is
5754 invoked with the current working directory set to the parent of the
5755 source directory, even if the source directory already exists. This
5756 can be used to create the source tree from a version control reposi‐
5757 tory.
5758 ctest_submit
5760 Perform the CTest Submit Step as a Dashboard Client.
5761 ctest_submit([PARTS <part>...] [FILES <file>...]
5763 [HTTPHEADER <header>]
5764 [RETRY_COUNT <count>]
5765 [RETRY_DELAY <delay>]
5766 [RETURN_VALUE <result-var>]
5767 [QUIET]
5768 )
5769 Submit results to a dashboard server. By default all available parts
5771 are submitted.
5772 The options are:
5774 PARTS <part>...
5776 Specify a subset of parts to submit. Valid part names are:
5777 Start = nothing
5779 Update = ctest_update results, in Update.xml
5780 Configure = ctest_configure results, in Configure.xml
5781 Build = ctest_build results, in Build.xml
5782 Test = ctest_test results, in Test.xml
5783 Coverage = ctest_coverage results, in Coverage.xml
5784 MemCheck = ctest_memcheck results, in DynamicAnalysis.xml
5785 Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
5786 ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
5787 Upload = Files prepared for upload by ctest_upload(), in Upload.xml
5788 Submit = nothing
5789 FILES <file>...
5791 Specify an explicit list of specific files to be submitted.
5792 Each individual file must exist at the time of the call.
5793 HTTPHEADER <HTTP-header>
5795 Specify HTTP header to be included in the request to CDash dur‐
5796 ing submission. This suboption can be repeated several times.
5797 RETRY_COUNT <count>
5799 Specify how many times to retry a timed-out submission.
5800 RETRY_DELAY <delay>
5802 Specify how long (in seconds) to wait after a timed-out submis‐
5803 sion before attempting to re-submit.
5804 RETURN_VALUE <result-var>
5806 Store in the <result-var> variable 0 for success and non-zero on
5807 failure.
5808 QUIET Suppress all non-error messages that would have otherwise been
5810 printed to the console.
5811 Submit to CDash Upload API
5813 ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
5814 [HTTPHEADER <header>]
5815 [RETRY_COUNT <count>]
5816 [RETRY_DELAY <delay>]
5817 [QUIET])
5818 This second signature is used to upload files to CDash via the CDash
5820 file upload API. The api first sends a request to upload to CDash along
5821 with a content hash of the file. If CDash does not already have the
5822 file, then it is uploaded. Along with the file, a CDash type string is
5823 specified to tell CDash which handler to use to process the data.
5824 This signature accepts the HTTPHEADER, RETRY_COUNT, RETRY_DELAY, and
5826 QUIET options as described above.
5827 ctest_test
5829 Perform the CTest Test Step as a Dashboard Client.
5830 ctest_test([BUILD <build-dir>] [APPEND]
5832 [START <start-number>]
5833 [END <end-number>]
5834 [STRIDE <stride-number>]
5835 [EXCLUDE <exclude-regex>]
5836 [INCLUDE <include-regex>]
5837 [EXCLUDE_LABEL <label-exclude-regex>]
5838 [INCLUDE_LABEL <label-include-regex>]
5839 [EXCLUDE_FIXTURE <regex>]
5840 [EXCLUDE_FIXTURE_SETUP <regex>]
5841 [EXCLUDE_FIXTURE_CLEANUP <regex>]
5842 [PARALLEL_LEVEL <level>]
5843 [TEST_LOAD <threshold>]
5844 [SCHEDULE_RANDOM <ON|OFF>]
5845 [STOP_TIME <time-of-day>]
5846 [RETURN_VALUE <result-var>]
5847 [CAPTURE_CMAKE_ERROR <result-var>]
5848 [QUIET]
5849 )
5850 Run tests in the project build tree and store results in Test.xml for
5852 submission with the ctest_submit() command.
5853 The options are:
5855 BUILD <build-dir>
5857 Specify the top-level build directory. If not given, the
5858 CTEST_BINARY_DIRECTORY variable is used.
5859 APPEND Mark Test.xml for append to results previously submitted to a
5861 dashboard server since the last ctest_start() call. Append
5862 semantics are defined by the dashboard server in use. This does
5863 not cause results to be appended to a .xml file produced by a
5864 previous call to this command.
5865 START <start-number>
5867 Specify the beginning of a range of test numbers.
5868 END <end-number>
5870 Specify the end of a range of test numbers.
5871 STRIDE <stride-number>
5873 Specify the stride by which to step across a range of test num‐
5874 bers.
5875 EXCLUDE <exclude-regex>
5877 Specify a regular expression matching test names to exclude.
5878 INCLUDE <include-regex>
5880 Specify a regular expression matching test names to include.
5881 Tests not matching this expression are excluded.
5882 EXCLUDE_LABEL <label-exclude-regex>
5884 Specify a regular expression matching test labels to exclude.
5885 INCLUDE_LABEL <label-include-regex>
5887 Specify a regular expression matching test labels to include.
5888 Tests not matching this expression are excluded.
5889 EXCLUDE_FIXTURE <regex>
5891 If a test in the set of tests to be executed requires a particu‐
5892 lar fixture, that fixture’s setup and cleanup tests would nor‐
5893 mally be added to the test set automatically. This option pre‐
5894 vents adding setup or cleanup tests for fixtures matching the
5895 <regex>. Note that all other fixture behavior is retained,
5896 including test dependencies and skipping tests that have fixture
5897 setup tests that fail.
5898 EXCLUDE_FIXTURE_SETUP <regex>
5900 Same as EXCLUDE_FIXTURE except only matching setup tests are
5901 excluded.
5902 EXCLUDE_FIXTURE_CLEANUP <regex>
5904 Same as EXCLUDE_FIXTURE except only matching cleanup tests are
5905 excluded.
5906 PARALLEL_LEVEL <level>
5908 Specify a positive number representing the number of tests to be
5909 run in parallel.
5910 TEST_LOAD <threshold>
5912 While running tests in parallel, try not to start tests when
5913 they may cause the CPU load to pass above a given threshold. If
5914 not specified the CTEST_TEST_LOAD variable will be checked, and
5915 then the --test-load command-line argument to ctest(1). See
5916 also the TestLoad setting in the CTest Test Step.
5917 SCHEDULE_RANDOM <ON|OFF>
5919 Launch tests in a random order. This may be useful for detect‐
5920 ing implicit test dependencies.
5921 STOP_TIME <time-of-day>
5923 Specify a time of day at which the tests should all stop run‐
5924 ning.
5925 RETURN_VALUE <result-var>
5927 Store in the <result-var> variable 0 if all tests passed. Store
5928 non-zero if anything went wrong.
5929 CAPTURE_CMAKE_ERROR <result-var>
5931 Store in the <result-var> variable -1 if there are any errors
5932 running the command and prevent ctest from returning non-zero if
5933 an error occurs.
5934 QUIET Suppress any CTest-specific non-error messages that would have
5936 otherwise been printed to the console. Output from the underly‐
5937 ing test command is not affected. Summary info detailing the
5938 percentage of passing tests is also unaffected by the QUIET
5939 option.
5940 See also the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE and
5942 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables.
5943 ctest_update
5945 Perform the CTest Update Step as a Dashboard Client.
5946 ctest_update([SOURCE <source-dir>] [RETURN_VALUE <result-var>] [QUIET])
5948 Update the source tree from version control and record results in
5950 Update.xml for submission with the ctest_submit() command.
5951 The options are:
5953 SOURCE <source-dir>
5955 Specify the source directory. If not given, the
5956 CTEST_SOURCE_DIRECTORY variable is used.
5957 RETURN_VALUE <result-var>
5959 Store in the <result-var> variable the number of files updated
5960 or -1 on error.
5961 QUIET Tell CTest to suppress most non-error messages that it would
5963 have otherwise printed to the console. CTest will still report
5964 the new revision of the repository and any conflicting files
5965 that were found.
5966 The update always follows the version control branch currently checked
5968 out in the source directory. See the CTest Update Step documentation
5969 for more information.
5970 ctest_upload
5972 Upload files to a dashboard server as a Dashboard Client.
5973 ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
5975 The options are:
5977 FILES <file>...
5979 Specify a list of files to be sent along with the build results
5980 to the dashboard server.
5981 QUIET Suppress any CTest-specific non-error output that would have
5983 been printed to the console otherwise.
5984 CAPTURE_CMAKE_ERROR <result-var>
5986 Store in the <result-var> variable -1 if there are any errors
5987 running the command and prevent ctest from returning non-zero if
5988 an error occurs.
5989
5991 These commands are available only for compatibility with older versions
5992 of CMake. Do not use them in new code.
5993 build_name
5995 Disallowed. See CMake Policy CMP0036.
5996 Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.
5998 build_name(variable)
6000 Sets the specified variable to a string representing the platform and
6002 compiler settings. These values are now available through the
6003 CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
6004 exec_program
6006 Deprecated. Use the execute_process() command instead.
6007 Run an executable program during the processing of the CMakeList.txt
6009 file.
6010 exec_program(Executable [directory in which to run]
6012 [ARGS <arguments to executable>]
6013 [OUTPUT_VARIABLE <var>]
6014 [RETURN_VALUE <var>])
6015 The executable is run in the optionally specified directory. The exe‐
6017 cutable can include arguments if it is double quoted, but it is better
6018 to use the optional ARGS argument to specify arguments to the program.
6019 This is because cmake will then be able to escape spaces in the exe‐
6020 cutable path. An optional argument OUTPUT_VARIABLE specifies a vari‐
6021 able in which to store the output. To capture the return value of the
6022 execution, provide a RETURN_VALUE. If OUTPUT_VARIABLE is specified,
6023 then no output will go to the stdout/stderr of the console running
6024 cmake.
6025 export_library_dependencies
6027 Disallowed. See CMake Policy CMP0033.
6028 Use install(EXPORT) or export() command.
6030 This command generates an old-style library dependencies file.
6032 Projects requiring CMake 2.6 or later should not use the command. Use
6033 instead the install(EXPORT) command to help export targets from an
6034 installation tree and the export() command to export targets from a
6035 build tree.
6036 The old-style library dependencies file does not take into account
6038 per-configuration names of libraries or the LINK_INTERFACE_LIBRARIES
6039 target property.
6040 export_library_dependencies(<file> [APPEND])
6042 Create a file named <file> that can be included into a CMake listfile
6044 with the INCLUDE command. The file will contain a number of SET com‐
6045 mands that will set all the variables needed for library dependency
6046 information. This should be the last command in the top level CMake‐
6047 Lists.txt file of the project. If the APPEND option is specified, the
6048 SET commands will be appended to the given file instead of replacing
6049 it.
6050 install_files
6052 Deprecated. Use the install(FILES) command instead.
6053 This command has been superceded by the install() command. It is pro‐
6055 vided for compatibility with older CMake code. The FILES form is
6056 directly replaced by the FILES form of the install() command. The reg‐
6057 exp form can be expressed more clearly using the GLOB form of the
6058 file() command.
6059 install_files(<dir> extension file file ...)
6061 Create rules to install the listed files with the given extension into
6063 the given directory. Only files existing in the current source tree or
6064 its corresponding location in the binary tree may be listed. If a file
6065 specified already has an extension, that extension will be removed
6066 first. This is useful for providing lists of source files such as
6067 foo.cxx when you want the corresponding foo.h to be installed. A typi‐
6068 cal extension is ‘.h’.
6069 install_files(<dir> regexp)
6071 Any files in the current source directory that match the regular
6073 expression will be installed.
6074 install_files(<dir> FILES file file ...)
6076 Any files listed after the FILES keyword will be installed explicitly
6078 from the names given. Full paths are allowed in this form.
6079 The directory <dir> is relative to the installation prefix, which is
6081 stored in the variable CMAKE_INSTALL_PREFIX.
6082 install_programs
6084 Deprecated. Use the install(PROGRAMS) command instead.
6085 This command has been superceded by the install() command. It is pro‐
6087 vided for compatibility with older CMake code. The FILES form is
6088 directly replaced by the PROGRAMS form of the install() command. The
6089 regexp form can be expressed more clearly using the GLOB form of the
6090 file() command.
6091 install_programs(<dir> file1 file2 [file3 ...])
6093 install_programs(<dir> FILES file1 [file2 ...])
6094 Create rules to install the listed programs into the given directory.
6096 Use the FILES argument to guarantee that the file list version of the
6097 command will be used even when there is only one argument.
6098 install_programs(<dir> regexp)
6100 In the second form any program in the current source directory that
6102 matches the regular expression will be installed.
6103 This command is intended to install programs that are not built by
6105 cmake, such as shell scripts. See the TARGETS form of the install()
6106 command to create installation rules for targets built by cmake.
6107 The directory <dir> is relative to the installation prefix, which is
6109 stored in the variable CMAKE_INSTALL_PREFIX.
6110 install_targets
6112 Deprecated. Use the install(TARGETS) command instead.
6113 This command has been superceded by the install() command. It is pro‐
6115 vided for compatibility with older CMake code.
6116 install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
6118 Create rules to install the listed targets into the given directory.
6120 The directory <dir> is relative to the installation prefix, which is
6121 stored in the variable CMAKE_INSTALL_PREFIX. If RUNTIME_DIRECTORY is
6122 specified, then on systems with special runtime files (Windows DLL),
6123 the files will be copied to that directory.
6124 load_command
6126 Disallowed. See CMake Policy CMP0031.
6127 Load a command into a running CMake.
6129 load_command(COMMAND_NAME <loc1> [loc2 ...])
6131 The given locations are searched for a library whose name is cmCOM‐
6133 MAND_NAME. If found, it is loaded as a module and the command is added
6134 to the set of available CMake commands. Usually, try_compile() is used
6135 before this command to compile the module. If the command is success‐
6136 fully loaded a variable named
6137 CMAKE_LOADED_COMMAND_<COMMAND_NAME>
6139 will be set to the full path of the module that was loaded. Otherwise
6141 the variable will not be set.
6142 make_directory
6144 Deprecated. Use the file(MAKE_DIRECTORY) command instead.
6145 make_directory(directory)
6147 Creates the specified directory. Full paths should be given. Any par‐
6149 ent directories that do not exist will also be created. Use with care.
6150 output_required_files
6152 Disallowed. See CMake Policy CMP0032.
6153 Approximate C preprocessor dependency scanning.
6155 This command exists only because ancient CMake versions provided it.
6157 CMake handles preprocessor dependency scanning automatically using a
6158 more advanced scanner.
6159 output_required_files(srcfile outputfile)
6161 Outputs a list of all the source files that are required by the speci‐
6163 fied srcfile. This list is written into outputfile. This is similar
6164 to writing out the dependencies for srcfile except that it jumps from
6165 .h files into .cxx, .c and .cpp files if possible.
6166 remove
6168 Deprecated. Use the list(REMOVE_ITEM) command instead.
6169 remove(VAR VALUE VALUE ...)
6171 Removes VALUE from the variable VAR. This is typically used to remove
6173 entries from a vector (e.g. semicolon separated list). VALUE is
6174 expanded.
6175 subdir_depends
6177 Disallowed. See CMake Policy CMP0029.
6178 Does nothing.
6180 subdir_depends(subdir dep1 dep2 ...)
6182 Does not do anything. This command used to help projects order paral‐
6184 lel builds correctly. This functionality is now automatic.
6185 subdirs
6187 Deprecated. Use the add_subdirectory() command instead.
6188 Add a list of subdirectories to the build.
6190 subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
6192 [PREORDER] )
6193 Add a list of subdirectories to the build. The add_subdirectory() com‐
6195 mand should be used instead of subdirs although subdirs will still
6196 work. This will cause any CMakeLists.txt files in the sub directories
6197 to be processed by CMake. Any directories after the PREORDER flag are
6198 traversed first by makefile builds, the PREORDER flag has no effect on
6199 IDE projects. Any directories after the EXCLUDE_FROM_ALL marker will
6200 not be included in the top level makefile or project file. This is
6201 useful for having CMake create makefiles or projects for a set of exam‐
6202 ples in a project. You would want CMake to generate makefiles or
6203 project files for all the examples at the same time, but you would not
6204 want them to show up in the top level project or be built each time
6205 make is run from the top.
6206 use_mangled_mesa
6208 Disallowed. See CMake Policy CMP0030.
6209 Copy mesa headers for use in combination with system GL.
6211 use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
6213 The path to mesa includes, should contain gl_mangle.h. The mesa head‐
6215 ers are copied to the specified output directory. This allows mangled
6216 mesa headers to override other GL headers by being added to the include
6217 directory path earlier.
6218 utility_source
6220 Disallowed. See CMake Policy CMP0034.
6221 Specify the source tree of a third-party utility.
6223 utility_source(cache_entry executable_name
6225 path_to_source [file1 file2 ...])
6226 When a third-party utility’s source is included in the distribution,
6228 this command specifies its location and name. The cache entry will not
6229 be set unless the path_to_source and all listed files exist. It is
6230 assumed that the source tree of the utility will have been built before
6231 it is needed.
6232 When cross compiling CMake will print a warning if a utility_source()
6234 command is executed, because in many cases it is used to build an exe‐
6235 cutable which is executed later on. This doesn’t work when cross com‐
6236 piling, since the executable can run only on their target platform. So
6237 in this case the cache entry has to be adjusted manually so it points
6238 to an executable which is runnable on the build host.
6239 variable_requires
6241 Disallowed. See CMake Policy CMP0035.
6242 Use the if() command instead.
6244 Assert satisfaction of an option’s required variables.
6246 variable_requires(TEST_VARIABLE RESULT_VARIABLE
6248 REQUIRED_VARIABLE1
6249 REQUIRED_VARIABLE2 ...)
6250 The first argument (TEST_VARIABLE) is the name of the variable to be
6252 tested, if that variable is false nothing else is done. If TEST_VARI‐
6253 ABLE is true, then the next argument (RESULT_VARIABLE) is a variable
6254 that is set to true if all the required variables are set. The rest of
6255 the arguments are variables that must be true or not set to NOTFOUND to
6256 avoid an error. If any are not true, an error is reported.
6257 write_file
6259 Deprecated. Use the file(WRITE) command instead.
6260 write_file(filename "message to write"... [APPEND])
6262 The first argument is the file name, the rest of the arguments are mes‐
6264 sages to write. If the argument APPEND is specified, then the message
6265 will be appended.
6266 NOTE 1: file(WRITE) and file(APPEND) do exactly the same as this one
6268 but add some more functionality.
6269 NOTE 2: When using write_file the produced file cannot be used as an
6271 input to CMake (CONFIGURE_FILE, source file …) because it will lead to
6272 an infinite loop. Use configure_file() if you want to generate input
6273 files to CMake.
6274
6276 2000-2018 Kitware, Inc. and Contributors
62773.11.4 May 13, 2019 CMAKE-COMMANDS(7)