Appendix F. PGPLOT Installation Instructions

Version 5.1.0 or 5.1.1.

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

  1. Copy the distribution file by anonymous ftp from Caltech.
  2. 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.
  3. 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.
  4. Configure PGPLOT by selecting device drivers from the available list.
  5. For supported operating systems, execute the supplied script to create
     the library and demonstration programs.
  6. Run the demonstration programs on your selected devices and verify that
     they run satisfactorily.
  7. Optionally, install and test the C binding and/or Motif driver. 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 file is a UNIX tar file compressed with Gzip. Issue the
following ftp commands to retrieve the file:


        cd pub/pgplot
        binary

To get the PGPLOT distribution:

        get pgplot5.1.tar.gz

Step 2: Decompress the files

UNIX systems:

Use Gunzip and tar to decompress the archive and extract its contents. 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.

        gunzip -c pgplot5.1.tar.gz | tar xvof -

VMS systems:

You will need two programs to decompress and extract the contents of the
distribution file: gunzip and vmstar. These programs are not part of VMS,
but are widely available on the Internet. Use gunzip to decompress the
distribution file, e.g.,

        $ gunzip pgplot.targz

(Substitute the name of the file that you copied in the ftp step). Then use
vmstar to extract the contents of the archive:

        $ vmstar/extract/verbose pgplot.tar

This will create a subdirectory [.PGPLOT] (and lower-level subdirectories)
in the current directory. Make sure that your current directory is where you
want to create the ``PGPLOT distribution'' directory tree.

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.

If you are upgrading from 5.1.0 to 5.1.1, you can keep the same drivers.list
file.

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:

  1. Make the target directory your current default directory, e.g.,

             cd /usr/local/pgplot

  2. 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 freebsd 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!

  3. 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

  4. 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            (shared library, optional)*
             makefile
             pgdemo1 ... pgdemo14    (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.

     Solaris 2.x users should define environment variable LD_LIBRARY_PATH (a
     list of directories) to include the directory that contains the PGPLOT
     shared library.

  5. 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 first line of file pgplot/makehtml to include the correct
     commands for invoking perl on your system.

  6. A documentation file in LaTeX format (Appendix A of the manual) can be
     created by typing

             make pgplot-routines.tex

     This file is also created by executing a perl program to extract the
     documentation from the source code. You may need to edit the first line
     of file pgplot/maketex to include the correct commands for invoking
     perl on your system. To print this file, you will need to run LaTeX to
     create a dvi file and a dvi interpreter to print it, e.g. (on Unix
     systems)

             latex pgplot-routines
             dvips pgplot-routines -o

Step 5 (VMS systems): Compile the library

  1. Make the target directory your current default directory, e.g.,

             set default USR:[LOCAL.PGPLOT]

  2. 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.

  3. 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 ... PGDEMO14.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.

  4. 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.

  5. Unlike the UNIX installation procedure, the VMS installation procedure
     does not generate documentation. A list of subroutine synopses is
     available in a variety of formats by anonymous ftp from
     ftp://astro.caltech.edu/pub/pgplot/DOC/:
        o pgplot.doc plain ASCII file
        o pgplot.hlp VMS help format
        o pgplot.html HTML (WWW) format
        o pgplot.ps PostScript (68 pages)
     The help file can be installed in a VMS help library with a DCL command
     like the following:

             $ 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.

Step 8: Install the Motif support and example files [optional]

Available only in PGPLOT v5.1.0 and later versions.

If you plan to develop Motif applications that use the PGPLOT widget, or if
you want to inspect a sample Motif application, you will need to do this
step. You must first: (a) ensure that the Motif header files and libraries
are installed on your system; (b) select XMDRIV in drivers.list before
installing the PGPLOT library [step 4]; and (c) install the C binding [step
7].

UNIX

In Unix installations, the Motif support files and demonstration program are
automatically installed by make if you have selected XMDRIV in drivers.lis
before running makemake, and if Motif is installed on your system. The
following files are installed:

        pgmdemo         (executable demo program)
        libXmPgplot.a   (object library required by PGPLOT/Motif applications)
        XmPgplot.h      (header file required by PGPLOT/Motif applications)

To test, run pgmdemo in the same way as the other demonstration programs.
You must first ensure that an X-window display is available and that
environment variable PGPLOT_DIR is correctly defined.

VMS

Execute the folliwing command:

@root:[pgplot.sys_vms]install root:[pgplot] PGMDEMO

This creates five files:

        PGMDEMO.EXE     (executable demo program)
        PGMOTIF.OPT     (linker options file for linking PGPLOT/Motif applications)
        PGXWIN.OBJ      (object module required by PGPLOT/Motif applications)
        XMPGPLOT.OBJ    (object module required by PGPLOT/Motif applications)
        XMPGPLOT.H      (header file required by PGPLOT/Motif applications)

To test, run PGMDEMO in the same way as the other demonstration programs.
You must first ensure that an X-window display is available (use
CREATE/DISPLAY if necessary) and that logical name PGPLOT_DIR is correctly
defined.

(This step may not work on all VMS systems: there are many differences
between the various available versions of the DEC C compiler and DECwindows
Motif. If you get error messages, you may need to modify file
[pgplot.sysvms]make_pgmdemo.com.)

----------------------------------------------------------------------------
Next: Appendix G
----------------------------------------------------------------------------
PGPLOT
Tim Pearson, California Institute of Technology, tjp@astro.caltech.edu
Copyright  1996 California Institute of Technology
