cmake: Improve compatibility with Python version managers #31421

1. 
   hebasto commented at 5:11 pm on December 4, 2024: member

   This PR resolves the issue highlighted in #31411:

   Here’s another case where CMake just picks some other Python…

   The fix leverages two hints for the CMake FindPython3 module:

   1. Python3_FIND_FRAMEWORK is set to LAST. This ensures that Unix-style package components are preferred over frameworks on macOS. As a side effect, the FindPython3 module reports a shim or symlink (e.g., from pyenv) rather than the underlying framework’s binary. The module’s output aligns with the result of the which command.
   2. Python3_FIND_UNVERSIONED_NAMES is set to FIRST. This supports scenarios where tools like pyenv—which use shims—have multiple Python versions installed.

   Here are examples of output on my macOS 15.1.1 (Intel) with installed Homebrew’s Python 3.13.0:

   • without any Python version manager:

   0% which -a python3                
   1/usr/local/bin/python3
   2/usr/bin/python3
   3% cmake -B build
   4<snip>
   5-- Found Python3: /usr/local/bin/python3 (found suitable version "3.13.0", minimum required is "3.10") found components: Interpreter
   6<snip>
   

   • using pyenv:

    0% pyenv versions       
    1  system
    2* 3.10.14 (set by /Users/hebasto/dev/bitcoin/.python-version)
    3  3.12.8
    4  3.13.1
    5% which -a python3
    6/Users/hebasto/.pyenv/shims/python3
    7/usr/local/bin/python3
    8/usr/bin/python3
    9% cmake -B build
   10<snip>
   11-- Found Python3: /Users/hebasto/.pyenv/shims/python3 (found suitable version "3.10.14", minimum required is "3.10") found components: Interpreter
   12<snip>
   

   Both variables, Python3_FIND_FRAMEWORK and Python3_FIND_UNVERSIONED_NAMES, can still be overridden by the user via the command line if needed.

2. hebasto added the label Build system on Dec 4, 2024
3. cmake: Improve compatibility with Python version managers 490dbfa2e8
4. hebasto force-pushed on Dec 4, 2024
5. 
   willcl-ark commented at 1:34 pm on December 5, 2024: member

   Concept ACK

   I have tested this using a uv-style venv to ensure nothing breaks, but not pyenv, where this is expected to make a difference:

   0will@ubuntu in …/src/core/bitcoin on  241204-python [$] via △ v3.30.5 : 🐍 (core)
   1₿ command -v python3
   2/home/will/src/core/.venv/bin/python3
   3
   4will@ubuntu in …/src/core/bitcoin on  241204-python [$] via △ v3.30.5 : 🐍 (core)
   5₿ cmake -B build --fresh | rg python
   6-- Found Python3: /home/will/src/core/.venv/bin/python3 (found suitable version "3.10.14", minimum required is "3.10") found components: Interpreter
   

   Trying to target symbol checks, which launches with the configured python also shows the correct binary in use:

   0will@ubuntu in …/src/core/bitcoin on  241204-python [$] via △ v3.30.5 : 🐍 (core) took 10s
   1₿ cmake --build build --target test-security-check
   2[1/1] cd /home/will/src/core/bitcoin/build && /home/linuxbrew/.linuxbrew/Cellar/cmake/3.30.5/bin/cmake -E env CXX=/usr/lib/ccache/clang...LAGS= /home/will/src/core/.venv/bin/python3 /home/will/src/core/bitcoin/contrib/devtools/test-symbol-check.py TestSymbolChecks.test_ELF
   

   As a side effect, the FindPython3 module reports a shim or symlink (e.g., from pyenv) rather than the underlying framework’s binary. The module’s output aligns with the result of the which command

   Just curious, how did you find this out? It’s not clear to me from the docs this would happen.

6. 
   DrahtBot commented at 1:34 pm on December 5, 2024: contributor

   The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

   Code Coverage & Benchmarks

   For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/31421.

   Reviews

   See the guideline for information on the review process.

   Type	Reviewers
   Concept ACK	willcl-ark

   If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

7. 
   hebasto commented at 1:43 pm on December 5, 2024: member

   As a side effect, the FindPython3 module reports a shim or symlink (e.g., from pyenv) rather than the underlying framework’s binary. The module’s output aligns with the result of the which command

   Just curious, how did you find this out? It’s not clear to me from the docs this would happen.

   From Python3_FIND_FRAMEWORK docs:

   On macOS the Python3_FIND_FRAMEWORK variable determine the order of preference between Apple-style and unix-style package components.

   You could observe the difference by configuring with -DPython3_FIND_FRAMEWORK=FIRST vs -DPython3_FIND_FRAMEWORK=LAST. The real Python binary can be verified with sys.executable.

Contributors
hebasto willcl-ark DrahtBot

Labels
Build system