# 为 Compiler 做贡献

本节介绍版本控制规则及其重要性。

## 编译器的工作原理

Dagor Shader Compiler （DSC） 用于创建编译的着色器转储（对于每个特定的驱动程序和着色器模型是独立的）。对于给定的编译器运行，最终结果通常是单个  `<name><driver>.[bindless.]<shader model>.shdump.bin`  文件和（可选）动态 CPP STCODE 库。为了减少编译时间，中间文件将被缓存并在将来的运行中重复使用：

- SHA cache (二进制): 位于 `<intermediate dir>/../../shaders_sha~<platform>-O<optimization level>[-bindless]/bin`，包含为特定着色器编译的特定于驱动程序的二进制文件。如果在将来的编译器运行中编译完全相同的 HLSL（或类似 HLSL）的代码，请重复使用。

- SHA cache (源代码): 位于 `<intermediate dir>/../../shaders_sha~<platform>-O<optimization level>[-bindless]/src`，可能包含要编译的特定着色器的最终 HLSL（或类似 HLSL）源代码。引用二进制缓存文件（如果已生成）。

- `.obj`文件：位于 `<intermediate dir>`中，包含给定`.dshl`文件的完整编译器输出。如果`.dshl`文件自上次编译器运行以来未被修改，则重复使用。

以下是可用`<driver>` 值的列表：
  - `DX12x` - Xbox One 平台
  - `DX12xs` - Xbox Series 平台
  - `DX12` - DirectX 12 API
  - `SpirV` - Vulkan API
  - `PS4` - PlayStation 4 平台
  - `PS5` - PlayStation 5 平台
  - `MTL` - Metal API
  - 空字符串 - DirectX 11 API

输入`.blk` **必须** 具有变量 `outDumpName:t="<dump path>/< name><driver>"`。

`[bindless]`的存在由 DSC 标志`-enableBindless:on`定义。

`<intermediate dir>`由 DSC 标志`-o`定义。

## 版本控制

Dagor Shader Compiler 有 3 个不同的“版本”，每个版本都必须单独更新：

- 如果生成的 HLSL（或类似 HLSL）代码**可以**生成与以前版本不同的字节码（例如，如果您更新了 HLSL 编译器的库），则相应的`sha1_cache_version`**必须**在`prog/tools/ShaderCompiler2/sha1_cache_version.h`中更新，因为它用于`_output/shaders_sha~<platform>-O<optimization level>[-bindless]/`中的缓存

- 如果更改需要重建所有`.obj` （如果`.dshl`文件 **可能** 生成的`.hlsl`与以前的版本不同，或者 stcode 生成已更改）

  - 在某些平台上，相应的  `_MAKE4C('version')`  **必须** 在 `prog/tools/ShaderCompiler2/ver_obj_<platform>.<h or cpp>`

  - 所有平台，`SHADER_CACHE_COMMON_VER`**必须**在`prog/tools/ShaderCompiler2/shCacheVer.h` 中更新

- 如果您实现一些新功能或修复了某些内容，则`prog/tools/ShaderCompiler2/globalConfig.h`中的`CompilerConfig::version`**必须**更新。它仅用于日志记录。