Modules/FindPython.cmake - third_party/cmake - Git at Google

 # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
 # file Copyright.txt or https://cmake.org/licensing for details.

 #[=======================================================================[.rst:
 FindPython
 ----------

 Find Python interpreter, compiler and development environment (include
 directories and libraries).

 Three components are supported:

 * ``Interpreter``: search for Python interpreter.
 * ``Compiler``: search for Python compiler. Only offered by IronPython.
 * ``Development``: search for development artifacts (include directories and
   libraries).
 * ``NumPy``: search for NumPy include directories.

 If no ``COMPONENTS`` is specified, ``Interpreter`` is assumed.

 To ensure consistent versions between components ``Interpreter``, ``Compiler``,
 ``Development`` and ``NumPy``, specify all components at the same time::

   find_package (Python COMPONENTS Interpreter Development)

 This module looks preferably for version 3 of Python. If not found, version 2
 is searched.
 To manage concurrent versions 3 and 2 of Python, use :module:`FindPython3` and
 :module:`FindPython2` modules rather than this one.

 .. note::

   If components ``Interpreter`` and ``Development`` are both specified, this
   module search only for interpreter with same platform architecture as the one
   defined by ``CMake`` configuration. This contraint does not apply if only
   ``Interpreter`` component is specified.

 Imported Targets
 ^^^^^^^^^^^^^^^^

 This module defines the following :ref:`Imported Targets <Imported Targets>`
 (when :prop_gbl:`CMAKE_ROLE` is ``PROJECT``):

 ``Python::Interpreter``
   Python interpreter. Target defined if component ``Interpreter`` is found.
 ``Python::Compiler``
   Python compiler. Target defined if component ``Compiler`` is found.
 ``Python::Python``
   Python library for Python embedding. Target defined if component
   ``Development`` is found.
 ``Python::Module``
   Python library for Python module. Target defined if component ``Development``
   is found.
 ``Python::NumPy``
   NumPy Python library. Target defined if component ``NumPy`` is found.

 Result Variables
 ^^^^^^^^^^^^^^^^

 This module will set the following variables in your project
 (see :ref:`Standard Variable Names <CMake Developer Standard Variable Names>`):

 ``Python_FOUND``
   System has the Python requested components.
 ``Python_Interpreter_FOUND``
   System has the Python interpreter.
 ``Python_EXECUTABLE``
   Path to the Python interpreter.
 ``Python_INTERPRETER_ID``
   A short string unique to the interpreter. Possible values include:
     * Python
     * ActivePython
     * Anaconda
     * Canopy
     * IronPython
 ``Python_STDLIB``
   Standard platform independent installation directory.

   Information returned by
   ``distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=True)``.
 ``Python_STDARCH``
   Standard platform dependent installation directory.

   Information returned by
   ``distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=True)``.
 ``Python_SITELIB``
   Third-party platform independent installation directory.

   Information returned by
   ``distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=False)``.
 ``Python_SITEARCH``
   Third-party platform dependent installation directory.

   Information returned by
   ``distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=False)``.
 ``Python_Compiler_FOUND``
   System has the Python compiler.
 ``Python_COMPILER``
   Path to the Python compiler. Only offered by IronPython.
 ``Python_COMPILER_ID``
   A short string unique to the compiler. Possible values include:
     * IronPython
 ``Python_Development_FOUND``
   System has the Python development artifacts.
 ``Python_INCLUDE_DIRS``
   The Python include directories.
 ``Python_LIBRARIES``
   The Python libraries.
 ``Python_LIBRARY_DIRS``
   The Python library directories.
 ``Python_RUNTIME_LIBRARY_DIRS``
   The Python runtime library directories.
 ``Python_VERSION``
   Python version.
 ``Python_VERSION_MAJOR``
   Python major version.
 ``Python_VERSION_MINOR``
   Python minor version.
 ``Python_VERSION_PATCH``
   Python patch version.
 ``Python_NumPy_FOUND``
   System has the NumPy.
 ``Python_NumPy_INCLUDE_DIRS``
   The NumPy include directries.
 ``Python_NumPy_VERSION``
   The NumPy version.

 Hints
 ^^^^^

 ``Python_ROOT_DIR``
   Define the root directory of a Python installation.

 ``Python_USE_STATIC_LIBS``
   * If not defined, search for shared libraries and static libraries in that
     order.
   * If set to TRUE, search **only** for static libraries.
   * If set to FALSE, search **only** for shared libraries.

 ``Python_FIND_ABI``
   This variable defines which ABIs, as defined in
   `PEP 3149 <https://www.python.org/dev/peps/pep-3149/>`_, should be searched.

   .. note::

     This hint will be honored only when searched for ``Python`` version 3.

   .. note::

     If ``Python_FIND_ABI`` is not defined, any ABI will be searched.

   The ``Python_FIND_ABI`` variable is a 3-tuple specifying, in that order,
   ``pydebug`` (``d``), ``pymalloc`` (``m``) and ``unicode`` (``u``) flags.
   Each element can be set to one of the following:

   * ``ON``: Corresponding flag is selected.
   * ``OFF``: Corresponding flag is not selected.
   * ``ANY``: The two posibilties (``ON`` and ``OFF``) will be searched.

   From this 3-tuple, various ABIs will be searched starting from the most
   specialized to the most general. Moreover, ``debug`` versions will be
   searched **after** ``non-debug`` ones.

   For example, if we have::

     set (Python_FIND_ABI "ON" "ANY" "ANY")

   The following flags combinations will be appended, in that order, to the
   artifact names: ``dmu``, ``dm``, ``du``, and ``d``.

   And to search any possible ABIs::

     set (Python_FIND_ABI "ANY" "ANY" "ANY")

   The following combinations, in that order, will be used: ``mu``, ``m``,
   ``u``, ``<empty>``, ``dmu``, ``dm``, ``du`` and ``d``.

   .. note::

     This hint is useful only on ``POSIX`` systems. So, on ``Windows`` systems,
     when ``Python_FIND_ABI`` is defined, ``Python`` distributions from
     `python.org <https://www.python.org/>`_ will be found only if value for
     each flag is ``OFF`` or ``ANY``.

 ``Python_FIND_STRATEGY``
   This variable defines how lookup will be done.
   The ``Python_FIND_STRATEGY`` variable can be set to empty or one of the
   following:

   * ``VERSION``: Try to find the most recent version in all specified
     locations.
     This is the default if policy :policy:`CMP0094` is undefined or set to
     ``OLD``.
   * ``LOCATION``: Stops lookup as soon as a version satisfying version
     constraints is founded.
     This is the default if policy :policy:`CMP0094` is set to ``NEW``.

 ``Python_FIND_REGISTRY``
   On Windows the ``Python_FIND_REGISTRY`` variable determine the order
   of preference between registry and environment variables.
   the ``Python_FIND_REGISTRY`` variable can be set to empty or one of the
   following:

   * ``FIRST``: Try to use registry before environment variables.
     This is the default.
   * ``LAST``: Try to use registry after environment variables.
   * ``NEVER``: Never try to use registry.

 ``Python_FIND_FRAMEWORK``
   On macOS the ``Python_FIND_FRAMEWORK`` variable determine the order of
   preference between Apple-style and unix-style package components.
   This variable can be set to empty or take same values as
   :variable:`CMAKE_FIND_FRAMEWORK` variable.

   .. note::

     Value ``ONLY`` is not supported so ``FIRST`` will be used instead.

   If ``Python_FIND_FRAMEWORK`` is not defined, :variable:`CMAKE_FIND_FRAMEWORK`
   variable will be used, if any.

 ``Python_FIND_VIRTUALENV``
   This variable defines the handling of virtual environments. It is meaningfull
   only when a virtual environment is active (i.e. the ``activate`` script has
   been evaluated). In this case, it takes precedence over
   ``Python_FIND_REGISTRY`` and ``CMAKE_FIND_FRAMEWORK`` variables.
   The ``Python_FIND_VIRTUALENV`` variable can be set to empty or one of the
   following:

   * ``FIRST``: The virtual environment is used before any other standard
     paths to look-up for the interpreter. This is the default.
   * ``ONLY``: Only the virtual environment is used to look-up for the
     interpreter.
   * ``STANDARD``: The virtual environment is not used to look-up for the
     interpreter. In this case, variable ``Python_FIND_REGISTRY`` (Windows)
     or ``CMAKE_FIND_FRAMEWORK`` (macOS) can be set with value ``LAST`` or
     ``NEVER`` to select preferably the interpreter from the virtual
     environment.

   .. note::

     If the component ``Development`` is requested, it is **strongly**
     recommended to also include the component ``Interpreter`` to get expected
     result.

 Commands
 ^^^^^^^^

 This module defines the command ``Python_add_library`` (when
 :prop_gbl:`CMAKE_ROLE` is ``PROJECT``), which has the same semantics as
 :command:`add_library` and adds a dependency to target ``Python::Python`` or,
 when library type is ``MODULE``, to target ``Python::Module`` and takes care of
 Python module naming rules::

   Python_add_library (my_module MODULE src1.cpp)

 If library type is not specified, ``MODULE`` is assumed.
 #]=======================================================================]


 set (_PYTHON_PREFIX Python)

 if (DEFINED Python_FIND_VERSION)
   set (_Python_REQUIRED_VERSION_MAJOR ${Python_FIND_VERSION_MAJOR})

   include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake)
 else()
   # iterate over versions in quiet and NOT required modes to avoid multiple
   # "Found" messages and prematurally failure.
   set (_Python_QUIETLY ${Python_FIND_QUIETLY})
   set (_Python_REQUIRED ${Python_FIND_REQUIRED})
   set (Python_FIND_QUIETLY TRUE)
   set (Python_FIND_REQUIRED FALSE)

   set (_Python_REQUIRED_VERSIONS 3 2)
   set (_Python_REQUIRED_VERSION_LAST 2)

   foreach (_Python_REQUIRED_VERSION_MAJOR IN LISTS _Python_REQUIRED_VERSIONS)
     set (Python_FIND_VERSION ${_Python_REQUIRED_VERSION_MAJOR})
     include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake)
     if (Python_FOUND OR
         _Python_REQUIRED_VERSION_MAJOR EQUAL _Python_REQUIRED_VERSION_LAST)
       break()
     endif()
     # clean-up some CACHE variables to ensure look-up restart from scratch
     foreach (_Python_ITEM IN LISTS _Python_CACHED_VARS)
       unset (${_Python_ITEM} CACHE)
     endforeach()
   endforeach()

   unset (Python_FIND_VERSION)

   set (Python_FIND_QUIETLY ${_Python_QUIETLY})
   set (Python_FIND_REQUIRED ${_Python_REQUIRED})
   if (Python_FIND_REQUIRED OR NOT Python_FIND_QUIETLY)
     # call again validation command to get "Found" or error message
     find_package_handle_standard_args (Python HANDLE_COMPONENTS
                                               REQUIRED_VARS ${_Python_REQUIRED_VARS}
                                               VERSION_VAR Python_VERSION)
   endif()
 endif()

 if (COMMAND __Python_add_library)
   macro (Python_add_library)
     __Python_add_library (Python ${ARGV})
   endmacro()
 endif()

 unset (_PYTHON_PREFIX)
	# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
	# file Copyright.txt or https://cmake.org/licensing for details.

	#[=======================================================================[.rst:
	FindPython
	----------

	Find Python interpreter, compiler and development environment (include
	directories and libraries).

	Three components are supported:

	* ``Interpreter``: search for Python interpreter.
	* ``Compiler``: search for Python compiler. Only offered by IronPython.
	* ``Development``: search for development artifacts (include directories and
	libraries).
	* ``NumPy``: search for NumPy include directories.

	If no ``COMPONENTS`` is specified, ``Interpreter`` is assumed.

	To ensure consistent versions between components ``Interpreter``, ``Compiler``,
	``Development`` and ``NumPy``, specify all components at the same time::

	find_package (Python COMPONENTS Interpreter Development)

	This module looks preferably for version 3 of Python. If not found, version 2
	is searched.
	To manage concurrent versions 3 and 2 of Python, use :module:`FindPython3` and
	:module:`FindPython2` modules rather than this one.

	.. note::

	If components ``Interpreter`` and ``Development`` are both specified, this
	module search only for interpreter with same platform architecture as the one
	defined by ``CMake`` configuration. This contraint does not apply if only
	``Interpreter`` component is specified.

	Imported Targets
	^^^^^^^^^^^^^^^^

	This module defines the following :ref:`Imported Targets <Imported Targets>`
	(when :prop_gbl:`CMAKE_ROLE` is ``PROJECT``):

	``Python::Interpreter``
	Python interpreter. Target defined if component ``Interpreter`` is found.
	``Python::Compiler``
	Python compiler. Target defined if component ``Compiler`` is found.
	``Python::Python``
	Python library for Python embedding. Target defined if component
	``Development`` is found.
	``Python::Module``
	Python library for Python module. Target defined if component ``Development``
	is found.
	``Python::NumPy``
	NumPy Python library. Target defined if component ``NumPy`` is found.

	Result Variables
	^^^^^^^^^^^^^^^^

	This module will set the following variables in your project
	(see :ref:`Standard Variable Names <CMake Developer Standard Variable Names>`):

	``Python_FOUND``
	System has the Python requested components.
	``Python_Interpreter_FOUND``
	System has the Python interpreter.
	``Python_EXECUTABLE``
	Path to the Python interpreter.
	``Python_INTERPRETER_ID``
	A short string unique to the interpreter. Possible values include:
	* Python
	* ActivePython
	* Anaconda
	* Canopy
	* IronPython
	``Python_STDLIB``
	Standard platform independent installation directory.

	Information returned by
	``distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=True)``.
	``Python_STDARCH``
	Standard platform dependent installation directory.

	Information returned by
	``distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=True)``.
	``Python_SITELIB``
	Third-party platform independent installation directory.

	Information returned by
	``distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=False)``.
	``Python_SITEARCH``
	Third-party platform dependent installation directory.

	Information returned by
	``distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=False)``.
	``Python_Compiler_FOUND``
	System has the Python compiler.
	``Python_COMPILER``
	Path to the Python compiler. Only offered by IronPython.
	``Python_COMPILER_ID``
	A short string unique to the compiler. Possible values include:
	* IronPython
	``Python_Development_FOUND``
	System has the Python development artifacts.
	``Python_INCLUDE_DIRS``
	The Python include directories.
	``Python_LIBRARIES``
	The Python libraries.
	``Python_LIBRARY_DIRS``
	The Python library directories.
	``Python_RUNTIME_LIBRARY_DIRS``
	The Python runtime library directories.
	``Python_VERSION``
	Python version.
	``Python_VERSION_MAJOR``
	Python major version.
	``Python_VERSION_MINOR``
	Python minor version.
	``Python_VERSION_PATCH``
	Python patch version.
	``Python_NumPy_FOUND``
	System has the NumPy.
	``Python_NumPy_INCLUDE_DIRS``
	The NumPy include directries.
	``Python_NumPy_VERSION``
	The NumPy version.

	Hints
	^^^^^

	``Python_ROOT_DIR``
	Define the root directory of a Python installation.

	``Python_USE_STATIC_LIBS``
	* If not defined, search for shared libraries and static libraries in that
	order.
	* If set to TRUE, search only for static libraries.
	* If set to FALSE, search only for shared libraries.

	``Python_FIND_ABI``
	This variable defines which ABIs, as defined in
	`PEP 3149 <https://www.python.org/dev/peps/pep-3149/>`_, should be searched.

	.. note::

	This hint will be honored only when searched for ``Python`` version 3.

	.. note::

	If ``Python_FIND_ABI`` is not defined, any ABI will be searched.

	The ``Python_FIND_ABI`` variable is a 3-tuple specifying, in that order,
	``pydebug`` (``d``), ``pymalloc`` (``m``) and ``unicode`` (``u``) flags.
	Each element can be set to one of the following:

	* ``ON``: Corresponding flag is selected.
	* ``OFF``: Corresponding flag is not selected.
	* ``ANY``: The two posibilties (``ON`` and ``OFF``) will be searched.

	From this 3-tuple, various ABIs will be searched starting from the most
	specialized to the most general. Moreover, ``debug`` versions will be
	searched after ``non-debug`` ones.

	For example, if we have::

	set (Python_FIND_ABI "ON" "ANY" "ANY")

	The following flags combinations will be appended, in that order, to the
	artifact names: ``dmu``, ``dm``, ``du``, and ``d``.

	And to search any possible ABIs::

	set (Python_FIND_ABI "ANY" "ANY" "ANY")

	The following combinations, in that order, will be used: ``mu``, ``m``,
	``u``, ``<empty>``, ``dmu``, ``dm``, ``du`` and ``d``.

	.. note::

	This hint is useful only on ``POSIX`` systems. So, on ``Windows`` systems,
	when ``Python_FIND_ABI`` is defined, ``Python`` distributions from
	`python.org <https://www.python.org/>`_ will be found only if value for
	each flag is ``OFF`` or ``ANY``.

	``Python_FIND_STRATEGY``
	This variable defines how lookup will be done.
	The ``Python_FIND_STRATEGY`` variable can be set to empty or one of the
	following:

	* ``VERSION``: Try to find the most recent version in all specified
	locations.
	This is the default if policy :policy:`CMP0094` is undefined or set to
	``OLD``.
	* ``LOCATION``: Stops lookup as soon as a version satisfying version
	constraints is founded.
	This is the default if policy :policy:`CMP0094` is set to ``NEW``.

	``Python_FIND_REGISTRY``
	On Windows the ``Python_FIND_REGISTRY`` variable determine the order
	of preference between registry and environment variables.
	the ``Python_FIND_REGISTRY`` variable can be set to empty or one of the
	following:

	* ``FIRST``: Try to use registry before environment variables.
	This is the default.
	* ``LAST``: Try to use registry after environment variables.
	* ``NEVER``: Never try to use registry.

	``Python_FIND_FRAMEWORK``
	On macOS the ``Python_FIND_FRAMEWORK`` variable determine the order of
	preference between Apple-style and unix-style package components.
	This variable can be set to empty or take same values as
	:variable:`CMAKE_FIND_FRAMEWORK` variable.

	.. note::

	Value ``ONLY`` is not supported so ``FIRST`` will be used instead.

	If ``Python_FIND_FRAMEWORK`` is not defined, :variable:`CMAKE_FIND_FRAMEWORK`
	variable will be used, if any.

	``Python_FIND_VIRTUALENV``
	This variable defines the handling of virtual environments. It is meaningfull
	only when a virtual environment is active (i.e. the ``activate`` script has
	been evaluated). In this case, it takes precedence over
	``Python_FIND_REGISTRY`` and ``CMAKE_FIND_FRAMEWORK`` variables.
	The ``Python_FIND_VIRTUALENV`` variable can be set to empty or one of the
	following:

	* ``FIRST``: The virtual environment is used before any other standard
	paths to look-up for the interpreter. This is the default.
	* ``ONLY``: Only the virtual environment is used to look-up for the
	interpreter.
	* ``STANDARD``: The virtual environment is not used to look-up for the
	interpreter. In this case, variable ``Python_FIND_REGISTRY`` (Windows)
	or ``CMAKE_FIND_FRAMEWORK`` (macOS) can be set with value ``LAST`` or
	``NEVER`` to select preferably the interpreter from the virtual
	environment.

	.. note::

	If the component ``Development`` is requested, it is strongly
	recommended to also include the component ``Interpreter`` to get expected
	result.

	Commands
	^^^^^^^^

	This module defines the command ``Python_add_library`` (when
	:prop_gbl:`CMAKE_ROLE` is ``PROJECT``), which has the same semantics as
	:command:`add_library` and adds a dependency to target ``Python::Python`` or,
	when library type is ``MODULE``, to target ``Python::Module`` and takes care of
	Python module naming rules::

	Python_add_library (my_module MODULE src1.cpp)

	If library type is not specified, ``MODULE`` is assumed.
	#]=======================================================================]


	set (_PYTHON_PREFIX Python)

	if (DEFINED Python_FIND_VERSION)
	set (_Python_REQUIRED_VERSION_MAJOR ${Python_FIND_VERSION_MAJOR})

	include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake)
	else()
	# iterate over versions in quiet and NOT required modes to avoid multiple
	# "Found" messages and prematurally failure.
	set (_Python_QUIETLY ${Python_FIND_QUIETLY})
	set (_Python_REQUIRED ${Python_FIND_REQUIRED})
	set (Python_FIND_QUIETLY TRUE)
	set (Python_FIND_REQUIRED FALSE)

	set (_Python_REQUIRED_VERSIONS 3 2)
	set (_Python_REQUIRED_VERSION_LAST 2)

	foreach (_Python_REQUIRED_VERSION_MAJOR IN LISTS _Python_REQUIRED_VERSIONS)
	set (Python_FIND_VERSION ${_Python_REQUIRED_VERSION_MAJOR})
	include (${CMAKE_CURRENT_LIST_DIR}/FindPython/Support.cmake)
	if (Python_FOUND OR
	_Python_REQUIRED_VERSION_MAJOR EQUAL _Python_REQUIRED_VERSION_LAST)
	break()
	endif()
	# clean-up some CACHE variables to ensure look-up restart from scratch
	foreach (_Python_ITEM IN LISTS _Python_CACHED_VARS)
	unset (${_Python_ITEM} CACHE)
	endforeach()
	endforeach()

	unset (Python_FIND_VERSION)

	set (Python_FIND_QUIETLY ${_Python_QUIETLY})
	set (Python_FIND_REQUIRED ${_Python_REQUIRED})
	if (Python_FIND_REQUIRED OR NOT Python_FIND_QUIETLY)
	# call again validation command to get "Found" or error message
	find_package_handle_standard_args (Python HANDLE_COMPONENTS
	REQUIRED_VARS ${_Python_REQUIRED_VARS}
	VERSION_VAR Python_VERSION)
	endif()
	endif()

	if (COMMAND __Python_add_library)
	macro (Python_add_library)
	__Python_add_library (Python ${ARGV})
	endmacro()
	endif()

	unset (_PYTHON_PREFIX)