cxximportstd: support setting the import std metadata location

Some deployments may not be able to discover the metadata file reliably
(e.g., custom `clang` builds on macOS while using the SDK's stdlib or
distribution bugs). Allow users to force the location so that
compiler-driven detection doesn't have to bend over backwards for
unforeseen bugs.

Help/manual/cmake-variables.7.rst

@@ -45,6 +45,7 @@ Variables that Provide Information
    /variable/CMAKE_CURRENT_LIST_FILE
    /variable/CMAKE_CURRENT_LIST_LINE
    /variable/CMAKE_CURRENT_SOURCE_DIR
+   /variable/CMAKE_CXX_STDLIB_MODULES_JSON
    /variable/CMAKE_DEBUG_TARGET_PROPERTIES
    /variable/CMAKE_DIRECTORY_LABELS
    /variable/CMAKE_DL_LIBS

Help/release/dev/cxxmodules-custom-import-std-metadata-file.rst

@@ -0,0 +1,7 @@
+cxxmodules-custom-import-std-metadata-file
+------------------------------------------
+
+* The ``import std`` support learned to use the
+  :variable:`CMAKE_CXX_STDLIB_MODULES_JSON` variable to set the path to the
+  metadata file for the standard library rather than using the compiler to
+  discover its location.

Help/variable/CMAKE_CXX_STDLIB_MODULES_JSON.rst

@@ -0,0 +1,11 @@
+CMAKE_CXX_STDLIB_MODULES_JSON
+-----------------------------
+
+.. versionadded:: 4.2
+
+This variable may be used to set the path to a metadata file for CMake to
+understand how the ``import std`` target for the active CXX compiler should be
+constructed.
+
+This should only be used when the compiler does not know how to discover the
+relevant module metadata file without such assistance.

Modules/Compiler/Clang-CXX-CXXImportStd.cmake

@@ -10,21 +10,25 @@ function (_cmake_cxx_import_std std variable)
     return ()
   endif ()
 
-  execute_process(
+  if (CMAKE_CXX_STDLIB_MODULES_JSON)
-    COMMAND
+    set(_clang_libcxx_modules_json_file "${CMAKE_CXX_STDLIB_MODULES_JSON}")
-      "${CMAKE_CXX_COMPILER}"
+  else ()
-      ${CMAKE_CXX_COMPILER_ID_ARG1}
+    execute_process(
-      "-print-file-name=${_clang_modules_json_impl}.modules.json"
+      COMMAND
-    OUTPUT_VARIABLE _clang_libcxx_modules_json_file
+        "${CMAKE_CXX_COMPILER}"
-    ERROR_VARIABLE _clang_libcxx_modules_json_file_err
+        ${CMAKE_CXX_COMPILER_ID_ARG1}
-    RESULT_VARIABLE _clang_libcxx_modules_json_file_res
+        "-print-file-name=${_clang_modules_json_impl}.modules.json"
-    OUTPUT_STRIP_TRAILING_WHITESPACE
+      OUTPUT_VARIABLE _clang_libcxx_modules_json_file
-    ERROR_STRIP_TRAILING_WHITESPACE)
+      ERROR_VARIABLE _clang_libcxx_modules_json_file_err
-  if (_clang_libcxx_modules_json_file_res)
+      RESULT_VARIABLE _clang_libcxx_modules_json_file_res
-    set("${variable}"
+      OUTPUT_STRIP_TRAILING_WHITESPACE
-      "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Could not find `${_clang_modules_json_impl}.modules.json` resource\")\n"
+      ERROR_STRIP_TRAILING_WHITESPACE)
-      PARENT_SCOPE)
+    if (_clang_libcxx_modules_json_file_res)
-    return ()
+      set("${variable}"
+        "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Could not find `${_clang_modules_json_impl}.modules.json` resource\")\n"
+        PARENT_SCOPE)
+      return ()
+    endif ()
   endif ()
 
   # Without this file, we do not have modules installed.

Modules/Compiler/GNU-CXX-CXXImportStd.cmake

@@ -6,21 +6,25 @@ function (_cmake_cxx_import_std std variable)
     return ()
   endif ()
 
-  execute_process(
+  if (CMAKE_CXX_STDLIB_MODULES_JSON)
-    COMMAND
+    set(_gnu_libstdcxx_modules_json_file "${CMAKE_CXX_STDLIB_MODULES_JSON}")
-      "${CMAKE_CXX_COMPILER}"
+  else ()
-      ${CMAKE_CXX_COMPILER_ID_ARG1}
+    execute_process(
-      -print-file-name=libstdc++.modules.json
+      COMMAND
-    OUTPUT_VARIABLE _gnu_libstdcxx_modules_json_file
+        "${CMAKE_CXX_COMPILER}"
-    ERROR_VARIABLE _gnu_libstdcxx_modules_json_file_err
+        ${CMAKE_CXX_COMPILER_ID_ARG1}
-    RESULT_VARIABLE _gnu_libstdcxx_modules_json_file_res
+        -print-file-name=libstdc++.modules.json
-    OUTPUT_STRIP_TRAILING_WHITESPACE
+      OUTPUT_VARIABLE _gnu_libstdcxx_modules_json_file
-    ERROR_STRIP_TRAILING_WHITESPACE)
+      ERROR_VARIABLE _gnu_libstdcxx_modules_json_file_err
-  if (_gnu_libstdcxx_modules_json_file_res)
+      RESULT_VARIABLE _gnu_libstdcxx_modules_json_file_res
-    set("${variable}"
+      OUTPUT_STRIP_TRAILING_WHITESPACE
-      "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Could not find `libstdc++.modules.json` resource\")\n"
+      ERROR_STRIP_TRAILING_WHITESPACE)
-      PARENT_SCOPE)
+    if (_gnu_libstdcxx_modules_json_file_res)
-    return ()
+      set("${variable}"
+        "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Could not find `libstdc++.modules.json` resource\")\n"
+        PARENT_SCOPE)
+      return ()
+    endif ()
   endif ()
 
   # Without this file, we do not have modules installed.

Modules/Compiler/MSVC-CXX-CXXImportStd.cmake

@@ -1,21 +1,25 @@
 function (_cmake_cxx_import_std std variable)
-  find_file(_msvc_modules_json_file
+  if (CMAKE_CXX_STDLIB_MODULES_JSON)
-    NAME modules.json
+    set(_msvc_modules_json_file "${CMAKE_CXX_STDLIB_MODULES_JSON}")
-    HINTS
+  else ()
-      "$ENV{VCToolsInstallDir}/modules"
+    find_file(_msvc_modules_json_file
-    PATHS
+      NAME modules.json
-      "$ENV{INCLUDE}"
+      HINTS
-      "${CMAKE_CXX_COMPILER}/../../.."
+        "$ENV{VCToolsInstallDir}/modules"
-      "${CMAKE_CXX_COMPILER}/../.."    # msvc-wine layout
+      PATHS
-    PATH_SUFFIXES
+        "$ENV{INCLUDE}"
-      ../modules
+        "${CMAKE_CXX_COMPILER}/../../.."
-    NO_CACHE)
+        "${CMAKE_CXX_COMPILER}/../.."    # msvc-wine layout
-  # Without this file, we do not have modules installed.
+      PATH_SUFFIXES
-  if (NOT EXISTS "${_msvc_modules_json_file}")
+        ../modules
-    set("${variable}"
+      NO_CACHE)
-      "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Could not find `modules.json` resource\")\n"
+    # Without this file, we do not have modules installed.
-      PARENT_SCOPE)
+    if (NOT EXISTS "${_msvc_modules_json_file}")
-    return ()
+      set("${variable}"
+        "set(CMAKE_CXX${std}_COMPILER_IMPORT_STD_NOT_FOUND_MESSAGE \"Could not find `modules.json` resource\")\n"
+        PARENT_SCOPE)
+      return ()
+    endif ()
   endif ()
 
   file(READ "${_msvc_modules_json_file}" _msvc_modules_json)

Source/cmCoreTryCompile.cxx

@@ -1095,6 +1095,7 @@ cm::optional<cmTryCompileResult> cmCoreTryCompile::TryCompileCode(
     vars.emplace("CMAKE_MSVC_RUNTIME_CHECKS"_s);
     vars.emplace("CMAKE_CXX_COMPILER_CLANG_SCAN_DEPS"_s);
     vars.emplace("CMAKE_VS_USE_DEBUG_LIBRARIES"_s);
+    vars.emplace("CMAKE_CXX_STDLIB_MODULES_JSON"_s);
 
     if (cmValue varListStr = this->Makefile->GetDefinition(
           kCMAKE_TRY_COMPILE_PLATFORM_VARIABLES)) {