Lmod Glossary

This glossary defines key terms, components, and concepts used within the Lmod codebase and documentation.

Cosmic

A singleton module in Lmod responsible for managing global configuration values and Lmod’s internal state or settings. It provides a centralized interface (e.g., cosmic:value(), cosmic:assign()) to get, set, and initialize these parameters, many of which are derived from environment variables (e.g., LMOD_SITE_NAME, LMOD_TRACING) or Lmod’s configuration files. It acts as a central access point for global settings throughout the Lmod codebase.

DirTree

A class/module in Lmod that scans module file directory structures (as defined by MODULEPATH). It builds a representation of the available modules by traversing these directories, identifying modulefiles, and noting associated version or .modulerc files. This hierarchical tree of directories and modulefiles is then utilized by other Lmod components, such as MName and ModuleA, to discover, locate, and understand the available software modules.

FrameStk

(Frame Stack) A singleton class managing a stack of “frames,” where each frame typically represents the evaluation context of a currently processing modulefile. This stack is crucial for Lmod to:

  1. Track the nesting depth of modulefile evaluations (e.g., module A loading module B).

  2. Provide access to context-specific data, such as the relevant MT (Module Table) or VarT (Variable Table) for the active module.

  3. Implement control flow operations within modulefiles, such as the break command, by allowing Lmod to unwind or alter the evaluation sequence based on the current stack state.

  4. Offer traceback capabilities for debugging or error reporting.

Common operations include push() when entering a module context and pop() when exiting.

For a detailed explanation of its role in state management, see FrameStk: The Engine of Reversible State.

Hub

A central singleton object, with its logic primarily defined in src/Hub.lua. It acts as the main engine for Lmod’s operations concerning modules. Its responsibilities include:

  1. Orchestrating the loading (hub:load()) and unloading (hub:unload()) of modules.

  2. Enforcing Lmod’s rules during these operations, such as handling already loaded modules, checking for conflicts, and managing dependencies (hub:dependencyCk()).

  3. Providing information about modules, such as listing available modules (hub:avail()) or their overview (hub:overview()).

  4. Managing the overall module state, including reloading all modules (hub:reloadAll()) or refreshing the shell aiases and functions (hub:refresh()).

It is called by MainControl methods (e.g., M.load() calls hub:load()) and is a critical component in the sequence of actions Lmod takes to manage the user’s environment.

l_usrLoad()

A local Lua function defined within src/cmdfuncs.lua, specifically as a helper function called by Load_Usr(). Its primary responsibilities are:

  1. To process the array of module name arguments (argA) passed from the command line.

  2. To distinguish between modules to be loaded and modules to be unloaded (those prefixed with a minus sign), sorting them into separate internal lists.

  3. To convert these module name strings (e.g., “foo/1.0”) into MName objects, which are Lmod’s internal representation for modules.

  4. It accepts a check_must_load boolean parameter, which dictates whether Lmod should verify at the end of the process if all requested modules were successfully loaded.

LMOD_CMD

An environment variable that stores the absolute path to the main Lmod executable script (typically named lmod). This variable is essential for the correct functioning of the module command. Shell initialization scripts (e.g., for bash, tcsh, zsh) use $LMOD_CMD to define the module shell function or alias, which then calls the Lmod executable, passing user commands and arguments to it. For example, in bash, the module function is often defined like: module () { eval "$($LMOD_CMD shell "$@")"; }. It must be correctly set in the user’s environment for Lmod to be invoked.

lmodCmdA

A Lua table defined in the lmod.in.lua script. It serves as a primary dispatch table for Lmod, mapping user-provided command strings (e.g., “load”, “avail”, “list”, “purge”) to internal Lmod data structures or function entry points. When a user issues a module <command> ... instruction, Lmod consults lmodCmdA to find the entry corresponding to <command>. This entry then directs Lmod to the appropriate internal table (like loadTbl) or function (like Load_Usr() found in src/cmdfuncs.lua) responsible for handling that specific action.

Load_Usr()

A function defined in src/cmdfuncs.lua that serves as the primary entry point for handling user-initiated module load commands (and similar commands like module try-load). Its main sequence of operations includes:

  1. Receiving the module names and any options specified by the user on the command line.

  2. Calling the local helper function l_usrLoad() to parse these arguments. l_usrLoad() separates them into lists of modules to load and unload, and converts the names into MName objects. It is typically called with check_must_load set to true for standard loads.

  3. Invoking mcp:load_usr(lA) (where mcp is the Main Control Program object and lA is the list of MName objects to load), which then delegates to M.load_usr() in src/MainControl.lua to continue the loading process.

loadModuleFile()

A function defined in src/loadModuleFile.lua that is responsible for the direct processing and evaluation of an individual modulefile. Its key tasks include:

  1. Reading the entire content of the specified modulefile.

  2. Detecting if the modulefile is a TCL-based module. If so, it invokes the runTCLprog() routine to convert the TCL commands into an equivalent Lua script.

  3. Taking the modulefile content (which is now guaranteed to be Lua code, either originally or after conversion) and evaluating it within a controlled environment using the sandbox() mechanism. The sandbox() restricts the Lmod and Lua functions available to the modulefile.

It is primarily called from src/Hub.lua during module loading but also used by other tools that need to interpret modulefile content.

loadTbl

A Lua table defined in src/lmod.in.lua that acts as a configuration and dispatch target for module loading commands. Entries in the main command dispatch table, lmodCmdA (for user commands like “load”, “add”, etc.), point to loadTbl via their action field. The loadTbl itself contains properties relevant to the load operation, most importantly a cmd field that holds a direct reference to the primary function responsible for handling the load request, which is Load_Usr() (located in src/cmdfuncs.lua). It may also contain other metadata like name (for debugging/identification) and checkMPATH (a boolean indicating if MODULEPATH needs to be checked).

LocationT

A class (defined in src/LocationT.lua) that creates a tructured representation of module locations when the module tree is completely N/V or C/N/V and not N/V/V. It is typically initialized with data derived from ModuleA (which itself is built from DirTree’s scan of MODULEPATH). LocationT’s primary purpose is to provide an efficient way to search for modules (via its LocationT:search(name) method) and to help MName objects resolve a given module name string (which might follow various conventions like Name/Version, Category/Name/Version) to its canonical file path and associated properties. It achieves this by abstracting the complexities of different directory layouts found across various module trees, effectively creating a readily searchable map or index.

mcp

(Main Control Program) The mcp (Main Control Program) is the primary stateful object that orchestrates Lmod’s behavior for a given user command. It is an instance of the MainControl class (defined in src/MainControl.lua). The mcp object is typically created using MainControl.build("mode"), where "mode" (e.g., “load”, “unload”, “spider”, “avail”, “help”) determines its operational context. Key characteristics and roles:

  1. State Management: The mode with which mcp is initialized dictates how subsequent operations are handled. For example, if a modulefile command like prepend_path() is encountered, the mcp object’s internal logic (based on its mode) will dispatch this to the appropriate underlying MainControl method, such as M.prepend_path if in “load” mode, or M.remove_path if in “unload” mode.

  2. Method Dispatch: It provides the core methods (like mcp:load_usr(), mcp:setenv(), mcp:prepend_path()) that are called by higher-level functions (in src/modfuncs.lua or src/cmdfuncs.lua). These mcp methods then delegate to the actual implementation methods (e.g., M.load_usr(), M.setenv()) within the MainControl class, tailored to the current mode.

  3. Central Orchestration: It ties together various components by holding references or providing access to other key Lmod objects and data structures necessary for the current operation.

The mcp global variable is in the current mode (i.e. load, unload, show, etc). MCP is always in load mode and MCPQ is always in quiet mode.

MName

An MName (Module Name) object is Lmod’s primary internal representation of a module. These objects are created from user-provided module name strings (e.g., “gcc/9.3.0”, “tacc”) or from other internal representations. MName objects are defined in src/MName.lua. Key characteristics and roles:

  1. Encapsulation: An MName object encapsulates various properties of a module, including its user-specified name, its canonical short name (:sn()), full name (:fullName()), version (:version()), and the resolved path to its modulefile (:fn()).

  2. Resolution: It contains the logic to resolve a potentially ambiguous module name string into a specific modulefile on the filesystem. This process involves interacting with other Lmod components like ModuleA (for collections of modules, mainly when a module tree is N/V/V ), and LocationT (for location indexing and handling different naming schemes like N/V, C/N/V).

  3. State & Validation: MName objects can report on the module’s status, such as whether it’s currently loaded (:isloaded()) or if it’s a valid, findable module (:valid()).

  4. Operations: They are used extensively throughout Lmod. For example, lists of MName objects are passed to functions like hub:load() and mcp:load_usr() to specify which modules to act upon. Modulefile commands like prereq or conflict also operate on MName objects.

Instantiation typically occurs via methods like MName:new(type, name, ...) or MName:buildA(type, argTable).

ModuleA

ModuleA (Module Array) is a class, defined in src/ModuleA.lua, that represents the entire collection of available modules discovered by Lmod from the MODULEPATH. It is typically used as a singleton within Lmod’s operations. Key characteristics and roles:

  1. Data Source: It acts as a primary, structured source of information about all known modules. It’s initialized by processing the MODULEPATH directories, using DirTree to scan the filesystem and identify modulefiles and their organization.

  2. Module Discovery: Provides methods like :search(name) to find modules, and :defaultT() to get information about default module versions.

  3. Information Provider: Supplies data for commands like module avail (via :build_availA()) and for internal checks, such as determining if a module path follows a Name/Version/Version (:isNVV()) convention.

  4. Interaction: ModuleA’s data is used by LocationT to build its searchable index, and MName objects query ModuleA (often via LocationT) to resolve names to specific modulefile paths and properties.

  5. Caching: It can incorporate spider cache information (spider_cache=true) to speed up discovery if available.

It’s instantiated using ModuleA:__new({mpathA}, maxdepthT) or more commonly accessed via ModuleA:singleton{spider_cache=...}.

MT

(Module Table) MT (Module Table) is a central Lmod data structure, defined in src/MT.lua, that represents the current state of the user’s environment in terms of loaded modules. It acts as a live record of which modules are loaded, their properties, and how they were loaded. Key characteristics and roles:

  1. State Tracking: It stores detailed information for each loaded module, including its short name (sn), full name, user-specified name, version, filename (:fn()), status (e.g., “active”, “inactive”, “pending” via :setStatus(), :status(), :have()), load order, and any associated properties.

  2. Environment Representation: It maintains the current MODULEPATH array (:modulePathA()) and other environment-related settings derived from module operations.

  3. Query Interface: Provides numerous methods to query the state of loaded modules, such as listing modules (:list()), checking if a module is loaded (:have()), retrieving a module’s filename or version.

  4. Modification Interface: Offers methods to modify the state, such as adding a module (:add()), changing its status, or marking it as directly loaded by the user (:userLoad()).

  5. Serialization: Can serialize its contents (e.g., via :serializeTbl()), which is crucial for Lmod to pass its state back to the shell for environment updates (e.g., by setting LOADEDMODULES).

  6. Collections: Handles module collections by loading their state from files (:getMTfromFile()).

The MT is typically accessed as a singleton object (e.g., MT:singleton()) or retrieved from the current evaluation context via frameStk:mt(). It is dynamically updated as modules are loaded and unloaded.

For a detailed explanation of its role in state management, see MT: The Module Table.

myGlobal

Refers to the Lua script src/myGlobals.lua. Its primary purpose is to initialize and make available a wide range of global variables, internal constants, and fundamental settings that govern Lmod’s runtime behavior. Key aspects:

  1. Centralized Configuration: It uses the Cosmic singleton (cosmic:init{...}) extensively to define and initialize numerous LMOD_* configuration parameters. These parameters can be sourced from compile-time settings (via sedV substitution), environment variables (envV), or assigned default values. Examples include LMOD_TRACING, LMOD_SITE_NAME, LMOD_CONFIG_DIR, LMOD_RC.

  2. Internal Constants: Defines essential internal constants like ModulePath (the string “MODULEPATH”) and LMOD_CACHE_VERSION.

  3. Global State: Establishes some baseline global state, such as ensuring LC_ALL is set to “C” for consistent behavior and initializing ExitHookA (an array for functions to be called on exit).

  4. Early Initialization: Due to its widespread inclusion, it plays a crucial role in the early setup of Lmod’s operating environment before specific commands are processed.

It serves as a foundational script that provides a consistent and globally accessible set of parameters and constants for the rest of the Lmod codebase.

runTCLprog()

A globally available Lmod function (_G.runTCLprog) responsible for executing a specified TCL script and returning its output. It is primarily used by:

  1. loadModuleFile(): To convert TCL-based modulefiles into Lua code. In this context, runTCLprog is called with tcl2lua.tcl (a TCL script that translates modulecmd TCL syntax to Lua) as the program to run, and the path to the target TCL modulefile plus other necessary arguments.

  2. mrc_load.lua: To convert .modulerc files (which can be TCL based) into Lua. Here, runTCLprog is called with RC2lua.tcl. The runTCLprog function itself has multiple potential backends: it can be a Lua implementation that invokes an external tclsh interpreter, or if Lmod is compiled with an embedded TCL interpreter (from pkgs/tcl2lua/tcl2lua.c or embed/tcl2lua.c), it can be a C function that directly executes the TCL script. Its purpose is to bridge the gap between TCL-based files and Lmod’s Lua core by translating TCL into executable Lua statements.

sandbox_run()

The “sandbox” refers to the controlled execution environment Lmod creates to evaluate the Lua code within modulefiles. This mechanism is primarily implemented in src/sandbox.lua. Key aspects:

  1. Controlled Environment (``sandbox_env``): A specific Lua environment table (sandbox_env) is constructed. This table explicitly includes a curated list of safe standard Lua library functions (e.g., pairs, string.format) and all Lmod-provided modulefile API functions (e.g., prepend_path, load, whatis from src/modfuncs.lua). Functions that could be harmful are generally excluded or replaced by safer Lmod versions.

  2. Execution (``sandbox_run``): The Lua code from a modulefile (after being read and potentially converted from TCL by runTCLprog) is executed using a function, typically sandbox_run. This function compiles and runs the module code, setting the sandbox_env as the global environment for that code.

  3. Purpose: To ensure security (preventing malicious operations), isolation (enforcing a defined API), and robust error handling for modulefile execution.

The loadModuleFile() function is the primary user of sandbox_run. A similar mechanism, mrc_sandbox_run (from src/mrc_sandbox.lua), is used for evaluating .modulerc files.

varT

(Variable Table) varT is Lmod’s internal representation of the environment that is being built or modified as modulefiles are processed. It is not the OS environment itself, but rather a Lua table that Lmod uses to track changes. Key characteristics:

  1. Structure: varT is a Lua table where keys are environment variable names (strings, e.g., “PATH”, “FOO_VERSION”). The values associated with these keys are instances of the Var class (defined in src/Var.lua). Each Var object encapsulates the state and behavior for a single environment variable (e.g., its current value, delimiter for path-like variables, rules for handling duplicates).

  2. Access: varT is typically accessed from the current evaluation context (frame) via frameStk:varT(), where frameStk is the singleton instance of FrameStk.

  3. Manipulation: All modifications to the environment dictated by modulefile commands (like setenv, prepend_path, set_alias) are performed by first obtaining the relevant Var object from varT (creating it if it doesn’t exist via Var:new(name)) and then calling methods on that Var object (e.g., :set(), :prepend(), :setAlias()). These methods update the internal state of the Var object within varT.

  4. Output Generation: After all module commands are processed, Lmod reads the final state of all Var objects in varT to generate the shell commands (e.g., export FOO=bar;, setenv PATH /new/path:$PATH) that will actually modify the user’s shell environment.

For a detailed explanation of its role in state management, see varT: The Variable Table.