FindPython3¶
3.12 版本新增。
查找 Python 3 解释器、编译器和开发环境(包含目录和库)。
3.19 版新增: 当请求版本时,可以将其指定为简单值或范围。有关版本范围使用和功能的详细说明,请参阅 find_package()
命令。
支持以下组件
Interpreter
: 搜索 Python 3 解释器Compiler
: 搜索 Python 3 编译器。仅由 IronPython 提供。Development
: 搜索开发工件(包含目录和库)。3.18 版新增:此组件包含两个子组件,可以独立指定
Development.Module
: 搜索 Python 3 模块开发的工件。Development.Embed
: 搜索 Python 3 嵌入开发的工件。
3.26 版新增
Development.SABIModule
: 搜索使用 稳定应用程序二进制接口 的 Python 3 模块开发的工件。此组件仅适用于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 (Python3 COMPONENTS Interpreter Development)
此模块仅查找 Python 3 版本。此模块可以与 FindPython2
模块同时使用,以使用两个 Python 版本。
如果 Python 版本对您不重要,可以使用 FindPython
模块。
注意
如果同时指定了组件 Interpreter
和 Development
(或其子组件之一),此模块仅搜索与 CMake 配置定义的平台架构相同的解释器。如果仅指定了 Interpreter
组件,则此限制不适用。
导入的目标¶
此模块定义了以下 导入目标
3.14 版更改: 导入目标 仅在 CMAKE_ROLE
为 PROJECT
时创建。
Python3::Interpreter
Python 3 解释器。仅当找到
Interpreter
组件时才定义此目标。Python3::InterpreterDebug
3.30 版本新增。
Python 3 调试解释器。仅当找到
Interpreter
组件并定义了Python3_EXECUTABLE_DEBUG
变量时才定义此目标。此目标仅在Windows
平台上定义。Python3::InterpreterMultiConfig
3.30 版本新增。
Python 3 解释器。解释器的发布或调试版本将根据上下文(平台、配置)使用。仅当找到
Interpreter
组件时才定义此目标Python3::Compiler
Python 3 编译器。仅当找到
Compiler
组件时才定义此目标。Python3::Module
版本 3.15 新增。
Python 模块的 Python 3 库。如果找到组件
Development.Module
,则定义目标。Python3::SABIModule
3.26 版新增。
使用稳定应用程序二进制接口的 Python 模块的 Python 3 库。如果找到组件
Development.SABIModule
,则定义目标。Python3::Python
Python 嵌入的 Python 3 库。如果找到组件
Development.Embed
,则定义目标。Python3::NumPy
3.14 版新增。
Python 3 的 NumPy 库。如果找到组件
NumPy
,则定义目标。
结果变量¶
此模块将在您的项目中设置以下变量(请参阅 标准变量名)
Python3_FOUND
系统具有请求的 Python 3 组件。
Python3_Interpreter_FOUND
系统具有 Python 3 解释器。
Python3_EXECUTABLE
Python 3 解释器的路径。
Python3_EXECUTABLE_DEBUG
3.30 版本新增。
调试 Python 3 解释器的路径。它仅在
Windows
平台上定义。Python3_INTERPRETER
3.30 版本新增。
Python 3 解释器的路径,定义为根据上下文(平台、配置)选择
Python3_EXECUTABLE
或Python3_EXECUTABLE_DEBUG
变量的生成器表达式
。Python3_INTERPRETER_ID
- 一个解释器独有的短字符串。可能的值包括
Python
ActivePython
Anaconda
Canopy
IronPython
PyPy
Python3_STDLIB
标准平台独立安装目录。
由
sysconfig.get_path('stdlib')
返回的信息。Python3_STDARCH
标准平台相关安装目录。
由
sysconfig.get_path('platstdlib')
返回的信息。Python3_SITELIB
第三方平台独立安装目录。
由
sysconfig.get_path('purelib')
返回的信息。Python3_SITEARCH
第三方平台相关安装目录。
由
sysconfig.get_path('platlib')
返回的信息。Python3_SOABI
在 3.17 版本中添加。
模块的扩展后缀。
从
sysconfig.get_config_var('EXT_SUFFIX')
或sysconfig.get_config_var('SOABI')
或python3-config --extension-suffix
计算的信息。Python3_SOSABI
3.26 版新增。
使用稳定应用程序二进制接口的模块的扩展后缀。
如果指定了组件
Interpreter
,则从importlib.machinery.EXTENSION_SUFFIXES
计算的信息。否则,扩展名为abi3
,除了Windows
、MSYS
和CYGWIN
,对于它们,这是一个空字符串。Python3_Compiler_FOUND
系统具有 Python 3 编译器。
Python3_COMPILER
Python 3 编译器的路径。仅由 IronPython 提供。
Python3_COMPILER_ID
- 一个编译器独有的短字符串。可能的值包括
IronPython
Python3_DOTNET_LAUNCHER
在 3.18 版本中新增。
.Net 解释器。仅由
IronPython
实现使用。
Python3_Development_FOUND
系统具有 Python 3 开发工件。
Python3_Development.Module_FOUND
在 3.18 版本中新增。
系统具有用于 Python 模块的 Python 3 开发工件。
Python3_Development.SABIModule_FOUND
3.26 版新增。
系统具有用于使用稳定应用程序二进制接口的 Python 模块的 Python 3 开发工件。
Python3_Development.Embed_FOUND
在 3.18 版本中新增。
系统具有用于 Python 嵌入的 Python 3 开发工件。
Python3_INCLUDE_DIRS
Python 3 包含目录。
Python3_DEFINITIONS
3.30.3 版新增。
Python 3 预处理器定义。
Python3_DEBUG_POSTFIX
3.30 版本新增。
调试 Python 模块的后缀。此变量可用于定义
DEBUG_POSTFIX
目标属性。Python3_LINK_OPTIONS
3.19 版本新增。
Python 3 链接选项。某些配置需要特定的链接选项才能正确构建和执行。
Python3_LIBRARIES
Python 3 库。
Python3_LIBRARY_DIRS
Python 3 库目录。
Python3_RUNTIME_LIBRARY_DIRS
Python 3 运行时库目录。
Python3_SABI_LIBRARIES
3.26 版新增。
用于稳定应用程序二进制接口的 Python 3 库。
Python3_SABI_LIBRARY_DIRS
3.26 版新增。
Python 3
SABI
库目录。Python3_RUNTIME_SABI_LIBRARY_DIRS
3.26 版新增。
Python 3 运行时
SABI
库目录。Python3_VERSION
Python 3 版本。
Python3_VERSION_MAJOR
Python 3 主版本。
Python3_VERSION_MINOR
Python 3 次版本。
Python3_VERSION_PATCH
Python 3 补丁版本。
Python3_PyPy_VERSION
在 3.18 版本中新增。
Python 3 PyPy 版本。
Python3_NumPy_FOUND
3.14 版新增。
系统具有 NumPy。
Python3_NumPy_INCLUDE_DIRS
3.14 版新增。
NumPy 包含目录。
Python3_NumPy_VERSION
3.14 版新增。
NumPy 版本。
提示¶
Python3_ROOT_DIR
定义 Python 3 安装的根目录。
Python3_USE_STATIC_LIBS
如果未定义,则按此顺序搜索共享库和静态库。
如果设置为 TRUE,则 仅 搜索静态库。
如果设置为 FALSE,则 仅 搜索共享库。
注意
此提示在
Windows
上将被忽略,因为此平台上不可用静态库。Python3_FIND_ABI
3.16 版新增。
此变量定义了应搜索的 ABI,如 PEP 3149 中所定义。
Python3_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
,则将搜索除gil_disabled
标志之外的任何 ABI。从这个 4 元组开始,将从最特殊到最一般地搜索各种 ABI。此外,当
pydebug
和gil_disabled
指定ANY
时,debug
和free threaded
版本将在non-debug
和non-gil-disabled
之后搜索。例如,如果我们有
set (Python3_FIND_ABI "ON" "ANY" "ANY" "ON")
以下标志组合将按该顺序附加到工件名称中:
tdmu
、tdm
、tdu
和td
。并搜索任何可能的 ABI
set (Python3_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
分发版。Python3_FIND_STRATEGY
版本 3.15 新增。
此变量定义查找将如何进行。
Python3_FIND_STRATEGY
变量可以设置为以下之一VERSION
: 尝试在所有指定位置中查找最新版本。如果策略CMP0094
未定义或设置为OLD
,则这是默认值。LOCATION
: 一旦找到满足版本约束的版本,立即停止查找。如果策略CMP0094
设置为NEW
,则这是默认值。
另请参阅
Python3_FIND_UNVERSIONED_NAMES
。Python3_FIND_REGISTRY
3.13 版本新增。
在 Windows 上,
Python3_FIND_REGISTRY
变量决定了注册表和环境变量之间的优先级顺序。Python3_FIND_REGISTRY
变量可以设置为以下之一FIRST
: 尝试在环境变量之前使用注册表。这是默认值。LAST
: 尝试在环境变量之后使用注册表。NEVER
: 从不尝试使用注册表。
Python3_FIND_FRAMEWORK
版本 3.15 新增。
在 macOS 上,
Python3_FIND_FRAMEWORK
变量决定了 Apple 风格和 Unix 风格包组件之间的优先级顺序。此变量可以采用与CMAKE_FIND_FRAMEWORK
变量相同的值。注意
不支持值
ONLY
,因此将使用FIRST
代替。如果未定义
Python3_FIND_FRAMEWORK
,则将使用CMAKE_FIND_FRAMEWORK
变量(如果存在)。Python3_FIND_VIRTUALENV
版本 3.15 新增。
此变量定义了由
virtualenv
或conda
管理的虚拟环境的处理方式。它仅在虚拟环境激活时(即已评估activate
脚本时)有意义。在这种情况下,它优先于Python3_FIND_REGISTRY
和CMAKE_FIND_FRAMEWORK
变量。Python3_FIND_VIRTUALENV
变量可以设置为以下之一FIRST
: 虚拟环境优先于任何其他标准路径用于查找解释器。这是默认值。ONLY
: 仅使用虚拟环境查找解释器。STANDARD
: 虚拟环境不用于查找解释器,但始终考虑环境变量PATH
。在这种情况下,变量Python3_FIND_REGISTRY
(Windows) 或CMAKE_FIND_FRAMEWORK
(macOS) 可以设置为值LAST
或NEVER
以优先选择虚拟环境中的解释器。
3.17 版新增: 添加了对
conda
环境的支持。注意
如果请求了组件
Development
(或其子组件之一)但未找到或返回了错误的工件,则同时包含组件Interpreter
可能会有所帮助。Python3_FIND_IMPLEMENTATIONS
在 3.18 版本中新增。
此变量以有序列表的形式定义将搜索的不同实现。
Python3_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 产品,因为(例如,当Python3_FIND_STRATEGY=LOCATION
时)每个位置将首先搜索IronPython
,然后搜索CPython
。注意
当指定
IronPython
时,在Windows
以外的平台上,预计.Net
解释器(即mono
命令)可以通过PATH
变量获得。Python3_FIND_UNVERSIONED_NAMES
在 3.20 版本中添加。
此变量定义通用名称的搜索方式。目前,它仅适用于解释器的通用名称,即
python3
和python
。Python3_FIND_UNVERSIONED_NAMES
变量可以设置为以下值之一FIRST
: 在更专业的名称(例如python3.5
)之前搜索通用名称。LAST
: 在更专业的名称之后搜索通用名称。这是默认值。NEVER
: 完全不搜索通用名称。
另请参阅
Python3_FIND_STRATEGY
。
工件规范¶
3.16 版新增。
为了解决特殊情况,可以通过设置以下变量直接指定工件
Python3_EXECUTABLE
解释器的路径。
Python3_COMPILER
编译器的路径。
Python3_DOTNET_LAUNCHER
在 3.18 版本中新增。
.Net 解释器。仅由
IronPython
实现使用。Python3_LIBRARY
库的路径。它将用于计算变量
Python3_LIBRARIES
、Python3_LIBRARY_DIRS
和Python3_RUNTIME_LIBRARY_DIRS
。Python3_SABI_LIBRARY
3.26 版新增。
稳定应用程序二进制接口的库路径。它将用于计算变量
Python3_SABI_LIBRARIES
、Python3_SABI_LIBRARY_DIRS
和Python3_RUNTIME_SABI_LIBRARY_DIRS
。Python3_INCLUDE_DIR
Python
头文件目录的路径。它将用于计算变量Python3_INCLUDE_DIRS
。Python3_NumPy_INCLUDE_DIR
NumPy
头文件目录的路径。它将用于计算变量Python3_NumPy_INCLUDE_DIRS
。
注意
所有路径必须是绝对路径。任何以相对路径指定的工件都将被忽略。
注意
当指定工件时,所有 HINTS
都将被忽略,并且不会为此工件执行搜索。
如果指定了多个工件,则用户有责任确保各种工件的一致性。
默认情况下,此模块支持在项目的不同目录中使用不同的版本/组件要求进行多次调用,同时为每次调用提供正确且一致的结果。为了支持此行为,CMake 缓存不以传统方式使用,这对于交互式规范可能会有问题。因此,为了也启用交互式规范,可以使用以下变量控制模块行为
Python3_ARTIFACTS_INTERACTIVE
在 3.18 版本中新增。
选择模块的行为。这是一个布尔变量
如果设置为
TRUE
: 为上述工件规范变量创建 CMake 缓存条目,以便用户可以交互式编辑它们。这将禁用对多个版本/组件要求的支持。如果设置为
FALSE
或未定义: 启用多个版本/组件要求。
Python3_ARTIFACTS_PREFIX
4.0 版本新增。
定义一个自定义前缀,它将用于定义所有结果变量、目标和命令。通过使用此变量,此模块支持在同一目录中多次调用,并带有不同的版本/组件要求。例如,在交叉编译的情况下,需要开发组件,但也可能需要本机 Python 解释器
find_package(Python3 COMPONENTS Development) set(Python3_ARTIFACTS_PREFIX "_HOST") find_package(Python3 COMPONENTS Interpreter) # Here Python3_HOST_EXECUTABLE and Python3_HOST::Interpreter artifacts are defined
注意
为了与模块的标准行为保持一致,每次调用
find_package()
命令也会定义各种标准_FOUND
变量(即不带自定义前缀)。
命令¶
此模块定义了命令 Python3_add_library
(当 CMAKE_ROLE
为 PROJECT
时),它与 add_library()
具有相同的语义,并添加了对目标 Python3::Python
的依赖,或者当库类型为 MODULE
时,对目标 Python3::Module
或 Python3::SABIModule
(当指定了 USE_SABI
选项时)的依赖,并处理 Python 模块命名规则
Python3_add_library (<name> [STATIC | SHARED | MODULE [USE_SABI <version>] [WITH_SOABI]]
<source1> [<source2> ...])
如果未指定库类型,则假定为 MODULE
。
3.17 版新增: 对于 MODULE
库类型,如果指定了选项 WITH_SOABI
,则模块后缀将包含 Python3_SOABI
值(如果存在)。
3.26 版新增: 对于 MODULE
类型,如果指定了选项 USE_SABI
,则将 Py_LIMITED_API
预处理器定义指定为 PRIVATE
,用于目标 <name>
,其值根据 <version>
参数计算。 <version>
的预期格式为 major[.minor]
,其中每个组件都是一个数字值。如果指定了 minor
组件,则版本应至少为 3.2
,这是引入 稳定应用程序二进制接口 的版本。仅指定主版本 3
等效于 3.2
。
当同时指定选项 WITH_SOABI
时,模块后缀将包含 Python3_SOSABI
值(如果存在)。
3.30 版新增: 对于 MODULE
类型,如果定义了 Python3_DEBUG_POSTFIX
变量,则 DEBUG_POSTFIX
目标属性将使用其值进行初始化。