rustfmt

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

如果你想帮忙（你应该这么做，这是一个有趣的项目！），请参阅Contributing.md和我们的行为准则。

你可以在Travis CI构建中使用rustfmt。我们提供了一份最小化的Travis CI配置（见这里）。

快速入门

你可以使用Rust 1.24及更高版本运行rustfmt。

在稳定工具链上

安装

rustup component add rustfmt

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

cargo fmt

在Nightly工具链上

要使用最新和最好的rustfmt，需要Nightly。

安装

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的bug（像任何软件一样，Rustfmt有bug，我们不认为bug修复会破坏我们的稳定性保证）。

运行

如果您已经使用cargo install安装，只需输入rustfmt 文件名即可运行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来指定自己的rustfmt二进制文件路径，以便cargo使用。这从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；如果会进行更改，则返回 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.toml 文件来识别使用的版本，如果通过 Cargo 的格式化工具 cargo fmt 执行。否则，需要在 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 格式输出差异	是

许可证

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

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