diff --git a/Modules/FindPythonInterp.cmake b/Modules/FindPythonInterp.cmake index e236112d8e..490d79f2cd 100644 --- a/Modules/FindPythonInterp.cmake +++ b/Modules/FindPythonInterp.cmake @@ -10,47 +10,80 @@ FindPythonInterp .. deprecated:: 3.12 - Use :module:`FindPython3`, :module:`FindPython2` or :module:`FindPython` instead. + Use :module:`FindPython3`, :module:`FindPython2`, or :module:`FindPython` + instead. -Find python interpreter - -This module finds if Python interpreter is installed and determines -where the executables are. This code sets the following variables: - -:: - - PYTHONINTERP_FOUND - Was the Python executable found - PYTHON_EXECUTABLE - path to the Python interpreter - - - -:: - - PYTHON_VERSION_STRING - Python version found e.g. 2.5.2 - PYTHON_VERSION_MAJOR - Python major version found e.g. 2 - PYTHON_VERSION_MINOR - Python minor version found e.g. 5 - PYTHON_VERSION_PATCH - Python patch version found e.g. 2 - - - -The Python_ADDITIONAL_VERSIONS variable can be used to specify a list -of version numbers that should be taken into account when searching -for Python. You need to set this variable before calling -find_package(PythonInterp). - -If calling both ``find_package(PythonInterp)`` and -``find_package(PythonLibs)``, call ``find_package(PythonInterp)`` first to -get the currently active Python version by default with a consistent version -of PYTHON_LIBRARIES. +This module finds the Python interpreter and determines the location of its +executable. .. note:: - A call to ``find_package(PythonInterp ${V})`` for python version ``V`` - may find a ``python`` executable with no version suffix. In this case - no attempt is made to avoid python executables from other versions. - Use :module:`FindPython3`, :module:`FindPython2` or :module:`FindPython` - instead. + When using both this and the :module:`FindPythonLibs` module, call + ``find_package(PythonInterp)`` before ``find_package(PythonLibs)``. This + ensures that the detected interpreter version is used to guide the selection + of compatible libraries, resulting in a consistent ``PYTHON_LIBRARIES`` value. +.. note:: + + A call to ``find_package(PythonInterp ${V})`` for Python version ``V`` may + find a ``python`` executable with no version suffix. In this case no attempt + is made to avoid Python executables from other versions. Use + :module:`FindPython3`, :module:`FindPython2`, or :module:`FindPython` instead. + +Result Variables +^^^^^^^^^^^^^^^^ + +This module defines the following variables: + +``PythonInterp_FOUND`` + Boolean indicating whether the (requested version of) Python executable is + found. For backward compatibility, the ``PYTHONINTERP_FOUND`` variable is + also set to the same value. +``PYTHON_VERSION_STRING`` + Python version found (e.g., ``2.5.2``). +``PYTHON_VERSION_MAJOR`` + Python major version found (e.g., ``2``). +``PYTHON_VERSION_MINOR`` + Python minor version found (e.g., ``5``). +``PYTHON_VERSION_PATCH`` + Python patch version found (e.g., ``2``). + +Cache Variables +^^^^^^^^^^^^^^^ + +The following cache variables may also be set: + +``PYTHON_EXECUTABLE`` + The path to the Python interpreter. + +Hints +^^^^^ + +This module accepts the following variables before calling +``find_package(PythonInterp)``: + +``Python_ADDITIONAL_VERSIONS`` + This variable can be used to specify a list of version numbers that should be + taken into account when searching for Python. + +Examples +^^^^^^^^ + +Finding the Python interpreter in earlier versions of CMake: + +.. code-block:: cmake + + find_package(PythonInterp) + execute_process(COMMAND ${PYTHON_EXECUTABLE} --help) + +Starting with CMake 3.12, the Python interpreter can be found using the +:module:`FindPython` module. The equivalent example using the modern approach +is: + +.. code-block:: cmake + + find_package(Python) + execute_process(COMMAND ${Python_EXECUTABLE} --help) #]=======================================================================] cmake_policy(GET CMP0148 _FindPythonInterp_CMP0148) diff --git a/Modules/FindPythonLibs.cmake b/Modules/FindPythonLibs.cmake index 3d7b536d76..2c8e13f3ab 100644 --- a/Modules/FindPythonLibs.cmake +++ b/Modules/FindPythonLibs.cmake @@ -10,42 +10,101 @@ FindPythonLibs .. deprecated:: 3.12 - Use :module:`FindPython3`, :module:`FindPython2` or :module:`FindPython` instead. + Use :module:`FindPython3`, :module:`FindPython2`, or :module:`FindPython` + instead. -Find python libraries +This module finds the Python installation and determines the location of its +include directories and libraries, as well as the name of the Python library to +link against. -This module finds if Python is installed and determines where the -include files and libraries are. It also determines what the name of -the library is. This code sets the following variables: +.. note:: -:: + When using both this and the :module:`FindPythonInterp` module, call + ``find_package(PythonInterp)`` before ``find_package(PythonLibs)``. This + ensures that the detected interpreter version is used to guide the selection + of compatible libraries, resulting in a consistent ``PYTHON_LIBRARIES`` value. - PYTHONLIBS_FOUND - have the Python libs been found - PYTHON_LIBRARIES - path to the python library - PYTHON_INCLUDE_PATH - path to where Python.h is found (deprecated) - PYTHON_INCLUDE_DIRS - path to where Python.h is found - PYTHON_DEBUG_LIBRARIES - path to the debug library (deprecated) - PYTHONLIBS_VERSION_STRING - version of the Python libs found (since CMake 2.8.8) +Result Variables +^^^^^^^^^^^^^^^^ +This module defines the following variables: +``PythonLibs_FOUND`` + Boolean indicating whether the (requested version of) Python libraries have + been found. For backward compatibility, the ``PYTHONLIBS_FOUND`` variable is + also set to the same value. -The Python_ADDITIONAL_VERSIONS variable can be used to specify a list -of version numbers that should be taken into account when searching -for Python. You need to set this variable before calling -find_package(PythonLibs). +``PYTHONLIBS_VERSION_STRING`` + .. versionadded:: 2.8.8 -If you'd like to specify the installation of Python to use, you should -modify the following cache variables: + The version of the Python libraries found. -:: +``PYTHON_LIBRARIES`` + Libraries needed to link against to use Python. - PYTHON_LIBRARY - path to the python library - PYTHON_INCLUDE_DIR - path to where Python.h is found +``PYTHON_INCLUDE_DIRS`` + Include directories needed to use Python. -If calling both ``find_package(PythonInterp)`` and -``find_package(PythonLibs)``, call ``find_package(PythonInterp)`` first to -get the currently active Python version by default with a consistent version -of PYTHON_LIBRARIES. +Cache Variables +^^^^^^^^^^^^^^^ + +The following cache variables may also be set to specify the Python installation +to use: + +``PYTHON_LIBRARY`` + The path to the Python library. + +``PYTHON_INCLUDE_DIR`` + The directory containing the ``Python.h`` header file. + +Hints +^^^^^ + +This module accepts the following variables before calling +``find_package(PythonLibs)``: + +``Python_ADDITIONAL_VERSIONS`` + This variable can be used to specify a list of version numbers that should be + taken into account when searching for Python. + +Deprecated Variables +^^^^^^^^^^^^^^^^^^^^ + +These variables are provided for backward compatibility: + +``PYTHON_DEBUG_LIBRARIES`` + .. deprecated:: 2.8.8 + Use ``PYTHON_LIBRARIES`` instead. + + Result variable that holds the path to the debug library. + +``PYTHON_INCLUDE_PATH`` + .. deprecated:: 2.8.0 + Use ``PYTHON_INCLUDE_DIR`` or ``PYTHON_INCLUDE_DIRS`` instead. + + Result variable that holds the path to the directory containing the + ``Python.h`` header file. + +Examples +^^^^^^^^ + +In earlier versions of CMake, Python libraries were found and used in a project +like this: + +.. code-block:: cmake + + find_package(PythonLibs) + target_link_libraries(app PRIVATE ${PYTHON_LIBRARIES}) + target_include_directories(app PRIVATE ${PYTHON_INCLUDE_DIRS}) + +Starting with CMake 3.12, Python libraries can be found using the +:module:`FindPython` module. The equivalent example using the modern approach +with an imported target is: + +.. code-block:: cmake + + find_package(Python COMPONENTS Development) + target_link_libraries(app PRIVATE Python::Python) #]=======================================================================] cmake_policy(PUSH)