FPHSA: Add hint for failure when called before project()

Help project authors recognize an ordering mistake.

Inspired-by: Jeremy Rifkin @jeremy-rifkin
Closes: #25941

Modules/FindPackageHandleStandardArgs.cmake

@@ -225,6 +225,9 @@ 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")
+  elseif(NOT DEFINED PROJECT_NAME)
+    string(APPEND __msg "\n"
+      "Hint: The project() command has not yet been called.  It sets up system-specific search paths.")
   endif()
   if (${_NAME}_FIND_REQUIRED)
     message(FATAL_ERROR "${__msg}")

Tests/RunCMake/FPHSA/BadFoundVar-stderr.txt

@@ -2,6 +2,6 @@ CMake Error at .*/Modules/FindPackageHandleStandardArgs.cmake:[0-9]+ \(message\)
   The argument for FOUND_VAR is "badfoundvar_FOUND", but only
   "BadFoundVar_FOUND" and "BADFOUNDVAR_FOUND" are valid names.
 Call Stack \(most recent call first\):
-  FindBadFoundVar.cmake:5 \(find_package_handle_standard_args\)
-  BadFoundVar.cmake:3 \(find_package\)
-  CMakeLists.txt:3 \(include\)
+  FindBadFoundVar.cmake:[0-9]+ \(find_package_handle_standard_args\)
+  BadFoundVar.cmake:[0-9]+ \(find_package\)
+  CMakeLists.txt:[0-9]+ \(include\)

Tests/RunCMake/FPHSA/BeforeProject-Error-result.txt

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

Tests/RunCMake/FPHSA/BeforeProject-Error-stderr.txt

@@ -0,0 +1,12 @@
+^CMake Error at [^
+]*/Modules/FindPackageHandleStandardArgs\.cmake:[0-9]+ \(message\):
+  Could NOT find BeforeProject \(missing: SOME_VAR\)
+
+  Hint: The project\(\) command has not yet been called\.  It sets up
+  system-specific search paths\.
+Call Stack \(most recent call first\):
+  [^
+]*/Modules/FindPackageHandleStandardArgs\.cmake:[0-9]+ \(_FPHSA_FAILURE_MESSAGE\)
+  FindBeforeProject\.cmake:[0-9]+ \(find_package_handle_standard_args\)
+  BeforeProject-Error\.cmake:[0-9]+ \(find_package\)
+  CMakeLists\.txt:[0-9]+ \(include\)$

Tests/RunCMake/FPHSA/BeforeProject-Error.cmake

@@ -0,0 +1,2 @@
+set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}")
+find_package(BeforeProject REQUIRED)

Tests/RunCMake/FPHSA/BeforeProject-Missing-stdout.txt

@@ -0,0 +1,2 @@
+-- Could NOT find BeforeProject \(missing: SOME_VAR\)[ ]*
+Hint: The project\(\) command has not yet been called\.  It sets up system-specific search paths\.

Tests/RunCMake/FPHSA/BeforeProject-Missing.cmake

@@ -0,0 +1,2 @@
+set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}")
+find_package(BeforeProject)

Tests/RunCMake/FPHSA/CMakeLists.txt

@@ -1,3 +1,8 @@
 cmake_minimum_required(VERSION 3.5)
+if(RunCMake_TEST MATCHES "^BeforeProject")
+  include(${RunCMake_TEST}.cmake)
+  project(${RunCMake_TEST} NONE)
+  return()
+endif()
 project(${RunCMake_TEST} NONE)
 include(${RunCMake_TEST}.cmake)

Tests/RunCMake/FPHSA/FindBeforeProject.cmake

@@ -0,0 +1,3 @@
+set(SOME_VAR FALSE)
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(BeforeProject REQUIRED_VARS SOME_VAR)

Tests/RunCMake/FPHSA/NameMismatch-stderr.txt

@@ -5,9 +5,9 @@ CMake Warning \(dev\) at .*/Modules/FindPackageHandleStandardArgs.cmake:[0-9]+ \
   `find_package` result variables \(e.g., `_FOUND`\) to follow a certain
   pattern.
 Call Stack \(most recent call first\):
-  FindNameMismatch.cmake:3 \(find_package_handle_standard_args\)
-  NameMismatch.cmake:3 \(find_package\)
-  CMakeLists.txt:3 \(include\)
+  FindNameMismatch.cmake:[0-9]+ \(find_package_handle_standard_args\)
+  NameMismatch.cmake:[0-9]+ \(find_package\)
+  CMakeLists.txt:[0-9]+ \(include\)
 This warning is for project developers.  Use -Wno-dev to suppress it.
 
 CMake Warning \(dev\) at .*/Modules/FindPackageHandleStandardArgs.cmake:[0-9]+ \(message\):
@@ -17,7 +17,7 @@ CMake Warning \(dev\) at .*/Modules/FindPackageHandleStandardArgs.cmake:[0-9]+ \
   `find_package` result variables \(e.g., `_FOUND`\) to follow a certain
   pattern.
 Call Stack \(most recent call first\):
-  FindNameMismatchOld.cmake:3 \(find_package_handle_standard_args\)
-  NameMismatch.cmake:4 \(find_package\)
-  CMakeLists.txt:3 \(include\)
+  FindNameMismatchOld.cmake:[0-9]+ \(find_package_handle_standard_args\)
+  NameMismatch.cmake:[0-9]+ \(find_package\)
+  CMakeLists.txt:[0-9]+ \(include\)
 This warning is for project developers.  Use -Wno-dev to suppress it.

Tests/RunCMake/FPHSA/RunCMakeTest.cmake

@@ -1,6 +1,8 @@
 include(RunCMake)
 
 run_cmake(BadFoundVar)
+run_cmake(BeforeProject-Error)
+run_cmake(BeforeProject-Missing)
 run_cmake(NameMismatch)
 
 # The pseudo module will "find" a package with the given version. Check if the