doc: add manual page for modulecmd(1) command

xdelaruelle · xdelaruelle · commit 2db5640cc149 · 2026-01-21T07:18:08.000+01:00
Signed-off-by: Xavier Delaruelle &lt;xavier.delaruelle@cea.fr&gt;
diff --git a/Makefile b/Makefile
@@ -836,7 +836,8 @@ dist-tar: ChangeLog.gz share/rpm/environment-modules.spec pkgdoc
 		doc/build/MIGRATING.txt doc/build/changes.txt doc/build/INSTALL.txt \
 		doc/build/INSTALL-win.txt doc/build/NEWS.txt doc/build/CONTRIBUTING.txt \
 		doc/build/module.1.in doc/build/ml.1 doc/build/envml.1 \
-		doc/build/modulefile.5 share/rpm/environment-modules.spec
+		doc/build/modulecmd.1 doc/build/modulefile.5 \
+		share/rpm/environment-modules.spec
 
 dist-gzip: dist-tar
 	$(ECHO_GEN2) $(DIST_PREFIX).tar.gz
diff --git a/NEWS.rst b/NEWS.rst
@@ -47,6 +47,7 @@ Modules 5.7.0 (not yet released)
   variable. (fix issue #595 with contribution from Achim Gsell)
 * Install: reorder the options in the :file:`configure` script help message
   alphabetically.
+* Doc: add manual page for :ref:`modulecmd(1)` command.
 
 
 .. _5.6 release notes:
diff --git a/README.md b/README.md
@@ -103,7 +103,7 @@ type:
 
 The following man pages are provided:
 
-    module(1), ml(1), envml(1), modulefile(5)
+    module(1), ml(1), modulecmd(1), envml(1), modulefile(5)
 
 
 Test suite
diff --git a/configure b/configure
@@ -1034,7 +1034,7 @@ if [ -e "${builddocdir}/changes.txt" ] && [ -e "${builddocdir}/MIGRATING.txt" ]
    && [ -e "${builddocdir}/NEWS.txt" ] && [ -e "${builddocdir}/CONTRIBUTING.txt" ] \
    && [ -e "${builddocdir}/module.1.in" ] && [ -e "${builddocdir}/ml.1" ] \
    && [ -e "${builddocdir}/envml.1" ] && [ -e "${builddocdir}/modulefile.5" ] \
-   && [ "$oldbuilddoc" != 'y' ]; then
+   && [ -e "${builddocdir}/modulecmd.1" ] && [ "$oldbuilddoc" != 'y' ]; then
    builddoc=p
 # test sphinx availability otherwise
 else
diff --git a/doc/Makefile b/doc/Makefile
@@ -38,7 +38,7 @@ ALL_RST := $(filter-out $(SOURCE_DIR)/latex_index.rst, $(wildcard $(SOURCE_DIR)/
 ALL_TXT := $(patsubst $(SOURCE_DIR)/%,$(BUILD_DIR)/%,$(patsubst %.rst,%.txt,$(ALL_RST)))
 ALL_HTML := $(patsubst $(SOURCE_DIR)/%,$(BUILD_DIR)/%,$(patsubst %.rst,%.html,$(ALL_RST)))
 ALL_MAN := $(BUILD_DIR)/module.1 $(BUILD_DIR)/ml.1 $(BUILD_DIR)/envml.1\
-	$(BUILD_DIR)/modulefile.5
+	$(BUILD_DIR)/modulecmd.1 $(BUILD_DIR)/modulefile.5
 ALL_TEX := $(BUILD_DIR)/latex/modules.tex
 ALL_PDF := $(BUILD_DIR)/latex/modules.pdf
 
@@ -105,7 +105,8 @@ $(BUILD_DIR)/%.txt: $(SOURCE_DIR)/%.rst $(SOURCE_DIR)/version.py
 	$(ECHO_GEN2) $(ECHO_DIR_PREFIX)$(BUILD_DIR)/*.txt
 	$(SPHINXBUILD) $(SPHINXOPTS) -b text "$(SOURCE_DIR)" "$(BUILD_DIR)"
 
-$(BUILD_DIR)/module.1.in $(BUILD_DIR)/modulefile.5 $(BUILD_DIR)/ml.1 $(BUILD_DIR)/envml.1: $(ALL_RST) $(SOURCE_DIR)/version.py
+$(BUILD_DIR)/module.1.in $(BUILD_DIR)/modulefile.5 $(BUILD_DIR)/ml.1 $(BUILD_DIR)/modulecmd.1 $(BUILD_DIR)/envml.1: $(ALL_RST) $(SOURCE_DIR)/version.py
+	$(ECHO_GEN2) $(ECHO_DIR_PREFIX)$(BUILD_DIR)/modulecmd.1
 	$(ECHO_GEN2) $(ECHO_DIR_PREFIX)$(BUILD_DIR)/envml.1
 	$(ECHO_GEN2) $(ECHO_DIR_PREFIX)$(BUILD_DIR)/ml.1
 	$(ECHO_GEN2) $(ECHO_DIR_PREFIX)$(BUILD_DIR)/module.1.in
@@ -138,6 +139,7 @@ ifeq ($(docinstall),y)
 endif
 	$(INSTALL_DATA) $(BUILD_DIR)/module.1 '$(DESTDIR)$(mandir)/man1/'
 	$(INSTALL_DATA) $(BUILD_DIR)/ml.1 '$(DESTDIR)$(mandir)/man1/'
+	$(INSTALL_DATA) $(BUILD_DIR)/modulecmd.1 '$(DESTDIR)$(mandir)/man1/'
 	$(INSTALL_DATA) $(BUILD_DIR)/envml.1 '$(DESTDIR)$(mandir)/man1/'
 	$(INSTALL_DATA) $(BUILD_DIR)/modulefile.5 '$(DESTDIR)$(mandir)/man5/'
 
@@ -153,6 +155,7 @@ ifeq ($(docinstall),y)
 endif
 	rm -f '$(DESTDIR)$(mandir)/man1/module.1'
 	rm -f '$(DESTDIR)$(mandir)/man1/ml.1'
+	rm -f '$(DESTDIR)$(mandir)/man1/modulecmd.1'
 	rm -f '$(DESTDIR)$(mandir)/man1/envml.1'
 	rm -f '$(DESTDIR)$(mandir)/man5/modulefile.5'
 	rmdir '$(DESTDIR)$(mandir)/man1' '$(DESTDIR)$(mandir)/man5'
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -233,6 +233,7 @@ def get_version_release_from_git():
 rst_epilog += '.. |emph libexecdir| replace:: *%s*\n' % libexecdir
 rst_epilog += '.. |bold libexecdir| replace:: **%s**\n' % libexecdir
 rst_epilog += '.. |file libexecdir| replace:: :file:`%s`\n' % libexecdir
+rst_epilog += '.. |file bindir_modulecmd| replace:: :file:`%s/modulecmd`\n' % bindir
 rst_epilog += '.. |file libexecdir_modulecmd| replace:: :file:`%s/modulecmd.tcl`\n' % libexecdir
 rst_epilog += '.. |etcdir| replace:: %s\n' % etcdir
 rst_epilog += '.. |emph etcdir| replace:: *%s*\n' % etcdir
@@ -295,6 +296,7 @@ def get_version_release_from_git():
     ('module', 'module', u'command interface to the Modules package', [], 1),
     ('ml', 'ml', u'handy command interface to the Modules package', [], 1),
     ('modulefile', 'modulefile', u'files containing Tcl code for the Modules package', [], 5),
+    ('modulecmd', 'modulecmd', u'generic wrapper pointing to Modules execution engine', [], 1),
     ('envml', 'envml', u'run a command in an environment setting up by Modules', [], 1)
 ]
 
diff --git a/doc/source/envml.rst b/doc/source/envml.rst
@@ -99,4 +99,4 @@ shell function), :command:`envml` will print an error and exit.
 SEE ALSO
 --------
 
-:ref:`module(1)`, :ref:`ml(1)`, :ref:`modulefile(5)`
+:ref:`module(1)`, :ref:`modulecmd(1)`, :ref:`ml(1)`, :ref:`modulefile(5)`
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -202,6 +202,7 @@ or (at your option) any later version (`GPL-2.0-or-later`).
       ml
       module
       modulefile
+      modulecmd
       envml
 
    .. toctree::
diff --git a/doc/source/latex_index.rst b/doc/source/latex_index.rst
@@ -14,6 +14,7 @@ Introduction
 .. include:: module.rst
 .. include:: modulefile.rst
 .. include:: ml.rst
+.. include:: modulecmd.rst
 .. include:: envml.rst
 .. include:: MIGRATING.rst
 .. include:: NEWS.rst
diff --git a/doc/source/ml.rst b/doc/source/ml.rst
@@ -93,5 +93,5 @@ the list of supported environment variables.
 SEE ALSO
 --------
 
-:ref:`module(1)`, :ref:`modulefile(5)`, :ref:`envml(1)`
+:ref:`envml(1)`, :ref:`module(1)`, :ref:`modulecmd(1)`, :ref:`modulefile(5)`
 
diff --git a/doc/source/module.rst b/doc/source/module.rst
@@ -70,10 +70,10 @@ program and has the shell evaluate the command's output. The first argument to
 The initialization scripts are kept in |file initdir_shell| where
 *<shell>* is the name of the sourcing shell. For example, a C Shell user
 sources the |file initdir_csh| script. The sh, csh, tcsh, bash, ksh,
-zsh, fish and cmd shells are supported by :file:`modulecmd.tcl`. In addition,
-python, perl, ruby, tcl, cmake, r and lisp "shells" are supported which
-writes the environment changes to stdout as python, perl, ruby, tcl, lisp,
-r or cmake code.
+zsh, fish, cmd and pwsh shells are supported by :file:`modulecmd.tcl`. In
+addition, python, perl, ruby, tcl, cmake, r and lisp "shells" are supported
+which writes the environment changes to stdout as python, perl, ruby, tcl,
+lisp, r or cmake code.
 
 Initialization may also be performed by directly calling the
 :subcmd:`autoinit` sub-command of the :file:`modulecmd.tcl` program.
@@ -191,6 +191,8 @@ set is not checked.
 .. note:: Run-command files are intended to set parameters for modulefiles,
    not to configure the :command:`module` command itself.
 
+.. _Command line switches:
+
 Command line switches
 ^^^^^^^^^^^^^^^^^^^^^
 
@@ -5887,6 +5889,8 @@ ENVIRONMENT
  :subcmd:`config` sub-command.
 
 
+.. _module FILES:
+
 FILES
 -----
 
@@ -5956,9 +5960,13 @@ FILES
 
 |file libexecdir_modulecmd|
 
- The *modulefile* interpreter that gets executed upon each invocation
+ Modules execution engine, interpreting *modulefile* upon each invocation
  of :command:`module`.
 
+|file bindir_modulecmd|
+
+ Generic wrapper command pointing to Modules execution engine.
+
 |file initdir_shell|
 
  The Modules package initialization file sourced into the user's environment.
@@ -5967,5 +5975,5 @@ FILES
 SEE ALSO
 --------
 
-:ref:`ml(1)`, :ref:`modulefile(5)`, :ref:`envml(1)`
+:ref:`envml(1)`, :ref:`ml(1)`, :ref:`modulecmd(1)`, :ref:`modulefile(5)`
 
diff --git a/doc/source/modulecmd.rst b/doc/source/modulecmd.rst
@@ -0,0 +1,60 @@
+.. _modulecmd(1):
+
+modulecmd
+=========
+
+SYNOPSIS
+--------
+
+**modulecmd** *shell* [*switches*] [*sub-command* [*sub-command-args*]]
+
+DESCRIPTION
+-----------
+
+The :command:`modulecmd` command is a generic wrapper pointing to Modules
+execution engine :command:`modulecmd.tcl`.
+
+The :command:`modulecmd.tcl` command is the low-level execution engine of the
+Environment Modules system. It is responsible for evaluating modulefile
+logic and emitting shell-specific commands that modify the user's
+environment.
+
+Unlike the user-facing :command:`module` command, :command:`modulecmd.tcl`
+does not directly alter the environment. Instead, it writes shell code to
+standard output, which must be evaluated by the calling shell.
+
+The :command:`module` shell function or wrapper script invokes
+:command:`modulecmd.tcl` internally and evaluates its output to apply
+environment changes.
+
+The following shells are supported: sh, csh, tcsh, bash, ksh, zsh, fish, cmd,
+pwsh, python, perl, ruby, tcl, cmake, r and lisp.
+
+See the :ref:`modulecmd startup`, :ref:`command line switches` and
+:ref:`module sub-commands` sections in the :ref:`module(1)` man page.
+
+Direct invocation of :command:`modulecmd` is primarily intended for debugging
+and advanced usage. End users should normally use the :command:`module`
+command instead.
+
+EXIT STATUS
+-----------
+
+:command:`modulecmd` exits with ``0`` on successful execution. Otherwise ``1``
+is returned.
+
+ENVIRONMENT
+-----------
+
+See the :ref:`ENVIRONMENT<module ENVIRONMENT>` section in the :ref:`module(1)`
+man page.
+
+FILES
+-----
+
+See the :ref:`FILES<module FILES>` section in the :ref:`module(1)` man page.
+
+SEE ALSO
+--------
+
+:ref:`envml(1)`, :ref:`ml(1)`, :ref:`module(1)`, :ref:`modulefile(5)`
diff --git a/doc/source/modulefile.rst b/doc/source/modulefile.rst
@@ -2455,10 +2455,10 @@ See the :ref:`ENVIRONMENT<module ENVIRONMENT>` section in the
 SEE ALSO
 --------
 
-:ref:`module(1)`, :ref:`ml(1)`, :ref:`envml(1)`, :manpage:`Tcl(n)`,
-:manpage:`TclX(n)`, :manpage:`id(1)`, :manpage:`xrdb(1)`, :manpage:`exec(n)`,
-:manpage:`uname(1)`, :manpage:`domainname(1)`, :manpage:`tclvars(n)`,
-:manpage:`lsort(n)`, :manpage:`string(n)`
+:ref:`envml(1)`, :ref:`ml(1)`, :ref:`module(1)`, ref:`modulecmd(1)`,
+:manpage:`Tcl(n)`, :manpage:`TclX(n)`, :manpage:`id(1)`, :manpage:`xrdb(1)`,
+:manpage:`exec(n)`, :manpage:`uname(1)`, :manpage:`domainname(1)`,
+:manpage:`tclvars(n)`, :manpage:`lsort(n)`, :manpage:`string(n)`
 
 
 NOTES
diff --git a/share/rpm/environment-modules.spec.in b/share/rpm/environment-modules.spec.in
@@ -253,6 +253,7 @@ fi
 %{_mandir}/man1/envml.1.gz
 %{_mandir}/man1/ml.1.gz
 %{_mandir}/man1/module.1.gz
+%{_mandir}/man1/modulecmd.1.gz
 %{_mandir}/man5/modulefile.5.gz
 %{macrosdir}/macros.%{name}
 %{vimfiles_root}/ftdetect/modulefile.vim
