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