"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/source/design/add-new-config-option.rst" between
modules-5.1.1.tar.bz2 and modules-5.2.0.tar.bz2

About: The Environment Modules package provides for the dynamic modification of a user’s environment via modulefiles.

add-new-config-option.rst  (modules-5.1.1.tar.bz2):add-new-config-option.rst  (modules-5.2.0.tar.bz2)
skipping to change at line 16 skipping to change at line 16
This document is a guide for Modules developers that wish to introduce a new This document is a guide for Modules developers that wish to introduce a new
configuration option for the :command:`module` command. configuration option for the :command:`module` command.
Core code Core code
--------- ---------
Introducing new configuration option means declaring it then using it (get its Introducing new configuration option means declaring it then using it (get its
value then branch code in :file:`modulecmd.tcl` script to adapt value then branch code in :file:`modulecmd.tcl` script to adapt
:command:`module` command behavior. :command:`module` command behavior.
1. First declare configuration option in ``g_config_defs`` definition array #. First declare configuration option in ``g_config_defs`` definition array
- File to edit: :file:`tcl/init.tcl.in` - File to edit: :file:`tcl/init.tcl.in`
- Example commit: :ghcommit:`2199edf8` - Example commit: :ghcommit:`2199edf8`
New configuration option name should be short yet understandable. If New configuration option name should be short yet understandable. If
composed of multiple words, they should be joined by ``_`` character. composed of multiple words, they should be joined by ``_`` character.
Option value could be superseded by an environment variable, using same name Option value could be superseded by an environment variable, using same name
than config, upper-cased and prefixed by ``MODULES_``. than config, upper-cased and prefixed by ``MODULES_``.
Entry in ``g_config_defs`` definition array uses option name as key then a Entry in ``g_config_defs`` definition array uses option name as key then a
list as value composed with: list as value composed with:
- Superseding environment variable - Superseding environment variable
- Default value - Default value
- Is configuration lockable to default value (0 or 1) - Is configuration lockable to default value (0 or 1)
- Valid value list (empty list if no validation list) - Valid value list (empty list if no validation list)
- Internal value representation (optional) - Internal value representation (optional)
- Specific procedure to call to initialize option value (optional) - Specific procedure to call to initialize option value (optional)
- Valid value list kind (empty string, ``intbe`` or ``eltlist``) - Valid value list kind (empty string, ``intbe`` or ``eltlist``)
2. Update the Tcl code that compose the :file:`modulecmd.tcl` script to adapt #. Update the Tcl code that compose the :file:`modulecmd.tcl` script to adapt
behavior depending on the value defined (by default or superseded) for the behavior depending on the value defined (by default or superseded) for the
configuration option. Use the ``getConf`` helper procedure to fetch configuration option. Use the ``getConf`` helper procedure to fetch
configuration option value. This part highly depends on the kind of configuration option value. This part highly depends on the kind of
configuration option introduced. configuration option introduced.
- File to edit: file(s) in :file:`tcl/` directory - File to edit: file(s) in :file:`tcl/` directory
- Example commit: :ghcommit:`4baf5dc4` - Example commit: :ghcommit:`4baf5dc4`
Installation scripts Installation scripts
-------------------- --------------------
If the default value of the configuration option may be selected at If the default value of the configuration option may be selected at
installation time, an installation option should be added on the installation time, an installation option should be added on the
:file:`configure` script. :file:`configure` script.
1. Define installation option argument in :file:`configure` script, add it to #. Define installation option argument in :file:`configure` script, add it to
the internal help message of this shell script, define an internal the internal help message of this shell script, define an internal
``<optionname>`` variable that is set to the default installation option ``<optionname>`` variable that is set to the default installation option
value, then updated when install option argument is set. value, then updated when install option argument is set.
- File to edit: :file:`configure` - File to edit: :file:`configure`
- Example commit: :ghcommit:`c00ecefa` - Example commit: :ghcommit:`c00ecefa`
2. Define the ``<optionname>`` variable in :file:`Makefile.inc.in` set to the #. Define the ``<optionname>`` variable in :file:`Makefile.inc.in` set to the
``@<optionname>@`` mark, that will be replaced by chosen value for option ``@<optionname>@`` mark, that will be replaced by chosen value for option
when :file:`configure` script will generate :file:`Makefile.inc`. Define when :file:`configure` script will generate :file:`Makefile.inc`. Define
the ``install_<optionname>`` variable in :file:`site.exp.in` to get value the ``install_<optionname>`` variable in :file:`site.exp.in` to get value
set for option within testsuite. Update ``translate-in-script`` rule in set for option within testsuite. Update ``translate-in-script`` rule in
:file:`Makefile` to add translation of the ``@<optionname>@`` mark into :file:`Makefile` to add translation of the ``@<optionname>@`` mark into
selected value. selected value.
- Files to edit: - Files to edit:
- :file:`Makefile.inc.in` - :file:`Makefile.inc.in`
- :file:`Makefile` - :file:`Makefile`
- :file:`site.exp.in` - :file:`site.exp.in`
- Example commit: :ghcommit:`c00ecefa` - Example commit: :ghcommit:`c00ecefa`
3. Set the ``@<optionname>@`` mark as the default value for configuration #. Set the ``@<optionname>@`` mark as the default value for configuration
option in ``g_config_defs`` definition array in Tcl core code option in ``g_config_defs`` definition array in Tcl core code
- File to edit: :file:`tcl/init.tcl.in` - File to edit: :file:`tcl/init.tcl.in`
- Example commit: :ghcommit:`c00ecefa` - Example commit: :ghcommit:`c00ecefa`
When the *make* installation step is performed the :file:`modulecmd.tcl` When the *make* installation step is performed the :file:`modulecmd.tcl`
script file is generated with the ``@<optionname>@`` mark replaced by script file is generated with the ``@<optionname>@`` mark replaced by
selected default value. selected default value.
Initialization scripts Initialization scripts
skipping to change at line 112 skipping to change at line 112
Documentation Documentation
------------- -------------
Man pages and other user documentation have to be updated to describe the Man pages and other user documentation have to be updated to describe the
introduced option. introduced option.
Files that should be edited: Files that should be edited:
- :file:`doc/source/module.rst` (module manpage) - :file:`doc/source/module.rst` (module manpage)
- add configuration option description with ``mconfig`` anchor under - add configuration option description with ``mconfig`` anchor under
:subcmd:`config` sub-command section :subcmd:`config` sub-command section
- add environment variable description with ``envvar`` anchor under - add environment variable description with ``envvar`` anchor under
*ENVIRONMENT* section *ENVIRONMENT* section
- :file:`doc/source/changes.rst` - :file:`doc/source/changes.rst`
- add configuration option under *Modules configuration options* section of - add configuration option under *Modules configuration options* section of
current Modules major version current Modules major version
- add environment variable under *Environment* section of current Modules - add environment variable under *Environment* section of current Modules
major version major version
- :file:`INSTALL.rst` - :file:`INSTALL.rst`
- add configuration and related environment variable and installation - add configuration and related environment variable and installation
option in the table under *Configuration options* section option in the table under *Configuration options* section
Example commits: Example commits:
- configuration option doc: :ghcommit:`f8e5eac6` - configuration option doc: :ghcommit:`f8e5eac6`
- related environment variable doc: :ghcommit:`eed719f0` - related environment variable doc: :ghcommit:`eed719f0`
In case an installation option has been added, it should be covered by documenta tion In case an installation option has been added, it should be covered by documenta tion
- File to edit: :file:`INSTALL.rst` - File to edit: :file:`INSTALL.rst`
- Example commit: :ghcommit:`3d19ab52` - Example commit: :ghcommit:`3d19ab52`
Example commit: :ghcommit:`3d19ab52`
Testsuite Testsuite
--------- ---------
Non-regression testsuite must be adapted first to ensure existing tests still Non-regression testsuite must be adapted first to ensure existing tests still
pass then to add specific tests to check the behavior of the added pass then to add specific tests to check the behavior of the added
configuration option and ensure overall code coverage does not drop. configuration option and ensure overall code coverage does not drop.
1. First, clear the run test environment from predefined configuration value, #. First, clear the run test environment from predefined configuration value,
set over the associated environment variable. set over the associated environment variable.
- Files that should be edited: - Files that should be edited:
- :file:`testsuite/modules.00-init/010-environ.exp` - :file:`testsuite/modules.00-init/010-environ.exp`
- :file:`testsuite/install.00-init/010-environ.exp` - :file:`testsuite/install.00-init/010-environ.exp`
- Example commit: :ghcommit:`1c9fe1bd` - Example commit: :ghcommit:`1c9fe1bd`
If default value for option could be set at installation time, it may be If default value for option could be set at installation time, it may be
important to take this chosen default value into account, thanks to the important to take this chosen default value into account, thanks to the
``install_<optionname>`` Tcl variable set in :file:`site.exp`. ``install_<optionname>`` Tcl variable set in :file:`site.exp`.
2. Add new configuration option to the list of options tested over the #. Add new configuration option to the list of options tested over the
:subcmd:`config` sub-command. :subcmd:`config` sub-command.
- File to edit: :file:`testsuite/modules.70-maint/220-config.exp` - File to edit: :file:`testsuite/modules.70-maint/220-config.exp`
- Example commit: :ghcommit:`1c9fe1bd` - Example commit: :ghcommit:`1c9fe1bd`
3. Craft specific tests to validate the correct behavior of the configuration #. Craft specific tests to validate the correct behavior of the configuration
when not set, set with valid or invalid values. when not set, set with valid or invalid values.
- File to edit: depends on what is impacted by the new configuration - File to edit: depends on what is impacted by the new configuration
option, if some tests already exist for concerned behavior (existing option, if some tests already exist for concerned behavior (existing
testsuite file to update) or not (new testfile to create). testsuite file to update) or not (new testfile to create).
- Example commit: :ghcommit:`122039e5` - Example commit: :ghcommit:`122039e5`
4. Optionally if a new installation option has been introduced, it may be #. Optionally if a new installation option has been introduced, it may be
interesting to adapt CI configuration to test a value different than the interesting to adapt CI configuration to test a value different than the
default one default one
- Files to either edit: - Files to either edit:
- :file:`.cirrus.yml` - :file:`.cirrus.yml`
- :file:`.github/workflows/linux_tests.yaml` - :file:`.github/workflows/linux_tests.yaml`
- Example commit: :ghcommit:`8bf6fb54` - Example commit: :ghcommit:`8bf6fb54`
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent:
 End of changes. 19 change blocks. 
30 lines changed or deleted 28 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)