Debian Codegraph @

doc/source/devel/add-new-sub-command.rst

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