cmTarget: support the CXX_MODULE_STD property

Help/manual/cmake-properties.7.rst

@@ -194,6 +194,7 @@ Properties on Targets
    /prop_tgt/CXX_MODULE_SET
    /prop_tgt/CXX_MODULE_SET_NAME
    /prop_tgt/CXX_MODULE_SETS
+   /prop_tgt/CXX_MODULE_STD
    /prop_tgt/CXX_SCAN_FOR_MODULES
    /prop_tgt/CXX_STANDARD
    /prop_tgt/CXX_STANDARD_REQUIRED

Help/manual/cmake-variables.7.rst

@@ -424,6 +424,7 @@ Variables that Control the Build
    /variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS
    /variable/CMAKE_CUDA_RUNTIME_LIBRARY
    /variable/CMAKE_CUDA_SEPARABLE_COMPILATION
+   /variable/CMAKE_CXX_MODULE_STD
    /variable/CMAKE_CXX_SCAN_FOR_MODULES
    /variable/CMAKE_DEBUG_POSTFIX
    /variable/CMAKE_DEFAULT_BUILD_TYPE

Help/prop_tgt/CXX_MODULE_STD.rst

@@ -0,0 +1,36 @@
+CXX_MODULE_STD
+--------------
+
+.. versionadded:: 3.30
+
+``CXX_MODULE_STD`` is a boolean specifying whether the target may use
+``import std;`` its C++ sources or not.
+
+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
+current build and will not appear in the exported interfaces of the targets.
+When consumed, these targets will be reapplied as necessary.
+
+.. note:
+
+   Similar to the introduction of :prop:`CXX_SCAN_FOR_MODULES`, this property
+   defaults to _not_ adding ``import std`` support to targets using
+   ``cxx_std_23`` without an explicit request in order to preserve existing
+   behavior for projects using C++23 without ``import std``. A future policy
+   to change the default behavior is expected once the feature sees wider
+   usage.
+
+This property's value is not relevant for targets which disable scanning (see
+:prop_tgt:`CXX_SCAN_FOR_MODULES`). Additionally, this property only applies to
+targets utilizing C++23 (``cxx_std_23``) or newer.
+
+The property supports
+:manual:`generator expressions <cmake-generator-expressions(7)>`, however
+expressions that depend upon the configuration, the consuming target, or the
+linker language are not allowed. Whether a target uses ``import std`` should
+not depend upon such things as it is a static property of the target's source
+code.
+
+Targets which are exported with C++ module sources will have this property's
+resolved value exported.

Help/release/dev/CXX_MODULE_STD-property.rst

@@ -0,0 +1,5 @@
+CXX_MODULE_STD-property
+-----------------------
+
+* The :prop_tgt:`CXX_MODULE_STD` property may be used to control
+  ``import std;`` support for targets.

Help/variable/CMAKE_CXX_MODULE_STD.rst

@@ -0,0 +1,10 @@
+CMAKE_CXX_MODULE_STD
+--------------------
+
+.. versionadded:: 3.30
+
+Whether to add utility targets as dependencies to targets with at least
+``cxx_std_23`` or not.
+
+This variable is used to initialize the :prop_tgt:`CXX_MODULE_STD` property on
+all targets.  See that target property for additional information.

Source/cmExportFileGenerator.cxx

@@ -1438,6 +1438,14 @@ bool cmExportFileGenerator::PopulateCxxModuleExportProperties(
 
   const ModuleTargetPropertyTable exportedDirectModuleProperties[] = {
     { "CXX_EXTENSIONS"_s, ExportWhen::Defined },
+    // Always define this property as it is an intrinsic property of the target
+    // and should not be inherited from the in-scope `CMAKE_CXX_MODULE_STD`
+    // variable.
+    //
+    // TODO(cxxmodules): A future policy may make this "ON" based on the target
+    // policies if unset. Add a new `ExportWhen` condition to handle it when
+    // this happens.
+    { "CXX_MODULE_STD"_s, ExportWhen::Always },
   };
   for (auto const& prop : exportedDirectModuleProperties) {
     auto const propNameStr = std::string(prop.Name);

Source/cmTarget.cxx

@@ -412,6 +412,7 @@ TargetProperty const StaticTargetProperties[] = {
   COMMON_LANGUAGE_PROPERTIES(C),
   // ---- C++
   COMMON_LANGUAGE_PROPERTIES(CXX),
+  { "CXX_MODULE_STD"_s, IC::CanCompileSources },
   // ---- CSharp
   { "DOTNET_SDK"_s, IC::NonImportedTarget },
   { "DOTNET_TARGET_FRAMEWORK"_s, IC::TargetWithCommands },
@@ -1842,6 +1843,7 @@ void cmTarget::CopyImportedCxxModulesProperties(cmTarget const* tgt)
     "CXX_STANDARD_REQUIRED",
     "CXX_EXTENSIONS",
     "CXX_VISIBILITY_PRESET",
+    "CXX_MODULE_STD",
 
     // Static analysis
     "CXX_CLANG_TIDY",

Tests/RunCMake/property_init/CompileSources.cmake

@@ -100,6 +100,7 @@ set(properties
   "C_LINKER_LAUNCHER"                       "ccache"            "<SAME>"
   ### C++
   "CXX_LINKER_LAUNCHER"                     "ccache"            "<SAME>"
+  "CXX_MODULE_STD"                          "ON"                "<SAME>"
   ### CUDA
   "CUDA_RESOLVE_DEVICE_SYMBOLS"             "ON"                "<SAME>"
   "CUDA_RUNTIME_LIBRARY"                    "Static"            "<SAME>"