FindPython3

在 3.12 版本中添加。

查找 Python 3 解释器、编译器和开发环境（包括目录和库）。

在 3.19 版本中添加： 当指定版本时，可以指定为一个简单的值或一个范围。有关版本范围使用和功能的详细说明，请参阅 find_package() 命令。

支持以下组件

  • 解释器：搜索 Python 3 解释器

  • 编译器：搜索 Python 3 编译器。仅 IronPython 提供。

  • 开发：搜索开发组件（包括目录和库）。

    在 3.18 版本中添加： 此组件包括两个可以独立指定的子组件

    • 开发.模块：搜索 Python 3 模块开发的组件。

    • 开发.嵌入：搜索 Python 3 嵌入开发的组件。

    在 3.26 版本中添加

  • NumPy：搜索 NumPy 包含目录。

在 3.14 版本中添加： 添加了 NumPy 组件。

如果未指定 组件，则假设为 解释器。

如果指定 开发 组件，则表示子组件 开发.模块 和 开发.嵌入。

要确保组件 解释器、编译器、开发（或其子组件之一）和 NumPy 之间的版本一致，请同时指定所有组件

find_package (Python3 COMPONENTS Interpreter Development)

此模块仅搜索 Python 3 版本。此模块可与 FindPython2 模块并行使用，以同时使用两个 Python 版本。

如果 Python 版本对您无关紧要，则可以使用 FindPython 模块。

注意

如果同时指定组件 解释器 和 开发（或其子组件之一），则此模块只会搜索与 CMake 配置定义的平台架构相同的解释器。如果仅指定 解释器 组件，则此限制不适用。

导入目标

该模块定义了以下 导入目标

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_SITEARCH

与平台无关的非标准的安装目录。

由 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 include 目录。

Python3_DEFINITIONS

3.30.3 版本新增。

Python 3 预处理器定义。

Python3_DEBUG_POSTFIX

调试 Python 模块的后缀。此变量可以用来定义 DEBUG_POSTFIX target 属性。

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 include 目录。

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。而且，当 ANY 指定给 pydebug 和 gil_disabled 时，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 时，仅当每个标志的值除第四个（gil_disabled）外均为 OFF 或 ANY 时，才能找到 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 first 和 CPython in second，基于 CPython 的 Python 产品也可以被选中，例如使用 Python3_FIND_STRATEGY=LOCATION，每个位置首先搜索 IronPython，然后搜索 CPython。

注意

当在除 Windows 之外的其他平台上指定 IronPython 时，希望通过 PATH 变量获得 .Net 解释器（即 mono 命令）。

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 版本中添加。

指向稳定应用程序二进制接口 (SABI) 的库的路径。它将用于计算变量 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_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，这是引入了 Stable Application Binary Interface 的版本。仅指定主版本 3 等同于 3.2。

如果也指定了选项 WITH_SOABI，则模块后缀将包含 Python3_SOSABI 值（如果有）。

已在版本 3.30 中添加： 对于 MODULE 类型，如果定义了变量 Python3_DEBUG_POSTFIX，则目标属性 DEBUG_POSTFIX 将采用其值初始化。