FindPython: Ensure Apple Xcode python 3 is usable

The python 3 distributed as part of Xcode requires the specification
of a 'rpath' pointing at frameowrks root for a correct execution.

Fixes: #21293

Help/release/3.19.rst

@@ -189,6 +189,10 @@ Modules
 * The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
   modules gained the capability to manage a version range.
 
+* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
+  modules provide, respectively, the variable ``Python3_LINK_OPTIONS``,
+  ``Python2_LINK_OPTIONS`` and ``Python_LINK_OPTIONS`` for link options.
+
 * The :module:`FindSDL` module now provides:
 
   * imported target ``SDL::SDL``,

Modules/FindPython.cmake

@@ -142,6 +142,9 @@ This module will set the following variables in your project
   System has the Python development artifacts for Python embedding.
 ``Python_INCLUDE_DIRS``
   The Python include directories.
+``Python_LINK_OPTIONS``
+  The Python link options. Some configurations require specific link options
+  for a correct build and execution.
 ``Python_LIBRARIES``
   The Python libraries.
 ``Python_LIBRARY_DIRS``

Modules/FindPython/Support.cmake

@@ -2990,6 +2990,29 @@ if (("Development.Module" IN_LIST ${_PYTHON_PREFIX}_FIND_COMPONENTS
                 ${_PYTHON_PREFIX}_PyPy_VERSION "${${_PYTHON_PREFIX}_PyPy_VERSION}")
   endif()
 
+  unset(${_PYTHON_PREFIX}_LINK_OPTIONS)
+  if (${_PYTHON_PREFIX}_Development.Embed_FOUND AND APPLE
+      AND ${_PYTHON_PREFIX}_LIBRARY_RELEASE MATCHES "${CMAKE_SHARED_LIBRARY_SUFFIX}$")
+    # rpath must be specified if python is part of a framework
+    unset(_${_PYTHON_PREFIX}_is_prefix)
+    foreach (_${_PYTHON_PREFIX}_implementation IN LISTS _${_PYTHON_PREFIX}_FIND_IMPLEMENTATIONS)
+      foreach (_${_PYTHON_PREFIX}_framework IN LISTS _${_PYTHON_PREFIX}_${_${_PYTHON_PREFIX}_implementation}_FRAMEWORKS)
+        cmake_path (IS_PREFIX _${_PYTHON_PREFIX}_framework "${${_PYTHON_PREFIX}_LIBRARY_RELEASE}" _${_PYTHON_PREFIX}_is_prefix)
+        if (_${_PYTHON_PREFIX}_is_prefix)
+          cmake_path (GET _${_PYTHON_PREFIX}_framework PARENT_PATH _${_PYTHON_PREFIX}_framework)
+          set (${_PYTHON_PREFIX}_LINK_OPTIONS "LINKER:-rpath,${_${_PYTHON_PREFIX}_framework}")
+          break()
+        endif()
+      endforeach()
+      if (_${_PYTHON_PREFIX}_is_prefix)
+        break()
+      endif()
+    endforeach()
+    unset(_${_PYTHON_PREFIX}_implementation)
+    unset(_${_PYTHON_PREFIX}_framework)
+    unset(_${_PYTHON_PREFIX}_is_prefix)
+  endif()
+
   if (NOT DEFINED ${_PYTHON_PREFIX}_SOABI)
     _python_get_config_var (${_PYTHON_PREFIX}_SOABI SOABI)
   endif()
@@ -3202,6 +3225,11 @@ if(_${_PYTHON_PREFIX}_CMAKE_ROLE STREQUAL "PROJECT")
                         PROPERTY INTERFACE_LINK_LIBRARIES ${_${_PYTHON_PREFIX}_LINK_LIBRARIES})
         endif()
       endif()
+
+      if (${_PYTHON_PREFIX}_LINK_OPTIONS
+          AND _${_PYTHON_PREFIX}_LIBRARY_TYPE STREQUAL "SHARED")
+        set_property (TARGET ${__name} PROPERTY INTERFACE_LINK_OPTIONS "${${_PYTHON_PREFIX}_LINK_OPTIONS}")
+      endif()
     endmacro()
 
     if (${_PYTHON_PREFIX}_Development.Embed_FOUND)

Modules/FindPython2.cmake

@@ -134,6 +134,9 @@ This module will set the following variables in your project
   System has the Python 2 development artifacts for Python embedding.
 ``Python2_INCLUDE_DIRS``
   The Python 2 include directories.
+``Python2_LINK_OPTIONS``
+  The Python 2 link options. Some configurations require specific link options
+  for a correct build and execution.
 ``Python2_LIBRARIES``
   The Python 2 libraries.
 ``Python2_LIBRARY_DIRS``

Modules/FindPython3.cmake

@@ -143,6 +143,9 @@ This module will set the following variables in your project
   System has the Python 3 development artifacts for Python embedding.
 ``Python3_INCLUDE_DIRS``
   The Python 3 include directories.
+``Python3_LINK_OPTIONS``
+  The Python 3 link options. Some configurations require specific link options
+  for a correct build and execution.
 ``Python3_LIBRARIES``
   The Python 3 libraries.
 ``Python3_LIBRARY_DIRS``