Cargo nightly 文档测试混用后端,核对 rustdoc 的 codegen-backend
profile 中为 rustc 指定 Cranelift,不保证 rustdoc 文档测试采用相同后端。检查 verbose 命令行,在同一 pinned nightly 下显式补足 rustdoc 参数,保留完整测试覆盖。
库和单元测试使用 Cranelift 编译,文档测试却仍走 LLVM,随后在某个平台出现链接或运行异常。若项目通过 Cargo profile 的 codegen-backend 选择后端,先查看 rustdoc --test 的实际参数;不要只检查 rustc 那几行。
在 Cargo 1.101.0-nightly 的具体路径中,后端参数会传给库和测试 harness 的 rustc,却没有同样传给文档测试。不同后端混用可能暴露 ABI 问题,但不能单凭一次 doctest 崩溃就认定原因,目标平台、依赖编译方式和详细命令都需要对应。
先确认哪条编译命令缺参数
在项目允许执行测试的环境,用同一 pinned nightly 查看详细测试命令,比较库、测试 harness 和 rustdoc。确认后端、target、panic 策略及其他项目必需参数;如果 rustdoc 已明确使用目标后端,就继续检查实际崩溃栈,不反复追加同一开关。
codegen-backend 和 Cranelift preview 属于不稳定配置。工具链文件、组件和目标平台应配套固定,不能把 -Z 选项复制到稳定工具链,也不能把某个开发快照的行为当作所有 Cargo 版本的保证。
在 rustdoc 入口补足相同后端
对于已经安装匹配 Cranelift 组件、并使用该 profile 的项目,可为 rustdoc 显式设置相同后端。以下只展示应合入现有 Cargo 配置的参数,不替代原来的 profile 声明:
[build]
rustdocflags = ["-Zcodegen-backend=cranelift"]
如果已经有 rustdocflags,保留原有内容。RUSTDOCFLAGS、编码形式的环境变量以及按 target 配置的参数可能影响最终值,须检查真正执行的命令,避免覆盖必要 feature 或产生重复选项。
改动后单独验证文档测试,再运行原来的完整测试入口。原项目若使用 -Zpanic-abort-tests、显式 target 或 package 选择,也要保持一致。关闭 doctest、删除库目标或只运行 --lib 会减少覆盖,不能用来证明后端问题解决。
切换后端的产物应按项目既有策略隔离,避免旧对象或远程缓存再次把不同后端产物混到同一验证中。覆盖目标架构上的编译、链接与运行,不能只看 rustdoc 命令已经带上字符串。
这项配置只补足当前调用入口。升级后检查 rustdoc 的实际参数,并用相同用例验证后端与产物一致,再决定是否撤掉显式配置。


