Kitware/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-05-08 22:37:04 +08:00
Code Issues Projects Releases Wiki Activity

FindPython{Interp,Libs}: Update documentation

Browse Source 
Even though these modules are removed with a policy, documentation can
still be improved a bit to help when upgrading CMake code.

Changes:
- Synced modules documentation with other similar find modules.
- Added examples section to hint how to rewrite code using the
  FindPython module.
- FindPythonLibs:
  - Deprecated variables moved to a separate section.
  - PythonLibs_FOUND variable used. The PYTHONLIBS_FOUND variable is
    also set to the same value since CMake 3.3.
- FindPythonInterp:
  - PythonInterp_FOUND variable used. The PYTHONINTERP_FOUND variable is
    also set to the same value since CMake 3.3.
This commit is contained in:
Peter Kokot 2025-04-11 19:01:55 +02:00
parent 562be7f05c
commit 008dc3f330
No known key found for this signature in database
GPG Key ID: A94800907AA79B36
2 changed files with 153 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
Modules/FindPythonInterp.cmake
View File

@ -10,47 +10,80 @@ FindPythonInterp
.. deprecated:: 3.12 .. 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 the Python interpreter and determines the location of its
executable.
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.
.. note:: .. note::
A call to ``find_package(PythonInterp ${V})`` for python version ``V`` When using both this and the :module:`FindPythonLibs` module, call
may find a ``python`` executable with no version suffix. In this case ``find_package(PythonInterp)`` before ``find_package(PythonLibs)``. This
no attempt is made to avoid python executables from other versions. ensures that the detected interpreter version is used to guide the selection
Use :module:`FindPython3`, :module:`FindPython2` or :module:`FindPython` of compatible libraries, resulting in a consistent ``PYTHON_LIBRARIES`` value.
instead.
.. 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) cmake_policy(GET CMP0148 _FindPythonInterp_CMP0148)

109
Modules/FindPythonLibs.cmake
View File

@ -10,42 +10,101 @@ FindPythonLibs
.. deprecated:: 3.12 .. 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 .. note::
include files and libraries are. It also determines what the name of
the library is. This code sets the following variables:
:: 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 Result Variables
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)
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 ``PYTHONLIBS_VERSION_STRING``
of version numbers that should be taken into account when searching .. versionadded:: 2.8.8
for Python. You need to set this variable before calling
find_package(PythonLibs).
If you'd like to specify the installation of Python to use, you should The version of the Python libraries found.
modify the following cache variables:
:: ``PYTHON_LIBRARIES``
Libraries needed to link against to use Python.
PYTHON_LIBRARY - path to the python library ``PYTHON_INCLUDE_DIRS``
PYTHON_INCLUDE_DIR - path to where Python.h is found Include directories needed to use Python.
If calling both ``find_package(PythonInterp)`` and Cache Variables
``find_package(PythonLibs)``, call ``find_package(PythonInterp)`` first to ^^^^^^^^^^^^^^^
get the currently active Python version by default with a consistent version
of PYTHON_LIBRARIES. 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) cmake_policy(PUSH)