rustfmt

一个用于根据风格指南格式化 Rust 代码的工具。

如果您想帮忙（您应该这么做，这是一个有趣的项目！），请参阅 Contributing.md 和我们的 Code of Conduct。

您可以在 Travis CI 构建中使用 rustfmt。我们提供了一个最小的 Travis CI 配置（见 此处）。

快速入门

您可以使用 Rust 1.24 及以上版本运行 rustfmt。

在稳定工具链上

安装

rustup component add rustfmt

在当前工作目录中的 cargo 项目上运行

cargo fmt

在夜间工具链上

要使用最新的 rustfmt，需要夜间版本。

安装

rustup component add rustfmt --toolchain nightly

在当前工作目录中的 cargo 项目上运行

cargo +nightly fmt

局限性

Rustfmt 尽可能地在尽可能多的 Rust 代码上工作。有时，代码甚至不需要编译！总的来说，我们希望限制不稳定区域的范围；特别是，1.0 版本之后，大多数代码的格式化不应随着 Rustfmt 的改进而改变。然而，有些事情 Rustfmt 无法做或做得不好（因此格式化可能即使是在 1.0 之后也可能发生显著变化）。我们希望随着时间的推移减少局限性的列表。

以下列出了Rustfmt不工作或稳定性保证不适用的情况（我们不对这两者进行区分，因为在将来，Rustfmt可能对目前无法工作的代码进行格式化）。

• 程序中任何部分无法解析的情况（解析是编译的早期阶段，在Rust中包括宏展开）。
• 宏声明和使用（当前状态：一些宏声明和使用已格式化）。
• 注释，包括任何具有“内部”注释的AST节点（Rustfmt目前不尝试格式化注释，但它会格式化包含注释的代码，但未来的格式化可能会发生变化）。
• 注释中的代码块中的Rust代码。
• 程序的任何片段（即，稳定性保证仅适用于整个程序，即使今天可以格式化程序的片段）。
• 包含非ASCII Unicode字符的代码（我们相信Rustfmt在这里基本工作，但没有足够的测试覆盖率或经验来确保100%正确）。
• Rustfmt中的错误（像任何软件一样，Rustfmt有错误，我们不认为错误修复会破坏我们的稳定性保证）。

运行

如果您已经使用 cargo install 安装了，只需键入 rustfmt filename 即可运行Rustfmt。这将在给定的文件上运行rustfmt，如果文件包含非内联模块，我们也将重新格式化它们。因此，要在一个整个模块或crate上运行，只需运行根文件（通常是mod.rs或lib.rs）即可。Rustfmt还可以从stdin读取数据。或者，您可以使用 cargo fmt 格式化您crate的所有二进制和库目标。

您可以通过运行 rustfmt -h 获取有关可用参数的信息。在项目中运行rustfmt的最简单方法是使用 cargo fmt。 cargo fmt 适用于单crate项目和 cargo工作区。请参阅 cargo fmt --help 获取使用信息。

您可以通过设置 RUSTFMT 环境变量来指定cargo使用的自己的 rustfmt 二进制文件的路径。这从v1.4.22版本开始添加，因此您必须具有此版本或更高版本才能利用此功能（cargo fmt --version）。

直接运行 rustfmt

要格式化单个文件或来自stdin的任意代码，应使用 rustfmt 二进制文件。以下是一些示例

• rustfmt lib.rs main.rs 将原地格式化 "lib.rs" 和 "main.rs"。
• rustfmt 将从stdin读取代码并将其格式化输出到stdout。
  • echo "fn main() {}" | rustfmt 将输出 "fn main() {"。

有关更多信息，包括参数和输出选项，请参阅 rustfmt -h。

验证代码已格式化

当使用--check时，如果Rustfmt对输入不进行任何格式化更改，则将退出并返回0，如果Rustfmt会进行更改，则返回1。在其他模式下，如果格式化过程中发生错误（例如解析或内部错误），则Rustfmt将退出并返回1，如果没有错误完成格式化（无论是否进行了更改），则返回0。

从您的编辑器运行Rustfmt

• Vim
• Emacs
• Sublime Text 3
• Atom
• Visual Studio Code
• IntelliJ或CLion

在CI服务器上检查样式

为了保持代码库格式的一致性，当拉取请求中包含未格式化的代码时，使CI构建失败可能很有帮助。使用--check指令让rustfmt在输入未正确格式化时退出并返回错误代码。它还会打印出找到的所有差异。（较旧版本的Rustfmt不支持--check，请使用--write-mode diff）。

一个最小的Travis设置可能如下所示（需要Rust 1.31.0或更高版本）

language: rust
before_script:
- rustup component add rustfmt
script:
- cargo build
- cargo test
- cargo fmt --all -- --check

有关更多信息，请参阅这篇博客文章。

如何构建和测试

使用cargo build进行构建。

使用cargo test运行所有测试。

在此之后运行rustfmt，请使用cargo run --bin rustfmt -- filename。有关运行rustfmt的说明，请参阅上面的注释。

配置Rustfmt

Rustfmt被设计成非常可配置。您可以创建一个名为rustfmt.toml或.rustfmt.toml的TOML文件，将其放置在项目或任何其他父目录中，它将应用该文件中的选项。有关可用选项，请参阅rustfmt --help=config，或者如果您更喜欢查看视觉样式预览，请访问GitHub页面。

默认情况下，Rustfmt使用符合通过样式RFC流程正式化的Rust样式指南的风格。

配置选项要么是稳定的，要么是不稳定的。稳定选项始终可以使用，而不稳定的选项仅在某些夜间工具链上可用，并且需要选择加入。有关详细信息，请参阅GitHub页面。

Rust的版本

Rustfmt能够通过读取执行通过Cargo的格式化工具cargo fmt时执行的Cargo.toml文件来获取使用的版本。否则，需要在rustfmt.toml中指定版本，例如，使用edition = "2018"。

提示

• 对于您不希望rustfmt修改的内容，请使用#[rustfmt::skip]

• 为了防止rustfmt格式化宏或属性，使用以下代码：#[rustfmt::skip::macros(target_macro_name)] 或 #[rustfmt::skip::attributes(target_attribute_name)]

  示例

  #![rustfmt::skip::attributes(custom_attribute)]
  
  #[custom_attribute(formatting , here , should , be , Skipped)]
  #[rustfmt::skip::macros(html)]
  fn main() {
      let macro_result1 = html! { <div>
  Hello</div>
      }.to_string();
  

• 当您运行rustfmt时，将名为 rustfmt.toml 或 .rustfmt.toml 的文件放置在目标文件目录或其父目录中，以覆盖rustfmt的默认设置。您可以使用 rustfmt --print-config default rustfmt.toml 生成包含默认配置的文件，并根据需要进行自定义。

• 编译成功后，可以在目标目录中找到名为 rustfmt 的可执行文件。

• 如果您在编译Rustfmt时遇到问题（或尝试安装时出现编译错误），请确保您已安装最新的Rust版本。

• 您可以使用 --emit 标志更改rustfmt发出更改的方式

  示例

  cargo fmt -- --emit files
  

  选项

  标志	描述	夜间仅
  文件	覆盖输出到文件	否
  stdout	将输出写入stdout	否
  覆盖率	显示输入文件处理了多少	是
  checkstyle	以checkstyle格式发出	是
  json	以json格式发出diff	是

许可证

Rustfmt根据MIT许可证和Apache许可证（版本2.0）的条款分发。

有关详细信息，请参阅 LICENSE-APACHE 和 LICENSE-MIT。