Debian Codegraph @

doc/source/design/magic-cookie-check.rst

raw
1 .. _magic-cookie-check:
2
3 Module magic cookie check
4 =========================
5
6 A file should start with a specific string as header line to be considered as
7 a modulefile. This specific string is called the magic cookie and is equal to
8 ``#%Module`` optionally followed by a version number to indicate the minimum
9 version of :file:`modulecmd.tcl` required to interpret this file.
10
11 Magic cookie applies to modulefiles and module RC files. More recently it also
12 applies to the :file:`initrc` configuration file and collections.
13
14 Magic cookie is checked in two different situations:
15
16 * When searching for a modulefile: all files located under a directory used as
17 a modulepath are checked to determine if they are modulefiles to take them
18 into account in the module search.
19
20 * When evaluating a modulefile: when reading file to pass it down to the
21 modulefile or modulerc interpreter, the magic cookie is checked to ensure
22 file can be evaluated.
23
24 The :mconfig:`mcookie_check` configuration option is introduced to be able to
25 disable the magic cookie check. Option accepts the following values:
26
27 * ``always``: This is the default value, magic cookie is checked in both
28 situations described above
29 * ``eval``: magic cookie is only checked prior evaluating file, not when
30 searching for modulefiles
31
32 The :mconfig:`mcookie_check` option works like the :mconfig:`icase` option
33 with value determining a level of cumulative support.
34
35 *FUTURE*: a third value, ``never``, may be interesting to disable the magic
36 cookie check in all situations.
37
38
39 Skipping check when searching modules
40 -------------------------------------
41
42 When setting :mconfig:`mcookie_check` to ``eval``, module magic cookie is not
43 checked when analyzing the files located under an enabled modulepath. This
44 mode significantly diminishes the I/O load when looking at the content of a
45 modulepath as files are not opened and header read for the check.
46
47 This mode requires a perfect control on the files located within the hierarchy
48 of the modulepath directories as:
49
50 * non-modulefiles will be considered modulefiles and will be reported in
51 module search results and used to locate a module corresponding to a query
52
53 * files hidden through restrictive permissions are reported in search results
54 and used to locate a module corresponding to a query
55
56 For these non-modulefiles or read-protected files an error is obtained when
57 trying to evaluate them, as the magic cookie is checked at this step.
58
59 Also the files specified full path are not checked prior evaluation if
60 ``mcookie_check`` is set to ``eval``, so if these files are not modulefile an
61 error will be obtained when trying to evaluate them.
62
63 The ``eval`` mode of ``mcookie_check`` configuration option has no impact on
64 the :file:`initrc` configuration file and collections as such files are not
65 searched like modulefiles. Their header is only checked at evaluation time.
66
67
68 Implementation of ``eval`` mode
69 -------------------------------
70
71 Modulefiles or modulercs are read through the ``readModuleContent`` procedure
72 which is called by:
73
74 * ``execute-modulerc`` or ``execute-modulefile`` procedures when files need to
75 get fully read to get evaluated
76 * ``checkValidModule`` procedure to verify file is a readable modulefile when
77 search for modules
78
79 The ``checkValidModule`` procedure is the one to update when ``mcookie_check``
80 configuration option is not set to ``always`` as this procedure is called by
81 all module search contexts. It is called by:
82
83 * ``findModules`` to check files in directories within modulepaths
84 * ``getModules`` to check files pointed by mfcmd:`module-virtual`
85 * ``getPathToModule`` to check files transmitted as full path file
86
87 .. note:: File readability (permission check) is not verified when
88 ``mcookie_check`` option is set to ``eval`` to keep the full benefit of
89 this mode regarding the I/O load optimization.
90
91 .. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: