FindPython: add support for Stable ABI

Fixes: #24141

Help/release/dev/FindPython-Stable-ABI.rst

@@ -0,0 +1,6 @@
+FindPython-Stable-ABI
+---------------------
+
+* The :module:`FindPython3` and :module:`FindPython` modules gain the support
+  of the
+  `Stable Application Binary Interface <https://docs.python.org/3/c-api/stable.html>`_.

Modules/FindPython.cmake

@@ -31,6 +31,13 @@ The following components are supported:
     * ``Development.Embed``: search for artifacts for Python embedding
       developments.
 
+  .. versionadded:: 3.26
+
+    * ``Development.SABIModule``: search for artifacts for Python module
+      developments using the
+      `Stable Application Binary Interface <https://docs.python.org/3/c-api/stable.html>`_.
+      This component is available only for version ``3.2`` and upper.
+
 * ``NumPy``: search for NumPy include directories.
 
 .. versionadded:: 3.14
@@ -80,6 +87,12 @@ This module defines the following :ref:`Imported Targets <Imported Targets>`:
   Python library for Python module. Target defined if component
   ``Development.Module`` is found.
 
+``Python::SABIModule``
+  .. versionadded:: 3.26
+
+  Python library for Python module using the Stable Application Binary
+  Interface. Target defined if component ``Development.SABIModule`` is found.
+
 ``Python::Python``
   Python library for Python embedding. Target defined if component
   ``Development.Embed`` is found.
@@ -145,6 +158,16 @@ This module will set the following variables in your project
   not available, ``sysconfig.get_config_var('EXT_SUFFIX')`` or
   ``sysconfig.get_config_var('SOABI')`` are used.
 
+``Python_SOSABI``
+  .. versionadded:: 3.26
+
+  Extension suffix for modules using the Stable Application Binary Interface.
+
+  Information computed from ``importlib.machinery.EXTENSION_SUFFIXES`` if the
+  COMPONENT ``Interpreter`` was specified. Otherwise, the extension is ``abi3``
+  except for ``Windows``, ``MSYS`` and ``CYGWIN`` for which this is an empty
+  string.
+
 ``Python_Compiler_FOUND``
   System has the Python compiler.
 ``Python_COMPILER``
@@ -166,6 +189,12 @@ This module will set the following variables in your project
 
   System has the Python development artifacts for Python module.
 
+``Python_Development.SABIModule_FOUND``
+  .. versionadded:: 3.26
+
+  System has the Python development artifacts for Python module using the
+  Stable Application Binary Interface.
+
 ``Python_Development.Embed_FOUND``
   .. versionadded:: 3.18
 
@@ -187,6 +216,18 @@ This module will set the following variables in your project
   The Python library directories.
 ``Python_RUNTIME_LIBRARY_DIRS``
   The Python runtime library directories.
+``Python_SABI_LIBRARIES``
+  .. versionadded:: 3.26
+
+  The Python libraries for the Stable Application Binary Interface.
+``Python_SABI_LIBRARY_DIRS``
+  .. versionadded:: 3.26
+
+  The Python ``SABI`` library directories.
+``Python_RUNTIME_SABI_LIBRARY_DIRS``
+  .. versionadded:: 3.26
+
+  The Python runtime ``SABI`` library directories.
 ``Python_VERSION``
   Python version.
 ``Python_VERSION_MAJOR``
@@ -425,6 +466,13 @@ setting the following variables:
   variables ``Python_LIBRARIES``, ``Python_LIBRARY_DIRS`` and
   ``Python_RUNTIME_LIBRARY_DIRS``.
 
+``Python_SABI_LIBRARY``
+  .. versionadded:: 3.26
+
+  The path to the library for Stable Application Binary Interface. It will be
+  used to compute the variables ``Python_SABI_LIBRARIES``,
+  ``Python_SABI_LIBRARY_DIRS`` and ``Python_RUNTIME_SABI_LIBRARY_DIRS``.
+
 ``Python_INCLUDE_DIR``
   The path to the directory of the ``Python`` headers. It will be used to
   compute the variable ``Python_INCLUDE_DIRS``.
@@ -470,10 +518,11 @@ Commands
 This module defines the command ``Python_add_library`` (when
 :prop_gbl:`CMAKE_ROLE` is ``PROJECT``), which has the same semantics as
 :command:`add_library` and adds a dependency to target ``Python::Python`` or,
-when library type is ``MODULE``, to target ``Python::Module`` and takes care of
-Python module naming rules::
+when library type is ``MODULE``, to target ``Python::Module`` or
+``Python::SABIModule`` (when ``USE_SABI`` option is specified) and takes care
+of Python module naming rules::
 
-  Python_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
+  Python_add_library (<name> [STATIC | SHARED | MODULE [USE_SABI <version>] [WITH_SOABI]]
                       <source1> [<source2> ...])
 
 If the library type is not specified, ``MODULE`` is assumed.
@@ -481,6 +530,19 @@ If the library type is not specified, ``MODULE`` is assumed.
 .. versionadded:: 3.17
   For ``MODULE`` library type, if option ``WITH_SOABI`` is specified, the
   module suffix will include the ``Python_SOABI`` value, if any.
+
+.. versionadded:: 3.26
+  For ``MODULE`` type, if the option ``USE_SABI`` is specified, the
+  preprocessor definition ``Py_LIMITED_API`` will be specified, as ``PRIVATE``,
+  for the target ``<name>`` with the value computed from ``<version>`` argument.
+  The expected format for ``<version>`` is ``major[.minor]``, where each
+  component is a numeric value. If ``minor`` component is specified, the
+  version should be, at least, ``3.2`` which is the version where the
+  `Stable Application Binary Interface <https://docs.python.org/3/c-api/stable.html>`_
+  was introduced. Specifying only major version ``3`` is equivalent to ``3.2``.
+
+  When option ``WITH_SOABI`` is also specified,  the module suffix will include
+  the ``Python3_SOSABI`` value, if any.
 #]=======================================================================]
 
 

Modules/FindPython3.cmake

@@ -31,6 +31,13 @@ The following components are supported:
     * ``Development.Embed``: search for artifacts for Python 3 embedding
       developments.
 
+  .. versionadded:: 3.26
+
+    * ``Development.SABIModule``: search for artifacts for Python 3 module
+      developments using the
+      `Stable Application Binary Interface <https://docs.python.org/3/c-api/stable.html>`_.
+      This component is available only for version ``3.2`` and upper.
+
 * ``NumPy``: search for NumPy include directories.
 
 .. versionadded:: 3.14
@@ -81,6 +88,12 @@ This module defines the following :ref:`Imported Targets <Imported Targets>`:
   Python 3 library for Python module. Target defined if component
   ``Development.Module`` is found.
 
+``Python3::SABIModule``
+  .. versionadded:: 3.26
+
+  Python 3 library for Python module using the Stable Application Binary
+  Interface. Target defined if component ``Development.SABIModule`` is found.
+
 ``Python3::Python``
   Python 3 library for Python embedding. Target defined if component
   ``Development.Embed`` is found.
@@ -146,6 +159,16 @@ This module will set the following variables in your project
   not available, ``sysconfig.get_config_var('EXT_SUFFIX')`` or
   ``sysconfig.get_config_var('SOABI')`` are used.
 
+``Python3_SOSABI``
+  .. versionadded:: 3.26
+
+  Extension suffix for modules using the Stable Application Binary Interface.
+
+  Information computed from ``importlib.machinery.EXTENSION_SUFFIXES`` if the
+  COMPONENT ``Interpreter`` was specified. Otherwise, the extension is ``abi3``
+  except for ``Windows``, ``MSYS`` and ``CYGWIN`` for which this is an empty
+  string.
+
 ``Python3_Compiler_FOUND``
   System has the Python 3 compiler.
 ``Python3_COMPILER``
@@ -168,6 +191,12 @@ This module will set the following variables in your project
 
   System has the Python 3 development artifacts for Python module.
 
+``Python3_Development.SABIModule_FOUND``
+  .. versionadded:: 3.26
+
+  System has the Python 3 development artifacts for Python module using the
+  Stable Application Binary Interface.
+
 ``Python3_Development.Embed_FOUND``
   .. versionadded:: 3.18
 
@@ -189,6 +218,18 @@ This module will set the following variables in your project
   The Python 3 library directories.
 ``Python3_RUNTIME_LIBRARY_DIRS``
   The Python 3 runtime library directories.
+``Python3_SABI_LIBRARIES``
+  .. versionadded:: 3.26
+
+  The Python 3 libraries for the Stable Application Binary Interface.
+``Python3_SABI_LIBRARY_DIRS``
+  .. versionadded:: 3.26
+
+  The Python 3 ``SABI`` library directories.
+``Python3_RUNTIME_SABI_LIBRARY_DIRS``
+  .. versionadded:: 3.26
+
+  The Python 3 runtime ``SABI`` library directories.
 ``Python3_VERSION``
   Python 3 version.
 ``Python3_VERSION_MAJOR``
@@ -423,6 +464,13 @@ setting the following variables:
   variables ``Python3_LIBRARIES``, ``Python3_LIBRARY_DIRS`` and
   ``Python3_RUNTIME_LIBRARY_DIRS``.
 
+``Python3_SABI_LIBRARY``
+  .. versionadded:: 3.26
+
+  The path to the library for Stable Application Binary Interface. It will be
+  used to compute the variables ``Python3_SABI_LIBRARIES``,
+  ``Python3_SABI_LIBRARY_DIRS`` and ``Python3_RUNTIME_SABI_LIBRARY_DIRS``.
+
 ``Python3_INCLUDE_DIR``
   The path to the directory of the ``Python`` headers. It will be used to
   compute the variable ``Python3_INCLUDE_DIRS``.
@@ -468,10 +516,11 @@ Commands
 This module defines the command ``Python3_add_library`` (when
 :prop_gbl:`CMAKE_ROLE` is ``PROJECT``), which has the same semantics as
 :command:`add_library` and adds a dependency to target ``Python3::Python`` or,
-when library type is ``MODULE``, to target ``Python3::Module`` and takes care
+when library type is ``MODULE``, to target ``Python3::Module`` or
+``Python3::SABIModule`` (when ``USE_SABI`` option is specified) and takes care
 of Python module naming rules::
 
-  Python3_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
+  Python3_add_library (<name> [STATIC | SHARED | MODULE [USE_SABI <version>] [WITH_SOABI]]
                        <source1> [<source2> ...])
 
 If the library type is not specified, ``MODULE`` is assumed.
@@ -479,6 +528,19 @@ If the library type is not specified, ``MODULE`` is assumed.
 .. versionadded:: 3.17
   For ``MODULE`` library type, if option ``WITH_SOABI`` is specified, the
   module suffix will include the ``Python3_SOABI`` value, if any.
+
+.. versionadded:: 3.26
+  For ``MODULE`` type, if the option ``USE_SABI`` is specified, the
+  preprocessor definition ``Py_LIMITED_API`` will be specified, as ``PRIVATE``,
+  for the target ``<name>`` with the value computed from ``<version>`` argument.
+  The expected format for ``<version>`` is ``major[.minor]``, where each
+  component is a numeric value. If ``minor`` component is specified, the
+  version should be, at least, ``3.2`` which is the version where the
+  `Stable Application Binary Interface <https://docs.python.org/3/c-api/stable.html>`_
+  was introduced. Specifying only major version ``3`` is equivalent to ``3.2``.
+
+  When option ``WITH_SOABI`` is also specified,  the module suffix will include
+  the ``Python3_SOSABI`` value, if any.
 #]=======================================================================]
 
 

Tests/CMakeLists.txt

@@ -1538,8 +1538,11 @@ if(BUILD_TESTING)
     add_subdirectory(GoogleTest)
   endif()
 
-  if(CMake_TEST_FindPython OR CMake_TEST_FindPython_NumPy
+  if(CMake_TEST_FindPython OR CMake_TEST_FindPython_SABIModule OR CMake_TEST_FindPython_NumPy
       OR CMake_TEST_FindPython_Conda OR CMake_TEST_FindPython_IronPython OR CMake_TEST_FindPython_PyPy)
+    if (CMake_TEST_FindPython AND CMAKE_SYSTEM_NAME MATCHES "Linux|Darwin")
+      set(CMake_TEST_FindPython_SABIModule TRUE)
+    endif()
     add_subdirectory(FindPython)
   endif()
 

Tests/FindPython/CMakeLists.txt

@@ -377,6 +377,7 @@ if(CMake_TEST_FindPython)
     --build-options ${build_options} "-Dbuild_generator_args=${build_generator_args}"
     "-DCMake_SOURCE_DIR=${CMake_SOURCE_DIR}"
     "-DCMake_BINARY_DIR=${CMake_BINARY_DIR}"
+    "-DCMake_TEST_FindPython_SABIModule=${CMake_TEST_FindPython_SABIModule}"
     --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
     )
 
@@ -478,6 +479,35 @@ if(CMake_TEST_FindPython)
   endif()
 endif()
 
+if(CMake_TEST_FindPython_SABIModule)
+  add_test(NAME FindPython.Python2.Development.SABIModule COMMAND
+    ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+    --build-and-test
+    "${CMake_SOURCE_DIR}/Tests/FindPython/Python2SABIModule"
+    "${CMake_BINARY_DIR}/Tests/FindPython/Python2SABIModule"
+    ${build_generator_args}
+    --build-project TestPython2SABIModule
+    --build-options ${build_options}
+    --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
+    )
+    set_tests_properties(FindPython.Python2.Development.SABIModule PROPERTIES
+      PASS_REGULAR_EXPRESSION "Could NOT find Python2 \\(missing: .*Development\\.SABIModule")
+
+  # Use exclusively Release configuration because Debug is, on Windows with MSVC,
+  # unusable with SABI: Python force link with debug version of full versioned library rather than
+  # the stable ABI one.
+  add_test(NAME FindPython.Python3.Development.SABIModule COMMAND
+    ${CMAKE_CTEST_COMMAND} -C Release
+    --build-and-test
+    "${CMake_SOURCE_DIR}/Tests/FindPython/Python3SABIModule"
+    "${CMake_BINARY_DIR}/Tests/FindPython/Python3SABIModule"
+    ${build_generator_args}
+    --build-project TestPython3SABIModule
+    --build-options ${build_options}
+    --test-command ${CMAKE_CTEST_COMMAND} -V -C Release
+    )
+endif()
+
 if(CMake_TEST_FindPython_NumPy)
   add_test(NAME FindPython.NumPy COMMAND
     ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>

Tests/FindPython/Python2SABIModule/CMakeLists.txt

@@ -0,0 +1,5 @@
+cmake_minimum_required(VERSION 3.1)
+
+project(TestPython2SABIModule LANGUAGES C)
+
+find_package(Python2 REQUIRED COMPONENTS Interpreter Development.Module Development.SABIModule)

Tests/FindPython/Python3Module/CMakeLists.txt

@@ -11,6 +11,9 @@ endif()
 if (Python3_Development_FOUND)
   message (FATAL_ERROR "Python 3, COMPONENT 'Development' unexpectedly found")
 endif()
+if (Python3_Development.SABIModule_FOUND)
+  message (FATAL_ERROR "Python 3, COMPONENT 'Development.SABIModule' unexpectedly found")
+endif()
 if (Python3_Development.Embed_FOUND)
   message (FATAL_ERROR "Python 3, COMPONENT 'Development.Embed' unexpectedly found")
 endif()
@@ -25,6 +28,12 @@ endif()
 if(TARGET Python3::Python)
   message(SEND_ERROR "Python3::Python unexpectedly found")
 endif()
+if(TARGET Python3::SABIMOdule)
+  message(SEND_ERROR "Python3::SABIModule unexpectedly found")
+endif()
+if(TARGET Python3::Embed)
+  message(SEND_ERROR "Python3::Embed unexpectedly found")
+endif()
 if(NOT TARGET Python3::Module)
   message(SEND_ERROR "Python3::Module not found")
 endif()

Tests/FindPython/Python3SABIModule/CMakeLists.txt

@@ -0,0 +1,51 @@
+cmake_minimum_required(VERSION 3.1)
+
+project(TestPython3SABIModule LANGUAGES C)
+
+include(CTest)
+
+find_package(Python3 REQUIRED COMPONENTS Interpreter Development.SABIModule)
+if (NOT Python3_FOUND)
+  message (FATAL_ERROR "Failed to find Python 3")
+endif()
+if (Python3_Development_FOUND)
+  message (FATAL_ERROR "Python 3, COMPONENT 'Development' unexpectedly found")
+endif()
+if (Python3_Development.Embed_FOUND)
+  message (FATAL_ERROR "Python 3, COMPONENT 'Development.Embed' unexpectedly found")
+endif()
+if (Python3_Development.Module_FOUND)
+  message (FATAL_ERROR "Python 3, COMPONENT 'Development.Module' unexpectedly found")
+endif()
+if (NOT Python3_Development.SABIModule_FOUND)
+  message (FATAL_ERROR "Python 3, COMPONENT 'Development.SABIModule' not found")
+endif()
+
+if(NOT TARGET Python3::Interpreter)
+  message(SEND_ERROR "Python3::Interpreter not found")
+endif()
+
+if(TARGET Python3::Python)
+  message(SEND_ERROR "Python3::Python unexpectedly found")
+endif()
+if(TARGET Python3::Module)
+  message(SEND_ERROR "Python3::Module unexpectedly found")
+endif()
+if(NOT TARGET Python3::SABIModule)
+  message(SEND_ERROR "Python3::SABIModule not found")
+endif()
+
+Python3_add_library (spam3 MODULE USE_SABI 3 WITH_SOABI ../spam.c)
+target_compile_definitions (spam3 PRIVATE PYTHON3)
+
+if (Python3_SOSABI)
+  get_property (suffix TARGET spam3 PROPERTY SUFFIX)
+  if (NOT suffix MATCHES "^.${Python3_SOSABI}")
+    message(FATAL_ERROR "Module suffix do not include Python3_SOSABI")
+  endif()
+endif()
+
+
+add_test (NAME python3_spam3
+          COMMAND "${CMAKE_COMMAND}" -E env "PYTHONPATH=$<TARGET_FILE_DIR:spam3>"
+          "${Python3_EXECUTABLE}" -c "import spam3; spam3.system(\"cd\")")

Tests/FindPython/RequiredArtifacts/CMakeLists.txt

@@ -8,7 +8,12 @@ find_package(Python2 REQUIRED COMPONENTS Interpreter Development)
 if (NOT Python2_FOUND)
   message (FATAL_ERROR "Failed to find Python 2")
 endif()
-find_package(Python3 REQUIRED COMPONENTS Interpreter Development)
+
+set(components Interpreter Development)
+if (CMake_TEST_FindPython_SABIModule AND WIN32)
+  list (APPEND components Development.SABIModule)
+endif()
+find_package(Python3 REQUIRED COMPONENTS ${components})
 if (NOT Python3_FOUND)
   message (FATAL_ERROR "Failed to find Python 3")
 endif()
@@ -108,3 +113,28 @@ add_test(NAME FindPython.RequiredArtifacts.Library-Include.INVALID COMMAND
                   "-DPython3_INCLUDE_DIR=${Python2_INCLUDE_DIRS}"
   --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
   )
+
+if (CMake_TEST_FindPython_SABIModule AND WIN32)
+  add_test(NAME FindPython.RequiredArtifacts.SABILibrary.VALID COMMAND
+    ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+    --build-and-test
+    "${CMake_SOURCE_DIR}/Tests/FindPython/RequiredArtifacts/Check"
+    "${CMake_BINARY_DIR}/Tests/FindPython/RequiredArtifacts/SABILibrary.VALID"
+    ${build_generator_args}
+    --build-project TestRequiredArtifacts.Check
+    --build-options -DPYTHON_IS_FOUND=TRUE -DCHECK_SABI_LIBRARY=ON
+    "-DPython3_SABI_LIBRARY=${Python3_SABI_LIBRARY_RELEASE}"
+    --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
+  )
+  add_test(NAME FindPython.RequiredArtifacts.SABILibrary.INVALID COMMAND
+    ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+    --build-and-test
+    "${CMake_SOURCE_DIR}/Tests/FindPython/RequiredArtifacts/Check"
+    "${CMake_BINARY_DIR}/Tests/FindPython/RequiredArtifacts/SABILibrary.INVALID"
+    ${build_generator_args}
+    --build-project TestRequiredArtifacts.Check
+    --build-options -DPYTHON_IS_FOUND=FALSE -DCHECK_SABI_LIBRARY=ON
+    "-DPython3_SABI_LIBRARY=${Python2_LIBRARY_RELEASE}"
+    --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
+  )
+endif()

Tests/FindPython/RequiredArtifacts/Check/CMakeLists.txt

@@ -16,6 +16,10 @@ if (CHECK_LIBRARY OR CHECK_INCLUDE)
     set (required_include "${Python3_INCLUDE_DIR}")
   endif()
 endif()
+if (CHECK_SABI_LIBRARY)
+  list (APPEND components Development.SABIModule)
+  set (required_sabi_library "${Python3_SABI_LIBRARY}")
+endif()
 
 find_package (Python3 COMPONENTS ${components})
 
@@ -39,3 +43,7 @@ endif()
 if (CHECK_INCLUDE AND NOT Python3_INCLUDE_DIRS STREQUAL required_include)
   message (FATAL_ERROR "Failed to use input variable Python3_INCLUDE_DIR")
 endif()
+
+if (CHECK_SABI_LIBRARY AND NOT Python3_SABI_LIBRARY_RELEASE STREQUAL required_sabi_library)
+  message (FATAL_ERROR "Failed to use input variable Python3_SABI_LIBRARY")
+endif()