Module Properties

Lmod support giving modules properties. For modules written Lua, the add_property() function looks like:

add_property("key", "value")

In TCL, it is written as:

add-property key value

The key and value are controlled by a file called lmodrc.lua.

The Properties File: lmodrc.lua

Lmod provides a standard lmodrc.lua which is copied to the installation directory. For example Lmod version X.Y.Z is installed in /apps/lmod/X.Y.Z then lmodrc.lua would be installed in /apps/lmod/X.Y.Z/init/lmodrc.lua. During the install process this file is modified to include the location of the system spider cache.

Lmod searches the properties in several location in order given below. Assuming again that Lmod is installed in /apps/lmod/X.Y.Z then Lmod searches for the property information in the following order:

1. /apps/lmod/X.Y.Z/init/lmodrc.lua

2. /apps/lmod/etc/lmodrc.lua

3. $LMOD_CONFIG_DIR/lmodrc.lua (default /etc/lmod/lmodrc.lua)

4. /etc/lmodrc.lua

5. $HOME/.lmodrc.lua

6. $LMOD_RC

Where $LMOD_RC is an environment variable that can be set to point to any file locaiton. If there are more than one of these files exist then they are merged and not a replacement. So a site can (and should) leave the first file as is and create another one to specify site properties and Lmod will merge the information into one.

The format of this file looks like:

local i18n = require("i18n")
propT = {
   arch = {
      validT = { mic = 1, offload = 1, gpu = 1, },
      displayT = {
         ["mic:offload"]     = { short = "(*)",  color = "blue", full_color = false, doc = "built for host, native MIC and offload to the MIC",  },
         ["mic"]             = { short = "(m)",  color = "blue", full_color = false, doc = "built for host and native MIC", },
         ["offload"]         = { short = "(o)",  color = "blue", full_color = false, doc = "built for offload to the MIC only",},
         ["gpu"]             = { short = "(g)",  color = "red" , full_color = false, doc = "built for GPU",},
         ["gpu:mic"]         = { short = "(gm)", color = "red" , full_color = false, doc = "built natively for MIC and GPU",},
         ["gpu:mic:offload"] = { short = "(@)",  color = "red" , full_color = false, doc = "built natively for MIC and GPU and offload to the MIC",},
      },
   },
   state = {
      validT = { experimental = 1, testing = 1, obsolete = 1 },
      displayT = {
         experimental  = { short = "(E)", full_color = false,  color = "blue",  doc = i18n("ExplM"), },
         testing       = { short = "(T)", full_color = false,  color = "green", doc = i18n("TstM"), },
         obsolete      = { short = "(O)", full_color = false,  color = "red",   doc = i18n("ObsM"), },
      },
   },
   lmod = {
      validT = { sticky = 1 },
      displayT = {
         sticky = { short = "(S)",  color = "red",    doc = i18n("StickyM"), }
      },
   },
   status = {
      validT = { active = 1, },
      displayT = {
         active = { short = "(L)",  color = "yellow", doc = i18n("LoadedM")},
     },
   },
}

This file defines a table called propT. A table is a generic name for a hash table or dictionary or associative array. That is, it stores key value pairs. It is an Lmod convention that a table is named with a trailing T to remind us that it is a table.

In this case propT defines the valid keys and values that are possible for a modulefile to use with add_property(). In the case of the above table, the only valid keys in a modulefile would be arch, state, lmod and status.

The value for state controls the valid values. In particular, the only valid values for state are experimental, testing or obsolete. Please note that a modulefile can have multiple properties but each property key can have only one value. So:

add_property("state","testing")
add_property("state","obsolete")

would make the state property have a value of obsolete. On the other hand a modulefile could have two or more properties.:

add_property("state","testing")
add_property("lmod","sticky")

Lmod itself depends on the keys lmod and status. So as a site, it is expected that any lmodrc.lua file will contain these properties.

The tables validT and displayT

The function add_property() expects a key and value. So for the state key, possible value are experimental, testing or obsolete. Those strings must appear in two tables: the validT and the displayT tables. For example, we can see that testing appears both in the validT and displayT tables. This exist for checking for valid values when the add_property() function is called from modulefiles.

The displayT table controls how the property is displayed. The fields in the table controls how a property is displayed. For example:

testing = { short = "(T)", full_color = false,  color = "green", doc = i18n("TstM"), },

says that a module with this property will have a ‘(T)’ next to its name when printed by module avail. If the terminal display has “xterm” as part of the environment variable TERM. then the ‘T’ will be in green. If the field full_color is set to true then the name and ‘T’ will be in green.

The possible color values are: black, red, green, yellow, blue, magenta, cyan, and white. In practice, since users can use light letters on dark backgrounds or dark letters on light backgrounds, sites may wish to avoid black, white and possibly yellow.

The arch key shows that the the values can be combined. If the value is colon separated then each string between the colons have to be valid keys.