PGPLOT Installation
Instructions: UNIX systems
Version 5.2.0
Note: The following
instructions refer to two directories, the distribution
(source) directory which will
contain the PGPLOT source code directory tree,
and the target directory in
which the machine-specific libraries, data
files, and demonstration
programs will be created. It is recommended that
you create new, empty
directories for these. They should not be the same
directory. In the examples
below, these directories are named
/usr/local/src/pgplot
(distribution directory)
/usr/local/pgplot (target
directory)
but you can use any convenient
names. Unusual (root) privileges are not
required to install PGPLOT,
assuming you have write access to the
directories. A single
distribution directory can be used to install versions
of PGPLOT for different
architectures in different target directories.
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
get pgplot5.2.tar.gz
The text files in this
directory are also included in the tar file.
The distribution file can also
be fetched from URL
ftp://astro.caltech.edu/pub/pgplot/pgplot5.2.tar.gz.
2. Decompress the files
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.
cd /usr/local/src
gunzip -c pgplot5.2.tar.gz | tar xvof -
This example will create
/usr/local/src/pgplot and subdirectories.
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.,
mkdir /usr/local/pgplot
Do not try to create the
PGPLOT library in the distribution directory.
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.
cd /usr/local/pgplot
cp /root/pgplot/drivers.list .
vi
drivers.list
(or use your preferred editor)
Note: If you select either the
Motif widget driver (XMDRIV) or the Tk/Tcl
widget driver (TKDRIV), the
installation procedure will install additional
files and demonstration
programs. Do not select these drivers unless you are
planning to develop programs
that will use them. For further information see
the appropriate documentation:
* XMDRIV
* TKDRIV
5. Create the makefile
The PGPLOT installation
procedure for UNIX uses a script, called makemake,
to generate a standard UNIX
makefile for your operating system, compilers,
and list of selected PGPLOT
device drivers. Operating-system and compiler
information is obtained from a
configuration file. Configuration files are
available for the following
systems. If your configuration is not one of
those listed, or if you have
trouble using the generated makefile, see below
for information about creating
your own configuration file.
In the following table, Arg#2
is a code for the operating system, and Arg#3
is a code for the Fortran and
C compilers. For more information about the
supported systems, see the
file pgplot/sys_*/aaaread.me, where * stands for
one of the options for Arg#2.
Arg#2 Arg#3
------ ------
aix xlf_cc
alliant fortran_cc
bsd g77_gcc
convex fc_cc
cray cf77_cc
epix2
f77_cc (Control
Data EP/IX 2.x)
freebsd f77_cc
fujitsu uxpm_frt_cc
fujitsu uxpv_frt_cc
hp fort77_c89
hp fort77_gcc
irix f77_cc
linux absoft_gcc
linux f77_gcc
linux g77_elf
linux g77_gcc
next af77_cc
next f2c_cc
next g77_cc
next gf77_cc
osf1 f77_cc
osf1 f77_cc_shared
sol2
f77_cc (Solaris
2.x, SunOs 5.x)
sol2 f77_gcc
sol2 f90_cc
sol2 g77_gcc
sun4
f77_acc (SunOS 4.x)
sun4 f77_cc
sun4 f77_gcc
ultrix f77_cc
If your system is one of those
listed, 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 (Arg#2 from the
above table); if you omit it
or supply an unrecognized name, makemake will
indicate the allowed values.
On some operating systems,
where more than one Fortran or C compiler is
available, a third argument is
required (Arg#3 from the above table);
usually this is composed of
the two compiler names separated by an
underscore. If you omit it,
makemake will indicate the allowed values.
Once you have supplied valid
arguments, makemake may complain that it can't
find the drivers.list file. Go
back to step 4!
Example
% ../pgplot/makemake ../pgplot
sol2 f77_gcc
For additional information,
read file ../pgplot/sys_sol2/aaaread.me
Reading configuration file:
../pgplot/sys_sol2/f77_gcc.conf
Selecting uncommented drivers
from ./drivers.list
Found drivers GIDRIV NUDRIV
PPDRIV PSDRIV TKDRIV TTDRIV WDDRIV XMDRIV XWDRIV
Creating make file: makefile
Determining object file
dependencies.
%
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.) It also copies two Fortran
include files that will be
needed during compilation. So at this stage you
will have at least the
following files:
drivers.list
grexec.f
grpckg1.inc
makefile
pgplot.inc
rgb.txt
If your UNIX system is not one
of the supported systems listed above, create
your own configuration file in
the target directory, with name local.conf.
It is best to copy one of the
configuration files provided (from
pgplot/sys_*/*.conf, and then
edit it following the comments in the file.
The makemake procedure will
use local.conf if it exists in the current
directory, and if you do not
specify Arg#3. Note that you must still specify
Arg#2 (operating system). For
more information about configuration files,
see Porting PGPLOT, or consult
tjp@astro.caltech.edu.
6. Use `make' to compile the
code
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 ... pgdemo16 (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 requested XMDRIV or
TKDRIV, you will also have some of the following
files:
pgmdemo
(executable demo program)
libXmPgplot.a
(object library required by PGPLOT/Motif applications)*
XmPgplot.h
(header file required by PGPLOT/Motif applications)*
libtkpgplot.a
(object library required by PGPLOT/Tk applications)*
pgtkdemo
(executable demo program)
pgtkdemo.tcl
(script used by demo program)
tkpgplot.h
(header file required by PGPLOT/Tk applications)*
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.
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.
make cpg
This creates three files:
cpgplot.h (ANSI C header file)
libcpgplot.a (library containing the C binding)
cpgdemo
(demonstration program)
8. 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
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 (e.g., on Solaris 2.x), 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, type its
name (with directory if the current directory is
not in your path):
./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).
To test the PGPLOT Motif
widget driver, 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.
To test the PGPLOT Tk/Tcl
widget driver, type
pgtkdemo pgtkdemo.tcl
See the documentation for the
driver for more information.
9. Install documentation files
(optional)
The standard installation
procedure creates an ASCII text file containing
synopses of all the PGPLOT
subroutines: pgplot.doc.
A documentation file in HTML
format that can be displayed with a Web browser
or an 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 at URL
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.
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
10. Install the library of
obsolete routines (optional)
The library libpgobs.a
includes some obsolete PGPLOT routines. If you have
old programs that use these
routines, you can install the library by
make libpgobs.a
However, these routines will
not be included in future versions of PGPLOT,
so you should rewrite your
programs to avoid their use.
----------------------------------------------------------------------------
PGPLOT
Tim Pearson, California
Institute of Technology, tjp@astro.caltech.edu
Copyright © 1997
California Institute of Technology