Help: Revise ctest_* command documentation (#15559)

Revise documentation for the major dashboard client step ``ctest_*``
commands.  Modernize the documentation formatting.  Add some missing
options.
This commit is contained in:
Brad King 2015-05-07 16:10:20 -04:00
parent f8716c8b44
commit 695d6f62d3
8 changed files with 275 additions and 152 deletions

View File

@ -1,36 +1,73 @@
ctest_build ctest_build
----------- -----------
Build the project. Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`.
:: ::
ctest_build([BUILD build_dir] [TARGET target] [RETURN_VALUE res] ctest_build([BUILD <build-dir>] [APPEND]
[APPEND][NUMBER_ERRORS val] [NUMBER_WARNINGS val]) [CONFIGURATION <config>]
[FLAGS <flags>]
[PROJECT_NAME <project-name>]
[TARGET <target-name>]
[NUMBER_ERRORS <num-err-var>]
[NUMBER_WARNINGS <num-warn-var>]
[RETURN_VALUE <result-var>]
)
Builds the given build directory and stores results in Build.xml. If no Build the project and store results in ``Build.xml``
``BUILD`` is given, the :variable:`CTEST_BINARY_DIRECTORY` variable is used. for submission with the :command:`ctest_submit` command.
The ``TARGET`` variable can be used to specify a build target. If none is The :variable:`CTEST_BUILD_COMMAND` variable may be set to explicitly
specified, the default target ("ALL_BUILD" for Visual Studio generators and specify the build command line. Otherwise the build command line is
"all" in others) will be built. computed automatically based on the options given.
The ``RETURN_VALUE`` option specifies a variable in which to store the The options are:
return value of the native build tool. The ``NUMBER_ERRORS`` and
``NUMBER_WARNINGS`` options specify variables in which to store the number
of build errors and warnings detected.
The ``APPEND`` option marks results for append to those previously ``BUILD <build-dir>``
submitted to a dashboard server since the last :command:`ctest_start`. Append Specify the top-level build directory. If not given, the
semantics are defined by the dashboard server in use. :variable:`CTEST_BINARY_DIRECTORY` variable is used.
The ``QUIET`` option suppresses any CTest-specific non-error output ``APPEND``
that would have been printed to the console otherwise. The summary Mark results for append to those previously submitted to a
of warnings / errors, as well as the output from the native build tool dashboard server since the last :command:`ctest_start` call.
is unaffected by this option. Append semantics are defined by the dashboard server in use.
If set, the contents of the variable ``CTEST_BUILD_COMMAND`` is used to build ``CONFIGURATION <config>``
the project. In addition, if set, the contents of the variable Specify the build configuration (e.g. ``Debug``). If not
``CTEST_BUILD_FLAGS`` are passed as additional arguments to the underlying specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked.
build command. This can, e.g., be used to trigger a parallel build using the Otherwise the ``-C <cfg>`` option given to the :manual:`ctest(1)`
``-j`` option of make. See :module:`ProcessorCount` for an example. command will be used, if any.
``FLAGS <flags>``
Pass additional arguments to the underlying build command.
If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked.
This can, e.g., be used to trigger a parallel build using the
``-j`` option of make. See the :module:`ProcessorCount` module
for an example.
``PROJECT_NAME <project-name>``
Set the name of the project to build. This should correspond
to the top-level call to the :command:`project` command.
If not specified the ``CTEST_PROJECT_NAME`` variable will be checked.
``TARGET <target-name>``
Specify the name of a target to build. If not specified the
``CTEST_BUILD_TARGET`` variable will be checked. Otherwise the
default target will be built. This is the "all" target
(called ``ALL_BUILD`` in :ref:`Visual Studio Generators`).
``NUMBER_ERRORS <num-err-var>``
Store the number of build errors detected in the given variable.
``NUMBER_WARNINGS <num-warn-var>``
Store the number of build warnings detected in the given variable.
``RETURN_VALUE <result-var>``
Store the return value of the native build tool in the given variable.
``QUIET``
Suppress any CTest-specific non-error output that would have been
printed to the console otherwise. The summary of warnings / errors,
as well as the output from the native build tool is unaffected by
this option.

View File

@ -1,25 +1,39 @@
ctest_configure ctest_configure
--------------- ---------------
Configure the project build tree. Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`.
:: ::
ctest_configure([BUILD build_dir] [SOURCE source_dir] [APPEND] ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
[OPTIONS options] [RETURN_VALUE res] [QUIET]) [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET])
Configures the given build directory and stores results in Configure the project build tree and record results in ``Configure.xml``
Configure.xml. If no BUILD is given, the CTEST_BINARY_DIRECTORY for submission with the :command:`ctest_submit` command.
variable is used. If no SOURCE is given, the CTEST_SOURCE_DIRECTORY
variable is used. The OPTIONS argument specifies command line
arguments to pass to the configuration tool. The RETURN_VALUE option
specifies a variable in which to store the return value of the native
build tool.
The APPEND option marks results for append to those previously The options are:
submitted to a dashboard server since the last ctest_start. Append
semantics are defined by the dashboard server in use.
The QUIET option suppresses any CTest-specific non-error messages ``BUILD <build-dir>``
that would have otherwise been printed to the console. Output from Specify the top-level build directory. If not given, the
the underlying configure command is not affected. :variable:`CTEST_BINARY_DIRECTORY` variable is used.
``SOURCE <source-dir>``
Specify the source directory. If not given, the
:variable:`CTEST_SOURCE_DIRECTORY` variable is used.
``APPEND``
Mark results for append to those previously submitted to a
dashboard server since the last :command:`ctest_start` call.
Append semantics are defined by the dashboard server in use.
``OPTIONS <options>``
Specify command-line arguments to pass to the configuration tool.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable the return value of the native
configuration tool.
``QUIET``
Suppress any CTest-specific non-error messages that would have
otherwise been printed to the console. Output from the underlying
configure command is not affected.

View File

@ -1,25 +1,39 @@
ctest_coverage ctest_coverage
-------------- --------------
Collect coverage tool results. Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`.
:: ::
ctest_coverage([BUILD build_dir] [RETURN_VALUE res] [APPEND] ctest_coverage([BUILD <build-dir>] [APPEND]
[LABELS label1 [label2 [...]]]) [LABELS <label>...]
[RETURN_VALUE <result-var>]
[QUIET]
)
Perform the coverage of the given build directory and stores results Collect coverage tool results and stores them in ``Coverage.xml``
in Coverage.xml. The second argument is a variable that will hold for submission with the :command:`ctest_submit` command.
value.
The LABELS option filters the coverage report to include only source The options are:
files labeled with at least one of the labels specified.
The APPEND option marks results for append to those previously ``BUILD <build-dir>``
submitted to a dashboard server since the last ctest_start. Append Specify the top-level build directory. If not given, the
semantics are defined by the dashboard server in use. :variable:`CTEST_BINARY_DIRECTORY` variable is used.
The QUIET option suppresses any CTest-specific non-error output ``APPEND``
that would have been printed to the console otherwise. The summary Mark results for append to those previously submitted to a
indicating how many lines of code were covered is unaffected by this dashboard server since the last :command:`ctest_start` call.
option. Append semantics are defined by the dashboard server in use.
``LABELS``
Filter the coverage report to include only source files labeled
with at least one of the labels specified.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable ``0`` if coverage tools
ran without error and non-zero otherwise.
``QUIET``
Suppress any CTest-specific non-error output that would have been
printed to the console otherwise. The summary indicating how many
lines of code were covered is unaffected by this option.

View File

@ -1,32 +1,28 @@
ctest_memcheck ctest_memcheck
-------------- --------------
Run tests with a dynamic analysis tool. Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`.
:: ::
ctest_memcheck([BUILD build_dir] [RETURN_VALUE res] [APPEND] ctest_memcheck([BUILD <build-dir>] [APPEND]
[START start number] [END end number] [START <start-number>]
[STRIDE stride number] [EXCLUDE exclude regex ] [END <end-number>]
[INCLUDE include regex] [STRIDE <stride-number>]
[EXCLUDE_LABEL exclude regex] [EXCLUDE <exclude-regex>]
[INCLUDE_LABEL label regex] [INCLUDE <include-regex>]
[PARALLEL_LEVEL level] ) [EXCLUDE_LABEL <label-exclude-regex>]
[INCLUDE_LABEL <label-include-regex>]
[PARALLEL_LEVEL <level>]
[SCHEDULE_RANDOM <ON|OFF>]
[STOP_TIME <time-of-day>]
[RETURN_VALUE <result-var>]
[QUIET]
)
Tests the given build directory and stores results in MemCheck.xml.
The second argument is a variable that will hold value. Optionally,
you can specify the starting test number START, the ending test number
END, the number of tests to skip between each test STRIDE, a regular
expression for tests to run INCLUDE, or a regular expression for tests
not to run EXCLUDE. EXCLUDE_LABEL and INCLUDE_LABEL are regular
expressions for tests to be included or excluded by the test property
LABEL. PARALLEL_LEVEL should be set to a positive number representing
the number of tests to be run in parallel.
The APPEND option marks results for append to those previously Run tests with a dynamic analysis tool and store results in
submitted to a dashboard server since the last ctest_start. Append ``MemCheck.xml`` for submission with the :command:`ctest_submit`
semantics are defined by the dashboard server in use. command.
The QUIET option suppresses any CTest-specific non-error messages The options are the same as those for the :command:`ctest_test` command.
that would have otherwise been printed to the console. Output from
the underlying tests are not affected.

View File

@ -1,46 +1,55 @@
ctest_submit ctest_submit
------------ ------------
Submit results to a dashboard server. Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`.
:: ::
ctest_submit([PARTS ...] [FILES ...] ctest_submit([PARTS <part>...] [FILES <file>...]
[RETRY_COUNT count] [RETRY_COUNT <count>]
[RETRY_DELAY delay] [RETRY_DELAY <delay>]
[RETURN_VALUE res] [RETURN_VALUE <result-var>]
[QUIET] [QUIET]
) )
By default all available parts are submitted if no PARTS or FILES are Submit results to a dashboard server.
specified. The PARTS option lists a subset of parts to be submitted. By default all available parts are submitted.
Valid part names are:
:: The options are:
Start = nothing ``PARTS <part>...``
Update = ctest_update results, in Update.xml Specify a subset of parts to submit. Valid part names are::
Configure = ctest_configure results, in Configure.xml
Build = ctest_build results, in Build.xml
Test = ctest_test results, in Test.xml
Coverage = ctest_coverage results, in Coverage.xml
MemCheck = ctest_memcheck results, in DynamicAnalysis.xml
Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
Upload = Files prepared for upload by ctest_upload(), in Upload.xml
Submit = nothing
The FILES option explicitly lists specific files to be submitted. Start = nothing
Each individual file must exist at the time of the call. Update = ctest_update results, in Update.xml
Configure = ctest_configure results, in Configure.xml
Build = ctest_build results, in Build.xml
Test = ctest_test results, in Test.xml
Coverage = ctest_coverage results, in Coverage.xml
MemCheck = ctest_memcheck results, in DynamicAnalysis.xml
Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
Upload = Files prepared for upload by ctest_upload(), in Upload.xml
Submit = nothing
The RETRY_DELAY option specifies how long in seconds to wait after a ``FILES <file>...``
timed-out submission before attempting to re-submit. Specify an explicit list of specific files to be submitted.
Each individual file must exist at the time of the call.
The RETRY_COUNT option specifies how many times to retry a timed-out ``RETRY_COUNT <count>``
submission. Specify how many times to retry a timed-out submission.
The QUIET option suppresses all non-error messages that would have ``RETRY_DELAY <delay>``
otherwise been printed by this call to ctest_submit(). Specify how long (in seconds) to wait after a timed-out submission
before attempting to re-submit.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable ``0`` for success and
non-zero on failure.
``QUIET``
Suppress all non-error messages that would have otherwise been
printed to the console.
Submit to CDash Upload API Submit to CDash Upload API
^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^

View File

@ -1,39 +1,79 @@
ctest_test ctest_test
---------- ----------
Run tests in the project build tree. Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
:: ::
ctest_test([BUILD build_dir] [APPEND] ctest_test([BUILD <build-dir>] [APPEND]
[START start number] [END end number] [START <start-number>]
[STRIDE stride number] [EXCLUDE exclude regex ] [END <end-number>]
[INCLUDE include regex] [RETURN_VALUE res] [STRIDE <stride-number>]
[EXCLUDE_LABEL exclude regex] [EXCLUDE <exclude-regex>]
[INCLUDE_LABEL label regex] [INCLUDE <include-regex>]
[PARALLEL_LEVEL level] [EXCLUDE_LABEL <label-exclude-regex>]
[SCHEDULE_RANDOM on] [INCLUDE_LABEL <label-include-regex>]
[STOP_TIME time of day]) [PARALLEL_LEVEL <level>]
[SCHEDULE_RANDOM <ON|OFF>]
[STOP_TIME <time-of-day>]
[RETURN_VALUE <result-var>]
[QUIET]
)
Tests the given build directory and stores results in Test.xml. The Run tests in the project build tree and store results in
second argument is a variable that will hold value. Optionally, you ``Test.xml`` for submission with the :command:`ctest_submit` command.
can specify the starting test number START, the ending test number
END, the number of tests to skip between each test STRIDE, a regular
expression for tests to run INCLUDE, or a regular expression for tests
to not run EXCLUDE. EXCLUDE_LABEL and INCLUDE_LABEL are regular
expression for test to be included or excluded by the test property
LABEL. PARALLEL_LEVEL should be set to a positive number representing
the number of tests to be run in parallel. SCHEDULE_RANDOM will
launch tests in a random order, and is typically used to detect
implicit test dependencies. STOP_TIME is the time of day at which the
tests should all stop running.
The APPEND option marks results for append to those previously The options are:
submitted to a dashboard server since the last ctest_start. Append
semantics are defined by the dashboard server in use.
The QUIET option suppresses any CTest-specific non-error messages ``BUILD <build-dir>``
that would have otherwise been printed to the console. Output from Specify the top-level build directory. If not given, the
the underlying test command is not affected. Summary info detailing :variable:`CTEST_BINARY_DIRECTORY` variable is used.
the percentage of passing tests is also unaffected by the QUIET
option. ``APPEND``
Mark results for append to those previously submitted to a
dashboard server since the last :command:`ctest_start` call.
Append semantics are defined by the dashboard server in use.
``START <start-number>``
Specify the beginning of a range of test numbers.
``END <end-number>``
Specify the end of a range of test numbers.
``STRIDE <stride-number>``
Specify the stride by which to step acorss a range of test numbers.
``EXCLUDE <exclude-regex>``
Specify a regular expression matching test names to exclude.
``INCLUDE <include-regex>``
Specify a regular expression matching test names to include.
Tests not matching this expression are excluded.
``EXCLUDE_LABEL <label-exclude-regex>``
Specify a regular expression matching test labels to exclude.
``INCLUDE_LABEL <label-include-regex>``
Specify a regular expression matching test labels to include.
Tests not matching this expression are excluded.
``PARALLEL_LEVEL <level>``
Specify a positive number representing the number of tests to
be run in parallel.
``SCHEDULE_RANDOM <ON|OFF>``
Launch tests in a random order. This may be useful for detecting
implicit test dependencies.
``STOP_TIME <time-of-day>``
Specify a time of day at which the tests should all stop running.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable ``0`` if all tests passed.
Store non-zero if anything went wrong.
``QUIET``
Suppress any CTest-specific non-error messages that would have otherwise
been printed to the console. Output from the underlying test command is not
affected. Summary info detailing the percentage of passing tests is also
unaffected by the ``QUIET`` option.

View File

@ -1,18 +1,27 @@
ctest_update ctest_update
------------ ------------
Update the work tree from version control. Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`.
:: ::
ctest_update([SOURCE source] [RETURN_VALUE res] [QUIET]) ctest_update([SOURCE <source-dir>] [RETURN_VALUE <result-var>] [QUIET])
Updates the given source directory and stores results in Update.xml. Update the source tree from version control and record results in
If no SOURCE is given, the CTEST_SOURCE_DIRECTORY variable is used. ``Update.xml`` for submission with the :command:`ctest_submit` command.
The RETURN_VALUE option specifies a variable in which to store the
result, which is the number of files updated or -1 on error.
If QUIET is specified then CTest will suppress most non-error The options are:
messages that it would have otherwise printed to the console.
CTest will still report the new revision of the repository ``SOURCE <source-dir>``
and any conflicting files that were found. Specify the source directory. If not given, the
:variable:`CTEST_SOURCE_DIRECTORY` variable is used.
``RETURN_VALUE <result-var>``
Store in the ``<result-var>`` variable the number of files
updated or ``-1`` on error.
``QUIET``
Tell CTest to suppress most non-error messages that it would
have otherwise printed to the console. CTest will still report
the new revision of the repository and any conflicting files
that were found.

View File

@ -1,14 +1,18 @@
ctest_upload ctest_upload
------------ ------------
Upload files to a dashboard server. Upload files to a dashboard server as a :ref:`Dashboard Client`.
:: ::
ctest_upload(FILES ... [QUIET]) ctest_upload(FILES <file>... [QUIET])
Pass a list of files to be sent along with the build results to the The options are:
dashboard server.
The QUIET option suppresses any CTest-specific non-error output ``FILES <file>...``
that would have been printed to the console otherwise. Specify a list of files to be sent along with the build results to the
dashboard server.
``QUIET``
Suppress any CTest-specific non-error output that would have been
printed to the console otherwise.