Sometimes the best way to get access to a piece of software on the HPC systems is to install it yourself as a "local install". This document will walk you through the OSC-recommended procedure for maintaining local installs in your home directory or project space. The majority of this document describes the process of "manually" building and installing your software. We also show a partially automated approach through the use of a bash script in the Install Script section near the end.
Before installing your software, you should first prepare a place for it to live. We recommend the following directory structure, which you should create in the top-level of your home directory:
local |-- src |-- share `-- lmodfiles
This structure is analogous to how OSC organizes the software we provide. Each directory serves a specific purpose:
local- Gathers all the files related to your local installs into one directory, rather than cluttering your home directory. Applications will be installed into this directory with the format "appname/version". This allows you to easily store multiple versions of a particular software install if necessary.
local/src- Stores the installers -- generally source directories -- for your software. Also, stores the compressed archives ("tarballs") of your installers; useful if you want to reinstall later using different build options.
local/share/lmodfiles- The standard place to store module files, which will allow you to dynamically add or remove locally installed applications from your environment.
You can create this structure with one command:
mkdir -p $HOME/local/src $HOME/local/share/lmodfiles
(NOTE: $HOME is defined by the shell as the full path of your home directory. You can view it from the command line with the command
Now that you have your directory structure created, you can install your software. For demonstration purposes, we will install a local copy of Git.
First, we need to get the source code onto the HPC filesystem. The easiest thing to do is find a download link, copy it, and use the
wget tool to download it on the HPC. We'll download this into
cd $HOME/local/srcwget https://github.com/git/git/archive/v2.9.0.tar.gz
Now extract the tar file:
Next, we'll go into the source directory and build the program. Consult your application's documentation to determine how to install into
"software_name" with the software's name and
"version" with the version you are installing, as demonstrated below. In this case, we'll use the
--prefix option to specify the install location.
You'll also want to specify a few variables to help make your application more compatible with our systems. We recommend specifying that you wish to use the Intel compilers and that you want to link the Intel libraries statically. This will prevent you from having to have the Intel module loaded in order to use your program. To accomplish this, add
CC=icc CFLAGS=-static-intel to the end of your invocation of
configure. If your application does not use
configure, you can generally still set these variables somewhere in its Makefile or build script.
Then, we can build Git using the following commands:
cd git-2.9.0 autoconf # this creates the configure file ./configure --prefix=$HOME/local/git/2.9.0 CC=icc CFLAGS=-static-intel make && make install
Your application should now be fully installed. However, before you can use it you will need to add the installation's directories to your path. To do this, you will need to create a module.
Creating a Module
Modules allow you to dynamically alter your environment to define environment variables and bring executables, libraries, and other features into your shell's search paths.
We can use the mkmod script to create a simple Lua module for the Git installation:
module load mkmod create_module.sh git 2.9.0 $HOME/local/git/2.9.0
It will create the module
$HOME/local/share/lmodfiles/git/2.9.0.lua. Please note that by default our mkmod script only creates module files that define some basic environment variables
GIT_HOME. These default variables may not cover all paths desired. We can overwrite these defaults in this way:
module load mkmod TOPDIR_LDPATH_LIST="lib:lib64" \ TOPDIR_PATH_LIST="bin:exe" \ create_module.sh git 2.9.0 $HOME/local/git/2.9.0
We can also add other variables by using ENV1, ENV2, and more. For example, suppose we want to change the default editor to vim for Git:
module load mkmod ENV1="GIT_EDITOR=vim" \ create_module.sh git 2.9.0 $HOME/local/git/2.9.0
Manually create a module
We will be using the filename 2.9.0.lua ("version".lua). A simple Lua module for our Git installation would be:
-- Local Variables local name = "git" local version = "2.9.0" -- Locate Home Directory local homedir = os.getenv("HOME") local root = pathJoin(homedir, "local", name, version)
-- Set Basic Paths prepend_path("PATH", pathJoin(root, "bin"))prepend_path("LD_LIBRARY_PATH", root .. "/lib") prepend_path("LIBRARY_PATH", root .. "/lib") prepend_path("INCLUDE", root .. "/include") prepend_path("CPATH", root .. "/include") prepend_path("PKG_CONFIG_PATH", root .. "/lib/pkgconfig")
prepend_path("MANPATH", root .. "/share/man")
NOTE: For future module files, copy our sample modulefile from
~support/doc/modules/sample_module.lua. This module file follows the recommended design patterns laid out above and includes samples of many common module operations
NOTE: TCL is cross-compatible and is converted to Lua when loaded. More documentation is available at https://www.tacc.utexas.edu/research-development/tacc-projects/lmod/ or by executing module help.
Any module file you create should be saved into your local lmodfiles directory ($HOME/local/share/lmodfiles). To prepare for future software installations, create a subdirectory within lmodfiles named after your software and add one module file to that directory for each version of the software installed.
In the case of our Git example, you should create the directory
$HOME/local/share/lmodfiles/git and create a module file within that directory named
To make this module usable, you need to tell lmod where to look for it. You can do this by issuing the command
module use $HOME/local/share/lmodfiles in our example. You can see this change by performing
module avail. This will allow you to load your software using either
module load git or
module load git/2.9.0.
module use$HOME/local/share/lmodfiles and module load "software_name" need to be entered into the command line every time you enter a new session on the system.
If you install another version later on (lets say version 2.9.1) and want to create a module file for it, you need to make sure you call it
2.9.1.lua. When loading Git, lmod will automatically load the newer version. If you need to go back to an older version, you can do so by specifying the version you want:
module load git/2.9.0.
To make sure you have the correct module file loaded, type
which git which should emit "~/local/git/2.9.0/bin/git" (NOTE: ~ is equivalent to $HOME).
To make sure the software was installed correctly and that the module is working, type git --version which should emit "git version 2.9.0".
Automating With Install Script
Simplified versions of the scripts used to manage the central OSC software installations are provided at
~support/share/install-script. The idea is that you provide the minimal commands needed to obtain, compile, and install the software (usually some variation on
make install) in a script, which then sources an OSC-maintained template that provides all of the "boilerplate" commands to create and manage a directory structure similar to that outlined in the Getting Started section above. You can copy an example install script from
~support/share/install-script/install-osc_sample.sh and follow the notes in that script, as well as in
~support/share/install-script/README.md, to modify it to install software of your choosing.
$HOME/osc_apps/lmodfiles, so you will need to run
module use $HOME/osc_apps/lmodfilesand
module load [software-name]every time you enter a new session on the system and want to use the software that you have installed.
For more information about modules, be sure to read the webpage indicated at the end of
module help. If you have any questions about modules or local installations, feel free to contact the OSC Help Desk and firstname.lastname@example.org.