4. Creating and installing new environments

The following instructions are a simplified version of the instructions found in Sections 6.1 and 6.2, and should work for systems where spack-stack already has a site configuration, or where minimal configuration is necessary. For more detailed instructions, including how to generate new site configurations and more details of when and how to use external packages, see Sections 6.1 and 6.2. To chain a new Spack environment to an existing one, such as to test a new package version based on dependencies already installed in the upstream environment, see 5.

Note that items in “<>” should be replaced with the appropriate values (site names, etc.), and items in ‘[]’ are optional. <site name> and <template name> must match the names of directories found under ‘configs/sites/’ and ‘configs/templates/’, respectively; <environment name> is a user-chosen name for the Spack environment. <path to spack-stack directory> is the root directory created by cloning the spack-stack GitHub repository, which contains ‘configs/’, ‘doc/’, ‘setup.sh’, ‘util/’, etc.

The argument <compiler> is used to specify the primary (preferred) compiler for the environment. For example, this can be gcc, intel, oneapi, … Depending on the configuration for a given compiler (configs/common/packages_COMPILER.yaml, configs/sites/TIER/SITE/packages_COMPILER.yaml), some packages may be built with a fallback compiler that is configured as the second compiler in the compiler list in configs/sites/TIER/SITE/packages_COMPILER.yaml. For example, when the preferred compiler is oneapi, the package bison is compiled with gcc due to a known bug in the package when using oneapi. Sometimes it is necesary to specify the compiler and the version, in which case the argument compiler is COMPILER@=VERSION. An example for this scenario is a site configuration that has two versions of the Intel oneAPI compilers configured in order to provide environments with the “mixed” oneAPI compilers (icx, icpx, ifort; oneapi@=2024.2.1) and with the full set of oneAPI compilers (icx, icpx, ifx; oneapi@=2025.0.4).

# To generate a new spack-stack directory structure, run 'git clone --recurse-submodules https://github.com/JCSDA/spack-stack',
# optionally with, e.g., '-b release/1.4.1' to specify the version

. <path to spack-stack directory>/setup.sh

# If <compiler> contains a version, other versions of the same compiler will be removed from site/compilers.yaml unless --keep-all-comilers is set
spack stack create env --site <site name> --template <template name> --name <environment name> --compiler <compiler>

cd ${SPACK_STACK_DIR}/envs/<environment name>/

spack env activate .

# If not using an existing site configuration, you may wish to modify config files and/or populate them using commands
# such as 'spack external find' and 'spack compiler find'.
# See https://spack-tutorial.readthedocs.io/en/latest/tutorial_configuration.html

spack concretize 2>&1 | tee log.concretize

spack install [--verbose] [--fail-fast] 2>&1 | tee log.install

spack module lmod refresh

spack stack setup-meta-modules

Note

Depending on the site configuration, tcl may be used instead of lmod modules. Check envs/<environment name>/site/modules.yaml and replace lmod with tcl if necessary in spack module lmod refresh.