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
。
为了确保组件 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 版本。
使用稳定应用程序二进制接口的模块的扩展名后缀。
如果指定了 COMPONENT
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
,则将搜索任何 ABI,但不包括gil_disabled
标志。从这个 4 元组中,将搜索各种 ABI,从最专门的到最一般的。此外,当为
pydebug
和gil_disabled
指定ANY
时,将在non-debug
和non-gil-disabled
版本之后搜索debug
和free threaded
版本。例如,如果我们有
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
翻译工具链来生成 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
都将被忽略,并且不会为此工件执行搜索。
如果指定了多个工件,则用户有责任确保各种工件的一致性。
默认情况下,此模块支持在项目的不同目录中进行多次调用,并具有不同的版本/组件要求...变量
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
注意
为了与模块的标准行为保持一致,各种标准
_FOUND
变量(即,没有自定义前缀)也由每次调用find_package()
命令定义。
命令¶
此模块定义了命令 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
,则将为目标 <name>
指定预处理器定义 Py_LIMITED_API
,作为 PRIVATE
,其值从 <version>
参数计算得出。 <version>
的预期格式为 major[.minor]
,其中每个组件都是一个数值。如果指定了 minor
组件,则版本应至少为 3.2
,这是引入 稳定应用程序二进制接口 的版本。仅指定主版本 3
等效于 3.2
。
当也指定选项 WITH_SOABI
时,模块后缀将包含 Python3_SOSABI
值(如果有)。
版本 3.30 新增:对于 MODULE
类型,DEBUG_POSTFIX
目标属性使用 Python3_DEBUG_POSTFIX
变量的值初始化(如果已定义)。