| 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. |