Add new module sub-command

This document is a guide for Modules developers that wish to introduce a new sub-command 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 update in the reportUsage procedure the usage message of the module command to report the new sub-command.

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

    • Example commit: 697b999a

  2. Update the module procedure and its helper procedures to register the new sub-command. First add sub-command in the list of valid sub-commands defined in parseModuleCommandName.

    If sub-command cannot be called within a modulefile context add it in module procedure to the list of sub-commands raising an error if found call from such context.

    Add test in module procedure to verify that the number of argument passed to sub-command is valid.

    Update main switch in module procedure to add case for new sub-command that calls the cmdModule<Subcmdname> procedure.

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

    • Example commit: 697b999a

  3. Create the cmdModule<Subcmdname> procedure and craft in it the Tcl code corresponding to the sub-command introduced.

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

    • Example commit: 697b999a

Initialization scripts

New sub-command should be referred in the shell completion scripts.

Files that should be edited to add reference to the new sub-command:

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

  • init/bash_completion.in

  • init/fish_completion

  • init/tcsh_completion.in

  • init/zsh-functions/_module.in

Example commit: 0a96ed64

Linter scripts

New sub-commands should be described in Nagelfar syntax databases if it can be called within a modulefile context.

Files that should be edited to add reference to the new sub-command:

  • share/nagelfar/syntaxdb_modulefile.tcl

    • add sub-command name in ::subCmd(module) list

    • add sub-command argument description in ::syntax array

    • add sub-command option description in ::option array

    • See Nagelfar syntax description

Documentation

Man pages and other user documentation have to be updated to describe the introduced sub-command.

Files that should be edited:

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

    • add sub-command description with subcmd anchor under Module Sub-Commands section

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

    • mention if sub-command can be called from the modulefile evaluation context under module modulefile command section

    • if sub-command leads to modulefile evaluation, mention sub-command name in the list of value returned by module-info command

  • doc/source/changes.rst

    • add sub-command under Module Sub-Commands section of current Modules major version

Example commits:

Testsuite

Non-regression testsuite must be adapted first to add specific tests to check the behavior of the added sub-command and ensure overall code coverage does not drop.

  1. Test the sub-command against an invalid number of arguments (too few and too many).

    • File to edit: testsuite/modules.00-init/071-args.exp

    • Example commit: 086ac136

  2. If the new sub-command cannot be called from a modulefile evaluation, test the error obtained when tried.

    • Files to edit:

      • testsuite/modules.50-cmds/151-module-onlytop.exp

      • testsuite/modulefiles.3/modbad/<subcmdname>

    • Example commit: 086ac136

  3. If the new sub-command leads to modulefile evaluation, test value returned by module-info command.

    • Files to edit:

      • testsuite/modules.50-cmds/282-info-command.exp

      • testsuite/modules.50-cmds/283-info-command-exp.exp

      • testsuite/modulefiles/info/commandexp

    • Example commit: 5cd53523

  4. Craft specific tests to validate the correct behavior of the sub-command against valid or invalid values and valid or invalid environment.

    • File to edit: new test file to create in testsuite/modules.50-cmds directory, for sub-command called during a modulefile evaluation, or in testsuite/modules.70-maint directory otherwise.

    • Example commit: 086ac136