Dylint

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

cargo install cargo-dylint dylint-link

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

内容

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

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

快速入门

运行 Dylint

下一步将安装 Dylint 并在 workspace 上运行此存储库的所有 通用示例代码检查

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 识别的文件名形式的文件（参见 库要求，位于 Dylint 的工作原理 下）。

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

可配置库

可以通过在工作空间根目录中包含一个 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 在使用 Rust 编译器检查 crate 时，将以下内容传递给 Rust 编译器，用于 Dylint

--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 是一组实用工具，可以简化 lints 的编写。它由 Rust Clippy 开发者慷慨地公开。请注意，与 rustc 一样，clippy_utils 不为其 API 提供稳定性保证。

资源

编写 lints 的有用资源包括以下内容

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

MSRV 政策

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

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

测试覆盖率