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
-----------
Build the project.
Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`.
::
ctest_build([BUILD build_dir] [TARGET target] [RETURN_VALUE res]
[APPEND][NUMBER_ERRORS val] [NUMBER_WARNINGS val])
ctest_build([BUILD <build-dir>] [APPEND]
[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`` is given, the :variable:`CTEST_BINARY_DIRECTORY` variable is used.
Build the project and store results in ``Build.xml``
for submission with the :command:`ctest_submit` command.
The ``TARGET`` variable can be used to specify a build target. If none is
specified, the default target ("ALL_BUILD" for Visual Studio generators and
"all" in others) will be built.
The :variable:`CTEST_BUILD_COMMAND` variable may be set to explicitly
specify the build command line. Otherwise the build command line is
computed automatically based on the options given.
The ``RETURN_VALUE`` option specifies a variable in which to store the
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 options are:
The ``APPEND`` option marks results for append to those previously
submitted to a dashboard server since the last :command:`ctest_start`. Append
semantics are defined by the dashboard server in use.
``BUILD <build-dir>``
Specify the top-level build directory. If not given, the
:variable:`CTEST_BINARY_DIRECTORY` variable is used.
The ``QUIET`` option suppresses 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.
``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.
If set, the contents of the variable ``CTEST_BUILD_COMMAND`` is used to build
the project. In addition, if set, the contents of the variable
``CTEST_BUILD_FLAGS`` are passed as additional arguments to the underlying
build command. This can, e.g., be used to trigger a parallel build using the
``-j`` option of make. See :module:`ProcessorCount` for an example.
``CONFIGURATION <config>``
Specify the build configuration (e.g. ``Debug``). If not
specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked.
Otherwise the ``-C <cfg>`` option given to the :manual:`ctest(1)`
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
---------------
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]
[OPTIONS options] [RETURN_VALUE res] [QUIET])
ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
[OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET])
Configures the given build directory and stores results in
Configure.xml. If no BUILD is given, the CTEST_BINARY_DIRECTORY
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.
Configure the project build tree and record results in ``Configure.xml``
for submission with the :command:`ctest_submit` command.
The APPEND option marks results for append to those previously
submitted to a dashboard server since the last ctest_start. Append
semantics are defined by the dashboard server in use.
The options are:
The QUIET option suppresses any CTest-specific non-error messages
that would have otherwise been printed to the console. Output from
the underlying configure command is not affected.
``BUILD <build-dir>``
Specify the top-level build directory. If not given, the
: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
--------------
Collect coverage tool results.
Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`.
::
ctest_coverage([BUILD build_dir] [RETURN_VALUE res] [APPEND]
[LABELS label1 [label2 [...]]])
ctest_coverage([BUILD <build-dir>] [APPEND]
[LABELS <label>...]
[RETURN_VALUE <result-var>]
[QUIET]
)
Perform the coverage of the given build directory and stores results
in Coverage.xml. The second argument is a variable that will hold
value.
Collect coverage tool results and stores them in ``Coverage.xml``
for submission with the :command:`ctest_submit` command.
The LABELS option filters the coverage report to include only source
files labeled with at least one of the labels specified.
The options are:
The APPEND option marks results for append to those previously
submitted to a dashboard server since the last ctest_start. Append
semantics are defined by the dashboard server in use.
``BUILD <build-dir>``
Specify the top-level build directory. If not given, the
:variable:`CTEST_BINARY_DIRECTORY` variable is used.
The QUIET option suppresses 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.
``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.
``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
--------------
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]
[START start number] [END end number]
[STRIDE stride number] [EXCLUDE exclude regex ]
[INCLUDE include regex]
[EXCLUDE_LABEL exclude regex]
[INCLUDE_LABEL label regex]
[PARALLEL_LEVEL level] )
ctest_memcheck([BUILD <build-dir>] [APPEND]
[START <start-number>]
[END <end-number>]
[STRIDE <stride-number>]
[EXCLUDE <exclude-regex>]
[INCLUDE <include-regex>]
[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
submitted to a dashboard server since the last ctest_start. Append
semantics are defined by the dashboard server in use.
Run tests with a dynamic analysis tool and store results in
``MemCheck.xml`` for submission with the :command:`ctest_submit`
command.
The QUIET option suppresses any CTest-specific non-error messages
that would have otherwise been printed to the console. Output from
the underlying tests are not affected.
The options are the same as those for the :command:`ctest_test` command.

View File

@ -1,46 +1,55 @@
ctest_submit
------------
Submit results to a dashboard server.
Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`.
::
ctest_submit([PARTS ...] [FILES ...]
[RETRY_COUNT count]
[RETRY_DELAY delay]
[RETURN_VALUE res]
ctest_submit([PARTS <part>...] [FILES <file>...]
[RETRY_COUNT <count>]
[RETRY_DELAY <delay>]
[RETURN_VALUE <result-var>]
[QUIET]
)
By default all available parts are submitted if no PARTS or FILES are
specified. The PARTS option lists a subset of parts to be submitted.
Valid part names are:
Submit results to a dashboard server.
By default all available parts are submitted.
::
The options are:
Start = nothing
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
``PARTS <part>...``
Specify a subset of parts to submit. Valid part names are::
The FILES option explicitly lists specific files to be submitted.
Each individual file must exist at the time of the call.
Start = nothing
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
timed-out submission before attempting to re-submit.
``FILES <file>...``
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
submission.
``RETRY_COUNT <count>``
Specify how many times to retry a timed-out submission.
The QUIET option suppresses all non-error messages that would have
otherwise been printed by this call to ctest_submit().
``RETRY_DELAY <delay>``
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
^^^^^^^^^^^^^^^^^^^^^^^^^^

View File

@ -1,39 +1,79 @@
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]
[START start number] [END end number]
[STRIDE stride number] [EXCLUDE exclude regex ]
[INCLUDE include regex] [RETURN_VALUE res]
[EXCLUDE_LABEL exclude regex]
[INCLUDE_LABEL label regex]
[PARALLEL_LEVEL level]
[SCHEDULE_RANDOM on]
[STOP_TIME time of day])
ctest_test([BUILD <build-dir>] [APPEND]
[START <start-number>]
[END <end-number>]
[STRIDE <stride-number>]
[EXCLUDE <exclude-regex>]
[INCLUDE <include-regex>]
[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 Test.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
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.
Run tests in the project build tree and store results in
``Test.xml`` for submission with the :command:`ctest_submit` command.
The APPEND option marks results for append to those previously
submitted to a dashboard server since the last ctest_start. Append
semantics are defined by the dashboard server in use.
The options are:
The QUIET option suppresses 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.
``BUILD <build-dir>``
Specify the top-level build directory. If not given, the
:variable:`CTEST_BINARY_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.
``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
------------
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.
If no SOURCE is given, the CTEST_SOURCE_DIRECTORY variable is used.
The RETURN_VALUE option specifies a variable in which to store the
result, which is the number of files updated or -1 on error.
Update the source tree from version control and record results in
``Update.xml`` for submission with the :command:`ctest_submit` command.
If QUIET is specified then CTest will 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.
The options are:
``SOURCE <source-dir>``
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
------------
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
dashboard server.
The options are:
The QUIET option suppresses any CTest-specific non-error output
that would have been printed to the console otherwise.
``FILES <file>...``
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.