..
   Copyright Spack Project Developers. See COPYRIGHT file for details.

   SPDX-License-Identifier: (Apache-2.0 OR MIT)

.. meta::
   :description lang=en:
      Learn how to configure and customize module file generation in Spack for Environment Modules and Lmod.

.. _modules:

Modules (modules.yaml)
======================

The use of module systems to manage user environments in a controlled way is a common practice at HPC centers that is sometimes embraced also by individual programmers on their development machines.
To support this common practice Spack integrates with `Environment Modules <http://modules.sourceforge.net/>`_ and `Lmod <http://lmod.readthedocs.io/en/latest/>`_ by providing post-install hooks that generate module files and commands to manipulate them.

Modules are one of several ways you can use Spack packages.
For other options that may fit your use case better, you should also look at :ref:`spack load <spack-load>` and :ref:`environments <environments>`.

Quick start
-----------

In the current version of Spack, module files are not generated by default.
To get started, you can generate module files for all currently installed packages by running either

.. code-block:: console

   $ spack module tcl refresh

or

.. code-block:: console

   $ spack module lmod refresh

Spack can also generate module files for all future installations automatically through the following configuration:

.. code-block:: console

   $ spack config add modules:default:enable:[tcl]

or

.. code-block:: console

   $ spack config add modules:default:enable:[lmod]

Assuming you have a module system installed, you should now be able to use the ``module`` command to interact with them:

.. code-block:: console

   $ module avail

   --------------------------------------------------------------- ~/spack/share/spack/modules/linux-ubuntu14-x86_64 ---------------------------------------------------------------
   autoconf/2.69-gcc-4.8-qextxkq       hwloc/1.11.6-gcc-6.3.0-akcisez             m4/1.4.18-gcc-4.8-ev2znoc                   openblas/0.2.19-gcc-6.3.0-dhkmed6        py-setuptools/34.2.0-gcc-6.3.0-fadur4s
   automake/1.15-gcc-4.8-maqvukj       isl/0.18-gcc-4.8-afi6taq                   m4/1.4.18-gcc-6.3.0-uppywnz                 openmpi/2.1.0-gcc-6.3.0-go2s4z5          py-six/1.10.0-gcc-6.3.0-p4dhkaw
   binutils/2.28-gcc-4.8-5s7c6rs       libiconv/1.15-gcc-4.8-at46wg3              mawk/1.3.4-gcc-4.8-acjez57                  openssl/1.0.2k-gcc-4.8-dkls5tk           python/2.7.13-gcc-6.3.0-tyehea7
   bison/3.0.4-gcc-4.8-ek4luo5         libpciaccess/0.13.4-gcc-6.3.0-gmufnvh      mawk/1.3.4-gcc-6.3.0-ostdoms                openssl/1.0.2k-gcc-6.3.0-gxgr5or         readline/7.0-gcc-4.8-xhufqhn
   bzip2/1.0.6-gcc-4.8-iffrxzn         libsigsegv/2.11-gcc-4.8-pp2cvte            mpc/1.0.3-gcc-4.8-g5mztc5                   pcre/8.40-gcc-4.8-r5pbrxb                readline/7.0-gcc-6.3.0-zzcyicg
   bzip2/1.0.6-gcc-6.3.0-bequudr       libsigsegv/2.11-gcc-6.3.0-7enifnh          mpfr/3.1.5-gcc-4.8-o7xm7az                  perl/5.24.1-gcc-4.8-dg5j65u              sqlite/3.8.5-gcc-6.3.0-6zoruzj
   cmake/3.7.2-gcc-6.3.0-fowuuby       libtool/2.4.6-gcc-4.8-7a523za              mpich/3.2-gcc-6.3.0-dmvd3aw                 perl/5.24.1-gcc-6.3.0-6uzkpt6            tar/1.29-gcc-4.8-wse2ass
   curl/7.53.1-gcc-4.8-3fz46n6         libtool/2.4.6-gcc-6.3.0-n7zmbzt            ncurses/6.0-gcc-4.8-dcpe7ia                 pkg-config/0.29.2-gcc-4.8-ib33t75        tcl/8.6.6-gcc-4.8-tfxzqbr
   expat/2.2.0-gcc-4.8-mrv6bd4         libxml2/2.9.4-gcc-4.8-ryzxnsu              ncurses/6.0-gcc-6.3.0-ucbhcdy               pkg-config/0.29.2-gcc-6.3.0-jpgubk3      util-macros/1.19.1-gcc-6.3.0-xorz2x2
   flex/2.6.3-gcc-4.8-yf345oo          libxml2/2.9.4-gcc-6.3.0-rltzsdh            netlib-lapack/3.6.1-gcc-6.3.0-js33dog       py-appdirs/1.4.0-gcc-6.3.0-jxawmw7       xz/5.2.3-gcc-4.8-mew4log
   gcc/6.3.0-gcc-4.8-24puqve           lmod/7.4.1-gcc-4.8-je4srhr                 netlib-scalapack/2.0.2-gcc-6.3.0-5aidk4l    py-numpy/1.12.0-gcc-6.3.0-oemmoeu        xz/5.2.3-gcc-6.3.0-3vqeuvb
   gettext/0.19.8.1-gcc-4.8-yymghlh    lua/5.3.4-gcc-4.8-im75yaz                  netlib-scalapack/2.0.2-gcc-6.3.0-hjsemcn    py-packaging/16.8-gcc-6.3.0-i2n3dtl      zip/3.0-gcc-4.8-rwar22d
   gmp/6.1.2-gcc-4.8-5ub2wu5           lua-luafilesystem/1_6_3-gcc-4.8-wkey3nl    netlib-scalapack/2.0.2-gcc-6.3.0-jva724b    py-pyparsing/2.1.10-gcc-6.3.0-tbo6gmw    zlib/1.2.11-gcc-4.8-pgxsxv7
   help2man/1.47.4-gcc-4.8-kcnqmau     lua-luaposix/33.4.0-gcc-4.8-mdod2ry        netlib-scalapack/2.0.2-gcc-6.3.0-rgqfr6d    py-scipy/0.19.0-gcc-6.3.0-kr7nat4        zlib/1.2.11-gcc-6.3.0-7cqp6cj

The names should look familiar, as they resemble the output from ``spack find``.
For example, you could type the following command to load the ``cmake`` module:

.. code-block:: console

   $ module load cmake/3.7.2-gcc-6.3.0-fowuuby

Neither of these is particularly pretty, easy to remember, or easy to type.
Luckily, Spack offers many facilities for customizing the module scheme used at your site.

Module file customization
-------------------------

The table below summarizes the essential information associated with the different file formats that can be generated by Spack:


+-----------+--------------+------------------------------+----------------------------------------------+----------------------+
|           | Hierarchical |  **Default root directory**  | **Default template file**                    | **Compatible tools** |
+===========+==============+==============================+==============================================+======================+
|  ``tcl``  | No           | share/spack/modules          | share/spack/templates/modules/modulefile.tcl | Env. Modules/Lmod    |
+-----------+--------------+------------------------------+----------------------------------------------+----------------------+
|  ``lmod`` | Yes          | share/spack/lmod             | share/spack/templates/modules/modulefile.lua | Lmod                 |
+-----------+--------------+------------------------------+----------------------------------------------+----------------------+


Spack ships with sensible defaults for the generation of module files, but you can customize many aspects of it to accommodate package or site specific needs.
In general you can override or extend the default behavior by:

1. overriding certain callback APIs in the Python packages
2. writing specific rules in the ``modules.yaml`` configuration file
3. writing your own templates to override or extend the defaults

The former method lets you express changes in the run-time environment that are needed to use the installed software properly, e.g. injecting variables from language interpreters into their extensions.
The latter two instead permit to fine tune the filesystem layout, content and creation of module files to meet site specific conventions.

.. _overide-api-calls-in-package-py:

Setting environment variables dynamically in ``package.py``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

There are two methods that you can implement in any ``package.py`` to dynamically affect the content of the module files generated by Spack.
The most important one is ``setup_run_environment``, which can be used to set environment variables in the module file that depend on the spec:

.. code-block:: python

   def setup_run_environment(self, env: EnvironmentModifications) -> None:
       if self.spec.satisfies("+foo"):
           env.set("FOO", "bar")

The second, less commonly used, is ``setup_dependent_run_environment(self, env, dependent_spec)``, which allows a dependency to set variables in the module file of its dependents.
This is typically used in packages like ``python``, ``r``, or ``perl`` to prepend the dependent's prefix to the search path of the interpreter (``PYTHONPATH``, ``R_LIBS``, ``PERL5LIB`` resp.), so it can locate the packages at runtime.

For example, a simplified version of the ``python`` package could look like this:

.. code-block:: python

   def setup_dependent_run_environment(
       self, env: EnvironmentModifications, dependent_spec: Spec
   ) -> None:
       if dependent_spec.package.extends(self.spec):
           env.prepend_path("PYTHONPATH", dependent_spec.prefix.lib.python)

and would make any package that ``extends("python")`` have its library directory added to the ``PYTHONPATH`` environment variable in the module file.
It's much more convenient to set this variable here, than to repeat it in every Python extension's ``setup_run_environment`` method.

.. _modules-yaml:

The ``modules.yaml`` config file and module sets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The configuration files that control module generation behavior are named ``modules.yaml``.
The default configuration looks like this:

.. literalinclude:: _spack_root/etc/spack/defaults/base/modules.yaml
   :language: yaml

You can define one or more **module sets**, each of which can be configured separately with regard to install location, naming scheme, inclusion and exclusion, autoloading, et cetera.

The default module set is aptly named ``default``.
All :ref:`Spack commands that operate on modules <maintaining-module-files>` apply to the ``default`` module set, unless another module set is specified explicitly (with the ``--name`` flag).


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

By default, an architecture-specific directory is added to the root directory.
A module set may override that behavior by setting the ``arch_folder`` config value to ``False``.

.. code-block:: yaml

   modules:
     default:
       roots:
         tcl: /path/to/install/tcl/modules
       arch_folder: false

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.

Automatically generating module files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Spack can be configured to automatically generate module files as part of package installation.
This is done by adding the desired module systems to the ``enable`` list.

.. code-block:: yaml

   modules:
     default:
       enable:
       - tcl
       - lmod

Configuring ``tcl`` and ``lmod`` modules
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can configure the behavior of either module system separately, under a key corresponding to the generator being customized:

.. code-block:: yaml

   modules:
     default:
       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 their content.
For the latter point it is possible to use anonymous specs to fine tune the set of packages on which the modifications should be applied.

.. _autoloading-dependencies:

Autoloading and hiding dependencies
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A module file should set the variables that are needed for an application to work.
But since an application often has many dependencies, where should all the environment variables for those be set?
In Spack the rule is that each package sets the runtime variables that are needed by the package itself, and no more.
This way, dependencies can be loaded standalone too, and duplication of environment variables is avoided.

That means however that if you want to use an application, you need to load the modules for all its dependencies.
Of course this is not something you would want users to do manually.

Since Spack knows the dependency graph of every package, it can easily generate module files that automatically load the modules for its dependencies recursively.
It is enabled by default for both Lmod and Environment Modules under the ``autoload: direct`` config option.
The former system has builtin support through the ``depends_on`` function, the latter simply uses a ``module load`` statement.
Both module systems (at least in newer versions) do reference counting, so that if a module is loaded by two different modules, it will only be unloaded after the others are.

The ``autoload`` key accepts the values:

* ``none``: no autoloading
* ``run``: autoload direct *run* type dependencies
* ``direct``: autoload direct *link and run* type dependencies
* ``all``: autoload all dependencies

In case of ``run`` and ``direct``, a ``module load`` triggers a recursive load.

The ``direct`` option is most correct: there are cases where pure link dependencies need to set variables for themselves, or need to have variables of their own dependencies set.

In practice however, ``run`` is often sufficient, and may make ``module load`` snappier.

The ``all`` option is discouraged and seldomly used.

A common complaint about autoloading is the large number of modules that are visible to the user.
Spack has a solution for this as well: ``hide_implicits: true``.
This ensures that only those packages you've explicitly installed are exposed by ``module avail``, but still allows for autoloading of hidden dependencies.
Lmod should support hiding implicits in general, while Environment Modules requires version 4.7 or higher.

.. note::
   If supported by your module system, we highly encourage the following configuration that enables autoloading and hiding of implicits.
   It ensures all runtime variables are set correctly, including those for dependencies, without overwhelming the user with a large number of available modules.
   Further, it makes it easier to get readable module names without collisions, see the section below on :ref:`modules-projections`.

   .. code-block:: yaml

       modules:
         default:
           tcl:
             hide_implicits: true
             all:
               autoload: direct # or `run`
           lmod:
             hide_implicits: true
             all:
               autoload: direct # or `run`

.. _anonymous_specs:

Setting environment variables for selected packages in config
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In the configuration file you can filter particular specs, and make further changes to the environment variables that go into their module files.
This is very powerful when you want to avoid :ref:`modifying the package itself <overide-api-calls-in-package-py>`, or when you want to set certain variables on multiple selected packages at once.

For instance, in the snippet below:

.. code-block:: yaml

   modules:
     default:
       tcl:
         # The keyword `all` selects every package
         all:
           environment:
             set:
               BAR: "bar"
         # This anonymous spec selects any package that
         # depends on mpi. The double colon at the
         # end clears the set of rules that matched so far.
         ^mpi::
           environment:
             prepend_path:
               PATH: "{^mpi.prefix}/bin"
             set:
               BAR: "baz"
         # Selects any zlib package
         zlib:
           environment:
             prepend_path:
               LD_LIBRARY_PATH: "foo"
         # Selects zlib compiled with gcc@4.8
         zlib%gcc@4.8:
           environment:
             unset:
             - FOOBAR

you are instructing Spack to set the environment variable ``BAR=bar`` for every module, unless the associated spec satisfies the abstract dependency ``^mpi`` in which case ``BAR=baz``, and the directory containing the respective MPI executables is prepended to the ``PATH`` variable.
In addition in any spec that satisfies ``zlib`` the value ``foo`` will be prepended to ``LD_LIBRARY_PATH`` and in any spec that satisfies ``zlib%gcc@4.8`` the variable ``FOOBAR`` will be unset.

.. admonition:: Note: order does matter
   :class: note

   The modifications associated with the ``all`` keyword are always evaluated first, no matter where they appear in the configuration file.
   All the other changes to environment variables for matching specs are evaluated from top to bottom.

.. warning::

   As general advice, it's often better to set as few unnecessary variables as possible.
   For example, the following seemingly innocent and potentially useful configuration

   .. code-block:: yaml

      all:
        environment:
          set:
            "{name}_ROOT": "{prefix}"

   sets ``BINUTILS_ROOT`` to its prefix in modules for ``binutils``, which happens to break the ``gcc`` compiler: it uses this variable as its default search path for certain object files and libraries, and by merely setting it, everything fails to link.

Exclude or include specific module files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can use anonymous specs also to prevent module files from being written or to force them to be written.
Consider the case where you want to hide from users all the boilerplate software that you had to build in order to bootstrap a new compiler.
Suppose for instance that ``gcc@4.4.7`` is the compiler provided by your system.
If you write a configuration file like:

.. code-block:: yaml

   modules:
     default:
       tcl:
         include: ["gcc", "llvm"]  # include will have precedence over exclude
         exclude: ["%gcc@4.4.7"]   # Assuming gcc@4.4.7 is the system compiler

you will prevent the generation of module files for any package that is compiled with ``gcc@4.4.7``, with the only exception of any ``gcc`` or any ``llvm`` installation.

It is safe to combine ``exclude`` and ``autoload`` :ref:`mentioned above <autoloading-dependencies>`.
When ``exclude`` prevents a module file to be generated for a dependency, the ``autoload`` feature will simply not generate a statement to load it.


.. _modules-projections:

Customize the naming of modules
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The names of environment modules generated by Spack are not always easy to fully comprehend due to the long hash in the name.
There are three module configuration options to help with that.
The first is a global setting to adjust the hash length.
It can be set anywhere from 0 to 32 and has a default length of 7.
This is the representation of the hash in the module file name and does not affect the size of the package hash.
Be aware that the smaller the hash length the more likely naming conflicts will occur.
The following snippet shows how to set hash length in the module file names:

.. code-block:: yaml

   modules:
     default:
       tcl:
         hash_length: 7

.. tip::

   Using ``hide_implicits: true`` (see :ref:`autoloading-dependencies`) vastly reduces the number modules exposed to the user.
   The hidden modules always contain the hash in their name, and are not influenced by the ``hash_length`` setting.
   Hidden implicits thus make it easier to use a short hash length or no hash at all, without risking name conflicts.

To help make module names more readable, and to help alleviate name conflicts with a short hash, one can use the ``suffixes`` option in the modules configuration file.
This option will add strings to modules that match a spec.
For instance, the following config options,

.. code-block:: yaml

   modules:
     default:
       tcl:
         all:
           suffixes:
             ^python@3: "python{^python.version.up_to_2}"
             ^openblas: "openblas"

will add a ``python3.12`` to module names of packages compiled with Python 3.12, and similarly for all specs depending on ``python@3``.
This is useful to know which version of Python a set of Python extensions is associated with.
Likewise, the ``openblas`` string is attached to any program that has ``openblas`` in the spec, most likely via the ``+blas`` variant specification.

The most heavyweight solution to module naming is to change the entire naming convention for module files.
This uses the projections format covered in :ref:`view_projections`.

.. code-block:: yaml

   modules:
     default:
       tcl:
         projections:
           all: "{name}/{version}-{compiler.name}-{compiler.version}-module"
           ^mpi: "{name}/{version}-{^mpi.name}-{^mpi.version}-{compiler.name}-{compiler.version}-module"

will create module files that are nested in directories by package name, contain the version and compiler name and version, and have the word ``module`` before the hash for all specs that do not depend on ``mpi``, and will have the same information plus the MPI implementation name and version for all packages that depend on ``mpi``.

When specifying module names by projection for Lmod modules, we recommend NOT including names of dependencies (e.g., MPI, compilers) that are already in the Lmod hierarchy.



.. note::

   Tcl and Lua modules also allow for explicit conflicts between module files.

   .. code-block:: yaml

      modules:
        default:
          enable:
          - tcl
          tcl:
            projections:
              all: "{name}/{version}-{compiler.name}-{compiler.version}"
            all:
              conflict:
              - "{name}"
              - "intel/14.0.1"

   will create module files that will conflict with ``intel/14.0.1`` and with the base directory of the same module, effectively preventing the possibility to load two or more versions of the same software at the same time.
   The tokens that are available for use in this directive are those understood by the :meth:`~spack.spec.Spec.format` method.

   For Lmod and Environment Modules versions prior to 4.2, it is important to express the conflict on both module files conflicting with each other.


.. admonition:: Note: Lmod hierarchical module files
   :class: note

   When ``lmod`` is activated Spack will generate a set of hierarchical lua module files that are understood by Lmod.
   The hierarchy always contains the ``Core`` and ``Compiler`` layers, but can be extended to include any package or virtual package in Spack.
   A case that could be useful in practice is for instance:

   .. code-block:: yaml

      modules:
        default:
          enable:
          - lmod
          lmod:
            core_compilers:
            - "gcc@4.8"
            core_specs:
            - "r"
            hierarchy:
            - "mpi"
            - "lapack"
            - "python"

   that will generate a hierarchy in which the ``python``, ``lapack`` and ``mpi`` layer can be switched independently.
   This allows a site to build the same libraries or applications against different implementations of ``mpi`` and ``lapack``, and with different versions of those implementations and of ``python``, and let Lmod switch safely from among the resulting installs.

   All packages built with a compiler in ``core_compilers`` and all packages that satisfy a spec in ``core_specs`` will be put in the ``Core`` hierarchy of the lua modules.

.. admonition:: Warning: consistency of core packages
   :class: warning

   The user is responsible for maintaining consistency among core packages, as ``core_specs`` bypasses the hierarchy that allows Lmod to safely switch between coherent software stacks.

.. admonition:: Warning: deep hierarchies
   :class: warning

   For hierarchies that are deeper than three layers ``lmod spider`` may have some issues.
   See `this discussion on the Lmod project <https://github.com/TACC/Lmod/issues/114>`_.

.. _customize-env-modifications:

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.

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

   modules:
     prefix_inspections:
       ./bin:
       - PATH
       ./man:
       - MANPATH
       ./:
       - CMAKE_PREFIX_PATH

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 manpages in ``man``, 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 ``MANPATH``.

The default list of environment variables in this config section includes ``PATH``, ``MANPATH``, ``ACLOCAL_PATH``, ``PKG_CONFIG_PATH`` and ``CMAKE_PREFIX_PATH``, as well as ``DYLD_FALLBACK_LIBRARY_PATH`` on macOS.
On Linux however, the corresponding ``LD_LIBRARY_PATH`` variable is *not* set, because it affects the behavior of system executables too.

.. note::

   In general, the ``LD_LIBRARY_PATH`` variable is not required when using packages built with Spack, thanks to the use of RPATH.
   Some packages may still need the variable, which is best handled on a per-package basis instead of globally, as explained in :ref:`overide-api-calls-in-package-py`.

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 view,
#. 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:
         root: /path/to/my/view
         projections:
           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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Modifications to certain environment variables in module files are there by default, for instance because they are generated by prefix inspections.
If you want to prevent modifications to some environment variables, you can do so by using the ``exclude_env_vars``:

.. code-block:: yaml

   modules:
     default:
       tcl:
         all:
           filter:
             # Exclude changes to any of these variables
             exclude_env_vars: ["CPATH", "LIBRARY_PATH"]

The configuration above will generate module files that will not contain modifications to either ``CPATH`` or ``LIBRARY_PATH``.

Select default modules
^^^^^^^^^^^^^^^^^^^^^^

By default, when multiple modules of the same name share a directory, the highest version number will be the default module.
This behavior of the ``module`` command can be overridden with a symlink named ``default`` to the desired default module.
If you wish to configure default modules with Spack, add a ``defaults`` key to your modules configuration:

.. code-block:: yaml

   modules:
     my-module-set:
       tcl:
         defaults:
         - gcc@10.2.1
         - hdf5@1.2.10+mpi+hl%gcc

These defaults may be arbitrarily specific.
For any package that satisfies a default, Spack will generate the module file in the appropriate path, and will generate a default symlink to the module file as well.

.. warning::

   If Spack is configured to generate multiple default packages in the same directory, the last modulefile to be generated will be the default module.

.. _maintaining-module-files:

Maintaining Module Files
------------------------

Each type of module file has a command with the same name associated with it.
The actions these commands permit are usually associated with the maintenance of a production environment.
Here's, for instance, a sample of the features of the ``spack module tcl`` command:

.. command-output:: spack module tcl --help

.. _cmd-spack-module-refresh:

Refresh the set of modules
^^^^^^^^^^^^^^^^^^^^^^^^^^

The subcommand that regenerates module files to update their content or their layout is ``refresh``:

.. command-output:: spack module tcl refresh --help

A set of packages can be selected using anonymous specs for the optional ``constraint`` positional argument.
Optionally the entire tree can be deleted before regeneration if the change in layout is radical.

.. _cmd-spack-module-rm:

Delete module files
^^^^^^^^^^^^^^^^^^^

If instead what you need is just to delete a few module files, then the right subcommand is ``rm``:

.. command-output:: spack module tcl rm --help

.. note::

   We care about your module files!
   Every modification done on modules that are already existing will ask for a confirmation by default.
   If the command is used in a script it is possible though to pass the ``-y`` argument, that will skip this safety measure.


.. _modules-in-shell-scripts:

Using Spack modules in shell scripts
------------------------------------

To enable additional Spack commands for loading and unloading module files, and to add the correct path to ``MODULEPATH``, you need to source the appropriate setup file.
Assuming Spack is installed in ``$SPACK_ROOT``, run the appropriate command for your shell:

.. code-block:: console

   # For bash/zsh/sh
   $ . $SPACK_ROOT/share/spack/setup-env.sh

   # For tcsh/csh
   $ source $SPACK_ROOT/share/spack/setup-env.csh

   # For fish
   $ . $SPACK_ROOT/share/spack/setup-env.fish

If you want to have Spack's shell support available on the command line at any login you can put this source line in one of the files that are sourced at startup (like ``.profile``, ``.bashrc`` or ``.cshrc``).
Be aware that the shell startup time may increase slightly as a result.

.. _cmd-spack-module-loads:

``spack module tcl loads``
^^^^^^^^^^^^^^^^^^^^^^^^^^

In some cases, it is desirable to use a Spack-generated module, rather than relying on Spack's built-in user-environment modification capabilities.
To translate a spec into a module name, use ``spack module tcl loads`` or ``spack module lmod loads`` depending on the module system desired.


To load not just a module, but also all the modules it depends on, use the ``--dependencies`` option.
This is not required for most modules because Spack builds binaries with RPATH support.
However, not all packages use RPATH to find their dependencies: this can be true in particular for Python extensions, which are currently *not* built with RPATH.

Scripts to load modules recursively may be made with the command:

.. code-block:: console

   $ spack module tcl loads --dependencies <spec>

An equivalent alternative using `process substitution <http://tldp.org/LDP/abs/html/process-sub.html>`_ is:

.. code-block:: console

   $ source <( spack module tcl loads --dependencies <spec> )


Module Commands for Shell Scripts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Although Spack is flexible, the ``module`` command is much faster.
This can become an issue when emitting a series of ``spack load`` commands inside a shell script.
By adding the ``--dependencies`` flag, ``spack module tcl loads`` may also be used to generate code that can be cut-and-pasted into a shell script.
For example:

.. code-block:: console

   $ spack module tcl loads --dependencies py-numpy git
   # bzip2@1.0.6%gcc@4.9.3=linux-x86_64
   module load bzip2/1.0.6-gcc-4.9.3-ktnrhkrmbbtlvnagfatrarzjojmkvzsx
   # ncurses@6.0%gcc@4.9.3=linux-x86_64
   module load ncurses/6.0-gcc-4.9.3-kaazyneh3bjkfnalunchyqtygoe2mncv
   # zlib@1.2.8%gcc@4.9.3=linux-x86_64
   module load zlib/1.2.8-gcc-4.9.3-v3ufwaahjnviyvgjcelo36nywx2ufj7z
   # sqlite@3.8.5%gcc@4.9.3=linux-x86_64
   module load sqlite/3.8.5-gcc-4.9.3-a3eediswgd5f3rmto7g3szoew5nhehbr
   # readline@6.3%gcc@4.9.3=linux-x86_64
   module load readline/6.3-gcc-4.9.3-se6r3lsycrwxyhreg4lqirp6xixxejh3
   # python@3.5.1%gcc@4.9.3=linux-x86_64
   module load python/3.5.1-gcc-4.9.3-5q5rsrtjld4u6jiicuvtnx52m7tfhegi
   # py-setuptools@20.5%gcc@4.9.3=linux-x86_64
   module load py-setuptools/20.5-gcc-4.9.3-4qr2suj6p6glepnedmwhl4f62x64wxw2
   # py-nose@1.3.7%gcc@4.9.3=linux-x86_64
   module load py-nose/1.3.7-gcc-4.9.3-pwhtjw2dvdvfzjwuuztkzr7b4l6zepli
   # openblas@0.2.17%gcc@4.9.3+shared=linux-x86_64
   module load openblas/0.2.17-gcc-4.9.3-pw6rmlom7apfsnjtzfttyayzc7nx5e7y
   # py-numpy@1.11.0%gcc@4.9.3+blas+lapack=linux-x86_64
   module load py-numpy/1.11.0-gcc-4.9.3-mulodttw5pcyjufva4htsktwty4qd52r
   # curl@7.47.1%gcc@4.9.3=linux-x86_64
   module load curl/7.47.1-gcc-4.9.3-ohz3fwsepm3b462p5lnaquv7op7naqbi
   # autoconf@2.69%gcc@4.9.3=linux-x86_64
   module load autoconf/2.69-gcc-4.9.3-bkibjqhgqm5e3o423ogfv2y3o6h2uoq4
   # cmake@3.5.0%gcc@4.9.3~doc+ncurses+openssl~qt=linux-x86_64
   module load cmake/3.5.0-gcc-4.9.3-x7xnsklmgwla3ubfgzppamtbqk5rwn7t
   # expat@2.1.0%gcc@4.9.3=linux-x86_64
   module load expat/2.1.0-gcc-4.9.3-6pkz2ucnk2e62imwakejjvbv6egncppd
   # git@2.8.0-rc2%gcc@4.9.3+curl+expat=linux-x86_64
   module load git/2.8.0-rc2-gcc-4.9.3-3bib4hqtnv5xjjoq5ugt3inblt4xrgkd

The script may be further edited by removing unnecessary modules.


Module Prefixes
^^^^^^^^^^^^^^^

On some systems, modules are automatically prefixed with a certain string; ``spack module tcl loads`` needs to know about that prefix when it issues ``module load`` commands.
Add the ``--prefix`` option to your ``spack module tcl loads`` commands if this is necessary.

For example, consider the following on one system:

.. code-block:: console

   $ module avail
   linux-SuSE11-x86_64/antlr/2.7.7-gcc-5.3.0-bdpl46y

   $ spack module tcl loads antlr    # WRONG!
   # antlr@2.7.7%gcc@5.3.0~csharp+cxx~java~python arch=linux-SuSE11-x86_64
   module load antlr/2.7.7-gcc-5.3.0-bdpl46y

   $ spack module tcl loads --prefix linux-SuSE11-x86_64/ antlr
   # antlr@2.7.7%gcc@5.3.0~csharp+cxx~java~python arch=linux-SuSE11-x86_64
   module load linux-SuSE11-x86_64/antlr/2.7.7-gcc-5.3.0-bdpl46y
