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