Configuration Files And Templates

Overview

Configuration files and templates are split into common configuration files, container recipes, site configurations, and templates.

Common configuration files

Several configuration files in YAML format are stored under configs/common:

Name	Description
config.yaml	Basic settings like number of parallel build processes, location of spack cache
modules.yaml	Generic module configuration, applies to Tcl/Tk environment modules and Lua/Lmod modules
modules_*.yaml	Settings specific to Tcl/Tk environment modules and Lua/Lmod modules
packages.yaml	Generic package configuration (providers, versions, build variants)
packages_*.yaml	Compiler-specific package configuration that overrides the generic package configuration *

* Currently, spack-stack does not support version-specific compiler configuration files in configs/common (different from site configurations)

Container recipes

Currently unused. Will be removed or updated later.

Site configurations

Site configurations are split into fully supported tier-1 sites (preconfigured sites) and tier-2 sites (configurable sites). The latter include default site configurations for Linux and macOS that serve as starting points for new site configurations and user systems.

Site configurations and common configurations are merged when creating new environments with spack-stack. Conflicts are resolved by overriding the common configuration with the site-specific configuration, where possible, or an error is generated.

For each site, the following configuration files can be present:

Name	Description
config.yaml	Basic settings
mirrors.yaml	Definition of source cache and build cache mirrors
modules.yaml	Choice between tcl and lmod modules, and which additional modules to be included (generated) or excluded by spack
packages.yaml	Compiler-independent package settings for this site
packages_*.yaml	Compiler-specific package settings; these can but do not have to include specific versions *
README.md	Additional information for this site

* For example, packages_gcc-12.2.0.yaml and packages_gcc-13.4.0.yaml to distinguish between the same environments with different GCC compiler versions. If only one version of a compiler is being used, it is sufficient to drop the version suffix, i.e. to use packages_gcc.yaml.

The site configuration for each site must provide information on the compiler and MPI provider (packages.yaml, packages_*.yaml) and which modules to generate (modules.yaml).

Templates

Templates are used by the spack-stack extension to create environments or containers and define which packages, including virtual packages, need to be installed. In some cases, variants and versions are specified in the templates. This is mostly used when different environments (templates) require different settings, in which case the common package configuration file allows multiple versions/build options or does not specify them at all.

Each of the available templates corresponds to a specific environment in the following table. Environment names (directories) take the format <prefix>-<compiler-name>-<compiler-version>, for example ue-oneapi-2025.3.0.

Template	Description	Prefix
unified-dev	Unified environment for all organizations/applications	ue
skylab-dev	JEDI/Skylab environment for JEDI, models, EWOK	se
neptune-dev	NEPTUNE-JEDI standalone environment	ne
neptune-ops	NEPTUNE-JEDI standalone environment for operations	ne
cylc-dev	Environment for running cylc (separate from other envs) *	ce
gsi-addon-dev	GSI addon (chained) environment on top of unified env.	gsi

* The cylc environment is a special environment that is used differently. See the next section for more information.

Special environments

Cylc environment

The cylc environment differs from the other environments:

1. The cylc environment can only be built with a reasonably recent version of the GNU compilers (gcc version 10 or later, as long as spack-stack in general supports the version; see [here](LINK MISSING( for a compiler compatibility matrix). Further, on Cray systems, the Cray compiler wrappers cannot be used. Note that, as long as the cylc environment does not use MPI (which is currently the case), it is not necessary to toggle the wrappers variant for the external cray-mpich package when using the native compilers without the Cray wrappers.

2. Instead of creating tcl or lmod modules and the associated meta-modules, this environment creates a spack environment view in /path/to/spack-stack/envs/env-name/view. In order to use the cylc installation provided in that view, the user is advised to create a cylc-wrapper similar to the following bash script and then create an alias cylc pointing to the wrapper script. This approach ensures that the environment in which cylc operates is encapsulated from the environment that users or cylc tasks operate in.

Cylc wrapper

> cat cylc-wrapper

#!/bin/bash

# Define environment variable CYLC_INSTALL_PREFIX here,
# pointing to /path/to/spack-stack/envs/env-name/view,
# or make sure the user did set it before calling the wrapper
[ -z ${CYLC_INSTALL_PREFIX} ] && echo "CYLC_INSTALL_PREFIX not set!" && exit 1

PATH=${CYLC_INSTALL_PREFIX}/bin:$PATH
unset PYTHONPATH
cylc "$@"

Cylc alias pointing to cylc wrapper

> alias
   
alias cylc='/path/to/cylc-wrapper'