Introduce linked_envvars configuration option

.hunspell.en.dic

@@ -1338,3 +1338,4 @@ ts
 OSX
 BAWT
 HTTPS
+mirrorEnvVarChange

INSTALL.rst

@@ -1721,7 +1721,9 @@ installation.
 | :mconfig:`implicit_requirement`   | ``1``                                        | :instopt:`--enable-implicit-requirement`,    |              |           |
 |                                   |                                              | :envvar:`MODULES_IMPLICIT_REQUIREMENT`       |              |           |
 +-----------------------------------+----------------------------------------------+----------------------------------------------+--------------+-----------+
-| :mconfig:`info_extension`         | ``0``                                        | :envvar:`MODULES_INFO_EXTENSION`,            |              |           |
+| :mconfig:`info_extension`         | ``0``                                        | :envvar:`MODULES_INFO_EXTENSION`             |              |           |
++-----------------------------------+----------------------------------------------+----------------------------------------------+--------------+-----------+
+| :mconfig:`linked_envvars`         | *Empty by default*                           | :envvar:`MODULES_LINKED_ENVVARS`             |              |           |
 +-----------------------------------+----------------------------------------------+----------------------------------------------+--------------+-----------+
 | :mconfig:`list_output`            | ``header:idx:variant:sym:tag:key``           | :instopt:`--with-list-output`,               |              |           |
 |                                   |                                              | :envvar:`MODULES_LIST_OUTPUT`,               |              |           |

MIGRATING.rst

@@ -93,6 +93,48 @@ the configuration option is changed from its default value using the
 environment variable is defined accordingly. See
 :envvar:`MODULES_PATH_ENTRY_REORDER` for details.
 
+.. _Linked environment variables:
+
+Linked environment variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A new configuration option, :mconfig:`linked_envvars`, can be used to
+automatically mirror environment variable changes onto other environment
+variables.
+
+When a modulefile modifies an environment variable using commands such as
+:mfcmd:`setenv`, :mfcmd:`unsetenv`, :mfcmd:`prepend-path`,
+:mfcmd:`append-path`, :mfcmd:`remove-path` or :mfcmd:`pushenv`, the same
+operation is also applied to all variables linked through the
+:mconfig:`linked_envvars` configuration option.
+
+For example, with the following configuration:
+
+.. parsed-literal::
+
+    :ps:`$` module config linked_envvars "CPATH&INCLUDE_PATH"
+
+loading a module that prepends a directory to ``CPATH``:
+
+.. parsed-literal::
+
+    :sgrcm:`prepend-path` CPATH /opt/pkg/include
+
+will also prepend the same directory to ``INCLUDE_PATH``.
+
+Links are directional. In the previous example, changes made to ``CPATH`` are
+also applied to ``INCLUDE_PATH``, but changes made directly to
+``INCLUDE_PATH`` are not applied back to ``CPATH`` unless an explicit reverse
+link is configured.
+
+When enabling this feature, note that existing values are not synchronized
+when the link is established. Only subsequent modifications performed through
+modulefile environment variable commands are propagated to linked variables.
+
+The output of ``module display`` also includes the environment variable
+changes applied to linked environment variables, making these propagated
+updates visible before a module is loaded.
+
 
 v5.6
 ----

NEWS.rst

@@ -84,12 +84,18 @@ Modules 5.7.0 (not yet released)
   :subcmd:`spider` sub-commands rather the last part of this via information.
   JSON output is updated to report the ``via`` key as an array rather as a
   string. (fix issue #586)
-* Introduce the :mconfig:`info_extension` configure option to consider that
-  module extensions have a pure informational purpose and no module alias is
-  associated to them. Extensions defined with :mfcmd:`provide` modulefile
+* Introduce the :mconfig:`info_extension` configuration option to consider
+  that module extensions have a pure informational purpose and no module alias
+  is associated to them. Extensions defined with :mfcmd:`provide` modulefile
   command are not affected by this mechanism. When :mconfig:`info_extension`
   is changed with :subcmd:`config` sub-command, it sets the
   :envvar:`MODULES_INFO_EXTENSION` environment variable. (fix issue #585)
+* Doc: add :ref:`linked-envvars` design notes.
+* Add the :mconfig:`linked_envvars` configuration option to apply the same
+  value update commands to all linked environment variables. When
+  :mconfig:`linked_envvars` is changed with :subcmd:`config` sub-command, it
+  sets the :envvar:`MODULES_LINKED_ENVVARS` environment variable. (fix issue
+  #609)
 
 
 .. _5.6 release notes:

doc/source/changes.rst

@@ -1075,8 +1075,9 @@ The following environment variables appeared on Modules 5.
 +------------+-----------------------------------------------------------------+
 | 5.7        | :envvar:`MODULES_PATH_ENTRY_REORDER`,                           |
 |            | :envvar:`MODULES_PAGINATE`,                                     |
-|            | :envvar:`MODULES_NON_EXPORTABLE_TAGS`                           |
-|            | :envvar:`MODULES_INFO_EXTENSION`                                |
+|            | :envvar:`MODULES_NON_EXPORTABLE_TAGS`,                          |
+|            | :envvar:`MODULES_INFO_EXTENSION`,                               |
+|            | :envvar:`MODULES_LINKED_ENVVARS`                                |
 +------------+-----------------------------------------------------------------+
 
 Modules Specific Tcl Commands
@@ -1290,7 +1291,8 @@ The following Modules configuration option has been introduced on Modules 5.
 |            | :mconfig:`spider_indepth`, :mconfig:`require_via`               |
 +------------+-----------------------------------------------------------------+
 | 5.7        | :mconfig:`path_entry_reorder`, :mconfig:`paginate`,             |
-|            | :mconfig:`non_exportable_tags`, :mconfig:`info_extension`       |
+|            | :mconfig:`non_exportable_tags`, :mconfig:`info_extension`,      |
+|            | :mconfig:`linked_envvars`                                       |
 +------------+-----------------------------------------------------------------+
 
 :mconfig:`auto_handling`

doc/source/design/linked-envvars.rst

@@ -0,0 +1,77 @@
+.. _linked-envvars:
+
+Linked environment variables
+============================
+
+This document describes the mechanism to link one environment variables onto
+others and apply the same value changes.
+
+The goal is to link environment variables together and apply all changes to
+both once linked.
+
+Design choices:
+
+* When link is being established, variable value is not synced
+* Link is not reflexive: if A is linked to B, all changes made to A are
+  applied to B, but direct changes to B are not applied to A unless if this
+  link is also configured
+* A ``module display`` shows the environment changes applying to linked
+  environment variables
+
+This mechanism applies to all environment variable management modulefile
+commands and module sub-commands:
+
+* :mfcmd:`append-path`
+* :mfcmd:`prepend-path`
+* :mfcmd:`pushenv`
+* :mfcmd:`remove-path`
+* :mfcmd:`setenv`
+* :mfcmd:`unsetenv`
+
+.. note:: Link is not effective when a value is set to the environment
+   variable through the ``::env`` Tcl global array.
+
+``linked_envvars`` configuration option
+---------------------------------------
+
+New configuration option :mconfig:`linked_envvars` is made to configure these
+links between environment variables.
+
+* Items are separated by colon character
+* One variable can be linked to several ones, either through:
+
+  - one item with several variables: ``A&B&C``
+  - several items: ``A&B:A&C``
+
+Implementation
+--------------
+
+* Define an internal state (``current_envvar``) to indicate the name of the
+  environment variable currently modified
+* Set a ``trace`` to execute ``mirrorEnvVarChange`` procedure at the end of
+  the execution of environment variable management commands
+* No trace setup if :mconfig:`linked_envvars` is empty
+* ``mirrorEnvVarChange`` procedure:
+
+  - get currently modified environment variable name through
+    ``current_envvar`` state
+  - get environment variable change command to execute through
+    ``command-string`` trace argument
+  - replace ``current_envvar`` in this command string by linked environment
+    variable name
+  - execute resulting command string in currently active interpreter
+  - do this for each linked environment variable, including recursively linked
+    ones: trace is triggered one and handle all environment variables to avoid
+    cycle loop
+
+.. note:: No other environment variable change can occur between the
+   definition of the ``current_envvar`` state and the execution of the
+   ``mirrorEnvVarChange`` trace procedure. The link mechanism cannot apply to
+   Modules internal environment variables like ``__MODULES_SHARE_*``.
+
+.. note:: Environment variable name argument is always positioned before any
+   value, thus replacing the first occurrence found of this name will
+   accurately change the name argument on all environment variable change
+   commands.
+
+.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent:

doc/source/module.rst

@@ -1248,6 +1248,21 @@ Module Sub-Commands
 
      .. versionadded:: 5.7
 
+ .. mconfig:: linked_envvars
+
+  Define links between environment variables to apply same value modification
+  to each linked variables.
+
+  This configuration option is set to an empty value by default. The
+  :envvar:`MODULES_LINKED_ENVVARS` environment variable is defined by
+  :subcmd:`config` sub-command when changing this configuration option from
+  its default value. See :envvar:`MODULES_LINKED_ENVVARS` description for
+  details
+
+  .. only:: html or latex
+
+     .. versionadded:: 5.7
+
  .. mconfig:: list_output
 
   Content to report in addition to module names on :subcmd:`list` sub-command
@@ -5149,6 +5164,32 @@ ENVIRONMENT
 
     .. versionadded:: 5.7
 
+.. envvar:: MODULES_LINKED_ENVVARS
+
+ A colon-separated list of environment variable link sets. Each link set is a
+ group of environment variable names separated by the ampersand character.
+ When an environment variable modification command is applied to the first
+ variable in a link set, the same command is automatically applied to all
+ other variables in that set.
+
+ This link mechanism applies to all environment variable management modulefile
+ commands and module sub-commands (:mfcmd:`append-path`,
+ :mfcmd:`prepend-path`, :mfcmd:`pushenv`, :mfcmd:`remove-path`,
+ :mfcmd:`setenv` and :mfcmd:`unsetenv`).
+
+ For example, if the configuration option is set to ``FOO&BAR&BAZ:BAR&QUX``, a
+ :mfcmd:`prepend-path` command applied to ``FOO`` will also be applied to
+ ``BAR``, ``BAZ``, and ``QUX``. Linking is not reflexive: a command applied to
+ ``QUX`` is not propagated to any other environment variable in the link set.
+
+ This environment variable value supersedes the default value set in the
+ :mconfig:`linked_envvars` configuration option. It can be defined with the
+ :subcmd:`config` sub-command.
+
+ .. only:: html or latex
+
+    .. versionadded:: 5.7
+
 .. envvar:: MODULES_LIST_OUTPUT
 
  A colon separated list of the elements to report in addition to module names

doc/source/modulefile.rst

@@ -1196,6 +1196,10 @@ the *modulefile* is being loaded.
  configuration option is activated, the *modulefile* is considered a
  dependency by the loaded modulefiles stored in the added modulepaths.
 
+ If a link is defined for variable through the :mconfig:`linked_envvars`
+ configuration option, the same :mfcmd:`prepend-path` command is applied to
+ all associated environment variables.
+
  .. only:: html or latex
 
     .. versionchanged:: 4.1
@@ -1359,6 +1363,10 @@ the *modulefile* is being loaded.
  which is named by prefixing *variable* by :envvar:`__MODULES_PUSHENV_\
  <__MODULES_PUSHENV_\<VAR\>>`.
 
+ If a link is defined for variable through the :mconfig:`linked_envvars`
+ configuration option, the same :mfcmd:`pushenv` command is applied to all
+ associated environment variables.
+
  .. only:: html or latex
 
     .. versionadded:: 5.1
@@ -1448,6 +1456,10 @@ the *modulefile* is being loaded.
 
  An error is raised if *value* equals *delimiter* character.
 
+ If a link is defined for variable through the :mconfig:`linked_envvars`
+ configuration option, the same :mfcmd:`remove-path` command is applied to
+ all associated environment variables.
+
  .. only:: html or latex
 
     .. versionchanged:: 4.1
@@ -1537,6 +1549,10 @@ the *modulefile* is being loaded.
 
  Any newline character in *value* is chopped if using *csh* or *tcsh* shells.
 
+ If a link is defined for variable through the :mconfig:`linked_envvars`
+ configuration option, the same :mfcmd:`setenv` command is applied to all
+ associated environment variables.
+
  .. only:: html or latex
 
     .. versionchanged:: 5.1
@@ -1661,6 +1677,10 @@ the *modulefile* is being loaded.
  environment *variable* is also unset when *modulefile* is unloaded. These
  behaviors are applied even if an optional *value* is defined.
 
+ If a link is defined for variable through the :mconfig:`linked_envvars`
+ configuration option, the same :mfcmd:`unsetenv` command is applied to all
+ associated environment variables.
+
  .. only:: html or latex
 
     .. versionchanged:: 5.0

doc/source/other-implementations.rst

@@ -71,6 +71,7 @@ table highlights features that are unique to each implementation.
        * :ref:`Specific modulepath for requirements`
        * :ref:`Logging activity`
        * :ref:`envml<envml(1)>` launcher
+       * :ref:`Linked environment variables`
 
 .. _Lua modulefile support: https://lmod.readthedocs.io/en/latest/050_lua_modulefiles.html
 .. _Inactive modules: https://lmod.readthedocs.io/en/latest/010_user.html#module-hierarchy

init/Makefile

@@ -136,7 +136,7 @@ comp_lint_opts := -a -i --all --icase
 comp_modtosh_opts := --auto --no-auto --force -f --icase -i
 comp_path_opts := -d --delim --duplicates
 comp_rm_path_opts := -d --delim --index
-comp_config_opts := --dump-state --reset abort_on_error advanced_version_spec auto_handling avail_indepth avail_output avail_terse_output cache_buffer_bytes cache_expiry_secs collection_pin_version collection_pin_tag collection_target color colors conflict_unload contact editor extended_default extra_siteconfig hide_auto_loaded home icase ignore_cache ignore_user_rc implicit_default implicit_requirement info_extension list_output list_terse_output locked_configs logged_events logger mcookie_check mcookie_version_check ml nearly_forbidden_days non_exportable_tags pager paginate path_entry_reorder protected_envvars quarantine_support rcfile redirect_output require_via reset_target_state run_quarantine search_match set_shell_startup shells_with_ksh_fpath silent_shell_debug source_cache spider_indepth spider_output spider_terse_output sticky_purge tag_abbrev tag_color_name tcl_linter term_background term_width unique_name_loaded unload_match_order variant_shortcut verbosity wa_277
+comp_config_opts := --dump-state --reset abort_on_error advanced_version_spec auto_handling avail_indepth avail_output avail_terse_output cache_buffer_bytes cache_expiry_secs collection_pin_version collection_pin_tag collection_target color colors conflict_unload contact editor extended_default extra_siteconfig hide_auto_loaded home icase ignore_cache ignore_user_rc implicit_default implicit_requirement info_extension linked_envvars list_output list_terse_output locked_configs logged_events logger mcookie_check mcookie_version_check ml nearly_forbidden_days non_exportable_tags pager paginate path_entry_reorder protected_envvars quarantine_support rcfile redirect_output require_via reset_target_state run_quarantine search_match set_shell_startup shells_with_ksh_fpath silent_shell_debug source_cache spider_indepth spider_output spider_terse_output sticky_purge tag_abbrev tag_color_name tcl_linter term_background term_width unique_name_loaded unload_match_order variant_shortcut verbosity wa_277
 
 define translate-in-script
 $(ECHO_GEN)

init/fish_completion

@@ -87,7 +87,7 @@ complete -c module -n '__fish_module_use_stashlist' -f -a "(module stashlist --c
    /Stash collection list\$/d; \
    /:\$/d; \
    /:ERROR:/d;')"
-complete -c module -n '__fish_module_use_config' -f -a "--dump-state --reset abort_on_error advanced_version_spec auto_handling avail_indepth avail_output avail_terse_output cache_buffer_bytes cache_expiry_secs collection_pin_version collection_pin_tag collection_target color colors conflict_unload contact editor extended_default extra_siteconfig hide_auto_loaded home icase ignore_cache ignore_user_rc implicit_default implicit_requirement info_extension list_output list_terse_output locked_configs logged_events logger mcookie_check mcookie_version_check ml nearly_forbidden_days non_exportable_tags pager paginate path_entry_reorder protected_envvars quarantine_support rcfile redirect_output require_via reset_target_state run_quarantine search_match set_shell_startup shells_with_ksh_fpath silent_shell_debug source_cache spider_indepth spider_output spider_terse_output sticky_purge tag_abbrev tag_color_name tcl_linter term_background term_width unique_name_loaded unload_match_order variant_shortcut verbosity wa_277"
+complete -c module -n '__fish_module_use_config' -f -a "--dump-state --reset abort_on_error advanced_version_spec auto_handling avail_indepth avail_output avail_terse_output cache_buffer_bytes cache_expiry_secs collection_pin_version collection_pin_tag collection_target color colors conflict_unload contact editor extended_default extra_siteconfig hide_auto_loaded home icase ignore_cache ignore_user_rc implicit_default implicit_requirement info_extension linked_envvars list_output list_terse_output locked_configs logged_events logger mcookie_check mcookie_version_check ml nearly_forbidden_days non_exportable_tags pager paginate path_entry_reorder protected_envvars quarantine_support rcfile redirect_output require_via reset_target_state run_quarantine search_match set_shell_startup shells_with_ksh_fpath silent_shell_debug source_cache spider_indepth spider_output spider_terse_output sticky_purge tag_abbrev tag_color_name tcl_linter term_background term_width unique_name_loaded unload_match_order variant_shortcut verbosity wa_277"
 
 complete -f -n '__fish_module_no_subcommand' -c module -a 'help' --description 'Print this or modulefile(s) help info'
 complete -f -n '__fish_module_no_subcommand' -c module -a 'avail' --description 'List all or matching available modules'