FPHSA: add capability to specify message explaining reason of failure

Fixes: #19660

Help/release/dev/FPHSA-reason-failure-message.rst

@@ -0,0 +1,5 @@
+FPHSA-reason-failure-message
+----------------------------
+
+* Modules :module:`FindPackageHandleStandardArgs` gains the capability to
+  specify a message giving the reason for the failure.

Modules/FindPackageHandleStandardArgs.cmake

@@ -27,6 +27,7 @@ valid filepaths.
       [VERSION_VAR <version-var>]
       [HANDLE_COMPONENTS]
       [CONFIG_MODE]
+      [REASON_FAILURE_MESSAGE <reason-failure-message>]
       [FAIL_MESSAGE <custom-failure-message>]
       )
 
@@ -81,6 +82,10 @@ valid filepaths.
     will automatically check whether the package configuration file
     was found.
 
+  ``REASON_FAILURE_MESSAGE <reason-failure-message>``
+    Specify a custom message of the reason for the failure which will be
+    appended to the default generated message.
+
   ``FAIL_MESSAGE <custom-failure-message>``
     Specify a custom failure message instead of using the default
     generated message.  Not recommended.
@@ -133,11 +138,15 @@ include(${CMAKE_CURRENT_LIST_DIR}/FindPackageMessage.cmake)
 
 # internal helper macro
 macro(_FPHSA_FAILURE_MESSAGE _msg)
+  set (__msg "${_msg}")
+  if (FPHSA_REASON_FAILURE_MESSAGE)
+    string(APPEND __msg "\n    Reason given by package: ${FPHSA_REASON_FAILURE_MESSAGE}\n")
+  endif()
   if (${_NAME}_FIND_REQUIRED)
-    message(FATAL_ERROR "${_msg}")
+    message(FATAL_ERROR "${__msg}")
   else ()
     if (NOT ${_NAME}_FIND_QUIETLY)
-      message(STATUS "${_msg}")
+      message(STATUS "${__msg}")
     endif ()
   endif ()
 endmacro()
@@ -158,12 +167,18 @@ macro(_FPHSA_HANDLE_FAILURE_CONFIG_MODE)
       foreach(currentConfigIndex RANGE ${configsCount})
         list(GET ${_NAME}_CONSIDERED_CONFIGS ${currentConfigIndex} filename)
         list(GET ${_NAME}_CONSIDERED_VERSIONS ${currentConfigIndex} version)
-        string(APPEND configsText "    ${filename} (version ${version})\n")
+        string(APPEND configsText "\n    ${filename} (version ${version})")
       endforeach()
       if (${_NAME}_NOT_FOUND_MESSAGE)
-        string(APPEND configsText "    Reason given by package: ${${_NAME}_NOT_FOUND_MESSAGE}\n")
+        if (FPHSA_REASON_FAILURE_MESSAGE)
+          string(PREPEND FPHSA_REASON_FAILURE_MESSAGE "${${_NAME}_NOT_FOUND_MESSAGE}\n    ")
+        else()
+          set(FPHSA_REASON_FAILURE_MESSAGE "${${_NAME}_NOT_FOUND_MESSAGE}")
+        endif()
+      else()
+        string(APPEND configsText "\n")
       endif()
-      _FPHSA_FAILURE_MESSAGE("${FPHSA_FAIL_MESSAGE} ${VERSION_MSG}, checked the following files:\n${configsText}")
+      _FPHSA_FAILURE_MESSAGE("${FPHSA_FAIL_MESSAGE} ${VERSION_MSG}, checked the following files:${configsText}")
 
     else()
       # Simple case: No Config-file was found at all:
@@ -177,7 +192,7 @@ function(FIND_PACKAGE_HANDLE_STANDARD_ARGS _NAME _FIRST_ARG)
 
 # Set up the arguments for `cmake_parse_arguments`.
   set(options  CONFIG_MODE  HANDLE_COMPONENTS)
-  set(oneValueArgs  FAIL_MESSAGE  VERSION_VAR  FOUND_VAR)
+  set(oneValueArgs  FAIL_MESSAGE  REASON_FAILURE_MESSAGE VERSION_VAR  FOUND_VAR)
   set(multiValueArgs REQUIRED_VARS)
 
 # Check whether we are in 'simple' or 'extended' mode:

Tests/RunCMake/FPHSA/CustomMessageConfig.cmake

@@ -0,0 +1 @@
+# pseudo config module

Tests/RunCMake/FPHSA/CustomMessageConfigVersion.cmake

@@ -0,0 +1,4 @@
+# pseudo find_module
+
+set (PACKAGE_VERSION 2)
+set (PACKAGE_VERSION_UNSUITABLE TRUE)

Tests/RunCMake/FPHSA/FindCustomMessage.cmake

@@ -0,0 +1,17 @@
+# pseudo find_module
+
+if (REASON_FAILURE_MESSAGE)
+  list (PREPEND REASON_FAILURE_MESSAGE "REASON_FAILURE_MESSAGE")
+endif()
+
+include(FindPackageHandleStandardArgs)
+
+if (CONFIG_MODE)
+  find_package (CustomMessage QUIET CONFIG HINTS "${CMAKE_MODULE_PATH}")
+  find_package_handle_standard_args(CustomMessage CONFIG_MODE
+                                                  ${REASON_FAILURE_MESSAGE})
+else()
+  find_package_handle_standard_args(CustomMessage REQUIRED_VARS FOOBAR
+                                                  VERSION_VAR CustomMessage_VERSION
+                                                  ${REASON_FAILURE_MESSAGE})
+endif()

Tests/RunCMake/FPHSA/RunCMakeTest.cmake

@@ -39,3 +39,10 @@ unset(RunCMake_DEFAULT_stderr)
 # check if searching for a version 0 works
 list(APPEND RunCMake_TEST_OPTIONS "-DCMAKE_MODULE_PATH=${CMAKE_CURRENT_LIST_DIR}" "-DPseudo_VERSION=0")
 run_cmake(exact_0_matching)
+
+# check custom error message
+set(RunCMake_TEST_OPTIONS "-DCMAKE_MODULE_PATH=${CMAKE_CURRENT_LIST_DIR}" "-DCustomMessage_VERSION=1.2.3.4")
+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)

Tests/RunCMake/FPHSA/custom_message_1-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/FPHSA/custom_message_1-stderr.txt

@@ -0,0 +1,7 @@
+^CMake Error at .+/Modules/FindPackageHandleStandardArgs.cmake:[0-9]+ \(message\):
+  Could NOT find CustomMessage \(missing: FOOBAR\) \(found suitable version
+  "1\.2\.3\.4", minimum required is "1\.2"\)
+
+      Reason given by package: Reason Failure
+
+Call Stack \(most recent call first\):

Tests/RunCMake/FPHSA/custom_message_1.cmake

@@ -0,0 +1,4 @@
+
+set (REASON_FAILURE_MESSAGE "Reason Failure")
+
+find_package(CustomMessage 1.2 REQUIRED)

Tests/RunCMake/FPHSA/custom_message_2-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/FPHSA/custom_message_2-stderr.txt

@@ -0,0 +1,8 @@
+^CMake Error at .+/Modules/FindPackageHandleStandardArgs.cmake:[0-9]+ \(message\):
+  Could NOT find CustomMessage \(Required is at least version "1\.2"\), checked
+  the following files:
+
+      .+/Tests/RunCMake/FPHSA/CustomMessageConfig.cmake \(version 2\)
+      Reason given by package: Not Found Message
+
+Call Stack \(most recent call first\):

Tests/RunCMake/FPHSA/custom_message_2.cmake

@@ -0,0 +1,5 @@
+
+unset (REASON_FAILURE_MESSAGE)
+set (CustomMessage_NOT_FOUND_MESSAGE "Not Found Message")
+
+find_package(CustomMessage 1.2 REQUIRED)

Tests/RunCMake/FPHSA/custom_message_3-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/FPHSA/custom_message_3-stderr.txt

@@ -0,0 +1,9 @@
+^CMake Error at .+/Modules/FindPackageHandleStandardArgs.cmake:[0-9]+ \(message\):
+  Could NOT find CustomMessage \(Required is at least version "1\.2"\), checked
+  the following files:
+
+      .+/Tests/RunCMake/FPHSA/CustomMessageConfig.cmake \(version 2\)
+      Reason given by package: Not Found Message
+      Reason Failure
+
+Call Stack \(most recent call first\):

Tests/RunCMake/FPHSA/custom_message_3.cmake

@@ -0,0 +1,5 @@
+
+set (REASON_FAILURE_MESSAGE "Reason Failure")
+set (CustomMessage_NOT_FOUND_MESSAGE "Not Found Message")
+
+find_package(CustomMessage 1.2 REQUIRED)