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-rust

setuptools-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( name="hello-world", version="1.0", packages=find_packages(where="python"), package_dir={"": "python"}, rust_extensions=[ RustExtension( "hello_world._lib", path="Cargo.toml", binding=Binding.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", binding=Binding.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中的packages=find_packages(where="python")和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。核心映射关系如下：

参考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.in：

include Cargo.toml recursive-include rust *.rs

多个扩展模块的注意事项

每个Cargo.toml只允许一个[lib]表。如果需要多个 Rust 扩展模块，要么编写多个Cargo.toml清单文件，要么在pyproject.toml里并列声明多个[[tool.setuptools-rust.ext-modules]]表格。

调试构建：覆盖默认 profile

setuptools-rust 默认以 release 模式构建。开发调试阶段可用环境变量切换到 debug 构建，速度更快、报错信息更友好：

export SETUPTOOLS_RUST_CARGO_PROFILE=dev

该环境变量的实现位于 rustc_info.py 与相关构建逻辑中，直接覆盖 Cargo 的 profile 选择。

命令行脚本的两种选择

除了 Rust 二进制，你也可以使用纯 Python 入口点（entry-point）调用 Rust 实现，参考 hello-world 示例 中的[project.scripts]。这种方式生成的 wheel 更小，安装更快，适合功能简单的 CLI。

迁移验证清单

完成迁移后，用下面几步快速验证配置是否正确：

1. python -m pip install -e .可编辑安装成功，import扩展模块无报错。
2. python -m build能生成 wheel 与 sdist，且 sdist 中包含 Cargo.toml 和.rs源文件。
3. 在全新虚拟环境中pip install生成的 wheel，Rust 扩展可正常导入。

小结

从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