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