# Hpc Toolchains

> Build, review, debug, and stabilize HPC compiler and build-toolchain workflows. Use when choosing compiler families such as GCC, Clang, or oneAPI; configuring CMake, `find_package`, or toolchain files; aligning BLAS or LAPACK or MPI stacks; using environment modules or Spack; or repairing ABI, link, and build-system failures.

- Skill: `scimate-ai/hpc-toolchains` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add scimate-ai/hpc-toolchains`
- Raw SKILL.md: https://api.skillmd.com/api/skills/scimate-ai/hpc-toolchains/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: scimate-ai (https://skillmd.com/u/scimate-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/scimate-ai/hpc-toolchains

---


# HPC Toolchains

Treat the toolchain as a coherent stack. Pick the compiler family, MPI family, math libraries, and build system together before tuning application-specific flags.

## Start

1. Read `references/compiler-family-selection.md` before choosing GCC, Clang, or vendor compilers.
2. Read `references/configure-and-build-matrix.md` when deciding between CMake, Make, Ninja, or wrapper-driven builds.
3. Read `references/cmake-and-find-package-playbook.md` when writing or repairing `CMakeLists.txt`, `find_package`, imported targets, or cache variables.
4. Read `references/toolchain-files-and-presets.md` when the build depends on reusable compiler, MPI, or site configuration.
5. Read `references/build-type-and-abi-hygiene.md` when debugging release versus debug mismatches, C++ standard mismatches, symbol issues, or ABI drift.
6. Read `references/blas-lapack-mpi-consistency.md` when linking against BLAS, LAPACK, ScaLAPACK, MPI, or vendor math stacks.
7. Read `references/modules-and-spack-playbook.md` when using environment modules, compiler wrappers, external packages, or Spack environments.
8. Read `references/error-recovery.md` when configure, compile, link, or runtime-loader failures occur.

## Work sequence

1. Decide the stack boundary first:
   - site-provided modules
   - Spack environment
   - container image
   - user-local source build
2. Pick one compiler family and keep the full dependency graph aligned to it.
3. Decide how dependencies are discovered:
   - wrapper compilers
   - `find_package`
   - `pkg-config`
   - explicit include and library paths only as a last resort
4. Keep build directories, cache state, and install prefixes separated by toolchain.
5. Record the exact configure command before tuning warning or optimization flags.

## Guardrails

- Do not mix compiler and MPI families casually across one build tree.
- Do not patch over a bad discovery path with many ad hoc include and library flags.
- Do not treat ABI, C++ standard, and release or debug mode as cosmetic metadata.
- Do not let one dependency come from a different module stack unless the site explicitly supports that mix.

## Additional References

Load these on demand:

- `references/cmake-and-find-package-playbook.md` for imported-target and cache-variable discipline
- `references/toolchain-files-and-presets.md` for reusable site or cluster build configuration
- `references/build-type-and-abi-hygiene.md` for symbol, ABI, and optimization mismatches
- `references/blas-lapack-mpi-consistency.md` for math-library and MPI stack alignment
- `references/modules-and-spack-playbook.md` for module and Spack-based reproducibility
- `references/error-pattern-dictionary.md` for fast matching of common toolchain failure classes

## Reusable Templates

Use `assets/templates/` when a concrete starting point is faster than rebuilding the build stack from scratch, especially:

- `minimal-cmake-project/CMakeLists.txt`
- `minimal-cmake-project/main.cpp`
- `configure-gcc-openmpi.sh`
- `build-smoke-slurm.sh`
- `spack-env-minimal.yaml`

## Outputs

Summarize:

- chosen compiler and MPI family
- dependency-discovery method
- build-system strategy
- math-library and ABI alignment decisions
- the exact failure phase if the workflow is being repaired