ctest.1.rst 42 KB
Newer Older
1 2
.. cmake-manual-description: CTest Command-Line Reference

3 4 5
ctest(1)
********

6 7
.. contents::

8 9
Synopsis
========
10

11
.. parsed-literal::
12

13
 ctest [<options>]
14 15 16
 ctest --build-and-test <path-to-source> <path-to-build>
       --build-generator <generator> [<options>...]
       [--build-options <opts>...] [--test-command <command> [<args>...]]
17
 ctest {-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>}
18
       [-- <dashboard-options>...]
19

20 21 22
Description
===========

23
The **ctest** executable is the CMake test driver program.
24
CMake-generated build trees created for projects that use the
25 26
:command:`enable_testing` and :command:`add_test` commands have testing support.
This program will run the tests and report results.
27

28 29
Options
=======
30

31 32
``-C <cfg>, --build-config <cfg>``
 Choose configuration to test.
33

34 35
 Some CMake-generated build trees can have multiple build
 configurations in the same tree.  This option can be used to specify
36 37
 which one should be tested.  Example configurations are ``Debug`` and
 ``Release``.
38

39 40 41
``--progress``
 Enable short progress output from tests.

42
 When the output of **ctest** is being sent directly to a terminal, the
43 44 45 46 47 48 49 50 51
 progress through the set of tests is reported by updating the same line
 rather than printing start and end messages for each test on new lines.
 This can significantly reduce the verbosity of the test output.
 Test completion messages are still output on their own line for failed
 tests and the final test summary will also still be logged.

 This option can also be enabled by setting the environment variable
 :envvar:`CTEST_PROGRESS_OUTPUT`.

52 53
``-V,--verbose``
 Enable verbose output from tests.
54

55 56
 Test output is normally suppressed and only summary information is
 displayed.  This option will show all test output.
57

58 59
``-VV,--extra-verbose``
 Enable more verbose output from tests.
60

61 62
 Test output is normally suppressed and only summary information is
 displayed.  This option will show even more test output.
63

64 65
``--debug``
 Displaying more verbose internals of CTest.
66

67 68
 This feature will result in a large number of output that is mostly
 useful for debugging dashboard problems.
69

70
``--output-on-failure``
71
 Output anything outputted by the test program if the test should fail.
72 73
 This option can also be enabled by setting the
 :envvar:`CTEST_OUTPUT_ON_FAILURE` environment variable
74

75 76
``-F``
 Enable failover.
77

78
 This option allows CTest to resume a test set execution that was
79
 previously interrupted.  If no interruption occurred, the ``-F`` option
80
 will have no effect.
81

82
``-j <jobs>, --parallel <jobs>``
83
 Run the tests in parallel using the given number of jobs.
84

85 86
 This option tells CTest to run the tests in parallel using given
 number of jobs. This option can also be set by setting the
87
 :envvar:`CTEST_PARALLEL_LEVEL` environment variable.
88

89 90 91 92
 This option can be used with the :prop_test:`PROCESSORS` test property.

 See `Label and Subproject Summary`_.

93 94 95 96 97 98 99
``--test-load <level>``
 While running tests in parallel (e.g. with ``-j``), try not to start
 tests when they may cause the CPU load to pass above a given threshold.

 When ``ctest`` is run as a `Dashboard Client`_ this sets the
 ``TestLoad`` option of the `CTest Test Step`_.

100
``-Q,--quiet``
101
 Make CTest quiet.
102

103
 This option will suppress all the output.  The output log file will
104 105 106
 still be generated if the ``--output-log`` is specified.  Options such
 as ``--verbose``, ``--extra-verbose``, and ``--debug`` are ignored
 if ``--quiet`` is specified.
107

108
``-O <file>, --output-log <file>``
109
 Output to log file.
110

111
 This option tells CTest to write all its output to a ``<file>`` log file.
112

113
``-N,--show-only[=<format>]``
114
 Disable actual execution of tests.
115

116
 This option tells CTest to list the tests that would be run but not
117
 actually run them.  Useful in conjunction with the ``-R`` and ``-E``
118
 options.
119

120 121 122 123 124 125 126 127 128 129
 ``<format>`` can be one of the following values.

   ``human``
     Human-friendly output.  This is not guaranteed to be stable.
     This is the default.

   ``json-v1``
     Dump the test information in JSON format.
     See `Show as JSON Object Model`_.

130 131
``-L <regex>, --label-regex <regex>``
 Run tests with labels matching regular expression.
132

133
 This option tells CTest to run only the tests whose labels match the
134
 given regular expression.
135

136 137
``-R <regex>, --tests-regex <regex>``
 Run tests matching regular expression.
138

139
 This option tells CTest to run only the tests whose names match the
140
 given regular expression.
141

142 143
``-E <regex>, --exclude-regex <regex>``
 Exclude tests matching regular expression.
144

145
 This option tells CTest to NOT run the tests whose names match the
146
 given regular expression.
147

148 149
``-LE <regex>, --label-exclude <regex>``
 Exclude tests with labels matching regular expression.
150

151
 This option tells CTest to NOT run the tests whose labels match the
152
 given regular expression.
153

154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170
``-FA <regex>, --fixture-exclude-any <regex>``
 Exclude fixtures matching ``<regex>`` from automatically adding any tests to
 the test set.

 If a test in the set of tests to be executed requires a particular fixture,
 that fixture's setup and cleanup tests would normally be added to the test set
 automatically. This option prevents adding setup or cleanup tests for fixtures
 matching the ``<regex>``. Note that all other fixture behavior is retained,
 including test dependencies and skipping tests that have fixture setup tests
 that fail.

``-FS <regex>, --fixture-exclude-setup <regex>``
 Same as ``-FA`` except only matching setup tests are excluded.

``-FC <regex>, --fixture-exclude-cleanup <regex>``
 Same as ``-FA`` except only matching cleanup tests are excluded.

171
``-D <dashboard>, --dashboard <dashboard>``
172
 Execute dashboard test.
173

174
 This option tells CTest to act as a CDash client and perform a
175 176 177 178
 dashboard test.  All tests are ``<Mode><Test>``, where ``<Mode>`` can be
 ``Experimental``, ``Nightly``, and ``Continuous``, and ``<Test>`` can be
 ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``,
 ``Coverage``, and ``Submit``.
179

180 181
 See `Dashboard Client`_.

182
``-D <var>:<type>=<value>``
183
 Define a variable for script mode.
184

185
 Pass in variable values on the command line.  Use in conjunction
186
 with ``-S`` to pass variable values to a dashboard script.  Parsing ``-D``
187
 arguments as variable values is only attempted if the value
188
 following ``-D`` does not match any of the known dashboard types.
189

190
``-M <model>, --test-model <model>``
191
 Sets the model for a dashboard.
192

193
 This option tells CTest to act as a CDash client where the ``<model>``
194 195
 can be ``Experimental``, ``Nightly``, and ``Continuous``.
 Combining ``-M`` and ``-T`` is similar to ``-D``.
196

197 198
 See `Dashboard Client`_.

199
``-T <action>, --test-action <action>``
200
 Sets the dashboard action to perform.
201

202
 This option tells CTest to act as a CDash client and perform some
203 204 205
 action such as ``start``, ``build``, ``test`` etc. See
 `Dashboard Client Steps`_ for the full list of actions.
 Combining ``-M`` and ``-T`` is similar to ``-D``.
206

207
 See `Dashboard Client`_.
208

209
``-S <script>, --script <script>``
210
 Execute a dashboard for a configuration.
211

212
 This option tells CTest to load in a configuration script which sets
213
 a number of parameters such as the binary and source directories.
214
 Then CTest will do what is required to create and run a dashboard.
215
 This option basically sets up a dashboard and then runs ``ctest -D``
216
 with the appropriate options.
217

218 219
 See `Dashboard Client`_.

220
``-SP <script>, --script-new-process <script>``
221
 Execute a dashboard for a configuration.
222

223
 This option does the same operations as ``-S`` but it will do them in a
224 225
 separate process.  This is primarily useful in cases where the
 script may modify the environment and you do not want the modified
226
 environment to impact other ``-S`` scripts.
227

228
 See `Dashboard Client`_.
229

230 231
``-I [Start,End,Stride,test#,test#|Test file], --tests-information``
 Run a specific number of tests by number.
232

233 234 235 236
 This option causes CTest to run tests starting at number ``Start``,
 ending at number ``End``, and incrementing by ``Stride``.  Any additional
 numbers after ``Stride`` are considered individual test numbers.  ``Start``,
 ``End``, or ``Stride`` can be empty.  Optionally a file can be given that
237
 contains the same syntax as the command line.
238

239
``-U, --union``
240
 Take the Union of ``-I`` and ``-R``.
241

242 243
 When both ``-R`` and ``-I`` are specified by default the intersection of
 tests are run.  By specifying ``-U`` the union of tests is run instead.
244

245
``--rerun-failed``
246
 Run only the tests that failed previously.
247

248 249
 This option tells CTest to perform only the tests that failed during
 its previous run.  When this option is specified, CTest ignores all
250 251
 other options intended to modify the list of tests to run (``-L``, ``-R``,
 ``-E``, ``-LE``, ``-I``, etc).  In the event that CTest runs and no tests
252
 fail, subsequent calls to CTest with the ``--rerun-failed`` option will run
253
 the set of tests that most recently failed (if any).
254

255 256 257 258 259
``--repeat-until-fail <n>``
 Require each test to run ``<n>`` times without failing in order to pass.

 This is useful in finding sporadic failures in test cases.

260
``--max-width <width>``
261
 Set the max width for a test name to output.
262

263 264 265
 Set the maximum width for each test name to show in the output.
 This allows the user to widen the output to avoid clipping the test
 name which can be very annoying.
266

267
``--interactive-debug-mode [0|1]``
268
 Set the interactive mode to ``0`` or ``1``.
269

270
 This option causes CTest to run tests in either an interactive mode
271 272
 or a non-interactive mode.  On Windows this means that in
 non-interactive mode, all system debug pop up windows are blocked.
273
 In dashboard mode (``Experimental``, ``Nightly``, ``Continuous``), the default
274 275
 is non-interactive.  When just running tests not for a dashboard the
 default is to allow popups and interactive debugging.
276

277 278
``--no-label-summary``
 Disable timing summary information for labels.
279

280
 This option tells CTest not to print summary information for each
281 282
 label associated with the tests run.  If there are no labels on the
 tests, nothing extra is printed.
283

284 285
 See `Label and Subproject Summary`_.

286
``--no-subproject-summary``
287 288
 Disable timing summary information for subprojects.

289
 This option tells CTest not to print summary information for each
290 291 292
 subproject associated with the tests run.  If there are no subprojects on the
 tests, nothing extra is printed.

293 294
 See `Label and Subproject Summary`_.

295 296 297 298 299 300 301 302 303 304 305 306
``--build-and-test``
See `Build and Test Mode`_.

``--test-output-size-passed <size>``
 Limit the output for passed tests to ``<size>`` bytes.

``--test-output-size-failed <size>``
 Limit the output for failed tests to ``<size>`` bytes.

``--overwrite``
 Overwrite CTest configuration option.

307
 By default CTest uses configuration options from configuration file.
308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327
 This option will overwrite the configuration option.

``--force-new-ctest-process``
 Run child CTest instances as new processes.

 By default CTest will run child CTest instances within the same
 process.  If this behavior is not desired, this argument will
 enforce new processes for child CTest processes.

``--schedule-random``
 Use a random order for scheduling tests.

 This option will run the tests in a random order.  It is commonly
 used to detect implicit dependencies in a test suite.

``--submit-index``
 Legacy option for old Dart2 dashboard server feature.
 Do not use.

``--timeout <seconds>``
328
 Set the default test timeout.
329

330 331 332
 This option effectively sets a timeout on all tests that do not
 already have a timeout set on them via the :prop_test:`TIMEOUT`
 property.
333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348

``--stop-time <time>``
 Set a time at which all tests should stop running.

 Set a real time of day at which all tests should timeout.  Example:
 ``7:00:00 -0400``.  Any time format understood by the curl date parser
 is accepted.  Local time is assumed if no timezone is specified.

``--print-labels``
 Print all available test labels.

 This option will not run any tests, it will simply print the list of
 all labels associated with the test set.

.. include:: OPTIONS_HELP.txt

349 350 351 352 353
.. _`Label and Subproject Summary`:

Label and Subproject Summary
============================

354
CTest prints timing summary information for each ``LABEL`` and subproject
355 356 357 358
associated with the tests run. The label time summary will not include labels
that are mapped to subprojects.

When the :prop_test:`PROCESSORS` test property is set, CTest will display a
359
weighted test timing result in label and subproject summaries. The time is
360 361
reported with `sec*proc` instead of just `sec`.

362 363
The weighted time summary reported for each label or subproject ``j``
is computed as::
364 365 366 367 368 369 370 371

  Weighted Time Summary for Label/Subproject j =
      sum(raw_test_time[j,i] * num_processors[j,i], i=1...num_tests[j])

  for labels/subprojects j=1...total

where:

372 373 374 375 376 377
* ``raw_test_time[j,i]``: Wall-clock time for the ``i``th test
  for the ``j``th label or subproject
* ``num_processors[j,i]``: Value of the CTest :prop_test:`PROCESSORS` property
  for the ``i``th test for the ``j``th label or subproject
* ``num_tests[j]``: Number of tests associated with the ``j``th label or subproject
* ``total``: Total number of labels or subprojects that have at least one test run
378 379 380 381 382 383

Therefore, the weighted time summary for each label or subproject represents
the amount of time that CTest gave to run the tests for each label or
subproject and gives a good representation of the total expense of the tests
for each label or subproject when compared to other labels or subprojects.

384 385 386
For example, if ``SubprojectA`` showed ``100 sec*proc`` and ``SubprojectB`` showed
``10 sec*proc``, then CTest allocated approximately 10 times the CPU/core time
to run the tests for ``SubprojectA`` than for ``SubprojectB`` (e.g. so if effort
387
is going to be expended to reduce the cost of the test suite for the whole
388
project, then reducing the cost of the test suite for ``SubprojectA`` would
389
likely have a larger impact than effort to reduce the cost of the test suite
390
for ``SubprojectB``).
391

392
.. _`Build and Test Mode`:
393

394 395 396
Build and Test Mode
===================

397 398
CTest provides a command-line signature to configure (i.e. run cmake on),
build, and/or execute a test::
399 400

  ctest --build-and-test <path-to-source> <path-to-build>
401 402 403 404
        --build-generator <generator>
        [<options>...]
        [--build-options <opts>...]
        [--test-command <command> [<args>...]]
405 406

The configure and test steps are optional. The arguments to this command line
407
are the source and binary directories.  The ``--build-generator`` option *must*
408 409 410
be provided to use ``--build-and-test``.  If ``--test-command`` is specified
then that will be run after the build is complete.  Other options that affect
this mode include:
411

412 413
``--build-target``
 Specify a specific target to build.
414

415
 If left out the ``all`` target is built.
416

417 418
``--build-nocmake``
 Run the build without running cmake first.
419

420
 Skip the cmake step.
421

422 423
``--build-run-dir``
 Specify directory to run programs from.
424

425
 Directory where programs will be after it has been compiled.
426

427
``--build-two-config``
428
 Run CMake twice.
429

430 431
``--build-exe-dir``
 Specify the directory for the executable.
432

433
``--build-generator``
434
 Specify the generator to use. See the :manual:`cmake-generators(7)` manual.
435

436 437 438
``--build-generator-platform``
 Specify the generator-specific platform.

439 440
``--build-generator-toolset``
 Specify the generator-specific toolset.
441

442 443
``--build-project``
 Specify the name of the project to build.
444

445
``--build-makeprogram``
446
 Override the make program chosen by CTest with a given one.
447

448 449
``--build-noclean``
 Skip the make clean step.
450

451 452
``--build-config-sample``
 A sample executable to use to determine the configuration that
453
 should be used.  e.g.  ``Debug``, ``Release`` etc.
454

455
``--build-options``
456 457 458 459
 Additional options for configuring the build (i.e. for CMake, not for
 the build tool).  Note that if this is specified, the ``--build-options``
 keyword and its arguments must be the last option given on the command
 line, with the possible exception of ``--test-command``.
460

461
``--test-command``
462 463 464
 The command to run as the test step with the ``--build-and-test`` option.
 All arguments following this keyword will be assumed to be part of the
 test command line, so it must be the last option given.
465

466
``--test-timeout``
467
 The time limit in seconds
468

469
.. _`Dashboard Client`:
470

471 472
Dashboard Client
================
473

474 475 476 477
CTest can operate as a client for the `CDash`_ software quality dashboard
application.  As a dashboard client, CTest performs a sequence of steps
to configure, build, and test software, and then submits the results to
a `CDash`_ server. The command-line signature used to submit to `CDash`_ is::
478

479 480
  ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>)
        [-- <dashboard-options>...]
481

482
Options for Dashboard Client include:
483

484 485
``--track <track>``
 Specify the track to submit dashboard to
486

487 488 489 490
 Submit dashboard to specified track instead of default one.  By
 default, the dashboard is submitted to Nightly, Experimental, or
 Continuous track, but by specifying this option, the track can be
 arbitrary.
491

492 493
``-A <file>, --add-notes <file>``
 Add a notes file with submission.
494

495
 This option tells CTest to include a notes file when submitting
496
 dashboard.
497

498
``--tomorrow-tag``
499
 ``Nightly`` or ``Experimental`` starts with next day tag.
500

501
 This is useful if the build will not finish in one day.
502

503 504
``--extra-submit <file>[;<file>]``
 Submit extra files to the dashboard.
505

506
 This option will submit extra files to the dashboard.
507

508
``--http1.0``
509
 Submit using `HTTP 1.0`.
510

511 512
 This option will force CTest to use `HTTP 1.0` to submit files to the
 dashboard, instead of `HTTP 1.1`.
513

514 515
``--no-compress-output``
 Do not compress test output when submitting.
516

517 518 519
 This flag will turn off automatic compression of test output.  Use
 this to maintain compatibility with an older version of CDash which
 doesn't support compressed test output.
520

521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663
Dashboard Client Steps
----------------------

CTest defines an ordered list of testing steps of which some or all may
be run as a dashboard client:

``Start``
  Start a new dashboard submission to be composed of results recorded
  by the following steps.
  See the `CTest Start Step`_ section below.

``Update``
  Update the source tree from its version control repository.
  Record the old and new versions and the list of updated source files.
  See the `CTest Update Step`_ section below.

``Configure``
  Configure the software by running a command in the build tree.
  Record the configuration output log.
  See the `CTest Configure Step`_ section below.

``Build``
  Build the software by running a command in the build tree.
  Record the build output log and detect warnings and errors.
  See the `CTest Build Step`_ section below.

``Test``
  Test the software by loading a ``CTestTestfile.cmake``
  from the build tree and executing the defined tests.
  Record the output and result of each test.
  See the `CTest Test Step`_ section below.

``Coverage``
  Compute coverage of the source code by running a coverage
  analysis tool and recording its output.
  See the `CTest Coverage Step`_ section below.

``MemCheck``
  Run the software test suite through a memory check tool.
  Record the test output, results, and issues reported by the tool.
  See the `CTest MemCheck Step`_ section below.

``Submit``
  Submit results recorded from other testing steps to the
  software quality dashboard server.
  See the `CTest Submit Step`_ section below.

Dashboard Client Modes
----------------------

CTest defines three modes of operation as a dashboard client:

``Nightly``
  This mode is intended to be invoked once per day, typically at night.
  It enables the ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``,
  ``Coverage``, and ``Submit`` steps by default.  Selected steps run even
  if the ``Update`` step reports no changes to the source tree.

``Continuous``
  This mode is intended to be invoked repeatedly throughout the day.
  It enables the ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``,
  ``Coverage``, and ``Submit`` steps by default, but exits after the
  ``Update`` step if it reports no changes to the source tree.

``Experimental``
  This mode is intended to be invoked by a developer to test local changes.
  It enables the ``Start``, ``Configure``, ``Build``, ``Test``, ``Coverage``,
  and ``Submit`` steps by default.

Dashboard Client via CTest Command-Line
---------------------------------------

CTest can perform testing on an already-generated build tree.
Run the ``ctest`` command with the current working directory set
to the build tree and use one of these signatures::

  ctest -D <mode>[<step>]
  ctest -M <mode> [ -T <step> ]...

The ``<mode>`` must be one of the above `Dashboard Client Modes`_,
and each ``<step>`` must be one of the above `Dashboard Client Steps`_.

CTest reads the `Dashboard Client Configuration`_ settings from
a file in the build tree called either ``CTestConfiguration.ini``
or ``DartConfiguration.tcl`` (the names are historical).  The format
of the file is::

  # Lines starting in '#' are comments.
  # Other non-blank lines are key-value pairs.
  <setting>: <value>

where ``<setting>`` is the setting name and ``<value>`` is the
setting value.

In build trees generated by CMake, this configuration file is
generated by the :module:`CTest` module if included by the project.
The module uses variables to obtain a value for each setting
as documented with the settings below.

.. _`CTest Script`:

Dashboard Client via CTest Script
---------------------------------

CTest can perform testing driven by a :manual:`cmake-language(7)`
script that creates and maintains the source and build tree as
well as performing the testing steps.  Run the ``ctest`` command
with the current working directory set outside of any build tree
and use one of these signatures::

  ctest -S <script>
  ctest -SP <script>

The ``<script>`` file must call :ref:`CTest Commands` commands
to run testing steps explicitly as documented below.  The commands
obtain `Dashboard Client Configuration`_ settings from their
arguments or from variables set in the script.

Dashboard Client Configuration
==============================

The `Dashboard Client Steps`_ may be configured by named
settings as documented in the following sections.

.. _`CTest Start Step`:

CTest Start Step
----------------

Start a new dashboard submission to be composed of results recorded
by the following steps.

In a `CTest Script`_, the :command:`ctest_start` command runs this step.
Arguments to the command may specify some of the step settings.
The command first runs the command-line specified by the
``CTEST_CHECKOUT_COMMAND`` variable, if set, to initialize the source
directory.

Configuration settings include:

``BuildDirectory``
  The full path to the project build tree.

664
  * `CTest Script`_ variable: :variable:`CTEST_BINARY_DIRECTORY`
665 666 667 668 669
  * :module:`CTest` module variable: :variable:`PROJECT_BINARY_DIR`

``SourceDirectory``
  The full path to the project source tree.

670
  * `CTest Script`_ variable: :variable:`CTEST_SOURCE_DIRECTORY`
671 672 673 674 675 676 677 678 679 680 681 682 683 684 685
  * :module:`CTest` module variable: :variable:`PROJECT_SOURCE_DIR`

.. _`CTest Update Step`:

CTest Update Step
-----------------

In a `CTest Script`_, the :command:`ctest_update` command runs this step.
Arguments to the command may specify some of the step settings.

Configuration settings to specify the version control tool include:

``BZRCommand``
  ``bzr`` command-line tool to use if source tree is managed by Bazaar.

686
  * `CTest Script`_ variable: :variable:`CTEST_BZR_COMMAND`
687 688 689 690 691
  * :module:`CTest` module variable: none

``BZRUpdateOptions``
  Command-line options to the ``BZRCommand`` when updating the source.

692
  * `CTest Script`_ variable: :variable:`CTEST_BZR_UPDATE_OPTIONS`
693 694 695 696 697
  * :module:`CTest` module variable: none

``CVSCommand``
  ``cvs`` command-line tool to use if source tree is managed by CVS.

698
  * `CTest Script`_ variable: :variable:`CTEST_CVS_COMMAND`
699 700 701 702 703
  * :module:`CTest` module variable: ``CVSCOMMAND``

``CVSUpdateOptions``
  Command-line options to the ``CVSCommand`` when updating the source.

704
  * `CTest Script`_ variable: :variable:`CTEST_CVS_UPDATE_OPTIONS`
705 706 707 708 709
  * :module:`CTest` module variable: ``CVS_UPDATE_OPTIONS``

``GITCommand``
  ``git`` command-line tool to use if source tree is managed by Git.

710
  * `CTest Script`_ variable: :variable:`CTEST_GIT_COMMAND`
711 712
  * :module:`CTest` module variable: ``GITCOMMAND``

713 714
  The source tree is updated by ``git fetch`` followed by
  ``git reset --hard`` to the ``FETCH_HEAD``.  The result is the same
715
  as ``git pull`` except that any local modifications are overwritten.
716 717
  Use ``GITUpdateCustom`` to specify a different approach.

718 719 720 721 722 723
``GITInitSubmodules``
  If set, CTest will update the repository's submodules before updating.

  * `CTest Script`_ variable: :variable:`CTEST_GIT_INIT_SUBMODULES`
  * :module:`CTest` module variable: ``CTEST_GIT_INIT_SUBMODULES``

724
``GITUpdateCustom``
725
  Specify a custom command line (as a semicolon-separated list) to run
726 727 728
  in the source tree (Git work tree) to update it instead of running
  the ``GITCommand``.

729
  * `CTest Script`_ variable: :variable:`CTEST_GIT_UPDATE_CUSTOM`
730 731 732 733 734
  * :module:`CTest` module variable: ``CTEST_GIT_UPDATE_CUSTOM``

``GITUpdateOptions``
  Command-line options to the ``GITCommand`` when updating the source.

735
  * `CTest Script`_ variable: :variable:`CTEST_GIT_UPDATE_OPTIONS`
736 737 738 739 740
  * :module:`CTest` module variable: ``GIT_UPDATE_OPTIONS``

``HGCommand``
  ``hg`` command-line tool to use if source tree is managed by Mercurial.

741
  * `CTest Script`_ variable: :variable:`CTEST_HG_COMMAND`
742 743 744 745 746
  * :module:`CTest` module variable: none

``HGUpdateOptions``
  Command-line options to the ``HGCommand`` when updating the source.

747
  * `CTest Script`_ variable: :variable:`CTEST_HG_UPDATE_OPTIONS`
748 749 750 751 752
  * :module:`CTest` module variable: none

``P4Client``
  Value of the ``-c`` option to the ``P4Command``.

753
  * `CTest Script`_ variable: :variable:`CTEST_P4_CLIENT`
754 755 756 757 758
  * :module:`CTest` module variable: ``CTEST_P4_CLIENT``

``P4Command``
  ``p4`` command-line tool to use if source tree is managed by Perforce.

759
  * `CTest Script`_ variable: :variable:`CTEST_P4_COMMAND`
760 761 762 763 764
  * :module:`CTest` module variable: ``P4COMMAND``

``P4Options``
  Command-line options to the ``P4Command`` for all invocations.

765
  * `CTest Script`_ variable: :variable:`CTEST_P4_OPTIONS`
766 767 768
  * :module:`CTest` module variable: ``CTEST_P4_OPTIONS``

``P4UpdateCustom``
769
  Specify a custom command line (as a semicolon-separated list) to run
770 771 772 773 774 775 776 777 778
  in the source tree (Perforce tree) to update it instead of running
  the ``P4Command``.

  * `CTest Script`_ variable: none
  * :module:`CTest` module variable: ``CTEST_P4_UPDATE_CUSTOM``

``P4UpdateOptions``
  Command-line options to the ``P4Command`` when updating the source.

779
  * `CTest Script`_ variable: :variable:`CTEST_P4_UPDATE_OPTIONS`
780 781 782 783 784
  * :module:`CTest` module variable: ``CTEST_P4_UPDATE_OPTIONS``

``SVNCommand``
  ``svn`` command-line tool to use if source tree is managed by Subversion.

785
  * `CTest Script`_ variable: :variable:`CTEST_SVN_COMMAND`
786 787 788 789 790
  * :module:`CTest` module variable: ``SVNCOMMAND``

``SVNOptions``
  Command-line options to the ``SVNCommand`` for all invocations.

791
  * `CTest Script`_ variable: :variable:`CTEST_SVN_OPTIONS`
792 793 794 795 796
  * :module:`CTest` module variable: ``CTEST_SVN_OPTIONS``

``SVNUpdateOptions``
  Command-line options to the ``SVNCommand`` when updating the source.

797
  * `CTest Script`_ variable: :variable:`CTEST_SVN_UPDATE_OPTIONS`
798 799 800 801 802 803
  * :module:`CTest` module variable: ``SVN_UPDATE_OPTIONS``

``UpdateCommand``
  Specify the version-control command-line tool to use without
  detecting the VCS that manages the source tree.

804
  * `CTest Script`_ variable: :variable:`CTEST_UPDATE_COMMAND`
805 806 807 808 809 810
  * :module:`CTest` module variable: ``<VCS>COMMAND``
    when ``UPDATE_TYPE`` is ``<vcs>``, else ``UPDATE_COMMAND``

``UpdateOptions``
  Command-line options to the ``UpdateCommand``.

811
  * `CTest Script`_ variable: :variable:`CTEST_UPDATE_OPTIONS`
812 813 814 815 816 817 818 819 820 821 822 823 824
  * :module:`CTest` module variable: ``<VCS>_UPDATE_OPTIONS``
    when ``UPDATE_TYPE`` is ``<vcs>``, else ``UPDATE_OPTIONS``

``UpdateType``
  Specify the version-control system that manages the source
  tree if it cannot be detected automatically.
  The value may be ``bzr``, ``cvs``, ``git``, ``hg``,
  ``p4``, or ``svn``.

  * `CTest Script`_ variable: none, detected from source tree
  * :module:`CTest` module variable: ``UPDATE_TYPE`` if set,
    else ``CTEST_UPDATE_TYPE``

825 826 827 828 829 830 831 832
``UpdateVersionOnly``
  Specify that you want the version control update command to only
  discover the current version that is checked out, and not to update
  to a different version.

  * `CTest Script`_ variable: :variable:`CTEST_UPDATE_VERSION_ONLY`


833 834 835 836 837 838 839 840 841 842
Additional configuration settings include:

``NightlyStartTime``
  In the ``Nightly`` dashboard mode, specify the "nightly start time".
  With centralized version control systems (``cvs`` and ``svn``),
  the ``Update`` step checks out the version of the software as of
  this time so that multiple clients choose a common version to test.
  This is not well-defined in distributed version-control systems so
  the setting is ignored.

843
  * `CTest Script`_ variable: :variable:`CTEST_NIGHTLY_START_TIME`
844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861
  * :module:`CTest` module variable: ``NIGHTLY_START_TIME`` if set,
    else ``CTEST_NIGHTLY_START_TIME``

.. _`CTest Configure Step`:

CTest Configure Step
--------------------

In a `CTest Script`_, the :command:`ctest_configure` command runs this step.
Arguments to the command may specify some of the step settings.

Configuration settings include:

``ConfigureCommand``
  Command-line to launch the software configuration process.
  It will be executed in the location specified by the
  ``BuildDirectory`` setting.

862
  * `CTest Script`_ variable: :variable:`CTEST_CONFIGURE_COMMAND`
863 864 865
  * :module:`CTest` module variable: :variable:`CMAKE_COMMAND`
    followed by :variable:`PROJECT_SOURCE_DIR`

866 867 868 869 870 871 872 873
``LabelsForSubprojects``
  Specify a semicolon-separated list of labels that will be treated as
  subprojects. This mapping will be passed on to CDash when configure, test or
  build results are submitted.

  * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS`
  * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS``

874
  See `Label and Subproject Summary`_.
875

876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893
.. _`CTest Build Step`:

CTest Build Step
----------------

In a `CTest Script`_, the :command:`ctest_build` command runs this step.
Arguments to the command may specify some of the step settings.

Configuration settings include:

``DefaultCTestConfigurationType``
  When the build system to be launched allows build-time selection
  of the configuration (e.g. ``Debug``, ``Release``), this specifies
  the default configuration to be built when no ``-C`` option is
  given to the ``ctest`` command.  The value will be substituted into
  the value of ``MakeCommand`` to replace the literal string
  ``${CTEST_CONFIGURATION_TYPE}`` if it appears.

894
  * `CTest Script`_ variable: :variable:`CTEST_CONFIGURATION_TYPE`
895
  * :module:`CTest` module variable: ``DEFAULT_CTEST_CONFIGURATION_TYPE``,
896
    initialized by the :envvar:`CMAKE_CONFIG_TYPE` environment variable
897

898 899 900 901 902 903 904 905
``LabelsForSubprojects``
  Specify a semicolon-separated list of labels that will be treated as
  subprojects. This mapping will be passed on to CDash when configure, test or
  build results are submitted.

  * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS`
  * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS``

906 907
  See `Label and Subproject Summary`_.

908 909 910 911 912
``MakeCommand``
  Command-line to launch the software build process.
  It will be executed in the location specified by the
  ``BuildDirectory`` setting.

913
  * `CTest Script`_ variable: :variable:`CTEST_BUILD_COMMAND`
914 915 916 917
  * :module:`CTest` module variable: ``MAKECOMMAND``,
    initialized by the :command:`build_command` command

``UseLaunchers``
918 919 920
  For build trees generated by CMake using one of the
  :ref:`Makefile Generators` or the :generator:`Ninja`
  generator, specify whether the
921 922 923 924 925 926 927 928 929
  ``CTEST_USE_LAUNCHERS`` feature is enabled by the
  :module:`CTestUseLaunchers` module (also included by the
  :module:`CTest` module).  When enabled, the generated build
  system wraps each invocation of the compiler, linker, or
  custom command line with a "launcher" that communicates
  with CTest via environment variables and files to report
  granular build warning and error information.  Otherwise,
  CTest must "scrape" the build output log for diagnostics.

930
  * `CTest Script`_ variable: :variable:`CTEST_USE_LAUNCHERS`
931 932 933 934 935 936 937 938 939 940 941 942
  * :module:`CTest` module variable: ``CTEST_USE_LAUNCHERS``

.. _`CTest Test Step`:

CTest Test Step
---------------

In a `CTest Script`_, the :command:`ctest_test` command runs this step.
Arguments to the command may specify some of the step settings.

Configuration settings include:

943 944 945