PIE link options: Update strategy to fix performance regression

Fixes: #18700

6 files changed, 55 insertions, 2 deletions

diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst
index f50fcb61ae..cf9e06f164 100644
--- a/Help/command/try_compile.rst
+++ b/Help/command/try_compile.rst
@@ -134,6 +134,11 @@ default values:
 If :policy:`CMP0056` is set to ``NEW``, then
 :variable:`CMAKE_EXE_LINKER_FLAGS` is passed in as well.
 
+If :policy:`CMP0083` is set to ``NEW``, then in order to obtain correct
+behavior at link time, the ``check_pie_supported()`` command from the
+:module:`CheckPIESupported` module must be called before using the
+:command:`try_compile` command.
+
 The current settings of :policy:`CMP0065` and :policy:`CMP0083` are set in the
 generated project.
 
diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst
index 2f08a047fd..940186a144 100644
--- a/Help/manual/cmake-modules.7.rst
+++ b/Help/manual/cmake-modules.7.rst
@@ -35,6 +35,7 @@ These modules are loaded using the :command:`include` command.
    /module/CheckIncludeFiles
    /module/CheckLanguage
    /module/CheckLibraryExists
+   /module/CheckPIESupported
    /module/CheckPrototypeDefinition
    /module/CheckStructHasMember
    /module/CheckSymbolExists
diff --git a/Help/module/CheckPIESupported.rst b/Help/module/CheckPIESupported.rst
new file mode 100644
index 0000000000..02e7b43169
--- /dev/null
+++ b/Help/module/CheckPIESupported.rst
@@ -0,0 +1 @@
+.. cmake-module:: ../../Modules/CheckPIESupported.cmake
diff --git a/Help/policy/CMP0083.rst b/Help/policy/CMP0083.rst
index 7b467b0b37..b26d6c8d96 100644
--- a/Help/policy/CMP0083.rst
+++ b/Help/policy/CMP0083.rst
@@ -17,8 +17,46 @@ is set:
   passed to the linker step. For example ``-no-pie`` for ``GCC``.
 * Not set: no flags are passed to the linker step.
 
+Since a given linker may not support ``PIE`` flags in all environments in
+which it is used, it is the project's responsibility to use the
+:module:`CheckPIESupported` module to check for support to ensure that the
+:prop_tgt:`POSITION_INDEPENDENT_CODE` target property for executables will be
+honored at link time.
+
 This policy was introduced in CMake version 3.14.  CMake version
 |release| warns when the policy is not set and uses ``OLD`` behavior.  Use
 the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
 
 .. include:: DEPRECATED.txt
+
+Examples
+^^^^^^^^
+
+Behave like CMake 3.13 and do not apply any ``PIE`` flags at link stage.
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 3.13)
+  project(foo)
+
+  # ...
+
+  add_executable(foo ...)
+  set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
+
+Use the :module:`CheckPIESupported` module to detect whether ``PIE`` is
+supported by the current linker and environment.  Apply ``PIE`` flags only
+if the linker supports them.
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 3.14) # CMP0083 NEW
+  project(foo)
+
+  include(CheckPIESupported)
+  check_pie_supported()
+
+  # ...
+
+  add_executable(foo ...)
+  set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
diff --git a/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst b/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst
index 54af8c6ded..0aaf66bd0e 100644
--- a/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst
+++ b/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst
@@ -9,3 +9,8 @@ property is ``True`` by default for ``SHARED`` and ``MODULE`` library
 targets and ``False`` otherwise.  This property is initialized by the value
 of the :variable:`CMAKE_POSITION_INDEPENDENT_CODE` variable  if it is set
 when a target is created.
+
+.. note::
+
+  For executable targets, the link step is controlled by the :policy:`CMP0083`
+  policy and the :module:`CheckPIESupported` module.
diff --git a/Help/release/dev/link-option-PIE.rst b/Help/release/dev/link-option-PIE.rst
index 824ab2ceac..872343ca84 100644
--- a/Help/release/dev/link-option-PIE.rst
+++ b/Help/release/dev/link-option-PIE.rst
@@ -2,5 +2,8 @@ link-option-PIE
 ---------------
 
 * Required link options to manage Position Independent Executable are now
-  added when :prop_tgt:`POSITION_INDEPENDENT_CODE` is set. These flags are
-  controlled by policy :policy:`CMP0083`.
+  added when :prop_tgt:`POSITION_INDEPENDENT_CODE` is set.  The project is
+  responsible for using the :module:`CheckPIESupported` module to check for
+  ``PIE`` support to ensure that the :prop_tgt:`POSITION_INDEPENDENT_CODE`
+  target property will be honored at link time for executables.  This behavior
+  is controlled by policy :policy:`CMP0083`.