mirror of
https://github.com/Kitware/CMake.git
synced 2025-05-08 14:29:03 +08:00
FindPython{Interp,Libs}: Update documentation
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
parent
562be7f05c
commit
008dc3f330
@ -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)
|
||||
|
||||
@ -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)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user