Debian Codegraph @

doc/source/devel/add-new-config-option.rst

raw
1 .. _add-new-config-option:
2
3 Add new configuration option
4 ============================
5
6 This document is a guide for Modules developers that wish to introduce a new
7 configuration option for the :command:`module` command.
8
9 Core code
10 ---------
11
12 Introducing new configuration option means declaring it then using it (get its
13 value then branch code in :file:`modulecmd.tcl` script to adapt
14 :command:`module` command behavior.
15
16 #. First declare configuration option in ``g_config_defs`` definition array
17
18 - File to edit: :file:`tcl/init.tcl.in`
19 - Example commit: :ghcommit:`2199edf8`
20
21 New configuration option name should be short yet understandable. If
22 composed of multiple words, they should be joined by ``_`` character.
23 Option value could be superseded by an environment variable, using same name
24 than config, upper-cased and prefixed by ``MODULES_``.
25
26 Entry in ``g_config_defs`` definition array uses option name as key then a
27 list as value composed with:
28
29 - Superseding environment variable
30 - Default value
31 - Is configuration lockable to default value (0 or 1)
32 - Value kind (``i`` for integer, ``s`` for string, ``b`` for boolean,
33 ``l`` for colon-separated list, ``o`` for other)
34 - Valid value list (empty list if no validation list)
35 - Internal value representation (optional)
36 - Specific procedure to call to initialize option value (optional)
37 - Valid value list kind (empty string, ``intbe`` or ``eltlist``)
38
39 #. Update the Tcl code that compose the :file:`modulecmd.tcl` script to adapt
40 behavior depending on the value defined (by default or superseded) for the
41 configuration option. Use the ``getConf`` helper procedure to fetch
42 configuration option value. This part highly depends on the kind of
43 configuration option introduced.
44
45 - File to edit: file(s) in :file:`tcl/` directory
46 - Example commit: :ghcommit:`4baf5dc4`
47
48 Installation scripts
49 --------------------
50
51 If the default value of the configuration option may be selected at
52 installation time, an installation option should be added on the
53 :file:`configure` script.
54
55 #. Define installation option argument in :file:`configure` script, add it to
56 the internal help message of this shell script, define an internal
57 ``<optionname>`` variable that is set to the default installation option
58 value, then updated when install option argument is set.
59
60 - File to edit: :file:`configure`
61 - Example commit: :ghcommit:`c00ecefa`
62
63 #. Define the ``<optionname>`` variable in :file:`Makefile.inc.in` set to the
64 ``@<optionname>@`` mark, that will be replaced by chosen value for option
65 when :file:`configure` script will generate :file:`Makefile.inc`. Define
66 the ``install_<optionname>`` variable in :file:`site.exp.in` to get value
67 set for option within testsuite. Update ``translate-in-script`` rule in
68 :file:`Makefile` to add translation of the ``@<optionname>@`` mark into
69 selected value.
70
71 - Files to edit:
72
73 - :file:`Makefile.inc.in`
74 - :file:`Makefile`
75 - :file:`site.exp.in`
76
77 - Example commit: :ghcommit:`c00ecefa`
78
79 #. Set the ``@<optionname>@`` mark as the default value for configuration
80 option in ``g_config_defs`` definition array in Tcl core code
81
82 - File to edit: :file:`tcl/init.tcl.in`
83 - Example commit: :ghcommit:`c00ecefa`
84
85 When the *make* installation step is performed the :file:`modulecmd.tcl`
86 script file is generated with the ``@<optionname>@`` mark replaced by
87 selected default value.
88
89 Initialization scripts
90 ----------------------
91
92 New configuration option should be referred in the shell completion scripts as
93 argument for the :subcmd:`config` sub-command.
94
95 Files that should be edited to add reference to the new option:
96
97 - :file:`init/Makefile` (contains definitions to build *bash* and *tcsh*
98 completion scripts
99 - :file:`init/fish_completion`
100 - :file:`init/zsh-functions/_module.in`
101
102 Example commit: :ghcommit:`abfef4ed`
103
104 Documentation
105 -------------
106
107 Man pages and other user documentation have to be updated to describe the
108 introduced option.
109
110 Files that should be edited:
111
112 - :file:`doc/source/module.rst` (module manpage)
113
114 - add configuration option description with ``mconfig`` anchor under
115 :subcmd:`config` sub-command section
116 - add environment variable description with ``envvar`` anchor under
117 *ENVIRONMENT* section
118
119 - :file:`doc/source/changes.rst`
120
121 - add configuration option under *Modules configuration options* section of
122 current Modules major version
123 - add environment variable under *Environment* section of current Modules
124 major version
125
126 - :file:`INSTALL.rst`
127
128 - add configuration and related environment variable and installation
129 option in the table under *Configuration options* section
130
131 Example commits:
132
133 - configuration option doc: :ghcommit:`f8e5eac6`
134 - related environment variable doc: :ghcommit:`eed719f0`
135
136 In case an installation option has been added, it should be covered by documentation
137
138 - File to edit: :file:`INSTALL.rst`
139 - Example commit: :ghcommit:`3d19ab52`
140
141 Testsuite
142 ---------
143
144 Non-regression testsuite must be adapted first to ensure existing tests still
145 pass then to add specific tests to check the behavior of the added
146 configuration option and ensure overall code coverage does not drop.
147
148 #. First, clear the run test environment from predefined configuration value,
149 set over the associated environment variable.
150
151 - Files that should be edited:
152
153 - :file:`testsuite/modules.00-init/010-environ.exp`
154 - :file:`testsuite/install.00-init/010-environ.exp`
155
156 - Example commit: :ghcommit:`1c9fe1bd`
157
158 If default value for option could be set at installation time, it may be
159 important to take this chosen default value into account, thanks to the
160 ``install_<optionname>`` Tcl variable set in :file:`site.exp`.
161
162 #. Add new configuration option to the list of options tested over the
163 :subcmd:`config` sub-command.
164
165 - File to edit: :file:`testsuite/modules.70-maint/220-config.exp`
166 - Example commit: :ghcommit:`1c9fe1bd`
167
168 #. Craft specific tests to validate the correct behavior of the configuration
169 when not set, set with valid or invalid values.
170
171 - File to edit: depends on what is impacted by the new configuration
172 option, if some tests already exist for concerned behavior (existing
173 testsuite file to update) or not (new testfile to create).
174 - Example commit: :ghcommit:`122039e5`
175
176 #. Optionally if a new installation option has been introduced, it may be
177 interesting to adapt CI configuration to test a value different than the
178 default one
179
180 - Files to either edit:
181
182 - :file:`.cirrus.yml`
183 - :file:`.github/workflows/linux_tests.yaml`
184
185 - Example commit: :ghcommit:`8bf6fb54`
186
187 .. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: