| 1 |
.. _source-script-in-modulefile: |
| 2 |
|
| 3 |
Source shell script in modulefile |
| 4 |
================================= |
| 5 |
|
| 6 |
When working with large software suite providing a shell script for their |
| 7 |
enablement in user environment, it is usually desired to also provide access |
| 8 |
to these software through ``module``. However these software enablement may be |
| 9 |
complex and it may be wise to keep using the shell script provided by software |
| 10 |
editor rather crafting a modulefile from scratch. |
| 11 |
|
| 12 |
This recipe describes how to make modulefiles for such software by using the |
| 13 |
enablement shell script provided with them. |
| 14 |
|
| 15 |
Implementation |
| 16 |
-------------- |
| 17 |
|
| 18 |
Modules version 4.6 introduces a new sub-command named :subcmd:`sh-to-mod` and |
| 19 |
a new modulefile command named :mfcmd:`source-sh`. The ``sh-to-mod`` |
| 20 |
outputs as a modulefile content the environment changes done by the evaluation |
| 21 |
of a shell script passed as argument. On the other hand, the ``source-sh`` |
| 22 |
modulefile command sources environment changes done by the evaluation of a |
| 23 |
shell script passed as argument. |
| 24 |
|
| 25 |
Both new features relies on the same mechanism that starts a designated shell |
| 26 |
to: |
| 27 |
|
| 28 |
* get current environment state (environment variables, shell aliases, shell |
| 29 |
functions and current working directory) |
| 30 |
* source designated shell script with defined arguments |
| 31 |
* get resulting environment state |
| 32 |
|
| 33 |
Once done, environment prior and after script source are compared to determine |
| 34 |
the corresponding environment changes and translate those changes into |
| 35 |
modulefile commands (:mfcmd:`setenv`, :mfcmd:`prepend-path`, |
| 36 |
:mfcmd:`set-alias`, :mfcmd:`set-function`, ...). |
| 37 |
|
| 38 |
:subcmd:`sh-to-mod` outputs these resulting modulefile commands. This output |
| 39 |
can be redirected into a file to create a modulefile. :mfcmd:`source-sh` on |
| 40 |
the other hand sources the resulting modulefile commands to evaluate them as |
| 41 |
if they were written in the modulefile calling ``source-sh``. |
| 42 |
|
| 43 |
``sh-to-mod`` and ``source-sh`` support the following shells: *sh*, *dash*, |
| 44 |
*csh*, *tcsh*, *bash*, *ksh*, *ksh93*, *zsh* and *fish*. |
| 45 |
|
| 46 |
**Compatible with Modules v4.6+** |
| 47 |
|
| 48 |
Basic usage example |
| 49 |
------------------- |
| 50 |
|
| 51 |
For this recipe, a dummy software named *foo* is used as example. *foo* is |
| 52 |
installed in version 1.2 in ``example/source-script-in-modulefile/foo-1.2`` |
| 53 |
directory and it provides a ``foo-setup.sh`` script to activate itself in |
| 54 |
user environment: |
| 55 |
|
| 56 |
.. literalinclude:: ../../example/source-script-in-modulefile/foo-1.2/foo-setup.sh |
| 57 |
:language: bash |
| 58 |
:caption: foo-setup.sh |
| 59 |
|
| 60 |
First line of ``foo-setup.sh`` script helps to identify which shell needs to |
| 61 |
be used to evaluate it: ``bash``. |
| 62 |
|
| 63 |
:subcmd:`sh-to-mod` may be used to get this script translated as a |
| 64 |
modulefile: |
| 65 |
|
| 66 |
.. parsed-literal:: |
| 67 |
|
| 68 |
:ps:`$` module sh-to-mod bash example/source-script-in-modulefile/foo-1.2/foo-setup.sh arg1 |
| 69 |
#%Module |
| 70 |
:sgrcm:`prepend-path` PATH example/source-script-in-modulefile/foo-1.2/bin |
| 71 |
:sgrcm:`set-alias` foo {foobin -q -l} |
| 72 |
:sgrcm:`setenv` FOOENV arg1 |
| 73 |
|
| 74 |
Output could be redirected into a ``foo/1.2`` file and make it the modulefile |
| 75 |
to enable software foo: |
| 76 |
|
| 77 |
.. parsed-literal:: |
| 78 |
|
| 79 |
:ps:`$` mkdir -p modulefiles/foo |
| 80 |
:ps:`$` module sh-to-mod bash example/source-script-in-modulefile/foo-1.2/foo-setup.sh arg1 >modulefiles/foo/1.2 |
| 81 |
:ps:`$` module use ./modulefiles |
| 82 |
:ps:`$` module show foo |
| 83 |
------------------------------------------------------------------- |
| 84 |
:sgrhi:`modulefiles/foo/1.2`: |
| 85 |
|
| 86 |
:sgrcm:`prepend-path` PATH example/source-script-in-modulefile/foo-1.2/bin |
| 87 |
:sgrcm:`set-alias` foo {foobin -q -l} |
| 88 |
:sgrcm:`setenv` FOOENV arg1 |
| 89 |
------------------------------------------------------------------- |
| 90 |
|
| 91 |
Instead of transforming shell script in modulefile, a modulefile using |
| 92 |
:mfcmd:`source-sh` modulefile command to evaluate shell script at modulefile |
| 93 |
evaluation time may be written: |
| 94 |
|
| 95 |
.. literalinclude:: ../../example/source-script-in-modulefile/modulefiles/foo/1.2 |
| 96 |
:language: Tcl |
| 97 |
:caption: modulefiles/foo/1.2 |
| 98 |
|
| 99 |
When displaying a modulefile using ``source-sh`` modulefile command, |
| 100 |
modulefile commands resulting from ``source-sh`` evaluation are reported: |
| 101 |
|
| 102 |
.. parsed-literal:: |
| 103 |
|
| 104 |
:ps:`$` module show foo/1.2 |
| 105 |
------------------------------------------------------------------- |
| 106 |
:sgrhi:`.../modulefiles/foo/1.2`: |
| 107 |
|
| 108 |
:sgrcm:`prepend-path` PATH example/source-script-in-modulefile/foo-1.2/bin |
| 109 |
:sgrcm:`set-alias` foo {foobin -q -l} |
| 110 |
:sgrcm:`setenv` FOOENV arg1 |
| 111 |
------------------------------------------------------------------- |
| 112 |
|
| 113 |
Loading this ``foo/1.2`` module will enable access to software *foo*: |
| 114 |
|
| 115 |
.. parsed-literal:: |
| 116 |
|
| 117 |
:ps:`$` module load foo/1.2 |
| 118 |
:ps:`$` alias foo |
| 119 |
alias foo='foobin -q -l' |
| 120 |
:ps:`$` foo |
| 121 |
foo, version 1.2 |
| 122 |
|
| 123 |
Unloading ``foo/1.2`` module will properly revert these environment settings: |
| 124 |
|
| 125 |
.. parsed-literal:: |
| 126 |
|
| 127 |
:ps:`$` module unload foo/1.2 |
| 128 |
:ps:`$` alias foo |
| 129 |
bash: alias: foo: not found |
| 130 |
:ps:`$` foobin |
| 131 |
bash: foobin: command not found |
| 132 |
|
| 133 |
As conclusion, these new features enable to leverage the setup scripts that |
| 134 |
are provided along with software to make them reachable from the ``module`` |
| 135 |
environment. |
| 136 |
|
| 137 |
Usage with shell-specific scripts |
| 138 |
--------------------------------- |
| 139 |
|
| 140 |
When the initialization script provided by software only defines environment |
| 141 |
variables, this script could be used to setup the user environment through the |
| 142 |
use of ``source-sh`` in a modulefile whatever the shell ran by user, as the |
| 143 |
``module`` command will accurately translate script changes into the language |
| 144 |
of the running shell. |
| 145 |
|
| 146 |
For instance the ``foo/1.2`` module, that uses the ``source-sh`` modulefile |
| 147 |
command over the ``foo-setup.sh`` bash script, could also be used when running |
| 148 |
the ``tcsh`` or ``fish`` shell: |
| 149 |
|
| 150 |
.. parsed-literal:: |
| 151 |
|
| 152 |
:ps:`$` echo $version |
| 153 |
tcsh 6.22.03 (Astron) 2020-11-18 (x86_64-unknown-linux) ... |
| 154 |
:ps:`$` module show foo/1.2 |
| 155 |
------------------------------------------------------------------- |
| 156 |
:sgrhi:`.../modulefiles/foo/1.2`: |
| 157 |
|
| 158 |
:sgrcm:`prepend-path` PATH example/source-script-in-modulefile/foo-1.2/bin |
| 159 |
:sgrcm:`set-alias` foo {foobin -q -l} |
| 160 |
:sgrcm:`setenv` FOOENV arg1 |
| 161 |
------------------------------------------------------------------- |
| 162 |
:ps:`$` module load foo/1.2 |
| 163 |
:ps:`$` foo |
| 164 |
foo, version 1.2 |
| 165 |
|
| 166 |
Software may sometimes provide a specific script for each shell they support |
| 167 |
as they do not perform their initialization the same way on every shell. Quite |
| 168 |
often a shell function is defined for *sh* shells whereas an alias is setup |
| 169 |
for *csh* shells (as such shells do not support shell function). |
| 170 |
|
| 171 |
Dummy software *bar* is used to demonstrate this situation. *bar* is installed |
| 172 |
in version 2.1 in ``example/source-script-in-modulefile/bar-2.1`` directory |
| 173 |
and it provides a ``bar-setup.sh`` and a ``bar-setup.csh`` scripts to activate |
| 174 |
itself in user environment, depending on the shell kind used. |
| 175 |
|
| 176 |
.. literalinclude:: ../../example/source-script-in-modulefile/bar-2.1/bar-setup.sh |
| 177 |
:language: bash |
| 178 |
:caption: bar-setup.sh |
| 179 |
|
| 180 |
.. literalinclude:: ../../example/source-script-in-modulefile/bar-2.1/bar-setup.csh |
| 181 |
:language: csh |
| 182 |
:caption: bar-setup.csh |
| 183 |
|
| 184 |
To accurately initialize environment for *bar* software, the ``bar`` module |
| 185 |
needs to call the ``.sh`` script if user is currently running a shell from the |
| 186 |
sh family, or to call the ``.csh`` script if user runs a csh-kind shell. |
| 187 |
|
| 188 |
.. literalinclude:: ../../example/source-script-in-modulefile/modulefiles/bar/2.1 |
| 189 |
:language: Tcl |
| 190 |
:caption: modulefiles/bar/2.1 |
| 191 |
|
| 192 |
This way the ``bar`` shell function is initialized when loading module from a user |
| 193 |
environment running a *sh* shell: |
| 194 |
|
| 195 |
.. parsed-literal:: |
| 196 |
|
| 197 |
:ps:`$` echo $BASH_VERSION |
| 198 |
5.1.0(1)-release |
| 199 |
:ps:`$` module use example/source-script-in-modulefile/modulefiles |
| 200 |
:ps:`$` module show bar |
| 201 |
------------------------------------------------------------------- |
| 202 |
:sgrhi:`.../modulefiles/bar/2.1`: |
| 203 |
|
| 204 |
:sgrcm:`prepend-path` PATH example/source-script-in-modulefile/bar-2.1/bin |
| 205 |
:sgrcm:`set-function` bar { |
| 206 |
barbin -q -l} |
| 207 |
------------------------------------------------------------------- |
| 208 |
:ps:`$` module load bar |
| 209 |
:ps:`$` type bar |
| 210 |
bar is a function |
| 211 |
bar () |
| 212 |
{ |
| 213 |
barbin -q -l |
| 214 |
} |
| 215 |
:ps:`$` bar |
| 216 |
bar, version 2.1 |
| 217 |
|
| 218 |
Whereas the ``bar`` shell alias is setup on *csh* shell environment: |
| 219 |
|
| 220 |
.. parsed-literal:: |
| 221 |
|
| 222 |
:ps:`$` echo $version |
| 223 |
tcsh 6.22.03 (Astron) 2020-11-18 (x86_64-unknown-linux) ... |
| 224 |
:ps:`$` module use example/source-script-in-modulefile/modulefiles |
| 225 |
:ps:`$` module show bar |
| 226 |
------------------------------------------------------------------- |
| 227 |
:sgrhi:`.../modulefiles/bar/2.1`: |
| 228 |
|
| 229 |
:sgrcm:`prepend-path` PATH example/source-script-in-modulefile/bar-2.1/bin |
| 230 |
:sgrcm:`set-alias` bar {barbin -q -l} |
| 231 |
------------------------------------------------------------------- |
| 232 |
:ps:`$` module load bar |
| 233 |
:ps:`$` alias bar |
| 234 |
barbin -q -l |
| 235 |
:ps:`$` bar |
| 236 |
bar, version 2.1 |
| 237 |
|
| 238 |
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: |