1ctest(1) General Commands Manual ctest(1)
2
3
4
6 ctest - Testing driver provided by CMake.
7
8
10 ctest [options]
11
12
14 The "ctest" executable is the CMake test driver program. CMake-gener‐
15 ated build trees created for projects that use the ENABLE_TESTING and
16 ADD_TEST commands have testing support. This program will run the
17 tests and report results.
18
19
21 -C <cfg>, --build-config <cfg>
22 Choose configuration to test.
23
24 Some CMake-generated build trees can have multiple build config‐
25 urations in the same tree. This option can be used to specify
26 which one should be tested. Example configurations are "Debug"
27 and "Release".
28
29
30 -V,--verbose
31 Enable verbose output from tests.
32
33 Test output is normally suppressed and only summary information
34 is displayed. This option will show all test output.
35
36
37 -VV,--extra-verbose
38 Enable more verbose output from tests.
39
40 Test output is normally suppressed and only summary information
41 is displayed. This option will show even more test output.
42
43
44 --debug
45 Displaying more verbose internals of CTest.
46
47 This feature will result in a large number of output that is
48 mostly useful for debugging dashboard problems.
49
50
51 --output-on-failure
52 Output anything outputted by the test program if the test should
53 fail. This option can also be enabled by setting the environ‐
54 ment variable CTEST_OUTPUT_ON_FAILURE
55
56
57 -F Enable failover.
58
59 This option allows ctest to resume a test set execution that was
60 previously interrupted. If no interruption occurred, the -F
61 option will have no effect.
62
63
64 -j <jobs>, --parallel <jobs>
65 Run the tests in parallel using thegiven number of jobs.
66
67 This option tells ctest to run the tests in parallel using given
68 number of jobs. This option can also be set by setting the
69 environment variable CTEST_PARALLEL_LEVEL.
70
71
72 -Q,--quiet
73 Make ctest quiet.
74
75 This option will suppress all the output. The output log file
76 will still be generated if the --output-log is specified.
77 Options such as --verbose, --extra-verbose, and --debug are
78 ignored if --quiet is specified.
79
80
81 -O <file>, --output-log <file>
82 Output to log file
83
84 This option tells ctest to write all its output to a log file.
85
86
87 -N,--show-only
88 Disable actual execution of tests.
89
90 This option tells ctest to list the tests that would be run but
91 not actually run them. Useful in conjunction with the -R and -E
92 options.
93
94
95 -L <regex>, --label-regex <regex>
96 Run tests with labels matching regular expression.
97
98 This option tells ctest to run only the tests whose labels match
99 the given regular expression.
100
101
102 -R <regex>, --tests-regex <regex>
103 Run tests matching regular expression.
104
105 This option tells ctest to run only the tests whose names match
106 the given regular expression.
107
108
109 -E <regex>, --exclude-regex <regex>
110 Exclude tests matching regular expression.
111
112 This option tells ctest to NOT run the tests whose names match
113 the given regular expression.
114
115
116 -LE <regex>, --label-exclude <regex>
117 Exclude tests with labels matching regular expression.
118
119 This option tells ctest to NOT run the tests whose labels match
120 the given regular expression.
121
122
123 -D <dashboard>, --dashboard <dashboard>
124 Execute dashboard test
125
126 This option tells ctest to act as a Dart client and perform a
127 dashboard test. All tests are <Mode><Test>, where Mode can be
128 Experimental, Nightly, and Continuous, and Test can be Start,
129 Update, Configure, Build, Test, Coverage, and Submit.
130
131
132 -D <var>:<type>=<value>
133 Define a variable for script mode
134
135 Pass in variable values on the command line. Use in conjunction
136 with -S to pass variable values to a dashboard script. Parsing
137 -D arguments as variable values is only attempted if the value
138 following -D does not match any of the known dashboard types.
139
140
141 -M <model>, --test-model <model>
142 Sets the model for a dashboard
143
144 This option tells ctest to act as a Dart client where the Test‐
145 Model can be Experimental, Nightly, and Continuous. Combining -M
146 and -T is similar to -D
147
148
149 -T <action>, --test-action <action>
150 Sets the dashboard action to perform
151
152 This option tells ctest to act as a Dart client and perform some
153 action such as start, build, test etc. Combining -M and -T is
154 similar to -D
155
156
157 --track <track>
158 Specify the track to submit dashboard to
159
160 Submit dashboard to specified track instead of default one. By
161 default, the dashboard is submitted to Nightly, Experimental, or
162 Continuous track, but by specifying this option, the track can
163 be arbitrary.
164
165
166 -S <script>, --script <script>
167 Execute a dashboard for a configuration
168
169 This option tells ctest to load in a configuration script which
170 sets a number of parameters such as the binary and source direc‐
171 tories. Then ctest will do what is required to create and run a
172 dashboard. This option basically sets up a dashboard and then
173 runs ctest -D with the appropriate options.
174
175
176 -SP <script>, --script-new-process <script>
177 Execute a dashboard for a configuration
178
179 This option does the same operations as -S but it will do them
180 in a separate process. This is primarily useful in cases where
181 the script may modify the environment and you do not want the
182 modified environment to impact other -S scripts.
183
184
185 -A <file>, --add-notes <file>
186 Add a notes file with submission
187
188 This option tells ctest to include a notes file when submitting
189 dashboard.
190
191
192 -I [Start,End,Stride,test#,test#|Test file], --tests-information
193 Run a specific number of tests by number.
194
195 This option causes ctest to run tests starting at number Start,
196 ending at number End, and incrementing by Stride. Any additional
197 numbers after Stride are considered individual test numbers.
198 Start, End,or stride can be empty. Optionally a file can be
199 given that contains the same syntax as the command line.
200
201
202 -U, --union
203 Take the Union of -I and -R
204
205 When both -R and -I are specified by default the intersection of
206 tests are run. By specifying -U the union of tests is run
207 instead.
208
209
210 --max-width <width>
211 Set the max width for a test name to output
212
213 Set the maximum width for each test name to show in the output.
214 This allows the user to widen the output to avoid clipping the
215 test name which can be very annoying.
216
217
218 --interactive-debug-mode [0|1]
219 Set the interactive mode to 0 or 1.
220
221 This option causes ctest to run tests in either an interactive
222 mode or a non-interactive mode. On Windows this means that in
223 non-interactive mode, all system debug pop up windows are
224 blocked. In dashboard mode (Experimental, Nightly, Continuous),
225 the default is non-interactive. When just running tests not for
226 a dashboard the default is to allow popups and interactive
227 debugging.
228
229
230 --no-label-summary
231 Disable timing summary information for labels.
232
233 This option tells ctest not to print summary information for
234 each label associated with the tests run. If there are no labels
235 on the tests, nothing extra is printed.
236
237
238 --build-and-test
239 Configure, build and run a test.
240
241 This option tells ctest to configure (i.e. run cmake on), build,
242 and or execute a test. The configure and test steps are
243 optional. The arguments to this command line are the source and
244 binary directories. By default this will run CMake on the
245 Source/Bin directories specified unless --build-nocmake is spec‐
246 ified. Both --build-makeprogram and --build-generator MUST be
247 provided to use --build-and-test. If --test-command is specified
248 then that will be run after the build is complete. Other options
249 that affect this mode are --build-target --build-nocmake,
250 --build-run-dir, --build-two-config, --build-exe-dir,
251 --build-project,--build-noclean, --build-options
252
253
254 --build-target
255 Specify a specific target to build.
256
257 This option goes with the --build-and-test option, if left out
258 the all target is built.
259
260
261 --build-nocmake
262 Run the build without running cmake first.
263
264 Skip the cmake step.
265
266
267 --build-run-dir
268 Specify directory to run programs from.
269
270 Directory where programs will be after it has been compiled.
271
272
273 --build-two-config
274 Run CMake twice
275
276
277 --build-exe-dir
278 Specify the directory for the executable.
279
280
281 --build-generator
282 Specify the generator to use.
283
284
285 --build-generator-toolset
286 Specify the generator-specific toolset.
287
288
289 --build-project
290 Specify the name of the project to build.
291
292
293 --build-makeprogram
294 Specify the make program to use.
295
296
297 --build-noclean
298 Skip the make clean step.
299
300
301 --build-config-sample
302 A sample executable to use to determine the configuration
303
304 A sample executable to use to determine the configuration that
305 should be used. e.g. Debug/Release/etc
306
307
308 --build-options
309 Add extra options to the build step.
310
311 This option must be the last option with the exception of
312 --test-command
313
314
315 --test-command
316 The test to run with the --build-and-test option.
317
318
319 --test-timeout
320 The time limit in seconds, internal use only.
321
322
323 --tomorrow-tag
324 Nightly or experimental starts with next day tag.
325
326 This is useful if the build will not finish in one day.
327
328
329 --ctest-config
330 The configuration file used to initialize CTest state when sub‐
331 mitting dashboards.
332
333 This option tells CTest to use different initialization file
334 instead of CTestConfiguration.tcl. This way multiple initializa‐
335 tion files can be used for example to submit to multiple dash‐
336 boards.
337
338
339 --overwrite
340 Overwrite CTest configuration option.
341
342 By default ctest uses configuration options from configuration
343 file. This option will overwrite the configuration option.
344
345
346 --extra-submit <file>[;<file>]
347 Submit extra files to the dashboard.
348
349 This option will submit extra files to the dashboard.
350
351
352 --force-new-ctest-process
353 Run child CTest instances as new processes
354
355 By default CTest will run child CTest instances within the same
356 process. If this behavior is not desired, this argument will
357 enforce new processes for child CTest processes.
358
359
360 --schedule-random
361 Use a random order for scheduling tests
362
363 This option will run the tests in a random order. It is commonly
364 used to detect implicit dependencies in a test suite.
365
366
367 --submit-index
368 Submit individual dashboard tests with specific index
369
370 This option allows performing the same CTest action (such as
371 test) multiple times and submit all stages to the same dashboard
372 (Dart2 required). Each execution requires different index.
373
374
375 --timeout <seconds>
376 Set a global timeout on all tests.
377
378 This option will set a global timeout on all tests that do not
379 already have a timeout set on them.
380
381
382 --stop-time <time>
383 Set a time at which all tests should stop running.
384
385 Set a real time of day at which all tests should timeout. Exam‐
386 ple: 7:00:00 -0400. Any time format understood by the curl date
387 parser is accepted. Local time is assumed if no timezone is
388 specified.
389
390
391 --http1.0
392 Submit using HTTP 1.0.
393
394 This option will force CTest to use HTTP 1.0 to submit files to
395 the dashboard, instead of HTTP 1.1.
396
397
398 --no-compress-output
399 Do not compress test output when submitting.
400
401 This flag will turn off automatic compression of test output.
402 Use this to maintain compatibility with an older version of
403 CDash which doesn't support compressed test output.
404
405
406 --print-labels
407 Print all available test labels.
408
409 This option will not run any tests, it will simply print the
410 list of all labels associated with the test set.
411
412
413 --help-command <cmd> [<file>]
414 Show help for a single command and exit.
415
416 Prints the help for the command to stdout or to the specified
417 file.
418
419
420 --help-command-list [<file>]
421 List available commands and exit.
422
423 Prints the list of all available listfile commands to stdout or
424 the specified file.
425
426
427 --help-commands [<file>]
428 Print help for all commands and exit.
429
430 Prints the help for all commands to stdout or to the specified
431 file.
432
433
434 --copyright [file]
435 Print the CMake copyright and exit.
436
437 If a file is specified, the copyright is written into it.
438
439
440 --help,-help,-usage,-h,-H,/?
441 Print usage information and exit.
442
443 Usage describes the basic command line interface and its
444 options.
445
446
447 --help-full [file]
448 Print full help and exit.
449
450 Full help displays most of the documentation provided by the
451 UNIX man page. It is provided for use on non-UNIX platforms,
452 but is also convenient if the man page is not installed. If a
453 file is specified, the help is written into it.
454
455
456 --help-html [file]
457 Print full help in HTML format.
458
459 This option is used by CMake authors to help produce web pages.
460 If a file is specified, the help is written into it.
461
462
463 --help-man [file]
464 Print full help as a UNIX man page and exit.
465
466 This option is used by the cmake build to generate the UNIX man
467 page. If a file is specified, the help is written into it.
468
469
470 --version,-version,/V [file]
471 Show program name/version banner and exit.
472
473 If a file is specified, the version is written into it.
474
475
477 The following generators are available on this platform:
478
479
481 break Break from an enclosing foreach or while loop.
482
483 break()
484
485 Breaks from an enclosing foreach loop or while loop
486
487
488 build_name
489 Deprecated. Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER}
490 instead.
491
492 build_name(variable)
493
494 Sets the specified variable to a string representing the plat‐
495 form and compiler settings. These values are now available
496 through the CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
497
498
499 cmake_host_system_information
500 Query host system specific information.
501
502 cmake_host_system_information(RESULT <variable> QUERY <key> ...)
503
504 Queries system information of the host system on which cmake
505 runs. One or more <key> can be provided to select the informa‐
506 tion to be queried. The list of queried values is stored in
507 <variable>.
508
509
510 <key> can be one of the following values:
511
512
513 NUMBER_OF_LOGICAL_CORES = Number of logical cores.
514 NUMBER_OF_PHYSICAL_CORES = Number of physical cores.
515 HOSTNAME = Hostname.
516 FQDN = Fully qualified domain name.
517 TOTAL_VIRTUAL_MEMORY = Total virtual memory in megabytes.
518 AVAILABLE_VIRTUAL_MEMORY = Available virtual memory in megabytes.
519 TOTAL_PHYSICAL_MEMORY = Total physical memory in megabytes.
520 AVAILABLE_PHYSICAL_MEMORY = Available physical memory in megabytes.
521
522
523 cmake_minimum_required
524 Set the minimum required version of cmake for a project.
525
526 cmake_minimum_required(VERSION major[.minor[.patch[.tweak]]]
527 [FATAL_ERROR])
528
529 If the current version of CMake is lower than that required it
530 will stop processing the project and report an error. When a
531 version higher than 2.4 is specified the command implicitly
532 invokes
533
534
535 cmake_policy(VERSION major[.minor[.patch[.tweak]]])
536
537 which sets the cmake policy version level to the version speci‐
538 fied. When version 2.4 or lower is given the command implicitly
539 invokes
540
541
542 cmake_policy(VERSION 2.4)
543
544 which enables compatibility features for CMake 2.4 and lower.
545
546
547 The FATAL_ERROR option is accepted but ignored by CMake 2.6 and
548 higher. It should be specified so CMake versions 2.4 and lower
549 fail with an error instead of just a warning.
550
551
552 cmake_policy
553 Manage CMake Policy settings.
554
555 As CMake evolves it is sometimes necessary to change existing
556 behavior in order to fix bugs or improve implementations of
557 existing features. The CMake Policy mechanism is designed to
558 help keep existing projects building as new versions of CMake
559 introduce changes in behavior. Each new policy (behavioral
560 change) is given an identifier of the form "CMP<NNNN>" where
561 "<NNNN>" is an integer index. Documentation associated with
562 each policy describes the OLD and NEW behavior and the reason
563 the policy was introduced. Projects may set each policy to
564 select the desired behavior. When CMake needs to know which
565 behavior to use it checks for a setting specified by the
566 project. If no setting is available the OLD behavior is assumed
567 and a warning is produced requesting that the policy be set.
568
569
570 The cmake_policy command is used to set policies to OLD or NEW
571 behavior. While setting policies individually is supported, we
572 encourage projects to set policies based on CMake versions.
573
574
575 cmake_policy(VERSION major.minor[.patch[.tweak]])
576
577 Specify that the current CMake list file is written for the
578 given version of CMake. All policies introduced in the speci‐
579 fied version or earlier will be set to use NEW behavior. All
580 policies introduced after the specified version will be unset
581 (unless variable CMAKE_POLICY_DEFAULT_CMP<NNNN> sets a default).
582 This effectively requests behavior preferred as of a given CMake
583 version and tells newer CMake versions to warn about their new
584 policies. The policy version specified must be at least 2.4 or
585 the command will report an error. In order to get compatibility
586 features supporting versions earlier than 2.4 see documentation
587 of policy CMP0001.
588
589
590 cmake_policy(SET CMP<NNNN> NEW)
591 cmake_policy(SET CMP<NNNN> OLD)
592
593 Tell CMake to use the OLD or NEW behavior for a given policy.
594 Projects depending on the old behavior of a given policy may
595 silence a policy warning by setting the policy state to OLD.
596 Alternatively one may fix the project to work with the new
597 behavior and set the policy state to NEW.
598
599
600 cmake_policy(GET CMP<NNNN> <variable>)
601
602 Check whether a given policy is set to OLD or NEW behavior. The
603 output variable value will be "OLD" or "NEW" if the policy is
604 set, and empty otherwise.
605
606
607 CMake keeps policy settings on a stack, so changes made by the
608 cmake_policy command affect only the top of the stack. A new
609 entry on the policy stack is managed automatically for each sub‐
610 directory to protect its parents and siblings. CMake also man‐
611 ages a new entry for scripts loaded by include() and find_pack‐
612 age() commands except when invoked with the NO_POLICY_SCOPE
613 option (see also policy CMP0011). The cmake_policy command pro‐
614 vides an interface to manage custom entries on the policy stack:
615
616
617 cmake_policy(PUSH)
618 cmake_policy(POP)
619
620 Each PUSH must have a matching POP to erase any changes. This
621 is useful to make temporary changes to policy settings.
622
623
624 Functions and macros record policy settings when they are cre‐
625 ated and use the pre-record policies when they are invoked. If
626 the function or macro implementation sets policies, the changes
627 automatically propagate up through callers until they reach the
628 closest nested policy stack entry.
629
630
631 configure_file
632 Copy a file to another location and modify its contents.
633
634 configure_file(<input> <output>
635 [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
636 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
637
638 Copies a file <input> to file <output> and substitutes variable
639 values referenced in the file content. If <input> is a relative
640 path it is evaluated with respect to the current source direc‐
641 tory. The <input> must be a file, not a directory. If <output>
642 is a relative path it is evaluated with respect to the current
643 binary directory. If <output> names an existing directory the
644 input file is placed in that directory with its original name.
645
646
647 If the <input> file is modified the build system will re-run
648 CMake to re-configure the file and generate the build system
649 again.
650
651
652 This command replaces any variables in the input file referenced
653 as ${VAR} or @VAR@ with their values as determined by CMake. If
654 a variable is not defined, it will be replaced with nothing. If
655 COPYONLY is specified, then no variable expansion will take
656 place. If ESCAPE_QUOTES is specified then any substituted
657 quotes will be C-style escaped. The file will be configured
658 with the current values of CMake variables. If @ONLY is speci‐
659 fied, only variables of the form @VAR@ will be replaced and
660 ${VAR} will be ignored. This is useful for configuring scripts
661 that use ${VAR}.
662
663
664 Input file lines of the form "#cmakedefine VAR ..." will be
665 replaced with either "#define VAR ..." or "/* #undef VAR */"
666 depending on whether VAR is set in CMake to any value not con‐
667 sidered a false constant by the if() command. (Content of "...",
668 if any, is processed as above.) Input file lines of the form
669 "#cmakedefine01 VAR" will be replaced with either "#define VAR
670 1" or "#define VAR 0" similarly.
671
672
673 With NEWLINE_STYLE the line ending could be adjusted:
674
675
676 'UNIX' or 'LF' for \n, 'DOS', 'WIN32' or 'CRLF' for \r\n.
677
678 COPYONLY must not be used with NEWLINE_STYLE.
679
680
681
682 ctest_build
683 Build the project.
684
685 ctest_build([BUILD build_dir] [TARGET target] [RETURN_VALUE res]
686 [APPEND][NUMBER_ERRORS val] [NUMBER_WARNINGS val])
687
688 Builds the given build directory and stores results in
689 Build.xml. If no BUILD is given, the CTEST_BINARY_DIRECTORY
690 variable is used.
691
692
693 The TARGET variable can be used to specify a build target. If
694 none is specified, the "all" target will be built.
695
696
697 The RETURN_VALUE option specifies a variable in which to store
698 the return value of the native build tool. The NUMBER_ERRORS and
699 NUMBER_WARNINGS options specify variables in which to store the
700 number of build errors and warnings detected.
701
702
703 The APPEND option marks results for append to those previously
704 submitted to a dashboard server since the last ctest_start.
705 Append semantics are defined by the dashboard server in use.
706
707
708 ctest_configure
709 Configure the project build tree.
710
711 ctest_configure([BUILD build_dir] [SOURCE source_dir] [APPEND]
712 [OPTIONS options] [RETURN_VALUE res])
713
714 Configures the given build directory and stores results in Con‐
715 figure.xml. If no BUILD is given, the CTEST_BINARY_DIRECTORY
716 variable is used. If no SOURCE is given, the CTEST_SOURCE_DIREC‐
717 TORY variable is used. The OPTIONS argument specifies command
718 line arguments to pass to the configuration tool. The
719 RETURN_VALUE option specifies a variable in which to store the
720 return value of the native build tool.
721
722
723 The APPEND option marks results for append to those previously
724 submitted to a dashboard server since the last ctest_start.
725 Append semantics are defined by the dashboard server in use.
726
727
728 ctest_coverage
729 Collect coverage tool results.
730
731 ctest_coverage([BUILD build_dir] [RETURN_VALUE res] [APPEND]
732 [LABELS label1 [label2 [...]]])
733
734 Perform the coverage of the given build directory and stores
735 results in Coverage.xml. The second argument is a variable that
736 will hold value.
737
738
739 The LABELS option filters the coverage report to include only
740 source files labeled with at least one of the labels specified.
741
742
743 The APPEND option marks results for append to those previously
744 submitted to a dashboard server since the last ctest_start.
745 Append semantics are defined by the dashboard server in use.
746
747
748 ctest_empty_binary_directory
749 empties the binary directory
750
751 ctest_empty_binary_directory( directory )
752
753 Removes a binary directory. This command will perform some
754 checks prior to deleting the directory in an attempt to avoid
755 malicious or accidental directory deletion.
756
757
758 ctest_memcheck
759 Run tests with a dynamic analysis tool.
760
761 ctest_memcheck([BUILD build_dir] [RETURN_VALUE res] [APPEND]
762 [START start number] [END end number]
763 [STRIDE stride number] [EXCLUDE exclude regex ]
764 [INCLUDE include regex]
765 [EXCLUDE_LABEL exclude regex]
766 [INCLUDE_LABEL label regex]
767 [PARALLEL_LEVEL level] )
768
769 Tests the given build directory and stores results in Mem‐
770 Check.xml. The second argument is a variable that will hold
771 value. Optionally, you can specify the starting test number
772 START, the ending test number END, the number of tests to skip
773 between each test STRIDE, a regular expression for tests to run
774 INCLUDE, or a regular expression for tests not to run EXCLUDE.
775 EXCLUDE_LABEL and INCLUDE_LABEL are regular expressions for
776 tests to be included or excluded by the test property LABEL.
777 PARALLEL_LEVEL should be set to a positive number representing
778 the number of tests to be run in parallel.
779
780
781 The APPEND option marks results for append to those previously
782 submitted to a dashboard server since the last ctest_start.
783 Append semantics are defined by the dashboard server in use.
784
785
786 ctest_read_custom_files
787 read CTestCustom files.
788
789 ctest_read_custom_files( directory ... )
790
791 Read all the CTestCustom.ctest or CTestCustom.cmake files from
792 the given directory.
793
794
795 ctest_run_script
796 runs a ctest -S script
797
798 ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
799 script_file_name2 ... [RETURN_VALUE var])
800
801 Runs a script or scripts much like if it was run from ctest -S.
802 If no argument is provided then the current script is run using
803 the current settings of the variables. If NEW_PROCESS is speci‐
804 fied then each script will be run in a separate process.If
805 RETURN_VALUE is specified the return value of the last script
806 run will be put into var.
807
808
809 ctest_sleep
810 sleeps for some amount of time
811
812 ctest_sleep(<seconds>)
813
814 Sleep for given number of seconds.
815
816
817 ctest_sleep(<time1> <duration> <time2>)
818
819 Sleep for t=(time1 + duration - time2) seconds if t > 0.
820
821
822 ctest_start
823 Starts the testing for a given model
824
825 ctest_start(Model [TRACK <track>] [APPEND] [source [binary]])
826
827 Starts the testing for a given model. The command should be
828 called after the binary directory is initialized. If the
829 'source' and 'binary' directory are not specified, it reads the
830 CTEST_SOURCE_DIRECTORY and CTEST_BINARY_DIRECTORY. If the track
831 is specified, the submissions will go to the specified track. If
832 APPEND is used, the existing TAG is used rather than creating a
833 new one based on the current time stamp.
834
835
836 ctest_submit
837 Submit results to a dashboard server.
838
839 ctest_submit([PARTS ...] [FILES ...] [RETRY_COUNT count] [RETRY_DELAY delay][RETURN_VALUE res])
840
841 By default all available parts are submitted if no PARTS or
842 FILES are specified. The PARTS option lists a subset of parts
843 to be submitted. Valid part names are:
844
845
846 Start = nothing
847 Update = ctest_update results, in Update.xml
848 Configure = ctest_configure results, in Configure.xml
849 Build = ctest_build results, in Build.xml
850 Test = ctest_test results, in Test.xml
851 Coverage = ctest_coverage results, in Coverage.xml
852 MemCheck = ctest_memcheck results, in DynamicAnalysis.xml
853 Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
854 ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
855 Submit = nothing
856
857 The FILES option explicitly lists specific files to be submit‐
858 ted. Each individual file must exist at the time of the call.
859
860
861 The RETRY_DELAY option specifies how long in seconds to wait
862 after a timed-out submission before attempting to re-submit.
863
864
865 The RETRY_COUNT option specifies how many times to retry a
866 timed-out submission.
867
868
869
870 ctest_test
871 Run tests in the project build tree.
872
873 ctest_test([BUILD build_dir] [APPEND]
874 [START start number] [END end number]
875 [STRIDE stride number] [EXCLUDE exclude regex ]
876 [INCLUDE include regex] [RETURN_VALUE res]
877 [EXCLUDE_LABEL exclude regex]
878 [INCLUDE_LABEL label regex]
879 [PARALLEL_LEVEL level]
880 [SCHEDULE_RANDOM on]
881 [STOP_TIME time of day])
882
883 Tests the given build directory and stores results in Test.xml.
884 The second argument is a variable that will hold value. Option‐
885 ally, you can specify the starting test number START, the ending
886 test number END, the number of tests to skip between each test
887 STRIDE, a regular expression for tests to run INCLUDE, or a reg‐
888 ular expression for tests to not run EXCLUDE. EXCLUDE_LABEL and
889 INCLUDE_LABEL are regular expression for test to be included or
890 excluded by the test property LABEL. PARALLEL_LEVEL should be
891 set to a positive number representing the number of tests to be
892 run in parallel. SCHEDULE_RANDOM will launch tests in a random
893 order, and is typically used to detect implicit test dependen‐
894 cies. STOP_TIME is the time of day at which the tests should all
895 stop running.
896
897
898 The APPEND option marks results for append to those previously
899 submitted to a dashboard server since the last ctest_start.
900 Append semantics are defined by the dashboard server in use.
901
902
903 ctest_update
904 Update the work tree from version control.
905
906 ctest_update([SOURCE source] [RETURN_VALUE res])
907
908 Updates the given source directory and stores results in
909 Update.xml. If no SOURCE is given, the CTEST_SOURCE_DIRECTORY
910 variable is used. The RETURN_VALUE option specifies a variable
911 in which to store the result, which is the number of files
912 updated or -1 on error.
913
914
915 ctest_upload
916 Upload files to a dashboard server.
917
918 ctest_upload(FILES ...)
919
920 Pass a list of files to be sent along with the build results to
921 the dashboard server.
922
923
924
925 else Starts the else portion of an if block.
926
927 else(expression)
928
929 See the if command.
930
931
932 elseif Starts the elseif portion of an if block.
933
934 elseif(expression)
935
936 See the if command.
937
938
939 endforeach
940 Ends a list of commands in a FOREACH block.
941
942 endforeach(expression)
943
944 See the FOREACH command.
945
946
947 endfunction
948 Ends a list of commands in a function block.
949
950 endfunction(expression)
951
952 See the function command.
953
954
955 endif Ends a list of commands in an if block.
956
957 endif(expression)
958
959 See the if command.
960
961
962 endmacro
963 Ends a list of commands in a macro block.
964
965 endmacro(expression)
966
967 See the macro command.
968
969
970 endwhile
971 Ends a list of commands in a while block.
972
973 endwhile(expression)
974
975 See the while command.
976
977
978 exec_program
979 Deprecated. Use the execute_process() command instead.
980
981 Run an executable program during the processing of the CMake‐
982 List.txt file.
983
984
985 exec_program(Executable [directory in which to run]
986 [ARGS <arguments to executable>]
987 [OUTPUT_VARIABLE <var>]
988 [RETURN_VALUE <var>])
989
990 The executable is run in the optionally specified directory.
991 The executable can include arguments if it is double quoted, but
992 it is better to use the optional ARGS argument to specify argu‐
993 ments to the program. This is because cmake will then be able
994 to escape spaces in the executable path. An optional argument
995 OUTPUT_VARIABLE specifies a variable in which to store the out‐
996 put. To capture the return value of the execution, provide a
997 RETURN_VALUE. If OUTPUT_VARIABLE is specified, then no output
998 will go to the stdout/stderr of the console running cmake.
999
1000
1001
1002 execute_process
1003 Execute one or more child processes.
1004
1005 execute_process(COMMAND <cmd1> [args1...]]
1006 [COMMAND <cmd2> [args2...] [...]]
1007 [WORKING_DIRECTORY <directory>]
1008 [TIMEOUT <seconds>]
1009 [RESULT_VARIABLE <variable>]
1010 [OUTPUT_VARIABLE <variable>]
1011 [ERROR_VARIABLE <variable>]
1012 [INPUT_FILE <file>]
1013 [OUTPUT_FILE <file>]
1014 [ERROR_FILE <file>]
1015 [OUTPUT_QUIET]
1016 [ERROR_QUIET]
1017 [OUTPUT_STRIP_TRAILING_WHITESPACE]
1018 [ERROR_STRIP_TRAILING_WHITESPACE])
1019
1020 Runs the given sequence of one or more commands with the stan‐
1021 dard output of each process piped to the standard input of the
1022 next. A single standard error pipe is used for all processes.
1023 If WORKING_DIRECTORY is given the named directory will be set as
1024 the current working directory of the child processes. If TIME‐
1025 OUT is given the child processes will be terminated if they do
1026 not finish in the specified number of seconds (fractions are
1027 allowed). If RESULT_VARIABLE is given the variable will be set
1028 to contain the result of running the processes. This will be an
1029 integer return code from the last child or a string describing
1030 an error condition. If OUTPUT_VARIABLE or ERROR_VARIABLE are
1031 given the variable named will be set with the contents of the
1032 standard output and standard error pipes respectively. If the
1033 same variable is named for both pipes their output will be
1034 merged in the order produced. If INPUT_FILE, OUTPUT_FILE, or
1035 ERROR_FILE is given the file named will be attached to the stan‐
1036 dard input of the first process, standard output of the last
1037 process, or standard error of all processes respectively. If
1038 OUTPUT_QUIET or ERROR_QUIET is given then the standard output or
1039 standard error results will be quietly ignored. If more than
1040 one OUTPUT_* or ERROR_* option is given for the same pipe the
1041 precedence is not specified. If no OUTPUT_* or ERROR_* options
1042 are given the output will be shared with the corresponding pipes
1043 of the CMake process itself.
1044
1045
1046 The execute_process command is a newer more powerful version of
1047 exec_program, but the old command has been kept for compatibil‐
1048 ity.
1049
1050
1051 file File manipulation command.
1052
1053 file(WRITE filename "message to write"... )
1054 file(APPEND filename "message to write"... )
1055 file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX])
1056 file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> filename variable)
1057 file(STRINGS filename variable [LIMIT_COUNT num]
1058 [LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes]
1059 [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes]
1060 [NEWLINE_CONSUME] [REGEX regex]
1061 [NO_HEX_CONVERSION])
1062 file(GLOB variable [RELATIVE path] [globbing expressions]...)
1063 file(GLOB_RECURSE variable [RELATIVE path]
1064 [FOLLOW_SYMLINKS] [globbing expressions]...)
1065 file(RENAME <oldname> <newname>)
1066 file(REMOVE [file1 ...])
1067 file(REMOVE_RECURSE [file1 ...])
1068 file(MAKE_DIRECTORY [directory1 directory2 ...])
1069 file(RELATIVE_PATH variable directory file)
1070 file(TO_CMAKE_PATH path result)
1071 file(TO_NATIVE_PATH path result)
1072 file(DOWNLOAD url file [INACTIVITY_TIMEOUT timeout]
1073 [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS]
1074 [EXPECTED_HASH ALGO=value] [EXPECTED_MD5 sum]
1075 [TLS_VERIFY on|off] [TLS_CAINFO file])
1076 file(UPLOAD filename url [INACTIVITY_TIMEOUT timeout]
1077 [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS])
1078 file(TIMESTAMP filename variable [<format string>] [UTC])
1079 file(GENERATE OUTPUT output_file
1080 <INPUT input_file|CONTENT input_content>
1081 [CONDITION expression])
1082
1083 WRITE will write a message into a file called 'filename'. It
1084 overwrites the file if it already exists, and creates the file
1085 if it does not exist. (If the file is a build input, use config‐
1086 ure_file to update the file only when its content changes.)
1087
1088
1089 APPEND will write a message into a file same as WRITE, except it
1090 will append it to the end of the file
1091
1092
1093 READ will read the content of a file and store it into the vari‐
1094 able. It will start at the given offset and read up to numBytes.
1095 If the argument HEX is given, the binary data will be converted
1096 to hexadecimal representation and this will be stored in the
1097 variable.
1098
1099
1100 MD5, SHA1, SHA224, SHA256, SHA384, and SHA512 will compute a
1101 cryptographic hash of the content of a file.
1102
1103
1104 STRINGS will parse a list of ASCII strings from a file and store
1105 it in a variable. Binary data in the file are ignored. Carriage
1106 return (CR) characters are ignored. It works also for Intel Hex
1107 and Motorola S-record files, which are automatically converted
1108 to binary format when reading them. Disable this using
1109 NO_HEX_CONVERSION.
1110
1111
1112 LIMIT_COUNT sets the maximum number of strings to return.
1113 LIMIT_INPUT sets the maximum number of bytes to read from the
1114 input file. LIMIT_OUTPUT sets the maximum number of bytes to
1115 store in the output variable. LENGTH_MINIMUM sets the minimum
1116 length of a string to return. Shorter strings are ignored.
1117 LENGTH_MAXIMUM sets the maximum length of a string to return.
1118 Longer strings are split into strings no longer than the maximum
1119 length. NEWLINE_CONSUME allows newlines to be included in
1120 strings instead of terminating them.
1121
1122
1123 REGEX specifies a regular expression that a string must match to
1124 be returned. Typical usage
1125
1126
1127 file(STRINGS myfile.txt myfile)
1128
1129 stores a list in the variable "myfile" in which each item is a
1130 line from the input file.
1131
1132
1133 GLOB will generate a list of all files that match the globbing
1134 expressions and store it into the variable. Globbing expressions
1135 are similar to regular expressions, but much simpler. If RELA‐
1136 TIVE flag is specified for an expression, the results will be
1137 returned as a relative path to the given path. (We do not rec‐
1138 ommend using GLOB to collect a list of source files from your
1139 source tree. If no CMakeLists.txt file changes when a source is
1140 added or removed then the generated build system cannot know
1141 when to ask CMake to regenerate.)
1142
1143
1144 Examples of globbing expressions include:
1145
1146
1147 *.cxx - match all files with extension cxx
1148 *.vt? - match all files with extension vta,...,vtz
1149 f[3-5].txt - match files f3.txt, f4.txt, f5.txt
1150
1151 GLOB_RECURSE will generate a list similar to the regular GLOB,
1152 except it will traverse all the subdirectories of the matched
1153 directory and match the files. Subdirectories that are symlinks
1154 are only traversed if FOLLOW_SYMLINKS is given or cmake policy
1155 CMP0009 is not set to NEW. See cmake --help-policy CMP0009 for
1156 more information.
1157
1158
1159 Examples of recursive globbing include:
1160
1161
1162 /dir/*.py - match all python files in /dir and subdirectories
1163
1164 MAKE_DIRECTORY will create the given directories, also if their
1165 parent directories don't exist yet
1166
1167
1168 RENAME moves a file or directory within a filesystem, replacing
1169 the destination atomically.
1170
1171
1172 REMOVE will remove the given files, also in subdirectories
1173
1174
1175 REMOVE_RECURSE will remove the given files and directories, also
1176 non-empty directories
1177
1178
1179 RELATIVE_PATH will determine relative path from directory to the
1180 given file.
1181
1182
1183 TO_CMAKE_PATH will convert path into a cmake style path with
1184 unix /. The input can be a single path or a system path like
1185 "$ENV{PATH}". Note the double quotes around the ENV call
1186 TO_CMAKE_PATH only takes one argument. This command will also
1187 convert the native list delimiters for a list of paths like the
1188 PATH environment variable.
1189
1190
1191 TO_NATIVE_PATH works just like TO_CMAKE_PATH, but will convert
1192 from a cmake style path into the native path style \ for win‐
1193 dows and / for UNIX.
1194
1195
1196 DOWNLOAD will download the given URL to the given file. If LOG
1197 var is specified a log of the download will be put in var. If
1198 STATUS var is specified the status of the operation will be put
1199 in var. The status is returned in a list of length 2. The first
1200 element is the numeric return value for the operation, and the
1201 second element is a string value for the error. A 0 numeric
1202 error means no error in the operation. If TIMEOUT time is speci‐
1203 fied, the operation will timeout after time seconds, time should
1204 be specified as an integer. The INACTIVITY_TIMEOUT specifies an
1205 integer number of seconds of inactivity after which the opera‐
1206 tion should terminate. If EXPECTED_HASH ALGO=value is specified,
1207 the operation will verify that the downloaded file's actual hash
1208 matches the expected value, where ALGO is one of MD5, SHA1,
1209 SHA224, SHA256, SHA384, or SHA512. If it does not match, the
1210 operation fails with an error. ("EXPECTED_MD5 sum" is short-hand
1211 for "EXPECTED_HASH MD5=sum".) If SHOW_PROGRESS is specified,
1212 progress information will be printed as status messages until
1213 the operation is complete. For https URLs CMake must be built
1214 with OpenSSL. TLS/SSL certificates are not checked by default.
1215 Set TLS_VERIFY to ON to check certificates and/or use
1216 EXPECTED_HASH to verify downloaded content. Set TLS_CAINFO to
1217 specify a custom Certificate Authority file. If either TLS
1218 option is not given CMake will check variables CMAKE_TLS_VERIFY
1219 and CMAKE_TLS_CAINFO, respectively.
1220
1221
1222 UPLOAD will upload the given file to the given URL. If LOG var
1223 is specified a log of the upload will be put in var. If STATUS
1224 var is specified the status of the operation will be put in var.
1225 The status is returned in a list of length 2. The first element
1226 is the numeric return value for the operation, and the second
1227 element is a string value for the error. A 0 numeric error means
1228 no error in the operation. If TIMEOUT time is specified, the
1229 operation will timeout after time seconds, time should be speci‐
1230 fied as an integer. The INACTIVITY_TIMEOUT specifies an integer
1231 number of seconds of inactivity after which the operation should
1232 terminate. If SHOW_PROGRESS is specified, progress information
1233 will be printed as status messages until the operation is com‐
1234 plete.
1235
1236
1237 TIMESTAMP will write a string representation of the modification
1238 time of filename to variable.
1239
1240
1241 Should the command be unable to obtain a timestamp variable will
1242 be set to the empty string "".
1243
1244
1245 See documentation of the string TIMESTAMP sub-command for more
1246 details.
1247
1248
1249 The file() command also provides COPY and INSTALL signatures:
1250
1251
1252 file(<COPY|INSTALL> files... DESTINATION <dir>
1253 [FILE_PERMISSIONS permissions...]
1254 [DIRECTORY_PERMISSIONS permissions...]
1255 [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
1256 [FILES_MATCHING]
1257 [[PATTERN <pattern> | REGEX <regex>]
1258 [EXCLUDE] [PERMISSIONS permissions...]] [...])
1259
1260 The COPY signature copies files, directories, and symlinks to a
1261 destination folder. Relative input paths are evaluated with
1262 respect to the current source directory, and a relative destina‐
1263 tion is evaluated with respect to the current build directory.
1264 Copying preserves input file timestamps, and optimizes out a
1265 file if it exists at the destination with the same timestamp.
1266 Copying preserves input permissions unless explicit permissions
1267 or NO_SOURCE_PERMISSIONS are given (default is USE_SOURCE_PER‐
1268 MISSIONS). See the install(DIRECTORY) command for documentation
1269 of permissions, PATTERN, REGEX, and EXCLUDE options.
1270
1271
1272 The INSTALL signature differs slightly from COPY: it prints sta‐
1273 tus messages, and NO_SOURCE_PERMISSIONS is default. Installa‐
1274 tion scripts generated by the install() command use this signa‐
1275 ture (with some undocumented options for internal use).
1276
1277
1278 GENERATE will write an <output_file> with content from an
1279 <input_file>, or from <input_content>. The output is generated
1280 conditionally based on the content of the <condition>. The file
1281 is written at CMake generate-time and the input may contain gen‐
1282 erator expressions. The <condition>, <output_file> and
1283 <input_file> may also contain generator expressions. The <con‐
1284 dition> must evaluate to either '0' or '1'. The <output_file>
1285 must evaluate to a unique name among all configurations and
1286 among all invocations of file(GENERATE).
1287
1288
1289 find_file
1290 Find the full path to a file.
1291
1292 find_file(<VAR> name1 [path1 path2 ...])
1293
1294 This is the short-hand signature for the command that is suffi‐
1295 cient in many cases. It is the same as find_file(<VAR> name1
1296 [PATHS path1 path2 ...])
1297
1298
1299 find_file(
1300 <VAR>
1301 name | NAMES name1 [name2 ...]
1302 [HINTS path1 [path2 ... ENV var]]
1303 [PATHS path1 [path2 ... ENV var]]
1304 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1305 [DOC "cache documentation string"]
1306 [NO_DEFAULT_PATH]
1307 [NO_CMAKE_ENVIRONMENT_PATH]
1308 [NO_CMAKE_PATH]
1309 [NO_SYSTEM_ENVIRONMENT_PATH]
1310 [NO_CMAKE_SYSTEM_PATH]
1311 [CMAKE_FIND_ROOT_PATH_BOTH |
1312 ONLY_CMAKE_FIND_ROOT_PATH |
1313 NO_CMAKE_FIND_ROOT_PATH]
1314 )
1315
1316 This command is used to find a full path to named file. A cache
1317 entry named by <VAR> is created to store the result of this com‐
1318 mand. If the full path to a file is found the result is stored
1319 in the variable and the search will not be repeated unless the
1320 variable is cleared. If nothing is found, the result will be
1321 <VAR>-NOTFOUND, and the search will be attempted again the next
1322 time find_file is invoked with the same variable. The name of
1323 the full path to a file that is searched for is specified by the
1324 names listed after the NAMES argument. Additional search loca‐
1325 tions can be specified after the PATHS argument. If ENV var is
1326 found in the HINTS or PATHS section the environment variable var
1327 will be read and converted from a system environment variable to
1328 a cmake style list of paths. For example ENV PATH would be a
1329 way to list the system path variable. The argument after DOC
1330 will be used for the documentation string in the cache.
1331 PATH_SUFFIXES specifies additional subdirectories to check below
1332 each search path.
1333
1334
1335 If NO_DEFAULT_PATH is specified, then no additional paths are
1336 added to the search. If NO_DEFAULT_PATH is not specified, the
1337 search process is as follows:
1338
1339
1340 1. Search paths specified in cmake-specific cache variables.
1341 These are intended to be used on the command line with a
1342 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
1343
1344
1345 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1346 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1347 CMAKE_INCLUDE_PATH
1348 CMAKE_FRAMEWORK_PATH
1349
1350 2. Search paths specified in cmake-specific environment vari‐
1351 ables. These are intended to be set in the user's shell config‐
1352 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1353 passed.
1354
1355
1356 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1357 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1358 CMAKE_INCLUDE_PATH
1359 CMAKE_FRAMEWORK_PATH
1360
1361 3. Search the paths specified by the HINTS option. These should
1362 be paths computed by system introspection, such as a hint pro‐
1363 vided by the location of another item already found. Hard-coded
1364 guesses should be specified with the PATHS option.
1365
1366
1367 4. Search the standard system environment variables. This can be
1368 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1369
1370
1371 PATH
1372 INCLUDE
1373
1374 5. Search cmake variables defined in the Platform files for the
1375 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
1376 passed.
1377
1378
1379 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1380 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1381 CMAKE_SYSTEM_INCLUDE_PATH
1382 CMAKE_SYSTEM_FRAMEWORK_PATH
1383
1384 6. Search the paths specified by the PATHS option or in the
1385 short-hand version of the command. These are typically
1386 hard-coded guesses.
1387
1388
1389 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1390 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
1391 following:
1392
1393
1394 "FIRST" - Try to find frameworks before standard
1395 libraries or headers. This is the default on Darwin.
1396 "LAST" - Try to find frameworks after standard
1397 libraries or headers.
1398 "ONLY" - Only try to find frameworks.
1399 "NEVER" - Never try to find frameworks.
1400
1401 On Darwin or systems supporting OS X Application Bundles, the
1402 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
1403 of the following:
1404
1405
1406 "FIRST" - Try to find application bundles before standard
1407 programs. This is the default on Darwin.
1408 "LAST" - Try to find application bundles after standard
1409 programs.
1410 "ONLY" - Only try to find application bundles.
1411 "NEVER" - Never try to find application bundles.
1412
1413 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
1414 directories to be prepended to all other search directories.
1415 This effectively "re-roots" the entire search under given loca‐
1416 tions. By default it is empty. It is especially useful when
1417 cross-compiling to point to the root directory of the target
1418 environment and CMake will search there too. By default at first
1419 the directories listed in CMAKE_FIND_ROOT_PATH and then the
1420 non-rooted directories will be searched. The default behavior
1421 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.
1422 This behavior can be manually overridden on a per-call basis. By
1423 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
1424 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
1425 CMAKE_FIND_ROOT_PATH will not be used. If
1426 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1427 tories will be searched.
1428
1429
1430 The default search order is designed to be most-specific to
1431 least-specific for common use cases. Projects may override the
1432 order by simply calling the command multiple times and using the
1433 NO_* options:
1434
1435
1436 find_file(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1437 find_file(<VAR> NAMES name)
1438
1439 Once one of the calls succeeds the result variable will be set
1440 and stored in the cache so that no call will search again.
1441
1442
1443 find_library
1444 Find a library.
1445
1446 find_library(<VAR> name1 [path1 path2 ...])
1447
1448 This is the short-hand signature for the command that is suffi‐
1449 cient in many cases. It is the same as find_library(<VAR> name1
1450 [PATHS path1 path2 ...])
1451
1452
1453 find_library(
1454 <VAR>
1455 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
1456 [HINTS path1 [path2 ... ENV var]]
1457 [PATHS path1 [path2 ... ENV var]]
1458 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1459 [DOC "cache documentation string"]
1460 [NO_DEFAULT_PATH]
1461 [NO_CMAKE_ENVIRONMENT_PATH]
1462 [NO_CMAKE_PATH]
1463 [NO_SYSTEM_ENVIRONMENT_PATH]
1464 [NO_CMAKE_SYSTEM_PATH]
1465 [CMAKE_FIND_ROOT_PATH_BOTH |
1466 ONLY_CMAKE_FIND_ROOT_PATH |
1467 NO_CMAKE_FIND_ROOT_PATH]
1468 )
1469
1470 This command is used to find a library. A cache entry named by
1471 <VAR> is created to store the result of this command. If the
1472 library is found the result is stored in the variable and the
1473 search will not be repeated unless the variable is cleared. If
1474 nothing is found, the result will be <VAR>-NOTFOUND, and the
1475 search will be attempted again the next time find_library is
1476 invoked with the same variable. The name of the library that is
1477 searched for is specified by the names listed after the NAMES
1478 argument. Additional search locations can be specified after
1479 the PATHS argument. If ENV var is found in the HINTS or PATHS
1480 section the environment variable var will be read and converted
1481 from a system environment variable to a cmake style list of
1482 paths. For example ENV PATH would be a way to list the system
1483 path variable. The argument after DOC will be used for the docu‐
1484 mentation string in the cache. PATH_SUFFIXES specifies addi‐
1485 tional subdirectories to check below each search path.
1486
1487
1488 If NO_DEFAULT_PATH is specified, then no additional paths are
1489 added to the search. If NO_DEFAULT_PATH is not specified, the
1490 search process is as follows:
1491
1492
1493 1. Search paths specified in cmake-specific cache variables.
1494 These are intended to be used on the command line with a
1495 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
1496
1497
1498 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1499 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1500 CMAKE_LIBRARY_PATH
1501 CMAKE_FRAMEWORK_PATH
1502
1503 2. Search paths specified in cmake-specific environment vari‐
1504 ables. These are intended to be set in the user's shell config‐
1505 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1506 passed.
1507
1508
1509 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1510 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1511 CMAKE_LIBRARY_PATH
1512 CMAKE_FRAMEWORK_PATH
1513
1514 3. Search the paths specified by the HINTS option. These should
1515 be paths computed by system introspection, such as a hint pro‐
1516 vided by the location of another item already found. Hard-coded
1517 guesses should be specified with the PATHS option.
1518
1519
1520 4. Search the standard system environment variables. This can be
1521 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1522
1523
1524 PATH
1525 LIB
1526
1527 5. Search cmake variables defined in the Platform files for the
1528 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
1529 passed.
1530
1531
1532 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1533 <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1534 CMAKE_SYSTEM_LIBRARY_PATH
1535 CMAKE_SYSTEM_FRAMEWORK_PATH
1536
1537 6. Search the paths specified by the PATHS option or in the
1538 short-hand version of the command. These are typically
1539 hard-coded guesses.
1540
1541
1542 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1543 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
1544 following:
1545
1546
1547 "FIRST" - Try to find frameworks before standard
1548 libraries or headers. This is the default on Darwin.
1549 "LAST" - Try to find frameworks after standard
1550 libraries or headers.
1551 "ONLY" - Only try to find frameworks.
1552 "NEVER" - Never try to find frameworks.
1553
1554 On Darwin or systems supporting OS X Application Bundles, the
1555 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
1556 of the following:
1557
1558
1559 "FIRST" - Try to find application bundles before standard
1560 programs. This is the default on Darwin.
1561 "LAST" - Try to find application bundles after standard
1562 programs.
1563 "ONLY" - Only try to find application bundles.
1564 "NEVER" - Never try to find application bundles.
1565
1566 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
1567 directories to be prepended to all other search directories.
1568 This effectively "re-roots" the entire search under given loca‐
1569 tions. By default it is empty. It is especially useful when
1570 cross-compiling to point to the root directory of the target
1571 environment and CMake will search there too. By default at first
1572 the directories listed in CMAKE_FIND_ROOT_PATH and then the
1573 non-rooted directories will be searched. The default behavior
1574 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.
1575 This behavior can be manually overridden on a per-call basis. By
1576 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
1577 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
1578 CMAKE_FIND_ROOT_PATH will not be used. If
1579 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1580 tories will be searched.
1581
1582
1583 The default search order is designed to be most-specific to
1584 least-specific for common use cases. Projects may override the
1585 order by simply calling the command multiple times and using the
1586 NO_* options:
1587
1588
1589 find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1590 find_library(<VAR> NAMES name)
1591
1592 Once one of the calls succeeds the result variable will be set
1593 and stored in the cache so that no call will search again.
1594
1595
1596 When more than one value is given to the NAMES option this com‐
1597 mand by default will consider one name at a time and search
1598 every directory for it. The NAMES_PER_DIR option tells this
1599 command to consider one directory at a time and search for all
1600 names in it.
1601
1602
1603 If the library found is a framework, then VAR will be set to the
1604 full path to the framework <fullPath>/A.framework. When a full
1605 path to a framework is used as a library, CMake will use a
1606 -framework A, and a -F<fullPath> to link the framework to the
1607 target.
1608
1609
1610 If the global property FIND_LIBRARY_USE_LIB64_PATHS is set all
1611 search paths will be tested as normal, with "64/" appended, and
1612 with all matches of "lib/" replaced with "lib64/". This property
1613 is automatically set for the platforms that are known to need it
1614 if at least one of the languages supported by the PROJECT com‐
1615 mand is enabled.
1616
1617
1618 find_package
1619 Load settings for an external project.
1620
1621 find_package(<package> [version] [EXACT] [QUIET] [MODULE]
1622 [REQUIRED] [[COMPONENTS] [components...]]
1623 [OPTIONAL_COMPONENTS components...]
1624 [NO_POLICY_SCOPE])
1625
1626 Finds and loads settings from an external project. <pack‐
1627 age>_FOUND will be set to indicate whether the package was
1628 found. When the package is found package-specific information
1629 is provided through variables and imported targets documented by
1630 the package itself. The QUIET option disables messages if the
1631 package cannot be found. The MODULE option disables the second
1632 signature documented below. The REQUIRED option stops process‐
1633 ing with an error message if the package cannot be found.
1634
1635
1636 A package-specific list of required components may be listed
1637 after the COMPONENTS option (or after the REQUIRED option if
1638 present). Additional optional components may be listed after
1639 OPTIONAL_COMPONENTS. Available components and their influence
1640 on whether a package is considered to be found are defined by
1641 the target package.
1642
1643
1644 The [version] argument requests a version with which the package
1645 found should be compatible (format is
1646 major[.minor[.patch[.tweak]]]). The EXACT option requests that
1647 the version be matched exactly. If no [version] and/or compo‐
1648 nent list is given to a recursive invocation inside a find-mod‐
1649 ule, the corresponding arguments are forwarded automatically
1650 from the outer call (including the EXACT flag for [version]).
1651 Version support is currently provided only on a package-by-pack‐
1652 age basis (details below).
1653
1654
1655 User code should generally look for packages using the above
1656 simple signature. The remainder of this command documentation
1657 specifies the full command signature and details of the search
1658 process. Project maintainers wishing to provide a package to be
1659 found by this command are encouraged to read on.
1660
1661
1662 The command has two modes by which it searches for packages:
1663 "Module" mode and "Config" mode. Module mode is available when
1664 the command is invoked with the above reduced signature. CMake
1665 searches for a file called "Find<package>.cmake" in the
1666 CMAKE_MODULE_PATH followed by the CMake installation. If the
1667 file is found, it is read and processed by CMake. It is respon‐
1668 sible for finding the package, checking the version, and produc‐
1669 ing any needed messages. Many find-modules provide limited or
1670 no support for versioning; check the module documentation. If
1671 no module is found and the MODULE option is not given the com‐
1672 mand proceeds to Config mode.
1673
1674
1675 The complete Config mode command signature is:
1676
1677
1678 find_package(<package> [version] [EXACT] [QUIET]
1679 [REQUIRED] [[COMPONENTS] [components...]]
1680 [CONFIG|NO_MODULE]
1681 [NO_POLICY_SCOPE]
1682 [NAMES name1 [name2 ...]]
1683 [CONFIGS config1 [config2 ...]]
1684 [HINTS path1 [path2 ... ]]
1685 [PATHS path1 [path2 ... ]]
1686 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1687 [NO_DEFAULT_PATH]
1688 [NO_CMAKE_ENVIRONMENT_PATH]
1689 [NO_CMAKE_PATH]
1690 [NO_SYSTEM_ENVIRONMENT_PATH]
1691 [NO_CMAKE_PACKAGE_REGISTRY]
1692 [NO_CMAKE_BUILDS_PATH]
1693 [NO_CMAKE_SYSTEM_PATH]
1694 [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
1695 [CMAKE_FIND_ROOT_PATH_BOTH |
1696 ONLY_CMAKE_FIND_ROOT_PATH |
1697 NO_CMAKE_FIND_ROOT_PATH])
1698
1699 The CONFIG option may be used to skip Module mode explicitly and
1700 switch to Config mode. It is synonymous to using NO_MODULE.
1701 Config mode is also implied by use of options not specified in
1702 the reduced signature.
1703
1704
1705 Config mode attempts to locate a configuration file provided by
1706 the package to be found. A cache entry called <package>_DIR is
1707 created to hold the directory containing the file. By default
1708 the command searches for a package with the name <package>. If
1709 the NAMES option is given the names following it are used
1710 instead of <package>. The command searches for a file called
1711 "<name>Config.cmake" or "<lower-case-name>-config.cmake" for
1712 each name specified. A replacement set of possible configura‐
1713 tion file names may be given using the CONFIGS option. The
1714 search procedure is specified below. Once found, the configura‐
1715 tion file is read and processed by CMake. Since the file is
1716 provided by the package it already knows the location of package
1717 contents. The full path to the configuration file is stored in
1718 the cmake variable <package>_CONFIG.
1719
1720
1721 All configuration files which have been considered by CMake
1722 while searching for an installation of the package with an
1723 appropriate version are stored in the cmake variable <pack‐
1724 age>_CONSIDERED_CONFIGS, the associated versions in <pack‐
1725 age>_CONSIDERED_VERSIONS.
1726
1727
1728 If the package configuration file cannot be found CMake will
1729 generate an error describing the problem unless the QUIET argu‐
1730 ment is specified. If REQUIRED is specified and the package is
1731 not found a fatal error is generated and the configure step
1732 stops executing. If <package>_DIR has been set to a directory
1733 not containing a configuration file CMake will ignore it and
1734 search from scratch.
1735
1736
1737 When the [version] argument is given Config mode will only find
1738 a version of the package that claims compatibility with the
1739 requested version (format is major[.minor[.patch[.tweak]]]). If
1740 the EXACT option is given only a version of the package claiming
1741 an exact match of the requested version may be found. CMake
1742 does not establish any convention for the meaning of version
1743 numbers. Package version numbers are checked by "version" files
1744 provided by the packages themselves. For a candidate package
1745 configuration file "<config-file>.cmake" the corresponding ver‐
1746 sion file is located next to it and named either "<con‐
1747 fig-file>-version.cmake" or "<config-file>Version.cmake". If no
1748 such version file is available then the configuration file is
1749 assumed to not be compatible with any requested version. A
1750 basic version file containing generic version matching code can
1751 be created using the macro write_basic_package_version_file(),
1752 see its documentation for more details. When a version file is
1753 found it is loaded to check the requested version number. The
1754 version file is loaded in a nested scope in which the following
1755 variables have been defined:
1756
1757
1758 PACKAGE_FIND_NAME = the <package> name
1759 PACKAGE_FIND_VERSION = full requested version string
1760 PACKAGE_FIND_VERSION_MAJOR = major version if requested, else 0
1761 PACKAGE_FIND_VERSION_MINOR = minor version if requested, else 0
1762 PACKAGE_FIND_VERSION_PATCH = patch version if requested, else 0
1763 PACKAGE_FIND_VERSION_TWEAK = tweak version if requested, else 0
1764 PACKAGE_FIND_VERSION_COUNT = number of version components, 0 to 4
1765
1766 The version file checks whether it satisfies the requested ver‐
1767 sion and sets these variables:
1768
1769
1770 PACKAGE_VERSION = full provided version string
1771 PACKAGE_VERSION_EXACT = true if version is exact match
1772 PACKAGE_VERSION_COMPATIBLE = true if version is compatible
1773 PACKAGE_VERSION_UNSUITABLE = true if unsuitable as any version
1774
1775 These variables are checked by the find_package command to
1776 determine whether the configuration file provides an acceptable
1777 version. They are not available after the find_package call
1778 returns. If the version is acceptable the following variables
1779 are set:
1780
1781
1782 <package>_VERSION = full provided version string
1783 <package>_VERSION_MAJOR = major version if provided, else 0
1784 <package>_VERSION_MINOR = minor version if provided, else 0
1785 <package>_VERSION_PATCH = patch version if provided, else 0
1786 <package>_VERSION_TWEAK = tweak version if provided, else 0
1787 <package>_VERSION_COUNT = number of version components, 0 to 4
1788
1789 and the corresponding package configuration file is loaded.
1790 When multiple package configuration files are available whose
1791 version files claim compatibility with the version requested it
1792 is unspecified which one is chosen. No attempt is made to
1793 choose a highest or closest version number.
1794
1795
1796 Config mode provides an elaborate interface and search proce‐
1797 dure. Much of the interface is provided for completeness and
1798 for use internally by find-modules loaded by Module mode. Most
1799 user code should simply call
1800
1801
1802 find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
1803
1804 in order to find a package. Package maintainers providing CMake
1805 package configuration files are encouraged to name and install
1806 them such that the procedure outlined below will find them with‐
1807 out requiring use of additional options.
1808
1809
1810 CMake constructs a set of possible installation prefixes for the
1811 package. Under each prefix several directories are searched for
1812 a configuration file. The tables below show the directories
1813 searched. Each entry is meant for installation trees following
1814 Windows (W), UNIX (U), or Apple (A) conventions.
1815
1816
1817 <prefix>/ (W)
1818 <prefix>/(cmake|CMake)/ (W)
1819 <prefix>/<name>*/ (W)
1820 <prefix>/<name>*/(cmake|CMake)/ (W)
1821 <prefix>/(lib/<arch>|lib|share)/cmake/<name>*/ (U)
1822 <prefix>/(lib/<arch>|lib|share)/<name>*/ (U)
1823 <prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/ (U)
1824
1825 On systems supporting OS X Frameworks and Application Bundles
1826 the following directories are searched for frameworks or bundles
1827 containing a configuration file:
1828
1829
1830 <prefix>/<name>.framework/Resources/ (A)
1831 <prefix>/<name>.framework/Resources/CMake/ (A)
1832 <prefix>/<name>.framework/Versions/*/Resources/ (A)
1833 <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A)
1834 <prefix>/<name>.app/Contents/Resources/ (A)
1835 <prefix>/<name>.app/Contents/Resources/CMake/ (A)
1836
1837 In all cases the <name> is treated as case-insensitive and cor‐
1838 responds to any of the names specified (<package> or names given
1839 by NAMES). Paths with lib/<arch> are enabled if
1840 CMAKE_LIBRARY_ARCHITECTURE is set. If PATH_SUFFIXES is speci‐
1841 fied the suffixes are appended to each (W) or (U) directory
1842 entry one-by-one.
1843
1844
1845 This set of directories is intended to work in cooperation with
1846 projects that provide configuration files in their installation
1847 trees. Directories above marked with (W) are intended for
1848 installations on Windows where the prefix may point at the top
1849 of an application's installation directory. Those marked with
1850 (U) are intended for installations on UNIX platforms where the
1851 prefix is shared by multiple packages. This is merely a conven‐
1852 tion, so all (W) and (U) directories are still searched on all
1853 platforms. Directories marked with (A) are intended for instal‐
1854 lations on Apple platforms. The cmake variables
1855 CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE determine the
1856 order of preference as specified below.
1857
1858
1859 The set of installation prefixes is constructed using the fol‐
1860 lowing steps. If NO_DEFAULT_PATH is specified all NO_* options
1861 are enabled.
1862
1863
1864 1. Search paths specified in cmake-specific cache variables.
1865 These are intended to be used on the command line with a
1866 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
1867
1868
1869 CMAKE_PREFIX_PATH
1870 CMAKE_FRAMEWORK_PATH
1871 CMAKE_APPBUNDLE_PATH
1872
1873 2. Search paths specified in cmake-specific environment vari‐
1874 ables. These are intended to be set in the user's shell config‐
1875 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1876 passed.
1877
1878
1879 <package>_DIR
1880 CMAKE_PREFIX_PATH
1881 CMAKE_FRAMEWORK_PATH
1882 CMAKE_APPBUNDLE_PATH
1883
1884 3. Search paths specified by the HINTS option. These should be
1885 paths computed by system introspection, such as a hint provided
1886 by the location of another item already found. Hard-coded
1887 guesses should be specified with the PATHS option.
1888
1889
1890 4. Search the standard system environment variables. This can be
1891 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed. Path entries
1892 ending in "/bin" or "/sbin" are automatically converted to their
1893 parent directories.
1894
1895
1896 PATH
1897
1898 5. Search project build trees recently configured in a CMake
1899 GUI. This can be skipped if NO_CMAKE_BUILDS_PATH is passed. It
1900 is intended for the case when a user is building multiple depen‐
1901 dent projects one after another.
1902
1903
1904 6. Search paths stored in the CMake user package registry. This
1905 can be skipped if NO_CMAKE_PACKAGE_REGISTRY is passed. On Win‐
1906 dows a <package> may appear under registry key
1907
1908
1909 HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package>
1910
1911 as a REG_SZ value, with arbitrary name, that specifies the
1912 directory containing the package configuration file. On UNIX
1913 platforms a <package> may appear under the directory
1914
1915
1916 ~/.cmake/packages/<package>
1917
1918 as a file, with arbitrary name, whose content specifies the
1919 directory containing the package configuration file. See the
1920 export(PACKAGE) command to create user package registry entries
1921 for project build trees.
1922
1923
1924 7. Search cmake variables defined in the Platform files for the
1925 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
1926 passed.
1927
1928
1929 CMAKE_SYSTEM_PREFIX_PATH
1930 CMAKE_SYSTEM_FRAMEWORK_PATH
1931 CMAKE_SYSTEM_APPBUNDLE_PATH
1932
1933 8. Search paths stored in the CMake system package registry.
1934 This can be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is
1935 passed. On Windows a <package> may appear under registry key
1936
1937
1938 HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package>
1939
1940 as a REG_SZ value, with arbitrary name, that specifies the
1941 directory containing the package configuration file. There is
1942 no system package registry on non-Windows platforms.
1943
1944
1945 9. Search paths specified by the PATHS option. These are typi‐
1946 cally hard-coded guesses.
1947
1948
1949 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1950 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
1951 following:
1952
1953
1954 "FIRST" - Try to find frameworks before standard
1955 libraries or headers. This is the default on Darwin.
1956 "LAST" - Try to find frameworks after standard
1957 libraries or headers.
1958 "ONLY" - Only try to find frameworks.
1959 "NEVER" - Never try to find frameworks.
1960
1961 On Darwin or systems supporting OS X Application Bundles, the
1962 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
1963 of the following:
1964
1965
1966 "FIRST" - Try to find application bundles before standard
1967 programs. This is the default on Darwin.
1968 "LAST" - Try to find application bundles after standard
1969 programs.
1970 "ONLY" - Only try to find application bundles.
1971 "NEVER" - Never try to find application bundles.
1972
1973 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
1974 directories to be prepended to all other search directories.
1975 This effectively "re-roots" the entire search under given loca‐
1976 tions. By default it is empty. It is especially useful when
1977 cross-compiling to point to the root directory of the target
1978 environment and CMake will search there too. By default at first
1979 the directories listed in CMAKE_FIND_ROOT_PATH and then the
1980 non-rooted directories will be searched. The default behavior
1981 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.
1982 This behavior can be manually overridden on a per-call basis. By
1983 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
1984 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
1985 CMAKE_FIND_ROOT_PATH will not be used. If
1986 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1987 tories will be searched.
1988
1989
1990 The default search order is designed to be most-specific to
1991 least-specific for common use cases. Projects may override the
1992 order by simply calling the command multiple times and using the
1993 NO_* options:
1994
1995
1996 find_package(<package> PATHS paths... NO_DEFAULT_PATH)
1997 find_package(<package>)
1998
1999 Once one of the calls succeeds the result variable will be set
2000 and stored in the cache so that no call will search again.
2001
2002
2003 Every non-REQUIRED find_package() call can be disabled by set‐
2004 ting the variable CMAKE_DISABLE_FIND_PACKAGE_<package> to TRUE.
2005 See the documentation for the CMAKE_DISABLE_FIND_PACKAGE_<pack‐
2006 age> variable for more information.
2007
2008
2009 When loading a find module or package configuration file
2010 find_package defines variables to provide information about the
2011 call arguments (and restores their original state before return‐
2012 ing):
2013
2014
2015 <package>_FIND_REQUIRED = true if REQUIRED option was given
2016 <package>_FIND_QUIETLY = true if QUIET option was given
2017 <package>_FIND_VERSION = full requested version string
2018 <package>_FIND_VERSION_MAJOR = major version if requested, else 0
2019 <package>_FIND_VERSION_MINOR = minor version if requested, else 0
2020 <package>_FIND_VERSION_PATCH = patch version if requested, else 0
2021 <package>_FIND_VERSION_TWEAK = tweak version if requested, else 0
2022 <package>_FIND_VERSION_COUNT = number of version components, 0 to 4
2023 <package>_FIND_VERSION_EXACT = true if EXACT option was given
2024 <package>_FIND_COMPONENTS = list of requested components
2025 <package>_FIND_REQUIRED_<c> = true if component <c> is required
2026 false if component <c> is optional
2027
2028 In Module mode the loaded find module is responsible to honor
2029 the request detailed by these variables; see the find module for
2030 details. In Config mode find_package handles REQUIRED, QUIET,
2031 and version options automatically but leaves it to the package
2032 configuration file to handle components in a way that makes
2033 sense for the package. The package configuration file may set
2034 <package>_FOUND to false to tell find_package that component
2035 requirements are not satisfied.
2036
2037
2038 See the cmake_policy() command documentation for discussion of
2039 the NO_POLICY_SCOPE option.
2040
2041
2042 find_path
2043 Find the directory containing a file.
2044
2045 find_path(<VAR> name1 [path1 path2 ...])
2046
2047 This is the short-hand signature for the command that is suffi‐
2048 cient in many cases. It is the same as find_path(<VAR> name1
2049 [PATHS path1 path2 ...])
2050
2051
2052 find_path(
2053 <VAR>
2054 name | NAMES name1 [name2 ...]
2055 [HINTS path1 [path2 ... ENV var]]
2056 [PATHS path1 [path2 ... ENV var]]
2057 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2058 [DOC "cache documentation string"]
2059 [NO_DEFAULT_PATH]
2060 [NO_CMAKE_ENVIRONMENT_PATH]
2061 [NO_CMAKE_PATH]
2062 [NO_SYSTEM_ENVIRONMENT_PATH]
2063 [NO_CMAKE_SYSTEM_PATH]
2064 [CMAKE_FIND_ROOT_PATH_BOTH |
2065 ONLY_CMAKE_FIND_ROOT_PATH |
2066 NO_CMAKE_FIND_ROOT_PATH]
2067 )
2068
2069 This command is used to find a directory containing the named
2070 file. A cache entry named by <VAR> is created to store the
2071 result of this command. If the file in a directory is found the
2072 result is stored in the variable and the search will not be
2073 repeated unless the variable is cleared. If nothing is found,
2074 the result will be <VAR>-NOTFOUND, and the search will be
2075 attempted again the next time find_path is invoked with the same
2076 variable. The name of the file in a directory that is searched
2077 for is specified by the names listed after the NAMES argument.
2078 Additional search locations can be specified after the PATHS
2079 argument. If ENV var is found in the HINTS or PATHS section the
2080 environment variable var will be read and converted from a sys‐
2081 tem environment variable to a cmake style list of paths. For
2082 example ENV PATH would be a way to list the system path vari‐
2083 able. The argument after DOC will be used for the documentation
2084 string in the cache. PATH_SUFFIXES specifies additional subdi‐
2085 rectories to check below each search path.
2086
2087
2088 If NO_DEFAULT_PATH is specified, then no additional paths are
2089 added to the search. If NO_DEFAULT_PATH is not specified, the
2090 search process is as follows:
2091
2092
2093 1. Search paths specified in cmake-specific cache variables.
2094 These are intended to be used on the command line with a
2095 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
2096
2097
2098 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2099 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2100 CMAKE_INCLUDE_PATH
2101 CMAKE_FRAMEWORK_PATH
2102
2103 2. Search paths specified in cmake-specific environment vari‐
2104 ables. These are intended to be set in the user's shell config‐
2105 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2106 passed.
2107
2108
2109 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2110 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2111 CMAKE_INCLUDE_PATH
2112 CMAKE_FRAMEWORK_PATH
2113
2114 3. Search the paths specified by the HINTS option. These should
2115 be paths computed by system introspection, such as a hint pro‐
2116 vided by the location of another item already found. Hard-coded
2117 guesses should be specified with the PATHS option.
2118
2119
2120 4. Search the standard system environment variables. This can be
2121 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
2122
2123
2124 PATH
2125 INCLUDE
2126
2127 5. Search cmake variables defined in the Platform files for the
2128 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
2129 passed.
2130
2131
2132 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2133 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2134 CMAKE_SYSTEM_INCLUDE_PATH
2135 CMAKE_SYSTEM_FRAMEWORK_PATH
2136
2137 6. Search the paths specified by the PATHS option or in the
2138 short-hand version of the command. These are typically
2139 hard-coded guesses.
2140
2141
2142 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2143 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
2144 following:
2145
2146
2147 "FIRST" - Try to find frameworks before standard
2148 libraries or headers. This is the default on Darwin.
2149 "LAST" - Try to find frameworks after standard
2150 libraries or headers.
2151 "ONLY" - Only try to find frameworks.
2152 "NEVER" - Never try to find frameworks.
2153
2154 On Darwin or systems supporting OS X Application Bundles, the
2155 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
2156 of the following:
2157
2158
2159 "FIRST" - Try to find application bundles before standard
2160 programs. This is the default on Darwin.
2161 "LAST" - Try to find application bundles after standard
2162 programs.
2163 "ONLY" - Only try to find application bundles.
2164 "NEVER" - Never try to find application bundles.
2165
2166 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
2167 directories to be prepended to all other search directories.
2168 This effectively "re-roots" the entire search under given loca‐
2169 tions. By default it is empty. It is especially useful when
2170 cross-compiling to point to the root directory of the target
2171 environment and CMake will search there too. By default at first
2172 the directories listed in CMAKE_FIND_ROOT_PATH and then the
2173 non-rooted directories will be searched. The default behavior
2174 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.
2175 This behavior can be manually overridden on a per-call basis. By
2176 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
2177 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
2178 CMAKE_FIND_ROOT_PATH will not be used. If
2179 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2180 tories will be searched.
2181
2182
2183 The default search order is designed to be most-specific to
2184 least-specific for common use cases. Projects may override the
2185 order by simply calling the command multiple times and using the
2186 NO_* options:
2187
2188
2189 find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2190 find_path(<VAR> NAMES name)
2191
2192 Once one of the calls succeeds the result variable will be set
2193 and stored in the cache so that no call will search again.
2194
2195
2196 When searching for frameworks, if the file is specified as
2197 A/b.h, then the framework search will look for A.framework/Head‐
2198 ers/b.h. If that is found the path will be set to the path to
2199 the framework. CMake will convert this to the correct -F option
2200 to include the file.
2201
2202
2203 find_program
2204 Find an executable program.
2205
2206 find_program(<VAR> name1 [path1 path2 ...])
2207
2208 This is the short-hand signature for the command that is suffi‐
2209 cient in many cases. It is the same as find_program(<VAR> name1
2210 [PATHS path1 path2 ...])
2211
2212
2213 find_program(
2214 <VAR>
2215 name | NAMES name1 [name2 ...]
2216 [HINTS path1 [path2 ... ENV var]]
2217 [PATHS path1 [path2 ... ENV var]]
2218 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2219 [DOC "cache documentation string"]
2220 [NO_DEFAULT_PATH]
2221 [NO_CMAKE_ENVIRONMENT_PATH]
2222 [NO_CMAKE_PATH]
2223 [NO_SYSTEM_ENVIRONMENT_PATH]
2224 [NO_CMAKE_SYSTEM_PATH]
2225 [CMAKE_FIND_ROOT_PATH_BOTH |
2226 ONLY_CMAKE_FIND_ROOT_PATH |
2227 NO_CMAKE_FIND_ROOT_PATH]
2228 )
2229
2230 This command is used to find a program. A cache entry named by
2231 <VAR> is created to store the result of this command. If the
2232 program is found the result is stored in the variable and the
2233 search will not be repeated unless the variable is cleared. If
2234 nothing is found, the result will be <VAR>-NOTFOUND, and the
2235 search will be attempted again the next time find_program is
2236 invoked with the same variable. The name of the program that is
2237 searched for is specified by the names listed after the NAMES
2238 argument. Additional search locations can be specified after
2239 the PATHS argument. If ENV var is found in the HINTS or PATHS
2240 section the environment variable var will be read and converted
2241 from a system environment variable to a cmake style list of
2242 paths. For example ENV PATH would be a way to list the system
2243 path variable. The argument after DOC will be used for the docu‐
2244 mentation string in the cache. PATH_SUFFIXES specifies addi‐
2245 tional subdirectories to check below each search path.
2246
2247
2248 If NO_DEFAULT_PATH is specified, then no additional paths are
2249 added to the search. If NO_DEFAULT_PATH is not specified, the
2250 search process is as follows:
2251
2252
2253 1. Search paths specified in cmake-specific cache variables.
2254 These are intended to be used on the command line with a
2255 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
2256
2257
2258 <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2259 CMAKE_PROGRAM_PATH
2260 CMAKE_APPBUNDLE_PATH
2261
2262 2. Search paths specified in cmake-specific environment vari‐
2263 ables. These are intended to be set in the user's shell config‐
2264 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2265 passed.
2266
2267
2268 <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2269 CMAKE_PROGRAM_PATH
2270 CMAKE_APPBUNDLE_PATH
2271
2272 3. Search the paths specified by the HINTS option. These should
2273 be paths computed by system introspection, such as a hint pro‐
2274 vided by the location of another item already found. Hard-coded
2275 guesses should be specified with the PATHS option.
2276
2277
2278 4. Search the standard system environment variables. This can be
2279 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
2280
2281
2282 PATH
2283
2284
2285 5. Search cmake variables defined in the Platform files for the
2286 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
2287 passed.
2288
2289
2290 <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2291 CMAKE_SYSTEM_PROGRAM_PATH
2292 CMAKE_SYSTEM_APPBUNDLE_PATH
2293
2294 6. Search the paths specified by the PATHS option or in the
2295 short-hand version of the command. These are typically
2296 hard-coded guesses.
2297
2298
2299 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2300 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
2301 following:
2302
2303
2304 "FIRST" - Try to find frameworks before standard
2305 libraries or headers. This is the default on Darwin.
2306 "LAST" - Try to find frameworks after standard
2307 libraries or headers.
2308 "ONLY" - Only try to find frameworks.
2309 "NEVER" - Never try to find frameworks.
2310
2311 On Darwin or systems supporting OS X Application Bundles, the
2312 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
2313 of the following:
2314
2315
2316 "FIRST" - Try to find application bundles before standard
2317 programs. This is the default on Darwin.
2318 "LAST" - Try to find application bundles after standard
2319 programs.
2320 "ONLY" - Only try to find application bundles.
2321 "NEVER" - Never try to find application bundles.
2322
2323 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
2324 directories to be prepended to all other search directories.
2325 This effectively "re-roots" the entire search under given loca‐
2326 tions. By default it is empty. It is especially useful when
2327 cross-compiling to point to the root directory of the target
2328 environment and CMake will search there too. By default at first
2329 the directories listed in CMAKE_FIND_ROOT_PATH and then the
2330 non-rooted directories will be searched. The default behavior
2331 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.
2332 This behavior can be manually overridden on a per-call basis. By
2333 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
2334 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
2335 CMAKE_FIND_ROOT_PATH will not be used. If
2336 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2337 tories will be searched.
2338
2339
2340 The default search order is designed to be most-specific to
2341 least-specific for common use cases. Projects may override the
2342 order by simply calling the command multiple times and using the
2343 NO_* options:
2344
2345
2346 find_program(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2347 find_program(<VAR> NAMES name)
2348
2349 Once one of the calls succeeds the result variable will be set
2350 and stored in the cache so that no call will search again.
2351
2352
2353 foreach
2354 Evaluate a group of commands for each value in a list.
2355
2356 foreach(loop_var arg1 arg2 ...)
2357 COMMAND1(ARGS ...)
2358 COMMAND2(ARGS ...)
2359 ...
2360 endforeach(loop_var)
2361
2362 All commands between foreach and the matching endforeach are
2363 recorded without being invoked. Once the endforeach is evalu‐
2364 ated, the recorded list of commands is invoked once for each
2365 argument listed in the original foreach command. Before each
2366 iteration of the loop "${loop_var}" will be set as a variable
2367 with the current value in the list.
2368
2369
2370 foreach(loop_var RANGE total)
2371 foreach(loop_var RANGE start stop [step])
2372
2373 Foreach can also iterate over a generated range of numbers.
2374 There are three types of this iteration:
2375
2376
2377 * When specifying single number, the range will have elements 0
2378 to "total".
2379
2380
2381 * When specifying two numbers, the range will have elements from
2382 the first number to the second number.
2383
2384
2385 * The third optional number is the increment used to iterate
2386 from the first number to the second number.
2387
2388
2389 foreach(loop_var IN [LISTS [list1 [...]]]
2390 [ITEMS [item1 [...]]])
2391
2392 Iterates over a precise list of items. The LISTS option names
2393 list-valued variables to be traversed, including empty elements
2394 (an empty string is a zero-length list). The ITEMS option ends
2395 argument parsing and includes all arguments following it in the
2396 iteration.
2397
2398
2399 function
2400 Start recording a function for later invocation as a command.
2401
2402 function(<name> [arg1 [arg2 [arg3 ...]]])
2403 COMMAND1(ARGS ...)
2404 COMMAND2(ARGS ...)
2405 ...
2406 endfunction(<name>)
2407
2408 Define a function named <name> that takes arguments named arg1
2409 arg2 arg3 (...). Commands listed after function, but before the
2410 matching endfunction, are not invoked until the function is
2411 invoked. When it is invoked, the commands recorded in the func‐
2412 tion are first modified by replacing formal parameters (${arg1})
2413 with the arguments passed, and then invoked as normal commands.
2414 In addition to referencing the formal parameters you can refer‐
2415 ence the variable ARGC which will be set to the number of argu‐
2416 ments passed into the function as well as ARGV0 ARGV1 ARGV2 ...
2417 which will have the actual values of the arguments passed in.
2418 This facilitates creating functions with optional arguments.
2419 Additionally ARGV holds the list of all arguments given to the
2420 function and ARGN holds the list of arguments past the last
2421 expected argument.
2422
2423
2424 A function opens a new scope: see set(var PARENT_SCOPE) for
2425 details.
2426
2427
2428 See the cmake_policy() command documentation for the behavior of
2429 policies inside functions.
2430
2431
2432 get_cmake_property
2433 Get a property of the CMake instance.
2434
2435 get_cmake_property(VAR property)
2436
2437 Get a property from the CMake instance. The value of the prop‐
2438 erty is stored in the variable VAR. If the property is not
2439 found, VAR will be set to "NOTFOUND". Some supported properties
2440 include: VARIABLES, CACHE_VARIABLES, COMMANDS, MACROS, and COM‐
2441 PONENTS.
2442
2443
2444 See also the more general get_property() command.
2445
2446
2447 get_directory_property
2448 Get a property of DIRECTORY scope.
2449
2450 get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
2451
2452 Store a property of directory scope in the named variable. If
2453 the property is not defined the empty-string is returned. The
2454 DIRECTORY argument specifies another directory from which to
2455 retrieve the property value. The specified directory must have
2456 already been traversed by CMake.
2457
2458
2459 get_directory_property(<variable> [DIRECTORY <dir>]
2460 DEFINITION <var-name>)
2461
2462 Get a variable definition from a directory. This form is useful
2463 to get a variable definition from another directory.
2464
2465
2466 See also the more general get_property() command.
2467
2468
2469 get_filename_component
2470 Get a specific component of a full filename.
2471
2472 get_filename_component(<VAR> <FileName> <COMP> [CACHE])
2473
2474 Set <VAR> to a component of <FileName>, where <COMP> is one of:
2475
2476
2477 DIRECTORY = Directory without file name
2478 NAME = File name without directory
2479 EXT = File name longest extension (.b.c from d/a.b.c)
2480 NAME_WE = File name without directory or longest extension
2481 ABSOLUTE = Full path to file
2482 REALPATH = Full path to existing file with symlinks resolved
2483 PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
2484
2485 Paths are returned with forward slashes and have no trailing
2486 slahes. The longest file extension is always considered. If the
2487 optional CACHE argument is specified, the result variable is
2488 added to the cache.
2489
2490
2491 get_filename_component(<VAR> FileName
2492 PROGRAM [PROGRAM_ARGS <ARG_VAR>]
2493 [CACHE])
2494
2495 The program in FileName will be found in the system search path
2496 or left as a full path. If PROGRAM_ARGS is present with PRO‐
2497 GRAM, then any command-line arguments present in the FileName
2498 string are split from the program name and stored in <ARG_VAR>.
2499 This is used to separate a program name from its arguments in a
2500 command line string.
2501
2502
2503 get_property
2504 Get a property.
2505
2506 get_property(<variable>
2507 <GLOBAL |
2508 DIRECTORY [dir] |
2509 TARGET <target> |
2510 SOURCE <source> |
2511 TEST <test> |
2512 CACHE <entry> |
2513 VARIABLE>
2514 PROPERTY <name>
2515 [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
2516
2517 Get one property from one object in a scope. The first argument
2518 specifies the variable in which to store the result. The second
2519 argument determines the scope from which to get the property.
2520 It must be one of the following:
2521
2522
2523 GLOBAL scope is unique and does not accept a name.
2524
2525
2526 DIRECTORY scope defaults to the current directory but another
2527 directory (already processed by CMake) may be named by full or
2528 relative path.
2529
2530
2531 TARGET scope must name one existing target.
2532
2533
2534 SOURCE scope must name one source file.
2535
2536
2537 TEST scope must name one existing test.
2538
2539
2540 CACHE scope must name one cache entry.
2541
2542
2543 VARIABLE scope is unique and does not accept a name.
2544
2545
2546 The required PROPERTY option is immediately followed by the name
2547 of the property to get. If the property is not set an empty
2548 value is returned. If the SET option is given the variable is
2549 set to a boolean value indicating whether the property has been
2550 set. If the DEFINED option is given the variable is set to a
2551 boolean value indicating whether the property has been defined
2552 such as with define_property. If BRIEF_DOCS or FULL_DOCS is
2553 given then the variable is set to a string containing documenta‐
2554 tion for the requested property. If documentation is requested
2555 for a property that has not been defined NOTFOUND is returned.
2556
2557
2558 if Conditionally execute a group of commands.
2559
2560 if(expression)
2561 # then section.
2562 COMMAND1(ARGS ...)
2563 COMMAND2(ARGS ...)
2564 ...
2565 elseif(expression2)
2566 # elseif section.
2567 COMMAND1(ARGS ...)
2568 COMMAND2(ARGS ...)
2569 ...
2570 else(expression)
2571 # else section.
2572 COMMAND1(ARGS ...)
2573 COMMAND2(ARGS ...)
2574 ...
2575 endif(expression)
2576
2577 Evaluates the given expression. If the result is true, the com‐
2578 mands in the THEN section are invoked. Otherwise, the commands
2579 in the else section are invoked. The elseif and else sections
2580 are optional. You may have multiple elseif clauses. Note that
2581 the expression in the else and endif clause is optional. Long
2582 expressions can be used and there is a traditional order of
2583 precedence. Parenthetical expressions are evaluated first fol‐
2584 lowed by unary operators such as EXISTS, COMMAND, and DEFINED.
2585 Then any EQUAL, LESS, GREATER, STRLESS, STRGREATER, STREQUAL,
2586 MATCHES will be evaluated. Then NOT operators and finally AND,
2587 OR operators will be evaluated. Possible expressions are:
2588
2589
2590 if(<constant>)
2591
2592 True if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
2593 ber. False if the constant is 0, OFF, NO, FALSE, N, IGNORE,
2594 NOTFOUND, '', or ends in the suffix '-NOTFOUND'. Named boolean
2595 constants are case-insensitive. If the argument is not one of
2596 these constants, it is treated as a variable:
2597
2598
2599 if(<variable>)
2600
2601 True if the variable is defined to a value that is not a false
2602 constant. False otherwise. (Note macro arguments are not vari‐
2603 ables.)
2604
2605
2606 if(NOT <expression>)
2607
2608 True if the expression is not true.
2609
2610
2611 if(<expr1> AND <expr2>)
2612
2613 True if both expressions would be considered true individually.
2614
2615
2616 if(<expr1> OR <expr2>)
2617
2618 True if either expression would be considered true individually.
2619
2620
2621 if(COMMAND command-name)
2622
2623 True if the given name is a command, macro or function that can
2624 be invoked.
2625
2626
2627 if(POLICY policy-id)
2628
2629 True if the given name is an existing policy (of the form
2630 CMP<NNNN>).
2631
2632
2633 if(TARGET target-name)
2634
2635 True if the given name is an existing target, built or imported.
2636
2637
2638 if(EXISTS file-name)
2639 if(EXISTS directory-name)
2640
2641 True if the named file or directory exists. Behavior is
2642 well-defined only for full paths.
2643
2644
2645 if(file1 IS_NEWER_THAN file2)
2646
2647 True if file1 is newer than file2 or if one of the two files
2648 doesn't exist. Behavior is well-defined only for full paths. If
2649 the file time stamps are exactly the same, an IS_NEWER_THAN com‐
2650 parison returns true, so that any dependent build operations
2651 will occur in the event of a tie. This includes the case of
2652 passing the same file name for both file1 and file2.
2653
2654
2655 if(IS_DIRECTORY directory-name)
2656
2657 True if the given name is a directory. Behavior is well-defined
2658 only for full paths.
2659
2660
2661 if(IS_SYMLINK file-name)
2662
2663 True if the given name is a symbolic link. Behavior is
2664 well-defined only for full paths.
2665
2666
2667 if(IS_ABSOLUTE path)
2668
2669 True if the given path is an absolute path.
2670
2671
2672 if(<variable|string> MATCHES regex)
2673
2674 True if the given string or variable's value matches the given
2675 regular expression.
2676
2677
2678 if(<variable|string> LESS <variable|string>)
2679 if(<variable|string> GREATER <variable|string>)
2680 if(<variable|string> EQUAL <variable|string>)
2681
2682 True if the given string or variable's value is a valid number
2683 and the inequality or equality is true.
2684
2685
2686 if(<variable|string> STRLESS <variable|string>)
2687 if(<variable|string> STRGREATER <variable|string>)
2688 if(<variable|string> STREQUAL <variable|string>)
2689
2690 True if the given string or variable's value is lexicographi‐
2691 cally less (or greater, or equal) than the string or variable on
2692 the right.
2693
2694
2695 if(<variable|string> VERSION_LESS <variable|string>)
2696 if(<variable|string> VERSION_EQUAL <variable|string>)
2697 if(<variable|string> VERSION_GREATER <variable|string>)
2698
2699 Component-wise integer version number comparison (version format
2700 is major[.minor[.patch[.tweak]]]).
2701
2702
2703 if(DEFINED <variable>)
2704
2705 True if the given variable is defined. It does not matter if the
2706 variable is true or false just if it has been set.
2707
2708
2709 if((expression) AND (expression OR (expression)))
2710
2711 The expressions inside the parenthesis are evaluated first and
2712 then the remaining expression is evaluated as in the previous
2713 examples. Where there are nested parenthesis the innermost are
2714 evaluated as part of evaluating the expression that contains
2715 them.
2716
2717
2718 The if command was written very early in CMake's history, pre‐
2719 dating the ${} variable evaluation syntax, and for convenience
2720 evaluates variables named by its arguments as shown in the above
2721 signatures. Note that normal variable evaluation with ${}
2722 applies before the if command even receives the arguments.
2723 Therefore code like
2724
2725
2726 set(var1 OFF)
2727 set(var2 "var1")
2728 if(${var2})
2729
2730 appears to the if command as
2731
2732
2733 if(var1)
2734
2735 and is evaluated according to the if(<variable>) case documented
2736 above. The result is OFF which is false. However, if we remove
2737 the ${} from the example then the command sees
2738
2739
2740 if(var2)
2741
2742 which is true because var2 is defined to "var1" which is not a
2743 false constant.
2744
2745
2746 Automatic evaluation applies in the other cases whenever the
2747 above-documented signature accepts <variable|string>:
2748
2749
2750 1) The left hand argument to MATCHES is first checked to see if
2751 it is a defined variable, if so the variable's value is used,
2752 otherwise the original value is used.
2753
2754
2755 2) If the left hand argument to MATCHES is missing it returns
2756 false without error
2757
2758
2759 3) Both left and right hand arguments to LESS GREATER EQUAL are
2760 independently tested to see if they are defined variables, if so
2761 their defined values are used otherwise the original value is
2762 used.
2763
2764
2765 4) Both left and right hand arguments to STRLESS STREQUAL STR‐
2766 GREATER are independently tested to see if they are defined
2767 variables, if so their defined values are used otherwise the
2768 original value is used.
2769
2770
2771 5) Both left and right hand argumemnts to VERSION_LESS VER‐
2772 SION_EQUAL VERSION_GREATER are independently tested to see if
2773 they are defined variables, if so their defined values are used
2774 otherwise the original value is used.
2775
2776
2777 6) The right hand argument to NOT is tested to see if it is a
2778 boolean constant, if so the value is used, otherwise it is
2779 assumed to be a variable and it is dereferenced.
2780
2781
2782 7) The left and right hand arguments to AND OR are independently
2783 tested to see if they are boolean constants, if so they are used
2784 as such, otherwise they are assumed to be variables and are
2785 dereferenced.
2786
2787
2788
2789 include
2790 Load and run CMake code from a file or module.
2791
2792 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
2793 [NO_POLICY_SCOPE])
2794
2795 Load and run CMake code from the file given. Variable reads and
2796 writes access the scope of the caller (dynamic scoping). If
2797 OPTIONAL is present, then no error is raised if the file does
2798 not exist. If RESULT_VARIABLE is given the variable will be set
2799 to the full filename which has been included or NOTFOUND if it
2800 failed.
2801
2802
2803 If a module is specified instead of a file, the file with name
2804 <modulename>.cmake is searched first in CMAKE_MODULE_PATH, then
2805 in the CMake module directory. There is one exception to this:
2806 if the file which calls include() is located itself in the CMake
2807 module directory, then first the CMake module directory is
2808 searched and CMAKE_MODULE_PATH afterwards. See also policy
2809 CMP0017.
2810
2811
2812 See the cmake_policy() command documentation for discussion of
2813 the NO_POLICY_SCOPE option.
2814
2815
2816 list List operations.
2817
2818 list(LENGTH <list> <output variable>)
2819 list(GET <list> <element index> [<element index> ...]
2820 <output variable>)
2821 list(APPEND <list> <element> [<element> ...])
2822 list(FIND <list> <value> <output variable>)
2823 list(INSERT <list> <element_index> <element> [<element> ...])
2824 list(REMOVE_ITEM <list> <value> [<value> ...])
2825 list(REMOVE_AT <list> <index> [<index> ...])
2826 list(REMOVE_DUPLICATES <list>)
2827 list(REVERSE <list>)
2828 list(SORT <list>)
2829
2830 LENGTH will return a given list's length.
2831
2832
2833 GET will return list of elements specified by indices from the
2834 list.
2835
2836
2837 APPEND will append elements to the list.
2838
2839
2840 FIND will return the index of the element specified in the list
2841 or -1 if it wasn't found.
2842
2843
2844 INSERT will insert elements to the list to the specified loca‐
2845 tion.
2846
2847
2848 REMOVE_AT and REMOVE_ITEM will remove items from the list. The
2849 difference is that REMOVE_ITEM will remove the given items,
2850 while REMOVE_AT will remove the items at the given indices.
2851
2852
2853 REMOVE_DUPLICATES will remove duplicated items in the list.
2854
2855
2856 REVERSE reverses the contents of the list in-place.
2857
2858
2859 SORT sorts the list in-place alphabetically.
2860
2861
2862 The list subcommands APPEND, INSERT, REMOVE_AT, REMOVE_ITEM,
2863 REMOVE_DUPLICATES, REVERSE and SORT may create new values for
2864 the list within the current CMake variable scope. Similar to the
2865 SET command, the LIST command creates new variable values in the
2866 current scope, even if the list itself is actually defined in a
2867 parent scope. To propagate the results of these operations
2868 upwards, use SET with PARENT_SCOPE, SET with CACHE INTERNAL, or
2869 some other means of value propagation.
2870
2871
2872 NOTES: A list in cmake is a ; separated group of strings. To
2873 create a list the set command can be used. For example, set(var
2874 a b c d e) creates a list with a;b;c;d;e, and set(var "a b c d
2875 e") creates a string or a list with one item in it.
2876
2877
2878 When specifying index values, if <element index> is 0 or
2879 greater, it is indexed from the beginning of the list, with 0
2880 representing the first list element. If <element index> is -1 or
2881 lesser, it is indexed from the end of the list, with -1 repre‐
2882 senting the last list element. Be careful when counting with
2883 negative indices: they do not start from 0. -0 is equivalent to
2884 0, the first list element.
2885
2886
2887
2888 macro Start recording a macro for later invocation as a command.
2889
2890 macro(<name> [arg1 [arg2 [arg3 ...]]])
2891 COMMAND1(ARGS ...)
2892 COMMAND2(ARGS ...)
2893 ...
2894 endmacro(<name>)
2895
2896 Define a macro named <name> that takes arguments named arg1 arg2
2897 arg3 (...). Commands listed after macro, but before the match‐
2898 ing endmacro, are not invoked until the macro is invoked. When
2899 it is invoked, the commands recorded in the macro are first mod‐
2900 ified by replacing formal parameters (${arg1}) with the argu‐
2901 ments passed, and then invoked as normal commands. In addition
2902 to referencing the formal parameters you can reference the val‐
2903 ues ${ARGC} which will be set to the number of arguments passed
2904 into the function as well as ${ARGV0} ${ARGV1} ${ARGV2} ...
2905 which will have the actual values of the arguments passed in.
2906 This facilitates creating macros with optional arguments. Addi‐
2907 tionally ${ARGV} holds the list of all arguments given to the
2908 macro and ${ARGN} holds the list of arguments past the last
2909 expected argument. Note that the parameters to a macro and val‐
2910 ues such as ARGN are not variables in the usual CMake sense.
2911 They are string replacements much like the C preprocessor would
2912 do with a macro. If you want true CMake variables and/or better
2913 CMake scope control you should look at the function command.
2914
2915
2916 See the cmake_policy() command documentation for the behavior of
2917 policies inside macros.
2918
2919
2920 make_directory
2921 Deprecated. Use the file(MAKE_DIRECTORY ) command instead.
2922
2923 make_directory(directory)
2924
2925 Creates the specified directory. Full paths should be given.
2926 Any parent directories that do not exist will also be created.
2927 Use with care.
2928
2929
2930 mark_as_advanced
2931 Mark cmake cached variables as advanced.
2932
2933 mark_as_advanced([CLEAR|FORCE] VAR VAR2 VAR...)
2934
2935 Mark the named cached variables as advanced. An advanced vari‐
2936 able will not be displayed in any of the cmake GUIs unless the
2937 show advanced option is on. If CLEAR is the first argument
2938 advanced variables are changed back to unadvanced. If FORCE is
2939 the first argument, then the variable is made advanced. If nei‐
2940 ther FORCE nor CLEAR is specified, new values will be marked as
2941 advanced, but if the variable already has an
2942 advanced/non-advanced state, it will not be changed.
2943
2944
2945 It does nothing in script mode.
2946
2947
2948 math Mathematical expressions.
2949
2950 math(EXPR <output variable> <math expression>)
2951
2952 EXPR evaluates mathematical expression and returns result in the
2953 output variable. Example mathematical expression is '5 * ( 10 +
2954 13 )'. Supported operators are + - * / % | & ^ ~ << >> * / %.
2955 They have the same meaning as they do in C code.
2956
2957
2958 message
2959 Display a message to the user.
2960
2961 message([STATUS|WARNING|AUTHOR_WARNING|FATAL_ERROR|SEND_ERROR]
2962 "message to display" ...)
2963
2964 The optional keyword determines the type of message:
2965
2966
2967 (none) = Important information
2968 STATUS = Incidental information
2969 WARNING = CMake Warning, continue processing
2970 AUTHOR_WARNING = CMake Warning (dev), continue processing
2971 SEND_ERROR = CMake Error, continue processing,
2972 but skip generation
2973 FATAL_ERROR = CMake Error, stop processing and generation
2974
2975 The CMake command-line tool displays STATUS messages on stdout
2976 and all other message types on stderr. The CMake GUI displays
2977 all messages in its log area. The interactive dialogs (ccmake
2978 and CMakeSetup) show STATUS messages one at a time on a status
2979 line and other messages in interactive pop-up boxes.
2980
2981
2982 CMake Warning and Error message text displays using a simple
2983 markup language. Non-indented text is formatted in line-wrapped
2984 paragraphs delimited by newlines. Indented text is considered
2985 pre-formatted.
2986
2987
2988 option Provides an option that the user can optionally select.
2989
2990 option(<option_variable> "help string describing option"
2991 [initial value])
2992
2993 Provide an option for the user to select as ON or OFF. If no
2994 initial value is provided, OFF is used.
2995
2996
2997 If you have options that depend on the values of other options,
2998 see the module help for CMakeDependentOption.
2999
3000
3001 remove Deprecated. Use the list(REMOVE_ITEM ) command instead.
3002
3003 remove(VAR VALUE VALUE ...)
3004
3005 Removes VALUE from the variable VAR. This is typically used to
3006 remove entries from a vector (e.g. semicolon separated list).
3007 VALUE is expanded.
3008
3009
3010 return Return from a file, directory or function.
3011
3012 return()
3013
3014 Returns from a file, directory or function. When this command is
3015 encountered in an included file (via include() or find_pack‐
3016 age()), it causes processing of the current file to stop and
3017 control is returned to the including file. If it is encountered
3018 in a file which is not included by another file, e.g. a CMake‐
3019 Lists.txt, control is returned to the parent directory if there
3020 is one. If return is called in a function, control is returned
3021 to the caller of the function. Note that a macro is not a func‐
3022 tion and does not handle return like a function does.
3023
3024
3025 separate_arguments
3026 Parse space-separated arguments into a semicolon-separated list.
3027
3028 separate_arguments(<var> <UNIX|WINDOWS>_COMMAND "<args>")
3029
3030 Parses a unix- or windows-style command-line string "<args>" and
3031 stores a semicolon-separated list of the arguments in <var>.
3032 The entire command line must be given in one "<args>" argument.
3033
3034
3035 The UNIX_COMMAND mode separates arguments by unquoted white‐
3036 space. It recognizes both single-quote and double-quote pairs.
3037 A backslash escapes the next literal character (\" is "); there
3038 are no special escapes (\n is just n).
3039
3040
3041 The WINDOWS_COMMAND mode parses a windows command-line using the
3042 same syntax the runtime library uses to construct argv at
3043 startup. It separates arguments by whitespace that is not dou‐
3044 ble-quoted. Backslashes are literal unless they precede dou‐
3045 ble-quotes. See the MSDN article "Parsing C Command-Line Argu‐
3046 ments" for details.
3047
3048
3049 separate_arguments(VARIABLE)
3050
3051 Convert the value of VARIABLE to a semi-colon separated list.
3052 All spaces are replaced with ';'. This helps with generating
3053 command lines.
3054
3055
3056 set Set a CMake, cache or environment variable to a given value.
3057
3058 set(<variable> <value>
3059 [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE])
3060
3061 Within CMake sets <variable> to the value <value>. <value> is
3062 expanded before <variable> is set to it. Normally, set will set
3063 a regular CMake variable. If CACHE is present, then the <vari‐
3064 able> is put in the cache instead, unless it is already in the
3065 cache. See section 'Variable types in CMake' below for details
3066 of regular and cache variables and their interactions. If CACHE
3067 is used, <type> and <docstring> are required. <type> is used by
3068 the CMake GUI to choose a widget with which the user sets a
3069 value. The value for <type> may be one of
3070
3071
3072 FILEPATH = File chooser dialog.
3073 PATH = Directory chooser dialog.
3074 STRING = Arbitrary string.
3075 BOOL = Boolean ON/OFF checkbox.
3076 INTERNAL = No GUI entry (used for persistent variables).
3077
3078 If <type> is INTERNAL, the cache variable is marked as internal,
3079 and will not be shown to the user in tools like cmake-gui. This
3080 is intended for values that should be persisted in the cache,
3081 but which users should not normally change. INTERNAL implies
3082 FORCE.
3083
3084
3085 Normally, set(...CACHE...) creates cache variables, but does not
3086 modify them. If FORCE is specified, the value of the cache vari‐
3087 able is set, even if the variable is already in the cache. This
3088 should normally be avoided, as it will remove any changes to the
3089 cache variable's value by the user.
3090
3091
3092 If PARENT_SCOPE is present, the variable will be set in the
3093 scope above the current scope. Each new directory or function
3094 creates a new scope. This command will set the value of a vari‐
3095 able into the parent directory or calling function (whichever is
3096 applicable to the case at hand). PARENT_SCOPE cannot be combined
3097 with CACHE.
3098
3099
3100 If <value> is not specified then the variable is removed instead
3101 of set. See also: the unset() command.
3102
3103
3104 set(<variable> <value1> ... <valueN>)
3105
3106 In this case <variable> is set to a semicolon separated list of
3107 values.
3108
3109
3110 <variable> can be an environment variable such as:
3111
3112
3113 set( ENV{PATH} /home/martink )
3114
3115 in which case the environment variable will be set.
3116
3117
3118 *** Variable types in CMake ***
3119
3120
3121 In CMake there are two types of variables: normal variables and
3122 cache variables. Normal variables are meant for the internal use
3123 of the script (just like variables in most programming lan‐
3124 guages); they are not persisted across CMake runs. Cache vari‐
3125 ables (unless set with INTERNAL) are mostly intended for config‐
3126 uration settings where the first CMake run determines a suitable
3127 default value, which the user can then override, by editing the
3128 cache with tools such as ccmake or cmake-gui. Cache variables
3129 are stored in the CMake cache file, and are persisted across
3130 CMake runs.
3131
3132
3133 Both types can exist at the same time with the same name but
3134 different values. When ${FOO} is evaluated, CMake first looks
3135 for a normal variable 'FOO' in scope and uses it if set. If and
3136 only if no normal variable exists then it falls back to the
3137 cache variable 'FOO'.
3138
3139
3140 Some examples:
3141
3142
3143 The code 'set(FOO "x")' sets the normal variable 'FOO'. It does
3144 not touch the cache, but it will hide any existing cache value
3145 'FOO'.
3146
3147
3148 The code 'set(FOO "x" CACHE ...)' checks for 'FOO' in the cache,
3149 ignoring any normal variable of the same name. If 'FOO' is in
3150 the cache then nothing happens to either the normal variable or
3151 the cache variable. If 'FOO' is not in the cache, then it is
3152 added to the cache.
3153
3154
3155 Finally, whenever a cache variable is added or modified by a
3156 command, CMake also *removes* the normal variable of the same
3157 name from the current scope so that an immediately following
3158 evaluation of it will expose the newly cached value.
3159
3160
3161 Normally projects should avoid using normal and cache variables
3162 of the same name, as this interaction can be hard to follow.
3163 However, in some situations it can be useful. One example (used
3164 by some projects):
3165
3166
3167 A project has a subproject in its source tree. The child project
3168 has its own CMakeLists.txt, which is included from the parent
3169 CMakeLists.txt using add_subdirectory(). Now, if the parent and
3170 the child project provide the same option (for example a com‐
3171 piler option), the parent gets the first chance to add a
3172 user-editable option to the cache. Normally, the child would
3173 then use the same value that the parent uses. However, it may be
3174 necessary to hard-code the value for the child project's option
3175 while still allowing the user to edit the value used by the par‐
3176 ent project. The parent project can achieve this simply by set‐
3177 ting a normal variable with the same name as the option in a
3178 scope sufficient to hide the option's cache variable from the
3179 child completely. The parent has already set the cache variable,
3180 so the child's set(...CACHE...) will do nothing, and evaluating
3181 the option variable will use the value from the normal variable,
3182 which hides the cache variable.
3183
3184
3185 set_directory_properties
3186 Set a property of the directory.
3187
3188 set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
3189
3190 Set a property for the current directory and subdirectories. If
3191 the property is not found, CMake will report an error. The prop‐
3192 erties include: INCLUDE_DIRECTORIES, LINK_DIRECTORIES,
3193 INCLUDE_REGULAR_EXPRESSION, and ADDITIONAL_MAKE_CLEAN_FILES.
3194 ADDITIONAL_MAKE_CLEAN_FILES is a list of files that will be
3195 cleaned as a part of "make clean" stage.
3196
3197
3198 set_property
3199 Set a named property in a given scope.
3200
3201 set_property(<GLOBAL |
3202 DIRECTORY [dir] |
3203 TARGET [target1 [target2 ...]] |
3204 SOURCE [src1 [src2 ...]] |
3205 TEST [test1 [test2 ...]] |
3206 CACHE [entry1 [entry2 ...]]>
3207 [APPEND] [APPEND_STRING]
3208 PROPERTY <name> [value1 [value2 ...]])
3209
3210 Set one property on zero or more objects of a scope. The first
3211 argument determines the scope in which the property is set. It
3212 must be one of the following:
3213
3214
3215 GLOBAL scope is unique and does not accept a name.
3216
3217
3218 DIRECTORY scope defaults to the current directory but another
3219 directory (already processed by CMake) may be named by full or
3220 relative path.
3221
3222
3223 TARGET scope may name zero or more existing targets.
3224
3225
3226 SOURCE scope may name zero or more source files. Note that
3227 source file properties are visible only to targets added in the
3228 same directory (CMakeLists.txt).
3229
3230
3231 TEST scope may name zero or more existing tests.
3232
3233
3234 CACHE scope must name zero or more cache existing entries.
3235
3236
3237 The required PROPERTY option is immediately followed by the name
3238 of the property to set. Remaining arguments are used to compose
3239 the property value in the form of a semicolon-separated list.
3240 If the APPEND option is given the list is appended to any exist‐
3241 ing property value.If the APPEND_STRING option is given the
3242 string is append to any existing property value as string, i.e.
3243 it results in a longer string and not a list of strings.
3244
3245
3246 site_name
3247 Set the given variable to the name of the computer.
3248
3249 site_name(variable)
3250
3251
3252 string String operations.
3253
3254 string(REGEX MATCH <regular_expression>
3255 <output variable> <input> [<input>...])
3256 string(REGEX MATCHALL <regular_expression>
3257 <output variable> <input> [<input>...])
3258 string(REGEX REPLACE <regular_expression>
3259 <replace_expression> <output variable>
3260 <input> [<input>...])
3261 string(REPLACE <match_string>
3262 <replace_string> <output variable>
3263 <input> [<input>...])
3264 string(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512>
3265 <output variable> <input>)
3266 string(COMPARE EQUAL <string1> <string2> <output variable>)
3267 string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
3268 string(COMPARE LESS <string1> <string2> <output variable>)
3269 string(COMPARE GREATER <string1> <string2> <output variable>)
3270 string(ASCII <number> [<number> ...] <output variable>)
3271 string(CONFIGURE <string1> <output variable>
3272 [@ONLY] [ESCAPE_QUOTES])
3273 string(TOUPPER <string1> <output variable>)
3274 string(TOLOWER <string1> <output variable>)
3275 string(LENGTH <string> <output variable>)
3276 string(SUBSTRING <string> <begin> <length> <output variable>)
3277 string(STRIP <string> <output variable>)
3278 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
3279 [RANDOM_SEED <seed>] <output variable>)
3280 string(FIND <string> <substring> <output variable> [REVERSE])
3281 string(TIMESTAMP <output variable> [<format string>] [UTC])
3282 string(MAKE_C_IDENTIFIER <input string> <output variable>)
3283
3284 REGEX MATCH will match the regular expression once and store the
3285 match in the output variable.
3286
3287
3288 REGEX MATCHALL will match the regular expression as many times
3289 as possible and store the matches in the output variable as a
3290 list.
3291
3292
3293 REGEX REPLACE will match the regular expression as many times as
3294 possible and substitute the replacement expression for the match
3295 in the output. The replace expression may refer to paren-delim‐
3296 ited subexpressions of the match using \1, \2, ..., \9. Note
3297 that two backslashes (\\1) are required in CMake code to get a
3298 backslash through argument parsing.
3299
3300
3301 REPLACE will replace all occurrences of match_string in the
3302 input with replace_string and store the result in the output.
3303
3304
3305 MD5, SHA1, SHA224, SHA256, SHA384, and SHA512 will compute a
3306 cryptographic hash of the input string.
3307
3308
3309 COMPARE EQUAL/NOTEQUAL/LESS/GREATER will compare the strings and
3310 store true or false in the output variable.
3311
3312
3313 ASCII will convert all numbers into corresponding ASCII charac‐
3314 ters.
3315
3316
3317 CONFIGURE will transform a string like CONFIGURE_FILE transforms
3318 a file.
3319
3320
3321 TOUPPER/TOLOWER will convert string to upper/lower characters.
3322
3323
3324 LENGTH will return a given string's length.
3325
3326
3327 SUBSTRING will return a substring of a given string. If length
3328 is -1 the remainder of the string starting at begin will be
3329 returned.
3330
3331
3332 STRIP will return a substring of a given string with leading and
3333 trailing spaces removed.
3334
3335
3336 RANDOM will return a random string of given length consisting of
3337 characters from the given alphabet. Default length is 5 charac‐
3338 ters and default alphabet is all numbers and upper and lower
3339 case letters. If an integer RANDOM_SEED is given, its value
3340 will be used to seed the random number generator.
3341
3342
3343 FIND will return the position where the given substring was
3344 found in the supplied string. If the REVERSE flag was used, the
3345 command will search for the position of the last occurrence of
3346 the specified substring.
3347
3348
3349 The following characters have special meaning in regular expres‐
3350 sions:
3351
3352
3353 ^ Matches at beginning of input
3354 $ Matches at end of input
3355 . Matches any single character
3356 [ ] Matches any character(s) inside the brackets
3357 [^ ] Matches any character(s) not inside the brackets
3358 - Inside brackets, specifies an inclusive range between
3359 characters on either side e.g. [a-f] is [abcdef]
3360 To match a literal - using brackets, make it the first
3361 or the last character e.g. [+*/-] matches basic
3362 mathematical operators.
3363 * Matches preceding pattern zero or more times
3364 + Matches preceding pattern one or more times
3365 ? Matches preceding pattern zero or once only
3366 | Matches a pattern on either side of the |
3367 () Saves a matched subexpression, which can be referenced
3368 in the REGEX REPLACE operation. Additionally it is saved
3369 by all regular expression-related commands, including
3370 e.g. if( MATCHES ), in the variables CMAKE_MATCH_(0..9).
3371
3372 *, + and ? have higher precedence than concatenation. | has
3373 lower precedence than concatenation. This means that the regular
3374 expression "^ab+d$" matches "abbd" but not "ababd", and the reg‐
3375 ular expression "^(ab|cd)$" matches "ab" but not "abd".
3376
3377
3378 TIMESTAMP will write a string representation of the current date
3379 and/or time to the output variable.
3380
3381
3382 Should the command be unable to obtain a timestamp the output
3383 variable will be set to the empty string "".
3384
3385
3386 The optional UTC flag requests the current date/time representa‐
3387 tion to be in Coordinated Universal Time (UTC) rather than local
3388 time.
3389
3390
3391 The optional <format string> may contain the following format
3392 specifiers:
3393
3394
3395 %d The day of the current month (01-31).
3396 %H The hour on a 24-hour clock (00-23).
3397 %I The hour on a 12-hour clock (01-12).
3398 %j The day of the current year (001-366).
3399 %m The month of the current year (01-12).
3400 %M The minute of the current hour (00-59).
3401 %S The second of the current minute.
3402 60 represents a leap second. (00-60)
3403 %U The week number of the current year (00-53).
3404 %w The day of the current week. 0 is Sunday. (0-6)
3405 %y The last two digits of the current year (00-99)
3406 %Y The current year.
3407
3408 Unknown format specifiers will be ignored and copied to the out‐
3409 put as-is.
3410
3411
3412 If no explicit <format string> is given it will default to:
3413
3414
3415 %Y-%m-%dT%H:%M:%S for local time.
3416 %Y-%m-%dT%H:%M:%SZ for UTC.
3417
3418 MAKE_C_IDENTIFIER will write a string which can be used as an
3419 identifier in C.
3420
3421
3422 unset Unset a variable, cache variable, or environment variable.
3423
3424 unset(<variable> [CACHE])
3425
3426 Removes the specified variable causing it to become undefined.
3427 If CACHE is present then the variable is removed from the cache
3428 instead of the current scope.
3429
3430
3431 <variable> can be an environment variable such as:
3432
3433
3434 unset(ENV{LD_LIBRARY_PATH})
3435
3436 in which case the variable will be removed from the current
3437 environment.
3438
3439
3440 use_mangled_mesa
3441 Copy mesa headers for use in combination with system GL.
3442
3443 use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
3444
3445 The path to mesa includes, should contain gl_mangle.h. The mesa
3446 headers are copied to the specified output directory. This
3447 allows mangled mesa headers to override other GL headers by
3448 being added to the include directory path earlier.
3449
3450
3451 variable_watch
3452 Watch the CMake variable for change.
3453
3454 variable_watch(<variable name> [<command to execute>])
3455
3456 If the specified variable changes, the message will be printed
3457 about the variable being changed. If the command is specified,
3458 the command will be executed. The command will receive the fol‐
3459 lowing arguments: COMMAND(<variable> <access> <value> <current
3460 list file> <stack>)
3461
3462
3463 while Evaluate a group of commands while a condition is true
3464
3465 while(condition)
3466 COMMAND1(ARGS ...)
3467 COMMAND2(ARGS ...)
3468 ...
3469 endwhile(condition)
3470
3471 All commands between while and the matching endwhile are
3472 recorded without being invoked. Once the endwhile is evaluated,
3473 the recorded list of commands is invoked as long as the condi‐
3474 tion is true. The condition is evaluated using the same logic as
3475 the if command.
3476
3477
3478 write_file
3479 Deprecated. Use the file(WRITE ) command instead.
3480
3481 write_file(filename "message to write"... [APPEND])
3482
3483 The first argument is the file name, the rest of the arguments
3484 are messages to write. If the argument APPEND is specified, then
3485 the message will be appended.
3486
3487
3488 NOTE 1: file(WRITE ... and file(APPEND ... do exactly the same
3489 as this one but add some more functionality.
3490
3491
3492 NOTE 2: When using write_file the produced file cannot be used
3493 as an input to CMake (CONFIGURE_FILE, source file ...) because
3494 it will lead to an infinite loop. Use configure_file if you want
3495 to generate input files to CMake.
3496
3497
3499 CMake Properties - Properties supported by CMake, the Cross-Platform Makefile Generator.
3500
3501
3502 This is the documentation for the properties supported by CMake. Prop‐
3503 erties can have different scopes. They can either be assigned to a
3504 source file, a directory, a target or globally to CMake. By modifying
3505 the values of properties the behaviour of the build system can be cus‐
3506 tomized.
3507
3508
3510 CMake Compatibility Listfile Commands - Obsolete commands supported by CMake for compatibility.
3511
3512
3513 This is the documentation for now obsolete listfile commands from pre‐
3514 vious CMake versions, which are still supported for compatibility rea‐
3515 sons. You should instead use the newer, faster and shinier new com‐
3516 mands. ;-)
3517
3518
3521 Copyright 2000-2012 Kitware, Inc., Insight Software Consortium. All
3522 rights reserved.
3523
3524
3525 Redistribution and use in source and binary forms, with or without mod‐
3526 ification, are permitted provided that the following conditions are
3527 met:
3528
3529
3530 Redistributions of source code must retain the above copyright notice,
3531 this list of conditions and the following disclaimer.
3532
3533
3534 Redistributions in binary form must reproduce the above copyright
3535 notice, this list of conditions and the following disclaimer in the
3536 documentation and/or other materials provided with the distribution.
3537
3538
3539 Neither the names of Kitware, Inc., the Insight Software Consortium,
3540 nor the names of their contributors may be used to endorse or promote
3541 products derived from this software without specific prior written per‐
3542 mission.
3543
3544
3545 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
3546 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
3547 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC‐
3548 ULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
3549 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
3550 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
3551 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
3552 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
3553 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
3554 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
3555 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
3556
3557
3559 cmake(1), ccmake(1)
3560
3561
3562 The following resources are available to get help using CMake:
3563
3564
3565 Home Page
3566 http://www.cmake.org
3567
3568 The primary starting point for learning about CMake.
3569
3570
3571 Frequently Asked Questions
3572 http://www.cmake.org/Wiki/CMake_FAQ
3573
3574 A Wiki is provided containing answers to frequently asked ques‐
3575 tions.
3576
3577
3578 Online Documentation
3579 http://www.cmake.org/HTML/Documentation.html
3580
3581 Links to available documentation may be found on this web page.
3582
3583
3584 Mailing List
3585 http://www.cmake.org/HTML/MailingLists.html
3586
3587 For help and discussion about using cmake, a mailing list is
3588 provided at cmake@cmake.org. The list is member-post-only but
3589 one may sign up on the CMake web page. Please first read the
3590 full documentation at http://www.cmake.org before posting ques‐
3591 tions to the list.
3592
3593
3595 This manual page was generated by the "--help-man" option.
3596
3597
3598
3599
3600ctest 2.8.12.2 October 15, 2014 ctest(1)