Installing and Using OdinMP/CCp

Prerequisites

These installation instructions assume that you have fetched the OdinMP/CCp archive, odinmp-1.0.tar.gz.

Installing

  1. Fetch the OdinMP/CCp archive and place it in a temporary location, such as tempdir/odinmp-1.0.tar.gz .
  2. 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.
  3. cd to install-root
  4. Unpack the OdinMP/CCp archive:
  5. 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:
  1. Open the file install-root/odinmp/bin/odinmp_prep in a text editor. Near the top, there is an area which reads something like
  2. ######################################################################
    # 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";
  3. 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:

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.