2. StGermain Installation Guide

SPModel is based on a low level library called StGermain. SPModel also depends on a few fortran libraries from the legacy code (Cascade). The source comes with both of these dependencies. However StGermain itself has a few core dependencies the the user has to install.

 

2.1. Configuring and Compiling the code

StGermain-based codes use our in-house VMake build system to find out and record information about dependencies, then compile the code.

The basic procedure

The basic process is:

  1. Tell the build system where required dependencies are installed by setting appropriate environment variables;

  2. Configure the code so its ready to compile by typing ./configure.sh;
  3. Compile executables, libraries & tests and install along with their header files by typing make.

Below are the details of configure options, plus notes on configuring on certain key systems.

Configure options

The following options can be included in the options argument during configuration in comma separated form. The environment variables at right can be used to override the option you give to configure at compile-time.

 

option

description

default

env variable

debug

Adds debug flags so extra checks are performed

OFF

USE_DEBUG

optimised

Compiles optimised code, with no debugging symbols

OFF

USE_OPTIMISED

cautious

Performs addtional run-time validation checks.

OFF

USE_CAUTIOUS

macro_as_func

Compiles some macros as functions instead for safety checks. Will incur a performance penalty.

OFF

USE_MACRO_AS_FUNC

memory_stats

Enable statistics recording of the memory module.

OFF

USE_MEMORY_STATS

tau

compiles the code ready for use with the tau profiler

OFF

USE_TAU

pdt

automatically instruments the code for use with tau using pdt

OFF

USE_PDT

version

appends the build directory with the current svn version, eg build-2803, to allow the user to link against different version if necessary.

OFF

USE_VERSION

 

eg. To include cautious checks and memory statistics recording:

./configure.sh --options=cautious,memory_stats

Installing StGermain's dependencies

The next step towards getting a StGermain-based code up and running is installing all of StGermains required dependencies, and any optional ones that you'll require.

Below we've listed information on each of them, including where to download them from, and any additional notes we've made on how to set them up (to complement the manuals of the packages themselves).

We try to keep the list of dependencies small, but even setting up a few can be a trying process, so you may need to refer to our installation notes. In some cases, problems with a dependency don't appear until you actually try to compile and link your StGermain-based code - in which case you'll need to come back to the install notes for that dependency.

2.1.2. Setting up run-time paths

StGermain has a small script which you can source from your .bashrc to automatically set up any run-time path changes, such as modifying your PATH variable, every time you log in.

To utilise this, add the following to your .bashrc, setting STG_INSTALL_DIR as appropriate:

#StGermain
export STG_INSTALL_DIR="~/+Codes/ClubStGermain"
pushd $STG_INSTALL_DIR > /dev/null
   . ./profile.sh
popd > /dev/null


Notes: Detailed information on setting up and linking against StGermain's dependencies

This section contains details on the dependencies of StGermain.

1.1     Basic Shell Utilities Info  

31 Dec 2004 - 06:37   PatrickSunter

Basic Shell Utilities

Package:

Basic Shell Utilities

Description:

The basic shell utilities that its reasonable for a Unix shell environment to provide - details below

Required for:

The VMake build system, and thus all StGermain-based codes

Download from:

The GNU core utilities package is at http://www.gnu.org/software/coreutils/

Further Notes

These are low-level utilities that we expect all Unix environments where you'll be running StGermain to provide. They should already be installed on your system, but if not the GNU Coreutils package contains most of them - see http://www.gnu.org/software/coreutils/.

If running ./configure.sh doesn't locate one of these utilities, you'll need to specify its location by setting an environment variable. The environment variable for each tool is the capitalised name of the tool - e.g. "find" is set by $FIND, "ar" is determined by $AR etc.

 

1.2     Cee Compiler Info  

03 Jan 2005 - 20:44   PatrickSunter

C Compiler

Package:

A C-Language Compiler

Description:

A compiler to turn code written in the C language into compiled libraries and executables

Required for:

Since the majority of StGermain is written in C, you will need a C-language compiler to build and compile your program

Download from:

GCC, the popular GNU Compiler Collection, which includes a C Compiler is available at http://gcc.gnu.org/releases.html

Further Notes

StGermain should work with almost all C89-compliant C compilers - see our policy on C standards. While most of the StGermain developers use the GCC (GNU Compiler Collection) C compiler, we also regularly test it compiles with the Intel compiler, and the Compaq Tru64 C Compiler. You should choose the C compiler that gives the best performance on the system you'll be running on.

Specifying a compiler to use to the VMake build system

Our build system assumes you'll use the C compiler available at "/usr/bin/cc", which is usually GCC.

You can override this by setting the $CC environment variable to the path of your preferred compiler. For example, if you wish to use the Intel compiler, and its locatable using your path as "icc", then just set the $CC environment variable to "icc" before you run ./configure.sh.

Once it knows where the binary of your C Compiler is, VMake will compile a test file to work out the compiler type, and set up several subsidiary variables based on the type. If you are using either the GCC, Intel or Alpha Tru64 compiler, your work is now done.

However, if you are using a different compiler to those three, you will need to work out and define other variables:

Variable

Meaning

CC

The executable of the compiler

SO_CFLAGS

Flags to pass to the compiler to create Shared Object dynamic libraries

SO_LFLAGS

Flags to pass to the compiler/linker to create Shared Object dynamic libraries

MODULE_LFLAGS

Flags to pass to the compiler/linker to create a dynamically-loadable module (eg plugin). Usually the same as SO_LFLAGS, but different on some systems

SO_EXT

extension of a dynamically linked library

MODULE_EXT

extension a dynamically loadable module (e.g. plugin). Usually the same as SO_EXT, but different on some systems

RPATH_LFLAGS

Flags to pass the compiler so that it expects to find required dll's in a certain location.

EXPORT_DYNAMIC_LFLAGS

Flags to specify that when creating a dynamically linked executable, add all symbols to the dynamic symbol table. (ie allow dlopened plugins to read symbols in main executable.

Passing Extra information (eg debugging) to the C compiler and linker

Sometimes, you wish to have fine-grained control over specific aspects of the C compiler - such as what level of optimisation should be performed. Note that we recommend you use the appropriate option to configure.sh to achieve this, but you can manually set the flags using the following environment variables:

Variable

Meaning

CC_WARNINGLEVEL

Flag specifying to the compiler what warnings should be printed while compiling - e.g. "-Wall"

CC_SYMBOLLEVEL

Flags specifying whether to add debug symbols to compiled binaries - e.g. "-g"

CC_DEBUGLEVEL

Flags passed to the StGermain/User code to specify debugging info - e.g. "-DDEBUG"

CC_OPTIMISATIONLEVEL

Flags specifying the level of optimisation to perform - e.g. "-O3"

On top of this, we have 2 other catch-all miscellaneous variables that you can use to pass in any other information:

Variable

Meaning

CFLAGS

Miscellaneous flags that should be passed to the compiler

LFLAGS

Miscellaneous flags that should be passed to the linker

For example, if you wanted to memory-check your code using Electric Fence, you might set LFLAGS="-lefence" so that your code was compiled to use the special Electric Fence memory wrappers.

Our policy on C language standards to use in StGermain-based codes

Our basic policy is that since we wish StGermain-based codes to be portable, we try and be conservative in our use of features so that most standard compilers can build the code. Accordingly, we use the C89 standard, with the following inclusions from the C99 standard:

The GCC pages have some good explanations of the different standards, including what is implemented in GCC:

1.3     Gnu Make Info  

31 Dec 2004 - 03:48   PatrickSunter

Package:

GNU Make

Description:

Make is the almost-universal tool which controls the generation of executables and other non-source files of a program from the program's source files. GNU Make is a more powerful version of the original Make.

Required for:

StGermain's build system VMake requires GNU make, so it is thus crucial for all StGermain based projects

Download from:

ftp://ftp.gnu.org/pub/gnu/make or ftp://mirror.aarnet.edu.au/pub/gnu/make/

 

VMake uses GNU Make (as opposed to the original Make) since it provides enough capability to do more complex tasks (allowing "if" conditions etc), but is still very widely available, and is comes pre-installed on almost all Unix systems.

Usually our build system will find and use GNU Make automatically. However, if you get strange make-related errors when attempting to compile the code, then try typing "gmake" instead of "make" - some systems install GNU Make as gmake. If you still have problems, type "make -v", and check that its GNU Make. If it isn't, you'll need to download and install it from the location above.

1.4     Lib XML2Info  

31 Dec 2004 - 01:17   PatrickSunter

LibXML2 - The XML C parser and toolkit of Gnome

Package:

LibXML2 - The XML C parser and toolkit of Gnome

Description:

LibXML2 is a free, open-source XML parsing toolkit, written in C.

Required for:

The ability to read XML files into the Journal - currently a compulsory function

Download from:

http://www.xmlsoft.org/downloads.html

Further Notes

LibXML2 is part of the GNOME project (although is usable by any software), under the MIT licence. It is almost always pre-installed on Unix systems, so VMake should take care of setting everything up for you.

 


1.5     Mpi Implementation Info  

31 Dec 2004 - 07:19   PatrickSunter

MPI - An Implementation of the MPI Message Passing standard

StGermain-based codes require an implementation of the MPI-1 standard for parallel message-passing, even if you only intend to run the code in serial. Fortunately, there are several free implementations of MPI than run on all flavours of Unix.

If you intend to run a StGermain-based code on your desktop or a commodity cluster that doesn't yet have an MPI implementation, we recommend installing the free, open source MPICH. We've provided details on it below:

Package:

MPICH - A Portable Implementation of MPI

Description:

A portable, free, open-source implementation of the MPI standard for message-passing to allow parallel computing

Required for:

All of StGermain - since MPI is the core message passing standard used by StGermain's parallel domain decomposition etc. algorithms, journalling etc

Download from:

http://www-unix.mcs.anl.gov/mpi/mpich/download.html

Further Notes

For detailed instructions on setting up MPICH, see Tech.MpichHowTo.

Telling StGermain how to link against your MPI implementation

Set up the following environment variables so the VMake build system knows where to find your MPI implementation:

In bash:

export MPI_DIR="/usr/local/mpich"

In tcsh:

setenv MPI_DIR /usr/local/mpich

Where /usr/local/mpich is the path where your MPI implementation was installed.

If you need to specify a machine file every time you run your MPI implementation, then in order for VMake's "make check" command to work, you'll need to specify another environment variable, MPI_MACHINES. Here are some examples:

In bash:

export MPI_MACHINES="/home/raq/machinefile"

In tcsh:

setenv MPI_MACHINES -machinefile /home/raq/machinefile