Merge topic 'CheckIPOSupported-honor-flags' into release-3.24

ec08bc1752 CheckIPOSupported: Compile check using flags of calling project

Acked-by: Kitware Robot <kwrobot@kitware.com>
Tested-by: buildbot <buildbot@kitware.com>
Merge-request: !7343

1 files changed, 19 insertions, 1 deletions

diff --git a/Help/policy/CMP0138.rst b/Help/policy/CMP0138.rst
index c7f0e2d..a86849d 100644
--- a/Help/policy/CMP0138.rst
+++ b/Help/policy/CMP0138.rst
@@ -3,7 +3,25 @@ CMP0138
 
 .. versionadded:: 3.24
 
-Placeholder for reverted policy.
+:module:`CheckIPOSupported` uses flags from calling project.
+
+The :module:`CheckIPOSupported` module :command:`check_ipo_supported`
+command compiles a test project to determine whether the toolchain
+supports :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION`.  CMake 3.23 and
+below run the check with the default values of the
+:variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
+variables for the current environment and toolchain settings.
+However, some projects may modify these flag variables to add
+flags that affect availability of the toolchain's IPO features.
+CMake 3.24 and above prefer to honor the calling project's values
+for these variables.  This policy provides compatibility for projects
+that have not been updated to expect this behavior.
+
+The ``OLD`` behavior for this policy is to ignore the calling
+project's values of :variable:`CMAKE_<LANG>_FLAGS` and
+:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`.  The ``NEW`` behavior
+for this policy is to use the values of those variables as
+compiler flags in the test project.
 
 This policy was introduced in CMake version 3.24. Use the
 :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.