Diagnostic Line Number Test【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slangThis test verifies that error diagnostics in.slang.mdfiles report the correct line number from the original Markdown file.//DIAGNOSTIC_TEST:SIMPLE(diagCHECK): void foo() { int x undefinedVar; //CHECK: ^^^^^^^^^^^^ undefined identifier //CHECK: ^^^^^^^^^^^^ undefined identifier undefinedVar. }它由三层结构组成 1. **Markdown 正文**第 1–4 行说明性文字仅用于文档展示不参与编译。 2. **指令行**第 7 行//DIAGNOSTIC_TEST:SIMPLE(diagCHECK): 声明这是一个**诊断测试**diagnostic test并约定注解前缀为 CHECK。 3. **故意写错的代码块**第 9–14 行int x undefinedVar; 引用了未定义的标识符 undefinedVar用于触发编译器报错。第 12–13 行的 //CHECK: 注解声明了对错误位置的预期。 注意一个细节代码块内第 8 行是空行而 void foo() 实际位于原始 Markdown 文件的**第 9 行**# 标题占 1 行、正文占 3 行、围栏起始行 slang 占 1 行、指令行占 1 行、空行占 1 行。从提取后的合成源码看void foo() 是第一个代码块的首行行号为 1但测试要求诊断指向的行号必须是 **9**原始文件行号这正是本测试的核心断言。 ## 三、行号映射的底层机制#line 重映射 行号之所以能回到原始 Markdown 文件关键在源码提取阶段。编译入口对源码文件的分段逻辑位于 [source/slang/slang-compile-request.cpp](https://link.gitcode.com/i/e348d95c42e98ff0753411895e60d636) 的 extractSourceSegments第 623–648 行 cpp if (!hasLiterateFileExtension(sourceFile-getPathInfo().foundPath)) { segments.add(sourceFile); return segments; } auto content sourceFile-getContent(); auto codeBlocks extractSlangCodeBlocks(content.begin(), content.getLength()); for (auto block : codeBlocks) { StringBuilder syntheticContent; syntheticContent #line block.startLine \n; syntheticContent block.content; ... } 实现要点 - **识别 literate 文件**hasLiterateFileExtension定义于 [source/slang/slang-markdown.cpp](https://link.gitcode.com/i/85c3f9b3a45f4fe1bcfd0f77c7f6a41f)判断路径是否以 .md 结尾非 literate 文件直接作为单个分段返回不经过提取。 - **提取代码块**extractSlangCodeBlocks[source/slang/slang-markdown.cpp](https://link.gitcode.com/i/9080d3be472d880ddce39d0ff17c4814)使用 cmark-gfm 解析 Markdown 文档只保留满足以下条件的代码块 - 节点类型为 CMARK_NODE_CODE_BLOCK - 围栏信息fence info为空或等于 slang。这解释了为什么 basic-multi-block.slang.md 中的 python 代码块会被忽略而**无标签代码块**会被当作 Slang 源码。 - **行号重映射**对每个代码块在块内容前拼接一行 #line block.startLine其中 block.startLine 取自 cmark 的 CMARK_OPT_SOURCEPOS 源位置信息——即该代码块在**原始 Markdown 文件中的起始行号**围栏起始行 1见 [slang-markdown.cpp](https://link.gitcode.com/i/87207b10a8e896dbfe7a3fec33399b80) 的 nodeLine 1 逻辑。#line 指令随后驱动预处理与词法/语法分析的行号追踪使后续所有诊断都基于原始文件的行号体系。 因此当编译器在第 12 行报出 undefined identifier undefinedVar 时行号 12 对应的正是原始 .slang.md 文件中的真实位置而非合成源码中的位置。 ## 四、诊断注解//CHECK的语义与书写规范 测试文件第 12–13 行使用的是**基于位置的注解**position-based annotation slang //CHECK: ^^^^^^^^^^^^ undefined identifier //CHECK: ^^^^^^^^^^^^ undefined identifier undefinedVar. 其语义由 [tools/slang-test/diagnostic-annotation-util.cpp](https://link.gitcode.com/i/a1263aed998ee4a9e03e43715cc092d6) 中的解析器定义 - **行号**注解所在行不属于源码解析器记录最后一个非注解、非空行lastNonAnnotationLine注解的行号取 lastNonAnnotationLine 1[diagnostic-annotation-util.cpp](https://link.gitcode.com/i/a1263aed998ee4a9e03e43715cc092d6#L215)。本例中最后一个非注解行是 int x undefinedVar;原始第 11 行所以注解指向第 **12** 行。 - **列号**^ 串在注解行中的起始位置0 基加 1 得到列起点^ 串长度决定列终点采用排他性终点约定即终点列 起始列 1 caret 数见 [diagnostic-annotation-util.cpp](https://link.gitcode.com/i/a1263aed998ee4a9e03e43715cc092d6#L221-L222)。测试中的 12 个 ^ 正好覆盖第 12 行第 5–16 列的 undefinedVar 标识符注意第 11 行的 int x undefinedVar; 中 undefinedVar 起始列是 5。 - **消息匹配**^ 之后的文本作为**子串**与诊断消息匹配。两条注解分别匹配 undefined identifier 与 undefined identifier undefinedVar.后者是 Slang 诊断系统的完整消息前者是省略变量名的子串。匹配不仅限于 message 字段还可以命中 severity、errorCode 或拼接的 severity errorCode[diagnostic-annotation-util.cpp](https://link.gitcode.com/i/a1263aed998ee4a9e03e43715cc092d6#L473-L487)。 除基于位置的 ^ 注解外解析器还支持**简单子串注解**//CHECK: 某文本只要该文本出现在任一诊断的 message/severity/errorCode 中即通过以及块注释形式的注解/*CHECK: ... */当诊断列号小于 //CHECK: 前缀长度时自动建议使用块注释见 [diagnostic-annotation-util.cpp](https://link.gitcode.com/i/a1263aed998ee4a9e03e43715cc092d6#L372-L408)。 ## 五、诊断测试的驱动流程从指令到断言 //DIAGNOSTIC_TEST:SIMPLE(diagCHECK): 指令由测试框架解析并驱动整条测试关键流程位于 [tools/slang-test/slang-test-main.cpp](https://link.gitcode.com/i/1c6f9b7b279757b586226f497ef11b0a) 1. **指令解析**第 774–806 行测试发现 DIAGNOSTIC_TEST 指令后用 _gatherTestOptions 收集 SIMPLE(diagCHECK) 中的选项diagCHECK 指定注解前缀并把测试类型标记为 TestOptions::Type::Diagnostic。 2. **编译并收集诊断**按普通编译流程运行此处 SIMPLE 表示直接编译该文件其标准错误输出被捕获。 3. **提取标准错误**第 886–903 行从格式化输出中定位 standard error {\n 与 \n} 之间的内容作为诊断文本。 4. **机器可读诊断解析**parseMachineReadableDiagnostics[diagnostic-annotation-util.cpp](https://link.gitcode.com/i/a1263aed998ee4a9e03e43715cc092d6#L246-L324)诊断文本按 Tab 分隔格式为 Ecode\tseverity\tfilename\tbeginLine\tbeginCol\tendLine\tendCol\tmessage其中每个字段对应诊断的错误码、严重级别、文件名、起止行列与消息severity 为 span 的行若与主诊断行列文本完全一致会被视为冗余而跳过避免 exhaustive 模式要求重复注解。 5. **注解比对**checkDiagnosticAnnotations[diagnostic-annotation-util.cpp](https://link.gitcode.com/i/a1263aed998ee4a9e03e43715cc092d6#L777-L826)将源码中的注解与机器可读诊断逐条匹配。 6. **失败反馈**若匹配失败框架不仅报错还会基于实际诊断**自动生成可复制的建议注解**generateSuggestedAnnotations[diagnostic-annotation-util.cpp](https://link.gitcode.com/i/a1263aed998ee4a9e03e43715cc092d6#L327-L438)按行分组输出 ⋮ 上下文的 //CHECK: 或 /*CHECK: 模板并提示在非穷尽模式下可使用 non-exhaustive 跳过未注解的诊断检查[diagnostic-annotation-util.cpp](https://link.gitcode.com/i/a1263aed998ee4a9e03e43715cc092d6#L752-L757)。 机器可读诊断输出由命令行选项 -enable-machine-readable-diagnostics 开启定义于 [source/slang/slang-options.cpp](https://link.gitcode.com/i/d98509581dbfbbdcc90493f40b8724ba)标志位见 [source/compiler-core/slang-diagnostic-sink.h](https://link.gitcode.com/i/dee3cea8ac26d633c1022cbf975c805c) 的 MachineReadableDiagnostics。 ## 六、匹配模式默认穷尽 vs. non-exhaustive 注解比对存在两种模式[slang-test-main.cpp](https://link.gitcode.com/i/1c6f9b7b279757b586226f497ef11b0a#L905-L906) - **默认穷尽模式exhaustive**要求每个注解都能匹配到诊断且每个诊断都至少被一个注解匹配。若有诊断未被注解覆盖测试失败并列出未注解诊断及建议注解。 - **non-exhaustive 模式**跳过诊断未被注解覆盖的检查。但若所有诊断实际都被匹配了框架反而会报Unnecessary non-exhaustive提示移除该选项回归严格模式[diagnostic-annotation-util.cpp](https://link.gitcode.com/i/a1263aed998ee4a9e03e43715cc092d6#L759-L771)。 在设计上穷尽模式能强制测试作者把**全部**预期错误写进注解防止诊断数量变化但旧断言仍然通过的漏网之鱼。diagCHECK 前缀也可换用其他名称如 diagERR同一文件甚至可存在多条不同前缀的诊断指令互不干扰。 ## 七、Literate 支持在模块系统中的配套 行号验证并非孤立机制。Slang 的模块导入系统同样把 .slang.md 视为一等公民 - [source/slang/slang-session.cpp](https://link.gitcode.com/i/9845c96f107270efb3821a661d32d4a2) 的 getFileNameFromModuleName当模块名本身以 .slang 或 literate 扩展名.md结尾时按原样作为文件名否则补全 .slang 后缀。 - [source/slang/slang-session.cpp](https://link.gitcode.com/i/71c9b9b2d4a2af0511913094dd8620dd) 的模块查找逻辑对 .slang.md 文件查找二进制模块时先剥离 .md 后缀使 Path::replaceExt 能正确生成 .slang-module 缓存名。 - tests/literate/include-literate.slang 与 include-literate-impl.slang.md 演示了普通 .slang 文件通过 __include include-literate-impl 引入 literate 实现模块import-literate-module.slang 则演示 import 导入方式[literate-helper.slang.md](https://link.gitcode.com/i/46f23b3a489a8855919da18b9c70bfb9) 提供了可被模块导入的公共函数literateAdd。 这些配套保证literate 文件不仅能作为独立测试运行还能作为被 include / import 的模块参与真实工程而行号映射机制确保这类文件中的错误同样能定位到 Markdown 原文。 ## 八、运行与验证 要亲手复现这条测试可在构建好 slang-test 后执行 bash slang-test tests/literate/diagnostic-line-number.slang.md 也可用 slangc 直接编译该 literate 文件观察诊断输出前提是编译器支持 .slang.md 输入映射表见 [source/slang/slang-options.cpp](https://link.gitcode.com/i/d02b9b886fb8036ae763a8999a781612) bash slangc tests/literate/diagnostic-line-number.slang.md【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考