This chapter describes how to use pghpf to control the translation
process for a program written in High Performance Fortran (HPF). The pghpf
command is called the compilation driver. The compilation
driver controls several phases of compilation: HPF compiling, Fortran 77
preprocessing and compiling, assembling and linking (linking includes the
correct pghpf runtime routines for the target communications protocol).
Since pghpf runs on a variety of host systems and generates output for
several target systems, the commands that allow you to run (execute) a program
will vary from system to system.
In general, using pghpf, the compilation process involves three steps:
- Produce an HPF program and give your file a .hpf, .f90,
.for , .F or .f file extension. The HPF program may be a
program that you have written or a program that you are modifying for parallel
execution.
- Compile the HPF program using pghpf and supply appropriate
compiler command line options. This produces a ready to run binary file
and by default links the HPF runtime libraries.
- Execute the binary file on the target system (the target system
may
be your local system). The execution behavior of your program can be controlled
with runtime command line options or environment variables.
The pghpf
compiler allows many variations on these general program development
steps. These variations include the following:
- Stop the compilation after HPF compilation, after Fortran 77 compilation
or after assembling to save and examine intermediate results.
- Provide options to the driver that control compiler optimization, that
specify an alternate communications protocol, or to enable various compiler
features.
- Include as input intermediate files such as preprocessor output, compiler
output or assembler output.
The pghpf compiler targets an SPMD
(Single Program Multiple Data) programming model. Each processor executes the
same program, but operates on different data. This is implemented by loading
the same program image into each processor. Each processor then allocates and
operates on its own local portion of distributed arrays, according to the
distributions, array sizes and number of processors as determined at runtime by
HPF directives or using command line arguments. Special attention is required
to address the unique communication characteristics of many parallel systems.
The pghpf runtime libraries take into account the communications to be
performed and are optimized at two levels, the transport independent level,
where efficient communications are generated based on the type and pattern of
data access performed in the computation, and at the transport dependent level
where the runtime library's communication is performed using a standard
communications protocol or a custom data transfer mechanism.
To translate and link an HPF program, pghpf does the following:
- Preprocesses the HPF source text file.
- Checks the syntax of the HPF source text.
- Optionally generates a Fortran 77 program including calls to the
pghpf runtime library.
- Generates an assembly language file from the Fortran 77 file.
- Passes control to the subsequent assembly and link steps.
Figure 1.1
shows the stages that are under driver control. The driver sets the HPF
compiler and Fortran 77 compiler switches and assembles and links the program.
It lets you pass command-line options to any of the various driver stages.
Chapter 2, pghpf Compiler Options, covers the compiler's command-line
options. The executable output from pghpf is an SPMD program that can
execute on a target parallel system. Chapter 3, PGHPF Runtime Options,
describes some of the command-line options and environment variables available
for the pghpf runtime (executable) environment.
Figure 1-1 Stages of the pghpf driver
For more information on the Fortran 77 compiler, the assembler and linker,
refer to the documentation listed in the Preface or to the appropriate
manuals supplied with your system.
The following examples show several driver options that should be available on
most systems. The command-lines and output may differ on your system. You can
compile the HPF program hello.hpf using the default pghpf driver
options.
$ pghpf hello.hpf
By
default, the executable output is placed in the file a.out. You can use
the -o option to specify the output file.
$ pghpf -o hello hello.hpf
To
see the command lines that pghpf will run, without actually executing
them, use the driver's -dryrun option. For example:
$ pghpf -dryrun -o hello hello.hpf
/usr/pgi/arch/bin/pghpfc hello.hpf -output hello.f
-stdinc
/usr/pgi/arch/include:/usr/include -def sun
-def arch -def unix -inform warn
-terse 1
/usr/pgi/arch/bin/pgftn hello.f -x 124 0x400 -inform warn -terse 2 -astype 1 -opt
1 -fn hello.hpf
-asm /usr/tmp/pghpfAAAa14451
/usr/bin/as -Q -o hello.o /usr/tmp/pghpfAAAa14451
Unlinking /usr/tmp/pghpfAAAa14451
/usr/bin/ld -dc -dp -e start -X -L/usr/pgi/arch/lib -L/usr/lib -o hello
/usr/lib/crt0.o /usr/pgi/arch/lib/hpfmain_rpm.o hello.o -lhpfrtl -lhpf_rpm -lm
-lpgc -lc
Unlinking hello.o
1.2.1 pghpf Command-
line
Syntax
The pghpf command-
line
syntax is:
pghpf [options] filename [...]
Where:
- options
is one or more command-line options. Case is significant for options
and their arguments. For a complete description of the options, refer to
Chapter 2, pghpf Compiler Options.
-
- The driver recognizes characters preceded by a hyphen (-
)
as a command-
line
option. For example, the -Mextend option specifies that the compiler
accepts extended 132 column lines[*].
-
- The order of options and the filename is not fixed. That is,
you can place options both before and after the filename argument on the
driver command line. However, the placement of some options is significant, for
example the -l option.
-
- If two or more options contradict each other, the last one in the command
line takes precedence.
- filename
- is the name of a source file, assembly-language file, object file, or
library to be processed by the compilation system. You can specify more than
one filename.
1.2.2 Compiler Command-line Options
The compiler command-line options control various aspects of the compilation
process. For a listing and a description of the pghpf specific compiler
command-line options, refer to Chapter 2, pghpf Compiler Options.
There are many additional options that apply to the node-compiler for your
system (PGI's pgf77 Fortran is one possible node compiler), refer to the
pgf77 User's Guide for details on the pgf77
compiler command-line options and to the user manual for your node compiler for
other systems (you can also use the pghpf driver option -help to
list the available options.
Several options provide for optimization of the HPF program. These compiler
command line options, -O1, and -O2, provide varying levels of
optimization to the HPF code, and also set optimization flags for the Fortran
77 node compiler. For details on the optimization transformations applied,
refer to the Release Notes supplied with the pghpf Software.
The pghpf driver uses the filenames that you specify on the
command line to find and to create input and output files. This section
describes the input and output filename conventions for the phases of the
compilation process.
1.3.1 Input Files
You can specify HPF source files, preprocessed HPF source files,
assembly-language files, object files and libraries as inputs on the pghpf
command line. The driver determines the type of each input file by
examining the filename extension. The driver uses the following conventions:
- filename.a
- indicates a library of object files.
- filename.f
- indicates an HPF source file.
- filename.F
- indicates an HPF source file with preprocessing.
- filename.for
- indicates an HPF source file.
- filename.f90
- indicates an HPF source file.
- filename.hpf
- indicates an HPF source file.
- filename.o
- indicates an object file.
- filename.s
- indicates an assembly-language file.
The driver passes files with .o and .a extensions to the
linker and .s files to the assembler. Input files with unrecognized
extensions, or no extensions, are also passed to the linker.
Any input files not needed for a particular phase of processing are not
processed. For example, if on the command line you use an assembly-language
file (filename.s) and the -S option to stop before the assembly
phase, the compiler takes no action on the assembly-
language
file. Processing stops after compilation and the assembler does not run (in
this case compilation must have been completed in a previous pass which created
the .s file). Refer to the following section, "Output Files," for a
description of the -S option.
In addition to specifying primary input files, files with extensions
indicating an HPF source file on the command line, you can insert text from
include files using the INCLUDE statement or the preprocessor
#include directive from within HPF source files (includes and
preprocessing is only available if you use a .F extension or the
-Mpreprocess command line argument).
When linking a program object file with a library, the linker extracts only
those objects from the library that the program needs. The pghpf driver
includes several libraries by default. For more information about libraries,
refer to Chapter 4, PGHPF Libraries.
1.3.2 Output Files
By default, the pghpf executable output is placed in the file
a.out. In addition, on the command line you can use the -o option
to specify the output file.
If you use one of the options: -Mftn, -F, -S or
-c, the compiler produces a file containing the output of the last phase
that completes for each input file, as specified by the option supplied. The
output file will be a Fortran 77 file with pghpf runtime library calls,
an HPF preprocessed source file, an assembly-language file or an unlinked
object file respectively. Similarly, the -E option does not produce a
file, but displays the preprocessed HPF source file on the standard output.
Using any of these options, the -o option is valid only if you specify a
single input file. If no errors occur during processing, you can use the
files created by these options as input to a future invocation of pghpf.
Table 1-1 lists the stop after options and the output files that
pghpf creates when you use these options.
If you specify multiple input files or do not specify an object filename, the
compiler uses the input filenames to derive corresponding default output
filenames of the following form, where filename is the input filename
without its extension:
- filename.o
- indicates an object file from the -c option.
- filename.s
- indicates an assembly-language file from the -S option.
- filename.f
- indicates a Fortran 77 file with pghpf runtime library calls.
Table 1-1 Stop after Options and Outputs
Option Stop after Output from pghpf
-F preprocessing preprocessed file - .f
-Mftn HPF compilation Fortran 77 file
-S compilation assembly-language file - s.
-c assembly unlinked object file - .o
none linking executable files a.out
When running pghpf you can save the intermediate Fortran 77 file
generated from the first stage of pghpf using the -Mkeepftn
option. This option continues the compilation after HPF compiling, but does not
remove the intermediate Fortran 77 file.
Note
Unless you specify otherwise, the destination directory for any output file
is the current working directory. If the file exists in the destination
directory, the compiler overwrites it.