From a46395df06a87f10aae22706543b1899bd314dba Mon Sep 17 00:00:00 2001
From: Ben Boeckel <ben.boeckel@kitware.com>
Date: Tue, 14 May 2024 16:03:16 -0400
Subject: [PATCH] importstd: clarify when the experimental UUID must be
 available

Fixes: #25980
---
 Help/dev/experimental.rst                                  | 3 ++-
 Modules/Compiler/CMakeCommonCompilerMacros.cmake           | 2 +-
 Tests/RunCMake/CXXModules/NoCXX23TargetRequired-stderr.txt | 2 +-
 Tests/RunCMake/CXXModules/NoCXX26TargetRequired-stderr.txt | 2 +-
 4 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/Help/dev/experimental.rst b/Help/dev/experimental.rst
index 93298c54bb..35ea34f89c 100644
--- a/Help/dev/experimental.rst
+++ b/Help/dev/experimental.rst
@@ -50,7 +50,8 @@ set
 
 This UUID may change in future versions of CMake.  Be sure to use the value
 documented here by the source tree of the version of CMake with which you are
-experimenting.
+experimenting.  It must be set before the ``CXX`` toolchain is discovered by
+CMake, usually as part of a :command:`project` call.
 
 When activated, this experimental feature provides the following:
 
diff --git a/Modules/Compiler/CMakeCommonCompilerMacros.cmake b/Modules/Compiler/CMakeCommonCompilerMacros.cmake
index 75a9da228f..ffd02ec50e 100644
--- a/Modules/Compiler/CMakeCommonCompilerMacros.cmake
+++ b/Modules/Compiler/CMakeCommonCompilerMacros.cmake
@@ -250,7 +250,7 @@ function(cmake_create_cxx_import_std std variable)
     _cmake_supported_import_std_experimental)
   if (NOT _cmake_supported_import_std_experimental)
     set("${variable}"
-      "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Experimental `import std` support not enabled when detecting toolchain\")\n"
+      "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Experimental `import std` support not enabled when detecting toolchain; it must be set before `CXX` is enabled (usually a `project()` call)\")\n"
       PARENT_SCOPE)
     return ()
   endif ()
diff --git a/Tests/RunCMake/CXXModules/NoCXX23TargetRequired-stderr.txt b/Tests/RunCMake/CXXModules/NoCXX23TargetRequired-stderr.txt
index e3d31c5a6e..866fa55f9c 100644
--- a/Tests/RunCMake/CXXModules/NoCXX23TargetRequired-stderr.txt
+++ b/Tests/RunCMake/CXXModules/NoCXX23TargetRequired-stderr.txt
@@ -3,7 +3,7 @@ CMake Error in CMakeLists.txt:
   the "__CMAKE::CXX23" target exist, but it was not provided by the
   toolchain.  Reason:
 
-    (Toolchain does not support discovering `import std` support|Experimental `import std` support not enabled when detecting toolchain|Unsupported generator: [^\n]*)
+    (Toolchain does not support discovering `import std` support|Experimental `import std` support not enabled when detecting toolchain; it must be set before `CXX` is enabled \(usually a `project\(\)` call\)|Unsupported generator: [^\n]*)
 
 
 CMake Generate step failed.  Build files cannot be regenerated correctly.
diff --git a/Tests/RunCMake/CXXModules/NoCXX26TargetRequired-stderr.txt b/Tests/RunCMake/CXXModules/NoCXX26TargetRequired-stderr.txt
index 8addcb2452..6e14f1e8ac 100644
--- a/Tests/RunCMake/CXXModules/NoCXX26TargetRequired-stderr.txt
+++ b/Tests/RunCMake/CXXModules/NoCXX26TargetRequired-stderr.txt
@@ -3,7 +3,7 @@ CMake Error in CMakeLists.txt:
   the "__CMAKE::CXX26" target exist, but it was not provided by the
   toolchain.  Reason:
 
-    (Toolchain does not support discovering `import std` support|Experimental `import std` support not enabled when detecting toolchain|Unsupported generator: [^\n]*)
+    (Toolchain does not support discovering `import std` support|Experimental `import std` support not enabled when detecting toolchain; it must be set before `CXX` is enabled \(usually a `project\(\)` call\)|Unsupported generator: [^\n]*)
 
 
 CMake Generate step failed.  Build files cannot be regenerated correctly.