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

运行

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

您可以通过运行 rustfmt --help 获取有关可用参数的信息。运行 rustfmt 与项目交互的最简单方法是使用 cargo fmt。 cargo fmt 适用于单包项目和 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 --help。

验证代码格式

当使用 --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 使用符合通过 Rust 代码风格指南 正式化的风格的样式，该指南通过 样式 RFC 流程 确定下来。

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

Rust 的版本

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

提示

• 对于你不想让 rustfmt 修改的内容，使用 #[rustfmt::skip]

• 要防止 rustfmt 格式化宏或属性，使用 #[rustfmt::skip::macros) 或 #[rustfmt::skip::attributes)

  示例

  #![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 格式输出差异	是