FindPython*: Add capability to control virtual env handling.

Fixes: #19097

4 files changed, 111 insertions, 20 deletions

diff --git a/Modules/FindPython.cmake b/Modules/FindPython.cmake
index 1c134e278b..c5074e8b3d 100644
--- a/Modules/FindPython.cmake
+++ b/Modules/FindPython.cmake
@@ -145,18 +145,30 @@ Hints
   * ``NEVER``: Never try to use registry.
 
 ``CMAKE_FIND_FRAMEWORK``
-  On OS X the :variable:`CMAKE_FIND_FRAMEWORK` variable determine the order of
+  On macOS the :variable:`CMAKE_FIND_FRAMEWORK` variable determine the order of
   preference between Apple-style and unix-style package components.
 
   .. note::
 
     Value ``ONLY`` is not supported so ``FIRST`` will be used instead.
 
-.. note::
+``Python_FIND_VIRTUALENV``
+  This variable defines the handling of virtual environments. It is meaningfull
+  only when a virtual environment is active (i.e. the ``activate`` script has
+  been evaluated). In this case, it takes precedence over
+  ``Python_FIND_REGISTRY`` and ``CMAKE_FIND_FRAMEWORK`` variables.
+  The ``Python_FIND_VIRTUALENV`` variable can be set to empty or one of the
+  following:
 
-  If a Python virtual environment is configured, set variable
-  ``Python_FIND_REGISTRY`` (Windows) or ``CMAKE_FIND_FRAMEWORK`` (macOS) with
-  value ``LAST`` or ``NEVER`` to select it preferably.
+  * ``FIRST``: The virtual environment is used before any other standard
+    paths to look-up for the interpreter. This is the default.
+  * ``ONLY``: Only the virtual environment is used to look-up for the
+    interpreter.
+  * ``STANDARD``: The virtual environment is not used to look-up for the
+    interpreter. In this case, variable ``Python_FIND_REGISTRY`` (Windows)
+    or ``CMAKE_FIND_FRAMEWORK`` (macOS) can be set with value ``LAST`` or
+    ``NEVER`` to select preferably the interpreter from the virtual
+    environment.
 
 Commands
 ^^^^^^^^
diff --git a/Modules/FindPython/Support.cmake b/Modules/FindPython/Support.cmake
index 1236bf8f86..0868989df4 100644
--- a/Modules/FindPython/Support.cmake
+++ b/Modules/FindPython/Support.cmake
@@ -298,6 +298,22 @@ else()
   set (_${_PYTHON_PREFIX}_FIND_REGISTRY "FIRST")
 endif()
 
+# virtual environments handling
+if (DEFINED ENV{VIRTUAL_ENV})
+  if (DEFINED ${_PYTHON_PREFIX}_FIND_VIRTUALENV)
+    if (NOT ${_PYTHON_PREFIX}_FIND_VIRTUALENV MATCHES "^(FIRST|ONLY|STANDARD)$")
+      message (AUTHOR_WARNING "Find${_PYTHON_PREFIX}: ${${_PYTHON_PREFIX}_FIND_VIRTUALENV}: invalid value for '${_PYTHON_PREFIX}_FIND_VIRTUALENV'. 'FIRST', 'ONLY' or 'IGNORE' expected.")
+      set (_${_PYTHON_PREFIX}_FIND_VIRTUALENV "FIRST")
+    else()
+      set (_${_PYTHON_PREFIX}_FIND_VIRTUALENV ${${_PYTHON_PREFIX}_FIND_VIRTUALENV})
+    endif()
+  else()
+    set (_${_PYTHON_PREFIX}_FIND_VIRTUALENV FIRST)
+  endif()
+else()
+  set (_${_PYTHON_PREFIX}_FIND_VIRTUALENV STANDARD)
+endif()
+
 
 unset (_${_PYTHON_PREFIX}_REQUIRED_VARS)
 unset (_${_PYTHON_PREFIX}_CACHED_VARS)
@@ -318,6 +334,30 @@ if ("Interpreter" IN_LIST ${_PYTHON_PREFIX}_FIND_COMPONENTS)
 
     _python_get_frameworks (_${_PYTHON_PREFIX}_FRAMEWORK_PATHS ${_${_PYTHON_PREFIX}_VERSION})
 
+    # Virtual environments handling
+    if (_${_PYTHON_PREFIX}_FIND_VIRTUALENV MATCHES "^(FIRST|ONLY)$")
+      find_program (${_PYTHON_PREFIX}_EXECUTABLE
+                    NAMES python${_${_PYTHON_PREFIX}_VERSION}
+                          python${_${_PYTHON_PREFIX}_REQUIRED_VERSION_MAJOR}
+                          python
+                    NAMES_PER_DIR
+                    HINTS ${_${_PYTHON_PREFIX}_HINTS}
+                    PATHS ENV VIRTUAL_ENV
+                    PATH_SUFFIXES bin Scripts
+                    NO_CMAKE_PATH
+                    NO_CMAKE_ENVIRONMENT_PATH
+                    NO_SYSTEM_ENVIRONMENT_PATH
+                    NO_CMAKE_SYSTEM_PATH)
+
+      _python_validate_interpreter (${_${_PYTHON_PREFIX}_VERSION})
+      if (${_PYTHON_PREFIX}_EXECUTABLE)
+        break()
+      endif()
+      if (_${_PYTHON_PREFIX}_FIND_VIRTUALENV STREQUAL "ONLY")
+        continue()
+      endif()
+    endif()
+
     # Apple frameworks handling
     if (APPLE AND _${_PYTHON_PREFIX}_FIND_FRAMEWORK STREQUAL "FIRST")
       find_program (${_PYTHON_PREFIX}_EXECUTABLE
@@ -423,7 +463,8 @@ if ("Interpreter" IN_LIST ${_PYTHON_PREFIX}_FIND_COMPONENTS)
     endif()
   endforeach()
 
-  if (NOT ${_PYTHON_PREFIX}_EXECUTABLE)
+  if (NOT ${_PYTHON_PREFIX}_EXECUTABLE AND
+      NOT _${_PYTHON_PREFIX}_FIND_VIRTUALENV STREQUAL "ONLY")
     # No specific version found. Retry with generic names
     # try using HINTS
     find_program (${_PYTHON_PREFIX}_EXECUTABLE
@@ -685,18 +726,32 @@ if ("Development" IN_LIST ${_PYTHON_PREFIX}_FIND_COMPONENTS
   # if python interpreter is found, use its location and version to ensure consistency
   # between interpreter and development environment
   unset (_${_PYTHON_PREFIX}_PREFIX)
+  unset (_${_PYTHON_PREFIX}_EXEC_PREFIX)
+  unset (_${_PYTHON_PREFIX}_BASE_EXEC_PREFIX)
   if (${_PYTHON_PREFIX}_Interpreter_FOUND)
     execute_process (COMMAND "${${_PYTHON_PREFIX}_EXECUTABLE}" -c
-                             "import sys; from distutils import sysconfig; sys.stdout.write(sysconfig.PREFIX)"
+                             "import sys; from distutils import sysconfig; sys.stdout.write(sysconfig.EXEC_PREFIX)"
                      RESULT_VARIABLE _${_PYTHON_PREFIX}_RESULT
-                     OUTPUT_VARIABLE _${_PYTHON_PREFIX}_PREFIX
+                     OUTPUT_VARIABLE _${_PYTHON_PREFIX}_EXEC_PREFIX
                      ERROR_QUIET
                      OUTPUT_STRIP_TRAILING_WHITESPACE)
     if (_${_PYTHON_PREFIX}_RESULT)
-      unset (_${_PYTHON_PREFIX}_PREFIX)
+      unset (_${_PYTHON_PREFIX}_EXEC_PREFIX)
+    endif()
+
+    if (NOT ${_PYTHON_PREFIX}_FIND_VIRTUALENV STREQUAL "STANDARD")
+      execute_process (COMMAND "${${_PYTHON_PREFIX}_EXECUTABLE}" -c
+                               "import sys; from distutils import sysconfig; sys.stdout.write(sysconfig.BASE_EXEC_PREFIX)"
+                       RESULT_VARIABLE _${_PYTHON_PREFIX}_RESULT
+                       OUTPUT_VARIABLE _${_PYTHON_PREFIX}_BASE_EXEC_PREFIX
+                       ERROR_QUIET
+                       OUTPUT_STRIP_TRAILING_WHITESPACE)
+      if (_${_PYTHON_PREFIX}_RESULT)
+        unset (_${_PYTHON_PREFIX}_BASE_EXEC_PREFIX)
+      endif()
     endif()
   endif()
-  set (_${_PYTHON_PREFIX}_HINTS "${_${_PYTHON_PREFIX}_PREFIX}" "${${_PYTHON_PREFIX}_ROOT_DIR}" ENV ${_PYTHON_PREFIX}_ROOT_DIR)
+  set (_${_PYTHON_PREFIX}_HINTS "${_${_PYTHON_PREFIX}_EXEC_PREFIX}" "${_${_PYTHON_PREFIX}_BASE_EXEC_PREFIX}" "${${_PYTHON_PREFIX}_ROOT_DIR}" ENV ${_PYTHON_PREFIX}_ROOT_DIR)
 
   foreach (_${_PYTHON_PREFIX}_VERSION IN LISTS _${_PYTHON_PREFIX}_FIND_VERSIONS)
     string (REPLACE "." "" _${_PYTHON_PREFIX}_VERSION_NO_DOTS ${_${_PYTHON_PREFIX}_VERSION})
diff --git a/Modules/FindPython2.cmake b/Modules/FindPython2.cmake
index b9c0b6b739..a2be84fee5 100644
--- a/Modules/FindPython2.cmake
+++ b/Modules/FindPython2.cmake
@@ -153,11 +153,23 @@ Hints
 
     Value ``ONLY`` is not supported so ``FIRST`` will be used instead.
 
-.. note::
+``Python2_FIND_VIRTUALENV``
+  This variable defines the handling of virtual environments. It is meaningfull
+  only when a virtual environment is active (i.e. the ``activate`` script has
+  been evaluated). In this case, it takes precedence over
+  ``Python2_FIND_REGISTRY`` and ``CMAKE_FIND_FRAMEWORK`` variables.
+  The ``Python2_FIND_VIRTUALENV`` variable can be set to empty or one of the
+  following:
 
-  If a Python virtual environment is configured, set variable
-  ``Python_FIND_REGISTRY`` (Windows) or ``CMAKE_FIND_FRAMEWORK`` (macOS) with
-  value ``LAST`` or ``NEVER`` to select it preferably.
+  * ``FIRST``: The virtual environment is used before any other standard
+    paths to look-up for the interpreter. This is the default.
+  * ``ONLY``: Only the virtual environment is used to look-up for the
+    interpreter.
+  * ``STANDARD``: The virtual environment is not used to look-up for the
+    interpreter. In this case, variable ``Python2_FIND_REGISTRY`` (Windows)
+    or ``CMAKE_FIND_FRAMEWORK`` (macOS) can be set with value ``LAST`` or
+    ``NEVER`` to select preferably the interpreter from the virtual
+    environment.
 
 Commands
 ^^^^^^^^
diff --git a/Modules/FindPython3.cmake b/Modules/FindPython3.cmake
index c2f3384697..3409554580 100644
--- a/Modules/FindPython3.cmake
+++ b/Modules/FindPython3.cmake
@@ -137,7 +137,7 @@ Hints
 ``Python3_FIND_REGISTRY``
   On Windows the ``Python3_FIND_REGISTRY`` variable determine the order
   of preference between registry and environment variables.
-  the ``Python3_FIND_REGISTRY`` variable can be set to empty or one of the
+  The ``Python3_FIND_REGISTRY`` variable can be set to empty or one of the
   following:
 
   * ``FIRST``: Try to use registry before environment variables.
@@ -146,18 +146,30 @@ Hints
   * ``NEVER``: Never try to use registry.
 
 ``CMAKE_FIND_FRAMEWORK``
-  On OS X the :variable:`CMAKE_FIND_FRAMEWORK` variable determine the order of
+  On macOS the :variable:`CMAKE_FIND_FRAMEWORK` variable determine the order of
   preference between Apple-style and unix-style package components.
 
   .. note::
 
     Value ``ONLY`` is not supported so ``FIRST`` will be used instead.
 
-.. note::
+``Python3_FIND_VIRTUALENV``
+  This variable defines the handling of virtual environments. It is meaningfull
+  only when a virtual environment is active (i.e. the ``activate`` script has
+  been evaluated). In this case, it takes precedence over
+  ``Python3_FIND_REGISTRY`` and ``CMAKE_FIND_FRAMEWORK`` variables.
+  The ``Python3_FIND_VIRTUALENV`` variable can be set to empty or one of the
+  following:
 
-  If a Python virtual environment is configured, set variable
-  ``Python_FIND_REGISTRY`` (Windows) or ``CMAKE_FIND_FRAMEWORK`` (macOS) with
-  value ``LAST`` or ``NEVER`` to select it preferably.
+  * ``FIRST``: The virtual environment is used before any other standard
+    paths to look-up for the interpreter. This is the default.
+  * ``ONLY``: Only the virtual environment is used to look-up for the
+    interpreter.
+  * ``STANDARD``: The virtual environment is not used to look-up for the
+    interpreter. In this case, variable ``Python3_FIND_REGISTRY`` (Windows)
+    or ``CMAKE_FIND_FRAMEWORK`` (macOS) can be set with value ``LAST`` or
+    ``NEVER`` to select preferably the interpreter from the virtual
+    environment.
 
 Commands
 ^^^^^^^^