08-cargo fix

cargo-fix(1) 自动修复警告

8 分钟阅读

译文 · 基于 The Cargo Book

cargo-fix(1)

原文链接: https://doc.rust-lang.org/cargo/commands/cargo-fix.html

名称

cargo-fix — 自动修复 rustc 报告的 lint 警告

大纲

cargo fix [options]

描述

此 Cargo 子命令会自动获取 rustc 诊断（如警告）中的建议，并将其应用到你的源代码。其目的是帮助自动化那些 rustc 本身已经知道如何告诉你去修复的任务！

执行 cargo fix 实质上会运行 cargo-check(1)。适用于你的 crate 的任何警告都会被自动修复（若可能），检查过程结束后会显示所有剩余警告。例如，若想对当前包应用所有修复，可运行：

cargo fix

其行为与 cargo check --all-targets 相同。

cargo fix 只能修复通常由 cargo check 编译的代码。若代码通过可选特性有条件地启用，则需要启用这些特性以便分析该代码：

cargo fix --features foo

类似地，其他 cfg 表达式（如平台特定代码）需要传入 --target 才能修复给定目标的代码。

cargo fix --target x86_64-pc-windows-gnu

若在使用 cargo fix 时遇到任何问题，或有任何疑问或功能请求，请随时在 https://github.com/rust-lang/cargo 提交 issue。

Edition 迁移

cargo fix 子命令也可用于将包从一个 edition 迁移到下一个。一般流程为：

运行 cargo fix --edition。若项目有多个特性，可考虑同时使用 --all-features 标志。若项目有由 cfg 属性控制的平台特定代码，你可能还想使用不同的 --target 标志多次运行 cargo fix --edition。
修改 Cargo.toml，将 edition 字段设为新的 edition。
运行项目测试以验证一切仍正常。若出现新警告，可考虑再次运行 cargo fix（不带 --edition 标志）以应用编译器给出的任何建议。

希望这样就完成了！请记住上文提到的注意事项：cargo fix 无法更新未激活特性或 cfg 表达式下的代码。此外，在极少数情况下，编译器无法自动将所有代码迁移到新 edition，构建新 edition 后可能需要手动修改。

选项

Fix 选项

--broken-code: 即便代码已有编译器错误也进行修复。若 cargo fix 未能应用更改，此选项很有用。它会应用更改，并将损坏的代码留在工作目录中供你检查并手动修复。
--edition: 应用可将代码更新到下一个 edition 的更改。这不会更新 Cargo.toml 清单中的 edition，必须在 cargo fix --edition 完成后手动更新。
--edition-idioms: 应用可将代码更新为当前 edition 首选风格的建议。
--allow-no-vcs: 即便未检测到 VCS 也修复代码。
--allow-dirty: 即便工作目录有更改（包括已暂存的更改）也修复代码。
--allow-staged: 即便工作目录有已暂存的更改也修复代码。

包选择

默认情况下，若未给出包选择选项，所选包取决于所选清单文件（若未给出 --manifest-path，则基于当前工作目录）。若清单是工作空间根，则选择该工作空间的默认成员；否则仅选择清单所定义的包。

工作空间的默认成员可通过根清单中的 workspace.default-members 键显式设置。若未设置，虚拟工作空间将包含所有工作空间成员（等价于传入 --workspace），非虚拟工作空间将仅包含根 crate 本身。

-p spec…
--package spec…: 仅修复指定的包。 SPEC 格式见 cargo-pkgid(1)。此标志可指定多次，并支持常见的 Unix glob 模式，如 *、? 和 []。不过，为避免 shell 在 Cargo 处理之前意外展开 glob 模式，必须用单引号或双引号括住每个模式。
--workspace: 修复工作空间中的所有成员。
--all: --workspace 的已弃用别名。
--exclude SPEC…: 排除指定的包。必须与 --workspace 标志一起使用。此标志可指定多次，并支持常见的 Unix glob 模式，如 *、? 和 []。不过，为避免 shell 在 Cargo 处理之前意外展开 glob 模式，必须用单引号或双引号括住每个模式。

目标选择

若未给出目标选择选项，cargo fix 将修复所有目标（隐含 --all-targets）。若二进制缺少其 required-features，则会被跳过。

传入目标选择标志将仅修复指定的目标。

注意：--bin、--example、--test 和 --bench 标志也支持常见的 Unix glob 模式，如 *、? 和 []。不过，为避免 shell 在 Cargo 处理之前意外展开 glob 模式，必须用单引号或双引号括住每个 glob 模式。

--lib: 修复包的库。
--bin name…: 修复指定的二进制目标。此标志可指定多次，并支持常见的 Unix glob 模式。
--bins: 修复所有二进制目标。
--example name…: 修复指定的示例。此标志可指定多次，并支持常见的 Unix glob 模式。
--examples: 修复所有示例目标。
--test name…: 修复指定的集成测试。此标志可指定多次，并支持常见的 Unix glob 模式。
--tests: 修复所有在清单中设置了 test = true 标志的目标。默认包括作为单元测试构建的库与二进制目标，以及集成测试。请注意这也会构建任何所需依赖，因此 lib 目标可能会被构建两次（一次作为单元测试，一次作为二进制、集成测试等的依赖）。可通过在目标的清单设置中设置 test 标志来启用或禁用目标。
--bench name…: 修复指定的基准测试。此标志可指定多次，并支持常见的 Unix glob 模式。
--benches: 修复所有在清单中设置了 bench = true 标志的目标。默认包括作为基准测试构建的库与二进制目标，以及 bench 目标。请注意这也会构建任何所需依赖，因此 lib 目标可能会被构建两次（一次作为基准测试，一次作为二进制、基准测试等的依赖）。可通过在目标的清单设置中设置 bench 标志来启用或禁用目标。
--all-targets: 修复所有目标。等价于指定 --lib --bins --tests --benches --examples。

特性选择

特性标志用于控制启用哪些特性（feature）。若未给出特性选项，则为每个所选包激活 default 特性。

参见特性文档了解更多详情。

-F features
--features features: 要激活的特性列表，以空格或逗号分隔。工作空间成员的特性可用 package-name/feature-name 语法启用。此标志可指定多次，将启用所有指定的特性。
--all-features: 激活所有所选包的全部可用特性。
--no-default-features: 不激活所选包的 default 特性。

编译选项

--target triple

为指定的目标架构修复。此标志可指定多次。默认为主机架构。 triple 的一般格式为 <arch><sub>-<vendor>-<sys>-<abi>。

可能的值：

rustc --print target-list 中任何受支持的目标。
"host-tuple"，内部会替换为主机目标。若你在交叉编译某些 crate，又不想把主机机器指定为目标（例如可能由多台主机协作的共享项目中的 xtask），这会特别有用。
自定义目标规范的路径。更多信息见自定义目标查找路径。

也可通过 build.target 配置值指定。

注意：指定此标志会使 Cargo 以不同模式运行，目标产物会放在单独目录中。详情见构建缓存文档。

-r

--release

使用 release 配置文件修复优化后的产物。也可使用 --profile 选项按名称选择特定配置文件。

--profile name

使用给定的配置文件修复。

作为特殊情况，指定 test 配置文件还会启用测试模式下的检查，这将启用对测试的检查并启用 test cfg 选项。更多详情见 rustc 测试。

关于配置文件的更多详情见参考文档。

--timings

输出每次编译耗时信息，并跟踪一段时间内的并发信息。

构建结束时会将 cargo-timing.html 文件写入 target/cargo-timings 目录。还会写入一份文件名带时间戳的额外报告，便于查看先前运行。这些报告仅供人阅读，不提供机器可读的耗时数据。

输出选项

--target-dir directory: 所有生成产物与中间文件的目录。也可通过 CARGO_TARGET_DIR 环境变量或 build.target-dir 配置值指定。默认为工作空间根目录下的 target。

显示选项

-v

--verbose

使用详细输出。可指定两次以获得「非常详细」的输出，其中包括依赖警告与构建脚本输出等额外信息。也可通过 term.verbose 配置值指定。

-q

--quiet

不打印 cargo 日志消息。也可通过 term.quiet 配置值指定。

--color when

控制何时使用彩色输出。有效值：

auto （默认）：自动检测终端是否支持颜色。
always: 始终显示颜色。
never: 从不显示颜色。

也可通过 term.color 配置值指定。

--message-format fmt

诊断消息的输出格式。可指定多次，由逗号分隔的值组成。有效值：

human （默认）：以人类可读的文本格式显示。与 short 和 json 冲突。
short: 发出更短的人类可读文本消息。与 human 和 json 冲突。
json: 向 stdout 发出 JSON 消息。详情见参考文档。与 human 和 short 冲突。
json-diagnostic-short: 确保 JSON 消息的 rendered 字段包含 rustc 的「short」渲染。不能与 human 或 short 一起使用。
json-diagnostic-rendered-ansi: 确保 JSON 消息的 rendered 字段包含嵌入的 ANSI 颜色代码，以遵循 rustc 的默认配色方案。不能与 human 或 short 一起使用。
json-render-diagnostics: 指示 Cargo 不要在打印的 JSON 消息中包含 rustc 诊断，而是由 Cargo 自身渲染来自 rustc 的 JSON 诊断。Cargo 自己的 JSON 诊断以及来自 rustc 的其他内容仍会发出。不能与 human 或 short 一起使用。