Debian Codegraph @

doc/source/FAQ.rst

raw
1 .. _FAQ:
2
3 Frequently Asked Questions
4 ==========================
5
6 Module command
7 --------------
8
9 How does the ``module`` command work?
10 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
11
12 The command ``module`` is an alias for something like:
13
14 sh:
15
16 .. code-block:: sh
17
18 module ()
19 {
20 eval "$(/some/path/modulecmd sh "$@")"
21 }
22
23 csh:
24
25 .. code-block:: csh
26
27 eval "`/some/path/modulecmd csh !*:q`"
28
29 Where the ``modulecmd`` outputs valid shell commands to *stdout* which manipulates the shell's environment. Any text that is meant to be seen by the user **must** be sent to *stderr*. For example:
30
31 .. code-block:: tcl
32
33 puts stderr "\n\tSome Text to Show\n"
34
35 I have installed Modules but I get a ``module: command not found`` error
36 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
37
38 This error means the ``module`` shell function or alias is not defined in your
39 shell session.
40
41 After :ref:`installing Modules<INSTALL>` and depending on the OS distribution
42 you use, some additional steps may be necessary to make ``module`` properly
43 defined in shell sessions whatever their kind (interactive or
44 non-interactive).
45
46 Follow the :ref:`enable-modules-in-shells` guidelines to adapt the
47 initialization files of the shell you use.
48
49 I put the ``module`` command in a script and I run the script... it doesn't change my environment?
50 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
51
52 A child process (script) can not change the parent process environment. A ``module load`` in a script only affects the environment for the script itself. The only way you can have a script change the current environment is to *source* the script which reads it into the current process.
53
54 sh:
55
56 .. code-block:: sh
57
58 . somescript
59
60 csh:
61
62 .. code-block:: csh
63
64 source somescript
65
66 How do I capture the module command output?
67 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
68
69 This ties in with the very first question. Since the :ref:`module(1)` command is essentially an *eval*, the visible output to the screen must necessarily be sent to *stderr*. It becomes a matter on how to capture output from *stderr* for the various shells. The following examples just show how to spool the output from the **avail** command to a file. This also works for the various other module commands like **list**, **display**, etc. There are also various tricks for piping *stderr* to another program.
70
71 sh:
72
73 .. code-block:: sh
74
75 module avail 2> spoolfile
76
77 csh: (overwrite existing file)
78
79 .. code-block:: csh
80
81 module avail >&! spoolfile
82
83 How to use the module command from Makefile?
84 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
85
86 To make use of the ``module`` command from a Makefile, the shell initialization script should first be sourced within Makefile rule to define the ``module`` function in that context. Environment variable ``MODULESHOME`` may help to locate the shell initialization script in a generic way, like done in the following example:
87
88 .. code-block:: Makefile
89
90 module_list:
91 source $$MODULESHOME/init/bash; module list
92
93 How to preserve my loaded environment when running ``screen``?
94 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
95
96 Usually the `Screen`_ terminal utility is installed with the *setgid* bit
97 set. Depending on the operating system, when a *setgid* program is ran, it may
98 not inherit several environment variables from its parent context like
99 :envvar:`LD_LIBRARY_PATH`. This is a safeguard mechanism to protect the
100 privileged process from being fooled by malicious dynamic libraries.
101
102 As a result, if your currently loaded environment has defined
103 :envvar:`LD_LIBRARY_PATH`, you will find it cleared in the ``screen`` session.
104
105 One way to get your environment correctly initialized within ``screen`` session
106 is to reload it once started with :subcmd:`module reload<reload>` command:
107
108 .. parsed-literal::
109
110 :ps:`$` module load foo/1.0
111 :ps:`$` echo $LD_LIBRARY_PATH
112 /path/to/lib
113 :ps:`$` screen
114 :ps:`$` module list
115 Currently Loaded Modulefiles:
116 1) foo/1.0
117 :ps:`$` echo $LD_LIBRARY_PATH
118
119 :ps:`$` module reload
120 :ps:`$` echo $LD_LIBRARY_PATH
121 /path/to/lib
122
123 Other way around is to reconfigure ``screen`` not to rely on the *setgid* bit
124 for its operations. You may also look at the `tmux`_ utility, which is an
125 alternative to ``screen`` that do not use the *setgid* mechanism.
126
127 .. _Screen: https://www.gnu.org/software/screen/
128 .. _tmux: https://github.com/tmux/tmux/wiki
129
130
131 Modulefiles
132 -----------
133
134 I want the modulefile to source some rc script that came with some application
135 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
136
137 See the module :ref:`sh-to-mod_sub-command` sub-command to translate the
138 environment changes done by a shell script into a :ref:`modulefile(5)`.
139
140 You could also check the :ref:`source-sh_modulefile_command` to directly
141 import the environment changes performed by a shell script within a
142 :ref:`modulefile(5)`.
143
144 How do I specify the *default* modulefile for some modulefile directory?
145 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
146
147 Modules usually uses the the highest lexicographically sorted :ref:`modulefile(5)` under the directory, unless there is a ``.version`` file in that directory which has a format like the following where ``native`` is a modulefile (or a sub-directory) in that directory. It's also possible to set the default with a ``.modulerc`` file with a **module-version** command.
148
149 .. code-block:: tcl
150
151 #%Module
152 set ModulesVersion native
153
154 I cannot access regular man pages now I have loaded some module
155 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
156
157 If your system does not have the :envvar:`MANPATH` environment variable set by
158 default, and you load a module that defines it, you must append a colon
159 (``:``) to the end of the :envvar:`MANPATH` value. This ensures continued
160 access to the system's default man pages.
161
162 See :ref:`man-path` cookbook recipe for details.
163
164 I don't want a *default* modulefile for the directory?
165 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
166
167 Follow the same prescription as setting a *default*, but give some *bogus* value, say *no_default*. The :ref:`module(1)` command will return an error message when no specific version is given.
168
169
170 Build Issues
171 ------------
172
173 The configure script complains about TclX
174 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
175 ::
176
177 ...
178 checking for TclX configuration (tclxConfig.sh)... not found
179 checking for TclX version... using 8.4
180 checking TCLX_VERSION... 8.4
181 checking TCLX_LIB_SPEC... TCLX_LIB_SPEC not found, need to use --with-tclx-lib
182 checking TCLX_INCLUDE_SPEC... TCLX_INCLUDE_SPEC not found, need to use --with-tclx-inc
183 ...
184
185 TclX is an optional library that can speed up some operations. You don't need TclX for modules to compile and work, so you can add the --without-tclx option when configuring and it should proceed to completion. In fact, it should have succeeded anyways and just not attempt to use TclX.
186
187 Otherwise, you can load the TclX library package for your OS and the ``configure`` script should find it. If not then if you know where the ``tclxConfig.sh`` file or the library and include files are placed then use the following options::
188
189 --with-tclx=<dir> directory containing TclX configuration
190 (tclxConfig.sh) [[searches]]
191 --with-tclx-ver=X.Y TclX version to use [[search]]
192 --with-tclx-lib=<dir> directory containing tclx libraries (libtclxX.Y)
193 [[none]]
194 --with-tclx-inc=<dir> directory containing tclx include files
195 (tclExtend.h,...) [[none]]
196
197
198 General information
199 -------------------
200
201 Why does Modules use Tcl?
202 ^^^^^^^^^^^^^^^^^^^^^^^^^
203
204 The first versions of the *Modules* package used shell scripts to do its
205 magic. The original authors then chose to implement the same in C to speed
206 things up and to add features. At the time the only easily embeddable
207 interpreter was Tcl which provided a standard language and the glue.
208
209 A pure Tcl version of the modulecmd script is available, and starting with
210 Modules version 4, it became the default implementation. The use of Tcl for
211 both the core commands and modulefile interpretation simplifies the addition
212 of new features.
213
214 How can I help?
215 ^^^^^^^^^^^^^^^
216
217 See the :ref:`CONTRIBUTING` documentation. It provides guidelines on how to
218 ask questions, report issues, submit patches.
219
220 How do I download the source repository?
221 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
222
223 Anonymously clone the git repository:
224
225 .. code-block:: sh
226
227 git clone https://github.com/envmodules/modules.git
228
229 Then you can create a specific branch and start your local adaptation if any:
230
231 .. code-block:: sh
232
233 cd modules
234 git checkout -b my_work
235
236 I cannot find answer to my question
237 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
238
239 If your question isn't answered in the :ref:`INSTALL` documentation or the
240 :ref:`module(1)` and :ref:`modulefile(5)` man pages, you may also refer to the
241 :ref:`cookbook` section, which offers various installation examples.
242
243 If you still can't find the information you need, consult the
244 :ref:`CONTRIBUTING` documentation to learn how to ask your question within
245 the Modules community.