| 1 |
.. _EESSI: |
| 2 |
|
| 3 |
Adding Environment Modules support to EESSI |
| 4 |
=========================================== |
| 5 |
|
| 6 |
The `European Environment for Scientific Software Installations`_ (EESSI) is |
| 7 |
a collaboration among European HPC centres and industry partners aiming to |
| 8 |
provide a common, optimized stack of scientific software installations usable |
| 9 |
across diverse systems (HPC clusters, workstations, cloud) regardless of |
| 10 |
Linux distribution or CPU architecture |
| 11 |
|
| 12 |
This document analyzes the EESSI framework to determine how it can be adapted |
| 13 |
to support the Environment Modules tool alongside the existing Lmod support. |
| 14 |
|
| 15 |
.. _European Environment for Scientific Software Installations: https://www.eessi.io |
| 16 |
|
| 17 |
Providing equivalent functionality |
| 18 |
---------------------------------- |
| 19 |
|
| 20 |
Here we analyze the content of the EESSI CVMFS repository to find the files |
| 21 |
that are specific to Lmod and define how they should be ported to provide the |
| 22 |
same functionality with Environment Modules. |
| 23 |
|
| 24 |
Files not mentioned here, like ``init/lmod_eessi_archdetect_wrapper.sh``, do |
| 25 |
not need to be adapted to get used in an Environment Modules context. |
| 26 |
|
| 27 |
.. _EESSI Lua module: |
| 28 |
|
| 29 |
``init/modules/EESSI/2025.06.lua`` module |
| 30 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 31 |
|
| 32 |
This Lua modulefile requires a corresponding Tcl version for Environment |
| 33 |
Modules to interpret it. Below are the commands to use when creating the |
| 34 |
equivalent Tcl modulefile to ensure the same functionality: |
| 35 |
|
| 36 |
* ``report`` procedure is equivalent to ``LmodMessage`` (execution should be |
| 37 |
restricted to ``load`` evaluation mode to avoid polluting other modes) |
| 38 |
* ``error`` command is equivalent to ``LmodError`` |
| 39 |
* ``module-help`` (v5.6+) is equivalent to ``help`` (if version below 5.6 is |
| 40 |
expected, define a ``ModulesHelp`` procedure) |
| 41 |
* ``module-tag`` command is equivalent to ``add_property`` (needed to define |
| 42 |
the ``sticky`` tag) |
| 43 |
* ``uname machine`` modulefile command is equivalent than calling ``uname -m`` |
| 44 |
in a sub-process |
| 45 |
* ``versioncmp`` command helps to compare software release number (like |
| 46 |
``convertToCanonical`` does in Lua) |
| 47 |
|
| 48 |
.. _EESSI bash script: |
| 49 |
|
| 50 |
``init/bash`` script |
| 51 |
^^^^^^^^^^^^^^^^^^^^ |
| 52 |
|
| 53 |
Among other things this script sources module tool initialization script, then |
| 54 |
use the ``module`` command to setup environment. |
| 55 |
|
| 56 |
The only adaptation required is to source the Environment Modules |
| 57 |
initialization script if this module tool is selected. |
| 58 |
|
| 59 |
.. _EESSI Lmod initialization shell scripts: |
| 60 |
|
| 61 |
``init/lmod/<shell>`` scripts |
| 62 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 63 |
|
| 64 |
This scripts initializes module tool the following way: |
| 65 |
|
| 66 |
* reset ``MODULEPATH`` to only point to EESSI modulepath |
| 67 |
* source module tool initialization script |
| 68 |
* if initialization has not been performed yet: |
| 69 |
|
| 70 |
* it load default modules defined externally in |
| 71 |
``LMOD_SYSTEM_DEFAULT_MODULES`` or load ``EESSI/$EESSI_VERSION`` |
| 72 |
* define this as the initial environment |
| 73 |
|
| 74 |
* otherwise, module tool refresh shell alias and functions in currently loaded |
| 75 |
modules |
| 76 |
|
| 77 |
Sourcing Environment Modules initialization script will setup the initial |
| 78 |
environment defined in its ``initrc`` configuration script unless either the |
| 79 |
``MODULEPATH`` or ``LOADEDMODULES`` environment variables are non-empty. |
| 80 |
|
| 81 |
Here the idea is to unset ``MODULEPATH`` and ``LOADEDMODULES`` to be able to |
| 82 |
initialize EESSI environment with the content of ``initrc``. With such |
| 83 |
strategy, environment definition is only defined in ``initrc`` and not in |
| 84 |
every shell initialization script. |
| 85 |
|
| 86 |
.. code-block:: tcl |
| 87 |
|
| 88 |
#%Module |
| 89 |
if {[string length [getenv EESSI_SITE_MODULEPATH]]} { |
| 90 |
module use --append [getenv EESSI_SITE_MODULEPATH] |
| 91 |
} |
| 92 |
module use --append [getenv EESSI_MODULEPATH] |
| 93 |
module load EESSI/$EESSI_VERSION |
| 94 |
|
| 95 |
Before unsetting ``LOADEDMODULES``, it is important to purge any eventually |
| 96 |
loaded modules, including sticky modules. If such command fails, because for |
| 97 |
instance ``module`` command is not defined, it should not disturb the script. |
| 98 |
|
| 99 |
The initialization script could look like to setup EESSI environment with |
| 100 |
Environment Modules: |
| 101 |
|
| 102 |
.. code-block:: sh |
| 103 |
|
| 104 |
if [ -z "$__Init_Default_Modules" ]; then |
| 105 |
export __Init_Default_Modules=1; |
| 106 |
|
| 107 |
# unset pre-existing module environment |
| 108 |
module purge --force --no-redirect 2>/dev/null || true |
| 109 |
unset MODULEPATH |
| 110 |
unset LOADEDMODULES |
| 111 |
fi |
| 112 |
|
| 113 |
# Choose an EESSI CVMFS repository |
| 114 |
EESSI_CVMFS_REPO="${EESSI_CVMFS_REPO:-/cvmfs/software.eessi.io}" |
| 115 |
# Choose an EESSI version |
| 116 |
EESSI_VERSION_DEFAULT="2025.06" |
| 117 |
EESSI_VERSION="${EESSI_VERSION:-${EESSI_VERSION_DEFAULT}}" |
| 118 |
export EESSI_MODULEPATH="${EESSI_CVMFS_REPO}/versions/${EESSI_VERSION}/init/modules" |
| 119 |
. "${EESSI_CVMFS_REPO}/versions/${EESSI_VERSION}/compat/linux/$(uname -m)/usr/share/Modules/init/bash" |
| 120 |
|
| 121 |
The ``module refresh`` part could be omitted as Environment Modules |
| 122 |
initialization process already performs a refresh if an environment is found |
| 123 |
set. |
| 124 |
|
| 125 |
``init/Magic_Castle/bash`` script |
| 126 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 127 |
|
| 128 |
This script is similar to `EESSI Lmod initialization shell scripts`_ described |
| 129 |
above and the same adaptation strategy could be applied here. |
| 130 |
|
| 131 |
.. _EESSI-extend Lua module: |
| 132 |
|
| 133 |
``EESSI-extend-easybuild.eb`` easyconfig file |
| 134 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 135 |
|
| 136 |
This easyconfig file is there to produce the extra modulefile |
| 137 |
``EESSI-extend``. It contains a large ``modluafooter`` variable to define the |
| 138 |
content of the modulefile. |
| 139 |
|
| 140 |
A Tcl version of this ``EESSI-extend`` modulefile is needed for Environment |
| 141 |
Modules. A ``modtclfooter`` variable should be added in the easyconfig file to |
| 142 |
define the same kind of code than in ``modluafooter``. |
| 143 |
|
| 144 |
The following Tcl code, similar to the one needed for the `EESSI Lua module`_, |
| 145 |
is needed here to provide the same functionalities than the Lua code: |
| 146 |
|
| 147 |
* ``report`` procedure is equivalent to ``LmodMessage`` (execution should be |
| 148 |
restricted to ``load`` evaluation mode to avoid polluting other modes) |
| 149 |
* ``error`` command is equivalent to ``LmodError`` |
| 150 |
* ``versioncmp`` command helps to compare software release number (like |
| 151 |
``convertToCanonical`` does in Lua) |
| 152 |
* ``module load`` command should be used to translate the if not |
| 153 |
``isloaded()`` then ``load()`` code block (in order to always define the |
| 154 |
dependency link, even if it is already loaded) |
| 155 |
|
| 156 |
``$EESSI_SOFTWARE_PATH/modules`` modulepaths |
| 157 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 158 |
|
| 159 |
These modulepaths contains Lua modulefiles. Environment Modules only supports |
| 160 |
modulefiles written in Tcl language. Thus Tcl modulefiles are needed in EESSI |
| 161 |
in addition to Lua modulefiles. |
| 162 |
|
| 163 |
The features used in Lua modulefiles are also available in Tcl modulefiles, |
| 164 |
thus if Tcl modulefiles are generated by EasyBuild in EESSI repository, they |
| 165 |
will provide the same functionalities than those provided by Lua modulefiles. |
| 166 |
|
| 167 |
``$EESSI_SOFTWARE_PATH/.lmod/lmodrc.lua`` config file |
| 168 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 169 |
|
| 170 |
``lmodrc.lua`` config file, pointed by ``LMOD_RC`` environment variable is |
| 171 |
only used to define location of module cache data. |
| 172 |
|
| 173 |
Environment Modules does not require such file as cache information is |
| 174 |
always stored at the root of each modulepath. Just build the cache files with |
| 175 |
``module cachebuild`` command in a session where the EESSI modulepaths are |
| 176 |
enabled. |
| 177 |
|
| 178 |
As a consequence ``LMOD_RC`` and ``LMOD_CONFIG_DIR`` environment variable |
| 179 |
should not be ported to Environment Modules. |
| 180 |
|
| 181 |
``$EESSI_SOFTWARE_PATH/.lmod/SitePackage.lua`` config file |
| 182 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 183 |
|
| 184 |
This ``SitePackage.lua`` config file has 3 purposes: |
| 185 |
|
| 186 |
* Define a Lmod ``load`` hook through ``eessi_load_hook`` function |
| 187 |
* Define a Lmod ``isVisible`` hook through ``hide_2022b_modules`` function |
| 188 |
* Call ``load_site_specific_hooks`` function that sources additional |
| 189 |
site-specific ``SitePackage.lua`` files if they exist |
| 190 |
|
| 191 |
The ``load`` hook is used to: |
| 192 |
|
| 193 |
* Print warning message when loading specific module to advice to use other |
| 194 |
version of this module: such warning can be defined in modulepath-specific |
| 195 |
``.modulerc`` file with the ``module-warn`` command introduced in |
| 196 |
Environment Modules version 5.6. |
| 197 |
* Breaking load of specific module if some files are not found: Environment |
| 198 |
Modules can achieve the same functionality in modulepath-specific |
| 199 |
``.modulerc`` file with the ``module-forbid`` command. The local files check |
| 200 |
will be performed on any ``module`` command but these forbidden modules will |
| 201 |
be seen already on a ``module avail``. |
| 202 |
|
| 203 |
The ``isVisible`` hook is used to hide modules coming from the ``2022b`` or |
| 204 |
``12.2.0`` toolchains. Environment Modules can achieve the same functionality |
| 205 |
with a modulepath-specific ``.modulerc`` file that calls ``module-hide`` |
| 206 |
command for each of these modules. The full module name and version should be |
| 207 |
used, not a regular expression or a glob pattern. Thus it is advised to |
| 208 |
generate the ``.modulerc`` file after looking at the existing modulefiles in |
| 209 |
modulepath directory. |
| 210 |
|
| 211 |
To provide the same functionality than the ``load_site_specific_hooks`` |
| 212 |
function, a ``siteconfig.tcl`` config file will be needed that will load |
| 213 |
additional site-specific ``siteconfig.tcl`` files if they exist. The |
| 214 |
``source`` Tcl command should be called from ``siteconfig.tcl`` main context |
| 215 |
to load these files. |
| 216 |
|
| 217 |
The main ``siteconfig.tcl`` file should be placed in a central location within |
| 218 |
the EESSI repository and each Environment Modules installation should point to |
| 219 |
it via a symbolic link. No ``LMOD_PACKAGE_PATH`` environment variable should |
| 220 |
be ported to Environment Modules. |
| 221 |
|
| 222 |
Site-specific ``SitePackage.lua`` config file |
| 223 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 224 |
|
| 225 |
As expressed in `EESSI issue #456`_, site-specific ``SitePackage.lua`` config |
| 226 |
file may be used to apply tuning when loading specific modules. Here it meant |
| 227 |
adding environment variable definition into the modulefile evaluation context. |
| 228 |
|
| 229 |
.. _EESSI issue #456: https://github.com/EESSI/software-layer/issues/456 |
| 230 |
|
| 231 |
The software provided by EESSI have a generic configuration that may need to |
| 232 |
be adapted to correctly work on sites, especially things related to the |
| 233 |
underlying high performance network of the supercomputer. |
| 234 |
|
| 235 |
The recommended way to provide an equivalent functionality is to let site |
| 236 |
define the content of a modulefile where they will put all their configuration |
| 237 |
specificities. This modulefile would be automatically loaded by the ``EESSI`` |
| 238 |
modulefile. |
| 239 |
|
| 240 |
With this approach, sites only have to maintain environment definition and not |
| 241 |
complex hook code in addition to environment definition code. The counterpart |
| 242 |
is that these environment changes are loaded once and for all even if the |
| 243 |
modules they relate to are not loaded. |
| 244 |
|
| 245 |
If the strategy to use a site-specific modulefile for this setup does not fit, |
| 246 |
a site-specific ``siteconfig.tcl`` file can be used with the following kind of |
| 247 |
code: |
| 248 |
|
| 249 |
.. code-block:: tcl |
| 250 |
|
| 251 |
proc load_hook {cmd_str op} { |
| 252 |
switch -- [module-info name] { |
| 253 |
OpenMPI/5.0.3 { |
| 254 |
set itrp [getCurrentModfileInterpName] |
| 255 |
interp eval $itrp { |
| 256 |
setenv OMPI_MCA_btl ^openib |
| 257 |
setenv OMPI_MCA_osc ^ucx |
| 258 |
setenv OMPI_MCA_pml ^ucx |
| 259 |
} |
| 260 |
} |
| 261 |
} |
| 262 |
} |
| 263 |
trace add execution evaluateModulefile enter load_hook |
| 264 |
|
| 265 |
Such site-specific ``siteconfig.tcl`` file may be loaded by the main |
| 266 |
``siteconfig.tcl`` section as described in the above section. |
| 267 |
|
| 268 |
Adding Environment Modules into EESSI compat layer |
| 269 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 270 |
|
| 271 |
A Gentoo Ebuild should be developed for Environment Modules to incorporate it |
| 272 |
into the EESSI compatibility layer. |
| 273 |
|
| 274 |
Branching depending on chosen module tool |
| 275 |
----------------------------------------- |
| 276 |
|
| 277 |
EESSI project provides to users two ways to initialize. The following sections |
| 278 |
suggest adaptations to these initialization methods to also support |
| 279 |
Environment Modules. |
| 280 |
|
| 281 |
Loading an EESSI environment module |
| 282 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 283 |
|
| 284 |
Provide EESSI Environment Modules initialization shell scripts like `EESSI |
| 285 |
Lmod initialization shell scripts`_ in a ``init/envmodules`` directory (as |
| 286 |
``init/modules`` directory already exists for another purpose). |
| 287 |
|
| 288 |
Create a Tcl counterpart for `EESSI Lua module`_. Such Tcl modulefile can be |
| 289 |
stored in the same directory as the Lua modulefile: when evaluating the |
| 290 |
``EESSI/2025.06`` module, Lmod will interpret the ``EESSI/2025.06.lua`` file |
| 291 |
and Environment Modules the ``EESSI/2025.06`` file. |
| 292 |
|
| 293 |
Sourcing the EESSI ``bash`` initialization script |
| 294 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 295 |
|
| 296 |
Introduce the ``EESSI_MODULE_TOOL`` environment variable that branches to: |
| 297 |
|
| 298 |
* *Environment Modules* if variable is set to ``EnvironmentModules`` |
| 299 |
* *Lmod* if variable is not set or if set to ``Lmod`` |
| 300 |
|
| 301 |
Use this ``EESSI_MODULE_TOOL`` environment variable in `EESSI bash script`_ to |
| 302 |
determine the correct module tool initialization script to source. |
| 303 |
|
| 304 |
.. code-block:: sh |
| 305 |
|
| 306 |
case "${EESSI_MODULE_TOOL:-Lmod}" in |
| 307 |
Lmod) source $EESSI_EPREFIX/usr/share/Lmod/init/bash ;; |
| 308 |
EnvironmentModules) source $EESSI_EPREFIX/usr/share/Modules/init/bash ;; |
| 309 |
*) error "Module tool '$EESSI_MODULE_TOOL' is not supported" ;; |
| 310 |
esac |
| 311 |
|
| 312 |
Such adaptation helps to keep a single ``bash`` initialization script whatever |
| 313 |
the module tool used. |
| 314 |
|
| 315 |
Reducing maintenance load |
| 316 |
------------------------- |
| 317 |
|
| 318 |
``EESSI/2025.06`` modulefile only in Tcl syntax |
| 319 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 320 |
|
| 321 |
To reduce the maintenance load, it would be nice to have the ``EESSI`` |
| 322 |
modulefiles only in Tcl and not in both Tcl and Lua syntaxes. |
| 323 |
|
| 324 |
Lmod supports evaluation of Tcl modulefiles, but we need to check that a |
| 325 |
syntax understood by both module tools exists to have a single implementation |
| 326 |
of ``EESSI`` modulefile. |
| 327 |
|
| 328 |
Based on the analysis of `EESSI Lua module`_, the following things should be |
| 329 |
taken into account: |
| 330 |
|
| 331 |
* ``report`` procedure should be added to Lmod to support an equivalent of |
| 332 |
``LmodMessage`` in Tcl evaluation context |
| 333 |
* ``module-help`` is available on Lmod (in the not yet released version after |
| 334 |
8.7.65): if EESSI would like to support older Lmod releases, the |
| 335 |
``ModulesHelp`` procedure should be used instead |
| 336 |
* ``add-property`` should be used instead of ``module-tag`` to define the |
| 337 |
module ``sticky``: Environment Modules 5.6+ supports defining a tag with |
| 338 |
this command |
| 339 |
* ``uname machine`` modulefile command is supported by Lmod |
| 340 |
* ``versioncmp`` modulefile command is supported by Lmod since 8.4.7 |
| 341 |
|
| 342 |
``EESSI-extend/2025.06-easybuild`` modulefile only in Tcl syntax |
| 343 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 344 |
|
| 345 |
Like for the ``EESSI`` module, having only a Tcl modulefile for the |
| 346 |
``EESSI-extend`` will help to reduce the overall quantity of code to maintain. |
| 347 |
|
| 348 |
Based on the analysis of `EESSI-extend Lua module`_, the following things |
| 349 |
should be taken into account to have a Tcl version of ``EESSI-extend`` module |
| 350 |
that Lmod is able to evaluate: |
| 351 |
|
| 352 |
* ``report`` procedure should be added to Lmod to support an equivalent of |
| 353 |
``LmodMessage`` in Tcl evaluation context |
| 354 |
* ``module-help`` is available on Lmod (in the not yet released version after |
| 355 |
8.7.65): if EESSI would like to support older Lmod releases, the |
| 356 |
``ModulesHelp`` procedure should be used instead |
| 357 |
* ``versioncmp`` modulefile command is supported by Lmod since 8.4.7 |
| 358 |
* ``depends-on`` should be used instead of ``module load`` to define |
| 359 |
``EasyBuild`` module dependency (to avoid reload of the module by Lmod if it |
| 360 |
is already loaded) |
| 361 |
|
| 362 |
Decommissioning the EESSI ``bash`` initialization script |
| 363 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 364 |
|
| 365 |
EESSI currently provides two ways for initialization which adds load to the |
| 366 |
maintenance process. Advertising a single initialization way may simplify |
| 367 |
things. |
| 368 |
|
| 369 |
Initialization via the ``EESSI`` modulefile allows to switch between EESSI |
| 370 |
releases. |
| 371 |
|
| 372 |
For a smooth migration, the ``bash`` initialization script may at first |
| 373 |
redirect to the ``EESSI`` modulefile initialization process. |
| 374 |
|
| 375 |
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: |