1 Getting Started

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.

1.1 Overview

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.

1.2 Invoking pghpf

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.

1.3 Filename Conventions

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.