Skip to content

Troubleshooting Superbuild Failures

Use this page before switching to manual dependency installation. Many failures are caused by compiler, MPI, permission, or network issues that can be fixed without manually building every dependency.

Common Failure Modes

Symptom Likely cause Fix
Install tries to write into /usr/local No install prefix was provided at configure time. Configure with -DCMAKE_INSTALL_PREFIX=$EXASIM_PREFIX, then run cmake --install Exasim-build.
CMake cannot find a compiler Compiler modules or command-line tools are missing. Install/load compilers and rerun CMake from a clean build directory.
CMake finds the wrong MPI Multiple MPI installations are visible. Set MPI_C_COMPILER and MPI_CXX_COMPILER explicitly.
ParMETIS or MPI link errors MPI compiler/runtime mismatch. Build and run with the same MPI stack.
BLAS/LAPACK not found Missing system packages or unloaded vendor math module. Install libblas-dev liblapack-dev or load site math libraries.
Download step fails Network blocked or proxy required. Use site mirrors, preload dependencies, or use manual install.
Kokkos fails to configure Unsupported compiler, path with spaces, or wrong GPU toolchain. Use a supported compiler and a whitespace-free path.
GPU compile fails Wrong CUDA/HIP architecture or compiler. Use GPU Installation and platform-specific GPU pages.

Diagnostic Commands

cmake --version
which cc c++ || true
which mpicc mpicxx || true
mpicc --version || true
mpicxx --version || true

For GPU builds:

nvcc --version || true
hipcc --version || true

Inspect the CMake logs:

find Exasim-build -name CMakeError.log -o -name CMakeOutput.log
find Exasim-build -name CMakeConfigureLog.yaml

Clean Reconfigure

If CMake cached the wrong compiler or dependency path, use a fresh build directory:

rm -rf Exasim-build
export EXASIM_PREFIX=/path/to/prefix
cmake -S Exasim -B Exasim-build -DCMAKE_INSTALL_PREFIX=$EXASIM_PREFIX
cmake --build Exasim-build -j8
cmake --install Exasim-build

When To Use Manual Installation

Proceed to Manual Dependency Installation when:

  • your site blocks Superbuild downloads;
  • you must use preinstalled system or vendor dependencies;
  • the cluster requires specific compiler/MPI/GPU module combinations;
  • you need fine-grained control over Kokkos, SymEngine, METIS, or ParMETIS.