Add CMAKE_<LANG>_STANDARD_LATEST variables

Add a variable to indicate the latest standard known to be supported for
each language:

* `CMAKE_C_STANDARD_LATEST`
* `CMAKE_CXX_STANDARD_LATEST`
* `CMAKE_CUDA_STANDARD_LATEST`
* `CMAKE_HIP_STANDARD_LATEST`
* `CMAKE_OBJC_STANDARD_LATEST`
* `CMAKE_OBJCXX_STANDARD_LATEST`

These variables, more generally referred to as
`CMAKE_<LANG>_STANDARD_LATEST`, are assigned an integer value which
represents the minimum between the latest version of the associated
language standard supported by the current compiler and the latest
version supported by CMake.

Add documentation for these variables in a new page called
`CMAKE_<LANG>_STANDARD_LATEST` was added under the "Variables for
Languages" section of the `cmake-variables(7)` page.

Update each compiler-specific CMake script under
`${CMAKE_ROOT}\Modules\Compiler` to manually define the relevant
`CMAKE_<LANG>_STANDARD_LATEST` variable as necessary. This will
require updating and maintaining as newer compiler versions become
recognized by CMake.

Closes: #25717

1 files changed, 64 insertions, 0 deletions

diff --git a/Help/variable/CMAKE_LANG_STANDARD_LATEST.rst b/Help/variable/CMAKE_LANG_STANDARD_LATEST.rst
new file mode 100644
index 0000000..3a759cf
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_STANDARD_LATEST.rst
@@ -0,0 +1,64 @@
+CMAKE_<LANG>_STANDARD_LATEST
+-----------------------------
+
+.. versionadded:: 3.30
+
+This variable represents the minimum between the latest version of the
+standard for language ``<LANG>`` which is supported by the current compiler
+and the latest version which is supported by CMake. Its value will be set to
+one of the supported values of the corresponding :prop_tgt:`<LANG>_STANDARD`
+target property; see the documentation of that property for a list of
+supported languages.
+
+See the :manual:`cmake-compile-features(7)` manual for information on compile
+features and a list of supported compilers.
+
+.. note::
+
+  ``CMAKE_<LANG>_STANDARD_LATEST`` will never be set to a language standard
+  which CMake recognizes but provides no support for. Unless explicitly
+  stated otherwise, every value which is supported by the corresponding
+  :prop_tgt:`<LANG>_STANDARD` target property represents a standard of
+  language ``<LANG>`` which is both recognized and supported by CMake.
+
+Checking for Language Standard Support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to use the value of the ``CMAKE_<LANG>_STANDARD_LATEST``
+variable to check for language standard support. This can be used to, e.g.,
+conditionally enable optional features for a distributed library.
+
+When doing so, one should be careful to **not** rely on integer value
+comparisons between standard levels. This is because some older standards of
+a given language which are supported by CMake (e.g., C++98, represented as
+``98``) will have a higher numerical value than newer standards of that same
+language.
+
+The following code sample demonstrates how one might correctly check for
+C++17 support:
+
+.. code-block:: cmake
+
+  # Careful! We cannot do direct integer comparisons with
+  # CMAKE_CXX_STANDARD_LATEST because some earlier C++ standards (e.g.,
+  # C++98) will have a higher numerical value than our requirement (C++17).
+  #
+  # Instead, we keep a list of unsupported C++ standards and check if
+  # CMAKE_CXX_STANDARD_LATEST appears in that list.
+  set(UNSUPPORTED_CXX_STANDARDS
+    98
+    11
+    14
+  )
+
+  list(FIND UNSUPPORTED_CXX_STANDARDS ${CMAKE_CXX_STANDARD_LATEST} UNSUPPORTED_CXX_STANDARDS_INDEX)
+
+  if(UNSUPPORTED_CXX_STANDARDS_INDEX EQUAL -1)
+    # We know that the current compiler supports at least C++17. Enabling
+    # some optional feature...
+  else()
+    message(STATUS
+      "Feature X is disabled because it requires C++17, but the current "
+      "compiler only supports C++${CMAKE_CXX_STANDARD_LATEST}."
+    )
+  endif()