bash

#!/usr/bin/env bash

# SPDX-License-Identifier: GPL-2.0-only
# Copyright (C) 2020-2026 EESSI contributors
#
# EESSI - European Environment for Scientific Software Installations
#
# This file is a template for initialising EESSI via Lmod for the environment indicated by the shebang.
#
# Assumptions:
# - EESSI accessible under $EESSI_CVMFS_REPO or /cvmfs/software.eessi.io
#   - expected to be true as this file is also meant to be shipped under that location
#   - Lmod must the shipped in the repository in the correct location
#
# Options:
# - The script listens to environment variables so that it can be silently configured by a site
#   - EESSI_CVMFS_REPO: perform the initialisation from a repository other than /cvmfs/software.eessi.io
#   - EESSI_VERSION: loads a specific EESSI version ignoring the default in the file
#   - EESSI_DEFAULT_MODULES_PREPEND: environment variable allows you to prepend modules to the defaults (loaded last, : separated)
#   - EESSI_DEFAULT_MODULES_APPEND: environment variable allows you to append modules to the defaults (loaded first, : separated)
#   - EESSI_EXTRA_MODULEPATH: environment variable allows a site to append to MODULEPATH (: separated, lower priority than EESSI MODULEPATH)
#   - EESSI_NO_MODULE_PURGE_ON_INIT: environment variable that disables purging modules before initialisation
#
# Other options that can be set to influence the end result:
# - The EESSI module also listens to environment variables so that it can be silently configured by a site
#   - EESSI_MODULE_FAMILY_NAME: use the value of the environment variable to set an Lmod family for the EESSI module
#   - EESSI_MODULE_STICKY: make the EESSI module sticky
#   - EESSI_MODULE_UPDATE_PS1: have the EESSI module update PS1 to give a prompt that is prepended with "{EESSI/...} " (requires exporting PS1)
#  (- EESSI_MODULE_DEBUG_INIT: enable debug print statements when loading the EESSI module)
#
# Effects:
# - Should always succeed
# - Initialises Lmod from specific version of EESSI
#   - Clobbers any existing Lmod configuration
#   - Some special environment variables that are internal to Lmod (__LMOD_REF_COUNT_MODULEPATH and
#     _ModuleTable001_) are used to force a hard reset of an existing Lmod installation. This
#     approach may be brittle.
# - Then loads module EESSI/... to initialise EESSI
#   - use `module show EESSI/...` to see the environment variables set by the EESSI module
#
# Reverting the effects:
# - EESSI initialisation via `module unload EESSI/...`
# - Lmod initialisation cannot be undone

# Choose an EESSI CVMFS repository
EESSI_CVMFS_REPO="${EESSI_CVMFS_REPO:-/cvmfs/software.eessi.io}"

# Choose an EESSI version (the default is only used if the EESSI_VERSION environment variable is not provided)
# (Note: in the repository which is home to this file a template value __EESSI_VERSION_DEFAULT__ is present in
#  the line below which is replaced within our deployment pipeline.)
EESSI_VERSION_DEFAULT="${__EESSI_VERSION_USED_FOR_INIT:-__EESSI_VERSION_DEFAULT__}"
EESSI_VERSION="${EESSI_VERSION:-${EESSI_VERSION_DEFAULT}}"
# On the first run we want to record the EESSI version used for init as an environment variable so that if a different
# version of this script is called (e.g, for a a different EESSI version) it retains a memory which EESSI
# version was actually used in the initialisation. This is useful as __Init_EESSI_Default_Modules used below will
# be defined on the first call and Lmod initialisation will not happen twice.
# This sets the value only on first execution, if the variable already exists in the environment
# the original value is retained.
export __EESSI_VERSION_USED_FOR_INIT="${__EESSI_VERSION_USED_FOR_INIT:-${EESSI_VERSION}}"

# LMOD_SYSTEM_DEFAULT_MODULES are used by Lmod to load a default set of modules in the scenario
# - where we initialise Lmod (the if part of the clause below)
# - where we reset Lmod (the else part of the clause below)
# This means that if we call this script twice we will get the same end result: an Lmod installation
# with a set of default modules loaded.
#
# We also allow the ability to predefine elsewhere the default list of modules to load (colon separated):
# - EESSI_DEFAULT_MODULES_PREPEND environment variable allows you to prepend modules (loaded last)
# - EESSI_DEFAULT_MODULES_APPEND environment variable allows you to append modules (loaded first)
LMOD_SYSTEM_DEFAULT_MODULES="${EESSI_DEFAULT_MODULES_PREPEND:+$EESSI_DEFAULT_MODULES_PREPEND:}EESSI/$EESSI_VERSION${EESSI_DEFAULT_MODULES_APPEND:+:$EESSI_DEFAULT_MODULES_APPEND}"
export LMOD_SYSTEM_DEFAULT_MODULES

if [ -z "$__Init_EESSI_Default_Modules" ]; then
    export __Init_EESSI_Default_Modules=1;

    # Lmod version in 2023.06 has a problem with newer Lmod caches, so let's stick to more recent Lmod
    # (has no effect except on Lmod itself, and compatible caches are still created/supported by EESSI)
    LMOD_EESSI_VERSION=${EESSI_VERSION/2023.06/2025.06}

    # Let's attempt a purge of any loaded modules as any environment variables currently set will survive EESSI initialisation
    # (it's ok if the module command does not exist)
    if [ -z "$EESSI_NO_MODULE_PURGE_ON_INIT" ]; then
        module purge >/dev/null 2>&1 && echo "Modules purged before initialising EESSI"
    fi

    # Lmod may have been initialised so we need to clear some internal variables to allow for a full reset
    # - make it forget about the system set MODULEPATH
    unset __LMOD_REF_COUNT_MODULEPATH
    # - and clear out any memory Lmod might have
    unset _ModuleTable001_

    # For the shells that use PS1 for the prompt, let's add the trigger to enable updating that by default
    # (in an interactive shell PS1 is likely unset, so let's only do this if it is set)
    if [ -n "$PS1" ]; then
        export PS1
        if [ ! -z ${EESSI_MODULE_UPDATE_PS1} ] && [ ${EESSI_MODULE_UPDATE_PS1} -eq "0" ]; then
            unset EESSI_MODULE_UPDATE_PS1
        else
            export EESSI_MODULE_UPDATE_PS1=1
        fi
    fi

    # Path to top-level module tree
    # - EESSI_EXTRA_MODULEPATH environment variable allows a site to append to MODULEPATH (lower priority than EESSI MODULEPATH)
    export MODULEPATH="${EESSI_CVMFS_REPO}/init/modules${EESSI_EXTRA_MODULEPATH:+:$EESSI_EXTRA_MODULEPATH}"
    . "${EESSI_CVMFS_REPO}/versions/${LMOD_EESSI_VERSION}/compat/linux/$(uname -m)/usr/share/Lmod/init/bash"
    module --initial_load --no_redirect restore

    # After initialising, we now know the architecture(s) that was/were selected so let's report them
    echo "EESSI has selected ${EESSI_SOFTWARE_SUBDIR} as the compatible CPU target for EESSI/${EESSI_VERSION}"
    if [ -n "$EESSI_ACCEL_SUBDIR" ]; then
        echo "EESSI has selected ${EESSI_ACCEL_SUBDIR} as the compatible accelerator target for EESSI/${EESSI_VERSION}"
    else
        echo "EESSI did not identify an accelerator on the system"
    fi
    # If people want more detailed information about what EESSI is doing, they can also set an environment variable
    # for additional information.
    echo "(for debug information when loading the EESSI module, set the environment variable EESSI_MODULE_DEBUG_INIT)"
else
    module reset
fi