概述

构建工具将通过读取源代码树根目录下的 pypa.json 文件来定位。该文件描述了如何获取构建工具以及调用该工具的命令名称。

所有工具都应遵循一个模仿 pip 当前使用 setuptools setup.py 接口的单一命令行接口。

pypa.json

文件 pypa.json 作为 pip 和其他想要构建源代码树的工具的通用配置文件，用于咨询配置。Python 源代码树中缺少 pypa.json 文件意味着使用 setuptools 或兼容 setuptools 的构建系统。

JSON 具有以下模式。额外的键将被忽略，这允许使用 pypa.json 作为其他相关工具的配置文件。如果是这样做，则选择的键必须在 tools 下进行命名空间隔离。

{"tools": {"flit": ["Flits content here"]}}

schema

模式的版本。本 PEP 定义版本“1”。如果不存在，则默认为“1”。所有读取文件的工具都必须在遇到无法识别的模式版本时报错。

bootstrap_requires

可选的 PEP 508 依赖项规范列表，必须在运行构建工具之前安装。例如，如果使用 flit，那么依赖项可能是：

bootstrap_requires: ["flit"]

build_command

一个强制性的键，这是一个描述要运行的命令的 Python 格式字符串 [8] 列表。例如，如果使用 flit，那么构建命令可能是：

build_command: ["flit"]

如果使用一个可运行模块 fred 作为命令

build_command: ["{PYTHON}", "-m", "fred"]

进程接口

要运行的命令由一个简单的 Python 格式字符串 [8] 定义。

这允许拥有专用脚本的构建系统以及通过“python -m somemodule”调用的构建系统。

进程将以源代码树根目录作为当前工作目录运行。

运行时，进程不应从 stdin 读取 - 虽然 pip 当前运行构建系统时 stdin 连接到其自身的 stdin、stdout 和 stderr，但 stdout 和 stderr 被重定向，无法与用户进行任何通信。

与进程一贯的做法一样，非零退出状态表示错误。

可用的格式变量

PYTHON

正在使用的 Python 解释器。这对于调用仅仅是 Python 入口点的东西很重要。

{PYTHON} -m foo

可用的环境变量

这些变量由构建系统的调用者设置，并且始终可用。

PATH

标准的系统路径。

PYTHON

与格式变量相同。

PYTHONPATH

用于根据正常的 Python 机制控制 sys.path。

子命令

构建系统必须支持一些单独的子命令。下面的示例使用 flit 作为 build_command 以便说明。

build_requires

查询构建依赖项。构建依赖项以 UTF-8 编码的 JSON 文档返回，其中有一个键 build_requires，包含一个 PEP 508 依赖项规范列表。其他键将被忽略。build_requires 命令是唯一在不设置构建环境的情况下运行的命令。

示例命令

flit build_requires

metadata

查询项目元数据。元数据（仅元数据）应以 UTF-8 编码输出到 stdout。pip 将仅运行一次 metadata 命令，以确定需要下载和安装哪些其他包。元数据按照 PEP 427 以 wheel METADATA 文件的形式输出。

请注意，metadata 命令生成的元数据以及生成的 wheel 中的元数据必须相同。

示例命令

flit metadata

wheel -d OUTPUT_DIR

用于构建项目 wheel 的命令。OUTPUT_DIR 将指向一个现有的目录，wheel 将在此目录中输出。Stdout 和 stderr 没有语义意义。应该只输出一个文件 - 如果输出更多文件，pip 将选择一个任意文件进行消耗。

示例命令

flit wheel -d /tmp/pip-build_1234

develop [–prefix PREFIX]

用于对项目进行就地“开发”安装的命令。Stdout 和 stderr 没有语义意义。

并非所有构建系统都能执行开发安装。如果构建系统无法执行开发安装，则在运行时应报错。请注意，这样做会导致像 pip install -e foo 这样的操作失败。

prefix 选项用于定义安装的替代前缀。虽然 setuptools 有 --root 和 --user 选项，但它们可以通过 --prefix 等效地实现，而接受 --root 或 --user 选项的 pip 或其他工具应进行适当的转换。

root 选项用于定义命令应在其操作的替代根目录。

例如

flit develop --root /tmp/ --prefix /usr/local

应该在 /tmp/usr/local/bin 内安装脚本，即使正在使用的 Python 环境报告 sys.prefix 为 /usr/，这将导致使用 /tmp/usr/bin/。类似的逻辑也适用于包文件等。

构建环境

除了 build_requires 命令之外，所有命令都在构建环境中运行。不要求特定的实现，但构建环境必须满足以下要求。

1. 项目 build_requires 指定的所有依赖项必须可以从 $PYTHON 中导入。

1. 由构建依赖包提供的所有命令行脚本必须存在于 $PATH 中。

由此得出，构建系统不能假定可以访问任何未声明为 build_requires 或在 Python 标准库中的 Python 包。

隔离构建

本规范不规定构建是否应该是隔离的。现有的构建工具（如 setuptools）将使用已安装的构建时依赖项（例如 setuptools_scm），并且仅在版本冲突或依赖项缺失时才安装其他版本。然而，通过始终隔离构建并仅使用指定的依赖项，很可能会获得更好的一致性。

然而，这其中存在一些细微的问题——例如，用户如何强制避免一个满足某些包依赖项但存在问题的构建依赖项版本。未来的 PEP 可能会解决这个问题，但目前不在范围内——它不影响协调构建系统和需要进行构建的实体之间所需的元数据，因此不是 PEP 的范畴。

升级

‘pypa.json’ 进行了版本化，以允许未来的更改而无需兼容性。

在新 PEP 中升级任一模式的顺序将是：

1. 发布新的 PEP，定义更新的模式。如果模式不是完全向后兼容的，则必须定义一个新的版本号。
2. 消费者（例如 pip）实现对新模式版本的支持。
3. 当包作者乐于引入对引入了新模式版本支持的“pip”（以及其他可能的消费者）版本的依赖时，他们可以选择采用新模式。

本 PEP 的初始部署将经历相同的过程：能够使用本 PEP 而无需 setuptools 包装器 的能力，将在很大程度上取决于第一个支持它的 pip 版本的采用率。

sdist 中的静态元数据

本 PEP 不处理当前无法信任 sdist 中静态元数据的问题。这是一个独立于识别和消费源代码树中使用的构建系统的问题，无论它来自 sdist 还是其他来源。

编译器选项的处理

不同编译器选项的处理超出了本规范的范围。

pip 当前通过将用户提供的字符串附加到其运行时命令上来处理编译器选项，当运行 setuptools 时。这种方法足以与本 PEP 中定义的构建系统接口配合使用，但有一个例外：随着不同构建系统的发展，全局指定的选项将不再全局生效。这个问题可以在 pip（或 conda 或其他安装程序）中解决，而不会影响互操作性。

从长远来看，wheel 应该能够表达用一个编译器或选项与另一个编译器或选项构建的 wheel 之间的区别，这属于 PEP 的范畴。

网络效应

采用非 setuptools 兼容构建系统的项目——即没有 setup.py，或者 setup.py 不接受现有工具尝试使用的命令——将无法被这些现有工具安装。

当这些项目被其他项目使用时，这种影响将级联。

特别是，由于 pip 当前不支持 setup-requires，任何采用非 setuptools 兼容构建系统并被第二个项目（B）作为 setup-requirement 使用的项目（A），而项目 B 本身尚未迁移到拥有 pypa.json，那么 B 将无法被任何版本的 pip 安装。这是因为在 pip 运行 B 的 ‘setup.py egg_info’ 时会触发 easy-install，而 easy-install 会尝试安装 A 但会失败。

因此，我们建议目前被用作 setup-requires 的工具，要么确保它们保留一个 setuptools 包装器，要么找到它们的消费者并让它们在自身迁移到使用 pypa.json 之前全部升级。实际上这是不可能的，因此建议无限期地保留一个 setuptools 包装器——无论是对于 pbr、setuptools_scm 等项目，还是像 numpy 这样的项目。

setuptools 包装器

可以编写一个通用的 setuptools 包装器，它看起来像 setup.py，并在底层使用 pypa.json 来驱动构建。这对 pip 使用该系统不是必需的，但它将允许包作者使用新功能，同时仍然与旧版本的 pip 保持兼容。