Build Guide

SPONGE 2.0 documentation: Build Guide.

Organized by GPT-6-Astra. SPONGE 2.0 is under active, iterative development; features, parameters, and documentation may change. Consult the GitHub repository’s docs and skills for the latest version information.

Source snapshot for this page.

Build Guide

Build workflow

pixi install -e <env>             # install dependencies
pixi run -e <env> configure       # CMake configure
pixi run -e <env> compile         # build and install into the environment

The binary is installed to $CONDA_PREFIX/bin/SPONGE. Build artifacts go into build-<env>.

Environments

Environment	Purpose	Parallel backend
`dev-cuda13`	CUDA 13 development (recommended)	CUDA
`dev-cuda12`	CUDA 12 development	CUDA
`dev-hip`	AMD GPU / Hygon DCU development	HIP
`dev-cpu`	CPU development	defaults to `none`, SIMD can be specified manually
`dev-cpu-mpi`	CPU + MPI development	defaults to `none` + MPI, SIMD can be specified manually
`cuda13` / `cuda12` / `hip` / `cpu` / `cpu-mpi`	build-only (no dev tools)	corresponding backend

dev-* environments include development tools (python, pytest, clang-format, ruff, etc.). Benchmark and format tasks are only available in dev-* environments.

CUDA build

pixi run -e dev-cuda13 configure
pixi run -e dev-cuda13 compile

pixi automatically installs cuda-nvcc, libcufft-dev, libcublas-dev, and other CUDA dependencies.

Compilation parallelism defaults to 4 threads. Pass a positional argument to adjust:

pixi run -e dev-cuda13 compile 8     # 8 threads

HIP build

pixi run -e dev-hip configure
pixi run -e dev-hip compile

Note: pixi does not install the HIP/ROCm SDK. It must be pre-installed on the system, e.g. via apt install, from the official ROCm repository, or via module load. CMake detects the HIP environment by looking for hipcc / hipconfig in the system PATH.

CPU build

pixi run -e dev-cpu configure          # defaults to no SIMD
pixi run -e dev-cpu configure avx2     # specify AVX2
pixi run -e dev-cpu compile

Available SIMD backends:

x86_64	ARM
`avx512`, `avx2`, `avx`, `sse42`	`sve2`, `sve`, `neon`

CPU + MPI build

pixi run -e dev-cpu-mpi configure
pixi run -e dev-cpu-mpi compile

Automatically adds -DMPI=ON and the MPI compiler configuration.

Platform differences

Platform	Compiler	Math library	Notes
Linux x86_64	GCC 11 (conda)	MKL	CUDA + MPI requires NCCL
Linux aarch64	GCC 11 (conda)	OpenBLAS + FFTW	supports SVE/NEON
Windows x64 CPU	Intel oneAPI 2026.1.1 `icx-cl`	MKL	Requires VS 2022 C++ Build Tools 14.44+ and Windows SDK
Windows x64 CUDA	NVCC + MSVC (vs2022)	CUDA libraries	may need `pixi run install-msvc` first
macOS ARM	Clang 22.1	OpenBLAS + FFTW	CPU backend only

Windows CPU builds use Intel oneAPI icx-cl for both C and C++. pixi run -e dev-cpu configure automatically installs the locked compiler environment in tools/oneapi; Intel packages are kept separate from the project’s LLVM JIT dependencies. Local builds and CI use the same entry point. VS C++ Build Tools and the Windows SDK must be installed separately with administrator privileges; the vs2022_win-64 package only activates them. Use VS 2022 C++ toolset 14.44 or newer for the headers and import libraries: the prebuilt LLVM 22 libraries require newer STL symbols than toolset 14.39 provides. Updating only the redistributable runtime does not update these build-time libraries. The CUDA environments continue to use MSVC as the NVCC host compiler. The Windows CPU tasks use a separate build-<environment>-oneapi directory, so existing MSVC/Clang build caches are not reused. For unit tests, run pixi run -e dev-cpu configure-tests, pixi run -e dev-cpu compile, then pixi run -e dev-cpu test. Run the normal benchmark tasks after installation. To include the opt-in HDF5 runtime tests in PowerShell, set $env:SPONGE_H5_ENABLE_RUNTIME_SMOKE = "1" before running test. Windows CPU CI enables these tests with two OpenMP/MKL threads. The runtime package includes intel-cmplr-lib-rt for Intel math functions; OpenMP uses conda-forge’s llvm-openmp compatibility DLL, shared with MKL. End users installing the binary package do not need the compiler environment.

Global compile settings

The following are hardcoded in cmake/utils/common.cmake:

C++ standard: C++17
Build type: Release
Fast math: -ffast-math / /fp:fast / --use_fast_math
OpenMP: always enabled

Formatting

pixi run -e dev-cuda13 format        # auto-fix
pixi run -e dev-cuda13 format-check  # check only

See Contributing for details.

Packaging

pixi run -e dev-cuda13 package-conda

Produces a .conda package in packaging/outputs/.

Troubleshooting

configure cannot find CUDA

Make sure you are using a CUDA environment (dev-cuda12 or dev-cuda13). Do not specify -DPARALLEL=cuda in a CPU environment.

nvcc warning “incompatible redefinition for option compiler-bindir”

Known warning under the conda environment. Does not affect the build. Safe to ignore.

Wrong system compiler or libraries picked up

When pixi provides all required dependencies, use pixi install -e <env> --clean-envs to rebuild a clean environment. However, this does not apply when the build depends on external toolchains (MSVC on Windows, HIP/ROCm); in those cases, set up the environment variables yourself before invoking pixi.

format reports missing BOM

C++ files require UTF-8 with BOM. Run pixi run format to fix automatically.

Cleaning build directories

rm -rf build-dev-cuda13   # clean a specific environment
rm -rf build-*            # clean all