| 1 |
.. _linked-envvars: |
| 2 |
|
| 3 |
Linked environment variables |
| 4 |
============================ |
| 5 |
|
| 6 |
This document describes the mechanism to link one environment variable onto |
| 7 |
others and apply the same value changes. |
| 8 |
|
| 9 |
The goal is to link environment variables together and apply all changes to |
| 10 |
both once linked. |
| 11 |
|
| 12 |
Design choices: |
| 13 |
|
| 14 |
* When link is being established, variable value is not synced |
| 15 |
* Link is not reflexive: if A is linked to B, all changes made to A are |
| 16 |
applied to B, but direct changes to B are not applied to A unless if this |
| 17 |
link is also configured |
| 18 |
* A ``module display`` shows the environment changes applying to linked |
| 19 |
environment variables |
| 20 |
|
| 21 |
This mechanism applies to all environment variable management modulefile |
| 22 |
commands and module sub-commands: |
| 23 |
|
| 24 |
* :mfcmd:`append-path` |
| 25 |
* :mfcmd:`prepend-path` |
| 26 |
* :mfcmd:`pushenv` |
| 27 |
* :mfcmd:`remove-path` |
| 28 |
* :mfcmd:`setenv` |
| 29 |
* :mfcmd:`unsetenv` |
| 30 |
|
| 31 |
.. note:: Link is not effective when a value is set to the environment |
| 32 |
variable through the ``::env`` Tcl global array. |
| 33 |
|
| 34 |
``linked_envvars`` configuration option |
| 35 |
--------------------------------------- |
| 36 |
|
| 37 |
New configuration option :mconfig:`linked_envvars` is made to configure these |
| 38 |
links between environment variables. |
| 39 |
|
| 40 |
* Items are separated by colon character |
| 41 |
* One variable can be linked to several ones, either through: |
| 42 |
|
| 43 |
- one item with several variables: ``A&B&C`` |
| 44 |
- several items: ``A&B:A&C`` |
| 45 |
|
| 46 |
Implementation |
| 47 |
-------------- |
| 48 |
|
| 49 |
* Define an internal state (``current_envvar``) to indicate the name of the |
| 50 |
environment variable currently modified |
| 51 |
* Set a ``trace`` to execute ``mirrorEnvVarChange`` procedure at the end of |
| 52 |
the execution of environment variable management commands |
| 53 |
* No trace setup if :mconfig:`linked_envvars` is empty |
| 54 |
* ``mirrorEnvVarChange`` procedure: |
| 55 |
|
| 56 |
- get currently modified environment variable name through |
| 57 |
``current_envvar`` state |
| 58 |
- get environment variable change command to execute through |
| 59 |
``command-string`` trace argument |
| 60 |
- replace ``current_envvar`` in this command string by linked environment |
| 61 |
variable name |
| 62 |
- execute resulting command string in currently active interpreter |
| 63 |
- do this for each linked environment variable, including recursively linked |
| 64 |
ones: trace is triggered one and handle all environment variables to avoid |
| 65 |
cycle loop |
| 66 |
|
| 67 |
.. note:: No other environment variable change can occur between the |
| 68 |
definition of the ``current_envvar`` state and the execution of the |
| 69 |
``mirrorEnvVarChange`` trace procedure. The link mechanism cannot apply to |
| 70 |
Modules internal environment variables like ``__MODULES_SHARE_*``. |
| 71 |
|
| 72 |
.. note:: Environment variable name argument is always positioned before any |
| 73 |
value, thus replacing the first occurrence found of this name will |
| 74 |
accurately change the name argument on all environment variable change |
| 75 |
commands. |
| 76 |
|
| 77 |
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: |