| 1 |
.. _add-new-sub-command: |
| 2 |
|
| 3 |
Add new module sub-command |
| 4 |
========================== |
| 5 |
|
| 6 |
This document is a guide for Modules developers that wish to introduce a new |
| 7 |
sub-command 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 |
1. First update in the ``reportUsage`` procedure the usage message of the |
| 17 |
:command:`module` command to report the new sub-command. |
| 18 |
|
| 19 |
- File to edit: :file:`tcl/report.tcl.in` |
| 20 |
- Example commit: :ghcommit:`697b999a` |
| 21 |
|
| 22 |
2. Update the ``module`` procedure and its helper procedures to register the |
| 23 |
new sub-command. First add sub-command in the list of valid sub-commands |
| 24 |
defined in ``parseModuleCommandName``. |
| 25 |
|
| 26 |
If sub-command cannot be called within a modulefile context add it in |
| 27 |
``module`` procedure to the list of sub-commands raising an error if found |
| 28 |
call from such context. |
| 29 |
|
| 30 |
Add test in ``module`` procedure to verify that the number of argument |
| 31 |
passed to sub-command is valid. |
| 32 |
|
| 33 |
Update main switch in ``module`` procedure to add case for new sub-command |
| 34 |
that calls the ``cmdModule<Subcmdname>`` procedure. |
| 35 |
|
| 36 |
- File to edit: :file:`tcl/main.tcl.in` |
| 37 |
- Example commit: :ghcommit:`697b999a` |
| 38 |
|
| 39 |
3. Create the ``cmdModule<Subcmdname>`` procedure and craft in it the Tcl code |
| 40 |
corresponding to the sub-command introduced. |
| 41 |
|
| 42 |
- File to edit: :file:`tcl/subcmd.tcl.in` |
| 43 |
- Example commit: :ghcommit:`697b999a` |
| 44 |
|
| 45 |
Initialization scripts |
| 46 |
---------------------- |
| 47 |
|
| 48 |
New sub-command should be referred in the shell completion scripts. |
| 49 |
|
| 50 |
Files that should be edited to add reference to the new sub-command: |
| 51 |
|
| 52 |
- :file:`init/Makefile` (contains definitions to build *bash* and *tcsh* |
| 53 |
completion scripts |
| 54 |
- :file:`init/bash_completion.in` |
| 55 |
- :file:`init/fish_completion` |
| 56 |
- :file:`init/tcsh_completion.in` |
| 57 |
- :file:`init/zsh-functions/_module.in` |
| 58 |
|
| 59 |
Example commit: :ghcommit:`0a96ed64` |
| 60 |
|
| 61 |
Linter scripts |
| 62 |
-------------- |
| 63 |
|
| 64 |
New sub-commands should be described in Nagelfar syntax databases if it can be |
| 65 |
called within a modulefile context. |
| 66 |
|
| 67 |
Files that should be edited to add reference to the new sub-command: |
| 68 |
|
| 69 |
- :file:`share/nagelfar/syntaxdb_modulefile.tcl` |
| 70 |
|
| 71 |
- add sub-command name in ``::subCmd(module)`` list |
| 72 |
- add sub-command argument description in ``::syntax`` array |
| 73 |
- add sub-command option description in ``::option`` array |
| 74 |
- See `Nagelfar syntax description`_ |
| 75 |
|
| 76 |
.. _Nagelfar syntax description: http://nagelfar.sourceforge.net/syntaxtokens.html |
| 77 |
|
| 78 |
Documentation |
| 79 |
------------- |
| 80 |
|
| 81 |
Man pages and other user documentation have to be updated to describe the |
| 82 |
introduced sub-command. |
| 83 |
|
| 84 |
Files that should be edited: |
| 85 |
|
| 86 |
- :file:`doc/source/module.rst` (module manpage) |
| 87 |
|
| 88 |
- add sub-command description with ``subcmd`` anchor under *Module |
| 89 |
Sub-Commands* section |
| 90 |
|
| 91 |
- :file:`doc/source/modulefile.rst` (modulefile manpage) |
| 92 |
|
| 93 |
- mention if sub-command can be called from the modulefile evaluation |
| 94 |
context under :mfcmd:`module` modulefile command section |
| 95 |
- if sub-command leads to modulefile evaluation, mention sub-command name |
| 96 |
in the list of value returned by :mfcmd:`module-info |
| 97 |
command<module-info>` |
| 98 |
|
| 99 |
- :file:`doc/source/changes.rst` |
| 100 |
|
| 101 |
- add sub-command under *Module Sub-Commands* section of current Modules |
| 102 |
major version |
| 103 |
|
| 104 |
Example commits: |
| 105 |
|
| 106 |
- sub-command doc: :ghcommit:`b4c0e0f8` |
| 107 |
- new value returned by ``module-info command``: :ghcommit:`5cd53523` |
| 108 |
|
| 109 |
Testsuite |
| 110 |
--------- |
| 111 |
|
| 112 |
Non-regression testsuite must be adapted first to add specific tests to check |
| 113 |
the behavior of the added sub-command and ensure overall code coverage does |
| 114 |
not drop. |
| 115 |
|
| 116 |
#. Test the sub-command against an invalid number of arguments (too few and |
| 117 |
too many). |
| 118 |
|
| 119 |
- File to edit: :file:`testsuite/modules.00-init/071-args.exp` |
| 120 |
- Example commit: :ghcommit:`086ac136` |
| 121 |
|
| 122 |
#. If the new sub-command cannot be called from a modulefile evaluation, test |
| 123 |
the error obtained when tried. |
| 124 |
|
| 125 |
- Files to edit: |
| 126 |
|
| 127 |
- :file:`testsuite/modules.50-cmds/151-module-onlytop.exp` |
| 128 |
- :file:`testsuite/modulefiles.3/modbad/<subcmdname>` |
| 129 |
|
| 130 |
- Example commit: :ghcommit:`086ac136` |
| 131 |
|
| 132 |
#. If the new sub-command leads to modulefile evaluation, test value returned |
| 133 |
by :mfcmd:`module-info command<module-info>`. |
| 134 |
|
| 135 |
- Files to edit: |
| 136 |
|
| 137 |
- :file:`testsuite/modules.50-cmds/282-info-command.exp` |
| 138 |
- :file:`testsuite/modules.50-cmds/283-info-command-exp.exp` |
| 139 |
- :file:`testsuite/modulefiles/info/commandexp` |
| 140 |
|
| 141 |
- Example commit: :ghcommit:`5cd53523` |
| 142 |
|
| 143 |
#. Craft specific tests to validate the correct behavior of the sub-command |
| 144 |
against valid or invalid values and valid or invalid environment. |
| 145 |
|
| 146 |
- File to edit: new test file to create in |
| 147 |
:file:`testsuite/modules.50-cmds` directory, for sub-command called |
| 148 |
during a modulefile evaluation, or in :file:`testsuite/modules.70-maint` |
| 149 |
directory otherwise. |
| 150 |
|
| 151 |
- Example commit: :ghcommit:`086ac136` |
| 152 |
|
| 153 |
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: |