cibuildwheel项目中的非默认构建标识符管理方案

在Python生态系统的持续集成和构建工具cibuildwheel中，开发团队正在讨论如何更好地管理非默认构建选项。当前项目中已经存在一些特殊的构建配置需求，如自由线程构建（free-threaded build）需要特殊设置，而未来可能还会有更多类似需求（如GraalPy支持、旧版PyPy支持等）。

现有问题分析

目前cibuildwheel已经积累了多种构建选择机制：

• 平台选择（platform）
• 架构选择（arch）
• 构建包含/跳过（build/skip）
• Python版本要求（requires-python）
• 自由线程支持（free-threaded-support）
• 预发布Python版本（prerelease-pythons）

这种分散的配置方式不仅增加了用户的学习成本，也使得项目维护变得复杂。特别是当需要支持更多特殊构建类型时，这种问题会愈发明显。

提出的解决方案

团队提出了一个统一的"enable"配置选项，通过一个列表来管理所有非默认构建类型：

[tool.cibuildwheel]
enable = ["cpython-freethreading", "graalpy", "pypy", "cpython-prerelease"]

对应的环境变量格式为：

CIBW_ENABLE: "cpython-freethreading graalpy pypy cpython-prerelease"

关键设计决策

1. 命名规范：

   • 采用"cpython-"前缀明确区分不同Python实现
   • 使用"freethreading"而非"free-threaded"以保持一致性
   • 保持选项名称简洁且具有描述性

2. 向后兼容：

   • 计划将现有选项（如free-threaded-support）迁移到新系统
   • 考虑在过渡期提供警告信息
   • 最终移除旧的独立配置选项

3. 特殊构建类型处理：

   • PyPy构建将全部设为可选（opt-in）
   • GraalPy支持将通过此机制实现
   • 预发布Python版本管理纳入统一系统

4. 未来扩展性：

   • 保留添加否定选项（如"!cpython-freethreading"）的可能性
   • 为可能的新Python实现或构建变体预留空间

技术实现考量

1. 与现有机制的交互：

   • 新系统将与requires-python机制协同工作
   • 保持与build/skip选项的逻辑一致性
   • 确保环境变量和pyproject.toml配置的等效性

2. 默认值策略：

   • 大多数项目不需要的特殊构建默认禁用
   • 常见场景（如标准CPython构建）保持零配置可用
   • 通过合理默认值降低用户配置负担

3. 错误处理：

   • 对冲突配置提供明确错误信息
   • 对即将废弃的旧选项提供迁移指引
   • 对可能的问题场景（如未设置requires-python）提供警告

社区影响评估

这一变更将影响：

1. 需要特殊构建类型的项目维护者
2. 希望禁用某些构建变体的用户
3. 工具链维护者和下游项目

通过这种统一的管理方式，cibuildwheel将能够：

• 更清晰地表达构建选项
• 简化未来功能的添加
• 提供更一致的配置体验
• 降低新用户的学习曲线

该方案目前仍在讨论中，团队正在收集反馈以完善设计细节。对于Python打包生态系统的参与者来说，理解这一发展方向将有助于提前规划项目配置策略。