Debian Codegraph @

AGENTS.md

raw
1 # AGENTS.md
2
3 This file provides guidance to AI coding assistants when working with code
4 in this repository. Codex, Claude Code and Mistral Vibe read it directly.
5 Gemini CLI only looks for its own `GEMINI.md` filename, so it is generated
6 as a stub that just imports this file (see the `GEMINI.md:` rule in
7 `Makefile`).
8
9 ## What this is
10
11 Modules (`envmodules/modules`) is the `module` command: a Tcl-based tool for
12 dynamic modification of a user's shell environment via modulefiles. The
13 runtime engine (`modulecmd.tcl`) is written in Tcl and must stay compatible
14 with Tcl 8.5+.
15
16 ## Build
17
18 ```sh
19 ./configure
20 make # builds modulecmd.tcl and other install artifacts
21 make install
22 ```
23
24 `configure`/`Makefile` are hand-written (no autoconf/automake despite
25 `lib/aclocal.m4`, `lib/configure.ac` existing for the optional C helper
26 library in `lib/`).
27
28 ### The core script is generated, not hand-edited directly for the final artifact
29
30 `modulecmd.tcl` (the actual interpreter installed to `libexecdir`) is built by
31 `make` by concatenating the files in `tcl/` in a fixed order (see the
32 `modulecmd.tcl:` rule in `Makefile`):
33
34 ```
35 init -> util -> envmngt -> report -> interp -> mfcmd -> modscan ->
36 modfind -> modeval -> modspec -> cache -> coll -> main -> subcmd
37 ```
38
39 Always edit the individual source file in `tcl/` (e.g. `tcl/main.tcl.in`,
40 `tcl/subcmd.tcl.in`); never edit a built `modulecmd.tcl` output directly.
41 Files with a `.in` suffix contain `@markname@` substitutions filled in by
42 `configure`/`Makefile`; files without `.in` (`mfcmd.tcl`, `modeval.tcl`,
43 `modscan.tcl`, `modspec.tcl`, `syntaxdb.tcl`, `util.tcl`) have no
44 substitutions.
45
46 ## Tests
47
48 See `doc/source/devel/testsuite.rst` for the full description of how the
49 testsuite (DejaGnu-based) is organized, how to add tests, and how to debug
50 a failing one.
51
52 ```sh
53 make test # full suite via DejaGnu (~25,000 cases, ~12 min)
54 make test QUICKTEST=y # quick mode, most essential tests (~1,900 cases, ~1 min)
55 make testinstall # test an already-`make install`ed tree
56 ```
57
58 Run a subset of tests directly with `script/mt` (reports an expected/actual
59 diff on failure):
60
61 ```sh
62 script/mt 50/470 # runs testsuite/modules.50-cmds/470-*.exp
63 script/mt --help # full usage/selection syntax
64 ```
65
66 Coverage (uses Nagelfar):
67
68 ```sh
69 make test COVERAGE=y # then inspect tcl/*.tcl_m for ';# Not covered' lines
70 script/mt cov 70/{280,290} # coverage run on selected testfiles
71 ```
72
73 Lint (Nagelfar for Tcl, ShellCheck for sh/bash/ksh):
74
75 ```sh
76 make testlint
77 script/mt lint 00/030
78 ```
79
80 Performance comparison across released versions and current branch
81 (`script/mb`, stashes local changes, builds `modulecmd.tcl` for each
82 version):
83
84 ```sh
85 script/mb
86 script/mb profile
87 ```
88
89 ## Docs
90
91 ```sh
92 cd doc && make html # requires Sphinx >= 1.0; output in doc/_build/html
93 ```
94
95 In `.rst` files, make a section title's underline exactly as long as the
96 title text — no more, no less. Sphinx silently accepts a longer underline,
97 so a length mismatch has to be checked deliberately whenever a title is
98 added or its text edited.
99
100 ## Repository layout
101
102 - `tcl/` — Tcl source, split by concern; concatenated into `modulecmd.tcl`
103 (see Build section). Key files:
104 - `init.tcl.in` — configuration option definitions (`g_config_defs`) and
105 state handling
106 - `main.tcl.in` — top-level `module` procedure, sub-command dispatch/parsing
107 - `subcmd.tcl.in` — one `cmdModule<Subcmdname>` procedure per sub-command
108 - `mfcmd.tcl` — modulefile commands (procedures usable *inside* a
109 modulefile, e.g. `setenv`, `prepend-path`)
110 - `modeval.tcl` — modulefile evaluation engine
111 - `modfind.tcl.in` — locating available/loaded modules
112 - `modscan.tcl` — modulefile scan / extra-match search
113 - `modspec.tcl` — module specification (name/version/variant) parsing
114 - `cache.tcl.in`, `coll.tcl.in` — module cache and collection management
115 - `envmngt.tcl.in` — environment variable manipulation
116 - `interp.tcl.in` — sub-interpreter management (modulefile sandboxing)
117 - `report.tcl.in` — all output/error/debug rendering
118 - `util.tcl` — generic helpers
119 - `syntaxdb.tcl` — generated Nagelfar syntax DB for linting (do not hand-edit)
120 - `init/` — per-shell init/wrapper scripts (`bash.in`, `csh.in`, `fish.in`,
121 `tcsh.in`, `zsh.in`, `pwsh.ps1.in`, `perl.pm.in`, `r.R.in`, `ruby.rb.in`,
122 `cmake.in`, ...) and shell completion scripts
123 (`bash_completion.in`, `fish_completion`, `tcsh_completion.in`,
124 `zsh-functions/_module.in`)
125 - `script/` — developer/maintainer tooling: `mt` (test runner), `mb`
126 (benchmark), `mlprof` (profiling), `mrel`/`mpub` (release), `pre-commit`/
127 `commit-msg` git hooks, `add.modules.in`, `modulecmd.in` wrapper
128 - `lib/` — optional C helper library (`envmodules.c`) used for things Tcl
129 can't do portably (e.g. group lookups); has its own `configure.ac`
130 - `testsuite/` — DejaGnu test suite; `.exp` files grouped by numbered
131 directory reflecting test category, e.g. `modules.00-init`,
132 `modules.50-cmds`, `modules.70-maint`, `modules.90-avail`,
133 `modules.92-spider`, `lint.00-init`, `install.00-init`. Each `.exp` file is
134 numbered/prefixed (e.g. `470-variant.exp`); `script/mt 50/470` targets it.
135 `modulefiles*/` subdirectories hold fixture modulefiles used by the tests.
136 Add fixture modulefiles for a *new* test under the highest-numbered
137 `modulefiles.N` directory (e.g. `modulefiles.4`; check for a higher one
138 first) rather than the default `modulefiles/` directory — many existing
139 tests (`aliases`, `avail`, `spider`, `scan_eval`, ...) enumerate a
140 modulepath's *entire* content, so adding to the heavily shared default dir
141 changes their expected output. Even a numbered dir gets referenced
142 wholesale by some tests and by filesystem-glob-order-dependent debug-trace
143 assertions elsewhere in the suite, so run the full test suite after adding
144 fixtures there and update any expected output it exposes — don't assume
145 isolation is complete just from picking the newest numbered directory.
146 - `share/` — Nagelfar syntax databases, RPM spec, logo assets
147 - `doc/source/` — Sphinx documentation source
148 - `design/` — design notes for individual features (one `.rst` per feature)
149 - `devel/` — maintainer/developer howtos, notably
150 `add-new-sub-command.rst` and `add-new-config-option.rst`, which give
151 the exact list of files to touch (core code, init/completion scripts,
152 Nagelfar syntax db, man pages, testsuite) when adding a sub-command or
153 config option — follow these when doing either task
154 - `changes.rst` — in-depth behavior/feature changes per major version
155 - `*.rst` at top level — man page sources (`module.rst`, `modulefile.rst`,
156 `modulecmd.rst`, `ml.rst`, `envml.rst`)
157
158 ## Coding conventions (Tcl)
159
160 - Max line length: 78 characters
161 - Indent with 3 spaces, no tabs
162 - Tcl minimal escaping style
163 - Procedure names: `lowerCamelCase`; variable names: `no_case_at_all`
164 - Brace/bracket placement:
165 ```tcl
166 if {![isStateDefined already_report]} {
167 setState already_report 1
168 }
169 ```
170 - No trailing whitespace, no misspellings (enforced by the `pre-commit`/
171 `commit-msg` hooks in `script/`, backed by `codespell` and `hunspell`)
172 - Code must remain compatible with Tcl 8.5+
173 - Comments must convey information the code cannot — see "Code comments" in
174 `CONTRIBUTING.rst` for the full guidelines (based on Ousterhout's
175 *A Philosophy of Software Design*)
176
177 ## Commit conventions
178
179 - Follow the "Commit message conventions" section in `CONTRIBUTING.rst` for
180 subject-line prefix/verb/length, body wrapping, and trailer order.
181 - Every commit needs a DCO `Signed-off-by:` trailer matching the committer's
182 git `user.name`/`user.email` — use `git commit -s`.
183 - Patches (bug fix or feature) should include tests, and the test should be
184 shown to fail without the patch.
185 - A commit body describes the change and why it is needed — never the
186 investigation or verification steps taken to produce it ("Verified
187 with `<command>`", "Confirmed via git archaeology"). If a verification
188 detail is essential to justify the change, state it as a plain
189 declarative fact about the change itself.
190 - Squash small follow-up commits that merely refine a change introduced
191 earlier on the same branch (typo fix, forgotten hunk, reworded sentence)
192 into the commit introducing that change, so each commit in the series
193 stands as a coherent change. Only rewrite commits not pushed yet.
194 - The project follows the Linux kernel's policy on AI coding assistants (see
195 "AI coding assistants" in `CONTRIBUTING.rst`): never add a
196 `Signed-off-by:` trailer on behalf of the AI — only the human committer
197 signs off — and disclose AI involvement with an `Assisted-by:` trailer,
198 e.g. `Assisted-by: Claude:claude-sonnet-5`.
199
200 ## Pull request descriptions
201
202 - Start the body directly with the prose or bullet list describing the
203 change — no "Summary" or any other heading, no test-plan section, no
204 "Generated with ..." tool attribution line.
205 - Do not hard-wrap the body to a column width — GitHub renders it as
206 Markdown and wraps paragraphs itself, so manual line breaks only produce
207 ragged text. The 72-column wrapping convention applies to commit
208 messages only.
209
210 ## Updating NEWS.rst
211
212 Add a new entry at the *end* of the current in-development version's bullet
213 list (immediately before the next `.. _X.Y release notes:` section marker),
214 not inserted by topic or alphabetically — entries are in the order changes
215 landed.
216
217 ## Adding a new `module` sub-command or config option
218
219 Don't improvise the file list — `doc/source/devel/add-new-sub-command.rst`
220 and `doc/source/devel/add-new-config-option.rst` enumerate, in order, every
221 file that needs a change: core Tcl (`main.tcl.in`/`subcmd.tcl.in` or
222 `init.tcl.in`), shell completion scripts, Nagelfar syntax db, man pages
223 (`doc/source/module.rst`, `modulefile.rst`), `doc/source/changes.rst`, and
224 the specific testsuite files/directories to extend. Read the relevant one
225 before starting either task.