查找Python3

在 3.12 版本加入.

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

在 3.19 版本加入: 请求版本时，可以将其指定为简单值或范围。有关版本范围用法和功能的详细说明，请参阅:command:find_package 命令。

支持以下组件：

• Interpreter：搜索 Python 3 解释器

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

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

  在 3.18 版本加入: 该组件包括两个可以独立指定的子组件：

  • Development.Module：搜索用于 Python 3 模块开发的工件。

  • Development.Embed：搜索用于 Python 3 嵌入开发的工件。

  在 3.26 版本加入:

  • Development.SABIModule：使用 Stable Application Binary Interface 搜索用于 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 组件，则此约束不适用。

进口目标

此模块定义以下:ref:Imported Targets <Imported Targets>：

在 3.14 版本发生变更: Imported Targets 仅在 CMAKE_ROLE 为 PROJECT 时创建。

Python3::解释器

Python 3 解释器。如果找到组件“解释器”，则定义目标。

Python3::编译器

Python 3 编译器。如果找到组件“Compiler”，则定义目标。

Python3::模块

在 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_INTERPRETER_ID

解释器独有的短字符串。可能的值包括：

• Python

• ActivePython

• 蟒蛇

• 雨棚

• 铁蟒

• PyPy

Python3_STDLIB

标准平台独立安装目录。

distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=True) 或 sysconfig.get_path('stdlib') 返回的信息。

Python3_STDARCH

标准平台相关安装目录。

distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=True) 或 sysconfig.get_path('platstdlib') 返回的信息。

Python3_SITELIB

第三方平台独立安装目录。

distutils.sysconfig.get_python_lib(plat_specific=False,standard_lib=False) 或 sysconfig.get_path('purelib') 返回的信息。

Python3_SITEARCH

第三方平台依赖安装目录。

distutils.sysconfig.get_python_lib(plat_specific=True,standard_lib=False) 或 sysconfig.get_path('platlib') 返回的信息。

Python3_SOABI

在 3.17 版本加入.

模块的扩展后缀。

从``distutils.sysconfig.get_config_var('EXT_SUFFIX')`` 或``distutils.sysconfig.get_config_var('SOABI')`` 或``python3-config --extension-suffix`` 计算的信息。如果包 distutils.sysconfig 不可用，则使用 sysconfig.get_config_var('EXT_SUFFIX') 或 sysconfig.get_config_var('SOABI')。

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

编译器独有的短字符串。可能的值包括：

• 铁蟒

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_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，将搜索任何 ABI。

Python3_FIND_ABI 变量是一个三元组，按顺序指定 pydebug (d)、pymalloc (m) 和 unicode ( u) 标志。每个元素都可以设置为以下之一：

• ON：选择相应的标志。

• OFF：未选择相应标志。

• ANY：将搜索两种可能性（ON 和``OFF``）。

从这个 3 元组开始，将搜索各种 ABI，从最专业到最通用。此外，“调试”版本将在**“非调试”版本之后搜索。

例如，如果我们有：

set (Python3_FIND_ABI "ON" "ANY" "ANY")

以下标志组合将按顺序附加到工件名称：dmu、dm、du 和 d。

并搜索任何可能的 ABI:

set (Python3_FIND_ABI "ANY" "ANY" "ANY")

以下组合将按顺序使用：mu、m、u、<empty>、dmu、dm、 du 和 d。

备注

此提示仅在 POSIX 系统上有用。因此，在 Windows 系统上，当定义 Python3_FIND_ABI 时，只有当值每个标志都是 OFF 或 ANY。

Python3_FIND_STRATEGY

在 3.15 版本加入.

此变量定义如何完成查找。 Python3_FIND_STRATEGY 变量可以设置为以下之一：

• VERSION：尝试在所有指定位置找到最新版本。如果策略 CMP0094 未定义或设置为“旧”，则这是默认设置。

• LOCATION：一旦找到满足版本约束的版本就停止查找。如果策略 CMP0094 设置为 NEW，则这是默认设置。

Python3_FIND_REGISTRY

在 3.13 版本加入.

在 Windows 上，Python3_FIND_REGISTRY 变量确定注册表和环境变量之间的优先顺序。 Python3_FIND_REGISTRY 变量可以设置为以下之一：

• FIRST：尝试在环境变量之前使用注册表。这是默认设置。

• LAST：尝试在环境变量之后使用注册表。

• 从不：永远不要尝试使用注册表。

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：此实现在`动态语言运行时`（DLR）之上使用``CSharp``语言用于``.NET Framework``。请参阅`IronPython <https://ironpython.net>`_。

• PyPy：此实现使用``RPython`` 语言和``RPython 翻译工具链`` 来生成 python 解释器。请参阅`PyPy <https://www.pypy.org>`_。

默认值为：

• 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：根本不搜索通用名称。

工件规格

在 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。

备注

所有路径都必须是绝对路径。将忽略使用相对路径指定的任何工件。

备注

指定工件时，将忽略所有“提示”，并且不会对该工件执行任何搜索。

如果指定了多个工件，则用户有责任确保各种工件的一致性。

默认情况下，此模块支持在具有不同版本/组件要求的项目的不同目录中进行多次调用，同时为每次调用提供正确且一致的结果。为了支持这种行为，CMake 缓存没有以传统方式使用，这对于交互式规范来说可能是有问题的。因此，为了启用交互式规范，可以使用以下变量控制模块行为：

Python3_ARTIFACTS_INTERACTIVE

在 3.18 版本加入.

选择模块的行为。这是一个布尔变量：

• 如果设置为“TRUE”：为上述工件规范变量创建 CMake 缓存条目，以便用户可以交互式编辑它们。这将禁用对多个版本/组件要求的支持。

• 如果设置为“FALSE”或未定义：启用多个版本/组件要求。

命令

此模块定义命令 Python3_add_library``（当 :prop_gbl:`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，这是 Stable Application Binary Interface 被引入。仅指定主要版本 3 等同于 3.2。

当还指定选项 WITH_SOABI 时，模块后缀将包含 Python3_SOSABI 值（如果有）。