Module tags
Configuration
No specific configuration
Specification
Introduce one new modulefile command to set tags on modulefiles:
module-tag
A tag is a piece of information associated to individual modulefiles
That is reported along module name on
avail
orlist
sub-command resultsThis piece of information could lead to specific behaviors when handling modulefile over the different module sub-commands or modulefile evaluation modes
For instance, a module with a
sticky
tag set on it cannot be unloaded
Tag may also be set manually with the
--tag
sub-command optionWhen directly used from the terminal session or within modulefile
Applies to
always-load
,depends-on
,prereq
,prereq-all
andprereq-any
modulefile commands
3 different kind of tag exist:
Those inherited from module state, consequence of a specific modulefile command or module action
This kind of tag cannot be defined with the
module-tag
commandAn error is returned otherwise
Specific modulefile command should be used instead as such tag may have specific properties that should also be defined along
Easier for everybody to only have one way to define such tags and not 2 different commands
Every tag holding specific properties should have its dedicated modulefile command to define it
Those set with
module-tag
or--tag
option that lead to a specific behaviorThose set with
module-tag
or--tag
option that are purely informational, no specific behavior
Tags inherited from module state:
hidden
: module not visible, not reported by default inavail
result (tag acquired throughmodule-hide
)hidden-loaded
: loaded module not reported by default inlist
result (tag acquired throughmodule-hide --hidden-loaded
or--tag
option)forbidden
: module that cannot be loaded (tag acquired throughmodule-forbid
)nearly-forbidden
: module that soon cannot be loaded (tag acquired throughmodule-forbid
)loaded
: loaded moduleauto-loaded
: module automatically loaded by another module
Tags set with
module-tag
or--tag
option associated to a specific behavior:sticky
: loaded module cannot be unloaded unless forced or reloaded or when restoring a collection or initial environment (see Sticky modules)super-sticky
: loaded module cannot be unloaded even if forced, it stills can be unloaded if reloaded afterward (see Sticky modules)keep-loaded
: auto_handling mechanism does not unload auto-loaded module
Tags inherited from module state cannot be set with
module-tag
commandAn error is otherwise thrown
Tags inherited from module state cannot be set with
--tag
optionException made for
hidden-loaded
tagAn error is otherwise thrown
Modules project may introduce in the future new tags inherited from new states or new specific behaviors
These new tags will supersede tags set by users using the same naming
Defining
module-tag [options] tag modspec...
Apply
tag
to all modules matchingmodspec
module specificationAdvanced module version specifiers are supported if relative module option is enabled
Full path module specification is not supported, as modulerc are not evaluated when reaching a modulefile specified as full path
One tag could be applied to multiple module specifications with a single
module-tag
command call
module-tag
accepts the following options:--not-user
: specify a list of users unaffected by specified tagging--not-group
: specify a list of groups whose member are unaffected by specified tagging--user
: specify a list of users specifically affected by specified tagging--group
: specify a list of groups whose member are specifically affected by specified tagging
--user
,--group
,--not-user
and--not-group
specification is only supported on Unix platformThese options raise an error when used on Windows platform
In which case relative
module-tag
command is made ineffective as well as remaining content of the modulerc script hosting themError message is clearly seen when trying to load related modules and indicate where to find the erroneous command
--user
and--group
options prevail over--not-user
and--not-group
optionsWhen
--user
or--group
is set, exclusion list from--not-user
and--not-group
are ignored
module-tag
is intended to be used in modulerc filesto be easily fetched during
avail
sub-command processingthey also need to be enabled in modulefile context as global/user rc files are evaluated as modulefile, not modulerc
it enables to dissociate environment changes described in the modulefile from the properties of this modulefile
as these properties are usually site-specific
and modulefile are automatically generated by a build tool
but properties are not always related and set by the build tool
module load --tag tag modspec...
Apply
tag
to the loading module selected throughmodspec
module specificationAvailable from all loading module sub-commands (
load
,try-load
,load-any
andswitch
)Option is preferably written:
--tag=tag
when called from command-line--tag tag
when called from modulefilebut both syntaxes work from both locations
Multiple tags can be set at once by providing a tag list separated by
:
e.g.,
--tag foo:bar
or--tag=foo:bar
Persistency
The
__MODULES_LMTAG
environment variable holds all tag information applying to loaded modulesFollowing the same syntax scheme than
__MODULES_LMCONFLICT
For instance
module/vers&tag&tag:module2&tag
The
loaded
tag is not recorded in__MODULES_LMTAG
environment variableAs it obviously applies to all loaded modules defined in
LOADEDMODULES
environment variable
The
auto-loaded
tag is now recorded in__MODULES_LMTAG
environment variableBefore version 5.0, this tag was not recorded and auto loaded modules where listed in the
__MODULES_LMNOTUASKED
environment variableThis environment variable has been removed in Modules 5.0
Tags applied to loaded modules are saved in collection
Saving tags in collection is introduced in Modules 5.1
When one or more tags are set on a module to save, the
--tag=tag1:tag2
option is addedAfter
module load
And before module specification
When option
--tag=
is found on a module to restoreDefined tags are transmitted to apply them to the module to load
With this change, the
--notuasked
option used in collection previously to indicate module has been auto loaded is replaced by--tag=auto-loaded
optionNo difference is made between tags set manually (through
--tag
option) or tags set in modulerc (throughmodule-tag
or loaded module states): both kind of tags are recorded in collection
The
collection_pin_tag
configuration option determines what tags should be recorded in collectionWhen disabled (default), only the tags set through
--tag
option or resulting from the way the module has been loaded (auto-loaded
andkeep-loaded
tags) are recorded in collectionsWhen enabled, all tags applying to modules are recorded
Exception made for
nearly-forbidden
tag, as its temporal meaning is not fit for being savedChanging default value of
collection_pin_tag
defines theMODULES_COLLECTION_PIN_TAG
variable
The
__MODULES_LMEXTRATAG
environment variable holds all tags applying to loaded modules that have been set through the--tag
optionIt helps to distinguish these specifically set tags from the others
To only record these tags and those resulting from the way the module has been loaded (like
auto-loaded
) in collections by defaultThe following tags set with
--tag
option but which describe a specific state of loaded module are excluded from__MODULES_LMEXTRATAG
record:auto-loaded
keep-loaded
When a collection saved with
collection_pin_tag
option enabled is restored all tags set are then considered extra tags (as they are found set through the--tag
option).
Reporting
Defined tags are reported on
avail
andlist
sub-command resultsReported along modulefile name, within angle brackets (following the HTML tag fashion)
Each tag separated by a colon
For instance
module/version <tag1:tag2>
Tags are right-aligned on each column
One space character at least separates module name and version or list of symbolic version from tag list
Defines tags are reported on module evaluation message block
Applies to Loading, Unloading, Refreshing, Tagging message blocks
Only for the module designation set in the header of the block
Not on the error message, or list of requirement loaded/unloaded
To avoid overloading the output
Tags are reported the same way than on
list
sub-commandIf load evaluation fails, the tags are not reported as they were not yet set
Tags applying to module alias are reported on
avail
reports onlyWhere the module alias stands for itself in the report
On
list
reports, alias is reported along its modulefile targetSo the tags applying to the alias are not reported
Also these tags of the alias are not inherited by alias' target
Tags applying to symbolic version are never reported
As symbols are never reported alone on
avail
orlist
reportsAlways reported along their modulefile target
Also these tags of the symbolic versions are not inherited by symbol's target
Some tags are not reported on
avail
output:hidden-loaded
: correspond to hiding module from loaded list, not from available list
Some tags are not reported on
list
output:loaded
: as every modules reported onlist
are loadedforbidden
: forbidden module cannot be loaded, so it cannot be found among loaded module listhidden
: correspond to hiding module from availabilities, not from loaded list
When reported in JSON output format
tags are listed under the
tags
key
Default
--long
report does not contain tag informationNot to exceed the 80-column output limit by default
Abbreviations
Tag abbreviations are used to translate tag names when reporting them on
avail
orlist
sub-command outputThe
tag_abbrev
configuration defines the abbreviations to apply to each tagSet by default at configure time to
auto-loaded=aL:loaded=L:hidden=H:hidden-loaded=H:forbidden=F:nearly-forbidden=nF:sticky=S:super-sticky=sS:keep-loaded=kL
Note that by default, hidden and hidden-loaded tags share the same abbreviation, as they operate on separate contexts (respectively avail and list contexts)
Configuration value consists in a
key=val
pair value, each key pair are separated by a:
characterFollow the same syntax than
colors
configuration
If an existing tag name is not part of the configuration, it means no abbreviation applies to it
If a tag name has an empty string abbreviation defined it is not reported
Unless if there is an SGR color configuration defined for this tag
The
MODULES_TAG_ABBREV
environment variable is used to set a specific value fortag_abbrev
configurationIf
MODULES_TAG_ABBREV
is set to an empty string, no tag abbreviation applies
In case default value or environment value of
tag_abbrev
is badly seta warning message is returned
value is ignored
if nor the environment nor the default value is correct then no abbreviation applies to tag
Tags are not translated to their defined abbreviation in JSON output format
SGR
If a tag name or tag abbreviation has an SGR code defined in the color list, this SGR code is applied to the module name this tag refer to
Tag name or abbreviation is not reported by itself in this case
As it is now represented by the SGR applied to module name
If an abbreviation exists for a tag, SGR code should be defined for this abbreviation in color list
An SGR code set for tag full name does not apply on the abbreviation of this tag
If multiple tags apply to the same modules and have an SGR code defined for them in the color list
All these SGR codes are rendered one after the other over the module name
For instance if 2 tags apply, the first one will be rendered over the first half of the module name, the second tag over the second half of
Tags use by default background color change to stand out
As module kind (alias, directory, etc) is mainly represented with foreground color change by default,
In case if there are more tags to graphically render than character in module name
The remaining tags are reported by there name or abbreviation and SGR applies over this name or abbreviation
The
MODULES_TAG_COLOR_NAME
environment variable is used to define the tags whose name (or abbreviation if set) should be reportedTheir name does not vanish if a SGR code is defined in the color list for them
Their SGR code is not rendered over the module name
Instead the SGR is applied to the reported tag name (or tag abbreviation if set)
MODULES_TAG_COLOR_NAME
is bound to thetag_color_name
configurationMODULES_TAG_COLOR_NAME
contains the list of tag name (or abbreviation), each tag separated with colon character (:
)If an abbreviation is defined for a tag and one want it to be reported by itself not rendered over module name
This abbreviation should be set in
MODULES_TAG_COLOR_NAME
Not the full tag name this abbreviation refers to
Querying
The
tags
sub-command ofmodule-info
modulefile command enables modulefile to know what tags apply to itselfmodule-info tags
returns a list of all the tags applying to currently evaluated modulean empty list is returned when called from a modulerc evaluation context or if no tag applies to current modulefile
Tags cannot be queried to select modules
Symbolic versions or variants can be used to select modules
Updating tags on already loaded modules
An attempt to load an already loaded module with a
--tag
option set will update the list of extra tags set for this loaded moduleWorks for every sub-command and modulefile commands accepting the
--tag
optionDoes not imply the reload of the loaded module
Add tags to the tag list already set, no removal
As tags defined with
module-tag
cannot be unset
A
tag
sub-command may seem useful to update tag list of already loaded modulesBut it is simpler to use the loading/enabling sub-command to set these extra tags, especially to distinguish between tagging modules or modulepaths
So no need for a dedicated sub-command, use loading or enabled sub-commands instead
If extra tags specified are already set as non-extra tags on already loaded module, the tags are not updated (extra tag list is not updated)
With
prereq
-like commands:all loaded requirement in specified list get their tag list updated
loading requirement does not get its tag list updated (no real use case foreseen for cyclic dependencies)
When restoring collection, extra tags of modules are unset to only keep the extra tags defined in collection.
Extra tags are cleared either when module is unloaded or specifically if module is already loaded at the correct position
When unloading a module, the
auto-loaded
,keep-loaded
and all extra tags are unset from in-memory knowledge, not to reapply automatically these tags if the module is loaded again: only the extra and state tags from this new load will be set.
Tags set over full path module designation
Sometimes a tag should be applied on a specific modulefile whose name and version is available in several modulepaths. For that need, tag has to be set over full path module designation.
Tags set over module full path designation cannot be mixed with tags set over regular module name and version as they only apply to the one modulefile in one modulepath and not to every module using the same short name and version designation.
Forbidden tag set over module full path designation and its properties get precedence over same tag's properties set over short module name and version.
It makes code more complex as full path designation has to be passed as argument along short name to get all tags applying to module.
When checking tag definition for stickiness, if tag is set over full path module then it means stickiness applies to fully qualified module. Thus it cannot be swapped by another version of this module. Defining stickiness over full path module directory is not possible as full path designation should match a modulefile.