Help: Format manual/*.1.rst options as definition lists

Convert the command-line option documentation formatting from bullet
lists to definition lists.
This commit is contained in:
Kitware Robot 2013-11-14 10:05:32 -05:00 committed by Brad King
parent d592fc48cd
commit 3442f2bcc4
6 changed files with 527 additions and 417 deletions

View File

@ -1,18 +1,22 @@
The following resources are available to get help using CMake: The following resources are available to get help using CMake:
* ``Home Page``: http://www.cmake.org Home Page
http://www.cmake.org
The primary starting point for learning about CMake. The primary starting point for learning about CMake.
* ``Frequently Asked Questions``: http://www.cmake.org/Wiki/CMake_FAQ Frequently Asked Questions
http://www.cmake.org/Wiki/CMake_FAQ
A Wiki is provided containing answers to frequently asked questions. A Wiki is provided containing answers to frequently asked questions.
* ``Online Documentation``: http://www.cmake.org/HTML/Documentation.html Online Documentation
http://www.cmake.org/HTML/Documentation.html
Links to available documentation may be found on this web page. Links to available documentation may be found on this web page.
* ``Mailing List``: http://www.cmake.org/HTML/MailingLists.html Mailing List
http://www.cmake.org/HTML/MailingLists.html
For help and discussion about using cmake, a mailing list is For help and discussion about using cmake, a mailing list is
provided at cmake@cmake.org. The list is member-post-only but one provided at cmake@cmake.org. The list is member-post-only but one

View File

@ -1,4 +1,5 @@
* ``-C <initial-cache>``: Pre-load a script to populate the cache. ``-C <initial-cache>``
Pre-load a script to populate the cache.
When cmake is first run in an empty build tree, it creates a When cmake is first run in an empty build tree, it creates a
CMakeCache.txt file and populates it with customizable settings for CMakeCache.txt file and populates it with customizable settings for
@ -9,7 +10,8 @@
containing SET commands that use the CACHE option, not a containing SET commands that use the CACHE option, not a
cache-format file. cache-format file.
* ``-D <var>:<type>=<value>``: Create a cmake cache entry. ``-D <var>:<type>=<value>``
Create a cmake cache entry.
When cmake is first run in an empty build tree, it creates a When cmake is first run in an empty build tree, it creates a
CMakeCache.txt file and populates it with customizable settings for CMakeCache.txt file and populates it with customizable settings for
@ -17,7 +19,8 @@
takes priority over the project's default value. The option may be takes priority over the project's default value. The option may be
repeated for as many cache entries as desired. repeated for as many cache entries as desired.
* ``-U <globbing_expr>``: Remove matching entries from CMake cache. ``-U <globbing_expr>``
Remove matching entries from CMake cache.
This option may be used to remove one or more variables from the This option may be used to remove one or more variables from the
CMakeCache.txt file, globbing expressions using * and ? are CMakeCache.txt file, globbing expressions using * and ? are
@ -26,14 +29,16 @@
Use with care, you can make your CMakeCache.txt non-working. Use with care, you can make your CMakeCache.txt non-working.
* ``-G <generator-name>``: Specify a build system generator. ``-G <generator-name>``
Specify a build system generator.
CMake may support multiple native build systems on certain CMake may support multiple native build systems on certain
platforms. A generator is responsible for generating a particular platforms. A generator is responsible for generating a particular
build system. Possible generator names are specified in the build system. Possible generator names are specified in the
Generators section. Generators section.
* ``-T <toolset-name>``: Specify toolset name if supported by generator. ``-T <toolset-name>``
Specify toolset name if supported by generator.
Some CMake generators support a toolset name to be given to the Some CMake generators support a toolset name to be given to the
native build system to choose a compiler. This is supported only on native build system to choose a compiler. This is supported only on
@ -46,12 +51,14 @@
See native build system documentation for allowed toolset names. See native build system documentation for allowed toolset names.
* ``-Wno-dev``: Suppress developer warnings. ``-Wno-dev``
Suppress developer warnings.
Suppress warnings that are meant for the author of the Suppress warnings that are meant for the author of the
CMakeLists.txt files. CMakeLists.txt files.
* ``-Wdev``: Enable developer warnings. ``-Wdev``
Enable developer warnings.
Enable warnings that are meant for the author of the CMakeLists.txt Enable warnings that are meant for the author of the CMakeLists.txt
files. files.

View File

@ -1,110 +1,129 @@
.. |file| replace:: The help is printed to a named <f>ile if given. .. |file| replace:: The help is printed to a named <f>ile if given.
* ``--help,-help,-usage,-h,-H,/?``: Print usage information and exit. ``--help,-help,-usage,-h,-H,/?``
Print usage information and exit.
Usage describes the basic command line interface and its options. Usage describes the basic command line interface and its options.
* ``--version,-version,/V [<f>]``: Show program name/version banner and exit. ``--version,-version,/V [<f>]``
Show program name/version banner and exit.
If a file is specified, the version is written into it. If a file is specified, the version is written into it.
|file| |file|
* ``--help-manual <man> [<f>]``: Print one help manual and exit. ``--help-manual <man> [<f>]``
Print one help manual and exit.
The specified manual is printed in a human-readable text format. The specified manual is printed in a human-readable text format.
|file| |file|
* ``--help-manual-list [<f>]``: List help manuals available and exit. ``--help-manual-list [<f>]``
List help manuals available and exit.
The list contains all manuals for which help may be obtained by The list contains all manuals for which help may be obtained by
using the ``--help-manual`` option followed by a manual name. using the ``--help-manual`` option followed by a manual name.
|file| |file|
* ``--help-command <cmd> [<f>]``: Print help for one command and exit. ``--help-command <cmd> [<f>]``
Print help for one command and exit.
The :manual:`cmake-commands(7)` manual entry for ``<cmd>`` is The :manual:`cmake-commands(7)` manual entry for ``<cmd>`` is
printed in a human-readable text format. printed in a human-readable text format.
|file| |file|
* ``--help-command-list [<f>]``: List commands with help available and exit. ``--help-command-list [<f>]``
List commands with help available and exit.
The list contains all commands for which help may be obtained by The list contains all commands for which help may be obtained by
using the ``--help-command`` option followed by a command name. using the ``--help-command`` option followed by a command name.
|file| |file|
* ``--help-commands [<f>]``: Print cmake-commands manual and exit. ``--help-commands [<f>]``
Print cmake-commands manual and exit.
The :manual:`cmake-commands(7)` manual is printed in a The :manual:`cmake-commands(7)` manual is printed in a
human-readable text format. human-readable text format.
|file| |file|
* ``--help-module <mod> [<f>]``: Print help for one module and exit. ``--help-module <mod> [<f>]``
Print help for one module and exit.
The :manual:`cmake-modules(7)` manual entry for ``<mod>`` is printed The :manual:`cmake-modules(7)` manual entry for ``<mod>`` is printed
in a human-readable text format. in a human-readable text format.
|file| |file|
* ``--help-module-list [<f>]``: List modules with help available and exit. ``--help-module-list [<f>]``
List modules with help available and exit.
The list contains all modules for which help may be obtained by The list contains all modules for which help may be obtained by
using the ``--help-module`` option followed by a module name. using the ``--help-module`` option followed by a module name.
|file| |file|
* ``--help-modules [<f>]``: Print cmake-modules manual and exit. ``--help-modules [<f>]``
Print cmake-modules manual and exit.
The :manual:`cmake-modules(7)` manual is printed in a human-readable The :manual:`cmake-modules(7)` manual is printed in a human-readable
text format. text format.
|file| |file|
* ``--help-policy <cmp> [<f>]``: Print help for one policy and exit. ``--help-policy <cmp> [<f>]``
Print help for one policy and exit.
The :manual:`cmake-policies(7)` manual entry for ``<cmp>`` is The :manual:`cmake-policies(7)` manual entry for ``<cmp>`` is
printed in a human-readable text format. printed in a human-readable text format.
|file| |file|
* ``--help-policy-list [<f>]``: List policies with help available and exit. ``--help-policy-list [<f>]``
List policies with help available and exit.
The list contains all policies for which help may be obtained by The list contains all policies for which help may be obtained by
using the ``--help-policy`` option followed by a policy name. using the ``--help-policy`` option followed by a policy name.
|file| |file|
* ``--help-policies [<f>]``: Print cmake-policies manual and exit. ``--help-policies [<f>]``
Print cmake-policies manual and exit.
The :manual:`cmake-policies(7)` manual is printed in a The :manual:`cmake-policies(7)` manual is printed in a
human-readable text format. human-readable text format.
|file| |file|
* ``--help-property <prop> [<f>]``: Print help for one property and exit. ``--help-property <prop> [<f>]``
Print help for one property and exit.
The :manual:`cmake-properties(7)` manual entries for ``<prop>`` are The :manual:`cmake-properties(7)` manual entries for ``<prop>`` are
printed in a human-readable text format. printed in a human-readable text format.
|file| |file|
* ``--help-property-list [<f>]``: List properties with help available and exit. ``--help-property-list [<f>]``
List properties with help available and exit.
The list contains all properties for which help may be obtained by The list contains all properties for which help may be obtained by
using the ``--help-property`` option followed by a property name. using the ``--help-property`` option followed by a property name.
|file| |file|
* ``--help-properties [<f>]``: Print cmake-properties manual and exit. ``--help-properties [<f>]``
Print cmake-properties manual and exit.
The :manual:`cmake-properties(7)` manual is printed in a The :manual:`cmake-properties(7)` manual is printed in a
human-readable text format. human-readable text format.
|file| |file|
* ``--help-variable <var> [<f>]``: Print help for one variable and exit. ``--help-variable <var> [<f>]``
Print help for one variable and exit.
The :manual:`cmake-variables(7)` manual entry for ``<var>`` is The :manual:`cmake-variables(7)` manual entry for ``<var>`` is
printed in a human-readable text format. printed in a human-readable text format.
|file| |file|
* ``--help-variable-list [<f>]``: List variables with help available and exit. ``--help-variable-list [<f>]``
List variables with help available and exit.
The list contains all variables for which help may be obtained by The list contains all variables for which help may be obtained by
using the ``--help-variable`` option followed by a variable name. using the ``--help-variable`` option followed by a variable name.
|file| |file|
* ``--help-variables [<f>]``: Print cmake-variables manual and exit. ``--help-variables [<f>]``
Print cmake-variables manual and exit.
The :manual:`cmake-variables(7)` manual is printed in a The :manual:`cmake-variables(7)` manual is printed in a
human-readable text format. human-readable text format.

View File

@ -32,7 +32,8 @@ Options
.. include:: OPTIONS_BUILD.txt .. include:: OPTIONS_BUILD.txt
* ``-E``: CMake command mode. ``-E``
CMake command mode.
For true platform independence, CMake provides a list of commands For true platform independence, CMake provides a list of commands
that can be used on all systems. Run with -E help for the usage that can be used on all systems. Run with -E help for the usage
@ -43,7 +44,8 @@ Options
are available. On Windows: delete_regv, write_regv. On are available. On Windows: delete_regv, write_regv. On
UNIX: create_symlink. UNIX: create_symlink.
* ``-L[A][H]``: List non-advanced cached variables. ``-L[A][H]``
List non-advanced cached variables.
List cache variables will run CMake and list all the variables from List cache variables will run CMake and list all the variables from
the CMake cache that are not marked as INTERNAL or ADVANCED. This the CMake cache that are not marked as INTERNAL or ADVANCED. This
@ -53,7 +55,8 @@ Options
display also advanced variables. If H is specified, it will also display also advanced variables. If H is specified, it will also
display help for each variable. display help for each variable.
* ``--build <dir>``: Build a CMake-generated project binary tree. ``--build <dir>``
Build a CMake-generated project binary tree.
This abstracts a native build tool's command-line interface with the This abstracts a native build tool's command-line interface with the
following options: following options:
@ -70,38 +73,44 @@ Options
Run cmake --build with no options for quick help. Run cmake --build with no options for quick help.
* ``-N``: View mode only. ``-N``
View mode only.
Only load the cache. Do not actually run configure and generate Only load the cache. Do not actually run configure and generate
steps. steps.
* ``-P <file>``: Process script mode. ``-P <file>``
Process script mode.
Process the given cmake file as a script written in the CMake Process the given cmake file as a script written in the CMake
language. No configure or generate step is performed and the cache language. No configure or generate step is performed and the cache
is not modified. If variables are defined using -D, this must be is not modified. If variables are defined using -D, this must be
done before the -P argument. done before the -P argument.
* ``--find-package``: Run in pkg-config like mode. ``--find-package``
Run in pkg-config like mode.
Search a package using find_package() and print the resulting flags Search a package using find_package() and print the resulting flags
to stdout. This can be used to use cmake instead of pkg-config to to stdout. This can be used to use cmake instead of pkg-config to
find installed libraries in plain Makefile-based projects or in find installed libraries in plain Makefile-based projects or in
autoconf-based projects (via share/aclocal/cmake.m4). autoconf-based projects (via share/aclocal/cmake.m4).
* ``--graphviz=[file]``: Generate graphviz of dependencies, see CMakeGraphVizOptions.cmake for more. ``--graphviz=[file]``
Generate graphviz of dependencies, see CMakeGraphVizOptions.cmake for more.
Generate a graphviz input file that will contain all the library and Generate a graphviz input file that will contain all the library and
executable dependencies in the project. See the documentation for executable dependencies in the project. See the documentation for
CMakeGraphVizOptions.cmake for more details. CMakeGraphVizOptions.cmake for more details.
* ``--system-information [file]``: Dump information about this system. ``--system-information [file]``
Dump information about this system.
Dump a wide range of information about the current system. If run Dump a wide range of information about the current system. If run
from the top of a binary tree for a CMake project it will dump from the top of a binary tree for a CMake project it will dump
additional information such as the cache, log files etc. additional information such as the cache, log files etc.
* ``--debug-trycompile``: Do not delete the try_compile build tree. Only useful on one try_compile at a time. ``--debug-trycompile``
Do not delete the try_compile build tree. Only useful on one try_compile at a time.
Do not delete the files and directories created for try_compile Do not delete the files and directories created for try_compile
calls. This is useful in debugging failed try_compiles. It may calls. This is useful in debugging failed try_compiles. It may
@ -110,30 +119,36 @@ Options
fail incorrectly. This option is best used for one try-compile at a fail incorrectly. This option is best used for one try-compile at a
time, and only when debugging. time, and only when debugging.
* ``--debug-output``: Put cmake in a debug mode. ``--debug-output``
Put cmake in a debug mode.
Print extra stuff during the cmake run like stack traces with Print extra stuff during the cmake run like stack traces with
message(send_error ) calls. message(send_error ) calls.
* ``--trace``: Put cmake in trace mode. ``--trace``
Put cmake in trace mode.
Print a trace of all calls made and from where with Print a trace of all calls made and from where with
message(send_error ) calls. message(send_error ) calls.
* ``--warn-uninitialized``: Warn about uninitialized values. ``--warn-uninitialized``
Warn about uninitialized values.
Print a warning when an uninitialized variable is used. Print a warning when an uninitialized variable is used.
* ``--warn-unused-vars``: Warn about unused variables. ``--warn-unused-vars``
Warn about unused variables.
Find variables that are declared or set, but not used. Find variables that are declared or set, but not used.
* ``--no-warn-unused-cli``: Don't warn about command line options. ``--no-warn-unused-cli``
Don't warn about command line options.
Don't find variables that are declared on the command line, but not Don't find variables that are declared on the command line, but not
used. used.
* ``--check-system-vars``: Find problems with variable usage in system files. ``--check-system-vars``
Find problems with variable usage in system files.
Normally, unused and uninitialized variables are searched for only Normally, unused and uninitialized variables are searched for only
in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR. This flag tells CMake to in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR. This flag tells CMake to

View File

@ -27,54 +27,64 @@ native tool on their platform.
Options Options
======= =======
* ``-G <generator>``: Use the specified generator to generate package. ``-G <generator>``
Use the specified generator to generate package.
CPack may support multiple native packaging systems on certain CPack may support multiple native packaging systems on certain
platforms. A generator is responsible for generating input files platforms. A generator is responsible for generating input files
for particular system and invoking that systems. Possible generator for particular system and invoking that systems. Possible generator
names are specified in the Generators section. names are specified in the Generators section.
* ``-C <Configuration>``: Specify the project configuration ``-C <Configuration>``
Specify the project configuration
This option specifies the configuration that the project was build This option specifies the configuration that the project was build
with, for example 'Debug', 'Release'. with, for example 'Debug', 'Release'.
* ``-D <var>=<value>``: Set a CPack variable. ``-D <var>=<value>``
Set a CPack variable.
Set a variable that can be used by the generator. Set a variable that can be used by the generator.
* ``--config <config file>``: Specify the config file. ``--config <config file>``
Specify the config file.
Specify the config file to use to create the package. By default Specify the config file to use to create the package. By default
CPackConfig.cmake in the current directory will be used. CPackConfig.cmake in the current directory will be used.
* ``--verbose,-V``: enable verbose output ``--verbose,-V``
enable verbose output
Run cpack with verbose output. Run cpack with verbose output.
* ``--debug``: enable debug output (for CPack developers) ``--debug``
enable debug output (for CPack developers)
Run cpack with debug output (for CPack developers). Run cpack with debug output (for CPack developers).
* ``-P <package name>``: override/define CPACK_PACKAGE_NAME ``-P <package name>``
override/define CPACK_PACKAGE_NAME
If the package name is not specified on cpack commmand line If the package name is not specified on cpack commmand line
thenCPack.cmake defines it as CMAKE_PROJECT_NAME thenCPack.cmake defines it as CMAKE_PROJECT_NAME
* ``-R <package version>``: override/define CPACK_PACKAGE_VERSION ``-R <package version>``
override/define CPACK_PACKAGE_VERSION
If version is not specified on cpack command line thenCPack.cmake If version is not specified on cpack command line thenCPack.cmake
defines it from CPACK_PACKAGE_VERSION_[MAJOR|MINOR|PATCH]look into defines it from CPACK_PACKAGE_VERSION_[MAJOR|MINOR|PATCH]look into
CPack.cmake for detail CPack.cmake for detail
* ``-B <package directory>``: override/define CPACK_PACKAGE_DIRECTORY ``-B <package directory>``
override/define CPACK_PACKAGE_DIRECTORY
The directory where CPack will be doing its packaging work.The The directory where CPack will be doing its packaging work.The
resulting package will be found there. Inside this directoryCPack resulting package will be found there. Inside this directoryCPack
creates '_CPack_Packages' sub-directory which is theCPack temporary creates '_CPack_Packages' sub-directory which is theCPack temporary
directory. directory.
* ``--vendor <vendor name>``: override/define CPACK_PACKAGE_VENDOR ``--vendor <vendor name>``
override/define CPACK_PACKAGE_VENDOR
If vendor is not specified on cpack command line (or inside If vendor is not specified on cpack command line (or inside
CMakeLists.txt) thenCPack.cmake defines it with a default value CMakeLists.txt) thenCPack.cmake defines it with a default value

View File

@ -21,113 +21,133 @@ program will run the tests and report results.
Options Options
======= =======
* ``-C <cfg>, --build-config <cfg>``: Choose configuration to test. ``-C <cfg>, --build-config <cfg>``
Choose configuration to test.
Some CMake-generated build trees can have multiple build Some CMake-generated build trees can have multiple build
configurations in the same tree. This option can be used to specify configurations in the same tree. This option can be used to specify
which one should be tested. Example configurations are "Debug" and which one should be tested. Example configurations are "Debug" and
"Release". "Release".
* ``-V,--verbose``: Enable verbose output from tests. ``-V,--verbose``
Enable verbose output from tests.
Test output is normally suppressed and only summary information is Test output is normally suppressed and only summary information is
displayed. This option will show all test output. displayed. This option will show all test output.
* ``-VV,--extra-verbose``: Enable more verbose output from tests. ``-VV,--extra-verbose``
Enable more verbose output from tests.
Test output is normally suppressed and only summary information is Test output is normally suppressed and only summary information is
displayed. This option will show even more test output. displayed. This option will show even more test output.
* ``--debug``: Displaying more verbose internals of CTest. ``--debug``
Displaying more verbose internals of CTest.
This feature will result in a large number of output that is mostly This feature will result in a large number of output that is mostly
useful for debugging dashboard problems. useful for debugging dashboard problems.
* ``--output-on-failure``: Output anything outputted by the test program if the test should fail. This option can also be enabled by setting the environment variable CTEST_OUTPUT_ON_FAILURE ``--output-on-failure``
Output anything outputted by the test program if the test should fail. This option can also be enabled by setting the environment variable CTEST_OUTPUT_ON_FAILURE
* ``-F``: Enable failover. ``-F``
Enable failover.
This option allows ctest to resume a test set execution that was This option allows ctest to resume a test set execution that was
previously interrupted. If no interruption occurred, the -F option previously interrupted. If no interruption occurred, the -F option
will have no effect. will have no effect.
* ``-j <jobs>, --parallel <jobs>``: Run the tests in parallel using thegiven number of jobs. ``-j <jobs>, --parallel <jobs>``
Run the tests in parallel using thegiven number of jobs.
This option tells ctest to run the tests in parallel using given This option tells ctest to run the tests in parallel using given
number of jobs. This option can also be set by setting the number of jobs. This option can also be set by setting the
environment variable CTEST_PARALLEL_LEVEL. environment variable CTEST_PARALLEL_LEVEL.
* ``-Q,--quiet``: Make ctest quiet. ``-Q,--quiet``
Make ctest quiet.
This option will suppress all the output. The output log file will This option will suppress all the output. The output log file will
still be generated if the --output-log is specified. Options such still be generated if the --output-log is specified. Options such
as --verbose, --extra-verbose, and --debug are ignored if --quiet is as --verbose, --extra-verbose, and --debug are ignored if --quiet is
specified. specified.
* ``-O <file>, --output-log <file>``: Output to log file ``-O <file>, --output-log <file>``
Output to log file
This option tells ctest to write all its output to a log file. This option tells ctest to write all its output to a log file.
* ``-N,--show-only``: Disable actual execution of tests. ``-N,--show-only``
Disable actual execution of tests.
This option tells ctest to list the tests that would be run but not This option tells ctest to list the tests that would be run but not
actually run them. Useful in conjunction with the -R and -E actually run them. Useful in conjunction with the -R and -E
options. options.
* ``-L <regex>, --label-regex <regex>``: Run tests with labels matching regular expression. ``-L <regex>, --label-regex <regex>``
Run tests with labels matching regular expression.
This option tells ctest to run only the tests whose labels match the This option tells ctest to run only the tests whose labels match the
given regular expression. given regular expression.
* ``-R <regex>, --tests-regex <regex>``: Run tests matching regular expression. ``-R <regex>, --tests-regex <regex>``
Run tests matching regular expression.
This option tells ctest to run only the tests whose names match the This option tells ctest to run only the tests whose names match the
given regular expression. given regular expression.
* ``-E <regex>, --exclude-regex <regex>``: Exclude tests matching regular expression. ``-E <regex>, --exclude-regex <regex>``
Exclude tests matching regular expression.
This option tells ctest to NOT run the tests whose names match the This option tells ctest to NOT run the tests whose names match the
given regular expression. given regular expression.
* ``-LE <regex>, --label-exclude <regex>``: Exclude tests with labels matching regular expression. ``-LE <regex>, --label-exclude <regex>``
Exclude tests with labels matching regular expression.
This option tells ctest to NOT run the tests whose labels match the This option tells ctest to NOT run the tests whose labels match the
given regular expression. given regular expression.
* ``-D <dashboard>, --dashboard <dashboard>``: Execute dashboard test ``-D <dashboard>, --dashboard <dashboard>``
Execute dashboard test
This option tells ctest to act as a Dart client and perform a This option tells ctest to act as a Dart client and perform a
dashboard test. All tests are <Mode><Test>, where Mode can be dashboard test. All tests are <Mode><Test>, where Mode can be
Experimental, Nightly, and Continuous, and Test can be Start, Experimental, Nightly, and Continuous, and Test can be Start,
Update, Configure, Build, Test, Coverage, and Submit. Update, Configure, Build, Test, Coverage, and Submit.
* ``-D <var>:<type>=<value>``: Define a variable for script mode ``-D <var>:<type>=<value>``
Define a variable for script mode
Pass in variable values on the command line. Use in conjunction Pass in variable values on the command line. Use in conjunction
with -S to pass variable values to a dashboard script. Parsing -D with -S to pass variable values to a dashboard script. Parsing -D
arguments as variable values is only attempted if the value arguments as variable values is only attempted if the value
following -D does not match any of the known dashboard types. following -D does not match any of the known dashboard types.
* ``-M <model>, --test-model <model>``: Sets the model for a dashboard ``-M <model>, --test-model <model>``
Sets the model for a dashboard
This option tells ctest to act as a Dart client where the TestModel This option tells ctest to act as a Dart client where the TestModel
can be Experimental, Nightly, and Continuous. Combining -M and -T can be Experimental, Nightly, and Continuous. Combining -M and -T
is similar to -D is similar to -D
* ``-T <action>, --test-action <action>``: Sets the dashboard action to perform ``-T <action>, --test-action <action>``
Sets the dashboard action to perform
This option tells ctest to act as a Dart client and perform some This option tells ctest to act as a Dart client and perform some
action such as start, build, test etc. Combining -M and -T is action such as start, build, test etc. Combining -M and -T is
similar to -D similar to -D
* ``--track <track>``: Specify the track to submit dashboard to ``--track <track>``
Specify the track to submit dashboard to
Submit dashboard to specified track instead of default one. By Submit dashboard to specified track instead of default one. By
default, the dashboard is submitted to Nightly, Experimental, or default, the dashboard is submitted to Nightly, Experimental, or
Continuous track, but by specifying this option, the track can be Continuous track, but by specifying this option, the track can be
arbitrary. arbitrary.
* ``-S <script>, --script <script>``: Execute a dashboard for a configuration ``-S <script>, --script <script>``
Execute a dashboard for a configuration
This option tells ctest to load in a configuration script which sets This option tells ctest to load in a configuration script which sets
a number of parameters such as the binary and source directories. a number of parameters such as the binary and source directories.
@ -135,19 +155,22 @@ Options
This option basically sets up a dashboard and then runs ctest -D This option basically sets up a dashboard and then runs ctest -D
with the appropriate options. with the appropriate options.
* ``-SP <script>, --script-new-process <script>``: Execute a dashboard for a configuration ``-SP <script>, --script-new-process <script>``
Execute a dashboard for a configuration
This option does the same operations as -S but it will do them in a This option does the same operations as -S but it will do them in a
separate process. This is primarily useful in cases where the separate process. This is primarily useful in cases where the
script may modify the environment and you do not want the modified script may modify the environment and you do not want the modified
environment to impact other -S scripts. environment to impact other -S scripts.
* ``-A <file>, --add-notes <file>``: Add a notes file with submission ``-A <file>, --add-notes <file>``
Add a notes file with submission
This option tells ctest to include a notes file when submitting This option tells ctest to include a notes file when submitting
dashboard. dashboard.
* ``-I [Start,End,Stride,test#,test#|Test file], --tests-information``: Run a specific number of tests by number. ``-I [Start,End,Stride,test#,test#|Test file], --tests-information``
Run a specific number of tests by number.
This option causes ctest to run tests starting at number Start, This option causes ctest to run tests starting at number Start,
ending at number End, and incrementing by Stride. Any additional ending at number End, and incrementing by Stride. Any additional
@ -155,12 +178,14 @@ Options
End,or stride can be empty. Optionally a file can be given that End,or stride can be empty. Optionally a file can be given that
contains the same syntax as the command line. contains the same syntax as the command line.
* ``-U, --union``: Take the Union of -I and -R ``-U, --union``
Take the Union of -I and -R
When both -R and -I are specified by default the intersection of 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. tests are run. By specifying -U the union of tests is run instead.
* ``--rerun-failed``: Run only the tests that failed previously ``--rerun-failed``
Run only the tests that failed previously
This option tells ctest to perform only the tests that failed during This option tells ctest to perform only the tests that failed during
its previous run. When this option is specified, ctest ignores all its previous run. When this option is specified, ctest ignores all
@ -169,13 +194,15 @@ Options
subsequent calls to ctest with the --rerun-failed option will run subsequent calls to ctest with the --rerun-failed option will run
the set of tests that most recently failed (if any). the set of tests that most recently failed (if any).
* ``--max-width <width>``: Set the max width for a test name to output ``--max-width <width>``
Set the max width for a test name to output
Set the maximum width for each test name to show in the output. 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 This allows the user to widen the output to avoid clipping the test
name which can be very annoying. name which can be very annoying.
* ``--interactive-debug-mode [0|1]``: Set the interactive mode to 0 or 1. ``--interactive-debug-mode [0|1]``
Set the interactive mode to 0 or 1.
This option causes ctest to run tests in either an interactive mode This option causes ctest to run tests in either an interactive mode
or a non-interactive mode. On Windows this means that in or a non-interactive mode. On Windows this means that in
@ -184,13 +211,15 @@ Options
is non-interactive. When just running tests not for a dashboard the is non-interactive. When just running tests not for a dashboard the
default is to allow popups and interactive debugging. default is to allow popups and interactive debugging.
* ``--no-label-summary``: Disable timing summary information for labels. ``--no-label-summary``
Disable timing summary information for labels.
This option tells ctest not to print summary information for each This option tells ctest not to print summary information for each
label associated with the tests run. If there are no labels on the label associated with the tests run. If there are no labels on the
tests, nothing extra is printed. tests, nothing extra is printed.
* ``--build-and-test``: Configure, build and run a test. ``--build-and-test``
Configure, build and run a test.
This option tells ctest to configure (i.e. run cmake on), build, This option tells ctest to configure (i.e. run cmake on), build,
and or execute a test. The configure and test steps are optional. and or execute a test. The configure and test steps are optional.
@ -204,106 +233,132 @@ Options
--build-two-config, --build-exe-dir, --build-two-config, --build-exe-dir,
--build-project,--build-noclean, --build-options --build-project,--build-noclean, --build-options
* ``--build-target``: Specify a specific target to build. ``--build-target``
Specify a specific target to build.
This option goes with the --build-and-test option, if left out the This option goes with the --build-and-test option, if left out the
all target is built. all target is built.
* ``--build-nocmake``: Run the build without running cmake first. ``--build-nocmake``
Run the build without running cmake first.
Skip the cmake step. Skip the cmake step.
* ``--build-run-dir``: Specify directory to run programs from. ``--build-run-dir``
Specify directory to run programs from.
Directory where programs will be after it has been compiled. Directory where programs will be after it has been compiled.
* ``--build-two-config``: Run CMake twice ``--build-two-config``
Run CMake twice
* ``--build-exe-dir``: Specify the directory for the executable. ``--build-exe-dir``
Specify the directory for the executable.
* ``--build-generator``: Specify the generator to use. ``--build-generator``
Specify the generator to use.
* ``--build-generator-toolset``: Specify the generator-specific toolset. ``--build-generator-toolset``
Specify the generator-specific toolset.
* ``--build-project``: Specify the name of the project to build. ``--build-project``
Specify the name of the project to build.
* ``--build-makeprogram``: Specify the make program to use. ``--build-makeprogram``
Specify the make program to use.
* ``--build-noclean``: Skip the make clean step. ``--build-noclean``
Skip the make clean step.
* ``--build-config-sample``: A sample executable to use to determine the configuration ``--build-config-sample``
A sample executable to use to determine the configuration
A sample executable to use to determine the configuration that A sample executable to use to determine the configuration that
should be used. e.g. Debug/Release/etc should be used. e.g. Debug/Release/etc
* ``--build-options``: Add extra options to the build step. ``--build-options``
Add extra options to the build step.
This option must be the last option with the exception of This option must be the last option with the exception of
--test-command --test-command
* ``--test-command``: The test to run with the --build-and-test option. ``--test-command``
The test to run with the --build-and-test option.
* ``--test-timeout``: The time limit in seconds, internal use only. ``--test-timeout``
The time limit in seconds, internal use only.
* ``--tomorrow-tag``: Nightly or experimental starts with next day tag. ``--tomorrow-tag``
Nightly or experimental starts with next day tag.
This is useful if the build will not finish in one day. This is useful if the build will not finish in one day.
* ``--ctest-config``: The configuration file used to initialize CTest state when submitting dashboards. ``--ctest-config``
The configuration file used to initialize CTest state when submitting dashboards.
This option tells CTest to use different initialization file instead This option tells CTest to use different initialization file instead
of CTestConfiguration.tcl. This way multiple initialization files of CTestConfiguration.tcl. This way multiple initialization files
can be used for example to submit to multiple dashboards. can be used for example to submit to multiple dashboards.
* ``--overwrite``: Overwrite CTest configuration option. ``--overwrite``
Overwrite CTest configuration option.
By default ctest uses configuration options from configuration file. By default ctest uses configuration options from configuration file.
This option will overwrite the configuration option. This option will overwrite the configuration option.
* ``--extra-submit <file>[;<file>]``: Submit extra files to the dashboard. ``--extra-submit <file>[;<file>]``
Submit extra files to the dashboard.
This option will submit extra files to the dashboard. This option will submit extra files to the dashboard.
* ``--force-new-ctest-process``: Run child CTest instances as new processes ``--force-new-ctest-process``
Run child CTest instances as new processes
By default CTest will run child CTest instances within the same By default CTest will run child CTest instances within the same
process. If this behavior is not desired, this argument will process. If this behavior is not desired, this argument will
enforce new processes for child CTest processes. enforce new processes for child CTest processes.
* ``--schedule-random``: Use a random order for scheduling tests ``--schedule-random``
Use a random order for scheduling tests
This option will run the tests in a random order. It is commonly This option will run the tests in a random order. It is commonly
used to detect implicit dependencies in a test suite. used to detect implicit dependencies in a test suite.
* ``--submit-index``: Submit individual dashboard tests with specific index ``--submit-index``
Submit individual dashboard tests with specific index
This option allows performing the same CTest action (such as test) This option allows performing the same CTest action (such as test)
multiple times and submit all stages to the same dashboard (Dart2 multiple times and submit all stages to the same dashboard (Dart2
required). Each execution requires different index. required). Each execution requires different index.
* ``--timeout <seconds>``: Set a global timeout on all tests. ``--timeout <seconds>``
Set a global timeout on all tests.
This option will set a global timeout on all tests that do not This option will set a global timeout on all tests that do not
already have a timeout set on them. already have a timeout set on them.
* ``--stop-time <time>``: Set a time at which all tests should stop running. ``--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: 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 7:00:00 -0400. Any time format understood by the curl date parser
is accepted. Local time is assumed if no timezone is specified. is accepted. Local time is assumed if no timezone is specified.
* ``--http1.0``: Submit using HTTP 1.0. ``--http1.0``
Submit using HTTP 1.0.
This option will force CTest to use HTTP 1.0 to submit files to the This option will force CTest to use HTTP 1.0 to submit files to the
dashboard, instead of HTTP 1.1. dashboard, instead of HTTP 1.1.
* ``--no-compress-output``: Do not compress test output when submitting. ``--no-compress-output``
Do not compress test output when submitting.
This flag will turn off automatic compression of test output. Use This flag will turn off automatic compression of test output. Use
this to maintain compatibility with an older version of CDash which this to maintain compatibility with an older version of CDash which
doesn't support compressed test output. doesn't support compressed test output.
* ``--print-labels``: Print all available test labels. ``--print-labels``
Print all available test labels.
This option will not run any tests, it will simply print the list of This option will not run any tests, it will simply print the list of
all labels associated with the test set. all labels associated with the test set.