Merge 9851db19ad into 1f8b4a7f1a

In this example, the IPO/LTO flags should not be added if the
general property is already set for all targets via
`CMAKE_INTERPROCEDURAL_OPTIMIZATION`.

Also, if `CMAKE_INTERPROCEDURAL_OPTIMIZATION` is set to `OFF`, LTO
flags should also not be added. This is sometimes needed when working
around compiler bugs with IPO/LTO, e.g. on ppc64le with some
toolchains.

docs/compiling.rst

@@ -588,6 +588,26 @@ You can use these targets to build complex applications. For example, the
     set_target_properties(example PROPERTIES CXX_VISIBILITY_PRESET "hidden"
                                              CUDA_VISIBILITY_PRESET "hidden")
 
+Since prior to CMake 3.18 the ``INTERPROCEDURAL_OPTIMIZATION`` property exists but is not working reliably, a manual user section around linking the legacy ``pybind11::lto`` target should look like this:
+
+.. code-block:: cmake
+
+    # LTO/IPO: CMake target properties work well for 3.18+ and are buggy before
+    set(_USE_PY_LTO ON)  # default shall be ON
+    if(DEFINED CMAKE_INTERPROCEDURAL_OPTIMIZATION)  # overwrite default if defined
+        if(NOT CMAKE_INTERPROCEDURAL_OPTIMIZATION)
+            set(_USE_PY_LTO OFF)
+        endif()
+    endif()
+    if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.18)
+        set_target_properties(example PROPERTIES
+            INTERPROCEDURAL_OPTIMIZATION ${_USE_PY_LTO})
+    else()
+        if(_USE_PY_LTO)
+            target_link_libraries(example PRIVATE pybind11::lto)
+        endif()
+    endif()
+
 Instead of setting properties, you can set ``CMAKE_*`` variables to initialize these correctly.
 
 .. warning::

tools/pybind11NewTools.cmake

@@ -274,10 +274,6 @@ function(pybind11_add_module target_name)
     target_link_libraries(${target_name} PRIVATE pybind11::embed)
   endif()
 
-  if(MSVC)
-    target_link_libraries(${target_name} PRIVATE pybind11::windows_extras)
-  endif()
-
   # -fvisibility=hidden is required to allow multiple modules compiled against
   # different pybind versions to work properly, and for some features (e.g.
   # py::module_local).  We force it on everything inside the `pybind11`