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

CTestCustom.cmake.in

@@ -1,9 +1,7 @@
-set(CTEST_CUSTOM_ERROR_MATCH
+list(APPEND CTEST_CUSTOM_ERROR_MATCH
-  ${CTEST_CUSTOM_ERROR_MATCH}
   "ERROR:")
 
-set(CTEST_CUSTOM_WARNING_EXCEPTION
+list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
-  ${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
+  list(APPEND CTEST_CUSTOM_COVERAGE_EXCLUDE
-    ${CTEST_CUSTOM_COVERAGE_EXCLUDE}
     "XCode"
     )
 endif ()
 
 if(NOT "@CMAKE_GENERATOR@" MATCHES "KDevelop")
-  set(CTEST_CUSTOM_COVERAGE_EXCLUDE
+  list(APPEND CTEST_CUSTOM_COVERAGE_EXCLUDE
-    ${CTEST_CUSTOM_COVERAGE_EXCLUDE}
     "Kdevelop"
     )
 endif ()
 
-set(CTEST_CUSTOM_COVERAGE_EXCLUDE
+list(APPEND CTEST_CUSTOM_COVERAGE_EXCLUDE
-  ${CTEST_CUSTOM_COVERAGE_EXCLUDE}
-
   # Exclude kwsys files from coverage results. They are reported
   # (with better coverage results) on kwsys dashboards...
   "/Source/(cm|kw)sys/"

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.

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

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

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

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

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

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

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
+When saving a failing test's output, this is the maximum size, in bytes, that
-be collected by the :command:`ctest_test` command.  If not set,
+will be collected by the :command:`ctest_test` command. Defaults to 307200
-the default is 300 KiB.
+(300 KiB).
+
+.. include:: CTEST_CUSTOM_XXX.txt

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

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

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
+When saving a passing test's output, this is the maximum size, in bytes, that
-be collected by the :command:`ctest_test` command.  If not set,
+will be collected by the :command:`ctest_test` command. Defaults to 1024
-the default is 1 KiB.
+(1 KiB).
+
+.. include:: CTEST_CUSTOM_XXX.txt

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

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

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

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

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

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

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

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

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.

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

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)