无需fork Clippy即可编写Rust lint工具——Dylint完全指南

Rust linting与Clippy

像Clippy这样的工具利用了Rust编译器对linting的专门支持。Rust linter的核心组件称为"driver"，它链接到一个名为rustc_driver的库。通过这种方式，driver本质上成为了Rust编译器的包装器。

要运行linter，需要设置RUSTC_WORKSPACE_WRAPPER环境变量指向driver，然后运行cargo check。Cargo注意到环境变量已设置，就会调用driver而不是直接调用rustc。当driver被调用时，它会在Rust编译器的Config结构中设置回调。该回调注册一定数量的lints，然后Rust编译器会将这些lints与其内置lints一起运行。

Clippy执行一些检查以确保其已启用，但其他方面以上述方式工作。虽然安装时可能不太明显，但Clippy实际上是两个二进制文件：一个Cargo命令和一个rustc driver。

Dylint的工作原理

与Clippy类似，Dylint提供了一个Cargo命令。用户向该命令指定要从中加载lints的动态库。Dylint以确保在控制权交给Rust编译器之前注册lints的方式运行cargo check。

然而，Dylint的lint注册过程比Clippy更复杂。所有Clippy的lints都使用相同的编译器版本，因此只需要一个driver。但Dylint用户可以选择从使用不同编译器版本的库加载lints。

Dylint通过根据需要动态构建新的driver来处理这种情况。换句话说，如果用户想要从使用编译器版本A的库加载lints，并且找不到适用于编译器版本A的driver，Dylint将构建一个新的driver。driver缓存在用户的主目录中，因此只在必要时重新构建。

这带来了上一节提到的额外好处。Dylint按使用的编译器版本对库进行分组。使用相同编译器版本的库被一起加载，它们的lints也一起运行。这允许在lints之间共享中间编译结果（例如，符号解析、类型检查、trait求解等）。

应用：项目特定lints

您知道吗？Clippy包含一些专门用于lint Clippy自身代码的lints。这是真的。例如，Clippy包含检查每个lint都有相关的LintPass、使用某些Clippy包装函数而不是它们包装的函数，以及每个lint都有非默认描述的lints。

Dylint同样包含主要用于lint Dylint自身代码的lints。例如，在开发Dylint时，我们发现自己编写了如下代码：

1
2
3


let rustup_toolchain = std::env::var("RUSTUP_TOOLCHAIN")?;
...
std::env::remove_var("RUSTUP_TOOLCHAIN");

这是不好的做法。为什么？因为迟早会出现字符串字面量输入错误：

1

std::env::remove_var("RUSTUP_TOOLCHIAN"); // 糟糕

更好的方法是使用常量而不是字符串字面量：

1
2
3


const RUSTUP_TOOLCHAIN: &str = "RUSTUP_TOOLCHAIN";
...
std::env::remove_var(RUSTUP_TOOLCHAIN);

因此，在开发Dylint时，我们编写了一个lint来检查这种不良做法并提出适当建议。我们将（并且仍然在应用）该lint应用于Dylint源代码。该lint名为env_literal，其当前实现的核心部分如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


impl<'tcx> LateLintPass<'tcx> for EnvLiteral {
   fn check_expr(&mut self, cx: &LateContext<'tcx>, expr: &Expr<'_>) {
      if_chain! {
         if let ExprKind::Call(callee, args) = expr.kind;
         if is_expr_path_def_path(cx, callee, &REMOVE_VAR)
            || is_expr_path_def_path(cx, callee, &SET_VAR)
            || is_expr_path_def_path(cx, callee, &VAR);
         if !args.is_empty();
         if let ExprKind::Lit(lit) = &args[0].kind;
         if let LitKind::Str(symbol, _) = lit.node;
         let ident = symbol.to_ident_string();
         if is_upper_snake_case(&ident);
         then {
            span_lint_and_help(
               cx,
               ENV_LITERAL,
               args[0].span,
               "referring to an environment variable with a string literal is error prone",
               None,
               &format!("define a constant `{}` and use that instead", ident),
            );
         }
      }
   }
}

以下是它可能产生的警告示例：

1
2
3
4
5
6
7
8


warning: referring to an environment variable with a string literal is error prone
 --> src/main.rs:2:27
  |
2 |     let _ = std::env::var("RUSTFLAGS");
  |                           ^^^^^^^^^^^
  |
  = note: `#[warn(env_literal)]` on by default
  = help: define a constant `RUSTFLAGS` and use that instead

开始使用lint

使用以下命令安装Dylint：

1

cargo install cargo-dylint

我们还建议安装dylint-link工具以方便链接：

1

cargo install dylint-link

编写Dylint库的最简单方法是fork dylint-template仓库。该仓库开箱即用即可生成可加载库。您可以通过以下方式验证：

1
2
3
4


git clone https://github.com/trailofbits/dylint-template
cd dylint-template
cargo build
DYLINT_LIBRARY_PATH=$PWD/target/debug cargo dylint fill_me_in --list

您只需要实现LateLintPass trait并处理需要填充的符号即可。

编写lints的有用资源包括：

添加新lint（针对Clippy但仍然有用）
编写lints的常用工具
rustc_hir文档

还可以考虑使用上面提到的clippy_utils crate。它包含许多低级任务的函数，例如查找符号和打印诊断消息，使编写lints变得更加容易。

我们要真诚感谢Clippy作者向Rust社区提供clippy_utils crate。我们还要感谢Philipp Krones对本文早期版本提供了有益的评论。