| 1 |
.. _sticky-modules: |
| 2 |
|
| 3 |
Sticky modules |
| 4 |
============== |
| 5 |
|
| 6 |
Configuration |
| 7 |
------------- |
| 8 |
|
| 9 |
- No specific configuration |
| 10 |
|
| 11 |
Specification |
| 12 |
------------- |
| 13 |
|
| 14 |
- Once loaded a sticky module cannot be unloaded unless |
| 15 |
|
| 16 |
- forced |
| 17 |
- or reloaded |
| 18 |
- or when restoring a collection |
| 19 |
- or resetting to initial environment state |
| 20 |
|
| 21 |
- If module is super-sticky instead of sticky, it cannot be unloaded even if forced, only if it is reloaded afterward |
| 22 |
|
| 23 |
- Stickiness definition relies on :ref:`module-tags` |
| 24 |
|
| 25 |
- ``module-tag sticky foo/1.0`` defines module *foo/1.0* as sticky |
| 26 |
- ``module-tag super-sticky foo/1.0`` defines module *foo/1.0* as super-sticky |
| 27 |
|
| 28 |
- Stickiness specified over a symbolic version or a module alias has no effect |
| 29 |
|
| 30 |
- ``module-tag`` allows to specify a symbolic module version or a module alias |
| 31 |
- but associated tag will apply to the symbolic version or alias only |
| 32 |
- as modulefile targeted by symbol or alias does not inherit their tags |
| 33 |
- so a sticky or super-sticky tag set on a symbolic version or alias has no effect |
| 34 |
|
| 35 |
- Sticky module can be swapped with another version from same module when stickiness is defined over module parent name |
| 36 |
|
| 37 |
- For instance if stickiness is defined over module *foo*, *foo/1.0* can be swapped with *foo/2.0* |
| 38 |
- Such swap could occur from a ``restore`` or a ``switch`` sub-command |
| 39 |
- As soon as stickiness is defined over a precise module version name (like *foo/1.0*) such module cannot be swapped by another version of *foo* module |
| 40 |
- Stickiness defined over module parent name (like *foo*) means *any version from module foo must be loaded* |
| 41 |
- When stickiness is defined for several module versions using advanced version specifiers like *foo@1:* or *[email protected],2.0* |
| 42 |
|
| 43 |
- it means stickiness applies to the module versions |
| 44 |
- thus they cannot be swapped by another version |
| 45 |
|
| 46 |
- In case stickiness is defined over module parent name and another ``module-tag`` defines stickiness over specific module version name |
| 47 |
|
| 48 |
- it means stickiness applies to the module version |
| 49 |
- thus these versions targeted specifically with ``module-tag`` cannot be swapped by another version from same module |
| 50 |
|
| 51 |
- When a super-sticky module depends on a non-super-sticky module |
| 52 |
|
| 53 |
- If a forced ``purge`` command occurs, the dependent module will be unloaded |
| 54 |
- Which let the super-sticky module with a missing dependency |
| 55 |
|
| 56 |
- Starting Modules 5.2, sticky modules are unloaded |
| 57 |
|
| 58 |
- On :subcmd:`restore` sub-command |
| 59 |
- On :subcmd:`reset` sub-command if :mconfig:`reset_target_state` is not equal to ``__purge__`` |
| 60 |
- No specific error or warning message |
| 61 |
- This is allowed to fully restore the collection in its targeted state |
| 62 |
- No change for super-sticky modules |
| 63 |
|
| 64 |
- An error is reported when trying to unload a sticky or super-sticky module |
| 65 |
|
| 66 |
- As the expected unload is not performed |
| 67 |
- So with the return code and message, user knows that what they asked for was not done |
| 68 |
- Same goes for the ``purge`` command: user expects no more module loaded |
| 69 |
|
| 70 |
- so an error is returned as after the command the sticky module is still loaded |
| 71 |
|
| 72 |
- When the unload is forced a warning message is reported |
| 73 |
|
| 74 |
- the sticky module is unloaded as expected but a warning message is done |
| 75 |
- as the module was tagged not to be unloaded by default |
| 76 |
- user should know they have done something specific |
| 77 |
|
| 78 |
- Reporting an error during a ``purge`` may be considered inappropriate |
| 79 |
|
| 80 |
- as purge cannot unload the sticky, so it may be considered normal not to |
| 81 |
be able to unload the loaded sticky or super-sticky modules |
| 82 |
- a configuration option :mconfig:`sticky_purge` is introduced on Modules |
| 83 |
5.4 to define behavior when facing sticky/super-sticky modules during a |
| 84 |
``purge``: |
| 85 |
|
| 86 |
- when set to ``error`` (default), and error is raised |
| 87 |
- when set to ``warning``, a warning message is reported, no error exit |
| 88 |
code |
| 89 |
- when set to ``silent``, no message reported, no error exit code |
| 90 |
|
| 91 |
- Even when ``sticky_purge`` is set to ``silent``, a warning message is |
| 92 |
reported when unload of sticky module is forced during a purge. |
| 93 |
|
| 94 |
- Module specification on which stickiness is defined is recorded in |
| 95 |
environment when loading a sticky or super-sticky module |
| 96 |
|
| 97 |
- This is introduced on Modules 5.4 |
| 98 |
- With :envvar:`__MODULES_LMSTICKYRULE` environment variable |
| 99 |
- This change is made to determine if a sticky module is reloading, based on |
| 100 |
the sticky rule definition |
| 101 |
- It was previously made with an evaluation of modulerc files toward the |
| 102 |
currently loaded sticky module. But this methodology was not able to |
| 103 |
handle virtual modules whose modulefile is defined outside of enabled |
| 104 |
modulepaths |
| 105 |
- If stickiness is defined over a specific module name and version, sticky |
| 106 |
rule definition is not exported in user environment when loading module. |
| 107 |
This way we know stickiness reloads if exact same module name and version |
| 108 |
reloads |
| 109 |
- If several generic sticky rules applies to the loading module, all of them |
| 110 |
are recorded in user environment |
| 111 |
- When stickiness is set with ``--tag`` option, it applies to the module |
| 112 |
name and version, thus no rule need to be recorded in loaded environment |
| 113 |
|
| 114 |
|
| 115 |
Current limitations |
| 116 |
------------------- |
| 117 |
|
| 118 |
- When swapping a sticky module explicitly targeted by the ``module-tag`` command and which is the default version |
| 119 |
|
| 120 |
- For instance ``module-tag sticky foo/1.0`` and ``module-version foo/1.0 default`` |
| 121 |
- If specified swapped-on module is the generic module name, for instance *foo* |
| 122 |
- ``switch`` sub-command raises an error even if the sticky module is the default version (either implicit or explicitly set) for this module |
| 123 |
|
| 124 |
- When swapping a sticky module defined over a full path modulefile by another |
| 125 |
in different modulepath but with same module name and version |
| 126 |
|
| 127 |
- This switched-on module is currently considered as the sticky module |
| 128 |
reloading |
| 129 |
|
| 130 |
- When swapping a sticky module by itself but specified as full path module |
| 131 |
swap command is not able to detect same module is reloading |
| 132 |
|
| 133 |
|
| 134 |
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: |