Merge topic 'ipo-policy-CMP0069'

dfa8263f Implement interprocedural optimization for GNU compilers
1588a577 Add policy CMP0069 to enforce INTERPROCEDURAL_OPTIMIZATION
a7575700 Refactoring: s,GetFeatureAsBool,IsIPOEnabled,
e05835c3 CheckIPOSupported: Visual Studio and Xcode generators do not support IPO

Acked-by: Kitware Robot <kwrobot@kitware.com>
Reviewed-by: Brad King <brad.king@kitware.com>
Reviewed-by: Nils Gladitz <nilsgladitz@gmail.com>
Merge-request: !568

4 files changed, 108 insertions, 0 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 0c9ee2d..7b85817 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.9
 .. toctree::
    :maxdepth: 1
 
+   CMP0069: INTERPROCEDURAL_OPTIMIZATION is enforced when enabled. </policy/CMP0069>
    CMP0068: RPATH settings on macOS do not affect install_name. </policy/CMP0068>
 
 Policies Introduced by CMake 3.8
diff --git a/Help/policy/CMP0069.rst b/Help/policy/CMP0069.rst
new file mode 100644
index 0000000..b8f5d80
--- /dev/null
+++ b/Help/policy/CMP0069.rst
@@ -0,0 +1,92 @@
+CMP0069
+-------
+
+:prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` is enforced when enabled.
+
+CMake 3.9 and newer prefer to add IPO flags whenever the
+:prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property is enabled and
+produce an error if flags are not known to CMake for the current compiler.
+Since a given compiler may not support IPO flags in all environments in which
+it is used, it is now the project's responsibility to use the
+:module:`CheckIPOSupported` module to check for support before enabling the
+:prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property.  This approach
+allows a project to conditionally activate IPO when supported.  It also
+allows an end user to set the :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION`
+variable in an environment known to support IPO even if the project does
+not enable the property.
+
+Since CMake 3.8 and lower only honored :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION`
+for the Intel compiler on Linux, some projects may unconditionally enable the
+target property.  Policy ``CMP0069`` provides compatibility with such projects.
+
+This policy takes effect whenever the IPO property is enabled.  The ``OLD``
+behavior for this policy is to add IPO flags only for Intel compiler on Linux.
+The ``NEW`` behavior for this policy is to add IPO flags for the current
+compiler or produce an error if CMake does not know the flags.
+
+This policy was introduced in CMake version 3.9.  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.8 and do not apply any IPO flags except for Intel compiler
+on Linux:
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 3.8)
+  project(foo)
+
+  # ...
+
+  set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
+
+Use the :module:`CheckIPOSupported` module to detect whether IPO is
+supported by the current compiler, environment, and CMake version.
+Produce a fatal error if support is not available:
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 3.9) # CMP0069 NEW
+  project(foo)
+
+  include(CheckIPOSupport)
+  check_ipo_support()
+
+  # ...
+
+  set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
+
+Apply IPO flags only if compiler supports it:
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 3.9) # CMP0069 NEW
+  project(foo)
+
+  include(CheckIPOSupport)
+
+  # ...
+
+  check_ipo_support(RESULT result)
+  if(result)
+    set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
+  endif()
+
+Apply IPO flags without any checks.  This may lead to build errors if IPO
+is not supported by the compiler in the current environment.  Produce an
+error if CMake does not know IPO flags for the current compiler:
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 3.9) # CMP0069 NEW
+  project(foo)
+
+  # ...
+
+  set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
diff --git a/Help/release/dev/gcc-ipo.rst b/Help/release/dev/gcc-ipo.rst
new file mode 100644
index 0000000..ebc5c0d
--- /dev/null
+++ b/Help/release/dev/gcc-ipo.rst
@@ -0,0 +1,7 @@
+GCC IPO
+-------
+
+* Interprocedural optimization (IPO) is now supported for GNU
+  compilers using link time optimization (LTO) flags.  See the
+  :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property and
+  :module:`CheckIPOSupported` module.
diff --git a/Help/release/dev/interprocedural_optimization_policy.rst b/Help/release/dev/interprocedural_optimization_policy.rst
new file mode 100644
index 0000000..93a9d68
--- /dev/null
+++ b/Help/release/dev/interprocedural_optimization_policy.rst
@@ -0,0 +1,8 @@
+interprocedural_optimization_policy
+-----------------------------------
+
+* The :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property is now enforced
+  when enabled.  CMake will add IPO flags unconditionally or produce an error
+  if it does not know the flags for the current compiler.  The project is now
+  responsible to use the :module:`CheckIPOSupported` module to check for IPO
+  support before enabling the target property.  See policy :policy:`CMP0069`.