fix: support CMake 3.27, drop 3.4 (#4719)

* fix: support CMake 3.27, drop 3.4

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* Update upgrade.rst

* Update upgrade.rst

* Update upgrade.rst

---------

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

16 files changed, 75 insertions, 49 deletions

diff --git a/.github/workflows/configure.yml b/.github/workflows/configure.yml
index 82a49390..ec7cd612 100644
--- a/.github/workflows/configure.yml
+++ b/.github/workflows/configure.yml
@@ -26,20 +26,24 @@ jobs:
       matrix:
         runs-on: [ubuntu-20.04, macos-latest, windows-latest]
         arch: [x64]
-        cmake: ["3.23"]
+        cmake: ["3.26"]
 
         include:
         - runs-on: ubuntu-20.04
           arch: x64
-          cmake: 3.4
+          cmake: "3.5"
+
+        - runs-on: ubuntu-20.04
+          arch: x64
+          cmake: "3.27"
 
         - runs-on: macos-latest
           arch: x64
-          cmake: 3.7
+          cmake: "3.7"
 
         - runs-on: windows-2019
           arch: x64 # x86 compilers seem to be missing on 2019 image
-          cmake: 3.18
+          cmake: "3.18"
 
     name: 🐍 3.7 • CMake ${{ matrix.cmake }} • ${{ matrix.runs-on }}
     runs-on: ${{ matrix.runs-on }}
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 0ad74db2..87ec1034 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -5,15 +5,15 @@
 # All rights reserved. Use of this source code is governed by a
 # BSD-style license that can be found in the LICENSE file.
 
-cmake_minimum_required(VERSION 3.4)
+cmake_minimum_required(VERSION 3.5)
 
-# The `cmake_minimum_required(VERSION 3.4...3.22)` syntax does not work with
+# The `cmake_minimum_required(VERSION 3.5...3.26)` syntax does not work with
 # some versions of VS that have a patched CMake 3.11. This forces us to emulate
 # the behavior using the following workaround:
-if(${CMAKE_VERSION} VERSION_LESS 3.22)
+if(${CMAKE_VERSION} VERSION_LESS 3.26)
   cmake_policy(VERSION ${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION})
 else()
-  cmake_policy(VERSION 3.22)
+  cmake_policy(VERSION 3.26)
 endif()
 
 # Avoid infinite recursion if tests include this as a subdirectory
diff --git a/docs/advanced/embedding.rst b/docs/advanced/embedding.rst
index dd980d48..e6a1686f 100644
--- a/docs/advanced/embedding.rst
+++ b/docs/advanced/embedding.rst
@@ -18,7 +18,7 @@ information, see :doc:`/compiling`.
 
 .. code-block:: cmake
 
-    cmake_minimum_required(VERSION 3.4)
+    cmake_minimum_required(VERSION 3.5...3.26)
     project(example)
 
     find_package(pybind11 REQUIRED)  # or `add_subdirectory(pybind11)`
diff --git a/docs/compiling.rst b/docs/compiling.rst
index 2b543be0..1fd098be 100644
--- a/docs/compiling.rst
+++ b/docs/compiling.rst
@@ -241,7 +241,7 @@ extension module can be created with just a few lines of code:
 
 .. code-block:: cmake
 
-    cmake_minimum_required(VERSION 3.4...3.18)
+    cmake_minimum_required(VERSION 3.5...3.26)
     project(example LANGUAGES CXX)
 
     add_subdirectory(pybind11)
@@ -261,6 +261,9 @@ PyPI integration, can be found in the [cmake_example]_  repository.
 .. versionchanged:: 2.6
    CMake 3.4+ is required.
 
+.. versionchanged:: 2.11
+   CMake 3.5+ is required.
+
 Further information can be found at :doc:`cmake/index`.
 
 pybind11_add_module
@@ -495,7 +498,7 @@ You can use these targets to build complex applications. For example, the
 
 .. code-block:: cmake
 
-    cmake_minimum_required(VERSION 3.4)
+    cmake_minimum_required(VERSION 3.5...3.26)
     project(example LANGUAGES CXX)
 
     find_package(pybind11 REQUIRED)  # or add_subdirectory(pybind11)
@@ -553,7 +556,7 @@ information about usage in C++, see :doc:`/advanced/embedding`.
 
 .. code-block:: cmake
 
-    cmake_minimum_required(VERSION 3.4...3.18)
+    cmake_minimum_required(VERSION 3.5...3.26)
     project(example LANGUAGES CXX)
 
     find_package(pybind11 REQUIRED)  # or add_subdirectory(pybind11)
diff --git a/docs/faq.rst b/docs/faq.rst
index 28498e7d..1eb00efa 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -284,7 +284,8 @@ There are three possible solutions:
    COMPONENTS Interpreter Development)`` on modern CMake (3.12+, 3.15+ better,
    3.18.2+ best). Pybind11 in these cases uses the new CMake FindPython instead
    of the old, deprecated search tools, and these modules are much better at
-   finding the correct Python.
+   finding the correct Python. If FindPythonLibs/Interp are not available
+   (CMake 3.27+), then this will be ignored and FindPython will be used.
 3. Set ``PYBIND11_NOPYTHON`` to ``TRUE``. Pybind11 will not search for Python.
    However, you will have to use the target-based system, and do more setup
    yourself, because it does not know about or include things that depend on
diff --git a/docs/upgrade.rst b/docs/upgrade.rst
index 6a9db2d0..b13d21f5 100644
--- a/docs/upgrade.rst
+++ b/docs/upgrade.rst
@@ -8,6 +8,20 @@ to a new version. But it goes into more detail. This includes things like
 deprecated APIs and their replacements, build system changes, general code
 modernization and other useful information.
 
+.. _upgrade-guide-2.11:
+
+v2.11
+=====
+
+* The minimum version of CMake is now 3.5. A future version will likely move to
+  requiring something like CMake 3.15. Note that CMake 3.27 is removing the
+  long-deprecated support for ``FindPythonInterp`` if you set 3.27 as the
+  minimum or maximum supported version. To prepare for that future, CMake 3.15+
+  using ``FindPython`` or setting ``PYBIND11_FINDPYTHON`` is highly recommended,
+  otherwise pybind11 will automatically switch to using ``FindPython`` if
+  ``FindPythonInterp`` is not available.
+
+
 .. _upgrade-guide-2.9:
 
 v2.9
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 5574663b..80ee9c1f 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -5,20 +5,17 @@
 # All rights reserved. Use of this source code is governed by a
 # BSD-style license that can be found in the LICENSE file.
 
-cmake_minimum_required(VERSION 3.4)
+cmake_minimum_required(VERSION 3.5)
 
-# The `cmake_minimum_required(VERSION 3.4...3.18)` syntax does not work with
+# The `cmake_minimum_required(VERSION 3.5...3.26)` syntax does not work with
 # some versions of VS that have a patched CMake 3.11. This forces us to emulate
 # the behavior using the following workaround:
-if(${CMAKE_VERSION} VERSION_LESS 3.21)
+if(${CMAKE_VERSION} VERSION_LESS 3.26)
   cmake_policy(VERSION ${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION})
 else()
-  cmake_policy(VERSION 3.21)
+  cmake_policy(VERSION 3.26)
 endif()
 
-# Only needed for CMake < 3.5 support
-include(CMakeParseArguments)
-
 # Filter out items; print an optional message if any items filtered. This ignores extensions.
 #
 # Usage:
diff --git a/tests/test_cmake_build/CMakeLists.txt b/tests/test_cmake_build/CMakeLists.txt
index 8bfaa386..e5aa975c 100644
--- a/tests/test_cmake_build/CMakeLists.txt
+++ b/tests/test_cmake_build/CMakeLists.txt
@@ -1,6 +1,3 @@
-# Built-in in CMake 3.5+
-include(CMakeParseArguments)
-
 add_custom_target(test_cmake_build)
 
 function(pybind11_add_build_test name)
diff --git a/tests/test_cmake_build/installed_embed/CMakeLists.txt b/tests/test_cmake_build/installed_embed/CMakeLists.txt
index f7d69399..d9dcb45e 100644
--- a/tests/test_cmake_build/installed_embed/CMakeLists.txt
+++ b/tests/test_cmake_build/installed_embed/CMakeLists.txt
@@ -1,12 +1,12 @@
-cmake_minimum_required(VERSION 3.4)
+cmake_minimum_required(VERSION 3.5)
 
-# The `cmake_minimum_required(VERSION 3.4...3.18)` syntax does not work with
+# The `cmake_minimum_required(VERSION 3.5...3.26)` syntax does not work with
 # some versions of VS that have a patched CMake 3.11. This forces us to emulate
 # the behavior using the following workaround:
-if(${CMAKE_VERSION} VERSION_LESS 3.18)
+if(${CMAKE_VERSION} VERSION_LESS 3.26)
   cmake_policy(VERSION ${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION})
 else()
-  cmake_policy(VERSION 3.18)
+  cmake_policy(VERSION 3.26)
 endif()
 
 project(test_installed_embed CXX)
diff --git a/tests/test_cmake_build/installed_function/CMakeLists.txt b/tests/test_cmake_build/installed_function/CMakeLists.txt
index d7ca4db5..2f4f6427 100644
--- a/tests/test_cmake_build/installed_function/CMakeLists.txt
+++ b/tests/test_cmake_build/installed_function/CMakeLists.txt
@@ -1,13 +1,13 @@
-cmake_minimum_required(VERSION 3.4)
+cmake_minimum_required(VERSION 3.5)
 project(test_installed_module CXX)
 
-# The `cmake_minimum_required(VERSION 3.4...3.18)` syntax does not work with
+# The `cmake_minimum_required(VERSION 3.5...3.26)` syntax does not work with
 # some versions of VS that have a patched CMake 3.11. This forces us to emulate
 # the behavior using the following workaround:
-if(${CMAKE_VERSION} VERSION_LESS 3.18)
+if(${CMAKE_VERSION} VERSION_LESS 3.26)
   cmake_policy(VERSION ${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION})
 else()
-  cmake_policy(VERSION 3.18)
+  cmake_policy(VERSION 3.26)
 endif()
 
 project(test_installed_function CXX)
diff --git a/tests/test_cmake_build/installed_target/CMakeLists.txt b/tests/test_cmake_build/installed_target/CMakeLists.txt
index bc5e101f..a981e236 100644
--- a/tests/test_cmake_build/installed_target/CMakeLists.txt
+++ b/tests/test_cmake_build/installed_target/CMakeLists.txt
@@ -1,12 +1,12 @@
-cmake_minimum_required(VERSION 3.4)
+cmake_minimum_required(VERSION 3.5)
 
-# The `cmake_minimum_required(VERSION 3.4...3.18)` syntax does not work with
+# The `cmake_minimum_required(VERSION 3.5...3.26)` syntax does not work with
 # some versions of VS that have a patched CMake 3.11. This forces us to emulate
 # the behavior using the following workaround:
-if(${CMAKE_VERSION} VERSION_LESS 3.18)
+if(${CMAKE_VERSION} VERSION_LESS 3.26)
   cmake_policy(VERSION ${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION})
 else()
-  cmake_policy(VERSION 3.18)
+  cmake_policy(VERSION 3.26)
 endif()
 
 project(test_installed_target CXX)
diff --git a/tests/test_cmake_build/subdirectory_embed/CMakeLists.txt b/tests/test_cmake_build/subdirectory_embed/CMakeLists.txt
index 58cdd7cf..f286746b 100644
--- a/tests/test_cmake_build/subdirectory_embed/CMakeLists.txt
+++ b/tests/test_cmake_build/subdirectory_embed/CMakeLists.txt
@@ -1,12 +1,12 @@
-cmake_minimum_required(VERSION 3.4)
+cmake_minimum_required(VERSION 3.5)
 
-# The `cmake_minimum_required(VERSION 3.4...3.18)` syntax does not work with
+# The `cmake_minimum_required(VERSION 3.5...3.26)` syntax does not work with
 # some versions of VS that have a patched CMake 3.11. This forces us to emulate
 # the behavior using the following workaround:
-if(${CMAKE_VERSION} VERSION_LESS 3.18)
+if(${CMAKE_VERSION} VERSION_LESS 3.26)
   cmake_policy(VERSION ${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION})
 else()
-  cmake_policy(VERSION 3.18)
+  cmake_policy(VERSION 3.26)
 endif()
 
 project(test_subdirectory_embed CXX)
diff --git a/tests/test_cmake_build/subdirectory_function/CMakeLists.txt b/tests/test_cmake_build/subdirectory_function/CMakeLists.txt
index 01557c43..275a75c0 100644
--- a/tests/test_cmake_build/subdirectory_function/CMakeLists.txt
+++ b/tests/test_cmake_build/subdirectory_function/CMakeLists.txt
@@ -1,12 +1,12 @@
-cmake_minimum_required(VERSION 3.4)
+cmake_minimum_required(VERSION 3.5)
 
-# The `cmake_minimum_required(VERSION 3.4...3.18)` syntax does not work with
+# The `cmake_minimum_required(VERSION 3.5...3.26)` syntax does not work with
 # some versions of VS that have a patched CMake 3.11. This forces us to emulate
 # the behavior using the following workaround:
-if(${CMAKE_VERSION} VERSION_LESS 3.18)
+if(${CMAKE_VERSION} VERSION_LESS 3.26)
   cmake_policy(VERSION ${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION})
 else()
-  cmake_policy(VERSION 3.18)
+  cmake_policy(VERSION 3.26)
 endif()
 
 project(test_subdirectory_function CXX)
diff --git a/tests/test_cmake_build/subdirectory_target/CMakeLists.txt b/tests/test_cmake_build/subdirectory_target/CMakeLists.txt
index ba82fdee..37bb2c56 100644
--- a/tests/test_cmake_build/subdirectory_target/CMakeLists.txt
+++ b/tests/test_cmake_build/subdirectory_target/CMakeLists.txt
@@ -1,12 +1,12 @@
-cmake_minimum_required(VERSION 3.4)
+cmake_minimum_required(VERSION 3.5)
 
-# The `cmake_minimum_required(VERSION 3.4...3.18)` syntax does not work with
+# The `cmake_minimum_required(VERSION 3.5...3.26)` syntax does not work with
 # some versions of VS that have a patched CMake 3.11. This forces us to emulate
 # the behavior using the following workaround:
-if(${CMAKE_VERSION} VERSION_LESS 3.18)
+if(${CMAKE_VERSION} VERSION_LESS 3.26)
   cmake_policy(VERSION ${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION})
 else()
-  cmake_policy(VERSION 3.18)
+  cmake_policy(VERSION 3.26)
 endif()
 
 project(test_subdirectory_target CXX)
diff --git a/tools/pybind11Common.cmake b/tools/pybind11Common.cmake
index e4ff1e40..308d1b70 100644
--- a/tools/pybind11Common.cmake
+++ b/tools/pybind11Common.cmake
@@ -163,11 +163,19 @@ endif()
 
 # --------------------- Python specifics -------------------------
 
+# CMake 3.27 removes the classic FindPythonInterp if CMP0148 is NEW
+if(CMAKE_VERSION VERSION_LESS "3.27")
+  set(_pybind11_missing_old_python "OLD")
+else()
+  cmake_policy(GET CMP0148 _pybind11_missing_old_python)
+endif()
+
 # Check to see which Python mode we are in, new, old, or no python
 if(PYBIND11_NOPYTHON)
   set(_pybind11_nopython ON)
 elseif(
-  PYBIND11_FINDPYTHON
+  _pybind11_missing_old_python STREQUAL "NEW"
+  OR PYBIND11_FINDPYTHON
   OR Python_FOUND
   OR Python2_FOUND
   OR Python3_FOUND)
diff --git a/tools/pybind11Config.cmake.in b/tools/pybind11Config.cmake.in
index 9383e8c6..5734f437 100644
--- a/tools/pybind11Config.cmake.in
+++ b/tools/pybind11Config.cmake.in
@@ -63,7 +63,9 @@ Modes
 
 There are two modes provided; classic, which is built on the old Python
 discovery packages in CMake, or the new FindPython mode, which uses FindPython
-from 3.12+ forward (3.15+ _highly_ recommended).
+from 3.12+ forward (3.15+ _highly_ recommended). If you set the minimum or
+maximum version of CMake to 3.27+, then FindPython is the default (since
+FindPythonInterp/FindPythonLibs has been removed via policy `CMP0148`).
 
 New FindPython mode
 ^^^^^^^^^^^^^^^^^^^