Spack Recipes: Automation & Best Practices

• Spack recipes are Python-based specifications encoding dependencies, build-time options, and variant logic to ensure reproducibility in HPC deployments.
• The SpackIt framework leverages LLM-assisted generation and iterative repair to scale recipe creation, boosting installation success from 19.7% to over 82%.
• Empirical evaluations highlight the importance of automated metadata extraction, reference retrieval, and diagnostic feedback for robust recipe generation.

Spack recipes are Python-based specifications that enable automated, reproducible building and installation of complex scientific software within the Spack package manager, with particular relevance for high performance computing (HPC) environments. By encoding dependencies, build-time options, variant logic, and platform specifics, Spack recipes formalize the myriad configurations required to deploy modern scientific applications, whose external requirements routinely number in the hundreds. Writing and maintaining these recipes is non-trivial due to HPC heterogeneity, nonuniform build systems, and rapidly evolving dependency constraints. Recent research has targeted both hand-written and large-language-model (LLM)-assisted generation of Spack recipes, addressing the escalating manual effort and the need for scalable, reliable automation (Melone et al., 7 Nov 2025, Atif et al., 13 May 2025).

1. Structure and Semantics of Spack Recipes

A Spack recipe is defined by a Python class (typically subclassing CMakePackage, PythonPackage, or other build-system-specific base classes), which encapsulates all necessary metadata for building a package. Elements include:

• version(...): Defines specific release tags or commit hashes with associated checksums.
• variant(...): Encodes optional features that affect the build (e.g., enabling CUDA support).
• depends_on(...): Declares precise dependency relations, usually with version constraints and type annotations (build, run, link).
• Build customization methods such as def cmake_args(self) or def build_args(self) inject appropriate flags at configuration time.
• Environment setup hooks such as def setup_build_environment(self, env) allow fine-grained control over compilation and runtime paths.

For example, the p2r recipe (Atif et al., 13 May 2025) includes variants to select the portability layer (impl) and hardware backend (backend), mapping these directly to CMake flags for compatibility with CUDA/HIP/Kokkos/Alpaka/SYCL:

class P2r(CMakePackage): variant('impl', default='cuda', values=('cuda', 'kokkos', 'alpaka', 'stdpar', 'sycl')) variant('backend', default='nvidia', values=('nvidia', 'amd', 'cpu')) depends_on('[email protected]:', when='backend=nvidia') depends_on('kokkos', when='impl=kokkos') # cmake_args and environment setup omitted for brevity

These elements succinctly capture and parameterize both the build-time and run-time software graph, supporting reproducibility and modularity.

2. Spack Recipe Generation at Scale: The SpackIt Framework

Manual production of Spack recipes presents scalability and maintenance limits as HPC software ecosystems expand. The SpackIt framework (Melone et al., 7 Nov 2025) describes a systematic, LLM-augmented automation pipeline for recipe generation comprising four interleaved stages:

1. Repository Analysis
   • Automated scanning of source trees for canonical build descriptors (e.g., CMakeLists.txt, setup.py).
   • Extraction of raw metadata including dependency lists, compiler flags, build-time options, and optional linkage distillation to a compact schema that maps, e.g., CMake variables to Spack concepts.
2. Example Retrieval
   • Reference set: a curated ∼8,500-recipe E4S knowledge base ingested into Neo4j or embedded for semantic retrieval.
   • Retrieval mechanisms:
     • Graph-based affinity via the weighted score:

   $$\mathcal{A}(p_t,p) = w_D\,|D_t\cap D_p| + w_B\,|B_t\cap B_p|, \quad w_D=0.6,\, w_B=0.4$$

   with $D$ and $B$ representing the dependency and build-option sets, respectively. - Embedding-based nearest-neighbor retrieval over feature-rich recipe encodings. - These references seed LLM prompting with structurally similar, technically relevant exemplars.

3. Recipe Generation
   • Prompt construction comprises task preambles, reference schemas/best practices, distilled metadata, and retrieved recipes.
   • LLMs output full package Python classes, including all boilerplate elements and tailored variant/dependency logic matching the analyzed source.
4. Diagnostic Feedback and Iterative Refinement
   • Generated recipes are parsed, concretized, built, and installed in containerized Spack environments.
   • Failures trigger automated error capture (spack audit, build logs), which become part of a repair prompt for up to $k$ LLM-assisted iterations (with $k=5$ providing a cost-effective balance), closing the loop for robust synthesis.

High-level pseudocode illustrates the logic:

procedure GenerateSpackRecipe(repo, k=5): metadata ← ExtractMetadata(repo) distilled ← OptionallyDistill(metadata) references ← RetrieveExamples(distilled, mode) prompt ← BuildPrompt(repo.name, distilled, references) recipe ← LLM_Call(prompt) for attempt in 1..k: result ← SpackEvaluate(recipe) if result.success: return recipe errors ← CollectErrors(result) audit ← RunSpackAudit(recipe) repair_prompt ← BuildRepairPrompt(recipe, errors, audit) recipe ← LLM_Call(repair_prompt) end for return recipe # best effort end procedure

3. Empirical Results and Evaluation Metrics

Performance of automated Spack recipe generation has been empirically benchmarked using 308 CMake-based E4S packages (Melone et al., 7 Nov 2025). Key findings:

• Zero-shot LLM generation (no retrieval or error-guided repair) succeeded in only 19.7% of cases (GPT-5).
• Integrating schema distillation, two structurally similar reference recipes, and up to five repair passes raised installation success to 82.9%.
• Cross-model averages (within $k=5$ repairs):

Model	Install	$S_d$ (dependency sim.)	$S_v$ (variant sim.)
GPT-5	0.78	0.66	0.46
GPT-4.1	0.41	0.58	0.31
Claude 3.7	0.39	0.54	0.41
Mistral 2.1	0.22	0.52	0.39

Where:

• Variant similarity:

$S_v = \frac{|A \cap B|}{|A|}$

with $A$ as human-authored variant arguments, $B$ as those in the LLM recipe.

• Dependency similarity:

$$S_d = \frac{1}{|D_A|}\sum_{d_i\in D_A}\max_{d_j\in D_B} \left( \alpha + \beta\frac{|T_i \cap T_j|}{|T_i|} + \gamma\delta(S_i,S_j) + \lambda\delta(C_i,C_j) \right)$$

with $\alpha=0.6$, $\beta=0.2$, $\gamma=\lambda=0.1$ (attributes include targets $T$, scopes $S$, and compilers $C$).

Functional installation success correlates with semantic similarity to human recipes but cannot be inferred solely from token overlap; explicit formula-based metrics are necessary to quantify adequacy.

4. Implementation Patterns and Representative Recipes

Hand-authored and LLM-generated recipes follow a Python DSL structure standardized by Spack. Standard patterns include:

• Import control for build systems (from spack.package import *) and conditionally-injected imports (e.g., CudaPackage if CUDA is detected).
• Use of define_from_variant for mapping variant selections to CMake options, ensuring both conciseness and stability across repeated builds.
• Fine-grained specification of dependency types and version ranges.

Example: Incomplete zero-shot recipe for Cgal (no variants or dependencies):

class Cgal(CMakePackage): version('6.0.2', url='https://github.com/CGAL/cgal/archive/v6.0.2.tar.gz')

Example: FXdiv before/after LLM refinement:

Human-optimized:

class Fxdiv(CMakePackage): version("1.0") variant("inline_asm", default=False) variant("tests", default=False) depends_on("[email protected]:", type="build") depends_on("c", type="build") depends_on("cxx", type="build") def cmake_args(self): return [ self.define_from_variant("FXDIV_USE_INLINE_ASSEMBLY","inline_asm"), self.define_from_variant("FXDIV_BUILD_TESTS","tests"), ]

SpackIt-generated, post-repair:

class Fxdiv(CMakePackage): version("1.0") variant("inline_asm", default=False, description="Use inline assembly") variant("tests", default=False, description="Build tests") depends_on("[email protected]:", type="build") depends_on("c", type="build") depends_on("cxx", type="build") def cmake_args(self): args = [ self.define_from_variant("FXDIV_USE_INLINE_ASSEMBLY","inline_asm"), self.define_from_variant("FXDIV_BUILD_TESTS","tests"), ] return args

Here, automated repair yields improved compliance with Spack conventions ($S_v=1.0$, $S_d=0.75$).

5. Application to Heterogeneous Mini-app Portability

In the context of cross-facility benchmarking for high energy physics (HEP), Spack recipes play a critical role in portable deployment of mini-apps targeting modern HPC architectures (Atif et al., 13 May 2025). For example, the p2r mini-app leverages Spack variants to select among CUDA, HIP, Kokkos, Alpaka, SYCL, and standard parallelism (stdpar), and to specify hardware backends (NVIDIA/AMD/CPU).

Deployment follows the standard reproducibility workflow:

• Add package.py to the Spack repository.
• Select variants and dependencies via spack install or environment files.
• Use module systems (e.g., Lmod) to deliver the correct runtime configuration.

For benchmarking, environment parameters such as event counts are exported as environment variables by the recipe, ensuring tunable, repeatable performance runs.

FastCaloSim and other mini-apps use containerized builds with similar dependency logic encoded in Dockerfiles rather than published Spack recipes, illustrating the complementarity of Spack recipes and container-based approaches when targeting rapidly changing GPU stacks. Spack recipe templates for undocumented applications (e.g., Patatrack, WireCell Toolkit) may plausibly follow the p2r idiom, with CMake-driven variant logic and externalized toolkit selection.

6. Actionable Best Practices and Future Directions

The dominant findings from empirical analysis and applied case studies converge on several practitioner guidelines (Melone et al., 7 Nov 2025):

1. Extract and optionally distill repository metadata (CMake variables, dependencies) to provide dense and relevant context for both human and LLM-based recipe generation.
2. Retrieve and present to the LLM at least one or two structurally similar Spack recipes to ground the prompt in idiomatic, domain-specific logic.
3. Explicitly encode Spack best-practice heuristics (variant naming, import structure, builder class selection) within prompts to improve consistency and correctness.
4. Automate parse→concretize→install/test cycles, capturing diagnostic and audit feedback to drive iterative correction.
5. Cap repair attempts at 5–10 to maximize efficiency—most recoverable errors are resolved within the first few iterations.
6. Measure recipe similarity using semantic metrics ($S_v$, $S_d$) in addition to functional installation outcomes.

As HPC software complexity continues to grow, integrating LLM-based automation with retrieval, context distillation, and structured feedback loops is likely to further alleviate the burden of Spack recipe authoring and maintenance. A plausible implication is that recipe generation will shift further toward mixed-initiative workflows, combining expert validation with scalable automation for new software domains and evolving platform features.

7. Limitations and Open Technical Challenges

Fully automated Spack recipe synthesis remains an unsolved challenge in several respects. LLMs without retrieval or iterative repair generally underperform compared to schema-guided, feedback-driven strategies (installation success < 20% in zero-shot). Certain recipes, involving complex, non-standard build procedures or undocumented dependencies, resist synthesis even after multiple repair passes, necessitating expert intervention.

Additionally, although recipe similarity metrics $S_v$ and $S_d$ correlate with installation and semantic correctness, they do not fully capture subtle quality aspects (e.g., Spack policy compliance, future-proofing against software drift). This suggests future research should address richer conformance metrics, cross-stack dependency evolution, and better integration with both containerized and bare-metal HPC deployment workflows.

Spack recipes, and the frameworks for their generation, thus occupy a critical junction between software engineering, scientific computing, and AI-driven automation—enabling scalable, robust, and reproducible scientific software for contemporary HPC ecosystems.