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.
StGermain-based codes use our in-house
VMake build system to find out and record information about dependencies,
then compile the code.
The basic process is:
build system where required dependencies are installed by setting appropriate
Below are the details of configure options,
plus notes on configuring on certain key systems.
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.
Adds debug flags so extra checks are performed
Compiles optimised code, with no debugging symbols
Performs addtional run-time validation checks.
Compiles some macros as functions instead for
safety checks. Will incur a performance penalty.
Enable statistics recording of the memory module.
compiles the code ready for use with the tau
automatically instruments the code for use with
tau using pdt
appends the build directory with the current
svn version, eg build-2803, to allow the user to link against different
version if necessary.
eg. To include cautious checks and memory
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
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
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
pushd $STG_INSTALL_DIR > /dev/null
popd > /dev/null
This section contains details on the dependencies
31 Dec 2004 - 06:37 PatrickSunter
Basic Shell Utilities
The basic shell utilities that its reasonable
for a Unix shell environment to provide - details below
The VMake build system, and thus all StGermain-based
The GNU core utilities package is at http://www.gnu.org/software/coreutils/
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/.
sh - An
sh-shell compatible shell (e.g. Bash)
Print system information.
find - for
finding files that pass a certain criteria
cp, mv, mkdir, ln - basic file utilities
sed - text
ar - create,
modify, and extract from archives
ranlib - generate an index to an archive
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.
03 Jan 2005 - 20:44 PatrickSunter
A C-Language Compiler
A compiler to turn code written in the C language
into compiled libraries and executables
Since the majority of StGermain is written in
C, you will need a C-language compiler to build and compile your
GCC, the popular GNU Compiler Collection, which
includes a C Compiler is available at http://gcc.gnu.org/releases.html
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.
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
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:
The executable of the compiler
Flags to pass to the compiler to create Shared
Object dynamic libraries
Flags to pass to the compiler/linker to create
Shared Object dynamic libraries
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
extension of a dynamically linked library
extension a dynamically loadable module (e.g.
plugin). Usually the same as SO_EXT, but different on some systems
Flags to pass the compiler so that it expects
to find required dll's in a certain location.
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.
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:
Flag specifying to the compiler what warnings
should be printed while compiling - e.g. "-Wall"
Flags specifying whether to add debug symbols
to compiled binaries - e.g. "-g"
Flags passed to the StGermain/User code to specify
debugging info - e.g. "-DDEBUG"
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:
Miscellaneous flags that should be passed to
Miscellaneous flags that should be passed to
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 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:
use of C++-style // comments
The __func__ predefined
The GCC pages have some good explanations
of the different standards, including what is implemented in GCC:
31 Dec 2004 - 03:48 PatrickSunter
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.
StGermain's build system VMake requires GNU
make, so it is thus crucial for all StGermain based projects
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.
31 Dec 2004 - 01:17 PatrickSunter
- The XML C parser and toolkit of Gnome
LibXML2 is a free, open-source XML
parsing toolkit, written in C.
The ability to read XML
files into the Journal
- currently a compulsory function
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.
31 Dec 2004 - 07:19 PatrickSunter
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:
- A Portable Implementation of MPI
A portable, free, open-source
implementation of the MPI standard for message-passing to allow
All of StGermain - since MPI is the core
message passing standard used by StGermain's parallel domain
decomposition etc. algorithms, journalling etc
For detailed instructions on
setting up MPICH, see Tech.MpichHowTo.
Set up the following
environment variables so the VMake build system knows where to
find your MPI implementation:
setenv MPI_DIR /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: