HOWTO: Locally Installing Software

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.

NOTE: Throughout this document we'll assume you're installing into your home directory, but you can follow the steps below in any directory for which you have read/write permissions.
This document assumes you are familiar with the process of building software using "configure" or via editing makefiles, and only provides some suggested "best practices" for installing in your home directory.

Getting Started

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
    |   `-- tars
    `-- share
        `-- modulefiles

This structure is quite common in the UNIX world, and is also 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.
  • local/src/tars - Stores the compressed archives ("tarballs") of your installers. Useful if you want to reinstall later using different build options.
  • local/share/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, run:

    mkdir -p local/src/tars local/share/modulefiles

Finally, you need to add your local modulefiles directory to the module system's search path. To do this, append the following line to your .bashrc, .cshrc, .tcshrc, or other shell startup script:

    module use /nfs/01/username/local/share/modulefiles

Replace "/nfs/01/username" with the full path of your home directory. (You can identify this from the command line with the command "echo $HOME".) If you already have a .modulerc file, just add the "module use" line to the end of it.

Installing Software

Now that you have your directory structure in space, 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 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 ~/local/src/tars:

    cd ~/local/src/tars
    wget http://git-core.googlecode.com/files/git-1.7.9.3.tar.gz

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

    tar zxvf git-1.7.9.3.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. 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.

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

    cd ../git-1.7.9.3
    ./configure --prefix=$HOME/local/git/1.7.9.3 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. 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 string "#%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.

You can read about all of the available commands by reading the manpage for "modulefile":

    man modulefile
This manpage is only available on Glenn. Oakley has a slightly different module system. Modules written for Glenn will work, but there are additional features available in Oakley's module system. That documentation can be found at http://www.tacc.utexas.edu/tacc-projects/mclay/lmod or by executing module help.

A simple module for our Git installation would be:

    #%Module

    ## Local variables
    set name git
    set version 1.7.9.3
    set root /nfs/01/username/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

Installation

Any modulefile you create you 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 of the app installed.

In the case of our Git example, you would create the directory $HOME/local/share/modulefiles/git and create a modulefile within that directory named "1.7.9.3". To make this module usable, you need to tell the modules utility where to look for it. You can do this by issuing the command module use $HOME/local/share/modulefiles, in our example. This will allow you to load your app using either module load git or module load git/1.7.9.3. If you installed version 1.8 later on and created a modulefile for it called "1.8", 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/1.7.9.3.

module use [/path/to/modulefiles] is not persistent between sessions.

For a starting point, copy our sample modulefile from ~support/doc/modules/sample_module. This modulefile follows the recommended design patterns laid out above, and includes samples of many common module operations.

Further Reading

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 OSC Help Desk and oschelp@osc.edu.

Supercomputer: 
Service: