diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index d0ac28d32..c91321b10 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -372,6 +372,8 @@ Options .. include:: OPTIONS_HELP.txt +.. _`Dashboard Client`: + Dashboard Client ================ @@ -749,8 +751,9 @@ Configuration settings include: initialized by the :command:`build_command` command ``UseLaunchers`` - For build trees generated by CMake using a Makefile generator - or the :generator:`Ninja` generator, specify whether the + For build trees generated by CMake using one of the + :ref:`Makefile Generators` or the :generator:`Ninja` + generator, specify whether the ``CTEST_USE_LAUNCHERS`` feature is enabled by the :module:`CTestUseLaunchers` module (also included by the :module:`CTest` module). When enabled, the generated build diff --git a/Modules/CTest.cmake b/Modules/CTest.cmake index 7759ead6d..8278c5c4b 100644 --- a/Modules/CTest.cmake +++ b/Modules/CTest.cmake @@ -1,68 +1,52 @@ -#.rst: -# 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: -# -# :: -# -# 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 -# -# :: -# -# 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 -# -# :: -# -# 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). -# -# 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 -# -# :: -# -# set(CTEST_USE_LAUNCHERS 1) -# -# 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 -# 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 -# 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.) +#[=======================================================================[.rst: +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:: + + 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:: + + 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:: + + 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 :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 setting +the :variable:`CTEST_USE_LAUNCHERS` variable:: + + set(CTEST_USE_LAUNCHERS 1) + +in the ``CTestConfig.cmake`` file. +#]=======================================================================] #============================================================================= # Copyright 2005-2009 Kitware, Inc.