Set hints to find the python version we actually want. (#508)

The comment in the commit explains the reasoning behind it.

Signed-off-by: Chris Lalancette <[email protected]>

ament_cmake_core/cmake/core/python.cmake

@@ -18,5 +18,21 @@
 #   find_package(Python3 3.8 REQUIRED)
 #   find_package(ament_cmake REQUIRED)
 if(NOT TARGET Python3::Interpreter)
+  # By default, without the settings below, find_package(Python3) will attempt
+  # to find the newest python version it can, and additionally will find the
+  # most specific version.  For instance, on a system that has
+  # /usr/bin/python3.10, /usr/bin/python3.11, and /usr/bin/python3, it will find
+  # /usr/bin/python3.11, even if /usr/bin/python3 points to /usr/bin/python3.10.
+  # The behavior we want is to prefer the "system" installed version unless the
+  # user specifically tells us othewise through the Python3_EXECUTABLE hint.
+  # Setting CMP0094 to NEW means that the search will stop after the first
+  # python version is found.  Setting Python3_FIND_UNVERSIONED_NAMES means that
+  # the search will prefer /usr/bin/python3 over /usr/bin/python3.11.  And that
+  # latter functionality is only available in CMake 3.20 or later, so we need
+  # at least that version.
+  cmake_minimum_required(VERSION 3.20)
+  cmake_policy(SET CMP0094 NEW)
+  set(Python3_FIND_UNVERSIONED_NAMES FIRST)
+
   find_package(Python3 REQUIRED COMPONENTS Interpreter)
 endif()