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