Dylint

从动态库中运行 Rust 代码风格检查

cargo install cargo-dylint dylint-link

Dylint 是一个类似于 Clippy 的 Rust 代码风格检查工具。但 Clippy 运行的是一组预定的、静态的代码风格检查，而 Dylint 运行的是用户指定的动态库中的代码风格检查。因此，Dylint 允许开发者维护他们自己的个人代码风格检查集合。

内容

• 快速入门
  • 运行 Dylint
  • 编写代码风格检查
• 功能
  • 工作区元数据
  • 可配置库
  • 条件编译
  • VS Code 集成
• 实用工具
• 资源
• MSRV 政策

有关 Dylint 的工作原理的文档也可在 此处 查看。

快速入门

运行 Dylint

以下两个步骤将安装 Dylint 并在一个工作区上运行此仓库的所有 通用示例代码风格检查。

1. 安装 cargo-dylint 和 dylint-link

   cargo install cargo-dylint dylint-link
   

2. 运行 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 特性，并适应要求填充的符号。

编写 lints 时的有用资源如下。

功能

工作区元数据

工作空间可以在其 Cargo.toml 或 dylint.toml 文件中指定应进行 lint 的库。具体来说，任意文件都可以包含位于 workspace.metadata.dylint.libraries 下的 TOML 列表。每个列表条目都必须采用 Cargo git 或 path 依赖项的形式，但有以下区别

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

Dylint 会下载并构建每个条目，类似于 Cargo 下载和构建依赖项的方式。结果 target/release 目录会搜索 Dylint 识别的文件名（见 Library requirements 下的 How Dylint works）。

例如，如果您在您的工作空间的 Cargo.toml 或 dylint.toml 文件中包含以下内容并运行 cargo dylint --all，Dylint 将运行此存储库的所有 示例通用 lints，以及示例限制 lints 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" },
]

可配置库

可以通过在 linted 工作空间的根目录中包含一个 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 被使用时允许 lint，但在 Dylint 未使用时避免“未知 lint”警告。具体来说，您可以执行以下操作

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

请注意，LIBRARY_NAME和LINT_NAME可能相同。例如，在non_thread_safe_call_in_test中，请参阅此存储库中的dylint/src/lib.rs。

此外，上述方法不适用于预展开的lint。已知针对预展开lint的唯一解决方案是允许编译器内置的unknown_lints lint。具体来说，您可以执行以下操作

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

例如，在abs_home_path中，请参阅此存储库中的internal/src/examples.rs。

VS Code 集成

您可以使用rust-analyzer在VS Code中查看Dylint的结果。为此，将以下内容添加到您的VS Code settings.json文件中

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

如果您想在lint库中使用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是一组使编写lint更容易的实用工具。它由Rust Clippy开发者慷慨公开。请注意，与rustc一样，clippy_utils不为其API提供稳定性保证。

资源

以下资源有助于编写lint

• 添加新的lint（针对Clippy但仍然有用）
• 作者lint
• 编写lint的常用工具
• Rustc开发指南
• Crate rustc_hir
• Crate rustc_middle
• Struct rustc_lint::LateContext
  • Method typeck_results
  • Field tcx
    • Method hir

MSRV 政策

Dylint库的MSRV提升将伴随着至少Dylint次要版本的提升。

换句话说，我们在发布错误修复时努力保留Dylint的MSRV，仅在发布新功能时更改它。

测试覆盖率