User manual APOGEE SOFTWARE APOGEE COMPILERS C & C++ & FORTRAN 77 & FORTRAN 90

USER'S MANUAL rs FOR e COMPILERS VAPOGEE APOGEE-CTM APOGEE-C++TM n io HIGHLY OPTIMIZING COMPILERS WITH INTRODUCTION TO KAPTM & VASTTM PREPROCESSORS & FLEXLMTM LICENSE MANAGER 4.0 APOGEE-FORTRAN 77TM APOGEE-FORTRAN 90TM © 1990-1996 -- Apogee Software, Inc. Revised November, 1996 for Release 4.0. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the express written permission of Apogee Software, Inc. Information in this document is subject to change without notice and does not represent a commitment on the part of Apogee Software, Inc. The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. Apogee-C, Apogee-C++, Apogee-FORTRAN 77, Apogee-Fortran 90 and the Apogee logo { } are trademarks of Apogee Software, Inc. KAP is a trademark of Kuck and Associates, Inc. VAST is a registered trademark of Pacific-Sierra Research Corporation. UNIX is a registered trademark and is exclusively licensed by X/Open Company, Ltd. SPARC is a registered trademark of SPARC International, Inc. All SPARC trademarks, including microSPARC, SuperSPARC, hyperSPARC, and UltraSPARC are trademarks or registered trademarks of SPARC International, Inc. SunOS, Solaris and SunSoft are trademarks or registered trademarks of Sun Microsystems, Inc. PowerPC is a trademark of International Business Machines Corporation. VAX and VMS are trademarks of Digital Equipment Corporation. Cray is a registered trademark of Cray Research, Inc., and/or Silicon Graphics, Inc. FLEXlm is a trademark of Globetrotter Software. Portions of the FLEXlm Manual are used with permission of Globetrotter Software. All other names are trademarks of their respective holders. Throughout this manual, trademarked names are used without placing a trademark symbol at every occurrence. All such names are used in an editorial fashion only, with no intention of trademark infringement. Inquires concerning trademarks or trademarked products should be directed to the companies involved. Table of Contents Table of Contents Table of Contents ............................................................................................... 3 Preface .................................................................................................................. 9 Contents of this Manual ...........................................................................................9 Typographic Conventions ...................................................................................... 11 Terminology .............................................................................................................12 A 3-minute Guide to Using the Apogee Compilers ...........................................13 Chapter 1 Introduction to the Apogee Compilers........................................................... 15 The Compilation System ........................................................................................15 Optimization ............................................................................................................19 Control of Compiler Behavior ...............................................................................21 Chapter 2 Invoking the Compilers..................................................................................... 23 Compiler Invocation Command ...........................................................................23 Files............................................................................................................................23 Fortran 90 File Names.............................................................................................25 Options......................................................................................................................25 Chapter 3 Control-Variables and Control-Programs...................................................... 33 Control-Variables.....................................................................................................33 Control-Groups........................................................................................................35 Control-Expressions ................................................................................................36 Control-Assignments ..............................................................................................37 Control-Programs ....................................................................................................38 Writing Pragma Directives.....................................................................................39 Apogee User's Manual Page 3 Apogee Software, Inc. Chapter 4 Control-Variable Definitions ........................................................................... 41 Optimization Control-Variables............................................................................ 41 Introduction to Optimization......................................................................... 41 Control-Variable alias -- Alias Analysis ...................................................... 43 Control-Variable callmod -- Call Modification Analysis .......................... 44 Control-Variable cih -- Cross-Iteration Hoisting........................................ 45 Control-Variable constp -- Constant Propagation...................................... 45 Control-Variable copyp -- Copy Propagation............................................. 46 Control-Variable domain -- Optimization Domain ................................... 46 Control-Variable fcm -- Forward Code Motion.......................................... 46 Control-Variable flex -- Optimization Flexibility ....................................... 47 Control-Variable flow -- Control Flow Optimization................................ 47 Control-Variable fltacc -- Floating Point Expression Rearrangement & Numerical Accuracy................................................................................. 48 Control-Variable fltedge -- Floating Point Limits ...................................... 49 Control-Variable fltfold -- Floating Point Constant Folding .................... 50 Control-Variable intedge -- Integer Limits.................................................. 50 Control-Variable ivrep -- Induction Variable Replacement...................... 50 Control-Variable memlimit -- Scope of Main Optimizations ................... 51 Control-Variable mopt -- Main Optimizations........................................... 51 Control-Variable reg -- Register Allocation ................................................ 52 Control-Variable safeintr -- Intrinsic Error Checking................................ 53 Control-Variable sched -- Scheduling.......................................................... 53 Control-Variable unroll -- Loop Unrolling.................................................. 54 Control-Variable unrollexact -- Loop Unrolling Exactness ...................... 54 Control-Variable whole -- Whole Program Compilation.......................... 55 Control-Variable xopt -- Extra Optimizations ............................................ 55 Control-Variable zone -- Expansion of Zones............................................. 56 Control-Variables inline, noinline, deflib, inllev and sinllev -- Routine Inlining ....................................................................................................... 56 Control-Variables profile and pstat -- Profiling Feedback to Inlining .... 58 Control-Group O -- Optimization ................................................................ 59 Target Computer Control-Variables ..................................................................... 59 Control-Variable cg -- Target Computer Instruction Set ........................... 60 Control-Variable pipe -- Target Computer Instruction Pipeline .............. 61 Control-Group T -- Target Computer .......................................................... 62 Diagnostic Control-Variables ................................................................................ 62 Control-Variable diag -- Diagnostic Output Level .................................... 63 Control-Variable quit -- Diagnostic Quit Level .......................................... 64 Control-Variable stddiag -- Standard Diagnostics (FORTRAN only)..... 64 FORTRAN Source File Format.............................................................................. 64 FORTRAN 77 Statement Format ................................................................... 64 Control-Variable fblank -- FORTRAN Statement Blanks.......................... 66 Control-Variable fcols -- FORTRAN Statement Columns ........................ 66 Page 4 Apogee User's Manual Table of Contents Control-Variable ftab -- FORTRAN Tab Statements.................................. 66 Control-Group F -- FORTRAN Statement Format..................................... 67 Control-Variable fcont -- FORTRAN Continuation Lines ........................ 68 Control-Variable fstmt -- FORTRAN Statement Buffer............................. 68 Control-Variable case -- FORTRAN Case Sensitivity ................................ 69 Control-Variable dline -- FORTRAN Debug Lines .................................... 69 Fortran 90 Statement Format.......................................................................... 69 Control-Variable sform -- FORTRAN 90 Statement Format..................... 70 FORTRAN 77 Compilation.................................................................................... 70 Control-Variable alnstd -- FORTRAN Standard Common/Equivalent Layout ........................................................................................................ 70 Control-Variable cmul -- Complex multiply............................................... 72 Control-Variable comname -- COMMON Block Name Format .............. 72 Control-Variable ftype -- FORTRAN Types................................................ 73 Control-Variable implicit -- Assumed Implicit None Statement ............. 76 Control-Variable onetrip -- One-Trip DO Loops in FORTRAN ............... 76 Control-Variable save -- SAVE Variables in FORTRAN............................ 77 Control-Variable vms -- VAX/VMS Compatibility ................................... 80 C/C++ Compilation ............................................................................................... 81 Control-Variable c -- C/C++ Language Modes.......................................... 81 Control-Variable char -- Signedness of plain char in C/C++................... 83 Control-Variables sizet and wchart -- Definitions of types size_t and wchar_t in C/C++ .................................................................................... 84 Control-Variable fltdbl -- Single vs. Double Arithmetic ........................... 85 Control-Variable inclpath -- Include File Searching .................................. 85 Control-Variable join -- Combining Programs ........................................... 86 C++ Compilation..................................................................................................... 87 C++ Dialect ....................................................................................................... 87 Control-Variable tmpl -- Template Instantiation Mode in C++ ............... 87 General Code Control............................................................................................. 90 Control-Variable addr -- Data Addressing Mode ...................................... 90 Control-Variable alnref -- Alignment of Indirect References ................... 90 Control-Variable bss -- Use of .bss section .................................................. 92 Control-Variable flat -- Flat Register Model ............................................... 92 Control-Variable fltconst -- Single Precision Floating Point Constants .. 93 Control-Variable g -- Symbolic Debugging ................................................ 95 Control-Variable glbreg -- Use of Global Registers in Compiled Code .. 95 Control-Variable kap -- Use of the KAP Preprocessor .............................. 96 Control-Variable prof -- Profiling ................................................................. 97 Control-Variable relfunc -- Routine Handling in Assembly Files ........... 97 Control-Variable vast -- Use of the VAST Preprocessor ............................ 98 Properties of Variables............................................................................................ 98 Control-Variables volatile, defvol, ptrvol -- Volatile Variables ................ 98 Miscellaneous Controls .......................................................................................... 99 Apogee User's Manual Page 5 Apogee Software, Inc. Control-Variable lmstat -- Status of License Manager............................... 99 Control-Variable progress -- Status of Compilation ................................ 100 Control-Variable show -- Output Values of Control-Variables .............. 101 Control-Variable xref -- Output a Cross-Reference Table ....................... 101 Chapter 5 Reference Tables ............................................................................................... 105 Control-Variable Reference Table ....................................................................... 105 Control-Group Reference Tables......................................................................... 129 Optimization Group (O) ............................................................................... 129 Fortran Input Format Group (F) .................................................................. 130 Target Machine Group (T) ............................................................................ 131 Chapter 6 Programming Restrictions............................................................................... 133 Introduction to Programming Restrictions and Optimization....................... 133 Required Restrictions ........................................................................................... 135 Uninitialized Variables.................................................................................. 135 Overlapping String Moves ........................................................................... 136 Side-effects Within a Zone ............................................................................ 136 Assignable Actual Parameters (FORTRAN) .............................................. 137 EQUIVALENCE/COMMON Cross-Typing (FORTRAN) ....................... 137 Default Restrictions .............................................................................................. 138 Out of Bound References/Wildness............................................................ 138 Asynchronous Modifications/Volatility..................................................... 138 SETJMP and LONGJMP (C) ......................................................................... 141 Assigned GOTO Bounds (FORTRAN) ....................................................... 141 Dummy Argument Aliasing (FORTRAN) ................................................. 142 Recursion (FORTRAN) ................................................................................. 142 Compilation Restrictions ..................................................................................... 143 Interprocedural Optimizations and Compilation ..................................... 143 Mixing C and Fortran, or FORTRAN-77 and Fortran 90 ......................... 143 Using Fortran 90 MODULEs........................................................................ 144 Using the KAP Preprocessor ........................................................................ 144 Using the VAST Preprocessor ...................................................................... 144 Using the VAST -mi Option.......................................................................... 144 Using control-variable whole....................................................................... 144 Chapter 7 The Apogee-FORTRAN 77/90 Languages .................................................... 145 Overview of Apogee-FORTRAN........................................................................ 145 ANSI FORTRAN-77 Features.............................................................................. 146 ANSI FORTRAN-66 Features.............................................................................. 146 MIL-STD 1753 Extensions.................................................................................... 146 VAX FORTRAN Extensions................................................................................. 147 Cray FORTRAN Extensions ................................................................................ 149 SUN FORTRAN Extensions ................................................................................ 149 Additional Extensions .......................................................................................... 150 Page 6 Apogee User's Manual Table of Contents Transformation of Symbol Names...................................................................... 150 Intermixing C Modules with FORTRAN Modules.......................................... 151 Control-Variables That Affect the FORTRAN Language ................................ 154 Fortran 90 Compilation Restrictions .................................................................. 155 Chapter 8 The Apogee-C & Apogee-C++ Languages....................................................157 C Language Definition ......................................................................................... 157 C++ Language Definition .................................................................................... 158 Dialect.............................................................................................................. 158 Boolean Type (bool) ....................................................................................... 158 Wide Characters (wchar_t) ........................................................................... 159 Special Pragmas ............................................................................................. 160 Exception Handling....................................................................................... 161 On-going Standardization Issues ................................................................ 162 Significant Comments .......................................................................................... 165 Predefined Symbols .............................................................................................. 166 Appendix A A 5-Minute VAST Guide ..............................................................................167 Introduction ........................................................................................................... 167 Optimizing Small Programs with VAST............................................................ 168 Optimizing Large Programs with VAST............................................................ 168 Improving and Customizing VAST Performance ............................................ 169 Additional Performance Improvement Techniques......................................... 170 Problems................................................................................................................. 171 Appendix B A 5-Minute KAP Guide .................................................................................173 Introduction ........................................................................................................... 173 Optimizing Small Programs with KAP ............................................................. 173 Optimizing Large Programs with KAP ............................................................. 174 Improving and Customizing KAP Performance.............................................. 175 Additional Performance Improvement Techniques......................................... 177 Problems................................................................................................................. 177 Appendix C Apogee Compilers on SPARC Systems......................................................179 Introduction ........................................................................................................... 179 Operating System Issues...................................................................................... 180 SPARC-specific control variables........................................................................ 180 SPARC-specific predefines................................................................................... 181 SPARC-specific command-line options ............................................................. 182 Compatibility......................................................................................................... 183 Appendix D Apogee Compilers on PowerPC Systems...................................................185 Appendix E Installation and License Management........................................................187 Overview................................................................................................................ 187 Installation Features ...................................................................................... 189 Mounting the Apogee CD-ROM......................................................................... 191 Apogee User's Manual Page 7 Apogee Software, Inc. Introduction .................................................................................................... 191 Procedure for Use .......................................................................................... 191 The Installation Process ................................................................................ 191 Installing From a Local CD Drive................................................................ 192 Installing From a Remote CD Drive............................................................ 193 The Installation Directory .................................................................................... 194 The FLEXlm License Manager ............................................................................ 198 How the FLEXlm License Manager Works ................................................ 198 The FLEXlm Log File..................................................................................... 199 The FLEXlm License-file ............................................................................... 200 SERVER Lines.......................................................................................... 200 DAEMON Lines...................................................................................... 201 FEATURE Lines ...................................................................................... 201 License File Example ..................................................................................... 202 Managing/Merging License-Files ............................................................... 202 The FLEXlm Options File ............................................................................. 204 RESERVE Line......................................................................................... 205 NOLOG Line ........................................................................................... 205 INCLUDE Line........................................................................................ 205 EXCLUDE Line ....................................................................................... 206 GROUP Line............................................................................................ 206 FLEXlm Utilities............................................................................................. 206 Troubleshooting Guide ................................................................................. 207 General Debugging Hints...................................................................... 207 Problem Description Format................................................................. 207 Problems .................................................................................................. 208 Index.................................................................................................................. 211 Page 8 Apogee User's Manual Preface Preface Contents of this Manual Throughout this manual, C and C++ are collectively referred to as C/C++, while FORTRAN 77 and Fortran 90 are collectively referred to as FORTRAN 77/90, or simply as FORTRAN. Cases specific to each language are noted by reference to the specific language. The addition of "Apogee-" to any of the above languages denotes the appropriate Apogee Compiler. Most of the information provided in this manual applies to the Apogee-C, Apogee-C++, ApogeeFORTRAN and Apogee-Fortran 90 compilers. When a specific point applies to any subgroup of these compilers, that fact is noted. This manual provides information on how to use the Apogee-C, Apogee-C++, ApogeeFORTRAN 77 and Apogee-FORTRAN 90 Optimizing Compilers running under the UNIX operating system. Information that is provided in this manual includes: · · · · · How to compile, assemble, and link programs. How to control the behavior of the compilers during compilation. Which kinds of optimizations are performed by the compilers. How the C, C++ and FORTRAN 77/90 languages accepted by the compilers compare with several industry-standard definitions of C/C++ and FORTRAN 77/90. Which programming restrictions apply when the Apogee compilers are used, and how to deal with programs that violate these restrictions. How to write C/C++ and FORTRAN 77/90 programs in general. (For that purpose a C, C++, FORTRAN 77 or Fortran 90 language reference manual should be consulted.) Information that is not provided in this manual includes: · Apogee User's Manual Page 9 Apogee Software, Inc. · How to use the various aspects of UNIX indirectly associated with compiling and executing programs, such as: 1) preparing program files to be input to the compilers, 2) using the make program, 3) using the debugger, 4) using the profiling facility, or 5) manipulating files output from program execution. For any of these topics, a suitable UNIX manual should be consulted. Specifically, the chapters of this manual are organized as follows: Chapter 1: Introduction to the Apogee Compilers. This chapter discusses and explains the various components of the compilation system, and gives an overview discussion of compiler optimization and control of the compiler's behavior. Invoking the Compilers. This chapter discusses the command line used to invoke the compilation system. This chapter is the "man page" in UNIX terminology. Control-Variables and Control-Programs. This chapter introduces the control-variables whose values can be set to govern the behavior of the compilers during compilation. Control-Variable Definitions. This chapter discusses the meaning of each of the control-variables. Reference Tables. This chapter contains tables that can be consulted to learn the important properties of each of the control-variables and control-groups. Programming Restrictions. This chapter discusses the restrictions on programming usage that must be followed when applying optimization to a program. The Apogee-FORTRAN 77/90 Languages. This chapter discusses the FORTRAN language accepted by the Apogee-FORTRAN and ApogeeFortran 90 Optimizing Compilers relative to industry standards. The Apogee-C & Apogee-C++ Languages. This chapter discusses the C and C++ languages accepted by the Apogee-C and Apogee-C++ Optimizing Compilers relative to several industry standards. A 5-Minute VAST Guide. This appendix gives a brief introduction to the VAST preprocessors, including commonly useful switches. A 5-Minute KAP Guide. This appendix is designed to supply the basic information needed to begin using the KAP preprocessors. Chapter 2: Chapter 3: Chapter 4: Chapter 5: Chapter 6: Chapter 7: Chapter 8: Appendix A: Appendix B: Page 10 Apogee User's Manual Preface Typographic Conventions Appendix C: Appendix D: Appendix E: Apogee Compilers on SPARC Systems. This appendix documents the features specific to Apogee's compilers on SPARC systems. Apogee Compilers on PowerPC Systems. This appendix documents the features specific to Apogee's compilers on PowerPC systems. Installation and License Management. This chapter is designed to assist users in installing Apogee products, and in understanding and utilizing the FLEXlm License Manager. Typographic Conventions The conventions for use of various typefaces in this manual are as follows: Purpose English prose definitions Convention The Palatino typeface is used for ordinary English prose in this manual. The bold variant of Palatino is used to emphasize words. For defined terms, at their point of definition, this typeface, the underlined variant of Palatino, is used. Some defined terms that are multiple words are hyphenated. For literal samples of text from some language given as input to or output from the computer, this typeface, the bold variant of a typeface named Courier, is used. Two examples are: "The control-variable mopt is used to govern the main optimizations." "When writing a for statement in C.... " variable fields computer text For parts of the compiler control language whose exact value must be specified by user, this typeface, the italic variant of Helvetica, is used. For example: "To govern the main optimizations, write mopt=n, where n is an integer from 0 through 4." "quotation marks" Quotation marks are used in the usual way for quoting text copied from another place, and for quoting text being discussed (as in the examples just above). Quotation marks are also used to set off technical terms borrowed from another context. Apogee User's Manual Page 11 Apogee Software, Inc. Terminology The following definitions apply to terms used throughout this manual: Term routine Definition A subroutine or function or procedure. As used in this manual, the term "routine" includes routines which either return a value or do not return a value, which are either main-routines or not main-routines, which have either a single entry point or have multiple entry points, and which are either written by the user or are intrinsic-routines. Thus in FORTRAN 77/90, the following things are routines: a program, a subroutine, a function, a block data subprogram, or an intrinsic function. A statement-function is not a routine. And in C/C++, the following things are routines: a user-written function or a library function. A preprocessor macro is not a routine. main-routine A routine that the user has coded to indicate that it is the starting point for program execution. In FORTRAN 77/90, a program. In C/C++, a function named main. A routine whose effect is defined as a part of the definition of the source language in use, so that it can be called by the user without needing to be supplied by the user. A collection of routines organized by the user to execute together. Each program must have exactly one main-routine, and may also have any number of non-main-routines. Any behavior of the compiled program that causes it to produce the wrong answers, or to fail to complete execution properly. The concept of correctness against which program failure or success is measured can come from either a standard language definition or from the behavior of the program when compiled by some other compiler. See the Index listing "program failure". A quantity that is similar in concept to a variable in a programming language, but that exists only during compilation and that is used to control the behavior of the compiler. Note the hyphen in "controlvariable". This distinguishes it from more casual use of the term, e.g., "The loop control variable ...". The particular kind and model of computer for which the compiler is to produce compiled code and the operating environment on it. The particular kind and model of computer on which the compiler is running. The usual situation is, of course, that the target computer is the same as the host computer. However, it is not necessary that this be true. intrinsic-routine program program failure control-variable target computer host computer Page 12 Apogee User's Manual Preface A 3-minute Guide to Using the Apogee Compilers A 3-minute Guide to Using the Apogee Compilers Read this section for a quick introduction to using the Apogee compilers. Also quickly scan the appendix specific to your target operating environment (eg, SPARC). On SPARC, the Apogee compilers support both Solaris 1 (SunOS 4.1.x) and Solaris 2.x. The compilers may be installed on any machine, with a single license permitting use of the compiler on any connected Solaris 1 or Solaris 2 machine. On a mixed Solaris 1/Solaris 2 network, the compilers may be used transparently on either OS, i.e. the compilers automatically determine whether they are running under Solaris 1 or Solaris 2. However, the compilers do not support cross-compilation. Running the compiler on a Solaris 1 system will produce a Solaris 1 binary, and running the compiler on a Solaris 2 system will produce a Solaris 2 binary. The Apogee compilers use the Flexible License Manager (FLEXlm) to permit floating license usage. That is, the compilers may be used on any machine that is on the same network as the license server for the compilers. The number of simultaneous users is limited to the number of licensed copies. For more information, see Appendix E. The Apogee compilers strongly follow UNIX tradition for compiler options. For areas where there is not an established UNIX tradition, options unique to the Apogee compilers are used. The common UNIX compiler options accepted by the Apogee compilers are as follows: -c, -g, -l, -o, -p, -w, -A, -C,-D, -E, -H, -I, -L, -O, -S, and -U. The Apogee compilers also accept several Sun-specific options. See page 182 in Appendix C. To see the "man page" for the compilers, see Chapter 2: "Invoking the Compilers", page 23. For the nontraditional options, which permit very detailed control of the compilers, see the -X option in Chapter 2 and the table of control-variables in Chapter 5. Overall control of optimization is done with the -On option, where n can range from 0 to 5. The default is -O1, which does only minimal optimization. The -O3 (or just -O) option is a very useful level of optimization. Levels -O4 and -O5 invoke interprocedural optimization and require extra care in managing recompilation. -O and -g may be specified together, though debugging optimized code presents certain challenges. Note: To optimize a given program, we recommend compiling it initially with "typical" compiler optimization enabled. Specifically, build your program using the optimization switch -fast (or -O), to get a baseline of optimized performance, before enabling other more sophisticated optimization switches. This simple approach generally results in excellent performance with virtually no effort. Optimization for a specific SPARC system can be done by specifying the -XT=name option, where name is one of the system names found in the table in "Target Machine Group (T)" on page 131. This option controls the instructions generated by the compiler plus the properties of the instruction pipeline and system cache assumed by the compiler. The compiled programs remain compatible across all SPARC systems, except that there are bugs in older versions of the SunOS emulation of the -cg92 level of instructions on older processors. Apogee User's Manual Page 13 Apogee Software, Inc. The VAST optimizing preprocessors from Pacific-Sierra Research are separately priced options available with the Apogee compilers. If purchased, they are invoked by specifying the -Xvast option. Please see "Appendix A: A 5-Minute VAST Guide," as well as the appropriate VAST User's Guide. If you are using Solaris 2 and you have purchased the multiprocessor VAST preprocessor, automatic parallelization of your program may be done with -Xvast=mp. The KAP optimizing preprocessors from Kuck & Associates are separately priced options available with the Apogee compilers. If purchased, they are invoked by specifying the -Xkap option. Please see "Appendix B: A 5-Minute KAP Guide," as well as the appropriate KAP User's Guide. If you are using Solaris 2 and you have purchased the multiprocessor KAP preprocessor, automatic parallelization of your program may be done with -Xkap=mp. Apogee-C offers several modes for dealing with the differences between traditional C and ANSI C. The default mode is ANSI compatible with some relaxed requirements. Other modes offer support for traditional C. See Chapter 8 for details. Apogee-C++ offers several modes for dealing with the differences between cfront-like C++ and ARM or ANSI C++. The default mode is ANSI compatible with a number of extensions. Other modes offer support for cfront-like C++. See Chapter 8 for details. Apogee-FORTRAN offers several modes for dealing with different FORTRAN dialects. The default mode is ANSI compatible with support for many extensions. Other modes offer support for non-ANSI features. See Chapter 7 for details. Apogee-FORTRAN offers support for a wide variety of FORTRAN input formats. See "FORTRAN Source File Format" on page 64 for details. Apogee-FORTRAN offers support for changing the compiled precision of numeric types declared in the program. See control-variable ftype on page 73 for details. The Apogee compilers can output cross-reference tables. See control-variable xref on page 101 for details. The Apogee compilers and the optimizing preprocessors each require that certain restrictions on programming usage (as specified in the ANSI C, C++ and FORTRAN standards) be met in order to apply full optimization. The restrictions required by the compilers are discussed in Chapter 6: "Programming Restrictions", page 133. The restrictions required by KAP are discussed further in the KAP User's Guide. Some programs contain latent violations of these ANSI restrictions. Such programs may fail when high degrees of optimization are applied. A systematic process of fixing or working around any such violations may then be necessary to get the best program performance. A particularly frequent violation of this sort is "save-usage" in FORTRAN programs. See "Control-Variable save -- SAVE Variables in FORTRAN" on page 77 for the details. The -Xsave option may be used to work around this problem. The Apogee compilers use the standard calling sequence, so compiled modules from other compilers may be intermixed and linked. However, Apogee-FORTRAN uses a different interface to FORTRAN I/O in order to increase speed, so FORTRAN programs doing I/O may not be intermixed. Also, because of internal implementation issues in C++ such as name mangling, C++ object files from different compilers may not be intermixed. Page 14 Apogee User's Manual Chapter 1 Chapter 1Introduction to the Apogee Compilers The Compilation System The Apogee optimizing compilers are part of a compilation system having several components that are used together to compile and execute source programs. These components are: 1) The Apogee-C compiler. This compiler accepts C source files and compiles them to produce assembly files, which express the compiled program in symbolic machine language form. This compiler includes a preprocessor for the C preprocessing language. This compiler may also include the single or multiprocessing version of the KAP-C or VAST-C preprocessosrs, which are optionally available. When executing, this compiler is itself composed of several UNIX processes. 2) The Apogee-C++ compiler. This compiler accepts C++ source files and compiles them to produce assembly files, which express the compiled program in symbolic machine language form. This compiler includes a preprocessor for the C++ preprocessing language. When executing, this compiler is itself composed of several UNIX processes. If the source files contain template definitions, this compiler may produce instantiationinformation (.ii) files that will be used by a prelinker. 3) The Apogee-FORTRAN compiler. This compiler accepts FORTRAN source files and compiles them to produce assembly files, which express the compiled program in symbolic machine language form. This compiler may also include the single or multiprocessing version of the KAP-F or VAST-F preprocessors, which are optionally available. When executing, this compiler is itself composed of several UNIX processes. Apogee User's Manual Page 15 Apogee Software, Inc. 4) The UNIX assembler. This assembler takes assembly files and assembles them to produce relocatable object files. Object files express the compiled program in a binary machine language form. 5) The C++ templates prelinker. There are situations in C++ programs using templates where the absence of certain compiler generated functions (template instantiations) is only detectable immediately prior to the final linking phase. The prelinker program determines whether there are any such missing template instantiations, and reinvokes the compiler on one or more source files, using information provided by the compiler via .ii files (see "Control-Variable tmpl -- Template Instantiation Mode in C++" on page 87). This prelinker is called just before the final link phase on all object files. 6) The UNIX link editor. The link editor takes one or more relocatable object files and binds them together to create a single object file. The result can be either a relocatable object file, which is suitable for input to a subsequent invocation of the link editor, or an executable object file, which is ready to be executed by UNIX. 7) The patch program. There are situations in C++ programs where certain pieces of code (constructors for static variables) need to be run before the main program starts, or after the main program ends. Under Solaris 1 (SunOS), a special program called 'patch' runs after the link editor, and modifies the final executable file to create the necessary links to run such code. The Solaris 2 compiler does not require this program because the assembler and linker provide the same facility in other ways. Normally one or more source files comprise a program. These source files can be written in C, C++, FORTRAN 77/90, or in assembly language. In addition, each source file can contain one or more routines. The compilation system can be used in a number of different ways to prepare a program such as this for execution, for example: case 1) case 2) All of the source files can be passed to the system with one command line invocation, with the result being a single executable object file. The source files can be passed to the system individually to produce one relocatable object file per source file. A final invocation of the system can produce an executable object file from the relocatable object files. Some source files and some relocatable object files can be passed to the system, with the result being a single executable object file. C, C++, and FORTRAN 77/90 source files can be given to the system one at a time or in groups, with an option which indicates that processing should stop after production of assembly files. Later invocations of the system can carry the processing through to the production of the executable object file, or can stop after production of relocatable object files. case 3) case 4) Page 16 Apogee User's Manual Chapter 1: Introduction to the Apogee Compilers The Compilation System case 5) The C preprocessor is normally applied to C source files. However, it can also be applied to FORTRAN source files. This preprocessing can be followed by normal compilation, or the system can be told to stop after writing the preprocessed output to a file. Later invocations of the system can produce an executable object file, or stop at some one of the other intermediate stages. The KAP-C or VAST-C optimizing preprocessor may or may not be applied to each C source file prior to compilation. The KAP-F or VAST-F optimizing preprocessor may or may not be applied to each FORTRAN source file prior to compilation. This preprocessing will usually be followed by normal compilation, but the system can be told to stop after writing the preprocessed output to a file. The link editor can be invoked repeatedly, binding in more relocatable object files with each invocation. For each step except the last, the output is a relocatable object file. For the last step, the output is an executable object file. case 6) case 7) The best way to use the compilation system depends on your situation. For example, case 1) above is the simplest approach when you have a set of source files and you only want to execute the program (this case is also the default behavior of the system). Case 2) above is often used during program development, when only modified files need to be recompiled. One part of each compiler, called the driver, controls the actions of the system. The driver is invoked by the command line that starts the system, and when invoked runs as a single UNIX process. The driver looks at the set of options passed to it, as well as the suffix of each file name it is passed. These files and options direct the behavior of the driver as it invokes and/or directs the behavior of the remainder of the system. The components of the compilation system communicate with each other by writing and reading temporary files. For example, when the KAP-F preprocessor is run, the result of KAP is placed in a temporary FORTRAN source file, and this temporary file is then processed by the compiler. By default, all temporary files are placed in the directory "/tmp". A directory other than "/tmp" can be used by setting the environment variable TMPDIR to the desired directory path-name. Chapter 2 contains a detailed discussion of the command line used to invoke the compilation system. The following examples are given as an introduction to that discussion. For the first example, suppose the driver is passed a mixture of FORTRAN 77/90, C, C++ and assembly source files with no command line options (thus invoking the default behavior of the driver). Under these circumstances, case 1) above applies. Specifically the driver will: · · · pass each of the given FORTRAN 90 source files to the FORTRAN 90 compiler for compilation, pass each of the given FORTRAN 77 source files to the FORTRAN 77 compiler for compilation, pass each of the given C source files to the C compiler for C preprocessing and compilation, Apogee User's Manual Page 17 Apogee Software, Inc. · · · · pass each of the given C++ source files to the C++ compiler for C++ preprocessing and compilation, pass all of the resultant assembly files and all of the given assembly source files to the assembler for assembly, and pass all of the resultant relocatable object files to the link editor to produce a single combined executable object file. invoke a patch program for C++ executables to take care of constructor calls before the main program begins. A point worth noting for this example is that all drivers will pass FORTRAN files to the FORTRAN compiler, C files to the C compiler, C++ files to the C++ compiler, and assembly files to the assembler. As a second example, suppose the driver is passed a mixture of FORTRAN, C and assembly source files, but is also given the -Xvast command line option (which directs it to use the appropriate VAST preprocessor). Under these circumstances, the driver will: · pass each of the given FORTRAN source files successively through the VAST-F preprocessor for optimization preprocessing and then through the FORTRAN compiler for compilation, pass each of the given C source files successively through the C compiler for C preprocessing, through the VAST-C preprocessor for optimization preprocessing, and then through the C compiler for compilation, pass all of the resultant assembly files and all of the given assembly source files to the assembler for assembly, and pass all of the resultant relocatable object files to the link editor to produce a single combined executable object file. invoke a patch program for C++ executables to take care of constructor calls before the main program begins. · · · · As a third example, suppose the driver is passed a single FORTRAN source file and is also given the -c command line option. (The -c option directs the driver to stop prior to calling the link editor.) Under these circumstances, the first half of case 2) above applies. Specifically the driver will: · · pass the given FORTRAN source file to the FORTRAN compiler for compilation, and then pass the resultant assembly file to the assembler for assembly, leaving the resultant relocatable object file in the current directory. This third example is the case commonly used in make files to cause recompilation when a source file or any of its antecedents has changed. As a fourth example, suppose the driver is passed a set of relocatable object files and no options. Under these circumstances, the second half of case 2) above applies. Specifically the driver will pass the given files to the link editor, which will bind them together to produce a single executable object file. Page 18 Apogee User's Manual Chapter 1: Introduction to the Apogee Compilers Optimization This fourth example is the case commonly used in make files to create the executable object file when any of the relocatable object files have changed. There is a point worth noting regarding the first and fourth examples. In UNIX, you must explicitly pass to the link editor the names of subroutine libraries containing any intrinsicroutines needed by the compiled program. In the default case, this information does not come from the object files being linked, but from the particular driver you have invoked. The C driver passes by default just the libraries needed by C programs, while the C++ driver passes by default the libraries needed by C++ programs and the libraries needed by C programs. Similarly, the FORTRAN drivers pass by default the libraries needed by FORTRAN programs and the libraries needed by C programs. Thus if FORTRAN programs are among the relocatable object files being linked, you must either invoke the FORTRAN driver to do the linking, or you must augment the list of libraries passed to the link editor by using the -l option. Optimization The distinguishing characteristic of the Apogee compilers is their ability to aggressively optimize programs. This characteristic has the following consequences: · Programs execute faster. The amount of execution time saved varies strongly with the particular source program and with the way it is written, but some time is saved for almost all programs and a very significant amount of time is saved for some programs. Since optimization requires more time and more memory during compilation, applying it to a program is not always an effective use of computer resources. For example, during program development a program may only be executed for a short time each time it is compiled. In this case, optimization may require more compilation time than it saves in program execution time. Because of this, the Apogee compilers permit you to control the extent of the optimization in a number of ways. The optimization applied by the compilers depends on certain programming restrictions that are part of the standard language definition for each language. If a source program violates these restrictions, optimization applied to the source program sometimes produces an object program that fails. (This failure may take the form of different results from the program, or it may be something more dramatic, such as a program abort.) Because of this requirement: 1) the compilers permit you to control the nature of the optimization in a number of ways, and 2) you may find it desirable to modify the program to conform to the standard language definition in order to be able to apply optimization to it. · An optimized object program differs from an unoptimized object program in a number of ways, for example: 1) The basic control flow of the program (i.e., its tests, branches, loops, and so forth) can be changed. · · Apogee User's Manual Page 19 Apogee Software, Inc. 2) Even where the control flow is not changed, computations will probably be done in a quite different order than the one expressed in the source code. 3) The registers of the processor are used to hold quantities across longer sections of the program. (For example, a "variable" of the source program may never appear in memory at all.) Because of these facts, any interaction you have with the optimized program at the assembly code level will become harder. One of these interactions is the use of the debugger. Debugging optimized code is very difficult because of the changes to the program. The following is a list of some of the optimizations that are applied by the Apogee compilers: · Common Subexpression Elimination. If a value that has already been computed is unnecessarily recomputed, the first result can be held in a processor register and reused instead of being recomputed. Sometimes the value is a repeated expression in the source code. Sometimes it is below the level of the source code. For example, if there are two FORTRAN references to a real array A(I), with no intervening assignment to I, the value 4*I needed to address the array in memory does not have to be recomputed. Constant Folding and Constant Propagation. Expressions involving constant operands can be computed during compilation. Assignment of constant values to variables can be propagated forward to the next use of the variable. User function inlining. Calls to small user functions can be replaced by the code they call. This saves the overhead of making a function call and creates additional opportunities for optimization by providing the optimizer with greater scope on which to work. Code Motion. Values computed within a loop that are the same each time through the loop can be computed once, either before or after the loop, as appropriate. The code that computes such values can be moved a significant distance, for example, completely outside of a large nested loop. Dead Code Elimination. Code that will never be executed or whose results will never be used can be eliminated. This can be individual computations, or whole sections of code. Such code can result from poor programming, but more commonly results from the fact that other optimizations have removed all uses of a value. Strength Reduction. Within loops, multiplication operations involving values that change linearly with the loop iterations can often be replaced with suitable addition operations. Induction Variable Elimination. Loop control variables that are not needed can be eliminated. This situation is common in loops after strength reduction has been applied. Control Flow Improvements. Several kinds of improvements can be applied to the control flow of the program. For example, unconditional transfers to unconditional transfer instructions can be eliminated. · · · · · · · Page 20 Apogee User's Manual