Separable module configuration -- without the bugs this time (#23703)

Currently, module configurations are inconsistent because modulefiles are generated with the configs for the active environment, but are shared among all environments (and spack outside any environment).

This PR fixes that by allowing Spack environments (or other spack config scopes) to define additional sets of modules to generate. Each set of modules can enable either lmod or tcl modules, and contains all of the previously available module configuration. The user defines the name of each module set -- the set configured in Spack by default is named "default", and is the one returned by module manipulation commands in the absence of user intervention.

As part of this change, the module roots configuration moved from the config section to inside each module configuration.

Additionally, it adds a feature that the modulefiles for an environment can be configured to be relative to an environment view rather than the underlying prefix. This will not be enabled by default, as it should only be enabled within an environment and for non-default views constructed with separate projections per-spec.

lib/spack/docs/environments.rst

@@ -723,6 +723,8 @@ Spack Environment managed views are updated every time the environment
 is written out to the lock file ``spack.lock``, so the concrete
 environment and the view are always compatible.
 
+.. _configuring_environment_views:
+
 """""""""""""""""""""""""""""
 Configuring environment views
 """""""""""""""""""""""""""""

lib/spack/docs/module_file_support.rst

@@ -71,9 +71,24 @@ Module file customization
 -------------------------
 
 Module files are generated by post-install hooks after the successful
-installation of a package. The table below summarizes the essential
-information associated with the different file formats
-that can be generated by Spack:
+installation of a package.
+
+.. note::
+
+   Spack only generates modulefiles when a package is installed. If
+   you attempt to install a package and it is already installed, Spack
+   will not regenerate modulefiles for the package. This may to
+   inconsistent modulefiles if the Spack module configuration has
+   changed since the package was installed, either by editing a file
+   or changing scopes or environments.
+
+   Later in this section there is a subsection on :ref:`regenerating
+   modules <cmd-spack-module-refresh>` that will allow you to bring
+   your modules to a consistent state.
+
+The table below summarizes the essential information associated with
+the different file formats that can be generated by Spack:
+
 
   +-----------------------------+--------------------+-------------------------------+----------------------------------------------+----------------------+
   |                             | **Hook name**      |  **Default root directory**   | **Default template file**                    | **Compatible tools** |
@@ -163,6 +178,46 @@ the installation folder of each package for the presence of a set of subdirector
 (``bin``, ``man``, ``share/man``, etc.). If any is found its full path is prepended
 to the environment variables listed below the folder name.
 
+Spack modules can be configured for multiple module sets. The default
+module set is named ``default``. All Spack commands which operate on
+modules default to apply the ``default`` module set, but can be
+applied to any module set in the configuration. Settings applied at
+the root of the configuration (e.g. ``modules:enable`` rather than
+``modules:default:enable``) are applied to the default module set for
+backwards compatibility.
+
+"""""""""""""""""""""""""
+Changing the modules root
+"""""""""""""""""""""""""
+
+As shown in the table above, the default module root for ``lmod`` is
+``$spack/share/spack/lmod`` and the default root for ``tcl`` is
+``$spack/share/spack/modules``. This can be overridden for any module
+set by changing the ``roots`` key of the configuration.
+
+.. code-block:: yaml
+
+   modules:
+     default:
+       roots:
+         tcl: /path/to/install/tcl/modules
+     my_custom_lmod_modules:
+       roots:
+         lmod: /path/to/install/custom/lmod/modules
+         ...
+
+This configuration will create two module sets. The default module set
+will install its ``tcl`` modules to ``/path/to/install/tcl/modules``
+(and still install its lmod modules, if any, to the default
+location). The set ``my_custom_lmod_modules`` will install its lmod
+modules to ``/path/to/install/custom/lmod/modules`` (and still install
+its tcl modules, if any, to the default location).
+
+Obviously, having multiple module sets install modules to the default
+location could be confusing to users of your modules. In the next
+section, we will discuss enabling and disabling module types (module
+file generators) for each module set.
+
 """"""""""""""""""""
 Activate other hooks
 """"""""""""""""""""
@@ -178,13 +233,14 @@ to the generator being customized:
 .. code-block:: yaml
 
    modules:
-     enable:
-       - tcl
-       - lmod
-     tcl:
-       # contains environment modules specific customizations
-     lmod:
-       # contains lmod specific customizations
+     default:
+       enable:
+         - tcl
+         - lmod
+       tcl:
+         # contains environment modules specific customizations
+       lmod:
+         # contains lmod specific customizations
 
 In general, the configuration options that you can use in ``modules.yaml`` will
 either change the layout of the module files on the filesystem, or they will affect
@@ -399,10 +455,16 @@ that are already in the LMod hierarchy.
 Customize environment modifications
 """""""""""""""""""""""""""""""""""
 
-You can control which prefixes in a Spack package are added to environment
-variables with the ``prefix_inspections`` section; this section maps relative
-prefixes to the list of environment variables which should be updated with
-those prefixes.
+You can control which prefixes in a Spack package are added to
+environment variables with the ``prefix_inspections`` section; this
+section maps relative prefixes to the list of environment variables
+which should be updated with those prefixes.
+
+The ``prefix_inspections`` configuration is different from other
+settings in that a ``prefix_inspections`` configuration at the
+``modules`` level of the configuration file applies to all module
+sets. This allows users to make general overrides to the default
+inspections and customize them per-module-set.
 
 .. code-block:: yaml
 
@@ -415,10 +477,66 @@ those prefixes.
       '':
         - CMAKE_PREFIX_PATH
 
-In this case, for a Spack package ``foo`` installed to ``/spack/prefix/foo``,
-the generated module file for ``foo`` would update ``PATH`` to contain
+Prefix inspections are only applied if the relative path inside the
+installation prefix exists. In this case, for a Spack package ``foo``
+installed to ``/spack/prefix/foo``, if ``foo`` installs executables to
+``bin`` but no libraries in ``lib``, the generated module file for
+``foo`` would update ``PATH`` to contain ``/spack/prefix/foo/bin`` and
+``CMAKE_PREFIX_PATH`` to contain ``/spack/prefix/foo``, but would not
+update ``LIBRARY_PATH``.
+
+There is a special case for prefix inspections relative to environment
+views. If all of the following conditions hold for a module set
+configuration:
+
+#. The configuration is for an :ref:`environment <environments>` and
+   will never be applied outside the environment,
+#. The environment in question is configured to use a :ref:`view
+   <filesystem-views>`,
+#. The :ref:`environment view is configured
+   <configuring_environment_views>` with a projection that ensures
+   every package is linked to a unique directory,
+
+then the module set may be configured to create modules relative to
+the environment view. This is specified by the ``use_view``
+configuration option in the module set. If ``True``, the module set is
+constructed relative to the default view of the
+environment. Otherwise, the value must be the name of the environment
+view relative to which to construct modules, or ``False-ish`` to
+disable the feature explicitly (the default is ``False``).
+
+If the ``use_view`` value is set in the config, then the prefix
+inspections for the package are done relative to the package's path in
+the view.
+
+.. code-block:: yaml
+
+   spack:
+     modules:
+       view_relative_modules:
+         use_view: my_view
+       prefix_inspections:
+         bin:
+           - PATH
+     view:
+       my_view:
+         projections:
+           root: /path/to/my/view
+           all:  '{name}-{hash}'
+
+The ``spack`` key is relevant to :ref:`environment <environments>`
+configuration, and the view key is discussed in detail in the section
+on :ref:`Configuring environment views
+<configuring_environment_views>`. With this configuration the
+generated module for package ``foo`` would set ``PATH`` to include
+``/path/to/my/view/foo-<hash>/bin`` instead of
 ``/spack/prefix/foo/bin``.
 
+The ``use_view`` option is useful when deploying a large software
+stack to users who are likely to inspect the modules to find full
+paths to software, when it is desirable to present the users with a
+simpler set of paths than those generated by the Spack install tree.
+
 """"""""""""""""""""""""""""""""""""
 Filter out environment modifications
 """"""""""""""""""""""""""""""""""""