FindPython: add Python_FIND_ABI hint.

This variable will enable to specify will ABIs will be searched.

Help/release/dev/FindPython-FIND_ABI.rst

+FindPython-FIND_ABI
+-------------------
+
+* Modules :module:`FindPython3` and :module:`FindPython` gain the capability
+  to control which ``ABIs`` will be searched.

Modules/FindPython.cmake

@@ -137,6 +137,51 @@ Hints
   * If set to TRUE, search **only** for static libraries.
   * If set to FALSE, search **only** for shared libraries.
 
+``Python_FIND_ABI``
+  This variable defines which ABIs, as defined in
+  `PEP 3149 <https://www.python.org/dev/peps/pep-3149/>`_, should be searched.
+
+  .. note::
+
+    This hint will be honored only when searched for ``Python`` version 3.
+
+  .. note::
+
+    If ``Python_FIND_ABI`` is not defined, any ABI will be searched.
+
+  The ``Python_FIND_ABI`` variable is a 3-tuple specifying, in that order,
+  ``pydebug`` (``d``), ``pymalloc`` (``m``) and ``unicode`` (``u``) flags.
+  Each element can be set to one of the following:
+
+  * ``ON``: Corresponding flag is selected.
+  * ``OFF``: Corresponding flag is not selected.
+  * ``ANY``: The two posibilties (``ON`` and ``OFF``) will be searched.
+
+  From this 3-tuple, various ABIs will be searched starting from the most
+  specialized to the most general. Moreover, ``debug`` versions will be
+  searched **after** ``non-debug`` ones.
+
+  For example, if we have::
+
+    set (Python_FIND_ABI "ON" "ANY" "ANY")
+
+  The following flags combinations will be appended, in that order, to the
+  artifact names: ``dmu``, ``dm``, ``du``, and ``d``.
+
+  And to search any possible ABIs::
+
+    set (Python_FIND_ABI "ANY" "ANY" "ANY")
+
+  The following combinations, in that order, will be used: ``mu``, ``m``,
+  ``u``, ``<empty>``, ``dmu``, ``dm``, ``du`` and ``d``.
+
+  .. note::
+
+    This hint is useful only on ``POSIX`` systems. So, on ``Windows`` systems,
+    when ``Python_FIND_ABI`` is defined, ``Python`` distributions from
+    `python.org <https://www.python.org/>`_ will be found only if value for
+    each flag is ``OFF`` or ``ANY``.
+
 ``Python_FIND_STRATEGY``
   This variable defines how lookup will be done.
   The ``Python_FIND_STRATEGY`` variable can be set to empty or one of the

Modules/FindPython3.cmake

@@ -138,6 +138,47 @@ Hints
   * If set to TRUE, search **only** for static libraries.
   * If set to FALSE, search **only** for shared libraries.
 
+``Python3_FIND_ABI``
+  This variable defines which ABIs, as defined in
+  `PEP 3149 <https://www.python.org/dev/peps/pep-3149/>`_, should be searched.
+
+  .. note::
+
+    If ``Python3_FIND_ABI`` is not defined, any ABI will be searched.
+
+  The ``Python3_FIND_ABI`` variable is a 3-tuple specifying, in that order,
+  ``pydebug`` (``d``), ``pymalloc`` (``m``) and ``unicode`` (``u``) flags.
+  Each element can be set to one of the following:
+
+  * ``ON``: Corresponding flag is selected.
+  * ``OFF``: Corresponding flag is not selected.
+  * ``ANY``: The two posibilties (``ON`` and ``OFF``) will be searched.
+
+  From this 3-tuple, various ABIs will be searched starting from the most
+  specialized to the most general. Moreover, ``debug`` versions will be
+  searched **after** ``non-debug`` ones.
+
+  For example, if we have::
+
+    set (Python3_FIND_ABI "ON" "ANY" "ANY")
+
+  The following flags combinations will be appended, in that order, to the
+  artifact names: ``dmu``, ``dm``, ``du``, and ``d``.
+
+  And to search any possible ABIs::
+
+    set (Python3_FIND_ABI "ANY" "ANY" "ANY")
+
+  The following combinations, in that order, will be used: ``mu``, ``m``,
+  ``u``, ``<empty>``, ``dmu``, ``dm``, ``du`` and ``d``.
+
+  .. note::
+
+    This hint is useful only on ``POSIX`` systems. So, on ``Windows`` systems,
+    when ``Python3_FIND_ABI`` is defined, ``Python`` distributions from
+    `python.org <https://www.python.org/>`_ will be found only if value for
+    each flag is ``OFF`` or ``ANY``.
+
 ``Python3_FIND_STRATEGY``
   This variable defines how lookup will be done.
   The ``Python3_FIND_STRATEGY`` variable can be set to empty or one of the

Tests/FindPython/FindPythonScript.cmake

-find_package(${PYTHON_PACKAGE_NAME} REQUIRED QUIET)
+
+if (PYTHON_MUST_NOT_BE_FOUND)
+  find_package(${PYTHON_PACKAGE_NAME} QUIET)
+  if (${PYTHON_PACKAGE_NAME}_FOUND)
+    message(FATAL_ERROR "${PYTHON_PACKAGE_NAME}: unexpectedly founded.")
+  endif()
+else()
+  find_package(${PYTHON_PACKAGE_NAME} REQUIRED QUIET)
+endif()

Tests/FindPython/Python2/CMakeLists.txt

@@ -34,4 +34,5 @@ add_test (NAME python2_spam2
 
 add_test(NAME findpython2_script
          COMMAND "${CMAKE_COMMAND}" -DPYTHON_PACKAGE_NAME=Python2
+         -DPython2_FIND_STRATEGY=${Python2_FIND_STRATEGY}
          -P "${CMAKE_CURRENT_LIST_DIR}/../FindPythonScript.cmake")

Tests/FindPython/Python3/CMakeLists.txt

@@ -34,4 +34,57 @@ add_test (NAME python3_spam3
 
 add_test(NAME findpython3_script
          COMMAND "${CMAKE_COMMAND}" -DPYTHON_PACKAGE_NAME=Python3
+         -DPython3_FIND_STRATEGY=${Python3_FIND_STRATEGY}
+         -P "${CMAKE_CURRENT_LIST_DIR}/../FindPythonScript.cmake")
+
+
+## Try a new search specifying only expected ABI
+# retrieve ABI of python interpreter
+execute_process (COMMAND "${Python3_EXECUTABLE}" -c
+                         "import sys; sys.stdout.write(sys.abiflags)"
+                 RESULT_VARIABLE result
+                 OUTPUT_VARIABLE abi
+                 ERROR_QUIET
+                 OUTPUT_STRIP_TRAILING_WHITESPACE)
+if (result)
+  # assume ABI is not supported
+  set (abi "")
+endif()
+
+# define FIND_ABI variable
+if (abi MATCHES "d")
+  set (Python3_VALID_ABI "ON")
+else()
+  set (Python3_VALID_ABI "OFF")
+endif()
+if (abi MATCHES "m")
+  list (APPEND Python3_VALID_ABI "ON")
+else()
+  list (APPEND Python3_VALID_ABI "OFF")
+endif()
+if (abi MATCHES "u")
+  list (APPEND Python3_VALID_ABI "ON")
+else()
+  list (APPEND Python3_VALID_ABI "OFF")
+endif()
+# build an invalid pattern for ABI
+set (Python3_INVALID_ABI)
+foreach (abi IN LISTS Python3_VALID_ABI)
+  if (abi)
+    list (APPEND Python3_INVALID_ABI "OFF")
+  else()
+    list (APPEND Python3_INVALID_ABI "ON")
+  endif()
+endforeach()
+
+add_test(NAME python3_find_valid_abi
+         COMMAND "${CMAKE_COMMAND}" -DPYTHON_PACKAGE_NAME=Python3
+         -DPython3_FIND_STRATEGY=${Python3_FIND_STRATEGY}
+         "-DPython3_FIND_ABI=${Python3_VALID_ABI}"
+         -P "${CMAKE_CURRENT_LIST_DIR}/../FindPythonScript.cmake")
+add_test(NAME python3_find_invalid_abi
+         COMMAND "${CMAKE_COMMAND}" -DPYTHON_PACKAGE_NAME=Python3
+         -DPYTHON_MUST_NOT_BE_FOUND=ON
+         -DPython3_FIND_STRATEGY=${Python3_FIND_STRATEGY}
+         "-DPython3_FIND_ABI=${Python3_INVALID_ABI}"
          -P "${CMAKE_CURRENT_LIST_DIR}/../FindPythonScript.cmake")