Build CRESSim-Neo#

CRESSim-Neo is a C++17 simulation engine with optional Python bindings. Third-party C++ dependencies (including Diligent Engine, pybind11, and GLFW) are managed as in-tree git submodules and built automatically by CMake. A normal CMake build produces the native libraries; enabling Python adds the cressim_neo extension module.

Prerequisites#

  • CMake 3.23 or newer to use the supported CMake presets. Manual configuration supports CMake 3.18 or newer.

  • Python 3.10 or newer. The enabled Diligent Vulkan/SPIR-V toolchain needs a Python interpreter even when CRESSim-Neo’s Python bindings are disabled.

  • Linux: Clang/Clang++ with C++17 support and Ninja.

  • Windows: Visual Studio 2022 with the Desktop development with C++ workload and a Windows SDK.

  • macOS: Xcode Command Line Tools, Ninja, and the LunarG Vulkan SDK with MoltenVK. Set VULKAN_SDK before configuration. Apple Silicon is the regularly supported source-build tier; Intel and universal builds are not regularly validated.

  • Linux viewer builds: development packages for Xcursor, Xext, Xi, Xinerama, and XRandR.

  • Python development headers when building Python bindings.

  • A Vulkan-capable graphics driver/runtime for Vulkan-backed programs.

On Ubuntu or Debian, install the standard Linux dependencies with:

sudo apt update
sudo apt install -y \
  build-essential \
  clang \
  clang++ \
  cmake \
  ninja-build \
  python3-dev \
  python3-venv \
  python3-pip \
  git \
  libvulkan-dev \
  vulkan-tools \
  libxcursor-dev \
  libxext-dev \
  libxi-dev \
  libxinerama-dev \
  libxrandr-dev

Linux and Windows use a pinned DXC runtime by default; CMake downloads it and verifies its SHA-256 the first time it populates a build-directory cache. In-tree dependencies—such as Diligent Engine (extern/DiligentEngine), GLFW (extern/glfw), and pybind11 (extern/pybind11)—are tracked as git submodules, require no manual user handling or system-level installation, and are compiled automatically. Simply initialize them when checking out the repository:

git submodule update --init --recursive

Keep the intended virtual or Conda environment active when building Python so CMake and pip use the same interpreter. macOS uses the Vulkan SDK’s MoltenVK and disables DXC. It is a source-build-only, best-effort tier: CUDA interop, Ultrasound, and macOS release wheels are not provided.

Native development#

CMakePresets.json is the canonical native configuration interface. Release and debug presets build the shared SDK, viewer, and examples; Python, tests, CUDA interop, and Ultrasound are off by default.

Linux#

cmake --preset linux-release
cmake --build --preset linux-release --parallel

Use linux-debug for interactive debugging. linux-ci is a headless test profile:

cmake --preset linux-ci
cmake --build --preset linux-ci --parallel
ctest --preset linux-ci

macOS#

export VULKAN_SDK=/path/to/vulkansdk-macos
cmake --preset macos-release
cmake --build --preset macos-release --parallel
cmake --install build/macos-release --component CXXSDK
cmake --install build/macos-release --component Examples

Use macos-debug for development and macos-ci for a lean, headless local CTest profile.

Windows#

cmake --preset windows-vs2022-release
cmake --build --preset windows-vs2022-release --parallel
cmake --install build/windows-vs2022-release --config Release --component CXXSDK
cmake --install build/windows-vs2022-release --config Release --component Examples

Use windows-vs2022-debug for debugging. The windows-vs2022-ci preset is a headless local verification profile; run it with its matching build and test presets. Visual Studio is multi-config, so use --config for installation.

Components and customization#

The install components are:

  • CXXSDK: shared C++ libraries, public headers, standard assets, shaders, and the CMake package. Assets are installed below share/cressim-neo/assets.

  • Examples: enabled standalone C++ executables. Install CXXSDK with it so their default asset paths resolve.

  • Python: the cressim_neo module, native runtime libraries, package files, shaders, models, and environment maps.

Set a prefix while configuring (or use the same --prefix for every install component):

cmake --preset linux-release -DCMAKE_INSTALL_PREFIX="$HOME/.local"

Without an override, native installations go below the build directory, for example build/linux-release/install. Static C++ SDK installation is not a supported public workflow. Set CRESSIM_NEO_ASSET_DIR to use a custom asset tree; otherwise C++ uses installed assets and Python uses package-local assets.

Pass -D options after a preset to customize it. For example:

cmake --preset linux-release -DCRESSIM_NEO_BUILD_PYTHON=ON
cmake --build --preset linux-release --parallel

For a headless build, add -DCRESSIM_NEO_BUILD_VIEWER=OFF and -DCRESSIM_NEO_BUILD_EXAMPLES=OFF. Other useful switches are:

  • -DBUILD_TESTING=ON

  • -DCRESSIM_NEO_ENABLE_CLANG_TIDY=ON

  • -DCRESSIM_NEO_ENABLE_CUDA_INTEROP=ON

  • -DCRESSIM_NEO_ENABLE_ULTRASOUND=ON (also requires CUDA interop and a CUDA compiler)

  • -DCRESSIM_NEO_CUDA_RUNTIME_PROVIDER=SYSTEM for a locally built Python CUDA extension (AUTO is the local-development default; MANAGED is for distributed CUDA-wheel lanes)

  • -DCRESSIM_NEO_DXC_PROVIDER=SYSTEM to use SDK-provided DXC, or OFF to omit DXC. Without DXC, DXC-only Vulkan features fall back and Windows D3D12 is unsupported.

Consuming an installed C++ SDK#

cmake -S . -B build -DCMAKE_PREFIX_PATH="$HOME/.local"

find_package(CRESSimNeo CONFIG REQUIRED)
target_link_libraries(my_application PRIVATE CRESSimNeo::engine)

Python package development and wheels#

pyproject.toml uses scikit-build-core and builds the Python component and interactive viewer, with examples, tests, CUDA interop, and Ultrasound off. Build a local wheel with:

scripts/build_local_wheel.sh
python -m pip install dist/cressim_neo-*.whl
python -c "import cressim_neo; print(cressim_neo.__file__)"

On Windows, activate the intended environment and run ./scripts/build_local_wheel.ps1. On macOS, build from a recursive checkout with VULKAN_SDK set and DXC disabled:

python -m pip wheel --no-deps --wheel-dir dist \
  -C cmake.define.CRESSIM_NEO_DXC_PROVIDER=OFF .

For editable development, run python -m pip install -e .. Package builds can take several minutes; use the preset-based native build for frequent C++ iteration. The local wheel requires NumPy. Install Gymnasium separately when its environment wrappers are needed:

python -m pip install gymnasium

The installed wheel contains two Python packages. Use cressim_neo for the native bindings and runtime API. Task environments and PSM authoring helpers are in cressim_neo_envs and must be imported from their defining modules:

import cressim_neo as neo
from cressim_neo_envs.cartpole import CartPoleTorchVectorEnv
from cressim_neo_envs.psm_env import PsmEnv

Import high-level helpers from their cressim_neo_envs modules.

Local wheels do not include CUDA interop or Ultrasound. Install PyTorch separately when needed, and use the release-wheel workflow for CUDA-enabled Linux or Windows distributions.

Distribution and packaging strategy#

The long-term distribution plan addresses target environments across platforms:

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

  • Python on mainstream platforms: Pinned CUDA-specific wheels (cu126, cu130, cu132) with pinned NVIDIA pip runtime dependencies, installed in 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.

Note

PyTorch CUDA runtime compatibility: Torch interoperability (DLPack and CUDA external memory exchange) strictly requires that CRESSim-Neo links and interacts with the exact same CUDA runtime as PyTorch. On stable Linux distributions and Windows, system Python packages and system CUDA installations frequently conflict with PyTorch’s bundled CUDA runtime wheels. Performing a system-Python install with system CUDA on stable Linux/Windows is therefore unsupported for Torch-interoperable workflows; users should rely on isolated virtual environments with matching wheels. For system-CUDA source builds, use compatible CUDA and PyTorch packages.