Pants构建系统插件开发指南：如何添加自定义Linter工具-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00564/article/details/148577354

Pants构建系统插件开发指南：如何添加自定义Linter工具

pants The Pants Build System 项目地址: https://gitcode.com/gh_mirrors/pa/pants

前言

在软件开发过程中，代码质量检查(Linting)是保证代码风格一致性和发现潜在问题的重要环节。Pants构建系统提供了强大的插件机制，允许开发者将各种Linter工具集成到构建流程中。本文将详细介绍如何在Pants项目中添加一个新的Linter工具。

准备工作

在开始之前，需要明确几个前提条件：

目标Linter工具已经作为独立二进制文件存在（如Shellcheck、Pylint等）
熟悉Python编程语言
了解Pants构建系统的基本概念

第一步：安装Linter工具

Pants提供了多种方式来安装Linter工具，最常用的是通过ExternalTool机制。以下是一个Shellcheck工具的安装配置示例：

from pants.core.util_rules.external_tool import ExternalTool
from pants.engine.platform import Platform
from pants.option.option_types import ArgsListOption, SkipOption

class Shellcheck(ExternalTool):
    """Shell脚本检查工具"""
    
    options_scope = "shellcheck"
    name = "ShellCheck"
    default_version = "v0.8.0"
    
    skip = SkipOption("lint")
    args = ArgsListOption(example="-e SC20529")
    
    def generate_url(self, plat: Platform) -> str:
        # 根据不同平台生成下载URL
        plat_str = {
            "macos_arm64": "darwin.x86_64",
            "macos_x86_64": "darwin.x86_64",
            "linux_arm64": "linux.aarch64",
            "linux_x86_64": "linux.x86_64",
        }[plat.value]
        return f"https://example.com/shellcheck-{self.version}.{plat_str}.tar.xz"
    
    def generate_exe(self, _: Platform) -> str:
        return f"./shellcheck-{self.version}/shellcheck"

关键点说明：

options_scope：定义工具的配置命名空间
default_version：指定默认版本
skip：添加跳过检查的选项
args：允许用户传递额外参数

第二步：设置FieldSet和LintTargetsRequest

为了使Pants能够识别哪些目标需要应用这个Linter，我们需要定义FieldSet：

from dataclasses import dataclass
from pants.engine.target import Dependencies, FieldSet

@dataclass(frozen=True)
class ShellcheckFieldSet(FieldSet):
    required_fields = (BashSources,)
    sources: BashSources
    dependencies: Dependencies

然后创建对应的Lint请求类型：

from pants.core.goals.lint import LintTargetsRequest

class ShellcheckRequest(LintTargetsRequest):
    field_set_type = ShellcheckFieldSet
    tool_subsystem = Shellcheck

第三步：实现Linter规则

核心规则负责执行实际的Lint操作：

from pants.engine.rules import Get, MultiGet, rule
from pants.core.goals.lint import LintResult

@rule
async def run_shellcheck(
    request: ShellcheckRequest.Batch, 
    shellcheck: Shellcheck, 
    platform: Platform
) -> LintResult:
    # 1. 下载工具
    download_request = Get(
        DownloadedExternalTool,
        ExternalToolRequest,
        shellcheck.get_request(platform),
    )
    
    # 2. 获取源代码
    sources_request = Get(
        SourceFiles,
        SourceFilesRequest(field_set.sources for field_set in request.elements),
    )
    
    # 3. 合并所有输入
    downloaded_tool, sources = await MultiGet(download_request, sources_request)
    input_digest = await Get(
        Digest,
        MergeDigests((downloaded_tool.digest, sources.snapshot.digest)),
    )
    
    # 4. 执行检查
    process_result = await Get(
        FallibleProcessResult,
        Process(
            argv=[downloaded_tool.exe, *shellcheck.args, *sources.snapshot.files],
            input_digest=input_digest,
            description=f"运行Shellcheck检查",
        ),
    )
    
    return LintResult.create(request, process_result)

第四步：注册规则

最后需要将所有规则注册到Pants系统中：

from pants.engine.unions import UnionRule
from pants.core.util_rules.external_tool import ExportableTool

def rules():
    return [
        *collect_rules(),
        *ShellcheckRequest.rules(),
        UnionRule(ExportableTool, Shellcheck),
    ]