企业官网建设流程全解析

CrossTL 是一款开源的通用着色器翻译器（Shader Translator），以 CrossGL 为中间表示，支持 HLSL、GLSL、Metal、CUDA、HIP、Rust、Slang 等 GPU 语言在 DirectX、OpenGL、Vulkan 等图形 API 之间的批量转换。本文用 4 条命令行指令完成整个仓库的着色器审计与批量移植：scan扫描审计、translate-project批量移植、validate-project产物校验、inspect-report摘要查看。

01 准备工作：安装 CrossTL 并准备项目配置

一行命令即可安装：

pip install crosstl

也可以从源码构建后使用：

git clone https://gitcode.com/gh_mirrors/cr/crosstl cd crosstl pip install -e .

CrossTL 的项目级命令由根目录的crosstl.toml配置文件驱动，指定源码目录、include 路径、目标后端与输出目录。以仓库内置示例为例：

[project] source_roots = ["."] include = ["alpha_stitch.glsl"] targets = ["cgl", "opengl", "metal", "directx", "vulkan"] output_dir = "crosstl-out" external_corpus_manifest = "corpus.json"

📍 完整示例见 demos/open-source-porting/cases/godot-betsy-alpha-stitch/crosstl.toml，配置加载逻辑位于 crosstl/project/pipeline.py。

💡 没有crosstl.toml时，也可以用--source-root、--include-dir、--define等参数临时覆盖配置。

02 命令一：scan 扫描仓库，生成着色器资产审计报告

批量移植前先做"零写入审计"：scan命令遍历整个仓库，识别所有受支持的着色器与 GPU 内核源文件，并输出一份 JSON 审计报告——不写入任何移植产物，专门用来摸清家底：有多少着色器、分别是什么语言、有没有潜在诊断问题。

python -m crosstl scan /path/to/repo \ --target metal \ --output scan-report.json

几个要点：

• --target可重复指定，把多个目标后端（如--target metal --target vulkan）同时纳入报告；
• 报告中的summary.diagnosticCounts汇总 error / warning 数量，存在 error 时命令以退出码1结束，天然适合接进 CI 门禁。

📍 子命令实现在 crosstl/_crosstl.py。

03 命令二：translate-project 一次移植整个项目到多个后端

审计报告确认无雷区后，进入真正的移植环节。translate-project会翻译项目中所有已发现的源文件，并按后端整理产物目录：

python -m crosstl translate-project /path/to/repo \ --target metal --target opengl --target vulkan \ --output-dir crosstl-out \ --report crosstl-out/portability-report.json

几个高频参数值得了解：

存在失败产物时退出码为1，可以直接作为 CI 的成败判定依据。📍 子命令定义见 crosstl/_crosstl.py。

04 命令三：validate-project 校验移植产物的完整性

validate-project对可移植性报告中引用的每个产物做二次核验：是否生成成功、来源映射是否完整、诊断是否可追溯，并可输出 SARIF 格式，方便接入静态分析平台：

python -m crosstl validate-project crosstl-out/portability-report.json \ --format text

--format支持json（默认）、text、sarif三种输出格式，退出码同样遵循"有问题返回 1"的约定。📍 实现位于 crosstl/_crosstl.py。

05 命令四：inspect-report 查看人类可读的移植摘要

报告 JSON 动辄数万行，直接翻看并不现实。inspect-report会把报告蒸馏成一份紧凑摘要：失败产物、诊断采样、运行时引用、迁移动作——每类默认最多 20 条，一条命令输出人人看得懂的"移植体检报告"：

python -m crosstl inspect-report crosstl-out/portability-report.json \ --format text

也可以配合--output把摘要落盘，或用--output -直接打到标准输出。📍 实现位于 crosstl/_crosstl.py。

06 四条命令串起来：一条完整的着色器移植流水线

4 条命令彼此独立、又首尾衔接：审计报告告诉你"该移植什么"，可移植性报告告诉你"校验什么"，摘要报告告诉你"下一步做什么"。大仓库移植时，--checkpoint/--resume让长时间任务可以断点续跑，无需从头再来。

官方文档给出了同样的推荐顺序：先scan出报告，再translate-project，随后validate-project与inspect-report。📍 完整的项目移植指南见 docs/source/project-porting.rst，仓库还内置了 40 多个钉住版本真实开源项目的移植案例（GLSL、HLSL、Metal、CUDA、HIP、Rust-GPU、OpenCL 全覆盖），可用一条命令全量复现：python demos/open-source-porting/run_demo.py --check，详见 demos/open-source-porting/README.md。

07 小结

• 先审计、后移植：scan摸清家底再动手，避免批量踩雷；
• 报告即接口：4 条命令全部输出结构化 JSON 报告、退出码规范，接入 CI 几乎零成本；
• 大仓库友好：--workers并行加速 +--checkpoint断点续跑；
• 排障有抓手：把inspect-report --format text的输出直接贴给维护者，快速定位问题。

掌握这 4 条命令，"仓库里有多少着色器、能否移植到 Metal / Vulkan / DirectX、如何一次移植完"就有了确定性的答案。