FindPython¶
3.12 版本加入。
查找 Python 解释器、编译器和开发环境(包含目录和库)。
3.19 版本加入: 当请求版本时,可以指定为简单值或范围。 有关版本范围用法和功能的详细描述,请参阅 find_package()
命令。
支持以下组件
Interpreter
:搜索 Python 解释器。Compiler
:搜索 Python 编译器。 仅 IronPython 提供。Development
:搜索开发工件(包含目录和库)。3.18 版本加入: 此组件包含两个可以独立指定的子组件
Development.Module
:搜索 Python 模块开发所需的工件。Development.Embed
:搜索 Python 嵌入式开发所需的工件。
3.26 版本加入
Development.SABIModule
:搜索使用 稳定应用二进制接口 的 Python 模块开发所需的工件。 此组件仅适用于3.2
及更高版本。
NumPy
:搜索 NumPy 包含目录。
3.14 版本加入: 添加了 NumPy
组件。
如果未指定 COMPONENTS
,则假定为 Interpreter
。
如果指定了组件 Development
,则意味着子组件 Development.Module
和 Development.Embed
。
为了确保组件 Interpreter
、Compiler
、Development
(或其子组件之一)和 NumPy
之间的版本一致,请同时指定所有组件
find_package (Python COMPONENTS Interpreter Development)
此模块优先查找 Python 3 版本。 如果未找到,则搜索版本 2。 要管理 Python 的并发版本 3 和 2,请使用 FindPython3
和 FindPython2
模块,而不是此模块。
注意
如果同时指定了组件 Interpreter
和 Development
(或其子组件之一),则此模块仅搜索与 CMake 配置定义的平台架构相同的解释器。 如果仅指定 Interpreter
组件,则此约束不适用。
导入目标¶
此模块定义了以下 导入目标
3.14 版本变更: 导入目标 仅在 CMAKE_ROLE
为 PROJECT
时创建。
Python::Interpreter
Python 解释器。 仅当找到
Interpreter
组件时,才定义此目标。Python::InterpreterDebug
3.30 版本加入。
Python 调试解释器。 仅当找到
Interpreter
组件并且定义了Python_EXECUTABLE_DEBUG
变量时,才定义此目标。 该目标仅在Windows
平台上定义。Python::InterpreterMultiConfig
3.30 版本加入。
Python 解释器。 将根据上下文(平台、配置)使用解释器的发布或调试版本。 仅当找到
Interpreter
组件时,才定义此目标Python::Compiler
Python 编译器。 仅当找到
Compiler
组件时,才定义此目标。Python::Module
3.15 版本加入。
用于 Python 模块的 Python 库。 如果找到组件
Development.Module
,则定义目标。Python::SABIModule
3.26 版本加入。
用于使用稳定应用二进制接口的 Python 模块的 Python 库。 如果找到组件
Development.SABIModule
,则定义目标。Python::Python
用于 Python 嵌入的 Python 库。 如果找到组件
Development.Embed
,则定义目标。Python::NumPy
3.14 版本加入。
NumPy Python 库。 如果找到组件
NumPy
,则定义目标。
结果变量¶
此模块将在您的项目中设置以下变量(请参阅 标准变量名称)
Python_FOUND
系统具有请求的 Python 组件。
Python_Interpreter_FOUND
系统具有 Python 解释器。
Python_EXECUTABLE
Python 解释器的路径。
Python_EXECUTABLE_DEBUG
3.30 版本加入。
调试 Python 解释器的路径。 它仅在
Windows
平台上定义。Python_INTERPRETER
3.30 版本加入。
Python 解释器的路径,定义为
generator expression
,根据上下文(平台、配置)选择Python_EXECUTABLE
或Python_EXECUTABLE_DEBUG
变量。Python_INTERPRETER_ID
- 解释器唯一的简短字符串。 可能的值包括
Python
ActivePython
Anaconda
Canopy
IronPython
PyPy
Python_STDLIB
标准平台无关安装目录。
由
sysconfig.get_path('stdlib')
返回的信息。Python_STDARCH
标准平台相关安装目录。
由
sysconfig.get_path('platstdlib')
返回的信息。Python_SITELIB
第三方平台无关安装目录。
由
sysconfig.get_path('purelib')
返回的信息。Python_SITEARCH
第三方平台相关安装目录。
由
sysconfig.get_path('platlib')
返回的信息。Python_SOABI
3.17 版本加入。
模块的扩展名后缀。
从
sysconfig.get_config_var('EXT_SUFFIX')
或sysconfig.get_config_var('SOABI')
或python3-config --extension-suffix
计算的信息。Python_SOSABI
3.26 版本加入。
使用稳定应用二进制接口的模块的扩展名后缀。
如果指定了 COMPONENT
Interpreter
,则从importlib.machinery.EXTENSION_SUFFIXES
计算的信息。 否则,扩展名为abi3
,但对于Windows
、MSYS
和CYGWIN
,则为空字符串。Python_Compiler_FOUND
系统具有 Python 编译器。
Python_COMPILER
Python 编译器的路径。 仅 IronPython 提供。
Python_COMPILER_ID
- 编译器唯一的简短字符串。 可能的值包括
IronPython
Python_DOTNET_LAUNCHER
3.18 版本加入。
.Net
解释器。 仅由IronPython
实现使用。Python_Development_FOUND
系统具有 Python 开发工件。
Python_Development.Module_FOUND
3.18 版本加入。
系统具有用于 Python 模块的 Python 开发工件。
Python_Development.SABIModule_FOUND
3.26 版本加入。
系统具有用于使用稳定应用二进制接口的 Python 模块的 Python 开发工件。
Python_Development.Embed_FOUND
3.18 版本加入。
系统具有用于 Python 嵌入的 Python 开发工件。
Python_INCLUDE_DIRS
Python 包含目录。
Python_DEFINITIONS
3.30.3 版本加入。
Python 预处理器定义。
Python_DEBUG_POSTFIX
3.30 版本加入。
调试 python 模块的后缀。 此变量可用于定义
DEBUG_POSTFIX
目标属性。Python_LINK_OPTIONS
3.19 版本加入。
Python 链接选项。 某些配置需要特定的链接选项才能正确构建和执行。
Python_LIBRARIES
Python 库。
Python_LIBRARY_DIRS
Python 库目录。
Python_RUNTIME_LIBRARY_DIRS
Python 运行时库目录。
Python_SABI_LIBRARIES
3.26 版本加入。
用于稳定应用二进制接口的 Python 库。
Python_SABI_LIBRARY_DIRS
3.26 版本加入。
Python
SABI
库目录。Python_RUNTIME_SABI_LIBRARY_DIRS
3.26 版本加入。
Python 运行时
SABI
库目录。Python_VERSION
Python 版本。
Python_VERSION_MAJOR
Python 主版本。
Python_VERSION_MINOR
Python 次版本。
Python_VERSION_PATCH
Python 补丁版本。
Python_PyPy_VERSION
3.18 版本加入。
Python PyPy 版本。
Python_NumPy_FOUND
3.14 版本加入。
系统具有 NumPy。
Python_NumPy_INCLUDE_DIRS
3.14 版本加入。
NumPy 包含目录。
Python_NumPy_VERSION
3.14 版本加入。
NumPy 版本。
提示¶
Python_ROOT_DIR
定义 Python 安装的根目录。
Python_USE_STATIC_LIBS
如果未定义,则按顺序搜索共享库和静态库。
如果设置为 TRUE,则**仅**搜索静态库。
如果设置为 FALSE,则**仅**搜索共享库。
注意
此提示在
Windows
上将被忽略,因为此平台上不提供静态库。Python_FIND_ABI
3.16 版本加入。
此变量定义应搜索哪些 ABI,如 PEP 3149 中定义的那样。
注意
仅当搜索 Python 3 版本时,此提示才会被采纳。
Python_FIND_ABI
变量是一个 4 元组,按顺序指定pydebug
(d
)、pymalloc
(m
)、unicode
(u
) 和gil_disabled
(t
) 标志。3.30 版本加入: 添加了第四个元素,指定
gil_disabled
标志(即自由线程 python),并且是可选的。 如果未指定,则值为OFF
。每个元素都可以设置为以下之一
ON
:选择相应的标志。OFF
:未选择相应的标志。ANY
:将搜索两种可能性(ON
和OFF
)。
注意
如果未定义
Python3_FIND_ABI
,则将搜索任何 ABI,但不包括gil_disabled
标志。从此 4 元组中,将搜索各种 ABI,从最专业的到最通用的。 此外,当为
pydebug
和gil_disabled
指定ANY
时,将在non-debug
和non-gil-disabled
版本**之后**搜索debug
和free threaded
版本。例如,如果我们有
set (Python_FIND_ABI "ON" "ANY" "ANY" "ON")
以下标志组合将按顺序附加到工件名称:
tdmu
、tdm
、tdu
和td
。并且要搜索任何可能的 ABI
set (Python_FIND_ABI "ANY" "ANY" "ANY" "ANY")
将按顺序使用以下组合:
mu
、m
、u
、<empty>
、dmu
、dm
、du
、d
、tmu
、tm
、tu
、t
、tdmu
、tdm
、tdu
和td
。注意
此提示仅在
POSIX
系统上有用,但gil_disabled
标志除外。 因此,在Windows
系统上,当定义Python_FIND_ABI
时,只有当每个标志的值为OFF
或ANY
(第四个标志(gil_disabled
)除外)时,才能找到来自 python.org 的Python
发行版。Python_FIND_STRATEGY
3.15 版本加入。
此变量定义查找的执行方式。
Python_FIND_STRATEGY
变量可以设置为以下之一VERSION
:尝试在所有指定位置查找最新版本。 如果策略CMP0094
未定义或设置为OLD
,则这是默认值。LOCATION
:一旦找到满足版本约束的版本,就停止查找。 如果策略CMP0094
设置为NEW
,则这是默认值。
另请参阅
Python_FIND_UNVERSIONED_NAMES
。Python_FIND_REGISTRY
3.13 版本加入。
在 Windows 上,
Python_FIND_REGISTRY
变量确定注册表和环境变量之间的首选顺序。Python_FIND_REGISTRY
变量可以设置为以下之一FIRST
:尝试先使用注册表,然后再使用环境变量。 这是默认值。LAST
:尝试先使用环境变量,然后再使用注册表。NEVER
:永远不要尝试使用注册表。
Python_FIND_FRAMEWORK
3.15 版本加入。
在 macOS 上,
Python_FIND_FRAMEWORK
变量确定 Apple 风格和 unix 风格包组件之间的首选顺序。 此变量可以采用与CMAKE_FIND_FRAMEWORK
变量相同的值。注意
不支持值
ONLY
,因此将改用FIRST
。如果未定义
Python_FIND_FRAMEWORK
,则将使用CMAKE_FIND_FRAMEWORK
变量(如果有)。Python_FIND_VIRTUALENV
3.15 版本加入。
此变量定义如何处理由
virtualenv
或conda
管理的虚拟环境。 仅当虚拟环境处于活动状态时(即已评估activate
脚本),此变量才有意义。 在这种情况下,它优先于Python_FIND_REGISTRY
和CMAKE_FIND_FRAMEWORK
变量。Python_FIND_VIRTUALENV
变量可以设置为以下之一FIRST
:虚拟环境在任何其他标准路径之前用于查找解释器。 这是默认值。ONLY
:仅虚拟环境用于查找解释器。STANDARD
:虚拟环境不用于查找解释器,但始终考虑环境变量PATH
。 在这种情况下,可以将变量Python_FIND_REGISTRY
(Windows) 或CMAKE_FIND_FRAMEWORK
(macOS) 设置为值LAST
或NEVER
,以优先从虚拟环境中选择解释器。
3.17 版本加入: 增加了对
conda
环境的支持。注意
如果请求了组件
Development
(或其子组件之一)但未找到或返回了错误的工件,则包含组件Interpreter
可能会有所帮助。Python_FIND_IMPLEMENTATIONS
3.18 版本加入。
此变量以有序列表的形式定义将搜索的不同实现。
Python_FIND_IMPLEMENTATIONS
变量可以包含以下值CPython
:这是标准实现。 各种产品,例如Anaconda
或ActivePython
,都依赖于此实现。IronPython
:此实现使用CSharp
语言,用于.NET Framework
,基于 Dynamic Language Runtime (DLR
)。 请参阅 IronPython。PyPy
:此实现使用RPython
语言和RPython translation toolchain
来生成 python 解释器。 请参阅 PyPy。
默认值为
Windows 平台:
CPython
、IronPython
其他平台:
CPython
注意
此提示的优先级在所有提示中最低,因此即使例如,您首先指定
IronPython
,然后在第二位指定CPython
,也可能会选择基于CPython
的 python 产品,因为例如使用Python_FIND_STRATEGY=LOCATION
,将首先搜索每个位置的IronPython
,然后搜索CPython
。注意
当指定
IronPython
时,在Windows
以外的平台上,.Net
解释器(即mono
命令)预计可通过PATH
变量获得。Python_FIND_UNVERSIONED_NAMES
3.20 版本加入。
此变量定义如何搜索通用名称。 目前,它仅适用于解释器的通用名称,即
python3
或python2
和python
。Python_FIND_UNVERSIONED_NAMES
变量可以设置为以下值之一FIRST
:在搜索更专业的名称(例如python2.5
)之前,先搜索通用名称。LAST
:在搜索更专业的名称之后,再搜索通用名称。 这是默认值。NEVER
:根本不搜索通用名称。
另请参阅
Python_FIND_STRATEGY
。
工件规范¶
3.16 版本加入。
为了解决特殊情况,可以直接通过设置以下变量来指定工件
Python_EXECUTABLE
解释器的路径。
Python_COMPILER
编译器的路径。
Python_DOTNET_LAUNCHER
3.18 版本加入。
.Net
解释器。 仅由IronPython
实现使用。Python_LIBRARY
库的路径。 它将用于计算变量
Python_LIBRARIES
、Python_LIBRARY_DIRS
和Python_RUNTIME_LIBRARY_DIRS
。Python_SABI_LIBRARY
3.26 版本加入。
用于稳定应用二进制接口的库的路径。 它将用于计算变量
Python_SABI_LIBRARIES
、Python_SABI_LIBRARY_DIRS
和Python_RUNTIME_SABI_LIBRARY_DIRS
。Python_INCLUDE_DIR
Python
标头的目录路径。 它将用于计算变量Python_INCLUDE_DIRS
。Python_NumPy_INCLUDE_DIR
NumPy
标头的目录路径。 它将用于计算变量Python_NumPy_INCLUDE_DIRS
。
注意
所有路径都必须是绝对路径。 任何使用相对路径指定的工件都将被忽略。
注意
当指定工件时,所有 HINTS
都将被忽略,并且不会对此工件执行搜索。
如果指定了多个工件,则用户有责任确保各种工件的一致性。
默认情况下,此模块支持在项目的不同目录中使用不同的版本/组件要求进行多次调用,同时为每次调用提供正确且一致的结果。 为了支持此行为,CMake 缓存未使用传统方式,这对于交互式规范来说可能存在问题。 因此,为了也启用交互式规范,可以使用以下变量控制模块行为
Python_ARTIFACTS_INTERACTIVE
3.18 版本加入。
选择模块的行为。 这是一个布尔变量
如果设置为
TRUE
:为上述工件规范变量创建 CMake 缓存条目,以便用户可以交互式地编辑它们。 这会禁用对多个版本/组件要求的支持。如果设置为
FALSE
或未定义:启用多个版本/组件要求。
Python_ARTIFACTS_PREFIX
4.0 版本加入。
定义一个自定义前缀,该前缀将用于定义所有结果变量、目标和命令。 通过使用此变量,此模块支持在同一目录中使用不同的版本/组件要求进行多次调用。 例如,在交叉编译的情况下,需要开发组件,但也可能需要本机 python 解释器
find_package(Python COMPONENTS Development) set(Python_ARTIFACTS_PREFIX "_HOST") find_package(Python COMPONENTS Interpreter) # Here Python_HOST_EXECUTABLE and Python_HOST::Interpreter artifacts are defined
注意
为了与模块的标准行为保持一致,各种标准
_FOUND
变量(即没有自定义前缀)也由每次调用find_package()
命令定义。
命令¶
此模块定义了命令 Python_add_library
(当 CMAKE_ROLE
为 PROJECT
时),该命令具有与 add_library()
相同的语义,并添加对目标 Python::Python
的依赖,或者当库类型为 MODULE
时,添加对目标 Python::Module
或 Python::SABIModule
的依赖(当指定 USE_SABI
选项时),并处理 Python 模块命名规则
Python_add_library (<name> [STATIC | SHARED | MODULE [USE_SABI <version>] [WITH_SOABI]]
<source1> [<source2> ...])
如果未指定库类型,则假定为 MODULE
。
3.17 版本加入: 对于 MODULE
库类型,如果指定了选项 WITH_SOABI
,则模块后缀将包含 Python_SOABI
值(如果有)。
3.26 版本加入: 对于 MODULE
类型,如果指定了选项 USE_SABI
,则将为目标 <name>
指定预处理器定义 Py_LIMITED_API
作为 PRIVATE
,其值从 <version>
参数计算得出。 <version>
的预期格式为 major[.minor]
,其中每个组件都是数值。 如果指定了 minor
组件,则版本应至少为 3.2
,这是引入 稳定应用二进制接口 的版本。 仅指定主版本 3
等效于 3.2
。
当也指定选项 WITH_SOABI
时,模块后缀将包含 Python_SOSABI
值(如果有)。
3.30 版本加入: 对于 MODULE
类型,DEBUG_POSTFIX
目标属性使用 Python_DEBUG_POSTFIX
变量的值(如果已定义)初始化。