Setuptools-rust版本迁移指南：从setup.py到pyproject.toml的现代化配置

Setuptools-rust版本迁移指南从setup.py到pyproject.toml的现代化配置【免费下载链接】setuptools-rustSetuptools plugin for Rust support项目地址: https://gitcode.com/gh_mirrors/se/setuptools-rustsetuptools-rust 是 Python 生态中连接 Rust 与 setuptools 的关键桥梁它让开发者能用 PyO3 编写高性能扩展模块并像发布普通 Python 包一样轻松构建和分发。本篇文章将为你提供一份完整的 setuptools-rust 版本迁移指南重点讲解如何把传统setup.py中的配置迁移到pyproject.toml完成现代化配置改造让新手也能快速上手、少踩坑。为什么要从 setup.py 迁移到 pyproject.toml在 PEP 517/518 成为标准之后pyproject.toml已成为 Python 打包的事实标准配置文件。对于 setuptools-rust 项目来说迁移至少有三大好处构建声明统一构建依赖、项目元数据、Rust 扩展配置全部集中在一个文件里无需再写 Python 代码。环境更干净不再需要执行setup.py里的任意 Python 逻辑构建流程更可复现、更安全。兼容未来工具链新版 pip、setuptools 对pyproject.toml的支持日趋完善旧式setup.py声明逐渐成为历史包袱。在 setuptools-rust 项目中旧配置的核心是 setup.py 中的RustExtension类而新配置的核心是pyproject.toml中的[[tool.setuptools-rust.ext-modules]]表格。两者的对应关系非常直观下文将逐行演示。新旧配置对比一眼看懂差异旧方式setup.py 中声明 RustExtension传统写法依赖setuptools_rust包中的RustExtension与Binding例如项目中的 setup.py 示例from setuptools import find_packages, setup from setuptools_rust import Binding, RustExtension setup( namehello-world, version1.0, packagesfind_packages(wherepython), package_dir{: python}, rust_extensions[ RustExtension( hello_world._lib, pathCargo.toml, bindingBinding.PyO3, ) ], )这种写法有两大痛点一是rust_extensions只能通过 Python 代码构造配置与逻辑耦合二是构建时 setuptools-rust 需要借助 setuptools_ext.py 中的add_rust_extension函数做大量 monkey-patch动态替换 setuptools 内部命令类行为隐晦且难以调试。新方式pyproject.toml 声明扩展模块迁移后的等效配置参考 pyproject.toml[build-system] requires [setuptools, setuptools-rust] build-backend setuptools.build_meta [project] name hello-world version 1.0 [tool.setuptools.packages] find { where [python] } [[tool.setuptools-rust.ext-modules]] target hello_world._lib binding PyO3可以看到原来RustExtension(hello_world._lib, bindingBinding.PyO3)中的参数现在变成了 TOML 表格里的键值对一一对应、无需再写任何 Python 代码。一步步完成迁移最快配置方法第一步准备 pyproject.toml 骨架新建或重写pyproject.toml先声明构建后端[build-system] requires [setuptools, setuptools-rust] build-backend setuptools.build_meta其中requires里必须包含setuptools-rust它是构建 Rust 扩展的插件本体build-backend指定使用 setuptools 的 PEP 517 后端。第二步迁移包与元数据配置把setup.py中的packagesfind_packages(wherepython)和package_dir{: python}迁移为[tool.setuptools.packages][tool.setuptools.packages] find { where [python] }项目名称、版本号等元数据放入[project]表[project] name hello-world version 1.0第三步迁移 Rust 扩展模块RustExtension的每个参数在 TOML 中都有对应键只需把下划线_换成短横线-例如rust_version→rust-version。核心映射关系如下setup.py 参数pyproject.toml 键说明第一个位置参数target扩展模块的 Python 全限定名pathpathCargo.toml 清单文件路径默认即Cargo.tomlbindingbinding绑定类型如PyO3、RustCPythonfeaturesfeatures传给 Cargo 的--featuresargsargs额外的 Cargo 参数列表rust_versionrust-version最低 Rust 编译器版本参考setuptools-rust源码 setuptools_ext.py 中的_create函数它会把 pyproject.toml 里带短横线的键自动转换回 Python 参数名再实例化RustExtension或RustBin。因此所有RustExtension支持的参数都能原样迁移只是命名规则从 snake_case 变成 kebab-case。第四步迁移 Rust 可执行程序bins如果你的项目还要分发 Rust 写的命令行工具旧写法使用Binding.Exec新写法更推荐使用[[tool.setuptools-rust.bins]]表格。参考 hello-world-script 示例[[tool.setuptools-rust.bins]] target hello-world-script args [--profile, release-lto]target必须与Cargo.toml中[bin]的name一致这样生成的 wheel 会把可执行文件安装到虚拟环境的 bin 目录。迁移后的常见问题与避坑技巧别忘了 MANIFEST.in从源码分发包sdist构建时必须让 Rust 源文件一起被打包。请在项目根目录添加MANIFEST.ininclude Cargo.toml recursive-include rust *.rs多个扩展模块的注意事项每个Cargo.toml只允许一个[lib]表。如果需要多个 Rust 扩展模块要么编写多个Cargo.toml清单文件要么在pyproject.toml里并列声明多个[[tool.setuptools-rust.ext-modules]]表格。调试构建覆盖默认 profilesetuptools-rust 默认以 release 模式构建。开发调试阶段可用环境变量切换到 debug 构建速度更快、报错信息更友好export SETUPTOOLS_RUST_CARGO_PROFILEdev该环境变量的实现位于 rustc_info.py 与相关构建逻辑中直接覆盖 Cargo 的 profile 选择。命令行脚本的两种选择除了 Rust 二进制你也可以使用纯 Python 入口点entry-point调用 Rust 实现参考 hello-world 示例 中的[project.scripts]。这种方式生成的 wheel 更小安装更快适合功能简单的 CLI。迁移验证清单完成迁移后用下面几步快速验证配置是否正确python -m pip install -e .可编辑安装成功import扩展模块无报错。python -m build能生成 wheel 与 sdist且 sdist 中包含 Cargo.toml 和.rs源文件。在全新虚拟环境中pip install生成的 wheelRust 扩展可正常导入。小结从setup.py迁移到pyproject.toml是 setuptools-rust 项目走向现代化配置的必经之路。借助[[tool.setuptools-rust.ext-modules]]与[[tool.setuptools-rust.bins]]两个表格你可以用纯声明式配置替代过去的 Python 代码构建流程更透明、更易维护。建议以项目中的 hello-world-setuppy旧写法和 hello-world新写法两个示例为对照边迁移边验证最快半小时即可完成整个项目升级。【免费下载链接】setuptools-rustSetuptools plugin for Rust support项目地址: https://gitcode.com/gh_mirrors/se/setuptools-rust创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考