Slang 编译器 CLI 选项白盒覆盖测试套件coverage/cli-options的意图、设计与维护指南【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang导读docs/generated/tests/coverage/cli-options/README.md描述的是 Slang 编译器中一套特殊的测试套件针对命令行选项解析器source/slang/slang-options.cpp的白盒特性测试white-box characterization tests。这套测试的目的是把slangc各 CLI 标志的当前可观察行为钉死下来——而不是钉住规格书应该怎么做——从而把传统测试未触及的约 140 个OptionKind::解析分支纳入回归保护。读完本文你将理解这套套件的定位与conformance/、design/测试树的区别、30 个测试各自钉住了什么行为、测试如何编写与运行、哪些代码缺口被有意跳过及其原因以及套件自身如何做漂移审查。一、套件定位第三种生成测试树要理解cli-options套件必须先理解它的上层框架。docs/generated/tests/coverage/METHODOLOGY.md明确指出这是第三个生成测试树与前两个是并列关系且刻意不同conformance/断言语言参考手册失败 规格与编译器漂移design/断言生成的设计文档失败 已固化行为的回归coverage/断言未被测试的代码的当前可观察行为失败 代码变了由人工分诊决定是修复还是回归。coverage/树存在的唯一理由以文档为锚点的生成流程在覆盖率上会遇到天花板因为文档并不能描述每一个可达分支。这套树直接针对这些分支是唯一允许通过阅读覆盖率报告和编译器源码来挑选测试的地方。这与文档锚定树_expand.md的硬规则完全相反。该树在_meta/manifest.yaml中携带role: coverage不声明source_doc只声明watched_paths即它们所描述的编译器源码。对源码的任何改动是唯一会让覆盖套件过期的因素。二、意图Intent钉住每个标志的可观察差异套件的核心意图按 README 原文是驱动slangc的 CLI 标志并钉住每个标志带来的可观察差异observable difference。设计原则非常明确只要标志存在差异测试就把带标志与不带标志默认两次运行配对使用不同的 FileCheck 前缀让选项成为观察差异的唯一原因CHECK 标记token逐字复制自真实的slangc运行输出绝不凭空编造命令行诊断被附着在合成命令行源第 0 行上因此无法绑定位置/脱字符caret锚定的注释只能通过错误码和消息文本来钉住。两代生成的内容第一代覆盖了在发射的着色器文本中可见的标志矩阵布局、#line模式、-fvk-use-entrypoint-name、-fvk-invert-y、-fvk-bind-globals外加四个选项解析错误路径。**第二代本套件主体**针对OptionsParser::_parse的其余部分——那里集中了几乎所有剩余未覆盖行约 140 个case OptionKind::分支其中大部分从未被任何随版本发布的测试进入过。本代测试分为四组分组标志带代码生成差异的标志-disable-short-circuit、-fvk-use-c-layout、-fvk-t-shift、-specialize、-enable-effect-annotations、-pass-through、-emit-spirv-via-glsl、-trace-coverage-binding、-trace-coverage-reserved-space、-source-embed-name、-no-codegen唯一可观察物是 stderr 报告的标志-dump-module、-dump-warning-diagnostics、-get-supported-module-versions、-v、-get-compiler-path操作数校验错误路径-default-downstream-compiler、-source-embed-language、-file-system、-get-module-info、-diagnostic-color唯一句柄是值能解析且编译不受影响的标志三个-file-system钩子与-Wall/-Wpedantic组。这些比差异弱测试注释中已如此标注它们存在的意义是守住解析分支而不是断言行为三、功能覆盖全表30 个测试逐一钉住什么以下表格完整继承自 README 的## Functional coverage。covers列即白盒目标源码文件本套件通过//META: covers字段命名白盒目标而非使用doc_ref旧测试仍带doc_ref指向 LLM 派生的设计文档仅作定向参考——本树的权威是源码依据 coverage/METHODOLOGY.md。测试钉住的行为coversmatrix-layout-row-major-hlsl-pragma.slang-matrix-layout-row-major使 HLSL 发射#pragma pack_matrix(row_major)默认发射column_majorsource/slang/slang-options.cppmatrix-layout-spirv-decoration.slang在 SPIR-V 中源布局发射反向的成员修饰-matrix-layout-row-major→ColMajor-matrix-layout-column-major→RowMajorsource/slang/slang-options.cppline-directive-mode-none-suppresses.slang-line-directive-mode none从 HLSL 中移除所有#line指令默认发射 C 风格#line N filesource/slang/slang-options.cppline-directive-mode-glsl-style.slang-line-directive-mode glsl发射 GLSL 数值文件 ID 的#line N 0指令source/slang/slang-options.cppfvk-use-entrypoint-name-spirv.slang-fvk-use-entrypoint-name在OpEntryPoint中保留源码入口名如fragMain默认改名为mainsource/slang/slang-options.cppfvk-invert-y-negates-position.slang-fvk-invert-y在 SV_Position.y 输出上插入一个OpFNegate无该标志时不存在source/slang/slang-options.cppfvk-bind-globals-spirv-binding.slang-fvk-bind-globals 7 3将$Globals放在 SPIR-VBinding 7/DescriptorSet 3默认为0/0source/slang/slang-options.cppunknown-option-diagnostic.slang无法识别的命令行选项以 E00017 被拒绝source/slang/slang-options.cppinvalid-optimization-level-diagnostic.slang越界的-O9以 E00062选项的未知值被拒绝source/slang/slang-options.cppinvalid-line-directive-mode-diagnostic.slang未知的-line-directive-mode值以 E00062 被拒绝source/slang/slang-options.cppunknown-profile-diagnostic.slang未知的-profile操作数以 E00014 被拒绝source/slang/slang-options.cppdisable-short-circuit-eager-operands.slang-disable-short-circuit预先求值两个操作数并发射单个if(a b)默认发射守卫右端调用的分支source/slang/slang-options.cppfvk-use-c-layout-offsets.slang-fvk-use-c-layout用 C 规则%S_c偏移 0/4/16布局常量缓冲而非 std140%S_std140偏移 0/16/28source/slang/slang-options.cppfvk-shift-binding-offset.slang-fvk-t-shift 10 space将register(t3)参数移到 VulkanBinding 13并压制该寄存器类的 E39029 警告all行为与匹配的显式空间一致source/slang/slang-options.cppspecialize-generic-entrypoint.slang-specialize Impl将泛型入口点编译为具体的Impl_get_0()调用省略它以 E38014 失败source/slang/slang-options.cppenable-effect-annotations-parse.slang-enable-effect-annotations使解析器跳过声明符后的... ;...组默认以 E20001 拒绝相同源码source/slang/slang-options.cpppass-through-emits-source.slang-pass-through glslang重现原始 Slang 源码文本而非常规的合法化 GLSL 发射source/slang/slang-options.cppemit-spirv-via-glsl-generator.slang-emit-spirv-via-glsl在 SPIR-V 1.0 上盖印Generator: Khronos Glslang Reference Front End默认在 1.5 上盖印Khronos Slang Compiler且末尾的-emit-spirv-directly胜出source/slang/slang-options.cpptrace-coverage-binding-and-reserved-space.slang-trace-coverage-binding 5 2将__slang_coverage钉在Binding 5/DescriptorSet 2-trace-coverage-reserved-space 1将自动分配从 set 1 推到 set 2source/slang/slang-options.cppsource-embed-name-and-language.slang-source-embed-name myBlob将嵌入数组从data改名-source-embed-language slang以 E00051 被拒绝source/slang/slang-options.cppno-codegen-skips-emit.slang-no-codegen仍报告前端诊断但不发射任何目标代码source/slang/slang-options.cppwarning-id-enable-and-level-groups.slang-Wid在-Wno-id之后重新启用该警告-Wall/-Wpedantic可解析且保持始终开启的 Default 组发射source/slang/slang-options.cppdiagnostic-color-ansi-escapes.slang-diagnostic-color always在非 tty 上也将诊断包裹在 ANSI SGR 转义中never保持纯文本形式未知值给出 E00062source/slang/slang-options.cppfile-system-option-values.slang-file-system接受default、load-file和os且通过每一个值编译不变未知值给出 E00062恰好列出这三个source/slang/slang-options.cppdefault-downstream-compiler-diagnostics.slang-default-downstream-compiler以 E00019 拒绝未知语言、以 E00016 拒绝未知编译器并接受c gccsource/slang/slang-options.cppdownstream-compiler-path-query.slang-get-compiler-path打印compiler path: text编译器无共享库路径时打印not available不存在时打印not found并让编译继续spirv-dis这类带连字符的名字可检验-get-/-path前后缀剥离source/slang/slang-options.cppdump-module-ir-disassembly.slang-dump-module path将文件作为模块加载并打印其 IR 反汇编entryPoint/numThreads 修饰、函数体source/slang/slang-options.cppget-module-info-missing-file.slang-get-module-info指向不存在的路径时报告 E00001 并使运行失败source/slang/slang-options.cppdump-warning-diagnostics-listing.slang-dump-warning-diagnostics打印id : name形式的警告表然后正常编译source/slang/slang-options.cppmodule-version-and-build-version-queries.slang-get-supported-module-versions打印序列化模块版本的最小/最大值-v打印构建标签两者均为 note 且编译继续source/slang/slang-options.cppdebug-info-include-source-requires-debug-info.slang-debug-info-include-source与-g0组合以 E57007 被拒绝。两个选项单独都能干净解析钉住的是事后运行的跨选项校验而非兄弟测试-O9/-profile钉的逐选项值解析source/slang/slang-options.cpp四、代表性测试的源码级剖析套件 README 是目录真正的内容在每个.slang测试里。下面选取几个代表性测试看它们如何把差异翻译成可机器校验的 FileCheck 标记。4.1 标志是唯一差异来源-fvk-invert-yfvk-invert-y-negates-position.slang 用同一着色器做四次运行配四个 FileCheck 前缀//TEST:SIMPLE(filecheckINVERT):-target spirv-asm -fvk-invert-y -entry main -stage vertex //TEST:SIMPLE(filecheckPLAIN):-target spirv-asm -entry main -stage vertex //TEST:SIMPLE(filecheckGINV):-target glsl -fvk-invert-y -entry main -stage vertex //TEST:SIMPLE(filecheckGPLN):-target glsl -entry main -stage vertex uniform float yval; [shader(vertex)] float4 main() : SV_Position { return float4(0, yval, 0, 1); } //INVERT: OpFNegate //PLAIN-NOT: OpFNegate //GINV: .y - globalParams_{{[0-9]}}.yval_{{[0-9]}} //GPLN-NOT: .y -设计要点Y 值由uniform float供给常量折叠器无法预计算取反INVERT前缀钉住OpFNegate出现PLAIN用CHECK-NOT钉住它不出现从而把选项隔离为取反的唯一原因。该测试还体现了发射扇出emission fan-outY 翻转是 Khronos 目标专属合法化GLSL 表现为对gl_Position临时量显式的.y -存储而 HLSL、Metal、WGSL 在带/不带标志时字节相同无可钉差异见 READMEUntested claims表。4.2 矩阵布局的反直觉SPIR-V 修饰matrix-layout-spirv-decoration.slang 揭示了一个文档读者无法预测的反转Slang 的矩阵约定相对 SPIR-V 是转置的因此 CLI 选择的源级布局发射相反的SPIR-V 修饰 token——//ROW: OpMemberDecorate {{.*}} 0 ColMajor //COL: OpMemberDecorate {{.*}} 0 RowMajor //HLR: #pragma pack_matrix(row_major) //GLR: layout(column_major) uniform;-matrix-layout-row-major发射ColMajor、-matrix-layout-column-major发射RowMajor。该测试覆盖 5 个目标、10 次运行spirv-asm/hlsl/glsl/metal/wgsl 各一对。Metal 和 WGSL 没有布局限定符差异体现在使用点的解包顺序行优先直接读矩阵成员列优先按转置顺序逐元素重建测试用MTR/MTC/WGR/WGC前缀钉住。因为正确性相对 SPIR-V 布局契约未独立确认该测试携带//META: characterization-unverifiedtrue。4.3 短路求值的两种降级形态-disable-short-circuitdisable-short-circuit-eager-operands.slang 的白盒目标是OptionKind::DisableShortCircuit分支。sideEffect写入缓冲区因此右操作数是否执行直接可见。默认降级为临时量 守卫分支右端调用只在第一个返回 true 时执行带标志时两个调用无条件发射为两个bool临时量测试变成平铺的if(_S1 _S2)//DEFAULT: bool {{[A-Za-z_0-9]}} sideEffect_0(int(0)); //DEFAULT: if({{[A-Za-z_0-9]}}) //DEFAULT: sideEffect_0(int(1)); //DEFAULT: else //DEFAULT: false; //EAGER: bool {{[A-Za-z_0-9]}} sideEffect_0(int(0)); //EAGER: bool {{[A-Za-z_0-9]}} sideEffect_0(int(1)); //EAGER: if({{[A-Za-z_0-9]}} {{[A-Za-z_0-9]}})所有 CHECK 标记逐字复制自真实slangc运行生成名如_S1被通配符化因为它们是附带产物。4.4 错误路径按错误码钉住合成命令行命令行的错误诊断附着在第 0 行的合成命令行源上无法用位置锚定。因此 unknown-option-diagnostic.slang 使用//DIAGNOSTIC_TEST:SIMPLE(diagCHECK)且只钉错误码//DIAGNOSTIC_TEST:SIMPLE(diagCHECK):-target hlsl -no-such-option -entry main -stage compute //CHECK: E00017同样debug-info-include-source-requires-debug-info.slang 用//CHECK: E57007钉住跨选项校验-g0与-debug-info-include-source各自都能解析但组合后请求嵌入源码却没有调试信息可嵌入拒绝发生在整组选项校验阶段区别于兄弟测试钉的逐选项值解析。4.5 报告并继续-get-compiler-pathdownstream-compiler-path-query.slang 是解析器报告后继续路径的展示。解析器剥掉固定前缀-get-与后缀-path而不是做lastIndexOf(-)扫描所以spirv-dis这种带连字符的名字能正确往返。一次运行带四个拼写覆盖结果分支的不同侧面glslang链接进构建报告真实共享库路径SLANG_OKclang是基于可执行文件的命令行编译器无可恢复的共享库路径报告not availableSLANG_E_NOT_AVAILABLEfxc仅 Windows机器上没有时报告not foundSLANG_E_NOT_FOUNDspirv-dis带连字符能解析本身就证明前后缀剥离正确。//CHECK: glslang path: {{.}} //CHECK: clang path: {{.}} //CHECK: fxc path: {{.}} //CHECK: spirv-dis path: {{.}} //CHECK: void main(最后的void main(就是该分支报告后继续解析、编译照常进行的可观察证明。4.6 覆盖着色器跟踪缓冲的两种分配方式trace-coverage-binding-and-reserved-space.slang 用同一着色器三次运行区分两个选项臂合计约 53 行未覆盖代码AUTO着色器自带一个RWStructuredBuffer占据DescriptorSet 0仅-trace-coverage时合成的__slang_coverage缓冲自动分配到Binding 0, DescriptorSet 1EXPLICIT-trace-coverage-binding 5 2覆盖为Binding 5, DescriptorSet 2该选项还隐含-trace-coverageRESERVED-trace-coverage-reserved-space 1保持自动分配但声明 set 1 禁区缓冲落到DescriptorSet 2、binding 保持 0——这正是与显式臂区分的差异。//AUTO: OpDecorate %__slang_coverage Binding 0 //AUTO-NEXT: OpDecorate %__slang_coverage DescriptorSet 1 //EXPLICIT: OpDecorate %__slang_coverage Binding 5 //EXPLICIT-NEXT: OpDecorate %__slang_coverage DescriptorSet 2 //RESERVED: OpDecorate %__slang_coverage Binding 0 //RESERVED-NEXT: OpDecorate %__slang_coverage DescriptorSet 2五、测试元数据与运行契约按 coverage/METHODOLOGY.md 的每个测试契约套件内每个.slang测试必须用真实输入驱动build/.../slangc或slangi干净编译/运行钉住观察到的输出filecheck/filecheck-buffer或诊断diag从真实输出逐字复制对区分性 token 收得紧对附带的 id/寄存器通配携带标准//META块外加//META: intentcharacterization//META: coverssource/slang/file.cpp白盒目标替代doc_ref要求正确性未确认时加//META: characterization-unverifiedtrue本树豁免于发射扇出门控和文档锚定 lint其自身 lint 要求intentcharacterization、covers目标以及至少一个匹配器。5.1 两种测试指令形式//TEST:SIMPLE(filecheckPREFIX):-target ...对输出做 FileCheckPREFIX下的//PREFIX: ...、//PREFIX-NOT: ...、//PREFIX-NEXT: ...标记按序匹配//DIAGNOSTIC_TEST:SIMPLE(diagPREFIX):-target ...匹配诊断输出如E00017、E57007用于命令行解析错误这类无源码位置的场景。5.2 相关源码锚点所有测试的白盒目标都是 source/slang/slang-options.cpp 中OptionsParser::_parse的各OptionKind::分支。例如OptionKind::VulkanInvertY-fvk-invert-y驱动一个 IR pass 在阶段输出前对 SV_Position 的 Y 分量取反OptionKind::VulkanBindShift-fvk-t-shift约 30 行从标志拼写本身读出寄存器类再读两个操作数移位量与描述符空间字面量all选择每个空间形式OptionKind::DiagnosticColor解析always/never/auto并记录模式随后由applySettingsToDiagnosticSink在 slang-compiler-options.cpp 中应用auto通过询问 writer 是否为控制台来解析OptionKind::GetCompilerPath无固定拼写剥前缀/后缀后用TypeTextUtil::findPassThrough解析中间名经getDownstreamCompilerPath取路径并打印后break继续。六、未测试的声明Untested claimsREADME 的_claims.md§2 Meaningful back-ends 要求无法扇出到某一目标的发射声明要逐目标记录。下表三行来自 README除它们之外每一对目标/声明都带有真实//TEST:SIMPLE指令钉住从slangc逐字复制的输出——没有任何东西是为了让指令变绿而放弃测试。Claim 单元格逐字重复测试的//META: purpose。Claim原因锚点为何未测试验证-fvk-invert-y在 SV_Position.y 输出上插入无标志时不存在的OpFNegateunsupported-on-target#option-set-toggles缺失目标hlsl、metal、wgsl。Y 翻转是仅应用于 Khronos 目标的 Vulkan 跨 API 合法化这三个目标上带/不带标志的输出字节相同CHECK 无可钉差异。Khronos 对spirv-asm 与 glsl都带指令验证-fvk-use-entrypoint-name在OpEntryPoint中保留源入口名而默认改名为mainunsupported-on-target#option-set-toggles缺失目标glsl、hlsl、metal、wgsl。改名为main的默认位于 SPIR-VOpEntryPoint命名路径GLSL 必须始终把入口命名为main其余三个已发射源名标志对四个目标均无差异同源上标志 vs 无标志输出字节级 diff 已验证验证-line-directive-mode glsl发射 GLSL 风格数值文件 ID#line N 0而非 C 风格#line N fileunsupported-on-target#option-set-toggles缺失目标spirv-asm。SPIR-V 完全没有#line预处理结构——源位置挂在OpLine/OpSource上且仅-g下——因此该目标上任何-line-directive-mode值都不可观察。glsl、metal、wgsl 都带指令验证-line-directive-mode none从 HLSL 输出中移除所有#line指令而默认发射 C 风格#line N fileunsupported-on-target#option-set-toggles缺失目标wgsl、spirv-asm。WGSL 默认模式不发射#linenone无可见差异只能写空洞的 CHECK-NOTspirv-asm 根本没有#line结构。glsl 和 metal 携带默认/none 对七、不可达缺口Unreachable gaps刻意不针对的分诊记录套件 README 同时是一份分诊记录说明哪些slang-options.cpp未覆盖代码被有意跳过及原因。上一代的-fvk-*-shift行已被移除该选项最终被证明可达slang-test 把源文件放在命令行首位两个操作数可干净读取现由 fvk-shift-binding-offset.slang 覆盖。选项 / 区域为何不针对-default-image-format-unknownOptionKind::DefaultImageFormatUnknown同时探测了无属性的RWTexture2Dfloat4与带[format(rgba8)]属性的。无属性图像默认已发射OpTypeImage ... Unknown且标志不覆盖显式[format]属性——范围内没有任何 slangc 输入产生与默认不同的输出。无 runner 门控路径可钉差异-capability cap值解析-capability bogus_cap报 E00014 unknown profile——能力操作数走与-profile相同的Profile::lookUp路径其错误已被unknown-profile-diagnostic.slang表征。有效的能力代码生成效果是目标/特性相关的能力门控更适合放到各目标的 design 套件-gdebug-level/-gdebug-info-formatOptionKind::DebugInformation-g2确实发射可区分的NonSemantic.Shader.DebugInfo.100导入 DebugSource但同一-g2输出在OpString操作数中嵌入完整着色器源码和绝对磁盘路径环境相关且难以确定性钉住。留给后续能稳健通配易变操作数的跟进-load-repro、-load-repro-directory、-repro-file-system、-repro-fallback-directory、-dump-repro、-extract-repro约 250 行最大单块刻意不针对。CLAUDE.md 的 Repro Tooling 将这些限定于 repro 处理本身且它们只在拿到之前 slangc 运行产生的.slang-reproblob 时才有动作——单次调用的SIMPLE指令无法准备。需要两步 harness 而非着色器测试-load-core-module、-compile-core-module、-save-core-module、-save-core-module-bin-source、-save-glsl-module-bin-source、-docOptionKind::LoadCoreModule 及邻近着色器编译不可达。这些是slang-bootstrap的构建时入口操作序列化核心模块由 source/slang-core-module/CMakeLists.txt 在构建期间驱动且要么终止运行要么写构建产物。在此测试等于重测构建而非编译器-dump-ir-ids、-dump-intermediate-prefix、-dump-ast、-serial-ir、-verify-debug-serial-ir明确列于 CLAUDE.md § AVOID These Debugging Options未维护/不可靠。-dump-ir-ids还仅 debug 构建可用在套件运行的 RelWithDebInfo 构建中是空操作OptionKind::WarningLevel分支中的SLANG_UNEXPECTED(unhandled -W warning-level flag)防御性。只有-Wall、-Wextra、-Wpedantic注册为WarningLevel拼写任何 argv 都到不了else。分支注释已说明。正确的不针对-emit-cpu-via-cpp、-emit-cpu-via-llvm、-llvm-target-triple、-llvm-cpu、-llvm-featuresOptionKind::EmitCPUViaLLVM 及邻近可达且被接受五个都能对-target cpp干净解析编译但无一改变任何文本输出的字节它们选择 CPU 后端及其代码生成调优只有运行产物二进制才可观察。特性测试钉不住任何东西。留给宿主执行 harness-zero-initialize、-parameter-blocks-use-register-spaces、-ir-compression、-archive-type已弃用或惰性。-zero-initialize为兼容而接受且其行为现已是默认-ir-compression被解析后丢弃源码带TODO: warn that this option is deprecated-archive-type只影响容器输出。无差异可钉钉无差异只会锁死弃用状态-embed-downstream-irOptionKind::EmbedDownstreamIR按现状不可测除spirv外每个目标都以 255 退出且零诊断输出。按 METHODOLOGY崩溃/中止/内部错误/畸形输出是 finding 而非测试记录为 findingcli-embed-downstream-ir-silent-failure-get-module-info作用于可读的非 IR 文件同样原因以 1 退出且无任何输出。记录为 findingcli-get-module-info-non-ir-file-silent-failure。只有无法打开分支被 get-module-info-missing-file.slang 表征-Ipath/-I pathOptionKind::Include、-conformance、-reflection-json、-separate-debug-info-output、-module-name可达但各自需要磁盘上的第二个文件——头文件、第二个模块或输出 sidecar——而 bundle 目录只放*.slang测试放非测试.slang会被 bundle glob 捡走。留给能用_fixtures/约定的跟进-verbose-pathsOptionKind::VerbosePaths可达但每次探测相对/绝对输入路径、警告与错误诊断都与默认产生字节相同诊断。它选择的规范路径渲染对单文件编译似乎无差异无可钉内容findGlslProfileFromPath约 27 行仅在编译.vert/.frag/.comp/... 且无显式-profile/-stage时被调用。那是 GLSL 输入领域-allow-glsl属于 GLSL 前端测试而非选项解析器该函数本身除返回的 profile 外无 CLI 可见行为八、观察到的文档缺口Doc gaps observed套件在钉行为的同时也反向检查文档凡可达行为本应被记录而未记录就反馈给文档树。锚点类型缺口建议补充#option-set-togglesundocumented-behaviorSPIR-V 的 option-set-toggles 一节未说明CLI 选择的源级矩阵布局会发射相反的 SPIR-V 成员修饰 token-matrix-layout-row-major→ColMajor反之亦然源于 Slang 的转置矩阵约定。期望RowMajor的读者会意外在矩阵布局 toggle 行加一行说明发射的 SPIR-V 修饰是源布局的转置——行优先源发射ColMajor反之亦然#error-code-namespaceundocumented-behavior命令行选项解析诊断E00017、E00062、E00014附着于合成命令行源第 0 行而非翻译单元内任何文件。诊断文档的渲染一节未提及该命令行虚拟源测试作者无法预知位置/脱字符锚定注释绑定不上只能做错误码匹配加一小段说明 CLI 解析诊断使用合成命令行SourceView基于位置的匹配器应按错误码钉住而非按文件行/列#option-set-togglesundocumented-behavior提供任何-fvk-class-shift都会给未移位的参数重新编号。Texture2D tex : register(t3); SamplerState samp : register(s1); RWStructuredBuffer outBuf : register(u2);默认绑定为 3/1/2加-fvk-t-shift 10 0后变为 13/0/1——samp和outBuf即便没有给s/u移位也移动了。文档只描述移位影响被移位的寄存器类在绑定移位行注明引入移位会对每个无显式 Vulkan 绑定的参数重新运行自动分配未移位的参数也可能移动给出上面三参数示例#source-locations-and-message-renderingundocumented-behavior-diagnostic-color always改变的不仅是颜色整个诊断从 ASCII 框-- file:line:col、\|、^切换到 Unicode 框线框╭╼、│、━并包裹 ANSI SGR 转义。渲染一节只记录 ASCII 形式解析 slangc 诊断的消费者无从得知框线字符本身是颜色模式相关的加一个小节展示同一诊断的两种渲染并说明-diagnostic-color在两者间选择auto通过询问 writer 是否为控制台解析因此管道输出得到 ASCII 形式九、兄弟套件重叠与漂移审查9.1 与目标管线套件的重叠-matrix-layout-*的发射形态也能从目标管线设计套件练习到本套件专门把它钉为CLI 选项驱动的差异标志 vs 无标志这才是这里的白盒目标slang-options.cpp而非作为目标代码生成声明。9.2 漂移审查Drift review套件 README 记录了最近一次漂移审查在d592afa9b9对照生成基准提交ef1068b548审查。期间 23 个提交触及 watched paths全部 30 个既有测试仍通过。审查还发现基准提交之后有三个新诊断从slang-options.cpp抛出E45113-trace-coverage-counter-width值与 E57006冲突的描述符堆步长选项已有手写测试E57007 此前没有任何测试钉住本次新增为 debug-info-include-source-requires-debug-info.slang。它值得与兄弟-O9/-profile测试分开存在因为这是不同类型的检查-g0与-debug-info-include-source各自都能干净解析拒绝发生在之后整组选项被校验时。窗口期内还出现了六个新选项-debug-info-include-source、-separate-debug-info-output、-spirv-unified-descriptor-heap-stride、-trace-coverage-bindless-index、-trace-coverage-boolean、-trace-coverage-counter-width。增加上述一个测试后套件达 31 个文件逼近 30 个的软上限其余选项留给未来扩展轮而非继续突破上限。十、给测试作者与维护者的实践要点综合 README 与 METHODOLOGY.md向本套件或类似套件添加测试时有几条硬性纪律先分诊只针对可达缺口大部分未覆盖行不值得或不可能针对。按类别处理——可从 CLI 到达则针对runner 门控需要 GPU/DXC/nvrtc/Metal 工具链则写//META: requires-tool...防御性/不可达、死代码则不针对并在 bundle README 的## Unreachable gaps记录原因。分诊图本身是交付物它揭示了真实的可达上限。钉真实观察输出运行 slangc、逐字复制绝不发明。无法确认行为正确时加//META: characterization-unverifiedtrue标签让人类/规格审查可复查仅在带此标签时允许钉住未验证行为。崩溃/畸形输出是 finding不是测试按 METHODOLOGY 记入_meta/findings/例如本套件的cli-embed-downstream-ir-silent-failure与cli-get-module-info-non-ir-file-silent-failure。收窄 CHECK 到区分性 token对附带 id/寄存器通配对唯一造成差异的 token 收紧CHECK-NOT/CHECK-NEXT是钉无差异与顺序的常用工具。不要把 bug 固化为预期这是本树常驻风险——针对错误分支写的测试会锁死 bug。缓解手段就是第 2、3 条。【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考