Variants

Configuration

  • Variant mechanism requires the advanced_version_spec option to be enabled

    • Variants can be seen as an extension of the advanced module version specifiers

Specification

Defining

  • variants are defined for modulefiles within concerned modulefiles with the variant modulefile command

    • variants are bound to the modulefile they target

    • especially modulefile evaluation may be guided by the value selected for the variants

    • so it makes more sense to have variants defined within modulefiles rather in modulercs

  • variant --default? defaultval? --alias? {aliasname...?} name value? ...?

  • name restrained to the accepted variable name

    • which should correspond to a sequence of one or more characters that are a letter, digit, underscore and minus sign

    • first character cannot be a minus sign

    • name as a whole cannot correspond to a number

    • if we want to match Spack here also: [A-Za-z0-9_][A-Za-z0-9_-]*

    • raise error otherwise

  • a variant name that has already been defined as variant or variant alias for this modulefile evaluation overwrites previous definition

    • it is up to modulefile author to ensure there is no duplicate

    • no need this way to check in modulecmd.tcl code if variant has already been defined

  • may have a default value (when --default argument is passed)

    • if not, variant is undefined

    • argument --default should be associated a defaultval argument

      • raise error otherwise

    • default value should be part of possible value list if value list provided

      • error is raised otherwise when default value is used, as it does not correspond to an accepted value

        • ex: variant name --default 1.8 1.0 2.0

      • when no list of accepted value is provided, default value could be any value

  • may be set as a Boolean variant (when --boolean argument is passed)

    • a Boolean variant may equal true or false

  • may have a list of accepted values

    • unless if defined as a Boolean variant

    • passed value(s) must correspond to those accepted

      • raise error otherwise

      • raised error is a global error to signal specification issue, not a modulefile error

    • an error is raised if one or more accepted values are defined on a Boolean variant

    • non-Boolean variants cannot define Boolean value in their accepted value list

      • as Boolean values are translated to their canonical form (0 or 1) when specified

      • an error is raised otherwise

      • exception made for the 0 and 1 integers

    • when no list of accepted value is provided it means any value is accepted

      • it is up to the modulefile author to write the appropriate test after variant declaration to check that the value provided is acceptable

  • may be aliased (when argument --alias is passed) in which case:

    • argument --alias should be associated one or a list of alias names

      • raise error otherwise

    • defined alias names should be valid variant name (see spec above)

      • raise error otherwise

    • should not be already defined as variant or variant alias

      • raise error otherwise

    • variant alias could negate its target (when alias name is prefixed by -)

      • meaning if alias variant is set to false its target is set to true

      • only possible if targeted variant is Boolean

        • raise error otherwise

      • no support of ~ as an alternative negated prefix to only get one way to write negation

  • require a value to be set

    • raise error if no value set for variant (no value specified and no defined default)

  • to validate variant value is coherent against other variant values or any other test

    • it is up to the modulefile author to write the appropriate test after all variant declaration

    • and then raise error if variant combination is not appropriate

    • as there is no way to automatically determine when all variants are declared

Evaluating

  • when reaching variant command in modulefile

  • set a key name in array ModuleVariant if variant name has been specified or if it owns a default value

    • variable ModuleVariant($name) is not defined if variant not specified and no default for it

      • error is raised if used in this case

  • if variant name can be aliased, if alias is set it specifies the value of variant name

    • evaluated from left to right, in case variant is set and also its aliases

    • negating aliases sets its reversed value to Boolean variant

  • variant alias is not instantiated in ModuleVariant array

    • therefore accessing $ModuleVariant($aliasname) will raise an error

  • raise error if variant name:

    • has been specified but passed value is incorrect

    • is wrongly declared in modulefile (e.g., invalid name specified)

  • then variable $ModuleVariant(name) could be used to adapt modulefile evaluation

  • to know all variant currently set, use [array names ModuleVariant]

    • but beware that only the variant already evaluated will be set in array

    • must use after all the variant to be set in the modulefile to accurately get all variant defined

  • if variant accepted values are Booleans, variable could be directly used in conditional tests

    • like if {$ModuleVariant($name)} {...

  • quoting Tcl doc, Booleans could have many forms:

    • If string is any of 0, false, no, or off, then Tcl_GetBoolean stores a zero value at *boolPtr.

    • If string is any of 1, true, yes, or on, then 1 is stored at *boolPtr.

    • Any of these values may be abbreviated, and upper-case spellings are also acceptable

  • variants with a shortcut defined for them, are resolved to their full name and transmitted this way to the modulefile

    • therefore no entry in ModuleVariant array is made for the shortcut name

  • as special variant version will not be implemented on Modules 4.8, an error is raised if a variant is named version

    • to ensure no usage of this variant name will be made before its special mechanism availability

  • special variant version is instantiated as variable ModuleVariant(version) if declared

    • will be set to value that may be specified with the @ shortcut

    • will initially work as any other variant (accepted list of value, default value)

      • using variant version --default 1.8 1.8 1.10

      • is equivalent of having two modulefiles mod/1.8 and mod/1.10

      • with a default defined: module-version mod/1.8 default

    • FUTURE: could be refined later on to accept range then select latest version or defined default if in range

    • note that ModuleVariant(version) is set only if a version variant is declared in modulefile

    • querying [module-info name] returns modulefile designation appended by the version variant: @versionvalue

  • at the end of the modulefile evaluation, if module specification contains a variant which is not defined in modulefile

    • an error is raised

  • for the different evaluation modes:

    • load, help and test apply evaluation mechanism described above

      • for the help and test modes it helps to see how the modulefile reacts to the different variant value

    • display applies evaluation mechanism described above but allow variant to be unspecified

      • to help learning all the variant defined by the modulefile

      • as a result unspecified variant is not instantiated in the ModuleVariant array variable

      • with unspecified variant a user will not accurately see how the modulefile reacts to the different variant value

        • evaluation error is obtained if accessing the ModuleVariant array variable for an unspecified variant

      • on display mode, the variant command is reported in addition of its evaluation

    • unload evaluates the mechanism described above but the specified variants are fetched from loaded module persistent information

      • version variant value is fetched from the module specification to identify the module to unload

      • other variant specification on the unload command are dropped once matching loaded module is identified

        • however this specification remains available when querying [module-info specified]

      • variant values are defined within modulefile context by the evaluation of the variant modulefile commands

        • like it is done during a load modulefile evaluation

        • this way variables related to variant are instantiated the same way whether module is loading or unloading

        • so it is easier for modulefile author to understand how the modulefile code is evaluated

      • variant evaluated during modulefile unload may produce an error

        • if variant value not found defined or if value recorded in persistency does not match an allowed value

        • should encourage variants to be consistent between the load and unload evaluation phases

    • whatis ignores all variants from the module specification (only the module names are retained)

      • like for setenv or *-path modulefile commands on this mode, variant will set the ModuleVariant array with a empty string for each variant defined in the modulefile

      • this is done to avoid the undefined variable error if these variables are used later in the modulefile

      • however variant specified in module specification is used to filter modules to evaluate in whatis mode thanks to the extra match search mechanism

      • FUTURE: if the different version variant values are considered as different modulefiles in the future, then whatis may evaluates the version variant from module specification

getvariant

  • A getvariant modulefile command is added following the same principle than getenv

    • A variant name is passed as argument

    • Corresponding variant value is returned if it is defined

    • If not defined the value if not defined argument is returned

    • By default value if not defined argument equals to the empty string

  • getvariant should be preferred to accessing variant value in ModuleVariant array

  • On display evaluation mode, getvariant returns the variant name enclosed in curly braces

    • Which helps to report where the variant is used in environment variable content

    • The variant name and enclosing curly braces are graphically enhanced with va SGR code

Persistency

  • once a module is loaded its defined variants are made persistent in user environment

    • to keep track of how loaded modules were evaluated

    • and enable query commands on these loaded modules without need to reevaluate modulefile

  • variants defined are made persistent in __MODULES_LMVARIANT environment variable

    • following same approach than for __MODULES_LMPREREQ

    • each loaded module with defined variants (default value or specifically set) will expose:

      • these variants value

      • and if the value is the default one and if this default was specifically asked

      • in a record with following syntax:

      • loadedmodule&boolvariantname1|isbooleanvariant|isdefaultvalue&variantname2|value2|value3...|isbooleanvariant|isdefaultvalue

    • for each variant it is recorded if the variant is a Boolean variant

      • which enables to compare value in a Boolean way

      • and to report variant value with the +variant or -variant syntax

    • for each variant it is recorded if the value set corresponds to the variant default value or not

      • such information is useful to save collection when pin version mechanism is disabled

      • on such setup the variant definition should not recorded in collection if this is the default value which is set

    • in addition to know if the variant value is default or not, it is recorded if the default value was:

      • specifically asked (isdefaultvalue=1)

      • or automatically set (isdefaultvalue=2)

      • this information will be useful in the FUTURE to determine if a variant may be automatically swapped by another

    • each loadedmodule record are joined in __MODULES_LMVARIANT separated by : character

  • variant alias are also made persistent in __MODULES_LMVARIANTALTNAME environment variable

    • each loaded module with defined variants (default value or specifically set) which could be aliased will expose their aliases in a record with following syntax

      • loadedmodule&variantname1|aliasname1|-aliasname2&variant2|aliasname3...

    • each loadedmodule record are joined in __MODULES_LMVARIANTALTNAME separated by : character

  • when persistency information is corrupted

    • a missing or non Boolean isdefaultvalue information means variant value is not the default

    • a missing or non Boolean isbooleanvariant information means variant is not a Boolean variant

    • a non-Boolean value set on a Boolean variant means variant equals 0

  • Boolean variants are stored in the form +name or -name

    • which enables to determine this variant is of Boolean type

    • and check against query using different Boolean representations

      • like serial=0, serial=on, serial=false, etc.

  • when the special variant version is defined for a loaded module

    • the value of this variant is part of loaded module identification

    • @versionvalue is appended to the module name, for instance mod@1.2

    • such identification is then recorded in persistency variables to designate loaded module (like LOADEDMODULES, __MODULES_LMPREREQ, __MODULES_LMVARIANT, etc)

    • this way in case a modulefile allows the load of two of its versions in the user environment, it is possible to distinguish these two loaded versions (to unload one of them for instance)

    • with this identification, it is possible to distinguish a traditional module (identified by mod/version) from a module using version variant (identified by mod@version)

    • note that if a modulefile mod/1.2 defines a version variant, it will be identified as mod/1.2@versionvalue

      • so the version variant should not be defined if each version of the module has its own modulefile

      • version variant is useful if a single modulefile is used to instantiate every version of the module

    • FUTURE: when it will be possible to override the shortcut for version variant it will be important to identify version value in loaded module identification string with a designation that is not dependent of the selected shortcut

  • loaded module identification stops at the module name and version variant (if defined)

    • other variants are not considered as part of the identification

    • as it is not foreseen useful to have the same module loaded multiple times with different variant values, unless for version variant

Specifying

  • following Spack spec

  • same grammar used whatever the context

    • command-line or as argument to modulefile command (like command)

  • variants are specified whether

    • as specific words (separated by " ")

    • or as suffix to module name

  • change command specifications which were previously accepting list of modules

    • like module1 module2 module3

    • now these modules could express variants appended to their name

      • like module1@1.8+debug module2~shared module3

    • or these variants could be defined as words next to module name

      • like module1@1.8 +debug module2 shared=false module3

    • as a consequence it denies:

      • use of +, ~ and = in module names

      • and use of - as first character of module names

    • also a command-line argument starting with the - character is not anymore considered as an invalid option

      • it is considered as an element of the module specification (potential negated boolean variant)

      • unless if set prior the sub-command designation

      • or set on sub-commands that do not accept module specification as argument

    • such change requires an option to be enabled to avoid breaking compat

      • this is why to enable variant, the advanced_version_spec option has to be enabled

  • a valued-variant is specified by name=value

    • this kind of variant cannot be directly appended to module name

    • thus it must be specified as a separate word

  • a Boolean variant can be specified with its bare name prefixed by +, - or ~

    • when directly appended to module name string (no space) only + and ~ are recognized

      • - in this case is retained as part of previous name/value

    • the negation prefix - is not supported on the ml command

      • as this - prefix means to unload a module on this command

    • negation prefix plus Boolean variant name should not equal a command-line option short form

      • command-line option takes precedence

      • for instance the -t will always be treated as --terse and not the negation of a t variant

    • beware that the negation prefix ~ when used as a separate word may trigger the tilde resolution of the currently running shell

      • if a username matches a Boolean variant name, using the ~name form on the shell command-line will leads to the resolution of the HOME directory path of user name

    • module name could end with one or more + characters

      • it could be distinguished from a Boolean variant specification as no character should follow these trailing +

    • Boolean variant could also be specified using the name=value form

      • in which case, it should be written as a separate word

      • value could be any syntax recognized as a true or false string

        • false: 0, false, no, or off

        • true: 1, true, yes, or on

        • Any of these values may be abbreviated, and upper-case spellings are also acceptable.

    • when specified Boolean value is translated to its canonical form (0 or 1)

  • variant may be specified with a shortcut if any set (see Variant shortcut)

    • a shortcut is appended to the module designation word or specified as separate word, combined or not with other variant

      • for instance for the @ shortcut: module@versspec+boolvar, module+boolvar@versspec, module +boolvar@versspec

    • even if a shortcut is set, the variant could also be expressed as valued variant name

  • in case variant is specified multiple times

    • on selection context, lastly mentioned (read from left to right) value is retained (it overwrites previous values)

      • a merge all passed values in list is not the methodology retained here

        • same handling way whatever the variant properties

    • like name=value1 name=value2

      • or name=value name=value

      • or name=value1,value2 name=value3

      • or name=value1 name=value2,value3

      • or @vers1 version=vers2

      • or for boolean +name~name

      • or ~name -name

      • or ~name name=value1 name=value2,value3

      • or in case of variant aliases +name~aliastoname

    • at the specification time variant aliases are not known

      • so the full module specification has to be transmitted toward the modulefile to determine what is the value at the most right position

      • for instance name=value1 aliasname=value2 with aliasname being an alias of name

      • specification can just be cleared from the obvious duplicates (same variant name defined multiple times on the line)

    • on search context, all specifications form an AND operation

      • name=value1 name=value2 means find modules defining value1 and value2 as available values for name variant

  • on search context, several values may be set on one variant criterion

    • like name=value1,value2

    • which means find modules defining either value1 or value2 as available value for name variant

    • an error is obtained if performed on selection context

  • on search context, variant criterion may be prefixed by not: string

    • like not:name=value1,value2

    • which means find modules not defining variant name or not providing value1 and value2 as available value

    • an error is obtained if performed on selection context

  • when special characters like ? or * are used in variant name or value

    • they are treated literally, no wildcard meaning is applied

    • like currently done when specifying module version on command-line

      • which leads to errors as no corresponding module is found:

        $ module load loc_dv6/*
ERROR: Unable to locate a modulefile for 'loc_dv6/*'

  • when a variant is specified but it does not correspond to a variant defined in the evaluated modulefile

    • an error is raised at the end of modulefile evaluation

    • need to wait for the end of modulefile evaluation to be sure the variant is defined nowhere in modulefile code

  • special variant version has to be specified with @ shortcut or by its full variant name (version=value)

    • traditional separator character / cannot be used to specify variant version

    • if used, a modulefile named mod/version will be searched and a module not found error will be raised

  • specification may be passed to commands to verify a given module and variant combination is loaded

    • which should be performed without evaluating modulefiles

    • like for is-loaded sub-command:

      • module is-loaded hdf5+parallel

      • or hdf5@1.8 parallel=true

      • or hdf5 -serial

      • or hdf5 serial=0

    • checks rely on the content of the __MODULES_LMVARIANT and __MODULES_LMVARIANTALTNAME variables

      • which store variants set for loaded modules and eventual variant aliases of variant set

    • with this information it is possible to compare query against what is loaded

      • a variant specified on query which is not part of the variables means a different module/variant combination

        • even if variant from query is not valid for module, which cannot be known

    • verification mechanism of a sub-command like is-loaded should be preserved

      • which means a query not mentioning a specific value for a variant should match a loaded module which specify a variant value that differs from this variant default

    • the module identification part in specification may be resolved from a symbolic version or a module alias to an actual modulefile

  • the @loaded specification is translated into the name, version and variant list of corresponding loaded module

    • for instance mod/3.0 foo=val1 is loaded so mod@loaded is translated into mod/3.0 foo=val1

    • in case the @loaded specification is followed by variant specified, those variant specifications are ignored

    • following the above example, mod@loaded foo=val2 is translated into mod/3.0 foo=val1

  • variant can also be specified to designate module on module-tag, module-hide or module-forbid commands

    • tags may only apply when a given variant of a module is loaded

    • it may be useful to decommission a given variant of a module prior others

    • or to forbid the use of a given variant to some users

  • variants specified on search context are taken into account to filter results

    • due to the Extra match search mechanism

    • it concerns the avail, spider, whatis and paths sub-commands

    • only available modules matching the variant specification will be retained

    • for instance avail mod foo=var returns all versions of mod module where a variant foo is defined with var as a possible value

    • exception is made for is-avail and path search sub-command

      • as they are more module selection commands rather an available module search commands

      • it does not take info account variants defined within module specification

    • these search commands (except is-avail and path) allow module specification without module name and version

      • only variant name and value specified (e.g., module avail foo=var)

      • only modules declaring such variant with such version will be retained in result

  • variants specified on loaded module list context are taken into account to filter results

    • concerns list sub-command

    • not related to extra match search as comparison is made against loaded modules not content of available modules

    • only loaded modules matching the variant specification will be retained

    • module specification without module name and version is allowed on this context

      • only variant name and value specified (e.g., module list foo=var)

      • only loaded modules declaring such variant set with this version will be retained in result

  • variant cannot be specified over the module-alias, module-version, module-virtual commands

  • variant passed as argument to module-info alias, version or symbols will not match anything

  • module-info loaded only accepts modulefile as argument, not variant specification

    • it also only return loaded module name and version, without the variant set

Variant in requirement specification

  • prereq/conflict specification

    • could consolidate different variation set for same module on the same prereq/conflict list

      • to indicate a preferred order (if available)

      • like prereq netcdf -debug netcdf +debug

      • or prereq netcdf var=val1 netcdf var=val2 netcdf

    • in last example, could not currently consolidate definition into prereq netcdf var=val1,val2,default

      • in case of requirement alternatives, all possibilities should be written as independent

        • like prereq module@vers variant=val1 module@vers variant=val2

      • to clearly indicate a priority order to apply when for instance attempting to load these requirements

      • FUTURE: a value selection mechanism, like when selecting a module version among others, would help here

  • prereq/conflict persistency

    • __MODULES_LMPREREQ and __MODULES_LMCONFLICT content should reflect specified variant constraint

    • it could be expressed in these variables as it is specified over the prereq/conflict modulefile commands

      • for instance __MODULES_LMPREREQ=hdf5/1.10&mpi@1.8 +shared variant=name&netcdf

      • use of characters `` , ``+, ~, , is not an issue

        • as delimiters characters in these environment variables are :, & and |

Variant shortcut

  • shortcuts can be set to abbreviate variant names and simplify their specification

    • a shortcut abbreviates name= into a unique character

    • when using shortcut, variant value is specified as <shortcut>value

    • for instance, if the % is set as the shortcut for a toolchain variant, value foss21a is specified as %foss21a

  • shortcut can be set through the variant_shortcut configuration option

    • this option holds a colon separated list of shortcut definitions

    • each definition have the following form: variantname=shortcut_character

    • for instance: toolchain=%:foo=^

  • shortcut must be:

    • a single character

    • excluding characters already used for other concerns or in module names or version specifications (-, +, ~, /, @, =, :, ,, [a-zA-Z0-9])

    • when set through config sub-command or --with-variant-shortcut installation option: an error is raised when a shortcut is badly specified

    • if a badly specified shortcut ends up in modulecmd configuration, it is purely ignored

  • shortcut does not apply to Boolean variants

    • as shortcuts are intended to be a prefix, they do not add benefit compared to -, + or ~ Boolean prefixes

    • however a shortcut could be defined on a boolean variant (e.g., %true or %0)

  • by default, when advanced_version_spec is enabled, the @ character is set as a shortcut for the version variant

    • this shortcut is not referred in MODULES_VARIANT_SHORTCUT thus it cannot be unset

    • FUTURE: superseding of this @ shortcut in MODULES_VARIANT_SHORTCUT may be introduced in the future

      • but currently entries in MODULES_VARIANT_SHORTCUT for version variant are ignored

  • variant shortcuts could be used on the command-line or within modulefiles even if it is not recommended to use them in the latter case

    • as if user updates the variant_shortcut configuration option, it will broke underlying modulefiles using a de-configured shortcuts

  • module designation in collection does not use variant shortcuts

    • when shortcut configuration is changed it should not impact collection definition

Reporting

  • Defined variants are reported on list sub-command results

    • Reported joined to modulefile name, within curly braces

    • Each variant definition separated by a colon

    • For instance module/version{vr=val:+boolvr}

  • Variants are reported by default on list sub-command

    • as they qualify what exact flavor of the module is loaded

    • so it enables users to really catch what has been loaded exactly

    • They can be removed from output using the output configuration mechanism

  • Variants defined by modulefiles may be reported on avail sub-command

    • Not by default, if variant value is added to avail_output or avail_terse_output

    • Or if variantifspec value is added to avail_output or avail_terse_output and a variant is specified in search query

    • It requires an Extra match search

    • Which in turns requires more processing time as modulefiles are evaluated

    • Having cache file available helps to reduce the I/O load caused by such process

  • Variants defined by modulefiles may be reported on spider sub-command

    • Not by default, if variant value is added to spider_output or spider_terse_output

    • Or if variantifspec value is added to spider_output or spider_terse_output and a variant is specified in search query

    • It requires an Extra match search

    • Which in turns requires more processing time as modulefiles are evaluated

    • Having cache file available helps to reduce the I/O load caused by such process

  • A specific color key is defined to highlight variants: va

  • Variant report depends on variant type

    • valued variant: variant=value

    • boolean variant: +variant or -variant

    • valued variant with shortcut set: <shortcut>value (for instance if % is a defined shortcut: %value)

    • in case a shortcut is defined over a Boolean variant, Boolean report prevails over shortcut

  • On avail and spider, all possible values of variant are reported

    • Values are separated from each other with , character

    • Boolean variant are reported as valued variant with on and off values reported

    • Example: mod/1.0{variant=val1,val2,boolvariant=on,off:%val1,val2}

    • A * value is reported in possible value list for free-value variant

      • To indicate all values are possible

      • Loaded variant value and default variant value are also reported if any

  • Variant aliases are not reported

    • to keep output tight

  • Special variant version is reported right after the module name

    • with @ shortcut

    • using variant highlight color if any

    • for instance: module@version{othervariant=value}

  • Variants are reported on the Loading, Unloading and Switching informational messages

    • As they qualify what exact flavor of the module is loaded, unloaded or switched

    • They are put along the module name and version designation

    • They are reported using their short form, like for list sub-command to keep output tight

    • Separated between each other by space character

    • Each variant specification is enclosed between single quotes if it contains a space character

    • The whole variant specification is enclosed between curly braces ({}) and separated from module name version by space character

      • Easier this way to distinguish variant specification from module name version on informational messages where multiple module designation are reported

    • These designations have to be recorded

      • prior module evaluation and based on variant specification (passed as argument) in order to be ready for any report prior the end of modulefile evaluation (in case of error for instance)

      • then refined after module evaluation with the variant accurately set in loaded environment

  • Variants are also reported along module name and version in the auto_handling informational messages

Recording collection

  • The variant specification set for loaded modules has to be recorded when saving it in a collection

    • Restoring such environment should apply the variant specified on the module to load

    • Lines like the following one could now be found in collection: module load hdf5@1.10 +parallel

    • Important to distinguish multiple modules specified on a single line from a module specified with variant defined

  • In case the collection_pin_version configuration option is disabled variant set to their default value should not be recorded in collection

    • Following the same scheme than for module version

    • When saving collection, the is-default-value information stored in persistency variable (__MODULES_LMVARIANT) helps to know whether the value set to a variant is or not the default one

    • The save mechanism will rely on this information to exclude or not the variant specification in the generated collection output

    • Within this is-default-value hint, the was-this-default-specified-by-user sub-information is not preserved when saving collection

      • if collection is not pinned, default value is excluded whether it was specifically set by user or not

Comparing module specification including variants

  • When a module specification has to be compared on a non-loaded or non-loading modules context

    • If this specification contains variants

      • Applies especially to the search commands taking a module specification as argument

      • Specified variants are taken into account through Extra match search mechanism

        • Once matching name and version are found

        • A scan evaluation is made on them

        • Only those declaring specified variants and values are retained in results

      • It applies to avail, spider, whatis and paths sub-commands

      • Exception is made for is-avail and path sub-commands

        • do not trigger extra match search process

        • even if variant specified in module specification argument

    • If this specification does not contain variant

      • There is no variant set on non-loaded or non-loading modules we are comparing to

      • Match is performed over module name and version

  • When a module specification has to be compared against loaded or loading modules

    • If this specification contains variants

      • It should be matched against the variants set on loaded or loading modules

      • No variant set for loaded or loading module means no match

    • If this specification does not contain variant

      • Loaded or loading modules match is only made on their name

      • No comparison occurs over the variants set on loaded or loading modules

  • To compare variant set on loaded or loading modules

    • A ismodlo flag is added to the modEq procedure

    • With this flag it is known if modEq operates on a:

      • non-loaded or non-loading context (0),

      • loading context (1)

      • loaded context (2)

    • Variants set on loading or loaded modules will be fetched in case ismodlo is equal to 1 or 2

    • Loaded or loading modules are passed to modEq by their name/version designation

      • No change here

      • And no change required in all procedures that perform such comparison

    • Alternative names should also be tested like main module name with variants set

      • As the alternative names currently apply to module name and version only

      • Name and version could be compared on their own

      • Then variants could be compared

      • Which means all applying names are compared then if a match is found variants are compared

  • Specific comparison occurs when restoring collection

    • When a collection is restored an unspecified variant for a given module to load means this variant has to be set at its default value

    • So when comparing against loaded environment, an unspecified variant in collection only matches if variant set on loaded environment is the default one

    • Collection procedures now rely on the modEq procedure

      • ismodlo flag is set to 3 to indicate a collection context

      • This collection context leads to also compare simplified module names (in addition to alternative names)

      • And to treat an unspecified variant on tested pattern as a default variant value

  • There is no need to compare variants on following procedures

    • getLoadedWithClosestName

      • Find a loaded module whose name and version is the closest to passed specification

      • Variant specified on loaded modules or on specification is ignored here

    • modStartNb

      • Only used to compare module name and versions

      • Used by getLoadedWithClosestName and isModuleHidden

    • modEqStatic

      • Always used over non-loaded or non-loading context

      • Used by findModules and getModules

    • getEqArrayKey

    • cmdModuleSearch

    • cmdModuleSwitch

    • getModules

      • Unless if module specification contains a variant definition, which triggers an extra match search process

      • Used by cmdModuleAvail, getPathToModule, isStickinessReloading, cmdModulePaths, cmdModuleSearch and cmdModuleAliases

    • getPathToModule

      • Which calls to getModules

      • Used by cmdModulePath, cmdModuleSearch, cmdModuleSwitch, cmdModuleLoad, cmdModuleUnload, cmdModuleTest, cmdModuleHelp, getAllModuleResolvedName, is-avail, getSimplifiedLoadedModuleList and cmdModuleDisplay

    • getAllModuleResolvedName

  • Variant comparison is needed on following procedures

    • setModuleDependency

    • getUnmetDependentLoadedModuleList

    • getDirectDependentList

    • cmdModuleLoad

    • cmdModuleList

    • conflict

    • getLoadedMatchingName

    • doesModuleConflict

    • getModuleTag

      • Useful when a tag is defined only when a specific variant is set

    • collectModuleTag

      • Useful when a tag is defined only when a specific variant is set

    • getModuleHidingLevel

      • Useful when a module with a specific variant value set is defined hidden

      • FUTURE: if variants are reported on avail, hiding a variant specific value would have an effect on this sub-command

    • isModuleHidden

      • Useful when a module with a specific variant value set is defined hidden

      • FUTURE: if variants are reported on avail, hiding a variant specific value would have an effect on this sub-command

Specific impact

  • When loading a module with variant, if this module is already loaded but with a different variant set an error is raised

  • Tags applying specifically on variants do not appear over avail or spider results

    • Even when variants are processed on avail mode

    • However if a module is loaded and tags apply to the variant selected, these tags will appear on the module designation within avail result

  • Forbidding a specific variant of a module will not exclude it from search results

    • The module will still be reported on avail, spider or evaluated on whatis

    • Even if this specific variant is searched

    • As search sub-commands report all possible variants of available modules

  • Hiding a specific variant of a module will not hide the module from search results

    • Even if this specific variant is searched

    • As search sub-commands report all possible variants of available modules

  • Sticky modules can be swapped by another sticky modules if the stickiness applies to the generic module name

    • It stays true even if module has variants

    • Which means if stickiness designate module version or several versions, sticky module cannot be changed once loaded

    • Variant change cannot either occur

    • FUTURE: this may be revised to allow variant change if needs arise

  • Stickiness can be defined over specific variant value, like any other tag

    • In case stickiness applies to the default value of a variant

    • When swapping sticky modules by another still matching the sticky rule

    • The variant with default value has to be explicitly specified for the swap to be allowed

      • As it cannot be guessed prior loading module that the default value of the variant will match the sticky rule

      • It applies to both sticky module swap context: restore and switch

  • On module-info tags, currently defined tags need to get fetched when called

    • As variant specified prior module-info tags call may change the list of tags that apply

    • Especially when a variant inherits its default value as it is not specified when loading module

  • module-info specified returns module name version and variants specified to designate the currently evaluating module

  • module-info name only returns module name and version, variants are not part of the result

    • Variants can be fetched in the ModuleVariant array within evaluation context

Corner cases

  • When loading a variant which is an optional requirement for an already loaded module

    • If this optional requirement is loaded without specifying its variant value to get the default variant value

    • Currently it is not seen as an optional requirement at the load time

    • Thus dependent module is not reloaded

    • FUTURE: the deps evaluation mode that will be triggered prior module load may fix this current limitation