kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge topic 'doc-ctest-command-formatting' 

695d6f62 Help: Revise ctest_* command documentation (#15559)
f8716c8b Help: Update cmake-generators(7) organization for GHS
This commit is contained in:
Brad King 2015-05-08 09:41:24 -04:00 committed by CMake Topic Stage
parent 715b3edf7d 695d6f62d3
commit 6831f91a6c
9 changed files with 278 additions and 155 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
Help/command/ctest_build.rst
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.

46
Help/command/ctest_configure.rst
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.

44
Help/command/ctest_coverage.rst
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.

42
Help/command/ctest_memcheck.rst
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.

43
Help/command/ctest_submit.rst
View File

@ -1,22 +1,24 @@
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:
``PARTS <part>...``
Specify a subset of parts to submit. Valid part names are::
Start = nothing
Update = ctest_update results, in Update.xml
@ -30,17 +32,24 @@ Valid part names are:
Upload = Files prepared for upload by ctest_upload(), in Upload.xml
Submit = nothing
The FILES option explicitly lists specific files to be submitted.
Each individual file must exist at the time of the call.
``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_DELAY option specifies how long in seconds to wait after a
timed-out submission before attempting to re-submit.
``RETRY_COUNT <count>``
Specify how many times to retry a timed-out submission.
The RETRY_COUNT option specifies how many times to retry a timed-out
submission.
``RETRY_DELAY <delay>``
Specify how long (in seconds) to wait after a timed-out submission
before attempting to re-submit.
The QUIET option suppresses all non-error messages that would have
otherwise been printed by this call to ctest_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
^^^^^^^^^^^^^^^^^^^^^^^^^^

100
Help/command/ctest_test.rst
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.

29
Help/command/ctest_update.rst
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.

16
Help/command/ctest_upload.rst
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.

6
Help/manual/cmake-generators.7.rst
View File

@ -73,7 +73,6 @@ Visual Studio Generators
.. toctree::
:maxdepth: 1
/generator/Green Hills MULTI
/generator/Visual Studio 6
/generator/Visual Studio 7
/generator/Visual Studio 7 .NET 2003
@ -84,12 +83,13 @@ Visual Studio Generators
/generator/Visual Studio 12 2013
/generator/Visual Studio 14 2015
Xcode Generator
^^^^^^^^^^^^^^^
Other Generators
^^^^^^^^^^^^^^^^
.. toctree::
:maxdepth: 1
/generator/Green Hills MULTI
/generator/Xcode
Extra Generators