Extending the software stack

Tip

The EESSI-extend module makes it possible to build and install whole software stacks that are available to the user, group.

In a nutshell, EESSI-extend is a module that loads EasyBuild in an environment that is configured to install software to one specific location at a time. This location may be configured by the user, by setting one of the variables mentioned below.

Using the EESSI-extend module is a short and informative introduction to building software with EasyBuild on EESSI. It is recommended that new users first read that page before proceeding.

Note that a specific version of EESSI's compatibility must be selected when building software. This will default to the most recent release available on the system if no version number is supplied. For a quick overview of EESSI-extend, see the module's help.

ml help EESSI-extend/2023.06-easybuild

EESSI-extend for user installations

By default, the EESSI-extend module sets the EESSI_USER_INSTALL variable. This can be configured to point to any location on the filesystem, but by default it points to $HOME/eessi. The user will have full write permissions to this location, and can build out any software that they require.

Tip

You can define multiple locations. For instance, if you run out of space on the $HOME filesystem, just build additional software at EESSI_USER_INSTALL=$DATA/eessi.

EESSI-extend for project/group installations

Often you will want to install software in a way that it is usable for everyone within a research group. This can be done by setting up some shared storage, setting the variable EESSI_PROJECT_INSTALL to point there, loading EESSI-extend and building the software with easybuild.

Tip

If both EESSI_USER_INSTALL and EESSI_PROJECT_INSTALL are defined, both sets of installations are exposed, but new installations are created as user installations.

See our examples page for an example of how to install a software package for a group.

Advanced

It can sometimes be a challenge to find an easyconfig file that build right away. Part of the reason for this is that some toolchains are better supported than others in EESSI. Software built with a well supported toolchain will be quicker to build with EasyBuild, because it will be easier to resolve the dependencies from already installed software. Note that passing the -r or --robot flag to EasyBuild will cause it to automatically build and install any missing dependencies. Even though this is possible, the recommended approach is to try to align the dependencies with what is already available through the existing software repositories as much as is practical. This is not only because the software will be quicker to build, but also because there will likely be better support from the community if any extra hooks or patches are required to build the software.

Manually building software on top of EESSI

Overview of buildenv modules

Warning

Even with the help of a buildenv module, this documentation is intended for "experts" in the runtime linker and it's behaviour, and most cases are untested. Any feedback on this topic is highly appreciated.

In order to run software that has been compiled on the system, the linker must be configured in a way so that the required libraries can be found at runtime. Traditionally this is handled by either setting the LD_LIBRARY_PATH variable, or explicitly setting the run-time search-path rpath headers in the elf executable being compiled. Each approaches have its merits, and we generally recommended adopting the approach that works more reliably on any given system.

In the case of MUSICA, the approach that works more reliably is to set rpath values for the executables being compiled. While it is possible to do this manually, it can be a tedious exercise to do so. Instead, the recommendation is to first load a special buildenv module for the toolchain which you are using to compile your software.

The primary purpose of a buildenv module is to handle the configuration of compilers and linkers, so they work with the current system configuration. For an overview of all types of buildenv currently available on MUSICA, run module avail buildenv. Alternatively, the following websites offer a good overview:

• EESSI provided buildenv modules
• ASC provided buildenv modules

Examples of working with buildenv modules

Example: VASP 6.6.0 with NVHPC-25.9 and Cmake

#!/usr/bin/env bash
#ASC --vanilla
#SBATCH -p zen4_0768_h100x4
#SBATCH --qos zen4_0768_h100x4
#SBATCH --ntasks=32
#SBATCH --gres=gpu:1
#SBATCH --mem 256G
#SBATCH --cpus-per-task=1
#SBATCH --threads-per-core=2
#SBATCH --job-name="bvasp66"
#SBATCH --output=slurm-%j.out

# Start with a clean environment
ml --force purge && ml load EESSI/2025.06 ASC/2025.06

# Load the buildenv module (this automatically loads the toolchain)
ml buildenv/default-NVHPC-25.9

# Load aditional dependencies
ml load HDF5/1.14.5-NVHPC-25.9
ml load Wannier90/3.1.0-NVHPC-25.9
ml load FFTW/3.3.10-NVHPC-25.9
ml load CUDA/13.0

bash cmake/setup.sh

export NVROOT="$EBROOTNVHPC/Linux_x86_64/25.9"
export QD_ROOT="$NVROOT"/compilers/extras/qd

rm -rf cmake_build
mkdir -p cmake_build
cd cmake_build
cmake ${SCRATCH}/vasp/vasp.6.6.0-NVHPC-25.9/ \
  -DVASP_OPENMP=ON -DVASP_HDF5=ON \
  -DVASP_CUDA=ON -DVASP_CUDA_VERSION=13.0 -DCMAKE_CUDA_ARCHITECTURES=90

make -j16

Example: HBT-HERONS with foss-2023b toolchain

The following snippet shows how to build HBT-HERONS with the foss-2023b toolchain.

myname@n3001-007:~$ git clone https://github.com/SWIFTSIM/HBT-HERONS.git && cd HBT-HERONS

myname@n3001-007:~$ mkdir build && cd build

myname@n3001-007:~$ module load buildenv/default-foss-2023b
myname@n3001-007:~$ module load CMake/3.27.6-GCCcore-13.2.0
myname@n3001-007:~$ module load HDF5/1.14.3-gompi-2023b

myname@n3001-007:~$ cmake ../ && make -j 128