Debian Codegraph @

doc/source/cookbook/source-script-in-modulefile.rst

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