Installing and Using OdinMP/CCp
Prerequisites
These installation instructions assume that you have fetched the OdinMP/CCp
archive, odinmp-1.0.tar.gz.
Installing
-
Fetch the OdinMP/CCp archive and place it in a temporary location, such
as tempdir/odinmp-1.0.tar.gz .
-
To install OdinMP/CCp, choose where you wish to install OdinMP/CCp - call
this install-root . A good choice for install-root would
be, for instance, /usr/local , /opt , or perhaps your
home directory.
-
cd to install-root
-
Unpack the OdinMP/CCp archive:
gzcat tempdir/odinmp-1.0.tar.gz | tar -xvf -
his will create a subdirectory odinmp beneath the current directory,
which contains all the necessary OdinMP files.
You have now unpacked the OdinMP/CCp files.
Mandatory Configuration
Before you can begin using OdinMP/CCp, you must inform the OdinMP/CCp system
where it is installed:
-
Open the file install-root/odinmp/bin/odinmp_prep
in a text editor. Near the top, there is an area which reads something
like
######################################################################
# Edit this to point to the dircetory where you installed OdinMP/CCp #
# #
$odinmp_home = "INSTALLDIR/odinmp";
# #
######################################################################
Replace 'INSTALLDIR' (or whatever is in its place) with 'install-root'
. If your install-root is /usr/local, then the line
should read exactly
$odinmp_home = "/usr/local/odinmp";
-
Similarly, open the file install-root/odinmp/bin/OdinMP,
and perform the same editing actions on that as you did with odinmp_prep
above.
Requirements and Optional Configuration
To run, OdinMP/CCp requires two things.
Perl version 5
The programs in install-root/odinmp/bin/ are Perl
version 5 programs. They expect Perl version 5 to be installed somewhere
in your search path, so that it can be found by /usr/bin/env . If the programs
won't immediately run on your system, modify the top line of each program
to point to the correct location for Perl version 5.
Java 1.1 or newer
A Java runtime, version 1.1 or newer, which must be in the program search
path, such as identifed by the PATH environment variable. This is used
by the install-root/odinmp/bin/OdinMP program. If
necessary, you can edit install-root/odinmp/bin/OdinMP
to explicitly point out the java interpreter you require.
Running OdinMP/CCp
Consider that you have a program foobar, compiled from files foo.c
and bar.c, which you wish to parallelize through OdinMP/CCp. Here
is a description, step by step, of what you need to do.
cd to the directory containing the original source files
This places you in the directory which contains the original source files
for your program foo.c and bar.c .
Prepare for OdinMP/CCp parallelization
Run the command
odinmp_prep --output=foobar --targetDirectory=foobar_parallel foo.c bar.c
This will create a directory called foobar_parallel, and
in that directory a makefile and symbolic links to the files 'omp.c'
and 'omp.h' as supplied with OdinMP/CCp.
cd to foopar_parallel
This places you in the same directory as the generated makefile.
make
This will call upon OdinMP/CCp to walk through the files specified on the
odinmp_prep
command line, parallelizing each one, and generating a corresponding output
file in the current directory. Each generated C source file will be compiled,
and finally all object files get linked to form the resulting program.
A Simple Example
The NAS benchmark suite for OpenMP includes a program called 'laplace'.
To build this program, a Makefile is provided:
#
# Makefile for Laplace
#
# OPT = -g
# OPT = -xO4
OBJ = lap.o
INCL=lap.h
# CC=gcc
CFLAGS = $(OPT)
LDLIBS = -lm
OMPCC = ompcc
PROGRAM = lap-omp lap-seq
all: $(PROGRAM)
lap-omp: lap.c second.o
$(OMPCC) $(CFLAGS) -o lap-omp lap.c second.o $(LDLIBS)
lap-seq: lap.c second.o
$(CC) $(CFLAGS) -o lap-seq lap.c second.o $(LDLIBS)
clean:
rm -f $(PROGRAM)
Since OdinMP does not provide an 'ompcc' command, a slightly
different approach must be taken. To build 'lap-odinmp' (the OdinMP-compiled
version of the laplace program), we would use the following rules instead:
odinmp_ccd/makefile:
LIBS=$(LDLIBS) odinmp_prep --targetDirectory=odinmp_ccd --output=../lap_odinmp lap.c second.c
lap-odinmp: odinmp_ccd/makefile
cd odinmp_ccd; make
The first rule will prepare the OdinMP build directory ('odinmp_ccd'),
with a makefile to create '../lap-odinmp' from the source files 'lap.c'
and 'second.c', linking the .
The second rule will build lap-odinmp by changing to the OdinMP build
directory and building the program there. Since this rule depends on the
existance of the makefile in the OdinMP build directory, this will be created
if it does not already exist.
Specifics on the Provided Programs
odinmp_prep
Synopsis
odinmp_prep [--output=output] [--targetDirectory=targetDirectory]
[--targetDebug=(always|runtime|never)]
[--targetTiming=(always|runtime|never)]
source-files
Description
odinmp_prep prepares a project of C language source code files
for OdinMP parallelization, by the following steps:
-
creates the directory targetDirectory. If no targetDirectory
is specified, it defaults to 'odinmp_ccd'.
-
creates a makefile inside targetDirectory with a dependancy of each
of the source-files to the corresponding file in the directory that
odinmp_prep was called from.
-
configures the makefile to call OdinMP with the targetDebug
and targetTiming options as specified on the command line. Their
respective default value is never.
-
configures the makefile to build a resulting program called output.
If output is not specified, it defaults to a.out.
OdinMP
Synopsis
OdinMP [--targetDirectory=targetDirectory] [--targetTiming=(always|runtime|never)]
[--targetDebug=(always|runtime|never)]
[--cpp=cpp] [--cc=cc] [--numProcessors=numProcessors]
[--numThreads=numThreads] source-files
Desciption
OdinMP performs the actual compilation from C with OpenMP directives, to
C with pthreads library calls.
Files are read from the current directory and generated to targetDirectory.
If targetDirectory is not specified, it defaults to 'odinmp_ccd'.
The 'targetTiming' option specifies whethet OdinMP/CCp will include
timing code in the generated code, and whether timing will actually be
performed. If targetTiming is 'never', no code is generated. If
targetTiming
is 'runtime', code is generated which will allow the resulting program
to print timing information if called with the '--odinmp_timing' command
line option. If targetTiming is 'always', the generated code will
always measure and report timing information. The default value for targetTiming
is 'never.
The 'targetDebug' option specifies whethet OdinMP/CCp will include debugging
code in the generated code, and whether debugging messages will actually
be printed. If targetDebug is 'never', no code is generated. If
targetDebug
is 'runtime', code is generated which will allow the resulting program
to print debug information if called with the '--odinmp_debug' command
line option. If targetDebug is 'always', the generated code will
always print debugging information. The default value for targetDebug
is 'never.
The '--cpp=cpp' option specifies an alternate C preprocessor
to use for preprocessing the input C source files. The default is 'install-root/odinmp/bin/cppp'.
The '--cc=cc' option selects an alternate C compiler
to use for compiling the generated C source files. The default is 'install-root/odinmp/bin/ccc'.
cppp
Synopsis
cppp [options] < input > output
Description
cppp reads un-preprocessed C source code from its standard input,
preprocesses it, and prints the result to its standard output.
cppp is implemented as a Perl script which wraps around various
different C preprocessors. By setting the variable '$cpp' at the
top of the script, one of several underlying C preprocessors can be selected.
The purpose of cppp is to insulate OdinMP from the particular
semantics of how the underlying C preprocessor accepts and generates data.
The environment variable ODINMP_CPP can be used to override
the contents of the $cpp variable specified in the script at runtime.
ccc
Synopsis
ccc [options] source-files
Description
ccc compiles the C source code specified into object files, or
links the object files specified into an executable.
ccc is implemented as a Perl script which wraps around various
different C compilers. By setting the variable '$cc' at the top
of the script, one of several underlying C compilers can be selected. The
purpose of ccc is to insulate OdinMP from the particular semantics
of how the underlying C compiler wants its arguments.
The environment variable ODINMP_CC can be used to override
the contents of the $cc variable specified in the script at runtime.