try_compile: Pass linker flags into test project (#14066)

Copy CMAKE_EXE_LINKER_FLAGS into the test project generated by
try_compile, just like we already copy CMAKE_<LANG>_FLAGS.

Add CMake Policy CMP0056 to activate this behavior in a compatible way,
but do not warn by default when the policy is not set since it will
affect all try_compile calls.

Extend the RunCMake.try_compile test with a case covering this behavior
for each policy setting.

4 files changed, 41 insertions, 0 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 742fd63..96f39e6 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -113,3 +113,4 @@ All Policies
    /policy/CMP0053
    /policy/CMP0054
    /policy/CMP0055
+   /policy/CMP0056
diff --git a/Help/policy/CMP0056.rst b/Help/policy/CMP0056.rst
new file mode 100644
index 0000000..3c75ff4
--- /dev/null
+++ b/Help/policy/CMP0056.rst
@@ -0,0 +1,32 @@
+CMP0056
+-------
+
+Honor link flags in :command:`try_compile` source-file signature.
+
+The :command:`try_compile` command source-file signature generates a
+``CMakeLists.txt`` file to build the source file into an executable.
+In order to compile the source the same way as it might be compiled
+by the calling project, the generated project sets the value of the
+:variable:`CMAKE_<LANG>_FLAGS` variable to that in the calling project.
+The value of the :variable:`CMAKE_EXE_LINKER_FLAGS` variable may be
+needed in some cases too, but CMake 3.1 and lower did not set it in
+the generated project.  CMake 3.2 and above prefer to set it so that
+linker flags are honored as well as compiler flags.  This policy
+provides compatibility with the pre-3.2 behavior.
+
+The OLD behavior for this policy is to not set the value of the
+:variable:`CMAKE_EXE_LINKER_FLAGS` variable in the generated test
+project.  The NEW behavior for this policy is to set the value of
+the :variable:`CMAKE_EXE_LINKER_FLAGS` variable in the test project
+to the same as it is in the calling project.
+
+If the project code does not set the policy explicitly, users may
+set it on the command line by defining the
+:variable:`CMAKE_POLICY_DEFAULT_CMP0056 <CMAKE_POLICY_DEFAULT_CMP<NNNN>>`
+variable in the cache.
+
+This policy was introduced in CMake version 3.2.  Unlike most policies,
+CMake version |release| does *not* warn by default when this policy
+is not set and simply uses OLD behavior.  See documentation of the
+:variable:`CMAKE_POLICY_WARNING_CMP0056 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
+variable to control the warning.
diff --git a/Help/release/dev/try_compile-link-flags.rst b/Help/release/dev/try_compile-link-flags.rst
new file mode 100644
index 0000000..d995e0b
--- /dev/null
+++ b/Help/release/dev/try_compile-link-flags.rst
@@ -0,0 +1,6 @@
+try_compile-link-flags
+----------------------
+
+* The :command:`try_compile` command source file signature now honors
+  link flags (e.g. :variable:`CMAKE_EXE_LINKER_FLAGS`) in the generated
+  test project.  See policy :policy:`CMP0056`.
diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst
index b563aea..a83c807 100644
--- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst
+++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst
@@ -9,6 +9,8 @@ warn by default:
   policy :policy:`CMP0025`.
 * ``CMAKE_POLICY_WARNING_CMP0047`` controls the warning for
   policy :policy:`CMP0047`.
+* ``CMAKE_POLICY_WARNING_CMP0056`` controls the warning for
+  policy :policy:`CMP0056`.
 
 This variable should not be set by a project in CMake code.  Project
 developers running CMake may set this variable in their cache to