Slang 构建依赖图文档的评审修复子系统粒度、链接不变量与生成式架构文档的质量闭环【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang导读本文围绕 Slang 开源仓库中 docs/generated/design/architecture/dependency-graph.md 及其评审修复报告 dependency-graph.md.remediation.md 展开完整还原这份子系统级构建依赖图文档的成文逻辑、CMake 证据链以及一次真实的评审 → 修复质量闭环三个评审发现F-001/F-002/F-003如何被逐条核实并修复。读完本文你将掌握 Slang 源码树中source/各子系统之间的静态链接关系、四个生成代码目标的真实身份以及SLANG_EMBED_CORE_MODULE等关键 CMake 选项对构建结构的影响同时理解该仓库如何用机器可校验的生成式文档防止架构文档与源码漂移。一、背景生成式架构文档与评审 → 修复闭环Slang 项目维护了一套由 AI 代理生成、经脚本驱动的架构文档位于docs/generated/design/下。这类文档不是手写草稿而是由 regenerate.md 描述的流水线产出每份文档对应一份提示词模板如 architecture-dependency-graph.md模板定义文档必须包含的章节、粒度规则与质量清单每个文档有被监视路径watched paths与内容摘要digestregenerate.py list-stale可以判定文档是missing、stale还是fresh文档头部 front-matter 记录source_commit、watched_paths_digest并带有警告Auto-generated. May drift from source. Do not edit by hand.——意味着文档只允许重新生成不允许手工修补。在这套体系之上还有一个显式的质量关卡评审报告review与修复报告remediation。本主题的修复报告由claude-opus-5于2026-08-04T09:06:00Z生成针对的评审报告来自gpt-5.6-soldependency-graph.md.review.md修复前后的源码提交均为53b76e6d3009b8e6434d41573524c7ce5c499d23动作统计为fixed: 3其余拒绝伪发现、超出范围、延迟、升级均为 0——即三个发现全部属实并已修复。修复报告的结构规范见 _remediate.md要求以表格逐条给出 Finding ID、Action、Rationale 与 Fix summary动作计数必须与评审报告的finding_count一致。二、被评审的文档讲了什么子系统级构建依赖图2.1 粒度定义子系统级而非文件级依赖图文档的核心定位是预测修改某个子系统时会波及其他哪些子系统。其粒度被严格限定为子系统级——一个节点对应一个source/subsystem/目录而不是单个文件。文件级清单由 module-map.md 承担文档开篇即明确两者的分工依赖图本文主题source/下各子系统之间的静态链接依赖模块映射module-map.md每个子系统内文件的逻辑单元与职责。这份文档的边并非拍脑袋画出来的而是逐条从各目录CMakeLists.txt的slang_add_target(... LINK_WITH_PRIVATE ...)与LINK_WITH_PUBLIC子句中推导得到。提示词模板 architecture-dependency-graph.md 的硬性要求包括图中每个节点必须对应source/下的目录或module-map.md中的标题模板第 42-44 行每条边必须有CMakeLists.txt引用作为依据禁止发明构建文件未证实的边Mermaid 语法遵循项目约定camelCase 节点 ID、节点名不含空格、不着色文档体积不得超过 16 KB。2.2 依赖图全貌修复后的最终形态修复后的 Mermaid 图只保留真正的子系统节点外部依赖miniz、lz4_static、Threads::Threads、unordered_dense、fast_float、SPIRV-Headers、SPIRV-Tools-opt、SPIRV-Tools-link、SPIRV、glslang、${CMAKE_DL_LIBS}全部从图中省略仅在节点注释中概述以保持图聚焦于项目内部结构注意其中两条特殊边coreModule --|generated targets| slangLib是一条带标签的实线边语义并非slang-core-module 链接了编译器库而是它链接了source/slang/所拥有的生成产物详见 3.1 节 F-001 的修复slangLib -.-|source include| slangRecordReplay是虚线边它不是LINK_WITH_*链接关系而是源文件并入关系。三个在 module-map.md 中存在、但在图中没有普通链接边的子系统也需要特别说明source/standard-modules/其 CMakeLists.txt 只configure_file一个配置头并add_subdirectoryneural、experimental、numerics三个模块不声明自己的链接目标模块产物以独立的.slang-module文件形式发布source/slang-record-replay/没有自己的CMakeLists.txt源码通过source/slang/CMakeLists.txt中的EXTRA_SOURCE_DIRS ${SLANG_RECORD_REPLAY_SYSTEM}直接并入slang目标即图中的虚线边source/slang-llvm/同样没有自己的CMakeLists.txtslang-llvm在树外构建或下载预编译二进制由根 CMakeLists.txt 第 385-401 行的SLANG_SLANG_LLVM_FLAVOR控制源码树内没有任何目标直接链接它。三、三个评审发现与修复从看起来对到逐条可核实这是本主题修复报告的核心。评审报告发现 3 个问题1 个 major、2 个 minor修复报告全部核实并修复。下面逐条还原问题 → 证据 → 修复。3.1 F-001major生成代码 target 混入子系统图问题原图中slang-fiddle-output、slang-capability-defs、slang-capability-lookup、slang-lookup-tables被画成了独立节点。但它们是定义在source/slang/内部的 CMake 构建目标既不是source/下的子系统目录也不是module-map.md的标题违反了提示词每个节点必须对应 source 目录或 module-map 标题的节点覆盖规则导致图混用了目标级与子系统级两种抽象。证据评审报告核实四个目标分别定义于 source/slang/CMakeLists.txt 的slang-fiddle-output第 56-66 行INTERFACE 库由slang-fiddle工具生成 AST/IR 支持代码、能力相关目标第 119-143 行区域与slang-lookup-tables第 198-210 行OBJECT 库。从源码可以进一步确认它们的生成机制slang-fiddle-output由自定义命令驱动slang-fiddle工具把*.lua与 FIDDLE 输入生成到SLANG_FIDDLE_OUTPUT_DIR再用一个.fiddle.stamp时间戳文件作为产出标记避免陈旧 mtime 干扰增量构建source/slang/CMakeLists.txtslang-capability-defs/slang-capability-lookup由slang-capability-generator从*.capdef生成能力表头文件与查找源码slang-generated-capability-defs.h、slang-lookup-capability-defs.cpp等生成时还会同步刷新 a4-02-reference-capability-atoms.md 这份用户文档slang-lookup-tables由slang-spirv-embed-generator从 SPIR-V 核心文法 JSON 生成查表源码是 OBJECT 库LINK_WITH_PRIVATE core SPIRV-Headers::SPIRV-Headers。修复从图中移除这 4 个节点及其 14 条边改为在图后以文字段落描述它们及其消费者slang与slang-wasm都消费这些生成目标新增coreModule → slangLib的generated targets标签边把slang-core-module对source/slang/生成产物的依赖显式化——因为 source/slang-core-module/CMakeLists.txt 第 60-64 行的LINK_WITH_PRIVATE列表里同时含有core、slang-capability-defs和slang-fiddle-output也就是说它依赖source/slang/拥有的生成产物却并不链接编译器库本身同时把## Edge citations表格中原来逐 target 的 4 行折叠并改写slang与slang-wasm两行的措辞。修复后文档从 16384 字节上限内的 10661 字节变为 12275 字节regenerate.py lint通过。3.2 F-002minor源归属不变量在嵌入式构建下不成立问题原文档断言主库slang是唯一拉入 AST/IR/emit/check 源码的目标the only target。当SLANG_EMBED_CORE_MODULE开启时这个说法是错的。证据从 source/slang/CMakeLists.txt 可以看到两条构建路径的分叉SLANG_EMBED_CORE_MODULE关闭时直接slang_add_target(. ${SLANG_LIB_TYPE} ...)正常构建slang源文件由slang自己持有slang-without-embedded-core-module只是它的 ALIASSLANG_EMBED_CORE_MODULE开启时第 322-329 行先以.为源目录声明一个 OBJECT 库slang-common-objects把整目录源码编译成对象文件随后第 330-358 行声明的两个库目标slang-without-embedded-core-module与主slang均带NO_SOURCE只通过LINK_WITH_PRIVATE slang-common-objects链接这些对象。换言之真正持有 AST/IR/emit/check 源码的源归属目标在两种模式下不同。修复把不变量的表述从目标级降为子系统级明确写出非嵌入式构建中源归属目标是slangSLANG_EMBED_CORE_MODULE开启时则是slang-common-objects。这也与文档 Cycles and known irregularities 一节中关于slang-common-objects间接层的描述同一批源文件被编译成对象库后再重链接进两个库以便随编译器一同发布无嵌入式 core module 的生成器保持一致消除了文档内部的自相矛盾。顺带一提同文件中slang目标的链接清单第 270-281 行把core、prelude、compiler-core、slang-capability-defs、slang-capability-lookup、slang-fiddle-output、slang-lookup-tables、SPIRV-Headers、libcmark-gfm全部列为LINK_WITH_PRIVATE——这正是图中slang → {core, prelude, compiler-core, core-module}多条边以及生成目标消费关系的直接依据其中prelude实际是私有 include 依赖而非静态链接文档专门注明这一点以与 module-map.md 对齐。3.3 F-003minor过时的根 CMake 行号引用问题原文档在slang-llvm注释中把SLANG_SLANG_LLVM_FLAVOR说成位于根CMakeLists.txtaround line 366实际行号偏差约 20 行。证据评审报告核实根 CMakeLists.txt 第 366 行声明的是SLANG_ENABLE_RELEASE_DEBUG_INFOSLANG_SLANG_LLVM_FLAVOR是第 386 行的enum_option标识符其处理逻辑延伸到第 401 行。修复把引用改为lines 385-401。这个细节看似微小但对机器校验驱动的文档体系意义重大——行号是评审与再生成时核对的重点过期行号会让后续自动化核对产生误报。四、修复后沉淀的构建不变量可逐条对证的架构规则修复后的## Notable invariants一节给出若干方向性约束每一条都有具体的构建文件背书source/core/不依赖任何内部子系统。从 source/core/CMakeLists.txt 可见其LINK_WITH_PRIVATE只列外部库miniz lz4_static Threads::Threads ${CMAKE_DL_LIBS}LINK_WITH_PUBLIC只有unordered_densesource/compiler-core/可依赖source/core/但不得依赖source/slang/。其 CMakeLists.txt 只有LINK_WITH_PRIVATE core fast_floatfast_float用于快速浮点解析source/slang/是唯一拉入 AST/IR/emit/check 源码的子系统具体源归属目标见 3.2 节的两种模式其他需要编译服务的二进制如slangc见 source/slangc/CMakeLists.txt 的LINK_WITH_PRIVATE core slang都链接slang而不是逐文件接入能力子系统拆分为两个库slang-capability-defs生成的头文件库与slang-capability-lookup生成的源码库主slang目标同时消费两者核心模块可选链接SLANG_EMBED_CORE_MODULE通过 source/slang/CMakeLists.txt 的生成器表达式在slang-embedded-core-module与slang-no-embedded-core-module之间选择当该选项关闭且SLANG_LIB_TYPE为SHARED时同文件还会新增generate_core_module_cache目标用slang-core-module-cache工具处理新链接的库与source/slang-core-module/产出的core_module_archive_without_timestamp归档在库旁写出slang-core-module.bin——这是对tools/下目标的构建顺序依赖而非链接边且把库文件的时间戳纳入缓存有效性slang-rt不依赖编译器它随 CPU 目标输出一起发布LINK_WITH_PRIVATE中没有任何编译器内部库但不链接不等于源码无关——其 CMakeLists.txt 通过EXTRA_SOURCE_DIRS ${slang_SOURCE_DIR}/source/core把source/core/的源码以SLANG_RT_DYNAMIC_EXPORT重新编译进运行时并配置INCLUDE_DIRECTORIES_PRIVATE ${slang_SOURCE_DIR}/source使这些源码能解析#include core/slang-basic.h这类直连路径包含slang-glslang的导出面由一份文件限定而非编译器可见性设置CXX_VISIBILITY_PRESET hidden与-Wl,--exclude-libs,ALL只能隐藏自身与静态链接依赖的非导出符号真正一锤定音的是slang-glslang.version-script。ELF 直接消费该文件Mach-O 没有 version-script 概念因此同一份 CMake 在 configure 阶段解析脚本的global:块推导出-exported_symbols_list每个符号加 ld64 前缀下划线如glslang_compile→_glslang_compile并且解析逻辑被写成宁可报错也不静默漏导出——提取不到任何名字、或移除name;条目后还有残留字符时都会message(FATAL_ERROR)。对贡献者的实际含义记录在 shim 头文件注释中新增导出入口必须同时加入 version-script否则在 ELF 与 macOS 上都不会被导出include/公共头不得包含source/私有头这是项目规则而非构建系统约束见 CLAUDE.md遵守它才能保证下游用户只需消费include/slang.h。五、循环与已知异常评审与修复都确认各目录 CMake 文件中未观察到链接级循环文档明确写出 No link-level cycles are observed。但有两处值得知道的异常slang库向上侵入 tools 树取头文件source/slang/CMakeLists.txt 把${slang_SOURCE_DIR}/tools加入INCLUDE_DIRECTORIES_PRIVATE这让slang-language-server.cpp能编译#include platform/performance-counter.h来自 tools/platform。没有伴随链接边——头文件只用于其内联定义——但意味着tools/platform/不能随意搬移而不触碰库slang-common-objects间接层见 3.2 节某些配置模式下同一批源文件先编译成对象库再被重链接进slang-without-embedded-core-module与主slang这是为了随用户可见的slang一并发布无嵌入式 core module 的编译器生成器而做的构建系统便利。六、外部依赖清单图外的真实链接面图内只画内部结构但每个节点的外部依赖在节点注释与 Edge citations 一节 中均有交代节点主要外部依赖依据文件coreminiz、lz4_static、Threads::Threads、unordered_dense、${CMAKE_DL_LIBS}SLANG_ENABLE_MIMALLOC开启时 PUBLIC 链接mimalloc-static并传播SLANG_ENABLE_MIMALLOC1编译定义配置阶段若找不到mimalloc-static目标会直接硬失败source/core/CMakeLists.txtcompiler-corefast_float除内部core链接外source/compiler-core/CMakeLists.txtslang、slang-wasmSPIRV-Headerswasm 目标另有miniz、lz4_staticsource/slang/CMakeLists.txt、source/slang-wasm/CMakeLists.txtslang-rtminiz、lz4_static、Threads、unordered_dense、${CMAKE_DL_LIBS}无任何 Slang 内部库依赖source/slang-rt/CMakeLists.txtslang-glslangglslang、SPIRV、SPIRV-Tools-opt、SPIRV-Tools-linksource/slang-glslang/CMakeLists.txtslang-lookup-tablesSPIRV-Headerssource/slang/CMakeLists.txt完整的逐边引用表Edge citations覆盖了图中每一条实线边例如compiler-core → core对应 source/compiler-core/CMakeLists.txt 的LINK_WITH_PRIVATE corecore-module → {core, slang}对应 source/slang-core-module/CMakeLists.txt 的LINK_WITH_PRIVATE core slang-capability-defs slang-fiddle-outputslang-wasm → {slang, core, compiler-core}对应 wasm 目标上的LINK_WITH_PRIVATE miniz lz4_static slang core compiler-core slang-capability-defs slang-capability-lookup slang-fiddle-output slang-lookup-tables虚线边slang -.- slang-record-replay则只由EXTRA_SOURCE_DIRS源列表包含所证明不依赖任何LINK_WITH_*子句。七、这套质量闭环对我们意味着什么把评审报告、修复报告与最终文档放在一起看可以得到几条方法论层面的结论文档的粒度纪律是被强制执行的。提示词模板规定节点必须对应 source 目录或 module-map 标题评审据此抓出了四个目标混入子系统图的节点修复时没有简单地把它们从图中删掉就完事而是用带标签的边和文字段落保住了信息量coreModule →|generated targets| slangLib反而比原来更准确地表达了跨子系统依赖生成产物但不链接编译器这一微妙关系不变量必须区分构建模式。SLANG_EMBED_CORE_MODULE开关会改变源归属目标、核心模块链接方式甚至动态库缓存生成逻辑——把唯一持有源码的目标写成绝对化断言在另一种配置下就会失真修复后的表述slang或slang-common-objects才是可移植的真相行号、字节上限、digest 都是校验资产。regenerate.py lint会检查 front-matter 键、链接可解析性与 16 KB 体积上限watched_paths_digest与source_commit让任何一次源码变动都能被标记为stale。修复报告特别指出文档现为 12275 字节低于 16384 字节上限regenerate.py lint通过——这就是机器可验证的完成定义。如果你正想深入 Slang 源码文件级清单请查阅 module-map.md运行时数据流而非构建依赖请沿 pipeline/overview.md 的编译流水线继续追踪而本主题的完整证据链——评审报告、修复报告、提示词模板与被监视的 CMake 文件——都可以在 docs/generated/design/_meta 目录下对照阅读。【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Slang 构建依赖图文档的评审修复：子系统粒度、链接不变量与生成式架构文档的质量闭环
Slang 构建依赖图文档的评审修复子系统粒度、链接不变量与生成式架构文档的质量闭环【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang导读本文围绕 Slang 开源仓库中 docs/generated/design/architecture/dependency-graph.md 及其评审修复报告 dependency-graph.md.remediation.md 展开完整还原这份子系统级构建依赖图文档的成文逻辑、CMake 证据链以及一次真实的评审 → 修复质量闭环三个评审发现F-001/F-002/F-003如何被逐条核实并修复。读完本文你将掌握 Slang 源码树中source/各子系统之间的静态链接关系、四个生成代码目标的真实身份以及SLANG_EMBED_CORE_MODULE等关键 CMake 选项对构建结构的影响同时理解该仓库如何用机器可校验的生成式文档防止架构文档与源码漂移。一、背景生成式架构文档与评审 → 修复闭环Slang 项目维护了一套由 AI 代理生成、经脚本驱动的架构文档位于docs/generated/design/下。这类文档不是手写草稿而是由 regenerate.md 描述的流水线产出每份文档对应一份提示词模板如 architecture-dependency-graph.md模板定义文档必须包含的章节、粒度规则与质量清单每个文档有被监视路径watched paths与内容摘要digestregenerate.py list-stale可以判定文档是missing、stale还是fresh文档头部 front-matter 记录source_commit、watched_paths_digest并带有警告Auto-generated. May drift from source. Do not edit by hand.——意味着文档只允许重新生成不允许手工修补。在这套体系之上还有一个显式的质量关卡评审报告review与修复报告remediation。本主题的修复报告由claude-opus-5于2026-08-04T09:06:00Z生成针对的评审报告来自gpt-5.6-soldependency-graph.md.review.md修复前后的源码提交均为53b76e6d3009b8e6434d41573524c7ce5c499d23动作统计为fixed: 3其余拒绝伪发现、超出范围、延迟、升级均为 0——即三个发现全部属实并已修复。修复报告的结构规范见 _remediate.md要求以表格逐条给出 Finding ID、Action、Rationale 与 Fix summary动作计数必须与评审报告的finding_count一致。二、被评审的文档讲了什么子系统级构建依赖图2.1 粒度定义子系统级而非文件级依赖图文档的核心定位是预测修改某个子系统时会波及其他哪些子系统。其粒度被严格限定为子系统级——一个节点对应一个source/subsystem/目录而不是单个文件。文件级清单由 module-map.md 承担文档开篇即明确两者的分工依赖图本文主题source/下各子系统之间的静态链接依赖模块映射module-map.md每个子系统内文件的逻辑单元与职责。这份文档的边并非拍脑袋画出来的而是逐条从各目录CMakeLists.txt的slang_add_target(... LINK_WITH_PRIVATE ...)与LINK_WITH_PUBLIC子句中推导得到。提示词模板 architecture-dependency-graph.md 的硬性要求包括图中每个节点必须对应source/下的目录或module-map.md中的标题模板第 42-44 行每条边必须有CMakeLists.txt引用作为依据禁止发明构建文件未证实的边Mermaid 语法遵循项目约定camelCase 节点 ID、节点名不含空格、不着色文档体积不得超过 16 KB。2.2 依赖图全貌修复后的最终形态修复后的 Mermaid 图只保留真正的子系统节点外部依赖miniz、lz4_static、Threads::Threads、unordered_dense、fast_float、SPIRV-Headers、SPIRV-Tools-opt、SPIRV-Tools-link、SPIRV、glslang、${CMAKE_DL_LIBS}全部从图中省略仅在节点注释中概述以保持图聚焦于项目内部结构注意其中两条特殊边coreModule --|generated targets| slangLib是一条带标签的实线边语义并非slang-core-module 链接了编译器库而是它链接了source/slang/所拥有的生成产物详见 3.1 节 F-001 的修复slangLib -.-|source include| slangRecordReplay是虚线边它不是LINK_WITH_*链接关系而是源文件并入关系。三个在 module-map.md 中存在、但在图中没有普通链接边的子系统也需要特别说明source/standard-modules/其 CMakeLists.txt 只configure_file一个配置头并add_subdirectoryneural、experimental、numerics三个模块不声明自己的链接目标模块产物以独立的.slang-module文件形式发布source/slang-record-replay/没有自己的CMakeLists.txt源码通过source/slang/CMakeLists.txt中的EXTRA_SOURCE_DIRS ${SLANG_RECORD_REPLAY_SYSTEM}直接并入slang目标即图中的虚线边source/slang-llvm/同样没有自己的CMakeLists.txtslang-llvm在树外构建或下载预编译二进制由根 CMakeLists.txt 第 385-401 行的SLANG_SLANG_LLVM_FLAVOR控制源码树内没有任何目标直接链接它。三、三个评审发现与修复从看起来对到逐条可核实这是本主题修复报告的核心。评审报告发现 3 个问题1 个 major、2 个 minor修复报告全部核实并修复。下面逐条还原问题 → 证据 → 修复。3.1 F-001major生成代码 target 混入子系统图问题原图中slang-fiddle-output、slang-capability-defs、slang-capability-lookup、slang-lookup-tables被画成了独立节点。但它们是定义在source/slang/内部的 CMake 构建目标既不是source/下的子系统目录也不是module-map.md的标题违反了提示词每个节点必须对应 source 目录或 module-map 标题的节点覆盖规则导致图混用了目标级与子系统级两种抽象。证据评审报告核实四个目标分别定义于 source/slang/CMakeLists.txt 的slang-fiddle-output第 56-66 行INTERFACE 库由slang-fiddle工具生成 AST/IR 支持代码、能力相关目标第 119-143 行区域与slang-lookup-tables第 198-210 行OBJECT 库。从源码可以进一步确认它们的生成机制slang-fiddle-output由自定义命令驱动slang-fiddle工具把*.lua与 FIDDLE 输入生成到SLANG_FIDDLE_OUTPUT_DIR再用一个.fiddle.stamp时间戳文件作为产出标记避免陈旧 mtime 干扰增量构建source/slang/CMakeLists.txtslang-capability-defs/slang-capability-lookup由slang-capability-generator从*.capdef生成能力表头文件与查找源码slang-generated-capability-defs.h、slang-lookup-capability-defs.cpp等生成时还会同步刷新 a4-02-reference-capability-atoms.md 这份用户文档slang-lookup-tables由slang-spirv-embed-generator从 SPIR-V 核心文法 JSON 生成查表源码是 OBJECT 库LINK_WITH_PRIVATE core SPIRV-Headers::SPIRV-Headers。修复从图中移除这 4 个节点及其 14 条边改为在图后以文字段落描述它们及其消费者slang与slang-wasm都消费这些生成目标新增coreModule → slangLib的generated targets标签边把slang-core-module对source/slang/生成产物的依赖显式化——因为 source/slang-core-module/CMakeLists.txt 第 60-64 行的LINK_WITH_PRIVATE列表里同时含有core、slang-capability-defs和slang-fiddle-output也就是说它依赖source/slang/拥有的生成产物却并不链接编译器库本身同时把## Edge citations表格中原来逐 target 的 4 行折叠并改写slang与slang-wasm两行的措辞。修复后文档从 16384 字节上限内的 10661 字节变为 12275 字节regenerate.py lint通过。3.2 F-002minor源归属不变量在嵌入式构建下不成立问题原文档断言主库slang是唯一拉入 AST/IR/emit/check 源码的目标the only target。当SLANG_EMBED_CORE_MODULE开启时这个说法是错的。证据从 source/slang/CMakeLists.txt 可以看到两条构建路径的分叉SLANG_EMBED_CORE_MODULE关闭时直接slang_add_target(. ${SLANG_LIB_TYPE} ...)正常构建slang源文件由slang自己持有slang-without-embedded-core-module只是它的 ALIASSLANG_EMBED_CORE_MODULE开启时第 322-329 行先以.为源目录声明一个 OBJECT 库slang-common-objects把整目录源码编译成对象文件随后第 330-358 行声明的两个库目标slang-without-embedded-core-module与主slang均带NO_SOURCE只通过LINK_WITH_PRIVATE slang-common-objects链接这些对象。换言之真正持有 AST/IR/emit/check 源码的源归属目标在两种模式下不同。修复把不变量的表述从目标级降为子系统级明确写出非嵌入式构建中源归属目标是slangSLANG_EMBED_CORE_MODULE开启时则是slang-common-objects。这也与文档 Cycles and known irregularities 一节中关于slang-common-objects间接层的描述同一批源文件被编译成对象库后再重链接进两个库以便随编译器一同发布无嵌入式 core module 的生成器保持一致消除了文档内部的自相矛盾。顺带一提同文件中slang目标的链接清单第 270-281 行把core、prelude、compiler-core、slang-capability-defs、slang-capability-lookup、slang-fiddle-output、slang-lookup-tables、SPIRV-Headers、libcmark-gfm全部列为LINK_WITH_PRIVATE——这正是图中slang → {core, prelude, compiler-core, core-module}多条边以及生成目标消费关系的直接依据其中prelude实际是私有 include 依赖而非静态链接文档专门注明这一点以与 module-map.md 对齐。3.3 F-003minor过时的根 CMake 行号引用问题原文档在slang-llvm注释中把SLANG_SLANG_LLVM_FLAVOR说成位于根CMakeLists.txtaround line 366实际行号偏差约 20 行。证据评审报告核实根 CMakeLists.txt 第 366 行声明的是SLANG_ENABLE_RELEASE_DEBUG_INFOSLANG_SLANG_LLVM_FLAVOR是第 386 行的enum_option标识符其处理逻辑延伸到第 401 行。修复把引用改为lines 385-401。这个细节看似微小但对机器校验驱动的文档体系意义重大——行号是评审与再生成时核对的重点过期行号会让后续自动化核对产生误报。四、修复后沉淀的构建不变量可逐条对证的架构规则修复后的## Notable invariants一节给出若干方向性约束每一条都有具体的构建文件背书source/core/不依赖任何内部子系统。从 source/core/CMakeLists.txt 可见其LINK_WITH_PRIVATE只列外部库miniz lz4_static Threads::Threads ${CMAKE_DL_LIBS}LINK_WITH_PUBLIC只有unordered_densesource/compiler-core/可依赖source/core/但不得依赖source/slang/。其 CMakeLists.txt 只有LINK_WITH_PRIVATE core fast_floatfast_float用于快速浮点解析source/slang/是唯一拉入 AST/IR/emit/check 源码的子系统具体源归属目标见 3.2 节的两种模式其他需要编译服务的二进制如slangc见 source/slangc/CMakeLists.txt 的LINK_WITH_PRIVATE core slang都链接slang而不是逐文件接入能力子系统拆分为两个库slang-capability-defs生成的头文件库与slang-capability-lookup生成的源码库主slang目标同时消费两者核心模块可选链接SLANG_EMBED_CORE_MODULE通过 source/slang/CMakeLists.txt 的生成器表达式在slang-embedded-core-module与slang-no-embedded-core-module之间选择当该选项关闭且SLANG_LIB_TYPE为SHARED时同文件还会新增generate_core_module_cache目标用slang-core-module-cache工具处理新链接的库与source/slang-core-module/产出的core_module_archive_without_timestamp归档在库旁写出slang-core-module.bin——这是对tools/下目标的构建顺序依赖而非链接边且把库文件的时间戳纳入缓存有效性slang-rt不依赖编译器它随 CPU 目标输出一起发布LINK_WITH_PRIVATE中没有任何编译器内部库但不链接不等于源码无关——其 CMakeLists.txt 通过EXTRA_SOURCE_DIRS ${slang_SOURCE_DIR}/source/core把source/core/的源码以SLANG_RT_DYNAMIC_EXPORT重新编译进运行时并配置INCLUDE_DIRECTORIES_PRIVATE ${slang_SOURCE_DIR}/source使这些源码能解析#include core/slang-basic.h这类直连路径包含slang-glslang的导出面由一份文件限定而非编译器可见性设置CXX_VISIBILITY_PRESET hidden与-Wl,--exclude-libs,ALL只能隐藏自身与静态链接依赖的非导出符号真正一锤定音的是slang-glslang.version-script。ELF 直接消费该文件Mach-O 没有 version-script 概念因此同一份 CMake 在 configure 阶段解析脚本的global:块推导出-exported_symbols_list每个符号加 ld64 前缀下划线如glslang_compile→_glslang_compile并且解析逻辑被写成宁可报错也不静默漏导出——提取不到任何名字、或移除name;条目后还有残留字符时都会message(FATAL_ERROR)。对贡献者的实际含义记录在 shim 头文件注释中新增导出入口必须同时加入 version-script否则在 ELF 与 macOS 上都不会被导出include/公共头不得包含source/私有头这是项目规则而非构建系统约束见 CLAUDE.md遵守它才能保证下游用户只需消费include/slang.h。五、循环与已知异常评审与修复都确认各目录 CMake 文件中未观察到链接级循环文档明确写出 No link-level cycles are observed。但有两处值得知道的异常slang库向上侵入 tools 树取头文件source/slang/CMakeLists.txt 把${slang_SOURCE_DIR}/tools加入INCLUDE_DIRECTORIES_PRIVATE这让slang-language-server.cpp能编译#include platform/performance-counter.h来自 tools/platform。没有伴随链接边——头文件只用于其内联定义——但意味着tools/platform/不能随意搬移而不触碰库slang-common-objects间接层见 3.2 节某些配置模式下同一批源文件先编译成对象库再被重链接进slang-without-embedded-core-module与主slang这是为了随用户可见的slang一并发布无嵌入式 core module 的编译器生成器而做的构建系统便利。六、外部依赖清单图外的真实链接面图内只画内部结构但每个节点的外部依赖在节点注释与 Edge citations 一节 中均有交代节点主要外部依赖依据文件coreminiz、lz4_static、Threads::Threads、unordered_dense、${CMAKE_DL_LIBS}SLANG_ENABLE_MIMALLOC开启时 PUBLIC 链接mimalloc-static并传播SLANG_ENABLE_MIMALLOC1编译定义配置阶段若找不到mimalloc-static目标会直接硬失败source/core/CMakeLists.txtcompiler-corefast_float除内部core链接外source/compiler-core/CMakeLists.txtslang、slang-wasmSPIRV-Headerswasm 目标另有miniz、lz4_staticsource/slang/CMakeLists.txt、source/slang-wasm/CMakeLists.txtslang-rtminiz、lz4_static、Threads、unordered_dense、${CMAKE_DL_LIBS}无任何 Slang 内部库依赖source/slang-rt/CMakeLists.txtslang-glslangglslang、SPIRV、SPIRV-Tools-opt、SPIRV-Tools-linksource/slang-glslang/CMakeLists.txtslang-lookup-tablesSPIRV-Headerssource/slang/CMakeLists.txt完整的逐边引用表Edge citations覆盖了图中每一条实线边例如compiler-core → core对应 source/compiler-core/CMakeLists.txt 的LINK_WITH_PRIVATE corecore-module → {core, slang}对应 source/slang-core-module/CMakeLists.txt 的LINK_WITH_PRIVATE core slang-capability-defs slang-fiddle-outputslang-wasm → {slang, core, compiler-core}对应 wasm 目标上的LINK_WITH_PRIVATE miniz lz4_static slang core compiler-core slang-capability-defs slang-capability-lookup slang-fiddle-output slang-lookup-tables虚线边slang -.- slang-record-replay则只由EXTRA_SOURCE_DIRS源列表包含所证明不依赖任何LINK_WITH_*子句。七、这套质量闭环对我们意味着什么把评审报告、修复报告与最终文档放在一起看可以得到几条方法论层面的结论文档的粒度纪律是被强制执行的。提示词模板规定节点必须对应 source 目录或 module-map 标题评审据此抓出了四个目标混入子系统图的节点修复时没有简单地把它们从图中删掉就完事而是用带标签的边和文字段落保住了信息量coreModule →|generated targets| slangLib反而比原来更准确地表达了跨子系统依赖生成产物但不链接编译器这一微妙关系不变量必须区分构建模式。SLANG_EMBED_CORE_MODULE开关会改变源归属目标、核心模块链接方式甚至动态库缓存生成逻辑——把唯一持有源码的目标写成绝对化断言在另一种配置下就会失真修复后的表述slang或slang-common-objects才是可移植的真相行号、字节上限、digest 都是校验资产。regenerate.py lint会检查 front-matter 键、链接可解析性与 16 KB 体积上限watched_paths_digest与source_commit让任何一次源码变动都能被标记为stale。修复报告特别指出文档现为 12275 字节低于 16384 字节上限regenerate.py lint通过——这就是机器可验证的完成定义。如果你正想深入 Slang 源码文件级清单请查阅 module-map.md运行时数据流而非构建依赖请沿 pipeline/overview.md 的编译流水线继续追踪而本主题的完整证据链——评审报告、修复报告、提示词模板与被监视的 CMake 文件——都可以在 docs/generated/design/_meta 目录下对照阅读。【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考