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 distribution method depends on both the platform and how CRESSim-Neo is used:

  • Rolling Linux distributions: Build from source against the system CUDA and PyTorch packages. Configure CRESSIM_NEO_CUDA_RUNTIME_PROVIDER=SYSTEM and verify that the resulting runtime is compatible with the installed PyTorch package.

  • Stable Linux and Windows — Python and PyTorch workflows: Use CUDA-specific wheels (for example, cu126, cu130, or cu132) in an isolated virtual or Conda environment. Install the CRESSim-Neo and PyTorch wheels from the same named CUDA lane. On Linux, the CRESSim-Neo wheel declares the corresponding NVIDIA runtime packages; on Windows, install the matching PyTorch wheel first, because the CRESSim-Neo loader uses its torch\lib directory (or Conda’s Library\bin).

  • Stable Linux and Windows — native applications and C++ SDK: Use prebuilt native binaries for the C++ SDK, viewer, and standalone examples. These releases require the CUDA runtime version specified for the toolchain release.

Note

PyTorch CUDA runtime compatibility: Torch interoperability uses DLPack and CUDA external-memory exchange, so CRESSim-Neo and PyTorch must run with a compatible CUDA runtime and driver stack in the same process. On stable Linux distributions and Windows, system Python installations can load CUDA libraries from the system toolchain that differ from the NVIDIA CUDA runtime libraries used by PyTorch wheels. This can cause runtime-library conflicts or missing-symbol errors.

For Python/Torch workflows on stable platforms, install CRESSim-Neo and PyTorch in the same isolated virtual or Conda environment, using the same supported CUDA lane. For source builds using system CUDA, use compatible system CUDA and PyTorch packages.