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 - Starting Modules 5.7, ``purge`` preserves requirements of retained sticky
52 and super-sticky modules
53
54 - Direct and indirect requirements are preserved, even without a sticky tag
55 - Requirements are preserved whatever their load order relative to their
56 dependent, as a requirement may be loaded after its dependent
57 - Only strong requirements are preserved: an alternative requirement may
58 be unloaded while another loaded module still satisfies it
59 - A forced ``purge`` unloads sticky modules and can unload their
60 requirements, but preserves super-sticky modules and their requirements
61 - Before version 5.7, a forced ``purge`` could unload a non-super-sticky
62 requirement and leave a super-sticky module with a missing dependency
63
64 - Starting Modules 5.2, sticky modules are unloaded
65
66 - On :subcmd:`restore` sub-command
67 - On :subcmd:`reset` sub-command if :mconfig:`reset_target_state` is not equal to ``__purge__``
68 - No specific error or warning message
69 - This is allowed to fully restore the collection in its targeted state
70 - No change for super-sticky modules
71
72 - An error is reported when trying to unload a sticky or super-sticky module
73
74 - As the expected unload is not performed
75 - So with the return code and message, user knows that what they asked for was not done
76 - Same goes for the ``purge`` command: user expects no more module loaded
77
78 - so an error is returned as after the command the sticky module is still loaded
79
80 - When the unload is forced a warning message is reported
81
82 - the sticky module is unloaded as expected but a warning message is done
83 - as the module was tagged not to be unloaded by default
84 - user should know they have done something specific
85
86 - Reporting an error during a ``purge`` may be considered inappropriate
87
88 - as purge cannot unload the sticky, so it may be considered normal not to
89 be able to unload the loaded sticky or super-sticky modules
90 - a configuration option :mconfig:`sticky_purge` is introduced on Modules
91 5.4 to define behavior when facing sticky/super-sticky modules during a
92 ``purge``:
93
94 - when set to ``error`` (default), and error is raised
95 - when set to ``warning``, a warning message is reported, no error exit
96 code
97 - when set to ``silent``, no message reported, no error exit code
98
99 - Starting Modules 5.7, this configuration also applies to skipped unload
100 of requirements of retained sticky or super-sticky modules
101 - Requirement unload is reported as ``Unload of sticky module requirement
102 skipped`` or ``Unload of super-sticky module requirement skipped``
103 - If both sticky and super-sticky modules require a module, the
104 super-sticky tag takes precedence in this message
105
106 - Even when ``sticky_purge`` is set to ``silent``, a warning message is
107 reported when unload of sticky module is forced during a purge.
108
109 - Module specification on which stickiness is defined is recorded in
110 environment when loading a sticky or super-sticky module
111
112 - This is introduced on Modules 5.4
113 - With :envvar:`__MODULES_LMSTICKYRULE` environment variable
114 - This change is made to determine if a sticky module is reloading, based on
115 the sticky rule definition
116 - It was previously made with an evaluation of modulerc files toward the
117 currently loaded sticky module. But this methodology was not able to
118 handle virtual modules whose modulefile is defined outside of enabled
119 modulepaths
120 - If stickiness is defined over a specific module name and version, sticky
121 rule definition is not exported in user environment when loading module.
122 This way we know stickiness reloads if exact same module name and version
123 reloads
124 - If several generic sticky rules applies to the loading module, all of them
125 are recorded in user environment
126 - When stickiness is set with ``--tag`` option, it applies to the module
127 name and version, thus no rule need to be recorded in loaded environment
128
129
130 Current limitations
131 -------------------
132
133 - When swapping a sticky module explicitly targeted by the ``module-tag`` command and which is the default version
134
135 - For instance ``module-tag sticky foo/1.0`` and ``module-version foo/1.0 default``
136 - If specified swapped-on module is the generic module name, for instance *foo*
137 - ``switch`` sub-command raises an error even if the sticky module is the default version (either implicit or explicitly set) for this module
138
139 - When swapping a sticky module defined over a full path modulefile by another
140 in different modulepath but with same module name and version
141
142 - This switched-on module is currently considered as the sticky module
143 reloading
144
145 - When swapping a sticky module by itself but specified as full path module
146 swap command is not able to detect same module is reloading
147
148
149 .. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: