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.
In general, using a PGI compiler involves three steps:
The PGI compilers allow many variations on these general program development steps. These variations include the following:
To translate and link a Fortran, C, or C++ language program, the pgf77, pgf90, pghpf, pgcc, and pgCC commands do the following:
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 NT 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 NT). 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$
The command-line syntax, using pgf90 as an example, is:
pgf90 [options] [path]filename [...]
Where:
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.
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++.
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.
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:
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.
By default, an executable output file produced by one of the PGI compilers is placed in the file a.out (a.exe on NT) 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.
Option
|
Stop after
|
Input
|
Output
|
|---|---|---|---|
-E |
preprocessing |
Source files (must have .F extension for Fortran) |
preprocessed file to standard out |
-F |
preprocessing |
Source files (must have .F extension, this option is not valid for pgcc or pgCC) |
preprocessed file - .f |
-P |
preprocessing |
Source files (this option is not valid for pgf77, pgf90 or pghpf) |
preprocessed file - .i |
-S |
compilation |
Source
files or |
assembly-language
|
-c |
assembly |
Source
files, |
unlinked
object |
none |
linking |
Source files, preprocessed files, assembly-language files, object files or libraries |
executable
files |
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:
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.
The PGI compilers support 3 styles of parallel programming:
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.
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 NT 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 NT 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 NT 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.
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 NT 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.
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.
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/libpthread.a. This version of the library will be included by default before any system version of the library. The 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.
On NT, 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 NT 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:
vi |
emacs |
make |
tar / untar |
gzip / gunzip |
ftp |
sed |
grep / egrep / fgrep |
awk |
cat |
cksum |
cp |
date |
diff |
du |
find |
kill |
ls |
more / less |
mv |
printenv / env |
rm / rmdir |
touch |
wc |
Depending on the release of the PGI compilers you have purchased, you may need to choose "Custom Installation" when installing in order to user the emacs editor.
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.