From 242406e9dbace53bc14751fa7e3672fd6b642380 Mon Sep 17 00:00:00 2001 From: Xavier Delaruelle Date: Sat, 23 Nov 2024 23:28:34 -0500 Subject: [PATCH] doc: desc. depends-on-any command in NEWS/man/changes Signed-off-by: Xavier Delaruelle --- NEWS.rst | 5 +++ doc/source/changes.rst | 3 ++ doc/source/design/extra-match-search.rst | 6 +++- doc/source/module.rst | 38 +++++++++++---------- doc/source/modulefile.rst | 42 +++++++++++++++--------- 5 files changed, 59 insertions(+), 35 deletions(-) diff --git a/NEWS.rst b/NEWS.rst index c4c13ffc..29208505 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -46,6 +46,11 @@ Modules 5.6.0 (not yet released) * Add :option:`--dumpname` option to report name of current Environment Modules implementation. Here it returns ``Modules``. This option is also available on Lmod starting version 8.7.50. +* Add the :mfcmd:`depends-on-any` modulefile command, alias over the + :mfcmd:`prereq` command for compatibility with Lmod Tcl modulefiles. +* Add ``depends-on-any`` extra specifier to query modulefile requirement + definitions. The extra specifier aliases ``prereq``, ``prereq-any`` or + ``require`` may also be used to query this modulefile command. .. _Security policy: https://github.com/envmodules/modules/blob/main/SECURITY.md .. _Modules chat room: https://matrix.to/#/#modules:matrix.org diff --git a/doc/source/changes.rst b/doc/source/changes.rst index ea3afee8..4050cd10 100644 --- a/doc/source/changes.rst +++ b/doc/source/changes.rst @@ -952,6 +952,7 @@ The following module sub-commands appeared on Modules 5. * ``use`` :ref:`extra specifier` is introduced. * setting :envvar:`MODULEPATH` environment variable with :mfcmd:`append-path` or :mfcmd:`prepend-path` may also be queried with ``use`` extra specifier. + * ``depends-on-any`` :ref:`extra specifier` is introduced. :subcmd:`reload` @@ -1027,6 +1028,8 @@ The following modulefile Tcl commands appeared on Modules 5. | 5.5 | :mfcmd:`hide-modulefile`, :mfcmd:`hide-version`, | | | :mfcmd:`lsb-release` | +------------+-----------------------------------------------------------------+ +| 5.6 | :mfcmd:`depends-on-any` | ++------------+-----------------------------------------------------------------+ :mfcmd:`system`, :mfcmd:`is-used` diff --git a/doc/source/design/extra-match-search.rst b/doc/source/design/extra-match-search.rst index 67030011..8c6027e2 100644 --- a/doc/source/design/extra-match-search.rst +++ b/doc/source/design/extra-match-search.rst @@ -199,12 +199,16 @@ specifiers and their associated modulefile command. +--------------------+-----------------------------------------+ | prereq | prereq, prereq-any, require | +--------------------+-----------------------------------------+ -| prereq-any | prereq-any, prereq, require | +| prereq-any | prereq-any, depends-on-any, prereq, | +| | require | +--------------------+-----------------------------------------+ | prereq-all | prereq-all, depends-on, require | +--------------------+-----------------------------------------+ | depends-on | depends-on, prereq-all, require | +--------------------+-----------------------------------------+ +| depends-on-any | depends-on-any, prereq-any, prereq, | +| | require | ++--------------------+-----------------------------------------+ | always-load | always-load, require | +--------------------+-----------------------------------------+ | conflict | conflict, incompat | diff --git a/doc/source/module.rst b/doc/source/module.rst index 38e9a2dd..95f82f26 100644 --- a/doc/source/module.rst +++ b/doc/source/module.rst @@ -2911,10 +2911,11 @@ Supported extra specifier *elements* are: * ``setenv``, ``unsetenv``, ``append-path``, ``prepend-path``, ``remove-path`` and ``pushenv``: these elements related to environment variable handling may also be aliased ``envvar`` -* ``prereq``, ``prereq-any``, ``prereq-all``, ``depends-on``, ``always-load``, - ``load``, ``load-any``, ``try-load``, ``switch`` and ``switch-on``: these - elements related to module requirement definition accept a module - specification as value *name* and may be aliased ``require`` +* ``prereq``, ``prereq-any``, ``prereq-all``, ``depends-on``, + ``depends-on-any``, ``always-load``, ``load``, ``load-any``, ``try-load``, + ``switch`` and ``switch-on``: these elements related to module requirement + definition accept a module specification as value *name* and may be aliased + ``require`` * ``conflict``, ``unload``, ``switch`` and ``switch-off``: these elements related to module incompatibility definition accept a module specification as value *name* and may be aliased ``incompat`` @@ -2923,15 +2924,16 @@ Supported extra specifier *elements* are: Each of the above supported *elements* corresponds to a Tcl modulefile command. ``load``, ``load-any``, ``try-load``, ``switch``, ``unload`` and ``use`` match corresponding module sub-commands. ``prereq-any`` is an alias on -``prereq`` and vice versa as both Tcl modulefile commands are the same. -Following the same trend ``prereq-all`` is an alias on ``depends-on`` and vice -versa. Regarding ``switch-off`` and ``switch-on`` elements they correspond -respectively to the module to unload (if specified) and the module to load on -a ``module switch`` command. ``switch`` is an alias that matches both -``switch-off`` and ``switch-on`` elements. ``require`` and ``incompat`` -*elements* do not match module commands where ``--not-req`` option is set. -Setting the ``MODULEPATH`` environment variable with ``append-path`` or -``prepend-path`` commands can be queried with ``use`` element. +``prereq``, ``depends-on-any`` and vice versa as both Tcl modulefile commands +are the same. Following the same trend ``prereq-all`` is an alias on +``depends-on`` and vice versa. Regarding ``switch-off`` and ``switch-on`` +elements they correspond respectively to the module to unload (if specified) +and the module to load on a ``module switch`` command. ``switch`` is an alias +that matches both ``switch-off`` and ``switch-on`` elements. ``require`` and +``incompat`` *elements* do not match module commands where ``--not-req`` +option is set. Setting the ``MODULEPATH`` environment variable with +``append-path`` or ``prepend-path`` commands can be queried with ``use`` +element. When several *names* are set on one *element* criterion (e.g., ``env:PATH,LD_LIBRARY_PATH``), they act as an *OR* operation. Which means @@ -2975,7 +2977,7 @@ if an unknown extra specifier *element* is defined in search query. not matching specified names .. versionchanged:: 5.6 - Extra specifier ``use`` added + Extra specifiers ``use`` and ``depends-on-any`` added .. _Module tags: @@ -3018,10 +3020,10 @@ meaning: The :option:`--tag` option helps to apply additional tags to modules. It is available on :subcmd:`load`, :subcmd:`load-any`, :subcmd:`switch` and :subcmd:`try-load` sub-commands and on :mfcmd:`always-load`, -:mfcmd:`depends-on`, :mfcmd:`module`, :mfcmd:`prereq`, :mfcmd:`prereq-all` and -:mfcmd:`prereq-any` modulefile commands. In case the designated module is -already loaded, the additional tags are added to the list of tags already -applied to this module. +:mfcmd:`depends-on`, :mfcmd:`depends-on-any`, :mfcmd:`module`, +:mfcmd:`prereq`, :mfcmd:`prereq-all` and :mfcmd:`prereq-any` modulefile +commands. In case the designated module is already loaded, the additional tags +are added to the list of tags already applied to this module. Module tags are reported along the module they are associated to on :subcmd:`avail` and :subcmd:`list` sub-command results and also when module's diff --git a/doc/source/modulefile.rst b/doc/source/modulefile.rst index 5e06e85c..97132822 100644 --- a/doc/source/modulefile.rst +++ b/doc/source/modulefile.rst @@ -242,6 +242,14 @@ the *modulefile* is being loaded. .. versionchanged:: 5.5 Option ``--modulepath`` added +.. mfcmd:: depends-on-any [options] modulefile... + + Alias of :mfcmd:`prereq` command. + + .. only:: html + + .. versionadded:: 5.6 + .. mfcmd:: exit [N] This is not a modules specific command but another overloaded Tcl command @@ -1956,13 +1964,14 @@ requirement. The latter means specified modulefiles should not be loaded for the modulefile that express the conflict to be loaded too. Pre-requirement could be expressed with :mfcmd:`prereq`, :mfcmd:`prereq-any`, -:mfcmd:`prereq-all`, :mfcmd:`depends-on`, :mfcmd:`always-load`, -:mfcmd:`module load`, :mfcmd:`module switch`, -:mfcmd:`module try-load` or :mfcmd:`module load-any` -modulefile commands. When the :mconfig:`auto_handling` configuration option is -disabled, required modulefile should be manually loaded prior their dependent -modulefile when expressed with the :mfcmd:`prereq`, :mfcmd:`prereq-any`, -:mfcmd:`prereq-all` or :mfcmd:`depends-on` modulefile commands. For other +:mfcmd:`prereq-all`, :mfcmd:`depends-on`, :mfcmd:`depends-on-any`, +:mfcmd:`always-load`, :mfcmd:`module load`, +:mfcmd:`module switch`, :mfcmd:`module try-load` or +:mfcmd:`module load-any` modulefile commands. When the +:mconfig:`auto_handling` configuration option is disabled, required modulefile +should be manually loaded prior their dependent modulefile when expressed with +the :mfcmd:`prereq`, :mfcmd:`prereq-any`, :mfcmd:`prereq-all`, +:mfcmd:`depends-on` or :mfcmd:`depends-on-any` modulefile commands. For other commands or when :mconfig:`auto_handling` is enabled, pre-required modulefiles are automatically loaded. @@ -2006,12 +2015,13 @@ with the :mfcmd:`module` command will attempt to load or unload the designated modulefile but it will not mark them as pre-requirement or conflict. Adding the ``--optional`` option on :mfcmd:`prereq`, :mfcmd:`prereq-any`, -:mfcmd:`prereq-all`, :mfcmd:`depends-on` or :mfcmd:`always-load` modulefile -commands declares the pre-requirement as optional. If an optional -pre-requirement is not found loaded or cannot be automatically loaded, the -dependency expressed is yet considered satisfied. When an optional requirement -is loaded afterward, the dependent module will get automatically reloaded if -the :mconfig:`auto_handling` configuration option is enabled. +:mfcmd:`prereq-all`, :mfcmd:`depends-on`, :mfcmd:`depends-on-any` or +:mfcmd:`always-load` modulefile commands declares the pre-requirement as +optional. If an optional pre-requirement is not found loaded or cannot be +automatically loaded, the dependency expressed is yet considered satisfied. +When an optional requirement is loaded afterward, the dependent module will +get automatically reloaded if the :mconfig:`auto_handling` configuration +option is enabled. By adding the :option:`--force` option to the :command:`module` command when loading or unloading modulefile, the consistency checks are by-passed. This @@ -2108,9 +2118,9 @@ on Modules whereas on Lmod it is equivalent to the :mfcmd:`prereq-all` command. If the :mconfig:`auto_handling` configuration option is disabled, the -requirements defined with the :mfcmd:`depends-on` command are not -automatically loaded and an error is raised if none of these requirements are -found loaded. +requirements defined with the :mfcmd:`depends-on` or :mfcmd:`depends-on-any` +commands are not automatically loaded and an error is raised if none of these +requirements are found loaded. If the :mconfig:`auto_handling` or :mconfig:`conflict_unload` configuration options are disabled, the conflicts defined with the :mfcmd:`family` command