1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
.. _initial-environment:
Initial environment
===================
Initial environment corresponds to the environment state at the end of Modules
initialization.
* initialization performed by :subcmd:`autoinit` sub-command
* which evaluates :file:`modulespath` and :file:`initrc` initialization files
if they exist and if :envvar:`MODULEPATH` and :envvar:`LOADEDMODULES` are
both found unset or empty
* environment state is composed of:
* enabled modulepaths
* loaded modules
* with manual and modulerc tags applied onto loaded modules
* with variant values applied onto loaded modules
Initial environment is what you get when you connect to a machine, with the
environment configuration (modulepaths, loaded modules) defined by the
system administrator of this machine. Plus your own addition if the
:file:`initrc` file set by system administrator calls ``module restore`` to
load your default collection.
Persistency
-----------
Once defined after the evaluation of :file:`modulespath` and :file:`initrc`
initialization files, the initial environment is stored in an environment
variable: :envvar:`__MODULES_LMINIT`.
* colon-separated list serializing content of a collection
* each element is a ``module use`` or ``module load`` command describing the
initial environment (modulepaths, loaded modules, their tags and variants)
* variable is named following *private* name convention as it is not expected
to be modified by user
Initial environment is stored as a collection in user environment to:
* use collection mechanisms to restore or view the initial environment
* stored in user environment to attach to the current shell session
Like for other ``__MODULES_LM*`` persistency variables, ``:`` character in
content (like tag list separator) is translated into ``<`` character. Not to
be confused with element separator in such variable.
As what is stored in ``__MODULES_LMINIT`` corresponds to the loaded
environment after Modules initialization, this environment is consistent
(i.e., no missing dependency for loaded modules).
reset sub-command
-----------------
:subcmd:`reset` sub-command enables to restore the initial environment. It
means to unuse enabled modulepaths and unload loaded modules then use initial
modulepaths and load initial modules.
General properties:
* Shortcut name: none
* Accepted option: :option:`--force`, :option:`--auto`, :option:`--no-auto`
* Expected number of argument: 0
* Accept boolean variant specification: no
* Parse module version specification: no
* Fully read modulefile when checking validity: yes
* Sub-command only called from top level: yes
* Lead to modulefile evaluation: yes (``unload`` and ``load`` modes)
``reset`` is equivalent to ``restore __init__``. It relies totally on
:subcmd:`restore` sub-command that unsets current environment and restore
initial environment, like done for any collection.
Behavior of ``reset`` sub-command can be changed with `reset_target_state
configuration option`_.
As it evaluates modules, ``--force``, ``--auto`` and ``--no-auto`` options can
be set for ``reset`` sub-command. But, as for ``restore`` sub-command these
options should have no impact, as:
* collection fully describes dependencies to load, no automatic resolution
needed
* current environment unload is processed module by module, no automatic
resolution expected
* *sticky* modules are unloaded by default, no need to force unload
* *super-sticky* cannot be unloaded even if forced
``reset`` sub-command outputs *Loading*, *Unloading*, *Tagging* messages like
``restore`` sub-command. Which is the default output mode for a sub-command
triggering multiple module evaluations that cannot be guessed by user.
*FUTURE*: an ``init`` tag could be applied onto loaded modules and used
modulepaths of initial environment to let users spot what parts of their
environment is from the initial one.
restore/saveshow sub-commands
-----------------------------
:subcmd:`restore` and :subcmd:`saveshow` sub-commands respectively restore and
show the initial environment when called with the ``__init__`` argument.
* instead of reading a collection file, the two sub-commands read the content
of the :envvar:`__MODULES_LMINIT` variable
* specific name ``__init__`` is used not to confuse with an existing
collection
``restore`` sub-command is changed to restore initial environment when no
argument is provided in case no default collection exists. This is done to
align behavior with Lmod.
Same behavior change is applied on ``saveshow`` sub-command: initial
environment is displayed when no argument provided and no default collection
exists.
reset_target_state configuration option
---------------------------------------
:mconfig:`reset_target_state` defines targeted state of ``reset`` sub-command.
What environment to restore.
* equals ``__init__`` by default, which corresponds to the behavior described
above (initial environment is restored)
* when set with :subcmd:`config` sub-command, defines environment variable
:envvar:`MODULES_RESET_TARGET_STATE` for value persistency
* other value accepted:
* ``__purge__``: sub-command performs a ``module purge``
* any other value: sub-command restore designated collection (an error is
obtained if no collection with such name exists)
The ability to reset to a given collection enables user to define what is
their initial environment state. Useful if they do not want to rely on the
initial environment setup by sysadmins. For instance when sysadmins do not set
a ``module restore`` in :file:`initrc` to restore user's default collection
when user's session initializes.
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent:
|
