FindPython: Add capability to specify directly artifacts

Fixes: #19492

Help/release/dev/FindPython-specify_artifacts.rst

@@ -0,0 +1,5 @@
+FindPython-specify_artifacts
+----------------------------
+
+* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
+  gain the capability to specify directly artifacts.

Modules/FindPython.cmake

@@ -243,6 +243,44 @@ Hints
     recommended to also include the component ``Interpreter`` to get expected
     result.
 
+Artifacts Specification
+^^^^^^^^^^^^^^^^^^^^^^^
+
+To solve special cases, it is possible to specify directly the artifacts by
+setting the following variables:
+
+``Python_EXECUTABLE``
+  The path to the interpreter.
+
+``Python_COMPILER``
+  The path to the compiler.
+
+``Python_LIBRARY``
+  The path to the library. It will be used to compute the
+  variables ``Python_LIBRARIES``, ``Python_LIBRAY_DIRS`` and
+  ``Python_RUNTIME_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``.
+
+``Python_NumPy_INCLUDE_DIR``
+  The path to the directory of the ``NumPy`` headers. It will be used to
+  compute the variable ``Python_NumPy_INCLUDE_DIRS``.
+
+.. note::
+
+  All paths must be absolute. Any artifact specified with a relative path
+  will be ignored.
+
+.. note::
+
+  When an artifact is specified, all ``HINTS`` will be ignored and no search
+  will be performed for this artifact.
+
+  If more than one artifact is specified, it is the user's responsability to
+  ensure the consistency of the various artifacts.
+
 Commands
 ^^^^^^^^
 
@@ -275,6 +313,14 @@ else()
   set (_Python_REQUIRED_VERSIONS 3 2)
   set (_Python_REQUIRED_VERSION_LAST 2)
 
+  unset (_Python_INPUT_VARS)
+  foreach (_Python_ITEM IN ITEMS Python_EXECUTABLE Python_COMPILER Python_LIBRARY
+                                 Python_INCLUDE_DIR Python_NumPy_INCLUDE_DIR)
+    if (NOT DEFINED ${_Python_ITEM})
+      list (APPEND _Python_INPUT_VARS ${_Python_ITEM})
+    endif()
+  endforeach()
+
   foreach (_Python_REQUIRED_VERSION_MAJOR IN LISTS _Python_REQUIRED_VERSIONS)
     set (Python_FIND_VERSION ${_Python_REQUIRED_VERSION_MAJOR})
     include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake)
@@ -282,6 +328,10 @@ else()
         _Python_REQUIRED_VERSION_MAJOR EQUAL _Python_REQUIRED_VERSION_LAST)
       break()
     endif()
+    # clean-up INPUT variables not set by the user
+    foreach (_Python_ITEM IN LISTS _Python_INPUT_VARS)
+      unset (${_Python_ITEM})
+    endforeach()
     # clean-up some CACHE variables to ensure look-up restart from scratch
     foreach (_Python_ITEM IN LISTS _Python_CACHED_VARS)
       unset (${_Python_ITEM} CACHE)

Modules/FindPython2.cmake

@@ -199,6 +199,44 @@ Hints
     recommended to also include the component ``Interpreter`` to get expected
     result.
 
+Artifacts Specification
+^^^^^^^^^^^^^^^^^^^^^^^
+
+To solve special cases, it is possible to specify directly the artifacts by
+setting the following variables:
+
+``Python2_EXECUTABLE``
+  The path to the interpreter.
+
+``Python2_COMPILER``
+  The path to the compiler.
+
+``Python2_LIBRARY``
+  The path to the library. It will be used to compute the
+  variables ``Python2_LIBRARIES``, ``Python2_LIBRAY_DIRS`` and
+  ``Python2_RUNTIME_LIBRARY_DIRS``.
+
+``Python2_INCLUDE_DIR``
+  The path to the directory of the ``Python`` headers. It will be used to
+  compute the variable ``Python2_INCLUDE_DIRS``.
+
+``Python2_NumPy_INCLUDE_DIR``
+  The path to the directory of the ``NumPy`` headers. It will be used to
+  compute the variable ``Python2_NumPy_INCLUDE_DIRS``.
+
+.. note::
+
+  All paths must be absolute. Any artifact specified with a relative path
+  will be ignored.
+
+.. note::
+
+  When an artifact is specified, all ``HINTS`` will be ignored and no search
+  will be performed for this artifact.
+
+  If more than one artifact is specified, it is the user's responsability to
+  ensure the consistency of the various artifacts.
+
 Commands
 ^^^^^^^^
 

Modules/FindPython3.cmake

@@ -240,6 +240,44 @@ Hints
     recommended to also include the component ``Interpreter`` to get expected
     result.
 
+Artifacts Specification
+^^^^^^^^^^^^^^^^^^^^^^^
+
+To solve special cases, it is possible to specify directly the artifacts by
+setting the following variables:
+
+``Python3_EXECUTABLE``
+  The path to the interpreter.
+
+``Python3_COMPILER``
+  The path to the compiler.
+
+``Python3_LIBRARY``
+  The path to the library. It will be used to compute the
+  variables ``Python3_LIBRARIES``, ``Python3_LIBRAY_DIRS`` and
+  ``Python3_RUNTIME_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``.
+
+``Python3_NumPy_INCLUDE_DIR``
+  The path to the directory of the ``NumPy`` headers. It will be used to
+  compute the variable ``Python3_NumPy_INCLUDE_DIRS``.
+
+.. note::
+
+  All paths must be absolute. Any artifact specified with a relative path
+  will be ignored.
+
+.. note::
+
+  When an artifact is specified, all ``HINTS`` will be ignored and no search
+  will be performed for this artifact.
+
+  If more than one artifact is specified, it is the user's responsability to
+  ensure the consistency of the various artifacts.
+
 Commands
 ^^^^^^^^
 

Tests/FindPython/CMakeLists.txt

@@ -121,6 +121,19 @@ if(CMake_TEST_FindPython)
     --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
     )
 
+  add_test(NAME FindPython.RequiredArtifacts COMMAND
+    ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+    --build-and-test
+    "${CMake_SOURCE_DIR}/Tests/FindPython/RequiredArtifacts"
+    "${CMake_BINARY_DIR}/Tests/FindPython/RequiredArtifacts"
+    ${build_generator_args}
+    --build-project TestRequiredArtifacts
+    --build-options ${build_options} "-Dbuild_generator_args=${build_generator_args}"
+    "-DCMake_SOURCE_DIR=${CMake_SOURCE_DIR}"
+    "-DCMake_BINARY_DIR=${CMake_BINARY_DIR}"
+    --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
+    )
+
 endif()
 
 if(CMake_TEST_FindPython_NumPy)

Tests/FindPython/RequiredArtifacts/CMakeLists.txt

@@ -0,0 +1,110 @@
+cmake_minimum_required(VERSION 3.1)
+
+project(TestRequiredArtifacts LANGUAGES C)
+
+include(CTest)
+
+find_package(Python2 REQUIRED COMPONENTS Interpreter Development)
+if (NOT Python2_FOUND)
+  message (FATAL_ERROR "Fail to found Python 2")
+endif()
+find_package(Python3 REQUIRED COMPONENTS Interpreter Development)
+if (NOT Python3_FOUND)
+  message (FATAL_ERROR "Fail to found Python 3")
+endif()
+
+
+add_test(NAME FindPython.RequiredArtifacts.Interpreter.VALID COMMAND
+  ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+  --build-and-test
+  "${CMake_SOURCE_DIR}/Tests/FindPython/RequiredArtifacts/Check"
+  "${CMake_BINARY_DIR}/Tests/FindPython/RequiredArtifacts/Interpreter.VALID"
+  ${build_generator_args}
+  --build-project TestRequiredArtifacts.Check
+  --build-options -DPYTHON_IS_FOUND=TRUE -DCHECK_INTERPRETER=ON
+                  "-DPython3_EXECUTABLE=${Python3_EXECUTABLE}"
+  --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
+  )
+add_test(NAME FindPython.RequiredArtifacts.Interpreter.INVALID COMMAND
+  ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+  --build-and-test
+  "${CMake_SOURCE_DIR}/Tests/FindPython/RequiredArtifacts/Check"
+  "${CMake_BINARY_DIR}/Tests/FindPython/RequiredArtifacts/Interpreter.INVALID"
+  ${build_generator_args}
+  --build-project TestRequiredArtifacts.Check
+  --build-options -DPYTHON_IS_FOUND=FALSE -DCHECK_INTERPRETER=ON
+                  "-DPython3_EXECUTABLE=${Python3_EXECUTABLE}-bad${CMAKE_EXECUTABLE_SUFFIX}"
+  --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
+  )
+
+add_test(NAME FindPython.RequiredArtifacts.Library.VALID COMMAND
+  ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+  --build-and-test
+  "${CMake_SOURCE_DIR}/Tests/FindPython/RequiredArtifacts/Check"
+  "${CMake_BINARY_DIR}/Tests/FindPython/RequiredArtifacts/Library.VALID"
+  ${build_generator_args}
+  --build-project TestRequiredArtifacts.Check
+  --build-options -DPYTHON_IS_FOUND=TRUE -DCHECK_LIBRARY=ON
+                  "-DPython3_LIBRARY=${Python3_LIBRARY_RELEASE}"
+  --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
+  )
+add_test(NAME FindPython.RequiredArtifacts.Library.INVALID COMMAND
+  ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+  --build-and-test
+  "${CMake_SOURCE_DIR}/Tests/FindPython/RequiredArtifacts/Check"
+  "${CMake_BINARY_DIR}/Tests/FindPython/RequiredArtifacts/Library.INVALID"
+  ${build_generator_args}
+  --build-project TestRequiredArtifacts.Check
+  --build-options -DPYTHON_IS_FOUND=FALSE -DCHECK_LIBRARY=ON
+                  "-DPython3_LIBRARY=${Python2_LIBRARY_RELEASE}"
+  --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
+  )
+
+add_test(NAME FindPython.RequiredArtifacts.Include.VALID COMMAND
+  ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+  --build-and-test
+  "${CMake_SOURCE_DIR}/Tests/FindPython/RequiredArtifacts/Check"
+  "${CMake_BINARY_DIR}/Tests/FindPython/RequiredArtifacts/Include.VALID"
+  ${build_generator_args}
+  --build-project TestRequiredArtifacts.Check
+  --build-options -DPYTHON_IS_FOUND=TRUE -DCHECK_INCLUDE=ON
+                  "-DPython3_INCLUDE_DIR=${Python3_INCLUDE_DIRS}"
+  --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
+  )
+add_test(NAME FindPython.RequiredArtifacts.Include.INVALID COMMAND
+  ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+  --build-and-test
+  "${CMake_SOURCE_DIR}/Tests/FindPython/RequiredArtifacts/Check"
+  "${CMake_BINARY_DIR}/Tests/FindPython/RequiredArtifacts/Include.INVALID"
+  ${build_generator_args}
+  --build-project TestRequiredArtifacts.Check
+  --build-options -DPYTHON_IS_FOUND=FALSE -DCHECK_INCLUDE=ON
+                  "-DPython3_INCLUDE_DIR=${Python2_INCLUDE_DIRS}"
+  --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
+  )
+
+add_test(NAME FindPython.RequiredArtifacts.Interpreter-Library.INVALID COMMAND
+  ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+  --build-and-test
+  "${CMake_SOURCE_DIR}/Tests/FindPython/RequiredArtifacts/Check"
+  "${CMake_BINARY_DIR}/Tests/FindPython/RequiredArtifacts/Interpreter-Library.INVALID"
+  ${build_generator_args}
+  --build-project TestRequiredArtifacts.Check
+  --build-options -DPYTHON_IS_FOUND=FALSE -DCHECK_INTERPRETER=ON -DCHECK_LIBRARY=ON
+                  "-DPython3_EXECUTABLE=${Python3_EXECUTABLE}"
+                  "-DPython3_LIBRARY=${Python2_LIBRARY_RELEASE}"
+  --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
+  )
+
+add_test(NAME FindPython.RequiredArtifacts.Library-Include.INVALID COMMAND
+  ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+  --build-and-test
+  "${CMake_SOURCE_DIR}/Tests/FindPython/RequiredArtifacts/Check"
+  "${CMake_BINARY_DIR}/Tests/FindPython/RequiredArtifacts/Library-Include.INVALID"
+  ${build_generator_args}
+  --build-project TestRequiredArtifacts.Check
+  --build-options -DPYTHON_IS_FOUND=FALSE -DCHECK_LIBRARY=ON -DCHECK_INCLUDE=ON
+                  "-DPython3_LIBRARY=${Python3_LIBRARY_RELEASE}"
+                  "-DPython3_INCLUDE_DIR=${Python2_INCLUDE_DIRS}"
+  --test-command ${CMAKE_CTEST_COMMAND} -V -C $<CONFIGURATION>
+  )

Tests/FindPython/RequiredArtifacts/Check/CMakeLists.txt

@@ -0,0 +1,41 @@
+cmake_minimum_required(VERSION 3.1)
+
+project(TestRequiredArtifacts.Check LANGUAGES C)
+
+set (components)
+if (CHECK_INTERPRETER)
+  set (required_interpreter "${Python3_EXECUTABLE}")
+  list (APPEND components Interpreter)
+endif()
+if (CHECK_LIBRARY OR CHECK_INCLUDE)
+  list (APPEND components Development)
+  if (CHECK_LIBRARY)
+    set (required_library "${Python3_LIBRARY}")
+  endif()
+  if (CHECK_INCLUDE)
+    set (required_include "${Python3_INCLUDE_DIR}")
+  endif()
+endif()
+
+find_package (Python3 COMPONENTS ${components})
+
+
+if (PYTHON_IS_FOUND AND NOT Python3_FOUND)
+  message (FATAL_ERROR "Python3 unexpectedly not found")
+endif()
+if (NOT PYTHON_IS_FOUND AND Python3_FOUND)
+  message (FATAL_ERROR "Python3 unexpectedly found")
+endif()
+
+
+if (CHECK_INTERPRETER AND NOT Python3_EXECUTABLE STREQUAL required_interpreter)
+  message (FATAL_ERROR "Fail to use input variable Python3_EXECUTABLE")
+endif()
+
+if (CHECK_LIBRARY AND NOT Python3_LIBRARY_RELEASE STREQUAL required_library)
+  message (FATAL_ERROR "Fail to use input variable Python3_LIBRARY")
+endif()
+
+if (CHECK_INCLUDE AND NOT Python3_INCLUDE_DIRS STREQUAL required_include)
+  message (FATAL_ERROR "Fail to use input variable Python3_INCLUDE_DIR")
+endif()