FPHSA: REQUIRED_VARS is optional if HANDLE_COMPONENTS is specified

Fixes: #20655

8 files changed, 85 insertions, 4 deletions

diff --git a/Help/release/dev/FPHSA-handle_components.rst b/Help/release/dev/FPHSA-handle_components.rst
new file mode 100644
index 0000000000..39907c4257
--- /dev/null
+++ b/Help/release/dev/FPHSA-handle_components.rst
@@ -0,0 +1,5 @@
+FPHSA-handle_components
+-----------------------
+
+* The :module:`FindPackageHandleStandardArgs` module option ``REQUIRED_VARS``
+  is now optional if ``HANDLE_COMPONENTS`` is specified.
diff --git a/Modules/FindPackageHandleStandardArgs.cmake b/Modules/FindPackageHandleStandardArgs.cmake
index a078049e2b..4fb08259a0 100644
--- a/Modules/FindPackageHandleStandardArgs.cmake
+++ b/Modules/FindPackageHandleStandardArgs.cmake
@@ -57,7 +57,8 @@ valid filepaths.
     These may be named in the generated failure message asking the
     user to set the missing variable values.  Therefore these should
     typically be cache entries such as ``FOO_LIBRARY`` and not output
-    variables like ``FOO_LIBRARIES``.
+    variables like ``FOO_LIBRARIES``. This option is mandatory if
+    ``HANDLE_COMPONENTS`` is not specified.
 
   ``VERSION_VAR <version-var>``
     Specify the name of a variable that holds the version of the package
@@ -257,7 +258,7 @@ function(FIND_PACKAGE_HANDLE_STANDARD_ARGS _NAME _FIRST_ARG)
       set(FPHSA_VERSION_VAR ${_NAME}_VERSION)
     endif()
 
-    if(NOT FPHSA_REQUIRED_VARS)
+    if(NOT FPHSA_REQUIRED_VARS AND NOT FPHSA_HANDLE_COMPONENTS)
       message(FATAL_ERROR "No REQUIRED_VARS specified for FIND_PACKAGE_HANDLE_STANDARD_ARGS()")
     endif()
   endif()
@@ -283,7 +284,9 @@ function(FIND_PACKAGE_HANDLE_STANDARD_ARGS _NAME _FIRST_ARG)
     set(FPHSA_FAIL_MESSAGE "Could NOT find ${_NAME}")
   endif()
 
-  list(GET FPHSA_REQUIRED_VARS 0 _FIRST_REQUIRED_VAR)
+  if (FPHSA_REQUIRED_VARS)
+    list(GET FPHSA_REQUIRED_VARS 0 _FIRST_REQUIRED_VAR)
+  endif()
 
   string(TOUPPER ${_NAME} _NAME_UPPER)
   string(TOLOWER ${_NAME} _NAME_LOWER)
@@ -440,7 +443,17 @@ function(FIND_PACKAGE_HANDLE_STANDARD_ARGS _NAME _FIRST_ARG)
       _FPHSA_HANDLE_FAILURE_CONFIG_MODE()
     else()
       if(NOT VERSION_OK)
-        _FPHSA_FAILURE_MESSAGE("${FPHSA_FAIL_MESSAGE}: ${VERSION_MSG} (found ${${_FIRST_REQUIRED_VAR}})")
+        set(RESULT_MSG)
+        if (_FIRST_REQUIRED_VAR)
+          string (APPEND RESULT_MSG "found ${${_FIRST_REQUIRED_VAR}}")
+        endif()
+        if (COMPONENT_MSG)
+          if (RESULT_MSG)
+            string (APPEND RESULT_MSG ", ")
+          endif()
+          string (APPEND RESULT_MSG "${FOUND_COMPONENTS_MSG}")
+        endif()
+        _FPHSA_FAILURE_MESSAGE("${FPHSA_FAIL_MESSAGE}: ${VERSION_MSG} (${RESULT_MSG})")
       else()
         _FPHSA_FAILURE_MESSAGE("${FPHSA_FAIL_MESSAGE} (missing:${MISSING_VARS}) ${VERSION_MSG}")
       endif()
diff --git a/Tests/RunCMake/FPHSA/FindUseComponents.cmake b/Tests/RunCMake/FPHSA/FindUseComponents.cmake
new file mode 100644
index 0000000000..4168f1d480
--- /dev/null
+++ b/Tests/RunCMake/FPHSA/FindUseComponents.cmake
@@ -0,0 +1,15 @@
+# pseudo find_module
+
+if (UseComponents_REQUIRE_VARS)
+  set(FOOBAR TRUE)
+  set(REQUIRED_VARS REQUIRED_VARS  FOOBAR)
+endif()
+
+set (UseComponents_Comp1_FOUND TRUE)
+set (UseComponents_Comp2_FOUND TRUE)
+set (UseComponents_Comp3_FOUND FALSE)
+
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(UseComponents ${REQUIRED_VARS}
+                                                VERSION_VAR Pseudo_VERSION
+                                                HANDLE_COMPONENTS)
diff --git a/Tests/RunCMake/FPHSA/RunCMakeTest.cmake b/Tests/RunCMake/FPHSA/RunCMakeTest.cmake
index 286915db01..8e390908a0 100644
--- a/Tests/RunCMake/FPHSA/RunCMakeTest.cmake
+++ b/Tests/RunCMake/FPHSA/RunCMakeTest.cmake
@@ -47,3 +47,11 @@ run_cmake(custom_message_1)
 set(RunCMake_TEST_OPTIONS "-DCMAKE_MODULE_PATH=${CMAKE_CURRENT_LIST_DIR}" "-DCONFIG_MODE=TRUE")
 run_cmake(custom_message_2)
 run_cmake(custom_message_3)
+
+# check handling of components
+set(RunCMake_TEST_OPTIONS "-DCMAKE_MODULE_PATH=${CMAKE_CURRENT_LIST_DIR}" "-DUseComponents_VERSION=1.2.3.4")
+run_cmake(required_components)
+run_cmake(required_and_optional_components)
+run_cmake(all_optional_components)
+list(APPEND RunCMake_TEST_OPTIONS "-DUseComponents_REQUIRE_VARS=TRUE")
+run_cmake(required_components_with_vars)
diff --git a/Tests/RunCMake/FPHSA/all_optional_components.cmake b/Tests/RunCMake/FPHSA/all_optional_components.cmake
new file mode 100644
index 0000000000..f4d8b5ee64
--- /dev/null
+++ b/Tests/RunCMake/FPHSA/all_optional_components.cmake
@@ -0,0 +1,14 @@
+find_package(UseComponents OPTIONAL_COMPONENTS Comp1 Comp2 Comp3)
+
+if (NOT UseComponents_FOUND)
+  message (FATAL_ERROR "package UseComponents Not Found.")
+endif()
+if (NOT UseComponents_Comp1_FOUND)
+  message (FATAL_ERROR "package UseComponents, component Comp1 not found.")
+endif()
+if (NOT UseComponents_Comp2_FOUND)
+  message (FATAL_ERROR "package UseComponents, component Comp2 not found.")
+endif()
+if (UseComponents_Comp3_FOUND)
+  message (FATAL_ERROR "package UseComponents, component Comp2 unexpectedly found.")
+endif()
diff --git a/Tests/RunCMake/FPHSA/required_and_optional_components.cmake b/Tests/RunCMake/FPHSA/required_and_optional_components.cmake
new file mode 100644
index 0000000000..836dcac9dc
--- /dev/null
+++ b/Tests/RunCMake/FPHSA/required_and_optional_components.cmake
@@ -0,0 +1,14 @@
+find_package(UseComponents COMPONENTS Comp1 Comp2 OPTIONAL_COMPONENTS Comp3)
+
+if (NOT UseComponents_FOUND)
+  message (FATAL_ERROR "package UseComponents Not Found.")
+endif()
+if (NOT UseComponents_Comp1_FOUND)
+  message (FATAL_ERROR "package UseComponents, component Comp1 not found.")
+endif()
+if (NOT UseComponents_Comp2_FOUND)
+  message (FATAL_ERROR "package UseComponents, component Comp2 not found.")
+endif()
+if (UseComponents_Comp3_FOUND)
+  message (FATAL_ERROR "package UseComponents, component Comp2 unexpectedly found.")
+endif()
diff --git a/Tests/RunCMake/FPHSA/required_components.cmake b/Tests/RunCMake/FPHSA/required_components.cmake
new file mode 100644
index 0000000000..0dd8e9c49c
--- /dev/null
+++ b/Tests/RunCMake/FPHSA/required_components.cmake
@@ -0,0 +1,11 @@
+find_package(UseComponents COMPONENTS Comp1 Comp2)
+
+if (NOT UseComponents_FOUND)
+  message (FATAL_ERROR "package UseComponents Not Found.")
+endif()
+if (NOT UseComponents_Comp1_FOUND)
+  message (FATAL_ERROR "package UseComponents, component Comp1 Not Found.")
+endif()
+if (NOT UseComponents_Comp2_FOUND)
+  message (FATAL_ERROR "package UseComponents, component Comp2 Not Found.")
+endif()
diff --git a/Tests/RunCMake/FPHSA/required_components_with_vars.cmake b/Tests/RunCMake/FPHSA/required_components_with_vars.cmake
new file mode 100644
index 0000000000..842ef1557d
--- /dev/null
+++ b/Tests/RunCMake/FPHSA/required_components_with_vars.cmake
@@ -0,0 +1 @@
+include ("required_components.cmake")