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 or list sub-command results

    • This 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 option

  • 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 command

        • An 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 behavior

    • Those 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 in avail result (tag acquired through module-hide)
    • hidden-loaded: loaded module not reported by default in list result (tag acquired through module-hide --hidden-loaded or --tag option)
    • forbidden: module that cannot be loaded (tag acquired through module-forbid)
    • nearly-forbidden: module that soon cannot be loaded (tag acquired through module-forbid)
    • loaded: loaded module
    • auto-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 (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 command

    • An error is otherwise thrown

  • Tags inherited from module state cannot be set with --tag option

    • Exception made for hidden-loaded tag
    • An 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 matching modspec module specification
    • Advanced 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

  • --not-user and --not-group specification is only supported on Unix platform

    • These 2 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 them
    • Error message is clearly seen when trying to load related modules and indicate where to find the erroneous command

  • module-tag is intended to be used in modulerc files

    • to be easily fetched during avail sub-command processing

    • they 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 through modspec module specification

    • Available from all loading module sub-commands (load, try-load, load-any and switch)

    • Option is preferably written:

      • --tag=tag when called from command-line
      • --tag tag when called from modulefile
      • but 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 modules

    • Following 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 variable

    • As it obviously applies to all loaded modules defined in LOADEDMODULES environment variable

  • The auto-loaded tag is now recorded in __MODULES_LMTAG environment variable

    • Before version 5.0, this tag was not recorded and auto loaded modules where listed in the __MODULES_LMNOTUASKED environment variable
    • This 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 added

      • After module load
      • And before module specification

    • When option --tag= is found on a module to restore

      • Defined 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 option

    • No difference is made between tags set manually (through --tag option) or tags set in modulerc (through module-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 collection

    • When disabled (default), only the tags set through --tag option or resulting from the way the module has been loaded (auto-loaded and keep-loaded tags) are recorded in collections
    • When enabled, all tags applying to modules are recorded
    • Exception made for nearly-forbidden tag, as its temporal meaning is not fit for being saved
    • Changing default value of collection_pin_tag defines the MODULES_COLLECTION_PIN_TAG variable

  • The __MODULES_LMEXTRATAG environment variable holds all tags applying to loaded modules that have been set through the --tag option

    • It 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 default

    • The 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 and list sub-command results

    • Reported 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-command

    • If load evaluation fails, the tags are not reported as they were not yet set

  • Tags applying to module alias are reported on avail reports only

    • Where the module alias stands for itself in the report

    • On list reports, alias is reported along its modulefile target

      • So 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 or list reports
    • Always 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 on list are loaded
    • forbidden: forbidden module cannot be loaded, so it cannot be found among loaded module list
    • hidden: 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 information

    • Not to exceed the 80-column output limit by default

Abbreviations

  • Tag abbreviations are used to translate tag names when reporting them on avail or list sub-command output

  • The tag_abbrev configuration defines the abbreviations to apply to each tag

    • Set 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 : character

      • Follow 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 for tag_abbrev configuration

      • If 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 set

    • a 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 reported

    • Their 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 the tag_color_name configuration

    • MODULES_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 of module-info modulefile command enables modulefile to know what tags apply to itself

    • module-info tags returns a list of all the tags applying to currently evaluated module
    • an 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 module

    • Works for every sub-command and modulefile commands accepting the --tag option
    • Does 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 modules

    • But 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.