Experimental: add an experimental feature gate for `import std`

Help/dev/experimental.rst

@@ -38,3 +38,24 @@ When activated, this experimental feature provides the following:
 * The package name associated with specific targets may be specified
   using the ``CMAKE_EXPORT_FIND_PACKAGE_NAME`` variable and/or
 ``EXPORT_FIND_PACKAGE_NAME`` target property.
+
+C++ ``import std`` support
+==========================
+
+In order to activate support for ``import std`` in C++23 and newer targets,
+set
+
+* variable ``CMAKE_EXPERIMENTAL_CXX_IMPORT_STD`` to
+* value ``0e5b6991-d74f-4b3d-a41c-cf096e0b2508``.
+
+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.
+
+When activated, this experimental feature provides the following:
+
+* The :prop_tgt:`CXX_MODULE_STD` target property and its initializing variable
+  :variable:`CMAKE_CXX_MODULE_STD`.
+
+* Targets with the property set to a true value and at least ``cxx_std_23``
+  may use ``import std;`` in any scanned C++ source file.

Help/manual/cmake-cxxmodules.7.rst

@@ -92,6 +92,12 @@ Compilers which CMake natively supports module dependency scanning include:
 Support for ``import std`` is limited to the following toolchain and standard
 library combinations:
 
+.. note ::
+
+   This support is provided only when experimental support for
+   ``import std;`` has been enabled by the
+   ``CMAKE_EXPERIMENTAL_CXX_IMPORT_STD`` gate.
+
 Generator Support
 =================
 

Help/prop_tgt/CXX_MODULE_STD.rst

@@ -6,6 +6,11 @@ CXX_MODULE_STD
 ``CXX_MODULE_STD`` is a boolean specifying whether the target may use
 ``import std;`` its C++ sources or not.
 
+.. note ::
+
+   This setting is meaningful only when experimental support for ``import
+   std;`` has been enabled by the ``CMAKE_EXPERIMENTAL_CXX_IMPORT_STD`` gate.
+
 When this property is explicitly set to ``ON``, CMake will add a dependency to
 a target which provides the C++ standard library's modules for the C++
 standard applied to the target. This target is only applicable within the

Help/variable/CMAKE_CXX_MODULE_STD.rst

@@ -6,5 +6,10 @@ CMAKE_CXX_MODULE_STD
 Whether to add utility targets as dependencies to targets with at least
 ``cxx_std_23`` or not.
 
+.. note ::
+
+   This setting is meaningful only when experimental support for ``import
+   std;`` has been enabled by the ``CMAKE_EXPERIMENTAL_CXX_IMPORT_STD`` gate.
+
 This variable is used to initialize the :prop_tgt:`CXX_MODULE_STD` property on
 all targets.  See that target property for additional information.

Modules/Compiler/CMakeCommonCompilerMacros.cmake

@@ -229,6 +229,17 @@ function(cmake_create_cxx_import_std std variable)
   if (NOT COMMAND _cmake_cxx_import_std)
     return ()
   endif ()
+
+  # Check the experimental flag. Check it here to avoid triggering warnings in
+  # situations that don't support the feature anyways.
+  set(_cmake_supported_import_std_experimental "")
+  cmake_language(GET_EXPERIMENTAL_FEATURE_ENABLED
+    "CxxImportStd"
+    _cmake_supported_import_std_experimental)
+  if (NOT _cmake_supported_import_std_experimental)
+    return ()
+  endif ()
+
   _cmake_cxx_import_std("${std}" target_definition)
   string(CONCAT guarded_target_definition
     "if (NOT TARGET \"__CMAKE::CXX${std}\")\n"

Source/cmExperimental.cxx

@@ -37,6 +37,15 @@ cmExperimental::FeatureData LookupTable[] = {
     {},
     cmExperimental::TryCompileCondition::Always,
     false },
+  // CxxImportStd
+  { "CxxImportStd",
+    "0e5b6991-d74f-4b3d-a41c-cf096e0b2508",
+    "CMAKE_EXPERIMENTAL_CXX_IMPORT_STD",
+    "CMake's support for `import std;` in C++23 and newer is experimental. It "
+    "is meant only for experimentation and feedback to CMake developers.",
+    {},
+    cmExperimental::TryCompileCondition::Always,
+    false },
 };
 static_assert(sizeof(LookupTable) / sizeof(LookupTable[0]) ==
                 static_cast<size_t>(cmExperimental::Feature::Sentinel),

Source/cmExperimental.h

@@ -19,6 +19,7 @@ public:
   {
     ExportPackageDependencies,
     WindowsKernelModeDriver,
+    CxxImportStd,
 
     Sentinel,
   };

Source/cmGeneratorTarget.cxx

@@ -32,6 +32,7 @@
 #include "cmCustomCommandGenerator.h"
 #include "cmCxxModuleUsageEffects.h"
 #include "cmEvaluatedTargetProperty.h"
+#include "cmExperimental.h"
 #include "cmFileSet.h"
 #include "cmFileTimes.h"
 #include "cmGeneratedFileStream.h"
@@ -8502,6 +8503,14 @@ bool cmGeneratorTarget::ApplyCXXStdTargets()
       break;
     }
 
+    // Check the experimental feature here as well. A toolchain may have
+    // provided the target and skipped the check in the toolchain preparation
+    // logic.
+    if (!cmExperimental::HasSupportEnabled(
+          *this->Makefile, cmExperimental::Feature::CxxImportStd)) {
+      break;
+    }
+
     this->Target->AppendProperty(
       "LINK_LIBRARIES",
       cmStrCat("$<BUILD_LOCAL_INTERFACE:$<$<CONFIG:", config, ">:", targetName,

Tests/RunCMake/CXXModules/examples/import-std-export-no-std-build-stderr.txt

@@ -0,0 +1,8 @@
+CMake Warning \(dev\) at .*/Modules/Compiler/CMakeCommonCompilerMacros.cmake:[0-9]* \(cmake_language\):
+  CMake's support for `import std;` in C\+\+23 and newer is experimental.  It
+  is meant only for experimentation and feedback to CMake developers.
+Call Stack \(most recent call first\):
+  .*/Modules/CMakeDetermineCompilerSupport.cmake:[0-9]* \(cmake_create_cxx_import_std\)
+  .*/Modules/CMakeTestCXXCompiler.cmake:[0-9]* \(CMAKE_DETERMINE_COMPILER_SUPPORT\)
+  CMakeLists.txt:[0-9]* \(project\)
+This warning is for project developers.  Use -Wno-dev to suppress it.

Tests/RunCMake/CXXModules/examples/import-std-export-no-std-build/CMakeLists.txt

@@ -1,3 +1,6 @@
+set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD
+  "0e5b6991-d74f-4b3d-a41c-cf096e0b2508")
+
 cmake_minimum_required(VERSION 3.29)
 project(cxx_modules_import_std_export_no_std CXX)
 

Tests/RunCMake/CXXModules/examples/import-std-export-no-std-install-stderr.txt

@@ -0,0 +1,8 @@
+CMake Warning \(dev\) at .*/Modules/Compiler/CMakeCommonCompilerMacros.cmake:[0-9]* \(cmake_language\):
+  CMake's support for `import std;` in C\+\+23 and newer is experimental.  It
+  is meant only for experimentation and feedback to CMake developers.
+Call Stack \(most recent call first\):
+  .*/Modules/CMakeDetermineCompilerSupport.cmake:[0-9]* \(cmake_create_cxx_import_std\)
+  .*/Modules/CMakeTestCXXCompiler.cmake:[0-9]* \(CMAKE_DETERMINE_COMPILER_SUPPORT\)
+  CMakeLists.txt:[0-9]* \(project\)
+This warning is for project developers.  Use -Wno-dev to suppress it.

Tests/RunCMake/CXXModules/examples/import-std-export-no-std-install/CMakeLists.txt

@@ -1,3 +1,6 @@
+set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD
+  "0e5b6991-d74f-4b3d-a41c-cf096e0b2508")
+
 cmake_minimum_required(VERSION 3.29)
 project(cxx_modules_import_std_export_no_std CXX)
 

Tests/RunCMake/CXXModules/examples/import-std-no-std-property-stderr.txt

@@ -0,0 +1,8 @@
+CMake Warning \(dev\) at .*/Modules/Compiler/CMakeCommonCompilerMacros.cmake:[0-9]* \(cmake_language\):
+  CMake's support for `import std;` in C\+\+23 and newer is experimental.  It
+  is meant only for experimentation and feedback to CMake developers.
+Call Stack \(most recent call first\):
+  .*/Modules/CMakeDetermineCompilerSupport.cmake:[0-9]* \(cmake_create_cxx_import_std\)
+  .*/Modules/CMakeTestCXXCompiler.cmake:[0-9]* \(CMAKE_DETERMINE_COMPILER_SUPPORT\)
+  CMakeLists.txt:[0-9]* \(project\)
+This warning is for project developers.  Use -Wno-dev to suppress it.

Tests/RunCMake/CXXModules/examples/import-std-no-std-property/CMakeLists.txt

@@ -1,3 +1,6 @@
+set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD
+  "0e5b6991-d74f-4b3d-a41c-cf096e0b2508")
+
 cmake_minimum_required(VERSION 3.29)
 project(cxx_modules_import_std_no_std_property CXX)
 

Tests/RunCMake/CXXModules/examples/import-std-not-in-export-build-stderr.txt

@@ -0,0 +1,8 @@
+CMake Warning \(dev\) at .*/Modules/Compiler/CMakeCommonCompilerMacros.cmake:[0-9]* \(cmake_language\):
+  CMake's support for `import std;` in C\+\+23 and newer is experimental.  It
+  is meant only for experimentation and feedback to CMake developers.
+Call Stack \(most recent call first\):
+  .*/Modules/CMakeDetermineCompilerSupport.cmake:[0-9]* \(cmake_create_cxx_import_std\)
+  .*/Modules/CMakeTestCXXCompiler.cmake:[0-9]* \(CMAKE_DETERMINE_COMPILER_SUPPORT\)
+  CMakeLists.txt:[0-9]* \(project\)
+This warning is for project developers.  Use -Wno-dev to suppress it.

Tests/RunCMake/CXXModules/examples/import-std-not-in-export-build/CMakeLists.txt

@@ -1,3 +1,6 @@
+set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD
+  "0e5b6991-d74f-4b3d-a41c-cf096e0b2508")
+
 cmake_minimum_required(VERSION 3.29)
 project(cxx_modules_import_std_not_in_export CXX)
 

Tests/RunCMake/CXXModules/examples/import-std-not-in-export-install-stderr.txt

@@ -0,0 +1,8 @@
+CMake Warning \(dev\) at .*/Modules/Compiler/CMakeCommonCompilerMacros.cmake:[0-9]* \(cmake_language\):
+  CMake's support for `import std;` in C\+\+23 and newer is experimental.  It
+  is meant only for experimentation and feedback to CMake developers.
+Call Stack \(most recent call first\):
+  .*/Modules/CMakeDetermineCompilerSupport.cmake:[0-9]* \(cmake_create_cxx_import_std\)
+  .*/Modules/CMakeTestCXXCompiler.cmake:[0-9]* \(CMAKE_DETERMINE_COMPILER_SUPPORT\)
+  CMakeLists.txt:[0-9]* \(project\)
+This warning is for project developers.  Use -Wno-dev to suppress it.

Tests/RunCMake/CXXModules/examples/import-std-not-in-export-install/CMakeLists.txt

@@ -1,3 +1,6 @@
+set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD
+  "0e5b6991-d74f-4b3d-a41c-cf096e0b2508")
+
 cmake_minimum_required(VERSION 3.29)
 project(cxx_modules_import_std_not_in_export CXX)
 

Tests/RunCMake/CXXModules/examples/import-std-stderr.txt

@@ -0,0 +1,8 @@
+CMake Warning \(dev\) at .*/Modules/Compiler/CMakeCommonCompilerMacros.cmake:[0-9]* \(cmake_language\):
+  CMake's support for `import std;` in C\+\+23 and newer is experimental.  It
+  is meant only for experimentation and feedback to CMake developers.
+Call Stack \(most recent call first\):
+  .*/Modules/CMakeDetermineCompilerSupport.cmake:[0-9]* \(cmake_create_cxx_import_std\)
+  .*/Modules/CMakeTestCXXCompiler.cmake:[0-9]* \(CMAKE_DETERMINE_COMPILER_SUPPORT\)
+  CMakeLists.txt:[0-9]* \(project\)
+This warning is for project developers.  Use -Wno-dev to suppress it.

Tests/RunCMake/CXXModules/examples/import-std-transitive-not-in-export-build-stderr.txt

@@ -0,0 +1,8 @@
+CMake Warning \(dev\) at .*/Modules/Compiler/CMakeCommonCompilerMacros.cmake:[0-9]* \(cmake_language\):
+  CMake's support for `import std;` in C\+\+23 and newer is experimental.  It
+  is meant only for experimentation and feedback to CMake developers.
+Call Stack \(most recent call first\):
+  .*/Modules/CMakeDetermineCompilerSupport.cmake:[0-9]* \(cmake_create_cxx_import_std\)
+  .*/Modules/CMakeTestCXXCompiler.cmake:[0-9]* \(CMAKE_DETERMINE_COMPILER_SUPPORT\)
+  CMakeLists.txt:[0-9]* \(project\)
+This warning is for project developers.  Use -Wno-dev to suppress it.

Tests/RunCMake/CXXModules/examples/import-std-transitive-not-in-export-install-stderr.txt

@@ -0,0 +1,8 @@
+CMake Warning \(dev\) at .*/Modules/Compiler/CMakeCommonCompilerMacros.cmake:[0-9]* \(cmake_language\):
+  CMake's support for `import std;` in C\+\+23 and newer is experimental.  It
+  is meant only for experimentation and feedback to CMake developers.
+Call Stack \(most recent call first\):
+  .*/Modules/CMakeDetermineCompilerSupport.cmake:[0-9]* \(cmake_create_cxx_import_std\)
+  .*/Modules/CMakeTestCXXCompiler.cmake:[0-9]* \(CMAKE_DETERMINE_COMPILER_SUPPORT\)
+  CMakeLists.txt:[0-9]* \(project\)
+This warning is for project developers.  Use -Wno-dev to suppress it.

Tests/RunCMake/CXXModules/examples/import-std-transitive/CMakeLists.txt

@@ -1,3 +1,6 @@
+set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD
+  "0e5b6991-d74f-4b3d-a41c-cf096e0b2508")
+
 cmake_minimum_required(VERSION 3.29)
 
 if (EXPORT_NO_STD)

Tests/RunCMake/CXXModules/examples/import-std/CMakeLists.txt

@@ -1,3 +1,6 @@
+set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD
+  "0e5b6991-d74f-4b3d-a41c-cf096e0b2508")
+
 cmake_minimum_required(VERSION 3.29)
 project(cxx_modules_import_std CXX)
 

Tests/RunCMake/cmake_language/Experimental/CxxImportStd-set-stderr.txt

@@ -0,0 +1,6 @@
+CMake Warning \(dev\) at Experimental/CxxImportStd-set.cmake:4 \(cmake_language\):
+  CMake's support for `import std;` in C\+\+23 and newer is experimental.  It
+  is meant only for experimentation and feedback to CMake developers.
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.

Tests/RunCMake/cmake_language/Experimental/CxxImportStd-set.cmake

@@ -0,0 +1,11 @@
+set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD
+  "0e5b6991-d74f-4b3d-a41c-cf096e0b2508")
+
+cmake_language(GET_EXPERIMENTAL_FEATURE_ENABLED
+  "CxxImportStd"
+  feature_present)
+
+if (NOT feature_present STREQUAL "TRUE")
+  message(FATAL_ERROR
+    "Expected the `CxxImportStd` feature to be enabled.")
+endif ()

Tests/RunCMake/cmake_language/Experimental/CxxImportStd-unset.cmake

@@ -0,0 +1,8 @@
+cmake_language(GET_EXPERIMENTAL_FEATURE_ENABLED
+  "CxxImportStd"
+  feature_present)
+
+if (NOT feature_present STREQUAL "FALSE")
+  message(FATAL_ERROR
+    "Expected the `CxxImportStd` feature to be disabled.")
+endif ()

Tests/RunCMake/cmake_language/RunCMakeTest.cmake

@@ -157,6 +157,8 @@ run_cmake_command(
     -P ${RunCMake_SOURCE_DIR}/get_message_log_level.cmake
   )
 
+run_cmake(Experimental/CxxImportStd-set)
+run_cmake(Experimental/CxxImportStd-unset)
 run_cmake(Experimental/ExportPackageDependencies-set)
 run_cmake(Experimental/ExportPackageDependencies-unset)
 run_cmake(Experimental/WindowsKernelModeDriver-set)