slangpy-build

name	slangpy-build
license	MIT
description	Clone, build, and test SlangPy. Use when the repo needs setup, a rebuild, or when tests fail.
provides	["code.build","test.run","test.gen","ci.inspect"]
allowed-tools	Bash(git:*), Bash(cmake:*), Bash(python:*), Bash(pytest:*), Bash(pip:*), Bash(pre-commit:*), Read, Grep, Glob

Prerequisites

Check all of these before starting the build. Request any missing packages in a single install_packages call — the container will be rebuilt and you must restart the build from scratch after that, so identify everything upfront.

Required apt packages:

• cmake, ninja-build — build system
• libgl-dev, libegl-dev — OpenGL/EGL headers (SlangPy/SGL requires these)
• libvulkan-dev — Vulkan headers
• libx11-dev, libxext-dev, libxrandr-dev, libxinerama-dev, libxcursor-dev, libxi-dev — X11 display headers

Required Python packages (install via pip into the project venv after the build system is ready, not via install_packages):

• numpy — required by SlangPy
• pillow — required by tests
• pytest — test runner

Check:

# Check apt packages
for pkg in cmake ninja-build libgl-dev libegl-dev libvulkan-dev libx11-dev libxext-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev; do
  dpkg -l "$pkg" 2>/dev/null | grep -q "^ii" || echo "MISSING: $pkg"
done

If any are missing, call install_packages with all of them at once before proceeding. After the container rebuilds, re-invoke this skill from scratch.

Clone

git clone --recursive --tags https://github.com/shader-slang/slangpy.git /workspace/agent/slangpy
cd /workspace/agent/slangpy
git remote add upstream https://github.com/shader-slang/slangpy.git
git fetch --tags upstream

Build

SlangPy uses CMake presets for the native C++/nanobind layer. On Linux:

cmake --preset linux-gcc                    # Configure
cmake --build --preset linux-gcc-debug      # Build (debug)
cmake --build --preset linux-gcc-release    # Build (release)
cmake --preset linux-gcc --fresh            # Reconfigure from scratch

Available presets: windows-msvc, windows-arm64-msvc, linux-gcc, macos-arm64-clang.

For Python editable install (preferred for development):

pip install -e .

Use python tools/ci.py configure and python tools/ci.py build for CI-style builds that handle platform detection automatically.

Test

Always build before running tests.

# All Python tests
pytest slangpy/tests -v

# Example tests
pytest samples/tests -vra

# C++ unit tests
python tools/ci.py unit-test-cpp

# Specific test file
pytest slangpy/tests/slangpy_tests/test_X.py -v

# Specific test function
pytest slangpy/tests/slangpy_tests/test_X.py::test_fn -v

Debug generated shaders:

SLANGPY_PRINT_GENERATED_SHADERS=1 pytest slangpy/tests/slangpy_tests/test_X.py -v

CI

CI runs via .github/workflows/ci.yml and calls tools/ci.py:

python tools/ci.py --help                    # All available commands
python tools/ci.py configure                 # CMake configure
python tools/ci.py build                     # Build
python tools/ci.py unit-test-python          # Python tests
python tools/ci.py unit-test-cpp             # C++ tests
python tools/ci.py test-examples             # Example tests

To inspect CI failures:

gh run list --repo shader-slang/slangpy --workflow=ci.yml --limit 5
gh run view <run-id> --log-failed

Formatting

Run pre-commit run --all-files before committing. Re-run if it modifies files. Uses Black for Python and clang-format for C++.

Debugging the functional API

The functional API has a 3-phase call path. When debugging:

1. Phase 1 (Signature Lookup) -- runs every call in C++ (src/slangpy_ext/utils/slangpyfunction.cpp). Check NativeCallDataCache for signature string construction.
2. Phase 2 (Kernel Generation) -- runs once per unique signature in Python (slangpy/core/calldata.py). Check type resolution, vectorization dimensionality, generated kernel code.
3. Phase 3 (Dispatch) -- runs every call in C++ (src/slangpy_ext/utils/slangpy.cpp). Check shape calculation, uniform binding, dispatch thread count.

Set SLANGPY_PRINT_GENERATED_SHADERS=1 to see the Slang compute kernel source generated in Phase 2.

Local Slang build

To test with a local Slang compiler build:

cmake --preset linux-gcc --fresh -DSGL_LOCAL_SLANG=ON -DSGL_LOCAL_SLANG_DIR=<slang-dir> -DSGL_LOCAL_SLANG_BUILD_DIR=build/Debug
cmake --build --preset linux-gcc-debug

Gotchas

• Always build before running tests -- tests import the native extension.
• PyTorch integration is automatic when PyTorch is installed.
• Hot-reload is supported for shader (.slang) development.
• Slang uses single dashes for multi-character options: -help, -target spirv.

From project

• AGENTS.md -- 3-phase functional API architecture, build commands, test commands, debugging workflow
• CLAUDE.md -- references AGENTS.md
• CONTRIBUTING.md -- build from source instructions, test workflow
• CMakeLists.txt -- CMake build system, presets, platform detection
• pyproject.toml -- Python build config (setuptools + cmake + ninja)
• tools/ci.py -- CI task runner with configure, build, test, coverage commands