PORTABLE APPLICATION CODE TOOLKIT

Table of Contents

Disclaimer

Introduction

Overview

SCORE	A Low Level Foundation
PPC	Portable Process Control Library
PML	Portable Mathematics Library
PDB	Portable Binary Database Library
SCHEME	An Interpreter for the Scheme Dialect of LISP
PGS	Portable Graphics System
PANACEA	Portable Simulation Code Development Environment
ULTRA II	1D Data Presentation, Analysis, and Manipulation
SX	Scheme with Extensions

PACT Documentation

Availability of PACT Software

Platforms

Obtaining the PACT Distribution

Source and Version Management

PACT Manager

PACT Makefiles

PACT Manager Makefile

pact-config

pact-update

pact-dist

utilities

Installing and Using PACT

UNIX

CONFIGURATION FILE SYNTAX

CONFIGURATION PARAMETERS DESCRIBED

C ENVIRONMENT PARAMETERS

DOS

MAC OS

Disclaimer

This document was prepared as an account of work sponsored by an agency of the United States Government. Nneither the United States Government nor the University of California nor any of their employees, makes any warranty, express or implied, including the warranties of merchantability and fitness for a particular purpose, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not infringe privately owned rights. Reference herein to any specific commercial products, process, or service by trade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or the University of California. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or the University of California, and shall not be used for advertising or product endorsement purposes.

Part of this work performed under the auspices of the U.S. Department of Energy by Lawrence Livermore National Laboratory under Contract W-7405-Eng-48.

Introduction

In a computing landscape which has a plethora of different hardware architectures and supporting software systems ranging from compilers to operating systems, there is an obvious and strong need for a philosophy of software development that lends itself to the design and construction of portable code systems. The current efforts to standardize software bear witness to this need.

PACT is an effort to implement a software development environment which is itself portable and promotes the design and construction of portable applications. PACT does not include such important tools as editors and compilers. Well built tools of that kind are readily available across virtually all computer platforms. The areas that PACT addresses are at a higher level involving issues such as data portability, portable inter-process communication, and graphics. These blocks of functionality have particular significance to the kind of code development done at LLNL. That is partly why the general computing community has not supplied us with these tools already. This is another key feature of the software development environments which we must recognize. The general computing community cannot and should not be expected to produce all of the tools which we require.

At the time that PACT was begun other groups at other institutions were also beginning efforts to address some of these issues. That is the reason that one can find some of the conceptual parts of PACT in the work done at some of these institutions. One of the strengths of PACT is the degree of integration of these which the component parts can achieve. This affords the application developer a relatively small and efficient set of tools. For this reason, the total capability of PACT is unmatched in other software systems.

In its current conception, PACT is a set of nine tools. Eight of these are implemented as libraries, and two of them provide both libraries and executable applications. PACT is entirely coded in C but was designed with a view toward support of other languages, notably FORTRAN.

The design of PACT was and is functionally driven. The main idea is to identify generic blocks of functionality independent of considerations of language and specific applications. When that has been done, the application program interface (API) for a particular block of functionality, e.g. inter-process communication, naturally emerges. With the API specified, the implementation proceeds fairly naturally. The most important concept in making this approach work is that of abstraction barriers. The API defines an abstraction barrier between the general purpose functionality and the applications built on top of it. The underlying implementation can be changed without necessitating changes to the applications using it. This goal has not always been achieved, but the fact is that it remains as a goal and PACT is always evolving toward that goal. Part of the success which PACT enjoys from the perspective of meeting its requirements is due to the use of abstraction barriers. For people interested in a marvelous exposition of these ideas, I highly recommend Abelson and Sussman’s book, Structure and Interpretation of Computer Programs which has been one of the core textbooks in MIT’s Computer Science curriculum. All of PACT has been strongly influenced by that book.

PACT includes the following software libraries and applications:

SCORE	a low level, environment balancing library
PML	a math library
PPC	a process control library
PDB	a portable binary database management library
SCHEME	an interpreter for the Scheme dialect of the LISP language
PGS	a graphics library
PANACEA	a simulation code development system
ULTRA	a 1d data presentation, analysis, and manipulation tool
SX	Scheme with extensions (PDBView and PDBDiff are SX programs)

These tools facilitate the development of software which need portable support for graphics, inter-process communication and networking, and portable binary data handling and storage. It is ideal for the kinds of software development which are done at academic, applied scientific, and engineering institutions.

The point cannot be overemphasized that these tools are part of a coherent approach to solving portability problems. They are modularized which allows application builders to use only the parts needed for particular projects. They cooperate together so that there is maximal code reuse in PACT with its attendant benefits (maintainability, shareability, and flexibility). They are very generic in that each module is constructed to address a specific block of functionality, e.g. graphics, and address it in a general and comprehensive way. The PACT tools are also layered. The higher level tools utilize the functionality of the lower level ones. Roughly, the PACT tools fit in the following hierarchy:

ULTRA SX PANACEA PGS SCHEME PPC PML PDB SCORE

ULTRA and SX are at the top of the hierarchy and SCORE is at the bottom. This in turn sits on the more raw, vendor supplied, hierarchy:

COMPILER OPERATING SYSTEM HARDWARE

The following sections will give a brief overview of the purpose of the component parts of PACT.

Overview

As mentioned above, the PACT system is both modular and layered in design. In each layer the modules are independent of one another, but each layer can depend on any module in the layers beneath it. This consideration has a strong influence on where certain functions reside. In general, if a function has no strong attachment to a functional grouping (e.g. graphics), it goes into the lowest level layer to which all of the other parts of PACT that might be able to use that function have access. In spite of one’s expectations, this doesn’t mean that functions tend to gravitate to SCORE. There seems to be a real, natural level for almost every function in PACT.

To avoid name conflicts and to aid application developers who use PACT, there are some naming conventions followed (although not fanatically so) in all of the coding of PACT. Most functions, external variables, and macros begin with either a two, upper case character designator followed by an underscore or an underscore followed by the designator and an underscore. The main functions, variables, and macros of the API lack the leading underscore. Those functions, variables, and macros which are very useful but require greater understanding of the libraries or are simply not necessary to the main API have the leading underscore. Many software systems would not document this latter category of objects and protect the API with the freedom to change these around. I document these in PACT because they are too useful to brush off.

The list of designators for the PACT tools is:

Package	Designator	Example
SCORE	SC	SC_strsave
PPC	PC	PC_open
PML	PM	PM_decompose
PDB	PD	PD_read
SCHEME	SS	SS_eval
PGS	PG	PG_set_viewport
PANACEA	PA	PA_simulate
ULTRA	UL	UL_set_graphics_mode
SX	SX	SX_draw_plot

SCORE: A Low Level Foundation

SCORE (System CORE) has two main functions. The first and perhaps most important is to smooth over the differences between different C implementations and define the parameters which drive most of the conditional compilations in the rest of PACT. Secondly, it contains several groups of functionality that are used extensively throughout PACT.

Although C is highly standardized now, that has not always been the case. Roughly speaking C compilers fall into three categories: ANSI standard; derivative of the Portable C Compiler (Kernighan and Ritchie); and the rest. PACT has been successfully ported to many ANSI and PCC systems. It has never been successfully ported to a system in the last category. The reason is mainly that the “standard” C library supplied with such implementations is so far from true ANSI or PCC standard that PACT would have to include its own version of the standard C library to in order to work at all. Even with standardized compilers life is not dead simple. The ANSI standard leaves several crucial points ambiguous as “implementation defined”. Under these conditions one can find significant differences in going from one ANSI standard compiler to another.

SCORE’s job is to include the requisite standard headers and ensure that certain key standard library functions exist and function correctly (there are bugs in the standard library functions supplied with some compilers) so that, to applications which include the SCORE header(s) and load with SCORE, all C implementations look the same. This is a tall order, but in practice once SCORE has been successfully compiled only the areas of graphics, IPC, and binary data handling require special consideration! This has more of an impact on some programmers than on others. Those who prefer to specify only the exact headers to be included in each source file will find SCORE and PACT unusual. At the expense of a slight increase in compile time, the most commonly used headers are always included. This is crucial to getting the C implementation independence.

Typically, the SCORE header scstd.h includes the following:

   ANSI    stdlib.h stddef.h stdarg.h float.h

   PCC      sys/types.h varargs.h malloc.h

   Both     limits.h stdio.h string.h math.h ctype.h signal.h setjmp.h time.h

The single header, scstd.h, smooths over most of the generic problems that arise because of implementation defined behavior in the host C implementation. The remainder of the PACT sources ultimately include scstd.h. This strategy has been extremely successful for PACT and applications which use PACT.

There are basically three other areas which SCORE functions address: memory management; hash table management; and extended string handling.

See Also: SCORE User’s Manual

Dependent PACT Libraries: None

PPC: Portable Process Control Library

In operating systems which permit multiple independent processes to run and communicate there are several different notions of how the communication should work. An example is the difference between pipes and sockets. Even worse in the case of pipes is the fact that BSD Unix and System V Unix have substantial differences in the implementations of the pipe mechanism.

The abstract requirements of applications are more straightforward. A process should be able to spawn a subordinate process and open communications with it. The two processes should be able to exchange messages. The processes should be able to monitor one another’s status.

PPC defines and implements an API which embodies that simple model. Its interface is made as analogous as possible to the standard C file interface so that the experience which programmers have with files relates directly to interprocess communication. The details of whether pipes or sockets are used are substantially irrelevant to the application developer so long as the necessary functionality is there.

PPC is the least mature of the PACT tools. Ultimately, in conjunction with the binary data handling mechanisms of PDBLib, it will provide, in addition to interprocess communications (IPC) functionality, a highly efficient remote procedure call (RPC) capability. This will permit and facilitate the development of distributed applications in a portable manner.

See Also: PPC User’s Manual

Dependent PACT Libraries: SCORE, PDB

PML: Portable Mathematics Library

There are a great many numerical math libraries that are widely available. The PACT math library is more aimed at providing some useful mathematical structures, functions which deal with them, some geometry routines, interpolation functions, and the odd function from the standard C library which doesn’t work right on all platforms. It should be viewed as a supplement to some of the other available math libraries rather than a would be competitor. At a certain level, the portability issue does arise in that PML should work (and work the same) on all platforms while some math libraries are not so portable or available. The other parts of PACT which need a certain math routine cannot be held hostage to the availability of other libraries. These then are the basic considerations behind PML.

PML defines several structures to take advantage of C’s capabilities in that area. The effect that this produces on applications which use these mechanisms is one of simplifying the passing of data among functions, clarifying interfaces, and preventing certain classes of bugs. The main structures which PML defines are: complex numbers, matrices; sets; and mappings.

The matrix structure encapsulates an array of data with up to 2 dimensions. The set structure describes a collection of data elements in terms of type, set dimension, dimension of the elements, and other information. The mapping structure describes the generalization of a function which is an association of elements in a domain set with elements in a range set. The mapping is a nested structure containing pointers to two set structures.

These all are designed to be as mathematically faithful as possible. That means that they represent the fundamental abstract objects after which they are named. The sets and mappings in particular have a surprising application in the area of visualization. They turn out to be a good medium of exchange between data production systems such a simulation codes, data storage and transmission systems, and data visualization systems.

PML includes several useful matrix solvers. Some of these use the matrix structure and some of the sparse solvers do not. At this point, the math functions in PML have been more driven by specific needs than any systematic attempt at completeness. Perhaps in the future PML will be extended in this direction or perhaps a portable shell over some other math libraries will evolve.

See Also: PML User’s Manual

Dependent PACT Libraries: SCORE

PDB: Portable Binary Database Library

Binary data takes up about a factor of 3 less space than ASCII data and requires about a twentieth the time to read and write. Despite the obvious advantage of storing and transmitting binary data the majority of data is moved between dissimilar hardware/software platforms via ASCII format. The reason is that different hardware/software platforms use a variety of representations of binary data which are tuned to the hardware, operating system, or compiler on the platform.

PDBLib is a library which addresses the issue of binary data portability. It also offers unique facilities for handling structured data including pointers. Almost all solutions to the data portability problem employ a hub and spoke conversion method (e.g. Sun’s XDR) in which data is converted on output to a neutral format and converted to the host format on input. This is exactly what happens with ASCII data, that is ASCII is the neutral format. The conversion process is what takes most of the time difference between doing I/O with ASCII data and binary data. PDBLib’s approach only does conversions when necessary. In that way an application which will use its own data files or will give them to a machine of the same architecture will not do any data conversions thus saving the majority of the time difference between ASCII and binary I/O.

PDBLib supports structured data with a mechanism similar to the C struct mechanism. Since data objects as diverse as FORTRAN common blocks and C structs are representable by this means, PDBLib’s solution is a very general and flexible one. Furthermore, PDBLib supports the use of pointers, so that entire data trees can be read or written with a single PDBLib call. PDBLib is unique in this capability.

It is important to keep in mind that although there are many systems for handling portable binary data (e.g. HDF, netCDF, CDF, and FLUX) all of them have a particular set of requirements to address. PDBLib’s requirement is to be as general and flexible as possible. PDBLib is also the only tool of its kind which is an integral part of so far reaching a set of tools. Its integration with the PACT tools is a significant part of its flexibility.

PDBLib is especially designed to be inherently able to work with other languages. It concerns itself with issues such as array index ordering, and call by reference/call by value argument passing.

Another goal consistent with the portability of PDBLib is to be small enough to be useful on a small machine. The library has been used to real advantage on DOS and Macintosh PC’s.

See Also: PDBLib User’s Manual

Dependent PACT Libraries: SCORE

SCHEME: An Interpreter for the Scheme Dialect of LISP

The LISP programming language is one of the most powerful computer languages ever developed. Somewhat ironically, it is also one of the simplest to implement, at least to a certain level. Many applications would benefit by being able to provide their users with the ability to extend the application via a macro or scripting mechanism. LISP turns out to be ideal for this purpose. The language is syntactically simple and can be molded to meet a variety of needs. It also offers more power than most applications care to provide to their users, but one would rather be in that position than in having an underpowered extension mechanism.

Scheme is a lexically scoped, properly tail recursive dialect of the LISP programming language. The PACT implementation is described abstractly in Abelson and Sussman’s book, Structure and Interpretation of Computer Programs. It features all of the “essential procedures” described in the Revised, Revised, Revised Report on Scheme (Jonathan Rees and William Clinger, ed) which defines the standard for Scheme.

SCHEME is implemented as a library, however, a small driver delivers a stand alone Scheme interpreter. This is useful for people who want to learn the language as well as people who want to prototype algorithms (one of LISP’s strong points).

The PACT implementation features a reference counting incremental garbage collector. This distributes the overhead of memory management throughout the running of Scheme code. It also tends to keep SCHEME from trying to grab the entire machine on which it is running which some garbage collection schemes will attempt to do.

See Also: SX User’s Manual

Dependent PACT Libraries: PML, PPC, SCORE

PGS: Portable Graphics System

One of the biggest headaches for portability is graphics. The objective evidence is that the field is immature. One cannot exactly say that there are no graphics standards. The real problem is that there are too many standards. Until such time that the world settles down, there will be the need for a tool like PGS.

PGS is an API that is independent of the underlying host graphics system. All of the graphics portability headaches are confined to PGS and applications which use PGS are completely portable. PGS currently sits on top of X Windows on UNIX platforms, GRAFLIB on NLTSS, Quickdraw on Macintoshes, and Microsoft’s graphics library on DOS platforms.

PGS takes a least common denominator approach regarding what graphics functionality it supports. The goal is to run on the widest variety of machines. This lets out high level graphics capabilities such as real time 3D rotations which depend on specific hardware. On the other hand, any rendering capability that can be implemented with reasonable efficiency in software is fair game for PGS. This model will almost certainly change in time as both graphics hardware and software evolve and become ubiquitous across platforms.

PGS adopts a model in which graphics devices such as display windows and PostScript files are represented by a structure which contains all of their state information. Then PGS can manage an arbitrary number of devices simultaneously and any picture can be drawn to any device.

PGS also structures display surfaces with a viewport defined in normalized coordinates, an enclosing boundary where axes are drawn which is defined as a set of offsets from the viewport window, and a world coordinate system attached to the viewport. The enclosing boundary is useful for obtaining a standoff between rendered data such as line plots and the axes used to measure the rendering.

PGS supports both line and text drawing primitives, line and text attributes, and bit maps for handling images and other cell array data. Most functionality in PGS is either primitive operations such as moves and draws or at a very high level such as axis drawing and the rendering algorithms that it supports. These rendering algorithms have two interfaces: one for “raw” data; and one for PML type mappings. This gives a great deal of flexibility to the application developer.

PGS has the following rendering algorithms currently: 1D line plots; 2D contour plots; 2D vector plots; 2D image plots; 3D wire frame mesh plots (for 2D data sets); and Grotrian diagram plots.

See Also: PGS User’s Manual

Dependent PACT Libraries: PML, SCORE

PANACEA: Portable Simulation Code Development Environment

An analysis of numerical simulation codes will demonstrate a great deal of commonality. The goal of PANACEA is to implement everything that is generic to “all” numerical simulation codes once and for all. In doing this a model of numerical simulation codes is necessary as the context for defining a collection of services which defines the generic aspects of numerical simulation codes.

Some people like to refer to tools such as PANACEA as back-planes or shells. I think of PANACEA as an environment for code development. PANACEA is not so highly structured that it must be taken in its entirety or left alone. The notions of shell and back-plane are suggestive of that higher degree of structure. PANACEA can be used as just a library of routines (up to a point).

PANACEA provides the following general categories of services: definition and control of a database of simulation variables and packages; access control to the database; support for initial value problem generation; source and initial value data management; output/plot request handling; simulation control; units and conversion handling; and error handling.

PANACEA draws heavily on PDB and PML to provide its services. This gives it tremendous leverage in handling the database, state files, and output/graphics data files. This close coupling keeps the system small and compact while providing a fairly large range of services.

See Also: PANACEA User’s Manual

Dependent PACT Libraries: PDB, PML, SCORE

ULTRA II: 1D Data Presentation, Analysis, and Manipulation

ULTRA II is a tool for the presentation, analysis, and manipulation of 1D data sets or curves (i.e. y = f(x)). It supports operations such as addition, subtraction, multiplication, and division of curves; applying functions to curves (e.g. sin, cos); Fourier transforms; and shifting and scaling of curves. The user can control the range and domain of the displayed data as well as such attributes as line color, style, and width.

Either ASCII or binary data can be written or read by ULTRA II. ULTRA II uses the SCHEME interpreter to provide users with a very powerful mechanism to configure and extend ULTRA II to suit their needs. This also keeps the code small by not having to compile in everybody’s pet extension. Thus ULTRA II is extremely flexible.

See Also: ULTRA II User’s Manual

Dependent PACT Libraries: SCHEME, PGS, PDB, PML, PPC, SCORE

SX: Scheme with Extensions

SX is perhaps the ultimate PACT statement. It is simply SCHEME plus the other parts of PACT. A more precise way to describe it is as a dialect of LISP with extensions for PGS, PDB, PML, and PANACEA. What this yields is an interpretive language whose primitive procedures span the functionality of all of PACT.

Like the SCHEME implementation which it extends, SX provides both a library and a stand alone application. The stand alone interpreter is the engine behind applications such as PDBView and PDBDiff. The SX library is the heart of TRANSL a tool to translate data files from one database format to another. These examples demonstrate the extreme power of the PACT design. The modularization and layering make it possible to use the PACT components like building blocks.

In addition to the above mentioned functionality, SX contains functionality which is the generalization of that found in ULTRA II. This means that as the development of SX proceeds, an SX driven application will be able to perform arbitrary dimensional presentation, analysis, and manipulation tasks.

PDBView is a tool to examine the contents of PDB files. This may be done either by printing all or part of the entries in a PDB file or by displaying the data graphically. As such PDBView already performs the basic presentation tasks which the ULTRA II successor will have.

PDBDiff is a tool that does a binary comparison of two PDB files. The user can specify the precision of floating point comparisons, but by default PDBDiff uses the lesser of the two files’ precision in floating point comparisons. For example, comparing a CRAY generated file with 64 bit floats and a SUN generated file with 32 bit floats will be done to 32 bits not 64. PDBDiff can be run in either a batch or interactive mode. In batch mode it can be thought of as very similar to the UNIX diff utility. In interactive mode, the user can browse the files and compare all or part of arbitrary file entries.

See Also: SX User’s Manual

Dependent PACT Libraries: SCHEME, PANACEA, PGS, PDB, PML, PPC, SCORE

PACT Documentation

The individual components of PACT have their own documentation which is intended to give application developers and end users complete information about that component. It is important to remember that the parts of PACT are integrated so that they depend on one another. Consequently, it is assumed that readers of any PACT component document may need to refer to the documents for any component on which the desired component depends.

SCORE	none
PML	SCORE
PDB	SCORE
PPC	SCORE, PDB
PGS	SCORE, PML
SCHEME	SCORE, PML, PPC
PANACEA	SCORE, PML, PPC, PDB, PGS
SX	SCORE, PML, PPC, PDB, PGS, SCHEME, PANACEA
ULTRA II	SCORE, PML, PPC, PDB, PGS, SCHEME

The list of PACT Documents is:

PACT User’s Guide	UCRL-MA-112087	Current Document
SCORE User’s Manual	UCRL-MA-108976 Rev.1
PPC User’s Manual	UCRL-MA-108964 Rev.1
PML User’s Manual	UCRL-MA-108965 Rev.1
PDBLib User’s Manual	M-270 Rev.2
PGS User’s Manual	UCRL-MA-108966 Rev.1
PANACEA User’s Manual	M-276 Rev.2
ULTRA II User’s Manual	UCRL-MA-108967 Rev.1
PDBDiff User’s Manual	UCRL-MA-108975 Rev.1
PDBView User’s Manual	UCRL-MA-108968 Rev.1
SX User’s Manual	UCRL-MA-112315

Interested readers can obtain these documents from the author. Other sources that readers may find useful are:

    Abelson and Sussman, The Structure and Interpretation of Computer Programs, MIT Press

    Abramowitz, Stegun, Handbook of Mathematical Functions, Dover.

    Klinger, et. al., The Revised4 Report on the Algorithmic Language Scheme, MIT.

    Knuth, D.E. The Art of Computer Programming, vol I - III, Addison-Wesley.

    Press, Flannery, Teukolsky, and Vetterling, Numerical Recipes in C, Cambridge Press.

Availability of PACT Software

Platforms

The complete PACT distribution is currently running on the following platforms:

   CRAY XMP/YMP under NLTSS and UNICOS

   Motorola 68000 family under BSD and SYSV UNIX

   SPARC I under SUN OS 4.0 and higher

   MIPS R3000 under MIPS RISC OS, IRIX, and ULTRIX

   IBM RS6000 under AIX

   HP 700 under HPUX

   INTEL 80x86 under DOS

   Apple Macintosh family

The host graphics systems used are: the X Window System (X11 R3 and up), Quickdraw, and Microsoft Graphics library.

In the past parts of PACT have been ported to the following platforms:

   DEC VAX under ULTRIX and VMS

   INTEL 80x86 under SCO XENIX

These ports were not completed due to lack of access to the necessary computers.

Obtaining the PACT Distribution

The PACT distribution has been sent to NESC (now OSTI) and is available to U.S. Government contractors. Collaborations with other parties desiring to use PACT are welcome and inquiries should be directed to Stewart Brown at LLNL.

Source and Version Management

Portability obviously raises important issues in the implementation of PACT. Portability raises even larger problems in the context of source and version control. Portable codes aren’t portable until and unless they are built, tested, and used on multiple platforms. In practice there is a certain amount of sloshing of sources between platforms when a bug fix for one platform is propagated to all other platforms for validation. Sometimes a bug fix on one platform breaks the implementation on another.

This problem is compounded by having a team of people working on such a project. The best use of people is to have each person responsible for a distinct set of machines to which that person has permanent access. From the source and version management point of view this is the most difficult situation possible. The tools to support this sort of activity are not there from a portability point of view. The UNIX world can do quite nicely with CVS, but that may not help PC’s and other platforms which might give CVS trouble. Furthermore, the networking issues enter in forcibly. NFS with CVS works fine, but when sites have separate networks which don’t communicate,all of the headaches emerge even in the UNIX world!

This is an ongoing area of concern and work for the PACT system. The goal is to be able to do development work or fix bugs on a platform, have the work tested locally and “globally”, have the fiducial sources updated, and the binaries propagated to the greatest number of sites or distribution points. As much of this as possible should be automated. It is a crime to waste the people (note the plural) it will take to maintain a production quality PACT product on all platforms and sites.

PACT Manager

I refer to the scripts and programs which automate the check out, compilation, testing, check in, and distribution of a code system as the manager for that code system. PACT has an embryonic manager. It consists of scripts to obtain the sources from a CVS repository, set the configuration, build PACT either in part or completely, install PACT locally, and check the modified sources back in to the CVS repository.

The test suite for PACT is sketchy at best at this point and is an ongoing effort. It reflects the state of development of the entire source and version management process.

The remainder of this section is devoted to describing the UNIX based PACT manager. It is put forward as a model (the gaps will be mentioned) of a fully portable, distributed manager. The order in which the parts are presented doesn’t reflect their significance or their precise sequence. A manager is a thing with multiple branches and that makes a linear exposition difficult.

PACT Makefiles

The PACT manager uses a three part model of a Makefile which controls the construction of each PACT component. Each Makefile consists of: a part which is site dependent and contains all of the special paths for the entire installation process; a part which is specific to the PACT component; and a part containing common macros some of which are operating system dependent. These parts are referred to as make-def, pre-Make, and make-macro respectively. The pre-Make files reside with the PACT components whose compilation and installation they control. The make-def and make-macro files live with the manager. They are constructed in the configuration process.

PACT Manager Makefile

The manager Makefile has targets to build and install each PACT component separately or all together. It also has targets to remove the object files and libraries from all of the component directories. This is useful for conserving file space or for ensuring a clean build of PACT.

pact-config

pact-config configures the PACT Makefiles for the platform as described by the command line arguments. It makes the make-def and make-macros files appropriate to the platform and using build-make constructs all of the PACT Makefiles in each of the component directories. It also configures the binary file translation spokes for SX.

pact-update

pact-update takes the same basic arguments as pact-config. Its purpose is to extract the sources from the CVS repository, compile, and install the entire distribution for the system on which it is being run. This is for machines with network access to the CVS repository.

pact-dist

pact-dist extracts the PACT sources from the CVS repository, deletes any unnecessary files and directories (such as the CVS.adm directories), builds a tar file containing the entire PACT sources and the PACT manager, then deletes the sources. The net effect is a tar file of the entire PACT distribution which can then be shipped to other sites. The intended beneficiary is a site with no network access to the CVS repository.

utilities

Some utility scripts accompany the PACT manager. The version designation of PACT tools is given by the date. So, for example, a version built for release on October 23, 1991 would be version 10.23.91. This has been done so that version numbers mean something and help both the user and the developer to keep track PACT versions.

The script, code-date, runs the UNIX utility, date, and gets out a nice version of the date which has no undesirable zero’s. That is January 3, 1989 would have come out as 1.3.89 instead of 01.03.89.

The script for-pact, runs a single command in the directories associated with each PACT component except the manager. It is used by the manager Makefile and some of the other scripts. It also avoids directories which do not contain PACT sources.

The script, build-make, constructs the actual PACT Makefiles from the make-def, make-macros, and pre-Make files.

Installing and Using PACT

This section is intended for users who must do their own compilation and installation of the PACT system. The procedure varies from platform to platform and reflects the state of the tools in the vendor supplied computing environments.

DISCLAIMER: The installation procedures are evolving and I am aware of the rather crufty character of it all. They will be improved as time goes on and I welcome any input to its improvement or if anyone knows a good tool for this purpose which runs everywhere, please let me know.

If you must build PACT by hand, you will have to edit/re-create the Makefiles in each sub-directory, and run make over them by hand. This should be done in the order stated above: SCORE, PML, PPC, PDB, PGS, SCHEME, PANACEA, ULTRA, and SX.

UNIX

In the standard distribution each of the components resides in a subdirectory of the main pact directory. In addition there is a subdirectory called pact which contains various configuration files and shell scripts to automate the installation of PACT. In the following discussion, it will be assumed that there is a base directory called pact which is a subdirectory of some other directory such as /usr/local/src, so that when the directory score is referred to as pact/score, the directory /usr/local/src/pact/score is meant.

To make it as easy as possible to port/maintain/install PACT on a variety of systems, PACT uses the MAKE utility to control compilation, loading, and other tasks related to management of the system. Due to differences in operating systems and site installations, the PACT system uses a three part Makefile. The first part has site dependent information and this will be the same for all of the components of PACT. This part is called make-def and it resides in the directory pact/manager. The second part contains the specifics of the components and therefore each component of PACT has a separate file called pre-Make. In pact/score, pact/pml, pact/ppc, and so on there is a file called pre-Make which contains dependencies particular to those parts of PACT. The third part contains a number of macros and dependencies common to all of PACT but which depend on the operating system. This file is called make-macros and lives in the pact/manager directory.

The utility build-make in the pact/manager directory builds a Makefile from the make-def in pact/manager, the pre-Make in the component directory, and the make-macros in pact/manager. The utility pact-config automatically builds and invokes this for each component of the PACT system.

I have found the mechanism to be very simple and portable. I have used it in preference to such alternate mechanisms as Imake because it is much easier to manage and depends only on standard UNIX facilities.

To install PACT on a UNIX system:

• Obtain the distribution compressed tar file, pact.tar.Z, by some means and put it in a place such as /usr/local/src as follows:

     cd /usr/local/src
  

  and

     tar xvf /dev/rst8 
  

  or

     ftp <some host>
  

  or

     cp <somewhere>/pact.tar.Z .
  

• Un-compress and un-tar the distribution in a place such as /usr/local/src and get into the PACT configuration manager directory, manager, as follows:

     cd /usr/local/src
  

  then

     uncompress pact.tar
  

     tar xf pact.tar
  

  then

     cd pact/manager
  

• Next, build a <site>.config file for your installation. For example, if your host machine is foo with its various features, you should create a file “foo.config”. The “foo” base will be used by pact-config as described below. Use one of the supplied configurations (in pact/manager/configs) as an example and run pact-analyze to obtain some more information about your system.

     cd pact/manager
  

     pact-analyze -t
  

  Consult the list of configuration parameters and the syntax description listed below for more information about the configuration files and how to build them.

  NOTE: The utility pact-config used in the next section runs pact-analyze after reading your configuration file as part of the process of configuring PACT for your site.

  CAVEAT: C compiler and library implementations are not as uniform as one would like. In particular, it may be necessary to add declarations of functions and variables which PACT uses to your config file because the system header files leave them out. Use CDeclarations to do this.

• Configure the distribution as follows:

     pact-config <site>
  

  Where <site> is the identifier for the base of the local config file that was prepared in step (2). For example, if you’re at the host site, foo, type

     pact-config foo
  

  NOTE: If you want to ease a future update of PACT, make a directory outside of the PACT directory tree and save your custom configuration file (e.g. foo.config) there. Then when you update PACT with a new distribution, you can use pact-update and its -f option to use your custom configuration files. (Run pact-update with no arguments to get a brief description of its use.)

• Compile the distribution as follows:

     make pact
  

  or

     make pact >>& build.log
  

  In any case look over the log file or the tty screens carefully to see that everything is ok or to see what needs to be fixed for the installation to go forward.

  If there is a problem compiling some part of PACT and you change the sources to correct the problem, that part of PACT can be compiled from the pact/manager directory by doing a make on that part. For example, suppose that your compiler complained about something in ultra. You would do the following:

     cd ../ultra
  

     <edit and fix the appropriate files>
  

     cd ../manager
  

     make ultra
  

• Test the distribution as follows:

     make test
  

  If run in the manager directory, this runs all of the PACT tests; otherwise, it runs the test for the package of the current directory. It does not currently report its results in a systematic manner; however, tests either report failure, crash, or hang if they do not succeed.

  If you must build PACT by hand, you will have to edit/re-create the Makefiles in each sub-directory, and run make over them by hand. This should be done in the order stated above with SCORE first and ULTRA last.

CONFIGURATION FILE SYNTAX

The syntax of a configuration file is fairly simple. Blank lines and lines beginning with a ‘#’ signal the end of a section or are ignored. There are the following main section types: MakeRule, CEnvironment, CDeclarations, and VariableDef. The sections are begun by a line containing the section type. The default section type is VariableDef.

You can have any number of instances of the main sections and their specifications are all concatenated together. Specifications in the CEnvironment and CDeclarations sections result in #define’s and variable or function declarations in the scconfig.h file. MakeRule specifications allow sites to add targets and macro definitions to the make-def (and hence Makefile) files for the system. VariableDef specifications go into the construction of the make-def, trconfig.h, and spokes.scm files.

In addtion to the main section types there are the following special section types: .c.i:, .c.o:, .c.a:, .l.o:, .l.a:, .f.o:, and .f.a:. These are to define the make rules for preprocessing a C source file, compiling a C source file into an object file, compiling a C source file “directly” into an archive file (if your system’s make is capable of doing so), compiling a LEX source file into an object module, compiling a LEX source file directly into an archive file (make willing), compiling a FORTRAN source file into an object file, and compiling a FORTRAN source file directly into an archive file (make willing) respectively. These sections are began by a line containing the section name.

All sections are ended by blank or comment lines (lines beginning with ‘#’).

CONFIGURATION PARAMETERS DESCRIBED

This group of parameters is used by the configuration building and make processes to distinguish various operating system characteristics as well as the utilities which come with a UNIX/POSIX system.

Some of these are implied by PACT coding and are listed here to give you an idea of what they are for (just in case you need to look in the code).

BuildStrategy
UNIX systems with a sufficiently smart make can save lots of disk space by building the objects directly into library archives. Use “SpaceSaving” if your make is good enough and “none” otherwise. PACT-ANALYZE will detect this for you. Default is “SpaceSaving”.

CCompiler
The name of the C compiler to be used. Default is “cc”.

CDebug
C compiler flags to specify debuggable packages. Default is “-g”.

CFLAGS
C compiler flags to be used for all PACT packages. This is for those options which do not control debugging or optimization. Use CDebug or COptimize for those purposes. Default is ““.

COptimize
C compiler flags to specify optimized packages. Default is “-O”.

CSpokes
A list of C codes binary file translation spokes to be built with SX. An NACF spoke is included with the distribution. Default is is “nacf”.

FCompiler
The name of the FORTRAN compiler to be used. Default is “f77”.

FDebug
F77 compiler flags to specify debuggable packages. Default is “-g”.

FFLAGS
F77 compiler flags to be used for all PACT packages. This is for those options which do not control debugging or optimization. Use FDebug or FOptimize for those purposes. Default is ““.

FOptimize
F77 compiler flags to specify optimized packages. Default is “-O”.

GraphicsFlag
Any special graphics flag (not usually needed with X11). Default is ““.

GSYS
The host graphics system being used (almost always X). Default is “X”.

INSTALL
Place holder for either “install <options>” or “cp” depending on whether or not your system has install. Default is is “cp”.

InstBase
The directory in which the PACT manager expects to find lib, bin, and include directories into which to install PACT. Default is “/usr/local”.

LDFLAGS
Special loader/linker flags. Default is ““.

LXFLAGS
Flags for C compilation of LEX generated files. Default is “”.

MachDepGraphicsInc
Special specifications for the C compiler to find graphics related include files (e.g. -I/ usr/include/X11). This is not often needed. Default is ““.

MachDepGraphicsLib
Special specifications for graphics libraries to be loaded (e.g. /usr/lib/libX11.a). Default is ““.

MachDepInc
Special specifications for the C compiler to find non-graphics related include files (e.g. -I/usr/local/include). This is not often needed. Default is ““.

MachDepLib
Special specifications for non-graphics libraries to be loaded (e.g. -lbsd). Default is ““.

NEED_MEM_TRACE
PACT supports a layer of memory management over the system memory manager which provides diagnostic capabilities as well as useful features for applications. On some systems, PACT can understand the workings of the memory manager sufficiently to require a smaller amount of overhead and look more deeply in the system heap. Other systems are not so and PACT must do more bookkeeping work. Set this parameter to TRUE to indicate the latter case and FALSE to indicate the former. Default is “TRUE”.

RANLIB
Place holder for either “ranlib” or “touch” depending on whether or not your system has ranlib. Default is is “touch”.

RM
Place holder for “rm <options>” depending on the options your system’s rm has. Default is is “rm -f”.

SchemeSpokes
A list of Scheme coded binary file translation spokes to be used with SX. A netCDF spoke is included with the distribution. Default is is “netcdf”.

ScmDir
A directory in which to install scheme source files. This should also be a subdirectory of InstBase. Default is “scheme”.

UPDATE
Place holder for either “ranlib” or “touch” depending on whether or not your system needs ranlib to update archives which have been copied. Default is is “touch”.

C ENVIRONMENT PARAMETERS

This group of parameters is used in C header files to set up and define the C compilation environment for the PACT sources. These are specified in a CEnvironment section of a configuration file.

C Language Standard These parameters define which C standard is to be assumed when compiling PACT sources. Use at most one.

ANSI
Conforming to ANSI C (this is the default).

PCC
Conforming to the Portable C Compiler (KR 1rst edition).

FORTRAN Language Standard
ANSI_F77
Conforming to ANSI FORTRAN 77.

System Dependent Parameters Which Must Exist The following parameters are implied by other selected options:

byte
Type “void” if supported (default for ANSI compilers), type “char” if no voids (default for PCC compilers).

UNIX
UNIX/POSIX Operating System (as opposed to DOS or MAC).

X11R4
PACT uses X11 R4 or later graphics (implied by “GSYS = X”).

Other System Dependent Parameters
AIX
This indicates the presence of the IBM UNIX variant.

BINARY_MODE_R
Binary file mode parameter for read only mode. Default is “rb”.

BINARY_MODE_RPLUS
Binary file mode parameter for open for update mode. Default is “r+b”.

BINARY_MODE_W
Binary file mode parameter for create mode. Default is “wb”.

BINARY_MODE_WPLUS
Binary file mode parameter for create for update. Default is “w+b”.

BSD
This indicates the presence of BSD UNIX 4.2 or later.

DOS
This indicates the presence of IBM or Microsoft DOS.

FIXNUM
C type corresponding to FORTRAN integer defaults to long. Don’t set this.

HAVE_SELECT_P
Indicate the presence of a working “select” system call iff there is no working STREAMS package available. PACT-ANALYZE detects this for you.

HAVE_SOCKETS_P
Indicate the presence of a working socket library. Default is off. If you have X windows you have this.

HAVE_STREAMS_P
Indicate the presence of a working STREAMS package. Default is off. PACT-ANALYZE detects this for you.

HPUX
This indicates the presence of the HP UNIX variant.

MAC
This indicates the presence of Apple Macintosh OS.

MPW
This indicates the presence of MPW C 3.0 or later.

MSC
This indicates the presence of Microsoft C 5.0 DOS (16 bit) or later.

Register
Some C compilers take a dim view of the use of the register allocation specifier. Set to “register” if appropriate, and ““ if not. Default is ““.

SGI
This indicates the presence of Silicon Graphics machines.

SYSV
This indicates the presence of UNIX System V.

THINK_C
This indicates the presence of Symantec THINK C 5.0 and later

TURBOC
This indicates the presence of Borland C++ 3.0 DOS (16 bit) or later.

UNICOS
This indicates the presence of Cray Research C for UNICOS.

DOS

MAC OS