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
。
4.1 版本更改:在交叉编译模式下(即 CMAKE_CROSSCOMPILING
变量定义为 true),当策略 CMP0190
设置为 NEW
时,以下约束适用于请求的组件
Interpreter
或Compiler
单独:将搜索主机工件。Interpreter
或Compiler
与Development
或任何子组件:将搜索目标工件。在这种情况下,必须定义CMAKE_CROSSCOMPILING_EMULATOR
变量,并将其用于执行解释器或编译器。
当需要主机和目标工件时,应两次调用 find_package()
命令。在这种情况下,Python_ARTIFACTS_PREFIX
变量可能会有所帮助。
为确保组件 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 解释器的路径,定义为
生成器表达式
,根据上下文(平台、配置)选择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 开始,搜索各种 ABI,直到最通用的 ABI。此外,当为
pydebug
和gil_disabled
指定ANY
时,将在非调试
和非 gil 禁用
版本之后搜索调试
和自由线程
版本。例如,如果我们有
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
语言在 动态语言运行时 (DLR
) 之上实现.NET Framework
。请参阅 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
注意
为了与模块的标准行为保持一致,每次调用
find_package()
命令时,还会定义各种标准_FOUND
变量(即不带自定义前缀)。
命令¶
此模块定义了命令 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
变量的值进行初始化(如果已定义)。