<< >> Title Contents Index Home Help

B Driver Customization

The Portland Group compilation drivers, pghpf, pgcc, pgf77, pgCC (HPF, C, Fortran 77, and C++)[*] allow you to issue a single command that builds command lines to execute the various compilation tools using the correct options (including options for the compiler, the assembler and the linker). This chapter describes how you can customize the driver based on the settings of environment variables and the statements in driver initialization files. The environment variables provide information that the driver uses to locate executable files and other system files. The driver initialization file (PGIRC file) contains statements and configuration keywords that set various driver parameters; these parameters determine the defaults supplied to the driver, to the compiler or to other phases of the compilation sequence. Most users need not be concerned with customizing the driver, since the initialization file supplied with each system should serve their needs. Advanced users and system administrators can take advantage of the PGIRC facility to customize their environment on a global, per-user, or per-file basis.



Warning



A PGIRC file is required for the driver to operate correctly. If you remove the PGIRC file supplied with your software and do not specify an alternate PGIRC file, you will receive an error message from the driver, for example using the pghpf driver:
pghpf-error-Unable to open - /command-path/.pghpfrc

B.1 Environment Variable

The drivers use environment variables to locate support files and libraries as well as executable programs. If you install the PGI software in its default location, /usr/pgi, the environment variables do not need to be set as long as the directory containing the PGI executables is added to the PATH environment variable (in general, this is the directory /usr/pgi/arch/archbin where arch is a system -specific name for example SPARC or SGI). Otherwise the following variable needs to be set:

PGI
The root directory for the PGI products. For example, if your compilers were installed in /usr2/pgi, set PGI to this value.

B.1.1 Setting Environment Variables

The method for setting the PGI environment variables depends on your shell. Below are the commands for some common shells (note we use target as a generic name for any system, for example SPARC or SGI).

Bourne Shell or Korn Shell: 

PGI=/usr2/pgi; export PGI
PATH=$PATH:$PGI/target/bin; export PATH
C Shell: 
setenv PGI /usr2/pgi
setenv PATH $PATH:$PGI/target/bin

B.2 PGIRC Statements and Configuration Variables

PGIRC files contain statements, configuration variables, user-defined variables and configuration tests. The statements allow you to set variables to predefined or user specified values. In addition, configuration tests and the various flow control statements let you test whether a configuration variable or command-line option is set and then set a value or branch accordingly. There are also statements that read in additional configuration files for processing. The compiler driver, pghpf processes the PGIRC file and uses the values supplied to set its internal parameters. Once the driver's parameters are set, command lines are built and executed.

Most of the configuration variables have corresponding command-line options. The command-line options, when supplied, take precedence over values set in PGIRC files. There may be more than one PGIRC file, including the default system configuration file supplied with The Portland Group Software. For a variable that is set in more than one PGIRC file, the most recent value set overrides any previous value.

The examples presented later in this chapter show PGIRC configuration files. By supplying either user-specified values or predefined values you can set configuration variables. This text indicates valid values where a predefined keyword is expected.

Include comments in a PGIRC file using the # character. Any characters following a # are ignored.

The set statement, used in combination with the = operator (or a space), sets the value of a configuration variable. Case is significant for configuration variables, but not for the PGIRC commands. For example, the following PGIRC lines set the value of the PGI_TARGET configuration variable, and all three are equivalent. 

set PGI_TARGET=target
SET PGI_TARGET=target
SET PGI_TARGET target

B.3 Search Scope for PGIRC Files

There can be more than one PGIRC file. The driver determines which file to use according to the following scoping rules:

  1. If a -rc driver option is supplied on the command line, the named file supplied as a parameter is used as the PGIRC file. If this option is supplied with a full pathname, the specified file is used as the PGIRC file and no further searching takes place. If just a file name is supplied and it is not a full pathname, the filename supplied is used instead of the default name, .pghpfrc and the normal directory search scope rules apply using the alternate name, as described in the following two steps.
  2. If the $HOME environment variable is set, the driver looks for the configuration file in the $HOME directory, otherwise the driver looks for the configuration file in the current working directory. If the configuration file is found, in either of these directories, it is processed.
  3. If the second search fails, the driver attempts to find the configuration file in the directory where the driver resides (the $DRIVER directory).
If you want to use more than one configuration file, add the include statement to the PGIRC configuration file. Once a PGIRC file is found by the scope rules, processing begins and other PGIRC files that may exist further down the chain are not processed (unless you include them). Note that when a configuration variable is set twice, the later setting overrides any previous value. Thus, the placement of the include statement within a PGIRC file may be critical. For example, if you want to change the value of a configuration variable, you could create a PGIRC file in your home directory containing the following: 
include $DRIVER/.pghpfrc
set PGI_TARGET=target
This PGIRC file would read the contents of the default PGIRC file and override the value of the PGI_TARGET variable with the specified value.

B.4 Altering PGIRC Files

If you want to alter PGIRC files, it is useful to test the driver output. The driver option -dryrun prints the commands that the driver generates, but does not execute them. For example: 

$ pghpf -dryrun hello.hpf
The driver option -show prints the driver's current configuration, after reading the PGIRC file. This option is also useful for testing.

B.5 Defining and Using PGIRC Variables

Each PGIRC configuration variable is an internally defined name. If a variable is set in a PGIRC file, its value is available while the driver is executing. Variables that are not set in the configuration file can be set either as environment variables or on the command line (or a variable may not be set at all). There are four variations for setting a configuration variable (we use the Bourne shell for these examples).

1. Using the set statement from within a configuration file. For example: 

	set LD=ld
2 Setting the configuration variable on the driver command line. 
	$pghpf LD=ld860 -ohello hello.hpf
3. Setting an environment variable at the shell prompt or in the shell's startup file. 
	$LD=ld860 ; export LD
	$pghpf hello.hpf
If you use the environment variable method for setting configuration variables, you need to include a line similar to the following in your PGIRC file: 
	ifndef LD set LD=$LD
This tells the driver to try to resolve the LD configuration variable and look for an environment variable named LD.

4. Setting the configuration variable on the driver command line from the value of an environment variable. 

	$B=ld860 ; export B
	$pghpf LD=\$B hello.hpf
For these methods for setting configuration variables the following precedence is followed: variables set on the command line have higher precedence than those set in the configuration file.

You can also use user defined variables in PGIRC files. As with the B environment variable in example four above, configuration files can contain variable names not known to the driver. User-defined variables of this type must start with an upper or lower-case alphabetic character and must contain only upper-case or lower-case alphabetic characters, digits, or underbar "_". Special characters are not allowed in user-defined variable names.

To use a PGIRC user-defined variable, precede the variable name with a $. For example, if you set a variable B in a PGIRC file, you can subsequently use that variable: 

set B=ld860
set LD=$B
you can also use 
set LD=$(B)

B.6 PGIRC Statements

The driver interprets PGIRC statements entered in a configuration file. Normally a statement ends at the end of line character. Using the \ character, you can continue the command line.

B.6.1 If Statement Syntax

The general form of a logical if statement has two forms : 

if <configuration test> statement [statement ...] \
   [ else statement [statement ...] ] \
   [ endif]

ifn <configuration test> statement [statement ...] \
   [ else statement [statement ...] \
   [ endif]
where:
configuration test
is one of the valid configuration tests listed in Section B.8,"PGIRC Configuration Test Variables."
The general form of a defined if statement has two forms : 
ifdef <variable> statement [statement ...] \
   [ else statement [statement ...]
ifndef <variable> statement [statement ...] \
   [ else statement [statement ...]
where:
variable
is a variable name.
In the logical if and defined if statements, the else portion can appear on the same line as the if without including a \ character. When the else appears on the next line, the \ is required.

B.6.2 Set and Include Statement Syntax

The set PGIRC statement has the following syntax: 

set variable[=]value
where variable is either a predefined or user-defined variable name and value is either a predefined or user-defined value. The = is optional, but if it is not present a blank space is required.

The include PGIRC statement has the following syntax: 

include [path]filename
where path is an optional full pathname and filename is the name of the PGIRC file to include.

B.6.3 Switch Statement Syntax

The switch PGIRC statement has the following syntax: 

switch new_switch_name[=] [existing_switch]...
where new_switch_name is either a predefined or user-defined command-line switch name and existing_switch is either a predefined or user defined switch or switches, or blank. The = is optional, but if it is not present a blank space is required.

The following command adds a switch named test1. 

switch test1 = -Y0,/home/test/xxx/pgc
The following command adds a switch which passes a switch directly to the linker. test2. 
switch test2 = -Wl,-x1a
The following command adds a switch which tells the driver to ignore a previously defined -C switch. 
switch C =

B.6.4 Help Statement Syntax

The help PGIRC statement has the following syntax: 

help switch[=]value
where switch is either a predefined or user-defined variable name and value is a help string. The = is optional, but if it is not present a blank space is required.

B.6.5 Map Statement Syntax

The map command re-maps an internally created switch (driver) into another switch (compiler) or bypasses the switch completely. Internal switches are switches that are created by the driver and passed to the compiler. For example the "-O" switch is such a driver mapped switch. The driver's -Ox switch is passed to the compiler as the switch "-opt x".

The map PGIRC statement has the following syntax: 

map "<pass,>-switch<,args>"="<arg1,..,argn>"
If the <pass> is not indicated, all passes are affected. The passes are:
0
compiler
a
assembler
l
linker
c
C++ compiler
h
HPF compiler
On the right side of the = in the map command, a * indicates that the corresponding argument is dropped. If the argument is $1, ,$2, or...$n, then the corresponding argument passed in the specified position.

The number of arguments on the left of the "=" do not have to equal the number of arguments on the right. This allows a user to add additional arguments to a re-mapped switch.

For example: 

map "0,-inform,*"="*,*"
This deletes the -inform option and its argument. 
map "0,-terse"="*,*"
This deletes the -terse option and its argument. 
map "0,-x,119,2"="*,*,*"
This map command deletes the -x,119,2 argument. 
map "0,-idir,*"="-I,$2"
This map command re-maps the -idir switch to -I and copies its argument.

B.6.6 Passthru Statement Syntax

The passthru statement allows a command with optional or required arguments to be "passed through" to the compiler and linker passes. This switch is used by the pghpf driver to pass switches directly to the SGI f77 driver.

When using the -help option, the driver sorts and merges the passthru defined switches with the list of switches embedded into the driver.

The passthru PGIRC statement has either of the following forms: 

passthru "-switch";="help description"
passthru "-switch",="help description"
where the switch is the switch to pass through. The ';' indicates an optional argument follows the switch. The ',' indicates a required argument follows the switch.

For example, 

passthru "-p"="a switch with no arguments"
passthru "-g";="a switch with an optional argument"
passthru "-ko",="a switch with a required argument"

B.6.7 Bypass Statement Syntax

The bypass statement instructs the driver to bypass or ignore a known switch. A bypassed switch does not display using the driver's -help option .

The bypass PGIRC statement has the following syntax: 

bypass -switch
where switch is the switch to bypass.

For example, 

bypass "-M"
bypass -r

B.6.8 PGIRC Statement Examples

Where blank spaces are included in a string, quotes enclose the variable's value. 

1)   if PROFILE set LD_STARTUP="crti.o $LIB/pgcrt0.o $CRT"

2)   ifdef NEWCOMP set COMPDIR="$PGI/i860/bin"

3)   if PROFILE set LD_STARTUP="crti.o $LIB/pgcrt0.o $CRT" \
       else   set LD_STARTUP="crti.o crt1.o $CRT"

4)  ifn PROFILE set LD_STARTUP="crti.o crt1.o $CRT $PGFMAIN"

5)   ifndef COMPDIR set COMPDIR="$PGI/i860/bin"

6) include /home/test/pgirctest

7) set PGI_TARGET=i860

B.6.9 Statement Summary

Table B.1 shows the PGIRC statements (case is not significant for statements). Examples using the statements follow the table.

Table B.1 PGIRC Commands

Command
Description
bypass
Instructs the driver to bypass or ignore a known switch. A bypassed switch also will not be displayed using the -help option of the driver.
else
Logical else test. This is used in combination with the if statement.
endif
Completes a logical if test block.
error
Used to print an error message and to force the driver to exit. This is used primarily for debugging a configuration file.
help
Provide a description message for a driver switch (refer to -help).
if
Logical if test. This may be used in conjunction with an else statement.
ifdef
Determines if a variable has been assigned a value.
ifn
Logical if not test. This may be used in conjunction with an else statement.
ifndef
Determines if a variable has not been assigned a value.
include
Used to process an additional PGIRC file.
map
Re-maps a driver internally created switch into another switch or bypasses the switch completely. Internal switches are switches that are added directly by the driver to the compiler.
passthru
This statement allows a command with optional or required arguments to be "passed through" to the compiler and linker passes.
set
Sets the value of configuration variables used in PGIRC files.
switch
Add a user-defined switch.

B.7 PGIRC Configuration Variables

This section lists the valid configuration variables. Note, these descriptions are brief, you should have a good idea what you are doing before you attempt to modify the PGIRC configuration files.

Table B.2 PGIRC Configuration Variables

Variable

 Description
AIX
Indicates if tools are hosted on an aix system. The valid values are NO or YES.
APX
Indicates if tools hosted on i860. The valid values are NO or YES.
AS
Name of the assembler. The assembler command name will be set to the pathname pointed to by /$ASDIR/$AS.
ASDIR
Directory path of the assembler. The assembler command name will be set to the pathname pointed to by /$ASDIR/$AS.
ASARGS
Default assembler arguments. One or more assembler arguments. Refer to the assembler man page for information on its arguments.
ASTYPE
Output format of executable file. The valid values are: COFF, ELF and AOUT (this is used internally by the driver to pass output options to the compiler).
COMP_ARGS_C
Default C arguments. One or more compiler arguments.
COMP_ARGS_FTN
Default Fortran arguments. One or more compiler arguments.
COMP_ARGS_HPF
Default HPF arguments. One or more compiler arguments.
COMP_ARGS_LAST
One or more compiler arguments that the user cannot override.
COMP_C
Name of the C compiler. The compiler command name will be set to the pathname pointed to by /$COMPDIR/$COMP_C.
COMP_FTN
Name of the Fortran compiler. The compiler command name will be set to the pathname pointed to by /$COMPDIR/$COMP_FTN.
COMPDIR
Directory path of the compiler. The compiler command name will be set to the pathname /$COMPDIR/$COMP_C.
CPLUSARGS
Default C++ arguments for the C++ first phase.
CPLUSDIR1
Directory path of the C++ compiler (pass 1).
CPLUSDIR2
Directory path of the C++ compiler (pass 2).
CPLUS_LIBS
List of C++ .a files passed to linker
CPLUS_PREDEFS
List of define's passed to C++ compiler.
CRTDIR
Directory path of the startup files. This variable is used in the linker portion of the driver command.
CPLUS1
Name of the C++ compiler (pass 1)
CPLUS2
Name of the C++ compiler (pass 2)
DRIVER
Specifies the location (path) of the driver. Its value is available for use in PGIRC configuration files.
DRIVER_ARGS_C
Default driver arguments. Refer to Chapters 7 and 8 for lists of the valid driver options.
DRIVER_ARGS_CPLUS
Default driver arguments. Refer to Chapters 7 and 8 for lists of the valid driver options.
DRIVER_ARGS_FTN
Default driver arguments. Refer to Chapters 7 and 8 for in the Pgf77 User's Guide for lists of the valid driver options.
DRIVER_ARGS_HPF
Default driver arguments. Refer to Chapters 7 and 8 for in the Pgf77 User's Guide for lists of the valid driver options.
ENDIAN
Output byte-ordering of executable file. The valid values are LITTLE and BIG (this value is used internally by the driver).
EXTRACTOR_C
Name of the C function extractor.
EXTRACTOR_FTN
Name of the Fortran function extractor.
EXTRACTOR_HPF
Name of the High Performance Fortran function extractor.
HPFEXDIR
Pathname of the directory holding the HPF extractor.
INCDIR
Directory path of the C include files.
LANG
Sets driver language to C, C++, Fortran or HPF.
LD
Name of the linker. The linker command name will be set to the pathname pointed to by /$LDDIR/$LD.
LDARGS
Default linker arguments. Refer to the linker man page for details on linker arguments.
LD_ENDUP
List of .o endup files passed to linker.
LDDIR
Directory path of the linker. The linker command name will be set to the pathname pointed to by /$LDDIR/$LD.
LD_ENDUP

 List of .o endup files passed to linker. These .o or .a files are appended to the linker command.
LD_LOPT
Indicates if linker supports -l switch. The valid values are NO and YES. If this variable is set to NO, the driver builds the names of the library files by prepending "lib" and appending ".a" to library names supplied with the -l option on the command line. The library directory is specified with the -L command-line option or the LIBDIR variable.
LD_STARTUP
List of .o startup files passed to linker.
LIBDIR
Directory path of the library files.
LIBS
List of .a files passed to linker.
MERGEARGS
Arguments passed to merge program (same as ASARGS)
MERGEDIR
Directory of merge program (same as ASDIR)
MUNCH
Name of the C++ symbol table changer program.
MUNCHDIR
Directory path of the C++ symbol changer table program
NM
Name of the symbol name lister (C++ only)
NMDIR
Directory path of the symbol table listing program
NMARGS
Default name arguments. The name phase defined by NM is called during template instantiation. These arguments make the output of name readable by pgprelnk..
NOFRAME
Indicates if frame/noframe option passed to compiler. The valid values are NO and YES. Refer to the pgcc -Mframe option for details (this does not effect the Fortran compiler).
PGIDIR
Directory path of the PGI object files. Some object files (or libraries) contain routines for special compiler features. The PGIDIR is the directory that contains these object files.
PGMERGE
Name of pgivision merge program (same as AS)
PREDEFS
List of defines passed to compiler. This is a list of defines that is passed to the compiler. Each predef must have the following form:
-Dname
where name is the macro name. Multiple predefs can occur; they must be separated by spaces. For example:
set PREDEFS="-DTEST1=2 -DTEST2 -DTEST3"
PREPREDS
List of predicates passed to compiler.
RUN860
Name of the i860 executor program.
RUN860ARGS
Default i860 executor arguments.
SYSV_PROF
Indicates if System V style of profiling. The valid values are NO and YES. The driver uses this to set internal profiler options.
PGI_TARGET
Indicates the target system. The valid values are HAUPPAUGE, HYPERSPEED, MERC, SPARC, and I860. The driver uses this to set internal system specific options.

B.8 PGIRC Configuration Test Variables

List of valid configuration tests follows:

Test Variable

Description
AOUT
TRUE if "set ASTYPE=AOUT" or -Maout is set.
APX
TRUE if "set APX=YES" or -Mrun860=A
BE
TRUE if "set ENDIAN=BIG" or -Mbe is set
COFF
TRUE if "set ASTYPE=COFF" or -Mcoff
DEBUG
TRUE if -g is set on the command line
ELF
TRUE if "set ASTYPE=ELF" or -Melf is set
IEEE
TRUE if -Kieee
LE
TRUE if "set ENDIAN=LITTLE" or -Mle is set
PGC++
TRUE if pgCC driver is being used
PGCC
TRUE if pgcc driver is being used
PGF77
TRUE if pgf77 driver is being used
PGHPF
TRUE if pghpf driver is being used
PROFILE
TRUE if profiling is being used
PROF_NONE
TRUE if profiling is NOT being used
PROF_MCOUNT
TRUE if -Mprof=mcount is used or -qp
PROF_COVER
TRUE if -Mprof=cover is used or -qc
PROF_LPROF
TRUE if -Mprof=lprof is used or -ql or -pg (Solaris)
PROF_LINES
TRUE if -Mprof=lines is used or -ql
PROF_FUNC
TRUE if -Mprof=func is used or -qp
PROF_GPROF
TRUE if -Mprof=gprof is used or -xpg (Solaris)
SYSV_PROF
TRUE if "set SYSV_PROF=YES" or -pg (Sun 4.1.x)

B.9 Sample PGIRC Configuration File

This section shows a sample PGIRC file. The example uses most of the PGIRC commands. 


#
# PGI Compiler Configurations for High Performance Fortran
#

set SYSV_PROF=NO


#
# User Defined Switches for HPF
#

switch fast=-O2 -dalign -fnonstd -native

switch Mg=-g -Mnofn -Mkeepftn -Wh,-y,49,4
switch Mport=-Wh,-x,49,0x80

switch Mpvm
switch Mrpm
switch Mrpm1
switch Mstats

#
# Tool arguments
#

ifndef COMP_HPF	set COMP_HPF=pghpfc
ifndef HPFDIR	set HPFDIR=$PGI/$SYSTEM/bin

set DRIVER_ARGS_HPF="$EXTRA_DRIVER_ARGS_HPF -Mcray\=pointer"
ifndef COMP_ARGS_HPF	set COMP_ARGS_HPF="-x 49 4 $EXTRA_ARGS_HPF"

ifndef PGAPPEND	set PGAPPEND=pgappend
ifndef PGAPPENDDIR	set PGAPPENDDIR=$PGI/$SYSTEM/bin
ifndef PGAPPENDARGS	set PGAPPENDARGS=""

ifndef PGIPA	set PGIPA=pgipa
ifndef PGIPADIR	set PGIPADIR=$PGI/$SYSTEM/bin
ifndef PGIPAARGS	set PGIPAARGS=""

#
# HPF libraries and startup files
#
# Defines LPGFTNRTL, PGFMAIN, LPGHPF and LPVM3
#

ifndef LPVM3 \
  set LPVM3="/usr/local/pvm3/lib/SUN4/libpvm3.a $HPF_SOCKET"

if -Mstats set P="_p"
if PROF_HPF_FUNC	set P="_p"
if PROF_HPF_LINES	set P="_p"

if PGHPF \
  ifn	-Mnohpf \
    set LPGFTNRTL="-lhpfrtl" \
    ifndef LPGHPF \
      set LPGHPF="-lhpf$P $HPF_SOCKET $HPF_PROF_LIBS -lhpf2" \
      if -Mpvm \
	  set LPGHPF="-lhpf_pvm $LPVM3 $HPF_PROF_LIBS -lhpf2_pvm" \
      endif \
      if -Mrpm \
	  set LPGHPF="-lhpf_rpm$P $HPF_SOCKET $HPF_PROF_LIBS -lhpf2_rpm" \
      endif \
      if -Mrpms \
	  set LPGHPF="-lhpf_rpms $HPF_RPMS $HPF_PROF_LIBS -lhpf2_rpms" \
      endif \
      if -Mrpm1 \
	  set LPGHPF="-lhpf_rpm1 $HPF_UCB $HPF_PROF_LIBS -lhpf2_rpm1" \
      endif \
      if -Mtracegen \
	  set LPGHPF="-lhpf_par $HPF_TRACEGEN $HPF_PROF_LIBS -lhpf2_par" \
      endif \
      if -Mdolphin \
	  set LPGHPF="-lhpf_dol $HPF_SOCKET $HPF_PROF_LIBS -lhpf2_dol" \
      endif \
    endif \
    set PGFMAIN="$PGIDIR/hpfmain.o" \
    if -Mpvm \
	  set PGFMAIN="$PGIDIR/hpfmain_pvm.o" \
    endif \
    if -Mrpm \
	  set PGFMAIN="$PGIDIR/hpfmain_rpm.o" \
    endif \
    if -Mrpms \
	  set PGFMAIN="$PGIDIR/hpfmain_rpms.o" \
    endif \
    if -Mrpm1 \
	  set PGFMAIN="$PGIDIR/hpfmain_rpm1.o" \
    endif \
    if -Mtracegen \
	  set PGFMAIN="$PGIDIR/hpfmain_par.o" \
    endif \
    if -Mdolphin \
	  set PGFMAIN="$PGIDIR/hpfmain_dol.o" \
    endif \
    ifndef HPF_PROF_LIBS \
	if PROF_HPF_FUNC	set HPF_PROF_LIBS="-lpgpfh"	endif \
	if PROF_HPF_LINES	set HPF_PROF_LIBS="-lpgpfh"	endif \
    endif \
    set HPF_LIBS="$LPGHPF" \
  endif \
endif

set PGFALT="hpfalt.o"

[*] The C++ driver on DOS systems is pgcpp.

<< >> Title Contents Index Home Help