<< " border=0>

> " border=0>

1 Getting Started

• 1.1 Overview
• 1.2 Invoking the command-level PGI Compilers
  • 1.2.1 Command-line Syntax-
  • 1.2.2 Command-line Options
  • 1.2.3 Fortran Directives and C/C++ Pragmas
• 1.3 Filename Conventions
  • 1.3.1 Input Files
  • 1.3.2 Output Files
• 1.4 Parallel Programming Using the PGI Compilers
  • 1.4.1 Running SMP Parallel Programs
  • 1.4.2 Running Data Parallel HPF Programs
• 1.5 Using the PGI Compilers on Linux
  • 1.5.1 Linux Header Files
  • 1.5.2 Running Parallel Programs on Linux
• 1.6 Using the PGI Compilers on Win32

This chapter describes how to use the PGI compilers. The command used to invoke a compiler, for example the pgf90 command, is called a compilation driver. The compilation driver controls the following phases of compilation: preprocessing, compiling, assembling and linking. Once a file is compiled and an executable file is produced, you can execute, debug, or profile the program on your system. Executables produced by the PGI compilers are unconstrained, meaning they can be executed on any compatible IA-32 processor-based system regardless of whether the PGI compilers are installed on that system.

1.1 Overview

In general, using a PGI compiler involves three steps:

1. Produce a program in a file containing a .f extension or another appropriate extension (see section 1.3.1). This may be a program that you have written or a program that you are modifying.
2. Compile the program using the appropriate compiler command.
3. Execute, debug or profile the executable file on your system.

The PGI compilers allow many variations on these general program development steps. These variations include the following:

• Stop the compilation after preprocessing, compiling or assembling to save and examine intermediate results.
• Provide options to the driver that control compiler optimization or that specify various features or limitations.
• Include as input intermediate files such as preprocessor output, compiler output or assembler output.

1.2 Invoking the command-level PGI Compilers

To translate and link a Fortran, C, or C++ language program, the pgf77, pgf90, pghpf, pgcc, and pgCC commands do the following:

• Preprocess the source text file.
• Check the syntax of the source text.
• Generate an assembly language file.
• Pass control to the subsequent assembly and linking steps.

For example, if you enter the following simple Fortran program in the file hello.f:

print *, "hello"
end

you can compile it from a UNIX shell prompt or BASH for Win32 prompt using the default pgf90 driver options.

PGI$ pgf90 hello.f
Linking:
PGI$ 

By default the executable output is placed in the file a.out (a.exe on Win32). Use the -o option to specify an output file name. To place the executable output in the file hello:

PGI$ pgf90 -o hello hello.f 
Linking:
PGI$

To execute the resulting program, simply type the filename at the command prompt and hit return:

PGI$ hello 
 hello
PGI$

1.2.1 Command-line Syntax-

The command-line syntax, using pgf90 as an example, is:

pgf90  [options] [path]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 7, Command-line Options.

The compiler drivers recognize characters preceded by a hyphen (-) as command-line options. For example, the -Mlist option specifies that the compiler creates a listing file (in the text of this manual we show command-line options using a dash instead of a hyphen, for example
-Mlist). In addition, the pgCC command recognizes a group of characters preceded by a plus sign (+) as command-line options.

The order of options and the filename is not fixed. That is, you can place options before and after the filename argument on the 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.

path

is the pathname to the directory containing the file named by filename. If you do not specify path for a filename, the compiler uses the current directory. You must specify path separately for each filename not in the current directory. Note that within the BASH for Win32 shell, UNIX directory naming conventions are assumed. In particular, "/" is used to separate directory names in the directory hierarchy.

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 [path]filename.

1.2.2 Command-line Options

The command-line options control various aspects of the compilation process. For a complete alphabetical listing and a description of all the command-line options, refer to Chapter 7, Command-line Options.

1.2.3 Fortran Directives and C/C++ Pragmas

Fortran directives or C/C++ pragmas inserted in program source code allow you to alter the effects of certain command-line options and control various aspects of the compilation process for a specific routine or a specific program loop. For a complete alphabetical listing and a description of all the Fortran directives and C/C++ pragmas, refer to Chapter 9, Optimization Directives and Pragmas, Chapter 10, OpenMP Parallelization Directives for Fortran, and Chapter 11, OpenMP Parallelization Pragmas for C and C++.

1.3 Filename Conventions

The PGI compilers use 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 assembly-language files, preprocessed source files, Fortran/C/C++ source files, object files and libraries as inputs on the command line. The compilation driver determines the type of each input file by examining the filename extensions. The drivers use the following conventions:

filename.f

indicates a Fortran source file.

filename.F

indicates a Fortran source file that can contain macros and preprocessor directives (to be preprocessed).

filename.f90

indicates a Fortran 90 source file that is in freeform format.

filename.hpf

indicates an HPF source file.

filename.c

indicates a C source file that can contain macros and preprocessor directives (to be preprocessed).

filename.i

indicates a pre-processed C or C++ source file.

filename.C

indicates a C++ source file that can contain macros and preprocessor directives (to be preprocessed).

filename.cc

indicates a C++ source file that can contain macros and preprocessor directives (to be preprocessed).

filename.s

indicates an assembly-language file.

filename.o

indicates an object file.

filename.a

indicates a library of object files.

filename.so

(UNIX systems only) indicates a library of shared object files.

The driver passes files with .o, .so and .a extensions to the linker and .s files to the assembler. Input files with unrecognized extensions, or no extension, are also passed to the linker.

Files with a .F (Capital F) suffix are first preprocessed by the Fortran compilers and the output is passed to the compilation phase. The Fortran preprocessor functions similar to cpp for C/C++ programs, but is built in to the Fortran compilers rather than implemented through an invocation of cpp. This ensures consistency in the pre-processing step regardless of the type or revision of operating system under which you're compiling.

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 on the command line, code within other files can be compiled as part of "include" files using the INCLUDE statement in a Fortran source file or the preprocessor #include directive in Fortran source files that use a .F extension or C and C++ source files

When linking a program module with a library, the linker extracts only those library modules that the program needs. The compilation drivers link in several libraries by default. For more information about libraries, refer to Chapter 8, Libraries.

1.3.2 Output Files

By default, an executable output file produced by one of the PGI compilers is placed in the file a.out (a.exe on Win32) As shown in the preceding section you can use the -o option to specify the output file name.

If you use one of the options: -F (Fortran only), -P (C/C++ only), -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 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 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 any of the PGI compilation drivers. Table 1-1 lists the stop after options and the output files that the compilers create when you use these options.

Table 1-1 Stop after Options, Inputs and Outputs

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.f

indicates a preprocessed file (if you compiled a Fortran file using the
-F option).

filename.lst

indicates a listing file from the -Mlist option.

filename.o

indicates an object file from the -c option.

filename.s

indicates an assembly-language file from the -S option.

The following example demonstrates the use of output filename extensions.

$ pgf90 -c proto.f  proto1.F

This produces the output files proto.o and proto1.o, both of which are binary object files. Prior to compilation, the file proto1.F is pre-processed because it has a .F filename extension.

1.4 Parallel Programming Using the PGI Compilers

The PGI compilers support 3 styles of parallel programming:

• Automatic shared-memory parallel programs compiled using the -Mconcur option to pgf77, pgf90, pgcc, or pgCC - parallel programs of this variety can be run on shared-memory parallel (SMP) systems such as dual-processor workstations. Section 3.1.2, Using the -Mconcur Auto-parallelization Option, contains a complete description of -Mconcur.
• User-directed shared-memory parallel programs compiled using the -mp option to pgf77, pgf90, pgcc, or pgCC - parallel programs of this variety can be run on SMP systems. Carefully coded user-directed parallel programs using OpenMP directives can often achieve significant speed-ups on large numbers of processors on SMP server systems. Chapter 10, OpenMP Parallelization Directives for Fortran, and Chapter 11, OpenMP Parallelization Pragmas for C and C++ contain complete descriptions of user-directed parallel programming.
• Data parallel shared- or distribute-memory parallel programs compiled using the PGHPF High Performance Fortran compiler - parallel programs of this variety can be run on SMP workstations or servers, distributed-memory clusters of workstations, or clusters of SMP workstations or servers. Coding a data parallel version of an application can be somewhat more work than using OpenMP directives, but has the advantage that the resulting executable is usable on all types of parallel systems regardless of whether shared memory is available. See the PGHPF User's Guide for a complete description of how to build and execute data parallel HPF programs. Note: the -Mconcur option is valid with the PGHPF compiler and can be used to create hybrid shared/distributed-memory parallel programs.

In this manual, the first two types of parallel programs are collectively referred to as SMP parallel programs. The third type is referred to as a data parallel program, or simply as an HPF program.

1.4.1 Running SMP Parallel Programs

When you execute an SMP parallel program, by default it will use only 1 processor. If you wish to run on more than 1 processor, set the NCPUS environment variable to the desired number of processors (subject to a maximum of 4 for PGI's workstation-class products). You can set this environment variable by issuing the following command:

% setenv NCPUS <number>

on Linux or Solaris under csh, or with

% NCPUS=<number>; export NCPUS

in sh or ksh, or within a BASH for Win32 command window.

NOTE: If you set NCPUS to a number larger than the number of physical processors, your program will execute very slowly.

A ready-made example of an auto-parallelizable benchmark is available at the URL:

	ftp://ftp.pgroup.com/pub/SMP/linpack.tar

Unpack it within a UNIX shell window or a BASH for Win32 command window using the command:

% tar xvf linpack.tar

and follow the instructions in the supplied README file.

In addition to the NCPUS environment variable, directive-based parallel programs built using the OpenMP features of PGF77 and PGF90 recognize the OpenMP-standard environment variable OMP_NUM_THREADS. Initialization and usage are identical to that for NCPUS. A ready-made example of an OpenMP parallel program is available at the URL:

	ftp://ftp.pgroup.com/pub/SMP/matmul.tar

Unpack it within a UNIX shell window or a BASH for Win32 command window using the command:

% tar xvf matmul.tar

and follow the instructions in the supplied README file. In addition to showing the OpenMP capabilities of PGF77 and PGF90, this example also further illustrates auto-parallelization and provides a brief glimpse of the capabilities of the PGHPF data parallel compiler on SMP systems.

1.4.2 Running Data Parallel HPF Programs

When you execute an HPF program, by default it will use only 1 processor. If you wish to run on more than 1 processor, use the -pghpf -np runtime option. For example, to compile and run the hello.f example defined above on one processor, you would issue the following commands

% pghpf -o hello hello.f 
Linking:
% hello
 hello
%

To execute it on two processors, you would issue the following commands:

% hello -pghpf -np 2
 hello
%

NOTE: If you specify a number larger than the number of physical processors, your program will execute very slowly.

Note that you still only see a single "hello" printed to your screen. This is because HPF is a single-threaded model, meaning that all statements execute with the same semantics as if they were running in serial. However, parallel statements or constructs operating on explicitly distributed data are in fact executed in parallel. The programmer must manually insert compiler directives to cause data to be distributed to the available processors. See the PGHPF User's Guide and The High Performance Fortran Handbook for more details on constructing and executing data parallel programs on shared-memory or distributed-memory cluster systems using PGHPF.

Several ready-made examples of data parallel HPF programs are available at the URL:

	ftp://ftp.pgroup.com/pub/HPF/examples

In particular, the matrix multiply example matmul.tar is a good example to start with. Unpack it within a UNIX shell window or a BASH for Win32 command window using the command:

% tar xvf matmul.tar

and follow the instructions in the supplied README file. Also available at this URL are HPF implementations of several of the NAS Parallel Benchmarks.

1.5 Using the PGI Compilers on Linux

1.5.1 Linux Header Files

The Linux system header files contain many GNU gcc extensions. Many of these extensions are supported. This should allow the PGCC C and C++ compilers to compile most programs compilable with the GNU compilers. A few header files not interoperable with previous revisions of the PGI compilers have been rewritten and are included in $PGI/linux86/include. These files are: sigset.h, asm/byteorder.h, stddef.h, and asm/posix_types.h. Also, PGI's version of stdarg.h should support changes in newer versions of Linux.

If you are using the PGCC C or C++ compilers, please make sure that the supplied versions of these include files are found before the system versions. This will happen by default unless you explicitly add a -I option that references one of the system include directories.

1.5.2 Running Parallel Programs on Linux

The PGI compilers use the LinuxThreads package by Xavier Leroy for SMP parallelism on Linux. Because of potential incompatibilities with installed versions of this package, PGI now ships a custom version of the library in $PGI/linux86/lib/libpgthread.a. This version of the library will be included by default before any system version of the library. This library is used only when -Mconcur or -mp is specified on the command line.

For some reason there have been problems with some parallel programs on Linux systems when the per-thread stack size is set to the default (2MB). If you have unexplained failures, please try setting the environment variable MPSTKZ to a larger value, such as 8MB. This can be accomplished with the command:

% setenv MPSTKZ 8M

in csh, or with

% MPSTKZ=8M; export MPSTKZ

in bash, sh, or ksh.

If your program is still failing, you may be encountering the hard 8 MB limit on main process stack sizes in Linux. You can work around the problem by becoming root, issuing the command:

% limit stacksize unlimited

in csh, or

% ulimit -s unlimited

in bash, sh, or ksh. There is currently no way for a normal user to increase the stacksize limit without rebuilding the Linux kernel.

1.6 Using the PGI Compilers on Win32

On Win32, the tools that ship with the PGI compilers include a full-featured UNIX-like command environment. After installation, you should have a PGI icon on your Win32 desktop. Double-left-click on this icon to cause an instance of the BASH command shell to appear on your screen. Working within BASH is very much like working within the sh or ksh shells on a UNIX system, but in addition BASH has a command history feature similar to csh and several other unique features. Shell programming is fully supported. A complete BASH User's Guide is available in the PGI online manual set. Select "PGI Workstation" under Start->Programs and double-left-click on the documentation icon to see the online manual set. You must have a web browser installed on your system in order to read the online manuals.

The BASH shell window is pre-initialized for usage of the PGI compilers, so there is no need to set environment variables or modify your command path when the command window comes up. In addition to the PGI compiler commands referenced above, within BASH you have access to over 100 common UNIX-like commands and utilities, including but not limited to the following:

If you are familiar with program development in a UNIX environment, editing, compiling, and executing programs within BASH will be very comfortable. If you have not previously used such an environment, you should take time to familiarize yourself with either the vi or emacs editors and with makefiles. The emacs editor has an extensive online tutorial, which you can start by bringing up emacs and selecting the appropriate option under the pulldown help menu. In addition there is a full online EMACS User's Guide included as part of the PGI compilers online manual set referenced above. You can get a thorough introduction to the construction and use of makefiles in the online Makefile User's Guide. A simple example makefile is included in the Linpack100 benchmark example referenced above.

<< " border=0>

> " border=0>