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.
Some examples, assuming the source code is in a file called pgprog.f
:
f77 -o pgprog pgprog.f -L/usr/local/pgplot -lpgplot
f77
is the command used to invoke the Fortran compiler. On some systems, this may be, e.g., fort77
or g77
.-assume backslash
, -xl
, -!bs
, -qnoescape
). The symptom of backslash problems is that greek letters, subscripts, superscripts, etc. are displayed incorrectly.-lpgplot
option tells the linker to scan the PGPLOT library, and the -L
option specifies a directory where the linker should look for it.-Ldirectory -lX11
to the command line. (This is not required on Solaris.)$ FORTRAN PGPROG $ LINK PGPROG, PGPLOT_DIR:GRPSHR/LIBThe logical name
PGPLOT_DIR
should point to the directory in which the PGPLOT library is installed. (Your system may be set up so that the library is scanned automatically, in which case you just need $ LINK PGPROG
.) The result is an executable file PGPROG.EXE
that can be executed with the RUN
command..EXE
file, use the non-shared library as follows (the XLIB library is not required if your version of PGPLOT does not include an X-window driver):
$ LINK PGPROG,PGPLOT_DIR:GRPCKG/LIB,SYS$INPUT:/OPT SYS$SHARE:DECW$XLIBSHR.EXE/SHARE [ctrl-Z]
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
Some examples, assuming the source code is in a file called pgprog.c
:
cc -c -I/usr/local/pgplot pgprog.c f77 -o pgprog pgprog.o -L/usr/local/pgplot -lcpgplot -lpgplot
c
is the command used to invoke the C compiler. On some systems, this may be, e.g., gcc
or c89
.-I
option in compilation specifies a directory where the linker should look for the header file cpgplot.h
.f77
(or equivalent) command is used for linking to ensure that the required Fortran support libraries are loaded. It is possible to link using cc
or ld
, but you must then figure out which libraries your Fortran compiler needs (man f77
might help).-lcpgplot -lpgplot
options tell the linker to scan the PGPLOT libraries, and the -L
option specifies a directory where the linker should look for them. Both -lcpgplot
and -lpgplot
are required, in that order.-Ldirectory -lX11
to the command line.To give an indication of how difficult it can be to include the correct libraries when using the C compiler to do the linking, here is an example of the command required to compile a PGPLOT program using gcc on a Sun/Solaris system (assuming that the PGPLOT code was compiled using g77):
gcc -o pgprog -I/usr/local/pgplot pgprog.c -L/usr/local/pgplot/ \ -lcpgplot -lpgplot -L/usr/local/lib/gcc-lib/sparc-sun-solaris2.6/2.8.1/ \ -lf2c -lgcc -lmThe locations of the libraries vary according to the operating system and compiler versions.
$ CC PGPROG /INCLUDE=PGPLOT_DIR: $ LINK PGPROG, PGPLOT_DIR:CPGPLOT/LIB, PGPLOT_DIR:GRPSHR/LIBFor C, two libraries are required.
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
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
).
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:
PGPLOT_DIR="/usr/local/pgplot"; export PGPLOT_DIR (sh) setenv PGPLOT_DIR /usr/local/pgplot (csh)
$ DEFINE PGPLOT_DIR USER:[PGPLOT]
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.
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:
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/
grfont.dat
in the directory specified by PGPLOT_DIR. e.g.
setenv PGPLOT_FONT /usr/local/pgplot/grfont.dat
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
setenv PGPLOT_DEV /xwin
setenv PGPLOT_TYPE ps
setenv PGPLOT_ENVOPT IVG
setenv PGPLOT_FOREGROUND springgreen
setenv PGPLOT_BACKGROUND slateblue
setenv PGPLOT_BUFFER yes
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.