Appendix F. PGPLOT Installation Instructions

To install PGPLOT, you need to perform the following steps. These steps are described more fully below.

Copy the distribution file by anonymous ftp from Caltech.
Unpack the distribution file to create the ``PGPLOT distribution'' directory tree. This is identical for all implementations of PGPLOT and can be placed on any disk that is visible on the target system, including read-only network-mounted disks.
Create a writeable directory in which the PGPLOT library and associated files will be created. One such directory is needed for each different operating system and compiler combination (``target system'') that you wish to support. This should not be the same directory as the directory containing the source code.
Configure PGPLOT by selecting device drivers from the available list.
For supported operating systems, execute the supplied script to create the library and demonstration programs.
Run the demonstration programs on your selected devices and verify that they run satisfactorily.
Optionally, install and test the C binding for PGPLOT. This requires an ANSI C compiler (that understands function prototypes) and is not available on all systems.

Step 1: Copy the distribution file

Copy the distribution file by anonymous ftp from Caltech. Use anonymous ftp (user: anonymous, password: your id username@machine) to node astro.caltech.edu (131.215.240.1).

The distribution is available in either a compressed tar file (for UNIX systems) or a compressed backup saveset (for VMS systems). The contents of the two files are identical.

Issue the following ftp commands to retrieve the compressed PGPLOT tar file:

 
	cd pub/pgplot
	binary

To get the PGPLOT distribution:

EITHER:	get pgplot5.0.tar.Z
OR:	get pgplot5.0.backup.Z pgplot.backupZ

To get the VMS decompression software:

EITHER	get lzdcm.exe		[for VMS-VAX]
OR	get lzdcm_axp.exe	[for VMS-AXP]

The source code for the decompression program is available from DECUS (The Digital Equipment Computer Users Society), in the directory [LZCOMPRESS] on the ``DECUS Essential Tools Collection for OpenVMS'' CD-ROM.

Step 2: Decompress the files

UNIX systems:

User the standard UNIX decompress utility, and then extract the source code from the resulting tar file. This will create directory pgplot (and subdirectories) in the current directory. Make sure that your current directory is where you want to create the ``PGPLOT distribution'' directory tree.

	uncompress pgplot5.0.tar.Z
        tar xvf pgplot5.0.tar

VMS systems:

Define a ``foreign command'' to run the decompression program:

	$ decomp == "$disk:[dir]lzdcm.exe"

Do not omit the $ sign; replace disk:[dir] by the location of the exe file you copied by ftp. For VMS-AXP systems, use lzdcm_axp instead of lzdcm.

Then run it:

	$ decomp pgplot.backupZ pgplot.backup

Extract the source code with the VMS backup utility:

	$ backup/log pgplot.backup/save/select=[pgplot...] []

Step 3: Create the target directory

Create a writeable directory in which the PGPLOT library and associated files will be created. One such directory is needed for each different operating system and compiler combination (``target system'') that you wish to support, e.g.,

UNIX:	mkdir /usr/local/pgplot
VMS:	create/directory USR:[LOCAL.PGPLOT]

Do not try to create the PGPLOT library in the source directory.

Step 4: Select device drivers

Configure PGPLOT by selecting device drivers from the available list. First copy the file drivers.list from the distribution directory to the target directory, and then use a text editor to select device drivers. This file contains one line for each available device driver: delete the exclamation mark (!) at the beginning of the line to include the driver, or ensure that an exclamation mark is present if you want to exclude the driver. Many of the drivers can be used only on certain operating systems (see notes in drivers.list), so include only the drivers you plan to use. PGPLOT can later be reconfigured by restarting the installation at this step. Most installations should include: the null device (/NULL), PostScript printers (/PS, /VPS, /CPS, and /VCPS), Tektronix terminals (/TEK, /XTERM, and possibly other variants), and, if the X window system is available on the target, the X window drivers (/XWIN, /XSERV). You may also wish to include drivers for GIF files (/GIF, /VGIF) or some of the other printers.

UNIX:	cd /usr/local/pgplot
	cp /root/pgplot/drivers.list .
	vi drivers.list			(or use your preferred editor)

VMS:	set default usr:[local.pgplot]
	copy root:[pgplot]drivers.list []
	edit drivers.list

The PGPLOT distribution directory is here called /root/pgplot or root:[pgplot] by way of example.

Step 5 (UNIX systems): Compile the library

If your UNIX system is not one of the supported systems, see Porting PGPLOT, or consult tjp@astro.caltech.edu. If your system is supported, proceed as follows:

Make the target directory your current default directory, e.g.,
```
	cd /usr/local/pgplot
```
Execute the script makemake from the distribution directory: e.g.,
```
	/root/pgplot/makemake	/root/pgplot  sun4
```
The first argument supplied to makemake is the name of the distribution directory.
The second argument is the name of the operating system; if you omit it or supply an unrecognized name, makemake will indicate the allowed values (currently these include: aix alliant convex cray hp irix linux next osf1 sol2 sun4 ultrix vp2200).
On some operating systems, where more than one Fortran or C compiler is available, a third argument is required; usually this is composed of the two compiler names separated by an underscore. If you omit it, makemake will indicate the allowed values. Note that you need both a Fortran compiler and a C compiler to install PGPLOT.
Once you have supplied valid arguments, makemake may complain that it can't find the drivers.list file. Go back to step 4!
The script makemake generates a file makefile for subsequent use, a Fortran file grexec.f that calls the selected device drivers, and a text file rgb.txt that contains color definitions for use by routine PGSCRN. (If you already have a file rgb.txt, possibly modified with your own custom definitions, makemake does not modify it.) So at this stage you will have at least the following files:
```
	drivers.list
	grexec.f
	makefile
	rgb.txt
```
Now use the UNIX make command to compile the PGPLOT library following the instructions in makefile:
```
	make
```
By default, make will generate: an object-module library, libpgplot.a; a shareable library (if possible on the selected operating system), the binary PGPLOT font file grfont.dat, the demonstration programs pgdemo*, and a documentation file pgplot.doc. In addition, if the /XWIN and/or /XSERV driver was selected in step 4, it will generate a program pgxwin_server, and if the /XDISP driver was selected, it will generate a program pgdisp.
If this step proceeds satisfactorily, you may want to type
```
	make clean
```
to remove unneeded intermediate files. You will then have the following files in the current directory:
```
	drivers.list
	grexec.f
	grfont.dat		(binary font file)*
	libpgplot.a		(PGPLOT library)*
	libpgplot.so.1.4	(shared library, optional)*
	makefile
	pgdemo1 ... pgdemo12	(demonstration programs)
	pgdisp			(required by /XDISP driver)*
	pgplot.doc		(ASCII documentation file)
	pgxwin_server		(required by /XWIN driver)*
	rgb.txt			(color name database)*
```
If you want to copy the compiled version of PGPLOT to another directory, you must copy at least the files marked with an asterisk (*). The documentation file contains the PGPLOT subroutine descriptions, which are also available in the manual.
A documentation file in HTML format that can be displayed with Mosaic, Lynx, Netscape or another HTML reader can be created by typing:
```
	make pgplot.html 
```
This file is created by executing a perl program to extract the documentation from the source code. If you do not have perl installed on your system, you can access the file on the WWW at http://astro.caltech.edu/~tjp/pgplot/subroutines.html. You may need to edit the file pgplot/makehtml to include the correct commands for invoking perl on your system.

Step 5 (VMS systems): Compile the library

Make the target directory your current default directory, e.g.,
```
	set default USR:[LOCAL.PGPLOT]
```
Don't forget to first copy DRIVERS.LIST into the target directory and edit it to indicate which drivers are to be included in the PGPLOT installation.
Execute the script install.com from the VMS subdirectory of the distribution directory, e.g.:
```
	@root:[pgplot.sys_vms]install root:[pgplot]
```
The first argument supplied to install is the name of the distribution directory.
The install script issues messages as it proceeds: it usually takes quite a long time. It should generate the following files:
```
	DRIVERS.LIST
	GREXEC.F
	GRFONT.DAT
	GRPCKG.OLB
	GRPSHR.EXE
	GRPSHR.OLB
	PGDEMO1.EXE ... PGDEMO12.EXE
	PGXWIN_SERVER.EXE
	RGB.TXT
```
The script assumes that you have the current DEC Fortran and C compilers installed. A C compiler is required for XWDRIV and X2DRIV and the associated programs PGXWIN_SERVER and PGDISP, and for generating the C wrapper library CPGPLOT.OLB. If you don't have the DEC C compiler, the script will have to be modified.
The script may fail if you redefine any of the common DCL commands like PURGE or DELETE.
To install the PGDISP program (optional, required if you selected the /XDISP device driver):
```
	@root:[pgplot.sys_vms]install root:[pgplot] PGDISP
```
This adds one file, PGDISP.EXE. The PGDISP program sometimes gives compilation problems. Most of these are non-fatal warnings that can be ignored.
Unlike the UNIX installation procedure, the VMS installation procedure does not generate documentation. A list of subroutine synopses in VMS help format is available by anonymous ftp from ftp://astro.caltech.edu/pub/pgplot/pgplot.hlp. This file can be inserted in a help library with a DCL command like
```
	$ library/insert/help pgplot.hlb pgplot.hlp
```

Step 6: Run the demonstration programs

Run the demonstration programs on your selected devices and verify that they run satisfactorily.

Before running any PGPLOT program, you must ensure that the environment variable PGPLOT_DIR is correctly defined. This is the name of the directory in which PGPLOT will look for the files grfont.dat and rgb.txt (unless environment variables PGPLOT_FONT and PGPLOT_RGB are defined to override this default behavior), and, if needed, the X-window server program pgxwin_server:

UNIX csh:	setenv PGPLOT_DIR /usr/local/pgplot/
UNIX sh:	PGPLOT_DIR="/usr/local/pgplot/"; export PGPLOT_DIR
VMS dcl:	define PGPLOT_DIR usr:[local.pgplot]

It is also convenient, but not essential, to define a default PGPLOT device with environment variable PGPLOT_DEV, e.g.

UNIX csh:	setenv PGPLOT_DEV      /xwin

Other PGPLOT environment variables are described in the manual.

When using a UNIX shared library, you may also need to put the PGPLOT directory in your loader search path, defined in environment variable LD_LIBRARY_PATH.

To run a program in UNIX, type its name (with directory if the current directory is not in your path):

	./pgdemo1

To run a program in VMS, use the RUN command:

	run pgdemo1

All the demonstration programs prompt for a device name and type. Type a question mark ? to see a list of the available device types and verify that PGPLOT has been configured properly.

Points to check for: the PGPLOT program correctly reads the font file and displays superscripts, subscripts and special characters (pgdemo2); the PGPLOT program can read the color database (pgdemo10); on interactive devices, the cursor works correctly (pgdemo5, pgdemo6).

Step 7: Install the C binding

Optionally, install and test the C binding for PGPLOT. This requires an ANSI C compiler (that understands function prototypes) and is not available on all systems.

UNIX:	make cpg

This creates three files:

	cpgplot.h	(ANSI C header file)
	libcpgplot.a	(library containing the C binding)
	cpgdemo		(demonstration program)

VMS:	@root:[pgplot.sys_vms]install root:[pgplot] CPG

This creates three files:

	CPGPLOT.H	(ANSI C header file)
	CPGPLOT.OLB	(library containing the C binding)
	CPGDEMO.EXE	(demonstration program)

To test, run cpgdemo in the same way as the other demonstration programs.

Next: Appendix G