Packaging and Release Wheels#

Local developer wheels and release wheels are different artifacts. Build local wheels with scripts/build_local_wheel.sh (or scripts/build_local_wheel.ps1 on Windows); do not publish them as releases. The local workflow is covered in Build CRESSim-Neo.

Distribution strategy#

The long-term packaging architecture provides targeted release mechanisms per platform:

  • Stable Linux / Windows releases: Prebuilt native binaries (C++ SDK, viewer, standalone examples) with a pinned CUDA-runtime prerequisite matching the toolchain.

  • Python on mainstream platforms: CUDA-specific wheels (e.g. cu126, cu130, cu132) with pinned NVIDIA pip runtime dependencies, deployed into isolated virtual or Conda environments alongside matching PyTorch wheels.

  • Rolling distributions: Build from source in an environment with compatible system CUDA and PyTorch packages. Configure CRESSIM_NEO_CUDA_RUNTIME_PROVIDER=SYSTEM and verify compatibility with the installed PyTorch runtime.

Torch interop and CUDA runtime compatibility#

Torch interoperability (DLPack and CUDA external memory exchange) strictly requires that CRESSim-Neo and PyTorch link and run against the exact same CUDA runtime. On stable Linux distributions and Windows, system Python packages and system CUDA installations frequently conflict with PyTorch’s bundled/pinned CUDA runtime wheels.

Performing a system-Python install with system CUDA on stable Linux/Windows is therefore unsupported for Torch workflows. Mainstream platforms should use isolated virtual environments with matching wheels. For system-CUDA source builds, use compatible CUDA and PyTorch packages.

Linux release lanes#

Linux releases are built in controlled manylinux containers with cibuildwheel. The supported lanes are base (no CUDA interop or Ultrasound), cu126, cu130, and cu132 (matching CUDA interop and Ultrasound builds). They target manylinux_2_34_x86_64 and are written under dist/<lane>/.

Install the host tools, then build one lane at a time:

python -m pip install cibuildwheel auditwheel
scripts/build_release_wheels.sh --lane base
scripts/build_release_wheels.sh --lane cu126

Use CIBW_BUILD='cp312-*' before the script for a narrow local ABI iteration. The build script clears the selected lane’s output directory before building. Verify every resulting wheel before publishing:

for wheel in dist/base/*.whl; do
  scripts/verify_release_wheel.sh --lane base "$wheel"
done

Base wheels are tested in a clean Ubuntu 22.04/Mesa container. CUDA lanes also need an NVIDIA GPU host and NVIDIA Container Toolkit for the interop and Ultrasound runtime test.

Windows release lanes#

Build Windows releases on an x64 Visual Studio developer environment, not in Docker. Install cibuildwheel in the active Python environment, then run:

.\scripts\build_release_wheels.ps1 -Lane base
.\scripts\build_release_wheels.ps1 -Lane cu126

CUDA lanes require the matching locally installed CUDA Toolkit: 12.6, 13.0, or 13.2. The helper verifies the generated wheels automatically; run the verifier again before publishing copied artifacts. Install the matching CUDA PyTorch wheel before testing a CUDA CRESSim-Neo wheel—CUDA runtime DLLs are not bundled.

The full commands, lane images, runtime tests, and verification requirements are maintained in packaging/README.md.