mirror of
https://github.com/Kitware/CMake.git
synced 2025-12-31 10:50:16 -06:00
Help: Split ctest options into groups like cmake man page has
Co-Authored-By: Craig Scott <craig.scott@crascit.com>
This commit is contained in:
Alex Turbov
@@ -1,4 +1,9 @@
|
||||
.. |file| replace:: The help is printed to a named ``<file>`` if given.
|
||||
.. |file| replace:: The output is printed to a named ``<file>`` if given.
|
||||
|
||||
.. option:: -version [<file>], --version [<file>], /V [<file>]
|
||||
|
||||
Show program name/version banner and exit.
|
||||
|file|
|
||||
|
||||
.. option:: -h, -H, --help, -help, -usage, /?
|
||||
|
||||
@@ -6,13 +11,6 @@
|
||||
|
||||
Usage describes the basic command line interface and its options.
|
||||
|
||||
.. option:: -version [<file>], --version [<file>], /V [<file>]
|
||||
|
||||
Show program name/version banner and exit.
|
||||
|
||||
If a file is specified, the version is written into it.
|
||||
|file|
|
||||
|
||||
.. option:: --help-full [<file>]
|
||||
|
||||
Print all help manuals and exit.
|
||||
|
||||
@@ -10,12 +10,24 @@ Synopsis
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
ctest [<options>]
|
||||
ctest --build-and-test <path-to-source> <path-to-build>
|
||||
--build-generator <generator> [<options>...]
|
||||
[--build-options <opts>...] [--test-command <command> [<args>...]]
|
||||
ctest {-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>}
|
||||
[-- <dashboard-options>...]
|
||||
`Run Tests`_
|
||||
ctest [<options>]
|
||||
|
||||
`Build and Test Mode`_
|
||||
ctest --build-and-test <path-to-source> <path-to-build>
|
||||
--build-generator <generator> [<options>...]
|
||||
[--build-options <opts>...]
|
||||
[--test-command <command> [<args>...]]
|
||||
|
||||
`Dashboard Client`_
|
||||
ctest -D <dashboard> [-- <dashboard-options>...]
|
||||
ctest -M <model> -T <action> [-- <dashboard-options>...]
|
||||
ctest -S <script> [-- <dashboard-options>...]
|
||||
ctest -SP <script> [-- <dashboard-options>...]
|
||||
|
||||
`View Help`_
|
||||
ctest --help[-<topic>]
|
||||
|
||||
|
||||
Description
|
||||
===========
|
||||
@@ -25,14 +37,13 @@ CMake-generated build trees created for projects that use the
|
||||
:command:`enable_testing` and :command:`add_test` commands have testing support.
|
||||
This program will run the tests and report results.
|
||||
|
||||
.. _`CTest Options`:
|
||||
.. _`Run Tests`:
|
||||
|
||||
Options
|
||||
=======
|
||||
Run Tests
|
||||
=========
|
||||
|
||||
.. program:: ctest
|
||||
|
||||
|
||||
.. option:: --preset <preset>, --preset=<preset>
|
||||
|
||||
Use a test preset to specify test options. The project binary directory
|
||||
@@ -239,73 +250,6 @@ Options
|
||||
Same as :option:`-FA <ctest -FA>` except only matching cleanup tests are
|
||||
excluded.
|
||||
|
||||
.. option:: -D <dashboard>, --dashboard <dashboard>
|
||||
|
||||
Execute dashboard test.
|
||||
|
||||
This option tells CTest to act as a CDash client and perform a
|
||||
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``.
|
||||
|
||||
See `Dashboard Client`_.
|
||||
|
||||
.. option:: -D <var>:<type>=<value>
|
||||
|
||||
Define a variable for script mode.
|
||||
|
||||
Pass in variable values on the command line. Use in conjunction
|
||||
with :option:`-S <ctest -S>` to pass variable values to a dashboard script.
|
||||
Parsing ``-D`` arguments as variable values is only attempted if the value
|
||||
following ``-D`` does not match any of the known dashboard types.
|
||||
|
||||
.. option:: -M <model>, --test-model <model>
|
||||
|
||||
Sets the model for a dashboard.
|
||||
|
||||
This option tells CTest to act as a CDash client where the ``<model>``
|
||||
can be ``Experimental``, ``Nightly``, and ``Continuous``.
|
||||
Combining ``-M`` and :option:`-T <ctest -T>` is similar to
|
||||
:option:`-D <ctest -D>`.
|
||||
|
||||
See `Dashboard Client`_.
|
||||
|
||||
.. option:: -T <action>, --test-action <action>
|
||||
|
||||
Sets the dashboard action to perform.
|
||||
|
||||
This option tells CTest to act as a CDash client and perform some
|
||||
action such as ``start``, ``build``, ``test`` etc. See
|
||||
`Dashboard Client Steps`_ for the full list of actions.
|
||||
Combining :option:`-M <ctest -M>` and ``-T`` is similar to
|
||||
:option:`-D <ctest -D>`.
|
||||
|
||||
See `Dashboard Client`_.
|
||||
|
||||
.. option:: -S <script>, --script <script>
|
||||
|
||||
Execute a dashboard for a configuration.
|
||||
|
||||
This option tells CTest to load in a configuration script which sets
|
||||
a number of parameters such as the binary and source directories.
|
||||
Then CTest will do what is required to create and run a dashboard.
|
||||
This option basically sets up a dashboard and then runs :option:`ctest -D`
|
||||
with the appropriate options.
|
||||
|
||||
See `Dashboard Client`_.
|
||||
|
||||
.. option:: -SP <script>, --script-new-process <script>
|
||||
|
||||
Execute a dashboard for a configuration.
|
||||
|
||||
This option does the same operations as :option:`-S <ctest -S>` but it
|
||||
will do them in a separate process. This is primarily useful in cases
|
||||
where the script may modify the environment and you do not want the modified
|
||||
environment to impact other :option:`-S <ctest -S>` scripts.
|
||||
|
||||
See `Dashboard Client`_.
|
||||
|
||||
.. option:: -I [Start,End,Stride,test#,test#|Test file], --tests-information
|
||||
|
||||
Run a specific number of tests by number.
|
||||
@@ -402,10 +346,6 @@ Options
|
||||
|
||||
See `Label and Subproject Summary`_.
|
||||
|
||||
.. option:: --build-and-test
|
||||
|
||||
See `Build and Test Mode`_.
|
||||
|
||||
.. option:: --test-dir <dir>
|
||||
|
||||
Specify the directory in which to look for tests.
|
||||
@@ -488,6 +428,12 @@ Options
|
||||
unifies the behavior of CTest by either returning an error code if no tests
|
||||
were found or by ignoring it.
|
||||
|
||||
View Help
|
||||
=========
|
||||
|
||||
To print version details or selected pages from the CMake documentation,
|
||||
use one of the following options:
|
||||
|
||||
.. include:: OPTIONS_HELP.txt
|
||||
|
||||
.. _`Label Matching`:
|
||||
@@ -597,6 +543,10 @@ 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:
|
||||
|
||||
.. option:: --build-and-test
|
||||
|
||||
Switch into the build and test mode.
|
||||
|
||||
.. option:: --build-target
|
||||
|
||||
Specify a specific target to build.
|
||||
@@ -681,11 +631,78 @@ 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::
|
||||
|
||||
ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>)
|
||||
[-- <dashboard-options>...]
|
||||
ctest -D <dashboard> [-- <dashboard-options>...]
|
||||
ctest -M <model> -T <action> [-- <dashboard-options>...]
|
||||
ctest -S <script> [-- <dashboard-options>...]
|
||||
ctest -SP <script> [-- <dashboard-options>...]
|
||||
|
||||
Options for Dashboard Client include:
|
||||
|
||||
.. option:: -D <dashboard>, --dashboard <dashboard>
|
||||
|
||||
Execute dashboard test.
|
||||
|
||||
This option tells CTest to act as a CDash client and perform a
|
||||
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``.
|
||||
|
||||
If ``<dashboard>`` is not one of the recognized ``<Mode><Test>`` values,
|
||||
this will be treated as a variable definition instead (see the
|
||||
:ref:`dashboard-options <Dashboard Options>` further below).
|
||||
|
||||
.. option:: -M <model>, --test-model <model>
|
||||
|
||||
Sets the model for a dashboard.
|
||||
|
||||
This option tells CTest to act as a CDash client where the ``<model>``
|
||||
can be ``Experimental``, ``Nightly``, and ``Continuous``.
|
||||
Combining ``-M`` and :option:`-T <ctest -T>` is similar to
|
||||
:option:`-D <ctest -D>`.
|
||||
|
||||
.. option:: -T <action>, --test-action <action>
|
||||
|
||||
Sets the dashboard action to perform.
|
||||
|
||||
This option tells CTest to act as a CDash client and perform some
|
||||
action such as ``start``, ``build``, ``test`` etc. See
|
||||
`Dashboard Client Steps`_ for the full list of actions.
|
||||
Combining :option:`-M <ctest -M>` and ``-T`` is similar to
|
||||
:option:`-D <ctest -D>`.
|
||||
|
||||
.. option:: -S <script>, --script <script>
|
||||
|
||||
Execute a dashboard for a configuration.
|
||||
|
||||
This option tells CTest to load in a configuration script which sets
|
||||
a number of parameters such as the binary and source directories.
|
||||
Then CTest will do what is required to create and run a dashboard.
|
||||
This option basically sets up a dashboard and then runs :option:`ctest -D`
|
||||
with the appropriate options.
|
||||
|
||||
.. option:: -SP <script>, --script-new-process <script>
|
||||
|
||||
Execute a dashboard for a configuration.
|
||||
|
||||
This option does the same operations as :option:`-S <ctest -S>` but it
|
||||
will do them in a separate process. This is primarily useful in cases
|
||||
where the script may modify the environment and you do not want the modified
|
||||
environment to impact other :option:`-S <ctest -S>` scripts.
|
||||
|
||||
.. _`Dashboard Options`:
|
||||
|
||||
The available ``<dashboard-options>`` are the following:
|
||||
|
||||
.. option:: -D <var>:<type>=<value>
|
||||
|
||||
Define a variable for script mode.
|
||||
|
||||
Pass in variable values on the command line. Use in conjunction
|
||||
with :option:`-S <ctest -S>` to pass variable values to a dashboard script.
|
||||
Parsing ``-D`` arguments as variable values is only attempted if the value
|
||||
following ``-D`` does not match any of the known dashboard types.
|
||||
|
||||
.. option:: --group <group>
|
||||
|
||||
Specify what group you'd like to submit results to
|
||||
|
||||
Reference in New Issue
Block a user