A Field Guide to Installing PACT on UNIX Systems PACT (Portable Application Code Toolkit) is a set of libraries and utilities to facilitate the development of portable software systems. It has a bias toward scientific and engineering applications especially in terms of the data handling services. Consult the PACT User's Guide which is included in the document distribution for some additional information. I can be reached at 510-423-4889 during business hours (9-5 Pacific Time), if you have questions on PACT and its installation. WWWeb: http://www.llnl.gov/def_sci/pact/pact_homepage.html TO INSTALL PACT 0) Obtain the distribution file (e.g. pact10_7_93-src) by some means and put it in a place such as /usr/local/src as follows: -> cd /usr/local/src -> tar xvf /dev/rst8 or ftp or cp /pact10_7_93-src . -> chmod a+x pact10_7_93-src You do not want to have a subdirectory of the directory in which you have put the distribution file named pact. The installation process will mangle it thoroughly if you do! For the rest of this document the distribution file will be called pact-src (you may or may not want to rename it to this). If you have obtained the PACT documents as well as the distribution (e.g. pact10_7_93-doc.tar.Z), you may wish to get them out and start printing the ones of interest before proceeding on to the installation which may take minutes to hours. -> mkdir pact-docs -> mv pact10_7_93-doc.tar.Z pact-docs/pact-doc.tar.Z -> cd pact-docs -> uncompress pact-doc.tar -> tar xvf pact-doc.tar -> lpr .ps ... 1) After reading the section "PACT DISTRIBUTION BUILDER DESCRIPTION" below, run the distribution file (the C Shell must be installed on your system). Running the distribution file without arguments will give you a usage summary. Select the arguments you wish and run it again. For example: -> pact-src . . . -> pact-src -i /usr/local/pact auto This does the following things: configures the distribution, compiles all packages, runs all of the PACT tests, and finally installs it in the designated place (unless "-i none" is used). The directory designated for installation, if any, must contain at least the following subdirectories: include, bin, lib, and scheme. On a fast machine all of the above will take a few minutes and on a slow machine it will take a few hours. Although the amount of disk space which PACT takes up varies here are some rough guidelines for a RISC system (CISC systems will use less space): PACT Executables: 8 MBytes PACT Libraries: 12 MBytes Other PACT Files: 1 MByte As the installation proceeds, most messages from component programs and scripts are routed into a file called Build.Log. When the installation completes the name is changed to .BUILD and the file is moved up one directory level so as to be out of the way in case another attempt or a build on a different system is to be done next. You may wish to check this file for problems or information about the process itself. There should be no error or warning messages in a normal installation. 2) If the installation failed skip over to step (3). Now that PACT is installed. You need to set two environment variables in order to use ULTRA, SCHEME, SX, PDBVIEW, or PDBDIFF. The SCHEME and ULTRA environment variables must be set to point to the directory in which the scheme files were installed. The default for this directory is /usr/local/scheme and in the above example it would be /usr/local/pact/scheme (see the SCMDir variable if in doubt). -> setenv SCHEME /usr/local/pact/scheme -> setenv ULTRA /usr/local/pact/scheme These should probably be put into your .cshrc or your .profile so that they appear when you log into your system. The PACT documentation has additional information about these environment variables. This example will serve to get you started. 3) If everything has completed successfully, you are done and PACT is installed on your system. Otherwise you have some work cut out for you. Here is some guidance for trouble shooting. We start off with a partial list of assumptions (we try to have as few of these as possible). ASSUMPTIONS ABOUT UNIX SYSTEMS A) You have configured your environment for code development. This means that you have your path set to find compilers and debuggers, that your manpath is right to access man pages on development tools such as the compiler. If you don't know your own system PACT-CONFIG certainly can't be expected to either. It uses your environment ($path, etc) to know where to find what it needs to know. B) You have the CSH on your system. If you do not have the C Shell on your system you can obtain csh or tcsh on the Internet. C) You have X Windows on your system. If you do not have it, either get it or work around the graphical applications (ignore complaints about compiling or loading the graphical components of PACT). This assumption is one we plan to remove. D) We have had trouble in the past when "." was not on the default CSH path. This is a system wide thing which you cannot control by adding "." to the path in your private .cshrc. We think we have this taken care of and if you find out differently let us know. E) Use /bin/make in preferrence to GNU make. GNU make's defaults are bizarre for PACT's needs and it is difficult to work with. If you absolutely must use GNU make you may wish to look at linux.config for some guidance on make rule adjustments aimed at GNU make. (If anybody out there knows how to get rid of the messages about entering and leaving directories we would like to know - it's a small side point which is extremely annoying) WHAT TO DO TO GET PACT TO BUILD A) Read the sections below to orient yourself to the organization of PACT. PACT will probably compile and load correctly if you can create a good configuration file. That should be your first thrust. If you can't get PACT to configure you can try to create the Makefiles in each sub-directory, and run make over them by hand. This should be done in the order stated below with SCORE first and ULTRA last. B) If PACT fails to configure itself, you will need to build a configuration file as follows: i) Build a .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.std) 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 below for more information about the configuration files and how to build them. NOTE: The utility PACT-CONFIG which you will use in step (ii) runs PACT-ANALYZE also after reading your configuration file. 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 configuration file because the system header files leave them out. Use CDeclarations to do this. ii) Configure the distribution as follows: -> pact-config Where is the identifier for the base of the local configuration file that was prepared in step (i). 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 file. (Run PACT-UPDATE with no arguments to get a brief description of its use.) iii) Follow the instructions which PACT-CONFIG prints out and source the file env-xxxxx (which is written by PACT-CONFIG) into your environemnt. This sets up your environment to work with the configuration of directories for a particular platform which the PACT-CONFIG creates. For example suppose this is being done on a system running Linux 1.0.8 -> source env-lnx-1.0.8 If you are going to work with the PACT sources beyond simply installing the PACT system, you may wish to add the contents of env-xxxxx to your .cshrc (with suitable conditions). Do this only if you are confident that you understand what env-xxxxxx does! iv) Then do: -> pact build C) 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 in two different ways: first, from the pact/manager directory by doing a pact on that part; and second, in the source directory by doing pact install. For example, suppose that your compiler complained about something in ultra. You would do the following: -> source env-xxxxx -> cd pact/ultra Then you would do the one of the following: -> pact install -> cd ../manager or -> cd ../manager -> pact ultra D) Test the distribution as follows: -> cd pact/manager -> pact test E) Even if there are problems with some parts of PACT you can still install it so that you can use the functioning parts. To do so type the following: -> cd pact/manager -> install-pact MULTIPLE PLATFORM INSTALLATIONS If you have a network setup in which you have a single network path (independent of node) to the PACT sources, you can build PACT for each machine type on your net by doing an appropriate PACT-CONFIG on each different platform. This creates separate bin, lib, include, and scheme directories for each platform and keeps machine dependent files (libraries, executables, etc) out of the source directories and in the machine dependent ones. Perform the following steps (assuming for example that the sources are in /usr/local/src/pact on all platforms): 1) Follow the instructions in TO INSTALL PACT and install PACT on one system. 2) For each additional platform: a) log onto the platform (telnet, rlogin, rsh, etc) -> rlogin b) go into the manager directory (pact/manager) -> cd /usr/local/src/pact/manager c) do a pact-config auto -> pact-config auto d) source env-xxxxx To make this work you must follow the instructions which PACT-CONFIG prints out and source the file env-xxxxx (which is written by PACT-CONFIG) into your environemnt. This sets up your environment to work with the configuration of directories for a particular platform which the PACT-CONFIG creates. For example suppose this is being done on a system running Linux 1.0.8 -> source env-lnx-1.0.8 If you are going to work with the PACT sources beyond simply installing the PACT system, you may wish to add the contents of env-xxxxx to your .cshrc (with suitable conditions). Do this only if you are confident that you understand what env-xxxxxx does! e) do a pact update to compile, test, and install PACT -> pact update This should be all that is required for this platform! If any there are any problems with (2-c) or (2-e) see the trouble shooting discussion in the TO INSTALL PACT section. NOTE: This is a new feature and we hope to improve it in coming releases; however, it is oriented toward the C shell at this point and if you are using another shell you will have to jump in and understand what is going on in order for everything to work properly. PACT DISTRIBUTION BUILDER DESCRIPTION The PACT distribution is a C shell script prepended to the compressed tar file containing the PACT sources. In this fashion the distribution is self-extracting, self-configuring, self-compiling, self-testing, and self- installing. Recognizing that there is a certain minimal set of information which the installer may wish to specify, the distribution file takes command line arguments. The script will write a log file called Build.Log which should be monitored (using tail -f) for problems in the build. Here is a synopsis of the distribution file. Usage: pact-src [-b ] [-c] [-f ] [-i ] [-k] [[+-n ] | [-s]] [-t ] -b When builing PACT, which can take a while, the installer may wish to turn to other tasks. The -b flag causes the compilation to occur in the background and to have mail sent to the designated address when the compilation, testing, and installation are complete. -c Stop after configuring the distribution. -f It is possible, even likely, that each site at which PACT is installed will have its own configuration file. It is a bad idea to keep this configuration file with the PACT sources since they may be deleted. The -f flag is used to tell the distribution where to find your configuration file. -i By default the distribution file will try to install PACT in /usr/local. If you want it to be installed off of another directory, use the -i flag to specify the alternate base directory. A value of "none" will cause PACT to be compiled and tested but not installed. The installation will warn you of required sub-directories (e.g. include, bin, lib, scheme) which do not exist (even if only in the log file). -k When updating PACT you may or may not want to remove any old sources. The default behavior is to remove them. The -k flag causes the old sources to be kept. -n,+n Once PACT has been installed at a site, it can be updated from a distribution that is available via anonymous FTP in the pub directory on any internet node. This means that new postings of distributions can be conveniently built at your site. The -n flag updates PACT without also updating the documentation while the +n flag simultaneously updates PACT and its documentation. -s The sources are out and only need to be configured. -t PACT can be updated if you have a compressed tar file containing the sources. This method is older and more error prone than using the distribution file directly, but is still supported. The file specified may be compressed or uncompressed. In any case, it should be specified as something such as pact.tar, i.e. if you have pact.tar.Z type -t pact.tar. This is the configuration for the installation. Known configs are: auto detects the system configuration aix IBM RS6000 systems hp HP RISC 700 systems irix SGI systems irix64 64 bit SGI systems running IRIX64 6.x linux LINUX systems meiko MEIKO solaris systems mips MIPS OS systems osf OSF systems osfg OSF systems with GCC solaris Sun Solaris systems sun standard Sun systems sung Sun systems with GCC t3d CRAY t3d systems ultrix DEC ULTRIX systems unicos CRAY UNICOS systems If you supply your own configuration file its name must be of the form site.config. For example, create a file foo.config in ~/myconfig with your configuration for site foo, and do: pact-src -f ~/myconfig foo NOTE: the distribution installation process assumes that the umask may not be appropriately set for the purpose of installing PACT. It therefore sets the umask to 002. BACKGROUND AND ORGANIZATION OF PACT PACT includes the following software libraries and applications: SCORE - a low level, environment balancing library PML - a portable math library PDB - a portable binary data base management library PPC - a portable process control library PGS - a portable graphics library PANACEA - a portable numerical simulation code development system SCHEME - a portable Scheme interpreter SX - Scheme with extensions (PDBVIEW is an SX program) ULTRA - a 1d presentation, analysis, and manipulation application In the standard distribution each of the components resides in a subdirectory of the main pact directory. In addition there is a subdirectory called manager 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. 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 are pre-Make files which contain 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. The utility PACT runs builds the Makefile from these pieces, runs MAKE over it, then deletes the Makefile. The reason for the deletion is that the Makefile has system dependencies and in the context of multi-platform builds such a file cannot persist indefinitely lest it interfere with the Makefile from another platform. The files make-def and make-macros are built for you automatically using a few pieces of information supplied in your configuration file (see below) and live in the dev//include directory thereafter. 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. 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 addition 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 begun 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 the PACT coding and are listed here to give you an idea of what they are there for (just in case you need to look in the code). ArcInstOpt The options needed by ar to run correctly and quietly in the process of building PACT. These can depend on other configuration parameters. Default is "rsc". 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 coded binary file translation spokes to be built with SX. An NACF spoke is included with the distribution. Default is "nacf". ExtensionBinaries Any local extensions that need to be installed with PACT. Default is "". 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". FrontEnd On some systems (particularly parallel machines) the target codes are cross-compiled and must be run in a special way by the front end machine. This is used to execute the target appropriately. Default is "". GraphicsDevices Host graphics systems/devices available. Current possibilities are PS and CGM (PostScript and Computer Graphics Metafile) are generic to all systems. X, GL, XGL, SUN, and PEX (X Windows System, SGI's GL, SUN's latest, SUN's suncore, and Phigs Extension to X) are usually to be found only on UNIX based systems. BGI and MSC (Borland Graphics Interface and Microsoft Graphics Library) are for DOS based systems. QD (QuickDraw) is on Apple Macintosh systems. Default is "PS CGM". GraphicsFlag Any special graphics flag (not usually needed with X11). Default is "". INSTALL Place holder for either "install " or "cp" depending on whether or not your system has install. Default is "cp". InstBase The directory in which the PACT manager expects to find lib, bin, include, and scheme 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 "". NoExe On some systems (particularly parallel machines) the target codes are cross-compiled and must be run in a special way by the front end machine. In this situation it may be pointless to build the PACT executables but necessary to build the libraries. If this is TRUE then no executables will be linked and installed (e.g. no ULTRA or SX). Default is "FALSE". PubInc Specification for C compiler to find PACT include files in some public directory. This is primarily used for developers who are working on a single package but need headers from other parts of PACT. This follows the InstBase variable by default so any resetting of PubInc must come after the last setting of InstBase (e.g. -I /home/pact/include). Default is "-I /usr/local/include". PubLib Specification for the loader to find PACT library files in some public directory. This is primarily used for developers who are working on a single package but need libraries from other parts of PACT. This follows the InstBase variable by default so any resetting of PubLib must come after the last setting of InstBase (e.g. -I /home/pact/lib). Default is "-I /usr/local/lib". 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 and FALSE the former. Default is "TRUE". RANLIB Place holder for either "ranlib" or "touch" depending on whether or not your system has ranlib. Default is "touch". RM Place holder for "rm " depending on the options your system's rm has. Default 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 "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 "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. C Language Standard These parameters define which C standard is to be assumed when compiling PACT sources. This is determined for you by PACT-ANALYZE from the compiler. ANSI Conforming to ANSI C (this is the default). PCC Conforming to the Portable C Compiler (KR first 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 (goes with GraphicsDevices). Other System Dependent Parameters AIX This indicates 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 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 an SGI machine. SYSV This indicates the presence of UNIX System V. THINK_C This indicates the presence of Symantec THINK C 5.0 or 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.