Making software available via a custom module file
Personal module files contain instructions for
making installed software available by adjusting your environment. Keep them in
$HOME/modules, separate from software installations such as
$HOME/software/installs/my_new_program. This gives Lmod one directory to
search for your module files without mixing them with programs and libraries.
The installation path is an example; another path works if the module file
points to it.
Create your module directory and make it available in the current session:
$ mkdir -p "$HOME/modules"
$ module use "$HOME/modules"
To make this directory available in future sessions, add
module use "$HOME/modules" to your .bashrc file.
You can generate a basic module file using the basic Lua directives to set local variables,
export these to your shell with the setenv function and prepend paths to your existing environment
variables with the prepend_path function.
Warning
Module files are not aware of bash shell variables unless you import them using the os.getenv function and set a Lua variable based on them.
e.g. the following example imports our shell environment HOME variable and sets the Lua
HOME variable with it. The Lua HOME variable is used to set the Lua variable MY_PROGRAM_DIR
(the software’s installation directory). The Lua MY_PROGRAM_DIR variable is then used to add the program’s
bin directory to your shell environment PATH variable with the prepend_path function.
-- Import the shell environment HOME variable into a Lua variable.
local HOME = os.getenv("HOME")
-- Set a local Lua variable for the program directory.
local MY_PROGRAM_DIR = HOME .. "/software/installs/my_new_program"
-- Export the program directory to the shell environment.
setenv("MY_PROGRAM_DIR", MY_PROGRAM_DIR)
-- Prepend the program's bin directory to the shell environment PATH variable.
prepend_path("PATH", MY_PROGRAM_DIR .. "/bin")
Save the following example module file as
$HOME/modules/my_new_program.lua, adapting the paths and dependencies
for your software:
------------------------------------------------------------------------------------------------
-- ~/modules/my_new_program.lua:
------------------------------------------------------------------------------------------------
-- Provide help text for the module.
help([[
Description
===========
Makes my newly installed program available.
More information
================
- Homepage: https://www.my-new-programme.com
]])
-- Describe the module.
whatis("Description: Makes my newly installed program available.")
whatis("Homepage: https://www.my-new-programme.com")
whatis("URL: https://www.my-new-programme.com")
-- Specify a conflicting module.
conflict("my_new_program")
-- Load any dependencies.
load("GCC/10.2")
load("CMake/3.18.4-GCCcore-10.2.0")
-- Set a program root directory Lua variable MY_PROGRAM_DIR to simplify prepend_path directives.
-- Reminder: setting an environment variable with setenv does not set the equivalent Lua variable!
-- Reminder: setting a Lua variable does not set the equivalent shell environment variable either!
-- Note no trailing slash is required for MY_PROGRAM_DIR as we are using a / on the prepend_path directives.
local MY_PROGRAM_DIR = "/users/my_username/software/installs/my_new_program"
setenv("MY_PROGRAM_DIR", MY_PROGRAM_DIR)
setenv("MY_SOFTWARE_LICENSE_PATH", "/users/my_username/software/licenses/mysoftware/license.lic")
-- Add directories to environment variables.
prepend_path("PATH", pathJoin(MY_PROGRAM_DIR, "bin"))
prepend_path("LIBRARY_PATH", pathJoin(MY_PROGRAM_DIR, "lib"))
prepend_path("LD_LIBRARY_PATH", pathJoin(MY_PROGRAM_DIR, "lib"))
prepend_path("PKG_CONFIG_PATH", pathJoin(MY_PROGRAM_DIR, "lib/pkgconfig"))
prepend_path("CMAKE_PREFIX_PATH", MY_PROGRAM_DIR)
After adding $HOME/modules with module use, load this module with:
$ module load my_new_program
And unload with:
$ module unload my_new_program
Modulefiles make it easy to add many versions of the same software easily via duplication and simple editing without the risk of permanently corrupting your shell environment. Further info on the modules system can be found on the modules page.