Dylint

从动态库运行 Rust 代码检查

cargo install cargo-dylint dylint-link

Dylint 是一个类似于 Clippy 的 Rust 代码检查工具。但与 Clippy 运行预定义的静态检查集不同，Dylint 可以从用户指定的动态库运行检查。因此，Dylint 允许开发者维护自己的个人检查集合。

快速入门
- 运行 Dylint
- [编写检查]
[功能特性]
[实用工具]
资源
[MSRV 策略]

关于 Dylint 工作原理的文档也可以获取。

快速入门

运行 Dylint

以下两个步骤安装 Dylint 并在工作空间中运行此仓库的所有[通用示例检查]:

安装 cargo-dylint 和 dylint-link:
```
cargo install cargo-dylint dylint-link
```

运行 cargo-dylint:

cargo dylint --git https://github.com/trailofbits/dylint --pattern examples/general

在上面的例子中，库是通过命令行找到的。如果你打算定期运行 Dylint，可以考虑使用工作空间元数据。有关查找库的其他方法，请参阅Dylint 工作原理。

编写检查

你可以通过运行 cargo dylint new new_lint_name 来开始编写自己的 Dylint 库。这样做将会直接生成一个可加载的库。你可以按以下方式验证：

cargo dylint new new_lint_name
cd new_lint_name
cargo build
cargo dylint list --path .

你只需要实现 LateLintPass 特质并填写要求填充的符号即可。

下面提供了一些有助于编写检查的资源。

功能特性

工作空间元数据

工作空间可以在其 Cargo.toml 或 dylint.toml 文件中指定应该用于检查的库。具体来说，任一文件都可以在 workspace.metadata.dylint.libraries 下包含一个 TOML 数组。每个数组条目必须采用 Cargo git 或 path 依赖的形式，但有以下区别：

没有前导包名，即没有 package =。
path 条目可以包含 glob 模式，例如 *。
任何条目都可以包含一个 pattern 字段，其值是一个 glob 模式。pattern 字段指示包含 Dylint 库的子目录。

Dylint 会下载并构建每个条目，类似于 Cargo 下载和构建依赖项的方式。然后在结果的 target/release 目录中搜索 Dylint 识别的文件名形式（参见 Dylint 工作原理下的库要求）。

例如，如果你在工作空间的 Cargo.toml 或 dylint.toml 文件中包含以下内容并运行 cargo dylint --all，Dylint 将运行此仓库的所有[示例通用检查]，以及示例限制检查 try_io_result。

[workspace.metadata.dylint]
libraries = [
    { git = "https://github.com/trailofbits/dylint", pattern = "examples/general" },
    { git = "https://github.com/trailofbits/dylint", pattern = "examples/restriction/try_io_result" },
]

为方便起见，pattern 字段可以包含一个数组，在这种情况下，该模式被视为数组元素的并集。因此，刚才给出的 workspace.metadata.dylint.libraries 示例可以替代写成：

[workspace.metadata.dylint]
libraries = [
    { git = "https://github.com/trailofbits/dylint", pattern = [
        "examples/general",
        "examples/restriction/try_io_result",
    ] },
]

可配置库

可以通过在被检查工作空间的根目录中包含 dylint.toml 文件来配置库。该文件应编码一个 toml 表，其键为库名。库决定如何解释表中的值（如果有的话）。

例如，具有以下内容的 dylint.toml 文件将 non_local_effect_before_error_return 库的 work_limit 配置设置为 1_000_000：

[non_local_effect_before_error_return]
work_limit = 1_000_000

有关创建可配置库的说明，请参阅 dylint_linting 文档。

条件编译

对于 Dylint 用于检查 crate 的每个库，Dylint 会向 Rust 编译器传递以下内容：

--cfg=dylint_lib="LIBRARY_NAME"

你可以使用此功能在使用 Dylint 时允许检查，但在不使用 Dylint 时避免"未知检查"警告。具体来说，你可以这样做：

#[cfg_attr(dylint_lib = "LIBRARY_NAME", allow(LINT_NAME))]

注意，LIBRARY_NAME 和 LINT_NAME 可能相同。有关涉及 non_thread_safe_call_in_test 的示例，请参阅本仓库中的 dylint/src/lib.rs。

还要注意，刚才描述的方法不适用于预展开检查。对于预展开检查，唯一已知的解决方法是允许编译器内置的 unknown_lints 检查。具体来说，你可以这样做：

#[allow(unknown_lints)]
#[allow(PRE_EXPANSION_LINT_NAME)]

有关涉及 abs_home_path 的示例，请参阅本仓库中的 internal/src/examples.rs。

Rustc 的 `unexpected_cfg` 检查

从 nightly-2024-05-05 开始，每个可达的 #[cfg] 的名称和值[都会被检查]。这会导致编译器对上述描述的 cfg_attr 属性产生警告。

要抑制这些警告，请在你的包的 Cargo.toml 文件中添加以下内容：

[lints.rust.unexpected_cfgs]
level = "warn"
check-cfg = ["cfg(dylint_lib, values(any()))"]

或者，如果你使用的是 Cargo 工作空间，请在工作空间的 Cargo.toml 文件中添加以下内容：

[workspace.lints.rust.unexpected_cfgs]
level = "warn"
check-cfg = ["cfg(dylint_lib, values(any()))"]

然后，在工作空间中每个包的 Cargo.toml 文件中添加以下内容：

[lints]
workspace = true

有关示例，请参阅本仓库中的提交 c8fabc5。

VS Code 集成

可以使用 rust-analyzer 在 VS Code 中查看 Dylint 结果。要实现这一点，请在 VS Code 的 settings.json 文件中添加以下内容：

    "rust-analyzer.checkOnSave.overrideCommand": [
        "cargo",
        "dylint",
        "--all",
        "--",
        "--all-targets",
        "--message-format=json"
    ]

如果你想在检查库内部使用 rust-analyzer，需要在 VS Code 的 settings.json 文件中添加以下内容：

    "rust-analyzer.rustc.source": "discover",

并在库的 Cargo.toml 文件中添加以下内容：

[package.metadata.rust-analyzer]
rustc_private = true

实用工具

以下实用工具可以帮助编写 Dylint 库：

dylint-link 是 Rust 默认链接器（cc）的包装器，它会创建一个文件名为 Dylint 可识别格式的库副本。
dylint_library! 是一个宏，它会自动定义 dylint_version 函数并添加 extern crate rustc_driver 声明。
ui_test 是一个可用于测试 Dylint 库的函数。它提供了方便访问 compiletest_rs 包的功能。
clippy_utils 是一个使编写检查更容易的实用工具集合。它由 Rust Clippy 开发者慷慨地公开。请注意，与 rustc 一样，clippy_utils 不为其 API 提供稳定性保证。