From 700da5f2660ce4b85aa0ee89cbc01d1d2b6a5f3e Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 4 Dec 2009 13:44:19 -0500 Subject: Document usage of the include(CTest) module Previously this module gave only very brief documentation. We extend the module's documentation to describe CTestConfig.cmake, interaction with dashboard scripts, and the CTEST_USE_LAUNCHERS option. --- Modules/CTest.cmake | 54 ++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 45 insertions(+), 9 deletions(-) diff --git a/Modules/CTest.cmake b/Modules/CTest.cmake index fb430a7..28835ce 100644 --- a/Modules/CTest.cmake +++ b/Modules/CTest.cmake @@ -1,13 +1,49 @@ # - Configure a project for testing with CTest/CDash -# This file configures a project to use the CTest/CDash/Dart -# testing/dashboard process. This module should be included -# in the CMakeLists.txt file at the top of a project. Typical usage: -# INCLUDE(CTest) -# IF(BUILD_TESTING) -# # ... testing related CMake code ... -# ENDIF(BUILD_TESTING) -# The BUILD_TESTING option is created by the CTest module to determine -# whether testing support should be enabled. The default is ON. +# 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