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

Modules/CTest: Improve documentation formatting 

Use inline reStructuredText markup and add cross-references.
This commit is contained in:
Brad King 2015-04-27 10:32:53 -04:00
parent 5cbedd6b85
commit f693c136f9
1 changed files with 26 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
Modules/CTest.cmake
View File

@ -5,61 +5,53 @@ CTest
Configure a project for testing with CTest/CDash
Include this module in the top CMakeLists.txt file of a project to
enable testing with CTest and dashboard submissions to CDash:
enable testing with CTest and dashboard submissions to CDash::
::
project(MyProject)
...
include(CTest)
project(MyProject)
...
include(CTest)
The module automatically creates a ``BUILD_TESTING`` option that selects
whether to enable testing support (``ON`` by default). After including
the module, use code like::
The module automatically creates a BUILD_TESTING option that selects
whether to enable testing support (ON by default). After including
the module, use code like
::
if(BUILD_TESTING)
# ... CMake code to create tests ...
endif()
if(BUILD_TESTING)
# ... CMake code to create tests ...
endif()
to creating tests when testing is enabled.
To enable submissions to a CDash server, create a CTestConfig.cmake
file at the top of the project with content such as
To enable submissions to a CDash server, create a ``CTestConfig.cmake``
file at the top of the project with content such as::
::
set(CTEST_PROJECT_NAME "MyProject")
set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
set(CTEST_DROP_METHOD "http")
set(CTEST_DROP_SITE "my.cdash.org")
set(CTEST_DROP_LOCATION "/submit.php?project=MyProject")
set(CTEST_DROP_SITE_CDASH TRUE)
set(CTEST_PROJECT_NAME "MyProject")
set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
set(CTEST_DROP_METHOD "http")
set(CTEST_DROP_SITE "my.cdash.org")
set(CTEST_DROP_LOCATION "/submit.php?project=MyProject")
set(CTEST_DROP_SITE_CDASH TRUE)
(the CDash server can provide the file to a project administrator who
configures 'MyProject'). Settings in the config file are shared by
both this CTest module and the CTest command-line tool's dashboard
script mode (ctest -S).
configures ``MyProject``). Settings in the config file are shared by
both this ``CTest`` module and the :manual:`ctest(1)` command-line
:ref:`Dashboard Client` mode (``ctest -S``).
While building a project for submission to CDash, CTest scans the
build output for errors and warnings and reports them with surrounding
context from the build log. This generic approach works for all build
tools, but does not give details about the command invocation that
produced a given problem. One may get more detailed reports by adding
produced a given problem. One may get more detailed reports by adding::
::
set(CTEST_USE_LAUNCHERS 1)
set(CTEST_USE_LAUNCHERS 1)
to the CTestConfig.cmake file. When this option is enabled, the CTest
to the ``CTestConfig.cmake`` file. When this option is enabled, the CTest
module tells CMake's Makefile generators to invoke every command in
the generated build system through a CTest launcher program.
(Currently the CTEST_USE_LAUNCHERS option is ignored on non-Makefile
(Currently the ``CTEST_USE_LAUNCHERS`` option is ignored on non-Makefile
generators.) During a manual build each launcher transparently runs
the command it wraps. During a CTest-driven build for submission to
CDash each launcher reports detailed information when its command
fails or warns. (Setting CTEST_USE_LAUNCHERS in CTestConfig.cmake is
fails or warns. (Setting ``CTEST_USE_LAUNCHERS`` in ``CTestConfig.cmake`` is
convenient, but also adds the launcher overhead even for manual
builds. One may instead set it in a CTest dashboard script and add it
to the CMake cache for the build tree.)