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