Debian Codegraph @

doc/source/design/linked-envvars.rst

raw
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: