Commit 9d3aa95c authored by Betsy McPhail's avatar Betsy McPhail Committed by Brad King
Browse files

Help: Divide ctest(1) manual options into sections

parent 7904b659
......@@ -3,12 +3,18 @@
ctest(1)
********
.. contents::
Synopsis
========
.. parsed-literal::
ctest [<options>]
ctest <path-to-source> <path-to-build> --build-generator <generator>
[<options>...] [-- <build-options>...] [--test-command <test>]
ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>)
[-- <dashboard-options>...]
Description
===========
......@@ -142,6 +148,8 @@ Options
Experimental, Nightly, and Continuous, and Test can be Start,
Update, Configure, Build, Test, Coverage, and Submit.
See `Dashboard Client`_.
``-D <var>:<type>=<value>``
Define a variable for script mode.
......@@ -157,6 +165,8 @@ Options
can be ``Experimental``, ``Nightly``, and ``Continuous``.
Combining ``-M`` and ``-T`` is similar to ``-D``.
See `Dashboard Client`_.
``-T <action>, --test-action <action>``
Sets the dashboard action to perform.
......@@ -165,13 +175,7 @@ Options
`Dashboard Client Steps`_ for the full list of actions.
Combining ``-M`` and ``-T`` is similar to ``-D``.
``--track <track>``
Specify the track to submit dashboard to
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.
See `Dashboard Client`_.
``-S <script>, --script <script>``
Execute a dashboard for a configuration.
......@@ -182,6 +186,8 @@ Options
This option basically sets up a dashboard and then runs ``ctest -D``
with the appropriate options.
See `Dashboard Client`_.
``-SP <script>, --script-new-process <script>``
Execute a dashboard for a configuration.
......@@ -190,11 +196,7 @@ Options
script may modify the environment and you do not want the modified
environment to impact other ``-S`` scripts.
``-A <file>, --add-notes <file>``
Add a notes file with submission.
This option tells ctest to include a notes file when submitting
dashboard.
See `Dashboard Client`_.
``-I [Start,End,Stride,test#,test#|Test file], --tests-information``
Run a specific number of tests by number.
......@@ -250,32 +252,88 @@ Options
label associated with the tests run. If there are no labels on the
tests, nothing extra is printed.
``--no-subproject-summary``
``--no-subproject-summary``
Disable timing summary information for subprojects.
This option tells ctest not to print summary information for each
subproject associated with the tests run. If there are no subprojects on the
tests, nothing extra is printed.
``--build-and-test <path-to-source> <path-to-build>``
Configure, build and run a test.
``--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.
By default ctest uses configuration options from configuration file.
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>``
Set a global timeout on all tests.
This option will set a global timeout on all tests that do not
already have a timeout set on them.
``--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
.. _`Build and Test Mode`:
This option tells ctest to configure (i.e. run cmake on), build,
and or execute a test. The configure and test steps are optional.
The arguments to this command line are the source and binary
directories.
The ``--build-generator`` option *must* 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 are ``--build-target``, ``--build-nocmake``, ``--build-run-dir``,
``--build-two-config``, ``--build-exe-dir``,
``--build-project``, ``--build-noclean`` and ``--build-options``.
Build and Test Mode
===================
CTest provides a command-line signature to to configure (i.e. run cmake on),
build, and or execute a test::
ctest --build-and-test <path-to-source> <path-to-build>
--build-generator <generator> [<options>...] [-- <build-options>...]
[--test-command <test>]
The configure and test steps are optional. The arguments to this command line
are the source and binary directories. The ``--build-generator`` option *must*
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:
``--build-target``
Specify a specific target to build.
This option goes with the ``--build-and-test`` option, if left out the
``all`` target is built.
If left out the ``all`` target is built.
``--build-nocmake``
Run the build without running cmake first.
......@@ -324,60 +382,47 @@ Options
``--test-command``
The test to run with the ``--build-and-test`` option.
``--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.
``--test-timeout``
The time limit in seconds, internal use only.
The time limit in seconds
``--tomorrow-tag``
Nightly or experimental starts with next day tag.
This is useful if the build will not finish in one day.
``--overwrite``
Overwrite CTest configuration option.
.. _`Dashboard Client`:
By default ctest uses configuration options from configuration file.
This option will overwrite the configuration option.
Dashboard Client
================
``--extra-submit <file>[;<file>]``
Submit extra files to the dashboard.
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::
This option will submit extra files to the dashboard.
ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>)
[-- <dashboard-options>...]
``--force-new-ctest-process``
Run child CTest instances as new processes.
Options for Dashboard Client include:
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.
``--track <track>``
Specify the track to submit dashboard to
``--schedule-random``
Use a random order for scheduling tests.
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.
This option will run the tests in a random order. It is commonly
used to detect implicit dependencies in a test suite.
``-A <file>, --add-notes <file>``
Add a notes file with submission.
``--submit-index``
Legacy option for old Dart2 dashboard server feature.
Do not use.
This option tells ctest to include a notes file when submitting
dashboard.
``--timeout <seconds>``
Set a global timeout on all tests.
``--tomorrow-tag``
Nightly or experimental starts with next day tag.
This option will set a global timeout on all tests that do not
already have a timeout set on them.
This is useful if the build will not finish in one day.
``--stop-time <time>``
Set a time at which all tests should stop running.
``--extra-submit <file>[;<file>]``
Submit extra files to the dashboard.
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.
This option will submit extra files to the dashboard.
``--http1.0``
Submit using HTTP 1.0.
......@@ -392,26 +437,6 @@ Options
this to maintain compatibility with an older version of CDash which
doesn't support compressed test output.
``--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
.. _`Dashboard Client`:
Dashboard Client
================
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.
.. _`CDash`: http://cdash.org/
Dashboard Client Steps
----------------------
......@@ -1075,3 +1100,5 @@ See Also
========
.. include:: LINKS.txt
.. _`CDash`: http://cdash.org/
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment