cmStandardLevelResolver: Avoid unnecessary flags, fix unset level logic

The changes are part of CMP0128.

When the standard level is unset:
* Flags are added if extension mode doesn't match the compiler's default.
  Previously logic only worked if LANG_EXTENSIONS was ON. Fixes #22224.
* The full flag is used. Previously CMAKE_LANG_EXTENSION_COMPILE_OPTION was
  used. This was only supported for IAR.

Otherwise:
* Avoid adding flags if not necessary per the detected compiler defaults.
* Fixed check for when the requested standard is older. It now matches the
  nearby comments.

I reworded the fallback comment as its logic was a bit difficult to wrap my
head around.

1 files changed, 78 insertions, 0 deletions

diff --git a/Help/policy/CMP0128.rst b/Help/policy/CMP0128.rst
new file mode 100644
index 0000000..f341f24
--- /dev/null
+++ b/Help/policy/CMP0128.rst
@@ -0,0 +1,78 @@
+CMP0128
+-------
+
+.. versionadded:: 3.22
+
+When this policy is set to ``NEW``:
+
+* :prop_tgt:`<LANG>_EXTENSIONS` is initialized to
+  :variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`.
+
+* Extensions are correctly disabled/enabled if :prop_tgt:`<LANG>_STANDARD` is
+  unset.
+
+* Standard mode-affecting flags aren't added unless necessary to achieve the
+  specified mode.
+
+The ``OLD`` behavior:
+
+* Initializes :prop_tgt:`<LANG>_EXTENSIONS` to ``ON``.
+
+* Always adds a flag if :prop_tgt:`<LANG>_STANDARD` is set and
+  :prop_tgt:`<LANG>_STANDARD_REQUIRED` is ``OFF``.
+
+* If :prop_tgt:`<LANG>_STANDARD` is unset:
+
+  * Doesn't disable extensions even if :prop_tgt:`<LANG>_EXTENSIONS` is
+    ``OFF``.
+
+  * Fails to enable extensions if :prop_tgt:`<LANG>_EXTENSIONS` is ``ON``
+    except for the ``IAR`` compiler.
+
+Code may need to be updated for the ``NEW`` behavior in the following cases:
+
+* If :prop_tgt:`<LANG>_EXTENSIONS` matches
+  :variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT` or is unset and the compiler's
+  default satisfies :prop_tgt:`<LANG>_STANDARD` but the compiled code requires
+  the exact standard specified.
+  Such code should set :prop_tgt:`<LANG>_STANDARD_REQUIRED` to ``ON``.
+
+  For example:
+
+  .. code-block:: cmake
+
+    cmake_minimum_required(VERSION |release|)
+    project(example C)
+
+    add_executable(exe main.c)
+    set_property(TARGET exe PROPERTY C_STANDARD 99)
+
+  If the compiler defaults to C11 then the standard specification for C99 is
+  satisfied and CMake will pass no flags. ``main.c`` will no longer compile if
+  it is incompatible with C11.
+
+* If a standard mode flag previously overridden by CMake's and not used during
+  compiler detection now takes effect due to CMake no longer adding one as the
+  default detected is appropriate.
+
+  Such code should be converted to either:
+
+  * Use :prop_tgt:`<LANG>_STANDARD` and :prop_tgt:`<LANG>_EXTENSIONS` instead
+    of manually adding flags.
+
+  * Or ensure the manually-specified flags are used during compiler detection.
+
+If compiler flags affecting the standard mode are used during compiler
+detection (for example in :manual:`a toolchain file <cmake-toolchains(7)>`
+using :variable:`CMAKE_<LANG>_FLAGS_INIT`) then they will affect the detected
+default :variable:`standard <CMAKE_<LANG>_STANDARD_DEFAULT>` and
+:variable:`extensions <CMAKE_<LANG>_EXTENSIONS_DEFAULT>`.
+
+Unlike many policies, CMake version |release| does *not* warn when the policy
+is not set and simply uses the ``OLD`` behavior. Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+See documentation of the
+:variable:`CMAKE_POLICY_WARNING_CMP0128 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
+variable to control the warning.
+
+.. include:: DEPRECATED.txt