Docs: CMake LTO honor global flag

[ax3l]

Description

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.

Suggested changelog entry:

- documentation: improve manual LTO CMake example

[henryiii]

I'd rather show this as an either-or. If your CMake is new enough (and this includes complex issues up till about 3.18, so maybe 3.18+), then CMAKE_INTERPROCEDURAL_OPTIMIZATION should be used; older than that, then pybind11::lto should be used.

[ax3l]

So two independent code samples? The logic might get a bit complex in one listing.

[henryiii]

I was thinking more of a simple mention, like Primarily to older versions of CMake, we provide a pybind11::lto target that manually provides the LTO linker flags independently of the INTERPROCEDURAL_OPTIMIZATION setting.

[ax3l]

I see. I actually think we have that explained in the text.

I find that if someone has a CMake file that supports e.g. 3.15+ and uses our LTO logic, we need to provide a concrete example somewhere, otherwise it might be a bit confusing to people how to derive at a consistent control logic. We can move the example around, but I think it's at least as complex as in the diff, no?

[Skylion007]

I'd rather show this as an either-or. If your CMake is new enough (and this includes complex issues up till about 3.18, so maybe 3.18+), then CMAKE_INTERPROCEDURAL_OPTIMIZATION should be used; older than that, then pybind11::lto should be used.
For a testimonial from an end user.

So I just went about enabling LTO fully in a repo of mine recently. Doing a "FAT" LTO worked fine, but ThinLTO kept causing the linker to segfault. I had to avoid using CMAKE_INTERPROCEDURAL_OPTIMIZATION because there is no way to tell it NOT to use ThinLTO and instead set the -flto flags manually.