doc: add provide design notes

Signed-off-by: Xavier Delaruelle <[email protected]>

Author: xdelaruelle

NEWS.rst

@@ -174,6 +174,7 @@ Modules 5.6.0 (not yet released)
   options. When set, module aliases are included into the output and the
   *extra match search* mechanism is activated to scan modulefiles to get the
   module aliases they define.
+* Doc: add :ref:`provide` design notes.
 
 .. _Security policy: https://github.com/envmodules/modules/blob/main/SECURITY.md
 .. _Modules chat room: https://matrix.to/#/#modules:matrix.org

doc/source/design/extra-match-search.rst

@@ -37,7 +37,7 @@ by default on Modules v5 and enabled by default on v6.
 What triggers an extra match search?
 ------------------------------------
 
-* module variants should be reported
+* module variants or provided module aliases should be reported
 * variant is specified in query on :subcmd:`avail`, :subcmd:`paths`,
   :subcmd:`spider` or :subcmd:`whatis`
 * an extra specifier is specified in query

doc/source/design/lmod-tcl-modulefile-compat.rst

@@ -74,20 +74,17 @@ Lmod Tcl modulefile compatibility
   - Not used to load the modulefile declaring them when an extension name is
     passed to ``load`` sub-command or ``depends-on`` modulefile command
 
-- This command will be first implemented as a no-operation command (``nop``)
+- This command was first implemented as a no-operation command (``nop``) in
+  Modules 5.1
 
   - No error raised if used
   - And no warning message to avoid polluting output
 
 - This command is intended for use only within modulefile evaluation context
   (not within modulerc)
 
-- *FUTURE*: may be interesting to improve the concept by making the extension
-  names an alias on the modulefile declaring them
-
-  - Will automatically achieve dependency consistency this way
-  - Could resolve dependencies based on extension names if modulefile is
-    evaluated during an ``avail``
+- Starting Modules 5.6, this command is made an alias onto :mfcmd:`provide`
+  modulefile command. See :ref:`provide` for details.
 
 
 ``prereq-any``

doc/source/design/provide.rst

@@ -0,0 +1,60 @@
+.. _provide:
+
+provide modulefile command
+==========================
+
+This design document describes the :mfcmd:`provide` Tcl command that defines
+one or multiple module aliases targeting currently evaluating module.
+
+Command specification
+---------------------
+
+The command has following syntax::
+
+    provide modulefile...
+
+Each modulefile argument corresponds to a module alias to define onto current
+modulefile. At least one argument should be provided, an error is raised
+otherwise. Modulefile specification should correspond to a module name and
+version. Variant cannot be specified. Each individual string is interpreted as
+a module name and version.
+
+This command is only available in modulefile evaluation contexts.
+
+``provide`` command is only effective during ``load`` evaluations. It
+corresponds to a *no-operation* on other evaluation modes.
+
+``provide`` only defines aliases, thus ``conflict`` definitions are expected
+to avoid these names to be provided by several loaded modules.
+
+extensions modulefile command
+-----------------------------
+
+The :mfcmd:`extensions` modulefile command introduced by Lmod is now
+implemented as a bare command alias onto :mfcmd:`provide`.
+
+Provided alias
+--------------
+
+Module alias defined with ``provide`` command are not distinguished from other
+aliases defined with ``family`` or ``module-alias``. These aliases are
+recorded in :envvar:`__MODULES_LMALTNAME` with `al` type like other aliases.
+
+It appears easier for the user to only face one kind of element (alias) rather
+requiring them to learn multiple concepts (family, extensions, alias). All of
+this is just different names applying to a given modulefile.
+
+A new item for output configuration is introduced: ``provided-alias``. It adds
+module aliases information into the generated output and enables the
+evaluation of modulefiles to fetch aliases provided by them (i.e., defined
+within them by ``provide`` or ``family`` modulefile commands).
+``provided-alias`` implies ``alias`` item.
+
+A given provided alias may be defined by several modulefiles. When reported
+first defined target is retained. Which means that first scanned modulefile
+wins.
+
+*FUTURE*: keep all target definitions to be able to report all of them if
+asked.
+
+.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: