gpuweb 仓库 wgsl/grammar 目录深度解析:用 tree-sitter 构建 WGSL 语法验证与规范代码片段检查体系
gpuweb 仓库 wgsl/grammar 目录深度解析:用 tree-sitter 构建 WGSL 语法验证与规范代码片段检查体系
本文围绕 gpuweb 仓库中 wgsl/grammar 目录展开,它是 WebGPU Shading Language(WGSL)规范从 Bikeshed 源码到可执行 tree-sitter 解析器的"文法工程"枢纽:既用于验证 WGSL 语法本身,也用于逐条检查规范正文中的代码片段能否被正确解析。读完本文,你将掌握该目录的文件构成、语法提取(extract)、解析器构建(build)、示例校验(example)、单元测试(test)四级流水线,以及配套的 LALR(1) 文法分析和自定义外部扫描器的底层原理,可直接在本地复现整个验证流程。
一、目录定位:规范文本到可执行文法的双向桥梁
wgsl/grammar/README.md 用两句话点明了该目录的核心职责:
This directory contains tree-sitter grammar files with necessary modifications to build to validate WebGPU Shading Language (WGSL) grammar and also check the code snippets in the specification text.
即该目录中的 tree-sitter 文法文件承担两个任务:
- 验证 WGSL 语法本身——通过将规范中的文法规则落地为可运行的解析器,检验文法是否自洽、可解析;
- 检查规范正文中的代码片段——规范(wgsl/index.bs)中散落大量
<div class="example ... wgsl ...">代码示例,这些示例必须能被同一套解析器成功解析,保证"文档里的代码不会骗人"。
README 同时规定了一个重要的同步约束:任何对 wgsl/grammar 目录内容的修改都应同步到独立的 tree-sitter-wgsl 仓库。这意味着本目录是文法定义的"权威源头",外部工具链则消费其产物。
从仓库顶层看,wgsl/grammar 只是一个"种子"目录:真正被检入的源文件只有 scanner.c、package.json、tree-sitter.json、binding.gyp、.gitignore 与 README.md,而 grammar.js、src/parser.c、bindings/ 等均由构建流程自动生成(见下文 .gitignore 分析)。这套"最小检入 + 自动生成"的设计,保证了文法事实来源唯一:规范文本(index.bs + wgsl/syntax.bnf)→ 自动提取 → tree-sitter 解析器。
二、目录文件逐个拆解
2.1 package.json:tree-sitter-wgsl 的 npm 元数据
wgsl/grammar/package.json 将本目录定义为一个标准 npm 包,包名为 tree-sitter-wgsl(版本 0.0.9,BSD-3-Clause 许可)。关键信息如下:
- tree-sitter 配置段:
scope: "source.wgsl"、file-types: ["wgsl"]、injection-regex: "^wgsl$",高亮规则指向queries/highlights.scm——这使任何基于 tree-sitter 的编辑器(如 Neovim、Helix 等)都能直接识别.wgsl文件并做语法高亮与注入解析。 - 构建脚本:
install:node-gyp-build——通过预编译产物安装原生绑定;prestart:tree-sitter build --wasm——先构建 WebAssembly 版本;start:tree-sitter playground——启动交互式 playground,可实时查看解析树;test:node --test bindings/node/*_test.js——运行 Node 绑定测试。
- 依赖:运行时依赖
node-addon-api与node-gyp-build;开发依赖prebuildify与tree-sitter-cli(版本 ^0.25.8);tree-sitter(^0.22.4)为可选 peer 依赖。 - files 白名单:打包仅包含
grammar.js、tree-sitter.json、binding.gyp、prebuilds/**、bindings/node/*、queries/*、src/**与*.wasm。
2.2 tree-sitter.json:跨语言绑定声明
wgsl/grammar/tree-sitter.json 遵循 tree-sitter 官方 schema,声明:
- 文法名
wgsl、驼峰名Wgsl、作用域source.wgsl、注入正则^wgsl$、类名TreeSitterWgsl; - bindings 字段一次性声明了 7 种目标语言绑定:
c、go、node、python、rust、swift、zig。这意味着本目录生成的解析器可以被广泛的生态消费,而不局限于某一种宿主语言。
2.3 binding.gyp:Node 原生模块的编译描述
wgsl/grammar/binding.gyp 是 node-gyp 的构建清单,目标 tree_sitter_wgsl_binding 将三个源文件编译为 Node 原生插件:
sources:
bindings/node/binding.cc
src/parser.c
src/scanner.c # 自定义外部扫描器(注意:注释提示若语言有外部扫描器则在此添加)
其中 parser.c 是 tree-sitter-cli 生成的 LR 解析器(检入时被 .gitignore 排除),scanner.c 则是手工维护的外部扫描器(唯一被检入的 C 源文件)。编译标准按平台区分:非 Windows 使用 -std=c11,Windows 使用 /std:c11 /utf-8。
2.4 .gitignore:哪些文件是"产物"而非"源码"
wgsl/grammar/.gitignore 揭示了目录的生成式工作流:Rust(target/)、Node(build/、node_modules/)、Swift(.build/)、Go(go.sum、_obj/)、Python(__pycache__/、dist/、*.egg-info)、C(*.a、*.so 等)、Zig 等各语言构建产物全部忽略;尤其关键的一条:
bindings/
src/*
!src/scanner.c
即 bindings/ 与 src/parser.c 等全部为 tree-sitter-cli 自动生成,唯一例外保留 src/scanner.c——这是整个目录中唯一需要人类维护的解析器源代码。
三、四级流水线:extract → build → example → test
目录的全部价值由 wgsl/tools/extract-grammar.py 驱动。其内嵌的 FLOW_HELP 文档给出了完整流程定义(extract-grammar.py):
| 字母 | 步骤 | 作用 |
|---|---|---|
x |
extract | 从 WGSL 规范的 Bikeshed 源码中提取文法规则,生成 tree-sitter 文法定义 grammar.js,同时生成每个规则的 Bikeshed 片段 *.syntax.bs.include |
b |
build | 调用 tree-sitter-cli 生成解析器并构建安装 tree_sitter_wgsl Python 模块 |
e |
example | 用解析器逐一解析规范中的代码示例,任何失败都会使流程报错 |
t |
test | 运行解析器单元测试(wgsl_unit_tests.py) |
默认流程为 --flow xbet,顺序固定。可选择性执行,例如 extract-grammar.py --flow xbe 表示提取、构建并校验示例。命令行参数还包括 --tree-sitter-dir(默认 grammar)、--spec(默认 index.bs)、--scanner、--syntax(默认 syntax.bnf)、--syntax-dir(默认 syntax)。
3.1 第一步 extract:从规范文本中"扫描"出文法
read_spec()(extract-grammar.py)通过三个 Scanner 类以状态机方式扫描规范源码:
scanner_rule(L170):识别<div class='syntax'>开头的文法规则块,解析<dfn for=syntax>规则名与|开头的产生式行,支持多行续行;scanner_example(L232):识别<div class="example ... wgsl ...">示例块,收集<xmp>中的 WGSL 源码文本,以 div 的 heading 属性作为示例名;scanner_token(L278):识别形如* <dfn for=syntax_sym lt='and' noexport>的终结符定义,建立"符号名 ↔ 字面量"映射。
此外,规则提取还会校验"源 BNF 与重生成 BNF 完全一致"(L927-L932),防止手工编辑与程序化表示产生漂移。提取完成后,extract_rules_to_bs() 将每个规则写回 wgsl/syntax 目录下的 *.syntax.bs.include 文件,这些文件正是规范 HTML 中语法框的渲染来源。
生成的 grammar.js 骨架(flow_extract)值得关注:
module.exports = grammar({
name: 'wgsl',
externals: $ => [
$._block_comment, $._disambiguate_template,
$._template_args_start, $._template_args_end,
$._less_than, $._less_than_equal, $._shift_left, $._shift_left_assign,
$._greater_than, $._greater_than_equal, $._shift_right, $._shift_right_assign,
$._error_sentinel,
],
extras: $ => [ $._comment, $._block_comment, $._blankspace ],
inline: $ => [ $.global_decl ],
// WGSL has no parsing conflicts.
conflicts: $ => [],
word: $ => $.ident_pattern_token,
rules: { ... }
});
注意三点:
conflicts: $ => []——注释明确"WGSL has no parsing conflicts",这是对文法质量的一项硬性声明;- 规则按"translation_unit/global_directive/global_decl → *_literal → 命名规则 → 终结符 → 下划线规则 → ident → comment → blankspace → 保留字"的顺序组织(L1021-L1102);
- 保留字直接取自
wgsl.reserved.plain,生成_reserved: choice('...', ...)(该文件由 wgsl/tools/generate-reserved-words.py 生成)。
文法的事实来源是 wgsl/syntax.bnf(620 行的 BNF 方言,例如 translation_unit : global_directive * ( global_decl | global_assert | ';' ) *),其头部说明该方言"不直接兼容现有 BNF 解析器",使用模式字面量与正则化操作以获得简洁阅读体验,具体符号约定见规范 1.2 节。
3.2 第二步 build:生成解析器并安装 Python 模块
flow_build()(extract-grammar.py)的执行路径:
- 若
bindings/python/tree_sitter_wgsl/binding.c不存在,先执行npx tree-sitter-cli@0.25.8 init --update; - 执行
npx tree-sitter-cli@0.25.8 generate,由grammar.js生成src/parser.c与各语言绑定; - 执行
python3 -m pip install -e .(虚拟环境下)或pip install -e . --user --break-system-packages(系统环境),把tree_sitter_wgsl安装为可导入的 Python 模块; - 成功后写入
grammar/build.stamp标记文件,供 Makefile 判断是否需要重建。
其中 build.stamp 的"新鲜度"判断基于两点:grammar.js 是否有变化、src/scanner.c 是否比 stamp 更新(L1223)。
3.3 第三步 example:规范代码片段逐一过关
flow_examples()(extract-grammar.py)读取扫描到的全部示例,逐条用 tree_sitter_wgsl 解析:
- 名为
expect-error的示例被跳过(它们是刻意展示语法错误的负面样例); - 名为
function-scope的示例会被自动包进fn function__scope____() { ... }; - 名为
type-scope的示例会被包装为const type_scope____: ... = ...();(零值表达式初始化),以模拟其在类型上下文中的使用。
任何一条示例解析出错都会打印示例源码与解析树(S-expression),最终累计错误数并抛出 Grammar is not compatible with examples!。这保证了规范正文中所有 WGSL 代码片段与文法定义保持严格一致。
3.4 第四步 test:面向解析树的单元测试
wgsl/tools/wgsl_unit_tests.py 定义了三种测试用例基类:
Case(L44):断言某段文本可被成功解析(expect_pass);XFail(L63):断言解析失败,用于验证文法正确地拒绝非法输入;MatchCase(L67):在解析成功后,用 TSPath 定位解析树中的节点并断言其类型与文本。
具体用例分布在 wgsl_unit_tests_simple.py、wgsl_unit_tests_enable.py、wgsl_unit_tests_equals.py、wgsl_unit_tests_template.py 四个文件中(GetCases 汇总)。以 simple 为例:
XFail("this fails"), # 非法文本必须解析失败
XFail("#version 450"), # GLSL 语法必须被拒绝
Case("const pi = 3.14;"),
Case("const b = bitcast<i32>(1u);"),
Case("@group(0) @binding(0) var s: sampler;"),
Case("var<workgroup> w: array<vec3<f32>,1>;"),
Case("var c : array<(a>b)>;"), # 可解析,但语义上非法(类型上下文)
XFail("const c = array<a>b>;"), # 模板参数歧义必须被拒绝
其中 array<a>b> 与 array<(a>b)> 的一对一正反对照,正是对模板参数与比较表达式歧义消解(见下节 scanner.c)的回归测试。
TSPath(wgsl/tools/TSPath.py)是一种受 XPath 启发的声明式解析树节点描述语言,例如:
/translation_unit # 树顶的 translation_unit 节点
//enable_directive # 树中任意位置的 enable_directive
//assignment_statement/lhs_expression # assignment 的直属 lhs_expression 子节点
//assignment_statement[1] # 任意位置 assignment 的第二个子节点
MatchCase 通过 path.match(tree) 收集命中节点,并将其 type:text 序列与期望值比对,从而把"语法是否正确"的断言精确到具体 AST 节点。
四、自定义外部扫描器 scanner.c:模板消歧与词法难点
wgsl/grammar/src/scanner.c(1161 行 C 代码)是目录中唯一的"人写"解析器代码,其 Token 枚举(L21-L38)声明了 10 个外部 token:
enum Token {
BLOCK_COMMENT,
DISAMBIGUATE_TEMPLATE, // 零长度 token,用于前瞻消歧
TEMPLATE_ARGS_START,
TEMPLATE_ARGS_END,
LESS_THAN, LESS_THAN_EQUAL, SHIFT_LEFT, SHIFT_LEFT_ASSIGN,
GREATER_THAN, GREATER_THAN_EQUAL, SHIFT_RIGHT, SHIFT_RIGHT_ASSIGN,
ERROR, // 哨兵值
};
为什么需要它? WGSL 的 array<T,N>、vec3<f32> 等模板类型使用尖括号,而 <、> 同时又作为比较运算符、移位运算符出现。array<a>b> 到底是"模板实参 a 后面跟变量 b",还是"比较 a > b 的结果作为数组类型"?这类歧义仅凭常规 LR 文法难以处理。解决方案正如 extract-grammar.py 中 custom_simple_tokens 字典(L331-L342)所注释的:
These fixed tokens must be parsed by the custom scanner. This is needed to support template disambiguation.
即 <、<=、<<、<<=、>、>=、>>、>>= 八个 token 全部交给自定义扫描器,配合零长度的 DISAMBIGUATE_TEMPLATE(向前扫描判定某个 < 是否开启模板实参)与 TEMPLATE_ARGS_START/END 标记,实现模板上下文的确定性切分。
scanner.c 还承担另外两项词法工作:
- 嵌套块注释:
BLOCK_COMMENT使 tree-sitter 支持 WGSL 嵌套/* /* */ */注释(外部扫描器 API 参见 tree-sitter 官方文档); - Unicode 标识符:文件内嵌完整的 Unicode 14 XID_Start 码点区间表(
kXIDStartRanges,L111 起),通过二分查找(binary_search,L90)判定字符是否可作标识符起始,从而支持规范规定的非 ASCII 标识符。
五、Makefile 集成:一条命令跑通验证链
wgsl/Makefile 将上述流程组织为可复现的目标:
| 目标 | 作用 | 对应实现 |
|---|---|---|
make validate |
执行 lalr、tspath_tests、unit_tests、validate-examples 全量验证 | L6 |
make validate-examples |
提取文法 → 构建解析器 → 校验规范示例 | L55-L56 |
make unit_tests |
运行解析器单元测试(依赖 build.stamp) | L64-L65 |
make lalr |
生成 LALR(1) 分析表,有冲突即失败 | L87-L96 |
make simple / make recursive |
输出未规范化 / 递归下降形式的文法 | L91-L107 |
make recursive_bs |
生成 wgsl.recursive.bs.include(规范用递归文法) |
L109-L111 |
make analyze_test |
文法分析器自身的单元测试 | L123-L125 |
其中文法事实链为:grammar/grammar.js 由 index.bs、grammar/src/scanner.c、extract-grammar.py、wgsl.reserved.plain 依赖生成(L40-L47);tree-sitter 解析器安装成功与否由 grammar/build.stamp 记录(L37);LALR 分析消费 tree-sitter 生成的 JSON 文法 grammar/src/grammar.json(L68-L69)。
六、文法分析器:验证 WGSL 文法为 LALR(1)
wgsl/tools/analyze/lalr.py 配套 Grammar.py、ObjectRegistry.py 构成自研文法分析器,输入即 tree-sitter 生成的 grammar/src/grammar.json,支持多种分析模式:
-lalr:计算 LALR(1) 分析表,存在任何冲突即以退出码 1 失败(L154-L161);-lr:输出 LR(1) 项目集;-ll:计算 LL(1) 分析表并列出冲突;-recursive <a href="https://link.gitcode.com/i/566247fde499ad094005247765901a9d" target="_blank">-bs]:将文法转换为适合递归下降解析的形式(并可选输出为 Bikeshed 片段,即wgsl.recursive.bs.include的来源),其中还针对unary_expression、ident等规则做左因子提取,并对hex_float_literal、decimal_float_literal做特殊 token 化处理([L104-L148)。
分析器的自测用例位于 wgsl/tools/analyze/test.py 及 test 目录,包含 ex417.json、ex442.json(即《编译原理(龙书)》例 4.42,Aho, Sethi, Ullman, 1986)、firsts.json、star.json 等小样本文法,用于验证 LALR/LR/LL 分析的正确性。
七、本地复现:环境准备与验证命令
根据 wgsl/README.md 的说明,复现本文所述流程需要:Python 3、Tree-sitter(py-tree-sitter)、npm/node.js、C/C++ 编译器,以及构建规范 HTML 所需的 Bikeshed。
# 1. 安装依赖(wgsl 选项会安装 build、tree_sitter==0.25.0、setuptools,
# 版本见 tools/custom-action/dependency-versions.sh)
./tools/install-dependencies.sh bikeshed diagrams wgsl
# 2.(可选)使用 venv 隔离 Python 环境
python -m venv myenv
. myenv/bin/activate
# 3. 一键构建规范并完成全部验证
make
# 4. 单独验证规范中的代码片段可解析
make validate-examples
# 5. 验证文法为 LALR(1)(有冲突即失败),输出 wgsl.lalr.txt
make lalr
关键版本约束记录在 tools/custom-action/dependency-versions.sh:PIP_TREE_SITTER_VERSION=0.25.0、NPM_TREE_SITTER_CLI_VERSION=0.25.8,且 extract-grammar.py 运行前必须 source 该文件(缺失环境变量会直接报错退出)。若机器无法联网,Bikeshed 会退化为使用 Web API 构建,速度较慢但可工作。
八、小结:一个"规范即文法"的自洽闭环
wgsl/grammar 目录的工程价值在于它把"写规范"与"写解析器"合二为一:文法唯一事实来源是规范文本(index.bs 与 syntax.bnf),通过 extract-grammar.py 的 x/b/e/t 流水线自动派生 tree-sitter 解析器,再反向用解析器验证规范正文中的每一个代码示例与文法自身性质(无解析冲突、LALR(1) 可分析)。对语言设计者而言,任何语法改动都会在同一套流水线中被示例校验与 LALR 分析即时拦截;对工具链开发者而言,该目录产出的解析器覆盖 C/Go/Node/Python/Rust/Swift/Zig 七种绑定,可直接嵌入编辑器高亮、代码检索与静态分析工具。而"修改需同步至 tree-sitter-wgsl 仓库"的约定,则保证了权威文法在 gpuweb 主仓库与独立发布包之间始终保持一致。