Debian Codegraph @

doc/source/design/initial-environment.rst

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