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