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.

1 files 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.