Basics

Libraries are compiled parts of the code that can be linked to existing code. They should be general, well tested modules with clearly defined and documented interfaces. Given the experimental nature of many codes used in science, building own libraries is usually a bit unpractical (unless you are a really good programmer already).

However, most simulation codes require some kind of non-standard library (e.g. MPI for parallel execution), so it is important to know how to use them.

A code might be compiled like this:

## this is my makefile

all: build

build: compile link

compile:

g++ -c test.cpp BST.cpp

link:

g++ -o testBST test.o BST.o

clean:

rm -rf *.o

rm -rf testBST

alternatively, BST.cpp could be converted to a (static) library (in general a library can contain multiple object files):

## compile

g++ -c ./bst/BST.cpp -o /opt_test/local/staticlib/BST.o

## create library (.a file) out of (in general multiple) object files

ar rcs /opt_test/local/staticlib/libBST.a /opt_test/local/staticlib/BST.o

## copy header file

cp ./bst/BST.h /opt_test/local/include/

The building of the rest of the code then looks like this:

## this is my makefile

all: build

build: compile link

compile:

g++ -I/opt/local/include -c -std=c++11 test.cpp ## #include <BST.h>

link:

g++ test.o -L/opt/local/lib -lBST -o testBST

clean:

rm -rf *.o

rm -rf testBST

The only thing that changed in test.cpp is the #include “BST.h” changed to #include <BST.h>.
The library here was installed in a non-standard place (not part of the PATH environment variable), which means that the path needs to be specified in compilation and linking. In detail, the path to the header needs to be included with -I/<path> during compilation and the path to the libBST.a library with -L/<path> -lBST.

 

Linking to libraries on clusters

On clusters, usually many different libraries are installed, and many different versions of the same one. To avoid conflicts they are usually made available on demand as loadable modules.

for details in general: https://www.tacc.utexas.edu/research-development/tacc-projects/lmod

for odyssey: https://www.rc.fas.harvard.edu/resources/documentation/software-on-odyssey/intro/

This means one has to find the appropriate library in the module list (cluster documentation)

and load them via

module load <moduleName>

In particular, this needs to be done in submission scripts. Loading these modules means that the installation path is made known to the compiler (PATH variable), which means that the path does not need to be specified in the building process.

Libraries that are not available this way need to be installed independently, usually in the home directory (since you are not admin of the cluster). This means that for these libraries, the path (to your home directory)  needs to be specified in the makefile. DO NOT CHANGE THE PATH ENVIRONMENT VARIABLE!