Slang 编译器架构全景:从源码树分层到编译请求生命周期

原创2026-09-19 19:55:431,654 阅读
文章标签:编译器图形学编程语言

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)

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)

2.6 驱动与工具(Driver and tooling)

  • source/slangc/——slangc 命令行驱动(main.cpp)。
  • tools/——辅助开发者工具(测试、反射、代码生成、fiddle、embed、性能剖析)。

2.7 source/ 之外的辅助树

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 一律通过"追加"增长,头文件展示了四种互不冲突的增长机制:

  1. 接口追加方法——新方法放 vtable 末尾(如 IGlobalSession::saveBuiltinModule,实现见 source/slang/slang-global-session.h)。
  2. 全新带 UUID 的接口——并非每个实现都具备的能力变成独立接口,通过 castAs/queryInterface 获取(如 IBindlessResourceMetadata、ICoverageTracingMetadata、ISyntheticResourceMetadata),而不是给既有接口加方法。
  3. 追加枚举值——新的 CompilerOptionName 值以显式整数追加在 CountOf 哨兵之前;CountOf 是唯一刻意不写显式值的枚举项。最近新增的两个是 TraceCoverageBindlessIndex = 158 与 GetCompilerPath = 159(include/slang.h 中对应位置)。
  4. 对带 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/design/ 下的手写开发者笔记与本树内容交叠,同样值得参考,尤其是 overview.md、ir.md 与 parsing.md。

登录后查看全文
slang