FindGTest: Add imported targets and update documentation

Modules/FindGTest.cmake

@@ -4,88 +4,89 @@
 #
 # Locate the Google C++ Testing Framework.
 #
-# Defines the following variables:
+# Imported targets
+# ^^^^^^^^^^^^^^^^
 #
-# ::
-#
-#    GTEST_FOUND - Found the Google Testing framework
-#    GTEST_INCLUDE_DIRS - Include directories
+# This module defines the following :prop_tgt:`IMPORTED` targets:
 #
+# ``GTest::GTest``
+#   The Google Test ``gtest`` library, if found; adds Thread::Thread
+#   automatically
+# ``GTest::Main``
+#   The Google Test ``gtest_main`` library, if found
 #
 #
-# Also defines the library variables below as normal variables.  These
-# contain debug/optimized keywords when a debugging library is found.
-#
-# ::
+# Result variables
+# ^^^^^^^^^^^^^^^^
 #
-#    GTEST_BOTH_LIBRARIES - Both libgtest & libgtest-main
-#    GTEST_LIBRARIES - libgtest
-#    GTEST_MAIN_LIBRARIES - libgtest-main
+# This module will set the following variables in your project:
 #
+# ``GTEST_FOUND``
+#   Found the Google Testing framework
+# ``GTEST_INCLUDE_DIRS``
+#   the directory containing the Google Test headers
 #
+# The library variables below are set as normal variables.  These
+# contain debug/optimized keywords when a debugging library is found.
 #
-# Accepts the following variables as input:
-#
-# ::
-#
-#    GTEST_ROOT - (as a CMake or environment variable)
-#                 The root directory of the gtest install prefix
-#
-#
+# ``GTEST_LIBRARIES``
+#   The Google Test ``gtest`` library; note it also requires linking
+#   with an appropriate thread library
+# ``GTEST_MAIN_LIBRARIES``
+#   The Google Test ``gtest_main`` library
+# ``GTEST_BOTH_LIBRARIES``
+#   Both ``gtest`` and ``gtest_main``
 #
-# ::
+# Cache variables
+# ^^^^^^^^^^^^^^^
 #
-#    GTEST_MSVC_SEARCH - If compiling with MSVC, this variable can be set to
-#                        "MD" or "MT" to enable searching a GTest build tree
-#                        (defaults: "MD")
+# The following cache variables may also be set:
 #
+# ``GTEST_ROOT``
+#   The root directory of the Google Test installation (may also be
+#   set as an environment variable)
+# ``GTEST_MSVC_SEARCH``
+#   If compiling with MSVC, this variable can be set to ``MD`` or
+#   ``MT`` (the default) to enable searching a GTest build tree
 #
 #
-# Example Usage:
+# Example usage
+# ^^^^^^^^^^^^^
 #
 # ::
 #
 #     enable_testing()
 #     find_package(GTest REQUIRED)
-#     include_directories(${GTEST_INCLUDE_DIRS})
-#
-#
-#
-# ::
 #
 #     add_executable(foo foo.cc)
-#     target_link_libraries(foo ${GTEST_BOTH_LIBRARIES})
-#
-#
-#
-# ::
+#     target_link_libraries(foo GTest::GTest GTest::Main)
 #
 #     add_test(AllTestsInFoo foo)
 #
 #
-#
-#
+# 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.  NOTE: It will slow down your tests by
-# running an executable for each test and test fixture.  You will also
-# have to rerun CMake after adding or removing tests or test fixtures.
-#
-# GTEST_ADD_TESTS(executable extra_args ARGN)
-#
-# ::
+# may use the following macro::
 #
-#     executable = The path to the test executable
-#     extra_args = Pass a list of extra arguments to be passed to
-#                  executable enclosed in quotes (or "" for none)
-#     ARGN =       A list of source files to search for tests & test
-#                  fixtures. Or AUTO to find them from executable target.
+#     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.  You will also have to
+# re-run CMake after adding or removing tests or test fixtures.
 #
-# ::
+# Example usage::
 #
-#   Example:
 #      set(FooTestArgs --foo 1 --bar 2)
 #      add_executable(FooTest FooUnitTest.cc)
 #      GTEST_ADD_TESTS(FooTest "${FooTestArgs}" AUTO)
@@ -208,5 +209,60 @@ if(GTEST_FOUND)
     _gtest_append_debugs(GTEST_LIBRARIES      GTEST_LIBRARY)
     _gtest_append_debugs(GTEST_MAIN_LIBRARIES GTEST_MAIN_LIBRARY)
     set(GTEST_BOTH_LIBRARIES ${GTEST_LIBRARIES} ${GTEST_MAIN_LIBRARIES})
-endif()
 
+    include(CMakeFindDependencyMacro)
+    find_dependency(Threads)
+
+    if(NOT TARGET GTest::GTest)
+        add_library(GTest::GTest UNKNOWN IMPORTED)
+        set_target_properties(GTest::GTest PROPERTIES
+            INTERFACE_LINK_LIBRARIES "Threads::Threads")
+        if(GTEST_INCLUDE_DIRS)
+            set_target_properties(GTest::GTest PROPERTIES
+                INTERFACE_INCLUDE_DIRECTORIES "${GTEST_INCLUDE_DIRS}")
+        endif()
+        if(EXISTS "${GTEST_LIBRARY}")
+            set_target_properties(GTest::GTest PROPERTIES
+                IMPORTED_LINK_INTERFACE_LANGUAGES "CXX"
+                IMPORTED_LOCATION "${GTEST_LIBRARY}")
+        endif()
+        if(EXISTS "${GTEST_LIBRARY_DEBUG}")
+            set_property(TARGET GTest::GTest APPEND PROPERTY
+                IMPORTED_CONFIGURATIONS DEBUG)
+            set_target_properties(GTest::GTest PROPERTIES
+                IMPORTED_LINK_INTERFACE_LANGUAGES_DEBUG "CXX"
+                IMPORTED_LOCATION_DEBUG "${GTEST_LIBRARY_DEBUG}")
+        endif()
+        if(EXISTS "${GTEST_LIBRARY_RELEASE}")
+            set_property(TARGET GTest::GTest APPEND PROPERTY
+                IMPORTED_CONFIGURATIONS RELEASE)
+            set_target_properties(GTest::GTest PROPERTIES
+                IMPORTED_LINK_INTERFACE_LANGUAGES_RELEASE "CXX"
+                IMPORTED_LOCATION_RELEASE "${GTEST_LIBRARY_RELEASE}")
+        endif()
+      endif()
+      if(NOT TARGET GTest::Main)
+          add_library(GTest::Main UNKNOWN IMPORTED)
+          set_target_properties(GTest::Main PROPERTIES
+              INTERFACE_LINK_LIBRARIES "GTest::GTest")
+          if(EXISTS "${GTEST_MAIN_LIBRARY}")
+              set_target_properties(GTest::Main PROPERTIES
+                  IMPORTED_LINK_INTERFACE_LANGUAGES "CXX"
+                  IMPORTED_LOCATION "${GTEST_MAIN_LIBRARY}")
+          endif()
+          if(EXISTS "${GTEST_MAIN_LIBRARY_DEBUG}")
+            set_property(TARGET GTest::Main APPEND PROPERTY
+                IMPORTED_CONFIGURATIONS DEBUG)
+            set_target_properties(GTest::Main PROPERTIES
+                IMPORTED_LINK_INTERFACE_LANGUAGES_DEBUG "CXX"
+                IMPORTED_LOCATION_DEBUG "${GTEST_MAIN_LIBRARY_DEBUG}")
+          endif()
+          if(EXISTS "${GTEST_MAIN_LIBRARY_RELEASE}")
+            set_property(TARGET GTest::Main APPEND PROPERTY
+                IMPORTED_CONFIGURATIONS RELEASE)
+            set_target_properties(GTest::Main PROPERTIES
+                IMPORTED_LINK_INTERFACE_LANGUAGES_RELEASE "CXX"
+                IMPORTED_LOCATION_RELEASE "${GTEST_MAIN_LIBRARY_RELEASE}")
+          endif()
+    endif()
+endif()