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.