Subsections

• CONVENTIONS
  • Routine Naming Conventions
  • Argument Lists
  
  
• LIBRARY STRUCTURE
  • Directories in the Distribution
  
  
• BUILDING THE DISTRIBUTION
  • Makefiles
  • The Library Archive File
  • Architectures
  
  
• SUBPROGRAMS REQUIRED

INTRODUCTION

GROWL is the Grid Resources On Workstation Library.

Note that a lot of this introduction is copied from the introduction to the CLIPS user manual and specifications. This is specific to Fortran 90. It will be updated in due course.

GROWL was the subject of a successful bid for funding to the JISC Virtual Research Environments Programme in 2004 [#!JISC_proposal!#] and a full joint software development project involving staff at Cambridge, Daresbury and Lancaster started in January 2005.

CONVENTIONS

Routine Naming Conventions

The routines are named growl_name where ``name'' is the name of the routine (function) and the corresponding chapter appearing in this documentation.

Argument Lists

In this release, ordering in argument lists is not completely standardised. Most routines may have ``context'', ``communicator'' and ``error'' arguments in addition to relevant numerical quantities following a method similar to that used in ScaLAPACK.

LIBRARY STRUCTURE

We shall assume that the library is to be installed at $(GROWL).

Directories in the Distribution

Typically GROWL will be installed on a desktop workstation in a location referred to as $(GROWL). This could for instance be $HOME/GROWL or /opt/GROWL or /usr/local/GROWL. The environment variable $GROWL will be set to refer to this location.

The Library distribution will contain a subset of the following directories. Usually the full source and all machine-specific files will not be included, but are likely to come with the development version plus some extra directories which are not used but retained for historical purposes.

[frame=single]
$(GROWL) - makefile install
     |__Doc
          |__Manual
     |__bin - grid-login etc.
     |__sbin - growl-globus-install etc.
     |__var
     |__arch - Readme.txt gcc.make
     |__include - README.txt INCLUDE.make makefile *.h
     |__Base - README.txt
          |__doc
          |__lib
          |__src - makefile *.c
     |__NAME - README.txt
          |__doc
          |__src - makefile *.c
          |__include - *.h
     |__etc.
     |__R - growl-install
        |__doc
        |__include - *h 
        |__src - makefile *.c
        |__GROWL - DESCRIPTION README configure configure.in...
             |__R - *.R ...
             |__src - Makevars.in README.txt *.c *.h ...
             |__help
             |__html
             |__man - *.Rd ...
             |__latex
             |__test
     |__lib - libgrowl.a
     |__Test
          |__src - makefile *.c
          |__include - *.h
          |__bin
          |__R

$(GROWL)/Doc

- Documentation suite. Sub-directory Manual contains LaTeX outline for complete specifications document, i.e. this document, which includes chapters from every set of routines via relative path;

$(GROWL)/sbin

- install scripts etc.

$(GROWL)/include

- user-accessible library module interfaces if not contained in library archive files;

$(GROWL)/Base

-

$(GROWL)/bin

- executable files such as grid-login;

$(GROWL)/lib

- user-accessible library archive file libgrowl.a (possibl containing module interfaces etc.);

$(GROWL)/arch

- set of machine-specific include files, may not all be present in a particular distribution;

$(GROWL)/NAME

- program directory for routine from chapter ``NAME'', e.g. Authentiation, Resources, Jobs, Transfer, Files, SRB, NetSolve, Gizmos, R;

$(GROWL)/Test

- location of test codes for individual routines;

$(GROWL)/Perl

- simple Perl test codes for remote methods;

$(GROWL)/examples

- example codes showing how to use the library;

$(GROWL)/Others

- collection of utility routines such as error handling, timers, memory management, sorting and random number generators.

$(GROWL)/backup

- backup files used during development;

$(GROWL)/dev

- stuff used for development only;

$(GROWL)/var

- log files etc.;

$(GROWL)/etc

- config files etc.;

$(GROWL)/SOAP

- link to a gSOAP distribution;

$(GROWL)/Globus

- link to a Globus distributino containing GSI and MyProxy client code and developers' libraries;

Each ``NAME'' subroutine directory, e.g. Resource or Jobs contains sub-directories as follows:

src

- source code for these library routines;

bin

- binaries and module interfaces for these routines;

lib

- partial library built from this source directory only;

include

- include files (modules) for this source directory only;

doc

- specifications chapter for these routines, plus other specific documentation;

test

- test suite for these library routines;

examples

- examples of using these library routines;

matrices

- example matrix input data (if present);

others

- various test routines which will not form part of the distribution;

backup

- copies of stuff done during development process.

Not all these will be present in the library distribution, but in addition a master makefile and README.txt may be present.

BUILDING THE DISTRIBUTION

The GROWL library directory contains a master makefile to build the distribution and test suite. It copies the machine-dependent definitions from arch to the required directories src and test and invokes make for each set of subroutines required. Assuming we are using bash shell this would typically be done as follows, e.g. on a Linux workstation:

export TARGET=gcc
make jobs

Information about other targets is given in Section  below.

The portion of the makefile which builds the contribution from the Gizmos directory is as follows:

gizmos:
	@echo 'Making $(TARGET) distribution...'
	(cd Gizmos/src; make GET; make stamp)

A similar procedure applies to each source directory and test program, but simply typing make after exporting the architecture target should build the whole distribution.

Makefiles

Each source and test directory contains its own makefile which will appear for instance as $(GROWL)/NAME/src/makefile. The makefiles include a machine-specific portion INCLUDE.make which contains definitions of architecture-dependdent compilation flags, libraries, options and shows what modules and binaries will be copied to $(GROWL)/include, $(GROWL)/lib and $(GROWL)/bin which will form the basis of the distribution.

The makefile contains a list of dependencies for building the object code of a particular set of subroutines. This will ensure that modules are compiled in the correct order.

Note that the routines in directory Base must be built first. This is ensured by the master makefile $(GROWL)/makefile.

The Library Archive File

Object modules built using the above procedure will be archived in a random-access library file $(GROWL)lib/libgrowl.a.

Architectures

This section is old and more appropriate for Fortran 90.

Specific details of the procedure used for Fortran 90 codes for each architecture are described in a separate report [#!f90build!#]. We list below the targets to invoke specific compilations available with the distribution. These should be defined as environment variables before building the distribution as described above for the gcc.

makefile TARGET for various computer architectures

TARGET	Architecture	See note #
gcc	Linux Gnu compiler
IBM-test	IBM	1
IBM-p2	IBM	1
IBM-ppc	IBM	1
IBM-sp2	IBM	1
IBM-sp3	IBM	1
IBM-smp	IBM	1
Cray-t3d	Cray T3D	2
Cray-t3e	Cray T3E	2
PGI-lam	Linux PGI	3
PGI-mpich	Linux PGI	3
SGI	SGI etc
DEC-alpha	Conpaq/ Digital
HP	HP
SUN	SUN
Hitachi	Hitachi SR2201 and SR8000	4
NEC	NEC SX4 and SX5
Fujitsu-vpp	Fujitsu VPP

Note 1. IBM RS/6000 with AIX

IBM compilers read ``.f'' ``.F'' or ``.f90'' files and produce ``.o'' and ``.mod'' files. The ``.mod'' files in the current directory or a directory referenced via the ``-I'' flag are parsed when a USE statement is met. A ``.mod'' file is therefore required for each user-accessible library module which must contain at least a list of explicit public interfaces. ``.o'' files are archived into libgrowl.a.

A typical user program compilation would be

mpxlf90_r -o myprog.out -O3 -qarch=auto myprog.f -I $(GROWL)/incude 
      -L $(GROWL)/lib -lgrowl

Note 2. Cray T series

The compiler reads ``.f'' and ``.F'' and produces ``.i'' and ``.o'' files. Module information must be either in the current directory or in a directory or binary file (``.o'' or ``.a'') referenced using the `'-p'' flag on the f90 command. In the user interface we use the final library file libgrowl.a to provide this information as follows:

f90 -o myprog.out -O3 myprog.f -p $(GROWL)/lib/libgrowl.a 
      -L $(GROWL)/lib -lgrowl

Note 3. Pentium Beowulf (RedHat Linux and PGI compilers)

PGI-lam and PGI-mpich targets invoke compilations using the Portland Group compilers and link with the Ohio Supercomputer Center LAM-MPI or the Argonne National Laboratory MPICH.

Note 4. Hitachi

The Hitachi Fortran 90 compiler on Hitach SR2201 and SR8000 systems takes files with a ``.f90'' extension. Only one module must be present in the file which must have the same name as the module. The source file is parsed when a USE statement is found. Only ``.o'' files are produced. For user-accessible modules a ``.f90'' file must be available in the distribution directory with at least a list of explicit public interfaces. ``.o'' files are archived into libgrowl.a.

SUBPROGRAMS REQUIRED