Merge topic 'ctest-variable-docs'

4da5a227 Help: document CTEST_CUSTOM_* variables
70c0cc72 ctest_read_custom_files: mention that ctest does this automatically
71c67e83 CTEST_CUSTOM_*: treat variables as lists
936a95d4 CTestCoverageCollectGCOV: replace tabulators

24 files changed, 151 insertions, 21 deletions

diff --git a/CTestCustom.cmake.in b/CTestCustom.cmake.in
index d3cff51..2adf317 100644
--- a/CTestCustom.cmake.in
+++ b/CTestCustom.cmake.in
@@ -1,9 +1,7 @@
-set(CTEST_CUSTOM_ERROR_MATCH
-  ${CTEST_CUSTOM_ERROR_MATCH}
+list(APPEND CTEST_CUSTOM_ERROR_MATCH
   "ERROR:")
 
-set(CTEST_CUSTOM_WARNING_EXCEPTION
-  ${CTEST_CUSTOM_WARNING_EXCEPTION}
+list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "xtree.[0-9]+. : warning C4702: unreachable code"
   "warning LNK4221"
   "warning LNK4204" # Occurs by race condition with objects in small libs
@@ -84,22 +82,18 @@ set(CTEST_CUSTOM_WARNING_EXCEPTION
   )
 
 if(NOT "@CMAKE_GENERATOR@" MATCHES "Xcode")
-  set(CTEST_CUSTOM_COVERAGE_EXCLUDE
-    ${CTEST_CUSTOM_COVERAGE_EXCLUDE}
+  list(APPEND CTEST_CUSTOM_COVERAGE_EXCLUDE
     "XCode"
     )
 endif ()
 
 if(NOT "@CMAKE_GENERATOR@" MATCHES "KDevelop")
-  set(CTEST_CUSTOM_COVERAGE_EXCLUDE
-    ${CTEST_CUSTOM_COVERAGE_EXCLUDE}
+  list(APPEND CTEST_CUSTOM_COVERAGE_EXCLUDE
     "Kdevelop"
     )
 endif ()
 
-set(CTEST_CUSTOM_COVERAGE_EXCLUDE
-  ${CTEST_CUSTOM_COVERAGE_EXCLUDE}
-
+list(APPEND CTEST_CUSTOM_COVERAGE_EXCLUDE
   # Exclude kwsys files from coverage results. They are reported
   # (with better coverage results) on kwsys dashboards...
   "/Source/(cm|kw)sys/"
diff --git a/Help/command/ctest_read_custom_files.rst b/Help/command/ctest_read_custom_files.rst
index 0bc57cd..cf8e17a 100644
--- a/Help/command/ctest_read_custom_files.rst
+++ b/Help/command/ctest_read_custom_files.rst
@@ -9,3 +9,6 @@ read CTestCustom files.
 
 Read all the CTestCustom.ctest or CTestCustom.cmake files from the
 given directory.
+
+By default, invoking :manual:`ctest(1)` without a script will read custom
+files from the binary directory.
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index e679962..635db00 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -375,8 +375,23 @@ Variables for CTest
    /variable/CTEST_COVERAGE_COMMAND
    /variable/CTEST_COVERAGE_EXTRA_FLAGS
    /variable/CTEST_CURL_OPTIONS
+   /variable/CTEST_CUSTOM_COVERAGE_EXCLUDE
+   /variable/CTEST_CUSTOM_ERROR_EXCEPTION
+   /variable/CTEST_CUSTOM_ERROR_MATCH
+   /variable/CTEST_CUSTOM_ERROR_POST_CONTEXT
+   /variable/CTEST_CUSTOM_ERROR_PRE_CONTEXT
    /variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE
+   /variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS
+   /variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS
    /variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE
+   /variable/CTEST_CUSTOM_MEMCHECK_IGNORE
+   /variable/CTEST_CUSTOM_POST_MEMCHECK
+   /variable/CTEST_CUSTOM_POST_TEST
+   /variable/CTEST_CUSTOM_PRE_MEMCHECK
+   /variable/CTEST_CUSTOM_PRE_TEST
+   /variable/CTEST_CUSTOM_TEST_IGNORE
+   /variable/CTEST_CUSTOM_WARNING_EXCEPTION
+   /variable/CTEST_CUSTOM_WARNING_MATCH
    /variable/CTEST_CVS_CHECKOUT
    /variable/CTEST_CVS_COMMAND
    /variable/CTEST_CVS_UPDATE_OPTIONS
@@ -386,6 +401,7 @@ Variables for CTest
    /variable/CTEST_DROP_SITE_CDASH
    /variable/CTEST_DROP_SITE_PASSWORD
    /variable/CTEST_DROP_SITE_USER
+   /variable/CTEST_EXTRA_COVERAGE_GLOB
    /variable/CTEST_GIT_COMMAND
    /variable/CTEST_GIT_UPDATE_CUSTOM
    /variable/CTEST_GIT_UPDATE_OPTIONS
diff --git a/Help/variable/CTEST_CUSTOM_COVERAGE_EXCLUDE.rst b/Help/variable/CTEST_CUSTOM_COVERAGE_EXCLUDE.rst
new file mode 100644
index 0000000..d5893c9
--- /dev/null
+++ b/Help/variable/CTEST_CUSTOM_COVERAGE_EXCLUDE.rst
@@ -0,0 +1,7 @@
+CTEST_CUSTOM_COVERAGE_EXCLUDE
+-----------------------------
+
+A list of regular expressions which will be used to exclude files by their
+path from coverage output by the :command:`ctest_coverage` command.
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_ERROR_EXCEPTION.rst b/Help/variable/CTEST_CUSTOM_ERROR_EXCEPTION.rst
new file mode 100644
index 0000000..cd65ae3
--- /dev/null
+++ b/Help/variable/CTEST_CUSTOM_ERROR_EXCEPTION.rst
@@ -0,0 +1,7 @@
+CTEST_CUSTOM_ERROR_EXCEPTION
+----------------------------
+
+A list of regular expressions which will be used to exclude when detecting
+error messages in build outputs by the :command:`ctest_test` command.
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_ERROR_MATCH.rst b/Help/variable/CTEST_CUSTOM_ERROR_MATCH.rst
new file mode 100644
index 0000000..558f5e5
--- /dev/null
+++ b/Help/variable/CTEST_CUSTOM_ERROR_MATCH.rst
@@ -0,0 +1,7 @@
+CTEST_CUSTOM_ERROR_MATCH
+------------------------
+
+A list of regular expressions which will be used to detect error messages in
+build outputs by the :command:`ctest_test` command.
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_ERROR_POST_CONTEXT.rst b/Help/variable/CTEST_CUSTOM_ERROR_POST_CONTEXT.rst
new file mode 100644
index 0000000..614859b
--- /dev/null
+++ b/Help/variable/CTEST_CUSTOM_ERROR_POST_CONTEXT.rst
@@ -0,0 +1,7 @@
+CTEST_CUSTOM_ERROR_POST_CONTEXT
+-------------------------------
+
+The number of lines to include as context which follow an error message by the
+:command:`ctest_test` command. The default is 10.
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_ERROR_PRE_CONTEXT.rst b/Help/variable/CTEST_CUSTOM_ERROR_PRE_CONTEXT.rst
new file mode 100644
index 0000000..74dc47a
--- /dev/null
+++ b/Help/variable/CTEST_CUSTOM_ERROR_PRE_CONTEXT.rst
@@ -0,0 +1,7 @@
+CTEST_CUSTOM_ERROR_PRE_CONTEXT
+------------------------------
+
+The number of lines to include as context which precede an error message by
+the :command:`ctest_test` command. The default is 10.
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst
index 1b4bb01..5aeae88 100644
--- a/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst
+++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE.rst
@@ -1,6 +1,8 @@
 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE
 --------------------------------------------
 
-Specify the maximum amount of output from a failed test that will
-be collected by the :command:`ctest_test` command.  If not set,
-the default is 300 KiB.
+When saving a failing test's output, this is the maximum size, in bytes, that
+will be collected by the :command:`ctest_test` command. Defaults to 307200
+(300 KiB).
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS.rst
new file mode 100644
index 0000000..920cb04
--- /dev/null
+++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS.rst
@@ -0,0 +1,8 @@
+CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS
+-------------------------------------
+
+The maximum number of errors in a single build step which will be detected.
+After this, the :command:`ctest_test` command will truncate the output.
+Defaults to 50.
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS.rst
new file mode 100644
index 0000000..a1f1cc1
--- /dev/null
+++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS.rst
@@ -0,0 +1,8 @@
+CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS
+---------------------------------------
+
+The maximum number of warnings in a single build step which will be detected.
+After this, the :command:`ctest_test` command will truncate the output.
+Defaults to 50.
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst b/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst
index 168e84e..1fbb8c5 100644
--- a/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst
+++ b/Help/variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE.rst
@@ -1,6 +1,8 @@
 CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE
 --------------------------------------------
 
-Specify the maximum amount of output from a passed test that will
-be collected by the :command:`ctest_test` command.  If not set,
-the default is 1 KiB.
+When saving a passing test's output, this is the maximum size, in bytes, that
+will be collected by the :command:`ctest_test` command. Defaults to 1024
+(1 KiB).
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_MEMCHECK_IGNORE.rst b/Help/variable/CTEST_CUSTOM_MEMCHECK_IGNORE.rst
new file mode 100644
index 0000000..578576c
--- /dev/null
+++ b/Help/variable/CTEST_CUSTOM_MEMCHECK_IGNORE.rst
@@ -0,0 +1,7 @@
+CTEST_CUSTOM_MEMCHECK_IGNORE
+----------------------------
+
+A list of regular expressions to use to exclude tests during the
+:command:`ctest_memcheck` command.
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_POST_MEMCHECK.rst b/Help/variable/CTEST_CUSTOM_POST_MEMCHECK.rst
new file mode 100644
index 0000000..40291fe
--- /dev/null
+++ b/Help/variable/CTEST_CUSTOM_POST_MEMCHECK.rst
@@ -0,0 +1,6 @@
+CTEST_CUSTOM_POST_MEMCHECK
+--------------------------
+
+A list of commands to run at the end of the :command:`ctest_memcheck` command.
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_POST_TEST.rst b/Help/variable/CTEST_CUSTOM_POST_TEST.rst
new file mode 100644
index 0000000..791292c
--- /dev/null
+++ b/Help/variable/CTEST_CUSTOM_POST_TEST.rst
@@ -0,0 +1,6 @@
+CTEST_CUSTOM_POST_TEST
+----------------------
+
+A list of commands to run at the end of the :command:`ctest_test` command.
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_PRE_MEMCHECK.rst b/Help/variable/CTEST_CUSTOM_PRE_MEMCHECK.rst
new file mode 100644
index 0000000..00de8aa
--- /dev/null
+++ b/Help/variable/CTEST_CUSTOM_PRE_MEMCHECK.rst
@@ -0,0 +1,7 @@
+CTEST_CUSTOM_PRE_MEMCHECK
+-------------------------
+
+A list of commands to run at the start of the :command:`ctest_memcheck`
+command.
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_PRE_TEST.rst b/Help/variable/CTEST_CUSTOM_PRE_TEST.rst
new file mode 100644
index 0000000..6af7152
--- /dev/null
+++ b/Help/variable/CTEST_CUSTOM_PRE_TEST.rst
@@ -0,0 +1,6 @@
+CTEST_CUSTOM_PRE_TEST
+----------------------
+
+A list of commands to run at the start of the :command:`ctest_test` command.
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_TEST_IGNORE.rst b/Help/variable/CTEST_CUSTOM_TEST_IGNORE.rst
new file mode 100644
index 0000000..6114e60
--- /dev/null
+++ b/Help/variable/CTEST_CUSTOM_TEST_IGNORE.rst
@@ -0,0 +1,7 @@
+CTEST_CUSTOM_TEST_IGNORE
+------------------------
+
+A list of regular expressions to use to exclude tests during the
+:command:`ctest_test` command.
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst b/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst
new file mode 100644
index 0000000..36fa37d
--- /dev/null
+++ b/Help/variable/CTEST_CUSTOM_WARNING_EXCEPTION.rst
@@ -0,0 +1,7 @@
+CTEST_CUSTOM_WARNING_EXCEPTION
+------------------------------
+
+A list of regular expressions which will be used to exclude when detecting
+warning messages in build outputs by the :command:`ctest_test` command.
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_WARNING_MATCH.rst b/Help/variable/CTEST_CUSTOM_WARNING_MATCH.rst
new file mode 100644
index 0000000..a35be96
--- /dev/null
+++ b/Help/variable/CTEST_CUSTOM_WARNING_MATCH.rst
@@ -0,0 +1,7 @@
+CTEST_CUSTOM_WARNING_MATCH
+--------------------------
+
+A list of regular expressions which will be used to detect warning messages in
+build outputs by the :command:`ctest_test` command.
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Help/variable/CTEST_CUSTOM_XXX.txt b/Help/variable/CTEST_CUSTOM_XXX.txt
new file mode 100644
index 0000000..02d1547
--- /dev/null
+++ b/Help/variable/CTEST_CUSTOM_XXX.txt
@@ -0,0 +1,2 @@
+It is initialized by :manual:`ctest(1)`, but may be edited in a ``CTestCustom``
+file. See :command:`ctest_read_custom_files` documentation.
diff --git a/Help/variable/CTEST_EXTRA_COVERAGE_GLOB.rst b/Help/variable/CTEST_EXTRA_COVERAGE_GLOB.rst
new file mode 100644
index 0000000..286f7df
--- /dev/null
+++ b/Help/variable/CTEST_EXTRA_COVERAGE_GLOB.rst
@@ -0,0 +1,7 @@
+CTEST_EXTRA_COVERAGE_GLOB
+-------------------------
+
+A list of regular expressions which will be used to find files which should be
+covered by the :command:`ctest_coverage` command.
+
+.. include:: CTEST_CUSTOM_XXX.txt
diff --git a/Modules/CTestCoverageCollectGCOV.cmake b/Modules/CTestCoverageCollectGCOV.cmake
index 6c74cf3..ef3aa76 100644
--- a/Modules/CTestCoverageCollectGCOV.cmake
+++ b/Modules/CTestCoverageCollectGCOV.cmake
@@ -161,7 +161,7 @@ function(ctest_coverage_collect_gcov)
       message(STATUS "Could not determine source file corresponding to: ${gcov_file}")
     endif()
 
-    foreach(exclude_entry ${CTEST_CUSTOM_COVERAGE_EXCLUDE})
+    foreach(exclude_entry IN LISTS CTEST_CUSTOM_COVERAGE_EXCLUDE)
       if(source_file MATCHES "${exclude_entry}")
         set(is_excluded true)
 
diff --git a/Tests/CTestCoverageCollectGCOV/test.cmake.in b/Tests/CTestCoverageCollectGCOV/test.cmake.in
index 29f7e7f..b2e6d6d 100644
--- a/Tests/CTestCoverageCollectGCOV/test.cmake.in
+++ b/Tests/CTestCoverageCollectGCOV/test.cmake.in
@@ -12,9 +12,9 @@ ctest_build()
 ctest_test()
 
 list(APPEND CTEST_CUSTOM_COVERAGE_EXCLUDE
-	"/foo/something"
-	"/3rdparty/"
-	"/bar/somethingelse"
+  "/foo/something"
+  "/3rdparty/"
+  "/bar/somethingelse"
 )
 
 include(CTestCoverageCollectGCOV)