maturin 平台支持全景：操作系统、CPU 架构、Python 解释器与 manylinux/musllinux 兼容性指南

开发工具构建工具【免费下载链接】maturinBuild and publish crates with pyo3, cffi and uniffi bindings as well as rust binaries as python packages项目地址https://gitcode.com/gh_mirrors/ma/maturin点击查看免费下载maturin 是一个用于构建和发布 Python 包的构建工具能够将基于 pyo3、cffi、uniffi 绑定的 Rust crate 以及纯 Rust 二进制文件打包为 Python wheel。本文以官方文档 guide/src/platform_support.md 为主线结合仓库源码系统梳理 maturin 支持的操作系统、CPU 架构、Python 解释器版本以及 manylinux / musllinux 兼容策略。读完本文你将掌握 maturin 在哪些平台上可以构建与发布 wheel、不同平台对应的 wheel 平台标签platform tag如何生成、如何为新的操作系统添加支持以及 manylinux 合规检查的底层原理。总体原则平台上限由 rustc 决定maturin 构建在 cargo 与 rustc 之上因此其平台支持能力首先受限于 Rust 编译器的平台支持范围。官方文档明确指出Being built on cargo and rustc, maturin is limited by rusts platform support.这意味着一个平台只有先被 Rust 工具链支持包括 target triple、标准库、链接器等maturin 才有可能在该平台上构建 wheel。从源码结构看这一约束被直接固化在目标平台解析逻辑中Target::from_triple在 src/target/mod.rs 中根据 rustc 报告的 host triple 或用户指定的--target参数解析出操作系统与 CPU 架构并通过get_supported_architectures校验该操作系统架构组合是否在 maturin 的支持清单内不在清单中的组合会直接报错{arch} is not supported on {os}。因此在评估我的平台能否用 maturin 构建 Python 包时第一道门槛是 Rust 官方平台支持矩阵第二道门槛才是 maturin 自身的支持清单。自动化测试覆盖的 CI 平台maturin 的持续集成CI覆盖情况如下GitHub ActionsWindows、macOS、Linux 三个平台均为 64 位 x86 架构Cirrus CIFreeBSD 也有测试覆盖但官方文档提示该测试might get removed at some point可能在未来某个时间点被移除。由于 CI 的维护成本极高官方倾向于将测试面收敛在 GitHub Actions 上的三大主流平台。这意味着Windows、macOS、Linux 三平台是经过 CI 持续回归验证的一等公民其余平台的正确性更多依赖 Rust 工具链与社区反馈。官方发布产物可下载二进制与 wheel 的目标平台maturin 的 Releases 中会构建出两类产物可下载的 maturin 可执行文件以及 maturin 自身作为 Python 包pip install maturin的 wheel。官方文档明确列出的发布目标如下操作系统支持的发布目标Windows32 位 x86i686、64 位 x86x86_64、arm64aarch64Linuxx86i686、x86_64、armv7、aarch64、ppc64lemusl、s390xgnumacOSx86_64、aarch64这与源码中get_supported_architectures在 src/target/mod.rs 的定义一一对应Windows 只发布X86、X86_64、Aarch64三个架构macOS 只发布Aarch64、X86_64两个架构Linux 则覆盖了Aarch64、Armv5teL、Armv6L、Armv7L、Powerpc、Powerpc64、Powerpc64Le、S390X、X86、X86_64、Riscv32、Riscv64、Mips64el、Mips64、Mipsel、Mips、Sparc64、LoongArch64等更宽的架构集合。需要注意的是官方 Release 只覆盖上述发布目标并不代表 maturin 只能在上述平台上运行——见下文其他操作系统。其他操作系统如何让 maturin 支持一个新平台理论上只要 Rust 支持某平台maturin 就应该能够在该平台上构建自身并为其构建 wheel。官方文档给出了为新增操作系统添加支持的明确步骤在 target.rs 中添加该 OS将新操作系统加入Target平台解析逻辑即当前仓库中的 src/target/mod.rs 的Os枚举与from_triple匹配分支必要时扩展标签生成逻辑如果该 OS 的行为与其他 Unix 系统不同需要在PythonInterpreter::get_tag中做相应处理。该函数位于 src/python_interpreter/mod.rs用于生成 PEP 425 格式的 wheel 文件名标签{python tag}-{abi tag}-{platform tag}提交 sysconfig 快照把该平台上python -m sysconfig的输出作为一个文件提交到仓库的sysconfig文件夹中。该文件夹见 sysconfig/Readme.md专门收集各版本、各操作系统下python -m sysconfig的输出因为这些配置在不同版本和操作系统之间差异巨大但对于 wheel 与扩展库的命名至关重要。仓库中已收录如cpython-linux-3.9.txt、cpython-win-mingw64-3.9.txt、pypy-linux-ppc64le-3.9-7.3.txt等数十个快照setup.py 允许放宽默认特性官方文档说明为了pip install能正常工作修改setup.py以停用默认特性deactivate default features是可以接受的避免复杂 workaround新平台不应要求在compile.rs即 src/compile.rs中加入复杂的特殊处理逻辑。从源码结构看maturin 的Os枚举目前已经覆盖了 Linux、Windows、macOS、iOS、FreeBSD、NetBSD、OpenBSD、DragonFly、Solaris、Illumos、Haiku、Emscripten、WASI、AIX、Hurd、Cygwin、Android 等十余种操作系统见 src/target/mod.rs对应的平台标签生成逻辑也已在 src/target/platform_tag.rs 中实现——例如 FreeBSD 生成freebsd_{release}_{machine}格式标签、Emscripten 生成pyemscripten_{year}_{patch}_wasm32PEP 783或回退到旧式emscripten_{emcc_version}_wasm32、AIX 则匹配 CPython_aix_support.aix_platform()生成aix_{ver:x}{rel}{tl:02}_{builddate:04}_{bitsize}格式标签。架构支持与 manylinux 架构对齐官方文档明确所有被 manylinux 项目覆盖的架构——aarch64、armv7l、ppc64le、ppc64、i686、x86_64、s390x——maturin 均支持。同时官方也对是否应该允许 manylinux 都不支持的架构持保留态度Im not sure whether it makes sense to allow architectures that arent even supported by manylinux.从实现看这一对齐体现在两点架构解析Arch枚举src/target/mod.rs覆盖了Aarch64、Armv7L、Powerpc64Le、Powerpc64、X86、X86_64、S390X等 manylinux 支持的架构也包含了Riscv64、LoongArch64、MIPS 系、SPARC 系等更边缘的架构平台标签src/target/platform_tag.rs 中的get_platform_tag为 Linux 目标生成manylinux_{major}_{minor}_{arch}标签及其 legacy 别名如manylinux2014并且只有当别名出现在 PyPI 静态白名单中才会被加入标签集合——例如manylinux2014从未为 riscv64 定义过因此不会为 riscv64 生成该 legacy 别名。此外针对不同架构 maturin 还维护了最低 manylinux 标签的映射get_minimum_manylinux_tagaarch64、armv7l、ppc64、ppc64le、s390x最低为manylinux2014x86与x86_64在 rustc ≥ 1.64.0 时也最低为manylinux2014因为 rustc 1.64.0 将 glibc 最低要求提升到 2.17更早的 rustc 则允许manylinux2010而riscv64、loongarch64分别对应manylinux_2_31、manylinux_2_36。Python 解释器支持CPython、PyPy 与 GraalPy支持的版本范围官方文档对 Python 解释器支持给出了明确声明CPython3.8 到 3.14 受支持并在 CI 上测试整个 3.x 系列理论上都应可用。该范围会随新版本发布、旧版本生命周期结束而调整PyPyPyPy 3.8 及更高版本可用GraalPyGraalPy 23.0 及更高版本可用。从源码看这一范围与 src/python_interpreter/mod.rs 中的常量一致MINIMUM_PYTHON_MINOR 7放宽到 Python 3.7 以覆盖旧版、MAXIMUM_PYTHON_MINOR 14该上限特意放宽以包含预览版本、MINIMUM_PYPY_MINOR 8、MAXIMUM_PYPY_MINOR 11。InterpreterKind枚举定义了CPython、PyPy、GraalPy三种实现类型并支持大小写不敏感的字符串解析cpython、pypy、graalvm/graalpy。不同解释器的 wheel 标签差异maturin 为不同解释器生成不同的 PEP 425 标签详见get_wheel_tagsrc/python_interpreter/mod.rsCPythoninterpreter 标签为cp{major}{minor}ABI 标签为cp{major}{minor}{abiflags}例如cp39-cp39若启用 abi3PEP 384 稳定 ABI则使用通用的abi3标签并附带最低版本号PyPyinterpreter 标签为pp{major}{minor}ABI 标签由EXT_SUFFIX计算得出例如pp311-pypy311_pp73GraalPy与 PyPy 类似GraalPy 的版本也参与 ABI 组成例如graalpy310-graalpy231_310_native。标签生成还会考虑系统平台信息仅当目标是 Windows、非 portable 的 Linux 标签或 Illumos 时才使用sysconfig.get_platform()的结果其余情况使用根据 target 推导的平台标签以避免 macOS deployment target 等复杂因素的干扰。当sys.implementation.name与platform.python_implementation()不一致时如 Pyston则回退到通用标签生成逻辑。Manylinux / Musllinux 兼容策略、命令与审计支持的兼容标准官方文档声明 maturin 支持manylinux2014即manylinux_2_17及其更新版本musllinux_1_1及其更新版本。在 src/auditwheel/platform_tag.rs 中PlatformTag::is_supported的判断正是manylinux的(major, minor) (2, 17)、musllinux始终为 true。manylinux2014的字符串解析同时接受2014、manylinux2014、manylinux_2_17等形式。兼容策略数据policy JSONmanylinux/musllinux 合规检查的底层依据是两份策略 JSONsrc/auditwheel/manylinux-policy.json定义linux、manylinux_2_5别名manylinux1、manylinux_2_12别名manylinux2010、manylinux_2_17别名manylinux2014等策略每个策略按优先级priority排序并包含各架构允许的符号版本如GLIBC、GLIBCXX、CXXABI、LIBATOMIC、ZLIB、白名单库lib_whitelist如libc.so.6、libgcc_s.so.1、libstdc.so.6以及黑名单符号src/auditwheel/musllinux-policy.json定义musllinux_1_1、musllinux_1_2等策略。在 src/auditwheel/policy.rs 中两份 JSON 被编译期内联加载为MANYLINUX_POLICIES与MUSLLINUX_POLICIES并按 priority 从高到低排序。musllinux 还有一个特殊修复逻辑fixup_musl_libc_so_name由于不同架构上 musl libc 的 SONAME 不同如 aarch64 为libc.musl-aarch64.so.1、x86_64 为libc.musl-x86_64.so.1策略中的通用libc.so会被替换为对应架构的 SONAME。这与官方文档中Linux 发布目标包含 ppc64lemusl的声明相互印证。通过命令行控制兼容性maturin 通过--compatibility别名--manylinux命令行参数控制平台标签与 PyPI 兼容性定义见 src/build_options.rspypi适用于所有平台确保只使用能够上传到 PyPI 的标签manylinux系列如manylinux2014/manylinux_2_24musllinux系列如musllinux_1_2linux使用原生 Linux 标签但此类 wheel 会被 PyPI 拒绝除非另行通过 auditwheel 校验默认值最低兼容的 manylinux 标签若没有匹配则回退到linux。此外--auditwheel用于启用 manylinux 合规审计--zig需安装pip install maturin[zig]可使用 zig 链接器确保 manylinux 合规。注意manylinux1和manylinux2010不受 Rust 编译器支持rustc 1.64.0 起 glibc 最低要求为 2.17因此实际上限以manylinux2014为起点这与策略中is_supported的判断一致。合规审计的验证测试仓库中的测试脚本直观展示了合规性的验证方式tests/manylinux_compliant.sh在 CI 的 manylinux 镜像中遍历/opt/python/cp3[89]*/bin下的各 Python 版本对test-crates/pyo3-mixed执行maturin build --manylinux tag验证合规构建能够成功tests/manylinux_incompliant.sh反向验证两类失败场景——在 manylinux_2_28 环境下试图构建--manylinux 2010因 glibc 版本不满足而必须失败以及链接了带黑名单符号如 zlib 的gzflags的lib_with_disallowed_lib测试 crate 时构建--manylinux 2014必须失败。这两份脚本表明maturin 的 manylinux 兼容性不仅是打标签还会在构建产物层面审计所链接库的符号版本与白名单不满足策略的 wheel 会被直接拒绝。版本策略manylinux 版本号升级方式由于 Rust 与 manylinux 项目有时会停止支持旧的 manylinux/musllinux 版本官方文档明确了版本号策略after maturin 1.0 manylinux version bumps will be minor versions rather than major versions.即 maturin 1.0 之后若因上游Rust、manylinux 项目放弃旧版本而导致最低支持版本上移这类变更将通过 minor 版本号次版本发布而不是 major 版本号主版本发布——以降低对用户的破坏性影响。该策略同样适用于 musllinux 的最低版本。小结如何判断你的平台能否使用 maturin综合官方文档与源码实现判断一个平台是否可用的快速路径如下先查 Rust 平台支持目标平台是否在 Rust 官方支持矩阵中且有对应的 target triple再查 maturin 的 OS 支持清单对应操作系统是否出现在 src/target/mod.rs 的Os枚举与get_supported_architectures中核对架构与标签架构是否在Arch枚举内且 src/target/platform_tag.rs 是否能为该OS架构组合生成平台标签核对 Python 版本CPython 3.8–3.14整个 3.x 可用、PyPy 3.8、GraalPy 23.0核对 Linux libc 策略manylinux2014manylinux_2_17及以上、musllinux_1_1 及以上且构建产物需通过符号白名单审计。满足上述条件后即可通过maturin build --compatibility tag构建对应平台标签的 wheel或通过--target triple进行交叉编译。对于官方尚未收录的新平台可参照其他操作系统一节中的步骤向项目贡献支持其中最关键的一步是提交该平台python -m sysconfig的输出到sysconfig目录为后续 wheel 命名提供依据。赞分享开发工具构建工具【免费下载链接】maturinBuild and publish crates with pyo3, cffi and uniffi bindings as well as rust binaries as python packages项目地址https://gitcode.com/gh_mirrors/ma/maturin点击查看免费下载相关推荐SSL4MIS10分钟快速上手指南 - 医学图像半监督分割入门SSL4MIS10分钟快速上手指南 医学图像半监督分割入门 SSL4MISSemi Supervised Learning for Medical Imag人工智能机器学习深度学习计算机视觉医疗健康sqlc跨平台兼容性支持多种操作系统和架构的终极指南sqlc跨平台兼容性支持多种操作系统和架构的终极指南 sqlc是一款能从SQL生成类型安全代码的强大工具它的跨平台兼容性让开发者可以在各种操作系统和架构上无开发工具代码生成数据库Ouroboros 平台支持全解操作系统、Python 版本与运行时后端的兼容性指南Ouroboros 平台支持全解操作系统、Python 版本与运行时后端的兼容性指南 OuroborosAgent OS是一个以规范Seed驱动、具备AI Agent人工智能代码智能体Agent 编排AI 评测CLI开发工具上一篇突破AI心理陪伴技术壁垒efaqa-corpus-zh如何重塑中文心理咨询数据生态下一篇GHelper深度解析华硕笔记本轻量级控制工具的终极实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考