Installation Instructions: UNIX systems

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.

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


ftp.astro.caltech.edu

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://ftp.astro.caltech.edu/pub/pgplot/pgplot5.2.tar.gz.

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.

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.

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 (/XWINDOW, /XSERVE). You may also wish to include drivers for GIF files (/GIF, /VGIF) or some of the other printers.

    cd /usr/local/pgplot
    cp /usr/local/src/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:

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.

Note that the configuration files are for particular compilers, on particular operating systems. If, for example, you have set up your system so that the command f77 invokes the GNU g77 compiler, then you cannot use a configuration file designed for, say, a SPARC f77 compiler. You will have to create a special 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.,

    /usr/local/src/pgplot/makemake  /usr/local/src/pgplot  sun4

The first argument supplied to makemake is the name of the distribution directory. Note that when you run makemake, your current default directory should be the target directory, i.e., the directory in which you want to put the compiled library.

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

You should check that these files have been created, and you should also check that the list of drivers that makemake says that it found corresponds to those you selected in drivers.list.

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.

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 /XWINDOW and/or /XSERVE 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 /XWINDOW 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.

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)

Note: The installation procedure does not create a shared library for the C binding. If you want one, you can create it by hand using the appropriate commands for your system, e.g. for some versions of Linux,

  ld -shared -o libcpgplot.so --whole-archive libcpgplot.a

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      /xwindow

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.

Note: The installation procedure does not install the Tk demo correctly on Digital Unix (4.0B). The demos program pgtkdemo is unable to read command-line arguments. Use the following commands to compile and link the demo:

 cc -c -I`pwd` -I/usr/local/include pgtkdemo.c

  cc -o pgtkdemo pgtkdemo.o -L`pwd` -ltkpgplot -lcpgplot -lpgplot \
     -L/usr/local/shlib/alpha -ltk -ltcl -lX11 -lUfor -lfor -lm

(i.e., omit -Dmain=MAIN__ and use cc instead of f77 for the link step.)

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://www.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

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.