"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/source/design/lmod-tcl-modulefile-compat.rst" between
modules-5.1.1.tar.bz2 and modules-5.2.0.tar.bz2

About: The Environment Modules package provides for the dynamic modification of a user’s environment via modulefiles.

lmod-tcl-modulefile-compat.rst  (modules-5.1.1.tar.bz2):lmod-tcl-modulefile-compat.rst  (modules-5.2.0.tar.bz2)
.. _lmod-tcl-modulefile-compat: .. _lmod-tcl-modulefile-compat:
Lmod Tcl modulefile compatibility Lmod Tcl modulefile compatibility
================================= =================================
- Goal is to be able to evaluate with :command:`modulecmd.tcl` a Tcl - Goal is to be able to evaluate with :command:`modulecmd.tcl` a Tcl
modulefile generated for Lmod modulefile generated for Lmod
- No evaluation error - No evaluation error
- Be as close as possible to the behavior of Lmod - Be as close as possible to the behavior of Lmod
- As of Modules v5.0, the following Tcl modulefile command of Lmod are not - As of Modules v5.0, the following Tcl modulefile command of Lmod are not
supported: supported:
- ``add-property`` - ``add-property``
- ``remove-property`` - ``remove-property``
- ``extensions`` - ``extensions``
- ``depends-on`` - ``depends-on``
- ``prereq-any`` - ``prereq-any``
- ``always-load`` - ``always-load``
- ``module load-any`` - ``module load-any``
- ``pushenv`` - ``pushenv``
- ``require-fullname`` - ``require-fullname``
- ``family`` - ``family``
``add-property``/``remove-property`` ``add-property``/``remove-property``
------------------------------------ ------------------------------------
- Property mechanism of Lmod does not completely fit into Modules tag - Property mechanism of Lmod does not completely fit into Modules tag
mechanism: mechanism:
- Property are first defined in a global RC file - Property are first defined in a global RC file
- Then associated to a given modulefile with ``add-property`` command - Then associated to a given modulefile with ``add-property`` command
- Could be unset with ``remove-property`` - Could be unset with ``remove-property``
- Defined as a key-value - Defined as a key-value
- These commands will be first implemented as a no-operation command (``nop``) - These commands will be first implemented as a no-operation command (``nop``)
- No error raised if used - No error raised if used
- And no warning message to avoid polluting output - And no warning message to avoid polluting output
- These commands are intended for use only within modulefile evaluation - These commands are intended for use only within modulefile evaluation
context (not within modulerc) context (not within modulerc)
- *FUTURE*: it could be interesting to map some properties on tags like the - *FUTURE*: it could be interesting to map some properties on tags like the
``lmod:sticky`` property which corresponds to the ``sticky`` tag ``lmod:sticky`` property which corresponds to the ``sticky`` tag
``extensions`` ``extensions``
-------------- --------------
- Extension mechanism is an additional information added on ``avail`` and - Extension mechanism is an additional information added on ``avail`` and
``spider`` sub-command output ``spider`` sub-command output
- Requires to evaluate modulefile on ``avail`` processing - Requires to evaluate modulefile on ``avail`` processing
- Not used to load the modulefile declaring them when an extension name is - Not used to load the modulefile declaring them when an extension name is
passed to ``load`` sub-command or ``depends-on`` modulefile command passed to ``load`` sub-command or ``depends-on`` modulefile command
- This command will be first implemented as a no-operation command (``nop``) - This command will be first implemented as a no-operation command (``nop``)
- No error raised if used - No error raised if used
- And no warning message to avoid polluting output - And no warning message to avoid polluting output
- This command is intended for use only within modulefile evaluation context - This command is intended for use only within modulefile evaluation context
(not within modulerc) (not within modulerc)
- *FUTURE*: may be interesting to improve the concept by making the extension - *FUTURE*: may be interesting to improve the concept by making the extension
names an alias on the modulefile declaring them names an alias on the modulefile declaring them
- Will automatically achieve dependency consistency this way - Will automatically achieve dependency consistency this way
- Could resolve dependencies based on extension names if modulefile is - Could resolve dependencies based on extension names if modulefile is
evaluated during an ``avail`` evaluated during an ``avail``
``prereq-any`` ``prereq-any``
-------------- --------------
- This command is an alias over ``prereq`` command - This command is an alias over ``prereq`` command
- In Lmod, ``prereq`` acts as a *prereq-all* - In Lmod, ``prereq`` acts as a *prereq-all*
- Whereas on Modules ``prereq`` acts already as a *prereq-any* - Whereas on Modules ``prereq`` acts already as a *prereq-any*
- This command is intended for use only within modulefile evaluation context - This command is intended for use only within modulefile evaluation context
(not within modulerc) (not within modulerc)
``require-fullname`` ``require-fullname``
-------------------- --------------------
- Raise an error if modulefile has been designed with implicit or explicit - Raise an error if modulefile has been designed with implicit or explicit
default name default name
- This error aborts modulefile evaluation - This error aborts modulefile evaluation
- Occurs for instance if ``foo/1.0`` is loaded with ``foo`` or - Occurs for instance if ``foo/1.0`` is loaded with ``foo`` or
``foo/default`` name ``foo/default`` name
- Which means ``require-fullname`` has precedence over explicitly set - Which means ``require-fullname`` has precedence over explicitly set
default version default version
- If an alias or a symbolic version (other than ``default``) point to the - If an alias or a symbolic version (other than ``default``) point to the
modulefile, no error occurs if modulefile is designated using these modulefile, no error occurs if modulefile is designated using these
alternative names. alternative names.
- ``require-fullname`` is implemented to only apply on *load* evaluation mode - ``require-fullname`` is implemented to only apply on *load* evaluation mode
- On Lmod, it applies on *load*, *unload*, and *display* modes - On Lmod, it applies on *load*, *unload*, and *display* modes
- It seems important not to apply the constraint on *unload* and *display* - It seems important not to apply the constraint on *unload* and *display*
modes to ease user's experience modes to ease user's experience
- This command is intended for use only within modulefile evaluation context - This command is intended for use only within modulefile evaluation context
(not within modulerc) (not within modulerc)
``depends-on`` ``depends-on``
-------------- --------------
- Auto load one or more modules said as dependencies when modulefile is - Auto load one or more modules said as dependencies when modulefile is
evaluated in *load* mode evaluated in *load* mode
- Corresponds to the *Requirement Load* module auto handling mechanism. - Corresponds to the *Requirement Load* module auto handling mechanism.
- Semantically this command corresponds to a requirement declaration. - Semantically this command corresponds to a requirement declaration.
- Make it an alias over :mfcmd:`prereq` but with each argument set as a - Make it an alias over :mfcmd:`prereq` but with each argument set as a
*prereq*all* not a *prereq-any*. *prereq*all* not a *prereq-any*.
- If :mconfig:`auto_handling` option is disabled, requirement will not be - If :mconfig:`auto_handling` option is disabled, requirement will not be
loaded and an error is raised. This will be different than Lmod as loaded and an error is raised. This will be different than Lmod as
with Modules the modulefile commands defines the semantic (*this is with Modules the modulefile commands defines the semantic (*this is
a dependency*) then the automation is defined by the module command a dependency*) then the automation is defined by the module command
configuration, not by the modulefile like done in Lmod. configuration, not by the modulefile like done in Lmod.
- Auto unload the dependency modules when modulefile is unloaded if no other - Auto unload the dependency modules when modulefile is unloaded if no other
loaded module depends on them loaded module depends on them
- Corresponds to the *Useless Requirement Unload* module auto handling - Corresponds to the *Useless Requirement Unload* module auto handling
mechanism mechanism
- Like for *load* evaluation, automation is configured at the module - Like for *load* evaluation, automation is configured at the module
command level, not by individual modulefiles command level, not by individual modulefiles
- This command is intended for use only within modulefile evaluation context - This command is intended for use only within modulefile evaluation context
(not within modulerc) (not within modulerc)
``always-load`` ``always-load``
--------------- ---------------
- Auto load on or more modules said as dependencies when modulefile is - Auto load on or more modules said as dependencies when modulefile is
evaluated in *load* mode evaluated in *load* mode
- Semantically this command corresponds to a requirement declaration. - Semantically this command corresponds to a requirement declaration.
- Make it an alias over :mfcmd:`module load<module>` - Make it an alias over :mfcmd:`module load<module>`
- Add ``keep-loaded`` tag to the modules loaded this way - Add ``keep-loaded`` tag to the modules loaded this way
- When several modules are specified, it acts as an *AND* operation, which - When several modules are specified, it acts as an *AND* operation, which
means all specified modules are required means all specified modules are required
- When modulefile is unloaded, the *always-load* modules are not automatically - When modulefile is unloaded, the *always-load* modules are not automatically
unloaded as they own the ``keep-loaded`` tag unloaded as they own the ``keep-loaded`` tag
- This command is intended for use only within modulefile evaluation context - This command is intended for use only within modulefile evaluation context
(not within modulerc) (not within modulerc)
``module load-any`` ``module load-any``
------------------- -------------------
- Auto load first valid module in a list when modulefile is evaluated in - Auto load first valid module in a list when modulefile is evaluated in
*load* mode *load* mode
- Semantically this command corresponds to a requirement declaration. - Semantically this command corresponds to a requirement declaration.
- Acting as an *OR* operation - Acting as an *OR* operation
- Evaluation stops after first module in list loaded - Evaluation stops after first module in list loaded
- Whether called from a modulefile evaluation context or from top - Whether called from a modulefile evaluation context or from top
evaluation context evaluation context
- Different than Lmod that apply the :subcmd:`load` sub-command - Different than Lmod that apply the :subcmd:`load` sub-command
behavior when called from top evaluation context and does not stop behavior when called from top evaluation context and does not stop
after first modulefile loaded after first modulefile loaded
- If the evaluation of first module to load in list ends in error - If the evaluation of first module to load in list ends in error
- When called from a modulefile evaluation context - When called from a modulefile evaluation context
- Error is silenced - Error is silenced
- Next module in list is tried - Next module in list is tried
- It behaves this way like a :mfcmd:`prereq` command with - It behaves this way like a :mfcmd:`prereq` command with
auto_handling mode enabled auto_handling mode enabled
- Proceed this way whatever the auto_handling state - Proceed this way whatever the auto_handling state
- Different than Lmod that aborts modulefile evaluation - Different than Lmod that aborts modulefile evaluation
- Otherwise when called from top evaluation context - Otherwise when called from top evaluation context
- Error message is reported - Error message is reported
- Next module in list is tried - Next module in list is tried
- Different than Lmod that aborts processing - Different than Lmod that aborts processing
- If first modules to load are unknown - If first modules to load are unknown
- No message reported - No message reported
- ``load-any`` continues until finding a module in the specified list - ``load-any`` continues until finding a module in the specified list
- If a module in the list is already loaded - If a module in the list is already loaded
- When called from a modulefile evaluation context - When called from a modulefile evaluation context
- ``load-any`` is not performed as requirement is considered - ``load-any`` is not performed as requirement is considered
already satisfied already satisfied
- Better cope this way with the expressed requirement - Better cope this way with the expressed requirement
- It behaves this way like a :mfcmd:`prereq` command - It behaves this way like a :mfcmd:`prereq` command
- Proceed this way whatever the auto_handling state - Proceed this way whatever the auto_handling state
- Different behavior than Lmod that still proceed to load the - Different behavior than Lmod that still proceed to load the
module in the list from the left to the right until loading one module in the list from the left to the right until loading one
or finding one loaded or finding one loaded
- Otherwise when called from top evaluation context - Otherwise when called from top evaluation context
- An attempt to load first module in list is still issued - An attempt to load first module in list is still issued
- And pursued from left to right until loading one module or - And pursued from left to right until loading one module or
finding one loaded finding one loaded
- ``load-any`` acts similarly to ``try-load`` but with an *OR* operation - ``load-any`` acts similarly to ``try-load`` but with an *OR* operation
behavior instead of an *AND* operation behavior instead of an *AND* operation
- An error is obtained if none of the listed modules can be loaded if - An error is obtained if none of the listed modules can be loaded if
none of their load attempt generated an error message none of their load attempt generated an error message
- If no argument is provided an error is obtained, like done for - If no argument is provided an error is obtained, like done for
``try-load`` ``try-load``
- When modulefile is unloaded, an attempt to unload all specified module is - When modulefile is unloaded, an attempt to unload all specified module is
made made
- Correspond to the behavior of a ``module unload`` - Correspond to the behavior of a ``module unload``
- Modules which are still depended by other loaded modules will not be - Modules which are still depended by other loaded modules will not be
unloaded unloaded
- This command is intended for use only within modulefile evaluation context - This command is intended for use only within modulefile evaluation context
(not within modulerc) (not within modulerc)
``module try-load``
-------------------
- ``try-load`` sub-command and modulefile command has been introduced in
Modules version 4.8.
- ``try-load`` modulefile command acts as an individual ``prereq`` for each
modulefile specified.
- Each modulefile specified are considered optional requirement, as no error
is raised if they cannot be loaded.
- An update is made on version 5.2 to record each modulefile specified on
``try-load`` as optional requirement even if their load attempt did not
succeed.
- With this change, if the optional requirement is loaded later on, the
module declaring the ``try-load`` command will be automatically reload
(if ``auto_handling`` is enabled) to take the new availability of its
optional requirement into account.
``family`` ``family``
---------- ----------
- Defines membership in family *name* and ensures that only one member of a - Defines membership in family *name* and ensures that only one member of a
given family is currently loaded. given family is currently loaded.
- Semantically this command corresponds to the definition of both: - Semantically this command corresponds to the definition of both:
- a conflict on family *name* - a conflict on family *name*
- a module alias *name* over currently loading module - a module alias *name* over currently loading module
- Also defines the :envvar:`MODULES_FAMILY_\<NAME\>` environment variable set - Also defines the :envvar:`MODULES_FAMILY_\<NAME\>` environment variable set
to the currently loading module name minus its version number. to the currently loading module name minus its version number.
- As family *name* is used in environment variable name, it requires that - As family *name* is used in environment variable name, it requires that
*name* should only use characters that are accepted there *name* should only use characters that are accepted there
- Accepted characters for family *name* are *[a-zA-Z0-9_]* - Accepted characters for family *name* are *[a-zA-Z0-9_]*
- An error is generated in case other kind of characters are found in - An error is generated in case other kind of characters are found in
specified family *name* specified family *name*
- The :envvar:`LMOD_FAMILY_\<NAME\>` environment variable is also set in - The :envvar:`LMOD_FAMILY_\<NAME\>` environment variable is also set in
addition to :envvar:`MODULES_FAMILY_\<NAME\>` and set to the same value. addition to :envvar:`MODULES_FAMILY_\<NAME\>` and set to the same value.
This way existing scripts or modulefiles relying on this variable do not This way existing scripts or modulefiles relying on this variable do not
need to be changed to be compatible with Modules. need to be changed to be compatible with Modules.
- When modulefile is unloaded, the ``MODULES_FAMILY_<NAME>`` and - When modulefile is unloaded, the ``MODULES_FAMILY_<NAME>`` and
``LMOD_FAMILY_<NAME>`` environment variables are unset ``LMOD_FAMILY_<NAME>`` environment variables are unset
- This command is intended for use only within modulefile evaluation context - This command is intended for use only within modulefile evaluation context
skipping to change at line 269 skipping to change at line 289
``pushenv`` ``pushenv``
----------- -----------
- Sets an environment variable with a value specified as argument but saves - Sets an environment variable with a value specified as argument but saves
the previous value set to restore it when modulefile is unloaded. the previous value set to restore it when modulefile is unloaded.
- Use a :envvar:`__MODULES_PUSHENV_\<VAR\>` environment variable as a stack to - Use a :envvar:`__MODULES_PUSHENV_\<VAR\>` environment variable as a stack to
record the previous values of environment variable ``<VAR>``. record the previous values of environment variable ``<VAR>``.
- Each element in this Modules-specific variable is the combination of the - Each element in this Modules-specific variable is the combination of the
currently evaluating modulename and pushed value. currently evaluating modulename and pushed value.
- Combination joined with the ampersand character - Combination joined with the ampersand character
- Each element in variable separated by colon character - Each element in variable separated by colon character
- When unloading, the value set by this module is removed not the value on - When unloading, the value set by this module is removed not the value on
top of the list. top of the list.
- Different than Lmod that restores the value on top of the stack even if - Different than Lmod that restores the value on top of the stack even if
unloading module were not the one defining the top value currently in unloading module were not the one defining the top value currently in
use. use.
- When saving value set before any module - When saving value set before any module
- An empty module name is used to push to the stack. - An empty module name is used to push to the stack.
- When restoring this initial value, initial entry in stack is also - When restoring this initial value, initial entry in stack is also
cleared (as no other module unload will unset it). cleared (as no other module unload will unset it).
- It is not expected that for the same environment variable, :mfcmd:`pushenv` - It is not expected that for the same environment variable, :mfcmd:`pushenv`
is mixed with: is mixed with:
- ``setenv``, ``unsetenv`` - ``setenv``, ``unsetenv``
- ``append-path``, ``prepend-path``, ``remove-path`` - ``append-path``, ``prepend-path``, ``remove-path``
- These other modulefile commands clear the pushenv stack environment - These other modulefile commands clear the pushenv stack environment
variable (like ``setenv``/``unsetenv`` clear the reference counter variable (like ``setenv``/``unsetenv`` clear the reference counter
environment variable of the ``*-path`` commands) environment variable of the ``*-path`` commands)
- It is not expected that :mfcmd:`pushenv` is called multiple times for the - It is not expected that :mfcmd:`pushenv` is called multiple times for the
same environment variable in the same modulefile same environment variable in the same modulefile
- Inconsistent results may be obtained if environment variable value is - Inconsistent results may be obtained if environment variable value is
used in modulefile to set other variables. used in modulefile to set other variables.
- Especially that unload evaluation of modulefile will not process the - Especially that unload evaluation of modulefile will not process the
``pushenv`` commands in the reverse order but in the script order. ``pushenv`` commands in the reverse order but in the script order.
- When checked during modulefile evaluation, lastly defined value remains - When checked during modulefile evaluation, lastly defined value remains
- However the operation is consistent at the end of modulefile evaluation, - However the operation is consistent at the end of modulefile evaluation,
as all values are withdrawn from stack and a value defined somewhere as all values are withdrawn from stack and a value defined somewhere
else is restored. else is restored.
- pushenv stack environment variable correctly handles multiple entries - pushenv stack environment variable correctly handles multiple entries
coming from same modulefile, even multiple identical values. coming from same modulefile, even multiple identical values.
- For Lua modulefiles, Lmod handles a specific ``false`` value which clears - For Lua modulefiles, Lmod handles a specific ``false`` value which clears
environment variable environment variable
- Lmod does not implement this for Tcl modulefile - Lmod does not implement this for Tcl modulefile
- Maybe because ``false`` cannot be distinguished from any other value - Maybe because ``false`` cannot be distinguished from any other value
- So this specific behavior is also not supported on Modules - So this specific behavior is also not supported on Modules
- This command is intended for use only within modulefile evaluation context - This command is intended for use only within modulefile evaluation context
(not within modulerc) (not within modulerc)
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent:
 End of changes. 43 change blocks. 
141 lines changed or deleted 161 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)