Debian Codegraph @

doc/source/design/eessi.rst

raw
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: