GoogleTest: Add module to contain gtest_add_tests independently

Extract the `gtest_add_tests` macro from `FindGTest` into a separate
module. GTest or GoogleTest can be used by a project in a several
different ways, including installed libraries in the system, from an
ExternalProject, or adding the GTest source directory as a sub directory
of the project. As not all of these uses are supported by the FindGTest
module the useful `gtest_add_tests` macro is separated to easily enable
reuse.

Issue: #14151

5 files changed, 83 insertions, 57 deletions

diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst
index d4712baa01..2dd56c7391 100644
--- a/Help/manual/cmake-modules.7.rst
+++ b/Help/manual/cmake-modules.7.rst
@@ -228,6 +228,7 @@ All Modules
    /module/GenerateExportHeader
    /module/GetPrerequisites
    /module/GNUInstallDirs
+   /module/GoogleTest
    /module/InstallRequiredSystemLibraries
    /module/MacroAddFileDependencies
    /module/ProcessorCount
diff --git a/Help/module/GoogleTest.rst b/Help/module/GoogleTest.rst
new file mode 100644
index 0000000000..3d4cc975df
--- /dev/null
+++ b/Help/module/GoogleTest.rst
@@ -0,0 +1 @@
+.. cmake-module:: ../../Modules/GoogleTest.cmake
diff --git a/Help/release/dev/ExtractGTestMacro.rst b/Help/release/dev/ExtractGTestMacro.rst
new file mode 100644
index 0000000000..574982cf3f
--- /dev/null
+++ b/Help/release/dev/ExtractGTestMacro.rst
@@ -0,0 +1,5 @@
+ExtractGTestMacro
+-----------------
+
+* A new :module:`GoogleTest` module was added to provide the
+  ``gtest_add_tests`` macro independently of the :module:`FindGTest` module.
diff --git a/Modules/FindGTest.cmake b/Modules/FindGTest.cmake
index 65401710d7..c4b4535ff8 100644
--- a/Modules/FindGTest.cmake
+++ b/Modules/FindGTest.cmake
@@ -70,64 +70,10 @@
 # Deeper integration with CTest
 # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 #
-# If you would like each Google test to show up in CTest as a test you
-# may use the following macro::
-#
-#     GTEST_ADD_TESTS(executable extra_args files...)
-#
-# ``executable``
-#   the path to the test executable
-# ``extra_args``
-#   a list of extra arguments to be passed to executable enclosed in
-#   quotes (or ``""`` for none)
-# ``files...``
-#   a list of source files to search for tests and test fixtures.  Or
-#   ``AUTO`` to find them from executable target
-#
-# However, note that this macro will slow down your tests by running
-# an executable for each test and test fixture.
-#
-# Example usage::
-#
-#      set(FooTestArgs --foo 1 --bar 2)
-#      add_executable(FooTest FooUnitTest.cc)
-#      GTEST_ADD_TESTS(FooTest "${FooTestArgs}" AUTO)
-
-#
-# Thanks to Daniel Blezek <blezek@gmail.com> for the GTEST_ADD_TESTS code
-
-function(GTEST_ADD_TESTS executable extra_args)
-    if(NOT ARGN)
-        message(FATAL_ERROR "Missing ARGN: Read the documentation for GTEST_ADD_TESTS")
-    endif()
-    if(ARGN STREQUAL "AUTO")
-        # obtain sources used for building that executable
-        get_property(ARGN TARGET ${executable} PROPERTY SOURCES)
-    endif()
-    set(gtest_case_name_regex ".*\\( *([A-Za-z_0-9]+) *, *([A-Za-z_0-9]+) *\\).*")
-    set(gtest_test_type_regex "(TYPED_TEST|TEST_?[FP]?)")
-    foreach(source ${ARGN})
-        set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${source})
-        file(READ "${source}" contents)
-        string(REGEX MATCHALL "${gtest_test_type_regex} *\\(([A-Za-z_0-9 ,]+)\\)" found_tests ${contents})
-        foreach(hit ${found_tests})
-          string(REGEX MATCH "${gtest_test_type_regex}" test_type ${hit})
+# See :module:`GoogleTest` for information on the :command:`gtest_add_tests`
+# command.
 
-          # Parameterized tests have a different signature for the filter
-          if("x${test_type}" STREQUAL "xTEST_P")
-            string(REGEX REPLACE ${gtest_case_name_regex}  "*/\\1.\\2/*" test_name ${hit})
-          elseif("x${test_type}" STREQUAL "xTEST_F" OR "x${test_type}" STREQUAL "xTEST")
-            string(REGEX REPLACE ${gtest_case_name_regex} "\\1.\\2" test_name ${hit})
-          elseif("x${test_type}" STREQUAL "xTYPED_TEST")
-            string(REGEX REPLACE ${gtest_case_name_regex} "\\1/*.\\2" test_name ${hit})
-          else()
-            message(WARNING "Could not parse GTest ${hit} for adding to CTest.")
-            continue()
-          endif()
-          add_test(NAME ${test_name} COMMAND ${executable} --gtest_filter=${test_name} ${extra_args})
-        endforeach()
-    endforeach()
-endfunction()
+include(${CMAKE_CURRENT_LIST_DIR}/GoogleTest.cmake)
 
 function(_gtest_append_debugs _endvar _library)
     if(${_library} AND ${_library}_DEBUG)
diff --git a/Modules/GoogleTest.cmake b/Modules/GoogleTest.cmake
new file mode 100644
index 0000000000..91a3a25485
--- /dev/null
+++ b/Modules/GoogleTest.cmake
@@ -0,0 +1,73 @@
+# Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
+# file Copyright.txt or https://cmake.org/licensing for details.
+
+#[=======================================================================[.rst:
+GoogleTest
+----------
+
+This module defines functions to help use the Google Test infrastructure.
+
+.. command:: gtest_add_tests
+
+  Automatically add tests with CTest by scanning source code for Google test
+  macros.
+
+  ::
+
+    gtest_add_tests(<exe> <args> <files>...)
+
+  ``<exe>``
+    The path to the test executable.
+  ``<args>``
+    A ;-list of extra arguments to be passed to executable.  The entire
+    list must be passed as a single argument.  Enclose it in quotes,
+    or pass ``""`` for no arguments.
+  ``<files>...``
+    A list of source files to search for tests and test fixtures.
+    Alternatively, use ``AUTO`` to specify that ``<exe>`` is the name
+    of a CMake executable target whose sources should be scanned.
+
+Example
+^^^^^^^
+
+.. code-block:: cmake
+
+  include(GoogleTest)
+  set(FooTestArgs --foo 1 --bar 2)
+  add_executable(FooTest FooUnitTest.cc)
+  gtest_add_tests(FooTest "${FooTestArgs}" AUTO)
+
+#]=======================================================================]
+
+function(gtest_add_tests executable extra_args)
+  if(NOT ARGN)
+    message(FATAL_ERROR "Missing ARGN: Read the documentation for GTEST_ADD_TESTS")
+  endif()
+  if(ARGN STREQUAL "AUTO")
+    # obtain sources used for building that executable
+    get_property(ARGN TARGET ${executable} PROPERTY SOURCES)
+  endif()
+  set(gtest_case_name_regex ".*\\( *([A-Za-z_0-9]+) *, *([A-Za-z_0-9]+) *\\).*")
+  set(gtest_test_type_regex "(TYPED_TEST|TEST_?[FP]?)")
+  foreach(source ${ARGN})
+    set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${source})
+    file(READ "${source}" contents)
+    string(REGEX MATCHALL "${gtest_test_type_regex} *\\(([A-Za-z_0-9 ,]+)\\)" found_tests ${contents})
+    foreach(hit ${found_tests})
+      string(REGEX MATCH "${gtest_test_type_regex}" test_type ${hit})
+
+      # Parameterized tests have a different signature for the filter
+      if("x${test_type}" STREQUAL "xTEST_P")
+        string(REGEX REPLACE ${gtest_case_name_regex}  "*/\\1.\\2/*" test_name ${hit})
+      elseif("x${test_type}" STREQUAL "xTEST_F" OR "x${test_type}" STREQUAL "xTEST")
+        string(REGEX REPLACE ${gtest_case_name_regex} "\\1.\\2" test_name ${hit})
+      elseif("x${test_type}" STREQUAL "xTYPED_TEST")
+        string(REGEX REPLACE ${gtest_case_name_regex} "\\1/*.\\2" test_name ${hit})
+      else()
+        message(WARNING "Could not parse GTest ${hit} for adding to CTest.")
+        continue()
+      endif()
+      add_test(NAME ${test_name} COMMAND ${executable} --gtest_filter=${test_name} ${extra_args})
+    endforeach()
+  endforeach()
+endfunction()