Idea: seamless stacking of multiple module hierarchies, use cases:

• develop/build new modules without exposing them to other users

• transparent/seamless support for modules optimised for certain CPUs

• modules for HPC systems like slurm and required software to support HPC hardware.

• modules on another filesystem or location than the default (@PSI: /opt/psi)

• …​

Overlays can be stacked. The first overlay - the overlay at the bottom of the stack - is called "base overlay". Multiple loaded overlays are organised as stack. Loading an overlay pushes it on top of the stack. It is only possible to unload the overlay on top of the stack.

The 'overlay' at the bottom of the stack is called the base overlay and cannot be unloaded.

The relative directory structure of a hierarchy group must be identical to the base overlay. It is also not possible to define a new hierarchical group.

Overlays must be loaded before the first module.

Unloading an overlay is only possible if no modules are loaded.

Note: an overlay can add new non-hierarchical groups.

1.4.1. Definition

1.4.2. Overlay definition files

---
overlays:
  name_of_overlay:
    root_dir: <DIR>
    modulefiles_root_dir: <DIR>
    type: normal|hidding|replacing
  ...

normal

In an overlay of this types the modules in the overlay are added to the already available modules provided by the overlays on the stack. If modules with identical name/version exist in multiple overlays, the module from the overlay which is higher on the stack is used. In other words modules with identical name/version are replaced by overlays loaded later.

Example: Assume we have the overlays base and private. In the base overlay are the modules git/2.33.1, gnuplot/5.4.0 and gnuplot/5.4.2 in the group Tools. In private overlay are the modules gnuplot/5.4.2 and gnuplot/5.4.3 (maybe compiled with a different configuration).

After loading the private overlay the following Gnuplot modules are available:

• git/2.33.1`and `gnuplot/5.4.0 from the base overlay

• gnuplot/5.4.2 and gnuplot/5.4.3 from the private overlay

  Note: the module gnuplot/5.4.2 from the base overlay has been replaced by the module with the same name from the private overlay.

hiding

An overlay of this types hides all modules with the same name in previous loaded overlays.

Example: Assume we have the same overlays and Gnuplot modules as in the example above.

After loading the private overlay with type hiding the following Gnuplot modules are available:

• git/2.33.1 from the base overlay

• gnuplot/5.4.2 and gnuplot/5.4.3 from the private overlay

  Note: the Gnuplot modules from the base overlay are hidden!

replacing

A overlay of this types replaces hole groups.

Example: If you load the private overlay from the examples above as replacing, the following modules are available in the group Tools:

• gnuplot/5.4.2 and gnuplot/5.4.3 from the private overlay

  Note: the Git module from the base overlay is not available any more.

With the implementation of overlays a new format for the so called variant files is necessary. In the old format extensions are almost impossible. Nowadays a common format used for configuration files is YAML.

1.6.1. YAML format of variant files

---
defaults:
  overlay: <overlay-name>
module_name/module_version:
  variants:
  - relstage: <release-stage>
    use_flags: <flags>
    overlay: <overlay-name>
    dependencies:
    - dependency_1
    - dependency_2
    - ...
...

module_name:
  rel_stage: <release-stage>
  use_flags: <use-flags>
  overlay: <overlay>
  versions:
    <id-1>:                           #
      rel_stage: <release-stage>
      use_flags: <use-flags>
      overlay: <overlay>
      version: <version>
      dependencies:
        - dependency1
        - ...
    <id-2>:
   ...

1.6.2. Variants file and overlays