Appendix G. Porting PGPLOT

General Notes

1. The ``standard'' routines pgplot/src/pg*.f and pgplot/src/gr*.f. All of these routines should be compiled and put in the object-module library, although the ``obsolete'' routines may be omitted (they are not used by current PGPLOT programs and will not be included in future versions of PGPLOT). The obsolete routines are: grchar grchr0 grdat2 grgtc0 grinqfont grinqli grinqpen grlinr grmark grmovr grsetfont grsetli grsetpen grtran grvect pgsetc pgsize. All routines in the pgplot/src directory are standard Fortran-77 with the following exceptions:
   • Several routines use the non-standard INCLUDE statement; if your compiler does not accept this, you need to replace the INCLUDE statement with the contents of the named file (pgplot.inc or grpckg1.inc as appropriate).
   • Some routines have names longer than 6 characters, the maximum allowed by the Fortran-77 standard: these routines can be omitted: all have shorter aliases that can be used in preference (e.g., PGPAGE instead of PGADVANCE).
   • One routine, GRSYXD, uses a non-standard INTEGER*2 statement; you can replace this with INTEGER, but if you do so you must make the corresponding change in GRSY00 and PGPACK (see below).
   • Routine GRCLPL uses function IAND(I,J) for bitwise logical and of two integers; most compilers recognize this as an intrinsic function and compile it inline, but if yours does not, you will need to supply this as an external function.
2. The system-dependent routines. Versions of these routines that work for many UNIX systems are provided in directory pgplot/sys, but for other systems these will need to be written. Some of the routines are used only by certain device drivers and will not be needed if you do not use these drivers.
   • GRDATE -- get date and time as character string
   • GRFILEIO -- routines GROFIL, GRCFIL, GRWFIL, GRWFCH for binary file I/O
   • GRFLUN -- free a Fortran logical unit number
   • GRFMEM -- free memory
   • GRGCOM -- read with prompt from user's terminal
   • GRGENV -- get value of PGPLOT environment parameter
   • GRGLUN -- get a Fortran logical unit number
   • GRGMEM -- allocate memory
   • GRGMSG -- print system message
   • GRIBF1 -- fill buffer with a specified character
   • GROPTX -- open input/output text file
   • GRSY00 -- initialize font definition
   • GRTERMIO -- routines GROTER, GRCTER, GRWTER, GRPTER, GRRTER for I/O to terminals
   • GRTRML -- get name of user's terminal
   • GRTTER -- test whether device is user's terminal
   • GRUSER -- get user name
3. The device-dispatch routine, grexec.f. This routine includes calls to all the selected device drivers. It is the only routine that needs to be modified to configure PGPLOT for a particular installation. It is usally generatred automatically from drivers.list.
4. The device drivers. Most device drivers are included in single files in the pgplot/drivers directory, with file name XXdriv.f or XXdriv.c. Some C drivers require additional .c or .h files. The drivers you wish to include in PGPLOT should be compiled and added to the object library. Many of the device drivers are written in portable, standard Fortran-77, but others cannot be written portably and either use Fortran-77 with extensions (such as BYTE and %VAL) or C. Some of the older drivrs are sloppily written and could be made more portable. For driver written in C, it is necessary to pay careful attention to the system-dependent conventions for calling C subroutines from Fortran programs.

Porting to UNIX systems

Background

1. To provide a uniform installation procedure for as many systems as possible.
2. To support PGPLOT compilation in directories other than the distribution directory. If the disk containing the source code distribution is cross-mounted over a number of different UNIX systems, this allows one copy of the source code to be used to compile PGPLOT on each of those systems. It also allows the source-code directory to be placed on a read-only disk partition or CD-ROM.
3. To allow more than one compiler combination on systems that support multiple compilers. Separate configuration files are provided for each compiler combination.
4. To avoid code duplication of system-specific routines where possible. The script allows one to selectively override generic routines with system specific versions.
5. To make the script behave as told by the user, rather than have it try to automatically determine its configuration from the system that it is run upon. This enables one to make makefiles for many systems without actually having to log in to those systems.

How to port PGPLOT to a new UNIX system

Create a system directory

Create a configuration file

Configuration files are distinguished from other files by a .conf file name extension. If you intend to support more than one FORTRAN and/or C compiler, then one configuration file will be needed per compiler combination. By convention, configuration files are named as a_b.conf, where a is the name of the FORTRAN compiler and b is the name of the C compiler.

The first line must be a short Bourne shell comment that describes how the configuration differs from other configuration files in the system directory. In most configuration files, the comment just ellaborates on which FORTRAN and C compilers are being configured. The comment is displayed alongside the configuration name when makemake users fail to specify a configuration name.

The easiest way to create a new configuration file is to copy one from another sys_xxx directory, rename it and then modify the shell variable assignments to suite your system. Note that within these scripts no spaces are tolerated around the = operator, and that you should enclose the assignment string within double quotes.

Configuration file variables

XINCL

The argument used to tell the C compiler where the X11/ include directory can be found. If your machine doesn't have X-windows, assign the empty string "". e.g.,

      XINCL=""
      XINCL="-I/usr/local/include"
      XINCL="-I/usr/openwin/include"

FCOMPL

The command used to invoke the FORTRAN compiler. e.g.,

      FCOMPL="f77"
      FCOMPL="fort77"
      FCOMPL="fortran"
      FCOMPL="frt"
      FCOMPL="gf77"
      FCOMPL="xlf"

FFLAGC

Any FORTRAN compiler flags required for compiling and linking the PGPLOT library. Note that this should not include the "-c" or "-o" options, which are automatically added, where needed, by the makemake script. Examples of possible flags to include, are optimization level flags and flags pertinent to creating shared libraries (where possible). This is usually an option to generate position-independent code (e.g., "+z", "-fpic", "-K PIC"). An option to check for undeclared variables (e.g., "-u") may be specified, but is not required. An option to use static rather than automatic storage (e.g., "-static") is not required but may be used: PGPLOT should work correctly with either static or automatic storage. e.g.,

      FFLAGC="-u -O"
      FFLAGC="-u -PIC -O"
      FFLAGC="-u -pic -O"
      FFLAGC="-u"
      FFLAGC='-Wf"-o novector -i64"'

FFLAGD

In most cases this should be the same as FFLAGC. It is used instead of FFLAGC when compiling and linking the PGPLOT demo programs. The main potential difference has to do with the fact that many of the demo programs exploit the '\' character to introduce special plot symbols within PGPLOT text. Unfortunately many compilers treat this as an escape character. To avoid this, FFLAGD should include a flag to tell the compiler to turn off special treatment of this character. Options for shared libraries (position-independent code) are not required. e.g.,

      FFLAGD=""
      FFLAGD="-O0"
      FFLAGD="-assume backslash"
      FFLAGD="-u -!bs"
      FFLAGD="-u -O"
      FFLAGD="-u -backslash -O0"
      FFLAGD="-u -qnoescape"
      FFLAGD="-xl -u -O"

CCOMPL

The command used to invoke the chosen C compiler on your system. If you intend to use the C wrapper library, then this should be an ANSI-C compiler. Otherwise a pre-ANSI K&R C compiler will be sufficient. e.g.,

      CCOMPL="/usr/ucb/cc"
      CCOMPL="c89"
      CCOMPL="cc"
      CCOMPL="gcc"

CFLAGC

Any C compiler flags that are needed to compile PGPLOT. Note that this should not include the "-c" or "-o" options, which are automatically added, where needed, by the makemake script. Examples of possible flags to include, are optimization level flags and flags pertinent to creating shared libraries (where possible; the option usually required is the one that generates "position-independent code"). Also, if your system exports FORTRAN symbols to the linker postfixed with an underscore then you should include the -DPG_PPU flag. e.g.,

      CFLAGC=""
      CFLAGC="+z -O -D_HPUX_SOURCE"
      CFLAGC="-DPG_PPU -pic -O"

LIBS

This should specify the loader flags required to cite any external libraries that are required when linking any of the demo and server programs. In most cases this is just the X-windows library, cited as "-Ldirectory_name -lX11" where directory_name is the name of the directory in which the library resides. e.g.,

      LIBS=""
      LIBS="-L/usr/lib/X11R5 -lX11"
      LIBS="-L/usr/openwin/lib -lX11"

RANLIB

Many older UNIX systems require newly created or modified libraries to be post-processed for better access speed. On such systems, you should set RANLIB="ranlib". On other systems you should set RANLIB="echo ranlib".

MOTIF_INCLUDE, MOTIF_LIBS

On systems where Motif is installed the MOTIF_INCLUDE and MOTIF_LIBS configuration variables should contain flags telling the C compiler and loader where to find the include files and libraries associated with Motif. This should include files related to X11, Xt and Xm. Note that the XINCL and LIBS variables are not consulted when compiling and linking Motif code, e.g.,

      MOTIF_INCL="-I/usr/dt/include $XINCL"
      MOTIF_LIBS="-L/usr/dt/lib -lXm -L/usr/openwin/lib -lXt $LIBS"

SYSDIR

On entering the configuration script, this variable contains the directory name of the system directory in which the configuration file resides. If you have multiple compiler combinations which require a different set of system-specific routines, then you should create a subdirectory in the system directory, for each combination, and redirect SYSDIR in each configuration file, to point at the relevant directory. eg. SYSDIR="$SYSDIR/f77_cc/".

PGBIND_FLAGS

If you wish to have the PGPLOT C wrapper library compiled for your system, then you will need to assign this variable. Its arguments are the configuration flags to the PGPLOT pgbind command. To see the available options, compile the pgbind program in pgplot/cpg/ with an ANSI-C compiler and invoke it with no arguments.

SHARED_LIB

If your system supports shared libraries, you should specify the name to give the shared library here.

SHARED_LD

If your system supports shared libraries, then you should specify the command and its leading arguments, which when all the PGPLOT object files are appended as trailing arguments, will create a shared library. You can use the SHARED_LIB variable specified above as an argument to this command, by referring to it as $SHARED_LIB.

MCOMPL

The command used to invoke the chosen Objective C compiler on your system. This is only required if any of the system code that you supply is written in Objective C. Few people have Objective C compilers, so you should stick to using just C and FORTRAN if at all possible.

MFLAGC

The compiler flags to use with MCOMPL. Note that this should not include the "-c" or "-o" options, which are automatically added, where needed, by the makemake script.

Creating system-dependent files

Points to consider when determining whether new versions of the default system routines are required include.

FORTRAN routines

All of the *.f files in pgplot/sys/ use FORTRAN extensions, or rely upon unportable assumptions such as unformatted I/O record sizes. If you are not familiar with the specifics of your FORTRAN compiler, then probably the best thing to do here, is to simply try to compile PGPLOT without overriding any of the default FORTRAN code, and see what the compiler or linker chokes upon.

Problems that might only show up at run time include:

• PGPLOT crashes when trying to read its FONT file. This probably means that grsy00.f, which relies upon being able to read large unformatted record sizes, will need to be re-written. This is a difficult problem to fix. The simplest way is to replace both pgplot/sys/grsy00.f and pgplot/fonts/pgpack.f with versions that read and write a useable file format. Both files should be placed in your local system directory. makemake will pick them up from there and compile them in place of the default versions.
• When PGPLOT prompts for terminal input, the cursor is placed on the line after the prompt. This is only a cosmetic problem, but if you can find a way to suppress the carriage return at the end of the prompt string, the appearance will be better.

An optional routine that makemake only compiles if it finds a version in your system directory, is a replacement for the common IAND() intrinsic function. This is used by pgplot/src/grclpl.f and if your compiler doesn't have the IAND intrinsic, you should place a function to replace it in your system directory. Its purpose is simply to return the bitwise logical AND of two FORTRAN integers.

C routines

Where C routines have been used, you should be aware that there is no guaranteed way to portably call C from FORTRAN. The C routines in pgplot/sys/ support the two most common conventions, both of which are based on the convention used in the original BSD f77 compiler. In the BSD f77 convention, FORTRAN symbols are converted to lower-case and postfixed with an underscore when exported to the linker, all arguments are passed by pointer, and the lengths of any string arguments are silently appended to the end of the argument list. A common modification to the BSD f77 convention, is to omit the trailing underscore. If you need the trailing underscore, (this is the most common convention), then you must include -DPG_PPU in the configuration file CFLAGS assignment.

If neither of the above conventions are supported by your compiler, then you will have to copy the C routines to the new system directory and modify them to support the calling conventions on your system.

Where C routines have been provided, they are usually based on the availability of POSIX.1. If your machine doesn't support POSIX yet, then you will have some changes to make - particularly as regards terminal I/O routines. If your system is of BSD decent, then try the BSD compatible terminal I/O routines in the pgplot/sys_convex/ system directory.

Wrapper routines for C drivers

As mentioned above there is no portable way to call C from FORTRAN, yet there are several drivers that are written in C in the pgplot/drivers/ directory. A prominent example is the X-windows drivers pgplot/drivers/xwdriv.c. Such drivers only understand the two calling conventions mentioned above. Unlike the system routines, the drivers are complicated, so for maintenance reasons it would be unwise to modify copies of them just to support a new calling convention. Instead, makemake checks to see if there are any C wrapper functions in the system directory. These are routines that act as intermediaries between FORTRAN and the unmodified drivers, and makemake arranges to have both the original driver code and wrapper code compiled and linked. In order that makemake detect such wrapper functions, for driver code called xxdriv.c, the wrapper function should be called xxwrap.c, where the two letter prefix xx names a particular driver.

The same mechanism can be used for Objective C drivers, in which case the file would be called xxwrap.m. However as mentioned before you should try to stick to C and FORTRAN code if possible.

Note that there is no requirement that you support all of the drivers in the pgplot/drivers/ directory. Many of them are targeted at specific systems, and others are for rare devices. When first porting PGPLOT, you should probably first stick to a small simple subset until PGPLOT appears to be working reliably, then re-run makemake with a larger selection of drivers uncommented to test more of them.