Debian Codegraph @

doc/source/design/sticky-modules.rst

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