Slang 仓库中的 slangpy 调试技能用本地 Slang 构建验证 SlangPy 兼容性的完整工作流【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slangSlang 仓库的.claude/skills/slangpy-debug/SKILL.md将针对本地 Slang 改动调试 SlangPy 兼容性问题固化为一套可被 AI Agent 直接执行的标准流程先用 CMake Preset 构建本地 Slang再把 SlangPy 以可编辑模式安装并指向该本地构建最后跑通其 pytest 测试套件。读完本文你可以完整复现这条从 Slang 源码改动到 SlangPy 测试验证的闭环路径并理解其中每个 CMake 选项、平台差异与排障检查点的具体含义。1. 技能文件的位置与整体结构该技能文件位于 Slang 仓库的 slangpy-debug/SKILL.md采用 Claude Code 技能的标准组织形式YAML frontmatter 声明元数据Markdown 正文承载操作步骤。frontmatter 的四个字段各有明确职责字段取值作用nameslangpy-debug技能标识符即调用时的/slangpy-debug名称descriptionDebug slangpy compatibility issues by building slangpy from source with a local Slang build...向 Agent 描述适用场景克隆、构建、安装并在本地 Slang 改动上测试 slangpyargument-hint[build-type: debug\|release]提示调用者可以传入构建类型参数allowed-toolsBash、Read、Write、Edit、Grep、Glob限定执行该技能时 Agent 可用的工具集全部围绕命令行执行与文件读写argument-hint中的debug|release选项在正文末尾的交互式工作流中生效$ARGUMENTS占位符会在技能被调用时替换为用户实际传入的参数。技能正文的组织顺序与实际操作顺序一致前置条件 → 构建 Slang → 克隆 slangpy → 指向本地 Slang 安装 → 安装测试依赖 → 运行测试 → 备注 → 排障 → 交互式工作流。以下逐节展开并结合本仓库的构建系统源码补充每个步骤背后的具体行为。2. 前置条件技能声明了三项前置条件已安装 Python 3.10Slang 已构建出 Debug 或 Release 配置的二进制Git 支持子模块submodules支持。Python 版本要求对应 pip 安装与 pytest 测试链Slang 已构建对应技能第 1 步Git 子模块支持对应第 2 步中git submodule update --init --recursive的必要性——slangpy 的构建依赖其子模块中的代码缺了这一步构建会失败。3. 第一步构建本地 Slang从 Slang 仓库根目录执行# From Slang repository root cmake --preset default cmake --build --preset debug # or --preset release这两条命令的行为可以直接从仓库中的 CMakePresets.json 得到印证default配置预设使用Ninja Multi-Config生成器binaryDir为${sourceDir}/build即构建输出落在仓库根目录下的build/通过CMAKE_CONFIGURATION_TYPES同时定义了Debug;Release;RelWithDebInfo;MinSizeRel四种配置CMAKE_MSVC_RUNTIME_LIBRARY按配置自动选择MultiThreadedDebugDebug或MultiThreaded非 DebugSLANG_ENABLE_IR_BREAK_ALLOC在 Debug 配置下为TRUE、其余配置下为FALSE即 Debug 构建内置了 IR BreakAlloc 调试辅助能力适合配合本地调试使用。对应地debug与release两个构建预设都绑定到default配置预设分别指定configuration为Debug或Release在 Ninja Multi-Config 布局下Debug 产物的输出目录即build/Debug。这正是技能后续步骤中-DSGL_LOCAL_SLANG_BUILD_DIRbuild/Debug路径的由来。补充几点来自仓库文档的适用前提见 building.mdPreset 机制要求 CMake 3.25文档推荐 3.26CMakePresets.json声明cmakeMinimumRequired为 3.25.0旧版 CMake 需退回cmake -B build -G Ninja手工配置此时构建产物路径可能与build/Debug不一致需要相应调整后面的指向参数一次完整构建视机器性能需要约 520 分钟也可以一步完成配置加构建cmake --workflow --preset debug。构建类型Debug/Release在此步就已确定它必须与后续安装 slangpy 时传入的构建目录严格一致这一点在第 5 节的备注中还会再次强调。4. 第二步克隆 slangpy 仓库# Clone with submodules (required for slangpy build) git clone https://github.com/shader-slang/slangpy.git external/slangpy cd external/slangpy git submodule update --init --recursive要点有二slangpy 被克隆到 Slang 仓库根目录下的external/slangpy与 Slang 自带的 external 第三方依赖目录并列。这个位置不是随意的正是为了让后续CMAKE_ARGS中相对路径../..从external/slangpy出发能精确指回 Slang 仓库根目录技能明确要求阅读external/slangpy/CLAUDE.md获取该仓库的一般性说明。slangpy 是独立于 Slang 之外的项目本仓库不包含其源码因此其构建系统CMAKE_ARGS如何被解析、SGL_*选项的完整语义应以克隆后的 slangpy 仓库内文档为准。5. 第三步使用本地 Slang 构建并安装 slangpy核心机制是通过CMAKE_ARGS环境变量向 slangpy 的 CMake 构建注入三个选项选项示例值含义-DSGL_LOCAL_SLANGON—启用本地 Slang模式slangpy 构建时使用本地构建的 Slang 而非预编译版本-DSGL_LOCAL_SLANG_DIR../..Slang 源码根目录相对external/slangpy解析指向 Slang 仓库根-DSGL_LOCAL_SLANG_BUILD_DIRbuild/Debug本地构建输出目录必须与第 3 节实际构建的配置匹配三种平台的命令形式Windowscd external/slangpy SET CMAKE_ARGS-DSGL_LOCAL_SLANGON -DSGL_LOCAL_SLANG_DIR../.. -DSGL_LOCAL_SLANG_BUILD_DIRbuild/Debug python.exe -m pip install -e .Linux/macOScd external/slangpy CMAKE_ARGS-DSGL_LOCAL_SLANGON -DSGL_LOCAL_SLANG_DIR../.. -DSGL_LOCAL_SLANG_BUILD_DIRbuild/Debug python -m pip install -e .Windows WSLcd external/slangpy WSLENV:CMAKE_ARGS CMAKE_ARGS-DSGL_LOCAL_SLANGON -DSGL_LOCAL_SLANG_DIR../.. -DSGL_LOCAL_SLANG_BUILD_DIRbuild/Debug python.exe -m pip install -e .几个值得注意的细节WSL 场景的WSLENVWSLENV:CMAKE_ARGS的作用是让在 WSL 内设置的CMAKE_ARGS能透传到 WSL 内启动的 Windows 进程此处是python.exe从而保证 Windows 侧 pip/构建环境同样能读到该变量。从技能给出的命令结构看WSL 场景走的是 Windows 侧的 Python 安装路径可编辑安装pip install -e .以 editable 模式安装 slangpy。技能备注明确说明这允许在调试过程中直接修改 slangpy 源码而无需重装改完 Python 代码立即生效——这对一边改 Slang 一边改 slangpy 适配代码的兼容性调试循环非常关键构建类型一致性备注指出若 Slang 以 Release 构建需改用-DSGL_LOCAL_SLANG_BUILD_DIRbuild/Release。构建类型不匹配例如本地是 Release 却指向build/Debug会导致 slangpy 找不到或加载错误配置的 Slang 二进制是此类排障中最常见的一类配置错误。6. 第四步与第五步安装测试依赖并运行测试# From external/slangpy directory python -m pip install -r requirements-dev.txt --user python -m pip install pytest-xdist --userrequirements-dev.txt安装开发依赖pytest-xdist则提供下一步的并行执行能力。运行测试# From external/slangpy directory python -m pytest slangpy/tests -ra -n auto --maxprocesses3 python tools/ci.py unit-test-python新写的回归用例应放在 slangpy 仓库的slangpy/tests目录下随 pytest 一并执行-ra输出各类简短结果摘要-n auto按可用 CPU 自动并行--maxprocesses3将并行进程数上限压到 3兼顾速度与资源占用技能备注解释-n auto用于并行加速测试执行python tools/ci.py unit-test-python复用 slangpy 自身 CI 脚本中的单元测试入口适合在与上游 CI 完全一致的路径下复现问题。7. 备注与排障清单技能在 Notes 与 Troubleshooting 两节给出的检查点可整理为如下清单现象检查项 / 操作测试找不到slangc核对SLANG_BUILD_DIR路径是否正确即SGL_LOCAL_SLANG_BUILD_DIR指向的目录中确实存在对应配置的slangcimport slangpy失败执行python -c import slangpy; print(slangpy.__file__)确认 slangpy 已正确安装且路径符合预期GPU 相关测试失败确保显卡驱动为最新另外部分测试在缺少 GPU 硬件时会直接跳过属预期行为Release 构建使用-DSGL_LOCAL_SLANG_BUILD_DIRbuild/Release替代 Debug 路径这张清单的价值在于把排障动作收敛为三条可机械执行的检查路径、安装状态、驱动/硬件避免了在兼容性问题上做无界猜测。8. 交互式工作流Agent 执行视角技能末尾定义了该技能被 Agent 调用时的决策逻辑若$ARGUMENTS指定了构建类型debug或release采用指定值否则默认使用debug检查external/slangpy/是否已经克隆若否执行第 4 节的克隆步骤用对应的构建类型执行构建与安装即第 5 节的流程SLANG_LOCAL_SLANG_BUILD_DIR随之取build/Debug或build/Release询问用户要运行哪个测试、或要调查什么问题。这个幂等检查 默认值 询问收敛的写法是典型的 Agent 技能设计重复调用不会重复克隆参数缺失时有确定的默认行为且每一步都有人工确认点不会在无人参与时自行扩大操作范围。9. 该技能在 Slang 仓库中的位置与背景从仓库文件结构看这条技能与仓库的 AI 协作体系是衔接的CLAUDE.md 的 Debugging with slangpy 小节明确写道调试 slangpy 兼容性问题时使用/slangpy-debug技能基于本地 Slang 构建从源码构建 slangpy 做兼容性测试。技能文件因此是该文档指向的唯一执行细节载体同一目录下还并列着其他技能如repro-remix、slang-release-process等slangpy-debug是其中唯一面向跨仓库验证的技能其余主要服务于 Slang 仓库内部的工作流背景上本仓库中旧的 PyTorch 互操作文档 a1-02-slangpy.mdslang-torch 教程已标记为弃用deprecated并建议新用户使用 SlangPy 作为替代方案。也就是说SlangPy 是当前 Python/PyTorch 方向上的主推互操作形态而本技能文件就是维护者在修改 Slang 编译器后验证这一形态不受影响的工具。需要注意的是slangpy 的源码不在本仓库中本仓库内可查证的内容只有这份技能文件及其在 CLAUDE.md 中的引用SGL_*选项在 slangpy 构建系统中的完整定义、tools/ci.py的可用命令列表等细节应到克隆后的 slangpy 仓库及其CLAUDE.md中确认。10. 总结这条调试闭环的设计要点最小路径从 Slang 源码改动出发到 slangpy 全量测试给出结论中间只经历构建 Slang → 克隆 → 带参安装 → 跑测试四个环节没有中间产物拷贝或手动替换二进制的操作配置即契约SGL_LOCAL_SLANG_DIR与SGL_LOCAL_SLANG_BUILD_DIR两个路径参数构成了 Slang 与 slangpy 两个仓库之间的显式契约且克隆位置external/slangpy保证了相对路径的稳定性可编辑安装支撑高频迭代pip install -e .让 slangpy 侧的适配代码修改无需重装配合pytest -n auto的并行执行压缩了改动—验证单轮耗时技能化沉淀把多平台命令差异Windows / Linux/macOS / WSL、构建类型一致性、排障检查点固化为单一可引用文件使人和 Agent 都能以同一套步骤复现问题。适用前提小结Python 3.10、CMake 3.25preset 机制、Git submodules、一台能构建 Slang 的开发机GPU 相关测试另需可用硬件与最新驱动。【免费下载链接】slangMaking it easier to work with shaders项目地址: https://gitcode.com/GitHub_Trending/sl/slang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考