PGPLOT > Documentation > User's Manual > Compiling, Linking, and Running

Compiling, Linking, and Running

Any Fortran or C program must be compiled and linked with its necessary support libraries before it can be run. The commands required to do this differ greatly from system to system, but you should already be familiar with them. The following paragraphs describe some special considerations for PGPLOT programs.

PGPLOT programs have special requirements at run time, which are described below. In particular, if you are using a shared library, you need to ensure that the system can find the library at run time. You also need to ensure that the program can find the PGPLOT font file which it needs in order to draw characters (text).

Some aspects of the behavior of PGPLOT programs can be changed by defining environment variables before running the program. These are also described in this chapter.

Compiling and Linking a Fortran-77 Program

Some examples, assuming the source code is in a file called pgprog.f:

Compiling and Linking a Fortran-95 Program

Although the PGPLOT subroutines are written using Fortran-77 conventions and do not take advantage of the new features in Fortran-90 or Fortran-95, they can be called directly from Fortran-90/95 programs.

If the PGPLOT library has been compiled with the Fortran-90 compiler, compiling and linking are straightforward:

f95 -o pgprog pgprog.f90 -L/usr/local/pgplot -lpgplot

If, on the other hand, the library has been compiled with a Fortran-77 compiler, as is commonly the case, you will need to link with the Fortran-77 support libraries. The names and locations of these libraries are system- and compiler-dependent. For the Sun/Solaris compilers, the following should work:

f95 -o pgprog pgprog.f90 -L/usr/local/pgplot -lpgplot -lF77

Compiling and Linking a C Program

Some examples, assuming the source code is in a file called pgprog.c:

Compiling and Linking a C++ Program

This is even more difficult than compiling a C program, because you must ensure that both the C++ support libraries and the Fortran support libraries are included. The example above (using g77) can be adapted for the GNU C++ compiler (g++) on Solaris and Linux; for other compilers, you may need to consult an expert.

g++ -o pgprog -I/usr/local/pgplot pgprog.cc -L/usr/local/pgplot/ \
  -lcpgplot -lpgplot -L/usr/local/lib/gcc-lib/sparc-sun-solaris2.6/2.8.1/ \
  -lf2c -lgcc -lm
g++ -o pgprog -I/usr/local/pgplot pgprog.cc -L/usr/local/pgplot/ \
  -lcpgplot -lpgplot  -lg2c -lgcc

Shared Libraries

On some systems, PGPLOT can be created as a shared library. This means it is only loaded into the program at run time, saving disk space in the executable file, and may also mean that several programs running at the same time can share a single copy of the library in memory.

The main drawback of shared libraries is that they can get separated from the program that needs them; e.g., if you copy the compiled program to another machine, you will also need to copy the library (unless it is already installed). On some systems, special care is required to ensure that the run-time system can find the library when it needs it.

On UNIX systems, the shared library (named libpgplot.so on most systems, but the extension may be different on yours) must be placed in one of the directories automatically scanned by the run-time loader (such as /usr/lib); if not, the directory containing the library should be named in the colon-separated list of directories specified by the environment variable LD_LIBRARY_PATH, e.g.

LD_LIBRARY_PATH="/usr/local/pgplot"; export LD_LIBRARY_PATH (sh)
setenv LD_LIBRARY_PATH /usr/local/pgplot (csh)

Take care when defining LD_LIBRARY_PATH to include directories that other programs may need to search, as well as the PGPLOT directory. Not all UNIX systems use LD_LIBRARY_PATH: see the documentation for your system. On some systems, you can use the -R option (or an equivalent one) of ld to specify a search directory for the library when you link the program; then the search directory is attached to the executable program and doesn't need to be specified by LD_LIBRARY_PATH.

On VMS systems, the shared library GRPSHR.EXE must be placed in a standard directory (SYS$LIBRARY), or you must define a logical name to point to the location of the library, e.g.,

$ DEFINE GRPSHR USER:[PGPLOT]GRPSHR.EXE

The logical name may be defined system-wide (system logical name) or for a specific user (process logical name, usually defined in LOGIN.COM).

The PGPLOT Font File

Any PGPLOT program that draws text needs to read a font file at run time; if it cannot find the file, no text will be drawn, and a warning message will be issued. Usually the font file is called grfont.dat and is placed in the same directory as the PGPLOT library. If you use routine PGSCRN, the program also needs to read file rgb.txt. You tell PGPLOT where to find both files by defining an environment variable giving the name of the directory containing the files:

The definitions may be placed in a startup file such as .cshrc or login.com. For other ways to locate the files, see the next section.

Environment Variables

Some aspects of the behavior of PGPLOT can be modified at run time by specifying environment variables. The variables have names which begin with PGPLOT_.

In UNIX systems, environment variables can be defined using the shell. For the bash, bourne (sh), or korn (ksh) shell, use commands like the following:

PGPLOT_DIR="/usr/local/pgplot"; export PGPLOT_DIR

For the c-shell and tcsh, use

setenv PGPLOT_DIR "/usr/local/pgplot/"

Note that the names of PGPLOT environment variables are specified using upper case characters, e.g. PGPLOT_DIR, not pgplot_dir.

In VMS systems, environment variables are ``logical names'' and can be defined with the DEFINE or ASSIGN command, e.g.

$ DEFINE PGPLOT_DIR user_disk:[local.pgplot]
$ DEASSIGN PGPLOT_DIR

The following environment variables affect all PGPLOT programs:

PGPLOT_DIR
Directory name. Unless told otherwise by environment variables PGPLOT_FONT and PGPLOT_RGB, PGPLOT looks for the files it needs at run-time in this directory. The binary font file is grfont.dat and the color-name database is rgb.txt. If this variable is undefined, or if the specified file does not exist in this directory, PGPLOT looks in the current default directory. e.g.
setenv PGPLOT_DIR /usr/local/lib/pgplot/
PGPLOT_FONT
File name for the binary font file. If this variable is defined, PGPLOT will interpret the value as a file name for the binary font file. If it is not defined, PGPLOT will look for the binary font file under name grfont.dat in the directory specified by PGPLOT_DIR. e.g.
setenv PGPLOT_FONT /usr/local/pgplot/grfont.dat
PGPLOT_RGB
File name for the color-name database. If this variable is defined, PGPLOT will interpret the value as a file name for the color-name database. If it is not defined, PGPLOT will look for the binary font file under name rgb.txt in the directory specified by PGPLOT_DIR. The color-name database is only used by programs that call PGSCRN, or when environment variable PGPLOT_BACKGROUND or PGPLOT_FOREGROUND is defined. e.g.
setenv PGPLOT_RGB /usr/local/pgplot/rgb.txt
PGPLOT_DEV
Device specification. If this variable is defined, it is used as the default device specification: if the device specification given to PGOPEN (or supplied by the user in response to the PGPLOT prompt) is a blank string, this device specification is used, e.g.
setenv PGPLOT_DEV /xwin
PGPLOT_TYPE
Device type. If this variable is defined, it is used as the default device type: if the device specification supplied to PGOPEN consists of a file name without a trailing slash (/) and device type, this device type is assumed. e.g.
setenv PGPLOT_TYPE ps
PGPLOT_ENVOPT
Character string. This affects programs that call routine PGENV. The characters supplied are options for PGBOX (in addition to those assumed by default by PGENV), i.e., `BCNST'. Useful options include `G' to draw a grid, `V' to draw y-axis labels upright, `I' to draw axis tick marks outside the box instead of inside, `1' or `2' to change the numeric label style. e.g.
setenv PGPLOT_ENVOPT IVG
PGPLOT_FOREGROUND
Color name. This variable can be used to change the color representation of color index 1 (the ``foreground'' color) from its device-dependent default (usually white or black). The value of the variable should be a color name defined in the color-name database. If the variable is defined, the effect is the same as a call to PGSCRN with this name as argument immediately after the graphics device is opened. Color names are case-insensitive and embedded spaces are ignored. e.g.
setenv PGPLOT_FOREGROUND springgreen
PGPLOT_BACKGROUND
Color name. This variable can be used to change the color representation of color index 0 (the ``background'' color) from its device-dependent default (usually black or white). The value of the variable should be a color name defined in the color-name database. If the variable is defined, the effect is the same as a call to PGSCRN with this name as argument immediately after the graphics device is opened. On devices without a color lookup table, changing the background color only affects the color of elements explicitly drawn in color index 0. To ensure that the background of the entire view surface changes to the new color, it is also necessary to call PGERAS at the start of each page. e.g.
setenv PGPLOT_BACKGROUND slateblue
PGPLOT_BUFFER
Switch. If this variable is defined, with any non-null value, PGPLOT buffers output. The effect is the same as if PGBBUF is called immediately after opening the graphics device, and PGEBUF immediately before closing it. It will have no effect on programs that already include these calls. On some devices, buffering output can lead to large improvements in speed, but enabling buffering may upset synchronization between graphical output and other program activity. e.g.
setenv PGPLOT_BUFFER yes
PGPLOT_DEBUG
Switch. If this variable is defined, with any non-null value, PGPLOT will print some debugging information on the standard output. Currently this includes attempts to open input files (binary font file and color-name database), and, when the null device is selected for output, statistics of device-driver calls. e.g.
setenv PGPLOT_DEBUG yes

In addition to these environment variables, several device drivers use device-specific environment variables. See the PGPLOT Device Manual for details.