Add new configuration option

This document is a guide for Modules developers that wish to introduce a new configuration option for the module command.

Core code

Introducing new configuration option means declaring it then using it (get its value then branch code in modulecmd.tcl script to adapt module command behavior.

  1. First declare configuration option in g_config_defs definition array

    • File to edit: tcl/init.tcl.in

    • Example commit: 2199edf8

    New configuration option name should be short yet understandable. If composed of multiple words, they should be joined by _ character. Option value could be superseded by an environment variable, using same name than config, upper-cased and prefixed by MODULES_.

    Entry in g_config_defs definition array uses option name as key then a list as value composed with:

    • Superseding environment variable

    • Default value

    • Is configuration lockable to default value (0 or 1)

    • Value kind (i for integer, s for string, b for boolean, l for colon-separated list, o for other)

    • Valid value list (empty list if no validation list)

    • Internal value representation (optional)

    • Specific procedure to call to initialize option value (optional)

    • Valid value list kind (empty string, intbe or eltlist)

  2. Update the Tcl code that compose the modulecmd.tcl script to adapt behavior depending on the value defined (by default or superseded) for the configuration option. Use the getConf helper procedure to fetch configuration option value. This part highly depends on the kind of configuration option introduced.

    • File to edit: file(s) in tcl/ directory

    • Example commit: 4baf5dc4

Installation scripts

If the default value of the configuration option may be selected at installation time, an installation option should be added on the configure script.

  1. Define installation option argument in configure script, add it to the internal help message of this shell script, define an internal <optionname> variable that is set to the default installation option value, then updated when install option argument is set.

    • File to edit: configure

    • Example commit: c00ecefa

  2. Define the <optionname> variable in Makefile.inc.in set to the @<optionname>@ mark, that will be replaced by chosen value for option when configure script will generate Makefile.inc. Define the install_<optionname> variable in site.exp.in to get value set for option within testsuite. Update translate-in-script rule in Makefile to add translation of the @<optionname>@ mark into selected value.

    • Files to edit:

      • Makefile.inc.in

      • Makefile

      • site.exp.in

    • Example commit: c00ecefa

  3. Set the @<optionname>@ mark as the default value for configuration option in g_config_defs definition array in Tcl core code

    • File to edit: tcl/init.tcl.in

    • Example commit: c00ecefa

    When the make installation step is performed the modulecmd.tcl script file is generated with the @<optionname>@ mark replaced by selected default value.

Initialization scripts

New configuration option should be referred in the shell completion scripts as argument for the config sub-command.

Files that should be edited to add reference to the new option:

  • init/Makefile (contains definitions to build bash and tcsh completion scripts

  • init/fish_completion

  • init/zsh-functions/_module.in

Example commit: abfef4ed

Documentation

Man pages and other user documentation have to be updated to describe the introduced option.

Files that should be edited:

  • doc/source/module.rst (module manpage)

    • add configuration option description with mconfig anchor under config sub-command section

    • add environment variable description with envvar anchor under ENVIRONMENT section

  • doc/source/changes.rst

    • add configuration option under Modules configuration options section of current Modules major version

    • add environment variable under Environment section of current Modules major version

  • INSTALL.rst

    • add configuration and related environment variable and installation option in the table under Configuration options section

Example commits:

In case an installation option has been added, it should be covered by documentation

  • File to edit: INSTALL.rst

  • Example commit: 3d19ab52

Testsuite

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 configuration option and ensure overall code coverage does not drop.

  1. First, clear the run test environment from predefined configuration value, set over the associated environment variable.

    • Files that should be edited:

      • testsuite/modules.00-init/010-environ.exp

      • testsuite/install.00-init/010-environ.exp

    • Example commit: 1c9fe1bd

    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 install_<optionname> Tcl variable set in site.exp.

  2. Add new configuration option to the list of options tested over the config sub-command.

    • File to edit: testsuite/modules.70-maint/220-config.exp

    • Example commit: 1c9fe1bd

  3. Craft specific tests to validate the correct behavior of the configuration when not set, set with valid or invalid values.

    • File to edit: depends on what is impacted by the new configuration option, if some tests already exist for concerned behavior (existing testsuite file to update) or not (new testfile to create).

    • Example commit: 122039e5

  4. Optionally if a new installation option has been introduced, it may be interesting to adapt CI configuration to test a value different than the default one

    • Files to either edit:

      • .cirrus.yml

      • .github/workflows/linux_tests.yaml

    • Example commit: 8bf6fb54