From 5cbedd6b8527dc265d50c877c1e4b3977a6dd23f Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 27 Apr 2015 10:21:52 -0400 Subject: Modules/CTest: Use bracket comment for documentation block --- Modules/CTest.cmake | 131 ++++++++++++++++++++++++++-------------------------- 1 file changed, 66 insertions(+), 65 deletions(-) diff --git a/Modules/CTest.cmake b/Modules/CTest.cmake index 7759ead..0015d4b 100644 --- a/Modules/CTest.cmake +++ b/Modules/CTest.cmake @@ -1,68 +1,69 @@ -#.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 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.) +#]=======================================================================] #============================================================================= # Copyright 2005-2009 Kitware, Inc. -- cgit v0.12 From f693c136f94c8a21857b8bf4eff944ab57f73765 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 27 Apr 2015 10:32:53 -0400 Subject: Modules/CTest: Improve documentation formatting Use inline reStructuredText markup and add cross-references. --- Modules/CTest.cmake | 60 +++++++++++++++++++++++------------------------------ 1 file changed, 26 insertions(+), 34 deletions(-) diff --git a/Modules/CTest.cmake b/Modules/CTest.cmake index 0015d4b..fccef4f 100644 --- a/Modules/CTest.cmake +++ b/Modules/CTest.cmake @@ -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.) -- cgit v0.12 From 7244e8452fc9e99c613d8fb098903608d96cf73a Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 27 Apr 2015 10:34:24 -0400 Subject: ctest: Consolidate documentation of CTEST_USE_LAUNCHERS (#15533) The documentation of this variable in the CTest module is outdated and has been superseded by the ctest(1) manual. In particular, the latter mentions that it works with the Ninja generator as well as makefile generators. Remove the documentation from the CTest module and replace it with a link to the main variable documentation (which already references the ctest(1) manual). --- Help/manual/ctest.1.rst | 7 +++++-- Modules/CTest.cmake | 15 +++------------ 2 files changed, 8 insertions(+), 14 deletions(-) diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index d0ac28d..c91321b 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 fccef4f..8278c5c 100644 --- a/Modules/CTest.cmake +++ b/Modules/CTest.cmake @@ -40,21 +40,12 @@ 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 setting +the :variable:`CTEST_USE_LAUNCHERS` variable:: 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.) +in the ``CTestConfig.cmake`` file. #]=======================================================================] #============================================================================= -- cgit v0.12