1CTEST(1) CMake CTEST(1)
2
6 ctest - CTest Command-Line Reference
7 Contents
9 · ctest(1)
10 · Synopsis
12 · Description
14 · Options
16 · Label and Subproject Summary
18 · Build and Test Mode
20 · Dashboard Client
22 · Dashboard Client Steps
24 · Dashboard Client Modes
26 · Dashboard Client via CTest Command-Line
28 · Dashboard Client via CTest Script
30 · Dashboard Client Configuration
32 · CTest Start Step
34 · CTest Update Step
36 · CTest Configure Step
38 · CTest Build Step
40 · CTest Test Step
42 · CTest Coverage Step
44 · CTest MemCheck Step
46 · CTest Submit Step
48 · See Also
50
52 ctest [<options>]
53 ctest <path-to-source> <path-to-build> --build-generator <generator>
54 [<options>...] [-- <build-options>...] [--test-command <test>]
55 ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>)
56 [-- <dashboard-options>...]
57
59 The “ctest” executable is the CMake test driver program. CMake-gener‐
60 ated build trees created for projects that use the ENABLE_TESTING and
61 ADD_TEST commands have testing support. This program will run the
62 tests and report results.
63
65 -C <cfg>, --build-config <cfg>
66 Choose configuration to test.
67 Some CMake-generated build trees can have multiple build config‐
69 urations in the same tree. This option can be used to specify
70 which one should be tested. Example configurations are “Debug”
71 and “Release”.
72 -V,--verbose
74 Enable verbose output from tests.
75 Test output is normally suppressed and only summary information
77 is displayed. This option will show all test output.
78 -VV,--extra-verbose
80 Enable more verbose output from tests.
81 Test output is normally suppressed and only summary information
83 is displayed. This option will show even more test output.
84 --debug
86 Displaying more verbose internals of CTest.
87 This feature will result in a large number of output that is
89 mostly useful for debugging dashboard problems.
90 --output-on-failure
92 Output anything outputted by the test program if the test should
93 fail. This option can also be enabled by setting the environ‐
94 ment variable CTEST_OUTPUT_ON_FAILURE.
95 -F Enable failover.
97 This option allows CTest to resume a test set execution that was
99 previously interrupted. If no interruption occurred, the -F
100 option will have no effect.
101 -j <jobs>, --parallel <jobs>
103 Run the tests in parallel using the given number of jobs.
104 This option tells CTest to run the tests in parallel using given
106 number of jobs. This option can also be set by setting the envi‐
107 ronment variable CTEST_PARALLEL_LEVEL.
108 This option can be used with the PROCESSORS test property.
110 See Label and Subproject Summary.
112 --test-load <level>
114 While running tests in parallel (e.g. with -j), try not to start
115 tests when they may cause the CPU load to pass above a given
116 threshold.
117 When ctest is run as a Dashboard Client this sets the TestLoad
119 option of the CTest Test Step.
120 -Q,--quiet
122 Make CTest quiet.
123 This option will suppress all the output. The output log file
125 will still be generated if the --output-log is specified.
126 Options such as --verbose, --extra-verbose, and --debug are
127 ignored if --quiet is specified.
128 -O <file>, --output-log <file>
130 Output to log file.
131 This option tells CTest to write all its output to a log file.
133 -N,--show-only
135 Disable actual execution of tests.
136 This option tells CTest to list the tests that would be run but
138 not actually run them. Useful in conjunction with the -R and -E
139 options.
140 -L <regex>, --label-regex <regex>
142 Run tests with labels matching regular expression.
143 This option tells CTest to run only the tests whose labels match
145 the given regular expression.
146 -R <regex>, --tests-regex <regex>
148 Run tests matching regular expression.
149 This option tells CTest to run only the tests whose names match
151 the given regular expression.
152 -E <regex>, --exclude-regex <regex>
154 Exclude tests matching regular expression.
155 This option tells CTest to NOT run the tests whose names match
157 the given regular expression.
158 -LE <regex>, --label-exclude <regex>
160 Exclude tests with labels matching regular expression.
161 This option tells CTest to NOT run the tests whose labels match
163 the given regular expression.
164 -FA <regex>, --fixture-exclude-any <regex>
166 Exclude fixtures matching <regex> from automatically adding any
167 tests to the test set.
168 If a test in the set of tests to be executed requires a particu‐
170 lar fixture, that fixture’s setup and cleanup tests would nor‐
171 mally be added to the test set automatically. This option pre‐
172 vents adding setup or cleanup tests for fixtures matching the
173 <regex>. Note that all other fixture behavior is retained,
174 including test dependencies and skipping tests that have fixture
175 setup tests that fail.
176 -FS <regex>, --fixture-exclude-setup <regex>
178 Same as -FA except only matching setup tests are excluded.
179 -FC <regex>, --fixture-exclude-cleanup <regex>
181 Same as -FA except only matching cleanup tests are excluded.
182 -D <dashboard>, --dashboard <dashboard>
184 Execute dashboard test.
185 This option tells CTest to act as a CDash client and perform a
187 dashboard test. All tests are <Mode><Test>, where Mode can be
188 Experimental, Nightly, and Continuous, and Test can be Start,
189 Update, Configure, Build, Test, Coverage, and Submit.
190 See Dashboard Client.
192 -D <var>:<type>=<value>
194 Define a variable for script mode.
195 Pass in variable values on the command line. Use in conjunction
197 with -S to pass variable values to a dashboard script. Parsing
198 -D arguments as variable values is only attempted if the value
199 following -D does not match any of the known dashboard types.
200 -M <model>, --test-model <model>
202 Sets the model for a dashboard.
203 This option tells CTest to act as a CDash client where the
205 <model> can be Experimental, Nightly, and Continuous. Combining
206 -M and -T is similar to -D.
207 See Dashboard Client.
209 -T <action>, --test-action <action>
211 Sets the dashboard action to perform.
212 This option tells CTest to act as a CDash client and perform
214 some action such as start, build, test etc. See Dashboard Client
215 Steps for the full list of actions. Combining -M and -T is sim‐
216 ilar to -D.
217 See Dashboard Client.
219 -S <script>, --script <script>
221 Execute a dashboard for a configuration.
222 This option tells CTest to load in a configuration script which
224 sets a number of parameters such as the binary and source direc‐
225 tories. Then CTest will do what is required to create and run a
226 dashboard. This option basically sets up a dashboard and then
227 runs ctest -D with the appropriate options.
228 See Dashboard Client.
230 -SP <script>, --script-new-process <script>
232 Execute a dashboard for a configuration.
233 This option does the same operations as -S but it will do them
235 in a separate process. This is primarily useful in cases where
236 the script may modify the environment and you do not want the
237 modified environment to impact other -S scripts.
238 See Dashboard Client.
240 -I [Start,End,Stride,test#,test#|Test file], --tests-information
242 Run a specific number of tests by number.
243 This option causes CTest to run tests starting at number Start,
245 ending at number End, and incrementing by Stride. Any addi‐
246 tional numbers after Stride are considered individual test num‐
247 bers. Start, End,or stride can be empty. Optionally a file can
248 be given that contains the same syntax as the command line.
249 -U, --union
251 Take the Union of -I and -R.
252 When both -R and -I are specified by default the intersection of
254 tests are run. By specifying -U the union of tests is run
255 instead.
256 --rerun-failed
258 Run only the tests that failed previously.
259 This option tells CTest to perform only the tests that failed
261 during its previous run. When this option is specified, CTest
262 ignores all other options intended to modify the list of tests
263 to run (-L, -R, -E, -LE, -I, etc). In the event that CTest runs
264 and no tests fail, subsequent calls to CTest with the
265 --rerun-failed option will run the set of tests that most
266 recently failed (if any).
267 --repeat-until-fail <n>
269 Require each test to run <n> times without failing in order to
270 pass.
271 This is useful in finding sporadic failures in test cases.
273 --max-width <width>
275 Set the max width for a test name to output.
276 Set the maximum width for each test name to show in the output.
278 This allows the user to widen the output to avoid clipping the
279 test name which can be very annoying.
280 --interactive-debug-mode [0|1]
282 Set the interactive mode to 0 or 1.
283 This option causes CTest to run tests in either an interactive
285 mode or a non-interactive mode. On Windows this means that in
286 non-interactive mode, all system debug pop up windows are
287 blocked. In dashboard mode (Experimental, Nightly, Continuous),
288 the default is non-interactive. When just running tests not for
289 a dashboard the default is to allow popups and interactive
290 debugging.
291 --no-label-summary
293 Disable timing summary information for labels.
294 This option tells CTest not to print summary information for
296 each label associated with the tests run. If there are no
297 labels on the tests, nothing extra is printed.
298 See Label and Subproject Summary.
300 --no-subproject-summary
302 Disable timing summary information for subprojects.
303 This option tells CTest not to print summary information for
305 each subproject associated with the tests run. If there are no
306 subprojects on the tests, nothing extra is printed.
307 See Label and Subproject Summary.
309 --build-and-test See Build and Test Mode.
311 --test-output-size-passed <size>
313 Limit the output for passed tests to <size> bytes.
314 --test-output-size-failed <size>
316 Limit the output for failed tests to <size> bytes.
317 --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 --force-new-ctest-process
325 Run child CTest instances as new processes.
326 By default CTest will run child CTest instances within the same
328 process. If this behavior is not desired, this argument will
329 enforce new processes for child CTest processes.
330 --schedule-random
332 Use a random order for scheduling tests.
333 This option will run the tests in a random order. It is com‐
335 monly used to detect implicit dependencies in a test suite.
336 --submit-index
338 Legacy option for old Dart2 dashboard server feature. Do not
339 use.
340 --timeout <seconds>
342 Set a global timeout on all tests.
343 This option will set a global timeout on all tests that do not
345 already have a timeout set on them.
346 --stop-time <time>
348 Set a time at which all tests should stop running.
349 Set a real time of day at which all tests should timeout. Exam‐
351 ple: 7:00:00 -0400. Any time format understood by the curl date
352 parser is accepted. Local time is assumed if no timezone is
353 specified.
354 --print-labels
356 Print all available test labels.
357 This option will not run any tests, it will simply print the
359 list of all labels associated with the test set.
360 --help,-help,-usage,-h,-H,/?
362 Print usage information and exit.
363 Usage describes the basic command line interface and its
365 options.
366 --version,-version,/V [<f>]
368 Show program name/version banner and exit.
369 If a file is specified, the version is written into it. The
371 help is printed to a named <f>ile if given.
372 --help-full [<f>]
374 Print all help manuals and exit.
375 All manuals are printed in a human-readable text format. The
377 help is printed to a named <f>ile if given.
378 --help-manual <man> [<f>]
380 Print one help manual and exit.
381 The specified manual is printed in a human-readable text format.
383 The help is printed to a named <f>ile if given.
384 --help-manual-list [<f>]
386 List help manuals available and exit.
387 The list contains all manuals for which help may be obtained by
389 using the --help-manual option followed by a manual name. The
390 help is printed to a named <f>ile if given.
391 --help-command <cmd> [<f>]
393 Print help for one command and exit.
394 The cmake-commands(7) manual entry for <cmd> is printed in a
396 human-readable text format. The help is printed to a named
397 <f>ile if given.
398 --help-command-list [<f>]
400 List commands with help available and exit.
401 The list contains all commands for which help may be obtained by
403 using the --help-command option followed by a command name. The
404 help is printed to a named <f>ile if given.
405 --help-commands [<f>]
407 Print cmake-commands manual and exit.
408 The cmake-commands(7) manual is printed in a human-readable text
410 format. The help is printed to a named <f>ile if given.
411 --help-module <mod> [<f>]
413 Print help for one module and exit.
414 The cmake-modules(7) manual entry for <mod> is printed in a
416 human-readable text format. The help is printed to a named
417 <f>ile if given.
418 --help-module-list [<f>]
420 List modules with help available and exit.
421 The list contains all modules for which help may be obtained by
423 using the --help-module option followed by a module name. The
424 help is printed to a named <f>ile if given.
425 --help-modules [<f>]
427 Print cmake-modules manual and exit.
428 The cmake-modules(7) manual is printed in a human-readable text
430 format. The help is printed to a named <f>ile if given.
431 --help-policy <cmp> [<f>]
433 Print help for one policy and exit.
434 The cmake-policies(7) manual entry for <cmp> is printed in a
436 human-readable text format. The help is printed to a named
437 <f>ile if given.
438 --help-policy-list [<f>]
440 List policies with help available and exit.
441 The list contains all policies for which help may be obtained by
443 using the --help-policy option followed by a policy name. The
444 help is printed to a named <f>ile if given.
445 --help-policies [<f>]
447 Print cmake-policies manual and exit.
448 The cmake-policies(7) manual is printed in a human-readable text
450 format. The help is printed to a named <f>ile if given.
451 --help-property <prop> [<f>]
453 Print help for one property and exit.
454 The cmake-properties(7) manual entries for <prop> are printed in
456 a human-readable text format. The help is printed to a named
457 <f>ile if given.
458 --help-property-list [<f>]
460 List properties with help available and exit.
461 The list contains all properties for which help may be obtained
463 by using the --help-property option followed by a property name.
464 The help is printed to a named <f>ile if given.
465 --help-properties [<f>]
467 Print cmake-properties manual and exit.
468 The cmake-properties(7) manual is printed in a human-readable
470 text format. The help is printed to a named <f>ile if given.
471 --help-variable <var> [<f>]
473 Print help for one variable and exit.
474 The cmake-variables(7) manual entry for <var> is printed in a
476 human-readable text format. The help is printed to a named
477 <f>ile if given.
478 --help-variable-list [<f>]
480 List variables with help available and exit.
481 The list contains all variables for which help may be obtained
483 by using the --help-variable option followed by a variable name.
484 The help is printed to a named <f>ile if given.
485 --help-variables [<f>]
487 Print cmake-variables manual and exit.
488 The cmake-variables(7) manual is printed in a human-readable
490 text format. The help is printed to a named <f>ile if given.
491
493 CTest prints timing summary information for each label and subproject
494 associated with the tests run. The label time summary will not include
495 labels that are mapped to subprojects.
496 When the PROCESSORS test property is set, CTest will display a weighted
498 test timing result in label and subproject summaries. The time is
499 reported with sec*proc instead of just sec.
500 The weighted time summary reported for each label or subproject j is
502 computed as:
503 Weighted Time Summary for Label/Subproject j =
505 sum(raw_test_time[j,i] * num_processors[j,i], i=1...num_tests[j])
506 for labels/subprojects j=1...total
508 where:
510 · raw_test_time[j,i]: Wall-clock time for the ith test for the jth
512 label or subproject
513 · num_processors[j,i]: Value of the CTest PROCESSORS property for the
515 ith test for the jth label or subproject
516 · num_tests[j]: Number of tests associated with the jth label or sub‐
518 project
519 · total: Total number of labels or subprojects that have at least one
521 test run
522 Therefore, the weighted time summary for each label or subproject rep‐
524 resents the amount of time that CTest gave to run the tests for each
525 label or subproject and gives a good representation of the total
526 expense of the tests for each label or subproject when compared to
527 other labels or subprojects.
528 For example, if “SubprojectA” showed “100 sec*proc” and “SubprojectB”
530 showed “10 sec*proc”, then CTest allocated approximately 10 times the
531 CPU/core time to run the tests for “SubprojectA” than for “SubprojectB”
532 (e.g. so if effort is going to be expended to reduce the cost of the
533 test suite for the whole project, then reducing the cost of the test
534 suite for “SubprojectA” would likely have a larger impact than effort
535 to reduce the cost of the test suite for “SubprojectB”).
536
538 CTest provides a command-line signature to to configure (i.e. run
539 cmake on), build, and or execute a test:
540 ctest --build-and-test <path-to-source> <path-to-build>
542 --build-generator <generator> [<options>...] [-- <build-options>...]
543 [--test-command <test>]
544 The configure and test steps are optional. The arguments to this com‐
546 mand line are the source and binary directories. The --build-generator
547 option must be provided to use --build-and-test. If --test-command is
548 specified then that will be run after the build is complete. Other
549 options that affect this mode include:
550 --build-target
552 Specify a specific target to build.
553 If left out the all target is built.
555 --build-nocmake
557 Run the build without running cmake first.
558 Skip the cmake step.
560 --build-run-dir
562 Specify directory to run programs from.
563 Directory where programs will be after it has been compiled.
565 --build-two-config
567 Run CMake twice.
568 --build-exe-dir
570 Specify the directory for the executable.
571 --build-generator
573 Specify the generator to use. See the cmake-generators(7) man‐
574 ual.
575 --build-generator-platform
577 Specify the generator-specific platform.
578 --build-generator-toolset
580 Specify the generator-specific toolset.
581 --build-project
583 Specify the name of the project to build.
584 --build-makeprogram
586 Override the make program chosen by CTest with a given one.
587 --build-noclean
589 Skip the make clean step.
590 --build-config-sample
592 A sample executable to use to determine the configuration that
593 should be used. e.g. Debug/Release/etc.
594 --build-options
596 Add extra options to the build step.
597 This option must be the last option with the exception of
599 --test-command
600 --test-command
602 The test to run with the --build-and-test option.
603 --test-timeout
605 The time limit in seconds
606
608 CTest can operate as a client for the CDash software quality dashboard
609 application. As a dashboard client, CTest performs a sequence of steps
610 to configure, build, and test software, and then submits the results to
611 a CDash server. The command-line signature used to submit to CDash is:
612 ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>)
614 [-- <dashboard-options>...]
615 Options for Dashboard Client include:
617 --track <track>
619 Specify the track to submit dashboard to
620 Submit dashboard to specified track instead of default one. By
622 default, the dashboard is submitted to Nightly, Experimental, or
623 Continuous track, but by specifying this option, the track can
624 be arbitrary.
625 -A <file>, --add-notes <file>
627 Add a notes file with submission.
628 This option tells CTest to include a notes file when submitting
630 dashboard.
631 --tomorrow-tag
633 Nightly or experimental starts with next day tag.
634 This is useful if the build will not finish in one day.
636 --extra-submit <file>[;<file>]
638 Submit extra files to the dashboard.
639 This option will submit extra files to the dashboard.
641 --http1.0
643 Submit using HTTP 1.0.
644 This option will force CTest to use HTTP 1.0 to submit files to
646 the dashboard, instead of HTTP 1.1.
647 --no-compress-output
649 Do not compress test output when submitting.
650 This flag will turn off automatic compression of test output.
652 Use this to maintain compatibility with an older version of
653 CDash which doesn’t support compressed test output.
654 Dashboard Client Steps
656 CTest defines an ordered list of testing steps of which some or all may
657 be run as a dashboard client:
658 Start Start a new dashboard submission to be composed of results
660 recorded by the following steps. See the CTest Start Step sec‐
661 tion below.
662 Update Update the source tree from its version control repository.
664 Record the old and new versions and the list of updated source
665 files. See the CTest Update Step section below.
666 Configure
668 Configure the software by running a command in the build tree.
669 Record the configuration output log. See the CTest Configure
670 Step section below.
671 Build Build the software by running a command in the build tree.
673 Record the build output log and detect warnings and errors. See
674 the CTest Build Step section below.
675 Test Test the software by loading a CTestTestfile.cmake from the
677 build tree and executing the defined tests. Record the output
678 and result of each test. See the CTest Test Step section below.
679 Coverage
681 Compute coverage of the source code by running a coverage analy‐
682 sis tool and recording its output. See the CTest Coverage Step
683 section below.
684 MemCheck
686 Run the software test suite through a memory check tool. Record
687 the test output, results, and issues reported by the tool. See
688 the CTest MemCheck Step section below.
689 Submit Submit results recorded from other testing steps to the software
691 quality dashboard server. See the CTest Submit Step section
692 below.
693 Dashboard Client Modes
695 CTest defines three modes of operation as a dashboard client:
696 Nightly
698 This mode is intended to be invoked once per day, typically at
699 night. It enables the Start, Update, Configure, Build, Test,
700 Coverage, and Submit steps by default. Selected steps run even
701 if the Update step reports no changes to the source tree.
702 Continuous
704 This mode is intended to be invoked repeatedly throughout the
705 day. It enables the Start, Update, Configure, Build, Test, Cov‐
706 erage, and Submit steps by default, but exits after the Update
707 step if it reports no changes to the source tree.
708 Experimental
710 This mode is intended to be invoked by a developer to test local
711 changes. It enables the Start, Configure, Build, Test, Cover‐
712 age, and Submit steps by default.
713 Dashboard Client via CTest Command-Line
715 CTest can perform testing on an already-generated build tree. Run the
716 ctest command with the current working directory set to the build tree
717 and use one of these signatures:
718 ctest -D <mode>[<step>]
720 ctest -M <mode> [ -T <step> ]...
721 The <mode> must be one of the above Dashboard Client Modes, and each
723 <step> must be one of the above Dashboard Client Steps.
724 CTest reads the Dashboard Client Configuration settings from a file in
726 the build tree called either CTestConfiguration.ini or DartConfigura‐
727 tion.tcl (the names are historical). The format of the file is:
728 # Lines starting in '#' are comments.
730 # Other non-blank lines are key-value pairs.
731 <setting>: <value>
732 where <setting> is the setting name and <value> is the setting value.
734 In build trees generated by CMake, this configuration file is generated
736 by the CTest module if included by the project. The module uses vari‐
737 ables to obtain a value for each setting as documented with the set‐
738 tings below.
739 Dashboard Client via CTest Script
741 CTest can perform testing driven by a cmake-language(7) script that
742 creates and maintains the source and build tree as well as performing
743 the testing steps. Run the ctest command with the current working
744 directory set outside of any build tree and use one of these signa‐
745 tures:
746 ctest -S <script>
748 ctest -SP <script>
749 The <script> file must call CTest Commands commands to run testing
751 steps explicitly as documented below. The commands obtain Dashboard
752 Client Configuration settings from their arguments or from variables
753 set in the script.
754
756 The Dashboard Client Steps may be configured by named settings as docu‐
757 mented in the following sections.
758 CTest Start Step
760 Start a new dashboard submission to be composed of results recorded by
761 the following steps.
762 In a CTest Script, the ctest_start() command runs this step. Arguments
764 to the command may specify some of the step settings. The command
765 first runs the command-line specified by the CTEST_CHECKOUT_COMMAND
766 variable, if set, to initialize the source directory.
767 Configuration settings include:
769 BuildDirectory
771 The full path to the project build tree.
772 · CTest Script variable: CTEST_BINARY_DIRECTORY
774 · CTest module variable: PROJECT_BINARY_DIR
776 SourceDirectory
778 The full path to the project source tree.
779 · CTest Script variable: CTEST_SOURCE_DIRECTORY
781 · CTest module variable: PROJECT_SOURCE_DIR
783 CTest Update Step
785 In a CTest Script, the ctest_update() command runs this step. Argu‐
786 ments to the command may specify some of the step settings.
787 Configuration settings to specify the version control tool include:
789 BZRCommand
791 bzr command-line tool to use if source tree is managed by
792 Bazaar.
793 · CTest Script variable: CTEST_BZR_COMMAND
795 · CTest module variable: none
797 BZRUpdateOptions
799 Command-line options to the BZRCommand when updating the source.
800 · CTest Script variable: CTEST_BZR_UPDATE_OPTIONS
802 · CTest module variable: none
804 CVSCommand
806 cvs command-line tool to use if source tree is managed by CVS.
807 · CTest Script variable: CTEST_CVS_COMMAND
809 · CTest module variable: CVSCOMMAND
811 CVSUpdateOptions
813 Command-line options to the CVSCommand when updating the source.
814 · CTest Script variable: CTEST_CVS_UPDATE_OPTIONS
816 · CTest module variable: CVS_UPDATE_OPTIONS
818 GITCommand
820 git command-line tool to use if source tree is managed by Git.
821 · CTest Script variable: CTEST_GIT_COMMAND
823 · CTest module variable: GITCOMMAND
825 The source tree is updated by git fetch followed by git reset
827 --hard to the FETCH_HEAD. The result is the same as git pull
828 except that any local moficiations are overwritten. Use GITUp‐
829 dateCustom to specify a different approach.
830 GITInitSubmodules
832 If set, CTest will update the repository’s submodules before
833 updating.
834 · CTest Script variable: CTEST_GIT_INIT_SUBMODULES
836 · CTest module variable: CTEST_GIT_INIT_SUBMODULES
838 GITUpdateCustom
840 Specify a custom command line (as a semicolon-separated list) to
841 run in the source tree (Git work tree) to update it instead of
842 running the GITCommand.
843 · CTest Script variable: CTEST_GIT_UPDATE_CUSTOM
845 · CTest module variable: CTEST_GIT_UPDATE_CUSTOM
847 GITUpdateOptions
849 Command-line options to the GITCommand when updating the source.
850 · CTest Script variable: CTEST_GIT_UPDATE_OPTIONS
852 · CTest module variable: GIT_UPDATE_OPTIONS
854 HGCommand
856 hg command-line tool to use if source tree is managed by Mercu‐
857 rial.
858 · CTest Script variable: CTEST_HG_COMMAND
860 · CTest module variable: none
862 HGUpdateOptions
864 Command-line options to the HGCommand when updating the source.
865 · CTest Script variable: CTEST_HG_UPDATE_OPTIONS
867 · CTest module variable: none
869 P4Client
871 Value of the -c option to the P4Command.
872 · CTest Script variable: CTEST_P4_CLIENT
874 · CTest module variable: CTEST_P4_CLIENT
876 P4Command
878 p4 command-line tool to use if source tree is managed by Per‐
879 force.
880 · CTest Script variable: CTEST_P4_COMMAND
882 · CTest module variable: P4COMMAND
884 P4Options
886 Command-line options to the P4Command for all invocations.
887 · CTest Script variable: CTEST_P4_OPTIONS
889 · CTest module variable: CTEST_P4_OPTIONS
891 P4UpdateCustom
893 Specify a custom command line (as a semicolon-separated list) to
894 run in the source tree (Perforce tree) to update it instead of
895 running the P4Command.
896 · CTest Script variable: none
898 · CTest module variable: CTEST_P4_UPDATE_CUSTOM
900 P4UpdateOptions
902 Command-line options to the P4Command when updating the source.
903 · CTest Script variable: CTEST_P4_UPDATE_OPTIONS
905 · CTest module variable: CTEST_P4_UPDATE_OPTIONS
907 SVNCommand
909 svn command-line tool to use if source tree is managed by Sub‐
910 version.
911 · CTest Script variable: CTEST_SVN_COMMAND
913 · CTest module variable: SVNCOMMAND
915 SVNOptions
917 Command-line options to the SVNCommand for all invocations.
918 · CTest Script variable: CTEST_SVN_OPTIONS
920 · CTest module variable: CTEST_SVN_OPTIONS
922 SVNUpdateOptions
924 Command-line options to the SVNCommand when updating the source.
925 · CTest Script variable: CTEST_SVN_UPDATE_OPTIONS
927 · CTest module variable: SVN_UPDATE_OPTIONS
929 UpdateCommand
931 Specify the version-control command-line tool to use without
932 detecting the VCS that manages the source tree.
933 · CTest Script variable: CTEST_UPDATE_COMMAND
935 · CTest module variable: <VCS>COMMAND when UPDATE_TYPE is <vcs>,
937 else UPDATE_COMMAND
938 UpdateOptions
940 Command-line options to the UpdateCommand.
941 · CTest Script variable: CTEST_UPDATE_OPTIONS
943 · CTest module variable: <VCS>_UPDATE_OPTIONS when UPDATE_TYPE
945 is <vcs>, else UPDATE_OPTIONS
946 UpdateType
948 Specify the version-control system that manages the source tree
949 if it cannot be detected automatically. The value may be bzr,
950 cvs, git, hg, p4, or svn.
951 · CTest Script variable: none, detected from source tree
953 · CTest module variable: UPDATE_TYPE if set, else
955 CTEST_UPDATE_TYPE
956 UpdateVersionOnly
958 Specify that you want the version control update command to only
959 discover the current version that is checked out, and not to
960 update to a different version.
961 · CTest Script variable: CTEST_UPDATE_VERSION_ONLY
963 Additional configuration settings include:
965 NightlyStartTime
967 In the Nightly dashboard mode, specify the “nightly start time”.
968 With centralized version control systems (cvs and svn), the
969 Update step checks out the version of the software as of this
970 time so that multiple clients choose a common version to test.
971 This is not well-defined in distributed version-control systems
972 so the setting is ignored.
973 · CTest Script variable: CTEST_NIGHTLY_START_TIME
975 · CTest module variable: NIGHTLY_START_TIME if set, else
977 CTEST_NIGHTLY_START_TIME
978 CTest Configure Step
980 In a CTest Script, the ctest_configure() command runs this step. Argu‐
981 ments to the command may specify some of the step settings.
982 Configuration settings include:
984 ConfigureCommand
986 Command-line to launch the software configuration process. It
987 will be executed in the location specified by the BuildDirectory
988 setting.
989 · CTest Script variable: CTEST_CONFIGURE_COMMAND
991 · CTest module variable: CMAKE_COMMAND followed by
993 PROJECT_SOURCE_DIR
994 LabelsForSubprojects
996 Specify a semicolon-separated list of labels that will be
997 treated as subprojects. This mapping will be passed on to CDash
998 when configure, test or build results are submitted.
999 · CTest Script variable: CTEST_LABELS_FOR_SUBPROJECTS
1001 · CTest module variable: CTEST_LABELS_FOR_SUBPROJECTS
1003 See Label and Subproject Summary.
1005 CTest Build Step
1007 In a CTest Script, the ctest_build() command runs this step. Arguments
1008 to the command may specify some of the step settings.
1009 Configuration settings include:
1011 DefaultCTestConfigurationType
1013 When the build system to be launched allows build-time selection
1014 of the configuration (e.g. Debug, Release), this specifies the
1015 default configuration to be built when no -C option is given to
1016 the ctest command. The value will be substituted into the value
1017 of MakeCommand to replace the literal string ${CTEST_CONFIGURA‐
1018 TION_TYPE} if it appears.
1019 · CTest Script variable: CTEST_CONFIGURATION_TYPE
1021 · CTest module variable: DEFAULT_CTEST_CONFIGURATION_TYPE, ini‐
1023 tialized by the CMAKE_CONFIG_TYPE environment variable
1024 LabelsForSubprojects
1026 Specify a semicolon-separated list of labels that will be
1027 treated as subprojects. This mapping will be passed on to CDash
1028 when configure, test or build results are submitted.
1029 · CTest Script variable: CTEST_LABELS_FOR_SUBPROJECTS
1031 · CTest module variable: CTEST_LABELS_FOR_SUBPROJECTS
1033 See Label and Subproject Summary.
1035 MakeCommand
1037 Command-line to launch the software build process. It will be
1038 executed in the location specified by the BuildDirectory set‐
1039 ting.
1040 · CTest Script variable: CTEST_BUILD_COMMAND
1042 · CTest module variable: MAKECOMMAND, initialized by the
1044 build_command() command
1045 UseLaunchers
1047 For build trees generated by CMake using one of the Makefile
1048 Generators or the Ninja generator, specify whether the
1049 CTEST_USE_LAUNCHERS feature is enabled by the CTestUseLaunchers
1050 module (also included by the CTest module). When enabled, the
1051 generated build system wraps each invocation of the compiler,
1052 linker, or custom command line with a “launcher” that communi‐
1053 cates with CTest via environment variables and files to report
1054 granular build warning and error information. Otherwise, CTest
1055 must “scrape” the build output log for diagnostics.
1056 · CTest Script variable: CTEST_USE_LAUNCHERS
1058 · CTest module variable: CTEST_USE_LAUNCHERS
1060 CTest Test Step
1062 In a CTest Script, the ctest_test() command runs this step. Arguments
1063 to the command may specify some of the step settings.
1064 Configuration settings include:
1066 LabelsForSubprojects
1068 Specify a semicolon-separated list of labels that will be
1069 treated as subprojects. This mapping will be passed on to CDash
1070 when configure, test or build results are submitted.
1071 · CTest Script variable: CTEST_LABELS_FOR_SUBPROJECTS
1073 · CTest module variable: CTEST_LABELS_FOR_SUBPROJECTS
1075 See Label and Subproject Summary.
1077 TestLoad
1079 While running tests in parallel (e.g. with -j), try not to start
1080 tests when they may cause the CPU load to pass above a given
1081 threshold.
1082 · CTest Script variable: CTEST_TEST_LOAD
1084 · CTest module variable: CTEST_TEST_LOAD
1086 TimeOut
1088 The default timeout for each test if not specified by the TIME‐
1089 OUT test property.
1090 · CTest Script variable: CTEST_TEST_TIMEOUT
1092 · CTest module variable: DART_TESTING_TIMEOUT
1094 CTest Coverage Step
1096 In a CTest Script, the ctest_coverage() command runs this step. Argu‐
1097 ments to the command may specify some of the step settings.
1098 Configuration settings include:
1100 CoverageCommand
1102 Command-line tool to perform software coverage analysis. It
1103 will be executed in the location specified by the BuildDirectory
1104 setting.
1105 · CTest Script variable: CTEST_COVERAGE_COMMAND
1107 · CTest module variable: COVERAGE_COMMAND
1109 CoverageExtraFlags
1111 Specify command-line options to the CoverageCommand tool.
1112 · CTest Script variable: CTEST_COVERAGE_EXTRA_FLAGS
1114 · CTest module variable: COVERAGE_EXTRA_FLAGS
1116 These options are the first arguments passed to CoverageCommand.
1118 CTest MemCheck Step
1120 In a CTest Script, the ctest_memcheck() command runs this step. Argu‐
1121 ments to the command may specify some of the step settings.
1122 Configuration settings include:
1124 MemoryCheckCommand
1126 Command-line tool to perform dynamic analysis. Test command
1127 lines will be launched through this tool.
1128 · CTest Script variable: CTEST_MEMORYCHECK_COMMAND
1130 · CTest module variable: MEMORYCHECK_COMMAND
1132 MemoryCheckCommandOptions
1134 Specify command-line options to the MemoryCheckCommand tool.
1135 They will be placed prior to the test command line.
1136 · CTest Script variable: CTEST_MEMORYCHECK_COMMAND_OPTIONS
1138 · CTest module variable: MEMORYCHECK_COMMAND_OPTIONS
1140 MemoryCheckType
1142 Specify the type of memory checking to perform.
1143 · CTest Script variable: CTEST_MEMORYCHECK_TYPE
1145 · CTest module variable: MEMORYCHECK_TYPE
1147 MemoryCheckSanitizerOptions
1149 Specify options to sanitizers when running with a sani‐
1150 tize-enabled build.
1151 · CTest Script variable: CTEST_MEMORYCHECK_SANITIZER_OPTIONS
1153 · CTest module variable: MEMORYCHECK_SANITIZER_OPTIONS
1155 MemoryCheckSuppressionFile
1157 Specify a file containing suppression rules for the MemoryCheck‐
1158 Command tool. It will be passed with options appropriate to the
1159 tool.
1160 · CTest Script variable: CTEST_MEMORYCHECK_SUPPRESSIONS_FILE
1162 · CTest module variable: MEMORYCHECK_SUPPRESSIONS_FILE
1164 Additional configuration settings include:
1166 BoundsCheckerCommand
1168 Specify a MemoryCheckCommand that is known to be command-line
1169 compatible with Bounds Checker.
1170 · CTest Script variable: none
1172 · CTest module variable: none
1174 PurifyCommand
1176 Specify a MemoryCheckCommand that is known to be command-line
1177 compatible with Purify.
1178 · CTest Script variable: none
1180 · CTest module variable: PURIFYCOMMAND
1182 ValgrindCommand
1184 Specify a MemoryCheckCommand that is known to be command-line
1185 compatible with Valgrind.
1186 · CTest Script variable: none
1188 · CTest module variable: VALGRIND_COMMAND
1190 ValgrindCommandOptions
1192 Specify command-line options to the ValgrindCommand tool. They
1193 will be placed prior to the test command line.
1194 · CTest Script variable: none
1196 · CTest module variable: VALGRIND_COMMAND_OPTIONS
1198 CTest Submit Step
1200 In a CTest Script, the ctest_submit() command runs this step. Argu‐
1201 ments to the command may specify some of the step settings.
1202 Configuration settings include:
1204 BuildName
1206 Describe the dashboard client platform with a short string.
1207 (Operating system, compiler, etc.)
1208 · CTest Script variable: CTEST_BUILD_NAME
1210 · CTest module variable: BUILDNAME
1212 CDashVersion
1214 Specify the version of CDash on the server.
1215 · CTest Script variable: none, detected from server
1217 · CTest module variable: CTEST_CDASH_VERSION
1219 CTestSubmitRetryCount
1221 Specify a number of attempts to retry submission on network
1222 failure.
1223 · CTest Script variable: none, use the ctest_submit()
1225 RETRY_COUNT option.
1226 · CTest module variable: CTEST_SUBMIT_RETRY_COUNT
1228 CTestSubmitRetryDelay
1230 Specify a delay before retrying submission on network failure.
1231 · CTest Script variable: none, use the ctest_submit()
1233 RETRY_DELAY option.
1234 · CTest module variable: CTEST_SUBMIT_RETRY_DELAY
1236 CurlOptions
1238 Specify a semicolon-separated list of options to control the
1239 Curl library that CTest uses internally to connect to the
1240 server. Possible options are CURLOPT_SSL_VERIFYPEER_OFF and
1241 CURLOPT_SSL_VERIFYHOST_OFF.
1242 · CTest Script variable: CTEST_CURL_OPTIONS
1244 · CTest module variable: CTEST_CURL_OPTIONS
1246 DropLocation
1248 The path on the dashboard server to send the submission.
1249 · CTest Script variable: CTEST_DROP_LOCATION
1251 · CTest module variable: DROP_LOCATION if set, else
1253 CTEST_DROP_LOCATION
1254 DropMethod
1256 Specify the method by which results should be submitted to the
1257 dashboard server. The value may be cp, ftp, http, https, scp,
1258 or xmlrpc (if CMake was built with support for it).
1259 · CTest Script variable: CTEST_DROP_METHOD
1261 · CTest module variable: DROP_METHOD if set, else
1263 CTEST_DROP_METHOD
1264 DropSite
1266 The dashboard server name (for ftp, http, and https, scp, and
1267 xmlrpc).
1268 · CTest Script variable: CTEST_DROP_SITE
1270 · CTest module variable: DROP_SITE if set, else CTEST_DROP_SITE
1272 DropSitePassword
1274 The dashboard server login password, if any (for ftp, http, and
1275 https).
1276 · CTest Script variable: CTEST_DROP_SITE_PASSWORD
1278 · CTest module variable: DROP_SITE_PASSWORD if set, else
1280 CTEST_DROP_SITE_PASWORD
1281 DropSiteUser
1283 The dashboard server login user name, if any (for ftp, http, and
1284 https).
1285 · CTest Script variable: CTEST_DROP_SITE_USER
1287 · CTest module variable: DROP_SITE_USER if set, else
1289 CTEST_DROP_SITE_USER
1290 IsCDash
1292 Specify whether the dashboard server is CDash or an older dash‐
1293 board server implementation requiring TriggerSite.
1294 · CTest Script variable: CTEST_DROP_SITE_CDASH
1296 · CTest module variable: CTEST_DROP_SITE_CDASH
1298 ScpCommand
1300 scp command-line tool to use when DropMethod is scp.
1301 · CTest Script variable: CTEST_SCP_COMMAND
1303 · CTest module variable: SCPCOMMAND
1305 Site Describe the dashboard client host site with a short string.
1307 (Hostname, domain, etc.)
1308 · CTest Script variable: CTEST_SITE
1310 · CTest module variable: SITE, initialized by the site_name()
1312 command
1313 TriggerSite
1315 Legacy option to support older dashboard server implementations.
1316 Not used when IsCDash is true.
1317 · CTest Script variable: CTEST_TRIGGER_SITE
1319 · CTest module variable: TRIGGER_SITE if set, else CTEST_TRIG‐
1321 GER_SITE
1322
1324 The following resources are available to get help using CMake:
1325 Home Page
1327 https://cmake.org
1328 The primary starting point for learning about CMake.
1330 Frequently Asked Questions
1332 https://cmake.org/Wiki/CMake_FAQ
1333 A Wiki is provided containing answers to frequently asked ques‐
1335 tions.
1336 Online Documentation
1338 https://cmake.org/documentation
1339 Links to available documentation may be found on this web page.
1341 Mailing List
1343 https://cmake.org/mailing-lists
1344 For help and discussion about using cmake, a mailing list is
1346 provided at cmake@cmake.org. The list is member-post-only but
1347 one may sign up on the CMake web page. Please first read the
1348 full documentation at https://cmake.org before posting questions
1349 to the list.
1350
1352 2000-2018 Kitware, Inc. and Contributors
13533.11.4 May 13, 2019 CTEST(1)