Slang 编译器架构全景:从源码树分层到编译请求生命周期
Slang 编译器架构全景:从源码树分层到编译请求生命周期
本篇技术指南以 docs/generated/design/architecture/overview.md 为骨架,面向尚未打开过 Slang 源码树的 C++ 工程师,系统梳理 Slang(一个着色语言编译器)的顶层源码树分层、四大公开产物、贯穿一次编译的中央数据对象,以及公开 API 的二进制兼容演化策略。读完本文,你将能回答"某个关注点应该在
source/下哪个子目录实现""编译请求如何流转""为什么头文件里新增接口只能追加不能插入"等架构级问题,并知道下一步该去docs/generated/design/下哪一份文档深入。
1. 项目定位与四大公开产物
Slang 是一个着色语言编译器。它的职责是接收 Slang(以及 HLSL 兼容)源码,为目标图形/计算工具链产出目标代码——DXIL、SPIR-V、GLSL、Metal Shading Language、WGSL、C++、CUDA 或 PyTorch 胶水代码——同时附带关于着色器参数的反射(reflection)/布局(layout)信息。
构建会产出四个主要的公开产物:
| 产物 | 说明 | 源码位置 |
|---|---|---|
slangc |
命令行编译驱动 | source/slangc/(入口 main.cpp) |
slang-compiler(共享库) |
可嵌入的编译器;公开 C API 与 COM 风格接口声明于 include/slang.h | 库体构建于 source/slang/ |
| WebAssembly 绑定 | 将编译器暴露给 JavaScript,附带生成的 interface.d.ts |
source/slang-wasm/(绑定实现 slang-wasm-bindings.cpp) |
slang-rt |
可选运行时支持,供发射到非 GPU 目标的代码链接使用 | source/slang-rt/ |
两个值得注意的兼容细节:
- 在
SLANG_ENABLE_SLANG_PROXY开启时,历史命名仍会以向后兼容别名形式产出:Unix 上是libslang符号链接,Windows 上是转发用的slang.dll。 slang-compiler共享库形态下,如果关闭SLANG_EMBED_CORE_MODULE,构建会额外生成generate_core_module_cache目标,把预编译的slang-core-module.bin缓存写到库文件旁边,使首次 global-session 请求加载该归档而不是现场编译 core module(见 source/slang/CMakeLists.txt 中相关逻辑,及 docs/generated/design/cross-cutting/core-module.md)。
1.1 CMake 构建组织
编译器用 CMake 构建,核心库的完整构建配置位于 source/slang/CMakeLists.txt,source/ 下每个同级子目录各自维护一个 CMakeLists.txt 加入同一构建。其中有一个关键路径约定:该文件中的路径相对 slang_BINARY_DIR 而非 CMAKE_BINARY_DIR 书写。copy_slang_headers 目标会把 include/ 加上生成的 slang-tag-version.h 暂存到 ${slang_BINARY_DIR}/$<CONFIG>/include(对应 source/slang/CMakeLists.txt):
add_custom_target(
copy_slang_headers
COMMAND ${CMAKE_COMMAND} -E make_directory "${slang_BINARY_DIR}/$<CONFIG>/include"
COMMAND ${CMAKE_COMMAND} -E copy_directory "${slang_SOURCE_DIR}/include"
"${slang_BINARY_DIR}/$<CONFIG>/include"
COMMAND ${CMAKE_COMMAND} -E copy
"${CMAKE_CURRENT_BINARY_DIR}/slang-version-header/slang-tag-version.h"
"${slang_BINARY_DIR}/$<CONFIG>/include/slang-tag-version.h"
)
这样做的目的是:当父项目通过 add_subdirectory 嵌入 Slang 时,暂存头文件会收集在 Slang 自己的构建目录下,而不是污染顶层构建目录。
2. 源码树顶层分层
source/ 下的目录是分层的:下层不依赖上层,而 include/ 中的公开 API 悬浮在最上层,充当不可变的边界。从架构文档看,主要分成以下若干层。
2.1 基础层(Foundational layers)
- source/core/ —— 平台无关的 C++ 工具集:容器、字符串、智能指针、文件系统抽象、哈希、分配器。项目内没有其他部分能在不链接它的前提下工作。代表性文件 slang-basic.h。分配器可选用 mimalloc 作为后端:设置
SLANG_ENABLE_MIMALLOC后,source/core/CMakeLists.txt 会把mimalloc-static链入core并对所有依赖目标定义SLANG_ENABLE_MIMALLOC=1。 - source/compiler-core/ —— 与语言无关的编译器基础设施,原则上可被另一门语言复用:词法分析器(slang-lexer.cpp)、诊断接收器(slang-diagnostic-sink.h)、源码位置编码、下游编译器胶水(DXC、FXC、GCC、glslang),以及用于携带编译产物的 artifact/blob 模型。
2.2 编译器主体(The compiler proper)
- source/slang/ —— Slang 前端、AST、中间表示、IR passes 与各 emit 后端,是编译器的绝大部分。其内部按文件名前缀约定分族:
slang-ast-*:AST;slang-parser*/slang-preprocessor*:前端解析与预处理;slang-check*:语义检查;slang-lower-to-ir*:AST→IR 降级;slang-ir.*/slang-ir-insts.*:IR 核心;slang-ir-*.cpp:IR passes;slang-emit*:代码发射;slang-serialize*:AST/IR/RIFF 序列化;slang-capability*:能力格(capability lattice);slang-diagnostics*:Slang 专属诊断目录。- 逐文件的详细清单一览见 docs/generated/design/architecture/module-map.md。
- prelude/ —— 各文本目标的 prelude 头文件,编译器随发射出的文本目标一起分发,供下游工具链编译结果使用;每个文本目标族一份(HLSL、CUDA、C++、Torch)。
2.3 标准库(Standard libraries)
- source/slang-core-module/ 与 source/slang/ 下的
*.meta.slang文件(core.meta.slang、hlsl.meta.slang、diff.meta.slang)——定义内建类型、内建函数与运算符映射的 core module,构建期嵌入slang-compiler。 - source/slang-glsl-module/ 与 glsl.meta.slang——面向 GLSL 风格内建函数的同类模块。
- source/standard-modules/——随发行提供但不以同样方式嵌入的标准模块源码,每个子目录构建独立的
.slang-module产物:neural(source/standard-modules/neural/)与experimental(source/standard-modules/experimental/,目前承载 work-graph 模块)。
2.4 下游编译器垫片(Downstream-compiler shims)
- source/slang-llvm/ —— 基于 LLVM 的 JIT/静态编译胶水(slang-llvm.cpp)。
- source/slang-glslang/ —— 通往 Khronos
glslang的桥,用于经 GLSL 生成 SPIR-V(slang-glslang.cpp)。注意:该垫片的导出符号并非仅由 C++ 决定——入口点还必须在slang-glslang.version-script中列出(ELF 与 macOS 构建都从它派生导出表),否则客户端的符号查找会返回 null、入口点静默不可用。 - source/slang-dispatcher/ —— 派发到下游工具的共享支撑(main.cpp)。
下游编译器统一通过 IDownstreamCompiler 抵达,声明于 source/compiler-core/slang-downstream-compiler.h。只有部分编译器具备的能力被建模为独立接口,而不是给主接口加方法。典型例子是 IDownstreamCompilerPathProvider(slang-downstream-compiler.h):它的单个 getPath 返回所加载编译器库在磁盘上的路径;DownstreamCompilerBase 提供默认实现,返回 SLANG_E_NOT_AVAILABLE,只有共享库承载的编译器会覆写它——基于可执行文件、在 PATH 上找到的命令行编译器,或缺少共享库内省能力的平台,没有这样的路径可返回。
该接口刻意不继承 ICastable,只作为借用对象通过 castAs/getObject 分发,绝不通过 getInterface:因为 getInterface 同时支撑带引用计数的 queryInterface,只能返回可释放的 ISlangUnknown 派生接口,若再给能力接口加一个 ICastable 基类,会让具体编译器类出现两个有歧义的 ISlangUnknown 子对象。这一模式在 slang-llvm.cpp 的 LLVMDownstreamCompiler 上有完整实现。
2.5 运行时与绑定(Runtime and bindings)
- source/slang-rt/(CMakeLists.txt)——链接进宿主机风格 CPU 输出的运行时库,包括 PyTorch 绑定输出;CUDA 源码是 kernel 风格,不依赖它。
- source/slang-record-replay/——公开 Slang API 的记录/重放器(replay-context.cpp)。
- source/slang-wasm/——WebAssembly 绑定(slang-wasm-bindings.cpp)。Emscripten 绑定块是"JavaScript 能碰到什么"的权威清单:
GlobalSession当前暴露createSession与getBuiltinModuleSource(后者按名字把内建模块的源码文本交回给调用方)。
2.6 驱动与工具(Driver and tooling)
- source/slangc/——
slangc命令行驱动(main.cpp)。 - tools/——辅助开发者工具(测试、反射、代码生成、fiddle、embed、性能剖析)。
2.7 source/ 之外的辅助树
- tests/——项目测试语料库。绝大多数文件是
.slang输入,由slang-test驱动(见 tools/slang-test/)。新增回归测试放这里;目录结构镜像被测区域(如 tests/language-feature/、tests/diagnostics/、tests/spirv/)。 - extras/——不编进任何二进制的开发者脚本与小工具:格式化(extras/formatting.sh)、IR dump 拆分(extras/split-ir-dump.py)、Windows 沙箱构建辅助等。该树只服务于开发者,不随发行交付。
- external/——第三方依赖与 git 子模块(spirv-headers、glslang、lz4、miniz 等)。这里只 vendoring,不改动。
2.8 构建期生成代码
Slang 重度依赖构建期代码生成。AST 与 IR 头文件中的 FIDDLE(...) 宏会展开为构建输出目录 build/source/slang/fiddle/ 下生成的成员/访问器/序列化表——例如 slang-ir-insts-enum.h.fiddle 从 source/slang/slang-ir-insts.lua 的 Lua 表枚举出 IR 操作码。诊断目录同样从 slang-diagnostics.lua 与 source/slang/diagnostics/ 下各区域的 Lua 表生成。
3. 编译请求生命周期:贯穿一次编译的中央对象
一次 Slang 编译流经一小撮中央对象,其声明散布在 include/slang.h 与 source/slang/ 的多个头文件中,包括 slang-translation-unit.h、slang-session.h、slang-target.h、slang-compile-request.h、slang-end-to-end-request.h 与 slang-module.h。下面是核心对象的职责速览。
| 对象 | 职责 | 声明位置 |
|---|---|---|
Session |
全局会话级编译器状态:持有内建模块、AST builder 与全局类型检查环境。公开 COM 风格接口为 slang::IGlobalSession(include/slang.h),实现类是 Session |
source/slang/slang-global-session.h |
Linkage |
配置作用域:打包搜索路径、预处理宏、目标设置与 source manager。多个模块共享同一 Linkage,从而彼此一致地解析 import。公开接口 slang::ISession 实际实现的就是它 |
source/slang/slang-session.h |
TranslationUnitRequest |
共享同一命名空间的一组源文件。默认情况下 slangc 传入的所有 Slang 源文件进入单个 TranslationUnitRequest;HLSL 输入则每单元一个 |
source/slang/slang-compile-request.h |
FrontEndEntryPointRequest |
一个函数名 + 其入口点所针对的 profile 阶段(如 main 作为 compute) |
source/slang/slang-compile-request.h |
TargetRequest |
输出格式 + profile 的组合(如 glsl_450 下的 SPIR-V) |
source/slang/slang-target.h |
FrontEndCompileRequest |
驱动一组翻译单元的前端(parse、check、lower to IR) | source/slang/slang-compile-request.h |
CodeGenContext |
驱动一组入口点与目标的后端(IR passes、emit);取代了历史上名为 BackEndCompileRequest 的对象 |
source/slang/slang-code-gen.h |
EndToEndCompileRequest |
单次 slangc 调用背后的总伞对象 |
source/slang/slang-end-to-end-request.h |
Module |
一个翻译单元的前端输出:同时包含检查后的 AST 与降级后的 IR;也是 .slang-module 序列化格式描述的单位。实现公开的 slang::IModule |
source/slang/slang-module.h |
IComponentType |
可链接程序抽象:一个 Module、一个入口点绑定或它们的组合都能呈现为 IComponentType;后端消费单个复合组件做代码生成 |
include/slang.h |
一个必须澄清的命名陷阱:本代码库中 "session" 指两个不同的东西。IGlobalSession 持有全局会话级状态,应用通常创建一次并复用,以摊薄启动成本(不同全局会话可以共存);而 ISession(即 Linkage)才是大多数调用方理解的"编译会话"。
这些对象的划分解释了为什么"translation unit""target"等概念是一等公民:Slang 的流水线以参数化方式把前端工作与后端工作干净地分离。解析与可复用模块检查大体与目标无关,但入口点验证会咨询请求的目标——它把推断出的能力需求与 profile 阶段逐一对照每个 TargetRequest(见 source/slang/slang-check-shader.cpp)——而所有代码生成都发生在后端。
4. 公开 API 位于何处,以及它如何保持二进制兼容
include/slang.h 是权威公开头文件。它声明 COM 风格接口(ISession、IModule、IComponentType 等)与少量用于创建会话的自由函数;连同 include/slang-com-helper.h 与 include/slang-com-ptr.h,构成下游应用链接所依赖的二进制稳定表面。
source/ 之下的一切都是实现。公开头文件规则(见 CLAUDE.md:枚举不许重排、vtable 中段不许改虚函数、不许删除)反映了该表面必须对旧调用方保持 ABI 兼容。因此新 API 一律通过"追加"增长,头文件展示了四种互不冲突的增长机制:
- 接口追加方法——新方法放 vtable 末尾(如
IGlobalSession::saveBuiltinModule,实现见 source/slang/slang-global-session.h)。 - 全新带 UUID 的接口——并非每个实现都具备的能力变成独立接口,通过
castAs/queryInterface获取(如IBindlessResourceMetadata、ICoverageTracingMetadata、ISyntheticResourceMetadata),而不是给既有接口加方法。 - 追加枚举值——新的
CompilerOptionName值以显式整数追加在CountOf哨兵之前;CountOf是唯一刻意不写显式值的枚举项。最近新增的两个是TraceCoverageBindlessIndex = 158与GetCompilerPath = 159(include/slang.h 中对应位置)。 - 对带
structSize的普通结构做尾部扩展——跨边界传递的结构把自身大小作为首字段,只有调用方structSize覆盖到时才写入新尾部成员。SyntheticResourceInfo::bindlessIndex是当前例子:它位于 v1 结构大小之后,用旧头文件编译的调用方保持自身布局,永远看不到该字段。
被取代的入口通常废弃而非删除。替代者落地时,旧声明留在原 vtable/重载位置并标注 deprecated,既有调用方继续可编译、可链接。VariableReflection 展示了该模式:getDefaultValueBlob 把变量默认初始化器作为打包字节 blob 返回,而被它取代的更窄接口 hasDefaultValue、getDefaultValueInt、getDefaultValueFloat 仍保留声明并标记 deprecated。IGlobalSession::addBuiltins 同样如此——在声明上标注 [[deprecated]],占住 vtable 槽位,从而保住其后每个方法的位置。
4.1 两条偏离规则的例外
仅读头文件会以为上述规则是绝对的,但有两个值得了解的例外:
- 就地替换:
IGlobalSession的最后一个方法不是追加而是原地替换——getDownstreamCompilerVersion(SlangPassThrough, int*, int*)在提交b9a17f86b1中变成了getDownstreamCompilerPath(SlangPassThrough, ISlangBlob**)(实现见 source/slang/slang-global-session.h),占据同一个末位 vtable 槽、换了名字与签名。替换回答的是另一个问题——Slang 选中的库实际位于磁盘何处,客户端可以自己加载并查询能力——而不是一个多个下游编译器只能报(0, 0)的版本对。因为它位于末位槽且引入不久,该改动不扰动任何更早方法的位置。 - 直接移除枚举值:驱动旧 CLI 查询的
CompilerOptionName枚举值CompilerVersion = 153被直接移除,而不是改名为REMOVED_CompilerVersion。整数153现在成了序列中的空洞——SPIRVUnifiedDescriptorHeapStride = 154紧随其后——退休值至少不会被复用,这正是规则中保护持有陈旧整数的调用方的部分。
4.2 语言版本与 ABI 版本是两回事
编译器接受的语言版本与上述 ABI 表面相互独立,由 SlangLanguageVersion 枚举。除按年份编号的 SLANG_LANGUAGE_VERSION_2025 / _2026 外,现在还有同一整数的字母后缀别名(_202A = 2025、_202B = 2026)以及进行中的 _202C = 2027——头文件明确警告该版本一旦获得正式名称,其数值可能变化。SLANG_LANGUAGE_VERSION_LATEST 指最新稳定版本,_NEXT 指开发中版本。
5. 下一步阅读指南
架构文档是 docs/generated/design/ 树的入口。要深入,可沿以下路径:
- 按子系统分组的穷举文件清单:读 docs/generated/design/architecture/module-map.md;
- 子系统间依赖:读 docs/generated/design/architecture/dependency-graph.md;
- 端到端编译流程(每阶段一篇文档):从 docs/generated/design/pipeline/overview.md 开始,依次可看 01-lex-preprocess.md、02-parse-ast.md、03-semantic-check.md、04-ast-to-ir.md、05-ir-passes.md、06-emit.md 等;
- 横切各阶段的关注点:见 docs/generated/design/cross-cutting/ 树下的 diagnostics.md、ir-instructions.md、targets.md、core-module.md 与 serialization.md;
- 表层语法:见 docs/generated/design/syntax-reference/。
此外,docs/design/ 下的手写开发者笔记与本树内容交叠,同样值得参考,尤其是 overview.md、ir.md 与 parsing.md。