This document will walk you through the Research Computing recommended procedure for maintaining local installs in your home directory or project space.

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
    |   `-- packages
    `-- modulefiles

This structure is quite common in the UNIX world, and is also similar to how Research Computing 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.
• local/src/packages - Stores the compressed archives (“tarballs”) of your installers. Useful if you want to reinstall later using different build options.
• local/modulefiles - 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. After navigating to where you want to create the directory structure, e.g. $HOME execute:

# Empty directory means go HOME
cd
mkdir -p local/src/packages local/modulefiles

You do not have to perform any magic to get your module files loaded by the system. The system wide modules have been configured to add your home directory path, i.e. ~/local/modulefiles.

Now that you have your directory structure in place, you can install your software. For demonstration purposes, we will install a local copy of the Git version control system.

First, we need to get the source code onto the your filesystem. The easiest thing to do is find a download link, copy it, and use the wget tool to download it on your system. We'll download this into ~/local/src/packages:

cd ~/local/src/packages wget https://github.com/git/git/archive/v2.27.0.tar.gz -O git-2.27.0.tar.gz

Now extract into the parent src directory. If you're working with a tar file, you can use the -C command to specify the directory to extract to:

tar zxvf git-2.27.0.tar.gz -C ../

Next, we'll go into the source directory and build the program. Consult your application's documentation to determine how to specify to install into ~/local/app/version. Replace app with the application's name and version with the version you are installing, as demonstrated below. In this case, we'll use the configure tool's –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. If your application does not use configure, you can generally still set these variables somewhere in its Makefile or build script.

With these things in mind, we can build Git using the following commands:

cd ../git-2.27.0
make configure
./configure --prefix=$HOME/local/git/2.27.0
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.

Modules allow you to dynamically alter your environment to define environment variables and bring executable, libraries, and other features into your shell's search paths. They are written in the TCL language, though you do not need to be familiar with it to create a simple module.

All modules begin with the magic cookie #%Module. After that, they contain several commands to tell the module system how to modify your environment. Some of the commonly used ones are:

• prepend-path VARIABLE path - Adds path to the beginning of VARIABLE, where VARIABLE is a colon-separated list of paths. Generally use to modify PATH, LD_LIBRARY_PATH, and  MANPATH.
• setenv VARIABLE value - Sets the environment variable VARIABLE to value.
• set VARIABLE value - Used to set local variables to be used within the module.
• is-loaded - Returns a true value if any of the listed modulefiles has been loaded.
• prereq - Lists modulefiles which must have been previously loaded before the current modulefile will be loaded. We use it in conjunction with is-loaded command.

You can read about all of the available commands by reading the manpage for “module file”:

man modulefile

A simple module for our Git installation would be:

module.git

#%Module 1.0 -*- tcl -*-
 
## Local variables
set name git
set version 2.27.0
# $::env is a Tcl builtin function to access your UNIX environment
set root $::env(HOME)/local/$name/$version
 
## Environment modifications
# Set basic paths
prepend-path PATH       $root/bin
prepend-path MANPATH    $root/share/man
 
# Git includes some Python and Perl modules that may be useful
prepend-path PERL5LIB   $root/lib
prepend-path PERL5LIB   $root/lib64
prepend-path PYTHONPATH $root/lib

Any modulefile you create should be saved into your local modulefiles directory. For maximum future-proofing, create a subdirectory within modulefiles named after your app and add one modulefile to that directory for each version installed.

In the case of our Git example, you would create the directory ~/local/modulefiles/git and create a modulefile within that directory named 2.27.0. This will allow you to load your app using either module load git or module load git/2.27.0. If you installed version 2.28 later on and created a modulefile for it called 2.28, the module system would automatically load the newer version whenever you loaded git. If you needed to go back to the older version for some reason, you can do so by specifying the version you wanted: module load git/2.27.0.

For more information about modules, be sure to read the module(1) and modulefile(4) manpages. If you have any questions about modules or local installations, feel free to contact the Linux and Advanced Platforms Team