CheckIPOSupported: Compile check using flags of calling project

Forward `CMAKE_<LANG>_FLAGS` and `CMAKE_<LANG>_FLAGS_DEBUG` from the
calling project into the test project.  The set of flags may affect the
availability of IPO support.  Since this may change the result of the
check for existing projects, add a policy for compatibility.

This was discovered after commit 5fcadc481e (MSVC: Default to -ZI
instead of /Zi for x86 and x64, 2022-05-24) introduced policy CMP0138 to
switch our default for MSVC's debug info flag.  The `-ZI` flag is
incompatible with the `-GL` flag used for IPO, so CMP0138 was reverted
pending future work on an alternative solution.  Re-use the CMP0138
policy number for this change to CheckIPOSupported instead.

Fixes: #23607

3 files changed, 25 insertions, 2 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index d99afe3..43eb200 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -59,7 +59,7 @@ Policies Introduced by CMake 3.24
    :maxdepth: 1
 
    CMP0139: The if() command supports path comparisons using PATH_EQUAL operator. </policy/CMP0139>
-   CMP0138: Placeholder for reverted policy. </policy/CMP0138>
+   CMP0138: CheckIPOSupported uses flags from calling project. </policy/CMP0138>
    CMP0137: try_compile() passes platform variables in project mode. </policy/CMP0137>
    CMP0136: Watcom runtime library flags are selected by an abstraction. </policy/CMP0136>
    CMP0135: ExternalProject ignores timestamps in archives by default for the URL download method. </policy/CMP0135>
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.
diff --git a/Help/release/3.24.rst b/Help/release/3.24.rst
index f347acb..4bde23f 100644
--- a/Help/release/3.24.rst
+++ b/Help/release/3.24.rst
@@ -323,6 +323,11 @@ Other Changes
   etc. when enabling the corresponding language during the first CMake run in
   a build directory.  See policy :policy:`CMP0132`.
 
+* The :module:`CheckIPOSupported` module :command:`check_ipo_supported`
+  command now uses the caller's :variable:`CMAKE_<LANG>_FLAGS`
+  and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values.
+  See policy :policy:`CMP0138`.
+
 * The :generator:`MSYS Makefiles` and :generator:`MinGW Makefiles`
   generators, when a compiler is not explicitly specified, now select
   the first compiler (of any name) found in directories listed by the